CodingThrust · GiggleLiu · Sep 7, 2026 · Sep 6, 2026 · Sep 6, 2026
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -49,10 +49,15 @@ jobs:
           node scripts/generate_reduction_graph_layout.js
           cargo run --example export_schemas
           cargo run --example export_module_graph
+          cargo build -p problemreductions-cli --bin pred
+          bash scripts/generate_doc_snippets.sh target/debug/pred
 
       - name: Build mdBook
         run: mdbook build
 
+      - name: Build research website
+        run: python3 scripts/build_website.py
+
       - name: Build PDF
         run: typst compile --root . docs/paper/reductions.typ book/reductions.pdf
 

diff --git a/Makefile b/Makefile
@@ -1,6 +1,6 @@
 # Makefile for problemreductions
 
-.PHONY: help build test mcp-test fmt clippy doc mdbook paper clean coverage rust-export compare qubo-testdata export-schemas release run-plan run-issue run-pipeline run-pipeline-forever run-review run-review-forever board-next board-claim board-ack board-move issue-context issue-guards pr-context pr-wait-ci worktree-issue worktree-pr diagrams jl-testdata cli cli-demo copilot-review papers papers-lookup papers-download papers-scihub papers-status papers-push papers-pull papers-index
+.PHONY: help build test mcp-test fmt clippy doc mdbook website paper clean coverage rust-export compare qubo-testdata export-schemas release run-plan run-issue run-pipeline run-pipeline-forever run-review run-review-forever board-next board-claim board-ack board-move issue-context issue-guards pr-context pr-wait-ci worktree-issue worktree-pr diagrams jl-testdata cli cli-demo copilot-review papers papers-lookup papers-download papers-scihub papers-status papers-push papers-pull papers-index
 
 RUNNER ?= codex
 CLAUDE_MODEL ?= opus
@@ -21,6 +21,7 @@ help:
 	@echo "  doc          - Build mdBook documentation"
 	@echo "  diagrams     - Generate SVG diagrams from Typst (light + dark)"
 	@echo "  mdbook       - Build and serve mdBook (with live reload)"
+	@echo "  website      - Build the research website and documentation"
 	@echo "  paper        - Build Typst paper from checked-in fixtures (requires typst)"
 	@echo "  coverage     - Generate coverage report (requires cargo-llvm-cov)"
 	@echo "  clean        - Clean build artifacts"
@@ -93,11 +94,23 @@ doc: node_modules/elkjs/package.json
 	node scripts/generate_reduction_graph_layout.js
 	cargo run --example export_schemas
 	cargo run --example export_module_graph
-	bash scripts/generate_doc_snippets.sh target/release/pred
-	mdbook build docs
+	cargo build -p problemreductions-cli --bin pred
+	bash scripts/generate_doc_snippets.sh target/debug/pred
+	mdbook build
+	python3 scripts/build_website.py
 	RUSTDOCFLAGS="--default-theme=dark" cargo doc --features ilp-highs --no-deps
