pi-simocracy 0.6.1 → 0.7.0

package/README.md

@@ -39,7 +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_post_proposal` | Submit a new funding proposal (`org.hypercerts.claim.activity`) **as the loaded sim**. Writes three records to the user's PDS: the proposal itself, an `org.simocracy.proposalContext` sidecar binding it to a parent gathering or FtC SF floor (required for visibility on `/proposals`), and an `org.simocracy.history` sidecar with `type: "proposal"`. You must pass exactly one of `gatheringUri` (an AT-URI to an `org.simocracy.gathering` — use `simocracy_lookup_record` to resolve a name) or `ftcSfFloor` (1–14). 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. |
 
 ---
@@ -69,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:

package/docs/SIM_AUTHORED_PROPOSALS.md

@@ -12,7 +12,7 @@ subject collection.
 ## TL;DR
 
 When pi submits a proposal on behalf of a loaded sim, it writes
-**two** records to the user's PDS:
+**three** records to the user's PDS:
 
 1. **`org.hypercerts.claim.activity`** — the proposal itself, in the
    exact shape simocracy.org's `ProposalFormDialog` already writes
@@ -20,16 +20,27 @@ When pi submits a proposal on behalf of a loaded sim, it writes
    `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:
+2. **`org.simocracy.proposalContext`** — sidecar binding the proposal
+   to its parent gathering (StrongRef to `org.simocracy.gathering`)
+   or to a Frontier Tower SF floor (`floorNumber` integer). Required
+   for visibility: post-Phase-5, simocracy.org's `/proposals` feed
+   sources its seed set from `org.simocracy.proposalContext` records,
+   not from a hashtag scan, so a proposal without this sidecar is
+   invisible. Lives in the proposer's PDS so the resolver's tier-1
+   (proposer) > tier-2 (facilitator backfill) precedence works.
+3. **`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 understand the history join (simocracy.org, since
+the planned change landed) 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.**
+**Zero hypercerts lexicon changes.** One new Simocracy lexicon was
+added for proposalContext (see `simocracy-v2/lexicons/org/simocracy/proposalContext.json`)
+so every Simocracy-bound proposal carries a typed back-pointer to
+its parent.
 
 ---
 
@@ -67,6 +78,17 @@ Use it as-is.
 Implemented by `simocracy_post_proposal` in `src/index.ts`:
 
 ```ts
+// Tool input — exactly one of gatheringUri / ftcSfFloor must be set.
+// gatheringUri is fetched ahead of any writes so a typo or unreachable
+// PDS surfaces *before* an orphaned proposal lands in the user's repo.
+const gatheringRef =
+  gatheringUri
+    ? await getRecordRefFromPds(parsed.did, "org.simocracy.gathering", parsed.rkey)
+    : undefined;
+const resolvedContext = gatheringRef
+  ? { kind: "gathering" as const, uri: gatheringRef.uri, cid: gatheringRef.cid }
+  : { kind: "ftc-sf" as const, floorNumber: ftcSfFloor };
+
 // 1. The proposal — same shape as ProposalFormDialog writes today.
 const proposal = await createProposal({
   agent, did,
@@ -78,7 +100,17 @@ const proposal = await createProposal({
   image: { $type: "org.hypercerts.defs#uri", uri: imageUri ?? DEFAULT_BANNER },
 });
 
-// 2. The sim-attribution sidecar — required, since attribution is the whole
+// 2. The parent-context sidecar — required for visibility on /proposals.
+//    A failure here doesn't roll back the proposal but is surfaced as
+//    a `contextSidecarWarning` so the LLM can retry just the sidecar.
+await createProposalContext({
+  agent, did,
+  proposalUri: proposal.uri,
+  proposalCid: proposal.cid,
+  context: resolvedContext,
+});
+
+// 3. The sim-attribution sidecar — required, since attribution is the whole
 //    point of this tool.
 await createProposalHistory({
   agent, did,
@@ -190,9 +222,12 @@ 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.
+- ✅ Renderer changes shipped in simocracy-v2
+- ✅ `org.simocracy.proposalContext` lexicon shipped (1 new Simocracy lexicon, 0 hypercerts changes)
+
+The proposal + proposalContext + history triple is being written
+today. Every pi-authored proposal carries both the sim badge
+(history sidecar) and the parent-gathering binding
+(proposalContext sidecar), so it surfaces correctly on
+`simocracy.org/proposals` and under its parent gathering page — no
+migration, no backfill needed for new submissions.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-simocracy",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "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

@@ -95,8 +95,10 @@ import {
   fetchAgentsForSim,
   fetchStyleForSim,
   fetchBlob,
+  fetchSkillMd,
   resolveHandle,
   parseAtUri,
+  getRecordRefFromPds,
   type AgentsRecord,
   type SimMatch,
   type StyleRecord,
@@ -128,6 +130,7 @@ import {
   createComment,
   createCommentHistory,
   createProposal,
+  createProposalContext,
   createProposalHistory,
   createStyle,
   findRkeyForSim,
@@ -136,6 +139,7 @@ import {
   NotSimOwnerError,
   updateAgents,
   updateStyle,
+  type ProposalContextTarget,
 } from "./writes.ts";
 
 // ---------------------------------------------------------------------------
@@ -533,12 +537,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 {
@@ -566,6 +572,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,
   };
 }
 
@@ -782,6 +790,25 @@ const PostProposalToolParams = Type.Object({
         "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.",
     }),
   ),
+  // Parent-context binding — effectively required for the proposal to
+  // be discoverable on simocracy.org (post-Phase-5 the read paths only
+  // surface proposals that have a sidecar). Exactly one of the two must
+  // be passed; the execute handler enforces that.
+  gatheringUri: Type.Optional(
+    Type.String({
+      description:
+        "AT-URI of the parent gathering this proposal belongs to (an `org.simocracy.gathering` record). Pass exactly one of `gatheringUri` or `ftcSfFloor`. Get the URI by calling `simocracy_lookup_record` first — the LLM should resolve a fuzzy gathering name to a real AT-URI before submitting. Without a parent context, the proposal will be invisible on simocracy.org's `/proposals` feed.",
+      pattern: "^at://[^/]+/org\\.simocracy\\.gathering/[^/]+$",
+    }),
+  ),
+  ftcSfFloor: Type.Optional(
+    Type.Integer({
+      description:
+        "Frontier Tower SF floor number this proposal belongs to (1–14, with the static configuration in simocracy-v2's `lib/ftc-sf-data.ts`). Pass exactly one of `gatheringUri` or `ftcSfFloor`. Use this for proposals submitted to the Frontier Tower SF agentic funding experiment instead of a regular gathering.",
+      minimum: 1,
+      maximum: 14,
+    }),
+  ),
 });
 
 const LookupRecordToolParams = Type.Object({
@@ -1487,11 +1514,21 @@ export default async function simocracy(pi: ExtensionAPI) {
     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.",
+      "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 THREE records to the user's PDS: (1) the proposal itself, (2) an `org.simocracy.proposalContext` sidecar binding the proposal to its parent gathering / FtC SF floor (required for the proposal to appear in simocracy.org's `/proposals` feed), and (3) 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\". You MUST pass exactly one of `gatheringUri` (to bind the proposal to a gathering) or `ftcSfFloor` (to bind to a Frontier Tower SF floor); call `simocracy_lookup_record` first to resolve a gathering name to its AT-URI. 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 },
+      {
+        title,
+        shortDescription,
+        description,
+        workScope,
+        contributors,
+        budgetItems,
+        imageUri,
+        gatheringUri,
+        ftcSfFloor,
+      },
     ) {
       if (!loadedSim) {
         throw new Error(
@@ -1515,6 +1552,64 @@ export default async function simocracy(pi: ExtensionAPI) {
         throw new Error(`ATProto auth failed: ${(err as Error).message}`);
       }
 
+      // Parent-context validation — exactly one of gatheringUri / ftcSfFloor.
+      // Without one, the proposal is invisible on /proposals, so we require
+      // it up-front rather than letting the LLM ship orphaned proposals.
+      const hasGathering = gatheringUri !== undefined;
+      const hasFloor = ftcSfFloor !== undefined;
+      if (hasGathering && hasFloor) {
+        throw new Error(
+          "Pass exactly one of `gatheringUri` (for a gathering) or `ftcSfFloor` (for FtC SF), not both.",
+        );
+      }
+      if (!hasGathering && !hasFloor) {
+        throw new Error(
+          "A parent context is required: pass `gatheringUri` (an AT-URI to an `org.simocracy.gathering` — use `simocracy_lookup_record` to resolve a name) or `ftcSfFloor` (a Frontier Tower SF floor number 1–14). Without one, the proposal will be invisible on simocracy.org's /proposals feed.",
+        );
+      }
+
+      // Resolve gathering URI → StrongRef now (before any writes) so a
+      // typo or unreachable PDS surfaces *before* we put a half-orphaned
+      // proposal record into the user's repo.
+      let resolvedContext: ProposalContextTarget;
+      if (hasGathering) {
+        let gatheringDid: string;
+        let gatheringRkey: string;
+        try {
+          const parsed = parseAtUri(gatheringUri!);
+          if (parsed.collection !== "org.simocracy.gathering") {
+            throw new Error(
+              `gatheringUri must point at an org.simocracy.gathering record (got ${parsed.collection}).`,
+            );
+          }
+          gatheringDid = parsed.did;
+          gatheringRkey = parsed.rkey;
+        } catch (err) {
+          throw new Error(
+            `gatheringUri is not a valid AT-URI: ${(err as Error).message}`,
+          );
+        }
+        let gatheringRef: { uri: string; cid: string };
+        try {
+          gatheringRef = await getRecordRefFromPds(
+            gatheringDid,
+            "org.simocracy.gathering",
+            gatheringRkey,
+          );
+        } catch (err) {
+          throw new Error(
+            `Couldn't fetch gathering record from owner's PDS — verify the URI is correct and the gathering still exists. ${(err as Error).message}`,
+          );
+        }
+        resolvedContext = {
+          kind: "gathering",
+          uri: gatheringRef.uri,
+          cid: gatheringRef.cid,
+        };
+      } else {
+        resolvedContext = { kind: "ftc-sf", floorNumber: ftcSfFloor! };
+      }
+
       // 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
@@ -1568,6 +1663,26 @@ export default async function simocracy(pi: ExtensionAPI) {
         throw new Error(`Proposal write failed: ${(err as Error).message}`);
       }
 
+      // Parent-context sidecar — written FIRST after the proposal so a
+      // visibility failure is loud and immediate. If this fails the
+      // proposal is already on the user's PDS but won't surface on
+      // /proposals; we surface a warning so the LLM can retry just this
+      // sidecar instead of re-submitting the whole proposal.
+      let contextSidecarUri: string | undefined;
+      let contextSidecarWarning: string | undefined;
+      try {
+        const ctxWrite = await createProposalContext({
+          agent: pdsAgent,
+          did: auth.did,
+          proposalUri: proposal.uri,
+          proposalCid: proposal.cid,
+          context: resolvedContext,
+        });
+        contextSidecarUri = ctxWrite.uri;
+      } catch (err) {
+        contextSidecarWarning = `Parent-context sidecar failed: ${(err as Error).message}`;
+      }
+
       let sidecarUri: string | undefined;
       let sidecarWarning: string | undefined;
       try {
@@ -1588,12 +1703,25 @@ export default async function simocracy(pi: ExtensionAPI) {
         sidecarWarning = `Sim-attribution sidecar failed: ${(err as Error).message}`;
       }
 
+      const parentLabel =
+        resolvedContext.kind === "gathering"
+          ? `gathering ${resolvedContext.uri}`
+          : `FtC SF floor ${resolvedContext.floorNumber}`;
       const lines = [
         `Submitted proposal as ${loadedSim.name}${loadedSim.handle ? ` (@${loadedSim.handle})` : ""}:`,
         `  title:        ${title}`,
         `  proposal URI: ${proposal.uri}`,
+        `  parent:       ${parentLabel}`,
         `  image:        ${imageRef.uri}`,
       ];
+      if (contextSidecarUri) {
+        lines.push(`  context:      ${contextSidecarUri}  (org.simocracy.proposalContext sidecar)`);
+      } else if (contextSidecarWarning) {
+        lines.push(`  WARNING:      ${contextSidecarWarning}`);
+        lines.push(
+          `                The proposal is posted but will be invisible on /proposals until a proposalContext sidecar is written.`,
+        );
+      }
       if (sidecarUri) {
         lines.push(`  attribution:  ${sidecarUri}  (org.simocracy.history sidecar)`);
       } else if (sidecarWarning) {
@@ -1616,6 +1744,12 @@ export default async function simocracy(pi: ExtensionAPI) {
           budgetItemCount: budgetItems?.length ?? 0,
           simUri: loadedSim.uri,
           simName: loadedSim.name,
+          parent:
+            resolvedContext.kind === "gathering"
+              ? { kind: "gathering", uri: resolvedContext.uri, cid: resolvedContext.cid }
+              : { kind: "ftc-sf", floorNumber: resolvedContext.floorNumber },
+          contextSidecarUri,
+          contextSidecarWarning,
           sidecarUri,
           sidecarWarning,
         },

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

@@ -252,6 +252,34 @@ export async function getRecordFromPds<T>(did: string, collection: string, rkey:
   return json.value as T;
 }
 
+/**
+ * Read a record's StrongRef ({uri, cid}) directly from the owner's PDS.
+ *
+ * Same wire call as `getRecordFromPds` but returns the metadata needed to
+ * reference the record from another record (e.g. an `org.simocracy.proposalContext`
+ * sidecar's `subject` or `context.gathering` field). The body is intentionally
+ * dropped — callers that need it should use `getRecordFromPds` instead.
+ */
+export async function getRecordRefFromPds(
+  did: string,
+  collection: string,
+  rkey: string,
+): Promise<{ uri: string; cid: string }> {
+  const pds = await resolvePds(did);
+  const url =
+    `${pds.replace(/\/+$/, "")}/xrpc/com.atproto.repo.getRecord` +
+    `?repo=${encodeURIComponent(did)}` +
+    `&collection=${encodeURIComponent(collection)}` +
+    `&rkey=${encodeURIComponent(rkey)}`;
+  const res = await fetch(url);
+  if (!res.ok) throw new Error(`PDS getRecord failed: ${res.status}`);
+  const json = (await res.json()) as { uri?: string; cid?: string };
+  if (!json.uri || !json.cid) {
+    throw new Error(`PDS getRecord returned no uri/cid: ${url}`);
+  }
+  return { uri: json.uri, cid: json.cid };
+}
+
 /** List records by paging com.atproto.repo.listRecords on a PDS. */
 export async function listRecordsFromPds<T>(did: string, collection: string): Promise<Array<{ uri: string; cid: string; value: T }>> {
   const pds = await resolvePds(did);
@@ -345,3 +373,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

@@ -130,6 +130,7 @@ 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";
+const COLLECTION_PROPOSAL_CONTEXT = "org.simocracy.proposalContext";
 
 /**
  * Defense-in-depth: every write helper below verifies the target
@@ -455,6 +456,86 @@ export async function createProposal(opts: {
   };
 }
 
+/**
+ * Discriminated parent target for an `org.simocracy.proposalContext`
+ * sidecar. Mirrors the lexicon's `context` union (#gatheringContext
+ * vs #ftcSfContext); see `simocracy-v2/lexicons/org/simocracy/proposalContext.json`.
+ */
+export type ProposalContextTarget =
+  | { kind: "gathering"; uri: string; cid: string }
+  | { kind: "ftc-sf"; floorNumber: number };
+
+/**
+ * POST `org.simocracy.proposalContext` (parent-context sidecar).
+ *
+ * Binds a proposal to its parent container — either an
+ * `org.simocracy.gathering` record (via StrongRef) or a static FtC SF
+ * floor number. Without this sidecar, simocracy.org's read paths
+ * (post-Phase-5) won't surface the proposal on `/proposals` or under
+ * the gathering / floor it belongs to. The sidecar is therefore
+ * effectively required for any proposal submitted via this tool.
+ *
+ * Same trust model as `org.simocracy.history` — lives in the
+ * proposer's own PDS so the resolver's tier-1 (proposer-PDS) >
+ * tier-2 (facilitator-PDS) precedence rule lets a backfill record
+ * be silently superseded if the proposer ever re-saves.
+ *
+ * No sim-ownership precondition: a proposal isn't sim-owned, and
+ * the sidecar references the proposal + parent gathering, not the
+ * sim. The OAuth precondition ($DID matches signed-in DID and the
+ * agent is authenticated) is enforced upstream by
+ * `assertCanWriteToSim` at the tool entry point.
+ */
+export async function createProposalContext(opts: {
+  agent: Agent;
+  did: string;
+  proposalUri: string;
+  proposalCid: string;
+  context: ProposalContextTarget;
+}): Promise<{ uri: string; cid: string; rkey: string }> {
+  let context: Record<string, unknown>;
+  if (opts.context.kind === "gathering") {
+    if (!opts.context.uri || !opts.context.cid) {
+      throw new Error(
+        "Gathering parent context requires both uri and cid (a full StrongRef).",
+      );
+    }
+    context = {
+      $type: `${COLLECTION_PROPOSAL_CONTEXT}#gatheringContext`,
+      gathering: { uri: opts.context.uri, cid: opts.context.cid },
+    };
+  } else {
+    if (
+      !Number.isInteger(opts.context.floorNumber) ||
+      opts.context.floorNumber < 1
+    ) {
+      throw new Error(
+        `FtC SF floor number must be a positive integer (got ${opts.context.floorNumber}).`,
+      );
+    }
+    context = {
+      $type: `${COLLECTION_PROPOSAL_CONTEXT}#ftcSfContext`,
+      floorNumber: opts.context.floorNumber,
+    };
+  }
+  const record = {
+    $type: COLLECTION_PROPOSAL_CONTEXT,
+    subject: { uri: opts.proposalUri, cid: opts.proposalCid },
+    context,
+    createdAt: new Date().toISOString(),
+  };
+  const res = await opts.agent.com.atproto.repo.createRecord({
+    repo: opts.did,
+    collection: COLLECTION_PROPOSAL_CONTEXT,
+    record,
+  });
+  return {
+    uri: res.data.uri,
+    cid: res.data.cid,
+    rkey: res.data.uri.split("/").pop() ?? "",
+  };
+}
+
 /**
  * Sim-attribution sidecar for a proposal.
  *