@cairnkeep/cli 2.23.1 → 2.25.0

package/docs/learning/video-scripts/V29-team-continuity.md

@@ -0,0 +1,66 @@
+# V29 - Remember together without sharing everything
+
+Status: technical rehearsal brief for the opt-in Cairnkeep 2.25.0 preview.
+Target: 10–12 minutes, experienced-developer audience. Describe a released
+experimental preview, not a generally production-admitted team service.
+Use the [isolated pilot guide](../../team-pilot.md) for a separately authorized
+native-harness trial, not as authorization to record private review or credentials.
+
+## 0:00–1:30 — Continuity is the goal
+
+“The useful part is not winning a one-shot puzzle. It is continuing tomorrow,
+in another harness, without explaining the same project decision again.”
+Pause, then introduce the new boundary: your private memory is not a team bucket.
+Show the proposal/review/revision lifecycle, one stage at a time.
+
+## 1:30–3:30 — Deliberately separate identities
+
+Use a disposable source checkout and only synthetic fixtures. Show
+`bin/cairn team --help` and the default-off failure. Read the roles in
+`docs/team.md`; highlight that a reviewer token is human-only and is never
+handed to the agent. Briefly show initialization/membership command forms,
+with no token contents on screen. The server is loopback-only.
+
+## 3:30–6:00 — Make the boundary visible
+
+Type the six L29 control commands at human speed; use completion where useful.
+Split the terminal: immutable selected proposal on one side, human review and
+approved retrieval on the other. Use the actual fixture results rather than
+fabricating a transcript. Pause on denied workload/self-review and the stale
+digest/base controls. Explain that confirming a hash does not prove human consent.
+
+## 6:00–8:00 — Change clients, not authority
+
+Run `smoke-team-mcp.mjs` separately and inspect its maintained fixture: two
+actual stdio clients, different cwd, same approved project decision. Zoom into
+project provenance, then contrast an unrelated project denial and live token
+revocation. Do not claim the test launched every named commercial harness.
+Show `cairn team member remove SUBJECT --project ID --data DIR` as the explicit
+project-offboarding command. Pause on the connected client's denial; explain
+that removing one project membership does not revoke all of that person's tokens.
+An additional MCP entry is opt-in; existing memory servers are not replaced.
+
+## 8:00–10:00 — Recovery with a catch
+
+Run `smoke-team-restore.mjs` and `smoke-team-cli.mjs`. Leave a two-second pause
+on “restored credentials revoked”: copying a backup must not silently restore
+access. Show fresh-only restore, no-overwrite and uninstall-retention controls.
+Explain that logical deletion is not secure disk erasure or backup deletion.
+
+## 10:00–11:30 — Honest closing
+
+End on the admission checklist in `docs/team.md`, not a production deployment.
+Distinguish completed regression controls, the internal governed review and
+the approved isolated native pilot from independent production review and a
+deployment-specific real-data pilot. Do not imply two independent human testers.
+Explain that personal-memory embeddings/reranking never process team search.
+Distinguish the JSON API/local stdio bridge from OAuth
+remote MCP. Call out OIDC, team packs and multi-organization tenancy as deferred.
+
+## Recording contract
+
+Use legible real terminals, short scene changes, natural pauses and emphasis
+around each changed authority boundary. Keep credentials, personal memory,
+source excerpts from private projects and raw snapshot text off screen.
+Do not enroll a real user, deploy, purchase services or mutate live MCP config
+to produce the video. This brief does not imply a video has been recorded.

package/docs/mcp-tool-profiles.md

@@ -41,3 +41,10 @@ The default `full` profile preserves the same tool names, schemas, responses,
 feature gates, and ordering as an unconfigured server. The annotations help
 conservative clients distinguish observations from actions; they do not grant
 permission or replace the client's approval policy.
+
+With a valid, explicitly enabled memory reranker, `memory_search` advertises
+`openWorldHint: true` because query and bounded candidate excerpts can reach
+the configured service. It remains `readOnlyHint: true`, so a read-only
+profile still exposes it. Tool restriction is not network consent: omit it
+from a custom profile or disable reranking if that data flow is unwanted.
+With reranking off, existing discovery metadata is unchanged.

