@neuralis/brain-core 0.3.2 → 0.4.1

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. `code:"vector_store_unavailable"` (per file on `/read`, `ok:false` on `/write`, a **503** elsewhere) means the index is not available yet: a new file on a folder source still lands, a `brain://` file, an edit, move or delete waits — nothing was changed; retry later. 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

@@ -13,8 +13,8 @@ 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.
+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. A job that stays `pending` while other calls answer `vector_store_unavailable` is held for the vector store: it runs by itself when the store is back — stop polling and report it as waiting, never as failed.
+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

package/dist/src/connectors/LocalDiskConnector.d.ts

@@ -1,171 +0,0 @@
-import type { ConnectorPort, ConnectorCapability, ConnectorListItem, ConnectorReadResult, ConnectorReadRawOpts, ConnectorReadRawResult, ConnectorStatResult, ConnectorMoveResult, ConnectorWriteResult, ConnectorDeltaRequest, ConnectorDeltaResult, ConnectorCountOpts, ConnectorWalkOpts, ScanContentOpts, ScanContentResult, ConnectorFactoryContext, ConnectorChangeEvent, ConnectorEventSubscription, ConnectorSubscribeOpts, ConnectorConnectionProbe } from '@neuralis/package-system/contracts';
-import { ConnectorRootAccessError } from '@neuralis/package-system/contracts';
-import { type OsMount } from '@neuralis/package-system/paths';
-/**
- * Concrete root-access error thrown by the local-disk connector. Routes +
- * services catch the abstract base (`ConnectorRootAccessError`), not this
- * class specifically — so every future connector that touches a real FS
- * surface can share the same structured-warning pathway.
- */
-export declare class LocalDiskRootAccessError extends ConnectorRootAccessError {
-    constructor(code: 'ROOT_MISSING' | 'ROOT_PERMISSION_DENIED', rootPath: string, uri: string, cause?: unknown);
-}
-/**
- * The capability set the local on-disk connector implements. This MUST stay
- * byte-equal to the `local` connector's `capabilities` array in
- * `package.json#neuralis.connectors` — `SourceLoader.instantiateConnector`
- * fails closed (`ConnectorCapabilityMismatch`) on any divergence, and for a
- * first-party connector `wiring.ts` now re-throws that (boot-fatal) instead of
- * silently degrading the kind. `localDiskCapabilities.test.ts` is the
- * derive-and-verify drift guard that catches a mismatch at TEST time.
- */
-export declare const LOCAL_DISK_CAPABILITIES: readonly ConnectorCapability[];
-/**
- * Structured failure thrown by `LocalDiskConnector.resolveOsUri` when the
- * connector is running inside a Docker container but no host-pair root has
- * been configured. Returning a container-internal path here would corrupt
- * vector payloads + filesystem-node `os_uri` fields with paths that do not
- * exist on the host. Callers (sync runner, the write engine) catch this
- * and either skip the upsert or persist `os_uri: undefined` instead.
- */
-export declare class OsUriUnresolvableError extends Error {
-    readonly code: 'os_uri_host_pair_missing';
-    readonly source: string;
-    readonly uri: string;
-    constructor(params: {
-        source: string;
-        uri: string;
-        root?: string;
-    });
-}
-/**
- * Connector for local filesystem access — URI-native.
- *
- * Contributed by brain-core via `neuralis.connectors[]` manifest entry
- * `{ kind: 'local', configSchema: { root, hostRoot? } }`. The package loader
- * instantiates it via `createLocalDiskConnector(ctx)` for each source binding.
- */
-export declare class LocalDiskConnector implements ConnectorPort {
-    #private;
-    readonly kind = "local";
-    readonly source: string;
-    readonly portVersion: 4;
-    constructor(root: string, source: string, hostRoot?: string, isDocker?: boolean);
-    capabilities(): ReadonlySet<ConnectorCapability>;
-    /** Expose the resolved root path for diagnostics / wiring logs. */
-    get root(): string;
-    probeRoot(): Promise<{
-        rootPath: string;
-        exists: boolean;
-        readable: boolean;
-        error?: string;
-    }>;
-    /**
-     * Connector-owned liveness — whether the backing host directory is reachable.
-     * Wraps {@link probeRoot} but maps to the fixed `SourceLiveReason` enum and
-     * DISCARDS the raw `rootPath`/`error` (those carry the absolute host-mount
-     * path — leaking them to a member via the tone-title is a path-disclosure
-     * regression). UI-tone + `<runtime_stack>` signal only; never gates access.
-     */
-    probeConnection(): Promise<ConnectorConnectionProbe>;
-    list(uri: string): Promise<ConnectorListItem[]>;
-    /**
-     * Existence + metadata, on the SAME guarded path as `read` and without
-     * transferring a byte of content. `null` = the path resolved but nothing is
-     * there (`ENOENT`, from either the guard's per-segment walk or the `lstat`);
-     * every other failure THROWS exactly as `read` would — a traversal/symlink
-     * refusal, an EACCES, a root-access error — so the caller's existing
-     * "gone vs. could-not-ask" split keeps working unchanged.
-     *
-     * `lstat`, never `stat`: `resolveAndGuard` REFUSES a symlink rather than
-     * resolving through it, so following one here would answer for a target the
-     * read path would never have served.
-     */
-    stat(uri: string): Promise<ConnectorStatResult | null>;
-    /**
-     * The sync media lane's PDF read — NOT a kernel `ConnectorPort` member (only
-     * a connector that holds the file on its own disk can render it; the lane
-     * treats a connector without it as "unavailable"). The raw bytes' sha256
-     * (the point's `content_hash`) and pages `first..last` rendered by the ONE
-     * renderer — none when the hash equals `unlessHash`, so an unchanged PDF is
-     * never re-rendered. `null` when `pdftoppm` is not installed; the same
-     * containment and read cap as `read`.
-     */
-    renderPdfPages(uri: string, opts: {
-        first: number;
-        last: number;
-        unlessHash?: string;
-    }): Promise<{
-        contentHash: string;
-        pages: Array<{
-            page: number;
-            png: Buffer;
-        }>;
-    } | null>;
-    /**
-     * The byte-exact read. Same guarded resolver as `read`; the cap is
-     * `min(opts.maxBytes, brainMaxReadFileMb)`, checked on the OPENED
-     * descriptor's size before any byte is buffered, and the read itself pulls
-     * at most that size+1 bytes — a file that grew after the size check is
-     * refused (over the cap: the too-large refusal), never cut.
-     */
-    readRaw(uri: string, opts: ConnectorReadRawOpts): Promise<ConnectorReadRawResult>;
-    read(uri: string): Promise<ConnectorReadResult>;
-    write(uri: string, content: string | Uint8Array): Promise<ConnectorWriteResult>;
-    delete(uri: string): Promise<void>;
-    move(fromUri: string, toUri: string): Promise<ConnectorMoveResult>;
-    mkdir(uri: string): Promise<void>;
-    rmdir(uri: string): Promise<void>;
-    /**
-     * OS-level change events under `rootUri`, fed by the shared FsWatchHub
-     * (D6: ONE watcher substrate). Catches EVERY background change — shell
-     * writes, host edits, git checkouts, external programs — not just app
-     * writes. URI mapping happens here (the hub only knows absolute paths);
-     * exclude filtering and debounce are the SUBSCRIBER's job. An `overflow`
-     * event means "event delivery can no longer be trusted — full reconcile".
-     */
-    subscribeEvents(rootUri: string, listener: (event: ConnectorChangeEvent) => void, opts?: ConnectorSubscribeOpts): ConnectorEventSubscription;
-    scanDelta(request: ConnectorDeltaRequest): Promise<ConnectorDeltaResult>;
-    resolveOsUri(uri: string): string;
-    peekCount(rootUri: string, opts?: ConnectorCountOpts): number | undefined;
-    walk(rootUri: string, opts?: ConnectorWalkOpts): Promise<ConnectorListItem[]>;
-    walkWithStatus(rootUri: string, opts?: ConnectorWalkOpts): Promise<{
-        items: ConnectorListItem[];
-        complete: boolean;
-        truncated: boolean;
-    }>;
-    count(rootUri: string, opts?: ConnectorCountOpts): Promise<number>;
-    scanContent(rootUri: string, query: string, opts?: ScanContentOpts): Promise<ScanContentResult[]>;
-}
-/**
- * Factory: builds a LocalDiskConnector instance for a specific source binding.
- *
- * Resolves `config.root` against the current projectRoot
- * (`resolveLocalRoot`): a relative path joins onto `ctx.projectRoot`, an
- * absolute one is the container path as written.
- */
-export declare function createLocalDiskConnector(ctx: ConnectorFactoryContext): ConnectorPort;
-/**
- * Derive a host-side root for `resolvedRoot` from the os-mount table. Returns
- * the host path for the *longest* matching mount whose `containerPath` is the
- * root itself or a path-boundary-correct ancestor (`/mounts/repo` matches
- * `/mounts/repo` and `/mounts/repo/sub`, but NOT `/mounts/repo2`). Mounts
- * without a `hostPath` (no `NEURALIS_MOUNT_HOST_*` pair) are skipped. Returns
- * `undefined` when nothing matches, so the caller falls through to the
- * fail-loud `OsUriUnresolvableError` path in Docker.
- */
-export declare function deriveHostRootFromOsMounts(resolvedRoot: string, mounts: OsMount[]): string | undefined;
-/**
- * Canonical container-root resolution for a local source's configured root.
- * Exported so the brain-core API can hand agent-core's shell uri-policy gate
- * the SAME resolved roots the connector itself mounts — the two branches
- * (relative under the project root, absolute as written) are never re-typed.
- */
-export declare function resolveLocalRoot(params: {
-    configured: string;
-    projectRoot: string;
-    source: string;
-}): {
-    resolvedRoot: string;
-};
-//# sourceMappingURL=LocalDiskConnector.d.ts.map