@alucify/cli 0.6.5 → 0.7.0

package/dist/docs/help/extension/spec-analysis/auditing-specs.md

@@ -0,0 +1,30 @@
+---
+order: 6
+title: "Auditing Imported Specs"
+description: "How to run an audit on your imported specifications to check for quality and completeness."
+---
+
+# Auditing Imported Specs
+
+The spec audit checks the quality of your imported specifications before or after a full analysis.
+
+## How to Audit Specs
+
+1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Search for **Alucify: Audit Specs**
+3. The audit runs against all imported specifications
+
+## What the Audit Checks
+
+The audit evaluates your specs for:
+
+- **Completeness** — Are all necessary details present? Are there missing sections or undefined requirements?
+- **Clarity** — Are requirements specific enough for an AI coding agent to implement?
+- **Consistency** — Do specs use consistent terminology? Are there contradictions between documents?
+- **Actionability** — Can each requirement be turned into a concrete implementation?
+
+## When to Audit
+
+- **After importing new specs** — Check that your documents are suitable for analysis before running full spec analysis
+- **After refining specs** — Verify that changes improved quality
+- **When AI readiness scores are low** — An audit can help identify which specs need improvement

package/dist/docs/help/extension/spec-analysis/filtering-and-browsing-specs.md

@@ -0,0 +1,43 @@
+---
+order: 3
+title: "Filtering & Browsing the Specs Panel"
+description: "How to filter, browse, and manage your imported specifications."
+---
+
+# Filtering & Browsing the Specs Panel
+
+The **Specifications** panel in the Alucify sidebar shows all your imported spec documents and their analysis status.
+
+## Spec Lifecycle
+
+Each spec goes through a lifecycle shown at the top of the panel:
+
+1. **Pending** — The spec has been imported but not yet analyzed
+2. **Analyzed** — The spec has been fully analyzed and integrated
+
+Click on any status label to filter the list to specs in that state. The count next to each status shows how many specs are in that phase.
+
+## Filtering Specs
+
+### Using the Filter Button
+
+1. Click the **Filter** icon (funnel) in the Specifications panel header
+2. Choose a filter:
+   - **Show All** — Display all specs regardless of status
+   - **Pending** — Only show specs awaiting analysis
+   - **Analyzed** — Only show fully analyzed specs
+
+### Clearing Filters
+
+When a filter is active, the filter icon changes to indicate filtering is on. Click **Clear Filter** (filled funnel icon) to remove the filter and show all specs.
+
+## Refreshing the List
+
+Click the **Refresh** icon in the panel header to update the specs list. This is useful if you've added files to the `.alucify/artifacts/` directory outside of VS Code.
+
+## Spec Actions
+
+From the panel, you can:
+
+- **Add Spec** — Import new specification documents
+- **Generate Spec** — Create specs using AI (requires Claude Code CLI)

package/dist/docs/help/extension/spec-analysis/generating-specs.md

@@ -0,0 +1,47 @@
+---
+order: 2
+title: "Generating Specs with AI"
+description: "How to use AI to generate specification documents from your codebase."
+---
+
+# Generating Specs with AI
+
+If you don't have existing specification documents, Alucify can help you generate them using AI.
+
+## Prerequisites
+
+- **Claude Code CLI** must be installed and authenticated on your machine
+- The Generate Spec button only appears when the CLI is detected
+
+## How to Generate a Spec
+
+1. In the **Specifications** panel, click the **Generate Spec** button (wand icon)
+2. Choose an artifact type from the picker:
+   - **Product Requirements Document** — Goals, personas, and functional requirements
+   - **Architecture Document** — Tech stack, system design, and architecture decisions
+   - **UX Specification** — User flows, screen designs, and interaction patterns
+   - **Epics & Stories** — Break down requirements into implementable work items
+   - **Quick Spec** — Lightweight technical spec for a focused task
+   - **Custom** — Describe any artifact you need
+3. An interactive chat session opens in the sidebar
+4. The AI uses your project context (if available) to draft the spec, and asks clarifying questions for anything it can't infer
+
+The generated spec is saved to `.alucify/artifacts/` and automatically picked up by Alucify for analysis.
+
+## Project Context
+
+If you've run a baseline or artifact analysis, the AI will use your project's architecture, data models, requirements, and coverage gaps to pre-populate the spec. This means you don't have to re-describe what already exists — the AI starts from what it knows and asks only about what's missing.
+
+For greenfield projects with no analysis, the AI guides you through each section step by step.
+
+## When to Use This
+
+- You have an existing codebase but no formal requirements documentation
+- You want to create API specifications from existing endpoints
+- You need to document existing business logic for AI coding agents
+- You're starting a new feature and want a structured spec template
+
+## Notes
+
+- The generated spec is a starting point — review and refine it before running spec analysis
+- You can also [add specs manually](adding-specs.md) if you prefer to write them yourself

