@alucify/cli 0.6.5 → 0.7.1

package/dist/docs/help/extension/code-analysis/understanding-tech-debt-analysis.md

@@ -0,0 +1,90 @@
+---
+order: 4
+title: "Understanding Technical Debt Analysis"
+description: "How to read and use the Technical Debt Analysis panel, including the Architecture Health Score."
+---
+
+# Understanding Technical Debt Analysis
+
+The Technical Debt Analysis panel provides a detailed assessment of your codebase's structural health, helping you identify areas of architectural risk before they cause problems for AI coding agents.
+
+## Opening the Panel
+
+- From the Code Analysis tab, click **View Details** next to the Architecture Health section
+- Or open the Command Palette and search for **Alucify: View Technical Debt Analysis**
+
+## Health Score
+
+At the top of the panel, a large score (0–100) with a letter grade summarizes your architecture's overall health:
+
+- **70–100 (Green)** — Healthy architecture with low structural risk
+- **40–69 (Yellow)** — Moderate issues that should be addressed
+- **Below 40 (Red)** — Significant structural problems that need attention
+
+## Banner Metrics
+
+Four cards below the health score provide key insights:
+
+### Change Scope
+The average percentage of your project affected when a single change propagates through dependencies. **Lower is better** — it means changes stay contained rather than rippling across the system.
+
+### Structural Risk
+How fragile your architecture is to cascading failures:
+- **Low** — Less than 20% of components are at risk
+- **Moderate** — 20–40% of components are at risk
+- **High** — More than 40% of components are at risk
+
+### Debt Trend
+Whether structural debt is growing or shrinking over time:
+- **Stable** — Debt isn't compounding
+- **X cycles (Doubling Time)** — Debt is growing; the number indicates how quickly
+- **X cycles (Halving Time)** — Debt is shrinking; the architecture is improving
+
+## Detail Tabs
+
+The panel has six tabs for deeper analysis:
+
+### Remediation
+Priority actions to reduce technical debt, ordered by impact. Each action shows:
+- What percentage of total debt it addresses
+- A description of the issue
+- The expected outcome if addressed
+
+A **Root Cause** alert may appear highlighting high-dependency components that are the source of multiple issues.
+
+### Change Scope
+Visualizes how far changes propagate through your codebase. Shows:
+- The average scope percentage
+- How many components a typical change touches
+- A breakdown by change type, each rated Low / Moderate / High effort
+
+### Structural Risk
+A snapshot of architectural complexity today:
+- **Fragility Index** — A 0–100 score measuring coupling, dependency cycles, and structural bottlenecks
+- **Health Score Breakdown** — Individual scores for each health dimension with letter grades and weights
+- **Stress Attribution** — Which specific structural patterns (like circular dependencies, single points of failure, or cross-feature coupling) contribute most to risk
+
+### Debt Trend
+A forward-looking simulation that projects how your architecture responds to sustained change pressure:
+- Shows whether debt compounds or gets absorbed over time
+- Includes a trajectory graph showing stress levels across simulation cycles
+- Lists the most affected components and their stress changes
+- A health callout indicates whether your architecture shows compounding risk or is structurally sound
+
+### Complexity
+Identifies the most complex areas of your codebase:
+- Lists complexity hotspots by location
+- Shows maximum cognitive complexity per component
+- Flags functions that are candidates for refactoring
+
+Complexity scale:
+- **0–5:** Trivial
+- **6–15:** Moderate
+- **16–30:** High (flagged as hotspot)
+- **31+:** Very high (strong refactoring signal)
+
+### Outdated Packages
+Shows which dependencies are out of date:
+- Lists packages with current and latest versions
+- Highlights risk levels for outdated dependencies
+- Requires internet access during analysis to detect outdated packages

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

