@bevel-software/platform-core-backend 0.34.0 → 0.35.0

package/agent-guide/skills.md

@@ -1,55 +1,80 @@
 ## Skills (`{{skillsDir}}/<scope>/…/<skill>/SKILL.md`, or `{{pluginsDir}}/<Plugin>/skills/<skill>/SKILL.md`)
 
 A skill is a folder holding a `SKILL.md` and whatever files it needs. Shared
-skills live under `{{skillsDir}}/`, organised by ownership; a skill that belongs to
-exactly one plugin may live inside that plugin's `skills/` folder instead.
-Skill names are unique across the whole catalog, whichever home they have.
-The frontmatter names it, declares which tools it may use, and may carry a
-version:
+skills live under `{{skillsDir}}/`, organised by ownership; a skill that
+belongs to one plugin alone may live in that plugin's `skills/` folder. Skill
+names are unique across the catalog. The frontmatter names the skill, says
+when to use it, and may list tools and a version:
 
 ```yaml
 ---
 name: weekly-newsletter
-description: Drafts the Friday newsletter for review.
+description: "Use when someone asks for the Friday newsletter: drafts it for review."
 allowed-tools: [slack_post_message]
 metadata:
   version: "1.4.0"
 ---
 ```
 
-The body is the instructions, in plain markdown. `allowed-tools` entries are
-tool names from the `.tool` manuals and MCP servers of the plugins that hold
-the skill, and the agent client's own tools beside them (`Bash`, `Read`,
-`Bash(git:*)` and the like, which the platform leaves to the client).
-`metadata.version` is semver; `list_skills` reports it, and
-`get_skill` with a `version` loads the skill as it was when it last declared
-that version (omit `version` for the latest). Any other `metadata` keys are
-the author's own notes — the catalog carries the file as it is and acts on
-none of them.
-
-Before offering to change a skill, read its `canWrite`: `list_skills` judges
-the `SKILL.md`; `get_skill` judges every file of the skill unless `file` is
-passed, in which case it judges only that file — a bundled file's `true` is
-not the skill's; both by the default branch's rules whichever branch you
-read. `canWrite: false` means use a branch and a change request; do not
-offer a direct write (see *Direct writes vs change requests* under **Access
-control**).
-
-A `SKILL.md` committed on the default branch is listed and loadable from the
-very next `list_skills` or `get_skill`, on the connection you already have:
-the released catalog is cached briefly and dropped the moment the default
-branch changes, so the next request reads the workspace again.
-See *A released tool or skill is live within ten seconds* under **Tool
-Manuals** for the one caveat (an MCP client that caches the prompt list it
-was given at connect time must re-list — the prompt-list-changed notification
-that tells it to arrives with the connection's next catalog check, which is
-within ten seconds on a connection in use and at its next use on an idle
-one).
-
-**How skills reach agents.** Through the MCP server (`list_skills`,
-`get_skill`), or as native plugins: every user can clone a git remote from
-the app's external-agent page that holds a plugin marketplace compiled from
-exactly the skills they may read — one plugin per plugin here, a
-`skills-and-knowledge` plugin for the rest plus this knowledge base's MCP
-server, and `hexis-all`, one plugin holding every skill they may read and
-the MCP server, for a single install.
+- **The frontmatter is YAML.** Quote a value that contains `: ` or starts
+  with a special character, as above, or the description comes out empty and
+  nobody finds the skill. Read it back with `get_skill` after writing.
+- **`description` is how the skill is found**: agents load a skill when its
+  description fits the task. Say when to use it, in the words people use.
+- **`allowed-tools`** names the tools the skill uses: any of the platform's
+  tools, a plugin's (as `<server>_<tool>`), and the client's own (`Bash`,
+  `Read`, `Bash(git:*)`). The platform warns about a name it does not know,
+  and enforces nothing.
+- **`metadata.version`** (or a top-level `version`) is reported by
+  `list_skills`; `get_skill` with `version` loads the skill as it was when it
+  last declared that version. Other `metadata` keys are the author's notes.
+
+The body is the instructions, in plain markdown.
+
+**A skill on a draft is not live.** The app's skills page, the prompts and
+`list_skills` without `branch` show only the released catalog, read from
+`{{defaultBranch}}`, so a skill on a draft "doesn't exist" there until it is
+merged. To try it, pass the draft: `list_skills({ body: { branch: "<draft>" } })`,
+then `get_skill({ body: { name: "weekly-newsletter", branch: "<draft>" } })`.
+A skill that differs from the released one comes back with `unmerged: true`,
+and its body opens with a line saying it is not approved. Once merged, it is
+in the next `list_skills` or `get_skill`; a client that cached the prompt list
+when it connected must reconnect to show it as a prompt.
+
+Before offering to change a skill, check its `canWrite` (see `access-control`).
+
+**How skills reach agents.** Through this server (prompts, `list_skills`,
+`get_skill`), or as native plugins: each person can install a plugin
+marketplace from the app's external agent page, compiled from exactly the
+skills they may read.
+
+### A skill that needs tools checks them first
+
+A skill that calls another service fails for anyone who has not signed in, or
+before the tool is merged. Make its first step a check, and stop with a plain
+instruction rather than a failed call:
+
+```markdown
+## Before you start
+Call `list_tool_setup`. Find the Jira tool. If a variable with `scope: user`
+shows `userConfigured: false` (or `authorized: false` for a sign-in), stop and
+say: "Open the Connect page in <app> and sign in to Jira, then ask me again."
+If the tool is missing altogether, say it is not available to them yet and who
+to ask.
+```
+
+### A guided skill for people who are not technical
+
+When a skill is for someone who is not an engineer, such as turning an idea
+into a ticket, write it to lead them:
+
+- **One question per message**, the most important first. Never a list of
+  five.
+- **Propose, then ask them to confirm.** "I would call it 'Search: filter by
+  date'. Is that right?" is easier to answer than "What is the title?".
+- **A checklist for "specified enough"** in the skill (who it is for, what
+  should happen, how we know it works), and stop asking once it is met.
+- **Plain words.** No platform terms (branch, change request, frontmatter,
+  tool names); show the result in their language before you create anything.
+- **Check its tools first** (above), so the conversation does not end in an
+  error after ten questions.

package/agent-guide/start-here.md

@@ -0,0 +1,65 @@
+## Start here
+
+You are connected to this organisation's knowledge base: its documents, and
+the skills and tools its teams have approved, with access set per folder. To
+the people you work with it is not a Git repository: say "knowledge base",
+"draft" and "change request", and do not explain it as "a Git repo". If they
+ask how it compares, see `for-git-users`.
+
+**Read this once per conversation.** Then fetch only the section a task needs,
+`get_agent_guide({ body: { section: "<id>" } })`, and do not reload the whole
+guide. When you start a sub-agent, pass it the rules below and the one section
+its task needs.
+
+### Before your first call
+
+- **Every file tool takes `branch`.** `{{defaultBranch}}` is the default
+  branch: what is live for everyone. Work in progress lives on a draft branch.
+  For example:
+  `read_file({ body: { branch: "{{defaultBranch}}", path: "{{kbDirName}}/{{knowledgeBaseDir}}/Overview.md" } })`.
+- **Copy each tool's `Call:` line.** It is generated from the tool's own
+  schema and shows the shape that tool takes, with every required argument;
+  optional ones are in the schema. A call with a missing or unknown argument
+  is refused, and the refusal shows the tool's interface.
+- **Pass `sessionId` only where a tool lists it.** Over MCP, call
+  `start_session` once and pass its id to the tools whose arguments include
+  `sessionId`. Other tools refuse it.
+- **`grep` takes RE2-style regular expressions** (ripgrep): no look-around
+  and no backreferences.
+- **Paths sit under `{{kbDirName}}/`**, as in
+  `{{kbDirName}}/{{knowledgeBaseDir}}/Overview.md`. A path without that prefix
+  is placed under it.
+
+### What is live, and what is only on a draft
+
+Work on a draft is visible to you, and to anyone who opens that draft in the
+app: its change request, once you open one, shows every changed file.
+**Skills and tools go live only once they are on `{{defaultBranch}}`**,
+merged through a change request or written there directly by someone allowed
+to. Until then the app's skills page, `list_skills` without `branch` and the
+tool list do not show them, and "doesn't exist" means "not merged yet". To see
+a skill on a draft, pass the draft as `branch` to `list_skills` or
+`get_skill`.
+
+### Which section answers what
+
+| Question | Section |
+|---|---|
+| What does my agent see when it connects, and how does it find the rest? | `how-agents-find-things` |
+| How is this like Git, and how is it not? Why can't I delete this? | `for-git-users` |
+| What is a plugin, a skill, a tool, a secret, a role, a group? | `glossary` |
+| What do the platform's folders hold? | `directory-structure` |
+| Where does a new file go? How do I lay out a team's first project? | `where-a-new-file-goes` |
+| What may the file tools do: content kinds, write modes, moves, deletes? | `working-with-files` |
+| Who may read or change what: roles, groups, `access.md`? | `access-control` |
+| How do I propose, sync or delete a draft, or settle a conflict? | `drafts-and-change-requests` |
+| How do I write a skill, or one for people who are not technical? | `skills` |
+| When can I use a tool, and what does it need set up? | `tools` |
+| How do I add a tool: `.tool` files, `mcp.json`, sign-ins? | `tool-manuals` |
+| How do I build an interactive HTML page? | `html-views` |
+| How are pages named, linked and sourced? | `conventions` |
+| The knowledge base is empty: what now? | `new-knowledge-base` |
+
+A deployment may add sections of its own: `sections` in this answer lists
+every one. `get_agent_guide({ body: { section: "all" } })` returns the whole
+guide.

package/agent-guide/tool-manuals.md

@@ -1,114 +1,95 @@
 ## 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):
+A `.tool` file is a **tool manual**: it lets agents call a service's HTTP API.
+It lives in a plugin's `software.bevel.hexis/tools/` folder, beside the skills
+that use it. `.tool` files are for `http` and `inline` manuals only: an MCP
+server belongs in the plugin's `mcp.json` (see `directory-structure`). Who may
+use and who manages a tool is in `tools`.
+
+**The tool is the frontmatter.** A `.tool` is one `---` YAML block holding
+everything: its `id`, its access verbs (`read`/`write`/`owner`/`download`,
+which override the folder's `access.md` for this file) and its config
+(`type`, `url`, `variables`, …). Anything after the closing `---` is notes the
+parser ignores. A file without the fence is the older form: the whole file is
+the object, so a bare JSON `.tool` still works.
 
 ```yaml
 ---
 id: my_tool
 write:
   - group/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.)
+`type` decides how the tools are found: **`inline`** embeds them in the file,
+**`http`** points `url` at an endpoint that returns a UTCP manual.
+(`type: mcp` is an older way to declare an MCP server; startup moves such files
+into `mcp.json` where it can. Do not write new ones.)
 
-**`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`).
+**`id` is the manual's identity**: the namespace its secrets bind to and its
+address. Use lowercase `snake_case`. Without an `id`, the `name`, then the file
+name, is used. It must be unique among all `.tool` files and `mcp.json` server
+names, and names differing only in `-` and `_` collide: the second is refused
+(an `mcp.json` server wins over a `.tool`), not renamed, and `list_tool_setup`
+names it under `invalid`. The same service in two plugins needs two ids
+(`serper_everyone`, `serper_finance`), each with its own secrets and access.
 
-**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.
+### Secrets: `${VAR}` and `variables`
 
-**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.)
+Wherever a manual needs a credential, write a placeholder such as
+`${API_KEY}`. At call time it is filled from the platform's Secrets Vault,
+under a key made from the manual's id and the variable's name, so a secret
+belongs to one manual. The app's Secrets page shows the exact key; do not spell
+it by hand.
 
-To actually USE those tools, run the workspace as a local MCP server:
+Declare who provides each variable in an optional `variables` list of
+`{ name, scope, label? }`:
 
-```
-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.
+- **`scope: admin`** (the default): set once by a writer of the file and shared
+  by everyone who uses the tool. Prefer it.
+- **`scope: user`**: each person sets their own.
 
-Declare who provisions each variable with an optional top-level `variables` array. Each entry is `{ name, scope, label? }`:
+`name` matches `[A-Za-z0-9_]+`. A `${VAR}` you do not declare is `admin` and
+still shows in the app, so the list is needed only for `user` scope, a label,
+or a sign-in. Values are entered in the app, never in the file. A malformed
+entry makes the whole file fail to load (it then shows under `invalid`).
 
-- **`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).
+### Sign-ins: the `oauth` block
 
-`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:
+A `user` variable can be filled by signing in instead of typing a value: add
+an `oauth` block, and the token rides in whatever header uses `${VAR}`. The
+block carries public settings 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:
+| `clientId` | required | the OAuth app's client id; its owner registers the app with the redirect URI `<backend>/api/secrets/oauth/callback` |
+| `authorizationUrl`, `tokenUrl` | required in a `.tool`; optional on an `mcp.json` server | an MCP server's are discovered from its own OAuth metadata, so give them only when that discovery fails. Both or neither |
+| `scopes` | optional | `string[]`, requested at sign-in |
+| `pkce` | optional, default on | only `false` means anything |
+| `resource` | optional | the RFC 8707 resource indicator; discovered on an `mcp.json` server |
+| `authParams` | optional | extra fixed parameters, such as Google's `access_type: offline` |
+
+**Never** a `clientSecret`: a `.tool` with one fails to load, and an `mcp.json`
+server whose entry has one is dropped. The secret is pasted once on the tool's
+page. For an `mcp.json` server, the declaration goes in `plugin.json`, beside
+the 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>" } }
-          ]
-        }
-      }
-    }
-  }
-}
+{ "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`
+### Google APIs as a 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>`:
+Some Google APIs (Ads, Tag Manager, BigQuery, Sheets) are called as one shared
+service account, with a short-lived token minted from its key. Name the key in
+an `auth` block on an inline tool's `tool_call_template` (with
+`call_template_type: http`), and the platform mints, caches and sends the token:
 
 ```yaml
 ---
@@ -134,94 +115,91 @@ tools:
 ---
 ```
 
-| 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}`.
+`credentials` is always a `${VAR}` holding the key JSON (whole, or base64);
+`scopes` is required; `subject` (optional) is a user to act as, for a service
+account with domain-wide delegation. The block anywhere else is refused and
+named under `invalid`. Give the service account access in the Google product
+itself. To have each person call Google as themselves, use a sign-in
+(`oauth`) instead.
 
 ### Examples
 
-An `http` manual that authenticates with a shared org key and a per-user key:
+An `http` manual with a shared and a personal key:
 
 ```yaml
-name: weather
+---
+id: 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" }
+  - { name: ORG_KEY,  scope: admin, label: "Org-wide weather key" }
+  - { name: USER_KEY, scope: user,  label: "Your personal weather 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}" }
-      }
-    }
-  ]
-}
+```yaml
+---
+id: 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.
+When asked to add a product as a tool ("add Notion", "wire up Linear"), never
+invent an endpoint or write a placeholder URL:
+
+1. **Find the real endpoint in the vendor's own docs**, preferring their
+   official remote MCP server, else their REST API. Confirm the URL, transport
+   and auth with a web search, not from memory; without web access, ask the
+   person.
+2. **Pick the home.** An MCP server is an entry in the plugin's `mcp.json`
+   (`type: "streamable-http"` and the `https://` URL, never `ws://`). A REST
+   API is a `.tool` with `type: http`, or `type: inline` when you write each
+   call by hand.
+3. **An OAuth-protected MCP server usually needs only its `mcp.json` entry.**
+   The app probes it, registers itself and offers a sign-in on the Connect page
+   (`oauth-auto`). An `Authorization` header or an `oauth` variable turns that
+   discovery off, so add neither. Some providers do not support it
+   (`oauth-manual`, such as HubSpot or Google): write the entry; once it is
+   live, `list_tool_setup` answers `setup.kind` and `setup.reason` for it.
+4. **For a key, use `variables`**, never a key in the file:
+   `Authorization: Bearer ${NOTION_TOKEN}` and a `variables` entry with its
+   scope.
+5. **Mark tools that only work on the person's machine**: `local: true` on an
+   MCP server's `plugin.json` entry, `remote: false` on a `.tool`.
+
+All of it lands on a draft first, and goes live once merged (see `tools`).
+
+**Walking an admin through `oauth-manual`:**
+
+1. Register an OAuth app with the provider, with the redirect URI that
+   `setup.reason` gives.
+2. Ask for the app's **client id** (public, fine in the chat) and write the
+   declaration: for an `mcp.json` server, the `variables` entry with
+   `oauth: { clientId }` and the `Authorization: Bearer ${VAR}` header in its
+   `plugin.json` entry; for a `.tool`, the same with `authorizationUrl` and
+   `tokenUrl`. A person can do the same under "Edit server" on the tool's page.
+3. Once the declaration is on `{{defaultBranch}}` (a draft's entry shows in
+   `onBranchOnly` with no `setup`), run `list_tool_setup`: `setup.reason` must
+   be gone. If the endpoints could not be discovered, add `authorizationUrl`
+   and `tokenUrl` from the provider's docs.
+4. The admin pastes the **client secret** into the tool's page, never into
+   the file or the chat. Then everyone signs in on the Connect page.