sdd-forge 0.1.0-alpha.24 → 0.1.0-alpha.26

package/README.md

@@ -2,23 +2,23 @@
 
 [![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. The API, command structure, and configuration format may change without notice. Please avoid using it in production environments.
+> **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/`.
 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 package dependencies.
-- **Automatic source code 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** — Four-layer inheritance (base → arch → preset → project-local) for flexible customization.
-- **SDD workflow** — Manage the development cycle of spec → gate → implementation → forge → review with simple commands.
-- **Multilingual support** — Automatically generate documentation in multiple languages via translate / generate modes.
-- **AI agent integration** — Compatible with Claude Code (skills) and Codex CLI.
-- **Multi-preset** — Supports Node.js CLI / CakePHP2 / Laravel / Symfony.
+- **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** — 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
 
 ## Quick Start
 
@@ -41,13 +41,13 @@ pnpm add -g {{data: project.name("")}}sdd-forge{{/data}}
 # 1. Register your project (interactive wizard)
 {{data: project.name("")}}sdd-forge{{/data}} setup
 
-# 2. Generate all documentation at once (scan → init → data → text → readme → agents → translate)
+# 2. Generate all documentation (scan → init → data → text → readme → agents → translate)
 {{data: project.name("")}}sdd-forge{{/data}} build
 </pre>
 
-This is all it takes to generate `docs/` and `README.md`.
+This generates `docs/` and `README.md` in one step.
 
-## Command Reference
+## Commands
 
 ### Document Generation
 
@@ -57,12 +57,12 @@ This is all it takes to generate `docs/` and `README.md`.
 | `build` | Run the full document generation pipeline |
 | `scan` | Analyze source code → `analysis.json` |
 | `init` | Initialize `docs/` from templates |
-| `data` | Resolve `{{data}}` directives with analyzed data |
+| `data` | Resolve `{{data}}` directives with analysis data |
 | `text` | Resolve `{{text}}` directives with AI |
 | `readme` | Auto-generate `README.md` from `docs/` |
 | `forge` | Iteratively improve documentation with AI |
 | `review` | Check documentation quality |
-| `translate` | Multilingual translation (default language → others) |
+| `translate` | Multi-language translation (default language → others) |
 | `upgrade` | Update preset templates to the latest version |
 
 ### SDD Workflow
@@ -81,16 +81,16 @@ This is all it takes to generate `docs/` and `README.md`.
 |---|---|
 | `default` | Set the default project |
 | `presets` | List available presets |
-| `help` | Show command list |
+| `help` | Display command list |
 
 ## SDD Workflow
 
-The flow for adding features or making changes:
+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 unresolved items)
+  gate          Spec gate check (PASS when no open questions)
     ↓
   implement     Write code after gate PASS
     ↓
@@ -112,7 +112,7 @@ Run the SDD workflow with skills:
 
 #### Codex CLI
 
-Run the workflow from a prompt:
+Run the workflow from prompts:
 
 ```
 $sdd-flow-start   — Start spec creation → gate → implementation
@@ -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) | This chapter provides a high-level view of `sdd-forge`, a Node.js CLI tool that automates documentation generation th… |
-| [02. CLI Command Reference](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/02_cli_commands.md) | This chapter documents all 17 subcommands available in `sdd-forge`, organized across three dispatcher layers (`docs.j… |
-| [03. Configuration and Customization](https://github.com/SpreadWorks/sdd-forge/blob/main/docs/03_configuration.md) | This chapter covers the configuration files and customization options available in sdd-forge, including project setti… |
+| [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,7 +4,7 @@
 
 <!-- {{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 high-level view 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 integrates with externally configured AI agents (such as Claude CLI) to produce and refine project documentation, while relying solely on Node.js built-in modules for all other operations.
+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
 
@@ -14,35 +14,61 @@ This chapter provides a high-level view of `sdd-forge`, a Node.js CLI tool that
 
 ```mermaid
 flowchart TD
-    User([User / CI]) -->|CLI invocation| Entry[sdd-forge.js\nEntry Point]
-
-    Entry -->|docs subcommands| DocsDispatcher[docs.js\nDispatcher]
-    Entry -->|spec / gate| SpecDispatcher[spec.js\nDispatcher]
-    Entry -->|flow| Flow[flow.js\nSDD Flow Runner]
-    Entry -->|presets| Presets[presets-cmd.js]
-    Entry -->|help| Help[help.js]
-
-    DocsDispatcher --> Scan[scan\nSource Analysis]
-    DocsDispatcher --> Data[data\nDirective Resolver]
-    DocsDispatcher --> Text[text\nAI Text Fill]
-    DocsDispatcher --> Forge[forge\nDocs Refinement]
-    DocsDispatcher --> Review[review\nQuality Check]
-    DocsDispatcher --> Readme[readme\nREADME Generator]
-
-    SpecDispatcher --> SpecInit[spec init\nSpec Creation]
-    SpecDispatcher --> Gate[gate\nGate Check]
-
-    Scan -->|analysis.json\nsummary.json| OutputDir[.sdd-forge/output/]
-    Data -->|reads| OutputDir
-    Text -->|reads| OutputDir
-    Forge -->|reads| OutputDir
-
-    Text -->|prompt| AgentLib[lib/agent.js\nAI Agent Caller]
-    Forge -->|prompt| AgentLib
-    Review -->|prompt| AgentLib
-    AgentLib -->|configured command| ExternalAI([External AI Agent\ne.g. Claude CLI])
-
-    OutputDir -->|resolved directives| DocsDir[docs/\nGenerated Documentation]
+    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
@@ -51,17 +77,17 @@ flowchart TD
 
 | Component | Location | Responsibility | Input | Output |
 |---|---|---|---|---|
-| CLI Entry Point | `src/sdd-forge.js` | Parses top-level subcommand and resolves project context via environment variables | CLI arguments, `.sdd-forge/projects.json` | Routes to dispatcher with `SDD_SOURCE_ROOT` / `SDD_WORK_ROOT` set |
-| Docs Dispatcher | `src/docs.js` | Routes docs-related subcommands (`build`, `scan`, `data`, `text`, `forge`, `review`, etc.) | Subcommand string | Delegates to `src/docs/commands/*.js` |
-| Spec Dispatcher | `src/spec.js` | Routes spec-related subcommands (`spec`, `gate`) | Subcommand string | Delegates to `src/specs/commands/*.js` |
-| Scanner | `src/docs/lib/scanner.js` | Traverses source files and extracts structural information (PHP, JS, YAML) | Source root path, scan config | `.sdd-forge/output/analysis.json`, `summary.json` |
-| Directive Parser | `src/docs/lib/directive-parser.js` | Parses `{{data}}`, `{{text}}`, `@block`, and `@extends` directives in Markdown templates | Markdown template files | Parsed directive AST |
-| Data Resolver | `src/docs/lib/resolver-factory.js` | Resolves `{{data}}` directives by binding analysis data to named data sources | Parsed directives, `analysis.json` | Rendered Markdown sections |
-| AI Agent Caller | `src/lib/agent.js` | Executes configured external AI agent commands synchronously or asynchronously | Prompt string, agent config | AI-generated text streamed or returned as string |
-| Config Manager | `src/lib/config.js` | Loads and validates `.sdd-forge/config.json`; manages context and path resolution | `.sdd-forge/` directory | Typed config object, resolved paths |
-| Flow State Manager | `src/lib/flow-state.js` | Persists and retrieves SDD workflow state (current spec, branch, worktree info) | Work root path, state object | `.sdd-forge/current-spec` JSON file |
-| Preset System | `src/lib/presets.js` | Auto-discovers `preset.json` files under `src/presets/` and registers available project types | `src/presets/` directory tree | `PRESETS` constant used across all consumers |
-| SDD Flow Runner | `src/flow.js` | Orchestrates the full SDD cycle (spec → gate → implement → forge → review) automatically | `--request` argument, flow state | Sequential command execution with user interaction |
+| 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
 
@@ -69,22 +95,21 @@ flowchart TD
 
 | System | Purpose | Connection Method | Configuration |
 |---|---|---|---|
-| AI Agent (e.g. Claude CLI) | Generates and refines documentation text, performs quality review, and evaluates spec gate checks | Spawned as a child process via `child_process.execFileSync` (sync) or `spawn` (async) | Defined in `.sdd-forge/config.json` under `providers` and `defaultAgent`; supports `command`, `args`, `timeoutMs`, and `systemPromptFlag` |
-| Git | Branch creation, worktree isolation, and repository root resolution for SDD workflows | Invoked via `child_process` shell commands (`git rev-parse`, `git worktree`, etc.) | Resolved automatically from the working directory; worktree support detected via `.git` file presence |
+| 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 |
 
-`sdd-forge` has no network-based external dependencies. All integrations are process-level and operate entirely within the local development environment.
+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).}} -->
 
