tinybeeai 0.0.0-stage → 0.16.1

package/.railway/railway.ts

@@ -0,0 +1,83 @@
+// Railway Infrastructure as Code for localdost. Preview with `railway config plan`, then run
+// `railway config apply --yes`. docs/DEPLOY.md has the full recipe. The project is `localdost`
+// (workspace "Huy Dao's Projects", next to `superapp`); both services below live in it.
+//
+// There is no build target here. Railway builds the root Dockerfile, and its last stage is the
+// `runner` target (Playwright image with browsers), so hosted test runs work.
+// No `source` either: `railway up` or a GitHub link supplies the code.
+import { defineRailway, preserve, project, service, volume } from 'railway/iac';
+
+export default defineRailway(() => {
+  // SQLite, VAPID keys, saved credentials, and run artifacts live here.
+  const data = volume('qadots-data', { sizeMB: 5120 });
+
+  const qadots = service('qadots', {
+    start: 'node dist/index.js',
+    healthcheck: '/',
+    healthcheckTimeout: 60,
+    // SQLite needs exactly one replica.
+    replicas: 1,
+    deploy: {
+      // Refuse to start without the volume, so a missing mount cannot silently write to the container disk.
+      requiredMountPath: '/data',
+      // Restart a crashed server a few times, then stop and show the failure instead of looping.
+      restartPolicyType: 'ON_FAILURE',
+      restartPolicyMaxRetries: 5,
+      // Seconds the old instance gets to finish SQLite writes after SIGTERM.
+      drainingSeconds: 10,
+    },
+    env: {
+      HOST: '0.0.0.0',
+      PORT: '4319',
+      QADOTS_DATA_DIR: '/data',
+      QADOTS_POLL: '1',
+      QADOTS_LLM: 'anthropic',
+      // Railway mounts volumes as root. The container starts as root, and its entrypoint gives /data
+      // to the qadots user and drops to it before the server starts (KAT-209).
+      RAILWAY_RUN_UID: '0',
+      // Secrets are set with `railway variable set NAME --stdin`; apply keeps the stored value.
+      QADOTS_TOKEN: preserve(),
+      GITHUB_TOKEN: preserve(),
+      ANTHROPIC_API_KEY: preserve(),
+      LINEAR_API_KEY: preserve(),
+      // TinyBee: this service is the staging Bee (`bee-dev`). The Hive URL is the private address of the hive service.
+      TINYBEE_ENV: 'staging',
+      TINYBEE_HIVE_URL: 'http://hive.railway.internal:4330',
+    },
+    volumeMounts: { '/data': data },
+  });
+
+  // TinyBee (docs/tinybee/06-environments-and-delivery.md section 1.1). The `qadots` service above doubles as
+  // `bee-dev`, the cloud-hosted Bee of tenant `dev`; the Hive control plane is a service of its own. The PWA
+  // reaches Hive through the Bee's /api/hive proxy (TINYBEE_HIVE_URL), so one origin serves both.
+  const hiveData = volume('hive-data', { sizeMB: 1024 });
+  const hive = service('hive', {
+    start: 'node dist/hive/index.js',
+    healthcheck: '/api/hive/health',
+    healthcheckTimeout: 60,
+    replicas: 1,
+    deploy: {
+      requiredMountPath: '/data',
+      restartPolicyType: 'ON_FAILURE',
+      restartPolicyMaxRetries: 5,
+      drainingSeconds: 10,
+    },
+    env: {
+      HOST: '0.0.0.0',
+      PORT: '4330',
+      TINYBEE_ENV: 'staging',
+      TINYBEE_TENANT_HOST: 'dots-{slug}.testllms.com',
+      HIVE_DATA_DIR: '/data',
+      RAILWAY_RUN_UID: '0',
+      // Set with `railway variable set NAME --stdin --service hive`. Unset CF_* keeps the mock tunnel provider.
+      HIVE_JWT_PRIVATE_KEY: preserve(),
+      HIVE_JWT_KID: preserve(),
+      CF_ACCOUNT_ID: preserve(),
+      CF_ZONE_ID: preserve(),
+      CF_API_TOKEN: preserve(),
+    },
+    volumeMounts: { '/data': hiveData },
+  });
+
+  return project('localdost', { resources: [data, qadots, hiveData, hive] });
+});

package/.railway/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "target": "ES2023",
+    "lib": ["ES2023"],
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": []
+  },
+  "include": ["railway.ts"]
+}

package/AGENTS.md