@@ -0,0 +1,49 @@
+---
+order: 2
+title: "Understanding the Code Analysis Tab"
+description: "A walkthrough of the Code Analysis tab — metrics, codebase summary, and what each section means."
+---
+
+# Understanding the Code Analysis Tab
+
+The Code Analysis tab is the first of three tabs in the Project Analysis panel. It shows the results of your codebase scan.
+
+## Codebase Section
+
+This section provides a high-level summary of your project:
+
+- **Lines of Code** — Total lines across your project (displayed as "1.2M", "301k", "45k", etc.)
+- **Tech Stack** — Detected frameworks and languages shown as tag pills (e.g., "React", "Express", "PostgreSQL")
+- **Analysis Date** — When the codebase was last analyzed (hover the info icon for the exact date)
+
+## Analysis Mode
+
+Shows which analysis mode was used, displayed as:
+- **Speed** (catalog mode)
+- **Balanced** (fast mode)
+- **Quality** (full mode)
+
+## Architecture Health
+
+If a technical debt analysis has been run, this section shows:
+
+- **Health Score** — A 0–100 score with a letter grade (A–F) rating your architecture's structural health
+- **View Details** link — Opens the full [Technical Debt Analysis](understanding-tech-debt-analysis.md) panel
+
+## AI Coding Risks
+
+If risks have been identified, this section shows a summary:
+
+- **Risk count** — Total number of identified risks
+- **Severity breakdown** — Count by severity level (Critical, High, Medium, Low)
+- **View Details** link — Opens the full [AI Coding Risks](understanding-ai-coding-risks.md) panel
+
+## Action Buttons
+
+- **Analyze Code** — Appears when no baseline exists, or when code has changed since the last analysis. Click to run or re-run code analysis.
+
+## Understanding Scores
+
+When you first see your scores, a dismissible card explains: "These scores show how ready your specs are for AI coding. Higher is better. Hover any score for details and check out the recommendations for next steps."
+
+Click **Got it** to dismiss this card permanently.

package/dist/docs/help/extension/dev-progress/_meta.json

@@ -0,0 +1 @@
+{ "title": "Dev Progress", "order": 6 }

package/dist/docs/help/extension/dev-progress/analyzing-commits.md

@@ -0,0 +1,56 @@
+---
+order: 1
+title: "Analyzing Implementation Progress"
+description: "How to analyze your git commits to track implementation progress against specs."
+---
+
+# Analyzing Implementation Progress
+
+Progress tracking analyzes your git commits to determine what's been implemented, what's in progress, and what's still outstanding — all measured against your specifications.
+
+## Prerequisites
+
+Before analyzing progress:
+
+1. You've run both [code analysis](../code-analysis/running-code-analysis.md) and [spec analysis](../spec-analysis/analyzing-specs.md)
+2. You have git commits to analyze
+
+## How to Analyze Progress
+
+1. In the **Project Analysis** panel, switch to the **Dev Progress** tab
+2. Click the **Analyze Progress** button
+3. Alucify analyzes your commits since the last checkpoint
+
+The analysis classifies each commit's changes against your specifications, updating the implementation status of each requirement.
+
+## Automatic Progress Analysis
+
+After running **Analyze Specs**, progress analysis runs automatically if your project has requirements linked to code. You don't need to trigger it manually the first time — it happens as part of the spec analysis workflow.
+
+## What Happens During Analysis
+
+Progress analysis:
+
+1. Reads your git history since the last analyzed checkpoint
+2. Maps file changes to project components using source file links and code references
+3. Reads the **full file content** for components being reassessed, so the classifier can judge whether the implementation is complete — not just what changed
+4. Classifies whether changes implement, partially implement, or test requirements
+5. Records **implementation gaps** for in-progress components — concrete notes describing exactly what's missing (e.g., "has GET handler but missing POST/DELETE branches")
+6. Updates implementation statuses (Planned → In Progress → Implemented)
+7. Saves a checkpoint so future analyses only process new commits
+8. Creates a versioned snapshot
+
+## Using the Command Palette
+
+You can also start progress analysis from the Command Palette:
+
+1. Press `Ctrl+Shift+P` / `Cmd+Shift+P`
+2. Search for **Alucify: Analyze Progress**
+
+## Tips
+
+- **Analyze regularly** — Run progress analysis after significant commits to keep your status up to date
+- **The first analysis covers all history** — The initial run analyzes all commits since your spec analysis. Subsequent runs only process new commits.
+- **Uncommitted changes are included** — Analysis looks at both committed and uncommitted changes
+- **In-progress components are always re-checked** — Components marked as in-progress are reassessed on every run until they reach implemented, even if their files haven't changed since the last checkpoint
+- **Link files for better accuracy** — Use `link_context` (via Claude Code) to connect components to their implementation files. This enables mechanical matching and ensures components are tracked accurately across runs.

package/dist/docs/help/extension/dev-progress/understanding-the-dev-progress-tab.md

