Foundocs setup

Use the installation prompt from your project's Foundocs integration guide. It contains a ten-minute, one-use connection code, never an API key. The coding agent fixes an absolute project root and sends the prompt's JSON to the installer's private stdin using a process tool. Do not paste the JSON into shell command text, argv, logs, or a committed file.

Version 0.3.5 extends portable project MCP settings to Claude Code. Both clients run the shared exact-version npm runtime while each installation key stays in private local storage. Existing owned Codex absolute-path and Claude HTTP helper configurations can migrate without exchanging a code or rotating a key. For local development verification, build this package and run from its directory:

node src/cli.mjs install --root /absolute/project
node src/cli.mjs doctor --root /absolute/project
node src/cli.mjs rollback --root /absolute/project
node src/cli.mjs migrate --root /absolute/project

The install command reads stdin until EOF. Commands never take codes or API keys as arguments. This package requires Node.js 22.19.0+ and a locally installed Claude Code or Codex CLI. Before exchanging the code it inspects the installed CLI's project stdio MCP support, parses existing settings and checks private storage permissions. Missing or incompatible CLIs require installation/update or the manual guide. Codex's desktop app without its CLI cannot pass this automatic feature check.

Input JSON follows SetupInstallInput version 1: client (claude or codex), projectId, workspaceId, attemptId, code, exchangeUrl, mcpUrl, and version: 1. The code is exchanged once for an installation key; same-attempt reruns reuse that private key. A newly issued attempt can replace a revoked key while retaining the previous key privately. Existing keys are never automatically revoked.

Configuration is local to the exact --root: foundocs.json, a marked AGENTS.md block, and either .codex/config.toml or .mcp.json. Claude additionally receives a marked CLAUDE.md reference to AGENTS.md. The package also installs its English Foundocs skill at .agents/skills/foundocs/ for Codex or .claude/skills/foundocs/ for Claude, including the Dreaming protocol reference. The managed instruction block points to the selected client’s discoverable skill. Existing instructions and foreign MCP entries are preserved. Skill files are updated only when unchanged from the installer’s recorded version. Byte-identical packaged files in a new clone are adopted locally; other foreign or user-edited skills stop preflight, and rollback preserves later user edits. Run update-skills to add the bundled skills to an older installation without a new connection code. Manual knowledge archival/restoration uses the server-discovered set_knowledge_status tool on explicit request; the bundled Foundocs skill documents versioned writes, archived lookup and the separate Dreaming approval path. Existing installations receive this guidance through update-skills; ordinary capture does not authorize archival. The bridge discovers tools dynamically, so server tool additions do not require a runtime upgrade. Dreaming itself requires the connected server to expose dream_memory and get_dream; installation does not enable unavailable server capabilities. Conflicting project IDs, malformed files, symlinks, or a different same-name foundocs server stop installation before exchanging the code. Resolve a conflict explicitly; this installer does not overwrite it.

Keys, backups and installation journals live in ~/.local/share/foundocs/setup, outside the project. FOUNDOCS_SETUP_HOME may select another absolute private directory outside the target project, including isolated test fixtures. Keep using that same value for doctor/rollback. Credentials are isolated by workspace, project, and canonical project root. Both clients use the exact-version npm package’s mcp command through npx on PATH; their project settings contain no user-specific path. Older copied helpers remain in private storage for compatibility and rollback, but portable MCP does not depend on them. Its stdio adapter forwards MCP tool discovery and calls to the same Remote HTTP endpoint with the saved Bearer key. This adapter preserves remote schemas, annotations, structured results and errors, and requires an explicit valid project ID on every call. A changed valid project ID is forwarded unchanged; the remote server enforces workspace access. It adds no remote service. macOS/Linux use user-only directories/files (0700/0600). Windows uses PowerShell to apply and verify a protected current-user-only ACL; unsupported ACL filesystems stop before code exchange.