package/dist/docs/help/extension/spec-analysis/refining-specs.md

@@ -0,0 +1,53 @@
+---
+order: 7
+title: "Refining Specs with Chat"
+description: "How to use the interactive chat to refine and improve your specifications."
+---
+
+# Refining Specs with Chat
+
+After analyzing your specs and reviewing the identified risks, you can work with Claude interactively to resolve issues and improve your specifications.
+
+## Starting a Refinement Session
+
+### From the AI Coding Risks Panel
+
+1. Open the [AI Coding Risks](../code-analysis/understanding-ai-coding-risks.md) panel
+2. Select one or more risks using the checkboxes
+3. Click the **Refine Specs** button (shows "Refine Specs (N selected)" with your selection count)
+4. A chat panel opens in the secondary sidebar
+
+### From the Command Palette
+
+1. Press `Ctrl+Shift+P` / `Cmd+Shift+P`
+2. Search for **Alucify: Refine Specs**
+
+## Using the Chat
+
+The chat panel opens with context about your selected risks. You can:
+
+- **Discuss the risks** — Ask Claude about the issues and get suggestions
+- **Review proposed changes** — Claude will suggest spec updates to resolve each risk
+- **Guide the resolution** — Tell Claude how you want to address each issue
+- **Type `/done`** to end the session
+- **Type `/help`** to see available commands
+
+As Claude resolves risks, their status updates from Open to Fixed in the AI Coding Risks panel.
+
+## Chat Mode vs. Terminal Mode
+
+Alucify supports two modes for spec refinement, configurable in settings:
+
+### Chat Mode (Default)
+An embedded chat panel in the VS Code secondary sidebar. You interact with Claude through a conversation interface, seeing messages, tool usage, and spec updates in real time.
+
+### Terminal Mode
+Uses the Claude Code CLI in a VS Code terminal. Progress is shown in the terminal output. This mode is useful if you prefer a CLI-based workflow.
+
+To switch modes, go to VS Code Settings and search for `alucify.refineSpecs.mode`.
+
+## Tips
+
+- **Select related risks together** — Resolving related risks in a single session is more efficient than addressing them one at a time
+- **Be specific** — Tell Claude how you want to resolve ambiguous issues rather than accepting all defaults
+- **Review changes** — After a session, re-run spec analysis to verify that the refinements improved your scores

package/dist/docs/help/extension/spec-analysis/understanding-the-spec-analysis-tab.md

@@ -0,0 +1,55 @@
+---
+order: 5
+title: "Understanding the Spec Analysis Tab"
+description: "A walkthrough of the Spec Analysis tab — congruency, coverage, completeness, and recommendations."
+---
+
+# Understanding the Spec Analysis Tab
+
+The Spec Analysis tab is the second of three tabs in the Project Analysis panel. It shows how well your specifications align with your codebase.
+
+## Key Metrics
+
+At the top of the tab, you'll see several scores (0–100%):
+
+### Congruency
+How well your specs align with your code. A high congruency score means your specs and code tell the same story — there are few contradictions or mismatches.
+
+### Coverage
+How much of your codebase is covered by specifications. High coverage means most components have corresponding requirements or specs.
+
+### Blast Radius
+The percentage of your project that could be affected by a change. Lower is better — it means changes are well-contained.
+
+### AI Readiness
+A composite score combining congruency, coverage, and other factors. This is the overall indicator of how prepared your project is for AI coding.
+
+Each score includes a sparkline showing the trend across analysis versions.
+
+## Sections
+
+### Congruency
+Shows a heatmap of how well each specification aligns with the codebase. Each row represents one of your imported specs. Click **View Details** to see the full congruency report for a specific spec.
+
+### Coverage
+Horizontal bars showing what percentage of each component type is grounded in specifications. Higher bars mean better spec coverage.
+
+### Completeness
+A visual indicator of how complete your specification coverage is across different dimensions.
+
+### Impact
+A pie chart showing how your project is distributed across impact categories:
+- **New** — Components introduced by specs that don't exist in code yet
+- **Modified** — Existing components that specs would change
+- **Affected** — Components indirectly impacted by spec changes
+- **Intact** — Components unaffected by spec changes
+
+### AI Coding Risks
+A summary of identified risks with severity counts. Click **View Details** to open the full [AI Coding Risks](../code-analysis/understanding-ai-coding-risks.md) panel.
+
+### Recommendations
+The top priority actions to improve your AI readiness score, ordered by impact. Click **View Details** to see the full list of recommendations.
+
+## Empty State
+
+If you haven't added or analyzed specs yet, the tab shows: "Please add specs and analyze them to update this tab." with links to add specs and run analysis.

