pi-simocracy 0.5.1 → 0.6.1

package/src/index.ts

@@ -48,6 +48,23 @@
  *                             style for the loaded sim to the user's
  *                             PDS. Requires the user to be signed in
  *                             via /sim login AND to own the sim.
+ *  - `simocracy_post_comment` Write a comment on a proposal /
+ *                             gathering / sim / decision / parent
+ *                             comment, attributed to the loaded sim
+ *                             via an `org.simocracy.history` sidecar
+ *                             (no impactindexer lexicon changes).
+ *                             Requires /sim login + ownership.
+ *  - `simocracy_post_proposal` Submit a new funding proposal
+ *                             (`org.hypercerts.claim.activity`) on
+ *                             behalf of the loaded sim, plus an
+ *                             `org.simocracy.history` sidecar with
+ *                             `type: "proposal"`. Same write pattern
+ *                             as `simocracy_post_comment`. Requires
+ *                             /sim login + sim ownership.
+ *  - `simocracy_lookup_record` Look up a sim / proposal / gathering /
+ *                             decision / comment by AT-URI or fuzzy
+ *                             name and return its details + comment
+ *                             subtree with sim attribution joined.
  *
  * Note on /login: pi itself ships a built-in `/login` for Anthropic OAuth.
  * To avoid the collision (and to make it explicit you're signing into
@@ -84,6 +101,13 @@ import {
   type SimMatch,
   type StyleRecord,
 } from "./simocracy.ts";
+import {
+  bestNameForRecord,
+  lookupRecord,
+  type LookupKind,
+  type LookupResult,
+  type ResolvedComment,
+} from "./lookup.ts";
 import {
   decodePng,
   renderRgbaToAnsi,
@@ -101,6 +125,10 @@ import { readAuth } from "./auth/storage.ts";
 import {
   assertCanWriteToSim,
   createAgents,
+  createComment,
+  createCommentHistory,
+  createProposal,
+  createProposalHistory,
   createStyle,
   findRkeyForSim,
   getAuthenticatedAgent,
@@ -459,6 +487,26 @@ async function renderSprite(sim: SimMatch): Promise<SpriteRender | null> {
   return null;
 }
 
+/**
+ * Subcommand keywords reserved by the `/sim` dispatcher. The dispatcher
+ * routes these BEFORE falling through to `runLoadFlow`, but we also
+ * guard the load flow itself against them as defense-in-depth — if a
+ * future regression ever leaks one of these into `runLoadFlow`, the
+ * user gets a "did you mean…?" hint instead of a misleading
+ * "Searching for 'login'…" + indexer-fetch error.
+ */
+const RESERVED_SUBCOMMANDS = new Set([
+  "help",
+  "login",
+  "logout",
+  "whoami",
+  "my",
+  "mine",
+  "unload",
+  "clear",
+  "status",
+]);
+
 async function loadSimByName(query: string): Promise<{
   matches: SimMatch[];
   loaded?: LoadedSim;
@@ -468,7 +516,15 @@ async function loadSimByName(query: string): Promise<{
   try {
     matches = await searchSimsByName(query, { maxResults: 8 });
   } catch (err) {
-    return { matches: [], error: `Indexer search failed: ${(err as Error).message}` };
+    const msg = (err as Error).message;
+    // Node's "fetch failed" is opaque — the user can't tell whether the
+    // indexer is down, their network is down, or DNS is broken. Rewrite
+    // it into something actionable.
+    const friendly =
+      msg === "fetch failed" || msg.includes("fetch failed")
+        ? "could not reach the Simocracy indexer at simocracy-indexer-production.up.railway.app — check your internet connection"
+        : msg;
+    return { matches: [], error: `Indexer search failed: ${friendly}` };
   }
   if (matches.length === 0) {
     return { matches: [], error: `No sim found matching "${query}".` };
@@ -605,6 +661,159 @@ const UpdateSimToolParams = Type.Object({
   ),
 });
 
+const PostCommentToolParams = Type.Object({
+  subjectUri: Type.String({
+    description:
+      "AT-URI of the record to comment on. Accepts proposals (org.hypercerts.claim.activity), gatherings (org.simocracy.gathering), sims (org.simocracy.sim), decisions (org.simocracy.decision), or another comment URI for a nested reply. Get one by calling simocracy_lookup_record first if you don't already have it.",
+    minLength: 1,
+  }),
+  text: Type.String({
+    description:
+      "The comment body. Plain text up to ~5000 chars. Write it as the loaded sim would speak \u2014 the sim's persona is already injected into your system prompt, so just say what they'd say.",
+    minLength: 1,
+    maxLength: 5000,
+  }),
+});
+
+/**
+ * Default cover image used by simocracy.org's `ProposalFormDialog` when the
+ * user doesn't upload anything. We mirror that exactly so a pi-authored
+ * proposal renders with the same banner as a webapp-authored one.
+ */
+const DEFAULT_PROPOSAL_BANNER_URI =
+  "https://www.simocracy.org/ftc-sf-default.jpeg";
+
+/**
+ * Mirror of simocracy-v2's `appendBudgetToDescription` — markers verbatim
+ * from `lib/budget-items.ts` so the block round-trips through the
+ * webapp's `parseDescriptionWithBudget` reader untouched. We only
+ * implement the *append* side here; pi-simocracy never parses
+ * existing descriptions back out (proposals are create-only).
+ *
+ * Returns the description unchanged when `items` is empty or contains
+ * no valid (non-empty name + positive amount) entries.
+ */
+const BUDGET_HEADER = "━━━ Budget Request ━━━";
+const TOTAL_PREFIX = "━━━ Total: ";
+const TOTAL_SUFFIX = " ━━━";
+
+function formatProposalUsd(amount: number): string {
+  const hasDecimals = !Number.isInteger(amount);
+  return new Intl.NumberFormat("en-US", {
+    style: "currency",
+    currency: "USD",
+    minimumFractionDigits: hasDecimals ? 2 : 0,
+    maximumFractionDigits: 2,
+  }).format(amount);
+}
+
+function appendBudgetToDescription(
+  description: string,
+  items: Array<{ item: string; amountUsd: number }>,
+): string {
+  const valid = items.filter(
+    (i) => i.item.trim() !== "" && i.amountUsd > 0 && Number.isFinite(i.amountUsd),
+  );
+  if (valid.length === 0) return description;
+  const total = valid.reduce((sum, i) => sum + i.amountUsd, 0);
+  const block = [
+    BUDGET_HEADER,
+    ...valid.map(
+      (i) => `• ${i.item.trim()} — ${formatProposalUsd(i.amountUsd)}`,
+    ),
+    `${TOTAL_PREFIX}${formatProposalUsd(total)}${TOTAL_SUFFIX}`,
+  ].join("\n");
+  const base = description.trim();
+  return base ? `${base}\n\n${block}` : block;
+}
+
+const PostProposalToolParams = Type.Object({
+  title: Type.String({
+    description:
+      "Proposal title in the sim's voice. Required, max 256 chars. The sim is already in your system prompt — write the title as they'd phrase it.",
+    minLength: 1,
+    maxLength: 256,
+  }),
+  shortDescription: Type.String({
+    description:
+      "One- or two-sentence pitch for the proposal, in the sim's voice. Required, max 300 chars. Shows up in proposal lists on simocracy.org.",
+    minLength: 1,
+    maxLength: 300,
+  }),
+  description: Type.Optional(
+    Type.String({
+      description:
+        "Long-form proposal body in the sim's voice. Plain text. Optional — pass when the user has discussed the project in detail. If `budgetItems` is also passed, an itemized budget block is appended automatically.",
+    }),
+  ),
+  workScope: Type.Optional(
+    Type.String({
+      description:
+        "Comma-separated tags describing the work scope (e.g. \"urban agriculture, food security\"). Optional. Stored as a bare string the same way simocracy.org's webapp writes it.",
+    }),
+  ),
+  contributors: Type.Optional(
+    Type.Array(Type.String({ minLength: 1 }), {
+      description:
+        "DIDs, handles, or freeform names of people credited as contributors. One entry per contributor. Optional.",
+    }),
+  ),
+  budgetItems: Type.Optional(
+    Type.Array(
+      Type.Object({
+        item: Type.String({
+          minLength: 1,
+          description: "What the line-item is funding (e.g. \"Solar panels\").",
+        }),
+        amountUsd: Type.Number({
+          minimum: 0,
+          description: "USD amount for this line-item. Must be > 0 to be included.",
+        }),
+      }),
+      {
+        description:
+          "Itemized budget request. When provided, an `━━━ Budget Request ━━━` block is appended to `description` so it renders the same way simocracy.org's proposal form writes it. Pass when the user discussed a budget; omit when they didn't.",
+      },
+    ),
+  ),
+  imageUri: Type.Optional(
+    Type.String({
+      description:
+        "https URL for the cover image. Defaults to the Simocracy banner if omitted. Image upload from disk is not supported — pass a URL or leave blank.",
+    }),
+  ),
+});
+
+const LookupRecordToolParams = Type.Object({
+  query: Type.String({
+    description:
+      "AT-URI (at://did/collection/rkey) or fuzzy name to look up. AT-URI fetches the exact record from its owner's PDS; a name searches the indexer.",
+    minLength: 1,
+  }),
+  kind: Type.Optional(
+    Type.Union(
+      [
+        Type.Literal("auto"),
+        Type.Literal("sim"),
+        Type.Literal("proposal"),
+        Type.Literal("gathering"),
+        Type.Literal("decision"),
+        Type.Literal("comment"),
+      ],
+      {
+        description:
+          "Restrict the search to one record kind. `auto` (default) searches sims + proposals + gatherings + decisions in parallel and returns the best match. `comment` is only meaningful with an AT-URI query \u2014 comments aren't full-text searchable.",
+      },
+    ),
+  ),
+  withComments: Type.Optional(
+    Type.Boolean({
+      description:
+        "Include the full comment subtree in the response, with sim attribution joined from org.simocracy.history sidecars. Default true. Set false for a smaller, record-only response.",
+    }),
+  ),
+});
+
 export default async function simocracy(pi: ExtensionAPI) {
   // -------------------------------------------------------------------------
   // System prompt injection — every turn the loaded sim's persona is appended.
@@ -746,8 +955,18 @@ export default async function simocracy(pi: ExtensionAPI) {
     description:
       "Simocracy: load sims, edit your own sim's constitution/style, sign into ATProto. `/sim help` for the full list.",
     handler: async (args, ctx) => {
-      const arg = args.trim();
-      if (!arg || arg === "help" || arg === "--help") {
+      // Strip zero-width / format characters that survive `.trim()` —
+      // a stray U+200B (ZWSP) glued onto "login" by a paste from a
+      // chat client is enough to make `arg === "login"` fail and
+      // route the request through `runLoadFlow` as if it were a sim
+      // name. We match subcommand keywords against the *lowercased*
+      // form, but pass the original-case clean arg through to handlers
+      // (sim names are user-facing strings; preserve their case).
+      const arg = args
+        .trim()
+        .replace(/[\u200B-\u200F\u202A-\u202E\u2060\uFEFF]/g, "");
+      const argLower = arg.toLowerCase();
+      if (!arg || argLower === "help" || argLower === "--help") {
         ctx.ui.notify(
           "Sim:\n" +
             "  /sim <name>            load a sim (e.g. /sim mr meow)\n" +
@@ -774,27 +993,28 @@ export default async function simocracy(pi: ExtensionAPI) {
       }
       // ATProto auth subcommands — must come BEFORE the sim-name
       // fallthrough (`runLoadFlow`) so we don't accidentally treat
-      // "login" as a sim name to load from the indexer.
-      if (arg === "login" || arg.startsWith("login ") || arg.startsWith("login\t")) {
+      // "login" as a sim name to load from the indexer. Match on
+      // `argLower` so `/sim Login` and `/sim LOGIN` route the same way.
+      if (argLower === "login" || argLower.startsWith("login ") || argLower.startsWith("login\t")) {
         const rest = arg.slice("login".length).trim();
         await runLogin(ctx, rest);
         return;
       }
-      if (arg === "logout") {
+      if (argLower === "logout") {
         await runLogout(ctx);
         return;
       }
-      if (arg === "whoami") {
+      if (argLower === "whoami") {
         await runWhoami(ctx);
         return;
       }
-      if (arg === "my" || arg === "mine" || arg.startsWith("my ") || arg.startsWith("my\t") || arg.startsWith("mine ") || arg.startsWith("mine\t")) {
-        const headLen = arg.startsWith("mine") ? 4 : 2;
+      if (argLower === "my" || argLower === "mine" || argLower.startsWith("my ") || argLower.startsWith("my\t") || argLower.startsWith("mine ") || argLower.startsWith("mine\t")) {
+        const headLen = argLower.startsWith("mine") ? 4 : 2;
         const rest = arg.slice(headLen).trim();
         await runMySimsCommand(pi, ctx, rest);
         return;
       }
-      if (arg === "unload" || arg === "clear") {
+      if (argLower === "unload" || argLower === "clear") {
         if (!loadedSim) {
           ctx.ui.notify("No sim loaded.", "info");
           return;
@@ -808,7 +1028,7 @@ export default async function simocracy(pi: ExtensionAPI) {
         ctx.ui.notify(`Unloaded ${name}. Pi will break character on the next reply.`, "info");
         return;
       }
-      if (arg === "status") {
+      if (argLower === "status") {
         if (!loadedSim) {
           ctx.ui.notify("No sim loaded. Try `/sim mr meow`.", "info");
           return;
@@ -1115,8 +1335,646 @@ export default async function simocracy(pi: ExtensionAPI) {
       };
     },
   });
+
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_post_comment
+  //
+  // Writes a comment on behalf of the currently loaded sim. Two records
+  // are written to the user's PDS:
+  //
+  //   1. org.impactindexer.review.comment   the comment itself (same wire
+  //      shape simocracy.org's webapp writes today, so it threads + renders
+  //      identically there).
+  //   2. org.simocracy.history               sidecar with type="comment",
+  //      simUris=[loadedSim], subjectUri=<comment uri>. Renderers that
+  //      understand the join (simocracy.org, when the planned change
+  //      lands) display a sim badge; renderers that don't see a regular
+  //      user comment — graceful degradation, zero lexicon changes.
+  //
+  // See `docs/SIM_AUTHORED_COMMENTS.md` for the full design.
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_post_comment",
+    label: "Post a comment as the loaded Simocracy sim",
+    description:
+      "Post a comment on a Simocracy record (proposal / gathering / sim / decision / another comment) as the currently loaded sim. The comment text should sound like the sim \u2014 their persona is already in your system prompt. Writes the comment to the user's PDS plus an org.simocracy.history sidecar that attributes the comment to the loaded sim (no impactindexer lexicon changes needed). Use this when the user asks the sim to weigh in on something, comment on a proposal, reply to another comment, or leave their opinion. Requires /sim login + ownership of the loaded sim.",
+    parameters: PostCommentToolParams,
+    async execute(_id, { subjectUri, text }) {
+      if (!loadedSim) {
+        throw new Error(
+          "No sim loaded. Call simocracy_load_sim first \u2014 comments are written on behalf of a specific sim.",
+        );
+      }
+      let auth;
+      try {
+        auth = await assertCanWriteToSim(loadedSim, { action: "post a comment as" });
+      } catch (err) {
+        if (err instanceof NotSignedInError || err instanceof NotSimOwnerError) {
+          throw new Error(err.message);
+        }
+        throw err;
+      }
+      let pdsAgent;
+      try {
+        ({ agent: pdsAgent } = await getAuthenticatedAgent());
+      } catch (err) {
+        if (err instanceof NotSignedInError) throw new Error(err.message);
+        throw new Error(`ATProto auth failed: ${(err as Error).message}`);
+      }
+
+      // Best-effort fetch of the parent record so we can denormalize its
+      // title onto the history sidecar (drives the timeline UX in
+      // simocracy.org). Failure is non-fatal — the comment goes through
+      // either way, the badge just won't carry a title.
+      let parentName: string | undefined;
+      let parentCollection: string | undefined;
+      try {
+        const parsed = parseAtUri(subjectUri);
+        parentCollection = parsed.collection;
+        const { getRecordFromPds } = await import("./simocracy.ts");
+        const parentValue = await getRecordFromPds<Record<string, unknown>>(
+          parsed.did,
+          parsed.collection,
+          parsed.rkey,
+        );
+        parentName = bestNameForRecord(parsed.collection, parentValue);
+      } catch {
+        /* non-fatal — leave parentName undefined */
+      }
+
+      let comment;
+      try {
+        comment = await createComment({
+          agent: pdsAgent,
+          did: auth.did,
+          subjectUri,
+          text,
+        });
+      } catch (err) {
+        throw new Error(`Comment write failed: ${(err as Error).message}`);
+      }
+
+      let attributionUri: string | undefined;
+      let attributionWarning: string | undefined;
+      try {
+        const history = await createCommentHistory({
+          agent: pdsAgent,
+          did: auth.did,
+          commentUri: comment.uri,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
+          text,
+          proposalTitle: parentName,
+          parentCollection,
+          parentName,
+        });
+        attributionUri = history.uri;
+      } catch (err) {
+        // Don't fail the whole call — the comment is already on the user's
+        // PDS. The sidecar can be re-written later. Surface the warning so
+        // the LLM can decide whether to retry.
+        attributionWarning = `Sim-attribution sidecar failed: ${(err as Error).message}`;
+      }
+
+      const lines = [
+        `Posted comment as ${loadedSim.name}${loadedSim.handle ? ` (@${loadedSim.handle})` : ""}:`,
+        `  comment URI: ${comment.uri}`,
+      ];
+      if (parentName) lines.push(`  on:          ${parentName} (${subjectUri})`);
+      else lines.push(`  on:          ${subjectUri}`);
+      if (attributionUri) {
+        lines.push(`  attribution: ${attributionUri}  (org.simocracy.history sidecar)`);
+      } else if (attributionWarning) {
+        lines.push(`  WARNING:     ${attributionWarning}`);
+        lines.push(
+          `               The comment is posted but will appear unattributed until a history sidecar is written.`,
+        );
+      }
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+        details: {
+          commentUri: comment.uri,
+          commentRkey: comment.rkey,
+          subjectUri,
+          parentName,
+          parentCollection,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
+          attributionUri,
+          attributionWarning,
+        },
+      };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_post_proposal
+  //
+  // Submit a new funding proposal on behalf of the loaded sim. Two
+  // records are written to the user's PDS, mirroring simocracy_post_comment:
+  //
+  //   1. org.hypercerts.claim.activity   the proposal itself, in the same
+  //      wire shape simocracy.org's ProposalFormDialog writes today, so it
+  //      renders identically in the webapp.
+  //   2. org.simocracy.history           sidecar with type="proposal",
+  //      simUris=[loadedSim], subjectUri=<proposal uri>. Renderers that
+  //      understand the join show the sim badge; others see a regular
+  //      proposal — graceful degradation, zero lexicon changes.
+  //
+  // See `docs/SIM_AUTHORED_PROPOSALS.md` for the full design.
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_post_proposal",
+    label: "Submit a Simocracy proposal as the loaded sim",
+    description:
+      "Submit a new funding proposal to Simocracy on behalf of the currently loaded sim. The sim should write the title + shortDescription + description in their own voice (their persona is already in your system prompt). Writes the proposal to the user's PDS plus an org.simocracy.history sidecar attributing the draft to the loaded sim. Use this when the user asks the sim to draft, propose, or submit a proposal — e.g. \"Mr Meow, propose a cat sanctuary\" or \"draft a proposal for solar panels\". Pass `budgetItems` if a budget request was discussed; pass `workScope` for tag-style categorization; pass `contributors` for credited humans. Image is optional and URL-only (the default Simocracy banner is used otherwise). Requires /sim login + a loaded sim the user owns.",
+    parameters: PostProposalToolParams,
+    async execute(
+      _id,
+      { title, shortDescription, description, workScope, contributors, budgetItems, imageUri },
+    ) {
+      if (!loadedSim) {
+        throw new Error(
+          "No sim loaded. Call simocracy_load_sim first — proposals are submitted on behalf of a specific sim.",
+        );
+      }
+      let auth;
+      try {
+        auth = await assertCanWriteToSim(loadedSim, { action: "post a proposal as" });
+      } catch (err) {
+        if (err instanceof NotSignedInError || err instanceof NotSimOwnerError) {
+          throw new Error(err.message);
+        }
+        throw err;
+      }
+      let pdsAgent;
+      try {
+        ({ agent: pdsAgent } = await getAuthenticatedAgent());
+      } catch (err) {
+        if (err instanceof NotSignedInError) throw new Error(err.message);
+        throw new Error(`ATProto auth failed: ${(err as Error).message}`);
+      }
+
+      // Resolve the cover image — either an LLM-supplied https URL or
+      // the simocracy.org default banner. Reject non-https schemes
+      // (data:, javascript:, file://) defensively even though the only
+      // real downstream consumer is the webapp's <Image> component.
+      let imageRef: { $type: "org.hypercerts.defs#uri"; uri: string };
+      if (imageUri !== undefined) {
+        const trimmed = imageUri.trim();
+        if (!/^https:\/\//i.test(trimmed)) {
+          throw new Error(
+            `imageUri must be an https URL (got "${trimmed}"). Pass an https URL, or omit imageUri to use the default Simocracy banner.`,
+          );
+        }
+        imageRef = { $type: "org.hypercerts.defs#uri", uri: trimmed };
+      } else {
+        imageRef = { $type: "org.hypercerts.defs#uri", uri: DEFAULT_PROPOSAL_BANNER_URI };
+      }
+
+      // Append the budget block (if any) to the user-authored description,
+      // exactly the same way simocracy.org's ProposalFormDialog does.
+      const baseDescription = description?.trim() ?? "";
+      const finalDescription = budgetItems
+        ? appendBudgetToDescription(baseDescription, budgetItems)
+        : baseDescription;
+
+      // Build contributors in the lexicon shape:
+      // `Array<{ contributorIdentity: string }>`. Drop blank entries.
+      const contributorRecords =
+        contributors && contributors.length > 0
+          ? contributors
+              .map((c) => c.trim())
+              .filter((c) => c.length > 0)
+              .map((contributorIdentity) => ({ contributorIdentity }))
+          : undefined;
+
+      let proposal;
+      try {
+        proposal = await createProposal({
+          agent: pdsAgent,
+          did: auth.did,
+          title,
+          shortDescription,
+          description: finalDescription || undefined,
+          workScope: workScope?.trim() || undefined,
+          contributors:
+            contributorRecords && contributorRecords.length > 0
+              ? contributorRecords
+              : undefined,
+          image: imageRef,
+        });
+      } catch (err) {
+        throw new Error(`Proposal write failed: ${(err as Error).message}`);
+      }
+
+      let sidecarUri: string | undefined;
+      let sidecarWarning: string | undefined;
+      try {
+        const history = await createProposalHistory({
+          agent: pdsAgent,
+          did: auth.did,
+          proposalUri: proposal.uri,
+          proposalTitle: title,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
+          content: finalDescription || shortDescription,
+        });
+        sidecarUri = history.uri;
+      } catch (err) {
+        // Don't roll back — the proposal is already on the user's PDS.
+        // The sidecar can be re-written later. Surface the warning so the
+        // LLM can decide whether to retry.
+        sidecarWarning = `Sim-attribution sidecar failed: ${(err as Error).message}`;
+      }
+
+      const lines = [
+        `Submitted proposal as ${loadedSim.name}${loadedSim.handle ? ` (@${loadedSim.handle})` : ""}:`,
+        `  title:        ${title}`,
+        `  proposal URI: ${proposal.uri}`,
+        `  image:        ${imageRef.uri}`,
+      ];
+      if (sidecarUri) {
+        lines.push(`  attribution:  ${sidecarUri}  (org.simocracy.history sidecar)`);
+      } else if (sidecarWarning) {
+        lines.push(`  WARNING:      ${sidecarWarning}`);
+        lines.push(
+          `                The proposal is posted but will appear unattributed until a history sidecar is written.`,
+        );
+      }
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+        details: {
+          proposalUri: proposal.uri,
+          proposalRkey: proposal.rkey,
+          proposalCid: proposal.cid,
+          title,
+          shortDescription,
+          imageUri: imageRef.uri,
+          workScope: workScope?.trim() || undefined,
+          contributors: contributorRecords,
+          budgetItemCount: budgetItems?.length ?? 0,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
+          sidecarUri,
+          sidecarWarning,
+        },
+      };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_lookup_record
+  //
+  // Look up a sim / proposal / gathering / decision / comment by AT-URI
+  // (exact, fetched from the owner's PDS) or by fuzzy name (fan-out
+  // search across both indexers). Returns the record + comment subtree
+  // with sim attribution joined from org.simocracy.history sidecars.
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_lookup_record",
+    label: "Look up a Simocracy record",
+    description:
+      "Fetch a Simocracy record (sim, proposal, gathering, decision, or comment) by AT-URI or fuzzy name and return its details plus the full comment subtree with sim attribution joined. Use this before `simocracy_post_comment` to find the right `subjectUri`, to inspect what's been said about something, or to read a specific comment thread. Comments authored by sims are flagged with their sim name and AT-URI in the response, so you can tell at a glance which opinions are human and which are sim.",
+    parameters: LookupRecordToolParams,
+    async execute(_id, { query, kind, withComments }) {
+      const { result, alternatives } = await lookupRecord(query, {
+        kind: (kind ?? "auto") as LookupKind,
+        withComments: withComments ?? true,
+      });
+      if (!result) {
+        const tail = alternatives.length
+          ? `\n\nClosest alternatives:\n${alternatives
+              .map((a) => `  - [${a.kind}] ${a.name || "(untitled)"}  ${a.uri}`)
+              .join("\n")}`
+          : "";
+        throw new Error(
+          `No record matching "${query}" (kind=${kind ?? "auto"}).${tail}`,
+        );
+      }
+      return {
+        content: [{ type: "text" as const, text: formatLookupResult(result, alternatives) }],
+        details: {
+          kind: result.kind,
+          uri: result.uri,
+          did: result.did,
+          rkey: result.rkey,
+          collection: result.collection,
+          name: result.name,
+          ownerHandle: result.ownerHandle,
+          attribution: result.attribution,
+          parent: result.parent,
+          commentCount: result.comments?.length ?? 0,
+          simAuthoredCommentCount:
+            result.comments?.filter((c) => c.simUri).length ?? 0,
+          alternatives: alternatives.map((a) => ({
+            kind: a.kind,
+            uri: a.uri,
+            name: a.name,
+          })),
+        },
+      };
+    },
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Lookup-result formatter
+//
+// Renders a `LookupResult` as a compact, LLM-friendly markdown block.
+// Calling out sim-authored comments with a 🐾 prefix is the whole
+// point of the human-vs-sim distinction described in
+// docs/SIM_AUTHORED_COMMENTS.md — keep it visually distinct from plain
+// `@handle` lines.
+// ---------------------------------------------------------------------------
+
+interface SearchHitForFormat {
+  kind: string;
+  uri: string;
+  name: string;
+}
+
+function formatLookupResult(
+  result: LookupResult,
+  alternatives: SearchHitForFormat[] = [],
+): string {
+  const lines: string[] = [];
+  const kindLabel = result.kind.toUpperCase();
+  const ownerLabel = result.ownerHandle ? `@${result.ownerHandle}` : result.did;
+  lines.push(`# [${kindLabel}] ${result.name || "(untitled)"}`);
+  lines.push(`- URI:   ${result.uri}`);
+  lines.push(`- Owner: ${ownerLabel} (${result.did})`);
+
+  // Kind-specific structured fields (status, treasury, dates, contributors
+  // — the operationally important stuff that doesn't fit in a generic
+  // shortDescription block). Rendered as a compact `Field: value` table.
+  const v = result.value;
+  const facts = collectKindFacts(result.kind, v);
+  if (facts.length > 0) {
+    lines.push("");
+    for (const [k, val] of facts) lines.push(`- ${k}: ${val}`);
+  }
+
+  // Long-form summary (shortDescription / description / context). Capped at
+  // ~25 lines so a verbose gathering context doesn't drown the rest of the
+  // tool output.
+  const longText =
+    (typeof v.shortDescription === "string" && v.shortDescription) ||
+    (typeof v.description === "string" && v.description) ||
+    (typeof v.context === "string" && v.context) ||
+    "";
+  if (longText.trim()) {
+    const trimmed = longText.split("\n").slice(0, 25).join("\n");
+    lines.push("");
+    lines.push("## Summary");
+    lines.push(trimmed);
+    if (longText.split("\n").length > 25) {
+      lines.push("… (truncated)");
+    }
+  }
+
+  // Council sims, suggested templates, etc — references the LLM may want
+  // to drill into via another simocracy_lookup_record call.
+  const refBlocks = collectKindRefs(result.kind, v);
+  for (const block of refBlocks) {
+    lines.push("");
+    lines.push(`## ${block.title}`);
+    for (const ref of block.refs) lines.push(`- ${ref}`);
+  }
+
+  // For comments — surface text + parent + attribution.
+  if (result.kind === "comment") {
+    lines.push("");
+    lines.push("## Comment text");
+    lines.push(((v.text as string) || "").trim() || "(empty)");
+    if (result.attribution) {
+      lines.push("");
+      lines.push(
+        `🐾 Posted on behalf of sim **${result.attribution.simName}** (${result.attribution.simUri})`,
+      );
+    } else {
+      lines.push("");
+      lines.push(`Posted by ${ownerLabel} (no sim attribution).`);
+    }
+    if (result.parent) {
+      lines.push("");
+      lines.push(
+        `## Parent (${result.parent.collection})\n- ${result.parent.name || "(untitled)"}\n- ${result.parent.uri}`,
+      );
+    }
+  }
+
+  // Comment subtree summary.
+  if (result.comments && result.comments.length > 0) {
+    const simCount = result.comments.filter((c) => c.simUri).length;
+    const humanCount = result.comments.length - simCount;
+    lines.push("");
+    lines.push(
+      `## Comments (${result.comments.length} total — ${humanCount} human, ${simCount} sim)`,
+    );
+    // Show up to 25 most recent comments, oldest first within that window.
+    const shown = result.comments.slice(-25);
+    for (const c of shown) {
+      lines.push(formatCommentLine(c));
+    }
+    if (result.comments.length > shown.length) {
+      lines.push(
+        `… ${result.comments.length - shown.length} earlier comment(s) omitted from this preview.`,
+      );
+    }
+  } else if (result.kind !== "comment") {
+    lines.push("");
+    lines.push("_No comments yet._");
+  }
+
+  if (alternatives.length > 0) {
+    lines.push("");
+    lines.push("## Other matches");
+    for (const a of alternatives) {
+      lines.push(`- [${a.kind}] ${a.name || "(untitled)"}  ${a.uri}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/**
+ * Per-kind structured facts — status, treasury, allocation mechanism, etc.
+ * Returned as `[label, value]` pairs so the formatter can render them as a
+ * compact key/value list. Only fields with actual values are included; absent
+ * or empty fields are omitted entirely so the output stays tight.
+ */
+function collectKindFacts(
+  kind: string,
+  v: Record<string, unknown>,
+): Array<[string, string]> {
+  const out: Array<[string, string]> = [];
+  const str = (k: string): string | undefined => {
+    const x = v[k];
+    return typeof x === "string" && x.trim() ? x : undefined;
+  };
+  const num = (k: string): number | undefined => {
+    const x = v[k];
+    return typeof x === "number" ? x : undefined;
+  };
+  const arr = <T = unknown>(k: string): T[] => {
+    const x = v[k];
+    return Array.isArray(x) ? (x as T[]) : [];
+  };
+  switch (kind) {
+    case "gathering": {
+      // Status · type · mechanism on one row — these are the at-a-glance fields.
+      const statusBits = [
+        str("status"),
+        str("gatheringType"),
+        str("allocationMechanism"),
+      ].filter(Boolean) as string[];
+      if (statusBits.length) out.push(["Status", statusBits.join(" · ")]);
+      const treasury = num("treasuryUsd");
+      if (treasury !== undefined) out.push(["Treasury", `$${treasury.toLocaleString()} USD`]);
+      const dates = str("dates");
+      if (dates) out.push(["Dates", dates]);
+      const location = str("location");
+      if (location) out.push(["Location", location]);
+      const url = str("url");
+      if (url) out.push(["URL", url]);
+      const appRoute = str("appRoute");
+      if (appRoute) out.push(["App route", appRoute]);
+      const collectionUri = str("collectionUri");
+      if (collectionUri) out.push(["Proposal collection", collectionUri]);
+      const scopeBits = [
+        str("simScope") && `sims=${str("simScope")}`,
+        str("proposalScope") && `proposals=${str("proposalScope")}`,
+        str("simSize") && `size=${str("simSize")}`,
+      ].filter(Boolean) as string[];
+      if (scopeBits.length) out.push(["Scope", scopeBits.join(", ")]);
+      const council = arr("councilSims");
+      if (council.length) out.push(["Council sims", `${council.length} — see below`]);
+      break;
+    }
+    case "proposal": {
+      const startDate = str("startDate");
+      const endDate = str("endDate");
+      if (startDate || endDate) {
+        out.push(["Dates", `${startDate || "?"} → ${endDate || "?"}`]);
+      }
+      const ws = v.workScope as Record<string, unknown> | undefined;
+      if (ws && typeof ws === "object") {
+        const scope = ws.scope || ws.expression;
+        if (typeof scope === "string" && scope.trim()) {
+          out.push(["Workscope", scope]);
+        }
+      }
+      const contribs = arr<Record<string, unknown>>("contributors");
+      if (contribs.length) {
+        const names = contribs
+          .map((c) => {
+            const ci = c.contributorIdentity;
+            if (typeof ci === "string") return ci;
+            if (ci && typeof ci === "object" && "uri" in ci) {
+              return (ci as { uri: string }).uri;
+            }
+            return null;
+          })
+          .filter((x): x is string => !!x);
+        out.push([
+          "Contributors",
+          names.length
+            ? `${contribs.length} (${names.slice(0, 3).join(", ")}${names.length > 3 ? "…" : ""})`
+            : `${contribs.length}`,
+        ]);
+      }
+      break;
+    }
+    case "decision": {
+      const mech = str("mechanism");
+      if (mech) out.push(["Mechanism", mech]);
+      const budget = num("budget");
+      if (budget !== undefined) out.push(["Budget", `$${budget.toLocaleString()} USD`]);
+      const outside = num("outsideOptionKept");
+      if (outside !== undefined) out.push(["Outside option kept", `$${outside.toLocaleString()} USD`]);
+      const allocs = arr("allocations");
+      if (allocs.length) out.push(["Allocations", `${allocs.length} proposal(s)`]);
+      const decidedAt = str("decidedAt");
+      if (decidedAt) out.push(["Decided at", decidedAt.slice(0, 19)]);
+      const gatheringUri = str("gatheringUri");
+      if (gatheringUri) out.push(["Gathering", gatheringUri]);
+      break;
+    }
+    case "sim": {
+      const spriteKind = str("spriteKind");
+      if (spriteKind) out.push(["Sprite kind", spriteKind]);
+      const created = str("createdAt");
+      if (created) out.push(["Created", created.slice(0, 10)]);
+      break;
+    }
+  }
+  return out;
 }
 
+/**
+ * Per-kind reference blocks — lists of AT-URIs the LLM might want to
+ * `simocracy_lookup_record` next (council sims, allocations breakdown,
+ * etc.). Returned as titled groups so the formatter can render each
+ * block under its own subheading.
+ */
+function collectKindRefs(
+  kind: string,
+  v: Record<string, unknown>,
+): Array<{ title: string; refs: string[] }> {
+  const out: Array<{ title: string; refs: string[] }> = [];
+  const arr = <T = unknown>(k: string): T[] =>
+    Array.isArray(v[k]) ? (v[k] as T[]) : [];
+  if (kind === "gathering") {
+    const council = arr<{ uri?: string }>("councilSims");
+    if (council.length) {
+      out.push({
+        title: "Council sims",
+        refs: council
+          .map((s) => s.uri)
+          .filter((u): u is string => !!u),
+      });
+    }
+    const tmpls = arr<{ uri?: string }>("suggestedInterviewTemplates");
+    if (tmpls.length) {
+      out.push({
+        title: "Suggested interview templates",
+        refs: tmpls.map((t) => t.uri).filter((u): u is string => !!u),
+      });
+    }
+  }
+  if (kind === "decision") {
+    const allocs = arr<Record<string, unknown>>("allocations");
+    if (allocs.length) {
+      out.push({
+        title: "Allocations",
+        refs: allocs.slice(0, 30).map((a) => {
+          const title = (a.proposalTitle as string) || "(untitled)";
+          const amount = a.amount as number | undefined;
+          const requested = a.requested as number | undefined;
+          const uri = (a.proposalUri as string) || "";
+          const amt = amount !== undefined ? `$${amount.toLocaleString()}` : "$?";
+          const req = requested !== undefined ? ` (requested $${requested.toLocaleString()})` : "";
+          return `${amt}${req}  —  ${title}${uri ? `  ${uri}` : ""}`;
+        }),
+      });
+    }
+  }
+  return out;
+}
+
+function formatCommentLine(c: ResolvedComment): string {
+  const author = c.simUri
+    ? `🐾 ${c.simName} (sim, written by ${c.authorHandle ? `@${c.authorHandle}` : c.did.slice(0, 16) + "…"})`
+    : c.authorHandle
+      ? `@${c.authorHandle}`
+      : c.did.slice(0, 16) + "…";
+  const when = (c.createdAt || "").slice(0, 19);
+  const head = `- [${when}] ${author}`;
+  const body = c.text.length > 240 ? c.text.slice(0, 237) + "…" : c.text;
+  // Indent body two spaces under the bullet so it stays visually grouped.
+  return `${head}\n  ${body.replace(/\n/g, "\n  ")}`;
+}
 
 // ---------------------------------------------------------------------------
 // Slash-command flow
@@ -1277,6 +2135,19 @@ async function runLoadFlow(
   ctx: ExtensionCommandContext,
   arg: string,
 ): Promise<void> {
+  // Defense-in-depth: if a reserved subcommand keyword somehow ends up
+  // here (e.g. dispatcher regression, exotic input that bypassed the
+  // case + zero-width normalization in the `/sim` handler), refuse to
+  // search the indexer for it. Otherwise the user sees a misleading
+  // `Searching for "login"…` followed by an indexer-fetch error.
+  const argTrimmed = arg.trim();
+  if (RESERVED_SUBCOMMANDS.has(argTrimmed.toLowerCase())) {
+    ctx.ui.notify(
+      `\`${argTrimmed}\` is a reserved subcommand. Did you mean \`/sim ${argTrimmed.toLowerCase()}\`? Run \`/sim help\` for the full list.`,
+      "error",
+    );
+    return;
+  }
   ctx.ui.notify(`Searching for "${arg}"…`, "info");
   let matches: SimMatch[] = [];
   if (arg.startsWith("at://")) {