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

package/README.md

@@ -1,24 +1,24 @@
-# <!-- {{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. The API, command structure, and configuration format may change without notice. Please avoid using it in production environments.
 
 **A CLI tool that automatically generates and maintains project documentation using 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
-- **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
+- **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.
 
 ## Quick Start
 
@@ -26,28 +26,28 @@ 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
+{{data: project.name("")}}sdd-forge{{/data}} build
 </pre>
 
-This alone generates `docs/` and `README.md`.
+This is all it takes to generate `docs/` and `README.md`.
 
-## Commands
+## Command Reference
 
 ### Document Generation
 
@@ -57,12 +57,12 @@ This alone generates `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 analysis data |
+| `data` | Resolve `{{data}}` directives with analyzed 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` | Multi-language translation (default language → other languages) |
+| `translate` | Multilingual 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 |
@@ -85,12 +85,12 @@ This alone generates `docs/` and `README.md`.
 
 ## SDD Workflow
 
-The feature addition / change flow:
+The flow for adding features or making changes:
 
 ```
   spec          Create a spec (feature branch + spec.md)
     ↓
-  gate          Spec gate check (PASS when no open issues)
+  gate          Spec gate check (PASS when no unresolved items)
     ↓
   implement     Write code after gate PASS
     ↓
@@ -112,7 +112,7 @@ Run the SDD workflow with skills:
 
 #### Codex CLI
 
-Run the workflow from prompts:
+Run the workflow from a prompt:
 
 ```
 $sdd-flow-start   — Start spec creation → gate → implementation