The helper prefers the saved installation credential. To explicitly use a process-provided FOUNDOCS_API_KEY, also provide matching FOUNDOCS_PROJECT_ID and FOUNDOCS_WORKSPACE_ID. An unrelated shell key never silently overrides the saved workspace key. The legacy HTTP helper’s stdout contains authentication headers solely for the host MCP client; do not invoke it through tools that log stdout. The shared portable runtime writes only MCP messages to stdout.

Version 0.2.0 recognizes recorded 0.1.x installations in their original private location. Reinstalling migrates their project filename, managed instruction markers and selected client's server name while retaining credential paths and the rollback journal. Existing doctor and rollback commands can discover the old location. Two recorded default locations are treated as a conflict; choose the intended location explicitly with FOUNDOCS_SETUP_HOME. A historical custom storage override remains supported when no current override is supplied. Credentials and helper directories are never moved automatically.

Migration refuses differing project IDs, foreign or duplicate server entries, malformed/mixed instruction markers and unsafe files before exchanging a code. It writes the new project configuration before replacing managed instructions and removes the old filename last. Every file write is atomic and journaled; the multi-file operation is recoverable rather than transactional. A retry reuses the same saved key. Rollback preserves the original installation baseline if an older journal exists; otherwise it restores the files as they were before migration. Manually changed or inline historical TOML server definitions require explicit conflict resolution. The private compatibility module also accepts a complete, matching historical credential namespace, only when no current credential variable is present.

Doctor performs MCP initialize, tool discovery, and get_project_context with the exact project ID. diagnostic_passed means the independent diagnostic succeeded. You must still trust/reconnect the project in the selected host and call its MCP tool to verify that host. Setup never reports host connection from file creation alone.

For response loss or failure before private key storage, the error reports the attempt ID and guide recovery route: inspect/revoke only that attempt's issued key and generate a new code. After key storage, rerun the same installation input. rollback restores only files still matching the installer-written content; concurrent edits are retained and reported. It preserves private credentials for retry. A stale operation lock after process interruption is never automatically deleted: confirm no installer is running before removing the reported private lock file.

Shared Codex projects

Commit foundocs.json, the project .codex/config.toml, and the managed instructions/skills when the team shares them. A newly generated entry uses this transport (the actual file also lists supported environment variable names, never their values):

[mcp_servers.foundocs]
command = "npx"
args = ["--yes", "@foundocs/[email protected]", "mcp", "--project-id", "YOUR-PROJECT-UUID"]
env_vars = ["FOUNDOCS_SETUP_HOME", "FOUNDOCS_API_KEY", "FOUNDOCS_PROJECT_ID", "FOUNDOCS_WORKSPACE_ID", "STEERDOCS_SETUP_HOME", "STEERDOCS_API_KEY", "STEERDOCS_PROJECT_ID", "STEERDOCS_WORKSPACE_ID"]
startup_timeout_sec = 60

Each teammate runs the integration prompt once for their own clone. This creates a local private manifest/key scoped to that canonical checkout; it retains the existing valid portable TOML byte for byte. Copying, moving or cloning a checkout does not transfer its authentication. A missing local installation returns a redacted error explaining how to install or diagnose it. No .env loader is needed, and the agent never reads the API key.

The host must have Node.js 22.19.0+ and npm/npx on its PATH. A desktop launched without your shell's PATH may need its environment configured or a restart. The first uncached npx launch requires npm registry access; later launches use npm's normal cache. The runtime version is pinned to an exact release for reproducibility. Reinstalling/authenticating with a newer installer preserves an existing valid pin; update-skills never upgrades the MCP runtime. An intentional runtime update is a reviewed change to the shared pin, followed by local install/migrate and host verification. A pinned registry command requires that release to have been published; local pre-release verification uses a packed artifact installed in an isolated fixture.

