Update to Kowalah

{
  "description": "Connect the Kowalah MCP server and work out what the signed-in account can see. Use when the Kowalah plugin has just been installed, when Kowalah tools return nothing or error, when the user asks how to connect Kowalah, or when someone wants to start mapping an AI operating model from scratch.",
  "included_files": [],
  "name": "kowalah-setup",
  "skill_md_contents": "---\nname: kowalah-setup\ndescription: Connect the Kowalah MCP server and work out what the signed-in account can see. Use when the Kowalah plugin has just been installed, when Kowalah tools return nothing or error, when the user asks how to connect Kowalah, or when someone wants to start mapping an AI operating model from scratch.\n---\n\n# Setting up the Kowalah connection\n\nThe Kowalah plugin talks to `https://mcp.kowalah.com/api/mcp` over authenticated HTTP.\nEvery tool is scoped to the organisations the signed-in user belongs to — there is no\nanonymous or read-only mode.\n\nYou do not need an existing Kowalah engagement. Signing in creates an account, and if\nnobody from the user's company is here yet it creates an organisation for them too, with\nthem as its admin and an empty operating model to fill.\n\n## Connecting\n\n1. **Installing the plugin doesn't connect it.** The plugin bundles the `kowalah` MCP\n   server, but the user still has to connect it. In Claude: open the plugin from\n   **Customize → Plugins** and go to its **Connectors** tab.\n   - **Not connected** — connect it there.\n   - **Not added** — add it there, then connect. On a Claude Team or Enterprise plan a\n     workspace owner usually has to add it for the organisation first, under\n     **Organization settings → Connectors** with the URL `https://mcp.kowalah.com/api/mcp`.\n     If the user can't add it, that's who to ask.\n\n   In Microsoft 365 Copilot: in Cowork, turn the Kowalah plugin on under\n   **Customize → Plugins**, then sign in when the Kowalah connector asks. In Copilot Chat,\n   add the Kowalah agent, and it asks you to sign in the first time it uses Kowalah. If\n   Kowalah isn't listed in either, the organisation's Microsoft 365 admin has to make it\n   available first.\n\n   In another assistant, connect the Kowalah app or connector the way that assistant asks.\n2. **Sign in, or sign up — with a work email address.** An email Kowalah doesn't already\n   know is fine; an account is created automatically and you do not need to be invited\n   first. The email domain decides where you land, so a personal address (gmail, outlook)\n   will not reach a company's organisation even if one exists.\n3. Approve the connection.\n\n## Then work out which organisation they landed in\n\nEvery Kowalah account belongs to an organisation — there are no personal accounts. On\nsign-up the user is placed in one of two, and the difference changes what you should do\nnext:\n\n- **Their company's organisation**, if its email domain is already registered with\n  Kowalah. They join it, usually as a `member`.\n- **A new organisation created for them**, if it isn't. They are its sole admin, and it\n  contains nothing but an automatically-created root unit.\n\nBoth authenticate identically and both are legitimate. Establish which one before doing\nanything else, because the same empty result means opposite things in each.\n\nRun **`kowalah_get_update`** with no query. A working connection returns `kind: \"home\"`\nwith the user's identity, their `organizations` (each with `id`, `name` and `role`), and a\nrole-appropriate rollup.\n\n### Read three things off it\n\n**Which organisations they belong to.** If more than one, several tools need an explicit\n`organization_id` — ask which one each time rather than guessing.\n\n**Their role.** This gates `kowalah_get_update` only: `admin` and `core_team` see\neverything in the organisation, `member` sees their own opportunities plus items they are a\nstakeholder on. It does **not** gate the operating model, vision map, accelerator library\nor process detail — anyone in the organisation can read all of those. Writes are\npermission-checked separately, and where a user cannot edit something the tools route them\nto a proposal rather than refusing. An admin is a cross-cutting editor in their own\norganisation, so a sole admin in a new organisation can author the whole model.\n\n**Which of the two organisations they landed in.** Check this by *shape*, never by name.\n\n**The organisation's name proves nothing.** A newly-created organisation is *named* from\nthe signer-up's email domain, so a work-email sign-up produces one named after their own\nemployer — indistinguishable at a glance from the company's real organisation, which may\nexist separately under a near-identical name. Only a personal email address produces the\nobvious *\"Sam's organization\"* giveaway.\n\nThe reliable tell that this is a **new, empty organisation** is all four together:\n\n- exactly **one** organisation, and `role` is `admin`\n- `kowalah_get_operating_model` returns **one unit and zero processes** — note this is\n  *not* `kind: \"empty\"`, because a root unit is created automatically, so the model looks\n  present but is bare\n- `kowalah_get_vision` returns `kind: \"empty\"`\n- `kowalah_get_update` shows no projects, deliverables or expert requests despite the\n  `admin` role that would reveal them\n\n## What to do about it\n\nSay plainly which of the two they are in, then ask what they expected, because that is\nwhat decides the next step.\n\n### They are in a new organisation of their own, and that is fine\n\nThis is the normal starting point for someone with no Kowalah engagement: an AI Operations\nLead, an internal forward deployed engineer, or anyone who owns AI delivery inside a\nbusiness and has nothing mapped yet. They are the admin, the model is empty, and they can\nauthor all of it.\n\nOffer to start. The first useful move is one org unit and its real processes, not an\nattempt at the whole company:\n\n- `kowalah_save_org_unit` to add the units under the root\n- `kowalah_save_process` and `kowalah_save_process_step` to capture how work actually runs\n- `kowalah_create_opportunity` to log what is worth automating as it comes up\n\nBuild it a function at a time, in the conversation where they are already describing how\ntheir business works. Coverage matters more than depth early on — a shallow map of several\nfunctions is worth more than a deep map of one.\n\nWhat a solo model cannot do is check itself. It is one person's account of how the\nbusiness runs until the people who own those processes confirm their own, which is what\nbringing the rest of the organisation in is for. Mention that when it becomes relevant,\nnot up front.\n\n### They expected their company's organisation and did not get it\n\nIf their company already works with Kowalah, or colleagues are already using it, landing\nin a new organisation of their own is the wrong outcome. Their work would go somewhere\nnobody else can see.\n\nSay so before they start building. The resolution is their Kowalah contact or their\norganisation's AI lead attaching the account to the right organisation, and it is worth\ndoing first rather than migrating later.\n\n### They are in their company's organisation\n\nThe working case. If the model or vision come back `kind: \"empty\"` here, the connection is\nfine and nothing has been authored yet. That is Define-phase work the Kowalah team does\nwith the client, so don't offer to build it from scratch — check with their Kowalah\ncontact instead.\n\nOnce they're connected, offer `my-ai-tools` as a natural next step: it shows them which AI\ntools their assistant has, fixes anything half set up, and lets them share their setup with\nthe organisation's AI register. Offer it once; it's optional.\n\n## If something fails\n\n- **No Kowalah tools at all, or every call fails** — the plugin is installed but its\n  connector isn't connected. The skills load either way, so this is easy to miss. Walk them\n  through step 1 of Connecting; if it shows *Not added*, they need their workspace owner.\n- **401 / authentication error** — the session expired. Re-authenticate.\n- **`User not found for Clerk user: …`** — sign-in worked, but the matching Kowalah\n  account record was never created. This is a provisioning failure, not something the user did.\n  Their Kowalah contact resolves it.\n- **`User … has no active organization memberships`** — signed in, but attached to nothing\n  at all. Rare, and also a provisioning failure. Same route.\n- **Tools succeed but return nothing** — usually the new-organisation case above. Work out\n  which of the two situations it is before treating it as a problem: for someone starting\n  fresh it is the expected state and the answer is to start mapping.\n"
}