usage notes

docs/usage.md

@@ -90,6 +90,94 @@ For prompt content, there is a third option when the client supports MCP prompt
 
 Instruction quality and metadata quality still matter, because they influence whether Copilot recognizes that the MCP server is relevant and chooses the tool path well.
 
+## Invocation Mechanics Deep Dive
+
+This section expands on how invocation works at runtime across chat entry points.
+
+### Invocation Surfaces
+
+A user request can arrive through one of these surfaces:
+
+1. plain chat request in Ask/Edit/Agent mode
+2. slash command invocation of a prompt or skill
+3. chat request with manually attached MCP resources
+
+Each surface changes how much discovery Copilot must do before applying guidance.
+
+### Resolution Order
+
+When multiple retrieval paths are possible, use this priority order:
+
+1. attached MCP resources already in context
+2. explicit slash-command workflow steps
+3. catalog-first discovery via MCP resources
+4. tool fallback (`list_resources` then `read_resource`, then thin catalog parity tools)
+
+This ordering keeps behavior predictable while minimizing unnecessary context expansion.
+
+### Prompt Invocation Pipeline
+
+For prompt-oriented flows, treat invocation as this sequence:
+
+1. parse prompt frontmatter and argument hints
+2. validate required inputs and ask one clarifying question if blocked
+3. run bounded discovery against prompt or skill catalogs
+4. fetch only selected document resources
+5. apply instructions to produce edits, recommendations, or commands
+6. report what was loaded and why
+
+Prompt objects and prompt document resources are additive mechanisms. The authored Markdown prompt document remains the canonical contract.
+
+### Argument Syntax Nuance
+
+Invocation strings such as target_modules=src/personal_mcp/registry/ingest/skill.py, mode=plan-only are a structured authoring convention, not a guaranteed client-level grammar.
+
+In practice:
+
+1. Prompt metadata defines expected argument names and intent.
+2. Prompt body instructions define how those inputs should be interpreted.
+3. Copilot may receive equivalent intent in freeform phrasing and still resolve it correctly.
+
+Implication for authors:
+
+1. Treat key=value examples as clarity aids for users.
+2. Do not assume strict parser enforcement unless your prompt explicitly validates and rejects malformed input.
+3. Include accepted invocation examples and one fallback freeform example so behavior is predictable for both humans and the model.
+
+This distinction is important because argument hints improve discoverability, while robust prompt instructions determine actual runtime reliability.
+
+### Skill Invocation Pipeline
+
+For guided skill loading, use this sequence:
+
+1. start from `resource://catalog/skills_index` or scoped index query
+2. inspect one or two top candidates for intent and capability fit
+3. fetch `resource://skills/<skill-id>/document`
+4. load references only when the task needs deeper detail
+5. apply only relevant sections and keep context bounded
+
+This avoids the common failure mode where many skill documents are loaded up front.
+
+### Determinism vs Flexibility
+
+Use this decision rule:
+
+1. choose slash-command invocation when repeatability and step order are critical
+2. choose guided loading when requests vary and speed matters more than strict orchestration
+3. escalate from guided loading to slash-command flow when confidence is low or conflicting skills appear
+
+### Invocation Trace (What to Log in Results)
+
+For transparent operation, include a concise invocation trace in task outputs:
+
+1. entry surface used (plain chat, slash command, or attached resource)
+2. discovery source used (catalog resource or tool path)
+3. resources fetched (ids only)
+4. clarifying questions asked (if any)
+5. reason for fallback or escalation (if used)
+
+This makes behavior auditable and easier to tune over time.
+
 ## Operating Pattern
 
 Use both modes intentionally in Copilot Chat.