Codex-generated pull request

CONTRIBUTING.md

@@ -12,6 +12,22 @@ Thanks for your interest in improving Web Learning Kit Generator.
 3. Run the interactive generator:
    - `npm run init`
 
+## Test strategy
+
+- **Unit tests**: validate individual modules (path resolution, setup option parsing, validators).
+- **Template tests**: verify section behavior and snapshot generated gulpfile variants.
+- **Integration tests**: scaffold in a temp directory and validate expected output tree/content.
+
+## Acceptance criteria for changes
+
+A change is ready to merge when all of the following are true:
+
+- Behavior changes are covered by tests (unit/integration/snapshot as appropriate).
+- `npm run typecheck` passes.
+- `npm test` passes.
+- Docs are updated for any user-facing command or setup-flow change.
+- PR notes describe generated-project behavior changes (if any).
+
 ## Contribution guidelines
 
 - Keep changes small and focused.

README.md

@@ -79,6 +79,10 @@ npm test
 └── README.md
 ```
 
+## Generated output examples
+
+See concrete scaffold output trees here: [Generated output examples](./docs/generated-output-examples.md).
+
 ## Current quality/devops baseline
 
 This repository now includes:
@@ -89,10 +93,26 @@ This repository now includes:
 - Contributing and security documentation
 - A single runtime architecture: setup always generates one `gulpfile.js` from user choices (no parallel dynamic task runtime)
 
+## Architecture decision
+
+This project intentionally uses **one runtime path**:
+
+1. collect user choices (interactive prompts or CLI flags)
+2. scaffold source files
+3. generate a single `gulpfile.js`
+4. run gulp commands through npm scripts
+
+See ADRs for rationale and trade-offs:
+- [ADR 0001: single generated-gulpfile runtime](./docs/adr/0001-generated-gulpfile-runtime.md)
+- [ADR 0002: template composition](./docs/adr/0002-template-composition.md)
+
 ---
 
 ## Deep improvement roadmap
 
+Track roadmap execution with milestones/labels using this guide: [Roadmap tracking](./docs/roadmap-tracking.md).
+
+
 If your goal is to make this starter more production-realistic for learners, implement the following in phases.
 
 ### Phase 1 — Reliability and maintainability (short term)
@@ -153,6 +173,10 @@ If your goal is to make this starter more production-realistic for learners, imp
 
 - [Contributing guide](./CONTRIBUTING.md)
 - [Security policy](./SECURITY.md)
+- [Troubleshooting](./docs/troubleshooting.md)
+- [Generated output examples](./docs/generated-output-examples.md)
+- [Roadmap tracking guide](./docs/roadmap-tracking.md)
+- [Architecture Decision Records](./docs/adr)
 
 ## Inspiration
 

docs/adr/0001-generated-gulpfile-runtime.md

@@ -0,0 +1,22 @@
+# ADR 0001: Keep a single generated-gulpfile runtime
+
+- Status: Accepted
+- Date: 2026-03-17
+
+## Context
+The project previously had two competing runtime paths:
+1. A generated `gulpfile.js` flow.
+2. A dynamic TypeScript task runtime.
+
+This created maintenance drift, duplicated behavior, and made onboarding harder.
+
+## Decision
+Use a single runtime architecture: setup writes one generated `gulpfile.js` based on user choices.
+
+## Consequences
+- Pros: Lower complexity, easier debugging, fewer drift bugs.
+- Cons: Generator templates become the central maintenance surface.
+
+## Follow-up
+- Keep snapshot tests for generated outputs.
+- Keep path/option resolution centralized.

docs/adr/0002-template-composition.md

@@ -0,0 +1,17 @@
+# ADR 0002: Compose gulpfile from template sections
+
+- Status: Accepted
+- Date: 2026-03-17
+
+## Context
+A monolithic template string for `gulpfile.js` was hard to evolve and review.
+
+## Decision
+Split generation into composable template sections with a shared context object.
+
+## Consequences
+- Pros: Easier review, easier targeted testing, smaller future diffs.
+- Cons: More files to navigate for newcomers.
+
+## Follow-up
+- Keep section-level unit tests and matrix snapshots.

docs/generated-output-examples.md

@@ -0,0 +1,29 @@
+# Generated output examples
+
+## Example A: JavaScript + Sass + HTML
+
+```text
+src/
+  js/main.js
+  sass/main.sass
+  html/index.html
+  img/
+  favicon.ico
+```
+
+## Example B: TypeScript + SCSS + Pug
+
+```text
+src/
+  ts/main.ts
+  scss/main.scss
+  scss/base/_normalize.scss (optional)
+  scss/base/_reset.scss (optional)
+  pug/index.pug
+  img/
+  favicon.ico
+```
+
+## Generated build entrypoints
+- Dev/build pipeline in `gulpfile.js`
+- Distribution output under `dist/`

docs/roadmap-tracking.md

@@ -0,0 +1,25 @@
+# Roadmap tracking guide
+
+Convert roadmap items into trackable work with these conventions.
+
+## Labels
+- `phase:1` ... `phase:5`
+- `area:generator`
+- `area:docs`
+- `area:devops`
+- `area:security`
+- `type:refactor|feature|test|docs`
+
+## Milestones
+- `Phase 1 - Reliability`
+- `Phase 2 - Security`
+- `Phase 3 - Learning UX`
+- `Phase 4 - DevOps`
+- `Phase 5 - Ecosystem`
+
+## Issue template for roadmap items
+- Problem statement
+- Proposed approach
+- Acceptance criteria
+- Validation commands
+- Out-of-scope notes

docs/troubleshooting.md

@@ -0,0 +1,26 @@
+# Troubleshooting
+
+## `npm run init` fails with prompt/runtime errors
+- Run `npm run typecheck` and `npm test` first.
+- Remove generated folders and retry: `rm -rf src dist && npm run init`.
+- For automation, pass full flags: `npm run init -- --script ts --style scss --markup pug --yes`.
+
+## `npm run lint` fails in restricted environments
+If your environment blocks registry packages, lint dependencies may not install.
+Use `npm run typecheck` + `npm test` as a fallback until package access is available.
+
+## BrowserSync or gulp startup issues
+- Ensure Node 18+.
+- Ensure dependencies are installed with `npm install`.
+- Re-run init to regenerate `gulpfile.js` after changing options.
+
+## Invalid setup choices in automation mode
+Provide all required flags together:
+- `--script`
+- `--style`
+- `--markup`
+
+Optional flags:
+- `--normalize`
+- `--reset`
+- `--yes` / `-y`

package.json

@@ -1,7 +1,7 @@
 {
-  "name": "web-boilerplate-starter-kit",
+  "name": "web-learning-kit-generator",
   "version": "4.0.0",
-  "description": "A Front-end web kit and boilerplate for building web apps or small sites",
+  "description": "A learning-focused front-end project generator with a realistic Gulp workflow",
   "main": "gulpfile.js",
   "type": "commonjs",
   "scripts": {