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

doc updates for new structure

Browse Source
This commit is contained in:
John Lancaster
2026-08-30 00:16:58 -05:00
parent afedcda930
commit 88474a75f5
14 changed files with 65 additions and 68 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/copilot-instructions.md
+1 -1
View File
@@ -2,7 +2,7 @@
This repository is resource-first.
- Canonical skill guidance lives in `docs/skills/<skill-id>/SKILL.md`.
- Canonical skill guidance lives in `src/personal_mcp/docs/skills/<skill-id>/SKILL.md`.
- Skills are exposed through FastMCP's native `skill://` resource family.
- Prompts are exposed through native MCP prompt operations (`prompts/list`, `prompts/get`).
- General documentation pages are exposed through `resource://docs/{path*}`.
.github/instructions/authoring.instructions.md
+8 -8
View File
@@ -1,19 +1,19 @@
---
name: Authoring Content
description: "Use when editing Markdown under docs/. Routes authors to the canonical docs ownership, layout, and symlink guidance."
applyTo: 'docs/**/*.md'
description: "Use when editing Markdown under src/personal_mcp/docs/. Routes authors to the canonical docs ownership and layout guidance."
applyTo: 'src/personal_mcp/docs/**/*.md'
---
For edits under `docs/`, use the [Authoring Guide](../../docs/authoring.md) as the entry point for content placement and contracts.
For edits under `src/personal_mcp/docs/`, use the [Authoring Guide](../../src/personal_mcp/docs/authoring.md) as the entry point for content placement and contracts.
For source-tree ownership, symlink, packaging, or runtime questions, follow [Source Tree Ownership](../../docs/authoring.md). Treat that section as authoritative instead of restating its guidance here.
For source-tree ownership, packaging, or runtime questions, follow [Source Tree Ownership](../../src/personal_mcp/docs/authoring.md). Treat that section as authoritative instead of restating its guidance here.
Primary references:
- [Skill contract](../../docs/contracts/skill_contract.md)
- [Prompt contract](../../docs/contracts/prompt.md)
- [Frontmatter contract](../../docs/contracts/frontmatter.md)
- [URI contract](../../docs/contracts/uris.md)
- [Skill contract](../../src/personal_mcp/docs/contracts/skill_contract.md)
- [Prompt contract](../../src/personal_mcp/docs/contracts/prompt.md)
- [Frontmatter contract](../../src/personal_mcp/docs/contracts/frontmatter.md)
- [URI contract](../../src/personal_mcp/docs/contracts/uris.md)
- `skill://zensical-docs/SKILL.md`
Inspect `skill://zensical-docs/_manifest` only when a supporting documentation reference is needed.
.github/instructions/pytesting.instructions.md
+1 -1
View File
@@ -21,4 +21,4 @@ Execution pattern:
If task intent is ambiguous, ask one clarifying question before editing.
Be sure to also refer to the [testing page](../../docs/testing.md) page for design detail
Be sure to also refer to the [testing page](../../src/personal_mcp/docs/testing.md) for design detail.
.github/prompts/pytest-fill-scaffold.prompt.md
+5 -5
View File
@@ -26,11 +26,11 @@ Use this prompt after test scaffolding exists and method names/docstrings are al
Load these in order and use only what matches the task:
1. Core defaults: [pytest scaffolding skill](../../docs/skills/pytesting/SKILL.md)
2. Naming/hierarchy preservation: [naming and organization](../../docs/skills/pytesting/references/naming-and-organization.md)
3. Baseline pytest fixtures/markers: [pytest docs notes](../../docs/skills/pytesting/references/pytest-docs.md)
4. FastAPI-specific behavior (only when needed): [fastapi testing](../../docs/skills/pytesting/references/fastapi-testing.md)
5. SQLAlchemy-specific behavior (only when needed): [sqlalchemy testing](../../docs/skills/pytesting/references/sqlalchemy-testing.md)
1. Core defaults: [pytest scaffolding skill](../../src/personal_mcp/docs/skills/pytesting/SKILL.md)
2. Naming/hierarchy preservation: [naming and organization](../../src/personal_mcp/docs/skills/pytesting/references/naming-and-organization.md)
3. Baseline pytest fixtures/markers: [pytest docs notes](../../src/personal_mcp/docs/skills/pytesting/references/pytest-docs.md)
4. FastAPI-specific behavior (only when needed): [fastapi testing](../../src/personal_mcp/docs/skills/pytesting/references/fastapi-testing.md)
5. SQLAlchemy-specific behavior (only when needed): [sqlalchemy testing](../../src/personal_mcp/docs/skills/pytesting/references/sqlalchemy-testing.md)
## Workflow
.github/prompts/pytest-scaffold.prompt.md
+2 -2
View File
@@ -24,8 +24,8 @@ Use this prompt to do in one run what we have been doing manually in chat:
## Repository Rules To Apply
- Use [pytest scaffolding skill](../../docs/skills/pytesting/SKILL.md) for strategy and defaults.
- Use [naming and organization reference](../../docs/skills/pytesting/references/naming-and-organization.md) before finalizing hierarchy.
- Use [pytest scaffolding skill](../../src/personal_mcp/docs/skills/pytesting/SKILL.md) for strategy and defaults.
- Use [naming and organization reference](../../src/personal_mcp/docs/skills/pytesting/references/naming-and-organization.md) before finalizing hierarchy.
- Use `uv run pytest --collect-only -q` as structural validation.
- Default to a source-mirror style adapted to this repository:
- map selected modules to `tests/` with concise path segments when requested
src/personal_mcp/docs/architecture.md
+6 -6
View File
@@ -6,7 +6,7 @@ icon: lucide/library
## Overview
The application combines a FastMCP server with a pre-built Zensical documentation site. Markdown under `docs/` is the single authored content tree, while native FastMCP providers own skill and prompt discovery.
The application combines a FastMCP server with a pre-built Zensical documentation site. Markdown under `src/personal_mcp/docs/` is the single authored content tree, while native FastMCP providers own skill and prompt discovery.
The runtime has four content paths:
@@ -23,8 +23,8 @@ There is no custom skill catalog, prompt catalog, or per-prompt Python module.
Each skill owns one directory:
1. `docs/skills/<skill-id>/SKILL.md`
2. `docs/skills/<skill-id>/<supporting-path>`
1. `src/personal_mcp/docs/skills/<skill-id>/SKILL.md`
2. `src/personal_mcp/docs/skills/<skill-id>/<supporting-path>`
`SkillsDirectoryProvider` publishes:
@@ -36,7 +36,7 @@ The provider parses standard skill frontmatter and generates the manifest. The g
### Prompts
Each prompt has one source: `docs/prompts/<prompt-id>/PROMPT.md`. Its nested `prompt` frontmatter owns runtime metadata and argument declarations, while its body owns canonical prose.
Each prompt has one source: `src/personal_mcp/docs/prompts/<prompt-id>/PROMPT.md`. Its nested `prompt` frontmatter owns runtime metadata and argument declarations, while its body owns canonical prose.
The custom provider reads packaged Markdown with `importlib.resources`, validates metadata and exact placeholder-to-argument equality, and creates native FastMCP prompt objects. It rescans on each list and get request, so an editable deployment observes file additions, edits, and deletions without a restart.
@@ -65,7 +65,7 @@ Server construction is lazy with respect to package import. Each application pro
## Packaging
The repository root `docs/` directory is the only authored Markdown source. `src/personal_mcp/docs` is a relative symlink used by source checkouts and editable installs. Hatchling follows it and stores regular files beneath `personal_mcp/docs/` in the wheel.
The regular directory `src/personal_mcp/docs/` is the only authored Markdown source. The `uv_build` backend includes it as package data beneath `personal_mcp/docs/` in built distributions.
Runtime reads are package-relative:
@@ -92,7 +92,7 @@ Only these canonical provider and protocol surfaces are registered.
## Static Documentation
Zensical builds `docs/` into `site/` before deployment. FastAPI mounts that immutable output in the same process that hosts FastMCP. Generated `site/` files are deployment assets and are never an authored source.
Zensical builds `src/personal_mcp/docs/` into `src/personal_mcp/site/` before deployment. FastAPI mounts that immutable output in the same process that hosts FastMCP. Generated site files are deployment assets and are never an authored source.
## Validation
src/personal_mcp/docs/authoring.md
+8 -9
View File
@@ -4,7 +4,7 @@ icon: lucide/pencil
# Authoring Guide
This page defines the practical workflow for maintaining skills, prompts, and project documentation while keeping root `docs/` as the only authored source.
This page defines the practical workflow for maintaining skills, prompts, and project documentation in the package-native `src/personal_mcp/docs` source tree.
Primary references:
@@ -16,16 +16,16 @@ Primary references:
## Source Tree Ownership
Edit content only under root `docs/`. The `src/personal_mcp/docs` path is a relative symlink for editable installs; do not author through a copied package tree.
Edit content only under `src/personal_mcp/docs`. This directory is the canonical authored source for both MCP content and the documentation site.
Hatchling's normal package traversal follows `src/personal_mcp/docs` during wheel builds and archives the linked targets as regular files under `personal_mcp/docs/`. Do not add a `force-include` entry for root `docs/`; it duplicates those wheel paths. The installed package therefore gives `SkillsDirectoryProvider` a regular filesystem directory while Zensical builds the human site directly from root `docs/`.
The `uv_build` backend packages this tree under `personal_mcp/docs/`. The installed package therefore gives runtime providers package-relative content, while Zensical builds the human site directly from `src/personal_mcp/docs` as configured by `docs_dir` in the repository's `zensical.toml`.
Generated `site/` content is a build artifact and must not be edited by hand.
Generated `src/personal_mcp/site/` content is a build artifact and must not be edited by hand.
## Content Layout
```text
docs/
src/personal_mcp/docs/
*.md
contracts/
prompts/<prompt-id>/
@@ -40,7 +40,7 @@ Keep skill and prompt files inside their owning directories. Relative links may
## Skill Authoring
A skill is discovered when a direct child of `docs/skills/` contains `SKILL.md`.
A skill is discovered when a direct child of `src/personal_mcp/docs/skills/` contains `SKILL.md`.
Required frontmatter:
@@ -72,9 +72,9 @@ Recommended sequence:
## Prompt Authoring
A prompt is one self-describing `docs/prompts/<prompt-id>/PROMPT.md` file:
A prompt is one self-describing `src/personal_mcp/docs/prompts/<prompt-id>/PROMPT.md` file:
1. Create a lowercase kebab-case directory beneath `docs/prompts/`.
1. Create a lowercase kebab-case directory beneath `src/personal_mcp/docs/prompts/`.
2. Add a nested `prompt` frontmatter mapping with version, description, tags, and ordered arguments.
3. Give every argument a description and explicit required flag.
4. Add `choices` only when a string argument accepts a fixed set of values.
@@ -112,7 +112,6 @@ When deeper guidance is needed, read the selected skill's `_manifest` and fetch
## Validation Checklist
```bash
uv run pytest tests/skills/test_provider.py tests/web/test_mcp_skills.py -q
uv run zensical build
uv run ruff check .
uv run ty check
src/personal_mcp/docs/contracts/frontmatter.md
+1 -1
View File
@@ -69,4 +69,4 @@ Prompt validation is provider- and renderer-oriented. Every list or get request
1. Skills remain directly portable to tools that understand standard Agent Skills directories.
2. Native skill discovery has no parallel catalog metadata source.
3. Prompts use FastMCP's native component metadata and protocol surface without a parallel catalog or Python component file.
4. All authored content remains under `docs/`.
4. All authored content remains under `src/personal_mcp/docs/`.
src/personal_mcp/docs/contracts/index.md
+8 -8
View File
@@ -21,13 +21,13 @@ This page defines the authored content contract for the docs-first MCP architect
## Canonical Source Of Truth
1. All authored Markdown lives under `docs/`.
1. All authored Markdown lives under `src/personal_mcp/docs/`.
2. MCP resources and static docs are two distribution surfaces of the same authored files.
3. No parallel authored markdown is allowed in `src/` or other package-only paths.
3. No parallel authored Markdown is allowed in a root `docs/` directory or another source tree.
## Canonical Content Shape
Authored content is organized under `docs/`:
Authored content is organized under `src/personal_mcp/docs/`:
```mermaid
---
@@ -41,7 +41,7 @@ config:
lineColor: '#FFFFFF'
---
treeView-beta
"docs/"
"src/personal_mcp/docs/"
"*.md (top-level docs pages)"
"contracts/"
"prompt.md"
@@ -59,9 +59,9 @@ treeView-beta
## File Placement And Ownership Boundaries
1. Top-level project docs stay in `docs/*.md`.
2. Skill docs stay in `docs/skills/<skill-id>/...`.
3. Prompt docs stay in `docs/prompts/<prompt-id>/...`.
1. Top-level project docs stay in `src/personal_mcp/docs/*.md`.
2. Skill docs stay in `src/personal_mcp/docs/skills/<skill-id>/...`.
3. Prompt docs stay in `src/personal_mcp/docs/prompts/<prompt-id>/...`.
4. A skill or prompt may link across sections, but must not store content in another artifact's directory.
5. Server and runtime code may index and serve docs, but must not be the source of authored markdown.
@@ -74,7 +74,7 @@ treeView-beta
This contract guarantees:
1. One authored source tree in `docs/` for both website and MCP.
1. One authored source tree in `src/personal_mcp/docs/` for both website and MCP.
2. Skill and prompt artifacts remain path-stable within their own sections.
3. Cross-surface publishing remains deterministic because authored content paths are canonical.
src/personal_mcp/docs/contracts/prompt.md
+2 -2
View File
@@ -22,7 +22,7 @@ config:
lineColor: '#FFFFFF'
---
treeView-beta
"docs/prompts/"
"src/personal_mcp/docs/prompts/"
"<prompt-id>/"
"PROMPT.md"
"src/personal_mcp/prompts/"
@@ -45,7 +45,7 @@ Rules:
1. Each `PROMPT.md` owns both its runtime metadata and prose.
2. Python owns only generic parsing, validation, rendering, and provider behavior.
3. There is no central prompt catalog, generated signature, or metadata sidecar.
4. The provider scans direct children of packaged `docs/prompts/` on each list or get request.
4. The provider scans direct children of packaged `personal_mcp/docs/prompts/` on each list or get request.
5. Additions, edits, and deletions become visible on the next request without restarting the server.
6. Reload is pull-based; the provider does not watch files or emit proactive change notifications.
src/personal_mcp/docs/contracts/skill_contract.md
+3 -3
View File
@@ -8,7 +8,7 @@ This page defines the canonical contract for skills in the docs-first MCP archit
## Canonical Skill Shape
Each skill is one directory under `docs/skills/`:
Each skill is one directory under `src/personal_mcp/docs/skills/`:
```mermaid
---
@@ -22,7 +22,7 @@ config:
lineColor: '#FFFFFF'
---
treeView-beta
"docs/"
"src/personal_mcp/docs/"
"... (other docs)"
"skills/"
"<skill-id>/"
@@ -70,7 +70,7 @@ Invalid examples:
## Provider Publication
[`SkillsDirectoryProvider`](https://gofastmcp.com/servers/providers/skills) scans `docs/skills/` with `supporting_files="template"` and publishes:
[`SkillsDirectoryProvider`](https://gofastmcp.com/servers/providers/skills) scans packaged `personal_mcp/docs/skills/` with `supporting_files="template"` and publishes:
1. `skill://<skill-id>/SKILL.md`
2. `skill://<skill-id>/_manifest`
src/personal_mcp/docs/contracts/uris.md
+1 -1
View File
@@ -46,7 +46,7 @@ FastMCP confines reads to the selected skill directory. Absolute paths, traversa
## General Docs URI
General authored documentation is exposed through `resource://docs/{path*}`. The wildcard accepts normalized relative POSIX Markdown paths beneath `docs/`, excludes the provider-owned `skills/` subtree, and rejects absolute paths, traversal segments, backslashes, and non-Markdown targets.
General authored documentation is exposed through `resource://docs/{path*}`. The wildcard accepts normalized relative POSIX Markdown paths beneath packaged `personal_mcp/docs/`, excludes the provider-owned `skills/` subtree, and rejects absolute paths, traversal segments, backslashes, and non-Markdown targets.
Prompts are MCP prompt components rather than resources. Clients discover them with the protocol `prompts/list` operation and render them with `prompts/get`.
src/personal_mcp/docs/mcp_layout.md
+18 -20
View File
@@ -6,7 +6,7 @@ icon: lucide/server
## Purpose
The project serves native MCP content and a pre-built documentation site from one FastAPI process. Markdown is authored once under `docs/`; runtime providers and Zensical consume that same packaged tree for different purposes.
The project serves native MCP content and a pre-built documentation site from one FastAPI process. Markdown is authored once under `src/personal_mcp/docs/`; runtime providers and Zensical consume that same package-owned tree for different purposes.
## Repository Layout
@@ -19,29 +19,27 @@ config:
---
treeView-beta
"project-root"
"docs"
"prompts/<prompt-id>/PROMPT.md"
"skills/<skill-id>/SKILL.md"
"skills/<skill-id>/<supporting-files>"
"<general-pages>.md"
"site"
"static build output"
"src/personal_mcp"
"docs"
"prompts/<prompt-id>/PROMPT.md"
"skills/<skill-id>/SKILL.md"
"skills/<skill-id>/<supporting-files>"
"<general-pages>.md"
"site"
"static build output"
"app.py"
"mcp.py"
"prompts/content.py"
"prompts/models.py"
"prompts/provider.py"
"skills.py"
"prompts/"
"registry/"
"skills/provider.py"
"web/"
```
Ownership rules:
1. `docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
2. Each file under `docs/prompts/` owns its prompt metadata, argument schema, and prose.
1. `src/personal_mcp/docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
2. Each file under `src/personal_mcp/docs/prompts/` owns its prompt metadata, argument schema, and prose.
3. The docs registry owns only general Markdown resources and explicitly excludes skills.
4. `site/` is generated output.
4. `src/personal_mcp/site/` is generated output.
5. The deleted custom `catalog/` package is not part of the runtime.
## Runtime Composition
@@ -70,8 +68,8 @@ Runtime guarantees:
## Build And Publish Flow
1. Author prompt definitions and prose under `docs/prompts/`.
2. Run `uv run zensical build` to produce `site/`.
1. Author prompt definitions and prose under `src/personal_mcp/docs/prompts/`.
2. Run `uv run zensical build` to produce `src/personal_mcp/site/`.
3. Build the wheel, which packages the authored docs under `personal_mcp/docs/`.
4. Start the app and serve MCP plus the static site.
@@ -79,10 +77,10 @@ No runtime Markdown-to-HTML conversion occurs.
## Machine-Facing Mapping
1. `docs/skills/<skill-id>/SKILL.md` maps to `skill://<skill-id>/SKILL.md`.
1. `src/personal_mcp/docs/skills/<skill-id>/SKILL.md` maps to `skill://<skill-id>/SKILL.md`.
2. Skill supporting files map to `skill://<skill-id>/<path>`.
3. Declarative prompt documents map to native MCP prompt names.
4. General `docs/<path>.md` maps to `resource://docs/{path*}`.
4. General `src/personal_mcp/docs/<path>.md` maps to `resource://docs/{path*}`.
The server publishes no tool projections of resources or prompts.
src/personal_mcp/docs/usage.md
+1 -1
View File
@@ -12,7 +12,7 @@ Skills are MCP resources. The client remains responsible for selecting guidance,
## Published Skill Surface
Each directory beneath `docs/skills/` publishes:
Each directory beneath `src/personal_mcp/docs/skills/` publishes:
1. `skill://<name>/SKILL.md` for primary instructions
2. `skill://<name>/_manifest` for file discovery and integrity metadata