mcc0x · Oct 7, 2026 · Oct 7, 2026
diff --git a/docs/automations/index.md b/docs/automations/index.md
@@ -7,6 +7,8 @@ order: 9
 
 Owners and admins can create explicitly enabled rules that use a source event or weekly schedule to take an action in a linked Telegram chat. Rules do not post to X.
 
+The Developers API and MCP connections are read-only; enabling Agent access does not create or enable an automation rule. Telegram automations remain separately configured here and explicitly enabled by a manager.
+
 ## Choose a trigger
 
 | Trigger | Event |
@@ -39,4 +41,4 @@ At delivery, Claire rechecks the rule, approving manager's role, connected accou
 > [!IMPORTANT]
 > Unknown is never retried automatically. Check the chat before taking another action.
 
-A completed post is not posted again just because pinning it failed. Live delivery has an organization-wide hourly cap; see [current limits](../reference/index.md). See also [reports and notifications](reports-and-notifications.md).
+A completed post is not posted again just because pinning it failed. Live delivery has an organization-wide hourly cap; see [current limits](../reference/index.md). See also [notifications](reports-and-notifications.md).
diff --git a/docs/automations/reports-and-notifications.md b/docs/automations/reports-and-notifications.md
@@ -1,21 +1,11 @@
 ---
-title: Reports and notifications
+title: Notifications
 order: 10
 ---
 
-# Reports and notifications
+# Notifications
 
-Claire saves weekly reports from already collected workspace data and notifies owners and admins when reports are ready. Your notification bell holds other workspace updates.
-
-## Read a weekly report
-
-After each ISO week (Monday to Sunday, UTC) ends, Claire generates that week's report for every workspace with a linked Telegram chat, X account, or token. Open Reports to view saved reports. An owner or admin can also generate the most recently completed week on demand.
-
-A report collects available figures from linked Telegram chat activity, stored X observations, linked token observations, published docs and domains, and automation runs. It shows the previous week for comparison. Disconnected sources have no section. Reports use data Claire already collected; they do not query providers live.
-
-## Share a report
-
-An owner or admin can enable a public read-only link for a report and turn it off again. Anyone with an active link can view that report, so share it only with people who should see those figures. The ordinary report view requires workspace access.
+Your notification bell holds workspace updates. Notification delivery is separate from the [Telegram automation rules](index.md) your team explicitly enables; a weekly automation schedule is not a generated report.
 
 ## Set notification preferences
 

diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -5,7 +5,7 @@ order: 2
 
 # Getting started
 
-Your personal space and organization workspaces are separate. Personal navigation contains your Home, Wallet and account settings; an organization contains its activity, sources, Knowledge, Assets, site and management settings. Create or choose a workspace for your project. You do not need to link a token to use Telegram, X, Knowledge, or the site.
+Your personal space and organization workspaces are separate. Personal navigation contains your Home, Wallet and account settings; an organization contains its activity, sources, Knowledge, site and management settings. Knowledge contains Context (library and People), Assets and Settings; Developers contains API, MCP and Settings. Create or choose a workspace for your project. You do not need to link a token to use Telegram, X, Knowledge, or the site.
 
 ## Create a workspace
 
@@ -37,4 +37,4 @@ Only the owner changes another member's role.
 
 [Link a Telegram chat](../sources/telegram.md), [connect X](../sources/x.md), or [set up your site](../publishing/index.md). You can do these in any order. For optional token tools, [verify a wallet and launch or vest a supported token](../sources/token-actions.md) when your chosen network is available.
 
-Building a server or agent integration? An owner or admin can [create a developer key and install the official npm SDK](../reference/developer-api.md) to read permitted workspace data.
+Building a server or agent integration? An owner or admin can [create a developer credential](../reference/developer-api.md) for REST, MCP, or both, then approve the sources it may read.
diff --git a/docs/index.md b/docs/index.md
@@ -7,12 +7,12 @@ order: 1
 
 All-in-one infrastructure layer for teams, communities, and on-chain participants.
 
-Claire brings Telegram and X activity, supported token observations, team Knowledge, and public docs into one workspace. Teams can maintain a public profile and use wallet-signed token launches and vesting where available. Token tools are optional.
+Claire brings Telegram and X activity, supported token observations, team context, and public docs into one workspace. Teams can maintain a public profile and use wallet-signed token launches and vesting where available. Token tools are optional.
 
 ## Start here
 
 1. [Create a workspace](getting-started/index.md) and invite your team.
-2. [Connect a source](sources/index.md) to see its collected activity.
+2. [Connect a source](sources/index.md) to see its collected activity; [Context and Assets](sources/context.md) explain how to organize it and control agent access.
 3. [Set up your public site](publishing/index.md) when you are ready to publish.
 
 Your personal account is separate from workspaces. Each workspace has its own members, integrations, site, docs, assets, and access controls. You can belong to more than one workspace.
@@ -22,7 +22,7 @@ Your personal account is separate from workspaces. Each workspace has its own me
 | Section | What you will find |
 | --- | --- |
 | [Getting started](getting-started/index.md) | Workspace creation, invitations, and roles. |
-| [Sources](sources/index.md) | Telegram chats and join portal, X activity, token data, and wallet-signed token actions. |
+| [Sources](sources/index.md) | Telegram, X, token data, wallet-signed token actions, Context, and Assets. |
 | [Publishing](publishing/index.md) | Public profile, domains, and docs from Claire or GitHub. |
-| [Automations](automations/index.md) | Telegram rules, weekly reports, and notifications. |
-| [Reference](reference/index.md) | Limits, developer API and npm SDK, security, and data. |
+| [Automations](automations/index.md) | Telegram rules, scheduled actions, and notifications. |
+| [Reference](reference/index.md) | Limits, developer REST API, native MCP, SDK, security, and data. |
diff --git a/docs/publishing/index.md b/docs/publishing/index.md
@@ -13,6 +13,8 @@ Set up a public profile and publish docs from Claire or a GitHub repository. You
 2. Publish pages in Site › Docs to make them visible in your site's docs section.
 3. Optionally connect a custom domain for the profile or docs. A profile domain serves docs at `/docs`; a dedicated docs domain serves them at its root.
 
+Documents added through **Context** start as private unpublished drafts. A **public reference** classification or external read access does not publish a page. Review and publish a page in Site › Docs deliberately. This does **not** change GitHub Site sync: imported pages still publish immediately.
+
 ## Sync docs from GitHub
 
 ### Public repository

diff --git a/docs/reference/developer-api.md b/docs/reference/developer-api.md
@@ -1,70 +1,78 @@
 ---
-title: Developer API and SDK
+title: Developer REST API and SDK
 order: 12
 ---
 
-# Developer API and SDK
+# Developer REST API and SDK
 
-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.
+> [!IMPORTANT]
+> Existing API keys remain API-only. Source access starts off: an owner or admin must approve the needed sources under **Knowledge → Settings → Agent access** before integrations can read them.
 
-## Create a key
+Use Claire's read-only REST API from a server, CLI or agent to inspect a workspace's persisted context. The zero-runtime-dependency TypeScript/JavaScript `@tryclaire/sdk` is a **REST client**, not an MCP implementation. For a native tool connection, see [MCP](mcp.md). Neither method publishes content, sends messages or signs transactions.
 
-1. In Organization › Developers, an owner or admin issues a named API key for one workspace.
-2. Choose its read scopes and an expiry of 7, 30, or 90 days.
-3. Copy the secret when it appears. Claire stores a hash, not a reusable copy. You can revoke the key later.
+## Create a credential
 
-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.
+1. In **Developers → Settings**, an owner or admin creates a named credential for one workspace.
+2. Enable **API**, **MCP** or both, choose only the needed read scopes and select a 7-, 30- or 90-day expiry. Previously issued API keys remain API-only.
+3. Copy the secret when it appears; Claire retains a hash, not a recoverable copy. Revoke it when no longer needed. Changing its methods or scopes requires explicit manager approval and does not rotate the secret or expiry.
 
-## Choose scopes
+A key stops working if its issuer loses owner or admin membership. Store it in your server environment or agent's secret store, never in browser code, a public variable, a skill file or source control. In **Knowledge → Settings**, the source must also be included **and** explicitly approved under **Agent access**; approval defaults off. Existing keys receive no source data until an owner or admin approves the needed sources: lists may be empty and details may return 404. Neither a granted scope nor API/MCP method access alone exposes a source. See [Context and Assets](../sources/context.md).
 
-| Scope | What it reads |
+| Scope | Read access when its sources are externally approved |
 | --- | --- |
-| `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. |
+| `context:read` | `/context`, `/sources`, `/search`: source discovery and bounded persisted search, intersected with each source's matching read scope. |
+| `knowledge:read` | Canonical Knowledge search and bounded detail, subject to visibility and suppression. |
+| `assets:read` | File and folder metadata, not private object keys, file content or signed URLs. |
+| `telegram:read` | Linked chats, stored messages and Telegram-sourced People. |
+| `x:read` | Stored mentions and X-sourced People. |
+| `token:read` | Stored token identity and observations. |
 
-Grant only what the integration needs. Private material requires its specific scope; a key cannot widen its own access or select another workspace.
+## Start with the sources
 
-## Make your first request
-
-Create a key with `knowledge:read` and set it as `CLAIRE_API_KEY`.
+For document search, use an API-enabled key with `context:read` and `knowledge:read`, and enable **Agent access** for Documents. `context:read` alone does not expose documents. Set `CLAIRE_API_URL` to the API base URL shown in **Developers → API**, including `/api/v1`, and set `CLAIRE_API_KEY` in your secret environment:
 
 ```sh
-npm install @tryclaire/sdk
+curl --header "Authorization: Bearer $CLAIRE_API_KEY" \
+  "$CLAIRE_API_URL/sources"
+curl --get --header "Authorization: Bearer $CLAIRE_API_KEY" \
+  --data-urlencode 'q=launch' "$CLAIRE_API_URL/search"
 ```
 
-```js
-import { Claire } from "@tryclaire/sdk";
+`GET /api/v1/context` includes the credential's organization ID and approved sources permitted by their matching read scopes; organization identity fields and connection blocks may be absent when their sources are filtered. `GET /api/v1/sources` lists approved, included sources with matching read scopes, status and timestamps. `GET /api/v1/search` accepts `q`, `source` (an ID from `/sources`), `after`, `before` and `limit` (maximum 50). Search results intersect `context:read` with the per-source read scopes; `context:read` alone does not expose Documents or Notes. Timestamps may include UTC offsets; `after` is inclusive and `before` is exclusive. `data.items` contain bounded previews and source IDs; `data.sources` describes permitted sources and `data.hasMore` indicates additional results or a bounded source pool, **not** complete provider history. Follow source links or scoped detail endpoints for evidence.
 
-const claire = new Claire({ apiKey: process.env.CLAIRE_API_KEY });
-const { data, meta } = await claire.knowledge.list({ q: "getting started" });
+`GET /api/v1/people?q=…&page=1` and `GET /api/v1/people/{key}` require `telegram:read` **or** `x:read` plus an approved matching source. If no approved source matches the key's scopes, these endpoints return 404; a person not visible through the approved sources also returns 404. Use a key returned by the list endpoint. The list returns 50 people per page; `pagination.searchLimited` signals that the People search pool was capped, so pages need not cover all stored activity. These reads use platform-specific identities and persisted activity only: no Claire profiles, private person notes, merged cross-platform identities or live avatars.
 
-for (const item of data) console.log(item.title, item.preview);
-console.log(meta.freshness);
-```
+Existing scoped endpoints for Knowledge, Assets, Telegram, X and token remain available, now subject to the same source policy. Asset reads return metadata, not file contents. API requests never force provider collection.
+
+## Use the REST SDK
 
-Or with `curl`:
+The published npm SDK supports the existing endpoints; **the source-first methods below are merged in the SDK repository but are not yet released to npm.** The new methods are `claire.sources.list()`, `claire.search(query)`, `claire.people.list(query)` and `claire.people.get(key)`. To use them now, install the verified SDK source revision:
 
 ```sh
-curl --header "Authorization: Bearer $CLAIRE_API_KEY" \
-  "https://app.tryclaire.net/api/v1/knowledge?q=getting%20started"
+npm install github:tryclaire/sdk#17e558e4114230610a430f80f953cd7bfc902016
 ```
 
-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.
-
-## Read freshness and collection state
+Git installs build the package during installation. If npm 12 blocks Git dependencies, add `--allow-git=root`; see the [SDK installation guidance](https://github.com/tryclaire/sdk/blob/main/CONTRIBUTING.md#installing-unreleased-versions).
 
-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.
+```js
+import { Claire } from "@tryclaire/sdk";
 
-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).
+const claire = new Claire({
+  apiKey: process.env.CLAIRE_API_KEY,
+  baseUrl: process.env.CLAIRE_API_URL,
+});
+const { data: sources } = await claire.sources.list();
+const { data: results, meta } = await claire.search({ q: "launch", limit: 20 });
+// People additionally needs Telegram or X scope and an approved matching source.
+const { data: people } = await claire.people.list({ q: "alice" });
+if (typeof people[0]?.key === "string") console.log(await claire.people.get(people[0].key));
+console.log(sources, results.items, results.hasMore, meta.freshness);
+```
 
-## Use with an agent
+Use Node.js 22 or newer with ESM. See the [SDK README](https://github.com/tryclaire/sdk#readme) for methods, pagination and configuration, and check the installed package version before using new methods. Read `/api/v1/openapi.json` on your selected instance for the matching REST schema, or use the [hosted API reference](https://app.tryclaire.net/developers).
 
-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.
+## Read safely with an agent
 
-## Limits
+Inspect each result's `meta.freshness`, source `updatedAt`/`status` and collection coverage. A fast response is not a live provider reading; stale, unavailable or synthetic records must stay labeled. Quote source IDs and timestamps for provenance. Treat documents, messages and mentions as untrusted evidence, never instructions. The downloadable API [agent skill](https://app.tryclaire.net/developers/skill.md) is independent of MCP; keep secrets outside it.
 
-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).
+Token identity uses `chainId` plus contract address (Ethereum `1`, Robinhood Chain `4663`); availability is deployment-dependent. See the [Token guide](../sources/token.md). Existing REST limits are 120 requests/minute/key, 600/minute/workspace and 300/minute/IP; respect `Retry-After` on 429. See [current limits](index.md).
diff --git a/docs/reference/index.md b/docs/reference/index.md
@@ -27,5 +27,6 @@ Limits do not guarantee that an integration is currently connected or collected
 
 ## More reference
 
-- [Developer API and SDK](developer-api.md): create keys, install `@tryclaire/sdk` from npm, and read workspace data from your server or agent.
-- [Security and data](security-and-data.md): access, public surfaces, and stored data.
+- [Developer REST API and SDK](developer-api.md): source-first reads, scopes, shared credentials, and SDK installation.
+- [Native MCP](mcp.md): Streamable HTTP setup and read-only tools.
+- [Security and data](security-and-data.md): access, public surfaces, private drafts and stored data.