@neuralis/brain-core 0.2.1 → 0.3.0

package/skills/manage-sources/SKILL.md

@@ -8,10 +8,13 @@ allowed-tools: execute fs_list fs_read fs_search
 # Sources Management Skill
 
 The `connect-business-data` skill owns common source listing, health checks, and
-creation through `connect`; this skill remains the full route/script lifecycle,
+creation through `connect`; this skill remains the full route lifecycle,
 especially policy-preserving updates, sync, enablement, reset and deletion.
 
-Wraps `/api/packages/@neuralis/brain-core/sources/*`. Useful for:
+Covers `@neuralis/brain-core/sources/*`, called with `neuralis request` (the
+session ticket inside an activated skill, `neuralis login` on your own machine;
+a non-2xx prints the route's body and `HTTP <code>` on stderr and exits 1).
+Useful for:
 
 - Bootstrapping a project's sources from a script (`for slug in …`).
 - Bulk-cancel + re-sync after a connector outage.
@@ -21,8 +24,7 @@ Wraps `/api/packages/@neuralis/brain-core/sources/*`. 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 route
-scripts:
+`drive.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`,
@@ -42,7 +44,7 @@ scripts:
    semantic/filter search needs the source to be indexed. For unsynced content,
    recommend `fs_search search_mode="grep"` scoped to the source URI.
 
-(`list.sh` below is the route-backed equivalent enriched with
+(`GET sources` below is the route-backed equivalent enriched with
 `kind_label`/`kind_icon`/`kind_trust`/`orphan`; use it when you want the
 server-side source rows rather than the index-count survey.)
 
@@ -52,41 +54,40 @@ server-side source rows rather than the index-count survey.)
 **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 | Feature | Script |
+| Action | Method | Path (`@neuralis/brain-core/…`) | Fields | Feature |
 |---|---|---|---|---|
-| List configured sources                     | GET    | `/sources`                    | `drive.read`  | `list.sh` |
-| Get one source's config                     | GET    | `/sources/:slug`              | `drive.read`  | `get.sh` |
-| List registered kinds                       | GET    | `/sources/kinds`              | `drive.read`  | `kinds.sh` |
-| Get a kind's config schema                  | GET    | `/sources/kinds/:kind/schema` | `drive.read`  | `kind-schema.sh` |
-| Discoverable connectors (filesystem hints)  | GET    | `/sources/discoverable`       | `drive.mount` | `discoverable.sh` |
-| Browse a filesystem path before adding it   | GET    | `/sources/browse?path=…`      | `drive.mount` | `browse.sh` |
-| Create a new source                         | POST   | `/sources`                    | `drive.mount` | `create.sh` |
-| Update an existing source                   | PATCH  | `/sources`                    | `drive.mount` | `update.sh` |
-| Delete a source                             | DELETE | `/sources/:slug`              | `drive.mount` | `delete.sh` |
-| Enable / disable a source                   | POST   | `/sources/enabled`            | `drive.mount` | `set-enabled.sh` |
-| Trigger sync (202 + queue job snapshot)     | POST   | `/sources/sync`               | `drive.sync`  | `sync.sh` |
-| Cancel an in-flight sync (optional SOURCE)  | POST   | `/sources/cancel`             | `drive.sync`  | `cancel.sh` |
-| Job status (optional SOURCE)                | GET    | `/sources/sync-status`        | `drive.sync`  | `sync-status.sh` |
-| Forget sync state (next tick re-walks; deletes nothing) | POST | `/sources/reset` | `drive.sync` | `reset.sh` |
-| Rescan changes (full re-walk now; unchanged files keep their vectors; 202 + job) | POST | `/sources/reindex` | `drive.sync` | `reindex.sh` |
-| Clean a file / folder / source index (estimate first) | POST | `/sources/purge` | `drive.mount` + `drive.sync` | `purge-index.sh` |
-| Catch up embedding debt; FORCE=1 re-embeds (estimate first) | POST | `/sources/reindex` + `embeddingOnly` or `force` | `drive.sync` | `reembed.sh` |
-
-> **`update` takes no `:slug`.** PATCH targets the bare `/sources` path; the
+| 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` |
+
+> **`update` takes no `<slug>`.** PATCH targets the bare `sources` path; the
 > source to patch is the body `source` field (the handler ignores the path).
 
-`list.sh` returns each row enriched with `kind_label` / `kind_icon` /
+`GET sources` returns each row enriched with `kind_label` / `kind_icon` /
 `kind_trust` / `orphan` (an orphan row's contributing kind package is missing).
-The list route also accepts optional `?scope=project|user|agent` and
-`?observed=1` query filters — `list.sh` sends neither, so it returns the
-default project-visible set.
+Without `-f scope=project|user|agent` or `-f observed=1` it returns the default
+project-visible set.
 
 **Output shape (jq) — read before piping.** `GET /sources` returns a **top-level
 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.sh` (`/sources/:slug`) returns a single object, not an array.
+read its root, and `sync.lastSyncResult.error` is a fixed text without `drive.sync`. `GET sources/<slug>` returns a single object, not an array.
 
 ## Feature gates
 
@@ -95,17 +96,17 @@ 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`:
 
-- **`drive.mount`** — `create.sh`, `update.sh`, `delete.sh`, `set-enabled.sh`,
-  `browse.sh` and `discoverable.sh`. Browsing and the
+- **`drive.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`** — `browse.sh` on the filesystem root or any
+- **`drive.mount.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.sh`, `cancel.sh`, `reset.sh`, `reindex.sh`, `reembed.sh`, `sync-status.sh`.
+- **`drive.sync`** — sync, cancel, reset, reindex, `reembed.sh`, sync-status.
 
-`purge-index.sh` requires both `drive.mount` and `drive.sync`, source-scope management authority and current READ visibility.
+The index purge requires both `drive.mount` and `drive.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.
@@ -143,42 +144,37 @@ role or agent asking for a shell needs a policy row added with
 
 ## Async sync semantics
 
-`sync.sh` and `reindex.sh` return **202 + a queue job snapshot**
+`sources/sync` and `sources/reindex` return **202 + a queue job snapshot**
 (`{jobId, source, mode, status}`) immediately — the run executes on the
-server-side sync queue. Poll `sync-status.sh` (`SOURCE=<slug>`) until
+server-side sync queue. Poll `sources/sync-status` (`-f source=<slug>`) until
 `status` leaves `pending`/`running`; a `failed` job carries `error`, a
-`cancelled` one is not an error (partial progress stays valid). `cancel.sh`
-with `SOURCE` stops one source's job mid-run; without it, every job on
+`cancelled` one is not an error (partial progress stays valid). `sources/cancel`
+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.
 
-`sync.sh` refuses in two ways worth telling apart. **404** — the slug does not
+`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 `update.sh` first. Neither is a server
+there is nothing to trigger: add one with an update first. Neither is a server
 fault, so neither should be retried unchanged.
 
-## Env vars
-
-Per-action:
-- `SLUG` — source slug path segment for `get.sh` and `delete.sh` ONLY (it is a
-  real path segment there). `update.sh` does NOT take a slug — it keys off the
-  `source` field inside `BODY_JSON`.
-- `KIND` — for `kind-schema.sh`: a registry kind as listed by `kinds.sh`, NOT a connector
-  id or a UI label. An unregistered value is `404 Unknown kind "<x>"` for every caller.
-- `PATH_ARG` — for `browse.sh` (we don't reuse `PATH`).
-- `PURGE` — optional for `delete.sh`; `PURGE=1` (or `true`) 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.
-- `SOURCE` — source name for `sync.sh`, `reindex.sh`, `reset.sh`, `reembed.sh` (required) and
-  `cancel.sh`, `sync-status.sh` (optional).
-- `FOLDER` / `URI` — `reembed.sh` scope (one of them, inside `SOURCE`; neither = the whole
+## Fields, bodies and script env
+
+- `<slug>` is a real path segment for get and delete ONLY. The update does NOT
+  take a slug — it keys off the `source` field inside the body.
+- `<kind>` in `sources/kinds/<kind>/schema` is a registry kind as listed by
+  `sources/kinds`, NOT a connector id or a UI label. An unregistered value is
+  `404 Unknown kind "<x>"` for every caller.
+- `?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
   writer's points of the source, not only yours — the way back after an operator dense clear.
-- `ENABLED` — `true | false | auto` for `set-enabled.sh`.
-- `BODY_JSON` — POST/PATCH bodies (`create.sh`, `update.sh`). Both MUST include
+- 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
   round-tripped through jq never 400s on it) — see **Package sources** below. A `sync`
