skillscript-runtime 0.20.1 → 0.21.0

package/dist/dashboard/spa/app.js

@@ -15,6 +15,8 @@ const state = {
   blockedShellAttempts: null,
   // v1.0 Gate #7 — { enabled, public_key_present } or null (pre-Gate-#7 server).
   securedApproval: null,
+  // v0.20.2 — true when the dashboard can sign in-browser (passcode unlock wired).
+  dashboardSigning: false,
   lastUpdate: null,
 };
 
@@ -45,11 +47,14 @@ async function refresh() {
   const ts = new Date();
   document.getElementById("poll-status").textContent = `polling…`;
   try {
-    const [catalog, triggers, metrics, capabilities, blocked] = await Promise.all([
-      // v0.9.8 — skill_list returns SkillCatalog (pre-grouped by audience).
-      // Dashboard wants the full picture (all categories); flatten the
-      // groups into a single array for the existing rendering code.
-      callTool("skill_list", { filter: { audience: "all" } }),
+    const [draftCat, apprCat, disabledCat, triggers, metrics, capabilities, blocked] = await Promise.all([
+      // v0.20.2 — fetch ALL statuses so the Skills view shows Draft + Approved +
+      // Disabled (skill_list defaults to Approved-only, which hid Disabled skills
+      // entirely — you couldn't find one to re-enable). Three calls + merge since
+      // skill_list has no "all-statuses" filter.
+      callTool("skill_list", { filter: { audience: "all", status: "Draft" } }),
+      callTool("skill_list", { filter: { audience: "all", status: "Approved" } }),
+      callTool("skill_list", { filter: { audience: "all", status: "Disabled" } }),
       callTool("list_triggers", {}),
       callTool("health_metrics", {}),
       callTool("runtime_capabilities", { include: ["mcpConnectors", "mcpConnectorClasses", "localModels", "dataStores", "skillStores", "agentConnectors", "securedApproval", "runtimeVersion"] }),
@@ -58,20 +63,23 @@ async function refresh() {
       // this tool; catch returns null and the Security view degrades.
       callTool("blocked_shell_attempts", { limit: 100 }).catch(() => null),
     ]);
-    state.skills = [
-      ...(catalog.receives ?? []),
-      ...(catalog.skills ?? []),
-      ...(catalog.headless ?? []),
-    ];
+    const flatCatalog = (c) => [...(c?.receives ?? []), ...(c?.skills ?? []), ...(c?.headless ?? [])];
+    // Approved first, then Draft, then Disabled — grouped by lifecycle.
+    state.skills = [...flatCatalog(apprCat), ...flatCatalog(draftCat), ...flatCatalog(disabledCat)];
     state.triggers = triggers;
     state.metrics = metrics;
     state.capabilities = capabilities;
     // v0.9.0+ servers may omit securedApproval (pre-Gate-#7) → null = "unsecured".
     state.securedApproval = capabilities?.securedApproval ?? null;
+    // v0.20.2 — can the dashboard sign in-browser? (passcode unlock wired)
+    state.dashboardSigning = await fetch("/signing-status").then((r) => r.json()).then((j) => j?.enabled === true).catch(() => false);
     state.blockedShellAttempts = blocked;
     state.lastUpdate = ts;
     renderSecuredBanner();
-    document.getElementById("poll-status").textContent = `last updated ${ts.toLocaleTimeString()}`;
+    // v0.21.0 — surface the running runtime version next to the poll timestamp.
+    const ver = state.capabilities?.runtimeVersion;
+    document.getElementById("poll-status").textContent =
+      `last updated ${ts.toLocaleTimeString()}${ver ? ` · skillscript v${ver}` : ""}`;
     renderCurrentView();
   } catch (err) {
     document.getElementById("poll-status").textContent = `poll failed: ${err.message}`;
@@ -119,11 +127,12 @@ function renderSecuredBanner() {
     </div>`;
     return;
   }
+  const approvalLine = state.dashboardSigning
+    ? `Approve in-browser after a one-time passcode unlock (or <code>skillfile approve &lt;name&gt;</code> at a terminal).`
+    : `Approval requires the operator's key: <code>skillfile approve &lt;name&gt;</code> at the terminal — the dashboard reviews, it does not sign.`;
   el.innerHTML = `<div class="banner banner-secured">
     <strong>🔒 Secured mode</strong> — unapproved skills cannot execute any
-    effectful op. Approval requires the operator's key:
-    <code>skillfile approve &lt;name&gt;</code> at the terminal. The dashboard
-    reviews; it does not sign.
+    effectful op. ${approvalLine}
   </div>`;
 }
 
@@ -157,10 +166,13 @@ async function renderApprovals() {
     return `<h2>Approvals</h2><section><div class="empty">Failed to load the approval queue: ${esc(err.message)}</div></section>`;
   }
   const staleCount = pending.filter((s) => s._why === "stale").length;
+  const signLine = state.dashboardSigning
+    ? `Review the source, then click <strong>Approve</strong> (a one-time passcode unlocks signing for this session).`
+    : `Review the source, then sign at a terminal that can read your approval key.`;
   const intro = secured
     ? `<p>Secured mode is <strong>ON</strong>. Each skill below is inert — no
-       effectful op will run until it is approved. ${staleCount > 0 ? `${staleCount} carry a stale/legacy approval (e.g. a pre-secured v1 stamp) and need re-signing — the fastest path is <code>skillfile reapprove --apply</code> at a terminal.` : ""}
-       Review the source, then sign at a terminal that can read your approval key.</p>`
+       effectful op will run until it is approved. ${staleCount > 0 ? `${staleCount} carry a stale/legacy approval (e.g. a pre-secured v1 stamp) and need re-signing${state.dashboardSigning ? "" : ` — the fastest path is <code>skillfile reapprove --apply</code> at a terminal`}.` : ""}
+       ${signLine}</p>`
     : `<p>Secured mode is <strong>OFF</strong> — Draft skills can be approved
        in-page from their detail view (the runtime self-stamps). Turn on secured
        mode (<code>SKILLSCRIPT_SECURED_MODE=true</code>) to require key-signed
@@ -188,7 +200,9 @@ async function renderApprovals() {
         <td>${sigBadges}</td>
         <td>
           <a href="#skill/${encodeURIComponent(s.name)}">Review →</a>
-          ${secured ? `<div class="approve-cmd"><code>${esc(cmd)}</code><button class="copy-btn" onclick="copyText('${esc(cmd).replace(/'/g, "\\'")}', this)">copy</button></div>` : ""}
+          ${!secured ? "" : (state.dashboardSigning
+            ? `<button class="primary" onclick="approveInBrowser('${esc(s.name).replace(/'/g, "\\'")}')">Approve</button>`
+            : `<div class="approve-cmd"><code>${esc(cmd)}</code><button class="copy-btn" onclick="copyText('${esc(cmd).replace(/'/g, "\\'")}', this)">copy</button></div>`)}
         </td>
       </tr>`;
   }).join("");
@@ -217,6 +231,38 @@ function approvalSignalBadges(sig) {
   return b.length ? b.join(" ") : `<span class="badge ok">no signals</span>`;
 }
 
+// v0.20.2 — in-browser approval. Click Approve → POST /approve. If the session
+// isn't unlocked, prompt for the passcode once (POST /unlock), then retry. The
+// unlock is session-scoped server-side, so subsequent approvals don't re-prompt.
+async function postJson(path, body) {
+  return fetch(path, { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(body) });
+}
+
+window.approveInBrowser = async function (name) {
+  try {
+    let res = await postJson("/approve", { name });
+    if (res.status === 401) {
+      const body = await res.json().catch(() => ({}));
+      if (body.needs_passcode) {
+        const pass = window.prompt(`Enter the approval passcode to sign '${name}'.\n(Unlocks signing for ~15 min — you can approve more without re-entering.)`);
+        if (!pass) return;
+        const unlock = await postJson("/unlock", { passcode: pass });
+        if (unlock.status !== 200) { alert("Incorrect passcode."); return; }
+        res = await postJson("/approve", { name });
+      }
+    }
+    const out = await res.json().catch(() => ({}));
+    if (res.status === 200 && out.approved) {
+      await refresh();
+      renderCurrentView();
+    } else {
+      alert(`Approve failed: ${out.error || ("HTTP " + res.status)}`);
+    }
+  } catch (err) {
+    alert(`Approve failed: ${err.message}`);
+  }
+};
+
 window.copyText = function (text, btn) {
   const done = () => { if (btn) { const o = btn.textContent; btn.textContent = "copied"; setTimeout(() => { btn.textContent = o; }, 1200); } };
   if (navigator.clipboard?.writeText) {
@@ -307,7 +353,7 @@ function renderSkills() {
           ${state.skills.map((s) => `
             <tr onclick="window.location.hash='#skill/${encodeURIComponent(s.name)}'">
               <td><strong>${esc(s.name)}</strong></td>
-              <td><span class="badge ${esc(s.status)}">${esc(s.status)}</span></td>
+              <td>${skillStatusBadge(s)}</td>
               <td>${esc(s.description ?? "—")}</td>
               <td><code>${esc(s.version?.slice(0, 8) ?? "—")}</code></td>
             </tr>
@@ -318,16 +364,28 @@ function renderSkills() {
   `;
 }
 
+// v0.21.0 — gate-aware status badge (adopter finding 576632ca). A legacy skill
+// stored `Approved` but failing the secured gate (e.g. a v1 stamp) WON'T run —
+// badging it a plain green "Approved" while the Approvals tab lists it as
+// "needs approval" reads as a contradiction. Show "re-approval needed" here too
+// so both views agree on the truth (what the gate will actually do).
+function skillStatusBadge(s) {
+  if (s.status === "Approved" && s.gate_ok === false) {
+    return `<span class="badge error" title="Approved status, but the body lacks a valid signature — won't run until re-approved">re-approval needed</span>`;
+  }
+  return `<span class="badge ${esc(s.status)}">${esc(s.status)}</span>`;
+}
+
 async function renderSkillDetail(name) {
   try {
-    // v0.13.3 — source moved out of skill_metadata into dedicated skill_read.
+    // v0.13.3 — source moved out of skill_preflight into dedicated skill_read.
     // Call both in parallel; skill_read may fail if the skill name doesn't
     // resolve (load() throws), so guard it to keep the detail view rendering.
     const [meta, readResult] = await Promise.all([
-      callTool("skill_metadata", { name }),
+      callTool("skill_preflight", { name }),
       callTool("skill_read", { name }).catch(() => null),
     ]);
-    const { metadata, versions, recent_fires, approval } = meta;
+    const { metadata, versions, recent_fires, approval, contract } = meta;
     const source = readResult?.source ?? null;
     const metrics = state.metrics?.perSkill?.[name];
     const triggersForSkill = state.triggers.filter((t) => t.skillName === name);
@@ -354,6 +412,8 @@ async function renderSkillDetail(name) {
         ${renderStatusActions(name, metadata, approval)}
       </section>
 
+      ${renderEffectfulFootprintPanel(contract?.effectful_footprint)}
+
       ${source ? renderSecuritySignalsPanel(source) : ""}
 
       <section>
@@ -460,19 +520,32 @@ function renderStatusActions(name, metadata, approval) {
     .join("");
 
   // The Approved action. Shown when not-yet-Approved OR stale (needs re-stamp).
+  // v0.20.2 — a Disabled skill is "re-enabled" (the user's mental model); in
+  // secured mode re-enabling = re-signing, since disabling stripped the token.
+  const isDisabled = status === "Disabled";
   const needsApprove = status !== "Approved" || staleApproved;
+  const headText = isDisabled ? "Re-enable this skill" : (staleApproved ? "Re-approve (body changed since signing)" : "Approve this skill");
+  const btnText = isDisabled ? "Re-enable" : "Approve";
   let approveBlock = "";
   if (needsApprove) {
-    if (secured) {
+    if (secured && state.dashboardSigning) {
+      // v0.20.2 — in-browser signing wired: click to approve (passcode-unlocked).
+      approveBlock = `
+        <div class="approve-panel">
+          <div class="approve-panel-head">${headText}</div>
+          <p>Signs with the operator's key after a one-time passcode unlock (review the source below first).</p>
+          <button class="primary" onclick="approveInBrowser('${esc(name).replace(/'/g, "\\'")}')">${btnText}</button>
+        </div>`;
+    } else if (secured) {
       const cmd = approveCommand(name);
       approveBlock = `
         <div class="approve-panel">
-          <div class="approve-panel-head">${staleApproved ? "Re-approve (body changed since signing)" : "Approve this skill"}</div>
-          <p>Secured mode: approval is signed with the operator's key at a terminal — not from this dashboard. Review the source below, then run:</p>
+          <div class="approve-panel-head">${headText}</div>
+          <p>Secured mode: ${isDisabled ? "re-enabling re-signs the skill" : "approval is signed"} with the operator's key at a terminal — not from this dashboard. Review the source below, then run:</p>
           <div class="approve-cmd"><code>${esc(cmd)}</code><button class="copy-btn" onclick="copyText('${esc(cmd).replace(/'/g, "\\'")}', this)">copy</button></div>
         </div>`;
     } else {
-      approveBlock = `<button onclick="updateStatus('${esc(name)}','Approved')">${staleApproved ? "Re-approve (refresh token)" : "Transition to Approved"}</button>`;
+      approveBlock = `<button onclick="updateStatus('${esc(name)}','Approved')">${isDisabled ? "Re-enable" : (staleApproved ? "Re-approve (refresh token)" : "Transition to Approved")}</button>`;
     }
   }
 
@@ -570,6 +643,49 @@ function renderHighlightedSkillBody(source) {
 // showing aggregated counts so a reviewer knows WHAT to look for before
 // scanning the body. Pairs with renderHighlightedSkillBody() (the
 // WHERE).
+// v0.21.0 — the authoritative "what does it touch" least-privilege checklist
+// for the human approver. Unlike renderSecuritySignalsPanel (regex over the
+// source), this is the AST-derived effectful_footprint from skill_preflight —
+// the SAME op enumeration the capability gate authorizes — so it's the truth of
+// what the skill can do when signed, not a textual approximation. Surfaced right
+// at the approve action so the operator sees the surface they're signing off.
+function renderEffectfulFootprintPanel(fp) {
+  if (!fp) return ""; // source not loadable / parse failed → no contract to show
+  const items = [];
+  if (fp.connectors.length > 0) {
+    items.push(`<li class="sig-medium-text">Dispatches to ${fp.connectors.length} MCP connector${fp.connectors.length === 1 ? "" : "s"}: ${fp.connectors.map((c) => `<code>${esc(c)}</code>`).join(", ")}</li>`);
+  }
+  if (fp.builtins.length > 0) {
+    items.push(`<li class="sig-info-text">Uses ${fp.builtins.length} built-in op${fp.builtins.length === 1 ? "" : "s"}: ${fp.builtins.map((b) => `<code>${esc(b)}</code>`).join(", ")}</li>`);
+  }
+  if (fp.file_writes > 0) {
+    items.push(`<li class="sig-high-text">${fp.file_writes} <code>file_write</code> op${fp.file_writes === 1 ? "" : "s"} <small>(writes to the filesystem allowlist)</small></li>`);
+  }
+  if (fp.file_reads > 0) {
+    items.push(`<li class="sig-medium-text">${fp.file_reads} <code>file_read</code> op${fp.file_reads === 1 ? "" : "s"}</li>`);
+  }
+  if (fp.unsafe_shell > 0) {
+    items.push(`<li class="sig-high-text">${fp.unsafe_shell} unsafe (full-bash) shell op${fp.unsafe_shell === 1 ? "" : "s"}</li>`);
+  }
+  const safeShellBins = fp.shell_binaries.filter((b) => b !== "bash" || fp.unsafe_shell === 0);
+  if (safeShellBins.length > 0) {
+    items.push(`<li class="sig-medium-text">Runs shell ${safeShellBins.length === 1 ? "binary" : "binaries"}: ${safeShellBins.map((b) => `<code>${esc(b)}</code>`).join(", ")} <small>(allowlist-gated)</small></li>`);
+  }
+  if (fp.notifies > 0) {
+    items.push(`<li class="sig-medium-text">${fp.notifies} <code>notify</code> agent-wake op${fp.notifies === 1 ? "" : "s"}</li>`);
+  }
+  const body = items.length === 0
+    ? `<p class="empty">Pure — no connector, shell, file, or notify ops. Nothing effectful to authorize.</p>`
+    : `<ul class="security-signals">${items.join("")}</ul>
+       <p><small>This is the AST-derived footprint the capability gate authorizes — the surface this skill can touch once approved. Confirm every line is least-privilege before signing.</small></p>`;
+  return `
+    <section>
+      <h2>What this skill touches</h2>
+      ${body}
+    </section>
+  `;
+}
+
 function renderSecuritySignalsPanel(source) {
   const sig = collectSecuritySignals(source);
   const items = [];
@@ -901,7 +1017,7 @@ async function loadComposeContract(detailsEl) {
   panel.dataset.loaded = "true";
   const [kind, name] = detailsEl.dataset.composeRef.split(":");
   try {
-    const meta = await callTool("skill_metadata", { name });
+    const meta = await callTool("skill_preflight", { name });
     const m = meta.metadata;
     // For inline (data-only), also fetch the body since it bakes at
     // compile time — reviewer sees what literally lands in the

package/dist/mcp-server.d.ts

@@ -14,23 +14,24 @@ import type { Registry } from "./connectors/registry.js";
  * protocol conforms to MCP — real MCP clients (Claude Desktop, Cursor,
  * future tools) can consume the server unchanged.
  *
- * Surface: tools wrapping existing T6 primitives.
+ * Surface: tools wrapping existing T6 primitives, ordered by the cold-author
+ * workflow loop the descriptions teach (learn → discover → draft → commit →
+ * approve → run → automate → observe).
  *
- *   skill_list({filter?})          → SkillCatalog (v0.9.8 — pre-grouped by audience)
- *   skill_metadata({name})         → metadata + version history + recent_fires + approval (no source — see skill_read)
- *   skill_read({name, version?})   → {name, version, status, source} (v0.13.3 — symmetric peer to skill_write)
- *   data_read({id, store?})      → PortableData | null (v0.13.8 — direct lookup; no data_write MCP by design)
- *   skill_status({name, new_state})→ SkillStatus update (write)
- *   list_triggers({filter?})       → TriggerRegistration[]
- *   register_trigger({...})        → TriggerRegistration (write)
- *   unregister_trigger({trigger_id})→ boolean (write)
- *   health_metrics({filter?})      → HealthMetrics
- *   runtime_capabilities({include?})→ wired connectors + shell-exec mode (v0.2.1)
- *   lint_skill({source?|name})     → diagnostics across tiers (v0.2.3)
- *   compile_skill({source?|name, inputs?})→ rendered artifact + errors (v0.2.3)
- *   skill_write({name, source, overwrite?})→ commit to SkillStore (write, v0.2.3)
- *   execute_skill({skill_name, inputs?, mechanical?})→ run + return result (write, v0.2.8)
- *   help({topic?})                 → cold-agent language discovery (read, v0.2.8)
+ *   LEARN     help({topic?})                  → language quickstart + deep topics
+ *             runtime_capabilities({include?})→ wired connectors + shell-exec mode
+ *   DISCOVER  skill_list({filter?})           → SkillCatalog (grouped by audience; entries carry the full contract)
+ *             skill_preflight({name})         → one skill's contract: takes/returns/requires/touches + approval + lifecycle
+ *             skill_read({name, version?})    → {name, version, status, source} (the body itself)
+ *             data_read({id, store?})         → PortableData | null (direct lookup; no data_write MCP by design)
+ *   DRAFT     lint_skill({source?|name})      → tiered diagnostics (inner loop)
+ *             compile_skill({source?|name, inputs?})→ rendered artifact + errors + exec order (pre-commit)
+ *   COMMIT    skill_write({name, source, overwrite?})→ store the body (write; secured mode forces unsigned→Draft)
+ *   APPROVE   skill_status({name, new_state}) → Draft/Approved/Disabled (write; secured promote needs a signature)
+ *   RUN       execute_skill({name|source, inputs?, mechanical?})→ run + return result (write)
+ *   AUTOMATE  register_trigger / list_triggers / set_trigger_enabled / unregister_trigger → autonomous dispatch
+ *   OBSERVE   health_metrics({filter?})       → per-skill/connector aggregates
+ *             blocked_shell_attempts()        → allowlist-refused shell ops (observe→promote loop)
  */
 export interface JsonRpcRequest {
     jsonrpc: "2.0";

package/dist/mcp-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"mcp-server.d.ts","sourceRoot":"","sources":["../src/mcp-server.ts"],"names":[],"mappings":"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"}

package/dist/mcp-server.js

@@ -4,6 +4,7 @@ import { healthMetrics } from "./metrics.js";
 import { lint } from "./lint.js";
 import { compile } from "./compile.js";
 import { parse as parseSkill } from "./parser.js";
+import { extractEffectfulFootprint } from "./skill-surface.js";
 import { listKnownConnectorClasses } from "./connectors/config.js";
 import { LintFailureError, MissingSkillReferenceError, OpError } from "./errors.js";
 import { executeSkillByName, executeSkillFromSource, RecursionDepthExceededError, SkillNotFoundForCompositionError, } from "./composition.js";
@@ -118,7 +119,7 @@ export class McpServer {
     registerBuiltinTools() {
         this.registerTool({
             name: "skill_list",
-            description: "Discover skills in the configured SkillStore (v0.9.8). Returns a `SkillCatalog` pre-grouped by audience-derived category: `receives` (skills that push to the calling agent via `# Output: agent:`), `skills` (skills the agent can invoke), `headless` (admin-view only). Category derived from each skill's `# Output:` declarations. Filter by audience / status / trigger_kind / domain_tags / name_prefix / author (AND-composed). Default: audience=\"agent\", status=\"Approved\". v0.18.6 — `author` filter narrows to skills authored by a specific identity; entries carry `author` for substrates that track it (null when not).",
+            description: "Discover skills in the configured SkillStore. Returns a `SkillCatalog` pre-grouped by audience-derived category: `receives` (skills that push to the calling agent via `# Output: agent:`), `skills` (skills the agent can invoke), `headless` (admin-view only). Category derived from each skill's `# Output:` declarations. Filter by audience / status / trigger_kind / domain_tags / name_prefix / author (AND-composed). Default: audience=\"agent\", status=\"Approved\". Every entry carries the full preflight contract — `vars` (inputs), `returns` (exported vars), `requires` (capability needs), `effectful_footprint` (which connectors / shell binaries / file + notify ops it touches), plus `gate_ok` (cleared-to-run under the current mode) and `author` (when the substrate tracks it). So you can read a skill's whole I/O + effect contract here without a per-skill `skill_preflight` call; reach for `skill_preflight` when you want one skill's contract + version/lifecycle detail, or `skill_read` for the body.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -143,7 +144,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "blocked_shell_attempts",
-            description: "v0.18.9 — list shell op dispatches refused by the binary allowlist gate. Queries the trace store cross-skill, filters to op records carrying `blocked_reason: \"binary-not-allowed\"`. Returns flat list ready for the dashboard's observe→promote loop (operator sees what binaries skills tried to invoke; decides whether to add any to `SKILLSCRIPT_SHELL_ALLOWLIST`).",
+            description: "List shell op dispatches refused by the binary allowlist gate. Queries the trace store cross-skill, filtering to op records carrying `blocked_reason: \"binary-not-allowed\"`. Returns a flat list for the dashboard's observe→promote loop: the operator sees what binaries skills tried to invoke, then decides whether to add any to `SKILLSCRIPT_SHELL_ALLOWLIST`. Read-only.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -196,8 +197,8 @@ export class McpServer {
             },
         });
         this.registerTool({
-            name: "skill_metadata",
-            description: "Get metadata + version history + recent fires + approval-gate state for a specific skill by name. For the source body itself, call skill_read.",
+            name: "skill_preflight",
+            description: "PRE-EXECUTION CONTRACT CHECK — call this BEFORE executing or composing a skill to see what it takes, returns, requires, and touches: its inputs (vars), exported variables (returns), capability requirements, and effectful footprint (which connectors / shell binaries / write + notify ops it dispatches). Also reports whether it's cleared to run (approval-gate state) + version/lifecycle. The least-privilege checklist for a human approver, and the contract surface for a cold author composing against it. Discover skills with skill_list (its entries already carry this same contract); call skill_preflight for one skill's contract plus version/lifecycle detail, or skill_read for the source body.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -219,15 +220,28 @@ export class McpServer {
                 // stale-Approved skills (body edited since approval, token no
                 // longer verifies). `null` when the source isn't loadable.
                 let approval = null;
+                // v0.21.0 — the contract surface: what the skill TAKES (vars, via the
+                // parser's frontmatter), RETURNS (exported vars), REQUIRES (capability
+                // clauses), and TOUCHES (effectful footprint). Derived statically from
+                // the body. Null when the source isn't loadable.
+                let contract = null;
                 if (loaded?.source !== undefined) {
                     const g = evaluateApprovalGate(loaded.source);
                     approval = g.ok ? { gate_ok: true } : { gate_ok: false, reason: g.reason };
+                    const parsed = parseSkill(loaded.source);
+                    contract = {
+                        vars: parsed.vars.map((v) => v.name),
+                        returns: parsed.returns,
+                        requires: parsed.requires,
+                        effectful_footprint: extractEffectfulFootprint(parsed),
+                    };
                 }
                 return {
                     metadata,
+                    contract,
+                    approval,
                     versions,
                     recent_fires,
-                    approval,
                 };
             },
         });
@@ -277,7 +291,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "skill_status",
-            description: "Transition a skill's status. Valid states: Draft, Approved, Disabled. Write operation.",
+            description: "Transition a skill's lifecycle status: Draft, Approved, Disabled. Approved is the only status that executes and lets triggers fire; Draft is the editing state; Disabled retires a skill without deleting it (re-enable by transitioning back to Approved/Draft). In secured mode you CANNOT promote to Approved here without a valid signature — approve via the dashboard or `skillfile approve` (which signs the body); a bare status flip can't grant approval. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -296,6 +310,19 @@ export class McpServer {
                 if (!isSkillStatus(newState)) {
                     throw new OpError(`\`skill_status\` requires \`new_state\` to be one of ${VALID_SKILL_STATUSES.map((s) => `"${s}"`).join(", ")}; got ${JSON.stringify(newState)}.`, "skill_status", `Pass \`new_state\` as one of: ${VALID_SKILL_STATUSES.join(" | ")}.`, name);
                 }
+                // v0.21.0 — store-agnostic secured-mode closure (red-team 33bf53d3).
+                // skill_status cannot GRANT approval in secured mode: promotion to
+                // Approved is refused unless the stored body already carries a valid v3
+                // signature. The per-store guard (FilesystemSkillStore/SqliteSkillStore)
+                // didn't cover custom adopter stores (e.g. AMP-backed), so an agent could
+                // flip Draft→Approved with no signature — a forgeable trust-state lie.
+                // Enforce HERE, at the ingress, regardless of substrate.
+                if (newState === "Approved" && isSecuredMode()) {
+                    const loaded = await this.deps.skillStore.load(name).catch(() => null);
+                    if (loaded === null || !evaluateApprovalGate(loaded.source).ok) {
+                        throw new OpError(`cannot promote '${name}' to Approved in secured mode — the skill carries no valid signature. Approve it via the dashboard or \`skillfile approve\` (which signs the body); a status change alone cannot grant approval.`, "skill_status", `Sign the skill with the operator's key, then it can be Approved.`, name);
+                    }
+                }
                 const result = await this.deps.skillStore.update_status(name, newState);
                 // v0.19.1 — sync declarative triggers on status transition.
                 // Approved → register the skill's declared triggers; Draft or
@@ -307,7 +334,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "list_triggers",
-            description: "List registered triggers. Optionally filter by skill name or trigger source.",
+            description: "List registered triggers — the autonomous-dispatch registry. Optionally filter by skill name or trigger source (cron / event). Read-only. Pairs with register_trigger / set_trigger_enabled / unregister_trigger to manage how Approved skills fire on their own.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -326,7 +353,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "register_trigger",
-            description: "Register a new trigger for a skill. Returns the registration. Write operation.",
+            description: "Register an autonomous-dispatch trigger for a skill — cron (time-based) or event (HTTP POST /event ingress, named). Only Approved skills fire; the scheduler re-verifies the approval gate at fire time, so registering a trigger never bypasses approval. Skills can also declare triggers inline via `# Triggers:` frontmatter (synced automatically on approval) — use this tool for imperative / dynamic registration. Returns the registration. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -374,7 +401,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "unregister_trigger",
-            description: "Unregister a trigger by id. Returns boolean (true if removed, false if id not found). Write operation.",
+            description: "Remove a registered trigger by id (see list_triggers for ids). Returns true if removed, false if the id wasn't found. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: { trigger_id: { type: "string" } },
@@ -387,7 +414,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "set_trigger_enabled",
-            description: "v0.9.0 — toggle a trigger's enabled state. Disabled triggers stay registered but the scheduler skips firing them (vacation / maintenance windows). State persists via the onTriggersChanged hook for imperative triggers. Returns the updated registration, or null if no trigger has that id. Write operation.",
+            description: "Toggle a trigger's enabled state without unregistering it — disabled triggers stay in the registry but the scheduler skips firing them (vacation / maintenance windows). State persists via the onTriggersChanged hook for imperative triggers. Returns the updated registration, or null if no trigger has that id. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -449,7 +476,7 @@ export class McpServer {
         // ─── v0.2.3 — over-the-wire authoring lifecycle ────────────────────────
         this.registerTool({
             name: "lint_skill",
-            description: "Run static lint against a skill source body or stored skill name. Returns diagnostics across tier-1 (errors that block compile), tier-2 (warnings), tier-3 (advisories). Read-only. Inner-loop affordance for cold authors iterating on a draft.",
+            description: "Run static lint against a skill source body or stored skill name. Returns diagnostics across tier-1 (errors that block compile), tier-2 (warnings), tier-3 (advisories). Read-only. The inner-loop affordance while drafting — lint as you iterate, then compile_skill for the full pre-commit check before skill_write.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -461,7 +488,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "compile_skill",
-            description: "Compile a skill source body or stored skill name. Returns the rendered artifact + parse/compile errors + resolved variables + topological execution order. Read-only. Pre-commit validation affordance.",
+            description: "Compile a skill source body or stored skill name. Returns the rendered artifact + parse/compile errors + resolved variables + topological execution order. Read-only. The pre-commit check after lint_skill passes and before skill_write — confirms the body compiles and shows the execution order without running effects (use execute_skill `mechanical: true` for a no-fire dispatch preview).",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -478,7 +505,7 @@ export class McpServer {
         });
         this.registerTool({
             name: "skill_write",
-            description: "Write a skill body into the configured SkillStore. Tier-1 lint runs at write time (SkillStore contract); throws on rejection. Returns version + content_hash. The `# Status:` header in the source body is honored — write with `# Status: Approved` and the skill lands Approved (otherwise defaults to Draft). Promote/demote later via skill_status. Write operation.",
+            description: "Write a skill body into the configured SkillStore. Tier-1 lint runs at write time (SkillStore contract) and throws on rejection — run lint_skill / compile_skill first to iterate cleanly. The `# Status:` header is honored: `# Status: Approved` lands Approved in unsecured mode, but in secured mode an unsigned body is forced to Draft (a write can't grant approval). Promote later via skill_status, or the dashboard / `skillfile approve` in secured mode. Returns version + content_hash. Write operation.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -533,7 +560,7 @@ export class McpServer {
     async executeSkill(args, callerCtx = {}) {
         // v0.15.2 — `name` is the canonical kwarg; `skill_name` is a silent
         // back-compat alias. Aligns the surface with the other skill_* tools
-        // (skill_read / skill_metadata / skill_status / skill_write all take
+        // (skill_read / skill_preflight / skill_status / skill_write all take
         // `name`). Per Perry signoff (thread 75abc8c0): silent alias — no
         // tier-3 advisory, no deprecation warn. If both are supplied with
         // different values, that's ambiguous; reject so the caller picks one.
@@ -817,7 +844,21 @@ export class McpServer {
         // posture (every write requires explicit human promotion regardless
         // of body claim) opt in via the flag at runtime startup. Per Perry's
         // `787b6b95` Option A.
-        const bodyToStore = this.deps.forceAlwaysDraft === true ? forceDraftStatus(source) : source;
+        // v0.21.0 — store-agnostic secured-mode closure (red-team 33bf53d3).
+        // skill_write cannot GRANT approval: if the body claims Approved without a
+        // valid v3 signature, force Draft — regardless of the SkillStore impl. The
+        // per-store guard didn't cover custom adopter stores (AMP-backed), letting an
+        // agent write status=Approved with no signature (a forgeable trust-state lie
+        // that misleads skill_list / skill_preflight / the dashboard). evaluateApproval
+        // -Gate is not-ok for any Draft OR unsigned-Approved body, so a genuine
+        // approve-flow write (signed body) is honored; everything else lands Draft.
+        let bodyToStore = source;
+        if (this.deps.forceAlwaysDraft === true) {
+            bodyToStore = forceDraftStatus(source);
+        }
+        else if (isSecuredMode() && !evaluateApprovalGate(source).ok) {
+            bodyToStore = forceDraftStatus(source);
+        }
         // v0.17.0 — thread host-attested caller identity into `store({author})`
         // so MCP-authored skills stamp `SkillMeta.author = <calling agent>`,
         // not the runtime's wiring identity. When ctx.callerIdentity is