---
stage: components
requires: flows
outputs: "{wiki_dir}/components/"
version: 2.1.0
estimated_tokens: 2000

guardrails:
  enforcement: active
  allowed_tools:
    - civyk-repoix
    - Read
    - Grep
    - Glob
    - Bash
  forbidden_actions:
    - "Delete any files"
    - "Modify any source files"
  read_only: true
---
# Stage 7: Component Documentation

Generate detailed documentation for each architectural component including purpose, public API, dependencies, and usage.

## Prerequisites

- Stage 06 completed with flows documented
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Discovery cache loaded: LIMITS, COMPONENT_SUFFIXES, COMPONENT_PREFIXES

## Critical Rules

| Rule | Action |
|------|--------|
| Flows required | **MUST** verify {wiki_dir}/flows/README.md exists |
| Component discovery | **MUST** discover at least 1 component |
| Dependencies | **MUST** document cross-component dependencies |
| Mermaid only | **MUST** use Mermaid syntax (no ASCII diagrams) |
| Multi-file output | **MUST** create components/ directory with separate files |

**Anti-pattern (DO NOT):**

```text
+-------------+     +-------------+
|  Component  |---->|   Service   |
+-------------+     +-------------+
```

**Correct pattern:**

```mermaid
classDiagram
    Component --> Service
    Service --> Repository
```

---

## Step 1: Verify Previous Stage

```bash
civyk-hatch deepwiki-update-state verify-stage --stage=07-components --wiki-dir={wiki_dir}
```

---

## Step 2: Load Discovery Cache

```bash
civyk-hatch deepwiki-update-state show --wiki-dir={wiki_dir}
# Extract: LIMITS = discovery_cache.project_size.limits
# Extract: COMPONENT_SUFFIXES = discovery_cache.file_patterns.component_patterns.suffixes
# Extract: COMPONENT_PREFIXES = discovery_cache.file_patterns.component_patterns.prefixes
```

**MCP/CLI conversion (if REPOIX_MODE == "cli"):**

| MCP Call | CLI Equivalent |
|----------|----------------|
| `architecture(action="components")` | `civyk-repoix query architecture --action components` |
| `file(action="symbols", path="...", kinds=["class"])` | `civyk-repoix query file --action symbols --path "..." --kinds "class"` |
| `symbol(action="hierarchy", fqn="...", direction="both")` | `civyk-repoix query symbol --action hierarchy --fqn "..." --direction both` |

---

{{include:ai-cache-enforcement.md}}

{{include:understand-fast-path.md}}

---

## Step 3: Discover Components

```text
# Get all components
architecture(action="components")
architecture(action="dependencies")
architecture(action="endpoints", limit=200)

# Architecture context
context(action="task", task="understand all architectural components", token_budget=2000)

# Development activity
git(action="hotspots", since="90d", group_by="component", limit=50)
git(action="changes", since="30d", include_symbols=true, limit=100)
```

---

## Step 4: Document Each Component

For each component:

```text
# Context and dependencies
context(action="task", task="document <component_name>", component_filter="<component_name>", token_budget=2000)
architecture(action="dependencies", component="<component_name>")

# Files and symbols
files(path="<component_path>", include_stats=true, limit=100)
file(action="symbols", path="<file>", include_private=true)
file(action="imports", path="<file>")

# Type hierarchy and patterns
symbol(action="hierarchy", fqn="<class_fqn>", direction="both", depth=5)
symbol(action="similar", fqn="<class_fqn>", similarity_threshold=0.5, limit=20)
quality(action="duplicates", component="<component_name>", source_only=true, limit=20)

# Usage analysis
symbol(action="references", fqn="<main_class_fqn>")
symbol(action="callers", fqn="<key_method_fqn>", depth=3)
quality(action="impact", fqn="<main_class_fqn>", depth=3, include_tests=true)
tests(action="for_file", path="<component_file>", include_indirect=true)

# Read key files
# Read file: <main_file>
# Read file: <test_file>

# Store module-level understanding
understand(action="store",
  scope="module",
  target="<component_path>",
  purpose="<component purpose and responsibilities>",
  importance="high",
  key_points=["<main classes>", "<public API>", "<key patterns>"],
  gotchas=["<edge cases>", "<known issues>"],
  analysis="<component_architecture>: <layers>, <patterns>. <public_api>: <key_methods>. <dependencies>: <imports>.",
  related_to=["<dependent_components>"]
)
```

Extract: purpose, public API, configuration, error handling, usage examples.

---

## Step 5: Write Output

**Required files:**

| File | Content |
|------|---------|
| `{wiki_dir}/components/README.md` | Index with component overview and dependency diagram |
| `{wiki_dir}/components/{component-slug}.md` | Individual component (one per component) |

**Each component file uses this template:**

{{include:wiki/component-template.md}}

**Fill placeholders with:** Component name, summary, purpose, responsibilities, public API (classes, functions, interfaces), dependencies, usage examples, related components.

---

## Step 6: Verification Gate (MANDATORY)

**[STOP: VERIFY_MULTI_FILE_OUTPUT]**

Before completing this stage, you MUST verify:

1. [ ] `{wiki_dir}/components/README.md` exists (index file)
2. [ ] At least 1 individual component file exists: `{wiki_dir}/components/{component-slug}.md`
3. [ ] Each component file contains: summary, public API, dependencies, examples

**FAILURE CONDITIONS:**

- If only README.md exists: FAIL - You MUST create individual component files
- If component files have no content: FAIL - Each file must have real documentation

**Count files in directory:**

```bash
ls {wiki_dir}/components/
```

Expected: README.md + at least 1 component file (e.g., `handlers.md`, `services.md`)

**IF verification fails:** Go back to Step 5 and create the missing individual files.

---

## Step 7: Complete Stage

```bash
civyk-hatch deepwiki-update-state stage --stage=07-components --status=completed --artifacts="{wiki_dir}/components/README.md,{wiki_dir}/components/{component-1}.md,..." --wiki-dir={wiki_dir}
```

---

## Output Format

```text
===========================================================
  STAGE COMPLETE: 07-components

  Generated: {wiki_dir}/components/
  Components: {count}
  Public symbols: {count}

  Checkpoint: P1 prompts complete
    - {wiki_dir}/quickstart.md
    - {wiki_dir}/overview.md
    - {wiki_dir}/architecture/diagrams.md
    - {wiki_dir}/flows/
    - {wiki_dir}/components/

  Next: Run {next_command}
===========================================================
```

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| Single component | Document as monolithic structure |
| No public exports | Document internal structure |
| Component filter active | Regenerate only specified component |
| Too many symbols (>100) | Focus on main exports only |

---

## Next Stage

Run `{next_command}` - CLI auto-detects current stage and emits next prompt.
