--- name: wiki-discovery description: >- Discovery on the Adom Wiki — a FIRST-CLASS component of the wiki, peer to git, adompkg, releases, discussions, and pull requests. How pages/skills get FOUND: the two layers (local installed-skill matching vs the registry /discover + search endpoints), how to make a page discoverable (manifest + page discovery_triggers), the current real state of what works and what doesn't, and the TODO list of what discovery still needs. Read this when a page won't surface, when setting discovery triggers, or when reasoning about how the AI finds the right skill. Trigger words: wiki discovery, discover endpoint, discovery_triggers, page not surfacing, skill not found, how does the AI find skills, wiki search, make a page discoverable, trigger words, /discover, registry discovery, why isn't my page showing up. --- Parent skill: **adom-wiki-skillpack** # Discovery — a first-class component of the wiki Discovery is **not a nice-to-have bolted onto the wiki — it is one of its core pillars**, on the same footing as the git host, the adompkg package manager, the release database, the discussions forum, and pull requests (see **wiki-anatomy**). A page that can't be discovered may as well not exist: discovery is how an AI (or a human) finds the right skill/app/doc *for what they're doing right now*, ideally **before** they've ever installed or starred it. ## The two layers of discovery Discovery happens at two distinct layers. They are wired differently and fail differently — know which one you're reasoning about. ### Layer 1 — Local installed-skill discovery (works today) Once a skill is installed (`~/.claude/skills//SKILL.md`), the AI picks it by matching the user's intent against the skill's **frontmatter `description`** — specifically its trigger phrases. This is why every skill's description must end with a generous, specific list of trigger words. This layer is reliable: if the phrase is in the description and the skill is installed, the AI surfaces it. → To make a skill catch a specific mistake, put the failure-mode phrases in its `description` (e.g. wiki-readme carries "hero shows twice", "duplicate hero" so it fires the moment someone is about to embed a hero). ### Layer 2 — Registry discovery (search + /discover) — partially working For pages a user has **not** installed yet, the wiki exposes: - `GET /api/v1/search?q=` — full-text search. **Works** (finds pages by slug/title/brief). Caveat: the FTS hyphen bug (`chip-fetcher` → "no such column: fetcher"). - `GET /api/v1/discover?triggers=` — intended to surface pages whose declared `discovery_triggers` match what the user is doing. **This is where discovery is currently weak — see the state + TODO below.** You declare a page's triggers in the **package manifest** (`package.json` `discovery_triggers: [...]`) and they ARE stored (verify: `GET /api/v1/packages//manifest`). ## ⚠️ Current real state (verified 2026-06-21 — re-verify, this WILL change) - ✅ Local installed-skill discovery (Layer 1) works. - ✅ `/search?q=` finds pages. - ✅ Manifest `discovery_triggers` are accepted and stored server-side. - ❌ **`/discover?triggers=` does NOT match manifest `discovery_triggers`.** It returns roughly the same fixed ~70-page set regardless of the triggers passed, so it appears to rank a popular set (stars/installs/recency) rather than match the requested phrases. A brand-new, correct, zero-engagement page is effectively invisible to trigger discovery until it organically accrues engagement — which is backwards (you discover something in order to *start* using it). - ❌ Page-level `metadata.discovery_triggers` pushed via `page.json` to `/files` does not persist (reads back as `metadata: []` on `GET /pages/:slug`). **Practical consequence today:** rely on Layer 1 (install the relevant skillpack, then local discovery is solid) and on `/search` for pages. Don't assume `/discover` will surface a fresh page by its triggers yet. ## 📋 TODO — what we need from discovery (for Colby) Discovery deserves to be as solid as the wiki's other pillars. The asks, roughly in priority order: 1. **Make `/discover?triggers=` actually match `discovery_triggers`.** Text-relevance match the requested phrases against each page's manifest (and persisted page) triggers — not just return a popular set. This is the core bug. 2. **Index triggers at publish time** so a page is discoverable the instant it's published, with no engagement required. 3. **Persist `page.json` `metadata.discovery_triggers`** (today it's dropped) — or document the manifest as the single source of truth and say so. 4. **Relevance + quality blend in ranking**, not quality alone: a highly-relevant new page should outrank a barely-relevant popular one. 5. **Author-side discovery preview/debug**: "what would `/discover` surface for trigger X, and why/where does my page rank?" so authors can test discoverability the way this skill pack dogfoods it. 6. **Unify the two layers**: expose the same trigger corpus so local skill discovery and registry discovery agree on what a page is "about." 7. **Synonym / fuzzy matching** so near-miss phrasings still hit. 8. **Per-type discovery** (skill vs app vs component vs bootstrap) and per-type ranking. 9. **Trigger conflict/dedup signal**: warn when two pages claim the same trigger, and support disambiguation/negative triggers. 10. **Exclude deprecated/soft-deleted/private pages** from public discovery. 11. **Fix the FTS hyphen bug** in `/search` (most Adom slugs contain hyphens). 12. **Discovery analytics**: which trigger surfaced a page, and install attribution, so authors can see discovery actually working (feeds **wiki-scoring**). > ⏳ **UPDATE THIS SKILL when discovery is upgraded.** The "current real state" > section above is a snapshot and is expected to go stale fast. After any wiki > discovery change, re-run the probes (`/discover?triggers=`, manifest check, > page metadata read-back), update the ✅/❌ list, and tick off the TODO items > that shipped. Don't let this skill claim a broken thing works or a fixed thing > is broken. ## Relationship to scoring Discovery answers "can this be found?"; **wiki-scoring** covers the engagement signals (stars / high-fives / installs / trending) that *rank* what's found. They are linked — ranking is part of discovery — but distinct: a page can be perfectly discoverable with zero stars, and discovery should surface it on relevance, with scoring breaking ties among relevant results.