diff --git a/docs/superpowers/specs/2026-06-21-documentation-restructure-design.md b/docs/superpowers/specs/2026-06-21-documentation-restructure-design.md new file mode 100644 index 0000000..2837e5b --- /dev/null +++ b/docs/superpowers/specs/2026-06-21-documentation-restructure-design.md @@ -0,0 +1,172 @@ +# Documentation Restructure — Design Spec + +**Date:** 2026-06-21 +**Scope:** Full restructure of `docs/` from organic flat layout to type-first hierarchy serving two personas: Mischa and Claude. + +--- + +## Problem + +The `docs/` folder grew organically: milestone specs, design specs, plans, QA docs, research, and how-tos sit at the same level with no clear navigation. There is no operational how-to for posting, GPX management, or trip switching. CLAUDE.md contains setup and architecture detail that inflates its size and makes it harder to scan. + +--- + +## Goals + +1. Two personas find what they need without searching: **Mischa** (poster, PM, designer, dev) and **Claude** (AI assistant). +2. `guides/` is written for Mischa now but extensible to external users later (future: publish as a Grav CMS travel setup). +3. CLAUDE.md stays lean — inline context only, no content duplicated from `docs/`. + +--- + +## Folder Structure + +``` +docs/ + guides/ ← operational how-tos; Mischa-facing; extensible to external users + reference/ ← stable facts: design system, architecture + working/ ← active project docs: specs, plans, QA, backlog, milestones + specs/ + plans/ + qa/ + milestones/ + research/ ← raw discovery input + README.md ← navigation index +``` + +### Persona mapping + +| Persona | Primary sections | +|---|---| +| Mischa (operational) | `guides/` for how-tos; `working/` for PM status | +| Mischa (design/dev) | `reference/` for design system + architecture | +| Claude | `working/specs/` + `working/plans/` for active context; `reference/` for stable facts; `CLAUDE.md` for always-loaded project rules | + +--- + +## File Migration + +### guides/ — new and extracted content + +| File | Source | +|---|---| +| `guides/posting.md` | new — end-to-end posting flow | +| `guides/gpx-manager.md` | new — GPX upload/delete/slug/Komoot workaround | +| `guides/trip-switching.md` | new — 3-file checklist, expanded | +| `guides/local-setup.md` | extracted from CLAUDE.md §2 | + +### reference/ — moved and new + +| File | Source | +|---|---| +| `reference/design-system.md` | moved from `docs/design/design-spec.md` | +| `reference/architecture.md` | new — stack, plugin roles, template hierarchy, post-submission data flow | + +### working/ — moved and renamed + +| New path | Current path | +|---|---| +| `working/specs/*` (13 files) | `docs/superpowers/specs/*` | +| `working/plans/*` (14 files) | `docs/superpowers/plans/*` | +| `working/milestones/milestone-1.md` | `docs/milestone-1-spec.md` | +| `working/milestones/milestone-2.md` | `docs/milestone-2-spec.md` | +| `working/milestones/milestone-3.md` | `docs/milestone-3-spec.md` | +| `working/milestones/milestone-4.md` | `docs/milestone-4-spec.md` | +| `working/backlog.md` | `docs/backlog.md` | +| `working/production-todo.md` | `docs/production-todo.md` | +| `working/pm-analysis.md` | `docs/pm-analysis.md` | +| `working/qa/test-plan.md` | `docs/qa-test-plan.md` | +| `working/qa/results.md` | `docs/qa-results.md` | +| `working/bugs-and-fixes.md` | `docs/bugs-and-fixes.md` | +| `working/summary.md` | `docs/summary.md` | + +### research/ — moved and renamed + +| New path | Current path | +|---|---| +| `research/polarsteps.md` | `docs/research-polarsteps.md` | +| `research/findpenguins.md` | `docs/research-findpenguins.md` | +| `research/story-editing.md` | `docs/research-story-editing.md` | + +--- + +## New Content + +### guides/posting.md + +Covers: opening `/post`, all form fields (title, body, location, weather fetch, lat/lng, photos), what happens on submit (form plugin → add-page-by-form → cache-on-save), how to verify the entry appeared, common failure modes (cache not cleared, entry in wrong trip folder). + +### guides/gpx-manager.md + +Covers: logging in, upload flow, slug rules (spaces/special chars → hyphens, lowercase), how slugification works (client-side Blob trick), delete flow, how to bypass the UI (drop file into `user/pages/01.trips//` + `make content-push`), Komoot manual export workaround (no API integration yet). + +### guides/trip-switching.md + +Covers: the 3-file checklist — `user/config/site.yaml` (`active_trip`), `user/pages/02.post/post-form.md` (`pageconfig.parent`) — why both must match, what breaks silently if they don't (entries post to wrong folder), and the new trip page tree to create under `user/pages/01.trips//`. + +### guides/local-setup.md + +Covers: first-time setup after clone (`mkdir -p user/plugins user/data`, `make setup`), fix-perms after 500 errors, Grav 2.0 upgrade process (update Dockerfile URL + `make setup`), required system.yaml settings (`accounts.type: flex`, `pages.type: flex`), admin user API permissions, disabling old `admin` plugin, language URL prefix fix. + +### reference/architecture.md + +Covers: +- **Stack**: Grav 2.0.0-rc.10 + Admin2, Docker image, PHP session config +- **Plugin roles**: form (built-in) → add-page-by-form (third-party) → cache-on-save (custom); what each does in the post-submission pipeline +- **Template hierarchy**: `base.html.twig` extended by all page templates; key templates: `trip.html.twig`, `entry.html.twig`, `map.html.twig`, `stats.html.twig`, `gpx-manager.html.twig` +- **Data flow for a post**: form submit → page created in dailies folder → cache cleared → entry visible in feed +- **GPX pipeline**: files on trip page media → picked up by `map.html.twig` via `trip_page.media.all` → rendered by MapLibre + +### docs/README.md + +```markdown +# docs/ + +## If you're Mischa +- **Doing something?** → guides/ +- **Checking project status?** → working/backlog.md, working/production-todo.md +- **Design or architecture decisions?** → reference/ + +## If you're Claude +- **Project rules + always-needed context** → CLAUDE.md (root) +- **Active specs and plans** → working/specs/, working/plans/ +- **Stable facts** → reference/ +- **Raw research** → research/ +``` + +--- + +## CLAUDE.md Changes + +**Remove** (moves to `docs/`): +- §2 local development setup → `docs/guides/local-setup.md`; replace with one-line pointer +- Architecture/plugin detail → `docs/reference/architecture.md`; replace with one-line pointer + +**Keep inline** (always-loaded context Claude needs without following a link): +- §0 project specifics (folder layout, stack versions, trip entity architecture, active trip, GPX pipeline, env rules, remote operations, content sync, gitignore) +- §1 environment modes (dev vs. prod settings, cache-on-save behaviour) +- Language URL prefix gotcha +- Grav 2.0 config requirements (flex accounts/pages, admin user permissions) + +--- + +## Out of Scope + +- End-user documentation (blog readers) — deferred until external publish decision +- `user/docs/` folder — separate git repo; not restructured here +- Memory files (`~/.claude/projects/*/memory/`) — not part of `docs/`; maintained separately +- Design/UX wireframes — stay in existing spec files, not reorganized further + +--- + +## Acceptance Criteria + +1. `docs/` contains exactly four subdirectories: `guides/`, `reference/`, `working/`, `research/` +2. All 32+ existing files are moved to their new paths; no files remain at `docs/` root except `README.md` +3. `docs/superpowers/` no longer exists; content is under `working/` +4. Four new guides exist and cover their stated scope +5. `reference/architecture.md` exists and covers stack, plugin roles, template hierarchy, and post data flow +6. `docs/README.md` exists with persona-based navigation +7. CLAUDE.md no longer contains §2 local setup block; contains pointer to `docs/guides/local-setup.md` +8. All internal cross-references in moved files updated to new paths +9. Memory files that reference `docs/superpowers/` paths updated to `docs/working/`