From 7a9e4044f0c8bb9c24a447598366c69a5391d587 Mon Sep 17 00:00:00 2001
From: John Lancaster <32917998+jsl12@users.noreply.github.com>
Date: Fri, 19 Jun 2026 08:38:10 -0500
Subject: [PATCH] explanations

---
 docs/architecture.md | 2 ++
 docs/index.md        | 6 ++++++
 2 files changed, 8 insertions(+)

diff --git a/docs/architecture.md b/docs/architecture.md
index ef8a907..93f19f6 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -8,6 +8,8 @@ icon: lucide/library
 
 The platform is implemented as a resource-first MCP system with an integrated static documentation surface. The same methodology content powers both MCP resources and the published docs site.
 
+An MCP server is a runtime that exposes machine-readable resources and tools through stable interfaces so AI clients can discover and consume context consistently. Here, the server's role is intentionally narrow: publish canonical methodology documents as resources, keep discovery predictable through a catalog layer, and serve the same source material as pre-built static documentation.
+
 The system is complete in three layers:
 
 1. Canonical methodology is maintained in Markdown skill documents.
diff --git a/docs/index.md b/docs/index.md
index 361254b..bc4967a 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,6 +4,12 @@ icon: lucide/rocket
 
 # Get started
 
+## What this MCP server is
+
+An MCP server is a service that gives AI clients a stable way to discover and read capabilities through defined contracts. In practice, it exposes named resources and optional tools so clients can request context reliably instead of depending on ad-hoc prompts.
+
+This server is designed to publish software methodology as canonical Markdown resources, with a small catalog for discovery, and to serve the same content as a static docs site. The intent is one source of truth for both humans and agents.
+
 ## Quick start
 
 Install dependencies first: