Regenerate agent instructions from state-hub templates (CUST-WP-0055 T01)

Sync AGENTS.md, CLAUDE.md, and .claude/rules from updated project_rules templates: workplan-first session protocol, legacy terminology footnote, and GET /workplans/ examples.
2026-07-08 14:50:38 +02:00 · 2026-07-08 14:50:38 +02:00 · 7fd31b5825
commit 7fd31b5825
parent 4af8a606a1
11 changed files with 360 additions and 241 deletions
--- a/.claude/rules/agents.md
+++ b/.claude/rules/agents.md
@ -0,0 +1,20 @@
 ## Kaizen Agents
 Specialized agent personas available on demand via the state-hub MCP.
 **Discover:** `list_kaizen_agents()` — returns all agents with name, description, category
 **Load:** `get_kaizen_agent("tdd-workflow")` — returns full instructions; read and follow them
 Common agents:
 | Agent | Category | When to use |
 |-------|----------|-------------|
 | `tdd-workflow` | testing | Step-by-step TDD8 workflow for any feature |
 | `code-refactoring` | quality | Code quality analysis and safe refactoring |
 | `test-maintenance` | testing | Diagnose and fix failing tests |
 | `requirements-engineering` | process | Prevent interface/mock mismatches upfront |
 | `keepaTodofile` | process | Maintain TODO.md during work |
 | `project-management` | process | Track status, determine next steps |
 | `datamodel-optimization` | quality | Optimize dataclasses and data structures |
 All 17 agents: call `list_kaizen_agents()` for the full list.
--- a/.claude/rules/architecture.md
+++ b/.claude/rules/architecture.md
@ -0,0 +1,8 @@
 ## Architecture
 <!-- TODO: Describe the key design decisions and component structure.
     Key modules, data flows, external integrations, state machines, etc. -->
 ## Quick Reference
 `~/state-hub/mcp_server/TOOLS.md` — MCP tool reference
--- a/.claude/rules/credential-routing.md
+++ b/.claude/rules/credential-routing.md
@ -0,0 +1,50 @@
 # Credential and access routing
 **Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
 for inference. Run this check **before** requesting secrets, API keys, SSH access,
 login tokens, or database passwords — in any repo, not only `ops-warden`.
 ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
 other credential need belongs to another subsystem. **Do not** message
 `ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
 ### Lookup (do this first)
 ```bash
 warden route find "<describe your need>" --json
 warden route show <catalog-id> --json
 ```
 Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
 | Agent runtime | How to orient |
 | --- | --- |
 | **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=timeline-svg` is for coordination, not secret vending |
 | **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
 | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
 ### Quick routing table
 | I need… | Owner | ops-warden executes? |
 | --- | --- | --- |
 | SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
 | API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
 | Login / OIDC / MFA | key-cape / Keycloak | No — route only |
 | Authorization decision | flex-auth | No — route only |
 | activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
 | SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
 ### Anti-patterns (do not do these)
 - `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
 - Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
 - Pasting secrets into Git, State Hub, workplans, logs, or chat
 ### Other capabilities (reuse-surface)
 Non-credential capabilities are usually discovered through **reuse-surface** federation
 (`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
 every repo's agent instructions because it is high-frequency, high-risk, and easy to
 get wrong.
 **Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
