baya-monorepo/docs/_plan/phase-0-inventory-and-scaffold.md

# Phase 0 — Inventory & scaffold

**Depends on:** nothing · **Blocks:** every other phase · **Size:** one session

## Goal

Before anything is moved, merged, or deleted, produce two things:

1. **A disposition for every one of the ~260 markdown files in the repo** — so that "summarize
   without losing data" is a checkable claim rather than a hope.
2. **The empty `docs/` skeleton** with a real entry point, so later phases have somewhere to write.

Plus one piece of housekeeping every later phase needs: a **fresh OpenAPI snapshot**, because the
committed one is 16 days behind the server code.

This phase writes almost no prose. It is a survey.

---

## Inputs

- The whole repo. Specifically: `dev/` (199 files), `product/` (48), root (4), `client/` (5),
  `server/` (6), `telegram-otp-bot/` (2), `.claude/skills/` (1), `.githooks/` (1).
- [`../README.md`](README.md) — the target tree and the decisions.

## Outputs

| File | What it is |
| --- | --- |
| `docs/_plan/inventory.md` | The disposition table — every markdown file, one row |
| `docs/README.md` | The single entry point: a map of `docs/`, `product/`, `archive/` and what belongs where |
| `docs/rules/index.md` `docs/integration/index.md` `docs/flows/index.md` `docs/status/index.md` `docs/roadmap/index.md` | Stub indexes, each with a one-line purpose and a "populated by phase N" note |
| `docs/integration/openapi/swagger.v1.json` | Regenerated from the running server |
| `docs/_plan/open-contradictions.md` | Running list of doc-vs-doc and doc-vs-code conflicts spotted during the survey — later phases resolve these |

---

## Steps

### 1. Build the inventory

Walk every `.md` file (exclude `node_modules`, `bin`, `obj`, `.git`). For each, record:

| Column | Meaning |
| --- | --- |
| `path` | repo-relative |
| `bytes` | size |
| `last commit` | `git log -1 --format=%ad --date=short -- <path>` |
| `kind` | `rule` · `reference` · `contract` · `plan` · `report` · `history` · `business` · `ops` · `feedback` |
| `disposition` | `keep-as-is` · `move` · `distill` · `merge-into` · `archive` · `delete` |
| `target` | where its content ends up (a `docs/…` path, or `archive/…`) |
| `owner phase` | which phase (1–7) handles it |
| `live facts?` | `yes` / `no` — does it contain anything not yet captured elsewhere? |

Rules for assigning disposition:

- **`dev/phases/backend/*` and `dev/phases/frontend/*`** (32 files, ~1 MB): these are *prompts that
  were already executed*. Disposition `archive`. But scan each for **decisions and constraints stated
  in the prompt that are not visible in the code** — those are `live facts: yes` and go to Phase 1
  (if a rule) or Phase 4 (`decisions.md`).
- **`dev/shared-working-context/reports/*` (50 files)**: `archive`, but every "Follow-ups for later
  phases" / "Deferred" / "Known gap" section is a live fact for **Phase 4**. Extract the section
  headings now; Phase 4 reads them in detail.
- **`dev/shared-working-context/*/STATUS.md`** (86 KB combined): `distill` → Phase 4 (`decisions.md`
  + `implemented.md`), then `archive`.
- **`dev/shared-working-context/frontend/requests/for-backend.md`** (67 REQs): `distill` → Phase 4.
- **`dev/post-phase/hardening/issues.md`** (18 open items): `distill` → Phase 4, **with
  re-verification** — the UI and refinement chains ran after this file was written and some items are
  probably already fixed.
- **`dev/contracts/**`**: `move` → `docs/integration/` — Phase 2 owns it, and refreshes it against code.
- **`dev/post-phase/manual-testing-plan.md`** + **`refinement/RUNBOOK.md`**: `distill` → Phase 3
  (`docs/flows/testing-setup.md` + the per-flow files). Both are stale on secrets handling.
- **`dev/manual-testing/iteration-*/`**: `distill` → Phase 4 (unfinished items) then `archive`
  (**keep the PNG screenshots** — they are the only visual record of the pre-overhaul UI).
