@neuralis/brain-core 0.3.1 → 0.4.0

package/skills/create-package/references/runtime-and-build.md

@@ -59,16 +59,16 @@ export function api(state: NotesState) {
 
 - **The lifecycle FILE is optional; `init` inside it is not.** A package with no routes and no tool handlers (markdown, schemas, connectors) ships no `src/lifecycle.ts` at all. A lifecycle module without `init` is discarded with a warning and `start`/`drain`/`stop`/`api`/`onBootstrapComplete`/`provisionProject`/`deprovisionProject`/`onPrincipalRevoked`/`onCredentialChanged`/`health` are never wired.
 - **`init` returning nothing** leaves the dispatch state `undefined` — symptom: every request returns 503 `Package not initialized — lifecycle failed to load`, though the route files loaded and nothing logged an error.
-- **Peer lookups belong in `onBootstrapComplete(state, ctx)`** — it fires once after every package's `init` and `start` have resolved. Elsewhere load order is not guaranteed: `getPackageApi()` returns `undefined` intermittently, fine on one boot, silently degraded on the next. From a non-first-party package `undefined` may also be a trust **denial** (audited `denied:untrusted` / `denied:trust-mismatch`), not a missing package.
+- **Peer lookups belong in `onBootstrapComplete(state, ctx)`** — it fires once after every package's `init` and `start` have resolved. Elsewhere load order is not guaranteed: `getPackageApi()` returns `undefined` intermittently, fine on one boot, silently degraded on the next. From a non-native package `undefined` may also be a trust **denial** (audited `denied:untrusted` / `denied:trust-mismatch`), not a missing package.
 - **`onPrincipalRevoked(state, event)` closes; it never decides.** The host calls it when a user is disabled, deleted or has their sessions reset (no `event.projectId`), or loses one project (`membership_removed` / `project_archived`, with `projectId`). Stop what you hold open for `event.userId` — sockets, running jobs, pollers — through your existing stop, and return promptly: the call is bounded by a timeout, and the user is already refused everywhere else, so never re-check access here. Only a host-installed package's lifecycle runs at all; a `_packages/` drop never receives it.
 
-**`init` receives** `selfId`, `selfTrust`, `data { dataDir, globalDir?, fileStore<T>, jsonlAppender<T>, dataPath, logger }`, `host { id }`, `packages { isLoaded, getPackageApi<T> }`, `credentials?`, `sessions? { createProjectFactory }`, `config { get }`, lazy `platform` facts, first-party `hostPorts`, `logger`. Platform facts throw before publication and are read where used; bootstrap completion receives the same `platform`, rather than copied aggregates. `dataDir` is **per project**: `<projectsRoot>/<projectId>/data/<zone>/`, mode `0700`, with `logs/`. First-party packages (host-installed, `@neuralis/*` and the deploy's own deps) additionally receive `data.globalDir` — a project-independent platform home under the app zone, where their process-global state and their `logs/` live; a project-installed package like yours has NO `globalDir` (its state is project data by nature), and `ctx.data.globalDir` is `undefined` for it.
+**`init` receives** `selfId`, `selfTrust`, `data { dataDir, globalDir?, fileStore<T>, jsonlAppender<T>, dataPath, logger }`, `host { id }`, `packages { isLoaded, getPackageApi<T> }`, `credentials?`, `sessions? { createProjectFactory }`, `config { get }`, lazy `platform` facts, native `hostPorts`, `logger`. Platform facts throw before publication and are read where used; bootstrap completion receives the same `platform`, rather than copied aggregates. `dataDir` is **per project**: `<projectsRoot>/<projectId>/data/<zone>/`, mode `0700`, with `logs/`. Native packages (host-installed, `@neuralis/*` and the deploy's own deps) additionally receive `data.globalDir` — a project-independent platform home under the app zone, where their process-global state and their `logs/` live; a project-installed package like yours has NO `globalDir` (its state is project data by nature), and `ctx.data.globalDir` is `undefined` for it.
 
 **Write through `dataPath`, and hold ONE appender.** `jsonlAppender()` takes a RESOLVED path, not a string — `ctx.data.dataPath('events.jsonl')` produces one, and it refuses anything that would leave your own data dir (an absolute path, or a relative one that climbs out), so you cannot write into a sibling package's data by accident. The APPENDER creates any missing intermediate directories when it writes; `dataPath` itself only resolves, so if you hand its result to your own `fs` call the directories are yours to create. Keep ONE appender for the life of the package: its write ordering is per-instance, so a fresh one per call gives up the guarantee that entries written together stay together. (The WASM guest plane's `ctx.data.*` also takes paths relative to the package data dir, but REPORTS failure as `{ ok: false, error }` instead of throwing — its answers cross into guest memory and carry a fixed code, never a filesystem path. Do not merge the two contracts in your head.)
 
-**The logger is levellable and append-only.** `ctx.data.logger` is a `PackageLogger` already pointed at `<dataDir>/logs/` (for a first-party package: `<globalDir>/logs/`); it resolves its level at every CALL — your package's entry in the operator's `packageLogLevelOverrides` (keyed on the `pkg` field of your log lines: your zone path, `runtime/packages/<dir>` for a drop, the bare name for `@neuralis/*`) → the global `packageLogLevel` → `debug`. Both are platform keys; your manifest declares nothing for them. Never cache `logger.level` in a constructor: the level is live, so a captured value stays pinned after an administrator edit. Every line is appended (O(1)), so the file is OLDEST-first: read "the newest N" with `JsonlAppender.readNewest(path, n)` (`@neuralis/package-system/data`), which takes the tail and then the rotated `.1`, `.2` … generations — never the first lines.
+**The logger is levellable and append-only.** `ctx.data.logger` is a `PackageLogger` already pointed at `<dataDir>/logs/` (for a native package: `<globalDir>/logs/`); it resolves its level at every CALL — your package's entry in the operator's `packageLogLevelOverrides` (keyed on the `pkg` field of your log lines: your zone path, `runtime/packages/<dir>` for a drop, the bare name for `@neuralis/*`) → the global `packageLogLevel` → `debug`. Both are platform keys; your manifest declares nothing for them. Never cache `logger.level` in a constructor: the level is live, so a captured value stays pinned after an administrator edit. Every line is appended (O(1)), so the file is OLDEST-first: read "the newest N" with `JsonlAppender.readNewest(path, n)` (`@neuralis/package-system/data`), which takes the tail and then the rotated `.1`, `.2` … generations — never the first lines.
 
-`onCredentialChanged(state, event)` receives `{credentialId, scope, change}` after a write or delete; re-resolve a changed secret through `ctx.credentials`, never through the event. `drain(state)` finishes or checkpoints work before `stop`, and `health(state)` returns structured checks with closed status/reason values. Runtime fan-outs are bounded. A first-party package exposes its declared `provides` implementations on the state returned by standalone `init(ctx)`. The discovered adapter retains `state.services` as `PackageRuntimeApi.services`, separately from the public `api(state)`; the host resolves them by contract id.
+`onCredentialChanged(state, event)` receives `{credentialId, scope, change}` after a write or delete; re-resolve a changed secret through `ctx.credentials`, never through the event. `drain(state)` finishes or checkpoints work before `stop`, and `health(state)` returns structured checks with closed status/reason values. Runtime fan-outs are bounded. A native package exposes its declared `provides` implementations on the state returned by standalone `init(ctx)`. The discovered adapter retains `state.services` as `PackageRuntimeApi.services`, separately from the public `api(state)`; the host resolves them by contract id.
 
 Use those contracts instead of module globals — `createProjectFactory` for per-project services, `ctx.credentials.*` for secrets. Cross-package calls carry the caller (`getPackageApi<T>(id, { userId, projectId, callerId, callerTrust })`) and are trust-gated and audited. Never call another package over MCP.
 
@@ -101,7 +101,7 @@ export const POST: RouteHandler = async (req, state) => {
 
 **The feature gate runs before your handler**; never re-check the route's own `feature` inside it.
 
-> **A route with no `feature` is reachable by any authenticated project member.** It does not "require first-party trust". Symptom: no error anywhere — a viewer-role user or an agent's skill script successfully calls an endpoint you assumed was admin-only, and you find out in an audit, not in a test. Declare a `feature` on every route not deliberately open to all members.
+> **A route with no `feature` is reachable by any authenticated project member.** It does not "require native trust". Symptom: no error anywhere — a viewer-role user or an agent's skill script successfully calls an endpoint you assumed was admin-only, and you find out in an audit, not in a test. Declare a `feature` on every route not deliberately open to all members.
 
 **Identity.** `req.session` (`userId`, `projectId`, `agentId`, `role`, `grantedFeatures`, `priority`, `agentAccess`, `limits`) is the only identity — never re-state it in a body or query, never trust a caller-supplied `projectId`; best case the gateway rejects with 403 `project_mismatch`, worst case you built a confused deputy. `req.interactive` is a transport marker (browser session vs machine ticket), **never identity**, and is absent on sandboxed dispatch — read it as strict `=== true` or you hand sandboxed callers the privileged human branch.
 
@@ -115,17 +115,17 @@ Enforced automatically by the dispatchers; your package writes no code for it. L
 
 | | tool calls / min | route calls / min | tool timeout |
 |---|---|---|---|
-| first-party | unlimited | unlimited | none effectively enforced |
+| native | unlimited | unlimited | none effectively enforced |
 | trusted | 100 | 300 | 120 s |
 | untrusted | 10 | 30 | 30 s |
 
-Only the **trusted** tier's tool rate limit and timeout are administrator-tunable; the rest are hardcoded security floors. Exceeding a route limit returns **429**, and every non-first-party route access is audited. Trust is assigned by where the package came from — declaring `access.trust` yourself changes none of it.
+Only the **trusted** tier's tool rate limit and timeout are administrator-tunable; the rest are hardcoded security floors. Exceeding a route limit returns **429**, and every non-native route access is audited. Trust is assigned by where the package came from — declaring `access.trust` yourself changes none of it.
 
 ---
 
 ## 6. The sandbox — what a dropped package can do
 
-A `_packages/` drop runs in a WASM sandbox, untrusted by default; an administrator may elevate it to trusted.
+A `_packages/` drop runs in a WASM sandbox, untrusted by default; an administrator may elevate it to trusted (Admin → Packages, or `neuralis package trust <package> trusted`).
 
 **WASM here is the TOOL and ROUTE runtime — it never renders UI.** There is no WASM UI engine and none can be declared: the `wasm-ui` renderer was removed from the surface contract and a manifest still declaring it fails validation. A sandboxed WASM tool feeds a card exactly like any other tool — by returning `structuredContent` — and the UI itself ships as a self-contained `iframe` asset (`references/surfaces-and-design.md`).
 
@@ -162,14 +162,14 @@ failure (`cross_package_denied`, `route_not_bridgeable` for streaming/binary
 routes, `route_response_too_large`…); `ok: true` carries the route's own
 `status`/`body` — a 403 arrives there. `ctx.fs.read/list/search/write` are thin
 wrappers over brain-core's `read`/`list`/`search`/`write` routes
-(`drive.read`/`drive.search`/`drive.write` per op); `write` takes one VERB KEY
+(`files.read`/`files.search`/`files.write` per op); `write` takes one VERB KEY
 (`create`/`overwrite`/`edit`/`insert`/`lines`/`fields`/`move`/`copy`/`mkdir`/`revert`/`delete`). The route CATALOG —
 which routes exist and which feature each needs — lives on the per-package
 "API &amp; usage" docs pages:
-<https://docs.neuralisapp.com/agent-core/api-usage> ·
-<https://docs.neuralisapp.com/brain-core/api-usage> ·
-<https://docs.neuralisapp.com/admin/features-and-routes> ·
-<https://docs.neuralisapp.com/machine-core/api-usage> — mechanism:
+<https://docs.neuralisapp.com/agent-core/routes> ·
+<https://docs.neuralisapp.com/brain-core/routes> ·
+<https://docs.neuralisapp.com/admin/routes> ·
+<https://docs.neuralisapp.com/machine-core/routes> — mechanism:
 <https://docs.neuralisapp.com/package-system/routes>.
 
 `callRoute` denials return `{ ok: false, error: '…' }` rather than throwing — a
@@ -241,13 +241,13 @@ Only a package with `src/tools/*.ts`, `src/routes/*.ts` or `src/lifecycle.ts` ne
 
 **Fail-closed:** `src/routes/*` present with no valid `dist/routes.json` ⇒ the package wires **no** route at all and loads `partial` (`build-missing`), logging `declares route sources but has no valid dist/routes.json — failing closed`. Tools may still work, which makes it look like a routing bug. Rebuild.
 
-**Three triggers:** the **Build** button in the filesystem widget's Packages panel (build + reload + audit — the recommended path); **automatic on install** when `runtime.type` is `wasm` and source is present, where failure is **non-fatal** (the installer warns, the package installs `partial` — this is why "it installed fine but my tool 503s" happens); or the CLI **by absolute path**:
+**Three triggers:** **Build** in Admin → Packages or `neuralis package build <package>` (a package manager's action: build + reload + audit — the recommended path); **automatic on install** when `runtime.type` is `wasm` and source is present, where failure is **non-fatal** (the installer warns, the package installs `partial` — this is why "it installed fine but my tool 503s" happens); or the CLI **by absolute path**:
 
 ```bash
 node <install-root>/node_modules/.bin/neuralis-build <absolute package root>
 ```
 
-A first-party package's UI uses the same CLI in `ui` mode — `neuralis-build ui <absolute package root>` bundles the `app.module` entry to `dist/app/` and fails the build if React or another host-shared module would be bundled into it (`BUNDLED_SHARED_MODULE` — two Reacts break every hook), if it imports a module of another UI package that package's `app.module.provides` does not list (`UNDECLARED_SHARED_MODULE`), or if it reads React with no resolvable `react` (`NO_REACT`). Beside the bundle it writes `shared-imports.json` (host API version, React major, shared ids read); the host refuses a module whose record no longer matches it, so rebuild after every platform upgrade.
+A native package's UI uses the same CLI in `ui` mode — `neuralis-build ui <absolute package root>` bundles the `app.module` entry to `dist/app/` and fails the build if React or another host-shared module would be bundled into it (`BUNDLED_SHARED_MODULE` — two Reacts break every hook), if it imports a module of another UI package that package's `app.module.provides` does not list (`UNDECLARED_SHARED_MODULE`), or if it reads React with no resolvable `react` (`NO_REACT`). Beside the bundle it writes `shared-imports.json` (host API version, React major, shared ids read); the host refuses a module whose record no longer matches it, so rebuild after every platform upgrade.
 
 `npx neuralis-build` from a project data folder **does not work** — no module tree above it, so npx goes to the public registry and dies with `E404 'neuralis-build@*' is not in this registry`.
 
@@ -255,9 +255,9 @@ A first-party package's UI uses the same CLI in `ui` mode — `neuralis-build ui
 
 ---
 
-## 7b. Developing a first-party package from ITS OWN repository
+## 7b. Developing a native package from ITS OWN repository
 
-A column-(a) package does not have to live inside the platform's tree, and for a real first-party
+A column-(a) package does not have to live inside the platform's tree, and for a real native
 package it should not. The dependency line is the trust act, and a dependency can point at any
 directory on the deploying machine — so the package gets its own repository, its own git history and
 its own release cadence, and the deployment's image build installs it from that directory (or from a
@@ -311,7 +311,7 @@ report a suite as green in an environment you did not run it in.
 
 1. **git remote** — source backup and review. Changes nothing about the deployment.
 2. **dependency registration + image rebuild** — the operator's trust act, then the build that
-   installs it. THIS is what makes the package discovered and loaded in-process with first-party
+   installs it. THIS is what makes the package discovered and loaded in-process with native
    trust.
 3. **mount** — binds the directory over the installed copy for live editing (build in the folder,
    restart). Plumbing only; without (2) the package is still invisible.
@@ -346,7 +346,7 @@ every agent that can see it.
 | **503 `code-runtime-unavailable`** | the package loaded `partial`; read the reason |
 | `pkg add` or the image build refuses the package, or it is absent and Admin health lists it under `builtin-packages` | it failed the loader's admission check (named per file — a tool in `tools/` missing `x-neuralis.annotations.category` is the usual one: the schema validator alone passes it, the native-tool check does not), or it collides with another package over a service, an OAuth prefix or a config key; only that package is left out |
 
-Partial reasons: `build-missing` (no sandbox artifact — rebuild), `runtime-unavailable` (the code runtime crashed, or an MCP subprocess failed to spawn), `untrusted-node` (a non-first-party package declared or defaulted to the in-process `node` runtime), `untrusted-mcp` (a non-first-party package declared the `mcp` subprocess runtime — nothing was spawned). **Both trust reasons have the same fix: declare `wasm`, the only code runtime available below first-party.** A `partial` package still registers every declarative contribution, which is why it looks half-working rather than broken.
+Partial reasons: `build-missing` (no sandbox artifact — rebuild), `runtime-unavailable` (the code runtime crashed, or an MCP subprocess failed to spawn), `untrusted-node` (a non-native package declared or defaulted to the in-process `node` runtime), `untrusted-mcp` (a non-native package declared the `mcp` subprocess runtime — nothing was spawned). **Both trust reasons have the same fix: declare `wasm`, the only code runtime available below native.** A `partial` package still registers every declarative contribution, which is why it looks half-working rather than broken.
 
 ---
 

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.
@@ -260,7 +276,7 @@ requiredFeatures:
 
 What matters is that the key is top-level and its value parses to a **list**. Anything else is ignored. (The warning you get for a non-list says "expected a flow array" — read that as "expected a list"; the block form is equally valid.)
 
-> **The nested form silently produces no gate.** A `requires:` key with an indented `features: [...]` parses to nothing, emits **no warning**, and your skill is visible to everyone. A non-array value at least logs `requiredFeatures: frontmatter ignored — expected a flow array of feature ids`; the nested block leaves no trace. Treat it as a security defect in waiting and grep for it before you ship.
+> **The nested form silently produces no gate.** A `requires:` key with an indented `features: [...]` is read by nothing, emits **no warning**, and your skill is visible to everyone. A non-array value at least logs `requiredFeatures: frontmatter ignored — expected a flow array of feature ids`; the nested block leaves no trace. Treat it as a security defect in waiting and grep for it before you ship.
 
 **Hidden means absent.** A caller missing any listed feature does not see the file in the overview, the files catalog, the slash menu or the prompt — never a greyed-out row — and activating it returns the same generic `Skill not found` as a typo. That is deliberate non-inference: do not "improve" it into a forbidden error, and debug by inspecting the *caller's* granted features, not the skill. Naming a feature no package provides makes the file reachable only by wildcard (`*`) holders — owner-strength roles only. To reach the project `admin` tier as well, DECLARE the feature in `providesFeatures` and grant it in your own `requires.defaultRoleGrants.admin` (for a package installed AFTER project creation — not shipped with the platform — grants to admin-strength roles are never auto-applied: the feature surfaces in the role catalog and an owner grants it by hand): the seeded `admin` role carries no `'*'` wildcard, so an undeclared id never reaches it — a valid way to declare owner-only, but NOT a way to reach project admins.
 
@@ -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)