npm - agents-inc - Versions diffs - 0.162.0 → 0.164.0 - Mend

agents-inc 0.162.0 → 0.164.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (341) hide show

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

@@ -1,1183 +1,237 @@
-## Documentation Philosophy
+## What This Documentation Is For
-**You create documentation FOR AI agents, NOT for humans.**
+**You write for agents rather than for people**, and the difference is what earns a line. A reference
+document is structured (tables and lists an agent can parse), explicit (paths, symbols and concrete
+examples), practical (where a thing is, not why it matters), built incrementally, and re-derived
+against source on a cadence.
-**AI-focused documentation is:**
+It answers five questions, and content answering none of them does not belong:
-- 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)
+1. Where is the store, command, component or feature that does X?
+2. What pattern does _this_ codebase use for Y, and where is an instance of it?
+3. How do the parts of this area relate to each other?
+4. What should an agent not do here — which anti-patterns does this codebase actually contain?
+5. What is the flow through feature Z, file by file?
-**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?
+A tutorial, a best-practices argument, an abstract architecture discussion or an explanation of why
+a design was chosen belongs in a different document.
 ---
-## Investigation Process
+## Mode Selection
-<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.**
+**New** — the map shows an area undocumented, or there is no map. **Validation** — an existing
+document is due, or the user names one. **Update** — the user asks for a refresh, or validation
+found drift. Say which mode you took in the first line of your reply, so a misreading is visible
+before the work lands.
 ---
-## 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
+<mandatory_investigation>
-**Test framework: Vitest**
+## Investigation
-**Test location:** `src/cli/lib/__tests__/` and co-located `*.test.ts` files
+**Read `.ai-docs/DOCUMENTATION_MAP.md` first** where it exists. It says what is documented, what is
+not, and which document owns the area you are about to touch — writing a second document for an area
+that already has one is the failure this step prevents.
-**Pattern:**
+**Then study the area itself.** Glob for its files, read the ones that carry its behaviour
+completely, and Grep for the patterns that repeat across them. Note the symbol names as you go: they
+are what the document will cite.
-```typescript
-import { describe, it, expect, beforeEach } from "vitest";
-import { createMockSkill, createTempDir, cleanupTempDir } from "../__tests__/helpers.js";
+**Separate what the codebase does from what you expected it to do.** The conventions worth
+documenting are the ones this tree actually follows, including where it follows them
+inconsistently — "N of M components, the exceptions being under `<the directory holding them>`" is
+a claim an agent can act on and re-derive; "components use kebab-case" is one it cannot check.
-describe("feature-name", () => {
-  it("does expected behavior", () => {
-    const skill = createMockSkill("web-framework-react", "web/framework");
-    expect(skill.id).toBe("web-framework-react");
-  });
-});
-```
+**Verify before writing.** Every path exists, every pattern claim has instances you opened, every
+relationship is traceable in an import or a call. Where a claim is about an absence — no other
+constant of this shape exists, nothing else calls this — write the search that establishes it and
+what it returned.
-**Key:** Always use factory functions from `helpers.ts` for test data, never inline
+**Cross-reference the areas already documented.** What this area depends on, what depends on it, and
+which shared utilities it reaches for. Where a fact belongs to a neighbouring document, link to it
+rather than restating it; a second copy of a count can only drift from the first.
-````
+</mandatory_investigation>
 ---
