Open-source Grok Bot alternative for named AI teammates. Local-first desktop, web, and mobile clients with per-bot tools, instructions, and memory. Independent fork of T3 Code.
docs(agents): add verification policy and rewrite testing skills (#183)
Leob49cad71239f
diff --git a/.agents/skills/ios-debugger-agent/SKILL.md b/.agents/skills/ios-debugger-agent/SKILL.mdindex 7afa57938..603e600a7 100644--- a/.agents/skills/ios-debugger-agent/SKILL.md+++ b/.agents/skills/ios-debugger-agent/SKILL.md@@ -1,6 +1,6 @@---name: ios-debugger-agent-description: Build, launch, inspect, and drive iOS apps with the repository-configured XcodeBuildMCP server. Use on macOS for iOS Simulator builds, focused native test runs, semantic UI automation, screenshots, logs, or debugging, including T3 Code Mobile verification.+description: Build, launch, inspect, and drive iOS apps with the repository-configured XcodeBuildMCP server. Use on macOS for iOS Simulator builds, focused native test runs, semantic UI automation, screenshots, logs, or debugging, including Akeru Bot mobile verification.---# iOS Debugger Agentdiff --git a/.agents/skills/ios-simulator-browser/SKILL.md b/.agents/skills/ios-simulator-browser/SKILL.mdindex 74b975307..e59835d4c 100644--- a/.agents/skills/ios-simulator-browser/SKILL.md+++ b/.agents/skills/ios-simulator-browser/SKILL.md@@ -19,16 +19,10 @@ Keep serve-sim on its default `127.0.0.1` binding. Do not expose its preview to1. Obtain the exact simulator UDID from the iOS build or launch workflow.2. Check whether an existing serve-sim stream for that UDID belongs to another task. Reuse it only when explicitly shared; never kill another task's stream.-3. Otherwise, clear only a stale stream for that UDID and start the pinned version with scoped cleanup:+3. Otherwise, start the pinned version as an owned background task and retain its handle. If another stream owns the device, report the conflict instead of terminating it:```bash- SIMULATOR_ID=<simulator-udid>- cleanup_serve_sim() {- npx --yes [email protected] --kill "$SIMULATOR_ID" >/dev/null 2>&1 || true- }- trap cleanup_serve_sim EXIT INT TERM HUP- cleanup_serve_sim- npx --yes [email protected] "$SIMULATOR_ID"+ npx --yes [email protected] <simulator-udid>```4. Keep the terminal alive and open the exact local URL printed by serve-sim in the agent's browser.@@ -44,7 +38,7 @@ If the in-app browser explicitly reports that previews are unavailable, do not i## Finish-Stop the long-running terminal and wait for its cleanup trap to finish. If it disappeared without cleanup, run `npx --yes [email protected] --kill <simulator-udid>` for that exact simulator. Never run an unscoped `--kill`.+Retain the owned stream during human review according to [the verification policy](../../../docs/internals/verification.md). At final teardown, stop its captured background task. If a stream remains, verify that it is still the one owned by this task before running `npx --yes [email protected] --kill <simulator-udid>`. Never run an unscoped `--kill`.## Upstreamdiff --git a/.agents/skills/test-t3-app/SKILL.md b/.agents/skills/test-t3-app/SKILL.mdindex 0e11b50e1..3f73d389b 100644--- a/.agents/skills/test-t3-app/SKILL.md+++ b/.agents/skills/test-t3-app/SKILL.md@@ -1,90 +1,61 @@---name: test-t3-app-description: Launch, retain, and test the T3 Code web app in isolated development environments, including first-try browser authentication with one-time pairing URLs, pairing-token recovery, worktree-safe state directories, cross-turn dev server lifecycle, and direct SQLite inspection or fixture seeding. Use when an agent needs to run T3 locally, iteratively test UI behavior with a human, recover from an expired or consumed pairing token, isolate dev state, or prepare test data in state.sqlite.+description: Launch and verify Akeru Bot web and desktop in isolated development environments. Use for browser testing, Electron-specific checks, pairing recovery, debug access, and fixture setup.----# Test T3 App+# Test Akeru Bot web and desktop-Use this skill for the web client. For iOS Simulator, Android Emulator, or physical-device testing against an isolated T3 backend, use the sibling [`test-t3-mobile`](../test-t3-mobile/SKILL.md) skill.+Read [the verification policy](../../../docs/internals/verification.md) before launching a client. It defines authorization, coverage, evidence, and environment lifetime. For native mobile testing, use [`test-t3-mobile`](../test-t3-mobile/SKILL.md).-## Start an isolated web environment+## Find or start the environment-1. Run commands from the repository root.-2. Choose a base directory that belongs only to the current worktree or test:- - Use the repository's ignored `.t3` directory for reusable worktree-local state.- - Use `mktemp -d /tmp/t3code-test.XXXXXX` for disposable state and retain the printed absolute path.-3. Start the full web stack with `vp run dev`. Add `--share` when the user needs to open it from another tailnet device. In a linked worktree it defaults to that worktree's gitignored `.t3`; pass `--home-dir <base-dir>` only when the test needs a different isolated directory.-4. Keep the terminal session alive and read the selected server port, web port, base directory, and pairing URL from its output.+1. Run commands from the repository root. Run `vp run dev:status` to inspect the current environment without starting it. Reuse an owned healthy environment and its authenticated browser context.+2. Use the worktree-local `.akeru` home. For a separate test, create a temporary directory and retain its absolute path. An explicit home stores runtime state in `<home>/userdata`.+3. Run `vp run dev` in the background. Use `--home-dir <path>` only for a deliberately selected isolated home. Add `--share` only when the user requests access from another tailnet device.+4. Retain the task handle, selected ports, home, and startup output. Read actual ports from `[dev-runner]`; occupied ports can shift them.+5. Confirm the selected home before loading fixtures or pairing. Worktree defaults outrank ambient home settings. Never start a test server against the live `~/.akeru/userdata` database.-Treat a base directory as disposable only when it was created or deliberately selected for the current test. Never delete or directly seed the shared `~/.t3` directory. Prefer starting with a new temporary base directory over clearing state of uncertain ownership.+The setup script copies optional project `.env` configuration into each new worktree. Existing `.env` files are preserved. If setup reports a legacy symlink, replace it with a private copy before editing configuration. Keep secrets out of test evidence.-The worktree-local default deliberately outranks an ambient `T3CODE_HOME`; do not pass the shared home through to a worktree dev server.+Browser dev is single-origin. Vite proxies backend requests; leave `VITE_HTTP_URL` and `VITE_WS_URL` unset. Automated runs leave browser auto-open disabled so an uncontrolled tab cannot consume the startup token.-Ports are derived from the worktree path but can shift when occupied. Always read the actual values from the `[dev-runner]` line.+## Pair the controlled browser-Shared browser dev is single-origin: Vite proxies the backend paths, so never set `VITE_HTTP_URL` or `VITE_WS_URL` for `dev`/`dev:web`.+1. Load the browser skill for the tool available in the current harness. With `agent-browser`, read its skill and run `agent-browser skills get core --full` before the first browser action. Keep one background browser session for this task.+2. Open the complete startup URL ending in `/pair#token=...` once. Preserve the fragment exactly.+3. Wait for the pairing exchange and redirect. Verify that the intended environment and projects appear.+4. Continue in the same browser context. A pairing page or disconnected empty view does not prove a connection.-The dev runner disables browser auto-open by default. Do not pass `--browser` during automated testing: an automatically opened page can consume the one-time bootstrap token before the controlled browser uses it.+Recover an expired or consumed token with `node apps/server/src/bin.ts pair`. If the server uses an explicit home, pass `--base-dir <same-absolute-path>`. Discovery reads the running server's origin, including its shared origin.-### Verify a shared environment before human handoff+Recovery tokens have standard client scopes. The startup URL has admin scopes needed for Settings → Connections management. For that flow, restart only the owned test server and use its new startup URL.-When another person will use the printed pairing URL, first open the shared origin without the pairing path or fragment in the controlled browser and confirm the T3 Code app loads. This browser navigation is required even when curl succeeds because browsers block some otherwise reachable ports before making a network request.+Keep tokens out of screenshots and durable evidence. A human and an agent need separate tokens. When handing over shared access, first check the shared bare origin in the browser without consuming the human's token. Then provide the full fresh pairing URL to the user.-Do not open the other person's complete pairing URL during this reachability check; doing so consumes its one-time token. If the agent also needs an authenticated browser, create and consume a separate pairing token, then leave a fresh token for the other person.+## Prepare data and verify behavior-## Preserve the environment while iterating+Read [SQLite fixtures](references/sqlite-fixtures.md) when preparing data or inspecting state. Prefer deterministic fixtures for repeatable visual checks. Use a safe snapshot of real data when reproducing a data-specific defect.-Treat the overall testing or implementation loop—not an assistant turn or one verification pass—as the environment lifecycle boundary.+Exercise the affected flow using clicks, typing, submission, and navigation. Apply the coverage and evidence checks in the verification policy. A screenshot alone is not a behavior test.-- Keep the dev process, base directory, selected ports, authenticated browser tab, registered projects, and seeded fixtures alive while the user may inspect the result or request follow-up changes.-- Do not stop the server merely because one verification pass completed or because you are yielding a response to the user.-- Before starting another environment, check whether the existing process and browser tab still serve the task. Reuse them when healthy instead of discarding useful state.-- On a later turn, verify that the existing process is alive and reuse its printed ports and base directory. If it exited, restart with the same base directory; create a new pairing token only when the browser session is no longer valid.-- Tell the user when a test environment remains available, including its non-secret web URL when useful. Include a pairing token only when the user still needs to pair (see below).+## Desktop-specific verification-## Authenticate the browser on the first navigation+Use a web pass for shared renderer-only changes. Run Electron when a change touches the desktop shell, IPC, native menus, protocol links, preload, packaged origins, startup, or process cleanup.-1. Wait for the server log that says authentication is required and includes a URL ending in `/pair#token=...`.-2. Use the controlled in-app browser or browser-automation surface available to the agent. Do not use a system-browser launch command during automated testing.-3. Open that complete URL exactly once as the controlled browser's first navigation. Preserve the fragment and token verbatim.-4. Wait for the pairing exchange and redirect to finish before navigating elsewhere.-5. Continue in the same browser context so its stored bearer session remains available.+1. Build with `vp run build:desktop`. For an automated startup check, run `vp run test:desktop-smoke`. The smoke script creates private application and OS home directories and stops its captured Electron process group.+2. For interactive inspection, use the installed raw Electron executable with `apps/desktop/dist-electron/main.cjs`. Resolve the executable and create its private environment with `resolveSmokeElectronPath` and `createSmokeEnvironment` from `apps/desktop/scripts/smoke-test.mjs`. Create the returned home, temporary, and config directories before spawning. Retain the temporary root and captured process group.+3. Set `T3CODE_HOME` and `AKERU_HOME` to the same isolated fixture home. Use a different home from any running backend. Pass `--remote-debugging-address=127.0.0.1 --remote-debugging-port=<free-port>` to that Electron process.+4. Attach the supported browser tool to that exact Electron instance. With `agent-browser`, use a named session and `connect <port>` after loading its version-matched guidance. Confirm the app and environment before acting.+5. Exercise the Electron behavior itself, then recheck after the relevant reload or restart. A successful external web tab does not prove shell behavior. Use native automation only when browser tools cannot reach the control, within the verification policy's authorization boundary.-Keep pairing URLs out of screenshots, committed files, and durable logs. When the user asked for a shared environment, the deliverable IS the full pairing URL — paste it in your reply, token and all; a bare origin is useless to them. A pairing token is short-lived and single-use; opening the URL in another browser or opening it twice can consume it, so never open a URL you handed to the user.+`--home-dir` isolates server data, not Electron's OS profile. The branded development launcher can also register OS protocol handlers. Use the raw runtime for isolated checks; test the branded launcher only when its OS integration is in scope and authorized. Startup log markers prove less than renderer content and interaction. Packaged-artifact tests must also isolate the OS home; `--user-data-dir` alone can be overridden by the app.-## Recover a consumed or expired pairing token+The debug port is local test access. Do not expose it through a tunnel. If attaching is unavailable, report the missing tool and what focused tests could prove instead.-Run `node apps/server/src/bin.ts pair` from the repository root. It discovers the running dev server (worktree `.t3` first, same precedence as the dev runner) and prints a fresh `Pair URL` against the server's current web origin, including a `--share` tailnet origin. Pass `--base-dir <base-dir>` only when the server was started with `--home-dir`, using the identical path.+## Diagnose and finish-Tokens from `pair` carry standard client scopes. The startup pairing URL carries admin scopes; if the user needs Settings → Connections management (`access:write`), restart the server and hand over the new startup URL instead.--## Inspect or seed SQLite state--Read [references/sqlite-fixtures.md](references/sqlite-fixtures.md) before changing the database.--- Use `node apps/server/scripts/t3-sqlite-state.ts query` for schema discovery and read-only checks.-- Stop the dev server before using `node apps/server/scripts/t3-sqlite-state.ts exec`, then restart it with the same base directory.-- Seed projection tables only for disposable UI fixtures. Use application commands and APIs when testing business behavior or projection correctness.-- Use the auth CLI, not direct `auth_*` table edits, for pairing and sessions.--The helper refuses to write to the shared `~/.t3` directory by default and creates a database backup before each mutation.--## Tear down only when the testing loop is finished--Tear down when the user explicitly asks, confirms the iteration is finished, or the overall task is genuinely complete with no pending human review. Do not infer completion from the end of an assistant turn.--When teardown is appropriate:--1. Stop the dev process with its terminal interrupt.-2. Preserve the isolated base directory when it contains useful reproduction evidence or state for a likely follow-up.-3. Otherwise remove only a path created for this test after resolving and verifying the exact target.--If completion is uncertain, keep the environment alive and mention that it is retained for further iteration. A fresh isolated base directory remains the safest reset when authentication, migrations, or fixture state becomes ambiguous.--## Troubleshoot predictably--- If the browser shows an unauthenticated pairing screen, issue a new token instead of retrying the consumed URL.-- If the pairing URL is no longer visible, create a replacement token with both `--dev-url` and `--base-url`.-- If the replacement token is rejected, verify that the CLI and server use the identical absolute base directory and web URL.-- If the UI shows unexpected data, verify that every command uses the identical explicit base directory before editing anything.-- If ports move because another instance is running, trust the current dev-runner output rather than assuming ports `13773` and `5733`.+- Run `vp run dev:status` to confirm the selected home and runtime state before diagnosing an unexpected screen.+- Inspect `<home>/userdata/logs/server.trace.ndjson` for explicitly selected or worktree homes. See [observability](../../../docs/operations/observability.md) for trace fields and provider logs.+- Preserve background stdout/stderr for startup failures. Share only the errors relevant to the failed action.+- If pairing fails, mint a fresh token and confirm home and origin rather than retrying the same URL.+- Retain or tear down the environment according to the verification policy. Stop only the task or process group captured at launch.diff --git a/.agents/skills/test-t3-app/agents/openai.yaml b/.agents/skills/test-t3-app/agents/openai.yamlindex 0445ee4cb..b2f43995c 100644--- a/.agents/skills/test-t3-app/agents/openai.yaml+++ b/.agents/skills/test-t3-app/agents/openai.yaml@@ -1,4 +1,4 @@interface:- display_name: "T3 App Testing"- short_description: "Launch and retain isolated T3 test environments"- default_prompt: "Use $test-t3-app to launch an isolated T3 environment and iteratively test it in the browser while preserving state."+ display_name: "Akeru Bot App Testing"+ short_description: "Verify isolated web and desktop environments"+ default_prompt: "Use $test-t3-app to verify Akeru Bot in an isolated web or desktop client and retain evidence of the affected behavior."diff --git a/.agents/skills/test-t3-app/references/sqlite-fixtures.md b/.agents/skills/test-t3-app/references/sqlite-fixtures.mdindex 8eca543cf..2660fc080 100644--- a/.agents/skills/test-t3-app/references/sqlite-fixtures.md+++ b/.agents/skills/test-t3-app/references/sqlite-fixtures.md@@ -1,6 +1,24 @@# SQLite fixtures-Load this reference only when inspecting or seeding local T3 state directly.+Load this reference when inspecting or seeding isolated Akeru Bot state. Use deterministic visual fixtures for repeatable checks; use application commands to verify business behavior.++## Repeatable visual fixtures++Create a fresh empty home and seed a scenario before starting the server:++```bash+FIXTURE_HOME=$(mktemp -d /tmp/akeru-ui.XXXXXX)+vp run dev:fixture --base-dir "$FIXTURE_HOME" --case populated+vp run dev --home-dir "$FIXTURE_HOME"+```++Start the final command as a background task. Retain the printed home and task handle.++Cases are `empty`, `populated`, and `edge`. The fixture command runs migrations and creates deterministic projection data without provider calls. Populated data includes a bot and completed chats; edge data adds empty states, a long title, and an archived chat.++The command accepts only an empty directory or its own unused fixture directory. Repeated offline runs replace projection data and back up an existing database. After the app adds credentials, provider state, or events, create a fresh fixture home rather than resetting it. The helper refuses a running database, shared Akeru home paths, and redirected fixture state.++These are display fixtures, not a coherent event history. Use the app's commands for tests of edits, persistence, projection rebuilds, or server behavior. For a data-specific defect, take a read-only `VACUUM INTO` snapshot as described in `AGENTS.md`.## Select the correct databasediff --git a/.agents/skills/test-t3-mobile/SKILL.md b/.agents/skills/test-t3-mobile/SKILL.mdindex fbcd52e69..698124660 100644--- a/.agents/skills/test-t3-mobile/SKILL.md+++ b/.agents/skills/test-t3-mobile/SKILL.md@@ -1,188 +1,103 @@---name: test-t3-mobile-description: Launch and test T3 Code Mobile on an iOS Simulator or Android Emulator against disposable local T3 environments, including Metro and dev-client reuse, native rebuild decisions, per-client pairing, seeded projects, semantic UI control, screenshots, and iOS serve-sim streaming. Use after mobile UI or native changes, when reproducing phone or tablet behavior, pairing an emulator to isolated state, or verifying mobile behavior on macOS, Linux, or Windows.+description: Verify Akeru Bot mobile on iOS or Android with an isolated environment, reusable development clients, deterministic pairing, semantic UI control, and focused evidence.----# Test T3 Mobile+# Test Akeru Bot mobile-Run one focused, end-to-end mobile verification pass against disposable T3 state. Use the sibling [`test-t3-app`](../test-t3-app/SKILL.md) skill as the detailed reference for pairing-token semantics and SQLite fixtures.+Read [the verification policy](../../../docs/internals/verification.md) for authorization, coverage, evidence, and environment lifetime. Use [`test-t3-app`](../test-t3-app/SKILL.md) for shared environment discovery, browser pairing, and SQLite fixtures.-Command examples use POSIX shell syntax. On Windows, use PowerShell equivalents: set variables with `$env:NAME = "value"`, use an explicit temporary directory from `[System.IO.Path]::GetTempPath()`, and run multiline examples on one line or with PowerShell backticks. Use `$env:ANDROID_HOME\platform-tools\adb.exe` when `adb` is not already on `PATH`.+## Select the platform and client-## Select a viable platform+1. On macOS with Xcode, use one representative iOS Simulator for cross-platform changes. Load [`ios-debugger-agent`](../ios-debugger-agent/SKILL.md). Load [`ios-simulator-browser`](../ios-simulator-browser/SKILL.md) when a live visual feed is needed.+2. Use Android when the change is Android-specific or iOS tooling is unavailable. Select one emulator serial with `adb devices`.+3. Reuse a compatible installed development client for JavaScript, TypeScript, and asset changes. Rebuild only when native source, dependencies, entitlements, config plugins, or generated projects changed.+4. Resolve identity with `node .agents/skills/test-t3-mobile/scripts/app-identity.mjs <scheme|ios-bundle-id|android-package>`. The helper reads the development app configuration, including personal-team overrides. For the full config, run `vp run --filter @t3tools/mobile config:dev`. Use the resolved values below instead of copied identifiers.+5. Find the actual generated Xcode workspace and scheme rather than assuming a historical name. If generated native projects are absent, first check for a compatible installed client or existing artifact.-Inspect the host and the affected code before launching processes:+`ios:dev` and `android:dev` run clean Expo prebuilds. Use them only when regeneration is required. If the user forbids a rebuild and no compatible client exists, report that blocker. Do not create or download simulator runtimes without permission.-- On macOS with Xcode, prefer one representative iOS Simulator when the change is cross-platform so the user can watch through serve-sim. Load and follow [`ios-debugger-agent`](../ios-debugger-agent/SKILL.md), and load [`ios-simulator-browser`](../ios-simulator-browser/SKILL.md) when live streaming is available.-- On macOS, Linux, or Windows with the Android SDK, use one Android Emulator when Android is the affected surface or iOS tooling is unavailable.-- When the change is platform-specific, test that platform. When neither platform is viable, report the missing SDK, emulator, or dev-client prerequisite rather than claiming verification.+## Start one isolated environment-Do not treat unavailable iOS tooling as a blocker when Android is a valid representative target.+Run backend commands from the repository root. Use the worktree-local `.akeru` or a deliberately created temporary home. Explicit homes store runtime state under `<home>/userdata`.-## Choose the lightest valid launch path+Use `vp run dev:status` to inspect an existing environment. Reuse a healthy owned server. When testing web and mobile together, run `vp run dev --home-dir <home>` once and connect both clients to that backend.-- For JavaScript, TypeScript, or asset-only changes, reuse a compatible installed development client and start Metro. Do not rebuild native code merely to load a new bundle.-- For native source, native dependencies, entitlements, config plugins, or generated project changes, rebuild the affected platform.-- Use `vp run ios:dev` or `vp run android:dev` only when an Expo clean prebuild is actually required; both commands regenerate the native project.-- If the user requested no native rebuild and no compatible app is installed, reuse an existing compatible `.app` or `.apk` artifact when available. Otherwise report the missing dev client instead of silently rebuilding.--The development identity on both platforms is:--- App: `T3 Code Dev`-- Bundle/package identifier: `com.t3tools.t3code.dev`-- URL scheme: `t3code-dev`--Bundle or package presence proves the correct variant, not native compatibility. Reuse it only when the current changes did not alter its Expo SDK, native dependencies, config plugins, entitlements, generated project, or native source.--## Start one disposable T3 environment--Run backend commands from the repository root. Use the ignored, worktree-local `.t3` directory or create a fresh directory with the host OS's temporary-directory mechanism. An explicit base directory stores state in `<base-dir>/userdata`; never point testing at shared `~/.t3` state.--Seed a small number of meaningful Git projects before starting the backend:+For a mobile-only backend:```bash-node apps/server/src/bin.ts project add <git-workspace> \- --base-dir <base-dir> \- --title <project-title>+node apps/server/src/bin.ts serve --host 127.0.0.1 --port <server-port> --base-dir <home> --no-browser```-Running `project add` before the backend starts gives it exclusive offline database access. If a backend is already running, wait until it is ready so the CLI dispatches through the live server; never run offline mutations concurrently with the server.--Use direct SQLite mutation only for disposable projection fixtures. Follow `test-t3-app` and stop the backend before writing.--Start a headless backend after seeding:--```bash-node apps/server/src/bin.ts serve \- --host 127.0.0.1 \- --port <server-port> \- --base-dir <base-dir> \- --no-browser-```--Use these client origins:--- iOS Simulator: `http://127.0.0.1:<server-port>`-- Android Emulator: `http://10.0.2.2:<server-port>`-- Physical device: bind the backend to `0.0.0.0` and use the host's reachable LAN origin--Enter the complete `http://` origin to make the test transport explicit. Bare IP addresses default to HTTP, while bare hostnames default to HTTPS. When testing web and mobile together, run `vp run dev --home-dir <base-dir> --host 127.0.0.1` instead and do not launch a second backend over the same base directory.--## Start or reuse Metro safely--Run Metro from `apps/mobile`.--1. Inspect any process on the intended Metro port and its `/status` response. Reuse it only when it is healthy, belongs to this worktree, and matches `APP_VARIANT=development`, `--dev-client`, and scheme `t3code-dev`.-2. Never kill another worktree's Metro. Use a free explicit port when necessary.-3. Run `vp run dev:client` on the standard port. For another port, retain the complete development identity:+Run it in the background and retain its handle and output. Seed meaningful projects through `project add`, or use the visual fixture recipe in [SQLite fixtures](../test-t3-app/references/sqlite-fixtures.md). Offline writes require the backend to be stopped. `project add` can use a running ready server; never race its startup with offline mutation.- ```bash- APP_VARIANT=development vp exec expo start \- --dev-client \- --scheme t3code-dev \- --clear \- --lan \- --port <metro-port>- ```+Use the complete HTTP origin:- In PowerShell, set `$env:APP_VARIANT = "development"` first and then run the `vp exec expo start ...` command without the leading assignment.+- iOS Simulator: `http://127.0.0.1:<server-port>`.+- Android Emulator: `http://10.0.2.2:<server-port>`.+- A requested physical-device test: bind to a reachable interface and use the host's LAN origin.-4. Open the exact development-client URL for the selected device and confirm the loaded bundle belongs to this worktree and Metro port.+## Start or reuse Metro-### iOS launch+Run Metro from `apps/mobile`. Check the intended port and `/status`. Reuse it only when its owner, worktree, development variant, and scheme match this task. A healthy Metro from another worktree is not interchangeable.-Use `ios-debugger-agent` to select one UDID and set these XcodeBuildMCP session defaults:--- Workspace: `<repo>/apps/mobile/ios/T3CodeDev.xcworkspace`-- Scheme: `T3CodeDev`-- Configuration: `Debug`-- Simulator ID: the selected UDID-- Bundle ID: `com.t3tools.t3code.dev`--Check the installed client with:+Use `vp run dev:client`. For a different free port, retain the development identity:```bash-xcrun simctl get_app_container <simulator-udid> com.t3tools.t3code.dev app-xcrun simctl openurl <simulator-udid> <printed-dev-client-url>+APP_VARIANT=development vp exec expo start --dev-client --scheme <resolved-scheme> --clear --lan --port <metro-port>```-Accept the iOS confirmation prompt and dismiss the developer menu when it obscures the app.+On Windows, set `APP_VARIANT` through PowerShell before running the command. Open the exact printed development-client URL and confirm that the loaded bundle belongs to this worktree.-### Android launch+### iOS-Select one running emulator serial from `adb devices` and check the installed client:+Set XcodeBuildMCP session defaults to the selected simulator UDID, actual workspace/scheme when building, Debug configuration, and resolved bundle ID. For an installed client:```bash-adb -s <emulator-serial> shell pm path com.t3tools.t3code.dev-adb -s <emulator-serial> reverse tcp:<metro-port> tcp:<metro-port>-adb -s <emulator-serial> shell am start -W \- -a android.intent.action.VIEW \- -d '<printed-dev-client-url>' \- com.t3tools.t3code.dev+xcrun simctl get_app_container <udid> <resolved-bundle-id> app+xcrun simctl openurl <udid> <printed-dev-client-url>```-Do not start, stop, erase, or reconfigure an emulator owned by another task. Track and later stop only processes owned by this test.--## Pair each client once+Accept the launch prompt and dismiss a developer menu if it obscures the app.-Use the bundled helper from the repository root. It issues a fresh credential against the running backend's exact base directory, opens the existing Add Environment route with the credential in an encoded query parameter, and asks that route to connect once:+### Android```bash-.agents/skills/test-t3-mobile/scripts/pair-client.sh \- ios <simulator-udid> <server-port> <base-dir>--.agents/skills/test-t3-mobile/scripts/pair-client.sh \- android <emulator-serial> <server-port> <base-dir>-```--Run only the command for the selected platform. The helper uses `http://127.0.0.1:<server-port>` for iOS and `http://10.0.2.2:<server-port>` for Android. Pass a fifth argument only when testing a non-development URL scheme.--The helper opens this registered route:--```text-t3code-dev://connections/new?pairingUrl=<encoded-pairing-url>&autoConnect=1+adb -s <serial> shell pm path <resolved-package>+adb -s <serial> reverse tcp:<metro-port> tcp:<metro-port>+adb -s <serial> shell am start -W -a android.intent.action.VIEW -d '<printed-dev-client-url>' <resolved-package>```-The Add Environment route owns the behavior: `pairingUrl` prefills its normal host and token inputs, while `autoConnect=1` submits once in development builds and returns to Home after success. Without `autoConnect`, the same route only prefills the form for manual inspection.--Do not enter pairing hosts or tokens through simulator keyboard automation. Xcode's semantic typer sends HID-style key events through the simulator's active keyboard state, which can corrupt uppercase tokens and punctuation even when the host Mac uses a U.S. input source. The one-shot route is the deterministic pairing path. Use the visible form only as a fallback, and paste credentials rather than typing them character by character.--Verify the expected seeded projects appear before exercising the affected flow.+Track any port-forwarding rule you add. Leave devices and processes owned by other tasks alone.-Pairing credentials are secret, short-lived, and single-use. Create a different credential for every simulator, emulator, physical device, or browser. If an attempt fails, issue a new credential rather than retrying the old one. Do not expose tokens in screenshots, commits, or final responses.+## Pair once per client-## Drive and observe the affected flow+Use the helper from the repository root. It resolves development identity and opens the existing Add Environment route:-### iOS+```bash+.agents/skills/test-t3-mobile/scripts/pair-client.sh ios <udid> <server-port> <home>+.agents/skills/test-t3-mobile/scripts/pair-client.sh android <serial> <server-port> <home>+```-Use `snapshot_ui` and current element references from XcodeBuildMCP for taps and typing. Stream the same UDID through `ios-simulator-browser` so the user can watch in T3 Code when the host supports it. Use the stream as a visual feed rather than a reason to switch to fragile browser coordinates.+Run only the command for the selected device. A fifth argument overrides the URL scheme when explicitly testing another variant.-### Android+The route prefills the normal pairing form and submits once through development-only `autoConnect=1`. Without that flag it only prefills the form. Verify the intended projects appear after connection.-Prefer semantic Android automation exposed by the current agent host. Otherwise inspect the current hierarchy with `adb shell uiautomator dump`, target stable resource IDs, content descriptions, text, or bounds, and use scoped `adb shell input` actions. Refresh the hierarchy after navigation. Capture the final state with `adb exec-out screencap -p`.+Use a fresh credential for each client and each failed attempt. Simulator keyboard input can corrupt token case and punctuation; use the helper instead. Test the manual form separately when pairing UI is the feature under test. Keep credentials out of screenshots and durable evidence.-Android does not use serve-sim. Use a browser-compatible Android mirror when the host already provides one; otherwise return focused emulator screenshots as evidence rather than installing unrelated streaming infrastructure during verification.+## Drive and observe-## Verify and clean up+On iOS, use current XcodeBuildMCP `snapshot_ui` element references. Refresh after navigation. Keep screenshots, semantic actions, and any simulator stream pinned to the same UDID.-Exercise only the affected flow on one representative device unless the change specifically concerns platform, OS version, or screen size. Before finishing:+On Android, prefer available semantic automation. Otherwise refresh `uiautomator dump` and use stable resource IDs, descriptions, or current bounds for scoped input. Capture evidence with `adb exec-out screencap -p`.-1. Confirm the app connected to the intended disposable environment instead of merely rendering an empty disconnected state.-2. Capture the relevant final state.-3. Remove the disposable environment from T3 Code Dev.-4. Remove any `adb reverse` rule created for this test with `adb -s <emulator-serial> reverse --remove tcp:<metro-port>`.-5. Stop only the serve-sim, Metro, backend, emulator, and log processes started by this test.-6. Remove only base directories and temporary Git repositories deliberately created for this test. Preserve them when they contain useful reproduction evidence.+Exercise the affected flow and surrounding cases from the verification policy. Confirm the intended environment, not merely an empty screen. A deep link that bypasses a form proves connection behavior, not the form's typing and validation behavior.-Keep local verification focused. Do not turn this workflow into a full repository test run.+## Diagnose and finish-## Troubleshoot predictable failures+- Old UI: confirm Metro's worktree, variant, URL, and port before changing app code.+- Connection failure: confirm the platform-specific origin and home, then mint a fresh token.+- Missing iOS references: refresh the snapshot and session defaults; report inaccessible controls rather than using guessed coordinates.+- Android bundle failure: check the exact Metro port and the forwarding rule.-- **Old UI or an old error appears:** verify Metro's worktree, variant, URL, and port before diagnosing the app.-- **The environment remains empty:** verify the platform-specific HTTP origin, use a fresh token, and confirm project seeding used the identical base directory.-- **A second client cannot pair:** pairing tokens are single-use; issue another token.-- **The pairing form opens but does not connect:** confirm the deep link uses the existing `connections/new` route, includes `autoConnect=1`, and carries a freshly minted encoded `pairingUrl`.-- **Pairing text changes case or punctuation:** do not retry semantic typing. Use `scripts/pair-client.sh`; the simulator keyboard layout and HID input path are not reliable for credentials.-- **iOS semantic actions fail:** set explicit XcodeBuildMCP defaults and refresh with `snapshot_ui`.-- **Android cannot reach Metro:** verify `adb reverse` for the exact Metro port and relaunch the development-client URL.-- **Android cannot reach the backend:** use `10.0.2.2`, not `127.0.0.1`, for the Android Emulator.+Follow the shared retention policy while the user reviews. At final teardown, remove the disposable app connection and owned `adb reverse` rules, stop only owned processes, and remove only deliberately created temporary data. Preserve useful reproduction evidence.diff --git a/.agents/skills/test-t3-mobile/agents/openai.yaml b/.agents/skills/test-t3-mobile/agents/openai.yamlindex e9518ce9e..8b4458cc9 100644--- a/.agents/skills/test-t3-mobile/agents/openai.yaml+++ b/.agents/skills/test-t3-mobile/agents/openai.yaml@@ -1,4 +1,4 @@interface:- display_name: "Test T3 Mobile"- short_description: "Test T3 Code on iOS or Android"- default_prompt: "Use $test-t3-mobile to launch T3 Code against an isolated backend and verify the affected flow on an available simulator or emulator."+ display_name: "Test Akeru Bot Mobile"+ short_description: "Verify Akeru Bot on iOS or Android"+ default_prompt: "Use $test-t3-mobile to connect Akeru Bot to an isolated environment and verify the affected flow on an available simulator or emulator."diff --git a/AGENTS.md b/AGENTS.mdindex 0a21b9e1b..d321c5096 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -88,7 +88,7 @@ The most common defect in this repo is a change that works on the path you teste## Dev servers-- `vp i` installs. Worktrees get this from the t3.json setup script; if module resolution looks broken, it probably did not run.+- `vp i` installs. Worktree setup installs dependencies, copies optional `.env` configuration without sharing later edits, and warms the web cache. It preserves existing local `.env` files and refuses legacy symlinks. If module resolution is broken, check setup first.- `vp run dev` starts server and web. In a worktree, state defaults to that worktree's gitignored `.akeru`, which deliberately outranks an ambient `T3CODE_HOME` or `AKERU_HOME` so you cannot land on shared state by accident. An explicit `--home-dir` still wins.- Ports derive from the worktree path and are stable across restarts, but read the real ones from the `[dev-runner]` line since occupied ports shift.- Sharing over the tailnet is three steps: run `vp run dev --share` in the background, wait for the `pairingUrl:` line in its output, paste that full URL (token included) in your reply. Do not wire up `tailscale serve` by hand for this, and do not open the URL yourself.@@ -97,15 +97,16 @@ The most common defect in this repo is a change that works on the path you teste## Test data-An empty database is a bad test. Seed your worktree's `.akeru` with a copy of real data instead of pointing at live state:+Choose meaningful test data. Use deterministic visual fixtures for repeatable UI checks; see [SQLite fixtures](.agents/skills/test-t3-app/references/sqlite-fixtures.md). For a data-specific defect, seed your worktree's `.akeru` with a safe snapshot instead of pointing at live state:- Copy from `~/.akeru/userdata` or `~/.akeru/dev`. Worktree state lives at `<worktree>/.akeru/userdata`.- Snapshot the database with `VACUUM INTO`, which is safe even while a server has the source open and yields one consistent file:```bash- mkdir -p .akeru/userdata- rm -f .akeru/userdata/state.sqlite* # VACUUM INTO refuses to overwrite- bun -e "new (require('bun:sqlite').Database)(process.env.HOME + '/.akeru/userdata/state.sqlite', { readonly: true }).run(\"VACUUM INTO '.akeru/userdata/state.sqlite'\")"+ SNAPSHOT_HOME=$(mktemp -d /tmp/akeru-snapshot.XXXXXX)+ mkdir -p "$SNAPSHOT_HOME/userdata"+ SNAPSHOT_HOME="$SNAPSHOT_HOME" node -e "const { DatabaseSync } = require('node:sqlite'); const db = new DatabaseSync(process.env.HOME + '/.akeru/userdata/state.sqlite', { readOnly: true }); db.prepare('VACUUM INTO ?').run(process.env.SNAPSHOT_HOME + '/userdata/state.sqlite'); db.close();"+ # Start the test server with --home-dir "$SNAPSHOT_HOME".```A plain `cp` is only safe when no server has the source open, and must bring the `-wal` and `-shm` siblings along. A live file copy is a corrupt copy.@@ -119,7 +120,7 @@ An empty database is a bad test. Seed your worktree's `.akeru` with a copy of re- **Do not run repo-wide checks.** No `vp check`, no `vp run -r test`, no `vp run -r typecheck` unless I ask. CI owns the full suite.- Backend behavior changes ship with focused tests for that behavior.- The server is event-sourced and its async flows emit typed receipts. Wait on receipts and worker drains, never on sleeps or polling. A test that needs a timeout to pass is wrong.-- Upon request, user-visible frontend changes should get one integrated pass in a real client: `test-t3-app` for web, `test-t3-mobile` for mobile. The primary agent does this once after integrating. Subagents do not launch their own dev servers. Ask permission before doing computer use or spinning up browsers.+- Implementation requests include focused verification in isolated local clients. Follow [the verification policy](docs/internals/verification.md) for authorization, coverage, evidence, and environment lifetime. Use `test-t3-app` for web or desktop and `test-t3-mobile` for native mobile. The primary agent performs the integrated pass; subagents do not launch dev servers.## Pull requests@@ -164,5 +165,5 @@ Full glossary with file links: `docs/internals/glossary.md`## Additional tips-- Don't verify with browsers or computer use unless the user explicitly agrees or requests it.+- Ask before controlling the user's live desktop session or physical devices. Isolated local verification follows the policy above.- Security is important, but should not be over-indexed on, especially for dev mode/maintainer-only features.diff --git a/docs/README.md b/docs/README.mdindex dd09c8ab6..4126fe119 100644--- a/docs/README.md+++ b/docs/README.md@@ -34,6 +34,7 @@ policy in [CONTRIBUTING.md](../CONTRIBUTING.md); agent rules in [AGENTS.md](../A- [Workspace layout](./internals/workspace-layout.md)- [Glossary](./internals/glossary.md)- [Scripts](./internals/scripts.md)+- [Local verification](./internals/verification.md)- [Connection runtime](./internals/connection-runtime.md)- [Providers](./internals/providers.md)- [Plugin lifecycle verification](./internals/plugin-lifecycle-verification.md)diff --git a/docs/internals/scripts.md b/docs/internals/scripts.mdindex 68925e28d..20da7a0df 100644--- a/docs/internals/scripts.md+++ b/docs/internals/scripts.md@@ -49,12 +49,52 @@ authenticated.`<path>/userdata`; the base directory remains available for caches, worktrees, and other shareddata.+### Dev status++Run `vp run dev:status` for a read-only status report. Use+`vp run dev:status --home-dir <path>` to inspect an explicit Akeru home.+The command uses the existing `server-runtime.json`; it does not scan ports or create a registry.++- Reports the checkout root, linked worktree, Akeru home, data directory, recorded server and web+ origins, trace path, and missing local prerequisites.+- Uses the same worktree home helper as the dev runner. An explicit `--home-dir` wins, then the+ worktree home, then `T3CODE_HOME`. The implicit main-checkout fallback is `~/.akeru/dev`.+ Explicit and worktree homes use `userdata`. `AKERU_HOME` is not a dev-runner override.+- Checks the recorded PID without sending a signal. Missing or stale runtime files remain unchanged.+ Recorded origins from stale files are historical, not proof that a server is running.+- Makes credential-free HTTP HEAD checks only on loopback. It does not follow redirects or contact+ remote origins. HTTP responses show availability, not verified application readiness.+- Reports desktop debug-port configuration and the command that resolves current mobile identity+ from app configuration. It does not duplicate bundle IDs or infer installed clients from settings.+ Provider credentials, native toolchains, and installed mobile apps are not checked.+- Does not print pairing URLs, URL credentials, queries, fragments, or arbitrary environment values.+ It does not read the database, start a server or browser, or change state, including in live homes.++### Worktree setup and verification++Worktree setup runs `scripts/setup-worktree-env.ts` after dependency installation. It copies optional+project `.env` configuration with private permissions, preserves an existing regular file, and+refuses a legacy symlink. Changes to the worktree copy do not change the source checkout.++Use `vp run dev:fixture --base-dir <empty-home> --case <empty|populated|edge>` for repeatable,+offline visual data. The command runs migrations, guards the home and database, and backs up repeated+fixture writes. After pairing or business activity, create a fresh fixture home. See+[the fixture recipe](../../.agents/skills/test-t3-app/references/sqlite-fixtures.md).++Follow [local verification](verification.md) for client coverage, evidence, and environment lifetime.+The app testing skill includes Electron debug attachment; mobile testing resolves development identity+from app configuration rather than copied identifiers.+## Build, check, test- `vp run build`: Fans out over `apps/*`, `packages/*`, `oxlint-plugin-t3code`, and `scripts`.Workspaces that define a build task run one: desktop, marketing, server (which depends on web), andweb. Shared packages are consumed and bundled transitively rather than built separately.- `vp run build:desktop`: Builds the desktop pipeline (desktop plus server).+- `vp run test:desktop-smoke`: Launches the built app with the installed raw Electron runtime in+ temporary application and OS homes. Requires backend-ready and main-window-created logs without+ a fatal error or early exit, then stops its captured process group and removes its temporary data.+ This proves startup, not renderer interaction. See the desktop testing skill for that check.- `vp run start`: Runs the production server (serves the built web app as static files).- `vp check`: Vite+ format, lint, and type checks. This repo sets `typeCheck: false` in its lintoptions, so workspace type checking runs separately.diff --git a/docs/internals/verification.md b/docs/internals/verification.mdnew file mode 100644index 000000000..da66752b7--- /dev/null+++ b/docs/internals/verification.md@@ -0,0 +1,45 @@+# Local verification++Use this policy with the repository's web/desktop and mobile testing skills. The policy owns authorization, coverage, evidence, and process lifetime; the skills own launch and control steps.++## Authorization++A request to implement or fix a change includes permission to run focused local tests and verify the affected client in an isolated environment. Use background browser automation or an available simulator. Ask first before controlling the user's live desktop session, using a physical device, downloading runtimes, or changing external state. An explicit request to avoid a browser, simulator, or build takes precedence; report the resulting verification limit.++## Choose the proof++Before editing, identify the affected entry points, clients, providers, contracts, reverse actions, and connection modes using the checklist in `AGENTS.md`. Mark unrelated cases as not applicable rather than running every possible combination.++- Add a focused regression test for each testable behavior change. Run it and targeted lint/type checks.+- For visible or interactive changes, exercise the affected flow end to end in a real client after integrating changes. The primary agent owns this pass; subagents do not launch separate environments.+- Visit routes that share the changed state or components. Check the reverse action, relevant empty/error states, and existing surrounding behavior.+- Check persistence after reload or reconnect when state is meant to survive it. For synchronization changes, check another client against the same environment.+- Check desktop and mobile viewport sizes when web layout changes. Run native mobile verification for React Native changes; a narrow web viewport is not a mobile client.+- Run Electron for shell, IPC, native menu, protocol, preload, packaged-origin, startup, or lifecycle changes. Web verification covers shared renderer behavior only.+- Keep provider calls bounded. Use fixtures or test adapters when they prove the change; do not invoke every paid provider merely because the checklist names them.+- Wait on receipts and worker drains in server tests. Use observable UI state for client transitions, not fixed sleeps as proof of completion.++An empty disconnected screen, an HTTP success, a passing unit test, and a screenshot each prove different things. None alone proves an interactive feature works.++## Data++Use deterministic projection fixtures for visual states and safe snapshots of real data for data-specific defects. Direct projection writes do not prove command handling or event history. Exercise business behavior through application commands or APIs. Keep one server owner per home and stop it before fixture writes.++## Environment lifetime++Retain the owned environment, authenticated client, and useful fixtures while the user is reviewing or iterating. Reuse them on later turns after confirming ownership and health. This applies to web, desktop, Metro, and simulator streams alike.++Tear down when the user requests it or the task is finished without pending human review. Stop only captured process handles or owned process groups. Leave pre-existing apps, devices, and servers alone. Remove test connections and port forwarding before removing their environment. Delete only directories created for this test; preserve reproduction evidence when useful.++## Evidence++Keep a small verification record outside tracked source files. Record:++- The revision or local changes tested, client, home, and relevant device or viewport.+- Each action, expected result, and observed result.+- Focused test commands and outcomes.+- Relevant screenshots or video, with credentials excluded.+- Cases not tested and the reason.+- Retained environment ownership and safe teardown details, when applicable.++In the final response, summarize what passed and what remains unverified. For a simple task, a short test summary is enough. Tool failures are blockers to the affected proof, not successful verification.diff --git a/scripts/verification-guidance.test.ts b/scripts/verification-guidance.test.tsnew file mode 100644index 000000000..8e0824190--- /dev/null+++ b/scripts/verification-guidance.test.ts@@ -0,0 +1,41 @@+// @effect-diagnostics nodeBuiltinImport:off+import * as NodeFS from "node:fs";+import * as NodePath from "node:path";+import * as NodeURL from "node:url";+import { assert, it } from "@effect/vitest";++const root = NodeURL.fileURLToPath(new URL("../", import.meta.url));+const guidance = [+ "AGENTS.md",+ "docs/internals/scripts.md",+ ".agents/skills/test-t3-app/SKILL.md",+ ".agents/skills/test-t3-app/references/sqlite-fixtures.md",+ ".agents/skills/test-t3-mobile/SKILL.md",+ ".agents/skills/ios-debugger-agent/SKILL.md",+ ".agents/skills/ios-simulator-browser/SKILL.md",+ "docs/internals/verification.md",+];++for (const relativePath of guidance) {+ it(`resolves local reference links in ${relativePath}`, () => {+ const filename = NodePath.join(root, relativePath);+ const content = NodeFS.readFileSync(filename, "utf8");+ const links = Array.from(content.matchAll(/\]\(([^)]+)\)/g), (match) => match[1]!);+ const localLinks = links.filter((link) => !/^(?:[a-z]+:|#)/i.test(link));+ for (const link of localLinks) {+ const target = NodePath.resolve(NodePath.dirname(filename), link.split("#")[0]!);+ assert.isTrue(NodeFS.existsSync(target), `${relativePath}: ${link}`);+ }+ });+}++it("keeps the worktree setup sequence connected to its implementation", () => {+ const config = JSON.parse(NodeFS.readFileSync(NodePath.join(root, "t3.json"), "utf8"));+ assert.deepEqual(+ config.scripts+ .filter((script: { runOnWorktreeCreate?: boolean }) => script.runOnWorktreeCreate)+ .map((script: { command: string }) => script.command),+ ["vp i && node scripts/setup-worktree-env.ts && node apps/web/scripts/warm-dep-cache.ts"],+ );+ assert.isTrue(NodeFS.existsSync(NodePath.join(root, "scripts/setup-worktree-env.ts")));+});