tinybeeai 0.0.0-stage → 0.16.1

package/docs/DOGFOOD-LEDGER.md

@@ -0,0 +1,81 @@
+# Dogfood ledger: false positives and false negatives
+
+The dot on :4500 reviews localdost itself. Each time it says something wrong (a false positive) or misses something real (a false negative), the case goes here with its cause and its fix, and becomes a golden eval case so it cannot come back. Counts are from the live dot's Inbox, 2026-10-07 to 2026-10-10: 361 drafts went out after approval and 262 were rejected (plus 187 expired and 102 superseded).
+
+## False positives in the dot's reports
+
+| Case | Seen | Cause | Fix |
+|---|---|---|---|
+| "1 bug found" when the facts show only a confirmed risk that no test reproduced | 28 rejected reports and checks | the headline counts confirmed risks as bugs | a bug is a reproduced failure (a failed test or a confirmed step failure); unreproduced risks are "N risks to test" in the headline, the check title and the PR comment, from one source |
+| "N checks not tested yet" that does not match the list below it | 4 or more | the headline and the list are counted in different places | every number in a report comes from one structured summary; a consistency check refuses to draft when they differ |
+| "85 of 138 tests passed" when 53 were skipped and none failed | every report | the line hides skipped tests | "85 passed, 53 skipped, 0 failed" |
+| "138 automated tests ran: 85 passed, 53 skipped" (PR 127, 0.13.0 batch, [KAT-402](https://linear.app/katalon-pm/issue/KAT-402)) | The dot, on PR 127, and its own safety check held the draft over it | the count of "ran" added the skipped tests, which did not run | "85 automated tests ran and passed. 53 were skipped (they do not apply to this project)."; the consistency check reads the ran and skipped counts back from the summary and the facts for the safety reviewer say a skipped test did not run |
+| A defect for behavior the PR says it changes on purpose (webhooks refused without a secret, fail-closed commit checks, paid fallback off by default, fork PRs not run) | 6 or more | the dot does not read the decisions in the PR body or the linked ticket | statements of intent in the PR body, the linked ticket and the repo docs ("decided", "by design", "behavior change", "intended") turn a matching risk into a "Behavior change to confirm" note, not a defect |
+| A defect whose Expected is "the team decides" or "confirm this is wanted" | 4 | a design question was written as a bug | no Expected, no defect: it becomes a question on the ticket |
+| The same defect filed again from a later PR or commit | 10 or more | dedupe only covers one run | match open defects by signature and by Linear search across runs; add evidence to the existing issue instead |
+| Defects for an older head of a PR | several | drafts outlive the head they were made for | a draft for a head that is no longer the PR head is superseded, defects included |
+| A ticket review draft in the Inbox with a summary line that did not match its lists, and two drafts for one ticket from different review runs ([KAT-371](https://linear.app/katalon-pm/issue/KAT-371)) | The dot, in the Inbox | the line took the model's counts while the comment capped and repeated lines; ticket comments never replaced an older pending draft | the line counts the rendered lists after the cap and after repeats are dropped; a newer review of the same ticket supersedes the older pending draft and the note names the newer run (tests in `ticket-comment`, `approvals-supersede`, `github-issues`) |
+| A ticket that is Done, Canceled, or closed listed under "Tickets without acceptance criteria" in the daily digest (KAT-288 and others) | the owner's Daily digest report page | the model wrote the section from the ticket reviews of the last 24 hours and never asked the tracker whether the ticket is still open | the dot builds the section itself from the run records: a review that read the ticket without criteria, and the tracker (GitHub, Jira, Linear) says it is open now; a closed ticket, or one the tracker will not read, is left out; a model-written copy of the section is removed; eval case `digest-closed-tickets` |
+| A merged PR listed under "Merged with bugs reported" in the daily digest when only a confirmed risk exists and no test failed (#79) | the owner's Daily digest report page | the model read a risk the verifier confirmed from the code as a bug | a bug is a failed test: the section lists a merge only with a reproduced failure, counted with the same summary line as the PR report; a risk-only run is "risk to test" in the digest lines, never "bug"; a model-written copy of the section is removed; eval case `digest-risk-only-prs` |
+| Environment failures filed as product defects (disk full, ENOSPC, runner cancelled, a test timing out under load, the dot's own new test failing on its first run) | 8 | failures are classified only by the test result | environment signatures (ENOSPC, disk-full notices, cancelled jobs, load timeouts) classify as environment and never become a product defect |
+| A defect for a rule the PR sets out on purpose: the map's evidence-only requirement rule, a requirement listed under each app with a new id, a finding that matches a stated decision | 4 drafts on 2026-10-10 (two were duplicates of each other) | the defect reviewer reads the code but not the PR's docs (docs/TRACE-MAP.md) or the commit that states the rule | intent-aware defects in [Report accuracy](https://github.com/duonghaijoe/localdost/pull/94); the same draft text on two heads is one defect |
+| A defect whose own Expected is what the code does: selected cases show their full count across folders; a check run left open when counts disagree, though the run's cleanup closes it | 2 drafts on 2026-10-10 | the reviewer stops at the first line it cites and does not follow the call to the end of the run | defects found by reading the code must cite the line that shows the failure, see KAT-304's sibling lane on code-reading defects |
+| A rejected defect came back on every new push to the same PR, because a finding read from the code is worded again on each run ([KAT-312](https://linear.app/katalon-pm/issue/KAT-312)) | The dot, on its own PRs | the draft step also matches a rejected finding of the same PR (any head, so also its merge) by the cited file, an overlapping line range and the review source, and the rejection holds until the cited lines change (golden case `rejected-finding-reworded-on-new-push`) |
+| "No tests ran" in the Details of a report that lists "Ran 138 selected tests: 85 passed, 53 skipped, 0 failed" under What I tested (PR 104, [KAT-330](https://linear.app/katalon-pm/issue/KAT-330)) | The dot, on PR 104 | the review text is written before the test run and pasted unchanged into Details | test facts come from one source, the run's results: once the run has results, review-stage sentences that say the tests did not run are dropped, and the consistency check refuses to draft a report that says no tests ran while it lists results; a run that did not run keeps its wording; case `review-text-says-no-tests-ran` |
+| "No tests ran in Safari." dropped from Details, and the pre-draft check refused a consistent report ([KAT-332](https://linear.app/katalon-pm/issue/KAT-332)) | The dot, on its own PR 106 | the "no tests ran" pattern also matched a sentence scoped to a place or condition | a sentence scoped with in, on, for, against, under, with or across is a coverage note and stays; only an unscoped claim is dropped or refused |
+
+## False positives in the safety reviewer
+
+| Case | Seen | Cause | Fix |
+|---|---|---|---|
+| "linear:KAT is outside the owner's permitted localdost Linear project" on every defect | 24 escalations | the model reads the Linear team key KAT as a different place from the localdost project | allowed destinations are a structured list (repo duonghaijoe/localdost; Linear team KAT, project localdost) checked by code; the model reviewer judges only the content |
+| "Reviewer returned no decision" | 40 escalations | the review model was unavailable (spend cap), and unavailable means escalate | when the model is unavailable, the deterministic checks and the rule decide, and the draft says the review model was unavailable |
+| "The draft is unusually long for an automatic post" on full QA reports | 10 | a fixed length limit | the QA report summary comment is long by design; the limit applies to other kinds |
+| A model finding about content cleared as a destination note ("Contains a token from a different workspace") | found by the dot on [Safety review fixes](https://github.com/duonghaijoe/localdost/pull/95), KAT-305 | the destination filter matched "different workspace" and dropped the whole finding | a reason that names a content risk (token, secret, credential, personal data, blame) still escalates |
+| A reason with a finding and a place or a length was cleared whole ("Contains a token and the body length looks odd", "The draft names a different customer team in the wrong project") | found by the dot on [Safety review fixes](https://github.com/duonghaijoe/localdost/pull/95), KAT-305 follow-up | the filters matched one phrase anywhere in the reason and dropped all of it; the length filter had no content guard | the reason is split into clauses (sentences, commas, "and"); it is cleared only when every clause is about the destination or the length, and a clause that names a content risk (now also "customer") keeps the escalation, for both filters |
+| A correct QA report escalated over counts ("the draft says eight checks were not tested, but the records list six"; the report listed six checks plus "And 2 more checks in the run") | found on a live report, [KAT-329](https://linear.app/katalon-pm/issue/KAT-329) | the model compared the counts it read in the draft, which code already checks before drafting (one-summary consistency check) | a reason wholly about destination, length or counts (bugs, checks, tests, risks, questions: "says N but lists M") clears on the QA report summary and check run, with a note that code checked the counts; a reason about results ("says no bugs but a test failed") or with a content risk keeps the escalation; case `safety-count-reasons` |
+
+## False negatives: real problems the dot missed
+
+| Case | Found by | What the dot should have done |
+|---|---|---|
+| A forged webhook could make the runner check out and run fork code (worktree commit not verified) | Opus security review of #75 | a security pass on any diff that clones, checks out, runs code, or trusts event fields: "can an attacker choose what runs?" |
+| A deleted dot's run could still post a PR comment or create an approval (run row gone, gate not stopped) | Opus review of #66 | the same pass: "what happens to in-flight work when the object is deleted?" |
+| copyFiles could write outside the worktree through a symlinked folder; a named pipe could block the server | Opus reviews of #84 | the same pass: symlinks, TOCTOU, special files for any file copy from a checkout |
+| `isRunCancelled` change made AI-Vision dispatch throw at once | CI on #66 | a "callers of a changed function" check: list every caller of a function whose contract changes |
+| Every phone push failed with 403 for a day (803 failures) | Huy and I, by hand | self-health: three or more consecutive delivery failures with the same error raise an outage on the dot itself |
+| A draft for an existing test overwrote edits made after it was written; a retire draft stayed approvable after the ticket check changed its mind; two repos with the same spec path merged into one spec | found by the dot on its own PR [A new ticket checks the existing tests it changes](https://github.com/duonghaijoe/localdost/pull/100), [KAT-314](https://linear.app/katalon-pm/issue/KAT-314), [KAT-315](https://linear.app/katalon-pm/issue/KAT-315), [KAT-316](https://linear.app/katalon-pm/issue/KAT-316) | the impact check itself: a draft records the case version it was based on, a changed verdict closes its Inbox draft, and a spec is keyed by repo and path |
+| A draft for an existing test recorded its base version when it was stored, after the model answered, so an edit made during the review was lost on accept; the impact panel said nothing was waiting when its request failed | Opus review of #100 | the draft base is the version the review read; a failed load shows an error with a retry, never an empty state |
+| A retire draft still retired a case that a person edited after the draft was written; the ticket review page showed "N existing tests checked" with no rows when its list failed to load | Opus review of [A new ticket checks the existing tests it changes](https://github.com/duonghaijoe/localdost/pull/100), [KAT-315](https://linear.app/katalon-pm/issue/KAT-315), [KAT-319](https://linear.app/katalon-pm/issue/KAT-319) | a retire draft records the case version the review read and approval refuses when it changed; every screen that loads the list shows an error with a retry |
+| A refused connection in one repo of a two-repo dot marked a failure in the other repo as environment (default-branch facts read the newest run of any repo) ([KAT-320](https://linear.app/katalon-pm/issue/KAT-320)) | The dot, on PR 94 and on main | scope default-branch facts to the repo of the change |
+| An environment failure (ENOSPC) on a linked check still marked the risk reproduced and drafted a file_defect ([KAT-321](https://linear.app/katalon-pm/issue/KAT-321)) | The dot, on PR 94 and on main | an environment failure never reproduces a risk and never drafts a defect, on every path |
+| The burst test left a localdost-kat313-* temp folder with 500 run folders on every run ([KAT-322](https://linear.app/katalon-pm/issue/KAT-322)) | The dot, on PR 94 and on main | a test or fixture that makes a temp folder removes it, even when its child is killed |
+| A head change or close on repo B's PR 84 superseded or expired repo A's pending defect for its PR 84 (the new-defect draft had no repo) ([KAT-323](https://linear.app/katalon-pm/issue/KAT-323)) | The dot, on PR 94 and on main | every defect and evidence draft carries its repo, and PR-state changes never touch a draft with an unknown repo |
+| The same failing test in two repos of one dot shared one defect (the bug signature had no repo) ([KAT-324](https://linear.app/katalon-pm/issue/KAT-324)) | The dot, on PR 94 and on main | the repo is part of the bug key and signature in a multi-repo dot |
+| An ENOSPC failure of an AI-Vision or generated check still marked the risk reproduced and drafted a defect ([KAT-325](https://linear.app/katalon-pm/issue/KAT-325)) | The dot, on PR 94 and on main | the environment signature applies to the failure text of every check kind, not only repo specs |
+| A changed ticket (10% to 20%, later 30%) kept the old note, ticket line and draft steps on an open test update ([KAT-327](https://linear.app/katalon-pm/issue/KAT-327)) | The dot, on the ticket review | a new check of a changed ticket refreshes the note, the ticket line and the pending draft, and keeps the base-revision guard |
+| Decimal values lost their fraction: "from 3 days to 4.5 days" proposed 4 ([KAT-328](https://linear.app/katalon-pm/issue/KAT-328)) | The dot, on the ticket review | a number keeps its decimal point and thousands separator in every value rule |
+| Adding or removing a repo of a dot broke its defect links: a saved answer's bug key and a pending defect no longer matched, and drafting from the saved answer failed ([KAT-326](https://linear.app/katalon-pm/issue/KAT-326)) | The dot, on PR 94 and on main | a bug or defect lookup also tries the other repo shape of the key and signature |
+| Every PR report showed the same test count | Huy | self-health: identical totals across different commits raise "test count looks stale" |
+| 30 GB of temp folders leaked by test runs | disk full | resource leaks: new mkdtemp without cleanup in a diff is a risk; disk free dropping fast raises an alert |
+| A test that fails just after midnight | CI | time-dependent tests ("today", local dates) are a risk the review names |
+| A rejected report left its GitHub check stuck | me | an approval path with no close path is a risk the review names |
+| Map and heatmap unreadable with real data | Huy | UI reviews check the screen with the dot's own real data size, not only demo data |
+| One rejected defect stopped the same bug from being drafted on every later PR | found by the dot on [Report accuracy](https://github.com/duonghaijoe/localdost/pull/94), KAT-307 | the earlier-defect lookup matched rejections by bug signature across PRs | a rejection holds for its own PR; a later PR drafts the bug again |
+| A failing assertion in a test the PR adds was reported as an environment problem | found by the dot on [Report accuracy](https://github.com/duonghaijoe/localdost/pull/94), KAT-308 | every failure of an added test on its first run was set aside | an added test that compared values and failed is a bug; only one that broke before any assertion is set aside |
+| "Never push to acme/prod, only comment." made acme/prod an allowed place to post | found by the dot on [Safety review fixes](https://github.com/duonghaijoe/localdost/pull/95), KAT-306 | the allow word "only" in a forbid sentence made every repo in it allowed | only the clauses from the allow word on, minus the clauses that forbid, name allowed places |
+| "Test count looks stale" never fired for dots that keep code in app/, packages/ or lib/ | found by the dot on [Safety review fixes](https://github.com/duonghaijoe/localdost/pull/95), KAT-311 | only changes under src/, client/, test/ and e2e/ counted as code, so every run of such a dot was left out of the streak | any changed path that is not docs (*.md, docs/), CI config or a lockfile counts as code |
+| Test files that hung until CI timed out (18 minutes for multi-repo-review.test.ts) were put down to machine load and rerun | 2 CI runs and 1 local run on 2026-10-10, KAT-309 | a demo-mode test that found nothing on port 4320 started the sample shop in-process and never stopped it | the shop never holds a process open on its own; a test spawns a process that starts the shop and checks it exits |
+| A cart total that shows the wrong discount was hidden as a stated behavior change next to "Discount banner removed from the cart" | found by the dot on [Report accuracy](https://github.com/duonghaijoe/localdost/pull/94), KAT-310 | a finding matched a decision when it shared two content words with the sentence | a match needs the decision's subject (its head noun and at least half of its words) and a result that agrees with what the decision says now happens; a failed test is read by its received value only, so an assertion that contradicts the decision is a bug |
+| A connection refusal or a page that hung after a change that broke app startup was put down to the environment | found by the dot on [Report accuracy](https://github.com/duonghaijoe/localdost/pull/94), KAT-308 follow-up | every ECONNREFUSED and load-timeout signature was environment, whoever caused it | those two are environment only when the latest default-branch run shows the same signature on the same test, or the change touches no app code; otherwise "the app did not answer; this change may cause it" and a defect is drafted. A full disk, a cancelled job, out of memory and a missing browser stay environment always |
+| Test files hung at 100% CPU with the test timeout never firing (chat-tickets.test.ts; the same loop froze a live server when many runs finished at once) | KAT-313, CI and local runs | every finished run queued its own artifact-cap pass that parsed every run row and read every run folder of the dot, so N finishing runs cost N-squared work inside setImmediate; a change that adds work per finished run, per job, or per poll result is a risk the review names, and a test that waits on a queue drain needs a burst-size check |
+| A concrete code-path risk (a cited file and line, and the input that breaks it) that no test reproduced was shown only as a "risk to test" and never filed, after "bug" came to mean a reproduced failure | the follow-up to the "1 bug found" row, found while dogfooding | the reviewer names an optional failing input. A risk with a cited line and a concrete input is filed as a defect labelled "found by reading the code", with the file and line and the input in the body and lower confidence. It stays a "risk to test" in the headline and the counts, never a bug. It is never drafted for an environment failure, a rejection of it holds while the cited lines are unchanged, and it carries the repo. A vague risk (no input, or "some edge cases") is never filed. A stated decision or a design question still wins. Eval cases `code-path-risk-is-filed` and `vague-risk-is-not-filed` |
+| A pending "found by reading the code" defect for PR 106 expired when 106 merged, losing a bug that lives on main ([KAT-333](https://linear.app/katalon-pm/issue/KAT-333)) | The dot, on 2026-10-12 | merging a PR expired every pending draft of that PR | a merge keeps pending defect drafts and their evidence drafts and records the merge commit; a close without a merge still expires them; PR comments and check runs keep the old behavior |
+
+## Golden eval cases
+
+Each row above is an eval case under `test/fixtures/qa-review/dogfood/`, run by `npm run eval:qa-review` and by unit tests: the input (diff, PR body, ticket, run facts at that head) and the expected outcome (no defect, a named defect, the headline counts, or an alert). The review evals run in CI, and a regression fails the build.
+
+### Decision set (KAT-210)
+
+`test/fixtures/qa-review/decisions/<approval id>/` holds real report and defect drafts with the decision a person gave each (`input.json`: the draft, the watch and the run facts; `expected.json`: approve or reject, and for a reject the escalation category). `test/decision-eval.test.ts` runs `src/review/decision-eval.ts` over them without a model: the safety rules (`safeReview` with the mock model) and the report consistency check must agree with the person. An approved draft that a gate holds, or a rejected draft that a gate lets through for a reason code can judge (a credential, copied instructions, the must-not rule, a destructive kind), is a disagreement and fails the test. A rejection for any other reason (a stale head, a duplicate, a claim the evidence does not back) needs a model and is skipped, and the test prints the count. A known disagreement goes in `decisions/allowlist.json` with a reason; an entry for a case that no longer disagrees also fails, so the list stays true. To refresh the set, run `npm run golden:export -- --db <copy of the dot database> --since <date> --limit 20` (the database opens read-only; point it at a copy), read every written file for a secret or personal data (the export masks email addresses, tokens, home paths and URLs outside github.com/duonghaijoe and linear.app/katalon-pm, but a person decides what is safe to commit), run `npm test`, and list each new disagreement in the allowlist or fix the gate.

package/docs/GITHUB.md

@@ -0,0 +1,148 @@
+# GitHub
+
+A dot reads PR files and diffs, clones the commit it tests, and posts one sticky PR comment plus a check result. localdost can reach GitHub three ways: a GitHub App, a token (from the GitHub CLI or a personal access token, PAT), or neither (demo mode). Events arrive by webhook or by polling, and either works with an App or a token.
+
+## Connect from the app
+
+Open Setup, press **Connect** on the GitHub row, and pick how localdost signs in:
+
+| Choice | What happens | Best for |
+|---|---|---|
+| **GitHub CLI login** | When `gh` is signed in on the server, **Use GitHub CLI login** connects. localdost reads the token from `gh` each time it starts | Your own machine |
+| **GitHub App** | **Create GitHub App** opens GitHub with the name, permissions, and events filled in. Create the App, install it on your repos, and GitHub sends you back to Setup connected | A team server |
+| **Personal access token** | Paste a fine-grained token with the [permissions](#permissions) below, press **Test**, then **Connect** | A server without `gh` where you cannot create an App |
+
+Then pick the repos your dots watch. **Test** on the row checks the saved connection again, and **Disconnect** deletes it. When `GITHUB_TOKEN` or the App variables are set in the environment, the row shows **Set by environment** and stays read-only.
+
+## Environment variables
+
+| | GitHub App | PAT | Demo |
+|---|---|---|---|
+| Variables | `GITHUB_APP_ID`, `GITHUB_PRIVATE_KEY` | `GITHUB_TOKEN` | none |
+| Check result | Check run with line annotations, queued and in progress states | Commit status, no annotations | Outbox |
+| Comment author | `<app-name>[bot]` | The token's owner | Outbox |
+| Repos | Every repo the App is installed on | Every repo the token can reach | Demo payloads |
+
+When both App variables are set, App mode wins over `GITHUB_TOKEN`. `GITHUB_PRIVATE_KEY` holds the PEM text, with `\n` escapes allowed, or a path to the `.pem` file. localdost looks up the installation for each repo and caches the installation token until shortly before it expires.
+
+For GitHub Enterprise Server, set `GITHUB_API_URL` (for example `https://github.example.com/api/v3`) and `GITHUB_SERVER_URL` (`https://github.example.com`).
+
+## Pick a setup
+
+| Situation | Setup |
+|---|---|
+| Trying it on your own machine | **GitHub CLI login** in Setup plus polling. `localdost init` writes the same with `gh auth token` |
+| A team server with a public HTTPS URL | **GitHub App** in Setup plus webhooks |
+| A server that GitHub cannot reach | GitHub App or token plus polling |
+
+Do not combine a webhook and polling on the same repo. The webhook dedupes on the delivery id and polling on the commit, so each push would run twice. A dot made in the setup flow polls until GitHub has delivered a webhook to the server (the Event delivery step says so, and **Check again** reads the server). Once webhooks work, set `pollGithub` to `false` on the dot (`PATCH /api/dots/:id`) so it stops polling.
+
+## Permissions
+
+The same permissions apply to an App and to a fine-grained PAT:
+
+| Permission | Access | Used for |
+|---|---|---|
+| Metadata | Read | Repo lookups, collaborator permission checks for checklist ticks |
+| Contents | Read | Clones, file reads at a sha, compare, code search |
+| Pull requests | Read and write | PR files and diffs, the sticky comment |
+| Checks | Read and write | Check runs (App only) |
+| Commit statuses | Read and write | Commit statuses (PAT mode) |
+| Actions | Read | Failed job logs for CI failure triage, coverage artifacts for the PR review |
+| Deployments | Read | The deploy wait of a merge run: the deployments of an environment and their statuses, see [Waiting for the deploy](SETUP.md#waiting-for-the-deploy). The same permission backs the Deployment status event |
+| Issues | Read and write | Issues as a tracker: read issues and timelines, the ticket review comment, defect issues, status labels. Subscribe the App to the Issues event |
+| Members (organization) | Read | The [PR scope](SETUP.md#pr-scope) `team` rule: read the members of a team of the org. Without it GitHub refuses the read: the PR runs without the scope, and its PR comment and check wait in the Inbox with the reason, and the dot shows "PR scope not applied" |
+
+Webhook events the App subscribes to, matching these permissions:
+
+| Event | Needs permission |
+|---|---|
+| Pull request, Push | Pull requests, Contents |
+| Workflow run | Actions |
+| Deployment status | Deployments |
+| Issue comment | Issues, Pull requests |
+| Issues | Issues |
+
+An App made with **Create GitHub App** in Setup has the Issues and Members permissions and the Issues event. An App made earlier needs them added in its GitHub settings, and each installation must accept the new permissions. For an organization, an owner approves the Members permission. A PAT needs Issues read and write on the watched repos, and Members read on the organization when a dot uses the `team` rule; it has no events, so the poller reads issues instead.
+
+A classic PAT needs the `repo` scope. localdost never pushes, merges, or reverts.
+
+## GitHub App
+
+**Create GitHub App** in Setup does every step below for you. To create the App by hand instead:
+
+1. Open GitHub Settings, Developer settings, GitHub Apps, and create an App.
+2. Set the webhook URL to `https://<your-host>/hooks/github`. Set a webhook secret and put the same value in `GITHUB_WEBHOOK_SECRET`. Leave the webhook inactive when you plan to poll. An App that **Create GitHub App** made before the public URL was set has no webhook: add the URL and the secret in the App's settings.
+3. Grant the repository permissions in the table above.
+4. Subscribe to the events in the next table.
+5. Generate a private key. Set `GITHUB_APP_ID` and `GITHUB_PRIVATE_KEY`.
+6. Install the App on the repos your dots watch.
+
+## PAT
+
+1. Create a fine-grained token with the permissions above on the watched repos, or run `gh auth login` and use `gh auth token`.
+2. Paste it in Setup with **Personal access token**, or set `GITHUB_TOKEN`. In `.env.localdost`, `GITHUB_TOKEN=${cmd:gh auth token}` reads it at start, so the token never lands in a file.
+3. For webhooks, add a repo webhook in the repo's Settings, Webhooks: URL `https://<your-host>/hooks/github`, content type `application/json`, the same secret as `GITHUB_WEBHOOK_SECRET`, and the events below. A token has no webhook of its own, so until someone adds this to each repo nothing arrives. GitHub sends a ping when the hook is added, and the setup flow's Event delivery step shows webhooks once it has seen one.
+
+## Webhook events
+
+| Event | What localdost does |
+|---|---|
+| Pull request | `opened`, `synchronize`, `reopened`, `ready_for_review` queue a PR check (a dot that already reviewed that head skips `ready_for_review`). `closed` with a merge queues a post-merge check. A repo entry can limit which PRs a dot takes, see [PR scope](SETUP.md#pr-scope) |
+| Push | A push to the default branch queues a post-merge check, unless the repo's PR scope keeps out the PR whose merge it is. Branch deletes are ignored |
+| Workflow run | A completed run with conclusion `failure` or `timed_out` queues CI failure triage |
+| Deployment status | A `success` state for a repo and an environment wakes the merge runs of dots that wait for that deploy, see [Waiting for the deploy](SETUP.md#waiting-for-the-deploy). With an environment URL it also records the preview URL for that sha. A later PR check tests against it. Polling never sees it: a PR of a dot that polls has no preview, and the dot's `prTestTarget` decides what its check tests, see [PR tests without a preview](SETUP.md#pr-tests-without-a-preview) |
+| Issue comment | An edit of the localdost sticky comment records checklist ticks, see [PR-REVIEW.md](PR-REVIEW.md#ticking-the-checklist). A new comment `/localdost review` on an issue, from a user with write access, queues a ticket review; on a pull request it queues a new check of the PR's latest push, for every dot that watches the repo as an app repo (a bot, and a comment that holds the localdost report, are no command) |
+| Issues | For a dot with a GitHub Issues tracker: `opened`, an `edited` body or title, and a `labeled`, `typed`, or `milestoned` change that brings the issue into scope queue a ticket review, see [TRACKERS.md](TRACKERS.md#github-issues) |
+
+GitHub's `ping` gets a 200. Other events get a 202 and are ignored. A bad signature gets a 401. With `GITHUB_WEBHOOK_SECRET` unset, `/hooks/github` answers 503 with a message that names the setting, and queues nothing. `LOCALDOST_ALLOW_UNSIGNED_WEBHOOKS=1` accepts unsigned deliveries again for a local demo and logs a warning at start.
+
+For local development, `npx smee-client -u https://smee.io/<channel> -t http://localhost:4319/hooks/github` forwards deliveries and keeps the signatures valid.
+
+## Polling
+
+Set `LOCALDOST_POLL=1`, or `pollGithub: true` on one dot. Every `POLL_GITHUB_SEC` seconds (default 60) the poller does two things per watched repo:
+
+- New commits on the default branch become one push event, which queues a post-merge check.
+- Each open PR with a new head sha queues a PR check. A label change does not.
+
+Polled events go through the same normalizer, dedupe keys, and job queue as webhooks. Cursors live in the `poll_cursors` table.
+
+**First poll.** The first poll after boot records a cursor and queues nothing for the repo as a whole. A dot's own first poll of a repo is different (KAT-352): the dot takes the 5 most recently updated open PRs, so a new dot hears about work that is already open without flooding the queue on a busy repo. The dot is marked per repo in `poll_cursors` (`github-seed:<dot>:<repo>`), so it happens once. It is left out for a dot that was more than an hour old at its first poll (an upgrade or a re-enabled poller never replays PRs), for a PR this poll already sends to every dot, and for a PR the dot already reviewed at that head. The repo's [PR scope](SETUP.md#pr-scope) applies to these PRs like to any other. A new dot has had no moment to say whose PRs it takes, and a shared repo holds the PRs of other teams, so a first look at a repo whose scope names no authors, team or linked issue labels is held: the PR comment and the check of those runs wait for approval in the Inbox, and the "queued" status is not written. The event carries `firstLook: true` for this. Name authors, a team or labels in the scope and the first look posts on its own.
+
+**After a gap.** A stored cursor older than an hour (`STALE_CURSOR_MS`: the server was down, or a laptop host slept) used to be recorded again with nothing replayed, so the PRs and the new issues of that time were never reviewed and nothing said so (KAT-363). Now the poll still re-records the commits of the default branch (the gap starts no post-merge run), but it takes the open PRs that changed since the old cursor: a new PR, a new head, a draft that turned ready, told from the PR map of the old cursor, so a PR the dot already saw at that head is not reviewed twice. The events go through the repo's [PR scope](SETUP.md#pr-scope) like any other, newest update first, and each dot takes at most 5 of them after its own scope (`CATCH_UP_MAX`, the same as a first poll), so on a repo shared by several teams the PRs of the others do not use up a dot's share. The PRs past a dot's share are recorded as seen and are not caught up later. Each event carries `catchUp: { since, gapMs }`, and its run starts with a "Caught up after a gap" step: "localdost did not poll GitHub for 9 h 55 min (since 13 Oct 22:10 UTC), so this was picked up late." The log has one line per poll with the counts. The issues of a GitHub tracker catch up the same way, see [TRACKERS.md](TRACKERS.md#github-issues), and so do the tickets of a Linear or Jira tracker, see [TRACKERS.md](TRACKERS.md#linear). A repo's first poll ever has no old cursor and catches up nothing.
+
+**A dot made in the app polls.** `POST /api/dots` sets `pollGithub: true` on the new dot when the server has no webhook route, that is, no `LOCALDOST_PUBLIC_URL` or no `GITHUB_WEBHOOK_SECRET`. A `pollGithub` in the request body wins. Without this the in-app flow made a dot that never heard about a PR.
+
+**Listening line.** `GET /api/dots` and `GET /api/dots/:id` return `listening`: `polling` (with `pollSec`), `webhooks`, or `none` (with `listeningMissing`: `GitHub connection`, `public URL`, `webhook secret`). Polling wins when both routes are set up. The dot page and the dot list show it as "Listening: polling every 60 s", "Listening: webhooks", or "Not listening: ..." with a Turn on polling button (`PATCH /api/dots/:id` with `pollGithub: true`). A paused dot, a demo or sandbox server, and a dot with no GitHub repo or GitHub Issues tracker have no `listening`. A dot with `listening: none` shows "Needs attention" in the app, whatever its last run said, since a dot that hears nothing is not all good. Polling that fails 3 times in a row (the dot's repos, and the repos of its GitHub tracker, each counted on its own) is `none` too, with `listeningMissing: []` and `listeningReason` (for example `GitHub polling for acme/shop failed 3 times in a row: HTTP 401: Bad credentials`): the line reads "Not listening: <reason>" with an Open Setup button, and the dot status is `attention` until one poll works again. The server keeps the count in memory, so a restart starts clean. `GET /api/dots` and `GET /api/dots/:id` also return `lastEventAt`, the time of the newest GitHub event the dot recorded (skipped events included, `null` before the first), and the line adds "Last event 2 h ago." so a quiet dot shows how long it has been quiet. An open dot list or dot page follows the line without a reload: the `dot` live event carries `delivery` (`listening`, `pollSec`, `listeningMissing`, `listeningReason`) when it changed, which the server checks every 5 seconds, so polling that breaks shows the reason and Open Setup, and polling that recovers shows "Listening" again.
+
+A draft PR that turns ready is polled too: the poller keeps which PRs were drafts, and queues the PR check when one is no longer a draft, even though its head did not change.
+
+A dot with a GitHub Issues tracker also polls its issue repos: issues opened, edited, or brought into scope since the last poll queue a ticket review.
+
+Polling does not see CI failures, deployment previews, comment edits, or `/localdost review` comments. A merge run that waits for a deploy does not need the event: it reads the deployments from the API every 30 s ([Waiting for the deploy](SETUP.md#waiting-for-the-deploy)). With no preview, a PR check tests against the dot's base URL and labels the report, or skips the tests, by `prTestTarget` ([PR tests without a preview](SETUP.md#pr-tests-without-a-preview)). Checklist ticks made on GitHub therefore need the Issue comment webhook. Without it, tick items in the app's run page instead.
+
+## Check status
+
+A PR check can wait behind other reviews. localdost shows that on GitHub at once, so a PR never looks ignored:
+
+| When | Check state | Title |
+|---|---|---|
+| The check job is enqueued | queued | `Queued, N ahead` |
+| The run starts | in progress | The latest step, or `Running tests 12/22` once the tests start |
+| The report is ready | completed | The report from the check-run renderer, written into the same check |
+| A newer push to the same PR or branch | completed, neutral | `Superseded by <sha>` |
+| The run fails, is cancelled, or ends without a report | completed, neutral | `Run failed`, `Cancelled`, `Interrupted`, or the last step |
+| The report waits for approval | completed, action required | `Report waiting for approval` |
+
+N counts the jobs that start first: the ones running now and the ones queued earlier. Progress updates go out at most every 30 seconds, and the latest state wins. A run that fails, is cancelled, is interrupted, is skipped, or ends without a report closes its check as neutral, and the title says which one happened. None of these says anything about whether the change works, so none of them blocks a merge. A report that waits for approval closes it as action required. A newer push replaces an older commit, which keeps one check: it says `Superseded by <sha>`, and its own report still completes that same check when its run finishes. A push in one repository never replaces a check in another repository of the same dot. If GitHub rejects a closing update, the check stays open in localdost too, and the next close tries again, so no check stays in progress.
+
+With a token, GitHub has commit statuses only. Neutral and cancelled show as success, failure and timed out show as failure, and a report that waits for approval or a superseded commit shows as pending. A token never shows those two as green.
+
+These status writes are templated, so auto-review skips them. They still follow the `check_run` rule. Only `act` writes them. Under `ask`, `act_when_asked`, or `hand_off` the check shows up with the final report only, and no status draft waits in the Inbox. In PAT mode each state is a pending commit status under the `localdost` context. In demo mode (no GitHub connection) nothing is written.
+
+The job also publishes a `picked_up` live event, see [API-V2.md](API-V2.md#live-test-runs), and sends a low-urgency push when no app is open. The push follows the `push_notify` rule.
+
+## Fork pull requests
+
+A PR check on a fork PR would clone and run code from someone outside your repo. localdost skips the test run for a fork PR unless the dot sets `runner.trustForks: true`, and the PR comment says "Tests did not run: this PR comes from a fork. Ask a maintainer to check it again." The PR review still runs, because it only reads files. Details: [SANDBOX.md](SANDBOX.md#fork-safety).

package/docs/INTEGRATION-MODEL.md

@@ -0,0 +1,200 @@
+# Integration model
+
+localdost works next to the test tools a team already has: Xray in Jira, TestRail, Katalon True Platform, and Linear for tickets. Think of a new teammate who joins a team that already keeps its tests somewhere. First they read what exists and learn where everything lives, then they keep both places in step, and they always tell the person in charge what they changed. This document says how localdost brings existing tests in, keeps them in sync both ways, and works as an agent beside people, based on how Linear syncs with Jira and how Atlassian put agents into Jira.
+
+It builds on the test management model in [DATA-MODEL.md](DATA-MODEL.md): folders, case versions, suites, plans, test runs, run items, results and step results. Facts about Linear and Atlassian were gathered on 2026-10-10; sources are at the end.
+
+## What Linear does
+
+**Import and sync are two separate tools.** The Jira importer brings history in once: issues, comments, labels, estimates, due dates, statuses, parent and sub-issue links, epics (as Linear projects) and images. The sync carries changes forward. Linear's advice is to turn on the sync first, then import history, then let the sync continue. Existing Jira issues join the sync only when they next change in Jira.
+
+**One container maps to one container.** A Jira space links to one Linear team. Several Jira spaces can feed one team. Each link chooses a direction:
+
+- One-way: items created in Jira appear in Linear, updates flow both ways, and items created in Linear stay in Linear.
+- Two-way: an item created on either side gets a copy on the other.
+
+**Only core fields sync.** Title, description, assignee, creator, priority, status, labels and due date sync. Custom fields do not transfer. Jira issue types become labels, and components become labels named "Component: X". New items created from Linear become the Jira type Task.
+
+**People are matched by email.** A Jira user with no Linear match becomes an external author, who can write issues and comments but cannot be an assignee. For the sync, each person connects their own Jira account so their changes carry their name.
+
+**Mismatches are left alone.** If a Jira status has no Linear equivalent, the Linear status does not change. Teams point unmapped work at a Triage state. If a Linear edit breaks a Jira rule, Linear keeps the edit and Jira does not change. Deleting a synced item on one side never deletes it on the other.
+
+**Comments become one shared thread.** Linear uses the same pattern for GitHub Issues, Slack threads and Asks: link a container, choose a direction, sync core fields, share one comment thread, and land new work in Triage.
+
+**Agents are delegates, not owners.** An agent is a workspace user that people assign or mention. When an issue is delegated to an agent, Linear sets a separate `delegate` field. The human assignee keeps ownership, and the issue stays in that person's My issues. Each piece of agent work is a session with a state: pending, active, awaiting input, error, complete or stale. The agent reports through activities:
+
+- a thought (what it is doing),
+- an action (a tool call and its result),
+- an elicitation (a question for the person),
+- a response (the outcome),
+- an error.
+
+A session can carry a plan, a checklist of steps. The agent must acknowledge within 10 seconds or Linear marks it unresponsive. Linear's interaction guidelines require five things:
+
+- the agent says it is an agent,
+- it uses the same actions a person would,
+- it shows its state,
+- it stops at once when asked,
+- final responsibility stays with a human.
+
+## What Atlassian does
+
+**Agents sit in the assignee field next to people** (agents in Jira, open beta February 2026, generally available May 2026). A person engages an agent in four ways:
+
+- picks it on the work item,
+- mentions it in a comment,
+- moves the item into a workflow status that an admin set to trigger the agent,
+- drops the item into a board column set up for the agent.
+
+**Agent output is private until a person shares it.** Results appear in an Agents section on the work item for the person who started the agent, and that person decides whether to publish them as a comment or attachment. Everyone with access can see that an agent ran. Approved updates land in the item history.
+
+**Agents act with existing permissions and leave a trail.** Every action is logged on the work item. Admins get an inventory of agents, separate permissions for using and for building agents, and credit dashboards. Atlassian publishes no separate reject or approval gate. Review happens through the private output and the choice to publish.
+
+**Outside agents connect over open standards.** The Forge module `rovo:agentConnector` puts a remote agent into Jira over Agent2Agent (A2A 1.0, JSON-RPC, streaming). People can then assign it work items, mention it, or chat with it. GitHub Copilot, Cursor and Claude Code are among the agents named. The Atlassian remote MCP server (generally available, OAuth 2.1) lets any MCP client read and write Jira with the user's permissions.
+
+**Test tools in Jira store tests differently.**
+
+- Xray adds the Jira issue types Test, Precondition, Test Set, Test Plan and Test Execution. A Test Run, one test inside one execution, lives inside Xray rather than as a Jira issue. Results import as JUnit or Xray JSON into a new or existing Test Execution.
+- In Zephyr Scale, adding a case to a cycle creates an execution, so a case in 10 cycles has 10 executions.
+
+## How localdost brings tests in
+
+Linear does not ask people to design a mapping. Its Jira mapping is built in: a person connects, authorises, and picks the Jira space and the Linear team, and the import and mapping run in the background. localdost does the same. Each tool has one built-in mapping, and a team never maps fields by hand.
+
+1. **Connect:** OAuth where the tool has it (Jira and Xray Cloud through Atlassian, Linear), an API token where it does not (TestRail, True Platform). The token is stored like every other connection and is scoped to read and write tests.
+2. **Pick the container:** the dot lists what the token can see (projects, suites, repositories) and the person picks one.
+3. **Import in the background:** localdost pulls history through the tool's REST API with the built-in mapping below, and shows progress on the dot page.
+4. **Check the summary:** for example, "412 cases in 18 folders, 3 suites, 40 test runs imported. 3 statuses and 2 users need a choice." The few exceptions it lists can be adjusted, and the rest needs nothing.
+
+| Tool | Container linked to a dot | Becomes in localdost |
+|---|---|---|
+| Xray | Jira project, optionally a test repository folder | folders, cases, suites (Test Sets), plans, test runs (Test Executions) |
+| TestRail | project and suite | folders (sections), cases, plans, test runs, run items (tests), results |
+| True Platform | project and test repository | folders, cases (with versions), suites, test runs, results |
+| Linear or Jira (tickets) | team or space | requirements and acceptance criteria |
+
+**What the built-in mapping does with each record:**
+
+- **External references:** each imported record keeps the tool, remote id, remote key, URL, remote revision and last-synced time.
+- **Folders:** keep their tree.
+- **Custom fields:** go into a read-only `external.fields` bag. They show on the case but never sync, which is the same rule as Linear.
+- **People:** a person with no email match becomes an external author.
+- **Existing local cases:** an incoming case matches by external key first, then by title and steps, so a case is never duplicated.
+- **Records the import missed:** join the sync when they next change on the remote side, as in Linear.
+
+## How changes move between the tools
+
+| Path | Transport | Why |
+|---|---|---|
+| Tool to localdost, as changes happen | webhooks: Jira (covers Xray's Test, Test Set, Test Plan and Test Execution issues) and Linear | changes arrive in seconds without polling |
+| Tool to localdost, everything else | polling with a cursor ("changed since"), for objects or tools without webhooks, and as a catch-up after downtime | nothing is missed; Xray Test Runs are not Jira issues, so they need polling |
+| localdost to the tool | the tool's REST API, with the authorised token | writes are exact, typed and carry the echo marker |
+| A dot doing its own work (look up a case, comment, move a status on request) | the tool's MCP server where one exists (Atlassian remote MCP, Katalon MCP) | the agent acts with the user's permissions; MCP is request and response, so it is not the sync backbone |
+
+To confirm per tool before building: whether TestRail and True Platform send webhooks, and what changed-since filters their APIs offer. Until that is known, polling is the default for both.
+
+## How two-way sync works
+
+**Every field has one owner, chosen when the link is made.** localdost does not settle conflicts by whichever edit came last:
+
+| Data | Default owner | Other direction |
+|---|---|---|
+| Case title, steps, expected results, preconditions | the tool, for imported cases; localdost, for cases the dots design | the non-owner's edit becomes a proposal |
+| Folders and suites | the tool | proposal |
+| Test runs that localdost creates (from a PR, a merge, or a person) | localdost | pushed to the tool as a Test Execution or run |
+| Results and step results that localdost produces | localdost | pushed; never pulled back over |
+| Results a person records in the tool | the tool | pulled into the matching run item as a new attempt |
+| Defects that localdost files | localdost at create, then the tracker for status and resolution | pulled |
+
+**Edits by the non-owner become proposals.** If Xray changes the steps of a case that a dot designed, or a dot wants to change a case owned in TestRail, localdost makes a draft in the Inbox: "TestRail changed steps of Checkout total, apply here?" A person approves or rejects it. This is the same gate as every other outward write in localdost (act, ask or hand off).
+
+**Statuses map per tool, and an unmapped status is flagged.** As in Linear, a remote status with no mapping leaves the local status alone. The item gets a "needs mapping" note on the sync page, so it never lands in a wrong state.
+
+**Sync never loops.** Every write carries the localdost bot marker and records the remote revision or etag it produced. An incoming change whose revision matches a write of our own is an echo and is ignored.
+
+**Deletes never travel.** A delete on either side archives the link and leaves a note, as in Linear.
+
+**Every record keeps a sync log.** It holds the last pull, the last push, the last error and any open proposal. Failed writes retry with backoff, the same retry approved actions use, and show "Retrying, attempt N".
+
+## How dots work with and beside people
+
+**A dot is a delegate. A person stays the owner.** A dot works on an item on someone's behalf, in Linear's `delegate` sense. The human owner stays accountable and still sees the item as theirs. When a tool has only one assignee field, as in Jira, the dot is the assignee and the person who triggered it is recorded as its owner.
+
+**People engage a dot the way the tools allow.**
+
+- They assign or delegate an item to it.
+- They mention it in a comment.
+- They move an item into a status or board column that is set up for it.
+- Inside localdost, they ask in chat, push a PR, or create a ticket.
+
+**Each job is a session, and the dot narrates it.** A session has a state: working, waiting for you, error or done. The dot posts activities as it works: thoughts, actions with results, questions, the final response and errors. A session can carry a plan checklist. The dot acknowledges within 10 seconds. localdost run steps already work this way. Each tool shows the same session in its own form:
+
+- Linear: agent activities,
+- Jira: the Agents section,
+- localdost: the run page.
+
+**Outward writes wait for a person unless a rule allows them.** This is the approval gate Atlassian does not publish. A draft is visible to the person who started the work until it is approved, which matches Atlassian's private output. The dot's rules then decide what may post on its own.
+
+**A dot discloses itself and stops when asked.**
+
+- Every write carries the dot's name and the bot marker.
+- "Stop" or "Hand off" ends the session at once.
+- The dot resumes only when a person says so.
+
+**A dot acts with scoped permissions and leaves an audit trail.** It acts with the connection's token, limited to what the dot needs. A paired member can approve, reject and pause, an editor can also change a dot but not the commands it runs on the server, and neither can archive, restore, or delete it. The audit table records every write with the actor and the before and after.
+
+## Where a dot appears in each tool
+
+| Tool | How the dot shows up | How a person engages it | How results go back |
+|---|---|---|---|
+| Linear | an agent app (OAuth actor app, assignable and mentionable) with sessions and activities | delegate the issue, or mention it | session activities, plan checklist, a comment with the QA review |
+| Jira with Rovo | a remote agent through `rovo:agentConnector` (A2A) | assign the work item, mention it, workflow status or board column | Agents section output that the person publishes; comments and field updates through the Atlassian MCP server |
+| Xray | through the Jira agent above | as above | results into a Test Execution: one Test Run per case, with step statuses, evidence and defects |
+| TestRail | no agent surface: the dot is an API user | from localdost or the linked ticket | runs, tests and results with step results and attachments |
+| True Platform | the Katalon MCP server and the report uploader | from localdost or the linked ticket | test runs and results; JUnit or Playwright reports first, then case and result mapping |
+
+## Build order
+
+1. **Connect and background import with the built-in mapping,** external references and the sync log, with True Platform first, then Xray, then TestRail.
+2. **Result push:** each automated or manual localdost test run goes into the tool's execution object.
+3. **Two-way case sync** with field owners, proposals in the Inbox, status mapping and echo protection.
+4. **Agent surfaces:** the Linear agent app (the Linear agent epic, KAT-213), then the Jira remote agent over A2A.
+
+## Sources
+
+Linear (pages undated unless noted):
+
+- [Jira importer](https://linear.app/docs/jira-to-linear)
+- [Jira integration and sync](https://linear.app/docs/jira)
+- [Jira sync launch (2023-12-20)](https://linear.app/changelog/2023-12-20-jira-sync)
+- [GitHub Issues sync](https://linear.app/docs/github-to-linear)
+- [Linear Asks](https://linear.app/docs/linear-asks)
+- [Slack](https://linear.app/docs/slack)
+- [Linear for Agents (2025-05-20)](https://linear.app/changelog/2025-05-20-linear-for-agents)
+- [Agents in Linear](https://linear.app/docs/agents-in-linear)
+- [Assigning and delegating issues](https://linear.app/docs/assigning-issues)
+- [Agent developer docs](https://linear.app/developers/agents)
+- [Agent interaction](https://linear.app/developers/agent-interaction)
+- [Agent Interaction Guidelines (2025-07-30)](https://linear.app/developers/aig)
+
+Atlassian:
+
+- [AI agents in Jira (2026-02-25)](https://www.atlassian.com/blog/rovo/ai-agents-in-jira)
+- [A new kind of teammate (2026-06-18)](https://www.atlassian.com/blog/ai-at-work/your-jira-board-just-got-a-new-kind-of-teammate)
+- [Collaborate on work items with AI agents](https://support.atlassian.com/jira-software-cloud/docs/collaborate-on-work-items-with-ai-agents/)
+- [Forge rovo:agentConnector](https://developer.atlassian.com/platform/forge/manifest-reference/modules/rovo-agent-connector/)
+- [Rovo A2A](https://developer.atlassian.com/cloud/rovo-a2a/)
+- [Atlassian remote MCP server](https://support.atlassian.com/rovo/docs/getting-started-with-the-atlassian-remote-mcp-server/)
+- [Team '26 coverage (2026-05-06)](https://siliconangle.com/2026/05/06/atlassian-opens-teamwork-graph-pushes-rovo-agentic-execution-team-26)
+
+Test tools:
+
+- [Xray issue types](https://www.atlassian.com/devops/testing-tutorials/jira-xray-integration-manage-test-cases)
+- [Xray result import](https://docs.getxray.app/display/XRAYCLOUD/Import+Execution+Results+-+REST+v2)
+- [Zephyr Scale test cycles](https://support.smartbear.com/zephyr-scale-cloud/docs/en/test-cycles/test-cycles--overview-.html)
+
+Not confirmed at the source:
+
+- Linear: how comments and attachments sync with Jira, the status-mapping UI, and manual linking of existing items.
+- Atlassian: who owns an item that an agent is assigned to.
+- Xray: whether a Test Run is a Jira issue.