@cairnkeep/cli 2.24.0 → 2.26.0

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

@@ -0,0 +1,84 @@
+# V29 - Remember together without sharing everything
+
+Status: technical rehearsal brief for Cairnkeep 2.26.0 guided onboarding to the
+opt-in preview introduced in 2.25.0. Not a recorded or independently rehearsed lesson.
+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.
+Use the [role-based handoff](../../team-onboarding.md) connection card to show
+which steps belong to the operator, reader and human reviewer. Run its actual
+reader check in the disposable lab; never film a credential or replace the
+personal memory entry. Keep a pause on the pending deployment decisions.
+
+## 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.
+
+With a matching 2.26.0-or-newer client and team API, insert a short dynamic client segment:
+open the harness checkboxes in `team connect`, pause on the no-write plan and
+read-only default, then explicitly apply in a disposable project. Keep the
+personal MCP entry visible beside the new team entry. Run `team doctor --client`
+and zoom into expiry/project/roles, never the token file or original-config
+backup. Switch folders, show the pinned project, then plan/apply disconnect.
+Explain that disconnect is not revocation and running sessions need a restart.
+Use the maintained `smoke-team-onboarding.mjs` results for interruption/drift
+controls, not a fabricated typing transcript. The automated human-class policy
+fixture is not actual human consent; no independent-human trial is claimed.
+Do not record this addition against a 2.25-only client/API; follow the version
+note in the onboarding guide and verify the published package before recording.
+
+## 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/operating.md

@@ -962,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:
 
