docs: brownfield documentation set + CLAUDE.md + README badges#12
Merged
Conversation
Comprehensive per-topic brownfield documentation for future
developers and AI coding agents picking the project up cold.
Twelve numbered files under docs/ + an ADR + CLAUDE.md +
for-the-badge styled README badges. No source changes.
What landed:
* docs/00-project-overview.md — what / who / target users / status
/ production-ready vs experimental
* docs/01-local-setup.md — prerequisites, install, run, test,
required services, common issues, env vars
* docs/02-architecture.md — quick-scan layers, data flow, storage,
external systems, tradeoffs, what
this architecture is NOT
* docs/03-code-map.md — per-folder + per-file purpose with
approximate LOC and related files
* docs/04-main-flows.md — entry points + key files + failure
modes for: auth, session lifecycle,
HITL, background jobs, ingestion,
deployment, error handling
* docs/05-configuration.md — env vars, config layers, per-skill
config, feature toggles, secrets,
safe defaults, validators
* docs/06-data-model.md — backends, entities, relationships,
migrations, persistence assumptions,
vector index, backup notes
* docs/07-integrations.md — LLM providers, MCP servers, auth,
queues, observability mocks (incident
example), code-review mocks, memory
layers, CI services, local overrides
* docs/08-testing.md — pytest config, run commands, suite
structure (149 files, 1265 tests),
what's covered well vs weakly,
CI gates, how to add a test
* docs/09-build-deploy-release — bundler pipeline, CI workflow,
containerisation status (none),
air-gap deploy procedure, release
flow, rollback, versioning
* docs/10-known-risks-and-todos — TODO/FIXME inventory, hardcoded
values, weak features, security
surfaces, migration risks,
concurrency risks, ops risks
* docs/11-agent-handoff.md — 20-line summary, top 20 files to
read, command allow/deny lists,
8 architectural rules, coding
conventions, common traps,
unfinished work, recommended next
tasks
* docs/adr/0001-current-architecture.md
— decision baseline as of v1.5,
consequences (positive / negative /
neutral), alternatives considered,
open questions for future ADRs
* CLAUDE.md — project context loaded by Claude
Code (and equivalent agents) every
session. DO / DO NOT lists,
architectural rules recap, common
traps, where-to-find-what map.
* README.md — added for-the-badge styled badges
(Python, LangGraph, FastMCP, CI,
SonarCloud quality gate + coverage,
test count, ruff, pyright). Body
unchanged from the v1.5 doc-
consolidation PR.
* .gitignore — explicit allowlist for the new
docs/* files + docs/adr/ next to
the existing DESIGN/AIRGAP/DEVELOPMENT
entries. The ``docs/*`` blanket
ignore stays so accidentally-
generated scratch doesn't leak in.
Documentation conventions used throughout:
- Inline source references (file:line where useful) for every
non-obvious claim.
- Inferences explicitly tagged "Inference:" so future readers can
re-verify.
- Unknowns explicitly tagged "Unknown" rather than guessed.
- No real secrets — only env-var names and CI dummy patterns.
Suite: 1265 passed (unchanged — docs-only). Ruff clean.
|
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Comprehensive per-topic brownfield documentation for future developers and AI coding agents picking the project up cold. Twelve numbered files under
docs/+ an ADR +CLAUDE.md+ for-the-badge styled README badges. No source changes.What landed
docs/00-project-overview.mddocs/01-local-setup.mddocs/02-architecture.mddocs/03-code-map.mddocs/04-main-flows.mddocs/05-configuration.mddocs/06-data-model.mddocs/07-integrations.mddocs/08-testing.mddocs/09-build-deploy-release.mddocs/10-known-risks-and-todos.mddocs/11-agent-handoff.mddocs/adr/0001-current-architecture.mdCLAUDE.mdREADME.md.gitignoreDocumentation conventions
Inference:so future readers can re-verifyUnknownrather than guessedTest plan
uv run pytest -x— 1265 passed, 8 skipped (unchanged — docs-only)uv run ruff check src/ tests/— clean🤖 Generated with Claude Code