diff --git a/README.md b/README.md index 9529b938..1d4a1195 100644 --- 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 new file mode 100644 index 00000000..bbec9f0f --- /dev/null +++ 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 new file mode 100644 index 00000000..21079ad5 --- /dev/null +++ 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 new file mode 100644 index 00000000..ac57f5ce --- /dev/null +++ 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 new file mode 100644 index 00000000..c7ee9fc8 --- /dev/null +++ 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 b/docs/reference/extend-domain.md similarity index 100% rename from docs/extend-domain.md rename to docs/reference/extend-domain.md diff --git a/docs/extend-solver.md b/docs/reference/extend-solver.md similarity index 100% rename from docs/extend-solver.md rename to docs/reference/extend-solver.md diff --git a/docs/reference/github-pages-migration.md b/docs/reference/github-pages-migration.md new file mode 100644 index 00000000..e604325c --- /dev/null +++ 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 (`.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 b/docs/reference/lifecycle-pause-resume-contract.md similarity index 100% rename from docs/lifecycle-pause-resume-contract.md rename to docs/reference/lifecycle-pause-resume-contract.md diff --git a/docs/typed-contract-audit.md b/docs/reference/typed-contract-audit.md similarity index 100% rename from docs/typed-contract-audit.md rename to docs/reference/typed-contract-audit.md