ai-context-docs

You write the 8 files under <target>/docs/agents/. The inspector digest is your map; read actual source files through it when a doc needs depth (domain rules, payload examples). Everything you write describes what is implemented — nothing prescriptive, nothing aspirational.

Inputs (injected by the router)

• target — absolute repo path
• digest — full inspector digest
• include_files — subset of the 8 file ids to generate; skip the rest with status disabled
• adopt — boolean; governs handling of not-owned files

Ownership contract

Same as the whole pipeline: absent → create; owned (banner present) → regenerate + byte-diff; not-owned → skip with skipped (not owned) unless adopt=true, then fold hand-written facts in and overwrite with status adopted.

Hard exclusions

• Never read or cite .spec/, .specs/, spec/ — this tree documents the code, not the plan.
• Never read .env; env var names come from the digest.
• Existing generated docs are a byte-diff target only — never recycle their prose as evidence. Regenerate from code every run.

Grounding rules

• Every claim about language, framework, pattern, rule, or contract cites something you or the inspector actually read (file path, class name, config key, dependency version).
• Never invent content. A section without evidence → the N/A shape (below), with the evidence of absence cited.
• Realistic payload examples come from fixtures, tests, or factories — never "string"/"value" placeholders.

Style — caveman docs

Dense from the first draft. Bullets over paragraphs, tables over lists, no meta-prose, no hedging, active imperative voice, numbers as digits, code blocks verbatim. Heading states the topic; body starts with facts.

Common shape — every file

# <Canonical Title>

<!-- Generated by /ai-context. Manual edits are overwritten on re-run. -->

## AS IS — Current state

### <subsection>
<bullets / tables / fenced code>

## Related documents

- [`<peer>.md`](<peer>.md) — <one-line scope>
- [`<peer>.md`](<peer>.md) — <one-line scope>

• Banner on line 3, after # Title and a blank line.
• ## AS IS — Current state always present.
• ## Related documents always last, ≥2 peer links with one-line scope each.
• Body ≥120 bytes. Never an empty file.

N/A shape (evidence-based, not classification-based)

When the repo has no evidence for a doc's subject (e.g. no persistence, no public API):

## AS IS — Current state

### Not applicable in this repository

<One paragraph citing the evidence of absence: "no migrations directory,
no ORM models, no schema files, no database driver in the manifest.">

Keep the banner and Related documents footer. Status reports as skipped (N/A) even though the file is written — the tree stays homogeneous at 8 files.

Per-file spec

project_overview.md — first line # Project Overview

AS IS subsections, in order:

• ### Purpose — 1 sentence, active voice, what the system does.
• ### Business problem — bullets: what breaks without it. Derive from README + observed behavior; no evidence → fold into Purpose and omit.
• ### Consumers and integrations — table System | Role, from entrypoints + external clients observed.
• ### Macro flow — numbered steps from entry (request/event/command) to terminal state (response/side-effect/persisted artifact).
• ### Out of scope — bullets, only when evidence supports a boundary (e.g. README states it, or an integration is explicitly delegated).

architecture.md — first line # Architecture

• ### Style — 1 sentence naming what you observe (MVC, layered, hexagonal, plugin tree, monorepo). Only labels the layout supports.
• ### Directory layout — fenced tree with inline comments per folder.
• ### Layer responsibilities — table Layer | Owns | Does NOT own.
• ### External integration points — table System | Client/config | Notes; only when integrations exist.
• When digest.async.present: ≥1 ### Macro flow: <name> with an ASCII flow diagram in a fence (plain boxes/arrows — no Mermaid, no PlantUML).

tech_stack.md — first line # Tech Stack

• ### Runtime and language — table; MUST contain these 2 rows even when the value is not found:
  • - **Language**: <name> <version>
  • - **Framework**: <name> <version> (no framework → No primary framework)
• ### Tests — table: runner, assertion lib, mock lib, coverage tool, versions.
• ### External integrations — table System | Client wiring; only when present.

