first commit

docs/devtools/tooling/install-agent-skills/src/post-install/post-install.md

@@ -0,0 +1,70 @@
+# `post-install`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Prints a short summary line and a next-step hint after the host's apply
+stage commits. Uses `ctx.cli.write` so the testing harness's `ScriptCli`
+captures the output for assertions, and so production runs can be piped
+through any compatible `InstallerCli` writer (e.g. one that wraps a
+structured logger).
+
+## Features
+
+- One summary line — `installed N skills to <dir>`.
+- One follow-up hint pointing at `--only` / `--exclude` for refinement.
+- No fs I/O, no side effects beyond `cli.write` calls.
+- Honours `ctx.signal` via the host's pre-invocation abort guard
+  (`runPostInstall`).
+
+## Basic Example
+
+```ts
+import { postInstall } from "@suaveplan/install-agent-skills";
+
+await postInstall(
+    { installed: 3, targetDir: ".suaveplan/skills" },
+    ctx
+);
+// stdout: installed 3 skills to .suaveplan/skills
+//         Tip: commit the new directory and re-run with --only / --exclude to refine.
+```
+
+## Advanced Example
+
+```ts
+import { postInstall } from "@suaveplan/install-agent-skills";
+
+const lines: string[] = [];
+const captureCtx = {
+    ...ctx,
+    cli: { ...ctx.cli, write: (line: string) => lines.push(line) },
+};
+await postInstall(
+    { installed: 5, targetDir: "/srv/agent/skills" },
+    captureCtx
+);
+console.log(`captured ${lines.length} lines`);
+```
+
+## API Reference
+
+- `postInstall(handle: AgentSkillsHandle, ctx: InstallerContext): Promise<void>`
+- Side effects: two `ctx.cli.write` calls.
+
+## Implementation Notes
+
+PostInstall is intentionally minimal — anything elaborate (e.g.
+generating a summary file, registering completions, sending telemetry)
+should live in a dedicated post-install helper composed at the bin
+layer rather than baked into the plugin. Keeping the message in stdout
+(via `cli.write`) instead of `logger.info` is deliberate: the bin's
+default cli writes to `process.stdout` so the message is visible by
+default, even when the logger is configured for higher verbosity
+thresholds. The host's `runPostInstall` already wraps this call in an
+OpenTelemetry span, so spinning up a per-call span here would
+double-instrument the same boundary. Plugins that need richer post-run
+behaviour should compose this function rather than replace it; the
+small surface keeps that composable in tests and embedders.