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