@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/agent-guide/tool-manuals.md

@@ -0,0 +1,227 @@
+## Tool Manuals (`{{pluginsDir}}/<Plugin>/software.bevel.hexis/tools/*.tool`)
+
+Each plugin folder holds `*.tool` files — reusable **tool manuals** that let agents call external APIs. They are **not part of the knowledge graph** (never modelled as nodes) and are access-controlled like any other file via `access.md`. Any user who can *read* a `.tool` can use its tools; anyone who can *write* it sets its shared (admin) secrets (see below). Put each manual in the plugin's `software.bevel.hexis/tools/` directory, beside
+the skills that use it. The same integration may exist in several plugins as
+separate files (`Everyone/…/serper.tool` and `Finance/…/serper.tool`), each
+with its own credentials and access rule — a plugin is a folder, not a registry
+of unique names. The manual's **id** is, though: two files that resolve to
+the same id (an explicit `id`, else `name`, else the file name) collide and
+the second is refused, so give each copy its own `id` (`serper_everyone`,
+`serper_finance`). Remember: `.tool` files are for `http` and `inline` manuals
+only; MCP servers belong in `mcp.json`.
+
+**Calling a tool: read its `Call:` line.** Tools do not share one calling
+shape — the knowledge-base tools take their arguments under a `body` object, a
+tool that calls another service takes them flat — so every tool description
+opens with one generated line showing how that tool is called, e.g.
+`Call: KNOWLEDGE_BASE.read_file({ body: { branch: "...", path: "..." } })` or
+`Call: SERPER.search({ query: "..." })`. Copy that line and fill it in, inside
+`call_tool_chain` or directly. Arguments that do not match a tool's input
+schema are refused before anything is sent, and the refusal lists what is
+wrong and gives the tool's whole interface.
+
+A `.tool` file is JSON or YAML. Its `type` decides how tools are discovered:
+
+- **`inline`** — the tools are embedded in the file (no network round-trip to list them).
+- **`http`** — `url` points to an endpoint that returns a UTCP manual.
+
+(`type: mcp` is the LEGACY spelling of an MCP server as a `.tool`. The boot
+migration converts such files into `mcp.json` entries; do not write new ones.)
+
+**The tool is the frontmatter.** A `.tool` is one `---` YAML block holding *everything* — its `id`, its access verbs (`read:`/`write:`/`owner:`/`download:`), and its config (`type`/`url`/`variables`/…) — all in the same object. Anything after the closing `---` is free-form notes the parser ignores (like a `SKILL.md` body):
+
+```yaml
+---
+id: my_tool
+write:
+  - Product Team
+owner:
+  - Jane Doe <jane@x.com>
+type: http
+url: https://api.example.com/utcp
+---
+```
+
+(A file with no `---` fence is the legacy form — the whole file is the object, so a bare JSON `.tool` still works.)
+
+**`id` = variable namespace.** The `id` is the manual's stable identity: it's the UTCP namespace secrets bind to (`<id>_<VAR>`) and its route slug. It must be lowercase `snake_case` and **unique** across all `.tool` files. Resolution is `id` → `name` → the file name (so a `name:` alone works, same as the id system uses for every file). If two files collide, the second is REFUSED, not renamed: a suffix would silently bind a configured secret to a different file, so the catalog keeps one and names the other as a duplicate until it is renamed by hand. **Access** declared here gates who can use and edit that tool, exactly like a node's own frontmatter (most specific; overrides the folder `access.md`).
+
+**Frontmatter `id` = address.** This is generic, not tool-specific: ANY `.md` or `.tool` file whose frontmatter declares an `id` (or a lowercase snake_case/kebab `name`) is addressable at `/workspace/<branch>/<id>` in the app, exactly like a knowledge node — tools, skills (`SKILL.md`), and plain notes alike. Graph nodes win an id collision; files without frontmatter stay path-addressed.
+
+**Remote vs local (`remote`).** A tool is available to remote agents by default. Add `remote: false` for a tool that only works on the user's own machine (e.g. an `http` manual whose `url` is on `localhost`): the hosted remote MCP endpoint cannot reach it, so it skips the tool and advertises it through the `list_local_tools` tool instead. (An MCP server that is local-only declares `local: true` in the plugin.json extensions block instead — see above.)
+
+To actually USE those tools, run the workspace as a local MCP server:
+
+```
+npx @bevel-software/hexis-mcp --url <workspace-url> --key <connection-key>
+```
+
+It serves everything the hosted endpoint serves **plus** the local-only tools, because it runs on the machine where they exist. Remote tools still execute on the server, so their shared keys and OAuth sign-ins keep working untouched; a local-only tool's own `${VAR}`s are fetched by `hexis-mcp` from this workspace's Secrets Vault with the connection key, and from the environment of whatever launched the command (your MCP client's config) for any the vault does not hold. Reading the `.tool` and wiring the server into your client by hand still works and is the fallback when the command is unavailable.
+
+### Referencing secrets — `${VAR}` and the `variables` block
+
+Anywhere a `.tool` needs a credential (an API key, a token) write a placeholder like `${API_KEY}`. At call time it is filled from the **Secrets Vault** under a key derived from the manual's resolved id (the same `id` → `name` → file-name resolution described above) and the variable's name: for a plain id the key is `<id>_<VAR>` — a manual whose id is `weather` referencing `${API_KEY}` reads the secret `weather_API_KEY` — while an id that contains `_` or punctuation is namespaced with every such character turned into `_` and then doubled (`serper_everyone` + `API_KEY` → `serper__everyone_API_KEY`). `list_tool_setup` and the Secrets page show the exact key each manual reads, so read it there rather than spelling it by hand. A secret is therefore bound to exactly one manual; another manual cannot read it.
+
+Declare who provisions each variable with an optional top-level `variables` array. Each entry is `{ name, scope, label? }`:
+
+- **`scope: admin`** (the **default**) — set **once by a writer** of this `.tool` file; the same value is shared by everyone who uses the tool. Prefer this: keep as much as possible owned by the tool author.
+- **`scope: user`** — set by **each end user** for themselves (their own value, never shared).
+
+`name` must match `[A-Za-z0-9_]+`. A referenced `${VAR}` that you don't declare defaults to `admin` — and it still SURFACES automatically: the app detects every `${VAR}` the file actually references and shows it in the secrets UI, so the `variables` block is only needed to change a variable's scope to `user`, give it a label, or declare an OAuth sign-in. Values are entered in the Secrets Vault UI (or the `.tool` editor's sidebar), never in the file itself. A malformed `variables` entry makes the whole file fail to load, so it is never silently mis-scoped.
+
+### Declaring an OAuth sign-in — the `oauth` block
+
+A `user`-scoped variable can be filled by **signing in** instead of by a typed value: add an `oauth` block and each member authorizes with the provider; the token then rides in whatever header references `${VAR}`. The block carries PUBLIC config only:
+
+| field | | |
+|---|---|---|
+| `clientId` | required | the OAuth app's client id — the tool owner registers the app with the provider, using the redirect URI `<backend>/api/secrets/oauth/callback` |
+| `authorizationUrl`, `tokenUrl` | **optional on an `mcp.json` server**, required in a `.tool` | leave both out on an MCP server: they are discovered from the server's own OAuth metadata. Give both or neither. |
+| `scopes` | optional | `string[]`, requested at sign-in and required back from the token |
+| `pkce` | optional, default **on** | PKCE S256 — MCP servers require it; providers without it ignore it. Only `false` is meaningful. |
+| `resource` | optional | RFC 8707 resource indicator (the MCP server URL); discovered on an `mcp.json` server |
+| `authParams` | optional | extra static authorize params, e.g. Google's `access_type: offline` |
+
+**Never** a `clientSecret` — a `.tool` carrying one fails to load, and an `mcp.json` server whose plugin.json entry carries one is dropped from the catalog. The secret is pasted once by a tool writer on the tool's page, then every member signs in on the Connect page.
+
+For an `mcp.json` server the declaration lives in `plugin.json`, in the same extensions entry as the auth header that uses it:
+
+```json
+{
+  "extensions": {
+    "software.bevel.hexis": {
+      "mcpServers": {
+        "hubspot": {
+          "headers": { "Authorization": "Bearer ${HUBSPOT_TOKEN}" },
+          "variables": [
+            { "name": "HUBSPOT_TOKEN", "scope": "user", "label": "HubSpot sign-in",
+              "oauth": { "clientId": "<the app's client id>" } }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+That is the whole declaration: endpoints, PKCE and the resource indicator come from the server. Add `authorizationUrl`/`tokenUrl` only when `list_tool_setup` reports in `setup.reason` that they could not be discovered.
+
+### Calling a Google API as a service account: `auth_type: google_service_account`
+
+Some Google APIs (Google Ads, Tag Manager, BigQuery, Sheets, …) are called as a **service account**: one shared identity, no sign-in per person. Google does not accept the service account's key on a call. It accepts a short-lived token that has to be minted from the key, so a header holding `${VAR}` cannot do it. Name the key in an `auth` block on an inline tool's `tool_call_template` instead, and the platform mints the token at call time, keeps it until shortly before it expires, and sends it as `Authorization: Bearer <token>`:
+
+```yaml
+---
+id: google_ads
+type: inline
+variables:
+  - { name: GOOGLE_SA_KEY,   scope: admin, label: "Service-account key JSON" }
+  - { name: DEVELOPER_TOKEN, scope: admin, label: "Google Ads developer token" }
+tools:
+  - name: list_accessible_customers
+    description: List the Google Ads customers the service account can reach.
+    inputs: { type: object, properties: {} }
+    outputs: { type: object, properties: {} }
+    tool_call_template:
+      call_template_type: http
+      http_method: GET
+      url: https://googleads.googleapis.com/v22/customers:listAccessibleCustomers
+      headers: { developer-token: "${DEVELOPER_TOKEN}" }
+      auth:
+        auth_type: google_service_account
+        credentials: ${GOOGLE_SA_KEY}
+        scopes: https://www.googleapis.com/auth/adwords
+---
+```
+
+| field | requirement | notes |
+|---|---|---|
+| `credentials` | required | always a `${VAR}`: the vault variable holding the key JSON Google issued for the service account (the whole file, or the file in base64). Admin-scoped, so a writer of the `.tool` stores it once on the tool's page. Never the key itself. |
+| `scopes` | required | the OAuth scopes the API needs: one scope, a space-separated list, or a list |
+| `subject` | optional | a user's email to act as, for a service account granted domain-wide delegation |
+
+The token always comes from Google's own token endpoint; a `token_uri` inside the key is ignored. Give the service account access in the Google product itself (for example add its email as a user of the Google Ads account or the Tag Manager container), or that product refuses every call with an error of its own. When Google refuses the key itself (a revoked key, a scope the account may not have, a subject without delegation), the error names the service account and Google's reason, never the key.
+
+The block works in one place: an inline tool's `tool_call_template` with `call_template_type: http`. Anywhere else (an `sse`, `streamable_http` or `mcp` template, or a `type: http` / `type: mcp` tool that discovers its tools from a `url`) no token would be sent, so the `.tool` is refused and `list_tool_setup` names it under `invalid`, saying where the block was found. It works the same for a `remote: false` tool run by the local `hexis-mcp` server, which mints the token on the machine it runs on.
+
+A service account is one shared identity. To have each person call Google as themselves instead, do not use this block: declare a sign-in variable (`oauth`, above) and send it as `Authorization: Bearer ${VAR}`.
+
+### Examples
+
+An `http` manual that authenticates with a shared org key and a per-user key:
+
+```yaml
+name: weather
+type: http
+url: https://api.weather.example/utcp
+headers:
+  Authorization: Bearer ${ORG_KEY}
+  X-User-Key: ${USER_KEY}
+variables:
+  - { name: ORG_KEY,  scope: admin, label: "Org-wide weather.com key" }
+  - { name: USER_KEY, scope: user,  label: "Your personal weather.com key" }
+```
+
+An `inline` manual with one tool:
+
+```json
+{
+  "name": "billing",
+  "type": "inline",
+  "variables": [{ "name": "BILLING_KEY", "scope": "admin" }],
+  "tools": [
+    {
+      "name": "create_invoice",
+      "description": "Create an invoice.",
+      "inputs": { "type": "object", "properties": {} },
+      "outputs": { "type": "object", "properties": {} },
+      "tool_call_template": {
+        "call_template_type": "http",
+        "http_method": "POST",
+        "url": "https://api.billing.example/invoices",
+        "headers": { "Authorization": "Bearer ${BILLING_KEY}" }
+      }
+    }
+  ]
+}
+```
+
+### Adding a third-party tool
+
+When asked to add/integrate a product as a tool (e.g. "add Notion", "wire up Linear"), **never invent an endpoint or write a placeholder URL** — a `.tool` pointing at a made-up host is useless:
+
+1. **Find the real endpoint from the vendor's own docs.** Prefer the vendor's official **remote MCP server** if one exists; otherwise fall back to their **REST API** base. No endpoint is named here on purpose — a URL copied into this file would be asserted long after it stopped being true, which is the failure this step exists to prevent. Use web search/extract to confirm the exact URL, transport, and auth scheme — don't answer from memory. If you have no web access or genuinely can't find it, **ask the user** for the endpoint URL and auth instead of guessing.
+2. **Pick the home from what you found.** An MCP server → an entry in the plugin's `mcp.json` (`type: "streamable-http"` with the official `url` — use the `https://…` URL, **never** `ws://`/`wss://`). A plain REST/HTTP endpoint → a `.tool` with `type: http`. Use `type: inline` only when hand-authoring the individual HTTP calls.
+3. **An OAuth-protected MCP server usually needs NOTHING beyond its `mcp.json` entry.** Write just those two and let the app probe the server: it discovers the sign-in provider (MCP authorization spec), registers itself, and surfaces a per-user sign-in on the Connect page. That is the `oauth-auto` case, and for it you must NOT declare `variables` or `headers`.
+
+   Some providers do not support automatic registration (`oauth-manual` — HubSpot, Google; see the walkthrough below). Those DO need a sign-in variable holding the client id of an app the owner registers, and an admin pastes the client secret on the tool's page. You do not have to guess which kind you are facing: write the two lines, then run `list_tool_setup` and read `setup.kind` — and `setup.reason`, which spells out the next step (including the redirect URI to register).
+4. **For key-based auth, wire it as `variables`, never a hard-coded secret.** Reference credentials as `${VAR}` in `headers` (e.g. `Authorization: Bearer ${NOTION_TOKEN}`) and declare each in the `variables` block with a scope (`admin` = one shared value; `user` = per-user). Users fill the values in the Secrets Vault.
+5. **Say so when a tool is reachable ONLY from the user's own machine.** For an MCP server (e.g. one on `localhost`), declare `local: true` on its entry in the plugin.json extensions block — `remote: false` is a `.tool` frontmatter field and means nothing in `mcp.json`. For an `http`/`inline` `.tool`, set `remote: false`. Otherwise leave the tool remote-capable.
+
+### Checking what an admin still needs to configure
+
+Call the **`list_tool_setup`** tool to see, for every accessible tool — `.tool` manuals and `mcp.json` servers alike — what is configured and what is still missing. Use it whenever a tool isn't working, after adding a tool, or when asked "what do I need to set up?" — then EXPLAIN the remaining steps to the user rather than guessing. Per tool it reports:
+
+- **`setup.kind`** (for MCP servers): `open` = no credentials needed; `oauth-auto` = the platform registered itself with the server automatically and users just authorize on the **Connect page**; `oauth-manual` = the sign-in uses an OAuth app the owner registers (the provider offers no automatic registration, or the declaration already names a client id). `setup.reason` is present only while something still blocks that sign-in — no declaration yet, or endpoints that could not be discovered — and says what to do.
+- **Per variable**: `adminConfigured` (the shared value — or, for a sign-in, the owner-side provider setup — is done), `userConfigured` / `authorized` (the CURRENT user's own value / sign-in), and `canWrite` (whether the current user may set the tool's shared config).
+
+**Tools are served from the default branch only.** An `mcp.json` entry or `.tool` you write on a draft is committed to that draft and nowhere else: it is not listed, not callable and has no sign-in on the Connect page until the draft is merged. After declaring a tool on a draft, call `list_tool_setup` with `branch` set to that draft — `onBranchOnly` names what is still waiting there — and tell the user it goes live once the change request is merged. A tool that stays in `tools` is released, and a restart does not remove it or its sign-ins; if one disappears, check the caller's read access to the file that declares it.
+
+**A released tool or skill is live within ten seconds — no reconnect.** A commit on the default branch that adds, changes or removes a `.tool`, an `mcp.json`, a `plugin.json` or a `SKILL.md` drops the catalogs at once, whichever way the commit arrived: the app, the file tools, a git push, or an approved change request being applied. The hosted endpoint is stateless — it reads the live catalog on every request, so the very next call sees the change. The local `hexis-mcp` server checks the workspace's catalog whenever its connection is USED — when a tool call finishes, and when a client lists the tools — and re-registers what changed, local-only servers included; on a connection in use the change is there within ten seconds of the commit — unless a tool call is still running on that connection, which holds the refresh for as long as that call runs, to a limit of fifteen seconds (see the caveat below) — and `list_tools`, `list_tool_setup` and `list_local_tools` then answer with the new state on the connection you already have. A listing runs a check and waits for it, so what you are handed is never a list a refresh is halfway through replacing; checks are collapsed to at most one every two seconds, so a listing arriving inside that window is answered from what the last check confirmed rather than from a fresh read — up to two of those ten seconds are that window alone, before the workspace has been asked anything. After a call, the change lands once that call finishes, so a new tool is callable from the call after that one. An IDLE connection is deliberately outside that window: it asks the workspace nothing about its catalog, holds nothing open beyond the one MCP session it serves tools through, and is told nothing — no catalog timer, no extra socket parked per laptop, so an unused connection costs the workspace nothing more than being connected (a browser-signed-in server still renews its own sign-in shortly before it expires, a single request every few hours) — and it catches up at its next use. Skills need no check at all: the released skill catalog is cached briefly and dropped the moment the default branch changes, so a committed `SKILL.md` is in the very next `list_skills` or `get_skill` answer, and the two resolve a skill the same way, so a skill you can load by name is a skill the listing shows.
+
+The platform also sends the MCP tool-list-changed and prompt-list-changed notifications when it can. **A client that CACHES the list it got at connect time — rather than honouring those notifications — will not see the change: it must re-list, or reconnect.** That is a property of the client, not of the workspace; if a tool you just wrote is missing, call `list_tools` again before assuming anything is wrong. One caveat on the local `hexis-mcp` server: a refresh there waits for a tool call that is still running, but only for fifteen seconds, so a commit made mid-call lands once that call finishes — or, if the call is still running after those fifteen seconds, while it is still running — and a LOCAL-only server (`local: true`, or a `type: "stdio"` command) that changed is restarted by that refresh, so a call to it made in the same moment may see it come back.
+
+The listing is scoped by the same access controls as everything else: a tool the caller can't READ doesn't appear at all, and `canWrite` means write access **on the file that declares it** — the `.tool` file itself (via its frontmatter `write:`/`owner:` verbs or the `access.md` chain), or the plugin's `mcp.json` for an MCP server (via the plugin's `access.md` chain — `mcp.json` carries no verb list of its own) — NOT any platform role. The people who manage that file are exactly the people who configure its shared secrets. To delegate a `.tool` to someone, add them to that file's `write:`/`owner:` list; to delegate an MCP server, grant them `write` on the plugin in its `access.md` (both are edits you can make via change request). That alone lets them configure it.
+
+**Agents never handle secret VALUES.** Never ask for an API key, token, or client secret in the conversation, and there is no tool to set one. Point the right person at the right surface instead:
+
+- **Shared (admin) values and OAuth client secrets** → a tool writer pastes them into the fields on the tool's page in the app (the "Your connection" section; for a `.tool` file, the setup panel is also in its editor sidebar).
+- **Per-user values and sign-ins** → each user enters/authorizes on the **Connect page**.
+
+For **`oauth-manual`** (e.g. HubSpot, Google, GitHub, Slack — no dynamic client registration), walk the admin through the one-time setup:
+
+1. Register an OAuth app in the provider's console, with redirect URI `<backend>/api/secrets/oauth/callback` (the exact URI is in `setup.reason`).
+2. Ask for the app's **client id** (public — fine to receive in chat) and write the sign-in declaration yourself: for an `mcp.json` server, the `variables` entry with `oauth: { clientId }` plus the `Authorization: Bearer ${VAR}` header in the plugin.json extensions entry (see "Declaring an OAuth sign-in" above — no URLs needed); for a `.tool`, the same entry with `authorizationUrl` and `tokenUrl` as well. You can do this edit for them via a change request. A human can do the same under "Edit server" on the tool's page — the form's fields are exactly this block.
+3. Run `list_tool_setup` again: `setup.reason` must be gone. If it says the endpoints could not be discovered, add `authorizationUrl`/`tokenUrl` from the provider's docs.
+4. The admin pastes the app's **client secret** into the "Client secret" field on the tool's page — never into the file, never into the chat.
+5. Every user then authorizes on the Connect page.

package/agent-guide/where-a-new-file-goes.md

@@ -0,0 +1,36 @@
+## Where a new file goes
+
+Decide by what the file IS, not by which folder you already hold rights in.
+Write access is not evidence that a file belongs somewhere.
+
+- **A document goes under `{{knowledgeBaseDir}}/`.** Knowledge, notes,
+  reports, tickets, specifications, plans, meeting minutes — anything written
+  to be read by a person — unless a section of this guide below, or the
+  `README.md` of a folder this deployment reserves, names a more specific
+  home for that kind of file. That is what the root is for, and its shape
+  inside is yours to choose.
+- **A shared skill goes under `{{skillsDir}}/`**, or under
+  `{{pluginsDir}}/<Plugin>/skills/<skill>/SKILL.md` when it belongs to one
+  plugin alone. A person's private skill goes in their personal plugin
+  (`my_plugin`).
+- **Tool manuals, MCP server declarations and manifests go inside a plugin:**
+  `.tool` manuals under `{{pluginsDir}}/<Plugin>/software.bevel.hexis/tools/`,
+  servers in that plugin's `mcp.json`, and `plugin.json` at its root.
+- **A plugin folder never holds a document.** `{{pluginsDir}}/` carries
+  machinery — manifests, tool manuals, server declarations, access rules, and
+  the skills a plugin owns. A ticket or a report written there is filed where
+  nobody will look for it, under rules written for tools.
+- **A personal plugin holds only its owner's skills and tools** —
+  `{{pluginsDir}}/personal-<id>/`, each skill's own bundled files (references,
+  scripts, assets) inside that skill's folder included — and never a note or
+  any other document. When the user wants knowledge kept private, ask where
+  under `{{knowledgeBaseDir}}/` it should go, and mention that a folder there
+  can be restricted so only they can read it. If they insist on the personal
+  plugin, decline and say why: a document there sits outside the knowledge
+  graph, where it is never found as knowledge again — then offer a place under
+  `{{knowledgeBaseDir}}/` once more.
+- **When the place named does not exist, or nothing fits, ask.** If the user
+  names a folder that is not there, or the file is of a kind this deployment
+  has made no home for, say so and ask where it should go. Do not settle for a
+  folder you happen to be able to write to; a wrong guess is discovered much
+  later than a question.

package/dist/assets.d.ts

@@ -2,4 +2,30 @@
 export declare function coreMigrationsDir(): string;
 /** Absolute path of the packaged KB seed template (`kb-template/`). */
 export declare function defaultKbTemplateDir(): string;
+/**
+ * The sections of the platform's agent guide, one markdown file each — the
+ * text `get_agent_guide` and a `read_file` of the guide's name serve, composed
+ * by `modules/agent-guide`. Beside `kb-template/` rather than under `src/`,
+ * so a build and the published source find it at the same place.
+ */
+export declare function agentGuideDir(): string;
+/**
+ * The MCP App views this deployment serves over `resources/read` — one static
+ * HTML file each, no build step. Beside `agent-guide/` and `kb-template/` for
+ * the same reason: a build and the published source find it at the same
+ * place, and `tsc` copies nothing that is not TypeScript.
+ *
+ * The backend serves these as BYTES and never imports frontend code — the
+ * view's whole job is to load the deployment's embed bundle into its own
+ * document (hosts forbid framing the deployment, see `mcp-app.ts`), where the
+ * app's renderers then draw the page.
+ */
+export declare function mcpAppDir(): string;
+/**
+ * The starter packs a new knowledge base may be filled from — one folder per
+ * team (`engineering/`, `sales/`, …), each a `pack.yaml` beside the pages and
+ * the plugin it adds (see `modules/onboarding/starter-packs.ts`). Beside
+ * `kb-template/` for the same reason: read at run time, shipped as files.
+ */
+export declare function defaultStarterPacksDir(): string;
 //# sourceMappingURL=assets.d.ts.map

package/dist/assets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAgBA,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}
+{"version":3,"file":"assets.d.ts","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAiBA,oEAAoE;AACpE,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED,uEAAuE;AACvE,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAEtC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,SAAS,IAAI,MAAM,CAElC;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,IAAI,MAAM,CAE/C"}

package/dist/assets.js

@@ -2,8 +2,9 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 /**
  * Locations of the assets shipped INSIDE this package (`files` in
- * package.json): the squashed core migration history (`migrations/`) and the
- * KB seed template (`kb-template/`). Both live at the PACKAGE ROOT, and this
+ * package.json): the squashed core migration history (`migrations/`), the
+ * KB seed template (`kb-template/`) and the starter packs (`starter-packs/`).
+ * All live at the PACKAGE ROOT, and this
  * module is a direct child of either `src/` (in-repo / tsx) or `dist/`
  * (compiled) — so one `..` hop from the module URL reaches the package root
  * in BOTH layouts. Resolved lazily so bundlers that rewrite `import.meta.url`
@@ -20,4 +21,36 @@ export function coreMigrationsDir() {
 export function defaultKbTemplateDir() {
     return path.join(packageRoot(), 'kb-template');
 }
+/**
+ * The sections of the platform's agent guide, one markdown file each — the
+ * text `get_agent_guide` and a `read_file` of the guide's name serve, composed
+ * by `modules/agent-guide`. Beside `kb-template/` rather than under `src/`,
+ * so a build and the published source find it at the same place.
+ */
+export function agentGuideDir() {
+    return path.join(packageRoot(), 'agent-guide');
+}
+/**
+ * The MCP App views this deployment serves over `resources/read` — one static
+ * HTML file each, no build step. Beside `agent-guide/` and `kb-template/` for
+ * the same reason: a build and the published source find it at the same
+ * place, and `tsc` copies nothing that is not TypeScript.
+ *
+ * The backend serves these as BYTES and never imports frontend code — the
+ * view's whole job is to load the deployment's embed bundle into its own
+ * document (hosts forbid framing the deployment, see `mcp-app.ts`), where the
+ * app's renderers then draw the page.
+ */
+export function mcpAppDir() {
+    return path.join(packageRoot(), 'mcp-app');
+}
+/**
+ * The starter packs a new knowledge base may be filled from — one folder per
+ * team (`engineering/`, `sales/`, …), each a `pack.yaml` beside the pages and
+ * the plugin it adds (see `modules/onboarding/starter-packs.ts`). Beside
+ * `kb-template/` for the same reason: read at run time, shipped as files.
+ */
+export function defaultStarterPacksDir() {
+    return path.join(packageRoot(), 'starter-packs');
+}
 //# sourceMappingURL=assets.js.map

package/dist/assets.js.map

@@ -1 +1 @@
-{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;GAQG;AACH,SAAS,WAAW;IAClB,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC,CAAC;AAChD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC"}
+{"version":3,"file":"assets.js","sourceRoot":"","sources":["../src/assets.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC;;;;;;;;;GASG;AACH,SAAS,WAAW;IAClB,OAAO,aAAa,CAAC,IAAI,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,oEAAoE;AACpE,MAAM,UAAU,iBAAiB;IAC/B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,YAAY,CAAC,CAAC;AAChD,CAAC;AAED,uEAAuE;AACvE,MAAM,UAAU,oBAAoB;IAClC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa;IAC3B,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,aAAa,CAAC,CAAC;AACjD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,SAAS;IACvB,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,sBAAsB;IACpC,OAAO,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,eAAe,CAAC,CAAC;AACnD,CAAC"}

package/dist/core/catalog-revision.d.ts

@@ -18,7 +18,16 @@ import '../modules/tool-auth/tool-auth.middleware.js';
  * already, but a dedupe or an access filter could reshuffle what survives, and
  * "the same set in another order" is not something a client owes a refresh for.
  */
-export declare function catalogRevision(manuals: readonly string[], skills: readonly SkillSummary[]): string;
+export declare function catalogRevision(manuals: readonly string[], skills: readonly SkillSummary[], 
+/**
+ * The MCP App views this deployment serves, by their bytes: a release that
+ * changes a view and nothing else must still move the revision, or a local
+ * server already running keeps serving the view it read at startup.
+ */
+views?: readonly {
+    uri: string;
+    text: string;
+}[]): string;
 /**
  * `GET /agent/catalog-revision` — the caller's catalog fingerprint, plus the
  * two counts behind it so an operator reading a log can tell a shrinking
@@ -35,5 +44,14 @@ export declare function createCatalogRevisionRoutes(deps: {
     manualAuth: RequestHandler;
     /** Connection-key/internal-token user id → email, for the per-caller ACL. */
     resolveUserEmail: (userId: string) => Promise<string | undefined>;
+    /** The MCP App views served; absent on a deployment that serves none. */
+    mcpApps?: {
+        manifest(): Promise<{
+            resources: readonly {
+                uri: string;
+                text: string;
+            }[];
+        }>;
+    };
 }): express.Router;
 //# sourceMappingURL=catalog-revision.d.ts.map

package/dist/core/catalog-revision.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-revision.d.ts","sourceRoot":"","sources":["../../src/core/catalog-revision.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,EAAE,EAAgB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAErE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACxF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAC;AAC3F,OAAO,8CAA8C,CAAC;AAmCtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,EAAE,SAAS,YAAY,EAAE,GAC9B,MAAM,CAOR;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,WAAW,EAAE,IAAI,CAAC,kBAAkB,EAAE,qBAAqB,CAAC,CAAC;IAC7D,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IAC1C,UAAU,EAAE,cAAc,CAAC;IAC3B,6EAA6E;IAC7E,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;CACnE,GAAG,OAAO,CAAC,MAAM,CAyBjB"}
+{"version":3,"file":"catalog-revision.d.ts","sourceRoot":"","sources":["../../src/core/catalog-revision.ts"],"names":[],"mappings":"AACA,OAAO,OAAO,EAAE,EAAgB,KAAK,cAAc,EAAE,MAAM,SAAS,CAAC;AAErE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACxF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,kDAAkD,CAAC;AAC3F,OAAO,8CAA8C,CAAC;AAmCtD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAC7B,OAAO,EAAE,SAAS,MAAM,EAAE,EAC1B,MAAM,EAAE,SAAS,YAAY,EAAE;AAC/B;;;;GAIG;AACH,KAAK,GAAE,SAAS;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,EAAO,GACnD,MAAM,CASR;AAED;;;;;;;;;GASG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE;IAChD,WAAW,EAAE,IAAI,CAAC,kBAAkB,EAAE,qBAAqB,CAAC,CAAC;IAC7D,MAAM,EAAE,IAAI,CAAC,aAAa,EAAE,YAAY,CAAC,CAAC;IAC1C,UAAU,EAAE,cAAc,CAAC;IAC3B,6EAA6E;IAC7E,gBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAClE,yEAAyE;IACzE,OAAO,CAAC,EAAE;QAAE,QAAQ,IAAI,OAAO,CAAC;YAAE,SAAS,EAAE,SAAS;gBAAE,GAAG,EAAE,MAAM,CAAC;gBAAC,IAAI,EAAE,MAAM,CAAA;aAAE,EAAE,CAAA;SAAE,CAAC,CAAA;KAAE,CAAC;CAC5F,GAAG,OAAO,CAAC,MAAM,CA4BjB"}

