@neuralis/brain-core 0.3.1 → 0.4.0

package/skills/manage-files/SKILL.md

@@ -1,5 +1,5 @@
 ---
-requiredFeatures: [drive.write]
+requiredFeatures: [files.write]
 name: manage-files
 description: "Perform bulk or route-level filesystem operations—list, search, read, raw, write (every verb), upload, and review approval—when fs_* calls are insufficient or an approval flow is involved. Use source URIs and preserve policy/scope; prefer direct fs_* for ordinary small file work."
 allowed-tools: execute
@@ -12,38 +12,37 @@ 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
 
 | Action | Method | Path (`@neuralis/brain-core/…`) | Feature gate |
 |---|---|---|---|
-| List files / folders at a URI               | POST | `list`     | `drive.read` |
-| Search vector index                         | POST | `search`   | `drive.search` |
-| Read multiple files                         | POST | `read`     | `drive.read` |
-| Raw (un-summarized) read                    | GET  | `raw`      | `drive.read` |
-| Write — every verb (create / overwrite / edit / insert / lines / fields / move / copy / mkdir / revert / delete) | POST | `write` — `scripts/write.sh` | `drive.write` |
-| Upload a payload (multipart/form-data)      | POST | `upload` — `scripts/upload.sh` | `drive.write` |
-| Approve a pending change                    | POST | `approve`  | `drive.write` |
-| List pending changes (project-wide)         | GET  | `pending`  | `drive.read` |
+| List files / folders at a URI               | POST | `list`     | `files.read` |
+| 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`    | `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` |
 
 Per-route feature gates are enforced server-side by the RouteDispatcher against the
 caller's real `grantedFeatures`, independently of this skill's `requiredFeatures`
-frontmatter — `/list`, `/read`, `/raw` and `GET /pending` need `drive.read`; `/search` needs
-`drive.search`; `/write`, `/upload`, `/approve` and the mutating `/pending`
-verbs (`revert`, `discard`, `dismiss`, `discard-orphans`) need `drive.write`. A caller who holds
-`drive.write` (enough to see and activate this skill) but NOT `drive.search` gets a
+frontmatter — `/list`, `/read`, `/raw` and `GET /pending` need `files.read`; `/search` needs
+`files.search`; `/write`, `/upload`, `/approve` and the mutating `/pending`
+verbs (`revert`, `discard`, `dismiss`, `discard-orphans`) need `files.write`. A caller who holds
+`files.write` (enough to see and activate this skill) but NOT `files.search` gets a
 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

@@ -1,5 +1,5 @@
 ---
-requiredFeatures: [drive.read]
+requiredFeatures: [files.read]
 name: manage-sources
 description: "Manage the full source lifecycle: survey freshness/index health, inspect kinds/schema, create/update/enable/disable/delete, browse, sync/cancel/reset/reindex, re-embed or clean a file/folder/source index, and diagnose vectors. Use when a source is stale, missing, misconfigured, offline, or needs lifecycle changes."
 allowed-tools: execute fs_list fs_read fs_search
@@ -24,7 +24,7 @@ Useful for:
 ## Read / survey mode (sources + freshness)
 
 To just **survey** the configured sources and their freshness (read-only, the
-`drive.read` floor — no mutation), use the `fs_*` tools rather than the routes:
+`files.read` floor — no mutation), use the `fs_*` tools rather than the routes:
 
 1. Call `fs_list` with `include_counts: true` (no `uri` — root registry) to
    enumerate sources with `on_disk`, `indexed_count`, `unindexed`,
@@ -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
@@ -50,29 +52,29 @@ server-side source rows rather than the index-count survey.)
 
 ## Routes covered
 
-`drive.read` is the skill's floor; mutating + sync-lifecycle routes escalate
+`files.read` is the skill's floor; mutating + sync-lifecycle routes escalate
 **in-handler** to a stronger feature and 403 an under-privileged caller (see
 **Feature gates** below). The `Feature` column is the gate actually enforced.
 
 | Action | Method | Path (`@neuralis/brain-core/…`) | Fields | Feature |
 |---|---|---|---|---|
-| List configured sources                     | GET    | `sources`                    | `scope?`, `observed?` | `drive.read`  |
-| Get one source's config                     | GET    | `sources/<slug>`             | | `drive.read`  |
-| List registered kinds                       | GET    | `sources/kinds`              | | `drive.read`  |
-| Get a kind's config schema                  | GET    | `sources/kinds/<kind>/schema` | | `drive.read`  |
-| Discoverable connectors (filesystem hints)  | GET    | `sources/discoverable`       | | `drive.mount` |
-| Browse a filesystem path before adding it   | GET    | `sources/browse`             | `path` | `drive.mount` |
-| Create a new source                         | POST   | `sources`                    | body (below) | `drive.mount` |
-| Update an existing source                   | PATCH  | `sources`                    | body (below) | `drive.mount` |
-| Delete a source                             | DELETE | `sources/<slug>[?purge=1]`   | | `drive.mount` |
-| Enable / disable a source                   | POST   | `sources/enabled`            | `source`, `enabled` (`true`\|`false`\|`"auto"`) | `drive.mount` |
-| Trigger sync (202 + queue job snapshot)     | POST   | `sources/sync`               | `source`, `agentId?` | `drive.sync`  |
-| Cancel an in-flight sync                    | POST   | `sources/cancel`             | `source?` | `drive.sync`  |
-| Job status                                  | GET    | `sources/sync-status`        | `source?` | `drive.sync`  |
-| Forget sync state (next tick re-walks; deletes nothing) | POST | `sources/reset` | `source` | `drive.sync` |
-| Rescan changes (full re-walk now; unchanged files keep their vectors; 202 + job) | POST | `sources/reindex` | `source`, `agentId?` | `drive.sync` |
-| Clean a file / folder / source index (estimate first) | POST | `sources/purge` | body (below) | `drive.mount` + `drive.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 | `drive.sync` |
+| List configured sources                     | GET    | `sources`                    | `scope?`, `observed?` | `files.read`  |
+| Get one source's config                     | GET    | `sources/<slug>`             | | `files.read`  |
+| 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 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?`, `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, 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).
@@ -87,51 +89,77 @@ array** of source rows (NOT `{ sources: [...] }`). Pipe `jq '.[]'`, never
 `jq '.sources[]'` (that errors `Cannot index array with string "sources"`). Each
 element carries `slug`, `enabled`, `connection.kind`, `scope`, plus the enrichment
 fields above. `connection.config` is `{}` unless you could attach the source or
