From 06396b28849891660809c502ad3f63f46baf1b16 Mon Sep 17 00:00:00 2001
From: Beon de Nood <beon@bigdune.net>
Date: Sat, 22 Nov 2025 00:06:29 -0500
Subject: [PATCH 1/3] chore: remove duplicate documentation files causing build
 warnings

---
 docs/architecture.md       | 450 -------------------------------------
 docs/scoring-system.md     | 365 ------------------------------
 docs/validation-process.md | 356 -----------------------------
 3 files changed, 1171 deletions(-)
 delete mode 100644 docs/architecture.md
 delete mode 100644 docs/scoring-system.md
 delete mode 100644 docs/validation-process.md

diff --git a/docs/architecture.md b/docs/architecture.md
deleted file mode 100644
index 017049d..0000000
--- a/docs/architecture.md
+++ /dev/null
@@ -1,450 +0,0 @@
-# 🏛️ Architecture Documentation
-
-> **Internal architecture and design decisions for CapiscIO CLI**
-
-## Design Philosophy
-
-**Core Principles:**
-
-- ✅ **Zero External Dependencies**: No reliance on external validator services
-- ✅ **Modularity**: Clean separation of concerns for easy maintenance
-- ✅ **Extensibility**: Simple to add new validation rules
-- ✅ **Performance**: Efficient validation with minimal overhead
-- ✅ **Reliability**: Comprehensive error handling and graceful degradation
-
-This document outlines the internal architecture, design patterns, and technical decisions behind the CapiscIO CLI validation system.
-
-## 📚 Table of Contents
-
-- [Overview](#overview)
-- [Core Components](#core-components)
-- [Data Flow](#data-flow)
-- [Design Patterns](#design-patterns)
-- [Dependency Management](#dependency-management)
-- [Performance Considerations](#performance-considerations)
-- [Extensibility](#extensibility)
-
-## Overview
-
-The CapiscIO CLI is designed as a self-contained, performant validation tool for A2A protocol agent cards. The architecture prioritizes:
-
-- **Zero External Dependencies**: No reliance on external validator services
-- **Modularity**: Clean separation of concerns
-- **Extensibility**: Easy to add new validation rules
-- **Performance**: Efficient validation with minimal overhead
-- **Reliability**: Comprehensive error handling and graceful degradation
-
-## Core Components
-
-### Component Diagram
-
-```mermaid
-graph TB
-    CLI[CLI Layer<br/>cli.ts<br/>Command Registration]
-    CMD[Commands<br/>validate.ts<br/>ValidateCmd]
-    OUT[Output<br/>console.ts<br/>json.ts]
-    
-    UTIL[Utilities<br/>file-utils.ts<br/>semver.ts]
-    VAL[Validator<br/>a2a-validator.ts]
-    HTTP[HTTP Client<br/>http-client.ts]
-    
-    TYPES[Type System<br/>AgentCard, ValidationResult<br/>ValidationOptions, ValidationError<br/>TransportProtocol, CLIOptions]
-    
-    CLI --> CMD
-    CMD --> OUT
-    CMD --> VAL
-    VAL --> UTIL
-    VAL --> HTTP
-    CLI -.-> TYPES
-    CMD -.-> TYPES
-    VAL -.-> TYPES
-    OUT -.-> TYPES
-```
-
-### Layer Responsibilities
-
-#### 1. CLI Layer (`src/cli.ts`)
-- Entry point and command registration
-- Global error handling
-- Version management
-- Commander.js integration
-
-#### 2. Command Layer (`src/commands/`)
-- Command-specific logic
-- Option parsing and validation
-- User interaction (spinners, prompts)
-- Result formatting coordination
-
-#### 3. Validator Layer (`src/validator/`)
-- Core validation logic
-- Schema validation
-- Version compatibility checking
-- Network endpoint testing
-
-#### 4. Output Layer (`src/output/`)
-- Result formatting and display
-- Console output with colors and styling
-- JSON output for CI/CD integration
-
-#### 5. Utility Layer (`src/utils/`)
-- File system operations
-- Semver utilities
-- Helper functions
-
-#### 6. Type Layer (`src/types/`)
-- TypeScript type definitions
-- Interface contracts
-- Type safety enforcement
-
-## Data Flow
-
-### Validation Flow Diagram
-
-```mermaid
-graph TB
-    USER[User Input] --> PARSE[Command Parser]
-    PARSE --> RESOLVE[Input Resolution<br/>File or URL Detection]
-    RESOLVE --> LOAD[Load Agent Card Data]
-    LOAD --> VALIDATOR[A2A Validator]
-    
-    VALIDATOR --> SCHEMA[Schema Validation]
-    VALIDATOR --> VERSION[Version Compatibility]
-    VALIDATOR --> NETWORK[Network Testing]
-    
-    SCHEMA --> RESULT[Validation Result]
-    VERSION --> RESULT
-    NETWORK --> RESULT
-    
-    RESULT --> FORMATTER[Output Formatter]
-    FORMATTER --> OUTPUT[Console or JSON Output]
-```
-
-### Processing Pipeline
-
-1. **Input Processing**
-   - Parse CLI arguments
-   - Resolve input type (file/URL/auto-detect)
-   - Load agent card data
-
-2. **Validation Pipeline**
-   - Schema validation
-   - Version compatibility analysis
-   - Network endpoint testing (if applicable)
-   - Feature detection and warnings
-
-3. **Result Aggregation**
-   - Collect errors, warnings, suggestions
-   - Calculate validation score
-   - Generate timing metrics
-
-4. **Output Generation**
-   - Format results for console or JSON
-   - Apply styling and colors
-   - Display actionable feedback
-
-## Design Patterns
-
-### 1. Strategy Pattern (Validation Modes)
-
-```typescript
-// Validation strategies
-interface ValidationStrategy {
-  validate(card: AgentCard): ValidationResult;
-}
-
-class ProgressiveStrategy implements ValidationStrategy {
-  validate(card: AgentCard): ValidationResult {
-    // Progressive validation logic
-  }
-}
-
-class StrictStrategy implements ValidationStrategy {
-  validate(card: AgentCard): ValidationResult {
-    // Strict validation logic
-  }
-}
-```
-
-### 2. Dependency Injection (HTTP Client)
-
-```typescript
-class A2AValidator {
-  constructor(private httpClient: HttpClient = new FetchHttpClient()) {
-    // Allows custom HTTP client injection for testing
-  }
-}
-```
-
-### 3. Factory Pattern (Output Formatters)
-
-```typescript
-function createOutputFormatter(format: 'json' | 'console'): OutputFormatter {
-  return format === 'json' ? new JsonOutput() : new ConsoleOutput();
-}
-```
-
-### 4. Command Pattern (CLI Commands)
-
-```typescript
-abstract class Command {
-  abstract execute(args: string[], options: CLIOptions): Promise<void>;
-}
-
-class ValidateCommand extends Command {
-  async execute(args: string[], options: CLIOptions): Promise<void> {
-    // Validation command implementation
-  }
-}
-```
-
-### 5. Builder Pattern (Validation Options)
-
-```typescript
-class ValidationOptionsBuilder {
-  private options: ValidationOptions = {};
-  
-  strictness(level: ValidationStrictness): this {
-    this.options.strictness = level;
-    return this;
-  }
-  
-  timeout(ms: number): this {
-    this.options.timeout = ms;
-    return this;
-  }
-  
-  build(): ValidationOptions {
-    return { ...this.options };
-  }
-}
-```
-
-## Dependency Management
-
-### Production Dependencies
-
-| Package | Purpose | Justification |
-|---------|---------|---------------|
-| `commander` | CLI framework | Industry standard, well-maintained |
-| `chalk` | Console colors | Enhanced user experience |
-| `ora` | Loading spinners | Visual feedback for long operations |
-| `inquirer` | Interactive prompts | Future extension capability |
-| `glob` | File pattern matching | Auto-detection functionality |
-
-### Zero External Service Dependencies
-
-- **No axios**: Uses native `fetch()` API
-- **No semver package**: Custom lightweight implementation
-- **No external validators**: Embedded validation logic
-- **No cloud services**: Completely self-contained
-
-### Bundle Size Optimization
-
-```bash
-# Production bundle analysis
-npm run build
-
-# Outputs:
-# dist/cli.js     ~27KB (minified)
-# dist/index.js   ~26KB (library)
-# dist/index.d.ts ~7KB  (types)
-```
-
-## Performance Considerations
-
-### Optimization Strategies
-
-1. **Lazy Loading**
-   ```typescript
-   // Only load validation rules when needed
-   const loadValidationRules = () => import('./validation-rules');
-   ```
-
-2. **Caching**
-   ```typescript
-   // Cache semver comparisons
-   const versionCache = new Map<string, boolean>();
-   ```
-
-3. **Early Termination**
-   ```typescript
-   // Stop validation on critical errors
-   if (criticalError) {
-     return { success: false, errors: [criticalError] };
-   }
-   ```
-
-4. **Parallel Processing**
-   ```typescript
-   // Validate multiple aspects concurrently
-   const [schemaResult, versionResult] = await Promise.all([
-     validateSchema(card),
-     validateVersion(card)
-   ]);
-   ```
-
-### Memory Management
-
-- Streaming JSON parsing for large files
-- Cleanup of HTTP connections
-- Garbage collection-friendly patterns
-
-### Performance Benchmarks
-
-| Operation | Average Time | Memory Usage |
-|-----------|--------------|---------------|
-| Schema validation | 1-10ms | 1-5MB |
-| Network request | 50-500ms | 1-2MB |
-| File parsing | 1-5ms | 1-3MB |
-| Total validation | 100-1000ms | 5-15MB |
-
-## Extensibility
-
-### Adding New Validation Rules
-
-```typescript
-// src/validator/rules/custom-rule.ts
-export class CustomValidationRule {
-  validate(card: AgentCard): ValidationError[] {
-    const errors: ValidationError[] = [];
-    
-    // Custom validation logic
-    if (customCondition(card)) {
-      errors.push({
-        code: 'CUSTOM_ERROR',
-        message: 'Custom validation failed',
-        severity: 'error'
-      });
-    }
-    
-    return errors;
-  }
-}
-
-// Register in validator
-validator.addRule(new CustomValidationRule());
-```
-
-### Custom Output Formatters
-
-```typescript
-// src/output/xml-output.ts
-export class XmlOutput implements OutputFormatter {
-  display(result: ValidationResult): void {
-    const xml = this.convertToXml(result);
-    console.log(xml);
-  }
-  
-  private convertToXml(result: ValidationResult): string {
-    // XML conversion logic
-  }
-}
-```
-
-### Plugin Architecture (Future)
-
-```typescript
-// Future plugin system design
-interface ValidationPlugin {
-  name: string;
-  version: string;
-  validate(card: AgentCard, options: ValidationOptions): Promise<PluginResult>;
-}
-
-class PluginManager {
-  private plugins: ValidationPlugin[] = [];
-  
-  register(plugin: ValidationPlugin): void {
-    this.plugins.push(plugin);
-  }
-  
-  async runPlugins(card: AgentCard): Promise<PluginResult[]> {
-    return Promise.all(
-      this.plugins.map(plugin => plugin.validate(card, {}))
-    );
-  }
-}
-```
-
-### Configuration System (Future)
-
-```typescript
-// .capiscio.config.js
-export default {
-  validation: {
-    strictness: 'progressive',
-    timeout: 10000,
-    rules: {
-      'schema-validation': { enabled: true },
-      'version-compatibility': { enabled: true },
-      'custom-rule': { enabled: false }
-    }
-  },
-  output: {
-    format: 'console',
-    colors: true,
-    verbose: false
-  }
-};
-```
-
-## Testing Architecture
-
-### Test Structure
-
-```
-tests/
-├── unit/
-│   ├── validator.test.ts
-│   ├── http-client.test.ts
-│   └── utils.test.ts
-├── integration/
-│   ├── cli.test.ts
-│   └── end-to-end.test.ts
-└── fixtures/
-    ├── valid-agents/
-    └── invalid-agents/
-```
-
-### Testing Patterns
-
-1. **Unit Tests**: Individual component testing
-2. **Integration Tests**: Component interaction testing
-3. **E2E Tests**: Full CLI workflow testing
-4. **Mock Strategy**: HTTP client mocking for network tests
-
----
-
-## See Also
-
-- **[Validation Process](validation-process.md)** - What gets validated
-- **[Scoring System](scoring-system.md)** - How validation results become scores
-- **[API Reference](api-reference.md)** - Public API surface
-- **[GitHub Repository](https://github.com/capiscio/capiscio-cli)** - Extend the validator
-
-!!! tip "Building an Agent?"
-    This document is for extending capiscio-cli. If you're building an A2A agent, see [CapiscIO Python SDK](/capiscio-python-sdk/) for runtime protection.
-
-## Maintenance & Evolution
-
-### Version Management
-
-- Semantic versioning for public API
-- Internal API versioning for extensions
-- Backward compatibility guarantees
-
-### Code Quality
-
-- TypeScript strict mode
-- ESLint with custom rules
-- Automated testing in CI
-- Code coverage requirements
-
-### Performance Monitoring
-
-- Validation timing metrics
-- Memory usage tracking
-- Bundle size monitoring
-- Performance regression testing
-
-This architecture provides a solid foundation for the current CLI while enabling future growth and extensibility.
\ No newline at end of file
diff --git a/docs/scoring-system.md b/docs/scoring-system.md
deleted file mode 100644
index 3f2b0c3..0000000
--- a/docs/scoring-system.md
+++ /dev/null
@@ -1,365 +0,0 @@
-# Using Scoring in the CLI
-
-> **Learn how to use the three-dimensional scoring system with CapiscIO CLI** - For the full scoring system reference, see the [**Unified Scoring Guide**](https://docs.capisc.io/guides/scoring-system/)
-
-## Quick Overview
-
-CapiscIO CLI uses a three-dimensional scoring system to evaluate agent cards:
-
-- **📄 Compliance (0-100)** - Protocol adherence and format validation
-- **🔐 Trust (0-100)** - Security practices and cryptographic verification  
-- **🚀 Availability (0-100)** - Operational readiness *(optional with `--test-live`)*
-
-!!! tip "Complete Scoring Details"
-    This page focuses on **CLI usage**. For the complete scoring system explanation, breakdowns, and calculations, see the [**Unified Scoring Guide**](https://docs.capisc.io/guides/scoring-system/).
-
----
-
-## Basic Usage
-
-### Viewing Scores
-
-Add the `--detailed-scores` flag to any validation command:
-
-```bash
-# Show detailed scoring breakdown
-capiscio validate agent-card.json --detailed-scores
-
-# Combine with live testing for availability scores
-capiscio validate https://agent.example.com --detailed-scores --test-live
-
-# JSON output with full scoring details
-capiscio validate agent-card.json --detailed-scores --json
-```
-
-### Example Output
-
-```
-📊 SCORING BREAKDOWN:
-
-  ✓ Spec Compliance: 100/100 Perfect
-    └─ Core Fields:       60/60
-    └─ Skills Quality:    20/20
-    └─ Format:            15/15
-    └─ Data Quality:      5/5
-
-  ✓ Trust: 24/100 Moderately Trusted
-    ⚠️  Confidence: 0.6x (Raw: 40)
-    └─ Signatures:        0/40
-    └─ Provider:          20/25
-    └─ Security:          15/20
-    └─ Documentation:     5/15
-
-  ⏭️  Availability: Not Tested
-    └─ Schema-only validation (use --test-live to test availability)
-
-💡 RECOMMENDATION:
-  ✅ Fully A2A v0.3.0 compliant
-  ⚠️ No cryptographic signatures - consider adding JWS signatures to improve trust
-  ⚠️ Not yet production ready - improve: trust
-```
-
----
-
-## JSON Output Format
-
-When using `--json` with `--detailed-scores`, the output includes full scoring details:
-
-```json
-{
-  "valid": true,
-  "version": "0.3.0",
-  "scores": {
-    "compliance": {
-      "total": 100,
-      "rating": "PERFECT",
-      "breakdown": {
-        "coreFields": {"score": 60, "maxScore": 60, "issues": []},
-        "skillsQuality": {"score": 20, "maxScore": 20, "issues": []},
-        "formatCompliance": {"score": 15, "maxScore": 15, "issues": []},
-        "dataQuality": {"score": 5, "maxScore": 5, "issues": []}
-      }
-    },
-    "trust": {
-      "total": 24,
-      "rating": "MODERATELY_TRUSTED",
-      "confidenceMultiplier": 0.6,
-      "breakdown": {
-        "signatures": {"score": 0, "maxScore": 40, "issues": ["No signatures present"]},
-        "provider": {"score": 20, "maxScore": 25, "issues": []},
-        "security": {"score": 15, "maxScore": 20, "issues": []},
-        "documentation": {"score": 5, "maxScore": 15, "issues": ["Missing docs URL"]}
-      }
-    },
-    "availability": null
-  },
-  "recommendation": "Improve trust score by adding cryptographic signatures"
-}
-```
-
-### Parsing JSON in Scripts
-
-```bash
-# Extract compliance score
-capiscio validate agent.json --detailed-scores --json | jq '.scores.compliance.total'
-
-# Check if production-ready (compliance >= 95, trust >= 60)
-COMPLIANCE=$(capiscio validate agent.json --detailed-scores --json | jq '.scores.compliance.total')
-TRUST=$(capiscio validate agent.json --detailed-scores --json | jq '.scores.trust.total')
-
-if [ "$COMPLIANCE" -ge 95 ] && [ "$TRUST" -ge 60 ]; then
-  echo "✅ Production ready"
-else
-  echo "⚠️  Not production ready"
-fi
-
-# Get all issues from trust breakdown
-capiscio validate agent.json --detailed-scores --json | \
-  jq '.scores.trust.breakdown | to_entries | .[] | select(.value.issues | length > 0) | {category: .key, issues: .value.issues}'
-```
-
----
-
-## CI/CD Integration
-
-### GitHub Actions Example
-
-```yaml
-name: Validate Agent Card
-
-on: [push, pull_request]
-
-jobs:
-  validate:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      
-      - name: Setup Node.js
-        uses: actions/setup-node@v3
-        with:
-          node-version: '18'
-      
-      - name: Install CapiscIO CLI
-        run: npm install -g capiscio-cli
-      
-      - name: Validate with scoring
-        run: |
-          capiscio validate agent-card.json --detailed-scores --json > results.json
-          
-          # Extract scores
-          COMPLIANCE=$(jq '.scores.compliance.total' results.json)
-          TRUST=$(jq '.scores.trust.total' results.json)
-          
-          echo "📊 Compliance: $COMPLIANCE/100"
-          echo "🔐 Trust: $TRUST/100"
-          
-          # Fail if below thresholds
-          if [ "$COMPLIANCE" -lt 95 ] || [ "$TRUST" -lt 60 ]; then
-            echo "❌ Failed: Scores below production thresholds (Compliance >= 95, Trust >= 60)"
-            exit 1
-          fi
-          
-          echo "✅ Passed: Production-ready scores"
-```
-
-### GitLab CI Example
-
-```yaml
-validate-agent:
-  stage: test
-  image: node:18
-  script:
-    - npm install -g capiscio-cli
-    - capiscio validate agent-card.json --detailed-scores --json > results.json
-    - COMPLIANCE=$(jq '.scores.compliance.total' results.json)
-    - TRUST=$(jq '.scores.trust.total' results.json)
-    - |
-      if [ "$COMPLIANCE" -lt 95 ] || [ "$TRUST" -lt 60 ]; then
-        echo "❌ Scores below thresholds"
-        exit 1
-      fi
-  artifacts:
-    reports:
-      junit: results.json
-```
-
----
-
-## Command Combinations
-
-### Validate Multiple Files
-
-```bash
-# Validate all agent cards with scoring
-for file in agents/*.json; do
-  echo "Validating $file..."
-  capiscio validate "$file" --detailed-scores
-done
-
-# Or use find
-find agents/ -name "*.json" -exec capiscio validate {} --detailed-scores \;
-```
-
-### Live Testing with Scoring
-
-```bash
-# Full validation with live endpoint testing
-capiscio validate https://agent.example.com --detailed-scores --test-live
-
-# Output shows all three dimensions:
-# - Compliance: Protocol adherence
-# - Trust: Security and signatures
-# - Availability: Endpoint health (from live test)
-```
-
-### Compare Agents
-
-```bash
-# Compare two agents side-by-side
-capiscio validate agent-a.json --detailed-scores --json > a.json
-capiscio validate agent-b.json --detailed-scores --json > b.json
-
-# Extract key metrics
-echo "Agent A - Compliance: $(jq '.scores.compliance.total' a.json), Trust: $(jq '.scores.trust.total' a.json)"
-echo "Agent B - Compliance: $(jq '.scores.compliance.total' b.json), Trust: $(jq '.scores.trust.total' b.json)"
-```
-
----
-
-## Filtering by Score Thresholds
-
-### Only Show Low Scores
-
-```bash
-#!/bin/bash
-# validate-and-filter.sh - Only show agents below thresholds
-
-for file in agents/*.json; do
-  RESULT=$(capiscio validate "$file" --detailed-scores --json)
-  COMPLIANCE=$(echo "$RESULT" | jq '.scores.compliance.total')
-  TRUST=$(echo "$RESULT" | jq '.scores.trust.total')
-  
-  if [ "$COMPLIANCE" -lt 90 ] || [ "$TRUST" -lt 70 ]; then
-    echo "⚠️  $file - Compliance: $COMPLIANCE, Trust: $TRUST"
-    echo "$RESULT" | jq '.scores.compliance.breakdown, .scores.trust.breakdown'
-  fi
-done
-```
-
-### Batch Validation Report
-
-```bash
-#!/bin/bash
-# generate-report.sh - Create CSV report of all agent scores
-
-echo "File,Compliance,Trust,ComplianceRating,TrustRating" > report.csv
-
-for file in agents/*.json; do
-  RESULT=$(capiscio validate "$file" --detailed-scores --json 2>/dev/null)
-  if [ $? -eq 0 ]; then
-    COMPLIANCE=$(echo "$RESULT" | jq -r '.scores.compliance.total')
-    TRUST=$(echo "$RESULT" | jq -r '.scores.trust.total')
-    COMP_RATING=$(echo "$RESULT" | jq -r '.scores.compliance.rating')
-    TRUST_RATING=$(echo "$RESULT" | jq -r '.scores.trust.rating')
-    
-    echo "$file,$COMPLIANCE,$TRUST,$COMP_RATING,$TRUST_RATING" >> report.csv
-  fi
-done
-
-echo "📊 Report generated: report.csv"
-```
-
----
-
-## Exit Codes and Scoring
-
-The CLI uses exit codes to indicate validation results:
-
-- **Exit 0**: Validation passed (agent is valid)
-- **Exit 1**: Validation failed (agent has errors)
-
-**Important:** The CLI exits with 0 even if scores are low, as long as the agent card is structurally valid. If you need to enforce score thresholds, use the JSON output and check scores in your script (see examples above).
-
-```bash
-# This will exit 0 even if trust is low
-capiscio validate agent.json --detailed-scores
-
-# To enforce thresholds, check JSON output
-TRUST=$(capiscio validate agent.json --detailed-scores --json | jq '.scores.trust.total')
-if [ "$TRUST" -lt 60 ]; then
-  echo "❌ Trust score too low"
-  exit 1
-fi
-```
-
----
-
-## Rating Enums
-
-The CLI outputs rating labels based on score ranges:
-
-### Compliance Ratings
-- `PERFECT` (100)
-- `EXCELLENT` (95-99)
-- `GOOD` (85-94)
-- `FAIR` (70-84)
-- `POOR` (0-69)
-
-### Trust Ratings
-- `HIGHLY_TRUSTED` (90-100)
-- `TRUSTED` (70-89)
-- `MODERATELY_TRUSTED` (50-69)
-- `UNTRUSTED` (30-49)
-- `HIGHLY_UNTRUSTED` (0-29)
-
-### Availability Ratings (with `--test-live`)
-- `HIGHLY_AVAILABLE` (90-100)
-- `AVAILABLE` (70-89)
-- `PARTIALLY_AVAILABLE` (50-69)
-- `DEGRADED` (30-49)
-- `UNAVAILABLE` (0-29)
-
----
-
-## See Also
-
-<div class="grid cards" markdown>
-
--   **📚 Unified Scoring Guide**
-
-    ---
-
-    Complete scoring system reference with all breakdowns, calculations, and rating thresholds.
-
-    [:octicons-arrow-right-24: View Complete Guide](https://docs.capisc.io/guides/scoring-system/)
-
--   **🐍 A2A Security Scoring**
-
-    ---
-
-    Python usage with ValidationResult API and decision patterns.
-
-    [:octicons-arrow-right-24: Python Usage](https://docs.capisc.io/capiscio-python-sdk/guides/scoring/)
-
--   **📖 CLI Reference**
-
-    ---
-
-    Complete command-line reference and options.
-
-    [:octicons-arrow-right-24: CLI Docs](./api-reference.md)
-
--   **⚡ Quick Start**
-
-    ---
-
-    Get started with CapiscIO CLI in 5 minutes.
-
-    [:octicons-arrow-right-24: Quick Start](./index.md)
-
-</div>
-
----
-
-**For complete scoring details**, see the [**Unified Scoring Guide**](https://docs.capisc.io/guides/scoring-system/).
diff --git a/docs/validation-process.md b/docs/validation-process.md
deleted file mode 100644
index 6f8ddb6..0000000
--- a/docs/validation-process.md
+++ /dev/null
@@ -1,356 +0,0 @@
-# 🔍 Validation Process Documentation
-
-> **Comprehensive guide to the CapiscIO CLI validation system**
-
-## What Gets Validated?
-
-**The Challenge:** The A2A protocol specification is comprehensive, and manually checking every requirement is time-consuming and error-prone.
-
-**Our Solution:** Automated validation across 7+ categories:
-
-- ✅ Input resolution and discovery
-- ✅ HTTP client and network validation
-- ✅ Schema and structure compliance
-- ✅ Version compatibility analysis
-- ✅ Protocol adherence
-- ✅ Security and authentication
-- ✅ Endpoint availability (optional)
-
-This document provides an exhaustive overview of everything included in the A2A agent card validation process.
-
-## 📚 Table of Contents
-
-- [Input Resolution & Discovery](#input-resolution-discovery)
-- [HTTP Client & Network Validation](#http-client-network-validation)
-- [Schema Validation](#schema-validation)
-- [Version Compatibility Analysis](#version-compatibility-analysis)
-- [Validation Modes](#validation-modes)
-- [Advanced Feature Detection](#advanced-feature-detection)
-- [Output & Reporting](#output-reporting)
-- [Error Codes Reference](#error-codes-reference)
-- [Performance & Timing](#performance-timing)
-
-## Input Resolution & Discovery
-
-### Auto-Detection Process
-
-When no input is specified, the CLI searches for agent cards in these locations (in order):
-
-```
-./agent-card.json (preferred)
-./.well-known/agent-card.json 
-./src/agent-card.json
-./public/.well-known/agent-card.json
-./dist/.well-known/agent-card.json
-./agent.json (legacy support)
-./.well-known/agent.json (legacy support)
-```
-
-### URL Handling
-
-1. **Direct URL validation**: Tests if URL directly contains agent card JSON
-2. **Well-known endpoint discovery**: Tries `/.well-known/agent-card.json` (A2A v0.3.0 standard)
-3. **Legacy endpoint fallback**: Falls back to `/.well-known/agent.json` (legacy)
-4. **Protocol inference**: Automatically adds `https://` if missing
-
-### File Processing
-
-- JSON parsing with detailed error messages
-- UTF-8 encoding support
-- Validation of JSON structure before processing
-- Graceful error handling for malformed files
-
-## HTTP Client & Network Validation
-
-### Request Configuration
-
-```typescript
-{
-  method: 'GET',
-  headers: {
-    'Accept': 'application/json',
-    'User-Agent': 'capiscio-cli/1.0.0'
-  },
-  timeout: 10000 // configurable
-}
-```
-
-### Error Handling
-
-| Error Type | Code | Description |
-|------------|------|-------------|
-| HTTP 400 | `BAD_REQUEST` | Invalid request format |
-| HTTP 401 | `UNAUTHORIZED` | Authentication required |
-| HTTP 403 | `FORBIDDEN` | Access denied |
-| HTTP 404 | `NOT_FOUND` | Agent card not found |
-| HTTP 408 | `TIMEOUT` | Request timeout |
-| HTTP 429 | `RATE_LIMITED` | Too many requests |
-| HTTP 500 | `INTERNAL_SERVER_ERROR` | Server error |
-| HTTP 502 | `BAD_GATEWAY` | Gateway error |
-| HTTP 503 | `SERVICE_UNAVAILABLE` | Service unavailable |
-| HTTP 504 | `GATEWAY_TIMEOUT` | Gateway timeout |
-| Network | `ENOTFOUND` | Domain not found |
-| Network | `ECONNREFUSED` | Connection refused |
-| Network | `NETWORK_ERROR` | General network error |
-
-## Schema Validation
-
-### Required Fields (A2A v0.3.0)
-
-#### Basic Required Fields
-- `name`: Agent display name
-- `description`: Agent description
-- `url`: Agent base URL
-- `provider`: Provider information object
-- `version`: Agent version (semver format)
-
-#### A2A Protocol Required Fields
-- `protocolVersion`: A2A protocol version (e.g., "0.3.0")
-- `preferredTransport`: Primary transport protocol
-
-#### Provider Structure
-```typescript
-{
-  "provider": {
-    "organization": "string", // Required
-    "url": "string"           // Optional
-  }
-}
-```
-
-### Skills Validation
-
-Each skill in the `skills` array must have:
-- `id`: Unique skill identifier
-- `examples`: Array of string examples (if present)
-
-### Version Format Validation
-
-- **Agent Version**: Must follow semantic versioning (semver)
-- **Protocol Version**: Must be valid A2A protocol version
-
-## Version Compatibility Analysis
-
-### Feature-Version Requirements
-
-| Feature | Minimum Protocol Version | Description |
-|---------|-------------------------|-------------|
-| `capabilities.pushNotifications` | 0.3.0 | Push notification support |
-| `additionalInterfaces` | 0.3.0 | Multiple interface support |
-| `capabilities.streaming` | 0.3.0 | Streaming capability |
-
-### Compatibility Checks
-
-1. **Protocol Version Detection**: Identifies declared protocol version
-2. **Feature Analysis**: Checks used features against declared version
-3. **Mismatch Detection**: Identifies incompatible feature-version combinations
-4. **Migration Suggestions**: Provides upgrade recommendations
-
-## Validation Modes
-
-### Progressive Mode (Default)
-```bash
-capiscio validate agent.json --progressive
-```
-
-**Characteristics:**
-- Balanced validation approach
-- Core A2A protocol requirements enforced
-- Warnings for deprecated features
-- Suggestions for best practices
-- Permissive of emerging features
-
-**Use Cases:**
-- Development and testing
-- Continuous integration
-- General-purpose validation
-
-### Strict Mode
-```bash
-capiscio validate agent.json --strict
-```
-
-**Characteristics:**
-- Full A2A protocol compliance required
-- All endpoints must be accessible
-- Security schemes required
-- Complete metadata validation
-- Zero tolerance for deprecated features
-
-**Use Cases:**
-- Production deployment
-- Registry submission
-- Compliance verification
-
-### Conservative Mode
-```bash
-capiscio validate agent.json --conservative
-```
-
-**Characteristics:**
-- Minimal validation requirements
-- Basic schema structure checking
-- Optional endpoint testing
-- Permissive security requirements
-
-**Use Cases:**
-- Early development
-- Legacy agent support
-- Basic structure validation
-
-## Advanced Feature Detection
-
-### Legacy Endpoint Handling
-
-**Detection Logic:**
-1. Check if URL uses `.well-known/agent.json` (legacy)
-2. Generate warning if legacy endpoint detected
-3. Suggest migration to `.well-known/agent-card.json`
-
-**Warning Generated:**
-```
-LEGACY_DISCOVERY_ENDPOINT: Agent discovered via legacy endpoint.
-The A2A v0.3.0 specification recommends using /.well-known/agent-card.json
-```
-
-### Transport Protocol Validation
-
-**Supported Protocols:**
-- `JSONRPC`: JSON-RPC transport
-- `GRPC`: gRPC transport
-- `HTTP+JSON`: HTTP with JSON payloads
-
-**Cross-Validation:**
-- gRPC transport should have streaming capabilities
-- Transport protocols must match interface declarations
-
-## Output & Reporting
-
-### Console Output Structure
-
-```
-✅ A2A AGENT VALIDATION PASSED
-Agent: https://example.com/.well-known/agent-card.json
-Score: 100/100
-Version: 0.3.0 (Strictness: progressive)
-
-🔍 VALIDATION SUMMARY:
-  📊 3 checks performed: 3 passed, 0 failed, 0 warnings
-  ⏱️  Completed in 245ms
-
-🔍 VALIDATIONS PERFORMED:
-✅ Schema Validation
-   Agent card structure is valid
-   Duration: 12ms
-✅ Endpoint Connectivity
-   All endpoints are accessible and responding
-   Duration: 195ms
-✅ A2A v0.3.0 Features
-   All v0.3.0 features are properly configured
-
-🏆 Perfect! Your agent passes all validations.
-🚀 Your agent is ready for deployment!
-```
-
-### JSON Output Structure
-
-```json
-{
-  "success": true,
-  "score": 100,
-  "errors": [],
-  "warnings": [],
-  "suggestions": [],
-  "validations": [
-    {
-      "id": "schema_validation",
-      "name": "Schema Validation",
-      "status": "passed",
-      "message": "Agent card conforms to A2A v0.3.0 schema",
-      "duration": 12,
-      "details": "Agent card structure is valid"
-    }
-  ],
-  "versionInfo": {
-    "detectedVersion": "0.3.0",
-    "validatorVersion": "0.3.0",
-    "strictness": "progressive",
-    "compatibility": {
-      "compatible": true,
-      "mismatches": [],
-      "suggestions": []
-    }
-  }
-}
-```
-
-## Error Codes Reference
-
-### Schema Validation Errors
-
-| Code | Description | Severity | Fixable |
-|------|-------------|----------|----------|
-| `SCHEMA_VALIDATION_ERROR` | Missing or invalid required field | Error | Yes |
-| `VERSION_MISMATCH_ERROR` | Protocol version conflicts | Error | Yes |
-| `STRICT_VERSION_MISMATCH` | Strict mode version issues | Error | Yes |
-
-### Network & Discovery Errors
-
-| Code | Description | Severity | Fixable |
-|------|-------------|----------|----------|
-| `VALIDATION_FAILED` | General validation failure | Error | Depends |
-| `ENDPOINT_UNREACHABLE` | HTTP connection issues | Error | Yes |
-| `LEGACY_DISCOVERY_ENDPOINT` | Using legacy endpoint | Warning | Yes |
-
-### Feature Compatibility Warnings
-
-| Code | Description | Severity | Fixable |
-|------|-------------|----------|----------|
-| `VERSION_FEATURE_MISMATCH` | Feature requires newer protocol | Warning | Yes |
-| `GRPC_WITHOUT_STREAMING` | gRPC without streaming capability | Warning | Yes |
-
-## Performance & Timing
-
-### Metrics Collected
-
-- **Individual Validation Steps**: Timing for each validation component
-- **Total Duration**: Complete validation time
-- **Network Requests**: HTTP request timing
-- **Schema Processing**: JSON parsing and validation time
-
-### Optimization Features
-
-- **Schema-Only Mode**: Skip network calls with `--schema-only`
-- **Timeout Configuration**: Custom timeout with `--timeout <ms>`
-- **Efficient Error Handling**: Early termination on critical failures
-
-### Performance Benchmarks
-
-| Operation | Typical Duration | Notes |
-|-----------|------------------|-------|
-| Schema Validation | 1-50ms | Depends on agent card size |
-| Network Request | 50-1000ms | Depends on network latency |
-| Version Analysis | <1ms | Cached semver operations |
-| Total Validation | 100-2000ms | Varies by mode and network |
-
----
-
-## See Also
-
-- **[Scoring System](scoring-system.md)** - Understand how validation results translate to scores
-- **[API Reference](api-reference.md)** - Use validation programmatically
-- **[Architecture](architecture.md)** - Internal validator implementation details
-- **[Python SDK](/capiscio-python-sdk/)** - Runtime protection for production agents
-
-!!! tip "Production Deployment"
-    capiscio-cli validates agent cards during development and CI/CD. For runtime protection, use [CapiscIO Python SDK](/capiscio-python-sdk/).
-
-## Contributing to Validation
-
-See the [GitHub repository](https://github.com/capiscio/capiscio-cli) for information on extending the validation system.
-
-## Related Documentation
-
-- [CLI Usage Guide](index.md)
-- [API Reference](./api-reference.md)
-- [A2A Protocol Specification](https://github.com/a2aproject/A2A){:target="_blank"}

From 04ea7a81d600d1c14c50c1d9c616311bbe94bb22 Mon Sep 17 00:00:00 2001
From: Beon de Nood <beon@bigdune.net>
Date: Tue, 2 Dec 2025 11:38:35 -0500
Subject: [PATCH 2/3] docs: clarify CLI-wrapper-only architecture

---
 docs/guides/programmatic-usage.md | 144 ++++++++-
 docs/guides/scoring.md            | 320 ++++++++----------
 docs/index.md                     | 174 ++++++++--
 docs/reference/api.md             | 520 +++++++++++++-----------------
 docs/reference/architecture.md    | 450 --------------------------
 docs/reference/cli.md             | 138 ++++++++
 mkdocs.yml                        |   3 +-
 7 files changed, 788 insertions(+), 961 deletions(-)
 delete mode 100644 docs/reference/architecture.md
 create mode 100644 docs/reference/cli.md

diff --git a/docs/guides/programmatic-usage.md b/docs/guides/programmatic-usage.md
index 6858f4e..3d65a54 100644
--- a/docs/guides/programmatic-usage.md
+++ b/docs/guides/programmatic-usage.md
@@ -1,24 +1,144 @@
+---
+title: Programmatic Usage
+description: How to use the capiscio CLI programmatically in Node.js applications.
+---
+
 # Programmatic Usage
 
-You can also use the CapiscIO wrapper programmatically in your Node.js scripts.
+For Node.js applications that need validation results, spawn the CLI with `--json` output.
+
+---
+
+## Basic Example
+
+```typescript
+import { execSync } from 'child_process';
+
+interface ValidationResult {
+  success: boolean;
+  score: number;
+  errors: Array<{ code: string; message: string }>;
+  warnings: Array<{ code: string; message: string }>;
+}
+
+function validate(path: string): ValidationResult {
+  try {
+    const output = execSync(`npx capiscio validate "${path}" --json`, {
+      encoding: 'utf8',
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+    return JSON.parse(output);
+  } catch (error: any) {
+    // CLI exits with code 1 on validation failure, but still outputs JSON
+    if (error.stdout) {
+      return JSON.parse(error.stdout);
+    }
+    throw error;
+  }
+}
+
+// Usage
+const result = validate('./agent-card.json');
+console.log(`Valid: ${result.success}, Score: ${result.score}`);
+```
+
+---
+
+## Async Version
+
+```typescript
+import { exec } from 'child_process';
+import { promisify } from 'util';
+
+const execAsync = promisify(exec);
+
+async function validateAsync(path: string): Promise<ValidationResult> {
+  try {
+    const { stdout } = await execAsync(`npx capiscio validate "${path}" --json`);
+    return JSON.parse(stdout);
+  } catch (error: any) {
+    if (error.stdout) {
+      return JSON.parse(error.stdout);
+    }
+    throw error;
+  }
+}
+```
+
+---
+
+## Batch Validation
+
+```typescript
+import { glob } from 'glob';
 
-## Installation
+async function validateAll(pattern: string) {
+  const files = await glob(pattern);
+  
+  const results = await Promise.all(
+    files.map(async file => ({
+      file,
+      result: await validateAsync(file)
+    }))
+  );
+  
+  const passed = results.filter(r => r.result.success);
+  const failed = results.filter(r => !r.result.success);
+  
+  console.log(`✅ Passed: ${passed.length}`);
+  console.log(`❌ Failed: ${failed.length}`);
+  
+  return results;
+}
 
-```bash
-npm install capiscio
+// Usage
+await validateAll('./agents/**/*.json');
 ```
 
-## Example
+---
+
+## Express Middleware
 
 ```typescript
-import { ValidateCommand } from 'capiscio';
+import express from 'express';
+import { execSync } from 'child_process';
+import { writeFileSync, unlinkSync } from 'fs';
+import { randomUUID } from 'crypto';
+
+const app = express();
+app.use(express.json());
 
-// Execute validation programmatically
-// Note: This currently spawns the binary and inherits stdio
-await ValidateCommand.execute('./agent-card.json', {
-  json: true,
-  strict: true
+app.post('/api/validate', (req, res) => {
+  // Write to temp file
+  const tempFile = `/tmp/agent-${randomUUID()}.json`;
+  writeFileSync(tempFile, JSON.stringify(req.body));
+  
+  try {
+    const output = execSync(`npx capiscio validate "${tempFile}" --json`, {
+      encoding: 'utf8'
+    });
+    res.json(JSON.parse(output));
+  } catch (error: any) {
+    if (error.stdout) {
+      res.json(JSON.parse(error.stdout));
+    } else {
+      res.status(500).json({ error: 'Validation failed' });
+    }
+  } finally {
+    unlinkSync(tempFile);
+  }
 });
 ```
 
-> **Note**: The programmatic API is currently minimal and primarily designed for CLI usage. For deeper integration, consider using the `capiscio-core` binary directly via `child_process`.
+---
+
+## Why Not a Native API?
+
+The `capiscio` npm package is a **distribution wrapper** for the Go-based validation engine. This approach:
+
+- ✅ Ensures consistent validation across all platforms
+- ✅ Leverages the high-performance Go implementation
+- ✅ Keeps the npm package lightweight
+- ✅ Single source of truth for validation logic
+
+For deep TypeScript integration, consider using the [capiscio-sdk-python](../../reference/sdk-python/index.md) pattern with your own HTTP middleware.
diff --git a/docs/guides/scoring.md b/docs/guides/scoring.md
index a0907eb..250fc1a 100644
--- a/docs/guides/scoring.md
+++ b/docs/guides/scoring.md
@@ -1,17 +1,14 @@
 # Using Scoring in the CLI
 
-> **Learn how to use the three-dimensional scoring system with CapiscIO CLI** - For the full scoring system reference, see the [**Unified Scoring Guide**](https://docs.capisc.io/guides/scoring-system/)
+> **Learn how to use the three-dimensional scoring system with CapiscIO CLI**
 
 ## Quick Overview
 
 CapiscIO CLI uses a three-dimensional scoring system to evaluate agent cards:
 
-- **📄 Compliance (0-100)** - Protocol adherence and format validation
-- **🔐 Trust (0-100)** - Security practices and cryptographic verification  
-- **🚀 Availability (0-100)** - Operational readiness *(optional with `--test-live`)*
-
-!!! tip "Complete Scoring Details"
-    This page focuses on **CLI usage**. For the complete scoring system explanation, breakdowns, and calculations, see the [**Unified Scoring Guide**](https://docs.capisc.io/guides/scoring-system/).
+- **📄 Compliance (0-100)** - Protocol adherence and format validation (`complianceScore`)
+- **�� Trust (0-100)** - Security practices and cryptographic verification (`trustScore`)
+- **🚀 Availability (0-100)** - Operational readiness *(only with `--test-live`)*
 
 ---
 
@@ -19,81 +16,93 @@ CapiscIO CLI uses a three-dimensional scoring system to evaluate agent cards:
 
 ### Viewing Scores
 
-Add the `--detailed-scores` flag to any validation command:
+Scores are included in `--json` output:
 
 ```bash
-# Show detailed scoring breakdown
-capiscio validate agent-card.json --detailed-scores
+# Validate and get JSON output with scores
+capiscio validate agent-card.json --json
+
+# Add live endpoint testing for availability scores
+capiscio validate https://agent.example.com --json --test-live
+```
 
-# Combine with live testing for availability scores
-capiscio validate https://agent.example.com --detailed-scores --test-live
+### Example Text Output
 
-# JSON output with full scoring details
-capiscio validate agent-card.json --detailed-scores --json
+```
+✅ A2A AGENT VALIDATION PASSED
+Score: 100/100
+Version: 0.3.0
+Perfect! Your agent passes all validations
 ```
 
-### Example Output
+### Example Output with Warnings
 
 ```
-📊 SCORING BREAKDOWN:
-
-  ✓ Spec Compliance: 100/100 Perfect
-    └─ Core Fields:       60/60
-    └─ Skills Quality:    20/20
-    └─ Format:            15/15
-    └─ Data Quality:      5/5
-
-  ✓ Trust: 24/100 Moderately Trusted
-    ⚠️  Confidence: 0.6x (Raw: 40)
-    └─ Signatures:        0/40
-    └─ Provider:          20/25
-    └─ Security:          15/20
-    └─ Documentation:     5/15
-
-  ⏭️  Availability: Not Tested
-    └─ Schema-only validation (use --test-live to test availability)
-
-💡 RECOMMENDATION:
-  ✅ Fully A2A v0.3.0 compliant
-  ⚠️ No cryptographic signatures - consider adding JWS signatures to improve trust
-  ⚠️ Not yet production ready - improve: trust
+✅ A2A AGENT VALIDATION PASSED
+Score: 85/100
+Version: 0.3.0
+Agent passed with warnings
+
+ERRORS FOUND:
+⚠️ [MISSING_DOCS] warning: No documentation URL provided
+⚠️ [UNSIGNED] warning: Agent card is not cryptographically signed
 ```
 
 ---
 
 ## JSON Output Format
 
-When using `--json` with `--detailed-scores`, the output includes full scoring details:
+When using `--json`, the output includes the full scoring result:
 
 ```json
 {
-  "valid": true,
+  "success": true,
+  "score": 100,
   "version": "0.3.0",
-  "scores": {
-    "compliance": {
-      "total": 100,
-      "rating": "PERFECT",
-      "breakdown": {
-        "coreFields": {"score": 60, "maxScore": 60, "issues": []},
-        "skillsQuality": {"score": 20, "maxScore": 20, "issues": []},
-        "formatCompliance": {"score": 15, "maxScore": 15, "issues": []},
-        "dataQuality": {"score": 5, "maxScore": 5, "issues": []}
-      }
+  "errors": [],
+  "warnings": [],
+  "scoringResult": {
+    "success": true,
+    "complianceScore": 100,
+    "trustScore": 85,
+    "availability": {
+      "score": 0,
+      "tested": false
     },
-    "trust": {
-      "total": 24,
-      "rating": "MODERATELY_TRUSTED",
-      "confidenceMultiplier": 0.6,
-      "breakdown": {
-        "signatures": {"score": 0, "maxScore": 40, "issues": ["No signatures present"]},
-        "provider": {"score": 20, "maxScore": 25, "issues": []},
-        "security": {"score": 15, "maxScore": 20, "issues": []},
-        "documentation": {"score": 5, "maxScore": 15, "issues": ["Missing docs URL"]}
-      }
+    "issues": [],
+    "signatures": null
+  },
+  "liveTest": null
+}
+```
+
+### With Live Testing (`--test-live`)
+
+```json
+{
+  "success": true,
+  "score": 100,
+  "version": "0.3.0",
+  "errors": [],
+  "warnings": [],
+  "scoringResult": {
+    "success": true,
+    "complianceScore": 100,
+    "trustScore": 85,
+    "availability": {
+      "score": 95,
+      "tested": true,
+      "endpointUrl": "https://agent.example.com/.well-known/agent.json",
+      "latencyMs": 142
     },
-    "availability": null
+    "issues": []
   },
-  "recommendation": "Improve trust score by adding cryptographic signatures"
+  "liveTest": {
+    "success": true,
+    "endpoint": "https://agent.example.com/.well-known/agent.json",
+    "responseTime": 142,
+    "errors": []
+  }
 }
 ```
 
@@ -101,21 +110,24 @@ When using `--json` with `--detailed-scores`, the output includes full scoring d
 
 ```bash
 # Extract compliance score
-capiscio validate agent.json --detailed-scores --json | jq '.scores.compliance.total'
+capiscio validate agent.json --json | jq '.scoringResult.complianceScore'
+
+# Extract trust score
+capiscio validate agent.json --json | jq '.scoringResult.trustScore'
 
 # Check if production-ready (compliance >= 95, trust >= 60)
-COMPLIANCE=$(capiscio validate agent.json --detailed-scores --json | jq '.scores.compliance.total')
-TRUST=$(capiscio validate agent.json --detailed-scores --json | jq '.scores.trust.total')
+RESULT=$(capiscio validate agent.json --json)
+COMPLIANCE=$(echo "$RESULT" | jq '.scoringResult.complianceScore')
+TRUST=$(echo "$RESULT" | jq '.scoringResult.trustScore')
 
-if [ "$COMPLIANCE" -ge 95 ] && [ "$TRUST" -ge 60 ]; then
+if (( $(echo "$COMPLIANCE >= 95" | bc -l) )) && (( $(echo "$TRUST >= 60" | bc -l) )); then
   echo "✅ Production ready"
 else
   echo "⚠️  Not production ready"
 fi
 
-# Get all issues from trust breakdown
-capiscio validate agent.json --detailed-scores --json | \
-  jq '.scores.trust.breakdown | to_entries | .[] | select(.value.issues | length > 0) | {category: .key, issues: .value.issues}'
+# Get all validation issues
+capiscio validate agent.json --json | jq '.scoringResult.issues[]'
 ```
 
 ---
@@ -133,30 +145,30 @@ jobs:
   validate:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       
       - name: Setup Node.js
-        uses: actions/setup-node@v3
+        uses: actions/setup-node@v4
         with:
-          node-version: '18'
+          node-version: '20'
       
       - name: Install CapiscIO CLI
-        run: npm install -g capiscio-cli
+        run: npm install -g capiscio
       
       - name: Validate with scoring
         run: |
-          capiscio validate agent-card.json --detailed-scores --json > results.json
+          capiscio validate agent-card.json --json > results.json
           
           # Extract scores
-          COMPLIANCE=$(jq '.scores.compliance.total' results.json)
-          TRUST=$(jq '.scores.trust.total' results.json)
+          COMPLIANCE=$(jq '.scoringResult.complianceScore' results.json)
+          TRUST=$(jq '.scoringResult.trustScore' results.json)
           
           echo "📊 Compliance: $COMPLIANCE/100"
           echo "🔐 Trust: $TRUST/100"
           
           # Fail if below thresholds
-          if [ "$COMPLIANCE" -lt 95 ] || [ "$TRUST" -lt 60 ]; then
-            echo "❌ Failed: Scores below production thresholds (Compliance >= 95, Trust >= 60)"
+          if (( $(echo "$COMPLIANCE < 95" | bc -l) )) || (( $(echo "$TRUST < 60" | bc -l) )); then
+            echo "❌ Failed: Scores below production thresholds"
             exit 1
           fi
           
@@ -168,20 +180,17 @@ jobs:
 ```yaml
 validate-agent:
   stage: test
-  image: node:18
+  image: node:20
   script:
-    - npm install -g capiscio-cli
-    - capiscio validate agent-card.json --detailed-scores --json > results.json
-    - COMPLIANCE=$(jq '.scores.compliance.total' results.json)
-    - TRUST=$(jq '.scores.trust.total' results.json)
+    - npm install -g capiscio
+    - capiscio validate agent-card.json --json > results.json
+    - COMPLIANCE=$(jq '.scoringResult.complianceScore' results.json)
+    - TRUST=$(jq '.scoringResult.trustScore' results.json)
     - |
-      if [ "$COMPLIANCE" -lt 95 ] || [ "$TRUST" -lt 60 ]; then
+      if (( $(echo "$COMPLIANCE < 95" | bc -l) )) || (( $(echo "$TRUST < 60" | bc -l) )); then
         echo "❌ Scores below thresholds"
         exit 1
       fi
-  artifacts:
-    reports:
-      junit: results.json
 ```
 
 ---
@@ -191,79 +200,57 @@ validate-agent:
 ### Validate Multiple Files
 
 ```bash
-# Validate all agent cards with scoring
+# Validate all agent cards
 for file in agents/*.json; do
   echo "Validating $file..."
-  capiscio validate "$file" --detailed-scores
+  capiscio validate "$file"
 done
 
 # Or use find
-find agents/ -name "*.json" -exec capiscio validate {} --detailed-scores \;
+find agents/ -name "*.json" -exec capiscio validate {} \;
 ```
 
-### Live Testing with Scoring
+### Live Testing for Availability
 
 ```bash
 # Full validation with live endpoint testing
-capiscio validate https://agent.example.com --detailed-scores --test-live
+capiscio validate https://agent.example.com --test-live --json
 
-# Output shows all three dimensions:
-# - Compliance: Protocol adherence
-# - Trust: Security and signatures
-# - Availability: Endpoint health (from live test)
+# Schema-only validation (no live test even if URL)
+capiscio validate https://agent.example.com --schema-only
 ```
 
 ### Compare Agents
 
 ```bash
 # Compare two agents side-by-side
-capiscio validate agent-a.json --detailed-scores --json > a.json
-capiscio validate agent-b.json --detailed-scores --json > b.json
+capiscio validate agent-a.json --json > a.json
+capiscio validate agent-b.json --json > b.json
 
 # Extract key metrics
-echo "Agent A - Compliance: $(jq '.scores.compliance.total' a.json), Trust: $(jq '.scores.trust.total' a.json)"
-echo "Agent B - Compliance: $(jq '.scores.compliance.total' b.json), Trust: $(jq '.scores.trust.total' b.json)"
+echo "Agent A - Compliance: $(jq '.scoringResult.complianceScore' a.json), Trust: $(jq '.scoringResult.trustScore' a.json)"
+echo "Agent B - Compliance: $(jq '.scoringResult.complianceScore' b.json), Trust: $(jq '.scoringResult.trustScore' b.json)"
 ```
 
 ---
 
-## Filtering by Score Thresholds
-
-### Only Show Low Scores
-
-```bash
-#!/bin/bash
-# validate-and-filter.sh - Only show agents below thresholds
-
-for file in agents/*.json; do
-  RESULT=$(capiscio validate "$file" --detailed-scores --json)
-  COMPLIANCE=$(echo "$RESULT" | jq '.scores.compliance.total')
-  TRUST=$(echo "$RESULT" | jq '.scores.trust.total')
-  
-  if [ "$COMPLIANCE" -lt 90 ] || [ "$TRUST" -lt 70 ]; then
-    echo "⚠️  $file - Compliance: $COMPLIANCE, Trust: $TRUST"
-    echo "$RESULT" | jq '.scores.compliance.breakdown, .scores.trust.breakdown'
-  fi
-done
-```
-
-### Batch Validation Report
+## Batch Validation Report
 
 ```bash
 #!/bin/bash
 # generate-report.sh - Create CSV report of all agent scores
 
-echo "File,Compliance,Trust,ComplianceRating,TrustRating" > report.csv
+echo "File,Success,Compliance,Trust,Issues" > report.csv
 
 for file in agents/*.json; do
-  RESULT=$(capiscio validate "$file" --detailed-scores --json 2>/dev/null)
-  if [ $? -eq 0 ]; then
-    COMPLIANCE=$(echo "$RESULT" | jq -r '.scores.compliance.total')
-    TRUST=$(echo "$RESULT" | jq -r '.scores.trust.total')
-    COMP_RATING=$(echo "$RESULT" | jq -r '.scores.compliance.rating')
-    TRUST_RATING=$(echo "$RESULT" | jq -r '.scores.trust.rating')
+  RESULT=$(capiscio validate "$file" --json 2>/dev/null)
+  if [ $? -eq 0 ] || [ $? -eq 1 ]; then
+    SUCCESS=$(echo "$RESULT" | jq -r '.success')
+    COMPLIANCE=$(echo "$RESULT" | jq -r '.scoringResult.complianceScore')
+    TRUST=$(echo "$RESULT" | jq -r '.scoringResult.trustScore')
+    ISSUES=$(echo "$RESULT" | jq -r '.scoringResult.issues | length')
     
-    echo "$file,$COMPLIANCE,$TRUST,$COMP_RATING,$TRUST_RATING" >> report.csv
+    echo "$file,$SUCCESS,$COMPLIANCE,$TRUST,$ISSUES" >> report.csv
   fi
 done
 
@@ -272,53 +259,42 @@ echo "📊 Report generated: report.csv"
 
 ---
 
-## Exit Codes and Scoring
+## Exit Codes
 
 The CLI uses exit codes to indicate validation results:
 
-- **Exit 0**: Validation passed (agent is valid)
-- **Exit 1**: Validation failed (agent has errors)
+| Exit Code | Meaning |
+|-----------|---------|
+| **0** | Validation passed (agent is valid) |
+| **1** | Validation failed (agent has errors) |
 
-**Important:** The CLI exits with 0 even if scores are low, as long as the agent card is structurally valid. If you need to enforce score thresholds, use the JSON output and check scores in your script (see examples above).
+**Important:** The CLI exits with 0 even if scores are low, as long as the agent card is structurally valid. To enforce score thresholds, parse the JSON output:
 
 ```bash
-# This will exit 0 even if trust is low
-capiscio validate agent.json --detailed-scores
+# Enforce minimum trust score
+RESULT=$(capiscio validate agent.json --json)
+TRUST=$(echo "$RESULT" | jq '.scoringResult.trustScore')
 
-# To enforce thresholds, check JSON output
-TRUST=$(capiscio validate agent.json --detailed-scores --json | jq '.scores.trust.total')
-if [ "$TRUST" -lt 60 ]; then
-  echo "❌ Trust score too low"
+if (( $(echo "$TRUST < 60" | bc -l) )); then
+  echo "❌ Trust score too low: $TRUST"
   exit 1
 fi
 ```
 
 ---
 
-## Rating Enums
-
-The CLI outputs rating labels based on score ranges:
-
-### Compliance Ratings
-- `PERFECT` (100)
-- `EXCELLENT` (95-99)
-- `GOOD` (85-94)
-- `FAIR` (70-84)
-- `POOR` (0-69)
+## CLI Flags Reference
 
-### Trust Ratings
-- `HIGHLY_TRUSTED` (90-100)
-- `TRUSTED` (70-89)
-- `MODERATELY_TRUSTED` (50-69)
-- `UNTRUSTED` (30-49)
-- `HIGHLY_UNTRUSTED` (0-29)
-
-### Availability Ratings (with `--test-live`)
-- `HIGHLY_AVAILABLE` (90-100)
-- `AVAILABLE` (70-89)
-- `PARTIALLY_AVAILABLE` (50-69)
-- `DEGRADED` (30-49)
-- `UNAVAILABLE` (0-29)
+| Flag | Description |
+|------|-------------|
+| `--json` | Output results as JSON (includes all scores) |
+| `--test-live` | Test live agent endpoint for availability score |
+| `--strict` | Enable strict validation mode |
+| `--schema-only` | Validate schema only, skip endpoint testing |
+| `--skip-signature` | Skip JWS signature verification |
+| `--registry-ready` | Check registry deployment readiness |
+| `--timeout` | Request timeout (default: 10s) |
+| `--errors-only` | Show only errors and warnings |
 
 ---
 
@@ -326,29 +302,13 @@ The CLI outputs rating labels based on score ranges:
 
 <div class="grid cards" markdown>
 
--   **📚 Unified Scoring Guide**
-
-    ---
-
-    Complete scoring system reference with all breakdowns, calculations, and rating thresholds.
-
-    [:octicons-arrow-right-24: View Complete Guide](https://docs.capisc.io/guides/scoring-system/)
-
--   **🐍 A2A Security Scoring**
-
-    ---
-
-    Python usage with ValidationResult API and decision patterns.
-
-    [:octicons-arrow-right-24: Python Usage](https://docs.capisc.io/capiscio-python-sdk/guides/scoring/)
-
 -   **📖 CLI Reference**
 
     ---
 
     Complete command-line reference and options.
 
-    [:octicons-arrow-right-24: CLI Docs](../reference/api.md)
+    [:octicons-arrow-right-24: CLI Docs](../reference/cli.md)
 
 -   **⚡ Quick Start**
 
@@ -359,7 +319,3 @@ The CLI outputs rating labels based on score ranges:
     [:octicons-arrow-right-24: Quick Start](../getting-started/installation.md)
 
 </div>
-
----
-
-**For complete scoring details**, see the [**Unified Scoring Guide**](https://docs.capisc.io/guides/scoring-system/).
diff --git a/docs/index.md b/docs/index.md
index 0577e1b..bbc3ee0 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,51 +1,173 @@
 ---
-title: CapiscIO Node.js CLI - Documentation
-description: Official documentation for the CapiscIO Node.js CLI wrapper. Validate, score, and manage A2A agents from the command line.
+title: CapiscIO npm Package
+description: Install the capiscio CLI via npm. Validate A2A agent cards from the command line.
 ---
 
-# CapiscIO Node.js CLI
+# CapiscIO npm Package
 
-The **CapiscIO Node.js CLI** (`capiscio-cli`) is the official command-line tool for interacting with the Agent-to-Agent (A2A) Protocol. It provides a robust suite of tools for validating agent cards, checking protocol compliance, and integrating A2A security into your development workflow.
+The `capiscio` npm package installs the CapiscIO CLI for validating A2A agent cards.
 
-<div class="grid cards" markdown>
+```bash
+npm install -g capiscio
+```
+
+---
+
+## Quick Start
+
+```bash
+# Validate a local file
+capiscio validate ./agent-card.json
+
+# Validate a remote agent
+capiscio validate https://your-agent.example.com
+
+# Strict mode with JSON output
+capiscio validate ./agent-card.json --strict --json
+```
+
+---
+
+## What This Package Does
 
--   **🚀 Getting Started**
+This npm package is a **distribution wrapper** for [capiscio-core](https://github.com/capiscio/capiscio-core), the Go-based validation engine.
 
-    ---
+```
+┌────────────────────────────────────┐
+│     npm install -g capiscio        │
+└─────────────────┬──────────────────┘
+                  │
+                  ▼
+┌────────────────────────────────────┐
+│     capiscio-core (Go binary)      │
+│     Downloaded automatically       │
+└────────────────────────────────────┘
+```
 
-    Install the CLI and run your first validation.
+**Why a wrapper?**
 
-    [:octicons-arrow-right-24: Installation](./getting-started/installation.md)
+- ✅ Easy installation via npm
+- ✅ No Go toolchain required
+- ✅ Automatic binary management
+- ✅ Cross-platform support
 
--   **📖 Guides**
+---
 
-    ---
+## Installation Options
 
-    Learn how to use the CLI programmatically and understand scoring.
+### Global Install (Recommended)
 
-    [:octicons-arrow-right-24: View Guides](./guides/programmatic-usage.md)
+```bash
+npm install -g capiscio
+capiscio validate ./agent-card.json
+```
 
--   **⚙️ Reference**
+### npx (No Install)
 
-    ---
+```bash
+npx capiscio validate ./agent-card.json
+```
 
-    Complete API reference and architecture details.
+### Project Dependency
 
-    [:octicons-arrow-right-24: API Reference](./reference/api.md)
+```bash
+npm install --save-dev capiscio
+npx capiscio validate ./agent-card.json
+```
 
-</div>
+---
 
-## Key Features
+## CLI Reference
 
-- **Agent Validation**: Validate `agent-card.json` files against the A2A specification.
-- **Scoring System**: Get detailed compliance, trust, and availability scores.
-- **CI/CD Integration**: Easily integrate validation into GitHub Actions or GitLab CI.
-- **Programmatic API**: Use the CLI as a library in your Node.js applications.
+### validate
 
-## Installation
+Validate an A2A agent card.
 
 ```bash
-npm install -g capiscio-cli
+capiscio validate [input] [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `--strict` | Strict validation mode |
+| `--json` | JSON output (for CI/CD) |
+| `--schema-only` | Skip network requests |
+| `--skip-signature` | Skip JWS signature verification |
+| `--test-live` | Test live agent endpoint |
+| `--timeout <ms>` | Request timeout (default: 10000) |
+| `--verbose` | Detailed output |
+| `--errors-only` | Show only errors |
+
+### Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Validation passed |
+| `1` | Validation failed |
+
+---
+
+## CI/CD Integration
+
+### GitHub Actions
+
+```yaml
+- name: Validate Agent Card
+  run: npx capiscio validate ./agent-card.json --strict --json
+```
+
+### GitLab CI
+
+```yaml
+validate:
+  script:
+    - npx capiscio validate ./agent-card.json --strict --json
+```
+
+!!! tip "Dedicated GitHub Action"
+    For richer CI integration, use [validate-a2a](https://github.com/capiscio/validate-a2a).
+
+---
+
+## Programmatic Usage
+
+For Node.js applications that need validation results programmatically, spawn the CLI with JSON output:
+
+```typescript
+import { execSync } from 'child_process';
+
+function validateAgentCard(path: string) {
+  try {
+    const output = execSync(`npx capiscio validate ${path} --json`, {
+      encoding: 'utf8'
+    });
+    return JSON.parse(output);
+  } catch (error: any) {
+    // CLI returns non-zero exit code on validation failure
+    return JSON.parse(error.stdout);
+  }
+}
+
+const result = validateAgentCard('./agent-card.json');
+console.log(`Valid: ${result.success}, Score: ${result.score}`);
 ```
 
-For full installation instructions, see the [Installation Guide](./getting-started/installation.md).
+---
+
+## Alternative Installation Methods
+
+If you prefer not to use npm:
+
+| Method | Command |
+|--------|---------|
+| **pip** | `pip install capiscio` |
+| **Binary** | [Download from GitHub](https://github.com/capiscio/capiscio-core/releases) |
+| **Docker** | `docker pull ghcr.io/capiscio/capiscio-core` |
+
+---
+
+## See Also
+
+- [CLI Reference](../reference/cli/index.md) - Complete command documentation
+- [capiscio-core](https://github.com/capiscio/capiscio-core) - Underlying Go binary
+- [validate-a2a](https://github.com/capiscio/validate-a2a) - GitHub Action
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 23b5b64..4104371 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -1,206 +1,199 @@
 ---
-title: API Reference - CapiscIO CLI Documentation
-description: Programmatic API documentation for CapiscIO CLI including A2AValidator class, validation methods, and TypeScript interfaces.
-keywords: CapiscIO CLI API, A2AValidator, validation methods, TypeScript, programmatic usage, npm package
+title: TypeScript API Reference
+description: Programmatic API documentation for the capiscio npm package. A2AValidator class and TypeScript types.
 ---
 
-# API Reference
+# TypeScript API Reference
 
-> Programmatic usage documentation for CapiscIO CLI
+The `capiscio` package exports a pure TypeScript validation engine for programmatic use.
 
-This document provides comprehensive API documentation for using CapiscIO CLI programmatically.
-
-## Table of Contents
+!!! info "When to Use"
+    Use the TypeScript API when you need:
+    
+    - Runtime validation in Node.js applications
+    - Custom error handling and result processing
+    - Integration with Express, Fastify, or other frameworks
+    - Batch validation workflows
+    
+    For command-line usage, see the [CLI Reference](./cli.md).
 
-- [Installation](#installation)
-- [Core Classes](#core-classes)
-- [Types & Interfaces](#types-interfaces)
-- [Validation Options](#validation-options)
-- [Error Handling](#error-handling)
-- [Examples](#examples)
+---
 
 ## Installation
 
 ```bash
-npm install capiscio-cli
+npm install capiscio
 ```
 
-## Core Classes
-
-### A2AValidator
+---
 
-The main validation class for A2A agent cards.
+## Quick Start
 
 ```typescript
-import { A2AValidator } from 'capiscio-cli';
+import { A2AValidator } from 'capiscio';
 
 const validator = new A2AValidator();
-```
 
-#### Constructor
+// Validate a local file
+const result = await validator.validate('./agent-card.json');
 
-```typescript
-constructor(httpClient?: HttpClient)
+// Validate a URL
+const remoteResult = await validator.validate('https://agent.example.com');
+
+// Check results
+if (result.success) {
+  console.log(`Score: ${result.score}/100`);
+} else {
+  result.errors.forEach(err => console.error(err.message));
+}
 ```
 
-**Parameters:**
-- `httpClient` (optional): Custom HTTP client implementation
+---
 
-#### Methods
+## A2AValidator
 
-##### `validate(input, options?): Promise<ValidationResult>`
+The main validation class.
 
-Main validation method that supports both files and URLs.
+### Constructor
 
 ```typescript
-const result = await validator.validate('./agent.json', {
-  strictness: 'progressive',
-  timeout: 10000
-});
+constructor(httpClient?: HttpClient)
 ```
 
-**Parameters:**
-- `input`: `AgentCard | string` - Agent card object or URL/file path
-- `options`: `ValidationOptions` - Validation configuration
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `httpClient` | `HttpClient` | Optional custom HTTP client for network requests |
 
-**Returns:** `Promise<ValidationResult>`
+### Methods
 
-##### `validateProgressive(input, options?): Promise<ValidationResult>`
+#### validate()
 
-Convenience method for progressive validation.
+Main validation method supporting files and URLs.
 
 ```typescript
-const result = await validator.validateProgressive('./agent.json');
+async validate(
+  input: AgentCard | string, 
+  options?: ValidationOptions
+): Promise<ValidationResult>
 ```
 
-##### `validateStrict(input, options?): Promise<ValidationResult>`
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `input` | `AgentCard \| string` | Agent card object, file path, or URL |
+| `options` | `ValidationOptions` | Validation configuration |
 
-Convenience method for strict validation.
+**Example:**
 
 ```typescript
-const result = await validator.validateStrict('./agent.json');
+const result = await validator.validate('./agent-card.json', {
+  strictness: 'progressive',
+  timeout: 10000,
+  skipSignatureVerification: false
+});
 ```
 
-##### `validateConservative(input, options?): Promise<ValidationResult>`
+#### validateStrict()
 
-Convenience method for conservative validation.
+Convenience method for strict validation.
 
 ```typescript
-const result = await validator.validateConservative('./agent.json');
+async validateStrict(
+  input: AgentCard | string, 
+  options?: ValidationOptions
+): Promise<ValidationResult>
 ```
 
-##### `validateSchemaOnly(card, options?): Promise<ValidationResult>`
-
-Schema-only validation (no network calls).
+**Example:**
 
 ```typescript
-const result = await validator.validateSchemaOnly(agentCardObject);
+const result = await validator.validateStrict('./agent-card.json');
+// Equivalent to: validator.validate(input, { strictness: 'strict' })
 ```
 
-### FetchHttpClient
+#### validateProgressive()
 
-Default HTTP client implementation using native fetch API.
+Convenience method for progressive validation (default mode).
 
 ```typescript
-import { FetchHttpClient } from 'capiscio-cli';
-
-const httpClient = new FetchHttpClient();
-const validator = new A2AValidator(httpClient);
+async validateProgressive(
+  input: AgentCard | string, 
+  options?: ValidationOptions
+): Promise<ValidationResult>
 ```
 
-#### Methods
+#### validateConservative()
 
-##### `get(url, options?): Promise<HttpResponse>`
-
-Performs HTTP GET request.
+Convenience method for conservative validation (minimal requirements).
 
 ```typescript
-const response = await httpClient.get('https://example.com/agent.json', {
-  timeout: 5000,
-  headers: { 'Authorization': 'Bearer token' }
-});
+async validateConservative(
+  input: AgentCard | string, 
+  options?: ValidationOptions
+): Promise<ValidationResult>
 ```
 
-## Types & Interfaces
+#### validateSchemaOnly()
 
-### AgentCard
+Schema validation without network requests.
 
 ```typescript
-interface AgentCard {
-  protocolVersion: string;
-  name: string;
-  description: string;
-  url: string;
-  preferredTransport: TransportProtocol;
-  additionalInterfaces?: AgentInterface[];
-  provider: AgentProvider;
-  iconUrl?: string;
-  version: string;
-  documentationUrl?: string;
-  capabilities?: AgentCapabilities;
-  securitySchemes?: Record<string, SecurityScheme>;
-  security?: Array<Record<string, string[]>>;
-  defaultInputModes?: string[];
-  defaultOutputModes?: string[];
-  skills?: AgentSkill[];
-  supportsAuthenticatedExtendedCard?: boolean;
-  signatures?: AgentCardSignature[];
-  extensions?: AgentExtension[];
-}
+async validateSchemaOnly(
+  card: AgentCard, 
+  options?: ValidationOptions
+): Promise<ValidationResult>
 ```
 
-### ValidationResult
+**Example:**
 
 ```typescript
-interface ValidationResult {
-  success: boolean;
-  score: number;
-  errors: ValidationError[];
-  warnings: ValidationWarning[];
-  suggestions: ValidationSuggestion[];
-  validations: ValidationCheck[];
-  versionInfo?: VersionInfo;
-}
+import { readFileSync } from 'fs';
+
+const cardJson = JSON.parse(readFileSync('./agent-card.json', 'utf8'));
+const result = await validator.validateSchemaOnly(cardJson);
 ```
 
+---
+
+## Types
+
 ### ValidationOptions
 
 ```typescript
 interface ValidationOptions {
-  transport?: TransportProtocol | 'all';
-  strictness?: ValidationStrictness;
-  a2aVersion?: string;
-  timeout?: number;
-  compliance?: boolean;
-  registryReady?: boolean;
-  testMessage?: string;
-  skipDynamic?: boolean;
-  suggestions?: boolean;
-  showVersionCompat?: boolean;
+  strictness?: 'strict' | 'progressive' | 'conservative';
+  timeout?: number;                    // HTTP timeout in ms (default: 10000)
+  skipDynamic?: boolean;               // Skip network requests
+  skipSignatureVerification?: boolean; // Skip JWS verification
+  verbose?: boolean;                   // Enable detailed logging
+  registryReady?: boolean;             // Check registry readiness
+  showVersionCompat?: boolean;         // Include version analysis
 }
 ```
 
-### ValidationStrictness
-
-```typescript
-type ValidationStrictness = 'strict' | 'progressive' | 'conservative';
-```
-
-### TransportProtocol
+### ValidationResult
 
 ```typescript
-type TransportProtocol = 'JSONRPC' | 'GRPC' | 'HTTP+JSON';
+interface ValidationResult {
+  success: boolean;           // Overall pass/fail
+  score: number;              // 0-100 score
+  errors: ValidationError[];  // Blocking issues
+  warnings: ValidationWarning[];
+  suggestions: ValidationSuggestion[];
+  validations: ValidationCheck[];
+  versionInfo?: VersionValidationInfo;
+  scoringResult?: ScoringResult;
+}
 ```
 
 ### ValidationError
 
 ```typescript
 interface ValidationError {
-  code: string;
-  message: string;
-  field?: string;
+  code: string;        // e.g., 'SCHEMA_VALIDATION_ERROR'
+  message: string;     // Human-readable description
+  field?: string;      // JSON path (e.g., 'skills.0.id')
   severity: 'error';
-  fixable?: boolean;
+  fixable?: boolean;   // Can be auto-fixed
 }
 ```
 
@@ -216,32 +209,67 @@ interface ValidationWarning {
 }
 ```
 
-### ValidationSuggestion
+### ValidationCheck
 
 ```typescript
-interface ValidationSuggestion {
-  id: string;
+interface ValidationCheck {
+  id: string;                              // e.g., 'schema_validation'
+  name: string;                            // e.g., 'Schema Validation'
+  status: 'passed' | 'failed' | 'skipped';
   message: string;
-  severity: 'info';
-  impact?: string;
-  fixable?: boolean;
+  duration?: number;                       // ms
+  details?: string;
 }
 ```
 
-### ValidationCheck
+### AgentCard
+
+Full A2A v0.3.0 agent card type:
 
 ```typescript
-interface ValidationCheck {
-  id: string;
+interface AgentCard {
+  // Required fields
+  protocolVersion: string;
   name: string;
-  status: 'passed' | 'failed' | 'skipped';
-  message: string;
-  duration?: number;
-  details?: string;
+  description: string;
+  url: string;
+  version: string;
+  capabilities: AgentCapabilities;
+  defaultInputModes: string[];
+  defaultOutputModes: string[];
+  skills: AgentSkill[];
+  
+  // Optional fields
+  preferredTransport?: 'JSONRPC' | 'GRPC' | 'HTTP+JSON';
+  additionalInterfaces?: AgentInterface[];
+  provider?: AgentProvider;
+  iconUrl?: string;
+  documentationUrl?: string;
+  securitySchemes?: Record<string, SecurityScheme>;
+  security?: Array<Record<string, string[]>>;
+  supportsAuthenticatedExtendedCard?: boolean;
+  signatures?: AgentCardSignature[];
+  extensions?: AgentExtension[];
+}
+```
+
+### AgentSkill
+
+```typescript
+interface AgentSkill {
+  id: string;           // Required, unique
+  name: string;         // Required, max 200 chars
+  description: string;  // Required, max 2000 chars
+  tags: string[];       // Required, at least one
+  examples?: string[];
+  inputModes?: string[];
+  outputModes?: string[];
 }
 ```
 
-### HttpClient Interface
+### HttpClient
+
+Interface for custom HTTP clients:
 
 ```typescript
 interface HttpClient {
@@ -261,209 +289,123 @@ interface HttpResponse {
 }
 ```
 
-## Validation Options
-
-### Strictness Levels
-
-| Level | Description | Use Case |
-|-------|-------------|----------|
-| `strict` | Full compliance, zero tolerance | Production deployment |
-| `progressive` | Balanced validation with warnings | Development, CI/CD |
-| `conservative` | Minimal requirements only | Early development |
-
-### Common Options
-
-```typescript
-const options: ValidationOptions = {
-  strictness: 'progressive',    // Validation level
-  timeout: 10000,              // HTTP timeout in ms
-  skipDynamic: false,          // Skip network calls
-  registryReady: false,        // Registry deployment checks
-  showVersionCompat: true      // Detailed version analysis
-};
-```
-
-## Error Handling
-
-### Error Types
-
-```typescript
-// Validation errors
-if (!result.success) {
-  result.errors.forEach(error => {
-    console.error(`${error.code}: ${error.message}`);
-    if (error.field) {
-      console.error(`Field: ${error.field}`);
-    }
-  });
-}
-
-// HTTP errors
-try {
-  const result = await validator.validate('https://invalid-url.com');
-} catch (error) {
-  if (error instanceof HttpError) {
-    console.error(`HTTP ${error.status}: ${error.message}`);
-  }
-}
-```
-
-### Error Codes
-
-- `SCHEMA_VALIDATION_ERROR`: Schema validation failed
-- `VERSION_MISMATCH_ERROR`: Version compatibility issues
-- `VALIDATION_FAILED`: General validation failure
-- `ENDPOINT_UNREACHABLE`: Network connectivity issues
-- `NOT_FOUND`: Agent card not found
-- `TIMEOUT`: Request timeout
+---
 
 ## Examples
 
-### Basic Validation
+### Express Middleware
 
 ```typescript
-import { A2AValidator } from 'capiscio-cli';
+import express from 'express';
+import { A2AValidator } from 'capiscio';
 
+const app = express();
 const validator = new A2AValidator();
 
-// Validate local file
-const result = await validator.validate('./agent.json');
-console.log(`Validation ${result.success ? 'passed' : 'failed'}`);
-console.log(`Score: ${result.score}/100`);
-
-// Validate URL
-const urlResult = await validator.validate('https://api.example.com');
-if (!urlResult.success) {
-  urlResult.errors.forEach(error => {
-    console.error(`Error: ${error.message}`);
+app.post('/validate', express.json(), async (req, res) => {
+  const result = await validator.validate(req.body);
+  
+  res.json({
+    valid: result.success,
+    score: result.score,
+    errors: result.errors,
+    warnings: result.warnings
   });
-}
-```
-
-### Strict Validation for Production
-
-```typescript
-const validator = new A2AValidator();
-
-const result = await validator.validateStrict('./agent.json', {
-  registryReady: true,
-  timeout: 15000
 });
-
-if (result.success) {
-  console.log('✅ Agent ready for production deployment!');
-} else {
-  console.log('❌ Agent failed production validation:');
-  result.errors.forEach(error => {
-    console.log(`  • ${error.message}`);
-  });
-  process.exit(1);
-}
 ```
 
-### Schema-Only Validation
+### Batch Validation
 
 ```typescript
+import { A2AValidator } from 'capiscio';
+import { glob } from 'glob';
+
 const validator = new A2AValidator();
-const agentCard = JSON.parse(fs.readFileSync('./agent.json', 'utf8'));
+const files = await glob('./agents/**/*.json');
 
-const result = await validator.validateSchemaOnly(agentCard);
+const results = await Promise.all(
+  files.map(async (file) => ({
+    file,
+    result: await validator.validate(file)
+  }))
+);
 
-if (result.success) {
-  console.log('Schema validation passed');
-} else {
-  console.log('Schema issues found:');
-  result.errors.forEach(error => {
-    console.log(`  ${error.field}: ${error.message}`);
+// Summary
+const passed = results.filter(r => r.result.success).length;
+console.log(`${passed}/${results.length} agents passed validation`);
+
+// Failed agents
+results
+  .filter(r => !r.result.success)
+  .forEach(r => {
+    console.log(`❌ ${r.file}:`);
+    r.result.errors.forEach(e => console.log(`   ${e.message}`));
   });
-}
 ```
 
 ### Custom HTTP Client
 
 ```typescript
-class CustomHttpClient implements HttpClient {
+import { A2AValidator, HttpClient, HttpResponse } from 'capiscio';
+
+class AuthenticatedClient implements HttpClient {
+  constructor(private token: string) {}
+  
   async get(url: string, options?: RequestOptions): Promise<HttpResponse> {
-    // Custom implementation with authentication, retries, etc.
     const response = await fetch(url, {
       headers: {
-        'Authorization': 'Bearer ' + process.env.API_TOKEN,
+        'Authorization': `Bearer ${this.token}`,
         ...options?.headers
-      }
+      },
+      signal: options?.signal
     });
     
     return {
       status: response.status,
       data: await response.json(),
-      headers: Object.fromEntries(response.headers.entries())
+      headers: Object.fromEntries(response.headers)
     };
   }
 }
 
-const validator = new A2AValidator(new CustomHttpClient());
-const result = await validator.validate('https://protected-api.example.com');
+const validator = new A2AValidator(
+  new AuthenticatedClient(process.env.API_TOKEN!)
+);
 ```
 
-### CI/CD Integration
+### Error Code Reference
 
-```typescript
-// ci-validation.js
-import { A2AValidator } from 'capiscio-cli';
-
-const validator = new A2AValidator();
-
-const result = await validator.validate('./dist/agent.json', {
-  strictness: 'progressive',
-  skipDynamic: true  // No network calls in CI
-});
+| Code | Description |
+|------|-------------|
+| `SCHEMA_VALIDATION_ERROR` | Required field missing or invalid type |
+| `VERSION_MISMATCH_ERROR` | Protocol version incompatibility |
+| `SIGNATURE_VERIFICATION_FAILED` | JWS signature invalid |
+| `PRIMARY_ENDPOINT_UNREACHABLE` | Main URL not responding |
+| `TRANSPORT_URL_CONFLICT` | Conflicting transport declarations |
+| `JSONRPC_ENDPOINT_ERROR` | JSON-RPC protocol test failed |
 
-// Output for CI systems
-console.log(JSON.stringify({
-  success: result.success,
-  score: result.score,
-  errors: result.errors.length,
-  warnings: result.warnings.length
-}, null, 2));
+---
 
-process.exit(result.success ? 0 : 1);
-```
+## Exports
 
-### Batch Validation
+The package exports these items:
 
 ```typescript
-import { A2AValidator } from 'capiscio-cli';
-import { glob } from 'glob';
-
-const validator = new A2AValidator();
-const agentFiles = await glob('./agents/**/*.json');
-
-const results = await Promise.all(
-  agentFiles.map(async (file) => {
-    const result = await validator.validate(file);
-    return {
-      file,
-      success: result.success,
-      score: result.score,
-      errors: result.errors.length
-    };
-  })
-);
-
-// Report summary
-const passed = results.filter(r => r.success).length;
-const total = results.length;
-console.log(`Validation Summary: ${passed}/${total} agents passed`);
-
-// Report failures
-results.filter(r => !r.success).forEach(result => {
-  console.log(`❌ ${result.file}: ${result.errors} errors`);
-});
+// Classes
+export { A2AValidator } from './validator/a2a-validator';
+export { FetchHttpClient } from './validator/http-client';
+export { ValidateCommand } from './commands/validate';
+export { ConsoleOutput } from './output/console';
+export { JsonOutput } from './output/json';
+
+// Types
+export * from './types';
 ```
 
 ---
 
 ## See Also
 
-- **[Validation Process](../../concepts/validation.md)** - Detailed validation logic
-- **[Scoring System](../../concepts/scoring.md)** - How scores are calculated
-- **[Architecture](./architecture.md)** - Internal implementation details
+- [CLI Reference](./cli.md) - Command-line usage
+- [Scoring System](./scoring.md) - Understanding validation scores
+- [Programmatic Usage](./programmatic-usage.md) - Integration patterns
diff --git a/docs/reference/architecture.md b/docs/reference/architecture.md
deleted file mode 100644
index 248f9c3..0000000
--- a/docs/reference/architecture.md
+++ /dev/null
@@ -1,450 +0,0 @@
-# 🏛️ Architecture Documentation
-
-> **Internal architecture and design decisions for CapiscIO CLI**
-
-## Design Philosophy
-
-**Core Principles:**
-
-- ✅ **Zero External Dependencies**: No reliance on external validator services
-- ✅ **Modularity**: Clean separation of concerns for easy maintenance
-- ✅ **Extensibility**: Simple to add new validation rules
-- ✅ **Performance**: Efficient validation with minimal overhead
-- ✅ **Reliability**: Comprehensive error handling and graceful degradation
-
-This document outlines the internal architecture, design patterns, and technical decisions behind the CapiscIO CLI validation system.
-
-## 📚 Table of Contents
-
-- [Overview](#overview)
-- [Core Components](#core-components)
-- [Data Flow](#data-flow)
-- [Design Patterns](#design-patterns)
-- [Dependency Management](#dependency-management)
-- [Performance Considerations](#performance-considerations)
-- [Extensibility](#extensibility)
-
-## Overview
-
-The CapiscIO CLI is designed as a self-contained, performant validation tool for A2A protocol agent cards. The architecture prioritizes:
-
-- **Zero External Dependencies**: No reliance on external validator services
-- **Modularity**: Clean separation of concerns
-- **Extensibility**: Easy to add new validation rules
-- **Performance**: Efficient validation with minimal overhead
-- **Reliability**: Comprehensive error handling and graceful degradation
-
-## Core Components
-
-### Component Diagram
-
-```mermaid
-graph TB
-    CLI[CLI Layer<br/>cli.ts<br/>Command Registration]
-    CMD[Commands<br/>validate.ts<br/>ValidateCmd]
-    OUT[Output<br/>console.ts<br/>json.ts]
-    
-    UTIL[Utilities<br/>file-utils.ts<br/>semver.ts]
-    VAL[Validator<br/>a2a-validator.ts]
-    HTTP[HTTP Client<br/>http-client.ts]
-    
-    TYPES[Type System<br/>AgentCard, ValidationResult<br/>ValidationOptions, ValidationError<br/>TransportProtocol, CLIOptions]
-    
-    CLI --> CMD
-    CMD --> OUT
-    CMD --> VAL
-    VAL --> UTIL
-    VAL --> HTTP
-    CLI -.-> TYPES
-    CMD -.-> TYPES
-    VAL -.-> TYPES
-    OUT -.-> TYPES
-```
-
-### Layer Responsibilities
-
-#### 1. CLI Layer (`src/cli.ts`)
-- Entry point and command registration
-- Global error handling
-- Version management
-- Commander.js integration
-
-#### 2. Command Layer (`src/commands/`)
-- Command-specific logic
-- Option parsing and validation
-- User interaction (spinners, prompts)
-- Result formatting coordination
-
-#### 3. Validator Layer (`src/validator/`)
-- Core validation logic
-- Schema validation
-- Version compatibility checking
-- Network endpoint testing
-
-#### 4. Output Layer (`src/output/`)
-- Result formatting and display
-- Console output with colors and styling
-- JSON output for CI/CD integration
-
-#### 5. Utility Layer (`src/utils/`)
-- File system operations
-- Semver utilities
-- Helper functions
-
-#### 6. Type Layer (`src/types/`)
-- TypeScript type definitions
-- Interface contracts
-- Type safety enforcement
-
-## Data Flow
-
-### Validation Flow Diagram
-
-```mermaid
-graph TB
-    USER[User Input] --> PARSE[Command Parser]
-    PARSE --> RESOLVE[Input Resolution<br/>File or URL Detection]
-    RESOLVE --> LOAD[Load Agent Card Data]
-    LOAD --> VALIDATOR[A2A Validator]
-    
-    VALIDATOR --> SCHEMA[Schema Validation]
-    VALIDATOR --> VERSION[Version Compatibility]
-    VALIDATOR --> NETWORK[Network Testing]
-    
-    SCHEMA --> RESULT[Validation Result]
-    VERSION --> RESULT
-    NETWORK --> RESULT
-    
-    RESULT --> FORMATTER[Output Formatter]
-    FORMATTER --> OUTPUT[Console or JSON Output]
-```
-
-### Processing Pipeline
-
-1. **Input Processing**
-   - Parse CLI arguments
-   - Resolve input type (file/URL/auto-detect)
-   - Load agent card data
-
-2. **Validation Pipeline**
-   - Schema validation
-   - Version compatibility analysis
-   - Network endpoint testing (if applicable)
-   - Feature detection and warnings
-
-3. **Result Aggregation**
-   - Collect errors, warnings, suggestions
-   - Calculate validation score
-   - Generate timing metrics
-
-4. **Output Generation**
-   - Format results for console or JSON
-   - Apply styling and colors
-   - Display actionable feedback
-
-## Design Patterns
-
-### 1. Strategy Pattern (Validation Modes)
-
-```typescript
-// Validation strategies
-interface ValidationStrategy {
-  validate(card: AgentCard): ValidationResult;
-}
-
-class ProgressiveStrategy implements ValidationStrategy {
-  validate(card: AgentCard): ValidationResult {
-    // Progressive validation logic
-  }
-}
-
-class StrictStrategy implements ValidationStrategy {
-  validate(card: AgentCard): ValidationResult {
-    // Strict validation logic
-  }
-}
-```
-
-### 2. Dependency Injection (HTTP Client)
-
-```typescript
-class A2AValidator {
-  constructor(private httpClient: HttpClient = new FetchHttpClient()) {
-    // Allows custom HTTP client injection for testing
-  }
-}
-```
-
-### 3. Factory Pattern (Output Formatters)
-
-```typescript
-function createOutputFormatter(format: 'json' | 'console'): OutputFormatter {
-  return format === 'json' ? new JsonOutput() : new ConsoleOutput();
-}
-```
-
-### 4. Command Pattern (CLI Commands)
-
-```typescript
-abstract class Command {
-  abstract execute(args: string[], options: CLIOptions): Promise<void>;
-}
-
-class ValidateCommand extends Command {
-  async execute(args: string[], options: CLIOptions): Promise<void> {
-    // Validation command implementation
-  }
-}
-```
-
-### 5. Builder Pattern (Validation Options)
-
-```typescript
-class ValidationOptionsBuilder {
-  private options: ValidationOptions = {};
-  
-  strictness(level: ValidationStrictness): this {
-    this.options.strictness = level;
-    return this;
-  }
-  
-  timeout(ms: number): this {
-    this.options.timeout = ms;
-    return this;
-  }
-  
-  build(): ValidationOptions {
-    return { ...this.options };
-  }
-}
-```
-
-## Dependency Management
-
-### Production Dependencies
-
-| Package | Purpose | Justification |
-|---------|---------|---------------|
-| `commander` | CLI framework | Industry standard, well-maintained |
-| `chalk` | Console colors | Enhanced user experience |
-| `ora` | Loading spinners | Visual feedback for long operations |
-| `inquirer` | Interactive prompts | Future extension capability |
-| `glob` | File pattern matching | Auto-detection functionality |
-
-### Zero External Service Dependencies
-
-- **No axios**: Uses native `fetch()` API
-- **No semver package**: Custom lightweight implementation
-- **No external validators**: Embedded validation logic
-- **No cloud services**: Completely self-contained
-
-### Bundle Size Optimization
-
-```bash
-# Production bundle analysis
-npm run build
-
-# Outputs:
-# dist/cli.js     ~27KB (minified)
-# dist/index.js   ~26KB (library)
-# dist/index.d.ts ~7KB  (types)
-```
-
-## Performance Considerations
-
-### Optimization Strategies
-
-1. **Lazy Loading**
-   ```typescript
-   // Only load validation rules when needed
-   const loadValidationRules = () => import('./validation-rules');
-   ```
-
-2. **Caching**
-   ```typescript
-   // Cache semver comparisons
-   const versionCache = new Map<string, boolean>();
-   ```
-
-3. **Early Termination**
-   ```typescript
-   // Stop validation on critical errors
-   if (criticalError) {
-     return { success: false, errors: [criticalError] };
-   }
-   ```
-
-4. **Parallel Processing**
-   ```typescript
-   // Validate multiple aspects concurrently
-   const [schemaResult, versionResult] = await Promise.all([
-     validateSchema(card),
-     validateVersion(card)
-   ]);
-   ```
-
-### Memory Management
-
-- Streaming JSON parsing for large files
-- Cleanup of HTTP connections
-- Garbage collection-friendly patterns
-
-### Performance Benchmarks
-
-| Operation | Average Time | Memory Usage |
-|-----------|--------------|---------------|
-| Schema validation | 1-10ms | 1-5MB |
-| Network request | 50-500ms | 1-2MB |
-| File parsing | 1-5ms | 1-3MB |
-| Total validation | 100-1000ms | 5-15MB |
-
-## Extensibility
-
-### Adding New Validation Rules
-
-```typescript
-// src/validator/rules/custom-rule.ts
-export class CustomValidationRule {
-  validate(card: AgentCard): ValidationError[] {
-    const errors: ValidationError[] = [];
-    
-    // Custom validation logic
-    if (customCondition(card)) {
-      errors.push({
-        code: 'CUSTOM_ERROR',
-        message: 'Custom validation failed',
-        severity: 'error'
-      });
-    }
-    
-    return errors;
-  }
-}
-
-// Register in validator
-validator.addRule(new CustomValidationRule());
-```
-
-### Custom Output Formatters
-
-```typescript
-// src/output/xml-output.ts
-export class XmlOutput implements OutputFormatter {
-  display(result: ValidationResult): void {
-    const xml = this.convertToXml(result);
-    console.log(xml);
-  }
-  
-  private convertToXml(result: ValidationResult): string {
-    // XML conversion logic
-  }
-}
-```
-
-### Plugin Architecture (Future)
-
-```typescript
-// Future plugin system design
-interface ValidationPlugin {
-  name: string;
-  version: string;
-  validate(card: AgentCard, options: ValidationOptions): Promise<PluginResult>;
-}
-
-class PluginManager {
-  private plugins: ValidationPlugin[] = [];
-  
-  register(plugin: ValidationPlugin): void {
-    this.plugins.push(plugin);
-  }
-  
-  async runPlugins(card: AgentCard): Promise<PluginResult[]> {
-    return Promise.all(
-      this.plugins.map(plugin => plugin.validate(card, {}))
-    );
-  }
-}
-```
-
-### Configuration System (Future)
-
-```typescript
-// .capiscio.config.js
-export default {
-  validation: {
-    strictness: 'progressive',
-    timeout: 10000,
-    rules: {
-      'schema-validation': { enabled: true },
-      'version-compatibility': { enabled: true },
-      'custom-rule': { enabled: false }
-    }
-  },
-  output: {
-    format: 'console',
-    colors: true,
-    verbose: false
-  }
-};
-```
-
-## Testing Architecture
-
-### Test Structure
-
-```
-tests/
-├── unit/
-│   ├── validator.test.ts
-│   ├── http-client.test.ts
-│   └── utils.test.ts
-├── integration/
-│   ├── cli.test.ts
-│   └── end-to-end.test.ts
-└── fixtures/
-    ├── valid-agents/
-    └── invalid-agents/
-```
-
-### Testing Patterns
-
-1. **Unit Tests**: Individual component testing
-2. **Integration Tests**: Component interaction testing
-3. **E2E Tests**: Full CLI workflow testing
-4. **Mock Strategy**: HTTP client mocking for network tests
-
----
-
-## See Also
-
-- **[Validation Process](../../concepts/validation.md)** - What gets validated
-- **[Scoring System](../../concepts/scoring.md)** - How validation results become scores
-- **[API Reference](./api.md)** - Public API surface
-- **[GitHub Repository](https://github.com/capiscio/capiscio-cli)** - Extend the validator
-
-!!! tip "Building an Agent?"
-    This document is for extending capiscio-cli. If you're building an A2A agent, see [CapiscIO Python SDK](../../capiscio-python-sdk/index.md) for runtime protection.
-
-## Maintenance & Evolution
-
-### Version Management
-
-- Semantic versioning for public API
-- Internal API versioning for extensions
-- Backward compatibility guarantees
-
-### Code Quality
-
-- TypeScript strict mode
-- ESLint with custom rules
-- Automated testing in CI
-- Code coverage requirements
-
-### Performance Monitoring
-
-- Validation timing metrics
-- Memory usage tracking
-- Bundle size monitoring
-- Performance regression testing
-
-This architecture provides a solid foundation for the current CLI while enabling future growth and extensibility.
\ No newline at end of file
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
new file mode 100644
index 0000000..012dc41
--- /dev/null
+++ b/docs/reference/cli.md
@@ -0,0 +1,138 @@
+---
+title: CLI Reference
+description: Command-line reference for the capiscio npm package.
+---
+
+# CLI Reference
+
+Complete reference for the `capiscio` command-line interface.
+
+---
+
+## validate
+
+Validate an A2A agent card from a file or URL.
+
+```bash
+capiscio validate [input] [options]
+```
+
+### Arguments
+
+| Argument | Description |
+|----------|-------------|
+| `input` | Path to agent-card.json, URL, or omit to auto-detect |
+
+### Options
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--strict` | boolean | false | Strict validation mode |
+| `--progressive` | boolean | true | Progressive validation (default) |
+| `--schema-only` | boolean | false | Validate schema only, skip network requests |
+| `--skip-signature` | boolean | false | Skip JWS signature verification |
+| `--test-live` | boolean | false | Test live agent endpoint |
+| `--registry-ready` | boolean | false | Check registry deployment readiness |
+| `--json` | boolean | false | Output results as JSON |
+| `--errors-only` | boolean | false | Show only errors and warnings |
+| `--verbose` | boolean | false | Show detailed validation steps |
+| `--timeout <ms>` | string | 10000 | Request timeout in milliseconds |
+
+---
+
+## Examples
+
+### Basic Validation
+
+```bash
+# Local file
+capiscio validate ./agent-card.json
+
+# Remote agent (auto-discovers /.well-known/agent-card.json)
+capiscio validate https://my-agent.example.com
+
+# Auto-detect in current directory
+capiscio validate
+```
+
+### Validation Modes
+
+```bash
+# Progressive (default) - warnings for issues
+capiscio validate ./agent-card.json
+
+# Strict - warnings become errors
+capiscio validate ./agent-card.json --strict
+
+# Schema only - no network requests
+capiscio validate ./agent-card.json --schema-only
+```
+
+### CI/CD
+
+```bash
+# JSON output for parsing
+capiscio validate ./agent-card.json --json
+
+# Production pipeline
+capiscio validate ./agent-card.json --strict --json
+```
+
+### Live Testing
+
+```bash
+# Test endpoint responds correctly
+capiscio validate https://agent.example.com --test-live
+
+# With custom timeout
+capiscio validate https://agent.example.com --test-live --timeout 15000
+```
+
+---
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| 0 | Validation passed |
+| 1 | Validation failed |
+
+---
+
+## JSON Output
+
+When using `--json`, output follows this structure:
+
+```json
+{
+  "success": true,
+  "score": 95,
+  "errors": [],
+  "warnings": [
+    {
+      "code": "NO_SIGNATURES_FOUND",
+      "message": "No signatures present",
+      "severity": "warning"
+    }
+  ],
+  "validations": [
+    {
+      "id": "schema_validation",
+      "status": "passed",
+      "message": "Agent card conforms to A2A v0.3.0"
+    }
+  ],
+  "scoringResult": {
+    "compliance": { "total": 95, "rating": "Excellent" },
+    "trust": { "total": 80, "rating": "Good" },
+    "availability": null
+  }
+}
+```
+
+---
+
+## See Also
+
+- [capiscio-core CLI](../../reference/cli/index.md) - Full CLI documentation
+- [validate-a2a](https://github.com/capiscio/validate-a2a) - GitHub Action
diff --git a/mkdocs.yml b/mkdocs.yml
index c224907..b43d980 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -90,5 +90,4 @@ nav:
       - Programmatic Usage: guides/programmatic-usage.md
       - Scoring: guides/scoring.md
   - Reference:
-      - API Reference: reference/api.md
-      - Architecture: reference/architecture.md
+      - CLI Reference: reference/cli.md

From afc0682ffd4bc43d0134b344c455d60ee74b7b91 Mon Sep 17 00:00:00 2001
From: Beon de Nood <beon@bigdune.net>
Date: Tue, 2 Dec 2025 11:51:56 -0500
Subject: [PATCH 3/3] fix: address PR review comments
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- Fix broken links in api.md (scoring.md, programmatic-usage.md → guides folder)
- Fix command injection vulnerability: replace execSync with spawnSync
- Fix async example: replace exec with spawn
- Fix Express middleware: use spawnSync instead of execSync
- Fix emoji encoding issue (�� → 🔐) in scoring.md
- Remove broken getting-started link in scoring.md
- Fix circular reference in cli.md See Also section
- Remove irrelevant Python SDK reference from Node.js docs
---
 docs/guides/programmatic-usage.md | 75 ++++++++++++++++---------------
 docs/guides/scoring.md            | 23 ++--------
 docs/index.md                     | 18 ++++----
 docs/reference/api.md             |  4 +-
 docs/reference/cli.md             |  5 ++-
 5 files changed, 55 insertions(+), 70 deletions(-)

diff --git a/docs/guides/programmatic-usage.md b/docs/guides/programmatic-usage.md
index 3d65a54..319225b 100644
--- a/docs/guides/programmatic-usage.md
+++ b/docs/guides/programmatic-usage.md
@@ -12,7 +12,7 @@ For Node.js applications that need validation results, spawn the CLI with `--jso
 ## Basic Example
 
 ```typescript
-import { execSync } from 'child_process';
+import { spawnSync } from 'child_process';
 
 interface ValidationResult {
   success: boolean;
@@ -22,19 +22,17 @@ interface ValidationResult {
 }
 
 function validate(path: string): ValidationResult {
-  try {
-    const output = execSync(`npx capiscio validate "${path}" --json`, {
-      encoding: 'utf8',
-      stdio: ['pipe', 'pipe', 'pipe']
-    });
-    return JSON.parse(output);
-  } catch (error: any) {
-    // CLI exits with code 1 on validation failure, but still outputs JSON
-    if (error.stdout) {
-      return JSON.parse(error.stdout);
-    }
-    throw error;
+  const result = spawnSync('npx', ['capiscio', 'validate', path, '--json'], {
+    encoding: 'utf8',
+    stdio: ['pipe', 'pipe', 'pipe']
+  });
+  
+  // CLI may exit with code 1 on validation failure but still outputs valid JSON
+  const output = result.stdout || '';
+  if (!output) {
+    throw new Error(`Validation failed: ${result.stderr}`);
   }
+  return JSON.parse(output);
 }
 
 // Usage
@@ -47,21 +45,26 @@ console.log(`Valid: ${result.success}, Score: ${result.score}`);
 ## Async Version
 
 ```typescript
-import { exec } from 'child_process';
-import { promisify } from 'util';
-
-const execAsync = promisify(exec);
-
-async function validateAsync(path: string): Promise<ValidationResult> {
-  try {
-    const { stdout } = await execAsync(`npx capiscio validate "${path}" --json`);
-    return JSON.parse(stdout);
-  } catch (error: any) {
-    if (error.stdout) {
-      return JSON.parse(error.stdout);
-    }
-    throw error;
-  }
+import { spawn } from 'child_process';
+
+function validateAsync(path: string): Promise<ValidationResult> {
+  return new Promise((resolve, reject) => {
+    const child = spawn('npx', ['capiscio', 'validate', path, '--json']);
+    let stdout = '';
+    let stderr = '';
+    
+    child.stdout.on('data', (data) => { stdout += data; });
+    child.stderr.on('data', (data) => { stderr += data; });
+    
+    child.on('close', (code) => {
+      // CLI may exit with code 1 on validation failure but still outputs valid JSON
+      if (stdout) {
+        resolve(JSON.parse(stdout));
+      } else {
+        reject(new Error(stderr || 'Validation failed'));
+      }
+    });
+  });
 }
 ```
 
@@ -101,7 +104,7 @@ await validateAll('./agents/**/*.json');
 
 ```typescript
 import express from 'express';
-import { execSync } from 'child_process';
+import { spawnSync } from 'child_process';
 import { writeFileSync, unlinkSync } from 'fs';
 import { randomUUID } from 'crypto';
 
@@ -114,15 +117,15 @@ app.post('/api/validate', (req, res) => {
   writeFileSync(tempFile, JSON.stringify(req.body));
   
   try {
-    const output = execSync(`npx capiscio validate "${tempFile}" --json`, {
+    const result = spawnSync('npx', ['capiscio', 'validate', tempFile, '--json'], {
       encoding: 'utf8'
     });
-    res.json(JSON.parse(output));
-  } catch (error: any) {
-    if (error.stdout) {
-      res.json(JSON.parse(error.stdout));
+    
+    const output = result.stdout || '';
+    if (output) {
+      res.json(JSON.parse(output));
     } else {
-      res.status(500).json({ error: 'Validation failed' });
+      res.status(500).json({ error: result.stderr || 'Validation failed' });
     }
   } finally {
     unlinkSync(tempFile);
@@ -141,4 +144,4 @@ The `capiscio` npm package is a **distribution wrapper** for the Go-based valida
 - ✅ Keeps the npm package lightweight
 - ✅ Single source of truth for validation logic
 
-For deep TypeScript integration, consider using the [capiscio-sdk-python](../../reference/sdk-python/index.md) pattern with your own HTTP middleware.
+For native TypeScript integration, the spawning patterns shown above provide full access to all CLI features with proper error handling.
diff --git a/docs/guides/scoring.md b/docs/guides/scoring.md
index 250fc1a..0a9f9b8 100644
--- a/docs/guides/scoring.md
+++ b/docs/guides/scoring.md
@@ -7,7 +7,7 @@
 CapiscIO CLI uses a three-dimensional scoring system to evaluate agent cards:
 
 - **📄 Compliance (0-100)** - Protocol adherence and format validation (`complianceScore`)
-- **�� Trust (0-100)** - Security practices and cryptographic verification (`trustScore`)
+- **🔐 Trust (0-100)** - Security practices and cryptographic verification (`trustScore`)
 - **🚀 Availability (0-100)** - Operational readiness *(only with `--test-live`)*
 
 ---
@@ -300,22 +300,5 @@ fi
 
 ## See Also
 
-<div class="grid cards" markdown>
-
--   **📖 CLI Reference**
-
-    ---
-
-    Complete command-line reference and options.
-
-    [:octicons-arrow-right-24: CLI Docs](../reference/cli.md)
-
--   **⚡ Quick Start**
-
-    ---
-
-    Get started with CapiscIO CLI in 5 minutes.
-
-    [:octicons-arrow-right-24: Quick Start](../getting-started/installation.md)
-
-</div>
+- [CLI Reference](../reference/cli.md) - Complete command-line reference and options
+- [Programmatic Usage](./programmatic-usage.md) - Use the CLI from Node.js applications
diff --git a/docs/index.md b/docs/index.md
index bbc3ee0..ce56074 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -134,18 +134,16 @@ validate:
 For Node.js applications that need validation results programmatically, spawn the CLI with JSON output:
 
 ```typescript
-import { execSync } from 'child_process';
+import { spawnSync } from 'child_process';
 
 function validateAgentCard(path: string) {
-  try {
-    const output = execSync(`npx capiscio validate ${path} --json`, {
-      encoding: 'utf8'
-    });
-    return JSON.parse(output);
-  } catch (error: any) {
-    // CLI returns non-zero exit code on validation failure
-    return JSON.parse(error.stdout);
-  }
+  const result = spawnSync('npx', ['capiscio', 'validate', path, '--json'], {
+    encoding: 'utf8'
+  });
+  
+  // CLI may exit with code 1 on validation failure but still outputs valid JSON
+  const output = result.stdout || result.stderr;
+  return JSON.parse(output);
 }
 
 const result = validateAgentCard('./agent-card.json');
diff --git a/docs/reference/api.md b/docs/reference/api.md
index 4104371..844dd3a 100644
--- a/docs/reference/api.md
+++ b/docs/reference/api.md
@@ -407,5 +407,5 @@ export * from './types';
 ## See Also
 
 - [CLI Reference](./cli.md) - Command-line usage
-- [Scoring System](./scoring.md) - Understanding validation scores
-- [Programmatic Usage](./programmatic-usage.md) - Integration patterns
+- [Scoring System](../guides/scoring.md) - Understanding validation scores
+- [Programmatic Usage](../guides/programmatic-usage.md) - Integration patterns
diff --git a/docs/reference/cli.md b/docs/reference/cli.md
index 012dc41..e35d065 100644
--- a/docs/reference/cli.md
+++ b/docs/reference/cli.md
@@ -134,5 +134,6 @@ When using `--json`, output follows this structure:
 
 ## See Also
 
-- [capiscio-core CLI](../../reference/cli/index.md) - Full CLI documentation
-- [validate-a2a](https://github.com/capiscio/validate-a2a) - GitHub Action
+- [Scoring Guide](../guides/scoring.md) - Understanding validation scores
+- [Programmatic Usage](../guides/programmatic-usage.md) - Use the CLI from Node.js
+- [validate-a2a](https://github.com/capiscio/validate-a2a) - GitHub Action for CI/CD