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

package/agent-guide/onboarding.md

@@ -0,0 +1,111 @@
+## Onboarding someone new
+
+Use this when someone is new here or asks to be onboarded ("onboard me", "get
+started", "what is this", "what can you do for me"). Give them one picture, let
+them choose what to do, and explain each idea at the moment they meet it, while
+they do something real. Write short messages in plain words, in their language,
+one question at a time.
+
+### 1. Look around first, and say nothing yet
+
+The welcome uses real examples, so find them first. About eight calls; one
+search and one read are enough for the examples. Every read below takes
+`branch: "{{defaultBranch}}"`, the branch people read.
+
+- `read_file` on `{{kbDirName}}/mcp-description.md`: what this knowledge base
+  holds. If it is still the commented-out template, it says nothing about this
+  organisation; do not quote it.
+- `list_files` on `{{kbDirName}}` and `{{kbDirName}}/{{knowledgeBaseDir}}`: the
+  areas that exist.
+- `list_skills`: what people here can use.
+- If you know who the person is (most clients say who is signed in): `grep` for
+  their name and email to find pages they own or that name them, and their
+  drafts in `list_branches` (named `<you>/…`, see `drafts-and-change-requests`);
+  `branch_status` shows what a draft changes.
+
+### 2. Welcome, and offer three things
+
+> Hi <first name>, welcome to <organisation>'s knowledge base.
+>
+> It holds <organisation>'s shared knowledge, and I, your agent, can read it
+> and work in it. You can:
+>
+> 1. **Ask**: get answers from <organisation>'s knowledge, each with the page
+>    it came from. *For example: <a real question one of their areas answers>*
+> 2. **Contribute**: add or change pages. Where a page isn't yours to change,
+>    the people who look after it approve your change before it goes live.
+>    *For example: <something waiting on them, or a page they could improve>*
+> 3. **Automate**: use skills, ready-made instructions I follow, and connect
+>    tools. *For example: <a real skill from `list_skills`, in one line>*
+>
+> Which one are you interested in?
+
+Every name in an example must come from a tool result in this conversation;
+never invent one. On a read-only connection leave Contribute out: offer Ask and
+connecting tools, and say in one line that this connection cannot change pages. With nothing about the person, use the organisation's
+top-level areas and its first useful skill; without their name, say "Hi,
+welcome". When `list_skills` names no released skill, leave the Automate
+example out and say that tools can still be connected. When the knowledge
+base has no area or page of the organisation's own yet, leave the Ask example
+out and say it is still empty, so Contribute is where to start. Keep it under
+about 150 words. If their first message also asks a question, answer it in two
+or three lines above the welcome. Then stop and wait. A reply that names or
+asks for one of the three is that option, and asking to connect a tool is
+Automate; any other question is option 1.
+
+### 3. Do the option they chose
+
+Explain an idea only when they meet it, in a sentence or two, and point to the
+section that has the rest.
+
+**Ask.** Search, read what matches, and answer in a few lines, naming the page
+each fact came from by its path. If the knowledge base has nothing on it, say
+so and do not fill the gap from memory.
+The first time, say how this works: you search when asked rather than reading
+everything up front (`how-agents-find-things`).
+
+**Contribute.** Agree the change, show it as old and new text, and write only
+after a yes. It goes on a draft (`drafts-and-change-requests`):
+
+- Their existing draft for this work, if it has one. If its change request goes
+  into another draft rather than `{{defaultBranch}}`, approving it makes nothing
+  live yet: say so.
+- If what is already on that draft changes more than they likely meant (who
+  owns a page, who may edit it), point it out and ask.
+- Otherwise a new `<you>/<topic>` draft. Ask before writing to
+  `{{defaultBranch}}`, even when you may.
+
+Ask before opening a change request, then give its link: that is where they see
+the change in the app. Say once that the people who look after those pages
+(their owners and writers) approve it in the app with **Approve**, then **Apply
+changes**, and that you cannot do that for them. If a write is refused, follow
+the refusal: offer a draft and a change request only when it says you may
+propose the change; otherwise say that this change cannot be proposed from here.
+Name who approves (`access-control`) only for a change that may be proposed. A
+connection that may not write at all (a read-only connection: its write tools
+refuse and say so) gets Ask, and connecting tools, with a line saying why
+Contribute is not on offer.
+
+**Automate.** Name two or three skills in one line each, pick one with them,
+load it with `get_skill` and run it together. With one released skill, offer
+that one; with none, say so and offer Ask or Contribute instead, or connecting
+a tool (`tools`). Before a step that creates
+something outside the knowledge base, show it and ask. If the skill needs a
+tool, `tools` says what each person sets up and when it starts working. A
+secret pasted into the chat is never repeated or used: say to enter it on the
+Connect page instead and to replace the pasted one. To build a skill, see
+`skills`.
+
+### 4. Close
+
+One line of what happened and what now waits on whom:
+
+> ✓ Connected · ✓ <what they did> · ◻ <what waits on someone, by name>
+
+Offer the other two options in one line. If they use an agent with a local
+project (Claude Code, Cursor), ask once whether they want a line for its
+`AGENTS.md` or `CLAUDE.md`, the only text that agent always reads, and give it
+only on a yes:
+
+> Before answering about <organisation>'s <areas>, search the knowledge-base
+> connector and cite the page used.

package/agent-guide/skills.md

@@ -1,55 +1,80 @@
 ## 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:
+skills live under `{{skillsDir}}/`, organised by ownership; a skill that
+belongs to one plugin alone may live in that plugin's `skills/` folder. Skill
+names are unique across the catalog. The frontmatter names the skill, says
+when to use it, and may list tools and a version:
 
 ```yaml
 ---
 name: weekly-newsletter
-description: Drafts the Friday newsletter for review.
+description: "Use when someone asks for the Friday newsletter: drafts it 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.
-
-Before offering to change a skill, read its `canWrite`: `list_skills` judges
-the `SKILL.md`; `get_skill` judges every file of the skill unless `file` is
-passed, in which case it judges only that file — a bundled file's `true` is
-not the skill's; both by the default branch's rules whichever branch you
-read. `canWrite: false` means use a branch and a change request; do not
-offer a direct write (see *Direct writes vs change requests* under **Access
-control**).
-
-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.
+- **The frontmatter is YAML.** Quote a value that contains `: ` or starts
+  with a special character, as above, or the description comes out empty and
+  nobody finds the skill. Read it back with `get_skill` after writing.
+- **`description` is how the skill is found**: agents load a skill when its
+  description fits the task. Say when to use it, in the words people use.
+- **`allowed-tools`** names the tools the skill uses: any of the platform's
+  tools, a plugin's (as `<server>_<tool>`), and the client's own (`Bash`,
+  `Read`, `Bash(git:*)`). The platform warns about a name it does not know,
+  and enforces nothing.
+- **`metadata.version`** (or a top-level `version`) is reported by
+  `list_skills`; `get_skill` with `version` loads the skill as it was when it
+  last declared that version. Other `metadata` keys are the author's notes.
+
+The body is the instructions, in plain markdown.
+
+**A skill on a draft is not live.** The app's skills page, the prompts and
+`list_skills` without `branch` show only the released catalog, read from
+`{{defaultBranch}}`, so a skill on a draft "doesn't exist" there until it is
+merged. To try it, pass the draft: `list_skills({ body: { branch: "<draft>" } })`,
+then `get_skill({ body: { name: "weekly-newsletter", branch: "<draft>" } })`.
+A skill that differs from the released one comes back with `unmerged: true`,
+and its body opens with a line saying it is not approved. Once merged, it is
+in the next `list_skills` or `get_skill`; a client that cached the prompt list
+when it connected must reconnect to show it as a prompt.
+
+Before offering to change a skill, check its `canWrite` (see `access-control`).
+
+**How skills reach agents.** Through this server (prompts, `list_skills`,
+`get_skill`), or as native plugins: each person can install a plugin
+marketplace from the app's external agent page, compiled from exactly the
+skills they may read.
+
+### A skill that needs tools checks them first
+
+A skill that calls another service fails for anyone who has not signed in, or
+before the tool is merged. Make its first step a check, and stop with a plain
+instruction rather than a failed call:
+
+```markdown
+## Before you start
+Call `list_tool_setup`. Find the Jira tool. If a variable with `scope: user`
+shows `userConfigured: false` (or `authorized: false` for a sign-in), stop and
+say: "Open the Connect page in <app> and sign in to Jira, then ask me again."
+If the tool is missing altogether, say it is not available to them yet and who
+to ask.
+```
+
+### A guided skill for people who are not technical
+
+When a skill is for someone who is not an engineer, such as turning an idea
+into a ticket, write it to lead them:
+
+- **One question per message**, the most important first. Never a list of
+  five.
+- **Propose, then ask them to confirm.** "I would call it 'Search: filter by
+  date'. Is that right?" is easier to answer than "What is the title?".
+- **A checklist for "specified enough"** in the skill (who it is for, what
+  should happen, how we know it works), and stop asking once it is met.
+- **Plain words.** No platform terms (branch, change request, frontmatter,
+  tool names); show the result in their language before you create anything.
+- **Check its tools first** (above), so the conversation does not end in an
+  error after ten questions.

package/agent-guide/start-here.md

@@ -0,0 +1,66 @@
+## Start here
+
+You are connected to this organisation's knowledge base: its documents, and
+the skills and tools its teams have approved, with access set per folder. To
+the people you work with it is not a Git repository: say "knowledge base",
+"draft" and "change request", and do not explain it as "a Git repo". If they
+ask how it compares, see `for-git-users`.
+
+**Read this once per conversation.** Then fetch only the section a task needs,
+`get_agent_guide({ body: { section: "<id>" } })`, and do not reload the whole
+guide. When you start a sub-agent, pass it the rules below and the one section
+its task needs.
+
+### Before your first call
+
+- **Every file tool takes `branch`.** `{{defaultBranch}}` is the default
+  branch: what is live for everyone. Work in progress lives on a draft branch.
+  For example:
+  `read_file({ body: { branch: "{{defaultBranch}}", path: "{{kbDirName}}/{{knowledgeBaseDir}}/Overview.md" } })`.
+- **Copy each tool's `Call:` line.** It is generated from the tool's own
+  schema and shows the shape that tool takes, with every required argument;
+  optional ones are in the schema. A call with a missing or unknown argument
+  is refused, and the refusal shows the tool's interface.
+- **Pass `sessionId` only where a tool lists it.** Over MCP, call
+  `start_session` once and pass its id to the tools whose arguments include
+  `sessionId`. Other tools refuse it.
+- **`grep` takes RE2-style regular expressions** (ripgrep): no look-around
+  and no backreferences.
+- **Paths sit under `{{kbDirName}}/`**, as in
+  `{{kbDirName}}/{{knowledgeBaseDir}}/Overview.md`. A path without that prefix
+  is placed under it.
+
+### What is live, and what is only on a draft
+
+Work on a draft is visible to you, and to anyone who opens that draft in the
+app: its change request, once you open one, shows every changed file.
+**Skills and tools go live only once they are on `{{defaultBranch}}`**,
+merged through a change request or written there directly by someone allowed
+to. Until then the app's skills page, `list_skills` without `branch` and the
+tool list do not show them, and "doesn't exist" means "not merged yet". To see
+a skill on a draft, pass the draft as `branch` to `list_skills` or
+`get_skill`.
+
+### Which section answers what
+
+| Question | Section |
+|---|---|
+| Someone is new here, asks what this is or what you can do for them, or asks to be onboarded | `onboarding` |
+| What does my agent see when it connects, and how does it find the rest? | `how-agents-find-things` |
+| How is this like Git, and how is it not? Why can't I delete this? | `for-git-users` |
+| What is a plugin, a skill, a tool, a secret, a role, a group? | `glossary` |
+| What do the platform's folders hold? | `directory-structure` |
+| Where does a new file go? How do I lay out a team's first project? | `where-a-new-file-goes` |
+| What may the file tools do: content kinds, write modes, moves, deletes? | `working-with-files` |
+| Who may read or change what: roles, groups, `access.md`? | `access-control` |
+| How do I propose, sync or delete a draft, or settle a conflict? | `drafts-and-change-requests` |
+| How do I write a skill, or one for people who are not technical? | `skills` |
+| When can I use a tool, and what does it need set up? | `tools` |
+| How do I add a tool: `.tool` files, `mcp.json`, sign-ins? | `tool-manuals` |
+| How do I build an interactive HTML page? | `html-views` |
+| How are pages named, linked and sourced? | `conventions` |
+| The knowledge base is empty: what now? | `new-knowledge-base` |
+
+A deployment may add sections of its own: `sections` in this answer lists
+every one. `get_agent_guide({ body: { section: "all" } })` returns the whole
+guide.