hamidBalinyaar docs
The entry point. Start here, follow one link, stop reading.
Being built. This tree is the output of the clarify chain. Sections marked not yet written are scaffolded but empty — the doc that currently holds that knowledge is named beside each one so nothing is unreachable in the meantime.
The rule that keeps three trees apart
| Tree | Answers | Example |
|---|---|---|
product/ |
What the business is | escrow holds funds until check-out is confirmed |
docs/ (here) |
What we built, and how we work | the escrow ledger is implemented; here is how to test it |
archive/ |
How we got here | the phase-10 prompt that built the ledger, and its report |
A file belongs in exactly one. If you are about to write a business rule into docs/, it belongs in
product/. If you are about to obey something in archive/, stop — it is a record, not an instruction.
archive/ does not exist yet; Phase 6 creates it from today's dev/.
Map
| Section | What it holds | Status |
|---|---|---|
| rules/ | What must never be broken — the tiered rule set behind the CLAUDE.md files |
written · phase 1 |
| integration/ | The client↔server seam in one place: contract, config, topology, OpenAPI | written · phase 2 |
| flows/ | What is implemented, and how to test it — one file per user journey | written · phase 3 |
| status/ | Where the project actually is: implemented, backlog, decisions | not yet written · phase 4 |
| roadmap/ | Where it goes next, and what gates a launch | not yet written · phase 5 |
| _plan/ | The chain that builds this tree. Temporary — moves to archive/ when done |
in progress |
Still elsewhere
Two documents stay outside this tree on purpose:
DEPLOY.md— the deploy procedure, at the repo root where an operator will look for it. The runtime topology it implies moves todocs/integration/topology.md.product/— untouched by this chain.docs/status/implemented.mdwill overlay build state onto its 14 business areas rather than restating them.
Conventions
- Every status or flow doc carries
> Last verified: <date> against <commit>. A doc without one is a claim, not a fact. - Verify, don't copy. A load-bearing claim is checked against code or run. If it cannot be checked,
it is written with an explicit
UNVERIFIED:prefix. - Write short. A reference doc over ~400 lines should be split. One deliberate exception: flows/testing-setup.md is the single page you hand a new tester, and splitting it would defeat that.
- English throughout, including in files that describe Persian UI copy.
The full convention is in docs/rules/documentation.md, to be enforced by a pre-commit warning (phase 7).