The runtime starts from the host's working directory and selects the nearest foundocs.json. It stops at a Git checkout boundary, a malformed nearer file or a project-ID mismatch. It never searches another checkout for a working credential. It validates the canonical root, project/workspace IDs, endpoint, recorded attempt, expected private credential path and file permissions before opening the remote connection. The explicit --project-id protects a nested project from silently inheriting its parent's transport. These are startup identity checks: tool calls still pass their explicit project_id unchanged and the remote server retains its existing workspace authorization rules.

FOUNDOCS_SETUP_HOME selects custom private storage through the host environment. Keep the same value when installing, starting Codex, diagnosing, migrating and rolling back. Supported scoped API-key override names and historical equivalents are forwarded through env_vars; values stay outside Git. Per-server cwd, env and URL overrides are rejected by setup/doctor because they can silently change installation selection. Tool allowlists and timeouts are preserved.

Existing Codex installations

After this release is published:

npx --yes @foundocs/[email protected] migrate --root /absolute/project
npx --yes @foundocs/[email protected] doctor --root /absolute/project

migrate is offline, requires no connection code, and retains the credential bytes. It verifies the private manifest and journal against the original absolute transport, edits only the owned server's transport fields and preserves unrelated TOML, comments, tool settings and timeouts. Missing ownership evidence, changed execution settings and unsupported inline tables stop with the original file intact. An install rerun can perform the same migration while reusing its saved same-attempt key. update-skills remains skill-only.

Writes use the existing lock, atomic replacement, concurrency check and rollback journal. If interrupted, retain the journal and rerun the same command; confirm no process is running before clearing a stale lock. rollback restores unchanged setup edits to the recorded baseline and preserves later user edits and credentials. The baseline may predate migration when an installation already has a journal. After migration, restart/reconnect the trusted Codex project and call get_project_context through its MCP server. Doctor reports legacy transport migration separately from conflicting portable configuration; an independent doctor call does not prove the host connected.

Shared Claude Code projects (0.3.5)

Commit the project .mcp.json alongside foundocs.json, instructions and .claude/skills when sharing a Claude project. A fresh Claude installation generates:

{
  "mcpServers": {
    "foundocs": {
      "type": "stdio",
      "command": "npx",
      "args": ["--yes", "@foundocs/[email protected]", "mcp", "--project-id", "YOUR-PROJECT-UUID"]
    }
  }
}

Every teammate runs the integration prompt once in their clone to save their own installation key. The shared JSON remains byte-identical when it already has a valid supported pin. Claude’s stdio process inherits the host environment: start Claude with Node/npm/npx on PATH and, when applicable, the same FOUNDOCS_SETUP_HOME and matching scoped credential override variables. No private environment value belongs in .mcp.json. The first uncached launch can require registry access. Approve the project MCP server in Claude before connecting.

Claude uses the same working-directory resolution, project ID guard, private manifest/credential checks and redacted errors as Codex. CLAUDE_PROJECT_DIR does not override root selection. Runtime 0.3.5 is the first version that accepts Claude installation manifests; a Claude pin to 0.3.4 is rejected. Existing Codex 0.3.4 pins remain supported and are not upgraded by reinstall or update-skills.

For an existing Claude HTTP headersHelper installation, run the same migrate --root /absolute/project command above with 0.3.5. Migration verifies the recorded helper command, private credential scope and endpoint before converting it to stdio. It performs no key exchange or remote request, retains unrelated JSON values and server settings, and supports retry and rollback. Modified endpoints/helpers, extra authentication or execution overrides, and missing ownership evidence are conflicts. JSON whitespace may be normalized during conversion; an already-portable configuration is left byte for byte unchanged. doctor points owned HTTP installs to migration, distinguishes configuration conflicts, and independently checks MCP connectivity. update-skills changes neither connection settings nor keys.

