diff --git a/CLAUDE.md b/CLAUDE.md
index 70086afe..a3d9a594 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -184,6 +184,7 @@ patherly/
 │   │   │   ├── auth.ts
 │   │   │   ├── trees.ts
 │   │   │   └── sessions.ts
+│   │   ├── hooks/                  # Custom React hooks (useKeyboardShortcuts)
 │   │   ├── store/
 │   │   │   ├── authStore.ts        # Zustand auth state
 │   │   │   ├── themeStore.ts       # Dark/light theme
@@ -195,6 +196,7 @@ patherly/
 │   │   │   ├── tree-editor/        # Tree editor components
 │   │   │   ├── tree-preview/       # Visual tree preview
 │   │   │   ├── step-library/       # Step library browser, forms, modals
+│   │   │   ├── session/            # Session modals, scratchpad sidebar
 │   │   │   └── ui/                 # MarkdownContent
 │   │   ├── pages/
 │   │   │   ├── LoginPage.tsx
@@ -216,7 +218,7 @@ patherly/
 ├── LESSONS-LEARNED.md              # Bugs and fixes (READ THIS!)
 ├── PROGRESS.md                     # Detailed progress log
 ├── REBRAND-IMPLEMENTATION-GUIDE.md # Patherly → ResolutionFlow rebrand guide
-├── docs/plans/                     # Implementation plans
+├── docs/plans/                     # Design docs & implementation plans (YYYY-MM-DD-<topic>-design.md / -implementation.md)
 ├── 01-PROJECT-OVERVIEW.md          # Vision and goals
 ├── 02-TECHNICAL-ARCHITECTURE.md    # System design, API specs
 ├── 03-DEVELOPMENT-ROADMAP.md       # Phases and timeline
@@ -347,6 +349,10 @@ alembic revision --autogenerate -m "Description"
 alembic revision -m "Description"  # Edit migration file manually
 # Migration runs when DB is available - safe to commit without testing locally
 
+# Find current migration head (check down_revision in latest file)
+# Chain mixes numeric IDs (001-008) and hex hashes (e.g., 4cdb5cba1aff)
+# Always inspect the actual files — don't assume sequential ordering
+
 # Access PostgreSQL (no local psql needed)
 docker exec -it patherly_postgres psql -U postgres -d patherly
 ```
@@ -667,6 +673,8 @@ const response = await api.get('/api/v1/trees')
 - Commit message format: `type: description`
 - Types: `feat`, `fix`, `refactor`, `docs`, `test`, `chore`
 - Always include `Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>`
+- Always create a feature branch BEFORE committing new work (not retroactively after committing to main)
+- PR workflow: `git checkout -b feat/feature-name` → commit → `git push -u origin feat/feature-name` → `gh pr create`
 
 ### Commit Strategy for Large Features