# Kiro Crew Documentation

**This directory is the contributor and architecture documentation.** It is not
shipped to users: the docs that ship inside the Python package live in
[`../src/kiro_crew/docs/`](../src/kiro_crew/docs/README.md), and frontend-specific
docs live in [`../website/docs/`](../website/docs/README.md).

New here? Start with [guides/install.md](guides/install.md), then
[architecture/overview.md](architecture/overview.md).

## Where things live

| Directory | What it is for |
|---|---|
| [guides/](guides/README.md) | Install, run, and operate Kiro Crew. Task-oriented. |
| [architecture/](architecture/README.md) | How the system fits together, one doc per cross-cutting concern. |
| [feature-map/](feature-map/README.md) | Every dashboard feature, mapped to the nav path, page, and handler that own it. A lookup index. |
| [build/](build/README.md) | Packaging, signing, and releasing. |
| [ci/](ci/README.md) | Everything that gates a pull request. |
| [app-kit/](app-kit/README.md) | Building apps that run inside Kiro Crew (third-party developer docs). |
| [system-specs/](system-specs/README.md) | Change-control contracts. The doc a code change MUST update in the same commit. |
| [request-for-change/](request-for-change/README.md) | Proposals and decision records for large or contested changes, plus the dated implementation plans that execute them under [plans/](request-for-change/plans/README.md). |
| [decisions/](decisions/README.md) | The append-only record of product and design decisions a person on the team made. One immutable file per decision; grep it before changing a user-facing label, placement or behaviour. |
| [blog/](blog/README.md) | Essays on direction and design philosophy. Arguments, not contracts. |
| [reference/](reference/README.md) | A mirror of upstream kiro-cli documentation, with named local exceptions. |
| [task-specs/](task-specs/README.md) | Archived per-task specs. Not current context. |
| `../.kiro/specs/` (repo root) | Archived feature specs from the repo's own Spec Builder runs. Each file's `Status` marker says what it is; not current context. Spec Builder writes live specs to `<project>/.kiro/specs/` in the user's project, not here. |

## The rule for changing docs

A code change that alters documented behavior MUST update the docs **in the same
commit**. Concretely:

1. **Find the one owning doc.** Every subsystem has exactly one. The routing table
   in [`../AGENTS.md`](../AGENTS.md) maps subsystem to doc; `system-specs/modules/`
   is the usual home.
2. **Update it, do not add a second doc.** Prefer editing the existing doc over
   creating a new one. Two docs on one subject diverge, and then a reader cannot
   tell which is true.
3. **Update every index that points at it** when you add, move, rename, or delete a
   doc: this file, the directory's own `README.md`, and any doc that links to it.
4. **Do not write a changelog into a doc.** No `Last Updated:` line, no
   "previously/used to/we now" narration, no PR numbers or commit SHAs. Git records
   history; the doc states current behavior in present tense.
5. **Run the gate:** `./scripts/docs-lint.sh`. It fails on a broken internal link, a
   doc no index reaches, a directory with no index, a code comment citing a doc that
   does not exist, a renamed doc whose filename is hardcoded in code, a git
   conflict marker left at the start of a line, and a section link (`#anchor`) in
   this tree that no heading or `<a id>` produces. It walks four trees: this one,
   the packaged [`../src/kiro_crew/docs/`](../src/kiro_crew/docs/README.md),
   [`../website/docs/`](../website/docs/README.md), and the markdown a builtin app
   ships under `src/kiro_crew/apps/builtins/`. That fourth tree is link-checked and
   fact-checked but exempt from the index rules, because an app's README, agent
   briefs and `SKILL.md` files are curated by its `app.json` rather than by a
   documentation index.

Two constraints that are easy to miss:

- **`src/kiro_crew/docs/` filenames are an API.** That tree is packaged, is read at
  runtime by `tips.py` (gated by `tips_allowlist.py`), and specific filenames are
  hardcoded in dashboard Settings panels. Renaming a file there is a code change.
  The tree is also flat by design: `setup.cfg`'s `package_data` glob does not
  recurse, so a subdirectory would ship in the sdist but not the wheel.
- **User-facing docs belong in that packaged tree, not here.** An internal
  engineering note that lands in it ships to every `pip install`.