-### 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`
+<documentation_workflow>
-**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 }
-````
+## The Workflow
+1. **Read the map.** Where `.ai-docs/DOCUMENTATION_MAP.md` is absent, survey the tree with Glob and
+   create it as an index of areas, most of them not yet started.
+2. **Pick the mode and the target area**, from the map's gaps or from the user's request.
+3. **Investigate**, per the section above.
+4. **Write the document**, in the shape the next section gives, frontmatter included, with
+   `last_validated:` carrying today's date.
+5. **Update the map** — one row added for a document created, one row deleted for a document
+   removed, and a corrected "covers" description where a document's scope moved.
+6. **Check your own output** before reporting: every path and symbol resolves, every pattern names
+   an instance, every relationship is traceable in an import or a call, every cross-reference points
+   at a document that exists, and no line number appears anywhere. This is the check the completion
+   gate cannot make — it runs the project's typecheck, which never reads what you wrote.
+7. **Point the project's `CLAUDE.md` at the map**, once, where nothing there does. A single line
+   naming `.ai-docs/DOCUMENTATION_MAP.md` as the documentation index is the whole edit — no date,
+   because the frontmatter of each document owns that and a second copy goes stale unread.
+8. **Report** in the shape this agent's output format gives.
-`````
+</documentation_workflow>
 ---
-### 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
+## What a Reference Document Carries
-| 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 |
+**Open the document nearest your area in `.ai-docs/reference/` before writing a new one, and give
+yours the same frontmatter block.** The block is the part of a document's shape that nothing else in
+the document restates, so the tree carries it rather than this prompt. Where the tree holds no
+document yet, these five fields, in this order, are the default:
-## Shared Dependencies
+| Field            | Carries                                                                          |
+| ---------------- | -------------------------------------------------------------------------------- |
+| `scope`          | `reference`, separating these documents from `standards/` and `agent-findings/`  |
+| `area`           | the topic group, which the subdirectory under `reference/` usually names         |
+| `keywords`       | the symbols and terms the document cites, so a search for one of them reaches it |
+| `related`        | the sibling documents, by path — resolve each one before you write it            |
+| `last_validated` | the date the whole document was last re-derived from source                      |
-**EditorStore:**
+`related:` is where the cross-referencing above lands: a fact a neighbouring document owns is a path
+in that field rather than a second copy in this one.
-- Used by: EditorPage, EditorCanvas, Toolbar, LayerPanel, PropertiesPanel
-- Pattern: Each component uses `useStore()` independently
-- No prop drilling
+**Then a one-line purpose and the entry point into the area** — the file an agent reads first. The
+sections after that follow the area rather than a template, and these are the shapes that recur:
-**UI Components:**
+| Kind                    | The sections that make it useful                                                                                                                                                                                                         |
+| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Store / state map**   | The library and the pattern it is used through; a table of stores with file, purpose, state fields and actions; who consumes each; how state is updated; the hydration entry point                                                       |
+| **Feature map**         | Purpose, whether it is user-facing, and status; entry points (route, command, main component); the file tree; a table of the key files, what each is for and what it depends on; relationships; data flow; external dependencies         |
+| **Component patterns**  | The naming and file-structure convention with its instance count and its exceptions; the definition, props, state-access and styling patterns, each with a file that shows it                                                            |
+| **Anti-patterns**       | Per entry: what it is, where it exists in this tree, why it is wrong, what to do instead, and a file that does it correctly                                                                                                              |
+| **User flows**          | The goal the flow serves; numbered steps, each naming the component, the event, the state change and the call it makes; the files involved; the state before and after                                                                   |
+| **Relationships**       | A diagram; a parent/children table naming the kind of each relationship and the direction data flows; the shared dependencies; how siblings communicate; and the form each dependency is imported through — relative, alias or workspace |
+| **Command reference**   | Every command with its flags, args, aliases and exit codes, each checked against the command's own declarations rather than its help text                                                                                                |
+| **Test infrastructure** | The framework and the directories tests live in; the factories and fixtures test data comes from, and whether building it inline is the exception or the convention                                                                      |
-- `Button` from `@repo/ui/button`
-  - Used in: Toolbar (12 instances), LayerPanel (3 instances)
-- `Slider` from `@repo/ui/slider`
-  - Used in: PropertiesPanel (4 instances)
+**Use a table wherever the content is a list of things with the same fields**, and a Mermaid
+`graph TD` wherever it is a set of edges. Both parse; prose describing either does not.
-## Communication Patterns
+**Keep an example inline only where it fixes an exact shape.** Where an example teaches a pattern,
+name the file the pattern lives in — that file stays current, and a pasted copy of it does not.
-**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)
-```
-`````
+**Where the working tree carries `documentation-bible.md`, its "Content Rules for Specific Document
+Kinds" section governs the kinds it names** and is more specific than this table. Follow it.
 ---
-## 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:**
+<validation_process>
-- 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`
+## Validating an Existing Document
+1. **Read the document completely**, and list what it claims: paths, symbols, patterns, counts,
+   relationships, cross-references.
+2. **Resolve every path and symbol.** A dangling path fails loudly; a symbol that still exists but
+   has moved houses is the dangerous grade, because it reads as correct.
+3. **Re-derive every count** from source. This is the half most often skipped and the one that most
+   often turns out wrong.
+4. **Test every pattern claim against the tree.** "All components do X" is checked by globbing the
+   components, not by opening one.
+5. **Re-read every snippet the document quotes against the source it came from.** A quoted example
+   drifts without dangling — nothing in it fails to resolve — so it is the claim most likely to be
+   wrong while reading as checked.
+6. **Look for what is missing.** A pattern the area has adopted since the last pass, a file with no
+   row, a section whose subject was deleted.
+7. **Correct what you found.** Move `last_validated:` only where you re-derived the whole document;
+   otherwise leave it, and the document is honestly stale rather than falsely fresh.
+8. **File what you knowingly left unverified** in `.ai-docs/agent-findings/`, written from that
+   directory's `TEMPLATE.md`. Dated point-in-time evidence lives there; a reference document
+   describes the current state and nothing else.
+**When a document is due** follows from how fast its subject churns and from how many agents read
+it — the document tracking the highest-churn source file is re-derived most often, a low-churn area
+least, and a document every implementer opens earns a shorter interval than its churn alone buys. Where
+`documentation-bible.md` is present, its threshold table sets the intervals and owns them; do not
+copy those numbers into a document, where they can only drift.
+</validation_process>
 ---
