docs: move the long-form docs into docs/, without the superpowers nesting

ARCHITECTURE, PRODUCT and TODO move out of the repository root, and
docs/superpowers/{specs,plans} flattens to docs/{specs,plans}:
"superpowers" names the tool that wrote those documents, not a kind of
document.

No content changes. This commit is the move, plus the roughly thirty
cross-references the move invalidated.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

AGENTS.md

@@ -6,13 +6,13 @@ validation this codebase deliberately does not perform.
 
 Then, depending on what you are doing:
 
-- **Changing anything structural** → `ARCHITECTURE.md` (layers, data flow, and
+- **Changing anything structural** → `docs/ARCHITECTURE.md` (layers, data flow, and
   why the non-obvious choices are what they are).
-- **Picking up queued work** → `TODO.md` (ordered, each item carrying the
+- **Picking up queued work** → `docs/TODO.md` (ordered, each item carrying the
   reasoning already settled).
-- **Making a product decision** → `PRODUCT.md` (who this is for, what must never
+- **Making a product decision** → `docs/PRODUCT.md` (who this is for, what must never
   break, and what must not be invented).
-- **Wondering why something is the way it is** → `docs/superpowers/specs/`
+- **Wondering why something is the way it is** → `docs/specs/`
   records the decisions *and the alternatives that were rejected*.
 
 Two rules worth knowing before your first edit:

CLAUDE.md

@@ -144,11 +144,11 @@ For more information, read the Bun API docs in `node_modules/bun-types/docs/**.m
 
 ## Start here
 
-- `ARCHITECTURE.md` — layers, data flow, and why the non-obvious choices are
+- `docs/ARCHITECTURE.md` — layers, data flow, and why the non-obvious choices are
   what they are. Read it before changing anything structural.
-- `TODO.md` — queued work, each item carrying the reasoning already settled.
-- `PRODUCT.md` — who this is for and what must never break.
-- `docs/superpowers/specs/` — design decisions, including alternatives rejected.
+- `docs/TODO.md` — queued work, each item carrying the reasoning already settled.
+- `docs/PRODUCT.md` — who this is for and what must never break.
+- `docs/specs/` — design decisions, including alternatives rejected.
 
 ## Gotchas that cost real bugs
 

README.md

@@ -53,5 +53,5 @@ your current data first.
 
 ## Documentation
 
-- Design: `docs/superpowers/specs/2026-09-01-budget-app-design.md`
-- Implementation plan: `docs/superpowers/plans/2026-09-01-budget-app.md`
+- Design: `docs/specs/2026-09-01-budget-app-design.md`
+- Implementation plan: `docs/plans/2026-09-01-budget-app.md`

docs/ARCHITECTURE.md

@@ -175,7 +175,7 @@ timing that happy-dom does not reproduce.
 
 ## Where the reasoning lives
 
-- `PRODUCT.md` — durable product truth: who it is for, what must never break.
-- `TODO.md` — queued work, with the reasoning behind each decision already made.
-- `docs/superpowers/specs/` — design decisions and the alternatives rejected.
-- `docs/superpowers/plans/` — task-by-task implementation plans.
+- `docs/PRODUCT.md` — durable product truth: who it is for, what must never break.
+- `docs/TODO.md` — queued work, with the reasoning behind each decision already made.
+- `docs/specs/` — design decisions and the alternatives rejected.
+- `docs/plans/` — task-by-task implementation plans.

docs/TODO.md

@@ -17,8 +17,8 @@ behaviour-preserving by construction and tested as such.
 
 ## 1. ~~Time-versioned allocation rules~~ — DONE, all six tasks
 
-**Spec:** `docs/superpowers/specs/2026-09-02-versioned-allocation-rules-design.md`
-**Plan:** `docs/superpowers/plans/2026-09-02-versioned-allocation-rules.md`
+**Spec:** `docs/specs/2026-09-02-versioned-allocation-rules-design.md`
+**Plan:** `docs/plans/2026-09-02-versioned-allocation-rules.md`
 **Ledger + extracted briefs:** `.superpowers/sdd/2026-09-02-versioned-allocation-rules/`
 
 | Task | What | Commit |
@@ -68,7 +68,7 @@ sleek, modern, and nice to use."* Then, on scoping: both themes with a toggle,
 a full rethink of every screen, purchases compact and grouped by date, ship a
 webfont — and *"override everything you want for this step."*
 
-**Spec:** `docs/superpowers/specs/2026-09-02-design-foundation-design.md`
+**Spec:** `docs/specs/2026-09-02-design-foundation-design.md`
 
 **The diagnosis, which should shape the rest:** a design system already existed
 and was never wired up. `src/index.css` defined the paper/ink/teal palette with
@@ -84,7 +84,7 @@ foundation last is how that happened; do not repeat it.
 | 4 | Dialogs and fast entry | untouched. Native `<select>` elements are still browser-default, and `up`/`down`/`archive` are bare text buttons |
 
 **Sub-project 2, for whoever does 3 and 4.** Spec:
-`docs/superpowers/specs/2026-09-02-month-view-design.md`. Three things it
+`docs/specs/2026-09-02-month-view-design.md`. Three things it
 settled that the reporting screens should follow rather than re-decide:
 
 - **Meter geometry is `src/ui/meterSegments.ts`**, pure and tested, with

docs/plans/2026-09-01-budget-app.md

@@ -15,7 +15,7 @@
 
 **Tech Stack:** Bun 1.3+ (runtime, package manager, bundler, test runner), React 19, Tailwind 4, shadcn/ui, `fflate` for ODS zip generation, hand-written service worker. No Vite. No Electron.
 
-**Spec:** `docs/superpowers/specs/2026-09-01-budget-app-design.md`
+**Spec:** `docs/specs/2026-09-01-budget-app-design.md`
 
 ## Global Constraints
 
@@ -177,7 +177,7 @@ The scaffolded `CLAUDE.md` documents Bun idioms. Append the rules specific to th
   reimplement the math.
 - Over-budget is always allowed. Never add validation that blocks it.
 - Base path comes from `BUN_PUBLIC_BASE_PATH`; never hardcode a subpath.
-- Read the spec at `docs/superpowers/specs/2026-09-01-budget-app-design.md`.
+- Read the spec at `docs/specs/2026-09-01-budget-app-design.md`.
 ```
 
 - [ ] **Step 8: Ignore the IDE directory**
@@ -7357,8 +7357,8 @@ your current data first.
 
 ## Documentation
 
-- Design: `docs/superpowers/specs/2026-09-01-budget-app-design.md`
-- Implementation plan: `docs/superpowers/plans/2026-09-01-budget-app.md`
+- Design: `docs/specs/2026-09-01-budget-app-design.md`
+- Implementation plan: `docs/plans/2026-09-01-budget-app.md`
 ```
 
 - [ ] **Step 7: Final verification**

docs/plans/2026-09-02-versioned-allocation-rules.md

@@ -8,7 +8,7 @@
 
 **Tech Stack:** Bun (runtime, package manager, test runner), TypeScript strict, React 19, Tailwind 4, shadcn/ui. No new dependencies.
 
-**Spec:** `docs/superpowers/specs/2026-09-02-versioned-allocation-rules-design.md`
+**Spec:** `docs/specs/2026-09-02-versioned-allocation-rules-design.md`
 
 ## Global Constraints
 

docs/specs/2026-09-01-budget-app-design.md

@@ -315,5 +315,5 @@ migrations are mandatory rather than optional.
   invariants: the domain layer stays free of React and IndexedDB, money
   rounds at every boundary, the last distributed part is computed by
   subtraction, and the rollover fold has exactly one implementation.
-- `docs/superpowers/specs/` — this document
-- `docs/superpowers/plans/` — the implementation plan, written next
+- `docs/specs/` — this document
+- `docs/plans/` — the implementation plan, written next

docs/specs/2026-09-02-design-foundation-design.md

@@ -76,7 +76,7 @@ rather than on the arithmetic.
 
 Inter for text, JetBrains Mono for figures, both variable, both self-hosted,
 latin + latin-ext only. SIL OFL 1.1; licences committed beside the files.
-Self-hosted rather than CDN-linked because PRODUCT.md's position is that the
+Self-hosted rather than CDN-linked because docs/PRODUCT.md's position is that the
 data never leaves the browser and the app needs no third party — a font request
 to another origin on every cold load quietly contradicts that.
 

docs/specs/2026-09-02-month-view-design.md

@@ -19,7 +19,7 @@ Three problems, found by looking at the rendered page in Chrome at 1280px and
 Income, Allocated, Spent and Unallocated sat in one row at one weight. The
 income *input* — the only editable thing on the screen — was in the same visual
 register as three numbers derived from it. And nothing at the month level
-answered the second of PRODUCT.md's two questions, *did I overspend*: with
+answered the second of docs/PRODUCT.md's two questions, *did I overspend*: with
 Transport at −3,200 DKK, you had to read down the Remaining column to find out.
 
 **The carry meter belonged to the wrong row.** It is the design contract's
@@ -41,7 +41,7 @@ Three zones in reading order, in the one `Section` card, on the paper ground
 below the unchanged month `<header>`.
 
 1. **Income** — the field. Unchanged in behaviour: still `type="number"`, still
-   base-currency only. Section 6 of TODO.md records the reasoning — a month has
+   base-currency only. Section 6 of docs/TODO.md records the reasoning — a month has
    one income, so making the field parse a currency the way the purchase total
    does is arguably wrong rather than merely undone. It keeps field affordance
    so it stays visibly the one editable thing on the screen.

scripts/demo-data.ts

@@ -11,7 +11,7 @@
  * profile on every run unless you pass --profile, so without this every
  * screenshot shows an app full of zeros.
  *
- * The data is visibly synthetic on purpose. PRODUCT.md: the owner's real budget
+ * The data is visibly synthetic on purpose. docs/PRODUCT.md: the owner's real budget
  * never leaves their browser, so it is never available as example material, and
  * illustrative data must not pretend to be real.
  */
@@ -19,7 +19,7 @@ import { createSeedDataset } from "../src/domain/seed.ts";
 import * as actions from "../src/store/actions.ts";
 import { FALLBACK_FX_RATES } from "../src/store/bakedRates.ts";
 
-// Visibly synthetic, per PRODUCT.md: the owner's real budget must never be
+// Visibly synthetic, per docs/PRODUCT.md: the owner's real budget must never be
 // used as example material, and illustrative data must not look real.
 const d = createSeedDataset("2026-01", FALLBACK_FX_RATES);
 const [games, food, social] = d.posts as [typeof d.posts[0], typeof d.posts[0], typeof d.posts[0]];

scripts/fetch-fonts.ts

@@ -3,7 +3,7 @@
  *
  *   bun scripts/fetch-fonts.ts
  *
- * Self-hosted, not linked from a CDN, because PRODUCT.md's position is that the
+ * Self-hosted, not linked from a CDN, because docs/PRODUCT.md's position is that the
  * app works offline and needs no third party: a font request to another origin
  * on every cold load contradicts that, and would leak the fact that the app was
  * opened. The files are COMMITTED so neither the build nor a fresh checkout

scripts/screenshot.ts

@@ -7,7 +7,7 @@
  *                             [--eval=<js>|--eval-file=<path>] [--dark] [--reload]
  *                             [--profile=<dir>] [--eval-after-file=<path>]
  *
- * Why this exists: ARCHITECTURE.md and TODO.md both say nothing here can run a
+ * Why this exists: docs/ARCHITECTURE.md and docs/TODO.md both say nothing here can run a
  * browser, so appearance has never been verified. Chrome IS available, but its
  * plain `--screenshot` flag fires on the load event — before this app's async
  * IndexedDB read resolves, which captures an empty page. Driving CDP directly