mercury-agent 0.5.2 → 0.5.6

package/docs/debug/major/2026-07-02-registry-pull-no-local-fallback.md

@@ -1,194 +0,0 @@
-# Bug: mercury run fails when registry pull fails but local build exists
-
-**Status:** Fixed  
-**Severity:** P1 — blocks users who build locally but have a registry image configured  
-**Introduced in:** 0.4.22 (commit 75e8e71)  
-**File:** `src/cli/mercury.ts`, `runAction()` (~line 187)  
-**Last updated:** 2026-07-02
-
-## Symptom
-
-```
-$ mercury build          # succeeds → mercury-agent:latest exists locally
-$ mercury run
-Image 'ghcr.io/avishai-tsabari/mercury-agent:latest' not found locally, pulling...
-Error response from daemon: unauthorized
-
-Error: Failed to pull 'ghcr.io/avishai-tsabari/mercury-agent:latest'.
-If this is a private registry, authenticate first:
-  docker login ghcr.io
-```
-
-The user has a working local image (`mercury-agent:latest`) from `mercury build`,
-but `mercury run` exits with an error because the configured registry image
-can't be pulled (private registry, no auth, offline, etc.).
-
-## Root cause
-
-The 0.4.22 change replaced the local-fallback logic with auto-pull. The old
-code tried `mercury-agent:latest` as a fallback when the configured image
-wasn't found. The new code attempts `docker pull` and hard-exits on failure —
-it never checks whether a locally built image exists.
-
-### Before (0.4.21)
-
-```
-configured image not found?
-  → try mercury-agent:latest locally
-    → found? use it (with warning)
-    → not found? error: pull or build
-```
-
-### After (0.4.22)
-
-```
-configured image not found?
-  → is registry image? attempt pull
-    → pull fails? hard exit  ← BUG: should fall back to local
-  → not registry? error: run mercury build
-```
-
-## Fix
-
-After a failed pull of a registry image, check if `mercury-agent:latest`
-exists locally before giving up. If it does, use it with a warning.
-
-### Implementation (lines ~187–213 of `src/cli/mercury.ts`)
-
-Replace the current block:
-
-```typescript
-if (imageCheck.status !== 0) {
-    const isRegistryImage = imageName.includes("/");
-    if (isRegistryImage) {
-      console.log(`Image '${imageName}' not found locally, pulling...`);
-      const pull = spawnSync("docker", ["pull", imageName], {
-        stdio: "inherit",
-      });
-      if (pull.signal) {
-        process.exit(1);
-      }
-      if (pull.status !== 0) {
-        const firstSegment = imageName.split("/")[0];
-        const registry = firstSegment.includes(".")
-          ? firstSegment
-          : "docker.io";
-        console.error(`\nError: Failed to pull '${imageName}'.`);
-        console.error(
-          "If this is a private registry, authenticate first:\n" +
-            `  docker login ${registry}`,
-        );
-        process.exit(1);
-      }
-    } else {
-      console.error(`Error: Container image '${imageName}' not found.`);
-      console.error("Run 'mercury build' to build it.");
-      process.exit(1);
-    }
-  }
-```
-
-With:
-
-```typescript
-if (imageCheck.status !== 0) {
-    const isRegistryImage = imageName.includes("/");
-    let resolved = false;
-
-    if (isRegistryImage) {
-      console.log(`Image '${imageName}' not found locally, pulling...`);
-      const pull = spawnSync("docker", ["pull", imageName], {
-        stdio: "inherit",
-      });
-      if (pull.signal) {
-        process.exit(1);
-      }
-      if (pull.status === 0) {
-        resolved = true;
-      }
-    }
-
-    // Fallback: if the configured image isn't available (pull failed, not a
-    // registry image, or never pulled), try the local build tag.
-    if (!resolved) {
-      const localTag = "mercury-agent:latest";
-      if (imageName !== localTag) {
-        const localCheck = spawnSync("docker", ["image", "inspect", localTag], {
-          stdio: "pipe",
-        });
-        if (localCheck.status === 0) {
-          console.log(
-            `\nℹ️  Using locally built ${localTag} (configured image unavailable)\n`,
-          );
-          process.env.MERCURY_AGENT_IMAGE = localTag;
-          resolved = true;
-        }
-      }
-    }
-
-    if (!resolved) {
-      if (isRegistryImage) {
-        const firstSegment = imageName.split("/")[0];
-        const registry = firstSegment.includes(".")
-          ? firstSegment
-          : "docker.io";
-        console.error(`\nError: Failed to pull '${imageName}'.`);
-        console.error(
-          "If this is a private registry, authenticate first:\n" +
-            `  docker login ${registry}\n` +
-            "Or build locally:\n" +
-            "  mercury build",
-        );
-      } else {
-        console.error(`Error: Container image '${imageName}' not found.`);
-        console.error("Run 'mercury build' to build it.");
-      }
-      process.exit(1);
-    }
-  }
-```
-
-### Behavior after fix
-
-```
-configured image not found?
-  → is registry image? attempt pull
-    → pull succeeds? use it ✓
-    → pull fails? continue to fallback
-  → try mercury-agent:latest locally
-    → found? use it (with info message) ✓
-    → not found? error with both suggestions (login + build) ✓
-```
-
-## How to verify
-
-1. Build locally: `mercury build`
-2. Ensure no GHCR auth: `docker logout ghcr.io`
-3. Set `.env` to `MERCURY_AGENT_IMAGE=ghcr.io/avishai-tsabari/mercury-agent:latest`
-4. Run `mercury run` — should fall back to local image with info message
-5. Remove local image: `docker rmi mercury-agent:latest`
-6. Run `mercury run` — should error with both `docker login` and `mercury build` suggestions
-
----
-
-## Post-Mortem
-
-### Investigation
-Triaged from a hanging bug doc during `/f-doc-sync`. First confirmed the fix was NOT already present: grepped `src/` for any local-fallback logic (`Using locally built`, `localTag`, `resolved`) — zero hits — and read `runAction()` in `src/cli/mercury.ts` (lines 186–216), which was still the buggy 0.4.22 version that hard-exits on pull failure. Fixed in an isolated worktree.
-
-### Root Cause
-The 0.4.22 auto-pull rewrite dropped the pre-existing local-image fallback. When the configured image was a registry ref and `docker pull` failed (private registry / no auth / offline), `runAction()` called `process.exit(1)` immediately, never checking whether a locally built `mercury-agent:latest` existed.
-
-### Fix
-`src/cli/mercury.ts`, `runAction()` (committed to main as `1c120bf`):
-- Introduced a `resolved` flag. A registry pull sets it on success; on failure, control falls through instead of exiting.
-- Added a fallback block: if unresolved and the configured image isn't already `mercury-agent:latest`, `docker image inspect mercury-agent:latest`; if present, use it with an info message.
-- Only after both paths fail does it `process.exit(1)`, now suggesting **both** `docker login` and `mercury build`.
-- **Beyond the original fix guide:** the child is spawned with `env: { ...process.env, ...envVars }`, and `envVars` (loaded from `.env`, which typically pins `MERCURY_AGENT_IMAGE` to the registry) wins that merge. Setting only `process.env.MERCURY_AGENT_IMAGE` would have been silently clobbered — the repro scenario itself. The fix therefore also sets `envVars.MERCURY_AGENT_IMAGE = localTag`. Confirmed load-bearing by the session code review.
-
-Verification: `bun run typecheck` + `bun run lint` clean; `bun test` → 1039 pass / 0 fail; session code review returned "No issues found."
-
-### Lessons
-- When a spawn merges multiple env sources (`{ ...process.env, ...envVars }`), an override must be written to the **last-wins** source, not just `process.env` — otherwise it's silently reverted.
-- Behavior-replacing rewrites (the 0.4.22 auto-pull change) should preserve existing fallbacks explicitly; a regression test for "pull fails but local image exists" would have caught this.
-- Reconcile hanging bug docs against current code before opening a fix — two sibling P0/P1 docs (`e2big`, `bwrap-privileged`) turned out already fixed; only this one needed work.

