@neuralis/brain-core 0.2.0 → 0.3.0

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

@@ -15,7 +15,7 @@ Every surface lives in `package.json` under `neuralis.app.surfaces[]` — a unio
 | kind | required | useful optional |
 |---|---|---|
 | `widget` | `kind`, `id`, `type`, `title`, `component` | `icon`, `layout`, `chrome`, `open`, `defaultOpen`, `requires` |
-| `dock` | `kind`, `id`, `label`, `action` | `icon`, `position`, `section`, `dock`, `tooltip`, `color` |
+| `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`.
@@ -68,6 +68,8 @@ 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.
+
 ## Task: pick a renderer
 
 **Two renderers exist, and both render.** There is no third option and no placeholder tier: `inline-html` and `wasm-ui` were removed from the contract, and a manifest still declaring one is rejected outright — *renderer 'inline-html' was removed; ship the HTML asset and declare renderer 'iframe' with a relative url*. A leftover `fallback` key is inert and warned about. (WASM remains the **tool/route** sandbox runtime; there has never been a WASM UI engine, and one can no longer be declared.)
@@ -117,7 +119,7 @@ Five things to know before you use it:
 - **Budgets: 64 distinct paths and 8 MiB per SCOPE**, and the lane is `no-store`, so every render refetches the whole set. The preflight errors past both numbers and warns past 1 MiB — but it counts only your SURFACE tree, while the runtime budget also charges every `app/shared/` file your entry pulls in, so a shared-heavy bundle can pass authoring and still be refused at request time. The per-file 2 MiB cap applies in both modes.
 - **Still no remote origins.** The CSP names none, so a CDN script or a Google font is blocked before the request leaves. Ship the file.
 
-`app/shared/` is a declared **package-public** namespace: any visible surface of the package may read it, so nothing feature-private belongs there.
+`app/shared/` is a declared **package-public** namespace: any visible surface of the package may read it, and a declared dock picture is served from it, so nothing feature-private belongs there.
 
 ## The silent failures — symptom first
 
@@ -167,7 +169,7 @@ Asset serving is authenticated per request, scope-bound, traversal-safe, `Cache-
 
 *Symptom of omitting `color-scheme` or an explicit height:* the frame collapses to the HTML default 150px, and the browser paints an opaque **white** backdrop behind a cross-origin frame whose colour scheme differs from the dark workspace. Declare `color-scheme: dark light` at **every** nesting level — outer element and embedded document both.
 
-Host CSS custom properties (`--color-text`, `--w-bg-rgb`, `--icon-accent`, `--control-surface`, …) reach `direct`-rendered components only; there, never hardcode a hex — three themes ship — and `--w-bg-rgb` is comma-separated channels: `rgba(var(--w-bg-rgb), 0.55)`.
+Host CSS custom properties (`--color-text`, `--w-bg-rgb`, `--icon-accent`, `--control-surface`, …) reach `direct`-rendered components only; there, never hardcode a hex — four themes ship, independently selected for widgets, docks and background — and `--w-bg-rgb` is comma-separated channels: `rgba(var(--w-bg-rgb), 0.55)`. Every theme is dark polarity (white text), so design once for the dark design.
 
 ### Design floor
 
@@ -183,7 +185,7 @@ Host CSS custom properties (`--color-text`, `--w-bg-rgb`, `--icon-accent`, `--co
 
 `chrome.mode` is `toolbar` (default), `frameless` or `floating`. All three render the **same** host control strip, differing only in placement and visibility. `toolbar`/`floating` wrap content with padding and automatic scroll; **`frameless` clips content with no padding and no scrollbar** — the widget root owns its scroll and padding and must reserve roughly 4rem at the top right. *Symptom of ignoring it:* your top-right controls sit under the hover-revealed host strip and become unclickable, and content is cut off with no way to scroll. Iframe widgets usually want `frameless`.
 
-**The close (X) button minimises; it does not destroy.** The widget stays mounted off-screen and survives a refresh. *Symptom:* reopening shows it exactly as it was, "fresh start" initialisation never runs, and teardown in an unmount handler never fires. True destroy is the dock item's hover trash. **Exception for `renderer: "iframe"` widgets:** only the React subtree stays mounted — the frame itself is detached from the document while minimised (and on a stage-mode switch), so the browser discards its browsing context and the frame reloads from the same URL with everything inside it gone. *Symptom:* your in-frame bootstrap DOES re-run and any in-frame in-memory state is lost. Make an iframe widget's bootstrap re-runnable and persist state server-side or in the frame's own storage.
+**The close (X) button minimises; it does not destroy.** The widget stays mounted off-screen and survives a refresh. *Symptom:* reopening shows it exactly as it was, "fresh start" initialisation never runs, and teardown in an unmount handler never fires. True destroy is the dock item's clean (broom) control. **Exception for `renderer: "iframe"` widgets:** only the React subtree stays mounted — the frame itself is detached from the document while minimised (and on a stage-mode switch), so the browser discards its browsing context and the frame reloads from the same URL with everything inside it gone. *Symptom:* your in-frame bootstrap DOES re-run and any in-frame in-memory state is lost. Make an iframe widget's bootstrap re-runnable and persist state server-side or in the frame's own storage.
 
 Transparency resolves per-instance override → manifest `chrome.transparent` → the user's Layout default → opaque; the cycle control is hidden when `chrome.userTransparency: false` or the package is untrusted. **The level is a user setting your surface cannot read, and it changes the panel's CSS containment**: the panel emits a `backdrop-filter` at `dim` and `opaque` (not at `transparent`), so at those two levels it is a containing block for `position: fixed` descendants. Design so the level never matters — portal every `fixed` overlay to `document.body` (see the Design floor above). The panel's stacking context does not vary: it is isolated at every level.
 
