---
title: Cornerstone — AI operating guide
version: 1.23.0
updated: 2026-11-16
canonical_url: https://cornerstone.instructedintelligence.com/mcp/prompt.md
version_url: https://cornerstone.instructedintelligence.com/mcp/prompt/version
---

# Cornerstone — AI Operating Guide

You have the **`cornerstone`** MCP server available. Cornerstone is a business-knowledge substrate: it holds a company's operating knowledge (rules, decisions, processes, references, concepts), the **work history** behind them, and a **situational record** of the people and organisations the business deals with — all retrieval-optimised so you only ever see the pieces relevant to the task.

**You are the intelligence. There is no server-side LLM.** Cornerstone's read tools retrieve; its extraction tools let *you* read a document, reason, and stage structured knowledge yourself. Every answer is deterministic and auditable.

Read this guide once at the start of a session, then work from it. It covers all four modes: **retrieval**, **extraction**, **work history (episodic)**, and the **situational record (transcript layer)**.

---

## Staying current

This guide is **versioned**: see `version:` in the frontmatter above.

- **Cannot open a URL?** Call the `get_guide` tool: it returns this guide, with no tenant needed.
- The MCP server reports the current guide version in its connect-time **instructions**. If that version is newer than the one you last read, **re-read this guide** — behaviour or tools may have changed.
- Cheap check any time: `GET https://cornerstone.instructedintelligence.com/mcp/prompt/version` → `{"version": "…", "updated": "…"}`.
- Full guide (curl or browser): `GET https://cornerstone.instructedintelligence.com/mcp/prompt.md`. The older `/mcp-prompt.md` and `/mcp-prompt/version` still answer, with the same content.
- Which build is running: `GET https://cornerstone.instructedintelligence.com/health` → `{"status", "service", "version", "revision", "built"}`. The release `version` there is the server's, separate from this guide's own version.
- The **Changelog** at the bottom lists what changed between versions, so you can decide what to re-learn without re-reading the whole thing.

---

## Tenancy — always pass `tenant`

Every data tool takes an optional **`tenant`** argument (the id of the knowledge base to act in).

### Tenant or project? Almost always project.

Two boundaries, and they answer different questions. Choosing wrong is the most common structural mistake made here, and only one of the two is reversible.

| | Answers | Reversible | Use for |
|---|---|---|---|
| **Tenant** | *who may see this* | **No** — there is no merge or move | a separate org, department, client, or legal entity |
| **Project** | *what this is about* | Yes — it is a field | a workstream, product, or engagement inside one of those |

**Default to a project.** Retrieval spans every project you can see inside a tenant, so knowledge in sibling projects **compounds** — a question about one workstream can be answered by what was learned in another. Split the same knowledge across tenants and it fragments permanently: each new tenant starts empty, answers nothing, and stays that way until someone fills it.

**A new tenant is a one-way door.** There is no merge, no move, no reparent. A tenant created by mistake can only be abandoned or shredded — its knowledge cannot be folded into where it should have lived. So create one only when the answer to *"must these two bodies of knowledge be invisible to each other?"* is genuinely yes.

If someone asks for "a knowledge base for project X" and X belongs to an organisation that already has a tenant, **make it a project in that tenant** and say why.


- `list_tenants` — discover the tenants your credential can reach (id + name + role + `purpose`). A person-scoped key spans several; a pinned key sees one. `purpose` is `primary` for an ordinary knowledge tenant and `method` for a **ways-of-working tenant**: the company's method, which members read and only its owners change. Don't write day-to-day knowledge into a `method` tenant.
- Pass `tenant=<id>` on every subsequent call. If you omit it and your key spans several tenants, the tool replies with the list so you can retry with the right one.
- `create_tenant(name, purpose?, default_member_role?)` — spin up a new **isolated** knowledge base (requires a person-scoped key). Read the decision table above first: this is irreversible in the sense that matters, and a project is usually what was wanted. Pass `purpose="method"` when the tenant is a company's ways-of-working tenant: it makes people added later **viewers** by default, because a method tenant where every member is an editor lets any member's AI session rewrite the company's method. Leave `default_member_role` out unless you have a reason to override that. The result reports `encrypted`: encryption at rest is switched on as part of the create wherever the deployment has an encryption root, so there is no separate "enable encryption" step to remember, and if it cannot be switched on the tenant is not created.
- `delete_tenant(tenant_id, confirm_tenant_id)` — **recoverable** delete of a tenant you own (data retained; undo with `recover_tenant`). Echo the id in `confirm_tenant_id`. Owner-only; the safe cleanup for a duplicate or mistaken knowledge base.
- `recover_tenant(tenant_id)` — undo a `delete_tenant` (restores the tenant + its data).
- `shred_tenant(tenant_id, confirm_tenant_id)` — **irreversible**: permanently destroy an already-`delete_tenant`'d tenant and all its data. Two-step by design (delete, then shred), each id-confirmed.

**Projects** — the normal way to organise work inside a tenant, and the boundary you should reach for first (see the decision table above). `list_projects(tenant)` lists them with their keys; `create_project(tenant, key, name)` makes one. A tenant with one project is usually a tenant whose owner did not know projects existed.

*Targeting a project* — every argument below takes a **UUID or a key**, is validated against your accessible set, and is **rejected, never silently redirected**, if it is outside it:

- **Writes** — `add_document`, `record_episode`, `stage_observation`, `promote_note`, `promote_episode` and `reverse_decision` all take `project`. Omit it and the write lands in **your default write project**: the one an owner/admin set for you (`set_member_default_project`), else the tenant's default project, which is usually shared with every member. A tenant can **require a project on every write** (`set_tenant_settings require_project_on_write=true`); then a write that names none is refused, except an update of a document that already exists at that path. Resolve the project from the work itself — the ticket's project, the repo in hand — rather than relying on a default.
- **Reads** — `query` and `get_context` take `project` to narrow to ONE. **Omit it in the normal case:** reading across every project you can see is what makes knowledge compound. Narrow only when you deliberately want to exclude sibling workstreams. Narrowing can never widen — an unknown or out-of-access project searches nothing and says so in `coverage.hint`, rather than quietly answering from the wider scope.

*Renaming a project* (owner/admin only, audited): `update_project(project_id, confirm_key, name, key)`. **A project's name and key always change together** — neither can change alone, so people and the system never call it different things. The default project keeps the key `default`; only its name can change. `description` and `color` can be changed on their own. The old key keeps working for a changeover (`changeover_days`, default 30), and every result from a call that uses it begins with a `NOTICE:` naming the new key — **when you see one, use the new key from then on and update any instruction file that names the old one.** After the changeover the old key is refused with an error naming the new one. A retired key never names another project.

