---
stage: config
requires: components
outputs: "{wiki_dir}/configuration/"
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 10: Configuration Guide

Generate configuration documentation covering config files, environment variables, and setup options.

## Prerequisites

- Stage 09 completed (or skipped if no models)
- Mode: `{REPOIX_MODE}` (if "cli", convert MCP calls per AGENTS.md)
- Discovery cache loaded: LIMITS

## Critical Rules

| Rule | Action |
|------|--------|
| Models required | **MUST** verify {wiki_dir}/models.md exists (or stage skipped) |
| Search before skip | **MUST** search for config files before deciding to skip |
| No secrets | **NEVER** document actual secret values |
| Multi-file output | **MUST** create configuration/ directory with separate files |
| Skip if none | **MAY** skip if no configuration found |

---

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

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

---

## Step 1: Verify Previous Stage

```bash
civyk-hatch deepwiki-update-state verify-stage --stage=10-config --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: PRIMARY_LANGUAGE = discovery_cache.file_patterns.languages.primary
```

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

| MCP Call | CLI Equivalent |
|----------|----------------|
| `files(pattern="**/*.config.*", limit=100)` | `civyk-repoix query files --pattern "**/*.config.*" --limit 100` |
| `search(action="code", query="process.env", limit=100)` | `civyk-repoix query search --action code --query "process.env" --limit 100` |
| `search(action="symbols", query="%Config", kind="class")` | `civyk-repoix query search --action symbols --query "%Config" --kind class` |

---

## Step 3: Find Configuration Files

```text
# Generic config patterns
files(pattern="**/*.config.*", limit=100)
files(pattern="**/config/**", limit=100)
files(pattern="**/settings.*", limit=50)
files(pattern="**/.env*", limit=50)

# Language-specific configs
files(pattern="**/appsettings*.json", limit=20)
files(pattern="**/application*.yml", limit=20)
files(pattern="**/pyproject.toml", limit=10)
files(pattern="**/tsconfig*.json", limit=20)

# Docker/Infrastructure
files(pattern="**/docker-compose*.yml", limit=20)
files(pattern="**/Dockerfile*", limit=20)
files(pattern="**/terraform/**", limit=50)
files(pattern="**/k8s/**", limit=50)
```

---

## Step 4: Find Config Usage

```text
# Environment variable access
search(action="code", query="process.env", limit=100)
search(action="code", query="os.environ|os.getenv", is_regex=true, limit=100)
search(action="code", query="Environment.GetEnvironmentVariable", limit=50)

# Config schemas
search(action="symbols", query="%Config", kind="class", limit=50)
search(action="symbols", query="%Settings", kind="class", limit=50)
search(action="code", query="Pydantic|BaseSettings|Zod|z.object", is_regex=true, limit=50)

# Read config files
# Read file: <config_file>
# -> Extract all config keys
# -> Note default values
# -> Identify required vs optional

# Find validation
file(action="related", path="<config_file>", relationship_types=["test"])
```

---

## Step 5: Write Output

**Required files:**

| File | Content |
|------|---------|
| `{wiki_dir}/configuration/README.md` | Index with quick reference for critical vars |
| `{wiki_dir}/configuration/{area}.md` | Individual config area (environment, database, security) |

**Each config file uses this template:**

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

**Fill placeholders with:** Area title, purpose, config keys/variables table, default values, required vs optional indicators, environment-specific variations, examples.

---

## Step 6: Verification Gate (MANDATORY)

**[STOP: VERIFY_MULTI_FILE_OUTPUT]**

Before completing this stage, you MUST verify:

1. [ ] `{wiki_dir}/configuration/README.md` exists (index file)
2. [ ] At least 1 individual config area file exists: `{wiki_dir}/configuration/{area}.md`
3. [ ] Each config file contains: purpose, config keys table, examples

**FAILURE CONDITIONS:**

- If only README.md exists: FAIL - You MUST create individual area files (e.g., `environment.md`, `database.md`)
- If config files have no config key table: FAIL - Each file must list actual config variables

**Count files in directory:**

```bash
ls {wiki_dir}/configuration/
```

Expected: README.md + at least 1 area file (e.g., `environment.md`, `database.md`, `security.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=10-config --status=completed --artifacts="{wiki_dir}/configuration/README.md,{wiki_dir}/configuration/{area-1}.md,..." --wiki-dir={wiki_dir}
```

---

## Output Format

```text
===========================================================
  STAGE COMPLETE: 10-config

  Generated: {wiki_dir}/configuration/
  Config files: {count}
  Environment variables: {count}

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

---

## Edge Cases

| Scenario | Action |
|----------|--------|
| No config files | Document CLI arguments instead |
| Secret management detected | Document retrieval patterns, not values |
| Environment-only config | Focus on .env.example documentation |
| Config schema available | Extract field definitions from schema |

---

## Next Stage

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