> ## 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.

# ADR-11: CLAUDE.md BIOS v2: env-var path convention + SOR/replica model

> CLAUDE.md is reborn as a thin, project-agnostic BIOS file (v2.0.0). It contains NO hardcoded paths, NO PID, NO persona, NO communication style. All paths derive

<Info>**Status:** `accepted` · **ADR-11** · Filed 2026-04-17</Info>

## Decision

CLAUDE.md is reborn as a thin, project-agnostic BIOS file (v2.0.0). It contains NO hardcoded paths, NO PID, NO persona, NO communication style. All paths derive from two env vars: `$PROJECT_ROOT` (parent of all projects) and `$PRISM_ROOT` (Prism's own repo, conventionally `$PROJECT_ROOT/Prism`). User projects resolve as `$PROJECT_ROOT/{project_name}`. SOR templates live at `$PRISM_ROOT/templates/`. Each user project holds a replica of CLAUDE.md (and AGENTS.md, PRISM.md) carrying a `bios_version` header. On `prism_start`, the server compares replica version to SOR; major-version mismatch prompts user to run `prism_sync_bios`. A manual force-sync verb exists for recovery when a user breaks a replica. PID is resolved dynamically via `prism_start` + project dir name, not hardcoded in the BIOS.

## Rationale

The legacy CLAUDE.md (v1.0.0) carried hardcoded paths (`X:\DFW\DFWP`, `C:\DATA\DFW\DFWP`) and a hardcoded PID (PID-BFG9N) from the DFWP era. This broke the moment Frank's work expanded beyond a single project and machine. Symptoms in the live exhibit: the file could not be reused across PrismGR (Windows, `C:\Data\PrismGR`) and Prism (Mac, `/Users/fpn/projects/Prism`) without hand-editing; it carried identity for a project that isn't this one; and its 'Project Root' field was doing double duty as both an env pointer and a literal path. Root cause: CLAUDE.md was being used as both BIOS (load-before-everything) and application constitution (project-specific facts) — two jobs that want opposite update cadences. BIOS should be stable, small, OS-agnostic, one file for all projects. Application facts belong in PRISM.md, AGENTS.md, and project metadata inside Prism. The `$PROJECT_ROOT`/`$PRISM_ROOT` split mirrors the sprint-1 PRISM\_ROOT refactor CC already shipped, extending the same principle to the BIOS layer. SOR/replica with version-pin is the least fragile distribution model: replicas are disposable, SOR is canon, drift is visible instead of silent, and a force-sync verb handles recovery.

## Alternatives Considered

Symlink replicas to SOR — rejected because it breaks across OS boundaries, git clones, and WSL/Mac sync; Claude Desktop on Windows handles symlinks unreliably. Keep CLAUDE.md project-specific with a PID — rejected because it forces every project to duplicate BIOS content with only the PID differing, creating a drift surface. Move templates to `$PROJECT_ROOT/.prism/` — rejected because it implies templates are OS-level cache rather than a Prism product artifact; hidden-dir placement is surprising. Defer the sync verb and rely only on version-header warnings — rejected because when a user breaks a replica there must be a one-command recovery path.