package/dist/core/catalog-revision.js

@@ -48,11 +48,19 @@ function skillFingerprint(s) {
  * already, but a dedupe or an access filter could reshuffle what survives, and
  * "the same set in another order" is not something a client owes a refresh for.
  */
-export function catalogRevision(manuals, skills) {
+export function catalogRevision(manuals, skills, 
+/**
+ * The MCP App views this deployment serves, by their bytes: a release that
+ * changes a view and nothing else must still move the revision, or a local
+ * server already running keeps serving the view it read at startup.
+ */
+views = []) {
     const lines = [
         ...[...manuals].sort(),
-        '\u0001', // separates the two lists, so a line can never migrate between them
+        '\u0001', // separates the lists, so a line can never migrate between them
         ...skills.map(skillFingerprint).sort(),
+        '\u0001',
+        ...views.map((v) => `${v.uri}\u0000${createHash('sha256').update(v.text).digest('hex')}`).sort(),
     ];
     return createHash('sha256').update(lines.join('\n')).digest('hex').slice(0, 32);
 }
@@ -78,8 +86,11 @@ export function createCatalogRevisionRoutes(deps) {
             const [manuals, skills] = email
                 ? await Promise.all([deps.toolManuals.catalogFingerprints(email), deps.skills.listSkills(email)])
                 : [[], []];
+            // A manifest that cannot be read counts as no views, which is also what
+            // the MCP endpoint serves in that state.
+            const views = deps.mcpApps ? ((await deps.mcpApps.manifest().catch(() => null))?.resources ?? []) : [];
             res.json({
-                revision: catalogRevision(manuals, skills),
+                revision: catalogRevision(manuals, skills, views),
                 tools: manuals.length,
                 skills: skills.length,
             });

package/dist/core/catalog-revision.js.map

@@ -1 +1 @@
-{"version":3,"file":"catalog-revision.js","sourceRoot":"","sources":["../../src/core/catalog-revision.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AACzC,OAAO,OAA8C,MAAM,SAAS,CAAC;AACrE,OAAO,EAAE,MAAM,EAAE,MAAM,sBAAsB,CAAC;AAG9C,OAAO,8CAA8C,CAAC,CAAC,8CAA8C;AAErG,MAAM,GAAG,GAAG,MAAM,CAAC,kBAAkB,CAAC,CAAC;AAEvC;;;;;;;;;;;;;;;;;;;GAmBG;AAEH;;;;;GAKG;AACH,SAAS,gBAAgB,CAAC,CAAe;IACvC,OAAO,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;AACzE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,eAAe,CAC7B,OAA0B,EAC1B,MAA+B;IAE/B,MAAM,KAAK,GAAG;QACZ,GAAG,CAAC,GAAG,OAAO,CAAC,CAAC,IAAI,EAAE;QACtB,QAAQ,EAAE,oEAAoE;QAC9E,GAAG,MAAM,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,EAAE;KACvC,CAAC;IACF,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClF,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,2BAA2B,CAAC,IAM3C;IACC,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAEhC,MAAM,CAAC,GAAG,CAAC,yBAAyB,EAAE,IAAI,CAAC,UAAU,EAAE,KAAK,EAAE,GAAY,EAAE,GAAG,EAAE,EAAE;QACjF,IAAI,CAAC;YACH,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC;YACpC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,CAAC,MAAM,IAAI,CAAC,gBAAgB,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;YAC9F,wEAAwE;YACxE,qEAAqE;YACrE,mDAAmD;YACnD,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,GAAG,KAAK;gBAC7B,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,mBAAmB,CAAC,KAAK,CAAC,EAAE,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,KAAK,CAAC,CAAC,CAAC;gBACjG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;YACb,GAAG,CAAC,IAAI,CAAC;gBACP,QAAQ,EAAE,eAAe,CAAC,OAAO,EAAE,MAAM,CAAC;gBAC1C,KAAK,EAAE,OAAO,CAAC,MAAM;gBACrB,MAAM,EAAE,MAAM,CAAC,MAAM;aACtB,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,GAAG,CAAC,KAAK,CAAC,0BAA0B,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;YAC/C,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,4BAA4B,EAAE,CAAC,CAAC;QAChE,CAAC;IACH,CAAC,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"catalog-revision.js","sourceRoot":"","sources":["../../src/core/catalog-revision.ts"],"names":[],"mappings":"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"}

package/dist/core/core-ports.d.ts

@@ -6,6 +6,7 @@ import type { IErasureParticipant } from '../modules/auth/account-erasure.servic
 import type { IAccountAdmission } from '../modules/auth/account-admission.js';
 import type { IWriteAccess } from '../modules/write-access/write-access.js';
 import type { OnServerStart } from '../modules/workspace/startup/on-server-start.js';
+import type { AgentGuideHook } from '../modules/agent-guide/agent-guide.js';
 /**
  * Every seam the enterprise overlay can fill in the CORE composition
  * (`createCoreServices`). All fields are optional; each has a safe core-only
@@ -96,6 +97,16 @@ export interface CorePorts {
      * contract each step signs up to). Core default: `[]`.
      */
     kbStartupSteps?: readonly OnServerStart[];
+    /**
+     * THIS distribution's say over the agent guide — the text `get_agent_guide`
+     * and a `read_file` of the guide's name serve. Called with core's sections
+     * and the layout in effect on every composition; returns the sections the
+     * guide is made of, so a distribution appends its own, replaces one of
+     * core's by id, or drops one, and every change core makes to the rest still
+     * reaches it. Core default: core's sections as they are. See
+     * `modules/agent-guide`.
+     */
+    agentGuide?: AgentGuideHook;
     /**
      * Mirror this composition's branch model and knowledge-base layout onto the
      * shared package's PROCESS-WIDE live bindings (`DEFAULT_BRANCH`,

package/dist/core/core-ports.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core-ports.d.ts","sourceRoot":"","sources":["../../src/core/core-ports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,+CAA+C,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iDAAiD,CAAC;AAErF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACrC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC5C;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAI/B,CAAC"}
+{"version":3,"file":"core-ports.d.ts","sourceRoot":"","sources":["../../src/core/core-ports.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sCAAsC,CAAC;AACzE,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACpB,MAAM,+CAA+C,CAAC;AACvD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,yCAAyC,CAAC;AAC9E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,gCAAgC,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,4CAA4C,CAAC;AACtF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iDAAiD,CAAC;AACrF,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uCAAuC,CAAC;AAE5E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,MAAM,WAAW,SAAS;IACxB;;;;OAIG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;IAC3B;;;;;OAKG;IACH,aAAa,CAAC,EAAE,mBAAmB,CAAC;IACpC;;;;OAIG;IACH,YAAY,CAAC,EAAE,iBAAiB,CAAC;IACjC;;;;OAIG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;OAIG;IACH,aAAa,CAAC,EAAE,kBAAkB,EAAE,CAAC;IACrC;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,EAAE,CAAC;IAC5C;;;;;;;;;;;;;OAaG;IACH,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC;;;;OAIG;IACH,cAAc,CAAC,EAAE,SAAS,aAAa,EAAE,CAAC;IAC1C;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,cAAc,CAAC;IAC5B;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;;;;OAOG;IACH,gBAAgB,CAAC,EAAE,iBAAiB,CAAC;IACrC;;;;;;;OAOG;IACH,WAAW,CAAC,EAAE,YAAY,CAAC;CAC5B;AAED;;;;;GAKG;AACH,eAAO,MAAM,iBAAiB,EAAE,mBAI/B,CAAC"}

package/dist/core/core-ports.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-ports.js","sourceRoot":"","sources":["../../src/core/core-ports.ts"],"names":[],"mappings":"AAmIA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAwB;IACpD,KAAK,CAAC,GAAG;QACP,yCAAyC;IAC3C,CAAC;CACF,CAAC"}
+{"version":3,"file":"core-ports.js","sourceRoot":"","sources":["../../src/core/core-ports.ts"],"names":[],"mappings":"AA8IA;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAwB;IACpD,KAAK,CAAC,GAAG;QACP,yCAAyC;IAC3C,CAAC;CACF,CAAC"}

package/dist/core/create-core-server.d.ts

@@ -7,6 +7,11 @@ type ExpressApp = ReturnType<typeof express>;
  * The context handed to {@link ServerExtensions.tools}: everything an overlay
  * needs to register its own tool defs + endpoint routes on the unified tool
  * surface, exactly like the core modules do.
+ *
+ * A tool that works on a branch declares it on its `toolDef` (`branch:
+ * 'required'` or, read-only tools only, `'defaults-to-default-branch'`), and
+ * `toolHandler` resolves the branch before the tool runs — see "The branch"
+ * in `modules/tool-helpers/index.ts`.
  */
 export interface ToolSurfaceCtx {
     registry: CoreServices['toolRegistry'];

package/dist/core/create-core-server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"create-core-server.d.ts","sourceRoot":"","sources":["../../src/core/create-core-server.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAG9B,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAwCtD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAkCvG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAG9D,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,YAAY,CAAC,oBAAoB,CAAC,CAAC;IAChD,kEAAkE;IAClE,eAAe,EAAE,eAAe,CAAC;IACjC,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;OAYG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClD,mFAAmF;IACnF,OAAO,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACpD;;;;OAIG;IACH,KAAK,CAAC,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACtD,2EAA2E;IAC3E,MAAM,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;CACpD;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,YAAY,EAClB,GAAG,GAAE,gBAAqB,EAC1B,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,CAAC;CACX,GACL,OAAO,CAAC,UAAU,CAAC,CAgrBrB"}
+{"version":3,"file":"create-core-server.d.ts","sourceRoot":"","sources":["../../src/core/create-core-server.ts"],"names":[],"mappings":"AAAA,OAAO,OAAO,MAAM,SAAS,CAAC;AAG9B,OAAO,KAAK,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AA4CtD,OAAO,EAAwB,KAAK,eAAe,EAAE,MAAM,2CAA2C,CAAC;AAmCvG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAO9D,KAAK,UAAU,GAAG,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC;AAE7C;;;;;;;;;GASG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC;IACvC,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,cAAc,CAAC;IACzB,WAAW,EAAE,YAAY,CAAC,oBAAoB,CAAC,CAAC;IAChD,kEAAkE;IAClE,eAAe,EAAE,eAAe,CAAC;IACjC,IAAI,EAAE,YAAY,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC/B;;;;;;;;;;;;OAYG;IACH,qBAAqB,CAAC,EAAE,MAAM,EAAE,CAAC;IACjC;;;;OAIG;IACH,MAAM,CAAC,CAAC,IAAI,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAClD,mFAAmF;IACnF,OAAO,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACpD;;;;OAIG;IACH,KAAK,CAAC,CAAC,GAAG,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC;;;;OAIG;IACH,SAAS,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACtD,2EAA2E;IAC3E,MAAM,CAAC,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;CACpD;AAED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,YAAY,EAClB,GAAG,GAAE,gBAAqB,EAC1B,IAAI,GAAE;IACJ,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iFAAiF;IACjF,IAAI,CAAC,EAAE,OAAO,CAAC;CACX,GACL,OAAO,CAAC,UAAU,CAAC,CA6uBrB"}