@@ -192,14 +188,14 @@ Per-action:
   `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.
 
-**`update.sh` REPLACES `permissions` wholesale — it does not merge.** A PATCH body
+**The update REPLACES `permissions` wholesale — it does not merge.** A PATCH body
 carrying only `permissions.default` answers `200` and **silently drops every
 `paths[]` rule the source was carrying** (`data` typically holds dozens of
 per-package rules). Immutable `floor:true` rules are the one protected class — omitting
 one returns `409` instead of destroying it — so a green `200` is NOT evidence that the
 rest survived. Never hand-write a `permissions` object for an existing source: read the
-current one with `list.sh` and send it back unchanged, editing only the field you meant
-to change. Every `update.sh` example below does exactly that.
+current one with `GET sources` and send it back unchanged, editing only the field you meant
+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
@@ -218,28 +214,28 @@ theirs.
 
 ## Clean index without detaching the source
 
-`purge-index.sh` uses `{source,selector:{kind:"source"|"folder"|"file",uri?},mode:"estimate"|"apply",obsoleteOnly:true|false}`. `SOURCE` is required; `FOLDER` or `URI` selects a canonical URI inside it; neither selects the whole source. It returns only authorized counts: `removedParents`, `removedChunks`, `retained`, `unresolved`, `canMaintain`. Unreadable children are withheld. Missing configuration, invalid provenance or read failures are not deletion evidence; unresolved points stay untouched. No source config, host bytes, journal or baseline is deleted and no embedding provider is called.
+`POST sources/purge` takes `{source,selector:{kind:"source"|"folder"|"file",uri?},mode:"estimate"|"apply",obsoleteOnly:true|false}`. `source` and `mode` are required (no `mode` is a 400, never an implicit apply); a `folder` or `file` selector names a canonical URI inside the source; `kind:"source"` selects the whole source. It returns only authorized counts: `removedParents`, `removedChunks`, `retained`, `unresolved`, `canMaintain`. Unreadable children are withheld. Missing configuration, invalid provenance or read failures are not deletion evidence; unresolved points stay untouched. No source config, host bytes, journal or baseline is deleted and no embedding provider is called.
 
-The default `OBSOLETE_ONLY=true` cleans only current include/exclude or disabled-media exclusions. `false` clears all selected searchable cache, preserving recovery payloads; later sync can rebuild it. Existing scoped recovery-only payloads can remain locally retained if source config is physically absent; that marker grants no READ or indexing permission, and unmarked missing input or invalid provenance still blocks generation switching. Already recovery-only eligible records with unavailable input stay fully preserved without vectors in the target, including when source I/O returns no input; verified input restores searchable embedding. Estimate first, show counts and the selection, then use `CONFIRM=1` for the explicit apply. Apply rereads authority and eligibility; an estimate is not an authorization token. In the Sources panel, **Clean index…** exposes the same selection, counts and confirmation. An idle manual source otherwise waits until the next requested FULL sync; targeted sync and Enabled/auto changes do not clean it.
+`obsoleteOnly:true` cleans only current include/exclude or disabled-media exclusions. `false` clears all selected searchable cache, preserving recovery payloads; later sync can rebuild it. Existing scoped recovery-only payloads can remain locally retained if source config is physically absent; that marker grants no READ or indexing permission, and unmarked missing input or invalid provenance still blocks generation switching. Already recovery-only eligible records with unavailable input stay fully preserved without vectors in the target, including when source I/O returns no input; verified input restores searchable embedding. Estimate first, show counts and the selection, then resend the same body with `mode:"apply"`. Apply rereads authority and eligibility; an estimate is not an authorization token. In the Sources panel, **Clean index…** exposes the same selection, counts and confirmation. An idle manual source otherwise waits until the next requested FULL sync; targeted sync and Enabled/auto changes do not clean it.
 
 ```bash
-# Disposable source from the lifecycle walkthrough only; default = estimate.
-SOURCE=scratch-demo OBSOLETE_ONLY=true bash ${SKILL_DIR}/scripts/purge-index.sh
+# 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"}}'
 # Apply only after reviewing the same selection’s counts.
-SOURCE=scratch-demo OBSOLETE_ONLY=true CONFIRM=1 bash ${SKILL_DIR}/scripts/purge-index.sh
+neuralis request POST @neuralis/brain-core/sources/purge --input - <<<'{"source":"scratch-demo","mode":"apply","obsoleteOnly":true,"selector":{"kind":"source"}}'
 # A canonical folder selection, still estimate-only:
-SOURCE=scratch-demo FOLDER=scratch-demo://docs OBSOLETE_ONLY=false bash ${SKILL_DIR}/scripts/purge-index.sh
+neuralis request POST @neuralis/brain-core/sources/purge --input - <<<'{"source":"scratch-demo","mode":"estimate","obsoleteOnly":false,"selector":{"kind":"folder","uri":"scratch-demo://docs"}}'
 ```
 
 ## 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 `sync-status.sh`). Disabled embedding refuses: each `list.sh` 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. `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
 `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`)
 
-`create.sh` / `update.sh` accept `recognizesPackages` (boolean) in `BODY_JSON`. It does
+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
@@ -267,25 +263,25 @@ scope (a different run identity sees nothing — correct-by-design, not a load f
 ```bash
 # NOT DISPOSABLE — promoting is only meaningful on a source that already exists
 # and already holds markdown, so this edits a REAL source. `repo` is a stand-in:
-# substitute a slug from list.sh. The effect is live — every matching .md under
+# substitute a slug from the sources list. The effect is live — every matching .md under
 # it starts being advertised as a package contribution on the next sync — and it
 # is reversible only by resending the same body with `recognizesPackages:false`.
 # Needs drive.mount, then priority <= 2 (the admin anchor) or a '*' grant, and a
 # local-kind source. The body carries the source's CURRENT permissions back —
 # PATCH replaces them:
-BODY_JSON=$(bash ${SKILL_DIR}/scripts/list.sh | jq -c '.[] | select(.source=="repo") | {source, permissions, recognizesPackages:true}') bash ${SKILL_DIR}/scripts/update.sh
+neuralis request GET @neuralis/brain-core/sources --jq '.[] | select(.source=="repo") | {source, permissions, recognizesPackages:true}' | neuralis request PATCH @neuralis/brain-core/sources --input -
 ```
 
 ## `description` field
 
-Both create and update accept an optional `description` (string) in `BODY_JSON`.
+Both create and update accept an optional `description` (string) in the body.
 It is a one-line summary of what the source holds; it is persisted on the source
 config and loaded into the agent system prompt's `<runtime_stack>` source table,
 so keep it short and purpose-focused (e.g. `"Project data zone — working files"`).
 
 **Leaving it unset is fine.** The description you see is RESOLVED, not
 necessarily stored: the authored text, else what the owning package declared for
-that source, else what the connector kind says it is. `list.sh` and `get.sh`
+that source, else what the connector kind says it is. The list and the get
 return both — `description` is what is on disk, `description_effective` is what
 the agent actually reads. So a blank `description` with a non-null
 `description_effective` is a source described by its package, not an undescribed
@@ -298,18 +294,22 @@ each sync — you do not set them.
 ## Examples
 
 ```bash
-bash ${SKILL_DIR}/scripts/list.sh
-# list.sh = TOP-LEVEL ARRAY → filter with .[] (NOT .sources[]):
+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).
-bash ${SKILL_DIR}/scripts/list.sh | jq '.[] | {source, enabled, kind: .connection.kind, orphan}'
-bash ${SKILL_DIR}/scripts/list.sh | jq '.[] | select(.connection.kind=="local")'
-# `KIND` is the registry KIND, not a connector id or a UI label. Enumerate them with
-# kinds.sh (today: brain, host, local, webtop); an unregistered value is 404
+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")'
+# 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
 # `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`.
-bash ${SKILL_DIR}/scripts/kinds.sh | jq -r '.kinds[].kind'
-KIND=local bash ${SKILL_DIR}/scripts/kind-schema.sh
-SOURCE=data bash ${SKILL_DIR}/scripts/sync.sh                 # needs drive.sync
+neuralis request GET @neuralis/brain-core/sources/kinds --jq '.kinds[].kind'
+neuralis request GET @neuralis/brain-core/sources/kinds/local/schema
+neuralis request POST @neuralis/brain-core/sources/sync -f source=data      # needs drive.sync
+neuralis request GET @neuralis/brain-core/sources/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
 ```
 
 ### Lifecycle walkthrough — create → update → delete
@@ -327,26 +327,26 @@ the throwaway.
 ```bash
 # 1. Create (needs drive.mount). source + connection.kind + permissions.default.* required.
 #    The root does not have to exist yet — create records the coordinate, sync walks it.
-BODY_JSON='{"source":"scratch-demo","connection":{"kind":"local","config":{"root":"/tmp/scratch-demo"}},"permissions":{"default":{"read":true,"write":true,"exec":false}}}' bash ${SKILL_DIR}/scripts/create.sh
+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).
 #    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
 #    delete every paths[] rule the source carried:
-BODY_JSON=$(bash ${SKILL_DIR}/scripts/list.sh | jq -c '.[] | select(.source=="scratch-demo") | {source, permissions, description:"Throwaway source — lifecycle demo"}') bash ${SKILL_DIR}/scripts/update.sh
-# 3. DESTRUCTIVE — deletes the source config, and with PURGE=1 enqueues an async purge
+neuralis request GET @neuralis/brain-core/sources --jq '.[] | select(.source=="scratch-demo") | {source, permissions, description:"Throwaway source — lifecycle demo"}' | neuralis request PATCH @neuralis/brain-core/sources --input -
+# 3. DESTRUCTIVE — deletes the source config, and with ?purge=1 enqueues an async purge
 #    of every vector indexed under it. Returns 202 + {purgeJob} when purging, 200
 #    otherwise. There is no undo and no backup. Only ever aim this at a source you
 #    created yourself; never at `data`, `packages` or `brain`.
-SLUG=scratch-demo PURGE=1 bash ${SKILL_DIR}/scripts/delete.sh
+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 the implicit session ticket via the `execute` shell action. **The two
+`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`
-and is POST-only (see below). That covers all three of its actions: `gc` and `repair-orphans`
+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.
 
@@ -359,14 +359,14 @@ mutate, and `deduplicate` is read-only but rides the same gate — its rows enum
   `duplicateGroups` are COUNTS (numbers) — read them directly, never `|length`. The full duplicate
   ROWS arrive only from `POST …/health/gc {action:deduplicate}` → `{ duplicates: DuplicateGroup[] }`
   (each `{contentHash, source, paths, ids}`).
-- **`POST …/brain-core/health/gc`** with `{action}` (`gc` / `repair-orphans` / `deduplicate`) —
-  `gc` and `repair-orphans` MUTATE — run those only after a scan confirms a finding; `deduplicate`
+- **`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)"}`.
   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.
-  `dryRun` DEFAULTS TO FALSE — pass `{"dryRun": true}` first when you want a preview.
+  `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
@@ -377,11 +377,9 @@ mutate, and `deduplicate` is read-only but rides the same gate — its rows enum
 
 ```bash
 # counts (cheap):
-curl --fail-with-body -sS -H "Authorization: Bearer ${NEURALIS_SESSION_TOKEN}" -H "X-Neuralis-Skill: manage-sources" \
-  "${NEURALIS_API}/api/packages/@neuralis/brain-core/health"
+neuralis request GET @neuralis/brain-core/health
 # orphans / duplicate groups (scrolls — slower):
-curl --fail-with-body -sS -H "Authorization: Bearer ${NEURALIS_SESSION_TOKEN}" -H "X-Neuralis-Skill: manage-sources" \
-  "${NEURALIS_API}/api/packages/@neuralis/brain-core/health/scan"
+neuralis request GET @neuralis/brain-core/health/scan
 ```
 
 ### Health steps

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

@@ -1,7 +1,5 @@
 #!/usr/bin/env bash
 set -euo pipefail
-API_BASE="${NEURALIS_API:?NEURALIS_API not set; activate skill first}"
-TOKEN="${NEURALIS_SESSION_TOKEN:?missing session ticket; activate the skill via execute action=\"skill\"}"
 # Requires drive.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
@@ -21,7 +19,5 @@ BODY=$(jq -n --arg source "${SOURCE}" --arg folder "${FOLDER}" --arg uri "${URI}
    + (if $force == "1" then {force: ($confirm == "1")} else {embeddingOnly: true} end)
    + (if $scope == "" then {} else {scope: $scope} end)
    + (if $confirm == "1" then {} else {estimate: true} end)')
-curl --fail-with-body -sS -X POST \
-  -H "Authorization: Bearer ${TOKEN}" -H "X-Neuralis-Skill: manage-sources" \
-  -H "Content-Type: application/json" -d "${BODY}" \
-  "${API_BASE}/api/packages/@neuralis/brain-core/sources/reindex"
+# A non-2xx answer prints the route's body and `HTTP <code>` on stderr and exits 1.
+neuralis request POST @neuralis/brain-core/sources/reindex --input - <<<"${BODY}"

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

@@ -12,10 +12,11 @@ Patch the `paths[]` rules on a brain-core source-config so subsequent
 it edits the URI policy on any source (`data://`, `packages://`,
 `brain://`, future remote connectors), not vector or embedding state.
 
