@kubitnodes/stellaris 0.3.18 → 0.3.19

package/dist/server/index.js

@@ -6,7 +6,7 @@ import path9 from "node:path";
 import { serve } from "@hono/node-server";
 
 // packages/board-core/dist/board.js
-import { mkdir as mkdir4, readdir as readdir3, readFile as readFile5, rename as rename3, stat as stat2 } from "node:fs/promises";
+import { chmod as chmod2, cp, mkdir as mkdir4, readdir as readdir3, readFile as readFile5, rename as rename3, rm as rm2, stat as stat2, writeFile as writeFile4 } from "node:fs/promises";
 import path6 from "node:path";
 import { decodeTime, monotonicFactory } from "ulid";
 import { z as z13 } from "zod";
@@ -637,7 +637,7 @@ var ArchiveProposalSchema = z4.object({
 var SkillProposalSchema = z4.object({
   name: NameSchema,
   summary: z4.string().min(1).max(200),
-  body: z4.string().min(1)
+  body: z4.string().min(1).optional()
 });
 var ProposalCharterSchemas = {
   role: RoleCharterSchema,
@@ -764,6 +764,7 @@ var HomeFileDiffSchema = HomeFileChangeSchema.pick({ path: true, status: true })
 var KnowledgeSchema = z4.object({
   topic: NameSchema,
   project: NameSchema.nullable(),
+  revision: z4.number().int().min(0),
   updatedBy: NameSchema,
   updatedAt: IsoDateTimeSchema
 });
@@ -786,6 +787,24 @@ var ProposalOriginSchema = z4.object({
   thread: UlidSchema.optional(),
   channel: NameSchema.optional()
 });
+var SKILL_FILES_LIMIT = 100;
+var SKILL_BYTES_LIMIT = 10 * 1024 * 1024;
+var SkillFileSchema = z4.object({
+  path: z4.string().min(1),
+  size: z4.number().int().nonnegative(),
+  executable: z4.boolean()
+});
+var SkillFilesSchema = z4.object({
+  /** The commit of the proposer's home the files came from. */
+  commit: CommitIdSchema,
+  takenAt: IsoDateTimeSchema,
+  files: z4.array(SkillFileSchema)
+});
+var SkillFileContentSchema = SkillFileSchema.extend({
+  text: z4.string().nullable(),
+  /** The text was cut at its size limit. */
+  truncated: z4.boolean()
+});
 var ProposalFrontmatterSchema = z4.object({
   id: UlidSchema,
   kind: ProposalKindSchema,
@@ -794,6 +813,8 @@ var ProposalFrontmatterSchema = z4.object({
   createdAt: IsoDateTimeSchema,
   /** Absent for a proposal filed outside a turn, or before proposals recorded it. */
   filedFrom: ProposalOriginSchema.optional(),
+  /** A skill proposal's folder, once taken; absent for one proposed as text alone. */
+  skillFiles: SkillFilesSchema.optional(),
   decidedBy: NameSchema.optional(),
   decidedAt: IsoDateTimeSchema.optional(),
   reason: z4.string().optional(),
@@ -896,7 +917,9 @@ var VerbInputs = {
     /** A project you belong to, or null for society knowledge, which the steward and the user curate. */
     project: NameSchema.nullable().default(null),
     topic: NameSchema,
-    body: z5.string().min(1)
+    body: z5.string().min(1),
+    /** The `revision` in the frontmatter of the topic you read, 0 when it names none or for a new topic. */
+    revision: z5.number().int().min(0)
   }),
   remove_knowledge: z5.object({
     /** As for write_knowledge: a project you belong to, or null for society knowledge. */
@@ -986,7 +1009,7 @@ var VERB_DESCRIPTIONS = {
   create_project: "Create a project with its general channel: a slug, a display name, a git remote when one exists, and optionally a completion effect (none, merge, or ghpr for a GitHub remote).",
   join_project: "Join a project, or add another citizen to one when your role allows it. Membership gives the pair a worktree and an onboarding turn, and follows the project's general; the result lists its other open channels, to subscribe to when the work needs them.",
   leave_project: "Leave a project, or remove another citizen from one when your role allows it.",
-  write_knowledge: "Write or replace a knowledge topic: durable facts every member of a project should know, or with project null the society's shared knowledge (steward and user). Not a message; use post_message for those.",
+  write_knowledge: "Write or replace a knowledge topic: durable facts every member of a project should know, or with project null the society's shared knowledge (steward and user). Not a message; use post_message for those. Pass the revision from the frontmatter of the topic you read, or 0 for a new topic; if it was written since, the call is refused with the current text to merge yours into.",
   remove_knowledge: "Remove a knowledge topic that is wrong, superseded, or folded into another, so no turn or search finds it again. Whoever may write the topic may remove it; the board keeps its text aside for the user to restore.",
   plan_task: "Reshape a task's plan from the current stage onward, or after it while someone holds it: keep a stage by passing its id, drop it by leaving it out, add one without an id. Gated stages and on_done: user, steward, concierge.",
   advance_task: "Finish the stage you hold, with a note for the task's thread on what you did. The next stage becomes current; past the last one the task is done.",
@@ -1030,6 +1053,7 @@ var BOARD_EVENT_TYPES = [
   "proposal.created",
   "proposal.decided",
   "proposal.provisioned",
+  "proposal.files_taken",
   "channel.added",
   "channel.archived",
   "role.added",
@@ -1458,6 +1482,9 @@ var RunnerAnswerSchema = z7.discriminatedUnion("ok", [
 ]);
 var WarmSessionsSchema = z7.object({ warm: z7.array(z7.string()) });
 var FileManifestSchema = z7.object({ files: z7.record(z7.string(), z7.string()) });
+function fileVersion(sha, executable) {
+  return executable ? `${sha}+x` : sha;
+}
 var FileReadSchema = z7.object({ paths: z7.array(z7.string()) });
 var FileContentsSchema = z7.object({ files: z7.record(z7.string(), z7.string()) });
 function isSafeRelativePath(file) {
@@ -1834,7 +1861,7 @@ var RunnerConfigSchema = z11.object({
 });
 
 // packages/shared/dist/version.js
-var STELLARIS_VERSION = "0.3.18";
+var STELLARIS_VERSION = "0.3.19";
 
 // packages/board-core/dist/errors.js
 var BoardError = class extends Error {
@@ -1891,7 +1918,9 @@ async function readMarkdown(file, schema) {
   return { data: schema.parse(parsed.data), body: parsed.content.replace(/^\n/, "") };
 }
 async function readLooseMarkdown(file) {
-  const raw = await readFile(file, "utf8");
+  return parseLooseMarkdown(await readFile(file, "utf8"));
+}
+function parseLooseMarkdown(raw) {
   try {
     const parsed = parseMatter(raw);
     return { data: parsed.data, body: parsed.content.replace(/^\n/, ""), error: null };
@@ -2078,13 +2107,14 @@ var FileTree = class {
       if (info.size > MAX_FILE_BYTES) {
         return null;
       }
+      const executable = (info.mode & 73) !== 0;
       const known = this.hashes.get(absolute);
       if (known !== void 0 && known.mtimeMs === info.mtimeMs && known.size === info.size) {
-        return known.sha;
+        return fileVersion(known.sha, executable);
       }
       const sha = createHash("sha256").update(await readFile3(absolute)).digest("hex");
       this.hashes.set(absolute, { mtimeMs: info.mtimeMs, size: info.size, sha });
-      return sha;
+      return fileVersion(sha, executable);
     } catch (error) {
       if (isMissing2(error)) {
         return null;
@@ -2335,6 +2365,55 @@ var HomeRepos = class {
     }
     return files;
   }
+  /**
+   * The files of a folder in a home's newest commit, by path within the folder, with the commit;
+   * conflict copies and anything but a regular file are left out. Null when the home is not a
+   * repository yet.
+   */
+  async folder(home, folder) {
+    if (!await exists(path4.join(home, ".git"))) {
+      return null;
+    }
+    const commit = (await read(home, ["rev-parse", "--verify", "HEAD^{commit}"])).trim();
+    const prefix = `${folder}/`;
+    const listed = await read(home, [
+      "ls-tree",
+      "-r",
+      "-z",
+      "--long",
+      "--full-tree",
+      commit,
+      prefix
+    ]);
+    const files = [];
+    for (const entry of listed.split("\0")) {
+      const match = /^(100644|100755) blob ([0-9a-f]+) +(\d+)\t(.+)$/.exec(entry);
+      const [, mode = "", object = "", size = "0", file = ""] = match ?? [];
+      if (match === null || !file.startsWith(prefix) || !isSafeRelativePath(file) || conflictCopyOf(file) !== null) {
+        continue;
+      }
+      files.push({
+        path: file.slice(prefix.length),
+        object,
+        size: Number.parseInt(size, 10),
+        executable: mode === "100755"
+      });
+    }
+    return { commit, files };
+  }
+  /** A blob of a home's repository, as `folder` names it. */
+  async blob(home, object) {
+    const result = await execa("git", ["cat-file", "blob", object], {
+      cwd: home,
+      encoding: "buffer",
+      stripFinalNewline: false,
+      reject: false
+    });
+    if (result.exitCode !== 0) {
+      throw new Error(`git cat-file failed: ${Buffer.from(result.stderr).toString().trim()}`);
+    }
+    return Buffer.from(result.stdout);
+  }
   /** The conflict copies a merge added, against its first parent. */
   async keptCopies(home, parent, commit) {
     const added = await read(home, [
@@ -2750,6 +2829,10 @@ var BoardPaths = class {
   proposal(id) {
     return path5.join(this.proposals(), `${id}.md`);
   }
+  /** A skill proposal's folder, as the board took it from its proposer's home. */
+  proposalFiles(id) {
+    return path5.join(this.proposals(), id);
+  }
   decisions() {
     return path5.join(this.society, "decisions");
   }
@@ -3001,6 +3084,20 @@ var MENTION_PATTERN = /(^|[^\w@])@([a-z0-9][a-z0-9-]{0,31})(?![\w-])/g;
 function withoutMentions(text) {
   return text.replaceAll(MENTION_PATTERN, "$1$2");
 }
+var SKILL_TEXT_LIMIT_CHARS = 1e5;
+function skillFolderOf(proposal) {
+  if (proposal.kind !== "skill") {
+    return null;
+  }
+  const parsed = SkillProposalSchema.safeParse(proposal.charter);
+  return parsed.success && parsed.data.body === void 0 ? parsed.data.name : null;
+}
+function proposedFrom(origin, where) {
+  return origin !== void 0 && origin.scope === where.scope && origin.thread === where.thread && origin.channel === where.channel;
+}
+function megabytes(bytes) {
+  return (bytes / (1024 * 1024)).toFixed(1).replace(/\.0$/, "");
+}
 var CURATING_ROLES = [USER_ROLE, "steward"];
 var SEED_INSTRUCTIONS_HEADING = "## Seed instructions";
 var OPS_WAKE_TRIGGER = "ops_event";
@@ -3923,22 +4020,41 @@ ${charter.purpose}
     const dir = project === null ? this.paths.societyKnowledge() : this.paths.projectKnowledge(project);
     const topics = [];
     for (const file of await listFiles(dir)) {
-      const doc = await readMarkdown(path6.join(dir, file), z13.record(z13.string(), z13.unknown()));
-      const parsed = KnowledgeSchema.safeParse({
-        ...doc.data,
-        project,
-        topic: file.replace(/\.md$/, "")
-      });
-      const data = parsed.success ? parsed.data : {
-        topic: file.replace(/\.md$/, ""),
-        project,
-        updatedBy: SYSTEM_ACTOR.name,
-        updatedAt: (await stat2(path6.join(dir, file))).mtime.toISOString()
-      };
-      topics.push({ ...data, body: doc.body });
+      topics.push(await this.knowledgeAt(path6.join(dir, file), project, file.replace(/\.md$/, "")));
     }
     return topics;
   }
+  knowledgeFile(project, topic) {
+    return project === null ? this.paths.societyKnowledgeFile(topic) : this.paths.projectKnowledgeFile(project, topic);
+  }
+  /**
+   * Read loosely, as a dashboard is: a topic written before revisions counts as revision 0, and an
+   * author or a time that does not parse is the board's at the file's mtime.
+   */
+  async knowledgeAt(file, project, topic) {
+    const { data, body } = await readLooseMarkdown(file);
+    const revision = z13.number().int().min(0).safeParse(data["revision"]);
+    const updatedBy = NameSchema.safeParse(data["updatedBy"]);
+    const updatedAt = IsoDateTimeSchema.safeParse(data["updatedAt"]);
+    return {
+      topic,
+      project,
+      revision: revision.success ? revision.data : 0,
+      updatedBy: updatedBy.success ? updatedBy.data : SYSTEM_ACTOR.name,
+      updatedAt: updatedAt.success ? updatedAt.data : (await stat2(file)).mtime.toISOString(),
+      body
+    };
+  }
+  /** The highest revision among a topic's removed copies, 0 when it has none. */
+  async removedRevision(project, topic) {
+    const aside = this.paths.removedKnowledge(project ?? SOCIETY_SCOPE);
+    let highest = 0;
+    for (const file of (await listFiles(aside)).filter((name) => name.startsWith(`${topic}.`))) {
+      const copy = await this.knowledgeAt(path6.join(aside, file), project, topic);
+      highest = Math.max(highest, copy.revision);
+    }
+    return highest;
+  }
   /** Skills promoted to the society: every citizen may read them. */
   async listSocietySkills() {
     return this.listSkillsIn(this.paths.societySkills(), "society");
@@ -4652,26 +4768,42 @@ ${task.body}`;
   }
   /**
    * Writes a topic: a project's by its members, the society's by the curating roles. The note in
-   * the matching general channel carries no mention, so nobody is woken.
+   * the matching general channel carries no mention, so nobody is woken. A turn reads a topic from
+   * the copy of the projection pulled when it started, so a revision other than the current one, 0
+   * for a topic not there, means someone wrote or removed it since; the refusal carries the current
+   * text, which that copy lacks.
    */
   async writeKnowledge(actor, input) {
     const args = VerbInputs.write_knowledge.parse(input);
     await this.authorize(actor, "write_knowledge");
     return this.mutex.run(async () => {
       await this.assertMayCurate(actor, args.project);
+      const file = this.knowledgeFile(args.project, args.topic);
+      const current = await exists(file) ? await this.knowledgeAt(file, args.project, args.topic) : null;
+      const place = args.project ?? "the society";
+      if (current === null && args.revision !== 0) {
+        throw new BoardError("INVALID_STATE", `${place} has no knowledge topic ${args.topic}, so it has no revision ${args.revision}: it was removed since you read it, or never written. Write it with revision 0 to start it anew.`);
+      }
+      if (current !== null && args.revision !== current.revision) {
+        throw new BoardError("INVALID_STATE", `the knowledge topic ${args.topic} of ${place} is at revision ${current.revision}, updated by ${current.updatedBy} at ${current.updatedAt}, not ${args.revision}. Merge your changes into its current text, below, and write again with revision ${current.revision}.
+
+${current.body}`);
+      }
+      const base = current?.revision ?? await this.removedRevision(args.project, args.topic);
       const data = KnowledgeSchema.parse({
         topic: args.topic,
         project: args.project,
+        revision: base + 1,
         updatedBy: actor.name,
         updatedAt: this.now().toISOString()
       });
-      const file = args.project === null ? this.paths.societyKnowledgeFile(args.topic) : this.paths.projectKnowledgeFile(args.project, args.topic);
-      const replaced = await exists(file);
+      const replaced = current !== null;
       await writeMarkdown(file, data, args.body);
       await this.events.append("knowledge.written", actor.name, {
         topic: args.topic,
         project: args.project,
-        replaced
+        replaced,
+        revision: data.revision
       });
       const where = args.project === null ? "general" : channelRef(args.project, "general");
       await this.appendMessage(actor.name, where, `Knowledge ${replaced ? "updated" : "written"}: ${args.topic}. It is under knowledge/${args.topic}.md${args.project === null ? " of the society" : ""}.`, {
@@ -4694,7 +4826,7 @@ ${task.body}`;
     await this.authorize(actor, "remove_knowledge");
     return this.mutex.run(async () => {
       await this.assertMayCurate(actor, args.project);
-      const file = args.project === null ? this.paths.societyKnowledgeFile(args.topic) : this.paths.projectKnowledgeFile(args.project, args.topic);
+      const file = this.knowledgeFile(args.project, args.topic);
       if (!await exists(file)) {
         throw new BoardError("NOT_FOUND", `${args.project ?? "the society"} has no knowledge topic ${args.topic}`);
       }
@@ -5745,7 +5877,7 @@ ${args.summary}`);
       throw new BoardError("VALIDATION", `invalid ${args.kind} charter: ${parsed.error.message}`);
     }
     return this.mutex.run(async () => {
-      const proposal = {
+      let proposal = {
         ...ProposalFrontmatterSchema.parse({
           id: this.newId(),
           kind: args.kind,
@@ -5764,6 +5896,14 @@ ${args.summary}`);
         body: args.rationale
       };
       await this.validateProvision(proposal.kind, proposal.charter);
+      const skill = skillFolderOf(proposal);
+      if (skill !== null && proposal.filedFrom === void 0) {
+        const taken = await this.takeSkillFolderUnlocked(proposal, skill);
+        if (typeof taken === "string") {
+          throw new BoardError("VALIDATION", taken);
+        }
+        proposal = { ...proposal, skillFiles: taken };
+      }
       await this.writeProposal(proposal);
       await this.events.append("proposal.created", actor.name, {
         proposalId: proposal.id,
@@ -6980,7 +7120,7 @@ Short, curated, loaded on every turn. Keep entries that change future behavior a
       }
       case "skill": {
         const skill = SkillProposalSchema.parse(proposal.charter);
-        const replaced = await this.promoteSkillUnlocked(by, proposal.proposedBy, skill, meta);
+        const replaced = await this.promoteSkillUnlocked(by, proposal, skill, meta);
         return { skill: skill.name, replaced };
       }
       case "archive": {
@@ -6994,26 +7134,180 @@ Short, curated, loaded on every turn. Keep entries that change future behavior a
         return void 0;
     }
   }
-  /** Writes a promoted skill under the society's skills, where every citizen's skills index lists it. */
-  async promoteSkillUnlocked(by, proposedBy, skill, meta) {
+  /**
+   * Publishes a promoted skill under the society's skills, where every citizen's skills index lists
+   * it: the folder the board took from its proposer's home, or the text proposed alone. A
+   * replacement is the whole skill, so files the new version dropped go with the old one.
+   */
+  async promoteSkillUnlocked(by, proposal, skill, meta) {
+    const dir = this.paths.societySkill(skill.name);
     const file = this.paths.societySkillFile(skill.name);
     const replaced = await exists(file);
-    await ensureDir(this.paths.societySkill(skill.name));
+    const taken = proposal.skillFiles;
+    const staged = path6.join(this.paths.proposalFiles(proposal.id), "SKILL.md");
+    if (skill.body === void 0 && (taken === void 0 || !await exists(staged))) {
+      throw new BoardError("INVALID_STATE", `proposal ${proposal.id} holds no skill files`);
+    }
+    await rm2(dir, { recursive: true, force: true });
+    if (skill.body === void 0) {
+      await cp(this.paths.proposalFiles(proposal.id), dir, { recursive: true });
+    } else {
+      await ensureDir(dir);
+    }
+    const body = skill.body ?? (await readLooseMarkdown(file)).body;
     await writeMarkdown(file, {
       name: skill.name,
       description: skill.summary,
-      metadata: { proposedBy, promotedBy: by, promotedAt: this.now().toISOString() }
-    }, skill.body);
+      metadata: {
+        proposedBy: proposal.proposedBy,
+        promotedBy: by,
+        promotedAt: this.now().toISOString(),
+        ...taken === void 0 ? {} : { commit: taken.commit }
+      }
+    }, body);
     await this.events.append("skill.promoted", by, {
       name: skill.name,
       summary: skill.summary,
-      proposedBy,
+      proposedBy: proposal.proposedBy,
       replaced,
+      ...taken === void 0 ? {} : { files: taken.files.length },
       ...meta
     });
     await this.appendMessage(SYSTEM_ACTOR.name, "general", `Skill ${skill.name} ${replaced ? "updated in" : "promoted to"} the society: ${sentence(skill.summary)}. Every citizen's skills index now lists it.`);
     return replaced;
   }
+  /**
+   * Copies a skill's folder from its proposer's home, as the home's newest commit holds it, into the
+   * proposal's folder in the projection, where its deciders read it and from where approval
+   * publishes it. Returns what was taken, or why the home could not give it.
+   */
+  async takeSkillFolderUnlocked(proposal, name) {
+    const home = this.paths.agent(proposal.proposedBy);
+    const folder = `skills/${name}`;
+    const where = `${folder} in ${proposal.proposedBy}'s home`;
+    const taken = await this.homes.folder(home, folder);
+    if (taken === null || !taken.files.some((entry) => entry.path === "SKILL.md")) {
+      return `no ${folder}/SKILL.md in ${proposal.proposedBy}'s home`;
+    }
+    if (taken.files.length > SKILL_FILES_LIMIT) {
+      return `${where} holds ${taken.files.length} files, more than the ${SKILL_FILES_LIMIT} a society skill may`;
+    }
+    const bytes = taken.files.reduce((sum, entry) => sum + entry.size, 0);
+    if (bytes > SKILL_BYTES_LIMIT) {
+      return `${where} holds ${megabytes(bytes)} MB, more than the ${megabytes(SKILL_BYTES_LIMIT)} MB a society skill may`;
+    }
+    const contents = /* @__PURE__ */ new Map();
+    for (const entry of taken.files) {
+      contents.set(entry.path, await this.homes.blob(home, entry.object));
+    }
+    const manual = parseLooseMarkdown(contents.get("SKILL.md")?.toString("utf8") ?? "");
+    if (manual.error !== null) {
+      return `the frontmatter of ${folder}/SKILL.md in ${proposal.proposedBy}'s home does not parse (${manual.error})`;
+    }
+    const dir = this.paths.proposalFiles(proposal.id);
+    await rm2(dir, { recursive: true, force: true });
+    for (const entry of taken.files) {
+      const target = path6.join(dir, ...entry.path.split("/"));
+      await ensureDir(path6.dirname(target));
+      await writeFile4(target, contents.get(entry.path) ?? Buffer.alloc(0));
+      await chmod2(target, entry.executable ? 493 : 420);
+    }
+    return {
+      commit: taken.commit,
+      takenAt: this.now().toISOString(),
+      files: taken.files.map((entry) => ({
+        path: entry.path,
+        size: entry.size,
+        executable: entry.executable
+      }))
+    };
+  }
+  /** Keeps what was taken of a skill proposal's folder on the proposal, and logs it. */
+  async recordSkillFiles(proposal, taken) {
+    const next = { ...proposal, skillFiles: taken };
+    await this.writeProposal(next);
+    await this.events.append("proposal.files_taken", SYSTEM_ACTOR.name, {
+      proposalId: proposal.id,
+      kind: proposal.kind,
+      proposedBy: proposal.proposedBy,
+      commit: taken.commit,
+      files: taken.files.length
+    });
+    return next;
+  }
+  /**
+   * A skill proposal with its folder, for approval: taken now when the turn that filed it ended
+   * without it, as when the server restarted before the turn's end was recorded, and refused while
+   * that turn is still in flight, since the folder reaches the board only when it ends.
+   */
+  async skillFilesForApproval(proposal) {
+    const name = skillFolderOf(proposal);
+    if (name === null || proposal.skillFiles !== void 0) {
+      return proposal;
+    }
+    const cannot = `proposal ${proposal.id} cannot be approved`;
+    const filing = this.turnsInFlight().some((turn) => turn.agent === proposal.proposedBy && proposedFrom(proposal.filedFrom, turn));
+    if (filing) {
+      throw new BoardError("INVALID_STATE", `${cannot} until ${proposal.proposedBy}'s turn that proposed it ends, when the board takes the skill's folder from its home`);
+    }
+    const taken = await this.takeSkillFolderUnlocked(proposal, name);
+    if (typeof taken === "string") {
+      throw new BoardError("INVALID_STATE", `${cannot}: ${taken}; reject it with that reason`);
+    }
+    return this.recordSkillFiles(proposal, taken);
+  }
+  /**
+   * Takes the folders of the skills a citizen proposed from a conversation, once the turn there has
+   * ended and its runner has pushed the citizen's home. A proposal whose folder the home does not
+   * give is rejected by the board with the reason, which wakes the proposer to put it right; while
+   * someone is in a turn in the proposal's thread, it stays as it is, and approval meets the reason.
+   */
+  async takeSkillFiles(turn) {
+    const where = {
+      scope: turn.project,
+      ...turn.thread === void 0 ? {} : { thread: turn.thread },
+      ...turn.channel === void 0 ? {} : { channel: turn.channel }
+    };
+    await this.mutex.run(async () => {
+      for (const proposal of await this.listProposals()) {
+        const name = skillFolderOf(proposal);
+        if (name === null || proposal.status !== "proposed" || proposal.skillFiles !== void 0 || proposal.proposedBy !== turn.agent || !proposedFrom(proposal.filedFrom, where)) {
+          continue;
+        }
+        const taken = await this.takeSkillFolderUnlocked(proposal, name);
+        if (typeof taken !== "string") {
+          await this.recordSkillFiles(proposal, taken);
+          continue;
+        }
+        try {
+          await this.decideUnlocked(SYSTEM_ACTOR, proposal.id, "rejected", `${taken} when the turn that proposed it ended; propose it again once the folder is there`);
+        } catch (error) {
+          if (!(error instanceof BoardError)) {
+            throw error;
+          }
+        }
+      }
+    });
+  }
+  /** A skill proposal's files with their text, as the board took them; none before then. */
+  async readSkillFiles(proposalId) {
+    const proposal = await this.readProposal(proposalId);
+    const dir = this.paths.proposalFiles(proposal.id);
+    const files = [];
+    for (const entry of proposal.skillFiles?.files ?? []) {
+      if (!isSafeRelativePath(entry.path)) {
+        continue;
+      }
+      const bytes = await readFile5(path6.join(dir, ...entry.path.split("/"))).catch(() => null);
+      const text = bytes === null || bytes.includes(0) ? null : bytes.toString("utf8");
+      files.push({
+        ...entry,
+        text: text === null ? null : text.slice(0, SKILL_TEXT_LIMIT_CHARS),
+        truncated: text !== null && text.length > SKILL_TEXT_LIMIT_CHARS
+      });
+    }
+    return files;
+  }
   async validateAddAgent(input) {
     if (await exists(this.paths.agentFile(input.name))) {
       throw new BoardError("ALREADY_EXISTS", `agent ${input.name} already exists`);
@@ -7525,67 +7819,70 @@ ${charter.purpose}
    * retired. Validation runs before any write, so an impossible provision fails the decision.
    */
   async decide(actor, proposalId, outcome, reason) {
-    return this.mutex.run(async () => {
-      const proposal = await this.readProposal(proposalId);
-      if (proposal.status !== "proposed") {
-        throw new BoardError("INVALID_STATE", `proposal ${proposalId} is already ${proposal.status}`);
-      }
-      if (proposal.proposedBy === actor.name) {
-        throw new BoardError("FORBIDDEN", "a proposer never decides its own proposal");
-      }
-      const approvers = ROLE_KIND_APPROVERS[proposal.kind];
-      if (!approvers.includes(actor.role)) {
-        throw new BoardError("FORBIDDEN", `a ${proposal.kind} proposal requires one of: ${approvers.join(", ")}`);
-      }
-      if (outcome === "approved") {
-        await this.validateProvision(proposal.kind, proposal.charter);
-      }
-      this.assertNoTurnCut(actor, `proposal ${proposalId} cannot be decided`, (turn) => turn.thread === proposalId);
-      if (outcome === "approved" && proposal.kind === "archive") {
-        await this.assertProjectQuiet(actor, ArchiveProposalSchema.parse(proposal.charter).project);
-      }
-      const ts = this.now().toISOString();
-      const decision = DecisionSchema.parse({
-        id: this.newId(),
-        proposalId,
-        decidedBy: actor.name,
-        outcome,
-        ...reason === void 0 ? {} : { reason },
-        ts
-      });
-      await writeMarkdown(this.paths.decision(decision.id), decision, reason ?? "");
-      const provision = outcome === "approved" ? await this.executeProvision(actor.name, proposal) : void 0;
-      const status = outcome === "rejected" ? "rejected" : provision === void 0 ? "approved" : "provisioned";
-      await this.writeProposal({
-        ...proposal,
-        status,
-        decidedBy: actor.name,
-        decidedAt: ts,
-        ...reason === void 0 ? {} : { reason },
-        ...provision === void 0 ? {} : { provisionedAt: ts, provision }
-      });
-      await this.events.append("proposal.decided", actor.name, {
+    return this.mutex.run(() => this.decideUnlocked(actor, proposalId, outcome, reason));
+  }
+  async decideUnlocked(actor, proposalId, outcome, reason) {
+    const filed = await this.readProposal(proposalId);
+    if (filed.status !== "proposed") {
+      throw new BoardError("INVALID_STATE", `proposal ${proposalId} is already ${filed.status}`);
+    }
+    if (filed.proposedBy === actor.name) {
+      throw new BoardError("FORBIDDEN", "a proposer never decides its own proposal");
+    }
+    const approvers = ROLE_KIND_APPROVERS[filed.kind];
+    if (!approvers.includes(actor.role)) {
+      throw new BoardError("FORBIDDEN", `a ${filed.kind} proposal requires one of: ${approvers.join(", ")}`);
+    }
+    if (outcome === "approved") {
+      await this.validateProvision(filed.kind, filed.charter);
+    }
+    this.assertNoTurnCut(actor, `proposal ${proposalId} cannot be decided`, (turn) => turn.thread === proposalId);
+    if (outcome === "approved" && filed.kind === "archive") {
+      await this.assertProjectQuiet(actor, ArchiveProposalSchema.parse(filed.charter).project);
+    }
+    const proposal = outcome === "approved" ? await this.skillFilesForApproval(filed) : filed;
+    const ts = this.now().toISOString();
+    const decision = DecisionSchema.parse({
+      id: this.newId(),
+      proposalId,
+      decidedBy: actor.name,
+      outcome,
+      ...reason === void 0 ? {} : { reason },
+      ts
+    });
+    await writeMarkdown(this.paths.decision(decision.id), decision, reason ?? "");
+    const provision = outcome === "approved" ? await this.executeProvision(actor.name, proposal) : void 0;
+    const status = outcome === "rejected" ? "rejected" : provision === void 0 ? "approved" : "provisioned";
+    await this.writeProposal({
+      ...proposal,
+      status,
+      decidedBy: actor.name,
+      decidedAt: ts,
+      ...reason === void 0 ? {} : { reason },
+      ...provision === void 0 ? {} : { provisionedAt: ts, provision }
+    });
+    await this.events.append("proposal.decided", actor.name, {
+      proposalId,
+      outcome,
+      kind: proposal.kind,
+      proposedBy: proposal.proposedBy,
+      ...proposal.filedFrom === void 0 ? {} : { filedFrom: proposal.filedFrom }
+    });
+    if (provision !== void 0) {
+      await this.events.append("proposal.provisioned", actor.name, {
         proposalId,
-        outcome,
         kind: proposal.kind,
-        proposedBy: proposal.proposedBy,
-        ...proposal.filedFrom === void 0 ? {} : { filedFrom: proposal.filedFrom }
+        ...provision
       });
-      if (provision !== void 0) {
-        await this.events.append("proposal.provisioned", actor.name, {
-          proposalId,
-          kind: proposal.kind,
-          ...provision
-        });
-      }
-      const verdict = outcome === "approved" ? "Approved" : "Rejected";
-      const why = reason === void 0 ? "" : ` Reason: ${reason}.`;
-      const result = provision === void 0 ? "" : ` Provisioned: ${Object.entries(provision).map(([key, value]) => `${key} ${plain(value)}`).join(", ")}.`;
-      const thread = await this.proposalThreadUnlocked(actor.name, proposal);
-      await this.appendThreadMessage(actor.name, thread.id, `${verdict}: ${describeCharter(proposal.kind, proposal.charter)}.${why}${result}`, { step: { action: outcome } });
-      await this.endThreadOf(proposalId, actor.name, outcome);
-      return decision;
-    });
+    }
+    const verdict = outcome === "approved" ? "Approved" : "Rejected";
+    const why = reason === void 0 ? "" : ` Reason: ${reason}.`;
+    const result = provision === void 0 ? "" : ` Provisioned: ${Object.entries(provision).map(([key, value]) => `${key} ${plain(value)}`).join(", ")}.`;
+    const thread = await this.proposalThreadUnlocked(actor.name, proposal);
+    const post = `${verdict}: ${describeCharter(proposal.kind, proposal.charter)}.${why}${result}`;
+    await this.appendThreadMessage(actor.name, thread.id, actor.name === SYSTEM_ACTOR.name ? withoutMentions(post) : post, { step: { action: outcome } });
+    await this.endThreadOf(proposalId, actor.name, outcome);
+    return decision;
   }
   /** The opener, the people of its subject, and anyone who posted in it; mentions reach the rest. */
   async participatesInThread(actor, thread, threads) {
@@ -9336,7 +9633,8 @@ var TURN_CONTRACT = [
   "- An @mention wakes the citizen named, and every wake costs a turn. Address someone with @ only when you need them to act; when you merely refer to citizens, write their names plainly. @user wakes nobody, since the user takes no turns; it is what puts a question before the user, so use it only when you need the user to answer or decide.",
   "- A thread is a conversation off a channel that reaches only its participants and whoever is mentioned in it. Every task has one, opened with it under the task's id on the channel of its project it was filed in, general unless it was filed in another: talk about a task there, with post_message and its thread_id, and the notes you give advance_task and update_task are posted there as you. Its participants are the task's creator, its stage holders and assignees, whoever may take the stage that waits, and anyone who posted; it closes when the task ends. Every proposal has one too, in governance, opened with its pitch and closed by its decision. Open other threads with open_thread on a channel with a title, for any other topic; close_thread posts your summary to its channel.",
   "- Route every lesson: about you, your craft, or the user, write it to memory/core.md in your home directory, and keep that file short by moving detail to memory/<topic>.md, your archive; a durable fact about a project's codebase or process goes through `write_knowledge` on that project; something the whole project should know now, post it to the project channel, and anything about one task, in the task's thread.",
-  '- A procedure you have followed twice is a skill: write it to skills/<name>/SKILL.md in your home, frontmatter with `name` and a one-line `description` and then the steps, and your skills index lists it from the next turn. Propose it with kind "skill" when the whole society would use it.',
+  '- A procedure you have followed twice is a skill: write it to skills/<name>/SKILL.md in your home, frontmatter with `name` and a one-line `description` and then the steps, and your skills index lists it from the next turn. Files the steps use, such as scripts/ and references/, go in the same folder, named in SKILL.md by paths relative to it. Propose it with kind "skill" when the whole society would use it.',
+  "- To take a published skill for yourself, install it in a temporary folder and copy it into your home: in a folder from `mktemp -d`, `npx -y skills add <source> --skill <name> -a universal --copy -y` writes `.agents/skills/<name>/` and a lock file there, and you copy that skill folder to skills/<name>/ in your home, named in lowercase letters, digits, and hyphens. Never install one inside a worktree, where it would be committed into the project, or with -g, which writes to the runner's own home, shared by every citizen on it and listed in no skills index.",
   "- Report memoryUpdated: true in the status object whenever you changed memory/core.md or a skill, so a warm session restarts with the new instructions.",
   "- Other turns of yours may be running at the same time and share your home. Change a file there with your edit tool, which refuses a file changed since you read it, and never rewrite one whole from an earlier read, with a shell redirect or a script, or you erase what another of your turns wrote.",
   "- To ask the user something, mention @user where the question belongs: the task's thread for a task, the proposal's thread for a proposal, and for anything else a thread you open on your scope's general channel, titled with the question. The user answers in the same thread, and the answer comes back to that thread's conversation. A proposal waiting on the user is already in front of them and needs no mention.",
@@ -9359,7 +9657,7 @@ var GOVERNANCE = [
   '  - retirement: {"agent", "reason"}',
   '  - archive: {"project", "reason"}: approval archives the project: its members leave, its open threads close, and nothing more is posted, filed, or joined there, while its files and history stay; refused while a task there is in play',
   '  - reallocation: {"description"}',
-  '  - skill: {"name", "summary", "body"}: the SKILL.md text; approval publishes it under society/skills, where every citizen\'s skills index lists it until the steward or the user removes it with `remove_skill`; ask the steward to remove one that is wrong or superseded',
+  '  - skill: {"name", "summary"}: the folder skills/<name>/ in your home, SKILL.md and every file beside it, which the board takes as it stands when this turn ends into society/proposals/<id>/, where whoever decides reads it; a proposal whose folder has no SKILL.md then is rejected by the board. Approval publishes it under society/skills/<name>/, where every citizen\'s skills index lists it until the steward or the user removes it with `remove_skill`; ask the steward to remove one that is wrong or superseded. A proposal from before folders carries "body", its SKILL.md text alone',
   "- Projects and membership: a project is a lasting area of work, not one request; `create_project` opens one with its general channel (front desk and user), and `configure_project` sets its completion effect, its display name, or its default branch, never its slug (user, steward, concierge). A workstream within a project or the society, such as a release, gets a channel of its own: `create_channel` opens it, which its opener follows, and announces it in the place's general, where members subscribe when it concerns them, `create_task` with `channel` files the workstream's tasks there, and `archive_channel` ends it once none of its tasks is in play, leaving its history readable (user, steward, concierge; others propose a channel). A project whose work is finished or has moved to another project is archived by proposal, once no task there is in play. `join_project` and `leave_project` move yourself, or another citizen when you are the concierge, the steward, or the user; joining gives the pair a worktree and an onboarding turn. A society role, one that keeps watch over the whole society as the concierge and the steward do, is never in a project: it moves others, never itself.",
   "- Prefer scaling an existing role over inventing one; a new role is justified by work a project needs that no existing role covers. A role that needs a tool the board lacks is an engineering task, not a hiring request.",
   "- Operations signals are counters and timers the board logs, listed in the prompt of a role that reads them: stages waiting for a holder, backlog per role, stages waiting on a role nobody fills, churn, stale threads, idle members, missing capabilities, replicas added, spend. They are not posts in any channel; interpreting them is your judgment."
@@ -9387,7 +9685,7 @@ function renderSkillsIndex(skills) {
     ];
   }
   return [
-    "Read a skill's file when its summary matches the work at hand; do not load them all.",
+    "Read a skill's file when its summary matches the work at hand; do not load them all. Paths in it are relative to its folder, which holds whatever else it uses.",
     "",
     ...skills.map((skill) => `- ${skill.name} (${skill.scope === "own" ? "yours" : "society"}): ${skill.summary.trim().length === 0 ? "no summary" : skill.summary.trim().replace(/\.+$/, "")}. File: ${skill.path}`)
   ];
@@ -9412,7 +9710,7 @@ var REFLECTION_INTRO = "This turn is for your memory; take no new work, and answ
 var RECONCILE = "- Reconcile first: merge each copy listed under Edits to reconcile in your home into the file beside it, then delete the copy.";
 var REFLECTION_STEPS = [
   "- Consolidate memory/core.md: keep it to lessons that still hold, about sixty lines at most, and move detail worth keeping to memory/<topic>.md in your home, which the board's search covers for you alone.",
-  '- Extract a skill: a procedure you have followed twice goes to skills/<name>/SKILL.md, frontmatter with `name` and a one-line `description` and then the steps. Propose it with kind "skill" when other citizens would use it.',
+  '- Extract a skill: a procedure you have followed twice goes to skills/<name>/SKILL.md, frontmatter with `name` and a one-line `description` and then the steps, with any script or reference it uses in the same folder. Propose it with kind "skill" when other citizens would use it.',
   "- Refresh profile.md: one paragraph on what you do well and what to send your way; the roster the front desk routes with is built from it.",
   "- Share: a durable fact about this scope's codebase or process goes through write_knowledge; a norm the whole society should follow goes to the steward as a plain post in general.",
   "- Report memoryUpdated: true in the status object when core.md or a skill changed."
@@ -9627,7 +9925,7 @@ function buildTurnPrompt(input) {
     } else {
       lines.push(`Topics under ${knowledge.dir}; open one with your file tools when it is relevant.`, "");
       for (const topic of knowledge.topics) {
-        lines.push(`- ${topic.topic}: updated by ${topic.updatedBy} at ${topic.updatedAt}`);
+        lines.push(`- ${topic.topic}: revision ${topic.revision}, updated by ${topic.updatedBy} at ${topic.updatedAt}`);
       }
     }
   }
@@ -10157,6 +10455,7 @@ var TurnHost = class {
         channel: job.channel,
         exitReason: finished.exitReason
       }, "turn finished");
+      await this.takeSkillFiles(finished);
       turn.done(finished);
     }
     return { dropWorkspace: ended && (closing ? decided : !outcome.leftovers) };
@@ -10181,9 +10480,21 @@ var TurnHost = class {
     };
     if (await this.recorded(turn, () => this.board.finishTurn(finished, turn.transcript))) {
       this.log.warn({ agent: turn.job.agent, project: turn.job.scope, reason }, "turn aborted");
+      await this.takeSkillFiles(finished);
       turn.done(finished);
     }
   }
+  /**
+   * Takes the folders of the skills the turn proposed, which reached the board with the home its
+   * runner pushed before reporting. A failure only leaves them for approval to take.
+   */
+  async takeSkillFiles(record) {
+    try {
+      await this.board.takeSkillFiles(record);
+    } catch (error) {
+      this.log.warn({ agent: record.agent, project: record.project, error: String(error) }, "could not take the folders of the skills a turn proposed");
+    }
+  }
   /**
    * Records the end of a turn already taken out of `open`, and says whether it could. The scheduler
    * holds the turn's conversation until the turn ends, and nothing would end it once it has left
@@ -11743,6 +12054,7 @@ function createApp(deps) {
   api.get("/proposals", async (c) => c.json(await board2.listProposals()));
   api.get("/crons", async (c) => c.json(await board2.listCrons()));
   api.get("/proposals/:id", async (c) => c.json(await board2.readProposal(c.req.param("id"))));
+  api.get("/proposals/:id/files", async (c) => c.json(await board2.readSkillFiles(UlidSchema.parse(c.req.param("id")))));
   api.get("/signals", async (c) => c.json(await board2.listSignals(Number(c.req.query("limit") ?? "100"))));
   api.get("/metrics", async (c) => {
     const window = MetricsWindowSchema.parse(c.req.query("window") ?? "7d");