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:

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.
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 — 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 §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 §§1–7 vs 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:

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. 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)

7.6 KiB Raw Blame History Unescape Escape