@bevel-software/platform-core-backend 0.25.2 → 0.27.0

package/agent-guide/access-control.md

@@ -0,0 +1,251 @@
+## Access control
+
+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 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 names `deny` and `everyone` 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 (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 personal plugin
+  (`{{pluginsDir}}/personal-<id>/`) grants its owner access and 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`, …) 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.
+- **`roles.yaml` is editable only by Admin** — hard-coded in the resolver,
+  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 and `.tool` definitions.** 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; a distribution may register further file kinds
+  that carry their own rules. Any 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:
+
+- A user — or an agent acting as that user — whose access resolution grants
+  **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 — 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.
+- **Delete** a draft with `delete_branch`, which removes it for everyone. Only
+  its author (`<email-localpart>/…`, or your own `suggestions/…` bundle) or an
+  Admin may. Preview with `dryRun: true` first: it changes nothing and says
+  whether the delete would go through, how many commits are not on the default
+  branch, and the last commit. A branch holding such commits is refused unless
+  you pass `discardUnmerged: true` — only when the user wants that work gone. An
+  open change request from or into the branch that proposes nothing is closed
+  by the delete. One that still proposes something refuses it, with a link:
+  its author can withdraw it, or an Admin can decline it, in the app — hand the
+  user that link. A request you cannot see is not named, and a preview leaves
+  it out, so a delete can still be refused after a clean preview. Hand the user the
+  `lastCommit` it answers, so the branch can be restored. The server removes a
+  draft on its own once its change request was merged, but only while nothing
+  has happened to it since: no commit that is not on the default branch, no
+  request open from or into it, no save still landing, no file held for
+  editing, and its last commit
+  the one that was merged. Any other draft stays until someone deletes it.

package/agent-guide/conventions.md

@@ -0,0 +1,35 @@
+## Conventions
+
+These are conventions, not validations — nothing rejects a file for breaking
+them. They exist because a knowledge base people can navigate beats one that is
+merely correct.
+
+1. **Descriptive file names.** `Weekly-Sync-2026-03-14.md` beats `notes3.md`.
+   Avoid spaces; they survive git fine but make links noisier to read.
+
+2. **Markdown links between documents.** Use
+   `[Page Name](relative/path/to/Page.md)`, relative to the LINKING file's
+   directory rather than the repo root, so links resolve both in the app and on
+   the git host.
+   `move_file` keeps most of them working: it rewrites the links inside the
+   moved files and those in the other markdown pages it searches, and names
+   what it left — HTML pages, raw HTML inside a markdown page, and pages you
+   may not change. It does not search
+   `transcripts/` or `probes/` folders, and pages you cannot read are neither
+   searched nor named (the answer only says such pages may exist); links there
+   can still point at the old path. Paths written in prose or code are not
+   links, and a move leaves them as they are.
+
+3. **Absolute dates.** `YYYY-MM-DD`, never "last Tuesday" — a saved file
+   outlives the moment it was written.
+
+4. **Search before creating.** If a document on the subject exists, extend it
+   rather than starting a rival.
+
+5. **Preserve what is there.** Append or edit sections; do not overwrite a file
+   wholesale unless asked to.
+
+6. **Say where it came from.** When a claim rests on a specific source — a
+   person, a ticket, a document, a URL — name it inline near the claim, with
+   the date it was true. The next reader's first question is "says who, and is
+   it still true?".

package/agent-guide/directory-structure.md

@@ -0,0 +1,145 @@
+## Directory Structure
+
+```text
+{{kbDirName}}/
+├── {{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 composed.)
+
+Tool paths are workspace-relative, and the workspace root holds this
+repository as the `{{kbDirName}}/` folder (this deployment's own name for its
+checkout): a file in it is `{{kbDirName}}/{{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 `{{kbDirName}}/` rather than refused, so
+`{{knowledgeBaseDir}}/Foo.md` names that same file, and so does the
+root-anchored `/{{kbDirName}}/{{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
+{{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"] } } }
+```
+
+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 `{{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).
+
+**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). A stdio server SHOULD exit when its stdin
+reaches EOF — the client also terminates it on shutdown, but a server that
+ignores EOF outlives crashes as an orphan whose working directory blocks the
+plugin folder from ever refreshing.
+
+**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 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 personal plugin, holding their own skills and
+  tools, 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. A note or any other document goes under
+  `{{knowledgeBaseDir}}/` instead — see **Where a new file goes**.
+- `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 plugin into a shared 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.
+
+A deployment may reserve further root folders of its own — `Data/`, `Agents/`
+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.

package/agent-guide/finding-things.md

@@ -0,0 +1,7 @@
+## Finding things
+
+- `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
+  lives.

package/agent-guide/html-views.md

@@ -0,0 +1,83 @@
+## HTML views
+
+An `.html` (or `.htm`) file in the knowledge base is a live page: the app shows
+it in a sandboxed frame, scripts and all. Write one when a reader is better
+served by something interactive — a dashboard, a filterable table, a chart —
+than by a markdown document.
+
+### The frame
+
+- **No network.** The page cannot fetch, load or send anything: no `fetch`, no
+  XHR, no WebSocket, no external script, stylesheet, font or image. Put the
+  data the page shows into the page itself.
+- **Inline scripts and styles only.** `<script src>`, `<link>`, `<iframe>`,
+  `<object>`, `<embed>`, `<base>` and `<meta>` are removed. Write CSS in a
+  `<style>` element and code in an inline `<script>`. An image is a `data:`
+  URL.
+- **Scripts run as ES modules**, in source order, after the document is
+  parsed: `document.getElementById` works without waiting for
+  `DOMContentLoaded`, top-level `await` works, and a top-level declaration is
+  local to its script, not a global.
+- **No browser storage.** `localStorage`, `sessionStorage`, IndexedDB and
+  cookies are unavailable; a page keeps no state between views.
+- **No host navigation.** The page cannot navigate the app, open a window or
+  submit a form. Links reach the app through the bridge below.
+- **`window.bevel` exists only in the app.** Opened anywhere else, the page has
+  no bridge; guard a call with `window.bevel?.openNode`.
+
+### `window.bevel`
+
+Core puts two members on it:
+
+- `window.bevel.openNode(href)` — follow `href` as if the reader had clicked a
+  link to it.
+- `window.bevel.navigate(href)` — the same function under a second name.
+
+A distribution may add data members of its own to `window.bevel`; its own
+section of this guide names them. Do not call a member this guide does not
+name.
+
+### Links written in the markup
+
+An `<a href>` in the page keeps its address only when it is one of these:
+
+- a document of the knowledge base, `.md`, `.html` or `.htm`, with or without a heading — `../Knowledge/Alice.md#goal`, `Q3-Report.html`, `Notes.htm`
+- an absolute workspace URL — `/workspace/main/{{knowledgeBaseDir}}/Alice.md`
+- an external address — `https://example.com/docs`, `http://example.com`, `mailto:team@example.com`
+- a bare fragment, a place in this page — `#totals`, `#`
+
+Every other address is removed from the link when the page is shown, and the
+link goes nowhere:
+
+- any other scheme — `javascript:alert(1)`, `data:text/html,hi`, `file:///etc/hosts`, `tel:+15550100`
+- a protocol-relative address — `//cdn.example.com/lib.js`
+- a relative path to anything else — `data.csv`, `../Images/chart.png`
+
+### How a link resolves
+
+The same rules apply to a click on a link and to `window.bevel.openNode(href)`
+or `window.bevel.navigate(href)`:
+
+- **A bare fragment scrolls the page.** `#totals` scrolls the element with
+  `id="totals"` into view inside the frame; the page stays loaded and the app
+  does not move. A fragment that names no element by `id`, and no `<a name>`,
+  does nothing. `#` and `#top` scroll to the top of the page only when no
+  target matches: an element with `id="top"`, or an `<a name="top">`, wins
+  over the top of the page. Use this for a table of contents or a "back to
+  top" link. The page's own address does not change, so `hashchange` never
+  fires: a page that routes by hash handles its own clicks.
+- **A relative path** resolves against the folder of the page's own file and
+  opens that file in the app: from `{{knowledgeBaseDir}}/Reports/Q3.html`,
+  `../Knowledge/Alice.md#goal` opens `{{knowledgeBaseDir}}/Knowledge/Alice.md`
+  at its `goal` heading.
+- **`/workspace/<branch>/<path>`** opens that file on that branch.
+- **An external address** (`http:`, `https:`, `mailto:`) opens in a new tab.
+  A call from a script may also open `tel:`, `sms:`, `geo:` and a
+  protocol-relative `//host/path` address in a new tab, though a link
+  written in the markup cannot keep one.
+- **Anything else** (`javascript:`, `data:`, `file:`, an empty string) does
+  nothing.
+
+A click that a handler of the page has already cancelled with
+`event.preventDefault()` is left to that handler: the bridge neither scrolls
+nor opens anything for it.

package/agent-guide/introduction.md

@@ -0,0 +1,27 @@
+# Knowledge base
+
+This is a git-backed knowledge base. You are the primary agent responsible for
+maintaining it.
+
+> **This guide is served by the platform.** It is not a file in the
+> repository: `get_agent_guide` returns it, whole or one section at a time,
+> and so does `read_file` on `AGENTS.md` at the repository root — after the
+> knowledge base's own `AGENTS.md`, when it has one; `grep` searches it there
+> too. An `AGENTS.md` you find on disk is the organisation's own conventions
+> file, written by its people; follow it, and never write this text into it.
+> Deployment- or team-specific conventions belong there, or 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 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
+document for having the wrong shape. If a deployment layers a structured
+knowledge graph on top, it brings its own conventions, in sections of this
+guide of its own; what follows describes the platform underneath, which stores
+files and controls who may change them.

package/agent-guide/new-knowledge-base.md

@@ -0,0 +1,24 @@
+## A new knowledge base
+
+When `start_session` answers with a `firstRun` note, this knowledge base is
+new: `{{kbDirName}}/{{knowledgeBaseDir}}/` has no pages yet, the starter guide
+aside. The person has most likely just connected you, and you are the quickest way to
+fill it. The note stops coming once real pages exist.
+
+- **Offer once per conversation, in a sentence or two.** For example: "Your
+  Hexis knowledge base is connected and almost empty. Want me to draft a few
+  pages about your company — what you do, your customers, your products, your
+  glossary? Give me your website or tell me a bit, and I'll write them for you
+  to review."
+- **Never in the way.** If they asked for something else, do that first and
+  make the offer in one line at the end. If they decline, drop it.
+- **Draft from what they give you.** Read the website they name, or work from
+  what they tell you, and ask when something essential is missing rather than
+  inventing it. Good first pages: About the company, Customers, Products,
+  Glossary, How we work. Say where each fact came from (see Conventions).
+- **Write them with the normal tools** (`write_file`, `write_files`) as
+  markdown under `{{kbDirName}}/{{knowledgeBaseDir}}/`, one page per subject.
+  Leave the starter guide as it is. A write you are refused says whether you
+  may propose it as a change instead; propose it only when it says you may.
+- **Tell them where the pages are:** in the knowledge base in the app, where
+  they can read, edit or delete them, and every version stays in the history.

package/agent-guide/skills.md

@@ -0,0 +1,47 @@
+## 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 and MCP servers of the plugins that hold
+the skill, and the agent client's own tools beside them (`Bash`, `Read`,
+`Bash(git:*)` and the like, which the platform leaves to the client).
+`metadata.version` is semver; `list_skills` reports it, and
+`get_skill` with a `version` loads the skill as it was when it last declared
+that version (omit `version` for the latest). Any other `metadata` keys are
+the author's own notes — the catalog carries the file as it is and acts on
+none of them.
+
+A `SKILL.md` committed on the default branch is listed and loadable from the
+very next `list_skills` or `get_skill`, on the connection you already have:
+the released catalog is cached briefly and dropped the moment the default
+branch changes, so the next request reads the workspace again.
+See *A released tool or skill is live within ten seconds* under **Tool
+Manuals** for the one caveat (an MCP client that caches the prompt list it
+was given at connect time must re-list — the prompt-list-changed notification
+that tells it to arrives with the connection's next catalog check, which is
+within ten seconds on a connection in use and at its next use on an idle
+one).
+
+**How skills reach agents.** Through the MCP server (`list_skills`,
+`get_skill`), or as native plugins: every user can clone a git remote from
+the app's external-agent page that holds a plugin marketplace compiled from
+exactly the skills they may read — one plugin per plugin here, a
+`skills-and-knowledge` plugin for the rest plus this knowledge base's MCP
+server, and `hexis-all`, one plugin holding every skill they may read and
+the MCP server, for a single install.