-Wraps the brain-core `policies/uri` routes, authenticated with the
-per-stream session ticket (`NEURALIS_SESSION_TOKEN`) auto-injected into the
-script env at skill activation. It carries your real identity; the routes
-gate on your real granted features server-side.
+Covers the brain-core `policies/uri` routes, called with `neuralis request` —
+inside an activated skill it authenticates with the per-stream session ticket
+(your real identity), on your own machine with `neuralis login`. The routes
+gate on your real granted features server-side; a non-2xx prints the route's
+body and `HTTP <code>` on stderr and exits 1.
 
 ## When to use
 
@@ -27,69 +28,56 @@ gate on your real granted features server-side.
 
 ## Routes
 
-| Method | Path | Wrapper |
-|---|---|---|
-| GET  | `/policies/uri/manifests`     | `scripts/manifests.sh` |
-| GET  | `/policies/uri/:source`       | `scripts/show-uri.sh`  |
-| POST | `/policies/uri`               | `scripts/set-uri.sh`   |
+| Method | Path (`@neuralis/brain-core/…`) |
+|---|---|
+| GET  | `policies/uri/manifests`     |
+| GET  | `policies/uri/<source>`      |
+| POST | `policies/uri`               |
 
-## Scripts
+## Calls
 
 ### Show effective URI policy for a source
 
 ```bash
-SOURCE=data bash ${SKILL_DIR}/scripts/show-uri.sh
+neuralis request GET @neuralis/brain-core/policies/uri/data
 ```
 
