@neuralis/brain-core 0.3.2 → 0.4.0

package/skills/git/SKILL.md

@@ -7,7 +7,7 @@ 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
 `files.read` / `files.write` + the source's uri-policy, with a **server-side snapshot
@@ -17,7 +17,7 @@ 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,19 +66,17 @@ 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 |
 |---|---|---|---|---|
@@ -91,7 +88,7 @@ unreadable; never write "no changes" into a report you cannot back.
 | 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 — **and the plane-liveness test: empty `repos` ⇒ every root-gated read fails soft** | GET | `repos` | `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) |
@@ -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
 ```

package/skills/manage-files/SKILL.md

@@ -12,7 +12,7 @@ The `fs_*` tools (`fs_read`, `fs_write`, etc.) remain the primary path for one-o
 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.
+on your own machine) — every route is one call line, with no script in between.
 
 ## Routes covered
 
@@ -22,8 +22,8 @@ on your own machine); `write` and `upload` go through their scripts.
 | Search vector index                         | POST | `search`   | `files.search` |
 | Read multiple files                         | POST | `read`     | `files.read` |
 | Raw (un-summarized) read                    | GET  | `raw`      | `files.read` |
-| Write — every verb (create / overwrite / edit / insert / lines / fields / move / copy / mkdir / revert / delete) | POST | `write` — `scripts/write.sh` | `files.write` |
-| Upload a payload (multipart/form-data)      | POST | `upload` — `scripts/upload.sh` | `files.write` |
+| Write — every verb (create / overwrite / edit / insert / lines / fields / move / copy / mkdir / revert / delete) | POST | `write`    | `files.write` |
+| Upload a payload (multipart/form-data)      | POST | `upload`   | `files.write` |
 | Approve a pending change                    | POST | `approve`  | `files.write` |
 | List pending changes (project-wide)         | GET  | `pending`  | `files.read` |
 
@@ -37,13 +37,12 @@ server-side **403** from `search` even though the other routes work.
 
 ## Bodies
 
