# Glintbase Developer Documentation & Technical Reference Manual

The definitive specification for the Agent Readiness Standard (ARS 3.0), the Autonomous Multi-Agent Flight Simulator, the CLI v3.0 suite, and the 17-tool Model Context Protocol (MCP) server.

---

## 01. Quickstart — Auditing Agent Readiness

The fastest way to evaluate an API or documentation platform for AI coding agents is the hosted scanner or the CLI harness:

- **Hosted Scanner**: https://scan.glintbase.dev
- **CLI Quickstart**: `npx @glintbase/cli audit https://docs.example.com`
- **Hosted MCP Endpoint**: `https://scan.glintbase.dev/api/mcp`
- **Flight Simulator API**: `https://scan.glintbase.dev/api/simulate`

---

## 02. CLI Suite (`@glintbase/cli` v3.0.0)

Install globally via `npm i -g @glintbase/cli` or execute on-the-fly with `npx @glintbase/cli`. Requires Node.js >= 20.

### 1. `glintbase audit [target] [options]`
Executes the full 119-check ARS 3.0 audit with dynamic denominator mathematics.
```bash
# Audit any public website or API docs
npx @glintbase/cli audit https://api.stripe.com

# Audit local codebase with embedded Flight Simulator and strict score threshold
glintbase audit . --simulate --fail-under 85 --report audit-report.md
```
- `--simulate`: Spawns embedded Flight Simulator alongside audit.
- `--report <file>`: Exports executive Markdown report with remediation code diffs.
- `--fail-under <score>`: Exits with code 1 if score drops below threshold.
- `--json`: Outputs raw structured JSON telemetry.

### 2. `glintbase simulate [target] [options]`
Empirical multi-agent flight simulator testing whether real agent personas can navigate, ingest, and call tools.
```bash
# Simulate Claude Code persona (200k context)
glintbase simulate https://api.stripe.com --agent claude-code

# Test custom natural language intent
glintbase simulate . -i "Create an isolated tenant webhook and verify signature"
```
- `--agent <persona>`: Target persona: `claude-code` (200k), `cursor` (128k), `perplexity` (zero-JS).
- `-i, --intent <prompt>`: Custom mission goal mapped to OpenAPI/MCP operations.
- `--allow-mutations`: Authorizes live network mutations (safe dry-runs by default).
- `--live`: Runs live LLM agent instead of fast deterministic state machine.

### 3. `glintbase fix [target] [options]`
Autonomous AST code remediation engine synthesizing missing agent surfaces.
```bash
# Automatically scaffold missing llms.txt, auth.md, robots.txt, and stage Git PR
glintbase fix -y --branch glintbase/agent-readiness
```
- `-y, --yes`: Applies all AST recommendations automatically.
- `--branch <name>`: 1-Click Git PR staging (branch, commit, PR draft).
- `--dry-run`: Displays file diffs in-memory without modifying disk.

### 4. `glintbase ci [url|path] [options]`
Zero-drift CI/CD quality gate for GitHub Actions, GitLab CI, and CircleCI.
```bash
glintbase ci . --fail-under 80 --pr-drift --github-token ${{ secrets.GITHUB_TOKEN }}
```
- `--fail-under <score>`: Fails build if overall score drops below threshold.
- `--pr-drift`: Compares PR modifications against base branch and outputs diff table.

### 5. `glintbase mcp [options]`
Launches official Model Context Protocol server.
```bash
# Local stdio transport for Claude Code / Cursor
glintbase mcp

# Streamable HTTP SSE transport
glintbase mcp --http --port 3001

# Ephemeral Cloudflare Quick Tunnel for remote collaboration
glintbase mcp --share
```

---

## 03. Autonomous Agent Flight Simulator

The Flight Simulator evaluates real-world execution friction across three dimensions:

### 1. Persona Emulators
- **claude-code**: 200k token window, deep schema reasoning, multi-step dependency chaining.
- **cursor**: 128k token window, rapid semantic indexing, tight token budgeting.
- **perplexity**: Zero-JavaScript SSR crawler, strict markdown parser, anti-SPA canary detector.

### 2. Economic Telemetry (The Token Tax)
$$\text{Dollar Tax} = (\text{Tokens}_{\text{in}} \times \$3/1\text{M}) + (\text{Tokens}_{\text{out}} \times \$15/1\text{M})$$
Across 50 engineers relying on coding agents, documentation context bloat creates an average **$433,200 / year** token tax.

### 3. Schema Friction Index
Measures mismatch rate between OpenAPI parameter descriptions, actual JSON types, and ambiguous constraints before runtime. Friction > 0.25 triggers agent tool-use loops.

### 4. Multi-Modal Visual Experience
- **Inline SVG Journey Tree**: Rendered directly in chat via MCP `type: "image"` (`image/svg+xml`).
- **Compressed State URL**: Zlib-deflated base64url hash (`#data=...`) linking to the web replay cockpit.

---

## 04. ARS 3.0 Dynamic Denominator Scoring Mathematics

$$\text{Final Score} = \min\left(100, \operatorname{round}\left(\frac{S_{\text{base\_earned}} + S_{\text{bonus\_earned}}}{D_{\text{active}}} \times 100\right)\right)$$

Where active denominator:
$$D_{\text{active}} = D_{\text{archetype\_base}} + S_{\text{bonus\_earned}}$$

### Archetype Baselines ($D_{\text{archetype\_base}}$):
- `api_devtool`: 85 pts (APIs, SDKs, CLI tools, SaaS)
- `docs_kb`: 85 pts (Documentation hubs, Knowledge bases)
- `ecommerce`: 100 pts (Commerce APIs, transactional surfaces)
- `content_media`: 50 pts (Publishers, corporate blogs)

### Unpenalized Bonus Rule:
Bonus specifications (WorkOS `auth.md`, WebMCP, Google AP2) add 0 to the denominator when absent. When satisfied, points add to both numerator and denominator, granting full positive upside without penalty.

---

## 05. The 4 Operational Layers (119 Checks)

1. **Layer 1: Discovery & Entrypoints (16 checks)**: `robots.txt` AI crawler Allow rules, `/.well-known/ard.json`, canonical root resolution, Wikidata grounding.
2. **Layer 2: Access & Understanding (41 checks)**: Anti-SPA 404 soft-200 canaries, `/llms.txt`, No-JS SSR markdown content density, token tax ratio.
3. **Layer 3: Usability & Interoperability (56 checks)**: Streamable HTTP MCP, WorkOS `auth.md`, Schema Friction Index, mutation idempotency locks.
4. **Layer 4: Payments & Commerce (6 checks)**: Universal Commerce Protocol (UCP), x402 micropayments, zero-auth test sandboxes.

---

## 06. Official MCP Server (17 Tools & 9 Skills)

### Connection Options:
1. **Hosted Cloud**: `https://scan.glintbase.dev/api/mcp`
2. **Local Stdio**: `glintbase mcp`
3. **Cloudflare Quick Tunnel**: `glintbase mcp --share`

