swapped docs symlink

src/personal_mcp/docs/contracts/frontmatter.md

@@ -0,0 +1,72 @@
+---
+icon: lucide/braces
+---
+
+# Frontmatter Contract
+
+This page defines frontmatter ownership for native skills and prompt documentation.
+
+## Skill Frontmatter
+
+Skills use the standard Agent Skills fields consumed by the [FastMCP Skills Provider](https://gofastmcp.com/servers/providers/skills):
+
+```yaml
+---
+name: <skill-id>
+description: <what the skill does and when to use it>
+---
+```
+
+Rules:
+
+1. `name` and `description` are required.
+2. `name` must equal the skill directory name.
+3. The repository uses lowercase kebab-case directory names.
+4. Skill frontmatter contains no `x-personal-mcp` catalog metadata.
+5. Supporting files require no frontmatter manifest. The provider discovers files recursively and generates `_manifest` with relative paths, byte sizes, and SHA256 hashes.
+
+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 Documentation Frontmatter
+
+Each prompt stores runtime metadata in a nested `prompt` mapping beside fields consumed by the static documentation site. The runtime mapping uses this shape:
+
+```yaml
+---
+icon: lucide/messages-square
+prompt:
+ version: "1.0.0"
+ description: Describe when to use the prompt.
+ tags: [example, prompts]
+ arguments: {topic: {description: "Topic to process.", required: true, choices: [first, second]}, notes: {description: "Optional constraints.", required: false}}
+---
+```
+
+Prompt rules:
+
+1. `version`, `description`, `tags`, and `arguments` are required; unknown fields inside `prompt` or an argument are rejected.
+2. The directory name supplies the prompt id. Do not add a duplicate `name` field.
+3. Argument names must be valid identifiers and preserve their authored mapping order.
+4. Every argument requires a non-empty `description` and explicit `required` boolean.
+5. Optional `choices` must be a non-empty list of unique, non-empty strings.
+6. Markdown placeholders must exactly match the declared argument names.
+7. Top-level fields such as `icon` remain owned by the documentation site and are not runtime prompt metadata.
+
+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.
+
+## Validation Timing
+
+Skill validation is file- and provider-oriented:
+
+1. `SkillsDirectoryProvider` discovers each directory containing `SKILL.md`.
+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 is provider- and renderer-oriented. Every list or get request reloads and validates the authored files. A malformed definition fails the request instead of publishing a partial prompt set.
+
+## 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 use FastMCP's native component metadata and protocol surface without a parallel catalog or Python component file.
+4. All authored content remains under `docs/`.