hamid
59 lines
3.0 KiB
Markdown
59 lines
3.0 KiB
Markdown
# Balinyaar docs
|
|
|
|
The entry point. Start here, follow one link, stop reading.
|
|
|
|
> **Being built.** This tree is the output of [the clarify chain](_plan/README.md). 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/`](../product/index.md) | **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/`](../dev/README.md).
|
|
|
|
---
|
|
|
|
## Map
|
|
|
|
| Section | What it holds | Status |
|
|
| --- | --- | --- |
|
|
| [rules/](rules/index.md) | What must never be broken — the tiered rule set behind the `CLAUDE.md` files | **written** · phase 1 |
|
|
| [integration/](integration/index.md) | The client↔server seam in one place: contract, config, topology, OpenAPI | **written** · phase 2 |
|
|
| [flows/](flows/index.md) | What is implemented, and how to test it — one file per user journey | **written** · phase 3 |
|
|
| [status/](status/index.md) | Where the project actually is: implemented, backlog, decisions | not yet written · phase 4 |
|
|
| [roadmap/](roadmap/index.md) | Where it goes next, and what gates a launch | not yet written · phase 5 |
|
|
| [_plan/](_plan/README.md) | 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`](../DEPLOY.md) — the deploy *procedure*, at the repo root where an operator will look for
|
|
it. The runtime *topology* it implies moves to `docs/integration/topology.md`.
|
|
- [`product/`](../product/index.md) — untouched by this chain. `docs/status/implemented.md` will overlay
|
|
build state onto its 14 business areas rather than restating them.
|
|
|
|
## Conventions
|
|
|
|
1. **Every status or flow doc carries `> Last verified: <date> against <commit>`.** A doc without one is
|
|
a claim, not a fact.
|
|
2. **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.
|
|
3. **Write short.** A reference doc over ~400 lines should be split. One deliberate exception:
|
|
[flows/testing-setup.md](flows/testing-setup.md) is the single page you hand a new tester, and splitting
|
|
it would defeat that.
|
|
4. **English throughout**, including in files that describe Persian UI copy.
|
|
|
|
The full convention is in [docs/rules/documentation.md](rules/documentation.md), to be enforced by a
|
|
pre-commit warning (phase 7).
|