@alucify/cli 0.6.5 → 0.7.0

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

@@ -0,0 +1 @@
+{ "title": "Advanced", "order": 10 }

package/dist/docs/help/vscode/advanced/congruency-analysis.md

@@ -0,0 +1,32 @@
+---
+order: 1
+title: "Congruency Analysis"
+description: "Running congruency analysis as a standalone pass."
+---
+
+# Congruency Analysis
+
+Congruency analysis checks how well your specs and code agree. It's normally run automatically as part of [spec analysis](../spec-analysis/analyzing-specs.md), but Advanced Mode exposes it as a standalone command.
+
+For the concept, see [Congruency, Coverage & Completeness](../../concepts/congruency-coverage-completeness.md).
+
+## When to Run It Alone
+
+- You've only updated specs (not code) and want a fast congruency refresh without re-running the whole spec analysis pipeline
+- You want to try a different analysis mode just for congruency
+- You're debugging unexpected congruency scores
+
+## How to Run
+
+- **Command Palette** — **Alucify (Advanced): Analyze Congruency** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+Pick an [analysis mode](../../concepts/analysis-modes.md) and the target specs when prompted.
+
+## Output
+
+A congruency-only report written to the current version. Scores are updated in the [Specifications Panel](../spec-analysis/specifications-panel.md) when done.
+
+## Caveats
+
+- Congruency depends on coverage data — if coverage hasn't been computed, results will be incomplete
+- For the full view (congruency + coverage + completeness + risks + recommendations), run [Analyze Specs](../spec-analysis/analyzing-specs.md) instead

package/dist/docs/help/vscode/advanced/coverage-analysis.md

@@ -0,0 +1,31 @@
+---
+order: 2
+title: "Coverage Analysis"
+description: "Running coverage analysis as a standalone pass."
+---
+
+# Coverage Analysis
+
+Coverage analysis identifies which parts of your codebase have no corresponding specification. Advanced Mode exposes it as a standalone command.
+
+For the concept, see [Congruency, Coverage & Completeness](../../concepts/congruency-coverage-completeness.md).
+
+## When to Run It Alone
+
+- You've added new code and want a fast coverage refresh without full spec analysis
+- You're triaging "missing spec" risks and want the latest coverage data
+
+## How to Run
+
+- **Command Palette** — **Alucify (Advanced): Analyze Coverage** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+Pick an [analysis mode](../../concepts/analysis-modes.md).
+
+## Output
+
+A coverage-only report. Coverage bars in the [Specifications Panel](../spec-analysis/specifications-panel.md) update when done.
+
+## Related
+
+- [AI Coding Risks](../../concepts/ai-coding-risks.md) — low coverage produces Missing UX / Data / Logic Spec risks
+- [`get_remaining_work`](../../mcp-server/tools/coverage-gaps.md) — query coverage gaps from Claude Code

package/dist/docs/help/vscode/advanced/developer-mode.md

@@ -0,0 +1,34 @@
+---
+order: 6
+title: "Developer Mode"
+description: "Internal diagnostics for debugging the Alucify extension."
+---
+
+# Developer Mode
+
+Developer Mode enables diagnostics used by the Alucify team (or contributors) when debugging the extension itself. You probably don't need this.
+
+## What It Enables
+
+- **Output Channel** — `Alucify` in VS Code's Output panel, with verbose logging
+- **Extra panels** — internal state inspectors for workflow engine, agent runner, and MCP client
+- **Override flags** — `alucify.agentsInternalPath` starts being respected (normally ignored)
+
+## Turning It On
+
+Developer Mode isn't a single setting — it's enabled when you set `alucify.agentsInternalPath` to a non-empty value (typically a path to the `alucify-agents-internal` repo for internal development).
+
+For external users this is almost never what you want. If you're debugging behavior, start with:
+- [Output Channel](../../reference/alucify-directory.md#debug-logs) — inspect logs without Developer Mode
+- [Reset Extension](reset-extension.md) — clear state
+- File an issue with reproduction steps
+
+## Agent Path Override
+
+`alucify.agentsInternalPath` lets internal developers point at a local copy of the agent definitions repo. Setting this to an empty string (default) uses the agents bundled with the extension.
+
+Invalid paths fall back to bundled agents with a warning in the Output Channel.
+
+## Reverting
+
+Clear the setting (set to empty string). The extension goes back to normal user mode.

package/dist/docs/help/vscode/advanced/findings-synthesis.md

@@ -0,0 +1,27 @@
+---
+order: 4
+title: "Findings Synthesis"
+description: "Running quality insight synthesis as a standalone pass."
+---
+
+# Findings Synthesis
+
+Findings Synthesis aggregates results from congruency, coverage, and impact analyses into a ranked list of actionable insights. It's the step that produces the Recommendations section in the Spec Analysis tab and the AI Coding Risks output.
+
+## When to Run It Alone
+
+- You've manually run congruency, coverage, or impact analyses separately and want to re-synthesize without a full spec analysis run
+- You want to regenerate the Recommendations list after updating mitigations
+
+## How to Run
+
+- **Command Palette** — **Alucify (Advanced): Analyze Findings** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+## Output
+
+- Updated recommendations in the Spec Analysis tab
+- Refreshed AI Coding Risks (severities may shift based on new data)
+
+## Prerequisites
+
+This analysis reads results from prior congruency, coverage, and impact runs. If any of those are stale or missing, re-run them first.

package/dist/docs/help/vscode/advanced/impact-analysis.md

@@ -0,0 +1,31 @@
+---
+order: 3
+title: "Impact Analysis"
+description: "Running blast-radius analysis as a standalone pass."
+---
+
+# Impact Analysis
+
+Impact analysis computes blast radius — how much of your project is affected by changes in a given area.
+
+For the concept, see [Blast Radius](../../concepts/blast-radius.md).
+
+## When to Run It Alone
+
+- You want to re-score blast radius after structural changes to the codebase
+- You're investigating a specific area and want the latest propagation data
+
+## How to Run
+
+- **Command Palette** — **Alucify (Advanced): Analyze Impact** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+## Output
+
+Updated blast-radius metrics per node. Shown in:
+- Spec Analysis tab (project-level average)
+- AppGraph Visualizer node details
+- AI Coding Risks panel (High Blast Radius risks are re-scored)
+
+## Related
+
+- [`trace_dependencies`](../../mcp-server/tools/impact-analysis.md) — query impact from Claude Code

package/dist/docs/help/vscode/advanced/reset-extension.md

@@ -0,0 +1,39 @@
+---
+order: 5
+title: "Reset Extension"
+description: "Factory reset for the VS Code extension — clears auth and local state."
+---
+
+# Reset Extension
+
+A full factory reset for the Alucify VS Code extension. Use this sparingly — it clears authentication and extension state, but does **not** delete your project's analysis data.
+
+## What Reset Extension Does
+
+- Clears the API key from VS Code secret storage
+- Clears any Auth0 session tokens
+- Resets extension-level state (welcome flags, auth-mode-chosen, panel states)
+- Does **not** touch `.alucify/` in any project — analyses, specs, versions, and token logs are preserved
+
+## How to Run
+
+- **Command Palette** — **Alucify (Advanced): Reset Extension** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+A confirmation dialog appears warning what will be cleared. Click **Yes, reset** to proceed.
+
+## After Reset
+
+- The Welcome view reappears
+- You'll be prompted to pick an auth mode again
+- Analyses are untouched; reopen a project and its data is still there
+
+## vs. Reset Analysis
+
+- **[Reset Analysis](../resetting-analysis.md)** — archives a project's `.alucify/` data to start that project fresh; auth and extension settings are preserved
+- **Reset Extension** — clears auth and extension settings; projects' analyses are preserved
+
+## When to Use
+
+- Debugging auth issues
+- Switching to a different Anthropic account on this machine
+- Reproducing a first-run experience

package/dist/docs/help/vscode/appgraph-visualizer/_meta.json

@@ -0,0 +1 @@
+{ "title": "AppGraph Visualizer", "order": 6 }

package/dist/docs/help/vscode/appgraph-visualizer/filtering-and-search.md

@@ -0,0 +1,63 @@
+---
+order: 3
+title: "Filtering and Search"
+description: "Narrowing the AppGraph view with filters and text search."
+---
+
+# Filtering and Search
+
+The AppGraph Visualizer lets you narrow what's visible via filters (pinned in the left panel) and free-text search.
+
+## Filter by Node Type
+
+Toggle each node type on or off:
+
+- **Interface** — UI screens, views, components
+- **Logic** — functions, classes, modules
+- **Schema** — data models, types, tables
+- **FunctionalArea** — top-level feature areas
+- **FeatureSpec** — feature definitions
+- **AcceptanceCriterion** — testable conditions
+- **Validation** — tests
+- **Other** — anything else
+
+See [AppGraph](../../concepts/appgraph.md) for what each type represents.
+
+## Filter by Status
+
+Narrow to specific [implementation statuses](../../concepts/implementation-progress.md):
+
+- Planned
+- In Progress
+- Implemented
+- Tested
+- Deprecated
+
+Useful for: "show me only what's still planned" or "what's in-progress right now?"
+
+## Filter by Origin
+
+Every node has an origin indicating where it came from:
+
+- **Spec** — introduced by a specification artifact (with the spec name)
+- **Code** — found during code analysis
+- **Intent** — captured from a Claude Code session ([Intent Capture](../../concepts/intent-capture.md))
+
+Filter to, for example, see only intent-captured nodes — useful to review what Claude Code sessions have introduced to your project.
+
+## Filter by Neighborhood
+
+Click a node and choose **Focus on Neighborhood** (N hops) to hide everything not reachable from this node within N edges. Good for: trace dependencies, understand a subsystem.
+
+## Free-Text Search
+
+The search bar at the top of the visualizer accepts any text. It matches node names, descriptions, and source file paths. Matches are highlighted; clicking a result focuses it.
+
+## Combining Filters
+
+Filters are AND-combined — checking "Interface" and "In Progress" shows only interface nodes that are in-progress. Text search intersects with that set.
+
+## Clearing Filters
+
+- **Reset all filters** — click the Reset button at the top of the filter panel
+- **Clear search** — clear the search input

package/dist/docs/help/vscode/appgraph-visualizer/navigating-the-graph.md

@@ -0,0 +1,34 @@
+---
+order: 2
+title: "Navigating the Graph"
+description: "Zooming, panning, and moving through the AppGraph Visualizer."
+---
+
+# Navigating the Graph
+
+## Basic Navigation
+
+- **Pan** — click and drag any empty space
+- **Zoom** — scroll wheel (trackpad pinch on macOS)
+- **Select a node** — single-click
+- **Focus a node** — double-click to center and zoom in
+- **Fit to screen** — click the Fit button in the toolbar
+
+## Force-Directed Layout
+
+The graph uses a force-directed layout — nodes repel each other and edges pull connected nodes together. The layout runs continuously by default, which is why nodes drift slowly until they settle.
+
+- **Freeze layout** — click the lock icon in the toolbar to stop the simulation
+- **Restart layout** — click again to resume
+
+## Traversing Edges
+
+Click any edge to traverse along it. The connected node becomes the new focus. Use this to explore dependency chains or implementation links.
+
+## Mini-map
+
+A mini-map in the bottom-right shows your current viewport relative to the full graph. Click any spot on the mini-map to jump there.
+
+## Performance
+
+Very large graphs (thousands of nodes) may render slowly with the force layout running. Filter the view first (see [Filtering and Search](filtering-and-search.md)) to narrow the scope, or freeze the layout once nodes have settled.

package/dist/docs/help/vscode/appgraph-visualizer/node-details.md

@@ -0,0 +1,49 @@
+---
+order: 4
+title: "Node Details"
+description: "Reading node information in the AppGraph Visualizer details pane."
+---
+
+# Node Details
+
+When you click a node, a detail pane opens showing everything Alucify knows about it.
+
+## What's Displayed
+
+### Identity
+- **Name** — canonical name of the node
+- **Type** — node type (Logic, Interface, etc.)
+- **ID** — internal AppGraph ID (copyable; used by MCP tools)
+
+### Status
+- **Status badge** — Planned / In Progress / Implemented / Tested / Deprecated
+- **Gap notes** (for in-progress) — what's still missing
+- **Status history** — status changes across versions
+
+### Grounding
+- **Source files** — where in the code this node lives (clickable; opens in editor)
+- **Spec references** — which artifacts introduced or reference this node
+- **Origin** — Spec / Code / Intent
+
+### Relationships
+- **Inbound edges** — what points at this node (callers, parents, etc.)
+- **Outbound edges** — what this node points at (dependencies, children)
+
+Click any edge entry to jump to the connected node.
+
+### Metrics
+- **[Blast radius](../../concepts/blast-radius.md)** — percentage of the project reachable from this node
+- **Depth** — how many hops from the nearest root
+
+## Jumping to Source
+
+Clicking a source file opens it in the editor at the right location. For Logic nodes, this typically means the function definition; for Schema nodes, the type or table declaration.
+
+## Editing
+
+The visualizer is read-only. To change a spec, edit the spec file directly; to change code, edit the source. Alucify picks up the changes on the next analysis.
+
+## Copying
+
+- **Copy ID** — useful when asking Claude about a specific node via MCP tools
+- **Copy as link** — creates a link you can paste into specs or docs that will navigate back to this node when clicked

package/dist/docs/help/vscode/appgraph-visualizer/opening-the-visualizer.md

@@ -0,0 +1,33 @@
+---
+order: 1
+title: "Opening the Visualizer"
+description: "How to open the AppGraph Visualizer panel in VS Code."
+---
+
+# Opening the AppGraph Visualizer
+
+The AppGraph Visualizer is an interactive graph view of every node and edge in your [AppGraph](../../concepts/appgraph.md).
+
+## Ways to Open It
+
+- **Command Palette** — `Cmd+Shift+P` / `Ctrl+Shift+P` → search for **Alucify: Open AppGraph Visualizer**
+- **Advanced menu** — in the Alucify Activity Bar view, expand **Advanced** and click **Open AppGraph Visualizer** (requires [Advanced Mode](../settings/advanced-mode.md) to be on)
+- **Context links** — anywhere a node is displayed in the extension (e.g., the Specifications or AI Coding Risks panels), click the node to open the visualizer focused on it
+
+## Prerequisites
+
+You must have run at least one analysis — code or spec. Without an AppGraph, the visualizer is empty.
+
+## Panel Behavior
+
+The visualizer opens as a VS Code webview panel (not a sidebar view). It takes up the entire editor column by default but can be moved into a split view like any other VS Code tab.
+
+## Reopening a Specific Node
+
+The last node you clicked is remembered across sessions. When you reopen the visualizer, it focuses on that node automatically. To start fresh, clear all filters from the panel.
+
+## See Also
+
+- [Navigating the Graph](navigating-the-graph.md)
+- [Filtering and Search](filtering-and-search.md)
+- [Node Details](node-details.md)

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

@@ -0,0 +1 @@
+{ "title": "Authentication", "order": 3 }

package/dist/docs/help/vscode/authentication/api-key-setup.md

@@ -0,0 +1,47 @@
+---
+order: 2
+title: "Setting Up an Anthropic API Key"
+description: "How to configure Alucify with your Anthropic API key for pay-per-use access."
+---
+
+# Setting Up an Anthropic API Key
+
+Use your own Anthropic API key to pay per token for AI analysis.
+
+## Getting an API Key
+
+1. Go to [console.anthropic.com](https://console.anthropic.com)
+2. Create an account or sign in
+3. Navigate to **API Keys**
+4. Click **Create Key** and copy the generated key (it starts with `sk-ant-`)
+
+## Entering Your Key in Alucify
+
+### During Welcome Setup
+
+1. In Step 2 of the welcome screen, select **Anthropic API Key**
+2. Enter your API key in the text field
+3. Click **Save**
+4. You'll see a confirmation: "Anthropic API key saved securely."
+
+### After Setup
+
+If you need to update your API key later:
+
+1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Search for **Alucify: Set Anthropic API Key**
+3. Enter your new key
+
+## Security
+
+Your API key is stored securely in VS Code's built-in secret storage. It is never written to disk in plain text or included in any project files.
+
+## Cost Considerations
+
+API costs depend on your analysis mode and project size:
+
+- **Speed mode** — Free (no AI calls, mechanical analysis only)
+- **Balanced mode** — Moderate cost (uses Claude Sonnet)
+- **Quality mode** — Higher cost (uses Claude Opus for comprehensive analysis)
+
+The exact cost depends on your codebase size and the number of specs you analyze. For most projects, a single code analysis in Balanced mode costs a few dollars.

package/dist/docs/help/vscode/authentication/claude-code-setup.md

@@ -0,0 +1,43 @@
+---
+order: 3
+title: "Using Claude Code / Claude Max Subscription"
+description: "How to use your existing Claude Code or Claude Max subscription with Alucify."
+---
+
+# Using Claude Code / Claude Max Subscription
+
+If you have a Claude Code or Claude Max subscription, you can use it with Alucify instead of paying per token with an API key.
+
+## Prerequisites
+
+1. **Claude Code CLI** installed on your machine — download from [claude.ai/download](https://claude.ai/download)
+2. An active **Claude Code** or **Claude Max** subscription
+3. The CLI authenticated (run `claude` in your terminal to verify)
+
+## Setting Up
+
+### During Welcome Setup
+
+1. In Step 2 of the welcome screen, select **Claude Code Subscription**
+2. If the Claude CLI is detected, you'll see a green status indicator
+3. If the CLI is not detected, you'll see "(CLI not detected)" in red — install Claude Code first
+
+### After Setup
+
+You can switch to Claude Code mode at any time:
+
+1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Search for **Alucify: Switch Auth Mode**
+3. Select **Claude Code Subscription**
+
+## How It Works
+
+When using Claude Code mode, Alucify runs AI analysis through the Claude CLI on your machine. This uses your subscription's included usage rather than per-token billing.
+
+## Troubleshooting
+
+If Alucify can't detect your Claude CLI:
+
+- Ensure `claude` is available in your system PATH
+- Try running `claude --version` in your terminal to verify it's installed
+- Restart VS Code after installing the Claude CLI

package/dist/docs/help/vscode/authentication/signing-in.md

@@ -0,0 +1,36 @@
+---
+order: 1
+title: "Creating an Account & Signing In"
+description: "How to create an Alucify account and sign in from the welcome screen."
+---
+
+# Creating an Account & Signing In
+
+An Alucify account is required to use the extension. Accounts are free to create.
+
+## Signing Up
+
+1. Click the **Alucify** icon in the VS Code activity bar
+2. On the welcome screen, find **Step 1: Sign in to Alucify**
+3. Click **Sign Up / Sign In**
+4. A browser window opens to the Alucify authentication page
+5. Create a new account or sign in with an existing one
+6. After successful authentication, VS Code shows a confirmation — click **Allow** to complete the sign-in
+
+Once signed in, a green checkmark appears next to the step, along with your username.
+
+## Signing Out
+
+To sign out:
+
+1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Search for **Alucify: Logout**
+3. Select the command
+
+## Signing Back In
+
+If you've previously dismissed the welcome screen:
+
+1. Open the Command Palette
+2. Search for **Alucify: Sign In**
+3. Follow the browser authentication flow

package/dist/docs/help/vscode/authentication/switching-auth-modes.md

@@ -0,0 +1,28 @@
+---
+order: 4
+title: "Switching Between Auth Modes"
+description: "How to switch between Anthropic API key and Claude Code subscription authentication."
+---
+
+# Switching Between Auth Modes
+
+You can switch between API key and Claude Code subscription at any time.
+
+## How to Switch
+
+1. Open the Command Palette (`Ctrl+Shift+P` / `Cmd+Shift+P`)
+2. Search for **Alucify: Switch Auth Mode**
+3. Select your preferred mode
+
+You'll see a confirmation message: "Auth mode switched to: [mode name]"
+
+## When to Switch
+
+- **To API Key** — If you don't have a Claude Code subscription, or if you want more control over per-token costs
+- **To Claude Code** — If you have a Claude Code or Claude Max subscription and want to use your subscription's included usage
+
+## Notes
+
+- Switching auth modes does not affect your existing analysis data
+- Any in-progress workflows will need to be restarted after switching
+- Your API key (if previously set) is retained in secure storage even when using Claude Code mode, so you can switch back without re-entering it

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

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

package/dist/docs/help/vscode/chat/asking-about-your-project.md

@@ -0,0 +1,39 @@
+---
+order: 1
+title: "Asking Questions About Your Project"
+description: "How to use the chat panel to ask questions about your project's architecture and specs."
+---
+
+# Asking Questions About Your Project
+
+The Ask About Project feature lets you have a conversation with Claude about your project, using the context from your Alucify analysis.
+
+## How to Start
+
+1. In the **Project Analysis** panel header, click the **chat icon** (comment discussion icon)
+2. Or open the Command Palette and search for **Alucify: Ask about Project**
+
+A chat panel opens in the secondary sidebar.
+
+## What You Can Ask
+
+With your analysis as context, Claude can answer questions like:
+
+- "What does the authentication flow look like?"
+- "Which parts of the codebase handle payment processing?"
+- "Are there any requirements that aren't implemented yet?"
+- "What would be affected if I changed the user data model?"
+- "How does the notification system work?"
+
+## Using the Chat
+
+- Type your question in the message input field
+- Press Enter or click the send button
+- Claude responds with answers grounded in your project analysis
+- Continue the conversation with follow-up questions
+
+## Tips
+
+- **Run analysis first** — The chat is most useful after you've run code analysis and/or spec analysis, as Claude uses those results to ground its answers
+- **Be specific** — The more specific your question, the more targeted the answer
+- **Use for exploration** — This is a great way to understand an unfamiliar codebase or to explore how different parts of your project relate to each other

package/dist/docs/help/vscode/chat/generating-artifacts-in-chat.md

@@ -0,0 +1,53 @@
+---
+order: 3
+title: "Generating Artifacts in Chat"
+description: "Creating new spec artifacts with AI assistance inside VS Code."
+---
+
+# Generating Artifacts in Chat
+
+Artifact generation lets you create new specs from templates with Claude's help. Useful when you know what you want but don't have a formal spec document yet.
+
+## Prerequisites
+
+- Authentication set up (see [Authentication](../authentication/signing-in.md))
+- For Claude Code subscription users: Claude Code CLI installed
+
+## Starting Generation
+
+1. Open the Specs sidebar view
+2. Click **Generate Spec**
+3. Pick a template:
+   - **PRD** — full product requirements document
+   - **Architecture** — technical architecture doc
+   - **UX** — user experience flow / wireframe description
+   - **Epic / Story** — feature epic with stories and acceptance criteria
+   - **Quick Spec** — lightweight one-pager
+   - **Custom** — describe your own format
+
+4. Describe what you want in a few sentences
+
+Claude drafts a full artifact and streams it into the chat view. You iterate with follow-up messages ("make it shorter", "add mobile considerations", etc.) until you're happy.
+
+## What Claude Sees
+
+Each generation prompt includes:
+
+- The template structure
+- Your description
+- Your current [AppGraph](../../concepts/appgraph.md) summary (so the new spec is consistent with existing ones)
+- Relevant code excerpts if your description mentions specific features
+
+## Saving the Artifact
+
+When you're ready, click **Save as Artifact**. The generated content is written to `.alucify/artifacts/` with a filename you choose. It immediately appears in your Specs list with **Pending** status.
+
+## Running Analysis
+
+Once saved, you can click **Analyze** on the artifact to incorporate it into the project AppGraph — same flow as any manually-imported artifact.
+
+## Good Practices
+
+- **Start specific** — vague prompts produce generic specs. Say what this feature does, who uses it, and why.
+- **Reference existing nodes** — mention specific requirements, components, or data models by name. Claude will connect the new spec to them.
+- **Iterate, don't restart** — use follow-up messages rather than starting over. Claude keeps context and improves on previous drafts.