@extuitive/skill 0.1.0

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@extuitive/skill",
+  "version": "0.1.0",
+  "description": "The Extuitive agent skill and installer for Claude Code, Codex, and Claude Desktop. Run it with `npx extuitive`.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/fl100inc/extuitive-skill.git"
+  },
+  "homepage": "https://github.com/fl100inc/extuitive-skill#readme",
+  "bugs": {
+    "url": "https://github.com/fl100inc/extuitive-skill/issues"
+  },
+  "keywords": [
+    "extuitive",
+    "mcp",
+    "claude-code",
+    "claude-desktop",
+    "codex",
+    "agent-skills",
+    "facebook-ads"
+  ],
+  "files": [
+    "bin",
+    "src",
+    "skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "doctor": "node bin/cli.mjs doctor"
+  }
+}

package/skills/extuitive/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: extuitive
+description: Work with Extuitive, where each workspace is one Facebook ads account. Check that Extuitive is connected and signed in, choose which ad account to work in, upload images and videos in bulk, check how an upload is going and which files were accepted, connect or repair a Meta connection, or set Extuitive up from scratch. Use when asked to check the Extuitive connection or whether Extuitive is set up, to upload, add, or import creative, ad images, ad videos, or a folder of assets into Extuitive, to check an Extuitive upload, to pick or switch which Extuitive workspace or ad account to work in, or when Extuitive tools are missing or refusing.
+argument-hint: "[init | select | upload | upload-status | connect]"
+arguments: command
+---
+
+# Extuitive
+
+One skill, five jobs. Read the reference for the job you are doing and follow it; this page
+only routes.
+
+## Which job
+
+The requested command is **`$command`**, from the full invocation `$ARGUMENTS`.
+
+If that is empty, or still reads as a literal `$command` because this host does not
+substitute arguments, work it out from what was actually asked instead.
+
+| Command | Read | For |
+| --- | --- | --- |
+| `init` | `references/init.md` | Nothing is set up yet, the tools are missing, or "check my Extuitive connection" — is it set up, signed in, and working |
+| `select` | `references/select.md` | Choose which ad account the rest of this session works in |
+| `upload` | `references/upload.md` | Send local files into a workspace |
+| `upload-status` | `references/upload-status.md` | How is an upload going, what was accepted |
+| `connect` | `references/connect.md` | No workspaces, or ads data has gone stale — the *Meta* connection |
+
+Anything else, or nothing at all: pick from the "For" column. An unrecognised command is
+worth one sentence — say what the five are — rather than a guess.
+
+"Connection" is ambiguous here, so route it by what is being asked about. Whether *this
+host* can reach Extuitive — tools present, signed in, workspaces listed — is `init`, which
+checks all three in order and hands off to `connect` itself if the only thing missing is a
+Meta connection. Whether a *workspace's* ads data is flowing is `connect`.
+
+`references/tools.md` documents every tool's arguments, the error vocabulary, and the status
+lifecycle. Reach for it when a call fails or a field is not what you expected.
+
+## True regardless of which job
+
+**The MCP tools never carry file bytes.** `create_upload_batch` hands back presigned storage
+URLs and whoever holds the files sends the bytes there directly. No tool accepts a file. If
+you cannot open the person's files, you cannot upload — use `create_browser_upload_link` and
+let them do it from their browser. Being able to run code is not the same as being able to
+read their disk; some hosts give you one without the other.
+
+**Signing in happens in a browser and only the person can do it.** The token lands in this
+host's own credential store. You never see it, and no amount of retrying substitutes for it.
+
+**If the Extuitive tools are not in this session, stop and read `references/init.md`.** Do not
+invent setup commands. They differ per host and they change.
+
+**Uploading files is not an instruction to do anything with them.** Thirty images is not a
+request for thirty ads. Report what landed and wait.
+
+**Say what a tool returned, not what it implies.** The fields on a workspace do not predict
+which tools will accept it — `role` and `isOwner` govern reconnecting Meta and nothing else —
+so "use this one for uploads" is a claim you can only make after one worked. Two workspaces
+can point at the same ad account and behave differently. Ask rather than choose.
+
+**Ask which workspace once, then stop asking.** A choice made anywhere in the conversation —
+through `select`, or in passing while asking for something else — holds until they change it
+or the session ends. Re-asking on every upload is its own kind of wrong answer.

package/skills/extuitive/references/connect.md