-- `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.
+- `list` / `search` / `read` / `approve` / `write` take a JSON body on stdin (`echo '<json>' | neuralis request POST @neuralis/brain-core/<route> --input -`, the one form bash and PowerShell both parse; a `'` inside the text is written `\u0027` in the JSON); file content and other free text ride that body, never a `-f` argument (PowerShell strips the quotes inside an argument).
+- `/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` and the CLI exits 0, so branch on `ok`, never the status or the exit code. 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 — a missing file as `code:"not_found"`, and a device folder that cannot serve as `code:"source_unavailable"` or `"device_refused"` with a `reason` (`device_not_ready` adds `not_ready`: what the device's owner fixes there). 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 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 — `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.
+- `/upload` is **multipart/form-data**, NOT JSON — `--form file=@<local path>` and `--form agentId=<id>` are required, `--form uri=…` / `--form tags=a,b` optional; 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.
 
 
@@ -55,14 +54,14 @@ For a disposable pending record you created in your project, substitute its real
 
 ```bash
 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}'
+echo '{"action":"revert","id":"<scratch-record-id>","expectedFingerprint":"<64-hex-preview-fingerprint>","acknowledgeCurrentState":true}' | neuralis request POST @neuralis/brain-core/pending --input -
 ```
 
 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
-neuralis request POST @neuralis/brain-core/list --input - <<<'{"uri":"data://","recursive":true,"limit":100}'
+echo '{"uri":"data://","recursive":true,"limit":100}' | neuralis request POST @neuralis/brain-core/list --input -
 
 # Vector search across all sources (body key is `search_mode`, same as the fs_search tool)
 neuralis request POST @neuralis/brain-core/search -f search_mode=semantic -f query='telemetry pipeline' -F limit=10
@@ -74,15 +73,13 @@ neuralis request GET @neuralis/brain-core/pending -f status=pending_review -f li
 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.
-BODY_JSON='{"agentId":"<agent-id>","uri":"data://scratch/manage-files-probe.md","create":{"content":"# probe\n"}}' \
-  bash ${SKILL_DIR}/scripts/write.sh
+# `<agent-id>` is a placeholder; a real id makes this line write for real. Read `ok` in the answer.
+echo '{"agentId":"<agent-id>","uri":"data://scratch/manage-files-probe.md","create":{"content":"# probe\n"}}' | neuralis request POST @neuralis/brain-core/write --input -
 
 # Upload a payload (multipart, NOT JSON): file + agentId are required form fields.
 # The route never overwrites: a `URI` already in use lands the upload BESIDE the
 # existing file as `name (2).ext`, and the response `uri` is where it went — read
 # it, do not assume the path. `<agent-id>` is a placeholder; take a real id from the agents
 # list, and note that a real id makes this line write for real.
-FILE_PATH=/tmp/report.pdf AGENT_ID=<agent-id> URI='data://report.pdf' TAGS='reports,q3' \
-  bash ${SKILL_DIR}/scripts/upload.sh
+neuralis request POST @neuralis/brain-core/upload --form file=@/tmp/report.pdf --form agentId=<agent-id> --form uri=data://report.pdf --form tags=reports,q3
 ```

package/skills/manage-sources/SKILL.md

@@ -32,8 +32,10 @@ To just **survey** the configured sources and their freshness (read-only, the
    are opt-in: without `include_counts` the registry still lists the sources but
    `on_disk`/`indexed_count`/`unindexed` are usually omitted (survey mode is
    exactly when you want them).
-2. For any source in `sync_status: "error"`, report `last_error` — it is the
-   per-source diagnosis and needs no extra call. Do **not** reach for the log
+2. For any source that carries `last_error`, report it — it is the per-source
+   diagnosis and needs no extra call. `sync_status: "error"` means the last
+   SYNC failed; a `last_error` without it means the walk or count failed now
+   (no `on_disk`), not the sync. Do **not** reach for the log
    files with `fs_read`: `data://<package>/logs/**` is read-denied by uri policy
    for everyone below owner/admin, so on a member's behalf that call fails.
    Read them through `inspect-agent-core` (or, for the platform-wide view, the
@@ -61,18 +63,18 @@ server-side source rows rather than the index-count survey.)
 | List registered kinds                       | GET    | `sources/kinds`              | | `files.read`  |
 | Get a kind's config schema                  | GET    | `sources/kinds/<kind>/schema` | | `files.read`  |
 | Discoverable connectors (filesystem hints)  | GET    | `sources/discoverable`       | | `sources.mount` |
-| Browse a filesystem path before adding it   | GET    | `sources/browse`             | `path` | `sources.mount` |
+| Browse folders before adding one            | GET    | `sources/browse`             | `path`, `device?` | `sources.mount`; with `device` the device's owner (`device.own`) |
 | Create a new source                         | POST   | `sources`                    | body (below) | `sources.mount` |
 | Update an existing source                   | PATCH  | `sources`                    | body (below) | `sources.mount` |
 | Delete a source                             | DELETE | `sources/<slug>[?purge=1]`   | | `sources.mount` |
 | Enable / disable a source                   | POST   | `sources/enabled`            | `source`, `enabled` (`true`\|`false`\|`"auto"`) | `sources.mount` |
-| Trigger sync (202 + queue job snapshot)     | POST   | `sources/sync`               | `source`, `agentId?` | `sources.sync`  |
+| Trigger sync (202 + queue job snapshot)     | POST   | `sources/sync`               | `source`, `agentId?`, `confirmEmpty?` | `sources.sync`  |
 | Cancel an in-flight sync                    | POST   | `sources/cancel`             | `source?` | `sources.sync`  |
 | Job status                                  | GET    | `sources/sync-status`        | `source?` | `sources.sync`  |
 | Forget sync state (next tick re-walks; deletes nothing) | POST | `sources/reset` | `source` | `sources.sync` |
 | Rescan changes (full re-walk now; unchanged files keep their vectors; 202 + job) | POST | `sources/reindex` | `source`, `agentId?` | `sources.sync` |
 | Clean a file / folder / source index (estimate first) | POST | `sources/purge` | body (below) | `sources.mount` + `sources.sync` |
-| Catch up embedding debt; FORCE=1 re-embeds (estimate first) | POST | `sources/reindex` + `embeddingOnly` or `force` — run `bash ${SKILL_DIR}/scripts/reembed.sh` | env | `sources.sync` |
+| Catch up embedding debt, or re-embed with `force` (estimate first) | POST | `sources/reindex` + `embeddingOnly` or `force` (lines under §Re-embed) | `source`, `folder?`/`uri?`, `estimate?` | `sources.sync` |
 
 > **`update` takes no `<slug>`.** PATCH targets the bare `sources` path; the
 > source to patch is the body `source` field (the handler ignores the path).
@@ -99,19 +101,28 @@ feature server-side, beyond the `files.read` floor — a caller holding only
 - **`sources.mount`** — create, update, delete, enable/disable, browse and the
   discoverable list. Browsing and the
   discoverable list are the steps that PRECEDE attaching, and they enumerate the
-  host: you may browse exactly what you would be allowed to attach.
+  host: you may browse exactly what you would be allowed to attach. On a native
+  install (no container) a folder on this server may root only in the project's own
+  folder — browsable with its parents on the way down to it — or a privileged
+  zone below; any other folder answers `403 native_local_root_outside_project`
+  and is attached as a folder on the user's own paired device instead.
 - **`sources.privileged`** — browsing the filesystem root or any
   protected host zone (the App Zone, the Neuralis tree), the same zones whose
   ATTACH needs it. A protected directory is also omitted from the listing of a
   parent you may browse, so an absent entry is not proof it does not exist.
-- **`sources.sync`** — sync, cancel, reset, reindex, `reembed.sh`, sync-status.
+- **`sources.sync`** — sync, cancel, reset, reindex, re-embed, sync-status.
 
 The index purge requires both `sources.mount` and `sources.sync`, source-scope management authority and current READ visibility.
 
 Create/update/delete/enable additionally enforce `canAccessScope(.., 'write')`
 on the target source's scope, and create validates the kind's scope rules.
+Send a folder's `root` alone: the server derives its `hostRoot` (the same
+folder on the machine) and stores both, so the source opens whether the server runs
+in Docker or natively. A `hostRoot` that contradicts that derivation answers
+`400 source_root_pair_mismatch`; one nothing derives is accepted only from a
+`sources.privileged` caller, and audited.
 
