migration

docs/contracts/prompt.md

@@ -4,11 +4,11 @@ icon: lucide/messages-square
 
 # Prompt Contract
 
-This page defines the canonical contract for prompts in the docs-first MCP architecture.
+This page defines the canonical contract for typed prompts discovered by FastMCP's `FileSystemProvider`.
 
 ## Canonical Prompt Shape
 
-Each prompt is one directory under `docs/prompts/`:
+Each prompt has a Python component and one canonical Markdown document:
 
 ```mermaid
 ---
@@ -22,27 +22,31 @@ config:
             lineColor: '#FFFFFF'
 ---
 treeView-beta
-    "docs/"
-      "... (other docs)"
-      "prompts/"
-        "<prompt-id>/"
-          "PROMPT.md"
-          "references/"
-            "... (one or more markdown files, optional nested folders)"
+    "src/personal_mcp/prompts/"
+      "components/"
+        "<prompt_module>.py"
+      "content.py"
+      "provider.py"
+    "docs/prompts/"
+      "<prompt-id>/"
+        "PROMPT.md"
 ```
 
 Rules:
 
-1. `PROMPT.md` is required for every prompt.
-2. `references/` is the only place for prompt-specific supporting docs.
-3. Nested folders inside `references/` are allowed so a prompt can reorganize internals without changing global architecture.
-4. Prompt directories are independent ownership boundaries; no cross-prompt file writes.
+1. Each component exports one typed function decorated with `@prompt`.
+2. Function parameters define the MCP argument names, requiredness, and accepted values.
+3. Decorator fields define runtime name, description, tags, and version.
+4. The function loads its matching `docs/prompts/<prompt-id>/PROMPT.md` through `importlib.resources`.
+5. `PROMPT.md` owns the rendered prompt prose and uses `{argument_name}` placeholders.
+6. The renderer requires exact equality between the function's arguments and the Markdown placeholders.
 
-## Metadata Location Constraint
+## Ownership Boundary
 
-1. Prompt metadata is embedded in YAML frontmatter in `PROMPT.md`.
-2. No `metadata.yaml` sidecar exists in the end state.
-3. Reference lookup metadata is documented and explicit: top-level `references/*.md` are auto-discovered from filenames, while `PROMPT.md` frontmatter declares overrides and nested mappings when needed.
+1. Python owns runtime metadata and the callable schema.
+2. Markdown owns prompt prose and may contain only documentation-site frontmatter.
+3. There is no custom prompt catalog, prompt registry model, or metadata sidecar.
+4. `FileSystemProvider(reload=False)` discovers components when the server is created.
 
 ## Prompt Id Contract
 
@@ -53,8 +57,8 @@ Rules:
 3. Must start with a letter.
 4. No underscores, spaces, dots, or uppercase characters.
 5. Directory name should equal `prompt-id` in each committed revision.
-6. Frontmatter `id` should equal directory name in each committed revision.
-7. Treat `prompt-id` as immutable after release; any rename is a breaking replacement and clients must move to the new id.
+6. The `@prompt` name and Markdown directory name must equal `prompt-id`.
+7. Treat `prompt-id` as immutable after release; a rename is a breaking replacement.
 
 Valid examples:
 
@@ -68,8 +72,11 @@ Invalid examples:
 2. `Prompt-Template`
 3. `docs.prompt`
 
-## Direct Documentation Inclusion
+## Rendering Contract
 
-1. For direct API documentation, use mkdocstrings directives rather than pasting large code blocks.
-2. Keep manually-authored code examples short and task-focused; large implementation excerpts are out of scope for this contract.
+1. The renderer strips one leading YAML frontmatter block before returning prompt content.
+2. Required values are supplied by the typed function signature.
+3. An omitted optional value renders as `Not provided`.
+4. Unknown prompt ids and mismatched placeholders fail immediately.
+5. Prompt content is read from packaged resources and does not depend on the working directory.