@alucify/cli 0.6.5 → 0.7.1

package/dist/docs/help/concepts/authentication-modes.md

@@ -0,0 +1,68 @@
+---
+order: 12
+title: "Authentication Modes"
+description: "The two ways Alucify authenticates with Claude — API key vs Claude Code subscription."
+---
+
+# Authentication Modes
+
+Alucify talks to Claude through one of two modes. You choose which mode to use during onboarding, and you can switch later.
+
+## Claude Code Subscription (default)
+
+Alucify uses your existing Claude Code CLI login. No separate API key needed — if you're signed in to Claude Code, you're signed in to Alucify.
+
+**Prerequisites:**
+- Claude Code CLI installed (`claude` on your PATH)
+- Active Claude subscription (Pro or Team)
+
+**Pros:**
+- No API key to manage
+- Usage counts against your subscription, not a separate API bill
+- Faster onboarding
+
+**Cons:**
+- Requires the Claude Code CLI installed locally
+- Usage is capped by subscription limits (5-hour rolling windows)
+
+## Anthropic API Key
+
+Alucify calls the Anthropic API directly using your API key. Usage is billed to your Anthropic Console account.
+
+**Prerequisites:**
+- API key from [console.anthropic.com](https://console.anthropic.com)
+
+**Pros:**
+- No local CLI dependency
+- Usage limits are based on your API tier, not subscription
+
+**Cons:**
+- Separate billing to manage
+- You handle the key securely (stored in OS keychain or CLI credentials file)
+
+## Which Mode Should I Use?
+
+- **Active Claude Code user on Pro/Team plan** → Claude Code Subscription
+- **Standalone / CI / team deployments** → API Key
+- **Want lowest friction to start** → Claude Code Subscription
+- **Want predictable, isolated billing** → API Key
+
+## Setting Up
+
+- CLI: [Authentication](../cli/authentication.md)
+- VS Code: [Signing In](../vscode/authentication/signing-in.md), [API Key Setup](../vscode/authentication/api-key-setup.md), [Claude Code Setup](../vscode/authentication/claude-code-setup.md)
+- Web UI: [Settings Tab](../cli/ui/settings-tab.md)
+- Desktop: same as Web UI (auth UI is embedded)
+
+## Switching Modes
+
+You can switch between modes at any time without losing analysis data.
+- VS Code: [Switching Auth Modes](../vscode/authentication/switching-auth-modes.md)
+
+## Where Credentials Are Stored
+
+- **API key (VS Code):** OS keychain via VS Code secret storage
+- **API key (CLI):** `~/.alucify/credentials.json` (chmod 600)
+- **Claude Code subscription:** Inherited from Claude Code CLI's own credential store (`~/.claude/`)
+
+Alucify never transmits credentials to its own servers — all LLM calls go directly to Anthropic.

package/dist/docs/help/concepts/blast-radius.md

@@ -0,0 +1,37 @@
+---
+order: 14
+title: "Blast Radius"
+description: "What blast radius means and how Alucify computes the impact of changes."
+---
+
+# Blast Radius
+
+Blast radius measures the potential impact of changing a piece of code. A small blast radius means a change is well-contained; a large blast radius means changing one thing may ripple through many others.
+
+## Why It Matters
+
+AI coding agents (and humans) make safer, faster changes to low-blast-radius code. High-blast-radius areas are where small edits cause unexpected breakage — exactly the kind of thing Alucify wants you to see *before* handing work to an agent.
+
+## How It's Computed
+
+Blast radius is a graph computation over the [AppGraph](appgraph.md):
+
+1. Start from a node (e.g., a function, a data model, a UI component)
+2. Follow outbound edges (`depends_on`, `affects`, `parent_of`)
+3. Count the transitively-reachable nodes within a hop limit (typically 3 hops)
+4. Normalize against the total graph size → a percentage
+
+So "23% blast radius" means that roughly 23% of the project is reachable from that node within a few dependency hops.
+
+## Project-Level vs Node-Level
+
+- **Project-level blast radius** — The average across all change-prone nodes. Shown as a top-level metric on the Spec Analysis tab.
+- **Node-level blast radius** — How much the project would be affected if *this specific node* changed. Shown in node details and in the AppGraph Visualizer.
+
+## As a Risk Signal
+
+Any node with a high blast radius (typically > 30%) becomes a **High Blast Radius** risk in the [AI Coding Risks](ai-coding-risks.md) panel. It's a warning, not a problem per se — some high-blast-radius code is inevitable (core utilities, foundational types). But if you didn't expect a node to have high blast radius, that's a structural issue worth investigating.
+
+## Trace Dependencies (MCP)
+
+From Claude Code you can ask for the blast radius of a file or set of files via [`trace_dependencies`](../mcp-server/tools/impact-analysis.md). The response includes direct and transitive impacts up to 3 hops.

package/dist/docs/help/concepts/chat-refinement.md

@@ -0,0 +1,40 @@
+---
+order: 15
+title: "Chat Refinement"
+description: "How Alucify's chat lets you refine specs, ask about your project, and generate artifacts."
+---
+
+# Chat Refinement
+
+Alucify's chat is a multi-turn Claude conversation grounded in your current AppGraph, specs, and analysis. You use it to refine specs, ask questions about your project, and generate new artifacts — all without leaving the product.
+
+## Three Chat Modes
+
+### Ask About Your Project
+Open-ended Q&A grounded in your current AppGraph. Good for exploratory questions: "Which features are least tested?", "What specs contradict the code?", "What's the blast radius of this module?"
+
+### Refine Specs
+Iterative spec improvement focused on specific risks or requirements. You typically open this from the AI Coding Risks panel — Claude sees the risk context and helps you resolve it.
+
+### Generate Artifacts
+AI-assisted spec writing from templates (PRD, architecture, UX, epics/stories, quick spec, custom). Claude drafts the spec using your project context, then you iterate.
+
+## What Makes It Different from Raw Claude
+
+Every chat turn includes:
+- The current AppGraph summary
+- Relevant spec excerpts
+- Current risk context (if applicable)
+- Existing artifact content
+
+This grounding means Claude doesn't hallucinate about your project — it's working from the real analysis data.
+
+## Where to Find It
+
+- VS Code: [Asking About Your Project](../vscode/chat/asking-about-your-project.md), [Refining Specs in Chat](../vscode/chat/refining-specs-in-chat.md), [Generating Artifacts in Chat](../vscode/chat/generating-artifacts-in-chat.md)
+- Web UI: [Chat Panel](../cli/ui/chat-panel.md)
+- Desktop: uses the same chat as the Web UI (embedded)
+
+## Not the Same as Claude Code
+
+Alucify's chat is separate from Claude Code. Claude Code is the agent that actually makes edits to your files; Alucify's chat refines specs and answers questions about your project. The two integrate — Alucify's `alucify plan` and `alucify continue` commands launch Claude Code sessions with Alucify context pre-loaded. See [Claude Code Integration](../integrations/claude-code.md).

package/dist/docs/help/concepts/congruency-coverage-completeness.md

@@ -0,0 +1,50 @@
+---
+order: 5
+title: "Congruency, Coverage & Completeness"
+description: "The three dimensions Alucify uses to measure spec-to-code alignment."
+---
+
+# Congruency, Coverage & Completeness
+
+Spec analysis measures three independent dimensions plus a composite readiness score.
+
+## Congruency
+
+How well your specs **align** with your code. A high congruency score means specs and code tell the same story — few contradictions or mismatches. Low congruency means your specs describe something different from what the code actually does.
+
+Congruency is scored 0–100%. You'll see it broken down per spec (in a heatmap) and aggregated across the project.
+
+## Coverage
+
+How much of your codebase is **covered** by specifications. High coverage means most components have corresponding requirements or specs. Low coverage means you have code that isn't backed by any spec.
+
+Coverage is scored 0–100%, broken down by component type (interfaces, logic, schemas, etc.).
+
+## Completeness
+
+How thorough your specs are along multiple dimensions — do requirements have clear acceptance criteria? Are error states described? Are data models complete? Completeness catches thin specs even when congruency and coverage look fine.
+
+## AI Readiness
+
+A composite score combining congruency, coverage, completeness, and other factors. This is the overall indicator of how prepared your project is for AI coding agents to work effectively. See [AI Readiness](ai-readiness.md).
+
+## Impact Categories
+
+During spec analysis, every component gets classified into one of four impact categories:
+
+- **New** — Introduced by specs, doesn't exist in code yet
+- **Modified** — Existing in code, specs would change it
+- **Affected** — Indirectly impacted by spec changes (via dependencies)
+- **Intact** — Unaffected by spec changes
+
+## Relationship to AI Coding Risks
+
+Low scores in any of these dimensions produce specific [AI Coding Risks](ai-coding-risks.md):
+
+- Low coverage → Missing UX/Data/Logic Spec risks
+- Low congruency → Conflict, Naming, or Requirements Gap risks
+- Low completeness → Missing Acceptance Criteria risks
+
+For UI-specific instructions on viewing these metrics, see:
+- VS Code: [Specifications Panel](../vscode/spec-analysis/specifications-panel.md)
+- Web UI: [Requirements Progress Tab](../cli/ui/requirements-progress-tab.md)

package/dist/docs/help/concepts/implementation-progress.md

@@ -0,0 +1,44 @@
+---
+order: 9
+title: "Implementation Progress"
+description: "How Alucify tracks what's implemented, what's in progress, and what's still open."
+---
+
+# Implementation Progress
+
+Alucify tracks implementation status on every node in your [AppGraph](appgraph.md), giving you a live picture of how much of your spec is actually built.
+
+## Statuses
+
+Every requirement and validation node carries one of these statuses:
+
+- **Planned** — Specified but no code exists yet
+- **In Progress** — Partial implementation detected, or gaps flagged
+- **Implemented** — Code satisfies the specification
+- **Tested** — A validation (test) exists and maps to this requirement
+- **Deprecated** — Intentionally removed or superseded
+
+## How Status Is Determined
+
+Status is assigned in two phases:
+
+### 1. During Spec Analysis
+When specs are integrated into the AppGraph, Alucify does a mechanical pass that matches each spec node to code it might be backed by. Clean matches get `implemented`; clear gaps get `planned`; partial or ambiguous matches get `in_progress` with gap notes.
+
+### 2. As Commits Land
+Each git commit triggers progress analysis (via a post-commit hook if you've run `alucify enable`). Alucify reads the commit, maps changed files to nodes, and updates statuses. A pre-commit hook also runs a fast check so you see status updates before the commit finishes.
+
+## Gap Notes
+
+For `in_progress` nodes, Alucify writes a short "what's still missing" note attached to the node. This is the most useful signal when you're about to hand work to Claude Code — the gap note tells the agent exactly where to pick up.
+
+## Progress Reports
+
+- CLI: [`alucify progress`](../cli/commands/progress.md) and [`alucify status`](../cli/commands/status.md)
+- VS Code: [Dev Progress Tab](../vscode/dev-progress/understanding-the-dev-progress-tab.md)
+- Web UI: [Requirements Progress Tab](../cli/ui/requirements-progress-tab.md)
+- MCP Server: [`get_implementation_tasks`](../mcp-server/tools/implementation-tasks.md), [`get_remaining_work`](../mcp-server/tools/coverage-gaps.md)
+
+## Planning Against Gaps
+
+Use `alucify plan` or `/alucify-plan` in Claude Code to plan work against currently open requirements. The planner reads the current progress state and proposes implementation tasks focused on closing gaps. See [`alucify plan`](../cli/commands/plan.md) and [Using MCP with Claude Code](../mcp-server/using-with-claude-code.md).

package/dist/docs/help/concepts/intent-capture.md

@@ -0,0 +1,46 @@
+---
+order: 10
+title: "Intent Capture"
+description: "What intent capture extracts from your Claude Code sessions and how it appears in your AppGraph."
+---
+
+# 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.
+
+For UI-specific instructions, see:
+- CLI: [`alucify capture-intent`](../cli/commands/capture-intent.md)
+- VS Code: [Enabling Intent Capture](../vscode/intent-capture/enabling-intent-capture.md)
+
+## 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/concepts/tech-debt-analysis.md

@@ -0,0 +1,65 @@
+---
+order: 7
+title: "Tech Debt Analysis"
+description: "What Tech Debt Analysis measures — health score, structural risk, debt trend, and complexity."
+---
+
+# Tech Debt Analysis
+
+Tech Debt Analysis is a detailed assessment of your codebase's structural health, helping you identify areas of architectural risk before they cause problems for AI coding agents. It runs as part of code analysis in Balanced or Quality modes.
+
+For UI-specific instructions on viewing tech debt, see:
+- VS Code: [Tech Debt Panel](../vscode/code-analysis/tech-debt-panel.md)
+- Web UI: [Tech Debt Tab](../cli/ui/tech-debt-tab.md)
+
+## Architecture Health Score
+
+A single score (0–100) with a letter grade summarizes 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
+
+### 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 Dimensions
+
+### Remediation
+Priority actions to reduce technical debt, ordered by impact. Each action shows what percentage of total debt it addresses, the issue, and the expected outcome. A **Root Cause** alert may highlight high-dependency components that source multiple issues.
+
+### Change Scope
+How far changes propagate through your codebase: average scope percentage, how many components a typical change touches, and a breakdown by change type rated Low / Moderate / High effort.
+
+### Structural Risk
+A snapshot of architectural complexity today:
+- **Fragility Index** — 0–100 score measuring coupling, dependency cycles, and bottlenecks
+- **Health Score Breakdown** — individual scores for each dimension with letter grades and weights
+- **Stress Attribution** — which structural patterns (circular dependencies, single points of failure, cross-feature coupling) contribute most to risk
+
+### Debt Trend (Projection)
+A forward-looking simulation that projects how your architecture responds to sustained change pressure. Shows whether debt compounds or gets absorbed over time, a trajectory graph across simulation cycles, and the most affected components.
+
+### Complexity
+Complexity hotspots by location, with maximum cognitive complexity per component. Scale:
+- **0–5:** Trivial
+- **6–15:** Moderate
+- **16–30:** High (flagged as hotspot)
+- **31+:** Very high (strong refactoring signal)
+
+### Outdated Packages
+Dependencies that are out of date with current and latest versions, plus risk levels. Requires internet access during analysis.

package/dist/docs/help/concepts/token-usage.md

@@ -0,0 +1,70 @@
+---
+order: 11
+title: "Token Usage"
+description: "What tokens are, how they're categorized, and how to interpret your usage data."
+---
+
+# Token Usage
+
+This page explains what tokens are and how Alucify tracks them. For UI-specific instructions, see:
+- CLI: [`alucify usage`](../cli/commands/usage.md)
+- VS Code: [Viewing Token Usage](../vscode/token-usage/viewing-token-usage.md)
+- Web UI: [Token Usage Tab](../cli/ui/token-usage-tab.md)
+
+
+## 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/concepts/versions-and-snapshots.md

@@ -0,0 +1,57 @@
+---
+order: 13
+title: "Versions & Snapshots"
+description: "How Alucify versions your analysis and lets you compare or revert between versions."
+---
+
+# Versions & Snapshots
+
+Every time Alucify runs a code analysis, spec analysis, or progress analysis, it creates a new versioned snapshot of your AppGraph. Nothing is overwritten — you always have history.
+
+## Version Identifiers
+
+Versions are labeled `v1`, `v2`, `v3`, ... in the order they were created. The most recent version is your "current" version; earlier versions stay available for comparison.
+
+## What's in a Version
+
+Each version captures:
+- The full AppGraph (nodes + edges)
+- Scores (congruency, coverage, AI readiness, etc.)
+- Risks identified at that point
+- Implementation status per node
+- Analysis mode used
+
+Version metadata (timestamp, git commit hash, who ran it) is stored in `.alucify/versions/`.
+
+## Diffing Versions
+
+You can compare any two versions to see:
+- Nodes added, removed, or modified
+- Status changes (e.g., `planned` → `implemented`)
+- Score deltas
+- Risks resolved or newly surfaced
+
+Commands:
+- CLI: [`alucify version --diff v1..v3`](../cli/commands/version.md)
+- VS Code: [Comparing Versions](../vscode/versions/comparing-versions.md)
+- MCP Server: [`diff_context`](../mcp-server/tools/version-diff.md)
+
+## Switching Versions
+
+You can load an older version as your current view if you want to see the project as it was at an earlier point. This doesn't delete newer versions — they remain available.
+
+- VS Code: [Switching Versions](../vscode/versions/switching-versions.md)
+
+## Deleting Versions
+
+Old versions take disk space but are otherwise harmless. You can delete versions you no longer need; the current version can't be deleted.
+
+- VS Code: [Deleting Versions](../vscode/versions/deleting-versions.md)
+
+## Version Control
+
+You can commit `.alucify/` to git to share AppGraph history with your team (recommended for most projects), or gitignore it for privacy. See [Alucify Directory Structure](../reference/alucify-directory.md#version-control).
+
+## Progressive Snapshots
+
+During a long analysis, Alucify writes an in-progress version snapshot so you can see partial results before the full analysis completes. In-progress versions are filtered out of the default version list but can be viewed in Advanced mode.

package/dist/docs/help/concepts/workflow-overview.md

@@ -0,0 +1,40 @@
+---
+order: 1
+title: "Workflow Overview"
+description: "The five-step Alucify workflow that applies across every UI."
+---
+
+# Workflow Overview
+
+Alucify's core workflow is the same across every UI — only the way you invoke each step changes.
+
+## The Five Steps
+
+### 1. Analyze Code
+Alucify scans your codebase and builds a baseline [AppGraph](appgraph.md) — a structured model of interfaces, logic, schemas, and dependencies. You choose an [analysis mode](analysis-modes.md) based on how much time and cost you want to spend.
+
+### 2. Add Specs
+You import specification artifacts (PRDs, architecture docs, designs, requirements) into Alucify. See [Artifacts & Specs](artifacts-and-specs.md) for supported formats.
+
+### 3. Analyze Specs
+Alucify compares your specs against your code and produces three alignment scores: [Congruency, Coverage & Completeness](congruency-coverage-completeness.md). It also surfaces [AI Coding Risks](ai-coding-risks.md) — concrete issues that would confuse an AI coding agent.
+
+### 4. Review Risks
+You review the identified risks and resolve them, either by refining specs, updating code, or marking a risk as ignored. [Chat-based refinement](chat-refinement.md) lets you work with Claude on fixes interactively.
+
+### 5. Plan & Track Progress
+Once you're ready to implement, Alucify can plan work against the gaps and track [implementation progress](implementation-progress.md) as commits land.
+
+## Which UI Does What
+
+| Step | CLI | VS Code | Web UI | Desktop |
+|---|---|---|---|---|
+| Analyze Code | `alucify analyze-code` | Analyze Code button | Dashboard → Analyze | Dashboard → Analyze |
+| Add Specs | `alucify add-spec` | Specs sidebar → Add | Artifacts sidebar → Upload | Artifacts sidebar → Upload |
+| Analyze Specs | `alucify analyze-specs` | Specs → Analyze | Dashboard → Analyze Specs | Dashboard → Analyze Specs |
+| Review Risks | n/a (review via VS Code or Web) | AI Coding Risks panel | AI Coding Risks tab | AI Coding Risks tab |
+| Plan & Track | `alucify plan`, `alucify progress` | Dev Progress tab | Requirements Progress tab | Requirements Progress tab |
+
+## Incremental Workflow
+
+After the first full pass, subsequent analysis runs are incremental — Alucify detects which files changed since the last baseline and only re-analyzes what's affected. See [Versions & Snapshots](versions-and-snapshots.md).

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

@@ -0,0 +1 @@
+{ "title": "Desktop App", "order": 5 }

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

@@ -0,0 +1,56 @@
+---
+order: 2
+title: "Installation"
+description: "Download and install the Alucify Desktop app on macOS, Windows, or Linux."
+---
+
+# Installing Alucify Desktop
+
+## Download
+
+Get the installer for your platform from the Alucify releases page:
+
+- **macOS** — `.dmg` (Apple Silicon) or `.dmg` (Intel)
+- **Windows** — `.exe` installer
+- **Linux** — `.AppImage` or `.deb`
+
+## System Requirements
+
+See [System Requirements](../getting-started/system-requirements.md). In short: modern 64-bit OS, 8 GB RAM recommended, ~500 MB disk.
+
+## macOS
+
+1. Download the `.dmg`
+2. Open it and drag **Alucify** into `Applications`
+3. The first time you open it, right-click → **Open** (macOS blocks unsigned apps by default; Alucify is signed and notarized but your OS may still warn)
+4. Grant any permissions the app requests
+
+## Windows
+
+1. Run the `.exe` installer
+2. Follow the prompts (choose a destination, create a shortcut)
+3. Launch **Alucify** from the Start menu
+
+## Linux
+
+### AppImage
+1. Download `Alucify-x.y.z.AppImage`
+2. `chmod +x Alucify-x.y.z.AppImage`
+3. Run it directly, or integrate with your desktop environment
+
+### Debian/Ubuntu (.deb)
+```bash
+sudo dpkg -i alucify_x.y.z_amd64.deb
+```
+
+## Updates
+
+The desktop app checks for updates on launch. When an update is available, you'll see a prompt. Updates download in the background and install on next restart.
+
+## Troubleshooting
+
+**"App can't be opened" on macOS:** See the [FAQ](../faq.md) or right-click the app → Open (instead of double-click).
+
+**Window doesn't appear:** Check if another Alucify window is already running — the app enforces a single instance per user.
+
+**Workspace not loading:** See [Workspace Picker](workspace-picker.md).

package/dist/docs/help/desktop/keyboard-shortcuts.md

@@ -0,0 +1,47 @@
+---
+order: 7
+title: "Keyboard Shortcuts"
+description: "Platform-native shortcuts for common actions in Alucify Desktop."
+---
+
+# Keyboard Shortcuts
+
+Shortcuts follow each OS's conventions. `Cmd` is the macOS modifier; on Windows/Linux, use `Ctrl` instead.
+
+## File
+
+| Action | macOS | Windows/Linux |
+|---|---|---|
+| Open Workspace | `Cmd+O` | `Ctrl+O` |
+| Close Window | `Cmd+W` | `Ctrl+W` |
+| Quit | `Cmd+Q` | `Alt+F4` |
+
+## Edit
+
+Standard editing shortcuts work in any text field:
+
+| Action | macOS | Windows/Linux |
+|---|---|---|
+| Undo | `Cmd+Z` | `Ctrl+Z` |
+| Redo | `Cmd+Shift+Z` | `Ctrl+Y` |
+| Cut / Copy / Paste | `Cmd+X/C/V` | `Ctrl+X/C/V` |
+| Select All | `Cmd+A` | `Ctrl+A` |
+
+## View
+
+| Action | macOS | Windows/Linux |
+|---|---|---|
+| Reload | `Cmd+R` | `Ctrl+R` |
+| Developer Tools | `Cmd+Option+I` | `Ctrl+Shift+I` |
+| Zoom In | `Cmd++` | `Ctrl++` |
+| Zoom Out | `Cmd+-` | `Ctrl+-` |
+| Actual Size | `Cmd+0` | `Ctrl+0` |
+| Full Screen | `Ctrl+Cmd+F` | `F11` |
+
+## Web UI Shortcuts
+
+Inside the embedded web UI, additional shortcuts may apply (search, chat focus, etc.). These are documented with each feature in [Web UI](../cli/ui/_meta.json).
+
+## Customization
+
+Desktop-level shortcuts are not user-customizable in the current version. If that matters to you, let us know via the Help → Send Feedback menu.