@neuralis/brain-core 0.3.2 → 0.4.0

package/package.json

@@ -1,8 +1,23 @@
 {
   "name": "@neuralis/brain-core",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "license": "FSL-1.1-ALv2",
   "homepage": "https://docs.neuralisapp.com/brain-core",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/neuralisapp/neuralis.git"
+  },
+  "bugs": {
+    "url": "https://github.com/neuralisapp/neuralis/issues"
+  },
+  "keywords": [
+    "neuralis",
+    "neuralis-package",
+    "vector-search",
+    "rag",
+    "virtual-filesystem",
+    "ai-agents"
+  ],
   "type": "module",
   "publishConfig": {
     "access": "public"
@@ -33,6 +48,18 @@
     "./upgrade/vector-proof": {
       "types": "./dist/scripts/vectorProofV1.d.ts",
       "default": "./dist/scripts/vectorProofV1.js"
+    },
+    "./upgrade/source-root-pair": {
+      "types": "./dist/scripts/sourceRootPairV1.d.ts",
+      "default": "./dist/scripts/sourceRootPairV1.js"
+    },
+    "./upgrade/source-to-folder": {
+      "types": "./dist/scripts/sourceToFolderV1.d.ts",
+      "default": "./dist/scripts/sourceToFolderV1.js"
+    },
+    "./upgrade/source-to-host": {
+      "types": "./dist/scripts/sourceToHostV1.d.ts",
+      "default": "./dist/scripts/sourceToHostV1.js"
     }
   },
   "typesVersions": {
@@ -57,25 +84,24 @@
   ],
   "dependencies": {
     "@codemirror/commands": "^6.11.1",
-    "@codemirror/language": "^6.12.4",
-    "@codemirror/merge": "^6.12.2",
+    "@codemirror/language": "^6.13.1",
+    "@codemirror/merge": "^6.12.3",
     "@codemirror/state": "^6.7.6",
-    "@codemirror/view": "^6.43.13",
-    "@iconify-json/vscode-icons": "^1.2.81",
-    "@iconify/react": "^6.0.2",
-    "@neuralis/package-system": "0.3.2",
-    "@qdrant/js-client-rest": "1.19.0",
+    "@codemirror/view": "^6.43.15",
+    "@iconify-json/vscode-icons": "^1.2.94",
+    "@iconify/react": "^6.0.3",
+    "@neuralis/package-system": "0.4.0",
+    "@qdrant/js-client-rest": "1.20.0",
     "@shikijs/engine-javascript": "^4.4.3",
     "@shikijs/langs": "^4.4.3",
     "@shikijs/themes": "^4.4.3",
     "react-diff-view": "^3.3.3",
-    "shiki": "^4.4.3",
-    "simple-git": "^4.0.2"
+    "shiki": "^4.4.3"
   },
   "peerDependencies": {
     "@aws-sdk/client-s3": "^3.975.0",
     "@aws-sdk/s3-request-presigner": "^3.975.0",
-    "@neuralis/agent-core": "0.3.2",
+    "@neuralis/agent-core": "0.4.0",
     "@tanstack/react-virtual": "^3.13.0",
     "lucide-react": "^1.47.0",
     "react": "^19.0.0",
@@ -112,7 +138,7 @@
     "@types/node": "^26.6.2",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "jsdom": "^30.1.1",
+    "jsdom": "^30.1.3",
     "typescript": "^7.0.2",
     "vitest": "^5.0.1"
   },
@@ -128,9 +154,6 @@
     "authors": [
       "Neuralis"
     ],
