@bevel-software/platform-core-backend 0.14.0 → 0.19.0

package/kb-template/AGENTS.md

@@ -1,12 +1,26 @@
+---
+# 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
-> `KnowledgeBase/`, linked from wherever they are needed.
+> **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
@@ -20,34 +34,73 @@ change them.
 
 ```text
 knowledge-base/
-├── KnowledgeBase/        ← the knowledge itself; organise it however suits you
-├── Plugins/              ← one folder per plugin: its skills AND its tools
+├── {{knowledgeBaseDir}}/        ← the knowledge itself; organise it however suits you
+├── {{skillsDir}}/               ← shared skills, organised by who owns them
+├── {{pluginsDir}}/              ← one folder per plugin: its tools, and links to skills
 ├── roles.yaml            ← identity → role mapping (Admin-only edits)
 └── access.md             ← repo-root access-control rules
 ```
 
+(The three root names above are this deployment's own — a deployment may
+rename them in its setup screen, and this guide is rendered with the names in
+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/KnowledgeBase/Foo.md`, never `KnowledgeBase/Foo.md`. A path
-without that prefix is refused, because it would land beside the repository
-where git never sees it.
-
-Only those two folders are structural, and only `Plugins/` has a layout the
+`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
+it is ownership (`{{skillsDir}}/<scope>/…/<skill>/SKILL.md`, with an `access.md` in
+any scope folder that needs its own rules). `{{pluginsDir}}/` has a layout the
 platform reads:
 
 ```text
-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
+{{pluginsDir}}/<Plugin>/plugin.json                  the manifest (Agent Plugins) — what makes the folder a plugin; its `name` is the plugin's identity
+{{pluginsDir}}/<Plugin>/skills/<skill>/SKILL.md      a skill that lives inside the plugin
+{{pluginsDir}}/<Plugin>/mcp.json                     MCP servers (authoritative)
+{{pluginsDir}}/<Plugin>/software.bevel.hexis/tools/  `.tool` manuals
+{{pluginsDir}}/<Plugin>/access.md                    who can read/write the plugin
+{{pluginsDir}}/personal-<user-id>/…                  one per person: private
+```
+
+**The manifest's `name` is the plugin.** It is a kebab-case identifier
+(`sales-team`), and it is what every grant spells (`plugin/sales-team/read`),
+what the URLs and the catalog key on, and what the compiled marketplace
+publishes the plugin as. `displayName` is what people see it called ("Sales
+Team"); absent, the folder name is shown. Rename a plugin from its page in the
+app: an identifier change rewrites every grant that names it, in one commit —
+editing `name` by hand leaves those grants pointing at a plugin that no longer
+exists.
+
+**A plugin LINKS shared skills rather than containing them.** Its manifest
+lists skill paths under `extensions["software.bevel.hexis"].skills` — each
+entry is one skill folder or a folder of skills under `{{skillsDir}}/`:
+
+```json
+{ "extensions": { "software.bevel.hexis": { "skills": ["{{skillsDir}}/Engineering/deploy", "{{skillsDir}}/Sales"] } } }
 ```
 
-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.
+One skill, stored once, can be listed by many plugins. A plugin's effective
+skills are the ones inside its folder plus everything its links resolve to.
+Do not edit that list by hand: linking is done from the plugin's page in the
+app, because it is two edits at once — the manifest entry AND a grant on the
+skill (see *Access control* below). A manifest entry without the grant lists
+a skill the plugin's members cannot read; the app shows such a link as
+needing setup and offers Repair.
+
+**Ownership decides who may read a skill, never the plugin.** A shared
+skill's readability comes from the `access.md` rules on its own folder and
+the scopes above it. A plugin that links a skill someone cannot read simply
+does not show it to them.
 
-**Symlinks are not supported anywhere under `Plugins/`.** Access control
+**Symlinks are not supported anywhere under `{{pluginsDir}}/`.** 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).
@@ -89,20 +142,29 @@ 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 plugin
-exists exactly when its folder carries an `access.md` — a bare directory
-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 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 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,
+**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. 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
 what the next reader needs, not a rule the platform enforces.
 
@@ -111,25 +173,109 @@ 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.
+  = `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). 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`
+  is `<name>`, derived live from the plugin's own `access.md`. Any spelling
+  folds to the identifier (`plugin/GTM/read` and `plugin/gtm/read` are one
+  principal). This is how a shared skill is made visible to a plugin's
+  members: `read: plugin/gtm/read` on the skill's folder.
+  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.
@@ -137,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:
@@ -149,30 +407,76 @@ 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.
 
-## 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:
+### 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
+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:
 
 ```yaml
 ---
 name: weekly-newsletter
 description: Drafts the Friday newsletter 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 in the same plugin — a skill can only reach
-tools its plugin can read.
-
-## Tool Manuals (`Plugins/<Plugin>/software.bevel.hexis/tools/*.tool`)
+tool names from the `.tool` manuals and MCP servers of the plugins that hold
+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 `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`)
 
 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
@@ -326,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:
@@ -371,7 +681,7 @@ merely correct.
 
 ## Finding things
 
-- `grep` for keywords across `KnowledgeBase/`.
+- `grep` for keywords across `{{knowledgeBaseDir}}/`.
 - Follow markdown links: when you read `[Some Page](relative/path/Some Page.md)`,
   that path is relative to the file you are reading.
 - `list_files` to see the shape of a folder before assuming where something

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

package/kb-template/access.md

@@ -18,9 +18,11 @@ owner:
 #
 # 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.
+# treated as part of a name). A principal is a role name from roles.yaml
+# (matched case-insensitively), a group name from groups.yaml, a person as
+# `Name <email>`, or `everyone` — every signed-in person and their agents, the
+# whole organisation. `read: everyone` in a folder's BODY opens that folder to
+# all; the same line in a file's frontmatter only makes that one file visible.
 #
 # 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:

package/kb-template/mcp-description.md

@@ -0,0 +1,27 @@
+<!-- Remove this comment wrapper (the first and last lines of this file) to broadcast the text below to every connected agent.
+
+This file is the deployment preamble. Every agent that connects to this knowledge base over MCP, hosted or through the local hexis-mcp server, is told its content at the start of each session, whatever that agent's access. It arrives after a fixed platform header that already says what Hexis is and to search here before answering from memory; this file adds what only you know: what this knowledge base holds, where things are, and when an agent must look here first.
+
+Keep the content under 6,000 characters. Keep the first paragraph under about 220 characters: a fixed purpose sentence of 76 characters is put in front of it, the two together are cut at 300, and the result is shown at the start of the start_session, grep, list_files and read_file tool descriptions, which is all some clients (claude.ai on the web, Cline, the Agent SDK) show the model. Text inside an HTML comment like this one is never sent, so notes to yourself can stay here. Folder names you write are sent to every agent, including those that cannot open the folders.
+
+Starter skeleton, fill in and delete what does not apply:
+
+Acme is a solar developer in Spain. This knowledge base holds our project files, permitting process, customer records and engineering conventions.
+
+## What is where
+
+- {{knowledgeBaseDir}}/Projects/: one folder per site, with its permits, contracts and status.
+- {{knowledgeBaseDir}}/Processes/: how we run permitting, procurement and commissioning.
+- {{knowledgeBaseDir}}/Customers/: accounts, contacts and meeting notes.
+
+## Always check here before answering about
+
+- Any project, customer or supplier by name.
+- Our permitting steps, timelines and the authorities involved.
+- Internal terms, acronyms and team responsibilities.
+
+## Conventions
+
+- Dates are written YYYY-MM-DD. Money is in EUR unless stated.
+- Cite the file you read when you answer from it.
+-->

package/migrations/0005_github_facade.sql

@@ -0,0 +1,25 @@
+CREATE TABLE "github_facade_codes" (
+	"user_id" uuid PRIMARY KEY NOT NULL,
+	"client_id" text NOT NULL,
+	"code_hash" text NOT NULL,
+	"redirect_uri" text NOT NULL,
+	"expires_at" timestamp NOT NULL,
+	"consumed_at" timestamp,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	CONSTRAINT "github_facade_codes_code_hash_unique" UNIQUE("code_hash")
+);
+--> statement-breakpoint
+CREATE TABLE "github_facade_identity" (
+	"id" text PRIMARY KEY NOT NULL,
+	"app_id" text NOT NULL,
+	"client_id" text NOT NULL,
+	"client_secret" text NOT NULL,
+	"webhook_secret" text NOT NULL,
+	"private_key_pem" text NOT NULL,
+	"public_key_pem" text NOT NULL,
+	"created_at" timestamp DEFAULT now() NOT NULL,
+	"rotated_at" timestamp
+);
+--> statement-breakpoint
+ALTER TABLE "api_tokens" ADD COLUMN "kind" text DEFAULT 'key' NOT NULL;--> statement-breakpoint
+ALTER TABLE "github_facade_codes" ADD CONSTRAINT "github_facade_codes_user_id_users_id_fk" FOREIGN KEY ("user_id") REFERENCES "public"."users"("id") ON DELETE cascade ON UPDATE no action;

package/migrations/0006_api_tokens_revoked_by.sql

@@ -0,0 +1 @@
+ALTER TABLE "api_tokens" ADD COLUMN "revoked_by" text;

package/migrations/0007_github_facade_registered.sql

@@ -0,0 +1 @@
+ALTER TABLE "github_facade_identity" ADD COLUMN "registered_at" timestamp;

package/migrations/0008_change_request_apply_failure.sql

@@ -0,0 +1,4 @@
+ALTER TABLE "change_requests" ADD COLUMN "apply_failure_reason" text;--> statement-breakpoint
+ALTER TABLE "change_requests" ADD COLUMN "apply_failure_conflicts" boolean;--> statement-breakpoint
+ALTER TABLE "change_requests" ADD COLUMN "apply_failed_at" timestamp;--> statement-breakpoint
+ALTER TABLE "change_requests" ADD COLUMN "apply_failed_by_name" text;