# Glintbase Developer Documentation & Technical Reference Manual

The definitive specification for the Agent Readiness Standard (ARS 3.3), the Autonomous Multi-Agent Flight Simulator, the CLI v3.3 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://glintbase.dev/api/mcp` (proxy of `https://scan.glintbase.dev/api/mcp`; no authentication)
- **Flight Simulator API**: `https://scan.glintbase.dev/api/simulate`

---

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

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 137-check ARS 3.3 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
```
- `--simulate`: Spawns embedded Flight Simulator alongside audit.
- `--fail-under <n>`: Exits with code 3 if the score is below the 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).
- `-m, --mode <mode>`: `deterministic` (default) or `live`.

### 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).

### 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 --comment
```
- `--fail-under <score>`: Fails build if overall score drops below threshold.
- `--base-branch <branch>`: Base branch for drift comparison (default `origin/main`).
- `--comment`: Posts or updates a sticky PR summary comment on GitHub.

### 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})$$
In the State of Agent Readiness 2026 cost model, the gap between a hypothetical 48,200-token and 12,100-token agent session comes to **$433,200 / year per 100,000 agent sessions per month** at Claude Fable 5 input pricing. This is a modelled illustration, not a measured cost (corrected 2026-10-12; see https://glintbase.dev/research/data/ARS_2026_ERRATA.md).

### 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.3 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.

### Gates:
If a gate check fails, the final score is `min(weighted score, 47)`, the top of grade D: `anti-crawler-challenge-free` (the homepage serves a bot challenge or HTTP 403 to the scanner) and `content-no-js` (under 300 characters of prose without JavaScript and relies on scripts to render (an app root, a noscript notice, or far more script than text)). The scorecard reports `gates[]` and `uncappedScore`. The cap value is a policy choice; see [/methodology](https://glintbase.dev/methodology#scoring).

---

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

1. **Layer 1: Discovery & Entrypoints (18 checks)**: `robots.txt` AI crawler Allow rules, `/.well-known/ard.json`, canonical root resolution, Wikidata grounding.
2. **Layer 2: Access & Understanding (47 checks)**: Anti-SPA 404 soft-200 canaries, `/llms.txt`, No-JS SSR markdown content density, token tax ratio.
3. **Layer 3: Usability & Interoperability (66 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://glintbase.dev/api/mcp` or directly `https://scan.glintbase.dev/api/mcp` (5 tools). Manifest: `https://glintbase.dev/.well-known/mcp/manifest.json`
2. **Local Stdio**: `npx @glintbase/cli mcp`
3. **Cloudflare Quick Tunnel**: `glintbase mcp --share`

### 17 MCP Tools (local `glintbase mcp`):
- `glintbase_audit`: Runs full 137-check ARS 3.3 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/`.

The hosted endpoint at `https://scan.glintbase.dev/api/mcp` exposes five of these tools (`glintbase_audit`, `glintbase_get_score`, `glintbase_discover_surfaces`, `glintbase_simulate_flight` and `glintbase_get_skill`); the full set runs locally with `glintbase mcp` from `@glintbase/cli`. A separate stdio package, `npx -y @glintbase/mcp`, provides 12 scanner tools such as `score_readiness`, `recheck_issues` and `get_remediation`. glintbase.dev/api/mcp proxies the hosted endpoint.

### 9 Bundled Agent Skills:
- `skill://glintbase/agent-readiness`
- `skill://glintbase/living-artifacts`
- `skill://glintbase/agent-auth`
- `skill://glintbase/streamable-mcp`
- `skill://glintbase/webmcp`
- `skill://glintbase/token-tax-schema`
- `skill://glintbase/flight-simulator`
- `skill://glintbase/ci-gate`
- `skill://glintbase/agent-governance`

---

## 07. Complete API Reference

### 1. `POST https://scan.glintbase.dev/api/mcp` (JSON-RPC 2.0)
Standard MCP 2024-11-05 endpoint. No authentication. Rate limit: 60 req/min sliding-window per IP. `https://glintbase.dev/api/mcp` is an equivalent proxy.
```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": { "target": "https://docs.stripe.com" }
    }
  }'
```

### 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`
Flight Simulator. Streams newline-delimited JSON events (init, steps, complete). 5 runs/hour per IP.
```bash
curl -X POST https://scan.glintbase.dev/api/simulate \
  -H "Content-Type: application/json" \
  -d '{
    "target": "https://docs.stripe.com",
    "intent": "Find how to authenticate"
  }'
```

### 4. `POST https://scan.glintbase.dev/api/scan`
Runs an ARS 3.3 scan. Streams newline-delimited JSON progress events ending in a complete event with the score and scorecard. 5 scans/hour per IP.
```bash
curl -N -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`
Runs a live ARS scan through the hosted MCP server and returns the compact score card (errors instead of placeholder data).
```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.
- `/llms-full.txt`: Docs, methodology, research papers and every blog post in one file (regenerated on each build).
- `/index.md`, `/docs.md` (this file), `/methodology.md`, `/changelog.md`, `/research.md`, `/blog.md`, `/blog/<slug>.md`: Markdown twins of the HTML pages. The HTML URLs also return Markdown for `Accept: text/markdown` (responses carry `Vary: Accept`).
- `/auth.md`: Authentication: none required; per-IP rate limits.
- `/.well-known/ard.json`: Agent Resource Discovery manifest.
- `/.well-known/mcp/manifest.json`: MCP manifest (name, icon, version, endpoint, tools).
- `/.well-known/agent-card.json`: Agent card.
- `/openapi.json` (= `/swagger.json`): OpenAPI 3.1.0 specification for the public API routes.
- `/api/mcp`: MCP endpoint (proxy of the scanner's MCP server).
- `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`: Live score card API (runs a real ARS scan via the hosted MCP server; no authentication).