@neuralis/brain-core 0.3.1 → 0.3.2

package/skills/git/SKILL.md

@@ -2,7 +2,7 @@
 name: git
 description: "Operate git on a git-backed source through governed routes: inspect status, diff, history, and outgoing changes; stage, discard, commit, branch, switch, fetch, pull, or push. Use for repository work; choose governed git by default, raw CLI for allowed local inspection, and GitHub tools for remote collaboration."
 allowed-tools: execute
-requiredFeatures: [drive.read]
+requiredFeatures: [files.read]
 ---
 
 # Git
@@ -10,7 +10,7 @@ requiredFeatures: [drive.read]
 Drive git on a **git-backed source** (any `local`-kind source that is a git checkout)
 through brain-core's governed git routes. These are the **same routes the Git Control
 panel drives**, so an agent gets exactly the rights a human member has: gated by
-`drive.read` / `drive.write` + the source's uri-policy, with a **server-side snapshot
+`files.read` / `files.write` + the source's uri-policy, with a **server-side snapshot
 before every destructive op** and **credential-safe remotes** (the push/pull token is
 resolved server-side and never touches the agent shell).
 
@@ -83,25 +83,25 @@ unreadable; never write "no changes" into a report you cannot back.
 
 | Action | Method | Route | Key params | Gate |
 |---|---|---|---|---|