-Required env vars (pass via `execute action="shell" env={...}`):
-- `SOURCE` — source slug (e.g. `data`, `packages`).
-
 ### Add or remove a path rule
 
 **`addRule` takes effect the moment it returns — on a REAL source.** There is no
 staging, no preview and no dry run: the next `fs_read`, route call, UI listing or
 shell command evaluated against that source already sees the new rule, for every
-caller it names. `removeRule` is the only undo, and it matches on the `PATTERN`
+caller it names. `removePatterns` is the only undo, and it matches on the `pattern`
 string, so a rule you cannot spell exactly is a rule you cannot take back. Read
-the current policy with `show-uri.sh` before and after — the pair below is
+the current policy before and after — the pair below is
 written to be run top-to-bottom and leaves the policy exactly as it found it.
-One caveat the rules do not show: a `removeRule` is not always the last word
+One caveat the rules do not show: a removal is not always the last word
 across a restart. The old cause is FIXED — the route no longer un-stamps
 `baselineRepairVersion`, so a patch (a no-op included) does not re-arm the
 baseline repair and cannot resurrect a rule you removed. What remains is the
 legitimate case: a package that SHIPS a new manifest baseline, or a connector
 that adds a `floor:true` row, still reaches an existing source on the next boot
 by design — floors are reconciled on every boot, past the version stamp. So