@@ -0,0 +1,75 @@
+# `/extuitive connect` — connect or repair Meta
+
+Each Extuitive workspace is one Facebook ads account. When something is wrong with that
+connection, the tools tell you what and where to send the person — your job is to route to the
+right one and relay what it says.
+
+The reverse does not hold: two workspaces can point at the same ads account, each with its own
+connection and its own `canReconnect`. Repairing one does not repair the other, so check the
+`metaConnection` on the workspace you are actually being asked about.
+
+## Two different problems
+
+They look similar and have different fixes, so identify which one you have before acting.
+
+- **No workspaces at all.** `list_workspaces` returns an empty list. This is a setup problem,
+  and it belongs to the person themselves. Use `get_meta_setup_status`.
+- **A workspace exists but its data has gone stale.** `list_workspaces` returns a workspace
+  whose `metaConnection.status` is not `healthy`. This is a repair problem, and it may belong
+  to someone else. Use `create_meta_reconnect_link`.
+
+Do not guess between them. Sending someone who already finished Meta OAuth back through it
+achieves nothing and wastes their time.
+
+## No workspaces yet
+
+Call `get_meta_setup_status`. It takes no arguments and answers the question an empty
+`list_workspaces` cannot: whether they never connected Meta, or connected it but never chose
+ad accounts, or connected it and Meta returned no ad accounts.
+
+It gives you back:
+
+- `stage` — which of those situations this is
+- `url` — the page that completes this particular stage
+- `nextStep` — what to tell them, already worded for the stage
+
+**Relay `nextStep` rather than writing your own.** It is phrased per stage precisely so that
+someone who is already connected is not told to connect again.
+
+Give them the `url`. It requires them to be signed in, so it grants nothing on its own — it is
+an ordinary link to a page, not a credential. Then ask them to call you back and run
+`list_workspaces` again.
+
+## A workspace whose connection is broken
+
+`list_workspaces` reports `metaConnection` on every workspace:
+
+| `status` | Means |
+| --- | --- |
+| `healthy` | Working. Nothing to do. |
+| `expiring` | The token will expire soon; `daysUntilExpiry` says when. |
+| `token_invalid` | The token stopped working. Ads data is stale until it is renewed. |
+| `missing_scope` | Meta stopped granting the ads permissions this workspace needs. |
+| `ad_account_permission` | Their Meta user has no role on this ad account. |
+
+**Check `metaConnection.canReconnect` before calling `create_meta_reconnect_link`.** Only the
+workspace owner can reconnect, because the Meta account is theirs. When `canReconnect` is
+`false`, tell the person to ask the workspace owner — do not call the tool to find out, it
+will refuse with `not_workspace_owner`.
+
+`canReconnect` is also `false` for `ad_account_permission` even when the person *is* the
+owner, because reconnecting cannot grant a Business Manager role. That one is fixed in Meta's
+own settings, not in Extuitive.
+
+When `canReconnect` is `true`, call `create_meta_reconnect_link` with the `workspaceId`. It
+returns a `url` and a `nextStep`. Same rule as above: relay the `nextStep`, hand over the
+`url`, and note that the page requires sign-in.
+
+## What not to do
+
+Do not report numbers from a workspace whose connection is broken without saying so. A
+`token_invalid` workspace still has data, but it stopped updating on the day the token died,
+and presenting it as current is worse than reporting nothing.
+
+Do not treat any of these URLs as secret. They all point at pages that require the person to
+be signed in.

package/skills/extuitive/references/init.md

