This directory contains the source for https://roborev.io. The site has three tiers assembled by one build:

llms.txt indexes all three tiers for machine readers. The docs source lives on main; image media lives on orphan asset branches so normal clones do not pull large screenshots and PNGs into the main history.

• *.md, guides/, advanced/, integrations/, agents/: public docs source, rendered under /docs/.
• website/: the hand-written product page, guide, 404 page, styles, script, and self-hosted fonts (OFL licenses alongside). Copied verbatim to the site root. Every local reference must be root-relative (/docs/..., /styles/...); media comes from the hydrated /docs/assets/... tree, never from tracked files.
• llms.txt: the machine-readable site index.
• zensical.toml: Zensical site configuration and navigation.
• pyproject.toml and uv.lock: pinned docs toolchain.
• vercel.json and vercel-build.sh: Vercel project configuration.
• assets/hydrate-assets.sh: hydrates ignored local assets from orphan branches.
• assets/update-static-assets-branch.sh: updates curated static assets.
• screenshots/: Docker/tmux/freeze screenshot generator and generated asset branch updater.
• scripts/format_markdown.py: syntax-aware formatting for published pages.
• scripts/check_built_site.py, scripts/check_public_markdown_sources.py, and scripts/check_vercel_redirects.py: post-build validation. check_vercel_redirects.py --write regenerates vercel.json from the nav after a docs page is added, moved, or removed.

docs/assets/static/, docs/assets/generated/, docs/site/, and docs/.venv/ are ignored local outputs.

• docs-assets: curated static media, including logos, favicons, Open Graph images, diagrams, agent icons, and manually captured integration images.
• docs-generated-assets: generated browser UI, CLI, and TUI screenshots.

Docs pages and the website tier should reference media through:

• /docs/assets/static/... for curated assets.
• /docs/assets/generated/... for generated screenshots.

The root favicon.svg is copied from the hydrated static assets at build time.

Do not commit image media to main.

Install the docs toolchain:

make docs-install

Hydrate assets and build:

make docs-build

Preview the docs tier at http://localhost:8000/docs/:

make docs-serve

Zensical serves only the docs tier, mounted at /docs/ as in production. The product page and guide are static files it does not serve. Both targets below render a staged copy of the docs tree, so restart them to pick up edits. To preview the whole site with production routing, build it and serve the assembled site/ directory:

make docs-preview                          # http://127.0.0.1:8000/
make docs-preview DOCS_PREVIEW_PORT=8765   # another port

Run all docs validation:

make docs-check

Format all Markdown pages listed by zensical.toml:

make markdown

The formatter wraps prose at 80 columns and leaves Markdown tables unchanged. Use make markdown-ci for the non-mutating check run by prek and CI.

make docs-check hydrates assets, runs a strict Zensical build, checks generated links/assets/metadata, verifies public Markdown source files, and validates vercel.json redirects.

Asset hydration force-fetches origin/docs-assets and origin/docs-generated-assets by default so force-pushed orphan branches do not silently leave stale local media in place. Set ROBOREV_DOCS_USE_LOCAL_ASSET_BRANCHES=1 only when you intentionally want to hydrate from local asset branch refs instead of origin.

Regenerate generated CLI/TUI screenshots and update the local docs-generated-assets orphan branch:

make docs-generated-assets-branch

Push that branch when the generated screenshots should be published:

bash docs/screenshots/update-generated-assets-branch.sh --push

The script writes screenshots to ignored docs/assets/generated/, validates the expected SVGs, creates a temporary git repository with a single commit, then fetches that commit into docs-generated-assets. It does not switch branches. Screenshot data is derived from the maintainer's local roborev database, selected only from committed review jobs for repos whose identity or origin remote matches the canonical public kenn-io/roborev, kenn-io/kata, kenn-io/msgvault, and kenn-io/agentsview repositories. The demo DB keeps public repo/job metadata such as repo names, refs, branches, statuses, timings, verdict mix, token usage, prompts, diffs, and review output so screenshots stay representative of real open-source review data. The copy omits responses and sanitizes local paths, local usernames, email addresses, and credential-shaped tokens before Docker renders screenshots. The generated demo database is written to $TMPDIR/roborev-demo-data.

For the initial import or a manual refresh from an existing directory:

bash docs/screenshots/update-generated-assets-branch.sh --source /path/to/assets --push

Hydrate or stage curated media under ignored docs/assets/static/, then update the local docs-assets orphan branch:

make docs-assets-branch

Push it only when curated static assets should be published:

bash docs/assets/update-static-assets-branch.sh --push

This branch is separate from docs-generated-assets so normal screenshot regeneration cannot accidentally overwrite curated media.

Use the plain-language rules in AGENTS.md.

1. Compare the new release tag with the previous release tag. Check release notes against shipped changes; do not describe proposals as available.
2. Move shipped Unreleased entries into a dated version section in changelog.md. Group entries into new features, improvements, and bug fixes. Lead with what users can do or what problem changed, and link to the owning guide for instructions.
3. Update those guides in place. Put upgrade actions in the installation guide and link to the detailed configuration or migration instructions. Keep historical release entries as history.
4. Add acknowledgements based on authors and human co-authors in the release range and merged pull requests. Verify public names and profile links, and describe each contributor's work. Do not infer credit from commit counts or private review activity.
5. Run make markdown, make markdown-ci, and make docs-check. Review the diff for stale instructions, broken links, and claims that need qualification.

Documentation checks build locally. Publishing docs and editing GitHub release notes are separate actions; use the publishing workflow only when requested.

The Vercel project should be linked from the repository root with docs/ as the Vercel root directory:

The build wrapper renders the Zensical docs into site/docs/, copies index.md and every nav-listed Markdown document alongside its rendered page (for example, /docs/changelog.md serves the Markdown source that generated /docs/changelog/, and section indexes such as agents/index.md also publish a flattened /docs/agents.md twin), then copies the website tier and llms.txt to the site root. Every rendered docs page advertises its twin with <link rel="alternate" type="text/markdown">.

Docs used to be served from the site root. vercel.json carries a permanent redirect for every old page, its Markdown twin, and the /assets/... media paths, so external links and older binaries keep resolving.

Link the checkout once from the repository root:

vercel link

When prompted, choose the roborev docs Vercel project. The generated .vercel/ directory is local-only and ignored.

Deploy committed docs changes with:

scripts/update-docs.sh

That helper requires a clean tracked tree, installs the docs toolchain, regenerates and pushes docs-generated-assets, clears and rehydrates local assets, builds, checks, and then runs:

make docs-deploy

Create a Vercel preview/staging deployment before production with:

make docs-deploy-staging

Use make docs-deploy directly only when the asset branches and local build state are already correct.