Before release, the 0.3.5 tarball was tested through both clients’ private installation records and real HTTP MCP. The macOS Claude CLI loaded the generated .mcp.json at project scope and reported Connected; a protocol client using the same generated command completed discovery and get_project_context. The real Codex host also discovered the tools and completed a read call. Claude was not logged in, so model-driven Claude tool selection was not verified. Public npm publication and Linux/Windows host verification are separate release checks.

Verification status

The implementation includes unit/integration tests for both configuration formats, preservation, reruns, conflicts, credential isolation, redaction, recovery, rollback, protocol diagnostics, path quoting and ACL command generation. Local feature checks pass on macOS with Codex CLI 0.149.1 and Claude Code 2.1.284. Windows/Linux command paths are implemented, but real runtime verification on those operating systems is still required before claiming them verified. Package automated tests use isolated host capability fixtures. The 0.3.4 packed artifact was additionally verified in the product repository on macOS with a real Codex host, an isolated trusted CODEX_HOME, the generated project configuration, and an actual HTTP MCP get_project_context call. This does not verify Linux/Windows or a public npm release.

Development: npm ci, npm test, and npm run typecheck.

Knowledge skills (0.3.1)

The 0.3.1 source includes the English foundocs-capture-knowledge skill and writing guide, plus the foundocs Dreaming skill and protocol reference. install copies the same bundle into .agents/skills/ for Codex or .claude/skills/ for Claude Code, and adds a compact bootstrap with exact skill links and trigger conditions to its managed AGENTS block. Configuration validation, document/knowledge policy, update checks and Dreaming procedures are read from the selected skill and its references only when needed. The bootstrap retains same-turn knowledge-capture and explicit Dreaming triggers, plus the governing configuration location; unrelated tasks do not need the full procedures. Claude also receives the existing CLAUDE reference. Explicit user destinations and repository spec conventions take precedence over default Foundocs storage.

Existing recorded installations can update the skill and managed instructions without supplying a connection code, contacting the service or rotating credentials:

node /absolute/path/to/foundocs-setup/src/cli.mjs update-skills --root /absolute/project

The equivalent command for this release is npx --yes @foundocs/foundocs-setup@latest update-skills --root /absolute/project. The local commands above run this checkout; a pinned npm command requires that registry release to exist.

Updates preserve MCP settings, project configuration, authentication helpers and private keys, including installations that still use the historical configuration filename. The private skills.json records installed/pending asset hashes for interruption recovery. Foreign same-name files and local skill edits stop installation/update before project writes; move or reconcile the reported file explicitly, then retry. Unrelated skills and instructions are retained. rollback includes skill assets and preserves concurrent edits.

doctor reports missing, outdated or conflicting skill files separately from MCP diagnostics and points to update-skills. A successful skills.status: installed verifies files only; the selected host must still discover the skill after reconnection/restart when needed. Neither setup nor doctor claims that a model executed the skill or will always follow it. A SessionStart skill-update hook is installed; no background knowledge collection is installed.

The package's skills/ and templates/ directories must be included in every tarball. Run package tests and a packed-CLI smoke check before publishing; keep production's exact version pinned to a registry-verified release.

Dreaming adversarial fixtures and trace checks live in eval/; see eval/README.md. These checks do not claim real-model quality evaluation.

Knowledge folders (0.3.8)

The bundled capture skill reuses existing topic folders beneath the fixed knowledge/rules/, knowledge/learnings/ and knowledge/decisions/ roots. Nested topic folders and files directly under a root are both valid. Related facts stay together rather than becoming fragments or duplicate shallow folders. Verified, reusable lessons from correcting the agent’s own mistakes are captured in the same turn; typo-only and unverified fixes are excluded.

Dreaming inspects dispersed knowledge and similar folders within its existing six stages. Consolidation compares concrete topic groups, destination folders and retrieval benefits, including files still directly under a category root. Clear filenames alone do not justify skipping that assessment; justified moves are submitted, while a zero-move result records why the candidate groups should stay in place. The review avoids fragmentation and cosmetic churn rather than requiring a move quota.

