docs

docs/authoring.md

@@ -89,7 +89,78 @@ Source examples:
 - [FastMCP docs](https://gofastmcp.com/getting-started/welcome)
 - [Zensical docs](https://zensical.org/docs/)
 
-## Navigation And Frontmatter
+## Authoring for GitHub Copilot
+
+For resource selection or tool-based matching to work well, each skill should have:
+
+1. precise `description`
+2. focused `tags`
+3. explicit `capabilities`
+4. stable `id` and slug naming
+
+Weak metadata reduces Copilot match quality and increases wrong context injection.
+
+### Copilot Instruction Authoring Pattern
+
+If you want Copilot to use `personal-mcp` skill content more reliably, instruction files should describe three things clearly:
+
+1. when MCP-backed skill guidance is relevant
+2. which retrieval path Copilot should prefer first
+3. how much skill context it should load before answering
+
+Instructions strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. Keep wording explicit about preferred path and fallback path.
+
+Repository policy:
+
+1. start from catalog discovery
+2. prefer MCP resources when the current chat surface exposes resource attachment
+3. fall back to catalog tools when resource attachment is unavailable
+4. keep loaded skill context bounded
+
+Suggested instruction text:
+
+```md
+When a task may match a documented implementation pattern from `personal-mcp`:
+
+1. Start with catalog-first discovery.
+2. Prefer MCP resources when the chat surface exposes resource attachment.
+3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
+4. Load only the most relevant skill document, or at most 2 skill documents.
+5. Reconcile loaded skill guidance with the actual repository code before making changes.
+
+Preferred resource order:
+
+1. `resource://catalog/skills_index`
+2. `resource://catalog/skills/{skill_id}`
+3. `resource://skills/<skill-id>/document`
+4. `resource://skills/<skill-id>/references/<ref-id>` when needed
+
+Preferred tool fallback order:
+
+1. `list_resources`
+2. `read_resource`
+3. `search_patterns`
+4. `get_pattern_by_id`
+5. `get_skill_document_by_id`
+
+Compatibility aliases for clients that use `catalog_*` naming are also available:
+
+1. `catalog_search_patterns`
+2. `catalog_get_pattern_by_id`
+3. `catalog_get_skill_document_by_id`
+4. `catalog_search_prompts`
+5. `catalog_get_prompt_by_id`
+
+Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.
+
+If confidence is low after discovery, ask one clarifying question before loading more context.
+```
+
+This is guidance, not a guarantee. It defines a reliable policy while preserving the resource-first architecture.
+
+Thin shim path binding guidance for MCP consumers is covered in [Skill Usage Mechanics](./usage.md).
+
+## Zensical Details
 
 When adding or restructuring pages:
 
@@ -116,6 +187,8 @@ uv run ty check
 uv run pytest
 ```
 
+Address any errors or warnings that result.
+
 If a change only affects docs content, `uv run zensical build` is still required.
 
 ## Quick Authoring Checklist

docs/usage.md

@@ -138,16 +138,9 @@ flowchart TD
     H --> I
 ```
 
-## Authoring Requirements For Reliable Matching
+## Authoring Requirements
 
-For resource selection or tool-based matching to work well, each skill should have:
+Authoring rules for metadata quality and instruction patterns are maintained in [Authoring Guide](./authoring.md).
-
-1. precise `description`
-2. focused `tags`
-3. explicit `capabilities`
-4. stable `id` and slug naming
-
-Weak metadata reduces Copilot match quality and increases wrong context injection.
 
 ## Practical Guidelines
 
@@ -175,64 +168,6 @@ Behavior:
 2. `bm25` uses ranked natural-language matching.
 3. `list_resources` and `read_resource` stay visible so resource-backed fallback remains primary.
 
-## Copilot Instruction Pattern
-
-If you want Copilot to use `personal-mcp` skill content more reliably, the instruction file should describe three things clearly:
-
-1. when MCP-backed skill guidance is relevant
-2. which retrieval path Copilot should prefer first
-3. how much skill context it should load before answering
-
-That matters because instructions can strongly steer discovery behavior, but they do not force VS Code to auto-attach MCP resources. A good instruction tells Copilot to prefer the canonical MCP content path while remaining accurate about the fallback path.
-
-In this repository, the right policy is:
-
-1. start from catalog discovery
-2. prefer MCP resources when the current chat surface exposes resource attachment
-3. fall back to catalog tools when resource attachment is unavailable
-4. keep loaded skill context bounded
-
-Suggested instruction text:
-
-```md
-When a task may match a documented implementation pattern from `personal-mcp`:
-
-1. Start with catalog-first discovery.
-2. Prefer MCP resources when the chat surface exposes resource attachment.
-3. If MCP resource attachment is unavailable, use `list_resources`/`read_resource` first, then thin catalog tools if needed.
-4. Load only the most relevant skill document, or at most 2 skill documents.
-5. Reconcile loaded skill guidance with the actual repository code before making changes.
-
-Preferred resource order:
-
-1. `resource://catalog/skills_index`
-2. `resource://catalog/skills/{skill_id}`
-3. `resource://skills/<skill-id>/document`
-4. `resource://skills/<skill-id>/references/<ref-id>` when needed
-
-Preferred tool fallback order:
-
-1. `list_resources`
-2. `read_resource`
-3. `search_patterns`
-4. `get_pattern_by_id`
-5. `get_skill_document_by_id`
-
-Compatibility aliases for clients that use `catalog_*` naming are also available:
-
-1. `catalog_search_patterns`
-2. `catalog_get_pattern_by_id`
-3. `catalog_get_skill_document_by_id`
-4. `catalog_search_prompts`
-5. `catalog_get_prompt_by_id`
-
-Use canonical names first; aliases exist only to preserve interoperability when a client emits non-canonical names.
-
-If confidence is low after discovery, ask one clarifying question before loading more context.
-```
-
-This is intentionally guidance, not a guarantee. It gives Copilot a strong policy for when to use resources and when to fall back to discovery tools, while preserving the resource-first architecture.
-
 ## Failure Modes and Recovery
 
 Common failure modes:
@@ -258,22 +193,13 @@ Use this checklist when configuring GitHub Copilot in VS Code against `personal-
 2. verify catalog resources are readable
 3. verify at least one `resource://skills/<id>/document` can be fetched
 4. add one deterministic `/` command for fallback
-5. add Copilot instruction: prefer catalog-first discovery, then targeted skill fetch
+5. confirm your workspace instruction policy exists (see [Authoring Guide](./authoring.md))
 6. verify context size remains bounded
 7. validate behavior in Ask/Edit/Agent-style workflows with at least one task each
 
-## Local Ruff Workflow
+## Runtime Discovery Workflow
 
-Use [Ruff](https://docs.astral.sh/ruff/) locally through `uv` so lint and format checks are consistent for contributors.
+Use this runtime sequence in chat sessions:
-
-1. Lint check: `uv run ruff check .`
-2. Apply safe lint fixes: `uv run ruff check . --fix`
-3. Format files: `uv run ruff format .`
-4. Format check (CI-style): `uv run ruff format --check .`
-
-Rule-family baseline for this repository is `E`, `F`, `I`, and `UP`, configured in [pyproject.toml](../pyproject.toml).
-
-Suggested instruction policy text:
 
 1. Start with catalog-first discovery.
 2. Prefer MCP resources when the chat surface exposes resource attachment.
@@ -281,6 +207,66 @@ Suggested instruction policy text:
 4. Prefer `list_resources`/`read_resource` first when operating in tool-only clients.
 5. If confidence is low, ask one clarifying question before loading more.
 
+## Thin Shim Path Binding Pattern
+
+For repositories that consume this MCP server, thin shims are a usage pattern for binding path scopes to the right MCP resources. The "thin shims" are just lightweight, repo-specific instructions files that tell Copilot to use certain MCP resources when editing files that match a pattern. That helps with ensuring Copilot uses the intended resources without too much specific goading in the prompt.
+
+Use thin shims in Copilot instruction files to bind file-path scopes to:
+
+1. the most relevant docs page for human-readable conventions
+2. the matching MCP resource URI for machine retrieval
+
+Keep each shim short: trigger, primary resource, minimal execution pattern, and one fallback rule.
+
+Recommended binding pattern:
+
+1. Put shims in `.github/instructions/*.instructions.md`.
+2. Scope each shim with `applyTo` so it activates only where needed.
+3. Point to one primary `resource://skills/<skill-id>/document` URI.
+4. Link one repository docs page as the human-facing companion.
+5. Expand to references only when the task needs deeper detail.
+
+Current repository examples:
+
+| applyTo scope | Primary docs page | Primary MCP resource |
+| --- | --- | --- |
+| `**/*.md` | [docs/authoring.md](./authoring.md) | `resource://skills/zensical-docs/document` |
+| `tests/**` | [docs/testing.md](./testing.md) | `resource://skills/pytesting/document` |
+| `.vscode/**` | [docs/skills/vscode-configuration/SKILL.md](./skills/vscode-configuration/SKILL.md) | `resource://skills/vscode-configuration/document` |
+
+Minimal shim shape:
+
+```md
+---
+name: <short scope name>
+description: Route <path scope> edits to the Personal MCP <skill-id> resource.
+applyTo: '<glob>'
+---
+
+When editing files matching <glob>, use `resource://skills/<skill-id>/document` as the primary guidance source.
+
+Execution pattern:
+
+1. Load the primary skill document first.
+2. Apply only sections relevant to the file being edited.
+3. Keep edits minimal and aligned with repository conventions.
+4. If confidence is low, ask one clarifying question before editing.
+
+Companion docs page: [docs/<page>.md](./<page>.md)
+```
+
+When to use thin shims:
+
+1. Repositories that want thin local policy while keeping canonical guidance in MCP resources.
+2. Stable, repeated workflows with clear path ownership.
+3. Cases where teams need predictable retrieval behavior.
+
+When not to use thin shims:
+
+1. Broad, ambiguous tasks with unclear ownership boundaries.
+2. Cases where one shim would need many exceptions.
+3. Situations better handled by catalog-first discovery at runtime.
+
 ## Summary
 
 The intended model is: