@neuralis/brain-core 0.2.1 → 0.3.1

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}"