-    "source": {
-      "kind": "neuralis"
-    },
     "runtime": {
       "binding": "embedded",
       "hosted": {
@@ -153,15 +176,15 @@
         ]
       },
       {
-        "id": "local-disk",
-        "kind": "local",
+        "id": "host",
+        "kind": "host",
         "type": "source",
         "transport": "in-process",
-        "name": "Local Disk",
-        "description": "A folder on this machine, mounted into the workspace by absolute path — read, write, search and index its files with the fs_* tools.",
+        "name": "Host folder",
+        "description": "A folder as a source — on this server, or on a paired device through its broker — read, write, search and index its files with the fs_* tools. A device folder is attached only by the device's owner (device.own), every path is clamped by that owner's ceiling, and an offline device serves its indexed text.",
         "icon": "HardDrive",
         "category": "disk",
-        "urlScheme": "local",
+        "urlScheme": "host",
         "defaultScope": "project",
         "scopeSelectable": true,
         "allowedScopes": [
@@ -172,34 +195,73 @@
         "configSchema": {
           "type": "object",
           "additionalProperties": false,
+          "x-neuralis": {
+            "ui": {
+              "summary": "A folder on this server or one of your devices"
+            }
+          },
           "properties": {
             "root": {
               "type": "string",
               "minLength": 1,
-              "description": "Absolute or project-relative path to the directory the agent should see.",
+              "description": "The folder: on this server an absolute or project-relative path; on a device an absolute path ON THAT DEVICE (`/…`, `C:\\…` on Windows; never a UNC share), inside its owner's ceiling.",
               "x-neuralis": {
                 "ui": {
-                  "label": "Root path",
+                  "label": "Folder",
                   "control": "container-path",
-                  "placeholder": "/home/user/my-project"
+                  "placeholder": "/home/user/my-project",
+                  "deviceLabel": "Folder on the device",
+                  "devicePlaceholder": "/home/you/projects",
+                  "devicePlaceholders": {
+                    "win32": "C:\\Users\\you\\projects",
+                    "darwin": "/Users/you/projects",
+                    "linux": "/home/you/projects"
+                  },
+                  "browse": true
                 }
               }
             },
             "hostRoot": {
               "type": "string",
-              "description": "Host-side mirror of the path when running inside a container. Used by `resolveOsUri` so ide_open-style tools surface a usable host path.",
+              "description": "Host-side mirror of the path when running inside a container. Used by `resolveOsUri` so ide_open-style tools surface a usable host path. Never beside `device`.",
               "x-neuralis": {
                 "ui": {
                   "label": "Host mirror path",
                   "control": "host-path",
-                  "optional": true
+                  "optional": true,
+                  "advanced": true,
+                  "placeholder": "auto",
+                  "help": "Derived from the mount; set it only for a folder no mount names (sources.privileged)."
+                }
+              }
+            },
+            "device": {
+              "type": "string",
+              "minLength": 1,
+              "pattern": "^dev_[A-Za-z0-9]+$",
+              "description": "The paired device (`dev_…`, from `neuralis device status`) the folder lives on; absent = this server. Only that device's owner may attach a folder to it, and it never changes after the attach.",
+              "x-neuralis": {
+                "ui": {
+                  "label": "Where",
+                  "control": "select",
+                  "optionsRoute": "sources/devices",
+                  "optional": true,
+                  "emptyLabel": "This server",
+                  "help": "Your computer is not listed? Pair it first: \"Pair this computer…\" in the Neuralis app's tray, or run neuralis device pair on it.",
+                  "transport": true
                 }
               }
             }
           },
           "required": [
             "root"
-          ]
+          ],
+          "not": {
+            "required": [
+              "device",
+              "hostRoot"
+            ]
+          }
         },
         "capabilities": [
           "list",
@@ -268,7 +330,7 @@
             "exec": false
           }
         },
