​

Prism-Vault Documentation Contract

This page defines what documentation each Prism-Vault implementation phase must produce, so docs land lockstep with the code instead of trailing it. It is the docs-lane companion to SPEC-122 and Plan #28.

​

Principles

1. Docs are a phase exit gate, not an afterthought. A phase is not “done” until its doc artifacts exist and have passed the proofread gate.
2. Document against real artifacts. Operator steps, env contracts, and verb signatures are written against landed code, verified by running them — not from the spec alone.
3. One source of truth per fact. The backend HTTP API is the source contract for the verb surface; mcp-node shims and docs describe it, they don’t redefine it. The git log is the source of truth for per-commit detail; the Prism-Vault changelog is the curated arc.
4. Subproject changelog updated every phase. Prism-Vault carries its own version string (SPEC-122 §Subproject Boundary). Every phase that ships code bumps the version and adds a dated changelog entry.
5. Preserve all diagrams. The four docs/diagrams/prism-vault/*.mmd sources are load-bearing. They are updated when the design changes, never deleted.
6. Proofread gate. Every Prism-Vault doc passes Desiree’s proofread before any Mintlify push, regardless of who drafted it. Carla coordinates viewer review of the spec and Mermaid diagrams.

​

Doc surfaces

Prism-Vault docs live under docs/architecture/prism-vault/: Pages are added to docs/docs.json navigation only when they exist — no broken nav links to unwritten pages.

​

Per-phase gates

​

Phase 0 — Service boundary and contract

Code lands: provider adapter interface, vault_service.py, /vault HTTP router, thin mcp-node prism_vault_* verb shims, contract tests. Docs required:

• api-contract.mdx — the verb surface as built: every prism_vault_* verb signature, request/response shapes, the short-lived env-payload format for prism_vault_secret_resolve (TTL, env, audit_id), and the failure-mode table (prism_vault_scope_denied, prism_vault_provider_unavailable, prism_vault_secret_missing, prism_vault_audit_unavailable, prism_vault_render_binding_missing, prism_vault_run_context_missing).
• Changelog — first dated, versioned entry; version string established.
• Overview — update the API contract section if the built surface diverges from the spec.

Exit gate: api-contract.mdx matches the landed verb shims and HTTP routes, verified against the contract tests. Owner: Desiree, drafted with Donna.

​

Phase 1 — Prism local provider

Code lands: Vault KV v2 adapter for local mode, Prism local bootstrap for Prism-scoped config and secrets. Docs required:

• build-deploy.mdx — local-mode section: how to stand up Prism-Vault locally (Vault dev mode), the .env-as-input-channel-only rule, and the local bootstrap steps. Verified by running them.
• api-contract.mdx — add worked examples: put metadata → get masked metadata → resolve for a Prism runtime purpose → observe audit.
• Changelog — Phase 1 entry, version bump.

Exit gate: a reader can stand up Prism-Vault locally from build-deploy.mdx alone. Owner: Desiree, drafted with Lafonda (deploy) and Donna (bootstrap).

​

Phase 2 — Prism LAN provider

Code lands: real Vault config with app token and scoped policy, Vault readiness health probe. Docs required:

• build-deploy.mdx — LAN-mode section: real Vault deployment, non-root app token, project-scoped policies, durable storage, seal/unseal operation, private LAN addressing, no public Vault port. Health-probe usage.
• Changelog — Phase 2 entry, version bump.

Exit gate: LAN deployment steps are reproducible and the no-public-port / non-root-token invariants are explicit. Owner: Desiree, drafted with Lafonda. Candi reviews the security-sensitive sections.

​

Phase 3 — Prism Render provider

Code lands: Render adapter for service-level env/secret bindings, Render deploy env contract, deploy smoke probes. Docs required:

• build-deploy.mdx — Render-mode section: the Render deploy env contract, deploy smoke probes, and every Render-native env/secret binding exception documented individually (SPEC-122 requires Prism-Vault as default service of record; native bindings are exceptions, each justified).
• Changelog — Phase 3 entry, version bump.

Exit gate: Render deployment uses the same Prism-Vault API contract as local/LAN with no caller-visible Render special cases; every native-binding exception is documented. Owner: Desiree, drafted with Lafonda.

​

Phase 4 — Prism operations

Code lands: operator UI/API for masked metadata, config version history, promotion, policy creation, audit lookup; monthly + manual-on-demand rotation hooks; export/import for project migration. Docs required:

• operator-guide.mdx — the operator runbook: inspecting masked metadata, reading config version history and promoting versions, creating access policies, running audit lookups scoped to a project, performing manual on-demand rotation, and exporting/importing a project between local/LAN/Render.
• api-contract.mdx — add the operations-surface verbs and rotation audit shape.
• Changelog — Phase 4 entry, version bump.

Exit gate: an operator can perform every Phase 4 operation from the guide; the monthly + manual rotation policy and its audit shape are documented. Owner: Desiree, drafted with Donna. Candi reviews policy/rotation sections.

​

Phase 5 — Janus / DPA-Crawl collaboration

Code lands: Janus/DPA-Crawl as later consumers, caller_kind=worker, job-scoped policy gates, crawl config read before job start, job credential resolution requiring job_id. Docs required:

• janus-dpa-integration.mdx — how a non-Prism project integrates: caller_kind=worker semantics, job-scoped policy, the required job_id on worker resolves, crawl config read-before-job-start, and worker-log masking.
• Changelog — Phase 5 entry, version bump.
• Overview — promote Janus/DPA-Crawl from “later” to “supported.”

Exit gate: a non-Prism project owner can integrate from the guide; the explicit-policy-and-audit requirement for non-Prism access is unmissable. Owner: Desiree, drafted with the Janus/DPA-Crawl owner.

​

Cross-phase standing requirements

These apply to every phase, not a specific one:

• Changelog discipline — every code-shipping phase bumps the Prism-Vault version string and adds a dated changelog entry.
• Diagram parity — if a phase changes the architecture, the relevant docs/diagrams/prism-vault/*.mmd source is updated in the same arc. Diagrams are never deleted; superseded ones are flagged for review.
• Masking discipline in examples — no doc example ever shows a real or realistic secret value. Resolve examples show the env-payload shape with placeholder values only.
• Failure-mode coverage — when a phase adds or changes a failure mode, the api-contract.mdx failure table is updated in the same arc.
• Proofread gate — Desiree proofreads before any Mintlify push; Carla coordinates viewer review.

​

See also

• SPEC-122 v0.1 — the contract this documents.
• Plan #28 — workstreams A–F and review gates.
• Prism-Vault Overview
• Prism-Vault Changelog