Organize v1 documentation

TDanks2000 · TDanks2000 · commit b04f99799584 · 2026-05-11T16:49:33.000+01:00
diff --git a/README.md b/README.md
@@ -135,13 +135,13 @@ Some options add commands. For example, `--addons turborepo` adds `bun run check
 ## Docs
 
 - [Docs index](./docs/README.md): where to start.
-- [CLI reference](./docs/cli.md): every command and operational flag.
-- [Stack options](./docs/options.md): what each option adds and where to find it after scaffolding.
-- [Generated project guide](./docs/generated-project.md): file structure, app lifecycle, and maintenance workflow.
-- [Add command](./docs/add-command.md): how to grow an existing generated app.
-- [Manifest reference](./docs/manifest.md): `ces.json` fields and schema.
-- [Templates](./docs/templates.md): how template overlays are organized.
-- [V1 release plan](./docs/v1-plan.md): release gates for moving from pre-release to `1.0.0`.
+- [CLI reference](./docs/reference/cli.md): every command and operational flag.
+- [Stack options](./docs/reference/options.md): what each option adds and where to find it after scaffolding.
+- [Manifest reference](./docs/reference/manifest.md): `ces.json` fields and schema.
+- [Generated project guide](./docs/guides/generated-project.md): file structure, app lifecycle, and maintenance workflow.
+- [Add command](./docs/guides/add-command.md): how to grow an existing generated app.
+- [Templates](./docs/internals/templates.md): how template overlays are organized.
+- [V1 release plan](./docs/roadmap/v1-plan.md): release gates for moving from pre-release to `1.0.0`.
 - [LLM guide](./docs/llm.txt): compact agent-oriented reference.
 
 ## Development
diff --git a/docs/README.md b/docs/README.md
@@ -4,33 +4,43 @@ This folder is the durable reference for `create-electrobun-stack`. It is meant
 
 ## Start Here
 
-- [CLI reference](./cli.md) covers commands, flags, defaults, and examples.
-- [Stack options](./options.md) explains each scaffold option, what files it affects, and the combinations that are valid.
-- [Generated project guide](./generated-project.md) explains the app that gets created and how to work in it after scaffolding.
-- [Add command](./add-command.md) explains how existing generated apps are expanded through `ces.json`.
-- [Manifest reference](./manifest.md) documents `ces.json` and links to the JSON schema.
-- [Templates](./templates.md) explains the template overlay structure used by the generator.
-- [V1 release plan](./v1-plan.md) tracks the work needed to move from pre-release to `1.0.0`.
+- [CLI reference](./reference/cli.md) covers commands, flags, defaults, and examples.
+- [Stack options](./reference/options.md) explains each scaffold option, what files it affects, and the combinations that are valid.
+- [Manifest reference](./reference/manifest.md) documents `ces.json` and links to the JSON schema.
+- [Generated project guide](./guides/generated-project.md) explains the app that gets created and how to work in it after scaffolding.
+- [Add command](./guides/add-command.md) explains how existing generated apps are expanded through `ces.json`.
+- [Templates](./internals/templates.md) explains the template overlay structure used by the generator.
+- [V1 release plan](./roadmap/v1-plan.md) tracks the work needed to move from pre-release to `1.0.0`.
 - [LLM guide](./llm.txt) is a compact plain-text summary for agents and retrieval systems.
 
+## Folder Map
+
+- `reference/` holds stable CLI, option, and manifest contracts.
+- `guides/` holds task-oriented docs for working with generated projects.
+- `internals/` holds contributor-facing implementation docs.
+- `roadmap/` holds planning docs and release gates.
+- `ces.schema.json` stays at the docs root because generated manifests point at that public path.
+- `llm.txt` stays at the docs root as the compact retrieval entrypoint.
+
 ## Recommended Reading Path
 
 For a first app:
 
 1. Read the root [README](../README.md).
-2. Use [CLI reference](./cli.md) for commands.
-3. Use [Stack options](./options.md) before choosing optional integrations.
-4. Use [Generated project guide](./generated-project.md) once the app exists.
+2. Use [CLI reference](./reference/cli.md) for commands.
+3. Use [Stack options](./reference/options.md) before choosing optional integrations.
+4. Use [Generated project guide](./guides/generated-project.md) once the app exists.
 
 For contributing to the generator:
 
-1. Read [Templates](./templates.md) to understand `base` and option overlays.
-2. Read [Manifest reference](./manifest.md) before changing `ces.json`.
+1. Read [Templates](./internals/templates.md) to understand `base` and option overlays.
+2. Read [Manifest reference](./reference/manifest.md) before changing `ces.json`.
 3. Update [LLM guide](./llm.txt) when user-facing options or behavior changes.
 
 ## Documentation Rules
 
-- Keep this folder flat unless a topic becomes large enough to justify a subfolder.
+- Place new docs in the folder that matches the reader: `reference/`, `guides/`, `internals/`, or `roadmap/`.
+- Add a new top-level docs file only for stable public paths or machine-readable entrypoints.
 - Prefer exact flag names, generated paths, and commands over broad descriptions.
 - Document what exists now. Mark future ideas as future work only when they are relevant to current behavior.
-- When adding a scaffold option, update `cli.md`, `options.md`, `generated-project.md` if generated files change, `manifest.md` if manifest fields change, `templates.md` if template layout changes, and `llm.txt`.
+- When adding a scaffold option, update `reference/cli.md`, `reference/options.md`, `guides/generated-project.md` if generated files change, `reference/manifest.md` if manifest fields change, `internals/templates.md` if template layout changes, and `llm.txt`.
diff --git a/docs/guides/add-command.md b/docs/guides/add-command.md
diff --git a/docs/guides/generated-project.md b/docs/guides/generated-project.md
@@ -169,4 +169,4 @@ Before distributing an app generated by this stack:
 - Node engine mismatch: use Node.js `>=20.19.0` when running the published generator through npm or npx.
 - Electrobun platform support: run and package generated apps on a desktop OS supported by Electrobun.
 - Package manager install failures: rerun the generated install command shown in the README, then rerun typecheck and build.
-- Unsupported option combinations: rerun the generator or `add` command with a supported combination from [Stack Options](./options.md).
+- Unsupported option combinations: rerun the generator or `add` command with a supported combination from [Stack Options](../reference/options.md).
diff --git a/docs/internals/templates.md b/docs/internals/templates.md
@@ -150,6 +150,6 @@ When adding a scaffold option:
 4. Add template data in `src/scaffold.ts`.
 5. Add a new option directory only when the option needs new files or an overlay.
 6. Update tests in `tests/cli.test.ts`.
-7. Update `README.md`, `docs/cli.md`, `docs/options.md`, `docs/generated-project.md`, `docs/manifest.md`, and `docs/llm.txt`.
+7. Update `README.md`, `docs/reference/cli.md`, `docs/reference/options.md`, `docs/guides/generated-project.md`, `docs/reference/manifest.md`, and `docs/llm.txt`.
 
 Keep option overlays narrow. A template directory should own a feature, not a broad refactor of unrelated base files.
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
diff --git a/docs/reference/manifest.md b/docs/reference/manifest.md
@@ -9,7 +9,7 @@ The manifest is used for:
 - Letting `create-electrobun-stack add` expand the project later.
 - Giving tools and LLMs a structured source of truth for generated features.
 
-The schema is published in this repository at [ces.schema.json](./ces.schema.json). Generated manifests point `$schema` at the package version on unpkg.
+The schema is published in this repository at [ces.schema.json](../ces.schema.json). Generated manifests point `$schema` at the package version on unpkg.
 
 ## Compatibility Policy
 
@@ -170,5 +170,5 @@ If a new stack option is added to the generator, update:
 - `src/manifest.ts`
 - `docs/ces.schema.json`
 - This page
-- `docs/options.md`
+- `docs/reference/options.md`
 - `docs/llm.txt`
diff --git a/docs/reference/options.md b/docs/reference/options.md
diff --git a/docs/roadmap/v1-plan.md b/docs/roadmap/v1-plan.md
@@ -30,19 +30,19 @@ The release is ready when:
 
 Goal: decide what V1 promises and avoid accidental breaking changes after release.
 
-Status: completed in the repo. Evidence lives in `docs/cli.md`, `docs/options.md`, `docs/manifest.md`, `docs/add-command.md`, `src/cli.ts`, `src/prompts.ts`, and `tests/cli.test.ts`.
+Status: completed in the repo. Evidence lives in `docs/reference/cli.md`, `docs/reference/options.md`, `docs/reference/manifest.md`, `docs/guides/add-command.md`, `src/cli.ts`, `src/prompts.ts`, and `tests/cli.test.ts`.
 
 - Freeze the V1 CLI command shape:
   - `create-electrobun-stack <project>`
   - `create-electrobun-stack add`
   - `--dry-run`, `--yes`, `--cwd`, `--install`, `--git`, and stack flags.
-- Mark the V1-supported stack options in `docs/options.md`.
+- Mark the V1-supported stack options in `docs/reference/options.md`.
 - Decide whether `minimal`, `standard`, and `full` should remain aliases for V1 or whether only `minimal` should be advertised.
 - Document the compatibility rules for `ces.json`:
   - V1 manifests are additive.
   - Existing generated apps should keep working with future `add` features.
   - Breaking manifest migrations require a documented migration path.
-- Add a short compatibility policy to `docs/manifest.md`.
+- Add a short compatibility policy to `docs/reference/manifest.md`.
 
 Exit criteria:
 
@@ -54,7 +54,7 @@ Exit criteria:
 
 Goal: make the stack chooser feel complete before V1 without adding new categories or padding the CLI with weak options.
 
-Status: scoped for V1. The option set includes multiple meaningful choices in the categories that are ready for V1, and intentionally narrow categories are documented in `docs/options.md`. Post-V1 option expansion is tracked in GitHub issue #3.
+Status: scoped for V1. The option set includes multiple meaningful choices in the categories that are ready for V1, and intentionally narrow categories are documented in `docs/reference/options.md`. Post-V1 option expansion is tracked in GitHub issue #3.
 
 Use these rules for the V1 option depth pass:
 
@@ -165,10 +165,10 @@ Goal: make the first-run path clear and keep generated project docs accurate.
 Status: completed for the pre-RC documentation pass. The V1 public contract, option boundaries, manifest compatibility, generated-project lifecycle, troubleshooting notes, release checks, and changelog are represented in docs. The generated-project guide now reflects the actual default layout, including route, menu, and test files. The final pass should be repeated after RC feedback and before `1.0.0`.
 
 - Verify root README commands against the packed package.
-- Keep `docs/cli.md` aligned with `parseArgs`.
-- Keep `docs/options.md` aligned with `src/options.ts`.
-- Keep `docs/manifest.md` and `docs/ces.schema.json` aligned with generated manifests.
-- Make `docs/generated-project.md` describe the actual default app lifecycle.
+- Keep `docs/reference/cli.md` aligned with `parseArgs`.
+- Keep `docs/reference/options.md` aligned with `src/options.ts`.
+- Keep `docs/reference/manifest.md` and `docs/ces.schema.json` aligned with generated manifests.
+- Make `docs/guides/generated-project.md` describe the actual default app lifecycle.
 - Update `docs/llm.txt` after any option or behavior change.
 - Add troubleshooting notes for:
   - Bun version mismatch,
