@neuralis/brain-core 0.4.0 → 0.4.1

package/skills/manage-files/SKILL.md

@@ -38,7 +38,7 @@ server-side **403** from `search` even though the other routes work.
 ## Bodies
 
 - `list` / `search` / `read` / `approve` / `write` take a JSON body on stdin (`echo '<json>' | neuralis request POST @neuralis/brain-core/<route> --input -`, the one form bash and PowerShell both parse; a `'` inside the text is written `\u0027` in the JSON); file content and other free text ride that body, never a `-f` argument (PowerShell strips the quotes inside an argument).
-- `/write` body = `{"agentId":"…","uri":"data://notes/plan.md","<verb>":…}` — the VERB is a KEY and its presence is the intent. Content verbs COMPOSE in one call, in a fixed order, as ONE write with ONE baseline: `create` (`{content, client_request_id?}` — never overwrites; a taken name lands BESIDE as `name-2.ext` and the response `uri` is where it went, so read it back), `overwrite` (`{content}` — refuses on a missing file and names `create`), `edit` (`[{old_string, new_string?, replace_all?, expected_replacements?}]`, applied in order, one failure discards all of them), `insert` (`{insert_text, insert_line?}` — inserts AFTER that line, `0` = start of file, omitted = append), `lines` (`{line_start, line_end, content}`), `fields` (`{category, status, pinned, tags{add,remove,set}, metadata}`). Structural verbs stand ALONE: `move`/`copy` (a destination uri or, for a file move, a bare new filename; `copy` may cross sources), `mkdir:true` (a real empty directory; not on `brain://`, where folders are implicit), `revert:true` (one-level undo), `delete:true` (a file, or a whole folder recursively). **A 2xx does not mean success** — a refusal is 200 with `ok:false` and the CLI exits 0, so branch on `ok`, never the status or the exit code. A `move` (or a `revert` that relocates or re-creates) onto a uri that already holds something answers `ok:false` + `error:"DESTINATION_EXISTS"` — nothing was overwritten; delete or rename the occupant first. A delete has ONE spelling, the `delete` key: `fields.status:"deleted"` is refused. `review` is never read from the body — a content edit (`overwrite`/`edit`/`insert`/`lines`) lands `pending_review` on every lane (visible and revertible in Changes); `create`/`move`/`copy`/`mkdir` land committed for a human interactive caller and `pending_review` from this ticket lane; `/upload` also journals agent-origin uploads as pending review; interactive human uploads land committed. Use `/write` for JSON text and `/upload` for multipart file bytes. A missing `agentId`/`uri` is a **400** naming the field, a body the server could not parse a **400** `Request body must be a JSON object`. A uri-policy denial is a **403 with no `ok` field**, a disabled source a **409** with `code:"source_disabled"`. A source slug this project does not have answers one of two ways, and BOTH mean "stop guessing this name": with a scheme (`zzz://a.md`) the uri gate answers **403 `uri_policy_denied`** first; without one (`notes.md`) you get **404 `code:"source_not_configured"`** carrying `availableSources` — the sources you CAN address. `/list` gives the 404 in both forms. Switch to a source from that list (or from `<runtime_stack>`); retrying the same name never works. `/read` is different again: it reports PER FILE inside a 200, so a denied or disabled source arrives as `{uri, error, code:"forbidden"}` — never a 409 — a missing file as `code:"not_found"`, and a device folder that cannot serve as `code:"source_unavailable"` or `"device_refused"` with a `reason` (`device_not_ready` adds `not_ready`: what the device's owner fixes there). No code means the read failed for some other reason; do not conclude the file is gone. A folder delete or copy that partly succeeded reports what really happened: `affected` (files touched) and `failed` (the NAMES that could not be), so "failed" does not mean "nothing happened". `warning:"moved_with_source_retained"` on a move means the copy landed but the original could not be removed — BOTH copies exist on purpose; do not re-run the move. `indexed:false` means the bytes DID land and are readable, but search indexing was skipped or failed; report it, do not re-write. Sync retries failed indexing only for eligible files; excluded files remain unindexed. A non-2xx prints the route's body too — on stderr, followed by an `HTTP <code>` line, under a `--- stderr ---` separator, so read the whole output.
+- `/write` body = `{"agentId":"…","uri":"data://notes/plan.md","<verb>":…}` — the VERB is a KEY and its presence is the intent. Content verbs COMPOSE in one call, in a fixed order, as ONE write with ONE baseline: `create` (`{content, client_request_id?}` — never overwrites; a taken name lands BESIDE as `name-2.ext` and the response `uri` is where it went, so read it back), `overwrite` (`{content}` — refuses on a missing file and names `create`), `edit` (`[{old_string, new_string?, replace_all?, expected_replacements?}]`, applied in order, one failure discards all of them), `insert` (`{insert_text, insert_line?}` — inserts AFTER that line, `0` = start of file, omitted = append), `lines` (`{line_start, line_end, content}`), `fields` (`{category, status, pinned, tags{add,remove,set}, metadata}`). Structural verbs stand ALONE: `move`/`copy` (a destination uri or, for a file move, a bare new filename; `copy` may cross sources), `mkdir:true` (a real empty directory; not on `brain://`, where folders are implicit), `revert:true` (one-level undo), `delete:true` (a file, or a whole folder recursively). **A 2xx does not mean success** — a refusal is 200 with `ok:false` and the CLI exits 0, so branch on `ok`, never the status or the exit code. A `move` (or a `revert` that relocates or re-creates) onto a uri that already holds something answers `ok:false` + `error:"DESTINATION_EXISTS"` — nothing was overwritten; delete or rename the occupant first. A delete has ONE spelling, the `delete` key: `fields.status:"deleted"` is refused. `review` is never read from the body — a content edit (`overwrite`/`edit`/`insert`/`lines`) lands `pending_review` on every lane (visible and revertible in Changes); `create`/`move`/`copy`/`mkdir` land committed for a human interactive caller and `pending_review` from this ticket lane; `/upload` also journals agent-origin uploads as pending review; interactive human uploads land committed. Use `/write` for JSON text and `/upload` for multipart file bytes. A missing `agentId`/`uri` is a **400** naming the field, a body the server could not parse a **400** `Request body must be a JSON object`. A uri-policy denial is a **403 with no `ok` field**, a disabled source a **409** with `code:"source_disabled"`. A source slug this project does not have answers one of two ways, and BOTH mean "stop guessing this name": with a scheme (`zzz://a.md`) the uri gate answers **403 `uri_policy_denied`** first; without one (`notes.md`) you get **404 `code:"source_not_configured"`** carrying `availableSources` — the sources you CAN address. `/list` gives the 404 in both forms. Switch to a source from that list (or from `<runtime_stack>`); retrying the same name never works. `/read` is different again: it reports PER FILE inside a 200, so a denied or disabled source arrives as `{uri, error, code:"forbidden"}` — never a 409 — a missing file as `code:"not_found"`, and a device folder that cannot serve as `code:"source_unavailable"` or `"device_refused"` with a `reason` (`device_not_ready` adds `not_ready`: what the device's owner fixes there). No code means the read failed for some other reason; do not conclude the file is gone. `code:"vector_store_unavailable"` (per file on `/read`, `ok:false` on `/write`, a **503** elsewhere) means the index is not available yet: a new file on a folder source still lands, a `brain://` file, an edit, move or delete waits — nothing was changed; retry later. A folder delete or copy that partly succeeded reports what really happened: `affected` (files touched) and `failed` (the NAMES that could not be), so "failed" does not mean "nothing happened". `warning:"moved_with_source_retained"` on a move means the copy landed but the original could not be removed — BOTH copies exist on purpose; do not re-run the move. `indexed:false` means the bytes DID land and are readable, but search indexing was skipped or failed; report it, do not re-write. Sync retries failed indexing only for eligible files; excluded files remain unindexed. A non-2xx prints the route's body too — on stderr, followed by an `HTTP <code>` line, under a `--- stderr ---` separator, so read the whole output.
 - `/search` body key is `search_mode` (semantic|filter|grep) — the SAME vocabulary as the `fs_search` tool; the legacy `mode` key is rejected with 400. The route forwards `search_mode`, `query`, `folder_uri`, `glob`, `category`, `tags`, `status`, `created_after`/`created_before`, `limit`, and the grep-only `path_glob`, `context` and `case_sensitive`. In `grep` mode the search is uri-policy `read`-gated (only paths the caller holds `read` policy on are grepped), the match is a FIXED STRING, and the answer carries `truncated` + `total_seen` — a cut set says so, so never read a full-looking list as proof that the rest is absent.
 - `/raw` is a GET — pass the file URI as `-f uri=<uri>` and redirect stdout to a file: it always returns the full bytes, unaffected by the response headers; what those headers say is a BROWSER instruction. Safe types (images except SVG, video, audio, PDF, text, JSON) are marked for inline display; SVG, HTML and XML are marked `attachment` so a person clicking the link downloads them instead of executing them on the app origin. Do not describe a `.svg` or `.html` you wrote as viewable in the browser — offer it as a download, or convert it to a raster image if a human needs to look at it.
 - `/read` is at parity with the `fs_read` tool: the body takes `files[]` — each entry a URI string or `{"uri":"…","line_start":N,"line_end":M}` with that file's own window — plus `read_version`, batch-level `line_start`/`line_end` and `include_ids`. An entry that is neither shape is a **400**. Text is a bounded preview; native media may accompany it, while unsupported/invalid binary data has a URI and marker. For a byte-exact binary copy use the authorized `/raw` byte lane and multipart `/upload`, never re-encode a text preview. If you only need the pre-edit content, a plain `/read` response already carries it: each file's `version.baseline.content`, with `available_versions` listing `baseline` exactly when one exists.

package/skills/sync/SKILL.md

@@ -13,7 +13,7 @@ Trigger a delta sync for the brain-core filesystem.
 
 1. Use `fs_list` with no `uri` first to identify configured sources, scopes, current sync status, and recent errors.
 2. Call the brain-core source sync route for the intended source. The route answers 202 + a queue job snapshot — the sync runs in the background. Explicit sync requires `sources.sync`; source create/update/delete uses `sources.mount`; file writes use `files.write`.
-3. Poll `GET /sources/sync-status?source=<slug>` until the job finishes, then report the job `result` counts: `filesAdded`, `filesUpdated`, `filesRemoved`, `filesSkipped`, `filesMoved`, `chunksRemoved`, `chunksEmbedded` and `chunksSkipped` plus `embeddingDegraded` (safe, deduplicated embedding stop reasons). Payload indexing can succeed with missing/stale embeddings; report that debt separately. Read the two flags before interpreting completion. `cancelled: true` is not a failure, but the run stopped early: the counts are partial and a re-run converges. `truncated: true` means the walk stopped at `filesScanCap`, so files past the cap were never examined and no deletion or move was inferred — call that a partial pass, never a completed sync.
+3. Poll `GET /sources/sync-status?source=<slug>` until the job finishes, then report the job `result` counts: `filesAdded`, `filesUpdated`, `filesRemoved`, `filesSkipped`, `filesMoved`, `chunksRemoved`, `chunksEmbedded` and `chunksSkipped` plus `embeddingDegraded` (safe, deduplicated embedding stop reasons). Payload indexing can succeed with missing/stale embeddings; report that debt separately. Read the two flags before interpreting completion. `cancelled: true` is not a failure, but the run stopped early: the counts are partial and a re-run converges. `truncated: true` means the walk stopped at `filesScanCap`, so files past the cap were never examined and no deletion or move was inferred — call that a partial pass, never a completed sync. A job that stays `pending` while other calls answer `vector_store_unavailable` is held for the vector store: it runs by itself when the store is back — stop polling and report it as waiting, never as failed.
 4. If any errors occur, list them clearly with the affected source, scope, and file path. Two job errors are fixed codes and removed nothing: `root_unreachable` (the source root cannot be reached — unmounted, renamed, device offline; fix the mount, then sync again) and `root_empty` (the root answers but holds no file while the index still holds some). Re-send `confirmEmpty:true` with the sync only after the user confirms the folder really is empty — that one pass removes its files from the index.
 5. Distinguish live connector data, indexed payload and embedding freshness. Provider outage or disabled embedding preserves metadata/full-text indexing; semantic results may be old, or the response may fall back to filter search. Ordinary sync completion does not settle all embedding debt. Use `manage-sources` explicit debt catchup; terminal `paused` carries `result.embedding.pausedReason`, and Resume creates a new authorized job from durable debt.