@alucify/cli 0.6.5 → 0.7.0

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

@@ -0,0 +1 @@
+{ "title": "CLI & Web UI", "order": 3 }

package/dist/docs/help/cli/authentication.md

@@ -0,0 +1,70 @@
+---
+order: 3
+title: "CLI Authentication"
+description: "How to authenticate the CLI with an Anthropic API key or Claude Code subscription."
+---
+
+# CLI Authentication
+
+The CLI supports two authentication modes. For a full comparison of the modes and when to pick each, see [Authentication Modes](../concepts/authentication-modes.md).
+
+## Default: Claude Code Subscription
+
+```bash
+alucify analyze-code
+```
+
+Requires the Claude Code CLI installed (`claude` on your PATH) and an active subscription. Run `claude` once to ensure it's authenticated.
+
+Explicit form:
+```bash
+alucify analyze-code --auth claudeCode
+```
+
+## API Key
+
+```bash
+alucify analyze-code --auth apiKey --api-key sk-ant-your-key-here
+```
+
+Billed to your Anthropic Console account.
+
+Or set an environment variable to avoid passing the flag every time:
+```bash
+export ALUCIFY_AUTH_MODE=apiKey
+export ANTHROPIC_API_KEY=sk-ant-...
+alucify analyze-code
+```
+
+## Which Commands Need AI?
+
+Not all commands use AI:
+
+| Command | Needs AI? | Notes |
+|---|---|---|
+| `analyze-code` | Only in Balanced / Quality modes | Speed mode is free |
+| `analyze-specs` | Only in Balanced / Quality modes | Speed mode is free |
+| `analyze-progress` | Yes | Always uses AI |
+| `add-spec` | No | File copy only |
+| `status`, `progress`, `version`, `usage`, `check`, `context` | No | Reads local data |
+| `enable`, `disable`, `mcp-install` | No | Configures integration |
+| `plan`, `continue` | Via Claude Code | Launches Claude Code |
+| `help` | No | — |
+
+## Speed Mode Is Free
+
+```bash
+alucify analyze-code --mode catalog
+```
+
+No AI calls, no authentication required.
+
+## Credentials on Disk
+
+- **API key** — stored in `~/.alucify/credentials.json` (chmod 600) after first explicit use
+- **Claude Code subscription** — inherited from Claude Code's own credential store at `~/.claude/`
+
+Clear credentials:
+```bash
+rm ~/.alucify/credentials.json
+```

package/dist/docs/help/cli/automation.md

@@ -0,0 +1,72 @@
+---
+order: 6
+title: "Automation & Scripting"
+description: "Using the CLI in git hooks, CI/CD, and custom scripts."
+---
+
+# Automation & Scripting
+
+The CLI is designed to be scripted. All commands that produce reports accept `--json` for machine-readable output, and exit codes are consistent for gating builds.
+
+## Exit Codes
+
+- `0` — success (including pre-commit hook runs, which always exit 0 to avoid blocking commits)
+- `1` — runtime error (network failure, bad arguments, missing prerequisites)
+
+Quality signals like "risks found" or "coverage below threshold" are **not** surfaced via exit codes — read them from `alucify status --json` and gate your own script's exit on them.
+
+## JSON Output
+
+Commands with structured output support `--json`:
+
+```bash
+alucify status --json
+alucify progress --json
+alucify usage --json
+alucify version --json
+alucify check --staged
+alucify context --json
+```
+
+JSON is streamed line-by-line for commands that emit progress events, and emitted as a single object for one-shot reports. Pipe into `jq` or any JSON tool.
+
+## Git Hooks
+
+Running [`alucify enable`](commands/enable-disable.md) installs:
+
+- **pre-commit** — runs [`alucify check --staged`](commands/check.md) with a ≤15s timeout. Blocks the commit only if a hard failure occurs; otherwise non-blocking.
+- **post-commit** — runs [`alucify analyze-progress`](commands/analyze-progress.md) asynchronously in the background.
+
+To install manually without `enable`, copy the scripts from `.alucify/hooks/` into `.git/hooks/`. See [Git Hooks](../integrations/git-hooks.md).
+
+## CI/CD
+
+See [CI/CD Integration](../integrations/ci-cd.md) for patterns:
+- Gate PRs on congruency or coverage thresholds
+- Post risk summaries to PR comments
+- Track token spend per build
+
+Quick example:
+
+```yaml
+# .github/workflows/alucify.yml
+- run: npm install -g @alucify/cli
+- run: alucify analyze-code --mode catalog
+- run: alucify analyze-specs --mode catalog
+- run: alucify status --json > alucify-status.json
+```
+
+## Scheduled Jobs
+
+For teams wanting periodic re-analysis:
+
+```bash
+# nightly re-baseline in Balanced mode
+0 2 * * * cd /path/to/project && alucify analyze-code --mode fast
+```
+
+Combine with commit hooks for continuous state: hooks keep the AppGraph current per-commit, while scheduled runs refresh the deeper analyses.
+
+## Scripting Claude Code Handoff
+
+You can invoke [`alucify plan`](commands/plan.md) or [`alucify continue`](commands/continue.md) from scripts. Both launch Claude Code non-interactively and pass the current analysis state as context.

package/dist/docs/help/cli/commands/_meta.json

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

package/dist/docs/help/cli/commands/add-spec.md

@@ -0,0 +1,49 @@
+---
+order: 3
+title: "alucify add-spec"
+description: "Add specification artifacts (PRDs, requirements, design files) to your project."
+---
+
+# alucify add-spec
+
+Imports specification files into your project for analysis. Files are copied into `.alucify/artifacts/`.
+
+## Usage
+
+```bash
+alucify add-spec <file-path> [<file-path> ...]
+```
+
+## Arguments
+
+| Argument | Description | Required |
+|----------|-------------|----------|
+| `<file-path>` | Path to a specification file. Multiple paths accepted. | Yes (at least one) |
+
+## Supported File Types
+
+Any file type — PDFs, Markdown, plain text, images, JSON, YAML, code files, and more. See [Supported Project Types](../../getting-started/supported-project-types.md) for the full list.
+
+## Examples
+
+```bash
+# Add a single spec
+alucify add-spec ~/specs/requirements.pdf
+
+# Add multiple specs at once
+alucify add-spec docs/api-spec.md docs/data-model.md docs/wireframes.png
+
+# Add all markdown files in a directory
+alucify add-spec docs/specs/*.md
+```
+
+## What Happens
+
+- Each file is copied into `.alucify/artifacts/`
+- Original filenames are preserved
+- No processing occurs — files are staged for the next `analyze-specs` run
+- Adding more files later is safe; existing files are not affected
+
+## Next Steps
+
+After adding specs, run `alucify analyze-specs` to compare them against your codebase.

package/dist/docs/help/cli/commands/analyze-code.md

@@ -0,0 +1,54 @@
+---
+order: 1
+title: "alucify analyze-code"
+description: "Extract a baseline analysis from your project source code."
+---
+
+# alucify analyze-code
+
+Scans your codebase to build a structured understanding of your project — its screens, logic, data models, and how they connect.
+
+## Usage
+
+```bash
+alucify analyze-code [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--mode <catalog\|fast\|full>` | Analysis depth | `catalog` |
+| `--auth <apiKey\|claudeCode>` | Authentication mode | `claudeCode` |
+| `--api-key <key>` | Anthropic API key (required when `--auth apiKey`) | — |
+
+## Analysis Modes
+
+- **`catalog`** (Speed) — Mechanical analysis only. Uses AST parsing and static analysis. **No AI calls, no cost.** Usually 5–10 minutes.
+- **`fast`** (Balanced) — Adds AI-powered classification using Claude Sonnet. Usually 15–60 minutes.
+- **`full`** (Quality) — Comprehensive AI analysis using Claude Opus. Usually 45–90 minutes.
+
+## Examples
+
+```bash
+# Free mechanical analysis (default)
+alucify analyze-code
+
+# AI-powered analysis with Claude Code subscription
+alucify analyze-code --mode fast
+
+# AI-powered analysis with API key
+alucify analyze-code --mode full --auth apiKey --api-key sk-ant-...
+```
+
+## Output
+
+Creates `.alucify/appgraph-baseline.json` — the baseline model of your codebase.
+
+## What It Detects
+
+- **Interfaces** — Screens, UI components, API endpoints
+- **Logic** — Services, workflows, handlers, business logic
+- **Schemas** — Data models, database schemas, type definitions
+- **Dependencies** — How components relate to each other
+- **Tech stack** — Frameworks and languages in use

package/dist/docs/help/cli/commands/analyze-progress.md

@@ -0,0 +1,73 @@
+---
+order: 4
+title: "alucify analyze-progress"
+description: "Analyze git commits to track implementation progress against your specs."
+---
+
+# alucify analyze-progress
+
+Analyzes your git commits (and uncommitted changes) to track which requirements have been implemented, are in progress, or are still planned.
+
+## Usage
+
+```bash
+alucify analyze-progress [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--commit <hash>` | Analyze a specific commit only | All commits since last checkpoint |
+| `--pre-commit` | Run in pre-commit hook mode (staged files, synchronous) | — |
+| `--timeout <ms>` | Timeout for pre-commit analysis in milliseconds | 15000 |
+
+## Prerequisites
+
+- A project with spec analysis results (run `analyze-code` and `analyze-specs` first)
+- Git commits to analyze
+
+## Examples
+
+```bash
+# Analyze all new commits since last checkpoint
+alucify analyze-progress
+
+# Analyze a specific commit
+alucify analyze-progress --commit abc1234
+
+# Pre-commit hook mode (called by the git hook, not typically run manually)
+alucify analyze-progress --pre-commit --timeout 15000
+```
+
+## What It Does
+
+1. Reads your git history since the last analyzed checkpoint
+2. Maps file changes to project components
+3. Classifies changes as implementations, partial implementations, or tests
+4. Updates implementation statuses (Planned → In Progress → Implemented → Tested)
+5. Saves a checkpoint so future runs only process new commits
+6. Creates a versioned snapshot
+
+## Pre-Commit Hook Integration
+
+When you run `alucify enable`, both a **pre-commit** and **post-commit** git hook are installed:
+
+1. **Pre-commit** (synchronous, ≤15s): Classifies staged files against the appgraph with a single LLM call. On success, the analysis output is staged into the same commit — one atomic commit with zero leftovers.
+
+2. **Post-commit** (async fallback): Only runs if the pre-commit analysis timed out or failed. Performs full async analysis in the background. Results are auto-staged into the next commit.
+
+The pre-commit hook always exits 0 — it never blocks your commit, even if the analysis fails or times out.
+
+## Output
+
+- Updates `.alucify/progress/checkpoint.json` with the latest analyzed commit
+- Creates a new version snapshot in `.alucify/versions/`
+
+## Notes
+
+- The first run processes all commits since your spec analysis
+- Subsequent runs only process commits made after the last checkpoint
+- Uncommitted changes are included in the analysis
+- Uses file locking to prevent concurrent modification
+- The pre-commit hook skips analysis during rebase, merge, and cherry-pick operations

package/dist/docs/help/cli/commands/analyze-specs.md

@@ -0,0 +1,60 @@
+---
+order: 2
+title: "alucify analyze-specs"
+description: "Integrate specifications and run congruency analysis against your codebase."
+---
+
+# alucify analyze-specs
+
+Analyzes your imported specification documents against your codebase to identify gaps, conflicts, and coverage issues.
+
+## Usage
+
+```bash
+alucify analyze-specs [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--mode <catalog\|fast\|full>` | Analysis depth | `catalog` |
+| `--auth <apiKey\|claudeCode>` | Authentication mode | `claudeCode` |
+| `--api-key <key>` | Anthropic API key (required when `--auth apiKey`) | — |
+
+## Prerequisites
+
+- Run `alucify analyze-code` first to create a baseline
+- Add specs with `alucify add-spec` before analyzing
+
+## Analysis Modes
+
+- **`catalog`** (Speed) — Mechanical projection of spec changes. **No AI calls, no cost.**
+- **`fast`** (Balanced) — AI-powered extraction and congruency checks using Claude Sonnet.
+- **`full`** (Quality) — Comprehensive analysis: requirement extraction, gap detection, full congruency using Claude Opus.
+
+## Examples
+
+```bash
+# Analyze specs with free mechanical mode
+alucify analyze-specs
+
+# AI-powered analysis
+alucify analyze-specs --mode balanced
+
+# Full analysis with API key
+alucify analyze-specs --mode full --auth apiKey --api-key sk-ant-...
+```
+
+## Output
+
+Creates `.alucify/appgraph-project.json` — a combined model of your codebase plus spec analysis results.
+
+After spec analysis completes, **progress analysis runs automatically** if your project has requirements linked to implementation code. This establishes the initial implementation status for all components — you don't need to run `analyze-progress` separately after your first spec analysis.
+
+## What It Finds
+
+- **Coverage gaps** — Requirements with no corresponding code
+- **Conflicts** — Contradictions between specs and existing code
+- **Congruency issues** — Misalignments between what's specified and what's built
+- **AI coding risks** — Issues that could cause problems for AI coding agents

package/dist/docs/help/cli/commands/capture-intent.md

@@ -0,0 +1,56 @@
+---
+order: 5
+title: "alucify capture-intent"
+description: "Extract requirements and decisions from Claude Code sessions and add them to your AppGraph."
+---
+
+# alucify capture-intent
+
+Reads your recent Claude Code session history and extracts project-level context — requirements you clarified, design decisions you made, scope you defined — then stages it for integration into your AppGraph.
+
+## Usage
+
+```bash
+alucify capture-intent [options]
+```
+
+## Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--force` | Extract immediately, even for very recent sessions | Wait for sessions to be idle |
+| `--backfill` | Re-process all past sessions from the beginning | Only new sessions since last run |
+| `--session-id <id>` | Process a single specific session only | All eligible sessions |
+
+## Prerequisites
+
+- `alucify enable` has been run (required to locate Claude Code session files)
+- An AppGraph exists (run `alucify analyze-code` or `alucify analyze-specs` first)
+
+## Example Output
+
+```
+  Intent Capture
+  Scanned:    12 sessions
+  Extracted:  3 sessions → 3 intent files
+  Skipped:    9 sessions  (no novel intent)
+
+  Extracted:
+    session-abc123 → .alucify/extractions/intents/01HV...json
+    session-def456 → .alucify/extractions/intents/01HV...json
+    session-ghi789 → .alucify/extractions/intents/01HV...json
+```
+
+## What Gets Extracted
+
+Sessions containing project-level decisions and requirements — things that would be meaningful additions to your AppGraph. Sessions that are only execution work (running commands, iterating on output) are skipped automatically.
+
+## Integrating Results
+
+`capture-intent` stages intent files but doesn't integrate them into the AppGraph. To integrate, run **Alucify: Analyze Intent** from the VS Code Command Palette, which does both capture and integration in one step.
+
+## Notes
+
+- Reads local session files only — no data leaves your machine beyond the normal Claude API calls
+- Extracted intent is stored in `.alucify/extractions/intents/`
+- Re-running is safe — already-processed sessions are skipped unless you pass `--backfill`

package/dist/docs/help/cli/commands/check.md

@@ -0,0 +1,49 @@
+---
+order: 13
+title: "alucify check"
+description: "Preview how uncommitted or staged changes would affect your AppGraph."
+---
+
+# `alucify check`
+
+Previews how your current uncommitted changes (or staged changes) would affect your AppGraph, without updating it.
+
+## Usage
+
+```bash
+alucify check [--staged|--last-commit]
+```
+
+## Options
+
+- `--staged` — check only files that are staged for commit (`git add`ed)
+- `--last-commit` — check the files changed in the most recent commit
+- *(no flag)* — check everything: staged, unstaged, and untracked files
+
+## What It Shows
+
+For each changed file, `check` reports:
+- Which AppGraph nodes are affected
+- The expected status changes (e.g., `planned` → `in_progress`)
+- [Blast radius](../../concepts/blast-radius.md) of the change
+- Any new risks that would be introduced
+
+This is the same logic the pre-commit hook runs, but manually invoked and with full output.
+
+## Examples
+
+```bash
+alucify check                  # preview all current changes
+alucify check --staged         # preview what's about to be committed
+alucify check --last-commit    # see what the most recent commit did
+```
+
+## When to Use It
+
+- **Before committing** — confirm the change has the expected impact
+- **During refactoring** — see blast radius before you finish
+- **Code review** — run on a PR branch locally to understand scope
+
+## Relation to `analyze-progress`
+
+`check` is a preview; it doesn't write anything. [`analyze-progress`](analyze-progress.md) is the real update that commits progress state based on what actually landed.

package/dist/docs/help/cli/commands/context.md

@@ -0,0 +1,52 @@
+---
+order: 14
+title: "alucify context"
+description: "Manage the AppGraph context surfaced to Claude Code via CLAUDE.md."
+---
+
+# `alucify context`
+
+Manages the project context that Alucify surfaces to Claude Code sessions.
+
+## Usage
+
+```bash
+alucify context [--update-claude-md] [--json]
+```
+
+## Options
+
+- `--update-claude-md` — regenerate the AppGraph-derived section of your project's `CLAUDE.md` file
+- `--json` — output the current context as JSON (for scripting)
+- *(no flag)* — print a human-readable summary
+
+## What Context Includes
+
+- A summary of the current AppGraph (node counts by type, status counts)
+- Any open AI Coding Risks that are above a severity threshold
+- Requirements currently `in_progress` with gap notes
+- A pointer to the MCP tools available (`query_context`, `trace_dependencies`, etc.)
+
+This is the information Claude Code's `/alucify-plan`, `/alucify-continue`, and session start hooks rely on.
+
+## CLAUDE.md Integration
+
+When you run `alucify enable`, Alucify writes an AppGraph-aware section into your project's `CLAUDE.md`. That section tells any Claude Code session how to use Alucify's MCP tools and what the current project state is.
+
+`alucify context --update-claude-md` rewrites just that section (preserving the rest of the file), which you might want to do if:
+- You've done significant analysis and want Claude Code to pick up new state
+- You manually edited `CLAUDE.md` elsewhere and want the Alucify section refreshed
+
+## Examples
+
+```bash
+alucify context                       # print human-readable context
+alucify context --json                # machine-readable
+alucify context --update-claude-md    # refresh CLAUDE.md
+```
+
+## See Also
+
+- [Claude Code Integration](../../integrations/claude-code.md)
+- [`alucify enable`](enable-disable.md)
+- [MCP Server — Using with Claude Code](../../mcp-server/using-with-claude-code.md)

package/dist/docs/help/cli/commands/continue.md

@@ -0,0 +1,40 @@
+---
+order: 9
+title: "alucify continue"
+description: "Continue a previously started workflow from where it left off."
+---
+
+# alucify continue
+
+Launches a Claude Code session focused on closing gaps identified during progress tracking. If no gaps exist, falls back to planning unimplemented requirements.
+
+## Usage
+
+```bash
+alucify continue
+```
+
+No flags or options.
+
+## Prerequisites
+
+- Claude Code CLI installed and authenticated
+- A project with analysis and progress tracking results
+
+## What It Does
+
+1. Ensures Claude Code integration is enabled (runs `alucify enable` if needed)
+2. Checks for a gap report from the last `analyze-progress` run
+3. If gaps exist, builds a targeted prompt with specific items to address and opens Claude Code
+4. If no gaps exist, falls back to the same behavior as `alucify plan`
+
+## When to Use
+
+- After running `alucify analyze-progress` and seeing unresolved gaps
+- When you want Claude Code to pick up where it left off on implementation work
+- As a daily workflow: commit, analyze progress, then continue
+
+## Notes
+
+- This command launches Claude Code interactively — it does not produce CLI output
+- Requires an active Claude Code or Claude Max subscription

package/dist/docs/help/cli/commands/enable-disable.md

@@ -0,0 +1,53 @@
+---
+order: 10
+title: "alucify enable / disable"
+description: "Enable or disable Alucify integration with Claude Code (hooks, MCP server, CLAUDE.md)."
+---
+
+# alucify enable / disable
+
+Wire up (or remove) the full Alucify integration with Claude Code, giving it access to your project analysis.
+
+## alucify enable
+
+```bash
+alucify enable
+```
+
+Installs the following components:
+
+1. **Claude Code hooks** — Inject project context into Claude Code sessions automatically
+2. **MCP server** — Registers the Alucify MCP server in `.mcp.json` so Claude Code can query your project
+3. **CLAUDE.md rules** — Adds project context rules to your `CLAUDE.md` file
+4. **Git hooks (pre-commit + post-commit)** — Automatically analyzes and tracks commits for progress tracking
+
+After enabling, Claude Code will have access to your project analysis through the MCP server tools. See [MCP Server Tools](../../mcp-server/tools/query.md) for what's available.
+
+**This command is idempotent** — running it multiple times is safe. It updates existing entries rather than duplicating them.
+
+## alucify disable
+
+```bash
+alucify disable
+```
+
+Removes all integration components:
+
+- Removes Alucify hooks from `.claude/settings.json`
+- Removes MCP server config from `.mcp.json`
+- Removes Alucify rules from `CLAUDE.md`
+- Removes git hooks (pre-commit + post-commit)
+
+**Your analysis data is preserved.** The `.alucify/` directory and all analysis results are left intact. Only the integration wiring is removed.
+
+**This command is also idempotent** — safe to run multiple times.
+
+## When to Use
+
+- **Enable** after running your initial analysis, when you're ready for Claude Code to use your project context
+- **Disable** if you want to temporarily stop Claude Code from using Alucify context, or when removing Alucify from a project
+
+## Notes
+
+- `enable` is automatically called by `alucify plan` and `alucify continue` if needed
+- The MCP server can also be installed separately with `alucify mcp-install` for a lighter-weight setup

package/dist/docs/help/cli/commands/help.md

@@ -0,0 +1,30 @@
+---
+order: 11
+title: "alucify help"
+description: "Display available CLI commands and usage information."
+---
+
+# alucify help
+
+Displays a summary of all available commands and their usage.
+
+## Usage
+
+```bash
+alucify help
+alucify --help
+alucify -h
+```
+
+## What It Shows
+
+A list of all available commands with brief descriptions and common options. Use this as a quick reference when you need to remember a command name or flag.
+
+## Getting Help for a Specific Command
+
+Most commands also accept `--help`:
+
+```bash
+alucify analyze-code --help
+alucify status --help
+```