@bevel-software/platform-core-backend 0.34.0 → 0.35.0

package/agent-guide/directory-structure.md

@@ -5,141 +5,93 @@
 ├── {{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
+├── roles.yaml            ← who holds which role
+├── groups.yaml           ← who is in which group
+└── access.md             ← the access rules at the root
 ```
 
-(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.)
+(The three root names are this deployment's own: a deployment may rename them
+in its setup screen, and this guide names the folders in effect.)
 
 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
+repository as the `{{kbDirName}}/` folder: a file in it is
+`{{kbDirName}}/{{knowledgeBaseDir}}/Foo.md`. Write the prefix where you can, as
+every tool reports paths with it; a path without it is placed under
+`{{kbDirName}}/`, so `{{knowledgeBaseDir}}/Foo.md` and the app's Copy path
+`/{{kbDirName}}/{{knowledgeBaseDir}}/Foo.md` name the same file. A leading
+`./` and doubled slashes are tidied away; `..`, any other `.` segment,
+backslashes and other absolute paths are refused.
+
+Only those three folders are structural, and `Data/`, `Agents/` and
+`Pipelines/` are reserved names on every deployment. Under
+`{{knowledgeBaseDir}}/`, subfolders, naming and whether a topic is one file or
+twenty are yours to decide. `{{skillsDir}}/` holds shared skills at any depth:
+the folder that holds a `SKILL.md` is the skill, and the folders above it are
+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>/plugin.json                  the manifest: 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
+{{pluginsDir}}/<Plugin>/mcp.json                     its MCP servers
+{{pluginsDir}}/<Plugin>/software.bevel.hexis/tools/  its `.tool` manuals
+{{pluginsDir}}/<Plugin>/access.md                    who can read and write the plugin
+{{pluginsDir}}/personal-<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.
+(`sales-team`): what every grant spells (`plugin/sales-team/read`) and what the
+app and the marketplace key on. `displayName` is what people see ("Sales
+Team"); without one, the `name` is shown. Rename a plugin from its page in the
+app, which rewrites every grant naming 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}}/`:
+**A plugin links shared skills rather than containing them.** Its manifest
+lists skill folders, or folders 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.
+A plugin's skills are the ones in its own `skills/` folder plus everything its
+links resolve to, and one skill can be linked by many plugins. Do not edit that
+list by hand: link from the plugin's page in the app, which also grants the
+plugin's members read on the skill (see `access-control`). A link without that
+grant is repaired automatically when someone who may write the plugin opens its
+page; one that cannot be repaired that way shows as needing setup. Who may read
+a skill is decided by the skill's own folders, never by the plugin: a plugin
+linking a skill someone cannot read simply does not show it to them.
+
+**MCP servers go in `mcp.json`, not in `.tool` files.** Each `mcpServers` key
+is the server's identity and the namespace its secrets bind to, so renaming a
+key unbinds every configured secret and sign-in. `mcp.json` says only where the
+server is (`type`, `url`, plain headers). Everything else the platform needs
+(headers carrying `${VAR}` secrets, `variables`, a `description`, or
+`local: true` for a server reachable only from a user's machine) goes in
+`plugin.json` under `extensions["software.bevel.hexis"].mcpServers[<name>]`.
+Secrets never go in `mcp.json`: plugins follow the
+[Agent Plugins](https://agent-plugins.org) specification (v1.0.0), which other
+clients load, and it has no place for credentials. A `type: "stdio"` server
+runs on the user's machine through the local `hexis-mcp` server, never on the
+hosted endpoint; it should exit when its standard input closes.
+
+**Make plugins with the tools, not by writing files.** A folder is a plugin
+when it has a `plugin.json` (or the read-only `plugin.bundle.json` format), and
+it is listed only when it also has an `access.md`. Writing files into a new
+name under `{{pluginsDir}}/` makes neither: on a protected branch it is
+refused, and on a draft it makes a folder that is not a plugin. Use:
+
+- `my_plugin`: the user's personal plugin, `{{pluginsDir}}/personal-<id>/`,
+  created on first use. Only its owner can read it, admins included, and it is
+  never listed as a plugin. Their own skills go in its `skills/` folder, each in
+  a folder with a `SKILL.md`. 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
+  (`parent`). The caller runs it; others join through the app or are granted
+  in its `access.md`.
+
+The app's **New plugin** button does the same. A skill moves from a personal
+plugin to a shared one by moving its folder. Symlinks are ignored anywhere
+under `{{pluginsDir}}/`: access is resolved by path, and a second path to the
+same file could disagree about who may read it.

package/agent-guide/drafts-and-change-requests.md

@@ -0,0 +1,92 @@
+## Drafts and change requests
+
+An agent drafts, proposes and syncs; people approve and apply, in the app.
+
+- **Start a draft** with `create_branch`: `name` is the new draft and `branch`
+  the branch it forks from, usually `{{defaultBranch}}`:
+  `create_branch({ body: { name: "paul-brandt/pricing-page", branch: "{{defaultBranch}}" } })`.
+  Name it `<you>/<topic>`, where `<you>` is the person's email before the
+  `@`, in lower case, with each run of other characters than letters and
+  digits as one `-`: `paul.brandt@` gives `paul-brandt/`. Only that prefix
+  makes the draft theirs, so they can delete it later. Ask for the email if
+  you do not know it. A draft is shared at once, and the file tools then take
+  it as `branch`. In the app, the person sees it through its change request
+  once you open one; until then the app shows them `{{defaultBranch}}`.
+- **Saving shares.** Every write is committed as the person and shared,
+  moments after the call returns; there is no separate push. `branch_status`
+  lists writes still landing. `share_current_branch` is only for sharing
+  again after a refused push, and `commit_change` only for a file a tool left
+  uncommitted (`unzip` does).
+- **Propose** with `open_change_request`
+  (`sourceBranch` = the draft, `targetBranch` = the protected branch, a
+  `title`), then give the person the request's `url`. It first brings the
+  latest target into the draft. The answer lists `approvals` (who must approve
+  each file) and `mergeBlockedReasons`. Reviewing, approving and merging happen
+  in the app; someone who may approve every file it changes may merge their own
+  request there.
+- **Edit** an open request with `update_change_request`: `description`
+  replaces the text whole, `appendDescription` adds a paragraph. Allowed for its
+  author and anyone who may merge it.
+- **Know where a draft stands** with `branch_status`: ahead or behind, whether
+  the shared draft moved (`behindRemote`), writes still landing, the protected
+  branch it was forked from, and `changedPaths`, the files a request would
+  carry. That list holds only files you may read; `withheldPaths` counts the
+  others (changed or still landing), so above zero the list is not the whole
+  request. Ask it before proposing.
+- **Sync** a draft with `update_branch` on the draft, `from` = the request's
+  target. It is allowed while the request is open. Without `from` it brings in
+  the draft's own shared state, for when it moved while your workspace held
+  commits (`behindRemote`). `merge_branch` (`source` = the target, `target` =
+  the draft) does the same without conflict handling.
+- **`merge_branch` into a protected branch** merges only what you could write
+  there directly, never a change to `roles.yaml`, and refuses a draft whose
+  open request targets that branch: ask the person to review it in the app.
+- **Read history** with `list_file_changes` (a file's commits: who, when,
+  subject), `read_file_at` (the file at a commit, given as the full sha, or on
+  another branch) and `compare_file` (the diff of a commit, or between two
+  branches). To put an earlier version back, read it with `read_file_at` and
+  write it with `write_file`.
+
+### Settling a conflict
+
+When `update_branch` answers `conflicts`, it has left the draft exactly as it
+was. For each conflicted path it carries the file at the merge base, on your
+side (`ours`) and on theirs (`theirs`), and the working copy with git's
+markers. A side is null when it has no file, or when `truncated` names it
+(too large, or not text): then read `ours` with `read_file`, `theirs` with
+`read_file_at` at `from` (the branch name), and the base with `read_file_at` at
+the answer's `mergeBase`. A side that is not text cannot be read that way:
+settle that file whole with `choose`. A conflicted file you may not read on one
+of the branches is only counted (`withheldConflicts`): ask a person who can read
+it to update the draft in the app.
+
+Decide each file (keep both sides' information unless one is clearly stale;
+`list_file_changes` says who changed what and why), then call `update_branch`
+again with the same `from` and `resolutions`, one per conflicted path: `content`,
+the resolved text, or `choose` (`ours`, `theirs`, `delete`). A resolution is a
+write on your draft: you must be able to read the path (or the folder it lands
+in). It merges, commits as you and shares. If sharing is refused, or the shared
+draft moved meanwhile, the answer is the saved-locally error: the merge is on
+your draft but not shared, and `branch_status` shows it ahead. Do not report it as shared; the next save
+or `share_current_branch` carries it. You never have a half-done merge to
+finish.
+
+### When a draft goes away
+
+- **After a merge** the draft is deleted on its own, unless another change
+  request is still open from or into it. Start a new draft for the next change.
+  A draft whose open request turns out to propose nothing (its changes are
+  already on the target) is removed the same way when that request is closed,
+  and so is the draft of a request deleted in the app.
+- **`delete_branch`** removes a draft for everyone. Only its author (the
+  `<you>/…` prefix above, or your own `suggestions/…` bundle) or an Admin may.
+  Preview with `dryRun: true`: it changes nothing and says whether the delete
+  would go through, how many commits are not on `{{defaultBranch}}`, and the
+  last commit. A draft holding such commits is refused unless you pass
+  `discardUnmerged: true`, only when the person wants that work gone. An open
+  request from or into it 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. A request you cannot see
+  is not named, even in a preview, so a delete can still be refused after a
+  clean preview. Hand the person the `lastCommit` it answers, so the draft can
+  be restored.

package/agent-guide/for-git-users.md

@@ -0,0 +1,47 @@
+## If you know Git
+
+The platform keeps its files in a Git repository, but the people you work with
+never touch Git, and neither do you: you have no git command. Use the
+platform's own words. What carries over, and what does not:
+
+| | Git and a code host | Here |
+|---|---|---|
+| Branches | Anyone branches anything | The default branch, `{{defaultBranch}}`, and any other protected branch are live. Work in progress goes on a draft branch named `<you>/<topic>` (see `drafts-and-change-requests`) |
+| Commits | `git commit`, then `git push` | Every save is committed and shared as the person, moments after the call returns. No separate push |
+| Pull requests | Opened and merged on the code host | A change request: you open it (`open_change_request`), a person reviews, approves and merges it in the app. No agent tool approves or merges one |
+| Who approves | Code owners, branch rules | The owners and writers of each file the request changes |
+| Permissions | The whole repository, read or write | Per folder and per file: `access.md` files say who may read, write, download or own. What you cannot read you cannot see or change, on any branch |
+| Layout | Free | Free under `{{knowledgeBaseDir}}/`; `{{skillsDir}}/` and `{{pluginsDir}}/` have a layout the platform reads |
+| Skills and tools | Files like any other | Live only once on `{{defaultBranch}}`; on a draft they wait for review |
+
+**On your draft you can do anything to what you can read.** Create, edit, move
+or delete any file you can read (a few platform files aside, see
+`working-with-files`). The draft is shared at once, so anyone who may read a
+file can open it there, but nothing is live until the draft is merged. Merging
+is where the owners of the files approve, so a delete on your draft deletes
+for everyone only once they accept it.
+
+**On a protected branch, write access is checked per file.** If you may write
+every file a change touches, it lands directly; ask the person first. If not,
+the write is refused, and the refusal says how to propose it instead.
+
+**An example.** A team keeps its specs in `{{knowledgeBaseDir}}/Products/Search/`,
+whose `access.md` is:
+
+```yaml
+---
+owner:
+  - role/Admin
+---
+read:
+  - everyone
+write:
+  - group/Search Team
+```
+
+The part above the second `---` says who may change this `access.md`; the
+part below it is the folder's rules. Everyone signed in can read the specs.
+Members of the group `Search Team` change them directly on `{{defaultBranch}}`.
+Anyone else drafts the change on a branch and opens a change request, which a
+member of `Search Team` approves. A folder inside it can narrow or widen this
+with an `access.md` of its own. The full rules are in `access-control`.

package/agent-guide/glossary.md

@@ -0,0 +1,36 @@
+## Words used here
+
+- **Knowledge base**: this organisation's documents, skills and tools in one
+  repository, with access set per folder.
+- **Default branch** (`{{defaultBranch}}`): what is live. Other protected
+  branches may exist; `list_branches` marks each with `isProtected`.
+- **Draft**: any branch that is not protected. Work waits there for review,
+  visible to whoever opens the draft.
+- **Change request**: the request to merge a draft into a protected branch.
+- **Plugin**: a package: a folder under `{{pluginsDir}}/` with a `plugin.json`.
+  It holds or links skills and declares tools, and its `access.md` says who
+  uses it. Each person also has a private one (`my_plugin`).
+- **MCP server**: a connection to another service, declared in a plugin's
+  `mcp.json`. Its tools appear in the tool list as `<server>_<tool>`.
+- **Tool**: one action an agent can call: one of the platform's own
+  (`read_file`), one from a plugin's MCP server, or one from a tool manual.
+- **Tool manual**: a `.tool` file in a plugin that describes HTTP tools, for a
+  service without an MCP server.
+- **Skill**: a folder with a `SKILL.md`: instructions an agent loads
+  (`get_skill`) when the skill's description fits the task.
+- **Secret**: a credential a tool needs, kept in the platform's Secrets Vault,
+  never in a file or in the chat. A *shared* (admin) secret is set once, by
+  someone who may edit the tool, for everyone who uses it. A *personal* (user)
+  secret is set by each person for themselves.
+- **Sign-in** (OAuth): a personal secret filled by signing in to the service
+  instead of pasting a key.
+- **Connect page**: where each person sets their personal secrets and signs in
+  to tools.
+- **Role**: a capability the platform defines, such as `Admin`, with the people
+  who hold it, in `roles.yaml`. Roles are pre-set: never create one.
+- **Group**: a named set of people, such as a team or a project, in
+  `groups.yaml` or synced from the organisation's directory. Groups are what
+  `access.md` files usually grant.
+- **`access.md`**: a folder's rules: who may `read`, `write`, `download` or be
+  `owner` of what is in it. A folder inherits from the folders above it, and
+  the nearest rule that names you decides.

package/agent-guide/how-agents-find-things.md

@@ -0,0 +1,49 @@
+## How your agent finds things
+
+Use this to know what you already have, and to explain it to the person you
+work with when they ask "does the agent read everything?".
+
+**When an agent connects, it has three things and no more:**
+
+1. **The server instructions**: a short platform note, the rules every file
+   tool shares, and this knowledge base's own description, which an admin
+   writes in `mcp-description.md` at the repository root (on the app's
+   external agent page). Some clients put them in the system prompt; a client
+   that drops them gets one line and the description's first paragraph at the
+   top of `start_session`, `grep`, `list_files` and `read_file` instead.
+2. **The tool list**: each tool's name, description and arguments.
+3. **The skills' names and descriptions**, as prompts and through
+   `list_skills`.
+
+**Everything else is fetched when a task needs it**: `grep` for the key terms,
+`list_files` to see a folder, `read_file` for a page, `get_skill` for a skill's
+instructions, and this guide one section at a time. No agent reads the whole
+knowledge base, and nothing makes it look: the instructions ask it to search
+before it answers about the organisation, and the rest is up to the text below.
+
+**What brings the right context is text the agent already has:**
+
+- **A skill's description** decides when the skill is loaded. Write it as
+  "Use when …", in the words people use for the task.
+- **Links between pages** (relative markdown links) lead one read to the next.
+  A page that links the pages explaining it is found together with them.
+- **`mcp-description.md`** says what this knowledge base holds, where, and
+  when to look. Its first paragraph is the part every client sees.
+
+**On the user's own machine**, the one text an agent always reads in a
+repository is that repository's `AGENTS.md` or `CLAUDE.md`. A few lines there
+make it look here first. Offer this, filled in:
+
+```markdown
+## Organisation knowledge
+Before you plan, design or write about <product or team>, search the
+<organisation> knowledge base (MCP server `<server name>`): grep for the key
+terms and read what matches. <What> lives in `{{knowledgeBaseDir}}/<Folder>/`.
+Prefer it over memory, and say when it is silent.
+```
+
+**This knowledge base's own conventions** go in an `AGENTS.md` at its root,
+written by its people: `read_file` on `AGENTS.md` returns that file first, then
+the start of this guide. A `CLAUDE.md` at the root is theirs too. Follow both, and never
+copy this guide into either: the platform serves it. Only the root file is read
+this way: an `AGENTS.md` deeper in a folder is an ordinary page.

package/agent-guide/html-views.md

@@ -3,7 +3,13 @@
 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.
+than by a markdown document. Plain HTML with inline CSS and JavaScript is
+enough; no skill or template is needed.
+
+**Data written into the page is governed by the page's access.** A tool call
+answers each viewer only what they may read; bytes in the file reach everyone
+who may read the page, so never copy in data from a source fewer people may
+read.
 
 ### The frame
 
@@ -15,6 +21,10 @@ than by a markdown document.
   `<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.
+- **The body is the page.** The app shows the sanitised contents of `<body>`
+  in a document of its own: `<style>` and inline `<script>` in `<head>` are
+  kept, moved to the start of the body; everything else in `<head>` and the
+  attributes on `<html>` and `<body>` are ignored.
 - **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
@@ -86,7 +96,7 @@ assume it is there:
 ```js
 const tools = window.bevel?.tools;
 if (tools) {
-  const file = await tools.callTool('read_file', { body: { branch: 'main', path: '{{knowledgeBaseDir}}/Foo.md' } });
+  const file = await tools.callTool('read_file', { body: { branch: '{{defaultBranch}}', path: '{{knowledgeBaseDir}}/Foo.md' } });
   // …show it
 } else {
   // …render without it
@@ -131,7 +141,7 @@ the app; the page never sees it.
 const input = document.getElementById('briefing');
 input.addEventListener('change', async () => {
   const answer = await window.bevel.tools.uploadFile(input.files[0], {
-    branch: 'main',
+    branch: '{{defaultBranch}}',
     destination: '{{knowledgeBaseDir}}/Campaigns/Easter',
   });
   // answer.files[0].path is where it landed
@@ -216,15 +226,10 @@ no build step and no framework:
 <head>
 <style>
   body { font: 14px system-ui, sans-serif; margin: 16px; }
-  header { display: flex; align-items: center; gap: 12px; min-height: 40px; }
-  #status { color: #555; }
+  .board { display: grid; grid-template-columns: repeat(3, 1fr); gap: 12px; }
+  .column { min-height: 320px; border: 1px solid #ddd; padding: 8px; }
+  .column li { min-height: 20px; padding: 6px; list-style: none; }
   #status.error { color: #b00020; }
-  .board { display: grid; grid-template-columns: repeat(3, minmax(0, 1fr)); gap: 12px; }
-  .column { min-height: 320px; border: 1px solid #ddd; border-radius: 6px; padding: 8px; }
-  .column ul { list-style: none; margin: 0; padding: 0; }
-  .column li { min-height: 20px; padding: 6px; margin-bottom: 6px; border-radius: 4px; background: #f4f4f4; }
-  .column li.placeholder { background: #ececec; }
-  .count { color: #777; font-weight: normal; }
 </style>
 </head>
 <body>

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

@@ -1,21 +1,22 @@
 ## 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.
+new: `{{kbDirName}}/{{knowledgeBaseDir}}/` holds nothing but its starter guide
+and any starter pages nobody has changed yet. 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."
+  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).
+  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