@alucify/cli 0.6.4 → 0.7.0

package/dist/docs/help/mcp-server/tools/verify-plan.md

@@ -0,0 +1,82 @@
+---
+order: 6
+title: "Verifying a Plan"
+description: "How the verify_plan tool mechanically checks a plan's appgraph references."
+---
+
+# Verifying a Plan
+
+The `verify_plan` tool checks a planning document against the appgraph to catch invented IDs, off-by-one drift, and silent omissions before the plan is presented or executed.
+
+## What It Does
+
+Runs three deterministic checks against the plan text:
+
+1. **Invalid IDs** — Extracts every appgraph ID (`nv*`, `nl*`, `ni*`, `nr*`, `ns*`) from the plan and confirms each exists in the current appgraph. Catches hallucinations.
+2. **Name mismatches** — Compares the plan's description near each ID against the actual node's name and description using token overlap. Catches off-by-one drift where the plan cites the wrong ID for a described task.
+3. **Missing coverage** — Lists untested validations and in-progress components that need work but aren't referenced anywhere in the plan. Catches silent omissions.
+
+No LLM calls — all checks are mechanical.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `plan_text` | string | Yes | The full plan text including task descriptions and any `link_context` references |
+| `require_coverage_for` | enum | No | `"all"` (default): flag every untested/in-progress item not in the plan. `"requirements"`: only flag entirely absent requirements. `"none"`: skip coverage check. |
+
+## What It Returns
+
+```json
+{
+  "valid": false,
+  "summary": "Found 44 IDs in plan | 11 INVALID (do not exist in appgraph) | 7 likely mismatched | 22 missing coverage",
+  "invalidIds": [
+    { "id": "nv00057", "nearbyText": "Task 5.1: TestAC_AgentAccountFieldSync (nv00057) ..." }
+  ],
+  "nameMismatches": [
+    {
+      "id": "nv00042",
+      "actualName": "Orphaned quota entry is warned and excluded",
+      "actualDescription": "...",
+      "planContext": "Task 2.7: TestLoadState_Corrupted (nv00042) — test malformed JSON...",
+      "similarity": 0.04
+    }
+  ],
+  "missingIds": [
+    {
+      "id": "nv00001",
+      "type": "validation",
+      "name": "Registering a new account and marking default",
+      "requirement": "nr00001: Register Multiple Provider Accounts",
+      "reason": "untested validation"
+    }
+  ],
+  "guidance": "Fix invalid IDs: these do not exist in the appgraph..."
+}
+```
+
+## How It's Used
+
+The `/alucify-plan` skill calls this tool as the final step before presenting a plan. If verification fails, the planning agent fixes the flagged issues and re-runs verification until `valid: true`.
+
+## Example Workflow
+
+```
+1. Plan agent writes plan referencing nv00057-nv00067
+2. verify_plan returns invalidIds: ["nv00057", ...] because IDs only go up to nv00055
+3. Plan agent removes invented IDs, replaces with real ones from get_implementation_tasks
+4. verify_plan re-runs — this time nameMismatches flags nv00042 because the plan's
+   description ("TestLoadState_Corrupted") doesn't match nv00042's actual name
+   ("Orphaned quota entry warning")
+5. Plan agent corrects the ID mapping
+6. verify_plan re-runs and returns valid: true
+7. Plan is presented to the user
+```
+
+## Notes
+
+- Name mismatches use a conservative similarity threshold — only obvious mismatches are flagged
+- The tool does not check the quality of the plan's tasks — only whether IDs are real and coverage is complete
+- `missingIds` is capped at 100 results to keep the response bounded
+- Safe to call repeatedly — verification is cheap and has no side effects

package/dist/docs/help/mcp-server/tools/version-diff.md

