copilot instructions

.github/instructions/zensical-docs.instructions.md

@@ -0,0 +1,9 @@
+---
+name: Zensical Docs Markdown Guidance
+description: Use the Zensical docs MCP resource when editing Markdown documentation in this repository.
+applyTo: '**/*.md'
+---
+
+When editing Markdown files in this repository, use the Zensical docs resource `resource://skills/zensical-docs/document` for relevant documentation authoring guidance.
+
+Prefer Zensical-native documentation conventions when they cover the need cleanly, while preserving expected MkDocs compatibility unless the Zensical guidance intentionally diverges.

docker-compose.yaml

@@ -0,0 +1,8 @@
+services:
+  personal-mcp:
+    build:
+      context: .
+      dockerfile: Dockerfile
+    ports:
+      - "8765:8765"
+    restart: unless-stopped

docs/securing.md

@@ -0,0 +1,139 @@
+---
+icon: lucide/shield-check
+---
+
+# Securing Remote Access
+
+## Context
+
+This project exposes two related surfaces from the same runtime:
+
+1. a static documentation site under `/docs`
+2. a Streamable HTTP MCP endpoint under `/mcp`
+
+The same Markdown content backs both surfaces. For the current project shape, the MCP server is resource-first and primarily exposes public skill and documentation text. It is not intended to expose secrets, private data, shell access, filesystem access, or tools with side effects.
+
+The expected deployment path is:
+
+```text
+Public internet
+	-> Cloudflare Tunnel
+	-> Caddy
+	-> personal-mcp container
+```
+
+## Decision
+
+For the current use case, heavy application-level authentication is not required.
+
+The recommended posture is:
+
+1. Keep the service behind Cloudflare Tunnel and Caddy.
+2. Do not expose the container port directly to the public internet.
+3. Treat everything exposed through MCP as publishable public documentation.
+4. Add stronger authentication only if the MCP surface later includes sensitive content or tools with meaningful side effects.
+
+This keeps the deployment simple while preserving a clear upgrade path.
+
+## Tradeoffs
+
+### Leaving `/mcp` Public
+
+This is acceptable if `/mcp` exposes only the same public Markdown already available through `/docs`.
+
+Benefits:
+
+1. lowest operational friction
+2. fewer compatibility issues with MCP clients
+3. no need to implement OAuth, mTLS, JWT validation, or custom auth middleware
+4. consistent with the project assumption that documentation content is public
+
+Risks:
+
+1. random scraping, probing, or fuzzing of a machine endpoint
+2. possible bandwidth or CPU nuisance traffic
+3. accidental future exposure if new tools or private resources are added
+4. less control over who can use the MCP endpoint
+
+### Protecting `/mcp` With Cloudflare Access
+
+Cloudflare Access can add a lightweight gate using GitHub, Google, one-time PIN, or service tokens.
+
+Benefits:
+
+1. reduces random internet traffic
+2. requires little app code
+3. works well for a small trusted team
+4. provides logs and centralized access control
+
+Costs:
+
+1. browser-based login may not work with all MCP clients
+2. non-browser MCP clients may need Cloudflare Access service tokens
+3. adds operational configuration for a low-sensitivity endpoint
+
+### Using mTLS
+
+mTLS is useful when both client and server environments are tightly controlled.
+
+Benefits:
+
+1. strong client identity
+2. good fit for service-to-service or private infrastructure
+3. can be used between Cloudflare, Caddy, and the backend if desired
+
+Costs:
+
+1. harder certificate provisioning and rotation
+2. weaker compatibility with normal MCP clients
+3. unnecessary for public documentation-only content
+
+For this project, mTLS is not the primary recommendation.
+
+## Practical Recommendation
+
+Use a simple public-docs posture unless the endpoint changes.
+
+Recommended current setup:
+
+```text
+/docs  public
+/mcp   public or lightly protected
+```
+
+If `/mcp` remains public, add only basic operational safeguards:
+
+1. keep Cloudflare Tunnel and Caddy in front
+2. avoid publishing `8765` directly
+3. enable Cloudflare or Caddy rate limiting if traffic becomes noisy
+4. monitor logs for unusual request volume
+5. document that MCP resources must remain safe to publish
+
+A slightly stricter setup is also reasonable:
+
+```text
+/docs  public
+/mcp   Cloudflare Access or service token
+```
+
+This is the best option if the team wants to reduce drive-by MCP traffic without adding auth code to the application.
+
+## Upgrade Trigger
+
+Add real authentication before introducing any MCP capability that can:
+
+1. read non-public files
+2. access private notes or credentials
+3. call upstream APIs
+4. mutate data
+5. run commands
+6. expose environment details
+7. perform expensive computation
+
+At that point, prefer edge-level authentication first, such as Cloudflare Access, and consider proper OAuth 2.1 resource-server behavior only if broad public MCP client interoperability becomes a goal.
+
+## Security Invariant
+
+Everything exposed by the MCP server must be safe to publish publicly.
+
+If that invariant stops being true, `/mcp` should be protected before the new capability is deployed.

docs/skills/copilot-customization/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: copilot-customization
+description: 'Plan, create, review, and debug GitHub Copilot and VS Code agent customizations, including instructions, prompt files, skills, custom agents, hooks, MCP servers, and repo-specific personal-mcp skill integration.'
+argument-hint: 'What Copilot behavior are you customizing, and should it be workspace-scoped, personal, or exposed as an MCP skill resource?'
+---
+
+# Copilot Customization
+
+Use this skill when a task is about changing how GitHub Copilot or VS Code agents behave through customization files or MCP-backed skill resources.
+
+## When to Use
+
+- Creating or updating `.github/copilot-instructions.md`, `AGENTS.md`, `CLAUDE.md`, or `*.instructions.md` files.
+- Creating prompt files, custom agents, hooks, or Agent Skills.
+- Deciding whether behavior belongs in instructions, prompts, skills, agents, hooks, MCP servers, or agent plugins.
+- Debugging why a customization is not discovered, loaded, or invoked.
+- Adding a new documentation-backed skill to this `personal-mcp` repository.
+
+## Start With The Decision
+
+Choose the smallest customization that matches the desired behavior:
+
+1. Use always-on instructions for project-wide coding standards, architecture decisions, security rules, and documentation standards that should apply to most requests.
+2. Use file-based instructions for conventions that only apply to matching files, folders, languages, frameworks, or documentation types.
+3. Use prompt files for reusable slash commands that package a single recurring prompt.
+4. Use Agent Skills for portable, task-specific workflows that may include references, scripts, examples, or templates.
+5. Use custom agents for specialized personas, tool restrictions, model choices, or role-specific workflows.
+6. Use hooks when a deterministic lifecycle action must enforce a policy, run a command, or block unsafe behavior.
+7. Use MCP servers when the agent needs live external tools, structured resources, or discoverable data beyond static instruction files.
+8. Use agent plugins when several related customizations should ship together as an installable package.
+
+If the request is ambiguous, ask only for the missing axis that changes the file type: scope, trigger, expected output, required tools, or whether it must be portable beyond VS Code.
+
+## Research Map
+
+Use [VS Code customization references](./references/vscode-customization.md) for official-source details about locations, frontmatter, discovery behavior, priority, and troubleshooting.
+
+## Workspace Customization Workflow
+
+1. Identify the customization primitive and scope.
+2. Check existing files before creating a new one.
+3. Keep the description or frontmatter trigger specific and keyword-rich.
+4. Keep instructions concise, focused, and self-contained.
+5. Add examples only when they clarify a non-obvious convention.
+6. For `*.instructions.md`, set `applyTo` only when automatic file matching is intended.
+7. For skills, make the folder name match the `name` field exactly and reference any extra files from `SKILL.md` with relative links.
+8. Validate placement, YAML frontmatter, discovery settings, and whether the customization should be workspace or user scoped.
+
+## Repo Integration Workflow
+
+When adding a new skill to this `personal-mcp` repo, follow the resource-first pattern:
+
+1. Search the catalog for `new skill` and load `resource://skills/new-skill/document`.
+2. Create authored docs under `docs/skills/<slug>/SKILL.md`, with optional one-level `references/` files.
+3. Choose consistent names: docs slug and resource id use kebab-case; Python namespace uses snake_case.
+4. Create `src/personal_mcp/skills/<python_namespace>/` with `__init__.py`, `server.py`, and `metadata.yaml`.
+5. Expose only `resource://skills/<skill-id>/document` from the per-skill server.
+6. Put discovery metadata in `metadata.yaml`, including `id`, `name`, `version`, `description`, `tags`, `capabilities`, and `depends_on`.
+7. Mount the skill server in `src/personal_mcp/mcp.py` using the Python namespace.
+8. Validate with the document loader and `uv run zensical build`.
+
+Keep per-skill servers resource-only. Catalog-level discovery is the only place for thin fallback discovery tools.
+
+## Quality Checks
+
+Before finishing:
+
+1. Confirm the customization file is in a supported location for its intended scope.
+2. Confirm required frontmatter fields are present and valid.
+3. Confirm names match directory names where VS Code requires it.
+4. Confirm descriptions include the phrases users are likely to ask for.
+5. Confirm extra skill resources are linked from `SKILL.md`.
+6. Confirm repo skill metadata exposes the correct `resource://skills/<skill-id>/document` capability.
+7. State any remaining ambiguity or user choice, such as personal vs workspace scope.
+
+## Output Contract
+
+Return the concrete customization created or changed, where it lives, how to invoke or trigger it, and any validation performed.

docs/skills/copilot-customization/references/vscode-customization.md

@@ -0,0 +1,82 @@
+# VS Code Copilot Customization References
+
+Use these notes as a source map before creating or debugging Copilot customizations.
+
+## Official Sources
+
+- Customization overview: https://code.visualstudio.com/docs/copilot/customization/overview
+- Custom instructions: https://code.visualstudio.com/docs/copilot/customization/custom-instructions
+- Agent skills: https://code.visualstudio.com/docs/copilot/customization/agent-skills
+- Prompt files: https://code.visualstudio.com/docs/copilot/customization/prompt-files
+- Custom agents: https://code.visualstudio.com/docs/copilot/customization/custom-agents
+- MCP servers: https://code.visualstudio.com/docs/copilot/customization/mcp-servers
+- Hooks: https://code.visualstudio.com/docs/copilot/customization/hooks
+
+## Customization Types
+
+- Instructions describe standards and conventions that apply to every request or to matching files.
+- Prompt files save reusable slash-command prompts for recurring tasks.
+- Agent Skills package reusable workflows, scripts, examples, and resources that load on demand.
+- Custom agents define specialized personas, tool access, model choices, and role-specific workflows.
+- MCP servers connect the agent to external tools, resources, and data.
+- Hooks run deterministic actions at defined lifecycle points.
+- Agent plugins bundle related customization types into an installable package.
+
+## Instructions
+
+Use `.github/copilot-instructions.md` for workspace-wide rules that should be included in every chat request. Use `AGENTS.md` when multiple agents should share the same repository guidance, or when nested agent guidance is useful. Use `CLAUDE.md` for Claude-compatible instruction sharing.
+
+Use `.github/instructions/**/*.instructions.md` for file-based or task-specific rules. Supported frontmatter fields include:
+
+```yaml
+---
+name: Documentation Standards
+description: Rules for documentation writing tasks
+applyTo: '**/*.md'
+---
+```
+
+`applyTo` is a workspace-relative glob. If it is omitted, the instruction file can still be manually attached but does not automatically apply by file match.
+
+## Agent Skills
+
+Skills live in a directory whose name must match the `name` field in `SKILL.md`. VS Code supports project skills in `.github/skills/`, `.claude/skills/`, and `.agents/skills/`, and personal skills under user-level skill folders.
+
+Required skill frontmatter:
+
+```yaml
+---
+name: skill-name
+description: Description of what the skill does and when to use it.
+---
+```
+
+Useful optional fields:
+
+- `argument-hint`: shown when invoking the skill as a slash command.
+- `user-invocable`: controls whether it appears in the slash menu.
+- `disable-model-invocation`: controls whether the model can auto-load it.
+- `context`: can use `fork` for a separate subagent context when supported.
+
+Skills load progressively: discovery reads frontmatter, instruction loading reads `SKILL.md`, and extra resources load only when linked from the skill document.
+
+## Priority And Discovery
+
+When multiple instruction sources apply, personal instructions have higher priority than repository instructions, and repository instructions have higher priority than organization instructions. If multiple instruction files exist, VS Code combines them; do not rely on ordering between instruction files.
+
+For monorepos, `chat.useCustomizationsInParentRepositories` can enable discovery from a trusted parent repository root. Skill locations can also be configured with `chat.agentSkillsLocations`, and instruction locations with `chat.instructionsFilesLocations`.
+
+## Troubleshooting
+
+If a customization is not applied:
+
+1. Confirm the file is in a supported location.
+2. Confirm frontmatter is valid YAML.
+3. Confirm skill `name` matches the parent directory.
+4. Confirm `applyTo` matches the file path when using `*.instructions.md`.
+5. Confirm relevant settings are enabled, such as instruction inclusion, referenced instruction inclusion, or AGENTS/CLAUDE support.
+6. Use the Chat customization diagnostics view or Agent Debug Logs to inspect what VS Code loaded.
+
+## Writing Effective Instructions
+
+Keep instructions short, self-contained, and focused on non-obvious rules. Include the reason for a rule when it helps with edge cases. Prefer concrete examples over abstract preferences. Split unrelated rules into separate targeted files when they have different triggers.

