docs: fix critical documentation inaccuracies

.claude/agents/dipeo-backend.md

@@ -23,8 +23,8 @@ You are an expert backend engineer specializing in DiPeO's server, CLI, and data
 
 ## Quick Reference
 - **Server**: apps/server/main.py, api/graphql_endpoint.py
-- **CLI**: apps/server/cli/ (5 commands: run, results, metrics, compile, export)
-- **Database**: apps/server/infra/ (db_schema.py, message_store.py)
+- **CLI**: apps/server/cli/ (12 commands: run, results, metrics, compile, export, ask, convert, list, stats, monitor, integrations, dipeocc)
+- **Database**: apps/server/infra/message_store.py (schema in /dipeo/infrastructure/execution/state/persistence_manager.py)
 - **MCP**: apps/server/api/mcp_sdk_server/
 
 ## Key Patterns

.claude/skills/dipeo-backend/SKILL.md

@@ -6,7 +6,7 @@ allowed-tools: Read, Grep, Glob, Bash, Skill
 
 # DiPeO Backend Router
 
-**Domain**: FastAPI server, CLI (`dipeo run/results/metrics/compile/export`), SQLite schema, MCP server integration in `apps/server/`.
+**Domain**: FastAPI server, CLI (12 commands including run/results/metrics/compile/export/ask/convert/list/stats/monitor/integrations/dipeocc), message store, MCP server integration in `apps/server/`. Database schema initialization is in `/dipeo/infrastructure/execution/state/persistence_manager.py` (package-maintainer domain).
 
 ## Quick Decision: Skill or Agent?
 

CLAUDE.md

@@ -46,27 +46,10 @@ See [Diagram-to-Python Export Guide](docs/features/diagram-to-python-export.md)
 
 ### Compile and Push (for MCP)
 ```bash
-# Validate from file
-dipeo compile my_diagram.light.yaml --light
-
-# Validate from stdin (LLM-friendly)
-echo '<diagram-content>' | dipeo compile --stdin --light
-
-# Compile and push to MCP directory (from file)
-dipeo compile my_diagram.light.yaml --light --push-as my_workflow
-
-# Compile and push from stdin (LLM-friendly workflow)
-echo '<diagram-content>' | dipeo compile --stdin --light --push-as my_workflow
-
-# Custom target directory
-dipeo compile --stdin --light --push-as my_workflow --target-dir /custom/path
+dipeo compile my_diagram.light.yaml --light              # Validate
+dipeo compile --stdin --light --push-as my_workflow      # Validate + push to MCP
+# Also supports: --target-dir for custom location
 ```
