@ouro.bot/cli 0.1.0-alpha.66 → 0.1.0-alpha.661

package/dist/trips/store.js

@@ -0,0 +1,265 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TripNotFoundError = void 0;
+exports.ensureAgentTripLedger = ensureAgentTripLedger;
+exports.readAgentTripKeypair = readAgentTripKeypair;
+exports.upsertTripRecord = upsertTripRecord;
+exports.readTripRecord = readTripRecord;
+exports.listTripIds = listTripIds;
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const identity_1 = require("../heart/identity");
+const runtime_1 = require("../nerves/runtime");
+const core_1 = require("./core");
+function tripsRoot(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "trips");
+}
+function legacyTripsRoot(agentName) {
+    return path.join((0, identity_1.getAgentRoot)(agentName), "state", "trips");
+}
+function ledgerPath(agentName) {
+    return path.join(tripsRoot(agentName), "ledger.json");
+}
+function recordsDir(agentName) {
+    return path.join(tripsRoot(agentName), "records");
+}
+function recordPath(agentName, tripId) {
+    return path.join(recordsDir(agentName), `${tripId}.json`);
+}
+function ledgerPathFor(root) {
+    return path.join(root, "ledger.json");
+}
+function recordsDirFor(root) {
+    return path.join(root, "records");
+}
+function removeMigrationTempRoot(tmpRoot) {
+    const records = recordsDirFor(tmpRoot);
+    if (fs.existsSync(records)) {
+        for (const entry of fs.readdirSync(records)) {
+            fs.unlinkSync(path.join(records, entry));
+        }
+        fs.rmdirSync(records);
+    }
+    const ledger = ledgerPathFor(tmpRoot);
+    if (fs.existsSync(ledger)) {
+        fs.unlinkSync(ledger);
+    }
+    if (fs.existsSync(tmpRoot)) {
+        fs.rmdirSync(tmpRoot);
+    }
+}
+function copyLegacyTripsIfNeeded(agentName) {
+    const durableRoot = tripsRoot(agentName);
+    const legacyRoot = legacyTripsRoot(agentName);
+    if (fs.existsSync(durableRoot) || !fs.existsSync(ledgerPathFor(legacyRoot))) {
+        return;
+    }
+    const tmpRoot = `${durableRoot}.tmp-${process.pid}-${Date.now()}`;
+    removeMigrationTempRoot(tmpRoot);
+    try {
+        fs.mkdirSync(recordsDirFor(tmpRoot), { recursive: true });
+        fs.copyFileSync(ledgerPathFor(legacyRoot), ledgerPathFor(tmpRoot));
+        const legacyRecordsDir = recordsDirFor(legacyRoot);
+        if (fs.existsSync(legacyRecordsDir)) {
+            for (const entry of fs.readdirSync(legacyRecordsDir)) {
+                if (entry.endsWith(".json")) {
+                    fs.copyFileSync(path.join(legacyRecordsDir, entry), path.join(recordsDirFor(tmpRoot), entry));
+                }
+            }
+        }
+        fs.renameSync(tmpRoot, durableRoot);
+    }
+    catch (error) {
+        removeMigrationTempRoot(tmpRoot);
+        throw error;
+    }
+}
+function collectStoreFiles(root) {
+    const files = [];
+    if (fs.existsSync(ledgerPathFor(root))) {
+        files.push("ledger.json");
+    }
+    const records = recordsDirFor(root);
+    if (fs.existsSync(records)) {
+        for (const entry of fs.readdirSync(records)) {
+            if (entry.endsWith(".json")) {
+                files.push(`records/${entry}`);
+            }
+        }
+    }
+    return files.sort();
+}
+function fileAt(root, relativePath) {
+    return path.join(root, ...relativePath.split("/"));
+}
+function findLegacyDifferences(durableRoot, legacyRoot) {
+    const paths = new Set([...collectStoreFiles(durableRoot), ...collectStoreFiles(legacyRoot)]);
+    const differences = [];
+    for (const relativePath of [...paths].sort()) {
+        const durablePath = fileAt(durableRoot, relativePath);
+        const legacyPath = fileAt(legacyRoot, relativePath);
+        const durableExists = fs.existsSync(durablePath);
+        const legacyExists = fs.existsSync(legacyPath);
+        if (durableExists !== legacyExists) {
+            differences.push(relativePath);
+            continue;
+        }
+        if (durableExists && !fs.readFileSync(durablePath).equals(fs.readFileSync(legacyPath))) {
+            differences.push(relativePath);
+        }
+    }
+    return differences;
+}
+function reportLegacyDivergence(agentName) {
+    const durableRoot = tripsRoot(agentName);
+    const legacyRoot = legacyTripsRoot(agentName);
+    if (!fs.existsSync(durableRoot) || !fs.existsSync(legacyRoot)) {
+        return;
+    }
+    const differences = findLegacyDifferences(durableRoot, legacyRoot);
+    if (differences.length === 0) {
+        return;
+    }
+    (0, runtime_1.emitNervesEvent)({
+        level: "warn",
+        component: "trips",
+        event: "trips.legacy_diverged",
+        message: "legacy trip store differs from durable trip store",
+        meta: {
+            agentId: agentName,
+            durablePath: "trips",
+            legacyPath: "state/trips",
+            differenceCount: differences.length,
+            differences: differences.slice(0, 10),
+        },
+    });
+}
+function prepareTripStorage(agentName) {
+    copyLegacyTripsIfNeeded(agentName);
+    reportLegacyDivergence(agentName);
+}
+function readJsonFile(filePath) {
+    if (!fs.existsSync(filePath))
+        return null;
+    return JSON.parse(fs.readFileSync(filePath, "utf-8"));
+}
+function writeJsonAtomic(filePath, value) {
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    const tmp = `${filePath}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(value, null, 2), "utf-8");
+    fs.renameSync(tmp, filePath);
+}
+class TripNotFoundError extends Error {
+    statusCode = 404;
+    constructor(input) {
+        super(`trip not found: agent=${input.agentName} trip=${input.tripId}`);
+    }
+}
+exports.TripNotFoundError = TripNotFoundError;
+/**
+ * Idempotent — if the agent already has a ledger on disk, return it; otherwise
+ * generate a fresh keypair and persist both halves.
+ */
+function ensureAgentTripLedger(input) {
+    prepareTripStorage(input.agentName);
+    const existing = readJsonFile(ledgerPath(input.agentName));
+    if (existing) {
+        return { ledger: existing.ledger, added: false };
+    }
+    const created = (0, core_1.newTripLedgerRecord)({
+        agentId: input.agentName,
+        ...(input.label ? { label: input.label } : {}),
+        ...(input.now ? { now: input.now } : {}),
+    });
+    const stored = {
+        schemaVersion: 1,
+        ledger: created.ledger,
+        privateKeyPem: created.keypair.privateKeyPem,
+    };
+    writeJsonAtomic(ledgerPath(input.agentName), stored);
+    (0, runtime_1.emitNervesEvent)({
+        component: "trips",
+        event: "trips.ledger_created",
+        message: "agent trip ledger keypair created",
+        meta: { agentId: input.agentName, ledgerId: created.ledger.ledgerId, keyId: created.ledger.keyId },
+    });
+    return { ledger: created.ledger, added: true };
+}
+function readLedgerOrThrow(agentName) {
+    prepareTripStorage(agentName);
+    const stored = readJsonFile(ledgerPath(agentName));
+    if (!stored) {
+        throw new Error(`no trip ledger for agent ${agentName} — call ensureAgentTripLedger first`);
+    }
+    return stored;
+}
+function readAgentTripKeypair(agentName) {
+    const stored = readLedgerOrThrow(agentName);
+    return {
+        keyId: stored.ledger.keyId,
+        publicKeyPem: stored.ledger.publicKeyPem,
+        privateKeyPem: stored.privateKeyPem,
+    };
+}
+function upsertTripRecord(agentName, trip) {
+    const stored = readLedgerOrThrow(agentName);
+    const payload = (0, core_1.encryptTripRecord)(trip, stored.ledger.publicKeyPem, stored.ledger.keyId);
+    writeJsonAtomic(recordPath(agentName, trip.tripId), payload);
+    (0, runtime_1.emitNervesEvent)({
+        component: "trips",
+        event: "trips.record_upserted",
+        message: "trip record upserted",
+        meta: { agentId: agentName, tripId: trip.tripId, legCount: trip.legs.length, status: trip.status },
+    });
+}
+function readTripRecord(agentName, tripId) {
+    prepareTripStorage(agentName);
+    const payload = readJsonFile(recordPath(agentName, tripId));
+    if (!payload)
+        throw new TripNotFoundError({ agentName, tripId });
+    const stored = readLedgerOrThrow(agentName);
+    return (0, core_1.decryptTripRecord)(payload, stored.privateKeyPem);
+}
+function listTripIds(agentName) {
+    prepareTripStorage(agentName);
+    const dir = recordsDir(agentName);
+    if (!fs.existsSync(dir))
+        return [];
+    return fs.readdirSync(dir)
+        .filter((entry) => entry.endsWith(".json"))
+        .map((entry) => entry.slice(0, -".json".length))
+        .sort();
+}

package/dist/util/frontmatter.js

@@ -0,0 +1,69 @@
+"use strict";
+/**
+ * Shared YAML-ish frontmatter parser.
+ *
+ * Originally lived in `src/repertoire/tasks/parser.ts`. Hoisted to
+ * `src/util/` as part of W6 Unit 8b so habit-parser, habit-migration,
+ * and await-parser can consume it without depending on the deprecated
+ * task module. Behavior unchanged from the original implementation.
+ *
+ * This is a pure-data helper: no side effects, no nerves observability of
+ * its own. Callers (habit-parser, await-parser, etc.) emit nerves events
+ * around parse calls, which is the right ownership boundary.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFrontmatter = parseFrontmatter;
+function parseScalar(raw) {
+    const value = raw.trim();
+    if (value === "null")
+        return null;
+    if (value === "true")
+        return true;
+    if (value === "false")
+        return false;
+    if (value === "[]")
+        return [];
+    if ((value.startsWith("\"") && value.endsWith("\"")) || (value.startsWith("'") && value.endsWith("'"))) {
+        return value.slice(1, -1);
+    }
+    return value;
+}
+function parseFrontmatter(raw) {
+    const frontmatter = {};
+    const lines = raw.split(/\r?\n/);
+    for (let idx = 0; idx < lines.length; idx += 1) {
+        const line = lines[idx];
+        if (!line.trim())
+            continue;
+        const match = /^([A-Za-z0-9_:-]+):\s*(.*)$/.exec(line);
+        if (!match)
+            continue;
+        const key = match[1];
+        const inline = match[2];
+        if (inline.length > 0) {
+            frontmatter[key] = parseScalar(inline);
+            continue;
+        }
+        const items = [];
+        let cursor = idx + 1;
+        while (cursor < lines.length && /^\s*-\s+/.test(lines[cursor])) {
+            items.push(parseScalar(lines[cursor].replace(/^\s*-\s+/, "")));
+            cursor += 1;
+        }
+        if (items.length > 0) {
+            frontmatter[key] = items;
+            idx = cursor - 1;
+            continue;
+        }
+        const nested = {};
+        cursor = idx + 1;
+        while (cursor < lines.length && /^\s+[A-Za-z0-9_:-]+:\s*/.test(lines[cursor])) {
+            const child = /^\s+([A-Za-z0-9_:-]+):\s*(.*)$/.exec(lines[cursor]);
+            nested[child[1]] = parseScalar(child[2]);
+            cursor += 1;
+        }
+        frontmatter[key] = Object.keys(nested).length > 0 ? nested : items;
+        idx = cursor - 1;
+    }
+    return frontmatter;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ouro.bot/cli",
-  "version": "0.1.0-alpha.66",
+  "version": "0.1.0-alpha.661",
   "main": "dist/heart/daemon/ouro-entry.js",
   "bin": {
     "cli": "dist/heart/daemon/ouro-bot-entry.js",
@@ -9,8 +9,9 @@
   },
   "files": [
     "dist/",
-    "AdoptionSpecialist.ouro/",
-    "subagents/",
+    "SerpentGuide.ouro/",
+    "RepairGuide.ouro/",
+    "skills/",
     "assets/",
     "changelog.json"
   ],
@@ -19,37 +20,79 @@
     "./runOuroCli": "./dist/heart/daemon/daemon-cli.js"
   },
   "scripts": {
-    "dev": "tsc && node dist/senses/cli-entry.js --agent ouroboros",
+    "dev": "tsc && node dist/heart/daemon/ouro-bot-entry.js dev",
+    "cli": "tsc && node dist/senses/cli-entry.js",
     "daemon": "tsc && node dist/heart/daemon/daemon-entry.js",
     "ouro": "tsc && node dist/heart/daemon/ouro-entry.js",
     "teams": "tsc && node dist/senses/teams-entry.js --agent ouroboros",
-    "bluebubbles": "tsc && node dist/senses/bluebubbles-entry.js --agent ouroboros",
+    "bluebubbles": "tsc && node dist/senses/bluebubbles/entry.js --agent ouroboros",
+    "voice:eval": "npm run build && node dist/senses/voice-realtime-eval-entry.js",
+    "worktree:bootstrap": "npm install --ignore-scripts",
     "test": "vitest run",
+    "test:integration": "npm run build && vitest run --config vitest.integration.config.ts",
+    "test:e2e:package": "npm run build && node scripts/package-e2e.cjs",
+    "test:e2e:real-smoke": "npm run build && node scripts/nightly-real-smoke.cjs",
+    "typecheck:mailbox-ui": "tsc --noEmit -p packages/mailbox-ui/tsconfig.json",
+    "test:mailbox-ui": "npm test --prefix packages/mailbox-ui",
     "test:coverage:vitest": "vitest run --coverage",
     "test:coverage": "node scripts/run-coverage-gate.cjs",
-    "build": "tsc",
+    "build": "node scripts/build.cjs",
     "lint": "eslint src/",
+    "package:verify-assets": "node scripts/package-assets.cjs",
+    "prepack": "npm run build && npm run package:verify-assets",
+    "release:bump": "node scripts/release-bump.cjs",
+    "release:preflight": "node scripts/release-preflight.cjs",
+    "release:trust:check": "node scripts/npm-trusted-publishers.cjs check",
+    "release:trust:repair-plan": "node scripts/npm-trusted-publishers.cjs repair-plan",
+    "release:trust:repair": "node scripts/npm-trusted-publishers.cjs repair",
+    "release:smoke": "node scripts/release-smoke.cjs",
     "audit:nerves": "npm run build && node dist/nerves/coverage/cli-main.js"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.78.0",
     "@azure/identity": "^4.13.0",
-    "@microsoft/teams.apps": "^2.0.5",
-    "@microsoft/teams.dev": "^2.0.5",
+    "@azure/storage-blob": "^12.31.0",
+    "@microsoft/teams.api": "2.0.11",
+    "@microsoft/teams.apps": "2.0.11",
+    "@microsoft/teams.cards": "2.0.11",
+    "@microsoft/teams.common": "2.0.11",
+    "@microsoft/teams.dev": "2.0.11",
+    "@microsoft/teams.graph": "2.0.11",
+    "@types/react": "^17.0.91",
+    "@types/ws": "^8.18.1",
     "fast-glob": "^3.3.3",
+    "ink": "^3.2.0",
+    "mailparser": "^3.9.8",
     "openai": "^6.27.0",
-    "semver": "^7.7.4"
+    "react": "^17.0.2",
+    "semver": "^7.7.4",
+    "smtp-server": "^3.18.4",
+    "stripe": "^22.0.0",
+    "ws": "^8.20.0"
   },
   "repository": {
     "type": "git",
-    "url": "https://github.com/ouroborosbot/ouroboros"
+    "url": "git+https://github.com/ourostack/ouroboros.git"
   },
   "devDependencies": {
+    "@testing-library/react": "^16.3.2",
+    "@types/mailparser": "^3.4.6",
     "@types/semver": "^7.7.1",
-    "@vitest/coverage-v8": "^4.0.18",
+    "@types/smtp-server": "^3.5.13",
+    "@vitest/coverage-v8": "^4.1.8",
     "eslint": "^10.0.2",
+    "jsdom": "^29.0.2",
     "typescript": "^5.7.0",
     "typescript-eslint": "^8.56.1",
-    "vitest": "^4.0.18"
+    "vitest": "^4.1.8"
+  },
+  "overrides": {
+    "@microsoft/teams.apps": {
+      "@azure/msal-node": "^5.2.2"
+    },
+    "@testing-library/react": {
+      "react": "$react",
+      "@types/react": "$@types/react"
+    }
   }
 }

package/skills/agent-commerce.md

@@ -0,0 +1,113 @@
+# Agent Commerce Skill
+
+How to book, purchase, and pay for things on behalf of humans.
+
+## Three Patterns
+
+### Pattern A: API (Structured, Preferred)
+
+For services with direct API access: Duffel flights, LiteAPI hotels.
+
+1. Search using the API tool (`flight_search`, LiteAPI MCP)
+2. Present options to the human with prices and details
+3. Create a checkout preview with `commerce_checkout_preview` for the exact merchant, item, amount, currency, allowed tool, and exact tool constraints
+4. Human approves in a new message that exactly equals the preview's `confirmationMessage`, including checkout id, digest, merchant, amount, currency, allowed tool, and constraints
+5. Commit the preview with `commerce_checkout_commit`; then call the approved payment or booking tool with the exact amount, currency, and constraints from the preview. Ouro consumes the matching authority without exposing a bearer token in the transcript.
+6. Book using the API tool with passenger data from `user_profile_get`
+7. Create a single-use virtual card via `stripe_create_card` when needed
+8. Complete payment through the API
+9. Deactivate the card via `stripe_deactivate_card`
+10. Confirm booking to the human and record/read back the receipt with `commerce_receipt_get`
+
+**Key tools**: `commerce_checkout_preview`, `commerce_checkout_commit`, `commerce_receipt_get`, `flight_search`, `flight_book`, `flight_cancel`, `user_profile_get`, `user_profile_store`, `stripe_create_card`, `stripe_deactivate_card`, `stripe_list_cards`
+
+### Pattern B: Browser (Best-Effort)
+
+For sites without API access, use browser automation via Playwright MCP.
+
+1. Navigate to the booking site
+2. Search for the requested service
+3. Fill forms using data from `user_profile_get`
+4. Create and commit a checkout preview before entering payment details
+5. Use a virtual card from `stripe_create_card` for payment
+6. If blocked by anti-bot measures, fall back to Pattern C
+7. Complete and confirm the booking
+
+**Limitations**: Browser automation is fragile. Sites may block, layouts change, CAPTCHAs appear. Always have Pattern C as fallback.
+
+### Pattern C: Link-Only (Primary for Hostile Sites)
+
+For sites that block automation or require complex human interaction.
+
+1. Research the best options using browser tools or API tools
+2. Prepare a curated link with pre-filled parameters where possible
+3. Send the link to the human with a summary of what to book
+4. Human completes the booking in their own browser
+
+**When to use**: Always use Pattern C as the primary approach for sites known to block automation (most airline direct sites, hotel chains, rental car sites). Pattern B is best-effort, not reliable.
+
+## Payment autonomy Levels
+
+- **Level 0**: No autonomous payments. Agent researches, human pays manually.
+- **Level 1**: Agent creates virtual cards, human approves each transaction explicitly.
+- **Level 2**: Agent can book pre-approved items (within budget, approved categories) without per-transaction approval.
+- **Level 3**: Full delegation with spending limits. Agent manages a budget and books as needed.
+
+Default is Level 1. Level changes require explicit human approval.
+
+## Commerce Authority
+
+Money-moving tools (`stripe_create_card`, `flight_hold`, `flight_book`) require a one-use confirmed commerce authority. This is the local AP2-compatible primitive: an exact mandate record with merchant, amount, currency, allowed tool, exact tool constraints, reason, digest, expiry, confirmation, reservation/attempt/consumption state, and access log. `commerce_checkout_commit` confirms the authority but does not reveal a live bearer token to the model; the runtime reserves the one matching confirmed authority under a checkout lock, marks it attempted before crossing an external provider boundary, and consumes it only after the successful side effect is verified. A pre-attempt validation failure can release the reservation; an attempted Stripe/Duffel call stays non-replayable so ambiguous provider failures cannot create duplicate cards or bookings. Stripe card authority must include exact `type` and `merchant_categories` constraints so the card is counterparty/category-bound. If the tool, amount, currency, offer id, card type, merchant category, or other constraint changes, create a new preview and get a new confirmation.
+
+## Error Handling
+
+### Price Change Guard
+Before completing a booking, verify the final price matches the approved price within 5%. If the price changed more than 5%, stop and report to the human. Never pay a price the human didn't approve.
+
+### Partial Failure Reporting
+When booking involves multiple services (e.g., flight + hotel), each service may succeed or fail independently — this is a partial failure scenario. Report the status of each service separately. **Never auto-cancel a successful booking because a related booking failed.** Let the human decide.
+
+Example: "Flight SFO-JFK booked (confirmation: ABC123). Hotel booking failed: no availability for those dates. Would you like me to search for alternative hotels?"
+
+### Refund Flow
+If a booking fails after card creation:
+1. Deactivate the virtual card immediately
+2. Report the failure to the human
+3. If a charge was made, note it for the human to follow up with the provider
+
+## CAPTCHA Handling
+
+When a CAPTCHA appears during browser automation (Pattern B):
+1. Take a screenshot and send it to the human
+2. Explain what page you're on and what you were trying to do
+3. Ask the human to solve the CAPTCHA in their own browser
+4. Switch to Pattern C (link-only) for this transaction
+
+Never attempt to solve CAPTCHAs programmatically.
+
+## Card Number Isolation
+
+Card numbers must NEVER appear in:
+- Tool return values shown to the model
+- Nerves events or logs
+- Chat messages to the human
+- Any stored state or written notes
+
+The only place card numbers exist is inside the Stripe client's internal payment flow functions, scoped to a single function call. The model only ever sees card IDs and last-4 digits.
+
+## Profile Data Usage
+
+Access profile data only when needed for the current transaction:
+- `user_profile_get` to retrieve specific fields (never dump full profile)
+- Passport data only for international bookings
+- Loyalty program numbers only when booking with that program
+- Emergency contact only when the booking service requires it
+
+## Self-Test
+
+Before first use, run the commerce self-test to verify all services are configured:
+- Stripe: creates and deactivates a test virtual card
+- Duffel: runs a test flight search
+- LiteAPI: verifies API key in vault
+
+Report results to the human with actionable next steps for any failures.

package/skills/browser-navigation.md

@@ -0,0 +1,117 @@
+# Browser Navigation Skill
+
+When to use browser tools and how to navigate effectively.
+
+## When to Use Browser Tools
+
+Use browser navigation when:
+- The target site has no API (e.g., Airbnb, VRBO, travel blogs)
+- Content is dynamic or requires JavaScript rendering
+- Login-required pages need session-based access
+- You need to verify visual content (screenshots, layouts)
+- Price comparison requires real-time scraping
+
+Do NOT use browser tools when:
+- A dedicated API or MCP server exists (prefer `weather_lookup`, Duffel MCP, etc.)
+- The data is available via a public JSON endpoint
+- The task can be completed with `web_search`
+
+## Stealth Browsing Best Practices
+
+The `@playwright/mcp` server is configured with realistic user-agent and viewport settings. To avoid detection on travel sites:
+
+- **Add delays between navigations**: Wait 2-5 seconds between page loads. Never hammer requests in rapid succession.
+- **Vary timing**: Use random delays rather than fixed intervals (e.g., 2-5s, not exactly 3s every time).
+- **Avoid predictable patterns**: Don't navigate the same path repeatedly in short succession.
+- **Use realistic scroll behavior**: Scroll gradually through pages rather than jumping to specific elements.
+- **Respect robots.txt**: Check for rate limits and crawling restrictions.
+
+## Navigation Workflow
+
+Follow this pattern for every page interaction:
+
+1. **Navigate**: Use `browser_navigate` to load the page
+2. **Wait**: Allow the page to fully load (use `browser_wait` if needed)
+3. **Snapshot**: Take a `browser_snapshot` to understand the page structure
+4. **Extract**: Parse the accessibility tree for relevant data
+5. **Screenshot** (optional): Use `browser_screenshot` for visual confirmation
+
+## Form Filling Patterns
+
+### Login Flows
+1. Navigate to the login page
+2. Take a snapshot to identify form fields
+3. Use `browser_type` for username/password fields
+4. Use `browser_click` to submit
+5. Wait for redirect, then verify login succeeded via snapshot
+6. NEVER hardcode credentials -- use `credential_get` to retrieve login info
+
+### Sign-up Flows
+1. Use `credential_generate_password` to mint a strong password for the target domain
+2. Fill the signup form with that password
+3. If the site rejects the password policy, generate a new one that matches the site rules
+4. Once the site accepts the exact password, call `credential_store` immediately
+5. Do not claim a new credential is saved until `credential_store` succeeds
+
+### Search Forms (Hotels, Flights, Rentals)
+1. Navigate to the search page
+2. Snapshot to identify input fields
+3. Fill location/date fields with `browser_type`
+4. Select options with `browser_select_option` or `browser_click`
+5. Submit the search
+6. Wait for results to load (travel sites often have loading animations)
+7. Snapshot the results page to extract listings
+
+### Booking Forms
+1. **ALWAYS confirm with the user before proceeding to payment**
+2. Fill traveler information
+3. Use stored credentials for payment (via `credential_get` -- NEVER type raw card numbers)
+4. Screenshot the final review page for user confirmation
+5. Only click "Book" / "Confirm" after explicit user approval
+
+## Anti-Bot Detection Avoidance
+
+The stealth configuration handles most fingerprinting automatically. Additionally:
+
+- **Don't access detection endpoints**: Avoid URLs containing "captcha", "challenge", "verify"
+- **Handle CAPTCHAs**: If you encounter a CAPTCHA, pause and inform the user. Do not attempt automated solving.
+- **Rotate viewport sizes occasionally**: Use different viewport sizes across sessions
+- **Maintain cookies**: Use persistent `user-data-dir` to appear as a returning user
+- **Avoid headless tells**: The user-agent is set to a real browser string
+
+## Travel Site Patterns
+
+### Airbnb / VRBO
+1. Search by location + check-in/check-out dates + guests
+2. Results load dynamically -- scroll to load more listings
+3. Extract: title, price per night, total price, rating, number of reviews
+4. For detailed info, click into each listing and snapshot
+5. Compare top 3-5 options
+
+### Hotel Sites (Booking.com, Hotels.com)
+1. Search by destination + dates + guests + rooms
+2. Filter by price range, star rating, amenities
+3. Extract: name, price, location, rating, key amenities
+4. Check cancellation policies (important for travel planning)
+
+### Flight Comparison
+1. Prefer Duffel MCP for flight search (structured API data)
+2. Use browser only if Duffel doesn't cover the airline
+3. Google Flights is useful for price comparison but requires careful navigation
+
+## Error Handling
+
+- **Page timeouts**: Retry once after 5 seconds. If still failing, inform the user.
+- **CAPTCHAs**: Stop and ask the user to solve manually.
+- **Stale elements**: Re-snapshot the page and retry the interaction.
+- **Blocked/403**: The site may have detected automation. Wait 30 seconds and try with a different approach (e.g., direct URL instead of navigation).
+- **Session expired**: Re-login using stored credentials.
+
+## Human Confirmation Gates
+
+**ALWAYS** confirm with the user before:
+- Any booking or payment action
+- Entering personal information (name, address, phone)
+- Agreeing to terms of service
+- Subscribing to any service
+- Any action that creates a financial obligation