docs: update CLAUDE.md, bugs log, and posting pipeline for Grav 2.0 + trip entity

- CLAUDE.md: add Grav 2.0 upgrade method, Admin2 setup, trip entity architecture, updated paths
- bugs-and-fixes.md: fix stale paths, add BUG-004 (Admin2 empty dashboard) and BUG-005 (PHP session path)
- posting-pipeline.md: update paths to trips/dailies structure

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -9,6 +9,24 @@
 - **./**: Grav CMS dev environment for intotheeast travel blog
 - **scripts/**: Server install and maintenance scripts
 - **user/**: Site content, config, pages, and theme (standalone git repo — do not modify from here)
+- **docs/**: All plans, specs, and project documentation (moved here from `user/docs/` on 2026-06-19)
+
+### Current stack
+
+- **Grav:** 2.0.0-rc.9 (installed manually — see §3 below)
+- **Admin:** Admin2 v2.0.0-rc.15 (plugin slug: `admin2`, NOT `admin`)
+- **Docker image:** `getgrav/grav` with `GRAV_CHANNEL=beta`
+- **PHP session:** `session.save_path = /tmp` set in `php/php-local.ini`
+
+### Trip entity architecture
+
+The site is structured around Trip entities. Key facts:
+- Active trip is set in `user/config/site.yaml` → `active_trip: japan-korea-2026`
+- Trip pages live at `user/pages/01.trips/<slug>/`
+- Each trip has: `01.dailies/`, `02.map/`, `03.stats/`, `04.stories/`
+- Nav in `base.html.twig` derives all links from `config.site.active_trip`
+- Post form parent (`post-form.md` → `pageconfig.parent`) **must be kept in sync** with `active_trip`
+- GPX route files live as media on the trip page itself, served via leaflet-gpx CDN
 
 ### Environment
 
@@ -23,6 +41,8 @@ Always use `make` commands for anything on the production server (`make remote-i
 - `make content-push` — commit and push `user/` to Gitea (triggers production pull via webhook)
 - `make content-pull` — pull latest from Gitea to local
 - `plugins.txt` is manually maintained — installing a plugin via Admin does NOT update it
+- `make demo-load` — load demo entries for both trips (Japan/Korea 2026 + Italy 2025 with real GPX)
+- `make demo-reset` — remove demo entries (keeps trip page structure, removes entries only)
 
 ### User repo gitignore
 
@@ -52,7 +72,7 @@ Before going live, change in `user/config/system.yaml`:
 |---|---|---|
 | `twig.cache` | `true` | Templates compiled once and reused; safe because theme files don't change at runtime |
 
-**Pre-launch smoke test required:** with `twig.cache: true`, submit one post via `/post` and confirm the entry appears in `/tracker` immediately. This verifies the cache-on-save plugin (BUG-001 fix) works correctly with caching enabled.
+**Pre-launch smoke test required:** with `twig.cache: true`, submit one post via `/post` and confirm the entry appears in `/trips/japan-korea-2026/dailies` immediately. This verifies the cache-on-save plugin (BUG-001 fix) works correctly with caching enabled.
 
 ### What the cache-on-save plugin handles
 
@@ -77,6 +97,58 @@ run `make fix-perms`. This creates uid 1000 in the container, chowns `/var/www/h
 and reloads Apache. Always run `make setup` (not just `make start`) after `docker compose down && up`
 to ensure permissions are correct.
 
+### Grav 2.0 upgrade (local)
+
+GPM (`php bin/gpm selfupgrade`) does **not** serve Grav 2.0 RC — it still reports 1.7.x as latest even on the `testing` channel. To upgrade locally:
+
+```bash
+# Download grav-admin bundle (includes Grav core + admin2 plugin)
+docker exec -w /tmp intotheeast_grav bash -c "
+  curl -sL 'https://getgrav.org/download/core/grav-admin/2.0.0-rc.9?testing' -o grav-admin.zip && \
+  unzip -q grav-admin.zip
+"
+# Copy core files only (not user/)
+docker exec -w /tmp intotheeast_grav bash -c "
+  cp -rf grav-admin/{assets,bin,system,vendor,webserver-configs,index.php,composer.json,composer.lock,robots.txt,CHANGELOG.md,LICENSE.txt} /var/www/html/
+"
+# Install Admin2 from the bundle (it's named admin2, not admin)
+docker exec -w /tmp intotheeast_grav bash -c "
+  cp -rf grav-admin/user/plugins/admin2 /var/www/html/user/plugins/admin2
+"
+make fix-perms
+docker exec -w /var/www/html intotheeast_grav php bin/grav cache --all
+# Cleanup
+docker exec intotheeast_grav rm -rf /tmp/grav-admin /tmp/grav-admin.zip
+```
+
+After upgrading, ensure these settings in `user/config/system.yaml`:
+```yaml
+accounts:
+  type: flex      # required for Admin2 API
+pages:
+  type: flex      # required for Admin2 pages API
+```
+
+And ensure the admin user account has `api.*` permissions (Admin2 uses a new permission namespace):
+```yaml
+# user/accounts/<username>.yaml
+access:
+  admin:
+    login: true
+    super: true
+  api:
+    super: true
+    access: true
+```
+
+**Disable the old `admin` plugin** once `admin2` is installed — both route to `/admin` and conflict:
+```bash
+# In user/plugins/admin/admin.yaml:
+enabled: false
+```
+
+**JWT secret:** Leave `jwt_secret: ''` in `user/plugins/api/api.yaml` — it works for local dev and production installs generate a secure secret automatically.
+
 ### Language URL prefix
 
 If Grav redirects to `/en/...` URLs, ensure `user/config/system.yaml` contains: