SolverForge · blackopsrepl · Apr 20, 2026
diff --git a/README.md b/README.md
@@ -37,15 +37,17 @@ The current templates cover standard-variable and list-heavy planning models, an
 
 ## Extend the Scaffold
 
-- [Extend the solver](docs/extend-solver.md) when you need custom constraints, phases, selectors, termination, or solver configuration beyond the default scaffold.
-- [Extend the domain](docs/extend-domain.md) when you need more entities, facts, variables, scoring, or mixed standard/list modeling inside the generated app.
+- [Extend the solver](docs/reference/extend-solver.md) when you need custom constraints, phases, selectors, termination, or solver configuration beyond the default scaffold.
+- [Extend the domain](docs/reference/extend-domain.md) when you need more entities, facts, variables, scoring, or mixed standard/list modeling inside the generated app.
 
 ## Documentation Map
 
 - `README.md` is the user-facing entry point for the workspace and generated-project integration model.
-- `docs/extend-solver.md` and `docs/extend-domain.md` cover scaffold extension workflows.
-- `docs/lifecycle-pause-resume-contract.md` defines the retained lifecycle contract, including exact pause/resume semantics, snapshot identity, and terminal-state cleanup rules.
-- `docs/typed-contract-audit.md` records the current neutral selector and extractor naming model, including the `EntityCollectionExtractor`, `ValueSelector`, and `MoveSelector` surface adopted in `0.7.0`.
+- `docs/README.md` is the docs entrypoint and points to the Bridgetown migration runbooks and reference content layout.
+- `docs/reference/extend-solver.md` and `docs/reference/extend-domain.md` cover scaffold extension workflows.
+- `docs/reference/lifecycle-pause-resume-contract.md` defines the retained lifecycle contract, including exact pause/resume semantics, snapshot identity, and terminal-state cleanup rules.
+- `docs/reference/typed-contract-audit.md` records the current neutral selector and extractor naming model, including the `EntityCollectionExtractor`, `ValueSelector`, and `MoveSelector` surface adopted in `0.7.0`.
+- `docs/reference/github-pages-migration.md` documents the GitHub Pages migration options for making `docs/` the source of truth while preserving the canonical docs URL strategy.
 - `crates/*/WIREFRAME.md` files are the canonical public API maps for each crate.
 - `AGENTS.md` defines repository-level engineering and documentation expectations for coding agents.
 
@@ -60,7 +62,7 @@ SolverForge preserves concrete types through the entire solver pipeline:
 
 This enables aggressive compiler optimizations and cache-friendly data layouts.
 
-Current public naming follows neutral Rust contracts rather than `Typed*` prefixes. The object-safe descriptor boundary is still intentional, but the concrete adapter and selector surface are now documented as `EntityCollectionExtractor`, `ValueSelector`, and `MoveSelector`. The historical rename and rationale are captured in [docs/typed-contract-audit.md](docs/typed-contract-audit.md).
+Current public naming follows neutral Rust contracts rather than `Typed*` prefixes. The object-safe descriptor boundary is still intentional, but the concrete adapter and selector surface are now documented as `EntityCollectionExtractor`, `ValueSelector`, and `MoveSelector`. The historical rename and rationale are captured in [docs/reference/typed-contract-audit.md](docs/reference/typed-contract-audit.md).
 
 ## Features
 

