authoring prompt

docs/authoring.md

@@ -74,6 +74,59 @@ When creating or updating a prompt module:
 
 For exact structure, see [Prompt contract](./contracts/prompt.md).
 
+## Prompt Argument Mechanics
+
+When defining prompt inputs, keep argument metadata aligned with the prompt contract and runtime behavior.
+
+1. Define arguments under `x-personal-mcp.arguments` as a map keyed by argument name.
+2. Argument names must match Python identifier format: `^[A-Za-z_][A-Za-z0-9_]*$`.
+3. Each argument entry supports only:
+	 - `title` (optional)
+	 - `description` (optional)
+	 - `required` (optional, defaults to `false`)
+4. Unknown argument fields are rejected by strict frontmatter validation.
+5. Prompt argument metadata appears in `resource://catalog/prompts/{prompt_id}`, and MCP prompt objects expose the same arguments for prompt-list/get-prompt workflows.
+6. Enum-like constraints are not a native argument field; encode allowed values in `description`.
+
+### Frontmatter Safety Rules
+
+Use these rules to avoid YAML parse failures in prompt and skill frontmatter:
+
+1. Quote any scalar value that contains `:` (for example, `description: "Enum: skill | prompt | shim"`).
+2. Prefer quoted scalars for values with reserved YAML characters such as `#`, `{}`, `[]`, or leading `*`.
+3. If a description needs multiple lines, use a block scalar (`|`) instead of packing punctuation-heavy text into one line.
+4. Keep frontmatter keys simple and contract-bound; do not add undeclared argument fields.
+
+### Validation Timing
+
+Run validation immediately after frontmatter edits, not only at the end of a task:
+
+1. First pass after metadata changes: `uv run zensical build`
+2. Prompt/skill load verification: `uv run pytest -q`
+3. Final full pass before completion: run the full checklist in [Validation Checklist](#validation-checklist)
+
+Example:
+
+```yaml
+x-personal-mcp:
+	arguments:
+		artifact_type:
+			title: Artifact type
+			description: Allowed values are skill, prompt, or shim.
+			required: true
+		scope_glob:
+			title: Scope glob
+			description: Optional applyTo glob for shim outputs.
+			required: false
+```
+
+References:
+
+1. [Frontmatter contract](./contracts/frontmatter.md)
+2. [URI contract](./contracts/uris.md)
+3. [Resource-First Pattern Module Architecture](./architecture.md)
+4. [Prompt objects concept docs](https://modelcontextprotocol.io/docs/learn/server-concepts#prompts)
+
 ## Writing Quality Rules
 
 Apply these defaults to all docs pages: