@neuralis/brain-core 0.3.1 → 0.4.0

package/skills/create-package/scripts/{verify-loaded.sh → verify-loaded.mjs}

@@ -1,84 +1,94 @@
-#!/usr/bin/env bash
-#
-# create-package/verify-loaded.sh — runtime proof that a package actually loaded.
-#
-# "It built clean" is not "it loaded". A package can compile, install, appear on
-# disk, and still register NOTHING — one bad tool schema aborts the whole load,
-# a missing build makes it declarative-only, an untrusted node runtime leaves
-# every handler returning an error. This script asks the platform, and reports
-# only what the platform said.
-#
-# WHAT IT CHECKS
-#   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 |
-#                untrusted-node | untrusted-mcp)
-#     error    — validation or init crash; prints the recorded message
-#     missing  — installed but never reached the loader (manifest read failed)
-#     absent   — the platform does not list it for you at all; the verdict then
-#                prints every installed AND source package id it DOES list, so
-#                you can find the right one without guessing
-#   On a clean load it also prints the surface the platform registered FOR YOU:
-#   tools, skills, instructions, rules, agents, docs, commands, workflows,
-#   connectors, hooks, policies, app surfaces, team members, active file count.
-#   The `connectors` row counts DECLARATIONS the loader accepted from the
-#   manifest — not live outbound instances. An outbound (mcp/openapi/http)
-#   connector is registered into ONE tenant, and into NO tenant at all when the
-#   package is neither first-party nor owned by a resolvable project, so this
-#   count can be non-zero while the connector exists nowhere.
-#   A source package (markdown discovered in an indexed source) has no loader
-#   status at all — it is reported separately, with its recognition reason.
-#
-# WHAT IT CANNOT CHECK
-#   That a surface WORKS. A loaded package with a broken handler still says
-#   `loaded`. Run the tool, open the widget, call the route — as the LEAST
-#   privileged role that is supposed to have access, because feature-gated
-#   contributions are hidden, so testing as the owner hides every gate bug.
-#   It also cannot see what your identity may not see: these surfaces are
-#   scoped, so `absent` can mean "correctly hidden from you", not "broken".
-#   For a source package `absent` also covers "the files exist on disk but no
-#   sync has indexed them yet" — discovery reads the index, never the live tree.
-#   For the static half run, before you install:
-#     bash "${SKILL_DIR}/scripts/check-package.sh" <package-root>
-#
-# USAGE   bash verify-loaded.sh <package-id> [--raw]
-#           <package-id>  the manifest id, e.g. "@acme/reports" or "reports".
-#                         A drop or source package: its instance URI, quoted.
-#           --raw         dump both untouched JSON responses before the verdict,
-#                         so you can self-diagnose if the shape ever drifts.
-# EXIT    0 = loaded
-#         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 `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.
-#
-# This script never accepts, prints or persists a token.
-#
-# Testing reference: https://docs.neuralisapp.com/package-system/testing
+//
+// create-package/verify-loaded.mjs — runtime proof that a package actually loaded.
+//
+// "It built clean" is not "it loaded". A package can compile, install, appear on
+// disk, and still register NOTHING — one bad tool schema aborts the whole load,
+// a missing build makes it declarative-only, an untrusted node runtime leaves
+// every handler returning an error. This script asks the platform, and reports
+// only what the platform said.
+//
+// WHAT IT CHECKS
+//   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 |
+//                untrusted-node | untrusted-mcp)
+//     error    — validation or init crash; prints the recorded message
+//     missing  — installed but never reached the loader (manifest read failed)
+//     absent   — the platform does not list it for you at all; the verdict then
+//                prints every installed AND source package id it DOES list, so
+//                you can find the right one without guessing
+//   On a clean load it also prints the surface the platform registered FOR YOU:
+//   tools, skills, instructions, rules, agents, docs, commands, workflows,
+//   connectors, hooks, policies, app surfaces, team members, active file count.
+//   The `connectors` row counts DECLARATIONS the loader accepted from the
+//   manifest — not live outbound instances. An outbound (mcp/openapi/http)
+//   connector is registered into ONE tenant, and into NO tenant at all when the
+//   package is neither native nor owned by a resolvable project, so this
+//   count can be non-zero while the connector exists nowhere.
+//   A source package (markdown discovered in an indexed source) has no loader
+//   status at all — it is reported separately, with its recognition reason.
+//
+// WHAT IT CANNOT CHECK
+//   That a surface WORKS. A loaded package with a broken handler still says
+//   `loaded`. Run the tool, open the widget, call the route — as the LEAST
+//   privileged role that is supposed to have access, because feature-gated
+//   contributions are hidden, so testing as the owner hides every gate bug.
+//   It also cannot see what your identity may not see: these surfaces are
+//   scoped, so `absent` can mean "correctly hidden from you", not "broken".
+//   For a source package `absent` also covers "the files exist on disk but no
+//   sync has indexed them yet" — discovery reads the index, never the live tree.
+//   For the static half run, before you install:
+//     node "${SKILL_DIR}/scripts/check-package.mjs" <package-root>
+//
+// USAGE   node verify-loaded.mjs <package-id> [--raw]
+//           <package-id>  the manifest id, e.g. "@acme/reports" or "reports".
+//                         A drop or source package: its instance URI, quoted.
+//           --raw         dump both untouched JSON responses before the verdict,
+//                         so you can self-diagnose if the shape ever drifts.
+// EXIT    0 = loaded
+//         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 `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.
+//
+// The CLI runs as `node <NEURALIS_CLI_ENTRY> request …` — the entry every
+// Neuralis runner exports — and never through a shell. With the variable
+// absent, Linux and macOS start `neuralis` from PATH; Windows stops by name.
+//
+// This script never accepts, prints or persists a token.
+//
+// Testing reference: https://docs.neuralisapp.com/package-system/testing
 