@@ -1541,3 +1542,22 @@ 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 2.26.0 guided client workflow is documented in
+[team onboarding](team-onboarding.md#guided-connection-next-release--matching-source-checkout):
+`team connect` plans before explicit apply, `team doctor --client` checks only
+authenticated project/credential metadata, and `team disconnect` preserves
+personal memory and credentials. Both client and team API must support 2.26's
+connection check. No ordinary setup or production sharing is enabled implicitly.
+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

@@ -14,7 +14,7 @@ below (some operator-owned endpoints do not require a credential).
 | 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_query` | Workspace identifier and query | Configured domain provider: `ANYTHINGLLM_BASE_URL`, or separately enabled `CAIRN_OPENVIKING_BASE_URL` |
 | `domain_knowledge_sync` | Files selected by the sync configuration | `ANYTHINGLLM_BASE_URL` |
 | `route_check` | A health request, with no memory or prompt content | `CAIRN_ROUTE_ENDPOINT` |
 | `context_explore` | Repository path and query are passed to the configured local executable | `CAIRN_EXPLORE_BINARY`; any further data flow is controlled by that tool |
@@ -57,6 +57,14 @@ 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.
 
+## Domain retrieval configuration
+
+Domain queries may derive a workspace identifier from local configuration;
+that identifier is intentionally disclosed to the chosen provider. This does
+not upload the configuration file or other local documents. See the
+[provider data-flow review](provider-data-flow-review.md) for the exact tested
+boundary and its limitations.
+
 ## Playbook decision and receipt flow
 
 Playbooks are local workflow policy, not model inference. A check reads the
@@ -71,12 +79,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
 
@@ -701,3 +709,34 @@ 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.
+
+The opt-in guided connection workflow stores endpoint/org/project IDs and a
+credential **file path**, never the credential bytes, in private client state.
+Its project-local MCP entry references that connection file; personal/global
+MCP configuration is not replaced. Private recovery snapshots copy the original
+harness configuration and may therefore contain preexisting operator secrets;
+keep them out of source control and protect/encrypt backups separately.
+Client doctor's authenticated metadata probe discloses the chosen project ID
+to the configured service and returns only subject, roles and credential
+ID/class/expiry. It neither reads memory text nor sends data to model providers.
+It appends a normal value-free service audit event. Disconnect retains backups
+and tokens and is not server-side revocation. See [onboarding](team-onboarding.md).

package/docs/provider-data-flow-review.md

@@ -0,0 +1,48 @@
+# Domain retrieval data-flow review
+
+The `js/file-access-to-http` findings in `domain-retrieval-provider.ts` trace
+the default workspace from the local memory configuration through
+`domain_knowledge_query` to the configured provider. The source is the
+`anythingllm_workspaces` field, not arbitrary document contents or stored memory.
+
+This is an intentional disclosure boundary, not evidence of no disclosure:
+the configured workspace identifier and the selected query leave the process.
+Only configure a provider trusted to receive both. A read-only MCP annotation
+means the tool does not mutate Cairnkeep state; it does **not** mean no network
+traffic. The tool's open-world annotation reflects this boundary.
+
+## Boundaries checked
+
+- Provider origin and authentication come from operator environment settings,
+  not workspace values or unrelated keys in a memory configuration file.
+- The default provider percent-encodes the workspace as one path segment. A
+  workspace that resembles a URL cannot select another origin or add headers.
+- The optional resource provider uses its fixed read-only endpoint, scopes
+  target identifiers below resources and rejects decoded traversal segments.
+  It requires explicit feature consent and separate remote-HTTP consent.
+- Neither request path reads, enumerates or uploads local documents. The
+  query tool is separate from explicitly approved document synchronization.
+- Both providers refuse redirects, bound responses and sanitize failures.
+  Do not weaken these controls to make a static-analysis finding disappear.
+
+`smoke-provider-config-flow.mjs` exercises the actual stdio MCP configuration
+path for both providers, including a URL-shaped workspace, unrelated file
+sentinels and forged endpoint/credential fields. It asserts the exact selected
+request body, fixed mock origin and operator-supplied authentication. All
+fixtures are synthetic and run against loopback only. Existing outbound tests
+cover redirect denial, consent, response bounds and payload-free failures.
+
+## Review disposition and limits
+
+The reviewed flows are expected provider-routing disclosures, not a discovered
+arbitrary-file-upload or file-selected-origin vulnerability. The alerts are
+not dismissed or suppressed by this change: retain the finding and this
+rationale for review, and reassess when source fields, destination selection,
+workspace handling or provider behavior changes.
+
+This is not a sandbox or a provider-side workspace ACL. A trusted local caller
+can explicitly choose another workspace served by its provider credential;
+the existing shared-token HTTP service is one trusted storage domain. Team
+authorization remains separate, and team retrieval does not use these providers.
+Same-account processes can change operator configuration. Tests establish the
+documented application boundary, not the trustworthiness of a configured host.

package/docs/security-assurance.md

@@ -138,6 +138,10 @@ prove a future privileged publish run succeeds.
 
 ## Verification evidence
 
+The [domain retrieval data-flow review](provider-data-flow-review.md) records
+the intentional file-derived workspace disclosure and its tested destination,
+credential and content boundaries. Static-analysis alerts are not suppressed.
+
 The maintained gates are `npm run security:baseline`, both production
 `npm audit` checks, `scripts/test-security-baseline.sh`, the memory-server
 security-assurance and HTTP-guard smoke tests, native-Windows tests, and the
@@ -161,6 +165,7 @@ node mcp-memory-server/scripts/smoke-runtime-file-reads.mjs
 node mcp-memory-server/scripts/smoke-bounded-input-reads.mjs
 node mcp-memory-server/scripts/smoke-workspace-file-security.mjs
 node mcp-memory-server/scripts/smoke-outbound-security.mjs
+node mcp-memory-server/scripts/smoke-security-fixture-order.mjs
 node scripts/test-runtime-file-security.mjs
 node scripts/test-omp-staged-security.mjs
 node scripts/test-container-health.mjs
@@ -173,6 +178,12 @@ assert that every historical CodeQL/Scorecard alert is fixed. Triage findings
 individually and use a fresh default-branch analysis to confirm alert status;
 never dismiss an uninvestigated finding merely to improve the score.
 
+The aggregate imports filesystem-hook fixtures sequentially. Top-level-await
+siblings are not a serial test runner: overlapping imports can restore another
+fixture's hooks and create a false failure before growth injection. The
+aggregate ownership/restoration observer covers this test-isolation contract;
+runtime reader checks and injection assertions remain unchanged.
+
 The developer-evidence follow-up also hardens the shared runtime note pre-image
 hasher: it reads from an inspected descriptor under a 64 MiB cap and rejects
 replacement or growth before accepting a hash. Missing targets remain valid
@@ -222,3 +233,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,35 @@ 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.
+
+Guided client connection state is separate from the organization database:
+`~/.cairnkeep/team-clients/<sha256-of-canonical-project-path>/` holds a strict
+versioned connection, private recovery receipt/original config snapshots and
+an exclusive sibling `<project-path-hash>.operation.lock`. Keeping the open lock
+outside the archived directory preserves native Windows rename semantics and
+continuous writer exclusion. Records contain token-file paths, not raw tokens.
+Original MCP configs can contain other secrets, so protect these backups.
+Activation is committed only after all selected entries are written. An
+interrupted connect stays inactive; interrupted disconnect can resume without
+overwriting unrelated edits. There is no automatic stale-lock cleanup.
+Disconnect archives state in a unique `.disconnected-*` sibling and retains
+credentials; uninstall/purge refuses to delete team client state/backups.
+See [client diagnostics/recovery](team-onboarding.md#client-diagnosis-and-recovery).

package/docs/team-onboarding.md

@@ -0,0 +1,226 @@
+# Team preview: a small, explicit handoff
+
+For Cairnkeep 2.25.0 or newer. This is **not production admission**;
+no real-data deployment is authorized by following this guide.
+
+## Choose the right workflow
+
+For your own context across sessions, folders and harnesses, keep ordinary
+`cairn-memory`. You already have that continuity; you do not need a team store.
+Use the team preview when another person should retrieve **selected, reviewed
+project decisions**. Personal memory stays separate. An overlay upgrade does
+not enroll anyone, start a team service or enable sharing.
+
+| Person | Responsibility | Keep separate |
+|---|---|---|
+| Operator | Private service, memberships, credentials and recovery | Deployment consent |
+| Reader / coding client | Own workload token and explicit project | Human-review token |
+| Contributor | Select/redact and propose exact text with consent | Publication authority |
+| Human reviewer | Inspect actual proposal, approve/reject its digest | Agent workspace |
+
+## Operator handoff
+
+For an explicitly approved **synthetic** rehearsal, follow the
+[isolated pilot setup](team-pilot.md#1-prepare-a-private-lab), then start its
+foreground loopback service. The tested recipe refuses an existing lab and
+preserves personal MCP settings. Do not use production paths.
+
+Give each participant a connection card: verified CLI version/path; loopback
+or authenticated-tunnel URL; organization/project IDs; their individual private
+workload-token file and expiry; disposable workspace; revocation contact.
+For this lab the IDs are `trial-org` and `trial-project`.
+
+Transfer tokens privately, never through chat, Git, arguments or recordings.
+Keep the reviewer token outside agent workspaces. Same-OS-owner processes are
+not mutually isolated; use separate accounts/machines when that is required.
+
+## Reader quick-check
+
+In a separate Bash terminal on Linux/macOS, set the operator's paths and URL:
+
+```sh
+TEAM_CAIRN=/absolute/path/to/verified-checkout/bin/cairn
+TEAM_PILOT_DIR=/absolute/private/new-team-pilot
+TEAM_PILOT_URL=http://127.0.0.1:17955
+```
+
+This block makes one read request. It does not create storage, issue credentials,
+start a service or edit a harness. Expect `[]` before any human publication.
+Stop on connection/authorization failure; never fall back to personal memory.
+
+<!-- team-reader-check:start -->
+```sh
+set -e
+: "${TEAM_CAIRN:?Set the verified CLI path}"
+: "${TEAM_PILOT_DIR:?Set the private lab directory}"
+: "${TEAM_PILOT_URL:?Set the loopback or authenticated-tunnel URL}"
+team_pilot_reader() {
+  env -i PATH="$PATH" CAIRN_TEAM=1 \
+    CAIRN_TEAM_URL="$TEAM_PILOT_URL" CAIRN_TEAM_ORGANIZATION=trial-org \
+    CAIRN_TEAM_TOKEN_FILE="$TEAM_PILOT_DIR/reader.token" \
+    "$TEAM_CAIRN" team "$@" --project trial-project
+}
+team_pilot_reader list
+```
+<!-- team-reader-check:end -->
+
+On native Windows, use equivalent explicit environment settings and
+`cairn team list --project trial-project` from [the reference](team.md).
+
+Add **only an additional**, disposable `cairn-team-memory` stdio entry:
+the verified command, arguments `team mcp --project-root WORKSPACE`, and the
+same four `CAIRN_TEAM*` settings above. For a reader, also set
+`CAIRN_TEAM_MCP_TOOL_PROFILE=read-only`. Merge into the isolated harness profile;
+never replace `cairn-memory` or its entire configuration. See
+[connection semantics](team.md#harness-connection).
+Each tool call names `trial-project`; cwd and display names grant no access.
+The MCP profile restricts tools; server membership independently restricts data.
+
+<a id="guided-connection-next-release--matching-source-checkout"></a>
+
+## Guided connection (2.26 or newer)
+
+The original preview and reader card above work on 2.25.0. The guided commands
+below require both the client **and team API** at 2.26.0 or newer. They do not
+change ordinary `cairn setup`, personal memory or the preview's
+production-admission boundary.
+
+After the operator supplies a **workload reader** credential, opt in explicitly:
+
+```sh
+CAIRN_TEAM=1 cairn team connect --project-root /absolute/project
+```
+
+The wizard asks for URL, organization/project IDs, a private credential-file
+path and harness checkboxes. Its default tool profile is read-only. It displays
+the planned files and asks before applying. Cancellation returns to the shell.
+For automation, supply every choice; without `--apply` this only plans:
+
+```sh
+CAIRN_TEAM=1 cairn team connect --project-root /absolute/project \
+  --url http://127.0.0.1:17955 --organization trial-org --project trial-project \
+  --token-file /absolute/private/reader.token --harness claude,opencode
+# Repeat the same command with --apply --yes to connect.
+CAIRN_TEAM=1 cairn team doctor --client --project-root /absolute/project
+```
+
+Never pass a token value. Keep the credential file outside this project's
+source tree and owner-only (POSIX 0600; native Windows private ACL). URLs must
+be loopback HTTP or HTTPS, without credentials, query, fragment or path prefix.
+Use the operator's encrypted authenticated tunnel, not a public unauthenticated
+listener. The command authenticates reader access before changing a harness.
+It refuses human-class credentials: the operator must issue a workload token
+for the agent, keeping human review credentials in the separate human terminal.
+
+| Harness choice | Project-local file | Additional entry |
+|----------------|--------------------|------------------|
+| `claude` | `.mcp.json` | `mcpServers.cairn-team-memory` |
+| `opencode` | `opencode.json` | `mcp.cairn-team-memory` |
+| `qwen` | `.qwen/settings.json` | `mcpServers.cairn-team-memory` |
+| `codex` | `.codex/config.toml` | marked `mcp_servers.cairn-team-memory` block |
+
+No global harness file is written. Existing unrelated entries are preserved;
+an existing team entry, duplicate JSON keys, JSONC or unsupported inline TOML
+causes refusal rather than replacement. OpenCode `opencode.jsonc` is not edited.
+Pi/OMP/Kimi use the manual bridge recipe; this wizard does not claim automated
+configuration for them. Harness-native trust/enablement prompts still apply.
+Adapter regression uses real SDK stdio calls, not live model/harness UI sessions.
+
+The generated entry invokes the verified Node/CLI paths with a private
+`--connection` file. It pins the server project even if the harness starts in
+another folder; each tool call still names that ID. It does not grant server
+membership. Contributors can explicitly select `--access full` to expose
+proposal creation, still subject to existing profile/capability restrictions
+and server authorization. Human review/admin tools never become available.
+Changing connection settings requires disconnect/reconnect; credentials may be
+rotated in place without a harness restart because the bridge rereads the file.
+
+### Client diagnosis and recovery
+
+Client doctor verifies the active managed entries and private credential file,
+then makes one authenticated `connection-check` request. It reports the current
+subject, credential ID/class/expiry, project and roles, **not** memory text,
+proposals, token values or environment snapshots. The service appends its normal
+value-free audit event. It opens no local administrator store and cannot issue
+credentials, grant membership or repair permissions. Wrong org/project, missing
+reader membership and expired/revoked credentials require the operator; failed
+team access never falls back to personal memory. Check the tunnel/TLS and API
+version on connection failure. Store doctor remains `team doctor --data DIR`.
+
+```sh
+CAIRN_TEAM=1 cairn team disconnect --project-root /absolute/project
+# Inspect the no-write plan, then:
+CAIRN_TEAM=1 cairn team disconnect --project-root /absolute/project --apply --yes
+```
+
+Disconnect removes only unchanged owned entries. It restores exact original
+bytes when nothing else changed; otherwise it preserves unrelated edits and
+refuses an altered team entry. It keeps the token and private backups. Restart
+existing harness sessions; disconnect is **not revocation**. The operator must
+revoke a credential/remove membership for immediate denial in running sessions.
+
+Connection records and original configuration snapshots are private under
+`~/.cairnkeep/team-clients/<canonical-project-path-sha256>/`. Backups may include
+secrets already present in your original MCP config: never commit or publish
+them; use separately encrypted backups as appropriate. No token content is
+copied from its file. Disconnected records are retained in uniquely named
+`.disconnected-*` siblings. Uninstall/purge refuses to delete this retained state.
+
+A per-project exclusive `<project-path-hash>.operation.lock` beside the state
+directory serializes Cairnkeep writers and stays held while state is archived,
+including on native Windows. A failed
+multi-file connect keeps its recovery record in `preparing`; the bridge refuses
+startup until **all** entries are written and activation is committed. Run
+disconnect to undo an interrupted operation after checking for configuration
+drift. An interrupted disconnect is likewise resumable. Do not restore a whole
+backup over newer unrelated edits. If the process crashed holding its lock,
+first verify no connection/disconnection process is running, preserve the state
+directory, then manually remove **only that project's** sibling `.operation.lock` and
+retry disconnect. The tool never guesses that a live lock is stale.
+
+Configuration directories must be owned/trusted and not writable by other users.
+Each configuration is bounded to 1 MiB and the four-file recovery record to
+16 MiB, including both original/new bytes and base64 overhead.
+Links and unsafe files are rejected. Writers use bounded descriptor-first reads,
+exclusive creation and atomic replacement with a final drift check. This is not
+an OS compare-and-swap against a hostile process running as your own identity;
+stop concurrent editor writes before applying. No root-directory or global
+configuration target, automatic permission changes to existing directories,
+automatic enrollment or background synchronization is introduced.
+
+## Contributor and reviewer
+
+Contributors get their **own** workload credential and explicit contributor
+membership. Start with one synthetic decision; select/redact exact text and
+confirm its value digest using the [proposal reference](team.md#harness-connection).
+There is no automatic personal-memory import.
+
+In the separate human terminal, inspect `proposal-show`, then approve/reject
+the actual stored bytes with their proposal digest. Never hand a human token
+to a model. Automated tests of human-class tokens are not human consent.
+Restart a reader in another folder: the approved decision/provenance must match;
+unrelated-project access and revoked credentials must fail. Follow the
+[pilot checks and cleanup](team-pilot.md#4-exercise-the-actual-review-boundary).
+Native trials require separately authorized providers; no model purchase or
+subscription use is authorized by this guide.
+
+## Deployment readiness
+
+Before requesting a real-data pilot, record an owner and evidence for:
+
+- **Purpose:** project IDs, participants, data classes, one continuity use case,
+  explicit exclusions and a stop date.
+- **Consent:** selected-data approval, independent production security review
+  and deployment authorization. Mark absent decisions pending; tests supply none.
+- **Access:** least-privilege roles, individual expiring tokens, separate human
+  review, authenticated tunnel/TLS, private storage and trusted host ownership.
+- **Operation:** named operator, revocation/offboarding contact, storage/audit
+  capacity, encrypted backup retention and a rehearsed fresh-only restore.
+  Restored credentials are revoked; reissue and activation remain explicit.
+- **Acceptance/rollback:** continuity across clients/folders, denied/unapproved
+  content hidden, immediate revocation and unchanged personal config hashes.
+  Stop the separate service and remove only its additional client entry to
+  withdraw access; preserve agreed private evidence.
+
+Until these decisions are explicitly approved, stay in the disposable synthetic
+lab. No automatic production transition follows the rehearsal.