authoring page

docs/authoring.md

@@ -0,0 +1,128 @@
+---
+icon: lucide/pencil
+---
+
+# Authoring Guide
+
+This page defines the practical authoring workflow for this repository so Markdown remains the single source of truth for both published docs and MCP resources.
+
+Primary references:
+- [Skill contract](./contracts/skill_contract.md)
+- [Prompt contract](./contracts/prompt.md)
+- [Frontmatter contract](./contracts/frontmatter.md)
+- [URI contract](./contracts/uris.md)
+- [Zensical documentation authoring skill](./skills/zensical-docs/SKILL.md)
+
+## What You Author
+
+This repository has two primary authored content types:
+
+1. Skills under `docs/skills/<skill-id>/`.
+2. Prompts under `docs/prompts/<prompt-id>/`.
+
+Each module keeps one canonical document plus optional references:
+
+```text
+docs/
+	skills/<skill-id>/
+		SKILL.md
+		references/
+			*.md
+
+	prompts/<prompt-id>/
+		PROMPT.md
+		references/
+			*.md
+```
+
+## Authoring Principles
+
+1. Keep Markdown as the canonical source and avoid duplicating content into alternate metadata files.
+2. Prefer resource-first discovery paths (`resource://catalog/...` then `resource://skills/...` or `resource://prompts/...`).
+3. Keep pages focused and composable: overview in the primary doc, details in `references/`.
+4. Use descriptive inline links for external sources instead of bare URLs.
+5. Use stable ids and slugs; renames are breaking changes and should be intentional.
+
+## Skill Authoring Workflow
+
+When creating or updating a skill:
+
+1. Confirm slug format is lowercase kebab-case.
+2. Keep directory name, `name`, and `x-personal-mcp.id` aligned.
+3. Ensure capabilities include `resource://skills/<skill-id>/document`.
+4. Place supporting material under `references/`.
+5. Use explicit frontmatter reference entries only when you need overrides or nested mappings.
+
+Recommended sequence:
+
+1. Draft `SKILL.md` intent and routing sections.
+2. Add or refine `references/*.md`.
+3. Verify links and example commands.
+4. Run docs build and tests.
+
+For exact metadata rules, see [Frontmatter contract](./contracts/frontmatter.md) and [Skill contract](./contracts/skill_contract.md).
+
+## Prompt Authoring Workflow
+
+When creating or updating a prompt module:
+
+1. Keep one canonical `PROMPT.md`.
+2. Keep `name`, `x-personal-mcp.id`, and directory slug aligned.
+3. Include `resource://prompts/<prompt-id>/document` in capabilities.
+4. Define prompt arguments in `x-personal-mcp.arguments` when inputs are required.
+5. Keep long rationale and source notes in `references/` to preserve prompt clarity.
+
+For exact structure, see [Prompt contract](./contracts/prompt.md).
+
+## Writing Quality Rules
+
+Apply these defaults to all docs pages:
+
+1. Prefer short sections with strong headings over long unbroken prose.
+2. Keep claims source-linked, especially for MCP, FastMCP, pytest, FastAPI, SQLAlchemy, and Zensical behavior.
+3. Prefer relative links for internal docs paths.
+4. Use code blocks for commands and configuration snippets.
+5. Keep examples minimal and actionable.
+
+Source examples:
+- [Model Context Protocol docs](https://modelcontextprotocol.io/docs/getting-started/intro)
+- [FastMCP docs](https://gofastmcp.com/getting-started/welcome)
+- [Zensical docs](https://zensical.org/docs/)
+
+## Navigation And Frontmatter
+
+When adding or restructuring pages:
+
+1. Update navigation in `zensical.toml`.
+2. Ensure top-level pages include frontmatter with an icon.
+3. Keep naming and labels concise so navigation remains scannable.
+
+Top-level page pattern:
+
+```yaml
+---
+icon: lucide/pencil
+---
+```
+
+## Validation Checklist
+
+Run these checks before considering authoring changes complete:
+
+```bash
+uv run zensical build
+uv run ruff check .
+uv run ty check
+uv run pytest
+```
+
+If a change only affects docs content, `uv run zensical build` is still required.
+
+## Quick Authoring Checklist
+
+1. Correct location (`skills/` or `prompts/`).
+2. Frontmatter id and slug alignment.
+3. Capability URI present.
+4. Links valid and descriptive.
+5. Navigation updated when needed.
+6. Validation commands passed.

zensical.toml

@@ -58,6 +58,7 @@ nav = [
     { "MCP" = "mcp_layout.md" },
     { "Copilot" = "copilot.md" },
     { "Usage" = "usage.md" },
+    { "Authoring" = "authoring.md" },
     { "Future Work" = "future_work.md" },
     { "Testing" = "testing.md" },
     { "Security" = "securing.md" },