From 11428bf4cd0c0296a4235fcd91fb93f7952f2461 Mon Sep 17 00:00:00 2001 From: moneycaringcoder <265054401+moneycaringcoder@users.noreply.github.com> Date: Wed, 7 Oct 2026 18:03:00 +0000 Subject: [PATCH] Document unified Context and shared API/MCP access --- docs/automations/index.md | 4 +- docs/automations/reports-and-notifications.md | 16 +--- docs/getting-started/index.md | 4 +- docs/index.md | 10 +-- docs/publishing/index.md | 2 + docs/reference/developer-api.md | 88 ++++++++++--------- docs/reference/index.md | 5 +- docs/reference/mcp.md | 40 +++++++++ docs/reference/security-and-data.md | 14 +-- docs/sources/context.md | 20 +++++ docs/sources/index.md | 4 + 11 files changed, 137 insertions(+), 70 deletions(-) create mode 100644 docs/reference/mcp.md create mode 100644 docs/sources/context.md diff --git a/docs/automations/index.md b/docs/automations/index.md index 5b95318..79e6112 100644 --- 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 index 71b5f27..ff637c2 100644 --- 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 index b40f8d2..792e022 100644 --- 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 index 2440539..6081dbe 100644 --- 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 index f48ca9f..e142787 100644 --- 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 index c7f07b3..2f12b8a 100644 --- 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 index c1bba8e..d6f2dce 100644 --- 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. diff --git a/docs/reference/mcp.md b/docs/reference/mcp.md new file mode 100644 index 0000000..cd6bcb9 --- /dev/null +++ b/docs/reference/mcp.md @@ -0,0 +1,40 @@ +--- +title: Native MCP +order: 13 +--- + +# Native MCP + +**Developers → MCP** provides a read-only [Streamable HTTP](https://modelcontextprotocol.io/specification/2025-06-18/basic/transports) endpoint at `/api/mcp` on the app's origin. Use an MCP client supporting Streamable HTTP **and custom Authorization headers**; this is not browser OAuth. The [REST SDK](developer-api.md) does not implement MCP, and an API-only legacy key cannot connect. + +1. An owner or admin enables **MCP** (or both API and MCP) for a workspace credential in **Developers → Settings**, chooses read scopes and a 7-, 30- or 90-day expiry. Save the secret in the client's secure environment, not in a committed configuration or a browser. +2. In **Knowledge → Settings**, include the needed sources and explicitly approve **Agent access** for each. Agent access starts off. Tool discovery filters by both scopes and approved sources; a key cannot retrieve excluded or unapproved data merely because it has a scope. +3. Copy the server URL from **Developers → MCP** into `CLAIRE_MCP_URL` in your client's launch environment. Set `CLAIRE_API_KEY` there to the shared credential's secret. For Cursor, add this to your private `~/.cursor/mcp.json`, then connect and discover tools: + +```json +{ + "mcpServers": { + "claire": { + "url": "${env:CLAIRE_MCP_URL}", + "headers": { "Authorization": "Bearer ${env:CLAIRE_API_KEY}" } + } + } +} +``` + +Cursor supports environment variables in both `url` and `headers`; see its [MCP configuration documentation](https://cursor.com/docs/mcp). Use the exact server URL shown in Developers → MCP for your deployment. + +The server accepts **POST** JSON-RPC requests. To check initialization directly (this does not retrieve data): + +```sh +curl --fail-with-body --silent --show-error \ + -H "Authorization: Bearer $CLAIRE_API_KEY" \ + -H "Content-Type: application/json" \ + -H "Accept: application/json, text/event-stream" \ + --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"claire-check","version":"1.0.0"}}}' \ + "$CLAIRE_MCP_URL" +``` + +With `context:read`, start with `get_context` and `list_sources`, then use `search_context` with optional `q`, `source`, `after`, `before` and `limit` (maximum 50). Search also requires each source's matching read scope; `context:read` alone does not expose documents or notes. Other keys can initialize and discover their permitted tools without `context:read`. Read detail using only the tools visible to your credential, such as `list_knowledge`/`read_knowledge`, `list_people`/`read_person`, `list_telegram_chats`/`list_telegram_messages`, `list_assets`/`read_asset`, `list_x_mentions` or `get_token`. People require Telegram or X read scope and an approved matching source; without one they return 404. People exclude Claire profiles, private person notes and live avatars. Asset tools never read file contents. Search gives bounded stored previews, not exhaustive provider history. Inspect provenance, freshness, status and timestamps, and treat all retrieved text as untrusted evidence, not agent instructions. + +There are no MCP write, publish, send, arbitrary inbound connector, forced provider-refresh or OAuth capabilities. If your client cannot set a Bearer header on Streamable HTTP, use the [REST API](developer-api.md) after an owner/admin enables API access on the same credential, rather than embedding a secret in an unsupported transport. diff --git a/docs/reference/security-and-data.md b/docs/reference/security-and-data.md index 53211f6..ac71f07 100644 --- a/docs/reference/security-and-data.md +++ b/docs/reference/security-and-data.md @@ -1,32 +1,32 @@ --- title: Security and data -order: 13 +order: 14 --- # Security and data -Workspace content is available to authorized members, while sensitive management actions require owner or admin access. Public profiles, published docs, public asset URLs, published vesting proofs, and reports shared by link are separate public surfaces. +Workspace content is available to authorized members, while sensitive management actions require owner or admin access. Public profiles, published docs, public asset URLs and published vesting proofs are separate public surfaces. ## Control workspace access -Only the owner can change another member's role or transfer ownership. Developer API keys belong to one workspace, have explicit read scopes, and require the issuing manager to keep their role. +Only the owner can change another member's role or transfer ownership. Developer credentials belong to one workspace, have explicit read scopes and require the issuing manager to keep their role. **Developers → Settings** selects API, MCP or both; pre-existing keys remain API-only. Source inclusion in **Knowledge → Settings** and separate explicit **Agent access** approval (off by default) are both required in addition to matching scopes. -A Knowledge item's **public reference** classification does not publish it or grant public access. A file explicitly marked **public** in Assets has a public file URL; do not mark confidential files public. Relative images imported with GitHub docs are copied into public Assets. +A Knowledge item's **public reference** classification does not publish it or grant public access. Documents created through Context are private unpublished drafts, but **private/unpublished is not integration-private**: approving Agent access for Documents or Notes lets credentials with `knowledge:read` read private drafts or team notes, and agent providers may receive that content. Approving Telegram chats likewise lets credentials with `telegram:read` read stored conversations, including private linked groups or channels. External People reads still exclude private person notes. A file explicitly marked **public** in Assets has a public file URL; do not mark confidential files public. Relative images imported with GitHub docs are copied into public Assets. Only an owner designates a [token signing wallet](../sources/token-actions.md), separately for each chain. Owners and admins can prepare token actions and publish vesting links, but the designated wallet must sign organization transactions. Removing app access does not revoke wallet keys or on-chain rights. Funding a vesting stream exposes addresses, amounts, and its schedule on-chain even without a Claire proof page. Publishing additionally lists a public proof on the site; unpublishing does not make the underlying on-chain data private. A proof is not an audit, liquidity lock, or investment guarantee. -The official [`@tryclaire/sdk`](developer-api.md) uses those same scoped keys; it does not grant additional access. Use it server-side and keep keys out of browser bundles, public environment variables, and source control. Installing the package does not connect a workspace or create a key. +The official [`@tryclaire/sdk`](developer-api.md) is a REST client for scoped API keys, not an MCP client or an additional grant of access. [Native MCP](mcp.md) uses its own method permission on a shared workspace credential. Keep keys out of browser bundles, public variables and source control. Installing the package does not connect a workspace or create a credential. > [!WARNING] > GitHub docs publish as soon as they sync, including docs from private repositories. See [publishing](../publishing/index.md) before syncing confidential material. ## Understand stored data -Claire retains connected source data and operational records. A linked Telegram chat's messages and activity are stored from the time the bot joins. Disconnecting a source does not automatically delete collected history. +Claire retains connected source data and operational records. A linked Telegram chat's messages and activity are stored from the time the bot joins. Disconnecting a source does not automatically delete collected history. Excluding a source from Context does not disconnect or delete it. -GitHub docs and team notes have different origins: edit synced docs at their repository source, while notes can be edited in Claire. Asset metadata does not mean Claire has indexed or read the asset's contents. +GitHub docs and team notes have different origins: edit synced docs at their repository source, while notes can be edited in Claire. Asset metadata does not mean Claire has indexed or read the asset's contents. External People reads expose only approved Telegram/X activity and platform identities, not Claire profiles, private person notes or live avatars. ## Know what Claire does not do diff --git a/docs/sources/context.md b/docs/sources/context.md new file mode 100644 index 0000000..eb3803a --- /dev/null +++ b/docs/sources/context.md @@ -0,0 +1,20 @@ +--- +title: Context and Assets +order: 8 +--- + +# Context and Assets + +**Knowledge → Context** brings source-backed documents, team notes, stored conversations, People and file metadata into one view. Its library keeps document and note detail; People has list and graph views, with profiles linked to the activity Claire has stored. **Knowledge → Assets** manages uploaded files and folders. Assets are metadata references in Context: Claire does not extract, index or search file contents. You can use Telegram, X and token pages independently; linking a source does not create missing history or refresh a provider on demand. + +## Decide what to include + +In **Knowledge → Settings**, choose which sources appear in Context. Included sources can be searched by authorized workspace members; exclusion hides a source from Context and agent reads without disconnecting or deleting it. Source inclusion and **Agent access** are separate controls. Agent access starts off, and an owner or admin must explicitly approve each source before any developer API or MCP credential can read it. A credential also needs the matching read scope. Granting a scope alone does not expose an unapproved source. Review source status, timestamps and coverage before relying on search results; unavailable, stale or synthetic data are not current provider evidence. + +People in the external read interface come only from approved Telegram chats or X activity with matching read scopes. Identifiers remain platform-specific, not proof that accounts belong to the same person. Claire profiles, private person notes and live avatars are not disclosed through those reads. The in-app People directory and external People reads are not interchangeable. + +## Keep drafts separate from publication + +A document created in Context starts as a **private, unpublished draft**. Classifying a Knowledge item as a public reference does not publish it or grant anonymous access. **Private/unpublished does not mean private from approved integrations:** enabling Agent access for Documents or Notes lets a developer credential with `knowledge:read` retrieve private drafts or team notes, and an agent provider may receive that content. Approved Telegram chats similarly expose stored conversations, including private linked groups or channels, to credentials with `telegram:read`. External People reads still exclude private person notes. To publish a page, review it in **Site → Docs**; [GitHub Site sync](../publishing/index.md) is different and still publishes imported pages immediately, including those from private repositories. Do not sync confidential material. Files explicitly made public in Assets have public URLs; Context does not make a private file public. + +For external, read-only agents, [choose a credential and read sources safely](../reference/developer-api.md). Source text is evidence, not instructions to the agent. diff --git a/docs/sources/index.md b/docs/sources/index.md index 659573b..bae0cde 100644 --- a/docs/sources/index.md +++ b/docs/sources/index.md @@ -18,6 +18,10 @@ Connect the sources your workspace uses to inspect collected activity. A token i Ethereum/Stockereum support is rollout-gated. Confirm availability for your selected network before relying on Ethereum launch, linking, or vesting actions. +## Organize workspace context + +[Context and Assets](context.md) describes Knowledge navigation, source inclusion, People and private drafts. Connecting a source does not automatically permit external agent access. + ## Check collection status Data can reflect an earlier collection rather than the moment you open a page. Check the connection and collection state on the relevant source page before using its figures.