-re-check with `show-uri.sh` after a restart when a package version changed, and
+re-check the policy after a restart when a package version changed, and
 read a reappeared rule as a NEW declaration rather than as your removal being
 undone.
 
 ```bash
 # 0. Read the policy you are about to change, so you can prove you restored it.
-SOURCE=data bash ${SKILL_DIR}/scripts/show-uri.sh
+neuralis request GET @neuralis/brain-core/policies/uri/data
 # 1. Add the rule (LIVE — members lose read on this subtree immediately).
-SOURCE=data \
-PATTERN='data://agent-core/admin/**' \
-DENY=read \
-ROLES=member \
-bash ${SKILL_DIR}/scripts/set-uri.sh
-# 2. Take it back — same SOURCE, same PATTERN, byte for byte.
-SOURCE=data \
-PATTERN='data://agent-core/admin/**' \
-OPERATION=removeRule \
-bash ${SKILL_DIR}/scripts/set-uri.sh
+neuralis request POST @neuralis/brain-core/policies/uri --input - <<<'{"source":"data","addPaths":[{"pattern":"data://agent-core/admin/**","permissions":{"read":false},"roles":["member"]}]}'
+# 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/**"]}'
 ```
 
 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.
 
-Env vars:
-- `SOURCE` — source slug (required).
-- `OPERATION` — `addRule` (default) or `removeRule`.
-- `PATTERN` — URI pattern with `**` wildcards (required for both).
-- `DENY` — comma-list of capabilities to deny (`read,write,exec`).
-- `ALLOW` — comma-list of capabilities to allow.
-- `ROLES` — comma-list of roles to scope the rule to.
+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).
 
 `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
@@ -101,34 +89,19 @@ refused" usually needs an `exec` ALLOW row for their role or agent here.
 ### List baseline URI policies from every loaded package's manifest
 
 ```bash
-bash ${SKILL_DIR}/scripts/manifests.sh
+neuralis request GET @neuralis/brain-core/policies/uri/manifests
 ```
 
-No env vars — returns every package's resolved `uriPolicies` baseline
+Returns every package's resolved `uriPolicies` baseline
 (read-only). Useful for diffing the persisted source-config against the
 package's seed.
 
-## Substitution placeholders
-
-When this skill is activated the host substitutes:
-
-- `${SKILL_DIR}` → container path of this skill bundle
-  (e.g. `/neuralis/packages/brain-core/skills/manage-uri-policy`).
-- `${NEURALIS_API}` → the host's internal API base URL.
-- `${SKILL_URI}` → `neuralis://`-addressable URI if the `neuralis://`
-  source is enabled, otherwise a sentinel.
-
-If `${SKILL_DIR}` resolves to a sentinel ("(no local containerDir)"),
-there is no local script directory — unless the envelope printed a source directory URI to pass as `cwd`, read
-`fs_read uri="${SKILL_URI}/SKILL.md"` for the procedure and call the
-routes manually with `execute action="shell" command="curl ..."`.
-
 ## Notes
 
 - **Two arms, both keyed on FEATURES — there is no role-name check on this
-  route.** Reading (`GET /policies/uri/...`, `manifests.sh` / `show-uri.sh`) is
+  route.** Reading (`GET policies/uri/...`) is
   the module feature `drive.read`, which every built-in role holds down to
-  `viewer`. Patching (`POST /policies/uri`, `set-uri.sh`) escalates in-handler 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
   no grant below the `admin` tier (enumerated for `admin`, `'*'` for `owner`)
@@ -155,9 +128,8 @@ routes manually with `execute action="shell" command="curl ..."`.
   conversation's creator). It is accepted only on an allow rule with
   `override: true` — the server refuses it on a deny. That is how agent-core
   ships conversations: `*/conversations/**` denied, re-granted to the creator