-### Privileged and host-plane sources
+### Privileged sources and device folders
 
 One escalation sits above `sources.mount`, not granted below the `admin` tier (`admin` holds
 it through its enumerated default grant, `owner` through the `'*'` wildcard; grantable to any
@@ -122,17 +133,33 @@ custom role):
   filesystem (`/`). Containment is checked in both directions on canonical paths, so a
   sub-path or an ancestor of a protected zone is caught too.
 
-A source on the HOST plane (a connector kind of `host` / `host-*`, on a paired device
-rather than in the container) has one rule: **only that device's owner, holding
-`device.own`, attaches or edits it** — at every root, and no role feature replaces it.
-Anyone else gets 403, whatever they hold.
+A folder is one kind, `host`, on one of two places its stored config names: without
+`connection.config.device` it is a folder on this server; with one it is a folder on that
+paired device (the DEVICE plane), reached through the device's broker. A device folder has one
+rule: **only that device's owner, holding `device.own`, attaches or edits it** — at every
+root, and no role feature replaces it. Anyone else gets 403, whatever they hold. It is
+attached at user scope unless you send `"scope":"project"` (never `agent`), its `root` is an
+absolute path on that device, and the place never changes after the attach — to move a
+folder between this server and a device, delete it and attach it again.
 
-A host source is also bounded by the device's own allowlist, which the platform cannot
+A device folder is also bounded by the device's own allowlist, which the platform cannot
 widen: even a permissive source policy only reaches paths the device's owner granted. If a
