doc updates for new structure

.github/copilot-instructions.md

@@ -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

@@ -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."
+description: "Use when editing Markdown under src/personal_mcp/docs/. Routes authors to the canonical docs ownership and layout guidance."
-applyTo: 'docs/**/*.md'
+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)
+- [Skill contract](../../src/personal_mcp/docs/contracts/skill_contract.md)
-- [Prompt contract](../../docs/contracts/prompt.md)
+- [Prompt contract](../../src/personal_mcp/docs/contracts/prompt.md)
-- [Frontmatter contract](../../docs/contracts/frontmatter.md)
+- [Frontmatter contract](../../src/personal_mcp/docs/contracts/frontmatter.md)
-- [URI contract](../../docs/contracts/uris.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

@@ -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

@@ -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)
+1. Core defaults: [pytest scaffolding skill](../../src/personal_mcp/docs/skills/pytesting/SKILL.md)
-2. Naming/hierarchy preservation: [naming and organization](../../docs/skills/pytesting/references/naming-and-organization.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](../../docs/skills/pytesting/references/pytest-docs.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](../../docs/skills/pytesting/references/fastapi-testing.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](../../docs/skills/pytesting/references/sqlalchemy-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

@@ -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 [pytest scaffolding skill](../../src/personal_mcp/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 [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,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`
+1. `src/personal_mcp/docs/skills/<skill-id>/SKILL.md`
-2. `docs/skills/<skill-id>/<supporting-path>`
+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

@@ -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

@@ -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

@@ -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`.
+1. Top-level project docs stay in `src/personal_mcp/docs/*.md`.
-2. Skill docs stay in `docs/skills/<skill-id>/...`.
+2. Skill docs stay in `src/personal_mcp/docs/skills/<skill-id>/...`.
-3. Prompt docs stay in `docs/prompts/<prompt-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

@@ -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

@@ -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

@@ -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

@@ -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"
+         "skills.py"
-         "prompts/models.py"
+         "prompts/"
-         "prompts/provider.py"
          "registry/"
-         "skills/provider.py"
-         "web/"
 ```
 
 Ownership rules:
 
-1. `docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
+1. `src/personal_mcp/docs/skills/` is owned exclusively by `SkillsDirectoryProvider` at runtime.
-2. Each file under `docs/prompts/` owns its prompt metadata, argument schema, and prose.
+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/`.
+1. Author prompt definitions and prose under `src/personal_mcp/docs/prompts/`.
-2. Run `uv run zensical build` to produce `site/`.
+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

@@ -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