@awesomate/hosting-mcp 0.74.0 → 0.85.0

package/skill/awesomate-onebrain/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: awesomate-onebrain
-description: Use the business's 1Brain (Business Blueprint's home for its systems) from Claude Code, its automations and its AI agents. Use when the user mentions 1Brain, Business Blueprint, "our systems", SOPs, policies, procedures, "what's our procedure for", "how do we do X here", "write this up as an SOP", "connect 1Brain", the 1Brain node in n8n, an agent that answers from our procedures, training courses, quizzes, acknowledgements or read markers. Covers connecting 1Brain in the hub, the three ways to use it and when to pick each, and the safety rules. Companion to awesomate-n8n (workflows and agents with the 1Brain node) and awesomate-hosting (the business map). Same connection, same PAT.
+description: Use the business's 1Brain (Business Blueprint's home for its systems) from Claude Code, its automations and its AI agents. Use when the user mentions 1Brain, Business Blueprint, "our systems", SOPs, policies, procedures, "what's our procedure for", "what are the procedures for the X role", "how do we do X here", "write this up as an SOP", "connect 1Brain", 1Brain Departments on the business map, the 1Brain node in n8n, an agent that answers from our procedures, training courses, quizzes, acknowledgements or read markers, onboarding a new starter, or a course for a role. Covers connecting 1Brain in the hub, looking procedures up with awesomate_onebrain, 1Brain on the business map, the other ways to use it and when to pick each, and the safety rules. Companion to awesomate-n8n (workflows and agents with the 1Brain node) and awesomate-hosting (the business map). Same connection, same PAT.
 ---
 
 # 1Brain: the business's systems, from Claude Code
@@ -11,18 +11,18 @@ Most people asking about it are business owners and their teams, not
 developers. Use plain words: "your procedures in 1Brain", "your systems",
 never "MCP", "OAuth" or "JSON-RPC" unless they use them first.
 
