@bevel-software/platform-core-backend 0.15.1 → 0.20.0

package/dist/shared/ssrf.js

@@ -16,31 +16,62 @@ export function isBlockedHost(hostname) {
     // IPv6 literals only: they contain a colon, whereas a plain hostname never does
     // — so domains like `fc.example.org` / `fd.example.com` are not matched.
     if (host.includes(':')) {
-        // IPv4-mapped IPv6 connects to the embedded v4 — validate it. The textual
-        // form may be dotted (`::ffff:169.254.169.254`) OR two hex hextets
-        // (`::ffff:a9fe:a9fe`) — WHATWG `new URL` canonicalizes the mapped address
-        // to the HEX form, so the dotted regex alone would miss a normalized
-        // hostname. Handle both.
-        const mappedDotted = /:(\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3})$/.exec(host);
-        if (mappedDotted && isBlockedV4(mappedDotted[1]))
+        const hextets = parseIPv6(host);
+        // Not an address `new URL` would accept either — nothing to connect to.
+        if (!hextets)
             return true;
-        const mappedHex = /:ffff:([0-9a-f]{1,4}):([0-9a-f]{1,4})$/.exec(host);
-        if (mappedHex) {
-            const hi = parseInt(mappedHex[1], 16);
-            const lo = parseInt(mappedHex[2], 16);
-            const v4 = `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
-            if (isBlockedV4(v4))
-                return true;
+        // IPv4-mapped (::ffff:0:0/96) connects to the embedded v4 — judge that.
+        // Decoded from the hextets, so every spelling lands here: dotted
+        // (`::ffff:169.254.169.254`), the hex form WHATWG `new URL` canonicalizes
+        // to (`::ffff:a9fe:a9fe`) and the fully expanded `0:0:0:0:0:ffff:…`.
+        if (hextets.slice(0, 5).every((h) => h === 0) && hextets[5] === 0xffff) {
+            const [hi, lo] = [hextets[6], hextets[7]];
+            return isBlockedV4(`${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`);
         }
-        if (host === '::1' || host === '::')
-            return true; // loopback / unspecified
-        // link-local fe80::/10 (fe80–febf) and unique-local fc00::/7 (fc/fd).
-        if (/^fe[89ab]/.test(host) || host.startsWith('fc') || host.startsWith('fd'))
+        // Everything else must be global unicast (2000::/3). That excludes loopback
+        // and unspecified (`::1`, `::`, `::2`…), link-local fe80::/10, unique-local
+        // fc00::/7 and multicast ff00::/8.
+        if (hextets[0] < 0x2000 || hextets[0] > 0x3fff)
+            return true;
+        // Inside global unicast, the special-purpose blocks: 2001::/23 (Teredo,
+        // ORCHID, the benchmarking range 2001:2::/48, …), documentation
+        // 2001:db8::/32, and the newer documentation block 3fff::/20. None is a
+        // real host to fetch from.
+        if (hextets[0] === 0x2001 && (hextets[1] < 0x0200 || hextets[1] === 0x0db8))
+            return true;
+        if (hextets[0] === 0x3fff && hextets[1] < 0x1000)
             return true;
         return false;
     }
     return isBlockedV4(host);
 }
+/**
+ * The eight hextets of an IPv6 literal (`::` expanded, a dotted IPv4 tail
+ * decoded), or null when it is not one. A zone id (`%eth0`) is ignored.
+ */
+function parseIPv6(literal) {
+    let text = literal.replace(/%.*$/, '');
+    const dotted = /^(.*:)(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(text);
+    if (dotted) {
+        const octets = dotted.slice(2).map(Number);
+        if (octets.some((o) => o > 255))
+            return null;
+        text = `${dotted[1]}${((octets[0] << 8) | octets[1]).toString(16)}:${((octets[2] << 8) | octets[3]).toString(16)}`;
+    }
+    const halves = text.split('::');
+    if (halves.length > 2)
+        return null;
+    const part = (half) => (half === '' ? [] : half.split(':'));
+    const head = part(halves[0]);
+    const tail = halves.length === 2 ? part(halves[1]) : [];
+    const missing = 8 - head.length - tail.length;
+    if (halves.length === 2 ? missing < 1 : missing !== 0)
+        return null;
+    const groups = [...head, ...Array(halves.length === 2 ? missing : 0).fill('0'), ...tail];
+    if (!groups.every((g) => /^[0-9a-f]{1,4}$/.test(g)))
+        return null;
+    return groups.map((g) => parseInt(g, 16));
+}
 /** True for an IPv4 literal in a private / loopback / link-local (incl. cloud IMDS) range. */
 function isBlockedV4(host) {
     const m = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(host);

package/dist/shared/ssrf.js.map

@@ -1 +1 @@
-{"version":3,"file":"ssrf.js","sourceRoot":"","sources":["../../src/shared/ssrf.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ssrf.js","sourceRoot":"","sources":["../../src/shared/ssrf.ts"],"names":[],"mappings":"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"}

package/dist/version.d.ts

@@ -4,12 +4,16 @@
  * rollout by sha *before* smoke-testing it.
  *
  * Sources, in priority order:
- *  - `GIT_SHA` — baked at image build time via the Dockerfile `ARG`/`ENV`
- *    (set from `git rev-parse HEAD` by CI or `docker compose build`).
- *  - `SOURCE_COMMIT` — Coolify injects this for git-based deploys, so the
- *    sha is correct on hosted deploys even when no explicit build arg was
- *    passed. `.git` is in `.dockerignore`, so the sha can't be derived
- *    inside the build — it has to be passed in.
+ *  - `GIT_SHA` — baked into the image by the Dockerfile from its ONE build
+ *    arg, `SOURCE_COMMIT` (CI, Coolify and a manual build all pass that
+ *    name). Baked under a different name deliberately: a runtime variable
+ *    overrides an image ENV of the same name, and `SOURCE_COMMIT` is what
+ *    a hosted deployment UI writes at runtime — once as an empty literal
+ *    that blanked the real value. Nothing at runtime sets `GIT_SHA`.
+ *  - `SOURCE_COMMIT` — the runtime value Coolify injects for git-based
+ *    deploys, so a build that was not given the arg still reports a sha.
+ *    `.git` is in `.dockerignore`, so the sha can't be derived inside the
+ *    build — it has to be passed in.
  *  - `'unknown'` — local `tsx` runs and any build that wired neither.
  */
 export declare function resolveGitSha(env?: NodeJS.ProcessEnv): string;

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE1E;AAED,eAAO,MAAM,OAAO,QAAkB,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAEA;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAAC,GAAG,GAAE,MAAM,CAAC,UAAwB,GAAG,MAAM,CAE1E;AAED,eAAO,MAAM,OAAO,QAAkB,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAW1C"}

package/dist/version.js

@@ -5,12 +5,16 @@ import { readFileSync } from 'node:fs';
  * rollout by sha *before* smoke-testing it.
  *
  * Sources, in priority order:
- *  - `GIT_SHA` — baked at image build time via the Dockerfile `ARG`/`ENV`
- *    (set from `git rev-parse HEAD` by CI or `docker compose build`).
- *  - `SOURCE_COMMIT` — Coolify injects this for git-based deploys, so the
- *    sha is correct on hosted deploys even when no explicit build arg was
- *    passed. `.git` is in `.dockerignore`, so the sha can't be derived
- *    inside the build — it has to be passed in.
+ *  - `GIT_SHA` — baked into the image by the Dockerfile from its ONE build
+ *    arg, `SOURCE_COMMIT` (CI, Coolify and a manual build all pass that
+ *    name). Baked under a different name deliberately: a runtime variable
+ *    overrides an image ENV of the same name, and `SOURCE_COMMIT` is what
+ *    a hosted deployment UI writes at runtime — once as an empty literal
+ *    that blanked the real value. Nothing at runtime sets `GIT_SHA`.
+ *  - `SOURCE_COMMIT` — the runtime value Coolify injects for git-based
+ *    deploys, so a build that was not given the arg still reports a sha.
+ *    `.git` is in `.dockerignore`, so the sha can't be derived inside the
+ *    build — it has to be passed in.
  *  - `'unknown'` — local `tsx` runs and any build that wired neither.
  */
 export function resolveGitSha(env = process.env) {

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CACzC,CAAC;QAC3B,OAAO,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,IAAI,QAAQ,CAAC,OAAO;YAC7D,CAAC,CAAC,QAAQ,CAAC,OAAO;YAClB,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEvC;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,UAAU,aAAa,CAAC,MAAyB,OAAO,CAAC,GAAG;IAChE,OAAO,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,aAAa,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,IAAI,SAAS,CAAC;AACtE,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAG,aAAa,EAAE,CAAC;AAEvC;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,iBAAiB;IAC/B,IAAI,CAAC;QACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CACzB,YAAY,CAAC,IAAI,GAAG,CAAC,iBAAiB,EAAE,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,CACzC,CAAC;QAC3B,OAAO,OAAO,QAAQ,CAAC,OAAO,KAAK,QAAQ,IAAI,QAAQ,CAAC,OAAO;YAC7D,CAAC,CAAC,QAAQ,CAAC,OAAO;YAClB,CAAC,CAAC,SAAS,CAAC;IAChB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAC;IACnB,CAAC;AACH,CAAC"}

package/kb-template/.bevelignore

@@ -11,7 +11,10 @@
 # Repo hygiene files that clutter the tree without being node content.
 .gitignore
 .gitattributes
-AGENTS.md
+# The platform's agent guide.
+{{agentsFile}}
+# The deployment preamble is edited from External agent access, not as a KB page.
+/mcp-description.md
 # The pre-rename name. Listed so a knowledge base carrying both files hides
 # both — top-up adds AGENTS.md but never deletes the CLAUDE.md beside it.
 CLAUDE.md
@@ -21,5 +24,3 @@ CLAUDE.md
 
 **/access.md
 roles.yaml
-
-{{pluginsDir}}/

package/kb-template/AGENTS.md

@@ -1,13 +1,27 @@
+---
+# This file's own access rule: readable by every signed-in person and their
+# agents, whatever the root access.md says. Agents are told to read this file
+# before their first action, and the root rules grant read to nobody by
+# default — without this line a non-admin's agent would fail on step one.
+read:
+  - everyone
+---
 # Knowledge base
 
 This is a git-backed knowledge base. You are the primary agent responsible for
 maintaining it.
 
-> **This file is managed by the platform.** Every server restart replaces it
-> with the current template, so edits made here are overwritten. Deployment- or
-> team-specific conventions belong in files of your own — anywhere under
+> **This file is managed by the platform.** It lives at the repository root as
+> `{{agentsFile}}`, and every server restart replaces it with the current
+> template, so edits made here are overwritten. Deployment- or team-specific
+> conventions belong in files of your own — anywhere under
 > `{{knowledgeBaseDir}}/`, linked from wherever they are needed.
 
+**Read `mcp-description.md` at the repository root first.** It says what this
+knowledge base contains and when to consult it. Agents connected over MCP
+receive the default branch's copy inline at the start of every session; a
+clone like this one reads the copy on its own branch.
+
 **There is no required format for knowledge.** Write markdown the way the
 subject wants to be written: prose, tables, checklists, diagrams, whatever
 serves the reader. Nothing here parses your files into a schema or rejects a
@@ -33,9 +47,13 @@ effect each time it is written.)
 
 Tool paths are workspace-relative, and the workspace root holds this
 repository as the `knowledge-base/` folder: a file in it is
-`knowledge-base/{{knowledgeBaseDir}}/Foo.md`, never `{{knowledgeBaseDir}}/Foo.md`. A path
-without that prefix is refused, because it would land beside the repository
-where git never sees it.
+`knowledge-base/{{knowledgeBaseDir}}/Foo.md`. Write the prefix where you can —
+it is the path every tool reports back — but a path without it is PLACED under
+`knowledge-base/` rather than refused, so `{{knowledgeBaseDir}}/Foo.md` names that
+same file, and so does the root-anchored `/knowledge-base/{{knowledgeBaseDir}}/Foo.md`
+the app's Copy path gives you. Nothing you send can land beside the repository,
+where git would never see it. `.` or `..` segments, backslashes and every other
+absolute path are refused.
 
 Only those three folders are structural. `{{skillsDir}}/` holds shared skills at any
 depth — the folder that holds a `SKILL.md` is the skill, and everything above
@@ -124,20 +142,27 @@ answer to that — and `mcp.json` carries only where a server is, never a
 under `extensions["software.bevel.hexis"].mcpServers[<name>]`, which is ours
 to interpret and which other clients ignore by design.
 
-**Plugin folders are made through the app, not by writing files.** A folder
-is a plugin exactly when it carries a `plugin.json` (the platform writes one
-into every legacy plugin folder at startup), and it is LISTED only when it
-also carries an `access.md` — a bare directory under `{{pluginsDir}}/` is neither.
-Plugins may sit at any depth under `{{pluginsDir}}/`; a folder that holds plugins
-deeper down is a grouping folder, not a plugin. A new plugin needs an
+**Plugin folders are made through the platform, not by writing files.** A
+folder is a plugin exactly when it carries a `plugin.json` (the platform
+writes one into every legacy plugin folder at startup), and it is LISTED only
+when it also carries an `access.md` — a bare directory under `{{pluginsDir}}/` is
+neither. Plugins may sit at any depth under `{{pluginsDir}}/`; a folder that holds
+plugins deeper down is a grouping folder, not a plugin. A new plugin needs an
 `access.md` naming who runs it, and the write gate refuses a plain write
 into an unused name there — so do not try to create a plugin by writing a
-skill into `{{pluginsDir}}/<new-name>/…`; it will be denied. Send the user to the app's **New plugin** button (or its
-`POST /api/plugins` endpoint), then write into the folder it made. Names
-starting with `personal-` are reserved: one such folder exists per person,
-created automatically with their first personal skill, readable only by its
-owner and never listed as a plugin — a signed-in user's own skills belong
-there, and move into a plugin by moving the skill's folder.
+skill into `{{pluginsDir}}/<new-name>/…`; it will be denied. Use the two tools
+instead:
+
+- `my_plugin` — your user's own private space, created on first use:
+  `{{pluginsDir}}/personal-<id>/`. Readable only by its owner — not even
+  admins — and never listed as a plugin. Their personal skills go under its `skills/`,
+  each in its own folder with a `SKILL.md`; write there with the file tools.
+- `create_plugin` — a shared plugin, named, optionally inside a grouping
+  folder under `{{pluginsDir}}/` (`parent`). The caller runs it; others join
+  through the app or are granted in its `access.md`.
+
+The app's **New plugin** button and `POST /api/plugins` do the same. A skill
+moves from a personal space into a plugin by moving its folder.
 
 Everything under `{{knowledgeBaseDir}}/` is yours to arrange. Subfolders, naming,
 whether a topic is one file or twenty — all of it is a judgement call about
@@ -148,16 +173,51 @@ and `Pipelines/` scaffold an agentic execution layer in some installations.
 They are not part of this template and are not created here; where they exist,
 each carries its own `README.md` describing what belongs in it.
 
+## 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.
+
+- **Any document goes under `{{knowledgeBaseDir}}/`.** Knowledge, notes,
+  reports, tickets, specifications, plans, meeting minutes — anything written
+  to be read by a person. 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 own space (`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.
+- **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.
+
 ## Access control
 
-Write access to any path is governed by `roles.yaml` (who has which role) and
-`access.md` files (which roles/users can write where).
+Access to any path — reading it as much as writing it — is governed by
+`roles.yaml` (who has which role), `groups.yaml` (who is in which group) and
+`access.md` files (who may do what, where).
 
-- **Roles** in `roles.yaml` map a role name to a list of emails. Role names are
+- **Roles** in `roles.yaml` map a role name to a list of members: emails, and
+  `group:<Name>` entries that give the role to a whole group (see *Giving a
+  role to a group* below). Role names are
   case- and whitespace-insensitive (`Admin` = `admin` = `ADMIN`; `Product Team`
   = `product team`). The reserved name `deny` cannot be used, and neither can
   names starting with `role/` or `plugin/` — those spellings are tokens in
-  access entries (below).
+  access entries (below). One exception to the file's authority: the
+  **deployment admin** — the address the server configuration sets as
+  `ADMIN_EMAIL` — is **always an Admin**, whether or not `roles.yaml` lists
+  it, and taking it out of the file does not change that. It is the rescue
+  path for a `roles.yaml` that has lost its last Admin. The App roles page
+  shows that account under Admin as a fixed member that cannot be added or
+  removed there; every other Admin membership is exactly what the file says,
+  and removing one takes effect on that person's next request.
 - **Plugins are grantable principals.** `plugin/<name>/read`,
   `plugin/<name>/write` and `plugin/<name>/owner` in any access file mean
   everyone who currently holds that verb on the plugin whose manifest `name`
@@ -168,16 +228,54 @@ Write access to any path is governed by `roles.yaml` (who has which role) and
   Adding or removing someone on the plugin changes what they can read
   everywhere the token is granted, with no copying.
 - **Access rules** live in `access.md` files, which carry **two blocks with two
-  scopes**: the body declares the rules for the folder the file sits in, and the
-  frontmatter declares who may read and write that `access.md` itself. Each
-  block names verbs (`read`, `write`, `download`, `owner`) whose entries are
-  either grants (bare principal — a role name or `Name <email>`) or denials
-  (the lowercase word `deny`, a space, then the principal). Capitalised forms
-  like `Deny` are *not* triggers; they are treated as part of a name.
+  scopes**: the BODY (below the closing `---`) declares the rules for the
+  folder the file sits in, and the FRONTMATTER declares who may read and
+  write that `access.md` itself. Each block names verbs (`read`, `write`,
+  `download`, `owner`) whose entries are either grants (a bare principal) or
+  denials (the lowercase word `deny`, a space, then the principal).
+  Capitalised forms like `Deny` are *not* triggers; they are treated as part
+  of a name.
+- **Principals** are a role name from `roles.yaml`, a group name from
+  `groups.yaml`, a person as `Name <email>`, a plugin token (above), or
+  **`everyone`** — the built-in org-wide principal: every signed-in person and
+  their agents. `read: everyone` in a folder's BODY opens that folder to the
+  whole organisation; it is how an organisation-wide skill or plugin is
+  shared. The same line in a file's FRONTMATTER only makes that one file
+  visible — a plugin's `access.md` ships with `read: everyone` in its
+  frontmatter so the plugin can be found and joined, and that admits nobody
+  to the plugin itself. A person's own space (`{{pluginsDir}}/personal-<id>/`)
+  denies `everyone` outright, so opening a parent folder never opens it.
+  When a group and a role share a name, the bare name means the GROUP;
+  `role/<Name>` (for example `deny role/Reviewer`) always means the role.
 - **Keep an `access.md` body pure YAML**, with any explanation in `#` comments.
   A body that does not parse as YAML naming at least one verb is read in the
   older format instead, where the FRONTMATTER carried the folder's rules — so a
   stray line of prose silently changes which block governs the folder.
+- **The verbs nest.** `owner` sits over `write` and `download`; `write` and
+  `download` each sit over `read` — anyone who may edit a node, or save a copy
+  of it, may also view it. `write` and `download` say nothing about each other.
+  The nesting is GRANT-ONLY: a grant of a higher verb confers the lower ones,
+  but `deny write` or `deny download` says nothing about `read` and never
+  strips a separate read grant. So `download: Ana <ana@x.io>` alone lets Ana
+  open the node as well as download it, and a `deny download` beside an
+  inherited read leaves her able to open it but not save it.
+- **You can only change what you can read.** Nothing is created, changed,
+  moved into or removed from a place the caller cannot read — on every
+  branch, drafts included, whatever `write:` rules say. A write tool refused
+  for this says so (`write-denied`, naming the unreadable folder), and
+  proposing is not offered either: a proposal into a folder its author cannot
+  see would vanish from them the moment it landed. Two exceptions. A NEW
+  FOLDER directly under `{{knowledgeBaseDir}}/`, `{{skillsDir}}/` or
+  `{{pluginsDir}}/`: anyone may start one, whatever the root's rules grant
+  them, and the new folder's `access.md` is seeded with the creator's own
+  `read:` grant so what they put there is visible to them (a loose FILE
+  directly at a root has no folder to carry that grant and is not excepted).
+  And an Admin — or the deployment owner — may change the files directly in
+  the repository root (`roles.yaml`, `access.md`, `groups.yaml`, `{{agentsFile}}`,
+  …) even when the root grants read to nobody: the same rescue the write
+  floor gives them, so a tree whose root rules lock everyone out stays
+  repairable from inside the app. That rescue stops at the root; a subfolder
+  an admin cannot read is closed to them like to anyone else.
 - **Resolution** walks repo root → file directory, accumulating per-principal
   state. User-level entries trump role-level entries. A role denial removes
   only that role's contribution; it does not undo grants from other roles.
@@ -185,10 +283,122 @@ Write access to any path is governed by `roles.yaml` (who has which role) and
   never overridable by an `access.md`.
 - **`access.md` files are picked up at any depth**, so a folder can tighten or
   widen what it inherited from its parent.
+- **Per-file rules exist for Markdown notes only.** A note (`.md`, lowercase)
+  may name verbs in its own frontmatter, and those rules apply to that one
+  note. (A `.tool` definition keeps the access verbs in its own YAML the same
+  way.) Every other file (a PDF, a presentation, a spreadsheet, an image, any
+  binary, a `.markdown` or `.MD` file, or binary content saved as `.md`)
+  takes its folder's rules: sharing it on its own is refused with
+  `folder-governs-access`, naming the folder. To change who
+  can open such a file, change its folder's `access.md`, or move the file to a
+  folder whose rules fit.
 
 Rules are enforced at runtime; a malformed `roles.yaml` or `access.md` surfaces
 when access is resolved.
 
+### Roles are pre-set — a "new role" is usually a group
+
+**What a role is.** A role in `roles.yaml` is an app role: a capability the
+platform defines and acts on (`Admin` is one), listed with the people who hold
+it. The set of roles is pre-set by the platform. A role is not a way to name a
+team.
+
+**Agents never create roles.** Add people to a role that already exists, or
+remove them, and nothing more: never add a role name to `roles.yaml`, and never
+rename one — a rename is a delete plus a create. Such a write is refused with a
+422 that names the role and says: app roles are pre-set — add people to
+existing roles, and use a GROUP for a task- or team-scoped set of people.
+Relay that refusal to your user as it stands; do not look for another way to
+write the file.
+
+**Is it really a group?** When someone asks for a "new role", it almost always
+is. It is a group when any of these hold:
+
+- the name says who the people are — a team, a project, a customer, a
+  committee — rather than a capability the platform already has;
+- it would change or disappear when the project ends or the team reshuffles;
+- its purpose is to give those people access to some folders or files.
+
+A request that matches a role that already exists is membership, not a new
+role.
+
+**What to do instead.**
+
+1. If an existing role already carries the capability, add the people to it.
+2. Otherwise make it a group: add or extend the group in `groups.yaml` (or
+   point your user at the app's Groups page), then grant the group in the
+   `access.md` of the folders it should reach.
+3. If your user still needs a role the platform does not have, that is not an
+   edit you can make — say so, and leave the decision to an admin.
+
+### Giving a role to a group
+
+A role's member list takes a group as well as individual emails. Write the
+entry as `- group:<Name>`, where `<Name>` is a group in the active group
+source — `synced-groups.yaml` when the deployment syncs groups from an
+identity provider, `groups.yaml` otherwise. Here a `Reviewer` role the
+deployment already has goes to a whole group:
+
+```yaml
+roles:
+  Admin:
+    - dana@example.com
+  Reviewer:
+    - lee@example.com
+    - group:Platform Team
+```
+
+- **Matching.** The name is matched case- and whitespace-insensitively against
+  the active group source, like role names: `group:platform team` and
+  `group:Platform  Team` are the same entry as `group:Platform Team`.
+- **Unknown groups are refused.** An entry naming a group the active source
+  does not declare is a validation error: the write is refused with a 422
+  that names the entry and its role (`'- group:Platfrom Team' under role
+  'Reviewer'`), and nothing is saved. Create the group first, or fix the name.
+- **A group under `Admin` makes every member a full admin** — including anyone
+  added to the group later, and including the right to edit `roles.yaml`
+  itself. Only make that edit when your user is an Admin and explicitly asks
+  for exactly that, and say so in the commit summary; for anyone else, tell
+  them what it would mean and who can do it (below). `Admin` must also always keep at least one
+  direct email member; a group entry alone is not enough, so a broken
+  directory can never leave the deployment without an admin.
+- **With direct emails.** Group entries and emails add up: the role's members
+  are everyone listed by email plus everyone currently in each listed group.
+  A person in both is simply a member; adding or removing someone from the
+  group changes the role with no edit to `roles.yaml`.
+- **With denials.** Group members hold the role's grants exactly as if they
+  were listed by email. A denial of the role in an `access.md`
+  (`deny role/Reviewer`) therefore removes the role's contribution for
+  everyone in the group, as it does for the emails. Write the `role/` form:
+  a bare `deny Reviewer` would deny a group named `Reviewer` instead, if one
+  exists. The nearest `access.md` that says
+  anything about the person decides: a person granted by name
+  (`Name <email>`) in the SAME `access.md` as the denial keeps that access,
+  because within one file a person's own entry beats a role entry. A grant by
+  name in a folder further up does not survive a role denial closer to the
+  file.
+
+**Only an Admin changes `roles.yaml`, and only on the default branch.** A
+change request cannot carry the edit: when a request is merged, `roles.yaml`
+is restored to what the default branch has, so a role edit drafted on a
+branch is dropped at the merge without a word. Do not propose one. If your
+user is an Admin, `edit_file` the file on the default branch directly — for
+example, to give the Reviewer role to a group, add the entry under the
+existing role:
+
+```yaml
+roles:
+  Admin:
+    - dana@example.com
+  Reviewer:
+    - lee@example.com
+    - group:Platform Team   # added
+```
+
+If your user is not an Admin, tell them who is (the `Admin` entries in
+`roles.yaml`) and that the change is made in the app's Roles page or by an
+admin editing the file; do not open a change request for it.
+
 ### Direct writes vs change requests
 
 File-level write access decides how a change lands on the default branch:
@@ -197,12 +407,30 @@ File-level write access decides how a change lands on the default branch:
   **write or owner on every file the change touches** may commit **directly**
   to the default branch.
 - Without that access, the change goes through a **branch + change request**,
-  approved by an owner / write-access holder of the affected files.
+  approved by an owner / write-access holder of the affected files — every
+  affected file with an eligible approver needs that approval, whatever its
+  type (notes, binary files, files without an extension).
 - Agents carry exactly their user's access, never more. Before writing to the
   default branch, **ask the user** whether to write directly or go through the
   review flow — and prefer a change request when in doubt, when the change is
   large, or when it touches content the user does not own.
 
+### An agent proposes and syncs; a person merges
+
+- **Propose** with `open_change_request`, then give the user the request's
+  `url`. Reviewing, approving and merging a change request happen in the app,
+  by a person — no agent tool approves a file, bypasses approval, or merges a
+  request. `merge_change_request` no longer exists.
+- **Sync** a draft with `merge_branch`, `source` = the branch the request
+  targets, `target` = the draft. This is allowed while the draft's request is
+  open, and is how you bring it up to date or surface conflicts to resolve on
+  the draft.
+- `merge_branch` refuses to merge a draft into the branch its open change
+  request targets — it names the request; ask the user to review it in the
+  app. Into a protected branch it merges only what you could commit there
+  directly, under the rule above — and never a change to `roles.yaml`, whoever
+  you are: roles are changed in the app, not merged in from a draft.
+
 ## 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
@@ -210,7 +438,7 @@ skills live under `{{skillsDir}}/`, organised by ownership; a skill that belongs
 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
-governance record:
+version:
 
 ```yaml
 ---
@@ -219,23 +447,34 @@ description: Drafts the Friday newsletter for review.
 allowed-tools: [slack_post_message]
 metadata:
   version: "1.4.0"
-  owner: "GTM"
-  lifecycle: active
 ---
 ```
 
 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. `metadata.version` is semver; `metadata.lifecycle` is `active`,
-`deprecated` (still served, flagged in the library) or `retired` (kept for
-its owners, never distributed to agents).
+the skill. `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.
+
+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:
+skills are read from the workspace on every request, on either connection.
+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 a `hexis-all` bundle that installs everything.
+server, and `hexis-all`, one plugin holding every skill they may read and
+the MCP server, for a single install.
 
 ## Tool Manuals (`{{pluginsDir}}/<Plugin>/software.bevel.hexis/tools/*.tool`)
 
@@ -391,6 +630,12 @@ Call the **`list_tool_setup`** tool to see, for every accessible tool — `.tool
 - **`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: `list_skills` and `get_skill` read the workspace on every request, so a committed `SKILL.md` is in the very next 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:

package/kb-template/KnowledgeBase/How to get started.md

@@ -55,7 +55,7 @@ exactly what you can see and can do exactly what you can do, nothing more.
 
 ## Good to know
 
-- The repo root's `AGENTS.md` is the full reference your agents read. It is
+- The repo root's `{{agentsFile}}` is the full reference your agents read. It is
   maintained by the platform, so leave it as it is; team conventions belong in
   documents like this one.
 - Nothing is ever really lost: every version of every file stays in the