migration

docs/contracts/frontmatter.md

@@ -4,7 +4,7 @@ icon: lucide/braces
 
 # Frontmatter Contract
 
-This page defines the authored frontmatter contracts for native FastMCP skills and registry-backed prompts.
+This page defines frontmatter ownership for native skills and prompt documentation.
 
 ## Skill Frontmatter
 
@@ -27,38 +27,22 @@ Rules:
 
 The provider uses the directory name as the URI identity and the frontmatter `description` as the main resource description. Repository tests enforce directory/name parity and reject extra skill frontmatter fields.
 
-## Prompt Frontmatter
+## Prompt Documentation Frontmatter
 
-Prompts remain registry-backed and retain repository metadata:
+Prompt runtime metadata is defined by typed Python components, not Markdown frontmatter. A prompt document may retain only fields consumed by the static documentation site:
 
 ```yaml
 ---
-name: <prompt-id>
-description: <what the prompt does and when to use it>
-x-personal-mcp:
-  id: <prompt-id>
-  version: <semver>
-  tags:
-    - <tag>
-  capabilities:
-    - resource://prompts/<prompt-id>/document
-  arguments:
-    <argument-name>:
-      title: <display title>
-      description: <input guidance>
-      required: true
+icon: lucide/messages-square
 ---
 ```
 
 Prompt rules:
 
-1. `name`, `description`, and `x-personal-mcp` are required.
-2. `x-personal-mcp.id`, `name`, and the prompt directory name must match.
-3. `version` must be semantic version text.
-4. `capabilities` must include `resource://prompts/<prompt-id>/document`.
-5. Argument names must be valid Python identifiers.
-6. Argument entries accept optional `title`, `description`, and `required` fields.
-7. Unknown prompt fields are rejected by the strict Pydantic registry models.
+1. Do not duplicate prompt names, descriptions, versions, tags, or arguments in Markdown YAML.
+2. Argument names must be valid Python identifiers in the component signature.
+3. Literal value constraints belong in Python type annotations.
+4. Markdown placeholders must exactly match the component argument names.
 
 See the MCP [prompts concept documentation](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts) and [schema reference](https://modelcontextprotocol.io/specification/latest/schema) for the protocol-level prompt shape.
 
@@ -70,11 +54,11 @@ Skill validation is file- and provider-oriented:
 2. FastMCP parses the description and scans all files when the provider is created.
 3. Repository tests enforce the stricter standard-only frontmatter and directory/name rules.
 
-Prompt validation remains registry-oriented and fails server startup for invalid metadata, duplicate prompt ids, or malformed arguments.
+Prompt validation is provider- and renderer-oriented. Provider discovery validates decorated functions, while focused tests render every prompt and reject placeholder drift.
 
 ## Invariants
 
 1. Skills remain directly portable to tools that understand standard Agent Skills directories.
 2. Native skill discovery has no parallel catalog metadata source.
-3. Prompts retain the richer metadata required by their catalog and MCP prompt-object surfaces.
+3. Prompts use FastMCP's native component metadata and protocol surface without a parallel catalog.
 4. All authored content remains under `docs/`.