From 1f7e63267a03bc97f4f8679ae285711e2d8779e5 Mon Sep 17 00:00:00 2001 From: John Lancaster <32917998+jsl12@users.noreply.github.com> Date: Sun, 21 Jun 2026 18:12:58 -0500 Subject: [PATCH] doc updates --- docs/architecture.md | 10 ++-- docs/{ => contracts}/content.md | 0 docs/{ => contracts}/frontmatter.md | 0 docs/contracts/index.md | 15 +++++ docs/{ => contracts}/uris.md | 0 docs/index.md | 7 ++- docs/mcp_layout.md | 57 +++++++------------ docs/prompts/initial-test-structure/PROMPT.md | 23 ++++++++ docs/skills/new-skill/SKILL.md | 6 +- zensical.toml | 9 ++- 10 files changed, 75 insertions(+), 52 deletions(-) rename docs/{ => contracts}/content.md (100%) rename docs/{ => contracts}/frontmatter.md (100%) create mode 100644 docs/contracts/index.md rename docs/{ => contracts}/uris.md (100%) create mode 100644 docs/prompts/initial-test-structure/PROMPT.md diff --git a/docs/architecture.md b/docs/architecture.md index ef5f2e4..4c301d0 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -26,9 +26,9 @@ This architecture is anchored by three contracts: Detailed contract pages: -1. [Content Contract](./content.md) -2. [Frontmatter Contract](./frontmatter.md) -3. [URI Contract](./uris.md) +1. [Content Contract](./contracts/content.md) +2. [Frontmatter Contract](./contracts/frontmatter.md) +3. [URI Contract](./contracts/uris.md) This architecture keeps authored content human-friendly while preserving machine-stable contracts. @@ -125,7 +125,7 @@ flowchart TD Each skill declares frontmatter in `docs/skills//SKILL.md`. -For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./frontmatter.md). +For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./contracts/frontmatter.md). Anthropic-facing required fields: @@ -147,7 +147,7 @@ No `metadata.yaml` sidecar is part of the end-state contract. Canonical resource URIs are: -For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./uris.md). +For the full URI semantics, parameter validation rules, and compatibility policy, see [URI Contract](./contracts/uris.md). 1. resource://skills//document 2. resource://skills//references/ diff --git a/docs/content.md b/docs/contracts/content.md similarity index 100% rename from docs/content.md rename to docs/contracts/content.md diff --git a/docs/frontmatter.md b/docs/contracts/frontmatter.md similarity index 100% rename from docs/frontmatter.md rename to docs/contracts/frontmatter.md diff --git a/docs/contracts/index.md b/docs/contracts/index.md new file mode 100644 index 0000000..4f2800d --- /dev/null +++ b/docs/contracts/index.md @@ -0,0 +1,15 @@ +--- +icon: lucide/file-check-2 +--- + +# Contracts + +This section groups the core data and contract documents for the repository. + +## Pages + +1. [Content Contract](./content.md) +2. [Frontmatter Contract](./frontmatter.md) +3. [URI Contract](./uris.md) + +Use these pages as the normative source for authored content layout, frontmatter schema, and canonical MCP URI semantics. \ No newline at end of file diff --git a/docs/uris.md b/docs/contracts/uris.md similarity index 100% rename from docs/uris.md rename to docs/contracts/uris.md diff --git a/docs/index.md b/docs/index.md index d6896ef..310418e 100644 --- a/docs/index.md +++ b/docs/index.md @@ -39,9 +39,10 @@ When the server is running, the health check is available at `/healthz` and the ## Architecture - [Resource-First Pattern Module Architecture](./architecture.md) -- [Content Contract](./content.md) -- [Frontmatter Contract](./frontmatter.md) -- [URI Contract](./uris.md) +- [Contracts](./contracts/index.md) +- [Content Contract](./contracts/content.md) +- [Frontmatter Contract](./contracts/frontmatter.md) +- [URI Contract](./contracts/uris.md) - [Static Docs Hosting Pattern](./mcp_layout.md) - [Skill Usage Mechanics](./usage.md) - [Copilot MCP Mechanics](./copilot.md) diff --git a/docs/mcp_layout.md b/docs/mcp_layout.md index e0fe0d0..e23e65c 100644 --- a/docs/mcp_layout.md +++ b/docs/mcp_layout.md @@ -32,55 +32,35 @@ treeView-beta "zensical.toml" "docs" "index.md" - "architecture.md" - "content.md" - "frontmatter.md" + ".md" + "contracts" + "index.md" + ".md" "mcp_layout.md" - "uris.md" + "prompts" + "" + "PROMPT.md" + "references" "skills" - "new-skill" - "SKILL.md" - "references" - "copilot-customization" - "SKILL.md" - "references" - "fastapi-async-sqlalchemy-modernization" - "SKILL.md" - "references" - "fastapi-uv-docker" - "SKILL.md" - "references" - "nicegui" - "SKILL.md" - "references" - "nicegui-ui-customization" - "SKILL.md" - "references" - "pytest-scaffolding" - "SKILL.md" - "references" - "python-logging-dictconfig" - "SKILL.md" - "references" - "vscode-configuration" - "SKILL.md" - "references" - "zensical-docs" + "" "SKILL.md" "references" + ".md" "site" "static build output" "src" "personal_mcp" + "__init__.py" "main.py" "mcp.py" - "web" - "app.py" - "docs_mount.py" "catalog" - "server.py" + ".py" + "registry" + ".py" + "web" + ".py" "skills" - "document_loader.py" + ".py" ``` Notes: @@ -88,7 +68,8 @@ Notes: 1. docs contains both project-authored pages and the canonical skill Markdown tree. 2. site contains static build output only. 3. docs/skills contains canonical skill Markdown and reference Markdown. -4. MCP resources and docs site read from the same Markdown sources. +4. docs/prompts contains canonical prompt Markdown used for prompt catalog and document surfaces. +5. MCP resources and docs site read from the same Markdown sources. ## Runtime Composition diff --git a/docs/prompts/initial-test-structure/PROMPT.md b/docs/prompts/initial-test-structure/PROMPT.md new file mode 100644 index 0000000..d314480 --- /dev/null +++ b/docs/prompts/initial-test-structure/PROMPT.md @@ -0,0 +1,23 @@ +--- +name: initial-test-structure +description: Create an initial pytest test structure for a target project scope using repository conventions. +x-personal-mcp: + id: initial-test-structure + version: 1.0.0 + tags: + - pytest + - testing + capabilities: + - resource://prompts/initial-test-structure/document + arguments: + target_scope: + type: string + description: Target project, package, or module to scaffold tests for. + required: false +--- + +# Prompt For Creating Initial Test Structure + +Create an initial test structure in `./tests` based around pytest best practices. + +Use for an overview of best practices `resource://skills/pytest-scaffolding/document`. Take into account the naming structure too and pull in other relevant resources like for fastapi testing \ No newline at end of file diff --git a/docs/skills/new-skill/SKILL.md b/docs/skills/new-skill/SKILL.md index f5698f3..97b83bf 100644 --- a/docs/skills/new-skill/SKILL.md +++ b/docs/skills/new-skill/SKILL.md @@ -46,10 +46,10 @@ If the domain includes naming or hierarchy conventions, include a dedicated nami 1. Use this file as the baseline template for new skill authoring. 2. Read and follow these docs before implementing a new skill: - [docs/architecture.md](../../architecture.md) - - [docs/content.md](../../content.md) - - [docs/frontmatter.md](../../frontmatter.md) + - [docs/contracts/content.md](../../contracts/content.md) + - [docs/contracts/frontmatter.md](../../contracts/frontmatter.md) - [docs/mcp_layout.md](../../mcp_layout.md) - - [docs/uris.md](../../uris.md) + - [docs/contracts/uris.md](../../contracts/uris.md) ## Canonical Skill Shape diff --git a/zensical.toml b/zensical.toml index 689db02..92207f2 100644 --- a/zensical.toml +++ b/zensical.toml @@ -48,9 +48,12 @@ nav = [ { "Home" = "index.md" }, { "Guide" = [ { "Arch" = "architecture.md" }, - { "Content" = "content.md" }, - { "Frontmatter" = "frontmatter.md" }, - { "URIs" = "uris.md" }, + { "Contracts" = [ + { "Overview" = "contracts/index.md" }, + { "Content" = "contracts/content.md" }, + { "Frontmatter" = "contracts/frontmatter.md" }, + { "URIs" = "contracts/uris.md" }, + ] }, { "MCP" = "mcp_layout.md" }, { "Copilot" = "copilot.md" }, { "Usage" = "usage.md" },