@@ -0,0 +1,42 @@
+---
+order: 6
+title: "Comparing Analysis Versions"
+description: "How to use the diff tool to compare two analysis versions and see what changed."
+---
+
+# Comparing Analysis Versions
+
+The `diff_context` tool compares two versions of your project analysis to show what was added, removed, or changed.
+
+## What It Does
+
+Takes two version numbers and returns a structured diff showing how your project evolved between them.
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `from_version` | string | Yes | Starting version (e.g., `v3` or `3`) |
+| `to_version` | string | Yes | Ending version (e.g., `v5` or `5`) |
+
+Both `v3` and `3` formats are accepted.
+
+## What It Returns
+
+- **Components added** — New components that appear in the later version (with ID, type, and name)
+- **Components removed** — Components that no longer exist in the later version
+- **Status changes** — Components whose implementation status changed (e.g., `planned` → `implemented`)
+- **Connection count change** — Net change in the number of connections between versions
+
+## Example Use Cases
+
+| Question | Parameters |
+|----------|------------|
+| "What changed since our baseline?" | `from_version: "v1", to_version: "v3"` |
+| "What did the last spec analysis add?" | Compare the two most recent versions |
+| "How has implementation progressed?" | Compare an early and late version to see status changes |
+
+## Notes
+
+- Each code analysis, spec analysis, and progress analysis creates a new version automatically
+- Use `alucify version` in the CLI to list all available versions

package/dist/docs/help/mcp-server/using-with-claude-code.md

@@ -0,0 +1,72 @@
+---
+order: 4
+title: "Using MCP with Claude Code"
+description: "How the /alucify-plan and /alucify-continue skills use MCP tools in practice."
+---
+
+# Using MCP with Claude Code
+
+Once the MCP server is installed (via [`alucify enable`](../cli/commands/enable-disable.md) or [`alucify mcp-install`](../cli/commands/mcp-install.md)), Claude Code sessions in your project get access to every [MCP tool](tools/tools-reference.md) and the [Terminology Resource](resources/terminology-resource.md).
+
+## Installed Skills
+
+`alucify enable` also installs two slash commands:
+
+### `/alucify-plan`
+
+Launches a Claude Code session focused on planning work. The skill:
+1. Calls `get_remaining_work` to see what's open
+2. Calls `get_implementation_tasks` for each target requirement
+3. Composes a plan with concrete implementation steps
+4. Calls `verify_plan` to mechanically check the plan (valid IDs, coverage, no drift)
+5. Presents the verified plan to you for approval
+
+Use when: you want to plan the next chunk of work with AppGraph awareness.
+
+### `/alucify-continue`
+
+Launches a Claude Code session focused on closing gaps. The skill:
+1. Reads the most recent progress analysis
+2. Identifies in-progress nodes with gap notes
+3. Picks the next logical one to close
+4. Plans and (with your approval) implements the fix
+
+Use when: you want to keep momentum — there's work in progress and you want it finished.
+
+## Manual Tool Use
+
+You can always call MCP tools directly in any Claude Code session. Typical patterns:
+
+**"What's left to build?"**
+- Claude calls `get_remaining_work`
+- You get a prioritized list of open requirements
+
+**"What's the blast radius of changing `UserAccount`?"**
+- Claude calls `trace_dependencies` with the file path
+- You get direct + transitive impacts up to 3 hops
+
+**"Don't name a new field — use the existing one."**
+- Claude calls `find_similar_context` before creating nodes
+- The terminology resource (always loaded) prevents most drift without an explicit tool call
+
+## Verifying Plans
+
+`verify_plan` is meant to catch common mistakes in LLM-generated plans:
+- Hallucinated node IDs that don't exist
+- Name drift (slight variations of real names)
+- Plans that claim to implement X but don't touch X's acceptance criteria
+
+If a plan fails verification, the skill tells Claude Code to fix it before presenting to you.
+
+## Troubleshooting
+
+**MCP server not appearing in Claude Code:**
+1. Check `.mcp.json` exists in your project root
+2. Restart Claude Code
+3. Run `alucify mcp-install --with-rules` to reinstall
+
+**Tools time out:**
+The server caches for 5 seconds; very large AppGraphs may need longer on the first call. Re-run the tool; subsequent calls are fast.
+
+**Stale data:**
+MCP serves the current version of the AppGraph. Run `alucify analyze-progress` (or just commit — the hook fires) to refresh.

package/dist/docs/help/reference/_meta.json

@@ -0,0 +1 @@
+{ "title": "Reference", "order": 8 }

package/dist/docs/help/reference/alucify-directory.md

@@ -0,0 +1,86 @@
+---
+order: 1
+title: "The .alucify Directory Structure"
+description: "What's inside the .alucify directory — versions, analysis reports, and configuration files."
+---
+
+# The .alucify Directory Structure
+
+Alucify stores all analysis data in a `.alucify/` directory at the root of your project. This directory is created automatically when you first run an analysis.
+
+## Directory Layout
+
+```
+.alucify/
+├── appgraph-baseline.json    # Code analysis baseline
+├── appgraph-project.json     # Combined code + spec analysis
+├── artifact-manifest.json    # Spec import tracking
+├── artifacts/                # Imported spec documents
+│   ├── requirements.pdf
+│   ├── api-spec.md
+│   └── ...
+├── versions/                 # Versioned snapshots
+│   ├── v1/
+│   ├── v2/
+│   └── ...
+├── analysis/                 # Analysis reports
+│   └── [date]/
+│       ├── congruency/
+│       ├── coverage-report.md
+│       └── quality-synthesis-report.md
+├── progress/                 # Progress tracking data
+│   ├── checkpoint.json
+│   └── gaps.json
+├── token-usage/              # Token consumption logs
+│   └── usage.jsonl           # All-time usage records (Alucify + Claude Code sessions)
+├── extractions/
+│   └── intents/              # Intent capture output (requires intentCapture.enabled)
+│       └── *.json            # Extracted intent files pending AppGraph integration
+├── archived/                 # Data from previous resets
+│   └── [timestamp]/
+├── mcp-server.js             # Vendored MCP server (if installed)
+└── debug-logs/               # Debug logs (if enabled)
+```
+
+## Key Files
+
+### appgraph-baseline.json
+The result of code analysis — a structured model of your codebase's architecture. Created by `Analyze Code` or `alucify analyze-code`.
+
+### appgraph-project.json
+The combined model after spec analysis — includes both your code baseline and spec analysis results. Created by `Analyze Specs` or `alucify analyze-specs`.
+
+### artifact-manifest.json
+Tracks which spec files have been imported and their analysis status (pending, analyzed).
+
+### artifacts/
+Contains copies of all imported specification documents. Files are copied here when you use **Add Spec** or `alucify add-spec`.
+
+### versions/
+Each analysis run creates a versioned snapshot. These allow you to compare how your project evolves over time.
+
+### analysis/
+Reports generated during spec analysis — congruency reports per artifact, coverage reports, and quality synthesis reports.
+
+### progress/
+Progress tracking data from commit analysis:
+- `checkpoint.json` — Records the last analyzed commit hash and timestamp
+- `gaps.json` — Gap report from the most recent progress analysis
+
+### token-usage/
+Token consumption records across all Alucify workflows and Claude Code sessions. `usage.jsonl` is an append-only log — you can commit it for team visibility or add it to `.gitignore` to keep it local.
+
+### extractions/intents/
+Intent capture output, created when `alucify.intentCapture.enabled` is on. Contains extracted intent files waiting to be integrated into the AppGraph. See [Intent Capture](../vscode/intent-capture/enabling-intent-capture.md).
+
+### archived/
+When you reset your analysis, all existing data is moved here with a timestamp. See [Resetting Your Analysis](../vscode/resetting-analysis.md).
+
+## Version Control
+
+You can choose whether to commit `.alucify/` to your repository:
+
+- **Commit it** — Team members can use the MCP server and view analysis results without re-running analysis
+- **Gitignore it** — Each developer runs their own analysis locally
+
+If committing, consider adding `debug-logs/` to your `.gitignore`.

package/dist/docs/help/reference/file-types-and-formats.md

@@ -0,0 +1,76 @@
+---
+order: 4
+title: "File Types & Formats"
+description: "What file types Alucify can ingest, and what formats its outputs use."
+---
+
+# File Types & Formats
+
+## Input: Spec Artifacts
+
+Formats you can add as specs:
+
+| Format | Extension | Notes |
+|---|---|---|
+| PDF | `.pdf` | Multi-page; Alucify slices pages per analysis chunk |
+| Markdown | `.md`, `.markdown` | PRDs, READMEs, design docs |
+| JSON | `.json` | Structured specs, OpenAPI, schemas |
+| YAML | `.yaml`, `.yml` | Config, schemas |
+| HTML | `.html`, `.htm` | Exported docs, web-published specs |
+| Plain text | `.txt` | Free-form |
+| Images | `.png`, `.jpg`, `.jpeg`, `.gif`, `.webp` | Wireframes, mockups; requires vision-capable model |
+| Source files | `.ts`, `.js`, `.py`, `.go`, `.java`, `.rs`, `.rb`, `.cs`, `.cpp`, `.c`, `.swift`, `.kt` | Used as reference implementations; languages = same as code analysis |
+
+See [Supported Project Types](../getting-started/supported-project-types.md) for the full code-side language list.
+
+## Input: Source Code
+
+Alucify detects languages automatically during code analysis. See [Supported Project Types](../getting-started/supported-project-types.md).
+
+## Output Formats
+
+### AppGraph (JSON)
+`.alucify/appgraph-baseline.json` and `.alucify/appgraph-project.json` are the canonical AppGraph files. JSON is pretty-printed and versioned via `.alucify/versions/`.
+
+### Analysis Reports
+- Congruency: `.alucify/analysis/congruency.json`
+- Coverage: `.alucify/analysis/coverage.json`
+- Impact: `.alucify/analysis/impact.json`
+- Findings: `.alucify/analysis/findings.json`
+- Tech debt: `.alucify/analysis/tech-debt.json`
+
+### Progress
+- `.alucify/progress/checkpoint.json` — current progress state
+- `.alucify/progress/log.jsonl` — append-only commit log
+
+### Token Usage
+- `.alucify/token-usage/usage.jsonl` — append-only log of every LLM call
+- `.alucify/token-usage/state.*.json` — per-user session reader state (gitignored)
+
+### Intent Capture
+- `.alucify/extractions/intents/*.json` — staged intent, pending integration
+
+### Exports
+
+| From UI | Format |
+|---|---|
+| CLI `--json` | JSON (single object or line-delimited) |
+| Web UI → Export | CSV (usage data), Markdown (reports), JSON (raw data) |
+| VS Code → Compare Versions → Export | Markdown or JSON |
+
+## Machine-Readable API
+
+For programmatic access, use:
+- **MCP server** — [tools](../mcp-server/tools/tools-reference.md) return structured JSON
+- **CLI `--json`** — every reporting command
+- **Web REST API** — `/api/artifacts`, `/api/usage`, etc. (same session-token auth as the web UI)
+
+## Internal-Use Only
+
+Some files in `.alucify/` are internal to Alucify's workflow engine and shouldn't be edited directly:
+
+- `*.lock` — concurrency locks
+- `*.partial` — in-flight analysis state
+- `debug-logs/` — verbose logs (for troubleshooting)
+
+If you see these, leave them alone. They're cleaned up automatically.

package/dist/docs/help/reference/glossary.md

@@ -0,0 +1,60 @@
+---
+order: 2
+title: "Glossary of Terms"
+description: "Definitions of key terms used throughout Alucify: congruency, coverage, grounding, and more."
+---
+
+# Glossary of Terms
+
+## AI Coding Risks
+Issues identified by Alucify that could cause problems when AI coding agents work on your project. Examples include missing specs, conflicting requirements, and high blast radius areas.
+
+## AI Readiness
+A composite score (0–100%) summarizing how prepared your project is for AI coding. Factors in congruency, coverage, completeness, and other metrics. Higher is better.
+
+## Analysis Mode
+The depth level for analysis. Three options:
+- **Speed** (catalog) — Mechanical analysis, no AI cost
+- **Balanced** (fast) — AI-powered with moderate depth
+- **Quality** (full) — Comprehensive AI analysis
+
+## Baseline
+The structured model of your codebase created by code analysis. This is the foundation that spec analysis builds on.
+
+## Blast Radius
+The percentage of your project that could be affected by a change in a specific area. A high blast radius means changes ripple across many components.
+
+## Claude Code
+Anthropic's AI coding assistant that runs in the terminal. Alucify can integrate with Claude Code via the MCP server to provide project context.
+
+## Completeness
+How thoroughly your specifications cover all necessary dimensions. High completeness means your specs address requirements, designs, data models, and acceptance criteria.
+
+## Congruency
+How well your specifications align with your codebase. High congruency means specs and code tell the same story with few contradictions or mismatches.
+
+## Coverage
+The proportion of your codebase that has corresponding specifications. High coverage means most components have requirements or specs backing them.
+
+## Grounding
+How well a component is anchored in your specifications. Strong grounding means clear spec references and well-defined requirements. Weak grounding suggests the component needs better documentation.
+
+## Health Score
+A 0–100 rating of your architecture's structural health from the Technical Debt Analysis. Considers coupling, complexity, dependency cycles, and other structural factors.
+
+## Implementation Status
+The development stage of a component:
+- **Planned** — Specified but not started
+- **In Progress** — Currently being worked on
+- **Implemented** — Code written
+- **Tested** — Tests exist and pass
+- **Deprecated** — No longer active
+
+## MCP (Model Context Protocol)
+A protocol that lets AI tools like Claude Code communicate with external data sources. Alucify's MCP server gives Claude Code access to your project analysis.
+
+## Spec (Specification)
+A document describing what your project should do — PRDs, requirements documents, design files, API specifications, and other project documentation.
+
+## Version
+A numbered snapshot of your analysis at a point in time (v1, v2, v3, etc.). Created automatically each time you run code analysis, spec analysis, or progress analysis.

package/dist/docs/help/reference/how-claude-code-integration-works.md

@@ -0,0 +1,123 @@
+---
+order: 3
+title: "How Claude Code Integration Works"
+description: "What Alucify installs into your Claude Code environment, how the pieces fit together, and what each one does."
+---
+
+# How Claude Code Integration Works
+
+When you run `alucify enable` (or toggle the integration in VS Code), Alucify installs four components that give Claude Code structured awareness of your project. Each serves a distinct purpose — together they form a feedback loop that helps Claude plan with real architecture context, implement against actual requirements, and track progress automatically.
+
+## What Gets Installed
+
+| Component | File | Purpose |
+|-----------|------|---------|
+| CLAUDE.md instructions | `CLAUDE.md` | Teaches Claude what the appgraph is and when to use it |
+| Hooks | `.claude/settings.json` | Injects context at key moments (planning, task creation, subagent start) |
+| MCP server | `.mcp.json` | Gives Claude tools to query your project's architecture on demand |
+| Git hooks | `.git/hooks/pre-commit` + `post-commit` | Analyzes commits against the appgraph for progress tracking |
+
+All installations are marker-based and idempotent — running `enable` multiple times is safe, and `disable` cleanly removes everything while preserving your analysis data.
+
+## CLAUDE.md Instructions
+
+**What it is:** A small section (~200 tokens) added to your project's `CLAUDE.md` file, delimited by `<!-- alucify:appgraph:start -->` / `<!-- alucify:appgraph:end -->` markers.
+
+**What it does:** Teaches Claude the mental model of your project's appgraph — the node type system (requirements, interfaces, schemas, logic, validations), how they connect via edges, and rules for when to query the architecture. For example: "Before planning features, call `query_context()` to find existing components" and "Call `trace_dependencies()` before cross-cutting changes to check blast radius."
+
+**Why it matters:** Without these instructions, Claude has MCP tools available but doesn't know *when* to use them. The instructions bridge that gap — they're always loaded, never go stale (they contain rules, not data), and work regardless of how large your project is.
+
+## Hooks
+
+**What they are:** Entries in `.claude/settings.json` that run automatically when Claude Code reaches specific moments in its workflow.
+
+**What they do:** Each hook injects a small, targeted piece of context:
+
+| Hook | When it fires | What it injects |
+|------|---------------|-----------------|
+| **EnterPlanMode** | When Claude enters formal planning | Unimplemented requirements with validation status, plus a step-by-step exploration workflow |
+| **ExitPlanMode** | When Claude finishes a plan, before presenting it | Validation warnings — missing dependencies, uncovered acceptance criteria, nodes referenced but not addressed |
+| **TodoWrite** | When Claude creates or updates tasks | Per-task context — related appgraph nodes, blast radius, acceptance criteria from validation nodes |
+
+**Why they matter:** Hooks deliver the right context at the right time without dumping your entire architecture into every conversation. The planning hooks ensure Claude's plans account for real dependencies and requirements. Task hooks give each implementation step the specific context it needs.
+
+**Note:** Not every Claude Code interaction uses all hooks. For simple tasks like bug fixes, only CLAUDE.md rules are active — Claude won't enter plan mode for a one-line fix, and that's the right behavior. The planning and task hooks activate naturally when Claude tackles more complex work.
+
+## MCP Server
+
+**What it is:** A lightweight server that starts as a subprocess when Claude Code connects. It reads your `.alucify/` analysis data and exposes it through tools and resources.
+
+**What it does:** Gives Claude on-demand access to your project's architecture:
+
+| Tool | What it answers |
+|------|-----------------|
+| `query_context` | "What screens exist?" "Find anything related to auth" "What's still planned?" |
+| `get_context` | Full detail on a specific node — UI structure, data model, state machines, connected nodes |
+| `trace_dependencies` | "If I change this file, what else is affected?" — blast radius analysis |
+| `get_remaining_work` | Unimplemented requirements, untested validations, orphaned nodes |
+| `get_implementation_tasks` | Per-requirement task list with gap notes and untested validations — used by `/alucify-plan` |
+| `link_context` | Link a node to its implementation file so progress tracking can find it |
+| `verify_plan` | Mechanically validate a plan's appgraph references before presenting it |
+| `find_similar_context` | "Is there already a concept called X?" — terminology grounding for artifact drafting |
+| `diff_context` | What changed between two analysis versions |
+| `get_analysis` | Congruency, coverage, or quality report summaries |
+
+**Why it matters:** The MCP server is the primary data source — it's where the actual architecture knowledge lives. The CLAUDE.md instructions teach Claude *when* to query, the hooks *nudge* Claude with summaries, but the MCP tools *provide the data*. This keeps the design scale-independent: a 50-node project and a 5,000-node project work identically because Claude queries what it needs rather than receiving everything upfront.
+
+All tools are read-only except `link_context`, which updates a node's file reference for progress tracking.
+
+## Git Hooks (Pre-Commit + Post-Commit)
+
+**What they are:** Two hooks in `.git/hooks/` that work together to analyze every commit.
+
+**How they work:**
+
+1. **Pre-commit hook** (synchronous, ≤15s timeout): Runs `alucify analyze-progress --pre-commit` to classify staged files against the appgraph using a single LLM call. On success, the analysis output (updated appgraph, version snapshot) is staged into the same commit — so everything lands in a single atomic commit with zero leftover files.
+
+2. **Post-commit hook** (async fallback): Only runs if the pre-commit analysis timed out or failed. In that case, it runs the full async analysis in the background, and the results are auto-staged into the *next* commit by the pre-commit hook.
+
+**Why they matter:** This closes the loop. The other three components help Claude *plan and write* code with architecture awareness. The git hooks track *what was actually built*, so you can see progress against your requirements without manual bookkeeping — and without requiring a second commit.
+
+## How They Work Together
+
+Here's the flow across a typical development session:
+
+```
+Session starts
+  └─ CLAUDE.md loaded → Claude knows the node types and when to query
+
+You ask Claude to plan a feature
+  └─ EnterPlanMode hook → "Here's what's unfinished: nr00045 (0/3 tested)..."
+  └─ Claude calls MCP tools → query_context, get_context, trace_dependencies
+  └─ ExitPlanMode hook → "⚠ ProjectDetail also depends on this schema"
+  └─ Claude presents plan with node IDs and dependency warnings
+
+You approve, Claude implements
+  └─ TodoWrite hook → per-task blast radius + acceptance criteria
+  └─ Claude calls link_context → links nodes to implementation files
+  └─ Claude edits files
+
+You commit
+  └─ Git hook captures changed files
+  └─ analyze-progress matches commits to nodes → statuses update
+```
+
+For simpler tasks (bug fixes, refactors), Claude skips the planning hooks entirely and works with just the baseline — CLAUDE.md rules and MCP tools available if needed.
+
+## `enable` vs `mcp-install`
+
+If you don't need the full integration — for example, you're consuming an appgraph a teammate built and just want Claude to be able to query it — you can install only the MCP server:
+
+```bash
+alucify mcp-install --with-rules
+```
+
+This gives you the MCP server and CLAUDE.md instructions but skips hooks and commit tracking. See [MCP Server Setup](../mcp-server/setup.md) for details.
+
+| | `enable` | `mcp-install --with-rules` |
+|---|---|---|
+| MCP server (query tools) | Yes | Yes |
+| CLAUDE.md instructions | Yes | Yes |
+| Hooks (session, planning, tasks) | Yes | No |
+| Git hook (commit tracking) | Yes | No |
+| Best for | Running analysis + developing | Consuming a teammate's analysis |

