Test/107 110 generator registry tests troubleshooting docs

README.md

@@ -150,7 +150,7 @@ See [SECURITY.md](SECURITY.md), the [threat model](docs/architecture/threat-mode
 
 `stellarforge add`, plugin architecture, remote template registries, and Mainnet deployment are **not implemented** and remain post-v1 or separately reviewed candidates.
 
-See [Quick Start](docs/guides/quick-start.md), [Command Reference](docs/reference/commands.md), [Configuration](docs/reference/configuration.md), and [Troubleshooting](docs/reference/troubleshooting.md).
+See [Quick Start](docs/guides/quick-start.md), [Command Reference](docs/reference/commands.md), [Configuration](docs/reference/configuration.md), [Troubleshooting](docs/reference/troubleshooting.md#find-your-problem), [Platform Support](docs/reference/platform-support.md), and [Exit Codes](docs/reference/exit-codes.md).
 
 ---
 

docs/guides/installation.md

@@ -83,3 +83,7 @@ The release workflow is designed around:
 The npm namespace, Trusted Publisher, protected GitHub environment, and Dependency Graph are configured. `NPM_PUBLISH_ENABLED` remains `false` as a deliberate kill switch. REL-001 remains open only for the first approved protected OIDC publication and its npm/tag/GitHub Release/provenance verification.
 
 See [Release Process](../contributing/release-process.md) for the complete release contract.
+
+## Troubleshooting
+
+If installation or local setup fails, see [Troubleshooting](../reference/troubleshooting.md#installation-or-setup-fails). Runtime and operating-system expectations are in [Platform Support](../reference/platform-support.md), and exit codes are defined in the [Exit Code Policy](../reference/exit-codes.md).

docs/guides/quick-start.md

@@ -23,6 +23,8 @@ stellarforge new my-stack --template full-stack
 
 Supported template IDs are `basic-app`, `full-stack`, `smart-contract`, and `api-service`.
 
+If creation fails, see [`new` troubleshooting](../reference/troubleshooting.md#stellarforge-new-cannot-create-the-project) and [Project name is rejected](../reference/troubleshooting.md#project-name-is-rejected).
+
 ## 2. Validate your environment
 
 ```bash
@@ -31,6 +33,8 @@ stellarforge doctor
 
 The command checks the supported local toolchain and prints remediation guidance. A failed required diagnostic exits with code `5`.
 
+If diagnostics fail, see [`doctor` troubleshooting](../reference/troubleshooting.md#stellarforge-doctor-reports-failures).
+
 ## 3. Run local development
 
 From a supported generated Node.js project:
@@ -41,6 +45,8 @@ stellarforge dev
 
 StellarForge looks for a supported npm development script: `dev`, then `start`, then `start:backend`.
 
+If no script is found, see [`dev` troubleshooting](../reference/troubleshooting.md#stellarforge-dev-says-no-supported-script-exists).
+
 ## 4. Run tests
 
 ```bash
@@ -49,6 +55,8 @@ stellarforge test
 
 Node.js projects use `npm run test`; Cargo projects use `cargo test`.
 
+If no workflow is found, see [`test` troubleshooting](../reference/troubleshooting.md#stellarforge-test-cannot-find-a-workflow).
+
 ## 5. Configure Testnet deployment
 
 For a smart-contract project, create `stellarforge.config.json` at the project root:
@@ -65,6 +73,8 @@ The identity must already exist in Stellar CLI identity management. Do not place
 
 See the [Configuration Reference](../reference/configuration.md).
 
+If the file is rejected, see [Configuration troubleshooting](../reference/troubleshooting.md#configuration-file-is-rejected).
+
 ## 6. Deploy to Testnet
 
 ```bash
@@ -79,9 +89,13 @@ stellarforge deploy --network testnet --source deployer
 
 The MVP deployment path is Testnet-only. Mainnet deployment is not implemented.
 
+If deployment fails, see [network required](../reference/troubleshooting.md#deployment-network-is-required), [Mainnet or Futurenet rejection](../reference/troubleshooting.md#deployment-rejects-mainnet-or-futurenet), [identity rejected](../reference/troubleshooting.md#deployment-identity-is-rejected), or [Stellar CLI deployment fails](../reference/troubleshooting.md#stellar-cli-deployment-fails).
+
 ## Next references
 
 - [Command Reference](../reference/commands.md)
-- [Troubleshooting](../reference/troubleshooting.md)
+- [Troubleshooting](../reference/troubleshooting.md#find-your-problem)
+- [Installation](installation.md)
+- [Platform Support](../reference/platform-support.md)
 - [Exit Code Policy](../reference/exit-codes.md)
 - [Security Policy](../../SECURITY.md)

docs/reference/commands.md

@@ -15,7 +15,7 @@ This reference documents the implemented StellarForge CLI MVP command surface.
 | `stellarforge deploy` | Deploy a supported smart-contract project to Stellar Testnet | Implemented |
 | `stellarforge add` | Add modules/plugins | Not implemented / post-v1 candidate |
 
-See also [Installation](../guides/installation.md), [Quick Start](../guides/quick-start.md), [Configuration](configuration.md), [Exit Codes](exit-codes.md), [Troubleshooting](troubleshooting.md), and the repository [security guidance](../../SECURITY.md).
+See also [Installation](../guides/installation.md), [Quick Start](../guides/quick-start.md), [Configuration](configuration.md), [Exit Codes](exit-codes.md), [Troubleshooting](troubleshooting.md#find-your-problem), [Platform Support](platform-support.md), and the repository [security guidance](../../SECURITY.md).
 
 ## Global command behavior
 
@@ -83,6 +83,8 @@ See [Template Generation Safety](template-generation.md).
 
 These are validation failures and exit with code `2`.
 
+See [Troubleshooting](troubleshooting.md#stellarforge-new-cannot-create-the-project) and [Project name is rejected](troubleshooting.md#project-name-is-rejected).
+
 ## `stellarforge doctor`
 
 Runs the registered development-environment diagnostics.
@@ -106,6 +108,8 @@ Warnings do not by themselves make the command fail.
 
 The command does not print complete sensitive environment values.
 
+See [Troubleshooting](troubleshooting.md#stellarforge-doctor-reports-failures) when diagnostics fail.
+
 ## `stellarforge dev`
 
 Starts the supported local-development workflow for a generated Node.js StellarForge project.
@@ -137,6 +141,8 @@ Child stdout/stderr are streamed with process labels.
 
 Validation failures use code `2`; failed child processes use code `3`.
 
+See [Troubleshooting](troubleshooting.md#stellarforge-dev-says-no-supported-script-exists).
+
 ## `stellarforge test`
 
 Runs the supported project test workflow.
@@ -163,6 +169,8 @@ StellarForge does not execute package script text directly. It delegates through
 - `2` — project/test configuration is unsupported or invalid;
 - `3` — the test subprocess fails.
 
+See [Troubleshooting](troubleshooting.md#stellarforge-test-cannot-find-a-workflow).
+
 ## `stellarforge deploy`
 
 Deploys a supported smart-contract Cargo project to **Stellar Testnet**.
@@ -222,7 +230,7 @@ No shell interpolation is used. Signing material remains under Stellar CLI ident
 - `2` — configuration, project layout, network, or identity input is invalid;
 - `3` — Stellar CLI fails to start or returns a failure.
 
-See [Configuration](configuration.md) and [Troubleshooting](troubleshooting.md).
+See [Configuration](configuration.md) and the deployment sections of [Troubleshooting](troubleshooting.md#deployment-network-is-required): [network required](troubleshooting.md#deployment-network-is-required), [Mainnet or Futurenet rejection](troubleshooting.md#deployment-rejects-mainnet-or-futurenet), [identity rejected](troubleshooting.md#deployment-identity-is-rejected), and [Stellar CLI deployment fails](troubleshooting.md#stellar-cli-deployment-fails).
 
 ## Unsupported or planned behavior
 

docs/reference/configuration.md

@@ -63,3 +63,5 @@ The file must:
 - contain only supported schema fields.
 
 Validation failures are designed to be actionable without echoing raw file contents or sensitive values.
+
+If the file is rejected, see [Troubleshooting](troubleshooting.md#configuration-file-is-rejected). For deployment settings, see [Deployment network is required](troubleshooting.md#deployment-network-is-required) and [Deployment identity is rejected](troubleshooting.md#deployment-identity-is-rejected).

docs/reference/exit-codes.md

@@ -15,6 +15,17 @@ StellarForge CLI uses predictable process exit codes so humans, scripts, and CI
 
 These values are part of the CLI contract and should not be changed casually. New stable categories require deliberate review and documentation.
 
+## Troubleshooting by Exit Code
+
+| Exit code | Start here |
+|---:|---|
+| `2` | [Usage](troubleshooting.md#command-or-option-is-not-recognized), [`new`](troubleshooting.md#stellarforge-new-cannot-create-the-project), [project name](troubleshooting.md#project-name-is-rejected), [configuration](troubleshooting.md#configuration-file-is-rejected), [deployment network](troubleshooting.md#deployment-network-is-required), or [deployment identity](troubleshooting.md#deployment-identity-is-rejected) |
+| `3` | [`dev`](troubleshooting.md#stellarforge-dev-says-no-supported-script-exists), [`test`](troubleshooting.md#stellarforge-test-cannot-find-a-workflow), or [Stellar CLI deployment](troubleshooting.md#stellar-cli-deployment-fails) |
+| `5` | [`doctor`](troubleshooting.md#stellarforge-doctor-reports-failures) |
+| `1` or `4` | [Unexpected or internal failure](troubleshooting.md#unexpected-or-internal-failure) |
+
+The full index is at [Troubleshooting](troubleshooting.md#find-your-problem).
+
 ## Rendering Rules
 
 - user-facing failures are written to stderr unless a command intentionally renders a structured report to stdout;

docs/reference/platform-support.md

@@ -55,3 +55,7 @@ A green platform job validates StellarForge's code and tests on that OS; it does
 A failing Linux, macOS, or Windows matrix job blocks merge/release for changes that affect the supported CLI surface. A failure may be waived only through an explicit project decision that documents the affected platform, reason, user impact, and follow-up plan.
 
 Platform-specific failures must not be hidden with `continue-on-error` in the supported matrix.
+
+## Troubleshooting
+
+For installation and setup failures, see [Troubleshooting](troubleshooting.md#installation-or-setup-fails). Runtime and tool requirements are in [Installation](../guides/installation.md#contributor-prerequisites), and exit codes are defined in [Exit Codes](exit-codes.md).

docs/reference/template-generation.md

@@ -17,3 +17,5 @@ StellarForge generates projects from project-controlled template directories onl
 If validation, copying, or substitution fails before promotion, the staging directory is removed and the final destination is left untouched. Existing non-empty destinations are never overwritten. An existing empty destination may be used, and if promotion fails after that empty directory is removed, StellarForge recreates the empty destination before returning the error.
 
 This model deliberately favors conservative failure over partial generation or implicit overwrite behavior.
+
+If generation is refused, see [Troubleshooting](troubleshooting.md#stellarforge-new-cannot-create-the-project) and [Project name is rejected](troubleshooting.md#project-name-is-rejected).