| name | capability-onboard |
| description | Runs a capability's onboarding interview — typed questions, batched, secrets to the harness store — and writes the answers to the user's MOD.md overlay. Use when installing a capability that ships ONBOARDING.md, when the user asks to redo, refresh or revisit their answers, or when bootstrapping the global MOD.md for a new user. Do NOT use to change a behaviour no question covers: an unasked change is a prose statement written by capability-evolve, and a new question is a source change owned by capability-contribute. |
| metadata | {"aos":{"origin":"capability-lifecycle@0.3.7"}} |
capability-onboard
You are the only writer of MOD.md files. Typed answers → frontmatter; prose nuance →
body; secret values → harness store (references only in MOD.md).
Inputs
- Target capability's
ONBOARDING.md: frontmatter = typed questions (id, prompt,
type: string|number|boolean|enum|list|path, optional required/secret/re_ask
booleans); body = the conversational script. Follow the script — don't read questions
off like a form.
- Existing MOD.md for this capability, if any.
- Global root MOD.md — skip questions it already answers; confirm instead of re-asking.
Which questions to ask
| Situation | Ask |
|---|
| First run | all; required must get answers, others may be skipped |
| Re-run | unanswered + every re_ask: true |
--refresh | all, current answer shown as default |
Never delete an answer the user didn't change.
Conduct
Cluster related questions; accept "skip" for non-required. Everything the user says
beyond the typed answer is body-prose nuance ("19:00 — but never over choir practice":
19:00 is the answer, the rest is nuance).
Write
- Validate every answer per reference/answer-validation.md.
secret: true answers: value → harness store per the cheat-sheet; MOD.md gets only
{store, key}. Never write or repeat the value.- Diff gate: show the diff (or the full draft on first run) and get approval.
Empty diff ⇒ no write, no prompt.
Format (normative):
---
capability: <id>
onboarded_version: <CAPABILITY.md version at interview time>
answers:
<question_id>: <typed value>
secrets:
<question_id>: {store: <store>, key: <key>}
---
<prose nuance under headings; omit headings with nothing under them>
Location: <home>/personal/MOD.md for the global bootstrap (this capability's own
interview); <home>/personal/capabilities/<id>/MOD.md otherwise. Never re-serialize unchanged content — edit the
file, don't regenerate it (unchanged answers stay byte-identical).
Report
Answered / skipped / unchanged; secret store+key names only; the applied diff on re-runs.
If part of an install, hand back to the installer.
