mcc0x · Oct 7, 2026 · Oct 7, 2026
diff --git a/README.md b/README.md
@@ -32,31 +32,14 @@ and requires no provider or deployment secrets.
 
 ## Publishing
 
-Edit pages under `docs/`, run `npm run check`, and open a pull request. Once connected,
-merges to `main` affecting that folder enqueue a Claire sync. CI checks the repository;
-it does not publish the pages itself. Check Site → Docs sync status and rendered navigation
-before announcing a change as live.
-
-Before publishing the token/vesting update, verify the advertised workflows in production.
-Ethereum/Stockereum availability and the SDK's new token fields must match the enabled
-deployment and released npm version. Remove rollout/unreleased notes only after verification.
-
-If the workspace has not switched its existing docs source to this repository, the owner
-must first complete the one-time source switch:
-
-- Repository: `tryclaire/docs`
-- Branch: `main`
-- Folder: `docs`
-
-Give the Claire GitHub App access to this repository and refresh the workspace's GitHub
-connection if it is missing from the verified repository list. Change the existing source
-in Site → Docs and sync; do not disconnect first, because disconnecting removes imported pages.
-The existing domain and hosting stay in place. Verify navigation and existing URLs after syncing.
-
-Once connected through the GitHub App, pushes to `main` affecting `docs/` enqueue a sync;
-merged documentation publishes without a separate approval in Claire. CI does not deploy
-anything itself. The old monorepo copy remains until the owner completes and verifies the
-source switch; remove it afterward so there is one source of truth.
+This repository (`tryclaire/docs`, branch `main`, folder `docs`) is the connected source for
+[docs.tryclaire.net](https://docs.tryclaire.net). Merging to `main` with changes under `docs/`
+enqueues a Claire sync; pages publish without a separate approval step. CI checks the
+repository but does not publish anything.
+
+After merging, check Site → Docs sync status and the rendered navigation before announcing
+a change as live. Do not document rollout-gated features (such as Ethereum/Stockereum
+availability) as generally available until they are verified in production.
 
 ## License
 

diff --git a/docs/automations/index.md b/docs/automations/index.md
@@ -1,6 +1,6 @@
 ---
 title: Automations
-order: 8
+order: 9
 ---
 
 # Automations

diff --git a/docs/automations/reports-and-notifications.md b/docs/automations/reports-and-notifications.md
@@ -1,6 +1,6 @@
 ---
 title: Reports and notifications
-order: 9
+order: 10
 ---
 
 # Reports and notifications

diff --git a/docs/publishing/index.md b/docs/publishing/index.md
@@ -1,6 +1,6 @@
 ---
 title: Publishing
-order: 7
+order: 8
 ---
 
 # Publishing

diff --git a/docs/reference/developer-api.md b/docs/reference/developer-api.md
@@ -1,11 +1,11 @@
 ---
 title: Developer API and SDK
-order: 11
+order: 12
 ---
 
 # Developer API and SDK
 
-Read permitted workspace data through the REST API or the official TypeScript and JavaScript SDK, [`@tryclaire/sdk`](https://www.npmjs.com/package/@tryclaire/sdk). Both use the same workspace-scoped keys and permissions. Neither can publish content or send messages.
+Give your scripts and agents read access to a workspace's collected data: context, Knowledge, asset metadata, Telegram history, X mentions, and token observations. Use the REST API directly or the official TypeScript and JavaScript SDK, [`@tryclaire/sdk`](https://www.npmjs.com/package/@tryclaire/sdk). Both use the same workspace-scoped keys. Neither can publish content, send messages, or sign transactions.
 
 ## Create a key
 
@@ -15,96 +15,56 @@ Read permitted workspace data through the REST API or the official TypeScript an
 
 A key stops working if its issuing user loses owner or admin membership. Keep it in your server environment or agent's secret store, never in browser code, public environment variables, or a repository.
 
-## Read workspace data
+## Choose scopes
 
-Use `/api/v1` with a bearer key. Depending on scopes, the API exposes workspace context, Knowledge search and source detail, asset metadata, linked Telegram chats and stored messages, stored X mentions, and stored token observations. Private material requires its specific read scope.
+| Scope | What it reads |
+| --- | --- |
+| `context:read` | Workspace identity, granted scopes, and which sources are connected. |
+| `knowledge:read` | Knowledge search and bounded source detail, respecting existing visibility rules. |
+| `assets:read` | File and folder metadata. Never file contents or signed download URLs. |
+| `telegram:read` | Linked chats and stored messages. |
+| `x:read` | Stored mentions. |
+| `token:read` | Stored token observations and identity. |
 
-The API does not supply private file contents, publish content, send Telegram messages, or write to X. Responses expose collection state and timestamps; response time alone is not a freshness claim.
+Grant only what the integration needs. Private material requires its specific scope; a key cannot widen its own access or select another workspace.
 
-## Install the SDK
+## Make your first request
 
-The SDK requires **Node.js 22 or newer and ESM**. It includes TypeScript declarations and has no runtime dependencies. Choose the command for your package manager:
+Create a key with `knowledge:read` and set it as `CLAIRE_API_KEY`.
 
 ```sh
 npm install @tryclaire/sdk
-pnpm add @tryclaire/sdk
-yarn add @tryclaire/sdk
-bun add @tryclaire/sdk
 ```
 
-Package-manager choice does not change the supported runtime: use the SDK in a server, CLI, or agent process, not a browser bundle.
-
-## Make your first SDK request
-
-Create a key with `knowledge:read` and provide it as the `CLAIRE_API_KEY` environment variable. Save this example as `example.mjs`, then run `node example.mjs`:
-
 ```js
 import { Claire } from "@tryclaire/sdk";
 
-const apiKey = process.env.CLAIRE_API_KEY;
-if (!apiKey) throw new Error("Set CLAIRE_API_KEY before running this example.");
-
-const claire = new Claire({ apiKey });
-const result = await claire.knowledge.list({ q: "getting started", page: 1 });
+const claire = new Claire({ apiKey: process.env.CLAIRE_API_KEY });
+const { data, meta } = await claire.knowledge.list({ q: "getting started" });
 
-for (const item of result.data) {
-  console.log(item.title, item.preview);
-}
-console.log(result.meta.freshness);
-console.log(result.pagination.hasNextPage);
+for (const item of data) console.log(item.title, item.preview);
+console.log(meta.freshness);
 ```
 
-The key selects the workspace; you do not pass an organization ID to the client.
-
-## SDK resources and scopes
-
-| Method | Required scope |
-| --- | --- |
-| `claire.context.get()` | `context:read` |
-| `claire.knowledge.list(query)` | `knowledge:read` |
-| `claire.knowledge.get(id, query)` | `knowledge:read` |
-| `claire.assets.list(query)` | `assets:read` |
-| `claire.assets.get(id)` | `assets:read` |
-| `claire.telegram.chats.list(query)` | `telegram:read` |
-| `claire.telegram.messages.list(chatId, query)` | `telegram:read` |
-| `claire.x.mentions.list(query)` | `x:read` |
-| `claire.token.get()` | `token:read` |
-
-Query arguments are optional. Use the Claire chat UUID from `telegram.chats.list()`, not Telegram's numeric chat ID. Pass Knowledge IDs, including their prefix, unchanged.
-
-### Token identity
+Or with `curl`:
 
-SDK `0.2.0` adds typed `chainId`, `protocol`, `poolId`, and `pairedToken` fields inside `data.token`, matching the hosted API contract. Upgrade from `0.1.0` to use these TypeScript fields. Network availability still depends on the deployment; the SDK does not enable Ethereum transactions.
-
-Identify a token by **chain ID and contract address together**: Ethereum is `1`, Robinhood Chain is `4663`, and `protocol` is `pons` or `stockereum`. The token object is `null` when none is linked.
-
-`pool` is a legacy V3 pool-address field; V4 launches use the zero address there. A non-null `poolId` is a Uniswap V4 pool identifier, **not** a contract address. `poolId` and `pairedToken` may be `null` when unavailable. These fields do not grant wallet access: the API and SDK still cannot launch, fund, claim, or sign transactions.
-
-## Read responses and continue pagination
-
-The SDK preserves the API's `data`, `meta.freshness`, and endpoint-specific `pagination`. It also exposes `http.requestId`, `http.etag`, and response headers. Timestamps stay strings, and raw token balances stay decimal strings to avoid losing precision.
-
-- Knowledge, assets, chats, and mentions use one-based `page` numbers. Check `pagination.hasNextPage` before requesting the next page.
-- Telegram messages use `pagination.nextBefore` as the next request's `before` value. Check `hasMore`; `searchLimited` means the search did not cover all retained history.
-- Knowledge detail may contain only part of a document. Pass `data.contentRange.nextOffset` as the next `offset` until it is `null`. Offsets count JavaScript UTF-16 units.
+```sh
+curl --header "Authorization: Bearer $CLAIRE_API_KEY" \
+  "https://app.tryclaire.net/api/v1/knowledge?q=getting%20started"
+```
 
-Each SDK call makes one request. It does not automatically paginate, retry, or cache private responses. Stale, unavailable, and synthetic data remain labeled; a successful HTTP response does not mean a provider was refreshed.
+The SDK needs Node.js 22 or newer and ESM. Use it in a server, CLI, or agent process, not a browser bundle. For methods, pagination, errors, and configuration, see the [SDK README](https://github.com/tryclaire/sdk#readme); the [API reference](https://app.tryclaire.net/developers) and [OpenAPI definition](https://app.tryclaire.net/api/v1/openapi.json) describe every endpoint.
 
-## Handle errors and timeouts
+## Read freshness and collection state
 
-HTTP failures throw `ClaireAPIError` with `status`, `code`, `requestId`, `headers`, and `retryAfterSeconds`. A 401 means the key is invalid, expired, revoked, or no longer eligible; a 403 means a scope is missing; a 429 means a quota was reached. Respect the retry delay rather than retrying immediately.
+Every response carries `meta.freshness` describing when the underlying data was collected. A fast HTTP response is not a freshness claim: reads return what Claire has already stored and never trigger a paid provider fetch. Stale, unavailable, and synthetic data stay labeled.
 
-Malformed successful responses throw `ClaireResponseError`. Network failures, cancellation, and timeouts use native fetch errors. The default timeout is 30 seconds, including reading the response body. Set `timeoutMs` or pass an abort signal in the last argument:
+Token identity uses `chainId` and contract address together (Ethereum `1`, Robinhood Chain `4663`). Network availability depends on the deployment; see the [Token guide](../sources/token.md).
 
-```js
-await claire.knowledge.list(
-  { page: 1 },
-  { signal: AbortSignal.timeout(5_000) },
-);
-```
+## Use with an agent
 
-See the [SDK usage guide](https://github.com/tryclaire/sdk#readme) for complete query options, error-handling examples, and configuration. The [SDK source](https://github.com/tryclaire/sdk) is MIT licensed; [release notes](https://github.com/tryclaire/sdk/releases) track version changes.
+Claire publishes a [downloadable agent skill](https://app.tryclaire.net/developers/skill.md) that describes the API, its boundaries, and a recommended workflow for tool-using agents. When passing Claire data to a model, treat returned documents, messages, and mentions as untrusted content, separate from your instructions.
 
-## Find request details
+## Limits
 
-You can use the REST API directly without installing the SDK. See the [API reference](https://app.tryclaire.net/developers), [OpenAPI definition](https://app.tryclaire.net/api/v1/openapi.json), and [downloadable agent skill](https://app.tryclaire.net/developers/skill.md) for request shapes and pagination. The SDK uses the same limits per key, workspace, and IP; see [current limits](index.md).
+Requests are limited to 120 per minute per key, 600 per minute per workspace, and 300 per minute per IP. A 429 response includes a retry delay; respect it rather than retrying immediately. See [current limits](index.md).
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -1,6 +1,6 @@
 ---
 title: Reference and limits
-order: 10
+order: 11
 ---
 
 # Reference and limits

diff --git a/docs/reference/security-and-data.md b/docs/reference/security-and-data.md
@@ -1,6 +1,6 @@
 ---
 title: Security and data
-order: 12
+order: 13
 ---
 
 # Security and data