doc updates

docs/architecture.md

@@ -75,9 +75,11 @@ The catalog is the canonical discovery layer and publishes normalized records fo
 Typical catalog resources:
 
 1. resource://catalog/skills_index
-2. resource://catalog/skills/{skill_id}
+2. resource://catalog/skills_index{?q,tag,capability,cursor,limit}
-3. resource://catalog/prompts_index
+3. resource://catalog/skills/{skill_id}
-4. resource://catalog/prompts/{prompt_id}
+4. resource://catalog/prompts_index
+5. resource://catalog/prompts_index{?q,tag,cursor,limit}
+6. resource://catalog/prompts/{prompt_id}
 
 Only canonical catalog resources are part of the runtime contract in this phase.
 
@@ -151,11 +153,13 @@ For the full URI semantics, parameter validation rules, and compatibility policy
 1. resource://skills/<skill_id>/document
 2. resource://skills/<skill_id>/references/<ref_id>
 3. resource://catalog/skills_index
-4. resource://catalog/skills/{skill_id}
+4. resource://catalog/skills_index{?q,tag,capability,cursor,limit}
-5. resource://docs/{path*}
+5. resource://catalog/skills/{skill_id}
-6. resource://catalog/prompts_index
+6. resource://docs/{path*}
-7. resource://catalog/prompts/{prompt_id}
+7. resource://catalog/prompts_index
-8. resource://prompts/{prompt_id}/document
+8. resource://catalog/prompts_index{?q,tag,cursor,limit}
+9. resource://catalog/prompts/{prompt_id}
+10. resource://prompts/{prompt_id}/document
 
 Validation rules:
 

docs/contracts/uris.md

@@ -6,9 +6,11 @@ icon: lucide/link
 
 This page defines the canonical resource URI contract, template parameter rules, and compatibility policy.
 
