@alucify/cli 0.6.4 → 0.7.0

package/dist/docs/help/cli/commands/mcp-install.md

@@ -0,0 +1,54 @@
+---
+order: 15
+title: "alucify mcp-install"
+description: "Install just the MCP server for Claude Code, without full Alucify integration."
+---
+
+# `alucify mcp-install`
+
+Installs the Alucify MCP server into your project's Claude Code configuration — a lightweight alternative to full [`alucify enable`](enable-disable.md).
+
+## Usage
+
+```bash
+alucify mcp-install [--with-rules]
+```
+
+## Options
+
+- `--with-rules` — also generate an AppGraph-aware section in `CLAUDE.md`. Without this flag, only the MCP server is registered; `CLAUDE.md` is untouched.
+
+## What Gets Installed
+
+- Vendored MCP server script copied to `.alucify/mcp-server.js`
+- Registration added to `.mcp.json` in your project root (Claude Code reads this on startup)
+- *(with `--with-rules`)* CLAUDE.md section explaining how to use the tools
+
+## What Doesn't Get Installed
+
+Unlike [`alucify enable`](enable-disable.md), `mcp-install` does **not**:
+
+- Install git pre-commit / post-commit hooks
+- Install Claude Code session hooks (for intent capture)
+- Install the `/alucify-plan` or `/alucify-continue` skills
+
+This makes it ideal when you want read-only AppGraph access from Claude Code without the full integration.
+
+## When to Use `mcp-install` vs. `enable`
+
+| Goal | Command |
+|---|---|
+| Just query the AppGraph from Claude Code | `alucify mcp-install` |
+| Track progress automatically on commits | `alucify enable` |
+| Capture intent from Claude Code sessions | `alucify enable` |
+| Use `/alucify-plan` skill | `alucify enable` |
+
+## Uninstalling
+
+Remove the `.mcp.json` entry for Alucify, and delete `.alucify/mcp-server.js`. No automated uninstall command (it's a thin install).
+
+## See Also
+
+- [`alucify enable` / `alucify disable`](enable-disable.md)
+- [Claude Code Integration](../../integrations/claude-code.md)
+- [MCP Server Setup](../../mcp-server/setup.md)

package/dist/docs/help/cli/commands/plan.md

@@ -0,0 +1,43 @@
+---
+order: 8
+title: "alucify plan"
+description: "Generate an implementation plan based on your current analysis."
+---
+
+# alucify plan
+
+Launches an interactive Claude Code session with your full project analysis as context, focused on planning implementation of unimplemented requirements.
+
+## Usage
+
+```bash
+alucify plan
+```
+
+No flags or options.
+
+## Prerequisites
+
+- Claude Code CLI installed and authenticated
+- A project with analysis results
+
+## What It Does
+
+1. Ensures Claude Code integration is enabled (runs `alucify enable` if needed)
+2. Opens an interactive Claude Code session
+3. Claude Code receives your project analysis as context
+4. The session focuses on planning implementation of all unimplemented requirements
+
+## Example
+
+```bash
+alucify plan
+```
+
+This opens Claude Code with a prompt to plan implementation of all outstanding requirements, using your project's analysis as a guide.
+
+## Notes
+
+- This command launches Claude Code interactively — it does not produce CLI output
+- Requires an active Claude Code or Claude Max subscription
+- The session has access to your full project analysis through the MCP server

package/dist/docs/help/cli/commands/progress.md

@@ -0,0 +1,58 @@
+---
+order: 6
+title: "alucify progress"
+description: "Show progress metrics and implementation statistics since a given version."
+---
+
+# alucify progress
+
+Shows per-requirement progress and validation coverage since the last spec analysis (or a specified version).
+
+## Usage
+
+```bash
+alucify progress [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--since vN` | Use version N as the reference point | Last spec analysis version |
+| `--json` | Output as JSON | Human-readable format |
+
+## Prerequisites
+
+- A project with spec analysis and progress tracking results
+
+## What It Shows
+
+For each requirement:
+- Name and identifier
+- Current implementation status
+- Status changes since the reference version
+- Validation coverage (e.g., "3/5 implemented, 2/5 tested")
+- New validations added since the reference
+
+A summary at the bottom shows:
+- Overall requirement progress
+- Validation coverage statistics
+- New scope (structural, requirement, or validation items added)
+
+## Examples
+
+```bash
+# Show progress since last spec analysis
+alucify progress
+
+# Show progress since version 3
+alucify progress --since v3
+
+# Output as JSON for scripting
+alucify progress --json
+```
+
+## Notes
+
+- This command reads local data only — no AI calls
+- If the baseline is stale (e.g., after a merge or rebase), a warning is shown

package/dist/docs/help/cli/commands/status.md

@@ -0,0 +1,50 @@
+---
+order: 5
+title: "alucify status"
+description: "Show the current implementation status of your project across all components."
+---
+
+# alucify status
+
+Displays a summary table showing how many components are in each implementation status, grouped by type.
+
+## Usage
+
+```bash
+alucify status [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Output as JSON instead of a table | Table format |
+
+## Prerequisites
+
+- A project with analysis results (run `analyze-code` and optionally `analyze-specs`)
+
+## Example Output
+
+```
+Type             | Planned | In Prog | Impl   | Tested | Depr
+─────────────────┼─────────┼─────────┼────────┼────────┼─────
+interface (10)   |    2    |    3    |   5    |   -    |  0
+logic (45)       |   10    |   15    |   15   |   -    |  5
+schema (25)      |    5    |    8    |   12   |   -    |  0
+requirement (50) |   20    |   10    |   15   |   5    |  0
+validation (26)  |   10    |    6    |    8   |   2    |  0
+```
+
+## JSON Output
+
+```bash
+alucify status --json
+```
+
+Returns a JSON object with counts per type and status, suitable for scripting and CI/CD pipelines.
+
+## Notes
+
+- This command reads local data only — no AI calls or network requests
+- Status reflects the latest analysis and progress tracking results

package/dist/docs/help/cli/commands/ui.md

@@ -0,0 +1,50 @@
+---
+order: 12
+title: "alucify ui"
+description: "Launch the web UI in your browser."
+---
+
+# `alucify ui`
+
+Starts a local server and opens the Alucify web UI in your default browser.
+
+## Usage
+
+```bash
+alucify ui [--port <number>] [--no-open]
+```
+
+## Options
+
+- `--port <number>` — bind to a specific port. Default: 3000, auto-falling-back to the next free port if 3000 is taken.
+- `--no-open` — start the server but don't open the browser automatically.
+
+## What It Does
+
+1. Starts a local HTTP + WebSocket server bound to `127.0.0.1:<port>`
+2. Generates a session token for this process
+3. Opens your default browser to `http://127.0.0.1:<port>/?session=<token>` (unless `--no-open`)
+4. Runs in the foreground until you press `Ctrl+C`
+
+## Examples
+
+```bash
+alucify ui                    # default port, auto-open browser
+alucify ui --port 4000        # custom port
+alucify ui --no-open          # headless — useful in CI or SSH sessions
+```
+
+## Viewing the UI on Another Machine
+
+The server binds to localhost only, so you can't just navigate to it from a different machine. If you need that:
+- Set up an SSH tunnel: `ssh -L 3000:127.0.0.1:3000 user@host`
+- Or use the Alucify Desktop app on your local machine, pointing at a shared workspace via a synced folder
+
+## Stopping
+
+`Ctrl+C` stops the server and closes any active workflow cleanly.
+
+## See Also
+
+- [Web UI — Launching](../ui/launching.md)
+- [Web UI — Dashboard](../ui/dashboard.md)

package/dist/docs/help/cli/commands/usage.md

@@ -0,0 +1,65 @@
+---
+order: 8
+title: "alucify usage"
+description: "Show a summary of AI token consumption across Alucify workflows and Claude Code sessions."
+---
+
+# alucify usage
+
+Displays a summary of token usage for the current project, including totals, breakdowns by source and model, and time-based comparisons.
+
+## Usage
+
+```bash
+alucify usage [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Output as JSON instead of formatted text | Formatted text |
+
+## Prerequisites
+
+- A workspace with `.alucify/` initialized (run `alucify enable` or any analysis command)
+
+## Example Output
+
+```
+  Token Usage
+
+  Total:      682.3K tokens (107 in + 682.2K out)
+  This Week:  682.3K tokens
+  Today:      197.2K tokens
+  Records:    23
+
+  By Source:
+    Alucify          485.1K tokens  (16 records)
+    Claude Code      197.2K tokens  (7 records)
+
+  By Model:
+    Haiku            400.0K tokens  (10 records)
+    Sonnet           282.3K tokens  (13 records)
+```
+
+## What Gets Tracked
+
+- **Alucify workflows** — tokens consumed by code analysis, spec analysis, progress tracking, and other automated agent calls
+- **Claude Code sessions** — tokens from your interactive Claude Code sessions, read from local session logs at `~/.claude/projects/`
+
+Running this command also refreshes the token store by ingesting any new Claude Code sessions that haven't been recorded yet.
+
+## JSON Output
+
+```bash
+alucify usage --json
+```
+
+Returns a JSON object with `all`, `today`, `week`, `bySource`, and `byModel` summaries, suitable for scripting.
+
+## Notes
+
+- This command reads local data only — no AI calls or network requests
+- Token data is stored in `.alucify/token-usage/usage.jsonl`
+- The same data is viewable in the VS Code extension via the Token Usage panel

package/dist/docs/help/cli/commands/version.md

@@ -0,0 +1,66 @@
+---
+order: 7
+title: "alucify version"
+description: "List saved analysis versions and compare differences between them."
+---
+
+# alucify version
+
+Lists all saved analysis versions, or compares two versions to see what changed.
+
+## Usage
+
+```bash
+alucify version [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--diff vN..vM` | Compare two versions | List all versions |
+| `--json` | Output as JSON | Human-readable format |
+
+## Listing Versions
+
+```bash
+alucify version
+```
+
+Shows all saved version snapshots with:
+- Version number
+- Creation date
+- What triggered the version (code analysis, spec analysis, or commit tracking)
+- Commit hash (if applicable)
+- Summary of what changed
+
+## Comparing Versions
+
+```bash
+alucify version --diff v1..v3
+```
+
+Shows the differences between two versions:
+- Components added
+- Components removed
+- Status changes (e.g., "Planned → Implemented")
+
+You can use either `v1..v3` or `1..3` format.
+
+## Examples
+
+```bash
+# List all versions
+alucify version
+
+# Compare v2 and v5
+alucify version --diff v2..v5
+
+# Output version list as JSON
+alucify version --json
+```
+
+## Notes
+
+- This command reads local data only — no AI calls
+- Each code analysis, spec analysis, and progress analysis creates a new version automatically

package/dist/docs/help/cli/installation.md

@@ -0,0 +1,70 @@
+---
+order: 2
+title: "Installing the CLI"
+description: "How to install the Alucify CLI tool."
+---
+
+# Installing the CLI
+
+## Requirements
+
+- **Node.js** version 18 or later
+- **npm** (comes with Node.js)
+
+## Global Install
+
+Install globally to use the `alucify` command anywhere:
+
+```bash
+npm install -g alucify
+```
+
+Then run commands directly:
+
+```bash
+alucify analyze-code
+alucify status
+```
+
+## Without Installing (npx)
+
+Use `npx` to run without a global install:
+
+```bash
+npx alucify analyze-code
+npx alucify status
+```
+
+This downloads the latest version on first use and caches it.
+
+## Local Install
+
+Install as a project dependency:
+
+```bash
+npm install alucify
+```
+
+Then use via npx or npm scripts:
+
+```bash
+npx alucify analyze-code
+```
+
+## Verifying Installation
+
+```bash
+alucify help
+```
+
+This should display a list of available commands and options.
+
+## Updating
+
+To update a global install:
+
+```bash
+npm update -g alucify
+```
+
+Using `npx` always fetches the latest version automatically.

package/dist/docs/help/cli/quickstart.md

@@ -0,0 +1,75 @@
+---
+order: 1
+title: "CLI Quick Start"
+description: "Get up and running with the Alucify CLI in under 5 minutes."
+---
+
+# CLI Quick Start
+
+The Alucify CLI lets you run analysis, manage specs, and track progress from the command line.
+
+## 1. Install
+
+```bash
+npm install -g alucify
+```
+
+Or use without installing:
+
+```bash
+npx alucify <command>
+```
+
+## 2. Analyze Your Code
+
+```bash
+alucify analyze-code
+```
+
+This scans your codebase and creates a baseline in `.alucify/`. By default, it uses Speed mode (free, no AI calls). Add `--mode balanced` or `--mode full` for deeper AI-powered analysis.
+
+## 3. Add Your Specs
+
+```bash
+alucify add-spec requirements.pdf design-spec.md api-contract.yaml
+```
+
+Import one or more specification documents.
+
+## 4. Analyze Specs
+
+```bash
+alucify analyze-specs
+```
+
+Compares your specs against your codebase to identify gaps, conflicts, and coverage issues.
+
+## 5. Check Status
+
+```bash
+alucify status
+```
+
+Shows a summary of implementation status across your project.
+
+## 6. Track Progress
+
+```bash
+alucify analyze-progress
+```
+
+Analyzes your git commits to track what's been implemented.
+
+## 7. Connect to Claude Code (Optional)
+
+```bash
+alucify enable
+```
+
+Installs hooks and an MCP server so Claude Code can access your project analysis while coding.
+
+## What's Next?
+
+- [Installing the CLI](installation.md) — More installation options
+- [CLI Authentication](authentication.md) — Configure API key or Claude Code subscription
+- [Command Reference](commands/analyze-code.md) — Full details on every command

package/dist/docs/help/cli/ui/_meta.json

@@ -0,0 +1 @@
+{ "title": "Web UI", "order": 5 }

package/dist/docs/help/cli/ui/ai-coding-risks-tab.md

@@ -0,0 +1,46 @@
+---
+order: 5
+title: "AI Coding Risks Tab"
+description: "The AI Coding Risks tab in the web UI — risk catalog and resolution."
+---
+
+# AI Coding Risks Tab
+
+The AI Coding Risks tab is where you review, prioritize, and resolve risks found during spec analysis.
+
+For what AI Coding Risks are and what each type means, see [AI Coding Risks](../../concepts/ai-coding-risks.md).
+
+## Layout
+
+The tab shows all identified risks in a sortable, filterable list. Each row includes:
+
+- **Severity** — color-coded dot (Critical / High / Medium / Low)
+- **Risk Type** — category
+- **Label** — short description
+- **Status** — Open / Fixed / Ignored
+
+## Filtering
+
+- **By severity** — show only Critical, High, etc.
+- **By type** — e.g., only Missing UX Spec or only Conflicts
+- **By status** — Open by default; toggle to see Fixed or Ignored
+
+## Resolving a Risk
+
+Click a row to expand it. You'll see:
+
+- **Recommended solution** — Alucify's best-guess fix
+- **Alternative solutions** — other ways to address it
+- **Resolve via chat** — opens the [Chat Panel](chat-panel.md) with this risk pre-loaded. Claude helps you refine the relevant spec.
+- **Ignore** — mark the risk as not relevant (can always be unignored)
+
+## Bulk Actions
+
+Select multiple risks with the checkbox column, then use the bulk bar at the top:
+
+- **Refine Specs** — open chat with all selected risks in context
+- **Ignore selected** — mark all selected as ignored
+
+## Where Risks Come From
+
+Risks are generated during spec analysis. If you haven't run spec analysis yet, this tab is empty. See [Workflow Overview](../../concepts/workflow-overview.md).

package/dist/docs/help/cli/ui/appgraph-visualizer-tab.md

@@ -0,0 +1,54 @@
+---
+order: 7
+title: "AppGraph Visualizer Tab"
+description: "The AppGraph Visualizer tab in the web UI — interactive graph of your project."
+---
+
+# AppGraph Visualizer Tab
+
+The AppGraph Visualizer is an interactive force-directed graph of every node and edge in your [AppGraph](../../concepts/appgraph.md). Use it to explore structure, trace dependencies, and investigate specific nodes.
+
+## Graph Controls
+
+- **Zoom** — scroll wheel or pinch
+- **Pan** — click and drag on empty space
+- **Select a node** — click it; details open in a right-side panel
+- **Focus** — double-click a node to center and zoom in on it
+- **Fit to screen** — keyboard `F` or the Fit button
+
+## Filters
+
+The filter panel on the left lets you narrow what's shown:
+
+- **Node type** — Interface, Logic, Schema, FunctionalArea, FeatureSpec, Validation, etc.
+- **Status** — Planned / In Progress / Implemented / Tested
+- **Origin** — which spec or source file introduced the node
+- **Intent-captured only** — show only nodes added via [intent capture](../../concepts/intent-capture.md)
+- **Connected to** — focus on the neighborhood around a specific node
+
+## Search
+
+The search bar accepts free text. Results highlight matching nodes; click a result to focus it.
+
+## Node Details Panel
+
+When you click a node, the right panel shows:
+
+- Name, type, and description
+- Status (with gap notes if in-progress)
+- Source file paths (click to open)
+- Inbound and outbound edges (click an edge to navigate to the connected node)
+- Grounding — which spec or code location introduced this node
+
+## Edge Types
+
+Edges are color-coded:
+- **Parent** (gray) — hierarchical
+- **Implements** (blue) — Logic implements FeatureSpec
+- **Validates** (green) — Validation covers AcceptanceCriterion
+- **Depends on** (orange) — runtime or code dependency
+- **Affects** (red) — change-impact; used for [blast radius](../../concepts/blast-radius.md)
+
+## Performance
+
+Very large graphs (thousands of nodes) may render slowly. Use the type/status filters to narrow the view; the force layout runs faster on smaller subsets.

package/dist/docs/help/cli/ui/artifacts-sidebar.md

@@ -0,0 +1,53 @@
+---
+order: 10
+title: "Artifacts Sidebar"
+description: "Managing specs in the web UI — upload, filter, generate, delete."
+---
+
+# Artifacts Sidebar
+
+The Artifacts sidebar is always visible on the left side of the web UI (below the nav). It's where you manage all your imported specs.
+
+For what artifacts are and what formats are supported, see [Artifacts & Specs](../../concepts/artifacts-and-specs.md).
+
+## Adding Artifacts
+
+- **Drag and drop** — drop files (PDF, Markdown, images, etc.) directly onto the sidebar
+- **Add button** — opens a file picker
+- Multiple files can be added at once
+
+Files are copied to `.alucify/artifacts/` and given an initial status of **Pending**.
+
+## Filter Buttons
+
+Four filter pills let you narrow the list:
+
+- **All** — every artifact
+- **Pending** — not yet analyzed
+- **Preview** — partially analyzed (mini-AppGraph extracted, not yet integrated)
+- **Analyzed** — fully integrated into the project AppGraph
+
+The filter persists across sessions.
+
+## Artifact Actions
+
+Hover an artifact for quick actions:
+
+- **Open** — view the artifact's contents in the main panel
+- **Delete** — remove it from the project (archives any extracted nodes)
+- **Re-analyze** — force re-analysis even if the file hasn't changed
+
+## Generate Button
+
+The **Generate** button at the top opens the [Chat Panel](chat-panel.md) in "Generate Artifact" mode. Pick a template (PRD, architecture, UX, epic/story, quick spec, custom), describe what you want, and Claude drafts a new artifact.
+
+## Status Badges
+
+Each artifact row shows a colored badge indicating status:
+- **Gray** — Pending
+- **Yellow** — Preview
+- **Green** — Analyzed
+
+## Auto-Analyze
+
+If you've enabled **Auto-trigger spec analysis on artifact upload** in Settings, newly-added artifacts trigger analysis immediately rather than waiting for a manual **Analyze Specs** click.