docs: reconcile documentation against the code; add a supersession ledger

Five weeks of undocumented evolution left the docs describing a site that
partly no longer exists, with nothing marking which documents were historical.
The code is treated as the source of truth throughout; every claim below was
verified against code, config or the Makefile rather than inferred.

Two mechanisms, following patterns the repo already used:

- docs/reference/superseded-decisions.md (new) — one authoritative table of all
  14 reversals: what was planned, where, what is true now, when, and why. Plus
  a short list of decisions that were NOT reversed, since their planning docs
  are old enough to look suspect.
- Inline "> **Superseded ...**" notes at each stale claim, so a claim can never
  be read un-corrected. This mirrors the existing "> History:" notes in
  architecture.md and "> **Changed 2026-07:**" in trip-switching.md.

Scope split by tense: present-tense docs (CLAUDE.md, reference/, guides/,
README.md, CONCEPTS.md) are corrected; past-tense records (plans/, specs/,
milestones/, summary.md, pm-analysis.md) are annotated only, never rewritten —
their staleness is what makes them records.

Present-tense corrections:

- CLAUDE.md asserted css-compiled/ is generated from css/style.css and
  css/tokens.css. That source relationship does not exist: css/ is hand-authored
  and served directly via assets.addCss in partials/base.html.twig, while
  css-compiled/ is esbuild output from the CSS imports inside js/src/*.js.
  Highest-severity finding — an always-loaded file inviting a hand-edit of a
  generated bundle.
- README.md documented every remote-* target without the -test/-prod suffix
  guard-env requires, so its entire server runbook was unrunnable, and listed
  7 of ~20 targets while CLAUDE.md designates it authoritative for the full
  list. Rewritten with all targets, grouped, and the suffix rule stated.
- README.md told readers to "git clone" into user/, which is a submodule.
- architecture.md: nav is Home + Trips + (authenticated) New Post, not
  "Home + Past Trips only"; template tree omitted trips.html.twig,
  post-form.html.twig and forms/, and placed base.html.twig at templates/ root
  rather than in partials/; entry-actions has three API routes, not just delete;
  added the undocumented css-compiled/maplibre-gl.css output and a section on
  the /post pin editor as the one sanctioned non-entry-map map.
- design-system.md: documented 13 colour tokens against 19 in tokens.css
  (missing --color-error, --color-draft-accent and four glass overlays); claimed
  "all 3 map templates"; and described --color-canvas as "white".
- design-system-light.md documented a light palette in present tense. No light
  mode exists — tokens.css has a single :root block, no prefers-color-scheme or
  data-theme switch, and no light hex appears in css/. Banner added.
- posting.md said photos were optional; they are required, 1-6. It documented
  hero_image, which was removed for entries (stories keep it). It had no mention
  of the frontend edit flow or photo editor, both shipped 2026-07-08. Photo
  files are photo-01..NN, zero-padded.
- working/README.md advertised summary.md as the project's "current state" while
  summary.md describes Leaflet, /tracker, /map and /stats. Most misleading line
  in the tree.
- CLAUDE.md: recorded js/src/location-map.js as the one sanctioned exception to
  the single-map-path rule, and documented that make start/setup fail on a clean
  checkout because docker-compose.yml still builds a travel-memories service
  whose source moved out in a80b0a9.

Also: 2026-07-23-post-form-location-override.md read "Not started" while merged
in user/ as dd19995; status corrected.

Findings that are not documentation problems — the compose breakage, a
repeatable drift check, the unused shortcode-gallery-plusplus, and demo fixtures
for retired views — are collected in
docs/working/2026-07-25-doc-drift-recommendations.md and deliberately not acted
on. Design and verification method: docs/working/specs/2026-07-25-docs-reconciliation-design.md

The submodule gitlink is deliberately not bumped.

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

docs/working/specs/2026-07-25-docs-reconciliation-design.md

@@ -0,0 +1,109 @@
+# Docs Reconciliation — Design
+
+**Date:** 2026-07-25
+**Status:** Implemented
+
+Reconcile the documentation against the code after five weeks of undocumented evolution, so that a
+repeat review returns "ok".
+
+---
+
+## Problem
+
+Documentation for this project began as thoughts and plans. The app then changed — features were
+built differently, some were dropped, and the owner changed his mind about what he needed. Those
+decisions were recorded ad hoc or not at all. The result is a tree where some docs describe a site
+that no longer exists, and nothing marks them as historical.
+
+Concretely, before this pass:
+
+- `docs/working/README.md` advertised `summary.md` as the project's **current state**, while
+  `summary.md` described Leaflet, a `/tracker` feed, a `/map` page, a `/stats` page, and a
+  "Journal · Map · Stats" nav — none of which exist.
+- `docs/reference/design-system-light.md` documented a light-mode palette in present tense. No light
+  mode is implemented anywhere: `tokens.css` has a single `:root` block and no
+  `prefers-color-scheme` / `data-theme` mechanism.
+- `CLAUDE.md` — the always-loaded file — asserted a source relationship that does not exist
+  (`css-compiled/` generated from `css/style.css` + `css/tokens.css`).
+- `README.md`'s server runbook documented every `make remote-*` command without the `-test`/`-prod`
+  suffix that `guard-env` requires, so the documented commands cannot run.
+- `docker-compose.yml` still defines a `travel-memories` service whose source was deleted in
+  `a80b0a9` ("moved to separate project"), so `make start` fails on any clean checkout.
+
+## Root cause
+
+Per [`docs/solutions/conventions/claude-md-content-tiering.md`](../../solutions/conventions/claude-md-content-tiering.md),
+descriptions drift because the code moves and the prose does not; rules do not drift, because they
+encode intent rather than state. This pass confirms that finding again: every defect found was a
+description of code, config, or a command — not one was a rule that had become wrong on its own.
+
+The compounding factor is **tense**. The tree mixes two kinds of document with no marker
+distinguishing them:
+
+| Kind | Files | Staleness is |
+|---|---|---|
+| Present-tense — "this is how it is" | `CLAUDE.md`, `reference/`, `guides/`, `README.md`, `CONCEPTS.md` | a defect |
+| Past-tense — "this is what we decided then" | `working/plans/`, `working/specs/`, `working/milestones/`, `summary.md`, `pm-analysis.md` | correct and expected |
+
+A completed plan *should* be stale — it is a record. It only becomes a problem when nothing tells a
+reader it is a record. `milestones/milestone-2.md` opens by describing a Leaflet `/map` page in
+confident present tense with no date qualifier.
+
+## Approach
+
+Two mechanisms, combined:
+
+**A — one authoritative supersession ledger.** `docs/reference/superseded-decisions.md` records every
+reversal in one table: what was planned, where it was planned, what is true now, when it changed, and
+why. This answers "what did I change my mind about?" in a single place, which is the question a
+review actually asks.
+
+**B — inline notes at the point of staleness.** Every superseded section carries a
+`> **Superseded …**` blockquote where the stale claim sits, so the claim can never be read
+un-corrected. This pattern is not invented here — `docs/reference/architecture.md` and
+`docs/guides/trip-switching.md` already use `> History:` and `> **Changed 2026-07:**` notes.
+
+A alone has an indirection problem (a pointer you may not follow). B alone has a completeness problem
+(no changelog view, and coverage is only as good as the annotation pass). Together each covers the
+other's gap.
+
+### Scope, split by tense
+
+- **Present-tense docs are corrected against the code.** The code is the source of truth. Every
+  factual claim was verified by reading the code, config, or `Makefile` — not inferred.
+- **Past-tense docs are annotated only, never rewritten.** 41 plans and 25 specs, ~30k lines. Their
+  `✅ Complete` trailing notes are good records; rewriting them would destroy the audit trail and is
+  unbounded work.
+- **Code-side inconsistencies are logged, not fixed.** Mixing behaviour changes into a documentation
+  diff would make it unreviewable. They go to
+  `docs/working/2026-07-25-doc-drift-recommendations.md` for a separate decision.
+
+### Out of scope
+
+- A repeatable drift check (script with an exit code). Deliberately deferred — the owner asked for the
+  one-time reconciliation first. It is the lead recommendation in the recommendations doc.
+- Fixing the `travel-memories` / `docker-compose.yml` breakage, the unused
+  `shortcode-gallery-plusplus`, and the `italy-2025` demo fixtures. All logged as recommendations.
+
+## Verification
+
+Claims were checked against, not assumed from:
+
+| Claim area | Verified against |
+|---|---|
+| Nav labels | `templates/partials/base.html.twig:27-31` |
+| Template + partial inventory | `ls templates/`, `ls templates/partials/` |
+| Asset sources → outputs | `user/themes/intotheeast/package.json` build script |
+| `css-compiled/` provenance | CSS imports in `js/src/*.js`; `assets.addCss` in `base.html.twig:7-8` |
+| Design tokens | `css/tokens.css` |
+| Light mode | absence of `prefers-color-scheme` / `data-theme` and of light hex values in `css/` |
+| Photo field rules | `user/pages/02.post/post-form.md:35-46` |
+| `hero_image` removal | `post-form.md:149-151` |
+| `entry-actions` routes | `user/plugins/entry-actions/entry-actions.php:63-73` |
+| `make` targets + env guard | `Makefile` (`guard-env:41-43`, `make-env-target:45-46`) |
+| `travel-memories` removal | `git log -- services/` → `a80b0a9`; `docker compose build` failure |
+| Plan status vs reality | `user/` HEAD `dd19995` |
+
+The `user/` submodule was moved off the outer repo's pin to its real HEAD (`dd19995`) before
+auditing, because the pin lagged and would have produced findings against a state that is no longer
+current.