Contributing

This page embeds CONTRIBUTING.md from the repository, followed by notes on the dashboard UI concepts and the documentation site.

Coding agents

If you work on Reverie with a coding agent (Claude Code, Codex, Cursor and others), point it at AGENTS.md. It holds the architecture, repository map, checks, code rules and git workflow for agents.

Contributing

Workflow

1. Create a branch from main. Name it <type>/<short-topic>, for example feat/run-review, fix/pilot-typing-loop, or docs/design-md.
2. Commit in small steps. Conventional Commit messages are preferred on the branch, but only the PR title reaches main.
3. Push the branch and open a pull request with gh pr create --fill. Fill in the template: why, what changed, verification, and risk.
4. CI must pass: Python (lint + tests), UI (typecheck + Storybook build), and PR title.
5. Squash merge. The PR title becomes the one commit on main, and GitHub deletes the branch.

Do not push to main directly. Enable the local guard once per clone:

git config core.hooksPath scripts/hooks

PR titles

The title must be a Conventional Commit: type(scope): summary. release-please reads these titles to pick the next version and write CHANGELOG.md.

Type	Use it for	Version bump (before 1.0)	Changelog
feat	New behavior	minor	Features
fix	Bug fix	patch	Bug Fixes
perf	Faster, same behavior	patch	Performance
refactor	Code change, same behavior	patch	Refactoring
docs	Docs only	patch	Documentation
test, build, ci, chore	Tooling	none alone	hidden
feat! or BREAKING CHANGE:	Incompatible change	minor before 1.0, major after	Breaking

Common scopes: pilot, session, cli, dashboard, ui, examples, docs.

Versions and releases

• The version lives in pyproject.toml, reverie/__init__.py, and .release-please-manifest.json. Do not change it by hand.
• Each push to main updates one open release PR, titled chore(main): release X.Y.Z. Merge it when you want to cut a release. release-please then tags vX.Y.Z and creates the GitHub release.
• reverie --version prints the installed version.

Checks to run locally

uv run ruff check reverie tests
uv run pytest -q
(cd ui && npx tsc -b --noEmit && npm run build-storybook -- --quiet)

Dashboard UI concepts

ui/ holds a Storybook (Vite, React, Tailwind CSS v4 and shadcn/ui) with design concepts for a more usable dashboard. Start with the Overview story; the first concept, Run review, is the primary view. These are concepts, not the shipped UI. The dashboard that reverie ui serves lives in reverie/control/.

cd ui
npm install
npm run storybook        # http://localhost:6006

Design rules for the UI (tokens, icons, components and voice) are in DESIGN.md. Icons come only from Lucide through react-icons/lu, and the UI uses no emoji.

Working on these docs

The site lives in website/ and uses Astro with Starlight. Pages are Markdown files in website/src/content/docs/. Search is built in (Pagefind) and is generated at build time.

cd website
npm ci
npm run dev          # http://localhost:4321/reverie/
npm run build        # static site in website/dist/
npm run preview      # serve dist/ under the /reverie base
npm run check:links  # headless check of every internal link and asset (needs a running preview)

The site is served from the /reverie base path, so internal links include it, for example [CLI reference](/reverie/reference/cli/). The changelog and this contributing page are read from the repository’s CHANGELOG.md and CONTRIBUTING.md at build time; edit those files, not copies.

scripts/publish-docs.sh builds the site and pushes it to the gh-pages branch.

The tests mock every network call. One opt-in test calls the hosted Jev engine for real: REVERIE_LIVE_JEV=1 uv run pytest tests/test_jev_live.py -s, or scripts/jev-smoke.sh [--e2e]. It needs OPENROUTER_API_KEY and spends a little credit.

Use the docs type for documentation PR titles, for example docs: explain checkpoints.