@neuralis/brain-core 0.1.0 → 0.2.1

package/rules/brain-rules.md

@@ -10,7 +10,7 @@ activation:
 
 ## Discovery and identity
 
-1. **Search before you create.** Run semantic and live `grep` in parallel and reconcile by URI: semantic finds meaning, grep avoids index lag. Check for duplicates first.
+1. **Search before you create.** Pair semantic search with live `grep`, reconcile by URI and check `effective_mode`/embedding freshness: fallback text or retained vectors can miss meaning; grep avoids index lag. Check duplicates first.
 2. **Files are URIs.** Use source URIs such as `data://…`; never expose internal UUIDs or invent schemes. `<runtime_stack>` names configured sources; `os://` entries are labels, not sources.
 3. **Prefer scoped reads.** Batch small files; range-read a large one (a truncation marker means you did not see it all — `tool-use` owns that). Scope listings to a source/folder; use connector reads or grep when the index is cold.
 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.

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

@@ -36,8 +36,10 @@ retention and indexing behavior.
 
 1. **Files or an authorised export** (CSV/XLSX/JSON/PDF, a folder, an approved dump) → attach an
    existing source kind. This is the cheapest path.
-2. **A live API, MCP server or OpenAPI service** → use an existing outbound integration or build a
-   source connector when searchable filesystem semantics are required. An outbound connector belongs
+2. **A live API, MCP server or OpenAPI service** → an existing outbound integration first, then the
+   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
    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
@@ -100,8 +102,8 @@ sync lifecycle; do not work around it by pasting the corpus into memory.
 - `manage-uri-policy` — per-path governance.
 - `create-package` — connector, skill, tool and workflow authoring around governed sources.
 - `create-package/references/connectors-and-uri-policies.md` — source and connector contract.
-- https://docs.neuralisapp.com/docs/package-system/connectors
-- https://docs.neuralisapp.com/docs/package-system/uri-policies
+- https://docs.neuralisapp.com/package-system/connectors
+- https://docs.neuralisapp.com/package-system/uri-policies
 
 ## Close the loop
 

package/skills/create-package/SKILL.md

@@ -23,7 +23,9 @@ argument.
 
 **One caveat:** activation happens through the `execute` tool and nowhere else — an agent without
 `execute` reads a skill's description and cannot run it. If the capability must work for such an
-agent, it is a tool, a route or a rule.
+agent, it is a tool, a route or a rule. **And every capability a human gets has its agent path in
+the same package** — a route the skill's script calls, or a tool, behind the same gate; a button only
+a human can press is half a capability.
 
 ## Golden rules
 
@@ -52,14 +54,14 @@ ADD to it rather than replace it; shipping several kinds together is the stronge
 system — a governed tool plus a skill teaching the craft of driving it.
 
 1. **Knowledge, procedure, judgment, or a checklist?** → **SKILL.** The default; most requests.
-2. **Does the platform already reach it?** (Step 0 — sources and MCP too.) An `{ type: "mcp" }` connector is zero code and zero schema — the external server's tool list simply becomes available.
+2. **Does the platform already reach it?** (Step 0 — sources and MCP too; then the vendor's OFFICIAL skill, MCP server or plugin, imported before you write anything — `references/connectors-and-uri-policies.md` §The headline.) An `{ type: "mcp" }` connector is zero code and zero schema — the external server's tool list simply becomes available.
 3. **Must it run on a schedule or a trigger — "weekly", "every morning", "when a ticket lands"?** → **WORKFLOW template** (`workflows/*.json`) carrying the instruction, usually invoking the skill from #1. A skill alone fires only when someone asks; the schedule is what makes it run by itself.
 4. **A separate persona running in its own forked context with a restricted tool set?** → **AGENT file** (`agents/*.md`) — the one place `allowed-tools` is genuinely *enforced*, filtering the child's tools. Leave it out for a universal role (the child inherits what the caller can reach); write `allowed-tools: []` for a persona that must hold no tools at all.
 5. **Must every turn obey it, unconditionally, even when nothing triggered it?** → **RULE.** The most expensive slot in the system. Budget: one rule file per package, under 4 KB, unconditional behaviour only; anything domain-conditional is a skill or a doc.
 6. **Do you need one of four things a skill structurally cannot give you?** → **TOOL.** *Schema enforcement* — arguments validated before your handler runs, invalid calls rejected. *Permission gating* — a `requires.features` gate that both hides and rejects, a risk category driving approval posture, per-trust rate limits. *Determinism* — skill composition is non-deterministic; if correctness depends on it happening, it is a tool, a script or a hook, never prose asking the model to be careful. *A designed surface* — a card, a widget, or an app a human looks at repeatedly.
 7. **An external corpus of files or records to search?** → **GOVERNED CONNECTOR / source** — establish owner, approved location, audience/scope, sensitivity/retention, credential scope, copy permission and provenance first. Attach it as a configured source; never put the dataset in identity or memory. Skills, tools and workflows wrap the source and point to its URIs.
 8. **An AI coworker with an identity, a persona and evolving memory?** → **TEAM MEMBER.**
-9. **Does a human look at it, repeatedly?** → **WIDGET + dock companion** (a standing panel) or **CARD** (the result of one tool call).
+9. **Does a human look at it, repeatedly?** → **WIDGET + dock companion** (a standing panel) or **CARD** (the result of one tool call). A tool whose result a human reads gets a card by default; the visual precedent is the platform's own cards (execute, todos, workflow) on the `CardShell` exported from `@neuralis/agent-core/app/chat`.
 
 **Corollaries.** Split read from write into separate tools — the approval floor is per-tool and never reads an argument's VALUE, so an `action` enum makes the destructive case ungateable; verbs sharing one posture go on one tool as keys, and a rare destructive verb inside that posture is gated by declaring its root key in `x-neuralis.askOnKeys` (`references/tools-and-schemas.md` §2, which also owns description craft — the callable contract there, the procedure in a skill). `allowed-tools` is enforced on agent files (absent = inherit, `[]` = nothing), advisory on skills — this one included.
 
@@ -145,9 +147,9 @@ a drop is rescanned in about half a second and source markdown needs no install
 
 **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
-the DIRECTORY name, never the registry id: a loaded drop registers under the namespaced id
-`p.<project>.project.<dir>`, which is what `verify-loaded.sh` and the trust/enable routes take,
-while every path stays `packages://<dir>/…`. An installed package's folder is
+the DIRECTORY name, never the registry id: a loaded drop's id is the instance URI
+`packages://<dir>?project=<p>&scope=project` (`<packages>` shows it short,
+`packages://<dir>`), while every path stays `packages://<dir>/…`. An installed package's folder is
 replaced wholesale on every update: treat it read-only and **report** a defect in a shipped file
 instead of patching it. Skills, rules, instructions, agents and docs you created or downloaded live
 where you own them — improve those in place, never weakening a security rule you find there.
@@ -156,7 +158,7 @@ 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 `source:data://acme`. Every project seeds two writable local sources, `data://` and
+skill, id `data://acme?project=<p>&scope=project`. Every project seeds two writable local 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
 source has one; absent, cwd the URI itself (`cwd: "data://acme"`). `fs_list` with no `uri` gives
@@ -182,8 +184,8 @@ around the gate — ask: files on disk, `drive.sync` named, Files widget → Sou
 **Sync** offered, in the words `references/test-and-ship.md` prescribes.
 
 Reach paths in full:
-<https://docs.neuralisapp.com/docs/package-system/directory-contract> ·
-<https://docs.neuralisapp.com/docs/package-system/source-packages>
+<https://docs.neuralisapp.com/package-system/directory-contract> ·
+<https://docs.neuralisapp.com/package-system/source-packages>
 
 ## What you can reach right now
 
@@ -255,7 +257,7 @@ bash ${SKILL_DIR}/scripts/verify-loaded.sh <package-id>              # any path,
 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
-`source:<rootUri>`) and reads package diagnostics, so it needs `core.observe` — lacking that it
+`<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
@@ -279,8 +281,8 @@ a fresh stream before re-diagnosing.
   package restating its own README is the README with extra steps. Report the byte delta of the
   prose you changed and any growth's reason.
 
-Full reference: <https://docs.neuralisapp.com/docs/package-system/create-a-package> · worked
-examples, one per reach path: <https://docs.neuralisapp.com/docs/package-system/reference-package>.
+Full reference: <https://docs.neuralisapp.com/package-system/create-a-package> · worked
+examples, one per reach path: <https://docs.neuralisapp.com/package-system/reference-package>.
 
 The registry is real and readable: §11 of `references/test-and-ship.md` has the read rows (Tier A
 `/content` plain text, Tier B `/document` JSON) and the operator's publish procedure. The public

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

@@ -122,7 +122,7 @@ set -euo pipefail
 curl -sS -H "Authorization: Bearer $WEATHER_API_KEY" "https://api.weather.example/v1/forecast?q=$1"
 ```
 
-On activation the host resolves each declared id at the caller's real `(userId, projectId, agentId)` scope. **The model never sees a resolved value.**
+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.
 - **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.
@@ -158,5 +158,5 @@ Never inline a secret in a manifest or a source config file, and never default-a
 
 ## Going deeper
 
-- Configuration tiers and the cascade: <https://docs.neuralisapp.com/docs/enterprise/configuration>
-- Credential scopes, the dynamic catalog and the encrypted store: <https://docs.neuralisapp.com/docs/enterprise/credentials>
+- 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>

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

@@ -10,7 +10,9 @@ Every system a connector reaches joins ONE URI-addressed, vector-indexed, policy
 
 **Survey before you act on real data**, in order: (1) survey what exists — the user's public surface and whatever the workspace already holds; `fs_list` the attached sources before proposing a new one. (2) Gather or request the company's own material — ask for it, or mount it. (3) Vectorize it by syncing, so it is searchable and not merely present. (4) Build skills around it. An agent that produces output about a business it never surveyed is doing the wrong job well.
 
-**Cheapest path first:** if an admin can point an existing connector kind at the material, do that and stop. Write a connector only when no existing kind reaches the system.
+**Official integration first, then the cheapest path** — in order: (1) what is already wired: the attached sources (`fs_list`) and the MCP assignments (`connect {list:{kind:"mcp"}}`); if an admin can point an existing connector kind at the material, do that and stop. (2) The vendor's official (or top-rated) skill, MCP server or plugin: import it under `packages://`, record its origin (upstream URL, version or commit, license) in a provenance note inside the imported folder, and prove it in each environment that uses it (it loads, one real operation succeeds). (3) Only when neither exists, write a connector (below).
+
+**Honest limits of an import today.** There is no clone route, and the seeded `packages://` source is `exec:false` — never instruct a shell `git clone` there, and never present an `exec` grant as routine (widening a path policy is the owner's call). A downloaded tree is untrusted data: its `.mcp.json` and hooks files stay inert, and code runs only from a Neuralis manifest's declared WASM runtime, sandboxed, at the drop-zone's trust; an MCP server goes live only through `connect {add:{kind:"mcp",…}}` (the `mcp-servers` skill). The provenance note is a record for humans and agents — the runtime does not read it — and a re-import overwrites local edits, so keep those as a separate note or patch. Put `skills/`, `agents/`, `rules/`, `instructions/`, `docs/` at the import root and prove it loads.
 
 **Governance precedes ingestion.** This applies equally to an organisation-wide corpus and a single user's private data. Before any copy or sync, verify the owner and approved location, intended audience and source scope, sensitivity and retention, credential scope, copy permission, and provenance/refresh record. Public web text remains untrusted data, not instruction, and public availability is not permission to collect sensitive personal data. If copying is denied, create nothing and index nothing.
 
@@ -94,7 +96,7 @@ None of this touches a `type: "source"` entry. A filesystem kind is registered a
 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 `pnpm neuralis:mount add` callout and the Browse button;
+   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
@@ -223,4 +225,4 @@ Two rules you never write are synthesized for every package: a **trust-tier ceil
 
 ---
 
-Public reference: [connectors](https://docs.neuralisapp.com/docs/package-system/connectors) · [URI policies](https://docs.neuralisapp.com/docs/package-system/uri-policies) · [sources and connectors in the brain](https://docs.neuralisapp.com/docs/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/sources-and-connectors)

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

@@ -56,7 +56,7 @@ dist  tools  workflows  skills  rules  instructions  agents  docs  team  hooks.j
 
 npm does no directory inference here, and a dev symlink hides the omission completely.
 
-> **Symptom:** everything works from a source checkout, then after `npm pack` / install / container build the package loads with **zero tools and zero skills and no error at all** — discovery found no folders. `team` and `app` are most-forgotten: no `team` ships no characters, no `app` ships no UI.
+> **Symptom:** everything works from a source checkout, then after `npm pack` / install / container build the package loads with **zero tools and zero skills and no error at all** — discovery found no folders. `team` and `app` are most-forgotten: no `team` ships no characters, no `app` ships no UI and no dock picture.
 
 Diff `files` against the folders that exist before every publish. Directory drops and source packages are unaffected — no tarball step.
 
@@ -175,7 +175,7 @@ A tool name is one key for the whole deployment, so two packages — or a packag
 
 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 `pnpm 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 `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.
 
 ## `dataLayout` — say where you keep your files
 
@@ -183,7 +183,7 @@ So **pick a name nobody else will pick**. Prefix by domain, not by convenience
 "dataLayout": { "directories": ["cache", "state"] }
 ```
 
-If your package writes under its own `data://` zone, declare the first-level directory names — this is the ONE channel through which a fresh delegate (no `<workspace>`, no identity file) learns the layout exists: every agent's `<runtime_stack>` carries a `data_areas` row per visible package, built from this field alone. Names only, never descriptions or paths; `agentDirectories` is the per-agent variant (`<zone>/<agentId>/<name>/`) for a package that keys a subtree by agent id. The validator is fail-closed: a `..`, a separator, a placeholder, a brace, whitespace or a duplicate rejects the WHOLE manifest. Your zone root is `data://<slug>/` for a first-party package and `data://_installed/<slug>/` for every other install class — never `data://<id>/`. An empty declaration renders no row.
+If your package writes under its own `data://` zone, declare the first-level directory names — this is the ONE channel through which a fresh delegate (no `<workspace>`, no identity file) learns the layout exists: every agent's `<runtime_stack>` carries a `data_areas` row per visible package, built from this field alone. Names only, never descriptions or paths; `agentDirectories` is the per-agent variant (`<zone>/<agentId>/<name>/`) for a package that keys a subtree by agent id. The validator is fail-closed: a `..`, a separator, a placeholder, a brace, whitespace or a duplicate rejects the WHOLE manifest. Your zone root is never `data://<id>/`: `data://<slug>/` for `@neuralis/<slug>`, `data://runtime/_npm/<npm id>/` for another npm install, and for a project instance its id's mirror, `data://runtime/<scheme>/<path>/` (`packages://acme` → `runtime/packages/acme`). An empty declaration renders no row.
 
 `"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.
 
@@ -208,6 +208,7 @@ A package the host installs as a dependency can declare the moments a person sho
 
 - **`requires.features` is required** — name the feature of the route that serves the same record. A reader without it never receives the event, whatever your predicate says.
 - **`dock`** is the id of one of your OWN `kind: "dock"` surfaces; its badge counts the unread notifications.
+- **`notify.clears`** (optional) lists your OWN event ids this one resolves — a `…recovered` that clears `…failed`. When it reaches a reader allowed to see it, their unread rows of those types about the SAME `subjectId` are marked read (kept in history), even if they muted the recovery itself. Never the event itself, never another package's id.
 - **Each `subject` needs `src/events/<subject>.ts`** (compiled to `dist/src/events/`): `export const subject`, a REQUIRED `visible(event, session, state)` answering whether this person may see an event about that subject — no file means every event of the subject is dropped — and an optional `bridge(publish, state)` that subscribes to your own internal bus, calls `publish({ event, subjectId, projectId, data, audience })` and returns its unsubscribe.
 - **An event is a signal, never content.** `data` holds ids and fixed codes, validated against `dataSchema` (a closed object, at most 4 KiB) — never an error message, a path or a transcript. The platform stamps `type` and `source` from your package, so you cannot emit another package's events, and a publish that breaks the schema throws.
 - **Two optional `data` keys shape the notification row** when your `dataSchema` declares them: `title` (a string, shown before the declaration title) and `nav` (`{ "widgetType": "<a widget>", "initialState": { … } }`, the row's navigation target). Without them the row shows the declaration title alone.
@@ -230,4 +231,4 @@ A malformed **hook** is skipped with a warning and the package still loads. A ma
 
 When nothing appears at all, re-check the two silent ones first: the `files` whitelist, and a category-folder markdown file with no `id`/`name`.
 
-Public reference: <https://docs.neuralisapp.com/docs/package-system/manifest> and <https://docs.neuralisapp.com/docs/package-system/directory-contract>.
+Public reference: <https://docs.neuralisapp.com/package-system/manifest> and <https://docs.neuralisapp.com/package-system/directory-contract>.

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

@@ -62,11 +62,11 @@ export function api(state: NotesState) {
 - **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.
 - **`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/<packageSlug>/`, 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, 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.
 
 **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: `_installed/<your-slug>` for a project package, the bare name for a first-party one) → 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 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.
 
 `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.
 
@@ -166,11 +166,11 @@ 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/docs/agent-core/api-usage> ·
-<https://docs.neuralisapp.com/docs/brain-core/api-usage> ·
-<https://docs.neuralisapp.com/docs/admin/features-and-routes> ·
-<https://docs.neuralisapp.com/docs/machine-core/api-usage> — mechanism:
-<https://docs.neuralisapp.com/docs/package-system/routes>.
+<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/package-system/routes>.
 
 `callRoute` denials return `{ ok: false, error: '…' }` rather than throwing — a
 handler that ignores the `ok` flag looks like it succeeded.
@@ -275,7 +275,7 @@ platform's own packages and links them for you.
 a `build` script (and `build:ui` → `neuralis-build ui` when you declare `app.module`), `files[]`
 naming every first-level runtime folder, the kernel as a peer, and **no `link:`/`file:` spec that
 leaves your directory** — a devDependency `link:` into a Neuralis checkout beside yours cannot
-resolve inside the build, and `pnpm neuralis:pkg add --path` refuses it with the spec named. If your
+resolve inside the build, and `neuralis pkg add --path` refuses it with the spec named. If your
 package manager installs peers automatically, a standalone install of your repository reaches for
 the kernel; with pnpm, `autoInstallPeers: false` in your own `pnpm-workspace.yaml` keeps it local.
 `pkg add` also runs the runtime's own admission check on the directory before it writes anything —
@@ -362,4 +362,4 @@ Hooks are declared in one package-root `hooks.json` shaped `{ "hooks": [ … ] }
 
 ---
 
-Public reference: [routes](https://docs.neuralisapp.com/docs/package-system/routes) · [lifecycle](https://docs.neuralisapp.com/docs/package-system/lifecycle) · [sessions](https://docs.neuralisapp.com/docs/package-system/sessions) · [sandboxed package build](https://docs.neuralisapp.com/docs/package-system/wasm-build)
+Public reference: [routes](https://docs.neuralisapp.com/package-system/routes) · [lifecycle](https://docs.neuralisapp.com/package-system/lifecycle) · [sessions](https://docs.neuralisapp.com/package-system/sessions) · [sandboxed package build](https://docs.neuralisapp.com/package-system/wasm-build)

package/skills/create-package/references/skills-and-context.md

@@ -138,8 +138,8 @@ execution: the activation envelope can supply a directory URI for an exec-capabl
 that URI with a relative script, and never pass the sentinel as `cwd`.
 
 **Authenticating back to the platform from app/host execution:** the script carries a
-per-stream `NEURALIS_SESSION_TOKEN`, holding the caller’s real identity, re-minted per call. Use it. The ticket authenticates ONLY package routes under `/api/packages/<package-id>/…`; host-level `/api/*` routes (projects, auth, admin) reject it by design. **Never invent a bearer token and never ask the user for one.** `credentials:` is for **external** secrets only — each entry is both the credential-store id and the env-var name projected into the child process. A miss is non-fatal: it renders `(missing: <id>)` and is reported in the activation result, and the model never sees a value. **Credentials pushed by an activation are conversation-scoped and outlive the turn**;
-app/host shell calls receive the union of still-active skills. Clear them with
+per-stream `NEURALIS_SESSION_TOKEN`, holding the caller’s real identity, re-minted per call. Use it. The ticket authenticates ONLY package routes under `/api/packages/<package-id>/…`; host-level `/api/*` routes (projects, auth, admin) reject it by design. **Never invent a bearer token and never ask the user for one.** `credentials:` is for **external** secrets only — each entry is both the credential-store id and the env-var name projected into the child process. A miss is non-fatal: it renders `(missing: <id>)` and is reported in the activation result, and the model never sees a value. **Credentials pushed by an activation are scoped to the conversation and the caller, and outlive the turn**;
+app/host shell calls receive the union of the caller's still-active skills. Clear them with
 `args.deactivate=true`. **Connector execution receives no platform ticket, credential env or
 non-secret substitution env**, and a provider may refuse caller `env` or background execution
 entirely — never promise that a platform-authenticated script runs there unchanged.
@@ -345,4 +345,4 @@ Two parsers run on the same file: **discovery** keeps every top-level key, **act
 
 ---
 
-Full public reference: **https://docs.neuralisapp.com/docs/package-system/skills** — and the five-category contribution contract at **https://docs.neuralisapp.com/docs/package-system/contributions**.
+Full public reference: **https://docs.neuralisapp.com/package-system/skills** — and the five-category contribution contract at **https://docs.neuralisapp.com/package-system/contributions**.

package/skills/create-package/references/surfaces-and-design.md

@@ -15,7 +15,7 @@ Every surface lives in `package.json` under `neuralis.app.surfaces[]` — a unio
 | kind | required | useful optional |
 |---|---|---|
 | `widget` | `kind`, `id`, `type`, `title`, `component` | `icon`, `layout`, `chrome`, `open`, `defaultOpen`, `requires` |
-| `dock` | `kind`, `id`, `label`, `action` | `icon`, `position`, `section`, `dock`, `tooltip`, `color` |
+| `dock` | `kind`, `id`, `label`, `action` | `icon`, `image`, `position`, `section`, `dock`, `tooltip`, `color` |
 | `card` | `kind`, `id`, `type` | `title`, `render`, `match`, `bridge` |
 
 **Every icon comes from ONE platform library** — about 270 curated lucide names in categories, the `ICON_LIBRARY` export of `@neuralis/package-system/icons`. Write the PascalCase name (`ChartLine`) or its lucide-kebab form (`chart-line`); a few aliases (`layout`, `terminal`, `admin`) also resolve. The same rule covers a surface `icon`, a team member's `appearance.icon` and a workflow template's `icon`. Any other name renders the fallback glyph, warns at load, and is an ERROR in `check-package.sh`.
@@ -68,6 +68,8 @@ The smallest complete, **reachable** UI a project-dropped package can ship. Four
 
 **Gate the widget, not the dock entry** — dock visibility inherits the target widget's `requires.features` automatically. Duplicating `requires` only creates drift: a user holding the widget's features but not your accidentally-different dock feature gets a widget they can never open.
 
+**An app picture is optional: `"image": "app/shared/<name>.png"`.** A PNG, JPEG or WebP under `app/shared/`, at most 256 KiB, each path segment letters, digits, `.`, `_` or `-`. The dock, the app menu and the inbox show it in a fixed-size box to whoever can see the dock entry; keep the `icon` glyph — it renders until the picture arrives and whenever it cannot be shown. The platform judges the BYTES, never the extension: an SVG, a renamed document or an oversized file is not served and the glyph stays. An invalid path (absolute, remote, outside `app/shared/`, `..`, a non-raster extension) is a validation error that fails the whole package. `check-package.sh` checks the path, the file and its bytes.
+
 ## Task: pick a renderer
 
 **Two renderers exist, and both render.** There is no third option and no placeholder tier: `inline-html` and `wasm-ui` were removed from the contract, and a manifest still declaring one is rejected outright — *renderer 'inline-html' was removed; ship the HTML asset and declare renderer 'iframe' with a relative url*. A leftover `fallback` key is inert and warned about. (WASM remains the **tool/route** sandbox runtime; there has never been a WASM UI engine, and one can no longer be declared.)
@@ -117,7 +119,7 @@ Five things to know before you use it:
 - **Budgets: 64 distinct paths and 8 MiB per SCOPE**, and the lane is `no-store`, so every render refetches the whole set. The preflight errors past both numbers and warns past 1 MiB — but it counts only your SURFACE tree, while the runtime budget also charges every `app/shared/` file your entry pulls in, so a shared-heavy bundle can pass authoring and still be refused at request time. The per-file 2 MiB cap applies in both modes.
 - **Still no remote origins.** The CSP names none, so a CDN script or a Google font is blocked before the request leaves. Ship the file.
 
-`app/shared/` is a declared **package-public** namespace: any visible surface of the package may read it, so nothing feature-private belongs there.
+`app/shared/` is a declared **package-public** namespace: any visible surface of the package may read it, and a declared dock picture is served from it, so nothing feature-private belongs there.
 
 ## The silent failures — symptom first
 
@@ -167,7 +169,7 @@ Asset serving is authenticated per request, scope-bound, traversal-safe, `Cache-
 
 *Symptom of omitting `color-scheme` or an explicit height:* the frame collapses to the HTML default 150px, and the browser paints an opaque **white** backdrop behind a cross-origin frame whose colour scheme differs from the dark workspace. Declare `color-scheme: dark light` at **every** nesting level — outer element and embedded document both.
 
-Host CSS custom properties (`--color-text`, `--w-bg-rgb`, `--icon-accent`, `--control-surface`, …) reach `direct`-rendered components only; there, never hardcode a hex — three themes ship — and `--w-bg-rgb` is comma-separated channels: `rgba(var(--w-bg-rgb), 0.55)`.
+Host CSS custom properties (`--color-text`, `--w-bg-rgb`, `--icon-accent`, `--control-surface`, …) reach `direct`-rendered components only; there, never hardcode a hex — four themes ship, independently selected for widgets, docks and background — and `--w-bg-rgb` is comma-separated channels: `rgba(var(--w-bg-rgb), 0.55)`. Every theme is dark polarity (white text), so design once for the dark design.
 
 ### Design floor
 
@@ -176,13 +178,14 @@ Host CSS custom properties (`--color-text`, `--w-bg-rgb`, `--icon-accent`, `--co
 - **Never override workspace chrome** (dock, panel headers, resize handles) or ship a per-component scrollbar override — one overlay-scrollbar rule with a stable gutter already covers it. Stay inside your panel's stacking context: the panel establishes one for you (`isolation: isolate`, at every transparency level), so your `z-index` values are scoped to your own surface and can never outrank the dock or the workspace's loading scrim. Do not try to escape it with a large `z-index`.
 - **A `position: fixed` overlay MUST `createPortal(…, document.body)`.** The panel emits a `backdrop-filter` at `dim` and at `opaque` (the latter is load-bearing and stays), none at `transparent` — and a filter makes the panel a containing block for `fixed` descendants, so at two of the three levels a `fixed` overlay anchors to your PANEL and is clipped to its rounded box, while at `transparent` it anchors to the viewport. The panel's `position: relative` covers `absolute` but never `fixed`. Symptom of skipping the portal: your modal is a widget-sized, corner-clipped rectangle for one user and a full-screen overlay for the next, purely because they cycled transparency. Portalling fixes it at **all three** levels, and `absolute` overlays need no portal at all. **One exception — a click-outside catcher for a popover that stays INSIDE the panel:** do not portal a scrim for it. The popover lives in the panel's isolated stacking context, so a body-level scrim paints over the popover and swallows its clicks; use a capture-phase `mousedown` listener on `document` that ignores targets inside the popover's zone instead — it needs no element, covers the real viewport, and closes on a click outside the widget too.
 - **No idle infinite animation** — it burns frames and breaks automated click stability. Inside the chat timeline — and inside ANY virtualized row your package renders, a file-tree row included — the rule is harder and it has no exception for "but it is still running": **a card in a timeline row must not animate `transform`, `opacity`, `filter`, `background-color` or `clip-path` at all — live or settled.** Those are the properties the browser accelerates, and they are exactly what a utility class like `animate-spin` or `animate-pulse` compiles to: the element becomes its own compositor layer, every row painted after it is pushed into another, and a fast wheel fling presents those layers at different generations (a glyph floating between rows, the next row drawn inside your card). A long-running tool multiplies it — several cards animating for minutes is several layers for minutes. A spinner still belongs to the tool call while it runs, but express it with something the compositor does not accelerate. The platform's own Files tree obeys the same floor — its virtualized rows import these primitives instead of an `animate-*` utility. **A `direct` card should not roll its own:** `@neuralis/agent-core/app/chat` exports the four live-motion primitives the platform's own cards use — `LiveSpinner` (a rotating arc), `LivePulseDot` (a pulsing status dot), `LiveCursor` (a streaming text caret) and `LivePulseText` (a pulsing line of text). Each takes its size and colour from `className` alone, so it drops into your layout at the box you give it (pass a `text-…` colour to the two that paint a shape — they fill with `currentColor`, not a background). If you do build your own, the mechanisms that work are SVG SMIL (`<animateTransform>`, or `<animate>` on `fill-opacity`, neither of which the compositor accelerates — note that element `opacity` DOES accelerate and `fill-opacity` does not) and a CSS keyframe on `color`. An `iframe` card is its own document and cannot import them; keep its body still and let the card header's status icon carry "this is running". A result state (`pending_review`, a parked approval) is the status icon's accessible name, never motion at all. **Truncate in flex and table cells**, and respect your declared `layout.minWidth` / `minHeight`.
+- **Show honest, fresh state.** A counter, status, badge or button never shows a stale or false value — re-read it from the event or route that owns it — and an action that cannot run right now is rendered disabled with its reason, never offered.
 - **Design for a panel, not a page.** A panel is a few hundred pixels tall: three or more sections belong in a two-pane layout — a navigation rail plus one swapped content pane owning the only scroll container — never one long scrolling column.
 
 ### Chrome facts to design around
 
 `chrome.mode` is `toolbar` (default), `frameless` or `floating`. All three render the **same** host control strip, differing only in placement and visibility. `toolbar`/`floating` wrap content with padding and automatic scroll; **`frameless` clips content with no padding and no scrollbar** — the widget root owns its scroll and padding and must reserve roughly 4rem at the top right. *Symptom of ignoring it:* your top-right controls sit under the hover-revealed host strip and become unclickable, and content is cut off with no way to scroll. Iframe widgets usually want `frameless`.
 
-**The close (X) button minimises; it does not destroy.** The widget stays mounted off-screen and survives a refresh. *Symptom:* reopening shows it exactly as it was, "fresh start" initialisation never runs, and teardown in an unmount handler never fires. True destroy is the dock item's hover trash. **Exception for `renderer: "iframe"` widgets:** only the React subtree stays mounted — the frame itself is detached from the document while minimised (and on a stage-mode switch), so the browser discards its browsing context and the frame reloads from the same URL with everything inside it gone. *Symptom:* your in-frame bootstrap DOES re-run and any in-frame in-memory state is lost. Make an iframe widget's bootstrap re-runnable and persist state server-side or in the frame's own storage.
+**The close (X) button minimises; it does not destroy.** The widget stays mounted off-screen and survives a refresh. *Symptom:* reopening shows it exactly as it was, "fresh start" initialisation never runs, and teardown in an unmount handler never fires. True destroy is the dock item's clean (broom) control. **Exception for `renderer: "iframe"` widgets:** only the React subtree stays mounted — the frame itself is detached from the document while minimised (and on a stage-mode switch), so the browser discards its browsing context and the frame reloads from the same URL with everything inside it gone. *Symptom:* your in-frame bootstrap DOES re-run and any in-frame in-memory state is lost. Make an iframe widget's bootstrap re-runnable and persist state server-side or in the frame's own storage.
 
 Transparency resolves per-instance override → manifest `chrome.transparent` → the user's Layout default → opaque; the cycle control is hidden when `chrome.userTransparency: false` or the package is untrusted. **The level is a user setting your surface cannot read, and it changes the panel's CSS containment**: the panel emits a `backdrop-filter` at `dim` and `opaque` (not at `transparent`), so at those two levels it is a containing block for `position: fixed` descendants. Design so the level never matters — portal every `fixed` overlay to `document.body` (see the Design floor above). The panel's stacking context does not vary: it is isolated at every level.
 
@@ -273,7 +276,7 @@ registerCardComponent('thing.result', ThingCard, {
 
 `component.import` resolves through a client-side host registry the package populates from its runtime UI module: declare `app.module`, build `app/host.tsx` with `neuralis-build ui`, and the host imports the module and calls each `install…HostComponents({ registry, port })` export with a registry that accepts only your own package's registrations. Every `component.import` your manifest declares must be registered somewhere under `app/`, or the surface resolves to null and shows the placeholder — no error. A module built before a platform upgrade can be refused (its record names an older host API or no React major): rebuild it with `neuralis-build ui`.
 
-The component receives exactly `{ agentId, widgetId, state }`; everything else comes from the workspace host port captured at install time — project/user ids, agents, `openWidget`, `updateWidgetState`, `getGrantedFeatures`, `useVisibleSkills`, and `subscribeRealtime({ channel, projectId, agentId?, onEvent })` over `runtime | presence | workflow | filesystem | conversation | project` (plus the optional `isRealtimeConnected()` for that connection's current state — treat its absence as "may be disconnected"). If your package keeps its own client store keyed on the active project/agent, subscribe to the optional `onClientStateReset(handler)` at install time: the dock's clean (broom) control fires it at widget level (with the widget `type` — reset only on YOUR type), agent level and project level, and your handler drops that scope's client state (persisted tabs included) without calling the host back or touching the server. A host without the method never resets you; assume nothing. HTTP goes through the generic package API client, which injects the project and agent headers.
+The component receives exactly `{ agentId, widgetId, state }` — `agentId` is the window's BOUND agent (fixed for that window, never the workspace's active one) and `widgetId` names the window; everything else comes from the workspace host port captured at install time — project/user ids, agents, `openWidget`, `updateWidgetState`, `getGrantedFeatures`, `useVisibleSkills`, and `subscribeRealtime({ channel, projectId, agentId?, onEvent })` over `runtime | presence | workflow | filesystem | conversation | project` (plus the optional `isRealtimeConnected()` for that connection's current state — treat its absence as "may be disconnected"). A widget can be open in SEVERAL windows (unless its manifest sets `open.singleton: true`): keep one client store PER WINDOW, keyed on `widgetId` and the bound `agentId`, never one global store read through the active agent — two windows must never share a selection, a draft or a late response. `openWidget({ agentId, type, title, target? })` picks the window: absent or `'default'` is the most recently focused window of that type bound to that agent (opened only when none exists), `'new'` always opens another (a singleton answers as `'default'`), and `{ instanceId }` is exactly that window. Subscribe to the optional `onClientStateReset(handler)` at install time: the dock's clean (broom) control fires it at four levels — `instance` (clean ONE window, `instanceId`; the window stays open), `widget` (that window is closed; reset only on YOUR `widgetType`), `agent` and `project` — and your handler drops that scope's client state (persisted tabs included) without calling the host back or touching the server. A host without the method never resets you; assume nothing. HTTP goes through the generic package API client, which injects the project and agent headers — build it from the window's bound agent.
 
 ### Offer the skill next to the button that does the same thing
 
@@ -309,4 +312,4 @@ Then fetch the runtime snapshot with the `x-project-id` header and confirm it li
 
 ---
 
-Full public reference: <https://docs.neuralisapp.com/docs/package-system/app-surfaces>
+Full public reference: <https://docs.neuralisapp.com/package-system/app-surfaces>

package/skills/create-package/references/team-and-workflows.md

@@ -19,7 +19,7 @@ team/<slug>/
 
 Discovery scans `team/*/` at package root and walks `identity/**` and `files/**` recursively, on **both** the installed-package path and the project `_packages/` drop path. **Source markdown packages cannot carry a `team/` folder** — their vocabulary is only skill / instruction / rule / agent / docs. The `.md` match is **case-sensitive**: a `SOUL.MD` never reaches the agent, with no error. Discovery skips symlinks, and a `member.json`'s own `slug` must be a single safe path segment.
 
-**The template paths are a validated contract, not free text.** Whether discovered or declared inline, every `identityFiles` / `memberFiles` entry must be package-RELATIVE: no `..` or bare `.` segment, no absolute prefix, no backslash, no control character, at most 512 characters, at most 64 entries per list. A manifest that breaks any of these is a load ERROR and the package registers **nothing** — not a partial load. (Precisely: nothing enters the PACKAGE REGISTRY. It is not content quarantine — markdown inside a directory synced as a source is still discovered by the source-package scanner, which reads no manifest, so a rejected drop's `skills/**` can still reach an agent's context under a `source:packages://<slug>` id. Live-measured 2026-08-24.) The reason is worth knowing while you author: these strings become a file read performed by the platform process itself, which reaches further than the person installing your package, so they are checked before the join and resolved against the package root again at provision time. A path that will not resolve inside the package refuses the whole provision with `team_member_path_escape`.
+**The template paths are a validated contract, not free text.** Whether discovered or declared inline, every `identityFiles` / `memberFiles` entry must be package-RELATIVE: no `..` or bare `.` segment, no absolute prefix, no backslash, no control character, at most 512 characters, at most 64 entries per list. A manifest that breaks any of these is a load ERROR and the package registers **nothing** — not a partial load. (Precisely: nothing enters the PACKAGE REGISTRY. It is not content quarantine — markdown inside a directory synced as a source is still discovered by the source-package scanner, which reads no manifest, so a rejected drop's `skills/**` can still reach an agent's context under its source-package id. Live-measured 2026-08-24.) The reason is worth knowing while you author: these strings become a file read performed by the platform process itself, which reaches further than the person installing your package, so they are checked before the join and resolved against the package root again at provision time. A path that will not resolve inside the package refuses the whole provision with `team_member_path_escape`.
 
 ### `member.json` — the complete field set
 
@@ -184,4 +184,4 @@ Installing a template is always **explicit**: it instantiates a mutable entry ow
 
 ---
 
-Public reference: [Workflows](https://docs.neuralisapp.com/docs/agent-core/workflows) · [Contributions, including team members](https://docs.neuralisapp.com/docs/package-system/contributions) · [Agent files and delegation](https://docs.neuralisapp.com/docs/agent-core/agents)
+Public reference: [Workflows](https://docs.neuralisapp.com/agent-core/workflows) · [Contributions, including team members](https://docs.neuralisapp.com/package-system/contributions) · [Agent files and delegation](https://docs.neuralisapp.com/agent-core/agents)

package/skills/create-package/references/test-and-ship.md

@@ -38,7 +38,7 @@ when it was not. Exit `0` no errors · `1` errors · `2` usage. Passing proves n
 or discovery, in either mode.
 
 After the restart, rescan or sync: `bash ${SKILL_DIR}/scripts/verify-loaded.sh <package-id>` — the
-manifest id for (a) and (b), `source:<rootUri>` for (c) (§2).
+manifest id for (a), the instance URI for (b) and (c) (§2).
 
 ---
 
@@ -68,10 +68,10 @@ tool handlers return.
 
 **A source package (path c) has no row in that table.** It never passes through the loader, so it
 has no status, no `reason` of that kind and no load line — done-gate step 1 for it is "it appears in
-the packages overview", not "it loaded". It is listed there under `sourcePackages[]`, keyed by the
-id **`source:<rootUri>`**: the literal prefix `source:` plus the package ROOT's URI, no trailing
-slash. A package rooted at `data://acme-pack` is `source:data://acme-pack`; one rooted at the source
-root itself is `source:data://`. Pass that id to `verify-loaded.sh` and it prints the root, the
+the packages overview", not "it loaded". It is listed there under `sourcePackages[]`, keyed by its
+instance id: the package ROOT's URI, no trailing slash, plus `?project=<p>&scope=<scope>`. A
+package rooted at `data://acme-pack` is `data://acme-pack?project=<p>&scope=project`; one at the
+source root itself is `data://?project=<p>&scope=project`. Pass that id to `verify-loaded.sh` and it prints the root, the
 grouping reason and the per-category file counts in place of a status.
 
 Where to read it without server-log access:
@@ -297,15 +297,15 @@ you publish.
 
 **(a) Installed node package — first-party, in-process.** Build so the compiled output exists (or
 leave a directory to the image build, which builds it), then have an admin register it as a
-dependency of the host — register, rebuild the image (`pnpm neuralis:rebuild` installs it), verify.
+dependency of the host — register, rebuild the image (`neuralis rebuild` installs it), verify.
 That sequence is the **deploying admin's terminal work, not yours**; registering a directory or a
 tarball runs the loader's own admission check first, so fix what it names. The host command depends
-on the package's registry channel: `pnpm neuralis:pkg add <identity> --version <v>` (an EXACT
+on the package's registry channel: `neuralis pkg add <identity> --version <v>` (an EXACT
 version) for an npm-channel package; the `neuralweb download <identity>@<v> --out <tgz>` +
-`pnpm neuralis:pkg add <identity> --tarball <tgz>` pair for an internal-channel one; and a
+`neuralis pkg add <identity> --tarball <tgz>` pair for an internal-channel one; and a
 direct-upload package has **no builtin rail at all** — upload is declarative-only by construction
 and never joins the in-process class. (Where the operator has the `neuralweb` CLI,
-`neuralweb install <identity> --channel builtin` prints exactly these commands with a trust notice
+`neuralweb install <identity> --channel builtin` prints these commands with a trust notice
 and never executes anything.) **Registering the dependency IS the trust act**: every dependency
 whose own `package.json` carries a `neuralis` block is discovered at boot and loaded in-process
 with host-assigned first-party trust — the same trust as the platform's own packages. Do it only
@@ -349,7 +349,7 @@ Worked example — a one-skill package needing no other file:
 
 ```text
 data://acme-pack/skills/release-notes/SKILL.md   → root data://acme-pack   (category-dirs)
-                                                 → id   source:data://acme-pack
+                                                 → id   data://acme-pack?project=<p>&scope=project
 ```
 
 **Write it with `execute` (`action: "shell"`), not `fs_write`.** An agent's `fs_write` with content
@@ -384,12 +384,12 @@ invisible, with **no error anywhere** — indistinguishable from correctly hidde
   Until then the files are on disk but the package will not appear."*
 
 **Then prove it with the script** — it is the authoritative check:
-`bash ${SKILL_DIR}/scripts/verify-loaded.sh source:data://acme-pack`. It reads the overview surface,
+`bash ${SKILL_DIR}/scripts/verify-loaded.sh 'data://acme-pack?project=<p>&scope=project'`. It reads the overview surface,
 which lists every discovered source package and reports each category as `N (M active)`. Once the
 sync has landed the package shows on the next stream — discovery is resolved fresh each time.
 
 Your own `<packages>` block is the second opinion, and it is the one that lies. A visible package
-renders there as `source:data://acme-pack [active, source]` followed by its root and
+renders there short, `data://acme-pack [active, source]`, followed by its root and
 `acme-pack (category-dirs)` — but switched-OFF files are dropped from the listing, and a package
 with **nothing** visible left is omitted **entirely**, header and all. Remember the opt-in defaults:
 rule files and identity instructions arrive switched OFF (docs stay on, but are manual-invocation
@@ -498,6 +498,6 @@ evidence.
 
 ---
 
-Public reference: <https://docs.neuralisapp.com/docs/package-system/testing> ·
-registry: <https://docs.neuralisapp.com/docs/package-system/marketplace> ·
-the three contract examples: <https://docs.neuralisapp.com/docs/package-system/reference-package>
+Public reference: <https://docs.neuralisapp.com/package-system/testing> ·
+registry: <https://docs.neuralisapp.com/package-system/marketplace> ·
+the three contract examples: <https://docs.neuralisapp.com/package-system/reference-package>

package/skills/create-package/references/tools-and-schemas.md

@@ -247,4 +247,4 @@ Untrusted tools are rate-limited an order of magnitude harder and time out soone
 
 ---
 
-Public reference: <https://docs.neuralisapp.com/docs/package-system/tools>
+Public reference: <https://docs.neuralisapp.com/package-system/tools>

package/skills/create-package/scripts/check-package.sh

@@ -38,8 +38,8 @@
 #
 # USAGE  bash check-package.sh <package-root>
 # EXIT   0 = no errors (warnings may print) · 1 = ERRORs · 2 = usage / no node
-# https://docs.neuralisapp.com/docs/package-system/directory-contract
-# https://docs.neuralisapp.com/docs/package-system/source-packages
+# https://docs.neuralisapp.com/package-system/directory-contract
+# https://docs.neuralisapp.com/package-system/source-packages
 
 set -euo pipefail
 
@@ -568,10 +568,56 @@ if (man) {
   for (const [f, t] of toolCardTypes) {
     if (!byType.has(t)) warn(f, `x-neuralis.ui.cardType "${t}" matches no card surface declared here — the result falls back to the generic default card. Deliberate when the type is a host/builtin card; otherwise add {"kind":"card","id":"…","type":"${t}"}`);
   }
+  const imageDocks = docks.filter((d) => d.image !== undefined);
   if (hasShared) {
     warn(`${SHARED_DIR}/`, anyBundle
       ? `declared package-public: any visible surface of this package may read it, so no feature-private asset belongs there. It IS served — a bundle surface reaches it as '../shared/…' relative to the entry's own directory, so mind the depth (an entry at 'sub/index.html' needs '../../shared/…')`
-      : `declared package-public: any visible surface of this package may read it, so no feature-private asset belongs there. No surface here declares "assetMode":"bundle", so nothing serves it — a self-contained entry requests it with no session cookie. Declare bundle mode on the surface that needs it, or inline the asset`);
+      : `declared package-public: any visible surface of this package may read it, so no feature-private asset belongs there. No surface here declares "assetMode":"bundle", so ${imageDocks.length ? 'only the declared dock picture(s) are served from it' : 'nothing serves it'} — a self-contained entry requests it with no session cookie. Declare bundle mode on the surface that needs it, or inline the asset`);
+  }
+
+  // dock pictures — an optional raster `image` on a dock entry. The PATH rule is
+  // the platform's own (`resolveDockImagePath`), the BYTE rule its own raster
+  // sniff and 256 KiB floor (`@neuralis/package-system/web-common`); where those
+  // do not resolve from here, the check is SKIPPED and says so.
+  if (imageDocks.length) {
+    let kernel = null, raster = null;
+    for (const from of [ROOT, process.cwd(), SCRIPT_DIR]) {
+      try {
+        kernel = require(require.resolve('@neuralis/package-system', { paths: [from] }));
+        raster = require(require.resolve('@neuralis/package-system/web-common', { paths: [from] }));
+        break;
+      } catch { kernel = null; raster = null; }
+    }
+    if (!kernel || typeof kernel.resolveDockImagePath !== 'function' || !raster || typeof raster.sniffRasterImage !== 'function') {
+      F.push({ lvl: 'SKIP', f: MF, m: `${imageDocks.length} dock image(s) NOT checked — @neuralis/package-system does not resolve from here; run the check where the platform is installed` });
+    } else {
+      let sharedReal = null;
+      try { sharedReal = fs.realpathSync(at('app', 'shared')); } catch { /* no app/shared */ }
+      for (const d of imageDocks) {
+        const L = `dock "${d.id || '(no id)'}" image`;
+        const resolved = typeof d.image === 'string' ? kernel.resolveDockImagePath(d.image) : { ok: false, error: 'not a string' };
+        if (!resolved.ok) {
+          err(MF, `${L} is not a valid picture path (${resolved.error}) — declare a relative path under '${SHARED_DIR}/' naming a .png, .jpg, .jpeg or .webp file (letters, digits, '.', '_', '-' per segment). The package does NOT load with this value`);
+          continue;
+        }
+        let real = null;
+        try { real = fs.realpathSync(at(...resolved.path.split('/'))); } catch { /* missing */ }
+        if (!real) { err(resolved.path, `${L} is declared but not on disk — the dock shows only its glyph`); continue; }
+        if (!sharedReal || !real.startsWith(sharedReal + path.sep)) {
+          err(resolved.path, `${L} resolves outside '${SHARED_DIR}/' through a link — the platform refuses to serve it`);
+          continue;
+        }
+        const st = fs.statSync(real);
+        if (!st.isFile()) { err(resolved.path, `${L} is not a regular file`); continue; }
+        if (st.size > raster.APPEARANCE_IMAGE_MAX_BYTES) {
+          err(resolved.path, `${L} is ${st.size} bytes; a package picture is served only up to ${raster.APPEARANCE_IMAGE_MAX_BYTES} bytes (256 KiB) — downscale it, a dock tile is a few dozen pixels`);
+          continue;
+        }
+        if (!raster.sniffRasterImage(new Uint8Array(fs.readFileSync(real)))) {
+          err(resolved.path, `${L} is not a PNG, JPEG or WebP picture by its BYTES — the platform sniffs the content, never the extension, and serves nothing else (an SVG or a renamed document is refused)`);
+        }
+      }
+    }
   }
 
   // icons — a name outside the platform icon library renders the fallback
@@ -644,6 +690,6 @@ const sk = F.filter((x) => x.lvl === 'SKIP').length;
 out.write(`\n${e} error(s), ${F.length - e - sk} warning(s)${sk ? `, ${sk} check(s) SKIPPED` : ''} — ${path.basename(ROOT)}\n`);
 if (e === 0) out.write(MODE === 'manifest'
   ? 'Static checks pass — that proves NOTHING about loading. Install, then verify-loaded.sh.\n'
-  : 'Static checks pass for what markdown can carry — that proves NOTHING about discovery.\nThe files must be indexed by a sync first, then: verify-loaded.sh "source:<slug>://<path>".\n');
+  : 'Static checks pass for what markdown can carry — that proves NOTHING about discovery.\nThe files must be indexed by a sync first, then: verify-loaded.sh "<slug>://<path>?project=<p>&scope=…".\n');
 process.exit(e > 0 ? 1 : 0);
 NODE_CHECK