diff --git a/docs/getting-started/complete-workflow.md b/docs/getting-started/complete-workflow.md index 1ccc508..9397f03 100644 --- a/docs/getting-started/complete-workflow.md +++ b/docs/getting-started/complete-workflow.md @@ -380,58 +380,9 @@ 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 @@ -439,12 +390,13 @@ You've learned the complete CapiscIO workflow: 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 index 6778527..1e079af 100644 --- a/docs/getting-started/index.md +++ b/docs/getting-started/index.md @@ -1,15 +1,11 @@ --- 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 @@ -17,79 +13,15 @@ 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
-- :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) -
--- -## 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: - -
- -- :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) - -
+- [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 new file mode 100644 index 0000000..3370b7d --- /dev/null +++ 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 index 997be31..3ef13b0 100644 --- 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 index 926cbf4..b1963a8 100644 --- 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