paseo-room 0.4.0 → 0.5.0

package/dist/index.js

@@ -15,7 +15,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "paseo-room",
-      version: "0.4.0",
+      version: "0.5.0",
       description: "One CLI that configures Codex, Claude Code, and Pi role homes in $HOME and registers them with your local Paseo daemon.",
       keywords: [
         "paseo",
@@ -49,7 +49,7 @@ var init_package = __esm({
         lint: "eslint . --max-warnings 0",
         test: "vitest run",
         "test:package": "vitest run --config vitest.package.config.ts",
-        build: `tsup && node --input-type=module -e "import { cpSync, rmSync } from 'node:fs'; for (const [source, target] of [['src/room/prompts', 'dist/prompts'], ['src/plugin-assets', 'dist/plugin-assets']]) { rmSync(target, { recursive: true, force: true }); cpSync(source, target, { recursive: true }); }"`,
+        build: `tsup && node --input-type=module -e "import { cpSync, rmSync } from 'node:fs'; for (const [source, target] of [['src/room/prompts', 'dist/prompts'], ['src/room/skills', 'dist/skills'], ['src/plugin-assets', 'dist/plugin-assets']]) { rmSync(target, { recursive: true, force: true }); cpSync(source, target, { recursive: true }); }"`,
         prepack: "npm run build",
         verify: "npm run typecheck && npm run lint && npm test && npm run build && npm run test:package"
       },
@@ -158,12 +158,6 @@ function preservedCredentialCheck(input) {
 function presentNames(names, supported) {
   return supported.filter((name) => names.has(name));
 }
-function configuredByNamesCheck(id, agent, role, names) {
-  return warn(
-    `${id}.configured-structurally`,
-    `${agent} ${role} auth: configured structurally; ${names.join(", ")} ${names.length === 1 ? "is" : "are"} present by name. Values, token validity, and freshness were not checked.`
-  );
-}
 function ambientNamesCheck(id, agent, role, names) {
   return warn(
     `${id}.ambient-auth-unverifiable`,
@@ -270,7 +264,7 @@ async function lstatOrAbsent(path) {
   }
 }
 async function staleChildren(entry) {
-  const declared = new Set(entry.children);
+  const declared = /* @__PURE__ */ new Set([...entry.children, ...entry.reserved ?? []]);
   let names;
   try {
     names = await readdir(entry.path);
@@ -765,18 +759,11 @@ function validateHeadOrCapsule(source, kind) {
   }
   return trimmed;
 }
-function validateSection(source) {
-  const trimmed = source.trimEnd();
-  if (!trimmed.trim()) throw new Error("is empty.");
-  const lines = trimmed.split("\n");
-  const heading = lines.shift() ?? "";
-  if (!/^## \S.*$/.test(heading) || headingCount(trimmed, 2) !== 1) {
-    throw new Error("section must begin with exactly one H2 heading.");
-  }
-  if (lines.some((line) => /^#{1,6}\s/.test(line))) {
+function renderSection(heading, bodyLines) {
+  if (bodyLines.some((line) => /^#{1,6}\s/.test(line))) {
     throw new Error("section must not contain additional Markdown headings.");
   }
-  const body = lines.join("\n").trim();
+  const body = bodyLines.join("\n").trim();
   if (!body) throw new Error("section must contain at least one non-empty statement.");
   const statements = body.split(/\n\s*\n/).map(
     (statement) => statement.split("\n").map((line) => line.trim()).join(" ")
@@ -787,6 +774,40 @@ function validateSection(source) {
   return `${heading}
 ${statements.map((statement) => `- ${statement}`).join("\n")}`;
 }
+function validateSection(source) {
+  const trimmed = source.trimEnd();
+  if (!trimmed.trim()) throw new Error("is empty.");
+  const lines = trimmed.split("\n");
+  const heading = lines.shift() ?? "";
+  if (!/^## \S.*$/.test(heading) || headingCount(trimmed, 2) !== 1) {
+    throw new Error("section must begin with exactly one H2 heading.");
+  }
+  return renderSection(heading, lines);
+}
+function splitSections(lines) {
+  const preface = [];
+  const sections = [];
+  for (const line of lines) {
+    if (/^## \S.*$/.test(line)) {
+      sections.push({ heading: line, lines: [] });
+      continue;
+    }
+    const current2 = sections.at(-1);
+    if (current2 === void 0) preface.push(line);
+    else current2.lines.push(line);
+  }
+  return { preface, sections };
+}
+function validateBody(source) {
+  const trimmed = source.trimEnd();
+  if (!trimmed.trim()) throw new Error("is empty.");
+  const { preface, sections } = splitSections(trimmed.split("\n"));
+  if (sections.length === 0) throw new Error("role body must contain at least one H2 section.");
+  if (preface.some((line) => line.trim())) {
+    throw new Error("role body must not contain content above its first H2 heading.");
+  }
+  return sections.map((section) => renderSection(section.heading, section.lines)).join("\n\n");
+}
 function loadPromptAsset(group, key) {
   const logicalAsset = `${group}.${String(key)}`;
   const cached = cache.get(logicalAsset);
@@ -796,7 +817,7 @@ function loadPromptAsset(group, key) {
   try {
     const source = readFileSync(assetUrl, "utf8");
     if (source.includes("\uFFFD")) throw new Error("is not valid UTF-8 text.");
-    const validated = asset.kind === "section" ? validateSection(source) : validateHeadOrCapsule(source, asset.kind);
+    const validated = validate(source, asset.kind);
     cache.set(logicalAsset, validated);
     return validated;
   } catch (error) {
@@ -805,6 +826,16 @@ function loadPromptAsset(group, key) {
     throw new PromptAssetError(logicalAsset, assetUrl, detail, { cause: error });
   }
 }
+function validate(source, kind) {
+  switch (kind) {
+    case "section":
+      return validateSection(source);
+    case "body":
+      return validateBody(source);
+    default:
+      return validateHeadOrCapsule(source, kind);
+  }
+}
 var PROMPT_ASSETS, PromptAssetError, cache;
 var init_prompts = __esm({
   "src/room/prompts.ts"() {
@@ -813,38 +844,15 @@ var init_prompts = __esm({
       documents: {
         supervisor: { path: "documents/supervisor.md", kind: "head" },
         lead: { path: "documents/lead.md", kind: "head" },
-        peer: { path: "documents/peer.md", kind: "head" },
-        workspace: { path: "documents/workspace.md", kind: "head" }
+        peer: { path: "documents/peer.md", kind: "head" }
       },
       contract: {
-        humanAuthority: { path: "contract/shared/human-authority.md", kind: "section" },
-        workspaceProtocolPrecedence: { path: "contract/shared-supervisor-lead/workspace-protocol-precedence.md", kind: "section" },
-        evidenceAndEventWaiting: { path: "contract/shared/evidence-and-event-waiting.md", kind: "section" },
-        scopeAndUnrelatedWork: { path: "contract/shared/scope-and-unrelated-work.md", kind: "section" },
-        directiveIntegrity: { path: "contract/supervisor/directive-integrity.md", kind: "section" },
-        technicalNonInterference: { path: "contract/supervisor/technical-non-interference.md", kind: "section" },
-        leadDiscoveryAndRecovery: { path: "contract/supervisor/lead-discovery-and-recovery.md", kind: "section" },
-        observationAndAdvice: { path: "contract/supervisor/observation-and-advice.md", kind: "section" },
-        escalationBoundaries: { path: "contract/supervisor/escalation-boundaries.md", kind: "section" },
-        projectTechnicalOwnership: { path: "contract/lead/project-technical-ownership.md", kind: "section" },
-        movingWriteOwnership: { path: "contract/lead/moving-write-ownership.md", kind: "section" },
-        completePeerBrief: { path: "contract/lead/complete-peer-brief.md", kind: "section" },
-        challengeSignals: { path: "contract/shared-lead-peer/challenge-signals.md", kind: "section" },
-        technicalAcceptance: { path: "contract/lead/technical-acceptance.md", kind: "section" },
-        independentReview: { path: "contract/lead/independent-review.md", kind: "section" },
-        peerSeatLifecycle: { path: "contract/lead/peer-seat-lifecycle.md", kind: "section" },
-        boundedOutcome: { path: "contract/peer/bounded-outcome.md", kind: "section" },
-        independentJudgment: { path: "contract/peer/independent-judgment.md", kind: "section" },
-        assignmentScope: { path: "contract/peer/assignment-scope.md", kind: "section" },
-        noOrchestration: { path: "contract/peer/no-orchestration.md", kind: "section" },
-        reproducibleHandoff: { path: "contract/peer/reproducible-handoff.md", kind: "section" },
-        noSelfAcceptance: { path: "contract/peer/no-self-acceptance.md", kind: "section" }
-      },
-      workspace: {
-        topology: { path: "workspace/topology.md", kind: "section" },
-        verification: { path: "workspace/verification.md", kind: "section" },
-        review: { path: "workspace/review.md", kind: "section" },
-        repositoryConventions: { path: "workspace/repository-conventions.md", kind: "section" }
+        sharedAuthority: { path: "contract/shared-authority.md", kind: "body" },
+        sharedSeatIdentity: { path: "contract/shared-seat-identity.md", kind: "section" },
+        challengeSignals: { path: "contract/challenge-signals.md", kind: "section" },
+        supervisor: { path: "contract/supervisor.md", kind: "body" },
+        lead: { path: "contract/lead.md", kind: "body" },
+        peer: { path: "contract/peer.md", kind: "body" }
       },
       pi: {
         communicationStyle: { path: "pi/communication-style.md", kind: "capsule" },
@@ -868,24 +876,12 @@ var init_prompts = __esm({
 // src/room/instructions.ts
 import { createHash } from "crypto";
 function instructionKeys(role) {
-  return [...SHARED_KEYS[role], ...ROLE_KEYS[role]];
-}
-function protocolKeys(role) {
-  return PROTOCOL_KEYS[role];
-}
-function protocol(keys) {
-  if (keys.length === 0) return [];
-  return [
-    loadPromptAsset("documents", "workspace"),
-    ...keys.map((key) => loadPromptAsset("workspace", key))
-  ];
+  return [...SHARED_KEYS[role], ROLE_KEYS[role]];
 }
 function renderInstructions(kind) {
-  if (kind === "workspace") return protocol(ALL_PROTOCOL_KEYS).join("\n\n") + "\n";
   return [
     loadPromptAsset("documents", kind),
-    ...instructionKeys(kind).map((key) => loadPromptAsset("contract", key)),
-    ...protocol(protocolKeys(kind))
+    ...instructionKeys(kind).map((key) => loadPromptAsset("contract", key))
   ].join("\n\n") + "\n";
 }
 function contractDigest() {
@@ -893,68 +889,23 @@ function contractDigest() {
   for (const kind of INSTRUCTION_KINDS) hash.update(`${kind}\0${renderInstructions(kind)}\0`);
   return `sha256:${hash.digest("hex").slice(0, 16)}`;
 }
-var AUTHORITY_KEYS, PROTOCOL_READER_KEYS, SHARED_KEYS, ROLE_KEYS, ALL_PROTOCOL_KEYS, PROTOCOL_KEYS, INSTRUCTION_KINDS;
+var SHARED_KEYS, ROLE_KEYS, INSTRUCTION_KINDS;
 var init_instructions = __esm({
   "src/room/instructions.ts"() {
     "use strict";
     init_roles();
     init_prompts();
-    AUTHORITY_KEYS = [
-      "humanAuthority",
-      "evidenceAndEventWaiting",
-      "scopeAndUnrelatedWork"
-    ];
-    PROTOCOL_READER_KEYS = [
-      "humanAuthority",
-      "workspaceProtocolPrecedence",
-      "evidenceAndEventWaiting",
-      "scopeAndUnrelatedWork"
-    ];
     SHARED_KEYS = {
-      supervisor: PROTOCOL_READER_KEYS,
-      lead: PROTOCOL_READER_KEYS,
-      peer: AUTHORITY_KEYS
+      supervisor: ["sharedAuthority", "sharedSeatIdentity"],
+      lead: ["sharedAuthority", "sharedSeatIdentity", "challengeSignals"],
+      peer: ["sharedAuthority", "challengeSignals"]
     };
     ROLE_KEYS = {
-      supervisor: [
-        "directiveIntegrity",
-        "technicalNonInterference",
-        "leadDiscoveryAndRecovery",
-        "observationAndAdvice",
-        "escalationBoundaries"
-      ],
-      lead: [
-        "projectTechnicalOwnership",
-        "movingWriteOwnership",
-        "completePeerBrief",
-        "challengeSignals",
-        "technicalAcceptance",
-        "independentReview",
-        "peerSeatLifecycle"
-      ],
-      // Peer needs Challenge Signals as well as its own obligations.
-      peer: [
-        "challengeSignals",
-        "boundedOutcome",
-        "independentJudgment",
-        "assignmentScope",
-        "noOrchestration",
-        "reproducibleHandoff",
-        "noSelfAcceptance"
-      ]
-    };
-    ALL_PROTOCOL_KEYS = [
-      "topology",
-      "verification",
-      "review",
-      "repositoryConventions"
-    ];
-    PROTOCOL_KEYS = {
-      supervisor: ALL_PROTOCOL_KEYS,
-      lead: ALL_PROTOCOL_KEYS,
-      peer: []
+      supervisor: "supervisor",
+      lead: "lead",
+      peer: "peer"
     };
-    INSTRUCTION_KINDS = [...ROLES, "workspace"];
+    INSTRUCTION_KINDS = [...ROLES];
   }
 });
 
@@ -1040,30 +991,55 @@ function isPaseoSkill(name) {
 function receivesExecutableResources(role) {
   return role !== "peer";
 }
-async function skillNames(path) {
+function receivesRoomSkill(role) {
+  return role === "lead";
+}
+async function skillNames(path, reserved, keep) {
   try {
-    return (await readdir2(path)).filter((name) => !isPaseoSkill(name)).sort();
+    return (await readdir2(path)).filter((name) => keep(name) && !reserved.has(name.toLowerCase())).sort();
   } catch (error) {
     if (error !== null && typeof error === "object" && "code" in error && error.code === "ENOENT") return [];
     throw error;
   }
 }
+async function skillsProjection(input, path, alias, present, reserved) {
+  const roomSkill = receivesRoomSkill(input.role) ? input.roomSkill : void 0;
+  const projectsChildren = !receivesExecutableResources(input.role) || roomSkill !== void 0;
+  if (!projectsChildren) return void 0;
+  const reservedNames = new Set([...reserved].map((name) => name.toLowerCase()));
+  const keep = roomSkill === void 0 ? (name) => !isPaseoSkill(name) : (name) => name.toLowerCase() !== roomSkill.name.toLowerCase();
+  const operator = present.has(path) ? await skillNames(path, reservedNames, keep) : [];
+  const children = roomSkill === void 0 ? operator : [...operator, roomSkill.name];
+  const projection = input.role === "lead" ? input.leadSkillProjection : alias;
+  return [
+    {
+      kind: "managed-dir",
+      path: projection,
+      children,
+      ...input.role === "peer" ? { legacyLink: path } : {},
+      ...reserved.size === 0 ? {} : { reserved: [...reserved] }
+    },
+    ...operator.map((child) => ({ kind: "link", path: join6(projection, child), target: join6(path, child) })),
+    ...roomSkill === void 0 ? [] : [{ kind: "link", path: join6(projection, roomSkill.name), target: roomSkill.source }],
+    ...input.role === "lead" ? [{ kind: "link", path: alias, target: projection }] : []
+  ];
+}
 async function roleResourceEntries(input) {
   const present = new Set(input.shared);
   const executable = new Set(input.executable);
+  const reserved = new Set(input.reservedSkills ?? []);
   const entries = [];
   for (const name of input.names) {
     const path = join6(input.home, name);
     const alias = join6(input.target, name);
-    if (!receivesExecutableResources(input.role)) {
-      if (executable.has(name)) continue;
-      if (name === SKILLS) {
-        const children = present.has(path) ? await skillNames(path) : [];
-        entries.push({ kind: "managed-dir", path: alias, children, legacyLink: path });
-        for (const child of children) entries.push({ kind: "link", path: join6(alias, child), target: join6(path, child) });
+    if (name === SKILLS) {
+      const projection = await skillsProjection(input, path, alias, present, reserved);
+      if (projection !== void 0) {
+        entries.push(...projection);
         continue;
       }
     }
+    if (!receivesExecutableResources(input.role) && executable.has(name)) continue;
     if (!present.has(path)) continue;
     entries.push({ kind: "link", path: alias, target: path });
   }
@@ -1077,9 +1053,99 @@ var init_resources = __esm({
   }
 });
 
+// src/room/skills.ts
+import { readFileSync as readFileSync2 } from "fs";
+import { join as join7 } from "path";
+function validateSkillAsset(path, source) {
+  if (source.includes("\uFFFD")) throw new Error("is not valid UTF-8 text.");
+  if (!source.trim()) throw new Error("is empty.");
+  if (path === "SKILL.md") {
+    const frontmatter = /^---\n([\s\S]*?)\n---\n/.exec(source)?.[1];
+    if (frontmatter === void 0) throw new Error("must begin with YAML frontmatter.");
+    const declaredName = /^name: (.+)$/m.exec(frontmatter)?.[1];
+    if (declaredName !== ROOM_SKILL_NAME) {
+      throw new Error(`frontmatter name must be ${ROOM_SKILL_NAME}.`);
+    }
+    if (!/^description: \S.+$/m.test(frontmatter)) {
+      throw new Error("frontmatter must contain a non-empty single-line description.");
+    }
+  }
+  if (path === "references/workspace-protocol-template.md" && !source.startsWith("# Workspace protocol template (scaffold)\n")) {
+    throw new Error("must begin with the workspace protocol scaffold heading.");
+  }
+  return source;
+}
+function loadSkillAsset(path) {
+  const cached = cache2.get(path);
+  if (cached !== void 0) return cached;
+  const logicalAsset = `${ROOM_SKILL_NAME}/${path}`;
+  const assetUrl = new URL(`./skills/${ROOM_SKILL_NAME}/${path}`, import.meta.url);
+  try {
+    const validated = validateSkillAsset(path, readFileSync2(assetUrl, "utf8"));
+    cache2.set(path, validated);
+    return validated;
+  } catch (error) {
+    if (error instanceof SkillAssetError) throw error;
+    const detail = error instanceof Error ? error.message : "could not be read.";
+    throw new SkillAssetError(logicalAsset, assetUrl, detail, { cause: error });
+  }
+}
+function roomSkillSource(layout) {
+  return join7(sharedRoom(layout), "skills", ROOM_SKILL_NAME);
+}
+function skillProjectionRoot(layout) {
+  return join7(sharedRoom(layout), "skill-projections");
+}
+function agentSkillProjectionRoot(layout, agent) {
+  return join7(skillProjectionRoot(layout), agent);
+}
+function leadSkillProjection(layout, agent) {
+  return join7(agentSkillProjectionRoot(layout, agent), "lead");
+}
+function roomSkillEntries(layout, agents) {
+  const root = roomSkillSource(layout);
+  return [
+    { kind: "dir", path: join7(sharedRoom(layout), "skills") },
+    { kind: "dir", path: skillProjectionRoot(layout) },
+    ...agents.map((agent) => ({ kind: "dir", path: agentSkillProjectionRoot(layout, agent) })),
+    { kind: "managed-dir", path: root, children: ["SKILL.md", ...SKILL_DIRECTORIES] },
+    {
+      kind: "managed-dir",
+      path: join7(root, "references"),
+      children: SKILL_FILES.filter((path) => path.startsWith("references/")).map((path) => path.slice("references/".length))
+    },
+    ...SKILL_FILES.map((path) => ({
+      kind: "file",
+      path: join7(root, path),
+      content: loadSkillAsset(path)
+    }))
+  ];
+}
+var ROOM_SKILL_NAME, SKILL_DIRECTORIES, SKILL_FILES, SkillAssetError, cache2;
+var init_skills = __esm({
+  "src/room/skills.ts"() {
+    "use strict";
+    init_layout();
+    ROOM_SKILL_NAME = "paseo-project-onboarding";
+    SKILL_DIRECTORIES = ["references"];
+    SKILL_FILES = ["SKILL.md", "references/workspace-protocol-template.md"];
+    SkillAssetError = class extends Error {
+      logicalAsset;
+      assetUrl;
+      constructor(logicalAsset, assetUrl, detail, options) {
+        super(`Skill asset ${logicalAsset} at ${assetUrl.pathname} ${detail} Reinstall paseo-room and try again.`, options);
+        this.name = "SkillAssetError";
+        this.logicalAsset = logicalAsset;
+        this.assetUrl = assetUrl;
+      }
+    };
+    cache2 = /* @__PURE__ */ new Map();
+  }
+});
+
 // src/agents/claude.ts
 import { readFile as readFile2 } from "fs/promises";
-import { join as join7 } from "path";
+import { join as join8 } from "path";
 function asObject(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? { ...value } : {};
 }
@@ -1098,17 +1164,21 @@ async function readStateIfPresent(path) {
     throw error;
   }
 }
-function renderRoleSettings(source, role, secureStorageDir) {
-  const settings = readObject(source);
-  settings.env = {
-    ...asObject(settings.env),
-    ...CONTROL_PLANE_ENV,
-    PASEO_ROOM_ROLE: role,
-    ...secureStorageDir === void 0 ? {} : { [SECURE_STORAGE_ENV]: secureStorageDir }
+function renderRoleSettings(role, secureStorageDir) {
+  const settings = {
+    // Claude applies settings.env after the launch environment, so repeat provider closures here.
+    env: {
+      ...CONTROL_PLANE_ENV,
+      PASEO_ROOM_ROLE: role,
+      ...secureStorageDir === void 0 ? {} : { [SECURE_STORAGE_ENV]: secureStorageDir }
+    },
+    // Provider disallowedTools is not sufficient alone; the isolated home carries the same list.
+    permissions: { deny: DISALLOWED_TOOLS },
+    // These restrictive settings cannot be weakened by another settings scope.
+    disableAgentView: true,
+    disableWorkflows: true,
+    crossSessionInbound: "refuse"
   };
-  settings.disableAgentView = true;
-  settings.disableWorkflows = true;
-  settings.crossSessionInbound = "refuse";
   return JSON.stringify(settings, null, 2) + "\n";
 }
 function renderRoleState(source) {
@@ -1125,17 +1195,9 @@ function renderRoleMemory(source, role, contract = true) {
 
 ${renderInstructions(role)}` : renderInstructions(role);
 }
-function claudeAuthMethodNames(settingsSource, envNames) {
-  const settings = readObject(settingsSource);
-  const settingsEnv = asObject(settings.env);
-  const names = new Set(presentNames(envNames, AUTH_ENV));
-  for (const name of AUTH_ENV) if (Object.hasOwn(settingsEnv, name)) names.add(name);
-  if (Object.hasOwn(settings, "apiKeyHelper")) names.add("apiKeyHelper");
-  return [...names];
-}
-async function claudeCredentialDiagnostic(layout, role, settingsSource, platform = process.platform, binary = "claude") {
+async function claudeCredentialDiagnostic(layout, role, platform = process.platform, binary = "claude") {
   const home = roleHome(layout, "claude", role);
-  const path = join7(home, ".credentials.json");
+  const path = join8(home, ".credentials.json");
   const roleEnvironment = { CLAUDE_CONFIG_DIR: home, [SECURE_STORAGE_ENV]: home };
   const login = roleCommand(roleEnvironment, binary, ["auth", "login"]);
   const status = roleCommand(roleEnvironment, binary, ["auth", "status"]);
@@ -1144,8 +1206,6 @@ async function claudeCredentialDiagnostic(layout, role, settingsSource, platform
   if (state.kind !== "missing") {
     return { path, checks: [preservedCredentialCheck({ id, agent: "Claude", role, path, state, login, status })] };
   }
-  const configured = claudeAuthMethodNames(settingsSource, /* @__PURE__ */ new Set());
-  if (configured.length > 0) return { path, checks: [configuredByNamesCheck(id, "Claude", role, configured)] };
   const ambient = presentNames(layout.envNames, AUTH_ENV);
   if (ambient.length > 0) return { path, checks: [ambientNamesCheck(id, "Claude", role, ambient)] };
   if (platform === "darwin") {
@@ -1159,7 +1219,7 @@ async function claudeCredentialDiagnostic(layout, role, settingsSource, platform
   return { path, checks: [{
     id: `${id}.login-required`,
     status: "warn",
-    message: `Claude ${role} auth: login-required; no role-owned .credentials.json or configured environment/static auth method was detected. Authentication was not attempted.`,
+    message: `Claude ${role} auth: login-required; no role-owned .credentials.json or supported ambient auth environment name was detected. Authentication was not attempted.`,
     fix: `Authenticate this role with: ${login}. If that subcommand is unavailable, launch ${roleCommand(roleEnvironment, binary)} and run /login. Check status with: ${status}.`
   }] };
 }
@@ -1174,7 +1234,7 @@ function mcpDriftCheck(role, home, path, divergence) {
     `If this role should have the same servers, add them with: CLAUDE_CONFIG_DIR=${home} claude mcp add ... \u2014 or delete ${path} and run setup --apply to reseed it from your current Claude state, which discards that role's other runtime state.`
   );
 }
-var SHARED, EXECUTABLE, MCP_KEY, AUTH_ENV, CONTROL_PLANE_ENV, SECURE_STORAGE_ENV, SEEDED_KEYS, claudeAgent;
+var SHARED, EXECUTABLE, RUNTIME_SKILLS, MCP_KEY, AUTH_ENV, CONTROL_PLANE_ENV, DISALLOWED_TOOLS, SECURE_STORAGE_ENV, SEEDED_KEYS, claudeAgent;
 var init_claude = __esm({
   "src/agents/claude.ts"() {
     "use strict";
@@ -1186,6 +1246,7 @@ var init_claude = __esm({
     init_which();
     init_mcp();
     init_resources();
+    init_skills();
     SHARED = [
       "skills",
       "plugins",
@@ -1197,6 +1258,7 @@ var init_claude = __esm({
       "themes"
     ];
     EXECUTABLE = ["plugins", "commands", "hooks"];
+    RUNTIME_SKILLS = ["synced"];
     MCP_KEY = "mcpServers";
     AUTH_ENV = [
       "ANTHROPIC_AUTH_TOKEN",
@@ -1210,6 +1272,22 @@ var init_claude = __esm({
       CLAUDE_CODE_DISABLE_AGENT_VIEW: "1",
       CLAUDE_CODE_DISABLE_WORKFLOWS: "1"
     };
+    DISALLOWED_TOOLS = [
+      "Task",
+      "Agent",
+      "Workflow",
+      "ListAgents",
+      "SendMessage",
+      "TeamCreate",
+      "TeamDelete",
+      "TaskCreate",
+      "TaskGet",
+      "TaskList",
+      "TaskUpdate",
+      "CronCreate",
+      "CronDelete",
+      "CronList"
+    ];
     SECURE_STORAGE_ENV = "CLAUDE_SECURESTORAGE_CONFIG_DIR";
     SEEDED_KEYS = ["hasCompletedOnboarding", "theme", "installMethod", "userID", MCP_KEY];
     claudeAgent = {
@@ -1222,24 +1300,7 @@ var init_claude = __esm({
       // Keep the legacy Task name and block current native orchestration,
       // shared task/cron coordination, and cross-session paths. Paseo alone owns
       // agent lifecycle and coordination.
-      pins: {
-        disallowedTools: [
-          "Task",
-          "Agent",
-          "Workflow",
-          "ListAgents",
-          "SendMessage",
-          "TeamCreate",
-          "TeamDelete",
-          "TaskCreate",
-          "TaskGet",
-          "TaskList",
-          "TaskUpdate",
-          "CronCreate",
-          "CronDelete",
-          "CronList"
-        ]
-      },
+      pins: { disallowedTools: DISALLOWED_TOOLS },
       async build(layout, roles, options = {}) {
         const home = layout.agentHome.claude;
         const binary = await which(layout.bin.claude, layout.searchPath);
@@ -1250,8 +1311,7 @@ var init_claude = __esm({
           return { entries: [], checks: [fail("claude.home", `No Claude config directory at ${home}.`, "Run claude once to initialise it, or pass --claude-home.")] };
         }
         const checks = [pass("claude.home", `Claude Code found at ${binary} using ${home}.`)];
-        const settingsSource = await readIfPresent(join7(home, "settings.json"));
-        const memorySource = await readIfPresent(join7(home, "CLAUDE.md"));
+        const memorySource = await readIfPresent(join8(home, "CLAUDE.md"));
         let stateSource;
         let operatorServers;
         try {
@@ -1271,9 +1331,10 @@ var init_claude = __esm({
         const credentials = [];
         const providerEnv = {};
         const drift = [];
+        const roomSkill = { name: ROOM_SKILL_NAME, source: roomSkillSource(layout) };
         for (const role of roles) {
           const target = roleHome(layout, "claude", role);
-          const statePath = join7(target, ".claude.json");
+          const statePath = join8(target, ".claude.json");
           let roleStateSource;
           let roleServers;
           try {
@@ -1293,13 +1354,23 @@ var init_claude = __esm({
             if (divergence) drift.push(mcpDriftCheck(role, target, statePath, divergence));
           }
           entries.push({ kind: "dir", path: target });
-          const memoryPath = join7(target, "CLAUDE.md");
+          const memoryPath = join8(target, "CLAUDE.md");
           const memory = renderRoleMemory(memorySource, role, options.memoryContract ?? true);
           entries.push(memory === void 0 ? { kind: "absent", path: memoryPath } : { kind: "file", path: memoryPath, content: memory });
-          entries.push({ kind: "file", path: join7(target, "settings.json"), content: renderRoleSettings(settingsSource, role, target) });
+          entries.push({ kind: "file", path: join8(target, "settings.json"), content: renderRoleSettings(role, target) });
           entries.push({ kind: "file", path: statePath, content: renderRoleState(stateSource), once: true });
-          entries.push(...await roleResourceEntries({ role, target, home, names: SHARED, shared, executable: EXECUTABLE }));
-          credentials.push(await claudeCredentialDiagnostic(layout, role, settingsSource, process.platform, binary));
+          entries.push(...await roleResourceEntries({
+            role,
+            target,
+            home,
+            names: SHARED,
+            shared,
+            executable: EXECUTABLE,
+            reservedSkills: RUNTIME_SKILLS,
+            roomSkill,
+            leadSkillProjection: leadSkillProjection(layout, "claude")
+          }));
+          credentials.push(await claudeCredentialDiagnostic(layout, role, process.platform, binary));
           providerEnv[role] = { [SECURE_STORAGE_ENV]: target };
         }
         return { entries, credentials, checks: [...checks, ...drift], binary, providerEnv };
@@ -1309,7 +1380,7 @@ var init_claude = __esm({
 });
 
 // src/agents/codex.ts
-import { join as join8 } from "path";
+import { join as join9 } from "path";
 import { parse, stringify } from "smol-toml";
 function table(parent, key) {
   const value = parent[key];
@@ -1366,7 +1437,7 @@ function codexCredentialStore(config) {
 }
 async function credentialDiagnostic(layout, role, store, binary) {
   const home = roleHome(layout, "codex", role);
-  const path = join8(home, "auth.json");
+  const path = join9(home, "auth.json");
   const login = roleCommand({ CODEX_HOME: home }, binary, ["login"]);
   const status = roleCommand({ CODEX_HOME: home }, binary, ["login", "status"]);
   const state = await inspectCredentialPath(path);
@@ -1415,6 +1486,7 @@ var init_codex = __esm({
     init_which();
     init_mcp();
     init_resources();
+    init_skills();
     SHARED2 = ["AGENTS.md", "skills", "plugins", "hooks.json"];
     EXECUTABLE2 = ["plugins", "hooks.json"];
     CATALOG = "model-catalog.json";
@@ -1433,7 +1505,7 @@ var init_codex = __esm({
         if (!binary) {
           return { entries: [], checks: [fail("codex.bin", "Codex executable not found.", "Install Codex, or pass --codex-bin /path/to/codex.")] };
         }
-        const configPath = join8(home, "config.toml");
+        const configPath = join9(home, "config.toml");
         const raw = await readIfPresent(configPath);
         if (raw === void 0) {
           return { entries: [], checks: [fail("codex.home", `No config.toml in ${home}.`, "Run codex once to initialise it, or pass --codex-home.")] };
@@ -1481,19 +1553,29 @@ var init_codex = __esm({
         }
         checks.push(pass("codex.catalog", evidence2.markers === 0 ? `Codex model catalog captured from ${capture}; it declared no multi_agent_version field, and each role home gets that generated copy instead of Codex's built-in catalog.` : `Codex model catalog captured from ${capture}; ${String(evidence2.markers)} multi_agent_version field(s) are nulled in the generated copy in each role home.`));
         const shared = await existingPaths(home, SHARED2);
+        const roomSkill = { name: ROOM_SKILL_NAME, source: roomSkillSource(layout) };
         for (const role of roles) {
           const target = roleHome(layout, "codex", role);
-          const catalogPath = join8(target, CATALOG);
+          const catalogPath = join9(target, CATALOG);
           const roleDocument = renderInstructions(role);
           entries.push({ kind: "dir", path: target });
-          entries.push({ kind: "file", path: join8(target, "role-instructions.md"), content: roleDocument });
+          entries.push({ kind: "file", path: join9(target, "role-instructions.md"), content: roleDocument });
           entries.push({
             kind: "file",
-            path: join8(target, "config.toml"),
+            path: join9(target, "config.toml"),
             content: renderRoleConfig(source, { roleDocument, catalogPath })
           });
           entries.push({ kind: "file", path: catalogPath, content: catalogSource });
-          entries.push(...await roleResourceEntries({ role, target, home, names: SHARED2, shared, executable: EXECUTABLE2 }));
+          entries.push(...await roleResourceEntries({
+            role,
+            target,
+            home,
+            names: SHARED2,
+            shared,
+            executable: EXECUTABLE2,
+            roomSkill,
+            leadSkillProjection: leadSkillProjection(layout, "codex")
+          }));
           credentials.push(await credentialDiagnostic(layout, role, store, binary));
         }
         return { entries, credentials, checks, binary };
@@ -1506,7 +1588,7 @@ var init_codex = __esm({
 import { spawn as spawn2 } from "child_process";
 import { mkdtemp, readFile as readFile3, realpath, rm as rm2, stat } from "fs/promises";
 import { tmpdir } from "os";
-import { isAbsolute as isAbsolute2, join as join9, resolve as resolve3 } from "path";
+import { isAbsolute as isAbsolute2, join as join10, resolve as resolve3 } from "path";
 function asObject2(value) {
   return value !== null && typeof value === "object" && !Array.isArray(value) ? { ...value } : void 0;
 }
@@ -1530,12 +1612,12 @@ function adapterFailure(home, detail) {
   return fail(
     "pi.adapter",
     detail,
-    `Install ${PACKAGE_NAME} in ${join9(home, "npm")} with Pi yourself, then run setup again.`
+    `Install ${PACKAGE_NAME} in ${join10(home, "npm")} with Pi yourself, then run setup again.`
   );
 }
 async function resolvePiAdapter(home) {
-  const packageRoot = join9(home, "npm", "node_modules", PACKAGE_NAME);
-  const manifestPath = join9(packageRoot, "package.json");
+  const packageRoot = join10(home, "npm", "node_modules", PACKAGE_NAME);
+  const manifestPath = join10(packageRoot, "package.json");
   try {
     const [canonicalRoot, manifestStat, raw] = await Promise.all([
       realpath(packageRoot),
@@ -1643,7 +1725,7 @@ function runProbeProcess(executable, adapterEntry, env, options, cwd) {
   });
 }
 async function runProbe(executable, adapterEntry, env, options) {
-  const createdCwd = await mkdtemp(join9(tmpdir(), "paseo-room-pi-probe-"));
+  const createdCwd = await mkdtemp(join10(tmpdir(), "paseo-room-pi-probe-"));
   const cwd = await realpath(createdCwd);
   try {
     return await runProbeProcess(executable, adapterEntry, {
@@ -1720,7 +1802,7 @@ async function readPiOptional(path) {
 }
 async function piCredentialDiagnostic(layout, role, binary = "pi") {
   const home = roleHome(layout, "pi", role);
-  const path = join9(home, "auth.json");
+  const path = join10(home, "auth.json");
   const launch = piLoginCommand(home, binary);
   const state = await inspectCredentialPath(path);
   const id = `pi.auth.${role}`;
@@ -1760,6 +1842,7 @@ var init_pi = __esm({
     init_which();
     init_mcp();
     init_resources();
+    init_skills();
     PACKAGE_NAME = "pi-mcp-adapter";
     PROBE_ID = "paseo-room-pi-mcp-probe";
     PROBE_TIMEOUT_MS = 1e4;
@@ -1816,7 +1899,7 @@ var init_pi = __esm({
           PI_OFFLINE: "1"
         });
         if (capability.status === "fail") return { entries: [], checks: [resolved.check, capability] };
-        const settingsPath = join9(home, "settings.json");
+        const settingsPath = join10(home, "settings.json");
         let settings;
         try {
           settings = renderPiSettings(await readPiOptional(settingsPath));
@@ -1834,7 +1917,7 @@ var init_pi = __esm({
             ]
           };
         }
-        const operatorAppendPath = join9(home, "APPEND_SYSTEM.md");
+        const operatorAppendPath = join10(home, "APPEND_SYSTEM.md");
         let operatorAppend;
         try {
           operatorAppend = await readPiOptional(operatorAppendPath);
@@ -1853,7 +1936,7 @@ var init_pi = __esm({
           };
         }
         const shared = await existingPaths(home, SHARED3);
-        const mcpPath = join9(home, MCP_FILE);
+        const mcpPath = join10(home, MCP_FILE);
         let servers;
         try {
           servers = jsonServerTable(await readPiOptional(mcpPath), MCP_KEYS);
@@ -1876,13 +1959,23 @@ var init_pi = __esm({
         const entries = [];
         const credentials = [];
         const argv = {};
+        const roomSkill = { name: ROOM_SKILL_NAME, source: roomSkillSource(layout) };
         for (const role of roles) {
           const target = roleHome(layout, "pi", role);
-          const appendPath = join9(target, "APPEND_SYSTEM.md");
+          const appendPath = join10(target, "APPEND_SYSTEM.md");
           entries.push({ kind: "dir", path: target });
-          entries.push({ kind: "file", path: join9(target, "settings.json"), content: settings });
+          entries.push({ kind: "file", path: join10(target, "settings.json"), content: settings });
           entries.push({ kind: "file", path: appendPath, content: renderPiAppend(operatorAppend, role) });
-          entries.push(...await roleResourceEntries({ role, target, home, names: SHARED3, shared, executable: EXECUTABLE3 }));
+          entries.push(...await roleResourceEntries({
+            role,
+            target,
+            home,
+            names: SHARED3,
+            shared,
+            executable: EXECUTABLE3,
+            roomSkill,
+            leadSkillProjection: leadSkillProjection(layout, "pi")
+          }));
           credentials.push(await piCredentialDiagnostic(layout, role, binary));
           argv[role] = ["--no-extensions", "--extension", resolved.adapter.entry, "--no-approve", "--append-system-prompt", appendPath];
         }
@@ -2108,20 +2201,29 @@ var init_paseo = __esm({
 });
 
 // src/plugin.ts
-import { readFileSync as readFileSync2 } from "fs";
-import { join as join10 } from "path";
+import { readFileSync as readFileSync3 } from "fs";
+import { join as join11 } from "path";
 function loadAsset(path) {
-  return readFileSync2(new URL(`./plugin-assets/${path}`, import.meta.url), "utf8");
+  return readFileSync3(new URL(`./plugin-assets/${path}`, import.meta.url), "utf8");
 }
 function claudeCarrierPluginDir(layout) {
-  return join10(layout.roomHome, "plugin");
+  return join11(layout.roomHome, "plugin");
+}
+function typescriptTemplateLiteral(value) {
+  const escaped = value.replaceAll("\\", "\\\\").replaceAll("`", "\\`").replaceAll("${", "\\${");
+  return `\`${escaped}\``;
 }
 function renderClaudeCarrierContract(roles) {
-  const contracts = Object.fromEntries(roles.map((role) => [providerId("claude", role), renderInstructions(role)]));
+  const entries = roles.map((role) => {
+    const id = JSON.stringify(providerId("claude", role));
+    return `  ${id}: ${typescriptTemplateLiteral(renderInstructions(role))},`;
+  });
   return [
     "/** Generated by paseo-room. The Markdown prompt assets remain authoritative. */",
     `export const GENERATION = ${JSON.stringify(contractDigest())};`,
-    `export const CONTRACT: Readonly<Record<string, string>> = ${JSON.stringify(contracts, null, 2)};`,
+    "export const CONTRACT: Readonly<Record<string, string>> = {",
+    ...entries,
+    "};",
     ""
   ].join("\n");
 }
@@ -2129,9 +2231,9 @@ function claudeCarrierEntries(layout, roles) {
   const root = claudeCarrierPluginDir(layout);
   return [
     { kind: "dir", path: root },
-    { kind: "dir", path: join10(root, "server") },
-    ...STATIC_ASSETS.map((path) => ({ kind: "file", path: join10(root, path), content: loadAsset(path) })),
-    { kind: "file", path: join10(root, "server", "contract.ts"), content: renderClaudeCarrierContract(roles) }
+    { kind: "dir", path: join11(root, "server") },
+    ...STATIC_ASSETS.map((path) => ({ kind: "file", path: join11(root, path), content: loadAsset(path) })),
+    { kind: "file", path: join11(root, "server", "contract.ts"), content: renderClaudeCarrierContract(roles) }
   ];
 }
 var CLAUDE_CARRIER_PLUGIN_ID, STATIC_ASSETS;
@@ -2152,7 +2254,7 @@ var init_plugin = __esm({
 });
 
 // src/commands.ts
-import { join as join11, sep as sep2 } from "path";
+import { join as join12, sep as sep2 } from "path";
 import { lstat as lstat4, rm as rm3 } from "fs/promises";
 function sessionOptions(options) {
   const password = (options.env ?? process.env).PASEO_PASSWORD;
@@ -2184,7 +2286,10 @@ async function buildDesired(layout, agents, roles, build = {}) {
   const entries = [
     { kind: "dir", path: layout.roomHome },
     { kind: "dir", path: sharedRoom(layout) },
-    { kind: "file", path: join11(sharedRoom(layout), "WORKSPACE_PROTOCOL.md"), content: renderInstructions("workspace") }
+    // Earlier versions generated a default workspace protocol template here. The room ships no
+    // default protocol now, so the old generated regular file is declared absent and removed.
+    { kind: "absent", path: join12(sharedRoom(layout), "WORKSPACE_PROTOCOL.md") },
+    ...roomSkillEntries(layout, agents)
   ];
   const providers = {};
   const profiles = [];
@@ -2218,18 +2323,18 @@ async function buildDesired(layout, agents, roles, build = {}) {
   if (agents.every((id) => binaries[id] !== void 0)) {
     entries.push({
       kind: "file",
-      path: join11(layout.roomHome, AUTHENTICATION_GUIDE),
+      path: join12(layout.roomHome, AUTHENTICATION_GUIDE),
       content: renderAuthenticationGuide(layout.roomHome, binaries, agents, roles)
     });
     checks.push(warn(
       "room.authentication-not-validated",
-      `Role authentication was not validated. Login instructions are managed at ${join11(layout.roomHome, AUTHENTICATION_GUIDE)}.`,
+      `Role authentication was not validated. Login instructions are managed at ${join12(layout.roomHome, AUTHENTICATION_GUIDE)}.`,
       "After setup --apply, follow that guide or run: paseo-room auth login <agent> <role>"
     ));
   }
   const pluginPath = agents.includes("claude") ? claudeCarrierPluginDir(layout) : void 0;
   if (pluginPath !== void 0) entries.push(...claudeCarrierEntries(layout, roles));
-  entries.push({ kind: "file", path: join11(layout.roomHome, MARKER), content: renderMarker(package_default.version, agents, roles, contractDigest(), markerMemoryContract(agents, build.memoryContract ?? true)) });
+  entries.push({ kind: "file", path: join12(layout.roomHome, MARKER), content: renderMarker(package_default.version, agents, roles, contractDigest(), markerMemoryContract(agents, build.memoryContract ?? true)) });
   return { entries, providers, profiles, checks, ...pluginPath === void 0 ? {} : { pluginPath } };
 }
 function contractProvenance(previous) {
@@ -2292,11 +2397,26 @@ async function safeDirectory(path, checks) {
 async function roomPathSafety(layout, agents, roles) {
   const checks = [];
   if (!await safeDirectory(layout.roomHome, checks)) return checks;
-  await safeDirectory(sharedRoom(layout), checks);
-  const rolesHome = join11(layout.roomHome, "roles");
+  const room = sharedRoom(layout);
+  const roomIsSafe = await safeDirectory(room, checks);
+  if (roomIsSafe && agents.length > 0) {
+    const skills = join12(room, "skills");
+    if (await safeDirectory(skills, checks)) {
+      const source = roomSkillSource(layout);
+      if (await safeDirectory(source, checks)) await safeDirectory(join12(source, "references"), checks);
+    }
+    const projections = skillProjectionRoot(layout);
+    if (await safeDirectory(projections, checks)) {
+      for (const agent of agents) {
+        const agentRoot = agentSkillProjectionRoot(layout, agent);
+        if (await safeDirectory(agentRoot, checks)) await safeDirectory(leadSkillProjection(layout, agent), checks);
+      }
+    }
+  }
+  const rolesHome = join12(layout.roomHome, "roles");
   if (!await safeDirectory(rolesHome, checks)) return checks;
   for (const agent of agents) {
-    const agentHome = join11(rolesHome, agent);
+    const agentHome = join12(rolesHome, agent);
     if (!await safeDirectory(agentHome, checks)) continue;
     for (const role of roles) await safeDirectory(roleHome(layout, agent, role), checks);
   }
@@ -2476,7 +2596,7 @@ async function setup(options = {}) {
         operations
       };
     }
-    const markerPath = join11(layout.roomHome, MARKER);
+    const markerPath = join12(layout.roomHome, MARKER);
     const markerEntries = desired.entries.filter((entry) => entry.path === markerPath);
     await applyEntries(desired.entries.filter((entry) => entry.path !== markerPath));
     const ids = Object.keys(desired.providers);
@@ -2665,6 +2785,7 @@ var init_commands = __esm({
     init_plugin();
     init_result();
     init_instructions();
+    init_skills();
     init_room();
     init_roles();
     AGENTS = { codex: codexAgent, claude: claudeAgent, pi: piAgent };
@@ -2745,6 +2866,7 @@ var init_wizard = __esm({
 init_package();
 init_auth();
 init_commands();
+init_fsops();
 import { Command, CommanderError, InvalidArgumentError } from "commander";
 
 // src/render.ts
@@ -2777,6 +2899,7 @@ function renderHuman(result) {
 init_result();
 init_roles();
 init_prompts();
+init_skills();
 function collectAgent(value, previous) {
   const agent = AGENT_IDS.find((id) => id === value);
   if (!agent) throw new InvalidArgumentError(`Unknown agent: ${value}`);
@@ -2808,6 +2931,16 @@ function failedFromThrown(command, error) {
       "Reinstall paseo-room, then try again."
     )]);
   }
+  if (error instanceof SkillAssetError) {
+    return failed(command, [fail(
+      `${command}.skill-asset`,
+      error.message,
+      "Reinstall paseo-room, then try again."
+    )]);
+  }
+  if (error instanceof ManagedPathError) {
+    return failed(command, [fail(`${command}.managed-path`, error.message, error.fix)]);
+  }
   const detail = error instanceof Error ? error.message : "unknown error";
   return failed(command, [fail(
     `${command}.error`,