package/docs/debug/summarization/2026-07-02-common-bug-patterns.md

@@ -1,72 +0,0 @@
-# Common Bug Patterns
-
-**Date:** 2026-07-02
-**Covers:** 1 bug report (1 major, 0 moderate, 0 minor) · 2026-07-01 → 2026-07-01
-
-This is the first bug-pattern summary. It covers a single major incident — the strict-YAML-schema crash — but that one bug braids together several distinct, reusable failure patterns worth capturing before they recur: over-strict input validation, unbounded restart loops, and the fragile-transport amplification that turns any crash into extended downtime. The dominant theme is **conflation**: treating "unknown input" and "invalid input" as the same failure, and treating "one crash" as harmless when the surrounding system amplifies it.
-
-## Findings
-
-### 1. Over-strict input validation (unknown key ≠ invalid value)
-
-Schemas that reject unrecognized input with the same severity as malformed input turn benign drift (typos, renamed fields, version skew) into hard failures.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | `mercuryFileSchema` used Zod `.strict()` on all 13 nested objects, so a single unknown `mercury.yaml` key (e.g. renamed `admin_numbers` → `admin_ids`) crashed startup with the same severity as an invalid value. |
-
-**Rule:** Separate "unknown key" (warn, strip, continue) from "invalid value" (fail fast). Default config schemas to strip-and-warn on unrecognized keys; reserve hard failure for values that are actually wrong.
-
-### 2. Version-skew intolerance
-
-Config that must be exactly in sync with the running binary breaks on every field rename, punishing the normal lifecycle of upgrades and rollbacks.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | A field renamed between 0.4.26 and 0.4.27 (`admin_numbers` → `admin_ids`) crashed any deployment whose yaml hadn't been updated in lockstep. |
-
-**Rule:** Any feature that adds or renames a config field must assume a user on version N may run a yaml from version N±1. Forward/backward-unknown keys should degrade gracefully, not crash.
-
-### 3. Unbounded restart loops amplify a single failure
-
-A deterministic startup error plus an unbounded auto-restarter converts one crash into an infinite crash loop, removing any window for human intervention.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | PM2's default unlimited restarts retried the identical failing config forever, each attempt failing the same way. |
-
-**Rule:** Configure `max_restarts` + `min_uptime` on process supervisors so a deterministic failure stops after N attempts and alerts, rather than looping. A restart policy is not a substitute for handling the error.
-
-### 4. Fragile-transport amplification
-
-When a downstream dependency punishes rapid reconnection, an unrelated crash loop escalates into a much costlier outage than the original bug.
-
-| Bug | What went wrong |
-|-----|-----------------|
-| strict-yaml-schema-crash | The crash loop drove rapid WhatsApp/Baileys reconnects, which Meta treats as abuse → session revoked (reason=401) → manual QR re-scan required for recovery. |
-
-**Rule:** Treat any crash loop as catastrophic when a session-based/unofficial transport is in play. Isolate transport-session lifecycle from process restarts, and prefer a circuit breaker that keeps the host alive while surfacing the error.
-
-## Summary table
-
-| Pattern | Count | Worst severity |
-|---------|-------|----------------|
-| Over-strict input validation | 1 | major |
-| Version-skew intolerance | 1 | major |
-| Unbounded restart loops | 1 | major |
-| Fragile-transport amplification | 1 | major |
-
-## Comparison with previous summary
-
-None — this is the first bug-pattern summary. Future summaries should track whether validation-strictness and restart-loop patterns recur once the fixes above land.
-
-## Decisions
-
-1. **Adopt strip-and-warn as the config default** across all schemas; audit remaining `.strict()` usages for the same class of crash.
-2. **Set supervisor restart limits** (`max_restarts`, `min_uptime`) plus an alert on limit-hit, so no deterministic failure can loop indefinitely.
-3. **Design a container/transport circuit breaker** (the bug's own Phase 2) so container-level errors log-and-recover instead of crashing the host and endangering the WhatsApp session.
-
-## Open Questions
-
-- Should config validation ever hard-fail on unknown keys in a "strict mode" opt-in for CI, while defaulting to warn in production?
-- What is the right `max_restarts` threshold given Baileys' revocation sensitivity — and should transport reconnection back off independently of process restarts?

package/docs/ideas/business-extensions.md

@@ -1,48 +0,0 @@
----
-name: business-extensions
-description: Dedicated business extensions that wrap raw capabilities (GWS, etc.) with deterministic domain logic — e.g. a barber-appointments extension
-metadata:
-  type: idea
----
-
-# Business Extensions
-
-**Status**: Idea
-**Created**: 2026-07-01
-
-## Problem
-
-Raw capability extensions (GWS Calendar, Gmail, web search) expose generic APIs. Business workflows (appointment booking, customer management) require deterministic logic — availability checks, double-booking prevention, confirmation flows — that can't be reliably delegated to the LLM via prompting alone.
-
-Today the only options are: (1) let the LLM orchestrate raw APIs via system prompt instructions (not deterministic enough), or (2) build a full standalone application outside Mercury. Neither is ideal.
-
-## Idea
-
-A pattern for **business extensions** that wrap raw capabilities with domain-specific, deterministic logic and expose simplified CLIs to the agent.
-
-Example: `barber-appointments` extension
-- Wraps GWS Calendar internally
-- Exposes: `book-appointment`, `list-availability`, `cancel-appointment`
-- Enforces business rules in code: no double-booking, business hours only, minimum slot duration, confirmation required
-- Registers as a single Mercury permission (`barber-appointments`)
-- The LLM calls the simplified CLI; the extension handles the hard logic deterministically
-
-This separates concerns:
-- **Mercury** = platform (messaging, spaces, permissions, rate limits)
-- **Capability extensions** = raw API access (GWS, web search, etc.) — admin-only or building blocks
-- **Business extensions** = deterministic domain logic wrapping capabilities — customer-facing
-
-## Why not just prompt engineering?
-
-LLMs are non-deterministic. For a barber shop, a double-booked appointment or a cancelled-without-confirmation is a real-world problem. Business rules must be enforced in code, not hoped for via prompts.
-
-## Open questions
-
-- Should business extensions be a separate category in the extension system, or just a convention?
-- How do business extensions declare their dependency on capability extensions (e.g., `barber-appointments` needs `gws`)?
-- Should there be a template/scaffold for creating business extensions?
-- How does this relate to "profiles" — is a profile = business extension + config preset?
-
-## First candidate
-
-`barber-appointments` — Calendar-based appointment booking for a barber shop. Quick win for first customer impression. Gmail integration deferred.

package/docs/runbooks/gws-oauth-setup.md

@@ -1,211 +0,0 @@
-# GWS OAuth Setup Runbook
-
-How to connect Google Calendar to a customer's Mercury assistant.
-
-## Prerequisites
-
-- Access to the Tagula GCP project (console.cloud.google.com, project "Tagula")
-- SSH access to the customer's VPS
-- The customer's `MERCURY_API_SECRET` (from their `.env`)
-- The customer's Google account email
-
-## Option A: Auth Gateway (preferred — works on mobile + desktop)
-
-Use this when `auth.tagula.ai` is set up. Customer just clicks a link.
-
-### One-time gateway setup
-
-> Skip if the gateway is already running at `auth.tagula.ai`.
-
-1. **DNS**: Add an A record for `auth.tagula.ai` → gateway server IP (GoDaddy DNS panel)
-
-2. **Server**: SSH into the gateway server and install nginx + certbot:
-   ```bash
-   apt-get update && apt-get install -y nginx certbot python3-certbot-nginx
-   ```
-
-3. **Nginx config** (`/etc/nginx/sites-available/auth-tagula`):
-   ```nginx
-   server {
-       listen 80;
-       server_name auth.tagula.ai;
-       location / {
-           proxy_pass http://127.0.0.1:3456;
-           proxy_set_header Host $host;
-           proxy_set_header X-Forwarded-For $remote_addr;
-       }
-   }
-   ```
-   ```bash
-   ln -s /etc/nginx/sites-available/auth-tagula /etc/nginx/sites-enabled/
-   nginx -t && systemctl reload nginx
-   ```
-
-4. **SSL**:
-   ```bash
-   certbot --nginx -d auth.tagula.ai
-   ```
-
-5. **Gateway config**: Copy `gateway-config.example.json` → `gateway-config.json`, fill in:
-   - `google.clientId` and `google.clientSecret` from the Tagula GCP project
-   - `google.redirectUri` = `https://auth.tagula.ai/oauth/callback`
-
-6. **GCP redirect URI**: In GCP Console → APIs & Services → Credentials → Web client → add `https://auth.tagula.ai/oauth/callback` to Authorized redirect URIs
-
-7. **Start gateway**:
-   ```bash
-   npm install -g pm2  # if not installed
-   pm2 start auth-gateway.js --name auth-gateway
-   pm2 save
-   ```
-
-### Per-customer setup
-
-1. **Add customer to gateway config** (`gateway-config.json`):
-   ```json
-   "assistants": {
-     "customer-name": {
-       "apiUrl": "http://<VPS_IP>:8787",
-       "apiSecret": "<MERCURY_API_SECRET from customer's .env>",
-       "envVar": "MERCURY_GWS_CREDENTIALS_JSON"
-     }
-   }
-   ```
-   Restart gateway: `pm2 restart auth-gateway`
-
-2. **Add test user in GCP**: GCP Console → Google Auth Platform → Audience → Add users → add customer's Gmail
-
-3. **Install gws extension on customer VPS** (if not already):
-   ```bash
-   ssh root@<VPS_IP>
-   # Via dashboard: go to http://<VPS_IP>:8787/dashboard/page/features → Install gws
-   # Or via API:
-   curl -X POST http://localhost:8787/api/console/extensions/install \
-     -H "Authorization: Bearer <API_SECRET>" \
-     -H "Content-Type: application/json" \
-     -d '{"catalogName": "gws"}'
-   ```
-
-4. **Send the link to customer**:
-   ```
-   https://auth.tagula.ai/connect/gws?assistant=customer-name
-   ```
-   Customer clicks → signs in with Google → sees "Connected!" → done.
-
-5. **Verify**: Check Mercury logs on the VPS:
-   ```bash
-   pm2 logs 'mercury run' --lines 20 --nostream | grep -i gws
-   ```
-   Should show: `Loaded extension: gws` and `Installed skill: gws`
-
----
-
-## Option B: Manual (ngrok — no gateway needed)
-
-Use this before the gateway is set up, or as a one-off.
-
-### Setup
-
-1. **Install ngrok on customer VPS**:
-   ```bash
-   ssh root@<VPS_IP>
-   curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \
-     | tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null
-   echo 'deb https://ngrok-agent.s3.amazonaws.com buster main' \
-     | tee /etc/apt/sources.list.d/ngrok.list
-   apt-get update && apt-get install -y ngrok
-   ngrok config add-authtoken <YOUR_NGROK_TOKEN>
-   ```
-
-2. **Write callback script** (`/tmp/oauth-callback.js`):
-   ```bash
-   # Copy from tagula-agents-cloud-console/oauth-callback-standalone.js
-   # Update CLIENT_ID and CLIENT_SECRET from GCP
-   scp oauth-callback-standalone.js root@<VPS_IP>:/tmp/oauth-callback.js
-   ```
-
-3. **Start callback + ngrok**:
-   ```bash
-   ssh root@<VPS_IP>
-   nohup node /tmp/oauth-callback.js > /tmp/oauth-callback.log 2>&1 &
-   ngrok http 9999
-   ```
-   Note the ngrok URL (e.g., `https://abc123.ngrok-free.dev`)
-
-4. **Configure redirect URI**:
-   - Set redirect URI in the callback script:
-     ```bash
-     curl "http://localhost:9999/set-redirect?uri=https://<NGROK_URL>/oauth/callback"
-     ```
-   - Add same URL to GCP: APIs & Services → Credentials → Web client → Authorized redirect URIs
-
-5. **Add test user**: GCP → Google Auth Platform → Audience → Add customer's Gmail
-
-6. **Send OAuth link to customer**:
-   ```
-   https://accounts.google.com/o/oauth2/v2/auth?client_id=<CLIENT_ID>&redirect_uri=https://<NGROK_URL>/oauth/callback&response_type=code&scope=https://www.googleapis.com/auth/calendar.events&access_type=offline&prompt=consent
-   ```
-
-7. **After customer authorizes**:
-   - ngrok free tier shows an interstitial — customer clicks "Visit Site"
-   - Check logs: `cat /tmp/oauth-callback.log`
-   - Should show `SUCCESS - credentials saved`
-
-8. **Move credentials to correct .env** (the callback script writes to `.mercury/.env` but Mercury reads from project root `.env`):
-   ```bash
-   grep MERCURY_GWS /opt/path/to/assistant/.mercury/.env >> /opt/path/to/assistant/.env
-   sed -i '/MERCURY_GWS/d' /opt/path/to/assistant/.mercury/.env
-   ```
-
-9. **Restart Mercury and clean up**:
-   ```bash
-   pm2 restart 'mercury run'
-   # Kill callback server and ngrok
-   kill $(lsof -ti:9999) 2>/dev/null
-   pkill ngrok
-   rm /tmp/oauth-callback.js /tmp/oauth-callback.log
-   ```
-
-10. **Verify**:
-    ```bash
-    pm2 logs 'mercury run' --lines 20 --nostream | grep -i gws
-    ```
-
----
-
-## Option C: Copy-paste URL (desktop only)
-
-Simplest, no infrastructure needed. Customer must be on a computer (not mobile).
-
-1. **Create Desktop-type OAuth client** in GCP (not Web) — allows `http://localhost` redirect
-2. **Generate OAuth URL** with `redirect_uri=http://localhost:1`
-3. **Send link to customer** — they click, authorize, Google redirects to localhost (fails)
-4. **Customer copies the full URL** from their browser bar and sends it back
-5. **Extract code and exchange**:
-   ```bash
-   # Extract code from the URL the customer sent
-   CODE="the_code_from_url"
-   curl -s -X POST https://oauth2.googleapis.com/token \
-     -d "code=$CODE&client_id=<CLIENT_ID>&client_secret=<CLIENT_SECRET>&redirect_uri=http://localhost:1&grant_type=authorization_code"
-   ```
-6. **Set env var and restart** — copy the tokens JSON into `.env` as `MERCURY_GWS_CREDENTIALS_JSON='...'`
-
----
-
-## Troubleshooting
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| `invalid_client` on Google consent | Client not propagated yet, or created in new Auth Platform UI | Wait 10 min, or recreate from legacy APIs & Services → Credentials |
-| Extension installs but doesn't load | `MERCURY_GWS_CREDENTIALS_JSON` not set or in wrong `.env` | Check `grep MERCURY_GWS .env` in project root |
-| `Removed stale skill: gws` in logs | Extension skipped by credential gate | Same as above — credential missing |
-| `Failed to build derived image` | `docker-buildx` not installed | `apt-get install docker-buildx` |
-| Customer's wrong Google account used | Browser auto-selects default account | Add all their accounts as test users, or use incognito |
-| ngrok "Visit Site" interstitial | Free tier warning | Customer clicks "Visit Site" — shows once |
-| `refresh_token_expires_in: 604799` | Token expires in 7 days (testing mode) | Publish the OAuth app in GCP to get non-expiring refresh tokens |
-
-## Important notes
-
-- **Test mode tokens expire in 7 days.** While the GCP app is in "Testing" status, refresh tokens expire after 7 days. To get permanent tokens, publish the app (requires Google verification for sensitive scopes). For now, re-run the OAuth flow when tokens expire.
-- **docker-buildx** is required on Linux servers for Mercury to build derived images with extension CLIs. Install with `apt-get install docker-buildx`.
-- **Rotate credentials** after sharing them in chat. Go to GCP → Credentials → Web client → rotate client secret. Update `gateway-config.json` and any callback scripts.

package/docs/runbooks/publish-checklist.md

@@ -1,54 +0,0 @@
-# Publish Checklist
-
-Before publishing a new version to npm:
-
-1. **`bun run check`** — typecheck + lint + tests
-2. **`mercury build`** — if you touched build path, Dockerfiles, or file-copy logic
-3. **`mercury init` + `mercury service install`** in a test project — if you touched CLI flow, config loading, or service management
-4. **Smoke test assistants** — send a message, verify they respond
-
-## Version bump & publish
-
-```bash
-npm version patch --no-git-tag-version   # or minor/major
-git add package.json
-git commit -m "chore: bump version to $(node -p 'require("./package.json").version')"
-git tag "v$(node -p 'require("./package.json").version')"
-git push && git push --tags
-
-# Publish to npm manually. npm 2FA requires an interactive one-time
-# password, so this cannot run in CI — pass it inline (it expires in ~30s):
-npm publish --otp=<code-from-authenticator>
-```
-
-Always tag and publish together — `package.json` is the single source of truth for both npm and GitHub.
-
-**CI does not publish to npm.** Pushing a `v*` tag runs `bun run check` and creates a
-GitHub Release (`.github/workflows/release.yml`), but the npm upload is a manual step
-done by a maintainer from a local machine. Verify afterward with
-`npm view mercury-agent version`.
-
-## Beta testing on another machine
-
-Use `--tag beta` to publish a test version without affecting the stable `latest` tag.
-
-```bash
-# 1. Bump to a beta prerelease
-npm version prerelease --preid=beta   # e.g. 0.4.24 → 0.4.25-beta.0
-
-# 2. Publish under the beta tag (won't affect `npm install mercury-agent`)
-npm publish --tag beta
-
-# 3. On the other machine, install the beta
-npm install -g mercury-agent@beta
-
-# 4. Test, iterate. Bump again if needed:
-npm version prerelease --preid=beta   # 0.4.25-beta.0 → 0.4.25-beta.1
-npm publish --tag beta
-
-# 5. When satisfied, promote to stable:
-npm version patch                     # 0.4.25-beta.1 → 0.4.25
-npm publish                           # publishes to "latest"
-```
-
-`npm install -g mercury-agent` (without @beta) always gets the stable version. Only explicit `@beta` gets the test version.

package/docs/templates/TEMPLATE-AUTOPILOT-CONFIG.yaml

@@ -1,35 +0,0 @@
-# Autopilot Configuration
-# Copy this file to docs/autopilot/config.yaml and customize.
-# The orchestrator script reads this file each iteration.
-
-gates:
-  max_iterations: 10                   # stop after N iterations per session
-  max_features_without_review: 3       # stop after completing N features/bugs without human review
-  max_retries_same_task: 3             # skip a task after N failed attempts
-  iteration_timeout_minutes: 30        # kill a single execute phase after this long
-
-risk:
-  sensitive_paths:                     # changes to these = immediate stop for review
-    - "**/auth/**"
-    - "**/migration*"
-    - "**/.env*"
-    - "**/schema*"
-  auto_stop_risk_threshold: 8          # risk_score >= this from assess = stop
-
-scope:
-  allowed_actions:                     # which actions the autopilot may take
-    - implement_feature
-    - continue_feature
-    - fix_bug
-    - sync_docs
-    # - propose_decomposition          # uncomment to enable autonomous planning (requires allow_autonomous_planning: true)
-  skip_slugs:                           # slugs to never touch autonomously
-    # - my-feature-slug
-
-planning:
-  allow_autonomous_planning: false     # when true, autopilot can decompose ideas into draft plans (requires propose_decomposition in allowed_actions)
-                                       # plans land as Status: Proposed and always stop for human review
-
-notifications:
-  on_stop: console                     # "console" | "file" (future: "slack", "email")
-  decision_log: docs/autopilot/decision-log.md