package/docs/memory-retrieval.md

@@ -161,8 +161,90 @@ Its sample threshold of 0.75 is an evaluation arm, not a recommended default.
 An attempted live run during development accepted short probes but failed with
 HTTP 502 on some fixture inputs. No successful live-model result is claimed.
 The offline suite never requires a model, API key, paid service or network beyond
-its own loopback fixture. An optional learned reranker remains deferred until
-provider-specific evidence demonstrates a benefit beyond this simpler policy.
+its own loopback fixture. A separate optional reranker comparison below does
+not replace this older study or retroactively make that failed run successful.
+
+## Optional learned reranking
+
+Available since Cairnkeep 2.24.0. This feature improves ordering, not guaranteed
+recall: the small live comparison below retained the same Recall@3 in both arms.
+
+The optional reranker is default-off and independent of extraction and
+embeddings. Set `CAIRN_MEMORY_RERANK=1`, `CAIRN_MEMORY_RERANK_URL` (a base URL,
+normally ending in `/v1`) and `CAIRN_MEMORY_RERANK_MODEL` on the memory-server
+process. The client appends `/rerank`. If authentication is needed, set the
+separate `CAIRN_MEMORY_RERANK_API_KEY`; extraction/embedding credentials are
+never reused. `CAIRN_MEMORY_RERANK_TIMEOUT_MS` defaults to 2,000 ms and accepts
+100–10,000 ms. Restart the server after configuration changes.
+
+Only `memory_search` in the `memory` address space is reranked, for either
+legacy or hybrid strategy. Notes, context packs, documents and the separate
+team store are unchanged. Existing scope, current-value, typed and relevance
+filters admit candidates first. The provider receives the original query
+(at most 4 KiB) and at most 50 admitted key/value excerpts (at most 4 KiB each),
+not the whole store. Candidate depth is `min(50, max(32, 4 * top_k))`.
+Exact-key priority in hybrid search (including explicit aliases) and typed legacy exact-hit priority remain
+ahead of model scores. The provider only reorders admitted records; it cannot
+add facts, change authority, write memory or recover a candidate already
+rejected by admission. A small final `top_k` can include a candidate outside
+the original top-k prefix after reranking.
+
+The endpoint must return every candidate index exactly once in a `results`
+array with finite `relevance_score` numbers. Negative raw scores are accepted;
+these are ranking values, not calibrated confidence. Returned memory text,
+provenance and existing retrieval scores are unchanged; those scores need not
+be descending after learned reranking. Ties preserve the
+existing order. Timeout, HTTP errors, redirects, oversized responses, invalid
+configuration or malformed/partial indices preserve the original order.
+No retries or alternate provider fallback are made. Unset/disabled configuration
+performs no reranker request and preserves existing discovery and responses.
+When configured, `memory_search` remains read-only but advertises
+`openWorldHint: true` because it can export candidate text.
+
+`cairn doctor` uses synthetic text to check configured reranking and fails if
+the configuration or response is invalid. Ordinary searches still fall back
+safely; doctor does not mistake fallback for a healthy provider.
+
+### Bounded provider comparison
+
+The frozen `memory-reranker-study-v1.json` fixture contains 20 synthetic
+continuity cases, including 16 positive and four negative cases. Both arms use
+the same embedding vectors, admission rules, aliases and final top three.
+Labels and the fixture digest were frozen before the first live ranking run.
+
+| Metric | Hybrid + embeddings | Same candidates + reranker |
+|---|---:|---:|
+| Relevant first result, 16 positive cases | 6/16 | 15/16 |
+| MRR@3 | 0.635417 | 0.968750 |
+| NDCG@3 | 0.728416 | 0.976933 |
+| Recall@3 | 1.0 | 1.0 |
+| Negative queries returning results, 4 cases | 0/4 | 0/4 |
+
+Ten cases improved and **one regressed**: `current-not-history` ranked a
+topical interface distractor above the correct current fact. Hidden history
+was still excluded. No scope/history violation or provider failure occurred.
+Observed additional ranking latency was 9 ms median and 46 ms p95 in this
+small local run; this is not a deployment latency guarantee.
+
+This is an engineering-labeled synthetic comparison with deliberately
+ambiguous topical distractors, not an independent holdout, a human study or
+proof of general agent-quality gains. It justifies an optional experiment,
+not default enablement. Evaluate your provider and corpus before opting in;
+disable `CAIRN_MEMORY_RERANK` to reverse the change.
+
+From a source checkout (these developer study scripts are not installed CLI
+commands):
+
+```sh
+npm --prefix mcp-memory-server run check:memory-reranker
+# Requires explicit existing embedding and reranker configuration:
+node mcp-memory-server/scripts/run-memory-reranker-study.mjs --live --summary
+```
+
+Without `--live`, the study makes no provider calls even when configured.
+Reports include fixture, implementation and model-ID digests, no URLs or keys.
+The frozen fixture SHA-256 is
+`f6a5d2de8d2846dd5a8de764096d92255716592805e8abfdc771181eac23beb1`.
 
 ## Research connection
 