@@ -0,0 +1,40 @@
+---
+order: 2
+title: "Understanding the Dev Progress Tab"
+description: "A walkthrough of the Dev Progress tab — progress metrics, requirement status, and commit analysis."
+---
+
+# Understanding the Dev Progress Tab
+
+The Dev Progress tab is the third of three tabs in the Project Analysis panel. It tracks your implementation progress against specifications.
+
+## Dev Progress Metric
+
+At the top, a percentage shows your overall development progress — the proportion of specified components that have been implemented or tested. A sparkline shows the trend across analysis versions.
+
+## Requirements Section
+
+Below the progress metric, a breakdown shows the status of each requirement:
+
+- How many requirements exist in total
+- How many are in each status: Planned, In Progress, Implemented
+- A visual indicator for each requirement showing its current state
+- Per-requirement implementation progress showing how many components are done
+
+Requirements that were newly added since the last analysis are marked with a **NEW** badge.
+
+For in-progress components, the tab shows **implementation gaps** — concrete notes describing what's still missing (e.g., "Missing scope check before mutation; missing audit_log() call on delete"). These gap notes are used by the `/alucify-plan` skill to generate targeted code changes.
+
+## Getting Started
+
+If you haven't analyzed any commits yet, the tab shows a guide explaining the feature and an **Analyze Progress** button to get started.
+
+## Claude Code Integration
+
+The Dev Progress tab includes a toggle to enable Alucify integration with Claude Code. When enabled, Claude Code gains access to your project analysis through the MCP server, allowing it to make more informed implementation decisions.
+
+See [Setting Up the MCP Server](../../mcp-server/setup.md) for details.
+
+## Empty State
+
+If you haven't run spec analysis yet, the tab shows: "Run code and spec analysis first to start tracking progress."

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

@@ -0,0 +1,34 @@
+---
+order: 2
+title: "Installing the Extension"
+description: "How to install the Alucify extension from the VS Code Marketplace."
+---
+
+# Installing the Extension
+
+## From the VS Code Marketplace
+
+1. Open VS Code
+2. Click the **Extensions** icon in the activity bar (or press `Ctrl+Shift+X` / `Cmd+Shift+X`)
+3. Search for **Alucify**
+4. Click **Install**
+
+After installation, the Alucify icon appears in your activity bar (left sidebar).
+
+## Requirements
+
+- VS Code version 1.85.0 or later
+- A project folder open in VS Code
+
+## First Launch
+
+When you click the Alucify icon for the first time, you'll see the welcome screen. This guides you through:
+
+1. Creating an Alucify account (free)
+2. Connecting to Claude (API key or Claude Code subscription)
+
+See [VS Code Extension Quick Start](quickstart.md) for the complete setup walkthrough.
+
+## Updating
+
+The extension updates automatically through VS Code's built-in extension update mechanism. You can also manually check for updates in the Extensions panel.

package/dist/docs/help/extension/intent-capture/_meta.json

@@ -0,0 +1 @@
+{ "title": "Intent Capture", "order": 7 }

package/dist/docs/help/extension/intent-capture/enabling-intent-capture.md

@@ -0,0 +1,40 @@
+---
+order: 1
+title: "Enabling Intent Capture"
+description: "How to turn on intent capture and surface requirements from your Claude Code sessions."
+---
+
+# Enabling Intent Capture
+
+Intent capture surfaces requirements, decisions, and design context from your Claude Code sessions and adds them to your AppGraph — so the thinking behind your code doesn't get lost when a session ends.
+
+## Prerequisites
+
+- You've run `alucify enable` (sets up the Claude Code integration)
+- You have an AppGraph (run **Analyze Code** or **Analyze Specs** first)
+
+## Turning It On
+
+1. Open VS Code Settings (`Cmd+,` / `Ctrl+,`)
+2. Search for **Alucify Intent Capture**
+3. Enable **Intent Capture: Enabled**
+
+Once enabled, Alucify periodically checks your recent Claude Code sessions and extracts anything relevant to your project.
+
+## Running It Manually
+
+You can trigger intent capture at any time from the Command Palette (`Cmd+Shift+P` / `Ctrl+Shift+P`):
+
+- **Alucify: Capture Intent** — Extract intent from your recent sessions. Results are staged for review before being added to the AppGraph.
+- **Alucify: Analyze Intent** — Capture intent and immediately integrate it into the AppGraph. Use this when you want to see results right away.
+
+## What Happens After Capture
+
+Extracted intent shows up in the AppGraph as new nodes or as annotations on existing nodes. You can explore them in the **AppGraph Visualizer** or see them reflected in your implementation status and coverage.
+
+## CLI
+
+```bash
+alucify capture-intent          # Extract from recent sessions
+alucify capture-intent --force  # Extract right now, don't wait
+```