### 17 Production MCP Tools:
- `glintbase_audit`: Runs full 119-check ARS 3.0 audit.
- `glintbase_get_score`: Fast cached scorecard retrieval.
- `glintbase_discover_surfaces`: Discovers canonical agent entrypoints.
- `glintbase_simulate_flight`: Multi-turn simulation with SVG Journey Tree & replay hash.
- `glintbase_calculate_token_tax`: Measures prompt/completion token waste and dollar burn.
- `glintbase_check_schema_friction`: Evaluates OpenAPI/JSON schemas for ambiguity.
- `glintbase_counterfactual_proof`: In-memory sandbox proving score upside (+pts).
- `glintbase_generate_artifact`: Synthesizes living agent artifacts (llms.txt, auth.md, ard.json, canary).
- `glintbase_sandbox_validate`: Executes curl and SDK code snippets in micro-sandbox.
- `glintbase_inspect_webmcp`: Inspects client-side window.modelContext browser agent tools.
- `glintbase_ci_gate`: CI/CD PR drift gate evaluating branch diffs.
- `glintbase_compliance_report`: Generates executive compliance breakdown.
- `glintbase_audit_canaries`: Probes randomized routes to verify authentic HTTP 404.
- `glintbase_verify_agent_auth`: Validates WorkOS auth.md, RFC 9728 metadata.
- `glintbase_audit_mutation_safety`: Verifies Idempotency-Key headers and safe mutation locks.
- `glintbase_get_skill`: Retrieves complete skill instruction playbook by URI.
- `glintbase_install_skill`: Scaffolds skill playbook into `.agents/skills/` or `~/.claude/skills/`.

### 9 Bundled Agent Skills:
- `skill://glintbase/living-artifacts-architect`
- `skill://glintbase/webmcp-builder`
- `skill://glintbase/machine-auth-specialist`
- `skill://glintbase/token-tax-optimizer`
- `skill://glintbase/schema-friction-reducer`
- `skill://glintbase/agentic-canary-guard`
- `skill://glintbase/mutation-safety-engineer`
- `skill://glintbase/mcp-server-scaffolder`
- `skill://glintbase/ci-drift-enforcer`

---

## 07. Complete API Reference

### 1. `POST https://scan.glintbase.dev/api/mcp` (JSON-RPC 2.0)
Standard MCP 2024-11-05 endpoint. Rate limit: 60 req/min sliding-window per IP.
```bash
curl -X POST https://scan.glintbase.dev/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "glintbase_simulate_flight",
      "arguments": { "url": "https://docs.stripe.com", "agent": "claude-code" }
    }
  }'
```

### 2. `GET https://scan.glintbase.dev/api/mcp` (SSE Stream)
Persistent bidirectional Server-Sent Events stream.
```bash
curl -N -H "Accept: text/event-stream" https://scan.glintbase.dev/api/mcp
```

### 3. `POST https://scan.glintbase.dev/api/simulate`
Autonomous Multi-Agent Flight Simulator REST endpoint.
```bash
curl -X POST https://scan.glintbase.dev/api/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.stripe.com",
    "agent": "claude-code",
    "intent": "Create customer and attach payment method"
  }'
```

### 4. `POST https://scan.glintbase.dev/api/scan`
Triggers real-time ARS 3.0 audit across 119 checks.
```bash
curl -X POST https://scan.glintbase.dev/api/scan \
  -H "Content-Type: application/json" \
  -d '{ "url": "https://docs.anthropic.com" }'
```

### 5. `POST https://glintbase.dev/api/v1/sandbox`
Deterministic zero-auth testing sandbox.
```bash
curl -X POST https://glintbase.dev/api/v1/sandbox \
  -H "Content-Type: application/json" \
  -d '{ "targetUrl": "https://docs.stripe.com" }'
```

---

## 08. Canonical Machine Surfaces on glintbase.dev

- `/llms.txt`: Machine index with H1 anchors.
- `/llms-full.txt`: Consolidated markdown documentation corpus.
- `/auth.md`: Machine authentication manual with YAML frontmatter.
- `/.well-known/ard.json`: Agent Resource Discovery manifest (ARD v0.91 / v3.0).
- `/openapi.json`: OpenAPI 3.1.0 specification with 17 MCP tools.
- `/docs.md`: Raw markdown developer manual (this file).
- `https://scan.glintbase.dev/api/mcp`: Live Streamable HTTP MCP server gateway.
- `https://scan.glintbase.dev/api/simulate`: Flight Simulator REST endpoint.
- `/api/v1/sandbox`: Zero-auth agent test sandbox.