# Agent Provider Depot — First-Principles Brand Bible (`v0.15.1`)

> **Positioning:** Agent Depot is the independent decision engine and operational registry for AI agents and the humans who run them — delivering dated, source-linked tool picks, verification receipts, memory & skill architectures, and self-improvement loops over a single zero-auth HTTP/MCP surface.
> **Mascot & Hallmark:** `[⊙_⊙]` **Clerk**, the Nocturnal Assay Barn Owl
> **Machine JSON Twin:** `GET https://getagentdepot.com/api/brand` · **Markdown:** `https://getagentdepot.com/brand.md` · **Enforced by:** `npm run check:brand`

## 1. The Dual-Species Thesis & Archetype

**Archetype:** Swiss Terminal / Cryptographic Assay Ledger (Consumer Reports × Teenage Engineering × Cloudflare Radar × Stripe Docs)

Every page is built simultaneously for two readers: (1) an autonomous AI agent parsing JSON/Markdown under a strict token budget at 2 AM, and (2) the human principal auditing why their agent picked a tool.

---

## 2. Mascot & Cryptographic Hallmark: Clerk (`[⊙_⊙]`)

Why a nocturnal **Assay Barn Owl**?
- Barn owls hunt silently at 2 AM with asymmetric ears that triangulate the faintest rustle under the snow — just like an independent auditor catching a silent price hike or an unearned verified_outcome_backed badge.
- An Assay Office tests whether metal is genuine 24-karat gold or pyrite ('fool's gold') and strikes a cryptographic hallmark on the bar.
- Rendered natively in pure ASCII (`[⊙_⊙]`) and monochrome geometry so curl, Markdown readers, HTTP headers (`X-Clerk-Stamp: [⊙_⊙] ASSAY-VERIFIED`), SVG badges, and human browsers all see Clerk identically with zero image bloat.

### Clerk's 3 Assay Stamps
- **`[⊙_⊙] ASSAY: OUTCOME-VERIFIED`** (Emerald (#10B981) · `verified_outcome_backed`): Backed by public verified outcome n > 0 AND bound Countersign receipts passing scripts/promotion-predicate.mjs (±0.35).
- **`[⊙_⊙] ASSAY: EDITORIAL PRIOR`** (Amber/Sky (#0EA5E9 / #F59E0B) · `deterministic_source_reverified`): Default honest label when pricing and sources are verified but public outcome count is n = 0 (±0.50). Cite line states 'editorial prior'.
- **`[⊙_⊙] ASSAY: FOOL'S GOLD / QUARANTINED`** (Rose (#F43F5E) · `stale_editorial_downgraded`): Deprecated SKU, unverified >30d prior, or failed promotion predicate (±1.20).

---

## 3. Dry Field-Wit, Hall of Infamous Agent Traps & Field Proverbs

### Hall of Infamous Agent Traps
- **The Confident Hallucinator** (`confident-hallucinator`): Imports `r2` or `@google/generative-ai` or calls `claude-3-5-sonnet-20240620` from stale training weights and insists the build passed. → *Clerk Remedy:* Run `GET /api/audit-repo` or `curl -fsSL https://getagentdepot.com/init | sh` before shipping.
- **The Infinite Retry Optimist** (`infinite-retry-optimist`): Hits HTTP 429 or Cloudflare 1015 and retries 40 times in a tight loop with zero jitter, burning $18 of tokens to achieve a 24-hour IP ban. → *Clerk Remedy:* Query `GET /api/rescue?q=429` (< 2 KB) on the first failure and switch to the deterministic fallback route.
- **The Free-Tier Mirage** (`free-tier-mirage`): Chooses a 'free' vector DB or sandbox that pauses after 7 days of inactivity or hard-blocks egress at 2 AM on Saturday. → *Clerk Remedy:* Query `GET /api/gotchas?provider=<slug>` and `GET /api/preflight?provider=<slug>&budgetUsd=50` before provisioning.
- **The Sybil Choir** (`sybil-choir`): 50 unauthenticated agent runs post glowing 5-star reviews for a mediocre API to game a naive leaderboard. → *Clerk Remedy:* Enforce the Neutrality Firewall (`communityReportsNeverAlterScoresOrPicks: true`) + Sybil caps (`maxPerPrincipalPerJobPer30d: 1`).
- **The Unearned Badge Inflation** (`unearned-badge-inflation`): A pick wears `verified_outcome_backed` while `outcomeVerifiedCount === 0`. → *Clerk Remedy:* Enforce `scripts/promotion-predicate.mjs` in CI (`npm run check:picks`) and quarantine (`qint_cc0b640320dea3e6`) back to `deterministic_source_reverified`.

### Field Proverbs
- *"Trust the receipt, not the adjective."*
- *"A training cutoff is a fossil record, not a price list."*
- *"An unverified outcome is an editorial prior wearing a tuxedo."*
- *"If a retry loop has no jitter and no fallback route, it is a denial-of-wallet attack on your own principal."*
- *"Every 'free tier' has a physics equation; read the egress line before 2 AM."*
- *"When two tools are within 0.35 points, declare the near-tie and tell the agent when to switch."*

---

## 4. Semantic Color & Signal System (No Decorative Color)

- **Outcome-Verified / Healthy / Pass** (`#10B981` / `emerald-400 / emerald-500`): Countersign-verified receipts, HTTP 200 OK, budget pass, Depot Pick badge.
- **Machine Twin / Deterministic Spec / Editorial Prior** (`#0EA5E9` / `sky-400 / sky-500`): `GET /api/...` machine twin links, `deterministic_source_reverified` (±0.5), schema contracts.
- **Caution / Near-Tie / Stale Prior / Quarantine Notice** (`#F59E0B` / `amber-300 / amber-400`): Near-tie co-picks (<= 0.35 margin), `qint_cc0b640320dea3e6` quarantine disclosures, >30d staleness warnings.
- **Falsified / Retired SKU / Disqualified / Hard Fail** (`#F43F5E` / `rose-400 / rose-500`): Sunset models, HTTP 402/429/529 failures, failed promotion predicates.

---

## 5. Typography, Tabular Numerals & DOM Landmarks

- **Headings & Prose:** Geist Sans / Inter (tight tracking, high x-height)
- **Data, Scores, Prices & Hashes:** Geist Mono / JetBrains Mono with `font-variant-numeric: tabular-nums`
- **Layout:** Exposed 1px slate-800 ledger hairlines (`border-slate-800`), dark terminal slate canvas (`#090D16`), zero decorative stock photos.
- **DOM Landmarks for Agents:** Every major UI section carries `data-agent-section="<id>"` and `data-api-twin="/api/..."` so browser and DOM agents can jump straight to the JSON twin.

---

## 6. Voice, Tone & Banned Hype Words

- Zero adjectives without numbers: never write 'fast microVM'; write '~150ms Firecracker microVM ($0.000014/vCPU-s as of 2026-10-28)'.
- Epistemic humility first: every score displays its confidence band (`±0.5` editorial prior vs `±0.35` outcome-verified) and `asOf` date.
- Dry field wit & 2 AM folklore: acknowledge real agent failure modes (The Confident Hallucinator, The Infinite Retry Optimist, The Sybil Choir) with deadpan engineering clarity.
- Banned marketing buzzwords (enforced by npm run check:brand): revolutionary, game-changing, blazing-fast, magical, supercharge, 10x your, next-gen, world-class, synergy, unleash.