package/dist/docs/help/extension/intent-capture/understanding-intent-capture.md

@@ -0,0 +1,40 @@
+---
+order: 2
+title: "Understanding Intent Capture"
+description: "What intent capture extracts from your Claude Code sessions and how it appears in your AppGraph."
+---
+
+# Understanding Intent Capture
+
+## What Gets Captured
+
+When you work in a Claude Code session, you naturally produce context that's valuable for your project: requirements you clarified with Claude, design decisions you made, edge cases you discussed, and features you decided to scope in or out.
+
+Intent capture reads your session history and looks for this kind of project-level context — things that would be useful to have in your AppGraph alongside your specs and code analysis.
+
+Examples of what gets captured:
+- A requirement you refined or added during a session ("we decided authentication should support SSO")
+- A design decision tied to specific code ("we're using optimistic updates for this component")
+- A scope clarification that affects your specs ("out of scope for v1: batch imports")
+
+Sessions that are only execution work — running commands, fixing syntax errors, iterating on output — are skipped.
+
+## How It Appears in the AppGraph
+
+Captured intent shows up in two ways:
+
+- **New nodes** — If intent introduces a new requirement or feature not already in the AppGraph, a new node is created with an `intent` origin, so you can tell where it came from.
+- **Annotations on existing nodes** — If intent relates to something already in the AppGraph, it's attached to that node as additional context.
+
+You can filter by origin in the AppGraph Visualizer to see only intent-captured nodes.
+
+## What It Doesn't Capture
+
+Intent capture is selective — it's designed to surface project-level decisions, not a transcript of everything you discussed. It won't add:
+- Code snippets or implementation details (those belong in the code itself)
+- Back-and-forth troubleshooting that didn't produce a decision
+- Context that's already reflected in your specs or AppGraph
+
+## Privacy
+
+Intent capture only reads local session files on your machine (`~/.claude/projects/`). Nothing is sent anywhere beyond the same Claude API calls your other Alucify workflows use. Captured intent is stored in `.alucify/extractions/intents/`, which you can commit or gitignore as you see fit.

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

@@ -0,0 +1,60 @@
+---
+order: 1
+title: "VS Code Extension Quick Start"
+description: "Get up and running with the Alucify VS Code extension in under 5 minutes."
+---
+
+# VS Code Extension Quick Start
+
+Get Alucify analyzing your project in just a few steps.
+
+## 1. Install the Extension
+
+Search for **Alucify** in the VS Code Extensions marketplace and click **Install**. See [Installing the Extension](installation.md) for details.
+
+## 2. Open a Project
+
+Open a project folder in VS Code. The Alucify icon will appear in your activity bar (left sidebar).
+
+## 3. Complete the Welcome Setup
+
+Click the Alucify icon to open the sidebar. The welcome screen walks you through two setup steps:
+
+1. **Sign in to Alucify** — Create a free account or sign in to your existing one. Click **Sign Up / Sign In** to get started.
+
+2. **Connect to Claude** — Choose how Alucify connects to Claude for AI analysis:
+   - **Claude Code Subscription** — Use your existing Claude Code or Claude Max subscription
+   - **Anthropic API Key** — Pay per token with your own API key
+
+## 4. Analyze Your Code
+
+Once setup is complete, you'll see the **Project Analysis** panel. Click the **Analyze Code** button to scan your codebase.
+
+Choose an analysis mode:
+- **Speed** — Fast mechanical analysis (5–10 minutes, no AI cost)
+- **Balanced** — AI-powered analysis (15–60 minutes)
+- **Quality** — Comprehensive analysis (45–90 minutes)
+
+Wait for the analysis to complete. You'll see a progress indicator and can continue working while it runs.
+
+## 5. Review Your Results
+
+When analysis finishes, the **Code Analysis** tab shows:
+- Your tech stack
+- Lines of code
+- Architecture health score
+- AI coding risks (if any)
+
+## 6. Add and Analyze Specs (Optional)
+
+To compare your code against your requirements:
+
+1. Click **Add Spec** in the **Specifications** panel to import your PRDs, design docs, or other spec files
+2. Click **Analyze Specs** to run the comparison
+3. Review the results in the **Spec Analysis** tab
+
+## What's Next?
+
+- [Understanding the Code Analysis Tab](code-analysis/understanding-the-code-analysis-tab.md)
+- [Adding Specification Documents](spec-analysis/adding-specs.md)
+- [Analyzing Implementation Progress](dev-progress/analyzing-commits.md)

