Files

T

m038andClaude Opus 5 8202d2a257 docs: reconcile documentation against the code; add a supersession ledger

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

Two mechanisms, following patterns the repo already used:

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

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

Present-tense corrections:

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

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

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

The submodule gitlink is deliberately not bumped.

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

2026-07-25 00:13:37 +02:00

3.7 KiB

Raw Blame History

Experimental Branch Summary

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.

For the site as it actually is, read ../reference/architecture.md.

What Was Done

This branch researched Polarsteps and FindPenguins, distilled their best ideas for a solo travel blog on Grav CMS, planned four milestones, and implemented all four.

What Was Built

Milestone 1 — Entry Enrichment

Location badge (📍 City, Country) on entry page and tracker feed cards
Weather badge (⛅ Partly cloudy · 19°C) on entry page header
"Get Weather" button on post form — auto-fetches via Open-Meteo (free, no key)
Photo gallery on entry pages — 2-col/3-col grid with full lightbox
Hero image on feed cards — falls back to first photo if no hero_image set
New post form fields: City, Country, weather auto-fill

Milestone 2 — Interactive Map (`/map`)

Leaflet.js with OpenStreetMap tiles
Marker per entry with GPS, route polyline in date order
Most recent entry highlighted
Click marker → popup with date, title, link to entry
Full-height map, mobile touch-friendly

Milestone 3 — Statistics Page (`/stats`)

Days on the road, entries posted, countries visited, distance traveled
Auto-updates as new entries are posted

Milestone 4 — Mini-map on Tracker Feed

Compact map above the entry list on /tracker
Tap marker → navigates to that entry
Hidden when no entries have GPS

Three links in site header: Journal · Map · Stats

Manual Verification Required on Mobile

Upload photos → verify gallery grid + lightbox works
Upload photo → verify hero image on feed card
Open /post logged in → Get Location + Get Weather buttons work end-to-end
Submit full entry → verify all badges appear
Open /map on phone → pinch zoom (no page scroll behind map)
Open /tracker → tap mini-map marker → navigates to entry
Check browser console → no JS errors

UI Redesign (2026-06-18)

Design direction: Field Notes — editorial travel journal aesthetic, not social app.

Typography: DM Serif Display (headings) + DM Sans (UI/body) — loaded via Google Fonts
Accent color: Deep teal #1F6B5A (replaces generic blue)
Background: Warm paper #F7F5F2
Signature element: Full-bleed 16:9 hero photos on feed cards with translucent date/location overlay
Design tokens: user/themes/intotheeast/css/tokens.css — single source of truth for all values
Post form: GPS lat/lng fields hidden from UI (filled by JS), cleaner status feedback
Design spec: user/docs/design/design-spec.md
Implementation plan: docs/working/plans/2026-06-18-ui-redesign.md

Demo Content

Seven sample entries for design/QA showcasing: feed, map route, stats, weather variety (including snow).

make demo-load   # copy entries into tracker, clear cache
make demo-reset  # remove demo entries, clear cache

Full instructions: user/docs/demo/README.md

What Was Skipped

Background GPS tracking, social features, video reels, 3D flyover, printed books, AI itinerary builder — all require native apps or don't suit a solo personal blog. Full reasoning in docs/working/pm-analysis.md.

3.7 KiB Raw Blame History