--- a/.claude/rules/first-session.md
+++ b/.claude/rules/first-session.md
@ -0,0 +1,42 @@
 ## First Session Protocol
 Triggered when `get_domain_summary("infotech")` shows **no workplans**.
 The project is registered but work has not yet been structured.
 **Step 1 — Read, don't write**
 - `~/the-custodian/canon/projects/infotech/project_charter_v0.1.md` — purpose, scope
 - `~/the-custodian/canon/projects/infotech/roadmap_v0.1.md` — planned phases
 - Scan repo root: README, directory structure, existing code or docs
 **Step 2 — Survey in-progress work**
 Look for TODOs, open branches, half-finished files. Note done vs. started but incomplete.
 **Step 3 — Propose workplans to Bernd**
 Propose 1–3 workplans — each a coherent strand, weeks to months, anchored to a
 roadmap phase. **Wait for approval before creating.**
 **Step 4 — Write the workplan file; fix-consistency registers it (ADR-001)**
 ```
 workplans/TMLN-WP-NNNN-<slug>.md   ← write this, commit it
 ```
 Then register by running the consistency check — do **not** call
 `create_workplan`/`create_task` yourself; manual registration duplicates what
 C-06 creates from the file:
 ```bash
 statehub fix-consistency --repo timeline-svg
 ```
 C-06 creates the hub workplan + tasks and writes `state_hub_workstream_id`
 (legacy frontmatter name — holds the workplan UUID) and `state_hub_task_id`
 back into the file.
 **Step 5 — Record the setup**
 ```
 add_progress_event(
    summary="First session: structured infotech into N workplans, M tasks",
    event_type="milestone",
    topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a",
    detail={"workplans": [...], "tasks_created": M}
 )
 ```
 <!-- Delete or archive this file once past first session -->
--- a/.claude/rules/repo-boundary.md
+++ b/.claude/rules/repo-boundary.md
@ -0,0 +1,8 @@
 ## Repo boundary
 This repo owns **timeline-svg** only. It does not own:
 <!-- TODO: List what belongs in adjacent repos, e.g.:
 - SSH key management → railiance-infra/
 - State hub code     → state-hub/
 -->
--- a/.claude/rules/repo-identity.md
+++ b/.claude/rules/repo-identity.md
@ -0,0 +1,5 @@
 **Purpose:** TimelineSvg is a client-side, browser-based tool that generates multi-lane SVG timeline graphics from CSV data using an Inkscape-editable SVG template system with no backend or build pipeline.
 **Domain:** infotech
 **Repo slug:** timeline-svg
 **Topic ID:** cee7bedf-2b48-46ef-8601-006474f2ad7a
--- a/.claude/rules/session-protocol.md
+++ b/.claude/rules/session-protocol.md
@ -0,0 +1,92 @@
 ## Session Protocol
 Dev Hub (State Hub API): http://127.0.0.1:8000
 MCP server name in `~/.claude.json`: `dev-hub`
 **Step 1 — Orient**
 Read the offline-safe brief first — it works without a live hub connection:
 ```bash
 cat .custodian-brief.md
 ```
 Then call the MCP tool for richer cross-domain context when MCP tools are exposed:
 ```
 get_domain_summary("infotech")
 ```
 If MCP tools are unavailable in the current agent session, use the REST API:
 ```bash
 curl -s "http://127.0.0.1:8000/state/summary" | python3 -m json.tool
 ```
 If the hub is offline: `cd ~/state-hub && make api`
 **Step 2 — Check inbox**
 With MCP tools:
 ```
 get_messages(to_agent="timeline-svg", unread_only=True)
 ```
 Mark read with `mark_message_read(message_id)`. Reply or act on coordination
 requests before proceeding.
 Without MCP tools:
 ```bash
 curl -s "http://127.0.0.1:8000/messages/?to_agent=timeline-svg&unread_only=true" \
  | python3 -m json.tool
 curl -s -X PATCH "http://127.0.0.1:8000/messages/<id>/read" \
  -H "Content-Type: application/json" -d '{}'
 ```
 **Step 3 — Scan workplans**
 ```bash
 ls workplans/
 ```
 For each file with `status: ready`, `active`, or `blocked`, note pending
 `wait`/`todo`/`progress` tasks.
 **Step 4 — Present brief**
 1. **Active workplans** for `infotech` — title, task counts, blocking decisions
 2. **Pending tasks** from `workplans/` + any `[repo:timeline-svg]` hub tasks
 3. **Goal guidance** — if `goal_guidance` in summary:
   - `needs_workplan`: surface as top action — *"Repo goal '{title}' has no workplan yet"*
   - `alignment_warnings`: flag if active work is not aligned with current goal
 4. **Suggested next action** — highest-priority open item
 5. **SBOM status** — flag if `last_sbom_at` is unset for this repo
 If no workplans: follow First Session Protocol (`first-session.md`).
 **During work:** `record_decision()` · `add_progress_event()` · `resolve_decision()`
 > State Hub is a *read model*. **Never register workplans or tasks by hand**
 > (`create_workplan`, `create_task`) — write the workplan file in `workplans/`
 > and run `fix-consistency`; C-06 registers the workplan and tasks and writes
 > IDs back into the file. Manual registration creates duplicates when
 > fix-consistency runs. Work structure belongs in repo files (ADR-001).
 >
 > Legacy: `create_workstream` and `/workstreams/` remain as metered aliases —
 > see `workplan-convention.md` (compatibility footnote).
 **Session close:**
 With MCP tools:
 ```
 add_progress_event(summary="...", topic_id="cee7bedf-2b48-46ef-8601-006474f2ad7a", workplan_id="<uuid>")
 ```
 Without MCP tools:
 ```bash
 curl -s -X POST http://127.0.0.1:8000/progress/ \
  -H "Content-Type: application/json" \
  -d '{"topic_id":"cee7bedf-2b48-46ef-8601-006474f2ad7a","workplan_id":"<uuid>","event_type":"note","summary":"what changed","author":"codex"}'
 ```
 If workplan files were modified, ensure the local copy is up to date first,
 then sync from the repo checkout:
 ```bash
 git pull --ff-only
 statehub fix-consistency
 ```
 For repos where implementation runs on a remote machine (e.g. CoulombCore),
 use the pull-before-fix mode from any shell with the State Hub CLI:
 ```bash
 statehub fix-consistency --repo timeline-svg --remote
 ```
 **C-15** (DB task ahead of file) is normal in multi-machine workflows — writeback
 will sync the file to match DB.  **C-16** (repo behind remote) blocks all writes
 until you pull — intentional to prevent clobbering remote progress.
--- a/.claude/rules/stack-and-commands.md
+++ b/.claude/rules/stack-and-commands.md
@ -0,0 +1,19 @@
 ## Stack
 <!-- TODO: Fill in language, frameworks, and key dependencies -->
 - **Language:**
 - **Key deps:**
 ## Dev Commands
 ```bash
 # TODO: Fill in the standard commands for this repo
 # Install dependencies
 # Run tests
 # Lint / type check
 # Build / package (if applicable)
 ```
--- a/.claude/rules/workplan-convention.md
+++ b/.claude/rules/workplan-convention.md
@ -0,0 +1,55 @@
 ## Workplan Convention (ADR-001)
 File location: `workplans/TMLN-WP-NNNN-<slug>.md`
 ID prefix: `TMLN-WP-`
 Work items originate as files in this repo **before** being registered in the hub.
 Canonical workplan frontmatter statuses are:
 `proposed`, `ready`, `active`, `blocked`, `backlog`, `finished`, `archived`.
 Use `proposed` for a newly drafted plan, `ready` after review against current
 repo state, and `finished` when implementation is complete. `stalled` and
 `needs_review` are derived health labels, not stored statuses.
 Closed workplans may be moved to `workplans/archived/` with a completion-date
 prefix: `YYMMDD-TMLN-WP-NNNN-<slug>.md`. The frontmatter id remains
 unchanged; the prefix is only for quick visual reference.
 Small opportunistic tasks discovered during another session use **Ad Hoc Tasks**:
 `workplans/ADHOC-YYYY-MM-DD.md`, workplan slug `adhoc-YYYY-MM-DD`, and task ids
 `ADHOC-YYYY-MM-DD-T01`, `T02`, etc. Use adhocs only for low-risk work completed
 directly. Promote anything requiring analysis, design, approval, dependencies, or
 multiple planned phases into a normal workplan.
 Ecosystem todos from other agents arrive as `[repo:timeline-svg]` hub tasks —
 visible at session start. Pick one up by creating the workplan file, committing,
 and running `statehub fix-consistency` — C-06 registers the workplan in the hub.
 Never register by hand with `create_workplan` (legacy MCP alias: `create_workstream`).
 Task blocks use this shape:
 ```task
 id: TMLN-WP-NNNN-T01
 status: wait | todo | progress | done | cancel
 priority: high | medium | low
 state_hub_task_id: "<uuid>"         # written by fix-consistency — do not edit
 ```
 Status progression is `todo` → `progress` → `done`; use `wait` for waiting or
 blocked work and `cancel` for stopped work.
 Workplan frontmatter carries `state_hub_workstream_id` — a legacy field name
 kept for compatibility; it holds the hub workplan UUID and is written by
 fix-consistency. Do not edit or rename it.
 ### Legacy terminology (compatibility footnote)
 **Workplan** is the fleet term — see
 `the-custodian/canon/standards/workplan-terminology-fleet_v0.1.md`.
 **Workstream** is legacy only: some API routes (`/workstreams/`), params
 (`workstream_id`), MCP aliases (`create_workstream`), and the frontmatter field
 above remain until `STATE-WP-0069` retires them via legacy-meter. Treat those
 identifiers as workplan IDs. Prefer `GET /workplans/` and `workplan_id` in new
 examples and scripts.
 <!-- Ralph Loop rules and HEUREKA sequence: ~/.claude/CLAUDE.md — do not duplicate here -->