-| Whole-repo change-set + branch + ahead/behind | GET | `status` | `source`,`repo?` | `drive.read` + uri-policy `read` (root) |
-| Local branch list | GET | `branch` | `source`,`repo?` | `drive.read` + `read` (root) |
-| Per-file unified diff | GET | `diff` | `source`,`path` **(required)**; optionally one of `staged=1` \| `commit=<sha>` \| `base=<sha>&head=<sha>` (omit all three for the unstaged working-tree diff) | `drive.read` + `read` (per-path) |
-| Blob content at a rev | GET | `show` | `source`,`path`,`rev=index\|<sha>` | `drive.read` + `read` (per-path) |
-| Commit-DAG page (+ `outgoing[]`) | GET | `log` | `source`,`maxCount?`,`skip?`,`ref?` | `drive.read` + `read` (root) |
-| Per-commit `+/-` totals for a log page | GET | `log-stats` | `source`,`maxCount?`,`skip?`,`ref?` | `drive.read` + `read` (root) |
-| Files a commit changed | GET | `commit` | `source`,`sha=<sha>` | `drive.read` + `read` (root) |
-| Committed-but-not-pushed files | GET | `outgoing` | `source` | `drive.read` + `read` (root) |
-| In-source repo picker — **and the plane-liveness test: empty `repos` ⇒ every root-gated read fails soft** | GET | `repos` | `source` | `drive.read` + `read` (root) |
-| Stage whole files or a hunk | POST | `stage` | `source`,`paths:[…]` **or** `hunk:"<patch>"` | `drive.write` + `write` (per-path) |
-| Unstage whole files or a hunk | POST | `unstage` | `source`,`paths:[…]` **or** `hunk` | `drive.write` + `write` (per-path) |
-| Discard working-tree changes (**destructive** → returns `rescue`) | POST | `discard` | `source`,`paths:[…]` | `drive.write` + `write` (per-path) |
-| Create a commit from the index | POST | `commit` | `source`,`message`,`amend?` | `drive.write` + `write` (root) |
-| Create / delete a branch (delete **destructive** → `rescue`) | POST | `branch` | `source`,`action:"create"\|"delete"`,`name`,`startPoint?`,`force?` | `drive.write` + `write` (root) |
-| Switch branch (plain, refuses to clobber → 409) | POST | `checkout` | `source`,`ref` | `drive.write` + `write` (root) |
-| **Undo** a `discard` / `branch` delete from its `rescue` carrier | POST | `restore` | `source`,`rescue:{kind:"stash"\|"branch",ref,name?}` | `drive.write` + `write` (root) |
-| Fetch from the connected remote | POST | `fetch` | `source` | `drive.write` + uri-policy **`exec`** + connected remote |
-| Pull (fetch + fast-forward-only merge) | POST | `pull` | `source` | `drive.write` + `exec` + `write` + connected remote |
-| Push `HEAD` (no force) | POST | `push` | `source` | `drive.write` + `exec` + connected remote |
+| Whole-repo change-set + branch + ahead/behind | GET | `status` | `source`,`repo?` | `files.read` + uri-policy `read` (root) |
+| Local branch list | GET | `branch` | `source`,`repo?` | `files.read` + `read` (root) |
+| Per-file unified diff | GET | `diff` | `source`,`path` **(required)**; optionally one of `staged=1` \| `commit=<sha>` \| `base=<sha>&head=<sha>` (omit all three for the unstaged working-tree diff) | `files.read` + `read` (per-path) |
+| Blob content at a rev | GET | `show` | `source`,`path`,`rev=index\|<sha>` | `files.read` + `read` (per-path) |
+| Commit-DAG page (+ `outgoing[]`) | GET | `log` | `source`,`maxCount?`,`skip?`,`ref?` | `files.read` + `read` (root) |
+| Per-commit `+/-` totals for a log page | GET | `log-stats` | `source`,`maxCount?`,`skip?`,`ref?` | `files.read` + `read` (root) |
+| Files a commit changed | GET | `commit` | `source`,`sha=<sha>` | `files.read` + `read` (root) |
+| Committed-but-not-pushed files | GET | `outgoing` | `source` | `files.read` + `read` (root) |
+| In-source repo picker — **and the plane-liveness test: empty `repos` ⇒ every root-gated read fails soft** | GET | `repos` | `source` | `files.read` + `read` (root) |
+| Stage whole files or a hunk | POST | `stage` | `source`,`paths:[…]` **or** `hunk:"<patch>"` | `files.write` + `write` (per-path) |
+| Unstage whole files or a hunk | POST | `unstage` | `source`,`paths:[…]` **or** `hunk` | `files.write` + `write` (per-path) |
+| Discard working-tree changes (**destructive** → returns `rescue`) | POST | `discard` | `source`,`paths:[…]` | `files.write` + `write` (per-path) |
+| Create a commit from the index | POST | `commit` | `source`,`message`,`amend?` | `files.write` + `write` (root) |
+| Create / delete a branch (delete **destructive** → `rescue`) | POST | `branch` | `source`,`action:"create"\|"delete"`,`name`,`startPoint?`,`force?` | `files.write` + `write` (root) |
+| Switch branch (plain, refuses to clobber → 409) | POST | `checkout` | `source`,`ref` | `files.write` + `write` (root) |
+| **Undo** a `discard` / `branch` delete from its `rescue` carrier | POST | `restore` | `source`,`rescue:{kind:"stash"\|"branch",ref,name?}` | `files.write` + `write` (root) |
+| Fetch from the connected remote | POST | `fetch` | `source` | `files.write` + uri-policy **`exec`** + connected remote |
+| Pull (fetch + fast-forward-only merge) | POST | `pull` | `source` | `files.write` + `exec` + `write` + connected remote |
+| Push `HEAD` (no force) | POST | `push` | `source` | `files.write` + `exec` + connected remote |
 
 Notes:
 - `GET commit` (what a commit changed) and `POST commit` (create a commit) are **different**
@@ -111,7 +111,7 @@ Notes:
   only (never paths), and read-denied paths are excluded from the totals. Use it instead of
   fetching diffs to count lines.
 - The three capability tiers are gated **independently server-side**, regardless of this skill's
