pi-simocracy 0.6.0 → 0.6.2

package/README.md

@@ -39,6 +39,7 @@ pi install npm:pi-simocracy
 | `simocracy_chat` | Send one message to a sim and get a quoted reply, **without** changing the active session persona. Needs `OPENROUTER_API_KEY`. |
 | `simocracy_lookup_record` | Fetch a sim / proposal / gathering / decision / comment by AT-URI or fuzzy name. Returns the record + comment subtree, with sim-authored comments flagged inline (🐾) so you can tell which opinions are human and which are sim. Use this before `simocracy_post_comment` to find the right `subjectUri`. |
 | `simocracy_post_comment` | Post a comment on a record **as the loaded sim**. Writes the comment plus an `org.simocracy.history` sidecar that attributes it to the sim. Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_COMMENTS.md`](docs/SIM_AUTHORED_COMMENTS.md) for the design. |
+| `simocracy_post_proposal` | Submit a new funding proposal (`org.hypercerts.claim.activity`) **as the loaded sim**. Writes the proposal plus an `org.simocracy.history` sidecar with `type: "proposal"`. Optional itemized `budgetItems`, `workScope` tags, `contributors`, and an https `imageUri` (the default Simocracy banner is used otherwise — image upload from disk is intentionally not supported). Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_PROPOSALS.md`](docs/SIM_AUTHORED_PROPOSALS.md) for the design. |
 | `simocracy_update_sim` | Rewrite the loaded sim's constitution (`shortDescription` + `description`) and/or speaking `style` and persist to your PDS. Requires `/sim login` + sim ownership. |
 
 ---
@@ -68,6 +69,17 @@ Pi calls `simocracy_lookup_record` to find the AT-URI, then `simocracy_post_comm
 
 ---
 
+## Loaded-sim system prompt
+
+When a sim is loaded, pi injects the sim's identity, constitution, and speaking style into the system prompt every turn. On top of that, the persona prompt appends a **Simocracy navigation cheat-sheet** fetched live from [`simocracy.org/skill.md`](https://www.simocracy.org/skill.md) at sim-load time — that's where the URL patterns (`/sims/<did>/<rkey>`, `/profile/<handle>`, …), indexer endpoints, and recommended tool-routing live. simocracy.org is the single source of truth; this extension keeps no baked-in fallback. If the fetch fails (offline, simocracy.org down, route not yet deployed) the section is simply omitted — the sim still loads, it just lacks the navigation guidance until the URL becomes reachable.
+
+Override or disable:
+
+- `SIMOCRACY_SKILL_URL=…` — point at a staging URL (the route is also viewable in a browser).
+- `SIMOCRACY_SKILL_MD_DISABLED=1` — skip the fetch entirely (useful on metered connections / offline).
+
+---
+
 ## Sprite rendering
 
 Two formats supported:
@@ -82,6 +94,7 @@ In Kitty / Ghostty / WezTerm / Konsole / iTerm2 the sprite renders as a true-col
 
 - [`AGENTS.md`](AGENTS.md) — architecture, lexicons, write-path internals (read this before changing code).
 - [`docs/SIM_AUTHORED_COMMENTS.md`](docs/SIM_AUTHORED_COMMENTS.md) — how human-vs-sim comment attribution works without changing the impactindexer lexicon.
+- [`docs/SIM_AUTHORED_PROPOSALS.md`](docs/SIM_AUTHORED_PROPOSALS.md) — same pattern, applied to `org.hypercerts.claim.activity` proposals.
 - [Simocracy](https://simocracy.org) · [pi](https://github.com/mariozechner/pi-coding-agent)
 
 MIT — see [LICENSE](LICENSE).

package/docs/SIM_AUTHORED_PROPOSALS.md

@@ -0,0 +1,198 @@
+# Sim-authored proposals
+
+How pi-simocracy attributes a funding proposal to a sim *without*
+extending the `org.hypercerts.claim.activity` lexicon — and what
+[simocracy-v2](https://github.com/GainForest/simocracy-v2) needs to
+do to render the attribution. Same pattern as
+[sim-authored comments](./SIM_AUTHORED_COMMENTS.md), different
+subject collection.
+
+---
+
+## TL;DR
+
+When pi submits a proposal on behalf of a loaded sim, it writes
+**two** records to the user's PDS:
+
+1. **`org.hypercerts.claim.activity`** — the proposal itself, in the
+   exact shape simocracy.org's `ProposalFormDialog` already writes
+   today (`title`, `shortDescription`, optional `description` /
+   `workScope` / `contributors` / `image`, `createdAt`). Old readers
+   (Hyperindexer, the existing webapp) see this as a regular
+   user-authored proposal — graceful degradation.
+2. **`org.simocracy.history`** — sidecar record with `type:
+   "proposal"`, `subjectUri` pointing at the proposal we just wrote,
+   `simUris[]` / `simNames[]` declaring which sim spoke. New `type`
+   value, but the lexicon's `type` field is free-form string and the
+   indexer already accepts new event types as they appear.
+
+Renderers that understand the join (simocracy.org, when the planned
+change lands) will display a sim badge on the proposal card;
+renderers that don't keep showing it as a regular user proposal.
+**Zero hypercerts lexicon changes. Zero new Simocracy lexicons.**
+
+---
+
+## Why no lexicon change
+
+The `org.hypercerts.*` namespace is owned by the GainForest
+hyperindexer project, not Simocracy — extending
+`org.hypercerts.claim.activity` with a `sim` StrongRef field would
+couple two independent release cycles together for one cross-app
+feature, and the same argument made for comments
+([`SIM_AUTHORED_COMMENTS.md`](./SIM_AUTHORED_COMMENTS.md)) applies
+verbatim here.
+
+The `org.simocracy.history` lexicon already has every field we need:
+
+| Field              | Used for sim-authored proposals                              |
+|--------------------|--------------------------------------------------------------|
+| `type`             | `"proposal"` (new value — appended like other event types)   |
+| `actorDid`         | The human who submitted on the sim's behalf                  |
+| `simNames[]`       | Display name(s) of the sim(s) credited as author             |
+| `simUris[]`        | AT-URI(s) of the sim(s) — the sim-attribution key            |
+| `subjectUri`       | AT-URI of the proposal record this attribution applies to    |
+| `subjectCollection`| `"org.hypercerts.claim.activity"`                            |
+| `subjectName`      | Proposal title (denormalized for the timeline)               |
+| `proposalTitle`    | Same as `subjectName` — kept parallel to comment sidecars    |
+| `content`          | Denormalized description (so the indexer doesn't have to join across PDSs to display the timeline) |
+| `createdAt`        | ISO timestamp                                                |
+
+Use it as-is.
+
+---
+
+## Write path (pi-simocracy)
+
+Implemented by `simocracy_post_proposal` in `src/index.ts`:
+
+```ts
+// 1. The proposal — same shape as ProposalFormDialog writes today.
+const proposal = await createProposal({
+  agent, did,
+  title,
+  shortDescription,
+  description: finalDescription,   // user body + appended budget block, if any
+  workScope,
+  contributors: contributors.map((c) => ({ contributorIdentity: c })),
+  image: { $type: "org.hypercerts.defs#uri", uri: imageUri ?? DEFAULT_BANNER },
+});
+
+// 2. The sim-attribution sidecar — required, since attribution is the whole
+//    point of this tool.
+await createProposalHistory({
+  agent, did,
+  proposalUri:   proposal.uri,
+  proposalTitle: title,
+  simUri:        loadedSim.uri,
+  simName:       loadedSim.name,
+  content:       finalDescription || shortDescription,
+});
+```
+
+Both writes go to the **user's** PDS via their OAuth session — same
+auth path that already powers `simocracy_post_comment` and
+`simocracy_update_sim`. The write is gated on `/sim login` plus sim
+ownership (the sim must live in the signed-in DID's repo) — the
+sidecar uses `assertRepoOwnsSimUri` as defense-in-depth, identical
+to the comment path.
+
+If the sidecar write fails after the proposal succeeds, **the
+proposal is not rolled back** — it just shows up unattributed until
+the user retries. We don't roll back, because rolling back leaves an
+orphaned tombstone in the user's repo that's harder to reason about
+than a missing badge. The tool surfaces a `sidecarWarning` in the
+result so the LLM can decide whether to retry.
+
+### What we deliberately don't do
+
+- **Image upload from disk.** The webapp uploads to `/api/upload-blob`;
+  pi-simocracy has no equivalent and we deliberately stay
+  read-mostly on blobs. The tool accepts an https `imageUri` only,
+  with a default that mirrors the webapp's banner fallback.
+- **Adding the proposal to a floor / collection.** That's a separate
+  `org.hypercerts.claim.collection` write the webapp does via
+  `/api/ftc-sf/add-to-collection`. Out of scope for this tool; a
+  follow-up tool can chain it after the fact.
+- **Editing existing proposals.** Create-only for now.
+
+---
+
+## Read path (proposed simocracy-v2 changes)
+
+Mirrors the comment renderer change in shape, applied to the
+proposal list / detail views.
+
+### 1. Proposal list query — pull history records in parallel
+
+After fetching the proposals for a floor / collection, fetch all
+`org.simocracy.history` records (capped, like notifications does)
+and build a `Map<proposalUri, HistoryRecord>` keyed on `subjectUri`.
+Filter to `type === "proposal"` and `subjectCollection ===
+"org.hypercerts.claim.activity"`. Attach `simUri`, `simName`, and a
+resolved `simAvatarUrl` to each proposal in the response that has a
+match. Sim avatar resolution can reuse `fetchAllSimsWithMeta()` —
+no extra round-trips per proposal.
+
+### 2. Extend the proposal type
+
+```ts
+export interface ProposalRecord {
+  // …existing fields…
+  simUri?: string
+  simName?: string
+  simAvatarUrl?: string
+}
+```
+
+No change to `ProposalFormDialog` — that path stays for human
+authors. Sim-authored proposals come from the CLI today, and a
+future "submit as sim" button in the modal would bundle both writes
+the same way pi-simocracy does.
+
+### 3. Proposal card — sim badge
+
+In the proposal card component, when `proposal.simUri` is set:
+
+- Replace the author avatar with the sim's sprite (32×32 walk-1 frame).
+- Render the byline as `🐾 {simName} · drafted by @{userHandle}` so
+  attribution stays unambiguous (the sim "drafted" it; the human
+  submitted and owns the record).
+- Add a `[sim]` mono-uppercase badge alongside the existing meta
+  pills.
+- Link the sim name to `/sims/{did}/{rkey}` via the existing slug
+  resolver.
+
+Proposals without `simUri` keep rendering exactly as today — no
+regression for human-authored proposals.
+
+---
+
+## Querying sim-authored proposals
+
+For "show me everything my sim has proposed":
+
+```ts
+const histories = await fetchHistory()  // existing helper
+const mySimProposals = histories.filter(h =>
+  h.event.type === "proposal" &&
+  h.event.simUris?.includes(mySimUri)
+)
+```
+
+Each result has `subjectUri` (the proposal URI) and `content`
+(denormalized description). Resolve the proposal URI for the full
+record. Same query shape the notifications system already uses for
+chat / hearing / sprocess events — no new indexer queries needed.
+
+---
+
+## Status
+
+- ✅ Implemented in pi-simocracy `simocracy_post_proposal` (this repo)
+- 🟡 Renderer changes pending in simocracy-v2
+- 🟢 Lexicons unchanged — both repos can ship the change independently
+
+The proposal + history pair is being written today. As soon as
+simocracy-v2 lands the renderer change, every existing pi-authored
+sim proposal retro-actively gets the sim badge — no migration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simocracy",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Pi extension: load a Simocracy sim into your chat — see its pixel-art sprite render inline in the terminal and roleplay with it.",
   "type": "module",
   "author": "David Dao <david@gainforest.earth> (https://github.com/daviddao)",

package/src/index.ts

@@ -54,6 +54,13 @@
  *                             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
@@ -88,6 +95,7 @@ import {
   fetchAgentsForSim,
   fetchStyleForSim,
   fetchBlob,
+  fetchSkillMd,
   resolveHandle,
   parseAtUri,
   type AgentsRecord,
@@ -120,6 +128,8 @@ import {
   createAgents,
   createComment,
   createCommentHistory,
+  createProposal,
+  createProposalHistory,
   createStyle,
   findRkeyForSim,
   getAuthenticatedAgent,
@@ -478,6 +488,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;
@@ -487,7 +517,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}".` };
@@ -496,12 +534,14 @@ async function loadSimByName(query: string): Promise<{
 }
 
 async function hydrateLoadedSim(match: SimMatch): Promise<LoadedSim> {
-  // Fetch agents (constitution), style, sprite ANSI + handle in parallel.
-  const [agents, style, sprite, handle] = await Promise.all([
+  // Fetch agents (constitution), style, sprite ANSI, handle, and the
+  // simocracy.org navigation cheat-sheet in parallel.
+  const [agents, style, sprite, handle, skill] = await Promise.all([
     fetchAgentsForSim(match.uri).catch(() => null) as Promise<AgentsRecord | null>,
     fetchStyleForSim(match.uri).catch(() => null) as Promise<StyleRecord | null>,
     renderSprite(match).catch(() => null),
     resolveHandle(match.did).catch(() => null),
+    fetchSkillMd(),
   ]);
 
   return {
@@ -529,6 +569,8 @@ async function hydrateLoadedSim(match: SimMatch): Promise<LoadedSim> {
     shortDescription: agents?.shortDescription,
     description: agents?.description,
     style: style?.description,
+    skillMd: skill.text,
+    skillMdError: skill.text ? undefined : skill.error,
   };
 }
 
@@ -638,6 +680,115 @@ const PostCommentToolParams = Type.Object({
   }),
 });
 
+/**
+ * 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:
@@ -809,8 +960,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" +
@@ -837,27 +998,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;
@@ -871,7 +1033,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;
@@ -1310,6 +1472,162 @@ export default async function simocracy(pi: ExtensionAPI) {
     },
   });
 
+  // -------------------------------------------------------------------------
+  // 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
   //
@@ -1822,6 +2140,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://")) {

package/src/persona.ts

@@ -7,6 +7,8 @@
  * normal `/sim` chat and with the `simocracy_chat` tool.
  */
 
+import { getSimocracySkillUrl } from "./simocracy.ts";
+
 export interface LoadedSim {
   uri: string;
   did: string;
@@ -55,6 +57,16 @@ export interface LoadedSim {
     /** Native PNG height in pixels. */
     heightPx: number;
   };
+  /** Fetched contents of `https://www.simocracy.org/skill.md` at
+   *  sim-load time, when the fetch succeeded. Appended verbatim to
+   *  the persona prompt by `buildSimPrompt`. Kept on the sim so a
+   *  re-render or a future `simocracy_chat` call uses the same
+   *  content the original load used. */
+  skillMd?: string;
+  /** Reason the skill.md fetch did not run / failed, when relevant.
+   *  Stored only for diagnostics — never injected into the persona
+   *  prompt. Surface optionally via `/sim status`. */
+  skillMdError?: string;
 }
 
 /**
@@ -86,6 +98,20 @@ export function buildSimPrompt(sim: LoadedSim): string {
     lines.push(`## ${sim.name}'s speaking style`);
     lines.push(sim.style);
   }
+  if (sim.skillMd) {
+    lines.push(``);
+    lines.push(`## Simocracy navigation cheat-sheet`);
+    lines.push(
+      `Your specific simocracy.org page: https://www.simocracy.org/sims/${sim.did}/${sim.rkey}` +
+        (sim.handle ? `\nThe owner's profile: https://www.simocracy.org/profile/${sim.handle}` : ""),
+    );
+    lines.push(``);
+    lines.push(
+      `The block below is fetched from ${getSimocracySkillUrl()} on every sim-load and is the canonical reference for URL patterns, indexer endpoints, and common navigation workflows. Treat it as authoritative; when the user asks about you, your gatherings, your proposals, or what other sims have been saying, follow this guide.`,
+    );
+    lines.push(``);
+    lines.push(sim.skillMd);
+  }
   lines.push(``);
   lines.push(
     `When the user asks you to use any of pi's tools (read, edit, bash, etc.), you should still use them — you're ${sim.name} *with access to a developer's terminal*. Just narrate tool use the way ${sim.name} would talk about it.`,

package/src/simocracy.ts

@@ -345,3 +345,48 @@ export async function resolveHandle(did: string): Promise<string | null> {
 }
 
 export const SIMOCRACY_INDEXER_URL = DEFAULT_INDEXER_URL;
+
+const SIMOCRACY_SKILL_URL =
+  process.env.SIMOCRACY_SKILL_URL ?? "https://www.simocracy.org/skill.md";
+
+const SKILL_MD_FETCH_TIMEOUT_MS = 4000;
+const SKILL_MD_MAX_BYTES = 64 * 1024;
+
+/**
+ * Fetch the navigation cheat-sheet served at `simocracy.org/skill.md`.
+ * Never throws — returns either `{ text }` on success or `{ error }` on
+ * failure / disablement so the caller can record the diagnostic and
+ * fall through to the pre-change behaviour (no navigation guidance).
+ */
+export async function fetchSkillMd(): Promise<{ text?: string; error?: string }> {
+  if (process.env.SIMOCRACY_SKILL_MD_DISABLED === "1") {
+    return { error: "disabled by SIMOCRACY_SKILL_MD_DISABLED=1" };
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), SKILL_MD_FETCH_TIMEOUT_MS);
+  try {
+    const res = await fetch(SIMOCRACY_SKILL_URL, {
+      signal: controller.signal,
+      headers: { Accept: "text/markdown, text/plain;q=0.5" },
+    });
+    if (!res.ok) {
+      return { error: `${res.status} ${res.statusText}` };
+    }
+    const buf = Buffer.from(await res.arrayBuffer());
+    const trimmed =
+      buf.byteLength > SKILL_MD_MAX_BYTES
+        ? buf.slice(0, SKILL_MD_MAX_BYTES).toString("utf8") +
+          `\n\n<!-- truncated at ${SKILL_MD_MAX_BYTES} bytes -->`
+        : buf.toString("utf8");
+    return { text: trimmed };
+  } catch (err) {
+    return { error: (err as Error).message };
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+/** Exported for the persona prompt to mention the URL by name. */
+export function getSimocracySkillUrl(): string {
+  return SIMOCRACY_SKILL_URL;
+}

package/src/writes.ts

@@ -129,6 +129,7 @@ const COLLECTION_AGENTS = "org.simocracy.agents";
 const COLLECTION_STYLE = "org.simocracy.style";
 const COLLECTION_COMMENT = "org.impactindexer.review.comment";
 const COLLECTION_HISTORY = "org.simocracy.history";
+const COLLECTION_PROPOSAL = "org.hypercerts.claim.activity";
 
 /**
  * Defense-in-depth: every write helper below verifies the target
@@ -390,6 +391,128 @@ export async function createCommentHistory(opts: {
   };
 }
 
+/**
+ * POST `org.hypercerts.claim.activity` (a funding proposal).
+ *
+ * Matches the wire shape simocracy.org's `ProposalFormDialog` writes
+ * today (`title`, `shortDescription`, optional `description` /
+ * `workScope` / `contributors` / `image`, `createdAt`), so proposals
+ * authored from pi render identically in the webapp.
+ *
+ * No sim-attribution lives in this record. Sim attribution is a
+ * sidecar `org.simocracy.history` written by `createProposalHistory`
+ * below — same pattern as comments, see
+ * `docs/SIM_AUTHORED_PROPOSALS.md` for the design rationale.
+ *
+ * The proposal itself is the *user's*, not the sim's, so this writer
+ * does NOT call `assertRepoOwnsSimUri` — the only precondition is
+ * that the user is signed in (enforced at the tool entry point via
+ * `assertCanWriteToSim`, which also requires a loaded sim because
+ * attribution requires one).
+ */
+export async function createProposal(opts: {
+  agent: Agent;
+  did: string;
+  title: string;
+  shortDescription: string;
+  description?: string;
+  workScope?: string;
+  contributors?: Array<{ contributorIdentity: string }>;
+  image?: { $type: "org.hypercerts.defs#uri"; uri: string };
+}): Promise<{ uri: string; cid: string; rkey: string }> {
+  const title = opts.title.trim();
+  if (!title) throw new Error("Proposal title is required.");
+  const shortDescription = opts.shortDescription.trim();
+  if (!shortDescription)
+    throw new Error("Proposal shortDescription is required.");
+  const record: Record<string, unknown> = {
+    $type: COLLECTION_PROPOSAL,
+    title: title.slice(0, 256),
+    shortDescription: shortDescription.slice(0, 300),
+    createdAt: new Date().toISOString(),
+  };
+  if (opts.description !== undefined) {
+    const body = opts.description.trim();
+    if (body) record.description = body;
+  }
+  if (opts.workScope !== undefined) {
+    const ws = opts.workScope.trim();
+    if (ws) record.workScope = ws;
+  }
+  if (opts.contributors && opts.contributors.length > 0) {
+    record.contributors = opts.contributors;
+  }
+  if (opts.image) record.image = opts.image;
+  const res = await opts.agent.com.atproto.repo.createRecord({
+    repo: opts.did,
+    collection: COLLECTION_PROPOSAL,
+    record,
+  });
+  return {
+    uri: res.data.uri,
+    cid: res.data.cid,
+    rkey: res.data.uri.split("/").pop() ?? "",
+  };
+}
+
+/**
+ * Sim-attribution sidecar for a proposal.
+ *
+ * Mirrors `createCommentHistory` exactly — same `org.simocracy.history`
+ * lexicon, same join key shape, just `type: "proposal"` and
+ * `subjectCollection: "org.hypercerts.claim.activity"`. The lexicon's
+ * `type` field is free-form string; the webapp doesn't filter
+ * histories by `type === "proposal"` today, but adding a new value is
+ * fine (history.json already documents that new event types are
+ * appended over time).
+ *
+ * Writes to the *user's* own PDS, not a shared facilitator repo —
+ * the attribution is an event the user triggered and naturally
+ * belongs in their history.
+ */
+export async function createProposalHistory(opts: {
+  agent: Agent;
+  did: string;
+  proposalUri: string;
+  proposalTitle: string;
+  simUri: string;
+  simName: string;
+  /** Plain-text description, denormalized for the timeline (truncated to ~5000 chars). */
+  content?: string;
+}): Promise<{ uri: string; cid: string; rkey: string }> {
+  // Defense-in-depth: the sim must live in the same repo we're writing to.
+  // The proposal record itself isn't sim-owned, but the history sidecar
+  // *claims attribution to* a sim — only the sim's owner can make that claim.
+  assertRepoOwnsSimUri(opts.did, opts.simUri);
+  const title = opts.proposalTitle.trim();
+  const record: Record<string, unknown> = {
+    $type: COLLECTION_HISTORY,
+    type: "proposal",
+    actorDid: opts.did,
+    simNames: [opts.simName].slice(0, 10),
+    simUris: [opts.simUri].slice(0, 10),
+    subjectUri: opts.proposalUri,
+    subjectCollection: COLLECTION_PROPOSAL,
+    subjectName: title.slice(0, 500),
+    proposalTitle: title.slice(0, 500),
+    createdAt: new Date().toISOString(),
+  };
+  if (opts.content) {
+    const trimmed = opts.content.trim();
+    if (trimmed) record.content = trimmed.slice(0, 5000);
+  }
+  const res = await opts.agent.com.atproto.repo.createRecord({
+    repo: opts.did,
+    collection: COLLECTION_HISTORY,
+    record,
+  });
+  return {
+    uri: res.data.uri,
+    cid: res.data.cid,
+    rkey: res.data.uri.split("/").pop() ?? "",
+  };
+}
+
 /**
  * Best-effort lookup of an existing rkey by listing the collection
  * and finding the record whose `sim.uri` matches. Used by the Apply