package/dist/docs/help/extension/resetting-analysis.md

@@ -0,0 +1,46 @@
+---
+order: 9
+title: "Resetting Your Analysis"
+description: "How to reset your analysis data and start fresh, including what gets archived."
+---
+
+# Resetting Your Analysis
+
+If you need to start fresh, you can reset all analysis data. This archives your existing data and returns Alucify to its initial state.
+
+## How to Reset
+
+1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Search for **Alucify: Reset Analysis**
+3. Confirm the reset when prompted
+
+You'll see a warning: "Reset all analysis? This will archive your current baseline, spec analysis, progress tracking, and all version history. Your data will be preserved in .alucify/archived/ if you need to recover it."
+
+Click **Reset Analysis** to proceed, or cancel to keep your data.
+
+## What Gets Archived
+
+All of your analysis data is moved to `.alucify/archived/[timestamp]/`, including:
+
+- Code analysis baseline
+- Spec analysis results
+- Version history
+- Progress tracking data
+- Imported artifacts
+
+## What Happens After Reset
+
+- All panels refresh to show their empty state
+- The Code Analysis tab shows the **Analyze Code** button again
+- The Specifications panel is empty
+- You'll see a confirmation: "Analysis reset. All previous data archived to .alucify/archived/."
+
+## Recovering Archived Data
+
+Your archived data is preserved in `.alucify/archived/` with a timestamp. While there's no built-in restore feature, the files are standard JSON and can be manually copied back if needed.
+
+## When to Reset
+
+- You've significantly restructured your project and want a clean baseline
+- You want to re-analyze with different settings from scratch
+- You're switching the project that a workspace is used for

package/dist/docs/help/extension/settings/_meta.json

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

package/dist/docs/help/extension/settings/notification-preferences.md

@@ -0,0 +1,38 @@
+---
+order: 2
+title: "Notification Preferences"
+description: "How to configure OS notifications for completed workflows."
+---
+
+# Notification Preferences
+
+Alucify can send native OS notifications when a workflow completes and VS Code is not in focus. This is useful when running long analyses in the background.
+
+## Configuring Notifications
+
+To enable or disable OS notifications:
+
+1. Open VS Code Settings (`Ctrl+,` / `Cmd+,`)
+2. Search for `alucify.notifications.os`
+3. Check or uncheck **Alucify: Notifications > OS**
+
+Or add this to your `settings.json`:
+
+```json
+{
+  "alucify.notifications.os": true
+}
+```
+
+## When Notifications Are Sent
+
+OS notifications are sent when:
+
+- A workflow (code analysis, spec analysis, or progress analysis) completes
+- VS Code is not the focused window
+
+If VS Code is in focus, you'll see the results directly in the sidebar without a separate notification.
+
+## Default Setting
+
+OS notifications are **enabled** by default.

package/dist/docs/help/extension/settings/telemetry.md

@@ -0,0 +1,45 @@
+---
+order: 1
+title: "Telemetry & Privacy"
+description: "What anonymous usage data Alucify collects and how to opt out."
+---
+
+# Telemetry & Privacy
+
+Alucify collects anonymous usage telemetry to help improve the product. You can opt out at any time.
+
+## What's Collected
+
+Alucify tracks anonymous usage events such as:
+
+- Which commands are used (e.g., "Analyze Code was run")
+- Workflow state changes (e.g., "analysis started", "analysis completed")
+- General usage metrics
+
+Telemetry does **not** include:
+
+- Your source code
+- Your specification documents
+- File names or paths
+- API keys or credentials
+- Any personally identifiable information beyond your account ID
+
+## Opting Out
+
+To disable telemetry:
+
+1. Open VS Code Settings (`Ctrl+,` / `Cmd+,`)
+2. Search for `alucify.telemetry`
+3. Uncheck **Alucify: Telemetry**
+
+Or add this to your `settings.json`:
+
+```json
+{
+  "alucify.telemetry": false
+}
+```
+
+## Data Storage
+
+All analysis data (your project model, spec analysis, versions) is stored locally in the `.alucify/` directory within your project. This data is never sent to Alucify's servers — it stays on your machine and in your repository.

