m038/intotheeast-com
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

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

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

Two mechanisms, following patterns the repo already used:

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

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

Present-tense corrections:

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

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

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

The submodule gitlink is deliberately not bumped.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
m038
2026-07-25 00:13:37 +02:00
co-authored by Claude Opus 5
parent e79275a3ab
commit 8202d2a257
18 changed files with 616 additions and 63 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+67 -28
View File
@@ -48,17 +48,23 @@ Two git repos:
## Local development setup
```bash
cp .env.example .env # fill in your values — never commit this file
make setup # start Docker container and install plugins
cp .env.example .env # fill in your values — never commit this file
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
```
---