@@ -0,0 +1,83 @@
+# `/extuitive init` — set Extuitive up, or check that it is
+
+Gets a person from nothing to a working connection, and doubles as the check: "is Extuitive
+connected?" is answered by walking the same three steps and reporting where they stop. Run
+when asked to set up or check the connection, or when the Extuitive tools are missing from
+the session.
+
+Work through the obstacles in order. Each has to be true before the next can be. When asked
+only to check, say which step you got to and stop there; do not start fixing what was not
+asked about.
+
+## 1. Is this host connected to the Extuitive MCP server?
+
+If the Extuitive tools are not available in this session, the connection is not set up.
+
+**Some hosts have no command line at all.** If this one is a desktop app where you reached the
+person through a chat window rather than a terminal — Claude Desktop is the one to expect —
+then the connection is a panel they click through, and telling them to run something would
+send them looking for a terminal they may not have:
+
+> Settings, then Connectors, then Add custom connector, and paste
+> `https://www.extuitive.com/mcp` as the URL.
+
+Everywhere else, tell them to run:
+
+```bash
+npx github:fl100inc/extuitive-skill doctor
+```
+
+That checks the endpoint, whether this host has the server registered, and whether sign-in
+has been completed, and it prints the exact next command for their host.
+
+**Do not invent setup commands.** They differ per host, they change between versions, and
+`doctor` reads the current ones. A stale command sends someone down a dead end that looks
+like the product is broken. The connector URL above is the one exception, and only because
+it is a URL rather than a command — there is nothing about it to go stale but the address.
+
+Relay what `doctor` prints, in the order it prints it. Three things are worth saying plainly
+while they work through it:
+
+- **Signing in happens in a browser and only they can do it.** It opens a page, they approve
+  access, and the token goes into their host's credential store. You never see it.
+- **Do not run the sign-in step yourself.** If `doctor` prints a slash command, it belongs to
+  the person's session, not your shell; if it prints a shell command, it opens a browser and
+  waits for a redirect your shell cannot receive. Either way, running it produces a failure
+  that reads as a broken install. Print the step and stop.
+- **The tools will not appear in this session.** Hosts connect MCP servers when a session
+  starts, so nothing registered while you have been running is visible to you. (The skill
+  itself is different: hosts pick up new skills without a restart, which is why you are
+  reading this.) Say so, and ask them to start a fresh session — a new chat, in a desktop
+  app — before checking. Retrying the tools here will not make them exist.
+
+## 2. Do they have an account?
+
+They do not need one in advance, and you should not send them off to make one first.
+
+The sign-in page in step 1 offers **Sign up** alongside **Log in**, both with a one-time
+email code. Someone with no account creates it there, in the same browser step that grants
+this host access. If they have no Meta connection yet, that same page then shows a panel
+pointing at the right setup step and returns them to the consent screen afterwards.
+
+So: let the flow do it. Do not narrate the signup steps or send them to a separate page —
+anything you add is a second, worse copy of a flow that already handles this.
+
+## 3. Does it work?
+
+Once the tools are available, call `list_workspaces`.
+
+- **It returns workspaces.** Setup is done. Say which ones they have and stop.
+- **It returns an empty list.** They are signed in but have no ads account connected yet.
+  Read `connect.md` — it covers exactly this.
+- **It refuses.** They are not signed in. Back to step 1.
+
+## What "done" means
+
+At least one workspace from `list_workspaces`. Until then, do not start on anything else they
+asked for: uploads and reporting both need a `workspaceId`, and every one of those tools will
+refuse without it.
+
+When setup started from a session with no Extuitive tools, that call belongs to the next
+session, not this one. Finish by handing over the remaining steps and saying which one they
+are on — not by declaring it working, and not by checking again for tools that cannot arrive
+until they restart.

package/skills/extuitive/references/select.md