-  `requiredFeatures`: read routes need `drive.read`, write routes additionally need `drive.write`
+  `requiredFeatures`: read routes need `files.read`, write routes additionally need `files.write`
   (a read-only caller sees a **403** from any POST), and the remote routes additionally need
   uri-policy **`exec`** on the source root (`exec` is off by default → a **403** whose body
   carries a grant-exec affordance) **plus a connected remote** (409 `not_connected` /
@@ -120,7 +120,7 @@ Notes:
   return a typed `rescue` carrier. **Undo it through the governed `restore` route** — echo the
   carrier straight back: `POST restore` with `{"source":"…","rescue":{"kind":"stash","ref":"<sha>"}}`
   for discarded content, `{"kind":"branch","ref":"<anchor>","name":"<branch>"}` for a deleted
-  branch. Same gate as any other write (`drive.write` + `write` on the root — no `exec`, no new
+  branch. Same gate as any other write (`files.write` + `write` on the root — no `exec`, no new
   capability), and the restore itself snapshots first. Do **not** reach for raw-shell
   `git stash apply` / `git branch` instead: Plane C has no snapshot, so a failed recovery there is
   unrecoverable. Surface the `rescue` to the user either way — a carrier you never mention is a

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
@@ -18,21 +18,21 @@ on your own machine); `write` and `upload` go through their scripts.
 
 | 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` — `scripts/write.sh` | `files.write` |
+| Upload a payload (multipart/form-data)      | POST | `upload` — `scripts/upload.sh` | `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

package/skills/manage-files/scripts/upload.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 # POST /upload REQUIRES multipart/form-data (NOT a JSON body): the handler reads the
 # form fields file (the binary/text payload), agentId, uri (optional), tags (optional,
 # comma-split). projectId is taken from the session ticket — passing a different one
-# is a 403. Requires the caller to hold the `drive.write` feature. agentId here is read
+# is a 403. Requires the caller to hold the `files.write` feature. agentId here is read
 # from the form field.
 FILE_PATH="${FILE_PATH:?FILE_PATH is required (local path of the payload to upload)}"
 AGENT_ID="${AGENT_ID:?AGENT_ID is required (form field; the destination agent)}"

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`,
@@ -50,29 +50,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 a filesystem path before adding it   | GET    | `sources/browse`             | `path` | `sources.mount` |
+| 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`  |
+| 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` |
 
 > **`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,49 +87,50 @@ 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
+- **`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, `reembed.sh`, 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.
 
 ### Privileged and host-plane sources
 
-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.
+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 host source 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
 files through `fs_*` and running commands there are separate grants.
@@ -199,7 +200,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
@@ -251,9 +252,9 @@ server-side gates apply regardless of what you send (`src/routes/sources.ts`):
   weaker gets `403 Setting recognizesPackages 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`.
 
@@ -266,7 +267,7 @@ scope (a different run identity sees nothing — correct-by-design, not a load f
 # 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
+# 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 —
 # 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 -
@@ -305,11 +306,11 @@ neuralis request GET @neuralis/brain-core/sources --jq '.[] | select(.connection
 # 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 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=/tmp   # needs sources.mount
 ```
 
 ### Lifecycle walkthrough — create → update → delete
@@ -325,10 +326,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).
+# 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 +345,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 +363,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

package/skills/manage-sources/scripts/reembed.sh

@@ -1,6 +1,6 @@
 #!/usr/bin/env bash
 set -euo pipefail
-# Requires drive.sync (403 otherwise). FORCE=1 re-embeds with the ACTIVE model; otherwise catches up durable embedding debt — a
+# Requires sources.sync (403 otherwise). FORCE=1 re-embeds with the ACTIVE model; otherwise catches up durable embedding debt — a
 # file (URI), a folder's indexed files (FOLDER) or, with neither, the whole
 # source — even when nothing changed. Default = the ESTIMATE only (changes
 # nothing); CONFIRM=1 starts it (202 + job). Only files you may read count.

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

@@ -1,7 +1,7 @@
 ---
-requiredFeatures: [drive.policy]
+requiredFeatures: [sources.policy]
 name: manage-uri-policy
-description: "Inspect and patch role-aware read, write, and execute URI policy for any source. Use when a legitimate path is denied or access must be narrowed; patching needs the drive.policy feature, and prefer the smallest explicit exception over broad defaults."
+description: "Inspect and patch role-aware read, write, and execute URI policy for any source. Use when a legitimate path is denied or access must be narrowed; patching needs the sources.policy feature, and prefer the smallest explicit exception over broad defaults."
 allowed-tools: execute
 ---
 
@@ -100,24 +100,24 @@ package's seed.
 
 - **Two arms, both keyed on FEATURES — there is no role-name check on this
   route.** Reading (`GET policies/uri/...`) is
