@neuralis/brain-core 0.3.1 → 0.4.0

package/rules/brain-rules.md

@@ -16,7 +16,7 @@ activation:
 3b. **The ladder, once:** `fs_list` = the SHAPE of a place you can name · `fs_search` = FINDING one you cannot · `fs_read` = the CONTENT once you can · `execute` = when you need a PROGRAM, never because you skipped the three. `<runtime_stack>` `data_areas` names where each package keeps its files; start there.
 4. **Presence and index state differ.** `unindexed` content is live but not semantically searchable; `stale_indexed` stays indexed after its connector entry disappeared **or after the connector failed to answer** — neither proves a file is gone.
 
-Tool descriptions own the choice among list/search/read/write; follow their discovery and recovery hints. Schemes, listing states and source mechanics live in `drive-overview`; the model itself in the on-demand `brain-model` (read both via `files/content`).
+Tool descriptions own the choice among list/search/read/write; follow their discovery and recovery hints. `<runtime_stack>` names the live sources and their schemes; the model itself is in the on-demand `brain-model` (read it via `files/content`).
 
 ## Writes
 
@@ -28,7 +28,7 @@ Tool descriptions own the choice among list/search/read/write; follow their disc
 
 ## Security floor
 
-10. **Paths are policy-gated.** Every URI is checked for read/write/exec; uncovered paths deny by default, shell included. Never build an alternate path to evade policy. `manage-uri-policy` is the way to a narrower exception: reading one needs `drive.read`, changing one escalates to `drive.policy` — no grant below `admin`.
+10. **Paths are policy-gated.** Every URI is checked for read/write/exec; uncovered paths deny by default, shell included. Never build an alternate path to evade policy. `manage-uri-policy` is the way to a narrower exception: reading one needs `files.read`, changing one escalates to `sources.policy` — no grant below `admin`.
 11. **Scope is enforced.** Files are scoped by user, project and agent; another identity's subtree is not yours, and routes reject cross-scope access.
 12. **Source state is three-valued.** No config → `source_not_configured`, and the reply lists the sources you CAN address, so pick one instead of retrying. Configured but off → `source_disabled`, whatever the policy allows. On → policy decides. **Which one you SEE depends on the call:** a schemed name hits the path gate first, and a read reports per file inside a success. Check `<workspace_live>` before diagnosing absence.
 13. **Host paths are optional.** A source may have no `os_uri`: address it by URI, never a made-up OS path.

package/skills/brain-start/SKILL.md

@@ -1,5 +1,5 @@
 ---
-requiredFeatures: [drive.read]
+requiredFeatures: [files.read]
 name: brain-start
 description: "Survey an unfamiliar workspace and recommend evidence-based next steps: inspect live sources, index health, packages, and useful existing material before creating anything. Use for “what is here or where should we start?” requests, not as a substitute for executing a specific task."
 allowed-tools: fs_search fs_list fs_read

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

@@ -1,5 +1,5 @@
 ---
-requiredFeatures: [drive.read]
+requiredFeatures: [files.read]
 name: connect-business-data
 description: "Connect governed organisation or personal data — files, exports, records, APIs, databases, MCP services — deciding ownership, storage, scope, policy, retention and copy permission first. Use before real business-data work; sync/index the source and build capabilities around it without copying datasets into identity or memory."
 allowed-tools: execute, connect
@@ -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.
-4. **`requiredFeatures: [a, b]` is flat.** The nested `requires:` form parses to nothing and your gate silently does not exist.
+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
@@ -179,8 +179,8 @@ ever is a contribution. The source needs no opt-in flag.
 absent, with no error. `data://` and `packages://` index themselves seconds after a disk change —
 the whole step. Any other source needs a sync:
 `neuralis request POST @neuralis/brain-core/sources/sync -f source=<slug>` — it needs
-`drive.sync`, and **no tool syncs.** Lacking it, do not route
-around the gate — ask: files on disk, `drive.sync` named, Files widget → Sources → `<slug>` →
+`sources.sync`, and **no tool syncs.** Lacking it, do not route
+around the gate — ask: files on disk, `sources.sync` named, Files widget → Sources → `<slug>` →
 **Sync** offered, in the words `references/test-and-ship.md` prescribes.
 
 Reach paths in full:
@@ -193,19 +193,19 @@ This skill is open to everyone: you must know *why* something does not work. Fiv
 decide how far you get — and the two ways to put a file down are gated differently. Missing one?
 **Name it and stop**; never retry a denied call or route around it.
 