--- a/AGENTS.md
+++ b/AGENTS.md
@ -107,7 +107,56 @@ curl -s -X PATCH "http://127.0.0.1:8000/tasks/<task_id>" \
 ---
-{CREDENTIAL_ROUTING}
+## Credential and access routing
 **Audience:** Codex, Claude Code, Grok, and custodian agents that call **llm-connect**
 for inference. Run this check **before** requesting secrets, API keys, SSH access,
 login tokens, or database passwords — in any repo, not only `ops-warden`.
 ops-warden **issues SSH certificates only** (`warden sign`, `cert_command`). Every
 other credential need belongs to another subsystem. **Do not** message
 `ops-warden` on State Hub expecting a secret value; the reply is a pointer, not a key.
 ### Lookup (do this first)
 ```bash
 warden route find "<describe your need>" --json
 warden route show <catalog-id> --json
 ```
 Requires the `warden` CLI from `~/ops-warden` (`uv tool install .` or `uv run warden`).
 | Agent runtime | How to orient |
 | --- | --- |
 | **Codex / Grok** (shell, HTTP State Hub) | `warden route` commands above; inbox `to_agent=timeline-svg` is for coordination, not secret vending |
 | **Claude Code** (MCP when available) | `get_domain_summary("custodian")` for workplans; **still** use `warden route` for credential ownership |
 | **llm-connect** (inference service) | Never put secret retrieval in prompts; route custody to OpenBao/operator paths surfaced by `warden route` |
 ### Quick routing table
 | I need… | Owner | ops-warden executes? |
 | --- | --- | --- |
 | SSH cert (`adm`/`agt`/`atm`) | ops-warden | **Yes** — `warden sign` |
 | API key, DB password, provider token | OpenBao (`railiance-platform`) | No — route only |
 | Login / OIDC / MFA | key-cape / Keycloak | No — route only |
 | Authorization decision | flex-auth | No — route only |
 | activity-core → issue-core emission | activity-core + issue-core | No — `warden route show activity-core-issue-sink` |
 | SSH tunnel | ops-bridge (+ `cert_command` from warden) | No — route only |
 ### Anti-patterns (do not do these)
 - `POST /messages/` to `ops-warden` asking for `ISSUE_CORE_API_KEY`, `OPENROUTER_API_KEY`, etc.
 - Inventing `warden secret`, `warden login`, `warden bao`, `warden tunnel` — they do not exist
 - Pasting secrets into Git, State Hub, workplans, logs, or chat
 ### Other capabilities (reuse-surface)
 Non-credential capabilities are usually discovered through **reuse-surface** federation
 (`reuse-surface` registry / `capability.*` indexes). Credential routing is inlined in
 every repo's agent instructions because it is high-frequency, high-risk, and easy to
 get wrong.
 **Canon:** `~/ops-warden/wiki/CredentialRouting.md` · catalog `~/ops-warden/registry/routing/catalog.yaml`
 <!-- REPO-AGENTS-EXTENSIONS -->
 <!-- Append repo-specific agent instructions below this marker.