-  the module feature `drive.read`, which every built-in role holds down to
+  the module feature `files.read`, which every built-in role holds down to
   `viewer`. Patching (`POST policies/uri`) escalates in-handler to
-  `drive.policy` and otherwise returns
-  `403 Missing feature: drive.policy (URI policy editing)`. `drive.policy` has
+  `sources.policy` and otherwise returns
+  `403 Missing feature: sources.policy (URI policy editing)`. `sources.policy` has
   no grant below the `admin` tier (enumerated for `admin`, `'*'` for `owner`)
   and is grantable to any custom role — so a custom role can hold it and a
   built-in one can lack it.
 - **Being able to SEE this skill is not the route gate.** Its
-  `requiredFeatures: [drive.policy]` frontmatter hides the bundle from anyone
+  `requiredFeatures: [sources.policy]` frontmatter hides the bundle from anyone
   without that feature; that is the ADVERTISEMENT layer. The session ticket
   carries your real identity to the route, and there is no synthetic owner
   upgrade anywhere.
 - **Patching SOMEONE ELSE'S user- or agent-scoped source additionally needs scope
   WRITE.** The POST runs `canAccessScope(..., 'write')` on the owning scope, which
   passes unconditionally for a project-scoped source and for your OWN user/agent
-  scope — so on the common path `drive.policy` is the whole answer. Only a
-  CROSS-scope patch consults `filesystem.modifyScoped`; an
-  `observeScoped`-but-not-`modifyScoped` holder gets
+  scope — so on the common path `sources.policy` is the whole answer. Only a
+  CROSS-scope patch consults `files.writeOthers`; an
+  `files.readOthers`-but-not-`files.writeOthers` holder gets
   `403 Forbidden for source scope` there.
 - **Manifest baselines are not edited by this skill.** Package
   manifests ship `permissions.uriPolicies` as the read-only baseline;

package/skills/organize/SKILL.md

@@ -1,5 +1,5 @@
 ---
-requiredFeatures: [drive.write]
+requiredFeatures: [files.write]
 name: organize
 description: "Analyze a workspace for duplicate, misplaced, stale, or poorly indexed material and design a safer information architecture. Use when asked to clean up or reorganize; inspect references and propose or preview moves before mutating shared files."
 allowed-tools: fs_search fs_write fs_list fs_read

package/skills/sync/SKILL.md

@@ -1,5 +1,5 @@
 ---
-requiredFeatures: [drive.sync]
+requiredFeatures: [sources.sync]
 name: sync
 description: "Run and verify brain-core delta synchronization for configured sources. Use when live connector content and the vector index may differ, files are stale or unindexed, or changes must become searchable; inspect completion and index state instead of trusting dispatch alone."
 allowed-tools: fs_list fs_read execute
@@ -12,7 +12,7 @@ Trigger a delta sync for the brain-core filesystem.
 ## Steps
 
 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 `drive.sync`; source create/update/delete uses `drive.mount`; file writes use `drive.write`.
+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.
 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.

package/tools/fs_list.json