@@ -0,0 +1,102 @@
+# Set up localdost for a repo
+
+These are the steps a coding agent follows when a person asks it to set up localdost for their repo, and to host it when they ask for that. Run each step, read its output, and fix what it reports before the next step. The person's repo is the "target repo" below. localdost itself lives in a separate checkout.
+
+## Safety rules
+
+- Never ask the person to paste a token, key, or password into the chat. When a step needs a secret, ask them to export it in their own shell, or to run the login command themselves.
+- Never print a secret. Do not run `printenv` or `env` without a variable name, `railway variable list --kv`, or `gh auth token` on its own. Pipe a secret straight into the command that needs it (`gh auth token | railway variable set GITHUB_TOKEN --stdin --service localdost`).
+- Never write a secret into a file. `.env.localdost` holds only references: `${env:NAME}` reads the person's shell, `${cmd:gh auth token}` runs a command at start. Keep it that way.
+- Never commit `.env.localdost` or `.localdost/data/`. `localdost init` adds both to `.gitignore`. `.localdost/config.json` holds no secrets and is safe to commit.
+- Set `LOCALDOST_TOKEN` before the server is reachable from the internet (a tunnel, a cloud host). Without it the API has no auth.
+- Leave the dot's rules at their defaults. Ticket comments ask first. Change a rule to `act` only when the person asks for it.
+- Logins open a browser: `gh auth login`, `claude auth login`, `railway login`. Ask the person to run them, then continue.
+
+## Steps
+
+### 1. Install localdost
+
+localdost needs Node 24. If `~/localdost` does not exist, clone and build it once, then put the `localdost` command on the PATH:
+
+```bash
+git clone https://github.com/duonghaijoe/localdost ~/localdost
+cd ~/localdost
+npm ci
+npm run build
+npm link
+```
+
+When `npm link` is not allowed, use `node ~/localdost/bin/localdost.js` wherever this file says `localdost`.
+
+### 2. Init in the target repo
+
+```bash
+cd <target repo>
+localdost init --yes
+```
+
+`init` reads the GitHub repo and default branch from `git remote get-url origin`, the test command and Playwright config from `package.json`, checks `gh auth token`, checks the Claude CLI login with a `claude -p` round trip (else uses `ANTHROPIC_API_KEY` from the shell), and picks Linear or Jira when `LINEAR_API_KEY` or `JIRA_*` is exported. It writes `.env.localdost` and `.localdost/config.json`, and creates the first dot in `.localdost/data/`. Running it again updates the same dot.
+
+Pass flags for what it cannot detect:
+
+| Need | Flag |
+|---|---|
+| Linear team | `--tracker linear --linear-team ENG` |
+| Jira project | `--tracker jira --jira-url https://acme.atlassian.net --jira-project SHOP` |
+| GitHub Issues | `--tracker github`, with `--tracker-repos owner/name` for the repo whose issues the dot reviews and where it files defects, `--require-labels pod:agentic` to review only issues with that label, and `--milestone 2026.11` |
+| No tracker | `--tracker none` |
+| A test command other than `npx playwright test` | `--command "npx playwright test --project=chromium"` |
+| The app URL the tests run against | `--base-url http://localhost:3000` |
+| A fixed port | `--port 4319` (default: 4319, or the next free port) |
+
+The test command runs without a shell, so `&&` and pipes do not work in it. Put install and build steps in the dot's Setup steps (`runner.setup`), for example `npm ci && npx playwright install chromium && npm run build`, and use **Try it** in the dot dialog to check both.
+
+### 3. Doctor
+
+```bash
+localdost doctor
+```
+
+It prints one line per service. `FAIL` lines carry a `fix:` command. Run each fix, or ask the person to run it when it is a login or needs a key, then run `localdost doctor` again. Repeat until it exits 0. `warn` lines are optional services (Slack, voice, Docker, a public URL) and do not block. `localdost doctor --json` gives the same checks as JSON.
+
+### 4. Start
+
+```bash
+localdost start
+```
+
+Run it in the background. It loads `.env.localdost`, resolves the references, and serves the app on `http://localhost:<PORT>`. Check that `curl -s http://localhost:<PORT>/api/dots` lists the dot. GitHub and the tracker are polled every 60 seconds, so no webhook is needed. The first poll of a new dot takes its 5 most recently updated open PRs, and their PR comment and check wait for approval unless the repo's PR scope names authors, a team or issue labels; after that, only new work.
+
+### 5. Deploy, only when the person asks to host it
+
+Skip this step unless the person asked to host or deploy localdost (for example "and host it on Railway"). Do not create cloud projects, services, or volumes on your own. When they did ask, follow the Railway section of `~/localdost/docs/DEPLOY.md`. It needs Railway CLI 5.42.1 or newer (`railway --version`). Run from `~/localdost`:
+
+```bash
+cd ~/localdost
+railway login                      # the person runs this one, it opens a browser
+railway init --name localdost
+railway config plan                # preview what .railway/railway.ts creates
+railway config apply --yes         # service, 5 GB volume at /data, non-secret variables
+
+# Secrets from stdin, never printed. Set only the ones the person has.
+openssl rand -hex 24 | railway variable set LOCALDOST_TOKEN --stdin --skip-deploys --service localdost
+gh auth token | railway variable set GITHUB_TOKEN --stdin --skip-deploys --service localdost
+printenv ANTHROPIC_API_KEY | railway variable set ANTHROPIC_API_KEY --stdin --skip-deploys --service localdost
+printenv LINEAR_API_KEY | railway variable set LINEAR_API_KEY --stdin --skip-deploys --service localdost
+
+railway up --detach --service localdost
+railway domain --port 4319 --service localdost
+```
+
+Then create the dot on the hosted server with the domain `railway domain` printed:
+
+```bash
+railway run --service localdost node bin/localdost.js init --yes --dir <target repo> --server https://<railway domain>
+railway run --service localdost node bin/localdost.js doctor --dir <target repo>
+```
+
+Test runs work on Railway: the default image is the `runner` target with browsers, and the first run of each cloned repo installs its dependencies. The real limits are memory and disk. Chromium needs at least 2 GB of RAM, and the volume is 5 GB. Tell the person both.
+
+## Done
+
+Tell the person, in a few lines: the URL, the dot name, the doctor result, and any `warn` line they may want to fix. Do not include any secret value.

