skillscript-runtime 0.27.3 → 0.31.0

package/dist/skill-surface.js

@@ -105,4 +105,199 @@ export function extractEffectfulFootprint(parsed) {
         notifies,
     };
 }
+/** Lane cap — beyond this the flow stops being a readable orientation aid. */
+const MAX_FLOW_LANES = 40;
+/** Built-in `$` ops → plain language. Unlisted builtins fall back to their name. */
+const BUILTIN_STEP = {
+    data_read: { label: "Read from the data store", tone: "normal" },
+    data_write: { label: "Write to the data store", tone: "mutation" },
+    llm: { label: "Ask the local model", tone: "normal" },
+    json_parse: { label: "Parse JSON", tone: "normal" },
+    execute_skill: { label: "Run another skill", tone: "normal" },
+    skill_read: { label: "Read a skill", tone: "normal" },
+    skill_list: { label: "List skills", tone: "normal" },
+    skill_write: { label: "Write a skill", tone: "mutation" },
+};
+function humanizeToolName(tool) {
+    return tool.replace(/_/g, " ");
+}
+/** Pull the binary + a short command snippet out of a `shell(command="…")` op. */
+function shellCommand(op) {
+    if (op.argv && op.argv.length > 0) {
+        return { binary: op.argv[0] ?? "", snippet: op.argv.join(" ") };
+    }
+    const m = op.body.match(/command\s*=\s*"([^"]*)"/) ?? op.body.match(/command\s*=\s*'([^']*)'/);
+    const cmd = (m?.[1] ?? op.body).trim();
+    return { binary: firstToken(cmd), snippet: cmd === "" ? undefined : cmd };
+}
+function clip(s, max) {
+    if (s === undefined)
+        return undefined;
+    return s.length <= max ? s : s.slice(0, max - 1) + "…";
+}
+/** A `$set` value shown only when it's a plain literal — computed expressions
+ * (variable references / filters) are raw skillscript, noise to a reader, so
+ * they're dropped and the step reads simply as "Set X". */
+function literalSetValue(v) {
+    if (v === undefined || v === "")
+        return undefined;
+    if (v.includes("${") || v.includes("$("))
+        return undefined;
+    return clip(v.replace(/^["']|["']$/g, ""), 60);
+}
+/** Value of a `key="…"` (or `key='…'`) kwarg in an op body. `key` comes from a
+ * fixed internal list, so building the RegExp from it is safe. */
+function argValue(body, key) {
+    return body.match(new RegExp(key + '\\s*=\\s*"([^"]*)"'))?.[1]
+        ?? body.match(new RegExp(key + "\\s*=\\s*'([^']*)'"))?.[1];
+}
+/** The most human-meaningful argument to show for a step — the "what" (the
+ * query it reads, the prompt it asks, the content it writes). First match wins. */
+const PRIMARY_ARG_KEYS = ["query", "prompt", "content", "message", "text", "url", "path", "name", "mode"];
+function primaryArg(body) {
+    for (const k of PRIMARY_ARG_KEYS) {
+        const v = argValue(body, k);
+        if (v !== undefined && v !== "")
+            return v;
+    }
+    return undefined;
+}
+/** Describe one op as a human-readable step. Leaf steps also carry the variable
+ * they produce (`-> VAR`) so a reader can trace data flow — see where a value is
+ * created and where (or whether) it's used. */
+function describeStep(op) {
+    const step = describeStepBody(op);
+    if (op.outputVar !== undefined && op.outputVar !== "" && step.children === undefined && step.branches === undefined) {
+        step.produces = op.outputVar;
+    }
+    return step;
+}
+function describeStepBody(op) {
+    switch (op.kind) {
+        case "foreach":
+            return {
+                label: `For each ${op.foreachIter ?? "item"} in ${op.foreachList ?? "the list"}`,
+                tone: "normal",
+                children: (op.foreachBody ?? []).map(describeStep),
+            };
+        case "if": {
+            const branches = (op.ifBranches ?? []).map((b, i) => ({
+                label: `${i === 0 ? "If" : "Otherwise, if"} ${clip(b.cond, 60)}`,
+                steps: b.body.map(describeStep),
+            }));
+            if (op.ifElseBody)
+                branches.push({ label: "Otherwise", steps: op.ifElseBody.map(describeStep) });
+            return { label: "Depending on the result", tone: "normal", branches };
+        }
+        case "shell": {
+            const { binary, snippet } = shellCommand(op);
+            if (op.policy === "unsafe") {
+                return { label: "Run a full bash command", detail: clip(snippet, 70), tone: "shell" };
+            }
+            return { label: binary ? `Run ${binary}` : "Run a shell command", detail: clip(snippet, 70), tone: "shell" };
+        }
+        case "file_read":
+            return { label: "Read a file", detail: clip(op.fileParams?.path, 60), tone: "normal" };
+        case "file_write":
+            return { label: "Write a file", detail: clip(op.fileParams?.path, 60), tone: "mutation" };
+        case "notify":
+            return { label: "Send a notification", tone: "mutation" };
+        case "emit":
+            return { label: "Produce output", tone: "normal" };
+        case "inline": {
+            const name = op.ampParams?.skillName;
+            const step = { label: name ? `Include the ${name} skill` : "Include a skill", tone: "normal" };
+            if (name)
+                step.ref = { skill: name };
+            return step;
+        }
+        case "$set":
+            return { label: `Set ${op.setName ?? "a value"}`, detail: literalSetValue(op.setValue), tone: "normal" };
+        case "$append":
+            return { label: `Add to ${op.setName ?? "a value"}`, detail: literalSetValue(op.setValue), tone: "normal" };
+        case "?":
+            return { label: "Check a condition", tone: "normal" };
+        case "$": {
+            const tool = firstToken(op.body);
+            // A composed skill: name it, and carry a ref so the UI can link through.
+            if (op.mcpConnector === undefined && tool === "execute_skill") {
+                const child = argValue(op.body, "skill_name") ?? argValue(op.body, "skill");
+                const step = { label: child ? `Run the ${child} skill` : "Run another skill", tone: "normal" };
+                if (child)
+                    step.ref = { skill: child };
+                return step;
+            }
+            const detail = clip(primaryArg(op.body), 60);
+            if (op.mcpConnector !== undefined) {
+                return { label: humanizeToolName(tool), detail: detail ?? `via ${op.mcpConnector}`, tone: "normal" };
+            }
+            const known = BUILTIN_STEP[tool];
+            if (known !== undefined) {
+                return { label: known.label, detail, tone: known.tone };
+            }
+            return { label: tool === "" ? "Run an operation" : humanizeToolName(tool), detail, tone: "normal" };
+        }
+        default:
+            return { label: String(op.kind), tone: "normal" };
+    }
+}
+/** Order targets so a needed target precedes its dependents (Kahn's algorithm),
+ * falling back to declaration order for any leftovers (e.g. a dependency cycle,
+ * which compile rejects anyway). */
+function orderLanes(names, depsOf) {
+    const present = new Set(names);
+    const indeg = new Map(names.map((n) => [n, 0]));
+    for (const n of names)
+        for (const d of depsOf(n))
+            if (present.has(d))
+                indeg.set(n, (indeg.get(n) ?? 0) + 1);
+    const queue = names.filter((n) => (indeg.get(n) ?? 0) === 0);
+    const ordered = [];
+    const seen = new Set();
+    while (queue.length > 0) {
+        const n = queue.shift();
+        if (seen.has(n))
+            continue;
+        seen.add(n);
+        ordered.push(n);
+        for (const m of names) {
+            if (seen.has(m))
+                continue;
+            if (depsOf(m).includes(n)) {
+                indeg.set(m, (indeg.get(m) ?? 1) - 1);
+                if ((indeg.get(m) ?? 0) <= 0)
+                    queue.push(m);
+            }
+        }
+    }
+    for (const n of names)
+        if (!seen.has(n))
+            ordered.push(n); // cycle leftovers, declaration order
+    return ordered;
+}
+/**
+ * Project a parsed skill into reading-order lanes of plain-language steps.
+ * Body-only skills (no targets) return an empty lane list — the dashboard shows
+ * no flow for those (there is nothing to walk).
+ */
+export function buildSkillFlow(parsed) {
+    const allNames = [...parsed.targets.keys()];
+    const truncated = allNames.length > MAX_FLOW_LANES;
+    const names = truncated ? allNames.slice(0, MAX_FLOW_LANES) : allNames;
+    const included = new Set(names);
+    const ordered = orderLanes(names, (n) => parsed.targets.get(n)?.deps ?? []);
+    const lanes = ordered.map((name) => {
+        const target = parsed.targets.get(name);
+        return {
+            id: name,
+            isEntry: parsed.entryTarget === name,
+            deps: target.deps.filter((d) => included.has(d)),
+            steps: target.ops.map(describeStep),
+        };
+    });
+    const entry = parsed.entryTarget !== null && included.has(parsed.entryTarget)
+        ? parsed.entryTarget
+        : null;
+    return { lanes, entry, truncated };
+}
 //# sourceMappingURL=skill-surface.js.map

package/dist/skill-surface.js.map

@@ -1 +1 @@
-{"version":3,"file":"skill-surface.js","sourceRoot":"","sources":["../src/skill-surface.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"skill-surface.js","sourceRoot":"","sources":["../src/skill-surface.ts"],"names":[],"mappings":"AAAA,iEAAiE;AACjE,EAAE;AACF,2EAA2E;AAC3E,gFAAgF;AAChF,6EAA6E;AAC7E,8EAA8E;AAC9E,8EAA8E;AAC9E,gFAAgF;AAChF,mDAAmD;AAqBnD,qFAAqF;AACrF,SAAS,OAAO,CAAC,GAAc,EAAE,KAA4B;IAC3D,KAAK,MAAM,EAAE,IAAI,GAAG,EAAE,CAAC;QACrB,KAAK,CAAC,EAAE,CAAC,CAAC;QACV,IAAI,EAAE,CAAC,WAAW;YAAE,OAAO,CAAC,EAAE,CAAC,WAAW,EAAE,KAAK,CAAC,CAAC;QACnD,IAAI,EAAE,CAAC,UAAU;YAAE,KAAK,MAAM,CAAC,IAAI,EAAE,CAAC,UAAU;gBAAE,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;QACzE,IAAI,EAAE,CAAC,UAAU;YAAE,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,KAAK,CAAC,CAAC;IACnD,CAAC;AACH,CAAC;AAED,SAAS,UAAU,CAAC,CAAS;IAC3B,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACxC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,wBAAwB,CAAC,MAAmB;IAC1D,MAAM,IAAI,GAAG,IAAI,GAAG,EAA+C,CAAC;IACpE,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC7C,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE;YACzB,IAAI,EAAE,CAAC,IAAI,KAAK,GAAG,IAAI,EAAE,CAAC,YAAY,KAAK,SAAS;gBAAE,OAAO;YAC7D,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;gBAAE,OAAO;YAC9B,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,YAAY,IAAI,IAAI,EAAE,EAAE,EAAE,SAAS,EAAE,EAAE,CAAC,YAAY,EAAE,IAAI,EAAE,CAAC,CAAC;QAC/E,CAAC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACtC,CAAC,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC;AAC5E,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,MAAmB;IAC3D,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IACnC,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;IACpC,IAAI,WAAW,GAAG,CAAC,CAAC;IACpB,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,SAAS,GAAG,CAAC,CAAC;IAClB,IAAI,QAAQ,GAAG,CAAC,CAAC;IAEjB,KAAK,MAAM,MAAM,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;QAC7C,OAAO,CAAC,MAAM,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,EAAE;YACzB,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;gBAChB,KAAK,GAAG,CAAC,CAAC,CAAC;oBACT,oEAAoE;oBACpE,qEAAqE;oBACrE,mDAAmD;oBACnD,IAAI,EAAE,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;wBAClC,UAAU,CAAC,GAAG,CAAC,EAAE,CAAC,YAAY,CAAC,CAAC;oBAClC,CAAC;yBAAM,CAAC;wBACN,MAAM,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;wBAC9B,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;4BAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACpC,CAAC;oBACD,MAAM;gBACR,CAAC;gBACD,KAAK,OAAO,CAAC,CAAC,CAAC;oBACb,IAAI,EAAE,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;wBAC3B,WAAW,EAAE,CAAC;wBACd,SAAS,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;oBACxB,CAAC;yBAAM,CAAC;wBACN,MAAM,GAAG,GAAG,EAAE,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;wBAChD,IAAI,GAAG,CAAC,MAAM,GAAG,CAAC;4BAAE,SAAS,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;oBACzC,CAAC;oBACD,MAAM;gBACR,CAAC;gBACD,KAAK,YAAY;oBAAE,UAAU,EAAE,CAAC;oBAAC,MAAM;gBACvC,KAAK,WAAW;oBAAE,SAAS,EAAE,CAAC;oBAAC,MAAM;gBACrC,KAAK,QAAQ;oBAAE,QAAQ,EAAE,CAAC;oBAAC,MAAM;gBACjC,OAAO,CAAC,CAAC,MAAM;YACjB,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;IAED,OAAO;QACL,UAAU,EAAE,CAAC,GAAG,UAAU,CAAC,CAAC,IAAI,EAAE;QAClC,QAAQ,EAAE,CAAC,GAAG,QAAQ,CAAC,CAAC,IAAI,EAAE;QAC9B,cAAc,EAAE,CAAC,GAAG,SAAS,CAAC,CAAC,IAAI,EAAE;QACrC,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,UAAU;QACvB,UAAU,EAAE,SAAS;QACrB,QAAQ;KACT,CAAC;AACJ,CAAC;AA2CD,8EAA8E;AAC9E,MAAM,cAAc,GAAG,EAAE,CAAC;AAE1B,oFAAoF;AACpF,MAAM,YAAY,GAA8D;IAC9E,SAAS,EAAE,EAAE,KAAK,EAAE,0BAA0B,EAAE,IAAI,EAAE,QAAQ,EAAE;IAChE,UAAU,EAAE,EAAE,KAAK,EAAE,yBAAyB,EAAE,IAAI,EAAE,UAAU,EAAE;IAClE,GAAG,EAAE,EAAE,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,QAAQ,EAAE;IACrD,UAAU,EAAE,EAAE,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,QAAQ,EAAE;IACnD,aAAa,EAAE,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE;IAC7D,UAAU,EAAE,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,QAAQ,EAAE;IACrD,UAAU,EAAE,EAAE,KAAK,EAAE,aAAa,EAAE,IAAI,EAAE,QAAQ,EAAE;IACpD,WAAW,EAAE,EAAE,KAAK,EAAE,eAAe,EAAE,IAAI,EAAE,UAAU,EAAE;CAC1D,CAAC;AAEF,SAAS,gBAAgB,CAAC,IAAY;IACpC,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,kFAAkF;AAClF,SAAS,YAAY,CAAC,EAAW;IAC/B,IAAI,EAAE,CAAC,IAAI,IAAI,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,OAAO,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;IAClE,CAAC;IACD,MAAM,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAC;IAC/F,MAAM,GAAG,GAAG,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,CAAC;IACvC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,GAAG,CAAC,EAAE,OAAO,EAAE,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;AAC5E,CAAC;AAED,SAAS,IAAI,CAAC,CAAqB,EAAE,GAAW;IAC9C,IAAI,CAAC,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IACtC,OAAO,CAAC,CAAC,MAAM,IAAI,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,GAAG,GAAG,CAAC,CAAC,GAAG,GAAG,CAAC;AACzD,CAAC;AAED;;2DAE2D;AAC3D,SAAS,eAAe,CAAC,CAAqB;IAC5C,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE;QAAE,OAAO,SAAS,CAAC;IAClD,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC;QAAE,OAAO,SAAS,CAAC;IAC3D,OAAO,IAAI,CAAC,CAAC,CAAC,OAAO,CAAC,cAAc,EAAE,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;AACjD,CAAC;AAED;kEACkE;AAClE,SAAS,QAAQ,CAAC,IAAY,EAAE,GAAW;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,GAAG,GAAG,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;WACzD,IAAI,CAAC,KAAK,CAAC,IAAI,MAAM,CAAC,GAAG,GAAG,oBAAoB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;AAC/D,CAAC;AAED;mFACmF;AACnF,MAAM,gBAAgB,GAAG,CAAC,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;AAC1G,SAAS,UAAU,CAAC,IAAY;IAC9B,KAAK,MAAM,CAAC,IAAI,gBAAgB,EAAE,CAAC;QACjC,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QAC5B,IAAI,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE;YAAE,OAAO,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;+CAE+C;AAC/C,SAAS,YAAY,CAAC,EAAW;IAC/B,MAAM,IAAI,GAAG,gBAAgB,CAAC,EAAE,CAAC,CAAC;IAClC,IAAI,EAAE,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,CAAC,SAAS,KAAK,EAAE,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,IAAI,IAAI,CAAC,QAAQ,KAAK,SAAS,EAAE,CAAC;QACpH,IAAI,CAAC,QAAQ,GAAG,EAAE,CAAC,SAAS,CAAC;IAC/B,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,SAAS,gBAAgB,CAAC,EAAW;IACnC,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,SAAS;YACZ,OAAO;gBACL,KAAK,EAAE,YAAY,EAAE,CAAC,WAAW,IAAI,MAAM,OAAO,EAAE,CAAC,WAAW,IAAI,UAAU,EAAE;gBAChF,IAAI,EAAE,QAAQ;gBACd,QAAQ,EAAE,CAAC,EAAE,CAAC,WAAW,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,YAAY,CAAC;aACnD,CAAC;QACJ,KAAK,IAAI,CAAC,CAAC,CAAC;YACV,MAAM,QAAQ,GAAG,CAAC,EAAE,CAAC,UAAU,IAAI,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC;gBACpD,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,eAAe,IAAI,IAAI,CAAC,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE;gBAChE,KAAK,EAAE,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,YAAY,CAAC;aAChC,CAAC,CAAC,CAAC;YACJ,IAAI,EAAE,CAAC,UAAU;gBAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,CAAC,UAAU,CAAC,GAAG,CAAC,YAAY,CAAC,EAAE,CAAC,CAAC;YACjG,OAAO,EAAE,KAAK,EAAE,yBAAyB,EAAE,IAAI,EAAE,QAAQ,EAAE,QAAQ,EAAE,CAAC;QACxE,CAAC;QACD,KAAK,OAAO,CAAC,CAAC,CAAC;YACb,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,YAAY,CAAC,EAAE,CAAC,CAAC;YAC7C,IAAI,EAAE,CAAC,MAAM,KAAK,QAAQ,EAAE,CAAC;gBAC3B,OAAO,EAAE,KAAK,EAAE,yBAAyB,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;YACxF,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC,OAAO,MAAM,EAAE,CAAC,CAAC,CAAC,qBAAqB,EAAE,MAAM,EAAE,IAAI,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;QAC/G,CAAC;QACD,KAAK,WAAW;YACd,OAAO,EAAE,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACzF,KAAK,YAAY;YACf,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC5F,KAAK,QAAQ;YACX,OAAO,EAAE,KAAK,EAAE,qBAAqB,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;QAC5D,KAAK,MAAM;YACT,OAAO,EAAE,KAAK,EAAE,gBAAgB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACrD,KAAK,QAAQ,CAAC,CAAC,CAAC;YACd,MAAM,IAAI,GAAG,EAAE,CAAC,SAAS,EAAE,SAAS,CAAC;YACrC,MAAM,IAAI,GAAa,EAAE,KAAK,EAAE,IAAI,CAAC,CAAC,CAAC,eAAe,IAAI,QAAQ,CAAC,CAAC,CAAC,iBAAiB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YACzG,IAAI,IAAI;gBAAE,IAAI,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;YACrC,OAAO,IAAI,CAAC;QACd,CAAC;QACD,KAAK,MAAM;YACT,OAAO,EAAE,KAAK,EAAE,OAAO,EAAE,CAAC,OAAO,IAAI,SAAS,EAAE,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC3G,KAAK,SAAS;YACZ,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,CAAC,OAAO,IAAI,SAAS,EAAE,EAAE,MAAM,EAAE,eAAe,CAAC,EAAE,CAAC,QAAQ,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QAC9G,KAAK,GAAG;YACN,OAAO,EAAE,KAAK,EAAE,mBAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACxD,KAAK,GAAG,CAAC,CAAC,CAAC;YACT,MAAM,IAAI,GAAG,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC;YACjC,yEAAyE;YACzE,IAAI,EAAE,CAAC,YAAY,KAAK,SAAS,IAAI,IAAI,KAAK,eAAe,EAAE,CAAC;gBAC9D,MAAM,KAAK,GAAG,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,YAAY,CAAC,IAAI,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;gBAC5E,MAAM,IAAI,GAAa,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC,CAAC,WAAW,KAAK,QAAQ,CAAC,CAAC,CAAC,mBAAmB,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;gBACzG,IAAI,KAAK;oBAAE,IAAI,CAAC,GAAG,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC;gBACvC,OAAO,IAAI,CAAC;YACd,CAAC;YACD,MAAM,MAAM,GAAG,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,EAAE,CAAC,CAAC;YAC7C,IAAI,EAAE,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;gBAClC,OAAO,EAAE,KAAK,EAAE,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,IAAI,OAAO,EAAE,CAAC,YAAY,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;YACvG,CAAC;YACD,MAAM,KAAK,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;YACjC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,CAAC;YAC1D,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,IAAI,KAAK,EAAE,CAAC,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;QACtG,CAAC;QACD;YACE,OAAO,EAAE,KAAK,EAAE,MAAM,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,CAAC;IACtD,CAAC;AACH,CAAC;AAED;;oCAEoC;AACpC,SAAS,UAAU,CAAC,KAAe,EAAE,MAA+B;IAClE,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,KAAK,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAChD,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,KAAK,MAAM,CAAC,IAAI,MAAM,CAAC,CAAC,CAAC;YAAE,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IAC5G,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAC7D,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAU,CAAC;IAC/B,OAAO,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACxB,MAAM,CAAC,GAAG,KAAK,CAAC,KAAK,EAAG,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,SAAS;QAC1B,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;QACZ,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;QAChB,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,IAAI,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;gBAAE,SAAS;YAC1B,IAAI,MAAM,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC1B,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;gBACtC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;YAC9C,CAAC;QACH,CAAC;IACH,CAAC;IACD,KAAK,MAAM,CAAC,IAAI,KAAK;QAAE,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;YAAE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,qCAAqC;IAC/F,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,MAAmB;IAChD,MAAM,QAAQ,GAAG,CAAC,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5C,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,cAAc,CAAC;IACnD,MAAM,KAAK,GAAG,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,cAAc,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC;IACvE,MAAM,QAAQ,GAAG,IAAI,GAAG,CAAC,KAAK,CAAC,CAAC;IAEhC,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,IAAI,IAAI,EAAE,CAAC,CAAC;IAC5E,MAAM,KAAK,GAAe,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE;QAC7C,MAAM,MAAM,GAAG,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAE,CAAC;QACzC,OAAO;YACL,EAAE,EAAE,IAAI;YACR,OAAO,EAAE,MAAM,CAAC,WAAW,KAAK,IAAI;YACpC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;YAChD,KAAK,EAAE,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC;SACpC,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,KAAK,IAAI,IAAI,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC;QAC3E,CAAC,CAAC,MAAM,CAAC,WAAW;QACpB,CAAC,CAAC,IAAI,CAAC;IAET,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,EAAE,CAAC;AACrC,CAAC"}

package/docs/adopter-agent-guide.md

@@ -0,0 +1,157 @@
+---
+title: Adopter Agent Guide
+description: "Wire your agent's instruction file so it discovers and prefers its skills instead of re-reasoning every session."
+mode: wide
+---
+
+How to set up your agent's instruction file (`CLAUDE.md`, `AGENTS.md`, system prompt — whatever your harness uses) so the agent actually *takes advantage* of Skillscript instead of ignoring it.
+
+Skillscript gives your agent a way to **capture a routine once as a durable, compiled, auditable skill** and run it many times — instead of re-reasoning the same workflow from scratch on every session, burning tokens and drifting a little each time. But an agent only uses skills if its instructions tell it to look. This guide is the minimum wiring to make that happen.
+
+---
+
+## 1. The runtime tells your agent how to use it
+
+**You probably don't need to paste anything.** The MCP server ships the usage contract as its `instructions` field — most MCP hosts surface that to the model at session start, so a connecting agent already knows to `skill_list()` first, preflight before composing, author-when-repeated, and never assume a backend. Quick check: after wiring the MCP, ask your agent "what do you know about skillscript?" — if it describes the workflow, you're done, and your `CLAUDE.md` / `AGENTS.md` needs nothing about Skillscript.
+
+**If your host doesn't surface server `instructions`** (some don't), paste the block below into your agent file. It mirrors what the server delivers — the authoritative copy is the runtime's `instructions` field, so keep this in sync rather than diverging from it.
+
+```markdown
+## Skillscript — your durable skills
+
+You have a Skillscript runtime wired over MCP. A *skillscript* is a compiled,
+auditable, reusable procedure — a routine captured once and run many times,
+rather than re-derived every session.
+
+### At session start
+List what you already have before doing routine work:
+
+- `skill_list()` — returns your skills grouped by category:
+  - **skills** — skills you can invoke directly (template-output skills + skills with no `# Output:` declaration)
+  - **receives** — skills that push augmenting context to you (`# Output: agent: <name>`)
+  - **headless** — autonomous skills (cron/event-fired); yours to maintain, not to invoke
+
+Know your own skills so you reach for them instead of rebuilding a workflow.
+
+### When a task smells routine
+If an existing skill fits, use it — don't re-reason the steps:
+
+- `skill_preflight({ name })` — see what a skill takes, returns, requires, and
+  *touches* (its effectful footprint) plus whether it's cleared to run, before
+  you invoke or compose it. (`skill_list` entries already carry this contract, so
+  often you won't need a separate call.)
+- `execute_skill({ name })` — run a stored skill end-to-end.
+- `compile_skill({ name })` — preview the rendered plan first, no side effects.
+
+### When you're repeating yourself, author a skill
+What you can script is the wired connectors, models, and allowed shell binaries that
+`runtime_capabilities()` reports — that list is your **menu of what's capturable**. When
+you catch yourself re-running the same multi-step routine over any of them, turn it into a skill:
+
+1. `help()` — learn the language (and `help({ topic })` for ops, frontmatter,
+   examples, composition, error-handling, connectors, lint-codes).
+2. Draft the skill body against what's wired.
+3. `lint_skill({ source })` then `compile_skill({ source })` — catch mistakes
+   before anything is stored.
+4. `skill_write({ name, source })` — it lands **Draft**; a human reviews and
+   approves before it can run (you can't self-approve).
+
+If something you'd need isn't wired yet, ask the operator to add it (a connector, or a
+binary on `SKILLSCRIPT_SHELL_ALLOWLIST`), then capture the routine.
+```
+
+That block is enough to change behavior. Everything below explains *why* and fills in the edges.
+
+### What your agent file *should* carry instead
+
+Now that the runtime delivers the universal how-to, your agent file gets *thinner* — it should hold only what the runtime can't know:
+
+- **Who the operator is.** The usage block says "ask the operator to wire what's missing" — but not *who*. Name them and the channel to ask on.
+- **Which skills are *this* agent's to maintain.** A skill's `headless` category (in `skill_list`) flags it as cron/event-fired, but "this one is *yours to keep correct*" is an ownership fact the universal block can't carry. Note the autonomous skills the agent is responsible for.
+- **The agent's role and behavioral context.** Who it is, how it should work. Never Skillscript's to provide; always yours.
+
+The test: if it's true for *every* agent on *any* Skillscript runtime, the runtime already delivers it — leave it out. If it's specific to *this* agent or *this* deployment, it belongs in your file. The runtime owns "how to use me"; your file owns "who you are, where you are, and what's yours to tend."
+
+---
+
+## 2. Best practices
+
+### Discover before you build
+The single highest-value instruction is "run `skill_list()` at session start." Agents that don't enumerate their skills silently re-derive workflows that already exist as skills — the exact waste Skillscript removes. Make discovery a reflex, not an afterthought.
+
+### Prefer a skill over re-reasoning
+A compiled skill runs the same way every time because the procedure *is* the source of record, not a prompt to be re-interpreted. When a routine exists as a skill, executing it is cheaper, more reliable, and auditable. Reserve fresh reasoning for the work that genuinely needs it.
+
+### Write descriptions as *trigger conditions*, not summaries
+When the agent picks among skills, it reads each `# Description:`. "Handles errors" is useless for selection. "If a downstream API returns non-200, run this" fires the skill at the right moment. Describe **when to invoke**, not what the skill does. This is what makes `skill_list()` actionable once you have more than a handful of skills.
+
+### Two kinds of skill, two postures
+- **Skills you invoke** — you call them when relevant (`execute_skill`).
+- **Skills you own but never invoke** — autonomous skills fired by a `cron` or `event` trigger. Your job is to keep them correct, not to run them by hand. (They show up under `headless` in `skill_list`.)
+
+Make sure your agent instructions distinguish these, so the agent doesn't try to manually fire a cron skill (or ignore a skill it should be invoking).
+
+### Trust the approval gate
+Every skill has a `Draft → Approved → Disabled` lifecycle, and only `Approved` skills run. **In secured mode** (`SKILLSCRIPT_SECURED_MODE=true` — the recommended posture for any agent-authored or multi-author deployment) approval is an operator's Ed25519 signature: a skill an agent `skill_write`s lands **Draft**, a naked `# Status: Approved` is forced to Draft, and only a human holding the operator key can sign it into a runnable state. That's the real safety boundary — an agent can *write* a skill, but a human decides whether it ever *runs*. In unsecured mode the status flag alone gates execution (a bare `# Status: Approved` runs, unkeyed) — convenient for a single trusted author, but it means a skill *you* write as Approved is immediately runnable. Either way, tell your agent to treat a freshly-written skill as not-yet-runnable until a human has approved it.
+
+### Author against discovered capability, not assumptions
+Before writing a skill that needs a data store, a model, or an external tool, check `runtime_capabilities()`. A skill that assumes a connector that isn't wired fails at dispatch with a clear error — but it's better to author against what's actually present. Use `# Requires: <connector>.<feature>` in a skill to fail-fast at compile time when a needed capability is missing.
+
+### Keep deterministic work in tools, not skill bodies
+Skills are orchestration. A fixed API call, a fixed parse, a fixed shell pipeline belongs in an MCP tool the skill *invokes* (`$ <connector> ...`), not hardcoded into the skill. This keeps skills portable across substrates and resistant to drift.
+
+---
+
+## 3. MCP tool reference
+
+The tools your agent has when a Skillscript runtime is wired:
+
+| Tool | Use |
+|---|---|
+| `skill_list({ filter? })` | Discover skills, grouped by category. Filter by status / trigger_kind / name_prefix / author. Each entry carries the full contract (vars / returns / requires / effectful footprint) + approval state. |
+| `skill_preflight({ name })` | Pre-execution contract check for one skill: what it takes / returns / requires / touches (effectful footprint) + approval-gate state + version. Call before invoking or composing. |
+| `skill_read({ name })` | Read a skill's source body. |
+| `compile_skill({ name \| source, inputs? })` | Render the compiled plan + surface errors. Read-only — safe to preview. |
+| `lint_skill({ name \| source })` | Static diagnostics (tier-1 errors / tier-2 warnings / tier-3 advisories). |
+| `execute_skill({ name \| source, inputs? })` | Run a skill. `name` runs a stored, approved skill; `source` runs ad-hoc inline (bypasses the store — for one-offs). |
+| `skill_write({ name, source, overwrite? })` | Store a skill. Lands Draft unless approved. |
+| `skill_status({ name, new_state })` | Transition Draft / Approved / Disabled. |
+| `help({ topic? })` | Language reference — quickstart, plus `ops`, `frontmatter`, `examples`, `composition`, `error-handling`, `connectors`, `lint-codes`. |
+| `data_read({ mode, query, limit, ... })` | Query the wired DataStore — substrate-neutral memory/data retrieval (the `$ data_read` op's tool surface). |
+| `runtime_capabilities()` | What's actually wired — connectors, models, shell mode. |
+| `health_metrics()` | Aggregated runtime health — dispatch counts, error rates, per-op timing. |
+| `blocked_shell_attempts()` | Shell-allowlist refusals: which binaries skills tried to run that the allowlist blocked. |
+| `register_trigger` / `list_triggers` / `unregister_trigger` / `set_trigger_enabled` | Inspect/manage autonomous dispatch (cron / event), including enabling or disabling a registered trigger. |
+
+---
+
+## 4. A minimal worked example
+
+The smallest useful loop, from the agent's point of view:
+
+```
+1. skill_list()                    → "I have a `weekly-report` skill."
+2. compile_skill({name:"weekly-report"})  → preview the plan, confirm it's right.
+3. execute_skill({name:"weekly-report"})  → run it, use the result.
+```
+
+And authoring a new one:
+
+```
+1. help({topic:"ops"})             → learn the op surface.
+2. lint_skill({source})            → fix tier-1 errors.
+3. compile_skill({source})         → confirm it renders.
+4. skill_write({name, source})     → stored as Draft.
+5. (human approves)                → now it can run.
+```
+
+---
+
+## 5. What *not* to put in your agent file
+
+- **Don't reference a specific backend.** No "query the X store" / "call the Y model" by product name. Skills name connectors by role; the operator maps roles to backends in config. Your agent reads roles via `runtime_capabilities()`.
+- **Don't tell the agent a freshly-authored skill is runnable.** In secured mode (the recommended posture) it lands Draft until a human approves; have the agent treat anything it just wrote as not-yet-runnable regardless.
+- **Don't have the agent manually fire autonomous skills.** Cron/event skills fire themselves; the agent maintains them.
+- **Don't hardcode tool/endpoint details into skill bodies.** That's tool territory; skills orchestrate, tools execute.
+
+The throughline: your agent's instructions should make it **discover its skills, prefer them over re-reasoning, author new ones through the lint→compile→approve loop, and stay honest about what substrate is actually wired.**

package/docs/configuration.md

@@ -83,18 +83,18 @@ Once `.env` populates `process.env`, both `skillscript.config.json` (`runtime-co
 
   ```json
   {
-    "amp": {
+    "memory": {
       "class": "HttpMcpConnector",
       "config": {
-        "endpoint": "${AMP_ENDPOINT}",
-        "headers": { "Authorization": "Bearer ${AMP_TOKEN}" },
+        "endpoint": "${MEMORY_ENDPOINT}",
+        "headers": { "Authorization": "Bearer ${MEMORY_TOKEN}" },
         "identityHeader": "X-Agent-Id"
       }
     }
   }
   ```
 
-  `AMP_ENDPOINT` and `AMP_TOKEN` in `.env`; declarative shape committed to `connectors.json`.
+  `MEMORY_ENDPOINT` and `MEMORY_TOKEN` in `.env`; declarative shape committed to `connectors.json`.
 
 ### `.env` file format
 
@@ -365,7 +365,7 @@ Underscore-prefixed top-level keys (`_comment`, `_note_security`, etc.) are igno
 
 ```json
 {
-  "_comment": "Last edited 2026-05-28 — switched skill_store to sqlite for AMP-style dogfooding",
+  "_comment": "Last edited 2026-05-28 — switched skill_store to sqlite for local dogfooding",
   "substrate": { "skill_store": "sqlite" }
 }
 ```

package/docs/language-reference.md

@@ -460,11 +460,11 @@ Calls a tool through a configured connector. Connector name resolves against `co
 $ <connector>.<tool> kwarg=value, ... [-> R]
 ```
 
-The text before the dot is the connector name (must match an entry in `connectors.json`); the rest is the tool name + args. Named form is canonical for any tool whose semantics are substrate-specific — adopter MCP servers (`amp_*`, `github_*`, `linear_*`, etc.).
+The text before the dot is the connector name (must match an entry in `connectors.json`); the rest is the tool name + args. Named form is canonical for any tool whose semantics are substrate-specific — adopter MCP servers (`github_*`, `linear_*`, etc.).
 
 ```
-$ amp.amp_check_mailbox limit=20 -> MAIL
-$ amp.amp_write_memory summary="..." domain_tags=["x"] vault="private" -> ACK
+$ youtrack.search_issues query="project:INFRA state:Open" limit=20 -> ISSUES
+$ github.create_issue repo="acme/foo" title="..." body="..." -> ACK
 $ github.search_issues query="repo:acme/foo state:open" -> ISSUES
 $ linear.find_issues filter="project:INFRA" -> TICKETS
 ```
@@ -508,7 +508,7 @@ Four surfaces apply to every `$` dispatch and to `shell()` (notably `(fallback:)
 
 ```
 $ llm prompt="..." timeout=30 -> R
-$ amp.amp_olsen_task task_type="scan" timeout=120 -> DISPATCH
+$ youtrack.run_report report_id="INFRA-weekly" timeout=120 -> DISPATCH
 ```
 
 **`approved="<reason>"`** — Author-intent marker for the mutation-gate lint. Any non-empty string satisfies. Extracted at runtime; **not forwarded to the connector**. The value is required but not parsed semantically — presence is the signal.
@@ -523,7 +523,7 @@ Note: an envelope object like `{items: []}` is a non-empty object and does NOT t
 
 ```
 $ llm prompt="Classify: ${INPUT}" -> VERDICT (fallback: "unknown")
-$ amp.amp_query_memories query="${TOPIC}" -> RESULTS (fallback: [])
+$ youtrack.search_issues query="${TOPIC}" -> RESULTS (fallback: [])
 shell(argv=["gh","pr","list","--repo","acme/foo"]) -> PRS (fallback: "No open PRs")
 $ ticketing.search query="..." -> ISSUES (fallback: "search-unavailable")
 ```
@@ -590,8 +590,8 @@ $ json_parse ${RAW_JSON} -> PARSED
 ### Worked examples
 
 ```
-$ amp.amp_olsen_task task_type="scan" -> DISPATCH
-$ amp.amp_query_memories query="recent activity" limit=5 -> RECENT
+$ youtrack.run_report report_id="INFRA-weekly" -> DISPATCH
+$ github.search_issues query="repo:acme/foo updated:>2026-01-01" limit=5 -> RECENT
 $ llm prompt="Classify: ${INPUT}" timeout=30 -> VERDICT
 $ llm prompt="Summarize: ${TEXT}" model="qwen" maxTokens=500 -> SUMMARY
 $ data_read mode=fts query="${TOPIC}" limit=5 -> RESULTS (fallback: [])
@@ -601,7 +601,7 @@ $ ticketing.search query="project:INFRA state:Open" limit=20 -> ISSUES
 
 Tool args are unconstrained `key=value` pairs — the connector forwards them to the underlying MCP tool. If a dispatched call returns `isError: true`, the executor throws via `makeOpError`, which routes through the target's `else:` handler. The inner tool's error text is preserved in `result.errors[]`.
 
-**Substrate-neutrality.** Typed-contract bare ops (`$ llm`, `$ data_read`, `$ data_write`, `$ skill_*`, `$ json_parse`) are not reserved built-ins — they're typed-contract bridges the adopter wires through `substrate.local_model` / `substrate.data_store` / `substrate.skill_store` in `skillscript.config.json`. Substrate-specific tools (`$ amp.*`, `$ github.*`, etc.) are whatever the adopter declares in `connectors.json`. For external MCP servers, three bundled wiring paths cover the common cases:
+**Substrate-neutrality.** Typed-contract bare ops (`$ llm`, `$ data_read`, `$ data_write`, `$ skill_*`, `$ json_parse`) are not reserved built-ins — they're typed-contract bridges the adopter wires through `substrate.local_model` / `substrate.data_store` / `substrate.skill_store` in `skillscript.config.json`. Substrate-specific tools (`$ github.*`, `$ linear.*`, etc.) are whatever the adopter declares in `connectors.json`. For external MCP servers, three bundled wiring paths cover the common cases:
 
 - `HttpMcpConnector` — declarative wiring for any Streamable HTTP MCP server (JSON-RPC over HTTP + SSE). No subprocess. Adopters declare instances by class name in `connectors.json`.
 - `RemoteMcpConnector` — stdio bridging for MCPs distributed as spawnable binaries (YouTrack, GitHub, Linear when run locally) or HTTP MCPs adapted via `npx mcp-remote ... --sse`.
@@ -2173,7 +2173,7 @@ For *data skills* (skills marked `# Type: data`), the compile-time inline primit
 - Recursion is legal but bounded. If your design requires deeper recursion than the configured limit, reshape the workflow — almost always a sign of an iteration that should be expressed as `foreach` rather than recursion.
 
 ## Session isolation — a skill can't mutate the calling agent's session
-A skill executes in its OWN session; agent session state (context, persona) is session-local. Calling `amp_set_session_context` (or similar) inside a skill sets it for the SKILL's session, not the caller's — the caller sees no change. The contract: **skills assemble and RETURN data; the agent owns its SESSION STATE.** To "enter a project," a skill returns the instruction bodies and the AGENT applies its own session context.
+A skill executes in its OWN session; agent session state (context, persona) is session-local. Calling a session-context tool (or similar) inside a skill sets it for the SKILL's session, not the caller's — the caller sees no change. The contract: **skills assemble and RETURN data; the agent owns its SESSION STATE.** To "enter a project," a skill returns the instruction bodies and the AGENT applies its own session context.
 
 ## Static vs Dynamic — skill execution model
 
@@ -2565,5 +2565,5 @@ When any of these primitives ship, the relevant grammar moves into its canonical
 
 ---
 
-*Rendered from `skillscript/skillscript-language-reference` — 2026-07-10 13:59 EDT*  
+*Rendered from `skillscript/skillscript-language-reference` — 2026-07-10 14:34 EDT*  
 *Source of truth: AMP (`amp_render_document("skillscript/skillscript-language-reference")`)*

package/docs/sqlite-skill-store.md

@@ -21,7 +21,7 @@ SkillStore (choose which connector)
    └── Adopter-custom        (you write your own)
 ```
 
-If your substrate is AMP, Pinecone, S3, Postgres, or anything else, write a `class FooSkillStore implements SkillStore { ... }` and call `registry.registerSkillStore("primary", new FooSkillStore(...))`. The runtime is none the wiser.
+If your substrate is Pinecone, S3, Postgres, Redis, or anything else, write a `class FooSkillStore implements SkillStore { ... }` and call `registry.registerSkillStore("primary", new FooSkillStore(...))`. The runtime is none the wiser.
 
 This SqliteSkillStore is one such impl — useful as a copy-paste starting point, or directly usable if your needs match.
 
@@ -160,10 +160,10 @@ The same holds for a fork: your `store()` neither stamps nor verifies — persis
 
 When forking into your codebase:
 
-1. Rename the class (e.g., `PostgresSkillStore`, `AmpSkillStore`)
+1. Rename the class (e.g., `PostgresSkillStore`, `RedisSkillStore`)
 2. Replace the SQL with your substrate's API (HTTP, DataStore, vector DB, etc.)
 3. Update `staticCapabilities()` to match what your substrate actually supports — drop `supports_versioning` if you can't track history, drop `supports_tag_filter` if querying tags isn't tractable
-4. Update `manifest()` to describe your substrate (`kind: "amp"` or whatever)
+4. Update `manifest()` to describe your substrate (`kind: "postgres"` or whatever)
 5. **Optional but high-value for network-backed forks: implement `version()`** — a cheap store-wide change-token computed WITHOUT loading bodies (a list ETag, max-revision, or metadata digest), where any add/remove/edit/status-change moves it. It lets `skill_list` skip its N+1 catalog rebuild on unchanged polls (each entry otherwise costs a `load()` — one network round-trip per skill against a remote store). `SqliteSkillStore` hashes `(name, status, current_version)` in one body-free query. Skip it and `skill_list` just always rebuilds.
 6. Tests: copy `tests/SqliteSkillStore.test.ts` as a starting point + run the conformance suite (`SkillStoreConformance.buildTests()` from `skillscript-runtime/testing`)
 

package/examples/skillscripts/classify-support-ticket.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:49.305Z",
+  "compiled_at": "2026-07-13T21:58:37.418Z",
   "source_skill": {
     "name": "classify-support-ticket"
   },

package/examples/skillscripts/data-store-roundtrip.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:49.486Z",
+  "compiled_at": "2026-07-13T21:58:37.578Z",
   "source_skill": {
     "name": "data-store-roundtrip"
   },

package/examples/skillscripts/doc-qa-with-citations.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:49.652Z",
+  "compiled_at": "2026-07-13T21:58:37.747Z",
   "source_skill": {
     "name": "doc-qa-with-citations"
   },

package/examples/skillscripts/feedback-sentiment-scan.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:49.855Z",
+  "compiled_at": "2026-07-13T21:58:37.903Z",
   "source_skill": {
     "name": "feedback-sentiment-scan"
   },

package/examples/skillscripts/hello-world.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:50.004Z",
+  "compiled_at": "2026-07-13T21:58:38.064Z",
   "source_skill": {
     "name": "hello-world"
   },

package/examples/skillscripts/morning-brief.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:50.178Z",
+  "compiled_at": "2026-07-13T21:58:38.217Z",
   "source_skill": {
     "name": "morning-brief"
   },

package/examples/skillscripts/queue-length-monitor.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:50.377Z",
+  "compiled_at": "2026-07-13T21:58:38.381Z",
   "source_skill": {
     "name": "queue-length-monitor"
   },

package/examples/skillscripts/service-health-watch.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:50.550Z",
+  "compiled_at": "2026-07-13T21:58:38.554Z",
   "source_skill": {
     "name": "service-health-watch"
   },

package/examples/skillscripts/skill-store-roundtrip.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:50.723Z",
+  "compiled_at": "2026-07-13T21:58:38.735Z",
   "source_skill": {
     "name": "skill-store-roundtrip"
   },

package/examples/skillscripts/youtrack-morning-sweep.skill.provenance.json

@@ -2,7 +2,7 @@
   "provenance_version": "1.0",
   "language_version": "1.0",
   "compiler_version": "0.1.0-dev",
-  "compiled_at": "2026-07-10T18:06:50.897Z",
+  "compiled_at": "2026-07-13T21:58:38.894Z",
   "source_skill": {
     "name": "youtrack-morning-sweep"
   },