docs/skills/zensical-docs/SKILL.md

@@ -1,175 +1,95 @@
 ---
 name: zensical-docs
-description: 'Plan, write, and improve high-quality documentation with Zensical. Use for information architecture, progressive discoverability, writing standards, navigation/search tuning, and feature-driven docs site configuration.'
+description: 'Reference skill for Zensical documentation mechanics. Use for quick lookup of docs structure, feature options, and source links, then edit this skill over time to record project preferences for when each feature should be used.'
 argument-hint: 'What are you documenting, who is the audience, and what Zensical features are in scope?'
 ---
 
 # Zensical Documentation Authoring
 
-Create documentation that is easy to discover, easy to scan, and easy to trust, then configure Zensical so the site reinforces those outcomes.
+Use this as a compact reference for Zensical mechanics and as the place to record evolving preferences for how this repository uses them.
 
 ## When to Use
 
-- You are creating or restructuring docs in a Zensical project.
+- You need a quick reminder of Zensical features, docs structure, or configuration mechanics.
-- You need a repeatable workflow for docs quality and discoverability.
+- You want direct links back to source documentation before changing docs behavior.
-- You want guidance that combines writing best practices with Zensical feature choices.
+- You want one small file you can keep editing as your preferences around docs authoring become clearer.
-- You need a checklist-driven review before publishing.
 
-## Progressive Loading References
+## How To Use This Skill
 
-Load only the references required for the current task:
+1. Start here for a quick decision about what kind of docs change you are making.
+2. Open only the linked reference that matches the current task.
+3. Add or revise preference notes in this file when you decide how this repo should use a feature.
 
-- Source map for official docs and APIs: [./references/index.md](./references/index.md)
+## Quick Reference Map
-- Zensical features and configuration links: [./references/zensical-features.md](./references/zensical-features.md)
-- Theme customization, colors, icons, and extension patterns: [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md)
-- Docs writing quality and style guidance: [./references/documentation-quality.md](./references/documentation-quality.md)
-- Information architecture and discoverability patterns: [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md)
-- Code-heavy API docs with mkdocstrings: [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md)
 
-## Project Bootstrap Rule
+Open only what you need:
 
-Always start a new documentation project with `uv run zensical new`.
+- Official docs and source map: [./references/index.md](./references/index.md)
+- Zensical feature catalog and setup links: [./references/zensical-features.md](./references/zensical-features.md)
+- Theme, icons, and visual customization: [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md)
+- Writing quality and review criteria: [./references/documentation-quality.md](./references/documentation-quality.md)
+- Navigation and discoverability patterns: [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md)
+- Code-heavy docs and API reference patterns: [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md)
 
-- This command provides the baseline scaffolding you need for structure, configuration, and theme setup.
+## Common Cases
-- Do not hand-build a new project skeleton when this command is available.
 
-## Related Skill Discovery
+### New docs project
 