+Conventions in this document follow [MCP resource semantics](https://modelcontextprotocol.io/docs/learn/server-concepts#resources), [URI generic syntax (RFC3986)](https://www.rfc-editor.org/rfc/rfc3986), and [URI templates (RFC6570)](https://www.rfc-editor.org/rfc/rfc6570).
+
 ## Canonical URI Surface
 
-The public, preferred URIs are:
+The public, preferred direct resource URIs are:
 
 1. `resource://catalog/skills_index`
 2. `resource://catalog/skills/{skill_id}`
@@ -19,11 +21,23 @@ The public, preferred URIs are:
 7. `resource://catalog/prompts/{prompt_id}`
 8. `resource://prompts/{prompt_id}/document`
 
+The public, preferred resource template URIs are:
+
+1. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
+2. `resource://catalog/prompts_index{?q,tag,cursor,limit}`
+
 Contract intent:
 
 1. Catalog URIs are discovery surfaces.
 2. Skill URIs are the primary per-skill guidance surfaces.
-3. The docs wildcard URI is a direct authored-markdown access surface under `docs/`.
+3. Catalog query templates are additive discovery helpers for filtering and pagination.
+4. The docs wildcard URI is a direct authored-markdown access surface under `docs/`.
+
+Best-practice alignment:
+
+1. Resource identifiers are stable and noun-oriented.
+2. Dynamic lookup variants are represented as RFC6570 templates.
+3. Resources remain read-oriented and are described with explicit MIME types.
 
 ## URI Semantics
 
@@ -52,7 +66,7 @@ Contract intent:
 ### `resource://docs/{path*}`
 
 1. Returns authored markdown at a normalized relative path under `docs/`.
-2. Supports nested paths via RFC6570 wildcard expansion.
+2. Supports nested paths via [RFC6570 wildcard expansion](https://www.rfc-editor.org/rfc/rfc6570).
 3. Typical examples include `index.md`, `usage.md`, `skills/<skill-id>/SKILL.md`, and `skills/<skill-id>/references/<file>.md`.
 
 ### `resource://catalog/prompts_index`
@@ -61,6 +75,18 @@ Contract intent:
 2. Contains one entry per `prompt_id`.
 3. Includes `id`, `name`, `description`, `tags`, `version`, and canonical document URI.
 
+### `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
+
+1. Returns the same record family as `resource://catalog/skills_index` with optional filtering and pagination.
+2. Query parameters are optional and composable.
+3. Unknown query keys are ignored or rejected deterministically by server policy.
+
+### `resource://catalog/prompts_index{?q,tag,cursor,limit}`
+
+1. Returns the same record family as `resource://catalog/prompts_index` with optional filtering and pagination.
+2. Query parameters are optional and composable.
+3. Unknown query keys are ignored or rejected deterministically by server policy.
+
 ### `resource://catalog/prompts/{prompt_id}`
 
 1. Returns one normalized record for `prompt_id`.
@@ -86,17 +112,27 @@ Contract intent:
 
 ### `path*`
 
-1. Relative POSIX path only.
+1. Relative POSIX path only, expressed as URI path segments under [RFC3986 path syntax](https://www.rfc-editor.org/rfc/rfc3986#section-3.3).
 2. No leading slash.
 3. No `..` traversal segments.
 4. Resolves only inside `docs/`.
 5. Markdown-only in the end state, meaning `.md` files.
+6. Any reserved URI characters in path segments must be [percent-encoded](https://www.rfc-editor.org/rfc/rfc3986#section-2.1).
 
 ### `prompt_id`
 
 1. Lowercase kebab-case.
 2. Must be unique across prompt ids and must not collide with skill ids.
 
+## URI Hygiene Rules
+
+1. Use lowercase, human-readable path segments for stable discoverability.
+2. Keep identifiers immutable once public whenever practical.
+3. Keep template variables semantic (`skill_id`, `prompt_id`, `ref_id`, `path*`) and avoid overloading one variable for unrelated meanings.
+4. Do not include secrets, tokens, or user-identifying data in URI paths or query strings.
+5. Prefer additive query parameters for discovery over introducing parallel URI families, matching [MCP resource-template discovery patterns](https://modelcontextprotocol.io/docs/learn/server-concepts#resources).
+6. Return clear not-found semantics for unknown ids and invalid template resolution.
+
 ## URI Versioning Policy
 
 Default rule:
@@ -141,3 +177,10 @@ This contract does not define:
 1. Implementation-specific transform wiring details, such as `VersionFilter`, mounts, or provider composition.
 2. Migration script mechanics for auto-generating aliases.
 3. Authorization policy design for URI-level access control.
+
+## Sources
+
+1. [MCP Server Concepts: Resources](https://modelcontextprotocol.io/docs/learn/server-concepts#resources)
+2. [MCP Architecture Overview](https://modelcontextprotocol.io/docs/learn/architecture)
+3. [MCP Specification Repository](https://github.com/modelcontextprotocol/spec)
+4. [RFC6570 URI Template](https://www.rfc-editor.org/rfc/rfc6570)

docs/mcp_layout.md

@@ -127,7 +127,11 @@ Example mapping model:
 Catalog discovery resources are:
 
 1. resource://catalog/skills_index
-2. resource://catalog/skills/{skill_id}
+2. resource://catalog/skills_index{?q,tag,capability,cursor,limit}
+3. resource://catalog/skills/{skill_id}
+4. resource://catalog/prompts_index
+5. resource://catalog/prompts_index{?q,tag,cursor,limit}
+6. resource://catalog/prompts/{prompt_id}
 
 Registry-backed registration details:
 

docs/usage.md

@@ -31,9 +31,11 @@ Prompt guidance is now exposed through both prompt resources and MCP prompt obje
 `personal-mcp` registers resources from the validated docs registry and exposes catalog discovery resources:
 
 1. `resource://catalog/skills_index`
-2. `resource://catalog/skills/{skill_id}`
+2. `resource://catalog/skills_index{?q,tag,capability,cursor,limit}`
-3. `resource://catalog/prompts_index`
+3. `resource://catalog/skills/{skill_id}`
-4. `resource://catalog/prompts/{prompt_id}`
+4. `resource://catalog/prompts_index`
+5. `resource://catalog/prompts_index{?q,tag,cursor,limit}`
+6. `resource://catalog/prompts/{prompt_id}`
 
 Each skill publishes a canonical Markdown document resource: