create mvp path

2026-08-02 20:01:31 +03:30
parent 72ab290da1
commit fb58ca54e1
203 changed files with 863 additions and 156 deletions
@@ -0,0 +1,61 @@
+# Balinyaar docs
+
+The entry point. Start here, follow one link, stop reading.
+
+> **Built by the clarify chain**, phases 0–7, 2026-07-29 → 2026-08-02. The chain's own plan — inventory,
+> contradiction log, phase files, and their progress table — is now history, kept at
+> [`archive/clarify-chain/`](../archive/clarify-chain/README.md). Phase 7 (skills & guardrails) is done:
+> three playbooks live in [`.claude/skills/`](../.claude/skills/); the anti-drift convention below is
+> enforced by review rather than a git hook (an MVP-stage call — see
+> [decisions.md](status/decisions.md)).
+
+---
+
+## 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/` holds the executed build-chain prompts, reports, and the pre-cleanup `docs/_plan/`. Start at
+[`archive/README.md`](../archive/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 | **written** · phase 4 |
+| [roadmap/](roadmap/index.md) | Where it goes next, and what gates a launch | **written** · phase 5 |
+
+## 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` overlays
+  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) — enforced by review,
+not tooling (an MVP-stage call; see [git-and-gates.md](rules/shared/git-and-gates.md)).