---
stage: summary
requires: enrichment
outputs: "{wiki_dir}/README.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 16: Summary & Finalization

Complete wiki generation with main README, navigation index, quality metrics, and workflow completion.

## Prerequisites

- Stage 15 completed with enrichment applied
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Discovery cache loaded: PROJECT_SIZE, PRIMARY_LANGUAGE

## Critical Rules

| Rule | Action |
|------|--------|
| Enrichment required | **MUST** verify enrichment stage completed |
| Protect custom | **NEVER** overwrite {wiki_dir}/custom/ directory |
| Quality metrics | **MUST** calculate and report quality metrics |
| Generate README | **MUST** generate {wiki_dir}/README.md with index |
| Final commit | **MUST** commit all wiki files at end |

---

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

## Step 1: Verify Previous Stage

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

---

## Step 2: List Generated Files

Verify all expected wiki files were generated:

```text
{wiki_dir}/
  README.md           (this stage creates)
  quickstart.md
  overview.md
  architecture/       (diagrams, decisions)
  flows/              (README + flow files)
  components/         (README + component files)
  api.md
  models.md
  configuration/      (README + config files)
  dependencies.md
  errors.md
  examples.md
```

---

## Step 3: Get Final Statistics

```text
status(action="check")
architecture(action="components")
```

---

## Step 4: Calculate Quality Metrics

```text
QUALITY_METRICS = {
  coverage: components_documented / components_total,
  cross_references: internal_links_count,
  completeness: stages_completed / 15,
  business_context: features_documented > 0
}

QUALITY_SCORE = (coverage * 30) + (xref * 25) + (completeness * 25) + (business * 20)
# Score 0-100, Rating: 90+ Excellent, 70-89 Good, 50-69 Fair, <50 Needs Work
```

---

## Step 5: Generate README

Write `{wiki_dir}/README.md` with:

```markdown
# <<PROJECT_NAME>> Documentation

> Auto-generated via [Civyk Hatch DeepWiki](https://github.com/civyk-official/civyk-hatch)

## Quick Navigation
- [Quick Start](quickstart.md)
- [Overview](overview.md)
- [Components](components/README.md)

## Documentation Index

### Core Documentation
| Document | Description |
|----------|-------------|
| [Quick Start](quickstart.md) | Installation and first steps |
| [Overview](overview.md) | Codebase architecture |
| [Diagrams](architecture/diagrams.md) | Visual architecture |
| [Flows](flows/README.md) | Request and data flows |

### Reference Documentation
| Document | Description |
|----------|-------------|
| [API Reference](api.md) | Endpoints and usage |
| [Data Models](models.md) | Entity definitions |
| [Configuration](configuration/README.md) | Config options |
| [Dependencies](dependencies.md) | Deps and relationships |

### Advanced Documentation
| Document | Description |
|----------|-------------|
| [Decisions](architecture/decisions.md) | Arch decisions |
| [Errors](errors.md) | Error handling |
| [Examples](examples.md) | Usage examples |

## Statistics
- Files Indexed: <<FILE_COUNT>>
- Components: <<COMPONENT_COUNT>>
- Generated: <<TIMESTAMP>>

## Custom Documentation
Add custom docs in `{wiki_dir}/custom/` - preserved during regeneration.
```

---

## Step 6: Mark Stage Complete

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

---

## Step 7: Mark Workflow Complete

```bash
civyk-hatch deepwiki-update-state complete
```

---

## Step 8: Final Commit

```bash
git add {wiki_dir}/
git commit -m "docs(wiki): complete deepwiki documentation generation

Generated complete wiki documentation:
- {wiki_dir}/README.md (main index)
- {wiki_dir}/quickstart.md, overview.md
- {wiki_dir}/architecture/, flows/, components/
- {wiki_dir}/api.md, models.md, configuration/
- {wiki_dir}/dependencies.md, errors.md, examples.md

Quality Score: {score}/100

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

---

## Output Format

```text
+==============================================================+
|                    DeepWiki Generation Complete              |
+==============================================================+
|  Files Generated: {count}                                    |
|  Components documented: {count}                              |
|  Quality Score: {score}/100 ({rating})                       |
|                                                              |
|  Next Steps:                                                 |
|    1. Review generated documentation                         |
|    2. Add custom docs to {wiki_dir}/custom/ if needed        |
|    3. Push to repository                                     |
+==============================================================+

WORKFLOW_COMPLETE:DEEPWIKI
```

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| Partial generation | Update README for available sections |
| Previous wiki exists | Preserve {wiki_dir}/custom/ |
| Large wiki (>50 files) | Suggest enabling search |

---

## Workflow Complete

Run `civyk-hatch deepwiki-update-state show` to view final state with all artifacts tracked.