-`sdd-forge` is a local developer CLI tool and does not have traditional deployment environments (staging, production). Configuration is driven entirely by `.sdd-forge/config.json` in each project's working directory.
+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 |
-|---|---|---|
-| Agent invocation | Interactive; supports streaming output callbacks for live feedback | Non-interactive; `callAgentAsync()` with `stdin: "ignore"` to prevent hangs |
-| `CLAUDECODE` env var | May be set if running inside Claude Code | Must be unset before spawning AI agent subprocess (handled automatically by `agent.js`) |
-| Project context | Resolved via `.sdd-forge/projects.json` `default` entry or `--project` flag | Set explicitly via `SDD_SOURCE_ROOT` and `SDD_WORK_ROOT` environment variables |
-| AI agent timeout | Defaults: 120 s / 180 s / 300 s depending on command | Same defaults apply; increase via `config.limits.designTimeoutMs` if needed |
-| Concurrency | Default 5 parallel file processes; tunable via `config.limits.concurrency` | Same; reduce if CPU-constrained in CI runners |
-| Output language | Controlled by `config.output.default` and `config.lang` | Same; no environment-specific overrides exist |
+| 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,7 +4,7 @@
 
 <!-- {{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 documents all 17 subcommands available in `sdd-forge`, organized across three dispatcher layers (`docs.js`, `spec.js`, and direct commands). Each subcommand is accessible via `sdd-forge <subcommand>`, with a small set of global options applying across the CLI.
+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
 
@@ -14,42 +14,44 @@ This chapter documents all 17 subcommands available in `sdd-forge`, organized ac
 
 | Command | Description | Key Options |
 |---|---|---|
-| `build` | Run the full documentation pipeline: `scan → init → data → text → readme → agents → translate` | `--project` |
-| `scan` | Analyze source code and output `analysis.json` and `summary.json` | `--project` |
-| `init` | Initialize `docs/` from preset templates | `--project`, `--preset` |
-| `data` | Resolve `{{data}}` directives using analysis results | `--project` |
-| `text` | Resolve `{{text}}` directives using AI agents | `--project`, `--agent`, `--file` |
-| `readme` | Auto-generate `README.md` from docs content | `--project` |
-| `forge` | Iteratively improve docs with AI | `--prompt`, `--spec`, `--project` |
-| `review` | Run a quality check on generated docs | `--project` |
-| `changelog` | Generate `change_log.md` from accumulated specs | `--project` |
-| `agents` | Update `AGENTS.md` (SDD template + PROJECT section) | `--sdd`, `--project`, `--dry-run` |
-| `translate` | Translate docs into additional output languages | `--lang`, `--force`, `--dry-run` |
-| `upgrade` | Update SDD-managed doc templates to the latest version | `--project` |
-| `setup` | Register a project and generate `.sdd-forge/config.json` | — |
-| `default` | Set or display the default project | — |
-| `spec` | Initialize a new spec file and feature branch | `--title`, `--no-branch` |
-| `gate` | Run a gate check against a spec file | `--spec`, `--phase` |
-| `flow` | Automatically execute the full SDD flow for a given request | `--request` |
-| `presets` | List or inspect available project type presets | — |
-| `help` | Display available subcommands and usage information | — |
+| `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: 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 | Alias | Description |
+| Option | Aliases | Description |
 |---|---|---|
-| `--project <name>` | — | Specify the target project by name, as registered in `.sdd-forge/projects.json`. Overrides the `default` project setting. |
-| `--help` | `-h` | Display usage information for the CLI or a specific subcommand. |
-| `--version` | `-v`, `-V` | Print the installed `sdd-forge` version (read from `package.json`). |
+| `--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` subcommands skip project context resolution entirely. They do not require a registered project and will not read `.sdd-forge/config.json` or set `SDD_SOURCE_ROOT` / `SDD_WORK_ROOT`.
+> **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.
@@ -252,19 +254,17 @@ sdd-forge -h
 
 <!-- {{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 Codes**
-
-| Code | Meaning |
+| Exit Code | Meaning |
 |---|---|
 | `0` | Command completed successfully |
-| `1` | General error (misconfiguration, missing required argument, unexpected failure) |
-| `2` | Validation failure — used by `gate` when one or more checks FAIL, and by `review` when the quality check does not PASS |
+| `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 Rules**
+**stdout / stderr usage:**
 
 | Stream | Content |
 |---|---|
-| `stdout` | Primary command output: generated text, rendered tables, `gate` PASS/FAIL check results, `review` PASS/FAIL results, `--dry-run` previews |
-| `stderr` | Diagnostic messages: progress indicators, warnings, error details, AI agent invocation logs |
+| `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 results to `stdout`, making them suitable for use in CI pipelines where stdout is captured and evaluated by automated tooling.
+`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

@@ -4,7 +4,7 @@
 
 <!-- {{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 the configuration files and customization options available in sdd-forge, including project settings, AI provider definitions, document style controls, and multi-project management. Understanding these options allows you to tailor the tool's behavior to your team's workflow, language preferences, and existing AI infrastructure.
+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
 
@@ -12,41 +12,41 @@ This chapter covers the configuration files and customization options available
 
 <!-- {{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 generated state files are stored under the `.sdd-forge/` directory at the working root of your project. The table below lists each file, its location, and its purpose.
+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 providers, document style, and workflow settings. Required before most commands can run. |
-| `context.json` | `.sdd-forge/context.json` | Free-form project context string passed to AI agents as supplementary background information. Takes priority over `textFill.projectContext` in `config.json`. |
-| `projects.json` | `.sdd-forge/projects.json` | Multi-project registry. Created by `sdd-forge setup`. Maps project names to their source and working root paths. |
-| `current-spec` | `.sdd-forge/current-spec` | JSON file tracking the active SDD flow state, including the spec path, base branch, and feature branch. Deleted at flow completion. |
-| `analysis.json` | `.sdd-forge/output/analysis.json` | Full source code analysis result produced by `sdd-forge scan`. Stored in compact JSON (no indentation). |
-| `summary.json` | `.sdd-forge/output/summary.json` | Lightweight version of `analysis.json` optimized for AI input. Used in preference to `analysis.json` by commands such as `forge`, `agents`, and `init`. |
+| `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 (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 following table describes every supported field in `.sdd-forge/config.json`. Fields marked **Required** must be present for the tool to operate correctly.
+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 documentation (e.g., `["ja"]`, `["en", "ja"]`). |
-| `output.default` | ✅ | `string` | — | The primary language used when generating documentation (e.g., `"ja"`). |
-| `output.mode` | — | `"translate"` \| `"generate"` | `"translate"` | How non-default languages are produced. `translate` derives them from the default-language output; `generate` produces them independently. |
-| `lang` | ✅ | `string` | — | Operating language for the CLI, AGENTS.md, skill prompts, and spec files (e.g., `"ja"`, `"en"`). |
-| `type` | ✅ | `string` | — | Project type identifier that selects the matching preset (e.g., `"webapp/cakephp2"`, `"cli/node-cli"`). |
-| `uiLang` | — | `"en"` \| `"ja"` | — | Language used for CLI interface messages. |
-| `documentStyle.purpose` | — | `string` | — | Describes the intended audience and purpose of the generated documentation. |
-| `documentStyle.tone` | — | `"polite"` \| `"formal"` \| `"casual"` | — | Controls the writing style applied by the AI when generating documentation text. |
-| `documentStyle.customInstruction` | — | `string` | — | Additional free-form instructions passed to the AI agent during text generation. |
-| `textFill.projectContext` | — | `string` | — | A brief description of the project used as supplementary context for AI generation. Overridden by `context.json` if present. |
-| `textFill.preamblePatterns` | — | `object[]` | — | Patterns used to strip unwanted preamble text from LLM output before it is written to documentation files. |
-| `defaultAgent` | — | `string` | — | The key name of the AI provider defined in `providers` to use when no explicit `--agent` flag is given. |
-| `providers` | — | `object` | — | A 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 and merging the feature branch back to the base branch. |
-| `limits.concurrency` | — | `number` | `5` | Number of files processed in parallel during documentation generation. |
-| `limits.designTimeoutMs` | — | `number` | — | Maximum time in milliseconds allowed for a single AI agent call before it is considered timed out. |
+| `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
 
@@ -54,7 +54,7 @@ The following table describes every supported field in `.sdd-forge/config.json`.
 
 **1. AI Provider Settings**
 
-The `providers` field lets you register one or more AI agents and control how sdd-forge invokes them. Each provider entry specifies the executable command, the argument list (use `{{PROMPT}}` as a placeholder for the prompt — if omitted it is appended automatically), an optional timeout, and how the system prompt is passed.
+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
 {
@@ -62,7 +62,7 @@ The `providers` field lets you register one or more AI agents and control how sd
   "providers": {
     "claude": {
       "command": "claude",
-      "args": ["--model", "claude-opus-4-5", "-p", "{{PROMPT}}"],
+      "args": ["--model", "claude-opus-4-5", "{{PROMPT}}"],
       "timeoutMs": 180000,
       "systemPromptFlag": "--system-prompt"
     }
@@ -70,23 +70,25 @@ The `providers` field lets you register one or more AI agents and control how sd
 }
 ```
 
+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` block shapes the tone and focus of every AI-generated text section. Set `purpose` to describe who will read the documentation, `tone` to control formality, and `customInstruction` to pass any project-specific writing rules directly to the AI.
+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 onboarding to the project",
+    "purpose": "Internal reference for backend engineers",
     "tone": "formal",
-    "customInstruction": "Always use active voice and avoid passive constructions."
+    "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 documentation template structure is applied. Choose the value that best matches your project's architecture.
+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
 {
@@ -94,11 +96,11 @@ The `type` field selects the preset that determines which source files are scann
 }
 ```
 
-Available preset keys include `webapp/cakephp2`, `webapp/laravel`, `webapp/symfony`, and `cli/node-cli`. Use `sdd-forge presets` to list all available options.
+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 integrated into the base branch at the end of an SDD workflow. `squash` (the default) combines all commits into one clean commit; `ff-only` requires a linear history; `merge` creates a standard merge commit.
+The `flow.merge` field controls how feature branches are merged into the base branch at the end of an SDD flow.
 
 ```json
 {
@@ -108,14 +110,17 @@ The `flow.merge` field controls how feature branches are integrated into the bas
 }
 ```
 
+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**
 
-The `limits.concurrency` field sets the number of source files processed in parallel during documentation generation. Increase this value on machines with sufficient resources to speed up large codebases, or decrease it to reduce memory pressure.
+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": 10
+    "concurrency": 3,
+    "designTimeoutMs": 240000
   }
 }
 ```
@@ -124,10 +129,8 @@ The `limits.concurrency` field sets the number of source files processed in para
 
 <!-- {{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).}} -->
 
-The following environment variables influence the behavior of sdd-forge at runtime. They are typically set automatically by the tool itself during command execution, but can also be specified manually when integrating sdd-forge into scripts or CI pipelines.
-
-| Variable | Direction | Description |
-|---|---|---|
-| `SDD_SOURCE_ROOT` | Input | Absolute path to the root of the source code being analyzed. When set, overrides the path resolved from `projects.json` or the current working directory. |
-| `SDD_WORK_ROOT` | Input | Absolute path to the working root — the directory that contains `.sdd-forge/`. When set, all config, output, and state files are read from and written to this location. |
-| `CLAUDECODE` | Internal | An environment variable that sdd-forge actively **removes** before spawning AI agent processes. This prevents the Claude CLI from entering an interactive mode and hanging when standard input is closed. |
+| 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. |