BloxClips docs

Appearance

How these docs work ​

Guide · last verified 2026-09-27. This page describes the docs repo itself — start here if you are about to write or reorganize documentation.

Two layers ​

  • Guides (this section) are hand-written, human-maintained, and small by design. They teach: onboarding, QA method, architecture, and this page. The sidebar shows guides first. If a guide contradicts a repo's source or tests, the repo wins — fix the guide.
  • Reference (everything else) is the full working record: scoped plans, audits, handoffs, and the historical archive. It is complete and full-text searchable, but it is not a reading list. Each page carries its own status note; "dated snapshot" means evidence, not instructions.

AI tooling reads the raw markdown of both layers. Humans should start with guides and search reference only when they need provenance.

Freshness rules ​

  • Guides carry a "last verified" line with a date. If yours is older than a quarter, re-verify it against the codebases or hand it to someone who can.
  • Reference pages keep their original status notes. Do not rewrite history — add a new note instead.
  • Never delete migrations, legacy evidence, or audit material. Archive, label, don't purge.

Writing a docs change ​

  1. Acquire a lease: scripts/treehouse-bloxclips acquire docs --task <TASK> from the workspace root. Branch task/<issue>-<slug>, base origin/main.
  2. Keep filenames stable — issues and code PRs link to these paths.
  3. Run npm run docs:build before every docs PR; it must stay green.
  4. Open the PR against main with the standard sections (Summary, Why, Scope, Verification, Data/Migration Impact, Risks/Rollback, Links) and link the counterpart code PRs explicitly.
  5. Never commit tokens, credentials, provider bodies, or personal data. Never commit .vitepress/dist, .vitepress/cache, or node_modules.

Links starting with ../ (../AGENTS.md, ../.agents/skills/*) and links to sibling checkouts resolve in the outer BloxClips workspace, not on this site — that is intentional and the build does not check them. Prefer site-local links in guides; leave historical links in reference pages alone.