-read its root, and `sync.lastSyncResult.error` is a fixed text without `drive.sync`. `GET sources/<slug>` returns a single object, not an array.
+read its root, and `sync.lastSyncResult.error` is a fixed text without `sources.sync`. `GET sources/<slug>` returns a single object, not an array.
 
 ## Feature gates
 
-The skill declares `drive.read`, which covers the source-config READ routes.
+The skill declares `files.read`, which covers the source-config READ routes.
 Everything that mutates, syncs, or ENUMERATES THE HOST enforces a **stronger**
-feature server-side, beyond the `drive.read` floor — a caller holding only
-`drive.read` gets a `403`:
+feature server-side, beyond the `files.read` floor — a caller holding only
+`files.read` gets a `403`:
 
-- **`drive.mount`** — create, update, delete, enable/disable, browse and the
+- **`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.
-- **`drive.mount.privileged`** — browsing the filesystem root or any
+  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.
-- **`drive.sync`** — sync, cancel, reset, reindex, `reembed.sh`, sync-status.
+- **`sources.sync`** — sync, cancel, reset, reindex, re-embed, sync-status.
 
-The index purge requires both `drive.mount` and `drive.sync`, source-scope management authority and current READ visibility.
+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
 
-Two escalations sit above `drive.mount`, neither granted below the `admin` tier (`admin` holds
-them through its enumerated default grants, `owner` through the `'*'` wildcard; both are
-grantable to any custom role):
+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
+custom role):
 
-- **`drive.mount.privileged`** — attaching (or seeing) a source rooted in, over, or at a
+- **`sources.privileged`** — attaching (or seeing) a source rooted in, over, or at a
   high-blast-radius zone: the platform App Zone, the Neuralis source tree, or the whole
   filesystem (`/`). Containment is checked in both directions on canonical paths, so a
   sub-path or an ancestor of a protected zone is caught too.
-- **`drive.mount.host`** — attaching or editing any source on the HOST plane (a connector
-  kind of `host` / `host-*`, resolving on the operator's machine rather than in the
-  container). **Both features are required together for a host source, at every root** —
-  there is no unprivileged host root, so `/home/me/notes` is gated exactly like `/`.
 
-A host source is also bounded by an operator-owned ceiling the platform cannot widen: even
-a permissive source policy only reaches paths the operator listed. If a host read or write
-fails while the source policy allows it, report the ceiling as the limit — it is an
-operator change, not a policy edit.
-
-Attaching a host source is not the same act as granting host command execution: reading
+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 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
+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
@@ -152,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
 
@@ -170,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.
@@ -199,7 +229,7 @@ to change. Every update example below does exactly that.
 
 **`syncExcludes` is a PREFERENCE; the uri policy is the security half. Do not
 confuse them.** A source's `sync.exclude` list is yours to edit — it is noise
-control (do not index `node_modules`), per source, managed through `drive.mount`.
+control (do not index `node_modules`), per source, managed through `sources.mount`.
 It is NOT how you keep a secret out of the index. The immutable `floor:true`
 uri-policy rows are: a path whose floor denies `read` cannot be read by any
 caller AND is never newly embedded, because *what cannot be read cannot be
@@ -220,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`):
 
