@bevel-software/platform-core-backend 0.9.0 → 0.9.1

package/kb-template/AGENTS.md

@@ -110,11 +110,17 @@ Write access to any path is governed by `roles.yaml` (who has which role) and
 - **Roles** in `roles.yaml` map a role name to a list of emails. Role names are
   case- and whitespace-insensitive (`Admin` = `admin` = `ADMIN`; `Product Team`
   = `product team`). The reserved name `deny` cannot be used.
-- **Access rules** live in `access.md` files. Each declares a `write:` list
-  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.
+- **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.
+- **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.
 - **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.

package/kb-template/access.md

@@ -1,36 +1,46 @@
 ---
+# Frontmatter governs THIS FILE — who may change the repository-wide rules below.
+owner:
+  - Admin
+---
+# Body governs the FOLDER. This is the root of the access-control tree, so every
+# path inherits what is declared here unless a nearer access.md overrides it.
+#
+# Two blocks, two scopes: the frontmatter above is about this file, the body
+# here is about the folder. Keep the body pure YAML and put prose in `#`
+# comments like these — a body that does not parse as YAML naming at least one
+# verb falls back to the older format, in which the FRONTMATTER carried the
+# folder's rules. That fallback is silent.
+#
+# Verbs are read, write, download and owner. `owner` implies the rest and
+# `write` implies `read`. Read is default-deny: a folder with no `read:` grant
+# is invisible to everyone except admins, who read through `write: Admin`.
+#
+# Each entry is a grant (a bare principal) or a denial (the lowercase word
+# `deny`, a space, then the principal — capitalised forms like `Deny` are
+# treated as part of a name). A principal is a role name from roles.yaml,
+# matched case-insensitively, or a user reference in `Name <email>` form.
+# See roles.yaml for the identity to role mapping.
+#
+# To tighten or widen a subtree, drop an access.md into any folder at any depth,
+# with the same two blocks. For example, in KnowledgeBase/Finance/access.md:
+#
+#     ---
+#     owner:
+#       - Admin
+#     ---
+#     read:
+#       - Finance
+#     write:
+#       - Admin
+#       - Jane Doe <jane.doe@example.com>
+#       - deny Mallory Bad <mallory@example.com>
+#
+# Resolution walks the repo root down to the file's own directory; for each
+# principal, the closest rule naming them wins. Rules are enforced at runtime,
+# so a malformed roles.yaml or access.md surfaces when access is resolved.
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bevel-software/platform-core-backend",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Open-source core backend of the Bevel platform: git-backed knowledge workspace, workflow (branches/change requests/locks/SSE), skills, tools, secrets vault, access control and the remote MCP surface.",
   "type": "module",
   "main": "./dist/index.js",
@@ -46,8 +46,8 @@
     "pg": "^8.20.0",
     "yaml": "^2.9.0",
     "zod": "^3.24.0",
-    "@bevel-software/platform-mcp-core": "0.9.0",
-    "@bevel-software/platform-shared": "0.9.0"
+    "@bevel-software/platform-mcp-core": "0.9.1",
+    "@bevel-software/platform-shared": "0.9.1"
   },
   "devDependencies": {
     "@types/adm-zip": "^0.5.8",