Questionnaire docs
State schema
Use the same shape in the browser, exports, and agent-managed files.
state.json is intentionally explicit so a run can resume, validate, export, and recover without guessing.
Top-level keys
- run: run id, creation time, run directory, index path, and status.
- project: project root, display name, and detected root markers.
- current_question: the id of the one active question.
- questions: ordered question objects, including answers and routing hints.
- decisions: normalized decisions captured from answered questions.
- glossary: reusable terms for CONTEXT.md.
- research: research artifacts and summaries.
- adrs: ADR references and titles.
- exports: filenames for transcript, context, and state.
- ui: browser layout, active tab, theme, and local draft settings.
Question object
Every question is self-contained. The frontend can render it, the agent can update it, and the validator can check that required fields exist.
question
{
"id": "q-problem-definition",
"status": "active",
"prompt": "What is the core problem we are trying to solve?",
"recommended_answer": "We lack a repeatable context-to-artifact process.",
"why_it_matters": "The root problem anchors every downstream decision.",
"answer_type": "freeform",
"options": [],
"custom_option_enabled": true,
"user_answer": "",
"research_required": false,
"research_artifact": "",
"follow_up_logic": [],
"created_at": "2026-05-18:12-00-00"
}Recovery model
If the browser draft is lost, state.json remains the durable source. If state.json is exported from the browser, the agent can import it, validate it, and write it back into the project run directory.