-
-**Benefits:**
-- **Safe Upload**: Only valid diagrams are pushed
-- **No File Persistence**: LLMs can validate and push diagrams from text without filesystem access
-- **Automatic MCP Integration**: Pushed diagrams immediately available via `dipeo_run`
-
 See [MCP Server Integration](docs/features/mcp-server-integration.md#3-uploading-diagrams-for-mcp-access)
 
 ### Code Generation
@@ -124,7 +107,7 @@ DiPeO uses specialized subagents for complex tasks. The agent structure is organ
   - Excludes: Code generation, backend server, CLI
 
 - **dipeo-backend**: FastAPI server, CLI, database, and MCP integration in apps/server/
-  - Use for: Server configuration, CLI commands (run, results, metrics, compile, export), database schema, MCP server
+  - Use for: Server configuration, CLI commands (run, results, metrics, compile, export, ask, convert, list, stats, monitor, integrations, dipeocc), message store, MCP server
 
 - **dipeo-codegen-pipeline**: Complete TypeScript → IR → Python/GraphQL pipeline
   - Use for: TypeScript model design, IR builders, code generation, generated code diagnosis
@@ -135,6 +118,8 @@ DiPeO uses specialized subagents for complex tasks. The agent structure is organ
 - **dipeo-frontend-dev**: React components, visual diagram editor, GraphQL integration
 - **codebase-auditor**: Targeted code analysis for security, performance, quality
 - **dipeocc-converter**: Converting Claude Code sessions to DiPeO diagrams
+- **code-polisher**: Polish and clean up code (file separation, comment cleanup, import refactoring, doc maintenance)
+- **codebase-qna**: Fast codebase retrieval using Haiku (find functions, classes, usage patterns)
 
 **Best Practice**: Run agents in parallel when possible. See [Agent docs](docs/agents/index.md) for detailed guides.
 
@@ -153,98 +138,22 @@ Router skills provide on-demand access to agent documentation with 80-90% token
 - **dipeo-frontend-dev**: React components, visual diagram editor, GraphQL integration, TypeScript types
 
 **How Router Skills Work:**
+- **Thin routers** (~50-100 lines): Decision criteria, doc anchors, escalation paths
+- **Progressive**: Use `Skill(dipeo-backend)` to load router → check if task is simple
+- **doc-lookup**: Load specific sections: `Skill(doc-lookup) --query "cli-commands"`
+- **Token efficiency**: 80-90% reduction (1.5k vs 15k tokens per task)
 
-Router skills are **thin** (~50-100 lines) and provide:
-1. **Decision criteria**: When to handle directly vs. escalate to full agent
-2. **Stable documentation anchors**: References to specific sections in `docs/`
-3. **Escalation paths**: Clear guidance on when to invoke other agents/skills
-
-**Usage Pattern:**
-
-```bash
-# Pattern 1: Router + direct handling (simple task)
-Skill(dipeo-backend)  # Load 50-line router
-# Review decision criteria → task is simple → handle directly
-# Cost: ~1,000 tokens
-
-# Pattern 2: Router + doc-lookup + solve (focused task)
-Skill(dipeo-backend)  # Load router
-Skill(doc-lookup) --query "cli-commands"  # Get specific section (~50 lines)
-# Solve problem with targeted context
-# Cost: ~1,500 tokens (vs. 15,000 with auto-injection)
-
-# Pattern 3: Router + escalate to agent (complex task)
-Skill(dipeo-backend)  # Load router, review decision criteria
-Task(dipeo-backend, "Add new CLI command with validation")
-# Agent can load additional sections via doc-lookup as needed
-```
-
-**doc-lookup Helper Skill:**
-
-The `doc-lookup` skill extracts specific documentation sections by anchor or keyword:
+**When to Use:** Before Task tool invocation or during agent execution
 
-```bash
-# Retrieve specific section by anchor
-python .claude/skills/doc-lookup/scripts/section_search.py \
-  --query "cli-commands" \
-  --paths docs/agents/backend-development.md \
-  --top 1
-
-# Search across multiple docs
-Skill(doc-lookup) --query "mcp-server-implementation"
-```
+See `.claude/skills/` for detailed skill documentation.
 
-**Benefits:**
-- **Progressive disclosure**: Load only relevant sections as needed
-- **Agent autonomy**: Agents decide what context they need
-- **Single source of truth**: Docs remain in `docs/`, no duplication
-- **Token efficiency**: 80-90% reduction (1.5k vs 15k tokens per task)
+### todo-manage Skill
 
-**When to Use:**
-- Before invoking a full agent with Task tool (to check if task is simple enough to handle directly)
-- During agent execution (to load specific documentation sections)
-- When exploring what an agent can do (decision criteria and scope)
+Use for comprehensive TODO management on multi-phase projects (3+ phases or 10+ tasks), complex migrations, or large feature implementations.
 
-### todo-manage Skill
+**Access**: `/dipeotodos` slash command
 
-**When to use**: For comprehensive TODO list management when working on multi-phase projects, complex migrations, or when planning feature implementations that require structured task tracking.
-
-**Use the `todo-manage` skill when:**
-- Planning multi-phase projects (3+ phases or 10+ tasks)
-- Organizing complex migrations or refactoring work
-- Breaking down large feature requests into structured task lists
-- User explicitly requests comprehensive TODO planning
-- Need to create organized, phase-based task breakdown with estimates
-
-**Examples:**
-
-<example>
-Context: User requests a major migration that requires multiple coordinated steps
-user: "We need to migrate from legacy MCP to SDK-only implementation"
-assistant: "I'll use the todo-manage skill to create a comprehensive, phase-based TODO list for this migration."
-<commentary>Use todo-manage for complex migrations requiring structured planning with phases, estimates, and dependencies.</commentary>
-</example>
-
-<example>
-Context: User wants to implement a large feature with many components
-user: "Add authentication system with OAuth, JWT, API keys, and role-based access control"
-assistant: "Let me use the todo-manage skill to break this down into a comprehensive TODO list organized by implementation phases."
-<commentary>Use todo-manage for large feature implementations that need structured task breakdown.</commentary>
-</example>
-
-<example>
-Context: User wants comprehensive project planning
-user: "Create a TODO list for implementing the new diagram export system"
-assistant: "I'll use the todo-manage skill to create a detailed, phase-organized TODO list with effort estimates and dependencies."
-<commentary>Use todo-manage when user explicitly requests TODO planning or when project complexity warrants structured task management.</commentary>
-</example>
-
-**Access TODO list**: Use `/dipeotodos` slash command to view current TODO.md
-
-**Don't use todo-manage for:**
-- Simple, single-task changes (use regular TodoWrite tool instead)
-- Quick bug fixes or minor updates
-- When you just need to mark existing TODOs as complete
+**Don't use for**: Simple single-task changes (use TodoWrite tool instead)
 
 ### Other Skills
 
@@ -282,34 +191,10 @@ See [Overall Architecture](docs/architecture/README.md) for complete details.
 
 ## Adding New Features
 
-### New Node Types
-1. Create spec in `/dipeo/models/src/nodes/`
-2. Build: `cd dipeo/models && pnpm build`
-3. Generate: `make codegen` → `make diff-staged` → `make apply-test`
-4. Configure handles in `/dipeo/domain/diagram/utils/shared_components.py` (HANDLE_SPECS)
-5. Add field mappings if needed in `/dipeo/domain/diagram/utils/node_field_mapper.py` (FIELD_MAPPINGS)
-6. Create handler in `/dipeo/application/execution/handlers/`
-7. Update schema: `make graphql-schema`
-
-See [Developer Guide](docs/guides/developer-guide-diagrams.md) for detailed instructions.
-
-### New Diagram Formats
-1. Create strategy in `/dipeo/domain/diagram/strategies/my_format/`
-2. Implement: `parser.py`, `transformer.py`, `serializer.py`, `strategy.py`
-3. Follow existing patterns (see `light/` or `readable/`)
-4. Register strategy in format registry
-
-See [Developer Guide](docs/guides/developer-guide-diagrams.md#adding-new-diagram-formats) for details.
-
-### GraphQL Operations
-1. Add definition in `/dipeo/models/src/frontend/query-definitions/`
-2. Follow codegen workflow above
-3. See [GraphQL Layer](docs/architecture/graphql-layer.md)
-
-### Other Changes
-- **API changes**: Modify schema → `make graphql-schema`
-- **UI changes**: Work in `/apps/web/src/`
-- **Compilation phases**: Create phase class implementing PhaseInterface (see [Diagram Compilation](docs/architecture/diagram-compilation.md))
+- **New Node Types**: TypeScript spec → codegen → handlers → update schema. See [Developer Guide](docs/guides/developer-guide-diagrams.md)
+- **New Diagram Formats**: Create strategy (parser/transformer/serializer). See [Developer Guide](docs/guides/developer-guide-diagrams.md#adding-new-diagram-formats)
+- **GraphQL Operations**: Add definition in `/dipeo/models/src/frontend/query-definitions/` → codegen. See [GraphQL Layer](docs/architecture/graphql-layer.md)
+- **API/UI Changes**: Modify schema → `make graphql-schema` or work in `/apps/web/src/`
 
 ## Important Notes
 

docs/agents/backend-development.md

@@ -112,6 +112,78 @@ echo '<diagram-content>' | dipeo compile --stdin --light --push-as my_workflow
 dipeo export examples/simple_diagrams/simple_iter.light.yaml output.py --light
 ```
 
+**`dipeo ask`** - AI-assisted diagram creation
+```python
+# Create diagram from natural language request
+dipeo ask "Create a workflow that processes user data"
+
+# Create and run immediately
+dipeo ask "Process user data" --and-run
+```
+
+**`dipeo convert`** - Convert between diagram formats
+```python
+# Convert diagram format
+dipeo convert input.light.yaml output.readable.yaml --from-format light --to-format readable
+```
+
+**`dipeo list`** - List available diagrams
+```python
+# List all diagrams
+dipeo list
+
+# List in JSON format
+dipeo list --json
+
+# Filter by format
+dipeo list --format light
+```
+
+**`dipeo stats`** - Show diagram statistics
+```python
+# Show statistics for a diagram
+dipeo stats examples/simple_diagrams/simple_iter
+```
+
+**`dipeo monitor`** - Open monitoring UI
+```python
+# Open monitor in browser
+dipeo monitor
+
+# Monitor specific diagram
+dipeo monitor --diagram my_diagram
+```
+
+**`dipeo integrations`** - Manage external integrations
+```python
+# Initialize integration configuration
+dipeo integrations init
+
+# Validate integration
+dipeo integrations validate --provider openai
+
+# Import OpenAPI spec
+dipeo integrations openapi-import spec.json my_api
+
+# Test integration
+dipeo integrations test my_provider --operation get_data
+```
+
+**`dipeo dipeocc`** - Manage Claude Code session conversion
+```python
+# List recent sessions
+dipeo dipeocc list
+
+# Convert specific session
+dipeo dipeocc convert session_id
+
+# Convert latest session
+dipeo dipeocc convert --latest
+
+# Watch for new sessions
+dipeo dipeocc watch
+```
+
 **CLI Architecture & Implementation**: The CLI uses a modular architecture: `entry_point.py` provides main entry and command registration; `parser.py` handles argument parsing with argparse; `dispatcher.py` routes commands to handlers; `cli_runner.py` implements core execution (sync and async via subprocess); `query.py` retrieves results and metrics; `formatter.py` handles JSON/text/markdown output.
 
 **Background Execution**: The `--background` flag enables async execution via subprocess isolation. When used, the runner spawns a subprocess with a unique execution_id and returns immediately with session status. The subprocess persists state to the database, preventing blocking while allowing results retrieval via `dipeo results exec_id`.
@@ -192,9 +264,9 @@ CREATE INDEX IF NOT EXISTS idx_node ON messages(node_id);
 
 **Message Store** (`message_store.py`): Persists person_job conversation messages, retrieves history for `dipeo results --verbose`, and supports MCP `see_result` tool with full context. Core methods: `save_message()`, `get_execution_messages()`, `get_node_messages()`.
 
-**State Persistence Coordination**: The database coordinates with (but does NOT replace) the core state management in `/dipeo/infrastructure/execution/state/`. YOU own database schema, SQL operations, and message store; dipeo-package-maintainer owns CacheFirstStateStore and PersistenceManager. Both layers write to the same SQLite database. Your responsibilities: schema evolution, SQL operations, message store implementation, migrations, and query optimization.
+**State Persistence Coordination**: The database coordinates with the core state management in `/dipeo/infrastructure/execution/state/`. Schema is initialized by `PersistenceManager.init_schema()` in `/dipeo/infrastructure/execution/state/persistence_manager.py` (owned by dipeo-package-maintainer). YOU own message store SQL operations and queries; dipeo-package-maintainer owns schema initialization, CacheFirstStateStore, and PersistenceManager. Both components write to the same SQLite database. Your responsibilities: message store implementation, message queries, and query optimization for backend operations.
 
-**Database Migrations**: When modifying schema, update `db_schema.py` with new CREATE TABLE/ALTER TABLE statements, test migration on existing data, document changes via `make schema-docs`, and consider backward compatibility.
+**Database Migrations**: When modifying schema, coordinate with dipeo-package-maintainer to update `PersistenceManager.init_schema()` in `/dipeo/infrastructure/execution/state/persistence_manager.py`, test migration on existing data, document changes via `make schema-docs`, and consider backward compatibility.
 
 ### 4. MCP Server Integration (apps/server/api/mcp_sdk_server/) {#mcp-server}
 **YOU OWN** the MCP (Model Context Protocol) server implementation.
@@ -287,7 +359,7 @@ Before completing any task:
 
 **CLI**: `apps/server/src/dipeo_server/cli/entry_point.py` (entry), `cli_runner.py` (execution logic), `parser.py` (argument parsing), `dispatcher.py` (command dispatch), `query.py` (query commands)
 
-**Database**: `apps/server/src/dipeo_server/infra/db_schema.py` (schema), `message_store.py` (persistence), `.dipeo/data/dipeo_state.db` (SQLite database)
+**Database**: `/dipeo/infrastructure/execution/state/persistence_manager.py` (schema initialization - package-maintainer domain), `apps/server/src/dipeo_server/infra/message_store.py` (message persistence), `.dipeo/data/dipeo_state.db` (SQLite database)
 
 **MCP**: `apps/server/src/dipeo_server/api/mcp_sdk_server/__init__.py` (server), `tools.py` (tools), `resources.py` (resources), `mcp_utils.py` (utilities)