- **`product/**`**: `keep-as-is`, every one. Not this chain's business.
- **`client/CLAUDE.md`, `server/CLAUDE.md`, `server/CONVENTIONS.md`, `client/messages/STYLE.md`,
  `dev/phases/_shared/*`, `dev/contracts/conventions/*`, `.claude/skills/*/SKILL.md`**: `distill` →
  Phase 1.
- **`DEPLOY.md`**: `keep-as-is` at root (it is the deploy *procedure* and it is current) — but Phase 2
  fixes its stale `user-secrets` reference and Phase 2's `topology.md` links to it.
- **`Prompt.md`** (0 bytes): `delete`.
- **`temp/swagger.json`** (stale duplicate): `delete` — Phase 2 replaces it.
- **`client/graphify-out/GRAPH_REPORT.md`, `server/graphify-out/GRAPH_REPORT.md`**: generated tool
  output. Decide `keep-as-is` if the tool is still used, else `delete`; check `.gitignore` first.

### 2. Log contradictions as you go

Write `docs/_plan/open-contradictions.md` with one row per conflict: *claim A (file:line) vs claim B
(file:line or code:line) — unresolved*. Seed it with the ones already known:

- **`user-secrets` is required** (18 files) vs **`user-secrets` was removed and the store isn't read**
  (root [CLAUDE.md](../../CLAUDE.md) §6, commit `5885280`).
- **`dev/contracts/` describes the API** (frozen 2026-07-13) vs **`server/src`** (through 2026-07-28).
- **Design language in [.claude/skills/frontend-designer/SKILL.md](../../.claude/skills/frontend-designer/SKILL.md) §§1–7**
  vs **[client/CLAUDE.md](../../client/CLAUDE.md) "Theme System" / "Anti-patterns"** — overlapping, possibly divergent.
- **Both** vs **the reality after iterations 1–2** (mobile-scoped shell, bottom nav, react-hook-form,
  new icon set) — the skill predates that overhaul.
- **18 hardening items open** (2026-07-16) vs **UI phases 0–13 and the deploy commits that ran after**.

Do **not** resolve these here. Phase 0 only finds them.

### 3. Regenerate the OpenAPI snapshot

Boot the server and capture the live swagger document:

```bash
cd server && dotnet run --project src/API/Baya.Web.Api/Baya.Web.Api.csproj
# then, from another shell:
curl -sk https://localhost:5002/swagger/v1/swagger.json -o docs/integration/openapi/swagger.v1.json
```

Record in the file's sibling `README.md`: the date, the commit, and the endpoint count. Diff the
endpoint *paths* against the old `dev/contracts/openapi/swagger.v1.json` and write the added/removed
list into `docs/_plan/open-contradictions.md` — Phase 2 uses it as its worklist.

If the server will not boot (config, DB reachability), **stop and report** rather than guessing. A
stale snapshot is what caused half of this mess.

### 4. Scaffold `docs/`

Create the directories and stub index files from the target tree in [`README.md`](README.md). Each
stub is ~10 lines: what lives here, which phase fills it, and a `> Populated by phase N — not yet
written` banner. `docs/README.md` is the only one with real content: the map, and the
`product/` vs `docs/` vs `archive/` rule.

Do **not** create `archive/` yet — Phase 6 does that, once there is something safe to put in it.

---

## Verification

- [ ] `docs/_plan/inventory.md` has a row for every `.md` file the survey walked; the count matches
      `find . -name "*.md" -not -path "./node_modules/*" … | wc -l` (~260 at baseline).
- [ ] No row has an empty `disposition` or `owner phase`.
- [ ] Every row with `live facts: yes` names the phase that will extract them.
- [ ] `docs/integration/openapi/swagger.v1.json` exists and its endpoint count is recorded.
- [ ] Every stub index exists and says which phase fills it.
- [ ] Nothing outside `docs/` was modified, except deleting `Prompt.md` and `temp/swagger.json`.

## Definition of done

You can answer, for any markdown file in the repo, "where does this end up and who handles it?"
without re-reading the file.

## Handoff

_(filled in by the agent that runs this phase — file counts, surprises, anything that changes a later
phase's scope)_