--- name: use-shadstone-handbook description: Securely search, read, and update Shadstone's private internal handbook through its authenticated agent interfaces. --- # Shadstone Handbook agent contract New to the Handbook? Read [https://handbook.shadstone.com/skill_gettingstarted.md](https://handbook.shadstone.com/skill_gettingstarted.md) first. This file is the stable operating contract for an already-oriented agent. ## Authentication and secrets Read [https://wallet.gfavip.com/skill.md](https://wallet.gfavip.com/skill.md) and use its PowerLobster headless SSO flow with your existing identity. Never open or automate the human browser sign-in. Use the resulting GFAVIP session token as a Bearer token on every API request. Never print, log, persist in Handbook content, or put a token in a query string. Call `GET https://handbook.shadstone.com/api/me` first. If access is not approved, report the exact GFAVIP username to a human administrator; do not create a replacement identity. ## Connecting Claude The MCP endpoint is `https://handbook.shadstone.com/mcp`. Every request to it must be authenticated, `initialize` and `ping` included. There are two ways in: - **A headless agent** sends its GFAVIP session token as a Bearer token, exactly as it does for the REST API. See [https://wallet.gfavip.com/skill.md](https://wallet.gfavip.com/skill.md). - **A person using Claude** (claude.ai, Claude Desktop or Claude Code) adds `https://handbook.shadstone.com/mcp` as a custom connector and approves it in the browser. The approval screen names the app and the address it will send you back to. No token is pasted anywhere, and the app registers itself. An anonymous call is refused with `401` and a `WWW-Authenticate` header whose `resource_metadata` points at `https://handbook.shadstone.com/.well-known/oauth-protected-resource/mcp`, which is how a connector client finds where to sign in. A connector can do everything your account can, and no more. Its access tokens are short-lived and the client renews them itself. It is refused at once, on its very next request, if you disconnect it or your account is deactivated, and a change to your rank applies to it on the next call. Manage your connections at https://handbook.shadstone.com/connections. An administrator can see and disconnect everyone's at https://handbook.shadstone.com/admin/connections. Tools are offered by rank: viewer, editor or administrator. A tool above your rank is not listed, and calling it by name answers exactly as an unknown tool does. When agent writes are switched off, every agent caller is held to the viewer tools whatever the account's rank. Call `whoami` to see your effective rank and whether you may write. No tool deletes an article, over MCP or the API. Archive it instead. ## Read safely - Prefer `GET /api/search?q=` over listing everything. - Read an article with `GET /api/articles/` and retain its `ETag` if an edit may follow. - A `404` means absent **or not visible to this identity**. Never use it as evidence that a private document exists, and never create a duplicate to bypass it. - Results are already filtered to this identity. Do not attempt to broaden access or infer hidden titles and paths. ## Write safely Writing requires the `editor` role and may be disabled for agents. 1. Search and read before writing. 2. On `PATCH`, send the observed `ETag` as `If-Match`. If the server returns `412`, re-read and reconcile instead of overwriting. 3. Send a clear `X-Action-Reason` with every mutation. It becomes part of the revision history. 4. Use Markdown, not raw HTML. Use Handbook-owned media rather than remote images, which could disclose who reads a private page. 5. When a change is ambiguous or consequential, especially around money, access, privacy, or safety, show the proposed text to a human before saving. `POST /api/articles` publishes it immediately. There is no draft state and no unpublish. Do not probe the schema with real writes: send the finished page, or send nothing. A create without a body is refused for this reason. On `POST /api/articles` or `PATCH /api/articles/`, use `category_slugs: ["it"]` and `tag_slugs: ["netlify", "seo"]` to set the exact categories and tags. Both fields are arrays of slugs; an empty array clears that set. Tags must be supported by words in the title or body. An unknown field or unknown category slug returns `400` rather than being silently ignored. ## Retire a page Nothing here is deleted. A page that is no longer true is **filed under the Archive axis**, which is what "outdated" means in this handbook; its address, its history and its inbound links all stay. There is no `DELETE` route and no `archived` field, and hunting for one is how blank stub pages get made. Archive with the edit call you already have: ``` PATCH /api/articles/ {"category_slugs": [""], "change_summary": "Archived: superseded by "} ``` `category_slugs` replaces the whole set, so send the archive section alone. Ask a human administrator which archive section to file under, or to create one; do not guess a slug, and do not invent a replacement page because the old one is wrong. Permanent deletion exists for pages that should never have been written at all, but it is a human administrator's action in the browser and there is no API or MCP equivalent. Archiving is the agent-facing answer, always. If a page truly needs removing, archive it and say so to a human. Core resources: - Articles: `GET/POST https://handbook.shadstone.com/api/articles` - One article: `GET/PATCH https://handbook.shadstone.com/api/articles/` - Search: `GET https://handbook.shadstone.com/api/search?q=` - Skills: `GET/POST https://handbook.shadstone.com/api/skills` - One skill: `GET/PATCH https://handbook.shadstone.com/api/skills/` Use `[[Document title]]` for an internal document link and `[[skill:skill-name]]` for a Handbook skill. Set `source_note_url` when a page should link back to the discussion it came from.