devworkspace 0.3.0 → 0.3.2

package/docs/architecture-report/diagrams.md

@@ -0,0 +1,446 @@
+# Visual Architecture Diagrams Catalog
+
+> **Consolidated visual reference catalog containing all 8 core Mermaid architecture, sequence, and workflow diagrams for DevWorkspace v0.3.1.**
+
+---
+
+## Catalog Index
+
+| # | Diagram Title | Type | Source Chapter |
+|:---:|---|---|---|
+| **1** | [High-Level System Architecture](#diagram-1-high-level-system-architecture) | Flowchart | [Chapter 2: System Architecture](./02-system-architecture.md) |
+| **2** | [CLI Startup and Command Dispatch Workflow](#diagram-2-cli-startup-and-command-dispatch-workflow) | Sequence Diagram | [Chapter 4: Execution Flows](./04-execution-flows.md) |
+| **3** | [Project Analysis & Discovery Engine Workflow](#diagram-3-project-analysis--discovery-engine-workflow) | Flowchart | [Chapter 4: Execution Flows](./04-execution-flows.md) |
+| **4** | [Tool and Integration Ecosystem Map](#diagram-4-tool-and-integration-ecosystem-map) | Flowchart | [Chapter 2: System Architecture](./02-system-architecture.md) |
+| **5** | [Agent Skills Lifecycle & Execution Flow](#diagram-5-agent-skills-lifecycle--execution-flow) | Sequence Diagram | [Chapter 4: Execution Flows](./04-execution-flows.md) |
+| **6** | [Build, Test & Deployment Pipeline](#diagram-6-build-test--deployment-pipeline) | Flowchart | [Chapter 8: Build, Test & Deployment](./08-build-test-deployment.md) |
+| **7** | [Repository Structure Map](#diagram-7-repository-structure-map) | Graph | [Chapter 5: Codebase Map](./05-codebase-map.md) |
+| **8** | [Feature Implementation Map](#diagram-8-feature-implementation-map) | Flowchart | [Chapter 10: Feature Status](./10-feature-status.md) |
+
+---
+
+## Diagram 1: High-Level System Architecture
+
+Illustrates the 4-layer subsystem architecture (Presentation, Service Orchestration, Domain Engines, Core Foundation & Security):
+
+```mermaid
+flowchart TD
+    subgraph UI_Layer["1. Presentation Layer"]
+        CLI_Entry["CLI Entrypoint\n(src/cli/main.ts)"]
+        ArgParser["Arg Parser\n(src/cli/args.ts)"]
+        CommandRouter["Command Dispatcher\n(src/cli/run.ts)"]
+        TerminalRenderer["Terminal / JSON Renderer\n(src/cli/render.ts)"]
+    end
+
+    subgraph Service_Layer["2. Service Orchestration Layer"]
+        SvcInit["initWorkspace()"]
+        SvcAnalyze["analyzeWorkspace()"]
+        SvcStatus["getStatus()"]
+        SvcDoctor["runDoctor()"]
+        SvcAgent["installAgent()"]
+        SvcTask["createTask() / runTaskCheck()"]
+        SvcKnowledge["addFact() / getContext()"]
+        SvcIntegrations["setupIntegrations()"]
+    end
+
+    subgraph Engine_Layer["3. Domain Engine Subsystems"]
+        subgraph DiscoverySub["Discovery Engine"]
+            Scanner["Filesystem Scanner\n(src/discovery/scan.ts)"]
+            Detector["Stack & Framework Detector\n(src/discovery/detect.ts)"]
+            CommandBuilder["Testing Contract Builder\n(src/discovery/commands.ts)"]
+            DocScanner["Documentation Detector\n(src/discovery/docs.ts)"]
+            EntryScanner["Entry Points Detector\n(src/discovery/entrypoints.ts)"]
+        end
+
+        subgraph AgentsSub["Multi-Agent Compatibility Engine"]
+            AgentRegistry["Agent Registry\n(src/agents/index.ts)"]
+            ClaudeAdapter["Claude Code Adapter\n(CLAUDE.md & SKILL.md)"]
+            CodexAdapter["OpenAI Codex Adapter\n(AGENTS.md)"]
+            CursorAdapter["Cursor Adapter\n(.cursor/rules/)"]
+            CopilotAdapter["Copilot Adapter\n(.github/copilot-instructions.md)"]
+            SectionMerger["Non-Destructive Section Merger\n(src/agents/shared.ts)"]
+        end
+
+        subgraph TasksSub["Task & Verification Engine"]
+            TaskRouter["Request Classifier\n(src/tasks/routing.ts)"]
+            TaskLifecycle["Task State Machine\n(src/tasks/task.ts)"]
+            GateEvaluator["evaluateGate()\n(src/tasks/task.ts)"]
+            SafetyClassifier["classifyCommand()\n(src/verification/safety.ts)"]
+            ScopeTracker["Scope & Baseline Tracker\n(src/verification/scope.ts)"]
+        end
+
+        subgraph IntegrationsSub["External Integration Manager"]
+            IntManager["Integration Manager\n(src/integrations/manager.ts)"]
+            GraphifyAdapter["Graphify Adapter\n(graphifyy PyPI)"]
+            AgentSkillsAdapter["Agent Skills Adapter\n(addyosmani/agent-skills)"]
+            PonytailAdapter["Ponytail Adapter\n(DietrichGebert/ponytail)"]
+            OmniRouteAdapter["OmniRoute Adapter\n(Observed optional)"]
+        end
+    end
+
+    subgraph Foundation_Layer["4. Core Foundation & Security"]
+        WorkspaceCore["Workspace Root & Paths\n(src/core/workspace.ts)"]
+        SecurityFiles["safeReadText() & Path Guard\n(src/security/files.ts)"]
+        SecretRedact["findSecrets() & redact()\n(src/security/redact.ts)"]
+        AtomicFs["atomicWriteJson() & Lockfile\n(src/utils/fs.ts, lock.ts)"]
+        Schemas["Data Contracts & Validation\n(src/config/schemas.ts)"]
+    end
+
+    CLI_Entry --> ArgParser
+    ArgParser --> CommandRouter
+    CommandRouter --> Service_Layer
+    CommandRouter --> TerminalRenderer
+
+    SvcInit --> WorkspaceCore
+    SvcAnalyze --> DiscoverySub
+    SvcAgent --> AgentsSub
+    SvcTask --> TasksSub
+    SvcIntegrations --> IntegrationsSub
+
+    DiscoverySub --> SecurityFiles
+    TasksSub --> SafetyClassifier
+    TasksSub --> ScopeTracker
+    AgentsSub --> SectionMerger
+    IntegrationsSub --> AtomicFs
+
+    SecurityFiles --> WorkspaceCore
+    AtomicFs --> Schemas
+    SecretRedact --> AtomicFs
+```
+
+*Detailed Analysis*: [Chapter 2: System Architecture & Subsystem Model](./02-system-architecture.md)
+
+---
+
+## Diagram 2: CLI Startup and Command Dispatch Workflow
+
+Traces the execution sequence from terminal command invocation to exit code:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Developer / Agent
+    participant OS as Operating System / Shell
+    participant Main as CLI Entry (src/cli/main.ts)
+    participant Parser as Arg Parser (src/cli/args.ts)
+    participant Dispatcher as Dispatcher (src/cli/run.ts)
+    participant Service as Service Function (src/services/*)
+    participant Renderer as Renderer (src/cli/render.ts)
+
+    User->>OS: Runs "devworkspace analyze --cwd . --json"
+    OS->>Main: Launches node dist/cli/main.js
+    Note over Main: Hooks SIGINT & SIGTERM<br/>to run cleanups & release locks
+    Main->>Dispatcher: run(process.argv.slice(2))
+    Dispatcher->>Parser: parseCli(argv)
+    Note over Parser: Strict validation using node:util<br/>Rejects unknown flags immediately
+    Parser-->>Dispatcher: ParsedArgs { values, positionals }
+    Dispatcher->>Dispatcher: Resolve command alias ("tasks" -> "task list")
+    Dispatcher->>Dispatcher: Initialize Ctx (logger, styles, stdout/stderr, cwd)
+    Dispatcher->>Service: Call handler (e.g. analyzeWorkspace(ws, svc))
+    Service-->>Dispatcher: Returns structured result object
+    Dispatcher->>Renderer: Format output (JSON or styled ANSI/ASCII text)
+    Renderer-->>Main: Write to stdout / stderr
+    Main->>OS: Set process.exitCode (0, 1, 2, 3, or 130)
+    OS-->>User: Process terminates with output
+```
+
+*Detailed Analysis*: [Chapter 4: Execution Flows & Lifecycles](./04-execution-flows.md#1-workflow-a-cli-startup-and-dispatch)
+
+---
+
+## Diagram 3: Project Analysis & Discovery Engine Workflow
+
+Details the 3-phase repository analysis pipeline:
+
+```mermaid
+flowchart TD
+    Start["devworkspace analyze"] --> CheckWs["Find .devworkspace/<br/>(src/core/workspace.ts)"]
+    CheckWs --> Lock["Acquire File Lock<br/>(.devworkspace/local/workspace.lock)"]
+
+    subgraph ScanningPhase["1. Bounded Filesystem Scan"]
+        Scan["scan.ts: readdirRecursive()<br/>• Max 10,000 files<br/>• Ignore node_modules, .git, dist<br/>• Detect symlinks (skip to prevent loops)"]
+    end
+    
+    subgraph DetectionPhase["2. Deterministic Detection"]
+        DetectStack["detect.ts:<br/>• Language extensions (.ts, .py, .go)<br/>• Frameworks from manifests<br/>• Monorepo structure"]
+        DetectCommands["commands.ts:<br/>• Inspect scripts in package.json<br/>• Map typecheck, unit, integration, build<br/>• Record exact cwd per command"]
+        DetectDocs["docs.ts:<br/>• Identify READMEs, docs/, ADRs (max 25)"]
+        DetectEntry["entrypoints.ts:<br/>• Identify server.ts, workers, CLIs"]
+        DetectSens["files.ts:<br/>• Record names of .env files (never read content)"]
+    end
+
+    subgraph OutputPhase["3. State & Prompt Generation"]
+        WriteDiscovery[".devworkspace/analysis/discovery.json"]
+        WriteCommands[".devworkspace/context/commands.json"]
+        GenPrompt["prompts/onboarding.ts:<br/>Generate onboarding-prompt.md"]
+        ValidateReqs["prompts/requirements.ts:<br/>Validate prompt against 21 requirements"]
+        SaveFacts["knowledge/facts.ts:<br/>Record 10+ DETECTED facts in facts.json"]
+    end
+
+    Lock --> ScanningPhase
+    ScanningPhase --> DetectionPhase
+    DetectionPhase --> OutputPhase
+    OutputPhase --> ReleaseLock["Release File Lock"]
+    ReleaseLock --> Finish["Render Analysis Summary to stdout"]
+```
+
+*Detailed Analysis*: [Chapter 4: Execution Flows & Lifecycles](./04-execution-flows.md#2-workflow-b-project-analysis-workflow)
+
+---
+
+## Diagram 4: Tool and Integration Ecosystem Map
+
+Illustrates connections between internal DevWorkspace modules, Node.js built-ins, and external toolchains:
+
+```mermaid
+flowchart LR
+    subgraph InternalModules["Internal DevWorkspace Modules"]
+        CLI["src/cli/"]
+        SvcAnal["src/services/analysis.ts"]
+        SvcAgent["src/services/agent.ts"]
+        SvcInt["src/services/integrations.ts"]
+        SvcVer["src/services/verify.ts"]
+        Sec["src/security/"]
+    end
+
+    subgraph NodeBuiltins["Node.js 20+ Built-in APIs"]
+        FS["node:fs / node:fs/promises"]
+        Path["node:path"]
+        Proc["node:child_process (spawnSync)"]
+        Crypto["node:crypto (createHash, randomUUID)"]
+        Util["node:util (parseArgs)"]
+        OS["node:os (tmpdir, platform)"]
+    end
+
+    subgraph ExternalAgents["Coding Agent Instruction Targets"]
+        ClaudeCode["Claude Code (CLAUDE.md)"]
+        Codex["OpenAI Codex / Antigravity (AGENTS.md)"]
+        Cursor["Cursor IDE (.cursor/rules/)"]
+        Copilot["GitHub Copilot (.github/copilot-instructions.md)"]
+    end
+
+    subgraph ExternalToolchains["External Subprocesses (Observed / Coordinated)"]
+        Git["git (git status, rev-parse, diff)"]
+        GraphifyCli["graphify (Python / pipx / uv)"]
+        ClaudeCli["claude (plugin list, plugin install)"]
+        SkillsCli["skills (npx skills add)"]
+        NodeExe["node (for Ponytail lifecycle hooks)"]
+        ProjectNPM["npm / pnpm / yarn (running contract tests)"]
+    end
+
+    CLI --> Util
+    CLI --> FS
+    SvcAnal --> FS
+    SvcAnal --> Path
+    SvcAgent --> ExternalAgents
+    SvcInt --> Proc
+    SvcInt --> GraphifyCli
+    SvcInt --> ClaudeCli
+    SvcInt --> SkillsCli
+    SvcInt --> NodeExe
+    SvcVer --> Git
+    SvcVer --> ProjectNPM
+    Sec --> Crypto
+    Sec --> Path
+    Sec --> FS
+```
+
+*Detailed Analysis*: [Chapter 2: System Architecture & Subsystem Model](./02-system-architecture.md#4-diagram-4-tool-and-integration-map)
+
+---
+
+## Diagram 5: Agent Skills Lifecycle & Execution Flow
+
+Details how external integrations are inspected, snapshotted, and installed safely:
+
+```mermaid
+sequenceDiagram
+    autonumber
+    actor User as Developer / Agent
+    participant Svc as setupIntegrations()
+    participant Mgr as IntegrationManager (src/integrations/manager.ts)
+    participant Adapter as Adapter (Graphify / Agent Skills / Ponytail)
+    participant Exec as Process Runner (src/integrations/exec.ts)
+    participant Protect as Snapshot Guard (src/integrations/protect.ts)
+    participant FS as Local Filesystem
+
+    User->>Svc: devworkspace setup --integrations [--yes]
+    Svc->>Mgr: run(options)
+    
+    loop For each adapter (Graphify, Agent Skills, Ponytail, OmniRoute)
+        Mgr->>Adapter: inspect(AdapterContext, deep=true)
+        Adapter->>Exec: which(toolName), run(tool --version)
+        Exec-->>Adapter: Tool status, version string
+        Adapter-->>Mgr: IntegrationReport { status: INSTALLED | NOT_INSTALLED | DEGRADED }
+        
+        Mgr->>Adapter: plan(AdapterContext, targetScope)
+        Adapter-->>Mgr: PlanResult { steps, protectPaths, blockers }
+    end
+
+    alt Dry-Run or Missing --yes
+        Mgr-->>User: Output planned steps & require confirmation (Exit Code 2)
+    else User Confirmed (--yes)
+        loop For each planned step
+            Mgr->>Protect: Take snapshot of protectPaths (e.g. CLAUDE.md)
+            Mgr->>Exec: Run installation command (e.g. "graphify install --project")
+            Mgr->>Protect: Verify snapshot; rollback if user changes overwritten
+            Mgr->>Adapter: Re-inspect to verify successful installation
+        end
+        Mgr->>FS: Save state to .devworkspace/state/integrations.json
+        Mgr-->>User: Report outcomes (VERIFIED, RESTART_REQUIRED, or DEGRADED)
+    end
+```
+
+*Detailed Analysis*: [Chapter 4: Execution Flows & Lifecycles](./04-execution-flows.md#3-workflow-c-agent-skills--integrations-lifecycle)
+
+---
+
+## Diagram 6: Build, Test & Deployment Pipeline
+
+Traces the entire verification and publishing lifecycle:
+
+```mermaid
+flowchart TD
+    subgraph Developer["Local Development"]
+        Source["TypeScript Source (src/)"]
+        Tests["Test Suites (tests/unit, integration, e2e)"]
+        Clean["scripts/clean.mjs\n(Purges dist/)"]
+    end
+
+    subgraph BuildPipeline["Compilation & Packaging"]
+        TSC["TypeScript Compiler (tsc -p tsconfig.build.json)\nES2022, NodeNext, Declarations (.d.ts), Maps (.js.map)"]
+        Pack["npm pack --ignore-scripts\n(Generates devworkspace-<version>.tgz)"]
+    end
+
+    subgraph TestGates["Quality & Verification Gates"]
+        Typecheck["npm run typecheck\n(Strict TS validation)"]
+        ESLint["npm run lint\n(ESLint flat config)"]
+        Vitest["npm run coverage\n(778 tests across Unit, Integration, E2E)"]
+        Audit["npm run audit:security\n(Production dependency audit)"]
+        ReleaseCheck["scripts/release-check.mjs\n(Hygiene, Semver, Docs, Tags, Clean Git)"]
+        Smoke["scripts/smoke.mjs\n(Tarball inspection & isolated CLI run)"]
+    end
+
+    subgraph CICD["GitHub Actions Automation"]
+        CIWorkflow[".github/workflows/ci.yml\n(Ubuntu, Windows, macOS on Node 20 & 22)"]
+        ReleaseWorkflow[".github/workflows/release.yml\n(Manual dispatch, OIDC Trusted Publishing)"]
+    end
+
+    subgraph Registry["Distribution"]
+        NPMRegistry["npm Registry (Public)\nhttps://www.npmjs.com/package/devworkspace"]
+    end
+
+    Source --> Clean
+    Clean --> TSC
+    TSC --> Pack
+    Source --> Typecheck
+    Source --> ESLint
+    Tests --> Vitest
+    Pack --> Smoke
+    Typecheck & ESLint & Vitest & Audit & Smoke --> ReleaseCheck
+
+    ReleaseCheck --> CIWorkflow
+    CIWorkflow --> ReleaseWorkflow
+    ReleaseWorkflow -->|"npm publish --access public (OIDC Token)"| NPMRegistry
+```
+
+*Detailed Analysis*: [Chapter 8: Build, Test & Deployment Architecture](./08-build-test-deployment.md)
+
+---
+
+## Diagram 7: Repository Structure Map
+
+Visualizes directory hierarchy and module organization:
+
+```mermaid
+graph TD
+    Root["devworkspace/"]
+
+    subgraph Src["src/ (TypeScript Source Code)"]
+        CLI["cli/ - Entrypoints, argument parsing, command dispatch, and formatting"]
+        Services["services/ - Pure service orchestration layer (16 command handlers)"]
+        Discovery["discovery/ - Deterministic repository scanning and stack detection"]
+        Agents["agents/ - Multi-agent adapters (Claude, Codex, Cursor, Copilot)"]
+        Integrations["integrations/ - External tool management (Graphify, Skills, Ponytail)"]
+        Tasks["tasks/ - Task routing, state machines, and completion gates"]
+        Knowledge["knowledge/ - Facts engine, authority ranking, and staleness detection"]
+        Decisions["decisions/ - Architecture Decision Records (ADRs) management"]
+        Sessions["sessions/ - Compact engineering session handover logs"]
+        Verification["verification/ - Command safety checks and scope tracking"]
+        Security["security/ - Path traversal defense, symlink containment, secret redaction"]
+        Core["core/ - Workspace discovery, schema migrations, and versioning"]
+        Config["config/ - Type-safe data contracts and schema validators"]
+        Git["git/ - Read-only Git state and tracked file discovery"]
+        Prompts["prompts/ - Onboarding and refresh prompt generators and validators"]
+        Portability["portability/ - JSON export/import bundling and validation"]
+        Utils["utils/ - Atomic file operations, lockfiles, loggers, and cleanup"]
+        Errors["errors/ - Typed error hierarchy and exit code definitions"]
+    end
+
+    subgraph Scripts["scripts/ (Build & Release Automation)"]
+        Clean["clean.mjs - Build directory cleanup"]
+        ReleaseCheck["release-check.mjs - Pre-release quality gate"]
+        Smoke["smoke.mjs - Fresh-install smoke testing"]
+        Bench["bench.mjs - Performance and token usage benchmarking"]
+    end
+
+    subgraph Tests["tests/ (Automated Test Suites)"]
+        Unit["unit/ - 21 unit test suites for individual modules"]
+        Integration["integration/ - 5 integration suites testing full flows and shims"]
+        E2E["e2e/ - 2 end-to-end scenario suites testing real CLI execution"]
+        Helpers["helpers/ - Fake process runners and tool mocks"]
+    end
+
+    subgraph Docs["docs/ (Project Documentation)"]
+        UserDocs["User & Developer Guides (getting-started, architecture, security, etc.)"]
+        ReportDir["architecture-report/ - This comprehensive architecture documentation"]
+        ImplNotes["implementation/ - Internal design notes and historical ADRs"]
+    end
+
+    Root --> Src
+    Root --> Scripts
+    Root --> Tests
+    Root --> Docs
+```
+
+*Detailed Analysis*: [Chapter 5: Codebase Map & Module Responsibilities](./05-codebase-map.md)
+
+---
+
+## Diagram 8: Feature Implementation Map
+
+Visualizes feature status partitioning across implementation tiers:
+
+```mermaid
+flowchart TD
+    subgraph FullyImplemented["🟢 Fully Implemented & Verified in Source"]
+        CoreInit["Workspace Init & Reset\n(src/services/init.ts, reset.ts)"]
+        DiscoveryScan["Deterministic Discovery Scanner\n(src/discovery/scan.ts, detect.ts)"]
+        TestingContract["Testing Contract Mapping\n(src/discovery/commands.ts)"]
+        TaskEngine["Task Lifecycle & Verification Gates\n(src/tasks/task.ts, routing.ts)"]
+        SafeExecution["Safe Task Run (ReadOnly Checks)\n(src/services/verify.ts)"]
+        FactsEngine["Knowledge Facts & Authority Ranks\n(src/knowledge/facts.ts)"]
+        ADRRecords["Architecture Decision Records (ADRs)\n(src/services/records.ts)"]
+        MultiAgentAdapters["Agent Adapters (Claude, Codex, Cursor, Copilot)\n(src/agents/*)"]
+        SecretsRedaction["Secrets Redaction & Symlink Containment\n(src/security/*)"]
+        PortabilityBundle["Import / Export Knowledge Bundles\n(src/services/portability.ts)"]
+    end
+
+    subgraph PartialOrGuarded["🟡 Partial / Guarded by Design"]
+        DBExecution["Service & DB-Touching Test Execution\n(src/verification/safety.ts: requires testenv declare)"]
+        DeepIntegrations["Integration Auto-Repair & Verification\n(src/integrations/manager.ts: requires --yes)"]
+    end
+
+    subgraph OptionalOrDelegated["🔵 Optional / Ecosystem-Delegated"]
+        GraphifyGraph["Graphify Graph Construction\n(src/integrations/adapters/graphify.ts: delegated to Claude Code /graphify .)"]
+        OmniRouteObs["OmniRoute Model Routing\n(src/integrations/adapters/omniroute.ts: observed on PATH only, never invoked)"]
+    end
+
+    subgraph UnverifiedOrPlanned["⚪ External / Unimplemented in Core"]
+        LiveTranscripts["Live Interactive Transcripts\n(Explicitly avoided: only summary handoffs stored)"]
+        NetworkTelemetry["Cloud Telemetry / Remote Analytics\n(Explicitly avoided: zero network calls)"]
+    end
+```
+
+*Detailed Analysis*: [Chapter 10: Feature Implementation Status & Discrepancy Analysis](./10-feature-status.md)
+

package/docs/architecture.md

@@ -27,7 +27,7 @@ The CLI contains no business logic. `src/index.ts` exports the services so a fut
 | `security/` | Sensitive-file rules, secret detection/redaction, safe reading |
 | `git/` | Porcelain parsing and state (no mutating Git commands anywhere) |
 | `integrations/` | Integration manager: one `IntegrationAdapter` per tool (observe, plan, verify), consent levels, file protection, state, runner abstraction (Windows shims, npx) |
-| `agents/` | `AgentAdapter` interface + the Claude adapter (managed `CLAUDE.md` block, skill) |
+| `agents/` | `AgentAdapter` contract, shared section-merging engine, and concrete adapters for Claude Code, OpenAI Codex (`AGENTS.md`), Cursor (`.cursor/rules` and `.cursorrules`), and GitHub Copilot (`.github/copilot-instructions.md`) |
 | `prompts/` | Onboarding/refresh prompt builders and the behavioural requirement checker |
 | `portability/` | Export bundle format and hostile-input validation |
 | `utils/` | Atomic writes, locking, safe paths, subprocess runner, logger |
@@ -36,7 +36,7 @@ The CLI contains no business logic. `src/index.ts` exports the services so a fut
 
 - **Zero runtime dependencies.** Argument parsing uses `node:util`, validation is hand-written, hashing/locking use Node built-ins. Smaller supply-chain surface; dev-only tooling.
 - **Deterministic core, AI at the edges.** Everything DevWorkspace does itself is reproducible and testable. Reasoning is delegated to the agent through generated prompts, and the prompts are themselves tested against a requirement list (`prompts/requirements.ts`).
-- **Adapters at every external boundary.** Core code sees `IntegrationStatus` and `PlannedChange`, never Graphify internals or Claude paths. Adding Cursor/Codex means a new `AgentAdapter`.
+- **Adapters at every external boundary.** Core code sees `IntegrationStatus` and `PlannedChange`, never external agent-specific paths. Coding agent adapters (Claude Code, OpenAI Codex, Cursor, GitHub Copilot) implement the common `AgentAdapter` contract.
 - **Single routing source.** `tasks/routing.ts` is the table from which the generated skill and `docs/routing.md` are derived.
 - **State is portable by default.** Anything machine-specific lives in `.devworkspace/local/`. Project identity is a UUID, paths are relative everywhere, and doctor flags absolute paths.
 - **Fail closed on the future.** Files with a newer `schemaVersion` are never modified; commands refuse with an upgrade hint.

package/docs/getting-started.md

@@ -1,6 +1,25 @@
 # Getting started
 
-## 1. Set up
+## Quick Start (One Command)
+
+```bash
+cd path/to/your/project
+npx devworkspace setup
+```
+
+`devworkspace setup` inspects your repository, initializes `.devworkspace/` non-destructively, discovers package verification commands, detects command-contract drift against manifests and directories, verifies feature knowledge, and displays a comprehensive health and readiness report with actionable next steps.
+
+To also install and verify optional integrations (Graphify, Agent Skills, Ponytail), run:
+
+```bash
+npx devworkspace setup --integrations --yes
+```
+
+---
+
+## Step-by-Step Workflow
+
+### 1. Set up
 
 ```bash
 cd path/to/your/project
@@ -58,6 +77,24 @@ npx devworkspace doctor
 
 Ask Claude for what you want. See [routing](routing.md) for how requests are handled and [claude.md](claude.md) for what was installed. After meaningful work Claude records durable knowledge; you can inspect it any time with `devworkspace context`, and run `devworkspace refresh` after large changes (or after pulling) to catch stale knowledge.
 
+## Feature Map & Graph Navigation
+
+Connect frontend entry points, backend routes, services, database tables, and tests into verifiable feature slices:
+
+```bash
+devworkspace feature list
+devworkspace feature show auth.login
+devworkspace feature validate
+devworkspace feature add --id sales.orders --name "Sales Orders" --entry src/pages/Orders.tsx --route src/routes/sales.ts --symbol OrderController
+```
+
+Navigate relationships safely with bounded Graphify tracing:
+
+```bash
+devworkspace graph status
+devworkspace graph trace src/routes/sales.ts --depth 2
+```
+
 ## Start over
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devworkspace",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Project-local AI engineering workspace: deterministic repository discovery, portable project knowledge, tasks, decisions and verification gates for AI coding agents.",
   "type": "module",
   "bin": {