@neuralis/brain-core 0.1.0 → 0.2.1

package/skills/create-package/scripts/verify-loaded.sh

@@ -45,7 +45,7 @@
 #
 # USAGE   bash verify-loaded.sh <package-id> [--raw]
 #           <package-id>  the manifest id, e.g. "@acme/reports" or "reports".
-#                         For a source package pass its "source:<rootUri>" id.
+#                         A drop or source package: its instance URI, quoted.
 #           --raw         dump both untouched JSON responses before the verdict,
 #                         so you can self-diagnose if the shape ever drifts.
 # EXIT    0 = loaded
@@ -58,7 +58,7 @@
 #
 # This script never accepts, prints or persists a token.
 #
-# Testing reference: https://docs.neuralisapp.com/docs/package-system/testing
+# Testing reference: https://docs.neuralisapp.com/package-system/testing
 
 set -euo pipefail
 
@@ -75,17 +75,17 @@ done
 
 manual_fallback() {
   case "$PKG_ID" in
-    source:*)
+    *://*)
       cat >&2 <<'SRCFALLBACK'
 
 Cannot verify programmatically. Do NOT record this package as working.
 
-This id names a SOURCE package. It never passes through the loader, so there
-is NO load line in the server log and its absence proves nothing. Verify it
-this way instead:
+A SOURCE package never passes through the loader, so there is NO load line
+in the server log (a drop's id has the same URI form and does get one).
+Verify a source package this way instead:
 
   1. Read your own <packages> block. A recognised source package appears as
-     "source:<rootUri> [active, source]" with its per-category counts.
+     "<rootUri> [active, source]" with its per-category counts.
      Caveat: files that are switched OFF by default (rule files, identity
      instructions) are dropped from that block, and a package with nothing
      visible left is omitted entirely — so <packages> can under-report a
@@ -223,7 +223,7 @@ if (!entry && srcEntry) {
   process.stdout.write(`SOURCE PACKAGE  ${pkgId}\n`);
   line('name', srcEntry.name || '(unnamed)');
   line('source', `${srcEntry.source || '?'} (${srcEntry.connectorKind || '?'})`);
-  line('root', `${srcEntry.rootUri || '?'}   (the id is always "source:" + this)`);
+  line('root', `${srcEntry.rootUri || '?'}   (the id is this + ?project=…&scope=…)`);
   line('recognized', `by ${srcEntry.reason}`);
   line('enabled', srcEntry.enabled === false ? 'no' : 'yes');
   for (const cat of ['skills', 'instructions', 'rules', 'agents', 'docs']) {
@@ -242,11 +242,11 @@ if (!entry) {
   w(`ABSENT  ${pkgId}\n`);
   w(`        Not among the ${diag.entries.length} installed and ${overSource.length} source package(s) the platform reports for you.\n\n`);
   w('This is often correct by design, not a failure. Work through these in order:\n');
-  w('  1. The id is wrong. An INSTALLED package is its manifest id EXACTLY, scope\n');
-  w('     prefix included ("@acme/reports" is not "reports"). A SOURCE package is\n');
-  w('     literally "source:" + its root URI — "source:data://acme-pack", no trailing\n');
-  w('     slash on a sub-directory; a package at the source root keeps the "://"\n');
-  w('     ("source:data://"). Both lists below print the exact strings.\n');
+  w('  1. The id is wrong. A host-installed package is its manifest id EXACTLY,\n');
+  w('     scope prefix included ("@acme/reports" is not "reports"). A drop or SOURCE\n');
+  w('     package is its root URI, no trailing slash, plus project and scope:\n');
+  w('     "data://acme-pack?project=<p>&scope=project" — <packages> shows it short,\n');
+  w('     "data://acme-pack". Both lists below print the exact strings.\n');
   w('  2. It was never installed, or the install did not land where you think.\n');
   w('  3. It is disabled for this agent or conversation.\n');
   w('  4. You cannot see it: visibility is scoped per user and per agent, and a\n');
@@ -260,8 +260,8 @@ if (!entry) {
   w('     package root or on the file itself. Once a sync has indexed the files they\n');
   w('     show on the next stream — discovery is not cached behind a timer.\n');
 
-  if (pkgId.includes('://') && !pkgId.startsWith('source:')) {
-    w(`\nThat looks like a root URI, not an id. Try:  source:${pkgId.endsWith('://') ? pkgId : pkgId.replace(/\/+$/, '')}\n`);
+  if (pkgId.includes('://') && !pkgId.includes('?')) {
+    w('\nNot a full id: an instance id ends in ?project=…&scope=… — the lists below print it.\n');
   }
   const rows = (title, items) => {
     w(`\n${title}\n`);
@@ -271,7 +271,7 @@ if (!entry) {
   };
   rows(`Installed package ids the platform lists for you (${diag.entries.length}):`,
     diag.entries.map((e) => [String(e.packageId), e.status && e.status !== 'loaded' ? `[${e.status}]` : '']));
-  rows(`Source package ids (${overSource.length}) — always "source:" + the root URI:`,
+  rows(`Source package ids (${overSource.length}) — the root URI + ?project=…&scope=…:`,
     overSource.map((p) => {
       const files = ['skills', 'instructions', 'rules', 'agents', 'docs']
         .reduce((n, c) => n + (Array.isArray(p[c]) ? p[c].length : 0), 0);

package/skills/manage-files/SKILL.md

@@ -41,9 +41,9 @@ server-side **403** from `search.sh` even though the other scripts work.
 - `/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. Every script here runs curl with `--fail-with-body`, so a non-2xx prints that body too — in the merged output the body comes FIRST and curl's own `curl: (22)` line after it, 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 via `URI=…` (no `BODY_JSON`). It always returns the full bytes, so `raw.sh` is 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**. 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.
+- `/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 — pass `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.
-- `GET /pending` lists durable pending records inside the Changes workspace. `STATUS`, `SOURCE`, `OP`, 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. 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.
+- `GET /pending` lists durable pending records inside the Changes workspace. `STATUS`, `SOURCE`, `OP`, 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.
 
 
 The body shape is route-specific — refer to brain-core's

package/skills/manage-sources/SKILL.md

@@ -70,7 +70,7 @@ server-side source rows rather than the index-count survey.)
 | 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` |
-| Re-embed a file / folder / source (estimate first) | POST | `/sources/reindex` + `force` | `drive.sync` | `reembed.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
 > source to patch is the body `source` field (the handler ignores the path).
@@ -151,6 +151,8 @@ server-side sync queue. Poll `sync-status.sh` (`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.
+
 `sync.sh` 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
@@ -167,11 +169,14 @@ Per-action:
   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).
+  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
-  source). `CONFIRM=1` starts the re-embed; without it the script only ESTIMATES.
+  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
   `source` + `permissions`; create additionally requires `connection.kind`. May also
@@ -182,7 +187,7 @@ Per-action:
   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. 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 `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
   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.
@@ -228,22 +233,18 @@ SOURCE=scratch-demo FOLDER=scratch-demo://docs OBSOLETE_ONLY=false bash ${SKILL_
 
 ## Re-embed (a file, a folder, a source)
 
-"Rescan changes" reuses unchanged indexed files, but rebuilds re-included recovery-only content. `reembed.sh` forces every file in the
-scope is read again and embedded with the ACTIVE model, and nothing else about the source
-changes. Run it WITHOUT `CONFIRM` first — it answers `{documents, estimate:{tokens,
-relStdErr, usd, seconds}}` and changes nothing (`usd` is `null` for an unpriced model; the
-count covers only files you may read). Show that to the user, then run it again with
-`CONFIRM=1` (202 + job; poll `sync-status.sh`). 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 `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
 `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`. When
-true, the source's markdown is discovered as **package contributions** (skill /
-instruction / rule / agent / docs — there is no `team` category via this path) — this is
-how a synced source feeds packages back (source packages, R2/R2b). Two server-side gates
-apply regardless of what you send (`src/routes/sources.ts`):
+`create.sh` / `update.sh` accept `recognizesPackages` (boolean) in `BODY_JSON`. 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
+`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`):
 
 - **Owner/admin-STRENGTH only, measured by PRIORITY — not by role name.** The
   gate passes a caller whose `priority` is at or above the built-in `admin`

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

@@ -2,19 +2,25 @@
 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). Re-embeds with the ACTIVE model — a
+# 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
 # nothing); CONFIRM=1 starts it (202 + job). Only files you may read count.
+# SCOPE=platform (catch-up only, whole source, needs platform.vector.maintain)
+# catches up EVERY writer's points of the source — the way back after a dense clear.
 SOURCE="${SOURCE:?SOURCE is required}"
 FOLDER="${FOLDER:-}"
 URI="${URI:-}"
 CONFIRM="${CONFIRM:-}"
-BODY=$(jq -n --arg source "${SOURCE}" --arg folder "${FOLDER}" --arg uri "${URI}" --arg confirm "${CONFIRM}" \
+FORCE="${FORCE:-}"
+SCOPE="${SCOPE:-}"
+BODY=$(jq -n --arg source "${SOURCE}" --arg folder "${FOLDER}" --arg uri "${URI}" --arg confirm "${CONFIRM}" --arg force "${FORCE}" --arg scope "${SCOPE}" \
   '{ source: $source }
    + (if $folder == "" then {} else { folder: $folder } end)
    + (if $uri == "" then {} else { uri: $uri } end)
-   + (if $confirm == "1" then { force: true } else { estimate: true } end)')
+   + (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}" \

package/skills/sync/SKILL.md

@@ -13,20 +13,20 @@ 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 `drive.sync`; source create/update/delete uses `drive.mount`; file writes use `drive.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` — and read the two flags that change what those counts mean before you report them. `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.
+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. Remind the user that `fs_read` and `fs_list` may already show live connector data before semantic/filter search catches up.
+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
 
-A file is embedded only when BOTH inputs allow it, and they are different kinds
+A file is indexed only when BOTH inputs allow it, and they are different kinds
 of thing — say which one you mean when you report a missing file:
 
 - the source's **exclude/include patterns** — a PREFERENCE the operator owns and
   can edit at any time (`manage-sources`). A file missing for this reason is a
   configuration answer, not a security one.
 - the immutable **uri-policy read floor** — the security half. *What cannot be
-  READ cannot be EMBEDDED*: a path a `floor:true` row denies `read` on is never
+  READ cannot be INDEXED*: a path a `floor:true` row denies `read` on is never
   newly embedded, on every source including ones attached long before the floor
   shipped, and no `include` whitelist resurrects it. There is no exclude entry to
   add and none to remove.

package/tools/fs_search.json

@@ -3,7 +3,7 @@
   "title": "Search Filesystem Nodes",
   "type": "object",
   "additionalProperties": false,
-  "description": "Find files by meaning, by indexed metadata, or by literal text in the live files. For a place you cannot name yet, pair semantic search with a scoped grep to cover index lag; grep needs a folder URI and answers with line anchors. Search before you create — and before you claim something is absent: every mode says when its set was cut.",
+  "description": "Find scoped files by meaning, indexed metadata/keywords or fixed-string live grep with line anchors (folder_uri required). Pair semantic and grep to cover index lag. Search before creating or claiming absence; every mode reports truncation.",
   "properties": {
     "search_mode": {
       "type": "string",
@@ -12,7 +12,7 @@
         "filter",
         "grep"
       ],
-      "description": "'semantic' (default) = embeddings + indexed text. 'filter' = indexed metadata/keyword, no embed cost. 'grep' = FIXED-STRING (never regex) over live files, needs folder_uri. `glob` alone → filter."
+      "description": "semantic (default): embeddings + indexed text; off/unavailable embedding → filter. Check effective_mode, embedding_degraded and row embedding_status (current/stale/missing/unknown). filter: metadata/keywords, no embed cost. grep: FIXED-STRING, never regex, needs folder_uri. glob alone → filter."
     },
     "query": {
       "type": "string",

package/app/filesystem/hooks/useContainerWidth.ts

@@ -1,39 +0,0 @@
-import { useEffect, useState, type RefObject } from 'react';
-
-/**
- * Reports whether a container is "wide" (≥ threshold), with hysteresis so a diff's
- * auto unified↔split flip does not strobe while the user drags the widget across the
- * boundary. Becomes wide at `wideThresholdPx`, flips back to narrow only below
- * `wideThresholdPx − hysteresisPx`.
- *
- * It reads `clientWidth` ONLY — never `scrollWidth` — so the observer callback cannot
- * force a layout flush of its own. (Its sibling `useElementFits` did compare the two
- * and was deleted in 2026-08: it had no consumer anywhere in `packages/*`.)
- */
-export function useContainerWidth<T extends HTMLElement>(
-  ref: RefObject<T | null>,
-  options?: { wideThresholdPx?: number; hysteresisPx?: number },
-): boolean {
-  const wideThresholdPx = options?.wideThresholdPx ?? 900;
-  const hysteresisPx = options?.hysteresisPx ?? 60;
-  const [isWide, setIsWide] = useState(false);
-
-  useEffect(() => {
-    const element = ref.current;
-    if (!element) {
-      setIsWide(false);
-      return;
-    }
-    const update = () => {
-      const width = element.clientWidth;
-      setIsWide((prev) => (prev ? width >= wideThresholdPx - hysteresisPx : width >= wideThresholdPx));
-    };
-    update();
-    if (typeof ResizeObserver === 'undefined') return undefined;
-    const observer = new ResizeObserver(() => update());
-    observer.observe(element);
-    return () => observer.disconnect();
-  }, [ref, wideThresholdPx, hysteresisPx]);
-
-  return isWide;
-}

package/dist/app/chunks/bash-M45GHPBQ.js

@@ -1 +0,0 @@
-import{a as e}from"./chunk-TY33BMKR.js";import"./chunk-DCANE7XH.js";export{e as default};

package/dist/app/chunks/c-X3REOAWD.js

@@ -1 +0,0 @@
-import{a}from"./chunk-QLBZ4JR2.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/cpp-VOWI743W.js

@@ -1 +0,0 @@
-import{a}from"./chunk-G4RZ3UNX.js";import"./chunk-XIFGTNRM.js";import"./chunk-QLBZ4JR2.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/css-2ZVPHE25.js

@@ -1 +0,0 @@
-import{a}from"./chunk-DKD2L57N.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/graphql-7V2NP54C.js

@@ -1 +0,0 @@
-import{a}from"./chunk-QXXJ73P5.js";import"./chunk-6TC3DVWV.js";import"./chunk-TRRUHDPN.js";import"./chunk-OLEIKJ3X.js";import"./chunk-KYH5EHHY.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/html-UF3LFLNA.js

@@ -1 +0,0 @@
-import{a}from"./chunk-RH3QY5LF.js";import"./chunk-DKD2L57N.js";import"./chunk-OLEIKJ3X.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/java-PNTAU4L3.js

@@ -1 +0,0 @@
-import{a}from"./chunk-BGRVFATT.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/javascript-4JJTQGEL.js

@@ -1 +0,0 @@
-import{a}from"./chunk-OLEIKJ3X.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/json-VLQ6D3JH.js

@@ -1 +0,0 @@
-import{a}from"./chunk-DZ5C5FKI.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/jsx-KQKSLAAH.js

@@ -1 +0,0 @@
-import{a}from"./chunk-KYH5EHHY.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/lua-UFPYUJ2O.js

@@ -1 +0,0 @@
-import{a}from"./chunk-5H7ZCOD3.js";import"./chunk-QLBZ4JR2.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/r-QEZB45SR.js

@@ -1 +0,0 @@
-import{a}from"./chunk-737Y24HS.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/sql-DTZHNUZP.js

@@ -1 +0,0 @@
-import{a}from"./chunk-4QNMHAIR.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/tsx-WPR2WRZD.js

@@ -1 +0,0 @@
-import{a}from"./chunk-TRRUHDPN.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/typescript-LWO362OA.js

@@ -1 +0,0 @@
-import{a}from"./chunk-6TC3DVWV.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/xml-A5H72RTS.js

@@ -1 +0,0 @@
-import{a}from"./chunk-3QLE7Y4L.js";import"./chunk-BGRVFATT.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/app/chunks/yaml-MXHSIJCI.js

@@ -1 +0,0 @@
-import{a}from"./chunk-SFUNBBEA.js";import"./chunk-DCANE7XH.js";export{a as default};

package/dist/src/services/purgePendingNodes.d.ts

@@ -1,32 +0,0 @@
-/**
- * One-time `_pending` boot self-heal (prudent-indexing-otter, Step C).
- *
- * The durable Pending-Changes journal + baseline blobs live under
- * `data://brain-core/_pending/**` — sync-EXCLUDED (the runtime floor) precisely
- * because the baseline blobs may hold sensitive file content that must NEVER be
- * vectorized. Before this increment the fs write path vectorized EVERY create,
- * so projects predating the floor can carry stale `_pending` nodes in Qdrant.
- *
- * This idempotent boot pass purges them per project — the proven `runPurge`
- * bounded `deleteByFilter` shape (no full-project scroll, no client matching):
- * a single server-side delete scoped to `projectId` + `folder_ancestors` =
- * `data://brain-core/_pending` (chunks carry `folder_ancestors` too, so they are
- * covered by the same filter). `_pending`-ONLY; general excluded-node cleanup
- * rides the existing sync config-change reconcile.
- */
-import type { SourceConfigPort } from '../connectors/types.js';
-import type { VectorIndexPort } from '../vector/types.js';
-import type { FilesystemNode } from '../domain/types.js';
-export type PurgePendingResult = {
-    projects: number;
-    removed: number;
-};
-export declare function purgeStalePendingNodes(deps: {
-    sourceConfigs: SourceConfigPort;
-    getVector: (projectId: string) => Promise<VectorIndexPort<FilesystemNode>>;
-    logger?: {
-        info?: (msg: string, meta?: Record<string, unknown>) => void;
-        warn?: (msg: string, meta?: Record<string, unknown>) => void;
-    };
-}): Promise<PurgePendingResult>;
-//# sourceMappingURL=purgePendingNodes.d.ts.map

package/dist/src/services/purgePendingNodes.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"purgePendingNodes.d.ts","sourceRoot":"","sources":["../../../src/services/purgePendingNodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAKzD,MAAM,MAAM,kBAAkB,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,wBAAsB,sBAAsB,CAAC,IAAI,EAAE;IACjD,aAAa,EAAE,gBAAgB,CAAC;IAChC,SAAS,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,eAAe,CAAC,cAAc,CAAC,CAAC,CAAC;IAC3E,MAAM,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;QAAC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAA;KAAE,CAAC;CACzI,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAyC9B"}

package/dist/src/services/purgePendingNodes.js

@@ -1,61 +0,0 @@
-/**
- * One-time `_pending` boot self-heal (prudent-indexing-otter, Step C).
- *
- * The durable Pending-Changes journal + baseline blobs live under
- * `data://brain-core/_pending/**` — sync-EXCLUDED (the runtime floor) precisely
- * because the baseline blobs may hold sensitive file content that must NEVER be
- * vectorized. Before this increment the fs write path vectorized EVERY create,
- * so projects predating the floor can carry stale `_pending` nodes in Qdrant.
- *
- * This idempotent boot pass purges them per project — the proven `runPurge`
- * bounded `deleteByFilter` shape (no full-project scroll, no client matching):
- * a single server-side delete scoped to `projectId` + `folder_ancestors` =
- * `data://brain-core/_pending` (chunks carry `folder_ancestors` too, so they are
- * covered by the same filter). `_pending`-ONLY; general excluded-node cleanup
- * rides the existing sync config-change reconcile.
- */
-/** The folder-ancestor key the `_pending` journal + blob nodes carry. */
-const PENDING_FOLDER_ANCESTOR = 'data://brain-core/_pending';
-export async function purgeStalePendingNodes(deps) {
-    let scoped;
-    try {
-        scoped = await deps.sourceConfigs.listAll();
-    }
-    catch (err) {
-        deps.logger?.warn?.('pending purge: listAll failed', {
-            error: err instanceof Error ? err.message : String(err),
-        });
-        return { projects: 0, removed: 0 };
-    }
-    const projectIds = new Set();
-    for (const { scope } of scoped) {
-        if (scope.projectId)
-            projectIds.add(scope.projectId);
-    }
-    let removed = 0;
-    for (const projectId of projectIds) {
-        try {
-            const vector = await deps.getVector(projectId);
-            removed += await vector.deleteByFilter({
-                must: [
-                    { field: 'projectId', equals: projectId },
-                    { field: 'folder_ancestors', equals: PENDING_FOLDER_ANCESTOR },
-                ],
-            });
-        }
-        catch (err) {
-            deps.logger?.warn?.('pending purge failed for project', {
-                projectId,
-                error: err instanceof Error ? err.message : String(err),
-            });
-        }
-    }
-    if (removed > 0) {
-        deps.logger?.info?.('stale _pending nodes purged', {
-            projects: projectIds.size,
-            removed,
-        });
-    }
-    return { projects: projectIds.size, removed };
-}
-//# sourceMappingURL=purgePendingNodes.js.map

package/dist/src/services/purgePendingNodes.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"purgePendingNodes.js","sourceRoot":"","sources":["../../../src/services/purgePendingNodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAMH,yEAAyE;AACzE,MAAM,uBAAuB,GAAG,4BAA4B,CAAC;AAI7D,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,IAI5C;IACC,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,aAAa,CAAC,OAAO,EAAE,CAAC;IAC9C,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,+BAA+B,EAAE;YACnD,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;SACxD,CAAC,CAAC;QACH,OAAO,EAAE,QAAQ,EAAE,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,CAAC;IACrC,CAAC;IAED,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,EAAE,KAAK,EAAE,IAAI,MAAM,EAAE,CAAC;QAC/B,IAAI,KAAK,CAAC,SAAS;YAAE,UAAU,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvD,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,CAAC;IAChB,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;YAC/C,OAAO,IAAI,MAAM,MAAM,CAAC,cAAc,CAAC;gBACrC,IAAI,EAAE;oBACJ,EAAE,KAAK,EAAE,WAAW,EAAE,MAAM,EAAE,SAAS,EAAE;oBACzC,EAAE,KAAK,EAAE,kBAAkB,EAAE,MAAM,EAAE,uBAAuB,EAAE;iBAC/D;aACF,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,kCAAkC,EAAE;gBACtD,SAAS;gBACT,KAAK,EAAE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC;aACxD,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,OAAO,GAAG,CAAC,EAAE,CAAC;QAChB,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE,CAAC,6BAA6B,EAAE;YACjD,QAAQ,EAAE,UAAU,CAAC,IAAI;YACzB,OAAO;SACR,CAAC,CAAC;IACL,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,UAAU,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC;AAChD,CAAC"}