*Removing a project* (owner/admin only, audited): `delete_project(project_id, confirm_key)` deletes an EMPTY project and nothing else. If it still holds anything it is refused and tells you what; move that to another project first (`plan_move` then `apply_move`, same tenant as the destination), then delete. Never the default project.

*Membership* (owner/admin only, audited): `list_project_members(project_id)`, `add_project_member(project_id, email, role?)`, `remove_project_member(project_id, user_id)`. A tenant member who isn't in a project can't see that project's knowledge — so if someone reports "I ingested documents and can't see them", check `list_project_members` and add them.

**Members** (owner/admin only, audited) — `list_tenant_members(tenant)` answers "is this person actually a member?"; `add_tenant_member(tenant, email, role?)` provisions + adds by email and joins them to the tenant's default project with **the tenant's default member role** (editor unless the tenant was set otherwise — a ways-of-working tenant is set to viewer, so people added there can read but not write; a role they already hold is left alone, so use `add_project_member` to change it); `set_tenant_member_role(tenant, user_id, role)` (can't demote the last owner); `remove_tenant_member(tenant, user_id)` (also removes their project roles). **Standing up a client tenant is one flow: `create_tenant` → `add_tenant_member`** — don't stop at create.

**Tool-owned processes** — when you are a tool registering something you RUN (a room, a workflow, a job), not distilling a fact from a document: `upsert_process(external_key, name, subtype?, description?, steps?, entry_points?, exit_points?, project?)`. The `external_key` is yours (e.g. `council:room:<uuid>`); the same key always updates the same entity, name included. It is live when the call returns. Facts that come OUT of it (decisions, references) still go through `add_document` → `stage_observation`, with the evidence in the document; then link them with `create_relationship` from the process (`produced`). `find_related` on the process lists them.

**Machine access** (owner/admin only, audited) — when another tool (not a person) needs to read a tenant, give its machine identity a grant rather than a `cs_` key: `list_machine_access(tenant)` shows who has it and which issuers can be named; `grant_machine_access(tenant, issuer, subject, label)` adds one; `revoke_machine_access(tenant, grant_id)` ends it. It is read-only and limited to that tenant.

**Access control** (owner/admin only, audited) — restrict who can see documents/entities without touching the database. `describe_access(tenant, {document_id | entity_id | path_prefix})` is the preflight ("who can see this?"). `grant_access` / `revoke_access` take a `document_id` or a `path_prefix` and a principal (`user|group|project|tenant` + UUID); `replace=true` swaps the whole ACL for just this grant — the "restrict `finance/` to one named user" case — and recomputes the derived-entity ACLs automatically. A `path_prefix` call is a **standing rule**: it is remembered, and a document added, renamed or restored under that folder later carries it without anyone acting (most specific folder wins; the folder is matched whole, ignoring case). Check `standing_rule` in the result, and read the `note`: it tells you when nothing is under the folder yet, which usually means a typo. Removing the last grant makes the document invisible (default-deny), never a silent open. A count never discloses restricted content: every coverage/total is ACL-scoped.

---

## The knowledge model — six entity types

Each is a first-class record with typed fields, freshness, relationships, and back-references to its source document.

| Type | What it is | Promotable? |
|---|---|---|
| **document** | Raw source (markdown, etc.). The *input*, created with `add_document`. | **No** — it's the source, never a promotion target |
| **concept** | A named idea / definition / principle | Yes |
| **decision** | An ADR: context, options, outcome | Yes |
| **rule** | A business/operational rule | Yes |
| **process** | A named sequence of steps | Yes |
| **reference** | An external authority (regulation, standard, wording) | Yes |

> **The single most common mistake:** staging with `proposed_type: document`. Documents are raw sources — you cannot promote one into a fact. **`proposed_type` must be one of `concept | decision | rule | process | reference`.** Staging or promoting anything else returns a `422` telling you exactly this.

**Payload fields per type** (the JSON you pass as `payload` when staging):
- **concept** — `{name, definition, synonyms[], tags[]}`
- **decision** — `{title, context, outcome, consequences, status, decision_date}`
- **rule** — `{name, condition, outcome, scope, severity}`
- **process** — `{name, description, steps[]}`
- **reference** — `{title, citation, kind, summary, url}`

Every entity carries a **lifecycle** (`canonical` · `stale` · `superseded` · `deprecated`). Retired entities drop out of retrieval; `supersede(type, old_id, new_id)` retires an entity in favour of a newer one so current facts win. The **lineage stays readable** (CORN-234): a retired entity is still fetchable with `get_entity` and carries `superseded_by` → its replacement; `find_related` on the replacement returns the reverse `supersedes` edge; and `list_by_type(type, lifecycle=superseded)` enumerates what's been retired — so "what did we used to think, and what changed our mind" is answerable. `sweep_staleness` flags facts whose source document changed after distillation or that aged past the confirm window (returns counts); `list_stale` pulls the flagged worklist itself (each with a `source_changed` | `unconfirmed` reason), which you resolve by re-distilling, confirming, or `supersede`.

**When a settled DECISION changes, reverse it in ONE step — don't just leave an episode.** `reverse_decision(supersedes = the prior decision's id or exact title, title = the new position, outcome, episode_body)` records the reversal as work history, creates the **new canonical decision**, AND **supersedes the old** — atomically — so the fresh position *wins* retrieval. Recording a reversal only as an episode is the classic decay: the old decision stays `canonical` and keeps being served to later sessions as if current, and they act on the wrong answer (CORN-276/277). If you catch yourself writing *"we changed our mind about X"* into an episode, that is the signal to call `reverse_decision` instead.

---

## Mode 1 — Retrieval (answering questions)

**Reach for `get_context` first.** One call returns synthesis-ready context: the relevant typed **entities** (facts, with their fields), grounding **passages**, deduplicated **citations**, and a bounded **`work_history`** slice — token-budgeted.

```
get_context(tenant, text="what is our refund policy?", entity_types?, exclude_stale?, budget_chars?, depth?)
```

**Depth: normal first, deep once if needed.** Call at the default depth. If the pack does not contain the answer and `deeper_available` is `true`, call **once** more with `depth="deep"` before concluding the answer is not documented. Deep searches about 8× wider and returns a pack of up to ~35k tokens, so never start deep and never go further than one deep call. (Measured, CORN-338: this recovers most of what deep-on-every-question gains, for about a fifth of the tokens.) A deep pack that still lacks the answer, or `no_strong_match` on the deep call, means it is genuinely not documented.

**Honour `no_strong_match`.** Every answer carries it. When `true`, nothing cleared the confidence floor — **say you lack solid grounding rather than answering from weak context.** Do not invent. Confidence is *entity-anchored*: a topical typed entity must back an answer; document passages ground an answer but never confer confidence on their own. (This holds for the semantic lane too — a *close* passage still only grounds.)

**Heed `possibly_overtaken`.** `get_context` flags a returned **canonical decision** that a *newer* related episode postdates (CORN-279) — the recorded position may have been reversed in later work but never superseded. When you see it, do **not** simply prefer the entity on lane order: read the cited episode and verify the current position before acting. If it turns out to be a reversal, capture it with `reverse_decision` so the next session doesn't hit the same trap.

When `no_strong_match` is `true`, the response also carries a `coverage` hint (counted over documents **you** can see, so it never discloses restricted content). Read it before concluding "nothing here": `visible_docs > 0` with `distilled: 0` means the corpus is present but **not distilled yet** — that is your own next action, not an empty tenant. Run `distillation_coverage()` to see the backlog, then distil the relevant source (`get_document → stage_observation → promote_observation`) so the next ask is answered. `coverage.hint` spells out which case you're in.

**Ask the repo for code, ask Cornerstone for position.** Cornerstone holds what the org has *decided* and *how it operates* — decisions, rules, processes, definitions. Code-level facts (an exact exclusion list, an env-var default, the current line in a config file) belong in the repository: they drift from the code the moment they're copied here. So a decline on a *code-level* question is correct behaviour, not a gap — go read the code. Operational *position* facts (deploy discipline, where a secret lives, why a build is token-free) DO belong here — if one is missing, that's a distillation gap to fill, not a class Cornerstone opts out of. (Measured: CORN-195.)

Other retrieval tools:
- `query(text, entity_types?, min_score?)` — ranked entities + passages with citations, when you want raw results rather than a packed answer.
- `get_entity(type, id)` — one entity by id, with citations.
- `list_by_type(type, name?, lifecycle?)` — list entities of a type; `lifecycle=superseded` reads back what's been **retired** (also `canonical|stale|deprecated|orphaned`; omit for every state). CORN-234.
- `list_stale` — the facts currently flagged stale (needing review), across all types; the read counterpart to `sweep_staleness`.
- `find_related(type, id, depth?)` — traverse relationships outward.

**Semantic lane:** when enabled, retrieval also matches by *meaning* (an embedding model, not a reasoning LLM), so a question can find an answer that shares no words with it. It's additive and never replaces the lexical lanes — you don't call it directly; `get_context`/`query` use it automatically. Where the deployment enables semantic passages (CORN-336), document **passages** are matched by meaning too, so a detail that was never distilled into a fact can still come back as grounding. Passages still never confer confidence.

**Withdrawn documents are excluded.** A document that declares itself superseded, withdrawn or no longer applicable near its top is not served, and neither are the facts distilled only from it (CORN-315/337). If you are asked what a withdrawn document *said*, open it directly with `get_document`.

---

## Mode 2 — Extraction (teaching Cornerstone)

Turn raw sources into typed, queryable entities. **You** are the extractor — read and propose; a human (or trusted AI) reviews before promotion. No server LLM.

```
1. add_document(tenant, source_path, content)     # load a source (idempotent by path)
2. get_document(tenant, id)                        # read its full text
3. stage_observation(tenant, proposed_type, subject, payload, source_ref=<doc id>, confidence)
4. list_observations(tenant, status="pending")     # review the queue, a page at a time
5. promote_observation(tenant, id)                 # → live typed entity   (or reject_observation)
```

- `stage_observation` — `proposed_type` (concept|decision|rule|process|reference — **not document**), `subject` = the entity's name/title, `payload` = the JSON fields for that type (see above), `source_ref` = the document id it came from. An invalid `proposed_type` is rejected at this step with a `422`.
- **Confidence gate (CORN-287).** Where a deployment auto-promotes on stage, an observation whose `confidence` is **below the deployment's floor** is HELD `pending` for review rather than promoted — the response returns `held:true` with a reason. Always set a real `confidence` on a machine-distilled observation so low-confidence extractions are caught by the gate; a deliberate stage that omits it (0) is treated as "no signal" and still auto-promotes. `reject_observation` only clears a **pending** proposal — it will not retract an already-promoted fact (that returns `409`; supersede/deprecate the entity instead).
- Upsert is by natural key (e.g. `(tenant, project, name)`), so re-distilling a changed document updates the entity instead of duplicating it.
- `distillation_coverage()` — how much of the corpus is distilled; `undistilled[]` is your backlog.
- `list_gaps()` — real questions that returned `no_strong_match`, ranked by frequency — the demand-driven "what to distil next" list.
- `redact_question(question)` — a data steward blanks a question's wording wherever it is held (the audit trail behind `list_gaps`, and the delivery records), e.g. when it names a person. The records stay; only the words go, and the gap leaves the list. Pass the text exactly as `list_gaps` shows it.
- `create_relationship(...)` — link entities (e.g. a Decision `implements` a Concept) to build the graph `find_related` traverses.
- **Original documents** — beyond git-style `add_document`, a person can upload a file's raw bytes (`POST /documents/upload`) and download the original (`GET /documents/{id}/download`, streamed after the ACL check). The bytes are content-addressed and kept as evidence even when the format can't be distilled (`extraction_status='unsupported'`). Editing an existing document uses **optimistic concurrency**: a stale edit is refused with the current head, never a silent overwrite.
- **Deleting a document — the reason decides the facts.** `delete_document(tenant, id, reason)` **requires** a reason: `error` (restorable, facts kept), `no_longer_needed` / `source_deleted` (facts **orphaned** — kept as history but retrieval-ineligible, since their citation no longer resolves), or `erasure` / personal-data `retention_expiry` which **purge** the document *and* its derived facts in an irreversible cascade (GDPR Art 17). Erasure needs the data-steward capability. Don't reach for erasure for housekeeping — orphaning is the safe default.
- **Erasing a document that is already deleted — never restore it first.** A document deleted with a restorable reason sits in `list_deleted_documents`. It can be erased **straight from there**: `delete_document(tenant, id, reason=erasure, confirmation_code)` accepts the soft-deleted id and purges it with the same full cascade (facts, observations, versions, stored original, search entries), and it is never visible again on the way. **Do not call `restore_document` to erase something** — that puts it back in front of its whole project until the erasure lands. The code comes from a person: call `arm_erasure` to get the steps to hand them — in the web console, **Sources → Recently deleted → Erase permanently → Arm erasure** (a live document: open it, **Delete…**, reason **Erasure / GDPR**, **Arm erasure**). Only a data steward can arm; the code is single use, bound to that one document, and lasts about ten minutes. They read it to you, or click **Erase now** themselves. An id that answers 404 "has already been permanently erased" is gone — there is nothing left to erase.
- **Removing one passage from a document's history.** History is never deleted. If a passage was taken out of the current document but is still in a past version, a data steward redacts it there: `list_document_versions`, `get_document_version` (copy the passage exactly), then `redact_version_passage` with the one-time code the steward gets by arming erasure in the web console. The version stays, the passage becomes a `[redacted …]` marker. Never redact the current version — edit the document.
- **The same passage inside a proposal.** A proposal (a staged observation) keeps a copy of the text it was distilled from, and a promoted one is kept for good. To remove the passage there too: find the proposal with `list_observations`, then `redact_proposal_passage(observation_id, passage, reason, confirmation_code)`. For a proposal drawn from a document the code is the one the steward gets by arming erasure for **that source document**; the proposal and its review snapshot keep their records, the passage becomes the marker. The fact it was promoted into is not changed — if that fact restates the passage, supersede it with clean wording or deprecate it.

### Keep the knowledge fresh — distillation is not one-and-done

A distilled fact is only as current as the last time its source was read. When a document changes, its entities are flagged **`stale`** (`source_changed`): they still answer, but they've drifted from the source and their wording ages out of what people ask. Left alone, a tenant **rots** — fully distilled once, then quietly out of date. **Freshness is a byproduct of use: every session is a curator.** Two habits, both cheap because you're already in context:

1. **On distil, refresh the neighbourhood.** When you distil or edit a document, glance at `list_stale` for entities from the **same source or topic** and re-distil the `source_changed` ones. Re-distilling **upserts by natural key (the same name/title): it updates the entity in place and clears the stale flag in the same write, so `list_stale` shrinks straight away.** It does not duplicate. A *different* name creates a new entity and leaves the old one stale, so `supersede` old→new in that case. If the fact is still correct as written, `confirm_fact` with a note saying why, but only after you've read the source.
2. **On entering a tenant to do real work, drain the top of the queue.** Glance at `distillation_coverage()` (undistilled backlog), `list_stale` (drifted facts), and `list_gaps()` (real questions that returned `no_strong_match`, frequency-ranked). Clear the **most-asked / most-recently-changed few** before your task — not the whole backlog, just the top. `list_gaps` is the demand-driven "what to distil next".

**Stale never blocks a read.** A stale fact is still returned, ranked lower and labelled. Answer the question you were asked, and mention the stale facts if they matter. Never make "the stale queue is empty" a precondition for answering: the queue is a review worklist, not a gate. Run `sweep_staleness` on a schedule (daily is plenty), not inside a user's request.

**Write entities to be *found*, not only to be *correct*.** An entity answers an oblique question only if its searchable text carries the words people ask with — so populate `synonyms` (concept) and phrase `title`/`name` the way the question is asked, not only the way the source states it. This is where recall is won or lost, and it costs nothing at distill time.

**The trust gate still holds:** auto-promote is fine when you're re-distilling a **trusted** source you just read (a git-ingested doc); route anything uncertain through `list_observations` for human review.

---

## Mode 3 — Work history (episodic)

Episodes are **append-only work history** — events (*"on date X, Y happened"*), not facts. They accrete, never supersede, are immune to staleness, and are kept **out of** the fact and semantic indexes so they never pollute retrieval. Team-visible by default.

- `search_episodes(text?, tag?, ticket?, since?, until?, summary?, limit?, offset?)` — **run this at the start of a session, or before raising work**, to see whether it was already done. Returns events, not facts. One page per call (see **Lists** below).
- `get_episode(id)` — one episode in full. Use it after `search_episodes(summary=true)`.
- `delete_episode(episode_id, reason)` — **permanently** remove one episode that must not be kept: it quotes something since erased, names a person, or was recorded in the wrong place. Owner/admin or the episode's author; `reason` is `erasure` | `error` | `no_longer_needed`; no restore. It is not how you correct history (record a new episode for that). The result lists `facts_still_citing`: check each and deprecate or supersede any that repeats what was removed.
- `record_episode(title, body, ticket_refs?, tags?, occurred_at?, secret?)` — **on ticket-close** (moving a ticket to review/done), log a *distilled* record: what changed, why, and a note for the next session. Not a transcript. Use `secret: true` to scope it to yourself.

You often don't need to call `search_episodes` explicitly — `get_context` already surfaces a bounded **`work_history`** section for the question at hand. Reach for it to browse history deliberately.

---

## Mode 4 — Situational record (transcript layer)

The soft, human context that meetings, calls and conversations throw off — a contact's preferences, who owns what, a commitment made on a call. Kept as **notes attached to subjects**, held apart from your business facts so they never bend a rule or decision. **Manage the subject, not the mention.**

- **Subjects** are `person | org | product | project | meeting`, tenant-scoped, with aliases.
  - `resolve_subject(kind, name)` — find or create the subject a note is about.
  - `list_subjects(kind?)` · `get_subject(id)`.
- **Notes** record what was said *and, separately, who said it*.
  - `record_note(tenant, subject, text, said_by?, source?, occurred_at?)` — capture a situational note. **Notes about a person are held as `proposed`** until someone accepts them (nothing about an individual is acted on unchecked); notes about non-person subjects are accepted directly.
  - `search_notes(...)` · `get_subject_context(subject)` — everything known about one subject, keyed by the subject itself. A bounded slice of this also rides along in `get_context`.
  - `accept_note(id)` · `reject_note(id)` · `flag_note(id, ...)` — triage proposed notes.
  - `promote_note(id)` — graduate a durable note into a typed fact (via the extraction path).
  - `reattribute_note(id, said_by)` — fix who said it.
- **Governance:** `get_transcript_settings` / `set_transcript_settings` control **person-capture** (a per-tenant/project on/off switch) and retention. `export_subject(subject)` exports everything known about a subject (data-subject requests) — deletion is an operator/REST action, deliberately off the tool surface.

If person-capture is **off** for a tenant/project, recording a note about a person is refused — respect that; it's a consent boundary, not a bug.

---

## Lists — a page at a time

Every list and search tool returns **one page**, never the whole set. This holds for documents, deleted documents, entities (`list_by_type`), observations (the review queue), work history, notes, subjects, stale facts, gaps and the other queues.

**The contract is the same on every list tool:**

- You send `limit` and `offset`. Each tool has its own default page and its own maximum; both are stated in the tool's description. A `limit` above the maximum gives you the maximum.
- You get back `total` and, when there is more, `next_offset`.
- `total` is the number of rows that match your filters and that you are allowed to read. It covers every page, not just the one returned.
- `next_offset` is where the next page starts. Pass it back as `offset`. When a response has no `next_offset`, you have reached the end.

**How to walk a list:**

1. Ask for the first page. Do not pass `offset`.
2. Read `total`. Decide whether you need the rest. Often you do not: narrow with a filter instead.
3. If you do, call again with `offset` set to `next_offset`. Repeat until `next_offset` is absent.
4. Never ask for everything in one call. There is no such call, and a large `limit` is clamped.

**Lists give summaries. Read the text one item at a time.**

- `list_documents` returns summary rows: id, path, kind, tags, size, dates, sensitivity. It never returns a document's text. Call `get_document(id)` for the one you want to read.
- `list_observations(summary=true)` and `search_episodes(summary=true)` return light rows without the body. Leave `summary` off when you want the full rows.

**Reading a deleted document.** `list_deleted_documents` lists soft-deleted documents, with when and why each was removed. To read one, call `get_document(id, include_deleted=true)`. You do not need to restore it first. The result carries `deleted_at` and `deletion_reason`. Without the flag a deleted document is not found. A purged or erased document is gone: it is in no list and no flag brings it back.

**Walking work history.**

1. `search_episodes(summary=true, since?, until?, tag?, ticket?)` gives the first page of summaries: id, title, date, tickets, tags.
2. Read `total`. Follow `next_offset` while you need more.
3. `get_episode(id)` gives the full body of each episode worth reading.

A text search over work history reports a `total` of at most 1000. If you reach that, narrow by date, tag or ticket.

**Two tools are bounded but not paged.** `get_subject_context` returns a subject's newest notes (50 by default, 200 at most); walk the rest with `search_notes(subject=<id>)`. `distillation_coverage` lists at most 100 undistilled documents; `total_docs - distilled_docs` is how many remain.

---

## Mode 5 — The enterprise graph (add-on)

Some workspaces have the **enterprise graph**: the company's own model of its people, things and processes. It is an add-on; without it every `graph_*` tool says so plainly, and you carry on without it.

- **The schema is theirs.** Call `graph_schema` first and use their type, property and link keys. Do not invent types; if one is missing, say so. Changing the schema (`graph_define`, `graph_schema_status`) is for the workspace's owner or admin, and every change is versioned with a reason.
- **Every value is a dated, cited statement.** `graph_assert` records one; a new value for a single-valued property (or a new link of a `one` link type) supersedes the current one, which is kept as history. Always give `reason` for a change, and `cause_kind` / `cause_ref` when a decision, ticket or episode caused it. `graph_end_statement` records that something stopped being true ("no longer works with Y").
- **Read it as it is, was, or changed.** `graph_get_thing` gives what is true now with grade, dates and source; `as_of` reads a past date; `history=true` gives what changed, from what, when and why.
- **It can be large; read it a slice at a time.** A thing's links come back as `link_counts` plus a first page: when you need a number, use the count, never page through to count. Page the rest with `links=out|in` only when you need the items. A list's `total` above 10,000 is a floor (`total_exact: false`).
- **Load with `graph_batch`**, up to 1,000 statements per call, all or nothing, addressing things by the workspace's own keys; re-running an import changes only what changed. To import history, give a finished span `valid_from` + `valid_to` (a past date); it never touches what is current. If a source does not give a start date, do not invent one and do not let it default to today: record `valid_from: "unknown"`. A statement flagged `start_unknown` is true now, but when you answer about a past date, say it is not known whether it held then.
- **Grades. Evidence is not assignment.** `declared` = asserted by someone with authority. `evidenced` = drawn from a cited source, dated, and possibly old. `proposed` = held for a person to review; it answers nothing until accepted. **Never infer responsibility from history.** "Sam ordered the merch in 2025" is evidence of an event, not "Sam is responsible for merch".
- **"Who do I ask about X?" → `graph_who_to_ask(about="X")`, before you name anyone.** It answers from declared responsibility only (directly, through whoever holds the role, or inherited from what X is part of). If it says "No owner is declared", repeat that, give the latest activity it shows *as evidence with its date*, and suggest an owner or admin declares one. Do not route the request to the person in the activity.
- **Link meanings.** Each link type has a `meaning`: `responsibility` (answers for), `holds_role`, `part_of`, `activity` (did something: evidence only) or `relation`. Record what someone *did* as an `activity` link, graded `evidenced` with its source. A `responsibility` link is never evidenced; unless you act for an owner or admin, propose it.
- **If you are inferring, propose.** Something you read in a document and are not sure of, or lack the authority to state, goes in with `grade=proposed` and its source. A person accepts or rejects it with `graph_proposals`.
- **What does not belong in it:** operational state that changes because the business operated, such as stock counts, orders or telemetry. The graph is for what things are, how they relate, and how that changed because the business decided or learned something.
- `graph_delete_thing` is permanent erasure (owner/admin). `graph_usage` counts what the workspace holds.

## Rules of engagement (the short version)

1. **Read history first.** `search_episodes` at session start / before raising work.
2. **Retrieve with `get_context`.** Read the pack, not the corpus. Normal depth first; one `depth="deep"` call only if the answer is missing and `deeper_available` is true.
3. **Honour `no_strong_match`.** No entity-anchored grounding → say you don't know; don't guess.
4. **Cite.** Answer from the returned entities/passages and carry their citations through.
5. **Stage valid types only.** `concept | decision | rule | process | reference` — never `document`. Promotion stays human-gated.
6. **Keep the lanes separate.** Facts = curated positions; episodes = work history; notes = situational context about subjects. Don't record situational context as a fact, and don't blend them.
7. **Close the loop.** `record_episode` on ticket-close.
8. **Respect consent.** Person-capture off = don't capture personal notes.
9. **Keep it fresh.** Re-distil the stale neighbours when you touch a document; clear the top of the `distillation_coverage` / `list_stale` / `list_gaps` queue when you enter a tenant. Write entities to be *found* (synonyms + question-phrasing). A tenant stays current only if the sessions working it curate as they go. Staleness is a worklist, never a gate on reads.
10. **Page every list.** Ask for a page, read `total` and `next_offset`, fetch full text one item at a time. Never ask for everything.
11. **Never infer responsibility from history.** That someone did something once (in a fact, an episode, a note or a document) does not make it their job. Ask `graph_who_to_ask` where the workspace has the graph; otherwise say who did it and when, and that no owner is recorded.

---

## Building a platform on Cornerstone (integrators)

If you're wiring Cornerstone behind your own gateway or agent loop, rather than connecting an AI client straight to `/mcp`:

- **Build your tool map from the live `tools/list`**, and fail your CI when it changes. Hand-maintained catalogs drift, and the loop then relies on tools the gateway doesn't expose. Keep `create_tenant`, membership and access-control tools out of the agent catalog; they are provisioning actions.
- **One tenant per organisation, projects inside it.** A tenant is the hard isolation boundary; a project is the scope you pass on writes.
- **Close-out = one distilled episode plus any fact the work settled or changed** (`stage_observation`, or `reverse_decision` for a reversed decision). Don't restrict the close-out step to `record_episode` alone, or decisions decay into history.
- **Replay safety:** `add_document` and `create_relationship` are idempotent. `record_episode`, `stage_observation` and `record_note` are append-only, so dedupe redelivered messages on your own operation key.
- **Bulk sync:** one file = one document, omit `expected_version`, send only changed hashes, and `delete_document(reason=source_deleted)` when a file goes away.
- **Freshness is out-of-band work** (see "Stale never blocks a read" above).

The full integrator guide is `docs/integration-guide.md` in the Cornerstone repo; ask your Cornerstone contact for a copy.

---

## Changelog

### 1.23.0 — 2026-11-16
**A passage can be redacted inside a proposal** (CORN-430). `redact_proposal_passage` replaces a passage in a proposal's subject, object and payload — promoted or not — and in its review snapshot, keeping the proposal. Data steward; for a proposal drawn from a document, a one-time code armed for that document. The promoted fact is not changed: supersede or deprecate it if it restates the passage.

### 1.22.0 — 2026-11-15
**Erase a document that is already deleted, without restoring it** (CORN-428). `delete_document(reason=erasure, confirmation_code)` now accepts a soft-deleted id (from `list_deleted_documents`) and erases it directly — same data-steward clearance, same one-time code, same cascade, and the document is never restored on the way. `arm_erasure`'s steps now cover deleted documents: the person arms from **Sources → Recently deleted → Erase permanently**. Never call `restore_document` as a step towards erasing. Deleting an already-deleted document for any other reason still answers 404, now saying it is already deleted and can be restored or erased. Re-read **Deleting a document** in the Extraction section. Server release 1.1.0.

### 1.21.0 — 2026-11-14
**The guide moved to the standard II paths** (CORN-418, the II tool surface contract). Canonical: `/mcp/prompt.md`; version check: `/mcp/prompt/version`. The old `/mcp-prompt.md` and `/mcp-prompt/version` remain as aliases. `GET /health` is now public and reports the running release version, git revision and build time; the MCP `serverInfo.version` and the OpenAPI `info.version` report the same release version. No tool signatures changed.

### 1.20.0 — 2026-11-13
**Renaming a project** (CORN-397). `update_project` renames a project; its name and key change together, never one alone (the default project keeps the key `default` but can be renamed). The old key keeps working for a changeover, default 30 days, and any result from a call that uses it begins with `NOTICE:` naming the new key. Switch to the new key when you see it. A retired key is never reused; a new key or name may not match another project's key or name, ignoring case.
**Sharing a document with another project** (CORN-391). `share_document(document_id, project)` lets the members of another project READ a document without moving it or joining its project; facts follow when every source document is readable there. `unshare_document` takes it back. `grant_access` only narrows access within the document's own project — a project grant naming another project is now refused and points to `share_document`; older ones show as `no_effect` in `describe_access`.
**Where a write with no project lands is now per person** (CORN-392). An owner/admin can give a member their own default write project (`set_member_default_project`; `list_tenant_members` shows it) and can make a tenant refuse any write that names no project (`set_tenant_settings require_project_on_write=true`; `get_tenant_settings` reads it). `promote_note`, `promote_episode` and `reverse_decision` now take `project`. The web console's uploads show and let you choose the project.
**History is never deleted; a passage in a past version can be redacted** (CORN-395 / ADR-0040). `list_document_versions` and `get_document_version` read a document's history. `redact_version_passage` replaces a passage in a PAST version with a `[redacted …]` marker, keeping the version; it needs a data steward's one-time code from the web console, exactly like erasure. Copy the passage from `get_document_version` exactly. `redact_question` (data steward) blanks the wording of a question in the gaps log and delivery records, keeping the records (CORN-383).

### 1.19.0 — 2026-10-27
**Unknown start dates in the graph** (CORN-413). `valid_from: "unknown"` records a fact whose start no one knows, rather than leaving it out or dating it today. Such statements come back flagged `start_unknown` with no `valid_from`; asked about a past date, say it is not known whether they held then.

### 1.18.0 — 2026-10-27
**Importing history into the graph.** `graph_assert` and `graph_batch` take `valid_to`: a finished span ("a member from 1962 to 1970") recorded as history in one statement, never touching what is current, and a no-op when re-recorded. Never invent a start date a source does not give.

### 1.17.0 — 2026-10-26
**The enterprise graph (add-on)** (CORN-401 / ADR-0039). A workspace with the add-on has its own model of its people, things and processes: `graph_schema`, `graph_define`, `graph_schema_status`, `graph_create_thing`, `graph_find_things`, `graph_get_thing` (now, `as_of` a date, `history`, or paged `links`), `graph_assert`, `graph_batch` (up to 1,000 statements, all or nothing), `graph_end_statement`, `graph_proposals`, `graph_delete_thing`, `graph_usage`, `graph_who_to_ask` (who answers for X, from declared responsibility only; `gaps=true` for what most needs an owner). Reads are bounded: links come back as counts plus a first page. Every value is a dated, cited statement with a grade; a change supersedes and keeps the history. Link types carry a `meaning` (responsibility, holds_role, part_of, activity, relation). New rule, in **Mode 5** and as rule 11 for every workspace: never infer who is responsible from who did something last.

### 1.16.0 — 2026-10-13
**A folder restriction now covers files that arrive later** (CORN-390). `grant_access` / `revoke_access` with a `path_prefix` used to change only the documents that existed at that moment; the next file under the folder was open to the whole project. The prefix is now kept as a standing rule: a document added, renamed or restored under the folder carries it automatically, and the most specific folder rule wins. The folder is matched whole and without regard to case (`finance` no longer also matches `finance-old/`). The result returns the stored rule as `standing_rule`, and says plainly when no document is under the folder yet. `describe_access(path_prefix)` shows the rule the next file will get. A rule made before this version was not stored: re-run the grant to make it standing.

### 1.15.0 — 2026-10-13
**One episode can be removed, and several writes now refuse instead of guessing.**
- `delete_episode(episode_id, reason)` permanently deletes one episode (CORN-382): for the tenant's owner/admin or the person who recorded it, with `reason` = `erasure` | `error` | `no_longer_needed`. No restore. Facts that cited it are kept and returned as `facts_still_citing`; read them and deprecate any that restate what had to go.
- `plan_move` / `apply_move` refuse an argument they do not list (CORN-385). There is no per-item move: sending `episode_ids` used to be ignored and planned the whole project.
- `add_project_member` / `add_tenant_member` refuse an unknown `role` with a 422 naming the valid ones (CORN-384). A typo is no longer turned into `editor`.
- `grant_access` refuses a `principal_ref` that is not really a principal of the stated `principal_type` in this tenant (CORN-389). Get the id from `list_tenant_members`, `list_projects` or `describe_access`.
- `add_document` onto a `source_path` that already exists updates that document where it lives, and needs write access to **its** project (CORN-387). Naming a different `project` is refused with 409: a write never moves a document, and never changes its owner or visibility.
- A project-pinned API key reads only while its owner can read that project (CORN-388).

### 1.14.0 — 2026-10-13
**A project can be deleted when it is empty** (CORN-381). `delete_project(tenant, project_id, confirm_key)` — owner/admin only, audited, not reversible. It is refused, with a list of what the project still holds, if it contains anything; move the knowledge out first with `plan_move` / `apply_move` (the destination can be another project in the same tenant). The default project cannot be deleted.

### 1.13.0 — 2026-10-13
**A tool can register what it runs** (CORN-380). `upsert_process(external_key, name, subtype?, …)` creates or updates ONE process by a key the caller owns, so a Council room (or any tool's workflow) is one entity however often it is renamed; it is live at once, with no review queue. `list_by_type(type=process, subtype=…)` lists one kind of process, and `subtype` + `external_key` are shown on every read. `create_relationship` now requires both entities to be ones you can see and files the edge in the project of the entity it starts from — point it FROM the thing you will ask about (`room —produced→ decision`).

### 1.12.0 — 2026-10-13
**Read this guide from inside MCP** — `get_guide()` returns this document, for a client that cannot open the URL. **Access is checked on more reads** (CORN-373/374): `describe_access` answers only for an owner/admin or for something you can see yourself; `list_gaps` shows a member their own unanswered questions; the audit reads, `export_subject` and the retrieval eval are owner/admin only; a proposed fact is listed only if you can read its source document; a citation is given only for a source you can open. A fact promoted from documents that share no audience is visible to nobody until a source's access is changed.

### 1.11.0 — 2026-10-12
**Machine access** (CORN-370). Another tool can read a tenant as itself, with its own machine identity, instead of holding a `cs_` key: `list_machine_access(tenant)`, `grant_machine_access(tenant, issuer, subject, label)`, `revoke_machine_access(tenant, grant_id)`. Owner/admin only, audited. The access is read-only and confined to that one tenant.

### 1.10.0 — 2026-10-08
**Every list loads a page at a time** (CORN-368). All list and search tools now share one contract: `limit` + `offset` in, `total` + `next_offset` out. A `limit` above a tool's maximum returns the maximum instead of falling back to the default. New `offset` on `list_observations`, `search_episodes`, `search_notes`, `list_deleted_documents`, `reliability_review_queue`, `list_stale`, `list_subjects`, `list_gaps`, `promotion_candidates`, `list_relationship_candidates`, `list_review_labels` and `list_pending_distillation`; `total` added to those and to `list_documents` and `list_by_type`. **`list_documents` now returns summary rows with no text** — read a document with `get_document(id)`. **`get_document(id, include_deleted=true)`** reads a soft-deleted document without restoring it. **`search_episodes(summary=true)`** and **`list_observations(summary=true)`** return light rows; new **`get_episode(id)`** reads one episode in full. `list_observations` now defaults to 50 rows per page (it returned up to 100 with no way to reach the rest). `list_relationship_candidates` lists only candidates whose two documents you may both see. See the new **Lists** section.

### 1.9.0 — 2026-10-05
**`create_tenant` makes a correct tenant first time** (CORN-361). Two new optional arguments: `purpose` (`primary` default, or `method` for a ways-of-working tenant) and `default_member_role`. A `method` tenant defaults new members to viewer, so staff read the method and only its owners change it. Encryption at rest is now turned on as part of the create (the result says `encrypted`), replacing a separate manual step; where the deployment encrypts, a tenant that cannot be encrypted is not created. `list_tenants` now returns each tenant's `purpose`. Existing calls are unchanged.

### 1.8.0 — 2026-10-05
**`add_tenant_member` follows the tenant's default member role** (CORN-360). It used to make every new member an editor on the default project; it now grants the tenant's own setting (`default_member_role`: viewer, commenter or editor — editor unless changed), so a read-only tenant stays read-only without a follow-up fix. Don't assume a newly added member can write: check `list_project_members`. **`remove_tenant_member` now also removes the person's project roles**, so someone re-added later starts from the tenant default instead of silently regaining old roles. No tool signatures changed.

### 1.7.0 — 2026-09-26
**Per-question retrieval depth** (CORN-338): `get_context` takes `depth` (`normal` default, or `deep`) and the pack reports `depth` and `deeper_available`. Answer from the normal pack; call once more with `depth="deep"` only when the answer is missing. **Semantic passages** (CORN-336): where enabled, passages are matched by meaning as well as by keyword. **Withdrawn-document detection is more precise** (CORN-337): only a declaration near the top of a document withdraws it, so a document that merely *mentions* "do not use" is no longer hidden. New optional argument; no existing signature changed.

### 1.6.0 — 2026-09-25
**Re-distilling now clears the stale flag immediately** (CORN-328). Previously a same-name re-distil refreshed the fact but left it `stale` until the next `sweep_staleness`, so a loop that re-distilled and then re-read `list_stale` saw no progress. **Stale never blocks a read** is now stated explicitly: the stale queue is a review worklist, never a precondition for answering. New **integrators** section for platforms wrapping Cornerstone behind their own gateway (CORN-329). No tool signatures changed.

### 1.4.0 — 2026-08-30
Supersession lineage is now **readable** (CORN-234): `get_entity` returns a retired entity (with `superseded_by`), `find_related` on the replacement walks the reverse `supersedes` edge, and **`list_by_type` gains a `lifecycle` filter** (`lifecycle=superseded` enumerates the retired). No behaviour change for the default (unfiltered) list. Unrelated to the AI write path, but worth knowing: a tenant's **git sources are now kept fresh automatically** (an hourly re-ingest scheduler + a push webhook, ADR-0027) — so re-`add_document` is for content you author here, not for chasing repo drift. Ingestion remains multi-path and **GitHub is never required** (upload / `add_document` / operator seed / other connectors all stand alone).

### 1.3.0 — 2026-08-24

**Project is the boundary to reach for; a tenant is a one-way door.** New decision table at the top of Tenancy, because the guide previously described both mechanisms and never said which to choose — and the estate it was written for ended up with 32 of 34 tenants holding exactly one project each. Every one of those was a reversible boundary someone did not know they had, spent on an irreversible one.

`project` now works on the paths that matter, not just `add_document`:
- **Writes** — `record_episode` and `stage_observation` take `project`. They previously filed to the caller's default project unconditionally, so everything a session produced landed in one place regardless of what the work was about.
- **Reads** — `query` and `get_context` take `project` to narrow to one. Omitting it (the normal case) reads every project you can see, which is what makes sibling workstreams compound. Narrowing can only narrow: an unknown or out-of-access project searches nothing and explains itself in `coverage.hint` instead of quietly answering from the wider scope.

All of them accept a **UUID or a key** and reject anything outside your accessible set rather than redirecting it.

### 1.2.9 — 2026-08-16
**Freshness discipline** (Mode 2 + rule 9): distillation is not one-and-done. A distilled fact is only as current as the last time its source was read; when a document changes its entities are flagged `stale` and, left alone, a tenant rots (measured on the dogfood tenant — fully distilled once, then six weeks stale). Two cheap habits make freshness a byproduct of use: on distil, refresh the same-source/topic stale neighbours (re-distilling upserts in place, clearing the flag — no duplicate); on entering a tenant, clear the top of the `distillation_coverage`/`list_stale`/`list_gaps` queue before your task. Plus: **write entities to be *found*** — populate `synonyms` and phrase titles the way questions are asked, since that (not raw correctness) is where recall is won. No tool signatures changed.

### 1.2.8 — 2026-08-15
Mode 1 gains **"ask the repo for code, ask Cornerstone for position"** (CORN-195): code-level facts live in the repository and a decline on them is correct; operational *position* facts (deploy discipline, where a secret lives, why a build is token-free) belong here — a miss is a distillation gap to fill. No tool signatures changed.

### 1.2.7 — 2026-08-14
`list_pending_distillation(tenant, limit?)` — the distiller worker's queue (CORN-192): user-dropped documents that have text but **no typed knowledge derived yet**. Each item is `{id, source_path, source_kind, content_hash}`. Workflow for a distiller (the WBA doc lane, or any client AI): poll this → `get_document` the text → reason → `stage_observation(source_ref=<doc id>)` per proposal → `promote_observation` (human-gated). Key idempotency on `content_hash`. Only ACL-visible **drops** appear — git-ingested/agent/session docs never do. Files dropped in the drive are also auto-converted to searchable text on upload (docx/pptx/xlsx/pdf), so this queue is text-ready.

### 1.2.6 — 2026-08-14
`add_document` now honours **`expected_version`** (ADR-0020), extending the native-drive optimistic-concurrency guard to the AI write path (CORN-186). When you EDIT a document that a human may also be editing (a drive file), pass the `content_hash` you read via `get_document`: if the head has moved you get a **409** instead of silently clobbering their change — reload and re-apply, and the loser's content is retained as a branch version, nothing lost. Omit it to create a new document or to bulk re-sync (the historical blind upsert, unchanged — ingestion/connectors rely on it). Pairs with the new web **Drive** (CORN-182): human and AI writers now play by the same rule.

### 1.2.5 — 2026-08-14
Project membership is now manageable from MCP (CORN-180): `list_project_members` / `add_project_member(project_id, email, role?)` / `remove_project_member`. A tenant member who was never added to a project cannot see its knowledge (ADR-0009 default-deny) — the fix for "I ingested docs and cannot see them". add_tenant_member also now auto-joins the tenant default project, and existing members were backfilled.

### 1.2.4 — 2026-08-13
Documentation catch-up (no behaviour change): the guide body now documents surfaces that had shipped but were only in the changelog or REST — **projects** (`list_projects`/`create_project`, `add_document`'s `project` arg), **tenant membership**, **access control** (`describe_access`/`grant_access`/`revoke_access`), **original documents** (upload/download, optimistic concurrency), and **reasoned deletion** (`delete_document(reason)` — retain/orphan/purge, erasure). Re-read the Tenancy and Extraction sections.

### 1.2.3 — 2026-08-13
Tenant membership is now administrable from MCP (CORN-178), so onboarding a colleague and answering "is X actually a member?" no longer drop into the web console or psql. `list_tenant_members(tenant)` returns user id / email / role; `add_tenant_member(tenant, email, role?)` provisions + adds by email; `set_tenant_member_role(tenant, user_id, role)` and `remove_tenant_member(tenant, user_id)` round it out. Owner/admin only, last-owner protected, each emits an audit event. Standing up a client tenant is now one flow: `create_tenant` → `add_tenant_member`.

### 1.2.2 — 2026-08-13
Access control is now a tool, not SQL (CORN-174 / ADR-0009). `describe_access` answers "who can see this?" for a document, an entity, or a whole `path_prefix` — the preflight. `grant_access` / `revoke_access` add or (with `replace: true`) restrict, by document or path prefix, and automatically recompute the derived-entity ACL intersection + reindex, so the content gate is correct immediately and the ≤15-min revocation SLA is real. `recompute_entity_acl` repairs derived entities after a legacy/manual document-ACL change. All admin-only; every grant/revoke emits an audit event. Use these instead of touching `document_acl`/`entity_acl` directly.

### 1.2.1 — 2026-08-13
`no_strong_match` responses now carry a `coverage` hint (CORN-176) counted over the documents **you** can see, so it never discloses restricted content. It distinguishes the three cases that used to share one signal: nothing here, documents-present-but-not-distilled (your own next action — run `distillation_coverage()`), and content-you-can't-see (invisible, never disclosed). See Mode 1. No tool signatures changed.

### 1.2.0 — 2026-08-09
Tenant lifecycle is now two-step and recoverable (CORN-148): `delete_tenant(tenant_id, confirm_tenant_id)` is a **recoverable** soft-delete, `recover_tenant` undoes it, and `shred_tenant(tenant_id, confirm_tenant_id)` permanently destroys an already-deleted tenant. Both destructive tools require echoing the id in `confirm_tenant_id`. (The old one-shot `delete_tenant(tenant_id)` was replaced — it had drifted from the id-confirmed API and returned 400.) Also added `sweep_retention` (enforce a tenant's retention policy — purge expired capture content, never facts/episodes; dry_run to preview) and thread support: `resolve_subject`/`list_subjects` accept the `thread` subject type and `ripple(kind=thread)` traces a coordination thread.

### 1.1.0 — 2026-08-07
Added `delete_tenant` (dispose of an empty tenant you own) and `list_stale` (pull the flagged/stale review worklist — the read counterpart to `sweep_staleness`). Note: retrieval is now **access-controlled within a tenant** (entity-level ACLs) — you only see entities and documents your principal is granted, so a narrower-than-expected result can be a permission boundary, not missing knowledge.

### 1.0.0 — 2026-08-02
Initial published guide. Covers tenancy, the six entity types (+ the promotable-type rule), retrieval (`get_context` / `no_strong_match` / semantic lane), client-driven extraction, the episodic work-history layer, and the situational transcript layer (subjects, notes, person-capture consent, governance).
