first commit

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

@@ -0,0 +1,75 @@
+# `prompts`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+## Purpose
+
+Builds the Zod-compatible `PromptSchema<AgentSkillsAnswers>` consumed by
+the host's prompt-validation stage. The schema validates `targetDir`,
+`only`, `exclude`, and `overwrite` answer shapes, defaulting `targetDir`
+to `.suaveplan/skills` when absent. Exposed as a builder function so
+plugin tests can re-derive the schema with different defaults if needed.
+
+## Features
+
+- `targetDir`: required string, default `.suaveplan/skills`.
+- `only`/`exclude`: optional `string[]` filters applied by the plan
+  stage.
+- `overwrite`: optional boolean — `true` flips per-write conflict policy
+  from `skip-if-exists` to `overwrite`.
+- Zod schema is exported separately so tests can validate answers
+  directly without going through the host pipeline.
+
+## Basic Example
+
+```ts
+import { buildPromptSchema } from "@suaveplan/install-agent-skills";
+
+const schema = buildPromptSchema();
+const result = schema.safeParse({ targetDir: ".suaveplan/skills" });
+if (result.success) {
+    console.log(result.data.targetDir);
+}
+```
+
+## Advanced Example
+
+```ts
+import { AnswersSchema, buildPromptSchema } from "@suaveplan/install-agent-skills";
+
+const explicit = AnswersSchema.parse({
+    targetDir: "/srv/agent/skills",
+    only: ["crypto", "events"],
+    overwrite: true,
+});
+
+// Or use the builder when threading through the installer host:
+import { Host } from "@suaveplan/installer";
+const host = new Host(ctx, fs);
+await host.run(myPlugin, {
+    answers: AnswersSchema.parse({ targetDir: "/.suaveplan/skills" }),
+});
+```
+
+## API Reference
+
+- `buildPromptSchema(): PromptSchema<AgentSkillsAnswers>` — function
+  that returns the Zod schema cast to the host's structural prompt
+  contract.
+- `AnswersSchema` — the underlying Zod schema for direct use.
+
+## Implementation Notes
+
+The cast to `PromptSchema<AgentSkillsAnswers>` is a structural narrowing
+— Zod's `safeParse` and `parse` already match the contract, but Zod
+returns a richer type that the host doesn't need to know about.
+Defaulting `targetDir` inside the schema means callers who supply an
+empty answer object still get a usable plan; the plan stage's defensive
+`TARGET_DIR_INVALID` guard covers the unlikely path where someone
+supplies an empty string explicitly. Both `only` and `exclude` are
+optional arrays — when omitted they're treated as "no filter" by the
+plan stage. The `overwrite` boolean flips per-write conflict policy
+without affecting the index patch (which always merges); this matches
+the spec's idempotent re-install requirement and lets users force a
+content refresh without churning the index entry shape.