---
stage: overview
requires: quickstart
outputs: "{wiki_dir}/overview.md"
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 4: Codebase Overview

Generate a comprehensive overview combining business context with architecture summary and component listing.

## Prerequisites

- Stage 02 completed with business-context.json generated
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Business context populated from Stage 02

## Critical Rules

| Rule | Action |
|------|--------|
| Business context required | **MUST** verify populated before proceeding |
| Component discovery | **MUST** discover at least 1 component or language |
| Mermaid diagrams only | **MUST** use Mermaid syntax for ALL diagrams (no ASCII art) |
| Checkpoint commit | **MUST** commit wiki files at end of this stage |

---

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

## Understand Workflow Cache Integration

Before running discovery, check if the understand workflow has cached module-level understanding:

```text
# Project understanding already recalled via cache enforcement above.
# Additionally check module-level understanding (adjust paths to match project structure):
understand(action="recall", target="src/")
understand(action="recall", target="scripts/")
# IF found AND fresh: Use module summaries to enrich overview
```

**After discovery (Step 3):** Compare your findings with cached project understanding.

- If discovery produces **richer** understanding (more components, patterns, dependencies) -> store back with `understand(action="store", scope="project")`
- If cached understanding is already **equal or better** -> keep existing cache, do not overwrite

---

## Step 1: Verify Previous Stage

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

**Stop if CLI returns error.**

---

## Step 2: Load Business Context

```bash
civyk-hatch deepwiki-update-state show --wiki-dir={wiki_dir}
```

Or read full context: `{wiki_dir}/business-context.json`

**Stop if business_context is empty.**

---

## Step 3: Get Architecture Context

**Load discovered patterns from discovery_cache:**

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

```text
# Components and dependencies
architecture(action="components")
architecture(action="dependencies")
quality(action="circular_deps", level="component")
git(action="hotspots", since="90d", group_by="component", limit=30)

# Code quality indicators
quality(action="dead_code", limit=50)
quality(action="duplicates", source_only=true, similarity_threshold=0.7, limit=30)

# Architecture overview
context(action="task", task="understand codebase architecture", token_budget=3000, prefer_kinds=["class", "function"])

# API entry points
architecture(action="endpoints", limit=200)
```

**MUST search using ALL YOUR discovered patterns:**

```text
# MANDATORY: For EACH suffix in your COMPONENT_SUFFIXES, search with %<SUFFIX>:
# Example if COMPONENT_SUFFIXES = ["Dto", "Service", "Controller", "Validator"]:
search(action="symbols", query="%Dto", kind="class", limit=LIMITS.symbols)
search(action="symbols", query="%Service", kind="class", limit=LIMITS.symbols)
search(action="symbols", query="%Controller", kind="class", limit=LIMITS.symbols)
search(action="symbols", query="%Validator", kind="class", limit=LIMITS.symbols)
# ... continue for ALL suffixes in YOUR discovered COMPONENT_SUFFIXES

# MANDATORY: For EACH prefix in your COMPONENT_PREFIXES, search with <PREFIX>%:
# Example if COMPONENT_PREFIXES = ["Base", "I", "Abstract"]:
search(action="symbols", query="Base%", kind="class", limit=LIMITS.symbols)
search(action="symbols", query="I%", kind="interface", limit=LIMITS.symbols)
search(action="symbols", query="Abstract%", kind="class", limit=LIMITS.symbols)
# ... continue for ALL prefixes in YOUR discovered COMPONENT_PREFIXES
```

**[!] CRITICAL:** The patterns above are examples. You **MUST** use YOUR actual discovered COMPONENT_SUFFIXES and COMPONENT_PREFIXES from enumerate-index output, not these examples.

**Read key files:** README.md for architecture, main entry point for bootstrap sequence.

```text
# [!] MANDATORY: Store MCP discovery summary after gathering architecture context
understand(action="store",
  scope="module",
  target="discovery/architecture",
  purpose="Architecture discovery results from MCP analysis",
  importance="high",
  key_points=["<component_count> components", "<api_endpoint_count> endpoints", "<circular_deps_if_any>"],
  gotchas=["<dead_code_areas>", "<duplicate_code_hotspots>", "<hotspot_files>"],
  analysis="<components>: <component_list>. <dependencies>: <dep_graph_summary>. <patterns>: <suffix_patterns>, <prefix_patterns>. <quality_issues>: <dead_code>, <duplicates>."
)
```

---

## Step 4: Analyze Tech Stack

```text
files(pattern="**/*", include_stats=true, limit=50)
```

Identify: primary languages, frameworks, database type, key dependencies.

---

## Step 5: Generate Overview

Write to `{wiki_dir}/overview.md` using this template:

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

**Fill placeholders with:**

- Business context (from Stage 02): project_name, features, entities, rules, glossary
- MCP discovery: tech stack, components, architecture
- All diagrams MUST use Mermaid syntax

---

## Step 6: Store Project Understanding (AI Context Cache)

After analyzing the codebase architecture, persist understanding for future stages:

```text
# Store project-level understanding for cross-session recall
understand(action="store",
  scope="project",
  target="project",
  purpose="<1-2 sentence summary of what this codebase does>",
  importance="critical",
  key_points=[
    "<Primary language and framework>",
    "<Main architectural pattern>",
    "<Key components discovered>",
    "<Notable patterns or conventions>"
  ],
  gotchas=[
    "<Any architectural concerns found>",
    "<Circular dependencies if any>",
    "<Dead code areas if significant>"
  ],
  analysis="<architecture_summary>: <layers>, <patterns>. <data_flow>. <key_decisions>.",
  related_to=["<main_entry_points>", "<key_config_files>"]
)
```

**Benefits:** Later stages (05-16) can `understand(action="recall", target="project")` to quickly access this analysis without re-running discovery.

---

## Step 7: Complete Stage

```bash
civyk-hatch deepwiki-update-state stage --stage=04-overview --status=completed --artifacts="{wiki_dir}/overview.md" --wiki-dir={wiki_dir}
```

---

## Step 8: Checkpoint Commit

```bash
git add {wiki_dir}/
git commit -m "docs(wiki): add overview and quickstart documentation

Generated via deepwiki stages 01-04:
- {wiki_dir}/quickstart.md
- {wiki_dir}/overview.md
- {wiki_dir}/business-context.json

[*] Generated with Civyk Hatch DeepWiki"
```

Verify with `git status`. **Do not push yet.**

---

## Output Format

```text
===========================================================
  STAGE COMPLETE: 04-overview

  Summary:
    - Generated: {wiki_dir}/overview.md
    - Features: {count} documented
    - Components: {count} documented
    - Tech stack: {languages} / {frameworks}

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

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| Missing business context | Re-run stage 02 |
| No components detected | Use directory structure as component boundaries |
| Large codebase (>1000 files) | Focus on top-level components only |
| Monorepo | Document each package as separate component |

---

## Next Stage

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