coding_guidelines.md — first line # Coding Guidelines

Under AS IS, ≥3 numbered pattern headings:

### 1. <pattern name>
### 2. <pattern name>
### 3. <pattern name>

Each: 1-line rationale + enforcement citation when it exists ("enforced by phpstan.neon level 8", "ESLint no-unused-vars"). No enforcement → no citation. Pull from lint configs, .editorconfig, pre-commit hooks, and patterns you verify in ≥2 source files. Never invent a pattern.

domain_rules.md — first line # Domain Rules

• ### Overview — bullets: the concepts the domain encodes.
• One ### <rule name> per significant rule: current behavior + implementing file/class. Use digest.domain_signals as the reading map; read those files.
• Routing/decision matrices in code → reproduce as a table (input axes × outcome) + 1 line on how to extend.

api_contracts.md — first line # API Contracts

• ### HTTP endpoints — per endpoint family: method, path, auth, request shape, response shape, error cases. Table for the index, fences for payloads.
• ≥1 realistic ```json payload example per endpoint family, sourced from tests/fixtures.
• When digest.async.present: ### Message formats — queue/topic names, message schema, retry/DLQ behavior as implemented.
• No API surface → N/A shape citing evidence of absence.

data_model.md — first line # Data Model

• When digest.persistence.present: ### Entities — per entity: attributes, types, relationships, invariants (from migrations/models/schema). ### Storage — engine, schema location, migration tool.
• Cache/in-memory state → ### Cache subsection regardless of persistence.
• No persistence → N/A shape citing evidence of absence.

dependencies.md — first line # Dependencies

• ### External services — table Service | Purpose.
• ### Internal libraries — table Package | Role; only private/first-party packages.
• ### Shared infrastructure — queues, caches, observability the code depends on.
• Omit a subsection only when the repo has 0 items in it.

Update detection (per artifact)

1. Generate canonical content in memory from digest + source reads.
2. Read on-disk bytes — absent → write, status created.
3. Byte-identical → unchanged, do not write.
4. Different → write, status updated (or adopted).

Convergence note: structure (headings, tables, fences, citations) converges across runs; narrative wording may not — LLM prose is not byte-deterministic. Do not chase byte-stability by copying old generated prose; regenerate from code.

Self-checks (run after all files, fix via Edit, re-run until green)

Per generated file:

test -f <target>/docs/agents/<file>
[ "$(wc -c < <target>/docs/agents/<file>)" -ge 120 ]
head -1 <target>/docs/agents/<file>          # must equal canonical first line
grep -Fq '<!-- Generated by /ai-context.' <target>/docs/agents/<file>
grep -Fq '## AS IS — Current state' <target>/docs/agents/<file>
grep -q '^## Related documents' <target>/docs/agents/<file>
[ "$(grep -Ec '^- \[.*\]\(.*\.md\)' <target>/docs/agents/<file>)" -ge 2 ]

File-specific:

grep -q '^- \*\*Language\*\*:' <target>/docs/agents/tech_stack.md
grep -q '^- \*\*Framework\*\*:' <target>/docs/agents/tech_stack.md
[ "$(grep -c '^### [0-9]' <target>/docs/agents/coding_guidelines.md)" -ge 3 ]
# api_contracts.md — only when API surface exists:
[ "$(grep -c '^```json' <target>/docs/agents/api_contracts.md)" -ge 1 ]
# architecture.md — only when async signals present:
[ "$(grep -c '^```' <target>/docs/agents/architecture.md)" -ge 2 ]

Skip checks for skipped (not owned) / disabled artifacts.

Output (summary only — never inline file content)

• Per artifact: absolute path + status (created / updated / unchanged / adopted / skipped (N/A) / skipped (not owned) / disabled).
• For each skipped (N/A): the one-paragraph evidence-of-absence written into the file.
• Self-checks: pass/fail; Red → Green transitions for initial failures.