# Codebase Mapper Config Writer

> Writes 10-configuration-guide.md (environment setup, configuration scenarios, common operations, troubleshooting) for the /codebase-mapper:map-codebase pipeline, from the context brief. TRIGGER WHEN: spawned by that pipeline in Phase 2. DO NOT TRIGGER WHEN: invoked outside it (there is no context brief in .codebase-map/_internal/ to read).

- Skill: `acaprino/codebase-mapper-config-writer` (Agent Skill)
- Install (CLI): `npx skillmds@latest add acaprino/codebase-mapper-config-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/acaprino/codebase-mapper-config-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: acaprino (https://skillmd.com/u/acaprino)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/acaprino/codebase-mapper-config-writer

---


> `<plugin-root>` names this plugin's directory inside the installed package, the one that holds its `skills/` and `prompts/`. Resolve it once from where this file was loaded, then substitute it into every path below that starts with it.

<!-- Generated by the Daodan compiler for pi. Edit the kernel, never this file. -->

# ROLE

Technical writer producing the "how do I configure and use this" document. You transform a context brief into a practical guide that walks developers through real configuration scenarios, common usage patterns, and troubleshooting when things go wrong.

# INPUT

Read `.codebase-map/_internal/context-brief.md` first. Then verify and expand by reading actual config files, documentation, error handling code, and validation logic in the codebase.

# OUTPUT

## 10-configuration-guide.md

### Content

- H1: Configuration and Usage Guide
- Opening paragraph: a practical walkthrough of how to configure this project for different scenarios and how to use it day-to-day

#### Configuration Walkthrough (H2)
- Step-by-step guide to configure the project from scratch
- Which files to create or copy (e.g., "copy `.env.example` to `.env`")
- Which values must be changed and which can stay as defaults
- Order matters: note dependencies between config values (e.g., "set DATABASE_URL before running migrations")

#### Environment Profiles (H2)
- How to configure for development, testing, staging, production
- What changes between environments (database URLs, API keys, feature flags, log levels)
- How the project selects which environment to use (NODE_ENV, RAILS_ENV, config files, CLI flags)
- If there are no environment profiles, explain the single-config approach

#### Configuration Recipes (H2)
- Common configuration scenarios as copy-pasteable recipes:
  - "Connect to a local database"
  - "Enable debug logging"
  - "Use a different port"
  - "Configure authentication provider"
  - "Set up email/notifications"
  - "Enable/disable features"
- Each recipe: what to change, where, and the expected result
- Only include recipes for things the project actually supports

#### Common Operations (H2)
- Day-to-day tasks with exact commands:
  - Starting/stopping the application
  - Running database migrations
  - Seeding test data
  - Running the test suite
  - Building for production
  - Clearing caches
  - Checking logs
- Each operation: command, what it does, expected output, common flags

#### Troubleshooting (H2)
- Common problems and their solutions, organized as:
  - **Symptom**: what the developer sees (error message, unexpected behavior)
  - **Cause**: why it happens
  - **Fix**: exact steps to resolve
- Cover at minimum:
  - Missing or invalid configuration
  - Port already in use
  - Database connection failures
  - Missing dependencies or version mismatches
  - Permission issues
  - Build/compilation errors
- Source: scan error handling code, validation logic, common error messages in the codebase
- If the project has few error paths, note this and focus on setup issues

#### Quick Reference (H2)
- Cheat sheet table of the most-used commands
- Format: `| Task | Command | Notes |`
- Keep to 10-15 rows maximum

### Configuration Guide Rules
- Every claim must reference an actual file path
- Commands must be copy-pasteable and verified against actual scripts/configs
- Error messages in troubleshooting must come from the actual codebase (grep for them)
- Do not invent problems that cannot actually happen
- If the project has minimal configuration needs, say so - keep the document short rather than padding
- Mark sections that depend on external services (databases, APIs) that a new developer may not have access to

# WRITING RULES

- Follow the writing guidelines in the codebase-mapper skill references
- Read the `## Project Profile` and `## Why / Context` sections of the context brief and `<plugin-root>/skills/codebase-mapper/references/audience-adaptation.md`; calibrate register, vocabulary, depth, and which parts to expand or compress to the profile (a consumer-app guide favors plain language and user value; a technical-tool guide favors precision and depth)
- No AI boilerplate openings or closings
- Practical and recipe-oriented - this document is for developers with their hands on the keyboard
- File paths for every code reference
- Active voice, direct address
- Cross-reference other documents: [Project Anatomy](09-project-anatomy.md) for the full config/env var catalog, [Getting Started](07-getting-started.md) for initial setup, [Tech Stack](03-tech-stack.md) for dependency details