Skip to content

[T-121] Docs refresh to as-built: architecture, API, config reference, CHANGELOG, ADR updates #222

Open

Description

@CodewithJha

Task T-121 · Milestone M11 — Release 1.0 · Size M · Priority P0 · Epic #11

Implements NFR-MNT-001

Branch docs/t-121-docs-refresh-to-as-built — one task = one branch = one PR (doc 32 §6)

Summary

Update every design doc to match the implementation (signatures, config keys from generated reference, endpoints from OpenAPI), close or supersede ADRs whose decisions changed, write CHANGELOG Unreleased entries for 1.0, update README quick-start and screenshots.

Context / motivation

Docs are part of the product (AGENTS.md); drift is a defect.

Scope

In scope

  • Traceability matrix (doc 28) updated with real test ids and issue links.

Implementation guidance

  • Work doc group by doc group, one PR each (architecture 04–05, data/API 11–12, UX 13, ops 17/20/29/30, evaluation 19, process 32–34): diff each doc against the code (signatures, config from the generated reference T-003c, endpoints from api/openapi.json, routes from router.tsx) and update text and diagrams.
  • ADRs: changed decisions get a new ADR that supersedes the old one (accepted ADRs are not rewritten; mark Superseded by).
  • Traceability (doc 28): fill in real test node ids and GitHub issue links per requirement; scripts/check_traceability.py verifies each FR/NFR has at least one test and one closed issue.
  • CHANGELOG: consolidate Unreleased into the 1.0.0 section (Keep a Changelog categories).
  • Standards: respect the layering contracts (doc 16 §2) and conventions in doc 34; no hard-coded tunables — thresholds/defaults come from typed settings (doc 27); no magic numbers (ruff PLR2004); public APIs typed (mypy strict) and documented.

Acceptance criteria

  • docs.yml green; no stale signature/config mismatches (scripted check where possible).
  • Traceability checker green.
  • Superseded ADRs correctly linked.
  • Tests listed below added and green in CI; coverage of new code meets the gate in doc 18 §3.
  • Docs, config reference and CHANGELOG Unreleased updated where behaviour, keys or interfaces changed.
  • Definition of Done (doc 32 §3) satisfied.

Tests required

  • docs.yml.

Dependencies

Blocked by: #208 (T-105b), #210 (T-120a), #188 (T-114)

Blocks: #223 (T-122)

Parallelization notes

Files / paths owned by this task — avoid editing other paths; shared files (pyproject.toml entry points, cli/main.py, api/routers/__init__.py, router.tsx, docker/compose.yaml, ci.yml) are append-only:

  • docs/**
  • README.md
  • CHANGELOG.md

Can be split per doc among agents.

Definition of Done

Per doc 32 §3 and AGENTS.md §5: lint, format, mypy strict and import-linter green; tests added and passing; docs updated; PR template completed with Closes #<this issue>; Conventional Commit messages referencing T-121 (doc 16 §6); commits authored only by the repository owner identity (AGENTS.md §4); CI green; reviewer checklist (doc 32 §5.1) satisfied.

References

Design docs: doc 28 §1 · doc 28 §3 · doc 33 §3 · AGENTS.md · doc 15 §2

Requirements: NFR-MNT-001 (traceability: doc 28)

Metadata

Metadata

Assignees

No one assigned

    Labels

    area:docsDocumentationmilestone:M11M11 — Release 1.0priority:P0Critical path / blocks otherssize:M1-3 daystaskChild task of a milestone epictype:docsDocumentation work

    Projects

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions