@alucify/cli 0.6.4 → 0.7.0

package/dist/docs/help/cli/ui/chat-panel.md

@@ -0,0 +1,56 @@
+---
+order: 11
+title: "Chat Panel"
+description: "The embedded chat panel in the web UI — ask questions, refine specs, generate artifacts."
+---
+
+# Chat Panel
+
+The Chat Panel is a collapsible right-side panel that hosts multi-turn conversations with Claude grounded in your project.
+
+For what chat can do across all UIs, see [Chat Refinement](../../concepts/chat-refinement.md).
+
+## Opening the Panel
+
+The panel is hidden by default when no chat session is active. Several actions open it:
+
+- **Ask about Project** button on the Dashboard header
+- **Resolve via chat** on an AI Coding Risk
+- **Refine Specs** in bulk from the Risks tab
+- **Generate** from the Artifacts sidebar
+
+You can also click the chat toggle in the top-right of the web UI.
+
+## Three Modes
+
+Each mode has a different system context pre-loaded:
+
+### Ask About Your Project
+Free-form Q&A. Claude sees the AppGraph summary and can answer questions about structure, coverage, risks, and progress.
+
+### Refine Specs
+Focused on resolving one or more risks. Claude sees the risk context, the relevant spec, and the code.
+
+### Generate Artifact
+Claude drafts a new spec from a template and your description. You iterate with follow-ups.
+
+## Chat Input
+
+- **Text field** — your message
+- **Attach** — add a file or image for context (for Generate mode especially)
+- **Send** — submit
+
+## Chat Output
+
+Claude's responses render with:
+- Syntax-highlighted code blocks
+- Clickable references to AppGraph nodes (hover for details)
+- "Apply to spec" actions for suggested spec edits (in Refine mode)
+
+## Sessions
+
+Chat sessions are stored per-workspace. You can resume a previous session from the session switcher at the top of the panel. Sessions are gitignored by default (`.alucify/chats/`).
+
+## Relation to Claude Code
+
+This chat is separate from Claude Code. To hand off to Claude Code for actual code edits, use the **Plan** button which invokes `/alucify-plan` in Claude Code. See [Using MCP with Claude Code](../../mcp-server/using-with-claude-code.md).

package/dist/docs/help/cli/ui/code-analysis-tab.md

@@ -0,0 +1,36 @@
+---
+order: 3
+title: "Code Analysis Tab"
+description: "The Code Analysis tab in the web UI — baseline metrics and scan results."
+---
+
+# Code Analysis Tab
+
+The Code Analysis tab shows the results of your codebase scan — structure, tech stack, and architecture summary.
+
+For what analysis produces and how it works, see [Workflow Overview](../../concepts/workflow-overview.md) and [Analysis Modes](../../concepts/analysis-modes.md).
+
+## Sections
+
+### Codebase Summary
+- **Lines of Code** — total, with an abbreviated display (`1.2M`, `301k`)
+- **Tech Stack** — detected frameworks and languages as tag pills
+- **Analysis Date** — when the baseline was last generated
+
+### Analysis Mode
+Which [mode](../../concepts/analysis-modes.md) was used — Speed, Balanced, or Quality.
+
+### Architecture Health
+Summary score (0–100 + letter grade) with a **View Details** link to the Tech Debt tab for the full breakdown. See [Tech Debt Tab](tech-debt-tab.md) and [Tech Debt Analysis](../../concepts/tech-debt-analysis.md).
+
+### AI Coding Risks Summary
+Risk count with severity breakdown. **View Details** opens the [AI Coding Risks Tab](ai-coding-risks-tab.md).
+
+## Actions
+
+- **Analyze Code** — run or re-run the baseline scan with a mode selector
+- **View Full AppGraph** — open the [AppGraph Visualizer Tab](appgraph-visualizer-tab.md)
+
+## When Code Has Changed
+
+If your code has changed since the last baseline, Alucify shows a yellow banner: "Code has changed since last analysis — re-run to update." Incremental re-analysis only processes what changed.

package/dist/docs/help/cli/ui/dashboard.md

@@ -0,0 +1,44 @@
+---
+order: 2
+title: "Dashboard"
+description: "The home view of the web UI — workflow status and quick actions."
+---
+
+# Dashboard
+
+The Dashboard is the home view you land on when you open the web UI. It gives you a snapshot of your project's analysis state and quick access to the main actions.
+
+## Sections
+
+### Workflow Status
+Shows any in-progress or recently-finished workflow (code analysis, spec analysis, progress analysis). If a workflow is running, you'll see its current phase, a progress bar, and pause/resume/cancel controls.
+
+### Metric Cards
+Once you've run at least one analysis, the Dashboard shows high-level metrics:
+- Lines of code
+- Tech stack (detected languages and frameworks)
+- [Congruency, Coverage, AI Readiness](../../concepts/congruency-coverage-completeness.md)
+- Architecture health score
+
+### Quick Actions
+- **Analyze Code** — run or re-run code analysis
+- **Analyze Specs** — run spec analysis (enabled once you have specs imported)
+- **Add Specs** — opens the Artifacts sidebar for upload
+
+## Navigation
+
+The left sidebar has entries for each major view: Dashboard, Code Analysis, Tech Debt, AI Coding Risks, Requirements Progress, AppGraph Visualizer, Token Usage, Settings, Help.
+
+## Workflow Controls
+
+When a workflow is running, pause/resume/cancel buttons appear on the Dashboard. Pausing lets a long Quality-mode analysis wait while you free up API capacity or step away. Resuming picks up exactly where it left off.
+
+## Empty State
+
+Before your first analysis, the Dashboard shows an onboarding walkthrough with four step panels:
+1. Analyze Code
+2. Add Specs
+3. Review Risks
+4. Refine & Plan
+
+Click any step to jump to that action.

package/dist/docs/help/cli/ui/launching.md

@@ -0,0 +1,46 @@
+---
+order: 1
+title: "Launching the Web UI"
+description: "How to open the Alucify web UI — via CLI or embedded in the desktop app."
+---
+
+# Launching the Web UI
+
+The Alucify web UI is a browser-based dashboard that ships with the CLI. You can launch it in two ways.
+
+## From the CLI
+
+```bash
+alucify ui
+```
+
+This starts a local server (default port 3000, falling back to the next free port) and opens your default browser to the UI.
+
+Options:
+```bash
+alucify ui --port 4000     # pick a specific port
+alucify ui --no-open       # start the server, don't auto-open the browser
+```
+
+See the full command reference: [`alucify ui`](../commands/ui.md).
+
+## From the Desktop App
+
+If you're using the Alucify Desktop app, it launches its own copy of the web UI automatically inside its native window. You don't need to run `alucify ui` separately. See [Desktop Quickstart](../../desktop/quickstart.md).
+
+## What Runs Where
+
+- **Server** — starts in-process (on `localhost:<port>`), serves the UI and exposes REST + WebSocket endpoints
+- **Browser** — loads the UI, connects over WebSocket for real-time workflow events
+- **Auth** — a session token is generated on server start and included in the URL the browser opens
+
+Only processes on your machine can connect. The server binds to `127.0.0.1` by default.
+
+## Sharing a Session
+
+You can't share the session URL with someone on another machine — the token is machine-local and the server only listens locally. For team collaboration, share the workspace's `.alucify/` directory via git; each teammate runs their own local UI against their checkout.
+
+## Stopping the Server
+
+- **CLI-launched:** Ctrl+C in the terminal stops the server
+- **Desktop-launched:** the server stops automatically when you quit the desktop app

package/dist/docs/help/cli/ui/requirements-progress-tab.md

@@ -0,0 +1,49 @@
+---
+order: 6
+title: "Requirements Progress Tab"
+description: "The Requirements Progress tab in the web UI — implementation status per requirement."
+---
+
+# Requirements Progress Tab
+
+The Requirements Progress tab shows how much of your spec is actually built. Each requirement from your specs is listed with its current implementation status and validation coverage.
+
+For how statuses are determined, see [Implementation Progress](../../concepts/implementation-progress.md).
+
+## Overall Progress Metric
+
+At the top, a percentage bar shows "X% of requirements implemented" — a weighted average across all requirement nodes. Hover the bar for the breakdown by status (Planned / In Progress / Implemented / Tested).
+
+## Requirements List
+
+Each requirement shows:
+
+- **Name** — the FeatureSpec or AcceptanceCriterion label
+- **Status badge** — Planned / In Progress / Implemented / Tested / Deprecated
+- **Validation coverage** — "3 of 5 acceptance criteria validated"
+- **Gap notes** (for In Progress) — what's missing
+
+Click a requirement to expand and see:
+
+- Source file(s) backing the implementation
+- Which tests validate it
+- Commits that touched it recently
+
+## Filters
+
+- **By status** — focus on Planned or In Progress to see what's next
+- **By area** — group by FunctionalArea
+- **New since last version** — items added since the previous version snapshot
+
+## Trigger Progress Analysis
+
+Progress updates automatically on each commit if you've run `alucify enable` (it installs a post-commit hook). To manually trigger:
+
+- Use the **Analyze Progress** button on this tab, or
+- Run [`alucify analyze-progress`](../commands/analyze-progress.md) from the terminal
+
+See [Integrations → Git Hooks](../../integrations/git-hooks.md).
+
+## Planning Against Gaps
+
+The top of the tab shows a **Plan** button that launches Claude Code with `/alucify-plan` — ready to plan work against currently-open requirements. See [`alucify plan`](../commands/plan.md).

package/dist/docs/help/cli/ui/settings-tab.md

@@ -0,0 +1,52 @@
+---
+order: 9
+title: "Settings Tab"
+description: "The Settings tab in the web UI — authentication, notifications, telemetry."
+---
+
+# Settings Tab
+
+The Settings tab is where you manage authentication, notification preferences, telemetry, and other options that apply to the web UI and the desktop app.
+
+## Authentication
+
+- **Current mode** — Claude Code subscription or API Key (see [Authentication Modes](../../concepts/authentication-modes.md))
+- **Switch mode** — change between them
+- **Sign in / Sign out** (OAuth mode) — manage your session
+- **API key** (API Key mode) — paste, update, or clear your key
+
+## Workspace (Desktop only)
+
+- **Current workspace** — path to the project folder
+- **Switch workspace** — opens the file picker
+- **Reset workspace** — archive analysis and start fresh
+
+## Notifications
+
+- **OS notifications** — toggle native notifications on/off (see [Notifications](../../desktop/notifications.md))
+- **Sound** (if OS-supported) — play a sound on completion
+
+## Analysis Preferences
+
+- **Default analysis mode** — Speed / Balanced / Quality ([Analysis Modes](../../concepts/analysis-modes.md))
+- **Auto-trigger spec analysis on artifact upload** — when you add a spec, analyze immediately
+
+## Integrations
+
+- **MCP Server** — enable or disable the Claude Code integration. See [Claude Code Integration](../../integrations/claude-code.md).
+- **Git hooks** — status of pre-commit and post-commit hooks. See [Git Hooks](../../integrations/git-hooks.md).
+
+## Telemetry
+
+- **Anonymous usage telemetry** — toggle on/off. When on, Alucify sends anonymous usage events (no code, no specs, no credentials). See [Telemetry](../../vscode/settings/telemetry.md) for what's collected.
+
+## Advanced
+
+- **Show advanced features** — reveal hidden options (version switching, reset analysis, etc.)
+- **Developer mode** — enables developer panels and detailed logs
+
+## About
+
+- Alucify version
+- Server status
+- Link to send feedback

package/dist/docs/help/cli/ui/tech-debt-tab.md

