Add .claude/rules/ for contextual convention enforcement

Extract coding conventions from CLAUDE.md into 4 modular rules files
(typescript, webview, yaml-operations, testing) that load contextually
when editing matching file patterns.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: ansonphong

.claude/rules/testing.md

@@ -0,0 +1,34 @@
+# Rules: Testing
+
+Applies when creating or modifying files in `src/**/*.test.ts` or `src/test/`.
+
+## Unit Tests (Vitest)
+
+- All unit tests use Vitest — run with `npm test` (includes typecheck) or `npm run test:watch`
+- VS Code API is mocked via `src/__mocks__/vscode.ts` — aliased in `vitest.config.ts`
+- **Never create inline VS Code mocks** — always use the shared mock file
+- Test files live alongside source: `src/codexModel.test.ts`, `src/search/tokenizer.test.ts`
+- Coverage: `npm run test:coverage` — v8 provider, reports to `./coverage/`
+
+## Integration Tests (@vscode/test-electron)
+
+- Live in `src/test/suite/` — compiled separately via `tsconfig.test.json` → `out/test/`
+- Use Mocha (not Vitest) — the test-electron runner requires it
+- Fixture workspace: `src/test/fixtures/workspace/test.codex.yaml`
+- Require a display server — use `xvfb-run` on CI
+- Test real extension activation, command registration, tree provider context
+
+## TDD Pattern
+
+When adding new features:
+1. Write failing test first
+2. Run `npm test` to confirm it fails
+3. Implement minimal code to pass
+4. Run `npm test` to confirm it passes
+5. Refactor if needed, re-run tests
+
+## Config Split
+
+- `tsconfig.json` excludes test files (`src/**/*.test.ts`, `src/__mocks__/**`, `src/test/**`)
+- `tsconfig.test.json` includes only integration test files
+- Vitest handles its own module resolution for unit tests

.claude/rules/typescript.md

@@ -0,0 +1,25 @@
+# Rules: TypeScript Conventions
+
+Applies when creating or modifying `.ts` files in `src/`.
+
+## Hard Rules
+
+- **Async file ops only** — Use `fs.promises` (readFile, writeFile, stat, etc.). Never use sync variants (`readFileSync`, `writeFileSync`, `statSync`, etc.). The extension runs in VS Code's extension host — sync I/O blocks the UI.
+- **No `as any` type bypasses** — Use proper typing. If you need to attach metadata to an object, use a `WeakMap` (see `panelResolverKeys` pattern in `writerView/manager.ts`).
+- **Path traversal validation** — Always call `isPathWithinWorkspace()` + `path.resolve()` before any file operation on user-provided paths. Import from `writerView/utils/helpers.ts`.
+- **SVG excluded from import** — SVG is an XSS vector. Never add SVG to import/embed flows. SVGs are display-only via workspace scanner with CSP blocking scripts.
+
+## Patterns
+
+- Use `WeakMap` for panel metadata (resolver keys) instead of casting with `as any`
+- `pendingDuplicateResolvers` Map + `panelResolverKeys` WeakMap for Promise-based webview dialogs
+- Resolve pending promises in `onDidDispose` to prevent hangs
+- Module-level state lives in `extensionState.ts` — access via `getDeps()`, not global variables
+- Commands are registered in domain-specific modules under `commands/` — routed by `commands/register.ts`
+
+## Tech Stack
+
+- TypeScript ES2022, strict mode, CommonJS output
+- esbuild bundles `src/extension.ts` → `out/extension.js`
+- Runtime deps: `yaml`, `minimatch` — keep minimal
+- `vscode` is external (provided by VS Code runtime, never bundled)

.claude/rules/webview.md