Only a server-verified path-only update within the same category may be applied automatically: body, title, TL;DR, ordered tags, creation date and other metadata must stay unchanged. Semantic, category and mixed changes retain owner review. Older servers without explicit automatic-move support receive review candidates. Prior moves and proposal history guide deduplication so repeated runs avoid cosmetic renames.

The skills explain stable IDs, previous-path aliases, relative-link bases, move receipts and versioned requests. Ordinary move undo uses the discovered get_content_moves / undo_content_move tools on explicit request; a Dreaming move returns to the exact saved proposal’s owner review for revert. New server tools are discovered dynamically. This release updates guidance, not an older server’s capabilities. Existing installations receive the guidance through update-skills or their enabled SessionStart update hook.

Session discovery

The Foundocs skill reached through the managed bootstrap guides the agent to resolve the configured project and read get_project_context({ project_id, view: "index" }) once on the first use of each project in a session. The compact index combines frequently retrieved, recently beneficial and recently updated documents and knowledge. It is a discovery shortcut: if an entry is absent or insufficient, the agent continues with metadata, path and body searches across active content. Index exposure does not add retrieval records.

Older servers without index mode remain usable through the existing context call and search tools. Index retrieval remains agent guidance; the separate SessionStart hook updates skill files only. The same instructions ship in new installations and update-skills.

Automatic skill updates

Setup and update-skills install a SessionStart command hook in .codex/hooks.json (Codex) or .claude/settings.json (Claude Code), preserving unrelated hooks and settings. On startup, resume, clear or fork, it checks public npm metadata and automatically installs a newer stable release using its exact version. Each event performs a fresh lookup, rather than reusing the manual checker's 24-hour cache. Only Foundocs skills, managed instructions and this hook are updated; MCP runtime pins, connection settings and keys stay unchanged.

Existing installations enable this once, without a new connection code:

npx --yes @foundocs/foundocs-setup@latest update-skills --root /absolute/project

The same command is the manual update command. Host trust still applies: review and trust new hooks with Codex /hooks, and accept the project settings/hook review in Claude Code. Disabled or untrusted hooks do not run. Never bypass the host's trust policy. Restart/reload the host if needed; installation does not prove host execution. Claude's hook requests a skill re-scan after a successful update; already loaded Codex instructions may require a reload.

The registry request has a five-second timeout and package execution a 45-second timeout. Failures remain non-blocking and do not print credentials or raw child output. Setup locks, asset hashes and hook ownership prevent concurrent writes and overwrites of local edits; a newer installed release is never downgraded by update-skills. Resolve a reported conflict manually, then rerun the command. Remove or disable the Foundocs SessionStart handler in the host to opt out; setup will preserve a modified/removed managed hook as a conflict rather than silently restoring it.

The bundled check-update.mjs remains a read-only manual version checker, with its 24-hour cache and deferral support for older clients. It does not itself install packages. The automatic hook intentionally ignores those old offer/deferral decisions. Private check state lives under ~/.local/share/foundocs/setup/update-checks or the corresponding FOUNDOCS_SETUP_HOME directory. The installer manages both scripts, foundocs/release.json and the hook through its update/rollback lifecycle.

Archival and Dreaming

The bundled Foundocs skill uses live tool discovery for set_content_status (atomic 1–100 document/knowledge archive or restore), get_archive_candidates (run-scoped review evidence) and approve_archive_proposal (one archive-only proposal explicitly approved by the human in chat). Existing set_knowledge_status remains compatible on servers with only single-knowledge archival. The stdio bridge forwards server tool schemas and responses dynamically; no hardcoded tool list or runtime upgrade is needed just to expose these tools.

