@wirl/mcp 0.2.0 → 0.2.2

package/bin.js

@@ -15,10 +15,14 @@ var __export = (target, all) => {
 };
 
 // packages/core/src/types.ts
-var AppKind;
+var AppRole, AppKind;
 var init_types = __esm({
   "packages/core/src/types.ts"() {
     "use strict";
+    AppRole = {
+      VIEWER: "viewer",
+      EDITOR: "editor"
+    };
     AppKind = {
       STATIC: "static",
       SERVICE: "service",
@@ -189,9 +193,33 @@ function validateSlug(input) {
 function isWellFormedSlug(input) {
   return typeof input === "string" && input.length >= SLUG_MIN && input.length <= SLUG_MAX && SLUG_RE.test(input) && !input.includes(HOST_SEPARATOR);
 }
-function slugify(input) {
-  const base = input.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, SLUG_MAX).replace(/-$/, "");
-  return isValidSlug(base) ? base : null;
+function slugBase(input) {
+  return input.normalize("NFKD").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").slice(0, SLUG_MAX).replace(/-$/, "");
+}
+function previewSlugFor(raw) {
+  const base = slugBase(raw);
+  switch (validateSlug(base).problem) {
+    case void 0:
+      return { ok: true, slug: base };
+    case "reserved":
+      return {
+        ok: false,
+        problem: "reserved",
+        message: `The preview name "${base}" is reserved. The reserved preview names are: ${[...RESERVED_SLUGS].sort().join(", ")}. Pick another name.`
+      };
+    case "too_short":
+      return {
+        ok: false,
+        problem: "too_short",
+        message: `That name is too short: it makes a preview name of one character, and a preview name needs at least ${String(SLUG_MIN)}.`
+      };
+    default:
+      return {
+        ok: false,
+        problem: "no_characters",
+        message: "That name has no usable characters: a preview name is made of the letters a to z and the digits 0 to 9 in what you give it, and none are left."
+      };
+  }
 }
 function appLabel(orgSlug, appSlug) {
   return `${orgSlug}${HOST_SEPARATOR}${appSlug}`;
@@ -1794,6 +1822,9 @@ var init_migrations = __esm({
       leaseMs: 6e5,
       orgApplies: 2,
       // per org: the limit one tenant's applies meet
+      // Per app, its live database and its previews' together, inside the org's
+      // two, so one app's deployers can never take both (OIM-927).
+      appApplies: 1,
       // Per control-plane process. The lease holds no pooled connection, so this
       // bounds the process's work, not its pool; at `orgApplies` two each,
       // filling it takes eight orgs (T5b-6).
@@ -2695,7 +2726,7 @@ var init_runtime = __esm({
 });
 
 // packages/core/src/broker-stream.ts
-var BROKER_LIMITS, STREAMED_MEDIA_TYPES;
+var BROKER_LIMITS, STREAMED_MEDIA_TYPES, MIB;
 var init_broker_stream = __esm({
   "packages/core/src/broker-stream.ts"() {
     "use strict";
@@ -2712,15 +2743,132 @@ var init_broker_stream = __esm({
       streamIdleMs: 4 * 6e4,
       /** Bytes in any one answer, streamed or read whole. */
       answerBytes: 25 * 1024 * 1024,
+      /**
+       * Bytes in the body of any one call an app makes. The body is read whole
+       * before the call is sent, and before its grant is looked up, so a body
+       * past this never opens a key and never reaches a vendor (OIM-931).
+       * 100 MiB: Cloudflare publishes 100 MB as the request body its Free and
+       * Pro plans take, and a deployed app's call is first held whole by the
+       * egress Worker, in an isolate Cloudflare gives 128 MB of memory. Nothing
+       * else bounds a caller that holds a broker token and reaches the control
+       * plane itself: Railway sets no size on a body, only five minutes to send it.
+       */
+      requestBytes: 100 * 1024 * 1024,
+      /**
+       * Bytes of call bodies one app's calls hold at once, its previews' with
+       * them (OIM-951): counted as each chunk arrives, from a call's first byte
+       * until the broker has answered it (broker-bodies.ts). At least
+       * `requestBytes`, so one call at the cap always fits an app that holds
+       * nothing else; a quarter of `heldBodyBytes`, so four apps of four owners
+       * at their share fill the whole (one owner's apps cannot: `ownerHeldBodyBytes`).
+       */
+      appHeldBodyBytes: 128 * 1024 * 1024,
+      /**
+       * Bytes of call bodies the calls of every app one owner has hold at once,
+       * their previews' with them (OIM-967): the person `apps.owner_user_id`
+       * names, whichever organisations their apps are in. Apps and
+       * organisations cost nothing to create (no cap on either), so a share per
+       * app let one person with four apps fill the whole, and one per
+       * organisation would let them do it with four organisations; a person
+       * costs a sign-in. Two apps at their share, so one app that runs
+       * away still leaves its owner's other apps room, and half of
+       * `heldBodyBytes`, so one owner can never take more than half, and a
+       * second sign-in is what it takes to fill it. At least `requestBytes`, so
+       * one call at the cap always fits an owner whose apps hold nothing else.
+       */
+      ownerHeldBodyBytes: 256 * 1024 * 1024,
+      /**
+       * Bytes of call bodies every app's calls hold at once, in this process.
+       * A call's reader starts at 16 KiB and doubles its buffer as the body
+       * arrives, so the buffers behind this hold at most twice it, 1 GiB, and
+       * 16 KiB a call beside (the ruling in OIM-951).
+       */
+      heldBodyBytes: 512 * 1024 * 1024,
+      /** The `Retry-After` of a call refused for either. */
+      heldBodyRetryAfterSeconds: 10,
+      /**
+       * How long a call's body may send nothing before its read is stopped:
+       * an upload's (OIM-935). A deployed app's body comes from the egress
+       * Worker, which holds it whole before it sends it, and `wirl dev` reads it
+       * whole first, so no ordinary sender ever pauses (fix round 1, R1-F2).
+       */
+      heldBodyStallMs: 3e4,
+      /**
+       * How long a call's body may take to arrive whole: 100 MiB in 120 seconds
+       * is about 7 Mbit/s, which a body between Cloudflare and the control plane
+       * passes many times over, and well under Node's 300 seconds a request,
+       * after which the body would be cut anyway (fix round 1, R1-F2).
+       */
+      heldBodyArrivalMs: 12e4,
+      /**
+       * Bytes of answers read whole that one app's calls hold at once, its
+       * previews' with them (OIM-966): counted as each chunk arrives from the
+       * vendor, from an answer's first byte until wirl's server has taken the
+       * last of it, or the app has gone (broker-bodies.ts). A vendor's event
+       * stream is not counted: it is passed on as the app reads it, and holds
+       * about 285 to 441 KiB at a time, measured end to end through the control
+       * plane's server (`passOn` in broker.ts; OIM-966 fix round 1, R1-F3,
+       * R2-F2). More than two `answerBytes`, so two answers at the cap fit an
+       * app that holds nothing else; a quarter of `heldAnswerBytes`, so four apps
+       * of four owners at their share fill the whole (one owner's apps cannot:
+       * `ownerHeldAnswerBytes`).
+       */
+      appHeldAnswerBytes: 64 * 1024 * 1024,
+      /**
+       * Bytes of answers read whole that the calls of every app one owner has
+       * hold at once, their previews' with them (OIM-967), for the reasons
+       * `ownerHeldBodyBytes` gives: two apps at their share, half of
+       * `heldAnswerBytes`, and more than two `answerBytes` and than the room a
+       * call needs, so an owner whose apps hold nothing else can always send.
+       */
+      ownerHeldAnswerBytes: 128 * 1024 * 1024,
+      /**
+       * Bytes of answers read whole that every app's calls hold at once, in this
+       * process. An answer's reader doubles its buffer as it fills, as a body's
+       * does, and never past `answerBytes`, so while answers arrive the buffers
+       * behind this hold at most twice it, 512 MiB, and 16 KiB an answer beside;
+       * an answer read whole is copied to exactly its size before it is handed
+       * on, so from then its count is its memory (the ruling in OIM-966, and its
+       * fix round 1, R1-F2).
+       */
+      heldAnswerBytes: 256 * 1024 * 1024,
+      /**
+       * The room an app's share of answers, and the whole, must each have left
+       * for a call to be sent at all: one answer at the cap. With less, the call
+       * is refused with a 503 before it leaves wirl, rather than run at its
+       * vendor and its answer cut (OIM-966 fix round 1, R1-F1).
+       */
+      heldAnswerRoomBytes: 25 * 1024 * 1024,
+      /** The `Retry-After` of a call refused for that room, before it was sent. */
+      heldAnswerRetryAfterSeconds: 10,
+      /**
+       * How long an answer read whole may wait for wirl's server to take the
+       * last of it once it is handed back: past this it is cut, and its count
+       * goes back, so no app holds its share, or the whole, by not reading.
+       * Under Cloudflare's measured 125 seconds with nothing moving, which ends
+       * a deployed app's unread answer anyway (OIM-966 fix round 1, R1-F1).
+       */
+      heldAnswerHandOutMs: 12e4,
       /**
        * Streamed answers one app may have open at once. Each holds a vendor
        * socket and an inbound connection on one control-plane instance for up
        * to fourteen minutes, so one app cannot be allowed an unbounded number.
        * Counted in memory, per instance, like the control plane's other limits.
        */
-      openStreamsPerApp: 20
+      openStreamsPerApp: 20,
+      /**
+       * How long an event stream wirl cut waits for its closing event to leave
+       * the server before it ends the stream with its error anyway (OIM-837 fix
+       * round 1). The event is on its way when the server's queue of what it has
+       * to write has emptied; a reader that is slow but reading empties a full
+       * kernel buffer, a few hundred kilobytes, well inside this. Past it the
+       * reader is not reading, and the stream ends as it always did; the write
+       * stall that holds a connection longer than this is OIM-968's.
+       */
+      cutEventSentMs: 5e3
     };
     STREAMED_MEDIA_TYPES = Object.freeze(["text/event-stream", "application/x-ndjson"]);
+    MIB = 1024 * 1024;
   }
 });
 
@@ -2788,20 +2936,21 @@ arrives: pass \`response.body\` straight on. There are no WebSockets. A front en
 \`"static": "dist"\` serves that folder's files at their own paths (\`/\` is its \`index.html\`) and the module
 answers everything else; add \`"spa": true\` for a client-side router. Nothing outside that folder is served.
 
-Preview before you deploy: \`wirl preview\` puts the folder up at its own address with
-its own database (empty at first), and \`wirl fetch <path> --preview <name>\` (or the
-\`wirl_preview_fetch\` tool) shows you what it serves.
+Preview before you deploy: \`wirl preview\` gives a folder its own address and database (at first only what
+\`migrations/\` makes). \`wirl fetch <path> --preview <name>\` or \`wirl_preview_fetch\` shows what it answers. Every request a preview's module gets names the preview in \`x-wirl-preview\`, and wirl marks its pages as previews.
 
 npm packages work: install them in the project and the deploy bundles them in. Nothing is installed on the
 server: native code will not run. Node built-ins work (\`node:crypto\`, \`node:path\`, ...; \`Buffer\` and
 \`process\` are global), but what \`node:fs\` writes is gone by the next request: use \`env.DB\`.
 
 \`env\` holds \`DB\` and nothing else. \`env.DB\` is Cloudflare D1: prepared statements with \`.bind()\`, at most
-100 bound parameters a statement. \`exec()\` runs one statement per line. Declare a host under \`connections\`
-in \`wirl.json\`, then \`fetch\` the vendor's real URL: wirl attaches the key. An undeclared host is refused; a
-public API needing no key uses \`"kind": "none"\`. Declaring one deploys before anyone approves it;
-the deploy says per connection whether it is usable now or waiting on an admin. A vendor has 60
-seconds to answer, whole, unless it streams: ask a model for a stream.
+100 bound parameters a statement. \`exec()\` runs one statement per line, as does each file in \`migrations/\`,
+which wirl applies in order to a preview and before going live; a failing one fails the deploy. Never edit
+an applied file. Dropping or renaming a table or column needs \`"migrations": { "destructive": [...] }\`, its
+own live deploy and a person's yes. Declare a host under \`connections\`, then \`fetch\` the vendor's real URL:
+wirl attaches the key. An undeclared host is refused; a public API needing no key uses \`"kind": "none"\`.
+Declaring one deploys before anyone approves it; the deploy says per connection whether it is usable now or
+waiting on an admin. A vendor has 60 seconds to answer, whole, unless it streams: ask a model for a stream.
 
 Six headers say who is asking: \`x-wirl-user-id\`, \`x-wirl-user-email\`, \`x-wirl-user-name\`,
 \`x-wirl-role\`, \`x-wirl-app-id\`, \`x-wirl-org\`. Read the name with
@@ -2811,10 +2960,9 @@ Schedules POST to \`/__wirl/schedule/<name>\`; a run gets 5 minutes unless that
 says otherwise, and at most 15. A \`public_paths\` path takes requests with no sign-in.
 Work that outlives one request (waiting for a person, trying tomorrow, a long loop) is a flow: see Flows.
 
-A new app defaults to org-wide visibility when its org has a company email domain,
-and to private otherwise, including one made with \`wirl orgs create\`.
-Sharing by email adds one named person; \`wirl visibility private|org\` (or the tool)
-sets the level. Public is only ever a person's click on the app's Access page.
+A new app defaults to org-wide visibility when its org has a company email domain, and to private
+otherwise, including one made with \`wirl orgs create\`; \`wirl visibility private|org\` sets the level.
+Sharing by email adds one named person. Public is only ever a person's click on the app's Access page.
 
 Porting an existing project: route it through the \`fetch\` handler, replace ORM calls with
 \`env.DB.prepare(...).bind(...)\`, turn timers into \`schedules\`, and move keys into \`connections\`. Keep the
@@ -2846,18 +2994,67 @@ early, repeated or late one gets 409, or 404 once the run ends; check \`x-wirl-u
   }
 });
 
+// packages/core/src/version.ts
+function wirlVersion() {
+  return BUILT_VERSION ?? WORKSPACE_VERSION;
+}
+var WORKSPACE_VERSION, BUILT_VERSION;
+var init_version = __esm({
+  "packages/core/src/version.ts"() {
+    "use strict";
+    WORKSPACE_VERSION = "0.0.0";
+    BUILT_VERSION = true ? "0.2.2" : null;
+  }
+});
+
 // packages/core/src/install.ts
+function fallbackWhen(controlPlane = "this control plane") {
+  return `If your npm registry does not carry wirl, or to run exactly the build ${controlPlane} serves,`;
+}
+function namedControlPlane(controlOrigin) {
+  return `the wirl control plane (${controlOrigin.replace(/^https?:\/\//, "").replace(/\/+$/, "")})`;
+}
 function installFor(controlOrigin) {
-  if (NPM_PUBLISHED) return { cli: "wirl", mcp: "@wirl/mcp" };
   const origin = controlOrigin.replace(/\/+$/, "");
-  return { cli: `${origin}/cli/wirl.tgz`, mcp: `${origin}/cli/wirl-mcp.tgz` };
+  const tarball = { cli: `${origin}/cli/wirl.tgz`, mcp: `${origin}/cli/wirl-mcp.tgz` };
+  if (NPM_PUBLISHED) return { cli: "wirl", mcp: "@wirl/mcp", tarball };
+  return { ...tarball, tarball };
 }
-var NPM_PUBLISHED, WIRL_BIN;
+var NPM_PUBLISHED, WIRL_BIN, FALLBACK_WHEN, hasFallback;
 var init_install = __esm({
   "packages/core/src/install.ts"() {
     "use strict";
-    NPM_PUBLISHED = false;
+    NPM_PUBLISHED = true;
     WIRL_BIN = NPM_PUBLISHED ? "npx wirl" : "wirl";
+    FALLBACK_WHEN = fallbackWhen();
+    hasFallback = (install) => install.cli !== install.tarball.cli;
+  }
+});
+
+// packages/core/src/share-role.ts
+function readShareRole(value) {
+  if (value === void 0 || value === null) return { ok: true, role: void 0 };
+  if (value === AppRole.VIEWER || value === AppRole.EDITOR) return { ok: true, role: value };
+  return { ok: false, message: SHARE_ROLE_REFUSAL };
+}
+var SHARE_ROLE_REFUSAL;
+var init_share_role = __esm({
+  "packages/core/src/share-role.ts"() {
+    "use strict";
+    init_types();
+    SHARE_ROLE_REFUSAL = "role must be viewer or editor.";
+  }
+});
+
+// packages/core/src/connect.ts
+var CLAUDE_CODE_SIGN_IN, CLAUDE_CODE_LOCAL_SIGN_IN, CLI_LOGIN_DOES;
+var init_connect = __esm({
+  "packages/core/src/connect.ts"() {
+    "use strict";
+    init_install();
+    CLAUDE_CODE_SIGN_IN = "`claude mcp add` only saves the server's configuration. Then sign in: run `/mcp` inside Claude Code and follow the steps in the browser, or run `claude mcp login wirl` in a terminal.";
+    CLAUDE_CODE_LOCAL_SIGN_IN = `The local server signs in the first time a wirl tool needs it: the agent calls \`wirl_login\`, which returns a link and a code, and the agent shows both to the person. The person approves the code in the browser, and the agent's next wirl tool call works. A machine already signed in with \`${WIRL_BIN} login\` skips this.`;
+    CLI_LOGIN_DOES = "prints a link and a code to approve in the browser";
   }
 });
 
@@ -3081,6 +3278,66 @@ var init_porting = __esm({
   }
 });
 
+// packages/core/src/throttle-report.ts
+var THROTTLE_REPORT, EDGE_REFUSALS_NOTE;
+var init_throttle_report = __esm({
+  "packages/core/src/throttle-report.ts"() {
+    "use strict";
+    init_public_path();
+    THROTTLE_REPORT = {
+      /**
+       * One report per app a minute at most from each gate isolate, and what
+       * one report counts spans a minute at most.
+       */
+      windowMs: 6e4,
+      /**
+       * How long the refusal that opens a window waits for more before the
+       * report goes, so a burst is one report with its count rather than a
+       * report of its first refusal.
+       */
+      gatherMs: 15e3,
+      /**
+       * The longest a refused request is asked to stay open, after its 429 has
+       * gone, for the report to be sent. Cloudflare keeps a request's
+       * `waitUntil` work for 30 seconds after the response, shared by all of
+       * it, and the send itself has `sendTimeoutMs` of what is left.
+       */
+      maxWaitMs: 2e4,
+      sendTimeoutMs: 5e3,
+      /**
+       * Reports one request carries for windows no refusal could wait for
+       * (`flushDue`). A request that was never refused must not queue its own
+       * reads behind posts that are not its own: Cloudflare runs six of a
+       * request's connections at once and queues the rest.
+       */
+      flushPerRequest: 2,
+      /** Apps one gate isolate counts for at once; a refusal for another app past this is not counted. */
+      maxApps: 1e3,
+      /** Lines in one report: each of an app's public paths, by each ceiling. */
+      maxEntries: 2 * PUBLIC_PATH_LIMITS.perApp,
+      /** A path is cut to this many characters, as `public.refused`'s is. */
+      maxPathChars: 256,
+      /**
+       * The most of a report's body the control plane reads. A full report is
+       * under 8 KiB: a path a request matched is ASCII, as a URL's path is.
+       */
+      bodyBytes: 16384,
+      /**
+       * Reports the control plane reads for one app a minute, from every isolate
+       * and location together. Of those, the first writes the app's one
+       * `public.throttled` row for that minute and the rest write nothing.
+       */
+      perAppPerMinute: 10,
+      /** The org's Activity page summarises this many apps' latest `public.throttled` lines, a line an app, from the last `logsPageDays` days. */
+      activityLines: 5,
+      /** The app's Logs page shows its latest this many `public.throttled` lines, from the last `logsPageDays` days. */
+      logsPageLines: 20,
+      logsPageDays: 7
+    };
+    EDGE_REFUSALS_NOTE = "Requests wirl refuses before your app is called, such as a public path's 429 over its ceiling, are not invocations and never show here; anyone who can deploy the app sees those 429s counted as public.throttled on its Logs page in the dashboard.";
+  }
+});
+
 // packages/core/src/supplied-bundle.ts
 var SUPPLIED_BUNDLE_PATH, MAX_SUPPLIED_BUNDLE_BYTES;
 var init_supplied_bundle = __esm({
@@ -3105,6 +3362,9 @@ var init_manifest_transport = __esm({
 });
 
 // packages/core/src/preview.ts
+function versionNumbersSentence(listing) {
+  return `A preview takes a version number from the same count as a deploy, and ${listing} never lists a preview, so a deploy's number can skip: if the newest version listed is v1 and this deploy is v4, v2 and v3 were previews.`;
+}
 var PREVIEW_TTL_DAYS, MAX_PREVIEWS_PER_APP;
 var init_preview = __esm({
   "packages/core/src/preview.ts"() {
@@ -3142,8 +3402,12 @@ var init_src = __esm({
     init_broker_stream();
     init_retention();
     init_contract();
+    init_version();
     init_install();
+    init_share_role();
+    init_connect();
     init_porting();
+    init_throttle_report();
     init_supplied_bundle();
     init_manifest_transport();
     init_preview();
@@ -4789,7 +5053,7 @@ init_src();
 import { access, link, lstat as lstat2, mkdir as mkdir3, open, readFile as readFile3, readdir, rename as rename2, rm as rm3, stat as stat3, unlink, writeFile as writeFile2 } from "node:fs/promises";
 import { homedir } from "node:os";
 import { basename as basename2, dirname as dirname3, isAbsolute, join as join5, relative, resolve as resolve4, sep } from "node:path";
-import { create as tarCreate, extract as tarExtract } from "tar";
+import { create as tarCreate, extract as tarExtract, Parser as TarParser } from "tar";
 import { gzipSync } from "node:zlib";
 
 // packages/core/src/node/preview-name.ts
@@ -4797,10 +5061,9 @@ init_slug();
 import { createHash } from "node:crypto";
 var HASH_SUFFIX_LENGTH = 5;
 function previewNameFor(raw, orgSlug, appSlug) {
-  const slug = slugify(raw);
-  if (!slug) {
-    return { ok: false, message: "That name has no usable characters, or is reserved." };
-  }
+  const made = previewSlugFor(raw);
+  if (!made.ok) return { ok: false, message: made.message };
+  const slug = made.slug;
   const budget = MAX_HOST_LABEL - (appLabel(orgSlug, appSlug).length + HOST_SEPARATOR.length);
   if (budget < 2) {
     return {
@@ -4920,6 +5183,64 @@ function shellPath(value) {
   return shellQuote(value);
 }
 
+// packages/cli/src/skill.ts
+init_src();
+var SKILL_INTRO = `A new app is visible to everyone in the org when the org came from a
+company email domain; in any other org, including a personal one or one
+made with \`wirl orgs create\`, it starts private. Deploys are one
+command; sharing is by email; a third-party API is declared, never pasted.`;
+var SKILL_DOCS_LINE = "Before you build, fetch https://docs.wirl.dev/llms-full.txt: every page of the docs as one Markdown file, so there is no need to read the site page by page.";
+var SKILL_RULES = `1. **Never ask for or paste an API key.** Declare the connection in \`wirl.json\` and deploy. Needs no key at all (a public API)? Declare it with "kind": "none" and its hosts. If the key is missing, the deploy prints a link to the app's keys page; show the person that link. Locally, keys live in \`.wirl/keys.json\`, which git ignores. To try a vendor call locally without the key, map its connection to a server of your own in \`.wirl/mocks.json\`, like \`{ "anthropic": "http://127.0.0.1:4010" }\`: \`wirl dev\` then sends the calls to that connection's hosts there instead (\`wirl dev --help\` has the rest).
+2. **Call third-party APIs by their real URL** (\`fetch("https://api.hubspot.com/...")\`). wirl attaches the key on the way out, deployed and under \`wirl dev\` alike.
+3. If a command names several organisations and asks which, ask the person; pass \`--org\` or put \`"org"\` in \`wirl.json\`.
+4. To keep a file out of the deploy, list it in a \`.wirlignore\` at the project root (gitignore-style lines; no \`!\` negation).
+5. **A file that can lose data waits for a person.** A deploy that would apply a destructive file (one wirl.json's \`"destructive"\` list must name) to the live database stops and names the page where a person approves each one. Show the person those pages, and deploy again once they say they approved. If \`${WIRL_BIN} deploy\` asks you to type a file's name, stop it and show the page instead, or deploy with \`--json\`, which never asks. Never type the name yourself or send the confirmation: that is the person's, and no flag skips it.`;
+var SKILL_MANIFEST_EXAMPLE = `\`\`\`json
+{ "app": "crm-sync", "server": "server.mjs", "connections": [{ "slug": "hubspot", "hosts": ["api.hubspot.com"] }] }
+\`\`\``;
+var SKILL_FILES_PARAGRAPH = "No blob storage: files go in `env.DB`, at most 2,000,000 bytes a value or row (the limit Cloudflare publishes for D1), so store a larger file in chunks, one row each, a few MB to a batch. `wirl dev` refuses a single bound value over 2,000,000 bytes, but a row's total, a value grown in SQL, or a batch bigger than one call to D1 carries can still pass locally and fail deployed.";
+var SKILL_STATIC_PARAGRAPH = 'A static folder maps a path to one file exactly: a path ending in `/` serves the `index.html` in that folder, `/about` never finds `about.html`, and a path that names no file goes to the module (with `"spa": true`, a page navigation gets `index.html` instead; in an app with no module, the top `index.html`, or a 404 for a missing file with an extension). Next.js runs only as a static export: `output: "export"` and `trailingSlash: true` in `next.config` make `next build` write `out/`, which goes under `"static"`; `next start` cannot run, and API routes move into the module.';
+function composeSkill(parts) {
+  if (parts.description.trim() === "" || /[\r\n]/.test(parts.description)) {
+    throw new Error("a skill description is one non-empty line");
+  }
+  return `---
+name: wirl
+description: ${parts.description}
+---
+
+# wirl
+
+${SKILL_INTRO}
+
+${SKILL_DOCS_LINE}
+
+## Commands
+
+${parts.commands.trimEnd()}
+
+## Rules
+
+${SKILL_RULES}
+
+## wirl.json
+
+${SKILL_MANIFEST_EXAMPLE}
+
+## What runs on wirl
+
+${BUILD_CONTRACT}
+
+${SKILL_FILES_PARAGRAPH}
+
+${SKILL_STATIC_PARAGRAPH}
+
+## Flows
+
+${FLOWS_CONTRACT}
+`;
+}
+
 // packages/cli/src/core.ts
 function credentialsPath(env = process.env) {
   return env["WIRL_CREDENTIALS_PATH"] || join5(homedir(), ".config", "wirl", "credentials.json");
@@ -4980,7 +5301,7 @@ async function loadCredentials(env = process.env) {
     }
   } catch {
   }
-  throw new CliError("Not signed in.", "Run `wirl login` first, or set WIRL_TOKEN.", { code: "not_signed_in" });
+  throw new CliError("Not signed in.", `Run \`${WIRL_BIN} login\` first, or set WIRL_TOKEN.`, { code: "not_signed_in" });
 }
 async function saveCredentials(creds, env = process.env) {
   const path = credentialsPath(env);
@@ -5041,11 +5362,11 @@ async function pollDeviceLogin(apiOrigin, login, options = {}) {
         continue;
       }
       case "expired_token":
-        throw new CliError("The sign-in code expired before it was approved.", "Run `wirl login` again.");
+        throw new CliError("The sign-in code expired before it was approved.", `Run \`${WIRL_BIN} login\` again.`);
       default:
         throw new CliError(
           typeof body["error"] === "string" ? `Sign-in failed: ${body["error"]}.` : `Sign-in failed (${response.status}).`,
-          "Run `wirl login` again."
+          `Run \`${WIRL_BIN} login\` again.`
         );
     }
   }
@@ -5096,6 +5417,10 @@ var SERVER_TEMPLATE = [
   " *",
   " * Everything real happens here. The page is HTML this module returns. The",
   " * data lives in env.DB, a SQLite database that belongs to this app alone.",
+  " * Its tables are in migrations/0001_init.sql: wirl applies each new file in",
+  " * migrations/ before a version goes live, to a preview's database when the",
+  " * preview is put up, and to the local one when wirl dev starts. Put the",
+  " * next change in migrations/0002_<what>.sql rather than editing that one.",
   " * The person making the request is in headers wirl sets after verifying",
   " * them, which the browser cannot forge. Any rule that matters, such as",
   ' * "you only see your own notes", is a line of code in this file: a check',
@@ -5107,18 +5432,8 @@ var SERVER_TEMPLATE = [
   " * live in .wirl/keys.json beside this file, which git ignores.",
   " */",
   "",
-  "// One line: exec runs one statement per line, as D1 does.",
-  "const SCHEMA =",
-  '  "create table if not exists notes (" +',
-  '  "  id integer primary key," +',
-  '  "  user_id text not null," +',
-  '  "  body text not null," +',
-  `  "  created_at text not null default (datetime('now'))" +`,
-  '  ")";',
-  "",
   "export default {",
   "  async fetch(request, env) {",
-  "    await env.DB.exec(SCHEMA);",
   "    const url = new URL(request.url);",
   "",
   `    // One line per request. Read it with ${WIRL_BIN} logs.`,
@@ -5201,56 +5516,34 @@ var SERVER_TEMPLATE = [
   "}",
   ""
 ].join("\n");
+var INIT_MIGRATION = [
+  "-- This app's tables. wirl applies each new file here, in order, before a version goes live.",
+  "-- Make the next change in 0002_<what>.sql; never edit a file that has been deployed.",
+  "create table notes (id integer primary key, user_id text not null, body text not null, created_at text not null default (datetime('now')))",
+  ""
+].join("\n");
+var INIT_MIGRATION_PATH = `${MIGRATIONS_DIR}/${ADOPTED_FILE}`;
 var SKILL_PATH = join5(".claude", "skills", "wirl", "SKILL.md");
-var SKILL_MARKDOWN = `---
-name: wirl
-description: Deploy and share the internal app in this project with wirl (${WIRL_BIN}). Use when the user wants a tool, dashboard or prototype put somewhere colleagues can open it, shared with a named person, run locally the way it will run deployed, or connected to a third-party API; or wants work that outlives one request, such as waiting for a person to approve something or trying again tomorrow.
----
-
-# wirl
-
-A new app is visible to everyone in the org when the org came from a
-company email domain; in any other org, including a personal one or one
-made with \`wirl orgs create\`, it starts private. Deploys are one
-command; sharing is by email; a third-party API is declared, never pasted.
-
-Before you build, fetch https://docs.wirl.dev/llms-full.txt: every page of the docs as one Markdown file, so there is no need to read the site page by page.
-
-## Commands
+var SKILL_ORIGIN = "https://app.wirl.dev";
+var SKILL_INSTALL = installFor(SKILL_ORIGIN);
+var SKILL_RUN = NPM_PUBLISHED ? `Run the CLI as \`${WIRL_BIN} <command>\`, which needs no install beyond Node 22.13 or later (in a terminal npm asks "Ok to proceed?" the first time: answer y); this file writes a command as \`wirl <command>\` for short anywhere but the list below.
 
-- Connect first, if the agent supports MCP: \`claude mcp add --transport http wirl https://app.wirl.dev/mcp\` opens the browser once to sign in. No HTTP MCP support? \`claude mcp add wirl -- npx -y ${installFor("https://app.wirl.dev").mcp}\` does the same, running locally. Neither available: \`${WIRL_BIN} login\` prints a link and a code; the person approves in the browser. Do this once, when any command says you are not signed in.
+` : "";
+var SKILL_FALLBACK = hasFallback(SKILL_INSTALL) ? `- ${fallbackWhen(namedControlPlane(SKILL_ORIGIN))} install the CLI from the control plane instead with \`npm install -g ${SKILL_INSTALL.tarball.cli}\`, run plain \`wirl\` where this file says \`${WIRL_BIN}\`, and name \`${SKILL_INSTALL.tarball.mcp}\` in place of \`${SKILL_INSTALL.mcp}\`.
+` : "";
+var SKILL_MARKDOWN = composeSkill({
+  description: `Deploy and share the internal app in this project with wirl (${WIRL_BIN}). Use when the user wants a tool, dashboard or prototype put somewhere colleagues can open it, shared with a named person, run locally the way it will run deployed, or connected to a third-party API; or wants work that outlives one request, such as waiting for a person to approve something or trying again tomorrow.`,
+  commands: `${SKILL_RUN}- Connect first, if the agent supports MCP: \`claude mcp add --transport http wirl https://app.wirl.dev/mcp\` needs no install. ${CLAUDE_CODE_SIGN_IN} No HTTP MCP support? \`claude mcp add wirl -- npx -y ${SKILL_INSTALL.mcp}\` runs the same tools locally. ${CLAUDE_CODE_LOCAL_SIGN_IN} Neither available: \`${WIRL_BIN} login\` prints a link and a code; the person approves in the browser. Do this once, when any command says you are not signed in.
 - \`${WIRL_BIN} deploy\` \u2014 deploys this directory. Prints the URL and who can open it.
 - \`${WIRL_BIN} share someone@company.com\` \u2014 that person can open it. Add \`--role editor\` so they can deploy too.
 - \`${WIRL_BIN} dev\` \u2014 runs the app here as it will run deployed, signed in as a stub user.
 - \`${WIRL_BIN} pull <app>\` \u2014 fetches a deployed app's source to keep building.
 - \`${WIRL_BIN} logs\` \u2014 what the deployed app printed, per request, newest first; \`--errors\` for failures only, \`--follow\` to keep watching, \`--cursor <n>\` for the page before a "More before this" line. Read this before changing code when something misbehaves.
+- \`${WIRL_BIN} migrations\` \u2014 what this app's database has applied, read only.
+- \`${WIRL_BIN} migrations adopt\` \u2014 once, for an app whose tables were made in code: writes \`migrations/0001_init.sql\` from the live database's shape.
 - \`${WIRL_BIN} --help\` \u2014 everything else: orgs, members, connections, move, transfer, rollback, flows and runs.
-
-## Rules
-
-1. **Never ask for or paste an API key.** Declare the connection in \`wirl.json\` and deploy. Needs no key at all (a public API)? Declare it with "kind": "none" and its hosts. If the key is missing, the deploy prints a link to the app's keys page; show the person that link. Locally, keys live in \`.wirl/keys.json\`, which git ignores. To try a vendor call locally without the key, map its connection to a server of your own in \`.wirl/mocks.json\`, like \`{ "anthropic": "http://127.0.0.1:4010" }\`: \`wirl dev\` then sends the calls to that connection's hosts there instead (\`wirl dev --help\` has the rest).
-2. **Call third-party APIs by their real URL** (\`fetch("https://api.hubspot.com/...")\`). wirl attaches the key on the way out, deployed and under \`wirl dev\` alike.
-3. If a command names several organisations and asks which, ask the person; pass \`--org\` or put \`"org"\` in \`wirl.json\`.
-4. To keep a file out of the deploy, list it in a \`.wirlignore\` at the project root (gitignore-style lines; no \`!\` negation).
-
-## wirl.json
-
-\`\`\`json
-{ "app": "crm-sync", "server": "server.mjs", "connections": [{ "slug": "hubspot", "hosts": ["api.hubspot.com"] }] }
-\`\`\`
-
-## What runs on wirl
-
-${BUILD_CONTRACT}
-
-No blob storage: files go in \`env.DB\`, at most 2,000,000 bytes a value or row (the limit Cloudflare publishes for D1), so store a larger file in chunks, one row each, a few MB to a batch. \`wirl dev\` refuses a single bound value over 2,000,000 bytes, but a row's total, a value grown in SQL, or a batch bigger than one call to D1 carries can still pass locally and fail deployed.
-
-A static folder maps a path to one file exactly: a path ending in \`/\` serves the \`index.html\` in that folder, \`/about\` never finds \`about.html\`, and a path that names no file goes to the module (with \`"spa": true\`, a page navigation gets \`index.html\` instead; in an app with no module, the top \`index.html\`, or a 404 for a missing file with an extension). Next.js runs only as a static export: \`output: "export"\` and \`trailingSlash: true\` in \`next.config\` make \`next build\` write \`out/\`, which goes under \`"static"\`; \`next start\` cannot run, and API routes move into the module.
-
-## Flows
-
-${FLOWS_CONTRACT}
-`;
+${SKILL_FALLBACK}`
+});
 async function pullNextStep(dir) {
   return `cd ${shellPath(dir)} && ${await pulledDevCommand(dir)}`;
 }
@@ -5522,7 +5815,7 @@ async function callApi(creds, path, options = {}) {
       throw new CliError(body.message, void 0, refusal);
     }
     if (response.status === 401 || response.status === 403) {
-      throw new CliError("Not signed in, or this token cannot do that.", "Try `wirl login`.", refusal);
+      throw new CliError("Not signed in, or this token cannot do that.", `Try \`${WIRL_BIN} login\`.`, refusal);
     }
     if (response.status === 404) {
       if (body.error !== void 0 && body.error !== "not_found" && body.message) throw new CliError(body.message, void 0, refusal);
@@ -5554,30 +5847,58 @@ async function callApiBytes(creds, path, options = {}) {
       body = {};
     }
     if (response.status === 401 || response.status === 403) {
-      throw new CliError("Not signed in, or this token cannot do that.", "Try `wirl login`.");
+      throw new CliError("Not signed in, or this token cannot do that.", `Try \`${WIRL_BIN} login\`.`);
     }
     if (response.status === 404) throw new CliError("Not found, or you do not have access to it.");
     throw new CliError(body.message ?? body.error ?? `Request failed (${response.status}).`);
   }
   const declared = Number(response.headers.get("content-length") ?? 0);
   if (declared > MAX_PULL_BYTES) throw new CliError(`That is ${Math.round(declared / 1048576)} MB, more than wirl will pull.`);
-  const bytes = new Uint8Array(await response.arrayBuffer());
+  let bytes;
+  try {
+    bytes = new Uint8Array(await response.arrayBuffer());
+  } catch {
+    throw new CliError(PULL_CUT, void 0, { code: "pull_cut" });
+  }
   if (bytes.byteLength > MAX_PULL_BYTES) throw new CliError("The download was larger than wirl will pull.");
   return bytes;
 }
+var PULL_CUT = "The pull was cut before it finished, so nothing was written. Run it again.";
+var pullShort = (dir) => `The pull's archive is cut short or damaged, so nothing was written to ${dir}. Run it again.`;
 var MAX_PULL_BYTES = 256 * 1048576;
 var pullApp = (creds, org, app, options = {}) => callApiBytes(creds, `/api/v1/apps/${seg(org)}/${seg(app)}/pull`, options.fetchImpl ? { fetchImpl: options.fetchImpl } : {});
+function isWholeArchive(archive) {
+  return new Promise((resolve6, reject) => {
+    let sound = true;
+    let ended2 = false;
+    const parser = new TarParser({ onReadEntry: (entry) => void entry.resume() });
+    parser.on("warn", (code) => {
+      if (code === "TAR_BAD_ARCHIVE" || code === "TAR_ENTRY_INVALID") sound = false;
+    });
+    parser.on("eof", () => {
+      ended2 = true;
+    });
+    parser.on("error", (error) => typeof error.code === "string" && error.code.startsWith("Z_") ? resolve6(false) : reject(error));
+    parser.on("end", () => resolve6(sound && ended2));
+    parser.end(archive);
+  });
+}
 async function unpackPull(bytes, dir, options = {}) {
-  await mkdir3(dir, { recursive: true });
-  const existing = await readdir(dir);
+  const existing = await readdir(dir).catch((error) => {
+    if (error.code === "ENOENT") return [];
+    throw error;
+  });
   if (existing.length > 0 && !options.force) {
     throw new CliError(`${dir} is not empty.`, "Pull into a new directory, or pass --force to overwrite.");
   }
+  const archive = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  if (!await isWholeArchive(archive)) throw new CliError(pullShort(dir), void 0, { code: "pull_cut" });
+  await mkdir3(dir, { recursive: true });
   await new Promise((resolve6, reject) => {
     const extractor = tarExtract({ cwd: dir });
     extractor.on("error", reject);
     extractor.on("finish", resolve6);
-    extractor.end(Buffer.from(bytes));
+    extractor.end(archive);
   });
   const written = [];
   await collect(dir, dir, written);
@@ -5935,10 +6256,13 @@ function describeVisibility(level, org) {
   }
 }
 var readVisibility = (creds, org, app) => callApi(creds, `/api/v1/apps/${seg(org)}/${seg(app)}`).then((r) => r.app.visibility ?? "unknown");
-async function changeVisibility(creds, options) {
-  if (!VISIBILITY_LEVELS.includes(options.level)) {
-    throw new CliError(`Visibility is private, org or public, not "${String(options.level)}".`);
+function refuseVisibilityLevel(level) {
+  if (!VISIBILITY_LEVELS.includes(level)) {
+    throw new CliError(`Visibility is private, org or public, not "${String(level)}".`);
   }
+}
+async function changeVisibility(creds, options) {
+  refuseVisibilityLevel(options.level);
   if (options.level === "public") {
     throw new CliError(
       "Public means anyone on the internet with the link can open it, without signing in, so a person decides that with their own click.",
@@ -5953,11 +6277,59 @@ async function changeVisibility(creds, options) {
   return result2.visibility;
 }
 var unmailedNote = (result2) => result2.mailed === false && result2.message ? ` ${result2.message}` : "";
+function refuseShareRole(value) {
+  const read = readShareRole(value);
+  if (read.ok) return read.role;
+  const shown2 = typeof value === "string" ? terminalSafe(value.slice(0, 40)) : typeof value;
+  throw new CliError(`Role is viewer or editor, not "${shown2}".`);
+}
 var shareApp = (creds, org, app, email, role) => callApi(creds, `/api/v1/apps/${seg(org)}/${seg(app)}/share`, {
   method: "POST",
-  body: JSON.stringify({ email, role }),
+  // No role is no `role`: the control plane then keeps the one a person has.
+  body: JSON.stringify(role === void 0 ? { email } : { email, role }),
   contentType: "application/json"
 });
+function shareSentence(result2, email, asked, voice) {
+  const roleOf = (value) => value === "viewer" || value === "editor" ? value : void 0;
+  const outcome = ["added", "kept", "unchanged", "changed"].includes(String(result2.outcome)) ? result2.outcome : void 0;
+  const role = roleOf(result2.role);
+  const old = outcome === void 0 || role === void 0;
+  const now = role ?? asked ?? "viewer";
+  const was = roleOf(result2.previousRole);
+  const article = (name) => name === "editor" ? "an editor" : "a viewer";
+  const mail = unmailedNote(result2);
+  const signIn = voice === "cli" ? "the moment they first sign in" : "when they first sign in";
+  if (result2.pending) {
+    const wait = `They will have access ${signIn}.`;
+    if (!old && outcome === "kept") return `${email} was already invited as ${now}, and no role was given, so it stays ${now}. ${wait}${mail}`;
+    const lead2 = `Invited ${email} as ${now}. ${wait}`;
+    if (old || outcome === "added") return `${lead2}${mail}`;
+    if (outcome === "unchanged") return `${lead2} The invitation already said that.${mail}`;
+    if (was === void 0) return `${lead2} The invitation's role was changed.${mail}`;
+    return `${lead2} The invitation said ${was} before.${mail}`;
+  }
+  if (!old && outcome === "kept") {
+    const change = voice === "cli" ? "Pass --role viewer or --role editor" : 'Pass role "viewer" or "editor"';
+    return `${email} already had access as ${now}, and no role was given, so it stays ${now}. ${change} to change it.`;
+  }
+  const lead = voice === "cli" ? `Shared with ${email} as ${now}.` : `${email} can now open the app as ${now}.`;
+  if (old || outcome === "added") return lead;
+  if (outcome === "unchanged") return `${lead} They already had that role.`;
+  if (was === void 0) return `${lead} Their role was changed.`;
+  return `${lead} They were ${article(was)} before.`;
+}
+var unshareApp = (creds, org, app, email) => callApi(creds, `/api/v1/apps/${seg(org)}/${seg(app)}/share`, {
+  method: "DELETE",
+  body: JSON.stringify({ email }),
+  contentType: "application/json"
+});
+function unshareSentence(result2, email) {
+  const share = result2.shareRevoked ?? result2.revoked;
+  const invitation = result2.invitationWithdrawn ?? false;
+  const found = share ? invitation ? `Revoked ${email}'s share and withdrew the invitation still waiting for them.` : `Revoked ${email}'s share.` : invitation ? `Withdrew ${email}'s invitation.` : `${email} held no share on the app and had no invitation to it, so there was nothing to take back.`;
+  const wasDeleted = result2.appDeleted === true && (share || invitation) ? " The app was deleted when this was asked, so a restore will not bring it back." : "";
+  return `${found}${wasDeleted} That takes back only what was shared by name: the app's level (wirl_visibility) and the rights of its owner and the organisation's owners and admins are unchanged.`;
+}
 var listDeployments = (creds, org, app) => callApi(
   creds,
   `/api/v1/apps/${seg(org)}/${seg(app)}/deployments`
@@ -6085,7 +6457,7 @@ var fetchLogs = (creds, org, app, filters) => callApi(
 );
 var LINE_INDENT = "         ";
 function terminalSafe(text) {
-  return escapeInvisible(text.replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`));
+  return escapeInvisible(text.replace(/\r\n/g, "\n").replace(/[\u0000-\u0008\u000b-\u001f\u007f-\u009f]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`));
 }
 function utcSecond(at2) {
   const ms = Date.parse(at2);
@@ -6121,7 +6493,8 @@ function formatLogPage(page, since) {
     // queryable. Without this an empty answer right after a request
     // reads as "nothing happened".
     " A request made in the last minute may not have arrived yet: ask again shortly."
-  )}` : page.invocations.map((entry) => formatInvocation(entry)).join("\n\n");
+  )}
+${EDGE_REFUSALS_NOTE}` : page.invocations.map((entry) => formatInvocation(entry)).join("\n\n");
   return page.cursor === null ? body : `${body}
 
 More before this: pass cursor=${page.cursor}.`;
@@ -6521,20 +6894,22 @@ async function previewFetch(creds, org, app, name, path, options) {
   const headers = callerHeaders(options.headers);
   headers.set(VISIT_HEADER, mint.token);
   const networkFetch = options.networkFetchImpl ?? fetch;
-  const sentAt = Date.now();
+  const clock = options.now ?? (() => performance.now());
+  const sentAt = clock();
+  const elapsed = () => Math.round(clock() - sentAt);
   const response = await networkFetch(target.toString(), {
     method: options.method ?? (options.body !== void 0 ? "POST" : "GET"),
     headers,
     redirect: "manual",
     ...options.body === void 0 ? {} : { body: options.body }
   });
-  const headersMs = Date.now() - sentAt;
+  const headersMs = elapsed();
   const contentType = response.headers.get("content-type") ?? "";
   const location = response.headers.get("location");
   const text = isTextBody(contentType);
   const streamWaitMs = Math.min(options.streamWaitMs ?? FETCH_STREAM_WAIT_MS, FETCH_WAIT_MAX_SECONDS * 1e3);
   const keep = options.keepBodyBytes === void 0 ? null : Math.min(options.keepBodyBytes, FETCH_FILE_MAX_BYTES);
-  const read = await readBounded(response, streamWaitMs, sentAt, keep ?? FETCH_READ_CEILING_BYTES);
+  const read = await readBounded(response, streamWaitMs, elapsed, keep ?? FETCH_READ_CEILING_BYTES);
   const bytes = read.bytes;
   const truncated = text && (read.cut || bytes.byteLength > FETCH_BODY_CAP_BYTES);
   const media = (contentType.split(";")[0] ?? "").trim().toLowerCase();
@@ -6610,7 +6985,7 @@ var FETCH_STREAM_WAIT_MS = 1e4;
 var FETCH_WAIT_MAX_SECONDS = 300;
 var FETCH_READ_CEILING_BYTES = 8 * FETCH_BODY_CAP_BYTES;
 var FETCH_FILE_MAX_BYTES = 1e8;
-async function readBounded(response, waitMs, sentAt, ceilingBytes) {
+async function readBounded(response, waitMs, elapsed, ceilingBytes) {
   if (response.body === null) return { bytes: new Uint8Array(0), chunks: [], stillStreaming: false, cut: false };
   const reader = response.body.getReader();
   const chunks = [];
@@ -6629,7 +7004,7 @@ async function readBounded(response, waitMs, sentAt, ceilingBytes) {
         break;
       }
       if (next.done) break;
-      chunks.push({ atMs: Date.now() - sentAt, bytes: next.value });
+      chunks.push({ atMs: elapsed(), bytes: next.value });
       total += next.value.byteLength;
       if (total > ceilingBytes) {
         cut = true;
@@ -6674,9 +7049,9 @@ function formatFetchResult(result2, saved) {
       0,
       `answered after ${seconds(result2.headersMs)} s; ${said} line${said === 1 ? "" : "s"} in ${pieces} piece${pieces === 1 ? "" : "s"} over ${seconds(last)} s (each line shown at the time it was complete)`
     );
+    const unfinished = lastLineUnfinished(result2);
     timed.forEach((line, i) => {
-      const unfinished = i === timed.length - 1 && !result2.timed.lastComplete && (!result2.bodyComplete || result2.truncated);
-      lines.push(line.text === "" ? "" : `+${seconds(line.atMs)}s  ${line.text}${unfinished ? "  (the line had not ended)" : ""}`);
+      lines.push(line.text === "" ? "" : `+${seconds(line.atMs)}s  ${line.text}${unfinished && i === timed.length - 1 ? "  (the line had not ended)" : ""}`);
     });
   } else {
     lines.push(result2.bodyText);
@@ -6689,6 +7064,44 @@ function formatFetchResult(result2, saved) {
   }
   return lines.join("\n");
 }
+function lastLineUnfinished(result2) {
+  return result2.timed !== null && !result2.timed.lastComplete && (!result2.bodyComplete || result2.truncated);
+}
+var STREAMED_DATA_MAX_LINES = 2e3;
+var STREAMED_DATA_MAX_TEXT_BYTES = 16 * 1024;
+function streamedFetchData(result2) {
+  if (result2.bodyText === null || result2.timed === null) return null;
+  const listed2 = listedLines(result2.timed.lines);
+  return {
+    status: result2.status,
+    statusText: result2.statusText,
+    contentType: result2.contentType,
+    location: result2.location,
+    refused: result2.refused,
+    answeredAfterMs: result2.headersMs,
+    streamWaitMs: result2.streamWaitMs,
+    stillStreaming: result2.stillStreaming,
+    bodyComplete: result2.bodyComplete,
+    truncated: result2.truncated,
+    bodyBytes: result2.bodyBytes,
+    pieces: result2.timed.pieces,
+    lastLineEnded: !lastLineUnfinished(result2),
+    lines: listed2,
+    linesLeftOut: result2.timed.lines.length - listed2.length
+  };
+}
+function listedLines(all) {
+  const listed2 = [];
+  let bytes = 0;
+  for (const line of all) {
+    if (listed2.length >= STREAMED_DATA_MAX_LINES) break;
+    const size = Buffer.byteLength(line.text);
+    if (listed2.length > 0 && bytes + size > STREAMED_DATA_MAX_TEXT_BYTES) break;
+    bytes += size;
+    listed2.push({ atMs: line.atMs, text: line.text });
+  }
+  return listed2;
+}
 function seconds(ms) {
   return (ms / 1e3).toFixed(2);
 }
@@ -6709,7 +7122,7 @@ var ADOPT_SENTENCES2 = {
    */
   cannotTell: (what) => `wirl did not get the adopt route's answer (${what}), so it cannot tell whether the live database recorded migrations/${ADOPTED_FILE}, and nothing was written here. Run wirl migrations adopt again: while an adopted ${ADOPTED_FILE} is all the live database records, adopting again replaces that record and writes the file.`,
   /** After the call, so the live database records the file; a CLI that reads files otherwise than the control plane says this every time. */
-  notAsRecorded: (install) => `The live database now records migrations/${ADOPTED_FILE} as adopted, but the file wirl sent does not match its own record of it, so nothing was written here. Run wirl migrations adopt again: while an adopted ${ADOPTED_FILE} is all the live database records, adopting again replaces that record and writes the file. If it says this again, this copy of wirl reads migration files differently from the control plane: update it (npm install -g ${install}).`,
+  notAsRecorded: (install) => `The live database now records migrations/${ADOPTED_FILE} as adopted, but the file wirl sent does not match its own record of it, so nothing was written here. Run wirl migrations adopt again: while an adopted ${ADOPTED_FILE} is all the live database records, adopting again replaces that record and writes the file. If it says this again, this copy of wirl reads migration files differently from the control plane: update it (npm install -g ${install.cli}${hasFallback(install) ? `, or, to match this control plane exactly, npm install -g ${install.tarball.cli}` : ""}).`,
   unwritten: (code) => `The live database now records migrations/${ADOPTED_FILE} as adopted, but wirl could not write that file here (${code}). Make migrations/ a folder you can write that holds no .sql file, then run wirl migrations adopt again: while an adopted ${ADOPTED_FILE} is all the live database records, adopting again replaces that record and writes the file.`,
   nothingWritten: "Nothing was written to migrations/.",
   /**
@@ -6887,7 +7300,7 @@ async function adoptIntoProject(creds, options) {
   const read = await readMigrations([{ name: ADOPTED_FILE, text: answer.file.text }], []);
   const [file, ...others] = read.ok ? read.files : [];
   if (file === void 0 || others.length > 0 || file.sha256 !== answer.file.sha256 || file.statements.length !== answer.file.statements) {
-    throw new CliError(ADOPT_SENTENCES2.notAsRecorded(installFor(creds.apiOrigin).cli));
+    throw new CliError(ADOPT_SENTENCES2.notAsRecorded(installFor(creds.apiOrigin)));
   }
   const path = await writeAdopted(projectDir, answer.file.text);
   const { recordLocalAdoption: recordLocalAdoption2 } = await Promise.resolve().then(() => (init_migrations_local(), migrations_local_exports));
@@ -7039,6 +7452,8 @@ function formatMigrationsListing(listing, app) {
 init_src();
 import { hostname } from "node:os";
 import { basename as basename3, resolve as resolve5 } from "node:path";
+var reads = (title) => ({ title, readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false });
+var readsTheirText = (title) => ({ ...reads(title), openWorldHint: true });
 var APPS_DOMAIN = "wirl.run";
 var pendingLogin = null;
 function loginInstructions(login) {
@@ -7121,6 +7536,7 @@ var SHARED = [
   {
     name: "wirl_list_connections",
     description: `List the connections in the organisation: named credentials an app may be granted, such as a HubSpot or Stripe key, with the hosts each allows, who made each (by name and email) and whether it holds its key, is waiting for one, or needs none. Use this to learn the exact name to put under "connections" in wirl.json before deploying an app that needs one; a name already listed here is that connection, not a new one, and other apps may be granted it too. The app never receives the key: it calls the vendor's own real URL (fetch("https://api.hubspot.com/...")) and wirl attaches the key on the way out. Declaring one at deploy grants it at once only when you made it or are an org admin, signed in with full access, it was never revoked from that app, and no request for it is already waiting; otherwise, unless the app already holds it, it opens or keeps a request that its maker or an org admin approves. There is no tool to approve one.`,
+    annotations: reads("List connections"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7143,27 +7559,55 @@ var SHARED = [
   },
   {
     name: "wirl_share",
-    description: `Give a named colleague access to a deployed app, by email address. Use this when the user says someone should be able to see what they built. Access belongs to that person and can be taken back. Viewers are free \u2014 sharing never costs anything, so there is no reason to hesitate. Role "viewer" can open it; "editor" can also deploy to it. A connection with deploy-only access cannot share; if the server says so, tell the person to open the app's Access page in the dashboard instead.`,
+    description: `Give a named colleague access to a deployed app, by email address. Use this when the user says someone should be able to see what they built. Access belongs to that person and can be taken back. Viewers are free \u2014 sharing never costs anything, so there is no reason to hesitate. Role "viewer" can open it; "editor" can also deploy to it. Sharing again with no role keeps the role a person has: pass "role" only to give or change one, and the answer says what the role is and, when it changed one, what it was. A connection with deploy-only access cannot share; if the server says so, tell the person to open the app's Access page in the dashboard instead.`,
+    annotations: { title: "Share an app with a person", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     inputSchema: {
       type: "object",
       properties: {
         app: { type: "string", description: 'The app slug, e.g. "quarterly-dashboard".' },
         email: { type: "string", description: "Work email address of the person." },
-        role: { type: "string", enum: ["viewer", "editor"], description: "Defaults to viewer." },
+        role: {
+          type: "string",
+          enum: ["viewer", "editor"],
+          description: "Leave it out unless the person should be given or moved to a role: a new person is a viewer, and someone who already has access, or is already invited, keeps the role they have. Naming one sets it, lowering an editor to viewer included."
+        },
+        org: { type: "string", description: "Organisation slug. Optional when the person belongs to only one; otherwise the tool says which ones exist and asks." }
+      },
+      required: ["app", "email"]
+    },
+    async handler(args, ctx) {
+      const role = refuseShareRole(args["role"]);
+      const org = await defaultOrg(ctx.creds, str(args, "org"));
+      const email = str(args, "email");
+      const result2 = await shareApp(ctx.creds, org, str(args, "app"), email, role);
+      return shareSentence(result2, email, role, "mcp");
+    }
+  },
+  {
+    name: "wirl_unshare",
+    description: `Take back a named person's access to a deployed app, by the email address it was shared with. Use this when the user says someone should no longer see what they built. It takes the whole share away, one person at a time; to change a role instead, use wirl_share with "role". It also withdraws an invitation that is still waiting for an address, and works while the app is deleted and can still be restored. It says what it found; finding nothing is not an error. Needs a sign-in with full access, like wirl_share.`,
+    annotations: { title: "Take back a share", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
+    inputSchema: {
+      type: "object",
+      properties: {
+        app: { type: "string", description: 'The app slug, e.g. "quarterly-dashboard".' },
+        email: { type: "string", description: "The email address the app was shared with." },
         org: { type: "string", description: "Organisation slug. Optional when the person belongs to only one; otherwise the tool says which ones exist and asks." }
       },
       required: ["app", "email"]
     },
     async handler(args, ctx) {
+      refuseUnshareArgs(args);
       const org = await defaultOrg(ctx.creds, str(args, "org"));
-      const role = str(args, "role") === "editor" ? "editor" : "viewer";
-      const result2 = await shareApp(ctx.creds, org, str(args, "app"), str(args, "email"), role);
-      return result2.pending ? `Invited ${str(args, "email")} as ${role}. They will have access when they first sign in.${unmailedNote(result2)}` : `${str(args, "email")} can now open the app as ${role}.`;
+      const email = str(args, "email");
+      const result2 = await unshareApp(ctx.creds, org, str(args, "app"), email);
+      return unshareSentence(result2, email);
     }
   },
   {
     name: "wirl_visibility",
     description: `See or change who can open an app. With no level it only reports the current one. "private": only its owner, the organisation's owners and admins, and the people it is shared with by email. "org": everyone signed in at the organisation. Use this when the person says who the app is for ("only me", "just my team and whoever I share it with", "the whole company"). It cannot make an app public, and nothing an agent can call can: anyone on the internet being able to open it is a decision a person takes with their own click, on the app's Access page in the dashboard, so if they ask for that, give them that link. To give one named person access use wirl_share instead. A connection with deploy-only access cannot change this either; if the server says so, send the person to the same Access page.`,
+    annotations: { title: "See or set who can open an app", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -7187,6 +7631,7 @@ var SHARED = [
   {
     name: "wirl_list_apps",
     description: "List the apps the user can open, with their URLs and who can see them. Use this to find an app before deploying to it or sharing it, or when the user asks what they have already deployed.",
+    annotations: reads("List apps"),
     inputSchema: { type: "object", properties: { org: { type: "string", description: "Organisation slug. Optional when the person belongs to only one; otherwise the tool says which ones exist and asks." } } },
     async handler(args, ctx) {
       const org = await defaultOrg(ctx.creds, str(args, "org"));
@@ -7198,6 +7643,7 @@ var SHARED = [
   {
     name: "wirl_list_versions",
     description: "List past deployments of an app, newest first, with their version numbers and ids. Use this before rolling back, to find which version to return to. A preview takes a version number from the same sequence and is never listed here, so the numbers can skip: a first deploy after one preview is v2.",
+    annotations: reads("List app versions"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7216,6 +7662,7 @@ var SHARED = [
   {
     name: "wirl_rollback",
     description: "Put an earlier deployment back to being the live one. Use this when a deploy broke something and the user wants the previous version back. Instant \u2014 nothing is rebuilt. Get the deployment id from wirl_list_versions first.",
+    annotations: { title: "Roll an app back", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -7237,6 +7684,7 @@ var SHARED = [
   {
     name: "wirl_migrations",
     description: "List what one of an app's databases has applied, read only: its own record of migrations (_wirl_migrations), read now, and wirl's ledger of what it sent there, one line a file, saying where the two differ. Use this before changing anything when a deploy was refused over a migration, or said it could not tell whether a file applied. It writes nothing, and needs the access a deploy needs.",
+    annotations: reads("Show applied migrations"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7257,6 +7705,7 @@ var SHARED = [
   {
     name: "wirl_list_schedules",
     description: "List an app's schedules (from its wirl.json) with the last run's outcome and the next run time. Use this to see whether a scheduled job is healthy.",
+    annotations: reads("List schedules"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7275,6 +7724,7 @@ var SHARED = [
   {
     name: "wirl_run",
     description: "Run one of an app's schedules right now and wait for the outcome (up to the schedule's timeout). Use this after deploying a schedule to check it works, instead of waiting for the clock. With `preview`, runs one of a preview's own schedules instead: it must be declared in the previewed wirl.json (a preview writes no schedule rows, so nothing of its fires on a clock), and the outcome comes back at once, with no queue to wait on.",
+    annotations: { title: "Run a schedule now", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -7308,6 +7758,7 @@ var SHARED = [
   {
     name: "wirl_list_flows",
     description: `List the flows an app declares under "flows" in its wirl.json, each with its step timeout, its retries, how many of its runs are unfinished and its last run. Use this to find a flow's exact name before wirl_start_flow, or to see whether runs are piling up. With preview, lists what that preview's own build declares instead of the live app's.`,
+    annotations: reads("List flows"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7328,6 +7779,7 @@ var SHARED = [
   {
     name: "wirl_start_flow",
     description: "Start a run of one of an app's flows. Use this to try a flow you have built: put it up with wirl_preview, start it here with preview and fast (fast, for a preview's run only, makes each sleep, until and retry delay the flow asks for 5 seconds, each wait's timeout 60 seconds, and each retry of a failing step 10 seconds, 90 after a try that ran out of time; wirl_retry_run still refuses a failed run until 4 minutes after it failed), follow it with wirl_show_run, answer each wait it reaches with wirl_send_event, and read what each step printed with wirl_logs with the run's id, and with preview for a preview's run. A key names the run in the app's own terms: starting the flow again with the same key finds the run it started instead of starting another, until 30 days after that run ends, so give each new try a new key. The input is at most 64 KiB: keep rows in env.DB and pass ids. Where flows are not on for the organisation yet, the answer says so and nothing starts.",
+    annotations: { title: "Start a flow run", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -7373,6 +7825,7 @@ var SHARED = [
   {
     name: "wirl_list_runs",
     description: "List an app's flow runs, newest first, each with its status, the step it is at and when it started. Use this to find a run to look at with wirl_show_run, or to see which runs failed or are waiting. Narrow it with flow and status. A preview's runs are listed only with preview, and the live app's only without it.",
+    annotations: reads("List flow runs"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7397,6 +7850,7 @@ var SHARED = [
   {
     name: "wirl_show_run",
     description: `Show one flow run: its status, who started it, what it waits for or sleeps until or, while wirl is still creating it, when wirl tries again, the step it goes on with next and since or from when (a step reports only when it ends, so one that is running says it has not reported yet), its output or error, its page on the dashboard, its newest ${SHOWN_RUN_ROWS} attempts with the version of the app that answered each and each attempt's deadline, and the earlier attempts that went wrong, and its newest ${SHOWN_RUN_ROWS} events with who sent each and whether it reached the run (the run's page lists every one). Use this after wirl_start_flow to follow a run step by step, and to learn which event a waiting run asks for before wirl_send_event. A preview's run is found only with preview, and a live run only without it.`,
+    annotations: readsTheirText("Show a flow run"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7417,6 +7871,7 @@ var SHARED = [
   {
     name: "wirl_send_event",
     description: "Answer what a preview's run waits for: send it the event its wait asks for, with an optional JSON object as the event's body. Use this to walk a flow through its waits while trying it on a preview, once wirl_show_run says which event the run waits for. The event is sent as you, so its from.email is your own address, and an app that takes a decision only from people it lists takes yours only if you are listed; to try that path, list yourself in the build you preview, and never loosen the check. It is for a preview's runs only: a live run is answered by a person, on the app's own page or the run's page on the dashboard, so this refuses a live run before sending anything and says where the person goes. Only a wait open for that event takes it, and only the first answer to a wait counts.",
+    annotations: { title: "Answer a wait on a preview run", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -7458,6 +7913,7 @@ var SHARED = [
   {
     name: "wirl_cancel_run",
     description: "Cancel a flow run: a step already running is stopped where it is. Use this when a run is stuck, was started by mistake, or is doing the wrong thing. A run that had already finished is left as it is, and the answer says so. A preview's run is found only with preview, and a live run only without it.",
+    annotations: { title: "Cancel a flow run", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -7478,6 +7934,7 @@ var SHARED = [
   {
     name: "wirl_retry_run",
     description: "Run a failed flow run again, from the step it failed at, or from an earlier step with from. Use this when what made the run fail has passed, such as a vendor that was down, or once a fix is deployed live, rather than starting a new run. A run can be retried from four minutes after it failed until three days after, while Cloudflare still keeps it; outside that the answer says why. A preview's failed run cannot be retried once the preview has been deployed again or removed, or has expired: start a new run. A preview's run is found only with preview, and a live run only without it. Where flows are not on for the organisation yet, the answer says so.",
+    annotations: { title: "Retry a failed flow run", readOnlyHint: false, destructiveHint: false, idempotentHint: false, openWorldHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -7507,6 +7964,7 @@ var SHARED = [
   {
     name: "wirl_logs",
     description: "What a deployed app printed, grouped per request (page load, webhook, schedule run, flow step), newest first, with the status and any exception. Use this first when a deploy misbehaves, a schedule or webhook failed, or someone reports an error, before changing code. Defaults to the last hour. A line usually appears within a minute of the request, not at once; if the run you expect is missing, wait and read again. With `preview`, reads that preview's own script instead of the live app's history. Logs are what the app printed, as far as Cloudflare kept them: Workers Logs can miss a request's lines, all of them at times. A run's record is wirl_show_run and the run's page, not its logs: never count a run's steps from them.",
+    annotations: readsTheirText("Read app logs"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7559,6 +8017,7 @@ var SHARED = [
   {
     name: "wirl_egress",
     description: "What a deployed app called out through wirl, call by call, newest first: when, the method and host, the connection, the status, and allowed or the code wirl refused it with; a flow step's call also names its run, step number n and attempt, and the path it called, never its query string. No header or body is recorded. Use this to check which calls a page, a schedule or a flow step actually made to a vendor, or why one was refused, before changing code: two calls of a retried step differ by attempt. Defaults to the last hour, at most seven days back. A flow step's call refused because its deadline had passed is not recorded. Only the app's own calls, for someone who can deploy it, as its logs are.",
+    annotations: readsTheirText("Read app outgoing calls"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7590,6 +8049,7 @@ var SHARED = [
   {
     name: "wirl_list_previews",
     description: `List an app's previews: folders put up at their own address, never live, each with its own database (its tables from migrations/, and at first no rows but the ones those files insert). Use this to find a preview's exact name before calling wirl_preview_fetch or wirl_delete_preview, or to see when one expires. An app holds at most ${MAX_PREVIEWS_PER_APP} previews at once, each for up to ${PREVIEW_TTL_DAYS} days unless redeployed.`,
+    annotations: reads("List previews"),
     inputSchema: {
       type: "object",
       properties: {
@@ -7607,7 +8067,8 @@ var SHARED = [
   },
   {
     name: "wirl_preview_fetch",
-    description: `Make one request to a preview and show what it answers: the status, the content type, and the body as text \u2014 the page source for HTML, so you can see what the app actually rendered and fix it. Use this after wirl_preview instead of asking the person to open the link and describe what they see. A binary body reports its type and size, not its bytes. A text body over 100 KB is cut, and the answer says so. A stream (server-sent events, newline-delimited JSON, or any text still arriving after 10 seconds) is shown with the time each line arrived, as far as it got, and says whether it was still going: that is how to check a stream arrives piece by piece. A preview's own database starts with the tables in migrations/ and no rows but the ones those files insert, so a page that expects rows may look blank until something writes to it, and its schedules do not run on a clock. A 401, or a redirect back to sign in, means the visit was refused or the preview has expired or been deleted, not that the app itself answered that way. The headers argument cannot set host, cookie, content-length, or any x-wirl-* header (including x-wirl-visit): those are wirl's own, and are dropped rather than sent. This tool cannot send a file or save an answer as bytes: body is sent as text, exactly as given (an @ in it is just a character), and a binary answer reports only its type and size. From a shell, wirl fetch --data @file sends a file and --output <file> saves the answer, each up to 100,000,000 bytes.`,
+    description: `Make one request to a preview and show what it answers: the status, the content type, and the body as text \u2014 the page source for HTML, so you can see what the app actually rendered and fix it. Use this after wirl_preview instead of asking the person to open the link and describe what they see. A binary body reports its type and size, not its bytes. A text body over 100 KB is cut, and the answer says so. A stream (server-sent events, newline-delimited JSON, or any text still arriving after 10 seconds) is shown with the time each line arrived, as far as it got, and says whether it was still going: that is how to check a stream arrives piece by piece. A stream also comes back as data, in the result's structuredContent: the same lines as { atMs, text }, atMs being whole milliseconds from sending the request to the read that completed the line (lines that arrived together share one), the first ${STREAMED_DATA_MAX_LINES.toLocaleString("en-US")} lines or ${String(STREAMED_DATA_MAX_TEXT_BYTES / 1024)} KB of their text, whichever comes first (always at least the first line), with linesLeftOut counting any more (the text shows them all), and the status, the content type and the flags stillStreaming, bodyComplete, truncated and lastLineEnded; any other answer is the text alone. A preview's own database starts with the tables in migrations/ and no rows but the ones those files insert, so a page that expects rows may look blank until something writes to it, and its schedules do not run on a clock. A 401, or a redirect back to sign in, means the visit was refused or the preview has expired or been deleted, not that the app itself answered that way. The headers argument cannot set host, cookie, content-length, or any x-wirl-* header (including x-wirl-visit): those are wirl's own, and are dropped rather than sent. This tool cannot send a file or save an answer as bytes: body is sent as text, exactly as given (an @ in it is just a character), and a binary answer reports only its type and size. From a shell, wirl fetch --data @file sends a file and --output <file> saves the answer, each up to 100,000,000 bytes.`,
+    annotations: { title: "Request a page from a preview", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
     inputSchema: {
       type: "object",
       properties: {
@@ -7625,24 +8086,15 @@ var SHARED = [
       },
       required: ["app", "name", "path"]
     },
+    answer: previewFetchAnswer,
     async handler(args, ctx) {
-      const org = await defaultOrg(ctx.creds, str(args, "org"));
-      const headersArg = args["headers"];
-      const headers = headersArg !== null && typeof headersArg === "object" && !Array.isArray(headersArg) ? Object.fromEntries(Object.entries(headersArg).map(([k, v]) => [k, String(v)])) : void 0;
-      const appsDomain = ctx.appsDomain ?? (await whoami(ctx.creds)).appsDomain;
-      const result2 = await previewFetch(ctx.creds, org, str(args, "app"), str(args, "name"), str(args, "path", "/"), {
-        appsDomain,
-        ...ctx.networkFetch ? { networkFetchImpl: ctx.networkFetch } : {},
-        ...str(args, "method") ? { method: str(args, "method") } : {},
-        ...typeof args["body"] === "string" ? { body: args["body"] } : {},
-        ...headers ? { headers } : {}
-      });
-      return formatFetchResult(result2);
+      return (await previewFetchAnswer(args, ctx)).text;
     }
   },
   {
     name: "wirl_delete_preview",
     description: `Remove a preview: its script, its files, its database and its address all go away. Use this to free a slot when an app already has ${MAX_PREVIEWS_PER_APP} previews (the most it can hold at once) and a new one is needed, or when a preview is no longer wanted before its own expiry. Idempotent: deleting one already gone still succeeds.`,
+    annotations: { title: "Delete a preview", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -7665,6 +8117,7 @@ var SHARED = [
   {
     name: "wirl_delete_app",
     description: `Delete an app. Use this only when the person has asked for this app to be deleted; to try something, use wirl_preview. It is a soft delete: the app's address and its previews stop answering at once, its schedules stop and its unfinished runs are cancelled, and its data is kept for ${String(RETENTION.deletedAppGraceDays)} days. Until then its owner, while a member of the organisation, or an organisation owner or admin can bring it back with wirl apps restore <app> --org <org>, or from the Recently deleted list on the organisation's tools page in the dashboard; an app that was public comes back only from that list. Its name stays taken for good. Needs a full-scope sign-in: a deploy-scoped token is refused, with where to do it instead.`,
+    annotations: { title: "Delete an app", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
     inputSchema: {
       type: "object",
       properties: {
@@ -7685,6 +8138,7 @@ var SHARED = [
   {
     name: "wirl_whoami",
     description: "Show which account this session is signed in as and which organisations it belongs to. Use this to check the connection works, or to find an organisation slug.",
+    annotations: reads("Show who is signed in"),
     inputSchema: { type: "object", properties: {} },
     async handler(_args, ctx) {
       const me = await whoami(ctx.creds);
@@ -7692,9 +8146,26 @@ var SHARED = [
     }
   }
 ];
+async function previewFetchAnswer(args, ctx) {
+  const org = await defaultOrg(ctx.creds, str(args, "org"));
+  const headersArg = args["headers"];
+  const headers = headersArg !== null && typeof headersArg === "object" && !Array.isArray(headersArg) ? Object.fromEntries(Object.entries(headersArg).map(([k, v]) => [k, String(v)])) : void 0;
+  const appsDomain = ctx.appsDomain ?? (await whoami(ctx.creds)).appsDomain;
+  const result2 = await previewFetch(ctx.creds, org, str(args, "app"), str(args, "name"), str(args, "path", "/"), {
+    appsDomain,
+    ...ctx.networkFetch ? { networkFetchImpl: ctx.networkFetch } : {},
+    ...ctx.now ? { now: ctx.now } : {},
+    ...str(args, "method") ? { method: str(args, "method") } : {},
+    ...typeof args["body"] === "string" ? { body: args["body"] } : {},
+    ...headers ? { headers } : {}
+  });
+  const data = streamedFetchData(result2);
+  return { text: formatFetchResult(result2), ...data === null ? {} : { structured: { ...data } } };
+}
 var LOGIN = {
   name: "wirl_login",
   description: "Sign this machine in to wirl so the other wirl tools work. Use this the first time, or whenever another wirl tool says it is not signed in. It returns a link and a short code: show both to the person, ask them to open the link and approve, then retry whatever you were doing. Nothing to paste back \u2014 the token is saved for you once they approve.",
+  annotations: { title: "Sign in to wirl", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
   inputSchema: { type: "object", properties: {} },
   anonymous: true,
   async handler() {
@@ -7712,7 +8183,8 @@ var LOGIN = {
 var EXISTING_CONNECTION_SENTENCE = "A declared name the org already has is that connection, not a new one: the answer names who made it, whether it holds a key and the other apps you can open that use it. Declaring a kind it does not have is refused, unless a deploy, never a preview, may change it: it has no key, you made it or are an org admin, no other app is granted it, and neither kind is webhook_secret. ";
 var LOCAL_DEPLOY = {
   name: "wirl_deploy",
-  description: `Deploy a directory of files to a URL that colleagues can open. Use this when the user has built something \u2014 a dashboard, a report, an internal tool \u2014 and wants it somewhere real instead of on their laptop. A new app is visible to everyone in the org when the org came from a company email domain; in any other org, including a personal one or one made with wirl orgs create, it starts private. Either way, share it by email to add someone outside that. Returns the URL, and who can open the app as the edge has it when the deploy finishes (a visibility change made while it ran included). Creates the app on first deploy. A wirl.json beside or inside the directory declares a "server" module for a backend and any "connections" the app needs; the answer says which declared connections are usable now, which are waiting on an admin and which need a key, and names the flows the version declares. New files in migrations/ are applied to the app's database before the version goes live; one that fails fails the deploy, and the version already live, if any, keeps serving. A destructive file (one wirl.json's "destructive" list must name) waits for a person before it applies to the live database: the refusal gives the address of the page where they approve it, and nothing this tool takes skips that. ` + EXISTING_CONNECTION_SENTENCE + "Refuses, without uploading anything, if the directory contains what looks like a live API key or password.",
+  description: `Deploy a directory of files to a URL that colleagues can open. Use this when the user has built something \u2014 a dashboard, a report, an internal tool \u2014 and wants it somewhere real instead of on their laptop. A new app is visible to everyone in the org when the org came from a company email domain; in any other org, including a personal one or one made with wirl orgs create, it starts private. Either way, share it by email to add someone outside that. Returns the URL, and who can open the app as the edge has it when the deploy finishes (a visibility change made while it ran included). Creates the app on first deploy. A wirl.json beside or inside the directory declares a "server" module for a backend and any "connections" the app needs; the answer says which declared connections are usable now, which are waiting on an admin and which need a key, and names the flows the version declares. New files in migrations/ are applied to the app's database before the version goes live; one that fails fails the deploy, and the version already live, if any, keeps serving. A destructive file (one wirl.json's "destructive" list must name) waits for a person before it applies to the live database: the refusal gives the address of the page where they approve it, and nothing this tool takes skips that. ` + EXISTING_CONNECTION_SENTENCE + "Refuses, without uploading anything, if the directory contains what looks like a live API key or password. " + versionNumbersSentence("wirl_list_versions"),
+  annotations: { title: "Deploy an app", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -7781,6 +8253,7 @@ function connectionLines(connections) {
 var LOCAL_PULL = {
   name: "wirl_pull",
   description: "Fetch the source of a deployed app into a local directory, to change it and deploy again. Use this when the user wants to work on an app a colleague built and shared with them, or to recover the source of one of their own. Anyone who can open the app can pull it. Refuses a directory that already has files in it unless told to overwrite.",
+  annotations: { title: "Pull an app source", readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -7809,6 +8282,7 @@ var PREVIEW_LOGS_SENTENCE = "Deploying a preview again under its name replaces i
 var LOCAL_PREVIEW = {
   name: "wirl_preview",
   description: "Put a directory of files up as a preview: a version of an app that is never live, at its own address, with its own database (every file in migrations/ applied, and no rows but the ones those files insert, the first time that name is used), open to the same people who can already open the app. Use this to preview before deploying \u2014 before wirl_deploy, whenever a change has not been checked yet \u2014 then look at what it actually rendered with wirl_preview_fetch instead of asking the person to open a link and describe what they see. It uses the app's real connections (as wirl_deploy's does, the answer says which declared connections are usable now, which are waiting on an admin and which need a key, and names the flows the build declares), but its own database starts with no rows but the ones the files in migrations/ insert, and its schedules do not run on a clock, so a page that expects rows may look blank until something writes to it. " + EXISTING_CONNECTION_SENTENCE + `An app holds at most ${MAX_PREVIEWS_PER_APP} previews at once; a sixth is refused until one is deleted with wirl_delete_preview. Each one expires after ${PREVIEW_TTL_DAYS} days if not redeployed. ` + PREVIEW_LOGS_SENTENCE + "Refuses, without uploading anything, if the directory contains what looks like a live API key or password. Works for a new app too: the app is made if it is not there yet, and its own address answers 404 until wirl_deploy.",
+  annotations: { title: "Preview an app", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -7862,9 +8336,39 @@ function refuseUnlessNames(names) {
     throw new CliError(`${JSON.stringify(value)} is not ${what} name. ${validateSlug(value).message ?? ""}`.trimEnd());
   }
 }
+var UNSHARE_TAKES = `It takes a person's whole share away, one person at a time: to change a role, use wirl_share with "role". Nothing was changed.`;
+function refuseUnshareArgs(args) {
+  const allowed = ["app", "email", "org"];
+  const extra = Object.keys(args).filter((key) => !allowed.includes(key));
+  if (extra.length > 0) {
+    const listed2 = extra.map((key) => JSON.stringify(key));
+    const said = listed2.length === 1 ? listed2[0] : `${listed2.slice(0, -1).join(", ")} or ${listed2[listed2.length - 1]}`;
+    throw new CliError(`wirl_unshare takes "app", "email" and "org", not ${said}. ${UNSHARE_TAKES}`);
+  }
+  const app = args["app"];
+  if (app === void 0 || app === "") throw new CliError('Which app? Pass its slug as "app".');
+  if (typeof app !== "string") throw new CliError(`"app" is an app's slug, as text.`);
+  if (!isWellFormedSlug(app)) throw new CliError(`${JSON.stringify(app)} is not an app's name, so nothing was changed.`);
+  const email = args["email"];
+  if (email === void 0 || typeof email === "string" && email.trim() === "") {
+    throw new CliError(`Whose access? Pass the person's email address as "email".`);
+  }
+  if (typeof email !== "string") throw new CliError('"email" is one address, as text: run this once for each person.');
+  const org = args["org"];
+  if (org !== void 0 && typeof org !== "string") throw new CliError(`"org" is an organisation's name, as text.`);
+  if (typeof org === "string" && org !== "" && !isWellFormedSlug(org)) {
+    throw new CliError(`${JSON.stringify(org)} is not an organisation's name, so nothing was changed.`);
+  }
+}
+function npmFallbackLines() {
+  const origin = apiOriginFromEnv();
+  const install = installFor(origin);
+  return hasFallback(install) ? ["", `${fallbackWhen(namedControlPlane(origin))} install the wirl CLI from the control plane instead (npm install -g ${install.tarball.cli}) and run plain wirl where this says ${WIRL_BIN}.`] : [];
+}
 var REMOTE_DEPLOY = {
   name: "wirl_deploy",
-  description: "Deploy a directory of files to a URL that colleagues can open. This server runs at app.wirl.dev and cannot read files on the machine you are on, so it returns the exact commands to run in a terminal (and makes the app first, when you name one); the upload itself happens from the machine holding the files, never through this chat. A new app is visible to everyone in the org when the org came from a company email domain; in any other org, including a personal one or one made with wirl orgs create, it starts private. Returns the URL it will get.",
+  description: "Deploy a directory of files to a URL that colleagues can open. This server runs at app.wirl.dev and cannot read files on the machine you are on, so it returns the exact commands to run in a terminal (and makes the app first, when you name one); the upload itself happens from the machine holding the files, never through this chat. A new app is visible to everyone in the org when the org came from a company email domain; in any other org, including a personal one or one made with wirl orgs create, it starts private. Returns the URL it will get. " + versionNumbersSentence("wirl_list_versions"),
+  annotations: { title: "Deploy an app", readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -7880,13 +8384,13 @@ var REMOTE_DEPLOY = {
     const directory = str(args, "directory", ".");
     const app = str(args, "app");
     if (app) await ensureRemoteApp(ctx.creds, org, app);
-    const install = installFor(apiOriginFromEnv());
     return [
       app ? `App ${app} exists in ${org}. Upload it from the machine that holds the files:` : "Upload it from the machine that holds the files:",
       "",
-      `  npm install -g ${install.cli}   # once per machine`,
-      "  wirl login                      # once per machine; opens the browser",
-      `  wirl deploy ${shellPath(directory)} --org ${shellQuote(org)}${app ? ` --app ${shellQuote(app)}` : ""}`,
+      ...NPM_PUBLISHED ? [] : [`  npm install -g ${installFor(apiOriginFromEnv()).cli}   # once per machine`],
+      `  ${WIRL_BIN} login          # once per machine; ${CLI_LOGIN_DOES}`,
+      `  ${WIRL_BIN} deploy ${shellPath(directory)} --org ${shellQuote(org)}${app ? ` --app ${shellQuote(app)}` : ""}`,
+      ...npmFallbackLines(),
       "",
       app ? `It will be at https://${org}--${app}.${APPS_DOMAIN}.` : `The command takes the app from "app" in the project's wirl.json, else from the folder's name, makes it if it is new, and prints its URL.`,
       "Once it is deployed, wirl_list_apps shows who can open it.",
@@ -7897,6 +8401,7 @@ var REMOTE_DEPLOY = {
 var REMOTE_PULL = {
   name: "wirl_pull",
   description: "Fetch the source of a deployed app to work on it. This server cannot write to the machine you are on, so it returns the command to run in a terminal.",
+  annotations: reads("Pull an app source"),
   inputSchema: {
     type: "object",
     properties: {
@@ -7910,18 +8415,19 @@ var REMOTE_PULL = {
     refuseUnlessNames({ org: str(args, "org"), app: str(args, "app") });
     const org = await defaultOrg(ctx.creds, str(args, "org"));
     const app = str(args, "app");
-    const install = installFor(apiOriginFromEnv());
     return [
       "Run in a terminal:",
       "",
-      ...NPM_PUBLISHED ? [] : [`  npm install -g ${install.cli}   # once per machine`],
-      `  ${WIRL_BIN} pull ${shellQuote(app)} ${shellPath(str(args, "directory", app))} --org ${shellQuote(org)}`
+      ...NPM_PUBLISHED ? [] : [`  npm install -g ${installFor(apiOriginFromEnv()).cli}   # once per machine`],
+      `  ${WIRL_BIN} pull ${shellQuote(app)} ${shellPath(str(args, "directory", app))} --org ${shellQuote(org)}`,
+      ...npmFallbackLines()
     ].join("\n");
   }
 };
 var REMOTE_PREVIEW = {
   name: "wirl_preview",
   description: "Put a directory of files up as a preview: a version of an app that is never live, at its own address, open to the same people who can already open the app. This server runs at app.wirl.dev and cannot read files on the machine you are on, so it returns the exact command to run in a terminal; the upload itself happens from the machine holding the files, never through this chat. Prefer suggesting this over wirl_deploy for a change that has not been checked yet \u2014 preview before deploying, then look at it with wirl_preview_fetch. Works for a new app too: the command makes the app if it is not there yet. " + PREVIEW_LOGS_SENTENCE.trimEnd(),
+  annotations: reads("Preview an app"),
   inputSchema: {
     type: "object",
     properties: {
@@ -7938,10 +8444,9 @@ var REMOTE_PREVIEW = {
   async handler(args, ctx) {
     refuseUnlessNames({ org: str(args, "org"), app: str(args, "app") });
     const given = str(args, "name");
-    const slug = given === "" ? "" : slugify(given);
-    if (slug === null || slug !== "" && !isValidSlug(slug)) {
-      throw new CliError(`${JSON.stringify(given)} makes no preview name: as a slug it is empty, one character, or a reserved word.`);
-    }
+    const made = given === "" ? null : previewSlugFor(given);
+    if (made !== null && !made.ok) throw new CliError(made.message);
+    const slug = made === null ? "" : made.slug;
     const org = await defaultOrg(ctx.creds, str(args, "org"));
     const directory = str(args, "directory", ".");
     const app = str(args, "app");
@@ -7952,8 +8457,9 @@ var REMOTE_PREVIEW = {
       "Upload it from the machine that holds the files:",
       "",
       ...NPM_PUBLISHED ? [] : [`  npm install -g ${installFor(apiOriginFromEnv()).cli}   # once per machine`],
-      `  ${WIRL_BIN} login          # once per machine; opens the browser`,
+      `  ${WIRL_BIN} login          # once per machine; ${CLI_LOGIN_DOES}`,
       `  ${WIRL_BIN} preview ${shellPath(directory)} --org ${shellQuote(org)}${app ? ` --app ${shellQuote(app)}` : ""}${name ? ` --name ${shellQuote(name)}` : ""}`,
+      ...npmFallbackLines(),
       "",
       ...app ? [] : [`The command takes the app from "app" in the project's wirl.json, else from the folder's name.`],
       "Once it is up, wirl_preview_fetch shows you what it actually renders.",
@@ -7972,6 +8478,7 @@ async function manifestFolder(directory) {
 var LOCAL_MIGRATIONS_ADOPT = {
   name: "wirl_migrations_adopt",
   description: `${MIGRATIONS_ADOPT_WHAT} The project's .wirl/local.sqlite is recorded too when it has the same shape and no record of other files, so wirl dev keeps its rows. Pointed at build output, it writes beside the wirl.json next to it, and the build must copy migrations/ to the top of what it deploys. Adopting again replaces the record of an earlier adopt, and is refused once a later file has applied.`,
+  annotations: { title: "Adopt app tables as migrations", readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: false },
   inputSchema: {
     type: "object",
     properties: {
@@ -7995,6 +8502,7 @@ var LOCAL_MIGRATIONS_ADOPT = {
 var REMOTE_MIGRATIONS_ADOPT = {
   name: "wirl_migrations_adopt",
   description: `${MIGRATIONS_ADOPT_WHAT} This server runs at app.wirl.dev and cannot write files on the machine you are on, so it returns the command to run in a terminal there.`,
+  annotations: reads("Adopt app tables as migrations"),
   inputSchema: {
     type: "object",
     properties: {
@@ -8013,8 +8521,9 @@ var REMOTE_MIGRATIONS_ADOPT = {
       "Run it on the machine that holds the project, in a terminal:",
       "",
       ...NPM_PUBLISHED ? [] : [`  npm install -g ${installFor(apiOriginFromEnv()).cli}   # once per machine`],
-      `  ${WIRL_BIN} login          # once per machine; opens the browser`,
+      `  ${WIRL_BIN} login          # once per machine; ${CLI_LOGIN_DOES}`,
       `  ${WIRL_BIN} migrations adopt ${shellPath(directory)} --org ${shellQuote(org)}${app ? ` --app ${shellQuote(app)}` : ""}`,
+      ...npmFallbackLines(),
       "",
       ...app ? [] : [`The command takes the app from "app" in the project's wirl.json, else from the folder's name.`],
       "It writes migrations/0001_init.sql beside wirl.json from the live database's shape, never a row, and the live database records it as applied.",
@@ -8034,6 +8543,7 @@ function toolsFor(mode) {
 var SERVER_INSTRUCTIONS = [
   "wirl deploys a small internal tool to a URL colleagues can open, with company sign-in, a database and vaulted API keys already wired up.",
   "Reach for it whenever what you just built should live somewhere shared instead of only on this machine.",
+  ...NPM_PUBLISHED ? [`The text below writes a command as \`wirl <command>\` for short; run one as \`${WIRL_BIN} <command>\`, which needs no install beyond Node 22.13 or later.`] : [],
   "",
   BUILD_CONTRACT,
   "",
@@ -8048,6 +8558,14 @@ function negotiate(requested) {
 function result(id, value) {
   return JSON.stringify({ jsonrpc: "2.0", id, result: value });
 }
+function escapeInvisibleDeep(value) {
+  if (typeof value === "string") return escapeInvisible(value);
+  if (Array.isArray(value)) return value.map(escapeInvisibleDeep);
+  if (value !== null && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key, escapeInvisibleDeep(inner)]));
+  }
+  return value;
+}
 function failure(id, code, message) {
   return JSON.stringify({ jsonrpc: "2.0", id, error: { code, message } });
 }
@@ -8060,7 +8578,7 @@ async function handleRpc(request, ctx) {
       return result(id, {
         protocolVersion: negotiate(request.params?.["protocolVersion"]),
         capabilities: { tools: {} },
-        serverInfo: { name: "wirl", version: "0.0.0" },
+        serverInfo: { name: "wirl", version: ctx?.serverVersion ?? wirlVersion() },
         instructions: SERVER_INSTRUCTIONS
       });
     // Notifications carry no id and expect no reply.
@@ -8073,7 +8591,10 @@ async function handleRpc(request, ctx) {
         tools: tools.map((t) => ({
           name: t.name,
           description: t.description,
-          inputSchema: t.inputSchema
+          inputSchema: t.inputSchema,
+          // After the three fields every client has always read: a client
+          // that knows no annotations ignores it (OIM-844).
+          annotations: t.annotations
         }))
       });
     case "tools/call": {
@@ -8083,8 +8604,17 @@ async function handleRpc(request, ctx) {
       if (!tool) return failure(id, -32602, `Unknown tool: ${name}`);
       const args = params["arguments"] ?? {};
       try {
-        const text = tool.anonymous ? await tool.handler(args) : await tool.handler(args, ctx ?? { creds: await credentialsOrPending(), mode: "local" });
-        return result(id, { content: [{ type: "text", text: escapeInvisible(text) }] });
+        let answer;
+        if (tool.anonymous) {
+          answer = { text: await tool.handler(args) };
+        } else {
+          const context = ctx ?? { creds: await credentialsOrPending(), mode: "local" };
+          answer = tool.answer ? await tool.answer(args, context) : { text: await tool.handler(args, context) };
+        }
+        return result(id, {
+          content: [{ type: "text", text: escapeInvisible(answer.text) }],
+          ...answer.structured === void 0 ? {} : { structuredContent: escapeInvisibleDeep(answer.structured) }
+        });
       } catch (error) {
         const message = error instanceof CliError ? [error.message, error.hint].filter(Boolean).join("\n") : error instanceof Error ? error.message : String(error);
         return result(id, { content: [{ type: "text", text: escapeInvisible(message) }], isError: true });