-host read or write fails while the source policy allows it, report the allowlist as the
-limit — the owner widens it with `neuralis device grant`, not a policy edit.
-
-Attaching a host source is not the same act as granting host command execution: reading
+device read or write fails while the source policy allows it, report the allowlist as the
+limit — the owner widens it with `neuralis device grant`, not a policy edit. The git panel
+and `/git/*` answer for a folder on this server only.
+
+To find the folder on your OWN device, browse it: `sources/browse -f device=dev_… -f path=`
+(empty path) lists the folders that device allows this server, with `-f path=/abs/dir` one
+level below. Anyone but the owner gets `403 Only the device's owner may browse it.`, an
+unknown id too. A `200` with `state` other than `ok` and no entries is the device's answer:
+`ceiling_denied` (not allowed yet), `device_offline`, `broker_outdated` (an older CLI there).
+For a folder it does not allow yet, ask the device to record it for its owner — the grant
+stays on that machine (tray → Allow a folder…, or `neuralis device grant <dir>`):
+`neuralis request POST @neuralis/agent-core/devices/dev_…/requests -f path=/abs/dir -f list=read`
+(`list=write` for a writable folder) → `{recorded:true}`, or `{recorded:false,
+reason:"inside_ceiling"}` when it is already allowed.
+
+Attaching a device folder is not the same act as granting host command execution: reading
 files through `fs_*` and running commands there are separate grants.
 
 The same split holds for every exec-capable source (a virtual desktop, any
@@ -153,13 +180,15 @@ server-side sync queue. Poll `sources/sync-status` (`-f source=<slug>`) until
 with `source` stops one source's job mid-run; without it, EVERY job on
 sources you can see.
 
-An embedding job can end `paused`: report `result.embedding.pausedReason` and partial counts. Resume is a new explicitly authorized `reembed.sh` request, using durable point debt; no saved job ID or automatic paid restart.
+An embedding job can end `paused`: report `result.embedding.pausedReason` and partial counts. Resume is a new explicitly authorized `embeddingOnly` request, using durable point debt; no saved job ID or automatic paid restart.
 
 `sources/sync` refuses in two ways worth telling apart. **404** — the slug does not
 resolve for you (it does not exist, or it is outside your scope; the two answer
 alike on purpose). **400** — the source exists but carries no `sync` block, so
 there is nothing to trigger: add one with an update first. Neither is a server
-fault, so neither should be retried unchanged.
+fault, so neither should be retried unchanged. A job that fails `root_empty`
+(or `root_unreachable`) removed nothing; `confirmEmpty:true` is for a folder the
+user confirmed is empty (the `sync` skill).
 
 ## Fields, bodies and script env
 
@@ -171,20 +200,20 @@ fault, so neither should be retried unchanged.
 - `?purge=1` on delete enqueues an async vector purge. Delete then returns
   **202 + `{purgeJob, …}`** (vs 200 normally). Any delete resolves the source's
   open notifications (its unread failure warnings) for you and its creator.
-- `reembed.sh` takes `SOURCE` (required) and `FOLDER` / `URI` — its scope (one of them, inside `SOURCE`; neither = the whole
-  source). `CONFIRM=1` starts debt catchup; without it the script only ESTIMATES. `FORCE=1` selects a forced connector re-embed instead.
-  `SCOPE=platform` (catch-up only, whole source, needs `platform.vector.maintain`) catches up EVERY
+- The re-embed body takes `source` (required) and `folder` / `uri` — its scope (one of them, inside `source`; neither = the whole
+  source). `embeddingOnly:true` catches up debt, `force:true` selects a forced connector re-embed instead, and `estimate:true` on
+  either only ESTIMATES. `scope:"platform"` (catch-up only, whole source, needs `platform.vector.maintain`) catches up EVERY
   writer's points of the source, not only yours — the way back after an operator dense clear.
 - Create and update bodies (`--input -`) MUST include
   `source` + `permissions`; create additionally requires `connection.kind`. May also
-  carry `recognizesPackages` (boolean; absent or `null` = unchanged, so a listing
+  carry `packageFolders` (an array of folders; absent or `null` = unchanged, so a listing
   round-tripped through jq never 400s on it) — see **Package sources** below. A `sync`
   block may carry an `include` allowlist alongside `exclude`/`trigger`
   (`"sync": {"exclude": [], "include": ["skills/**"], "trigger": "manual"}`): non-empty
   means only matching files sync, and an exclude still wins. A `sync.media` object
   (`{"images":true,"pdf":true,"video":false,"audio":false}`, absent key = that default)
   picks which binary kinds a MULTIMODAL active model embeds; a text-only model embeds
-  none, and `lastSyncResult.mediaSkipped` counts what was left out; `lastSyncResult.binarySkipped` is the last count of binary files not indexed as text (a binary extension, or a NUL in the first `brainSyncBinarySniffChars` characters); `lastSyncResult.embeddingDegraded` lists the reasons (`quota`, `credentials`, `rate_limit`, …) when the embedder was unavailable during the pass — the files are indexed and text-searchable, their semantic embedding is owed and caught up by `reembed.sh` once the embedder answers. The `invalid` reason is a local PNG structural check before provider work; invalid input preserves existing indexed and recovery payloads. **`include` bounds the
+  none, and `lastSyncResult.mediaSkipped` counts what was left out; `lastSyncResult.binarySkipped` is the last count of binary files not indexed as text (a binary extension, or a NUL in the first `brainSyncBinarySniffChars` characters); `lastSyncResult.embeddingDegraded` lists the reasons (`quota`, `credentials`, `rate_limit`, …) when the embedder was unavailable during the pass — the files are indexed and text-searchable, their semantic embedding is owed and caught up by an `embeddingOnly` re-embed once the embedder answers. The `invalid` reason is a local PNG structural check before provider work; invalid input preserves existing indexed and recovery payloads. **`include` bounds the
   INDEX, never the read.** What an agent can `fs_read` is set by the source ROOT and by
   `permissions.paths[]` — so narrowing a wide source with `include` alone leaves every
   file under that root readable. Re-root it, or add a path deny, or both.
@@ -221,25 +250,35 @@ theirs.
 
 ```bash
 # Disposable source from the lifecycle walkthrough only; estimate first.
-neuralis request POST @neuralis/brain-core/sources/purge --input - <<<'{"source":"scratch-demo","mode":"estimate","obsoleteOnly":true,"selector":{"kind":"source"}}'
+echo '{"source":"scratch-demo","mode":"estimate","obsoleteOnly":true,"selector":{"kind":"source"}}' | neuralis request POST @neuralis/brain-core/sources/purge --input -
 # Apply only after reviewing the same selection’s counts.
-neuralis request POST @neuralis/brain-core/sources/purge --input - <<<'{"source":"scratch-demo","mode":"apply","obsoleteOnly":true,"selector":{"kind":"source"}}'
+echo '{"source":"scratch-demo","mode":"apply","obsoleteOnly":true,"selector":{"kind":"source"}}' | neuralis request POST @neuralis/brain-core/sources/purge --input -
 # A canonical folder selection, still estimate-only:
-neuralis request POST @neuralis/brain-core/sources/purge --input - <<<'{"source":"scratch-demo","mode":"estimate","obsoleteOnly":false,"selector":{"kind":"folder","uri":"scratch-demo://docs"}}'
+echo '{"source":"scratch-demo","mode":"estimate","obsoleteOnly":false,"selector":{"kind":"folder","uri":"scratch-demo://docs"}}' | neuralis request POST @neuralis/brain-core/sources/purge --input -
 ```
 
 ## Re-embed (a file, a folder, a source)
 
-"Rescan changes" reuses unchanged indexed files, but rebuilds re-included recovery-only content. `reembed.sh` catches up missing/stale indexed embeddings, including brain-only and unchanged legacy records. Its read-only estimate returns `estimate_kind:scope_upper_bound`: authorized indexed scope counts are an upper bound, not a provider quote; no provider call or job starts. Show the estimate before `CONFIRM=1` (202 + embedding job; poll `sources/sync-status`). Disabled embedding refuses: each `GET sources` row's `embedding_enabled` is the live platform switch, and while it is `false` `reembed.sh` answers 409 `embedding_disabled`; without an active dense generation the estimate refuses and a submitted job pauses as `metadata_only`, never activating a model. `FORCE=1` instead rereads and re-embeds the connector scope; its estimate includes `{documents,estimate:{tokens,relStdErr,usd,seconds}}` (`usd:null` for an unpriced model). A single file you may not read answers
+"Rescan changes" reuses unchanged indexed files, but rebuilds re-included recovery-only content. `embeddingOnly:true` catches up missing/stale indexed embeddings, including brain-only and unchanged legacy records. Its read-only estimate returns `estimate_kind:scope_upper_bound`: authorized indexed scope counts are an upper bound, not a provider quote; no provider call or job starts. Show the estimate before you send the same body without `estimate` (202 + embedding job; poll `sources/sync-status`). Disabled embedding refuses: each `GET sources` row's `embedding_enabled` is the live platform switch, and while it is `false` the re-embed answers 409 `embedding_disabled`; without an active dense generation the estimate refuses and a submitted job pauses as `metadata_only`, never activating a model. `force:true` instead rereads and re-embeds the connector scope; its estimate includes `{documents,estimate:{tokens,relStdErr,usd,seconds}}` (`usd:null` for an unpriced model). A single file you may not read answers
 `404`, exactly like a missing one. Switching the platform to a DIFFERENT model is not this:
 that is the owner's rebuild in the admin Vector section.
 
-## Package sources (`recognizesPackages`)
+```bash
+# Read-only estimates first (no job, no provider call): debt catch-up, then a forced re-embed of one folder.
+neuralis request POST @neuralis/brain-core/sources/reindex -f source=scratch-demo -F embeddingOnly=true -F estimate=true
+neuralis request POST @neuralis/brain-core/sources/reindex -f source=scratch-demo -f folder=scratch-demo://docs -F force=true -F estimate=true
+# Starts a paid embedding job (202) — the same body without `estimate`.
+neuralis request POST @neuralis/brain-core/sources/reindex -f source=scratch-demo -F embeddingOnly=true
+```
+
+## Package sources (`packageFolders`)
 
-Create and update accept `recognizesPackages` (boolean) in the body. It does
-NOT switch markdown discovery on — a synced source's markdown becomes source-package
-contributions (skill / instruction / rule / agent / docs) either way; the flag lets the host
-load the source as a runtime package source (create-package
+Create and update accept `packageFolders` in the body: the folders of the source, relative
+to its root, whose packages the host loads (`""` = the whole source, `"tools/pkgs"` = that
+folder; no `..`, no absolute path; `[]` clears them). It does NOT switch markdown discovery
+on — a synced source's markdown becomes source-package contributions (skill / instruction /
+rule / agent / docs) either way; the folders let the host load packages from them as runtime
+package sources (create-package
 `references/connectors-and-uri-policies.md` §Declare source instances owns the details). Two
 server-side gates apply regardless of what you send (`src/routes/sources.ts`):
 
@@ -249,14 +288,16 @@ server-side gates apply regardless of what you send (`src/routes/sources.ts`):
   member 20 · viewer 30, lower = stronger), or who holds a `'*'` wildcard
   feature grant. A CUSTOM role that declares `priority: 2` passes exactly like
   the built-in `admin`; a role NAMED `admin` is not what is checked. Anything
-  weaker gets `403 Setting recognizesPackages requires an owner/admin-effective
+  weaker gets `403 Setting packageFolders requires an owner/admin-effective
   role.` — quote that string verbatim when you report it. It names the required
   STRENGTH, not a role you have to be called. This is the SECOND gate on the
   route: `sources.mount` is checked first for the whole PATCH, so a caller without
   it never reaches this message and sees `403 Updating sources requires
   sources.mount.` instead. Read the two strings as different answers — a missing
   feature grant versus insufficient role strength.
-- **Local-kind only** — setting it on a non-`local` connection returns `400`.
+- **`host` kind only** — setting it on another kind returns `400`. On a folder on a paired
+  device the packages are read over its link, never copied here; their skill scripts run on
+  that device. While it is offline its packages read "Not available".
 
 A package delivered through a **user/agent-scoped** source is advertised only to that
 scope (a different run identity sees nothing — correct-by-design, not a load failure).
@@ -266,11 +307,11 @@ scope (a different run identity sees nothing — correct-by-design, not a load f
 # and already holds markdown, so this edits a REAL source. `repo` is a stand-in:
 # substitute a slug from the sources list. The effect is live — every matching .md under
 # it starts being advertised as a package contribution on the next sync — and it
-# is reversible only by resending the same body with `recognizesPackages:false`.
+# is reversible only by resending the same body with `packageFolders:[]`.
 # Needs sources.mount, then priority <= 2 (the admin anchor) or a '*' grant, and a
-# local-kind source. The body carries the source's CURRENT permissions back —
+# folder source. The body carries the source's CURRENT permissions back —
 # PATCH replaces them:
-neuralis request GET @neuralis/brain-core/sources --jq '.[] | select(.source=="repo") | {source, permissions, recognizesPackages:true}' | neuralis request PATCH @neuralis/brain-core/sources --input -
+neuralis request GET @neuralis/brain-core/sources --jq '.[] | select(.source=="repo") | {source, permissions, packageFolders:[""]}' | neuralis request PATCH @neuralis/brain-core/sources --input -
 ```
 
 ## `description` field
@@ -299,18 +340,17 @@ neuralis request GET @neuralis/brain-core/sources
 # a TOP-LEVEL ARRAY → filter with .[] (NOT .sources[]):
 # Each row IS the source config: the slug lives in `.source` (there is no `.slug` key).
 neuralis request GET @neuralis/brain-core/sources --jq '.[] | {source, enabled, kind: .connection.kind, orphan}'
-neuralis request GET @neuralis/brain-core/sources --jq '.[] | select(.connection.kind=="local")'
+neuralis request GET @neuralis/brain-core/sources --jq '.[] | select(.connection.kind=="host" and (.connection.config.device|not))'
 # The kind is the registry KIND, not a connector id or a UI label. Enumerate them
-# (today: brain, host, local, webtop); an unregistered value is 404
+# (today: brain, host, webtop); an unregistered value is 404
 # `Unknown kind "<x>"` for EVERY caller, so it is never a permission problem.
-# The on-disk connector's id is `local-disk` but its kind is `local` — send `local`.
 neuralis request GET @neuralis/brain-core/sources/kinds --jq '.kinds[].kind'
-neuralis request GET @neuralis/brain-core/sources/kinds/local/schema
+neuralis request GET @neuralis/brain-core/sources/kinds/host/schema
 neuralis request POST @neuralis/brain-core/sources/sync -f source=data      # needs sources.sync
 neuralis request GET @neuralis/brain-core/sources/sync-status -f source=data
 # `"auto"` = live only while the source's runtime runs; a boolean is typed with -F
 neuralis request POST @neuralis/brain-core/sources/enabled -f source=data -F enabled=true
-neuralis request GET @neuralis/brain-core/sources/browse -f path=/tmp   # needs sources.mount
+neuralis request GET @neuralis/brain-core/sources/browse -f path="$DATA_ROOT"   # needs sources.mount; DATA_ROOT = the data source's container= path
 ```
 
 ### Lifecycle walkthrough — create → update → delete
@@ -328,7 +368,7 @@ the throwaway.
 ```bash
 # 1. Create (needs sources.mount). source + connection.kind + permissions.default.* required.
 #    The root does not have to exist yet — create records the coordinate, sync walks it.
-neuralis request POST @neuralis/brain-core/sources --input - <<<'{"source":"scratch-demo","connection":{"kind":"local","config":{"root":"/tmp/scratch-demo"}},"permissions":{"default":{"read":true,"write":true,"exec":false}}}'
+echo '{"source":"scratch-demo","connection":{"kind":"host","config":{"root":"/tmp/scratch-demo"}},"permissions":{"default":{"read":true,"write":true,"exec":false}}}' | neuralis request POST @neuralis/brain-core/sources --input -
 # 2. Update — NO SLUG; the body `source` field is the key (needs sources.mount).
 #    Sets the description shown in the agent <runtime_stack>. `permissions` is
 #    REPLACED, so read the live object back and resend it unchanged, editing only
@@ -391,5 +431,5 @@ neuralis request GET @neuralis/brain-core/health/scan
    duplicate groups (from `/health/scan`); unindexed/stale per source (from `fs_list`).
 3. A changed embedding model is never mixed in: the index keeps embedding with the model
    it was built with until the owner rebuilds it from the admin Vector section — no reset.
-4. If issues found, suggest specific remediation: source sync for stale data, `reembed.sh` for
+4. If issues found, suggest specific remediation: source sync for stale data, a `force` re-embed for
    files whose vectors look wrong, `POST /health/gc` to gc / repair-orphans / deduplicate.

package/skills/manage-uri-policy/SKILL.md

@@ -66,22 +66,25 @@ undone.
 # 0. Read the policy you are about to change, so you can prove you restored it.
 neuralis request GET @neuralis/brain-core/policies/uri/data
 # 1. Add the rule (LIVE — members lose read on this subtree immediately).
-neuralis request POST @neuralis/brain-core/policies/uri --input - <<<'{"source":"data","addPaths":[{"pattern":"data://agent-core/admin/**","permissions":{"read":false},"roles":["member"]}]}'
+echo '{"source":"data","addPaths":[{"pattern":"data://agent-core/admin/**","permissions":{"read":false},"roles":["member"]}]}' | neuralis request POST @neuralis/brain-core/policies/uri --input -
 # 2. Take it back — same source, same pattern, byte for byte.
-neuralis request POST @neuralis/brain-core/policies/uri --input - <<<'{"source":"data","removePatterns":["data://agent-core/admin/**"]}'
+echo '{"source":"data","removePatterns":["data://agent-core/admin/**"]}' | neuralis request POST @neuralis/brain-core/policies/uri --input -
 ```
 
 To keep a rule, run step 1 and stop; step 2 exists so the example is reversible
 rather than a permanent edit to a live source's access policy.
 
 Body: `source` (slug, required) plus either `addPaths` — rules of `{pattern,
-permissions, roles?}`, where `pattern` takes `**` wildcards, `permissions` maps
-`read`/`write`/`exec` to `false` (deny) or `true` (allow) and `roles` scopes the
-rule — or `removePatterns` (the patterns to take back).
+permissions, roles?, priority?, override?}`, where `pattern` takes `**` wildcards, `permissions` maps
+`read`/`write`/`exec` to `false` (deny) or `true` (allow), `roles` scopes the
+rule to named project roles (each must exist in the project, else 400) and
+`priority: 2` to callers whose role priority is 2 or stronger — admin and owner,
+lower = stronger (an integer 1..99, only on a grant row: `override: true` with every
+listed bit `true`); present fields all apply — or `removePatterns` (the patterns to take back).
 
 `exec` decides whether a shell may START in that directory — on an exec-capable
 source (a virtual desktop or any other one whose connector runs commands) as
-well as in the container. A caller also needs that plane's entry feature; the
+well as on the app's own machine. A caller also needs that plane's entry feature; the
 policy row alone does not grant one, and the entry alone does not grant the row.
 So a source whose owner reports "I hold the feature and the shell is still
 refused" usually needs an `exec` ALLOW row for their role or agent here.

package/skills/sync/SKILL.md

@@ -14,7 +14,7 @@ Trigger a delta sync for the brain-core filesystem.
 1. Use `fs_list` with no `uri` first to identify configured sources, scopes, current sync status, and recent errors.
 2. Call the brain-core source sync route for the intended source. The route answers 202 + a queue job snapshot — the sync runs in the background. Explicit sync requires `sources.sync`; source create/update/delete uses `sources.mount`; file writes use `files.write`.
 3. Poll `GET /sources/sync-status?source=<slug>` until the job finishes, then report the job `result` counts: `filesAdded`, `filesUpdated`, `filesRemoved`, `filesSkipped`, `filesMoved`, `chunksRemoved`, `chunksEmbedded` and `chunksSkipped` plus `embeddingDegraded` (safe, deduplicated embedding stop reasons). Payload indexing can succeed with missing/stale embeddings; report that debt separately. Read the two flags before interpreting completion. `cancelled: true` is not a failure, but the run stopped early: the counts are partial and a re-run converges. `truncated: true` means the walk stopped at `filesScanCap`, so files past the cap were never examined and no deletion or move was inferred — call that a partial pass, never a completed sync.
-4. If any errors occur, list them clearly with the affected source, scope, and file path.
+4. If any errors occur, list them clearly with the affected source, scope, and file path. Two job errors are fixed codes and removed nothing: `root_unreachable` (the source root cannot be reached — unmounted, renamed, device offline; fix the mount, then sync again) and `root_empty` (the root answers but holds no file while the index still holds some). Re-send `confirmEmpty:true` with the sync only after the user confirms the folder really is empty — that one pass removes its files from the index.
 5. Distinguish live connector data, indexed payload and embedding freshness. Provider outage or disabled embedding preserves metadata/full-text indexing; semantic results may be old, or the response may fall back to filter search. Ordinary sync completion does not settle all embedding debt. Use `manage-sources` explicit debt catchup; terminal `paused` carries `result.embedding.pausedReason`, and Resume creates a new authorized job from durable debt.
 
 ## What a sync will and will not index