Adom Wiki Skill Pack

@@ -5,13 +5,14 @@ description: >-   `adom-wiki pkg`, 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+  how `adom-wiki discover find "<the user's own words>"` ranks pages, the+  current state, and 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.+  showing up, discover find, find a skill I don't have, is there a tool for this,+  is there an app for. ---  Parent skill: **adom-wiki-skillpack**@@ -42,19 +43,40 @@ phrase is in the description and the skill is installed, the AI surfaces it. `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+### Layer 2: Registry discovery (find pages you have not installed) -For pages a user has **not** installed yet, the wiki exposes:-- `GET /api/v1/search?q=<query>`, full-text search. **Works** (finds pages by-  slug/title/brief/README/tags; hyphenated slugs are fine). Takes the filter-  syntax below.-- `GET /api/v1/discover?triggers=<csv>`, 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.**+For pages a user has **not** installed yet, ask the registry with the user's own+words:++```bash+adom-wiki discover find "where can I buy an STM32 and compare prices"+adom-wiki discover preview "make a hero image for my wiki page"   # same, plus why each ranked+```++`find` (`GET /api/discover/find?triggers=<prompt>`) takes a plain-language prompt,+not a keyword list. It ranks every page that declares `discovery_triggers` (apps,+skills, bootstraps, boards and other hardware with real triggers), and a part is+found by its part number (any word with a digit is looked up by slug and MPN).+How it ranks (2026-10-02):+- filler words are ignored and word endings folded (drive, driving, drives);+- rare words count more than common ones ("chipfit" says more than "kicad");+- per word, the best place it appears counts once: a trigger, then the title or+  slug, then a tag, then the brief;+- a trigger the prompt says in full is the strongest signal;+- pages covering more of the prompt rank higher; popularity only breaks ties.++On the live catalog this puts the right page first for about 9 prompts in 10 and+in the top three for nearly all. Use the top results' `discovery_pitch` to tell+the user what they would get, then `adom-wiki pkg install <owner>/<slug>`.++`GET /api/discover` lists the pages that carry triggers (the index), without+plain parts whose only trigger is their own part number.  You declare a page's triggers in the **package manifest** (`package.json`-`discovery_triggers: [...]`) and they ARE stored (verify:-`GET /api/v1/packages/<slug>/manifest`).+`discovery_triggers: [...]`) or `page.json`; either way they are indexed at+publish and push, so a new page is discoverable at once, with no engagement+needed. Write triggers as the phrases people say ("design a hero+image", "export gerbers"), not single generic words.  ## Search syntax: filters and search inside a page (2026-09-21) @@ -90,59 +112,26 @@ back and rows are capped, so a miss is a reason to read the pack, not a conclusion; "not found" never ends a search. Every markdown document a page ships is indexed by heading at index time; nothing to declare. -## ⚠️ 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=` 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 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.+## Current state (verified 2026-10-02 on wiki.adom.inc)++- Local installed-skill discovery (Layer 1) works.+- `discover find` / `preview` match a natural prompt against every page's+  triggers, title, tags and brief, and find parts by number.+- Manifest and `page.json` `discovery_triggers` are stored and indexed at publish.+- Each page's **Discover tab** self-tests its own sample prompts against the same+  matcher, and a publish answers with a `DISCOVERY_PREVIEW` hint (your rank,+  colliding pages, generic words, unique words). Use them to tune triggers.+- History: until 2026-10-02 `find` only looked at the 1000 most recently updated+  pages with triggers, and bulk part uploads filled that window, so apps and+  skills could not be found at all. If discovery looks broken again, check+  `adom-wiki discover preview "<prompt>"` first: it shows what ranked and why.++## Still to do++1. Discovery on every prompt for pages that are not installed (today an agent+   has to run `discover find` itself).+2. Synonyms ("buy" vs "source" vs "price"); today matching is on word forms.+3. Discovery analytics: which prompt surfaced a page, and install attribution.  ## Relationship to scoring