Contracts¶

This section groups the core data and contract documents for the repository.

Pages¶

1. Prompt Contract
2. Skill Contract
3. Frontmatter Contract
4. URI Contract

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 src/jsl_mcp/docs/.
2. MCP resources and static docs are two distribution surfaces of the same authored files.
3. No parallel authored Markdown is allowed in a root docs/ directory or another source tree.

Canonical Content Shape¶

Authored content is organized under src/jsl_mcp/docs/:

---
config:
    treeView:
        rowIndent: 20
        lineThickness: 2
    themeVariables:
        treeView:
            labelColor: '#FFFFFF'
            lineColor: '#FFFFFF'
---
treeView-beta
  "src/jsl_mcp/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 src/jsl_mcp/docs/*.md.
2. Skill docs stay in src/jsl_mcp/docs/skills/<skill-id>/....
3. Prompt docs stay in src/jsl_mcp/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.
2. Prompt-specific directory, metadata, and id rules are defined in Prompt Contract.

Invariants¶

This contract guarantees:

1. One authored source tree in src/jsl_mcp/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).
4. Detailed prompt rules (see Prompt Contract).