DEPRECATED: Bridge SDK (moved into Adom Bridge)

@@ -29,6 +29,33 @@ If a *bridge verb* misbehaves → fix the bridge. If a *generic AD capability* i 
 ---
 
+## Self-audit checklist — run this when asked to "audit against the SDK"
+
+When a maintainer says *"audit your code, skills, README, and wiki page against the Bridge SDK,"* **this is the checklist.** Each item names its section below; fix every miss, then re-check.
+
+**bridge.json** (the manifest in your zip):
+- [ ] `spawn.kind` ∈ `python|node|exe|external-http`, with **`entrypoint`** (NOT `process`/`cmd`/`args`); `healthEndpoint` is **inside `spawn`**; `port:0` lets AD pick. *(→ bridge.json)*
+- [ ] `updateManifestUrl` → YOUR page's manifest (durable auto-update); `docs` → your own page; **`homepage` is a `wiki.adom.inc` URL, NEVER `github.com`.**
+- [ ] `detect` declared iff you drive a HOST APP (KiCad/Fusion/Altium…); omitted if you bring your own runtime (pup). `prewarm.assets` declared for heavy downloads (e.g. `chrome-for-testing`). *(→ Cold-start tiers)*
+
+**Verbs & output** (what the AI actually reads):
+- [ ] EVERY verb returns a rich **`_hint`** (+ `_next`/`related`/`pitfalls`). *(→ THE ONE PRINCIPLE)*
+- [ ] A `<prefix>_describe` verb lists your whole catalog. *(→ Verb contract)*
+- [ ] No verb blocks on a heavy install/download — background it, report `installing`/`warming`; `<prefix>_readiness` is read-only. *(→ Cold-start tiers)*
+- [ ] `/health` returns `led`/`summary`/`tooltip` truthfully. *(→ Health + status chip)*
+
+**Discovery** (can a plain request find you?):
+- [ ] **10+ user-task `discovery_triggers`** (everyday phrasings, NOT dev jargon). **No triggers = invisible.** *(→ Artifact 3)*
+- [ ] You ran `discover preview --json` on 5-7 real user queries and land **top-3** for each.
+- [ ] Triggers stay in YOUR niche — you don't poach a sibling's (login/forms → native-browser, not pup). `discovery_pitch` is an INSTRUCTION.
+
+**Skills & docs** (what the container + humans read):
+- [ ] You ship the publish/dev/user **3-skill set**; only the USER skill is named `SKILL.md` (dev/publish are `dev-skills/*.md`, source-only). *(→ The SKILL SET)*
+- [ ] Your USER skill leads with the cold-start "read before you panic" section + the 8 conventions, and points the AI at `bridge_readiness`. *(→ USER-skill conventions)*
+- [ ] README + wiki page + skills all AGREE with the above (no stale github links, no wrong schema, triggers vetted).
+
+---
+
 ## bridge.json — the manifest that ships INSIDE your zip
 
 ```jsonc
@@ -71,6 +98,7 @@ If a *bridge verb* misbehaves → fix the bridge. If a *generic AD capability* i - **`spawn.healthEndpoint`** lives **inside `spawn`** (not at the top level), default `/health`.
 - **`updateManifestUrl`** — the full URL of YOUR manifest on YOUR page. **Declare it in `bridge.json`** so it survives a republish; AD polls it (on launch + every 4h) and auto-updates users. (AD also remembers the install URL in `~/.adom/bridge-install-urls.json` as a fallback, but the declared field is the durable, author-intended path.)
 - **`docs`** — point at YOUR dedicated wiki page. AD derives your **skillPkg** (`adom/<slug>`) and your card hero from this. Don't point it at a shared/structural page.
+- **`homepage`** — a **`wiki.adom.inc`** URL (your own page, or `https://wiki.adom.inc/adom/adom-desktop` for the platform). **NEVER `github.com/...`** — GitHub is source-backup only; the wiki is the canonical home. (A `homepage: github.com/adom-inc/adom-desktop` is a stale default to fix.)
 - **`detect` / `prewarm`** — the v1.9.47 cold-start declarations (full rules in "Cold-start tiers" below). `detect` = your HOST APP (AD detects, never installs); `prewarm` = your heavy RUNTIME assets (AD prewarms/auto-installs). A node bridge that ships its deps still works without `prewarm`; declare `prewarm.assets` only for big *downloaded* assets like a browser.
 
 ---
@@ -132,18 +160,30 @@ A container gets it **without anyone asking**: 
 ## Artifact 3 — DISCOVERABILITY: `discovery_triggers` so a plain request finds you
 
-The wiki has an **auto-discover** index. Declare `discovery_triggers` (the phrases a user might say) on your page/pkg manifest, and a request matches them via `adom-wiki discover find`:
+The wiki has an **auto-discover** index, and it is the difference between a usable bridge and an **invisible** one. Declare `discovery_triggers` (the phrases a user actually says) on your page, and a plain request matches them via `adom-wiki discover find` / the in-app discovery an AI runs.
 
 ```bash
-adom-wiki discover triggers adom/adom-desktop-<bridge>-bridge      # show/manage your triggers
-adom-wiki discover preview "open my app in pup"                    # what would surface + WHY
-adom-wiki discover find   "screenshot my website"                 # the live find an AI runs
+adom-wiki discover triggers adom/adom-desktop-<bridge>-bridge --add "open my pcb" "export gerbers"  # add triggers
+adom-wiki discover preview --json "open my pcb design"          # what would surface + the SCORE + WHY
+adom-wiki discover find    "screenshot my website"              # the live find an AI runs
 ```
-Pup's live example (great model to copy): triggers `"pup"`, `"open in pup"`, `"open my app in pup"`, `"open a browser window"`, `"screenshot my app"`, `"browser screenshot"`, … → `discover find` returns the pup page with its `title`, `brief`, `version`, and `discovery_triggers`.
 
-- **Lead `discovery_triggers` with everyday USER phrases, not dev jargon.** A user says *"open my app in pup"* / *"screenshot my website"* — NOT *"spawn the puppeteer CDP bridge"*. Front-load the natural-language phrases so a plain request surfaces you; put any technical aliases after.
-- **`discovery_pitch`** is the one-liner the discover snippet quotes back to the AI — there's **no separate snippet upload step**; the snippet is auto-generated from `discovery_triggers` + `discovery_pitch`. Make the pitch an INSTRUCTION (see below), not a tagline.
-- **Make your `brief` / `discovery_pitch` an instruction, not just a description** — it's what the AI actually reads from the find result. Write it so the AI knows the next moves: *"…**check `adom-desktop bridge_list`** to confirm the bridge is installed in Adom Desktop; if it is, drive its `browser_*` verbs. If the container is missing the skill, `adom-wiki pkg install adom/adom-desktop-puppeteer-bridge` (or `adom-desktop sync_skills`)."*
+**How scoring actually works (measured 2026-06-30 — know this or you'll guess wrong):**
+- `score = 3×(distinct triggers matched) + 1×(tags) + 1×(brief/text)`. **Trigger matches dominate (3× each);** tags/title/brief barely move it.
+- **NO TRIGGERS = INVISIBLE.** A bridge with a perfect title ("Adom Desktop - Blender Bridge") + a matching tag scored **ZERO** for the literal query *"blender"* — it never appeared in `discover preview`. The scorer ignores title/tags when there are no triggers. **Every shipped bridge MUST carry `discovery_triggers` or it cannot be found by the discovery an AI uses.** (`discover search` full-texts the readme, but that is NOT the path discovery takes.)
+- **More good triggers = higher rank.** Each match is +3, so 10 user-task phrasings beat 2. The healthy bundled bridges carry **30-40** triggers; a struggling one had 14 — all dev jargon — and lost EVERY user query.
+
+**The cardinal rule: triggers are USER-TASK phrasings, NOT dev jargon.** A real user types *"open my pcb design"* / *"export gerber files"* / *"design a circuit board"* — NOT *"reverse bridge"* / *"kicad_bridge_call"* / *"fork the kicad bridge"*. A trigger list full of architecture terms scores 0 on every real query (kicad's actual failure: 7/7 user queries missed, and the **Fusion** bridge out-ranked KiCad on PCB queries because Fusion happened to carry a couple of fuzzy "pcb"/"export" triggers). Put **10+ everyday task phrasings first**; technical aliases (verb names) are a small minority at the end.
+
+**VET it — never ship triggers you didn't test:**
+1. Write **5-7 queries a typical user would type** to get your tool (these double as your page `sample_prompts`).
+2. `adom-wiki discover preview --json "<each query>"` → read `data.scoring[]` (array order = rank). **You must land in the top 3.** (Rate-limited: space calls ~2 s; expect a 429 after ~25.)
+3. For every query where you're NOT top-3, **add that exact phrasing as a trigger** and re-test. If a sibling bridge out-ranks you on a shared word (Fusion vs KiCad on "pcb"), add MORE exact phrasings so your 3×-per-trigger total wins.
+
+**Claim YOUR niche — don't poach a sibling's territory.** Discovery routes by whose triggers match; if two bridges match a query the user lands on whichever has *more* triggers, NOT whichever is actually right. So your triggers must describe what YOU are genuinely best at — and you must LEAVE OUT cases a sibling owns. **Canonical example: logging into a site / filling a form on a signed-in page is the native-browser extension's job — it drives the user's REAL browser with their REAL logins — NOT puppeteer's.** Pup is a fresh Chrome-for-Testing profile with no saved logins; it's for *non-login* automation (scraping, screenshots, testing, public pages). So pup must NOT carry `log in` / `fill a form on a site I'm signed into` triggers, and native-browser MUST. When a task needs a capability you DON'T have, make your `discovery_pitch` *point at the bridge that does* — and tell the user to install it (e.g. "for logged-in form-filling, install the native-browser extension") — rather than claim it and do it badly.
+
+- **`discovery_pitch`** is the one-liner the snippet quotes back to the AI — auto-generated from `discovery_triggers` + `discovery_pitch`, **no separate upload step.** Make it an INSTRUCTION, not a tagline.
+- **Make your `brief` / `discovery_pitch` an instruction** — it's what the AI reads from the find result. Tell it the next moves: *"…check `adom-desktop bridge_list` to confirm the bridge is installed; if it is, drive its `<prefix>_*` verbs. If the container lacks the skill, `adom-wiki pkg install adom/adom-desktop-<bridge>-bridge` (or `adom-desktop sync_skills`)."*
 
 ### The end-to-end flow your three artifacts enable