version: "1.0.1" 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.5.0

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

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

1. Validate every answer per reference/answer-validation.md.
2. secret: true answers: value → harness store per the cheat-sheet; MOD.md gets only

{store, key}. Never write or repeat the value.

1. 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.