Manual identified targets execute on explicit request. Dreaming never archives automatically: the 168-hour/four-negative-evaluation threshold selects review candidates, current bodies and beneficial uses must also be assessed, and only specific current human approval applies a proposal. Content-grounded low future reuse value is also a reason to propose archiving unnecessary knowledge, even if it is factually correct and has no retrieval history; rare but useful rules, decision context and recovery lessons remain protected. Documents gain archive proposals only. See the Dreaming protocol and evaluation cases. Test new installs and skill updates in isolated fixtures; do not overwrite a developer's edited installed skills.

Source and releases

This repository contains the installer, bundled agent skills, templates and tests for @foundocs/foundocs-setup. The Foundocs application and server are maintained separately. Use this repository for installer changes and releases.

Releases are published from GitHub Actions using npm Trusted Publishing (OIDC), without a stored npm write token. A public repository allows npm provenance to link a published package to the exact source commit and workflow; it does not certify the code's safety. Existing releases published before this workflow do not gain provenance retroactively.

One-time maintainer setup in the npm package's Settings → Trusted Publisher:

• Provider: GitHub Actions
• Organization or user: foundocs
• Repository: foundocs-setup
• Workflow filename: publish.yml
• Environment: leave empty
• Allow direct publishing with npm publish; stage-only publishing requires a manual approval.

Complete the first publish within npm's configuration validation window (currently two days). If that window expires, recreate the publisher configuration before releasing.

To release after reviewing and merging the package changes into main:

npm ci
npm test
npm run typecheck
npm version patch
git push origin main
git push origin --follow-tags

npm version patch creates a version commit and annotated vX.Y.Z tag. The publish workflow validates the tag against package.json, runs the tests, builds the package and publishes it publicly with provenance. Each npm version can only be published once; use a new version for the first automated release if the current version already exists.

See npm Trusted Publishing.

Optional effect measurement (0.3.15)

The installed Foundocs skill automatically checks the project policy once per information task. When an administrator has enabled measurement, a supported shell host freezes a short pre-retrieval brief and allowlisted local source snapshot before its first index/search/read, then runs one measured pair after a beneficial retrieval. Users do not need to type a command for each task. Policy remains OFF unless a web owner/admin explicitly changes it.

The initial verified probe runner is Claude Code 2.1.312 on macOS, with an existing Claude login and an exact model ID such as claude-haiku-5-5. Codex and Claude shell hosts can coordinate it. Codex-native probes, Linux/Windows pending platform canaries, shell-less hosts and missing isolation/authentication are reported as unsupported without a fallback. Child tools are restricted to Read/Glob/Grep in separate snapshots; only the coordinator receives Foundocs credentials. The watchdog also terminates the provider CLI when its coordinator crashes.

foundocs-setup measure prepare|run|flush --root ABSOLUTE_PATH accepts private stdin JSON. The installed procedure defines the exact inputs and automatic host sequence. This is an opt-in sampled information-acquisition comparison, not whole-task savings. Actual input/output/cache usage and nullable estimated USD are kept separately, including failed and cancelled costs. Max turns and estimated USD settings are not hard API/billing caps.

Raw local data expires at preparation +24h; normalized settlement data has its own finite completion +24h lifetime. Expired raw data cannot be restored by a concurrent journal write. Uncertain report transmission retries the same requestId and payload without repeating model inference. Raw CLI transcripts are not stored by default.

Maintainers can run the opt-in synthetic checks with FOUNDOCS_EFFECT_LIVE_CHECK=1: node eval/effect-isolation-check.mjs checks actual filesystem tool boundaries; eval/effect-api-check.mjs, executed using the product checkout's tsx runner with FOUNDOCS_PRODUCT_DIR and optional FOUNDOCS_EFFECT_CLI, uses its isolated PostgreSQL/HTTP fixture. These checks incur provider usage, never enable a production project, and remove their temporary fixtures.

Automatic selective episodes (0.3.19)

New Codex and Claude Code installs include foundocs-capture-episode, a UserPromptSubmit checkpoint and a bounded Stop fallback. Review and trust the installed hook definitions through the host (Codex /hooks or desktop hook review; Claude Code project hook/settings review). The installer never changes host trust, approvals or sandbox settings. Confirm actual hook execution and remote capture_episode plus local episode_checkpoint tool discovery after reconnecting; installed files alone do not prove activation.

