capiscio · beonde · May 2, 2026 · May 2, 2026
diff --git a/docs/getting-started/complete-workflow.md b/docs/getting-started/complete-workflow.md
@@ -380,71 +380,23 @@ async def handle_task(request: dict):
 
 ---
 
-## Part 6: Monitor Trust Scores
-
-### 6.1 Check Validation Score
-
-```bash
-capiscio validate ./agent-card.json --json | jq '.scores'
-```
-
-Output:
-
-```json
-{
-  "compliance": 95,
-  "trust": 80,
-  "availability": 100
-}
-```
-
-### 6.2 Score Categories
-
-| Category | What It Measures |
-|----------|------------------|
-| **Compliance** | Schema correctness, required fields |
-| **Trust** | Signature validity, identity verification |
-| **Availability** | Endpoint reachability, response times |
-
-### 6.3 Improve Your Score
-
-- **Compliance**: Fix all schema warnings
-- **Trust**: Use CA-signed badges (level 2+)
-- **Availability**: Ensure `/.well-known/agent.json` is accessible
-
----
-
-## Part 7: Production Checklist
-
-Before going to production:
-
-- [ ] Agent card passes `--strict --registry-ready` validation
-- [ ] Private key secured (not in version control)
-- [ ] Domain verification completed (DNS TXT record)
-- [ ] Badge keeper daemon running
-- [ ] Gateway or SDK middleware configured
-- [ ] HTTPS enabled (TLS)
-- [ ] Health endpoints implemented
-- [ ] Monitoring configured
-
----
-
 ## Summary
 
-You've learned the complete CapiscIO workflow:
+You've completed the core CapiscIO workflow:
 
 1. **Create** an A2A agent card
 2. **Validate** with the CLI
 3. **Generate** Ed25519 keys
 4. **Register** with capiscio-server
 5. **Obtain** CA-signed badges
 6. **Deploy** with gateway enforcement
-7. **Monitor** trust scores
 
 ---
 
 ## Next Steps
 
+- [Trust Scores](../how-to/validation/trust-scores.md) — Monitor and improve your agent's scores
+- [Production Checklist](../reference/server/deployment.md#production-checklist) — Readiness checks before going live
 - [Trust Model](../concepts/trust-model.md) — Understand trust levels
 - [Badge Guides](../how-to/security/badges.md) — Advanced badge operations
 - [Gateway Setup](../how-to/security/gateway-setup.md) — Gateway configuration

diff --git a/docs/getting-started/index.md b/docs/getting-started/index.md
@@ -1,95 +1,27 @@
 ---
 title: Getting Started with CapiscIO
-description: Get your agent identity, trust badge, and validation in minutes. Zero to production-ready.
+description: Get your agent identity, trust badge, and validation in minutes.
 ---
 
 # Getting Started
 
-Get up and running with CapiscIO in minutes. **One command** gives your AI agent a cryptographic identity, just like Let's Encrypt did for HTTPS.
-
----
-
-## Quick Install
+Install CapiscIO and follow the guide that matches what you need to do.
 
 ```bash
 npm install -g capiscio       # or: pip install capiscio
 ```
 
 ---
 
-## The Fastest Path: One Command Setup
-
-Get a complete agent identity in **under 60 seconds**:
-
-=== "CLI"
-
-    ```bash
-    # Set your API key (get one free at app.capisc.io)
-    export CAPISCIO_API_KEY=sk_live_...
-
-    # That's it! One command does everything:
-    capiscio init
-    ```
-
-=== "Python"
-
-    ```python
-    from capiscio_sdk import CapiscIO
-
-    # One line - handles everything automatically
-    agent = CapiscIO.connect(api_key="sk_live_...")
-
-    print(agent.did)    # did:key:z6Mk...
-    print(agent.badge)  # Your trust badge
-    ```
-
-=== "Environment Variables"
-
-    ```python
-    # Set CAPISCIO_API_KEY in your environment
-    agent = CapiscIO.from_env()
-    ```
-
-**What happens automatically:**
-
-1. ✅ Ed25519 key pair generated
-2. ✅ `did:key` identity derived (RFC-002 compliant)
-3. ✅ DID registered with CapiscIO registry
-4. ✅ Agent card created with `x-capiscio` extension
-5. ✅ Trust badge requested and stored
-
----
-
-## What You Get
-
-After running `capiscio init`, your `.capiscio/` directory contains:
-
-```
-.capiscio/
-├── private.jwk      # Ed25519 private key (keep secret!)
-├── public.jwk       # Public key
-├── did.txt          # Your agent's did:key identifier
-└── agent-card.json  # A2A-compliant agent card
-```
-
-Your agent now has:
-
-- **Cryptographic identity** - A globally unique `did:key` that proves who you are
-- **Verifiable credentials** - Sign messages and prove authenticity
-- **Trust badge** - Registered with CapiscIO for discovery and verification
-- **A2A compliance** - Ready to interact with other A2A agents
-
----
-
-## Choose Your Next Step
+## Choose Your Path
 
 <div class="grid cards" markdown>
 
--   :material-check-decagram:{ .lg .middle } **Validate Your Agent**
+-   :material-check-decagram:{ .lg .middle } **Validate an Agent Card**
 
     ---
 
-    Ensure your agent card is A2A-compliant.
+    Check your `agent-card.json` is A2A-compliant.
 
     **5 minutes** · Beginner
 
@@ -99,7 +31,7 @@ Your agent now has:
 
     ---
 
-    Add request signing and verification.
+    Add request signing, badges, and trust verification.
 
     **15 minutes** · Intermediate
 
@@ -109,7 +41,7 @@ Your agent now has:
 
     ---
 
-    Add tool-level authorization to Model Context Protocol servers.
+    Add tool-level authorization to MCP servers.
 
     **10 minutes** · Intermediate
 
@@ -125,33 +57,15 @@ Your agent now has:
 
     [:octicons-arrow-right-24: Setup CI/CD](cicd/1-intro.md)
 
--   :material-routes:{ .lg .middle } **Complete Workflow**
-
-    ---
-
-    End-to-end guide: identity → badge → validation → deployment.
-
-    **30 minutes** · Comprehensive
-
-    [:octicons-arrow-right-24: Full Walkthrough](complete-workflow.md)
-
 </div>
 
 ---
 
-## Manual Setup (Advanced)
+## End-to-End Walkthrough
 
-If you need more control, you can still do things step-by-step:
+If you want to see the full flow — identity, registration, badges, gateway — in one tutorial:
 
-```bash
-# Generate keys only (no server registration)
-capiscio key gen --out-priv private.jwk --out-pub public.jwk
-
-# Show DID derived from generated key
-capiscio key gen --show-did
-```
-
-See the [CLI Reference](../reference/cli/index.md) for all options.
+[:octicons-arrow-right-24: Complete Workflow](complete-workflow.md) (30 minutes)
 
 ---
 
@@ -165,83 +79,8 @@ See the [CLI Reference](../reference/cli/index.md) for all options.
 
 ---
 
-## SDK Quick Reference
-
-=== "Python"
-
-    ```python
-    from capiscio_sdk import CapiscIO
-
-    # Connect and get full identity
-    agent = CapiscIO.connect(api_key="sk_live_...")
-
-    # Or from environment
-    agent = CapiscIO.from_env()  # Uses CAPISCIO_API_KEY
-
-    # Use the agent
-    print(agent.did)           # did:key:z6Mk...
-    print(agent.badge)         # Current trust badge
-    print(agent.status())      # Full status dict
-
-    # Emit events for observability
-    agent.emit("task_started", {"task_id": "123"})
-    ```
-
-=== "Node.js / TypeScript"
-
-    ```typescript
-    import { CapiscIO } from 'capiscio';
-
-    // Connect and get full identity
-    const agent = await CapiscIO.connect({ apiKey: 'sk_live_...' });
-
-    console.log(agent.did);    // did:key:z6Mk...
-    console.log(agent.badge);  // Current trust badge
-    ```
-
-=== "CLI"
-
-    ```bash
-    # Initialize agent identity
-    capiscio init --api-key $CAPISCIO_API_KEY
-
-    # Or with explicit agent ID
-    capiscio init --agent-id agt_abc123
-
-    # View your identity
-    cat .capiscio/did.txt
-    ```
-
----
-
 ## What's Next?
 
-After getting started, explore:
-
-<div class="grid cards" markdown>
-
--   :material-certificate:{ .lg .middle } **Get a Trust Badge**
-
-    ---
-
-    Upgrade from self-signed to verified trust.
-
-    [:octicons-arrow-right-24: Trust Badges](../trust/index.md)
-
--   :material-book-open:{ .lg .middle } **Understand the Concepts**
-
-    ---
-
-    Learn how validation, scoring, and trust work.
-
-    [:octicons-arrow-right-24: Concepts](../concepts/index.md)
-
--   :material-clipboard-list:{ .lg .middle } **How-To Guides**
-
-    ---
-
-    Solve specific problems with copy-paste recipes.
-
-    [:octicons-arrow-right-24: How-To Guides](../how-to/index.md)
-
-</div>
+- [Concepts](../concepts/index.md) — Understand how trust, scoring, and identity work
+- [How-To Guides](../how-to/index.md) — Solve specific problems with copy-paste recipes
+- [CLI Reference](../reference/cli/index.md) — All CLI commands and flags
diff --git a/docs/how-to/validation/trust-scores.md b/docs/how-to/validation/trust-scores.md
@@ -0,0 +1,39 @@
+# Monitor and Improve Trust Scores
+
+Check your agent's validation score and fix common issues.
+
+---
+
+## Check Your Score
+
+```bash
+capiscio validate ./agent-card.json --json | jq '.scores'
+```
+
+Output:
+
+```json
+{
+  "compliance": 95,
+  "trust": 80,
+  "availability": 100
+}
+```
+
+---
+
+## Score Categories
+
+| Category | What It Measures |
+|----------|------------------|
+| **Compliance** | Schema correctness, required fields |
+| **Trust** | Signature validity, identity verification |
+| **Availability** | Endpoint reachability, response times |
+
+---
+
+## Improve Your Score
+
+- **Compliance**: Fix all schema warnings (`capiscio validate --strict`)
+- **Trust**: Use CA-signed badges (trust level 2+)
+- **Availability**: Ensure `/.well-known/agent.json` is publicly accessible
diff --git a/docs/reference/server/deployment.md b/docs/reference/server/deployment.md
@@ -312,6 +312,21 @@ error: signature verification failed
 
 ---
 
+## Production Checklist
+
+Before going to production, ensure:
+
+- [ ] Agent card passes `capiscio validate --strict --registry-ready`
+- [ ] Private key secured (not in version control)
+- [ ] Domain verification completed (DNS TXT record)
+- [ ] Badge keeper daemon running for auto-renewal
+- [ ] Gateway or SDK middleware configured
+- [ ] HTTPS/TLS enabled on all endpoints
+- [ ] Health endpoints implemented (`/healthz`)
+- [ ] Monitoring and alerting configured
+
+---
+
 ## See Also
 
 - [API Reference](api.md) — Full API documentation

diff --git a/mkdocs.yml b/mkdocs.yml
@@ -212,6 +212,7 @@ nav:
           - Schema-Only Mode: how-to/validation/schema-only.md
           - Strict Mode: how-to/validation/strict-mode.md
           - Custom Timeout: how-to/validation/custom-timeout.md
+          - Trust Scores: how-to/validation/trust-scores.md
       - Security:
           - Sign Outbound: how-to/security/sign-outbound.md
           - Verify Inbound: how-to/security/verify-inbound.md