docs

Imported from Teased-oChroid-orrA/powershell_tool (docs/AGENTS.md). Install upstream with npx skills add Teased-oChroid-orrA/powershell_tool --skill docs. Copyright stays with the author.

docs/

Purpose

Owns: navigation index into this repo's design/history documentation - ADRs, per-issue phase-by-phase implementation logs, epic status reports, and standalone topic docs (architecture, deployment, FFI, benchmarking, etc.).

This is a navigation index, not a content digest. docs/ is ~132k tokens of Markdown. Do not read it all; use the tables below to jump to the one file that has the answer.

Does not own: the narrative content itself - don't duplicate phase-doc or ADR prose into this file or into root CLAUDE.md. Link to the source file.

Code Map

Find It Fast — by architecture decision

Find It Fast — by epic/issue implementation history

Find It Fast — by current/live status

Find It Fast — standalone topic docs

Entry Points

Contracts

• Phase docs and status docs are an append-only historical record. Never delete or rewrite one when the work it describes is superseded — add a new phase/status file, or a note at the top of the old one, instead. Precedent: ADR-007 was superseded by ADR-011 by adding ADR-011 and marking 007 "Superseded", not by deleting or editing 007's content.
• Don't duplicate phase-doc/epic narrative into CLAUDE.md or any AGENTS.md node. Root CLAUDE.md ballooned to 2273 lines by inlining issue #11's narrative in full; it's being slimmed to link here instead. This file must stay an index, not a digest, or it repeats that mistake.
• issue-N-status.md naming usually (not always) means a closed, point-in- time epic summary. docs/issue-10-status.md is the exception — it's a status doc for a partially executed, on-hold epic (Phase 1 shipped, rest explicitly not started). Verify with the file's own opening lines before treating any -status.md as "done".
• Standalone *-status.md / checklist files without an issue number (toolbench-status.md, rust-rewrite-status.md, bushing-workbench-status.md, app-egui-parity-checklist.md) are living documents, updated in place as that area evolves — not historical record.

Boundaries

Always

• Add new phase/status content as a new file (issue-N-phase-M.md) or a dated addendum inside a live status doc; keep prior phases intact.
• Link to the specific ADR/phase/status file rather than re-explaining its contents elsewhere in the repo.

Never

• Delete or overwrite a completed issue-N-phase-*.md or a closed issue-N-status.md when the work it describes is superseded.
• Copy phase-doc or ADR narrative into CLAUDE.md, this file, or any other AGENTS.md node — link instead.

Verify First

• Before treating any *-status.md as closed/superseded, check its own opening lines and git log -1 --format=%ai -- <file> — the filename pattern alone is not reliable (see issue-10-status.md).

Pitfalls

• docs/issue-11-phase-*.md numbering skips phase 8 (jumps 7 → 9) — that's not a missing file; phase 8's work was folded into another phase.
• docs/issue-10-status.md looks like a closed epic summary (same filename pattern as #2/#6/#8/#11) but explicitly scopes itself to "Phase 1 only", with the rest of the 14-toolbox platform "on hold (not started, not planned further here)" per its own text.
• ADR-007 (index-persistence-location) reads as a normal Accepted decision but is superseded by ADR-011 — read 011 for the actual current answer.
• Reading only issue-11-phase-14.md/-15.md for "what's left" on app-egui gives a stale answer — the current, maintained list is app-egui-parity-checklist.md, which exists specifically because the phase docs' deferred-item prose aged silently.
• A status/phase doc's numeric section refs (e.g. "epic §54") point into the external GitHub issue's own section numbering, not to anything inside docs/ — don't go looking for a "§54" file here.

Downlinks