fix(docs): sync MCP Guard content from authoritative source

docs/mcp-guard/getting-started/installation.md

@@ -1,42 +1,75 @@
----
-title: Installation
-description: Install CapiscIO MCP Guard for tool-level security on MCP servers.
----
+<!-- Synced from capiscio-mcp-python/docs/ — do not edit locally -->
 
 # Installation
 
-MCP Guard provides trust badges and identity verification for [Model Context Protocol](https://modelcontextprotocol.io) tool calls.
+## PyPI Installation
+
+```bash
+# Standalone (no MCP SDK dependency)
+pip install capiscio-mcp
+
+# With MCP SDK integration
+pip install capiscio-mcp[mcp]
+
+# With PoP signing/verification (requires cryptography)
+pip install capiscio-mcp[crypto]
+
+# Full installation
+pip install capiscio-mcp[mcp,crypto]
+```
+
+## Using uv
+
+```bash
+uv add capiscio-mcp
+uv add capiscio-mcp --extra mcp
+```
 
 ## Requirements
 
 - Python 3.10+
-- A CapiscIO account or self-hosted registry
+- capiscio-core (auto-downloaded on first use)
 
-## Install via pip
+## Core Connection Modes
+
+capiscio-mcp connects to capiscio-core for cryptographic operations:
+
+### Embedded Mode (Default)
+
+The SDK automatically downloads and manages the core binary:
 
 ```bash
 pip install capiscio-mcp
+# Just works! Binary downloaded on first use.
 ```
 
-For MCP SDK integration (FastMCP wrapper):
+The binary is cached at `~/.capiscio/bin/capiscio`.
 
-```bash
-pip install capiscio-mcp[mcp]
-```
+### External Mode
 
-## Verify Installation
+Connect to a separately managed core service:
 
 ```bash
-python -c "import capiscio_mcp; print(capiscio_mcp.__version__)"
+# Start core in another terminal
+capiscio mcp serve --listen localhost:50051
+
+# SDK connects to external core
+export CAPISCIO_CORE_ADDR="localhost:50051"
 ```
 
-## What's Included
+## Verify Installation
 
-| Package | Description |
-|---------|-------------|
-| `capiscio-mcp` | Core guard decorator and evidence logging |
-| `capiscio-mcp[mcp]` | FastMCP integration for automatic tool wrapping |
+```python
+from capiscio_mcp import MCP_VERSION, CORE_MIN_VERSION
+
+print(f"capiscio-mcp version: {MCP_VERSION}")
+print(f"Required core version: {CORE_MIN_VERSION}")
+```
 
-## Next Steps
+## Environment Variables
 
-- [Quickstart](quickstart.md) — protect your first MCP tool in 5 minutes
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `CAPISCIO_CORE_ADDR` | External core address | (embedded mode) |
+| `CAPISCIO_SERVER_ORIGIN` | Server origin for guard | (auto-detect) |
+| `CAPISCIO_LOG_LEVEL` | Logging verbosity | `info` |

docs/mcp-guard/getting-started/quickstart.md

@@ -1,52 +1,96 @@
----
-title: Quickstart
-description: Protect your first MCP tool with CapiscIO trust badges in 5 minutes.
----
+<!-- Synced from capiscio-mcp-python/docs/ — do not edit locally -->
 
 # Quickstart
 
-Protect your MCP tools with trust-level requirements using the `@guard` decorator.
+Get started with capiscio-mcp in under 5 minutes.
 
-## Server-Side: Protect a Tool
+## Server-Side: Protect Your Tools
+
+The `@guard` decorator protects MCP tools with trust-level requirements:
 
 ```python
 from capiscio_mcp import guard
 
 @guard(min_trust_level=2)
 async def read_database(query: str) -> list[dict]:
     """Only agents with Trust Level 2+ can execute this tool."""
-    # ... your tool logic
+    # Your database query logic here
+    return [{"id": 1, "name": "Example"}]
+```
+
+### With Configuration
+
+```python
+from capiscio_mcp import guard, GuardConfig
+
+config = GuardConfig(
+    min_trust_level=2,
+    trusted_issuers=["did:web:registry.capisc.io"],
+    allowed_tools=["read_*", "list_*"],
+    require_badge=True,  # Deny anonymous access
+)
+
+@guard(config=config)
+async def execute_query(sql: str) -> list[dict]:
+    """Execute a SQL query with full policy enforcement."""
+    pass
+```
+
+### Sync Version
+
+```python
+from capiscio_mcp import guard_sync
+
+@guard_sync(min_trust_level=2)
+def read_database_sync(query: str) -> list[dict]:
+    """Synchronous version for non-async code."""
     pass
 ```
 
-## Client-Side: Verify a Server
+## Client-Side: Verify Servers
+
+Before connecting to an MCP server, verify its identity:
 
 ```python
-from capiscio_mcp import verify_server
+from capiscio_mcp import verify_server, ServerState
 
-result = await verify_server("did:web:example.com:mcp:my-server")
-if result.verified:
-    print(f"Server trust level: {result.trust_level}")
+result = await verify_server(
+    server_did="did:web:mcp.example.com",
+    server_badge="eyJhbGc...",
+    transport_origin="https://mcp.example.com",
+)
+
+if result.state == ServerState.VERIFIED_PRINCIPAL:
+    print(f"✅ Trusted server at Level {result.trust_level}")
+elif result.state == ServerState.DECLARED_PRINCIPAL:
+    print("⚠️ Server identity declared but not verified")
+elif result.state == ServerState.UNVERIFIED_ORIGIN:
+    print("❌ Server did not disclose identity")
 ```
 
-## How It Works
+## Understanding Server States
 
-1. **Agent sends badge** — the calling agent presents its CapiscIO trust badge
-2. **Guard verifies** — `@guard` checks the badge signature, expiry, and trust level
-3. **Evidence logged** — every invocation is recorded with a cryptographic audit trail
-4. **Tool executes** — if verification passes, the tool runs normally
+| State | Meaning | Action |
+|-------|---------|--------|
+| `VERIFIED_PRINCIPAL` | Identity cryptographically verified | Safe to proceed |
+| `DECLARED_PRINCIPAL` | Identity declared but verification failed | Proceed with caution |
+| `UNVERIFIED_ORIGIN` | No identity disclosed | High risk |
 
 ## Trust Levels
 
-| Level | Name | Meaning |
-|-------|------|---------|
-| 0 | Self-Signed | Agent generated its own badge |
-| 1 | Domain Verified | Agent proved control of its DID |
-| 2 | Organization Verified | Agent's organization has been verified |
-| 3 | Extended Validation | Full identity verification completed |
+Per RFC-002 v1.4:
+
+| Level | Name | Validation | Use Case |
+|-------|------|------------|----------|
+| 0 | Self-Signed (SS) | None, `did:key` issuer | Local dev, testing, demos |
+| 1 | Registered (REG) | Account registration | Development, internal agents |
+| 2 | Domain Validated (DV) | DNS/HTTP challenge | Production, B2B agents |
+| 3 | Organization Validated (OV) | DUNS/legal entity | High-trust production |
+| 4 | Extended Validated (EV) | Manual review + legal | Regulated industries |
 
 ## Next Steps
 
-- [Server-Side Guide](../guides/server-side.md) — detailed guard configuration
-- [Client-Side Guide](../guides/client-side.md) — verify MCP servers before connecting
-- [Evidence Logging](../guides/evidence.md) — audit trail configuration
+- [Server-Side Guide](../guides/server-side.md) - Full @guard configuration
+- [Client-Side Guide](../guides/client-side.md) - Server verification patterns
+- [Evidence Logging](../guides/evidence.md) - Audit trail configuration
+- [MCP SDK Integration](../guides/mcp-integration.md) - Use with official MCP SDK