# Recommendations from the 2026-07-25 documentation reconciliation

**Status:** 📋 Proposed — nothing here has been acted on. Decide per item.

The reconciliation pass (see [`specs/2026-07-25-docs-reconciliation-design.md`](specs/2026-07-25-docs-reconciliation-design.md))
corrected the documentation. It also surfaced problems that are **not** documentation problems, plus
process changes that would stop this drift recurring. Those are collected here rather than mixed into
a docs diff.

Ordered by what I would do first.

---

## P1 — `make start` and `make setup` are broken on any clean checkout

**What.** `docker-compose.yml` still declares a `travel-memories` service with
`build: ./services/travel-memories`. That source was removed in `a80b0a9` ("moved to separate
project") and `services/` is gitignored, so the build context does not exist. `make start` is
`docker compose up -d` (all services), and `make setup` calls it.

**Proof.**
```
$ docker compose build travel-memories
unable to prepare context: path ".../services/travel-memories" not found
```

**Why it has stayed hidden.** A machine that built the image before `a80b0a9` still has
`travel-blog-intotheeast-travel-memories:latest` cached, so `docker compose up -d` reuses it and never
rebuilds. It breaks for a fresh clone, for every new worktree (different `COMPOSE_PROJECT_NAME` →
different image name → forced rebuild), and on the main checkout after any `docker image prune`. This
is why `make worktree-new` calls `start-grav`, not `start`.

**Options.**
1. **Delete the service from `docker-compose.yml`** (recommended). It lives in another project now. If
   that project needs to run alongside Grav, it can carry its own compose file.
2. Move it into a compose profile (`profiles: [tools]`) so `docker compose up -d` skips it by default.
3. Keep it and point `build` at the new location — only if you actually want the two coupled again.

Until this is decided, `CLAUDE.md` and `README.md` now warn to use `make start-grav`. That is a
signpost around a bug, not a fix.

---

## P2 — A repeatable drift check

Deliberately out of scope for the one-time pass; this is the item that stops the whole problem
recurring. Every defect found was mechanically checkable — a route, a path, a token name, a make
target, a field rule.

**Proposal.** A `make docs-check` target that fails loudly when the present-tense docs assert
something the code contradicts:

- Grep `CLAUDE.md`, `docs/reference/`, `docs/guides/`, `README.md`, `CONCEPTS.md` for references to
  retired routes (`/map`, `/stats`, `/tracker`, `/dailies`, `/stories`) and dead tech (`Leaflet`).
  These are already forbidden by `CLAUDE.md`, so any hit is a defect.
- Assert every `templates/*.html.twig` and `templates/partials/*.html.twig` named in
  `architecture.md` exists, and flag templates that exist but are undocumented. Both directions of
  drift were present this pass.
- Diff the `--color-*` token names in `design-system.md` against `css/tokens.css`. Six were missing.
- Assert every `make <target>` mentioned in `README.md` is a real target, **and** that no bare
  `remote-*` target is documented without an env suffix. This alone would have caught P4.
- Assert file paths cited in `CLAUDE.md` exist. A prior pass shipped a path to
  `js/src/maplibre-utils.js`, which never existed.

Deliberately **excluded**: `docs/working/`. Those documents are records and are supposed to drift;
scanning them would produce permanent noise.

Sequence this after P1 — otherwise the first thing the check reports is P1.

---

## P3 — Plan status can silently lag a merge

`plans/2026-07-23-post-form-location-override.md` read `📋 Not started` while the feature was merged
in `user/` as `dd19995`. Nothing connects a plan's status line to the commit that lands it, so the
convention depends entirely on remembering.

**Options.**
1. **Add the plan path to the feature's commit or PR body**, so `git log --grep` can find plans whose
   work landed but whose status never moved. Cheapest, no tooling.
2. Extend the P2 check: for each plan not `✅ Complete`/`❌ Abandoned`, look for a merged branch whose
   name matches the plan slug and warn. Catches it automatically; some false positives.
3. Accept it and rely on the convention. Reasonable — this was one miss across 41 plans.

---

## P4 — `README.md` was designated authoritative for a list it did not hold

`CLAUDE.md`'s entry-point table sends readers to `README.md` for "the full `make` command list".
Before this pass, README documented 7 of ~20 `remote-*` targets, and documented all of them **without
the `-test`/`-prod` suffix that `guard-env` requires** — so its server runbook was not executable.

Corrected now, but the structural point stands: **a doc promoted to "the authoritative list of X"
acquires a completeness obligation it did not have as prose.** The `Makefile` is the real source of
truth. Consider either generating the command tables from `Makefile` comments, or softening the
CLAUDE.md pointer to "common commands" and letting `make help` be authoritative.

Related: `docs/guides/deploy-cycle.md` had the env-suffix rule right the whole time. The defect was
README duplicating the same knowledge and drifting. Fewer copies would have prevented it.

---

## P5 — `shortcode-gallery-plusplus` is installed with no consumer

`plugins.txt` lists it, but there is no `[gallery]` shortcode anywhere in `templates/` or `pages/`.
Entry galleries are PhotoSwipe, wired in `js/src/main.js` against `.pswp-gallery` markup from
`partials/entry-journal.html.twig`.

**Careful before removing it.** `plugins.txt` does **not** list `shortcode-core`, which is present as
a GPM dependency — and `story-blocks` needs `shortcode-core`. Dropping
`shortcode-gallery-plusplus` could take `shortcode-core` with it and break stories.

**Recommendation.** Add `shortcode-core` to `plugins.txt` as an explicit, first-class dependency
*first*, then remove `shortcode-gallery-plusplus` and verify a story page still renders. Do not do
these in one step.

---

## P6 — Demo fixtures still contain retired views

`user/docs/demo/trips/italy-2025/` ships `map.md`, `stats.md` and `stories.md` — pages for views
retired on 2026-07-04. The newer `italy-2026-demo` fixture has no `map.md`/`stats.md`, so the fixtures
disagree with each other.

Low impact (demo trips are gitignored in the pages tree and loaded on demand), but `make demo-load`
copies them in, so a demo trip can materialise pages for views that no longer exist. Delete
`map.md` and `stats.md` from `italy-2025`; keep `stories.md` only if the container is still needed.

This is a `user/` submodule change, which is why it was left out of this pass.

---

## P7 — Structural notes worth a decision

**`design-system-light.md` is a record, not a reference.** It documents an unimplemented palette and
now carries a banner saying so, but it still sits in `reference/` — the "stable facts" tier. Moving it
to `docs/working/` would make its status structural rather than dependent on a reader seeing the
banner. Counter-argument: it is the natural starting point if a light theme is ever built, and
`reference/` is where someone would look. Either is defensible; the banner makes it safe for now.

**`milestone2-template-refactor-brief.md` sits loose in `docs/working/`** while the milestone docs live
in `working/milestones/`. Cosmetic, but it is the kind of thing that makes a folder stop being
self-explanatory.

**The `summary.md` lesson generalises.** The single most misleading line in the tree was
`working/README.md` advertising `summary.md` as "current state". A stale document is survivable; an
*index* that points at a stale document as authoritative is not, because it defeats the reader's
judgement. Worth remembering the next time an index gets written: **describing a document's role is
itself a factual claim that can rot.**