-  and to owner/admin, so a member sees only their own. This script does not
-  write `users`; widening who sees a conversation is done in the source's
-  policy editor.
+  and to owner/admin, so a member sees only their own. Widening who sees a
+  conversation is done in the source's policy editor.
 - **Connector-agnostic.** A rule like `roles:["member"] deny:["write"]`
   on `webtop://**` applies to a future WebtopConnector source just as
   it does to `data://agent-core/**` today — the URI is the unit of

package/skills/git/scripts/git.sh

@@ -1,48 +0,0 @@
-#!/usr/bin/env bash
-# Generic caller for the brain-core git routes — ONE helper for all 19 endpoints
-# (9 GET + 10 POST, spread over 17 route names: `commit` and `branch` carry both verbs).
-# NOTE the shape: the HTTP VERB is a positional ARGUMENT, not a property of this file.
-# Anything auditing "which examples mutate" must read the verb off the INVOCATION line
-# (`git.sh POST commit …`), never off this script — 10 of the 19 endpoints are POST writes,
-# and `commit`/`branch` READ on GET while WRITING on POST.
-#   GET:  git.sh GET  <route> [key=value ...]     # each pair is URL-encoded
-#   POST: git.sh POST <route> '<json-body>'       # body carries "source" + params
-# Auth is the per-stream session ticket (NEURALIS_SESSION_TOKEN), injected by the
-# skill activation — never a platform/admin token, never a git credential (the
-# route resolves the remote token server-side for fetch/pull/push).
-# `--fail-with-body` (NOT `-f`): the routes' error bodies still reach you on
-# 400/403/404/409 — `-f` would leave a bare `curl: (22)` — and a refused call
-# now exits NON-ZERO as well, so a rejected commit/push can no longer read as a
-# success. Failure shapes, measured 2026-09-01 against `src/routes/git.ts` —
-# EVERY refusal carries `error`, and:
-#   · a write-op failure (400/409/500) and the three remote 409s
-#     (`no_https_remote` / `not_connected` / `no_credential`) also carry
-#     `ok:false` AND `code`;
-#   · a 403 carries `code` (`feature_denied` / `uri_policy_denied`), no `ok`;
-#   · a plain argument or lookup 400/404 carries `error` only.
-# Separately, a **200** may still carry `ok:false`: `unavailable` from
-# `commit`/`outgoing`/`show`, `too_large` from `diff`. So use THIS script's exit
-# code as the discriminator — non-zero = an HTTP refusal (read `.error`, then
-# `.code` when present); zero + `ok:false` = a soft 200.
-set -euo pipefail
-API_BASE="${NEURALIS_API:?NEURALIS_API not set; activate skill first}"
-TOKEN="${NEURALIS_SESSION_TOKEN:?missing session ticket; activate the skill via execute action=\"skill\"}"
-METHOD="${1:?usage: git.sh <GET|POST> <route> [key=value ... | json-body]}"
-ROUTE="${2:?usage: git.sh <GET|POST> <route> [key=value ... | json-body]}"
-shift 2
-URL="${API_BASE}/api/packages/@neuralis/brain-core/git/${ROUTE}"
-AUTH=(-H "Authorization: Bearer ${TOKEN}" -H "X-Neuralis-Skill: git")
-if [ "${METHOD}" = "GET" ]; then
-  ENC=()
-  for kv in "$@"; do ENC+=(--data-urlencode "${kv}"); done
-  curl --fail-with-body -sS -G "${AUTH[@]}" "${ENC[@]}" "${URL}"
-else
-  # `${1:-{}}` does NOT work here: bash closes the expansion at the FIRST `}`, so
-  # the default becomes `{` and the trailing `}` is appended as a LITERAL — every
-  # POST body went on the wire as `{…}}`, invalid JSON, for all 10 POST routes.
-  # `--data-raw` (not `-d`): `-d` treats a leading `@` as a FILE reference.
-  BODY="${1:-}"
-  [ -z "${BODY}" ] && BODY='{}'
-  curl --fail-with-body -sS -X "${METHOD}" "${AUTH[@]}" \
-    -H "Content-Type: application/json" --data-raw "${BODY}" "${URL}"
-fi