package/dist/docs/help/extension/spec-analysis/_meta.json

@@ -0,0 +1 @@
+{ "title": "Spec Analysis", "order": 5 }

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

@@ -0,0 +1,40 @@
+---
+order: 1
+title: "Adding Specification Documents"
+description: "How to import PRDs, requirements docs, design files, and other specs into Alucify."
+---
+
+# Adding Specification Documents
+
+Specs are the documents that describe what your project should do — PRDs, requirements documents, design files, API specifications, and any other project documentation.
+
+## How to Add Specs
+
+1. In the Alucify sidebar, find the **Specifications** panel
+2. Click the **Add Spec** button (plus icon)
+3. A file picker opens — select one or more files
+4. The files are imported into your project's `.alucify/artifacts/` directory
+
+You can select multiple files at once to import them in batch.
+
+## Supported File Types
+
+Alucify supports a wide range of file formats:
+
+- **Documents:** PDF, Markdown (.md), plain text (.txt), ReStructuredText (.rst), AsciiDoc (.adoc)
+- **Data formats:** JSON, YAML, TOML, XML, CSV
+- **Images:** PNG, JPG, GIF, SVG, WebP
+- **Code files:** TypeScript, JavaScript, Python, Java, Go, Rust, Ruby, C/C++, C#, Swift, Kotlin
+
+## What Happens After Import
+
+After importing, your specs appear in the Specifications panel with a **Pending** status. They need to be analyzed before Alucify can compare them against your codebase.
+
+To analyze your specs, click **Analyze Specs** in the Project Analysis panel. See [Running Spec Analysis](analyzing-specs.md) for details.
+
+## Tips
+
+- **Import everything relevant** — PRDs, design docs, API contracts, wireframes, data models. The more context Alucify has, the better its analysis.
+- **Images work too** — Screenshots of wireframes and design mockups can be imported and analyzed.
+- **Large files are handled automatically** — Alucify chunks large documents for efficient processing.
+- **You can add more specs later** — Import additional specs at any time. When you run Analyze Specs again, Alucify will process only the new or changed files.

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

@@ -0,0 +1,60 @@
+---
+order: 4
+title: "Running Spec Analysis"
+description: "How to run spec analysis to compare your specifications against your codebase."
+---
+
+# Running Spec Analysis
+
+Spec analysis compares your imported specifications against your codebase to find gaps, conflicts, and coverage issues.
+
+## Prerequisites
+
+Before running spec analysis:
+
+1. You've [run code analysis](../code-analysis/running-code-analysis.md) at least once
+2. You've [added specs](adding-specs.md) to the Specifications panel
+
+## How to Run Spec Analysis
+
+1. In the **Project Analysis** panel, switch to the **Spec Analysis** tab
+2. Click the **Analyze Specs** button
+3. Select an analysis mode:
+   - **Speed** — Fast mechanical projection (5–10 minutes, no AI cost)
+   - **Balanced** — AI-powered analysis (15–60 minutes)
+   - **Quality** — Comprehensive analysis (45–90 minutes)
+4. Wait for the analysis to complete
+
+A progress indicator shows the current phase.
+
+## What Happens During Analysis
+
+Spec analysis:
+
+1. Extracts requirements, features, and acceptance criteria from your spec documents
+2. Maps spec items to existing components in your codebase
+3. Identifies coverage gaps — requirements with no matching code
+4. Detects conflicts — contradictions between specs and code
+5. Measures congruency — how well specs and code align
+6. Generates AI coding risks based on the findings
+7. Saves a versioned snapshot
+
+## Incremental Analysis
+
+When you add new specs or update existing ones and re-run analysis:
+
+- **Unchanged specs are reused** — Only new or modified specs are re-analyzed
+- **You can choose to rebuild** — If you prefer a fresh analysis, you'll see the option to do a full rebuild
+
+This saves time and cost when iterating on your specs.
+
+## After Analysis
+
+Results appear in the [Spec Analysis tab](understanding-the-spec-analysis-tab.md). You'll see congruency scores, coverage metrics, and any identified risks.
+
+## Using the Command Palette
+
+You can also start spec analysis from the Command Palette:
+
+1. Press `Ctrl+Shift+P` / `Cmd+Shift+P`
+2. Search for **Alucify: Analyze Specs**