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

# SPEC-112: Client and Contributor Scaffold Boundary

> Two scaffold/install modes — client (default) vs contributor (explicit opt-in) — and the artifact boundary each writes into $PROJECT_ROOT under the immutable $PRISM_ROOT model

# SPEC-112 v0.3 — Client and Contributor Scaffold Boundary

**Status:** accepted (Frank ratified 2026-05-13 via Cherry → Donna → Texi relay).
**Owner / Author:** Texi (architecture), Donna (engineering / Plan #18 integration).
**Related:** [SPEC-113 v0.3](/specs/spec-113-v0-3-bootstrap-path-resolution-and-scaffold-completeness) (sibling — runtime template resolution + scaffold completeness), ADR-030 (consumer-grade install authority), SPEC-053 (Node CLI bootstrap/update), SPEC-084 (editor-host install), SPEC-089 (cloud customer onboarding/auth), Plan #16 Workstream H (`.agent/` persona config).

## Origin

Frank via Cherry to Donna, relayed to Texi 2026-05-13. v0.3 corrects the v0.2 architectural miss: `PRISM.md` is not a customer/project scaffold artifact. Prism installs once at `$PRISM_ROOT`; Ring 2 methodology is owned by Prism under `$PRISM_ROOT/templates/` and read at runtime. Scaffold/adopt writes only the thin Prism edge into `$PROJECT_ROOT`, not copied Ring 2 methodology.

## Canonical Terms

`$PRISM_ROOT` is the Prism install directory. It is a single instance per host, immutable to non-contributors, and owns methodology at `$PRISM_ROOT/templates/`: `prism-base.md`, ptype overlays, and the content that historically composed `PRISM.md`. Agents read methodology from `$PRISM_ROOT/templates/` at runtime; it is never copied into ordinary project roots.

`$PROJECT_ROOT` is the customer project directory. It is mutable customer space. It gets only the thin edge: `CLAUDE.md` and/or `AGENTS.md` Ring 1 replicas, `.prism/`, and `.agent/` dotfile dirs when contributor mode is explicitly selected. It gets no root `PRISM.md`.

## Corrected Architecture

Prism owns the upper methodology rings immutably at `$PRISM_ROOT`:

* Ring 1 BIOS SOR: `$PRISM_ROOT/templates/AGENTS.md`, `$PRISM_ROOT/templates/CLAUDE.md`.
* Ring 2 methodology SOR: `$PRISM_ROOT/templates/prism-base.md` plus ptype/profile overlays such as `$PRISM_ROOT/templates/prism-application.md`.

Agents read Ring 2 methodology at runtime from `$PRISM_ROOT/templates/`; scaffold/adopt does not copy or compose `PRISM.md` into `$PROJECT_ROOT`.

Customer project directories contain only project-owned state and lower overlays:

* `$PROJECT_ROOT/.prism/` project metadata and Prism-managed local state.
* `$PROJECT_ROOT/.agent/` contributor/agent-contract config only when contributor mode is explicitly selected.
* `$PROJECT_ROOT/AGENTS.md` and/or `$PROJECT_ROOT/CLAUDE.md` Ring 1 editor bootstrap replicas where needed by editor surfaces.

## Special Case: Prism Repo Itself

On a contributor machine working on Prism itself, `$PRISM_ROOT` and `$PROJECT_ROOT` resolve to the same path. That is why `PRISM.md` exists at the Prism repo root: the repo is both product/install root and customer project for Prism development.

This is a single-machine special case, not the general rule. Customer/client projects must not receive root `PRISM.md` replicas.

## Prior Art Assessment

Prior art exists but was incomplete:

* ADR-030 and SPEC-053 define consumer-grade install authority and Node CLI bootstrap/update.
* SPEC-084 defines editor-host install.
* SPEC-089 defines cloud customer onboarding/auth.
* Plan #16 Workstream H defines `.agent/` persona config for contributor/development projects.
* SPEC-113 v0.3 defines runtime template resolution and scaffold completeness without `PRISM.md` replicas.

## Decision

Introduce two scaffold/install modes:

1. `client` mode — default for customer/user installs and ordinary Prism-tracked customer projects.
2. `contributor` mode — explicit opt-in for Prism development/cohort machines and agent-mesh operation.

The default is `client`. Contributor artifacts cross into `$PROJECT_ROOT` only when explicitly requested or when `$PROJECT_ROOT == $PRISM_ROOT` for the Prism repo special case.

## Client Mode Boundary

Client/customer mode **may** install or scaffold into `$PROJECT_ROOT`:

* `AGENTS.md` and/or `CLAUDE.md` Ring 1 replicas as required by active editor surfaces.
* `.prism/` dotfile directory for project binding, ptype/profile metadata, local state, and repair/sync metadata.
* Minimal project metadata required for Prism verbs and ordinary editor MCP use.
* Editor MCP config and API credentials required to connect to the backend.
* `prism` CLI and `coder` launcher only as user-facing entrypoints, without mesh-launch defaults.
* Project docs generated by the selected client-safe project template.

Client/customer mode **must not** install/scaffold into `$PROJECT_ROOT` by default:

* `PRISM.md` in the project root.
* `.agent/` persona contracts, role templates, project bindings, or launch.local.
* `agent-roster.psv` or seed/export roster files.
* `start-all.sh`, `start-all.ps1`, or mesh-launch scripts in the client project.
* Prism repo source trees, backend source, dashboard source, test harnesses, smoke scripts, or internal governance/install lane docs.
* Contributor-only hooks, release-cut tools, or agent cohort defaults.

## Contributor Mode Boundary

Contributor mode **may** install/scaffold into `$PROJECT_ROOT`:

* Full `.agent/` config for the project/cohort.
* Persona roles/bindings/launch.local.
* Roster seed/export artifacts as compatibility files.
* `start-all` launchers and validation tools.
* Development docs/spec references, smoke scripts, and repo source as appropriate for a Prism contributor checkout.
* Contributor/developer ptype/profile metadata in `.prism/` so runtime template resolution reads the right `$PRISM_ROOT/templates/` overlay.

Contributor mode still does not copy `PRISM.md` into arbitrary project roots. The Prism repo itself is the only legitimate root-`PRISM.md` carve-out.

## Runtime Methodology Contract

`PRISM.md` has no standalone `$PRISM_ROOT/templates/PRISM.md` source file. Ring 2 methodology is runtime-composed by reading:

* `$PRISM_ROOT/templates/prism-base.md`, and
* the selected ptype/profile overlay under `$PRISM_ROOT/templates/`.

Composition rules:

* Base is always `prism-base.md`.
* Overlay/profile is selected from install/project metadata, typically recorded under `$PROJECT_ROOT/.prism/` and/or backend project metadata.
* Client default must not select a Prism-product/developer overlay if that overlay contains product-specific implementation rules inappropriate for the target project.
* If no suitable overlay exists, bootstrap/scaffold repair fails closed as `template_not_found_at_prism_root`, `prism_root_misconfigured`, or `template_resolution_failed`; it must not write a misleading local `PRISM.md`.

## Interface Contract

`prism_create`, `prism_adopt`, and install flows gain a scaffold profile parameter or equivalent:

* `scaffold_profile='client'` default.
* `scaffold_profile='contributor'` explicit.

They also persist enough project metadata for runtime template resolution:

* `ptype`
* `scaffold_profile`
* selected overlay id/path or version reference

Existing dev flows may infer contributor mode only when `$PROJECT_ROOT == $PRISM_ROOT` for the Prism repo or an existing `.agent/` tree is present and explicitly accepted. New customer projects do not infer contributor mode from local environment alone.

## Failure Mode Names

* `contributor_surface_leak`: client/customer scaffold includes contributor-only artifacts.
* `client_runtime_under_scaffolded`: client/customer scaffold lacks files/dotfile metadata required for ordinary Prism use.
* `profile_ambiguity`: scaffolder cannot determine intended profile; fail closed to client and surface ambiguity.
* `template_not_found_at_prism_root`: `$PRISM_ROOT/templates/` lacks required base or overlay template.
* `prism_root_misconfigured`: runtime cannot locate or trust `$PRISM_ROOT` as the Prism install directory.
* `template_resolution_failed`: runtime cannot resolve a valid base + overlay for the project ptype/profile.
* `misprofiled_template_overlay`: client/customer project resolves contributor/product-specific Ring 2 methodology.

Removed failure mode:

* `missing_prism_replica` is invalid because `PRISM.md` is not a project replica.

## Acceptance Criteria

* Default `prism_create` for a customer project produces no root `PRISM.md`, no `.agent/`, no `agent-roster.psv`, and no `start-all` launchers in `$PROJECT_ROOT`.
* Default client scaffold records ptype/profile metadata sufficient for runtime template resolution from `$PRISM_ROOT/templates/`.
* Client runtime Ring 2 methodology is client-safe and excludes Prism-product-specific application overlay content unless explicitly selected by ptype/profile.
* Contributor mode produces `.agent/`, launch.local, role/persona config, and launcher compatibility artifacts, but does not copy `PRISM.md` except for the Prism repo special case.
* Missing template/overlay fails visibly as `template_not_found_at_prism_root`, `prism_root_misconfigured`, or `template_resolution_failed`.
* `prism_adopt` defaults to client mode unless existing contributor artifacts are present and explicitly accepted.
* Install docs and CLI help describe client vs contributor mode.
* Smoke tests assert no client-mode contributor artifact leak and no root `PRISM.md` in customer projects.

## Non-Goals

* Designing the hosted customer Tenant Console.
* Changing WorkOS/human auth semantics.
* Removing `PRISM.md` from the Prism repo itself.
* Making `.agent/` a local memory store; it remains committed config only in contributor mode.