-	rm -rf docs/book/api
-	cp -r target/doc docs/book/api
+	rm -rf book/api
+	cp -r target/doc book/api
+
+# Build the product website with fresh atlas data; API/PDF builds remain in doc/paper.
+website:
+	cargo run --example export_graph
+	cargo run --example export_schemas
+	cargo run --example export_module_graph
+	cargo build -p problemreductions-cli --bin pred
+	bash scripts/generate_doc_snippets.sh target/debug/pred
+	mdbook build
+	python3 scripts/build_website.py
 
 # Generate SVG diagrams from Typst sources (light + dark themes)
 TYPST_DOC_DIAGRAMS := $(wildcard docs/src/static/*.typ)
@@ -121,11 +134,13 @@ mdbook: node_modules/elkjs/package.json
 	@echo "Exporting module graph..."
 	@cargo run --example export_module_graph 2>&1 | tail -1
 	@echo "Generating CLI doc snippets..."
-	@bash scripts/generate_doc_snippets.sh target/release/pred 2>&1 | tail -1
+	@cargo build -p problemreductions-cli --bin pred
+	@bash scripts/generate_doc_snippets.sh target/debug/pred
 	@echo "Building API docs..."
 	@RUSTDOCFLAGS="--default-theme=dark" cargo doc --features ilp-highs --no-deps 2>&1 | tail -1
 	@echo "Building mdBook..."
 	@mdbook build
+	@python3 scripts/build_website.py
 	rm -rf book/api
 	cp -r target/doc book/api
 	@-lsof -ti:3001 | xargs kill 2>/dev/null || true

diff --git a/book.toml b/book.toml
@@ -9,9 +9,9 @@ src = "docs/src"
 default-theme = "navy"
 git-repository-url = "https://github.com/CodingThrust/problem-reductions"
 edit-url-template = "https://github.com/CodingThrust/problem-reductions/edit/main/{path}"
-additional-css = ["docs/src/static/theme-images.css", "docs/src/static/reduction-graph.css", "docs/src/static/module-graph.css"]
-additional-js = ["docs/src/static/cytoscape.min.js", "docs/src/static/reduction-graph.js", "docs/src/static/module-graph.js"]
-no-section-label = false
+additional-css = ["docs/src/static/docs-theme.css", "docs/src/static/theme-images.css", "docs/src/static/reduction-graph.css", "docs/src/static/module-graph.css"]
+additional-js = ["docs/src/static/docs-theme.js", "docs/src/static/cytoscape.min.js", "docs/src/static/reduction-graph.js", "docs/src/static/module-graph.js"]
+no-section-label = true
 
 [output.html.fold]
 enable = true

diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md
@@ -1,18 +1,54 @@
 # Summary
 
-[Introduction](./introduction.md)
+[Overview](introduction.md)
 
-# User Guide
+# Start here
 
-- [CLI Tool](./cli.md)
-- [AI Agent Skills](./skills.md)
+- [CLI in action](cli-demo.md)
+- [Start with an agent](skills.md)
+- [Install the CLI](install.md)
+- [First solve](cli.md)
 
-# Rust Library
+# Agent workflows
 
-- [Getting Started](./getting-started.md)
-- [Design](./design.md)
-- [API Reference](./api.md)
+- [Find a solver](agent-find-solver.md)
+- [Extend a solver's reach](agent-find-problem.md)
+- [Propose a model or rule](agent-propose.md)
+- [Implement and review](agent-pipeline.md)
+- [Connect with MCP](mcp.md)
+  - [Tool reference](mcp-tools.md)
+  - [Example session](mcp-walkthrough.md)
 
-# Reference
+# CLI reference
 
-- [MCP Server](./mcp.md)
+- [Explore the catalog](cli-catalog.md)
+- [Names and variants](cli-variants.md)
+- [Find reduction paths](cli-paths.md)
+- [Create an instance](cli-create.md)
+  - [Input examples](cli-examples.md)
+  - [Random instances](cli-random.md)
+- [Inspect and evaluate](cli-inspect.md)
+- [Reduce an instance](cli-reduce.md)
+- [Solve an instance](cli-solve.md)
+- [JSON and automation](cli-automation.md)
+- [Shell completions](cli-completions.md)
+
+# Rust library
+
+- [First Rust program](getting-started.md)
+- [Apply a reduction](rust-reduction.md)
+- [Discover and execute paths](rust-paths.md)
+- [Solver contracts](rust-solvers.md)
+- [API reference](api.md)
+
+# Internals
+
+- [Architecture](design.md)
+- [Problem contract](design-problem.md)
+- [Variant system](design-variants.md)
+  - [Register variants](design-variant-registration.md)
+- [Reduction contracts](design-reductions.md)
+- [Path costs and overhead](design-paths.md)
+- [JSON serialization](design-serialization.md)
+- [Reduction graph](reduction-graph.md)
+- [Contributing](contributing.md)
diff --git a/docs/src/agent-find-problem.md b/docs/src/agent-find-problem.md
@@ -0,0 +1,29 @@
+# Extend a solver's reach
+
+Find source problems that can reduce to a solver you already have.
+
+**Before you start:** complete [agent setup](skills.md). Specify the solver's accepted model, topology, weights, and practical size limit.
+
+## Prompt
+
+```text
+Read .claude/skills/find-problem/SKILL.md and follow it.
+My solver accepts: [exact model and variant].
+Its time complexity and practical size limit: [details].
+Find incoming reduction routes and rank useful source problems.
+Show the assumptions and composed size overhead for each recommendation.
+Write the findings to docs/solutions/.
+```
+
+## Check the direction
+
+A solver for a target can handle sources that reduce **to** it. For example:
+
+```bash
+pred to QUBO
+pred path MIS QUBO
+```
+
+A route in the opposite direction does not establish that capability. Confirm each candidate's exact variants and measure the constructed target size on a small instance.
+
+Next: [reduce an instance](cli-reduce.md).
diff --git a/docs/src/agent-find-solver.md b/docs/src/agent-find-solver.md
@@ -0,0 +1,26 @@
+# Find a solver
+
+Map a concrete problem to a library model and a usable solver route.
+
+**Before you start:** complete [agent setup](skills.md). Describe the inputs, constraints, objective, and expected instance sizes.
+
+## Prompt
+
+```text
+Read .claude/skills/find-solver/SKILL.md and follow it.
+My problem: [describe inputs, constraints, and objective].
+Typical size: [counts and ranges].
+Available solvers or hardware: [list, or no preference].
+Check the exact model variant and current reduction paths with pred.
+Separate implemented routes from suggestions that need new work.
+```
+
+## Expected result
+
+A solution document in `docs/solutions/` with the proposed model, assumptions, reduction route, size overheads, and solver recommendation.
+
+## Check the recommendation
+
+Ask the agent to construct a small instance, solve it, and evaluate the recovered configuration on the original problem. If several models fit, resolve the modeling differences before scaling up.
+
+Next: [first solve](cli.md) or [inspect a route](cli-paths.md).
diff --git a/docs/src/agent-pipeline.md b/docs/src/agent-pipeline.md
@@ -0,0 +1,31 @@
+# Implement and review
+
+Move a prepared issue through the repository's agent workflow. These commands act on GitHub issues, project status, and pull requests; run them in a configured maintainer checkout.
+
+## Implement one issue
+
+```bash
+make run-issue N=42
+```
+
+Replace `42` with the issue number. The task follows `.claude/skills/issue-to-pr/SKILL.md`. Model and rule skills define the source, tests, examples, and paper changes required.
+
+To pick one eligible Ready issue from the project board:
+
+```bash
+make run-pipeline
+```
+
+## Review one pull request
+
+```bash
+make run-review N=570
+```
+
+Replace `570` with the PR number. The review workflow checks structure, quality, and user-facing behavior, then moves the PR to Final review. Maintainer review controls acceptance.
+
+## Evidence to retain
+
+Keep the mathematical argument, constructor and adversarial checks, closed-loop tests, canonical example, and review findings with the work. A passing test suite is evidence for tested instances, not a proof for all inputs.
+
+For exact workflow rules, read [the repository instructions](https://github.com/CodingThrust/problem-reductions/blob/main/.claude/CLAUDE.md).
diff --git a/docs/src/agent-propose.md b/docs/src/agent-propose.md
@@ -0,0 +1,24 @@
+# Propose a model or rule
+
+Turn a mathematical idea or published construction into a precise proposal for the atlas.
+
+**Before you start:** complete [agent setup](skills.md). Bring a definition, a source reference, or a candidate source → target connection.
+
+## Prompt
+
+```text
+Read .claude/skills/propose/SKILL.md and follow it.
+I want to propose: [model or source-to-target reduction].
+Reference or construction: [details].
+Check the current catalog for existing models and exact variant endpoints.
+Clarify the objective, solution mapping, correctness argument, and overhead.
+Prepare the proposal for the issue workflow.
+```
+
+## Expected result
+
+A model or rule proposal with explicit assumptions and enough mathematical detail to assess usefulness and correctness. The skill guides issue creation.
+
+For a rule, distinguish a construction supported by literature from a new conjecture. Record proof gaps and counterexamples explicitly.
+
+Next: [implementation and review](agent-pipeline.md) once the issue is ready.
diff --git a/docs/src/api.md b/docs/src/api.md
@@ -1,9 +1,7 @@
-# API Reference
+# API reference
 
-<meta http-equiv="refresh" content="0; url=api/problemreductions/index.html">
+[Browse the Rust API →](api/problemreductions/index.html)
 
-Full API documentation is auto-generated from source code via `rustdoc`.
+The API is generated from Rust source with rustdoc. Start with [models](api/problemreductions/models/index.html), [reduction contracts](api/problemreductions/rules/index.html), or [solvers](api/problemreductions/solvers/index.html).
 
-**[Browse the API &rarr;](api/problemreductions/index.html)**
-
-If not redirected automatically, run `make doc` to generate the API docs.
+Run `make doc` to build the guides and API locally. For short runnable examples, see [first Rust program](getting-started.md) and [apply a reduction](rust-reduction.md).
diff --git a/docs/src/cli-automation.md b/docs/src/cli-automation.md
@@ -0,0 +1,37 @@
+# JSON and automation
+
+Use structured output for agent tools and scripts.
+
+```bash
+pred list --json
+pred show MIS --json
+pred path MIS QUBO --json
+pred solve problem.json -o solution.json
+```
+
+| Global flag | Effect |
+|---|---|
+| `--json` | Request JSON output for data commands |
+| `-o, --output <FILE>` | Save JSON to a file |
+| `-q, --quiet` | Suppress informational messages on stderr |
+
+Check the process exit status before consuming a result. Preserve `type` and `variant` with each instance; an alias alone is insufficient to replay an exact endpoint.
+
+## Pipe instances
+
+```bash
+pred create MIS --graph 0-1,1-2,2-3 | pred solve - --json
+pred create MIS --graph 0-1,1-2,2-3 | pred reduce - --to QUBO | pred solve - --solver brute-force --json
+```
+
+`-` reads a problem or bundle from stdin. In shell automation, enable `set -o pipefail` so a failed earlier command fails the pipeline.
+
+## Registry exports
+
+```bash
+pred export-graph -o reduction_graph.json
+```
+
+The docs build publishes [reduction_graph.json](reductions/reduction_graph.json) and [problem_schemas.json](reductions/problem_schemas.json). The graph includes exact variants, directed edges, capabilities, and symbolic overheads; schemas describe model fields.
+
+Use the [Markdown index](markdown/index.md) for task instructions and these JSON files for structured registry queries. The exports describe the website's build; local CLI output describes the installed version.
diff --git a/docs/src/cli-catalog.md b/docs/src/cli-catalog.md
@@ -0,0 +1,22 @@
+# Explore the catalog
+
+Use the installed registry to discover models, accepted fields, and reductions.
+
+```bash
+pred list
+pred show MIS
+pred show MIS --json
+```
+
+`list` reports names and aliases. `show` describes the resolved variant, its size fields, input schema, and incoming/outgoing reductions. Use that schema before constructing an instance.
+
+<details>
+<summary>Example: inspect Maximum Independent Set</summary>
+
+```text
+{{#include generated/pred-show-mis.txt}}
+```
+
+</details>
+
+For machine-readable catalog data, use `pred list --json`. Use [names and variants](cli-variants.md) to select exact endpoints and [path queries](cli-paths.md) to explore their connections.
diff --git a/docs/src/cli-completions.md b/docs/src/cli-completions.md
@@ -0,0 +1,16 @@
+# Shell completions
+
+Enable tab completion by adding one line to your shell config:
+
+```bash
+# bash (~/.bashrc)
+eval "$(pred completions bash)"
+
+# zsh (~/.zshrc)
+eval "$(pred completions zsh)"
+
+# fish (~/.config/fish/config.fish)
+pred completions fish | source
+```
+
+If the shell argument is omitted, `pred completions` auto-detects your current shell.
diff --git a/docs/src/cli-create.md b/docs/src/cli-create.md
@@ -0,0 +1,26 @@
+# Create an instance
+
+**Input:** a model name or exact variant, plus fields from `pred show <model>`.
+**Output:** a JSON problem file containing `type`, `variant`, and `data`.
+
+```bash
+pred create MIS --graph 0-1,1-2,2-3 -o problem.json
+pred create MIS/SimpleGraph/i32 --graph 0-1,1-2,2-3 --weights 2,1,3,1 -o weighted.json
+pred inspect weighted.json
+```
+
+Vertices use zero-based indices. `--graph` is a comma-separated edge list; weights must match the model's expected vertices or edges.
+
+## Use a canonical example
+
+```bash
+pred create --example MIS/SimpleGraph/i32 -o model.json
+pred create --example MVC/SimpleGraph/i32 --to MIS/SimpleGraph/i32 -o source.json
+pred create --example MVC/SimpleGraph/i32 --to MIS/SimpleGraph/i32 --example-side target -o target.json
+```
+
+The first command loads a model fixture. The next two load the source and target of a documented reduction example.
+
+CLI fields follow schema names: `universe_size` becomes `--universe-size`, and `subsets` becomes `--subsets`.
+
+Next: [input examples](cli-examples.md), [random instances](cli-random.md), or [inspect and evaluate](cli-inspect.md).