This folder is the source of truth for project documentation. It is split into three kinds of documents, by intent:
docs/
├── guides/ # How-to and reference. Stable, evergreen, no checkboxes.
├── plans/ # Tracked roadmaps with phases, deliverables, status.
└── obsidian/ # Obsidian vault: canvas + supporting scratch notes.
Stable, "how do I do X" content. Update when the answer changes.
guides/workflow.md— Git + GitHub workflow, branching, recovering from common mistakes.guides/axecore-integration.md— Reference for how the Puppeteer + axe-core scanner is meant to be wired in (architecture, code samples, troubleshooting).guides/intern-onboarding-post-reorg.md— Deep dive: every folder, why it exists, and the call chain through both halves of the app.guides/thinking-in-architecture.md— 5-minute intern primer on the layered model, with each open GitHub issue mapped to "which layer does this change live in?"
Time-bounded, trackable work. Each plan has phases, concrete deliverables, and a status. When a plan is complete, archive it but leave it in place for history.
plans/project-roadmap.md— Top-level map of phases (housekeeping → real scanner → UX → reliability → productionization) with intern-friendly tasks after each phase.plans/architecture-map.md— Visual map: every screen, what it does, what the backend does for it, and how frontend/backend code is organized.plans/axecore-integration-roadmap.md— Replace mock scan data with a real axe-core scanner.plans/codebase-reorganization.md— Post-mortem of the Phase 1 + Phase 3 reorg (PRs #38–#40): before/after tables and the rationale for each file move. The current layout itself lives in the top-levelREADME.md; the architectural target lives inplans/architecture-map.md§6.
Supplementary brainstorming material — Obsidian canvas, pasted images, notes. Not authoritative. Open the folder as a vault in Obsidian to edit it.
See obsidian/README.md.
| Need | Where it goes |
|---|---|
| "How do I do X in this repo?" | guides/ |
| "What work needs to happen, in what order?" | plans/ |
| "I'm thinking out loud / sketching" | obsidian/ |
| "What is the current behavior?" | Top-level README.md |
For lightweight task tracking prefer GitHub Issues. Use plans/ only
when a body of work spans many issues and needs a shared narrative.