docs: add technical diagrams and improve documentation (#10)

precision

Author: dgellow

CLAUDE.md

@@ -165,6 +165,22 @@ cmd/mcp-front/   # Main application entry point
 7. **Ask questions when uncertain** - Don't assume and proceed
 8. **No hacks or shortcuts** - Only clean, maintainable solutions
 
+### Documentation Standards
+
+**Write precise, technical language:**
+- ❌ "When Claude connects to MCP Front, it includes a bearer token in the Authorization header"
+- ✅ "An MCP client can connect to MCP Front with a bearer token"
+- ❌ "Users log in with their Google account"  
+- ✅ "Claude redirects users to Google for authentication"
+- ❌ "Claude establishes SSE connection"
+- ✅ "Claude connects via SSE"
+
+**Key clarifications:**
+- **Claude.ai only supports OAuth** - Bearer tokens are for development/alternative clients only
+- **Avoid redundant implementation details** - "bearer token" implies Authorization header
+- **Use precise actors** - "MCP client" not "user" in technical contexts
+- **Be specific about auth flow** - Claude handles the OAuth redirect, MCP Front validates domains
+
 ### Refactoring Guidelines
 
 When refactoring for better design:

README.md

@@ -1,4 +1,4 @@
-# mcp-front
+# mcp-front <img src="docs-site/src/assets/logo.svg" alt="MCP Front" width="32" height="32" style="vertical-align: middle;">
 
 ![Docker image with tag latest](https://img.shields.io/docker/image-size/dgellow/mcp-front/latest?style=flat&logo=docker&label=latest)
 ![Docker image with tag docker-client-latest](https://img.shields.io/docker/image-size/dgellow/mcp-front/docker-client-latest?style=flat&logo=docker&label=docker-client-latest)

docs-site/astro.config.mjs

@@ -22,11 +22,10 @@ export default defineConfig({
 				{ label: 'Introduction', slug: 'index' },
 				{ label: 'Quickstart', slug: 'quickstart' },
 				{
-					label: 'Examples',
+					label: 'Guides',
 					items: [
-						{ label: 'Bearer Token', slug: 'examples/bearer-token' },
 						{ label: 'OAuth with Google', slug: 'examples/oauth-google' },
-						{ label: 'Deploy to Cloud Run', slug: 'examples/cloud-run' },
+						{ label: 'Bearer Token', slug: 'examples/bearer-token' },
 					],
 				},
 				{ label: 'Configuration', slug: 'configuration' },