@synap-core/cli 1.13.0 → 1.13.1-next.20261102.4b45534

package/dist/lib/wait-state.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The state files `synap wait` writes, and the status line reads.
+ *
+ * One file per wait: `~/.synap/waits/<conversation>/<id>.json`, where the
+ * conversation is the Claude Code session id the wait ran under
+ * (`CLAUDE_CODE_SESSION_ID`, set in every Bash command an agent runs) or
+ * `_nosession`. The wait rewrites its file after every probe (tmp + rename,
+ * so a reader never sees half a file); the status line only ever reads.
+ *
+ * Local files only, no network: the status line renders from these.
+ */
+export type WaitKind = "devbox" | "pr" | "run";
+/** A wait is over once it carries `exitCode` (and `finishedAt`); `error` can be either. */
+export type WaitState = "pending" | "queued" | "running" | "passed" | "failed" | "infra" | "error" | "timeout";
+export declare function isFinal(w: Pick<WaitRecord, "exitCode">): boolean;
+export interface WaitRecord {
+    id: string;
+    kind: WaitKind;
+    /** Normalised target: the devbox job name, `owner/repo#n`, `owner/repo run <id>`. */
+    ref: string;
+    label: string;
+    pid: number;
+    startedAt: number;
+    probedAt: number;
+    changedAt: number;
+    state: WaitState;
+    detail: string;
+    /** 1 + the earlier waits in this conversation for the same kind+ref: the "looping" signal. */
+    attempt: number;
+    probeErrors: number;
+    exitCode?: number;
+    finishedAt?: number;
+}
+export declare function waitsRoot(): string;
+/** A session id as a directory name: anything outside [A-Za-z0-9_-] is dropped. */
+export declare function safeSessionDir(sessionId: string | undefined): string;
+export declare function waitsDir(sessionId: string | undefined): string;
+/** Every readable wait file of one conversation. A file that does not parse is skipped. */
+export declare function readWaits(sessionId: string | undefined): WaitRecord[];
+/** Atomic: write a sibling tmp file, then rename it over the target. */
+export declare function writeWait(sessionId: string | undefined, rec: WaitRecord): void;
+/** 1 + the earlier waits (any state) in this conversation for the same kind+ref. */
+export declare function attemptFor(existing: WaitRecord[], kind: WaitKind, ref: string): number;
+/**
+ * Remove waits that finished more than 24 h ago, and non-final ones whose
+ * process is gone and whose last probe is that old. Best-effort.
+ */
+export declare function pruneWaits(sessionId: string | undefined, now?: number): void;
+export declare function pidAlive(pid: number): boolean;
+/** How a wait is named on screen: its label, else kind + target without the Synap-core owner. */
+export declare function waitName(w: Pick<WaitRecord, "kind" | "ref" | "label">): string;
+/**
+ * A state and its detail in one phrase, never saying the state twice:
+ * "running (be-file · 1/2 done)", but "queued 2nd (light)" and
+ * "Release gate running · 2/4 done" as they are.
+ */
+export declare function stateAndDetail(state: string, detail: string): string;

package/dist/lib/wait-state.js

