@bevel-software/platform-core-backend 0.7.5 → 0.8.0

package/dist/shared/variable-refs.js

@@ -0,0 +1,60 @@
+/**
+ * The ONE variable-reference grammar, shared by every boundary that has to
+ * decide "would the substitutor expand this?" — `.tool` parsing, `mcp.json`
+ * discovery, the server editor's header split, and the Groups→Plugins
+ * migration. The decision has credential stakes on both sides (a reference
+ * mis-read as prose is a `${VAR}` written into portable, world-readable
+ * `mcp.json`; prose mis-read as a reference is a header that stops working),
+ * so the classifiers must not each keep their own approximation of it.
+ */
+/**
+ * The SDK substitutor's reference grammar, exactly: `${VAR}` or `$VAR`, names
+ * `[a-zA-Z0-9_]+`. Note a LEADING DIGIT is legal — `$5TOKEN` (and `$5` in
+ * prose) is a reference as far as substitution is concerned, and classifying
+ * it as anything else here would diverge from what actually expands.
+ */
+export const VARIABLE_REFERENCE_RE = /\$\{([a-zA-Z0-9_]+)\}|\$([a-zA-Z0-9_]+)/g;
+// `.test()` on a global regex is stateful (lastIndex persists across calls) —
+// the predicate gets its own non-global compilation of the same source.
+const VARIABLE_REFERENCE_ONCE = new RegExp(VARIABLE_REFERENCE_RE.source);
+/** True when any substring of `text` is a substitutor reference. */
+export function containsVariableReference(text) {
+    return VARIABLE_REFERENCE_ONCE.test(text);
+}
+/**
+ * Variable names the platform seeds for its own (Bevel-hosted) manuals:
+ * `<ns>_API_URL` points a manual at the backend and `<ns>_CONNECTION_KEY`
+ * carries the platform bearer. User-declared variables may not take these
+ * names, and user content may not reference them (bare or namespaced).
+ */
+export const RESERVED_VARIABLE_NAMES = ['API_URL', 'CONNECTION_KEY'];
+/**
+ * A NAME is reserved by SUFFIX, not by exact match: the substitutor looks a
+ * variable up under the manual's UTCP namespace first, so `${<ns>_CONNECTION_KEY}`
+ * resolves the very same seeded value the bare `${CONNECTION_KEY}` does.
+ * Suffix matching also refuses harmless-looking near-misses (`MY_API_URL`) —
+ * deliberately fail-closed.
+ */
+export function isReservedVariableName(varName) {
+    return RESERVED_VARIABLE_NAMES.some((reserved) => varName.endsWith(reserved));
+}
+/**
+ * The first reserved REFERENCE anywhere in `doc` (scanned as JSON text), or
+ * null. Built on the shared grammar above, so what counts as a reference here
+ * is exactly what counts everywhere else — `${ API_URL }` with spaces is not
+ * expandable, so it is a literal to every boundary, not reserved to one and
+ * portable to another.
+ */
+export function findReservedVariableRef(doc) {
+    const text = JSON.stringify(doc) ?? '';
+    // A fresh instance per scan: `matchAll` COPIES the source regex's
+    // `lastIndex` (spec), and the exported one is mutable module state — any
+    // future `.exec`/`.test` on it would make this scan start mid-string.
+    for (const match of text.matchAll(new RegExp(VARIABLE_REFERENCE_RE.source, VARIABLE_REFERENCE_RE.flags))) {
+        const varName = match[1] ?? match[2] ?? '';
+        if (isReservedVariableName(varName))
+            return match[0];
+    }
+    return null;
+}
+//# sourceMappingURL=variable-refs.js.map

package/dist/shared/variable-refs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"variable-refs.js","sourceRoot":"","sources":["../../src/shared/variable-refs.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,0CAA0C,CAAC;AAEhF,8EAA8E;AAC9E,wEAAwE;AACxE,MAAM,uBAAuB,GAAG,IAAI,MAAM,CAAC,qBAAqB,CAAC,MAAM,CAAC,CAAC;AAEzE,oEAAoE;AACpE,MAAM,UAAU,yBAAyB,CAAC,IAAY;IACpD,OAAO,uBAAuB,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAsB,CAAC,SAAS,EAAE,gBAAgB,CAAC,CAAC;AAExF;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAe;IACpD,OAAO,uBAAuB,CAAC,IAAI,CAAC,CAAC,QAAQ,EAAE,EAAE,CAAC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,uBAAuB,CAAC,GAAY;IAClD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC;IACvC,kEAAkE;IAClE,yEAAyE;IACzE,sEAAsE;IACtE,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,MAAM,CAAC,qBAAqB,CAAC,MAAM,EAAE,qBAAqB,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC;QACzG,MAAM,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC3C,IAAI,sBAAsB,CAAC,OAAO,CAAC;YAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/kb-template/.bevelignore

@@ -22,4 +22,4 @@ CLAUDE.md
 **/access.md
 roles.yaml
 
-Groups/
+Plugins/

package/kb-template/AGENTS.md

@@ -21,36 +21,77 @@ change them.
 ```text
 knowledge-base/
 ├── KnowledgeBase/        ← the knowledge itself; organise it however suits you
-├── Groups/               ← one folder per group: its skills AND its tools
+├── Plugins/              ← one folder per plugin: its skills AND its tools
 ├── roles.yaml            ← identity → role mapping (Admin-only edits)
 └── access.md             ← repo-root access-control rules
 ```
 
-Only those two folders are structural, and only `Groups/` has a layout the
+Only those two folders are structural, and only `Plugins/` has a layout the
 platform reads:
 
 ```text
-Groups/<Group>/<skill>/SKILL.md   a skill
-Groups/<Group>/<name>.tool        a tool manual
-Groups/<Group>/access.md          who can read/write the whole group
-Groups/personal-<user-id>/…       one per person: their own skills, private
+Plugins/<Plugin>/plugin.json                  the manifest (Agent Plugins)
+Plugins/<Plugin>/skills/<skill>/SKILL.md      a skill
+Plugins/<Plugin>/mcp.json                     MCP servers (authoritative)
+Plugins/<Plugin>/software.bevel.hexis/tools/  `.tool` manuals
+Plugins/<Plugin>/access.md                    who can read/write the plugin
+Plugins/personal-<user-id>/…                  one per person: private
 ```
 
-Skills and tools live TOGETHER in a group because they share one access
-boundary: a tool a group cannot read is a skill that group cannot run.
-
-**Group folders are made through the app, not by writing files.** A group
+Skills and tools live TOGETHER in a plugin because they share one access
+boundary: a tool a plugin cannot read is a skill that plugin cannot run.
+
+**Symlinks are not supported anywhere under `Plugins/`.** Access control
+resolves rules by path, and a symlink is a second path to the same content —
+the two can disagree about who may read what. The platform never creates
+them and ignores any it finds (they can only arrive via a direct git push).
+
+**A plugin follows the [Agent Plugins](https://agent-plugins.org) specification**
+(v1.0.0), so another conformant client can load one: it reads `plugin.json`, the
+skills under `skills/`, and the servers in `mcp.json`, and ignores everything
+else. Two things here are ours and sit outside that portable core. `access.md`
+stays at the plugin root because access resolution walks root → file, so the
+same rules one level down would govern only that subtree. And `http`/`inline` `.tool`
+manuals live under the reverse-DNS `software.bevel.hexis/` namespace, because
+the specification describes MCP servers only and has no way to express them.
+
+**MCP servers belong in `mcp.json` — do not write `.tool` files for them.**
+Each `mcpServers` key is the server's identity: it is the namespace its vault
+secrets bind to (`<name>_<VAR>`), so renaming a key unbinds every configured
+secret and sign-in. The portable entry carries only where the server is
+(`type`, `url`, literal headers). Anything this platform needs beyond that —
+auth headers carrying `${VAR}` vault references, `variables` declarations,
+a `description`, or `local: true` for a server only reachable from a user's
+machine — goes in `plugin.json` under
+`extensions["software.bevel.hexis"].mcpServers[<name>]`, which other clients
+ignore by design. A `type: "stdio"` entry (a command run on the user's own
+machine) is always local: the hosted endpoint never spawns it; the local
+`hexis-mcp` server fetches the plugin's files to a local directory and runs it
+per the Agent Plugins runtime contract (`PLUGIN_ROOT`/`PLUGIN_DATA`, `./`
+commands contained to the plugin).
+
+**Secrets are never written into a plugin's portable files.** The specification
+defines no portable credential mechanism on purpose: authorization and
+credential storage are the client's business, header and `env` values are
+"visible package data", and a client must not expand anything except
+`${PLUGIN_ROOT}` and `${PLUGIN_DATA}`. So the Secrets Vault IS this platform's
+answer to that — and `mcp.json` carries only where a server is, never a
+`${VAR}` reference to how to authenticate with it. Those live in `plugin.json`
+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 plugin
 exists exactly when its folder carries an `access.md` — a bare directory
-under `Groups/` is not a group and is never listed. A new
-direct child of `Groups/` needs an `access.md` naming who runs it, and the
+under `Plugins/` is not a plugin and is never listed. A new
+direct child of `Plugins/` 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 group by writing a skill into `Groups/<new-name>/…`; it will be
-denied. Send the user to the app's **New group** button (or its
-`POST /api/groups` endpoint), then write into the folder it made. Names
+create a plugin by writing a skill into `Plugins/<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 group — a signed-in user's own skills belong
-there, and move into a group by moving the skill's folder.
+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.
 
 Everything under `KnowledgeBase/` is yours to arrange. Subfolders, naming,
 whether a topic is one file or twenty — all of it is a judgement call about
@@ -99,7 +140,7 @@ File-level write access decides how a change lands on the default branch:
   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.
 
-## Skills (`Groups/<Group>/<skill>/SKILL.md`)
+## Skills (`Plugins/<Plugin>/skills/<skill>/SKILL.md`)
 
 A skill is a folder holding a `SKILL.md` and whatever files it needs. The
 frontmatter names it and declares which tools it may use:
@@ -113,21 +154,25 @@ allowed-tools: [slack_post_message]
 ```
 
 The body is the instructions, in plain markdown. `allowed-tools` entries are
-tool names from the `.tool` manuals in the same group — a skill can only reach
-tools its group can read.
+tool names from the `.tool` manuals in the same plugin — a skill can only reach
+tools its plugin can read.
 
-## Tool Manuals (`Groups/<Group>/*.tool`)
+## Tool Manuals (`Plugins/<Plugin>/software.bevel.hexis/tools/*.tool`)
 
-Each group 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 directly in the group folder whose skills use it. The same
-integration may exist in several groups as separate files (`Everyone/notion.tool`
-and `Finance/notion.tool`), each with its own credentials and access rule —
-a group is a folder, not a registry of unique names.
+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. Remember: `.tool` files are for `http` and `inline` manuals
+only; MCP servers belong in `mcp.json`.
 
 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.
-- **`mcp`** — `url` is a remote MCP server whose tools are discovered over MCP.
+
+(`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):
 
@@ -138,8 +183,8 @@ write:
   - Product Team
 owner:
   - Jane Doe <jane@x.com>
-type: mcp
-url: https://mcp.example.com
+type: http
+url: https://api.example.com/utcp
 ---
 ```
 
@@ -149,7 +194,15 @@ url: https://mcp.example.com
 
 **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 mcp/http `url` on `localhost`): the hosted remote MCP endpoint then skips it and instead advertises it through the `list_local_tools` tool, which returns the `.tool`'s path so a local agent can read it and self-configure (e.g. add the MCP server to its own client).
+**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 come from the environment of whatever launched the command (your MCP client's config), since the Secrets Vault never leaves the server. 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
 
@@ -207,21 +260,21 @@ An `inline` manual with one 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 type from what you found.** An MCP server → `type: mcp` with the official `url` (the MCP transport is HTTP/streamable — use the `https://…` URL, **never** `ws://`/`wss://`). A plain REST/HTTP endpoint → `type: http`. Use `type: inline` only when hand-authoring the individual HTTP calls.
-3. **An OAuth-protected MCP server usually needs NOTHING beyond `type: mcp` + `url`.** 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`.
+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` — see the walkthrough below). Those DO need a sign-in variable to hold the client id, 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`.
 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. **Set `remote: false`** only when the tool is reachable ONLY from the user's own machine (e.g. a `localhost` MCP server); otherwise leave it remote-capable.
+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`, 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:
+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 `type: mcp`): `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 provider does not support automatic registration, so a tool writer must configure it by hand (below).
+- **`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 provider does not support automatic registration, so a tool writer must configure it by hand (below).
 - **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).
 
-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 that `.tool` file itself** — granted by its frontmatter `write:`/`owner:` verbs or the `access.md` chain, NOT by any platform role. The people who manage a `.tool` file are exactly the people who configure its shared secrets. To delegate a tool to someone, add them to the file's `write:` or `owner:` list (an edit you can make via change request); that alone lets them configure it.
+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

@@ -17,7 +17,7 @@ Use the app switcher in the top-left corner to move between the two views:
 
 - **Knowledge** is the reading and writing surface: a file tree on the left,
   the document on the right.
-- **Skills & Tools** is the library: groups of skills and tools, who runs
+- **Skills & Tools** is the library: plugins holding skills and tools, who runs
   them, and what still needs setting up.
 
 ## Write your first document
@@ -29,22 +29,22 @@ someone else, you get **Propose changes** instead. A proposal becomes a
 nothing moves until they approve it. That is the whole safety model, and it
 applies to agents exactly as it applies to people.
 
-## Set up your group
+## Set up your plugin
 
-In Skills & Tools, use **New group** to make a place for your team. Creating
-a group makes you the one who runs it: you approve its change requests,
+In Skills & Tools, use **New plugin** to make a place for your team. Creating
+a plugin makes you the one who runs it: you approve its change requests,
 answer join requests, and manage who can see what (the **Share** button on
-the group page). Skills you create outside any group land in your own private
-space and can move into a group later.
+the plugin page). Skills you create outside any plugin land in your own private
+space and can move into a plugin later.
 
 ## Give your agents skills and tools
 
-- On a group page, **+** adds a skill: name it and an empty skill file opens,
+- On a plugin page, **+** adds a skill: name it and an empty skill file opens,
   ready for instructions. Write it the way you would brief a careful new
   colleague: what to load, what to do, what to record.
-- Tools are added as small manual files in the group. Sign-ins and keys are
-  entered on the **Connect** page or the tool's own page, never written into
-  files.
+- Tools live in the plugin too: most are small manual files, and MCP servers
+  go in the plugin's `mcp.json`. Sign-ins and keys are entered on the
+  **Connect** page or the tool's own page, never written into files.
 
 ## Connect your AI agent
 

package/kb-template/access.md

@@ -1,36 +1,36 @@
----
-write:
-  - Admin
-download:
-  - Admin
-owner: []
----
-
-# Repository access
-
-This file is the root of the access-control tree for this knowledge base. It grants
-write access only to the `Admin` role by default. Subfolders can broaden or narrow
-access by adding their own `access.md`.
-
-See [roles.yaml](roles.yaml) for the identity → role mapping. Access resolution and validation
-run in the Bevel platform.
-
-## Adding a folder-level rule
-
-Drop an `access.md` into any folder, at any depth. Frontmatter
-only — the body is ignored. Example:
-
-```yaml
----
-write:
-  - Admin
-  - Editor
-  - Jane Doe <jane.doe@example.com>
-  - deny Mallory Bad <mallory@example.com>
----
-```
-
-Each entry is either a grant (bare principal) or a denial (`deny <principal>` —
-**lowercase `deny` only**; capitalised forms like `Deny` are treated as part of a
-name). A principal is either a role name (matched case-insensitively against
-`roles.yaml`) or a user reference in `Name <email>` form.
+---
+write:
+  - Admin
+download:
+  - Admin
+owner: []
+---
+
+# Repository access
+
+This file is the root of the access-control tree for this knowledge base. It grants
+write access only to the `Admin` role by default. Subfolders can broaden or narrow
+access by adding their own `access.md`.
+
+See [roles.yaml](roles.yaml) for the identity → role mapping. Access resolution and validation
+run in the Bevel platform.
+
+## Adding a folder-level rule
+
+Drop an `access.md` into any folder, at any depth. Frontmatter
+only — the body is ignored. Example:
+
+```yaml
+---
+write:
+  - Admin
+  - Editor
+  - Jane Doe <jane.doe@example.com>
+  - deny Mallory Bad <mallory@example.com>
+---
+```
+
+Each entry is either a grant (bare principal) or a denial (`deny <principal>` —
+**lowercase `deny` only**; capitalised forms like `Deny` are treated as part of a
+name). A principal is either a role name (matched case-insensitively against
+`roles.yaml`) or a user reference in `Name <email>` form.