> ## Documentation Index
> Fetch the complete documentation index at: https://prism.ntecdev.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Host Contract

> What `prism install` promises to the MCP server runtime, and what runtime is allowed to assume. The boundary between install-time and runtime-time host concerns.

# Host Contract

What `prism install` promises to the MCP server runtime, and what runtime
is allowed to assume.

## Core principle

> **Cross-platform is a core tenant of Prism.** Prism-the-process (MCP
> server) detects its OS at runtime. Prism-the-project (the codebase)
> must ship code that runs correctly on macOS, Linux, and Windows.

The install does all host detection **once**, at install time, and writes
the results into each editor's MCP `env` block. Runtime reads env. This
eliminates detection drift between install and runtime, and between
different agents running against the same install.

## What install writes into each editor's MCP env block

| Variable            | Source at install                           | Consumed by                                |
| ------------------- | ------------------------------------------- | ------------------------------------------ |
| `PRISM_API_URL`     | personal default / LAN / cloud arg          | backend client                             |
| `PRISM_API_KEY`     | `~/.prism/credentials.personal.json` or arg | backend client                             |
| `PRISM_ROOT`        | bootstrap script location                   | path resolution, scaffold lookups          |
| `PROJECT_ROOT`      | `$PROJECT_ROOT` env or `~/projects`         | `prism_clone`, `prism_create` default dir  |
| `PRISM_GITHUB_USER` | `git config --global user.name` or asked    | `prism_clone` auto-derive of `github_repo` |
| `PRISM_HOST_OS`     | `platform.system()` normalized              | editor config path resolution              |
| `PRISM_APP_SUPPORT` | per-OS config root                          | editor config path resolution              |
| `PRISM_FS_MCP_NAME` | default `projects-filesystem`               | filesystem MCP block name                  |
| `LOG_DIR`           | `$PRISM_ROOT/logs`                          | log file writes                            |

## What runtime is allowed to assume

1. **`PRISM_API_URL` + `PRISM_API_KEY` are set** and reachable via HTTP.
   If not, preflight warns; backend calls fail cleanly.
2. **`PROJECT_ROOT` is writable** by the user running the MCP server.
3. **`PRISM_HOST_OS` is one of `darwin`, `linux`, `win32`.** If unset,
   runtime falls back to live `platform.system()` and logs the gap.
4. **`PRISM_GITHUB_USER` is a valid GitHub handle** (no spaces, no slashes).
   If unset, `prism_clone`'s auto-derive attempts `git config user.name` live.
5. **Binaries on PATH:** `git`, `python3.11+`, `node` (for `npx` of the
   filesystem MCP; only needed at editor-runtime, not install-time).

## What runtime is NOT allowed to assume

* **A specific package manager** (brew / winget / apt). That's install's
  concern; runtime never invokes them.
* **A specific Python** other than 3.11+. The venv at `mcp/.venv/bin/python`
  (or `Scripts\python.exe` on Windows) is the interpreter; install set it up.
* **A specific shell.** Runtime subprocesses use the binary directly
  (`git`, `docker`), never `bash -c "..."` style.
* **Internet access** during normal tool calls (except `git clone`, which
  is explicit user intent and fails with a clear error if offline).

## Host-side vs backend-side execution contract

| Concern                                         | Runs host-side (MCP server, Python) | Runs backend-side (Docker container)              |
| ----------------------------------------------- | ----------------------------------- | ------------------------------------------------- |
| git operations (clone, init, remote, ls-remote) | ✓                                   | ✗ — backend container has no git binary by design |
| Editor config file writes                       | ✓                                   | ✗ — backend can't see host filesystem             |
| Filesystem MCP installation                     | ✓                                   | ✗                                                 |
| Database writes (projects, todos, deltas, etc.) | ✗                                   | ✓                                                 |
| Semantic recall (pgvector + tsvector + Neo4j)   | ✗                                   | ✓                                                 |
| PID minting                                     | ✗                                   | ✓                                                 |
| BIOS template composition (`prism_sync_bios`)   | ✓ — composed host-side              | ✗ — backend has no `$PRISM_ROOT/templates/`       |

**Rule of thumb:** if it touches the caller's OS/filesystem/git/editors, it
runs in the MCP server (Python, host-side). If it touches Prism's data
stores, it runs in the backend (Docker).

## Backend deploy shapes

Three backend targets, all independent of host OS:

| Mode                          | What                                               | Set by                                                                                            |
| ----------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `local` (formerly "personal") | Docker Compose on the caller's Mac/Linux/Win       | `prism up` + `prism install --mode local` (TS CLI)                                                |
| `lan`                         | Docker Compose on a home server (server1.home.lan) | User runs `bin/prism-server-install.sh` there; clients run `prism install --mode lan --api-key …` |
| `cloud`                       | Hosted Prism service (deferred)                    | Not yet available; planned flow is `prism login` + `prism install --mode cloud`                   |

The MCP server's only connection to the backend is `PRISM_API_URL` + `PRISM_API_KEY`.
Backend never knows what OS the caller is on. That's orthogonal to everything else.

## Per-OS config file locations

Editors' MCP config files — where install writes, runtime reads:

| Editor         | macOS                                                             | Linux                                         | Windows                                                |
| -------------- | ----------------------------------------------------------------- | --------------------------------------------- | ------------------------------------------------------ |
| Claude Desktop | `~/Library/Application Support/Claude/claude_desktop_config.json` | `~/.config/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json`          |
| Claude Code    | `~/.claude.json` + `~/.claude/settings.json`                      | same                                          | `%USERPROFILE%\.claude.json` + `.claude\settings.json` |
| Cursor         | `~/.cursor/mcp.json`                                              | same                                          | `%USERPROFILE%\.cursor\mcp.json`                       |
| Codex          | `~/.codex/config.toml`                                            | same                                          | `%USERPROFILE%\.codex\config.toml`                     |

If any of these change upstream (editor vendor moves the config), update
the `clients()` function in **`cli/src/index.ts`** and re-run
`prism install`. Runtime picks up the new path via whatever the TS CLI
writes into each editor's MCP block. (The legacy Python `install/` tree
is deprecated per the TS migration — do not add new client paths there.)

## Re-running install when host state changes

The install manifest is pinned at install time. If any of these change,
re-run `prism install` to refresh (idempotent, auto-detects existing
backend, preserves user-added env keys unless `--force` is passed):

* OS upgrade (Windows 10 → 11; macOS major version)
* New editor installed (Codex was absent, now installed)
* New git identity (`git config --global user.name` changed)
* `$PROJECT_ROOT` relocated

Runtime won't notice these automatically — by design. Re-install is cheap
and idempotent.

## Dev-side invariants

When adding new host-touching features:

1. **Never call `platform.system()` in runtime code.** Use `os.environ["PRISM_HOST_OS"]`.
2. **Never call `Path.home()` for config paths.** Use `PRISM_APP_SUPPORT` / `PROJECT_ROOT`.
3. **Never assume a package manager.** If install is wrong, fix it in install.
4. **Add any new host-dependent value** to the install env block + this doc + the
   `_startup_preflight()` check list in `mcp/server.py`.