---
stage: examples
requires: errors
outputs: "{wiki_dir}/examples.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 14: Usage Examples

Generate usage examples and code snippets for common operations and integrations.

## Prerequisites

- Stage 13 completed with errors.md generated
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Discovery cache loaded: LIMITS, TEST_PATTERNS

## Critical Rules

| Rule | Action |
|------|--------|
| Errors required | **MUST** verify {wiki_dir}/errors.md exists |
| Search existing | **MUST** search for existing examples before creating |
| Complete examples | **NEVER** generate broken or incomplete code |
| Include imports | **SHOULD** include import statements in snippets |

---

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

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

---

## Step 1: Verify Previous Stage

```bash
civyk-hatch deepwiki-update-state verify-stage --stage=14-examples --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: TEST_PATTERNS = discovery_cache.file_patterns.test_patterns
```

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

| MCP Call | CLI Equivalent |
|----------|----------------|
| `files(pattern="**/examples/**", limit=100)` | `civyk-repoix query files --pattern "**/examples/**" --limit 100` |
| `tests(action="for_file", path="...", include_indirect=true)` | `civyk-repoix query tests --action for_file --path "..." --include-indirect true` |
| `architecture(action="endpoints", limit=200)` | `civyk-repoix query architecture --action endpoints --limit 200` |

---

## Step 3: Find Existing Examples

```text
# Example directories and files
files(pattern="**/examples/**", include_stats=true, limit=100)
files(pattern="**/*example*", include_stats=true, limit=50)
files(pattern="**/*demo*", include_stats=true, limit=50)
files(pattern="**/*sample*", include_stats=true, limit=50)

# Documentation with examples
files(pattern="**/docs/**/*.md", limit=50)
search(action="code", query="```|example|usage|how to", is_regex=true, file_pattern="*.md", limit=50)

# Notebooks
files(pattern="**/*.ipynb", limit=30)
```

---

## Step 4: Find Test Cases as Examples

```text
# Test files
files(pattern="**/test*/**", include_stats=true, limit=100)
files(pattern="**/*.test.*", include_stats=true, limit=100)
files(pattern="**/*.spec.*", include_stats=true, limit=100)
files(pattern="**/test_*.py", include_stats=true, limit=100)

# Integration tests (best examples)
files(pattern="**/integration/**", limit=50)
files(pattern="**/e2e/**", limit=50)

# Test mapping
tests(action="for_file", path="<source_file>", include_indirect=true)
tests(action="code_for_test", path="<test_file>")

# Related test files
file(action="related", path="<main_component>", relationship_types=["test"])
```

---

## Step 5: Find Entry Points

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

# Main functions
search(action="code", query="if __name__|func main|public static void main", is_regex=true, limit=50)

# CLI commands
search(action="code", query="@click.command|@click.group|argparse", is_regex=true, limit=50)

# Get file symbols
file(action="symbols", path="<main_file>", kinds=["function", "class", "method"])
symbol(action="detail", fqn="<class_fqn>")
symbol(action="callers", fqn="<function_fqn>", depth=2)
```

---

## Step 6: Extract Examples

For each example file:

```text
# Read example and test files
# Read file: <example_file>
# -> Extract runnable code snippets
# -> Note input/output patterns
# -> Identify configuration needed

# Read file: <test_file>
# -> Extract setup code
# -> Extract assertions (expected behavior)

file(action="imports", path="<example_file>")
symbol(action="similar", fqn="<example_function>", similarity_threshold=0.5, limit=20)
```

---

## Step 7: Generate Documentation

**[!] CRITICAL OUTPUT FILE: You MUST write to `{wiki_dir}/examples.md`**

- Do NOT create `usage.md`, `samples.md`, `demos.md`, or any other filename
- The output MUST be exactly: `{wiki_dir}/examples.md`

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

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

**Fill placeholders with:** Examples summary by category, basic usage example, common operations code snippets, Mermaid workflow diagrams, test examples, SDK usage (if applicable).

---

## Step 8: Complete Stage

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

---

## Step 9: Checkpoint Commit

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

Generated via deepwiki stages 05-14:
- {wiki_dir}/architecture/
- {wiki_dir}/flows/
- {wiki_dir}/components/
- {wiki_dir}/api.md, models.md, configuration/
- {wiki_dir}/dependencies.md, errors.md, examples.md

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

---

## Output Format

```text
===========================================================
  STAGE COMPLETE: 14-examples

  Generated: {wiki_dir}/examples.md
  Examples: {count}
  Code snippets: {count}

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

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| No examples directory | Extract from tests |
| Tests as primary examples | Reference test files |
| Interactive examples | Include notebook/REPL |
| No clear entry points | Base on public API |

---

## Next Stage

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