@@ -0,0 +1,89 @@
+# `/extuitive select` — choose which ad account to work in
+
+An Extuitive workspace is one Facebook ads account. This picks the one the rest of the
+conversation uses, so the person is not asked again on every upload and every status check.
+
+Anything they typed after the command — a name, a slug, an ad account id — arrives in
+`$ARGUMENTS`.
+
+**The choice lasts this conversation and nothing longer.** Nothing is written to disk, and no
+tool remembers it. A new session starts with none, which is worth saying once when they choose
+so that it is not a surprise tomorrow.
+
+If the Extuitive tools are missing from this session, read `init.md` instead. There is nothing
+to select from until they are there.
+
+## 1. List what they can actually reach
+
+Call `list_workspaces`. It takes no arguments.
+
+An **empty list** means they have no workspace, not that they lack access to one. Read
+`connect.md`; there is nothing to select yet.
+
+**Exactly one** is not a question. Say which workspace you are using and move on — a menu of
+one spends a turn to tell them something they cannot change.
+
+## 2. Show every row, ranked by nothing
+
+Give them each workspace with the three fields that actually tell one from another:
+
+| Show | From | Why |
+| --- | --- | --- |
+| Name | `name` | The only part they will recognise |
+| Ad account | `facebookAdAccountId`, or say it has none when `null` | What they think of as the account |
+| Connection | `metaConnection.status`, when it is not `healthy` | A stale workspace is still selectable, and they should know that before choosing it |
+
+**Do not order or recommend by `role` or `isOwner`.** Those govern who may reconnect Meta and
+say nothing about uploading — a workspace where they are `viewer` may take files that the one
+where they are `owner` refuses. Presenting one as the right one to work in is a claim you
+cannot make yet.
+
+**Two rows can carry the same `facebookAdAccountId`.** They are two separate workspaces with
+separate content, not one workspace listed twice. Show both, say they point at the same ad
+account, and let them pick. The ad account id does not identify a workspace, and collapsing
+the two loses the distinction that decides where their files end up.
+
+## 3. Match what they said, or ask
+
+When `$ARGUMENTS` names something, match it against `name`, `slug`, and
+`facebookAdAccountId`, ignoring case.
+
+- **One match.** Take it, and confirm which one by name.
+- **Several.** Ask which, showing what differs between them. A shared ad account id lands
+  here, and it is the case where a guess costs the most.
+- **None.** Say so and list what they do have, rather than matching loosely onto whichever
+  name looks closest.
+
+With no argument, ask.
+
+## 4. Say what you selected
+
+Confirm the workspace by **name**, not by id. The id is for the tools; the name is the part
+they can check. Mention its ad account when it has one.
+
+Then hold that `workspaceId` and pass it to every workspace-scoped call for the rest of the
+conversation. Not asking again is the entire point of having asked once.
+
+## Selecting is not access
+
+**A selected workspace can still refuse a call.** Membership is re-checked on every single
+call, so `workspace_access_denied` can come back from a `workspaceId` that `list_workspaces`
+returned a moment earlier.
+
+When it does, the selection is wrong rather than the call. Say plainly which one was refused,
+select another, and carry on in that one — correcting yourself in the same breath if you had
+already told them their files were going somewhere else. Retrying the refused id will not
+change it, and neither `role` nor `isOwner` explains it.
+
+## Switching later
+
+People change their mind mid-conversation. Run this again and replace the selection.
+
+Two things do not follow the switch. A `batchId` belongs to the workspace it was created in,
+so checking on an older batch needs the workspace it was made in, not the current one. And
+files already uploaded stay where they were sent — selecting elsewhere moves nothing.
+
+## Choosing without the command
+
+Naming a workspace in passing — "upload these to Acme" — is a selection. Take it, say which
+workspace you understood that to mean, and do not ask again in the same breath.

package/skills/extuitive/references/tools.md