-When the task is not just writing docs but creating or wiring a new MCP skill in this repository, use catalog discovery to load the bootstrap skill before drafting implementation steps.
+- Start with `uv run zensical new`.
+- Then review [./references/index.md](./references/index.md) and [./references/zensical-features.md](./references/zensical-features.md).
 
-1. Search the catalog with terms such as `new skill`, `skill bootstrap`, or `scaffold skill`.
+### Restructuring docs or navigation
-2. Fetch the `new-skill` document through the catalog tool path.
-3. Use that skill for runtime package, metadata, and mount wiring, then return here for documentation architecture and Zensical-specific authoring guidance.
 
-This keeps implementation guidance and documentation guidance separated while still making both discoverable from one request.
+- Review [./references/discoverability-and-ia.md](./references/discoverability-and-ia.md).
+- Use it to decide overview pages, section structure, and cross-linking.
 
-## Inputs To Collect
+### Improving writing quality
 
-Collect these before writing. If missing, make explicit assumptions.
+- Review [./references/documentation-quality.md](./references/documentation-quality.md).
+- Use it for page quality gates, trust signals, and review criteria.
 
-1. Audience: beginner, intermediate, advanced, or mixed.
+### Adjusting theme or UI mechanics
-2. User goals: top tasks users come to complete.
-3. Product scope: features, versions, and deployment context.
-4. Content constraints: release deadlines, localization, legal/compliance needs.
-5. Navigation constraints: explicit `nav` vs implicit structure.
-6. Site-level expectations: search quality, code example depth, diagrams, API docs.
 
-## Procedure
+- Review [./references/theme-customization-and-icons.md](./references/theme-customization-and-icons.md).
+- Use it for icons, color, theme extensions, and presentation choices.
 
-### Step 0: Audit Current Documentation
+### Documenting APIs or code-heavy systems
 
-Build a quick baseline of what exists now.
+- Review [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md).
+- Use it when generated API reference belongs alongside hand-authored docs.
 
-1. List docs sections and current nav structure.
+## Preferences To Maintain Here
-2. Identify orphan pages (not in nav, weak internal linking, or no inbound links).
-3. Identify stale sections (version drift, missing prerequisites, broken commands).
-4. Capture recurring support questions and map each to a missing or weak doc page.
 
-Completion check: you can name the top 5 current documentation gaps.
+Keep this section short and revise it over time.
 
-### Step 1: Define Outcomes and Page Taxonomy
+### Preferred feature choices
 
-Organize content by user intent, not by internal team boundaries.
+- Add the Zensical features you usually enable first.
+- Note which features are situational and why.
+- Prefer Zensical-native features and conventions when they cover the need cleanly.
+- Expect general backward compatibility with MkDocs patterns and configuration unless there is a documented reason not to.
 
-1. Split content into at least four buckets:
+### Preferred docs structure
-   - Learn (concepts and mental models)
-   - Do (task/how-to guides)
-   - Reference (API, config, CLI, schemas)
-   - Troubleshoot (symptoms, diagnostics, fixes)
-2. For each bucket, define success criteria and expected time-to-answer.
-3. Add clear page entry criteria (what belongs here, what does not).
 
-Completion check: every planned page maps to one primary user intent.
+- Record whether this repo prefers explicit nav, index pages, task-first docs, or another pattern.
 
-### Step 2: Design Progressive Discoverability
+### Preferred API docs approach
 
-Make docs progressively discoverable from overview to detail.
+- Record whether to use mkdocstrings, how much API surface to publish, and how to link task docs back to reference pages.
 
-1. Start each section with an index/overview page that answers:
+## Source-First Rule
-   - who this section is for
-   - what problems it solves
-   - where to go next
-2. Keep page openings front-loaded:
-   - first paragraph states purpose and outcome
-   - first heading after intro is usually prerequisites or quickstart path
-3. Add consistent wayfinding on every page:
-   - links to prerequisite concepts
-   - links to next steps
-   - links to relevant reference sections
-4. Prefer short sections, descriptive headings, and stable anchor names.
 
-Completion check: users can navigate from high-level overview to exact procedure in 3 clicks or fewer.
+When making a recommendation, link back to the relevant reference file first, and when possible to the upstream docs linked from that reference.
 
