jsgui3-server 0.0.150 → 0.0.152

package/docs/books/website-design/15-multi-repo-plan.md

@@ -0,0 +1,275 @@
+# Chapter 15: Multi-Repo Implementation Plan
+
+This chapter coordinates the implementation across three repositories. The `jsgui3-webpage` and `jsgui3-website` packages are separate npm modules; `jsgui3-server` consumes them.
+
+---
+
+## 15.1 Dependency Graph
+
+```
+jsgui3-html (Evented_Class)
+    ↑
+jsgui3-webpage  (Webpage class)
+    ↑
+jsgui3-website  (Website class, depends on Webpage for page creation)
+    ↑
+jsgui3-server   (consumes Website/Webpage, normalization layer, publisher)
+```
+
+Each arrow means "depends on". Implementation order follows this graph **bottom-up**.
+
+---
+
+## 15.2 Current State
+
+| Package | Version | Lines | What Exists |
+|---------|---------|-------|-------------|
+| `jsgui3-html` | (stable) | large | `Evented_Class`, `Control`, `Page_Context` — all stable, no changes needed |
+| `jsgui3-webpage` | 0.0.8 (npm) | 14 → ~200 | Skeleton on npm; full implementation in repo (see Ch.17) |
+| `jsgui3-website` | 0.0.8 (npm) | 14 → ~200 | Skeleton on npm; full implementation in repo (see Ch.17) |
+| `jsgui3-server` | (active) | large | Server integration complete: `normalize_serve_input`, `website_manifest`, `publication_summary` added to `serve-factory.js` |
+
+---
+
+## 15.3 Implementation Phases
+
+This plan uses two aligned tracks:
+
+1. **Minimal-first track** (v0.1.x) from Chapter 16
+2. **Full-spec track** (v0.3.x) from Chapters 13 and 14
+
+### Phase 1: jsgui3-webpage → v0.1.0 (minimal-first) ✅ COMPLETE
+
+**Repo**: `jsgui3-webpage`
+
+**Deliverables**:
+1. Implement minimal `Webpage.js` per Chapter 16 (`path`, `name`, `title`, `ctrl`, `content`, `meta`, assets)
+2. Include migration bridge: accept legacy `content: Function` as renderer alias when `ctrl` is missing
+3. Write focused unit tests for constructor behavior + alias normalization
+4. Update `README.md` with minimal-first examples
+5. Update `package.json`: version 0.1.0, add `main: "index.js"`
+6. Publish to npm
+
+**Acceptance criteria**:
+1. Minimal constructor behaviors pass
+2. Legacy renderer alias (`content: Function`) works for compatibility
+3. `require('jsgui3-webpage')` returns the new Webpage class
+
+**No other repo needs to change for this phase to succeed.**
+
+---
+
+### Phase 2: jsgui3-website → v0.1.0 (minimal-first) ✅ COMPLETE
+
+**Repo**: `jsgui3-website`
+
+**Prerequisites**: jsgui3-webpage v0.1.0 published
+
+**Deliverables**:
+1. Implement minimal `Website.js` per Chapter 16 (Map-backed pages + core methods)
+2. Add `jsgui3-webpage` as dependency
+3. Write focused unit tests for page registry and duplicate detection
+4. Update `README.md` with minimal-first examples
+5. Update `package.json`: version 0.1.0, dependencies, main field
+6. Publish to npm
+
+**Acceptance criteria**:
+1. Page registry methods (`add_page`, `get_page`, `has_page`) pass
+2. Duplicate path detection passes
+3. `require('jsgui3-website')` returns the new Website class
+4. Lab 002 (pages storage) assumptions hold against real module usage
+
+---
+
+### Phase 3: jsgui3-server integration against v0.1.x primitives ✅ COMPLETE
+
+**Repo**: `jsgui3-server`
+
+**Prerequisites**: jsgui3-webpage v0.1.0 and jsgui3-website v0.1.0 published
+
+**Deliverables**:
+1. Update `package.json` to depend on `jsgui3-webpage@^0.1.0` and `jsgui3-website@^0.1.0`
+2. Add `normalize_serve_input()` function (per Lab 005 design)
+3. Integrate into `serve-factory.js` publisher pipeline
+4. Add compatibility bridge for renderer field (`page.ctrl` canonical, legacy `page.content` function still accepted)
+5. Add integration tests
+6. Ensure all existing server tests still pass (backward compatibility)
+
+**Acceptance criteria**:
+- Lab 005 (input normalization) passes against the real modules
+- Lab 006 (server integration spike) passes against the real modules
+- Legacy `Server.serve(MyCtrl)` and `Server.serve({pages, api})` still work
+- A real Website with pages serves correctly on localhost
+
+---
+
+### Phase 4: primitives upgrade to full-spec track (v0.3.0) ⏳ NOT STARTED
+
+**Repos**: `jsgui3-webpage`, `jsgui3-website`
+
+**Prerequisites**: Phase 3 complete and stable in integration
+
+**Deliverables**:
+1. Implement full `Webpage` contract from Chapter 13 (Evented_Class, finalize, i18n helpers, type marker, toJSON)
+2. Implement full `Website` contract from Chapter 14 (API registry, finalize cascade, richer serialization)
+3. Keep migration bridge for legacy renderer shape during upgrade window
+4. Publish `jsgui3-webpage@0.3.0` and `jsgui3-website@0.3.0`
+
+**Acceptance criteria**:
+1. Chapter 13 and Chapter 14 unit test plans pass
+2. Lab 001, 003, and 004 assumptions pass against real modules
+3. No regressions in Phase 3 server integration tests
+
+---
+
+### Phase 5: Content integration (stretch) ⏳ NOT STARTED
+
+**All repos**
+
+**Deliverables**:
+1. Add content-aware rendering to the server (resolve locale, pass content to Controls)
+2. Create an example multi-language Webpage with real i18n content
+3. Demonstrate content loading from JSON files
+4. Update lab experiments to test content flow end-to-end
+
+**Acceptance criteria**:
+- A page with translated content renders correctly in multiple locales
+- `get_string()` and `resolve_content()` are exercised in integration tests
+
+---
+
+## 15.4 Version Pinning Strategy
+
+| Consumer | Dependency | Version Constraint |
+|----------|-----------|-------------------|
+| `jsgui3-website` | `jsgui3-webpage` | `^0.1.0` during minimal-first track |
+| `jsgui3-server` | `jsgui3-webpage` | `^0.1.0` initially, move to `^0.3.0` after Phase 4 |
+| `jsgui3-server` | `jsgui3-website` | `^0.1.0` initially, move to `^0.3.0` after Phase 4 |
+
+### Semver policy
+
+- **0.x.y**: pre-stable; minor bumps may include breaking changes
+- **1.0.0**: stable contract; breaking changes require major bump
+- Target stable at 1.0.0 after Phase 4+5 contracts are validated in production
+
+### npm link during development
+
+During development, use `npm link` for cross-repo testing:
+
+```bash
+# In jsgui3-webpage directory
+npm link
+
+# In jsgui3-website directory
+npm link jsgui3-webpage
+npm link
+
+# In jsgui3-server directory
+npm link jsgui3-webpage
+npm link jsgui3-website
+```
+
+Lab 003 confirmed that the `Symbol.for()` detection strategy works across linked packages (unlike `instanceof`).
+
+---
+
+## 15.5 Testing Strategy
+
+### Per-repo unit tests
+
+Each repo has its own test suite that runs independently:
+
+| Repo | Test Path | What It Tests |
+|------|-----------|---------------|
+| `jsgui3-webpage` | `test/webpage.test.js` | Webpage class in isolation |
+| `jsgui3-website` | `test/website.test.js` | Website class with Webpage dependency |
+| `jsgui3-server` | Existing test suite + new | Server integration with Website/Webpage |
+
+### Cross-repo integration (in jsgui3-server)
+
+The lab experiments in `labs/website-design/` serve as cross-repo integration tests:
+
+```bash
+# From jsgui3-server, after npm linking or installing new versions
+node labs/website-design/run-all.js
+```
+
+All 6 experiments should pass against the real modules — currently they use prototype classes that mirror the spec.
+
+### When to run what
+
+| When | Run |
+|------|-----|
+| Editing Webpage class | `cd jsgui3-webpage && npm test` |
+| Editing Website class | `cd jsgui3-website && npm test` |
+| Editing server integration | `cd jsgui3-server && npm test && node labs/website-design/run-all.js` |
+| Before publishing any package | All of the above |
+
+---
+
+## 15.6 npm Publish Workflow
+
+### Pre-publish checklist
+
+1. All per-repo tests pass
+2. Version in `package.json` updated
+3. README reflects current API
+4. Cross-repo lab experiments pass in jsgui3-server
+5. Git tag created for current phase (`v0.1.0` minimal-first, `v0.3.0` full-spec)
+
+### Publish order
+
+1. `jsgui3-webpage` first (no upstream dependency)
+2. `jsgui3-website` second (depends on webpage)
+3. `jsgui3-server` — update `package.json` dependencies, commit, no separate publish needed
+
+### Rollback
+
+If a publish reveals issues:
+1. `npm unpublish jsgui3-XXX@<version>` (within 72 hours)
+2. Or publish a patch release with the fix (`0.1.1`, `0.3.1`, etc.)
+
+---
+
+## 15.7 Agent Assignment Considerations
+
+| Phase | Repos Touched | Best Agent |
+|-------|--------------|------------|
+| Phase 1: Webpage | `jsgui3-webpage` only | Codex (single repo) or Antigravity |
+| Phase 2: Website | `jsgui3-website` (+ webpage as dependency) | Codex or Antigravity |
+| Phase 3: Server | `jsgui3-server` (+ webpage/website) | Antigravity (multi-repo context) |
+| Phase 4: Full-spec primitives | `jsgui3-webpage`, `jsgui3-website` | Codex or Antigravity |
+| Phase 5: Content | All three repos | Antigravity (cross-repo coordination) |
+
+Phases 1 and 2 are independent single-repo tasks. Phase 3 requires multi-repo awareness. Phase 4 should start only after Phase 3 stability is confirmed.
+
+---
+
+## 15.8 Risk Register
+
+| Risk | Likelihood | Impact | Mitigation |
+|------|-----------|--------|------------|
+| Evented_Class API changes in jsgui3-html | Low | High | Pin jsgui3-html version; test on update |
+| Circular dependency between webpage ↔ website | Medium | Medium | Website depends on Webpage, never the reverse |
+| Breaking change in Webpage API affects Website | Medium | Medium | Freeze shared contract at each phase boundary (`v0.1.x` then `v0.3.x`) |
+| Lab experiments diverge from real implementation | Medium | Low | Re-run labs against real modules in Phase 3 |
+| npm link issues during development | Low | Low | Symbol.for() detection handles cross-install (Lab 003) |
+
+---
+
+## 15.9 Timeline Estimate
+
+| Phase | Effort | Dependencies |
+|-------|--------|-------------|
+| Phase 1: Webpage minimal | 1–2 hours | None | ✅ Complete |
+| Phase 2: Website minimal | 1–2 hours | Phase 1 published | ✅ Complete |
+| Phase 3: Server integration | 4–6 hours | Phase 2 published | ✅ Complete |
+| Phase 4: Full-spec primitives | 4–6 hours | Phase 3 stable | ⏳ Not started |
+| Phase 5: Content integration | 2–4 hours | Phase 4 complete | ⏳ Not started |
+| **Total** | **12–20 hours** | | **~50% complete** |
+
+Phases 1 and 2 can be parallelized only if the minimal Webpage constructor contract is frozen first.
+
+---
+
+*See [Chapter 17](17-implementation-report-codex.md) for the implementation report. See the [README](README.md) for the full chapter index.*

package/docs/books/website-design/16-minimal-first.md

@@ -0,0 +1,203 @@
+# Chapter 16: Minimal First Implementation
+
+Chapters 12–14 describe the full vision. This chapter defines the **smallest useful version** — what to build first, what to defer, and when to promote deferred features.
+
+---
+
+## 16.1 The Problem with the Full Spec
+
+The full spec across Chapters 12–14 includes ~30 features. Both packages are currently 14 lines each. Jumping from 14 lines to a full Evented_Class-based, i18n-aware, finalize-cascading, event-emitting, Symbol-marked module is a big leap that introduces risk:
+
+- Features built before they have consumers
+- Dependencies added before they're justified
+- Complexity that makes the first real usage harder to debug
+
+**Principle**: ship the thinnest version that supports real usage, then grow it.
+
+---
+
+## 16.2 v0.1 — Store Data, Nothing More
+
+### Webpage (~15 lines)
+
+```js
+class Webpage {
+    constructor(spec = {}) {
+        const has_legacy_ctrl = typeof spec.content === 'function' && spec.ctrl === undefined;
+
+        this.path = spec.path;
+        this.name = spec.name;
+        this.title = spec.title;
+        this.ctrl = spec.ctrl || (has_legacy_ctrl ? spec.content : undefined);
+        this.content = has_legacy_ctrl ? undefined : spec.content;
+        this.render_mode = spec.render_mode;
+        this.scripts = spec.scripts || [];
+        this.stylesheets = spec.stylesheets || [];
+        this.meta = spec.meta || {};
+    }
+}
+
+module.exports = Webpage;
+```
+
+### Website (~30 lines)
+
+```js
+const Webpage = require('jsgui3-webpage');
+
+class Website {
+    constructor(spec = {}) {
+        this.name = spec.name;
+        this.meta = spec.meta || {};
+        this._pages = new Map();
+
+        if (Array.isArray(spec.pages)) {
+            for (const p of spec.pages) this.add_page(p);
+        }
+    }
+
+    add_page(page_or_spec) {
+        const page = page_or_spec instanceof Webpage
+            ? page_or_spec
+            : new Webpage(page_or_spec);
+        if (page.path && this._pages.has(page.path)) {
+            throw new Error(`Duplicate page path: "${page.path}"`);
+        }
+        this._pages.set(page.path, page);
+        return page;
+    }
+
+    get_page(path) { return this._pages.get(path); }
+    has_page(path) { return this._pages.has(path); }
+    get pages() { return [...this._pages.values()]; }
+    get page_count() { return this._pages.size; }
+}
+
+module.exports = Website;
+```
+
+### What this gets you
+
+- ✅ Webpage holds path, title, content, ctrl, meta, scripts, stylesheets
+- ✅ Website stores pages in a Map (O(1) lookup, duplicate detection — Lab 002)
+- ✅ `add_page()` / `get_page()` / `has_page()` API
+- ✅ Structured content objects are supported
+- ✅ Legacy renderer input (`content: Function`) remains accepted as an alias for `ctrl`
+- ✅ Zero dependencies (no jsgui3-html needed)
+- ✅ ~45 lines total across both packages
+
+### What this doesn't have
+
+- ❌ No `Evented_Class` base (no events)
+- ❌ No `finalize()` validation
+- ❌ No `toJSON()` serialization
+- ❌ No `Symbol.for()` type markers
+- ❌ No i18n resolution (`get_string`, `resolve_content`)
+- ❌ No API endpoint registry
+- ❌ No path normalization
+
+---
+
+## 16.3 Layered Growth Plan
+
+Each layer adds one area of functionality. Only add a layer when there's a real consumer.
+
+### v0.2 — When you need server integration
+
+**Trigger**: `jsgui3-server` needs to detect and route Website/Webpage inputs.
+
+**Add**:
+- Path normalization (leading slash)
+- `toJSON()` for admin/debug
+- API endpoint registry on Website (`add_endpoint`, `get_endpoint`)
+- Normalize renderer field (`ctrl` canonical, legacy `content: Function` normalized)
+- Duck-typing detection (check for `add_page` / `get_page`)
+
+**Dependencies**: still none. Duck typing doesn't need `Symbol.for()`.
+
+### v0.3 — When you need lifecycle safety
+
+**Trigger**: bugs from serving incomplete pages, or need to gate publication.
+
+**Add**:
+- `finalize()` on Webpage (require path + ctrl)
+- `finalize()` cascade on Website
+- `Evented_Class` base (enables `'finalized'` event)
+
+**Dependencies**: adds `jsgui3-html` (for `Evented_Class`).
+
+### v0.4 — When you need cross-install safety
+
+**Trigger**: npm link / monorepo setups where `instanceof` breaks.
+
+**Add**:
+- `Symbol.for('jsgui3.webpage')` / `Symbol.for('jsgui3.website')` markers
+- `isWebpage()` / `isWebsite()` utility functions
+
+### v0.5 — When you need i18n
+
+**Trigger**: a real site with multi-language content.
+
+**Add**:
+- `get_string(key, locale)` with dotted path resolution
+- `get_title(locale)` 
+- `resolve_content(locale)` for Controls
+- Locale fallback chains
+- `locales` computed property
+
+**Dependencies**: no new deps — just methods on Webpage.
+
+---
+
+## 16.4 Decision Matrix
+
+Use this table to decide which version you need:
+
+| You want to... | Minimum version |
+|----------------|-----------------|
+| Create a Website with pages and serve it | v0.1 |
+| Have the server detect Website vs legacy input | v0.2 |
+| Define API endpoints on a Website | v0.2 |
+| Validate pages before publishing | v0.3 |
+| Subscribe to page-added / finalized events | v0.3 |
+| Use npm link across packages safely | v0.4 |
+| Serve pages in multiple languages | v0.5 |
+
+---
+
+## 16.5 What the Labs Tell Us
+
+The lab experiments tested the full-featured design. They remain valid as specs for future versions:
+
+| Lab | Tests | Relevant from |
+|-----|-------|---------------|
+| 001 (Base class overhead) | Evented_Class perf | v0.3 onward |
+| 002 (Pages storage) | Map vs Array | **v0.1** (already using Map) |
+| 003 (Type detection) | Symbol + duck typing | v0.4 |
+| 004 (Two-stage validation) | finalize() | v0.3 |
+| 005 (Input normalization) | Manifest shape | v0.2 |
+| 006 (Server integration) | End-to-end | v0.2 |
+
+---
+
+## 16.6 Recommendation
+
+Start with **v0.1**. Build a real site with it. Discover what's missing through usage, not speculation. The full spec (Ch.12–14) is the *roadmap*, not the *first commit*.
+
+The implementation effort for v0.1 is under an hour. Each subsequent layer is 1–2 hours. The total work is the same as implementing the full spec upfront — but each step is validated by a real need.
+
+---
+
+## 16.7 Version Track Alignment
+
+To keep this chapter consistent with Chapters 13–15:
+
+1. **v0.1.x** is the minimal-first release line described here.
+2. **v0.3.x** is the full-spec line from Chapters 13 and 14.
+3. Migration between lines keeps compatibility for legacy `content: Function` renderer inputs until server normalization is fully in place.
+
+**Implementation note (Feb 2026)**: Codex implemented the full v0.3 spec directly (see [Ch.17](17-implementation-report-codex.md)), bypassing the minimal-first track. This chapter remains useful as a reference for understanding which features are foundational vs. which are convenience layers — and as a fallback plan if a simpler restart is ever needed.
+
+---
+
+*This chapter complements [Chapter 13](13-webpage-module-spec.md), [Chapter 14](14-website-module-spec.md), and [Chapter 15](15-multi-repo-plan.md), which describe the full target.*

package/docs/books/website-design/17-implementation-report-codex.md

@@ -0,0 +1,81 @@
+# Chapter 17: Implementation Report (Codex)
+
+Date: 2026-02-16
+
+## Summary
+
+This implementation cycle completed the core multi-repo work proposed in the book:
+
+1. Implemented full `Webpage` primitives in `jsgui3-webpage`.
+2. Implemented full `Website` and `Website_Api` primitives in `jsgui3-website`.
+3. Integrated Website/Webpage normalization and serving support into `jsgui3-server`.
+4. Added and ran focused tests for the new input shapes and behavior.
+
+## What Was Implemented
+
+### 1. `jsgui3-webpage`
+
+Main outcomes:
+
+1. Replaced skeleton `Webpage` with a full class based on `Evented_Class`.
+2. Added canonical renderer handling (`ctrl`) with legacy compatibility (`content: Function`).
+3. Added path normalization, i18n/content helpers, locale collection, `finalize()`, and `toJSON()`.
+4. Added marker-based type detection support (`Symbol.for('jsgui3.webpage')`).
+5. Added module exports and helper:
+   - `index.js`
+   - `is_webpage.js`
+6. Added test suite: `test/webpage.test.js`.
+
+### 2. `jsgui3-website`
+
+Main outcomes:
+
+1. Implemented `Website_Api` endpoint registry in `API.js` (fixing previous export bug and missing behavior).
+2. Replaced skeleton `Website` with Map-backed page registry and API integration.
+3. Added page and endpoint lifecycle methods (`add_page`, `remove_page`, `replace_page`, `add_endpoint`, etc.).
+4. Added `finalize()` cascade and `toJSON()` serialization.
+5. Added marker-based type detection support (`Symbol.for('jsgui3.website')`).
+6. Added module exports and helper:
+   - `index.js`
+   - `is_website.js`
+7. Added test suite: `test/website.test.js`.
+
+### 3. `jsgui3-server`
+
+Main outcomes in `serve-factory.js`:
+
+1. Added Website/Webpage-like input detection and normalization.
+2. Added route/base-path normalization with duplicate-route protection.
+3. Added endpoint normalization supporting metadata (`name`, `path`, `method`, `description`, handler).
+4. Supported direct webpage-like and website-like inputs in `Server.serve(...)`.
+5. Supported non-root page sets through manual page publication path.
+6. Added server-side manifest visibility:
+   - `server_instance.website_manifest`
+   - `server_instance.publication_summary`
+7. Improved route preparation robustness for API/manual-page servers by resolving router from either `server.router` or `server.server_router`.
+
+Main outcomes in tests:
+
+1. Added integration coverage in `tests/serve.test.js` for:
+   - webpage-like input serving on declared path
+   - website-like input with `base_path` and endpoint metadata
+   - duplicate normalized route rejection
+
+## Validation Results
+
+Executed successfully:
+
+1. `jsgui3-server`: `npm run test:serve`
+2. `jsgui3-server`: `npm run test:serve:resources`
+3. `jsgui3-webpage`: `npm test`
+4. `jsgui3-website`: `npm test`
+
+Note: `jsgui3-website` tests were run in this workspace using local sibling dependency installation for `jsgui3-webpage`, because `jsgui3-webpage@^0.3.0` is not yet published to npm.
+
+## Current Limitation
+
+Endpoint `method` metadata is preserved in normalization/manifests, but runtime request handling is still method-agnostic because endpoint publishing currently routes through `server.publish(...)`.
+
+## Practical Next Step
+
+Introduce method-aware API publishing in server/router integration so `GET/POST/...` metadata is enforced, not only stored.

package/docs/books/website-design/README.md

@@ -0,0 +1,43 @@
+# Designing jsgui3-website & jsgui3-webpage
+
+A design book covering the full lifecycle from design exploration through implementation of abstract website and webpage representations for the jsgui3 ecosystem.
+
+> **Status**: Core implementation complete (see Ch.17) — packages not yet published to npm  
+> **Date**: February 2026
+
+## Chapters
+
+| # | Chapter | Focus |
+|---|---------|-------|
+| 01 | [Introduction & Vision](01-introduction.md) | What we're building, why, and the core design tension |
+| 02 | [Current State](02-current-state.md) | Exact code in both repos today, and how jsgui3-server uses them |
+| 03 | [The Base Class Question](03-base-class.md) | Plain class vs obext vs Evented_Class — the foundational choice |
+| 04 | [Designing the Webpage](04-webpage.md) | Three proposals for jsgui3-webpage, with tradeoffs |
+| 05 | [Designing the Website](05-website.md) | Three proposals for jsgui3-website, with tradeoffs |
+| 06 | [Pages Storage](06-pages-storage.md) | Array vs Collection vs Map — how a website holds its pages |
+| 07 | [The API Layer](07-api-layer.md) | How websites describe their API endpoints |
+| 08 | [Server Integration](08-server-integration.md) | How jsgui3-server would consume these abstractions |
+| 09 | [Cross-Agent Review](09-cross-agent-review.md) | An OpenAI agent's review, and responses to it |
+| 10 | [Open Questions](10-open-questions.md) | Unresolved design decisions for future discussion |
+| 11 | [Converged Recommendation](11-converged-recommendation.md) | A concrete baseline proposal and phased delivery plan |
+| 12 | [The Content Model](12-content-model.md) | Webpage as content container — strings, i18n, locale fallback |
+| 13 | [jsgui3-webpage Module Spec](13-webpage-module-spec.md) | Complete implementation blueprint for the Webpage package |
+| 14 | [jsgui3-website Module Spec](14-website-module-spec.md) | Complete implementation blueprint for the Website package |
+| 15 | [Multi-Repo Plan](15-multi-repo-plan.md) | Cross-repo coordination, versioning, testing, publish workflow |
+| 16 | [Minimal First Implementation](16-minimal-first.md) | Pragmatic v0.1 (~45 lines) + layered growth plan |
+| 17 | [Implementation Report](17-implementation-report-codex.md) | What Codex built, validation results, known gaps |
+
+## Suggested Reading Paths
+
+- **Quick strategic summary**: 01 → 09 → 11
+- **Implementation-oriented**: 02 → 04 → 05 → 08 → 11
+- **Deep design debate**: 03 → 06 → 07 → 09 → 10
+- **Module specs (full design)**: 12 → 13 → 14 → 15
+- **What was built**: 16 → 17 (minimal-first rationale, then implementation report)
+
+## Related Documents
+
+- [Original proposals](../../proposals/jsgui3-website-and-webpage-design.md)
+- [OpenAI review](../../proposals/jsgui3-website-and-webpage-design-review.md)
+- [Server support proposal](../../proposals/jsgui3-website-and-webpage-design-jsgui3-server-support.md)
+- [Lab experiments](../../labs/website-design/README.md) — empirical validation of design decisions (179 checks passing)