pi-simocracy 0.6.2 → 0.8.0

package/README.md

@@ -39,7 +39,8 @@ 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_post_skill` | Publish an Anthropic-style agent skill (`org.simocracy.skill`) **as the loaded sim**. Writes two records to the user's PDS: the skill itself (`name` + `description` + `body` — same shape simocracy.org's SkillFormDialog writes) and an `org.simocracy.history` sidecar with `type: "skill"`. Skills appear at `simocracy.org/skills/<did>/<rkey>` with the full SKILL.md served at `.../skill.md` for loading into any agent harness. Requires `/sim login` + sim ownership. See [`docs/SIM_AUTHORED_SKILLS.md`](docs/SIM_AUTHORED_SKILLS.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. |
 
 ---
@@ -67,6 +68,13 @@ Pi rewrites the constitution and calls `simocracy_update_sim` to persist it. The
 ```
 Pi calls `simocracy_lookup_record` to find the AT-URI, then `simocracy_post_comment` to write the comment + the attribution sidecar.
 
+**Publish a skill as your sim:**
+```
+/sim my mr meow
+> draft a SKILL.md for evaluating cat-sanctuary proposals and publish it
+```
+Pi writes the SKILL.md (`name`, `description`, `body`) in the sim's voice, then calls `simocracy_post_skill` to publish the `org.simocracy.skill` record + the attribution sidecar. The skill appears on `simocracy.org/skills` and is loadable into any agent harness via `/skills/<did>/<rkey>/skill.md`.
+
 ---
 
 ## Loaded-sim system prompt
@@ -95,6 +103,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.
+- [`docs/SIM_AUTHORED_SKILLS.md`](docs/SIM_AUTHORED_SKILLS.md) — same pattern, applied to `org.simocracy.skill` agent skills.
 - [Simocracy](https://simocracy.org) · [pi](https://github.com/mariozechner/pi-coding-agent)
 
 MIT — see [LICENSE](LICENSE).

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/docs/SIM_AUTHORED_SKILLS.md

@@ -0,0 +1,221 @@
+# Sim-authored skills
+
+How pi-simocracy attributes an Anthropic-style agent skill
+(`org.simocracy.skill`) to a sim *without* extending the skill
+lexicon — and how
+[simocracy-v2](https://github.com/GainForest/simocracy-v2) renders
+the attribution. Same pattern as
+[sim-authored comments](./SIM_AUTHORED_COMMENTS.md) and
+[sim-authored proposals](./SIM_AUTHORED_PROPOSALS.md), different
+subject collection.
+
+---
+
+## TL;DR
+
+When pi publishes a skill on behalf of a loaded sim, it writes
+**two** records to the user's PDS:
+
+1. **`org.simocracy.skill`** — the skill itself, in the exact shape
+   simocracy.org's `SkillFormDialog` already writes today: `name`
+   (lowercase kebab-case identifier), `description` (the SKILL.md
+   trigger text), `body` (the markdown instructions, no YAML
+   frontmatter), `createdAt`. Old readers (the existing skills
+   gallery, the `/skills/[did]/[rkey]/skill.md` route) see this
+   as a regular user-authored skill — graceful degradation.
+2. **`org.simocracy.history`** — sidecar with `type: "skill"`,
+   `subjectUri` pointing at the skill we just wrote,
+   `subjectCollection: "org.simocracy.skill"`, `simUris[]` /
+   `simNames[]` declaring which sim spoke, and a denormalized
+   `content` snippet (the description) so the timeline renders
+   without a second round-trip.
+
+Renderers that understand the history join (simocracy.org, after
+the planned change lands) display a sim badge on the skill card;
+renderers that don't keep showing it as a regular user skill.
+**Zero skill lexicon changes.**
+
+---
+
+## Why no lexicon change
+
+The `org.simocracy.skill` record schema is intentionally minimal —
+it's just `name` + `description` + `body` so any agent harness can
+load it via the `/skills/[did]/[rkey]/skill.md` reconstruction
+route. Adding a `sim` StrongRef field would couple the skill
+lexicon to a Simocracy-specific concept (sim-authorship) and break
+the "this is just a SKILL.md container" framing.
+
+The `org.simocracy.history` lexicon already has every field we
+need — same case made for comments
+([`SIM_AUTHORED_COMMENTS.md`](./SIM_AUTHORED_COMMENTS.md)) and
+proposals ([`SIM_AUTHORED_PROPOSALS.md`](./SIM_AUTHORED_PROPOSALS.md)),
+applied verbatim:
+
+| Field              | Used for sim-authored skills                                   |
+|--------------------|----------------------------------------------------------------|
+| `type`             | `"skill"` (new value — appended like other event types)        |
+| `actorDid`         | The human who published 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 skill record this attribution applies to         |
+| `subjectCollection`| `"org.simocracy.skill"`                                        |
+| `subjectName`      | Skill name (denormalized for the timeline)                     |
+| `content`          | Skill description (denormalized so the indexer doesn't have to fetch the skill record to render the timeline) |
+| `createdAt`        | ISO timestamp                                                  |
+
+Use it as-is.
+
+---
+
+## Write path (pi-simocracy)
+
+Implemented by `simocracy_post_skill` in `src/index.ts`:
+
+```ts
+// 1. The skill — same shape as SkillFormDialog writes today.
+const skill = await createSkill({
+  agent, did,
+  name,         // lowercase, kebab-case (e.g. "quadratic-funding")
+  description,  // SKILL.md trigger text — when an agent should load it
+  body,         // markdown instructions, no YAML frontmatter
+});
+
+// 2. The sim-attribution sidecar — required, since attribution is the
+//    whole point of this tool.
+await createSkillHistory({
+  agent, did,
+  skillUri:        skill.uri,
+  skillName:       name,
+  skillDescription: description,
+  simUri:          loadedSim.uri,
+  simName:         loadedSim.name,
+});
+```
+
+Both writes go to the **user's** PDS via their OAuth session — same
+auth path that already powers `simocracy_post_comment`,
+`simocracy_post_proposal`, 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 / proposal paths.
+
+If the sidecar write fails after the skill succeeds, **the skill 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
+
+- **Skill editing.** Create-only for now. Editing an existing
+  skill would mean either a `putRecord` at a known rkey (no good
+  way to discover it from the loaded sim — skills have no `sim`
+  ref) or a `findRkeyForSkill` join through the history sidecar.
+  Out of scope until a real edit use case shows up.
+- **Skill deletion.** Same reason. The user can delete via the
+  webapp.
+- **Cross-skill linking.** Pi doesn't try to inject prerequisite /
+  related-skill references. The skill body is whatever the sim
+  writes; if it wants to reference another skill it includes the
+  AT-URI inline.
+
+---
+
+## Read path (proposed simocracy-v2 changes)
+
+Mirrors the comment + proposal renderer changes in shape, applied
+to the skills gallery / detail views.
+
+### 1. Skills gallery query — pull history records in parallel
+
+After fetching the skills via `fetchSkills`, fetch all
+`org.simocracy.history` records (capped, like notifications does)
+and build a `Map<skillUri, HistoryRecord>` keyed on `subjectUri`.
+Filter to `type === "skill"` and `subjectCollection ===
+"org.simocracy.skill"`. Attach `simUri`, `simName`, and a
+resolved `simAvatarUrl` to each skill in the response that has a
+match. Sim avatar resolution can reuse `fetchAllSimsWithMeta()` —
+no extra round-trips per skill.
+
+### 2. Extend the skill type
+
+```ts
+export interface SkillRecord {
+  // …existing fields…
+  simUri?: string
+  simName?: string
+  simAvatarUrl?: string
+}
+```
+
+No change to `SkillFormDialog` — that path stays for human
+authors. Sim-authored skills come from the CLI today, and a
+future "draft as sim" button in the dialog would bundle both
+writes the same way pi-simocracy does.
+
+### 3. Skill card — sim badge
+
+In `SkillCard` (`components/skills/skills-gallery.tsx`), when
+`skill.simUri` is set:
+
+- Render the sim sprite inline next to the title (32×32 walk-1
+  frame), the way proposal cards do.
+- Render the byline as `🐾 {simName} · drafted by @{userHandle}`
+  so attribution stays unambiguous (the sim "drafted" it; the human
+  published 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.
+
+Skills without `simUri` keep rendering exactly as today — no
+regression for human-authored skills.
+
+### 4. SKILL.md reconstruction
+
+The `/skills/[did]/[rkey]/skill.md` route stays unchanged — the
+served file is the canonical SKILL.md any agent harness loads,
+and sim attribution is metadata for the *gallery*, not the
+SKILL.md contents. Keeping attribution out of the served file
+means a sim-authored skill can be loaded by any external harness
+(Anthropic skills CLI, custom agent runtimes, …) without that
+harness needing to understand Simocracy lexicons.
+
+---
+
+## Querying sim-authored skills
+
+For "show me everything my sim has published":
+
+```ts
+const histories = await fetchHistory()  // existing helper
+const mySimSkills = histories.filter(h =>
+  h.event.type === "skill" &&
+  h.event.simUris?.includes(mySimUri)
+)
+```
+
+Each result has `subjectUri` (the skill URI) and `content`
+(denormalized description). Resolve the skill URI for the full
+record. Same query shape the notifications system already uses
+for chat / comment / proposal events — no new indexer queries
+needed.
+
+---
+
+## Status
+
+- ✅ Implemented in pi-simocracy `simocracy_post_skill` (this repo)
+- ⏳ Renderer changes pending in simocracy-v2 (sim badge on skill
+  cards, history-sidecar join in `fetchSkills` / skill detail page)
+- ✅ No new lexicons — uses the existing `org.simocracy.skill` and
+  `org.simocracy.history` records as-is
+
+The skill + history pair is being written today. Every pi-authored
+skill carries the sim badge (history sidecar) so once
+simocracy-v2's renderer change lands the attribution surfaces
+automatically — no migration, no backfill needed for new
+submissions. Pre-renderer, pi-authored skills appear identically
+to human-authored skills on `simocracy.org/skills`.

package/package.json

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

@@ -61,6 +61,14 @@
  *                             `type: "proposal"`. Same write pattern
  *                             as `simocracy_post_comment`. Requires
  *                             /sim login + sim ownership.
+ *  - `simocracy_post_skill`   Publish an Anthropic-style agent skill
+ *                             (`org.simocracy.skill`) on behalf of
+ *                             the loaded sim, plus an
+ *                             `org.simocracy.history` sidecar with
+ *                             `type: "skill"`. Same write pattern as
+ *                             `simocracy_post_comment` /
+ *                             `simocracy_post_proposal`. 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
@@ -98,6 +106,7 @@ import {
   fetchSkillMd,
   resolveHandle,
   parseAtUri,
+  getRecordRefFromPds,
   type AgentsRecord,
   type SimMatch,
   type StyleRecord,
@@ -129,7 +138,10 @@ import {
   createComment,
   createCommentHistory,
   createProposal,
+  createProposalContext,
   createProposalHistory,
+  createSkill,
+  createSkillHistory,
   createStyle,
   findRkeyForSim,
   getAuthenticatedAgent,
@@ -137,6 +149,7 @@ import {
   NotSimOwnerError,
   updateAgents,
   updateStyle,
+  type ProposalContextTarget,
 } from "./writes.ts";
 
 // ---------------------------------------------------------------------------
@@ -787,6 +800,47 @@ 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 PostSkillToolParams = Type.Object({
+  name: Type.String({
+    description:
+      "Skill identifier — lowercase, kebab-case (e.g. `quadratic-funding`). Maps to the `name` field of the SKILL.md YAML frontmatter. Required, max 100 characters.",
+    minLength: 1,
+    maxLength: 100,
+    pattern: "^[a-z][a-z0-9-]*$",
+  }),
+  description: Type.String({
+    description:
+      "Skill triggering description — what the skill does AND when an agent should load it. Maps to the `description` field of the SKILL.md YAML frontmatter; this is the primary signal an agent uses to decide whether to load the skill, so make it specific and a little pushy. Required, max 1024 characters.",
+    minLength: 1,
+    maxLength: 1024,
+  }),
+  body: Type.String({
+    description:
+      "Markdown body of SKILL.md, without YAML frontmatter — the actual instructions. Anthropic recommends keeping this under ~500 lines. Required, max 50000 characters.",
+    minLength: 1,
+    maxLength: 500000,
+  }),
 });
 
 const LookupRecordToolParams = Type.Object({
@@ -1492,11 +1546,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(
@@ -1520,6 +1584,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
@@ -1573,6 +1695,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 {
@@ -1593,12 +1735,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) {
@@ -1621,6 +1776,137 @@ 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,
+        },
+      };
+    },
+  });
+
+  // -------------------------------------------------------------------------
+  // Tool: simocracy_post_skill
+  //
+  // Publish an Anthropic-style agent skill (`org.simocracy.skill`) on
+  // behalf of the loaded sim. Two records are written to the user's
+  // PDS, mirroring `simocracy_post_comment` / `simocracy_post_proposal`:
+  //
+  //   1. org.simocracy.skill      the skill record itself, in the same
+  //      wire shape simocracy.org's `SkillFormDialog` writes today, so
+  //      it renders identically on /skills.
+  //   2. org.simocracy.history    sidecar with type="skill",
+  //      simUris=[loadedSim], subjectUri=<skill uri>. Renderers that
+  //      understand the join show the sim badge; others see a regular
+  //      user-authored skill — graceful degradation, zero lexicon
+  //      changes.
+  //
+  // See `docs/SIM_AUTHORED_SKILLS.md` for the design rationale.
+  // -------------------------------------------------------------------------
+  pi.registerTool({
+    name: "simocracy_post_skill",
+    label: "Publish a Simocracy skill as the loaded sim",
+    description:
+      "Publish an Anthropic-style agent skill (`org.simocracy.skill`) on behalf of the currently loaded sim. The sim should write the `name` (lowercase kebab-case identifier), `description` (what the skill does AND when an agent should load it — the primary trigger signal), and `body` (the markdown instructions, without YAML frontmatter) in their own voice; their persona is already in your system prompt. Writes TWO records to the user's PDS: (1) the `org.simocracy.skill` record itself in the same shape simocracy.org's SkillFormDialog writes today, and (2) an `org.simocracy.history` sidecar with `type: \"skill\"` attributing the skill to the loaded sim. Use this when the user asks the sim to write, publish, or share a skill — e.g. \"Mr Meow, draft a skill for evaluating cat-sanctuary proposals\" or \"publish a skill on quadratic funding\". The skill appears on simocracy.org/skills and can be loaded into any agent harness via /skills/<did>/<rkey>/skill.md. Anthropic recommends keeping `body` under ~500 lines. Requires /sim login + a loaded sim the user owns.",
+    parameters: PostSkillToolParams,
+    async execute(_id, { name, description, body }) {
+      if (!loadedSim) {
+        throw new Error(
+          "No sim loaded. Call simocracy_load_sim first — skills are published on behalf of a specific sim.",
+        );
+      }
+      let auth;
+      try {
+        auth = await assertCanWriteToSim(loadedSim, {
+          action: "publish a skill 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}`);
+      }
+
+      let skill;
+      try {
+        skill = await createSkill({
+          agent: pdsAgent,
+          did: auth.did,
+          name,
+          description,
+          body,
+        });
+      } catch (err) {
+        throw new Error(`Skill write failed: ${(err as Error).message}`);
+      }
+
+      let sidecarUri: string | undefined;
+      let sidecarWarning: string | undefined;
+      try {
+        const history = await createSkillHistory({
+          agent: pdsAgent,
+          did: auth.did,
+          skillUri: skill.uri,
+          skillName: name,
+          skillDescription: description,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
+        });
+        sidecarUri = history.uri;
+      } catch (err) {
+        // Don't roll back — the skill 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}`;
+      }
+
+      // Public URLs the LLM can hand back to the user. The skill page
+      // is served by simocracy-v2's /skills/[did]/[rkey] route; the
+      // .md endpoint reconstructs the full SKILL.md (frontmatter + body)
+      // for any agent harness that wants to load it.
+      const did = encodeURIComponent(loadedSim.did);
+      const rkey = encodeURIComponent(skill.rkey);
+      const pageUrl = `https://www.simocracy.org/skills/${did}/${rkey}`;
+      const skillMdUrl = `https://www.simocracy.org/skills/${did}/${rkey}/skill.md`;
+
+      const lines = [
+        `Published skill as ${loadedSim.name}${loadedSim.handle ? ` (@${loadedSim.handle})` : ""}:`,
+        `  name:        ${name}`,
+        `  skill URI:   ${skill.uri}`,
+        `  page:        ${pageUrl}`,
+        `  SKILL.md:    ${skillMdUrl}`,
+      ];
+      if (sidecarUri) {
+        lines.push(`  attribution: ${sidecarUri}  (org.simocracy.history sidecar)`);
+      } else if (sidecarWarning) {
+        lines.push(`  WARNING:     ${sidecarWarning}`);
+        lines.push(
+          `               The skill is published but will appear unattributed until a history sidecar is written.`,
+        );
+      }
+      return {
+        content: [{ type: "text" as const, text: lines.join("\n") }],
+        details: {
+          skillUri: skill.uri,
+          skillRkey: skill.rkey,
+          skillCid: skill.cid,
+          name,
+          description,
+          pageUrl,
+          skillMdUrl,
+          simUri: loadedSim.uri,
+          simName: loadedSim.name,
           sidecarUri,
           sidecarWarning,
         },

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);

package/src/writes.ts

@@ -130,6 +130,8 @@ 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";
+const COLLECTION_SKILL = "org.simocracy.skill";
 
 /**
  * Defense-in-depth: every write helper below verifies the target
@@ -455,6 +457,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.
  *
@@ -513,6 +595,117 @@ export async function createProposalHistory(opts: {
   };
 }
 
+/**
+ * POST `org.simocracy.skill` (an Anthropic-style agent skill).
+ *
+ * The lexicon stores the SKILL.md frontmatter (`name`, `description`)
+ * as separate fields and the markdown body in `body`, so the indexer
+ * can filter on metadata cheaply without parsing markdown. The full
+ * SKILL.md is reconstructed at serve time by simocracy.org's
+ * `/skills/[did]/[rkey]/skill.md` route.
+ *
+ * Skills are NOT 1:1 with sims — the lexicon has no `sim` ref. They
+ * live in the *user's* own PDS exactly the way simocracy.org's
+ * `SkillFormDialog` writes them today, so a sim-authored skill
+ * renders identically to a human-authored skill on the gallery.
+ * Sim attribution is a sidecar `org.simocracy.history` record
+ * written by `createSkillHistory` below — same pattern as comments
+ * and proposals. See `docs/SIM_AUTHORED_SKILLS.md` for the design.
+ */
+export async function createSkill(opts: {
+  agent: Agent;
+  did: string;
+  name: string;
+  description: string;
+  body: string;
+}): Promise<{ uri: string; cid: string; rkey: string }> {
+  const name = opts.name.trim();
+  if (!name) throw new Error("Skill name is required.");
+  const description = opts.description.trim();
+  if (!description) throw new Error("Skill description is required.");
+  const body = opts.body.trim();
+  if (!body) throw new Error("Skill body is required.");
+  // Lexicon caps (mirrored from lexicons/org/simocracy/skill.json):
+  //   name        ≤ 100 graphemes (maxLength 1000)
+  //   description ≤ 1024 graphemes (maxLength 10000)
+  //   body        ≤ 50000 graphemes (maxLength 500000)
+  // Slice on JS string length is a conservative approximation of grapheme
+  // count — it never exceeds the limit, occasionally trims early on rare
+  // multi-codepoint clusters. Same approach used elsewhere in this module.
+  const record = {
+    $type: COLLECTION_SKILL,
+    name: name.slice(0, 1000),
+    description: description.slice(0, 10000),
+    body: body.slice(0, 500000),
+    createdAt: new Date().toISOString(),
+  };
+  const res = await opts.agent.com.atproto.repo.createRecord({
+    repo: opts.did,
+    collection: COLLECTION_SKILL,
+    record,
+  });
+  return {
+    uri: res.data.uri,
+    cid: res.data.cid,
+    rkey: res.data.uri.split("/").pop() ?? "",
+  };
+}
+
+/**
+ * Sim-attribution sidecar for a skill.
+ *
+ * Mirrors `createCommentHistory` and `createProposalHistory` exactly —
+ * same `org.simocracy.history` lexicon, same join-key shape, just
+ * `type: "skill"` and `subjectCollection: "org.simocracy.skill"`.
+ * The lexicon's `type` field is free-form string and the indexer
+ * already accepts new event types as they appear (history.json
+ * documents this explicitly).
+ *
+ * Writes to the *user's* own PDS — the attribution is an event the
+ * user triggered and naturally belongs in their history.
+ */
+export async function createSkillHistory(opts: {
+  agent: Agent;
+  did: string;
+  skillUri: string;
+  skillName: string;
+  skillDescription: string;
+  simUri: string;
+  simName: string;
+}): Promise<{ uri: string; cid: string; rkey: string }> {
+  // Defense-in-depth: the sim must live in the same repo we're writing
+  // to. The skill 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 skillName = opts.skillName.trim();
+  const description = opts.skillDescription.trim();
+  const record: Record<string, unknown> = {
+    $type: COLLECTION_HISTORY,
+    type: "skill",
+    actorDid: opts.did,
+    simNames: [opts.simName].slice(0, 10),
+    simUris: [opts.simUri].slice(0, 10),
+    subjectUri: opts.skillUri,
+    subjectCollection: COLLECTION_SKILL,
+    subjectName: skillName.slice(0, 500),
+    createdAt: new Date().toISOString(),
+  };
+  if (description) {
+    record.content = description.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