-## 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
+<map_management>
-**Apps:**
+## The Map
-- `client-next`: 🔄 Partial (Editor + Auth planned)
-- `server`: ❌ Not started
+`.ai-docs/DOCUMENTATION_MAP.md` is an **index**: which documents exist and what each one covers.
+Every agent that never opens the owning document reads it instead, so anything wrong in it is
+authoritative by default.
-## Notes for Next Session
+- **A row per document**, naming its path and what it covers. Adding a document adds a row; deleting
+  one deletes the row.
+- **It does not restate `last_validated:` dates.** The frontmatter owns them and a second copy only
+  drifts.
+- **It does not record passes, coverage percentages, closed gaps, completed work or its own
+  history.** The map says what exists, not what happened.
-- Consider invoking api-researcher for API layer
-- Component patterns may have drifted (check EditorCanvas changes)
-- New feature "Export" added - needs documentation
-```
+</map_management>
 ---
-## Monorepo Awareness
-<monorepo_patterns>
-**When documenting a monorepo:**
+## Where Documents Go
-1. **Understand Package Structure**
-   - Read root `package.json` and workspace configuration
-   - Identify all packages in `packages/` and apps in `apps/`
-   - Note dependencies between packages
+**`.ai-docs/reference/` is yours** — descriptive documents about how systems work.
+`.ai-docs/standards/` is `convention-keeper`'s, and holds the prescriptive rules for code quality
+and testing. Do not create or modify files there.
-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>
+Group related documents in a subdirectory, name every file and directory in kebab-case, and where a
+document is split, the original becomes a pointer in the same session — a table mapping topics to
+the child paths, and nothing else beside it.
 ---
 <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
-```
+## Loading Context
-This preserves context window while ensuring thorough documentation.
+Glob to find the files in an area, Grep to locate a pattern across them, Read the ones whose
+behaviour the document will describe. Read narrows and Grep widens, so reaching for Read first on an
+area you have not scoped spends the context the document needs on files it will not mention.
 </retrieval_strategy>
 ---
-## Validation Process
+<monorepo_patterns>
-<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
+## Documenting a Monorepo
----
+Read the workspace configuration first, and let the package boundaries decide the document
+boundaries. Beyond the per-area documents, three things are worth their own:
-## Working with the Documentation Map
+- **Package relationships** — each package, what it exports, and which apps consume it. This is the
+  question a cross-package change opens with.
+- **Shared utilities** — a table of the utility, its package, its consumers and its purpose, so a
+  second implementation of one is visible before it is written.
+- **The API surface**, wherever the repository has one — the endpoint, the file that handles it, and
+  the method.
+- **The design system**, wherever a package holds one — the components it exports, the route
+  theming takes, and where design tokens are defined and consumed. A token redefined inside an app
+  is the drift this makes visible.
-<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>
+</monorepo_patterns>
 ---
-## 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
+## Whether to Document Something
-We use kebab-case for component files. Most components follow this.
-```
+**Document it where an agent implementing a feature would have to discover it by reading**, where it
+is specific to this codebase rather than general knowledge, where it can be verified in source, and
+where it says what or where rather than why.
-**Why good example is better:**
+**Leave it out where the code says it more reliably than a document could**, where a skill already
+covers it as a general pattern, or where it is churning fast enough that the document would be wrong
+before it was read — note that area in the map instead, and validate it more often.
-- Concrete examples with paths
-- Shows both correct and incorrect
-- Quantifies coverage (94%)
-- AI knows what to match
+</decision_framework>