-**Routing rule:** what 1Brain holds comes from 1Brain itself (its own
-connector, or the 1Brain node in a workflow). What Awesomate set up (the
-connection, the credential, the feature) comes from the Awesomate tools.
-Never answer "what's our procedure for X" from memory or general knowledge.
+**Routing rule:** what 1Brain holds comes from 1Brain itself, read live:
+`awesomate_onebrain` in a chat, the 1Brain node in a workflow, or 1Brain's
+own connector for the rarer writes (2d). Awesomate never keeps a copy. Never
+answer "what's our procedure for X" from memory or general knowledge.
 
 ## How 1Brain is organised
 
 | 1Brain word | What it is | Watch out for |
 |---|---|---|
 | Account (1Brain's code calls it organization) | One business's 1Brain | A person can belong to several. Always name the one you mean |
-| Category (some accounts call it "Organization") | A top-level group of departments | Two categories can share a name: pick by id |
-| Department | A part of the business, such as Marketing or Finance | Matches a division on the business map |
+| Category (some accounts call it "Organization") | A business: a top-level group of 1Brain Departments | Two categories can share a name: pick by id. On the map, each business is one category |
+| Department | A part of the business, such as Marketing or Finance | Say **"1Brain Department"** where it could be unclear: the business map calls its own top level departments too. Each 1Brain Department sits in one department of the map (`mapDepartmentNo`) |
 | Folder | A small topical group of pages in a department | Titles are unique within a department |
 | Page (System, SOP, policy) | One procedure or policy | Has a status: draft, published or for review |
 
@@ -61,44 +61,78 @@ then **Connect 1Brain**.
   its permission, so the hub links each 1Brain account's own MCP settings page
   where they remove it.
 
-You cannot connect 1Brain for them, and no Awesomate tool reads or changes the
-connection. Never ask for a 1Brain token or password in chat.
+You cannot connect 1Brain for them. `awesomate_onebrain` `status` says whether
+the person this key belongs to is connected, which 1Brain accounts they
+allowed and whether their credential is in their automations; nothing changes
+the connection from Claude. Never ask for a 1Brain token or password in chat.
 
 **Today 1Brain's connection point runs only on 1Brain's development server
 (`dev.1brain.io`).** `1brain.io` and `staging.1brain.io` do not offer it yet.
 Until they do, a connection reaches 1Brain's development server, not the
 1Brain the team signs in to every day. Say so if their pages "are missing".
 
-## 2. Three ways to use 1Brain, and which to pick
+## 2. The ways to use 1Brain, and which to pick
 
 | They want | Use |
 |---|---|
-| Claude (Claude Code, Claude.ai) to look things up or write in 1Brain, in a chat | **1Brain's own Claude connector** (2a) |
-| A workflow step that reads or writes 1Brain: a scheduled report, a form or email turned into an SOP draft, a sync | **The 1Brain node** with the hub-made "1Brain - <person>" credential (2b) |
-| An AI agent in their automations that answers from their procedures | **The 1Brain node as an agent tool** (`CUSTOM.oneBrainTool`: Page Search, then Page Get), on the credential of the person the agent answers to (2b) |
-| An AI agent that needs every 1Brain action, with no setup in the node | **MCP Client Tool** with n8n's own MCP OAuth2 credential (2c) |
+| Claude to find a procedure, read a page, list a role's systems, place 1Brain Departments on the map, or save a draft procedure | **`awesomate_onebrain`** (2a) |
+| A workflow step that reads or writes 1Brain: a scheduled report, a form or email turned into an SOP draft, a sync | **The 1Brain node** with the hub-made "1Brain - <person>" credential (2c) |
+| An AI agent in their automations that answers from their procedures | **The 1Brain node as an agent tool** (`CUSTOM.oneBrainTool`: Page Search, then Page Get), on the credential of the person the agent answers to (2c) |
+| A 1Brain course for a role or for everyone joining, and starting someone's onboarding | **`awesomate_onebrain`** onboarding actions (5) |
+| Claude doing what `awesomate_onebrain` does not: writing quizzes, acknowledgements, tailoring, publishing | **1Brain's own Claude connector** (2d) |
+| An AI agent that needs every 1Brain action, with no setup in the node | **MCP Client Tool** with n8n's own MCP OAuth2 credential (2e) |
 | Something done as the business rather than as a person | **Not possible yet.** Every 1Brain connection is a person |
 
-### 2a. Claude working directly in 1Brain
-
-1Brain has its own connector for Claude at `https://dev.1brain.io/mcp`
-(the development server, see above). The person adds it themselves:
-
-- Claude Code: `claude mcp add --transport http onebrain https://dev.1brain.io/mcp`,
-  then run `/mcp` in Claude Code and sign in to 1Brain.
-- Claude.ai: Settings, Connectors, Add custom connector, with that address.
-
-It signs in as them and asks which 1Brain accounts to allow. The Awesomate MCP
-has no 1Brain tool of its own: if 1Brain's tools are not in this session,
-never pretend to search 1Brain. Offer to set up the connector, or build a
-workflow that does it.
-
-When 1Brain's tools are in the session: confirm which account first (1Brain's
-own instructions ask this too), pass it on every call, search, then read the
-page before answering. 1Brain search returns titles only, and ranks loosely,
-so read the top few pages, not just the first.
-
-### 2b. Workflows and agents: the 1Brain node
+### 2a. Claude looking things up: `awesomate_onebrain`
+
+It reads 1Brain live through the 1Brain login of the person this key belongs
+to, so it sees exactly what they can see. Start with `status`: not connected
+means sending them to Settings, Integrations, 1Brain, and nothing else.
+`business.linked: null` means the map could not be read just now: try again,
+never treat it as unlinked.
+
+- **"What are the procedures for the front desk role?"** `awesomate_business_map`
+  `roles` for the role's slug, then `systems_for_role` {slug} (each system with its
+  link; a folder comes with its pages), then `fetch` {id} the pages that
+  answer the question. End with the link to every page used.
+- **"How do we do X?"** `search` {query}, then `fetch` the top few: search
+  returns titles only and ranks loosely, so never answer from a title.
+- **Nothing on the role yet?** Say so, then search, and offer to add what fits
+  with `link_role` {slug, ids} once they agree.
+- **A new procedure:** write it from their own words, show it, then
+  `propose_draft` {departmentId, title, contents}. It is always a draft in
+  1Brain; a person publishes it there. If 1Brain asks for a business
+  description or which template to follow, ask them exactly that and call
+  again with their answer.
+- **More than one 1Brain account and no category linked:** the tool asks for
+  `accountId`; `status` lists the accounts. Ask the user which.
+
+### 2b. 1Brain on the business map
+
+- **A category is a business.** The business is linked to one 1Brain
+  category; until it is, `departments` answers `not_linked`. `categories` lists
+  each 1Brain account the person can see with its categories; ask the owner
+  which one is this business (two can share a name, so pick by id), then link
+  it with `map` {accountId, categoryId}.
+- **1Brain Departments sit in the map's departments.** `departments` lists each one with
+  its map department (`mapDepartmentNo`, 1 to 7) and sub-department (`subDepartmentNo`), suggested
+  from its name until someone saves the map. Place one with `map` {projectId, mapDepartmentNo,
+  subDepartmentNo?}; `mapDepartmentNo: null` takes
+  it off the map. From Claude, a change to the map is a suggestion the owner
+  accepts from Tasks: say it is waiting for them, never that it is done.
+- **Each role keeps its 1Brain systems.** `link_role` adds pages or folders (up
+  to 10 at a time; a folder brings everything in it) and tags them
+  `job:<slug>` in 1Brain so people see it there too. The answer is per id:
+  when 1Brain refuses the tag (the person cannot edit that page), the system
+  stays on the role and the reason comes back: relay it. When 1Brain stops
+  partway (`stopped`: the rate limit, access switched off), what was added
+  stays added; ask again later with `retryIds` only, never the whole list. This list is knowledge, what someone in
+  the role must know. It grants nobody access to anything.
+- **Taking one off** is done on the map page in the hub. 1Brain cannot remove
+  tags over its connection yet, so the tag stays in 1Brain until someone
+  removes it there.
+
+### 2c. Workflows and agents: the 1Brain node
 
 The node is in the account's n8n as `CUSTOM.oneBrain` (and `CUSTOM.oneBrainTool`
 for AI agents), on the hub-made credential. Load the **awesomate-n8n** skill and