@@ -0,0 +1,114 @@
+/**
+ * The state files `synap wait` writes, and the status line reads.
+ *
+ * One file per wait: `~/.synap/waits/<conversation>/<id>.json`, where the
+ * conversation is the Claude Code session id the wait ran under
+ * (`CLAUDE_CODE_SESSION_ID`, set in every Bash command an agent runs) or
+ * `_nosession`. The wait rewrites its file after every probe (tmp + rename,
+ * so a reader never sees half a file); the status line only ever reads.
+ *
+ * Local files only, no network: the status line renders from these.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+export function isFinal(w) {
+    return typeof w.exitCode === "number";
+}
+const PRUNE_AFTER_MS = 24 * 60 * 60_000;
+export function waitsRoot() {
+    return path.join(os.homedir(), ".synap", "waits");
+}
+/** A session id as a directory name: anything outside [A-Za-z0-9_-] is dropped. */
+export function safeSessionDir(sessionId) {
+    const clean = (sessionId ?? "").replace(/[^A-Za-z0-9_-]/g, "");
+    return clean || "_nosession";
+}
+export function waitsDir(sessionId) {
+    return path.join(waitsRoot(), safeSessionDir(sessionId));
+}
+/** Every readable wait file of one conversation. A file that does not parse is skipped. */
+export function readWaits(sessionId) {
+    const dir = waitsDir(sessionId);
+    let names;
+    try {
+        names = fs.readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const out = [];
+    for (const n of names) {
+        if (!n.endsWith(".json"))
+            continue;
+        try {
+            const rec = JSON.parse(fs.readFileSync(path.join(dir, n), "utf-8"));
+            if (rec && typeof rec.id === "string" && typeof rec.state === "string")
+                out.push(rec);
+        }
+        catch {
+            /* a file mid-write by an older writer, or not ours */
+        }
+    }
+    return out;
+}
+/** Atomic: write a sibling tmp file, then rename it over the target. */
+export function writeWait(sessionId, rec) {
+    const dir = waitsDir(sessionId);
+    fs.mkdirSync(dir, { recursive: true });
+    const target = path.join(dir, `${rec.id}.json`);
+    const tmp = `${target}.${process.pid}.tmp`;
+    fs.writeFileSync(tmp, JSON.stringify(rec));
+    fs.renameSync(tmp, target);
+}
+/** 1 + the earlier waits (any state) in this conversation for the same kind+ref. */
+export function attemptFor(existing, kind, ref) {
+    return 1 + existing.filter((w) => w.kind === kind && w.ref === ref).length;
+}
+/**
+ * Remove waits that finished more than 24 h ago, and non-final ones whose
+ * process is gone and whose last probe is that old. Best-effort.
+ */
+export function pruneWaits(sessionId, now = Date.now()) {
+    const dir = waitsDir(sessionId);
+    for (const w of readWaits(sessionId)) {
+        const old = isFinal(w)
+            ? now - (w.finishedAt ?? w.probedAt) > PRUNE_AFTER_MS
+            : now - w.probedAt > PRUNE_AFTER_MS && !pidAlive(w.pid);
+        if (!old)
+            continue;
+        try {
+            fs.unlinkSync(path.join(dir, `${w.id}.json`));
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+export function pidAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (e) {
+        // EPERM: the process exists, it is just not ours to signal.
+        return e.code === "EPERM";
+    }
+}
+/** How a wait is named on screen: its label, else kind + target without the Synap-core owner. */
+export function waitName(w) {
+    return w.label || `${w.kind} ${w.ref.replace(/^Synap-core\//, "")}`;
+}
+/**
+ * A state and its detail in one phrase, never saying the state twice:
+ * "running (be-file · 1/2 done)", but "queued 2nd (light)" and
+ * "Release gate running · 2/4 done" as they are.
+ */
+export function stateAndDetail(state, detail) {
+    if (!detail)
+        return state;
+    return new RegExp(`\\b${state}\\b`).test(detail) ? detail : `${state} (${detail})`;
+}
+//# sourceMappingURL=wait-state.js.map

package/dist/lib/wait-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait-state.js","sourceRoot":"","sources":["../../src/lib/wait-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,IAAI,MAAM,WAAW,CAAC;AAe7B,MAAM,UAAU,OAAO,CAAC,CAA+B;IACrD,OAAO,OAAO,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC;AACxC,CAAC;AAqBD,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,MAAM,CAAC;AAExC,MAAM,UAAU,SAAS;IACvB,OAAO,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,CAAC,CAAC;AACpD,CAAC;AAED,mFAAmF;AACnF,MAAM,UAAU,cAAc,CAAC,SAA6B;IAC1D,MAAM,KAAK,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,EAAE,EAAE,CAAC,CAAC;IAC/D,OAAO,KAAK,IAAI,YAAY,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,SAA6B;IACpD,OAAO,IAAI,CAAC,IAAI,CAAC,SAAS,EAAE,EAAE,cAAc,CAAC,SAAS,CAAC,CAAC,CAAC;AAC3D,CAAC;AAED,2FAA2F;AAC3F,MAAM,UAAU,SAAS,CAAC,SAA6B;IACrD,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAChC,IAAI,KAAe,CAAC;IACpB,IAAI,CAAC;QACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,MAAM,GAAG,GAAiB,EAAE,CAAC;IAC7B,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;QACtB,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC;YAAE,SAAS;QACnC,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,OAAO,CAAC,CAAe,CAAC;YAClF,IAAI,GAAG,IAAI,OAAO,GAAG,CAAC,EAAE,KAAK,QAAQ,IAAI,OAAO,GAAG,CAAC,KAAK,KAAK,QAAQ;gBAAE,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACxF,CAAC;QAAC,MAAM,CAAC;YACP,sDAAsD;QACxD,CAAC;IACH,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,SAAS,CAAC,SAA6B,EAAE,GAAe;IACtE,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAChC,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,GAAG,CAAC,EAAE,OAAO,CAAC,CAAC;IAChD,MAAM,GAAG,GAAG,GAAG,MAAM,IAAI,OAAO,CAAC,GAAG,MAAM,CAAC;IAC3C,EAAE,CAAC,aAAa,CAAC,GAAG,EAAE,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;IAC3C,EAAE,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;AAC7B,CAAC;AAED,oFAAoF;AACpF,MAAM,UAAU,UAAU,CAAC,QAAsB,EAAE,IAAc,EAAE,GAAW;IAC5E,OAAO,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,CAAC,GAAG,KAAK,GAAG,CAAC,CAAC,MAAM,CAAC;AAC7E,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,SAA6B,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;IACxE,MAAM,GAAG,GAAG,QAAQ,CAAC,SAAS,CAAC,CAAC;IAChC,KAAK,MAAM,CAAC,IAAI,SAAS,CAAC,SAAS,CAAC,EAAE,CAAC;QACrC,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC;YACpB,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,CAAC,UAAU,IAAI,CAAC,CAAC,QAAQ,CAAC,GAAG,cAAc;YACrD,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,QAAQ,GAAG,cAAc,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;QAC1D,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,IAAI,CAAC;YACH,EAAE,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;QAChD,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,QAAQ,CAAC,GAAW;IAClC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,GAAG,IAAI,CAAC;QAAE,OAAO,KAAK,CAAC;IACrD,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC;IACd,CAAC;IAAC,OAAO,CAAC,EAAE,CAAC;QACX,4DAA4D;QAC5D,OAAQ,CAA2B,CAAC,IAAI,KAAK,OAAO,CAAC;IACvD,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,MAAM,UAAU,QAAQ,CAAC,CAA6C;IACpE,OAAO,CAAC,CAAC,KAAK,IAAI,GAAG,CAAC,CAAC,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,eAAe,EAAE,EAAE,CAAC,EAAE,CAAC;AACtE,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAAC,KAAa,EAAE,MAAc;IAC1D,IAAI,CAAC,MAAM;QAAE,OAAO,KAAK,CAAC;IAC1B,OAAO,IAAI,MAAM,CAAC,MAAM,KAAK,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,KAAK,KAAK,MAAM,GAAG,CAAC;AACrF,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synap-core/cli",
-  "version": "1.13.0",
+  "version": "1.13.1-next.20261102.4b45534",
   "description": "Connect any AI agent (Claude Code, Codex, Cursor and more) to your own Synap data pod: shared memory, structured data and human-approved changes.",
   "type": "module",
   "bin": {
@@ -19,7 +19,7 @@
   },
   "dependencies": {
     "@synap-core/hub-rest-client": "^1.1.1",
-    "@synap-core/types": "^1.12.1",
+    "@synap-core/types": "^1.12.4",
     "@synap-core/workspace-templates": ">=0.12.0 <1.0.0",
     "chalk": "^5.4.0",
     "commander": "^13.0.0",

package/skills/synap/SKILL.md

@@ -43,13 +43,13 @@ Your job is to turn unstructured input into a **connected** knowledge graph. Iso
 
 The user's Synap pod: source of truth. Tool names below are stems; your door may prefix them (`pod__ask`).
 
-1. **Recall first.** Before answering or creating, `ask`.
-2. **Capture after.** A durable fact, decision, person, task: `capture`; about the user: `remember_fact`. No private scratchpad.
-3. **Orient once.** `orient`: pending review (raise first), open sessions.
+1. **Recall first.** `get_*` a known id, else `ask`.
+2. **Capture as you go.** A decision, learning, pain (`finding`), win (`proof-point`), fact or task: `capture` it when it happens; about the user: `remember_fact`.
+3. **Orient once.** `orient`: pending review, open sessions.
 4. **Work in a session.** `start_session` or resume (playbook `templateId`); goal (TRACK): `list_tracks`, else `start_track`; work in it = `start_session` + `trackId`; 2-5 `criteria`; status moves carry `expectedStatus`; person-only: `owner:'human'` slot + `blockedReason` + `ask` (confirm/choose with 1 `recommended`/form/act/provide), then `wait_for_answer` if listed; post progress, questions and results in its room (`post_message` to `session.channelId`); your own chat may repeat them (`Q-<id8>`); chat answer → `relay_answer`, words verbatim; PR = outcome `pr-<repo>-<n>` (`ref.url`); `evaluate_session`, close open asks, `complete_session`.
 5. **Never guess a project**: pin only what the user names (`set_*_focus`).
 6. **`proposed` is success**: keep going, never retry.
-7. **Discover before inventing**: `list_profiles` / `list_capabilities`; **extend** (facet, overlay, parent), never a twin.
+7. **Discover before inventing**: `list_profiles` / `list_capabilities`; **extend**, never a twin.
 8. **One space per domain**; projects filter it (`file_into_project`, `project_use_workspace`).
 
 Depth: `load_skill` `system/synap/concepts`, `work-model`, `focus-sessions`, `from-intent`, `escalation-ladder`, `writes`.
@@ -60,32 +60,42 @@ Depth: `load_skill` `system/synap/concepts`, `work-model`, `focus-sessions`, `fr
 
 The ONE glossary; other skills point here. Word = what the user sees; internal = tools and tables.
 
-| Word                | Internal                | Answers                            | Test · e.g. · not                                                                                                                                                     |
-| ------------------- | ----------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Space**           | workspace               | which domain: kinds + tools?       | owns kinds, never done · CRM · not a project or method; findable, not emphasised                                                                                      |
-| **Project**         | project                 | what am I committed to, with whom? | ends with the commitment; spans spaces · a launch · not a task, method, or the owner's company                                                                        |
-| **Goal**            | project_tracks          | what goal am I pursuing?           | in ONE project; open while it matters, or its judge closes it with a verdict; criteria say when it is done; work = sessions · grow the newsletter · tools say "track" |
-| **Step**            | stage                   | where does this work stand?        | = the subject's status: move the thing, the step follows · legacy: steps of a goal started from a method                                                              |
-| **Work**            | focus_session           | what am I doing this sitting?      | one aim · no noun: "Start work"                                                                                                                                       |
-| **Template**        | playbook                | how do I reuse it?                 | kind DERIVED, never declared: scope session = work template (a method a session or worker follows), project = goal template (legacy); also space and rule templates   |
-| **Pack**            | suite                   | which templates come together?     | a bundle; depends on space templates, never creates a space                                                                                                           |
-| **Rule**            | automation              | what runs by itself, when?         | standing · "every Monday…" · not Approvals                                                                                                                            |
-| **Approvals**       | governance rules        | which AI writes wait for me?       | decides review vs auto, does no work                                                                                                                                  |
-| **Tools**           | capability, skill, tool | what can it act with?              | one word; the detail shows the kind                                                                                                                                   |
-| **To review**       | proposal                | what awaits my approval?           | `proposed` is success                                                                                                                                                 |
-| **Role**            | role profile + facet    | which hat does it wear?            | one role per name, pod-wide; spaces add properties by overlay; its entities show in all · client · never a twin                                                       |
-| **Thing**           | entity                  | what is being worked on?           | one kind, maybe roles · a post, a lead · never a twin for a hat                                                                                                       |
-| **Status**          | lifecycle               | where does it stand?               | ONE list per kind or role, declared on its profile; category open·active·paused·done·lost · moved only through the door (`expectedStatus`)                            |
-| **Pipeline**        | pipeline view           | what is in each status?            | computed from a lifecycle, never created · not an object                                                                                                              |
-| **Worker**          | playbook activator      | what starts work by itself?        | a method + trigger (enters status · schedule · count · manual) + size (per thing · per batch); a goal or project turns it on                                          |
-| **Inbox**           | needs-you signals       | what needs me?                     | one list: decisions, questions, routine changes, broken · not Work                                                                                                    |
-| **Questions**       | owed slot ask           | what did an agent ask me?          | an Inbox filter · answer it, the work resumes                                                                                                                         |
-| **Routine changes** | reversible proposal     | what can I approve in a batch?     | an Inbox filter · only reversible changes batch; undo says what it cannot restore                                                                                     |
-| **Broken**          | failed or stuck work    | what needs a fix?                  | an Inbox filter · a failed run, a stuck session                                                                                                                       |
-| **Library**         | data (things, files)    | what did we bring in?              | what you and your agents kept or made: things, files, imports · not a space                                                                                           |
-| **Unfiled**         | entity in no project    | what is not filed yet?             | things outside every project · file them into one                                                                                                                     |
-| **Agents**          | agent users + keys      | who acts for me?                   | Claude Code, Codex, any MCP client; each has its own page · not a Tool                                                                                                |
-| **Getting started** | first-run Home card     | what do I try first?               | goes away once done                                                                                                                                                   |
+| Word                | Internal                | Answers                               | Test · e.g. · not                                                                                                                                                         |
+| ------------------- | ----------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Space**           | workspace               | which domain: kinds + tools?          | owns kinds, never done · CRM · not a project or method; findable, not emphasised                                                                                          |
+| **Project**         | project                 | what am I committed to, with whom?    | ends with the commitment; spans spaces · a launch · not a task, method, or the owner's company                                                                            |
+| **Goal**            | project_tracks          | what goal am I pursuing?              | in ONE project; open while it matters, or its judge closes it with a verdict; criteria say when it is done; work = sessions · grow the newsletter · tools say "track"     |
+| **Step**            | stage                   | where does this work stand?           | = the subject's status: move the thing, the step follows · legacy: steps of a goal started from a method                                                                  |
+| **Work**            | focus_session           | what am I doing this sitting?         | one aim · no noun: "Start work"                                                                                                                                           |
+| **Template**        | playbook                | how do I reuse it?                    | kind DERIVED, never declared: scope session = work template (a method a session or worker follows), project = goal template (legacy); also space and automation templates |
+| **Pack**            | suite                   | which templates come together?        | a bundle; depends on space templates, never creates a space                                                                                                               |
+| **Rule**            | skill rule              | what do my agents always follow?      | a standing instruction written for agents · "always cite sources" · not an Automation, not Approvals                                                                      |
+| **Automation**      | automation              | what runs by itself, when?            | standing · "every Monday…" · not a Rule, not Approvals                                                                                                                    |
+| **Approvals**       | governance rules        | which AI writes wait for me?          | decides review vs auto, does no work                                                                                                                                      |
+| **Tools**           | capability, skill, tool | what can it act with?                 | one word; the detail shows the kind                                                                                                                                       |
+| **Card**            | cell                    | what block did I make?                | the made UI block · "a deals summary" · never Cell, Widget or Interface                                                                                                   |
+| **Display**         | renderer                | how does this kind look?              | a card bound to a kind's slot · "Change display" · Renderer stays an engine word                                                                                          |
+| **View**            | view                    | how do I look at the data?            | a saved arrangement of things · a table, a board · not a Card                                                                                                             |
+| **App**             | built-in surface        | what do I open in Synap?              | CRM, Calendar, a space's own front end · never a space, never outside software                                                                                            |
+| **Connected app**   | application             | which outside software holds a grant? | reaches the pod with a grant · not an App                                                                                                                                 |
+| **Account**         | provider connection     | which of my accounts is linked?       | a person's link to an outside service · never Connection, Connector or Integration                                                                                        |
+| **Kind**            | profile                 | what shape does a thing have?         | its fields and status list · never Data type, Schema or Profile                                                                                                           |
+| **Make**            | destination             | where do I make things?               | a view, a card, a space, an automation · pairs with Work                                                                                                                  |
+| **Get more**        | destination             | where do I add more?                  | the store · never Marketplace or Get more tools                                                                                                                           |
+| **To review**       | proposal                | what awaits my approval?              | `proposed` is success                                                                                                                                                     |
+| **Role**            | role profile + facet    | which hat does it wear?               | one role per name, pod-wide; spaces add properties by overlay; its entities show in all · client · never a twin                                                           |
+| **Thing**           | entity                  | what is being worked on?              | one kind, maybe roles · a post, a lead · never a twin for a hat                                                                                                           |
+| **Status**          | lifecycle               | where does it stand?                  | ONE list per kind or role, declared on its profile; category open·active·paused·done·lost · moved only through the door (`expectedStatus`)                                |
+| **Pipeline**        | pipeline view           | what is in each status?               | computed from a lifecycle, never created · not an object                                                                                                                  |
+| **Worker**          | playbook activator      | what starts work by itself?           | a method + trigger (enters status · schedule · count · manual) + size (per thing · per batch); a goal or project turns it on                                              |
+| **Inbox**           | needs-you signals       | what needs me?                        | one list: decisions, questions, routine changes, broken · not Work                                                                                                        |
+| **Questions**       | owed slot ask           | what did an agent ask me?             | an Inbox filter · answer it, the work resumes                                                                                                                             |
+| **Routine changes** | reversible proposal     | what can I approve in a batch?        | an Inbox filter · only reversible changes batch; undo says what it cannot restore                                                                                         |
+| **Broken**          | failed or stuck work    | what needs a fix?                     | an Inbox filter · a failed run, a stuck session                                                                                                                           |
+| **Library**         | data (things, files)    | what did we bring in?                 | what you and your agents kept or made: things, files, imports · not a space                                                                                               |
+| **Unfiled**         | entity in no project    | what is not filed yet?                | things outside every project · file them into one                                                                                                                         |
+| **Agents**          | agent users + keys      | who acts for me?                      | Claude Code, Codex, any MCP client; each has its own page · not a Tool                                                                                                    |
+| **Getting started** | first-run Home card     | what do I try first?                  | goes away once done                                                                                                                                                       |
 
 Doors: `start_track`, `start_session`, `create_rule`, `attach_facet`, `update_entity` + `expectedStatus` (a status). How they fit (sizes, workers, tenses): `work-model`.
 
@@ -150,7 +160,7 @@ A worker is a playbook **activator**, declared on the method and owned by the li
 
 ### Goals (tracks)
 
-A goal is a _track_ in every tool and field name (`start_track`, `trackId`) — say "goal" to the person; a session's one-line `goal` is its **Aim**. A goal holds an owner, a direction, instructions, the workers it turns on, and what done means (criteria, or a number measured as transitions into `done`). It has no stages. A goal can stay open as long as it matters, or finish: a person closes it with a verdict once its criteria are met (`set_track_status` `completed` + `verdict`; dropped = `archived`, with a `verdict` saying why). Your close is a proposal; a closed goal comes back only as a new version. Pause it while nobody should work on it. Work in it = `start_session` + `trackId`. A thing may count for two goals. Solo users may never need one: workers can run space-wide. Legacy: `start_stage_session` and `add_track_stage` serve old goals started from a method; never `advance_track` without the user.
+A goal is a _track_ in every tool and field name (`start_track`, `trackId`) — say "goal" to the person; a session's one-line `goal` is its **Aim**. A goal holds an owner, a direction, instructions, the workers it turns on, and what done means (criteria, or a number measured as transitions into `done`). It has no stages. A goal can stay open as long as it matters, or finish: a person closes it with a verdict once its criteria are met (`set_track_status` `completed` + `verdict`; dropped = `archived`, with a `verdict` saying why; every move sends `expectedStatus`, the status you read). Your close is a proposal; a closed goal comes back only as a new version. Pause it while nobody should work on it. Work in it = `start_session` + `trackId`. A thing may count for two goals. Solo users may never need one: workers can run space-wide. Legacy: `start_stage_session` and `add_track_stage` serve old goals started from a method; never `advance_track` without the user.
 
 **Keep the pod current (every agent, every session)** — three rules, so the next agent picks your step up from the pod alone:
 
@@ -330,7 +340,7 @@ If a close project exists, **reuse it**. Do not mint a twin. Name-match is enoug
 
 4. `synap_start_session` — **name the unit of work before you build it.** Title + goal, nothing else; the session is the room the rest of this happens in, not a form to fill. Every write you make afterwards is attributed to it automatically, so the user can open ONE object and see the whole arc instead of loose proposals with no shared story. Reuse an open session that already covers this intent (`synap_list_sessions`) rather than starting a second one. If the intent is a single fact with no structure behind it, skip the session and use the `synap` skill instead — this whole conductor is the wrong door for that.
 
-**Propose its `criteria` — do not grade yourself without them.** Two to five binary, observable statements the person can validate or rewrite ("`list_profiles` returns the `grp-run` kind"), not "the pack is good". They may equally be written by the person; what is not allowed is neither. A session with no criteria leaves you nothing to report against but your own opinion, which is how "85% complete" gets said about work nobody can check. Criteria are declarable at `synap_start_session` (as `outcomes` with `kind: 'fact'`, or the older `criteria`) and upserted later with `synap_update_session` — a session created inside a plan carries `expectedOutputs`, not criteria, so set them on the session once it exists.
+**Propose its `criteria` — do not grade yourself without them.** Two to five binary, observable statements the person can validate or rewrite ("`list_profiles` returns the `grp-run` kind"), not "the pack is good". They may equally be written by the person; what is not allowed is neither. A session with no criteria leaves you nothing to report against but your own opinion, which is how "85% complete" gets said about work nobody can check. Criteria are declarable at `synap_start_session` (as `outcomes` with `kind: 'fact'`, or the older `criteria`) and upserted later with `synap_update_session` — a session created inside a plan (`synap_capture` `sessions[]`) carries both: give each step its `criteria` with its `expectedOutputs`, and they land when the plan is approved.
 
 **A discovered prerequisite is a blocking child, not a paragraph in the same session.** When the goal cannot be finished until infrastructure exists, start that infrastructure as its own session: `parentSessionId` of the goal session, plus `suspendedIntent` — one line naming what the goal was about to do. That pair links the child (`spawned_from`) and blocks the parent (`blocked_by` the child). Work the child. Do not keep building the parent goal beside it. The parent stays open and waits; when the child is validated and closed, the parent unblocks and `suspendedIntent` is what you resume. A child that is only a slice of the same goal passes `parentSessionId` alone and does not block the parent.
 
@@ -414,7 +424,7 @@ A **goal** is a _track_ in every tool and field name (`synap_start_track`, `trac
 | new **kinds of things** no workspace owns        | a workspace (four-test, `workspace-design`) — never to represent a goal                                                                 |
 | a new long-lived commitment with its own gravity | a project — never a twin project for a goal of an existing one                                                                          |
 
-**A goal steers; its sessions verify.** A session that passes a criterion CLAIMS it; the judge accepts or sends it back — never accept your own claim. Report a lasting goal's number with `synap_update_track` `kpi: { current }`: a STATED value, stamped with when and by whom — never invent a measurement. Reaching the target nudges the person to re-aim it or close the goal; never change the target or close the goal yourself. While a goal is active, its agent may work in the spaces its project links (`synap_project_use_workspace`); pausing it suspends that, closing or dropping it ends it. Pause, resume, close (`completed` + a `verdict`) or drop (`archived`, with a `verdict` saying why) it with `synap_set_track_status`; your close is a proposal the person approves. Goal writes are governed: `proposed` is success. Installing a pack onto a project does **not** start goals — start each one.
+**A goal steers; its sessions verify.** A session that passes a criterion CLAIMS it; the judge accepts or sends it back — never accept your own claim. Report a lasting goal's number with `synap_update_track` `kpi: { current }`: a STATED value, stamped with when and by whom — never invent a measurement. Reaching the target nudges the person to re-aim it or close the goal; never change the target or close the goal yourself. While a goal is active, its agent may work in the spaces its project links (`synap_project_use_workspace`); pausing it suspends that, closing or dropping it ends it. Pause, resume, close (`completed` + a `verdict`) or drop (`archived`, with a `verdict` saying why) it with `synap_set_track_status`, sending `expectedStatus` = the status you read (`conflict` = someone moved it: re-read, decide again); your close is a proposal the person approves. Goal writes are governed: `proposed` is success. Installing a pack onto a project does **not** start goals — start each one.
 
 **Legacy: goals with steps.** A goal started from a goal template (`scope: "project"`, `playbookId` on `synap_start_track`) has re-enterable stages. Work a stage with `synap_start_stage_session` (`trackId`, optional `stageKey`); never `synap_advance_track` without the user — advancing returns an `offer` (show it, start it only on a yes). Do not create new goal templates; a new goal needs none.
 
@@ -985,6 +995,8 @@ Every write returns a `status` field:
 "denied"    → blocked, explain reason to user
 ```
 
+**`DENIED_BY_RULE` is a person's "Never".** A refusal whose reason opens with `DENIED_BY_RULE` (a write's `reason`, a run's `reasonCode`) means the person said never for this agent and this kind of act. It was not done. Do not retry it or do it another way; ask the person if it is needed. Only a pod admin can take that back, in pod admin Settings.
+
 **`"proposed"` is not an error.** It's the governance system queueing your change. When you get it:
 
 1. Tell the user exactly what was queued — use the `summary` field **verbatim**. Don't paraphrase.
@@ -1512,6 +1524,13 @@ claim cut off. Everything else goes elsewhere:
 When unsure, ask: "will this still help someone in three months, and is it a
 fact, a pitfall or a rule?" If not, it is not knowledge.
 
+### Descriptions of projects, spaces and goals
+
+A description says what the thing **is** and who it is for. A decision is
+**linked, never restated**: a restated decision goes stale the day the decision
+changes (the Synap project description repeated the 5 Oct branding split, which
+a 13 Oct decision replaced). Link the `decision` entity; let it carry the rule.
+
 ---
 
 ## Document embeds — live entities/views/cells inside markdown
@@ -1720,7 +1739,21 @@ Never rewrite a whole document to change part of it. Read it, then patch it:
    - `replace_all {content}` — the whole body; needs `baseRevision` and is
      always reviewed;
    - `set_title {title}` — renames the document (its one title). A human name,
-     never an id or a slug; the content is left as it is.
+     never an id or a slug; the content is left as it is;
+   - `insert_embed {directive, ref, props?, fallback?, sectionId? | after?}` —
+     adds an embed written for you (`synap-cell` with `{cellKey}` and its props,
+     `synap-entity` with `{id}`, `synap-view` with `{viewId}`): prefer it to
+     typing directive text. It goes at the end, at the end of section
+     `sectionId`, or after the line holding `after` (exact once). Give it a
+     `fallback` sentence: it is what the phone and exports read;
+   - `set_scope {scope}` — what a LIVING document's cells read through:
+     `{kind:"pod"}`, `{kind:"workspace", workspaceId, projectId?}`,
+     `{kind:"project", projectId}`, `{kind:"track", trackId}` or
+     `{kind:"session", sessionId}` (null clears it). Never put a scope in a
+     cell's props: the host stamps the document's scope on every cell;
+   - `set_refresher {automationId}` — binds the automation that refreshes the
+     document (null unbinds). Its runs may rewrite the document's EXISTING
+     `ai` sections without review; anything else they write is reviewed.
 
 Refused, whatever the op: changing a section whose `owner` is `human` (the AI
 never rewrites a person's words — write a new section), and removing an embed
@@ -2154,7 +2187,7 @@ A **focus session** is a named, multi-step work room where you and AI agents col
 
 **Fetch the pod's processes before you invent one.** Without `templateId`, the start door hands back the pod's existing playbooks ranked against your title and goal — the response's `playbooks` block lists `candidates` (id, name, score, and the `reason` each one matched) and applies **nothing**. Read them: if one fits, start again naming it with `templateId` (the only way a playbook binds), and if none does, go ad-hoc deliberately. Pass `templateId: null` to skip matching entirely. You can also look first, with `synap_list_playbooks` / `synap_match_playbooks`.
 
-**Declare your OUTCOMES** — `outcomes: [{ key?, label, kind, verify?, owner? }]` on `synap_start_session` / `synap_update_session` (Hub: the same field on `POST`/`PATCH /focus-sessions`). One list of what the work must yield, each one verifiable. Two kinds:
+**Declare your OUTCOMES** — a new session you start must declare at least one fact (or a deliverable with `verify`), or the start is refused (`NO_CRITERIA`); continuing an existing one needs none. `outcomes: [{ key?, label, kind, verify?, owner? }]` on `synap_start_session` / `synap_update_session` (Hub: the same field on `POST`/`PATCH /focus-sessions`). One list of what the work must yield, each one verifiable. Two kinds:
 
 - **A fact** (`kind: 'fact'`) — your definition of done, a binary, observable statement ("Typecheck passes with 0 errors"), checked by `verify` (`capability` → `judge` → `human`; default `judge`) through `synap_evaluate_session`. Two to five, not a checklist. **Propose them yourself and let the person validate or rewrite them**; they may equally be written by the person, but a session with none can only be reported on by opinion. Closing never blocks on them; unmet ones are flagged.
 - **A deliverable** (`kind: 'document'`, `'report'`, `'code'`, `'decision'`…). **Declare what the work will produce** — the documents, entities and decisions this session owes. That list is what makes "done" derivable instead of announced, and it is what the person's board shows as still outstanding. Give each a `key` (or one is derived from the label) and name it by that key from then on.
@@ -2171,10 +2204,10 @@ On `synap_update_session`, `outcomes` UPSERTS by key — a renamed label keeps i
 - **Targets get a result each.** A worker session holds its things as targets: your own move of a target marks it `done`, someone else's marks it `skipped`, and targets left at close are `skipped`. Put each outcome on its thing, not only in a summary. Model: `work-model`.
 - **Person-only steps** are an `owner: 'human'` output with a `blockedReason` and a `why` (below) — never a line buried in your reply.
 - **Room first.** Post progress, questions and results in the session room (below); your own chat may repeat them; show a question there with its short id, `Q-` + the first 8 characters of its message id (`Q-1a2b3c4d`).
-- **Grade before you say done.** `synap_evaluate_session { sessionId, evidence: { <criterionKey>: { passed, detail } } }` with the real evidence — the command output, the link, the count. Then close every question you asked that is still open (answer or withdraw it, below), then `synap_complete_session`: the pod refuses your close while your own room questions are undispositioned. Closing never blocks on criteria, but an ungraded one reads as unmeasured: a claim nobody checked.
+- **Grade before you say done.** `synap_evaluate_session { sessionId, evidence: { <criterionKey>: { passed, detail } } }` with the real evidence — the command output, the link, the count. Then close every question you asked that is still open (answer or withdraw it, below), then `synap_complete_session`: the pod refuses your close while your own room questions are undispositioned. Your `closed` close is refused (`NOT_DONE`) while a required criterion you can still check is failed or ungraded, a required outcome an agent owes (yours or a delegate's) is open and unclaimed, or a required outcome the person owes is still open: then wait for them (leave the session open or pause it). What only awaits the person's grade or review (a criterion they check, one escalated to them, an outcome you claimed, a proposal pending) never refuses and comes back as `waiting`. To close anyway, pass `reason`: it is posted as one line in the session room.
 - **The doors remind you.** `synap_update_session` and `synap_complete_session` replies (and Hub `PATCH /focus-sessions/:id` / `POST …/complete`) carry `nudges` (criteria still ungraded, no criteria, a stage never set, outputs owed by the person, and — once, on a session born without a playbook — the playbooks that fit it). `orient`'s `startHere.sessionsOwingGrade` lists your open sessions with ungraded criteria.
 - **Goal, PR, close.** File the session into the goal it serves (`trackId`: the start reply's `offers.goals` lists the project's open goals, `offers.sessions` the open sessions already on close work — continue one of those rather than opening a twin). Record each PR as an outcome `pr-<repo>-<n>` (`kind: 'pull_request'`, `ref: { url }`; `sessionId` may be left out when this conversation has exactly one open session). When every outcome is met, the reply's `nudges.readyToClose` says so: grade, then close. `synap_get_session`'s continuation carries the `goal` (end state, criteria marks, KPI), the `siblings` (parallel, before, next) and the `workUnits` (your recorded PRs and their state).
-- **Keep the books: end what you started.** `orient`'s `startHere.looseEnds` lists YOUR leftovers — sessions you opened, idle over a week; asks you left owed by the person on sessions you ended; your proposals pending over a week; automations you made that never fired — each row with the call that ends it (`close`). Close your own idle session when no person touched it and it owes the person nothing. Otherwise withdraw its asks (`retireOutput`, the person confirms) or hand them over in its room first. A close that leaves asks with the person returns `leftOwed`: only a cancel retires them, so withdraw or hand over each one — never leave one owed without saying so.
+- **Keep the books: end what you started.** `orient`'s `startHere.looseEnds` lists YOUR leftovers — sessions you opened, idle over a week; asks you left owed by the person on sessions you ended; your proposals pending over a week; automations you made that never fired — each row with the call that ends it (`close`). Close your own idle session when no person touched it and it owes the person nothing. Archive an automation you made that never ran (`automation.archive`): it applies at once; archiving anyone else's, or one that ran, is a proposal. Otherwise withdraw its asks (`retireOutput`, the person confirms) or hand them over in its room first. A close that leaves asks with the person returns `leftOwed`: only a cancel retires them, so withdraw or hand over each one — never leave one owed without saying so.
 
 **Hub Protocol REST** (for IS → backend; always include `workspaceId`):
 
@@ -2218,7 +2251,7 @@ Note: all hub-protocol writes are governance-gated server-side — a start may c
 **Asking the person.** On an `owner: 'human'` slot, add an `ask` so they answer in one tap instead of typing:
 
 - **Say it once.** The `label` is a short key (a few words: "Stripe account"), never the question and never "Decide: …". The `prompt` (confirm) or the options (choose) carry the question. `why` adds only what neither says: the fact that makes it matter, never a repeat of the label or prompt. Give each answer its consequence, and recommend one when you have a view. The person reads this card once and decides.
-- `confirm` — yes/no: `prompt` is the question; `yes` / `no` may each carry a one-line `description` of what that answer does, and ONE may be `recommended`. `choose` — 1–8 `options` (`label`, optional `value` and a one-line `description` of the consequence, at most ONE `recommended`; `allowOther: true` also takes free text). `form` — a small flat form (never a secret field). `act` — something to DO: an http(s) `url` and up to 7 `steps`. `provide` — a `connection`, `file` or `secret` handed over through the vault (you receive a reference, never the secret in the answer). A secret you asked for comes with a read for you alone, for 60 minutes: redeem the `vault://` ref (`POST /vault/redeem`). If the receipt says no agent can read it, ask for access through `POST /vault/request`.
+- `confirm` — yes/no: `prompt` is the question; `yes` / `no` may each carry a one-line `description` of what that answer does, and ONE may be `recommended`. `choose` — 1–8 `options` (`label`, optional `value` and a one-line `description` of the consequence, at most ONE `recommended`; the person can always answer in their own words instead; `allowOther: false` closes that, only for a choice code reads as a value). `form` — a small flat form (never a secret field). `act` — something to DO: an http(s) `url` and up to 7 `steps`. `provide` — a `connection`, `file` or `secret` handed over through the vault (you receive a reference, never the secret in the answer). A secret you asked for comes with a read for you alone, for 60 minutes: redeem the `vault://` ref (`POST /vault/redeem`). If the receipt says no agent can read it, ask for access through `POST /vault/request`.
 - **Which mode.** A DECISION is `confirm` (one yes/no) or `choose` — never `act`. When you have a view, mark exactly ONE answer `recommended` (a choose option, or a confirm's `yes` / `no`): the person's pick vs your recommendation is recorded, and every answered `confirm`/`choose` files a `decision` entity automatically. Recall past decisions first (`synap_ask`) so your recommendation follows the user's past choices. Use `act` ONLY for a physical/world task with `steps` (they answer "I did this"). Always add an `ask`: a human-owned slot with only `blockedReason` + `why` shows a bare "I did this" button. Example: `ask: {"mode":"choose","options":[{"label":"Ship now","recommended":true,"description":"Publishes today"},{"label":"Wait a week"}]}`, or `ask: {"mode":"confirm","prompt":"Publish the post today?","yes":{"description":"Goes live at 9:00","recommended":true},"no":{"description":"Stays a draft"}}`.
 - **How it comes back.** `act` is resolved by "I did this" (attest): the slot is done and you are woken. Every other mode goes through the answer door: the slot comes back to you with `answer.text` (a readable summary) and `answer.value`, the typed pick (`confirm` → `confirmed`, `chip` → the option, `form` → `values`, `provide` → `ref`, `text`). Act on `answer.value`, not the prose. A plain reply in the room answers a typed slot only when the ask takes text (`choose` with `allowOther`); otherwise it answers your question and the slot stays owed.
 - **Then wait — don't end your turn.** After an ask, call `wait_for_answer` with the `sessionId` (when your tools list it; an in-app agent has no such tool, the answer wakes it): it returns the moment the person answers (`status: 'answered'`, `answers[]` with `text` and the typed `value`) or after `timeoutSeconds` (default 50, max 90; Codex: 55 or less) with `status: 'timeout'` and `nextSince` — call again with `since = nextSince` to keep waiting. Without `since` you get only answers you have not picked up yet. Your read marks the answer "Picked up" for the person. If you must stop, the answer stays on the slot for your next turn.

package/skills/synap/code-skills.md

@@ -31,12 +31,22 @@ Calls an installed tool's API with ITS credential (you never see the key).
 - `tool`: the tool's name, as `synap_list_capabilities` lists it (e.g. `"apify_api"`).
 - `method`: `"GET" | "POST" | "PUT" | "DELETE"`.
 - `path`: relative to the tool's base URL. If the base URL already ends in a version (`https://api.apify.com/v2`), do NOT repeat it: `"/acts/{actorId}/runs"`, not `"/v2/acts/…"`.
-- `opts`: `{ headers?, baseUrlOverride? }`.
+- `opts`: `{ headers?, baseUrlOverride?, multipart? }`.
 
 Returns `{ status, headers, body }` on success, or `{ proposed: true, proposalId }` when the call was filed for review. It THROWS `callProvider failed: …` on a provider or auth failure. Always branch on `proposed` before reading `body`.
 
 A GET runs inline. A POST/PUT/DELETE by an agent is governed: it proposes, UNLESS the tool is one the skill declared in `requiredTools` on `synap_create_skill`. Then the verb's own approval covers it, and the run does not stop for a second review.
 
+### Pod files (`file:url`, `file:bytes`)
+
+Declare a parameter as a pod file in `parameters`: `"video": "file:url"`, `"media": "file[]:url?"`, `"attachments": "file[]:bytes?"`. The caller passes the file entity's id (a list for `file[]`). An agent's run that carries a file always waits for the person's approval.
+
+- `:url`: your code receives a signed https URL to the file. Hand it to the tool as is. It lives 15 minutes for a sync skill and 6 hours for an async one.
+- `:bytes`: your code receives a handle (`podfile:…`), not the bytes. Put it in a `callProvider` body sent to a tool the skill declared in `requiredTools`, and the pod sends the file:
+  - JSON body: the handle's slot becomes the file's base64 (`{ image: args.photo }`), at most 20 MB of files per call.
+  - `opts.multipart: true`: a `multipart/form-data` form. A handle, or a list of handles, under a key becomes file parts of that field. Every other value is a text field: `callProvider("unipile_linkedin", "POST", "/api/v1/posts", { account_id, text, attachments: args.attachments }, { multipart: true })`.
+  - A handle works only in the run that received it, and only toward the skill's own required tools. `host.fetch` never sends it.
+
 ### `hubProtocol` (reads, as the user)
 
 - `hubProtocol.getEntities({ profileSlug, limit })`: entities of one kind.
@@ -59,6 +69,10 @@ The governed write-back. Returns `{ status, proposalId, proposedEntityId, messag
 2. It can still be off: when the person who approved may not turn verbs on (the approval result says so in `refusals`), or after its code changed (an edit turns it off until approved again). `synap_list_capabilities` then shows it as `blocked: "not_enabled"` with an `enable.url`: hand that link to the user instead of running it.
 3. `console.log` goes to the pod log, not to your result: return what you need to see.
 
+## Fixing a code skill
+
+Change it in place with `synap_update_skill` (`id` or `slug`): it takes `code` (the whole new source), `parameters`, `timeoutSeconds` and `requiredTools` (the list replaces the declared set), as well as `body`, `description` and `name`. Never call `synap_create_skill` again under the same name: it is refused with the existing skill's id, because two skills with one name make a run by name ambiguous. A change to what the skill runs (code, parameters, timeout, a tool added) turns it off until the person approves it again: read `synap_list_capabilities` before running it.
+
 ## Box scripts (packages, files, Python or Node)
 
 When the work needs packages, files or another language (chart a CSV with pandas, convert a file, scrape with a headless browser), write a BOX script instead: `synap_create_skill` with `executionMode: "box"`, the script in `code` (a whole program, not a function body) and `box: { language: "python" | "node", packages: [{ name, version }], hosts: ["api.example.com"], limits? }`.

package/skills/synap/concepts.md

@@ -2,32 +2,42 @@
 
 The ONE glossary; other skills point here. Word = what the user sees; internal = tools and tables.
 
-| Word                | Internal                | Answers                            | Test · e.g. · not                                                                                                                                                     |
-| ------------------- | ----------------------- | ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Space**           | workspace               | which domain: kinds + tools?       | owns kinds, never done · CRM · not a project or method; findable, not emphasised                                                                                      |
-| **Project**         | project                 | what am I committed to, with whom? | ends with the commitment; spans spaces · a launch · not a task, method, or the owner's company                                                                        |
-| **Goal**            | project_tracks          | what goal am I pursuing?           | in ONE project; open while it matters, or its judge closes it with a verdict; criteria say when it is done; work = sessions · grow the newsletter · tools say "track" |
-| **Step**            | stage                   | where does this work stand?        | = the subject's status: move the thing, the step follows · legacy: steps of a goal started from a method                                                              |
-| **Work**            | focus_session           | what am I doing this sitting?      | one aim · no noun: "Start work"                                                                                                                                       |
-| **Template**        | playbook                | how do I reuse it?                 | kind DERIVED, never declared: scope session = work template (a method a session or worker follows), project = goal template (legacy); also space and rule templates   |
-| **Pack**            | suite                   | which templates come together?     | a bundle; depends on space templates, never creates a space                                                                                                           |
-| **Rule**            | automation              | what runs by itself, when?         | standing · "every Monday…" · not Approvals                                                                                                                            |
-| **Approvals**       | governance rules        | which AI writes wait for me?       | decides review vs auto, does no work                                                                                                                                  |
-| **Tools**           | capability, skill, tool | what can it act with?              | one word; the detail shows the kind                                                                                                                                   |
-| **To review**       | proposal                | what awaits my approval?           | `proposed` is success                                                                                                                                                 |
-| **Role**            | role profile + facet    | which hat does it wear?            | one role per name, pod-wide; spaces add properties by overlay; its entities show in all · client · never a twin                                                       |
-| **Thing**           | entity                  | what is being worked on?           | one kind, maybe roles · a post, a lead · never a twin for a hat                                                                                                       |
-| **Status**          | lifecycle               | where does it stand?               | ONE list per kind or role, declared on its profile; category open·active·paused·done·lost · moved only through the door (`expectedStatus`)                            |
-| **Pipeline**        | pipeline view           | what is in each status?            | computed from a lifecycle, never created · not an object                                                                                                              |
-| **Worker**          | playbook activator      | what starts work by itself?        | a method + trigger (enters status · schedule · count · manual) + size (per thing · per batch); a goal or project turns it on                                          |
-| **Inbox**           | needs-you signals       | what needs me?                     | one list: decisions, questions, routine changes, broken · not Work                                                                                                    |
-| **Questions**       | owed slot ask           | what did an agent ask me?          | an Inbox filter · answer it, the work resumes                                                                                                                         |
-| **Routine changes** | reversible proposal     | what can I approve in a batch?     | an Inbox filter · only reversible changes batch; undo says what it cannot restore                                                                                     |
-| **Broken**          | failed or stuck work    | what needs a fix?                  | an Inbox filter · a failed run, a stuck session                                                                                                                       |
-| **Library**         | data (things, files)    | what did we bring in?              | what you and your agents kept or made: things, files, imports · not a space                                                                                           |
-| **Unfiled**         | entity in no project    | what is not filed yet?             | things outside every project · file them into one                                                                                                                     |
-| **Agents**          | agent users + keys      | who acts for me?                   | Claude Code, Codex, any MCP client; each has its own page · not a Tool                                                                                                |
-| **Getting started** | first-run Home card     | what do I try first?               | goes away once done                                                                                                                                                   |
+| Word                | Internal                | Answers                               | Test · e.g. · not                                                                                                                                                         |
+| ------------------- | ----------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Space**           | workspace               | which domain: kinds + tools?          | owns kinds, never done · CRM · not a project or method; findable, not emphasised                                                                                          |
+| **Project**         | project                 | what am I committed to, with whom?    | ends with the commitment; spans spaces · a launch · not a task, method, or the owner's company                                                                            |
+| **Goal**            | project_tracks          | what goal am I pursuing?              | in ONE project; open while it matters, or its judge closes it with a verdict; criteria say when it is done; work = sessions · grow the newsletter · tools say "track"     |
+| **Step**            | stage                   | where does this work stand?           | = the subject's status: move the thing, the step follows · legacy: steps of a goal started from a method                                                                  |
+| **Work**            | focus_session           | what am I doing this sitting?         | one aim · no noun: "Start work"                                                                                                                                           |
+| **Template**        | playbook                | how do I reuse it?                    | kind DERIVED, never declared: scope session = work template (a method a session or worker follows), project = goal template (legacy); also space and automation templates |
+| **Pack**            | suite                   | which templates come together?        | a bundle; depends on space templates, never creates a space                                                                                                               |
+| **Rule**            | skill rule              | what do my agents always follow?      | a standing instruction written for agents · "always cite sources" · not an Automation, not Approvals                                                                      |
+| **Automation**      | automation              | what runs by itself, when?            | standing · "every Monday…" · not a Rule, not Approvals                                                                                                                    |
+| **Approvals**       | governance rules        | which AI writes wait for me?          | decides review vs auto, does no work                                                                                                                                      |
+| **Tools**           | capability, skill, tool | what can it act with?                 | one word; the detail shows the kind                                                                                                                                       |
+| **Card**            | cell                    | what block did I make?                | the made UI block · "a deals summary" · never Cell, Widget or Interface                                                                                                   |
+| **Display**         | renderer                | how does this kind look?              | a card bound to a kind's slot · "Change display" · Renderer stays an engine word                                                                                          |
+| **View**            | view                    | how do I look at the data?            | a saved arrangement of things · a table, a board · not a Card                                                                                                             |
+| **App**             | built-in surface        | what do I open in Synap?              | CRM, Calendar, a space's own front end · never a space, never outside software                                                                                            |
+| **Connected app**   | application             | which outside software holds a grant? | reaches the pod with a grant · not an App                                                                                                                                 |
+| **Account**         | provider connection     | which of my accounts is linked?       | a person's link to an outside service · never Connection, Connector or Integration                                                                                        |
+| **Kind**            | profile                 | what shape does a thing have?         | its fields and status list · never Data type, Schema or Profile                                                                                                           |
+| **Make**            | destination             | where do I make things?               | a view, a card, a space, an automation · pairs with Work                                                                                                                  |
+| **Get more**        | destination             | where do I add more?                  | the store · never Marketplace or Get more tools                                                                                                                           |
+| **To review**       | proposal                | what awaits my approval?              | `proposed` is success                                                                                                                                                     |
+| **Role**            | role profile + facet    | which hat does it wear?               | one role per name, pod-wide; spaces add properties by overlay; its entities show in all · client · never a twin                                                           |
+| **Thing**           | entity                  | what is being worked on?              | one kind, maybe roles · a post, a lead · never a twin for a hat                                                                                                           |
+| **Status**          | lifecycle               | where does it stand?                  | ONE list per kind or role, declared on its profile; category open·active·paused·done·lost · moved only through the door (`expectedStatus`)                                |
+| **Pipeline**        | pipeline view           | what is in each status?               | computed from a lifecycle, never created · not an object                                                                                                                  |
+| **Worker**          | playbook activator      | what starts work by itself?           | a method + trigger (enters status · schedule · count · manual) + size (per thing · per batch); a goal or project turns it on                                              |
+| **Inbox**           | needs-you signals       | what needs me?                        | one list: decisions, questions, routine changes, broken · not Work                                                                                                        |
+| **Questions**       | owed slot ask           | what did an agent ask me?             | an Inbox filter · answer it, the work resumes                                                                                                                             |
+| **Routine changes** | reversible proposal     | what can I approve in a batch?        | an Inbox filter · only reversible changes batch; undo says what it cannot restore                                                                                         |
+| **Broken**          | failed or stuck work    | what needs a fix?                     | an Inbox filter · a failed run, a stuck session                                                                                                                           |
+| **Library**         | data (things, files)    | what did we bring in?                 | what you and your agents kept or made: things, files, imports · not a space                                                                                               |
+| **Unfiled**         | entity in no project    | what is not filed yet?                | things outside every project · file them into one                                                                                                                         |
+| **Agents**          | agent users + keys      | who acts for me?                      | Claude Code, Codex, any MCP client; each has its own page · not a Tool                                                                                                    |
+| **Getting started** | first-run Home card     | what do I try first?                  | goes away once done                                                                                                                                                       |
 
 Doors: `start_track`, `start_session`, `create_rule`, `attach_facet`, `update_entity` + `expectedStatus` (a status). How they fit (sizes, workers, tenses): `work-model`.