first commit

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

@@ -0,0 +1,69 @@
+# `detect`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Reports what is already present at the target skills directory. The host
+calls `detect(ctx)` before prompts run; the result feeds into the user's
+decision about whether to proceed, `--force`, or supply `--only` /
+`--exclude` to limit the install. Detect is read-only: it only inspects
+`ctx.fs` and never mutates state.
+
+## Features
+
+- Reports `alreadyInstalled: boolean` based on the target directory's
+  presence — `false` means a fresh install path.
+- Lists existing skill directories as `conflicts` (excluding
+  `index.json`) so the host UI can show what would be touched.
+- Defaults to scanning `.suaveplan/skills` relative to `ctx.cwd`; the
+  optional second argument lets callers pre-supply a target dir from
+  partial answers.
+- Tolerant of degenerate states — when `listDir` throws (e.g. the target
+  is a file masquerading as a dir), returns `conflicts: []` rather than
+  propagating the error.
+
+## Basic Example
+
+```ts
+import { detect } from "@suaveplan/install-agent-skills";
+
+const result = await detect(ctx);
+if (result.alreadyInstalled) {
+    console.warn("Skills already installed; use --force to overwrite");
+}
+```
+
+## Advanced Example
+
+```ts
+import { detect } from "@suaveplan/install-agent-skills";
+
+const result = await detect(ctx, { targetDir: "/srv/agent/skills" });
+if (result.alreadyInstalled && (result.conflicts?.length ?? 0) > 0) {
+    console.log("Existing skills:");
+    for (const id of result.conflicts ?? []) {
+        console.log(`  - ${id}`);
+    }
+    console.log(
+        `Run again with --only ${result.conflicts?.join(",")} to refresh just those`
+    );
+}
+```
+
+## API Reference
+
+- `detect(ctx, answers?): Promise<DetectResult>` — `answers` may be
+  partial; only `targetDir` is consulted at this stage.
+- Return shape — `{ alreadyInstalled, conflicts?, notes? }` from the
+  host's `DetectResult` type.
+
+## Implementation Notes
+
+Detect runs _before_ prompts so it can't access fully-validated answers;
+the partial `answers` parameter lets the bin pass through whatever the
+user already supplied (e.g. via `--answers <file>`). Reading the
+target's directory listing instead of stating each known skill's
+manifest is cheaper and gives the user a holistic view — including
+unrelated skills that were dropped into the directory by hand.