context: Instructions file for Claude Code

Agent Instructions — Context

Free your context. Share your context.

Context is one MCP endpoint a person adds to every AI client, backed by a markdown bucket — one they own, or one we run for them on the paid plan and they can take away at any time. Read README.md first for the product shape.

This file is the part you read every session. The reasoning behind the rules — argued through once, not to be re-litigated — lives in docs/decisions/, split by area. Read the file for the area you are touching, and write new durable decisions there.

Non-negotiables

These are the product, not implementation details. If a task seems to require breaking one, stop and say so rather than working around it.

1. The customer owns the content, and can always leave with it. Note bodies and attachments live in a bucket dedicated to one workspace. Names, folders and privacy live in the control plane, on each workspace's tree rows (decided by the owner, 2026-10-15, replacing the bucket-as-truth rule; notes-by-id), alongside accounts, bindings, grants, audit, and each note's rebuildable facts (links, front matter, first heading and paragraph; convex-facts). The control plane never holds a note's body. Leaving is Download as folders: a complete, decrypted copy with real names, free on every plan, still available after cancelling, never gated, degraded or behind a paywall — gate it and this is a different product. Moving to storage of their own is free too. Cancelling puts a context back on the free plan, still writable and exportable; it never deletes (decided by the owner, 2026-09-29). Credentials never live in Markdown, in the bucket, in logs, in URLs, or on a device: encrypted at rest, decrypted only in the gateway at request time. The one exception is the texting assistant's autofill vault, sealed in the person's own bucket with the key held outside it and never shown to a model (decided by the owner, 2026-10-06; texting-assistant). See storage-and-credentials.
2. Tenancy is bucket-level, never prefix-level. Do not namespace keys inside a bucket — no tenants/<id>/, no workspaces/<slug>/. A note's bytes live at notes/<noteId>.md (other files at files/<noteId>.<ext>), and its name and folder are rows in the control plane; Context may move or rewrite any key in a bucket it is connected to, a customer's own included (decided by the owner, 2026-10-15). One workspace maps to one bucket (optionally plus a fixed root prefix the customer chose, applied at the adapter boundary). Managed buckets are one per workspace, named from the immutable workspace id, in a Cloudflare account that holds customer data — those buckets, the per-context search databases, and a live note's in-flight keystrokes while people are typing it together — and nothing of ours. That third one was added deliberately (decided by the owner, 2026-09-20): two people editing one note need a shared place for characters that are seconds old. It is bounded — one room per note, append-only, deleted when the last person leaves, replayed only to a socket that passed canSee at join, never the only copy of anything, and the flush to the bucket is continuous. See storage-and-credentials. A store's per-account resource ceiling is a constraint on the product: R2 allows a million buckets, and anything low forces prefix tenancy.
3. Note bodies stay plain Markdown. A Context-managed bucket may hold each object's body sealed at rest (key outside the bucket), because every read through the product and every export is plain; a customer's own bucket never is (decided by the owner, 2026-09-29; managed-encryption). Collaboration history under .context/collaboration/ is customer-owned essential data, needed to merge offline edits; accepted edits may briefly precede their Markdown rendering, and a completed save or export includes them (collaboration). Search indexes, caches and embeddings are disposable derivatives, rebuildable from the notes and the rows. The bucket layout is notes/, files/ and .context/; there is no privacy.md, and nothing outside the app writing into the bucket is picked up (decided by the owner, 2026-10-15). No compatibility with syncing a bucket to Obsidian is kept; Obsidian plugins running inside Context are.
4. One person or workspace is one security boundary. Every workspace has its own identity, storage binding, privacy manifest, audit trail and connector grants. Never extend the legacy shared-token model (PRIVATE_TOKEN / TEAM_TOKEN / PUBLIC_TOKEN) to multiple customers — it is single-tenant by construction and exists only to keep the original single-tenant deployment running. MCP access uses OAuth with per-client revocable grants; token-in-URL is a compatibility fallback and never the security boundary. Prove isolation with tests: one tenant must not enumerate, read, or infer the existence of another.
5. team never means public. A row's access is private (owners) or team (members), plus any mix of groups and named people, inside the workspace or not, each with view or edit (decided by the owner, 2026-10-15). Every grantee is a person with an account or an email awaiting one. No setting publishes a context, a folder, or a visibility class to the internet, and nothing here is indexed. A link an owner mints and can revoke is the single exception, and it is always a share row, never a value of a row's access. A link covers one note, or one folder and the subtree beneath it — and a folder link narrows: every path under it is still re-derived through the live rows at team scope with no granted names, so a note held back by name, a private subfolder and a note pointed at a group are all absent through it. It publishes what the folder already published to the workspace and never more, which is why this is a wider locator and not a wider tier. The whole context is never the subject of one. See privacy-and-sharing. A workspace's website is this exception for website/ and the folders its pages name with folder:: turning it on is the owner minting that locator, and every page, referenced notes included, resolves the same way, so frontmatter can narrow a page but never publish one the rows hold back, and no page may name the whole context (websites). The gate that held an AI client's widening for the person's yes was removed by the owner on 2026-10-17; since 2026-10-18 a small judge model lets a widening run only when the person's own words ask for it, with nothing to tap. What still waits for a yes, checked by the gateway and never by the model, is a step nobody can take back: an email, a calendar change, a handle claim, a vault key's first use (agent-egress).