docs: merge worktree-docs-restructure into main; move new superpowers/ files to working/
This commit is contained in:
@@ -0,0 +1,183 @@
|
||||
# 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/working/specs/*` |
|
||||
| `working/plans/*` (14 files) | `docs/working/plans/*` |
|
||||
| `working/milestones/milestone-1.md` | `docs/working/milestones/milestone-1.md` |
|
||||
| `working/milestones/milestone-2.md` | `docs/working/milestones/milestone-2.md` |
|
||||
| `working/milestones/milestone-3.md` | `docs/working/milestones/milestone-3.md` |
|
||||
| `working/milestones/milestone-4.md` | `docs/working/milestones/milestone-4.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
|
||||
|
||||
```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
|
||||
|
||||
**Add** (superpowers skill path overrides):
|
||||
|
||||
```markdown
|
||||
### Superpowers skill paths
|
||||
Specs: `docs/working/specs/YYYY-MM-DD-<topic>-design.md`
|
||||
Plans: `docs/working/plans/YYYY-MM-DD-<topic>.md`
|
||||
```
|
||||
|
||||
The brainstorming and writing-plans skills default to `docs/working/`; these lines override that default so generated files land in the right place automatically.
|
||||
|
||||
**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/working/` 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/working/` paths updated to `docs/working/`
|
||||
10. CLAUDE.md contains superpowers skill path overrides pointing to `docs/working/specs/` and `docs/working/plans/`
|
||||
Reference in New Issue
Block a user