@alucify/cli 0.6.5 → 0.7.1

package/dist/docs/help/desktop/menu-bar.md

@@ -0,0 +1,47 @@
+---
+order: 5
+title: "Menu Bar"
+description: "Native menu bar options — File, Edit, View, Help."
+---
+
+# Menu Bar
+
+Alucify Desktop has a native OS menu bar with standard options organized into four menus.
+
+## File
+
+- **Open Workspace…** — switch to a different project folder. See [Switching Workspaces](switching-workspaces.md).
+- **Recent Workspaces** — jump to a recently-used workspace
+- **Close Window** — close the window (quits the app on macOS only if no windows remain)
+- **Quit Alucify** (macOS) / **Exit** (Windows/Linux)
+
+## Edit
+
+Standard editing commands — **Undo**, **Redo**, **Cut**, **Copy**, **Paste**, **Select All**. These work in any text field inside the app (e.g., chat input, settings fields).
+
+## View
+
+- **Reload** — refresh the web UI (rarely needed; useful if the UI gets into a weird state)
+- **Toggle Developer Tools** — open the Chromium inspector for debugging
+- **Actual Size / Zoom In / Zoom Out** — adjust UI scale
+- **Toggle Full Screen**
+
+## Help
+
+- **Alucify Help** — opens the in-app help browser (the content you're reading now)
+- **Send Feedback** — opens a feedback form or email link
+- **Check for Updates** — force an update check
+- **About Alucify** — version, license, credits
+
+## macOS Extras
+
+- The **Alucify** menu at the far left (macOS convention) contains **About**, **Preferences**, **Hide / Hide Others**, **Quit**
+- The Dock icon shows a badge count when notifications are pending (see [Notifications](notifications.md))
+
+## Keyboard Access
+
+All menu items are keyboard-accessible:
+- macOS: `Cmd+key` combinations
+- Windows/Linux: `Alt+letter` to enter the menu, then arrow keys
+
+See [Keyboard Shortcuts](keyboard-shortcuts.md) for the full list.

package/dist/docs/help/desktop/notifications.md

@@ -0,0 +1,44 @@
+---
+order: 6
+title: "Notifications"
+description: "OS-native notifications for completed analyses and errors."
+---
+
+# Notifications
+
+Alucify Desktop uses your OS's native notification system to tell you when long-running work finishes, so you don't have to keep the window focused.
+
+## What Triggers a Notification
+
+- **Analysis completed** — code analysis, spec analysis, or progress analysis finished
+- **Analysis failed** — something went wrong and the run stopped
+- **Intent capture ingested** — new intent was found and added to the AppGraph
+
+Short, fast operations (quick mechanical checks, small status queries) don't notify.
+
+## What a Notification Shows
+
+- **Title** — what finished (e.g., "Spec Analysis Complete")
+- **Body** — a one-line summary (scores, risk counts, or error message)
+- **Action** — clicking the notification focuses the Alucify window and jumps to the relevant tab
+
+## Enabling / Disabling
+
+Notifications are on by default. To turn them off:
+
+1. Open the **Settings** tab in the app
+2. Toggle **OS Notifications**
+
+Or use your OS's notification settings to silence Alucify at the OS level:
+
+- **macOS:** System Settings → Notifications → Alucify
+- **Windows:** Settings → System → Notifications → Alucify
+- **Linux:** varies by desktop environment (GNOME Settings → Notifications, KDE System Settings → Notifications)
+
+## Focus Mode / Do Not Disturb
+
+Alucify respects your OS-level Focus / Do Not Disturb settings. If DND is on, notifications are queued and shown when DND lifts (OS-dependent behavior).
+
+## Notification History
+
+macOS and Windows keep a notification history pane you can review if you missed one. Alucify itself doesn't show an in-app history — the AppGraph versions page and the workflow panel both record what ran when.

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

@@ -0,0 +1,43 @@
+---
+order: 1
+title: "Quickstart"
+description: "Install the Alucify Desktop app and run your first analysis."
+---
+
+# Desktop Quickstart
+
+The Alucify Desktop app is a standalone native app (macOS, Windows, Linux) that embeds the full Alucify web UI. If you'd rather not install VS Code or manage a CLI, this is the simplest path.
+
+## 1. Install
+
+Download the installer for your OS from the Alucify releases page. See [Installation](installation.md) for detailed steps.
+
+## 2. Pick a Workspace
+
+On first launch, the app asks you to pick a project folder. This becomes your workspace — Alucify stores its analysis in `.alucify/` inside that folder. See [Workspace Picker](workspace-picker.md).
+
+## 3. Sign In
+
+Pick an authentication mode:
+- **Claude Code subscription** (default) — requires Claude Code CLI installed
+- **API key** — paste a key from console.anthropic.com
+
+See [Authentication Modes](../concepts/authentication-modes.md).
+
+## 4. Analyze Code
+
+On the Dashboard, click **Analyze Code**. Pick an [analysis mode](../concepts/analysis-modes.md) (Speed, Balanced, or Quality) and wait for the analysis to finish. You'll see the result in the Code Analysis tab.
+
+## 5. Add Specs and Analyze
+
+Drag your spec files (PRDs, design docs, etc.) into the Artifacts sidebar, or click **Add**. Then click **Analyze Specs**.
+
+## 6. Review Risks
+
+Open the AI Coding Risks tab to see what Alucify found. For each risk, you can resolve via chat, update the spec or code, or mark it as ignored.
+
+## What's Next
+
+- [Switching Workspaces](switching-workspaces.md) — work on multiple projects
+- [Notifications](notifications.md) — get notified when long analyses finish
+- [Workflow Overview](../concepts/workflow-overview.md) — the full five-step flow

package/dist/docs/help/desktop/switching-workspaces.md

@@ -0,0 +1,39 @@
+---
+order: 4
+title: "Switching Workspaces"
+description: "Moving between projects without losing analysis state."
+---
+
+# Switching Workspaces
+
+You can open a different project at any time — no need to restart the app.
+
+## How to Switch
+
+From the menu bar:
+- **File → Open Workspace…** — pick a different folder
+- **File → Recent Workspaces** — jump to a project you've opened before
+
+The native file picker opens; pick the new folder, and Alucify reloads with that workspace.
+
+## What Happens Under the Hood
+
+When you switch workspaces, Alucify:
+
+1. Stops the server bound to your current workspace
+2. Starts a new server bound to the new workspace path
+3. Reloads the web UI against the new server
+
+This takes ~1 second. You'll see the window briefly reload.
+
+## Analysis State Is Preserved
+
+All your analysis — AppGraphs, versions, risks, progress — is stored inside the workspace's `.alucify/` directory. Switching doesn't touch any of it. When you switch back, your state is exactly as you left it.
+
+## Single Instance
+
+Alucify Desktop enforces a single running instance per user. If you try to launch a second copy, it focuses the existing window rather than opening a new one. To work on multiple projects side by side, use the CLI-hosted web UI (via `alucify ui`) in a separate browser tab — that can run alongside the desktop app.
+
+## In-Progress Analyses
+
+If you switch workspaces while an analysis is running, the analysis is cancelled cleanly. Any progress written up to that point is kept (as an in-progress version), so nothing is lost — but the run won't complete.

package/dist/docs/help/desktop/workspace-picker.md

@@ -0,0 +1,38 @@
+---
+order: 3
+title: "Workspace Picker"
+description: "Choosing which project folder to analyze."
+---
+
+# Workspace Picker
+
+Alucify Desktop works on one **workspace** (project folder) at a time. The workspace is where Alucify stores its analysis data — the `.alucify/` directory is created inside this folder.
+
+## First Launch
+
+The first time you launch Alucify Desktop, a native file picker opens and asks you to choose a folder. Pick the root of any codebase you want to analyze.
+
+The picker requires a directory, not a file. You can't analyze arbitrary files — Alucify needs a project root to infer structure, languages, and build context.
+
+## Recent Workspaces
+
+Alucify remembers the workspaces you've opened. On subsequent launches, it reopens the most recently-used workspace automatically. You can switch to a different one at any time; see [Switching Workspaces](switching-workspaces.md).
+
+## What Gets Created in Your Workspace
+
+On first analysis, Alucify creates a `.alucify/` directory at the workspace root containing:
+
+- `appgraph-baseline.json` / `appgraph-project.json` — the [AppGraph](../concepts/appgraph.md)
+- `artifacts/` — your imported specs
+- `versions/` — historical snapshots
+- `token-usage/` — per-workflow token logs
+
+See [Alucify Directory Structure](../reference/alucify-directory.md) for the full layout.
+
+## Version Control
+
+You can commit `.alucify/` to git to share analysis across your team, or add it to `.gitignore` for privacy. Your call.
+
+## Changing Workspaces Without Losing Work
+
+All analysis data is stored inside the workspace folder — so switching workspaces doesn't lose anything. You can re-open any project later and pick up where you left off.

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

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

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

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

package/dist/docs/help/extension/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/extension/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/extension/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/extension/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/extension/chat/_meta.json

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

package/dist/docs/help/extension/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/extension/code-analysis/_meta.json

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

package/dist/docs/help/extension/code-analysis/analysis-modes.md

@@ -0,0 +1,63 @@
+---
+order: 3
+title: "Analysis Modes: Catalog, Fast, and Full"
+description: "The three analysis depth modes — when to use each and what they produce."
+---
+
+# Analysis Modes
+
+Alucify offers three analysis modes that trade off speed, cost, and depth. You choose a mode each time you run code analysis or spec analysis.
+
+## Speed (Catalog Mode)
+
+- **Time:** Usually 5–10 minutes
+- **Cost:** Free — no AI calls
+- **How it works:** Uses mechanical analysis (AST parsing and static analysis) to extract your project's structure. No AI model is involved.
+- **Best for:** Getting a quick overview, initial exploration, or when you want to minimize costs
+
+**What you get:**
+- Project structure (interfaces, logic, schemas)
+- Tech stack detection
+- Lines of code count
+- Basic dependency mapping
+
+## Balanced (Fast Mode)
+
+- **Time:** Usually 15–60 minutes
+- **Cost:** Moderate (uses Claude Sonnet)
+- **How it works:** Combines mechanical analysis with AI-powered extraction for deeper understanding. Uses Claude Sonnet for cost-efficient analysis.
+- **Best for:** Most projects — the recommended default for a good balance of insight and cost
+
+**What you get:**
+- Everything in Speed mode, plus:
+- AI-powered classification of components
+- Congruency analysis (when running spec analysis)
+- Richer dependency understanding
+
+## Quality (Full Mode)
+
+- **Time:** Usually 45–90 minutes
+- **Cost:** Higher (uses Claude Opus for comprehensive analysis)
+- **How it works:** Full multi-pass AI analysis with all checks enabled. Uses Claude Opus for maximum accuracy and depth.
+- **Best for:** Important analyses where thoroughness matters, such as before a major release or when onboarding a new AI coding agent to a complex project
+
+**What you get:**
+- Everything in Balanced mode, plus:
+- Semantic extraction with deeper understanding
+- Comprehensive relationship mapping
+- Holistic congruency analysis across all specs
+
+## Choosing a Mode
+
+| Consideration | Speed | Balanced | Quality |
+|---------------|-------|----------|---------|
+| Time | 5–10 min | 15–60 min | 45–90 min |
+| AI Cost | Free | Moderate | Higher |
+| Depth | Surface-level | Good | Comprehensive |
+| Best for | Quick overview | Day-to-day use | Critical analysis |
+
+**Tip:** You can start with Speed mode to get quick results, then re-analyze in Balanced or Quality mode when you need deeper insights. Each analysis creates a new version, so you don't lose previous results.
+
+## Selecting a Mode
+
+When you click **Analyze Code** or **Analyze Specs**, a dropdown appears with the three options. Select the one that fits your needs. The estimate text reads: "Estimates vary by codebase size."

package/dist/docs/help/extension/code-analysis/running-code-analysis.md

@@ -0,0 +1,54 @@
+---
+order: 1
+title: "Analyzing Your Codebase"
+description: "How to run code analysis to build a baseline understanding of your project."
+---
+
+# Analyzing Your Codebase
+
+Code analysis scans your project's source code to build a structured understanding of its architecture — what screens, logic, and data models exist.
+
+## Running Code Analysis
+
+1. Open the Alucify sidebar by clicking the Alucify icon in the activity bar
+2. In the **Project Analysis** panel, click the **Analyze Code** button
+3. Select an analysis mode:
+   - **Speed** — Optimized for speed, usually 5–10 minutes
+   - **Balanced** — Balances speed and quality, usually 15–60 minutes
+   - **Quality** — Optimized for quality, usually 45–90 minutes
+4. Wait for the analysis to complete
+
+A progress indicator shows the current phase. You can continue working in VS Code while the analysis runs.
+
+## Choosing an Analysis Mode
+
+See [Analysis Modes](analysis-modes.md) for a detailed comparison of the three modes.
+
+As a general rule:
+- Start with **Speed** to get quick results at no cost
+- Use **Balanced** for most projects where you want AI-powered insights
+- Use **Quality** for important analyses where thoroughness matters most
+
+## Re-Analyzing After Code Changes
+
+When your code changes after a previous analysis, the Code Analysis tab shows a message: "Code has changed since the last baseline was generated." Click **Analyze Code** again to update your baseline with the latest changes.
+
+## What Happens During Analysis
+
+During code analysis, Alucify:
+
+1. Scans your source files to identify components, services, and data models
+2. Maps dependencies and relationships between them
+3. Detects your tech stack (frameworks, languages)
+4. Counts lines of code
+5. Saves a versioned snapshot of the analysis
+
+When complete, the results appear in the [Code Analysis tab](understanding-the-code-analysis-tab.md).
+
+## Using the Command Palette
+
+You can also start code analysis from the Command Palette:
+
+1. Press `Ctrl+Shift+P` / `Cmd+Shift+P`
+2. Search for **Alucify: Analyze Code**
+3. Select your analysis mode

package/dist/docs/help/extension/code-analysis/understanding-ai-coding-risks.md

@@ -0,0 +1,75 @@
+---
+order: 5
+title: "Understanding AI Coding Risks"
+description: "How to view and interpret the AI Coding Risks panel — risk types, severity levels, and mitigations."
+---
+
+# Understanding AI Coding Risks
+
+AI Coding Risks are issues Alucify identifies that could cause problems when AI coding agents work on your project. Resolving these risks before handing work to an AI agent helps ensure better, more aligned implementations.
+
+## Opening the Panel
+
+- From the Code Analysis tab, click **View Details** next to the AI Coding Risks section
+- Or open the Command Palette and search for **Alucify: View AI Coding Risks**
+
+## Risk Severity Levels
+
+Each risk has a severity level:
+
+- **Critical** (red) — Issues that will very likely cause incorrect AI implementations
+- **High** (orange) — Significant issues that frequently lead to problems
+- **Medium** (yellow) — Moderate issues that may cause occasional problems
+- **Low** (blue) — Minor issues worth addressing when convenient
+
+## Risk Types
+
+Alucify identifies several categories of risk:
+
+- **Missing UX Spec** — A screen or UI component exists in code but has no corresponding specification
+- **Missing Data Spec** — A data model exists in code but has no corresponding specification
+- **Missing Logic Spec** — Business logic exists in code but has no corresponding specification
+- **Missing Acceptance Criteria** — Requirements exist without clear criteria for what "done" looks like
+- **Requirements Gap** — Specs reference functionality that doesn't exist in code
+- **Conflict** — Contradictions between different specs, or between specs and code
+- **Naming Issue** — Inconsistent terminology between specs and code
+- **Structural Issue** — Architectural problems that could confuse AI agents
+- **High Blast Radius** — Changes to this area affect many other parts of the system
+- **Domain Gap** — Missing domain knowledge that an AI agent would need
+- **Duplicate** — The same concept is defined in multiple places
+
+## Reading a Risk Entry
+
+Each risk in the list shows:
+
+1. **Severity** — Color-coded dot indicating severity level
+2. **Risk Type** — Category of the risk
+3. **Label** — A brief description of the specific issue
+4. **Action** — The recommended action to resolve it
+
+## Exploring Solutions
+
+Click on a risk to expand it and see solution options:
+
+- **Recommended** — The solution Alucify suggests based on the analysis (marked with a badge)
+- **Alternative options** — Other ways to address the issue
+- Each solution shows its expected impact
+
+## Resolving Risks
+
+You have several options for each risk:
+
+- **Resolve via chat** — Opens the [Refine Specs](../spec-analysis/refining-specs.md) chat to work with Claude on resolving the issue interactively
+- **Ignore this issue** — Marks the risk as ignored if it's not relevant to your project
+
+## Risk Status
+
+Risks can have three statuses:
+
+- **Open** (red) — Not yet addressed
+- **Fixed** (green) — Resolved, with details about what was changed and when
+- **Ignored** (gray) — Marked as not relevant
+
+## Bulk Actions
+
+You can select multiple risks using checkboxes and resolve them together using the **Refine Specs** button at the top of the panel.