The current host judges important confirmed decisions, verified results and discoveries, concrete blockers and milestones during ordinary work. Routine turns are acknowledged locally without creating remote candidates. Private checkpoint state contains only minimal identifiers; prepared requests contain brief evidence, never transcripts. The bounded outbox preserves the exact payload/requestId for uncertain retries (32 requests, 128 checkpoints, 14 days per prepared request; cleanup on use). Required checkpoint metadata remains until its pending requests settle/expire, at most 28 days after checkpoint creation; expired checkpoints cannot prepare new requests. Stop can request one follow-up per checkpoint and never loops on a failed write. There is no separate inference API or new model key.

The local MCP episode_checkpoint tool runs bookkeeping inside the existing stdio process, so ordinary capture needs no extra shell filesystem access. It is available only with the new portable runtime and a server advertising capture_episode. The server's episode tools still handle all remote writes. POSIX private storage is supported; Windows currently skips checkpoint capture. Unsupported/missing tools and failures preserve ordinary work and never turn an episode into a document. Document consent and Dreaming consent are unchanged.

Existing installations: update-skills and SessionStart updates deliberately preserve the pinned MCP runtime. To opt an installer-owned portable runtime into this release, run the new package's explicit upgrade, then refresh skills:

npx --yes @foundocs/[email protected] upgrade-runtime --root /absolute/project
npx --yes @foundocs/[email protected] update-skills --root /absolute/project

Legacy transports must first use the existing migrate flow. The upgrade checks the recorded transport, preserves foreign settings and credentials, journals its change and supports interrupted retry. Version 0.3.20 recognizes the environment list written by pre-episode portable runtimes, including 0.3.18; newer runtimes still require the episode opt-out environment variable. The existing conflict-safe rollback restores the original installation journal baseline, which can precede initial setup; it is not a runtime-only undo command. Reconnect MCP and review the exact new hook hashes afterward. Skill updates do not silently activate or upgrade the runtime. doctor reports runtime support and live/stale checkpoint locks separately from host verification. If a crashed helper leaves a stale lock, confirm its process has ended and remove only the reported lock; preserve the outbox and credentials.

Opt out without editing managed hooks/skills by adding "episodes": {"enabled": false} to foundocs.json, or launch the host with FOUNDOCS_EPISODES=off. Deleting/modifying managed hooks is treated as an update conflict; other hooks and user-edited skills remain preserved.

For opt-in live package validation, eval/episode-host-check.mjs (run with Bun) installs a .tgz into isolated projects backed by the product HTTP/PostgreSQL fixture. Supply FOUNDOCS_EPISODE_LIVE=1, FOUNDOCS_PRODUCT_DIR, FOUNDOCS_EPISODE_PACKAGE, and the test database URL. It never edits host trust. Review the generated project in each actual host, perform an ordinary task and a trivial lookup, then send verify to inspect persisted episodes. This fixture is separate from deterministic unit tests and does not claim model execution merely because installation succeeded.

After starting that fixture, eval/episode-host-run.mjs runs an ordinary model turn and asserts the observed tool path. Set FOUNDOCS_EPISODE_CLIENT to codex or claude, and FOUNDOCS_EPISODE_CASE to important or routine. Codex additionally requires an explicit FOUNDOCS_EPISODE_MODEL and FOUNDOCS_EPISODE_REVIEW_HOOKS=1 after reviewing the generated commands. This opt-in test uses the host's exact-hash hook review RPC in an isolated temporary CODEX_HOME, with workspace-write and on-request approvals. It never alters the real user configuration. Claude uses project/local settings and a scoped tool allowlist, with no permission bypass. eval/episode-api-check.mjs separately checks scripted API scenarios; those are not reported as host model evidence.