tinybeeai 0.0.0-stage → 0.16.1

package/docs/TRACE-MAP.md

@@ -0,0 +1,89 @@
+# Traceability map (KAT-189)
+
+The Traceability page gets three views of the same data: Table (today), Map, and Heatmap. The Map is a collapsible tree of the product, like the True Platform IA map. Every node carries its requirements, tests, defects, latest screenshot, and an agent skill. Every node and heatmap cell drills down.
+
+## Data: the observed app under test
+
+The map shows the app as the dot's test runs saw it, the way a tester walks it. It is not derived from the repo. Three sources, in order:
+
+1. **Observed pages (source of truth).** Every page or state a Playwright test or an AI-Vision case visited: URL, page title, main headings and landmarks from the accessibility snapshot, the real screenshot, the actions taken there (click, fill, assert, AI-Vision step text), the test that did it, and its result. URLs are normalized to route patterns (`/runs/0mv0dp...` becomes `/runs/:id`; query strings dropped; hash routes kept as paths).
+2. **Requirements.** A ticket sits on a page only on evidence: a test linked to it visited the page, its text names the route, or a file one of its PRs changed is the page's source or lies in the page's product area (repo profile). A run on the ticket's PR that visited the page is not evidence, since a full suite visits every page. A ticket with no evidence sits in Requirements without a page only. That section sits under the app of the dot the ticket belongs to (the dot that reviewed or linked it); in All dots each app has its own, and a ticket of two dots appears under both apps once each. A page's status comes from its own tests and requirements.
+3. **Repo code.** The repo scan maps a route pattern to its source files and API routes, shown in the drawer. Its page routes, and the routes its specs open, also make coverage gap nodes when no run visited them (see Coverage gaps on the map). API routes never make a node.
+
+Pages that the code, a requirement, or a probe names but no run has visited show as **Needs tests** or **Not run yet** nodes: that is the coverage gap.
+
+### Capture
+
+Every run that runs tests writes `observations.jsonl` among its artifacts (`src/runner/observe.ts`), one line per page or state change:
+
+`{ at, attempt, source, test, title, project?, url, route, host, from?, pageTitle?, headings[], landmarks[], dialog?, action?, steps?, requests?, screenshot?, result?, error? }`
+
+- **Playwright:** the runner passes `--trace=on`, so the repo's own specs need no edits. After each attempt it reads every test's `trace.zip`: the main-frame DOM snapshots give the URL, page title, headings, landmarks, and an open dialog; the "navigated to" logs and step titles give the step that led to the page (`action`) and the steps taken there (with the error of a failed one); the network log gives the requests the page made; the last screencast frame of the first visit is the screenshot. Traces of tests that passed are deleted once read, so a run keeps the traces it kept before (tests that did not pass).
+- **AI-Vision:** each case step maps to the same line shape: the step's URL when the server sends one, else the case's start URL, the step text, its error, and its screenshot. The CLI backends report no steps, so each case is one line at its start URL.
+- One screenshot per route per test, stored as a run artifact (`a1-obs-<test>-<route>.jpeg`). URLs are stored without their query string.
+
+### Tree
+
+App (from the base URL host; local servers a test run starts on a random loopback port that no dot names are one app, Local test servers) > section (the product area of the repo profile that lists the route, else the first path segment, named from the most common heading on those pages; a section with one page is that page, so the map does not say the same thing twice) > page (route pattern) > state (a distinct heading set or dialog on the same route, when tests open one). Each node: status, counts (requirements, tests passed of total, open bugs), the latest real screenshot, the tests and their last result, requirements, defects, dot presence, and the agent skill.
+
+The agent skill for a page is written from observations: how to reach it (the URL and the clicks tests used), what is on it (headings, landmarks), which tests cover it, open bugs, and gotchas from failed steps.
+
+## API
+
+- `GET /api/dots/:id/trace/map` returns `{ tree: TraceMapNode, stats, milestones, observed }`. `TraceMapNode = { id, kind: 'root'|'app'|'section'|'page'|'state', name, route?, pageTitle?, status, counts: { requirements, tests: {passed, failed, total}, defects: {open, total} }, screenshot?: url, dots?, children: TraceMapNode[] }`. The status is one of `covered`, `partly`, `failing`, `needs_tests`, `not_run`; `counts.gaps: { needsTests, notRun }` counts the pages at or below the node with each gap. A map with one app has the app as its root; several apps sit under a `root` node. Stats count nodes by status. `observed` is false until a run records a page.
+- `GET /api/dots/:id/trace/map/:nodeId` returns the drill-down: the node with the URLs, headings, and landmarks runs saw, requirement rows (same shape as `TraceRow`), tests with title, last result and run link, defects with links, screenshots (one per test per route, the latest, with the test's `result`; up to 12, newest first), `gaps` (the pages at or below the node that need tests or a run, with the specs that cover them), `code: { files, api }` from the repo scan, and the skill markdown.
+- `POST /api/dots/:id/trace/map/:nodeId/run` queues a `rerun` job with the spec files that cover the node (Run tests); 409 when no test covers it. `POST /api/trace/map/:nodeId/run` uses the node's first dot.
+- Requirement rows with no title (a key a PR names before a ticket review read it) get their title from the dot's tracker (Jira, Linear, or GitHub Issues), cached in `ticket_titles` for a day; a failed read is tried again after ten minutes, and the row keeps its fallback text until a read works (KAT-190).
+- `GET /api/dots/:id/trace/map/skill.md` returns the whole map as one agent skill: a router section (tree with status) and one section per page and state.
+
+## Agent skill per node
+
+Markdown an agent can follow without exploring the app first, written from observations: how to reach it (app base URL, route, the URLs runs saw, and the steps tests took from the page before), what is on it (page title, headings, landmarks, states, requests), the tests that cover it with their spec files and last results, open defects with repro lines, known gotchas from failed steps on the page and failed tests, the latest screenshot URL, its requirements, and the source files and API routes from the repo scan. Generated from data only, no model call. The chat tools (when the chat tools PR lands) can read it through the same endpoint.
+
+## Map view
+
+An IA map on a canvas, top down: a card on top, and when it is open its children sit in a panel below it, side by side, wrapping into rows. An open child is a block of its own, so the app reads across its areas with each area's pages in a grid under it. The wrap width comes from the viewport: the layout takes the widest zoom from 100% down to 60% at which the whole map fits, and Fit never goes below 60% just to show the full height (a taller map starts at the top and pans down).
+
+It opens at depth 2: the app and its areas (or the apps and their areas under an All dots root). A press on a card with children expands it in place and fits the view to it; a press on the open focus closes it again. A breadcrumb above the canvas goes back up a level, closing what was drilled into below it; the top crumb opens the map at depth 2 again. A leaf card, or the Details button on any card, opens the side drawer. Expand all, Collapse all and Depth 1/2/3 stay. A search or status filter cuts the tree down to the matches and opens the path to each.
+
+The canvas draws at most 300 cards: an open node shows its first 24 children, breadth first, and a '+N more' box stands for the rest; a press on it shows 100 more. The breadcrumb row says how many nodes are shown of the total.
+
+Each card has a fixed 72 by 45 thumbnail area on the left (object-fit cover, rounded). The box shows a small page icon until the screenshot has loaded and decoded, then the image fades in, so nothing moves. With no screenshot, or a file that does not load, the box keeps the page icon and no outline or fill; the app logs a file that does not load once. The map payload names only screenshot files still on disk: a file the artifact cap deleted is left out, the node takes its newest screenshot still on disk, and the server logs the first missing file once and three lines to its right: kind and name, the status icon and word, and three counters (requirements, tests passed of total, open bugs) in monospace tabular numbers, then the dots that visited it. Nodes are sized so nothing clips or wraps from 60% to 150% zoom; a long name ends in an ellipsis. List shows the same nodes as an outline list (also the screen-reader friendly reading).
+
+Status icons: each state has its own shape and color (a check in a circle for Covered, a half-filled circle for Partly covered, an octagon with a cross for Failing, a dashed circle with a plus for Needs tests, a rounded square with a play mark for Not run yet). Where an element is short of room it shows the icon alone and keeps the word for screen readers; the element's own width decides (CSS container queries).
+
+## Heatmap view
+
+A treemap. The top level has a tile per area, grouped under a header per app when there are several. A tile's size is its tests (or requirements, by the Size toggle), with a floor so an area with no tests still has a tile; its fill and icon are its coverage status. Each tile shows the icon, the area name and a short count, and the status word where it has room. The coverage gaps (Needs tests, Not run yet) get a stronger fill, a dashed inner edge in the text color and a bigger floor, so they stand out. A press on a tile with pages drills into them as the next level, with a breadcrumb back up and a Details button for the level's drawer; a tile with nothing under it opens the drawer (a gap opens the tests filtered to it). A legend names the five states.
+
+Table shows the same level as rows: Requirements, Tests, Passing, Failing, Not run, Open bugs, Needs tests, Not run yet. Cell shade scales with the value inside its column, using existing color tokens (bugs and failing use the danger scale, tests and passing use the success scale, requirements the neutral accent). Each cell shows the number. Clicking a cell opens the drawer on that node and tab, filtered to that column. A toggle switches columns to milestones, with cells showing open bugs per area per milestone.
+
+## Rules
+
+- Tokens only, light and dark both work. Visible labeled controls, no hidden overflow menus. Rows, not cards. Plain QA words.
+- Phone width works: below 640px the filters (Dot, status, search, depth, List) fold into one row with a Filters button that opens a sheet, so the view starts near the top. The phone gets the same canvas, with pan, pinch and the minimap; the Heatmap table scrolls sideways inside its own box.
+- No colored borders or stripes on list items or cards; selection reads from the background.
+- Tests: unit tests for the mapping rules and status roll-up, component tests for Map and Heatmap drill-down, one Playwright `@smoke` test that opens Map, clicks a node, and sees the drawer.
+- Controls never wrap their label: buttons, tabs, filter pills, status chips, and counters use `white-space: nowrap`. If a label cannot fit, drop the font one size step rather than wrap. Align by eye (optical alignment), not to the pixel.
+
+## Canvas and dot presence (KAT-211)
+
+The Map view is a canvas: drag to pan, wheel or pinch to zoom, buttons for zoom in, zoom out, and Fit, plus a small minimap in a corner. Node positions come from a left-to-right tree layout; a person can drag a node, and the position is kept per viewer in localStorage (wrapped in try/catch). One canvas can show every dot's repos: a "Dot" filter with "All dots" as the default gives the big picture.
+
+Each section, page, and state node shows the avatars of the dots whose runs visited it (or whose requirement, probe, or code it is, for a gap node). When a dot has a run in progress that has reached the page, or that is on a PR whose changed files hold the page's source files (from the repo scan), the node shows a live marker with the stage name (for example "Reviewing PR #34"). Clicking an avatar opens that dot; clicking a node opens the drawer as before. Data: add `dots: { id, name, avatar, running?: { runId, label } }[]` to `TraceMapNode`, and the map route accepts no dot id (`GET /api/trace/map`) for the all-dots canvas.
+
+Repo-derived areas (an earlier draft) are superseded by the observed tree above and removed.
+
+## Coverage gaps on the map (Huy, 2026-10-09)
+
+A page or path that the code or a requirement has always shows on the map, even when no run has visited it. Its indicator says what to do next, with a distinct dot and word (never color alone):
+
+| Indicator | Meaning | Next step |
+|---|---|---|
+| **Needs tests** | Known from code (routes) or a requirement, and no test covers it | Write a test |
+| **Not run yet** | A test covers it, but no run has executed that test, or not since the last change to the page's code | Run the tests |
+| Covered / Partly covered / Failing | Observed in runs, as before | As before |
+
+Gap nodes sit where their route pattern belongs in the tree, drawn with a dashed outline and no screenshot. The status filter and the heatmap get "Needs tests" and "Not run yet" columns, and clicking one lists those pages with a Write tests or Run tests action.
+
+How it is built: a test covers a page when a scanned spec opens its route, or when a requirement that names the route links the spec. A page's code changed when a merge (`post_merge` run) changed one of its source files after the latest observation of the page; a failing page stays Failing. A section with no visited page is Needs tests when any page in it needs tests, else Not run yet. The dots: a ring for Needs tests, a half-filled dot for Not run yet. Write tests opens the dot's chat with a draft that names the page and its skill; Run tests calls the run endpoint above. Requirements no route places sit in a "Requirements without a page" section, Not run yet when they link specs.

package/docs/TRACKERS.md

@@ -0,0 +1,225 @@
+# Jira, Linear, and GitHub Issues
+
+A dot with a tracker reviews each new ticket like a QA engineer in refinement. It scores the ticket from 0 to 100 for how ready it is. A ticket under 30 gets one line in the daily digest. Any other ticket gets a review: risks, open questions, gaps in the acceptance criteria, test ideas, and existing tests that the change may break, found by a code search in the watched repo. The dot then drafts a ticket comment. It also designs manual test cases from the review and stores them as drafts linked to the ticket, without repeating the cases it already has for that ticket. Mark each draft ready on the Test cases page.
+
+Ticket comments default to `ask`, so each draft waits in the Inbox until you approve, edit, or reject it. Change the rule for `ticket_comment` in the dot's Settings when you want the dot to comment on its own.
+
+Without credentials, a tracker runs in demo mode: the dot reviews tickets from webhook payloads and writes its comments to the outbox.
+
+| | Jira Cloud | Linear |
+|---|---|---|
+| Credentials | `JIRA_BASE_URL`, `JIRA_EMAIL`, `JIRA_API_TOKEN` | `LINEAR_API_KEY` |
+| Webhook | `/hooks/jira`, signed with `JIRA_WEBHOOK_SECRET` | `/hooks/linear`, signed with `LINEAR_WEBHOOK_SECRET` |
+| Polling | `LOCALDOST_POLL=1` or `pollJira: true` | `LOCALDOST_POLL=1` or `pollLinear: true` |
+| Triggers | Issue created; issue updated when the description or the acceptance criteria changed | Issue created |
+| Dot tracker field | `{ "kind": "jira", "baseUrl": "...", "projectKeys": ["SHOP"] }` | `{ "kind": "linear", "teamKeys": ["ENG"], "projectName": "Checkout" }` |
+| Loop guard | Signed marker from the dot's own account; `JIRA_BOT_ACCOUNT_ID` | Signed marker from the dot's own account; `LINEAR_BOT_USER_ID` |
+
+Connect either tracker from the Setup page: press **Connect** on its row, paste the credentials the flow asks for, press **Test**, then **Connect**, and pick the projects or team. The variables in the table are the environment route, and they win over values saved in the app.
+
+A ticket reaches a dot when its Jira project key or Linear team key is in the dot's tracker field. Webhook and poll events for the same ticket share one dedupe key, so a ticket is reviewed once. A ticket edited while its review still waits in the queue (it has not started, or the dot is at its daily model cap) keeps one review: the newer edit replaces the queued job of the same ticket for the same dot, so the review reads the newest text and posts one draft. A review that already runs is not stopped, and the edit queues a follow-up. A backfilled review never replaces a queued one. A late or repeated delivery for an older edit than the queued review (the ticket text carries the tracker's update time) starts nothing and stops nothing, so the review reads the newest text. A review a person asked to run again keeps its `rerunOf` link when a later edit replaces it, and **Rerun** on a review of a ticket whose review still waits replaces the queued one the same way, so the queue never holds two reviews of one ticket for one dot (KAT-408).
+
+## Jira
+
+1. Create an API token in your Atlassian account settings (the flow links there). In Setup, press **Connect** on the Jira row and enter the site, for example `acme.atlassian.net`, your Atlassian email, and the token. Press **Test**, then **Connect**, and pick the projects. With environment variables instead, set `JIRA_EMAIL`, `JIRA_API_TOKEN`, and `JIRA_BASE_URL`. `localdost init --tracker jira --jira-url <url> --jira-project SHOP` writes the references for you.
+2. As a Jira admin, open Settings, System, WebHooks, and create a webhook:
+   - URL: `https://<your-host>/hooks/jira`
+   - Events: Issue created. Add Issue updated to re-review a ticket when its description changes.
+   - JQL filter, optional: `project = SHOP`
+   - Secret: a random string, copied to `JIRA_WEBHOOK_SECRET`. With it unset, `/hooks/jira` answers 503 and queues nothing. Jira then signs each delivery with `X-Hub-Signature: sha256=<hex>`.
+3. Set the dot's tracker to `{ "kind": "jira", "baseUrl": "https://acme.atlassian.net", "projectKeys": ["SHOP"] }`.
+
+localdost reads issues through REST API v3 and posts comments as Atlassian Document Format. When your acceptance criteria live in a custom field, set `JIRA_AC_FIELD` to its id, for example `customfield_10042`. Otherwise the dot reads them from the description.
+
+### Jira polling
+
+With no URL that Jira Cloud can reach, use polling instead of the webhook. With `LOCALDOST_POLL=1` or `pollJira: true` on the dot, the poller searches Jira every `POLL_JIRA_SEC` seconds (default 60) through the connected Jira account with `project in (<the dot's keys>) AND updated >= <cursor>`. It queues a ticket review for each issue created since the last poll, and for each issue whose description or acceptance criteria field changed since then. The first poll after boot records a cursor and queues nothing. The open tickets that were there before a new dot started are reviewed by a separate backfill, see [Open tickets from before the dot started](#open-tickets-from-before-the-dot-started). After a gap of over an hour (the server was down, or a laptop host slept) the poll searches from the old cursor, the 1000 most recently updated tickets first, and queues the tickets created or edited since, newest first, at most 5 per dot (KAT-363). Each of those events carries `catchUp: { since, gapMs, source: "Jira" }`, and its run starts with a "Caught up after a gap" step.
+
+Polling uses the webhook's dedupe key for a new issue (`jira:<key>:created`), so a webhook and polling can run together. An edit is keyed by the time of the edit. Polling skips edits by the bot account (`JIRA_BOT_ACCOUNT_ID`, else the account that owns the token), and it skips an issue whose newest comment came from the bot account after the change (`JIRA_BOT_ACCOUNT_ID`, else the account that owns the token), because the dot has already answered it.
+
+A poll reads up to 1000 issues, oldest first, in pages of 100. The search is rounded to the minute, so a larger burst (or many issues with the same timestamp) can fill a window. The cursor then stays at the window start and remembers the issues it has handled by key and update time. The next poll reads deeper (up to 3000 issues), skips those, and queues the rest, so every ticket gets one review. Beyond 3000 changes in one window, the poll logs a warning and moves on.
+
+A webhook still reacts in seconds; polling reacts within a minute. Use a tunnel from [DEPLOY.md](DEPLOY.md) when you want the webhook and the server runs on your machine.
+
+To stop the dot from reviewing events its own account caused, set `JIRA_BOT_ACCOUNT_ID` to the account id of the user that owns `JIRA_API_TOKEN`. That skips everything the account does. Without it, the dot skips only the issues and comments it wrote itself (see [Loop guard](#loop-guard)), so a person who owns the token still gets their tickets reviewed.
+
+## Linear
+
+1. Create a personal API key in Linear: Settings, Security and access, New API key. The Linear flow in Setup links there. Paste the key, press **Test**, then **Connect**, and pick the team and project. With environment variables instead, export it as `LINEAR_API_KEY`. `localdost init --tracker linear --linear-team ENG` writes the reference.
+2. Pick webhooks or polling.
+3. Set the dot's tracker to `{ "kind": "linear", "teamKeys": ["ENG"] }`. Add `"projectName": "Checkout"` to narrow polling to one project. The same project is where the dot files its defects, see [Defects the dot files](#defects-the-dot-files).
+
+### Webhooks
+
+Create a webhook in Linear Settings, API, Webhooks:
+
+- URL: `https://<your-host>/hooks/linear`
+- Resource types: Issues
+- Copy the signing secret to `LINEAR_WEBHOOK_SECRET`. With it unset, `/hooks/linear` answers 503 and queues nothing.
+
+localdost checks the `Linear-Signature` header and rejects a delivery whose `webhookTimestamp` is more than 60 seconds off the server clock. Only issue creates trigger a review.
+
+### Polling
+
+With `LOCALDOST_POLL=1` or `pollLinear: true`, the poller asks Linear every `POLL_LINEAR_SEC` seconds (default 60) for issues created in the dot's teams since the last poll. The first poll after boot records a cursor and queues nothing. The open tickets that were there before a new dot started are reviewed by a separate backfill, see [Open tickets from before the dot started](#open-tickets-from-before-the-dot-started). After a restart of under an hour, polling catches up from the stored cursor. After a longer gap (KAT-363) the poll reads the issues created since the old cursor, up to 250 of them, and queues the newest first, at most 5 per dot. Each of those events carries `catchUp: { since, gapMs, source: "Linear" }`, and its run starts with a "Caught up after a gap" step.
+
+Polling skips issues created by `LINEAR_BOT_USER_ID` and the issues the dot wrote itself (see [Loop guard](#loop-guard)); a person who owns the API key still gets their tickets reviewed. When more than 250 issues were created since the last poll, the poll reads 250 and the cursor stays behind the issues it did not read, so the next polls continue. `LINEAR_API_URL` changes the GraphQL endpoint that polling and `localdost doctor` use.
+
+A Linear webhook and Linear polling can run together for the same team. Both use the dedupe key `linear:<identifier>:created`, so each issue is reviewed once.
+
+## GitHub Issues
+
+A dot can use the issues of a GitHub repo as its tracker. It reviews the requirements (native issue types **Feature**, **Story** and **Task**, or the labels below when an issue has no type), tracks the defects (type **Bug**), and ignores any other type. Each requirement gets a review, links to its PRs, a test status, and a row in the traceability view.
+
+It needs the GitHub connection from [GITHUB.md](GITHUB.md) with the Issues permission (read and write), and the App subscribed to the Issues event. An App created with **Create GitHub App** in Setup has both. An App created before this change needs the permission and the event added in its GitHub settings, and each installation must accept the new permission.
+
+Set the dot's tracker to `{ "kind": "github" }`. The dot then reviews the issues of its own repo. `localdost init --tracker github --tracker-repos katalon-studio/product --require-labels pod:agentic --milestone 2026.11` writes the same fields. The other fields are optional:
+
+| Field | Default | Effect |
+|---|---|---|
+| `repos` | The dot's repo | Repos (`owner/name`) whose issues the dot reviews. When it names repos, the dot files its defects in the first one |
+| `issueTypes.requirement` | `Feature`, `Story`, `Task` | Issue types reviewed as requirements |
+| `issueTypes.defect` | `Bug` | Issue types reviewed as defects |
+| `labels.requirement` | `requirement`, `story`, `feature`, `enhancement` | Labels that mark a requirement on an issue with no type |
+| `labels.defect` | `bug`, `defect` | Labels that mark a defect on an issue with no type |
+| `labels.ignore` | none | Issues with one of these labels are never reviewed |
+| `labels.require` | none | Review only issues that carry at least one of these labels (any case), whatever their type. The first one also goes on every defect the dot files |
+| `milestones` | all | Only review issues in these milestones |
+| `statusLabels` | off | Draft a `qa: passing` or `qa: failing` label on a requirement issue when its test status changes (see Test status below) |
+
+An issue with an issue type is classed by the type alone, so a type that is neither a requirement nor a defect type is skipped. Issue types exist only in organizations; in a personal repo, or an org that does not use types, the labels decide. An issue with neither a matching type nor a matching label is skipped. Closed issues are skipped.
+
+`labels.require` is for a repo that several teams share. With `"labels": { "require": ["pod:agentic"] }` an issue is in scope only when it carries `pod:agentic`, and the type or label rules above then decide how it is reviewed. An issue with no type and a required label is a requirement, unless a defect label or the `localdost` label of the dot's own defects says it is a bug. An issue with no required label is out of scope, whatever its type. Adding the label to an issue later brings it in. The test status, the traceability view and the defect links read the same rule. Every issue the dot skips for its scope (a missing required label, a type, a milestone, a skip label) is written to the log with the reason, for example `Agentic pod: skipped issue katalon-studio/product#412: it has none of the required labels (pod:agentic); it has pod:other`. An issue in scope whose event starts no review, such as a label that is not one of the scope labels, is logged as `no new review for` that issue, with the reason. The setup flow's Tracker step saves the labels it asks for in this field and counts the issues with the same rule.
+
+A review starts when an issue in scope is opened, when its body or title is edited, when a label, type, or milestone brings it into scope, or when someone with write access comments `/localdost review` on it. The command reviews any issue that is not ignored, whatever its type or milestone; with `labels.require` it still needs one of the required labels, so a member of another pod cannot start a review of an issue that is not the dot's. An issue opened with a label is reviewed once, and an edit that repeats earlier text queues nothing.
+
+Acceptance criteria come from the first of: a section under an "Acceptance criteria" heading, the task list items (`- [ ]`), or the issue form sections whose label names criteria (for example `### Acceptance criteria` or `### Expected behavior`).
+
+The review also reads the newest 20 comments of the issue, the parent issue and the sub-issues. A comment from an owner, member or collaborator of the repo can answer a question the review would otherwise ask. A comment from anyone else is background and never answers. The code checks it against the list of comments the review read: a summary line that credits only writers with no role (by their @login, the link of their comment, or a quote of 6 words or more that the ticket text does not hold) is cut whatever its wording, and the review asks the question again and names the writer (KAT-401). A line that only restates the issue stays, even when a stranger's comment repeats the issue.
+
+The review comment carries the marker `<!-- localdost:ticket-review -->`, and a re-review edits that comment in place. Ticket comments keep the default rule `ask`, so each draft waits in the Inbox.
+
+The review also reads the issue timeline and records links: PRs and issues that mention it, sub-issues, and blocking issues. A PR check records the issues the PR closes, from closing keywords in the title and body (`Fixes #12`, `closes acme/shop#7`, an issue URL) and from the PR's linked issues in the Development sidebar, plus Jira and Linear keys in the title, branch, or body. `GET /api/links?ref=acme/shop%2312` lists the links of one issue or PR.
+
+Webhook and poll events share dedupe keys: `github-issue:<owner/name>#<n>:created` and `github-issue:<owner/name>#<n>:edited:<hash>`. With `LOCALDOST_POLL=1` or `pollGithub: true`, the poller reads issues updated in each tracker repo every `POLL_GITHUB_SEC` seconds. Polling does not act on `/localdost review` comments (see [Review again when someone answers](#review-again-when-someone-answers) for the comments it does read). After a gap of over an hour with no poll (a server that was down or asleep), the poll catches up instead of dropping the gap (KAT-363): it reads the 100 most recently updated issues since the old cursor, tells what changed from the issue state it recorded (an opened issue, an edit, an added label, type or milestone), and queues them newest first, at most 5 per dot after the tracker's scope (required labels, types, milestone), so another pod's issues do not use them up. Each run starts with a "Caught up after a gap" step. Issues and comments the dot wrote itself (see [Loop guard](#loop-guard)), issues opened by the localdost App, and edits by `GITHUB_BOT_LOGIN` are never reviewed.
+
+### Review again when someone answers
+
+The review of a ticket ends with questions for the person who filed it. When someone answers them in a comment, the dot reviews the ticket again and says which questions are answered now (KAT-393). It works for GitHub Issues trackers, through the poller and through the `issue_comment` webhook, with the same rules:
+
+- The dot reviewed the issue, and its last finished review left open questions. A ticket reviewed without questions, or never reviewed, is not looked at again.
+- The issue is open and still in the dot's scope (required labels, skip labels, milestones), the dot is not paused or archived, and its Ticket analyst stage is on.
+- A person wrote the comment. A bot, a comment the dot wrote (its signed marker, by its own account), an empty comment, and a bare `/localdost review` do not count. The same account without the marker counts, since a person may share it.
+- The comment is newer than the last review, which read every comment that existed when it started.
+- The writer is the author of the issue, or has write access to the repo (`GET /repos/{owner}/{repo}/collaborators/{login}/permission`, asked once per login and poll). A stranger's comment starts nothing, and the review never treats it as an answer.
+
+A comment that counts queues one `ticket_review` job that waits for a quiet window of 10 minutes. Every counting comment that arrives while it waits joins it and pushes it back by 10 minutes from the new comment, so a burst of comments is one review. Once the review has started, the next counting comment starts a new burst. A dot makes at most 3 of these reviews per issue per day, counted from the local midnight of the server; a comment over that limit is stored as an event with `skipped` and the reason, and starts nothing: nothing reads it again, and the reason says that a person with write access can comment `/localdost review` to ask for one. The job key is `github-issue:<owner/name>#<n>:answered:<comment id>:<dot id>:ticket_review`, so a comment read twice (the 30 second overlap of the poll, or a webhook and a poll) counts once.
+
+The poller keeps its own cursor for comments, `github-issue-comments:<owner/name>`. The first poll of a repo records it and reads nothing, and a repo where no dot has a reviewed ticket with open questions costs no request. One request reads the new comments of the whole repo (`GET /repos/{owner}/{repo}/issues/comments?sort=created&direction=asc&since=`, up to 300 per poll, the rest on the next poll).
+
+When GitHub fails while the dot judges a comment (the issue read or the write-access check answers 5xx, times out, or hits a rate limit), the comment is not judged, and it is not counted as an answer of "no". The poller keeps its comment cursor where it was, so the next poll reads the comment again, for up to 60 minutes after the cursor; after that the cursor moves on and the warning `could not be checked on GitHub` stays in the log. A delivery of the `issue_comment` webhook is sent once, so the server asks again by itself, after 30 seconds, 5 minutes and 20 minutes, and then gives up with a warning. A comment judged on an earlier try is absorbed by its job key, so a review is never queued twice. A 404 on the issue, or a write-access answer of "no", is an answer, and the comment is ignored.
+
+What the second review does. It reads the issue as it is then, and it trusts the issue author and the writers it checked, whatever their role in the repo (the first review calls a comment from an outsider background only). The model gets the questions of the last review, numbered, and says which ones the comments answer in `answeredQuestions` (`question`, `by`, `quote`). The code checks every entry: it must name one of those questions (word for word, or close enough that no other question fits better), and its writer must be the issue author, a writer the poll checked, or a team member among the commenters. An entry that fails is dropped, and its question stays open. A quote is cut to 15 words. The posted comment gains a section, **Answered since the last review**, before **Questions**, listing each answered question with who answered and the quote, and the line "2 questions from the last review are answered now."; the comment is edited in place like any re-review. The run says **Someone answered** and then **Questions answered** (or **No question answered yet**). A ticket too thin to review is reviewed anyway after an answer, and a ticket closed before the review starts gets a run that says so and makes no model call. `ticket.change.field` of the job is `answer`, and `answers` on the trigger holds the logins, the comment ids and the time of the last one.
+
+### Defects filed as issues
+
+A test that failed on every attempt (the first run and both retries) in a `pr_check` or `post_merge` run whose verdict is a product failure drafts one `issue_create` action. Flaky tests, test failures, and environment failures never draft one. The default rule for **Create issues** is **Ask**, so the draft waits in the Inbox. The same action files into Jira (`POST /rest/api/3/issue`, Markdown converted to ADF, type `Bug` unless the draft names another) and Linear (`issueCreate` on the team, labels matched by name), whichever tracker the dot has. A dot with no tracker files into its repo's issues.
+
+The draft carries the scenario as the title, the steps, expected and actual results, the error text with secrets masked, links to the run and, when the app has a public URL, to the trace and the failure screenshot, the suspected PR, and `Relates to #N` for each requirement the PR is linked to (Features, Stories and Tasks; a Bug is left out). Labels are the first `labels.defect` (default `bug`) plus `localdost`. The issue type is the first `issueTypes.defect` (default `Bug`); a repo that rejects the type gets the issue again with labels only. The milestone is the one of the first linked requirement that has one.
+
+Where the defect lands: when the tracker names `repos`, every defect is filed in the first of them, unless the bug was found in a repo the tracker names too, which keeps it. A team that tracks its bugs in one repo (for example `katalon-studio/product`) sets `repos` and its code repos stay free of defect issues. The body then names the repo and the PR it came from (`Found while testing PR katalon-studio/web#12.`, and `Relates to katalon-studio/web#12.` on a defect from a review, or `Likely cause: PR ...` on one from a failing test), so the PR timeline links back. The labels are the first `labels.defect`, `localdost`, and the first `labels.require`, so the team's board picks the defect up. A defect that carries a required label also carries the defect label and the issue type, both from the first of `labels.defect` and `issueTypes.defect`, so it is never read back as a requirement; a dot with no `labels.require` files as before. The Inbox card says `Files in katalon-studio/product.`, and the PR comment says `Defect: drafted for katalon-studio/product, waiting in the Inbox.` A tracker with no `repos` files each defect in the repo the bug was found in. The duplicate check below reads the issues of the repo the defect lands in.
+
+What a defect says (KAT-377): the title states what went wrong with both values (`Discount applied at checkout: $120.00 instead of $108.00`). The body opens with the impact and when it was found, then the severity and how often the test failed, the steps to reproduce, Expected and Actual, the evidence (screenshot, video, the check), the likely cause, the test case it belongs to, and what it relates to. The steps are the names the failing test gave its own `test.step` blocks, or the steps of the test case that automates it. When neither exists the steps say "Run the automated test in For developers." and the issue gets the label `needs-manual-steps`. The run command, the test file, the trace, the commit, the error text and the bug signature sit under For developers: a `<details>` fold on GitHub, an `expand` node on Jira (the Markdown fold becomes ADF), and a plain heading on Linear, which shows the tags as text, so the Linear body keeps the signature line in view. A hidden marker `<!-- localdost:defect sig=... -->` stays at the end for the duplicate check.
+
+The body ends with `<!-- localdost:defect sig=<hash> -->`, a hash of the test id and the first line of its error. Before a draft is made:
+
+- a pending draft with the same signature means no second draft;
+- an open issue that carries the marker (GitHub issue search, or an issue this dot filed earlier for Jira and Linear) turns the draft into a comment on that issue, "Seen again in run <link>", under the `ticket_comment` rule. Jira and Linear issues are not checked for being closed;
+- a draft the person rejected for the same bug on the same PR is not drafted again.
+
+GitHub search can lag a few minutes behind a new issue. The dot also remembers the issues it filed, so a repeat right after filing still finds the first issue.
+
+### Test status
+
+`GET /api/tickets/status?dotId=<id>` lists the test status of every issue or ticket a dot tracks, and `&ref=acme/shop%2312` answers for one. The status is computed on read from the links and the runs, and cached in the issue's row as `testStatus`:
+
+| Status | Rule |
+|---|---|
+| Not tested | No linked PR has a run, and no spec links to the issue |
+| Passing | The latest run of every linked PR passed, and every linked spec passed in its latest run |
+| Failing | A linked PR, spec, or What to test item failed in its latest run, or an open defect links to the issue |
+| Partly tested | Some What to test items of the linked PRs have not run, or a linked PR or spec has no result yet |
+| Out of date | A linked PR has a newer head than its latest result |
+
+A run that did not run its tests, or ended as an environment failure, gives no result. A defect is an issue localdost filed with `Relates to` the requirement, or an issue that mentions it and has a defect type or label. Whether a defect is still open comes from the issue poller or the `issues` webhook; until one of them reads the issue, a defect localdost just filed on GitHub counts as open, and a Jira or Linear defect is listed without counting.
+
+With `statusLabels: true` on the GitHub tracker, a requirement issue whose status turns Passing or Failing gets a draft that sets the label `qa: passing` or `qa: failing` (the other one is removed). The draft is a `ticket_comment` action, so the default rule `ask` puts it in the Inbox, and a newer status closes an older pending draft. Other statuses write no label, so an issue keeps its last label until it is Passing or Failing again.
+
+### Traceability view
+
+**Traceability** in the sidebar (under **More** on a phone) shows one table per dot, one row per requirement. It reads the same data for GitHub, Jira, and Linear:
+
+| Column | Shows |
+|---|---|
+| Issue | The issue or ticket key and title. Select it to open the detail drawer |
+| Type | The issue type (`Feature`, `Story`), or `Requirement` when a label made it one |
+| PRs | The PRs linked to it, each with its latest verdict on hover |
+| Tests | Tests passed out of tests linked: the What to test items of its PRs and the specs that name it |
+| Defects | Open defects linked to it |
+| Status | A dot and one of Not tested, Passing, Failing, Partly tested, Out of date, by the rules in Test status |
+
+A line above the table sums up the requirements in plain words, for example `14 of 18 requirements passing, 2 failing, 1 not tested, 1 out of date`. The filters **Milestone**, **Status**, and **Repo** narrow the table and the line, except that the Status filter leaves the line alone. The milestone and repo come from the issue; a Jira or Linear ticket has the milestone and repo it carried in its last review.
+
+The detail drawer shows the issue summary and acceptance criteria, the linked PRs with their last verdict, the linked tests with their latest result, the defects, and the QA review comment.
+
+A ticket appears once the dot has read it: GitHub issues through the poller or the `issues` webhook, Jira and Linear tickets through their first review. A Bug, an issue of another type, a Jira or Linear Task, and a ticket with no matching type or label never appear as rows. With `labels.require`, neither does an issue without a required label.
+
+**Export CSV** downloads the table with the filters you set. The file follows RFC 4180: fields with a comma, a quote, or a line break are quoted, and rows end in CRLF. A cell that starts with `=`, `+`, `-`, or `@` gets a leading single quote, so a spreadsheet shows it as text and never runs it as a formula.
+
+**Save as report** saves the readiness of the chosen milestone as a report page of kind **Readiness**. Saving it again updates the same page. The page holds the summary line, the table, and a short note on why each requirement that is not Passing is where it is.
+
+| Route | Returns |
+|---|---|
+| `GET /api/dots/:id/traceability?milestone=&status=&repo=` | Rows, the milestone and repo options, and the summary counts |
+| `GET /api/dots/:id/traceability.csv?milestone=&status=&repo=` | The same rows as CSV |
+| `GET /api/dots/:id/traceability/issue?ref=` | One requirement with its detail |
+| `GET /api/dots/:id/readiness?milestone=` | The summary line and counts for a milestone |
+| `POST /api/dots/:id/readiness/report` | Saves the readiness page, body `{ "milestone": "2026.11" }` |
+
+The **Release notes** page in Reports (KAT-391, `GET /api/v2/release-notes`) reads the same ticket data. It groups the release note of each merged PR by the milestone of the issue the PR names, and shows the issue's title and link, so an issue the dot has not read yet appears under No milestone with its key only. Unlike the traceability table, it lists a Bug or a Task a PR names too. The fields are in [API-V2.md](API-V2.md#release-notes-kat-391).
+
+## Open tickets from before the dot started
+
+A new dot reviews the open tickets that were there before it started (KAT-381), so its first day is not empty. On the first poll of a tracker, and on the next poll after a dot is made on a tracker that was polled already, the dot picks the open tickets in its scope: the most recently updated ones, at most `backfillLimit` of them in all, however many repos the tracker names. The tracker sets the limit, for example `{ "kind": "github", "repos": ["katalon-studio/product"], "labels": { "require": ["pod:agentic"] }, "backfillLimit": 40 }`. The default is 25, the most is 100, and 0 turns the backfill off. It works the same for GitHub Issues, Jira (open means a status category other than Done) and Linear (a state that is not completed or canceled).
+
+The reviews start one at a time, oldest update first. A dot starts the next one when the review before it is done and its daily model cap is not reached, so 25 tickets never fill the queue ahead of a PR check, and a dot at its cap holds no job for each of them. The list is stored in the poll cursor store under `ticket-backfill:<dot id>:<scope>`. That row is also the mark that the dot picked: a second poll and a restart pick nothing again, and a restart in the middle goes on with the tickets left.
+
+Each review is an ordinary new-ticket event marked `backfill`. It uses the dedupe key of a new ticket, so a ticket the dot reviewed when it was opened is not reviewed twice. Nobody asked for these reviews, so the comment (and a status label) waits in the Inbox for your approval when the ticket comment rule is ask first or act, and act does not post it on its own. A dot set to hand off hands the review off, and a dot set to act when asked skips it, so nothing is posted under either rule. The run starts with the step "Ticket from before the dot started", and Activity shows one line, "Reviewing 25 open tickets from before the dot started", until the last review starts. A ticket that closed, left the scope, was deleted, or that the Jira account can no longer see (Jira answers such a key with HTTP 400) is dropped before its turn, and the next one starts. While the dot is at its daily model cap and no review runs, the line says "25 open tickets from before the dot started wait for the daily limit". If you take a repo off the tracker, or change the tracker to another kind, the tickets left for the old scope are dropped on the next scheduler step.
+
+A dot that was running for over an hour before its first poll is not new, so an upgrade or a re-enabled poller never replays its tickets. A tracker that names `backfillLimit` itself asks for the backfill, and it runs for a dot of any age. A dot with `backfillLimit: 0` picks nothing, and setting a limit later picks the tickets then. Lowering the limit, or setting it to 0, also cuts a list that is already going: the dot starts no more than the new limit counts, and a review already waiting in the queue ends without a model call when the limit is 0. A ticket that was cut is not picked again when you raise the limit later, because the dot already picked its set once.
+
+After an upgrade, a dot that is more than an hour old reviews none of its open tickets until you add `backfillLimit` to its tracker (for example `"backfillLimit": 25`) and save the dot. It picks its tickets on the next poll.
+
+## Review a ticket on demand
+
+Ask a dot to review any ticket now: paste a Jira, Linear, or GitHub issue link (or a key such as `TAD-3`) in chat with "check this", or send `POST /api/dots/:id/review { "ticket": "<url or key>" }`. The dot reads the ticket through the connected tracker and runs the same ticket review a new ticket gets, including the comment draft under the dot's rules (ask first by default). A review someone asks for runs even when the ticket scores too thin for the automatic path. When the tracker is not connected, or the link is on another Jira site, the dot says so. A GitHub issue link works when the issue's repo is the dot's repo or one of its GitHub Issues tracker repos (`owner/name#12` and, with one tracker repo, `#12` work as keys).
+
+## Defects the dot files
+
+A bug the PR review finds becomes a defect in the dot's tracker, through the `file_defect` rule (default **Ask**, so each one waits in the Inbox). See [PR-REVIEW.md](PR-REVIEW.md#defects).
+
+| | Linear | Jira | GitHub Issues |
+|---|---|---|---|
+| Where | The first team in `teamKeys`, in the project named by `projectName` when set | A Bug in the first key of `projectKeys` | The dot's repo |
+| Label | `localdost` | `localdost` | `localdost` |
+| Open defects read | Open issues (state not completed or canceled) of the team, and of the project when set, the 100 last updated | JQL `project = KEY AND statusCategory != Done AND labels = "localdost"`, 100 | Open issues labeled `localdost`, pull requests left out, 100 |
+
+**Linear project.** The project is looked up by name inside the team, ignoring case. When the team has no such project, filing fails with `Linear project "<name>" not found in team <KEY>` and the approval stays in the Inbox so you can fix `projectName` and retry. Without `projectName`, the issue has no project.
+
+**The `localdost` label.** Linear uses the team's `localdost` label, else a workspace label of that name, and creates the label in the team when neither exists. If the label cannot be read or created, the issue is filed without it. Jira sends `labels: ["localdost"]` in the create call, and retries without the label when the project's create screen has no Labels field. GitHub sends `labels: ["localdost"]`, and retries without them when the API rejects the labels (a token without triage access, for example).
+
+**No duplicates.** Before it drafts a defect, the dot compares the bug with the open issues above. A match gets a comment with the new evidence and the head commit, once per issue and head commit, instead of a second defect. The comment is a `ticket_comment` action: with the default **Ask** rule it waits in the Inbox, and on GitHub it is a plain comment, not the sticky review comment. A tracker that cannot be read, or demo mode, falls back to drafting a new defect. Jira needs the Browse and Create permissions on the project; the new-issue search uses `POST /rest/api/3/search/jql`.
+
+## Loop guard
+
+Every issue, ticket, and comment the dot posts ends with a hidden marker, `<!-- localdost:bot sig=... -->`. The signature is an HMAC of the text, made with the server secret (`LOCALDOST_SECRET_KEY`, or `secret.key` in the data folder). A webhook or poll skips content only when the signature is valid and the author is the dot's own account: the GitHub App (or the user of `GITHUB_TOKEN`), `LINEAR_BOT_USER_ID` or the Linear user the API key belongs to, the Jira account of `JIRA_BOT_ACCOUNT_ID` or the one `GET /myself` returns. Pasting a marker into an issue, a description, or a comment does nothing, because a person cannot produce the signature and a copy of a real marker comes from a different author. If you replace `secret.key` or change `LOCALDOST_SECRET_KEY`, older markers stop counting.

package/docs/VOICE.md

@@ -0,0 +1,36 @@
+# Voice
+
+You can talk to a dot in two ways: push-to-talk in Chat, and a call from the dot's page. A call runs in browser mode or in realtime mode. The server decides the mode when the call starts.
+
+| | Browser mode | Realtime mode |
+|---|---|---|
+| Needs | A browser with speech recognition | An OpenAI key (Voice row in Setup, or `OPENAI_API_KEY`) and `LOCALDOST_TOKEN` on the server |
+| Speech in | Web Speech API recognition in the browser | OpenAI Realtime over WebRTC, transcribed with `whisper-1` |
+| Answer | The normal chat endpoint, with the dot's tools and memory | The realtime model, with the dot's call instructions |
+| Speech out | `speechSynthesis` in the browser | The realtime model's voice |
+| Audio goes to | Your browser vendor, depending on the browser | OpenAI |
+
+## Browser mode
+
+Browser mode needs no key. The call loops three steps: the browser's speech recognition turns your words into text, the text goes to `POST /api/chat` like a typed message, and `speechSynthesis` reads the reply aloud. The mic closes while the dot thinks or speaks, so the dot does not hear itself. Because the answer comes from the normal chat, the dot can list runs, rerun tests, and use its MCP tools during the call.
+
+Chat also has a push-to-talk mic button and a read-aloud switch that use the same browser features.
+
+Browser support varies. Chrome, Edge, and Safari support speech recognition, and Chrome and Edge send the audio to their vendor's servers for it. In a browser without it, the mic button shows a note and you type instead. A browser also needs a secure page (HTTPS or `localhost`) before it opens the mic.
+
+## Realtime mode
+
+In Setup, press **Connect** on the Voice row, paste an OpenAI API key, press **Test**, then **Connect**. Or set `OPENAI_API_KEY` on the server, which wins over a saved key. When a call starts, the app calls `POST /api/call/session`. The server asks OpenAI for a client secret that expires after 10 minutes and returns it to the app. The browser then opens a WebRTC call straight to OpenAI with that secret. `OPENAI_API_KEY` never leaves the server.
+
+| Variable | Default |
+|---|---|
+| `OPENAI_REALTIME_MODEL` | `gpt-realtime-2.1` |
+| `OPENAI_REALTIME_VOICE` | `marin` |
+
+The realtime model gets short call instructions: the dot's name, mission, what it must never do, and its custom instructions. It has no tools in this version, so it cannot read runs or rerun tests. Use browser mode or chat for that.
+
+Realtime mode also needs `LOCALDOST_TOKEN`. Without a token, anyone who reaches the server could mint OpenAI tokens on your account, so the server hides `OPENAI_API_KEY` from the call route and every call uses browser mode. When OpenAI refuses the request or cannot be reached, the call falls back to browser mode, and the server logs the reason.
+
+## Call receipts
+
+When a call ends, the app sends the transcript to `POST /api/call/receipt`. The server stores it in the dot's chat as one message with the call length and every turn, so you can read the call later.

package/docs/tinybee/00-README.md

@@ -0,0 +1,45 @@
+# TinyBeeAI — Product Documentation Set (v0.1 draft, 2026-10-24)
+
+Working name: **TinyBeeAI**. Vocabulary: **Bee** = local agent on the laptop · **Hive** = our cloud control plane · **Tenant** = one user's isolated space at `<slug>.tinybee.app`.
+
+| File | What it covers | Read it if you are… |
+|---|---|---|
+| `01-PRD.md` | Problem, vision, goals/non-goals, personas, tenancy model, pricing & free month, user journeys, functional + non-functional requirements, metrics, risks, release plan, open questions | Everyone; the source of truth for scope |
+| `02-architecture-pairing.md` | Components and ownership matrix, data paths, keys/identity, detailed QR pairing sequence, tunnel provisioning (Cloudflare), OAuth connection flow, model access paths, presence/push, updates, security checklist | Backend / infra engineers |
+| `03-local-agent.md` | The Bee: process model, installer, health check, storage, workflow engine & YAML schema, agent runtime & tool registry, local API, tunnel manager, Hive client, menu bar app, updates, edge cases | Desktop / agent engineers |
+| `04-local-setup-ui.md` | The laptop setup page and menu bar app: screen-by-screen flow, copy, states, accessibility | Designers, desktop engineers |
+| `05-mobile-app-ux.md` | Mobile app: principles, IA, onboarding & pairing screens, Home, Chat, Workflows (list, skills, guided editor, run detail), Connections, Activity, More, degraded states, notifications, visual system, analytics | Designers, mobile engineers |
+| `06-environments-and-delivery.md` | Environments (local / staging `dots.testllms.com` on Railway, tenants `dots-<slug>.testllms.com` / prod), Railway services, env vars, PWA → APK/IPA via Capacitor, CI pipeline, test strategy, staging hygiene, observability | Everyone shipping code |
+| `07-coding-agent-handoff.md` | Instructions for the coding agent: read order, ground rules, repo layout to add, 8 delivery phases with acceptance criteria, Definition of Done, reporting | **The coding agent — start here** |
+
+## The promise in one paragraph
+A user downloads the app, picks an address, installs the Bee on a spare Mac, scans one QR code, and within a minute has a private, always-on AI agent at `https://<slug>.tinybee.app` that they configure entirely from their phone. Their account credentials and data stay on their laptop; we only provide identity, the address, the secure tunnel, notifications and (optionally) metered model access — which is why the first month is free and the plans are cheap.
+
+## Key decisions already taken in this draft
+- macOS only (Apple Silicon + Intel). Windows is **not supported** and not scheduled. Single native binary, **no Docker** for end users.
+- One Bee per tenant in v1.
+- Hive stores **no user content, no third-party tokens, no workflow bodies**.
+- Cloudflare Tunnel behind a provider interface (swappable for Tailscale/own relay).
+- Sends/writes require approval by default; reads are automatic.
+- Trial lapse → Bee keeps running locally; only remote access and push pause.
+
+## Relationship to localdost (this repo)
+localdost is the local agent app: one Node process + SQLite, "dots" that watch and act, a rule gate per action kind, and approvals in a phone Inbox. In TinyBee terms, **a running localdost instance is the Bee**. The TinyBee layer adds what localdost does not have yet: Hive (tenant identity, pairing, Cloudflare tunnel provisioning, push relay, metering) and the consumer mobile app with QR pairing. Map when reading these docs:
+
+| TinyBee doc term | localdost term |
+|---|---|
+| Bee | the localdost server process |
+| Workflow | a dot + its Watch |
+| Skill | role preset |
+| Permission scope (auto / ask / deny) | rule gate (act / act when asked / ask first / hand to you) |
+| Approval card | Inbox item |
+| Connection | integration credential (GitHub, Jira, Linear…) |
+
+## How this repo is used
+The human owner writes and maintains these docs; a coding agent implements them in this repository (`07-coding-agent-handoff.md`). Build and test target is the staging PWA at `https://dots.testllms.com` (Railway); APK/IPA are packaged from the same client with Capacitor after PWA verification (`06-environments-and-delivery.md`).
+
+## Suggested next steps
+1. Review open questions at the end of `01-PRD.md` and `05-mobile-app-ux.md`.
+2. Prototype pairing end-to-end (install → QR → tunnel → `/health` from phone) before any workflow features; it is the riskiest and most differentiating part.
+3. Begin Google OAuth app verification immediately (long lead time).
+4. Low-fi mobile wireframes for onboarding, Home and the guided editor; usability-test the pairing flow with 5 non-technical users.