sdd-forge 0.1.0-alpha.23 → 0.1.0-alpha.25

package/README.md

@@ -1,21 +1,21 @@
-# <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+# {{data: project.name("")}}sdd-forge{{/data}}
 
 [![npm version](https://img.shields.io/npm/v/sdd-forge.svg)](https://www.npmjs.com/package/sdd-forge)
 
-> **Alpha:** This tool is currently in alpha. APIs, command structures, and configuration formats may change without notice. Not recommended for production use.
+> **Alpha:** This tool is currently in alpha. APIs, command structure, and configuration formats may change without notice. Not recommended for production use.
 
-**A CLI tool that automatically generates and maintains project documentation using source code analysis + AI.**
+**A CLI tool that automatically generates and maintains project documentation via source code analysis + AI.**
 
 Statically analyzes your codebase and combines templates with AI to auto-generate `docs/`.
-Spec-Driven Development (SDD) workflows further automate documentation updates when adding features or making changes.
+The Spec-Driven Development (SDD) workflow also automates documentation updates when adding features or making changes.
 
 ## Features
 
 - **Zero dependencies** — Runs on Node.js 18+ only. No npm packages required
 - **Automatic source analysis** — Statically analyzes controllers, models, routes, and config files to extract structural data
 - **AI document generation** — AI automatically expands `{{text}}` directives in templates
-- **Template inheritance** — Customizable via 4-layer inheritance: base → arch → preset → project-local
-- **SDD workflow** — Manage the spec → gate → implement → forge → review cycle with commands
+- **Template inheritance** — Four-layer inheritance (base → arch → preset → project-local) for full customization
+- **SDD workflow** — Manage the spec → gate → implement → forge → review development cycle with commands
 - **Multi-language support** — Auto-generate documentation in multiple languages via translate / generate modes
 - **AI agent integration** — Supports Claude Code (skills) and Codex CLI
 - **Multi-preset** — Supports Node.js CLI / CakePHP2 / Laravel / Symfony
@@ -26,26 +26,26 @@ Spec-Driven Development (SDD) workflows further automate documentation updates w
 
 <pre>
 # npm
-npm install -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+npm install -g {{data: project.name("")}}sdd-forge{{/data}}
 
 # yarn
-yarn global add <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+yarn global add {{data: project.name("")}}sdd-forge{{/data}}
 
 # pnpm
-pnpm add -g <!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} -->
+pnpm add -g {{data: project.name("")}}sdd-forge{{/data}}
 </pre>
 
 ### Setup & Document Generation
 
 <pre>
 # 1. Register your project (interactive wizard)
-<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> setup
+{{data: project.name("")}}sdd-forge{{/data}} setup
 
-# 2. Generate all documentation at once (scan → init → data → text → readme → agents → translate)
-<!-- {{data: project.name("")}} -->sdd-forge<!-- {{/data}} --> build
+# 2. Generate all documentation (scan → init → data → text → readme → agents → translate)
+{{data: project.name("")}}sdd-forge{{/data}} build
 </pre>
 
-This alone generates `docs/` and `README.md`.
+This generates `docs/` and `README.md` in one step.
 
 ## Commands
 
@@ -62,7 +62,7 @@ This alone generates `docs/` and `README.md`.
 | `readme` | Auto-generate `README.md` from `docs/` |
 | `forge` | Iteratively improve documentation with AI |
 | `review` | Check documentation quality |
-| `translate` | Multi-language translation (default language → other languages) |
+| `translate` | Multi-language translation (default language → others) |
 | `upgrade` | Update preset templates to the latest version |
 
 ### SDD Workflow
@@ -70,7 +70,7 @@ This alone generates `docs/` and `README.md`.
 | Command | Description |
 |---|---|
 | `spec` | Create a spec document + feature branch |
-| `gate` | Pre-implementation check for spec |
+| `gate` | Pre-implementation check for the spec |
 | `flow` | Automatically run the SDD workflow |
 | `changelog` | Generate change history from specs/ |
 | `agents` | Update AGENTS.md |
@@ -81,16 +81,16 @@ This alone generates `docs/` and `README.md`.
 |---|---|
 | `default` | Set the default project |
 | `presets` | List available presets |
-| `help` | Show command list |
+| `help` | Display command list |
 
 ## SDD Workflow
 
 The feature addition / change flow:
 
 ```
-  spec          Create a spec (feature branch + spec.md)
+  spec          Create spec (feature branch + spec.md)
     ↓
-  gate          Spec gate check (PASS when no open issues)
+  gate          Spec gate check (PASS when no open questions)
     ↓
   implement     Write code after gate PASS
     ↓
@@ -121,7 +121,7 @@ $sdd-flow-close   — Finish with forge → review → commit → merge
 
 ## Configuration
 
-Running `sdd-forge setup` generates `.sdd-forge/config.json`.
+`sdd-forge setup` generates `.sdd-forge/config.json`.
 
 ```jsonc
 {
@@ -149,9 +149,9 @@ You can add project-specific templates and data sources:
 <!-- {{data: docs.chapters("Chapter|Overview")}} -->
 | Chapter | Overview |
 | --- | --- |
-| [01. System Overview](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/01_overview.md) |  |
-| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) |  |
-| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) |  |
+| [01. System Overview](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/01_overview.md) | This chapter provides a structural overview of sdd-forge, a Node.js CLI tool that automates documentation generation … |
+| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) | This chapter covers all 18 subcommands available in `sdd-forge`, organized into documentation generation commands (ro… |
+| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) | This chapter covers all configuration files used by sdd-forge, the full range of options available in `.sdd-forge/con… |
 | [04. Internal Design](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/04_internal_design.md) |  |
 <!-- {{/data}} -->
 

package/docs/01_overview.md

@@ -4,20 +4,112 @@
 
 <!-- {{text: Write a 1-2 sentence overview of this chapter. Include the project's architecture and whether it integrates with external systems.}} -->
 
+This chapter provides a structural overview of sdd-forge, a Node.js CLI tool that automates documentation generation through source code analysis and drives feature development via a Spec-Driven Development (SDD) workflow. The tool follows a three-layer command dispatch architecture and integrates with external AI agents (such as Claude CLI) to generate and refine documentation text.
+
 ## Content
 
 ### Architecture Diagram
 
 <!-- {{text: Generate a mermaid flowchart showing the project architecture. Include data flows between major components. Output only the mermaid code block.}} -->
 
+```mermaid
+flowchart TD
+    User["User (CLI)"]
+
+    subgraph Entry["Entry Layer"]
+        SDF["sdd-forge.js\n(Entry Point)"]
+    end
+
+    subgraph Dispatch["Dispatcher Layer"]
+        DOCS["docs.js"]
+        SPEC["spec.js"]
+        FLOW["flow.js"]
+        HELP["help.js"]
+    end
+
+    subgraph Commands["Command Layer"]
+        SCAN["scan"]
+        DATA["data"]
+        TEXT["text"]
+        FORGE["forge"]
+        REVIEW["review"]
+        SPEC_INIT["spec init"]
+        GATE["gate"]
+        OTHER["readme / agents / changelog / …"]
+    end
+
+    subgraph Lib["Core Libraries"]
+        AGENT["agent.js\n(AI Agent Caller)"]
+        CONFIG["config.js\n(Config & Paths)"]
+        SCANNER["scanner.js\n(Source Analyzer)"]
+        PARSER["directive-parser.js"]
+    end
+
+    subgraph Storage["File System"]
+        SRC["Source Code\n(project root)"]
+        ANALYSIS[".sdd-forge/output/\nanalysis.json / summary.json"]
+        DOCFILES["docs/*.md\n(generated docs)"]
+        SPECS["specs/NNN-xxx/spec.md"]
+        CFGFILE[".sdd-forge/config.json"]
+    end
+
+    AI["External AI Agent\n(e.g. Claude CLI)"]
+
+    User --> SDF
+    SDF --> DOCS & SPEC & FLOW & HELP
+    DOCS --> SCAN & DATA & TEXT & FORGE & REVIEW & OTHER
+    SPEC --> SPEC_INIT & GATE
+    SCAN --> SCANNER --> SRC
+    SCANNER --> ANALYSIS
+    DATA --> PARSER --> DOCFILES
+    TEXT --> AGENT --> AI
+    FORGE --> AGENT
+    REVIEW --> AGENT
+    AGENT --> DOCFILES
+    CONFIG --> CFGFILE
+    SPEC_INIT --> SPECS
+    GATE --> SPECS
+```
+
 ### Component Responsibilities
 
 <!-- {{text: Describe the major components with their location, responsibilities, and I/O in table format.}} -->
 
+| Component | Location | Responsibility | Input | Output |
+|---|---|---|---|---|
+| CLI Entry Point | `src/sdd-forge.js` | Resolves project context; routes subcommands to the appropriate dispatcher | CLI arguments, env vars (`SDD_SOURCE_ROOT`, `SDD_WORK_ROOT`) | Dispatched command execution |
+| Docs Dispatcher | `src/docs.js` | Routes `build`, `scan`, `init`, `data`, `text`, `forge`, `review`, and related subcommands | Subcommand name + flags | Delegates to `docs/commands/*.js` |
+| Spec Dispatcher | `src/spec.js` | Routes `spec` and `gate` subcommands | Subcommand name + flags | Delegates to `specs/commands/*.js` |
+| SDD Flow Runner | `src/flow.js` | Automates the full SDD cycle end-to-end | `--request` prompt string | Orchestrated spec → gate → implement → forge → review sequence |
+| Source Scanner | `src/docs/lib/scanner.js` | Parses project source files; extracts modules, routes, and structure | Source root directory | `.sdd-forge/output/analysis.json`, `summary.json` |
+| Directive Parser | `src/docs/lib/directive-parser.js` | Parses `{{data}}` and `{{text}}` directives in Markdown templates | `.md` template files | Directive AST for resolvers |
+| Data Resolver | `src/docs/lib/resolver-factory.js` | Injects structured analysis data into `{{data}}` directives | `analysis.json`, directive AST | Resolved Markdown sections |
+| AI Agent Caller | `src/lib/agent.js` | Invokes external AI agent processes synchronously or asynchronously | Prompt string, agent config | AI-generated text (stdout) |
+| Config Manager | `src/lib/config.js` | Loads and validates `.sdd-forge/config.json`; resolves standard paths | `.sdd-forge/` directory | Typed config object, file paths |
+| Spec Gate | `src/specs/commands/gate.js` | Validates a spec against pre/post implementation checklists | `spec.md` path, `--phase` flag | PASS / FAIL report |
+| Forge Engine | `src/docs/commands/forge.js` | Iteratively improves `docs/` by prompting the AI agent | Change summary prompt, `spec.md` path | Updated `docs/*.md` files |
+
 ### External Integrations
 
 <!-- {{text: If there are external system integrations, describe their purpose and connection method in table format.}} -->
 
+| System | Purpose | Connection Method | Configuration |
+|---|---|---|---|
+| AI Agent (e.g. Claude CLI) | Generates and refines documentation text for `{{text}}` directives; drives `forge`, `review`, `agents`, and `text` commands | Spawned as a child process via `execFileSync` (sync) or `spawn` (async streaming) in `src/lib/agent.js` | Defined under `providers` in `.sdd-forge/config.json`; selected by `defaultAgent` key |
+
+The AI agent is the only external integration. All other operations — file scanning, directive parsing, template merging, spec management — rely exclusively on Node.js built-in modules (`fs`, `path`, `child_process`, `os`). The agent command, arguments, timeout, and system-prompt delivery method (`--system-prompt` or `--system-prompt-file`) are all configurable per project.
+
 ### Environment Differences
 
 <!-- {{text: Describe the configuration differences across environments (local/staging/production).}} -->
+
+As a local CLI tool, sdd-forge does not have distinct deployment environments in the traditional sense. Configuration differences are instead expressed through per-project `.sdd-forge/config.json` settings and environment variables.
+
+| Aspect | Local Development | CI / Automated Pipeline | Multi-Project Setup |
+|---|---|---|---|
+| Project resolution | Interactive; `--project` flag or `.sdd-forge/projects.json` `default` key | `SDD_SOURCE_ROOT` and `SDD_WORK_ROOT` env vars set explicitly per job | `.sdd-forge/projects.json` registers named projects; `--project <name>` selects the target |
+| AI agent | Configured via `providers` + `defaultAgent` in `config.json`; runs interactively | Same config; `stdin: "ignore"` prevents CLI hang in non-TTY environments (`callAgentAsync`) | Each project carries its own `config.json` with independent agent settings |
+| Language / output | `lang` and `output.languages` control CLI language and doc output locale | Same config values apply; no separate override mechanism | Per-project `config.json` allows different languages per project |
+| Concurrency | `limits.concurrency` (default: 5) controls parallel file processing | Can be raised for faster execution on high-core machines | Independently tunable per project |
+| Timeouts | `limits.designTimeoutMs` / per-provider `timeoutMs` | Should be increased for slow CI agents; default constants: 120 s / 180 s / 300 s | Configurable per project |
+```

package/docs/02_cli_commands.md

@@ -4,20 +4,267 @@
 
 <!-- {{text: Write a 1–2 sentence overview of this chapter. Cover the total number of commands, whether global options exist, and the subcommand structure.}} -->
 
+This chapter covers all 18 subcommands available in `sdd-forge`, organized into documentation generation commands (routed through `docs.js`), spec workflow commands (routed through `spec.js`), and directly executed commands (`flow`, `presets`). All commands share a common set of global options, and most require a resolved project context before execution.
+
 ## Contents
 
 ### Command List
 
-<!-- {{text: List all commands in a table, including command name, description, and main options. Commands can be identified from the modules list in the analysis data. Include both commands routed through dispatchers (docs.js, spec.js) and directly executed commands (flow, presets). Note that build is a composite command (scan → init → data → text → readme → agents → translate pipeline). Be sure to include translate (multi-language translation), upgrade (template update), and default (default project configuration).}} -->
+<!-- {{text: List all commands in a table format. Include command name, description, and main options. Commands can be identified from the modules list in the analysis data. Include both commands routed through dispatchers (docs.js, spec.js) and directly executed commands (flow, presets). Note that build is a composite command (scan → init → data → text → readme → agents → translate pipeline). Be sure to include translate (multilingual translation), upgrade (template update), and default (default project configuration).}} -->
+
+| Command | Description | Key Options |
+|---|---|---|
+| `build` | Runs the full documentation pipeline (`scan → init → data → text → readme → agents → translate`) in one step | `--project` |
+| `scan` | Analyzes source code and writes `analysis.json` and `summary.json` | `--project` |
+| `init` | Initializes `docs/` from preset templates | `--project` |
+| `data` | Resolves `{{data: ...}}` directives using analysis output | `--project` |
+| `text` | Resolves `{{text: ...}}` directives using the configured AI agent | `--file`, `--agent`, `--project` |
+| `readme` | Auto-generates `README.md` from docs content via AI | `--project` |
+| `forge` | Iteratively improves docs using AI, guided by a prompt | `--prompt`, `--spec`, `--project` |
+| `review` | Runs an AI quality check on docs and reports PASS/FAIL | `--project` |
+| `changelog` | Generates `change_log.md` from all spec files under `specs/` | `--project` |
+| `agents` | Updates `AGENTS.md` with the latest SDD template and PROJECT section | `--sdd`, `--project-only`, `--dry-run` |
+| `translate` | Translates docs into additional output languages defined in config | `--lang`, `--force`, `--dry-run` |
+| `upgrade` | Updates SDD-managed template sections to match the installed package version | `--project` |
+| `setup` | Registers a project and generates initial `.sdd-forge/config.json` | — |
+| `default` | Sets or displays the default project in `projects.json` | — |
+| `spec` | Creates a new spec file and optionally a feature branch | `--title`, `--no-branch` |
+| `gate` | Validates a spec against acceptance criteria before or after implementation | `--spec`, `--phase` |
+| `flow` | Automates the full SDD flow from a natural-language request | `--request` |
+| `presets` | Lists all bundled project type presets | — |
+| `help` | Displays available subcommands and descriptions | `-h`, `--help` |
 
 ### Global Options
 
-<!-- {{text: Describe the global options common to all commands in a table. Include --project, --help/-h, and --version/-v/-V. Also note that setup, default, help, and presets skip project context resolution.}} -->
+<!-- {{text: List global options common to all commands in a table format. Include --project, --help/-h, and --version/-v/-V. Also note that setup, default, help, and presets skip project context resolution.}} -->
+
+| Option | Aliases | Description |
+|---|---|---|
+| `--project <name>` | — | Specifies the target project by name, as registered in `.sdd-forge/projects.json`. When omitted, the project marked as `default` in `projects.json` is used. |
+| `--help` | `-h` | Prints the help text for the given subcommand and exits. |
+| `--version` | `-v`, `-V` | Prints the current `sdd-forge` version from `package.json` and exits. |
+
+> **Note:** The `setup`, `default`, `help`, and `presets` commands skip project context resolution entirely. They do not require a registered project and ignore the `--project` flag.
 
 ### Command Details
 
 <!-- {{text: Describe the usage, options, and examples for each command in detail. Create a #### subsection for each command. For the build pipeline, list all steps: scan → init → data → text → readme → agents → translate. The translate command has --lang, --force, and --dry-run options.}} -->
 
+Each command below is documented with its purpose, available options, and representative usage examples. Commands that involve AI generation require a valid `defaultAgent` or `providers` entry in `.sdd-forge/config.json`. Commands that modify files on disk always operate within the resolved project's `docs/` directory unless otherwise noted.
+
+#### build
+
+Runs the complete documentation generation pipeline in a single step. The pipeline executes the following stages in order: `scan → init → data → text → readme → agents → translate`. This is the standard entry point for first-time setup or full regeneration of project docs.
+
+```bash
+sdd-forge build
+sdd-forge build --project myproject
+```
+
+#### scan
+
+Analyzes the project source code according to the configured preset (e.g., `cli/node-cli`, `webapp/cakephp2`) and writes results to `.sdd-forge/output/analysis.json` and `.sdd-forge/output/summary.json`. The `summary.json` is a lightweight version intended for AI consumption.
+
+```bash
+sdd-forge scan
+```
+
+#### init
+
+Initializes the `docs/` directory structure by copying preset templates. Templates are resolved from `src/presets/{preset}/templates/{lang}/`. Existing files are not overwritten unless explicitly forced.
+
+```bash
+sdd-forge init
+```
+
+#### data
+
+Resolves all `{{data: ...}}` directives found in `docs/` files, replacing them with structured data extracted from `analysis.json`. Directives outside template boundaries are left untouched.
+
+```bash
+sdd-forge data
+```
+
+#### text
+
+Resolves `{{text: ...}}` directives in `docs/` files using the configured AI agent. Processes files concurrently up to the `limits.concurrency` setting. Optionally targets a single file.
+
+| Option | Description |
+|---|---|
+| `--file <path>` | Process only the specified docs file |
+| `--agent <name>` | Override the AI agent to use |
+
+```bash
+sdd-forge text
+sdd-forge text --file docs/02_cli_commands.md
+```
+
+#### readme
+
+Auto-generates `README.md` in the project root using the content of `docs/` as source material. The output is driven by the AI agent defined in the project config.
+
+```bash
+sdd-forge readme
+```
+
+#### forge
+
+Iteratively improves one or more docs files using AI, guided by a prompt describing recent changes. When `--spec` is provided, the spec file is included as additional context for the AI.
+
+| Option | Description |
+|---|---|
+| `--prompt <text>` | Description of changes to reflect in docs (required) |
+| `--spec <path>` | Path to the spec file for additional context |
+
+```bash
+sdd-forge forge --prompt "Added translate command with --lang option"
+sdd-forge forge --prompt "Refactored scanner" --spec specs/010-refactor/spec.md
+```
+
+#### review
+
+Runs a quality check over the generated docs using AI, validating completeness, accuracy, and consistency with the source code. Outputs a PASS or FAIL result with actionable feedback.
+
+```bash
+sdd-forge review
+```
+
+#### changelog
+
+Generates `change_log.md` by aggregating all spec files under `specs/`. Each spec contributes a changelog entry describing the feature or fix it represents.
+
+```bash
+sdd-forge changelog
+```
+
+#### agents
+
+Updates `AGENTS.md` with the latest SDD instruction template and a newly generated PROJECT section derived from `analysis.json` / `summary.json`. The command supports partial updates via flags.
+
+| Option | Description |
+|---|---|
+| `--sdd` | Update only the `<!-- SDD:START/END -->` section |
+| `--project` | Update only the `<!-- PROJECT:START/END -->` section |
+| `--dry-run` | Preview output without writing to disk |
+
+```bash
+sdd-forge agents
+sdd-forge agents --sdd
+sdd-forge agents --dry-run
+```
+
+#### translate
+
+Translates the generated docs into one or more additional output languages, as specified by `output.languages` in the project config. Uses `output.mode` (`translate` or `generate`) to determine the translation strategy.
+
+| Option | Description |
+|---|---|
+| `--lang <code>` | Target language code to translate into (e.g., `en`, `ja`) |
+| `--force` | Overwrite existing translated files |
+| `--dry-run` | Preview without writing to disk |
+
+```bash
+sdd-forge translate --lang en
+sdd-forge translate --lang en --force
+```
+
+#### upgrade
+
+Updates the SDD-managed sections of `docs/` templates to match the latest version bundled with the installed `sdd-forge` package. Content outside directive boundaries is preserved.
+
+```bash
+sdd-forge upgrade
+```
+
+#### setup
+
+Registers a new project with `sdd-forge` and generates the initial `.sdd-forge/config.json`. Guides the user through selecting a project type preset and configuring output language settings. Also creates `AGENTS.md` and a `CLAUDE.md` symlink.
+
+```bash
+sdd-forge setup
+```
+
+#### default
+
+Sets or displays the default project for the current tool installation. The default project is stored in `.sdd-forge/projects.json` and used when `--project` is not specified.
+
+```bash
+sdd-forge default
+sdd-forge default myproject
+```
+
+#### spec
+
+Creates a new spec file under `specs/NNN-<slug>/spec.md` and optionally creates a feature branch. Used at the start of the SDD workflow for any new feature or fix.
+
+| Option | Description |
+|---|---|
+| `--title <name>` | Title of the spec / feature (required) |
+| `--no-branch` | Skip branch creation (e.g., when already inside a worktree) |
+
+```bash
+sdd-forge spec --title "Add translate command"
+sdd-forge spec --title "Fix scanner" --no-branch
+```
+
+#### gate
+
+Validates a spec file against defined acceptance criteria before (`--phase pre`) or after (`--phase post`) implementation. Reports each check item as PASS or FAIL.
+
+| Option | Description |
+|---|---|
+| `--spec <path>` | Path to the spec file to validate (required) |
+| `--phase <pre\|post>` | Gate phase; defaults to `pre` |
+
+```bash
+sdd-forge gate --spec specs/010-translate/spec.md
+sdd-forge gate --spec specs/010-translate/spec.md --phase post
+```
+
+#### flow
+
+Automatically executes the full SDD flow — spec creation, gate check, and implementation scaffolding — for a given natural-language request. Intended for AI agent environments where manual step-by-step execution is not practical.
+
+| Option | Description |
+|---|---|
+| `--request <text>` | Natural-language description of the feature or fix |
+
+```bash
+sdd-forge flow --request "Add support for multilingual output"
+```
+
+#### presets
+
+Lists all available project type presets bundled with `sdd-forge`, including architecture-layer presets (`webapp`, `cli`, `library`) and framework-specific presets (`cakephp2`, `laravel`, `symfony`, `node-cli`).
+
+```bash
+sdd-forge presets
+```
+
+#### help
+
+Displays a summary of all available subcommands and their descriptions. Equivalent to running `sdd-forge` with no arguments.
+
+```bash
+sdd-forge help
+sdd-forge -h
+```
+
 ### Exit Codes and Output
 
-<!-- {{text: Describe exit code definitions (0=success, 1=general error, etc.) and the rules for stdout/stderr usage in a table. Include the point that gate and review PASS/FAIL results are printed to stdout.}} -->
+<!-- {{text: Describe exit code definitions (0=success, 1=general error, etc.) and the rules for stdout/stderr usage in a table format. Include the fact that gate and review PASS/FAIL results are printed to stdout.}} -->
+
+| Exit Code | Meaning |
+|---|---|
+| `0` | Command completed successfully |
+| `1` | General error (missing required option, file not found, configuration invalid, etc.) |
+| `2` | Gate or review check failed (FAIL result reported; see stdout for details) |
+
+**stdout / stderr usage:**
+
+| Stream | Content |
+|---|---|
+| `stdout` | Primary command output: generated text, rendered tables, PASS/FAIL results from `gate` and `review`, dry-run previews |
+| `stderr` | Progress indicators, warnings, debug information, and error messages |
+
+`gate` and `review` always print their PASS/FAIL verdict and per-item check results to **stdout**, making them suitable for capture in CI pipelines. Error messages describing why a command could not run (missing config, invalid arguments, etc.) are written to **stderr** and do not appear in captured stdout.

package/docs/03_configuration.md

@@ -2,22 +2,135 @@
 
 ## Description
 
-<!-- {{text: Describe the overview of this chapter in 1–2 sentences. Cover the types of configuration files, the range of configurable options, and customization points.}} -->
+<!-- {{text: Describe the overview of this chapter in 1-2 sentences. Cover the types of configuration files, the range of configurable options, and customization points.}} -->
+
+This chapter covers all configuration files used by sdd-forge, the full range of options available in `.sdd-forge/config.json`, and the customization points for AI providers, document style, project type, merge strategy, and concurrency.
 
 ## Contents
 
 ### Configuration Files
 
-<!-- {{text: List the configuration files loaded by this tool in a table, including the location and role of each. Main files: .sdd-forge/config.json (project settings), .sdd-forge/context.json (project context), .sdd-forge/projects.json (multi-project management), .sdd-forge/current-spec (SDD flow state), .sdd-forge/output/analysis.json (analysis results), .sdd-forge/output/summary.json (lightweight version for AI).}} -->
+<!-- {{text: List all configuration files loaded by this tool in a table, including their locations and roles. Main files: .sdd-forge/config.json (project settings), .sdd-forge/context.json (project context), .sdd-forge/projects.json (multi-project management), .sdd-forge/current-spec (SDD flow state), .sdd-forge/output/analysis.json (analysis results), .sdd-forge/output/summary.json (lightweight version for AI).}} -->
+
+All configuration and state files are stored under the `.sdd-forge/` directory at the working root of your project.
+
+| File | Location | Role |
+|---|---|---|
+| `config.json` | `.sdd-forge/config.json` | Primary project configuration. Defines output languages, project type, AI agent settings, document style, and workflow options. Validated on load. |
+| `context.json` | `.sdd-forge/context.json` | Free-form project context string passed to AI during text generation. Takes priority over `textFill.projectContext` in `config.json`. |
+| `projects.json` | `.sdd-forge/projects.json` | Multi-project registry. Maps project names to their source and work root paths. Generated by `sdd-forge setup`. |
+| `current-spec` | `.sdd-forge/current-spec` | JSON file tracking the active SDD flow state, including spec path, base branch, feature branch, and worktree information. Deleted on flow completion. |
+| `analysis.json` | `.sdd-forge/output/analysis.json` | Full source code analysis result produced by `sdd-forge scan`. Stored without indentation for compact output. |
+| `summary.json` | `.sdd-forge/output/summary.json` | Lightweight version of `analysis.json` optimized for AI consumption. Used in preference to `analysis.json` wherever available. |
 
 ### Configuration Reference
 
-<!-- {{text: Describe all fields in .sdd-forge/config.json in a table format. Include field name, whether required, type, default value, and description. Main fields: output.languages (list of output languages), output.default (default language), output.mode (translate/generate), lang (CLI operating language), type (project type), documentStyle (purpose/tone/customInstruction), textFill (projectContext/preamblePatterns), defaultAgent, providers (AI agent definitions), flow.merge (squash/ff-only/merge), limits (concurrency/designTimeoutMs).}} -->
+<!-- {{text: Describe all fields in .sdd-forge/config.json in a table format. Include field name, whether required, type, default value, and description. Main fields: output.languages (output language list), output.default (default language), output.mode (translate/generate), lang (CLI operating language), type (project type), documentStyle (purpose/tone/customInstruction), textFill (projectContext/preamblePatterns), defaultAgent, providers (AI agent definitions), flow.merge (squash/ff-only/merge), limits (concurrency/designTimeoutMs).}} -->
+
+The table below describes every supported field in `.sdd-forge/config.json`.
+
+| Field | Required | Type | Default | Description |
+|---|---|---|---|---|
+| `output.languages` | ✅ | `string[]` | — | List of output languages for generated docs (e.g., `["ja"]`, `["en", "ja"]`). |
+| `output.default` | ✅ | `string` | — | The primary output language used when generating documents. |
+| `output.mode` | — | `"translate"` \| `"generate"` | `"translate"` | How non-default languages are produced: `translate` uses the default output as source; `generate` calls AI independently. |
+| `lang` | ✅ | `string` | — | Operating language for the CLI, AGENTS.md, skill prompts, and spec files. |
+| `type` | ✅ | `string` | — | Project type that selects the active preset (e.g., `"cli/node-cli"`, `"webapp/cakephp2"`). |
+| `uiLang` | — | `"en"` \| `"ja"` | — | Language for sdd-forge's own UI messages. |
+| `documentStyle.purpose` | — | `string` | — | A short description of the document's intended audience or purpose, passed to AI during generation. |
+| `documentStyle.tone` | — | `"polite"` \| `"formal"` \| `"casual"` | — | Writing tone applied to AI-generated text sections. |
+| `documentStyle.customInstruction` | — | `string` | — | Additional freeform instruction appended to AI prompts for every text generation task. |
+| `textFill.projectContext` | — | `string` | — | Project overview text supplied to AI. Overridden by `context.json` when that file exists. |
+| `textFill.preamblePatterns` | — | `object[]` | — | Patterns used to strip LLM-generated preamble text from AI responses before inserting into docs. |
+| `defaultAgent` | — | `string` | — | Name of the AI provider entry (from `providers`) used when no agent is explicitly specified. |
+| `providers` | — | `object` | — | Map of named AI agent definitions. Each entry specifies `command`, `args`, optional `timeoutMs`, and `systemPromptFlag`. |
+| `flow.merge` | — | `"squash"` \| `"ff-only"` \| `"merge"` | `"squash"` | Git merge strategy applied when closing an SDD flow. |
+| `limits.concurrency` | — | `number` | `5` | Maximum number of files processed in parallel during document generation. |
+| `limits.designTimeoutMs` | — | `number` | — | Timeout in milliseconds for AI agent calls during document generation. |
 
 ### Customization Points
 
-<!-- {{text: Describe the items users can customize. (1) AI provider settings (providers field, command/args/timeoutMs/systemPromptFlag) with configuration examples, (2) document style (purpose/tone/customInstruction), (3) preset selection (type field), (4) merge strategy (flow.merge), (5) concurrency level (limits.concurrency). Include JSON configuration examples for each item.}} -->
+<!-- {{text: Explain the items users can customize. (1) AI provider settings (providers field, command/args/timeoutMs/systemPromptFlag) with configuration examples, (2) document style (purpose/tone/customInstruction), (3) preset selection (type field), (4) merge strategy (flow.merge), (5) concurrency (limits.concurrency). Include a JSON configuration example for each item.}} -->
+
+**1. AI Provider Settings**
+
+The `providers` field defines one or more named AI agents. Each entry specifies the executable command, argument list, an optional timeout, and how system prompts are passed. Use `defaultAgent` to select which provider is active by default.
+
+```json
+{
+  "defaultAgent": "claude",
+  "providers": {
+    "claude": {
+      "command": "claude",
+      "args": ["--model", "claude-opus-4-5", "{{PROMPT}}"],
+      "timeoutMs": 180000,
+      "systemPromptFlag": "--system-prompt"
+    }
+  }
+}
+```
+
+The `{{PROMPT}}` placeholder in `args` marks where the generated prompt is injected. If omitted, the prompt is appended at the end of the argument list. Set `systemPromptFlag` to `"--system-prompt-file"` when the agent expects a file path rather than an inline string.
+
+**2. Document Style**
+
+The `documentStyle` field controls the tone and purpose of AI-generated documentation. Use `customInstruction` to enforce project-specific writing conventions.
+
+```json
+{
+  "documentStyle": {
+    "purpose": "Internal reference for backend engineers",
+    "tone": "formal",
+    "customInstruction": "Always include code examples for each API method."
+  }
+}
+```
+
+**3. Preset Selection**
+
+The `type` field selects the preset that determines which source files are scanned and which document chapters are generated. Choose the value that best matches your project's architecture.
+
+```json
+{
+  "type": "cli/node-cli"
+}
+```
+
+Available built-in values include `"cli/node-cli"`, `"webapp/cakephp2"`, `"webapp/laravel"`, and `"webapp/symfony"`. Refer to the preset list for the full set of supported aliases.
+
+**4. Merge Strategy**
+
+The `flow.merge` field controls how feature branches are merged into the base branch at the end of an SDD flow.
+
+```json
+{
+  "flow": {
+    "merge": "squash"
+  }
+}
+```
+
+Use `"squash"` to condense all feature commits into one, `"ff-only"` for a linear history without a merge commit, or `"merge"` for a standard merge commit.
+
+**5. Concurrency**
+
+Adjust `limits.concurrency` to control how many files are processed in parallel during document generation. Lower this value if AI rate limits are being hit; raise it to speed up generation on large codebases.
+
+```json
+{
+  "limits": {
+    "concurrency": 3,
+    "designTimeoutMs": 240000
+  }
+}
+```
 
 ### Environment Variables
 
-<!-- {{text: List the environment variables referenced by the tool and their purposes in a table. SDD_SOURCE_ROOT (source code root), SDD_WORK_ROOT (work root, location where .sdd-forge/ is placed), CLAUDECODE (internal variable deleted to prevent Claude CLI from hanging).}} -->
+<!-- {{text: List the environment variables referenced by the tool and their purposes in a table. SDD_SOURCE_ROOT (source code root), SDD_WORK_ROOT (working root, location of .sdd-forge/), CLAUDECODE (internal variable removed to prevent Claude CLI hangs).}} -->
+
+| Variable | Purpose |
+|---|---|
+| `SDD_SOURCE_ROOT` | Absolute path to the source code root being analyzed. When set, overrides the path resolved from `git rev-parse` or the current working directory. |
+| `SDD_WORK_ROOT` | Absolute path to the working root, i.e., the directory containing `.sdd-forge/`. When set, takes priority over the git-resolved root. |
+| `CLAUDECODE` | An internal variable that sdd-forge actively removes from the environment before spawning AI agent processes. This prevents the Claude CLI from hanging when launched as a child process. |