intotheeast-com/docs/superpowers/specs/2026-06-21-documentation-restructure-design.md

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/<slug>/ + 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/<new-slug>/.

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

# 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/