@@ -73,7 +73,7 @@
     "transport": "embedded",
     "requires": {
       "features": [
-        "drive.read"
+        "files.read"
       ]
     },
     "defaults": {

package/tools/fs_read.json

@@ -70,7 +70,7 @@
     "transport": "embedded",
     "requires": {
       "features": [
-        "drive.read"
+        "files.read"
       ]
     },
     "defaults": {},

package/tools/fs_search.json

@@ -80,7 +80,7 @@
     "transport": "embedded",
     "requires": {
       "features": [
-        "drive.search"
+        "files.search"
       ]
     },
     "defaults": {

package/tools/fs_write.json

@@ -226,7 +226,7 @@
     "transport": "embedded",
     "requires": {
       "features": [
-        "drive.write"
+        "files.write"
       ]
     },
     "askOnKeys": [

package/workflows/sources-digest.json

@@ -27,5 +27,5 @@
   ],
   "defaultStateMode": "fresh",
   "delivery": { "mode": "none" },
-  "requires": { "features": ["drive.search"] }
+  "requires": { "features": ["files.search"] }
 }

package/docs/drive-overview.md

@@ -1,59 +0,0 @@
----
-id: drive-overview
-title: Drive Overview
-description: URI schemes, tool capabilities, and sync reality for the virtual filesystem
----
-
-## URI Schemes
-
-| Scheme | Connector kind | Storage | Indexed | Example |
-|--------|---------|---------|---------|---------|
-| `brain://` | `brain` (builtin) | Qdrant vector DB (inline) | always | `brain://docs/note.md` |
-| `data://` | `local` (builtin) | Project data zone on disk + Qdrant | if configured & synced | `data://code/app.ts` |
-| `<slug>://` | `local` (user) | Any additional `local` mount, under its own slug (lower-case letters, digits and hyphens only — never a dot) + Qdrant | if configured & synced | `archive://old/x.md` |
-| `packages://` | `local` (builtin) | `_packages/` on disk + Qdrant | if configured & synced | `packages://my-pkg/tools/tool.json` |
-| `app://` | `local` (builtin, privileged mount) | Platform app zone (`~/.neuralis/app/`) | rarely synced | `app://config/sources/...` |
-| `neuralis://` | `local` (user, via `pnpm neuralis:mount add … --neuralis`) | The deployment's own `neuralis/` folder, live from the host (`scripts/`, `skills/`, `src/`, config — and `.env`) + Qdrant | if synced | `neuralis://scripts/mount.mts` |
-| `neuralis-skills://` | `local` (user, same overlay rooted at `<root>/skills`) | Just the shipped operator skills — the narrower default, offered first | if synced | `neuralis-skills://neuralis-operations/SKILL.md` |
-| `machine://` | `webtop` (`@neuralis/machine-core`) | Webtop sandbox | n/a | `machine://desktop/clipboard.txt` |
-| `<slug>://` | `host` (`@neuralis/agent-core`) | Operator's machine, OUTSIDE the container, via the operator-provisioned host broker | if configured & synced | `host-dev://repos/app/src/main.ts` |
-
-`os://<key>` is **not** a callable scheme — it is a decorative label
-rendered inside the system prompt's `<runtime_stack>` block for
-`NEURALIS_MOUNT_<KEY>` mounts. To address files inside a mount, use the
-`local`-kind source slug that was attached to that mount (e.g.
-`neuralis://` after `pnpm neuralis:mount add … --neuralis`).
-
-## Tool Quick Reference
-
-| Tool | Purpose | Key Detail |
-|------|---------|------------|
-| `fs_search` | Find by meaning, keyword, metadata, or live grep | `query` = semantic / grep pattern / filter content-keyword (tokenized over indexed text in `filter` mode), `glob` = filename keyword, `search_mode: "filter"` = metadata only, `search_mode: "grep"` + `folder_uri` = ripgrep over the live connector (works even for unsynced subpaths; results stay scoped to `folder_uri`; uri-policy `read`-gated). |
-| `fs_read` | Read content (batch max 10) | URIs or UUIDs. `line_start`/`line_end` for large files. |
-| `fs_list` | Workspace overview + folder browse (unified) | Omit / empty / `/` → full root (`all://`) with source registry. Pass a real URI to scope. `recursive:false` = direct children only (fast). `include=folders\|files\|all`, `summary_chars>0` attaches previews (use on small scoped folders — identity, rules). `include_metadata:true` surfaces id/category/tags/timestamps in the markdown. `only_indexed:true` skips the live merge. |
-| `fs_write` | Create, edit or restructure — one tool, one call | The VERB is a KEY: `create` (never overwrites — a taken name lands beside as `name-2.ext`), `overwrite`, `edit[]` (targeted `old_string`→`new_string`, in order), `insert` (by line), `lines` (replace a range), `fields` (category/tags/metadata/pinned), `move`, `copy` (file or folder; the destination may be in another source), `mkdir` (not on `brain://`), `revert` (1-level undo), `delete` (a file, or a whole folder recursively). Content verbs compose in ONE write; structural verbs stand alone. Agent-runtime deletes require approval. |
-
-## Indexed vs Live (connector-first contract)
-
-- **`brain://`** — Always indexed (content lives inline in Qdrant).
-- **`data://`, `packages://`, `neuralis://`, `app://` and any other `local`-kind slug** — Backed by a live `local`-kind connector; indexed mirror follows once sync has run.
-  - `fs_read` / `fs_list` go connector-first, so they work even when the index is cold or Qdrant is unreachable.
-  - Indexed searches require a warm index; payload and full-text indexing work without embeddings. Check `effective_mode`, `embedding_degraded` and row `embedding_status`: semantic requests can fall back to indexed text, and retained vectors can lag behind current content.
-  - `fs_search` in `grep` mode bypasses the index entirely and greps the connector directly (ripgrep / git grep / grep). It is uri-policy `read`-gated — only paths the caller holds `read` policy on are grepped (a `read:false` subtree is silently absent; a fully-denied `folder_uri` → 403). It needs no `execute`/shell/`exec.unconfined` access: `drive.search` + `read` policy is enough, making it the uri-policy-gated counterpart to `execute`+grep.
-- **`machine://`** — Backed by `machine-core`'s `webtop` connector against a running webtop session; `'auto'` enabled-state resolves through the host-injected probe.
-- **`host`-kind slugs** — Backed by `agent-core`'s host connector, resolving on the operator's machine outside the container. It exists only where the operator provisioned the broker; attaching one needs `drive.mount.host` **and** `drive.mount.privileged`. Addressed by its own slug like any other source.
-- **`FilePresence`** per node: `brain` (vector-only), `synced` (index + connector agree), `unindexed` (on-disk but not indexed yet), `stale_indexed` (index has it, connector doesn't).
-- **Unmounted dirs** — Not addressable as a Neuralis URI; the agent can still touch them through the `execute` tool's shell pipeline when the runtime grants exec, but `fs_*` will reject the URI.
-
-## Sources, Scope, and Access
-
-- Source slugs are URI schemes. Scoped clones use distinct schemes such as `local-alice://` or `machine-agent1://`; never assume every local source is named `data://`.
-- Built-in connector kinds come from package manifests: `local` is live disk, `brain` is Qdrant-backed internal memory, and other packages can contribute more `type: "source"` connectors through the same registry.
-- Source scopes are `project`, `user`, or `agent`. Project sources are visible to project members with the right feature grants; user/agent sources require ownership or scoped observation/modification features.
-- Feature gates: `drive.read` covers read/list/raw/events, the vector-health READS (stats and scan) and source metadata reads, `drive.search` covers indexed and grep search, `drive.write` covers create/modify/mkdir/copy/approve/upload, the mutating Pending Changes verbs and the vector-health `gc` sweep (`POST health/gc` — POST-only, `dryRun` defaults to false), `drive.mount` covers source create/update/delete/enable **and the two host-enumeration reads that precede an attach** (`sources/browse`, `sources/discoverable`), and `drive.sync` gates explicit sync plus cancel, reset, reindex and sync-status. Three features escalate above those and none is granted below the admin tier: `drive.policy` edits a source's URI policy, and `drive.mount.privileged` together with `drive.mount.host` are both required to attach a source on a high-blast-radius or host-plane root (and `drive.mount.privileged` alone gates BROWSING the filesystem root or a high-blast-radius zone). Reaching another identity's user- or agent-scoped source additionally needs `filesystem.observeScoped` (read) or `filesystem.modifyScoped` (write). The package declares two more features that gate affordances rather than paths: `packages.author` (the Packages panel authoring launcher) and `packages.registry` (the marketplace skill) — neither widens filesystem access.
-
-## Recovery and Health
-
-- Every write snapshots `version.baseline`; `fs_write {revert:true}` is the one-level recovery path.
-- A certified embedding generation locks its model and dimension. Existing collections without that proof retain unknown vectors as metadata indexes. Typed provider unavailability leaves payload indexing operational; invalid lock/schema records still fail closed. Changing an active generation requires an explicit rebuild rather than guessing vector compatibility.
-- Tool usage/accounting belongs under `_meta.neuralis.usage`; model-visible results stay in `content` and `structuredContent`.