@@ -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 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… |
 | [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,87 @@
 
 <!-- {{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.
+
 ## 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 / 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]
+```
+
 ### 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` | 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 |
+
 ### 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, 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 |
+
+`sdd-forge` has no network-based external dependencies. All integrations are process-level and operate entirely within the local development environment.
+
 ### 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.
+
+| 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 |

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 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.
+
 ## 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` | 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 | — |
 
 ### 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 | Alias | 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`). |
+
+> **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`.
 
 ### 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.}} -->
 
+#### 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 Codes**
+
+| 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 |
+
+**stdout / stderr Rules**
+
+| 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 |
+
+> `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.

package/docs/03_configuration.md

@@ -2,22 +2,132 @@
 
 ## 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 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.
 
 ## 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 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.
+
+| 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`. |
 
 ### 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 following table describes every supported field in `.sdd-forge/config.json`. Fields marked **Required** must be present for the tool to operate correctly.
+
+| 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. |
 
 ### 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 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.
+
+```json
+{
+  "defaultAgent": "claude",
+  "providers": {
+    "claude": {
+      "command": "claude",
+      "args": ["--model", "claude-opus-4-5", "-p", "{{PROMPT}}"],
+      "timeoutMs": 180000,
+      "systemPromptFlag": "--system-prompt"
+    }
+  }
+}
+```
+
+**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.
+
+```json
+{
+  "documentStyle": {
+    "purpose": "Internal reference for backend engineers onboarding to the project",
+    "tone": "formal",
+    "customInstruction": "Always use active voice and avoid passive constructions."
+  }
+}
+```
+
+**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.
+
+```json
+{
+  "type": "cli/node-cli"
+}
+```
+
+Available preset keys include `webapp/cakephp2`, `webapp/laravel`, `webapp/symfony`, and `cli/node-cli`. Use `sdd-forge presets` to list all available options.
+
+**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.
+
+```json
+{
+  "flow": {
+    "merge": "squash"
+  }
+}
+```
+
+**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.
+
+```json
+{
+  "limits": {
+    "concurrency": 10
+  }
+}
+```
 
 ### 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).}} -->
+
+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. |

package/docs/04_internal_design.md

@@ -2,26 +2,199 @@
 
 ## Overview
 
-<!-- {{text: Describe the purpose of this chapter in 1–2 sentences. Cover the project structure, module dependency direction, and key processing flows.}} -->
+<!-- {{text: Describe the purpose of this chapter in 1–2 sentences. Cover the project structure, direction of module dependencies, and key processing flows.}} -->
+
+This chapter describes the internal architecture of sdd-forge, covering the directory layout, module responsibilities, and dependency relationships. It also documents the key processing flows that run when core commands such as `build` and `forge` are executed.
 
 ## Contents
 
 ### Project Structure
 
-<!-- {{text: Describe the directory structure of this project in a tree-format code block. Include role comments for major directories and files. Cover the dispatchers directly under src/ (sdd-forge.js, docs.js, spec.js, flow.js), docs/commands/ (subcommand implementations), docs/lib/ (document generation library), lib/ (shared utilities), presets/ (preset definitions), and templates/ (bundled templates).}} -->
+<!-- {{text: Describe the directory structure of this project in a tree-format code block. Include role comments for major directories and files. Cover the top-level dispatchers under src/ (sdd-forge.js, docs.js, spec.js, flow.js), docs/commands/ (subcommand implementations), docs/lib/ (document generation libraries), lib/ (shared utilities), presets/ (preset definitions), and templates/ (bundled templates).}} -->
+
+```
+sdd-forge/
+├── package.json                        ← Package manifest; bin entry points to src/sdd-forge.js
+├── src/
+│   ├── sdd-forge.js                    ← Top-level CLI entry point; routes to docs.js / spec.js / flow.js
+│   ├── docs.js                         ← Dispatcher for all docs-related subcommands
+│   ├── spec.js                         ← Dispatcher for spec and gate subcommands
+│   ├── flow.js                         ← SDD flow automation (DIRECT_COMMAND, no sub-routing)
+│   ├── presets-cmd.js                  ← Dispatcher for the presets subcommand
+│   ├── help.js                         ← Renders the command reference to stdout
+│   ├── docs/
+│   │   ├── commands/                   ← One file per docs subcommand (scan, init, data, text,
+│   │   │                                  readme, forge, review, agents, changelog, setup, …)
+│   │   ├── data/                       ← DataSource implementations (project.js, docs.js,
+│   │   │                                  agents.js, lang.js)
+│   │   └── lib/                        ← Document-generation library (scanner, directive-parser,
+│   │                                      template-merger, renderers, forge-prompts, text-prompts,
+│   │                                      data-source, data-source-loader, resolver-factory, …)
+│   ├── specs/
+│   │   └── commands/                   ← Spec subcommand implementations (init, gate)
+│   ├── lib/                            ← Shared utilities (agent, cli, config, flow-state,
+│   │                                      presets, i18n, process, projects, types)
+│   ├── presets/                        ← Preset definitions; each subdirectory holds preset.json
+│   │   ├── base/                       ← Base preset + doc templates (ja/en)
+│   │   ├── webapp/, cli/, library/     ← Architecture-layer presets
+│   │   ├── cakephp2/, laravel/, symfony/ ← Framework-specific presets
+│   │   ├── node-cli/                   ← Node.js CLI preset
+│   │   └── lib/                        ← Shared preset utilities (composer-utils.js)
+│   └── templates/                      ← Bundled project templates (config.example.json,
+│                                          review-checklist.md, SDD skill scripts)
+├── docs/                               ← sdd-forge's own design documentation (published to npm)
+├── tests/                              ← Test files (*.test.js, Node.js built-in test runner)
+└── specs/                              ← Accumulated SDD spec files (020+ entries)
+```
 
 ### Module Overview
 
 <!-- {{text: List the major modules in a table format. Include module name, file path, and responsibility. Cover the dispatcher layer (sdd-forge.js, docs.js, spec.js), command layer (docs/commands/*.js, specs/commands/*.js), library layer (lib/agent.js, lib/cli.js, lib/config.js, lib/flow-state.js, lib/presets.js, lib/i18n.js), and document generation layer (docs/lib/scanner.js, directive-parser.js, template-merger.js, forge-prompts.js, text-prompts.js, review-parser.js, data-source.js, resolver-factory.js).}} -->
 
+| Module | File Path | Responsibility |
+|---|---|---|
+| **CLI Entry Point** | `src/sdd-forge.js` | Parses the top-level subcommand, resolves project context via env vars, and routes to the appropriate dispatcher |
+| **Docs Dispatcher** | `src/docs.js` | Routes docs-related subcommands (`build`, `scan`, `init`, `data`, `text`, `readme`, `forge`, `review`, `changelog`, `agents`, `setup`, …) to their command files |
+| **Spec Dispatcher** | `src/spec.js` | Routes `spec` and `gate` subcommands to their command files |
+| **Flow Command** | `src/flow.js` | Executes the end-to-end SDD workflow automation as a single DIRECT_COMMAND |
+| **Scan Command** | `src/docs/commands/scan.js` | Invokes the scanner on the source tree and writes `analysis.json` / `summary.json` |
+| **Data Command** | `src/docs/commands/data.js` | Resolves `{{data}}` directives in doc templates using DataSource implementations |
+| **Text Command** | `src/docs/commands/text.js` | Resolves `{{text}}` directives by invoking the configured AI agent |
+| **Forge Command** | `src/docs/commands/forge.js` | Iteratively improves docs by generating and applying AI-suggested edits |
+| **Review Command** | `src/docs/commands/review.js` | Runs the AI-powered doc quality check and parses pass/fail results |
+| **Spec Init Command** | `src/specs/commands/init.js` | Creates a new spec directory and `spec.md` scaffold, optionally creating a feature branch |
+| **Gate Command** | `src/specs/commands/gate.js` | Validates a spec against pre- or post-implementation checklists |
+| **Agent Utilities** | `src/lib/agent.js` | Wraps synchronous and asynchronous AI agent invocations; handles prompt injection and timeout management |
+| **CLI Utilities** | `src/lib/cli.js` | Provides `parseArgs()`, `repoRoot()`, `sourceRoot()`, `isInsideWorktree()`, and the `PKG_DIR` constant |
+| **Config Utilities** | `src/lib/config.js` | Loads and validates `.sdd-forge/config.json`; manages context, output, and data directory paths |
+| **Flow State** | `src/lib/flow-state.js` | Persists and retrieves the current SDD workflow state in `.sdd-forge/current-spec` |
+| **Presets Registry** | `src/lib/presets.js` | Auto-discovers `preset.json` files under `src/presets/` and exports the `PRESETS` constant |
+| **i18n** | `src/lib/i18n.js` | Loads locale strings for CLI messages and template labels |
+| **Scanner** | `src/docs/lib/scanner.js` | Traverses the source tree and extracts structural information from PHP, JS, and YAML files |
+| **Directive Parser** | `src/docs/lib/directive-parser.js` | Parses `{{data}}`, `{{text}}`, `@block`, and `@extends` directives from Markdown templates |
+| **Template Merger** | `src/docs/lib/template-merger.js` | Resolves `@extends` / `@block` template inheritance chains |
+| **Forge Prompts** | `src/docs/lib/forge-prompts.js` | Builds AI prompts for the `forge` and `agents` commands; exports `summaryToText()` |
+| **Text Prompts** | `src/docs/lib/text-prompts.js` | Builds per-directive AI prompts for the `text` command |
+| **Review Parser** | `src/docs/lib/review-parser.js` | Parses structured pass/fail results from AI review output |
+| **DataSource Base** | `src/docs/lib/data-source.js` | Abstract base class for all `{{data}}` resolver implementations |
+| **Resolver Factory** | `src/docs/lib/resolver-factory.js` | Creates the appropriate DataSource resolver for a given directive via `createResolver()` |
+
 ### Module Dependencies
 
-<!-- {{text: Generate a mermaid graph showing inter-module dependencies. Reflect the three-layer dispatch structure and show the dependency direction from dispatcher → command → library. Output only the mermaid code block.}} -->
+<!-- {{text: Generate a mermaid graph showing the dependencies between modules. Reflect the three-layer dispatch structure and show the dependency direction from dispatcher → command → library. Output only the mermaid code block.}} -->
+
+```mermaid
+graph TD
+    CLI["sdd-forge.js<br/>(Entry Point)"]
+
+    CLI --> DOCS["docs.js<br/>(Docs Dispatcher)"]
+    CLI --> SPEC["spec.js<br/>(Spec Dispatcher)"]
+    CLI --> FLOW["flow.js<br/>(Flow Command)"]
+
+    DOCS --> SCAN["docs/commands/scan.js"]
+    DOCS --> INIT_D["docs/commands/init.js"]
+    DOCS --> DATA["docs/commands/data.js"]
+    DOCS --> TEXT["docs/commands/text.js"]
+    DOCS --> FORGE["docs/commands/forge.js"]
+    DOCS --> REVIEW["docs/commands/review.js"]
+    DOCS --> AGENTS["docs/commands/agents.js"]
+    DOCS --> README["docs/commands/readme.js"]
+
+    SPEC --> SPEC_INIT["specs/commands/init.js"]
+    SPEC --> GATE["specs/commands/gate.js"]
+
+    SCAN --> SCANNER["docs/lib/scanner.js"]
+    DATA --> DIR_PARSER["docs/lib/directive-parser.js"]
+    DATA --> RESOLVER["docs/lib/resolver-factory.js"]
+    DATA --> DS["docs/lib/data-source.js"]
+    TEXT --> DIR_PARSER
+    TEXT --> TEXT_PROMPTS["docs/lib/text-prompts.js"]
+    FORGE --> FORGE_PROMPTS["docs/lib/forge-prompts.js"]
+    REVIEW --> REVIEW_PARSER["docs/lib/review-parser.js"]
+    INIT_D --> TMPL_MERGER["docs/lib/template-merger.js"]
+
+    SCAN --> CONFIG["lib/config.js"]
+    DATA --> CONFIG
+    TEXT --> CONFIG
+    FORGE --> CONFIG
+    REVIEW --> CONFIG
+    FORGE --> AGENT["lib/agent.js"]
+    TEXT --> AGENT
+    REVIEW --> AGENT
+    AGENTS --> AGENT
+
+    SPEC_INIT --> CLI_LIB["lib/cli.js"]
+    GATE --> CLI_LIB
+    SCAN --> CLI_LIB
+    FLOW --> CONFIG
+    FLOW --> CLI_LIB
+    FLOW --> FLOW_STATE["lib/flow-state.js"]
+
+    RESOLVER --> DS
+    FORGE_PROMPTS --> SCANNER
+    CLI --> CONFIG
+```
 
 ### Key Processing Flows
 
-<!-- {{text: Explain the data and control flow between modules when a representative command (build or forge) is executed, using numbered steps. Include the sequence: entry point → dispatch → config loading → analysis data preparation → AI invocation → file writing.}} -->
+<!-- {{text: Explain the inter-module data and control flow when a representative command (build or forge) is executed, using numbered steps. Include the flow from entry point → dispatch → config loading → analysis data preparation → AI invocation → file writing.}} -->
+
+**`sdd-forge build` flow**
+
+1. **Entry** — `sdd-forge.js` receives the `build` subcommand, resolves the project context (via `--project` flag or `.sdd-forge/projects.json`), and sets `SDD_SOURCE_ROOT` / `SDD_WORK_ROOT` environment variables.
+2. **Dispatch** — `docs.js` maps `build` to the ordered pipeline: `scan → init → data → text → readme`.
+3. **Config loading** — Each command calls `loadConfig()` in `lib/config.js` to read `.sdd-forge/config.json` and obtain output language settings, project type, and agent configuration.
+4. **Source scan** — `docs/commands/scan.js` invokes `scanner.js` to traverse the source tree. The result is serialised to `.sdd-forge/output/analysis.json` and a lightweight `.sdd-forge/output/summary.json`.
+5. **Template initialisation** — `docs/commands/init.js` applies `template-merger.js` to resolve `@extends` / `@block` inheritance and write the initial Markdown template files into `docs/`.
+6. **Data resolution** — `docs/commands/data.js` uses `directive-parser.js` to locate `{{data}}` directives, then calls `resolver-factory.js` to instantiate the matching DataSource. Each DataSource reads from `analysis.json` or `summary.json` and writes rendered Markdown back into the doc file.
+7. **AI text generation** — `docs/commands/text.js` locates `{{text}}` directives, builds prompts via `text-prompts.js`, and calls `callAgentAsync()` in `lib/agent.js` to stream responses from the configured AI agent. Results are written inline into the doc files.
+8. **README generation** — `docs/commands/readme.js` assembles the project README from the now-populated doc files and writes `README.md`.
+
+**`sdd-forge forge` flow**
+
+1. **Entry & dispatch** — `sdd-forge.js` → `docs.js` → `docs/commands/forge.js`.
+2. **Config & data loading** — `loadConfig()` provides agent settings; `summaryToText()` in `forge-prompts.js` converts `summary.json` into a compact textual representation for the AI prompt.
+3. **Prompt construction** — `forge-prompts.js` combines the summary text, the current doc content, and the `--prompt` argument into a structured improvement request.
+4. **AI invocation** — `callAgentAsync()` in `lib/agent.js` spawns the AI agent process with `stdin: "ignore"` to avoid EOF hangs, streaming output back via callback.
+5. **File writing** — The agent's output is parsed and written back to the target doc files, preserving content outside `{{data}}` / `{{text}}` directive blocks.
+6. **Review** — The caller is expected to subsequently run `sdd-forge review`, which uses `review-parser.js` to evaluate the updated docs and report pass/fail status.
 
 ### Extension Points
 
-<!-- {{text: Explain what needs to change and the extension patterns when adding new commands or features. Cover each of the following: (1) adding a new docs subcommand, (2) adding a new spec subcommand, (3) adding a new preset, (4) adding a new DataSource ({{data}} resolver), and (5) adding a new AI prompt.}} -->
+<!-- {{text: Explain where changes are needed and the extension patterns when adding new commands or features. Provide steps for each of the following: (1) adding a new docs subcommand, (2) adding a new spec subcommand, (3) adding a new preset, (4) adding a new DataSource ({{data}} resolver), and (5) adding a new AI prompt.}} -->
+
+**(1) Adding a new docs subcommand**
+
+1. Create `src/docs/commands/<name>.js` and export (or call at the bottom) a `main()` function.
+2. Open `src/docs.js` and add a `case '<name>':` branch that imports and invokes the new command file.
+3. Update `src/help.js` to include the new subcommand in the printed reference.
+4. Add a corresponding test file under `tests/docs/commands/`.
+
+**(2) Adding a new spec subcommand**
+
+1. Create `src/specs/commands/<name>.js` with a `main()` function.
+2. Open `src/spec.js` and add a routing entry for the new subcommand name.
+3. Update `src/help.js` with a description of the new subcommand.
+4. Add tests under `tests/specs/commands/`.
+
+**(3) Adding a new preset**
+
+1. Create a directory under `src/presets/<key>/` containing a `preset.json` that declares `type`, `arch`, `isArch`, and `chapters`.
+2. If the preset requires custom scan logic, add a DataSource file under `src/docs/data/` or directly within the preset directory.
+3. Place Markdown templates in `src/presets/<key>/templates/{ja,en}/` following the naming convention used by existing presets.
+4. The `PRESETS` constant in `src/lib/presets.js` is built by auto-discovery, so no manual registration is required.
+5. Add an alias to `src/lib/types.js` → `TYPE_ALIASES` if a short-form name is needed.
+
+**(4) Adding a new DataSource (`{{data}}` resolver)**
+
+1. Create a new class in `src/docs/data/` (or inside the relevant preset directory) that extends `DataSource` from `src/docs/lib/data-source.js` and implements the `resolve()` method.
+2. Register the new resolver key in `src/docs/lib/resolver-factory.js` inside `createResolver()` so that directive-parser matches `{{data: <key>(...)}}` to your class.
+3. Ensure the resolver reads from `.sdd-forge/output/summary.json` (falling back to `analysis.json`) rather than operating directly on source files.
+4. Add unit tests under `tests/docs/` covering the resolver's output format.
+
+**(5) Adding a new AI prompt**
+
+1. Determine whether the prompt belongs to the iterative improvement flow (`forge-prompts.js`) or the per-directive generation flow (`text-prompts.js`) and open the corresponding file in `src/docs/lib/`.
+2. Add a new exported function that accepts the relevant context (summary text, doc content, user-supplied hint) and returns a fully-formed prompt string.
+3. Import and call the new function from the command file that will use it (`forge.js`, `text.js`, or `agents.js`).
+4. If the prompt uses a system prompt, confirm whether `systemPromptFlag` in the agent config is `"--system-prompt"` or `"--system-prompt-file"` (the latter writes a temporary file) — see `lib/agent.js` for details.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sdd-forge",
-  "version": "0.1.0-alpha.23",
+  "version": "0.1.0-alpha.24",
   "description": "Spec-Driven Development tooling for automated documentation generation",
   "repository": {
     "type": "git",

package/src/docs/commands/agents.js

@@ -12,7 +12,7 @@ import path from "path";
 import { runIfDirect } from "../../lib/entrypoint.js";
 import { repoRoot, parseArgs } from "../../lib/cli.js";
 import { loadLang, sddOutputDir, resolveProjectContext } from "../../lib/config.js";
-import { callAgent, loadAgentConfig, MID_AGENT_TIMEOUT_MS } from "../../lib/agent.js";
+import { callAgent, loadAgentConfig, LONG_AGENT_TIMEOUT_MS } from "../../lib/agent.js";
 import { createI18n } from "../../lib/i18n.js";
 import { createResolver } from "../lib/resolver-factory.js";
 import { createLogger } from "../../lib/progress.js";
@@ -179,7 +179,7 @@ async function main(ctx) {
     const prompt = buildRefinePrompt(projectContent, summary, config, srcRoot, sddContent);
 
     try {
-      const result = callAgent(agent, prompt, MID_AGENT_TIMEOUT_MS, undefined, { systemPrompt });
+      const result = callAgent(agent, prompt, LONG_AGENT_TIMEOUT_MS, undefined, { systemPrompt });
 
       let refined = result.trim();