89 lines
2.4 KiB
Markdown
89 lines
2.4 KiB
Markdown
---
|
|
icon: lucide/file-check-2
|
|
---
|
|
|
|
# Contracts
|
|
|
|
This section groups the core data and contract documents for the repository.
|
|
|
|
## Pages
|
|
|
|
1. [Prompt Contract](./prompt.md)
|
|
2. [Skill Contract](./skill_contract.md)
|
|
3. [Frontmatter Contract](./frontmatter.md)
|
|
4. [URI Contract](./uris.md)
|
|
|
|
Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics.
|
|
|
|
## Content Contract
|
|
|
|
This page defines the authored content contract for the docs-first MCP architecture.
|
|
|
|
## Canonical Source Of Truth
|
|
|
|
1. All authored Markdown lives under `docs/`.
|
|
2. MCP resources and static docs are two distribution surfaces of the same authored files.
|
|
3. No parallel authored markdown is allowed in `src/` or other package-only paths.
|
|
|
|
## Canonical Content Shape
|
|
|
|
Authored content is organized under `docs/`:
|
|
|
|
```mermaid
|
|
---
|
|
config:
|
|
treeView:
|
|
rowIndent: 20
|
|
lineThickness: 2
|
|
themeVariables:
|
|
treeView:
|
|
labelColor: '#FFFFFF'
|
|
lineColor: '#FFFFFF'
|
|
---
|
|
treeView-beta
|
|
"docs/"
|
|
"*.md (top-level docs pages)"
|
|
"contracts/"
|
|
"prompt.md"
|
|
"skill_contract.md"
|
|
"frontmatter.md"
|
|
"uris.md"
|
|
"prompts/"
|
|
"<prompt-id>/"
|
|
"PROMPT.md"
|
|
"skills/"
|
|
"<skill-id>/"
|
|
"SKILL.md"
|
|
"references/..."
|
|
```
|
|
|
|
## File Placement And Ownership Boundaries
|
|
|
|
1. Top-level project docs stay in `docs/*.md`.
|
|
2. Skill docs stay in `docs/skills/<skill-id>/...`.
|
|
3. Prompt docs stay in `docs/prompts/<prompt-id>/...`.
|
|
4. A skill or prompt may link across sections, but must not store content in another artifact's directory.
|
|
5. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
|
|
|
|
## Delegated Contracts
|
|
|
|
1. Skill-specific directory, metadata, and id rules are defined in [Skill Contract](./skill_contract.md).
|
|
2. Prompt-specific directory, metadata, and id rules are defined in [Prompt Contract](./prompt.md).
|
|
|
|
## Invariants
|
|
|
|
This contract guarantees:
|
|
|
|
1. One authored source tree in `docs/` for both website and MCP.
|
|
2. Skill and prompt artifacts remain path-stable within their own sections.
|
|
3. Cross-surface publishing remains deterministic because authored content paths are canonical.
|
|
|
|
## Non-Goals
|
|
|
|
This contract does not define:
|
|
|
|
1. URI versioning policy details.
|
|
2. The full frontmatter schema.
|
|
3. Detailed skill rules (see [Skill Contract](./skill_contract.md)).
|
|
4. Detailed prompt rules (see [Prompt Contract](./prompt.md)).
|