relaybay 0.1.0__tar.gz

relaybay-0.1.0/.gitignore

@@ -0,0 +1,34 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+dist/
+build/
+site/
+*.egg-info/
+
+# Local data
+.dev-data/
+.demo-data/
+gif-data/
+*.sqlite
+*.sqlite3
+*.db
+.env
+.env.*
+!.env.example
+
+# Personal AI assistant settings (keep out of the public repo)
+CLAUDE.md
+CLAUDE.local.md
+.claude/
+.mcp.json
+
+# OS / editors
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/

relaybay-0.1.0/CHANGELOG.md

@@ -0,0 +1,186 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project
+adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-02
+
+First public release: a local board and MCP server for many Claude Code sessions, installable with
+one command (`uv tool install relaybay`, `uvx relaybay`, `pipx install relaybay` or the Docker
+image), with Claude Code hooks for live session status, working rules served to every session,
+`relaybay setup` and `relaybay doctor` for the machine setup, and a docs site.
+
+### Added
+
+- Packaging and release: version `0.1.0` in `pyproject.toml` (the only place; `relaybay
+  --version` reads the installed metadata), wheel and sdist with the templates, static assets and
+  migrations, a `Dockerfile` (`python:3.12-slim`, non-root, `/data` volume) and a release workflow
+  on `v*` tags: build and check the artifacts, publish to PyPI by trusted publishing, push the
+  multi-arch image `ghcr.io/codenator81/relaybay:<version>` and `:latest`, create the GitHub
+  Release with this file's notes and deploy the docs.
+- `relaybay doctor [--json]`: relaybay, Python and OS versions, data folder and token file, Claude
+  Code and its minimum supported version (2.0.0), the desktop app, the server with the same token,
+  MCP `initialize`, the hook endpoint, the rules hash against the running server, the hooks in the
+  user settings and the MCP registration. Read-only (it never creates the token); reports the
+  Claude Code files even when the server is down; the output has the shape of `setup --check
+  --json` and the exit code is 1 when an item fails.
+- `relaybay demo --home <dir> [--force]`: seeds a neutral demo workspace (`acme-shop`, `demo-api`:
+  tasks in every stage with descriptions, progress and reports, tracker badges, a stale next step,
+  a decision, a desktop session shown as working). A folder that already holds a board is refused;
+  `--force` renames its database aside first.
+- `/healthz` also returns `rules_hash`, the global rules the server started with.
+- Docs: install on Windows, macOS and Linux (uv, uvx, pipx, Docker), "Install relaybay with your
+  coding agent" (an idempotent procedure and a copy-paste prompt), CLI, configuration and MCP
+  reference pages generated by `scripts/gen_reference.py` (CI fails when they drift).
+- Community files: code of conduct (Contributor Covenant 2.1), security policy, governance note,
+  issue forms and a pull request template.
+- Live session status from Claude Code hooks: `POST /hooks/claude-code` (Bearer token, same
+  Host/Origin rules as `/mcp`) maps `SessionStart` / `UserPromptSubmit` / `PreToolUse` to working
+  (with the tool name as activity), `Notification` to waiting, `Stop` to idle and `SessionEnd` to
+  ended, which also unbinds the session from its tasks (`task.session_unbound`, reason
+  `session_end`). Activity is coalesced to one `session.status_changed` event per session per 5 s.
+  Cards show a status dot on the "open in desktop" icon; the task dialog shows the status and the
+  last activity. Prompt text and tool input are never stored.
+- Exact linking of hook sessions: the `SessionStart` answer tells the agent its hook session id,
+  and every write tool (and `task_bind_session`) accepts `hook_session`; the MCP instructions say
+  so. Without it, a hook session is linked by its working directory to the one desktop session bound
+  in that project; ambiguous cases stay unlinked and are listed on the Integrations page. Migration
+  `0007` adds `session.cc_session_id`, `activity_at` and `unlinked_reason`.
+- `relaybay setup` (`--dry-run` default, `--apply`, `--remove`, `--check [--json]`, `--expect
+  <plan hash>`, `--mode command|http` with `command` as the default, `--claude-home`): detects
+  `claude` and its version and the desktop app, prints the exact diff of `~/.claude/settings.json`
+  and its plan hash, backs the file up before any write (through a symlink to its target), adds or
+  removes only relaybay's own hook entries (a command hook running `relaybay.hook_client` with
+  `--url …/hooks/claude-code`, or an http hook posting exactly to `/hooks/claude-code` on a
+  loopback or the configured host), never writes the token, refuses files that are not UTF-8 or
+  valid JSON, and prints the `claude mcp add` command instead of editing `~/.claude.json`.
+  `--check` also runs the hook's interpreter once. `relaybay hook` and
+  `python -m relaybay.hook_client`: a standard-library command hook that gives up after 0.3 s and
+  always exits 0.
+- Board: **Integrations** page (header link) with detection, the plan, Apply / Remove / Run check
+  buttons (Apply and Remove write only the plan shown) and the unlinked hook sessions. Hook input
+  over 256 KB is dropped quietly (`204`). `relaybay serve --claude-home` / `RELAYBAY_CLAUDE_HOME`.
+- Working rules: the MCP server instructions are a short working contract (snapshot first, pick or
+  create a task, keep next step / waiting on / progress current, `state · size · gist` reports,
+  `waiting_on` for decisions, `task_patch` for missing fields). Rules as structured data (report
+  format, stage requirements `report_since_stage_change` / `field_present`, description template,
+  guidance) with built-in defaults (a report before `test`, `progress` before `done`), a global
+  `[rules]` table in `config.toml` and per-project overrides in the new `project_rules` table
+  (migration `0006`); a config error stops the start, a broken project override is logged and
+  ignored (global rules apply, "project override ignored: …" is shown). Read through the tool `rules_get(project?)` and the
+  resources `relaybay://rules` and `relaybay://rules/{project}`; `project_snapshot` starts with
+  the rules hash. Stage moves that miss a rule succeed with a `Warning (rules)` line in the MCP
+  response, the board form and the event's `warnings` (`rules_mode = "warn"`, default), or are
+  refused (`rules_mode = "strict"`).
+- `relaybay serve` (FastAPI + uvicorn, default `127.0.0.1:8765`) and `relaybay token [--rotate]`;
+  `python -m relaybay`; settings from `config.toml`, `RELAYBAY_*` environment variables and flags.
+- SQLite storage (WAL, numbered migrations) for projects, tasks, reports, decisions, sessions and an
+  append-only event log; every write goes through one service layer and publishes an event.
+- Token security: Bearer token on `/mcp` (and the reserved `/api` prefix), cookie login for the
+  board via `/login`, Host allow-list, Origin checks, CSRF protection for board edits,
+  `Content-Security-Policy`.
+- MCP server (Streamable HTTP at `/mcp`) with the tools `project_list`, `project_upsert`,
+  `project_snapshot`, `task_list`, `task_get`, `task_create`, `task_update`, `task_set_stage`,
+  `task_bind_session`, `report_add`, `decision_add`, `events_since` and the resource
+  `relaybay://project/{slug}`.
+- Board: projects list with per-stage counts, stage columns with cards, card editing, live updates
+  over Server-Sent Events with `Last-Event-ID` replay, a stage tab bar on narrow screens, light and
+  dark themes. htmx and its SSE extension are vendored.
+- Configurable display labels for stages (`[stages.labels]`).
+- Sign-in page: unauthenticated browser visits redirect to `/login`, which accepts the access
+  token in a form (CSRF-protected) and returns to the requested page.
+- `relaybay serve` and `relaybay token` print their data folder; `/healthz` reports a public token
+  fingerprint (`token_id`) and `relaybay token` warns when the running server uses a different
+  token.
+- Report state and size badges on cards and the task page (state coloured by meaning, size S/M/L,
+  both with tooltips); labels and tooltips configurable via `[reports.labels]` / `[reports.hints]`.
+- Claude desktop app session links: write tools accept a desktop session id (`local_<uuid>`) and a
+  `session_title`; cards and the new task page (`/t/{key}`) show "Open in desktop" and a copy-link
+  button; the link template is configurable (`desktop_link_template`).
+- Session binding history per task (`task_session`), shown on the task page and in `task_get`;
+  binding a session emits `task.session_bound`.
+- Task `description` and `progress` (markdown, migration `0002` upgrades existing databases in
+  place): `task_create` and `task_update` accept both, `report_add` takes an optional `progress`
+  saved in the same transaction, `task_get` shows them in full and `project_snapshot` shortened.
+- `task_unbind_session` MCP tool and an "Unbind session" button (with confirmation) on the board:
+  closes the binding, keeps the history and emits `task.session_unbound`; an optional `session`
+  refuses to unbind a session that took over meanwhile.
+- Session aliases (migration `0003`): `task_bind_session` with a plain name on a task bound to a
+  desktop session keeps the desktop binding and records the name as that session's alias (event
+  `session.alias_added`); the name then resolves to the desktop session in writes, `task_list` and
+  `task_unbind_session`. Aliases are global; no alias is made for a name a plain session already
+  has (the call warns and changes nothing).
+- Done column window and archive: the board's `done` column shows tasks closed within
+  `done_window_days` (default 7, `RELAYBAY_DONE_WINDOW_DAYS`); older ones are archived and shown
+  with "Show archived" (`?archived=1`). A search box filters cards by key or title (`?q=`) and also
+  searches the archive.
+- External tracker mark (migration `0003`): task fields `tracker_ref`, `tracker_name`,
+  `tracker_url` (http/https only) and `tracker_logged`, accepted by `task_create` / `task_update`,
+  shown by `task_get` and `project_snapshot`, edited in the task dialog. Cards show the issue as a
+  badge (a link with a URL, ✓ when logged). Opt-in `require_tracker_log`
+  (`RELAYBAY_REQUIRE_TRACKER_LOG`, default false): done tasks without the mark show "not logged" and
+  are never archived.
+- Next step freshness (migration `0004`, upgrades existing databases in place): `task_set_stage`
+  and `report_add` accept `next_step` and `waiting_on`, saved in the same transaction (`"-"`
+  clears them), and their descriptions ask sessions to keep both current. A next step set before
+  the task's last stage change shows muted with a "stale" marker on the card and in the task
+  dialog, and with `(stale)` in `task_get` / `project_snapshot`; writing it again over MCP (or editing it on the board) confirms it.
+- Tracker history (migration `0005`, upgrades existing databases in place and backfills one entry
+  per task with an issue key): a new `tracker_ref` appends an entry and earlier ones stay; marking
+  the work log entered or not stamps `logged_at` / `unlogged_at` on the current entry. The task
+  dialog and `/t/<key>` show a "Tracker history" block and `task_get` a "Tracker history" section;
+  the card badge and `project_snapshot` keep showing only the current issue.
+- Automatic unlog: when a logged task gets new work (a report, a changed `progress`, or a stage
+  move back out of `live` or `done` to an earlier stage), `tracker_logged` is cleared in the same
+  transaction with a `task.tracker_unlogged` event carrying the reason. Metadata edits (title,
+  branch, waiting on, next step, tracker fields) keep the mark; an explicit `tracker_logged` in
+  the same write wins. A new `tracker_ref` starts as not logged unless `tracker_logged` is passed
+  in the same write.
+- `task_patch` MCP tool: changes any editable task fields given as one JSON object (`fields`),
+  with the same validation, clearing, stage-move and auto-unlog rules as `task_update` /
+  `task_set_stage` and optional `expected_version`; unknown names fail with the allowed list. The
+  editable fields come from one list that also drives write validation, the new resource
+  `relaybay://schema/task` and an "Editable fields: …" line at the end of `task_get`, so clients
+  that cached an older `task_update` schema can still set new fields. README and
+  `docs/mcp-tools.md` explain schema caching in long-running sessions.
+- A test that keeps the repository English-only (no Cyrillic in `src/`, `docs/`, `tests/` and the
+  root markdown files).
+- `"-"` clears a text field in `task_update` (and leaves it empty in `task_create`, clears
+  `progress` in `report_add`), since models cannot always send an empty string.
+
+### Changed
+
+- Documentation restructured: `docs/SPEC.md` (shipped behaviour with stable `#spec-…` anchors),
+  `docs/ROADMAP.md` (versions 0.1.0 to 1.0 with status), `docs/architecture.md`, one design per
+  upcoming step in `docs/design/`, configuration and CLI reference pages, `docs/llms.txt`; the
+  former `docs/PLAN.md` is now a pointer to them. A MkDocs Material site (`mkdocs.yml`, optional
+  `docs` dependency group) is built with `mkdocs build --strict` on pull requests and deployed to
+  GitHub Pages from `main`.
+- Docs and tests use English examples for custom stage and report labels; labels in any language
+  remain configurable, the defaults are English.
+
+- Cards show only essentials: key, tracker badge (including "not logged") and an icon-only "open
+  in desktop" link in the top row, then title, "waiting on", branch and the next step (two lines).
+  Description, progress, the last report with its badges, the session name, "no session" and
+  "Copy link" moved off the card; the task dialog and `/t/<key>` still show all of them.
+- Done cards no longer show "waiting on" and the next step; the task dialog shows them muted.
+- The done column is no longer cut at 20 cards; it holds the window and is capped at 200 with a
+  note.
+- Clicking a card opens the task in a dialog over the live board instead of an inline editor: the
+  full task (description, progress, reports, session history, desktop link, unbind) and its edit
+  form. The dialog has its own URL (`/p/<project>?task=<key>`), closes with Back, Esc or a click
+  outside, and is full screen on narrow screens. The task page `/t/<key>` shows the same details.
+
+### Fixed
+
+- Clearing a field in the board's edit form (an empty input) now clears it; it used to keep the old
+  value.
+- A long session title no longer widens a card past its column: the session badge shrinks with an
+  ellipsis and shows the full title on hover.
+
+[Unreleased]: https://github.com/Codenator81/relaybay/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/Codenator81/relaybay/releases/tag/v0.1.0

relaybay-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Aleksandrs Poltarjonoks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

relaybay-0.1.0/PKG-INFO

@@ -0,0 +1,237 @@
+Metadata-Version: 2.5
+Name: relaybay
+Version: 0.1.0
+Summary: A live board and MCP server for coordinating many Claude Code sessions across projects.
+Project-URL: Homepage, https://github.com/Codenator81/relaybay
+Project-URL: Documentation, https://codenator81.github.io/relaybay/
+Project-URL: Changelog, https://github.com/Codenator81/relaybay/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/Codenator81/relaybay/issues
+Author: Aleksandrs Poltarjonoks
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Web Environment
+Classifier: Framework :: FastAPI
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development
+Requires-Python: >=3.12
+Requires-Dist: aiosqlite>=0.20
+Requires-Dist: fastapi>=0.115
+Requires-Dist: jinja2>=3.1
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: mcp<3,>=2
+Requires-Dist: platformdirs>=4.2
+Requires-Dist: python-multipart>=0.0.9
+Requires-Dist: uvicorn>=0.30
+Description-Content-Type: text/markdown
+
+# relaybay
+
+[![CI](https://github.com/Codenator81/relaybay/actions/workflows/ci.yml/badge.svg)](https://github.com/Codenator81/relaybay/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/relaybay)](https://pypi.org/project/relaybay/)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![Docs](https://github.com/Codenator81/relaybay/actions/workflows/docs.yml/badge.svg)](https://codenator81.github.io/relaybay/)
+
+A live board and MCP server for people who run many Claude Code sessions across many repositories.
+Sessions report their work through MCP tools; you watch **projects → tasks → stages → reports** update
+in the browser, on the desktop or on your phone.
+
+> **Status: early (0.1).** relaybay is built for my own workflow first and changes quickly. Expect
+> rough edges; issues and ideas are welcome.
+
+![The relaybay board updating live while sessions report their work](https://raw.githubusercontent.com/Codenator81/relaybay/main/docs/assets/board.gif)
+
+## Quick start
+
+```bash
+uv tool install relaybay      # or: pipx install relaybay  ·  or run it once: uvx relaybay
+relaybay serve                # prints the board's login link and the MCP URL
+relaybay setup                # shows how it connects Claude Code (then --apply --expect <hash>)
+```
+
+Open the login link once; the browser keeps a cookie. `relaybay token` prints the token again with
+the `claude mcp add …` command for Claude Code. Docker, Windows/macOS/Linux details and a procedure
+your coding agent can follow for you:
+[Install](https://codenator81.github.io/relaybay/getting-started/install/) ·
+[Install with your coding agent](https://codenator81.github.io/relaybay/getting-started/agent-install/).
+Something off? `relaybay doctor`.
+
+**Documentation:** [codenator81.github.io/relaybay](https://codenator81.github.io/relaybay/) ·
+[Specification](docs/SPEC.md) (how it behaves now) · [Roadmap](docs/ROADMAP.md) ·
+[Architecture](docs/architecture.md)
+
+## Features
+
+- **Board** — projects with per-stage counts; per project, columns `plan → dev → test → live → done`
+  with cards showing only the essentials: key, tracker badge, an "open in desktop" icon when a
+  desktop session works on the task, title, waiting-on person, branch and the next step. Click a
+  card to open the task in a dialog over the live board (its own URL,
+  `/p/<project>?task=<key>`, full screen on a phone): description and progress in full, reports,
+  session history, "Open in desktop", unbinding the session and editing the task. Each task also has
+  a page of its own (`/t/<key>`). Live updates over Server-Sent Events, catch-up after sleep or a
+  dropped connection, a stage tab bar on narrow screens.
+- **Next step that keeps up** — sessions pass the next step and who acts next together with a
+  stage change or a report; a next step left over from before the last stage change shows muted
+  and marked "stale".
+- **Done column and archive** — the `done` column shows tasks closed in the last
+  `done_window_days` (default 7); older ones are archived and come back with "Show archived" or a
+  search by key or title (`/p/<project>?archived=1`, `?q=…`). Done cards hide "waiting on" and the
+  next step.
+- **External tracker mark** — a task can carry its issue in any tracker (tracker name, issue key,
+  optional link) and a "work log entered" mark. The card shows the issue as a badge at the top (a
+  link when a URL is set, ✓ once logged). With `require_tracker_log = true` a done task without
+  the mark shows "not logged" and stays out of the archive until it is marked. Every issue key a
+  task has had is kept in its tracker history (task dialog, `/t/<key>`, `task_get`), and new work
+  on a logged task (a report, a progress change, a move back from `live` or `done`) clears the
+  mark again, so it always means "the log covers everything done".
+- **MCP server** — Streamable HTTP at `/mcp` in the same process: create and update tasks, change
+  stages, keep a task's description and progress summary current, add reports and decisions, bind
+  and unbind sessions, get a markdown snapshot of a project. A plain session name never replaces a
+  task's desktop session binding: it becomes that session's alias. `task_patch` takes any task
+  fields as one JSON object, so clients with an older tool schema can still set new fields.
+- **Working rules** — the server tells every connected session how to work with the board (MCP
+  instructions: read the snapshot, pick a task, keep next step / waiting on / progress current,
+  report as `state · size · gist`) and serves the rules as data: report format, what a stage move
+  needs (by default a report before `test`, `progress` before `done`), a description template and
+  free-text guidance. Global rules come from `config.toml`, a project can override them; agents read
+  them through `rules_get` or `relaybay://rules/<project>`, and `project_snapshot` starts with the
+  rules hash. A stage move that misses a rule succeeds with a warning (or is refused with
+  `rules_mode = "strict"`), in MCP responses and on the board.
+- **Local and private** — one process, SQLite, binds to `127.0.0.1`, token-protected, no telemetry,
+  no outbound calls, no CDN.
+
+## Try it with demo data
+
+```bash
+relaybay demo --home ./relaybay-demo                 # acme-shop and demo-api, tasks in every stage
+relaybay serve --home ./relaybay-demo --port 8766
+```
+
+## Connect Claude Code
+
+```bash
+claude mcp add --transport http --scope user relaybay http://127.0.0.1:8765/mcp \
+  --header "Authorization: Bearer <token>"
+```
+
+`user` scope adds relaybay once for all repositories. See
+[docs/connect-claude-code.md](docs/connect-claude-code.md) for `.mcp.json` and a short instruction
+snippet for your project's `CLAUDE.md` / `AGENTS.md` that tells the agent when to call the tools.
+
+### Live session status (hooks)
+
+```bash
+relaybay setup                         # what it found, the exact diff and its hash
+relaybay setup --apply --expect <hash> # adds relaybay's hooks to ~/.claude/settings.json
+relaybay setup --check                 # end-to-end check, one ok/FAIL line per item
+```
+
+The hooks let the board show whether each session is working, waiting for you, idle or gone, and
+unbind a session from its task when it ends. Setup adds only its own entries (other hooks stay as
+they are), never writes the token into the file, and `--remove` takes them out again. The same plan
+and buttons are on the board under **Integrations**. Hooks stay silent when relaybay is not
+running. Details: [docs/connect-claude-code.md](docs/connect-claude-code.md#3-live-session-status-hooks).
+
+### Schema changes and long-running sessions
+
+A Claude Code session keeps the parameter schema of a tool it already loaded, even after relaybay
+restarts and the client reconnects: new tools appear, but new parameters of an existing tool do
+not. Use `task_patch(task, fields={...})` for fields your client does not know yet (the allowed
+names are at the end of `task_get` and in `relaybay://schema/task`), or refresh the schemas by
+reconnecting the server in the client (`/mcp` in the CLI) or starting a new session. See
+[docs/mcp-tools.md](docs/mcp-tools.md#schema-changes-and-long-running-sessions).
+The tool reference is in [docs/mcp-tools.md](docs/mcp-tools.md).
+
+## Configuration
+
+Settings come from defaults, then `config.toml` in the data directory, then `RELAYBAY_*` environment
+variables, then command-line flags.
+
+| Setting | Default | Env | Flag |
+|---|---|---|---|
+| data directory | per-user data dir (`platformdirs`) | `RELAYBAY_HOME` | `--home` |
+| bind address | `127.0.0.1` | `RELAYBAY_HOST` | `--host` |
+| port | `8765` | `RELAYBAY_PORT` | `--port` |
+| extra allowed Host names | none | `RELAYBAY_ALLOWED_HOSTS` (comma-separated) | — |
+| desktop session link | `claude://claude.ai/epitaxy/{id}` | `RELAYBAY_DESKTOP_LINK_TEMPLATE` | — |
+| days a done task stays in the done column | `7` | `RELAYBAY_DONE_WINDOW_DAYS` | — |
+| keep done tasks without the tracker work log on the board | `false` | `RELAYBAY_REQUIRE_TRACKER_LOG` | — |
+| what a stage move that misses a rule does: `warn` or `strict` | `warn` | `RELAYBAY_RULES_MODE` | — |
+| folder with Claude Code's `.claude/` and `.claude.json` (setup, Integrations) | your home directory | `RELAYBAY_CLAUDE_HOME` | `--claude-home` |
+
+The data directory holds `relaybay.sqlite`, the `token` file and the optional `config.toml`:
+
+```toml
+port = 8765
+allowed_hosts = ["my-laptop.lan"]   # needed only when you bind to a LAN address
+desktop_link_template = "claude://claude.ai/epitaxy/{id}"  # {id} = desktop session id (local_…)
+done_window_days = 7                # older done tasks are archived
+require_tracker_log = false         # true: done tasks without the tracker work log stay and show "not logged"
+rules_mode = "warn"                 # "strict": a stage move that misses a rule is refused
+
+[stages.labels]                     # display names; the stage keys stay plan/dev/test/live/done
+dev = "in progress"
+done = "shipped"
+
+[reports.labels]                    # report badges: inspected/changed/verified/committed/pushed/blocked, S/M/L
+verified = "checked"
+
+[reports.hints]                     # badge tooltips
+M = "medium change"
+
+[rules]                             # global working rules, merged over the built-in defaults
+guidance = "Ask the owner before anything goes live."
+description_template = "Goal:\nWhy:\nDone when:"
+
+[rules.report_format]               # states/sizes: a subset of the built-in ones
+sizes = ["S", "M", "L"]
+
+[rules.stage_requirements]          # per target stage; a list replaces the default, [] drops it
+test = [{ kind = "report_since_stage_change" }]
+done = [{ kind = "field_present", field = "progress" }]
+```
+
+A rules error in `config.toml` (unknown key, stage, rule kind or field) stops `relaybay serve`
+with a message that names the key. A broken project override never stops the server: it is
+logged, the project falls back to the global rules, and `rules_get` and `project_snapshot` say
+"project override ignored: <error>". Project overrides and the merge rules are described in
+[docs/mcp-tools.md](docs/mcp-tools.md#working-rules).
+
+`relaybay token --rotate` creates a new token; restart the server and update the Claude Code entry.
+
+### Troubleshooting: "token not valid"
+
+Each data folder has its own token. `relaybay serve` prints the folder it uses (`Data folder: …`);
+run `relaybay token` with the same `--home` (or `RELAYBAY_HOME`). `relaybay token` prints its folder
+and warns when the server on the port uses a different token (another folder, or a rotation without
+a restart). After `relaybay token --rotate`, restart the server. `relaybay doctor` checks this and
+everything else in one command ([troubleshooting](https://codenator81.github.io/relaybay/how-to/troubleshooting/)).
+
+## Roadmap
+
+- **0.1.0** — board, MCP tools, working rules, hooks and `relaybay setup`, packaging
+  (`uv tool install`, `uvx`, `pipx`, Docker), `relaybay doctor`, docs site, demo workspace.
+- **0.2.0** — sidebar navigation and Inbox, comments to agents, project environments and access.
+- **0.3.0** — review checklist with screenshots, memory and documents.
+- **Later** — annotations, map and usage, rules versioning, intake, agents started from relaybay.
+
+Details and status: [docs/ROADMAP.md](docs/ROADMAP.md). Designs of upcoming steps are in
+[docs/design/](docs/design/index.md), decisions in [docs/adr/](docs/adr/). relaybay sends no
+telemetry.
+
+## Contributing and feedback
+
+- Questions, ideas, show and tell: [Discussions](https://github.com/Codenator81/relaybay/discussions).
+- Bugs and feature requests: [issues](https://github.com/Codenator81/relaybay/issues/new/choose)
+  (include `relaybay doctor` output for bugs).
+- Security problems: report privately, see [SECURITY.md](SECURITY.md).
+- Code: [CONTRIBUTING.md](CONTRIBUTING.md); AI coding tools: [AGENTS.md](AGENTS.md). Everyone
+  follows the [Code of Conduct](CODE_OF_CONDUCT.md); how decisions are made:
+  [GOVERNANCE.md](GOVERNANCE.md).
+
+## License
+
+[MIT](LICENSE)