Contracts

Discovery Contract

• expose agent-readable repo context through docs/agent/ and docs/context/
• treat docs/agent/manifest.yaml as the repo-local MCP manifest when present
• keep MCP docs aligned with the actual repo structure and workflows instead of generated placeholders

Authoring Source-Of-Truth Contract

• treat docs/decks/*.md as the human-edited source of truth for deck intent
• treat the React/Spectacle deck app as the primary generated or maintained product
• keep docs and implementation consistent when deck intent, inventory, or standards change

Layering Contract

• use reusable layers before writing deck-specific one-off code
• respect the standard precedence system > deck > page > block
• if a rule belongs at a higher layer, promote it there instead of duplicating it at a lower layer

Change-Boundary Contract

• content creators should not modify src/shared/ unless they are designated maintainers
• new blocks must be added in src/blocks/ and registered in the block registry
• new layouts must be added in src/page-templates/ and registered in the page-template registry
• keep export and rendering concerns out of the core deck and page prop model
• prefer composition over custom slide code when extending deck behavior

Curation Contract

• treat content/catalog/decks.json as the current curation source of truth for deck inventory
• keep published deck variants versioned rather than overwritten
• do not leave an accepted standard living only inside deck-demo