-- **Writing with `fs_write`** (`drive.write`) — absent from your inventory without it, and that
+- **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 `drive.write`) — the
-  gate wants source-level `exec` on the dir you `cwd` into and `write` on every path you write, same
-  `policy=` row, uncovered paths denied. `drive.write` off + `execute` on still ships.
+- **Writing with the shell** (`execute` present + the source's policy, never `files.write`) — the
+  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.
 - **Reading package diagnostics** (`core.observe`). Without it that response is forbidden. For an
   installed package fall back to the server log naming your id; for a source package there is no
   log line at all — read the source-package entries in your own `<packages>` block instead.
-- **Indexing a source** (`drive.sync`) — only on a manual-trigger source; lacking it, ask as above.
+- **Indexing a source** (`sources.sync`) — only on a manual-trigger source; lacking it, ask as above.
 
-**Path (c) needs no install, no build, no `packages.author`, no `drive.write`** — the shell gate
+**Path (c) needs no install, no build, no `packages.author`, no `files.write`** — the shell gate
 above, plus an indexing path. Proving it landed wants `core.observe` too. Find what you *can* reach
 before reporting you cannot.
 
@@ -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.
 

package/skills/create-package/references/config-and-credentials.md

@@ -48,13 +48,13 @@ Effective value cascade, exactly three steps: **platform file override → `envF
 - **`envFallback` is ignored for `type:"json"`** (validation warning; the administrator sets the env var and nothing changes), and **`type:"json"` rows are excluded from the flat settings list** — the key still reads through the cascade, it is just not on the list.
 - **`category: "vector"` is filtered out of the flat Platform Settings list** — a dedicated Vector section owns it, so any non-embedding key you file there is invisible in the admin UI.
 - **Secret-shaped names are warned, not blocked.** A `key` or `envFallback` matching `secret|token|passw|credential|apikey|api_key|private` produces a manifest warning — and the value still renders as plaintext. Declare a credential instead.
-- **Do not invent an `envFallback`.** It projects an arbitrary environment variable's VALUE into administrator-visible state — which is exactly why `configSettings[]` is honoured for **first-party** packages only.
+- **Do not invent an `envFallback`.** It projects an arbitrary environment variable's VALUE into administrator-visible state — which is exactly why `configSettings[]` is honoured for **native** packages only.
 
 **Declaration is not a grant.** A row registers a schema entry on the feature-gated admin Config surface. It gives your package no write authority over anything.
 
 ## Task — read a config value in your code
 
-`ctx.config.get(key)` reads a declared platform setting live. Every first-party key is registered before `init`; an undeclared key throws. Reads below host-assigned first-party trust are denied.
+`ctx.config.get(key)` reads a declared platform setting live. Every native key is registered before `init`; an undeclared key throws. Reads below host-assigned native trust are denied.
 
 ```ts
 import type { PackageInitContext } from '@neuralis/package-system/contracts';
@@ -80,8 +80,8 @@ The shape is exactly `{ id, label, category?, oauth? }` — `id` and `label` req
 
 - **`id` must pass `^[A-Za-z_][A-Za-z0-9_.-]*$`, at most 128 chars.** The id becomes an `<id>.enc.json` path segment, so a slash, whitespace or a leading dot is rejected — an id can never escape its scope directory. Duplicate ids in one manifest, a missing `id`/`label`, or a non-object entry all fail validation with a named error.
 - **Declare only what something RESOLVES.** A catalog row an owner fills in that no code reads is worse than no row — the operator believes the key is configured while the feature stays dark. A drift guard asserts declarations and consumers match **in both directions**, so a dead declaration fails the build. Boot-critical infrastructure read from the environment (a vector-DB key wired before any credential can be decrypted) belongs in `.env`, not here.
-- **Reserved namespaces are first-party-only.** The git (`git.<host>.pat`, `git.<host>.oauth.*`), channel, and MCP (`mcp.<server>.*`) id classes have host-owned resolution semantics — a resolver reads them at a member's OWN scope on that member's behalf — so a non-first-party manifest declaring one is a **validation error, not a warning**: unlike a retired key, it fails the manifest and the package does not load. Squatting `git.github.com.pat` would otherwise put a token an owner filled in at global scope into the cascade for every member without their own. Declare ids in your own namespace (`acme.apiKey`).
-- **The catalog is dynamic**: the union of package `credentials[]`, every installed skill's `credentials:` frontmatter, and ids already stored by hand. Entries carry only `hasValue`, never the value. There is **no visibility trust gate** — your package's own ids appear at any trust tier, or an owner could never set them. Trust governs ATTRIBUTION instead: a first-party declaration wins the label/category, a later declarer only joins the `declaredBy` list, and the UI renders the trust tier next to a non-first-party declarer.
+- **Reserved namespaces are native-only.** The git (`git.<host>.pat`, `git.<host>.oauth.*`), channel, and MCP (`mcp.<server>.*`) id classes have host-owned resolution semantics — a resolver reads them at a member's OWN scope on that member's behalf — so a non-native manifest declaring one is a **validation error, not a warning**: unlike a retired key, it fails the manifest and the package does not load. Squatting `git.github.com.pat` would otherwise put a token an owner filled in at global scope into the cascade for every member without their own. Declare ids in your own namespace (`acme.apiKey`).
+- **The catalog is dynamic**: the union of package `credentials[]`, every installed skill's `credentials:` frontmatter, and ids already stored by hand. Entries carry only `hasValue`, never the value. There is **no visibility trust gate** — your package's own ids appear at any trust tier, or an owner could never set them. Trust governs ATTRIBUTION instead: a native declaration wins the label/category, a later declarer only joins the `declaredBy` list, and the UI renders the trust tier next to a non-native declarer.
 - **Declaration is not a grant here either.** A row is catalog metadata; it confers no write authority, and consumption still resolves against the caller's real scope.
 - **`oauth: true` is a DISPLAY hint only** — it changes admin chrome to Connect/Disconnect. It gives you no OAuth flow, and on an unwired provider the row is a dead button.
 
@@ -112,19 +112,22 @@ description: Fetch a city forecast via the Weather API.
 credentials:
   - WEATHER_API_KEY
 ---
-Run: `bash ${SKILL_DIR}/scripts/forecast.sh "$CITY"`
+Run: `node "${SKILL_DIR}/scripts/forecast.mjs" "$CITY"`
 ```
 
-```bash
-# skills/forecast/scripts/forecast.sh
-set -euo pipefail
-: "${WEATHER_API_KEY:?not configured — set it under Credentials}"
-curl --fail-with-body -sS -H "Authorization: Bearer $WEATHER_API_KEY" "https://api.weather.example/v1/forecast?q=$1"
+```js
+// skills/forecast/scripts/forecast.mjs
+const key = process.env.WEATHER_API_KEY;
+if (!key) { process.stderr.write('WEATHER_API_KEY is not configured — set it under Credentials\n'); process.exit(2); }
+const res = await fetch(`https://api.weather.example/v1/forecast?q=${encodeURIComponent(process.argv[2] ?? '')}`, { headers: { Authorization: `Bearer ${key}` } });
+const body = await res.text();
+if (!res.ok) { process.stderr.write(`HTTP ${res.status}\n${body}\n`); process.exit(1); } // keep the error body
+process.stdout.write(body);
 ```
 
 On activation the host resolves each declared id at the caller's real `(userId, projectId, agentId)` scope, within the caller's tier ceiling: own user key always; agent and project keys with `project.credentials.write`; global with `platform.scope` too. A tier above it reads as missing, so a member's run needs the member's own key (`credentials.self`). **The model never sees a resolved value.**
 
-- **`credentials:` must be a list of plain strings.** A scalar or a list of objects is dropped silently by the whitelist frontmatter parser: the skill activates normally, the catalog shows no ids, and your script exits on the `${VAR:?…}` guard with no parse error anywhere.
+- **`credentials:` must be a list of plain strings.** A scalar or a list of objects is dropped silently by the whitelist frontmatter parser: the skill activates normally, the catalog shows no ids, and your script exits on its missing-key guard with no parse error anywhere.
 - **A missing value is non-fatal.** The id lands on a `missing` list, the rendered body carries a `(missing: <id>)` marker, and no variable is set — which is why scripts should fail with a message pointing the user at the Credentials surface.
 - **Sanitise exactly once.** Pass `env` and the allow-list straight through to the shell runner. A second defensive sanitise pass has no allow-list and strips exactly the credential keys that were just projected — and the symptom, "the credential is configured but the script says it is missing", sends you debugging the wrong layer.
 - **The allow-list applies to the OVERRIDES side only.** It never un-strips a same-named variable already present in the host process environment. That is deliberate: a leaked host secret must not piggyback on an allow-listed name.
@@ -153,10 +156,10 @@ Never inline a secret in a manifest or a source config file, and never default-a
 ## What works on which reach path
 
 - **Installed package (in-process):** the only path where both halves work fully. Trust comes from being installed, so keys register at boot, the Config tab shows your package as declarer, `ctx.credentials` is available, and skill `credentials:` projects into script environments.
-- **Project `_packages/` drop (sandboxed, untrusted):** `configSettings[]` is **silently dropped** — the only trace is a `config.declaration_skipped` warning, nothing fails at install time, and the first `get()` throws `Config key not registered`. The sandbox bridge exposes no config and no credential host function at all, so declared `credentials[]` still show in the catalog but sandboxed code cannot read a value. Take tunables as tool inputs or from your own data files, and do not plan on secret access. **An admin can elevate a dropped package to `trusted`, never to first-party** — the drop path pins `untrusted` and the elevation channel has no first-party value — so neither array ever comes back on this path. If you need declared config or credential access, ship the package on the installed path instead.
+- **Project `_packages/` drop (sandboxed, untrusted):** `configSettings[]` is **silently dropped** — the only trace is a `config.declaration_skipped` warning, nothing fails at install time, and the first `get()` throws `Config key not registered`. The sandbox bridge exposes no config and no credential host function at all, so declared `credentials[]` still show in the catalog but sandboxed code cannot read a value. Take tunables as tool inputs or from your own data files, and do not plan on secret access. **An admin can elevate a dropped package to `trusted`, never to native** — the drop path pins `untrusted` and the elevation channel has no native value — so neither array ever comes back on this path. If you need declared config or credential access, ship the package on the installed path instead.
 - **Source markdown package (no install step):** no manifest, so neither array exists on this path. Per-skill `credentials:` frontmatter still works exactly as above — a source-package skill can shell out with a secret in its environment; it just cannot declare a tunable or a catalog row of its own.
 
 ## Going deeper
 
 - Configuration tiers and the cascade: <https://docs.neuralisapp.com/enterprise/configuration>
-- Credential scopes, the dynamic catalog and the encrypted store: <https://docs.neuralisapp.com/enterprise/credentials>
+- Credential scopes, the dynamic catalog and the encrypted store: <https://docs.neuralisapp.com/package-system/credentials>

package/skills/create-package/references/connectors-and-uri-policies.md

@@ -28,6 +28,9 @@ The dataset lives only behind the configured source/connector. An arbitrary writ
   { "id": "acme-mcp", "type": "mcp", "transport": "stdio", "command": "npx",
     "args": ["-y", "@acme/mcp-server"],
     "auth": { "type": "env-vars", "envVarName": "ACME_TOKEN" } },
+  { "id": "acme-remote", "type": "mcp", "transport": "streamable-http",
+    "url": "https://mcp.acme.test/mcp", "name": "Acme", "description": "Orders and invoices",
+    "auth": { "type": "oauth2", "scopes": ["read"] } },
   { "id": "acme-api", "type": "openapi",
     "openApiSpec": "https://api.acme.test/openapi.json",
     "openApiOperationFilter": { "include": ["listOrders", "getOrder"] },
@@ -41,18 +44,19 @@ The dataset lives only behind the configured source/connector. An arbitrary writ
 - `auth.type` is closed: `none | api-key | bearer-token | basic | oauth2 | oauth2-pkce | env-vars`. `env-vars` is the one for a stdio MCP subprocess — decrypted values go into the child process env.
 - **Secrets are collected through `auth.setupFields[]`** (shape in `references/config-and-credentials.md`). There is no `credentialRef` auth field; writing one collects nothing and the connector starts unauthenticated.
 - A `type: "source"` entry is handled only by the source pipeline; the outbound lifecycle skips it.
+- **A remote `mcp` row is offered to the user, never auto-connected.** It needs `transport: "streamable-http"` and a `url` (a package fails validation otherwise; `stdio` + `command` is the trusted sidecar form above), and it is never registered as a connector. Every agent whose owner may see the package — its base-access feature, and the package switched on for that agent — gets it under Connections → MCP servers as "Offered by <package>" (and as an `offered` row of `connect {list:{kind:"mcp"}}`); Add, or `connect {add:{kind:"mcp", offer:"<packageId>#<connectorId>"}}`, adopts it as that agent's own MCP server and signs in through the server's OAuth (discovery, dynamic client registration, PKCE). Only `url`, `name`, `description`, `icon` and `auth.scopes` are read; `auth.type` is `oauth2`, `oauth2-pkce` or `none`, and any other type is not offered. No MCP request reaches the server before the user signs in (the sign-in reads its OAuth metadata and registers a client), no Neuralis identity header is ever sent, and an adopted server stays the user's when the package is later switched off.
 
 ### Which tenant an outbound connector registers into
 
 A `connectors[]` entry is **not** registered once for the whole deployment. It lands in exactly one **partition**, and which one is decided by how the package reached the host — never by anything you can write in the manifest:
 
-- **Installed package, first-party** → the **platform lane**. One registration, visible in every project on the deployment. It is the only lane a package with no owning project may reach.
+- **Installed package, native** → the **platform lane**. One registration, visible in every project on the deployment. It is the only lane a package with no owning project may reach.
 - **Project `_packages/` drop** → **that project's own partition**. The connector exists for that project and nowhere else; two projects dropping the same package get two independent connectors with independent config, status and health.
-- **No resolvable owning project and not first-party → NOTHING is registered.** Fail-closed on purpose: the only partition left would be the platform lane, which every project can see. **This is the first thing to check when a connector "disappeared"** — the package loads clean, `check-package.sh` is happy, the manifest is valid, and `GET /connectors` simply never lists it. The only trace is the server line `Connector registration refused: unresolved owning project`. Nothing in the manifest will fix it; find why the package has no owning project.
+- **No resolvable owning project and not native → NOTHING is registered.** Fail-closed on purpose: the only partition left would be the platform lane, which every project can see. **This is the first thing to check when a connector "disappeared"** — the package loads clean, `check-package.mjs` is happy, the manifest is valid, and `GET /connectors` simply never lists it. The only trace is the server line `Connector registration refused: unresolved owning project`. Nothing in the manifest will fix it; find why the package has no owning project.
 
 Reads follow the same partition. `GET /connectors` answers with the caller's own visibility — the platform lane UNION their project — and an id-addressed call resolves own-project first, then platform. An id belonging to **another** project answers the same generic **`404 Not found`** as an unknown id or a malformed one: the three are deliberately indistinguishable, so no caller can enumerate another project's connector ids out of the error text. Do not build a retry, a fallback or a "does it exist elsewhere" probe on that 404 — it will never become a more specific code.
 
-Tools follow it too: a connected remote-MCP connector's tools are merged into the sessions of its own tenant — the platform lane's into every project, a project's into that project alone.
+A remote MCP row never takes this path: it is an offer each agent adopts (above), so its tools reach exactly the agents that added it.
 
 **Reading is not writing.** Listing connectors, reading one's health and reading its resolved tools ride the module's `core.observe`. Every MUTATING arm — create, delete, configure, connect, disconnect, enable, disable — additionally requires the **`core.connectors`** feature — granted to `admin` by default, reached by an owner-strength role through its `'*'` wildcard, and held by no one else. A caller who can SEE a connector row and gets `403 Forbidden` on Connect is looking at that gate, not at a broken connector: name the feature and stop. Never retry it, and never reach for another identity.
 
@@ -93,16 +97,26 @@ None of this touches a `type: "source"` entry. A filesystem kind is registered a
 1. **Omitting `"additionalProperties": false` is PERMISSIVE, not rejecting.** Arbitrary unvalidated keys land in your factory's `config`; the rejection you assumed was happening never happens.
 2. **It is a hand-rolled draft-07 SUBSET.** Supported: top-level `type: "object"`, `required`, `additionalProperties: false`, and per-property `type`, `enum`, `const`, `minLength`, `maxLength`, `pattern`, `minimum`, `maximum`, `items`. Everything else — `$ref`, `oneOf`/`anyOf`/`allOf`, `format`, `dependencies`, nested object schemas — is **silently ignored**: no error, no warning, invalid config reaching your factory as a type crash deep inside the connector. Keep the form flat.
 
-3. **A `root` property must say WHICH PLANE it is on.** The Add-Source form renders every field
-   from its declared `x-neuralis.ui`, and `root` is where the chrome differs:
-   `"control": "container-path"` means the path lives in the CONTAINER filesystem, so the form
-   offers the `/mounts` volume picker, the `neuralis mount add` callout and the Browse button;
-   `"control": "host-path"` means it lives on the operator's machine (reached through the host
-   broker), so it gets none of them — Browse least of all, because `GET /sources/browse` readdirs
-   in the SERVER process, which is the wrong machine for a host root. The bare legacy
-   `"control": "path"` still works and is treated as container-plane. Declare `label` and
-   `placeholder` too: the form uses yours, and a kind that declares neither renders a bare `Path`
-   with an empty placeholder.
+3. **A `root` property declares `"control": "container-path"`** (the bare legacy `"path"` still
+   works the same): the path lives on the app's own machine — in a Docker install the container,
+   where the form suggests the `/mounts` binds and the `neuralis mount add` callout; on a native
+   install only the project's own folder, any other folder being attached on the user's paired
+   device. `"browse": true` offers the folder picker. Declare `label` and `placeholder` too: the
+   form uses yours, and a kind that declares neither renders a bare `Path` with an empty
+   placeholder. One kind may serve both planes: a field marked `"transport": true` (the `host`
+   kind's `device`) renders BEFORE the root and, while it holds a value, turns the root into a path
+   on that device — your `deviceLabel`/`devicePlaceholder` (or a `devicePlaceholders` entry per
+   the chosen row's `platform`: `win32` · `darwin` · `linux`), browsed through that device's broker —
+   and a schema-level `"not": {"required": ["device", "hostRoot"]}` both refuses the pair and hides
+   the excluded field. `"advanced": true` folds a field under "Advanced" and `"help"` is its short
+   line; the schema-level `"x-neuralis": {"ui": {"summary": "…"}}` is the kind's one-line form text
+   (your `description` stays the agent's).
+4. **Any other field is a text input, or a `select` filled by YOUR route.** `"control": "select",
+   "optionsRoute": "things?scope=mine"` makes the form read that relative route of your own package and
+   offer the first array in the JSON answer as rows `{id, name?, platform?, status?}` (value = `id`; a
+   `revoked` row is not offered). An absolute route, a scheme or a `..` segment is refused and the
+   field falls back to text with the reason. With `"optional": true` the select also offers the
+   empty value as a real choice, labelled `emptyLabel`. The list is UX only: re-check the value in your connector.
 
 **Never put a secret in `configSchema`.** There is no `credentialFields[]` key that splits schema properties into the credential store, and the factory context carries no `credentials` map — a config property IS plain config, persisted in `sourceConfig.json`. Declare the secret in `neuralis.credentials[]` and read it through the `CredentialResolver` the loader injects into your package's `init(ctx)` — **that** `ctx`, not the factory's — and let the factory close over the resolver. Rules in `references/config-and-credentials.md`.
 
@@ -127,7 +141,7 @@ export function createNotesConnector(ctx: ConnectorFactoryContext): ConnectorPor
 }
 ```
 
-- **Declared capabilities must EXACTLY equal the runtime set**, both directions. Closed vocabulary: `list`, `read`, `stat`, `write`, `delete`, `move`, `mkdir`, `rmdir`, `exec`, `execDetached`, `scanDelta`, `walk`, `count`, `peekCount`, `scanContent`, `subscribeEvents`, `resolveOsUri`; `list` and `read` are mandatory, each of the rest gates one optional method. Symptom: `connector.source.capability-mismatch` with declared-vs-actual sets, thrown at **per-source instantiation** — "installed fine, breaks the first time someone creates a source of this kind." First-party ⇒ boot-fatal; otherwise the kind goes unavailable and callers get `ConnectorCapabilityMissing`.
+- **Declared capabilities must EXACTLY equal the runtime set**, both directions. Closed vocabulary: `list`, `read`, `stat`, `write`, `delete`, `move`, `mkdir`, `rmdir`, `exec`, `execDetached`, `scanDelta`, `walk`, `count`, `peekCount`, `scanContent`, `subscribeEvents`, `resolveOsUri`; `list` and `read` are mandatory, each of the rest gates one optional method. Symptom: `connector.source.capability-mismatch` with declared-vs-actual sets, thrown at **per-source instantiation** — "installed fine, breaks the first time someone creates a source of this kind." Native ⇒ boot-fatal; otherwise the kind goes unavailable and callers get `ConnectorCapabilityMissing`.
 - **Pin the implemented ABI: `4 satisfies ConnectorPortVersion`.** A package shipped SEPARATELY from the kernel pins the number it was built against — importing the host's runtime constant makes an old binary relabel itself as current on the next platform upgrade, which is the one failure the version check exists to catch. (A connector that ships IN LOCKSTEP with the kernel may import the constant instead; yours does not.) Older exec signatures are rejected without adaptation; version equality alone does not prove external code enforces authorization.
 - **Exec is authenticated, and you do NOT write the entry check.** `exec({ command, cwd, timeout?, env?, background? }, { session, signal? })` receives the real `SessionContext` and exact source URI. Declaring the `exec` capability REQUIRES declaring `"execRequires": ["<feature.id>", …]` beside it — the feature id(s) that open a shell on your kind. A missing or EMPTY list is a manifest error, because "every id in an empty list is held" is a door that is always open. The platform stamps a frozen copy of those ids on the instance and wraps `exec` so each one is checked before your code runs, and the calling tool then evaluates the SOURCE's own uri-policy `exec` bit on the cwd. So enforce your lifecycle and supported options — not the entry feature; a second copy in your provider would be free to drift from your manifest. Return the existing result fields plus optional bounded `text`. Exec bindings require an absolute factory `projectRoot`. The loader snapshots provider/source/project/scope before factory execution and stamps the checked instance; callers verify `getConnectorBindingProvenance` against current authority. Never reuse one instance across bindings.
 - **A run that OUTLIVES its call is `execDetached` + the `detached` facet.** Declare the capability (it also requires `exec`) and implement all FIVE verbs — `start`, `status`, `output`, `kill`, `release` — or the loader refuses the binding: a declared capability with a missing verb is a run the platform can start and never stop. `start(request, context)` is a second exec ENTRY, so the platform wraps it with your `execRequires` exactly like `exec`; the other four take the run id you returned and NOTHING else, because a caller who has since lost the entry feature must still be able to read and stop their own run. Ownership is the platform's stored record, never a claim in your arguments: the optional `actor` on `kill` is for your audit row only. Report a kill as an ACKNOWLEDGEMENT and the real end through `status`; answer `null` for a run you no longer know, and keep `output` rows monotonic by `seq` so the platform can prove it copied the whole log before it reports the run finished.
@@ -151,12 +165,12 @@ export function createNotesConnector(ctx: ConnectorFactoryContext): ConnectorPor
 ]
 ```
 
-Required: `source` (unique slug), `kind`, `scope` ∈ `project|user|agent`, a non-empty `description`, `seed` ∈ `auto|discoverable`. Optional: `root`, `label`, `sync`, `permissions`, `recognizesPackages`, `visibility.seeRequires`.
+Required: `source` (unique slug), `kind`, `scope` ∈ `project|user|agent`, a non-empty `description`, `seed` ∈ `auto|discoverable`. Optional: `root`, `label`, `sync`, `permissions`, `packageFolders`, `visibility.seeRequires`.
 
-- `seed: "auto"` seeds into every project with no human in the loop → requires **trusted or better**, else `seed="auto" requires trust >= 'trusted'` and the package fails to load. A root naming a platform token (`${appRoot}`) requires **first-party**. Otherwise roots must be project-relative: no leading `/`, no `${…}` token, no `.` / `..` segments.
+- `seed: "auto"` seeds into every project with no human in the loop → requires **trusted or better**, else `seed="auto" requires trust >= 'trusted'` and the package fails to load. A root naming a platform token (`${appRoot}`) requires **native**. Otherwise roots must be project-relative: no leading `/`, no `${…}` token, no `.` / `..` segments.
 - An untrusted drop gets `seed: "discoverable"` with a project-relative root and nothing more — its declarations never enter the trusted attribution map, so the source appears unattributed, with no package-supplied label or description.
 - **`visibility.seeRequires` is a UX default, not the gate.** The authoritative see-filter and the add-feature check live server-side. Ship a source believing `seeRequires` hides it and you have shipped an unhidden source; setting it grants nothing either.
-- **`recognizesPackages` does NOT switch markdown discovery on**, despite the name. Default unset (⇒ false); allowed `true` only on a `local`-kind source (`recognizesPackages may only be true for local-kind sources.`), and settable only by an owner/admin-effective caller (`Setting recognizesPackages requires an owner/admin-effective role.`). Its real job is the *code-LOAD* axis: the host scans a flagged, enabled, local source's directory for **installable** packages, the way it always scans the project `packages` drop-zone (which needs no flag). Its one effect on markdown is a dedup nuance — under a flagged source the package slug is read as the FIRST path segment, so a subtree duplicating an already-loaded package stops double-injecting. **Symptom when unset: none for markdown.** A plain synced folder still contributes skills, instructions, rules, agents and docs by folder layout alone — recognition criteria are the reach-path table in `SKILL.md` (column (c)) and the discovery rules in `references/manifest-and-discovery.md`. If a source package is invisible, this flag is not the cause; work the diagnosis table below.
+- **`packageFolders` does NOT switch markdown discovery on.** Default unset (⇒ none); `[""]` makes the whole declared `host` source one package folder, `["a/b"]` one folder under its root — the same field the created source stores (`packageFolders may only be set when connection.kind is "host".`), settable only by an owner/admin-effective caller (`Setting packageFolders requires an owner/admin-effective role.`). Its real job is the *code-LOAD* axis: the host scans each package folder of an enabled folder it can open for **installable** packages, the way it always scans the project `packages` drop-zone (which needs no flag); a package folder on a paired device loads over the device link while the device is online, and while it is offline the package stays listed as not available. A loaded package's source twin is not injected twice — the dedup is by exact origin. **Symptom when unset: none for markdown.** A plain synced folder still contributes skills, instructions, rules, agents and docs by folder layout alone — recognition criteria are the reach-path table in `SKILL.md` (column (c)) and the discovery rules in `references/manifest-and-discovery.md`. If a source package is invisible, this flag is not the cause; work the diagnosis table below.
 
 ## Set path permissions (`uriPolicies`)
 
@@ -170,24 +184,24 @@ An **object keyed by URI pattern** — not an array, and no `access` enum. The p
       { "pattern": "data://<self>/private/**", "permissions": { "read": false } },
       { "pattern": "data://<self>/private/$self/**", "permissions": { "read": true }, "override": true },
       { "pattern": "data://<self>/private/**", "permissions": { "read": true },
-        "roles": ["owner", "admin"], "override": true } ] } }
+        "priority": 2, "override": true } ] } }
 ```
 
 1. **Every key must start with `packages://<self>/` or `data://<self>/`** (or equal that prefix minus the trailing slash). A foreign namespace — another package's id, `app://`, `neuralis://`, a bare OS path — **rejects the WHOLE manifest**: no partial registration, the package does not load at all. Inner `paths[].pattern` entries containing `://` are checked identically; relative inner patterns pass.
 2. **`<self>` is a load-time placeholder** substituted with your package slug at boot. Never hardcode your own id in a key.
 3. **`$self`, `$creator`, `$source` are a DIFFERENT family** — runtime tokens substituted inside `paths[].pattern` with the caller's agent id, the source creator's user id, and the source slug. Confusing them is the classic failure: `<self>` in a path position becomes a literal, never-matching segment (the rule appears to do nothing); `$self` in a *key* is not substituted at load, fails the prefix check, and rejects the manifest. This pair is also how self-maintaining identity works: `data://<self>/$self/**` writable while `data://<self>/*/**` is not means an agent rewrites its own identity files and no one else's — a uri-policy grant, not a special case.
 4. **Every value needs `default: { read, write, exec }`, all three booleans present**, or the manifest fails with `missing required default { read, write, exec } booleans`. **Every `paths[]` row needs its capabilities nested under a `permissions` object**, not at the row's top level — the top-level spelling used to normalize to `permissions: {}` and the rule became SILENTLY INERT (it read like a real deny in the manifest and in every persisted copy of it). It is now a load-time rejection, so an inert row cannot ship.
-5. **Patterns match the FULL URI** (leading slash stripped): `?` = one non-separator char, `*` = a run of non-`/`, `**` = anything including `/`, a leading `**/` may match zero segments, anchored both ends. Two symptoms follow: a source-relative pattern (`memory/**` instead of `data://<self>/memory/**`) **silently never matches**, so the intended deny is absent and access falls back to `default`; and `data://<self>/**` does **not** cover the bare root `data://<self>`, so directory-level denies leak on the directory node itself. Spelling is NOT one of the symptoms: slash runs, `.` and `..` are canonicalized on the pattern AND on the URI under test before matching (see the floor paragraph below), so you cannot miss a rule by writing it non-canonically and no caller reaches a file by rewriting its URI.
+5. **Patterns match the FULL URI** (leading slash stripped): `?` = one non-separator char, `*` = a run of non-`/`, `**` = anything including `/`, a leading `**/` may match zero segments, anchored both ends. Two symptoms follow: a source-relative pattern (`memory/**` instead of `data://<self>/memory/**`) **silently never matches**, so the intended deny is absent and access falls back to `default`; and `data://<self>/**` does **not** cover the bare root `data://<self>`, so directory-level denies leak on the directory node itself. Spelling is NOT one of the symptoms: slash runs, `.` and `..` are canonicalized on the pattern AND on the URI under test before matching (see the floor paragraph below), so you cannot miss a rule by writing it non-canonically and no caller reaches a file by rewriting its URI. Letter case is handled too: a rule's `false` bits match every case of its pattern (`CONVERSATIONS/` hits a `conversations/**` deny on every OS), its `true` bits only the exact spelling — write patterns in the case your package creates the files.
 
-**Evaluation order:** `default` → `byRole` → `byUser` → `byAgent` → `paths`. Path rules are **deny-wins**: a `read: true` rule applies only when the result is not already `false`. To re-open something a broader rule denied, set `override: true` — otherwise the carve-out looks correct in the manifest and the caller still gets 403. Rules narrow with `roles[]` and/or `agents[]`.
+**Evaluation order:** `default` → `byRole` → `byUser` → `byAgent` → `paths`. Path rules are **deny-wins**: a `read: true` rule applies only when the result is not already `false`. To re-open something a broader rule denied, set `override: true` — otherwise the carve-out looks correct in the manifest and the caller still gets 403. Rules narrow with `priority`, `users[]` and/or `agents[]`; every condition present on one rule must hold, so "A or B" is two rules.
 
-**`byRole` is keyed by name but resolved by STRENGTH; `roles[]` is still a literal name match.** Do not treat them as one mechanism. A `byRole` entry applies to the caller whose role NAME matches, else to the caller at that entry's exact declared `priority` (so a custom role at the owner anchor gets the `owner` entry), else — for every entry belonging to a role at least as strong as the caller — its explicit `false` bits only, never a grant. A role weaker than `viewer` therefore INHERITS viewer's denials instead of escaping them, and an `owner` never inherits a viewer restriction. A `paths[].roles[]` array has none of that: it matches the role name exactly, so a rule scoped to `["owner","admin"]` does not reach a custom owner-strength role until that role's name is added to the array. If your policy needs a custom role to reach a carve-out, name it in `roles[]`.
+**`byRole` is keyed by name but resolved by STRENGTH; a path rule names its subject by the caller's role priority with `priority`.** Do not treat them as one mechanism. A `byRole` entry applies to the caller whose role NAME matches, else to the caller at that entry's exact declared `priority` (so a custom role at the owner anchor gets the `owner` entry), else — for every entry belonging to a role at least as strong as the caller — its explicit `false` bits only, never a grant. A role weaker than `viewer` therefore INHERITS viewer's denials instead of escaping them, and an `owner` never inherits a viewer restriction. On a `paths[]` rule, `"priority": 2` matches every caller whose role priority is n or stronger (`<= 2`; lower = stronger: owner 1, admin 2, manager 10, member 20, viewer 30), a custom role at that strength included — it is the caller's role strength, not the rule's order. It fails closed: a value that is not an integer from 1 to 99, or a caller without a priority, never matches, and the manifest is rejected. `priority` is grant-only (`override: true`, every declared bit `true`), never on a deny or `floor: true` row. `paths[].roles[]` is rejected in a manifest (`roles is not allowed in a package manifest`): it matches a role NAME exactly, and only a project's own stored rules may use it.
 
 **Uncovered paths deny by default.** A filesystem-touching package with no policy baseline is not "open" — it is denied everywhere and its writes fail quietly. Missing path policy is a bug to flag, never a passing state.
 
 **`exec` is the dimension the sandboxed shell reads.** Keep it `false` on a data zone. The other direction's symptom: `execute action=shell` denies on the cwd with `capability: 'exec'` and `Source "<slug>" denies shell execution (exec) to this caller`, though reads and writes there succeed.
 
-**Your baseline's `default` applies to YOUR PATTERN, not to the source.** The key you declare (`data://<self>/**`) scopes the whole entry: at seeding, that `default` block becomes a path RULE on that pattern, and the source keeps its own source-level default. This is why a `default: { exec: false }` in your manifest does not — and must not — turn off `exec` for the entire shared `data` source that every other package also declares against. One consequence worth knowing: because the shell and terminal read SOURCE-level policy for `exec`, a manifest `exec:false` is enforced on the brain-core git remote-op gate but does not restrict code execution under your subtree. Use a `floor: true` row for anything that must actually be unreachable.
+**Your baseline's `default` applies to YOUR PATTERN, not to the source.** The key you declare (`data://<self>/**`) scopes the whole entry: at seeding, that `default` block becomes a path RULE on that pattern, and the source keeps its own source-level default. This is why a `default: { exec: false }` in your manifest does not — and must not — turn off `exec` for the entire shared `data` source that every other package also declares against. One consequence worth knowing: the shell and terminal judge `exec` on the working directory, so your manifest `exec:false` stops a shell from STARTING anywhere under your subtree (and binds the brain-core git remote-op gate) — but a command started elsewhere can still run a script it can read from there. Use a `floor: true` row for anything that must actually be unreachable.
 
 **Two limits on where your baselines land — and the one exception that is not limited.** Manifest `uriPolicies` baselines are seeded **only at first source attach, and only for source slugs literally named `data` or `packages`** — declare them expecting them to apply to a custom slug (`repo`, `machine`) and nothing happens; the persisted config is used verbatim. And **a new non-floor pattern in an updated package version does not reach existing installs**: only brand-new sources get it, pre-existing projects keep the old permissions indefinitely, and reaching them takes a version-stamped baseline repair pass. Plan for that whenever you tighten a shipped policy.
 
