diff --git a/docs/architecture.md b/docs/architecture.md index 5d877c4..ef8a907 100644 --- a/docs/architecture.md +++ b/docs/architecture.md @@ -21,7 +21,7 @@ This architecture keeps authored content human-friendly while preserving machine The architecture is designed to satisfy three long-term requirements: 1. Methodology must be editable as markdown by humans. -2. Agents must consume stable, discoverable resource contracts. +2. Agents must consume stable, discoverable resource contracts, with a minimal read-only catalog tool fallback for constrained clients. 3. Public documentation must be pre-built static output served from the application runtime without a separate docs service. ## System Model @@ -36,7 +36,7 @@ The document resource returns canonical Markdown, while clients can perform any ### Catalog Module -The catalog is the canonical discovery layer and publishes normalized records for all modules. +The catalog is the canonical discovery layer and publishes normalized records for all modules. It may also expose a minimal set of read-only discovery tools that resolve back to the same canonical markdown content when a client chat surface does not expose MCP resource attachment. Typical catalog resources: @@ -128,7 +128,7 @@ Markdown remains easy to review, while contracts remain stable for clients. ### Client Independence -Clients can use Ask, Edit, or Agent modes without requiring server-owned prompt orchestration. +Clients can use Ask, Edit, or Agent modes without requiring server-owned prompt orchestration. However, MCP affordances are still chat-surface-dependent: some clients or sessions expose resource attachment directly, while others make tool invocation the more reliable retrieval path. ## Authoring and Publishing Lifecycle @@ -148,9 +148,13 @@ In-scope: Out-of-scope: 1. Prompt-first orchestration as the primary interface -2. Large tool inventories duplicating static guidance +2. Large tool inventories duplicating static guidance across skill modules 3. Separate dynamic docs service at runtime +Allowed exception: + +1. A small catalog-level tool layer is acceptable when it improves client interoperability without creating a second source of truth for skill content. + ## Example Content Inputs Existing markdown reference sets are valid examples of authored source material for this architecture: diff --git a/docs/mcp_layout.md b/docs/mcp_layout.md index 7290aba..dffbffb 100644 --- a/docs/mcp_layout.md +++ b/docs/mcp_layout.md @@ -108,6 +108,8 @@ Example mapping model: Catalog resources provide discovery metadata and stable identifiers. +When clients cannot attach MCP resources directly, catalog-level tools may retrieve the same underlying skill documents indirectly. This does not create a second content source; it is only an alternate access path to the same markdown-backed contract. + ## Why This Pattern ### Operational Simplicity