@@ -106,7 +140,22 @@ read its [references/onebrain.md](../awesomate-n8n/references/onebrain.md) for
 the operations, the parameters and tested patterns. The node is only on some
 instances so far: check before designing around it (that reference says how).
 
-### 2c. The no-code agent route
+### 2d. 1Brain's own Claude connector
+
+For what `awesomate_onebrain` does not do (writing quizzes and acknowledgements,
+sharing a course, tailoring, publishing), 1Brain has its own connector for Claude at
+`https://dev.1brain.io/mcp` (the development server, see above). The person
+adds it themselves:
+
+- Claude Code: `claude mcp add --transport http onebrain https://dev.1brain.io/mcp`,
+  then run `/mcp` in Claude Code and sign in to 1Brain.
+- Claude.ai: Settings, Connectors, Add custom connector, with that address.
+
+It signs in as them and asks which 1Brain accounts to allow. Confirm which
+account first (1Brain's own instructions ask this too) and pass it on every
+call. Never pretend to use a 1Brain tool that is not in the session.
+
+### 2e. The no-code agent route
 
 n8n's own **MCP Client Tool** on an AI Agent, with an **MCP OAuth2** credential
 whose server address is `https://dev.1brain.io/mcp`. The person signs in from
@@ -114,7 +163,7 @@ their n8n. It gives the agent every 1Brain tool with no setup, but each
 reconnect registers a new 1Brain connection, and the agent can do anything the
 person can, so give it strict instructions. n8n's own code supports this
 route, but it has not been run end to end yet: say it is untested and test it
-with them before anyone relies on it. Prefer 2b when the agent only needs to
+with them before anyone relies on it. Prefer 2c when the agent only needs to
 read procedures.
 
 ## 3. Rules (every route)
@@ -162,13 +211,40 @@ read procedures.
 5. Publishing is a separate yes. Policies go to review rather than straight
    to published.
 
-## 5. Training: courses, quizzes, acknowledgements
-
-Owners and admins can list and read courses, quizzes and who passed them,
-and acknowledgements (read markers: "I have read and understood this page")
-and who completed them; members can read courses. Creating a course
-publishes it, so confirm first. A quiz or acknowledgement is added to one
-page; confirm by name before deleting one.
+## 5. Training and onboarding
+
+Onboarding is about a person and the roles they are about to hold. Each role
+on the business map can have a **1Brain course**, built from that role's 1Brain
+systems; the business has one **starter course** for anyone joining (culture,
+orientation, policies), built from one 1Brain Department or folder. Courses
+live in 1Brain; the hub keeps their ids, never their content. Read
+`features.onebrain_onboarding` in `awesomate_get_context` first: it can be off
+while 1Brain is on.
+
+- **`onboarding`**: each role's course (and whether its 1Brain systems changed
+  since it was built), the starter course, who checks training, and each
+  person's plan with quizzes passed and acknowledgements done. Owners only.
+- **`build_course`** {slug} or {starter: true, projectId or folder}: builds a
+  **published** course in 1Brain on the 1Brain login of the person this key
+  belongs to, who must be a 1Brain owner or admin. Say so and confirm before
+  building. When the answer is `needsConfirm`, 1Brain found systems with no
+  quiz: tell the user which, and that those can only be checked by an
+  acknowledgement, or not at all. Build anyway (`confirmMissingQuizzes: true`)
+  only on their yes; otherwise offer to write quizzes with 1Brain's own
+  connector (2d). Rebuilding makes a new course; the old one stays in 1Brain.
+- **`start_onboarding`** {email, starter?, roles?: [slug or {slug, intent}],
+  finishBy?} (`hats` is the old name for `roles`): gives the person a Task per course, linking their own onboarding
+  page. Nothing is written in 1Brain: the course must still be shared with
+  them there, and someone not yet in the business's 1Brain must be added there.
+- **Readiness grants nothing.** Each morning the hub reads quizzes and
+  acknowledgements on one Owner's 1Brain (chosen in the hub, re-checked every
+  run). When a person has passed every quiz and done every acknowledgement on
+  a course, the hub gives their future manager a Task asking whether to hand
+  the role over; the map's own rules decide. Never change the map, or anyone's
+  access, because someone is ready, and never show one person's results to
+  anyone but the Owners and that person.
+- Writing quizzes and acknowledgements, and sharing a course with a learner,
+  are 1Brain's own connector's work (2d), owners and admins only.
 
 ## 6. Known gaps (say so plainly)
 
@@ -176,9 +252,12 @@ page; confirm by name before deleting one.
   way to list them. Tags can be added, not read back or removed.
 - **Search cannot filter by tag** (or by department or folder). In a workflow,
   use the node's Limit to Department or Limit to Folder instead.
-- So a hat's procedures linked by its 1Brain tag on the business map
-  (`job:<slug>`, from `awesomate_business_map`) cannot be fetched by tag yet:
-  find them by department, folder or search.
+- So the hub keeps each role's list of 1Brain systems itself
+  (`awesomate_onebrain` `systems_for_role`), and also writes the `job:<slug>`
+  tag. A tag someone added by hand in 1Brain is not on the role's list until it
+  is added with `link_role`.
+- Tags cannot be removed over the connection, so taking a system off a role
+  leaves its tag in 1Brain.
 - No deleting or moving pages, folders, departments or categories through any
   route. That is done in 1Brain itself.
 - Nothing can run as the business itself: every connection is a person.