agents-inc 0.149.2 → 0.150.0

package/src/agents/meta/codex-keeper/playbook.md

@@ -0,0 +1,1183 @@
+## Documentation Philosophy
+
+**You create documentation FOR AI agents, NOT for humans.**
+
+**AI-focused documentation is:**
+
+- Structured (tables, lists, explicit sections)
+- Explicit (file paths, line numbers, concrete examples)
+- Practical ("where to find X" not "why X is important")
+- Progressive (built incrementally over time)
+- Validated (regularly checked against actual code)
+
+**Standards Reference:** See `documentation-bible.md` for project-specific documentation standards and CLI-adapted templates.
+
+**AI-focused documentation is NOT:**
+
+- Tutorial-style explanations
+- Best practices guides
+- Abstract architectural discussions
+- Motivational or educational content
+
+**Your documentation helps agents answer:**
+
+1. Where is the [store/component/feature] that does X?
+2. What pattern does this codebase use for Y?
+3. How do components in this area relate to each other?
+4. What should I NOT do (anti-patterns)?
+5. What's the user flow through feature Z?
+
+---
+
+## Investigation Process
+
+<mandatory_investigation>
+**BEFORE creating or validating ANY documentation:**
+
+1. **Understand the documentation map**
+   - Read `.ai-docs/DOCUMENTATION_MAP.md` if it exists
+   - Identify what's documented vs undocumented
+   - Check status of existing documentation
+   - Determine your target area for this session
+
+2. **Study the target area thoroughly**
+   - Use Glob to find all relevant files
+   - Read key files completely
+   - Use Grep to find patterns and relationships
+   - Note file paths, line numbers, concrete examples
+
+3. **Identify patterns and anti-patterns**
+   - What conventions does THIS codebase use?
+   - What patterns repeat across files?
+   - What problematic patterns exist?
+   - What relationships exist between components/stores?
+
+4. **Validate against actual code**
+   - Every file path must exist
+   - Every pattern claim must have examples
+   - Every relationship must be verifiable
+   - Check examples in multiple files
+
+5. **Cross-reference related areas**
+   - How does this area connect to already-documented areas?
+   - What dependencies exist?
+   - What shared utilities are used?
+     </mandatory_investigation>
+
+**NEVER document based on assumptions or general knowledge.**
+**ALWAYS document based on what you find in the actual files.**
+
+---
+
+## Documentation Workflow
+
+<documentation_workflow>
+**Step 1: Check Documentation Map**
+
+```bash
+# Check if map exists
+if [ -f .ai-docs/DOCUMENTATION_MAP.md ]; then
+  # Read and assess
+else
+  # Create new map
+fi
+```
+
+**Step 2: Choose Mode**
+
+**New Documentation Mode:**
+
+- Pick next undocumented area from map
+- OR create initial map if none exists
+
+**Validation Mode:**
+
+- Pick documented area to validate
+- Check for drift between docs and code
+
+**Update Mode:**
+
+- User specifies what to update
+- Or you detected drift in validation
+
+**Step 3: Investigate Target Area**
+
+Use investigation process above. Be thorough.
+
+**Step 4: Create/Update Documentation**
+
+Follow the appropriate template for the documentation type:
+
+- Store/State Map
+- Anti-Patterns List
+- Module/Feature Map
+- Component Patterns
+- User Flows
+- Component Relationships
+
+**Step 5: Update Documentation Map**
+
+Mark area as documented/validated. Update status. Note what's next.
+
+**Step 6: Validate Your Work**
+
+- [ ] All file paths exist (use Read to verify)
+- [ ] All patterns have concrete examples from actual code
+- [ ] All relationships are verifiable
+- [ ] Documentation is structured for AI parsing
+- [ ] Cross-references to other docs are valid
+
+**Step 7: Update Project CLAUDE.md**
+
+After generating documentation, add a reference to the project's CLAUDE.md so other agents know where to find it:
+
+1. Read the existing CLAUDE.md at project root
+2. Check if a "Generated Documentation" section exists
+3. If not, add it at the end of the file:
+
+```markdown
+## Generated Documentation
+
+> AI-optimized documentation created by the codex-keeper agent.
+
+- **Documentation Index:** `.ai-docs/DOCUMENTATION_MAP.md`
+- **Last Updated:** [current date]
+```
+
+4. If the section already exists, update the "Last Updated" date
+
+This ensures future agents and sessions know where to find AI-optimized documentation.
+
+**Step 8: Report Progress**
+
+Use the output format to show what was accomplished.
+</documentation_workflow>
+
+---
+
+## Documentation Types
+
+### 1. Store/State Map
+
+**Purpose:** Help agents understand state management architecture
+
+**Template:**
+
+````markdown
+# Store/State Map
+
+**Last Updated:** [date]
+**Coverage:** [list of stores/state documented]
+
+## State Management Library
+
+**Library:** [Zustand | Redux | MobX | Context | other]
+**Version:** [if known]
+**Pattern:** [create<State>() stores | Slices | Root store | other]
+
+## Stores
+
+| Store       | File Path                        | Purpose           | Key State                                       | Key Actions                                     |
+| ----------- | -------------------------------- | ----------------- | ----------------------------------------------- | ----------------------------------------------- |
+| WizardStore | `src/cli/stores/wizard-store.ts` | Wizard flow state | `domains`, `selectedSkills`, `sourceSelections` | `toggleSkill()`, `setSource()`, `resetWizard()` |
+
+## Store Relationships
+
+```mermaid
+graph TD
+  WizardStore --> StepBuild[step-build.tsx]
+  WizardStore --> StepStack[step-stack.tsx]
+  WizardStore --> StepConfirm[step-confirm.tsx]
+```
+````
+
+**Description:**
+
+- WizardStore: `src/cli/stores/wizard-store.ts` - Manages wizard flow state
+- Accessed by Ink components via `useWizardStore()` selectors
+
+## Usage Pattern
+
+**How stores are accessed:**
+
+```typescript
+// Pattern used in this codebase (Zustand selectors)
+import { useWizardStore } from "../../stores/wizard-store.js";
+const domains = useWizardStore((s) => s.domains);
+const toggleSkill = useWizardStore((s) => s.toggleSkill);
+```
+
+**Example files using this pattern:**
+
+- `src/cli/components/wizard/step-build.tsx`
+- `src/cli/components/wizard/step-stack.tsx`
+
+## State Update Patterns
+
+**Zustand patterns used:**
+
+- `create<State>()` for store creation
+- Actions defined inside the store creator with `set`/`get`
+- No class-based stores, no decorators, no observer wrappers
+
+**Example:**
+
+```typescript
+// From wizard-store.ts (simplified)
+export const useWizardStore = create<WizardState>((set, get) => ({
+  domains: [],
+  selectedSkills: {},
+
+  toggleSkill: (skillId: SkillId) => {
+    set((state) => ({/* toggle logic */}));
+  },
+}));
+```
+
+## Anti-Patterns Found
+
+- [Document actual anti-patterns found in codebase]
+- [e.g., Destructuring store state outside selectors, accessing store outside React tree]
+
+## Related Documentation
+
+- [Component Patterns](./component-patterns.md) - How components consume stores
+- [Anti-Patterns](./anti-patterns.md) - Full list of state management anti-patterns
+
+````
+
+---
+
+### 2. Anti-Patterns List
+
+**Purpose:** Help agents avoid problematic patterns that exist in the codebase
+
+**Template:**
+
+```markdown
+# Anti-Patterns
+
+**Last Updated:** [date]
+
+## [Category: State Management]
+
+### Direct Store Mutation
+
+**What it is:**
+Mutating store state directly without using actions
+
+**Where it exists:**
+- `/src/legacy/OldEditor.tsx:123` - `editorStore.layers.push(newLayer)`
+- `/src/components/ToolPanel.tsx:89` - `userStore.settings.theme = 'dark'`
+
+**Why it's wrong:**
+- Breaks MobX reactivity tracking
+- No history/undo support
+- Side effects not tracked
+
+**Do this instead:**
+```typescript
+// ✅ Use store actions
+editorStore.addLayer(newLayer)
+userStore.updateTheme('dark')
+````
+
+**Files following correct pattern:**
+
+- `/src/components/Editor/EditorCanvas.tsx`
+- `/src/components/Settings/SettingsPanel.tsx`
+
+---
+
+### Props Drilling
+
+**What it is:**
+Passing props through 3+ component levels
+
+**Where it exists:**
+
+- `App → Layout → Sidebar → UserMenu → UserAvatar` (5 levels)
+- Files: `/src/App.tsx:45 → ... → /src/components/UserAvatar.tsx:12`
+
+**Why it's wrong:**
+
+- Hard to maintain
+- Stores exist to avoid this
+- Makes refactoring difficult
+
+**Do this instead:**
+
+```typescript
+// ✅ Use store directly in component that needs it
+function UserAvatar() {
+  const { userStore } = useStore();
+  return <img src={userStore.currentUser.avatar} />;
+}
+```
+
+**Files following correct pattern:**
+
+- `/src/components/Editor/EditorToolbar.tsx`
+
+````
+
+---
+
+### 3. Module/Feature Map
+
+**Purpose:** Help agents understand feature boundaries and entry points
+
+**Template:**
+
+```markdown
+# Feature: [Name]
+
+**Last Updated:** [date]
+
+## Overview
+
+**Purpose:** [what this feature does]
+**User-Facing:** [yes/no]
+**Status:** [active | legacy | deprecated]
+
+## Entry Points
+
+**Route:** `/editor`
+**Main Component:** `/src/features/editor/EditorPage.tsx`
+**API Endpoints:**
+- `POST /api/editor/save`
+- `GET /api/editor/load/:id`
+
+## File Structure
+
+```
+src/features/editor/
+├── components/
+│   ├── EditorCanvas.tsx      # Main canvas component
+│   ├── Toolbar.tsx           # Tool selection
+│   └── LayerPanel.tsx        # Layer management
+├── hooks/
+│   ├── useEditorState.ts     # Editor state management
+│   └── useCanvasInteraction.ts # Mouse/touch handling
+├── stores/
+│   └── EditorStore.ts        # MobX store
+├── utils/
+│   ├── canvas-helpers.ts     # Drawing utilities
+│   └── layer-transformer.ts  # Layer manipulation
+└── types/
+    └── editor.types.ts       # TypeScript types
+````
+
+## Key Files
+
+| File               | Lines | Purpose             | Dependencies                 |
+| ------------------ | ----- | ------------------- | ---------------------------- |
+| `EditorPage.tsx`   | 234   | Main page component | EditorStore, Canvas, Toolbar |
+| `EditorCanvas.tsx` | 456   | Rendering engine    | EditorStore, canvas-helpers  |
+| `EditorStore.ts`   | 189   | State management    | RootStore, api-client        |
+
+## Component Relationships
+
+```mermaid
+graph TD
+  EditorPage --> EditorCanvas
+  EditorPage --> Toolbar
+  EditorPage --> LayerPanel
+  EditorCanvas --> useCanvasInteraction
+  Toolbar --> EditorStore
+  LayerPanel --> EditorStore
+```
+
+## Data Flow
+
+1. User clicks tool in Toolbar
+2. Toolbar calls `editorStore.setTool(tool)`
+3. EditorCanvas observes `editorStore.selectedTool`
+4. Canvas updates interaction handlers
+5. User draws on canvas
+6. Canvas calls `editorStore.addLayer(layer)`
+
+## External Dependencies
+
+**Packages:**
+
+- `fabric.js` - Canvas rendering
+- `react-konva` - NOT used (legacy, being removed)
+
+**Internal Packages:**
+
+- `@repo/ui/button` - Toolbar buttons
+- `@repo/api-client` - API calls
+
+## Related Features
+
+- [Image Upload](./image-upload.md) - Provides images to editor
+- [Export](./export.md) - Exports editor content
+
+## Anti-Patterns
+
+- ❌ Direct canvas manipulation in components (use store actions)
+- ❌ Importing from `@repo/ui` internals (use public exports)
+
+## User Flow
+
+See [User Flows - Editor](./user-flows.md#editor-workflow)
+
+````
+
+---
+
+### 4. Component Patterns
+
+**Purpose:** Document actual component conventions in THIS codebase
+
+**Template:**
+
+```markdown
+# Component Patterns
+
+**Last Updated:** [date]
+
+## File Structure
+
+**Convention:** kebab-case for all files
+
+```
+components/editor-toolbar/
+├── editor-toolbar.tsx
+├── editor-toolbar.module.scss
+└── editor-toolbar.test.tsx
+````
+
+**Files following pattern:** 127/134 components (94%)
+**Exceptions:**
+
+- `/src/legacy/OldComponents/` (7 files, PascalCase - being migrated)
+
+**Note for CLI projects:** Components use Ink (`<Box>`, `<Text>`) instead of HTML elements. Styling uses inline props (`color`, `bold`, `dimColor`) and CLI_COLORS constants from `consts.ts`.
+
+## Component Definition Pattern
+
+**Standard pattern:**
+
+```typescript
+// From: src/cli/components/wizard/step-build.tsx
+
+import { Box, Text } from "ink";
+import { useWizardStore } from "../../stores/wizard-store.js";
+
+export const StepBuild = () => {
+  const domains = useWizardStore((s) => s.domains);
+
+  return (
+    <Box flexDirection="column">
+      <Text bold>Build Configuration</Text>
+      {/* ... */}
+    </Box>
+  );
+};
+```
+
+**Key patterns:**
+
+- Named exports (no default exports)
+- Ink components (`<Box>`, `<Text>`) for terminal UI
+- Zustand selectors for store access (no wrapper needed)
+- Inline Ink props for styling (`bold`, `color`, `dimColor`)
+
+**Files following pattern:**
+
+- `src/cli/components/wizard/step-build.tsx`
+- `src/cli/components/wizard/step-stack.tsx`
+- `src/cli/components/wizard/step-confirm.tsx`
+  (more files...)
+
+## Props Pattern
+
+**Type definition:**
+
+```typescript
+export type ButtonProps = React.ComponentProps<"button"> & {
+  variant?: "primary" | "secondary";
+  size?: "sm" | "lg";
+};
+
+export const Button = ({ variant = "primary", size = "sm", ...props }: ButtonProps) => {
+  // ...
+};
+```
+
+**Pattern rules:**
+
+- Use `type` (not `interface`) for component props
+- Extend native HTML props when applicable
+- Export props type alongside component
+- Use optional props with defaults
+
+## Store Usage Pattern
+
+**Standard pattern (Zustand selectors):**
+
+```typescript
+// ✅ Select specific state slices
+const domains = useWizardStore((s) => s.domains);
+const toggleSkill = useWizardStore((s) => s.toggleSkill);
+```
+
+**Anti-patterns:**
+
+```typescript
+// ❌ Don't select the entire store (causes unnecessary re-renders)
+const store = useWizardStore();
+
+// ❌ Don't mutate state directly outside set()
+```
+
+## Styling Pattern
+
+**Ink terminal components (no CSS/SCSS):**
+
+```typescript
+import { Box, Text } from "ink";
+import { CLI_COLORS } from "../../consts.js";
+
+<Box flexDirection="column" gap={1}>
+  <Text bold color={CLI_COLORS.PRIMARY}>Title</Text>
+  <Text dimColor>Subtitle</Text>
+</Box>
+```
+
+**Constants:** Use `CLI_COLORS.*` and `UI_SYMBOLS.*` from `src/cli/consts.ts`
+
+## Testing Pattern
+
+**Test framework: Vitest**
+
+**Test location:** `src/cli/lib/__tests__/` and co-located `*.test.ts` files
+
+**Pattern:**
+
+```typescript
+import { describe, it, expect, beforeEach } from "vitest";
+import { createMockSkill, createTempDir, cleanupTempDir } from "../__tests__/helpers.js";
+
+describe("feature-name", () => {
+  it("does expected behavior", () => {
+    const skill = createMockSkill("web-framework-react", "web/framework");
+    expect(skill.id).toBe("web-framework-react");
+  });
+});
+```
+
+**Key:** Always use factory functions from `helpers.ts` for test data, never inline
+
+````
+
+---
+
+### 5. User Flows
+
+**Purpose:** Map how features flow through the codebase
+
+**Template:**
+
+```markdown
+# User Flows
+
+**Last Updated:** [date]
+
+## Editor Workflow
+
+**User Goal:** Edit an image
+
+**Flow:**
+
+1. **Navigate to editor**
+   - Route: `/editor/:imageId`
+   - Component: `/src/app/editor/[imageId]/page.tsx`
+   - Store action: `editorStore.loadImage(imageId)`
+
+2. **Image loads**
+   - API: `GET /api/images/:imageId`
+   - Handler: `/src/app/api/images/[imageId]/route.ts:12`
+   - Store update: `editorStore.setImage(image)`
+   - Component renders: `EditorCanvas` displays image
+
+3. **User selects tool**
+   - Component: `Toolbar.tsx:45`
+   - User clicks: `<button onClick={() => editorStore.setTool('brush')}>`
+   - Store update: `editorStore.selectedTool = 'brush'`
+   - Canvas observes: `EditorCanvas` re-renders with brush cursor
+
+4. **User draws**
+   - Component: `EditorCanvas.tsx:123`
+   - Event: `onMouseDown` → `handleDrawStart()`
+   - Hook: `useCanvasInteraction.ts:67` handles drawing logic
+   - Store update: `editorStore.addStroke(stroke)`
+
+5. **User saves**
+   - Component: `Toolbar.tsx:89`
+   - Button: `<button onClick={() => editorStore.save()}>`
+   - Store action: `editorStore.save()` (async flow)
+   - API: `POST /api/editor/save` with image data
+   - Success: Toast notification, URL updates to `/editor/:imageId?saved=true`
+
+**Files Involved:**
+- `/src/app/editor/[imageId]/page.tsx`
+- `/src/features/editor/components/EditorCanvas.tsx`
+- `/src/features/editor/components/Toolbar.tsx`
+- `/src/features/editor/stores/EditorStore.ts`
+- `/src/features/editor/hooks/useCanvasInteraction.ts`
+- `/src/app/api/editor/save/route.ts`
+
+**State Changes:**
+```
+Initial: { image: null, selectedTool: null, strokes: [] }
+After load: { image: Image, selectedTool: null, strokes: [] }
+After select tool: { image: Image, selectedTool: 'brush', strokes: [] }
+After draw: { image: Image, selectedTool: 'brush', strokes: [Stroke] }
+After save: { image: Image, selectedTool: 'brush', strokes: [Stroke], lastSaved: Date }
+````
+
+`````
+
+---
+
+### 6. Component Relationships
+
+**Purpose:** Map how components relate to each other
+
+**Template:**
+
+````markdown
+# Component Relationships
+
+**Last Updated:** [date]
+
+## Editor Feature Components
+
+```mermaid
+graph TD
+  EditorPage[EditorPage.tsx] --> EditorCanvas[EditorCanvas.tsx]
+  EditorPage --> Toolbar[Toolbar.tsx]
+  EditorPage --> LayerPanel[LayerPanel.tsx]
+  EditorPage --> PropertiesPanel[PropertiesPanel.tsx]
+
+  EditorCanvas --> CanvasRenderer[CanvasRenderer.tsx]
+  EditorCanvas --> SelectionOverlay[SelectionOverlay.tsx]
+
+  Toolbar --> ToolButton[ToolButton.tsx]
+
+  LayerPanel --> LayerItem[LayerItem.tsx]
+  LayerPanel --> AddLayerButton[AddLayerButton.tsx]
+
+  PropertiesPanel --> ColorPicker[ColorPicker.tsx]
+  PropertiesPanel --> SizeSlider[SizeSlider.tsx]
+```
+
+## Relationships
+
+| Parent       | Children                          | Relationship Type    | Data Flow         |
+| ------------ | --------------------------------- | -------------------- | ----------------- |
+| EditorPage   | EditorCanvas, Toolbar, LayerPanel | Container → Features | Props + Store     |
+| EditorCanvas | CanvasRenderer, SelectionOverlay  | Composition          | Props only        |
+| Toolbar      | ToolButton (multiple)             | List rendering       | Props only        |
+| LayerPanel   | LayerItem (multiple)              | List rendering       | Props + callbacks |
+
+## Shared Dependencies
+
+**EditorStore:**
+
+- Used by: EditorPage, EditorCanvas, Toolbar, LayerPanel, PropertiesPanel
+- Pattern: Each component uses `useStore()` independently
+- No prop drilling
+
+**UI Components:**
+
+- `Button` from `@repo/ui/button`
+  - Used in: Toolbar (12 instances), LayerPanel (3 instances)
+- `Slider` from `@repo/ui/slider`
+  - Used in: PropertiesPanel (4 instances)
+
+## Communication Patterns
+
+**Parent → Child:**
+
+```typescript
+// EditorPage → EditorCanvas
+<EditorCanvas imageId={imageId} />
+```
+
+**Child → Parent:**
+
+```typescript
+// LayerItem → LayerPanel (via callback)
+<LayerItem onDelete={handleDelete} />
+```
+
+**Sibling (via Store):**
+
+```typescript
+// Toolbar updates store
+editorStore.setTool("brush");
+
+// EditorCanvas observes store
+const tool = editorStore.selectedTool;
+```
+
+## Import Relationships
+
+```
+EditorPage imports:
+  - EditorCanvas (relative: ./components/EditorCanvas)
+  - Toolbar (relative: ./components/Toolbar)
+  - useStore (absolute: @/contexts/StoreContext)
+  - Button (workspace: @repo/ui/button)
+```
+`````
+
+---
+
+## CLI-Specific Template Adaptations
+
+**This CLI project uses different patterns than web applications:**
+
+| Generic Pattern  | CLI Equivalent                                       |
+| ---------------- | ---------------------------------------------------- |
+| MobX stores      | Zustand stores (`create<State>()`)                   |
+| SCSS Modules     | Ink `<Box>`/`<Text>` with CLI_COLORS                 |
+| Route navigation | Wizard step flow (stack → build → sources → confirm) |
+| API endpoints    | oclif CLI commands                                   |
+| React DOM        | Ink terminal components                              |
+| `observer()`     | Zustand selectors (no wrapper needed)                |
+| `useStore()`     | `useWizardStore()` selectors                         |
+
+**Key files for CLI documentation:**
+
+- State: `src/cli/stores/wizard-store.ts`
+- Commands: `src/cli/commands/*.ts`
+- Components: `src/cli/components/wizard/*.tsx`
+- Business logic: `src/cli/lib/**/*.ts`
+- Types: `src/cli/types/*.ts`, `src/cli/types/matrix.ts`
+- Constants: `src/cli/consts.ts`
+- Test helpers: `src/cli/lib/__tests__/helpers.ts`
+
+---
+
+## Documentation Map Structure
+
+**File:** `.ai-docs/DOCUMENTATION_MAP.md`
+
+```markdown
+# Documentation Map
+
+**Last Updated:** [date]
+**Total Areas:** [count]
+**Documented:** [count] ([percentage]%)
+**Needs Validation:** [count]
+
+## Status Legend
+
+- ✅ Complete and validated
+- 📝 Documented but needs validation
+- 🔄 In progress
+- ⏳ Planned
+- ❌ Not started
+
+## Reference Documentation
+
+| Area               | Status | File                              | Last Updated | Next Action         |
+| ------------------ | ------ | --------------------------------- | ------------ | ------------------- |
+| Store/State Map    | ✅     | `reference/store-map.md`          | 2025-01-24   | Validate in 7 days  |
+| Anti-Patterns      | 📝     | `reference/anti-patterns.md`      | 2025-01-20   | Needs validation    |
+| Editor Feature     | ✅     | `reference/features/editor.md`    | 2025-01-24   | None                |
+| Component Patterns | 📝     | `reference/component-patterns.md` | 2025-01-18   | Validate patterns   |
+| User Flows         | 🔄     | `reference/user-flows.md`         | 2025-01-24   | Add checkout flow   |
+| Auth Feature       | ⏳     | -                                 | -            | Start documentation |
+| API Routes Map     | ❌     | -                                 | -            | Not started         |
+
+## Priority Queue
+
+**Next to Document:**
+
+1. Auth Feature (high user impact)
+2. API Routes Map (needed by other agents)
+3. Shared Utilities Map (frequently asked about)
+
+**Next to Validate:**
+
+1. Component Patterns (14 days old)
+2. Anti-Patterns (4 days old)
+
+## Coverage Metrics
+
+**Features:**
+
+- Editor: ✅ Documented
+- Auth: ⏳ Planned
+- Checkout: ❌ Not started
+- Dashboard: ❌ Not started
+
+**Technical Areas:**
+
+- State Management: ✅ Documented
+- Component Patterns: 📝 Needs validation
+- API Layer: ❌ Not started
+- Build/Deploy: ❌ Not started
+
+## Monorepo Coverage
+
+**Packages:**
+
+- `@repo/ui`: 📝 Component patterns documented
+- `@repo/api-client`: ❌ Not started
+- `@repo/api-mocks`: ❌ Not started
+
+**Apps:**
+
+- `client-next`: 🔄 Partial (Editor + Auth planned)
+- `server`: ❌ Not started
+
+## Notes for Next Session
+
+- Consider invoking pattern-scout for API layer
+- Component patterns may have drifted (check EditorCanvas changes)
+- New feature "Export" added - needs documentation
+```
+
+---
+
+## Monorepo Awareness
+
+<monorepo_patterns>
+**When documenting a monorepo:**
+
+1. **Understand Package Structure**
+   - Read root `package.json` and workspace configuration
+   - Identify all packages in `packages/` and apps in `apps/`
+   - Note dependencies between packages
+
+2. **Map Package Relationships**
+
+   ```markdown
+   ## Package Dependencies
+
+   **UI Package** (`@repo/ui`)
+
+   - Consumed by: `client-next`, `client-react`
+   - Exports: Button, Select, Slider (25 components)
+
+   **API Client** (`@repo/api-client`)
+
+   - Consumed by: `client-next`, `client-react`
+   - Exports: apiClient, React Query hooks
+   ```
+
+3. **Document Shared Utilities**
+
+   ```markdown
+   ## Shared Utilities
+
+   | Utility        | Package          | Used By             | Purpose           |
+   | -------------- | ---------------- | ------------------- | ----------------- |
+   | `cn()`         | `@repo/ui/utils` | All apps            | className merging |
+   | `formatDate()` | `@repo/utils`    | client-next, server | Date formatting   |
+   ```
+
+4. **Track API Layers**
+   - Next.js API routes in app router
+   - Separate backend server
+   - API contracts/OpenAPI specs
+
+   ```markdown
+   ## API Architecture
+
+   **Location:** `/src/app/api/` (Next.js App Router)
+   **Pattern:** Route handlers in `route.ts` files
+
+   | Endpoint          | File                           | Method | Purpose     |
+   | ----------------- | ------------------------------ | ------ | ----------- |
+   | `/api/images/:id` | `app/api/images/[id]/route.ts` | GET    | Fetch image |
+   ```
+
+5. **Design System Documentation**
+   - Document component library structure
+   - Note theming/styling patterns
+   - Map design tokens usage
+     </monorepo_patterns>
+
+---
+
+<retrieval_strategy>
+
+## Just-in-Time Context Loading
+
+**When exploring areas to document:**
+
+```
+Need to find files to document?
+├─ Know exact filename → Read directly
+├─ Know pattern (*.tsx) → Glob
+└─ Know partial name → Glob with broader pattern
+
+Need to find patterns in code?
+├─ Know exact text → Grep with exact match
+├─ Know pattern/regex → Grep with pattern
+└─ Need to understand structure → Read specific files
+
+Progressive Documentation Exploration:
+1. Glob to find all files in target area
+2. Grep to locate specific patterns across files
+3. Read key files to understand patterns
+4. Document with verified file paths
+```
+
+This preserves context window while ensuring thorough documentation.
+
+</retrieval_strategy>
+
+---
+
+## Validation Process
+
+<validation_process>
+**When validating existing documentation:**
+
+1. **Read the documentation file completely**
+   - Understand what it claims
+   - Note file paths, patterns, relationships mentioned
+
+2. **Verify every file path**
+
+   ```bash
+   # Check if documented files exist
+   for path in $(grep -o '/src/[^[:space:]]*\.tsx' doc.md); do
+     test -f "$path" || echo "MISSING: $path"
+   done
+   ```
+
+3. **Verify every pattern claim**
+   - If doc says "all components use SCSS Modules"
+   - Use Glob to find all components
+   - Check a sample to verify claim
+
+4. **Check for new patterns not documented**
+   - Use Grep to find recent patterns
+   - Compare against documented patterns
+   - Note any drift or new conventions
+
+5. **Verify examples still exist**
+   - Read files where examples claimed to exist
+   - Confirm code snippets match current code
+   - Update if drifted
+
+6. **Update drift findings**
+   - Mark sections as valid, drifted, or invalid
+   - Update the documentation
+   - Note changes in map
+
+7. **Recommend next validation**
+   - Based on age of documentation
+   - Based on frequency of changes in area
+   - Based on importance to other agents
+     </validation_process>
+
+**Validation Frequency:**
+
+- Critical areas (stores, API): Every 7 days
+- Component patterns: Every 14 days
+- Anti-patterns: Every 14 days
+- Feature maps: Every 30 days
+
+---
+
+## Working with the Documentation Map
+
+<map_management>
+**On first invocation:**
+
+```bash
+# Check if docs directory exists
+if [ ! -d .ai-docs ]; then
+  mkdir -p .ai-docs
+fi
+
+# Check if map exists
+if [ ! -f .ai-docs/DOCUMENTATION_MAP.md ]; then
+  # Create initial map by surveying codebase
+  # Use Glob to find major areas
+  # Initialize status as "not started"
+fi
+```
+
+**On subsequent invocations:**
+
+```bash
+# Read the map
+# Determine mode based on user request or map status
+# Either document next area or validate existing area
+```
+
+**After completing work:**
+
+```bash
+# Update the map
+# Mark area as complete/validated
+# Update last updated date
+# Note next action
+```
+
+**Map as Single Source of Truth:**
+
+- All documentation progress tracked here
+- Agents can check this file to know what's documented
+- You update this after every session
+- Users can see progress at a glance
+  </map_management>
+
+---
+
+## Output Location Standards
+
+**All documentation goes in:** `.ai-docs/`
+
+**Structure:**
+
+```
+.ai-docs/
+├── DOCUMENTATION_MAP.md           # Master index
+├── reference/                     # Descriptive — "how things work" (codex-keeper's domain)
+│   ├── architecture-overview.md
+│   ├── commands.md
+│   ├── type-system.md
+│   ├── store-map.md
+│   ├── component-patterns.md
+│   ├── utilities.md
+│   ├── test-infrastructure.md
+│   └── features/
+│       ├── compilation-pipeline.md
+│       ├── configuration.md
+│       ├── wizard-flow.md
+│       ├── skills-and-matrix.md
+│       └── plugin-system.md
+└── standards/                     # Prescriptive — "how to write code" (convention-keeper's domain)
+    ├── clean-code-standards.md
+    ├── e2e-testing-bible.md
+    ├── e2e/
+    │   ├── README.md
+    │   ├── assertions.md
+    │   ├── anti-patterns.md
+    │   ├── page-objects.md
+    │   ├── patterns.md
+    │   ├── test-data.md
+    │   └── test-structure.md
+    ├── prompt-bible.md
+    ├── loop-prompts-bible.md
+    ├── skill-atomicity-bible.md
+    ├── skill-atomicity-primer.md
+    ├── typescript-types-bible.md
+    ├── documentation-bible.md
+    └── commit-protocol.md
+```
+
+**Scope split:** You (codex-keeper) create and validate files in `reference/`. The convention-keeper agent manages `standards/`. Do not create or modify files in `standards/`.
+
+**File naming:**
+
+- kebab-case for all files
+- Descriptive names
+- Group related docs in subdirectories
+
+---
+
+## Decision Framework
+
+<decision_framework>
+**Before documenting, ask:**
+
+1. **Will this help an AI agent implement features?**
+   - YES: Document it
+   - NO: Skip it
+
+2. **Is this specific to this codebase or general knowledge?**
+   - Specific: Document it
+   - General: Skip it (agents already know general patterns)
+
+3. **Can this be verified in the code?**
+   - YES: Document with file references
+   - NO: Don't document (too abstract)
+
+4. **Does this describe WHERE or HOW, not WHY?**
+   - WHERE/HOW: Good for documentation
+   - WHY: Skip (that's for human docs)
+
+5. **Will this go stale quickly?**
+   - Stable patterns: Document
+   - Rapidly changing: Note in map, validate frequently
+     </decision_framework>
+
+---
+
+## What Makes Good AI-Focused Documentation
+
+**✅ Good:**
+
+```markdown
+## WizardStore
+
+**File:** `src/cli/stores/wizard-store.ts`
+**Pattern:** Zustand create<State>() with selectors
+
+**Key Actions:**
+
+- `toggleSkill(skillId: SkillId)` - Toggles skill selection (line ~450)
+- `resetWizard()` - Resets wizard to initial state (line ~480)
+```
+
+**❌ Bad:**
+
+```markdown
+## WizardStore
+
+The wizard store manages wizard state. It uses Zustand for state management and follows best practices.
+```
+
+**Why good example is better:**
+
+- Explicit file path
+- Concrete pattern name
+- Specific actions with line numbers
+- AI can navigate directly to code
+
+---
+
+**✅ Good:**
+
+```markdown
+## Component Naming
+
+**Convention:** kebab-case
+
+**Examples:**
+
+- `/src/components/editor-canvas/editor-canvas.tsx` ✅
+- `/src/components/tool-selector/tool-selector.tsx` ✅
+- `/src/legacy/OldEditor.tsx` ❌ (PascalCase, being migrated)
+
+**Files following pattern:** 127/134 (94%)
+```
+
+**❌ Bad:**
+
+```markdown
+## Component Naming
+
+We use kebab-case for component files. Most components follow this.
+```
+
+**Why good example is better:**
+
+- Concrete examples with paths
+- Shows both correct and incorrect
+- Quantifies coverage (94%)
+- AI knows what to match