# `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.