@@ -248,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: `drive.mount` is checked first for the whole PATCH, so a caller without
+  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
-  drive.mount.` instead. Read the two strings as different answers — a missing
+  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).
@@ -265,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`.
-# Needs drive.mount, then priority <= 2 (the admin anchor) or a '*' grant, and a
-# local-kind source. The body carries the source's CURRENT permissions back —
+# is reversible only by resending the same body with `packageFolders:[]`.
+# Needs sources.mount, then priority <= 2 (the admin anchor) or a '*' grant, and a
+# 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
@@ -298,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 POST @neuralis/brain-core/sources/sync -f source=data      # needs drive.sync
+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 drive.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
@@ -325,10 +366,10 @@ the `delete` on the last line would destroy the project's real source instead of
 the throwaway.
 
 ```bash
-# 1. Create (needs drive.mount). source + connection.kind + permissions.default.* required.
+# 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}}}'
-# 2. Update — NO SLUG; the body `source` field is the key (needs drive.mount).
+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
 #    the field you meant to change — a hand-written {"default":…} body here would
@@ -344,8 +385,8 @@ neuralis request DELETE '@neuralis/brain-core/sources/scratch-demo?purge=1'
 ## Vector health (index diagnostics)
 
 The health route is SPLIT into a count-cheap path and a scan path (pattern `health/*`, feature
-`drive.read`) — call it with `neuralis request`. **The two
-read paths run on `drive.read`; the `gc` path does not** — it additionally requires `drive.write`
+`files.read`) — call it with `neuralis request`. **The two
+read paths run on `files.read`; the `gc` path does not** — it additionally requires `files.write`
 and is POST-only (see below). That covers its actions: `gc`, `repair-orphans` and `repair-pending`
 mutate, and `deduplicate` is read-only but rides the same gate — its rows enumerate other agents'
 `data://` paths.
@@ -362,14 +403,14 @@ mutate, and `deduplicate` is read-only but rides the same gate — its rows enum
 - **`POST …/brain-core/health/gc`** with `{action}` (`gc` / `repair-orphans` / `repair-pending` / `deduplicate`) —
   `gc`, `repair-orphans` and `repair-pending` MUTATE — run those only after a scan confirms a finding; `deduplicate`
   removes nothing (it reports groups) but is gated identically. **POST only** — a GET answers
-  `405 Method GET not allowed`. It needs **`drive.write`** on top of the route's `drive.read`; a
-  caller without it gets `403 {"error":"Missing feature: drive.write (vector health repair)"}`.
+  `405 Method GET not allowed`. It needs **`files.write`** on top of the route's `files.read`; a
+  caller without it gets `403 {"error":"Missing feature: files.write (vector health repair)"}`.
   That is a capability the caller lacks, not a broken call: report the finding and say that the
-  sweep needs `drive.write` (manager tier and up), rather than retrying.
+  sweep needs `files.write` (manager tier and up), rather than retrying.
   `dryRun` DEFAULTS TO FALSE — pass `{"dryRun": true}` first when you want a preview. `repair-pending` processes one visible batch (default 50) and returns `scannedVisible`, `orphaned`, `attempted`, `discarded`, `refused`, `failed`, safe reason counts, `nextCursor`, `complete` and `partial`. Pass the returned `nextCursor` as `cursor` in the next POST only after checking the result; pause on partial/failure, retry explicitly, and restart on `restartRequired`. Each page reconstructs the complete projected inventory; the batch bounds mutations, not scan work. A terminal acknowledgement is not a newly discarded record.
 - **`GET …/brain-core/health/hot-uris`** → the files the index rewrote most in the last hour:
   `{windowMinutes, threshold, uris: [{uri, writes, points, lastWriteAt, hot}]}` (`writes` = file
-  writes, `points` = index points incl. chunks). Same `drive.write` gate; already filtered to the
+  writes, `points` = index points incl. chunks). Same `files.write` gate; already filtered to the
   files you may read. Use it when indexing load is high or `deletedCount` keeps growing.
 
 `unindexed` / `stale_indexed` are NOT in the health route at all — get those per-source from
@@ -390,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.