@@ -0,0 +1,38 @@
+# Rules: Webview & Writer View
+
+Applies when creating or modifying files in `src/writerView/`.
+
+## Security
+
+- **HTML escape ALL interpolations** — Use `escapeHtml()` from `writerView/utils/helpers.ts`. It escapes `<`, `>`, `&`, `"`, and `'` (as `&#039;`). Never interpolate user content into HTML without escaping.
+- **CSP header required** — Every webview must include: `img-src ${webview.cspSource} data:;`. Scripts must use nonce-based CSP.
+- **No inline scripts** — All JavaScript goes through nonce-gated `<script>` tags. CSP blocks inline event handlers.
+
+## Image Handling
+
+- SHA256 content hash with file-size pre-filter for image deduplication
+- Images stored workspace-relative, served via `webview.asWebviewUri()`
+- `data:` URIs allowed in CSP for small inline images only
+
+## Webview Communication
+
+- Use `safePostMessage()` from helpers for extension → webview messages
+- Webview → extension communication via `vscode.postMessage()` with typed message objects
+- Always validate message types in both directions
+
+## File Structure
+
+```
+writerView/
+├── manager.ts          # Panel pool, file locking, lifecycle
+├── script.ts           # Webview-side JavaScript
+├── html/
+│   ├── builder.ts      # Main HTML assembly
+│   ├── contentRenderer.ts
+│   ├── attributesRenderer.ts
+│   ├── imagesRenderer.ts
+│   └── imageBrowserRenderer.ts
+├── toolbar/            # Contextual toolbar components
+└── utils/
+    └── helpers.ts      # escapeHtml, isPathWithinWorkspace, safePostMessage, nonce
+```

.claude/rules/yaml-operations.md

@@ -0,0 +1,25 @@
+# Rules: YAML & Codex Operations
+
+Applies when creating or modifying code that reads or writes `.codex.yaml`, `.codex.json`, or `.codex.md` files.
+
+## Mutation Safety
+
+- **Use `withFileLock()` for all YAML writes** — Concurrent writes corrupt YAML. The file lock prevents race conditions when multiple operations (auto-save, structure editing, drag-drop) target the same file.
+- **Preserve YAML comments and formatting** — `codexModel.ts` uses the `yaml` library's AST-preserving mode. Don't replace it with naive parse/stringify.
+- **Validate after mutation** — After any structural change (add/remove/move nodes), run validation to catch broken references.
+
+## Format Support
+
+The extension handles three formats transparently:
+
+| Format | Extension | Parser Path |
+|--------|-----------|-------------|
+| Codex YAML | `.codex.yaml` | `codexModel.ts` → `yaml` library |
+| Codex JSON | `.codex.json` | `codexModel.ts` → `JSON.parse` |
+| Codex Lite | `.md` with frontmatter | `codexModel.ts` → frontmatter extraction |
+
+## Auto-Fixer
+
+- `autoFixer.ts` repairs missing UUIDs, metadata, legacy fields, timecodes
+- Auto-fixer is aggressive — it can recover severely corrupted files
+- Always offer auto-fix via VS Code Quick Fix code actions, not silent mutation

CLAUDE.md

@@ -88,22 +88,13 @@ code --install-extension *.vsix --force
 - **GitHub Actions**: `.github/workflows/ci.yml` — typecheck, lint, unit tests + coverage, integration tests
 - **Lint**: ESLint with `continue-on-error: true` (18 pre-existing errors to clean up)
 
-## Coding Conventions
-
-### Must Follow
-- **Async file ops only** — Use `fs.promises`, never sync `fs.*Sync()`
-- **HTML escape all interpolations** — Use `escapeHtml()` from `writerView/utils/helpers.ts` (includes single-quote `'`)
-- **Path traversal validation** — Use `isPathWithinWorkspace()` + `path.resolve()` before any file operation on user-provided paths
-- **No `as any` type bypasses** — Use proper typing, WeakMap for metadata
-- **YAML mutation locking** — Use `withFileLock()` for concurrent-safe YAML writes
-- **SVG excluded from import** — XSS vector; kept in workspace scanner only (display-only, CSP blocks scripts)
-
-### Patterns
-- WeakMap for panel metadata (resolver keys) instead of `(panel as any)`
-- `pendingDuplicateResolvers` Map + `panelResolverKeys` WeakMap for Promise-based webview dialogs
-- Resolve pending promises in `onDidDispose` to prevent hangs
-- CSP header: `img-src ${webview.cspSource} data:;` required for images
-- SHA256 content hash with size pre-filter for image deduplication
+## Modular Rules
+
+See `.claude/rules/` for convention-specific rules that load contextually:
+- `typescript.md` — async FS, no `as any`, path validation, typing patterns
+- `webview.md` — HTML escaping, CSP headers, image handling, webview communication
+- `yaml-operations.md` — file locking, format support, mutation safety, auto-fixer
+- `testing.md` — Vitest patterns, integration tests, TDD, config split
 
 ### Tech Stack
 - **Language**: TypeScript (ES2022, strict, CommonJS)