-        "connectorFactory": "./dist/src/connectors/LocalDiskConnector.js#createLocalDiskConnector"
+        "connectorFactory": "./dist/src/connectors/HostConnector.js#createHostConnector"
       },
       {
         "id": "brain-internal",
@@ -314,7 +376,7 @@
     "sources": [
       {
         "source": "data",
-        "kind": "local",
+        "kind": "host",
         "root": "data",
         "scope": "project",
         "seed": "auto",
@@ -375,7 +437,7 @@
       },
       {
         "source": "packages",
-        "kind": "local",
+        "kind": "host",
         "root": "_packages",
         "scope": "project",
         "seed": "auto",
@@ -604,7 +666,6 @@
         "description": "Parallel file processing during sync",
         "type": "number",
         "default": 3,
-        "envFallback": "BRAIN_SYNC_CONCURRENCY",
         "category": "brain"
       },
       {
@@ -640,7 +701,7 @@
         "label": "Embedding Request Timeout (ms)",
         "description": "Maximum time for an embedding response including its body. Raise this for slower local servers or large batches; timeout preserves payload indexing.",
         "type": "number",
-        "default": 30000,
+        "default": 120000,
         "category": "brain",
         "min": 1000,
         "max": 600000
@@ -717,7 +778,6 @@
         "description": "Queue-level cap on concurrently RUNNING sync jobs (distinct from Sync Concurrency, the per-file fan-out inside one job). Applies live to the next queue pump.",
         "type": "number",
         "default": 2,
-        "envFallback": "BRAIN_SYNC_MAX_CONCURRENT",
         "category": "brain",
         "min": 1,
         "max": 8
@@ -760,6 +820,34 @@
         "min": 30000,
         "max": 604800000
       },
+      {
+        "key": "brainSyncPollIntervalMs",
+        "label": "Sync Scheduler Interval (ms)",
+        "description": "How often the sync scheduler checks which sources are due (first sync, filter change, reconcile cadence, a device back online). Applies on restart.",
+        "type": "number",
+        "default": 60000,
+        "category": "brain",
+        "min": 5000,
+        "max": 3600000
+      },
+      {
+        "key": "brainSyncBootReconcile",
+        "label": "Sync After Start",
+        "description": "One delta sync of every auto-trigger source shortly after the app starts, so files changed while it was stopped (or left by an interrupted sync) are indexed now instead of at the next reconcile cadence. Runs through the sync queue under Sync Queue Max Jobs. Applies on restart.",
+        "type": "boolean",
+        "default": true,
+        "category": "brain"
+      },
+      {
+        "key": "brainSyncBootReconcileDelayMs",
+        "label": "Sync After Start Delay (ms)",
+        "description": "How long after start the one after-start sync runs, so it does not compete with the first page load. Applies on restart.",
+        "type": "number",
+        "default": 30000,
+        "category": "brain",
+        "min": 0,
+        "max": 600000
+      },
       {
         "key": "vectorChunkTargetChars",
         "label": "Chunk Target Size (chars)",
@@ -840,6 +928,16 @@
         "min": 1000,
         "max": 300000
       },
+      {
+        "key": "brainWatchMaxFolders",
+        "label": "Watcher Folder Budget",
+        "description": "The most folders one source's live watch walks and watches on Linux, on this server and on a device; files cost nothing, and excluded trees such as node_modules and .git are never entered. The budget bounds this watcher's walk and its memory (about 2.5 KB per folder). The kernel's own watch memory is per distinct folder on the machine, shared by every source and host that watches it, and the machine limit (fs.inotify.max_user_watches) is the real floor: past it, or past the budget, the rest of the source is not watched, the Sources panel shows the live state as partial, and changes there arrive through the regular sync reconcile. macOS and Windows watch a whole source with one handle and ignore this value. A device clamps it to its own ceiling (200 000). Applies at the next watcher acquisition.",
+        "type": "number",
+        "default": 200000,
+        "category": "brain",
+        "min": 100,
+        "max": 1000000
+      },
       {
         "key": "brainSyncMaxIndexTextChars",
         "label": "Sync Max Index Text (chars)",
@@ -853,7 +951,7 @@
       {
         "key": "brainGrepContextConcurrency",
         "label": "Grep Context Read Concurrency",
-        "description": "How many context reads a grep search may have in flight at once. Raise it on a fast local disk, lower it when a slow connector (a webtop or host plane) is the bottleneck.",
+        "description": "How many context reads a grep search may have in flight at once. Raise it on a fast local disk, lower it when a slow connector (a webtop or device plane) is the bottleneck.",
         "type": "number",
         "default": 8,
         "category": "brain",
@@ -1021,12 +1119,12 @@
       {
         "key": "brainMaxReadFileMb",
         "label": "Max Read File Size (MB)",
-        "description": "Hard cap on connector file reads — larger files fail with 'File too large' for fs_read and every read-path consumer.",
+        "description": "The one ceiling of a whole-file read, the same for a folder on this server and on a paired device — larger files fail with 'File too large' for fs_read, the Files preview and every read-path consumer. A preview's ranged request (video seeking) moves at most 8 MB per answer whatever this says. Each whole read holds the file in memory once.",
         "type": "number",
-        "default": 20,
+        "default": 100,
         "category": "brain",
         "min": 1,
-        "max": 200
+        "max": 1024
       },
       {
         "key": "inlineImageMaxMb",
@@ -1073,7 +1171,7 @@
         "label": "Content Scan Timeout (ms)",
         "description": "Kill timeout for the grep/rg/git-grep child process behind fs_search grep mode; on timeout the search fails soft with 'Search timed out'.",
         "type": "number",
-        "default": 30000,
+        "default": 120000,
         "category": "brain",
         "min": 1000,
         "max": 300000
@@ -1081,7 +1179,7 @@
       {
         "key": "brainCountCacheTtlMs",
         "label": "File Count Cache TTL (ms)",
-        "description": "Cache TTL for connector file-count walks shown in the sources UI — a fresh walk at most once per TTL per root.",
+        "description": "Cache TTL for connector file-count walks shown in the sources UI — a fresh walk at most once per TTL per root; an older count is shown at once while one walk refreshes it.",
         "type": "number",
         "default": 60000,
         "category": "brain",
@@ -1141,7 +1239,7 @@
       {
         "key": "brainListConnectorConcurrency",
         "label": "List Connector Concurrency",
-        "description": "How many source connectors a single listing walks at once. Higher finishes a multi-source listing sooner; lower is gentler on slow mounts and remote APIs.",
+        "description": "How many source connectors a single listing walks (or counts) at once. Higher finishes a multi-source listing sooner; lower is gentler on slow mounts and remote APIs.",
         "type": "number",
         "default": 4,
         "category": "brain",
@@ -1351,7 +1449,7 @@
         "label": "Git Panel Timeout (ms)",
         "description": "Inactivity cap for the on-demand whole-repo status and branch list behind the git panel. Fails soft to an empty panel.",
         "type": "number",
-        "default": 5000,
+        "default": 15000,
         "category": "brain",
         "min": 1000,
         "max": 60000
@@ -1361,7 +1459,7 @@
         "label": "Git Heavy Timeout (ms)",
         "description": "Inactivity cap for heavy on-demand git readers: per-file diff, commit DAG, blob show. Caps silence, not wall-clock — streaming output resets it.",
         "type": "number",
-        "default": 15000,
+        "default": 60000,
         "category": "brain",
         "min": 2000,
         "max": 120000
@@ -1425,10 +1523,7 @@
             "permissions": {
               "read": true
             },
-            "roles": [
-              "owner",
-              "admin"
-            ],
+            "priority": 2,
             "override": true
           },
           {
@@ -1436,10 +1531,7 @@
             "permissions": {
               "read": true
             },
-            "roles": [
-              "owner",
-              "admin"
-            ],
+            "priority": 2,
             "override": true
           },
           {
@@ -1456,10 +1548,7 @@
               "read": true,
               "write": true
             },
-            "roles": [
-              "owner",
-              "admin"
-            ],
+            "priority": 2,
             "override": true
           }
         ]
@@ -2494,7 +2583,7 @@
       }
     ],
     "access": {
-      "trust": "first-party"
+      "trust": "native"
     },
     "app": {
       "module": {
@@ -2541,6 +2630,7 @@
         {
           "kind": "dock",
           "id": "brain-core.filesystem",
+          "image": "app/shared/filesystem.png",
           "label": "Filesystem",
           "icon": "Folder",
           "color": "#60a5fa",
@@ -2593,6 +2683,7 @@
     "postbuild": "node scripts/copyContracts.mjs",
     "build:ui": "neuralis-build ui",
     "typecheck:app": "tsc -p app/tsconfig.json",
+    "typecheck:test": "tsc -p test/tsconfig.json",
     "test": "vitest run"
   }
 }

package/skills/connect-business-data/SKILL.md

@@ -40,7 +40,7 @@ retention and indexing behavior.
    vendor's official skill, MCP server or plugin (create-package
    `references/connectors-and-uri-policies.md` §The headline); build a source connector only when
    neither exists or searchable filesystem semantics are required. An outbound connector belongs
-   to ONE tenant — the platform lane for a first-party install, otherwise the owning project — so
+   to ONE tenant — the platform lane for a native install, otherwise the owning project — so
    the set you can see is the platform lane plus your own project, and an id from another project
    answers the same generic `404` as a typo. Its write surface is admin-gated: listing rides
    `core.observe`, but creating, configuring, connecting, enabling or deleting one needs
@@ -55,7 +55,7 @@ retention and indexing behavior.
 
 Use `connect` to list sources, inspect one source's health, or create a source
 from its explicit `{connection, permissions, sync?, description?, scope?,
-recognizesPackages?}` options. Use `manage-sources` for the full lifecycle,
+packageFolders?}` options. Use `manage-sources` for the full lifecycle,
 including kind/schema discovery, policy-preserving updates, sync and deletion:
 
 1. List source kinds and read the chosen kind's schema.

package/skills/create-package/SKILL.md

@@ -31,10 +31,10 @@ a human can press is half a capability.
 
 1. **Prove it does not already exist.** Mandatory, not advisory: a second skill that half-duplicates an existing one is worse than none — both match, and the model picks between them at random.
 2. **Fix before you add.** Extend the existing skill, tool or reference; a new file needs a stated reason the existing owner cannot hold it. An edit leaves the file no larger unless it says why — improve the sentence that is now wrong, never append a changelog or a "we used to think" note.
-3. **Category comes from the folder, never from frontmatter** — `skills/<name>/SKILL.md`, and flat `.md` under `rules/`, `instructions/`, `agents/`, `docs/`. A `category:` or `role:` key is ignored. And every `.md` in ALL FOUR flat categories needs `id:` or `name:` frontmatter (a non-empty string) or discovery silently skips it — ONE kernel rule (`admitsContribution`) that runs the same on an installed package, a `_packages/` drop, a synced source (where the file is indexed as a plain `file` instead) and the marketplace scanner. Exempt are only the forms whose FILENAME is the identity by protocol: `skills/<name>/SKILL.md` (id from the folder name), `commands/*.md`, the identity basenames (`AGENTS.md`, `CLAUDE.md`, `CLAUDE.local.md`, `GEMINI.md`, `.github/copilot-instructions.md`), `.cursorrules`/`.windsurfrules` and `.cursor/rules/*.mdc`. `*.agent.md` is NOT exempt.
+3. **Category comes from the folder, never from frontmatter** — `skills/<name>/SKILL.md`, and flat `.md` under `rules/`, `instructions/`, `agents/`, `docs/`. A `category:` or `role:` key is ignored. And every `.md` in ALL FOUR flat categories needs a non-empty `id:` or `name:` frontmatter or discovery silently skips it — ONE kernel rule (`admitsContribution`) that runs the same on an installed package, a `_packages/` drop, a synced source (there it is indexed as a plain `file`) and the marketplace scanner. Exempt are only the forms whose FILENAME is the identity: `skills/<name>/SKILL.md` (id from the folder name), `commands/*.md`, the identity basenames (`AGENTS.md`/`AGENTS.local.md`/`AGENT.md`, `CLAUDE.md`/`CLAUDE.local.md`, `GEMINI.md`, `.github/copilot-instructions.md`), `.cursorrules`/`.windsurfrules` and `.cursor/rules/*.mdc`. `*.agent.md` is NOT exempt.
 4. **`requiredFeatures: [a, b]` is flat.** A nested `requires:` block is read by nothing, so your gate silently does not exist.
 5. **Hidden means absent.** A caller lacking a feature never sees the skill, tool or widget, and activating it returns the same generic "not found" as a typo. Never build a "locked" state.
-6. **Trust is assigned by where the package came from, never declared by it.** `access.trust: "first-party"` in a dropped manifest changes nothing.
+6. **Trust is assigned by where the package came from, never declared by it.** `access.trust: "native"` in a dropped manifest changes nothing.
 7. **`package.json#files` must list every first-level runtime folder** (`dist`, `tools`, `workflows`, `skills`, `rules`, `instructions`, `agents`, `docs`, `team`, `hooks.json`, `app`). Omit one and it works locally and ships empty.
 8. **A tool's name is its filename; the model-visible description is the root `description` field.** A tool file with no root `description` reaches the model with none.
 9. **A widget needs a companion `kind: "dock"` surface.** A `dock:` block inside a widget is inert; without the companion the widget is unreachable and nothing warns.
@@ -67,10 +67,10 @@ system — a governed tool plus a skill teaching the craft of driving it.
 
 ### Surfaces: two renderers, one entry rule
 
-**`direct`** is compiled React that the package's own first-party host entrypoint registers — the
+**`direct`** is compiled React that the package's own native host entrypoint registers — the
 host never imports package TSX, so a `direct` surface renders only once that entrypoint is
 installed at runtime from the prebuilt module the manifest's `app.module` names
-(`neuralis-build ui`, first-party only).
+(`neuralis-build ui`, native only).
 **`iframe`** is every other path and the only one a dropped package has. Nothing else exists:
 `inline-html` and `wasm-ui` were removed and now fail validation with a migration message. WASM is
 a **tool** runtime; there is no WASM UI engine.
@@ -112,7 +112,7 @@ what your package may contain.
 |---|---|---|---|
 | Lives in | a host dependency → `node_modules/@scope/name` | `<project>/_packages/<id>/` | a folder in a synced source, in a recognised layout |
 | Who ships it | whoever controls the deploy config — **the dependency IS the trust act** | anyone who can write `_packages/` | anyone who can write the source |
-| Trust | first-party (host-assigned) | untrusted; an admin may elevate to trusted; **never** first-party | inherits the source's scope and policy |
+| Trust | native (host-assigned) | untrusted; an admin may elevate to trusted; **never** native | inherits the source's scope and policy |
 | Install step | add the dependency, restart | drop the folder (rescanned in ~half a second) | **none** — but it must be INDEXED to exist (below); once indexed it shows on the next stream |
 | Manifest | `package.json#neuralis` | `package.json#neuralis` or `neuralis.package.json` | none — the folder layout IS the anchor |
 | The five markdown categories | all five; rules inject | all five, but **rules become docs** and `prompt-context` activation is rewritten to `workspace` | all five, but **rules and identity files default OFF**, docs manual-only |
@@ -133,9 +133,9 @@ its own category, and none of them ships a skill, rule or agent you should follo
 instruction.
 
 **Column (a) has an operator loop, and it is not "restart".** An installed node package is brought
-in by the person who controls the deploy configuration — registering the dependency, and, when it
+in by the person who controls the deploy configuration — registering the dependency, and, in a Docker install where it
 points at a folder being edited rather than a registry version, mounting that folder so the
-container can see it. The first install needs a real image rebuild; after that the package can be
+container can see it. There the first install needs a real image rebuild; after that the package can be
 rebuilt and swapped into the running container in about a minute instead of ten. Those commands are
 not yours to run and not yours to document: the deployment ships its own operator runbook
 (`neuralis-operations`) which owns them, including which form applies to how it was installed.
@@ -143,7 +143,7 @@ What IS yours: declare `files` correctly, because that whitelist decides what a
 actually ships — see `references/manifest-and-discovery.md`. Columns (b) and (c) have no such loop;
 a drop is rescanned in about half a second and source markdown needs no install at all.
 
-**And a column-(a) package need not live in the host's tree at all.** A dependency can point at any directory on the deploying machine, so a package that is a product in its own right gets its own repository, its own history and its own release cadence, reached through a mount. Two things change when it does: the kernel packages become `peerDependencies` (the host already loads them — a hard dependency would give one contract two module graphs) with a relative `link:` devDependency so `tsc` still resolves, and your `tsconfig` has to inline what it used to extend. Four acts stay separate and none implies the next — git remote, mount, dependency registration, registry publish; only the third makes the package load. `references/runtime-and-build.md` §7b has the shape, including the two ways an in-container gate fails while the package itself runs perfectly.
+**And a column-(a) package need not live in the host's tree at all.** A dependency can point at any directory on the deploying machine, so a package that is a product in its own right gets its own repository, its own history and its own release cadence, reached through a mount in a Docker install. Two things change when it does: the kernel packages become `peerDependencies` (the host already loads them — a hard dependency would give one contract two module graphs) with a relative `link:` devDependency so `tsc` still resolves, and your `tsconfig` has to inline what it used to extend. Four acts stay separate and none implies the next — git remote, mount, dependency registration, registry publish; only the third makes the package load. `references/runtime-and-build.md` §7b has the shape, including the two ways an app-side gate fails while the package itself runs perfectly.
 
 **Where your files go.** A drop: `fs_write({ uri: "packages://<dir>/package.json", create: { content } })` — that URI
 is the project's `_packages/` folder, parent dirs made for you. The `packages://` path segment is
@@ -158,9 +158,9 @@ where you own them — improve those in place, never weakening a security rule y
 
 **Address it.** A source slug is its own URI scheme, so a source package lives at `<slug>://<path>`:
 a skill at `data://acme/skills/release-notes/SKILL.md` makes `data://acme` a package carrying one
-skill, id `data://acme?project=<p>&scope=project`. Every project seeds two writable local sources, `data://` and
+skill, id `data://acme?project=<p>&scope=project`. Every project seeds two writable folder sources, `data://` and
 `packages://`. Only the `<runtime_stack>` `sources` list has paths and permissions: `policy=` is your
-own read/write/exec, `os_uri=` the host path, `container=` the shell's path — printed only when the
+own read/write/exec, `os_uri=` the host path, `container=` the shell's path (on a native install the same as `os_uri`) — printed only when the
 source has one; absent, cwd the URI itself (`cwd: "data://acme"`). `fs_list` with no `uri` gives
 roots and index counts — no path, no policy. Write with `execute` (`action: "shell"`), not
 `fs_write`: it stamps `category: "file"` and captures no frontmatter, and discovery keeps only the
@@ -196,7 +196,7 @@ decide how far you get — and the two ways to put a file down are gated differe
 - **Writing with `fs_write`** (`files.write`) — absent from your inventory without it, and that
   gate governs the write tool only.
 - **Writing with the shell** (`execute` present + the source's policy, never `files.write`) — the
-  gate wants source-level `exec` on the dir you `cwd` into and `write` on every path you write, same
+  gate wants `exec` on the dir you `cwd` into (that folder's rules) and `write` on every path you write, same
   `policy=` row, uncovered paths denied. `files.write` off + `execute` on still ships.
 - **Installing or building** (`packages.author`). Without it the Build and Install actions vanish
   from the UI and those routes refuse you; code cannot be compiled, markdown needs neither.
@@ -218,7 +218,7 @@ before reporting you cannot.
 | write a `tools/*.json` or its handler | `references/tools-and-schemas.md` | the `$schema` string, the closed `x-neuralis` keys, banned inputs, result bounding |
 | build a widget, dock item, or chat card | `references/surfaces-and-design.md` | the dock companion rule, the canonical entry root, the self-contained entry, renderer × trust, the design floor |
 | write server-side code (`src/lifecycle.ts`, `src/routes/*`, `src/tools/*`) or a sandboxed package | `references/runtime-and-build.md` | the exported shape, output paths, route pattern/feature literals, the build |
-| develop a first-party package from ITS OWN repository, outside the host's tree — kernel deps, `tsconfig` with nothing to extend, where the gates actually run, and which of git / mount / dependency / publish makes it LOAD | `references/runtime-and-build.md` §7b | a hard kernel dependency giving one contract two module graphs; a `tsc` that cannot resolve inside the container while the package runs fine; assuming a pushed commit changed the deployment |
+| develop a native package from ITS OWN repository, outside the host's tree — kernel deps, `tsconfig` with nothing to extend, where the gates actually run, and which of git / mount / dependency / publish makes it LOAD | `references/runtime-and-build.md` §7b | a hard kernel dependency giving one contract two module graphs; a `tsc` that cannot resolve inside the container while the package runs fine; assuming a pushed commit changed the deployment |
 | call ANOTHER package's routes from sandboxed code (`ctx.callRoute`, the `ctx.fs.*` sugar, the per-package route catalog links) | `references/runtime-and-build.md` §6 | trusted-only, caller's real session, deny-by-default feature gates, writes land pending_review |
 | attach an external system as a data source, set path permissions — or your connector never appears in `GET /connectors` | `references/connectors-and-uri-policies.md` | the connector port contract, which project a connector registers into (and when it registers into NONE), the admin-only write gate, `sources[]`, `uriPolicies` self-namespacing |
 | need a secret, an API key, or any adjustable value | `references/config-and-credentials.md` | declare-don't-hardcode, credential scopes, shell env projection |
@@ -249,23 +249,23 @@ shell → `grep -rn "requiredFeatures" ${SKILL_DIR}/references/`.
 Two scripts do the mechanical half:
 
 ```bash
-bash ${SKILL_DIR}/scripts/check-package.sh <absolute-package-root>   # any path, before you ship
-bash ${SKILL_DIR}/scripts/verify-loaded.sh <package-id>              # any path, after
+node "${SKILL_DIR}/scripts/check-package.mjs" <absolute-package-root>   # any path, before you ship
+node "${SKILL_DIR}/scripts/verify-loaded.mjs" <package-id>              # any path, after
 ```
 
-`check-package.sh` is static, needs no server, and modes off disk: with a manifest it runs
+`check-package.mjs` is static, needs no server, and modes off disk: with a manifest it runs
 everything; with **none** it runs markdown mode — package recognition, the categories, every
 frontmatter gate — then prints the manifest/tools/workflows/surfaces/runtime/dist checks it skipped,
-so no skip reads as a pass. `verify-loaded.sh` covers all three paths (for (c) pass
+so no skip reads as a pass. `verify-loaded.mjs` covers all three paths (for (c) pass
 `<rootUri>?project=<p>&scope=…`) and reads package diagnostics, so it needs `core.observe` — lacking that it
 reports it could not reach them rather than claiming the package is absent.
 
 **Enable, trust, install and rescan apply from the NEXT stream.** A stream captures the set of
 packages it may use once, at its start: a package you just enabled, trusted or installed becomes
 activatable in the next stream — a new user message, a workflow run, a fresh conversation — never
-mid-turn. A delegate spawned after the change sees its `<packages>` entry, injected
+mid-turn. A foreground delegate spawned after the change sees its `<packages>` entry, injected
 rules/instructions and agent resolution fresh, but its tool catalog and skill activation still
-use the parent stream's gate. A `Skill not found` in
+use the parent stream's gate; a background delegate re-reads all of them at its wake. A `Skill not found` in
 the same continuous turn that flipped the package is this rule, not a broken package: retry from
 a fresh stream before re-diagnosing.