@alucify/cli 0.6.5 → 0.7.1

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

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

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

@@ -0,0 +1 @@
+{ "title": "Versions", "order": 9 }

package/dist/docs/help/vscode/versions/comparing-versions.md

@@ -0,0 +1,47 @@
+---
+order: 1
+title: "Comparing Versions"
+description: "Diffing two AppGraph versions in VS Code."
+---
+
+# Comparing Versions
+
+For what versions are and why they exist, see [Versions & Snapshots](../../concepts/versions-and-snapshots.md).
+
+## Opening the Compare View
+
+- **Command Palette** — **Alucify: Compare Versions**
+- **Advanced menu** — **Compare Versions** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+## Selecting Versions
+
+The compare view asks you to pick two version snapshots: a **base** and a **target**. By convention you compare an older version (base) against a newer one (target), but either order works.
+
+## What's Shown
+
+The diff view has three sections:
+
+### Nodes
+- **Added** — nodes present in target but not base
+- **Removed** — nodes in base but not target
+- **Modified** — nodes whose fields changed (status, source file, description)
+
+Click any node to see the per-field diff.
+
+### Scores
+Before/after values for congruency, coverage, completeness, AI readiness, and blast radius. Deltas are color-coded (green for improvement, red for regression).
+
+### Risks
+- **Resolved** — risks present in base but not target
+- **New** — risks in target but not base
+- **Persisting** — risks present in both
+
+## Use Cases
+
+- **Track progress over a sprint** — compare the start and end of a two-week window
+- **Validate spec changes** — compare pre- and post-spec-refinement
+- **Compare analysis modes** — run the same project in Fast and Full, compare what Full catches
+
+## Exporting a Diff
+
+The **Export** button produces a Markdown or JSON summary of the diff. Useful for PR descriptions, sprint reviews, or audit trails.

package/dist/docs/help/vscode/versions/deleting-versions.md

@@ -0,0 +1,44 @@
+---
+order: 3
+title: "Deleting Versions"
+description: "Removing old AppGraph versions you no longer need."
+---
+
+# Deleting Versions
+
+Each version snapshot takes disk space (a few MB to tens of MB depending on project size). You can delete versions you no longer need.
+
+## Opening the Delete Dialog
+
+- **Command Palette** — **Alucify: Delete Version**
+- **Advanced menu** — **Delete Version** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+## What Can Be Deleted
+
+Any version **except the current one**. If you need to delete the current version, switch to a different one first (see [Switching Versions](switching-versions.md)).
+
+## What Gets Removed
+
+Deletion removes:
+- The version's AppGraph JSON files from `.alucify/versions/`
+- Associated analysis reports (congruency, coverage, etc.)
+- Risk records specific to that version
+
+The token usage log is **not** affected — usage history is append-only and lives separately.
+
+## Reversing a Delete
+
+Deletion is not reversible. If you've committed `.alucify/` to git, you can recover deleted versions via `git checkout`. Otherwise, they're gone.
+
+## Bulk Deletion
+
+To delete multiple versions at once, select them in the version list with checkboxes, then click **Delete selected**. You'll be asked to confirm before the delete runs.
+
+## Automatic Cleanup
+
+Alucify does not automatically delete old versions. If you want regular cleanup, delete manually on a schedule that fits your team's needs.
+
+## See Also
+
+- [Versions & Snapshots](../../concepts/versions-and-snapshots.md)
+- [Alucify Directory Structure](../../reference/alucify-directory.md)

package/dist/docs/help/vscode/versions/switching-versions.md

@@ -0,0 +1,43 @@
+---
+order: 2
+title: "Switching Versions"
+description: "Loading an older AppGraph version as your current view."
+---
+
+# Switching Versions
+
+You can load an older version as your current view — useful for investigating how the project looked at a past point without losing newer versions.
+
+## Opening the Version List
+
+- **Command Palette** — **Alucify: Switch Version**
+- **Advanced menu** — **Switch Version** (requires [Advanced Mode](../settings/advanced-mode.md))
+
+## What Happens When You Switch
+
+The extension reloads all panels against the selected version:
+
+- Project Analysis panel shows that version's scores
+- AI Coding Risks panel shows risks as they existed at that version
+- Requirements Progress shows status as it was then
+
+New analyses you run will create new versions — they don't overwrite older ones.
+
+## Returning to Latest
+
+To go back to the newest version, open the version list and pick the most recent entry (marked with a **Current** badge when selected).
+
+## In-Progress Versions
+
+Versions created during an in-progress analysis are filtered out of the default list. To see them, toggle **Show in-progress versions** in the version list. These are useful for debugging partially-completed analyses.
+
+## Gotchas
+
+- Switching to an older version affects what's shown in the UI but doesn't change files on disk. Your code isn't modified.
+- MCP tools serve the **current** version (the latest). To point Claude Code at an older version, you'd need to delete newer ones — usually not what you want.
+
+## See Also
+
+- [Versions & Snapshots](../../concepts/versions-and-snapshots.md)
+- [Comparing Versions](comparing-versions.md)
+- [Deleting Versions](deleting-versions.md)

package/dist/docs/help/vscode/workflow-controls.md

@@ -0,0 +1,49 @@
+---
+order: 11
+title: "Workflow Controls"
+description: "Pausing, resuming, and canceling long-running analyses in VS Code."
+---
+
+# Workflow Controls
+
+Analyses that take more than a few minutes (Balanced and Quality modes, especially on large projects) can be paused, resumed, or canceled.
+
+## Where the Controls Are
+
+- **Workflow Status view** in the Alucify Activity Bar shows live progress and exposes the controls
+- **Status bar item** at the bottom of VS Code shows a compact indicator; click it to open the Workflow Status view
+
+## Controls
+
+### Pause
+Suspends the current workflow at the next phase boundary. Any in-flight LLM calls finish first — no tokens are wasted. State is checkpointed so you can resume later.
+
+Use when:
+- You need to step away and want to pick up later
+- You're close to your API rate limit and want to let it reset
+- You want to inspect intermediate results before continuing
+
+### Resume
+Picks up from the last checkpoint. Already-completed phases don't re-run; only the work that was pending continues.
+
+### Cancel
+Stops the workflow entirely. In-flight LLM calls finish, then the workflow exits without writing final results. Any partial data produced up to that point is preserved as an in-progress version.
+
+## What's Preserved
+
+- **Paused:** everything — the run resumes exactly where it stopped
+- **Canceled:** partial outputs, written as an in-progress version (not visible in the default version list)
+
+To view an in-progress version, enable [Advanced Mode](settings/advanced-mode.md) and toggle **Show in-progress versions** in the version list.
+
+## Notifications
+
+If you've enabled OS notifications, you'll get a notification when:
+- A workflow completes (or fails)
+- A paused workflow has been idle for 30+ minutes (reminder to resume or cancel)
+
+See [Notification Preferences](settings/notification-preferences.md).
+
+## What Can't Be Controlled
+
+Mechanical phases (AST parsing, file scanning) run too fast to expose pause controls — they complete in seconds. Controls apply only to LLM-driven phases.

package/dist/docs/help/what-is-alucify.md

@@ -0,0 +1,56 @@
+---
+order: 0
+title: "What is Alucify?"
+description: "An overview of Alucify — what it does, who it's for, and how it helps you build better software with AI coding agents."
+---
+
+# What is Alucify?
+
+Alucify ensures your project is ready for AI coding by creating a unified, structured context and identifying potential gaps and issues to save you time and tokens.
+
+## The Problem
+
+When you use AI coding agents like Claude Code to build features, the AI needs to understand your project — its architecture, requirements, and how everything fits together. Without this context, AI agents can:
+
+- Miss requirements that aren't documented in code
+- Create implementations that conflict with existing specs
+- Introduce technical debt by not understanding the broader system
+- Waste tokens re-discovering project structure on every session
+
+## How Alucify Helps
+
+Alucify works in five steps — see the [Workflow Overview](concepts/workflow-overview.md):
+
+1. **Analyze Code** — Scan your codebase to identify its structure, components, data models, and business logic.
+2. **Add Specs** — Import your PRDs, design docs, API specs, and any other project documents. Many formats supported.
+3. **Analyze Specs** — Compare your specifications against your codebase to identify coverage gaps, contradictions, and potential impact.
+4. **Review Risks** — Use the interactive chat to refine your specs based on the analysis findings. Resolve risks before handing work to an AI coding agent.
+5. **Plan & Track Progress** — Plan implementation work against open requirements and monitor AI-generated code against your specs as commits land.
+
+## Who Is Alucify For?
+
+Alucify is designed for software teams and individual developers who:
+
+- Use AI coding agents (like Claude Code) to implement features
+- Have requirements documents, PRDs, or design specs that guide their work
+- Want to ensure their AI-generated code aligns with project requirements
+- Need to track implementation progress against specifications
+
+## Four UIs, One Core
+
+You can use Alucify through whichever interface fits your workflow — they're all equal peers backed by the same core engine:
+
+- **[VS Code Extension](vscode/installation.md)** — tightly integrated with your editor (tree views, status bar, command palette, inline jumps)
+- **[CLI](cli/installation.md)** — scriptable, great for automation and CI/CD; also launches the Web UI
+- **[Web UI](cli/ui/launching.md)** — rich browser dashboard with chat and visualizations
+- **[Desktop App](desktop/installation.md)** — standalone native app with workspace management and OS notifications
+
+Alucify also exposes an **[MCP Server](mcp-server/setup.md)** that gives Claude Code direct access to your project analysis.
+
+Not sure which UI to pick? See [Choosing a UI](getting-started/choosing-a-ui.md).
+
+## What's Next?
+
+- [Choosing a UI](getting-started/choosing-a-ui.md) — Pick the right interface for you
+- [Key Concepts](getting-started/key-concepts.md) — Understand the core ideas behind Alucify
+- [Your First Analysis](getting-started/first-analysis.md) — Run through the full workflow end-to-end