@neuralis/brain-core 0.3.2 → 0.4.0

package/skills/create-package/references/skills-and-context.md

@@ -61,10 +61,10 @@ arguments:
 Target environment: {{environment}}
 
 1. Run the checks — call this with `cwd: "${SKILL_DIR}"`:
-   `bash ${SKILL_DIR}/scripts/verify.sh {{environment}}`
+   `node "${SKILL_DIR}/scripts/verify.mjs" {{environment}}`
 2. Read `${SKILL_DIR}/references/runbook.md` for the manual steps.
 
-Done when `verify.sh` exited 0 and every runbook step is finished or explicitly reported as skipped.
+Done when `verify.mjs` exited 0 and every runbook step is finished or explicitly reported as skipped.
 ```
 
 No registration call, no index file, no manifest entry: discovery finds the `SKILL.md`, sets `category: skill` from the folder, derives the id, enumerates the bundle, and turns `requiredFeatures` into the visibility gate.
@@ -115,18 +115,26 @@ lines and move detail into `references/`, one level deep, each with its own trig
 ## Ship scripts with a skill
 
 There is **no separate script runner**: scripts run through the ordinary shell —
-`execute action="shell" command="bash scripts/verify.sh production"` at the skill's own working
+`execute action="shell" command="node scripts/verify.mjs production"` at the skill's own working
 directory, which is also what selects the execution provider (a source slug is not a kind).
 
+**Write a script that must run everywhere in Node (`.mjs`).** The same skill runs under bash on
+Linux, macOS and the Docker app and under PowerShell on a Windows device, which has no bash; `node`
+is present wherever `neuralis request` is, because the CLI is a Node program. A bash script is a
+POSIX-only script — on a Windows device it needs Git for Windows. Quote the path
+(`node "${SKILL_DIR}/scripts/x.mjs"`, a Windows path may hold spaces), and pass JSON and free text
+on stdin or through the `execute` tool's `env`, never as an argument: PowerShell 5.1 strips the
+quotes inside one.
+
 **Always pass the emitted working directory** — normally `cwd: "${SKILL_DIR}"`, or, for a
 connector-backed skill, the directory URI itself (`cwd: "<source>://bundle/skills/check"`), never
-that URI rewritten as an app-container path. The default working directory is the project data
+that URI rewritten as an absolute path. The default working directory is the project data
 root, deliberately, so relative output does not land in the package tree: a body saying
-`bash scripts/verify.sh` with no `cwd` produces `No such file or directory`.
+`node scripts/verify.mjs` with no `cwd` produces a `Cannot find module` error.
 
 Body substitutions: `${SKILL_DIR}`, `${SKILL_URI}`, `${SKILL_CONNECTOR}`, `${SKILL_NAME}`, `${SESSION_ID}`, `${NEURALIS_API}`, `${SKILL_CREDENTIALS_RESOLVED}`, `${SKILL_CREDENTIALS_MISSING}`, `${MISSING:<credential-id>}` (renders `(present: id)` / `(missing: id)`).
 
-- Syntax is `${UPPER_SNAKE}` **only**. `{SKILL_DIR}` and `$SKILL_DIR` are not substitutions — they are left intact by design, the model passes the literal text to bash, bash expands it to nothing, and your script path becomes `/scripts/verify.sh`.
+- Syntax is `${UPPER_SNAKE}` **only**. `{SKILL_DIR}` and `$SKILL_DIR` are not substitutions — they are left intact by design, the model passes the literal text to the shell, the shell expands it to nothing, and your script path becomes `/scripts/verify.mjs`.
 - **Argument injection is a different syntax and runs first**: `$ARGUMENTS`, `$1`…`$N` (positional, in args-object order), `{{name}}`. Only string values substitute, and `required: true` is **not** enforced — a missing argument renders empty and the model proceeds with a half-rendered body. `$ARGUMENTS` on a no-argument activation expands to the empty string — the agentskills.io/Claude Code semantic, kept so imported skills behave here as they do at home. Write the defensive shape yourself when the empty case matters ("if the line below is empty, do X"); a bare `$N` with nothing behind it stays LITERAL (dollar amounts in prose survive).
 - Scripts must be non-interactive, answer `--help`, and bound their output. For app/host execution, an active skill’s local `SKILL_DIR` subtree is a read and cwd allowance in the shell path gate — not writable, and the only implicit path grant activation confers. Connector execution retains its provider’s gates.
 
@@ -138,10 +146,18 @@ execution: the activation envelope can supply a directory URI for an exec-capabl
 that URI with a relative script, and never pass the sentinel as `cwd`.
 
 **Authenticating back to the platform from app/host execution:** call package routes with
-`neuralis request <METHOD> <package-id>/<route>` (`-f key=value` fields, `--input -` for a JSON
-body). It authenticates with the shell's per-stream `NEURALIS_SESSION_TOKEN` — the caller’s
+`neuralis request <METHOD> <package-id>/<route>` (`-f key=value` fields; a JSON
+body as `echo '<json>' | neuralis request … --input -`, which bash and PowerShell both parse). It authenticates with the shell's per-stream `NEURALIS_SESSION_TOKEN` — the caller’s
 real identity, re-minted per call — and on a developer's own machine with their `neuralis login`;
-your script never handles the ticket itself. It reaches ONLY package routes under
+your script never handles the ticket itself. A Node script that makes several calls starts the
+CLI with no shell: `execFileSync(process.execPath, [process.env.NEURALIS_CLI_ENTRY, 'request', 'GET',
+'<package-id>/<route>'], { encoding: 'utf8' })` — every Neuralis runner exports `NEURALIS_CLI_ENTRY`,
+the CLI's own JS entry. With it absent, spawn `neuralis` directly on Linux and macOS and stop with a
+message naming the variable on Windows; never pass `shell: true` (cmd.exe re-reads every argument).
+A script that only reshapes ONE answer reads it from a pipe instead —
+`neuralis request GET <package-id>/<route> | node "${SKILL_DIR}/scripts/x.mjs"` — and must exit non-zero on an empty
+or non-JSON stdin: a non-2xx leaves stdout empty, and neither shell reports the first stage's exit
+code. It reaches ONLY package routes under
 `/api/packages/<package-id>/…`; host-level `/api/*` routes (projects, auth, admin) reject it by design. **Never invent a bearer token and never ask the user for one.** `credentials:` is for **external** secrets only — each entry is both the credential-store id and the env-var name projected into the child process. A miss is non-fatal: it renders `(missing: <id>)` and is reported in the activation result, and the model never sees a value. **Credentials pushed by an activation are scoped to the conversation and the caller, and outlive the turn**;
 app/host shell calls receive the union of the caller's still-active skills. Clear them with
 `args.deactivate=true`. **Connector execution receives no platform ticket, credential env or
@@ -150,9 +166,9 @@ entirely — never promise that a platform-authenticated script runs there uncha
 
 **`neuralis request` keeps a route's error body:** a non-2xx answer prints an `HTTP <code>` line
 and the body on stderr, leaves stdout empty and exits 1. So a script that passes the answer
-through needs nothing more, and one that consumes it (`X="$(neuralis request …)"` under `set -e`,
-or `--jq`) stops before a projection can turn the `{code,error}` your SKILL.md tells the model to
-branch on into a `jq` error. Branch on the code by reading that `HTTP` line from stderr; never send
+through needs nothing more, and one that consumes it (`execFileSync` throws on the exit 1;
+`X="$(neuralis request …)"` under `set -e`; `--jq`) stops before a projection can turn the `{code,error}` your SKILL.md tells the model to
+branch on into a `jq` error. Branch on the code by reading that `HTTP` line from stderr (`err.stderr` in Node); never send
 the stderr to `/dev/null`.
 
 **For any other HTTP call — an external API — never let curl throw away the error body: `-f` is
@@ -162,7 +178,7 @@ depends on what the script does with the response:
 
 - **passes it through** (curl's output IS the script's output) → `curl --fail-with-body -sS …`.
   The body reaches the model, the exit stays non-zero, nothing else changes. (Needs curl ≥ 7.76,
-  March 2021; the shipped container carries 8.21.)
+  March 2021; the Docker image carries 8.21 — a native host's is its own, check `curl --version`.)
 - **consumes it** (captured into a variable, or piped into a `jq` projection) → capture the status
   instead: `RESPONSE="$(curl -sS -w '\n%{http_code}' …)"`, split `STATUS` off the tail, and print
   the RAW body then `exit 1` **before** the projection runs. Under `set -e` a failing assignment
@@ -171,7 +187,7 @@ depends on what the script does with the response:
 - **is documented as being piped by its CALLER** (`my-script.sh | jq …`) → write the error body to
   **stderr**, or the caller's filter eats it exactly the same way one level up.
 
-Neuralis' own first-party bundles are swept for both rules by a static test; a package you ship
+Neuralis' own native bundles are swept for both rules by a static test; a package you ship
 should carry the equivalent check over its own `scripts/`, because nothing in the platform
 inspects a third-party script for you.
 
@@ -215,7 +231,7 @@ missed a whole class:
 
 3. **Decide "does this mutate?" from the INVOCATION LINE, never from the script
    file.** A generic helper that takes its verb as an argument —
-   `bash ${SKILL_DIR}/scripts/api.sh POST commit '{…}'` — hides its own verb
+   `node "${SKILL_DIR}/scripts/api.mjs" POST commit` — hides its own verb
    behind a positional parameter. Keyed on the file, such a helper looks like a GET
    and every one of its write routes vanishes from the audit. If you ship such a
    helper, say so in its header comment; if you audit one, read the argument.
@@ -275,7 +291,7 @@ Only `rules/` and `instructions/` inject by category. Choose a rule only for beh
 - **A file with no `activation` block is injected every turn**; the default is `always`, and **`invocation: auto` is identical to `always`** — only `manual` keeps a file out of the prompt. There is no relevance-based injection.
 - **`activation.target` accepts exactly two values**, `prompt-context` and `workspace`. Anything else — a tool-scoped selector, say — is cast through unvalidated and silently ignored, and the file still injects because its folder made it a rule. There is no tool-conditional injection.
 
-**Only an installed first-party package can ship a rule at all.** For anything else the loader sanitises at discovery: every `rules/` file is physically moved into the docs array so it can never inject, `overwrite` is forced false, and `activation.target: prompt-context` becomes `workspace`. A package found inside a synced source goes further — its rules and universal identity files (`AGENTS.md`, `CLAUDE.md`) are **default-OFF** until someone opts in per agent or per conversation, and its docs are server-pinned to manual. Design a dropped or synced package so its behaviour never depends on a rule.
+**Only an installed native package can ship a rule at all.** For anything else the loader sanitises at discovery: every `rules/` file is physically moved into the docs array so it can never inject, `overwrite` is forced false, and `activation.target: prompt-context` becomes `workspace`. A package found inside a synced source goes further — its rules and universal identity files (`AGENTS.md`, `CLAUDE.md`) are **default-OFF** until someone opts in per agent or per conversation, and its docs are server-pinned to manual. Design a dropped or synced package so its behaviour never depends on a rule.
 
 Three craft rules for the floor: **one fact, one file** — copies of the same guidance drift apart; **floor versus method** — the always-on file carries only what must be obeyed every turn and the how-to goes in a skill, but a floor must **never** live only in a skill body, because an un-activated skill loses it entirely; **never hardcode the tool, skill or source inventory into a rule** — the runtime renders it already and your copy is wrong the moment the runtime changes.
 
@@ -303,7 +319,7 @@ listed as an agent, never summonable — and a skipped file in an installed pack
 
 In both forms the agent is callable BY NAME through its declared `id`/`name`; a
 filename-identity row without one (a `commands/*.md` skill fork) is listed in `<packages>`
-but not summonable — reachable by address only (`uri`, host path, container path).
+but not summonable — reachable by address only (`uri`, host path, local path).
 
 **Same key, two jobs: `allowed-tools` is ENFORCED on an agent file and ADVISORY on a skill.**
 
@@ -337,7 +353,7 @@ Two parsers run on the same file: **discovery** keeps every top-level key, **act
 | `allowed-tools` | a CEILING on agent files (a `delegate` call intersects, never replaces); advisory on skills. Absent = inherit; `[]` = no tools. |
 | `arguments` | real `{{name}}` / `$1` substitution; not validated, `required` not enforced. |
 | `disable-model-invocation` | sets a field the overview and file catalog display. On a **skill** it gates nothing — the model can still activate it. Load-bearing only on an `instruction`/`rule`, or on a file with an explicit `activation.pinned` / `activation.target: prompt-context`. |
-| `overwrite` | carried, but no replacement semantics exist; forced off for anything not first-party. |
+| `overwrite` | carried, but no replacement semantics exist; forced off for anything not native. |
 | `hooks` | **dropped by the activation parser** — no hooks, no warning, no log line. Use the package-level `hooks.json`. |
 | `user-invocable`, `contextMode`, `agentType`, `preferredModel`, `maxSteps`, `manualOnly` | accepted (the first for ecosystem compatibility) and read by nothing today. Zero effect, zero diagnostics. |
 
@@ -358,4 +374,4 @@ Two parsers run on the same file: **discovery** keeps every top-level key, **act
 
 ---
 
-Full public reference: **https://docs.neuralisapp.com/package-system/skills** — and the five-category contribution contract at **https://docs.neuralisapp.com/package-system/contributions**.
+Full public reference: **https://docs.neuralisapp.com/package-system/skills** — and the five-category contribution contract at **https://docs.neuralisapp.com/package-system**.

package/skills/create-package/references/surfaces-and-design.md

@@ -18,7 +18,7 @@ Every surface lives in `package.json` under `neuralis.app.surfaces[]` — a unio
 | `dock` | `kind`, `id`, `label`, `action` | `icon`, `image`, `position`, `section`, `dock`, `tooltip`, `color` |
 | `card` | `kind`, `id`, `type` | `title`, `render`, `match`, `bridge` |
 
-**Every icon comes from ONE platform library** — about 270 curated lucide names in categories, the `ICON_LIBRARY` export of `@neuralis/package-system/icons`. Write the PascalCase name (`ChartLine`) or its lucide-kebab form (`chart-line`); a few aliases (`layout`, `terminal`, `admin`) also resolve. The same rule covers a surface `icon`, a team member's `appearance.icon` and a workflow template's `icon`. Any other name renders the fallback glyph, warns at load, and is an ERROR in `check-package.sh`.
+**Every icon comes from ONE platform library** — about 270 curated lucide names in categories, the `ICON_LIBRARY` export of `@neuralis/package-system/icons`. Write the PascalCase name (`ChartLine`) or its lucide-kebab form (`chart-line`); a few aliases (`layout`, `terminal`, `admin`) also resolve. The same rule covers a surface `icon`, a team member's `appearance.icon` and a workflow template's `icon`. Any other name renders the fallback glyph, warns at load, and is an ERROR in `check-package.mjs`.
 
 ## Task: ship a standing panel
 
@@ -68,7 +68,7 @@ The smallest complete, **reachable** UI a project-dropped package can ship. Four
 
 **Gate the widget, not the dock entry** — dock visibility inherits the target widget's `requires.features` automatically. Duplicating `requires` only creates drift: a user holding the widget's features but not your accidentally-different dock feature gets a widget they can never open.
 
-**An app picture is optional: `"image": "app/shared/<name>.png"`.** A PNG, JPEG or WebP under `app/shared/`, at most 256 KiB, each path segment letters, digits, `.`, `_` or `-`. The dock, the app menu and the inbox show it in a fixed-size box to whoever can see the dock entry; keep the `icon` glyph — it renders until the picture arrives and whenever it cannot be shown. The platform judges the BYTES, never the extension: an SVG, a renamed document or an oversized file is not served and the glyph stays. An invalid path (absolute, remote, outside `app/shared/`, `..`, a non-raster extension) is a validation error that fails the whole package. `check-package.sh` checks the path, the file and its bytes.
+**An app picture is optional: `"image": "app/shared/<name>.png"`.** A PNG, JPEG or WebP under `app/shared/`, at most 256 KiB, each path segment letters, digits, `.`, `_` or `-`. The dock, the app menu and the inbox show it in a fixed-size box to whoever can see the dock entry; keep the `icon` glyph — it renders until the picture arrives and whenever it cannot be shown. The platform judges the BYTES, never the extension: an SVG, a renamed document or an oversized file is not served and the glyph stays. An invalid path (absolute, remote, outside `app/shared/`, `..`, a non-raster extension) is a validation error that fails the whole package. `check-package.mjs` checks the path, the file and its bytes.
 
 ## Task: pick a renderer
 
@@ -76,17 +76,17 @@ The smallest complete, **reachable** UI a project-dropped package can ship. Four
 
 | renderer | validates for | how it renders |
 |---|---|---|
-| `direct` | `access.trust: "first-party"` only — hard error otherwise | compiled React the package's **own** host entrypoint registers |
-| `iframe` | any trust with a **relative** url; an absolute (`https://`, `//`, leading `/`) url needs trusted or first-party | a sandboxed document — every non-first-party path |
-| `mcp` | trusted or first-party; widgets only, **rejected on cards** | a marker for imported external surfaces, not an authoring target |
+| `direct` | `access.trust: "native"` only — hard error otherwise | compiled React the package's **own** host entrypoint registers |
+| `iframe` | any trust with a **relative** url; an absolute (`https://`, `//`, leading `/`) url needs trusted or native | a sandboxed document — every non-native path |
+| `mcp` | trusted or native; widgets only, **rejected on cards** | a marker for imported external surfaces, not an authoring target |
 
-**Use `iframe` with a relative url for a dropped package, `direct` for an installed first-party one.** A project-dropped package is pinned untrusted at scan and capped at trusted; it can **never** be first-party, so `direct` stays unavailable even after an admin trust elevation. In a dropped package a missing `access.trust` is a warning and the package is treated as untrusted — `direct` in its trust-less manifest fails too. And `direct` is only half a declaration: the manifest entry alone renders nothing, because the host never imports package TSX — the package's own `install…HostComponents` entrypoint is what registers the component, and a first-party package ships that entrypoint as a prebuilt module named in `app.module` (built with `neuralis-build ui`).
+**Use `iframe` with a relative url for a dropped package, `direct` for an installed native one.** A project-dropped package is pinned untrusted at scan and capped at trusted; it can **never** be native, so `direct` stays unavailable even after an admin trust elevation. In a dropped package a missing `access.trust` is a warning and the package is treated as untrusted — `direct` in its trust-less manifest fails too. And `direct` is only half a declaration: the manifest entry alone renders nothing, because the host never imports package TSX — the package's own `install…HostComponents` entrypoint is what registers the component, and a native package ships that entrypoint as a prebuilt module named in `app.module` (built with `neuralis-build ui`).
 
 An absolute url also needs the remote page to permit framing — `X-Frame-Options: DENY` or `frame-ancestors 'none'` (most large SaaS, banks, mail providers) renders blank whatever the host allows; drive those through the virtual-desktop / browser-automation capability instead.
 
 ### The entry lives in its own root, and it is self-contained
 
-Two rules decide whether a relative `iframe` surface loads at all. Both are checked by `check-package.sh` before you ship.
+Two rules decide whether a relative `iframe` surface loads at all. Both are checked by `check-package.mjs` before you ship.
 
 **1. The canonical root.** Every asset-backed entry lives under its **own** dedicated directory:
 
@@ -159,7 +159,7 @@ The frame mounts `sandbox="allow-scripts allow-forms"` — deliberately **withou
 
 **Nothing is pushed into a widget iframe.** There is no host→widget message channel: the frame posts nothing and listens for nothing. **A card is different** — see the next section: a sandboxed card gets a bounded, identity-free, strictly one-way `neuralis:card-data/v1` feed. **Do not write a widget that waits for a message**; it will wait forever.
 
-The privileged `window.neuralis` JSON-RPC bridge (`submitApproval`, `requestData`) is a separate, opt-in layer for **cards**, gated by `bridge: { enabled: true }`, restricted to trusted/first-party, and further restricted at runtime to a **remote HTTPS origin that differs from the host's** — an untrusted package opting in is a hard validation error, and a host-served or same-origin frame is refused the bridge fail-closed even when trusted.
+The privileged `window.neuralis` JSON-RPC bridge (`submitApproval`, `requestData`) is a separate, opt-in layer for **cards**, gated by `bridge: { enabled: true }`, restricted to trusted/native, and further restricted at runtime to a **remote HTTPS origin that differs from the host's** — an untrusted package opting in is a hard validation error, and a host-served or same-origin frame is refused the bridge fail-closed even when trusted.
 
 Asset serving is authenticated per request, scope-bound, traversal-safe, `Cache-Control: private, no-store`, `Referrer-Policy: no-referrer`, capped at 2 MiB per asset, and limited to an extension allowlist (html, css, js, mjs, map, json, images, fonts, txt) — `.ts`/`.tsx` are excluded so package internals never leak. Every asset carries a hard CSP: `default-src 'none'`, `script-src`/`style-src` `'self' 'unsafe-inline'` (an entry's own inline script and style are the point), `img-src 'self' data: blob:`, `font-src 'self' data:`, `connect-src 'self'`, `form-action 'none'`, `base-uri 'self'`, `frame-ancestors 'self'` and `sandbox allow-scripts allow-forms`. That last directive mirrors the sandbox attribute the frame already carries, so it costs your surface nothing — what it buys is that the document stays in an opaque origin even if it is ever opened *outside* the workspace frame. No CDN script, no remote font, no third-party XHR target — every source list is `'self'`-based, and in an opaque sandboxed document `'self'` resolves to the origin that served the document, which is what lets a bundle surface's own same-origin files load. So two shapes work and no others: **a single self-contained document**, or **one document plus its own sibling files under `assetMode: "bundle"`**.
 
@@ -193,7 +193,7 @@ Transparency resolves per-instance override → manifest `chrome.transparent`
 
 A card binds to a tool through the tool's `x-neuralis.ui.cardType` matching the card's `type`: the handler returns `structuredContent`, the host resolves a card type, the registry maps it to a component, it renders inline in chat. An unknown card type falls back to a generic default card with a console warning. Three names must agree — the tool's `ui.cardType`, the card surface's `type`, and, for `direct`, the type your host entrypoint registered. **Render `running`, `success` and `error`**, or the card shows nothing while the tool runs and nothing when it fails.
 
-**While the tool call is still streaming, `tool.input` is a partial JSON STRING, not the parsed object — a `direct` card must never `JSON.parse` (or whole-string-regex) it per delta.** That is O(n²) across a large call and a real per-commit performance cost class in the timeline. Use the exported streaming helpers from `@neuralis/agent-core/app/chat` instead: `previewInput(input, isPending)` for the standard bounded input preview, `extractStreamingField(input, field)` to stream ONE named string field (a command, a task, a question) progressively into your header or body — it reads the settled object and the partial buffer alike — `extractSettledArrayItems(input, field)` to list the already-closed elements of ONE array field while it streams, and `parseSettledObject(input)` as the O(1) "is it complete?" gate before your one real parse. None of them truncates the input; iframe cards need none of this (the `card-data/v1` snapshot already delivers the bounded streaming input).
+**While the tool call is still streaming, `tool.input` is a partial JSON STRING, not the parsed object — a `direct` card must never `JSON.parse` (or whole-string-regex) it per delta.** That is O(n²) across a large call and a real per-commit performance cost class in the timeline. Use the exported streaming helpers from `@neuralis/agent-core/app/chat` instead: `previewInput(input, isPending)` for the standard bounded input preview, `extractStreamingField(input, field)` to stream ONE named string field (a command, a task, a question) progressively into your header or body — it reads the settled object and the partial buffer alike — `extractSettledArrayItems(input, field)` to list the already-closed elements of ONE array field while it streams (and `extractStreamingArrayTail(input, field)` for the element still open), and `parseSettledObject(input)` as the O(1) "is it complete?" gate before your one real parse. None of them truncates the input; iframe cards need none of this (the `card-data/v1` snapshot already delivers the bounded streaming input).
 
 Cards may declare `match.state: "interaction-required" | "approval-required"`. An **approval card is preview-only** — the host wraps it with approve/deny chrome. Painting your own approve/deny buttons is a **warning, not a rejection** (the validator cannot scan HTML statically), so the package loads, ships duplicate controls, and users click a button that does nothing.
 
@@ -209,9 +209,9 @@ A sandboxed `iframe` card — and **only** a card — receives the tool's own da
 
 **The channel is owner-gated.** Only a card whose registration is bound to its **own** package's tool receives the real input and result; a cardType that matches a foreign package's tool, or that no owner claims, gets a safe generic placeholder instead. This is not a cross-package data channel.
 
-**The host owns the performance, not your card — with ONE exception: your card's height.** Stream pacing, coalescing, virtualizer retention and the single multiplexed realtime hub are all host-side. Do not write a scheduler, a keep-alive or a per-card `EventSource` into a card — a handful of per-surface streams exhausts the browser's connection pool, and a card that re-renders on every delta is what the host's pacing exists to prevent. And bound your MOUNT cost to what is visible: a compact body clipped at ~90px shows only a handful of rows, so do not mount hundreds of row elements into it (clamp the element count while collapsed and render the full set on expand — the first-party diff card renders 8 rows collapsed, 200 expanded), and defer any mount-time network fetch to idle or to expand so a fast scroll over your cards is not a request burst — and cache the fetch RESULT (the negative "nothing there" answer included) in a bounded module-level map keyed by stable identity, because the timeline remounts your card on every scroll-back and idle deferral alone only delays the refetch, it does not remove it.
+**The host owns the performance, not your card — with ONE exception: your card's height.** Stream pacing, coalescing, virtualizer retention and the single multiplexed realtime hub are all host-side. Do not write a scheduler, a keep-alive or a per-card `EventSource` into a card — a handful of per-surface streams exhausts the browser's connection pool, and a card that re-renders on every delta is what the host's pacing exists to prevent. And bound your MOUNT cost to what is visible: a compact body clipped at ~90px shows only a handful of rows, so do not mount hundreds of row elements into it (clamp the element count while collapsed and render the full set on expand — the native diff card renders 8 rows collapsed, 200 expanded), and defer any mount-time network fetch to idle or to expand so a fast scroll over your cards is not a request burst — and cache the fetch RESULT (the negative "nothing there" answer included) in a bounded module-level map keyed by stable identity, because the timeline remounts your card on every scroll-back and idle deferral alone only delays the refetch, it does not remove it.
 
-The exception exists because the host CANNOT know it. The timeline is virtualized, so it must reserve a height for a row it has not measured yet, and reserving the wrong amount is exactly what makes a chat list jump when a card appears. That guess used to live in a host-side table that knew only the built-in cards; everything else shared one constant, measured wrong by up to 579px. A **first-party `direct` card registered from your own host entrypoint** may therefore pass an `estimateHeight` model next to its renderer and mount policy:
+The exception exists because the host CANNOT know it. The timeline is virtualized, so it must reserve a height for a row it has not measured yet, and reserving the wrong amount is exactly what makes a chat list jump when a card appears. That guess used to live in a host-side table that knew only the built-in cards; everything else shared one constant, measured wrong by up to 579px. A **native `direct` card registered from your own host entrypoint** may therefore pass an `estimateHeight` model next to its renderer and mount policy:
 
 ```tsx
 // module scope — NOT an inline arrow at the call site
@@ -235,7 +235,7 @@ Every rule below has already been violated at least once in this codebase:
 - Keep it a **module-level reference**. The registry compares estimators by identity to decide whether a re-registration changed anything; a fresh closure per call turns every reconcile pass into a replace, a fingerprint bump and a retained-View eviction.
 - Keep it **cheap and pure** — it runs inside the virtualizer's measurement arithmetic, for every unmeasured row, on every offset rebuild (and that rebuild sits in a pre-paint `flushSync` window, so an unmemoized parse is scroll jank). If it parses the payload, memoize by `tool` reference **together with every input the result depends on — the `status` it was computed at AND the wrap width**: the tool object mutates BY REFERENCE across pending→settle during a live stream, so a reference-only memo keeps serving the pending-era "Running…" height after the tool settles, and a memo that forgets the width keeps serving the previous panel size after a resize — silently cancelling your `widthScale` branch. Store `{ status, charsPerLine, height }` and recompute when either changes.
 - Compute it **from the same data the component renders from**, ideally by calling the same parser. An estimator that models a different shape than the renderer is worse than none. For text bodies, count lines with the exported `countRenderedLines(text, charsPerLine)` (from `@neuralis/agent-core/app/chat`) — a flat `ceil(length / charsPerLine)` cannot see hard newlines and understated a real markdown row by ~3× (the measured worst overlap source in the timeline) — and pass a `charsPerLine` you have scaled to the live panel, never the bare constant (see the width rule below).
-- **When unsure, round UP — and never return your COMPACT height for an expanded row.** Rows are absolutely positioned, so the next row sits at your row's offset plus your CACHED height: an over-estimate leaves a gap that closes on the first measurement, an under-estimate paints the next row on top of yours. If your card can expand, branch on `disclosure` and model the expanded body too. Skipping that branch is the worst measured bug in this whole surface — a first-party card estimated at 114px while rendering 1479px expanded.
+- **When unsure, round UP — and never return your COMPACT height for an expanded row.** Rows are absolutely positioned, so the next row sits at your row's offset plus your CACHED height: an over-estimate leaves a gap that closes on the first measurement, an under-estimate paints the next row on top of yours. If your card can expand, branch on `disclosure` and model the expanded body too. Skipping that branch is the worst measured bug in this whole surface — a native card estimated at 114px while rendering 1479px expanded.
 - **Scale every characters-per-line constant by `widthScale`, because "round up" depends on how wide the panel is.** A chat panel is not one width: it is split, resized, docked and widened, and a constant calibrated at one width crosses into the *under*-reserve half of the rule above at every narrower one — measured live, one real row rendered 1251px in a 350px column while the fixed estimate reserved 792px, a 459px shortfall that paints the following row on top of it. Multiply your own constant with the exported `scaleCharsPerLine(authored, widthScale)` (same import as `countRenderedLines`) and use the result everywhere you count lines. Do NOT invent your own formula from the number: it is a ratio against the width the platform's constants were authored at, and the helper carries the degenerate-width floor.
 
 `disclosure` carries the row's remembered expand/collapse state when it differs from your default; read it only if your card renders at two heights. `widthScale` carries how wide the row surface is relative to that authored reference width (`1` IS the reference; a narrow panel is below it, a wide one above). **Both are optional and an absent `widthScale` means `1`** — an estimator that ignores it behaves exactly as it did before the field existed, so an imported card needs no changes; reading it is purely an improvement to your card's first paint.
@@ -246,7 +246,7 @@ Declaring nothing is a legitimate choice: a REGISTERED card without a model gets
 
 ### Task: land your card's activity on the composer's Changes & Actions panel
 
-Above the chat composer sits the Changes & Actions panel — the per-conversation aggregation of tool activity (Changes / Todos / Actions / Delegates tabs + the post-stream summary chip of changed files). Which tab your card's activity lands on is declared by the card, through the SAME registration that carries `estimateHeight` — the aggregation surfaces iterate the card registry and hardcode nothing (the first-party filesystem card declares its own contract from its own package the same way).
+Above the chat composer sits the Changes & Actions panel — the per-conversation aggregation of tool activity (Changes / Todos / Actions / Delegates tabs + the post-stream summary chip of changed files). Which tab your card's activity lands on is declared by the card, through the SAME registration that carries `estimateHeight` — the aggregation surfaces iterate the card registry and hardcode nothing (the native filesystem card declares its own contract from its own package the same way).
 
 **Direct lane** — pass a `composer` contract in `registerCardComponent`:
 
@@ -272,7 +272,7 @@ registerCardComponent('thing.result', ThingCard, {
 
 **Manifest lane** (`iframe` cards, no JS): declare the minimal subset on the card surface — `"composer": { "tab": "changes", "badgeField": "label", "pathField": "uri" }`. `tab` targets EXISTING builtin tabs only (a manifest can never create a tab); `badgeField`/`pathField` name TOP-LEVEL `structuredContent` fields (string, or string[] for `pathField`) that the host compiles into the same generic extractors. An invalid composer block is a validation ERROR that sinks the package; a `composer` on a `direct`-renderer surface is a WARNING and is **ignored** — the direct lane's contract has ONE owner, your install-file registration, never the manifest.
 
-## First-party `direct` surfaces
+## Native `direct` surfaces
 
 `component.import` resolves through a client-side host registry the package populates from its runtime UI module: declare `app.module`, build `app/host.tsx` with `neuralis-build ui`, and the host imports the module and calls each `install…HostComponents({ registry, port })` export with a registry that accepts only your own package's registrations. Every `component.import` your manifest declares must be registered somewhere under `app/`, or the surface resolves to null and shows the placeholder — no error. A module built before a platform upgrade can be refused (its record names an older host API or no React major): rebuild it with `neuralis-build ui`.
 
@@ -288,7 +288,7 @@ import { SkillLauncher } from '@neuralis/package-system/client';
 <SkillLauncher
   skill="manage-things"                 // the ACTIVATION id (SKILL.md frontmatter `name`)
   packageId="@neuralis/your-package"    // the REGISTRY id — manifest `neuralis.id`
-  scripts={['scripts/list.sh']}         // optional: prefill specific bundle scripts
+  scripts={['scripts/list.mjs']}        // optional: prefill specific bundle scripts
   label="Do this with the agent"
   icon="wand"
   variant="icon"                        // 'icon' | 'label' | 'row'
@@ -306,7 +306,7 @@ Four rules, each of which has already cost someone a debugging session:
 
 ## Verify
 
-Run `bash ${SKILL_DIR}/scripts/check-package.sh <package-root>` first: the canonical entry root, the renderer profile and the self-containment rule are all checked there, and self-containment can be checked **nowhere else** — the load-time validator receives the manifest object with no package root and no filesystem, and the platform blocks nothing at runtime.
+Run `node "${SKILL_DIR}/scripts/check-package.mjs" <package-root>` first: the canonical entry root, the renderer profile and the self-containment rule are all checked there, and self-containment can be checked **nowhere else** — the load-time validator receives the manifest object with no package root and no filesystem, and the platform blocks nothing at runtime.
 
 Then fetch the runtime snapshot with the `x-project-id` header and confirm it lists **both** surfaces — the widget *and* the dock entry. Open it as the **least-privileged role that should have access**: feature-gated surfaces are hidden, never greyed out, so testing as the owner hides every gate bug. Finally look at the rendered surface itself — an unstyled panel is the signature of a subresource that was never served.
 

package/skills/create-package/references/team-and-workflows.md

@@ -42,7 +42,7 @@ Discovery scans `team/*/` at package root and walks `identity/**` and `files/**`
 
 That is the whole surface — **unknown keys are dropped silently.** The traps:
 
-- **There is no top-level `icon`, `color`, `model`, `allowedTools`, `blockedTools` or `tags`.** Appearance nests under `appearance`; the model pin is `config.settings.defaultModelId`; the permission-profile default is `config.settings.guardProfile` (`safe` | `balanced` | `auto`); the loop cap is `config.settings.maxSteps` — **omit it unless this coworker must be capped BELOW the platform**, because a pin can only ever LOWER the live `maxAgentSteps` ceiling, never raise it, and an unpinned agent runs AT the ceiling (both first-party team members ship unpinned for exactly this reason); tool restriction is `config.tools` (`mode: "all" | "custom"` + `selected[]` + per-tool `overrides`; an `owners` choice is stripped from a template — which package answers a shared tool name is picked per agent, inside its project). A top-level `icon` renders the default avatar and reports **no error at all**; `appearance.icon` takes a platform icon-library name (`surfaces-and-design.md`, the icon rule under "All UI is one array").
+- **There is no top-level `icon`, `color`, `model`, `allowedTools`, `blockedTools` or `tags`.** Appearance nests under `appearance`; the model pin is `config.settings.defaultModelId`; the permission-profile default is `config.settings.guardProfile` (`safe` | `balanced` | `auto`); the loop cap is `config.settings.maxSteps` — **omit it unless this coworker must be capped BELOW the platform**, because a pin can only ever LOWER the live `maxAgentSteps` ceiling, never raise it, and an unpinned agent runs AT the ceiling (both native team members ship unpinned for exactly this reason); tool restriction is `config.tools` (`mode: "all" | "custom"` + `selected[]` + per-tool `overrides`; an `owners` choice is stripped from a template — which package answers a shared tool name is picked per agent, inside its project). A top-level `icon` renders the default avatar and reports **no error at all**; `appearance.icon` takes a platform icon-library name (`surfaces-and-design.md`, the icon rule under "All UI is one array").
 - **`description` is the field the model reads; `descriptionForModel` reaches no prompt.** `description` is copied onto the provisioned agent and rendered in the workspace block's agent list, so every agent in the project sees it — write the *"pick this coworker when…"* sentence there. Fill `descriptionForModel` too (right slot, costs nothing), but never rely on it for coworker selection.
 - **`role` is priority-checked at provisioning, not cosmetic.** A caller may only provision a role equal to or weaker than their own (lower is stronger: owner 1, admin 2, manager 10, member 20, viewer 30; a custom role declares its own number in 1..99, and an unrecognised name resolves to the weakest tier and is always assignable). Name a template role `admin` or `owner` and provisioning **throws** for every ordinary member — the package installs and its coworker cannot be hired.
 - **`permissions` grants nothing.** `permissions.features` is a **visibility** gate — a caller lacking them never sees the member in the team catalogue; `permissions.sources` is display-only. Real scope comes from the caller's own role and features plus the package `uriPolicies`.
@@ -184,4 +184,4 @@ Installing a template is always **explicit**: it instantiates a mutable entry ow
 
 ---
 
-Public reference: [Workflows](https://docs.neuralisapp.com/agent-core/workflows) · [Contributions, including team members](https://docs.neuralisapp.com/package-system/contributions) · [Agent files and delegation](https://docs.neuralisapp.com/agent-core/agents)
+Public reference: [Workflows](https://docs.neuralisapp.com/agent-core/workflows) · [Contributions, including team members](https://docs.neuralisapp.com/package-system/team) · [Agent files and delegation](https://docs.neuralisapp.com/agent-core/agents)

package/skills/create-package/references/test-and-ship.md

@@ -21,7 +21,7 @@ All three must be true. Two is not done.
 3. **The structure is what you intended** —
    `fs_list({ uri: "packages://<slug>", recursive: true })`.
 
-Pre-flight, before you ship: `bash ${SKILL_DIR}/scripts/check-package.sh <package-root>`. It picks
+Pre-flight, before you ship: `node "${SKILL_DIR}/scripts/check-package.mjs" <package-root>`. It picks
 its mode from disk and prints which one it ran: a `package.json` carrying a `neuralis` block (or a
 `neuralis.package.json`) is **manifest mode**; no manifest at all is **markdown mode** — the
 source-package / bare-skill layout, which **is** checkable.
@@ -37,7 +37,7 @@ SKIPPED — manifest, tools, workflows, app surfaces, runtime, dist — so nothi
 when it was not. Exit `0` no errors · `1` errors · `2` usage. Passing proves nothing about loading
 or discovery, in either mode.
 
-After the restart, rescan or sync: `bash ${SKILL_DIR}/scripts/verify-loaded.sh <package-id>` — the
+After the restart, rescan or sync: `node "${SKILL_DIR}/scripts/verify-loaded.mjs" <package-id>` — the
 manifest id for (a), the instance URI for (b) and (c) (§2).
 
 ---
@@ -59,7 +59,7 @@ Three `partial` reasons exist, and only three:
   valid emitted route manifest. Routes fail closed rather than being served ungated. Rebuild.
 - **`runtime-unavailable`** — the code runtime failed to start (a sandbox load failure, or an MCP
   subprocess that would not spawn).
-- **`untrusted-node`** — a non-first-party package left `runtime.type` at its `node` default while
+- **`untrusted-node`** — a non-native package left `runtime.type` at its `node` default while
   shipping code. Declare `"runtime": { "type": "wasm" }` and rebuild. The most misread state in the
   system: markdown contributions still appear, so it looks like it half worked.
 
@@ -71,7 +71,7 @@ has no status, no `reason` of that kind and no load line — done-gate step 1 fo
 the packages overview", not "it loaded". It is listed there under `sourcePackages[]`, keyed by its
 instance id: the package ROOT's URI, no trailing slash, plus `?project=<p>&scope=<scope>`. A
 package rooted at `data://acme-pack` is `data://acme-pack?project=<p>&scope=project`; one at the
-source root itself is `data://?project=<p>&scope=project`. Pass that id to `verify-loaded.sh` and it prints the root, the
+source root itself is `data://?project=<p>&scope=project`. Pass that id to `verify-loaded.mjs` and it prints the root, the
 grouping reason and the per-category file counts in place of a status.
 
 Where to read it without server-log access:
@@ -88,7 +88,7 @@ is read — caller-supplied identity is not an auth mechanism anywhere on this p
 
 Entries carry `{ packageId, status, reason?, error?, trust, registered }`. The route is gated on
 the `core.observe` feature: **a `403` here means you lack the diagnostics capability, not that the
-package is missing.** Treat those as two different outcomes — `verify-loaded.sh` wraps this exact
+package is missing.** Treat those as two different outcomes — `verify-loaded.mjs` wraps this exact
 call and makes that split for you.
 
 ---
@@ -129,9 +129,9 @@ nothing:
    one everybody skips.
 5. **It activates**, and `${SKILL_DIR}` resolves to a real path. The placeholder falls back to a
    sentinel string only when the skill has no host-side directory at all — a source-contributed
-   skill whose connector exposes no container path. An installed package and a project-folder drop
+   skill whose connector exposes no local path. An installed package and a project-folder drop
    both resolve real directories.
-6. **A bundled script runs**: `bash ${SKILL_DIR}/scripts/<name>.sh`.
+6. **A bundled script runs**: `node "${SKILL_DIR}/scripts/<name>.mjs"`.
 
 ---
 
@@ -165,7 +165,7 @@ it loads, the snapshot lists it, and the panel is blank or unstyled. Work the ma
 
 | Check | How | What it catches |
 |---|---|---|
-| The pre-flight is clean | `bash ${SKILL_DIR}/scripts/check-package.sh <root>` | the canonical entry root, a removed renderer, a conflicting card profile, and the **self-containment** rule — which nothing else can check (see below) |
+| The pre-flight is clean | `node "${SKILL_DIR}/scripts/check-package.mjs" <root>` | the canonical entry root, a removed renderer, a conflicting card profile, and the **self-containment** rule — which nothing else can check (see below) |
 | The surface is in the snapshot | fetch the runtime snapshot with the `x-project-id` header | `meta.hosts` missing `neuralis-workspace`; a dropped untrusted absolute url |
 | The widget is **reachable** | the dock rail shows the companion item and it opens the panel | a widget with no `kind: "dock"` sibling — validates, loads, opens for nobody |
 | The card **appears** on a real tool call | run the tool in chat | the `ui.cardType` ↔ card `type` ↔ (for `direct`) registered-type triple; a mismatch silently renders the generic default card |
@@ -177,7 +177,7 @@ it loads, the snapshot lists it, and the panel is blank or unstyled. Work the ma
 
 **Least trust, deliberately.** Test the surface at the tier it will actually ship on. A dropped
 package is pinned untrusted: `direct` is unavailable to it, an absolute iframe url is dropped
-fail-closed, and the privileged bridge is a hard validation error. Proving a surface as first-party
+fail-closed, and the privileged bridge is a hard validation error. Proving a surface as native
 and shipping it untrusted is the same class of mistake as testing gates as the owner.
 
 **Self-containment can only be proven here.** The load-time validator receives the manifest
@@ -243,7 +243,7 @@ it('denies a caller who does not — via the dispatcher, where the gate lives',
 Other helpers, with the details that bite:
 
 - `createMockInitContext({ packageSlug, dataDir?, globalDir?, projectsRoot?, logger?, hostId?, apis? })` — the
-  context is first-party by default (a `globalDir` is present); pass `globalDir: null` to build a
+  context is native by default (a `globalDir` is present); pass `globalDir: null` to build a
   project-installed package's context, which has none. The
   key is **`packageSlug`**. A `slug` key is silently ignored and you get `'test-package'`.
 - `createMockToolCallContext(...)` / `createDeniedToolCallContext(...)` take a **shaped override
@@ -293,7 +293,7 @@ you publish.
 
 ## 10. Ship it
 
-**(a) Installed node package — first-party, in-process.** Build so the compiled output exists (or
+**(a) Installed node package — native, in-process.** Build so the compiled output exists (or
 leave a directory to the image build, which builds it), then have an admin register it as a
 dependency of the host — register, rebuild the image (`neuralis rebuild` installs it), verify.
 That sequence is the **deploying admin's terminal work, not yours**; registering a directory or a
@@ -306,7 +306,7 @@ and never joins the in-process class. (Where the operator has the `neuralweb` CL
 `neuralweb install <identity> --channel builtin` prints these commands with a trust notice
 and never executes anything.) **Registering the dependency IS the trust act**: every dependency
 whose own `package.json` carries a `neuralis` block is discovered at boot and loaded in-process
-with host-assigned first-party trust — the same trust as the platform's own packages. Do it only
+with host-assigned native trust — the same trust as the platform's own packages. Do it only
 for packages the deploying admin has vetted, exactly as any npm dependency. A dependency with no
 `neuralis` block is skipped silently and never exists.
 
@@ -319,7 +319,7 @@ plus an undeclared runtime type is the `untrusted-node` partial from §2.
 open when the other two are closed to you. It carries the five markdown categories and nothing else.
 
 **What discovery recognises.** No marker file, no manifest and no dot-directory is required — the
-folder layout alone decides. The platform records *why* it grouped a package, and `verify-loaded.sh`
+folder layout alone decides. The platform records *why* it grouped a package, and `verify-loaded.mjs`
 prints that `reason` back to you:
 
 | `reason` | What made it a package |
@@ -337,10 +337,10 @@ nothing.
 
 **Where to write it.** A source slug *is* a URI scheme, so the address is `<slug>://<path>`. To learn
 which slugs exist, read the `sources` list already in your `<runtime_stack>` block — one row per
-source, carrying the URI root, the connector, the container path and **your own** resolved
+source, carrying the URI root, the connector, the local path and **your own** resolved
 `policy=read/write/exec`. That block is the only place those coordinates appear. `fs_list` with no
 `uri` also prints a registry line per root, but it carries counts and sync status only — no
-connector, no container path, no policy — so it answers "is this indexed", never "may I write here,
+connector, no local path, no policy — so it answers "is this indexed", never "may I write here,
 and where does that land on disk". Every project seeds a writable `data://`.
 
 Worked example — a one-skill package needing no other file:
@@ -354,7 +354,7 @@ data://acme-pack/skills/release-notes/SKILL.md   → root data://acme-pack   (ca
 lands as a *pending change*, and a pending file's frontmatter is never captured: at best the skill
 reaches the model under its directory name with no description line — the description being its
 entire discovery surface — and under the tool's default category it is not indexed as a contribution
-at all. Writing the file into the source's container path (the `container=` value on that source's
+at all. Writing the file into the source's local path (the `container=` value on that source's
 `<runtime_stack>` row) has neither problem.
 
 **Then get it indexed.** Discovery reads the sync index, never the live tree: unsynced means
@@ -377,7 +377,7 @@ invisible, with **no error anywhere** — indistinguishable from correctly hidde
   Until then the files are on disk but the package will not appear."*
 
 **Then prove it with the script** — it is the authoritative check:
-`bash ${SKILL_DIR}/scripts/verify-loaded.sh 'data://acme-pack?project=<p>&scope=project'`. It reads the overview surface,
+`node "${SKILL_DIR}/scripts/verify-loaded.mjs" 'data://acme-pack?project=<p>&scope=project'`. It reads the overview surface,
 which lists every discovered source package and reports each category as `N (M active)`. Once the
 sync has landed the package shows on the next stream — discovery is resolved fresh each time.
 

package/skills/create-package/references/tools-and-schemas.md

@@ -26,7 +26,7 @@ So a `catalog_manage` with `action: ["list","update","delete"]` has one posture
 
 One `.json` per tool in the package-root `tools/` folder. **The tool name is the filename minus `.json`** — there is no `name` field (MCP-first), so renaming the file renames the tool and silently breaks every skill or prompt that named the old one. House style `<family>_<action>` in snake_case, not enforced. The file **is** the input schema: everything except `x-neuralis` is taken verbatim as `inputSchema`.
 
-**That name is GLOBAL to the deployment, and there is no per-package prefix.** If another installed package already declares it, exactly one entry owns it — the first-party one, otherwise the lexically-smaller `packageId` — and yours is **shadowed**: still loaded, its other tools untouched, but that name answers from the owner unless the owner is unavailable to the caller or an agent picks your package in Tool Access. Nothing is renamed for you. Pick a name nobody else will pick; `manifest-and-discovery.md` § *A tool name is global* has the rule and where the diagnostic shows up.
+**That name is GLOBAL to the deployment, and there is no per-package prefix.** If another installed package already declares it, exactly one entry owns it — the native one, otherwise the lexically-smaller `packageId` — and yours is **shadowed**: still loaded, its other tools untouched, but that name answers from the owner unless the owner is unavailable to the caller or an agent picks your package in Tool Access. Nothing is renamed for you. Pick a name nobody else will pick; `manifest-and-discovery.md` § *A tool name is global* has the rule and where the diagnostic shows up.
 
 ```json
 {
@@ -87,7 +87,7 @@ The load check accepts the bare-`http` form with or without the trailing `#`, an
 
 ### Session identity is never a tool input
 
-Seventeen names are banned as **root-level** properties: `userId`, `projectId`, `agentId`, `conversationId`, `requestId`, `toolUseId`, `delegateRunId`, `delegateMode`, `role`, `priority`, `grantedFeatures`, `spendLimits`, `llmRateLimitRpm`, `agentAccess`, `agentOwnership`, `session`, and the retired `dailyLimits`. Declaring one fails the load with `inputSchema.properties.userId is reserved session context and must not be tool input`. The fix is not to rename it — read `session.userId` in the handler. Identity always comes from the verified session, never from what the model typed.
+Nineteen names are banned as **root-level** properties: `userId`, `projectId`, `agentId`, `conversationId`, `requestId`, `toolUseId`, `delegateRunId`, `delegateMode`, `role`, `priority`, `rolePriorities`, `grantedFeatures`, `spendLimits`, `llmRateLimitRpm`, `agentAccess`, `agentOwnership`, `displayName`, `session`, and the retired `dailyLimits`. Declaring one fails the load with `inputSchema.properties.userId is reserved session context and must not be tool input`. The fix is not to rename it — read `session.userId` in the handler. Identity always comes from the verified session, never from what the model typed.
 
 The ban is **root-only by design**: `todos[].priority`, `members[].userId`, a message `role` are legitimate nested domain fields and none of them error. Only the top-level arguments object could be mistaken for caller identity.
 
@@ -217,7 +217,7 @@ For a sandboxed (WASM) package you write no dispatch switch — the build import
 
 **Presentation.** `ui.presentation` is `inline | card | explored`. Card type resolves first-match-wins: an MCP-app marker on the result, then `ui.cardType`, then `operation`, then `structuredContent.kind`/`.type` (the literal `tool.output` ignored), then the tool name, else `default`. **`ui.cardType` must match a declared card surface's `type`** — see `references/surfaces-and-design.md`.
 
-**Settled-header convention.** The chat card header draws ONE status icon, and its accessible name (`title` + `aria-label`) is the status word; there is no visible status pill. The settled status derives from `structuredContent`: `ok: true` (or a string `status` of `success`/`completed`/`pending_review`) → the green check; `ok: false` → the red X; any other string `status` becomes the icon's name, and its TONE is derived from the word by substring — a word containing `error` or `fail` draws the red X, `partial` the amber triangle, and a word containing `pending` draws the IN-FLIGHT SPINNER. Declaring `ok` on success payloads is the first-party convention. A completed tool with NO marker at all still settles (the platform floors runtime-`completed` to committed — a foreign tool cannot be forced into the convention), but two sharp edges: never reuse `status` for a domain value (an HTTP status number belongs under `httpStatus`), and never emit a settled status word containing `pending` — `pending_review` is the one floored carve-out. A card that claims to be running forever is a lie the user cannot dismiss, and the platform cannot tell it apart from a call that really is still open. The platform's own status spinner no longer splits the timeline into compositor layers, but anything YOUR card body animates still can — the prohibition, and the primitives that replace an `animate-*` utility, are in `references/surfaces-and-design.md` §Design floor.
+**Settled-header convention.** The chat card header draws ONE status icon, and its accessible name (`title` + `aria-label`) is the status word; there is no visible status pill. The settled status derives from `structuredContent`: `ok: true` (or a string `status` of `success`/`completed`/`pending_review`) → the green check; `ok: false` → the red X; any other string `status` becomes the icon's name, and its TONE is derived from the word by substring — a word containing `error` or `fail` draws the red X, `partial` the amber triangle, and a word containing `pending` draws the IN-FLIGHT SPINNER. Declaring `ok` on success payloads is the native convention. A completed tool with NO marker at all still settles (the platform floors runtime-`completed` to committed — a foreign tool cannot be forced into the convention), but two sharp edges: never reuse `status` for a domain value (an HTTP status number belongs under `httpStatus`), and never emit a settled status word containing `pending` — `pending_review` is the one floored carve-out. A card that claims to be running forever is a lie the user cannot dismiss, and the platform cannot tell it apart from a call that really is still open. The platform's own status spinner no longer splits the timeline into compositor layers, but anything YOUR card body animates still can — the prohibition, and the primitives that replace an `animate-*` utility, are in `references/surfaces-and-design.md` §Design floor.
 
 An unmatched `cardType` is not an error and not a blank: the result falls back to the **generic default card**, which is often deliberate (a host/builtin card type, a tool that only needs the standard rendering). The pre-flight warns rather than rejects for exactly that reason — but if you meant to ship your own card, that warning is the whole signal you will get.
 
@@ -241,9 +241,9 @@ An unmatched `cardType` is not an error and not a blank: the result falls back t
 | `Tool rate limit exceeded` | trust-tier rate limit — untrusted 10/min, trusted 100/min |
 | the handler got a number where you expected a rejected string | the dispatch validator coerces types; `"50"` becomes `50`. Guard on semantics, not on "it was validated" |
 | tools catalogued but every call policy-denied | an untrusted package with no explicit tool allowlist gets an **empty** one until an admin elevates it |
-| package `partial`, reason `untrusted-node` | a non-first-party package declaring the in-process runtime. Declare the sandboxed or MCP runtime instead |
+| package `partial`, reason `untrusted-node` | a non-native package declaring the in-process runtime. Declare the sandboxed or MCP runtime instead |
 
-Untrusted tools are rate-limited an order of magnitude harder and time out sooner than first-party ones; the full trust-ceiling table is in `references/runtime-and-build.md`.
+Untrusted tools are rate-limited an order of magnitude harder and time out sooner than native ones; the full trust-ceiling table is in `references/runtime-and-build.md`.
 
 ---