package/dist/docs/help/reference/ui-parity-matrix.md

@@ -0,0 +1,121 @@
+---
+order: 3
+title: "UI Parity Matrix"
+description: "What features are available in each of Alucify's four UIs."
+---
+
+# UI Parity Matrix
+
+Alucify's four UIs — CLI, VS Code Extension, Web UI, and Desktop App — share a single core server. Most features are available in all four. This page lists what's where.
+
+## Legend
+
+- ✅ Available
+- ⚠️ Limited / read-only
+- ❌ Not available (by design or not yet)
+
+## Analysis
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Analyze code | ✅ | ✅ | ✅ | ✅ |
+| Analyze specs | ✅ | ✅ | ✅ | ✅ |
+| Analyze progress | ✅ | ✅ | ✅ | ✅ |
+| Congruency / coverage / impact / findings (standalone) | ⚠️ (via composition) | ✅ (Advanced Mode) | ❌ | ❌ |
+| Analysis modes (Speed/Balanced/Quality) | ✅ | ✅ | ✅ | ✅ |
+
+## Artifacts
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Add artifact | ✅ `add-spec` | ✅ | ✅ (drag+drop) | ✅ (drag+drop) |
+| Filter by status | ⚠️ (via `status`) | ✅ | ✅ | ✅ |
+| Generate artifact (AI) | ❌ | ✅ | ✅ | ✅ |
+| Audit artifact | ❌ | ✅ | ❌ | ❌ |
+
+## AI Coding Risks
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| View risks | ⚠️ (via `status --json`) | ✅ | ✅ | ✅ |
+| Resolve via chat | ❌ | ✅ | ✅ | ✅ |
+| Bulk refine | ❌ | ✅ | ✅ | ✅ |
+| Ignore risk | ❌ | ✅ | ✅ | ✅ |
+
+## AppGraph Visualizer
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Interactive graph | ❌ | ✅ | ✅ | ✅ |
+| Filter by type/status/origin | ❌ | ✅ | ✅ | ✅ |
+| Node details | ⚠️ (via MCP) | ✅ | ✅ | ✅ |
+
+## Chat
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Ask about project | ❌ | ✅ | ✅ | ✅ |
+| Refine specs | ❌ | ✅ | ✅ | ✅ |
+| Generate artifact | ❌ | ✅ | ✅ | ✅ |
+
+## Progress Tracking
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Progress dashboard | ⚠️ (via `progress --json`) | ✅ | ✅ | ✅ |
+| Trigger progress analysis | ✅ | ✅ | ✅ | ✅ |
+| Reset progress | ❌ | ✅ (Advanced) | ❌ | ❌ |
+
+## Versions
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| List versions | ✅ `version` | ✅ (Advanced) | ❌ | ❌ |
+| Diff versions | ✅ `version --diff` | ✅ (Advanced) | ❌ | ❌ |
+| Switch version | ❌ | ✅ (Advanced) | ❌ | ❌ |
+| Delete version | ❌ | ✅ (Advanced) | ❌ | ❌ |
+
+## Intent Capture
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Automatic polling | ❌ | ✅ (`alucify.intentCapture.enabled`) | ❌ | ❌ |
+| Manual capture | ✅ `capture-intent` | ✅ | ❌ | ❌ |
+| Capture + integrate in one step | ❌ | ✅ | ❌ | ❌ |
+
+"Automatic polling" is a persistent background process in the VS Code extension that checks for new Claude Code sessions. The CLI has no persistent state — you invoke capture manually or via cron.
+
+## Token Usage
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Summary | ✅ `usage` | ✅ | ✅ | ✅ |
+| Daily chart | ❌ | ✅ | ✅ | ✅ |
+| Per-user / per-model / per-workflow breakdowns | ⚠️ (via `--json`) | ✅ | ✅ | ✅ |
+| Export CSV | ❌ | ❌ | ✅ | ✅ |
+
+## Authentication
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| API key mode | ✅ | ✅ | ✅ | ✅ |
+| Claude Code subscription mode | ✅ | ✅ | ✅ | ✅ |
+| Switch auth mode | ✅ (re-run with flag) | ✅ | ✅ | ✅ |
+
+## Integrations
+
+| Feature | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| `alucify enable` (full install) | ✅ | ✅ (via command) | ❌ | ❌ |
+| `alucify mcp-install` (lightweight) | ✅ | ❌ | ❌ | ❌ |
+| MCP server management | ✅ | ✅ | ⚠️ (settings toggle) | ⚠️ (settings toggle) |
+| Git hooks management | ✅ | ✅ | ❌ | ❌ |
+
+## UI-Native Only Features
+
+Some features exist only in their native UI because they'd make no sense elsewhere:
+
+- **CLI-only:** `--json` output, scripting-friendly exit codes, pre-commit hook
+- **VS Code-only:** status bar item, tree view sidebars, command palette integration, in-editor file jump
+- **Web-only:** drag-and-drop file upload, browser-native URLs for share/bookmark
+- **Desktop-only:** native file picker, OS menu bar, native notifications, workspace switcher

package/dist/docs/help/vscode/_meta.json

@@ -0,0 +1 @@
+{ "title": "VS Code Extension", "order": 4 }