--- a/CLAUDE.md
+++ b/CLAUDE.md
@ -1,241 +1,12 @@
-# CLAUDE.md
+# timeline-svg — Claude Code Instructions
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+@SCOPE.md
-
+@.claude/rules/repo-identity.md
-## Overview
+@.claude/rules/session-protocol.md
-
+@.claude/rules/first-session.md
-TimelineSvg is a browser-based system for generating multi-lane timelines as SVG graphics from CSV data. It processes everything client-side using vanilla JavaScript, with no build pipeline or backend required. The system uses a template-based architecture where SVG templates define the visual appearance and data is mapped through a project configuration file.
+@.claude/rules/workplan-convention.md
-
+@.claude/rules/stack-and-commands.md
-**Troubleshooting**: If you encounter issues during development, check `TROUBLESHOOTING.md` first. It contains solutions for common problems including npm installation failures, CORS errors, template validation issues, and more.
+@.claude/rules/architecture.md
-
+@.claude/rules/repo-boundary.md
-## Commands
+@.claude/rules/credential-routing.md
-
+@.claude/rules/agents.md
 ### Installation
 ```bash
 make install             # Install development dependencies
 ```
 **Important - Node.js v24 on WSL**: If you encounter `ERR_SSL_CIPHER_OPERATION_FAILED` errors during `npm install`, this is a known issue with Node.js v24 and OpenSSL 3.x in WSL environments. The Makefile automatically applies the workaround using `NODE_OPTIONS="--openssl-legacy-provider"`. If installing manually without make:
 ```bash
 export NODE_OPTIONS="--openssl-legacy-provider" && npm install
 ```
 ### Testing
 ```bash
 npm test                  # Run all tests once
 npm run test:watch       # Run tests in watch mode
 npm run test:coverage    # Generate coverage report
 npm run test:ui          # Run Vitest UI
 ```
 The project uses Vitest with jsdom for testing. Tests are located in `/test/` and cover the generator, engine, and integration scenarios.
 ### Development
 ```bash
 make serve               # Start local development server (auto-detects Python/npx)
 # or manually:
 python3 -m http.server 8000
 # Then open http://localhost:8000
 ```
 The application must be served via HTTP (not opened as file://) due to CORS restrictions when loading CSV, CSS, and SVG files.
 ### Distribution
 ```bash
 make dist                # Build distribution package in dist/
 make dist-zip            # Build distribution and create archive
 ```
 The distribution package includes:
 - All runtime files (HTML, JS, CSS)
 - Example projects (example/, example-1/, my-project/)
 - Documentation (README.md, TEMPLATE_V2_GUIDE.md, TROUBLESHOOTING.md)
 - Startup scripts for Windows (start-server.bat) and Linux/Mac (start-server.sh)
 Use this to deploy the application to Windows or other environments. The distribution is self-contained and requires only a web browser and Python (for the local server).
 **For Windows deployment from WSL**: See `WINDOWS_USAGE.md` for detailed instructions on building the distribution in WSL, transferring to Windows, and running the application on Windows OS.
 ## Architecture
 ### Core Components
 **1. engine.js** - Application controller and data loading
 - Manages project configuration loading (auto-loads from `binect/`, `my-project/`, or `example/` folders)
 - Handles CSV parsing using PapaParse library
 - Manages file uploads and overrides
 - Provides debug information panel
 - Controls view modes (internal vs external)
 - Implements zoom functionality for SVG viewer
 **2. generator.js** - Timeline rendering engine
 - Implements template-v2 architecture
 - Extracts template elements from `<defs>` section: `month-template`, `lane-template`, `item-template`
 - Replaces placeholders with calculated values and CSV data
 - Handles layout calculations (positioning months, lanes, items)
 - Generates final SVG by cloning templates and replacing `{{MONTHS}}` and `{{LANES}}` macros
 **3. index.html** - UI and browser entry point
 - Loads PapaParse from CDN for CSV parsing
 - Provides file upload controls
 - Contains viewer with zoom controls
 - Shows debug information panel with field mappings and data preview
 ### Data Flow
 1. **Project Configuration** (`project.json`) defines:
   - Data source (CSV file path)
   - Stylesheet (CSS file path)
   - SVG template (template-v2.svg file path)
   - Field mappings (CSV columns → timeline fields)
   - Optional placeholder mappings (override default `ITEM_*` convention)
   - Settings (timeline duration, etc.)
 2. **CSV Data** is parsed and mapped to timeline items:
   - Required fields: `id`, `title`, `due`, `lane`
   - Date parsing supports multiple formats: `YYYY-MM-DD`, `YYYY/MM/DD`, `DD.MM.YYYY`
   - Items without valid title or due date are filtered out
 3. **Template System** (template-v2 architecture):
   - Templates are standard SVG files editable in Inkscape, Illustrator, or Figma
   - Three required template elements in `<defs>` section:
     - `<g id="month-template">` - Defines month column rendering
     - `<g id="lane-template">` - Defines lane/epic row rendering
     - `<g id="item-template">` - Defines individual task rendering
   - Templates contain placeholders like `{{MONTH_X}}`, `{{LANE_NAME}}`, `{{ITEM_TITLE}}`
   - Generator extracts templates, replaces placeholders, and injects into main SVG
 4. **Placeholder System**:
   - Layout placeholders: `{{MONTH_X}}`, `{{LANE_Y}}`, `{{ITEM_X}}`, etc. (calculated by generator)
   - Data placeholders: Automatically created from CSV columns using `ITEM_{PROPERTY}` convention
   - Custom mappings: Use `placeholderMapping` in project.json to override default names (e.g., `TASK_ID` instead of `ITEM_ID`)
   - All CSV properties (except `due`) are available as placeholders in templates
 ### Key Concepts
 **Template-v2 Architecture**: The current system (migrated from older macro-based approach) uses proper SVG template elements that are cloned and customized. This makes templates more maintainable and editable in visual SVG editors.
 **Field Mapping**: CSV columns don't need to match exact names. The `fieldMapping` object in project.json maps CSV column names to the internal timeline model:
 ```json
 {
  "fieldMapping": {
    "id": "ID",           // CSV column "ID" maps to item.id
    "title": "Title",     // CSV column "Title" maps to item.title
    "lane": "Lane",       // CSV column "Lane" maps to item.lane
    "due": ["Due"]        // CSV column "Due" maps to item.due (array for fallbacks)
  }
 }
 ```
 **Placeholder Mapping**: When templates use non-standard placeholder names (common when migrating from other tools), use `placeholderMapping` to override the default `ITEM_*` convention:
 ```json
 {
  "placeholderMapping": {
    "id": "TASK_ID",       // Use {{TASK_ID}} instead of {{ITEM_ID}}
    "title": "TASK_NAME"   // Use {{TASK_NAME}} instead of {{ITEM_TITLE}}
  }
 }
 ```
 **Layout Constants** (generator.js:41-45): Control overall positioning
 - `left: 220` - Left margin
 - `top: 140` - Top margin
 - `monthWidth: 120` - Width of each month column
 - `laneHeight: 80` - Height of each lane/epic row
 - `laneGap: 16` - Vertical gap between lanes
 **View Modes**:
 - Internal view: Shows item IDs (for development/review)
 - External view: Hides item IDs (for presentations/exports)
 **Project Loading Methods**:
 - Auto-load: When served via HTTP, attempts to load from binect/, my-project/, or example/ folders
 - Folder picker: User selects entire project folder - all files load automatically (uses webkitdirectory attribute)
 - Individual files: User manually uploads project.json, then CSV/SVG/CSS separately
 The folder picker was added to solve the browser security limitation where uploading a single project.json doesn't allow automatic access to other files in the same directory.
 ## Project Structure
 ```
 /
 ├── index.html              # Main application entry point
 ├── engine.js               # Application controller & data loading
 ├── generator.js            # SVG generation & template processing
 ├── vitest.config.js        # Test configuration
 ├── test/
 │   ├── setup.js           # Test environment setup
 │   ├── generator.test.js  # Generator unit tests
 │   ├── engine.test.js     # Engine unit tests
 │   └── integration.test.js # End-to-end tests
 ├── example/               # Example project
 │   ├── project.json       # Project configuration
 │   ├── sample.csv         # Sample data
 │   ├── style.css          # Custom styling
 │   └── template-v2.svg    # SVG template
 └── TEMPLATE_V2_GUIDE.md   # Comprehensive template documentation
 ```
 ## Testing Guidelines
 When writing tests:
 - Use Vitest's `describe()` and `it()` structure
 - Mock browser APIs (localStorage, fetch) using jsdom
 - Test template validation separately from rendering
 - Test date parsing for all supported formats
 - Test field mapping edge cases (missing fields, null values)
 - Integration tests should cover full project loading → CSV parsing → SVG generation flow
 ## Important Implementation Details
 **Template Validation** (generator.js:54-70): Always validate templates before attempting to generate SVG. Check for all three required template IDs.
 **Template Extraction** (generator.js:73-82): Use regex to extract template elements from `<defs>`. Throws error if extraction fails (indicates malformed template).
 **XML Escaping** (generator.js:216-223): Always escape user data (titles, lane names) when injecting into SVG to prevent malformed XML.
 **Date Parsing** (engine.js:385-408): Supports multiple formats with fallback to `new Date()`. Returns null for invalid dates, which causes items to be filtered out.
 **Project Base Path Resolution** (engine.js:148-157): Relative paths in project.json are resolved relative to the project folder (e.g., `example/`). This enables projects to reference their own resources.
 **Debug Information Panel**: Shows field mappings, template placeholders, and CSV preview to help diagnose configuration issues. Automatically displayed when project loads.
 ## Common Development Tasks
 When adding new placeholder types:
 1. Add to placeholder documentation in TEMPLATE_V2_GUIDE.md
 2. Update generator.js placeholder replacement logic if needed
 3. Update example templates to demonstrate usage
 4. Add tests for the new placeholder type
 When modifying layout:
 1. Update layout constants in generator.js:41-45
 2. Update placeholder value calculations in generateFromTemplates()
 3. Update TEMPLATE_V2_GUIDE.md with new dimensions
 4. Regenerate example SVGs to verify
 When adding CSV field support:
 1. Update fieldMapping documentation in README.md
 2. Update example project.json files
 3. Add to processCsv() in engine.js
 4. Update generator to expose as placeholder
 5. Add tests for field mapping
 ## Template Development
 See TEMPLATE_V2_GUIDE.md for comprehensive template creation and customization documentation. Key points:
 - Templates must have all three required `<g id="*-template">` elements in `<defs>`
 - Use `style="display:none"` on template elements to hide them
 - All placeholders use `{{UPPERCASE_NAME}}` format
 - Templates are standard SVG - edit in any SVG editor
 - Test templates by loading them in the UI and checking debug panel
 ## Migration Notes
 The codebase uses template-v2 architecture. Legacy template-v1 (macro-based) is deprecated. When working with old projects:
 - Convert macro-based templates to template-v2 format
 - Move template definitions into `<defs>` section
 - Update placeholder names to match conventions
 - Use `placeholderMapping` if preserving legacy placeholder names