diff --git a/docs/AGENTS.md b/docs/AGENTS.md
@@ -0,0 +1,34 @@
+# AGENTS.md (docs scope)
+
+This file applies to everything under `docs/`.
+
+## Purpose
+
+`docs/` now serves two roles:
+
+1. **Website source-of-truth** for the upcoming Bridgetown site migration.
+2. **Reference documentation** for architecture and extension topics.
+
+## Required structure
+
+- Keep planning and migration docs in `docs/bridgetown/`.
+- Keep durable product/reference docs in `docs/reference/`.
+- Keep a short entrypoint in `docs/README.md` so humans and agents can find the right document quickly.
+
+## Bridgetown migration guardrails
+
+- Prefer small, reviewable commits (setup, content migration, CI integration).
+- Do not handwave commands; provide exact local commands and expected artifacts.
+- Keep migration docs implementation-oriented (what to run, where files go, how to verify).
+- If introducing generated Bridgetown files, keep custom logic minimal and documented.
+
+## Validation expectations
+
+When editing docs for the Bridgetown migration, run at least one relevant local check and record it in your final report. Prefer:
+
+- `cargo fmt --all -- --check` (workspace baseline)
+- Bridgetown checks (when Ruby/Bundler is available locally):
+  - `bundle exec bridgetown doctor`
+  - `bundle exec bridgetown build`
+
+If Bridgetown tooling is unavailable in this environment, document that clearly and keep instructions reproducible.
diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,23 @@
+# SolverForge Documentation
+
+This directory is now organized for the Bridgetown migration and long-term maintainability.
+
+## Directory map
+
+- `bridgetown/` — implementation docs for creating and operating the Bridgetown-based docs site.
+- `reference/` — product/reference guides that should be migrated into Bridgetown pages as content.
+- `AGENTS.md` — scoped instructions for coding agents working under `docs/`.
+
+## Start here
+
+1. Read `bridgetown/execution-plan.md`.
+2. Follow `bridgetown/agent-runbook.md` for exact local commands.
+3. Migrate and validate content from `reference/` into the Bridgetown site.
+
+## Current reference docs
+
+- `reference/extend-solver.md`
+- `reference/extend-domain.md`
+- `reference/lifecycle-pause-resume-contract.md`
+- `reference/typed-contract-audit.md`
+- `reference/github-pages-migration.md`
diff --git a/docs/bridgetown/agent-runbook.md b/docs/bridgetown/agent-runbook.md
@@ -0,0 +1,71 @@
+# Bridgetown Agent Runbook (Local-First)
+
+Use this runbook when executing the migration in a local/dev environment.
+
+## 1) Preconditions
+
+- Ruby installed (recommended via `rbenv` or `asdf`).
+- Bundler installed.
+- Node.js installed (if selected Bridgetown plugins require JS build steps).
+
+## 2) Bootstrap Bridgetown in `docs/site`
+
+From repository root:
+
+```bash
+mkdir -p docs/site
+cd docs/site
+bundle init
+bundle add bridgetown
+bundle exec bridgetown new . --force
+```
+
+Expected artifacts include:
+
+- `docs/site/bridgetown.config.yml`
+- `docs/site/src/index.md`
+- `docs/site/config/initializers.rb`
+
+## 3) Add baseline content structure
+
+Inside `docs/site/src/`, create sections:
+
+```text
+src/
+  guides/
+  architecture/
+  api/
+```
+
+Recommended mapping:
+
+- `docs/reference/extend-solver.md` -> `src/guides/extend-solver.md`
+- `docs/reference/extend-domain.md` -> `src/guides/extend-domain.md`
+- `docs/reference/lifecycle-pause-resume-contract.md` -> `src/architecture/lifecycle-pause-resume-contract.md`
+- `docs/reference/typed-contract-audit.md` -> `src/architecture/typed-contract-audit.md`
+
+## 4) Local verification
+
+From `docs/site`:
+
+```bash
+bundle exec bridgetown doctor
+bundle exec bridgetown build
+bundle exec bridgetown serve
+```
+
+Then open the local Bridgetown URL and verify migrated pages are linked from homepage/navigation.
+
+## 5) Deployment handoff
+
+Once local build is stable, implement CI deployment strategy from this repository:
+
+- Build site from `docs/site`.
+- Publish generated output to selected Pages target.
+- Document canonical URL and redirect policy.
+
+## 6) Commit hygiene for agents
+
+- Separate commits by concern (bootstrap vs content vs deploy).
+- Keep generated file updates reviewable.
+- Update `docs/README.md` whenever paths or process docs move.
diff --git a/docs/bridgetown/execution-plan.md b/docs/bridgetown/execution-plan.md
@@ -0,0 +1,63 @@
+# Bridgetown Migration Execution Plan
+
+This plan defines how to migrate SolverForge documentation to Bridgetown while making this repository the canonical website source.
+
+## Goals
+
+- Replace ad-hoc Markdown docs navigation with a Bridgetown site.
+- Keep all source content in this repository.
+- Enable deterministic local execution so agents can provide code-level references.
+- Preserve existing technical docs while improving discoverability.
+
+## Proposed target layout
+
+```text
+docs/
+  README.md
+  AGENTS.md
+  bridgetown/
+    execution-plan.md
+    agent-runbook.md
+  reference/
+    *.md
+  site/                  # Bridgetown app root (to be created)
+    bridgetown.config.yml
+    src/
+      index.md
+      guides/
+      architecture/
+      api/
+```
+
+## Phased rollout
+
+### Phase 1 — Bootstrap site
+
+- Create Bridgetown app in `docs/site`.
+- Add minimal navigation and homepage.
+- Configure local serve/build scripts.
+
+### Phase 2 — Content migration
+
+- Migrate docs from `docs/reference/` into `docs/site/src/` information architecture.
+- Keep redirects/stubs for moved paths as needed.
+- Normalize heading and front matter conventions.
+
+### Phase 3 — Deployment
+
+- Decide canonical URL strategy:
+  - keep `solverforge.github.io` host repository as thin deploy target, or
+  - switch canonical URL to custom domain and deploy directly from this repo.
+- Add CI workflow to build and publish Bridgetown output.
+
+### Phase 4 — Cleanup
+
+- Remove temporary migration stubs.
+- Keep `docs/reference/` only if needed as archival source; otherwise fully fold into `docs/site/src/`.
+
+## Definition of done
+
+- Bridgetown site builds locally from documented commands.
+- Existing core docs are migrated and accessible via site navigation.
+- Deployment path is documented and reproducible.
+- Agent instructions in `docs/AGENTS.md` and `docs/bridgetown/agent-runbook.md` remain current.
diff --git a/docs/extend-domain.md → docs/reference/extend-domain.md b/docs/extend-domain.md → docs/reference/extend-domain.md
diff --git a/docs/extend-solver.md → docs/reference/extend-solver.md b/docs/extend-solver.md → docs/reference/extend-solver.md
diff --git a/docs/reference/github-pages-migration.md b/docs/reference/github-pages-migration.md
@@ -0,0 +1,83 @@
+# GitHub Pages Migration: `solverforge.github.io` -> `solverforge/docs`
+
+This note documents whether we can retire the standalone `solverforge.github.io` repository and publish the website directly from the `docs/` directory in this repository.
+
+## Short answer
+
+Yes, we can move the **content source of truth** into this repository's `docs/` folder.
+
+However, if we must keep the site URL as **`https://solverforge.github.io/`**, we should expect to keep either:
+
+1. the `solverforge.github.io` repository itself, or
+2. an equivalent GitHub Pages target that still owns that hostname.
+
+In practice, for an organization/user Pages root URL (`<org>.github.io`), the special Pages target remains the safest anchor.
+
+## If you control a custom domain
+
+If you can point your own domain wherever you want (DNS + TLS), then yes: you can usually retire the separate `solverforge.github.io` repository.
+
+In that model:
+
+- Publish Pages from this `solverforge` repository (for example via GitHub Pages Actions).
+- Set your custom domain (for example `docs.solverforge.dev`) to that Pages site.
+- Keep redirects in place from old URLs as needed.
+
+Important distinction:
+
+- `https://solverforge.github.io/` is GitHub-owned hostname semantics.
+- Your custom domain is fully under your control.
+
+So if your canonical URL becomes your custom domain, the special `solverforge.github.io` host repo is not strictly required.
+
+## Recommended migration model
+
+Use this repository (`solverforge`) as the single authoring source, and publish to the Pages target via CI.
+
+### Phase 1: Make `docs/` authoritative
+
+- Keep all website content in `solverforge/docs/`.
+- If the site needs generation (e.g. mdBook, Docusaurus, MkDocs), build from `docs/` in CI.
+- If the site is static HTML/CSS/JS already, deploy `docs/` directly.
+
+### Phase 2: Automated publish bridge
+
+- Add a workflow in this repository that triggers on changes under `docs/**`.
+- The workflow publishes the rendered site artifact to the Pages host repository branch.
+- Keep deploy credentials in org secrets and lock workflow permissions to least privilege.
+
+### Phase 3: Decommission manually-edited content in `solverforge.github.io`
+
+- Remove hand-maintained site files there.
+- Keep only the minimal Pages/deploy plumbing needed to serve `https://solverforge.github.io/`.
+- Optionally archive that repository if deployment ownership is moved elsewhere without losing the hostname target.
+
+## Alternatives
+
+### A) Full delete of `solverforge.github.io` repo
+
+This is only safe if we are also willing to change public URL strategy (for example, project Pages URL or custom domain) and update inbound links.
+
+### B) Keep URL and keep tiny host repo
+
+This is the least risky option:
+
+- `solverforge` holds all docs and site source.
+- `solverforge.github.io` becomes a thin deploy target only.
+- No manual edits needed in the host repo.
+
+## Decision checklist
+
+Before proceeding, confirm:
+
+- Must canonical URL stay `https://solverforge.github.io/`?
+- Is a custom domain planned now or later, and who owns DNS/TLS renewals?
+- Is generated output committed, or build-only in CI?
+- Who owns deploy credentials and branch protections?
+- Do we need redirects from old paths?
+
+## Suggested next step
+
+If canonical URL must stay exactly `https://solverforge.github.io/`, proceed with **Option B** (thin host repo + docs source in this repository).
+
+If URL can change (or custom domain is ready), we can evaluate retiring the special repository entirely.
diff --git a/docs/lifecycle-pause-resume-contract.md → ...erence/lifecycle-pause-resume-contract.md b/docs/lifecycle-pause-resume-contract.md → ...erence/lifecycle-pause-resume-contract.md
diff --git a/docs/typed-contract-audit.md → docs/reference/typed-contract-audit.md b/docs/typed-contract-audit.md → docs/reference/typed-contract-audit.md