package/docs/operating.md

@@ -495,6 +495,11 @@ vendor or host.
 | `CAIRN_MEMORY_EMBEDDING_URL` | Embeddings endpoint (falls back to `CAIRN_LLM_API_URL`) |
 | `CAIRN_MEMORY_EMBEDDING_MODEL` | Embedding model name (required for semantic search) |
 | `CAIRN_MEMORY_EMBEDDING_TIMEOUT_MS` | Embedding request timeout before substring fallback (default `15000`) |
+| `CAIRN_MEMORY_RERANK` | Explicit `1` enables optional learned memory-search reranking; off by default |
+| `CAIRN_MEMORY_RERANK_URL` | Explicit HTTP(S) base URL; client appends `/rerank`; no embedded credentials, query or fragment |
+| `CAIRN_MEMORY_RERANK_MODEL` | Required model identifier when reranking is enabled |
+| `CAIRN_MEMORY_RERANK_API_KEY` | Optional separate reranker credential; no extraction/embedding key fallback |
+| `CAIRN_MEMORY_RERANK_TIMEOUT_MS` | Reranking deadline, default `2000`, allowed `100`–`10000`; failure preserves existing search order |
 | `CAIRN_AGENTFS_BASE_DIR` | Server-side base dir for named/global memory scopes (default `~/.cairnkeep`); it does not affect `project` scope |
 | `CAIRN_TRAJECTORY_CAPTURE` | Opt in to local structured session capture (`1`, `true`, `yes`, or `on`; unset/default → no capture work) |
 | `CAIRN_TRAJECTORY_SESSION_MAX_BYTES` | Maximum serialized bytes per session (default `5242880`, 5 MiB; minimum 1024) |
@@ -957,9 +962,10 @@ cairn playbook record --help
 ```
 
 Inspect receipts with `cairn playbook receipts list|show`; validate state with
-`cairn playbook doctor`. Actor and session options are provenance labels only:
-v2.15 does not authenticate them and does not provide team ACLs. See
-[team mode](design/team-mode.md) for the future admission contract.
+`cairn playbook doctor`. Actor and session options remain unverified provenance
+labels, not team ACLs. The separate [team preview](team.md) authenticates its own
+credentials and project memberships; it never trusts local playbook labels.
+See [team mode](design/team-mode.md) for the broader admission contract.
 
 The corresponding process overrides are optional:
 
@@ -1536,3 +1542,16 @@ cairn proposals apply PROPOSAL_DIGEST --project /path/to/project --json
 
 No background process synchronizes OpenViking, creates proposals, applies
 memory, enables packs, or approves skills.
+
+## Team continuity (opt-in 2.25 preview)
+
+The separate `cairn team` command implements explicitly selected and reviewed
+project memory. It is default off (`CAIRN_TEAM=1` required); serving also needs
+`CAIRN_TEAM_HTTP=1`. It does not change ordinary setup or existing MCP entries.
+Use [the team reference](team.md) for roles, private credentials, additional
+local stdio registration, human review, backup/restore and incident handling.
+The internal governed review and approved isolated native pilot are complete;
+independent production review and a deployment-specific approved real-data pilot
+are still required before using real organization data.
+Existing personal HTTP remains a trusted single storage domain; token-first
+team JSON HTTP is a different service, not OAuth remote MCP HTTP.

package/docs/privacy-and-data-flow.md

@@ -3,7 +3,8 @@
 Cairnkeep has no telemetry, analytics collector, hosted control plane, or
 automatic remote-service discovery. A default local stdio installation stores
 memory in SQLite on the machine running the MCP server and makes no model or RAG
-request unless the corresponding endpoint and credential are configured.
+request unless the corresponding feature is explicitly configured as described
+below (some operator-owned endpoints do not require a credential).
 
 ## Data flows
 
@@ -11,6 +12,7 @@ request unless the corresponding endpoint and credential are configured.
 |---|---|---|
 | Local substring search | None | Local SQLite only |
 | Embedding-ranked search | Stored memory values that are not cached, plus the search query | `CAIRN_MEMORY_EMBEDDING_URL` or `CAIRN_LLM_API_URL` |
+| Separately opted-in memory reranking | Query and at most 50 scope/current/filter-admitted key/value excerpts, each at most 4 KiB | Only the explicit `CAIRN_MEMORY_RERANK_URL`; separate optional credential, no retries/redirects/alternate hosts |
 | `memory_extract` | The transcript supplied to the tool | `CAIRN_LLM_API_URL` |
 | `domain_knowledge_query` | Workspace slug and query | `ANYTHINGLLM_BASE_URL` |
 | `domain_knowledge_sync` | Files selected by the sync configuration | `ANYTHINGLLM_BASE_URL` |
@@ -50,6 +52,10 @@ Model endpoints may be local or remote. Cairnkeep cannot determine a provider's
 retention, training, or logging policy; verify it before sending confidential
 material. Disabling `CAIRN_LLM_API_KEY`, `ANYTHINGLLM_API_KEY`, remote HTTP
 registration, and delegated tools keeps the core memory workflow local.
+Also leave `CAIRN_MEMORY_RERANK` unset to disable its independent data flow;
+it does not require or inherit `CAIRN_LLM_API_KEY`. A local provider is still a
+separate process that receives these excerpts. Neither a chat agent nor a
+research assistant is part of reranking or authorization.
 
 ## Playbook decision and receipt flow
 
@@ -65,12 +71,12 @@ timestamp, and the supplied actor/session labels. It excludes prompt content,
 file content, patches, command output, secrets, endpoint values, and environment
 snapshots. Changed paths influence a decision but are not copied into receipts.
 
-In v2.15, actor identity is an unauthenticated local assertion even when a
+Local playbook actor identity remains an unauthenticated assertion even when a
 harness supplies it. Do not use receipts for employee monitoring,
-authorization, non-repudiation, or team access decisions. The future
-[team-mode contract](design/team-mode.md) requires authenticated subjects,
-deny-by-default ACLs, tenant isolation, retention, and append-only auditing
-before shared operation can ship.
+authorization, non-repudiation, or team access decisions. The separate
+[team preview](team.md) uses verified credentials and server-side memberships,
+never these labels. The broader [team-mode contract](design/team-mode.md)
+retains independent production-admission, isolation and retention requirements.
 
 ## Data at rest
 
@@ -91,11 +97,14 @@ backups/journals are sensitive local data at rest. Dry-run and commit responses
 contain scopes/address spaces, digests, keys, actions, and counts—not supplied
 or displaced values. No model, API key, endpoint, or network is required.
 
-The existing explicitly configured embedding search is the sole related egress:
-eligible key/value/type/tag text and the query may be sent to
+Explicitly configured embedding search can send eligible key/value/type/tag
+text and the query to
 `CAIRN_MEMORY_EMBEDDING_URL` (or its documented fallback). Hard filters run
 before that request; endpoint failure returns to local substring search. Note
-search is always local and never uses embeddings.
+search is always local and never uses embeddings or reranking. Separately
+opting into the [bounded reranker](memory-retrieval.md#optional-learned-reranking)
+can also send admitted memory excerpts and the query. It only changes ordering,
+never scope, history admission, approval, factual authority or durable memory.
 
 Canonical note storage includes manifest records, Markdown, indexes, history,
 import replay state, staged bytes, backups, and journals. Prepared/committing
@@ -692,3 +701,22 @@ skill readable; Cairnkeep never copies it into a harness or executes it.
 
 Pack digests and proposal digests protect integrity and stale-state detection;
 they do not authenticate a publisher or make extracted statements true.
+
+## Team preview flow and isolation
+
+The default-off [team preview](team.md) reads no personal memory automatically.
+Only explicitly supplied, inspected text becomes an immutable project proposal;
+only review by a different human credential publishes a shared revision.
+Workload tokens cannot review. The agent's local stdio bridge sends explicit
+organization/project requests and bearer authorization to the separately
+configured JSON API. Search uses substring matching, never an embedding/model
+provider. There is no background ingestion or sync.
+
+Membership and credentials, not cwd or local playbook actor labels, select
+authority. Server checks happen on every operation. Profile/capability
+restrictions only narrow MCP tools. Shared values, source digests and identities
+are stored privately; audit includes operation/outcome/digests without text or
+tokens. Backups include shared proposals and memberships and need separate
+encryption and access control. No unapproved personal content is discoverable.
+A hash confirmation does not establish human consent or content truth.
+Review and production admission remain separate operator responsibilities.

package/docs/security-assurance.md

@@ -222,3 +222,31 @@ fallback; its response cap is 8 MiB. OpenViking retains its 1 MiB cap, explicit
 consents and HTTPS-or-loopback rule. Both reject malformed UTF-8 and suppress
 network/stream diagnostics. Health probes use only `127.0.0.1` with a validated
 port and the existing private token resolver, and never follow redirects.
+
+## Team preview assurance boundary
+
+The [team preview](team.md) adds a separate authenticated organization/project
+boundary; it does not retrofit ACLs onto the existing personal HTTP server.
+Expiring/revocable credentials, independent project roles, workload-review
+denial, self-review denial, policy/base conflicts, immutable proposals and
+transactional publication/audit have maintained synthetic controls.
+The local MCP bridge has no review/admin tools, no scope fallback and a
+restrictive profile/capability intersection. The loopback JSON API rejects
+browser origins and unexpected Host headers, bounds requests/responses and
+rechecks authority after body receipt.
+
+`smoke-team*.mjs` additionally covers concurrent/cross-process state changes,
+audit failure rollback, oversized chunked bodies, restore integrity, revoked
+restored credentials, CLI exit and uninstall retention. Built-in SQLite needs
+Node 22.13+ only when opted in. Linux fixture execution is not native Windows
+evidence, and same-account processes remain trusted. Hash-linked local audit
+cannot detect an OS owner rewriting the entire chain; backups are unencrypted.
+Capacity exhaustion fails closed rather than removing audit history.
+
+The governed internal separate-context review and approved isolated native
+pilot are complete; this is not an external professional assessment or a study
+with two independent human participants. The released preview remains default
+off. Independent production security review, platform/package/container
+verification and a deployment-specific approved real-data pilot remain
+mandatory production gates. Inline review alone is not independent review.
+The service is token-first JSON HTTP plus local stdio MCP, not OAuth remote MCP.

package/docs/storage.md

@@ -602,3 +602,21 @@ store; it does not turn the proposal directory into a second memory authority.
 Context-usage receipts are strict links in the existing work-evidence store.
 They inherit work-evidence inspection, retention, and doctor behavior; there is
 no separate prompt or retrieved-content log.
+
+## Separate team store (opt-in 2.25 preview)
+
+[Team continuity](team.md) keeps organization/project records in a separate
+`team.db` under `CAIRN_TEAM_BASE_DIR` (default `~/.cairnkeep/team`). Built-in
+SQLite transactions serialize state and audit across processes; personal
+AgentFS stores and layouts are unchanged. No migration or automatic copying
+of personal memory occurs. The OS owner is trusted; stored text is unencrypted.
+
+Use `cairn team backup`, not a live directory copy, for a verified consistent
+snapshot. Restore publishes only a new directory, requires its exact digest,
+and revokes all copied credentials. Doctor verifies references, object hashes,
+audit links and temporary remnants without choosing a recovery state.
+Manual logical key deletion retains audit metadata and does not erase free
+pages, WAL or backup copies. Uninstall retains team data and refuses purge
+targets overlapping its configured directory. Independently selected
+`--data` stores must be outside purge targets or also configured through
+`CAIRN_TEAM_BASE_DIR`. Keep encrypted backups separately protected.

package/docs/team-pilot.md

@@ -0,0 +1,132 @@
+# An isolated team-continuity pilot
+
+This guide is for the opt-in Cairnkeep 2.25.0 team preview. It is **not production admission**.
+Obtain explicit pilot approval first. Keep automated rehearsal, human review,
+native-harness observations and release authorization as separate evidence.
+Use the exact matching source checkout for the source controls below, not an
+unverified global command or a production overlay. The released CLI includes
+the optional team commands, but installation does not authorize this pilot.
+
+The pilot runs beside existing personal memory: a new private store, expiring
+credentials, a separate loopback port and additional isolated client profiles.
+It never imports a personal store or replaces an existing MCP registration.
+Use synthetic project decisions, not employer, personal or customer data.
+
+## 1. Prepare a private lab
+
+Build the matching checkout. The following setup uses Bash on Linux/macOS; on
+native Windows use the equivalent explicit CLI commands from [Team continuity](team.md).
+Choose an absolute, **nonexistent** lab directory outside source checkouts,
+personal memory, backup stores and other private stores. Do not reuse an old lab.
+
+```sh
+TEAM_CAIRN=/absolute/path/to/feature-checkout/bin/cairn
+TEAM_PILOT_DIR=/absolute/private/new-team-pilot
+```
+
+Run this setup block in that shell. The operator chooses these two paths; the
+block refuses an existing lab directory. Credential values are never printed.
+
+<!-- team-pilot-setup:start -->
+```sh
+set -e
+: "${TEAM_CAIRN:?Set the absolute feature-checkout command}"
+: "${TEAM_PILOT_DIR:?Set a new absolute private lab directory}"
+case "$TEAM_CAIRN:$TEAM_PILOT_DIR" in /*:/*) ;; *) exit 1 ;; esac
+mkdir -m 0700 "$TEAM_PILOT_DIR"
+mkdir -m 0700 "$TEAM_PILOT_DIR/author-workspace" "$TEAM_PILOT_DIR/reader-workspace"
+TEAM_PILOT_EXPIRY=$(node -p 'new Date(Date.now() + 2 * 3600000).toISOString()')
+team_pilot_admin() {
+  (cd "$TEAM_PILOT_DIR" && env -i PATH="$PATH" CAIRN_TEAM=1 \
+    "$TEAM_CAIRN" team "$@" --data "$TEAM_PILOT_DIR/store")
+}
+team_pilot_admin init --organization trial-org
+team_pilot_admin project create trial-project
+team_pilot_admin project create unrelated-project
+team_pilot_admin member set author --project trial-project --roles reader,contributor
+team_pilot_admin member set reader --project trial-project --roles reader
+team_pilot_admin member set reviewer --project trial-project --roles reader,reviewer,auditor
+team_pilot_admin credential issue author --class workload --expires-at "$TEAM_PILOT_EXPIRY" --output "$TEAM_PILOT_DIR/author.token"
+team_pilot_admin credential issue reader --class workload --expires-at "$TEAM_PILOT_EXPIRY" --output "$TEAM_PILOT_DIR/reader.token"
+team_pilot_admin credential issue reviewer --class human --expires-at "$TEAM_PILOT_EXPIRY" --output "$TEAM_PILOT_DIR/reviewer.token"
+team_pilot_admin doctor
+```
+<!-- team-pilot-setup:end -->
+
+If setup fails, stop and inspect only that generated lab; do not rerun against a
+partially initialized directory. Keep the reviewer token outside both agent
+workspaces. File-only credentials are private, but processes under the same OS
+owner are not mutually isolated: use separate accounts or machines if that is
+part of the pilot's threat model. Do not claim role tests prove OS isolation.
+
+## 2. Start only the disposable service
+
+In a dedicated terminal, choose a separate unused port and run the exact feature
+command from the lab directory. Do not kill another listener to claim its port.
+
+```sh
+cd "$TEAM_PILOT_DIR"
+env -i PATH="$PATH" CAIRN_TEAM=1 CAIRN_TEAM_HTTP=1 \
+  "$TEAM_CAIRN" team serve --data "$TEAM_PILOT_DIR/store" --port 17955
+```
+
+Keep it in the foreground and use Ctrl+C for shutdown. It binds loopback only.
+A second machine needs an authenticated SSH tunnel, not a public API listener.
+Keep the production service, personal stores and existing MCP definitions intact.
+
+## 3. Use two additional client profiles
+
+Configure only a new `cairn-team-memory` stdio server in disposable profiles for
+the chosen harnesses. Do not edit their user-wide settings, trust lists or tokens.
+Use the feature command with arguments `team mcp --project-root WORKSPACE` and
+an explicit private workspace path for each client. Both clients receive:
+
+- `CAIRN_TEAM=1`, `CAIRN_TEAM_ORGANIZATION=trial-org`;
+- `CAIRN_TEAM_URL=http://127.0.0.1:17955` (or the explicit loopback tunnel);
+- `CAIRN_TEAM_TOKEN_FILE` pointing to **only** their own workload credential.
+
+Each tool call must explicitly name project `trial-project`; the working folder
+and client name do not select or grant project access.
+
+The author uses `author.token`; the other client uses `reader.token` and
+`CAIRN_TEAM_MCP_TOOL_PROFILE=read-only`. Never give either model `reviewer.token`,
+an administrative command, production credentials or an inherited cloud-provider
+key for this lab. Use a provider explicitly authorized for the pilot. Starting
+a server or downloading a model is not implicit subscription authorization.
+
+## 4. Exercise the actual review boundary
+
+Have the author propose one exact synthetic project decision, with explicit
+mutation consent. Record the immutable proposal ID, digest, selected bytes and
+provenance privately. The reader must not see it before publication.
+
+In the operator-only terminal, use `proposal-show` with the human reviewer
+credential to inspect the **actual stored proposal**, not an agent's paraphrase.
+Only after the reviewer explicitly approves those bytes, call `review` with
+the exact proposal digest as described in [the reference](team.md#harness-connection).
+Do not put a human token into an agent profile or script automatic human review.
+Checking a hash does not establish human consent or verify a person's identity.
+
+Restart the reader harness in a different empty working folder, retaining the
+explicit authorized team project. Verify it reads identical approved text and
+provenance. Capture actual tool-use evidence, not a model's claim of recall.
+Exercise an unrelated-project denial, a read-only proposal denial, membership
+removal on a connected client, and restore into a fresh store with old tokens
+refused. Do not change production roles or activate the restored lab implicitly.
+
+## 5. Record, stop and decide
+
+Keep a private, payload-free summary of source revision, client versions,
+projects/roles, consent method and outcomes. Label unattended SDK controls as
+automated rehearsal; do not turn their pass result into a human-pilot claim.
+Record missing steps and failures, including model/tool-use failures.
+
+Stop the foreground lab server. Verify its listener and clients have exited.
+Revoke lab credentials if retaining the store; retain or remove only the exact
+generated lab after preserving agreed evidence. Never purge a real memory base.
+Confirm production configuration hashes are unchanged. No team setting is
+enabled globally, so stopping the lab requires no production rollback.
+
+Independent security review, platform checks, pilot approval/results and release
+authorization remain distinct gates. Completing this guide does not itself
+authorize a merge, release, production enrollment or fleet deployment.