-set -euo pipefail
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
 
-RAW=0
-PKG_ID=""
-for arg in "$@"; do
-  case "$arg" in
-    --raw) RAW=1 ;;
-    -h|--help) sed -n '2,60p' "$0" | sed 's/^#\{0,1\} \{0,1\}//'; exit 0 ;;
-    -*) echo "unknown flag: $arg" >&2; exit 4 ;;
-    *) if [ -z "$PKG_ID" ]; then PKG_ID="$arg"; else echo "unexpected argument: $arg" >&2; exit 4; fi ;;
-  esac
-done
-
-manual_fallback() {
-  case "$PKG_ID" in
-    *://*)
-      cat >&2 <<'SRCFALLBACK'
+const SELF = fileURLToPath(import.meta.url);
+let RAW = false;
+let pkgId = '';
+for (const arg of process.argv.slice(2)) {
+  if (arg === '--raw') RAW = true;
+  else if (arg === '-h' || arg === '--help') {
+    const head = readFileSync(SELF, 'utf8').split('\n');
+    const end = head.findIndex((l) => !l.startsWith('//'));
+    process.stdout.write(`${head.slice(1, end).map((l) => l.replace(/^\/\/ ?/, '')).join('\n')}\n`);
+    process.exit(0);
+  } else if (arg.startsWith('-')) {
+    process.stderr.write(`unknown flag: ${arg}\n`);
+    process.exit(4);
+  } else if (!pkgId) pkgId = arg;
+  else {
+    process.stderr.write(`unexpected argument: ${arg}\n`);
+    process.exit(4);
+  }
+}
 
+const SOURCE_FALLBACK = `
 Cannot verify programmatically. Do NOT record this package as working.
 
 A SOURCE package never passes through the loader, so there is NO load line
@@ -99,12 +109,8 @@ Verify a source package this way instead:
      SKILL.md, a marker dot-dir, or a usable manifest), and inside skills/
      only a file named SKILL.md counts.
 
-SRCFALLBACK
-      return
-      ;;
-  esac
-  cat >&2 <<FALLBACK
-
+`;
+const LOG_FALLBACK = `
 Cannot verify programmatically. Do NOT record this package as working.
 Fall back to the server log — the loader writes one line per package:
 
@@ -121,85 +127,76 @@ Fall back to the server log — the loader writes one line per package:
 Search the platform logs for your package id and read which of those five
 lines names it. No line at all means the loader never saw it: the install
 did not land, or the manifest could not be read.
-FALLBACK
-}
-
-if [ -z "$PKG_ID" ]; then
-  echo "usage: bash verify-loaded.sh <package-id> [--raw]" >&2
-  exit 4
-fi
-if ! command -v neuralis >/dev/null 2>&1; then
-  echo "ERROR  neuralis (the CLI) not found on PATH" >&2
-  manual_fallback
-  exit 4
-fi
-if ! command -v node >/dev/null 2>&1; then
-  echo "ERROR  node not found on PATH — this script parses JSON with node, not jq" >&2
-  manual_fallback
-  exit 4
-fi
-BASE_ROUTE="@neuralis/agent-core/packages"
-
-WORK="$(mktemp -d)"
-trap 'rm -rf "$WORK"' EXIT
+`;
+const manualFallback = () => process.stderr.write(pkgId.includes('://') ? SOURCE_FALLBACK : LOG_FALLBACK);
+const fail = (message) => {
+  process.stderr.write(`${message}\n`);
+  manualFallback();
+  process.exit(4);
+};
 
-# `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"
+if (!pkgId) {
+  process.stderr.write('usage: node verify-loaded.mjs <package-id> [--raw]\n');
+  process.exit(4);
 }
+const BASE_ROUTE = '@neuralis/agent-core/packages';
 
-DIAG_CODE="$(fetch "${BASE_ROUTE}/diagnostics" "$WORK/diag.json")"
-
-if [ "$DIAG_CODE" = "403" ]; then
-  echo "FORBIDDEN  the package diagnostics surface requires the 'core.observe' feature, and your identity does not hold it." >&2
-  echo "           This is a capability you are missing, not a broken package — say so instead of retrying." >&2
-  manual_fallback
-  exit 4
-fi
-if [ "$DIAG_CODE" != "200" ]; then
-  echo "ERROR  GET ${BASE_ROUTE}/diagnostics returned HTTP ${DIAG_CODE}" >&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
-fi
-
-OVER_CODE="$(fetch "${BASE_ROUTE}/overview" "$WORK/overview.json")"
-[ "$OVER_CODE" = "200" ] || : > "$WORK/overview.json"
+// `neuralis request` prints a 2xx body on stdout (exit 0); a non-2xx body goes to
+// stderr after an `HTTP <code>` line (exit 1). No such line = no answer at all
+// (no CLI login, no network) — "000"; its error text stays in `err`.
+function fetchRoute(route) {
+  const args = ['request', 'GET', route];
+  const opts = { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'], maxBuffer: 256 * 1024 * 1024 };
+  const entry = process.env.NEURALIS_CLI_ENTRY;
+  if (entry === undefined && process.platform === 'win32') {
+    fail('ERROR  set NEURALIS_CLI_ENTRY to the neuralis CLI entry (…/dist/neuralis.mjs) — on Windows this script starts the CLI through node, never a shell');
+  }
+  try {
+    const body = entry !== undefined ? execFileSync(process.execPath, [entry, ...args], opts) : execFileSync('neuralis', args, opts);
+    return { code: '200', body, err: '' };
+  } catch (e) {
+    if (e.code === 'ENOENT') fail('ERROR  neuralis (the CLI) not found on PATH');
+    const err = typeof e.stderr === 'string' ? e.stderr : '';
+    const lines = err.split('\n');
+    const at = lines.findIndex((l) => /^HTTP [0-9]{3}$/.test(l));
+    if (at < 0) return { code: '000', body: '', err };
+    return { code: lines[at].slice(5), body: lines.slice(at + 1).join('\n'), err };
+  }
+}
 
-if [ "$RAW" = "1" ]; then
-  echo "--- diagnostics (HTTP ${DIAG_CODE}) ---"
-  cat "$WORK/diag.json"; echo
-  echo "--- overview (HTTP ${OVER_CODE}) ---"
-  cat "$WORK/overview.json"; echo
-  echo "--- verdict ---"
-fi
+const diagRes = fetchRoute(`${BASE_ROUTE}/diagnostics`);
+if (diagRes.code === '403') {
+  fail("FORBIDDEN  the package diagnostics surface requires the 'core.observe' feature, and your identity does not hold it.\n"
+    + '           This is a capability you are missing, not a broken package — say so instead of retrying.');
+}
+if (diagRes.code !== '200') {
+  let detail = `ERROR  GET ${BASE_ROUTE}/diagnostics returned HTTP ${diagRes.code}`;
+  if (diagRes.err) detail += `\n${diagRes.err.replace(/\n$/, '').split('\n').map((l) => `       ${l}`).join('\n')}`;
+  if (diagRes.body) detail += `\n${diagRes.body.slice(0, 600)}`;
+  fail(detail);
+}
+const overRes = fetchRoute(`${BASE_ROUTE}/overview`);
+const overCode = overRes.code;
+if (overCode !== '200') overRes.body = '';
 
-set +e
-node - "$PKG_ID" "$WORK/diag.json" "$WORK/overview.json" "$OVER_CODE" <<'NODE_VERIFY'
-'use strict';
-const fs = require('fs');
-const [, , pkgId, diagPath, overPath, overCode] = process.argv;
+if (RAW) {
+  process.stdout.write(`--- diagnostics (HTTP ${diagRes.code}) ---\n${diagRes.body}\n`);
+  process.stdout.write(`--- overview (HTTP ${overCode}) ---\n${overRes.body}\n`);
+  process.stdout.write('--- verdict ---\n');
+}
 
-const readMaybe = (p) => {
-  try { const t = fs.readFileSync(p, 'utf8'); return t.trim() ? JSON.parse(t) : null; }
+const readMaybe = (t) => {
+  try { return t.trim() ? JSON.parse(t) : null; }
   catch { return null; }
 };
 
-const diag = readMaybe(diagPath);
+const diag = readMaybe(diagRes.body);
 if (!diag || !Array.isArray(diag.entries)) {
   process.stderr.write('ERROR  the diagnostics response did not carry an "entries" array — the response shape drifted.\n');
   process.stderr.write('       Re-run with --raw and read the payload before trusting any verdict.\n');
   process.exit(4);
 }
-const over = readMaybe(overPath);
+const over = readMaybe(overRes.body);
 const overPackages = over && Array.isArray(over.packages) ? over.packages : [];
 const overSource = over && Array.isArray(over.sourcePackages) ? over.sourcePackages : [];
 
@@ -309,9 +306,9 @@ const counts = () => {
     // an outbound connector is registered into ONE tenant, or into none.
     process.stdout.write('  NOTE: connectors are DECLARATIONS, not live instances. An outbound\n');
     process.stdout.write('        (mcp/openapi/http) connector registers into exactly one tenant — the\n');
-    process.stdout.write('        platform lane for a first-party install, the owning project for a\n');
+    process.stdout.write('        platform lane for a native install, the owning project for a\n');
     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('        native 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('        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');
@@ -325,8 +322,8 @@ const counts = () => {
 const REASONS = {
   'build-missing': 'the sandbox artifact was never built. Build the package, then reinstall.',
   'runtime-unavailable': 'the declared runtime could not start (a subprocess that failed to spawn, or a code runtime that crashed). Check the entry command and the runtime type.',
-  'untrusted-node': 'the manifest declares the in-process "node" runtime, which requires first-party trust. Declare "wasm" to run code on any other tier.',
-  'untrusted-mcp': 'the manifest declares the "mcp" runtime, which spawns a subprocess as the host user and requires first-party trust, so nothing was spawned. Declare "wasm" — it is the only code runtime available below first-party.',
+  'untrusted-node': 'the manifest declares the in-process "node" runtime, which requires native trust. Declare "wasm" to run code on any other tier.',
+  'untrusted-mcp': 'the manifest declares the "mcp" runtime, which spawns a subprocess as the host user and requires native trust, so nothing was spawned. Declare "wasm" — it is the only code runtime available below native.',
 };
 
 if (status === 'loaded') {
@@ -343,10 +340,11 @@ if (status === 'loaded') {
   process.stdout.write('If a skill of this package still answers "Skill not found" in the conversation\n');
   process.stdout.write('that just enabled, trusted or installed it: those changes apply from the NEXT\n');
   process.stdout.write('stream (a new user message, a workflow run, or a fresh conversation), never\n');
-  process.stdout.write('mid-turn. A delegate spawned after the change sees its <packages> entry,\n');
-  process.stdout.write('injected rules/instructions and agent resolution fresh, but its tool catalog\n');
-  process.stdout.write('and skill activation still use the parent stream\'s gate. Retry from a fresh\n');
-  process.stdout.write('stream before re-diagnosing.\n');
+  process.stdout.write('mid-turn. A FOREGROUND delegate spawned after the change sees its <packages>\n');
+  process.stdout.write('entry, injected rules/instructions and agent resolution fresh, but its tool\n');
+  process.stdout.write('catalog and skill activation still use the parent stream\'s gate; a background\n');
+  process.stdout.write('delegate re-reads all of them at its wake. Retry from a fresh stream before\n');
+  process.stdout.write('re-diagnosing.\n');
   process.exit(0);
 }
 
@@ -369,7 +367,7 @@ if (status === 'error' || status === 'missing') {
   if (entry.sourceRoot) line('sourceRoot', entry.sourceRoot);
   process.stdout.write(status === 'missing'
     ? '\nInstalled but it never reached the loader — the manifest could not be read.\n  Check that package.json exists at the install root, parses, and carries a\n  "neuralis" block with an id.\n'
-    : '\nValidation or init crashed and NOTHING registered. The message above is the\n  loader\'s own; a tool-schema error names the file that aborted the load.\n  Fix it, then run check-package.sh on the package root before reinstalling.\n');
+    : '\nValidation or init crashed and NOTHING registered. The message above is the\n  loader\'s own; a tool-schema error names the file that aborted the load.\n  Fix it, then run check-package.mjs on the package root before reinstalling.\n');
   process.exit(3);
 }
 
@@ -377,7 +375,3 @@ process.stdout.write(`UNKNOWN STATUS  ${pkgId} -> "${status}"\n`);
 process.stdout.write('The status vocabulary is loaded | partial | error | missing. Anything else\n');
 process.stdout.write('means the response shape drifted — re-run with --raw and read the payload.\n');
 process.exit(4);
-NODE_VERIFY
-NODE_STATUS=$?
-set -e
-exit "$NODE_STATUS"

package/skills/git/SKILL.md

@@ -2,22 +2,22 @@
 name: git
 description: "Operate git on a git-backed source through governed routes: inspect status, diff, history, and outgoing changes; stage, discard, commit, branch, switch, fetch, pull, or push. Use for repository work; choose governed git by default, raw CLI for allowed local inspection, and GitHub tools for remote collaboration."
 allowed-tools: execute
-requiredFeatures: [drive.read]
+requiredFeatures: [files.read]
 ---
 
 # Git
 
-Drive git on a **git-backed source** (any `local`-kind source that is a git checkout)
+Drive git on a **git-backed source** (any folder that is a git checkout — on this server, or on a paired device, where git runs on that device for its owner or for a member it admits; fetch/pull/push of a device folder run only for the device's owner, with their own git credentials there — anyone else gets `git_remote_owner_only`)
 through brain-core's governed git routes. These are the **same routes the Git Control
 panel drives**, so an agent gets exactly the rights a human member has: gated by
-`drive.read` / `drive.write` + the source's uri-policy, with a **server-side snapshot
+`files.read` / `files.write` + the source's uri-policy, with a **server-side snapshot
 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 `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
+server-side, or — on a device folder — use its owner's own git credentials there). 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.
 
@@ -31,8 +31,8 @@ agent operating git on a user's source.
 
 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 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.
+Plane A is always "call the routes with `neuralis request`" — the native `git` connector shown in the
+`<packages>` overview is metadata; there are no native git MCP *tools* to call.
 
 ## Routes covered
 
@@ -54,12 +54,11 @@ source and fence the rest with path policy, or split the subtree into its own re
 raw-CLI workaround.
 
 **But the refusal is only LOUD on the write side, and this has already fooled a run.** A write
-route answers a scrubbed **`400 git_outside_source`**. The four root-gated summary READS —
-`status`, `branch`, `log`, `log-stats` — **fail SOFT**: they answer `200 {"ok":true, …}` with an
-empty payload (`status` → `branch:null` + three empty buckets; `branch` → `branches:[]`;
-`log` → `commits:[]`; `log-stats` → `stats:{}`), which is **byte-identical to a clean repository
-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
+route answers a scrubbed **`400 git_outside_source`**. Three root-gated summary READS —
+`branch`, `log`, `log-stats` — **fail SOFT**: they answer `200 {"ok":true, …}` with an empty
+payload (`branch` → `branches:[]`; `log` → `commits:[]`; `log-stats` → `stats:{}`), which is
+**byte-identical to a clean repository with nothing to report**. The same empty answer covers a
+source with no `.git` at all. (`status`, `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 `neuralis request` exits 0: a zero exit with `ok:false` is a
@@ -67,41 +66,39 @@ soft answer, a non-zero exit is an HTTP refusal whose body and `HTTP <code>` are
 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.
-**Ask `repos` first.** `{"ok":true,"repos":[]}` means there is no checkout at the source root and
-none one level down — every root-gated read on that source will fail soft, so report the git plane
-**UNKNOWN** and stop. A non-empty `repos` is **not yet** a live plane: rows carry `rel`, and only a
-row with `rel:""` is the SOURCE ROOT — any other `rel` is a nested checkout that answers only when
-you pass `repo=<rel>`, so a list of nested rows leaves a root-gated `status` (no `repo`) still
-failing soft. And a `rel:""` row only proves a `.git` is THERE, not that git accepted it — the
-containment refusal above keeps its row. Confirm on the repo you are about to trust with
-`outgoing`: `{"ok":true,…}` proves git actually ran there; `{"ok":false,"code":"unavailable"}`
-leaves it UNKNOWN (a dead plane and an unborn HEAD answer alike). Only then does an empty `status`
-mean a clean tree. When you have already read an empty `status` and cannot re-ask, say the plane was
-unreadable; never write "no changes" into a report you cannot back.
+**So an empty `branch`/`log`/`log-stats` read is never evidence of a clean tree — `status` is.**
+`{"ok":true,…}` from `status` proves git ran on that checkout, so empty buckets there mean a clean
+tree; `{"ok":false,"code":"unavailable"}` means git could not read it (no checkout at that root, the
+containment refusal above, or git failing there) — report the git plane **UNKNOWN**. Do not test
+with `branch:null`: a real repository on a detached HEAD, or freshly initialised with no commit
+yet, reports exactly that. **Ask `repos` first** to find the checkout. `{"ok":true,"repos":[]}`
+means there is no checkout at the source root and none one level down. Rows carry `rel`, and only
+a row with `rel:""` is the SOURCE ROOT — any other `rel` is a nested checkout that answers only
+when you pass `repo=<rel>`. A `rel:""` row only proves a `.git` is THERE, not that git accepted it
+— the containment refusal keeps its row, so `status` stays the confirmation. Never write "no
+changes" into a report you cannot back.
 
 | Action | Method | Route | Key params | Gate |
 |---|---|---|---|---|
-| Whole-repo change-set + branch + ahead/behind | GET | `status` | `source`,`repo?` | `drive.read` + uri-policy `read` (root) |
-| Local branch list | GET | `branch` | `source`,`repo?` | `drive.read` + `read` (root) |
-| Per-file unified diff | GET | `diff` | `source`,`path` **(required)**; optionally one of `staged=1` \| `commit=<sha>` \| `base=<sha>&head=<sha>` (omit all three for the unstaged working-tree diff) | `drive.read` + `read` (per-path) |
-| Blob content at a rev | GET | `show` | `source`,`path`,`rev=index\|<sha>` | `drive.read` + `read` (per-path) |
-| Commit-DAG page (+ `outgoing[]`) | GET | `log` | `source`,`maxCount?`,`skip?`,`ref?` | `drive.read` + `read` (root) |
-| Per-commit `+/-` totals for a log page | GET | `log-stats` | `source`,`maxCount?`,`skip?`,`ref?` | `drive.read` + `read` (root) |
-| Files a commit changed | GET | `commit` | `source`,`sha=<sha>` | `drive.read` + `read` (root) |
-| Committed-but-not-pushed files | GET | `outgoing` | `source` | `drive.read` + `read` (root) |
-| In-source repo picker — **and the plane-liveness test: empty `repos` ⇒ every root-gated read fails soft** | GET | `repos` | `source` | `drive.read` + `read` (root) |
-| Stage whole files or a hunk | POST | `stage` | `source`,`paths:[…]` **or** `hunk:"<patch>"` | `drive.write` + `write` (per-path) |
-| Unstage whole files or a hunk | POST | `unstage` | `source`,`paths:[…]` **or** `hunk` | `drive.write` + `write` (per-path) |
-| Discard working-tree changes (**destructive** → returns `rescue`) | POST | `discard` | `source`,`paths:[…]` | `drive.write` + `write` (per-path) |
-| Create a commit from the index | POST | `commit` | `source`,`message`,`amend?` | `drive.write` + `write` (root) |
-| Create / delete a branch (delete **destructive** → `rescue`) | POST | `branch` | `source`,`action:"create"\|"delete"`,`name`,`startPoint?`,`force?` | `drive.write` + `write` (root) |
-| Switch branch (plain, refuses to clobber → 409) | POST | `checkout` | `source`,`ref` | `drive.write` + `write` (root) |
-| **Undo** a `discard` / `branch` delete from its `rescue` carrier | POST | `restore` | `source`,`rescue:{kind:"stash"\|"branch",ref,name?}` | `drive.write` + `write` (root) |
-| Fetch from the connected remote | POST | `fetch` | `source` | `drive.write` + uri-policy **`exec`** + connected remote |
-| Pull (fetch + fast-forward-only merge) | POST | `pull` | `source` | `drive.write` + `exec` + `write` + connected remote |
-| Push `HEAD` (no force) | POST | `push` | `source` | `drive.write` + `exec` + connected remote |
+| Whole-repo change-set + branch + ahead/behind | GET | `status` | `source`,`repo?` | `files.read` + uri-policy `read` (root) |
+| Local branch list | GET | `branch` | `source`,`repo?` | `files.read` + `read` (root) |
+| Per-file unified diff | GET | `diff` | `source`,`path` **(required)**; optionally one of `staged=1` \| `commit=<sha>` \| `base=<sha>&head=<sha>` (omit all three for the unstaged working-tree diff) | `files.read` + `read` (per-path) |
+| Blob content at a rev | GET | `show` | `source`,`path`,`rev=index\|<sha>` | `files.read` + `read` (per-path) |
+| Commit-DAG page (+ `outgoing[]`) | GET | `log` | `source`,`maxCount?`,`skip?`,`ref?` | `files.read` + `read` (root) |
+| Per-commit `+/-` totals for a log page | GET | `log-stats` | `source`,`maxCount?`,`skip?`,`ref?` | `files.read` + `read` (root) |
+| Files a commit changed | GET | `commit` | `source`,`sha=<sha>` | `files.read` + `read` (root) |
+| Committed-but-not-pushed files | GET | `outgoing` | `source` | `files.read` + `read` (root) |
+| In-source repo picker — **empty `repos` ⇒ no checkout at the root or one level down** | GET | `repos` | `source` | `files.read` + `read` (root) |
+| Stage whole files or a hunk | POST | `stage` | `source`,`paths:[…]` **or** `hunk:"<patch>"` | `files.write` + `write` (per-path) |
+| Unstage whole files or a hunk | POST | `unstage` | `source`,`paths:[…]` **or** `hunk` | `files.write` + `write` (per-path) |
+| Discard working-tree changes (**destructive** → returns `rescue`) | POST | `discard` | `source`,`paths:[…]` | `files.write` + `write` (per-path) |
+| Create a commit from the index | POST | `commit` | `source`,`message`,`amend?` | `files.write` + `write` (root) |
+| Create / delete a branch (delete **destructive** → `rescue`) | POST | `branch` | `source`,`action:"create"\|"delete"`,`name`,`startPoint?`,`force?` | `files.write` + `write` (root) |
+| Switch branch (plain, refuses to clobber → 409) | POST | `checkout` | `source`,`ref` | `files.write` + `write` (root) |
+| **Undo** a `discard` / `branch` delete from its `rescue` carrier | POST | `restore` | `source`,`rescue:{kind:"stash"\|"branch",ref,name?}` | `files.write` + `write` (root) |
+| Fetch from the connected remote | POST | `fetch` | `source` | `files.write` + uri-policy **`exec`** + connected remote |
+| Pull (fetch + fast-forward-only merge) | POST | `pull` | `source` | `files.write` + `exec` + `write` + connected remote |
+| Push `HEAD` (no force) | POST | `push` | `source` | `files.write` + `exec` + connected remote |
 
 Notes:
 - `GET commit` (what a commit changed) and `POST commit` (create a commit) are **different**
@@ -111,7 +108,7 @@ Notes:
   only (never paths), and read-denied paths are excluded from the totals. Use it instead of
   fetching diffs to count lines.
 - The three capability tiers are gated **independently server-side**, regardless of this skill's
-  `requiredFeatures`: read routes need `drive.read`, write routes additionally need `drive.write`
+  `requiredFeatures`: read routes need `files.read`, write routes additionally need `files.write`
   (a read-only caller sees a **403** from any POST), and the remote routes additionally need
   uri-policy **`exec`** on the source root (`exec` is off by default → a **403** whose body
   carries a grant-exec affordance) **plus a connected remote** (409 `not_connected` /
@@ -120,7 +117,7 @@ Notes:
   return a typed `rescue` carrier. **Undo it through the governed `restore` route** — echo the
   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
+  branch. Same gate as any other write (`files.write` + `write` on the root — no `exec`, no new
   capability), and the restore itself snapshots first. Do **not** reach for raw-shell
   `git stash apply` / `git branch` instead: Plane C has no snapshot, so a failed recovery there is
   unrecoverable. Surface the `rescue` to the user either way — a carrier you never mention is a
@@ -136,7 +133,12 @@ The remote routes act as *you*: they read your own remote binding and resolve yo
 via the agent-core **git-connect** surface (feature `git.connect`) — the **Git Remotes** config
 card — with either a Personal Access Token or **GitHub OAuth**. Only `origin` over HTTPS is
 supported (SSH → 409). If a push/pull returns `not_connected` / `no_credential`, ask the user to
-connect the remote in that card first.
+connect the remote in that card first. On a **device folder** no binding is used: the device's
+owner fetches/pulls/pushes with their own git credentials on that machine; for anyone else the
+route answers 409 `git_remote_owner_only` — ask the owner to run it. Any git call on a device
+folder that answers 409 `git_device_unavailable` names why in `reason` (`devices_disabled`,
+`runtime_offline`, `broker_outdated`, `others_denied`, `device_not_ready` — the device's broker is not
+ready; its owner runs `neuralis device status` there, …) — report it; it is not an empty repo.
 
 ## Safe workflow
 
@@ -179,15 +181,15 @@ neuralis request GET @neuralis/brain-core/git/log    -f source=my-repo -f maxCou
 # 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.
-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"}'
+echo '{"source":"my-repo","paths":["src/app.ts","README.md"]}' | neuralis request POST @neuralis/brain-core/git/stage  --input -
+echo '{"source":"my-repo","message":"Fix null guard in loader"}' | neuralis request POST @neuralis/brain-core/git/commit --input -
 
 # 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.
-neuralis request POST @neuralis/brain-core/git/branch   --input - <<<'{"source":"my-repo","action":"create","name":"fix/loader"}'
+echo '{"source":"my-repo","action":"create","name":"fix/loader"}' | neuralis request POST @neuralis/brain-core/git/branch   --input -
 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).
@@ -202,5 +204,5 @@ 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
-neuralis request GET @neuralis/brain-core/git/status -f source=mono -f repo=packages/api
+neuralis request GET @neuralis/brain-core/git/status -f source=mono -f repo=api
 ```