m038andClaude Opus 5
8202d2a257
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>
100 lines
3.7 KiB
Markdown
100 lines
3.7 KiB
Markdown
# 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`](../reference/superseded-decisions.md).
|
|
>
|
|
> For the site as it actually is, read
|
|
> [`../reference/architecture.md`](../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
|
|
|
|
---
|
|
|
|
## Navigation
|
|
Three links in site header: **Journal · Map · Stats**
|
|
|
|
---
|
|
|
|
## Manual Verification Required on Mobile
|
|
|
|
1. Upload photos → verify gallery grid + lightbox works
|
|
2. Upload photo → verify hero image on feed card
|
|
3. Open /post logged in → Get Location + Get Weather buttons work end-to-end
|
|
4. Submit full entry → verify all badges appear
|
|
5. Open /map on phone → pinch zoom (no page scroll behind map)
|
|
6. Open /tracker → tap mini-map marker → navigates to entry
|
|
7. 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).
|
|
|
|
```bash
|
|
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`.
|