Documentation Policy

The versioned Markdown under docs/ is the only authored product documentation source. The static website, generated reference pages, search index, llms.txt, and llms-full.txt are derived from it. Praxist does not use a separately edited GitHub Wiki.

One Fact, One Owner

Information	Sole owner	Other pages may
CLI arguments and defaults	praxist.cli parser code	Link to generated CLI reference
Skill name and activation description	Each skills/*/SKILL.md front matter	Link to generated Skills reference
Package installation, install commands, and filesystem effects	Installation	Link; the root landing page may show one canonical command
User-facing first-run/OOBE sequence	Quickstart	Name the lane and link
Agent-managed OOBE implementation	Agent OOBE Runbook	Link without duplicating agent instructions
Project prerequisites, research brief, and takeover stages	Your First Task	Show one takeover invocation and link
Goal-to-skill map and skill installation locations	Agent Skills	Name a relevant skill and link
Task schema, precedence, and scientific ownership	Task Projects	Explain how a mechanism consumes the task contract
Template/example distinction and example materialization commands	Examples And Templates	Identify an asset and link without redefining the boundary
Rocket Booster Recovery scientific details	examples/rocket_booster_recovery/README.md	Explain discovery and launch without duplicating its protocol
Rocket Booster Recovery (Rust) scientific details	examples/rocket_booster_recovery_rust/README.md	Explain discovery and launch without duplicating its protocol
Lifecycle semantics	Direct CLI Operations	Show one quickstart command and link
Core/plugin/task boundary and artifact roles	Architecture	Summarize purpose and link
Configuration ingress and precedence	Configuration Discipline	State a local input and link
Agent-session and prompt-layout mental model	Runtime Model	Explain a mechanism-specific effect and link
Runtime adapter capabilities	Agent Runtimes	Identify a selected runtime and link
API provider shapes	API Providers	Identify a selected provider and link
Open-source model API shortlist and selection criteria	Open-Source Model APIs	Link without duplicating the shortlist
Authentication and credential precedence	Credentials	State a prerequisite and link
Research-loop sequence	Research Loop	Refer to a stage without redefining the sequence
Maturity, close, incubator, peer-mix, and launch-freeze behavior	Flexibility Controls	Show task configuration only where Task Projects owns the combined profile
Deep Innovation Gate (DIG) behavior and artifacts	Deep Innovation Gate	State whether DIG is active and link
Quality-Diversity (QD) allocation	Quality-Diversity Allocation	Refer to the selected path and link
Peer-session memory	Peer Memory	Refer to memory as context and link
Experiment admission and resource ownership	Central Experiment Scheduler	State the selected profile and link
Tool catalog and frontier-tool behavior	Tool Servers	Name a tool and link
Literature source/provenance policy	Scientific Literature Lookup	State whether lookup is enabled and link
Human-readable report triggers and semantics	Run Reports	Link to a generated report or this guide
Usage measurement and formulas	Cost Estimation	Link to measured artifacts and this guide
Lossless token-saving mechanisms	Cost Optimization	State that a route uses the policy and link
Contributor contract	AGENTS.md	Link without redefining it
Software license	Root LICENSE.md	Link without restating license terms
User Agreement	Praxist User Agreement	Link without restating legal terms
Product-usage privacy policy, processing purposes, retention, and user rights	Privacy Notice	Link without restating the policy
Exact versioned product-usage consent text	Praxist User Data Collection Notice	The CLI loads this same package resource; other pages identify it and link
Product-usage consent commands and collector operation	Product Usage Controls	Link to the operational procedure
Product-usage implementation, endpoint, storage, and audit map	Product Usage Technical Documentation	Link without duplicating implementation details
Machine product-usage event schema	praxist/product_usage/protocol.py and checked-in JSON Schema	Technical and legal pages explain the contract; code remains authoritative for exact validation
Hosted documentation URL	praxist.cli.docs.DOCUMENTATION_URL	Mirror it in checked package/site metadata and link to it

Tutorials sequence actions. Guides explain procedures. Concept pages explain mental models. Reference pages enumerate machine contracts. The root README is a product landing page, not a second manual.

A minimal command may appear in a tutorial that needs the action, but its arguments, defaults, and edge cases remain in the generated reference. A page may summarize an adjacent contract only far enough to explain its own behavior; the summary must link to the owner instead of restating the contract.

Generated Sources

scripts/build_docs_site.py creates:

• docs/reference/cli.md from the live CLI parser;
• docs/reference/skills.md from skill front matter;
• site/llms.txt as a compact machine-readable map;
• site/llms-full.txt as the complete navigation-ordered corpus.

Generated HTML and LLM exports are not committed. Generated Markdown reference pages are committed so package users can read them without building the site, but CI verifies that they exactly match their code-owned inputs.

Navigation Ownership

Every authored Markdown page must appear exactly once in mkdocs.yml. This makes its primary audience and information role explicit. The docs build rejects missing pages, duplicate navigation ownership, and broken local links.

Build

uv sync --extra docs
uv run python scripts/build_docs_site.py
uv run python scripts/build_docs_site.py --check-generated

The build runs in strict mode and does not contact API providers, read API keys, or start research services.

Hosted Documentation

Documentation validation runs on every pull request and every push to main. Successful pushes to main publish the generated site to the repository's private GitHub Pages project. Access follows repository read permission and requires GitHub authentication; the generated HTML remains derived output and is not committed.

The repository variable PRAXIST_PAGES_ENABLED=true is the deployment switch. Maintainers can also trigger the docs workflow manually. Pull requests build and validate the complete site but never publish it.

The canonical site URL is surfaced through praxist docs. Contributors use the local build commands above only to preview unmerged changes.