package/Dockerfile

@@ -0,0 +1,108 @@
+# syntax=docker/dockerfile:1
+#
+# localdost image. Two targets:
+#   app     Node 24 slim. Serves the API and the PWA. No browsers, so demo and local
+#           Playwright runs need either the runner target or docker runner mode.
+#   runner  The same app on the pinned Playwright image, so local and demo runs have
+#           Chromium, Firefox, and WebKit installed. It is the last stage, so a plain
+#           `docker build` and Railway (which builds the last stage) produce it.
+#
+#   docker build --target app -t qadots:app .
+#   docker build --target runner -t qadots:runner .
+#
+# Keep runner last. Reordering the stages changes what Railway deploys (test/runner-default-install.test.ts).
+#
+# PLAYWRIGHT_VERSION must match node_modules/@playwright/test. A mismatch fails at run
+# time with "Executable doesn't exist". Renovate bumps both together (renovate.json).
+
+ARG NODE_VERSION=24
+ARG PLAYWRIGHT_VERSION=1.63.0
+
+# All dependencies, for the build and for the runner target.
+FROM node:${NODE_VERSION}-bookworm-slim AS deps
+WORKDIR /app
+ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+COPY package.json package-lock.json .npmrc ./
+RUN npm ci --no-audit --no-fund
+
+# Server (tsc to dist/) and client (vite to dist/web).
+FROM deps AS build
+COPY tsconfig.json tsconfig.client.json vite.config.ts ./
+COPY src ./src
+COPY client ./client
+COPY scripts/copy-assets.mjs ./scripts/
+RUN npx tsc -p tsconfig.json && node scripts/copy-assets.mjs && npx vite build
+
+# Production dependencies only, for the app target.
+FROM node:${NODE_VERSION}-bookworm-slim AS prod-deps
+WORKDIR /app
+ENV PLAYWRIGHT_SKIP_BROWSER_DOWNLOAD=1
+COPY package.json package-lock.json .npmrc ./
+RUN npm ci --omit=dev --no-audit --no-fund
+
+# App target. LOCALDOST_DATA_DIR holds the SQLite database, VAPID keys, and artifacts.
+FROM node:${NODE_VERSION}-bookworm-slim AS app
+# HOST=0.0.0.0 needs LOCALDOST_TOKEN: without a token the server refuses a non-loopback address.
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT=4319 \
+    LOCALDOST_DATA_DIR=/data
+# git: GitHub checkouts for local runs. tini: reaps Playwright and git child processes.
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates git tini \
+ && rm -rf /var/lib/apt/lists/*
+WORKDIR /app
+COPY --from=prod-deps --chown=root:root /app/node_modules ./node_modules
+COPY --from=build --chown=root:root /app/dist ./dist
+COPY --chown=root:root package.json ./
+# demo/ holds the sample shop and payloads for LOCALDOST_DEMO=1. The client is in dist/web.
+COPY --chown=root:root demo ./demo
+# Guides for the in-app docs viewer (#/docs).
+COPY --chown=root:root docs ./docs
+COPY --chown=root:root README.md ./
+RUN mkdir -p /data && chown node:node /data
+USER node
+# /data is the volume (compose.yml and docs/DEPLOY.md mount it). No VOLUME line: Railway's builder refuses it.
+EXPOSE 4319
+# /api/setup sits behind the bearer token when LOCALDOST_TOKEN is set, so the probe sends it.
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||4319)+'/api/setup',{headers:process.env.LOCALDOST_TOKEN?{authorization:'Bearer '+process.env.LOCALDOST_TOKEN}:{}}).then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+ENTRYPOINT ["/usr/bin/tini", "--"]
+CMD ["node", "dist/index.js"]
+
+# Runner target, and the default because it is the last stage. Railway builds the last stage.
+# The Playwright v1.63 noble image ships Node 24 and the browsers in /ms-playwright.
+FROM mcr.microsoft.com/playwright:v${PLAYWRIGHT_VERSION}-noble AS runner
+# HOST=0.0.0.0 needs LOCALDOST_TOKEN: without a token the server refuses a non-loopback address.
+ENV NODE_ENV=production \
+    HOST=0.0.0.0 \
+    PORT=4319 \
+    LOCALDOST_DATA_DIR=/data \
+    PLAYWRIGHT_BROWSERS_PATH=/ms-playwright
+RUN apt-get update \
+ && apt-get install -y --no-install-recommends ca-certificates git tini \
+ && rm -rf /var/lib/apt/lists/*
+# The server and the test runs it spawns run as qadots, which owns /app and /data. The browsers in
+# /ms-playwright stay owned by root and are made readable by every user.
+RUN useradd --system --create-home --home-dir /home/qadots --uid 10001 --shell /usr/sbin/nologin qadots \
+ && mkdir -p /app /data \
+ && chown qadots:qadots /app /data \
+ && chmod -R a+rX /ms-playwright
+WORKDIR /app
+# Full node_modules: the runner spawns `npx playwright test`, and generated specs import @playwright/test from here.
+COPY --from=deps --chown=qadots:qadots /app/node_modules ./node_modules
+COPY --from=build --chown=qadots:qadots /app/dist ./dist
+COPY --chown=qadots:qadots package.json ./
+COPY --chown=qadots:qadots demo ./demo
+# Guides for the in-app docs viewer (#/docs).
+COPY --chown=qadots:qadots docs ./docs
+COPY --chown=qadots:qadots README.md ./
+# Railway mounts the volume as root and starts the container as root (RAILWAY_RUN_UID=0). The
+# entrypoint then hands /data to qadots and drops to that user. Docker and Compose start as qadots.
+COPY --chmod=0755 scripts/docker-entrypoint.sh /usr/local/bin/qadots-entrypoint
+USER qadots
+EXPOSE 4319
+HEALTHCHECK --interval=30s --timeout=5s --start-period=20s --retries=3 \
+  CMD ["node", "-e", "fetch('http://127.0.0.1:'+(process.env.PORT||4319)+'/api/setup',{headers:process.env.LOCALDOST_TOKEN?{authorization:'Bearer '+process.env.LOCALDOST_TOKEN}:{}}).then(r=>process.exit(r.ok?0:1),()=>process.exit(1))"]
+ENTRYPOINT ["/usr/bin/tini", "--", "/usr/local/bin/qadots-entrypoint"]
+CMD ["node", "dist/index.js"]

package/LICENSE

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

package/README.md

@@ -1,3 +1,276 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# localdost
+
+### Always-on QA agents that watch every merge, ticket, and prod URL
+
+[Get started](#get-started) · [Overview](#overview) · [Architecture](#architecture) · [Features](#features) · [Docs](#docs) · [Contributing](#contributing)
+
+[![CI](https://github.com/duonghaijoe/localdost/actions/workflows/ci.yml/badge.svg)](https://github.com/duonghaijoe/localdost/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Status: alpha](https://img.shields.io/badge/status-alpha-orange.svg)](#features)
+
+Self-hosted. Runs with no accounts in demo mode. Bring your own Claude login or Anthropic key for real verdicts.
+
+</div>
+
+![localdost catching a checkout bug on a real PR, merge and phone alert](docs/demos/hero.gif)
+
+<sub>Real runs on a demo shop, sped up and trimmed as captioned. Full walkthrough: [localdost-walkthrough.mp4](docs/demos/localdost-walkthrough.mp4). Recording notes: [docs/demos](docs/demos/README.md).</sub>
+
+## Overview
+
+localdost gives your team a few QA helpers that never sleep. Each helper is a **dot**. A dot reads every pull request, every merge, every new ticket, and your health checks, runs your tests, and tells you on your phone when something needs you. Think of a colleague who reads every PR and every new Jira ticket, and texts you only when checkout breaks.
+
+Every outward action, such as a PR comment, a check run, or a ticket comment, passes a rule gate first. You decide per action kind whether the dot acts, acts only when asked, asks first, or hands the job to you. Approvals wait in the Inbox of the phone app.
+
+localdost is one Node process and one SQLite file on your machine or your server. Without credentials, every integration runs in demo mode: outward actions go to an outbox that you can read in the app, and a mock model writes canned verdicts.
+
+### Dots and Watches
+
+A dot holds one **Watch**: a GitHub repo, a Jira or Linear project, the production URLs it is responsible for, and a test command. The Watch also carries the dot's mission, when to notify you, and what it must never do, in your own words. Role presets (product area, QA lead, release guard, ticket reviewer, prod watcher) fill in the mission and the rules for a common job and switch on the stages it needs. One server runs many dots, and each dot has its own memory, rules, and chat.
+
+### PR review with what to test
+
+On every PR and every merge, the dot scopes the changed lines, maps them to impact areas, collects signals (untouched tests, removed assertions, changed routes, selector drift), and applies ten QA lenses such as money, auth, dates, and migrations. A reviewer model pass and a verifier model pass then produce risks with code citations and a **What to test** checklist. The review lands in one sticky PR comment and in a check run with line annotations. Ticking a checklist item in the comment records a manual test result on the run. Details: [docs/PR-REVIEW.md](docs/PR-REVIEW.md).
+
+![PR review: specs run live, the review flags a double discount, the sticky comment on GitHub](docs/demos/pr-review.gif)
+
+### Live test runs
+
+After a merge, the dot picks the Playwright specs that match the changed paths plus your smoke tests, runs them, and retries failures to separate flaky tests from real breaks. The run page streams each step live, shows browser frames during the run, and keeps screenshots, traces, videos, and the JSON report. Runs execute in your checkout, in a Docker container, or against the bundled sample shop. Details: [docs/SANDBOX.md](docs/SANDBOX.md).
+
+![After a merge: the full suite, retries, and the failing spec opened from the push](docs/demos/merge-alert.gif)
+
+### AI-Vision cases
+
+A dot can also run natural-language browser cases next to Playwright, on an AI-Vision server (Veesan) or the open-source Midscene CLI. Each What to test item from the PR review that has no existing test becomes one case, and test ideas from a ticket review of a ticket the PR names fill the rest. The cases run on `pr_check` and `post_merge`, and their verdicts, screenshots, and report links merge into the same run and checklist as the Playwright results. Details: [docs/SANDBOX.md](docs/SANDBOX.md#ai-vision-cases).
+
+### Ticket review
+
+A new Jira or Linear ticket gets a score for how ready it is. Tickets that score 30 or more get a review: risks, open questions, gaps in the acceptance criteria, test ideas, and existing tests that the change may break. The dot drafts a ticket comment, and by default the draft waits in your Inbox. It also checks the test cases and automated specs you already have, from any ticket, that the new ticket changes: a case that needs an update gets a draft version, a case the ticket makes obsolete gets a retire draft in your Inbox, and nothing is changed until you decide. Details: [docs/TRACKERS.md](docs/TRACKERS.md).
+
+![Ticket review: the draft is edited and approved in the Inbox, then read back from Linear](docs/demos/ticket-approval.gif)
+
+### Outage watch
+
+HTTP probes and browser probes check your production URLs on an interval. Three failures in a row open an outage: the dot looks at merges from the last 24 hours, names a suspected cause, and pushes a high-urgency alert. A recovery notice follows when the probe passes again. Atlassian Statuspage URLs of your vendors feed the same flow. A daily digest sums up runs, flaky specs, tickets, and incidents.
+
+### Ask-first rules and the Inbox
+
+Each action kind has one of four levels: `act`, `act_when_asked`, `ask`, or `hand_off`. The defaults let a dot run tests, post PR comments and check runs, and send pushes on its own. Ticket comments, new issues, MCP tools that change data, and report edits ask first. Reverts go to a person. An auto-review pass can move an `act` to `ask` when a draft looks risky. In the Inbox you approve, edit, or reject the exact draft. A pending approval expires after 24 hours.
+
+### Phone app with chat and calls
+
+The app is a React PWA that you add to your Home Screen. It has Dots, Feed, Inbox, Chat, Reports, and Settings. Chat with a dot about its runs, ask it to rerun tests, or ask whether prod is up. Push-to-talk and read-aloud use browser speech. With `OPENAI_API_KEY` set, a call uses OpenAI Realtime over WebRTC instead. Details: [docs/VOICE.md](docs/VOICE.md).
+
+### Slack
+
+Mention the bot in a thread and the dot named in the message, or the dot that owns the channel, answers in the thread. Outage and digest notices post to the dot's channel. Slack connects over Socket Mode, so it needs no public URL. Details: [docs/SLACK.md](docs/SLACK.md).
+
+### MCP connections
+
+Connect any MCP server over HTTP or stdio and attach it to a dot. Read-only tools run directly in chat. A tool that changes data is an outward action and goes through the rule gate like a PR comment. Presets add an AI-Vision server (Veesan) or the open-source Midscene MCP server in one step, with only the env var names they declare, so a dot's chat can find cases, start a run after approval, and read the verdicts. Details: [docs/CONNECTIONS.md](docs/CONNECTIONS.md).
+
+### Reports
+
+Save any run or digest as a report page. Edit it in the app, or chat with the dot about the page and let it propose edits, which ask first by default.
+
+## Architecture
+
+```mermaid
+flowchart LR
+  subgraph Triggers
+    GHW[GitHub webhook]
+    GHP[GitHub poller]
+    TRW[Jira and Linear webhooks]
+    LNP[Linear poller]
+    PRB[HTTP and browser probes]
+    STP[Statuspage poller]
+    SCH[Digest scheduler]
+  end
+  GHW --> NRM[webhooks.ts: verify, normalize, dedupe]
+  GHP --> NRM
+  TRW --> NRM
+  LNP --> NRM
+  NRM --> Q[(SQLite job queue)]
+  PRB --> Q
+  STP --> Q
+  SCH --> Q
+  Q --> FL[Flows: pr_check, post_merge, ci_failure, ticket_review, outage, recovery, digest, rerun]
+  FL --> REV[Review prep: scope, signals, lenses, impact]
+  REV --> LLM[Model backend: claude-cli, codex-cli, anthropic, mock]
+  FL --> LLM
+  FL --> RUN[Test runner: local, docker, demo, AI-Vision]
+  RUN --> ART[(Artifacts in the data folder)]
+  FL --> GATE{Rules gate}
+  GATE -- act --> EXT[GitHub, Jira, Linear, Slack]
+  GATE -- ask --> INB[Inbox approvals]
+  GATE -- no credentials --> OUT[(Outbox)]
+  FL --> PUSH[Web push and ntfy]
+  FL --> BUS[Live event bus]
+  BUS --> SSE[GET /api/live]
+  SSE --> PWA[React PWA]
+  PWA --> CHAT[POST /api/chat]
+  CHAT --> LLM
+  CHAT --> MCP[MCP connections]
+  PWA --> CALL[POST /api/call/session]
+```
+
+Every trigger becomes a `TriggerEvent` with a dedupe key, so a webhook delivery and a poll of the same commit or ticket queue one job. The queue lives in SQLite and runs two jobs at a time. Each running job holds a lease. When the server stops mid-run, the run ends as interrupted and you can rerun it. The server code is in `src/`, the PWA in `client/`, and the build contract in [SPEC.md](SPEC.md).
+
+## Get started
+
+localdost needs Node 24.
+
+### Demo in one command
+
+```bash
+git clone https://github.com/duonghaijoe/localdost && cd localdost && npm install && npm run demo
+```
+
+Open http://localhost:4319. The demo seeds a dot named "Checkout" that watches `demo/shop-web`, Jira project `SHOP`, and a sample shop on http://localhost:4320. In the app, open Settings and press a Simulate button: PR merged, PR opened, ticket created, outage, or CI failure. A simulated merge runs real Playwright tests against the sample shop. One spec passes and one fails on a seeded bug, and the dot reports the failure with a verdict. The same simulations work from a shell:
+
+```bash
+curl -X POST http://localhost:4319/api/simulate/pr_merged
+```
+
+### Start a team server
+
+One person sets a team server up, once. It takes four commands and ends in the setup flow of the app:
+
+```bash
+git clone https://github.com/duonghaijoe/localdost && cd localdost
+npm ci
+npm run build
+LOCALDOST_TOKEN=$(openssl rand -hex 24) LOCALDOST_PUBLIC_URL=https://localdost.example.com npm start
+```
+
+`LOCALDOST_TOKEN` is the token every person needs to open the server. Keep it where you can read it again. `LOCALDOST_PUBLIC_URL` is the https address your team opens, and the address GitHub sends webhooks to. Leave it out and the dot polls GitHub instead, which works but misses CI failures, preview deployments, and `/localdost review` comments. With no preview of a PR, its tests run against the dot's base URL (a build of shared QA work), and the report says so; the dot setting `prTestTarget` can skip those tests instead, see [PR tests without a preview](docs/SETUP.md#pr-tests-without-a-preview). With a token set, `npm start` listens on all interfaces. Put https in front of it, or use a tunnel. [docs/DEPLOY.md](docs/DEPLOY.md) covers Railway, Docker Compose, and a tunnel to your own machine.
+
+Back up the data folder before the pilot starts: the database, `secret.key`, and `vapid.json`. A backup without `secret.key` cannot decrypt the tokens saved in Setup. [Back up and restore](docs/DEPLOY.md#back-up-and-restore) has the commands for Docker Compose, Node with a start script, Railway, and Kubernetes, and `localdost doctor --restore-check <folder>` checks a backup. [Upgrade](docs/DEPLOY.md#upgrade) covers a new tag: pick it, read the CHANGELOG, wait until `localdost doctor --idle` exits 0, back up, switch, and roll back from that backup if needed.
+
+Open the address. A new server shows the Join screen, which also asks **Admin? Enter the server token**: paste `LOCALDOST_TOKEN` and the **setup flow** opens: Welcome (a team server or your laptop, with a check of the token and the public URL), Event delivery, Model, GitHub, Repos with a role and a PR scope each, Tracker (GitHub Issues first), Tests per repo, Slack, Rules with a shadow week, Create dot, and a first review that posts nothing until you say so. A reload keeps you in the flow, and the **Getting started** link in the sidebar brings you back to it until you finish or close it. Each step is described in [docs/SETUP.md](docs/SETUP.md#start-a-team-server).
+
+### Connect your services in the app
+
+Start the server, open the app, and open **Setup**. Each service has a **Connect** button: sign in to the model with your Claude subscription or an Anthropic API key, connect GitHub with the GitHub CLI login, a GitHub App that Setup creates for you, or a token, and paste keys for Linear, Jira, Slack, and voice. **Test** checks each one before you save it. Saved keys are encrypted in the data folder and never sent back to the browser. Environment variables still work and win over saved values. The guides open inside the app: [docs/SETUP.md](docs/SETUP.md).
+
+### Set up with a coding agent in one prompt
+
+Open a coding agent (Claude Code, Codex, Cursor) in the repo you want a dot for, and paste:
+
+```text
+Set up localdost for this repo. Clone https://github.com/duonghaijoe/localdost to ~/localdost if it is not there, then follow ~/localdost/AGENTS.md. Never ask me to paste a secret into the chat: tell me which command to run or which variable to export.
+```
+
+The agent follows [AGENTS.md](AGENTS.md): it builds localdost, runs `localdost init --yes` in your repo, fixes what `localdost doctor` reports, and starts the server. It stops for you at each browser login (`gh auth login`, `claude auth login`). Add "and host it on Railway" to the prompt to deploy it too.
+
+The same steps by hand:
+
+```bash
+cd ~/localdost && npm ci && npm run build && npm link   # once
+cd ~/code/your-repo
+localdost init        # detects the repo, tests, GitHub, Claude, tracker; writes .env.localdost with no secrets
+localdost doctor      # one line per service with a fix command; exits 1 until the required ones work
+localdost start       # http://localhost:4319
+```
+
+`localdost init` turns on poll mode, so GitHub and Linear work without a public webhook URL.
+
+### Docker or Railway
+
+```bash
+LOCALDOST_TOKEN=$(openssl rand -hex 24) docker compose up -d --build
+```
+
+The image listens on all interfaces, so it needs `LOCALDOST_TOKEN` and refuses to start without one. Keep the token in `.env` next to `compose.yml` so you can read it again. Railway, Docker Compose with test runs, and a cloudflared tunnel to your own machine are in [docs/DEPLOY.md](docs/DEPLOY.md).
+
+### Network and token
+
+Without `LOCALDOST_TOKEN`, the server listens on `127.0.0.1` only, whatever the default `HOST` would be. In that state `/api` also answers only requests whose `Host` header names a loopback address, so a tunnel or a DNS-rebinding page gets 403. A non-loopback `HOST` such as `0.0.0.0` without a token stops the server at boot. With a token set and `HOST` unset, the server listens on `0.0.0.0`, and every `/api` call needs `Authorization: Bearer <token>`. Set the token before you open the server to your LAN, a tunnel, or the internet.
+
+### Docs
+
+| Topic | Doc |
+|---|---|
+| The setup flow of a team server, connecting services in the app, every setting, model backends, poll mode, troubleshooting | [docs/SETUP.md](docs/SETUP.md) |
+| GitHub App, PAT, or polling | [docs/GITHUB.md](docs/GITHUB.md) |
+| Jira and Linear | [docs/TRACKERS.md](docs/TRACKERS.md) |
+| Slack | [docs/SLACK.md](docs/SLACK.md) |
+| MCP connections | [docs/CONNECTIONS.md](docs/CONNECTIONS.md) |
+| Test runners, live view, artifacts, fork safety | [docs/SANDBOX.md](docs/SANDBOX.md) |
+| Voice | [docs/VOICE.md](docs/VOICE.md) |
+| PR review for users | [docs/PR-REVIEW.md](docs/PR-REVIEW.md) |
+| Hosting | [docs/DEPLOY.md](docs/DEPLOY.md) |
+| HTTP API | [docs/API-V2.md](docs/API-V2.md) and [SPEC.md](SPEC.md) |
+| PR review design | [docs/PR-REVIEW-QA.md](docs/PR-REVIEW-QA.md) |
+
+## Data and privacy
+
+localdost sends no telemetry. It keeps its state in the data folder (`LOCALDOST_DATA_DIR`, default `data/`, or `.localdost/data` under `localdost start`): the SQLite database, the web push keys, run artifacts, review checkouts, and "Not a risk" eval candidates. Data leaves the machine only for the services you configure:
+
+| Recipient | When | What it receives |
+|---|---|---|
+| Anthropic | `LOCALDOST_LLM=claude-cli` or `anthropic` | Prompts: diffs, PR descriptions, ticket text, test results and log tails, dot memory, chat messages. The PR review masks common secret shapes in diff lines first. The `claude` CLI runs with its built-in tools off; a chat turn attaches only the local localdost chat tools as an MCP server. The PR review starts it with an allowlisted environment. Other calls remove the GitHub, Jira, Linear, ntfy, and push credentials and `LOCALDOST_TOKEN` from its environment |
+| OpenAI | `LOCALDOST_LLM=codex-cli` | The same prompts as the Anthropic row, through the `codex` CLI and your ChatGPT login. The CLI runs read-only, with shell, browser, and plugins off, no MCP server except the local localdost chat tools in a chat turn, and an allowlisted environment |
+| Your AI-Vision server, or the model behind Midscene | `runner.aivision` is set on a dot | Case titles and steps from the PR review and ticket test ideas, the start URL. The engine drives a browser against that URL and sends screenshots to its own model |
+| GitHub, Jira, Linear | Their credentials are set | API reads with your credentials, plus the comments, check runs, and statuses the dot posts |
+| Slack | `SLACK_APP_TOKEN` and `SLACK_BOT_TOKEN` are set | Chat answers and notices |
+| Your browser's push service (Apple, Google, or Mozilla) | You turn on alerts in the app | Notification title and body |
+| ntfy.sh, or your `NTFY_URL` | `NTFY_TOPIC` is set | Notification title, body, and a link |
+| OpenAI | `OPENAI_API_KEY` is set and you start a call | Call audio and the dot's call instructions |
+| Your browser vendor | A voice call in browser mode | Speech recognition audio, depending on the browser |
+| MCP servers you add | A chat uses one of their tools | The tool input |
+| mcr.microsoft.com and the npm registry | Docker runner mode | Image pulls and `npm ci` inside the test container |
+
+The mock model (`LOCALDOST_LLM=mock`) sends nothing anywhere. Demo mode with no credentials stays on the machine, except the browser push service when you turn on alerts.
+
+## Features
+
+The status column says how each part was checked. **Verified live** means it ran against the real service during dogfooding. **Real run, local** means automated tests run it for real on the machine with no outside service. **Fixture-tested** means unit tests run it against recorded payloads, fakes, or mocks. **No automated test** means only the code exists.
+
+| Area | What it does | Status |
+|---|---|---|
+| Claude CLI backend | Verdicts, scores, reviews, and chat through `claude -p` with your Claude login | Verified live |
+| Codex CLI backend | Verdicts, scores, reviews, chat, and the PR review through `codex exec` with your ChatGPT login | Verified live (analyze and a QA review pass on an eval fixture) |
+| Anthropic API backend | The same through `ANTHROPIC_API_KEY` | Fixture-tested |
+| GitHub PAT | Polling of commits and PRs, commit statuses | Verified live |
+| GitHub PAT | Sticky PR comments, job logs, contents reads | Fixture-tested |
+| GitHub App | Installation tokens, check runs with annotations | Fixture-tested |
+| GitHub webhooks | Signatures, normalizers, checklist ticks from comment edits | Fixture-tested |
+| Linear API | Personal API key, polling for new issues, issue reads | Verified live |
+| Linear webhooks and comments | Signature and timestamp check, ticket comments | Fixture-tested |
+| Jira Cloud | Webhooks, REST v3 reads, ADF comments | Fixture-tested |
+| PR review | Scoping, signals, lenses, impact, reviewer and verifier passes, sticky comment, check run | Fixture-tested: 17 eval fixtures through the mock backend, 5 of them golden cases from real misses. `npm run eval:qa-review` runs them against a live model |
+| Ticket review | Score, review, gated comment | Fixture-tested |
+| Impact on existing tests | Finds the cases and specs a ticket changes, drafts a new case version or a retire draft | Fixture-tested: 4 stories through the mock backend |
+| Demo runner and local runner | Real Playwright runs, live steps, browser frames, artifacts | Real run, local (e2e suite against the sample shop) |
+| Docker runner | Tests in a Playwright container with a read-only mount | Fixture-tested (fork guard). No test against a Docker daemon |
+| AI-Vision runner | Natural-language cases from the PR review and ticket test ideas on an AI-Vision server, its CLI, or the Midscene CLI | Verified live against a local AI-Vision server; fixture-tested (fake server and fake CLI) |
+| Browser probes | Playwright page load, selector wait, screenshot on failure | Real run, local |
+| HTTP probes, Statuspage, outage and recovery | Interval checks, three-strike outage, recovery notice | Fixture-tested |
+| Rules gate and Inbox | Four levels, auto-review, approvals with edit and expiry | Fixture-tested, plus e2e in the demo |
+| PWA | Dots, Feed, Run, Inbox, Chat, Reports, Settings, Setup screens | Real run, local (Playwright e2e at phone and desktop sizes) |
+| Web push and ntfy | Alerts to the phone | No automated test |
+| Slack | Socket Mode mentions, notices | Fixture-tested (fake Web API client) |
+| MCP connections | HTTP and stdio servers, tool calls through the gate | Fixture-tested (in-memory transport) |
+| MCP presets | AI-Vision and Midscene presets, env name passthrough, read-only tool lists | Verified live over stdio with the AI-Vision MCP server; Midscene preset not run |
+| Voice | Browser speech, OpenAI Realtime token minting | Fixture-tested (mocked OpenAI) |
+| Reports | Save a run as a page, edit, chat proposals | Fixture-tested, plus e2e |
+
+localdost is alpha software. Expect breaking changes to the database schema and the API before 1.0.
+
+## Credits
+
+localdost follows the product shape of [OpenDots](https://github.com/CopilotKit/OpenDots) by CopilotKit: a team of specialist dots with rules, an Inbox, chat, calls, Slack, and MCP connections. This README borrows its layout. [docs/PARITY.md](docs/PARITY.md) maps each OpenDots feature to its localdost version.
+
+The PR review adapts the review prompt structure, change scoping, file classifiers, five review lenses, and the script-check rules from [OpenQodex](https://github.com/openqodex/openqodex), under the Apache License 2.0. [NOTICE](NOTICE) lists the adapted files, and [LICENSES/Apache-2.0.txt](LICENSES/Apache-2.0.txt) holds the license text.
+
+## Contributing
+
+Read [CONTRIBUTING.md](CONTRIBUTING.md) for the dev setup, the test commands, and the writing rules. Report security issues as described in [SECURITY.md](SECURITY.md). Everyone in the project follows the [Code of Conduct](CODE_OF_CONDUCT.md).
+
+## License
+
+MIT. See [LICENSE](LICENSE). Material adapted from OpenQodex stays under the Apache License 2.0, as [NOTICE](NOTICE) describes.

package/bin/localdost.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// localdost CLI entry. In a checkout with dev dependencies it runs the TypeScript source through
+// tsx, so the CLI never runs a stale build. In an install without src/ or tsx (the Docker image,
+// `npm ci --omit=dev`) it runs the compiled CLI from dist/.
+import { existsSync } from 'node:fs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const root = fileURLToPath(new URL('..', import.meta.url));
+const source = `${root}src/cli/index.ts`;
+const built = `${root}dist/cli/index.js`;
+
+let register;
+if (existsSync(source) && !process.env.LOCALDOST_USE_DIST) {
+  try {
+    ({ register } = await import('tsx/esm/api'));
+  } catch {
+    /* no dev dependencies: use dist */
+  }
+}
+
+if (register) {
+  register();
+  await import(pathToFileURL(source).href);
+} else if (existsSync(built)) {
+  await import(pathToFileURL(built).href);
+} else {
+  console.error('localdost: no build found. Run `npm ci && npm run build` in the localdost folder.');
+  process.exit(1);
+}