@@ -274,7 +276,7 @@ registerCardComponent('thing.result', ThingCard, {
 
 `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`.
 
-The component receives exactly `{ agentId, widgetId, state }`; everything else comes from the workspace host port captured at install time — project/user ids, agents, `openWidget`, `updateWidgetState`, `getGrantedFeatures`, `useVisibleSkills`, and `subscribeRealtime({ channel, projectId, agentId?, onEvent })` over `runtime | presence | workflow | filesystem | conversation | project` (plus the optional `isRealtimeConnected()` for that connection's current state — treat its absence as "may be disconnected"). If your package keeps its own client store keyed on the active project/agent, subscribe to the optional `onClientStateReset(handler)` at install time: the dock's clean (broom) control fires it at widget level (with the widget `type` — reset only on YOUR type), agent level and project level, and your handler drops that scope's client state (persisted tabs included) without calling the host back or touching the server. A host without the method never resets you; assume nothing. HTTP goes through the generic package API client, which injects the project and agent headers.
+The component receives exactly `{ agentId, widgetId, state }` — `agentId` is the window's BOUND agent (fixed for that window, never the workspace's active one) and `widgetId` names the window; everything else comes from the workspace host port captured at install time — project/user ids, agents, `openWidget`, `updateWidgetState`, `getGrantedFeatures`, `useVisibleSkills`, and `subscribeRealtime({ channel, projectId, agentId?, onEvent })` over `runtime | presence | workflow | filesystem | conversation | project` (plus the optional `isRealtimeConnected()` for that connection's current state — treat its absence as "may be disconnected"). A widget can be open in SEVERAL windows (unless its manifest sets `open.singleton: true`): keep one client store PER WINDOW, keyed on `widgetId` and the bound `agentId`, never one global store read through the active agent — two windows must never share a selection, a draft or a late response. `openWidget({ agentId, type, title, target? })` picks the window: absent or `'default'` is the most recently focused window of that type bound to that agent (opened only when none exists), `'new'` always opens another (a singleton answers as `'default'`), and `{ instanceId }` is exactly that window. Subscribe to the optional `onClientStateReset(handler)` at install time: the dock's clean (broom) control fires it at four levels — `instance` (clean ONE window, `instanceId`; the window stays open), `widget` (that window is closed; reset only on YOUR `widgetType`), `agent` and `project` — and your handler drops that scope's client state (persisted tabs included) without calling the host back or touching the server. A host without the method never resets you; assume nothing. HTTP goes through the generic package API client, which injects the project and agent headers — build it from the window's bound agent.
 
 ### Offer the skill next to the button that does the same thing
 

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

@@ -77,16 +77,14 @@ grouping reason and the per-category file counts in place of a status.
 Where to read it without server-log access:
 
 ```bash
-curl -sS -w '\nHTTP %{http_code}\n' \
-  -H "Authorization: Bearer ${NEURALIS_SESSION_TOKEN}" \
-  "${NEURALIS_API}/api/packages/@neuralis/agent-core/packages/diagnostics"
+neuralis request GET @neuralis/agent-core/packages/diagnostics
 ```
 
-Both variables are already in a skill's environment. There is **no project header**: the catch-all
-derives the project from the verified ticket, and a project id you supply that disagrees with the
-ticket's is refused outright. Without that bearer (or a browser cookie session) the call is a flat
-`401` before anything else is read — caller-supplied identity is not an auth mechanism anywhere on
-this platform.
+Inside a skill's shell it authenticates with the session ticket already in the environment.
+There is **no project header**: the catch-all derives the project from the verified ticket, and a
+project id you supply that disagrees with the ticket's is refused outright. Without that ticket (or
+a `neuralis login` grant, or a browser cookie session) the call is a flat `401` before anything else
+is read — caller-supplied identity is not an auth mechanism anywhere on this platform.
 
 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
@@ -364,19 +362,14 @@ invisible, with **no error anywhere** — indistinguishable from correctly hidde
 
 - `data://` and `packages://` ship with `trigger: "auto"`, so a disk-level write is picked up by the
   file watcher after roughly a two-second debounce. **Nothing to call.**
-- On any other source, or one set to `manual`: **no tool syncs.** Call the route from the same shell —
-  both variables are already in a skill's environment:
+- On any other source, or one set to `manual`: **no tool syncs.** Call the route from the same shell:
 
   ```bash
-  curl --fail-with-body -sS -X POST \
-    -H "Authorization: Bearer ${NEURALIS_SESSION_TOKEN}" \
-    -H "Content-Type: application/json" \
-    -d '{"source":"data"}' \
-    "${NEURALIS_API}/api/packages/@neuralis/brain-core/sources/sync"
+  neuralis request POST @neuralis/brain-core/sources/sync -f source=data
   ```
 
   It answers `202` with a job snapshot; the run is asynchronous, so poll
-  `GET …/sources/sync-status?source=data`.
+  `neuralis request GET @neuralis/brain-core/sources/sync-status -f source=data`.
 - **Without `drive.sync` that call returns `403 {"error":"Sync requires drive.sync."}`.** Do not retry
   it and do not route around it — say which thing is off, in these words: *"I wrote the package files
   to `<uri>`. Indexing them needs a sync, which requires the `drive.sync` feature my role does not

package/skills/create-package/scripts/check-package.sh

@@ -568,10 +568,56 @@ if (man) {
   for (const [f, t] of toolCardTypes) {
     if (!byType.has(t)) warn(f, `x-neuralis.ui.cardType "${t}" matches no card surface declared here — the result falls back to the generic default card. Deliberate when the type is a host/builtin card; otherwise add {"kind":"card","id":"…","type":"${t}"}`);
   }
+  const imageDocks = docks.filter((d) => d.image !== undefined);
   if (hasShared) {
     warn(`${SHARED_DIR}/`, anyBundle
       ? `declared package-public: any visible surface of this package may read it, so no feature-private asset belongs there. It IS served — a bundle surface reaches it as '../shared/…' relative to the entry's own directory, so mind the depth (an entry at 'sub/index.html' needs '../../shared/…')`
-      : `declared package-public: any visible surface of this package may read it, so no feature-private asset belongs there. No surface here declares "assetMode":"bundle", so nothing serves it — a self-contained entry requests it with no session cookie. Declare bundle mode on the surface that needs it, or inline the asset`);
+      : `declared package-public: any visible surface of this package may read it, so no feature-private asset belongs there. No surface here declares "assetMode":"bundle", so ${imageDocks.length ? 'only the declared dock picture(s) are served from it' : 'nothing serves it'} — a self-contained entry requests it with no session cookie. Declare bundle mode on the surface that needs it, or inline the asset`);
+  }
+
+  // dock pictures — an optional raster `image` on a dock entry. The PATH rule is
+  // the platform's own (`resolveDockImagePath`), the BYTE rule its own raster
+  // sniff and 256 KiB floor (`@neuralis/package-system/web-common`); where those
+  // do not resolve from here, the check is SKIPPED and says so.
+  if (imageDocks.length) {
+    let kernel = null, raster = null;
+    for (const from of [ROOT, process.cwd(), SCRIPT_DIR]) {
+      try {
+        kernel = require(require.resolve('@neuralis/package-system', { paths: [from] }));
+        raster = require(require.resolve('@neuralis/package-system/web-common', { paths: [from] }));
+        break;
+      } catch { kernel = null; raster = null; }
+    }
+    if (!kernel || typeof kernel.resolveDockImagePath !== 'function' || !raster || typeof raster.sniffRasterImage !== 'function') {
+      F.push({ lvl: 'SKIP', f: MF, m: `${imageDocks.length} dock image(s) NOT checked — @neuralis/package-system does not resolve from here; run the check where the platform is installed` });
+    } else {
+      let sharedReal = null;
+      try { sharedReal = fs.realpathSync(at('app', 'shared')); } catch { /* no app/shared */ }
+      for (const d of imageDocks) {
+        const L = `dock "${d.id || '(no id)'}" image`;
+        const resolved = typeof d.image === 'string' ? kernel.resolveDockImagePath(d.image) : { ok: false, error: 'not a string' };
+        if (!resolved.ok) {
+          err(MF, `${L} is not a valid picture path (${resolved.error}) — declare a relative path under '${SHARED_DIR}/' naming a .png, .jpg, .jpeg or .webp file (letters, digits, '.', '_', '-' per segment). The package does NOT load with this value`);
+          continue;
+        }
+        let real = null;
+        try { real = fs.realpathSync(at(...resolved.path.split('/'))); } catch { /* missing */ }
+        if (!real) { err(resolved.path, `${L} is declared but not on disk — the dock shows only its glyph`); continue; }
+        if (!sharedReal || !real.startsWith(sharedReal + path.sep)) {
+          err(resolved.path, `${L} resolves outside '${SHARED_DIR}/' through a link — the platform refuses to serve it`);
+          continue;
+        }
+        const st = fs.statSync(real);
+        if (!st.isFile()) { err(resolved.path, `${L} is not a regular file`); continue; }
+        if (st.size > raster.APPEARANCE_IMAGE_MAX_BYTES) {
+          err(resolved.path, `${L} is ${st.size} bytes; a package picture is served only up to ${raster.APPEARANCE_IMAGE_MAX_BYTES} bytes (256 KiB) — downscale it, a dock tile is a few dozen pixels`);
+          continue;
+        }
+        if (!raster.sniffRasterImage(new Uint8Array(fs.readFileSync(real)))) {
+          err(resolved.path, `${L} is not a PNG, JPEG or WebP picture by its BYTES — the platform sniffs the content, never the extension, and serves nothing else (an SVG or a renamed document is refused)`);
+        }
+      }
+    }
   }
 
   // icons — a name outside the platform icon library renders the fallback

package/skills/create-package/scripts/verify-loaded.sh

@@ -9,8 +9,9 @@
 # only what the platform said.
 #
 # WHAT IT CHECKS
-#   Reads the agent-core package diagnostics and overview surfaces as YOU, with
-#   the session ticket already in the script environment, and reports one of:
+#   Reads the agent-core package diagnostics and overview surfaces as YOU through
+#   `neuralis request` (the session ticket inside an activated skill, your
+#   `neuralis login` on your own machine), and reports one of:
 #     loaded   — registered and operational
 #     partial  — declarative contributions registered, no code runtime; prints
 #                the reason (build-missing | runtime-unavailable |
@@ -52,7 +53,7 @@
 #         1 = partial (reason printed)
 #         2 = absent — not listed for this caller
 #         3 = error / missing (recorded message printed)
-#         4 = could not reach the diagnostics surface (no session ticket, no
+#         4 = could not reach the diagnostics surface (no `neuralis` CLI or login, no
 #             network, HTTP failure, or the caller lacks the `core.observe`
 #             feature). NOTHING is claimed about the package in this state.
 #
@@ -127,8 +128,8 @@ if [ -z "$PKG_ID" ]; then
   echo "usage: bash verify-loaded.sh <package-id> [--raw]" >&2
   exit 4
 fi
-if ! command -v curl >/dev/null 2>&1; then
-  echo "ERROR  curl not found on PATH" >&2
+if ! command -v neuralis >/dev/null 2>&1; then
+  echo "ERROR  neuralis (the CLI) not found on PATH" >&2
   manual_fallback
   exit 4
 fi
@@ -137,30 +138,20 @@ if ! command -v node >/dev/null 2>&1; then
   manual_fallback
   exit 4
 fi
-if [ -z "${NEURALIS_API:-}" ]; then
-  echo "ERROR  NEURALIS_API is not set — activate this skill first (execute action=\"skill\"); the API base and the session ticket are injected at activation" >&2
-  manual_fallback
-  exit 4
-fi
-if [ -z "${NEURALIS_SESSION_TOKEN:-}" ]; then
-  echo "ERROR  NEURALIS_SESSION_TOKEN is not set — activate this skill first; every internal call authenticates with the per-stream session ticket" >&2
-  manual_fallback
-  exit 4
-fi
-
-API_BASE="${NEURALIS_API%/}"
-BASE_ROUTE="${API_BASE}/api/packages/@neuralis/agent-core/packages"
+BASE_ROUTE="@neuralis/agent-core/packages"
 
 WORK="$(mktemp -d)"
 trap 'rm -rf "$WORK"' EXIT
 
-fetch() { # fetch <url> <outfile> -> echoes the HTTP status ("000" = no response)
-  local code
-  code="$(curl -sS -o "$2" -w '%{http_code}' \
-    -H "Authorization: Bearer ${NEURALIS_SESSION_TOKEN}" \
-    -H "X-Neuralis-Skill: create-package" \
-    "$1" 2>"$WORK/curl.err")" || true
-  [ -n "$code" ] || code="000"
+# `neuralis request` prints a 2xx body on stdout (exit 0); a non-2xx body goes to
+# stderr with an `HTTP <code>` line (exit 1). No such line = no answer
+# at all (no CLI login, no network) — "000". Its error text stays in request.err.
+fetch() { # fetch <route> <outfile> -> echoes the HTTP status ("000" = no response)
+  local rc=0 code
+  neuralis request GET "$1" >"$2" 2>"$WORK/request.err" || rc=$?
+  if [ "$rc" -eq 0 ]; then echo 200; return; fi
+  code="$(sed -n '/^HTTP [0-9][0-9][0-9]$/{s/^HTTP //p;q;}' "$WORK/request.err")"
+  if [ -n "$code" ]; then awk '!d && /^HTTP [0-9][0-9][0-9]$/ {d=1; next} {print}' "$WORK/request.err" > "$2"; else code="000"; fi
   echo "$code"
 }
 
@@ -174,7 +165,7 @@ if [ "$DIAG_CODE" = "403" ]; then
 fi
 if [ "$DIAG_CODE" != "200" ]; then
   echo "ERROR  GET ${BASE_ROUTE}/diagnostics returned HTTP ${DIAG_CODE}" >&2
-  [ -s "$WORK/curl.err" ] && sed 's/^/       /' "$WORK/curl.err" >&2
+  [ -s "$WORK/request.err" ] && sed 's/^/       /' "$WORK/request.err" >&2
   [ -s "$WORK/diag.json" ] && head -c 600 "$WORK/diag.json" >&2 && echo >&2
   manual_fallback
   exit 4
@@ -322,7 +313,7 @@ const counts = () => {
     process.stdout.write('        drop — and into NO tenant at all when the package is neither\n');
     process.stdout.write('        first-party nor owned by a resolvable project, which is silent\n');
     process.stdout.write('        apart from one server log line. Prove the instance exists with\n');
-    process.stdout.write('        GET <api>/api/packages/@neuralis/agent-core/connectors; that list is\n');
+    process.stdout.write('        neuralis request GET @neuralis/agent-core/connectors; that list is\n');
     process.stdout.write('        the platform lane plus your own project, and nothing else.\n');
   }
   if (overEntry.enabled === false) {

package/skills/git/SKILL.md

@@ -14,28 +14,32 @@ panel drives**, so an agent gets exactly the rights a human member has: gated by
 before every destructive op** and **credential-safe remotes** (the push/pull token is
 resolved server-side and never touches the agent shell).
 
-Call them with the one generic helper — `bash ${SKILL_DIR}/scripts/git.sh <GET|POST> <route> …`
-— which authenticates with the per-stream session ticket (`NEURALIS_API` +
-`NEURALIS_SESSION_TOKEN`, both injected at activation). This is *not* about committing to
-the Neuralis repo itself — it is about an agent operating git on a user's source.
+Call them with `neuralis request <GET|POST> @neuralis/brain-core/git/<route> …` — inside an
+activated skill it authenticates with the per-stream session ticket, on your own machine with
+`neuralis login`; never with a git credential (fetch/pull/push resolve the remote token
+server-side). The method is part of every call line: `commit` and `branch` READ on GET and
+WRITE on POST. This is *not* about committing to the Neuralis repo itself — it is about an
+agent operating git on a user's source.
 
 ## Three ways to reach git — pick the plane
 
 | Plane | Use it for | How | Guarantees |
 |---|---|---|---|
-| **A. Governed routes** (prefer for local ops + your own remote) | Review, stage, commit, branch/checkout, and fetch/pull/push on a git-backed source in the workspace | `bash ${SKILL_DIR}/scripts/git.sh …` (this skill) | uri-policy gated; auto-snapshot on destructive ops; remote token resolved server-side, never in the shell |
+| **A. Governed routes** (prefer for local ops + your own remote) | Review, stage, commit, branch/checkout, and fetch/pull/push on a git-backed source in the workspace | `neuralis request <GET|POST> @neuralis/brain-core/git/<route>` (this skill) | uri-policy gated; auto-snapshot on destructive ops; remote token resolved server-side, never in the shell |
 | **B. External GitHub MCP** | Collaboration on the hosting platform — pull requests, issues, reviews, releases | the connected GitHub MCP server's tools (if the user connected one) | authz delegated to the GitHub account + enterprise settings — Neuralis does not re-implement git ACLs |
 | **C. Raw git CLI** | Quick local inspection, or a user's own imported git skill | `execute action="shell"` running `git …` | uri-policy + Landlock sandboxed; secrets are stripped from the env, so it **cannot push**, and there is **no server snapshot**. It also resolves the repository by walking UP from `cwd`, so it is **repository-scoped, never source-scoped** — see the `repo` parameter note below |
 
 Default to **A** for governed local ops and for pushing/pulling your connected remote; **B**
 for platform collaboration; **C** for a fast read or when a user's own skill already drives git.
-Plane A is always "call the routes via `git.sh`" — the first-party `git` connector shown in the
+Plane A is always "call the routes with `neuralis request`" — the first-party `git` connector shown in the
 `<packages>` overview is metadata; there are no first-party git MCP *tools* to call.
 
 ## Routes covered
 
-Base path: `/api/packages/@neuralis/brain-core/git/<route>`. GET carries `source` (+ optional
-`repo`) as query params; POST carries them in the JSON body. `repo` is the optional in-source
+Path: `@neuralis/brain-core/git/<route>`. GET carries `source` (+ optional `repo`) as `-f`
+query fields; POST carries them in the JSON body (`--input -`), and every POST body must include
+`"source"` plus that route's own required fields (e.g. `paths[]` for `stage`, `message` for
+`commit`) — a source-less body is a `400`. `repo` is the optional in-source
 selector for a nested checkout when the source root is not itself the repo (omit for a
 single-repo source).
 
@@ -58,8 +62,10 @@ with nothing to report**. The same empty answer covers a
 source with no `.git` at all. (`commit`, `outgoing` and `show` are honest — they answer a typed
 `{"ok":false,"code":"unavailable"}` — and `diff` returns an empty diff string, except when it
 refuses a huge read with its own typed `{"ok":false,"code":"too_large"}`. Both of those typed
-refusals arrive on a **200**, so `git.sh` exits 0: a zero exit with `ok:false` is a soft answer,
-a non-zero exit is an HTTP refusal.)
+refusals arrive on a **200**, so `neuralis request` exits 0: a zero exit with `ok:false` is a
+soft answer, a non-zero exit is an HTTP refusal whose body and `HTTP <code>` are on stderr —
+EVERY refusal carries `error`; a write-op failure and the three remote 409s also carry
+`ok:false` and `code`; a 403 carries `code` (`feature_denied` / `uri_policy_denied`).)
 
 **So an empty read is never evidence of a clean tree.** Do not test it with `branch:null`: a real
 repository on a detached HEAD, or freshly initialised with no commit yet, reports exactly that.
@@ -112,7 +118,7 @@ Notes:
   `no_credential` / `no_https_remote` otherwise).
 - Destructive routes (`discard`, `branch` delete) snapshot server-side **before** mutating and
   return a typed `rescue` carrier. **Undo it through the governed `restore` route** — echo the
-  carrier straight back: `POST restore '{"source":"…","rescue":{"kind":"stash","ref":"<sha>"}}'`
+  carrier straight back: `POST restore` with `{"source":"…","rescue":{"kind":"stash","ref":"<sha>"}}`
   for discarded content, `{"kind":"branch","ref":"<anchor>","name":"<branch>"}` for a deleted
   branch. Same gate as any other write (`drive.write` + `write` on the root — no `exec`, no new
   capability), and the restore itself snapshots first. Do **not** reach for raw-shell
@@ -153,21 +159,13 @@ connect the remote in that card first.
   general "don't `reset --hard` / `--no-verify` / force-push unrequested" rule still applies to
   everything not named here.
 
-## Env vars
-
-- `NEURALIS_API` + `NEURALIS_SESSION_TOKEN` — injected at activation; every `git.sh` call reads them.
-- `git.sh` arguments: `<GET|POST> <route>` then, for **GET**, URL-encoded `key=value` pairs; for
-  **POST**, a single JSON body string. Every POST body must include `"source"` plus that route's
-  own required fields (e.g. `paths[]` for `stage`, `message` for `commit`) — a source-less body is
-  a `400`.
-
 ## Examples
 
 ```bash
 # Review: what changed, then the diff of one file, then recent history
-bash ${SKILL_DIR}/scripts/git.sh GET status source=my-repo
-bash ${SKILL_DIR}/scripts/git.sh GET diff   source=my-repo "path=src/app.ts"
-bash ${SKILL_DIR}/scripts/git.sh GET log    source=my-repo maxCount=10
+neuralis request GET @neuralis/brain-core/git/status -f source=my-repo
+neuralis request GET @neuralis/brain-core/git/diff   -f source=my-repo -f path=src/app.ts
+neuralis request GET @neuralis/brain-core/git/log    -f source=my-repo -f maxCount=10
 
 # NOT DISPOSABLE — every POST below writes to a REAL repository. These routes only
 # operate on an already-attached git-backed source, so there is no throwaway repo to
@@ -181,16 +179,16 @@ bash ${SKILL_DIR}/scripts/git.sh GET log    source=my-repo maxCount=10
 # authorship, and is unsafe once it has been pushed (the remote keeps the original
 # and the two histories diverge). Stage NAMED paths only — `paths:[…]` is what keeps
 # a stray secret from being swept in; there is no route that un-commits.
-bash ${SKILL_DIR}/scripts/git.sh POST stage  '{"source":"my-repo","paths":["src/app.ts","README.md"]}'
-bash ${SKILL_DIR}/scripts/git.sh POST commit '{"source":"my-repo","message":"Fix null guard in loader"}'
+neuralis request POST @neuralis/brain-core/git/stage  --input - <<<'{"source":"my-repo","paths":["src/app.ts","README.md"]}'
+neuralis request POST @neuralis/brain-core/git/commit --input - <<<'{"source":"my-repo","message":"Fix null guard in loader"}'
 
 # Create a branch, then switch to it.
 # checkout MOVES HEAD and swaps the working tree to that branch's content — the files
 # the user is looking at change under them. It is plain (never `-f`): if the switch
 # would overwrite uncommitted local changes, git refuses and you get a 409. Report
 # that refusal; there is no force option here and you must not build one in Plane C.
-bash ${SKILL_DIR}/scripts/git.sh POST branch   '{"source":"my-repo","action":"create","name":"fix/loader"}'
-bash ${SKILL_DIR}/scripts/git.sh POST checkout '{"source":"my-repo","ref":"fix/loader"}'
+neuralis request POST @neuralis/brain-core/git/branch   --input - <<<'{"source":"my-repo","action":"create","name":"fix/loader"}'
+neuralis request POST @neuralis/brain-core/git/checkout -f source=my-repo -f ref=fix/loader
 
 # Sync a connected remote (needs uri-policy exec + a connected remote).
 # pull REWRITES the working tree to the remote tip — fast-forward only, so it refuses
@@ -200,9 +198,9 @@ bash ${SKILL_DIR}/scripts/git.sh POST checkout '{"source":"my-repo","ref":"fix/l
 # OUTWARD-FACING: teammates, CI, and anything deploying from that branch see it the
 # moment it lands, and nothing in Neuralis can take it back. ASK THE USER FIRST, every
 # time — this is the one line here you never run on your own initiative.
-bash ${SKILL_DIR}/scripts/git.sh POST pull '{"source":"my-repo"}'
-bash ${SKILL_DIR}/scripts/git.sh POST push '{"source":"my-repo"}'
+neuralis request POST @neuralis/brain-core/git/pull -f source=my-repo
+neuralis request POST @neuralis/brain-core/git/push -f source=my-repo
 
 # Nested repo inside a multi-repo source: add the repo selector
-bash ${SKILL_DIR}/scripts/git.sh GET status source=mono repo=packages/api
+neuralis request GET @neuralis/brain-core/git/status -f source=mono -f repo=packages/api
 ```

package/skills/manage-files/SKILL.md

@@ -7,24 +7,25 @@ allowed-tools: execute
 
 # Files Management Skill
 
-Wraps `/api/packages/@neuralis/brain-core/{list,search,read,raw,write,upload,approve,pending}`
-behind one shell-callable bundle. The `fs_*` tools (`fs_read`, `fs_write`,
-etc.) remain the primary path for one-off file operations — this bundle is
-for *bulk*: iterating with a shell loop, posting a batch, or scripting an
-`upload + approve` sequence end-to-end.
+Covers `@neuralis/brain-core/{list,search,read,raw,write,upload,approve,pending}`.
+The `fs_*` tools (`fs_read`, `fs_write`, etc.) remain the primary path for one-off
+file operations — this skill is for *bulk*: iterating with a shell loop, posting a
+batch, or scripting an `upload + approve` sequence end-to-end. Call the routes with
+`neuralis request` (the session ticket inside an activated skill, `neuralis login`
+on your own machine); `write` and `upload` go through their scripts.
 
 ## Routes covered
 
-| Action | Method | Path | Script | Feature gate |
-|---|---|---|---|---|
-| List files / folders at a URI               | POST | `/list`     | `list.sh`    | `drive.read` |
-| Search vector index                         | POST | `/search`   | `search.sh`  | `drive.search` |
-| Read multiple files                         | POST | `/read`     | `read.sh`    | `drive.read` |
-| Raw (un-summarized) read                    | GET  | `/raw`      | `raw.sh`     | `drive.read` |
-| Write — every verb (create / overwrite / edit / insert / lines / fields / move / copy / mkdir / revert / delete) | POST | `/write` | `write.sh` | `drive.write` |
-| Upload a payload (multipart/form-data)      | POST | `/upload`   | `upload.sh`  | `drive.write` |
-| Approve a pending change                    | POST | `/approve`  | `approve.sh` | `drive.write` |
-| List pending changes (project-wide)         | GET  | `/pending`  | `pending.sh` | `drive.read` |
+| Action | Method | Path (`@neuralis/brain-core/…`) | Feature gate |
+|---|---|---|---|
+| List files / folders at a URI               | POST | `list`     | `drive.read` |
+| Search vector index                         | POST | `search`   | `drive.search` |
+| Read multiple files                         | POST | `read`     | `drive.read` |
+| Raw (un-summarized) read                    | GET  | `raw`      | `drive.read` |
+| Write — every verb (create / overwrite / edit / insert / lines / fields / move / copy / mkdir / revert / delete) | POST | `write` — `scripts/write.sh` | `drive.write` |
+| Upload a payload (multipart/form-data)      | POST | `upload` — `scripts/upload.sh` | `drive.write` |
+| Approve a pending change                    | POST | `approve`  | `drive.write` |
+| List pending changes (project-wide)         | GET  | `pending`  | `drive.read` |
 
 Per-route feature gates are enforced server-side by the RouteDispatcher against the
 caller's real `grantedFeatures`, independently of this skill's `requiredFeatures`
@@ -32,41 +33,45 @@ frontmatter — `/list`, `/read`, `/raw` and `GET /pending` need `drive.read`; `
 `drive.search`; `/write`, `/upload`, `/approve` and the mutating `/pending`
 verbs (`revert`, `discard`, `dismiss`, `discard-orphans`) need `drive.write`. A caller who holds
 `drive.write` (enough to see and activate this skill) but NOT `drive.search` gets a
-server-side **403** from `search.sh` even though the other scripts work.
+server-side **403** from `search` even though the other routes work.
 
-## Env vars
+## Bodies
 
-- All scripts read `NEURALIS_API` + `NEURALIS_SESSION_TOKEN` (both injected by the skill activation; the token is a per-stream session ticket).
-- `BODY_JSON` — the JSON request body for `list` / `search` / `read` / `write` / `approve`; on `pending.sh` it selects POST instead of GET. `create.sh`, `modify.sh`, `copy.sh` and `mkdir.sh` are kept only so an imported skill's existing path still writes; they exec `write.sh`, so they take the same verb-keyed body.
-- `/write` body = `{"agentId":"…","uri":"data://notes/plan.md","<verb>":…}` — the VERB is a KEY and its presence is the intent. Content verbs COMPOSE in one call, in a fixed order, as ONE write with ONE baseline: `create` (`{content, client_request_id?}` — never overwrites; a taken name lands BESIDE as `name-2.ext` and the response `uri` is where it went, so read it back), `overwrite` (`{content}` — refuses on a missing file and names `create`), `edit` (`[{old_string, new_string?, replace_all?, expected_replacements?}]`, applied in order, one failure discards all of them), `insert` (`{insert_text, insert_line?}` — inserts AFTER that line, `0` = start of file, omitted = append), `lines` (`{line_start, line_end, content}`), `fields` (`{category, status, pinned, tags{add,remove,set}, metadata}`). Structural verbs stand ALONE: `move`/`copy` (a destination uri or, for a file move, a bare new filename; `copy` may cross sources), `mkdir:true` (a real empty directory; not on `brain://`, where folders are implicit), `revert:true` (one-level undo), `delete:true` (a file, or a whole folder recursively). **A 2xx does not mean success** — a refusal is 200 with `ok:false`, so branch on `ok`. A `move` (or a `revert` that relocates or re-creates) onto a uri that already holds something answers `ok:false` + `error:"DESTINATION_EXISTS"` — nothing was overwritten; delete or rename the occupant first. A delete has ONE spelling, the `delete` key: `fields.status:"deleted"` is refused. `review` is never read from the body — a content edit (`overwrite`/`edit`/`insert`/`lines`) lands `pending_review` on every lane (visible and revertible in Changes); `create`/`move`/`copy`/`mkdir` land committed for a human interactive caller and `pending_review` from this ticket lane; `/upload` also journals agent-origin uploads as pending review; interactive human uploads land committed. Use `/write` for JSON text and `/upload` for multipart file bytes. A missing `agentId`/`uri` is a **400** naming the field, a body the server could not parse a **400** `Request body must be a JSON object`. A uri-policy denial is a **403 with no `ok` field**, a disabled source a **409** with `code:"source_disabled"`. A source slug this project does not have answers one of two ways, and BOTH mean "stop guessing this name": with a scheme (`zzz://a.md`) the uri gate answers **403 `uri_policy_denied`** first; without one (`notes.md`) you get **404 `code:"source_not_configured"`** carrying `availableSources` — the sources you CAN address. `/list` gives the 404 in both forms. Switch to a source from that list (or from `<runtime_stack>`); retrying the same name never works. `/read` is different again: it reports PER FILE inside a 200, so a denied or disabled source arrives as `{uri, error, code:"forbidden"}` — never a 409 — and a missing file as `code:"not_found"`. No code means the read failed for some other reason; do not conclude the file is gone. A folder delete or copy that partly succeeded reports what really happened: `affected` (files touched) and `failed` (the NAMES that could not be), so "failed" does not mean "nothing happened". `warning:"moved_with_source_retained"` on a move means the copy landed but the original could not be removed — BOTH copies exist on purpose; do not re-run the move. `indexed:false` means the bytes DID land and are readable, but search indexing was skipped or failed; report it, do not re-write. Sync retries failed indexing only for eligible files; excluded files remain unindexed. Every script here runs curl with `--fail-with-body`, so a non-2xx prints that body too — in the merged output the body comes FIRST and curl's own `curl: (22)` line after it, under a `--- stderr ---` separator, so read the whole output.
+- `list` / `search` / `read` / `approve` take a JSON body (`--input - <<<'<json>'`);
+  `write.sh` takes it as `BODY_JSON`. `create.sh`, `modify.sh`, `copy.sh` and `mkdir.sh` are kept only so an imported skill's existing path still writes; they exec `write.sh`, so they take the same verb-keyed body.
+- `/write` body = `{"agentId":"…","uri":"data://notes/plan.md","<verb>":…}` — the VERB is a KEY and its presence is the intent. Content verbs COMPOSE in one call, in a fixed order, as ONE write with ONE baseline: `create` (`{content, client_request_id?}` — never overwrites; a taken name lands BESIDE as `name-2.ext` and the response `uri` is where it went, so read it back), `overwrite` (`{content}` — refuses on a missing file and names `create`), `edit` (`[{old_string, new_string?, replace_all?, expected_replacements?}]`, applied in order, one failure discards all of them), `insert` (`{insert_text, insert_line?}` — inserts AFTER that line, `0` = start of file, omitted = append), `lines` (`{line_start, line_end, content}`), `fields` (`{category, status, pinned, tags{add,remove,set}, metadata}`). Structural verbs stand ALONE: `move`/`copy` (a destination uri or, for a file move, a bare new filename; `copy` may cross sources), `mkdir:true` (a real empty directory; not on `brain://`, where folders are implicit), `revert:true` (one-level undo), `delete:true` (a file, or a whole folder recursively). **A 2xx does not mean success** — a refusal is 200 with `ok:false`, so branch on `ok`. A `move` (or a `revert` that relocates or re-creates) onto a uri that already holds something answers `ok:false` + `error:"DESTINATION_EXISTS"` — nothing was overwritten; delete or rename the occupant first. A delete has ONE spelling, the `delete` key: `fields.status:"deleted"` is refused. `review` is never read from the body — a content edit (`overwrite`/`edit`/`insert`/`lines`) lands `pending_review` on every lane (visible and revertible in Changes); `create`/`move`/`copy`/`mkdir` land committed for a human interactive caller and `pending_review` from this ticket lane; `/upload` also journals agent-origin uploads as pending review; interactive human uploads land committed. Use `/write` for JSON text and `/upload` for multipart file bytes. A missing `agentId`/`uri` is a **400** naming the field, a body the server could not parse a **400** `Request body must be a JSON object`. A uri-policy denial is a **403 with no `ok` field**, a disabled source a **409** with `code:"source_disabled"`. A source slug this project does not have answers one of two ways, and BOTH mean "stop guessing this name": with a scheme (`zzz://a.md`) the uri gate answers **403 `uri_policy_denied`** first; without one (`notes.md`) you get **404 `code:"source_not_configured"`** carrying `availableSources` — the sources you CAN address. `/list` gives the 404 in both forms. Switch to a source from that list (or from `<runtime_stack>`); retrying the same name never works. `/read` is different again: it reports PER FILE inside a 200, so a denied or disabled source arrives as `{uri, error, code:"forbidden"}` — never a 409 — and a missing file as `code:"not_found"`. No code means the read failed for some other reason; do not conclude the file is gone. A folder delete or copy that partly succeeded reports what really happened: `affected` (files touched) and `failed` (the NAMES that could not be), so "failed" does not mean "nothing happened". `warning:"moved_with_source_retained"` on a move means the copy landed but the original could not be removed — BOTH copies exist on purpose; do not re-run the move. `indexed:false` means the bytes DID land and are readable, but search indexing was skipped or failed; report it, do not re-write. Sync retries failed indexing only for eligible files; excluded files remain unindexed. A non-2xx prints the route's body too — on stderr, followed by an `HTTP <code>` line, under a `--- stderr ---` separator, so read the whole output.
 - `/search` body key is `search_mode` (semantic|filter|grep) — the SAME vocabulary as the `fs_search` tool; the legacy `mode` key is rejected with 400. The route forwards `search_mode`, `query`, `folder_uri`, `glob`, `category`, `tags`, `status`, `created_after`/`created_before`, `limit`, and the grep-only `path_glob`, `context` and `case_sensitive`. In `grep` mode the search is uri-policy `read`-gated (only paths the caller holds `read` policy on are grepped), the match is a FIXED STRING, and the answer carries `truncated` + `total_seen` — a cut set says so, so never read a full-looking list as proof that the rest is absent.
-- `/raw` is a GET — pass the file URI via `URI=…` (no `BODY_JSON`). It always returns the full bytes, so `raw.sh` is unaffected by the response headers; what those headers say is a BROWSER instruction. Safe types (images except SVG, video, audio, PDF, text, JSON) are marked for inline display; SVG, HTML and XML are marked `attachment` so a person clicking the link downloads them instead of executing them on the app origin. Do not describe a `.svg` or `.html` you wrote as viewable in the browser — offer it as a download, or convert it to a raster image if a human needs to look at it.
+- `/raw` is a GET — pass the file URI as `-f uri=<uri>` and redirect stdout to a file: it always returns the full bytes, unaffected by the response headers; what those headers say is a BROWSER instruction. Safe types (images except SVG, video, audio, PDF, text, JSON) are marked for inline display; SVG, HTML and XML are marked `attachment` so a person clicking the link downloads them instead of executing them on the app origin. Do not describe a `.svg` or `.html` you wrote as viewable in the browser — offer it as a download, or convert it to a raster image if a human needs to look at it.
 - `/read` is at parity with the `fs_read` tool: the body takes `files[]` — each entry a URI string or `{"uri":"…","line_start":N,"line_end":M}` with that file's own window — plus `read_version`, batch-level `line_start`/`line_end` and `include_ids`. An entry that is neither shape is a **400**. Text is a bounded preview; native media may accompany it, while unsupported/invalid binary data has a URI and marker. For a byte-exact binary copy use the authorized `/raw` byte lane and multipart `/upload`, never re-encode a text preview. If you only need the pre-edit content, a plain `/read` response already carries it: each file's `version.baseline.content`, with `available_versions` listing `baseline` exactly when one exists.
-- `/upload` is **multipart/form-data**, NOT JSON — pass `FILE_PATH=…` `AGENT_ID=…` (required) plus optional `URI=…` / `TAGS=a,b`; a JSON body is rejected with 400. The 200 carries `indexed`: `false` means the bytes DID land but search indexing was skipped by the source selection or failed (provider outage/quota) — report it, do not re-upload. An eligible sync retries failed indexing; excluded uploads remain unindexed until the selection changes. The 200 also carries `mimeType`, and it may differ from what the upload declared: the stored type is resolved from the filename extension first, with the declared value kept only for an extension the platform does not know, and a common-image claim the leading bytes contradict falls back to `application/octet-stream`. Give the file a truthful extension and the stored type follows.
-- `GET /pending` lists durable pending records inside the Changes workspace. `STATUS`, `SOURCE`, `OP`, and `LIMIT` filter the list; owner/scope and URI READ gates apply per record. Review begins with `POST /pending` `{action:"preview",id}`: it returns the current connector content separately from the recorded snapshot and saved baseline, typed missing/unavailable/binary/too-large states, `indexState`, `requiresAcknowledgement`, and `expectedFingerprint`. The preview is bounded by `pendingPreviewMaxBytes`; it never fabricates missing content or vectors. Resolve through `POST /approve` `{id,expectedFingerprint}` or `POST /pending` `{action:"revert"|"dismiss",id,expectedFingerprint}`. If the preview requires acknowledgement, inspect those states and include `acknowledgeCurrentState:true`; never auto-acknowledge an unseen preview. The server rechecks freshness and WRITE authority at apply: a changed fingerprint requires a new preview, and acknowledgement grants no missing permission. Bare legacy `/write revert:true` refuses unsafe pending recovery; ordinary non-pending one-level undo remains available. Approval/dismissal preserve the stored snapshot/index state (including recovery-only or absent index), rather than certifying current connector bytes as indexed. For a file the preview shows `missing` with a saved `journal-latest-write` baseline, an acknowledged approve/dismiss closes the review and the file stays gone; revert is the restore. Terminal retries remain owner-gated and idempotent; `uri` is omitted without current READ and WRITE access. Revert restores the saved baseline and refuses missing baselines or occupied move destinations. Discard/Repair remain orphan-only, owner-gated operations; no transient outage is proof of orphanhood.
+- `/upload` is **multipart/form-data**, NOT JSON — `upload.sh` takes `FILE_PATH=…` `AGENT_ID=…` (required) plus optional `URI=…` / `TAGS=a,b`; a JSON body is rejected with 400. The 200 carries `indexed`: `false` means the bytes DID land but search indexing was skipped by the source selection or failed (provider outage/quota) — report it, do not re-upload. An eligible sync retries failed indexing; excluded uploads remain unindexed until the selection changes. The 200 also carries `mimeType`, and it may differ from what the upload declared: the stored type is resolved from the filename extension first, with the declared value kept only for an extension the platform does not know, and a common-image claim the leading bytes contradict falls back to `application/octet-stream`. Give the file a truthful extension and the stored type follows.
+- `GET /pending` lists durable pending records inside the Changes workspace. `status` (`pending_review`\|`approved`\|`reverted`), `source`, `op` (`create`\|`modify`\|`delete`\|`move`) and `limit` filter the list; owner/scope and URI READ gates apply per record. Review begins with `POST /pending` `{action:"preview",id}`: it returns the current connector content separately from the recorded snapshot and saved baseline, typed missing/unavailable/binary/too-large states, `indexState`, `requiresAcknowledgement`, and `expectedFingerprint`. The preview is bounded by `pendingPreviewMaxBytes`; it never fabricates missing content or vectors. Resolve through `POST /approve` `{id,expectedFingerprint}` or `POST /pending` `{action:"revert"|"dismiss",id,expectedFingerprint}`. If the preview requires acknowledgement, inspect those states and include `acknowledgeCurrentState:true`; never auto-acknowledge an unseen preview. The server rechecks freshness and WRITE authority at apply: a changed fingerprint requires a new preview, and acknowledgement grants no missing permission. Bare legacy `/write revert:true` refuses unsafe pending recovery; ordinary non-pending one-level undo remains available. Approval/dismissal preserve the stored snapshot/index state (including recovery-only or absent index), rather than certifying current connector bytes as indexed. For a file the preview shows `missing` with a saved `journal-latest-write` baseline, an acknowledged approve/dismiss closes the review and the file stays gone; revert is the restore. Terminal retries remain owner-gated and idempotent; `uri` is omitted without current READ and WRITE access. Revert restores the saved baseline and refuses missing baselines or occupied move destinations. Discard/Repair remain orphan-only, owner-gated operations; no transient outage is proof of orphanhood.
 
 
-The body shape is route-specific — refer to brain-core's
-`/api/packages/@neuralis/brain-core/list,search,read,write,…` route source
-for the exact schemas. For one-off calls, prefer the `fs_*` tools.
+For one-off calls, prefer the `fs_*` tools.
 
 ## Examples
 
 For a disposable pending record you created in your project, substitute its real id below. Inspect the preview before resolving; copy its exact fingerprint, and add acknowledgement only after reviewing the states the preview names. A 409 requires a new preview, never a fabricated fingerprint.
 
 ```bash
-BODY_JSON='{"action":"preview","id":"<scratch-record-id>"}' bash ${SKILL_DIR}/scripts/pending.sh
-BODY_JSON='{"action":"revert","id":"<scratch-record-id>","expectedFingerprint":"<64-hex-preview-fingerprint>","acknowledgeCurrentState":true}' bash ${SKILL_DIR}/scripts/pending.sh
+neuralis request POST @neuralis/brain-core/pending -f action=preview -f id=<scratch-record-id>
+neuralis request POST @neuralis/brain-core/pending --input - <<<'{"action":"revert","id":"<scratch-record-id>","expectedFingerprint":"<64-hex-preview-fingerprint>","acknowledgeCurrentState":true}'
 ```
 
+Pending calls return one page; scan-orphans preserves that page in `changes` and puts its orphan subset in `orphans`/`orphanIds`: pass `cursor` from `nextCursor` unchanged with the same filters, or `uri` for an exact URI. Check `complete`, `partial` and `hasMoreAvailable`; a partial exhausted branch remains incomplete. On `restartRequired`, restart the list instead of retrying the old cursor. Repair returns scannedVisible/orphaned/attempted/discarded/refused/failed/reasons for one batch; continue only via nextCursor; pause on partial and use an explicit Continue available/Retry.
+
 ```bash
 # Recursive list of /data
-BODY_JSON='{"uri":"data://","recursive":true,"limit":100}' \
-  bash ${SKILL_DIR}/scripts/list.sh
+neuralis request POST @neuralis/brain-core/list --input - <<<'{"uri":"data://","recursive":true,"limit":100}'
 
 # Vector search across all sources (body key is `search_mode`, same as the fs_search tool)
-BODY_JSON='{"search_mode":"semantic","query":"telemetry pipeline","limit":10}' \
-  bash ${SKILL_DIR}/scripts/search.sh
+neuralis request POST @neuralis/brain-core/search -f search_mode=semantic -f query='telemetry pipeline' -F limit=10
+
+# Pending review records still waiting, one page
+neuralis request GET @neuralis/brain-core/pending -f status=pending_review -f limit=20
+
+# The exact bytes of one file
+neuralis request GET @neuralis/brain-core/raw -f uri=data://report.pdf > /tmp/report.pdf
 
 # Create a text file — the journaled write lane. The verb is the KEY.
 # `<agent-id>` is a placeholder; a real id makes this line write for real.

package/skills/manage-files/scripts/upload.sh

@@ -1,7 +1,5 @@
 #!/usr/bin/env bash
 set -euo pipefail
-API_BASE="${NEURALIS_API:?NEURALIS_API not set; activate skill first}"
-TOKEN="${NEURALIS_SESSION_TOKEN:?missing session ticket; activate the skill via execute action=\"skill\"}"
 # POST /upload REQUIRES multipart/form-data (NOT a JSON body): the handler reads the
 # form fields file (the binary/text payload), agentId, uri (optional), tags (optional,
 # comma-split). projectId is taken from the session ticket — passing a different one
@@ -9,10 +7,10 @@ TOKEN="${NEURALIS_SESSION_TOKEN:?missing session ticket; activate the skill via
 # from the form field.
 FILE_PATH="${FILE_PATH:?FILE_PATH is required (local path of the payload to upload)}"
 AGENT_ID="${AGENT_ID:?AGENT_ID is required (form field; the destination agent)}"
-curl --fail-with-body -sS -X POST \
-  -H "Authorization: Bearer ${TOKEN}" -H "X-Neuralis-Skill: manage-files" \
-  -F "file=@${FILE_PATH}" \
-  -F "agentId=${AGENT_ID}" \
-  ${URI:+-F "uri=${URI}"} \
-  ${TAGS:+-F "tags=${TAGS}"} \
-  "${API_BASE}/api/packages/@neuralis/brain-core/upload"
+# `--form` sends multipart/form-data (`file=@path` is the file part). A non-2xx
+# answer prints the route's body and `HTTP <code>` on stderr and exits 1.
+neuralis request POST @neuralis/brain-core/upload \
+  --form "file=@${FILE_PATH}" \
+  --form "agentId=${AGENT_ID}" \
+  ${URI:+--form "uri=${URI}"} \
+  ${TAGS:+--form "tags=${TAGS}"}

package/skills/manage-files/scripts/write.sh

@@ -16,8 +16,6 @@ set -euo pipefail
 # `edit`, `insert`, `lines`) lands `pending_review` on EVERY lane; `create`, `move`,
 # `copy` and `mkdir` land committed for a human interactive caller and
 # `pending_review` from this ticket lane; `delete` tombstones on both.
-API_BASE="${NEURALIS_API:?NEURALIS_API not set; activate skill first}"
-TOKEN="${NEURALIS_SESSION_TOKEN:?missing session ticket; activate the skill via execute action=\"skill\"}"
 BODY_JSON="${BODY_JSON:?BODY_JSON is required — a JSON object with agentId, uri and ONE verb key; see the header comment for the shape}"
 # The retired body shape names no verb; the route would only say "Missing uri".
 # Refuse it HERE, naming what the caller has to send instead.
@@ -27,7 +25,5 @@ case "${BODY_JSON}" in
     exit 2
     ;;
 esac
-curl --fail-with-body -sS -X POST \
-  -H "Authorization: Bearer ${TOKEN}" -H "X-Neuralis-Skill: manage-files" \
-  -H "Content-Type: application/json" -d "${BODY_JSON}" \
-  "${API_BASE}/api/packages/@neuralis/brain-core/write"
+# A non-2xx answer prints the route's body and `HTTP <code>` on stderr and exits 1.
+neuralis request POST @neuralis/brain-core/write --input - <<<"${BODY_JSON}"