package/dist/docs/help/extension/token-usage/_meta.json

@@ -0,0 +1 @@
+{ "title": "Token Usage", "order": 7 }

package/dist/docs/help/extension/token-usage/understanding-token-usage.md

@@ -0,0 +1,64 @@
+---
+order: 2
+title: "Understanding Token Usage"
+description: "What tokens are, how they're categorized, and how to interpret your usage data."
+---
+
+# Understanding Token Usage
+
+## What Are Tokens?
+
+Tokens are the unit of measurement for AI model input and output. Roughly, 1 token is about 4 characters of English text. Every interaction with Claude — whether through Alucify workflows or direct Claude Code sessions — consumes tokens.
+
+## Token Types
+
+Each API call produces four types of token usage:
+
+### Output Tokens
+Tokens generated by the model in its response (completions, code, analysis). This is typically the largest component of usage.
+
+### Cache Read Tokens
+Input tokens that were served from Claude's prompt cache rather than reprocessed. Cached tokens are significantly cheaper than regular input tokens (90% discount). Alucify uses prompt caching extensively to reduce costs.
+
+### Cache Creation Tokens
+Input tokens that were written to the prompt cache for the first time. These cost slightly more than regular input (25% premium) but enable cache reads on subsequent calls.
+
+### Input Tokens (Non-cached)
+Input tokens that were neither cached nor cache-eligible. This is typically a small number since Alucify enables caching on system prompts and large content blocks.
+
+## Sources
+
+Token usage comes from two distinct sources:
+
+### Alucify
+Tokens consumed by Alucify's analysis workflows — code analysis, spec analysis, progress tracking, congruency checks, etc. These are automated agent calls managed by Alucify. Each record includes the specific workflow, phase, and agent that consumed the tokens.
+
+### Claude Code
+Tokens consumed during your direct Claude Code sessions (CLI or IDE). These are your interactive coding sessions where you chat with Claude. Alucify reads the local session logs from `~/.claude/projects/` to track this usage. The two sources never overlap — Alucify's SDK calls use `persistSession: false` and don't appear in Claude Code logs.
+
+## Models
+
+Different models have different token costs:
+- **Opus** — Most capable, highest per-token cost
+- **Sonnet** — Balanced capability and cost (Alucify's default for most agents)
+- **Haiku** — Fastest and cheapest (used by Alucify for template-driven extraction)
+
+The "By Model" breakdown helps you understand which models are consuming the most tokens.
+
+## Daily Average Comparison
+
+The "This Week" and "Today" banner cards show a percentage comparing your current usage to your daily average. This helps you quickly spot whether today is a heavy or light usage day:
+
+- **Orange (up arrow)** — Above your daily average by more than 10%
+- **Green (down arrow)** — Below your daily average by more than 10%
+- **"avg"** — Within 10% of your daily average
+
+## Per-User Tracking
+
+Every usage record is tagged with the git user email (`git config user.email`) of whoever triggered it. This enables per-user breakdowns in team environments. The token usage JSONL file is shared across the team (if committed), while the session reader state is per-user and gitignored.
+
+## Data Storage
+
+Token usage data is stored in `.alucify/token-usage/usage.jsonl` as an append-only log. Each line is a JSON record with all token counts, metadata, and timestamps. This file can be committed to version control for team visibility or gitignored for privacy — your choice.
+
+Per-user reader state files (`.alucify/token-usage/state.*.json`) track which Claude Code sessions have been ingested. These are automatically gitignored.

package/dist/docs/help/extension/token-usage/viewing-token-usage.md

@@ -0,0 +1,63 @@
+---
+order: 1
+title: "Viewing Token Usage"
+description: "How to open the Token Usage panel and monitor your AI token consumption."
+---
+
+# Viewing Token Usage
+
+Alucify tracks all AI token consumption across your project — both from Alucify workflows (code analysis, spec analysis, progress tracking) and from your direct Claude Code sessions.
+
+## Token Strip
+
+At the top of the Project Analysis panel, a compact strip shows your total and today's token usage. Click anywhere on the strip to open the full Token Usage panel.
+
+## Opening the Panel
+
+- Click the **token strip** at the top of the Project Analysis panel
+- Or open the Command Palette and search for **Alucify: View Token Usage**
+
+## Banner Metrics
+
+Four cards at the top of the panel provide a quick summary:
+
+- **Total Tokens** — All-time token consumption across all sources
+- **This Week** — Tokens used in the last 7 days, with a percentage showing how it compares to your daily average
+- **Today** — Tokens used today, with a comparison to your daily average
+- **Sessions** — Total number of Claude Code sessions and Alucify workflow runs
+
+## Tabs
+
+The panel has three tabs:
+
+### Overview
+
+A daily usage bar chart showing the last 30 days of token consumption, stacked by source (Alucify in cyan, Claude Code in orange). Below the chart, a daily breakdown table lists each active day with totals.
+
+### Breakdowns
+
+Six breakdown cards showing how tokens are distributed across different dimensions. Use the time period buttons (All Time, This Month, This Week, Today) to filter.
+
+Cards include:
+- **By Token Type** — Input, output, cache read, and cache creation tokens
+- **By Source** — Alucify workflows vs direct Claude Code sessions
+- **By Model** — Opus, Sonnet, Haiku
+- **By User** — Per-user attribution (useful for teams)
+- **By Branch** — Claude Code sessions grouped by git branch
+- **By Workflow** — Alucify workflow types (baseline, artifact integration, etc.)
+- **By Auth Mode** — SDK Runner vs API Runner (Alucify only)
+
+### Activity
+
+A sortable, filterable table of individual usage records. Each row shows the date, source, user, detail (workflow/phase or session ID), model, token counts, and duration. Use the dropdown filters to narrow by source, model, or user. Click any column header to sort.
+
+## CLI
+
+Run `alucify usage` in your terminal to see a summary of token usage. Add `--json` for machine-readable output.
+
+## Automatic Updates
+
+Token usage data updates automatically:
+- **Alucify workflows** — recorded in real time as agents run
+- **Claude Code sessions** — ingested from local session logs on extension activation and every 60 seconds while the extension is active
+- **Git commits** — session data is refreshed on each commit (via the post-commit hook installed by `alucify enable`)

package/dist/docs/help/faq.md

@@ -0,0 +1,128 @@
+---
+order: 99
+title: "Frequently Asked Questions"
+description: "Answers to common questions about Alucify, its features, pricing, and usage."
+---
+
+# Frequently Asked Questions
+
+## General
+
+### What is Alucify?
+Alucify ensures your project is ready for AI coding by creating a unified, structured context and identifying potential gaps and issues to save you time and tokens. It analyzes your code and specifications, identifies risks, and gives AI coding agents like Claude Code the context they need to produce better implementations.
+
+### Is Alucify free?
+Alucify accounts are free. Analysis costs depend on the mode you choose:
+- **Speed mode** is completely free — it uses mechanical analysis with no AI calls
+- **Balanced** and **Quality** modes require Claude access (either a subscription or API key) and cost varies by project size
+
+### What languages and frameworks does Alucify support?
+Alucify supports TypeScript, JavaScript, Python, Java, Go, Rust, Ruby, C/C++, C#, Swift, Kotlin, and more. It works with popular frameworks including React, Next.js, Django, Rails, Spring Boot, and many others. See [Supported Project Types](getting-started/supported-project-types.md).
+
+### Does Alucify send my code to the cloud?
+Alucify uses Claude (Anthropic's AI) for analysis, which requires sending code context to the Anthropic API. However, all analysis results are stored locally in the `.alucify/` directory in your project. Speed mode runs entirely locally with no cloud calls.
+
+## Extension
+
+### Where do I find Alucify in VS Code?
+After installing the extension, the Alucify icon appears in the activity bar (left sidebar). Click it to open the Alucify panel.
+
+### I dismissed the welcome screen. How do I get it back?
+In [Advanced Mode](vscode/settings/advanced-mode.md), open the Command Palette and run **Alucify (Advanced): Reset Welcome Screen**.
+
+### How long does analysis take?
+It depends on the analysis mode and your project size:
+- **Speed** — 5–10 minutes
+- **Balanced** — 15–60 minutes
+- **Quality** — 45–90 minutes
+
+You can continue working in VS Code while analysis runs in the background.
+
+### Can I cancel a running analysis?
+Yes. While an analysis is running, you can pause it using the pause button in the workflow status area, or clear it entirely.
+
+### What file types can I import as specs?
+PDFs, Markdown, plain text, images (PNG, JPG, SVG, etc.), JSON, YAML, TOML, XML, CSV, and code files. See [Supported Project Types](getting-started/supported-project-types.md) for the full list.
+
+### What does the AI Readiness score mean?
+AI Readiness is a composite score (0–100%) that summarizes how prepared your project is for AI coding. It factors in congruency (spec-code alignment), coverage (spec completeness), and other quality metrics. Higher scores mean AI agents are more likely to produce correct, aligned implementations.
+
+### How do I update my API key?
+Open the Command Palette and search for **Alucify: Set Anthropic API Key**. Enter your new key — it replaces the previous one securely.
+
+## CLI
+
+### How do I install the CLI?
+Run `npm install -g alucify` for a global install, or use `npx alucify <command>` without installing. Requires Node.js 18+.
+
+### Can I use the CLI without the VS Code extension?
+Yes. The CLI is fully standalone and works independently of the extension. You can run all analysis, tracking, and integration commands from the terminal.
+
+### What's the difference between `enable` and `mcp-install`?
+`alucify enable` installs the full integration (MCP server, hooks, CLAUDE.md rules, git hook). `alucify mcp-install` installs only the MCP server for lightweight, read-only access. Use `enable` for the full experience; use `mcp-install` when you just want Claude Code to query existing analysis.
+
+### How do I use the CLI in CI/CD?
+Run analysis commands with explicit auth:
+```bash
+alucify analyze-code --mode catalog  # Free, no auth needed
+alucify analyze-specs --auth apiKey --api-key $ANTHROPIC_API_KEY
+```
+
+## MCP Server
+
+### What is the MCP server?
+The MCP (Model Context Protocol) server gives Claude Code direct access to your project analysis. When enabled, Claude Code can search your project model, check impact of changes, find coverage gaps, and more — all without you having to manually provide context.
+
+### How do I set up the MCP server?
+The easiest way is `alucify enable`, which configures everything. See [Setting Up the MCP Server](mcp-server/setup.md) for all options.
+
+### Does the MCP server modify my analysis data?
+No. The MCP server is completely read-only. It queries your `.alucify/` data but never writes to it.
+
+### Can my whole team use the MCP server?
+Yes. If you commit the `.alucify/` directory (or at least `.alucify/mcp-server.js`) to your repository, team members can run `alucify enable` or `alucify mcp-install` to get MCP access without re-running analysis.
+
+## Web UI & Desktop App
+
+### How do I open the web UI?
+Run `alucify ui` from the CLI — it starts a local server and opens your browser. See [Launching the Web UI](cli/ui/launching.md).
+
+### Is the web UI the same as the desktop app?
+The desktop app embeds the web UI. The functional content is identical; the desktop app adds native features: OS-level workspace picker, native menu bar, OS notifications, and single-instance app behavior. See [Desktop App](desktop/quickstart.md).
+
+### Can I open the web UI from another machine?
+No. The web server binds to `127.0.0.1` only. Use an SSH tunnel if you need remote access, or use the Desktop app locally.
+
+### Do I need the CLI to run the desktop app?
+No. The desktop app is a standalone installer (`.dmg`, `.exe`, `.AppImage`). It bundles everything it needs.
+
+### Can I run the desktop app and the CLI web UI at the same time?
+Yes. The desktop app binds its own port, and CLI `alucify ui` finds its own free port. You can run both side-by-side on different projects.
+
+## Token Usage & Costs
+
+### How do I see how many tokens I've used?
+In the VS Code extension, look at the token strip at the top of the Project Analysis panel. Click it to open the full Token Usage panel with charts and breakdowns. From the CLI, run `alucify usage`.
+
+### Does it track my Claude Code sessions?
+Yes. Alucify reads Claude Code's local session logs (stored at `~/.claude/projects/`) to track token usage from your interactive coding sessions. This data stays on your machine.
+
+### Where is token usage data stored?
+In `.alucify/token-usage/usage.jsonl` as an append-only log. You can commit this file for team visibility or gitignore it for privacy. Per-user reader state files (`.alucify/token-usage/state.*.json`) are automatically gitignored.
+
+### How far back does token history go?
+On first activation, Alucify ingests all existing Claude Code session logs for the project. Alucify workflow usage is recorded from the first workflow run after the feature was enabled. If the JSONL file is deleted, Claude Code session history is automatically re-ingested on the next activation.
+
+### Can multiple team members track their usage?
+Yes. Every usage record includes the git user email. The shared `.alucify/token-usage/usage.jsonl` file contains records from all users, and the Token Usage panel can filter and break down by user.
+
+## Data & Privacy
+
+### Where is my analysis data stored?
+All analysis data is stored locally in the `.alucify/` directory within your project. It's never uploaded to Alucify's servers.
+
+### Can I opt out of telemetry?
+Yes. Go to VS Code Settings, search for `alucify.telemetry`, and uncheck it. See [Telemetry & Privacy](vscode/settings/telemetry.md).
+
+### Is my API key stored securely?
+Yes. API keys are stored in VS Code's built-in secret storage, which encrypts credentials at rest. Keys are never written to disk in plain text or included in project files.

package/dist/docs/help/getting-started/_meta.json

@@ -0,0 +1 @@
+{ "title": "Getting Started", "order": 1 }

package/dist/docs/help/getting-started/choosing-a-ui.md

@@ -0,0 +1,60 @@
+---
+order: 4
+title: "Choosing a UI"
+description: "Decision guide for picking the Alucify UI that fits your workflow."
+---
+
+# Choosing a UI
+
+Alucify ships four equal UIs. Most people use one or two. Here's how to pick.
+
+## Quick Decision
+
+| If you... | Use |
+|---|---|
+| ...live in VS Code | **VS Code Extension** |
+| ...run commands in a terminal or CI | **CLI** |
+| ...want a browser dashboard | **Web UI** (launched via `alucify ui`) |
+| ...want a native app without installing VS Code | **Desktop App** |
+
+You can use any combination. Many teams use VS Code Extension day-to-day + CLI in CI.
+
+## Detailed Comparison
+
+### VS Code Extension
+- **Best for:** developers who already work in VS Code
+- **Install:** one extension from the marketplace
+- **Pros:** tightly integrated (status bar, tree views, command palette, in-editor jumps); works inline with Claude Code
+- **Cons:** requires VS Code
+
+### CLI
+- **Best for:** scripting, CI/CD, pre-commit hooks, headless environments
+- **Install:** `npm install -g @alucify/cli`
+- **Pros:** scriptable, `--json` output for all reports, zero-GUI
+- **Cons:** not a visual dashboard (though `alucify ui` starts the Web UI for you)
+
+### Web UI
+- **Best for:** browser-based review, sharing across the team (via shared `.alucify/`), or when you want a dashboard but don't need a native app
+- **Install:** comes with the CLI; launch via `alucify ui`
+- **Pros:** rich dashboards, chat panel, artifact drag-drop, browser-native UX
+- **Cons:** requires CLI installed (can't run standalone)
+
+### Desktop App
+- **Best for:** a standalone native app without installing VS Code or managing a CLI
+- **Install:** download and install a .dmg / .exe / .AppImage
+- **Pros:** native look-and-feel, workspace picker, OS notifications, one-click install
+- **Cons:** separate install from VS Code; no `--json` scripting
+
+## Combining UIs
+
+- **VS Code + CLI** — common for developer workstations. Use VS Code interactively; CLI in pre-commit hooks.
+- **Desktop + CLI** — for non-VS-Code users who still want scripting. Use Desktop interactively; CLI for CI.
+- **Web UI (via CLI) + MCP in Claude Code** — no IDE dependency; browser + Claude Code agent in a terminal.
+
+## Feature Parity
+
+Most features exist everywhere. For a complete matrix of what's where, see [UI Parity Matrix](../reference/ui-parity-matrix.md).
+
+## Data Is Portable
+
+All four UIs read from the same `.alucify/` directory in your project. You can switch UIs (or mix them) without losing analysis data.

package/dist/docs/help/getting-started/first-analysis.md

@@ -0,0 +1,86 @@
+---
+order: 6
+title: "Your First Analysis"
+description: "End-to-end walkthrough: analyze code, add specs, review risks."
+---
+
+# Your First Analysis
+
+A 15-minute walkthrough of Alucify's five-step workflow, using whichever UI you prefer.
+
+For the concept, see [Workflow Overview](../concepts/workflow-overview.md).
+
+## Before You Start
+
+- Alucify installed (see [Installation](installation.md))
+- Authentication set up (see [Authentication Modes](../concepts/authentication-modes.md))
+- A project folder with some code in it (even a small demo works)
+
+## Step 1 — Analyze Code
+
+Run baseline code analysis. This scans your codebase and builds an [AppGraph](../concepts/appgraph.md) of your project's structure.
+
+| UI | How |
+|---|---|
+| CLI | `alucify analyze-code --mode catalog` |
+| VS Code | Click **Analyze Code** in the Alucify sidebar → pick mode |
+| Web / Desktop | Dashboard → **Analyze Code** → pick mode |
+
+Start with **Speed (catalog) mode** on your first run — it's free and takes ~5 minutes. You can re-analyze in a deeper mode later.
+
+Result: you'll see your project's structure (interfaces, logic, schemas) plus a tech stack summary.
+
+## Step 2 — Add Specs
+
+Import at least one spec — a PRD, architecture doc, feature epic, or even a README. Any [supported format](../reference/file-types-and-formats.md#input-spec-artifacts).
+
+| UI | How |
+|---|---|
+| CLI | `alucify add-spec docs/my-prd.md` |
+| VS Code | Specs sidebar → **Add Spec** |
+| Web / Desktop | Artifacts sidebar → drag-drop or **Add** |
+
+## Step 3 — Analyze Specs
+
+Now analyze the specs against your code.
+
+| UI | How |
+|---|---|
+| CLI | `alucify analyze-specs --mode catalog` |
+| VS Code | Specs sidebar → **Analyze** |
+| Web / Desktop | Dashboard → **Analyze Specs** |
+
+Result: scores for [congruency, coverage, completeness](../concepts/congruency-coverage-completeness.md), plus [AI Coding Risks](../concepts/ai-coding-risks.md) and recommendations.
+
+## Step 4 — Review Risks
+
+Open the AI Coding Risks panel to see what Alucify found.
+
+| UI | How |
+|---|---|
+| CLI | `alucify status --json | jq '.risks'` |
+| VS Code | **Alucify: View AI Coding Risks** |
+| Web / Desktop | AI Coding Risks tab |
+
+For each risk, you can:
+- Open it to see suggested solutions
+- Resolve via chat (refine the relevant spec with Claude)
+- Mark as ignored if it's not relevant
+
+## Step 5 — Plan & Track
+
+With risks reviewed, plan your next work and track progress as commits land.
+
+| UI | How |
+|---|---|
+| CLI | `alucify plan` (launches Claude Code) |
+| VS Code | **Alucify: Plan** / Dev Progress tab |
+| Web / Desktop | Requirements Progress tab → **Plan** |
+
+If you run [`alucify enable`](../cli/commands/enable-disable.md), git hooks automatically track progress on each commit.
+
+## What's Next
+
+- **Switch to Balanced or Quality mode** for deeper analysis: see [Analysis Modes](../concepts/analysis-modes.md)
+- **Enable Claude Code integration**: `alucify enable` wires up MCP + hooks + `/alucify-plan`
+- **Invite your team**: commit `.alucify/` to share analysis history