Add streaming proxy addendum for OpenAI-compatible API router

.github/workflows/deploy.yaml

@@ -0,0 +1,76 @@
+name: Deploy Docs to Cloudflare Pages
+
+on:
+  push:
+    branches: [main]
+
+  # Allow manual dispatch from GitHub Actions UI
+  workflow_dispatch:
+
+# Only one deploy at a time per branch
+concurrency:
+  group: pages-deploy-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+
+    steps:
+      # ── Checkout ──────────────────────────────────────────────────────────
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          submodules: recursive
+          fetch-depth: 0
+
+      # ── Python ────────────────────────────────────────────────────────────
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.11'
+
+      - name: Install Python dependencies
+        run: pip install -r gendoc-template/requirements.txt
+
+      # ── System dependencies ───────────────────────────────────────────────
+      - name: Install system dependencies
+        run: |
+          sudo apt-get update -qq
+          sudo apt-get install -y -qq doxygen
+
+      # ── doxybook2 ─────────────────────────────────────────────────────────
+      - name: Install doxybook2
+        run: bash gendoc-template/scripts/install_deps.sh
+
+      # ── Generate wrangler.toml ────────────────────────────────────────────
+      - name: Generate wrangler.toml
+        run: |
+          python3 -c "
+          import yaml
+          with open('gendoc.yml', 'r') as f:
+              cfg = yaml.safe_load(f)
+          project  = cfg['deploy']['cloudflare']['pages_project_name']
+          date     = cfg['deploy']['cloudflare'].get('compatibility_date', '2024-01-01')
+          site_dir = cfg.get('mkdocs', {}).get('site_dir', 'site')
+          tpl = open('gendoc-template/wrangler.toml.template', 'r').read()
+          out = tpl.replace('{{PAGES_PROJECT_NAME}}', project)
+          out = out.replace('{{COMPATIBILITY_DATE}}', date)
+          out = out.replace('{{SITE_DIR}}', site_dir)
+          with open('gendoc-template/wrangler.toml', 'w') as f:
+              f.write(out)
+          print(f'wrangler.toml generated — project={project}  site_dir={site_dir}')
+          "
+
+      # ── Build ─────────────────────────────────────────────────────────────
+      - name: Build documentation site
+        run: bash gendoc-template/scripts/build.sh
+
+      # ── Deploy ────────────────────────────────────────────────────────────
+      - name: Deploy to Cloudflare Pages
+        run: |
+          cd gendoc-template
+          npx wrangler pages deploy
+        env:
+          CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

.gitignore

@@ -0,0 +1,6 @@
+site/
+doxygen-output/
+docs/architecture/python-reference/
+docs/architecture/source-reference/
+docs/architecture/SUMMARY_EXT.md
+docs/architecture/index.md

.gitmodules

@@ -1,3 +1,6 @@
 [submodule "GNUS-NEO-SWARM"]
 	path = GNUS-NEO-SWARM
-	url = ../
+	url = ../GNUS-NEO-SWARM
+[submodule "gendoc-template"]
+	path = gendoc-template
+	url = ../gendoc-template.git

.planning/workstreams/doc-template/MILESTONES.md

@@ -0,0 +1,18 @@
+# Milestones
+
+## v0.1 Initial Template (Shipped: 2026-07-04)
+
+**Phases completed:** 6 phases, 8 plans, 12 tasks
+
+**Key accomplishments:**
+
+- Submodule-ready gendoc-template directory with a 60-line gendoc.yml config file that parameterizes every path the reference implementation hardcoded
+- Material-themed mkdocs.yml with GNUS cyan-blue palette, mermaid/mathjax extensions, 5 JS integrations, and runtime config resolution from gendoc.yml via Python hook
+- Pinned requirements.txt plus a clean `mkdocs build --strict` run proving the template renders a complete Material-themed static site with gendoc.yml-driven site_name
+- Parameterized Doxyfile template ({{TOKEN}} placeholders) and doxybook2 pipeline converting C++ source to markdown API reference pages
+- Unified navigation merging hand-written SUMMARY.md with generated API reference (Classes, Files, Namespaces) into a single literate-nav structure
+- Single-command build pipeline (Doxygen → doxybook2 → navigation → MkDocs) plus Cloudflare Pages deployment via Wrangler
+- Complete README with step-by-step setup instructions and end-to-end workflow verified from `git submodule add` through to deployed site
+- Zero hardcoded project paths — everything config-driven from gendoc.yml
+
+---

