@neuralis/brain-core 0.3.2 → 0.4.0

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,21 +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 a paired device — a machine outside the app (reached
-   through that device's 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?, status?}` (value = `id`; a
+   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. The list is UX only: re-check the value in your connector.
+   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`.
 
@@ -132,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.
@@ -156,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`)
 
@@ -175,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.
 
@@ -211,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.
@@ -220,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`.
 
@@ -230,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.
 

package/skills/create-package/references/runtime-and-build.md

@@ -59,16 +59,16 @@ export function api(state: NotesState) {
 
 - **The lifecycle FILE is optional; `init` inside it is not.** A package with no routes and no tool handlers (markdown, schemas, connectors) ships no `src/lifecycle.ts` at all. A lifecycle module without `init` is discarded with a warning and `start`/`drain`/`stop`/`api`/`onBootstrapComplete`/`provisionProject`/`deprovisionProject`/`onPrincipalRevoked`/`onCredentialChanged`/`health` are never wired.
 - **`init` returning nothing** leaves the dispatch state `undefined` — symptom: every request returns 503 `Package not initialized — lifecycle failed to load`, though the route files loaded and nothing logged an error.
-- **Peer lookups belong in `onBootstrapComplete(state, ctx)`** — it fires once after every package's `init` and `start` have resolved. Elsewhere load order is not guaranteed: `getPackageApi()` returns `undefined` intermittently, fine on one boot, silently degraded on the next. From a non-first-party package `undefined` may also be a trust **denial** (audited `denied:untrusted` / `denied:trust-mismatch`), not a missing package.
+- **Peer lookups belong in `onBootstrapComplete(state, ctx)`** — it fires once after every package's `init` and `start` have resolved. Elsewhere load order is not guaranteed: `getPackageApi()` returns `undefined` intermittently, fine on one boot, silently degraded on the next. From a non-native package `undefined` may also be a trust **denial** (audited `denied:untrusted` / `denied:trust-mismatch`), not a missing package.
 - **`onPrincipalRevoked(state, event)` closes; it never decides.** The host calls it when a user is disabled, deleted or has their sessions reset (no `event.projectId`), or loses one project (`membership_removed` / `project_archived`, with `projectId`). Stop what you hold open for `event.userId` — sockets, running jobs, pollers — through your existing stop, and return promptly: the call is bounded by a timeout, and the user is already refused everywhere else, so never re-check access here. Only a host-installed package's lifecycle runs at all; a `_packages/` drop never receives it.
 
-**`init` receives** `selfId`, `selfTrust`, `data { dataDir, globalDir?, fileStore<T>, jsonlAppender<T>, dataPath, logger }`, `host { id }`, `packages { isLoaded, getPackageApi<T> }`, `credentials?`, `sessions? { createProjectFactory }`, `config { get }`, lazy `platform` facts, first-party `hostPorts`, `logger`. Platform facts throw before publication and are read where used; bootstrap completion receives the same `platform`, rather than copied aggregates. `dataDir` is **per project**: `<projectsRoot>/<projectId>/data/<zone>/`, mode `0700`, with `logs/`. First-party packages (host-installed, `@neuralis/*` and the deploy's own deps) additionally receive `data.globalDir` — a project-independent platform home under the app zone, where their process-global state and their `logs/` live; a project-installed package like yours has NO `globalDir` (its state is project data by nature), and `ctx.data.globalDir` is `undefined` for it.
+**`init` receives** `selfId`, `selfTrust`, `data { dataDir, globalDir?, fileStore<T>, jsonlAppender<T>, dataPath, logger }`, `host { id }`, `packages { isLoaded, getPackageApi<T> }`, `credentials?`, `sessions? { createProjectFactory }`, `config { get }`, lazy `platform` facts, native `hostPorts`, `logger`. Platform facts throw before publication and are read where used; bootstrap completion receives the same `platform`, rather than copied aggregates. `dataDir` is **per project**: `<projectsRoot>/<projectId>/data/<zone>/`, mode `0700`, with `logs/`. Native packages (host-installed, `@neuralis/*` and the deploy's own deps) additionally receive `data.globalDir` — a project-independent platform home under the app zone, where their process-global state and their `logs/` live; a project-installed package like yours has NO `globalDir` (its state is project data by nature), and `ctx.data.globalDir` is `undefined` for it.
 
 **Write through `dataPath`, and hold ONE appender.** `jsonlAppender()` takes a RESOLVED path, not a string — `ctx.data.dataPath('events.jsonl')` produces one, and it refuses anything that would leave your own data dir (an absolute path, or a relative one that climbs out), so you cannot write into a sibling package's data by accident. The APPENDER creates any missing intermediate directories when it writes; `dataPath` itself only resolves, so if you hand its result to your own `fs` call the directories are yours to create. Keep ONE appender for the life of the package: its write ordering is per-instance, so a fresh one per call gives up the guarantee that entries written together stay together. (The WASM guest plane's `ctx.data.*` also takes paths relative to the package data dir, but REPORTS failure as `{ ok: false, error }` instead of throwing — its answers cross into guest memory and carry a fixed code, never a filesystem path. Do not merge the two contracts in your head.)
 
-**The logger is levellable and append-only.** `ctx.data.logger` is a `PackageLogger` already pointed at `<dataDir>/logs/` (for a first-party package: `<globalDir>/logs/`); it resolves its level at every CALL — your package's entry in the operator's `packageLogLevelOverrides` (keyed on the `pkg` field of your log lines: your zone path, `runtime/packages/<dir>` for a drop, the bare name for `@neuralis/*`) → the global `packageLogLevel` → `debug`. Both are platform keys; your manifest declares nothing for them. Never cache `logger.level` in a constructor: the level is live, so a captured value stays pinned after an administrator edit. Every line is appended (O(1)), so the file is OLDEST-first: read "the newest N" with `JsonlAppender.readNewest(path, n)` (`@neuralis/package-system/data`), which takes the tail and then the rotated `.1`, `.2` … generations — never the first lines.
+**The logger is levellable and append-only.** `ctx.data.logger` is a `PackageLogger` already pointed at `<dataDir>/logs/` (for a native package: `<globalDir>/logs/`); it resolves its level at every CALL — your package's entry in the operator's `packageLogLevelOverrides` (keyed on the `pkg` field of your log lines: your zone path, `runtime/packages/<dir>` for a drop, the bare name for `@neuralis/*`) → the global `packageLogLevel` → `debug`. Both are platform keys; your manifest declares nothing for them. Never cache `logger.level` in a constructor: the level is live, so a captured value stays pinned after an administrator edit. Every line is appended (O(1)), so the file is OLDEST-first: read "the newest N" with `JsonlAppender.readNewest(path, n)` (`@neuralis/package-system/data`), which takes the tail and then the rotated `.1`, `.2` … generations — never the first lines.
 
-`onCredentialChanged(state, event)` receives `{credentialId, scope, change}` after a write or delete; re-resolve a changed secret through `ctx.credentials`, never through the event. `drain(state)` finishes or checkpoints work before `stop`, and `health(state)` returns structured checks with closed status/reason values. Runtime fan-outs are bounded. A first-party package exposes its declared `provides` implementations on the state returned by standalone `init(ctx)`. The discovered adapter retains `state.services` as `PackageRuntimeApi.services`, separately from the public `api(state)`; the host resolves them by contract id.
+`onCredentialChanged(state, event)` receives `{credentialId, scope, change}` after a write or delete; re-resolve a changed secret through `ctx.credentials`, never through the event. `drain(state)` finishes or checkpoints work before `stop`, and `health(state)` returns structured checks with closed status/reason values. Runtime fan-outs are bounded. A native package exposes its declared `provides` implementations on the state returned by standalone `init(ctx)`. The discovered adapter retains `state.services` as `PackageRuntimeApi.services`, separately from the public `api(state)`; the host resolves them by contract id.
 
 Use those contracts instead of module globals — `createProjectFactory` for per-project services, `ctx.credentials.*` for secrets. Cross-package calls carry the caller (`getPackageApi<T>(id, { userId, projectId, callerId, callerTrust })`) and are trust-gated and audited. Never call another package over MCP.
 
@@ -101,7 +101,7 @@ export const POST: RouteHandler = async (req, state) => {
 
 **The feature gate runs before your handler**; never re-check the route's own `feature` inside it.
 
-> **A route with no `feature` is reachable by any authenticated project member.** It does not "require first-party trust". Symptom: no error anywhere — a viewer-role user or an agent's skill script successfully calls an endpoint you assumed was admin-only, and you find out in an audit, not in a test. Declare a `feature` on every route not deliberately open to all members.
+> **A route with no `feature` is reachable by any authenticated project member.** It does not "require native trust". Symptom: no error anywhere — a viewer-role user or an agent's skill script successfully calls an endpoint you assumed was admin-only, and you find out in an audit, not in a test. Declare a `feature` on every route not deliberately open to all members.
 
 **Identity.** `req.session` (`userId`, `projectId`, `agentId`, `role`, `grantedFeatures`, `priority`, `agentAccess`, `limits`) is the only identity — never re-state it in a body or query, never trust a caller-supplied `projectId`; best case the gateway rejects with 403 `project_mismatch`, worst case you built a confused deputy. `req.interactive` is a transport marker (browser session vs machine ticket), **never identity**, and is absent on sandboxed dispatch — read it as strict `=== true` or you hand sandboxed callers the privileged human branch.
 
@@ -115,17 +115,17 @@ Enforced automatically by the dispatchers; your package writes no code for it. L
 
 | | tool calls / min | route calls / min | tool timeout |
 |---|---|---|---|
-| first-party | unlimited | unlimited | none effectively enforced |
+| native | unlimited | unlimited | none effectively enforced |
 | trusted | 100 | 300 | 120 s |
 | untrusted | 10 | 30 | 30 s |
 
-Only the **trusted** tier's tool rate limit and timeout are administrator-tunable; the rest are hardcoded security floors. Exceeding a route limit returns **429**, and every non-first-party route access is audited. Trust is assigned by where the package came from — declaring `access.trust` yourself changes none of it.
+Only the **trusted** tier's tool rate limit and timeout are administrator-tunable; the rest are hardcoded security floors. Exceeding a route limit returns **429**, and every non-native route access is audited. Trust is assigned by where the package came from — declaring `access.trust` yourself changes none of it.
 
 ---
 
 ## 6. The sandbox — what a dropped package can do
 
-A `_packages/` drop runs in a WASM sandbox, untrusted by default; an administrator may elevate it to trusted.
+A `_packages/` drop runs in a WASM sandbox, untrusted by default; an administrator may elevate it to trusted (Admin → Packages, or `neuralis package trust <package> trusted`).
 
 **WASM here is the TOOL and ROUTE runtime — it never renders UI.** There is no WASM UI engine and none can be declared: the `wasm-ui` renderer was removed from the surface contract and a manifest still declaring it fails validation. A sandboxed WASM tool feeds a card exactly like any other tool — by returning `structuredContent` — and the UI itself ships as a self-contained `iframe` asset (`references/surfaces-and-design.md`).
 
@@ -166,10 +166,10 @@ wrappers over brain-core's `read`/`list`/`search`/`write` routes
 (`create`/`overwrite`/`edit`/`insert`/`lines`/`fields`/`move`/`copy`/`mkdir`/`revert`/`delete`). The route CATALOG —
 which routes exist and which feature each needs — lives on the per-package
 "API &amp; usage" docs pages:
-<https://docs.neuralisapp.com/agent-core/api-usage> ·
-<https://docs.neuralisapp.com/brain-core/api-usage> ·
-<https://docs.neuralisapp.com/admin/features-and-routes> ·
-<https://docs.neuralisapp.com/machine-core/api-usage> — mechanism:
+<https://docs.neuralisapp.com/agent-core/routes> ·
+<https://docs.neuralisapp.com/brain-core/routes> ·
+<https://docs.neuralisapp.com/admin/routes> ·
+<https://docs.neuralisapp.com/machine-core/routes> — mechanism:
 <https://docs.neuralisapp.com/package-system/routes>.
 
 `callRoute` denials return `{ ok: false, error: '…' }` rather than throwing — a
@@ -241,13 +241,13 @@ Only a package with `src/tools/*.ts`, `src/routes/*.ts` or `src/lifecycle.ts` ne
 
 **Fail-closed:** `src/routes/*` present with no valid `dist/routes.json` ⇒ the package wires **no** route at all and loads `partial` (`build-missing`), logging `declares route sources but has no valid dist/routes.json — failing closed`. Tools may still work, which makes it look like a routing bug. Rebuild.
 
-**Three triggers:** the **Build** button in the filesystem widget's Packages panel (build + reload + audit — the recommended path); **automatic on install** when `runtime.type` is `wasm` and source is present, where failure is **non-fatal** (the installer warns, the package installs `partial` — this is why "it installed fine but my tool 503s" happens); or the CLI **by absolute path**:
+**Three triggers:** **Build** in Admin → Packages or `neuralis package build <package>` (a package manager's action: build + reload + audit — the recommended path); **automatic on install** when `runtime.type` is `wasm` and source is present, where failure is **non-fatal** (the installer warns, the package installs `partial` — this is why "it installed fine but my tool 503s" happens); or the CLI **by absolute path**:
 
 ```bash
 node <install-root>/node_modules/.bin/neuralis-build <absolute package root>
 ```
 
-A first-party package's UI uses the same CLI in `ui` mode — `neuralis-build ui <absolute package root>` bundles the `app.module` entry to `dist/app/` and fails the build if React or another host-shared module would be bundled into it (`BUNDLED_SHARED_MODULE` — two Reacts break every hook), if it imports a module of another UI package that package's `app.module.provides` does not list (`UNDECLARED_SHARED_MODULE`), or if it reads React with no resolvable `react` (`NO_REACT`). Beside the bundle it writes `shared-imports.json` (host API version, React major, shared ids read); the host refuses a module whose record no longer matches it, so rebuild after every platform upgrade.
+A native package's UI uses the same CLI in `ui` mode — `neuralis-build ui <absolute package root>` bundles the `app.module` entry to `dist/app/` and fails the build if React or another host-shared module would be bundled into it (`BUNDLED_SHARED_MODULE` — two Reacts break every hook), if it imports a module of another UI package that package's `app.module.provides` does not list (`UNDECLARED_SHARED_MODULE`), or if it reads React with no resolvable `react` (`NO_REACT`). Beside the bundle it writes `shared-imports.json` (host API version, React major, shared ids read); the host refuses a module whose record no longer matches it, so rebuild after every platform upgrade.
 
 `npx neuralis-build` from a project data folder **does not work** — no module tree above it, so npx goes to the public registry and dies with `E404 'neuralis-build@*' is not in this registry`.
 
@@ -255,9 +255,9 @@ A first-party package's UI uses the same CLI in `ui` mode — `neuralis-build ui
 
 ---
 
-## 7b. Developing a first-party package from ITS OWN repository
+## 7b. Developing a native package from ITS OWN repository
 
-A column-(a) package does not have to live inside the platform's tree, and for a real first-party
+A column-(a) package does not have to live inside the platform's tree, and for a real native
 package it should not. The dependency line is the trust act, and a dependency can point at any
 directory on the deploying machine — so the package gets its own repository, its own git history and
 its own release cadence, and the deployment's image build installs it from that directory (or from a
@@ -311,7 +311,7 @@ report a suite as green in an environment you did not run it in.
 
 1. **git remote** — source backup and review. Changes nothing about the deployment.
 2. **dependency registration + image rebuild** — the operator's trust act, then the build that
-   installs it. THIS is what makes the package discovered and loaded in-process with first-party
+   installs it. THIS is what makes the package discovered and loaded in-process with native
    trust.
 3. **mount** — binds the directory over the installed copy for live editing (build in the folder,
    restart). Plumbing only; without (2) the package is still invisible.
@@ -346,7 +346,7 @@ every agent that can see it.
 | **503 `code-runtime-unavailable`** | the package loaded `partial`; read the reason |
 | `pkg add` or the image build refuses the package, or it is absent and Admin health lists it under `builtin-packages` | it failed the loader's admission check (named per file — a tool in `tools/` missing `x-neuralis.annotations.category` is the usual one: the schema validator alone passes it, the native-tool check does not), or it collides with another package over a service, an OAuth prefix or a config key; only that package is left out |
 
-Partial reasons: `build-missing` (no sandbox artifact — rebuild), `runtime-unavailable` (the code runtime crashed, or an MCP subprocess failed to spawn), `untrusted-node` (a non-first-party package declared or defaulted to the in-process `node` runtime), `untrusted-mcp` (a non-first-party package declared the `mcp` subprocess runtime — nothing was spawned). **Both trust reasons have the same fix: declare `wasm`, the only code runtime available below first-party.** A `partial` package still registers every declarative contribution, which is why it looks half-working rather than broken.
+Partial reasons: `build-missing` (no sandbox artifact — rebuild), `runtime-unavailable` (the code runtime crashed, or an MCP subprocess failed to spawn), `untrusted-node` (a non-native package declared or defaulted to the in-process `node` runtime), `untrusted-mcp` (a non-native package declared the `mcp` subprocess runtime — nothing was spawned). **Both trust reasons have the same fix: declare `wasm`, the only code runtime available below native.** A `partial` package still registers every declarative contribution, which is why it looks half-working rather than broken.
 
 ---