@@ -0,0 +1,29 @@
+---
+order: 4
+title: "Tech Debt Tab"
+description: "The Tech Debt Analysis tab in the web UI — structural health details."
+---
+
+# Tech Debt Tab
+
+The Tech Debt tab surfaces architectural health signals: how coupled your code is, where complexity lives, and which packages are outdated.
+
+For what each metric means, see [Tech Debt Analysis](../../concepts/tech-debt-analysis.md).
+
+## Layout
+
+- **Architecture Health Score** at the top (0–100 with letter grade)
+- **Four banner metrics**: Change Scope, Structural Risk, Debt Trend, plus a summary card
+- **Six detail tabs**: Remediation, Change Scope, Structural Risk, Debt Trend, Complexity, Outdated Packages
+
+## Interacting with Hotspots
+
+Click any component or file name in the tab to open it in your editor (browser limits this to opening a local file URL — your OS handles the handoff). In the Desktop app, clicking opens the file in your default editor.
+
+## Generating Tech Debt Analysis
+
+Tech Debt Analysis runs automatically during code analysis in Balanced and Quality modes. Speed mode doesn't produce tech debt data — if you only ran Speed, this tab will be empty until you re-run in a deeper mode.
+
+## Refreshing
+
+The data on this tab comes from the most recent code analysis. To refresh, re-run Analyze Code from the [Dashboard](dashboard.md) or the [Code Analysis Tab](code-analysis-tab.md).

package/dist/docs/help/cli/ui/token-usage-tab.md

@@ -0,0 +1,46 @@
+---
+order: 8
+title: "Token Usage Tab"
+description: "The Token Usage tab in the web UI — spend tracking by source, model, and session."
+---
+
+# Token Usage Tab
+
+The Token Usage tab shows your Claude token consumption across Alucify workflows and Claude Code sessions.
+
+For what the different token types mean, see [Token Usage](../../concepts/token-usage.md).
+
+## Header Strip
+
+A compact strip at the top of the tab (and visible on every page header in the web UI) shows:
+
+- **Total tokens** — lifetime consumption
+- **This week** — last 7 days, with a delta vs. your daily average
+- **Today** — today's usage, with a delta vs. average
+- **Sessions** — number of distinct Claude Code or Alucify sessions
+
+## Three Sub-Tabs
+
+### Overview
+A daily chart of token consumption over time. Hover any bar for that day's detail.
+
+### Breakdowns
+Token usage split by different dimensions:
+- **By source** — Alucify workflows vs. Claude Code sessions
+- **By model** — Opus vs. Sonnet vs. Haiku
+- **By workflow** — Code analysis vs. Spec analysis vs. etc.
+- **By agent** — which extractor/analyzer consumed the tokens
+- **By user** — git user emails, if you're on a team
+- **By artifact** — which specs drove the most usage
+- **By phase** — workflow phases
+
+### Activity
+Chronological table of every LLM call. Filter by source, model, date range, or user. Click a row for the full record.
+
+## Data Storage
+
+Token usage is stored as an append-only JSONL log at `.alucify/token-usage/usage.jsonl`. It's safe to commit for team visibility or gitignore for privacy. See [Alucify Directory Structure](../../reference/alucify-directory.md).
+
+## Export
+
+Use the **Export** button to download filtered usage data as CSV or JSON for external analysis or billing reconciliation.

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

@@ -0,0 +1 @@
+{ "title": "Concepts", "order": 2 }

package/dist/docs/help/concepts/ai-coding-risks.md

@@ -0,0 +1,50 @@
+---
+order: 6
+title: "AI Coding Risks"
+description: "What AI Coding Risks are — risk types, severity levels, and what each category means."
+---
+
+# 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.
+
+For UI-specific instructions on viewing and resolving risks, see:
+- VS Code: [AI Coding Risks Panel](../vscode/code-analysis/ai-coding-risks-panel.md)
+- Web UI: [AI Coding Risks Tab](../cli/ui/ai-coding-risks-tab.md)
+
+## 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. See [Blast Radius](blast-radius.md).
+- **Domain Gap** — Missing domain knowledge that an AI agent would need
+- **Duplicate** — The same concept is defined in multiple places
+
+## Risk Status
+
+Risks can have three statuses:
+
+- **Open** — Not yet addressed
+- **Fixed** — Resolved, with details about what was changed and when
+- **Ignored** — Marked as not relevant
+
+## How Risks Are Generated
+
+Risks are produced during spec analysis as the final synthesis step after congruency, coverage, and completeness checks. See [Congruency, Coverage & Completeness](congruency-coverage-completeness.md).

package/dist/docs/help/concepts/ai-readiness.md

@@ -0,0 +1,34 @@
+---
+order: 8
+title: "AI Readiness"
+description: "The composite score that tells you how prepared your project is for AI coding agents."
+---
+
+# AI Readiness
+
+AI Readiness is a 0–100% composite score that tells you how well-prepared your project is for an AI coding agent to work on it effectively. Higher readiness means an AI agent (or a human using one) will make fewer mistakes, need less back-and-forth, and produce implementations that match intent.
+
+## What Goes Into the Score
+
+AI Readiness combines:
+
+- [**Congruency**](congruency-coverage-completeness.md#congruency) — Do specs and code agree?
+- [**Coverage**](congruency-coverage-completeness.md#coverage) — Is most of the code backed by specs?
+- [**Completeness**](congruency-coverage-completeness.md#completeness) — Are specs thorough enough to act on?
+- **Risk density** — How many [AI Coding Risks](ai-coding-risks.md) remain open, weighted by severity?
+- **Architectural health** — Structural debt signals from [Tech Debt Analysis](tech-debt-analysis.md)
+
+## How to Improve Your Score
+
+The single best lever depends on where you're weakest. Each UI shows recommendations ranked by expected impact:
+
+- **Low Coverage** → Add specs for the code areas that have none. Alucify tells you which ones.
+- **Low Congruency** → Resolve conflicts and naming issues between specs and code.
+- **Low Completeness** → Fill out acceptance criteria and data model details in your specs.
+- **High Risk Density** → Work through the AI Coding Risks panel, highest severity first.
+
+## Trend Tracking
+
+Every version snapshot records your AI Readiness score. The sparkline next to the score shows your trend across recent analyses — a quick signal of whether your project is getting more or less ready over time.
+
+See [Versions & Snapshots](versions-and-snapshots.md).

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

@@ -0,0 +1,66 @@
+---
+order: 2
+title: "Analysis Modes"
+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 pick a mode each time you run code analysis or spec analysis, regardless of which UI you're using — CLI (`--mode`), VS Code extension (dropdown), or web app (selector).
+
+## 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
+
+See your UI's docs for where the mode selector lives:
+- **CLI:** [`alucify analyze-code --mode`](../cli/commands/analyze-code.md)
+- **VS Code:** [Running Code Analysis](../vscode/code-analysis/running-code-analysis.md)
+- **Web UI:** [Code Analysis Tab](../cli/ui/code-analysis-tab.md)

package/dist/docs/help/concepts/appgraph.md

@@ -0,0 +1,56 @@
+---
+order: 3
+title: "The AppGraph"
+description: "The structured model of your project that Alucify builds and queries."
+---
+
+# The AppGraph
+
+The AppGraph is Alucify's structured model of your project. It's a graph of **nodes** (things in your project) and **edges** (relationships between them). Everything Alucify does — congruency scoring, coverage analysis, progress tracking, risk detection — operates on the AppGraph.
+
+## Nodes
+
+Each node represents one distinct thing in your project. Common node types:
+
+- **FunctionalArea** — A top-level feature area (e.g., "Authentication", "Payments")
+- **FeatureSpec** — A specific feature or user-facing capability
+- **AcceptanceCriterion** — A testable condition for a feature
+- **Interface** — A UI screen or view
+- **Logic** — Business logic (function, class, or module)
+- **Schema** — Data model (table, type, entity)
+- **Validation** — A test or verification
+
+Each node carries metadata (name, description, source files, status) and grounding evidence that points back to where it came from.
+
+## Edges
+
+Edges describe how nodes relate:
+
+- **parent_of** — Hierarchy (FunctionalArea → FeatureSpec)
+- **implements** — A Logic node implements a FeatureSpec
+- **validates** — A Validation verifies an AcceptanceCriterion
+- **depends_on** — Runtime or code dependency
+- **affects** — Change impact (used for [blast radius](blast-radius.md))
+
+## Baseline vs. Project
+
+Alucify maintains two AppGraphs:
+
+- **Baseline AppGraph** — Built from code analysis alone. Reflects what exists in the codebase.
+- **Project AppGraph** — Built by integrating specs into the baseline. Reflects what *should* exist according to your specs, with implementation status tracked per node.
+
+## Versions
+
+Every analysis creates a new versioned snapshot. You can diff two versions to see what changed, or switch back to a previous version. See [Versions & Snapshots](versions-and-snapshots.md).
+
+## Where It Lives
+
+AppGraph data is stored as JSON in `.alucify/` within your project. See [Alucify Directory Structure](../reference/alucify-directory.md).
+
+## Viewing the Graph
+
+The AppGraph can be browsed visually in the AppGraph Visualizer:
+- VS Code: [AppGraph Visualizer](../vscode/appgraph-visualizer/opening-the-visualizer.md)
+- Web UI: [AppGraph Visualizer Tab](../cli/ui/appgraph-visualizer-tab.md)
+
+Or queried programmatically via the [MCP Server tools](../mcp-server/tools/query.md).

package/dist/docs/help/concepts/artifacts-and-specs.md

@@ -0,0 +1,46 @@
+---
+order: 4
+title: "Artifacts & Specs"
+description: "What counts as a spec artifact, what formats are supported, and how artifacts flow through analysis."
+---
+
+# Artifacts & Specs
+
+A **spec** (or **artifact**) is any document that describes what your project should do: a PRD, architecture doc, design spec, feature epic, acceptance criteria, or even a design screenshot. Alucify reads these and maps them against your code.
+
+## Supported Formats
+
+- **PDF** — Multi-page specs; Alucify extracts relevant pages per analysis chunk
+- **Markdown** (.md) — PRDs, READMEs, design docs
+- **JSON / YAML** — Structured specs, API contracts, config
+- **Images** (.png, .jpg, .gif) — Wireframes, mockups, screenshots (require vision-capable models)
+- **Source files** (.ts, .py, etc.) — Reference implementations used as specifications
+- **Plain text** (.txt)
+
+See [Supported Project Types](../getting-started/supported-project-types.md) for language coverage.
+
+## Artifact Lifecycle
+
+Each artifact moves through three statuses:
+
+1. **Pending** — Added to the project but not yet analyzed
+2. **Preview** — Partial analysis available (mini-AppGraph extracted, not yet integrated)
+3. **Analyzed** (integrated) — Fully merged into the project AppGraph
+
+You can filter your artifact list by status in any UI.
+
+## Where Artifacts Live
+
+Artifacts are stored in `.alucify/artifacts/` in your project. Their extracted AppGraph fragments live in `.alucify/extractions/`. See [Alucify Directory Structure](../reference/alucify-directory.md).
+
+## Generating Specs
+
+You can also have Alucify generate specs for you when you know what you want but need help producing a formal artifact. Generation launches a Claude Code session with project context. See:
+- VS Code: [Generating Specs](../vscode/spec-analysis/generating-specs.md)
+- Web UI: [Artifacts Sidebar](../cli/ui/artifacts-sidebar.md) → Generate
+
+## Adding Artifacts
+
+- CLI: [`alucify add-spec <file>`](../cli/commands/add-spec.md)
+- VS Code: [Adding Specs](../vscode/spec-analysis/adding-specs.md)
+- Web UI: [Artifacts Sidebar](../cli/ui/artifacts-sidebar.md)