first commit

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

@@ -0,0 +1,63 @@
+# `apply`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+The plugin-side apply hook. The installer host owns the actual
+transactional materialisation (staged-tmp + atomic-rename + journal-based
+rollback); this hook's only job is to inspect the planned ops and return
+an `AgentSkillsHandle` summarising what was installed so `postInstall`
+can render a meaningful summary line.
+
+## Features
+
+- Counts `write` ops to derive the `installed` count.
+- Echoes back the resolved `targetDir` so `postInstall` doesn't need to
+  re-derive it from ops or answers.
+- Pure pass-through — no fs I/O, no side effects.
+
+## Basic Example
+
+```ts
+import { apply } from "@suaveplan/install-agent-skills";
+
+const handle = await apply(ops, ctx, ".suaveplan/skills");
+console.log(`installed: ${handle.installed}`);
+```
+
+## Advanced Example
+
+```ts
+import { apply } from "@suaveplan/install-agent-skills";
+import type { FileOp, InstallerContext } from "@suaveplan/installer";
+
+async function dryRunSummary(
+    ops: ReadonlyArray<FileOp>,
+    ctx: InstallerContext,
+    targetDir: string
+): Promise<string> {
+    const handle = await apply(ops, ctx, targetDir);
+    return `dry-run plan: ${handle.installed} files would land in ${handle.targetDir}`;
+}
+```
+
+## API Reference
+
+- `apply(ops, ctx, targetDir): Promise<AgentSkillsHandle>` — pure
+  function returning `{ installed, targetDir }`.
+
+## Implementation Notes
+
+Apply is intentionally trivial because the installer host enforces
+transactional semantics via its own `applyOps` — every `FileOp` returned
+from `plan` is materialised through staged-tmp + atomic-rename with a
+journal-based rollback, so plugin-side apply does not need to perform
+any I/O. Plugin authors who need to perform side effects beyond what
+`FileOp` can express should do so in `postInstall` (where the host has
+already committed the apply transaction) rather than reaching into
+apply directly — that keeps
+rollback-on-failure semantics intact. The `targetDir` argument is
+threaded through from `plugin.ts` which extracts it from the index
+patch op so we don't lose it across the plan/apply boundary.