Compare commits
4
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
  m038andClaude Opus 5
|
086c36d157 | ||
|
m038andClaude Opus 5
|
7c9c140a1b | ||
|
m038andClaude Opus 5
|
d946eaaa7e | ||
|
m038andClaude Opus 5
|
8202d2a257 |
@@ -6,9 +6,10 @@ Rules, gotchas, and entry points — the things that must change what you do *be
|
||||
|---|---|
|
||||
| How the site hangs together — stack, plugin roles, templates, partial contracts, data flows | [`docs/reference/architecture.md`](docs/reference/architecture.md) |
|
||||
| Domain vocabulary — Trip, Entry, Story, Active Trip | [`CONCEPTS.md`](CONCEPTS.md) |
|
||||
| Doing something operational — posting, writing stories, GPX, switching trips, local setup, deploying | [`docs/guides/`](docs/guides/) |
|
||||
| Doing something operational — posting, GPX, switching trips, local setup, deploying | [`docs/guides/`](docs/guides/) |
|
||||
| Test suite layout and conventions | [`docs/reference/testing.md`](docs/reference/testing.md) |
|
||||
| A bug or workflow trap already hit and written up | [`docs/solutions/`](docs/solutions/) — grep the `module`/`tags`/`problem_type` frontmatter; check when working in a documented area |
|
||||
| Why an old plan describes something that no longer exists | [`docs/reference/superseded-decisions.md`](docs/reference/superseded-decisions.md) — check before re-creating anything found in `docs/working/` |
|
||||
| Folder map, prerequisites, the full `make` command list | [`README.md`](README.md) |
|
||||
|
||||
The site is Grav (flat-file PHP CMS, no database) in Docker, with content and theme in the `user/` submodule.
|
||||
@@ -20,13 +21,13 @@ The site is Grav (flat-file PHP CMS, no database) in Docker, with content and th
|
||||
- **Never SSH to a server directly** — use the `make remote-*` targets, since credentials live in `.env`. If no target covers what you need, ask the user to run it or propose a new target.
|
||||
- **Never hand-edit build output** — sources and outputs share folders under `user/themes/intotheeast/` (paths below are relative to it), so know which is which. Run `make build-assets` after editing any source.
|
||||
- Everything in `js/` is **generated** *except* `js/src/`, `js/maplibre-utils.js` and `js/nav.js`.
|
||||
- `css-compiled/` and `fonts/` are generated by esbuild from the `js/src/` entrypoints' CSS and font imports (fontsource, photoswipe, maplibre-gl) — **not** from `css/`. `css/style.css` and `css/tokens.css` are hand-authored and served directly (`partials/base.html.twig`), so editing them needs no rebuild.
|
||||
- `templates/partials/weather-icons.html.twig` is generated (source: `scripts/gen-weather-icons.js`).
|
||||
- `css-compiled/` and `fonts/` are **esbuild output from the imports inside `js/src/`** — *not* from `css/`. Everything in `css/` is hand-authored and served directly (`assets.addCss` in `partials/base.html.twig`), never compiled. So `templates/partials/weather-icons.html.twig` is also generated (source: `scripts/gen-weather-icons.js`).
|
||||
- **Never toggle dev↔prod mode mid-session.** If a caching or config issue appears, fix it at the application level (plugin, template logic) rather than flipping a mode flag — mode switches leave inconsistent state and make bugs harder to reproduce.
|
||||
|
||||
## Dev environment
|
||||
|
||||
- Dev server: **http://localhost:8081** (`make setup` on a first run, `make start` / `make stop` after). A second service, `travel-memories`, runs on :8082. A worktree gets its own container and port `8090+` from its `.worktree-env` — pass `GRAV_BASE_URL` when pointing tests at one.
|
||||
- Dev server: **http://localhost:8081** (`make setup` on a first run, `make start` / `make stop` after). A worktree gets its own container and port `8090+` from its `.worktree-env` — pass `GRAV_BASE_URL` when pointing tests at one.
|
||||
- ⚠️ **`make start` / `make setup` fail on a clean checkout** — `docker compose up -d` still tries to build a `travel-memories` service whose source was moved out of this repo, so the build context is missing. Use **`make start-grav`** (Grav only). Existing containers keep working from a cached image, which is why this hides until a rebuild.
|
||||
- `user/config/system.yaml` is committed with **dev** values (`twig.cache: false`), so templates recompile per request and no cache flush is needed after editing a `.html.twig`. Prod values live in `deploy/env/prod/system.yaml` and **never** in `user/config/`.
|
||||
- ⚠️ **Once `user/env/<hostname>/` exists on a server, Grav's Admin saves ALL config there** — system *and* plugin. So (a) config edited via Admin on the server is server-only and silently never reaches Gitea or local; (b) when reading or writing server config, check **both** `user/config/…` and `user/env/<host>/config/…` — **env wins**, so look there first. Mechanics: [`docs/guides/deploy-cycle.md`](docs/guides/deploy-cycle.md).
|
||||
- The Admin plugin slug is **`admin2`**, not `admin`.
|
||||
|
||||
+18
@@ -48,6 +48,24 @@ A server's per-host configuration overlay. Once it exists, Grav's Admin writes *
|
||||
### Remote-only plugin
|
||||
One of the project's three plugin-management categories, alongside GPM-managed (declared in the shared install list and restored by the standard install flow) and custom-in-repo (code tracked in the Content repo). A Remote-only plugin is installed explicitly on servers and restored by **no** standard flow — if its code goes missing it stays missing until someone reinstalls it deliberately, even while its configuration persists in the Env tree.
|
||||
|
||||
## Documentation
|
||||
|
||||
### Historical record
|
||||
A document that states what was decided or built at a past moment, not what is true now — plans, specs, milestone scopes, and session write-ups. Its going out of date is expected and is what makes it a record; it is corrected only by annotation, never by rewriting, because the value is the reasoning at the time.
|
||||
|
||||
Distinguished from *current documentation*, which asserts how the system is today and is simply wrong when it drifts. A Historical record often reads in present tense, so the distinction is carried by an explicit marker rather than by tone.
|
||||
|
||||
### Superseded decision
|
||||
Something the project planned or built and then deliberately reversed, recorded so the reversal is discoverable from the document that still describes the original. Each one names what was planned, what replaced it, when, and why.
|
||||
|
||||
The record exists because a reversal is otherwise invisible: the old document keeps asserting the old thing, and the reasoning that killed it lives only in whoever remembers. A Superseded decision is the standing answer to "may I re-create this?" — usually no, and often the prohibition is also a hard rule.
|
||||
|
||||
### Plan status
|
||||
The single recorded state of a plan, carried on the plan itself rather than in a separate tracker. **Deferred** and **Abandoned** are deliberately distinct: Deferred means still wanted but not now, Abandoned means decided against, kept so the decision is not re-litigated.
|
||||
|
||||
A status that lags reality is worse than no status, because it is trusted — so it moves when the work lands, not later.
|
||||
|
||||
## Flagged ambiguities
|
||||
|
||||
- "daily" / "entry" / "journal post" all refer to the same concept (a dated journal post). Canonical term: **Entry**. The section/folder is named "dailies" and the nav label is "Journal" — these name the *collection*, not a different entity.
|
||||
- A **Historical record** written in present tense is **not** a claim about the current system. Staleness there is correct; staleness in current documentation is a defect. When the two disagree, the code decides, and the gap is recorded as a **Superseded decision**.
|
||||
|
||||
@@ -27,7 +27,7 @@ Two git repos:
|
||||
| `tests/` | Playwright suite — see [`docs/reference/testing.md`](docs/reference/testing.md) |
|
||||
| `php/` | Local PHP ini overrides |
|
||||
| `docs/` | All project documentation — start at [`docs/README.md`](docs/README.md) |
|
||||
| `docs/guides/` | Operational how-tos (posting, story authoring, GPX, trip switching, setup, deploy cycle) |
|
||||
| `docs/guides/` | Operational how-tos (posting, GPX, trip switching, setup, deploy cycle) |
|
||||
| `docs/reference/` | Stable facts: architecture, design system, testing |
|
||||
| `docs/solutions/` | Write-ups of bugs and workflow traps already hit, with YAML frontmatter (`module`, `tags`, `problem_type`) |
|
||||
| `docs/working/` | Specs, plans, backlog, QA — work in flight |
|
||||
@@ -49,16 +49,22 @@ Two git repos:
|
||||
|
||||
```bash
|
||||
cp .env.example .env # fill in your values — never commit this file
|
||||
make setup # start Docker container and install plugins
|
||||
git submodule update --init user
|
||||
mkdir -p user/plugins user/data
|
||||
make build && make start-grav && make install-plugins && make fix-perms
|
||||
```
|
||||
|
||||
Site runs at http://localhost:8081.
|
||||
|
||||
Clone the user content repo into `user/` if not already present:
|
||||
`user/` is a **git submodule** — initialise it with `git submodule update --init user`. Do not
|
||||
`git clone` into `user/` by hand; that detaches it from the pin the outer repo tracks.
|
||||
|
||||
```bash
|
||||
git clone $USER_REPO user/
|
||||
```
|
||||
> ⚠️ **Use `make start-grav`, not `make setup`, on a clean checkout.** `make setup` runs `make start`
|
||||
> (`docker compose up -d`), which still tries to build the `travel-memories` service — but its source
|
||||
> was moved to a separate project (`a80b0a9`) and `services/` is gitignored, so the build context is
|
||||
> missing and the command fails. `make start-grav` brings up Grav only. Machines with a cached
|
||||
> `travel-memories` image will not see this until their next rebuild. See
|
||||
> [`docs/reference/superseded-decisions.md`](docs/reference/superseded-decisions.md) → R11.
|
||||
|
||||
---
|
||||
|
||||
@@ -69,12 +75,12 @@ git clone $USER_REPO user/
|
||||
**2. Run the install:**
|
||||
|
||||
```bash
|
||||
make remote-install
|
||||
make remote-install-prod # or -test
|
||||
```
|
||||
|
||||
This SSHes into the server, downloads Grav, clones both repos (user content + this config repo), installs plugins, and prints the server's SSH public key.
|
||||
|
||||
**3. Add the SSH key to Gitea** — copy the printed public key and add it as a read-only deploy key to both Gitea repos. After this, `make remote-fetch` works without credentials.
|
||||
**3. Add the SSH key to Gitea** — copy the printed public key and add it as a read-only deploy key to both Gitea repos. After this, `make remote-fetch-prod` works without credentials.
|
||||
|
||||
---
|
||||
|
||||
@@ -101,8 +107,9 @@ make content-push # push local user/ commits → Gitea
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make setup` | First run: build → start → install plugins → fix perms |
|
||||
| `make start` | Start the local Docker container |
|
||||
| `make setup` | First run: build → start → install plugins → fix perms. ⚠️ Currently fails on a clean checkout — see the setup note above; use the `start-grav` sequence instead |
|
||||
| `make start` | Start **all** compose services. ⚠️ Fails where `services/travel-memories` is absent |
|
||||
| `make start-grav` | Start the Grav service only — the reliable option |
|
||||
| `make stop` | Stop the local Docker container |
|
||||
| `make install-plugins` | (Re)install plugins from plugins.txt, then apply local plugin patches |
|
||||
| `make apply-plugin-patches` | Idempotently re-apply the patches in `deploy/patches/` |
|
||||
@@ -137,35 +144,67 @@ Details and conventions: [`docs/reference/testing.md`](docs/reference/testing.md
|
||||
| `make worktree-new NAME=<feature>` | Create a worktree with its own `user/` checkout and an isolated dev server on port `8090+` |
|
||||
| `make worktree-rm NAME=<feature>` | Tear one down cleanly (compose down → submodule deinit → worktree remove → prune) |
|
||||
|
||||
### Remote credentials
|
||||
### Remote targets — every one needs an environment suffix
|
||||
|
||||
> **All `remote-*` targets require `-test` or `-prod`.** A bare `make remote-fetch` fails via
|
||||
> `guard-env` with *"no environment. Use an env-suffixed target"*. The suffixed variants are generated
|
||||
> by a macro in the `Makefile`, so they will not show up in a grep for literal target names.
|
||||
|
||||
The runbook for shipping a change through test → prod is
|
||||
[`docs/guides/deploy-cycle.md`](docs/guides/deploy-cycle.md). The tables below are the inventory.
|
||||
|
||||
**Credentials** — always run `remote-env-remove-<env>` when done; credentials must not persist on the server.
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make remote-env-setup` | Write Gitea credentials to `~/.env-intotheeast` on the server |
|
||||
| `make remote-env-remove` | Delete `~/.env-intotheeast` from the server |
|
||||
| `make remote-env-setup-<env>` | Write Gitea credentials to `~/.env-intotheeast` on the server |
|
||||
| `make remote-env-remove-<env>` | Delete `~/.env-intotheeast` from the server |
|
||||
| `make remote-secrets-audit-<env>` | Check the server for exposed secrets |
|
||||
| `make remote-seed-api-salt-<env>` | Generate the API/CSRF salt on the server |
|
||||
|
||||
Always run `make remote-env-remove` when done. Credentials must not persist on the server.
|
||||
|
||||
### Remote server management
|
||||
**Install and sync**
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make remote-install` | First-time install: download Grav, clone both repos, install plugins |
|
||||
| `make remote-fetch` | Pull latest config repo (Makefile, scripts, plugins.txt) on the server |
|
||||
| `make remote-install-plugins` | Install/update plugins from local plugins.txt on the server |
|
||||
| `make remote-upgrade-grav` | Upgrade Grav core on the server |
|
||||
| `make remote-clean` | Clear Grav cache on the server |
|
||||
| `make remote-maintenance-on` | Enable maintenance mode (visitors see offline page) |
|
||||
| `make remote-maintenance-off` | Disable maintenance mode |
|
||||
| `make remote-install-<env>` | First-time install: download Grav, clone both repos, install plugins |
|
||||
| `make remote-fetch-<env>` | Pull latest config repo (Makefile, scripts, plugins.txt) on the server |
|
||||
| `make remote-fetch-content-<env>` | Pull latest `user/` content on the server |
|
||||
| `make remote-content-status-<env>` | Show the server's content-repo state |
|
||||
| `make remote-apply-env-<env>` | Apply `deploy/env/<env>/` config into the server's env tree — **re-run after any fresh install** |
|
||||
| `make remote-apply-plugin-patches-<env>` | Re-apply `deploy/patches/` on the server |
|
||||
|
||||
**Plugins and core**
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make remote-install-plugins-<env>` | Install plugins from local plugins.txt on the server |
|
||||
| `make remote-update-plugins-<env>` | Update installed plugins via GPM |
|
||||
| `make remote-gpm-install-<env>` | Install a single plugin via GPM |
|
||||
| `make remote-upgrade-grav-<env>` | Upgrade Grav core on the server (in place — servers have no image) |
|
||||
|
||||
**Operations**
|
||||
|
||||
| Command | Description |
|
||||
|---------|-------------|
|
||||
| `make remote-clean-<env>` | Clear Grav cache on the server |
|
||||
| `make remote-warmup-<env>` | Clear **and warm** the cache after a deploy |
|
||||
| `make remote-maintenance-on-<env>` | Enable maintenance mode (visitors see offline page) |
|
||||
| `make remote-maintenance-off-<env>` | Disable maintenance mode |
|
||||
| `make remote-diag-<env>` | Diagnostics on the server |
|
||||
| `make remote-git-sync-enable-<env>` / `-disable-<env>` | Toggle the remote-only git-sync plugin |
|
||||
| `make remote-wipe-<env>` | ⚠️ Destroy the server install |
|
||||
|
||||
### Typical upgrade workflow
|
||||
|
||||
Run against `test` first — it is a full dress rehearsal of prod.
|
||||
|
||||
```bash
|
||||
make remote-maintenance-on
|
||||
make remote-upgrade-grav
|
||||
make remote-install-plugins
|
||||
make remote-clean
|
||||
make remote-maintenance-off
|
||||
make remote-maintenance-on-prod
|
||||
make remote-upgrade-grav-prod
|
||||
make remote-install-plugins-prod
|
||||
make remote-apply-env-prod # env tree is not restored by anything else
|
||||
make remote-warmup-prod
|
||||
make remote-maintenance-off-prod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
+6
-1
@@ -15,9 +15,14 @@
|
||||
|
||||
**Design or architecture decisions?** → [`reference/`](reference/)
|
||||
- [Design system](reference/design-system.md)
|
||||
- [Architecture overview](reference/architecture.md)
|
||||
- [Architecture overview](reference/architecture.md) — the site as it actually is
|
||||
- [Superseded decisions](reference/superseded-decisions.md) — what was planned, then reversed, and why
|
||||
- [Testing](reference/testing.md)
|
||||
|
||||
> Documents under [`working/`](working/) are historical records. If one describes something that no
|
||||
> longer exists, [`reference/superseded-decisions.md`](reference/superseded-decisions.md) says what
|
||||
> replaced it.
|
||||
|
||||
---
|
||||
|
||||
## If you're Claude
|
||||
|
||||
+72
-17
@@ -1,18 +1,23 @@
|
||||
# Posting a Journal Entry
|
||||
|
||||
Two ways to post: the **mobile form** at `/post` (quick, phone-friendly) or the **Admin panel** at `/admin` (drafts, scheduling, editing).
|
||||
Two ways to post: the **mobile form** at `/post` (quick, phone-friendly) or the **Admin panel** at `/admin` (scheduling, bulk edits). The `/post` form also **edits** existing entries — see below.
|
||||
|
||||
---
|
||||
|
||||
## Quick start — mobile form
|
||||
|
||||
1. Open `/post` on your phone (login required)
|
||||
2. Fill in **Title** and **Content** (required)
|
||||
3. Tap **Get Location** → fills Lat/Lng automatically
|
||||
4. Tap **Get Weather** → fills weather fields using your coordinates
|
||||
5. Type **City** and **Country** (optional but nice)
|
||||
6. Attach photos (optional) — first photo becomes the hero image
|
||||
7. Tap **Submit** → entry appears in the feed immediately
|
||||
2. **Attach 1–6 photos** — photos come first because they anchor what you write. **At least one is required**; the form collapses them into a summary bar once uploaded
|
||||
3. Fill in **Title** and **Content** (required)
|
||||
4. Tap **Get Location** → fills Lat/Lng, then reverse-geocodes City + Country for you
|
||||
5. Tap **Get Weather** → fills weather fields using those coordinates
|
||||
6. Optional: open **More location details** to search for a place by name, or drag the pin on the map to place it exactly
|
||||
7. Optional: open **More options** for transport mode, publish state, connector and highlight toggles
|
||||
8. Tap **Submit** → entry appears in the feed immediately
|
||||
|
||||
> **Photos are mandatory (1–6).** This changed during the 2026-07 post-form work — an entry with no
|
||||
> photo will not submit. The first photo in the grid is the hero; reorder by dragging to change it.
|
||||
> See [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md) → R7, R8.
|
||||
|
||||
---
|
||||
|
||||
@@ -20,14 +25,20 @@ Two ways to post: the **mobile form** at `/post` (quick, phone-friendly) or the
|
||||
|
||||
| Field | Required | Notes |
|
||||
|---|---|---|
|
||||
| Photos | ✅ | **1–6 per entry.** HEIC is converted to JPEG in the browser. First photo = hero; drag to reorder |
|
||||
| Title | ✅ | Entry headline |
|
||||
| Content | ✅ | Markdown body |
|
||||
| Date | ✅ | Defaults to now — adjust if posting later |
|
||||
| Lat / Lng | — | Filled by Get Location; used for map marker |
|
||||
| City | — | Shown as `📍 Kyoto, Japan` on feed cards |
|
||||
| Country | — | Combined with City in location badge |
|
||||
| Lat / Lng | — | Filled by Get Location, by place search, or by dragging the map pin |
|
||||
| City | — | Auto-filled by reverse geocoding after Get Location; shown as `📍 Kyoto, Japan` on feed cards |
|
||||
| Country | — | Combined with City in the location badge |
|
||||
| Weather | — | Filled by Get Weather (Open-Meteo, free, no key) |
|
||||
| Photos | — | All uploaded files appear in the gallery; first = hero |
|
||||
| How I got here | — | `transport_mode`: walking · bicycle · bus · train · car · plane |
|
||||
| Published | — | Advanced. Default **Yes**. Set No to keep a draft, or to unpublish on edit |
|
||||
| Force connector line | — | Advanced. Default No. Forces a map connector to this entry even when suppressed |
|
||||
| Featured highlight | — | Advanced. Default No. Opts the entry into the home highlights grid |
|
||||
|
||||
The advanced three sit behind **More options**. There is **no `hero_image` field** — see the note above.
|
||||
|
||||
**Weather descriptions** (must be one of these if entered manually):
|
||||
`Sunny` · `Partly cloudy` · `Cloudy` · `Foggy` · `Drizzle` · `Rain` · `Snow` · `Thunderstorm`
|
||||
@@ -40,8 +51,9 @@ Two ways to post: the **mobile form** at `/post` (quick, phone-friendly) or the
|
||||
Browser → /post (post-form.md)
|
||||
└─ Grav Form plugin validates fields
|
||||
└─ cache-on-save injects parent from site.active_trip
|
||||
└─ add-page-by-form plugin
|
||||
├─ writes user/pages/01.trips/<active_trip>/01.dailies/<slug>/entry.md
|
||||
└─ and sets overwrite_mode: edit when edit_path is filled, else false
|
||||
└─ add-page-by-form plugin (patched — see deploy/patches/)
|
||||
├─ writes user/pages/01.trips/<active_trip>/01.dailies/<slug>.entry/entry.md
|
||||
└─ moves uploaded photos into the page folder
|
||||
└─ cache-on-save plugin
|
||||
└─ calls $grav['cache']->deleteAll() → entry visible immediately
|
||||
@@ -56,15 +68,21 @@ Example: `2026-07-20-0930-first-day-in-kyoto.entry`
|
||||
user/pages/01.trips/denmark-2026/01.dailies/
|
||||
└─ 2026-07-20-0930-first-day-in-kyoto.entry/
|
||||
├─ entry.md ← frontmatter + markdown body
|
||||
├─ temple.jpg ← hero image (or set hero_image in frontmatter)
|
||||
└─ market.jpg ← additional gallery image
|
||||
├─ photo-01.jpg ← first in order, so this is the hero
|
||||
└─ photo-02.jpg ← additional gallery image
|
||||
```
|
||||
|
||||
Photos are stored as `photo-01…NN` in display order — the numbering *is* the order, so reordering in
|
||||
the form renames files on disk, and `photo-01` is always the hero. Names are **zero-padded** so
|
||||
lexical sort matches numeric order (otherwise `photo-1, photo-10, photo-2…`); the pad width grows for
|
||||
100+ photos. `PhotoRenumberer` in `cache-on-save` is the single source of truth for this invariant and
|
||||
is shared with `entry-actions`.
|
||||
|
||||
---
|
||||
|
||||
## Admin panel — drafts and scheduling
|
||||
|
||||
Use the Admin panel at `/admin` for drafts, scheduled posts, or editing existing entries.
|
||||
Use the Admin panel at `/admin` for **scheduling** (`publish_date`) and bulk or structural edits. For ordinary edits — text, photos, location, publish state — the `/post` form is quicker; see [Editing an entry](#editing-an-entry).
|
||||
|
||||
1. Log in at `/admin`
|
||||
2. **Pages → Add Page**
|
||||
@@ -96,7 +114,36 @@ Every entry supports these frontmatter fields:
|
||||
| `location_country` | string | e.g. `Japan` |
|
||||
| `weather_desc` | string | One of the allowed values above |
|
||||
| `weather_temp_c` | number | Celsius, displayed rounded |
|
||||
| `hero_image` | string | Filename to pin as hero (e.g. `temple.jpg`); auto-selects first image if blank |
|
||||
| `transport_mode` | string | `walking` · `bicycle` · `bus` · `train` · `car` · `plane` |
|
||||
| `force_connect` | bool | Force a map connector line to this entry even where it would be suppressed |
|
||||
| `featured` | bool | Opt into the home page highlights grid |
|
||||
|
||||
> **No `hero_image` on journal entries.** The hero is whichever photo sorts first
|
||||
> (`entry-journal.html.twig` uses `entry.media.images|first`), which the owner controls by
|
||||
> reordering photos. **Stories still use `hero_image`** — they are not posted through this form.
|
||||
> See [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md) → R7.
|
||||
|
||||
---
|
||||
|
||||
## Editing an entry
|
||||
|
||||
The `/post` form doubles as the editor — you do not need Admin for ordinary edits.
|
||||
|
||||
1. Open the entry (or find it in the feed) while logged in
|
||||
2. Use the entry's **Edit** action → `/post` opens pre-filled, with the hidden `edit_path` set to that
|
||||
entry's path
|
||||
3. Existing photos load into the grid. You can **add**, **remove**, and **drag to reorder** them
|
||||
4. Submit → `cache-on-save` sets `overwrite_mode: edit`, so the entry is rewritten **in place**
|
||||
rather than creating a new dated folder
|
||||
|
||||
Photo files on disk are renumbered to `photo-1…N` to match the displayed order, so the first photo is
|
||||
always the hero. Reordering is a real file rename, handled server-side by `PhotoRenumberer` in the
|
||||
`entry-actions` plugin via `POST /api/v1/entry/{slug}/photos/order`.
|
||||
|
||||
To **unpublish** an entry, edit it and set **Published** to No under *More options*.
|
||||
|
||||
Deleting an entry is also an entry action (`DELETE /api/v1/entry/{slug}`), owner-only and scoped to
|
||||
the active trip.
|
||||
|
||||
---
|
||||
|
||||
@@ -111,5 +158,13 @@ Every entry supports these frontmatter fields:
|
||||
**Photos not showing in gallery**
|
||||
→ Verify files were uploaded (check the entry folder in Admin → Media). Only jpg, jpeg, png, webp, gif are rendered.
|
||||
|
||||
**Submit button does nothing**
|
||||
→ Check you have at least one photo attached, and that every upload has finished. The form blocks
|
||||
submit while an upload is still in flight, and requires 1–6 photos.
|
||||
|
||||
**500 error after posting**
|
||||
→ Run `make fix-perms` to restore container file ownership.
|
||||
|
||||
**Edits create a new entry instead of updating**
|
||||
→ The hidden `edit_path` was empty, so `overwrite_mode` fell back to `false`. Re-enter via the entry's
|
||||
Edit action rather than opening `/post` directly.
|
||||
|
||||
@@ -1,228 +0,0 @@
|
||||
# Writing a Story
|
||||
|
||||
A Story is a long-form, hand-crafted piece with an immersive layout — distinct from an Entry, which is a quick dated post from the road (see [`CONCEPTS.md`](../../CONCEPTS.md)). Stories get a Ken Burns hero, scroll-driven sections, galleries and pull quotes.
|
||||
|
||||
The admin editor gives you a **plain markdown textarea** for the body. There is no block picker — the layout vocabulary is a set of shortcodes you type by hand. This guide is that vocabulary; the story edit form also carries a condensed copy of it on its **Blocks** tab, so you don't need this file open while writing.
|
||||
|
||||
Admin lives at **`/admin`** (the plugin slug is `admin2`, but the route is `/admin`). A story's edit URL looks like `/admin/pages/edit/trips/<trip>/stories/<slug>`.
|
||||
|
||||
Stories live at:
|
||||
|
||||
```
|
||||
user/pages/01.trips/<trip>/04.stories/<slug>/story.md
|
||||
```
|
||||
|
||||
`04.stories/stories.md` is a `routable: false` container — its children are aggregated onto the trip page. There is no standalone `/stories` view; don't create one.
|
||||
|
||||
---
|
||||
|
||||
## 1. Create the page
|
||||
|
||||
1. Admin → **Pages** → add a page under the trip's **Stories** folder
|
||||
2. Set page template to **story** — this loads [`user/themes/intotheeast/blueprints/story.yaml`](../../user/themes/intotheeast/blueprints/story.yaml). You get the story-specific **Content / Blocks / Location / Publishing** tabs plus the inherited **Options / Advanced / Security** tabs
|
||||
3. Fill in Title and Start Date (both required)
|
||||
|
||||
---
|
||||
|
||||
## 2. Upload the images first
|
||||
|
||||
Upload every image the story needs via the **Images** field at the bottom of the Content tab, before writing the body.
|
||||
|
||||
> There is no separate *Media* tab — the uploader is a field on the Content tab, labelled **Images**. It arrives via inheritance: `story.yaml` declares `'@extends': {type: default, context: blueprints://pages}`, which merges in Grav's default page form. `story.yaml` and `trip.yaml` did not originally extend it, so neither form could upload anything, which is why the demo story images had to be placed on the filesystem. Both now inherit, matching [`entry.yaml`](../../user/themes/intotheeast/blueprints/entry.yaml). `home.yaml` is still standalone, deliberately — the home page has no per-page media.
|
||||
|
||||
Every shortcode refers to images by **bare filename** — the `story-blocks` plugin prefixes the page URL at render time ([`story-blocks.php:22`](../../user/plugins/story-blocks/story-blocks.php)), so you write:
|
||||
|
||||
```
|
||||
image="photo-1.jpg" ✅
|
||||
image="/images/photo-1.jpg" ❌ don't path it
|
||||
```
|
||||
|
||||
The demo stories use a `hero.jpg` / `photo-1.jpg` / `photo-2.jpg` naming convention. Worth copying — it keeps the shortcodes readable.
|
||||
|
||||
---
|
||||
|
||||
## 3. Frontmatter fields
|
||||
|
||||
All of these come from the form tabs, so you rarely type them by hand. Listed here because the body shortcodes are *not* the whole story — the hero in particular is frontmatter, not a tag.
|
||||
|
||||
| Field | Tab | Notes |
|
||||
|---|---|---|
|
||||
| `title` | Content | Required |
|
||||
| `date` | Content | Required. Start date |
|
||||
| `end_date` | Content | Optional — leave blank for a single-day story |
|
||||
| `hero_image` | Content | **The hero. Filename only**, from the Images field. Missing → grey placeholder, story still renders |
|
||||
| `hero_alt` | Content | Falls back to the title if empty |
|
||||
| `location_name`, `location_country` | Location | Shown in the hero meta line and the opener |
|
||||
| `lat`, `lng` | Location | Decimal degrees — places the story marker on the trip map |
|
||||
| `transport_mode` | Location | walking / bicycle / bus / train / car |
|
||||
| `force_connect` | Location | Always draw a connector line from the previous marker |
|
||||
| `published` | Options | Grav's standard toggle, from the inherited form |
|
||||
| `featured` | Publishing | Show as a homepage highlight when not travelling |
|
||||
|
||||
The Ken Burns pan on the hero is automatic — no parameter for it.
|
||||
|
||||
If you hand-write frontmatter, use `date: '2026-09-03'`. Admin2 saves its own serialization (`29-07-2026 19:51`); both parse fine.
|
||||
|
||||
---
|
||||
|
||||
## 4. The body: six shortcodes
|
||||
|
||||
Defined in [`user/plugins/story-blocks/shortcodes/`](../../user/plugins/story-blocks/shortcodes/). Plain prose between them renders as a normal reading column — you don't need a shortcode to write paragraphs.
|
||||
|
||||
### Wrapping tags
|
||||
|
||||
**`scrolly-section`** — text panels scroll over a pinned, slowly panning image. The centrepiece block.
|
||||
|
||||
```
|
||||
[scrolly-section image="hero.jpg" alt="Description of the image" caption="Optional caption"]
|
||||
The first panel. Scrolls into view over the image.
|
||||
|
||||
---
|
||||
|
||||
The second panel. A markdown `---` starts a new panel.
|
||||
[/scrolly-section]
|
||||
```
|
||||
|
||||
Panels are split on the `<hr>` that `---` produces ([`story.html.twig:234`](../../user/themes/intotheeast/templates/story.html.twig)). `caption` is optional. Under `prefers-reduced-motion` all panels render active with no pinning.
|
||||
|
||||
**`pull-quote`** — large extracted quote, optionally over a background image.
|
||||
|
||||
```
|
||||
[pull-quote image="photo-1.jpg" alt="Description of the image"]
|
||||
The quote itself. Markdown works in here.
|
||||
[/pull-quote]
|
||||
```
|
||||
|
||||
Drop `image`/`alt` entirely for the plain no-image variant.
|
||||
|
||||
### Self-closing tags
|
||||
|
||||
Note the ` /]` — these take no content.
|
||||
|
||||
**`chapter-break`** — full-width section transition over a background image.
|
||||
|
||||
```
|
||||
[chapter-break image="photo-1.jpg" title="After Dark" number="II" alt="Description" /]
|
||||
```
|
||||
|
||||
`number` is optional; the demo stories use roman numerals.
|
||||
|
||||
**`snap-gallery`** — swipeable multi-image carousel with dots.
|
||||
|
||||
```
|
||||
[snap-gallery images="hero.jpg,photo-1.jpg" captions="First caption,Second caption" alts="First alt,Second alt" /]
|
||||
```
|
||||
|
||||
⚠️ See the comma gotcha below.
|
||||
|
||||
**`full-bleed`** — single image edge-to-edge, as a visual pause.
|
||||
|
||||
```
|
||||
[full-bleed image="photo-2.jpg" alt="Description" caption="Optional" credit="Optional" /]
|
||||
```
|
||||
|
||||
**`image-caption`** — photo at a chosen width with caption beneath.
|
||||
|
||||
```
|
||||
[image-caption image="photo-2.jpg" alt="Description" caption="Optional" credit="Optional" width="column" /]
|
||||
```
|
||||
|
||||
`width` accepts `column` (default), `full`, `bleed`. Anything else falls back to `column`.
|
||||
|
||||
`full-bleed` and `image-caption` are implemented but not yet used by any story — the demos only exercise the other four.
|
||||
|
||||
---
|
||||
|
||||
## Gotchas
|
||||
|
||||
### snap-gallery splits on commas — captions cannot contain them
|
||||
|
||||
`images`, `captions` and `alts` are each split on `,` and zipped by index. **A comma inside a caption shifts every caption after it.**
|
||||
|
||||
This is already live in the demo content. `04.stories/04.florence-without-a-map/story.md` has:
|
||||
|
||||
```
|
||||
captions="The Arno at noon — greener than expected, the bridges older than you remember,Via dei Servi: …"
|
||||
```
|
||||
|
||||
Two images, but three comma-separated pieces — so slide 1 gets "The Arno at noon — greener than expected", slide 2 gets " the bridges older than you remember", and the Via dei Servi text is silently dropped.
|
||||
|
||||
Use em dashes or semicolons in gallery captions. There is no escaping mechanism.
|
||||
|
||||
### Self-closing tags need the space before `/]`
|
||||
|
||||
`[chapter-break … /]` — not `[chapter-break …/]` or `[chapter-break …]`.
|
||||
|
||||
### A typo'd shortcode fails silently
|
||||
|
||||
An unrecognised tag name or a malformed parameter list renders as literal text or vanishes — no error, no warning. Preview the page after every block; there is no in-editor validation.
|
||||
|
||||
### `---` outside a scrolly-section is just a horizontal rule
|
||||
|
||||
The panel-splitting behaviour only applies *inside* `[scrolly-section]`.
|
||||
|
||||
---
|
||||
|
||||
## Worked example
|
||||
|
||||
The best reference to copy from is [`user/pages/01.trips/italy-2026-demo/04.stories/01.sorano-rock-and-time/story.md`](../../user/pages/01.trips/italy-2026-demo/04.stories/01.sorano-rock-and-time/story.md) — it combines `scrolly-section`, `chapter-break` and `pull-quote` in one story.
|
||||
|
||||
```markdown
|
||||
---
|
||||
title: 'Sorano: Rock and Time'
|
||||
date: '2026-09-03'
|
||||
location_name: Sorano
|
||||
location_country: Italy
|
||||
lat: 42.683
|
||||
lng: 11.715
|
||||
hero_image: hero.jpg
|
||||
hero_alt: Medieval town of Sorano clinging to pale tufa cliffs at dusk
|
||||
published: true
|
||||
---
|
||||
|
||||
Opening prose. Renders as a normal reading column.
|
||||
|
||||
[scrolly-section image="hero.jpg" alt="Sorano seen from the approach road" caption="Sorano — tufa cliff town"]
|
||||
First panel over the pinned image.
|
||||
|
||||
---
|
||||
|
||||
Second panel.
|
||||
[/scrolly-section]
|
||||
|
||||
More prose between blocks.
|
||||
|
||||
[chapter-break image="photo-1.jpg" title="After Dark" number="II" alt="Narrow medieval alley at dusk" /]
|
||||
|
||||
[pull-quote image="photo-1.jpg" alt="Stone alley lit by a single lantern"]
|
||||
A town built on rock, carved from rock, returning slowly to rock.
|
||||
[/pull-quote]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Publish
|
||||
|
||||
1. Set **Published** on the Publishing tab
|
||||
2. Optionally set **Featured highlight** to surface it on the homepage between trips
|
||||
3. Push the content:
|
||||
|
||||
```bash
|
||||
make content-push
|
||||
```
|
||||
|
||||
That commits and pushes `user/` to Gitea, which triggers the production pull. See [`deploy-cycle.md`](deploy-cycle.md).
|
||||
|
||||
---
|
||||
|
||||
## The Blocks tab
|
||||
|
||||
The story edit form has a **Blocks** tab holding a paste-ready example of each shortcode plus the comma warning. It's built from `type: spacer` fields in `story.yaml`, whose `text` admin2 renders as HTML (confirmed against admin2 2.0.12 — see its CHANGELOG entry for issue #91).
|
||||
|
||||
If you edit those fields, note two things: the `text` values are YAML double-quoted scalars, so HTML attribute quotes must be escaped (`\"`) — and `<h4>` is flattened by admin2's CSS reset, which is why the headings use `<strong>` in a styled `<p>` instead. Long `<pre>` content needs `white-space:pre-wrap`, or it overflows underneath the Page Info sidebar.
|
||||
|
||||
---
|
||||
|
||||
## Why it's a raw textarea
|
||||
|
||||
The admin2 story editor is a plain markdown field by design-so-far, not by limitation. Background and the options considered: [`docs/research/story-editing.md`](../research/story-editing.md). Note that its conclusion that admin2 cannot host a custom editor is **out of date** — admin-next ships a plugin field-component surface (`admin-next/fields/{type}.js` + `onApiBlueprintResolved`) that the installed api 1.0.9 / admin2 2.0.12 support. Nobody has built it yet.
|
||||
@@ -14,7 +14,8 @@ How the intotheeast site hangs together.
|
||||
| Container | Docker (`getgrav/grav` base + custom `Dockerfile`) | Grav 2.0 baked in at build time |
|
||||
| PHP session | `session.save_path = /tmp` | Set in `php/php-local.ini` |
|
||||
| Dev URL | http://localhost:8081 | Mapped from container port 80 |
|
||||
| Maps | MapLibre GL JS | Replaced Leaflet; one shared map path (`MapUtils.initEntryMap`) on trip + home |
|
||||
| Maps | MapLibre GL JS | Replaced Leaflet. One shared *display* path (`MapUtils.initEntryMap`) on trip + home, plus one sanctioned *editor* (`js/src/location-map.js`) for the `/post` pin picker |
|
||||
| Basemap | CartoDB dark-matter | Style URL single-sourced as `MAP_STYLE` in `js/src/map-style.js`, imported by both map paths so they cannot drift |
|
||||
| GPX rendering | toGeoJSON (bundled in `js/map.js`) | Parses GPX → GeoJSON route layers client-side; no CDN |
|
||||
|
||||
---
|
||||
@@ -54,7 +55,7 @@ Other notable plugins:
|
||||
| `api` (Grav API v1) | Used by /gpx-manager to list/upload/delete GPX files |
|
||||
| `admin2` | Admin panel at /admin |
|
||||
| `story-blocks` (custom) | Storytelling shortcode blocks for long-form stories (needs `shortcode-core`) |
|
||||
| `entry-actions` (custom) | Owner-only, active-trip-scoped journal entry actions (delete) via the Grav API |
|
||||
| `entry-actions` (custom) | Owner-only, active-trip-scoped actions via the Grav API. Three routes: `DELETE /entry/{slug}`, `POST /entry/{slug}/photos/order`, `POST /trip/{slug}/publish`. Exists because stock `DELETE /api/v1/pages<route>` checks only write-permission (no trip scoping) and cannot renumber media to the `photo-NN` cover order |
|
||||
|
||||
### Plugin management model
|
||||
|
||||
@@ -76,10 +77,15 @@ Three categories, by how each plugin is installed and maintained:
|
||||
| `js/src/map.js` | `js/map.js` + `css-compiled/map.css` — bundles `maplibre-gl`, `@mapbox/togeojson`, and `js/maplibre-utils.js` |
|
||||
| `js/src/feed-actions.js` | `js/feed-actions.js` |
|
||||
| `js/src/trip-publish.js` | `js/trip-publish.js` |
|
||||
| `js/src/post-form.js` | `js/post/` (ESM + code splitting) + `css-compiled/post-form.css` |
|
||||
| `js/src/post-form.js` | `js/post/` (ESM + code splitting) + `css-compiled/post-form.css` — also pulls in `location-map.js` and `map-style.js` |
|
||||
| `node_modules/maplibre-gl/dist/maplibre-gl.css` | `css-compiled/maplibre-gl.css` — built standalone so `location-map.js` can inject it on demand without a static import defeating its lazy load |
|
||||
| `scripts/gen-weather-icons.js` | `templates/partials/weather-icons.html.twig` (Lucide SVGs inlined into a Twig map) |
|
||||
|
||||
**The trap:** `js/` holds both bundles *and* hand-authored sources. `js/maplibre-utils.js` (the `MapUtils` map engine, a plain IIFE imported by `js/src/map.js`) and `js/nav.js` are sources despite sitting beside the minified bundles. `css/style.css` and `css/tokens.css` are hand-authored too — only `css-compiled/` is generated.
|
||||
The table lists esbuild **entry points**. Other files in `js/src/` (`api-utils.js`, `location-map.js`, `map-style.js`, `post-form.css`) are sources too — they are imported into a bundle rather than being built directly.
|
||||
|
||||
**The trap:** `js/` holds both bundles *and* hand-authored sources. `js/maplibre-utils.js` (the `MapUtils` map engine, a plain IIFE imported by `js/src/map.js`) and `js/nav.js` are sources despite sitting beside the minified bundles.
|
||||
|
||||
**The second trap:** `css/` is **not** the source of `css-compiled/`. `css/style.css` and `css/tokens.css` are hand-authored and served *directly* via `assets.addCss('theme://css/…')` in `partials/base.html.twig` — they are never compiled. `css-compiled/` is esbuild output from the CSS imports inside `js/src/*.js` (fontsource + PhotoSwipe → `main.css`; maplibre → `map.css`) plus the standalone maplibre build above.
|
||||
|
||||
---
|
||||
|
||||
@@ -89,18 +95,24 @@ All page templates extend `base.html.twig`:
|
||||
|
||||
```
|
||||
templates/
|
||||
├─ base.html.twig ← site shell: nav, fonts, CSS tokens
|
||||
├─ default.html.twig ← extends base; generic page
|
||||
├─ home.html.twig ← extends base; context-aware two-column layout
|
||||
├─ trips.html.twig ← extends base; trip list (with the owner's publish toggle)
|
||||
├─ trip.html.twig ← extends base; trip page with filter bar (All/Journal/Stories)
|
||||
├─ entry.html.twig ← extends base; single journal entry (gallery, badges, map)
|
||||
├─ story.html.twig ← extends base; single story (Ken Burns hero, shortcodes)
|
||||
└─ gpx-manager.html.twig ← extends base; admin UI for GPX file management
|
||||
├─ post-form.html.twig ← extends base; the /post journal form
|
||||
├─ gpx-manager.html.twig ← extends base; admin UI for GPX file management
|
||||
├─ forms/ ← field overrides (e.g. forms/fields/datetime/datetime.html.twig)
|
||||
├─ macros/ ← cover, cycling, date-range, stats
|
||||
└─ partials/ ← base.html.twig lives HERE, not at templates/ root
|
||||
```
|
||||
|
||||
**`base.html.twig` is a partial** (`templates/partials/base.html.twig`), despite being the shell every page template extends.
|
||||
|
||||
The standalone `dailies.html.twig`, `map.html.twig`, `stats.html.twig` and `stories.html.twig` view templates were **removed** in the 2026-07-04 standalone-page cleanup — the trip page (`trip.html.twig`) consolidated the feed, inline map, and inline stats.
|
||||
|
||||
Site nav (in `base.html.twig`) is deliberately minimal — **Home + Past Trips only**. It does not link to trip sub-sections, because those standalone views no longer exist.
|
||||
Site nav (in `partials/base.html.twig`) is deliberately minimal — **Home + Trips**, plus **New Post** when `grav.user.authenticated`. It does not link to trip sub-sections, because those standalone views no longer exist.
|
||||
|
||||
Partials live in `templates/partials/` (plus macros in `templates/macros/`). Key partials: `base.html.twig` (site shell extended by all page templates), `entry-map.html.twig` (shared map column + `initEntryMap` call, used by trip + home), `trip-feed-col.html.twig` (feed column chrome, shared by trip + home), `home-predeparture.html.twig`, `entry-journal.html.twig` / `entry-story.html.twig` (feed cards), `trip-publish-toggle.html.twig`, and `weather-icons.html.twig`.
|
||||
|
||||
@@ -147,7 +159,20 @@ The column **beside** the map: date-range header, filter bar, stats/cycling pane
|
||||
|
||||
**Stats/cycling JS glue:** the partial emits an inline `DOMContentLoaded` script calling `window.initTripStats({ gpxUrls, gpsPoints, hasGpx })` — one shared function in `js/src/main.js`. It no-ops when `#stat-distance` is absent, populates exact distance + cycling stats from GPX, and falls back to a `~`-prefixed haversine estimate (or `—` for `<2` points) when there is no GPX. It depends on `window.MapUtils` from `map.js` (loaded in the `bottom` asset group on both pages).
|
||||
|
||||
> History: the map setup replaced an older three-variant arrangement (a `feed-map.html.twig` partial with its own inline init, plus a full-page `map.html.twig`), deleted in the 2026-07-04 standalone-page cleanup.
|
||||
> History: the map setup replaced an older three-variant arrangement (a `feed-map.html.twig` partial with its own inline init, plus a full-page `map.html.twig`), deleted in the 2026-07-04 standalone-page cleanup. See [`superseded-decisions.md`](superseded-decisions.md) → R12.
|
||||
|
||||
#### The one non-`entry-map` map: the `/post` pin editor
|
||||
|
||||
`js/src/location-map.js` (`getOrCreateLocationMap()`) is a deliberately separate, minimal engine for the post form's "More location details" panel — **an editor, not a display map**, so it shares none of `initEntryMap`'s concerns:
|
||||
|
||||
| | `initEntryMap` (display) | `location-map.js` (editor) |
|
||||
|---|---|---|
|
||||
| Markers | many, from entries | exactly one, **draggable** |
|
||||
| Popups / GPX / bounds-fitting | yes | none |
|
||||
| `maplibre-gl` | bundled into `js/map.js` | **lazy-imported** on first open, so a GPS-only submit never fetches it |
|
||||
| Stylesheet | via `js/src/map.js`'s CSS import | injects `css-compiled/maplibre-gl.css` on demand (a static import would defeat the lazy load) |
|
||||
|
||||
The two share exactly one thing: `MAP_STYLE` from `js/src/map-style.js`. Adding a *third* map path is forbidden — see `CLAUDE.md`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,6 +1,17 @@
|
||||
# Design System — Light Mode Color Palette
|
||||
|
||||
Light-mode counterpart to `design-system.md`. Only color tokens differ between themes — typography, spacing, radius, shadows, and layout are identical.
|
||||
> **Superseded — light mode is not implemented, and this palette is not in the code.**
|
||||
>
|
||||
> The site is **dark only**. `css/tokens.css` has a single `:root` block; there is no
|
||||
> `prefers-color-scheme` query, no `data-theme` switch, and none of the light hex values below appear
|
||||
> anywhere in `css/`. Dark mode shipped as *the* theme rather than as one of two
|
||||
> (`../working/plans/2026-06-19-dark-mode.md`, 2026-06-20).
|
||||
>
|
||||
> Keep this file as the record of the pre-dark-mode palette and as the starting point if a light
|
||||
> theme is ever built — but do not read the "Light" column as describing the running site. See
|
||||
> [`superseded-decisions.md`](superseded-decisions.md) → R9.
|
||||
|
||||
Light-mode counterpart to `design-system.md`, as originally specified. Only color tokens were intended to differ between themes — typography, spacing, radius, shadows, and layout are identical.
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -31,6 +31,13 @@
|
||||
|
||||
### Palette (dark theme — as implemented)
|
||||
|
||||
**Dark is the only theme.** `css/tokens.css` has a single `:root` block; there is no
|
||||
`prefers-color-scheme` query and no `data-theme` switch. `design-system-light.md` records the
|
||||
pre-dark-mode palette, which was never implemented as a switchable theme — see
|
||||
[`superseded-decisions.md`](superseded-decisions.md) → R9.
|
||||
|
||||
The authoritative list is `user/themes/intotheeast/css/tokens.css`.
|
||||
|
||||
| Token | Hex | Usage |
|
||||
|---|---|---|
|
||||
| `--color-paper` | `#1A1814` | Page background — warm near-black |
|
||||
@@ -46,6 +53,20 @@
|
||||
| `--color-accent-on` | `#FFFFFF` | Text on accent surfaces |
|
||||
| `--color-surface-raised` | `#2A2720` | Elevated surfaces: tooltips, hover |
|
||||
| `--color-ink-inverse` | `#17171A` | Text on accent-coloured buttons |
|
||||
| `--color-error` | `#c0392b` | Validation errors, form error status |
|
||||
| `--color-draft-accent` | `#E0A458` | Warm amber — draft/unpublished badges |
|
||||
|
||||
#### Glass overlays
|
||||
|
||||
Paper colour at opacity, used by the story components. Computed with `color-mix()` rather than fixed
|
||||
hex, so they track `--color-paper` automatically.
|
||||
|
||||
| Token | Value | Usage |
|
||||
|---|---|---|
|
||||
| `--color-paper-glass-low` | `color-mix(in srgb, var(--color-paper) 8%, transparent)` | Faintest scrim |
|
||||
| `--color-paper-glass-mid` | `color-mix(in srgb, var(--color-paper) 25%, transparent)` | Standard overlay |
|
||||
| `--color-paper-glass-high` | `color-mix(in srgb, var(--color-paper) 55%, transparent)` | Heavy scrim over imagery |
|
||||
| `--color-paper-glass-hover` | `color-mix(in srgb, var(--color-paper) 80%, transparent)` | Hover state on a glass surface |
|
||||
|
||||
### Rationale for accent color
|
||||
|
||||
@@ -150,7 +171,7 @@ DM Serif Display has a calligraphic quality — slightly editorial, authoritativ
|
||||
- Nav links: DM Sans, `--text-sm`, weight 500, `--color-ink-2`
|
||||
- Active nav link: `--color-accent`, weight 600
|
||||
- Mobile: same layout, title slightly smaller, nav links compact
|
||||
- Background: `--color-canvas` (white), bottom border `1px solid var(--color-border)`
|
||||
- Background: `--color-canvas` (`#22201B` in the dark theme), bottom border `1px solid var(--color-border)`
|
||||
|
||||
### 5.2 Entry Feed Card — With Photo
|
||||
|
||||
@@ -342,7 +363,7 @@ Minimal changes — the map itself is good. Style improvements:
|
||||
| JS | Vanilla JS — unchanged | Current JS is well-structured, scope doesn't justify a framework |
|
||||
| Icons | Unicode + emoji (current) | No dependency, works everywhere |
|
||||
| Fonts | Google Fonts via CDN | Two fonts, display-swap, negligible impact |
|
||||
| Maps | MapLibre GL JS | Replaced Leaflet; all 3 map templates use it |
|
||||
| Maps | MapLibre GL JS | Replaced Leaflet. One shared display-map partial (`partials/entry-map.html.twig`), not three templates — see [`superseded-decisions.md`](superseded-decisions.md) → R12 |
|
||||
| Build | None — no build pipeline | Grav's asset pipeline handles minification if needed |
|
||||
|
||||
**No Alpine.js, no TypeScript, no Tailwind.** The site has clean vanilla JS and CSS today; a redesign is about visual quality, not framework migration. Introducing a build pipeline on a 3-week timeline is a distraction.
|
||||
|
||||
@@ -0,0 +1,54 @@
|
||||
# Superseded decisions
|
||||
|
||||
Things this project planned, built, and then deliberately reversed. One row per reversal.
|
||||
|
||||
**Why this file exists.** The plans and milestones under `docs/working/` are historical records — they
|
||||
say what was decided *then*, and they are correct as records. But a reader who opens
|
||||
`milestones/milestone-2.md` finds a confident present-tense description of a Leaflet `/map` page that
|
||||
has not existed since 2026-07-04. This file is the changelog of "what did we change our mind about",
|
||||
so that question has one answer instead of requiring a re-derivation from the code.
|
||||
|
||||
**How to use it.** Each superseded section in the old docs carries a `> **Superseded …**` note
|
||||
pointing back here. If you are about to re-create something you found in an old plan, check here
|
||||
first — the reversal is usually deliberate, and several are load-bearing rules in
|
||||
[`CLAUDE.md`](../../CLAUDE.md).
|
||||
|
||||
**Keep it current.** When a decision is reversed, add a row *in the same commit as the reversal*. A
|
||||
ledger that lags is worse than no ledger, because it is trusted.
|
||||
|
||||
---
|
||||
|
||||
## The reversals
|
||||
|
||||
| # | Originally planned | Planned in | True now | Changed | Why |
|
||||
|---|---|---|---|---|---|
|
||||
| R1 | A standalone `/map` page — full-height Leaflet map, marker per entry, popups | `milestones/milestone-2.md` (whole doc); `summary.md` | No `/map` route. The map renders **inline on the trip page** through the single shared `partials/entry-map.html.twig` | 2026-07-04 | `plans/2026-07-04-standalone-page-cleanup.md`. One consolidated trip page beat four thin views; a separate map page meant a second map implementation to keep in sync |
|
||||
| R2 | A standalone `/stats` page — days on the road, entries, countries, distance | `milestones/milestone-3.md` (whole doc); `summary.md` | No `/stats` route. Stats render **inline on the trip page** behind a toggle, via `initTripStats()` | 2026-07-04 | Same cleanup. The numbers are trip context, not a destination |
|
||||
| R3 | A `/tracker` feed route as the entry list | `milestones/milestone-1.md` §1.6; `milestone-2.md`; `milestone-3.md`; `summary.md` | No `/tracker`. The feed is the **trip page** plus the home active-trip view, sharing `partials/trip-feed-col.html.twig` | Restructured 2026-06-19 (`plans/2026-06-19-trip-entity.md`), fully retired 2026-07-04 | The Trip entity became the organising unit, so a global tracker had nothing to track |
|
||||
| R4 | Leaflet.js with OpenStreetMap tiles | `milestone-2.md`; `milestone-4.md`; `summary.md`; `pm-analysis.md` | **MapLibre GL JS**, CartoDB dark-matter basemap. Style URL is single-sourced as `MAP_STYLE` in `js/src/map-style.js` | 2026-06-20 | `plans/2026-06-19-maplibre-migration.md`. Vector tiles, GPU rendering, and a dark basemap that suits the dark theme |
|
||||
| R5 | A standalone `/dailies` journal view and `/stories` story view | `plans/2026-06-19-trip-entity.md` era | Both routes retired. `01.dailies/` and `04.stories/` survive as `routable:false` **data containers** whose children the trip page aggregates | 2026-07-04 | Same cleanup. **The folders are load-bearing** — retiring a view must never delete its container (see [`CONCEPTS.md`](../../CONCEPTS.md) → Container) |
|
||||
| R6 | Site nav "Journal · Map · Stats" | `summary.md` | **Home · Trips**, plus **New Post** when authenticated (`partials/base.html.twig:27-31`) | Sub-views retired 2026-07-04; "Past Trips" renamed "Trips" 2026-07 (`6cf5092`) | Nav should not link to views that no longer exist |
|
||||
| R7 | `hero_image` frontmatter on entries, to pin a feed-card hero | `milestone-1.md` §1.6; `summary.md`; `pm-analysis.md` | **No `hero_image` field on journal entries.** The hero is the first uploaded photo (`entry-journal.html.twig` uses `entry.media.images\|first`). Photo order is owner-controlled, so an explicit filename was redundant. **Stories still use `hero_image`** | 2026-07 | `plans/2026-07-05-photo-editor-media-api.md` gave the owner drag-reorder over photos, which made "first photo" a deliberate choice rather than an accident |
|
||||
| R8 | Photos optional on an entry | `milestone-1.md` §1.5; `guides/posting.md` (pre-2026-07-25) | Photos are **required — minimum 1, maximum 6** (`post-form.md:35-46`, enforced in `post-form.js` `initValidation`) | 2026-07 | `plans/2026-07-04-journal-post-form.md`. Photos come first in the form because they anchor what you write |
|
||||
| R9 | A light-mode colour palette alongside dark | `reference/design-system-light.md` (whole doc); `plans/2026-06-19-dark-mode.md` | **Dark only.** `css/tokens.css` has a single `:root` block; there is no `prefers-color-scheme` or `data-theme` switch, and no light-palette hex appears in `css/` | 2026-06-20 | Dark mode shipped as *the* theme, not as one of two. The light palette was the pre-dark-mode original and was never re-implemented as a switchable theme |
|
||||
| R10 | `shortcode-gallery-plusplus` as the entry photo gallery | `pm-analysis.md` | Galleries are **PhotoSwipe**, wired in `js/src/main.js` against `.pswp-gallery` markup emitted by `partials/entry-journal.html.twig`. No `[gallery]` shortcode is used anywhere in `templates/` or `pages/` | 2026-06-21 (`30c8937`, "replace custom lightbox with PhotoSwipe v5") | A lightbox the theme controls beat a plugin's markup. ⚠️ The plugin is **still listed in `plugins.txt`** with no consumer — see recommendations |
|
||||
| R11 | `travel-memories` as an in-repo service on :8082, built from `./services/travel-memories` | `plans/2026-06-21-travel-memories.md`; `specs/2026-06-21-travel-memories-design.md`; `working/2026-06-21-travel-memories-handover.md` | **Extracted to a separate project.** `services/` is gitignored and the source is absent from this repo | `a80b0a9` — "remove travel-memories service from repo (moved to separate project)" | It was an independent Flask app with its own lifecycle. ⚠️ `docker-compose.yml` **still declares the service**, so `make start` fails on a clean checkout — see recommendations |
|
||||
| R12 | Three map template variants (`feed-map.html.twig` partial with inline init, plus full-page `map.html.twig`) | pre-2026-06-27 templates | **One display map path** — `MapUtils.initEntryMap()` in `js/maplibre-utils.js`, invoked through `partials/entry-map.html.twig` | Consolidated 2026-06-27, variants deleted 2026-07-04 | `plans/2026-06-27-map-init-consolidation.md`. Three implementations drifted apart |
|
||||
| R13 | A single map code path, no exceptions | `CLAUDE.md` (pre-2026-07-24 wording) | One **display** path (R12) **plus one sanctioned editor** — `js/src/location-map.js` for the `/post` pin picker: one draggable marker, no popups/GPX/bounds, `maplibre-gl` lazy-imported. Shares only `MAP_STYLE` with the display path | 2026-07-24 — `user/` `dd19995`, outer `4450bd6`; the rule was carved out in `829325c` | `plans/2026-07-23-post-form-location-override.md`. An editor map has none of a display map's concerns; folding them together would have compromised both |
|
||||
| R14 | `post-form.md` carries a static `pageconfig.parent` naming the write target | pre-2026-07 form config | **No `parent` in `post-form.md`.** `cache-on-save` derives it from `site.active_trip` at submit time | 2026-07 | The two settings silently desynced. **Never re-add it** — this is a hard rule in [`CLAUDE.md`](../../CLAUDE.md) |
|
||||
|
||||
---
|
||||
|
||||
## Decisions that were *not* reversed
|
||||
|
||||
Worth stating, because their planning docs are old enough to look suspect:
|
||||
|
||||
- **The SKIP list in [`pm-analysis.md`](../working/pm-analysis.md) still holds.** Background GPS
|
||||
tracking, followers, comments, social discovery, reactions, trip reels, 3D flyover, printed books,
|
||||
and AI itinerary building were all deliberately rejected for a solo flat-file blog. That reasoning
|
||||
has not changed — only some of the *BUILD* items' delivery mechanisms did (R1, R2, R4, R7, R10).
|
||||
- **Weather via Open-Meteo**, no API key, with the eight allowed `weather_desc` values — still exactly
|
||||
as planned in `milestone-1.md` §1.2, and still matching the blueprint and the post form.
|
||||
- **Location badge** (`📍 City, Country`) on cards and entry pages — as planned.
|
||||
- **Distance/stats computation from frontmatter and GPX** — the numbers survived; only their
|
||||
*location* moved from a `/stats` page to the trip page (R2).
|
||||
+253
@@ -0,0 +1,253 @@
|
||||
---
|
||||
title: Reconciling drifted docs — tier by tense, and record reversals in a ledger
|
||||
date: 2026-07-25
|
||||
category: conventions
|
||||
module: documentation
|
||||
problem_type: convention
|
||||
component: documentation
|
||||
severity: high
|
||||
applies_when:
|
||||
- Auditing documentation against the code after a period of undocumented change
|
||||
- Deciding whether a stale document should be corrected, annotated, or deleted
|
||||
- A plan or milestone describes a feature that was later dropped or replaced
|
||||
- Writing or reviewing an index that describes what another document is for
|
||||
- Asked whether the docs would pass a review, or to make them pass one
|
||||
- A decision is being reversed and the old rationale needs to survive the reversal
|
||||
tags: [documentation-conventions, staleness, tiering, drift, supersession, decision-log, audit, verification, indexes]
|
||||
---
|
||||
|
||||
# Reconciling drifted docs — tier by tense, and record reversals in a ledger
|
||||
|
||||
## Context
|
||||
|
||||
Five weeks after the last documentation pass, this repo's docs described a site that partly no longer
|
||||
existed. `/map`, `/stats`, `/tracker`, Leaflet, a light theme, and `hero_image` on entries had all been
|
||||
deliberately removed — but several documents still presented them in confident present tense, and
|
||||
nothing marked those documents as historical.
|
||||
|
||||
The trigger question was *"straighten this out so a repeat review returns ok."* The answer depended on
|
||||
a distinction the tree did not encode.
|
||||
|
||||
[`claude-md-content-tiering.md`](claude-md-content-tiering.md) established that **descriptions drift
|
||||
and rules do not**, and tiered content by *type* (rules stay in `CLAUDE.md`, descriptions move to
|
||||
`docs/`). This pass confirmed that thesis again — every one of 20 verified defects was a description
|
||||
of code, config, or a command; not one was a rule that had gone wrong on its own. But content-type
|
||||
tiering alone did not answer what to *do* with 41 completed plans and 4 milestone specs, because those
|
||||
are neither rules nor current descriptions.
|
||||
|
||||
The missing axis was **tense**.
|
||||
|
||||
## Guidance
|
||||
|
||||
### 1. Tier by tense, then treat the halves oppositely
|
||||
|
||||
| Kind | Files here | Claims | Staleness is | Treatment |
|
||||
|---|---|---|---|---|
|
||||
| **Present-tense** | `CLAUDE.md`, `docs/reference/`, `docs/guides/`, `README.md`, `CONCEPTS.md` | "this is how it *is*" | a **defect** | correct against the code |
|
||||
| **Past-tense** | `docs/working/plans/`, `specs/`, `milestones/`, `summary.md`, `pm-analysis.md` | "this is what we decided *then*" | **correct and expected** | annotate only, never rewrite |
|
||||
|
||||
A completed plan *should* be stale — that is what makes it a record. Rewriting 41 plans to match
|
||||
today's code would destroy the audit trail of *why* each thing changed, and the work is unbounded.
|
||||
The defect was never their staleness; it was that nothing told a reader they were history.
|
||||
|
||||
`docs/solutions/` straddles the split deliberately: past-tense incident, present-tense guidance. That
|
||||
is why its `applies_when` frontmatter matters more than its narrative — the frontmatter is the part
|
||||
that must stay true.
|
||||
|
||||
### 2. Ledger plus inline notes — neither alone is enough
|
||||
|
||||
Two mechanisms, because each covers the other's failure:
|
||||
|
||||
- **A supersession ledger** (`docs/reference/superseded-decisions.md`) — one table: what was planned,
|
||||
where it was planned, what is true now, when it changed, why. This is the only thing that answers
|
||||
*"what did I change my mind about?"* in one place, which is the question a review actually asks.
|
||||
Alone, it has an indirection problem: a pointer you might not follow.
|
||||
- **Inline `> **Superseded …**` notes** at each stale claim, so the claim cannot be read
|
||||
un-corrected. Alone, it has a completeness problem: no changelog view, and coverage is only as good
|
||||
as the annotation pass was.
|
||||
|
||||
**Prefer the annotation patterns the repo already uses.** Here, `architecture.md` already carried
|
||||
`> History:` notes and `trip-switching.md` already carried `> **Changed 2026-07:**`. Inventing a third
|
||||
convention would have been worse than adopting either.
|
||||
|
||||
**Add the ledger row in the same commit as the reversal.** A ledger that lags is worse than no ledger,
|
||||
because it is trusted — the same failure mode as a lagging plan `Status:` line.
|
||||
|
||||
### 3. Also record what was *not* reversed
|
||||
|
||||
A ledger of only reversals makes every old document look suspect. This one ends with a short
|
||||
"decisions that were *not* reversed" section — the `pm-analysis.md` SKIP list still stands, the
|
||||
weather integration shipped exactly as specified, the stats computation survived and only *moved*.
|
||||
Without it, a future reader re-litigates settled decisions because the surrounding docs looked old.
|
||||
|
||||
### 4. Separate "the docs are wrong" from "the code is wrong"
|
||||
|
||||
An audit against code finds both. Mixing them makes the diff unreviewable and stalls the documentation
|
||||
fix behind a behaviour decision. Route code-side findings to a separate recommendations document and
|
||||
**explicitly do not act on them**. Here that kept a 300-line docs diff clean while still capturing that
|
||||
`make start` is broken on any clean checkout.
|
||||
|
||||
Documenting a trap is not the same as fixing it — and is the right move when the fix is someone else's
|
||||
call. Per the tiering doc, a gotcha has no natural trigger that opens a file, so a live trap belongs in
|
||||
`CLAUDE.md` even while its fix stays unscheduled.
|
||||
|
||||
### 5. Verify against the artifact that decides behaviour, not the prose about it
|
||||
|
||||
Every finding must come from the thing that actually determines behaviour:
|
||||
|
||||
| To check | Read |
|
||||
|---|---|
|
||||
| What a command does | the `Makefile` — including macro-generated targets, which a grep for literal target names will miss |
|
||||
| What a build produces | the build script (`package.json`), not a prose asset table |
|
||||
| Whether a file is a source or an output | which file *imports* it, and how it reaches the page |
|
||||
| Whether a feature exists | the absence of its mechanism, not the absence of a mention |
|
||||
| Whether a plan shipped | the branch history, not the plan's own `Status:` line |
|
||||
|
||||
This is also where an audit catches *itself*. One draft finding here claimed the asset table was
|
||||
missing four source files; reading `package.json` showed the table lists esbuild **entry points**, so
|
||||
imported-only sources were correctly absent. The finding was withdrawn. **An audit that never
|
||||
withdraws a finding has not been checking itself.**
|
||||
|
||||
### 6. Re-check the baseline before publishing, not only before starting
|
||||
|
||||
A long audit **races the work it is auditing**. This one had its baseline move twice, and each time the
|
||||
convenient state was the wrong one:
|
||||
|
||||
- **The submodule pin lagged.** A fresh worktree checks out the commit the outer repo pins, not the
|
||||
submodule's real HEAD. Auditing the pin would have reported a shipped feature as unbuilt. Move to the
|
||||
real HEAD first, and keep the gitlink out of the commit (see
|
||||
[`dual-repo-submodule-workflow.md`](../architecture-patterns/dual-repo-submodule-workflow.md) —
|
||||
`M user` is normal and must not be "fixed").
|
||||
- **The base branch advanced 13 commits mid-audit**, independently fixing two findings. Merging the
|
||||
base branch in before opening the PR is what surfaced that. Without it, the branch would have
|
||||
**reverted** work that was already correct — the worst possible outcome for a cleanup pass, because it
|
||||
arrives disguised as an improvement.
|
||||
|
||||
Two habits fall out of this. **Merge the base branch in before publishing, and read the conflicts as
|
||||
findings rather than chores** — each conflict is the codebase telling you someone else already reasoned
|
||||
about this line. And **when the incoming version is better, take it wholesale**: here the base branch's
|
||||
map-doctrine wording and plan status were both more informed than the replacements drafted during the
|
||||
audit, so they were kept in full and the audit's own notes were corrected to match. An audit has no
|
||||
special authority over the work it audits.
|
||||
|
||||
## Why This Matters
|
||||
|
||||
**An index describing another document's role makes a factual claim that can rot — and it is worse
|
||||
than the stale document itself.** The single most misleading line in this tree was
|
||||
`docs/working/README.md` advertising `summary.md` as *"Project summary / current state"*, while
|
||||
`summary.md` described Leaflet, `/tracker`, `/map` and `/stats`. A stale document is survivable — a
|
||||
reader may notice the date, the tone, the odd claim. An index that vouches for it as authoritative
|
||||
**defeats that judgement before it engages.** When writing an index, treat every "what this file is
|
||||
for" phrase as an assertion with an expiry date.
|
||||
|
||||
**Wrong beats absent, again — now for commands.** The tiering doc found this for paths: an absent fact
|
||||
makes an agent go look; a wrong one makes it act confidently in the wrong place. The same held for
|
||||
`README.md`'s server runbook, where every `remote-*` command was documented without the `-test`/`-prod`
|
||||
suffix `guard-env` requires. Every documented command failed on the first line. `deploy-cycle.md` had
|
||||
the rule right the whole time — the defect was a **second copy** of the knowledge drifting from the
|
||||
first. Fewer copies would have prevented it outright.
|
||||
|
||||
**Promoting a doc to "the authoritative list of X" creates a completeness obligation it did not have
|
||||
as prose.** `CLAUDE.md` pointed at `README.md` for "the full `make` command list"; README then held 7
|
||||
of ~20 `remote-*` targets. The pointer was added by a well-intentioned earlier tiering pass. Routing
|
||||
content out of an always-loaded file is right, but **the destination inherits a duty to be complete**,
|
||||
and nothing enforces that.
|
||||
|
||||
**Deliberate removals leak.** `travel-memories` was extracted to its own project, its source deleted
|
||||
and `services/` gitignored — but `docker-compose.yml` still declared the service, and `CLAUDE.md` still
|
||||
claimed it ran on :8082. `make start` has therefore been broken on every clean checkout since, hidden
|
||||
only because a pre-removal Docker image stayed cached locally. **A removal is not finished when the
|
||||
code is gone; it is finished when every consumer and every description of it is gone too.** The cached
|
||||
image is the general lesson: local state can mask a breakage indefinitely, so "it works here" is not
|
||||
evidence.
|
||||
|
||||
## When to Apply
|
||||
|
||||
- After any stretch of change that outpaced its documentation, or when asked whether the docs would
|
||||
survive a review
|
||||
- Before rewriting a stale plan, spec, or milestone — annotate it instead; the record is the value
|
||||
- When reversing a decision: add the ledger row and the inline note in the reversal's own commit
|
||||
- When writing an index, a folder README, or any "read X for Y" pointer — that pointer is a claim
|
||||
- When removing a service, route, feature, or dependency: sweep for consumers *and* for prose that
|
||||
describes it, including compose files, always-loaded instruction files, and demo fixtures
|
||||
- When promoting any document to authoritative for a list — decide who keeps it complete
|
||||
- Before auditing a repo with submodules: confirm you are on the state that actually runs
|
||||
|
||||
## Examples
|
||||
|
||||
### Tense-marking a historical spec, without rewriting it
|
||||
|
||||
`milestones/milestone-2.md` still opens with its original goal — that is the record. The banner sits
|
||||
directly beneath it, so the stale claim cannot be read alone:
|
||||
|
||||
```markdown
|
||||
**Goal:** A `/map` page shows all entries as markers on an interactive Leaflet.js map, …
|
||||
|
||||
> **Superseded — written 2026-06-21. Neither the `/map` page nor Leaflet exists.**
|
||||
>
|
||||
> - **No `/map` route.** The map renders inline on the trip page via the single shared partial
|
||||
> `templates/partials/entry-map.html.twig` (R1, retired 2026-07-04).
|
||||
> - **Leaflet + OpenStreetMap tiles → MapLibre GL JS** (R4, 2026-06-20).
|
||||
>
|
||||
> The *substance* of this spec survived — markers per entry, chronological route line, popups,
|
||||
> bounds fitting — it all lives in `MapUtils.initEntryMap()`. Only the page and the library changed.
|
||||
```
|
||||
|
||||
Separating "the idea won" from "this implementation lost" is what stops a future reader concluding the
|
||||
whole spec was a dead end.
|
||||
|
||||
### An index that vouched for a stale document
|
||||
|
||||
```diff
|
||||
-| `summary.md` | Project summary / current state |
|
||||
+| `summary.md` | **Historical** wrap-up of the original four-milestone branch (2026-06-21).
|
||||
+ *Not* the current state — for that read [`../reference/architecture.md`](../reference/architecture.md) |
|
||||
```
|
||||
|
||||
### A source relationship that never existed
|
||||
|
||||
`CLAUDE.md` asserted a build dependency between two unrelated things. `css/` is hand-authored and
|
||||
served *directly*; `css-compiled/` is esbuild output from the CSS imports inside `js/src/*.js`:
|
||||
|
||||
```diff
|
||||
-- `css-compiled/` and `fonts/` are generated (sources: `css/style.css`, `css/tokens.css`)
|
||||
+- `css-compiled/` and `fonts/` are **esbuild output from the imports inside `js/src/`** — *not*
|
||||
+ from `css/`. Everything in `css/` is hand-authored and served directly (`assets.addCss` in
|
||||
+ `partials/base.html.twig`), never compiled.
|
||||
```
|
||||
|
||||
The failure this invited: an agent wanting to change a font edits `css-compiled/main.css` — a
|
||||
generated bundle — because the rule named `css/style.css` as its source and that file does not contain
|
||||
it. The next `make build-assets` silently reverts the edit.
|
||||
|
||||
### Proving a breakage instead of inferring it
|
||||
|
||||
Reasoning that a missing directory *would* break a build is not evidence. Running it is:
|
||||
|
||||
```console
|
||||
$ docker compose build travel-memories
|
||||
unable to prepare context: path ".../services/travel-memories" not found
|
||||
```
|
||||
|
||||
The follow-up mattered more than the failure: a cached `travel-blog-intotheeast-travel-memories:latest`
|
||||
image explained why `make start` still worked on the main checkout but failed in every new worktree.
|
||||
Without that check the finding would have been reported as "broken everywhere" and been wrong.
|
||||
|
||||
## Related
|
||||
|
||||
- [`claude-md-content-tiering.md`](claude-md-content-tiering.md) — the content-type tiering axis and
|
||||
the "descriptions drift, rules don't" thesis this learning extends with a tense axis. **Consolidation
|
||||
candidate:** the two overlap on root cause and on the files they touch; if a third documentation
|
||||
learning appears, consider merging all three into one documentation-maintenance doc.
|
||||
- [`../architecture-patterns/retiring-a-consolidated-grav-sub-page.md`](../architecture-patterns/retiring-a-consolidated-grav-sub-page.md)
|
||||
— the mechanics of the retirement that produced ledger rows R1, R2 and R5. That doc covers removing
|
||||
the *page*; this one covers removing the *claims about* the page.
|
||||
- [`../architecture-patterns/dual-repo-submodule-workflow.md`](../architecture-patterns/dual-repo-submodule-workflow.md)
|
||||
— why a fresh worktree's `user/` sits at the pin rather than at HEAD, which is the audit-baseline trap
|
||||
in §6.
|
||||
- [`../integration-issues/stale-grav-version-blocks-api-plugin-install.md`](../integration-issues/stale-grav-version-blocks-api-plugin-install.md)
|
||||
— the same rot in the deploy-config domain: a version number that went stale and broke an install.
|
||||
- `docs/working/specs/2026-07-25-docs-reconciliation-design.md` — the design and the verification
|
||||
table for this pass.
|
||||
- `docs/working/2026-07-25-doc-drift-recommendations.md` — the code-side findings deliberately not
|
||||
acted on, including the compose breakage and a proposed repeatable `make docs-check`.
|
||||
@@ -0,0 +1,149 @@
|
||||
# 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.**
|
||||
+12
-1
@@ -4,6 +4,17 @@ Everything here is a live working document: specs being built from, plans being
|
||||
|
||||
Stable facts belong in [`../reference/`](../reference/); how-to procedures in [`../guides/`](../guides/); write-ups of bugs already solved in [`../solutions/`](../solutions/).
|
||||
|
||||
> ⚠️ **Everything here is written in the past tense, even when it reads present-tense.** A completed
|
||||
> plan describes the code *as it was when the plan landed* — that is what makes it a useful record,
|
||||
> and it is not a defect when it no longer matches. Several documents here describe features that were
|
||||
> later deliberately reversed: there is no `/map` page, no `/stats` page, no `/tracker`, no Leaflet, no
|
||||
> light theme, and no `hero_image` on entries.
|
||||
>
|
||||
> **Before re-creating anything you find in this folder, check
|
||||
> [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md).** Superseded sections
|
||||
> also carry an inline `> **Superseded …**` note pointing there. For the site as it is, read
|
||||
> [`../reference/architecture.md`](../reference/architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## What's in here
|
||||
@@ -18,7 +29,7 @@ Stable facts belong in [`../reference/`](../reference/); how-to procedures in [`
|
||||
| `learnings/` | Retrospective notes worth keeping but not yet promoted to `../solutions/` |
|
||||
| `backlog.md` | Unscheduled ideas and wishes |
|
||||
| `bugs-and-fixes.md` | Running log of bugs found and what fixed them |
|
||||
| `summary.md` | Project summary / current state |
|
||||
| `summary.md` | **Historical** wrap-up of the original four-milestone branch (2026-06-21). *Not* the current state — for that read [`../reference/architecture.md`](../reference/architecture.md) |
|
||||
| `pm-analysis.md`, `git-sync-notes.md`, dated one-offs | Standalone notes, kept for reference |
|
||||
|
||||
---
|
||||
|
||||
@@ -0,0 +1,208 @@
|
||||
# Documentation Reconciliation — Handover
|
||||
|
||||
**Date:** 2026-07-25
|
||||
**Branch:** `feat/docs-reconcile` (worktree `.worktrees/docs-reconcile`, dev server :8091)
|
||||
**State:** Work **complete and pushed**. Remaining: **open the PR** (needs one interactive command) and **decide on 7 logged recommendations**. No code was changed; no `user/` commits were made.
|
||||
|
||||
Two audiences:
|
||||
- **Part A — Claude → future Claude:** exact state, the one trap that nearly caused a regression, and what must not be "tidied up".
|
||||
- **Part B — Mischa:** the two things only you can do.
|
||||
|
||||
---
|
||||
|
||||
## Part A — Handover (Claude → future Claude)
|
||||
|
||||
### What this branch delivers
|
||||
|
||||
A whole-repo reconciliation of the documentation against the code, after five weeks in which the app
|
||||
changed and the docs did not. **The code was treated as the source of truth throughout.**
|
||||
|
||||
Three deliverables:
|
||||
|
||||
1. **`docs/reference/superseded-decisions.md`** (new) — the supersession ledger. 14 reversals, each with
|
||||
what was planned, where, what is true now, when it changed, and why. Plus a "decisions that were
|
||||
*not* reversed" section so old planning docs don't all read as suspect.
|
||||
2. **Inline `> **Superseded …**` notes** at each stale claim, in the 4 milestone docs, `summary.md`,
|
||||
`pm-analysis.md`, and `design-system-light.md`. Reuses the repo's existing `> History:` /
|
||||
`> **Changed 2026-07:**` patterns — do not invent a third convention.
|
||||
3. **Corrections to the nine present-tense docs** (`CLAUDE.md`, `README.md`, `CONCEPTS.md`,
|
||||
`docs/README.md`, `docs/working/README.md`, `reference/architecture.md`,
|
||||
`reference/design-system.md`, `reference/design-system-light.md`, `guides/posting.md`).
|
||||
|
||||
Plus the compounded learning (`docs/solutions/conventions/reconciling-drifted-docs-tense-tiering-and-a-supersession-ledger.md`),
|
||||
the design/verification record (`docs/working/specs/2026-07-25-docs-reconciliation-design.md`), and the
|
||||
unacted findings (`docs/working/2026-07-25-doc-drift-recommendations.md`).
|
||||
|
||||
### The governing idea — do not undo this
|
||||
|
||||
Scope was split by **tense**, because the halves need opposite treatment:
|
||||
|
||||
| Kind | Staleness is | Treatment |
|
||||
|---|---|---|
|
||||
| Present-tense: `CLAUDE.md`, `reference/`, `guides/`, `README.md`, `CONCEPTS.md` | a **defect** | corrected against the code |
|
||||
| Past-tense: `plans/`, `specs/`, `milestones/`, `summary.md`, `pm-analysis.md` | **correct and expected** | annotated only, **never rewritten** |
|
||||
|
||||
**A completed plan is supposed to be stale — that is what makes it a record.** If a future session is
|
||||
tempted to "finish the job" by rewriting the milestone docs or the 41 completed plans to match today's
|
||||
code, that is the wrong instinct and destroys the audit trail. The banners are the fix.
|
||||
|
||||
### Commits (all on `feat/docs-reconcile`, all pushed)
|
||||
|
||||
`origin/feat/docs-reconcile` == local `HEAD` == `7c9c140`.
|
||||
|
||||
- `8202d2a` — the reconciliation: ledger + inline notes + the nine present-tense corrections
|
||||
- `d946eaa` — compounded learning into `docs/solutions/conventions/` + new `CONCEPTS.md` Documentation cluster
|
||||
- `7c9c140` — **merge of `main`** (see the trap below)
|
||||
|
||||
Net diff vs `main` is 19 files, +897/−60, **no deletions**, and the submodule gitlink is byte-identical
|
||||
to `main`.
|
||||
|
||||
### ⚠️ The trap — `main` moved 13 commits mid-audit
|
||||
|
||||
This is the most important thing on this page.
|
||||
|
||||
While the audit ran, the location-override work was merged into the outer repo, advancing `main` by 13
|
||||
commits. **It independently fixed two of the audit's own findings:**
|
||||
|
||||
- `829325c` — carved out the single-map-path exception for `js/src/location-map.js` in `CLAUDE.md`
|
||||
- `a517331` — set `2026-07-23-post-form-location-override.md` to `✅ Complete`
|
||||
|
||||
Had this branch been merged without first merging `main` in, it would have **reverted both**. Both
|
||||
conflicts were resolved **in `main`'s favour** (its wording was better informed in each case), and the
|
||||
audit's own notes were then corrected to stop claiming credit for fixes it did not make.
|
||||
|
||||
**If you pick this up on 2026-07-26 or later, `main` may have moved again. Do this first:**
|
||||
|
||||
```bash
|
||||
cd .worktrees/docs-reconcile
|
||||
git fetch origin
|
||||
git log --oneline HEAD..origin/main # anything here? then merge before touching the PR
|
||||
git merge origin/main # read each conflict as a finding, not a chore
|
||||
```
|
||||
|
||||
Two rules that came out of this, now recorded in the learning doc §6:
|
||||
- **Re-check the baseline before publishing, not only before starting.** A long audit races the work it audits.
|
||||
- **When the incoming version is better, take it wholesale.** An audit has no special authority over the work it audits.
|
||||
|
||||
### Submodule situation
|
||||
|
||||
- `user/` in this worktree is on branch `feat/docs-reconcile` at **`dd19995`** — I moved it off the
|
||||
outer repo's older pin (`02fa4e9`) so the audit ran against the state that actually runs. Auditing
|
||||
the pin would have reported a shipped feature as unbuilt.
|
||||
- **No commits were made inside `user/`.** `git -C user status` is clean. Nothing to push there.
|
||||
- The merge commit **preserves `main`'s pin bump to `dd19995`**. The no-gitlink-commit rule in
|
||||
`CLAUDE.md` is about not bumping the pin as a side effect of routine work — not about discarding a
|
||||
bump `main` already made. An earlier `git reset -- user` here had silently reverted it to the old pin;
|
||||
that was caught and fixed. **Verify before any future commit on this branch:**
|
||||
`git diff main..HEAD -- user` must be empty.
|
||||
|
||||
### What was verified, and how
|
||||
|
||||
Nothing was inferred from prose. Full table in the spec doc; the load-bearing ones:
|
||||
|
||||
| Claim | Verified against |
|
||||
|---|---|
|
||||
| Nav labels | `partials/base.html.twig:27-31` |
|
||||
| Asset sources → outputs | the theme's `package.json` build script |
|
||||
| `css-compiled/` provenance | CSS imports in `js/src/*.js`; `assets.addCss` in `base.html.twig:7-8` |
|
||||
| No light mode | absence of `prefers-color-scheme` / `data-theme` **and** of light hex values in `css/` |
|
||||
| Photo rules (1–6, required) | `user/pages/02.post/post-form.md:35-46` |
|
||||
| `entry-actions` routes | `entry-actions.php:63-73` |
|
||||
| Env-suffix rule | `Makefile` `guard-env:41-43` + the `make-env-target` macro at `:45-46` |
|
||||
| `travel-memories` removal | `git log -- services/` → `a80b0a9`, then a real `docker compose build` failure |
|
||||
|
||||
**One finding was withdrawn** after reading `package.json`: the asset table lists esbuild *entry
|
||||
points*, so imported-only sources (`api-utils.js`, `location-map.js`, `map-style.js`, `post-form.css`)
|
||||
are correctly absent from it. If a future pass "fixes" that table by adding them, it is reintroducing a
|
||||
non-defect.
|
||||
|
||||
Checks run before pushing: no conflict markers anywhere; `ce-compound`'s frontmatter validator exits 0;
|
||||
all relative links resolve. **One link check hit is a known false positive** —
|
||||
`../reference/architecture.md` inside a ```diff fence in the learning doc, quoting
|
||||
`docs/working/README.md`'s literal content, where that path is correct.
|
||||
|
||||
### Not done, deliberately
|
||||
|
||||
- **The PR is not open.** `tea` requires an interactive TTY for the SSH passphrase. Command in Part B.
|
||||
- **None of the 7 recommendations were acted on**, per instruction. They are decisions, not chores —
|
||||
several are behaviour changes that would have made this diff unreviewable as documentation.
|
||||
- **No `user/` changes**, including the `italy-2025` demo fixtures (recommendation P6).
|
||||
|
||||
### Do not, without being asked
|
||||
|
||||
- Rewrite any past-tense doc to match current code — annotate instead.
|
||||
- Act on `docs/working/2026-07-25-doc-drift-recommendations.md`. **P5 in particular is booby-trapped:**
|
||||
removing `shortcode-gallery-plusplus` may take `shortcode-core` with it (it is a GPM dependency and is
|
||||
*not* in `plugins.txt`), which would break stories. Add `shortcode-core` explicitly first, in its own
|
||||
step, then remove and verify a story page renders.
|
||||
- Bump the submodule pin beyond preserving `main`'s.
|
||||
- `content-push` — nothing here touches content.
|
||||
|
||||
### Environment
|
||||
|
||||
Worktree dev server on **http://localhost:8091** (`itte_docs-reconcile_grav`, from `.worktree-env`).
|
||||
Nothing in this branch needs a running server — it is documentation only — so tearing it down is safe:
|
||||
|
||||
```bash
|
||||
make worktree-rm NAME=docs-reconcile # compose down → submodule deinit → worktree remove → prune
|
||||
```
|
||||
|
||||
The branch is pushed, so removing the worktree loses nothing. Note `main`'s `cfe070e` fixed
|
||||
`worktree-rm` so it no longer unregisters `user/` for the main checkout — that fix is in this branch via
|
||||
the merge.
|
||||
|
||||
---
|
||||
|
||||
## Part B — For Mischa
|
||||
|
||||
### 1. Open the PR (one command)
|
||||
|
||||
```bash
|
||||
cd /home/mischa/Nextcloud/Projects/travel-blog-intotheeast/.worktrees/docs-reconcile
|
||||
tea pr create --login git.gorinskat.nl --repo m038/intotheeast-com \
|
||||
--head feat/docs-reconcile --base main \
|
||||
--title "docs: reconcile documentation against the code; add a supersession ledger" \
|
||||
--description "$(cat /home/mischa/.claude-work/jobs/18e4d444/tmp/pr-body.md)"
|
||||
```
|
||||
|
||||
Or in the browser: https://git.gorinskat.nl/m038/intotheeast-com/pulls/new/feat/docs-reconcile
|
||||
|
||||
⚠️ The body file lives in a Claude job directory and disappears when that job is deleted. If it is
|
||||
already gone, the PR description is reconstructable from
|
||||
`docs/working/specs/2026-07-25-docs-reconciliation-design.md` plus the recommendations doc.
|
||||
|
||||
### 2. Decide on the recommendations
|
||||
|
||||
`docs/working/2026-07-25-doc-drift-recommendations.md`, ordered. The first is a live bug:
|
||||
|
||||
| | What | Why it needs you |
|
||||
|---|---|---|
|
||||
| **P1** | `make start` / `make setup` fail on any clean checkout — `docker-compose.yml` still builds `travel-memories`, whose source you removed in `a80b0a9` | Three options (delete the service / put it behind a compose profile / re-point `build`). It is your call whether that project ever runs alongside Grav again. **It works on your machine only because a pre-removal Docker image is cached** — it breaks in every new worktree and after any `docker image prune` |
|
||||
| **P2** | A repeatable `make docs-check` | The half you deferred. Every defect this pass found was mechanically checkable, so this is what stops the drift recurring. Sequence it *after* P1, or the first thing it reports is P1 |
|
||||
| **P3** | Plan status can silently lag a merge | Three options, cheapest is naming the plan path in the feature commit |
|
||||
| **P4** | `README.md` was designated authoritative for a list it did not hold | Structural: either generate the command tables from the `Makefile`, or soften the `CLAUDE.md` pointer |
|
||||
| **P5** | `shortcode-gallery-plusplus` has no consumer | ⚠️ See the booby-trap warning in Part A before touching it |
|
||||
| **P6** | `italy-2025` demo fixtures still ship `map.md` / `stats.md` for retired views | A `user/` submodule change, so it was out of scope here |
|
||||
| **P7** | Structural notes — e.g. whether `design-system-light.md` should move out of `reference/`, since it documents a theme that does not exist | Judgement calls, both defensible |
|
||||
|
||||
### 3. Worth knowing
|
||||
|
||||
The three findings most likely to have bitten you in practice:
|
||||
|
||||
- **`posting.md` would have failed if followed** — it said photos were optional; they are required, 1–6.
|
||||
- **Every `make remote-*` command in `README.md` was unrunnable** — all documented without the
|
||||
`-test`/`-prod` suffix `guard-env` requires. `deploy-cycle.md` had it right the whole time; the defect
|
||||
was a second copy of the knowledge drifting from the first.
|
||||
- **`docs/working/README.md` advertised `summary.md` as "current state"** while `summary.md` describes
|
||||
Leaflet, `/tracker`, `/map` and `/stats`. An index that vouches for a stale doc is worse than the
|
||||
stale doc, because it defeats your judgement before it engages.
|
||||
|
||||
---
|
||||
|
||||
## Related
|
||||
|
||||
- `docs/working/specs/2026-07-25-docs-reconciliation-design.md` — design, scope rationale, and the full verification table
|
||||
- `docs/reference/superseded-decisions.md` — the ledger itself
|
||||
- `docs/working/2026-07-25-doc-drift-recommendations.md` — the 7 unacted findings
|
||||
- `docs/solutions/conventions/reconciling-drifted-docs-tense-tiering-and-a-supersession-ledger.md` — the compounded learning
|
||||
- `docs/solutions/conventions/claude-md-content-tiering.md` — the prior learning this extends; flagged as a consolidation candidate if a third documentation learning appears
|
||||
@@ -2,6 +2,18 @@
|
||||
|
||||
**Goal:** Every entry is richer out of the box — location name shown, weather auto-captured, photos in a proper gallery, hero image visible on the feed.
|
||||
|
||||
> **Historical — written 2026-06-21. Mostly shipped as specified; three details reversed.**
|
||||
>
|
||||
> Still true: the location badge, Open-Meteo weather auto-fetch with its eight `weather_desc` values,
|
||||
> and the entry photo gallery. Reversed since:
|
||||
> - **§1.5 gallery** is PhotoSwipe, not `shortcode-gallery-plusplus` (R10).
|
||||
> - **§1.6 `hero_image`** no longer exists on entries — the hero is the first uploaded photo, and the
|
||||
> owner controls photo order by drag-reorder (R7). Stories still use `hero_image`.
|
||||
> - **Photos are now required** (1–6 per entry), not optional (R8).
|
||||
> - **"Tracker feed"** is the trip page and the home active-trip view; there is no `/tracker` (R3).
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -2,6 +2,21 @@
|
||||
|
||||
**Goal:** A `/map` page shows all entries as markers on an interactive Leaflet.js map, connected by a chronological route line, with popups linking to entries.
|
||||
|
||||
> **Superseded — written 2026-06-21. Neither the `/map` page nor Leaflet exists.**
|
||||
>
|
||||
> - **No `/map` route.** The map renders inline on the trip page via the single shared partial
|
||||
> `templates/partials/entry-map.html.twig` (R1, retired 2026-07-04). `CLAUDE.md` forbids
|
||||
> re-creating it or linking to it.
|
||||
> - **Leaflet + OpenStreetMap tiles → MapLibre GL JS** with a CartoDB dark-matter basemap (R4,
|
||||
> 2026-06-20).
|
||||
> - **§2.6 nav link** is gone with the page (R6).
|
||||
>
|
||||
> The *substance* of this spec survived — markers per entry, chronological route line, popups linking
|
||||
> to entries, bounds fitting, mobile touch handling — it all lives in `MapUtils.initEntryMap()` in
|
||||
> `user/themes/intotheeast/js/maplibre-utils.js`. Only the page and the library changed.
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -2,6 +2,17 @@
|
||||
|
||||
**Goal:** A `/stats` page showing key trip numbers: days on the road, entries posted, countries visited, and approximate distance traveled.
|
||||
|
||||
> **Superseded — written 2026-06-21. There is no `/stats` page.**
|
||||
>
|
||||
> The stats themselves shipped and still work — days on the road, entries posted, countries visited,
|
||||
> distance (exact from GPX, or a `~`-prefixed haversine estimate without it). They render **inline on
|
||||
> the trip page** behind a toggle, computed by `window.initTripStats()` in `js/src/main.js`
|
||||
> (R2, retired 2026-07-04). `CLAUDE.md` forbids re-creating the standalone view.
|
||||
>
|
||||
> Also reversed: **§3.7 nav link** (R6), and the `/tracker` references (R3).
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -2,6 +2,20 @@
|
||||
|
||||
**Goal:** Embed a compact interactive map above the entry feed on the tracker page, showing recent entry positions and the current location, giving readers immediate spatial context.
|
||||
|
||||
> **Superseded — written 2026-06-21. The idea won; this implementation did not.**
|
||||
>
|
||||
> A map beside the feed is exactly what the site does now — but not as a separate "mini-map":
|
||||
> - **No `/tracker` page** to embed it above (R3). The map sits in a column on the trip page and the
|
||||
> home active-trip view.
|
||||
> - **No second map implementation.** This spec's `feed-map` variant with its own inline init was
|
||||
> deleted; everything goes through the one shared `partials/entry-map.html.twig` +
|
||||
> `MapUtils.initEntryMap()` path (R12, consolidated 2026-06-27). Adding a second display map is
|
||||
> forbidden by `CLAUDE.md`.
|
||||
> - **Leaflet → MapLibre GL JS** (R4), so §4.1's `if (typeof L === 'undefined')` guard is obsolete.
|
||||
> - **No "View full map →" link** — there is no full map page to link to (R1).
|
||||
>
|
||||
> Details: [`../../reference/superseded-decisions.md`](../../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## User Stories
|
||||
|
||||
@@ -2,6 +2,15 @@
|
||||
|
||||
*Role: Senior Product Manager. Audience: one solo traveler (Mischa), platform: Grav CMS flat-file PHP, no native app.*
|
||||
|
||||
> **Historical — written 2026-06-21. The verdicts still hold; some delivery mechanisms do not.**
|
||||
>
|
||||
> The **SKIP** column is still the standing decision and has not been revisited — background GPS,
|
||||
> followers, comments, social discovery, reactions, reels, 3D flyover, print, and AI itineraries
|
||||
> remain deliberately out of scope. What changed is *how* some **BUILD** items shipped: the map and
|
||||
> stats render inline on the trip page rather than as `/map` and `/stats`, MapLibre replaced Leaflet,
|
||||
> galleries use PhotoSwipe rather than `shortcode-gallery-plusplus`, and `hero_image` was dropped for
|
||||
> entries. See [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## Starting position
|
||||
|
||||
@@ -0,0 +1,123 @@
|
||||
# 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 |
|
||||
|
||||
## The audit baseline moved twice
|
||||
|
||||
Both times, auditing the convenient state rather than the real one would have produced wrong findings.
|
||||
|
||||
**The submodule pin lagged.** A fresh worktree checks out the `user/` commit the outer repo pins, not
|
||||
`user/`'s real HEAD. The pin predated the merged location-override work, so auditing it would have
|
||||
reported a feature as unbuilt and missed two new source files. `user/` was moved to its real HEAD
|
||||
(`dd19995`) before auditing, and the gitlink deliberately not committed.
|
||||
|
||||
**The outer `main` advanced 13 commits mid-audit.** The location-override branch was merged into the
|
||||
outer repo while this pass was running, which independently fixed two of the findings — the
|
||||
single-map-path carve-out (`829325c`) and the plan's `Status:` line (`a517331`). Merging `main` in
|
||||
before opening the PR was what surfaced that; without it this branch would have **reverted** both.
|
||||
`main`'s wording was better than the replacement drafted here and was kept in full. `main` touched none
|
||||
of the other nine corrected documents, so the remaining findings stand unchanged.
|
||||
|
||||
The general rule: **re-check the baseline before publishing, not only before starting.** A long audit
|
||||
races the work it is auditing.
|
||||
@@ -2,6 +2,16 @@
|
||||
|
||||
*Branch: `experimental-polar-steps`. Ready for morning review.*
|
||||
|
||||
> **Historical — written 2026-06-21. This is not the current state of the site.**
|
||||
>
|
||||
> This was the wrap-up of the four-milestone experimental branch. Much of what it describes has since
|
||||
> been deliberately reversed: there is no `/map` page, no `/stats` page, no `/tracker` feed, no
|
||||
> Leaflet, and the nav is not "Journal · Map · Stats". Every reversal is listed in
|
||||
> [`../reference/superseded-decisions.md`](../reference/superseded-decisions.md).
|
||||
>
|
||||
> For the site as it actually is, read
|
||||
> [`../reference/architecture.md`](../reference/architecture.md).
|
||||
|
||||
---
|
||||
|
||||
## What Was Done
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
// @ts-check
|
||||
// Tests: S1–S9 — story mode rendering and navigation
|
||||
// Tests: S1–S7 — story mode rendering and navigation
|
||||
// Requires demo data: run `make demo-load` before this suite.
|
||||
const { test, expect } = require('@playwright/test');
|
||||
|
||||
@@ -85,74 +85,3 @@ test('S7: story body back link has back-pill class', async ({ page }) => {
|
||||
await expect(bodyBack).toBeAttached();
|
||||
await expect(bodyBack).toHaveText(/← Back/);
|
||||
});
|
||||
|
||||
// ── S8: Scrolly-section text panels actually render beside the pinned image ───
|
||||
// The server ships the panel text inside .scrolly__steps-content, which CSS hides
|
||||
// (style.css: `display: none`). Only the inline Scrollama block in story.html.twig
|
||||
// splits it into visible .scrolly-step divs — and it early-returns silently if the
|
||||
// main.js bundle (which sets window.scrollama) hasn't executed yet. S3 asserted the
|
||||
// image column exists; nothing asserted the text column was non-empty.
|
||||
test('S8: scrolly-section builds visible step panels from its slot content', async ({ page }) => {
|
||||
await page.goto(STORY_SCROLLY);
|
||||
await expect(page.locator('.story-hero__img')).toBeVisible({ timeout: 8000 });
|
||||
|
||||
// The bundle must have published scrollama before the inline block ran
|
||||
expect(
|
||||
await page.evaluate(() => typeof window.scrollama !== 'undefined'),
|
||||
'window.scrollama published by main.js bundle'
|
||||
).toBe(true);
|
||||
|
||||
// Every scrolly-section must have produced at least one step
|
||||
const sections = page.locator('.scrolly');
|
||||
const sectionCount = await sections.count();
|
||||
expect(sectionCount, 'Two scrolly-sections').toBe(2);
|
||||
|
||||
for (let i = 0; i < sectionCount; i++) {
|
||||
const section = sections.nth(i);
|
||||
const steps = section.locator('.scrolly-step');
|
||||
expect(
|
||||
await steps.count(),
|
||||
`scrolly-section ${i} split its slot content into steps`
|
||||
).toBeGreaterThan(0);
|
||||
}
|
||||
|
||||
// …and the text must be readable, not left hidden in the raw slot.
|
||||
// Scroll each step into view so its reveal transition completes.
|
||||
const firstStep = page.locator('.scrolly').first().locator('.scrolly-step').first();
|
||||
await firstStep.scrollIntoViewIfNeeded();
|
||||
await page.waitForTimeout(800);
|
||||
await expect(firstStep.locator('.scrolly-step__inner')).toBeVisible();
|
||||
const text = (await firstStep.innerText()).trim();
|
||||
expect(text.length, 'First step panel renders non-empty text').toBeGreaterThan(20);
|
||||
});
|
||||
|
||||
// ── S9: Back-to-top is wired once, by main.js, and pushes a history entry ─────
|
||||
// The inline duplicate in story.html.twig was removed; initBackToTop() in
|
||||
// js/src/main.js now solely owns #story-totop. That makes the button depend on
|
||||
// the bundle having loaded, so assert the observable behaviour end to end.
|
||||
test('S9: story back-to-top reveals on scroll, returns to top, and pushes history', async ({ page }) => {
|
||||
await page.goto(STORY_SCROLLY);
|
||||
await expect(page.locator('.story-hero__img')).toBeVisible({ timeout: 8000 });
|
||||
|
||||
const btn = page.locator('#story-totop');
|
||||
await expect(btn).toBeAttached();
|
||||
|
||||
// Hidden until scrolled past the 0.8 * viewport threshold
|
||||
await expect(btn).not.toHaveClass(/is-visible/);
|
||||
|
||||
const historyBefore = await page.evaluate(() => history.length);
|
||||
|
||||
await page.evaluate(() => window.scrollTo(0, window.innerHeight * 2));
|
||||
await expect(btn).toHaveClass(/is-visible/, { timeout: 3000 });
|
||||
|
||||
await btn.click();
|
||||
await expect
|
||||
.poll(() => page.evaluate(() => window.scrollY), { timeout: 3000 })
|
||||
.toBeLessThan(10);
|
||||
|
||||
// main.js's variant pushes a history entry; the removed inline copy did not
|
||||
expect(
|
||||
await page.evaluate(() => history.length),
|
||||
'Back-to-top pushed a history entry'
|
||||
).toBeGreaterThan(historyBefore);
|
||||
});
|
||||
|
||||
+1
-1
Submodule user updated: 1b9e51baf7...dd19995973
Reference in New Issue
Block a user