@@ -206,7 +220,7 @@ Denial surfaces as `uri_policy_denied` (HTTP 403, structured body with `uri` and
 | Refused, source slug unknown here | `source_not_configured` (`nextStep: check_configured_sources`, HTTP 404) | no persisted SourceConfig for that slug in this project — or one scoped to someone else, which answers identically. NB the uri gate runs FIRST and denies an unconfigured source as `uri_policy_denied`, so this code surfaces on the routes with no pre-guard (`list`) and for scheme-less uris — a scheme-bearing guess usually reads as the 403 row above | read the reply's `availableSources` (the caller's own visible set) and address one of those; retrying the same slug never helps |
 | Kind absent from the picker | *(log only)* | manifest entry incomplete, factory unresolvable, or trust rejected | read the server log line |
 | A mutating connector call refused while listing works | `403 Forbidden` on a `/connectors` write arm | the caller holds `core.observe` but not `core.connectors` | an admin performs it, or the feature is granted — never retry |
-| An outbound connector is listed nowhere, package `loaded` | *(log only:* `Connector registration refused: unresolved owning project`*)* | the package is not first-party and has no owning project, so it was registered into NO partition | resolve the owning project; the manifest is not the problem |
+| An outbound connector is listed nowhere, package `loaded` | *(log only:* `Connector registration refused: unresolved owning project`*)* | the package is not native and has no owning project, so it was registered into NO partition | resolve the owning project; the manifest is not the problem |
 | Readable but invisible to semantic search | *(none)* | sync-excluded path — on disk, never indexed | do not conclude the file is missing |
 
 **Policy and enabled are orthogonal; the enabled check runs right after visibility** (a source you cannot see answers as absent, before any enabled or policy answer). Policy answers *which URIs you may touch*; the enable toggle (`true | false | 'auto'`, where `'auto'` derives from the connector runtime probe) answers *whether the source is live at all*. Conflate them and users flip the wrong switch.