.planning/workstreams/doc-template/PROJECT.md

@@ -0,0 +1,95 @@
+# gendoc-template
+
+## Core Value
+
+A reusable, config-driven MkDocs documentation template that any GNUS C++ project can add as a git submodule to produce a complete documentation site — combining hand-written markdown with Doxygen-generated API reference, deployable to Cloudflare Pages via Wrangler.
+
+## What This Is
+
+A parameterized generalization of the `../documentation` reference implementation. Instead of hardcoding SuperGenius paths, the template accepts a config file pointing to the host project's hand-written docs directory and C++ source directory. It provides:
+- MkDocs + Material theme configuration with GNUS brand styling
+- Doxygen config template for C++ API documentation
+- Navigation builder that merges hand-written and generated docs
+- Build scripts (local and Cloudflare Pages)
+- Wrangler deployment configuration
+
+**Shipped v0.1:** 8 plans across 6 phases. Zero hardcoded project paths — everything config-driven from a single `gendoc.yml`.
+
+## What This Is NOT
+
+- NOT a documentation hosting service
+- NOT specific to any one GNUS project
+- NOT a replacement for the existing `../documentation` setup — it's a template derived from it
+
+## Current State
+
+**Shipped v0.1 Initial Template** (2026-07-04).
+
+The template is complete and verified: `git submodule add` → fill out `gendoc.yml` → run `build.sh` → deployed to Cloudflare Pages. All 14 requirements satisfied. `mkdocs build --strict` produces a clean static site with zero warnings. The doxygen → doxybook2 → navigation → mkdocs pipeline works end-to-end.
+
+**Next milestone:** TBD — no active requirements.
+
+## Requirements
+
+### Validated
+
+- ✓ **CFG-01**: Template exposes a single config file (`gendoc.yml`) — v0.1
+- ✓ **CFG-02**: `git submodule add` into a host project, run one setup command, all paths resolve from config — v0.1
+- ✓ **CFG-03**: Config includes Wrangler deployment target — v0.1
+- ✓ **MKD-01**: Pre-configured Material theme matching GNUS visual style — v0.1
+- ✓ **MKD-02**: literate-nav plugin merges hand-written and generated API reference nav — v0.1
+- ✓ **MKD-03**: Site works locally (`mkdocs serve`) and built for deployment (`mkdocs build`) — v0.1
+- ✓ **API-01**: Generic Doxygen config template — project name, source dir, output dir from config — v0.1
+- ✓ **API-02**: doxybook2 converts Doxygen XML to markdown — v0.1
+- ✓ **API-03**: Navigation builder produces literate-nav entries for Classes, Files, Namespaces, Modules, Pages — v0.1
+- ✓ **BLD-01**: Single build script runs Doxygen → doxybook2 → navigation → MkDocs — v0.1
+- ✓ **BLD-02**: Cloudflare Pages deploy script using Wrangler — v0.1
+- ✓ **BLD-03**: Scripts work on macOS and Linux — v0.1
+- ✓ **TPL-01**: Clean submodule layout — no hardcoded project paths — v0.1
+- ✓ **TPL-02**: README with setup instructions for host projects — v0.1
+
+### Active
+
+_(none — all v0.1 requirements shipped and validated)_
+
+### Out of Scope
+
+- Hosting or serving the documentation (Cloudflare Pages handles this)
+- Custom MkDocs plugins beyond what Material theme + literate-nav provide
+- CI/CD integration (can be added by host projects)
+
+## Key Decisions
+
+- **Phase 01:** Template is its own standalone git repo outside GeniusCogntiveSystem to enable independent git-submodule workflows
+- **Phase 01:** Single 60-line `gendoc.yml` config file drives all paths — no scattered configuration
+- **Phase 02:** MkDocs Material theme with GNUS cyan-blue color ramp, Doxygen CSS integration ported from reference
+- **Phase 02:** 5 JS integrations for nav persistence, anchor handling, smooth scrolling, ToC highlighting, image lightbox
+- **Phase 02:** Config-driven via gendoc.yml → load_gendoc_config.py hook (no hardcoded site names or paths)
+- **Phase 02:** Python deps pinned: mkdocs==1.6.1, mkdocs-material==9.5.27, pymdown-extensions>=10.14, mkdocs-literate-nav==0.6.1, pyyaml>=6.0
+- **Phase 03:** Doxygen config uses `{{TOKEN}}` placeholders resolved at build time from gendoc.yml
+- **Phase 03:** doxybook2 converts Doxygen XML output to markdown for literate-nav consumption
+- **Phase 04:** Navigation builder merges hand-written SUMMARY.md with generated API reference into a single SUMMARY_EXT.md
+- **Phase 05:** Single `build.sh` orchestrates the full pipeline (Doxygen → doxybook2 → navigation → MkDocs)
+- **Phase 05:** `wrangler.toml.template` with `{{PLACEHOLDER}}` tokens for Cloudflare Pages deployment
+- **Phase 06:** README expanded from 65-line stub to 244-line guide covering full setup workflow
+
+## Evolution
+
+This document evolves at phase transitions and milestone boundaries.
+
+**After each phase transition:**
+1. Requirements invalidated? → Move to Out of Scope with reason
+2. Requirements validated? → Move to Validated with phase reference
+3. New requirements emerged? → Add to Active
+4. Decisions to log? → Add to Key Decisions
+5. "What This Is" still accurate? → Update if drifted
+
+**After each milestone:**
+1. Full review of all sections
+2. Core Value check — still the right priority?
+3. Audit Out of Scope — reasons still valid?
+4. Update Context with current state
+
+---
+
+_Last updated: 2026-07-04 after v0.1 milestone_

.planning/workstreams/doc-template/ROADMAP.md

@@ -0,0 +1,56 @@
+# Roadmap: gendoc-template
+
+## Milestones
+
+- ✅ **v0.1 Initial Template** — Phases 1-6 (shipped 2026-07-04)
+
+## Phases
+
+<details>
+<summary>✅ v0.1 Initial Template (Phases 1-6) — SHIPPED 2026-07-04</summary>
+
+- [x] Phase 1: Template Skeleton & Config (1/1 plan) — completed 2026-06-27
+- [x] Phase 2: MkDocs Site (2/2 plans) — completed 2026-07-03
+- [x] Phase 3: API Reference Pipeline (2/2 plans) — completed 2026-06-28
+- [x] Phase 4: Navigation Integration (1/1 plan) — completed 2026-06-28
+- [x] Phase 5: Build & Deploy (1/1 plan) — completed 2026-06-28
+- [ ] Phase 5.1: CI/CD Deployment (INSERTED) (0/2 plans)
+- [x] Phase 6: Documentation & Validation (1/1 plan) — completed 2026-06-28
+
+</details>
+
+Full milestone details: [milestones/v0.1-ROADMAP.md](milestones/v0.1-ROADMAP.md)
+
+### 🚧 Phase 5.1: CI/CD Deployment (In Progress)
+
+**Goal:** GitHub Actions CI/CD pipeline automatically builds and deploys the documentation site to Cloudflare Pages on push. Host projects get a deploy.yaml.template to drop into `.github/workflows/`.
+
+**Depends on:** Phase 5
+
+**Requirements:** CI-01, CI-02
+
+**Plans:** 2 plans
+
+Plans:
+- [ ] 05.1-01-PLAN.md — GitHub Actions deploy.yaml.template workflow (verbatim-copy contract, full pipeline + Wrangler deploy)
+- [ ] 05.1-02-PLAN.md — setup_ci.sh interactive onboarding script + README CI/CD Deployment section
+
+**Success Criteria:**
+1. `deploy.yaml.template` in gendoc-template can be copied VERBATIM to a host repo's `.github/workflows/deploy.yaml` (no token substitution needed)
+2. GitHub Actions workflow runs the full build pipeline (Doxygen → doxybook2 → navigation → MkDocs build) and deploys to Cloudflare Pages via Wrangler
+3. `scripts/setup_ci.sh` detects/verifies Cloudflare API tokens and stores them as GitHub secrets via `gh secret set`
+4. README includes a CI/CD Deployment section with prerequisites, setup flow, and required GitHub secrets table
+
+
+
+## Progress
+
+| Phase | Milestone | Plans Complete | Status | Completed |
+|-------|-----------|----------------|--------|-----------|
+| 1. Template Skeleton & Config | v0.1 | 1/1 | Complete | 2026-06-27 |
+| 2. MkDocs Site | v0.1 | 2/2 | Complete | 2026-07-03 |
+| 3. API Reference Pipeline | v0.1 | 2/2 | Complete | 2026-06-28 |
+| 4. Navigation Integration | v0.1 | 1/1 | Complete | 2026-06-28 |
+| 5. Build & Deploy | v0.1 | 1/1 | Complete | 2026-06-28 |
+| 5.1. CI/CD Deployment | v0.1 | 0/2 | Not started | — |
+| 6. Documentation & Validation | v0.1 | 1/1 | Complete | 2026-06-28 |

.planning/workstreams/doc-template/STATE.md

@@ -0,0 +1,121 @@
+---
+gsd_state_version: 1.0
+milestone: v0.1
+milestone_name: Initial Template
+status: Phase 5.1 inserted — needs planning
+stopped_at: Phase 5.1 — CI/CD Deployment inserted after Phase 5
+last_updated: "2026-07-04T18:20:01.309Z"
+last_activity: 2026-07-04 — Phase 5.1 (INSERTED) CI/CD GitHub Actions deployment workflow
+progress:
+  total_phases: 7
+  completed_phases: 6
+  total_plans: 8
+  completed_plans: 8
+  percent: 86
+---
+
+# Project State
+
+## Project Reference
+
+See: .planning/workstreams/doc-template/PROJECT.md (updated 2026-06-27)
+
+**Core value:** A reusable, config-driven MkDocs documentation template that any GNUS C++ project can add as a git submodule to produce a complete documentation site.
+**Current focus:** Phase 5.1 — CI/CD Deployment (INSERTED after Phase 5)
+
+## Current Position
+
+Phase: Milestone v0.1 complete
+Plan: —
+Status: Awaiting next milestone
+Last activity: 2026-07-04 — Milestone v0.1 completed and archived
+
+## Performance Metrics
+
+**Velocity:**
+
+- Total plans completed: 6
+- Average duration: 3 min
+- Total execution time: 0.2 hours
+
+**By Phase:**
+
+| Phase | Plans | Total | Avg/Plan |
+|-------|-------|-------|----------|
+| 1. Template Skeleton & Config | 1 | 2m | 2m |
+| 2. MkDocs Site | 1 | 10m | 10m |
+| 3. API Reference Pipeline | 2 | 7m | 3.5m |
+| 02 | 2 | - | - |
+
+**Recent Trend:**
+
+- Plan 01-01 completed in 2m — straightforward documentation-only phase with no blockers.
+- Plan 02-01 completed in 10m — mkdocs.yml, hook script, and 6 theme assets created. Docs-only, no compilation needed.
+- Plan 03-01 completed in 3m — Doxyfile.template (2478 lines, 12 tokens) and doxybook.json created.
+- Plan 03-02 completed in 4m — build_api_reference.sh (268 lines) and build_navigation.py (287 lines) created.
+
+*Updated after each plan completion*
+| Phase 01-template-skeleton-config P01 | 120 | 3 tasks | 7 files |
+| Phase 02-mkdocs-site P01 | 600 | 2 tasks | 8 files |
+| Phase 03-api-reference-pipeline P01 | 180 | 2 tasks | 2 files |
+| Phase 03-api-reference-pipeline P02 | 240 | 2 tasks | 2 files |
+| Phase 04-navigation-integration P04-01 | 300 | 2 tasks | 3 files |
+| Phase 05-build-deploy P01 | 2m | 3 tasks | 4 files |
+| Phase 06-documentation-validation P06-01 | 2m | 3 tasks | 3 files |
+| Phase 02 P02 | 1 | 2 tasks | 1 files |
+
+## Accumulated Context
+
+### Roadmap Evolution
+
+- Phase 5.1 inserted after Phase 5: CI/CD GitHub Actions deployment workflow (URGENT)
+
+### Decisions
+
+- Template is its own standalone git repo outside GeniusCogntiveSystem to enable independent git-submodule workflows
+- gendoc.yml paths are relative to the HOST PROJECT root (submodule parent), not the submodule itself
+- Six-section schema chosen to mirror the reference implementation's tool boundaries (MkDocs, Doxygen, doxybook2, Wrangler)
+- Python mkdocs hook (on_config) reads gendoc.yml at startup — site_name, docs_dir, site_dir are never hardcoded in mkdocs.yml
+- All theme assets are byte-for-byte identical to the reference implementation — proven working, fully project-agnostic
+- GitBook rewrite hook, redirects, and git-revision-date-localized excluded — SuperGenius-specific concerns not applicable to the template
+- EXCLUDE set to empty in Doxyfile template — exclusion handled by gendoc.yml paths.exclude_patterns via EXCLUDE_PATTERNS token
+- foldersToGenerate defaults to [classes, files, modules, namespaces, pages] — examples removed from standard template
+- Multi-line INPUT and FILE_PATTERNS collapsed to single-line tokens — build script expands them at substitution time
+- pyyaml via python3 -c in bash script — no jq dependency, works on both macOS and Linux
+- URL normalization strips computed api_dir basename instead of hardcoded project name
+- write_root_nav, write_readme, _write_root_summary removed from navigation builder — Phase 4 handles navigation integration
+- [Phase 04]: write_root_nav() produces SUMMARY_EXT.md via build_literate_nav()
+- [Phase 04]: HANDWRITTEN_DOCS_ABS already resolved by build_api_reference.sh (line 128) — no new variable needed
+- [Phase 04]: Missing SUMMARY.md is a soft warning, not a hard error — allows API-reference-only sites
+- [Phase 05]: build.sh reads gendoc.yml from HOST_ROOT (not TEMPLATE_ROOT) — matching load_gendoc_config.py pattern
+- [Phase 05]: wrangler.toml is generated at deploy time from .template via python3 — no sed -i, credentials stay in environment
+- [Phase 05]: CF_API_TOKEN and CF_ACCOUNT_ID passed via inline env assignment (not export) — limiting credential exposure
+- [Phase 05]: All three scripts use read_yaml() from build_api_reference.sh — single source of truth for YAML config parsing
+- [Phase ?]: README Configuration Reference documents all 6 gendoc.yml top-level keys and 20+ fields with required/optional status
+- [Phase ?]: Task 3 sweep found zero issues — all scripts use HOST_ROOT for gendoc.yml, no hardcoded project strings, README covers all config keys
+- [Phase ?]: Phase 02 requirements.txt pins mkdocs==1.6.1, mkdocs-material==9.5.27, pymdown-extensions>=10.14, mkdocs-literate-nav==0.6.1, pyyaml>=6.0 — matches reference; SuperGenius-specific deps dropped
+- [Phase ?]: Phase 02 build verification uses synthetic host project with gendoc.yml at host root — matches load_gendoc_config.py host-root resolution contract
+
+### Pending Todos
+
+None yet.
+
+### Blockers/Concerns
+
+None yet.
+
+## Deferred Items
+
+| Category | Item | Status | Deferred At |
+|----------|------|--------|-------------|
+| *(none)* | | | |
+
+## Session Continuity
+
+Last session: 2026-07-03T18:05:28.711Z
+Stopped at: Completed 06-01-PLAN.md — Final Verification & Self-Documentation
+Resume file: None
+
+## Operator Next Steps
+
+- Start the next milestone with /gsd-new-milestone