@@ -0,0 +1,252 @@
+# Extuitive MCP tools
+
+Every tool the Extuitive MCP server exposes, with its arguments and what it gives back. Read
+this when you need a schema or an error meaning; the `SKILL.md` files carry the procedures.
+
+Server endpoint is `https://www.extuitive.com/mcp`. Every tool except `list_workspaces`,
+`get_meta_setup_status`, and `create_meta_reconnect_link`'s sibling takes a `workspaceId`, and
+membership is re-checked on every single call — a token issued before someone left a workspace
+does not still reach it.
+
+## Read this first: five things that cause wrong answers
+
+1. **`role` and `isOwner` say nothing about uploading.** They decide one thing only: who may
+   call `create_meta_reconnect_link`. A workspace where this caller is `viewer` may accept
+   uploads that the one where they are `owner` refuses. Nothing in a `list_workspaces` row
+   predicts which workspaces the upload tools will accept, so never present one as the right
+   one for uploads — ask, or try and report what happened.
+2. **`count` is not the batch size.** In `get_upload_batch_content`, `count` describes only
+   the rows returned after filtering. `statusCounts`, `pending`, and `settled` always describe
+   the whole batch. Filtering to `["READY"]` and reading `count` makes an unfinished upload
+   look complete.
+3. **`complete_upload` uses S3's capitalisation.** `PartNumber` and `ETag`, not `partNumber`
+   and `eTag`. They are the only non-camelCase fields in the entire surface.
+4. **`sign_upload_part` does not give you the checksum.** You compute
+   `x-amz-checksum-crc32c` yourself over the exact bytes of that part and send it as a header.
+   The signature covers that header, so S3 rejects the part when it is missing or wrong. The
+   bundled `scripts/upload.mjs` does this for you.
+5. **No tool is annotated.** None declares `readOnlyHint`, `destructiveHint`, or an output
+   schema, so nothing can be inferred about safety from the listing. `abort_upload` is
+   destructive and carries no marking.
+
+Results always arrive as both a JSON text block and `structuredContent` with the same payload.
+
+## Workspaces
+
+### `list_workspaces`
+
+No arguments. Start every session here.
+
+Returns `{ workspaces: [...] }`, each with:
+
+| Field | Meaning |
+| --- | --- |
+| `workspaceId` | Pass this to every other tool |
+| `name`, `slug` | Display |
+| `role` | This caller's role in the workspace. Governs reconnect only |
+| `facebookAdAccountId` | The Meta ads account, or `null`. Not unique across workspaces |
+| `isOwner` | Whether this caller owns the workspace. Governs reconnect only |
+| `metaConnection.status` | `healthy`, `expiring`, `token_invalid`, `missing_scope`, `ad_account_permission` |
+| `metaConnection.daysUntilExpiry` | Whole days, or `null` when Meta gave no expiry |
+| `metaConnection.canReconnect` | Whether *this* caller can fix it |
+
+An empty list means no workspace, not no access. Follow with `get_meta_setup_status`.
+
+Two rows can carry the same `facebookAdAccountId`. They are still two separate workspaces
+with separate content, not one workspace listed twice, so do not merge them or pick between
+them on the person's behalf. Whichever they choose is the one their files will be in.
+
+A row in this list is also not a guarantee that every tool will accept its `workspaceId`; see
+`workspace_access_denied` below.
+
+## Meta connection
+
+### `get_meta_setup_status`
+
+No arguments. The right follow-up to an empty `list_workspaces`.
+
+Returns `stage`, `connected`, `discoveredAdAccountCount`, `connectedAdAccountCount`, `action`,
+`url` (absent only when setup is complete), and `nextStep`. Relay `nextStep` rather than
+writing your own wording — it differs per stage so that someone already connected is not told
+to connect again.
+
+### `create_meta_reconnect_link`
+
+| Argument | Required | Notes |
+| --- | --- | --- |
+| `workspaceId` | yes | Caller must **own** it, not merely belong to it |
+
+Returns `workspaceId`, `status`, `action`, `url`, `nextStep`. Check
+`metaConnection.canReconnect` first; a non-owner gets `not_workspace_owner` and the right
+answer is to ask the owner instead.
+
+## Uploads
+
+Bytes never pass through any of these. `create_upload_batch` mints presigned storage URLs and
+the caller sends bytes to them directly.
+
+### `get_upload_limits`
+
+| Argument | Required |
+| --- | --- |
+| `workspaceId` | yes |
+
+Returns `multipartThresholdBytes`, `recommendedPartBytes`, `maxParts`, `maxFiles`, and
+`media.image` / `media.video`, each with `maxBytes` and `contentTypes`. Image and video
+ceilings differ by orders of magnitude. Never hardcode any of these.
+
+### `create_upload_batch`
+
+| Argument | Required | Notes |
+| --- | --- | --- |
+| `workspaceId` | yes | |
+| `files` | yes | 1 to `maxFiles` entries (250 when the server does not say) |
+| `files[].fileName` | yes | Including extension |
+| `files[].contentType` | yes | Must be an allowed type |
+| `files[].bytes` | yes | Whole number, the real size |
+
+Returns `batchId`, `metaAdAccountId`, `createdAt`, `fileCount`, and `files` — one destination
+per file, in the order sent. A destination is one of:
+
+- **PUT** — `method`, `fileName`, `contentId`, `url`, `fields`, `headers`, `expiresIn` (1800).
+  Send the whole file to `url` with `headers` verbatim.
+- **MULTIPART** — `method`, `fileName`, `contentId`, `uploadId`, `key`, `partBytes`. Needs
+  `sign_upload_part` per part, then `complete_upload`.
+
+### `resign_upload`
+
+| Argument | Required |
+| --- | --- |
+| `workspaceId`, `contentId` | yes |
+
+A fresh presigned PUT for one file. Every URL in a batch is signed at the same instant and
+lasts 1800 seconds, so late files in a large batch can expire while early ones are still
+transferring. Call on a 403, or when most of `expiresIn` has passed.
+
+### `sign_upload_part`
+
+| Argument | Required | Notes |
+| --- | --- | --- |
+| `workspaceId`, `uploadId` | yes | |
+| `partNumber` | yes | 1 to 10000 |
+
+Returns `{ url, headers, expiresIn }`. Takes no bytes and no checksum, so all parts can be
+signed up front before any transfer starts. Part count is `ceil(bytes / partBytes)`.
+
+### `list_upload_parts`
+
+| Argument | Required |
+| --- | --- |
+| `workspaceId`, `uploadId` | yes |
+
+Returns a **bare array** of `{ PartNumber, Size, ETag }` — what storage already holds. Use it
+to resume without re-sending parts that landed.
+
+### `complete_upload`
+
+| Argument | Required | Notes |
+| --- | --- | --- |
+| `workspaceId`, `uploadId` | yes | |
+| `parts` | yes | `{ PartNumber, ETag }[]`, capitalised exactly so |
+
+Assembles the object. Returns `VALIDATING` — this does **not** mean accepted. Safe to retry.
+
+### `abort_upload`
+
+| Argument | Required |
+| --- | --- |
+| `workspaceId`, `uploadId` | yes |
+
+Discards a multipart upload and its stored parts. Destructive, and not marked as such.
+
+### `list_upload_batches`
+
+| Argument | Required |
+| --- | --- |
+| `workspaceId` | yes |
+
+Batches newest first, each with `batchId`, `createdAt`, `fileCount`, `pending`, and
+`statusCounts`. No file rows. The cheap way to check on an upload, and the way to find a batch
+someone created through a browser link. May return `truncated: true` at 1000 items, with no
+cursor beyond that.
+
+### `get_upload_batch_content`
+
+| Argument | Required | Notes |
+| --- | --- | --- |
+| `workspaceId`, `batchId` | yes | |
+| `status` | no | Array of statuses; omit for all |
+| `mediaKind` | no | `image` or `video`; omit for both |
+
+Returns `content`, `count`, `statusCounts`, `pending`, `settled`, `batchId`. Each content row:
+`contentId`, `status`, and optionally `rejectionReason`, `fileName`, `mediaKind`, `bytes`,
+`contentType`, `format`, `createdAt`, `updatedAt`, and `url` on a `READY` image.
+
+Remember that filtering narrows `content` and `count` only.
+
+### `get_upload_content`
+
+| Argument | Required |
+| --- | --- |
+| `workspaceId`, `contentId` | yes |
+
+One row, same shape as above. For a file uploaded on its own, which has no `batchId`.
+
+### `create_browser_upload_link`
+
+| Argument | Required |
+| --- | --- |
+| `workspaceId` | yes |
+
+Returns `{ workspaceId, url }` — a page where the person uploads from their browser. Use it
+whenever you cannot make HTTP requests, and for very large video where signing every part
+would take too many calls. The page requires them to be signed in, so the link grants nothing
+on its own.
+
+## Status lifecycle
+
+| Status | Final | Counted in `pending` |
+| --- | --- | --- |
+| `CREATED` | no | yes |
+| `UPLOADING` | no | yes |
+| `VALIDATING` | no | yes |
+| `READY` | **yes** | no |
+| `REJECTED` | yes | no |
+| `ABORTED` | yes | no |
+| `EXPIRED` | no | yes |
+
+`READY` is the only status that means a file uploaded successfully. Poll every 5 seconds, give
+up after 5 minutes.
+
+## Errors
+
+Refusals come back as a result with `isError: true` and a payload of `{ error, message }`, so
+they are yours to read and act on rather than hard failures.
+
+| `error` | Meaning |
+| --- | --- |
+| `invalid_arguments` | A required argument is missing, empty, or out of range |
+| `invalid_upload_body` | The `files` manifest was malformed |
+| `missing_workspace_id` | `workspaceId` was blank |
+| `workspace_access_denied` | Caller is not a member of that workspace |
+| `not_workspace_owner` | Caller belongs to the workspace but does not own it |
+| `upload_not_found` | No such content id |
+| `upload_signing_unreachable` | Upstream signing service could not be reached |
+| `upload_signing_timeout` | Upstream signing service timed out |
+| `upload_signing_invalid_json` | Upstream returned something unparseable |
+| `upload_signing_unconfigured` | Server is missing its upstream credentials |
+| `upstream_{status}` | Upstream error with no more specific code |
+| `internal_error` | Server-side fault; the detail is logged, not returned |
+
+Genuine protocol faults — an unknown tool, malformed JSON-RPC — arrive as JSON-RPC errors
+instead, and mean something is wrong with the call itself rather than its arguments.
+
+### `workspace_access_denied` on an id from `list_workspaces`
+
+This happens, and it is not something to solve by reasoning. Membership is re-checked on every
+call against the tool being called, so a workspace can appear in the list and still refuse an
+upload. Retrying will not change it, and neither `role` nor `isOwner` predicts it.
+
+Say plainly which id was refused and which one worked, and carry on with the one that worked.
+If you had already told the person to use the refused one, correct that in the same breath —
+they are about to look for their files in a workspace that has none.