@@ -215,7 +229,7 @@ Denial surfaces as `uri_policy_denied` (HTTP 403, structured body with `uri` and
 
 Live and enforced before any handler runs, where a **deny is absolute**. Three kinds compile:
 
-- **`safety`** — `config.blockedTools: string[]` is a tool blocklist and `config.timeoutMs` **plus** `config.target` is a per-tool timeout (`target` = a tool name, `*`, or a `fs_*` prefix; smallest matching timeout wins). Either half alone compiles to nothing. Both are **global** — a blocked name is denied for every caller and every package, not only yours — and that is exactly why they are **first-party-only**: from an installed or dropped package both are dropped at load, with a warning naming the kind. Do not reach for `safety` to restrict your own tools; `permission` does that at every trust level.
+- **`safety`** — `config.blockedTools: string[]` is a tool blocklist and `config.timeoutMs` **plus** `config.target` is a per-tool timeout (`target` = a tool name, `*`, or a `fs_*` prefix; smallest matching timeout wins). Either half alone compiles to nothing. Both are **global** — a blocked name is denied for every caller and every package, not only yours — and that is exactly why they are **native-only**: from an installed or dropped package both are dropped at load, with a warning naming the kind. Do not reach for `safety` to restrict your own tools; `permission` does that at every trust level.
 - **`permission`** — `config.allowedTools: string[]`, an allowlist scoped to the declaring package. It also filters the visible tool catalog, so a denied tool is hidden, not merely refused.
 - **`trust`** — `config.enforceInputValidation: boolean`.
 
@@ -225,4 +239,4 @@ Two rules you never write are synthesized for every package: a **trust-tier ceil
 
 ---
 
-Public reference: [connectors](https://docs.neuralisapp.com/package-system/connectors) · [URI policies](https://docs.neuralisapp.com/package-system/uri-policies) · [sources and connectors in the brain](https://docs.neuralisapp.com/brain-core/sources-and-connectors)
+Public reference: [connectors](https://docs.neuralisapp.com/package-system/connectors) · [URI policies](https://docs.neuralisapp.com/package-system/uri-policies) · [sources and connectors in the brain](https://docs.neuralisapp.com/brain-core/connectors)

package/skills/create-package/references/manifest-and-discovery.md

@@ -91,7 +91,7 @@ Four skill layouts are recognised, not one — `skills/<name>/SKILL.md`, `<root-
 
 ## Trust and runtime
 
-**Trust is assigned by where the package came from, never declared.** `access.trust` is `first-party | trusted | untrusted`. A package installed as a dependency of the host is made `first-party` by the host after its manifest is read; a project-dropped package is pinned `untrusted` on its seed *before* the manifest merge, and the seed wins. Wherever the host assigns nothing, an **absent value means `untrusted`** — so `"access": {"trust": "first-party"}` in a package the host did not install as a dependency changes nothing.
+**Trust is assigned by where the package came from, never declared.** `access.trust` is `native | trusted | untrusted`. A package installed as a dependency of the host is made `native` by the host after its manifest is read; a project-dropped package is pinned `untrusted` on its seed *before* the manifest merge, and the seed wins. Wherever the host assigns nothing, an **absent value means `untrusted`** — so `"access": {"trust": "native"}` in a package the host did not install as a dependency changes nothing.
 
 Untrusted implies, all at once: rules physically moved into the `docs` array (so they never inject into the system prompt), `activation.target: prompt-context` rewritten to `workspace`, `overwrite` forced false, `skillScripts` restricted to `"none"`, no `permissions.exec`, no `net: "full"`, no `fs: "full"`, no `seed: "auto"` sources.
 
@@ -101,15 +101,15 @@ Untrusted implies, all at once: rules physically moved into the `docs` array (so
 
 The three differ on two axes — LANGUAGE and CONFINEMENT — and only one of them gives a dropped package the second:
 
-- **`node`** — in-process, **first-party only**.
-- **`wasm`** — JS/TS compiled into an Extism sandbox. **The only code runtime available below first-party**, and what a dropped package declares to run code.
-- **`mcp`** — any language, as an stdio subprocess. Also **first-party only**: the child runs as the host user, with the host's filesystem and network reach, from the `entry.command` and `entry.args` your manifest names. It is a LANGUAGE escape hatch, never a confinement one. Pair it with `entry.command` or you get a warning.
+- **`node`** — in-process, **native only**.
+- **`wasm`** — JS/TS compiled into an Extism sandbox. **The only code runtime available below native**, and what a dropped package declares to run code.
+- **`mcp`** — any language, as an stdio subprocess. Also **native only**: the child runs as the host user, with the host's filesystem and network reach, from the `entry.command` and `entry.args` your manifest names. It is a LANGUAGE escape hatch, never a confinement one. Pair it with `entry.command` or you get a warning.
 
-**Neither `node` nor `mcp` is rejected below first-party — both are DEMOTED.** The package warns and loads `partial`, reason `untrusted-node` or `untrusted-mcp`: declarative contributions register normally, no subprocess is spawned, and every tool and route handler returns a `code-runtime-unavailable` error. So if you are writing a project drop and you need to run code, the answer is `wasm` — declaring `mcp` to get a non-JS language will load the package and silently run none of it.
+**Neither `node` nor `mcp` is rejected below native — both are DEMOTED.** The package warns and loads `partial`, reason `untrusted-node` or `untrusted-mcp`: declarative contributions register normally, no subprocess is spawned, and every tool and route handler returns a `code-runtime-unavailable` error. So if you are writing a project drop and you need to run code, the answer is `wasm` — declaring `mcp` to get a non-JS language will load the package and silently run none of it.
 
-**If you need an existing MCP server, do not reach for this runtime at all — but check WHERE that server runs before you plan around a connector either.** Declare an `{ "type": "mcp" }` **connector** (`connectors[]` — a different field and a different discriminator) when the server is reachable **over HTTP**: give it a `url`, and once connected it is dialed into the agent's MCP session with zero code and zero schema of yours. **A local stdio server (`command`) is not dialed in-host at any tier** — the transport factory refuses stdio and the session factory skips the assignment with a warning, so only `url` servers are reached. Two consequences worth stating plainly: a `"type": "mcp"` connector that omits `transport` **defaults to `stdio`**, i.e. to the refused one, so name `transport` explicitly for an HTTP server; and a **local** non-JS server has no working route below first-party today, by this path or by `runtime.type: "mcp"`. The intended shape for that case is a managed sidecar, which does not exist yet.
+**If you need an existing MCP server, do not reach for this runtime at all — but check WHERE that server runs before you plan around a connector either.** Declare an `{ "type": "mcp" }` **connector** (`connectors[]` — a different field and a different discriminator) when the server is reachable **over HTTP**: give it a `url`, and once connected it is dialed into the agent's MCP session with zero code and zero schema of yours. **A local stdio server (`command`) is not dialed in-host at any tier** — the transport factory refuses stdio and the session factory skips the assignment with a warning, so only `url` servers are reached. Two consequences worth stating plainly: a `"type": "mcp"` connector that omits `transport` **defaults to `stdio`**, i.e. to the refused one, so name `transport` explicitly for an HTTP server; and a **local** non-JS server has no working route below native today, by this path or by `runtime.type: "mcp"`. The intended shape for that case is a managed sidecar, which does not exist yet.
 
-`runtime.binding: "embedded"` is the one true hard reject — a non-first-party package declaring it is marked `error` with `embedded binding requires first-party trust`; nothing registers.
+`runtime.binding: "embedded"` is the one true hard reject — a non-native package declaring it is marked `error` with `embedded binding requires native trust`; nothing registers.
 
 **`runtime.skillScripts`** is `host | wasm-only | none`. An untrusted manifest declaring anything other than `"none"` fails validation (omitting it is also fine). Beyond that declaration-time check the value is **advertisement**: rendered as a tag in the package overview, enforcing nothing at runtime — do not plan around it blocking a spawn. Separately, `${SKILL_DIR}` resolves to a sentinel string only when a skill has **no host-side directory at all** (a source-contributed skill whose connector gives no container path); installed packages and project drops both resolve a real directory.
 
@@ -150,7 +150,7 @@ The three differ on two axes — LANGUAGE and CONFINEMENT — and only one of th
 
 **`meta.families`** groups tools for UI and feature gating. **`meta.distribution`** has exactly four keys — `installRoot`, `gitRepository`, `gitRef`, `npm`; no `homepage`, `repository` or `bugs` key exists there.
 
-**`source.kind`** records provenance — thirteen values: `neuralis`, `local-dir`, `mounted-dir`, `git`, `npm`, `archive`, `mcp-server`, plus the imported-ecosystem kinds `claude-skill`, `cursor-skill`, `gemini-extension`, `openclaw-plugin`, `openai-app`, `m365-agent`. Two rules bite: `git` **requires** `meta.distribution.gitRepository` or validation fails; `neuralis` is the marker the loader reads to treat a package as a host-owned builtin and select full in-process discovery — a project drop must never claim it.
+**`source.kind`** records provenance — thirteen values: `neuralis`, `local-dir`, `mounted-dir`, `git`, `npm`, `archive`, `mcp-server`, plus the imported-ecosystem kinds `claude-skill`, `cursor-skill`, `gemini-extension`, `openclaw-plugin`, `openai-app`, `m365-agent`. Two rules bite: `git` **requires** `meta.distribution.gitRepository` or validation fails; `neuralis` is never authored: the host stamps it — with `native` trust — on every package of its install slots (its own dependencies and the packages installed while it runs), and only that stamped pair lets a package's code be imported; a manifest that declares it is ignored (the validator warns), and a project drop can never reach it.
 
 **Not in this contract — do not invent them:** no `category` enum, no curated keyword vocabulary beyond free-form `tags`, no `engines`/compatibility field, no manifest-level deprecation or yank key (`version` is metadata, not an update trigger — pulling a published version is a registry-side operation over the signed revocation feed, never a field you declare here).
 
@@ -169,13 +169,13 @@ Each of `tools`, `prompts`, `resources` takes `none | selected | all`; `selected
 
 ### A tool name is global: a collision is SHADOWED, not renamed
 
-A tool name is one key for the whole deployment, so two packages — or a package and one of the platform's own tools, or an MCP server — can claim the same one. **Nothing is renamed.** Each agent answers the name with ONE claimant, chosen by rule, never by load order: the **first-party** claimant wins if there is one (the platform's own tools included), otherwise the lexically-smallest `packageId`, and any package before an MCP server. A claimant the caller cannot use — its package switched off for that agent, out of scope, or its tool feature-gated for the caller — drops out BEFORE the rule, so it never takes the name from anyone. The losing package keeps every one of its OTHER tools.
+A tool name is one key for the whole deployment, so two packages — or a package and one of the platform's own tools, or an MCP server — can claim the same one. **Nothing is renamed.** Each agent answers the name with ONE claimant, chosen by rule, never by load order: the **native** claimant wins if there is one (the platform's own tools included), otherwise the lexically-smallest `packageId`, and any package before an MCP server. A claimant the caller cannot use — its package switched off for that agent, out of scope, or its tool feature-gated for the caller — drops out BEFORE the rule, so it never takes the name from anyone. The losing package keeps every one of its OTHER tools.
 
 > **Symptom:** a call to your tool answers from another package. The package is healthy; the NAME is contested. An owner can pick your package for that name per agent in Tool Access, but by default the rule decides — rename your tool so nobody has to choose.
 
 Where to look: the boot log carries a `Namespace collisions detected` line naming the owner and the shadowed package ids, and `GET tools/catalog` returns a `contestedTools` row (`{name, owner, claimants, preferred?}`) for each name contested for that agent.
 
-So **pick a name nobody else will pick**. Prefix by domain, not by convenience — `acme_release_status`, not `status`. The rule is the ONLY protection, and it applies to every install class alike: the platform's own packages, an admin's `neuralis pkg add`'ed dependency and a project `_packages/` drop all fight for the same key. Trust decides who WINS the fight, never whether there is one — a host dependency is stamped `first-party` by the host regardless of its scope, so `@acme/*` next to `@neuralis/*` is a lexical tie-break, not a rescue. Nothing anywhere refuses to start over a collision: a taken name shadows, it never takes the deployment down.
+So **pick a name nobody else will pick**. Prefix by domain, not by convenience — `acme_release_status`, not `status`. The rule is the ONLY protection, and it applies to every install class alike: the platform's own packages, an admin's `neuralis pkg add`'ed dependency and a project `_packages/` drop all fight for the same key. Trust decides who WINS the fight, never whether there is one — a host dependency is stamped `native` by the host regardless of its scope, so `@acme/*` next to `@neuralis/*` is a lexical tie-break, not a rescue. Nothing anywhere refuses to start over a collision: a taken name shadows, it never takes the deployment down.
 
 ## `dataLayout` — say where you keep your files
 
@@ -187,9 +187,9 @@ If your package writes under its own `data://` zone, declare the first-level dir
 
 `"machineWritten": [{ "path": "*/stats/*.json", "class": "metrics" }]` (inside `dataLayout`) names the files your package writes on its own — never rendered into the prompt. `path` is a glob relative to your zone (`*` one segment, `**` any depth; a leading `/`, an empty or `..` segment, or any character outside `[A-Za-z0-9._*-]` rejects the manifest); `class` is `metrics` (numbers only), `log` or `runtime-text` (runtime state a person may search for). A NEW project's `data` source leaves `metrics` files out of its index from the start; existing projects keep their settings. Declarations from untrusted packages are ignored.
 
-**The rest of the block is owned elsewhere:** `sources[]` / `connectors[]` / `uriPolicies` → `connectors-and-uri-policies.md` (a `uriPolicies` pattern may name only `packages://<self>/…` and `data://<self>/…`; a foreign namespace rejects the whole manifest — and a `connectors[]` entry registers into exactly ONE project partition, or into none at all when the package is neither first-party nor owned by a resolvable project), `credentials[]` / `configSettings[]` → `config-and-credentials.md`, `app.surfaces[]` → `surfaces-and-design.md`, `team[]` / workflows → `team-and-workflows.md` (note that `team[]` is VALIDATED fail-closed at load: a bad slug or a template path that leaves the package rejects the whole manifest).
+**The rest of the block is owned elsewhere:** `sources[]` / `connectors[]` / `uriPolicies` → `connectors-and-uri-policies.md` (a `uriPolicies` pattern may name only `packages://<self>/…` and `data://<self>/…`; a foreign namespace rejects the whole manifest — and a `connectors[]` entry registers into exactly ONE project partition, or into none at all when the package is neither native nor owned by a resolvable project), `credentials[]` / `configSettings[]` → `config-and-credentials.md`, `app.surfaces[]` → `surfaces-and-design.md`, `team[]` / workflows → `team-and-workflows.md` (note that `team[]` is VALIDATED fail-closed at load: a bad slug or a template path that leaves the package rejects the whole manifest).
 
-## `events[]` — notifications from your package (first-party only)
+## `events[]` — notifications from your package (native only)
 
 A package the host installs as a dependency can declare the moments a person should hear about — a run finished, a sync failed. The platform delivers them: a badge on your dock entry, a row in the user's inbox, per-person mute and follow. You build none of that UI. Any other install class has the field dropped at load with a warning.