-### Step 3: Author High-Trust Content
+## Compatibility Rule
 
-Use writing patterns that reduce ambiguity and failure.
+Prefer the Zensical-native way of doing something when it exists and is well-supported.
-
+Assume MkDocs compatibility is still expected for most configuration and authoring patterns, and call out any case where a Zensical recommendation intentionally diverges from standard MkDocs behavior.
-1. Use imperative, task-oriented titles (for example: "Configure SSO with OIDC").
-2. State assumptions and prerequisites before commands.
-3. Provide copy-paste-safe examples and expected outputs.
-4. Include rollback or recovery steps for risky operations.
-5. Separate normative guidance (must/should) from optional patterns.
-6. Call out version-specific behavior explicitly.
-
-Completion check: each task page includes prerequisites, steps, expected result, and failure recovery.
-
-### Step 4: Apply Zensical Features Intentionally
-
-Load [./references/zensical-features.md](./references/zensical-features.md) and choose features based on content needs.
-Load [./references/code-heavy-docs-and-mkdocstrings.md](./references/code-heavy-docs-and-mkdocstrings.md) when the docs include Python APIs or other generated references.
-
-Decision matrix:
-
-- If docs are deep and section-heavy: enable `navigation.indexes`, `navigation.path`, and `navigation.sections`.
-- If speed and perceived responsiveness matter: enable `navigation.instant` and `navigation.instant.prefetch`.
-- If code-heavy content exists: enable `content.code.copy`, `content.code.select`, and `content.code.annotate`.
-- If code-heavy content includes API references: standardize on mkdocstrings for generated API docs and keep hand-written task guides alongside generated reference pages.
-- If users rely on search often: enable `search.highlight` and improve heading quality for better snippets.
-- If many pages share tab labels (for example Python/JS): enable `content.tabs.link`.
-
-Completion check: each enabled feature has a documented rationale tied to a user outcome.
-
-### Step 5: Standardize Navigation and Search Quality
-
-1. Use explicit nav for critical docs journeys and release-stable ordering.
-2. Keep page titles and H1 aligned with search intent language users actually type.
-3. Avoid duplicate page titles across sections.
-4. Use concise first paragraphs because search snippets often rely on early content.
-5. Add cross-links between concept, task, and reference pages.
-
-Completion check: top support queries return a correct page within first search results.
-
-### Step 6: Publish and Validate
-
-1. Build the site: `uv run zensical build`
-2. Validate links, code blocks, and navigation paths.
-3. Review on desktop and mobile for scanability and heading rhythm.
-4. Check that key journeys (new user setup, common task, troubleshooting flow) are uninterrupted.
-
-Completion check: no broken links, no dead-end pages, and all critical journeys are complete.
-
-## Completion Checks
-
-- Page taxonomy is intent-based: Learn, Do, Reference, Troubleshoot.
-- Every major section has an overview page and next-step links.
-- Task docs contain prerequisites, steps, expected results, and recovery guidance.
-- Enabled Zensical features are justified and aligned to user needs.
-- Code-heavy documentation strategy is explicit, including when and how mkdocstrings is used.
-- Navigation and search behavior are verified with real user tasks.
-- Site builds cleanly with `uv run zensical build`.
 
 ## Output Contract
 
-Return:
+Return only what is useful for the current docs task:
 
-1. Proposed docs architecture and navigation map.
+1. Which reference to read next.
-2. Zensical feature configuration recommendations with rationale.
+2. The smallest recommended docs or config change.
-3. A prioritized writing backlog (must-have, should-have, nice-to-have).
+3. Any repo-specific preference this suggests should be added back into this skill.
-4. A quality-gate checklist for pre-publish review.
-
-## Guardrails
-
-- Do not produce architecture-only docs without concrete task pages.
-- Do not bury prerequisites or version constraints below the fold.
-- Do not rely only on search; preserve strong navigational paths.
-- Do not enable features without documenting the expected user benefit.

docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md

@@ -28,13 +28,17 @@ Primary docs:
 ## Minimal Integration Pattern
 
 1. Add mkdocstrings and a Python handler package to project dependencies.
-2. Configure docs toolchain to enable mkdocstrings plugin/extension.
+2. Configure the Zensical docs toolchain to enable mkdocstrings within the site build.
 3. Create one API index page per package/domain.
 4. Expand coverage gradually from high-value modules first.
 
 General reference examples:
-- Plugin docs: https://www.mkdocs.org/user-guide/plugins/
+- Zensical docs home and setup entry point: https://zensical.org/docs/
-- Material + code/reference setup concepts: https://squidfunk.github.io/mkdocs-material/reference/
+- Zensical code blocks and authoring patterns: https://zensical.org/docs/authoring/code-blocks/
+- Zensical customization overview: https://zensical.org/docs/customization/
+
+Compatibility note:
+- Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.
 
 ## Authoring Guidance for Docstrings
 

docs/skills/zensical-docs/references/index.md

@@ -35,8 +35,8 @@ Use this index to load only the source references needed for the current task.
 ## Related Tooling References
 
 - Markdown guide: https://www.markdownguide.org/
-- MkDocs configuration reference: https://www.mkdocs.org/user-guide/configuration/
+- Zensical setup and configuration entry point: https://zensical.org/docs/
-- Material for MkDocs setup reference: https://squidfunk.github.io/mkdocs-material/setup/
+- Zensical customization reference: https://zensical.org/docs/customization/
 - mkdocstrings: https://mkdocstrings.github.io/
 
 ## Skill-Specific Deep Dives

src/personal_mcp/mcp.py

@@ -1,6 +1,7 @@
 from fastmcp import FastMCP
 
 from personal_mcp.catalog.server import catalog_server
+from personal_mcp.skills.copilot_customization.server import copilot_customization_server
 from personal_mcp.skills.fastapi_async_sqlalchemy_modernization.server import (
     fastapi_async_sqlalchemy_modernization_server,
 )
@@ -19,6 +20,7 @@ from personal_mcp.skills.zensical_docs.server import zensical_docs_server
 mcp = FastMCP("personal-mcp")
 
 mcp.mount(catalog_server, namespace="catalog")
+mcp.mount(copilot_customization_server, namespace="copilot_customization")
 mcp.mount(
     fastapi_async_sqlalchemy_modernization_server,
     namespace="fastapi_async_sqlalchemy_modernization",

src/personal_mcp/skills/copilot_customization/metadata.yaml

@@ -0,0 +1,21 @@
+id: copilot-customization
+name: Copilot Customization
+version: 1.0.0
+description: Plan, create, review, and debug GitHub Copilot and VS Code agent customizations for this repository.
+tags:
+  - copilot
+  - vscode
+  - customization
+  - instructions
+  - prompts
+  - agent-skills
+  - custom-agents
+  - hooks
+  - mcp
+  - personal-mcp
+  - skills
+capabilities:
+  - resource://skills/copilot-customization/document
+depends_on:
+  - new-skill
+  - zensical-docs

src/personal_mcp/skills/copilot_customization/server.py

@@ -0,0 +1,14 @@
+from fastmcp import FastMCP
+
+from personal_mcp.skills.document_loader import load_skill_document
+
+copilot_customization_server = FastMCP("copilot-customization")
+
+
+@copilot_customization_server.resource("resource://skills/copilot-customization/document")
+def skill_document() -> dict[str, str]:
+    """Return the canonical Markdown document for this skill."""
+    return load_skill_document(
+        skill_id="copilot-customization",
+        skill_slug="copilot-customization",
+    )

src/personal_mcp/skills/new_skill/metadata.yaml

@@ -3,6 +3,7 @@ name: New Skill Bootstrap
 version: 1.0.0
 description: Provide the bootstrap checklist and templates for creating new MCP skills.
 tags:
+  - fastmcp
   - bootstrap
   - scaffolding
   - skills

src/personal_mcp/skills/zensical_docs/metadata.yaml

@@ -4,6 +4,9 @@ version: 1.0.0
 description: Plan, write, and improve high-quality documentation with Zensical.
 tags:
   - zensical
+  - mkdocs
+  - mkdocs-material
+  - mkdocstrings
   - docs
   - documentation
   - information-architecture