john/prompts
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

doc updates

Browse Source
This commit is contained in:
John Lancaster
2026-06-20 14:56:25 -05:00
parent 467e1d3c35
commit bb7508cf65
9 changed files with 537 additions and 79 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/architecture.md
+15 -5
View File
@@ -16,11 +16,17 @@ The system is complete in three layers:
2. Catalog resources provide normalized discovery.
3. Zensical builds a static site from those same Markdown sources and the FastAPI app serves it in the FastMCP runtime process.
For Phase 1, this architecture is anchored by three contracts:
This architecture is anchored by three contracts:
1. Step 1: docs-first authored content contract under `docs/` with strict per-skill ownership.
2. Step 2: SKILL.md frontmatter contract with Anthropic fields plus `x-personal-mcp` metadata.
3. Step 3: canonical resource URI contract with break-and-replace policy for contract changes.
1. Docs-first authored content contract under `docs/` with strict per-skill ownership.
2. `SKILL.md` frontmatter contract with Anthropic fields plus `x-personal-mcp` metadata.
3. Canonical resource URI contract with break-and-replace policy for contract changes.
Detailed contract pages:
1. [Content Contract](./content.md)
2. [Frontmatter Contract](./frontmatter.md)
3. [URI Contract](./uris.md)
This architecture keeps authored content human-friendly while preserving machine-stable contracts.
@@ -62,7 +68,7 @@ Only canonical catalog resources are part of the runtime contract in this phase.
### Registry Loader
Phase 2 runtime composition introduces a startup registry loader that reads packaged docs resources using `importlib.resources.files(...)` and `Traversable` APIs.
The runtime composition includes a startup registry loader that reads packaged docs resources using `importlib.resources.files(...)` and `Traversable` APIs.
Loader responsibilities:
@@ -104,6 +110,8 @@ flowchart TD
Each skill declares frontmatter in `docs/skills/<skill-id>/SKILL.md`.
For the full field-level contract, validation model, and FastMCP metadata mapping, see [Frontmatter Contract](./frontmatter.md).
Anthropic-facing required fields:
1. name
@@ -124,6 +132,8 @@ 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).
1. resource://skills/<skill_id>/document
2. resource://skills/<skill_id>/references/<ref_id>
3. resource://catalog/skills_index