@agentrysh/mcp 0.0.13 → 0.0.15

package/dist/tools.js

@@ -6,22 +6,49 @@ import { api } from "./api.js";
 import { loadConfig, saveConfig } from "./config.js";
 import { getOnboardingHint } from "./onboarding.js";
 import { getMemoryPath, readCaseSection, upsertCaseSection, MEMORY_FILENAME, } from "./memory.js";
+import * as frictionTracker from "./friction-tracker.js";
 import * as fs from "node:fs";
 export const TOOL_DESCRIPTORS = [
     {
         name: "agentry_status",
         description: "Show what's set up locally and what to do next. Always safe to call. " +
-            "Use this first if you don't know whether the user has signed up or has a project.",
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            "Use this first if you don't know whether the user has signed up or has a project. " +
+            "" +
+            "If shapes + flags are passed (same vocabulary as agentry_recipe_requirements), the " +
+            "response also includes a coverage_gap report — applicable_count, runnable_count, and " +
+            "the events / event-properties still missing for full recipe runnability. Useful for " +
+            "re-installs and post-install audits: 'ready, but seat-utilization is one property " +
+            "away from working' is a more honest status than just 'ready'.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                shapes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "Optional. App shapes for coverage check (e.g. ['b2b-saas', 'devtools-api']). " +
+                        "When passed, response includes coverage_gap. Without it, status is project-only.",
+                },
+                has_revenue: { type: "boolean" },
+                is_b2b: { type: "boolean" },
+                is_two_sided: { type: "boolean" },
+                project_id: {
+                    type: "string",
+                    description: "Project id for the coverage check. Defaults to default_project_id.",
+                },
+            },
+            additionalProperties: false,
+        },
     },
     {
         name: "agentry_login",
-        description: "Authenticate the user via GitHub device flow. Returns an API key, stored locally. " +
+        description: "Authenticate the user via the agentry sign-in page (GitHub, Google, or magic link — " +
+            "user picks any provider). Returns an API key, stored locally. " +
             "" +
             "RECOMMENDED two-call sequence for interactive sessions: " +
-            "  1. Call with mode='start_only' → returns user_code + verification_uri + device_code. " +
-            "     Show the user the code and URL (DO NOT ask them to confirm authorization — they'll " +
-            "     just open the URL, paste the code, and you'll poll). " +
+            "  1. Call with mode='start_only' → returns user_code + verification_uri + device_code " +
+            "     (plus verification_uri_complete with the code pre-filled). Show the user the URL " +
+            "     and code (DO NOT ask them to confirm authorization — they'll open the URL, sign in " +
+            "     with their provider of choice, and you'll poll). " +
             "  2. IMMEDIATELY call again with mode='full' + the device_code from step 1. " +
             "     This blocks and auto-polls every ~5s for up to timeout_seconds (default 300 = 5min). " +
             "     Returns the api_key when the user authorizes, or status='expired'/'denied' on failure. " +
@@ -606,15 +633,20 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         name: "agentry_repair_analytics",
-        description: "Re-attempt PostHog provisioning for the authenticated user. Idempotent — if the user " +
-            "already has a PostHog project, returns its id without recreating. Use this when " +
+        description: "Re-attempt PostHog provisioning for one project. Idempotent — if the project already " +
+            "has a PostHog team binding, returns its id without recreating. Use this when " +
             "agentry_verify_install reports analytics ❌ with reason 'no_posthog_project' OR when a " +
             "/v1/track/ call returns 503 with that code. " +
             "" +
             "DO NOT re-run agentry_login for this failure mode — that mints a new api_key and " +
-            "churns the user's local config. This tool runs only the provisioning step that was " +
-            "supposed to happen at login.",
-        inputSchema: { type: "object", properties: {}, additionalProperties: false },
+            "churns the user's local config. This tool repairs the project-scoped analytics binding only.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string", description: "Project to repair. Defaults to local default_project_id." },
+            },
+            additionalProperties: false,
+        },
     },
     {
         name: "agentry_rotate_key",
@@ -979,13 +1011,16 @@ export const TOOL_DESCRIPTORS = [
     },
     {
         name: "agentry_verify_install",
-        description: "Comprehensive sanity check: fires a synthetic error, a synthetic analytics event, and a synthetic " +
-            "deploy event, then reports which signal types reached agentry. Run this AFTER walking through " +
-            "agentry_install_guide. " +
-            "MUST be run with NO skipped signal types on a first-time install — the install is not done until " +
-            "all three return OK. If any signal returns FAIL, the corresponding wire_* step was skipped or " +
-            "wired incorrectly; the agent must go back and fix it before declaring the install complete. Do not " +
-            "report 'installed' to the user with one or two ✅s and a ❌; that's a half-install.",
+        description: "Comprehensive sanity check. Fires a synthetic error, analytics event, and deploy event AND " +
+            "— if shapes are provided — checks PostHog for the events the user's applicable recipes need. " +
+            "Run this AFTER walking through agentry_install_guide. " +
+            "" +
+            "MUST be run with NO skipped signal types on a first-time install. The install is not done " +
+            "until all three signals are OK AND every event from `required_events` (derived from the app's " +
+            "shape via agentry_recipe_requirements) is actually firing in PostHog. " +
+            "" +
+            "Do not report 'installed' to the user with one or two ✅s and a ❌, or with synthetic ✅s but " +
+            "missing recipe events — that's a half-install.",
         inputSchema: {
             type: "object",
             properties: {
@@ -996,6 +1031,26 @@ export const TOOL_DESCRIPTORS = [
                     description: "ONLY for re-runs after a partial install has already been verified. On a first install, " +
                         "leave this empty — all three signal types must verify before the install counts as done.",
                 },
+                shapes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "App shape(s) the agent detected during investigate_app_structure (e.g. ['b2b-saas', " +
+                        "'devtools-api']). When passed, verify_install also queries PostHog for the events the " +
+                        "applicable docs recipes need and reports which recipes are blocked. Strongly recommended " +
+                        "on first install — without it you only know the pipe works, not that the recipes will run.",
+                },
+                has_revenue: {
+                    type: "boolean",
+                    description: "Payment processor detected. Used with shapes to filter applicable recipes.",
+                },
+                is_b2b: {
+                    type: "boolean",
+                    description: "Workspace/account/seat model present. Used with shapes to filter applicable recipes.",
+                },
+                is_two_sided: {
+                    type: "boolean",
+                    description: "Two-sided marketplace. Used with shapes to filter applicable recipes.",
+                },
             },
             additionalProperties: false,
         },
@@ -1018,6 +1073,49 @@ export const TOOL_DESCRIPTORS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "agentry_recipe_requirements",
+        description: "Recipe-driven install gate. Given the user's detected app shape(s) and revenue/B2B/two-sided " +
+            "flags, returns the *applicable* docs recipes and the UNION of events they need. The install guide " +
+            "uses this output as the canonical event inventory: every event in `required_events` MUST be wired, " +
+            "with the listed `required_event_properties` attached, before agentry_verify_install passes. " +
+            "" +
+            "CALL THIS during agentry_install_guide's inventory step, AFTER categorizing the app, BEFORE writing " +
+            "any track() calls. Don't hand-build an AARRR inventory — let the recipe catalog drive what to " +
+            "instrument so the user can actually run the recipes a week / month later. " +
+            "" +
+            "shapes: comma-sep app shapes from the install-guide vocabulary (b2c-saas, b2b-saas, ecommerce, " +
+            "marketplace, content-media, devtools-api, games, internal-tool, single-purchase, open-source, " +
+            "enterprise-sales, mobile-app). 'universal' recipes always match. " +
+            "has_revenue: true if the app has a payment processor (stripe/paddle/etc.) — gates revenue recipes. " +
+            "is_b2b: true if the app has workspaces/accounts/seats — gates B2B recipes. " +
+            "is_two_sided: true if the app is a marketplace with supply/demand — gates marketplace recipes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                shapes: {
+                    type: "array",
+                    items: { type: "string" },
+                    description: "App shape(s) detected during investigate_app_structure. Apps can straddle (e.g. a B2B SaaS " +
+                        "that's also a devtools API). Pass every shape that fits — applicable recipes are the union.",
+                },
+                has_revenue: {
+                    type: "boolean",
+                    description: "Payment processor present in the codebase. Gates trial/subscription/churn recipes.",
+                },
+                is_b2b: {
+                    type: "boolean",
+                    description: "Workspace/account/seat model present. Gates account-health, seat-utilization, etc.",
+                },
+                is_two_sided: {
+                    type: "boolean",
+                    description: "Two-sided marketplace. Gates supply-side/liquidity recipes.",
+                },
+            },
+            required: ["shapes"],
+            additionalProperties: false,
+        },
+    },
     {
         name: "agentry_run_recipe",
         description: "Run a recipe by id. Returns rows + a render_hint the agent uses to format the answer " +
@@ -1257,12 +1355,19 @@ export const TOOL_DESCRIPTORS = [
     {
         name: "agentry_send_feedback",
         description: "File feedback for the agentry team when something doesn't work or is missing. " +
-            "Call this in exactly two situations: " +
+            "Call this in three situations: " +
             "(1) the user explicitly asks for a feature that doesn't exist or expresses frustration that agentry " +
             "isn't doing what they want ('I wish it could…', 'why doesn't it…', 'this doesn't work', " +
             "'feature request: …'); " +
             "(2) you have made 2+ failed attempts at the same task — same MCP tool returning errors, or repeatedly " +
-            "failing to find a recipe/route for what the user asked. " +
+            "failing to find a recipe/route for what the user asked; " +
+            "(3) RECIPE PROPOSAL — during agentry_install_guide's plan-confirmation step, the user named a " +
+            "question they want to be able to ask that ISN'T in the docs recipe catalog. Use " +
+            "`kind: 'recipe_proposal'`, quote the user's question in `message`, and put a structured " +
+            "proposal in `agent_note` (the JSON shape described under that field). This is the only path " +
+            "from a customer's install back into the recipe catalog — without it, every novel question " +
+            "stays stranded in chat history. " +
+            "" +
             "File it ONCE per distinct issue per session — don't spam. Quote the user verbatim in `message` where " +
             "possible. Don't apologize repeatedly to the user; just tell them you've logged it.",
         inputSchema: {
@@ -1270,9 +1375,13 @@ export const TOOL_DESCRIPTORS = [
             properties: {
                 kind: {
                     type: "string",
-                    enum: ["missing_feature", "bug", "ux_friction", "other"],
+                    enum: ["missing_feature", "bug", "ux_friction", "recipe_proposal", "other"],
                     description: "missing_feature = capability doesn't exist; bug = something behaves wrong; " +
-                        "ux_friction = works but is awkward/confusing; other = anything else.",
+                        "ux_friction = works but is awkward/confusing; " +
+                        "recipe_proposal = user named a question to ask that no docs recipe covers — " +
+                        "use during install flow; agent_note MUST include the proposed applies_to / " +
+                        "required_events / required_event_properties so the catalog can absorb it; " +
+                        "other = anything else.",
                 },
                 message: {
                     type: "string",
@@ -1282,7 +1391,17 @@ export const TOOL_DESCRIPTORS = [
                 agent_note: {
                     type: "string",
                     description: "Optional: what YOU (the agent) were trying to do, which tools you called, what failed. " +
-                        "Helps the agentry team reproduce.",
+                        "Helps the agentry team reproduce. " +
+                        "" +
+                        "FOR kind='recipe_proposal' THIS FIELD IS REQUIRED and must be JSON-shaped, e.g.: " +
+                        "{\"applies_to\": [\"b2b-saas\"], \"requires_revenue\": true, \"required_events\": " +
+                        "[\"workspace_created\", \"template_first_action\"], \"required_event_properties\": " +
+                        "{\"workspace_created\": [\"starter_template\"]}, \"category\": \"growth\", " +
+                        "\"suggested_title\": \"Which starter template has the highest 30-day retention?\", " +
+                        "\"detected_shape_evidence\": \"workspaces.starter_template column present at " +
+                        "db/schema.ts:23\", \"new_events_wired\": [\"workspace_created.starter_template\", " +
+                        "\"template_first_action\"]}. " +
+                        "The catalog maintainers paste this shape into a new recipe.md with minimal editing.",
                 },
                 tool_name: {
                     type: "string",
@@ -1339,6 +1458,59 @@ export const TOOL_DESCRIPTORS = [
             additionalProperties: false,
         },
     },
+    {
+        name: "agentry_invite_teammate",
+        description: "Mint a one-shot invite URL granting a teammate access to a project. Owner-only. " +
+            "The recipient opens the URL, signs in with any provider (GitHub / Google / magic link), " +
+            "and gets their own agentry account + API key automatically scoped to this project — they " +
+            "do NOT use your API key. " +
+            "" +
+            "After this returns, share `invite_url` with your teammate (Slack, email — manual for v1). " +
+            "Invite expires in 7 days, single-use.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string", description: "Defaults to the local default project." },
+                email: {
+                    type: "string",
+                    description: "Optional — shown on the invite landing page as a hint to the recipient. " +
+                        "Does NOT restrict who can consume the invite; the link is the credential.",
+                },
+                role: {
+                    type: "string",
+                    enum: ["member", "owner"],
+                    description: "Defaults to 'member'. 'owner' is rare — only add other owners deliberately.",
+                },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_list_members",
+        description: "List members of a project + any pending (un-consumed, un-expired) invites. " +
+            "Any member can see the full roster; remove members via agentry_remove_member.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string", description: "Defaults to the local default project." },
+            },
+            additionalProperties: false,
+        },
+    },
+    {
+        name: "agentry_remove_member",
+        description: "Remove a teammate from a project. Owner-only. Cannot remove the last remaining owner, " +
+            "and an owner cannot remove themselves (transfer ownership first — TBD).",
+        inputSchema: {
+            type: "object",
+            properties: {
+                project_id: { type: "string", description: "Defaults to the local default project." },
+                user_id: { type: "string", description: "The user_id from agentry_list_members." },
+            },
+            required: ["user_id"],
+            additionalProperties: false,
+        },
+    },
 ];
 // ---------------------------------------------------------------------------
 // Helpers shared across tool handlers
@@ -1438,10 +1610,49 @@ function buildSyntheticEvent() {
 }
 export async function dispatchTool(name, args) {
     const a = args ?? {};
+    let result;
+    try {
+        result = await dispatchToolInner(name, a);
+    }
+    catch (err) {
+        frictionTracker.recordCall({
+            tool: name,
+            ts: Date.now(),
+            ok: false,
+            errorCode: err instanceof Error ? err.message.slice(0, 80) : String(err).slice(0, 80),
+        });
+        // Repeated-failure detector — fires when same tool errors N times in a row.
+        try {
+            frictionTracker.detectRepeatedFailure(loadConfig(), name);
+        }
+        catch { /* swallow — observability never breaks the request */ }
+        return summarizeApiError(err);
+    }
+    // Record success/failure outcome. `error` shape on the result means handler
+    // returned an error envelope without throwing.
+    const ok = !("error" in (result ?? {}));
+    frictionTracker.recordCall({ tool: name, ts: Date.now(), ok });
+    try {
+        if (!ok)
+            frictionTracker.detectRepeatedFailure(loadConfig(), name);
+        if (name === "agentry_install_guide") {
+            frictionTracker.detectGuideRefetched(loadConfig());
+        }
+    }
+    catch { /* swallow */ }
+    return result;
+}
+async function dispatchToolInner(name, a) {
     try {
         switch (name) {
             case "agentry_status":
-                return handleStatus();
+                return await handleStatus({
+                    shapes: Array.isArray(a.shapes) ? a.shapes.map(String) : undefined,
+                    has_revenue: a.has_revenue === true,
+                    is_b2b: a.is_b2b === true,
+                    is_two_sided: a.is_two_sided === true,
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                });
             case "agentry_login":
                 return await handleLogin({
                     mode: a.mode === "start_only" || a.mode === "poll_once"
@@ -1453,7 +1664,7 @@ export async function dispatchTool(name, args) {
             case "agentry_rotate_key":
                 return await handleRotateKey();
             case "agentry_repair_analytics":
-                return await handleRepairAnalytics();
+                return await handleRepairAnalytics(a.project_id ? String(a.project_id) : undefined);
             case "agentry_publish_query":
                 return await handlePublishQuery({
                     project_id: a.project_id ? String(a.project_id) : undefined,
@@ -1724,9 +1935,20 @@ export async function dispatchTool(name, args) {
                 return await handleVerifyInstall({
                     project_id: a.project_id ? String(a.project_id) : undefined,
                     skip: Array.isArray(a.skip) ? a.skip.map(String) : [],
+                    shapes: Array.isArray(a.shapes) ? a.shapes.map(String) : undefined,
+                    has_revenue: a.has_revenue === true,
+                    is_b2b: a.is_b2b === true,
+                    is_two_sided: a.is_two_sided === true,
                 });
             case "agentry_list_recipes":
                 return await handleListRecipes(a.category ? String(a.category) : undefined);
+            case "agentry_recipe_requirements":
+                return await handleRecipeRequirements({
+                    shapes: Array.isArray(a.shapes) ? a.shapes.map(String) : [],
+                    has_revenue: a.has_revenue === true,
+                    is_b2b: a.is_b2b === true,
+                    is_two_sided: a.is_two_sided === true,
+                });
             case "agentry_run_recipe":
                 return await handleRunRecipe({
                     recipe_id: String(a.recipe_id ?? ""),
@@ -1821,6 +2043,19 @@ export async function dispatchTool(name, args) {
                     kind: a.kind ? String(a.kind) : undefined,
                     resolved: typeof a.resolved === "boolean" ? a.resolved : undefined,
                 });
+            case "agentry_invite_teammate":
+                return await handleInviteTeammate({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    email: a.email ? String(a.email) : undefined,
+                    role: a.role === "owner" ? "owner" : "member",
+                });
+            case "agentry_list_members":
+                return await handleListMembers(a.project_id ? String(a.project_id) : undefined);
+            case "agentry_remove_member":
+                return await handleRemoveMember({
+                    project_id: a.project_id ? String(a.project_id) : undefined,
+                    user_id: String(a.user_id ?? ""),
+                });
             default:
                 return {
                     error: {
@@ -1835,14 +2070,15 @@ export async function dispatchTool(name, args) {
         return summarizeApiError(err);
     }
 }
+// dispatchToolInner is closed above. Below: handlers.
 // ---------------------------------------------------------------------------
 // Tool handlers
 // ---------------------------------------------------------------------------
-function handleStatus() {
+async function handleStatus(input) {
     const cfg = loadConfig();
     const hint = getOnboardingHint(cfg);
     const projectIds = Object.keys(cfg.projects);
-    return {
+    const baseResult = {
         server_url: cfg.server_url,
         has_api_key: Boolean(cfg.api_key),
         api_key_prefix: cfg.api_key ? `${cfg.api_key.slice(0, 8)}…` : null,
@@ -1850,24 +2086,114 @@ function handleStatus() {
         project_count: projectIds.length,
         projects: projectIds.map((id) => {
             const p = cfg.projects[id];
-            return { id, name: p.name, local_path: p.local_path };
+            return {
+                id,
+                name: p.name,
+                local_path: p.local_path,
+                analytics_ready: p.analytics_ready ?? null,
+                posthog_project_id: p.posthog_project_id ?? null,
+            };
         }),
         onboarding: hint,
-        next_steps: [hint.message, hint.next_action],
     };
+    // Coverage check — only runs when shapes are passed AND we have a project + api key.
+    // Independent of the onboarding hint above: status can be "ready" (synthetic signals
+    // verified) while still having coverage gaps (events firing without required props).
+    if (input?.shapes && input.shapes.length > 0 && cfg.api_key) {
+        const projectId = input.project_id ?? cfg.default_project_id;
+        if (projectId) {
+            try {
+                const reqs = await api.recipeRequirements(cfg, {
+                    shapes: input.shapes,
+                    has_revenue: input.has_revenue === true,
+                    is_b2b: input.is_b2b === true,
+                    is_two_sided: input.is_two_sided === true,
+                });
+                const events = await api.listEventNames(cfg, projectId);
+                const eventNames = new Set([
+                    ...(events.server_emitted ?? []),
+                    ...(events.analytics_events ?? []).map((e) => e.event),
+                ]);
+                // Sample property keys for events that ARE present and have required props.
+                const checkProps = new Set();
+                for (const rec of reqs.applicable) {
+                    for (const ev of Object.keys(rec.required_event_properties || {})) {
+                        if (eventNames.has(ev))
+                            checkProps.add(ev);
+                    }
+                }
+                let sampledKeys = {};
+                if (checkProps.size > 0) {
+                    try {
+                        const r = await api.eventPropertyKeys(cfg, projectId, [...checkProps]);
+                        sampledKeys = r.keys ?? {};
+                    }
+                    catch { /* best-effort */ }
+                }
+                const blocked = [];
+                const runnableIds = [];
+                for (const rec of reqs.applicable) {
+                    const missingEv = rec.required_events.filter((e) => !eventNames.has(e));
+                    const missingProp = {};
+                    for (const [ev, props] of Object.entries(rec.required_event_properties || {})) {
+                        if (!eventNames.has(ev))
+                            continue;
+                        const present = new Set(sampledKeys[ev] ?? []);
+                        const m = props.filter((p) => !present.has(p));
+                        if (m.length > 0)
+                            missingProp[ev] = m;
+                    }
+                    if (missingEv.length === 0 && Object.keys(missingProp).length === 0)
+                        runnableIds.push(rec.id);
+                    else
+                        blocked.push({ id: rec.id, title: rec.title, missing_events: missingEv, missing_properties: missingProp });
+                }
+                const missingEvUnion = new Set();
+                const missingPropUnion = new Set();
+                for (const b of blocked) {
+                    for (const e of b.missing_events)
+                        missingEvUnion.add(e);
+                    for (const [ev, props] of Object.entries(b.missing_properties))
+                        for (const p of props)
+                            missingPropUnion.add(`${ev}.${p}`);
+                }
+                baseResult.coverage_gap = {
+                    shapes: input.shapes,
+                    applicable_count: reqs.applicable_count,
+                    runnable_count: runnableIds.length,
+                    missing_events: [...missingEvUnion].sort(),
+                    missing_event_properties: [...missingPropUnion].sort(),
+                    blocked_recipes: blocked.map((b) => b.id),
+                    summary: `${runnableIds.length}/${reqs.applicable_count} applicable recipes runnable. ` +
+                        (missingEvUnion.size > 0 ? `Missing events: ${[...missingEvUnion].sort().join(", ")}. ` : "") +
+                        (missingPropUnion.size > 0 ? `Missing properties: ${[...missingPropUnion].sort().join(", ")}.` : ""),
+                };
+            }
+            catch (err) {
+                baseResult.coverage_gap = {
+                    error: err instanceof Error ? err.message : String(err),
+                    note: "coverage_gap requires logged-in api key + an existing project. Skipping.",
+                };
+            }
+        }
+    }
+    baseResult.next_steps = [hint.message, hint.next_action];
+    return baseResult;
 }
 async function handleLogin(input) {
     const cfg = loadConfig();
     if (input.mode === "start_only") {
         const start = await api.startDeviceFlow(cfg);
+        const openUrl = start.verification_uri_complete ?? start.verification_uri;
         return {
             mode: "start_only",
             verification_uri: start.verification_uri,
+            verification_uri_complete: start.verification_uri_complete,
             user_code: start.user_code,
             device_code: start.device_code,
             interval: start.interval,
             expires_in: start.expires_in,
-            next_action: `Show the user: "Open ${start.verification_uri} and enter the code ${start.user_code}." ` +
+            next_action: `Show the user a clickable link: ${openUrl} — one click takes them to sign-in, no code entry. ` +
                 `Then IMMEDIATELY call agentry_login again with mode='full' and device_code='${start.device_code}'. ` +
                 `That call will block and auto-poll for up to ${start.expires_in}s — DO NOT ask the user to confirm authorization before polling.`,
         };
@@ -1966,7 +2292,7 @@ async function handleLogin(input) {
         device_code: deviceCode,
         next_action: `Timed out after ${input.timeout_seconds ?? 300}s. ` +
             (verificationUri && userCode
-                ? `Confirm the user opened ${verificationUri} and entered ${userCode}, `
+                ? `Confirm the user opened ${verificationUri}?code=${userCode}, `
                 : "Confirm the user has authorized, ") +
             `then call agentry_login again with mode='full' and device_code='${deviceCode}' to resume polling.`,
     };
@@ -1995,7 +2321,7 @@ async function handleRotateKey() {
             "New key stored locally. Old key is revoked — update any places it was pasted (CI envs, etc).",
     };
 }
-async function handleRepairAnalytics() {
+async function handleRepairAnalytics(projectId) {
     const cfg = loadConfig();
     if (!cfg.api_key) {
         return {
@@ -2006,9 +2332,32 @@ async function handleRepairAnalytics() {
             },
         };
     }
+    const picked = pickProject(cfg, projectId);
+    if (!picked || !picked.project) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No local project selected for analytics repair.",
+                next_action: "Create a project first or pass a project_id from agentry_list_projects.",
+            },
+        };
+    }
     try {
-        const resp = await api.repairAnalyticsBackend(cfg);
-        return resp;
+        const resp = await api.repairAnalyticsBackend(cfg, picked.id);
+        const updatedProject = {
+            ...picked.project,
+            analytics_ready: resp.posthog_project_id !== null,
+            posthog_project_id: resp.posthog_project_id,
+        };
+        const nextCfg = {
+            ...cfg,
+            projects: {
+                ...cfg.projects,
+                [picked.id]: updatedProject,
+            },
+        };
+        saveConfig(nextCfg);
+        return { project_id: picked.id, ...resp };
     }
     catch (err) {
         return {
@@ -2016,7 +2365,7 @@ async function handleRepairAnalytics() {
                 code: "repair_failed",
                 message: err instanceof Error ? err.message : String(err),
                 next_action: "Upstream PostHog provisioning failed. If the error mentions 5xx / timeouts / rate " +
-                    "limits, wait 30–60s and call agentry_repair_analytics again. Errors and deploys are " +
+                    "limits, wait 30–60s and call agentry_repair_analytics again for the same project. Errors and deploys are " +
                     "unaffected; only analytics ingest needs PostHog.",
             },
         };
@@ -2425,6 +2774,8 @@ async function handleListProjects() {
             ...p,
             local_path: local?.local_path ?? null,
             dsn_known_locally: Boolean(local?.dsn),
+            analytics_ready: local?.analytics_ready ?? null,
+            posthog_project_id: local?.posthog_project_id ?? null,
             is_default: cfg.default_project_id === p.id,
         };
     });
@@ -2469,6 +2820,8 @@ async function handleCreateProject(input) {
         dsn: resp.dsn,
         local_path: input.local_path ?? null,
         default_branch: resp.default_branch ?? input.default_branch ?? "main",
+        analytics_ready: resp.analytics?.ready,
+        posthog_project_id: resp.analytics?.posthog_project_id ?? null,
     };
     const nextCfg = {
         ...cfg,
@@ -2497,6 +2850,7 @@ async function handleCreateProject(input) {
             logs_url: resp.logs_url,
             analytics_url: resp.analytics_url,
             deploys_url: resp.deploys_url,
+            analytics: resp.analytics,
         },
         install_snippet: install,
         next_action: resp.next_action ??
@@ -3188,10 +3542,21 @@ async function handleAnalyticsQuery(input) {
         };
     }
     const resp = await api.analyticsQuery(cfg, projectId, input.query);
+    // Friction: query references a named event in WHERE and got 0 rows back.
+    // Heuristic-driven (detector inspects the query string); fires only when
+    // a specific event name returned empty — most likely a missing-instrumentation
+    // or wrong-event-name signal worth flagging for AI review.
+    const rowsReturned = Array.isArray(resp.results) ? resp.results.length : 0;
+    const frictionFp = frictionTracker.detectEmptyAnalyticsQuery(cfg, {
+        query: input.query,
+        project_id: projectId,
+        rows_returned: rowsReturned,
+    });
     return {
         project_id: projectId,
         ...resp,
-        next_action: "Interpret the rows. If you suspect a regression, call agentry_list_deploys to see if a deploy correlates.",
+        next_action: "Interpret the rows. If you suspect a regression, call agentry_list_deploys to see if a deploy correlates." +
+            frictionTracker.frictionNoticeSuffix(frictionFp),
     };
 }
 // ---------------------------------------------------------------------------
@@ -3310,36 +3675,165 @@ async function handleVerifyInstall(input) {
     const analyticsDetail = checks.analytics?.detail ?? "";
     const noPosthogProject = !checks.analytics?.ok &&
         (analyticsDetail.includes("no_posthog_project") ||
-            analyticsDetail.includes("user has no PostHog project provisioned"));
+            analyticsDetail.includes("project has no PostHog project provisioned"));
     const baseAction = failed.length === 0
         ? "Install verified. Errors land in agentry_list_cases; analytics flow to PostHog; deploys via agentry_list_deploys."
         : noPosthogProject && failed.length === 1
             ? "Analytics is the only failed signal AND the cause is missing PostHog provisioning " +
-                "(first-login provisioning was best-effort and failed). Call agentry_repair_analytics " +
+                "(the project binding is missing). Call agentry_repair_analytics " +
                 "— it's idempotent and runs the same provisioning step. Then re-run agentry_verify_install. " +
                 "DO NOT re-run agentry_login for this."
             : `Install incomplete. Failed signal types: ${failed.join(", ")}. ` +
                 (noPosthogProject
-                    ? "Analytics failed because the user has no PostHog project provisioned — " +
+                    ? "Analytics failed because the project has no PostHog project provisioned — " +
                         "call agentry_repair_analytics, then re-run verify. "
                     : "") +
                 "For each failed type, re-read its corresponding step in agentry_install_guide and fix.";
+    // ── Recipe runnability check ───────────────────────────────────────────
+    // If the agent passed shapes, derive the required-events set and check
+    // PostHog for each. Report per-recipe runnability so the agent knows
+    // which docs recipes the user will actually be able to run.
+    let recipeCheck = {
+        requested: false,
+        applicable_count: 0,
+        runnable_count: 0,
+        runnable: [],
+        blocked: [],
+        missing_events: [],
+        missing_event_properties: [],
+    };
+    if (input.shapes && input.shapes.length > 0 && checks.analytics?.ok) {
+        try {
+            const cfg2 = loadConfig();
+            const reqs = await api.recipeRequirements(cfg2, {
+                shapes: input.shapes,
+                has_revenue: input.has_revenue === true,
+                is_b2b: input.is_b2b === true,
+                is_two_sided: input.is_two_sided === true,
+            });
+            // Snapshot the distinct event names currently firing in this project.
+            // listEventNames returns both server-emitted (PostHog $events) and analytics_events
+            // (PostHog person events with counts). Union them — recipes can need either.
+            const events = await api.listEventNames(cfg2, r.id);
+            const eventNames = new Set([
+                ...(events.server_emitted ?? []),
+                ...(events.analytics_events ?? []).map((e) => e.event),
+            ]);
+            // Sample property keys for the union of required events present, so we
+            // can confirm not just event presence but that the properties recipes
+            // depend on are actually being attached.
+            const eventsNeedingProps = [];
+            const propsByEvent = {};
+            for (const rec of reqs.applicable) {
+                for (const [ev, props] of Object.entries(rec.required_event_properties || {})) {
+                    if (!eventNames.has(ev))
+                        continue; // event missing entirely; separate check handles
+                    eventsNeedingProps.push(ev);
+                    for (const p of props) {
+                        propsByEvent[ev] = propsByEvent[ev] || [];
+                        if (!propsByEvent[ev].includes(p))
+                            propsByEvent[ev].push(p);
+                    }
+                }
+            }
+            let sampledKeys = {};
+            if (eventsNeedingProps.length > 0) {
+                try {
+                    const resp = await api.eventPropertyKeys(cfg2, r.id, [...new Set(eventsNeedingProps)]);
+                    sampledKeys = resp.keys ?? {};
+                }
+                catch {
+                    // best-effort — if property sampling fails, fall back to event-presence-only
+                }
+            }
+            const runnable = [];
+            const blocked = [];
+            for (const rec of reqs.applicable) {
+                const missingEvents = rec.required_events.filter((ev) => !eventNames.has(ev));
+                const missingProps = {};
+                for (const [ev, props] of Object.entries(rec.required_event_properties || {})) {
+                    if (!eventNames.has(ev))
+                        continue;
+                    const present = new Set(sampledKeys[ev] ?? []);
+                    const missing = props.filter((p) => !present.has(p));
+                    if (missing.length > 0)
+                        missingProps[ev] = missing;
+                }
+                if (missingEvents.length === 0 && Object.keys(missingProps).length === 0) {
+                    runnable.push(rec.id);
+                }
+                else {
+                    blocked.push({
+                        id: rec.id,
+                        title: rec.title,
+                        missing_events: missingEvents,
+                        missing_properties: missingProps,
+                    });
+                }
+            }
+            const missingUnion = new Set();
+            const missingPropUnion = new Set();
+            for (const b of blocked) {
+                for (const m of b.missing_events)
+                    missingUnion.add(m);
+                for (const [ev, props] of Object.entries(b.missing_properties)) {
+                    for (const p of props)
+                        missingPropUnion.add(`${ev}.${p}`);
+                }
+            }
+            recipeCheck = {
+                requested: true,
+                applicable_count: reqs.applicable_count,
+                runnable_count: runnable.length,
+                runnable,
+                blocked,
+                missing_events: [...missingUnion].sort(),
+                missing_event_properties: [...missingPropUnion].sort(),
+            };
+        }
+        catch (err) {
+            recipeCheck.skipped_reason = err instanceof Error ? err.message : String(err);
+        }
+    }
+    else if (input.shapes && input.shapes.length > 0) {
+        recipeCheck.skipped_reason = "analytics signal failed — fix analytics first, then re-run verify with shapes";
+    }
+    else {
+        recipeCheck.skipped_reason =
+            "no shapes provided — pass shapes/has_revenue/is_b2b/is_two_sided to verify recipe runnability";
+    }
+    const recipeFailing = recipeCheck.requested && recipeCheck.runnable_count < recipeCheck.applicable_count;
+    const allOk = failed.length === 0 && !recipeFailing;
     return {
-        ok: failed.length === 0,
-        summary: `${passed.length}/${Object.keys(checks).length} signal types verified`,
+        ok: allOk,
+        summary: `${passed.length}/${Object.keys(checks).length} signal types verified` +
+            (recipeCheck.requested
+                ? `; ${recipeCheck.runnable_count}/${recipeCheck.applicable_count} applicable recipes runnable`
+                : ""),
         passed,
         failed,
         checks,
+        recipe_check: recipeCheck,
         suggested_next_steps: nextSuggestions,
-        next_action: failed.length === 0 && nextSuggestions.length > 0
-            ? baseAction +
-                " Now offer the user this menu of post-install prompts:\n" +
-                nextSuggestions
-                    .slice(0, 5)
-                    .map((s, i) => `  ${i + 1}. ${s.title} — ${s.description}`)
-                    .join("\n") +
-                "\nWhen the user picks one, paste its `prompt_template` as their next prompt (or just execute the listed `uses`)."
-            : baseAction,
+        next_action: recipeFailing
+            ? `Install is HALF-DONE. Synthetic signals work, but ${recipeCheck.applicable_count - recipeCheck.runnable_count} of ${recipeCheck.applicable_count} applicable recipes are blocked.` +
+                (recipeCheck.missing_events.length > 0
+                    ? ` Missing events: ${recipeCheck.missing_events.join(", ")}.`
+                    : "") +
+                (recipeCheck.missing_event_properties.length > 0
+                    ? ` Missing required properties (event.property): ${recipeCheck.missing_event_properties.join(", ")} — events fire but lack required properties.`
+                    : "") + " " +
+                `Go back to the install-guide step \`track_comprehensively_for_this_app\` and wire the missing events. ` +
+                `Re-run agentry_verify_install with the same shapes when done. Do NOT tell the user 'installed' until this is 0 missing.`
+            : failed.length === 0 && nextSuggestions.length > 0
+                ? baseAction +
+                    " Now offer the user this menu of post-install prompts:\n" +
+                    nextSuggestions
+                        .slice(0, 5)
+                        .map((s, i) => `  ${i + 1}. ${s.title} — ${s.description}`)
+                        .join("\n") +
+                    "\nWhen the user picks one, paste its `prompt_template` as their next prompt (or just execute the listed `uses`)."
+                : baseAction,
     };
 }
 // ---------------------------------------------------------------------------
@@ -3355,6 +3849,20 @@ async function handleListRecipes(category) {
             "If nothing matches, call `agentry_query_docs` to compose ad-hoc HogQL via `agentry_analytics_query`.",
     };
 }
+async function handleRecipeRequirements(input) {
+    if (input.shapes.length === 0) {
+        return {
+            error: {
+                code: "missing_shapes",
+                message: "shapes is required (e.g. ['b2c-saas'], ['devtools-api', 'b2b-saas'])",
+                next_action: "Re-call agentry_recipe_requirements with the app shape(s) detected during " +
+                    "investigate_app_structure. See the description for the allowed vocabulary.",
+            },
+        };
+    }
+    const cfg = loadConfig();
+    return await api.recipeRequirements(cfg, input);
+}
 async function handleRunRecipe(input) {
     if (!input.recipe_id) {
         return {
@@ -3386,9 +3894,19 @@ async function handleRunRecipe(input) {
         };
     }
     const resp = await api.runRecipe(cfg, projectId, input.recipe_id, input.params);
+    // Aggressive friction detection: a recipe that runs without errors but
+    // returns 0 rows almost always means required events aren't firing. Fire
+    // feedback to the agentry team for AI review.
+    const rowsReturned = Array.isArray(resp.rows) ? resp.rows.length : 0;
+    const frictionFp = frictionTracker.detectEmptyRecipe(cfg, {
+        recipe_id: input.recipe_id,
+        project_id: projectId,
+        rows_returned: rowsReturned,
+    });
     return {
         project_id: projectId,
         ...resp,
+        next_action: (resp.next_action ?? "") + frictionTracker.frictionNoticeSuffix(frictionFp),
     };
 }
 async function handleQueryDocs() {
@@ -3774,4 +4292,61 @@ async function handleListFeedback(input) {
     const resp = await api.listFeedback(cfg, opts);
     return resp;
 }
+// ---------------------------------------------------------------------------
+// Team invites + member management (Phase 4)
+// ---------------------------------------------------------------------------
+async function handleInviteTeammate(input) {
+    const cfg = loadConfig();
+    const picked = pickProject(cfg, input.project_id);
+    if (!picked) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project_id given and no default project set.",
+                next_action: "Pass project_id, or call agentry_create_project.",
+            },
+        };
+    }
+    const body = { role: input.role };
+    if (input.email)
+        body.email = input.email;
+    return await api.inviteTeammate(cfg, picked.id, body);
+}
+async function handleListMembers(projectId) {
+    const cfg = loadConfig();
+    const picked = pickProject(cfg, projectId);
+    if (!picked) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project_id given and no default project set.",
+                next_action: "Pass project_id.",
+            },
+        };
+    }
+    return await api.listMembers(cfg, picked.id);
+}
+async function handleRemoveMember(input) {
+    const cfg = loadConfig();
+    const picked = pickProject(cfg, input.project_id);
+    if (!picked) {
+        return {
+            error: {
+                code: "no_project",
+                message: "No project_id given and no default project set.",
+                next_action: "Pass project_id.",
+            },
+        };
+    }
+    if (!input.user_id) {
+        return {
+            error: {
+                code: "invalid_payload",
+                message: "user_id is required.",
+                next_action: "Call agentry_list_members to find the user_id to remove.",
+            },
+        };
+    }
+    return await api.removeMember(cfg, picked.id, input.user_id);
+}
 //# sourceMappingURL=tools.js.map