# Documentation

<!-- AUTO-GENERATED by docs-reindex.mjs (ADR-0030). Reclassify via docs/.diataxis.json, then re-run `/docs-reindex`. Edits here are overwritten. -->

Organized by [Diátaxis](https://diataxis.fr/) — by what you are trying to do.

## 🎓 Tutorials — learning-oriented
_Lessons that take a newcomer by the hand through a first success._

- [Tutorial: <What the reader will accomplish>](tutorials/_TEMPLATE.md) — Goal: the reader succeeds at something for the FIRST TIME.
- [Tutorial: your first business case](tutorials/first-business-case.md) — By the end of this tutorial you will have created a business context on disk, read
- [Tutorial: your first shipped feature](tutorials/first-shipped-feature.md) — This tutorial creates one durable workflow, adds canonical tasks, implements a
- [Tutorial: Your First ContextDevKit Session](tutorials/getting-started.md) — Goal: the reader succeeds at something for the FIRST TIME.

## 🔧 How-to — task-oriented
_Recipes that solve a specific real-world problem for someone who already knows the basics._

- [Customizing ContextDevKit](CUSTOMIZING.md) — The kit works out of the box, but a few tweaks make it fit your project well.
- [How to <accomplish a specific real-world goal>](how-to/_TEMPLATE.md) — Goal: reader completes a specific, real-world task they already know they need.
- [Anatomy of a Business, Operation & Workflow](how-to/anatomy-of-business-operation-workflow.md) — Goal: understand ContextDevKit's durable governance memory in one read — what a **Business**, an **Operation**, and a…
- [Audit and test a change](how-to/audit-and-test.md) — Use audits to collect evidence, then decide explicitly whether any finding should
- [How to choose the right documentation altitude](how-to/authoring-docs.md) — You are adding or updating documentation and need to decide which folder to put
- [How to configure ContextDevKit](how-to/configure-contextkit.md) — Goal: reader makes a specific configuration change safely, by area.
- [How to connect MCP servers](how-to/connect-mcp-servers.md) — You want an external Model Context Protocol server available to the agent in this
- [How to cut a release](how-to/cut-a-release.md) — Goal: maintainer ships a version without tagging on a red gate or double-publishing.
- [How to forge an agent package](how-to/forge-an-agent-package.md) — You need an agent that is **portable** — one that runs outside this kit, against a
- [How to install ContextDevKit and choose a level](how-to/install-and-choose-a-level.md) — Goal: reader installs the kit into a real project and lands on the right level.
- [Record a decision](how-to/record-a-decision.md) — Create an ADR when a material choice needs durable rationale. Deliberation can
- [How to reduce token cost](how-to/reduce-token-cost.md) — Goal: reader applies the economy levers deliberately, highest-effect first.
- [Run a governed business or operation case](how-to/run-a-business-case.md) — Use this guide when a confirmed mutation needs durable Business or Operation memory. Most code changes do not.
- [Run a parallel swarm](how-to/run-a-parallel-swarm.md) — Use parallel agents when ready tasks are independent and the host can execute
- [Run a Workflow v2 package](how-to/run-a-workflow.md) — Use a workflow for real dependencies, waves, multi-session execution, cutover,
- [Start focused work](how-to/start-a-focused-session.md) — Conversation and exploration are read-only. For a mutation:
- [How to troubleshoot an install](how-to/troubleshoot.md) — Goal: reader turns a confusing symptom into a named cause and a command.
- [Configure capability levels](how-to/tune-autonomy-and-level.md) — ContextDevKit 4 has capability levels, not autonomy grades. A level controls
- [How to upgrade and update an install](how-to/upgrade-and-update.md) — Goal: reader updates a real install, understands every branch the updater can
- [Use domain-engineering guidance](how-to/use-domain-engineering.md) — Domain Engineering is an advisory lens. Run:
- [How to use the structural knowledge graph](how-to/use-the-knowledge-graph.md) — You are about to answer a structural question about the codebase — who calls this
- [Use the canonical task board](how-to/use-the-pipeline-board.md) — Choose one workflow or batch scope. All commands require it explicitly:
- [How to work across hosts and bridges](how-to/work-across-hosts-and-bridges.md) — Your team does not all use the same AI coding tool, and you want the same commands, the
- [Workflow file catalog](workflow-engine/file-catalog-guide.md) — Every ContextDevKit 4 workflow has the same authority contract. Profiles and
- [Workflow migration guide](workflow-engine/migration-guide.md) — Workflow v1 is not read by the normal workflow engine. `workflow-plan.json`,
- [Profile and pattern guidance](workflow-engine/profile-guide.md) — Profiles and patterns are optional topology suggestions. They do not change the
- [Workflow guide](workflow-engine/workflow-guide.md) — Use a workflow only when the work has strong dependencies, waves, required

## 📚 Reference — information-oriented
_Dry, accurate technical descriptions — formats, options, APIs. Consulted, not read._

- [Grok Build Integration](GROK.md) — Grok Build is a first-class native ContextDevKit host. It is an operation-owned
- [Documentation languages](LANGUAGES.md) — English is the canonical technical documentation. Localized trees preserve command names, paths, ids, JSON keys, code…
- [Privacy and data posture](PRIVACY.md) — ContextDevKit is local-first. Normal hooks and read-only context commands do not
- [agent-forge — the factory squad](SQUADS/agent-forge.md) — Add `agent-forge` when a project's purpose includes shipping production AI
- [Squad — design-team](SQUADS/design-team.md) — The kit's "make it usable, make it beautiful, make it findable" squad. Five
- [Reference: <Component / API / Config key name>](reference/_TEMPLATE.md) — Goal: complete, accurate lookup — describe the machinery exactly as it is.
- [Reference: Agents](reference/agents.md) — The specialized agents available to route work to. Generated from the agent registry.
- [Reference: Changelog policy](reference/changelog-policy.md) — The rules governing release chronology: which file records what, who cuts a version,
- [Reference: Slash commands](reference/commands.md) — Every slash command the platform ships, grouped by domain. Generated from the command registry.
- [Configuration reference](reference/config.md) — The runtime reads `contextkit/config.json` and layers it over zero-dependency
- [Runtime data posture](reference/data-posture.md) — This table describes the stock 4.0 hot path.
- [Reference: economy configuration and levers](reference/economy.md) — The `economy` block in `contextkit/config.json` governs the token-economy
- [Installed footprint](reference/footprint.md) — AGENTS.md / CLAUDE.md / INSTRUCTIONS.md
- [Glossary](reference/glossary.md) — `backlog`, `working`, `blocked`, `testing`, `done`, and `cancelled` are task status values, not directory names.
- [Governance contract](reference/governance-contract.md) — This page is the public contract of the ContextDevKit 4 governance runtime.
- [Reference: structural knowledge graph](reference/graph.md) — A committed, deterministic projection of the project's structure — files, modules,
- [Reference: Native hosts](reference/hosts.md) — The editor/agent hosts the platform runs on natively. Generated from the shipped host set.
- [Levels reference](reference/levels.md) — `contextkit/config.json` contains an integer `level` from 1 through 7. The level
- [Memory model](reference/memory-model.md) — `contextkit/memory/` stores authored project memory and rebuildable projections.
- [Workflow CLI reference](workflow-engine/cli-reference.md) — Entrypoint:

## 💡 Explanation — understanding-oriented
_Background and rationale — the why behind the decisions._

- [Agent Package Format (APF) v1](AGENT-PACKAGE-FORMAT.md) — agent-packages/
- [Antigravity host integration](ANTIGRAVITY.md) — Antigravity uses `INSTRUCTIONS.md` plus generated assets under `.agents/`.
- [Architecture](ARCHITECTURE.md) — ContextDevKit is a source-distributed, host-neutral **AI Software Engineering Governance Harness**. Its runtime hot p…
- [Codex host integration](CODEX.md) — ContextDevKit projects expose Codex through generated files. Canonical sources
- [Capability levels](LEVELS.md) — Levels select which ContextDevKit capabilities are installed or surfaced. They
- [Squad Pipeline Format v1](SQUAD-PIPELINE-FORMAT.md) — templates/contextkit/squads/<squad>/pipeline.yaml
- [architecture — system-shape and design](architecture/README.md) — How ContextDevKit is structured — the decisions behind the engine's shape, the
- [Explanation: <Topic — the concept, not the task>](explanation/_TEMPLATE.md) — Goal: build a mental model — the WHY, the history, the trade-offs.
- [Business-Driven Development](explanation/business-driven-development.md) — ContextDevKit treats software engineering as work performed in service of durable outcomes — without forcing every co…
- [Host parity without duplicated authority](explanation/contextkit-parity.md) — ContextDevKit supports Claude Code, Codex, Antigravity, and Grok through one
- [Deliberation is advisory](explanation/deliberation-council.md) — ContextDevKit can convene several specialist viewpoints when a decision benefits
- [Work and governance domain model](explanation/domain-model.md) — ContextDevKit 4 keeps authorities small and explicit.
- [Governance and enforcement](explanation/governance-and-enforcement.md) — ContextDevKit 4 separates deterministic quality floors from advisory engineering guidance.
- [Evidence-Driven Loop Engineering](explanation/loop-engineering.md) — ContextDevKit supports software engineering as an iterative evidence loop rather than a one-shot generation event.
- [Quality model](explanation/quality-model.md) — ContextDevKit 4 separates observations from authority. A useful warning may be heuristic; a denial must be determinis…
- [The three economies: token, cost, and autonomy](explanation/the-three-economies.md) — _Why an AI-assisted development platform tracks three separate resource
- [Value and impact](explanation/value-and-impact.md) — ContextDevKit turns project context into durable, inspectable engineering state without making ceremony the permissio…
- [Workflow engine](workflow-engine/README.md) — ContextDevKit 4 workflows are atomic JSON-backed packages for work whose

## 🗂️ Planning & meta

- [Architecture & Roadmap](ROADMAP.md) — An architect's view of where ContextDevKit is, what it learned from the production

## ❓ Unclassified
_Add these to `docs/.diataxis.json` so they land in a Diátaxis mode:_

- [Architecture: <Subsystem or feature name>](architecture/_TEMPLATE.md) — Goal: describe components, boundaries, data flow, and the decisions that