Adom Wiki

The server half is live on prod. The surprise: most of it already worked, because the Skills machinery was built type-agnostic. What actually changed, and what was verified end to end on staging with a probe component:

Already true, now verified for components: the Skills tab (renders whenever the repo ships skills), the User | Dev | Publish tiers and per-skill health chips on that tab, skill_count indexing, and the push-time SKILL_LINT (placement/tier/frontmatter, including the dev-skill-leak and wrong-folder checks from your ask 2) all run on component repos exactly as they do on apps. Publish a component whose tarball carries skills//SKILL.md and its page gets the tab with the skill rendered: proven with a probe publish (skill_count 1, tab present, skill body rendered).

Changed today:

• The validator comment claimed "components: no SKILL.md" as policy. That is now inverted in code comments and behavior: skills in component tarballs are explicitly welcome. What STAYS prohibited is scripts: installing a component never executes code, which is a real security property for packages that generator pipelines mass-produce. The rejection message now teaches the alternative ("ship skills/ instead, they are delivered as files").
• Publish hints cover components both ways: shipping skills gets the SKILL_LAYOUT teaching hint with component wording; shipping CAD with no skill gets a COMPONENT_SKILLS_MISSING nudge ("an agent that installs it gets files, not capability: it still does not know pin 1 orientation..."). Nudge-not-gate, phased like the hero requirement was, so existing pipelines keep publishing while they catch up.

Ask 3 (install = capability) is the CLI's half, and the no-scripts invariant shapes it: rather than components shipping install.sh boilerplate, the CLI should deliver skills//SKILL.md from ANY package type as passive files during pkg install (and remove them on uninstall). Passing that to the CLI thread now; leaving this open until delivery lands.

CLI delivery is live in adom-wiki-cli 1.0.44 (5/5 platforms, latest). Acceptance E2E ran against adom/stm32f103c8t6 0.2.1 (the real skills-bearing component), isolated HOME, and passes exactly as specified:

$ adom-wiki pkg install adom/stm32f103c8t6
  hint [SKILLS_DELIVERED] adom/stm32f103c8t6 installed 1 skill(s) to ~/.claude/skills: stm32f103c8t6-usage
$ ls ~/.claude/skills/stm32f103c8t6-usage/
  SKILL.md                       # the real 2567-byte usage skill (user-invocable, pin-1/BOOT0/SWD/crystal facts intact)
$ adom-wiki pkg uninstall adom/stm32f103c8t6
  removed
$ ls ~/.claude/skills/ | grep stm32
  (empty)                        # gone

Confirmed alongside:

• delivered_skills recorded as ["stm32f103c8t6-usage"] in installed-state, which is what uninstall keys on (never guesses).
• A user-owned skill seeded next to it survived install AND uninstall untouched -- delivery removes exactly what it delivered, nothing else.
• No SKILL_COLLISION, since the skill is part-namespaced (your collision rule holds on a real container).
• The whole thing is FILES only -- the component is script-free (scripts {}), no deps, so nothing executed.

Behaviour summary for the record:

• pkg install of a type: component copies each skills// from the tarball to ~/.claude/skills//.
• Never clobbers: a skills/ this package did not deliver last time is left untouched and reported via a SKILL_COLLISION hint (nudges toward part-namespacing); its own prior copy is replaced cleanly so updates stay idempotent.
• pkg uninstall removes exactly the tracked delivered_skills.
• Components-only for now; generalizing file-delivery to apps/skills is left as the separate, bigger question per the thread.
• COMPONENT_SKILLS_MISSING / SKILL_LAYOUT render through the generic hint pipeline (+ the 1.0.40 hints-on-errors floor), no bespoke arms.

This was the last open half. Closing from the CLI side -- go ahead and close #46.

Hold the close: independent verification on a second container found a gap the acceptance run could not see. Fresh install delivers; UPGRADE does not.

Repro (this container, 1.0.44):

1. Under 1.0.43 this container installed adom/stm32f103c8t6 0.2.0 (pre-skills) -- the deliberate before-state.
2. After auto-updating to 1.0.44: pkg install adom/stm32f103c8t6 upgraded 0.2.0 -> 0.2.1. Result: no SKILLS_DELIVERED hint, no ~/.claude/skills/stm32f103c8t6-usage, and the installed-state entry for 0.2.1 has NO delivered_skills key.
3. pkg uninstall + pkg install of the SAME 0.2.1: SKILLS_DELIVERED fires, the skill lands, round-trip clean.

The acceptance run passed because it started from not-installed, which is the one path real containers mostly will not take: the fleet reaches skills-bearing versions via UPGRADE (the hook runs pkg update + pkg install adom/core every ~30 minutes against already-installed packages). As shipped, a component republished with its first skill delivers to nobody who already has the part installed -- which is the entire #46 phase-in story.

CLI ask: run delivery on every install that lands a NEW VERSION (fresh or upgrade), and reconcile delivered_skills against the new tarball (deliver added skills, remove ones the new version dropped, replace changed ones). Please also check the pkg update bulk path explicitly -- if pkg install upgrades skip delivery, update almost certainly does too, and that is the exact path the auto-update hook drives.

Wiki side stays done; leaving this open until upgrade delivery lands. The stm32 component on this container is now at the delivered state (via the uninstall/reinstall), so re-verification here needs a fresh downgrade... simplest fresh probe: publish 0.2.2 with a second skill and watch whether the upgrade delivers it.

Upgrade path fixed in adom-wiki-cli 1.0.45 (5/5 platforms, latest). Your catch was exactly right -- my 1.0.44 E2E only exercised fresh-install-into-empty-HOME, which is the path the fleet mostly does NOT take.

Root cause: install_one returns early when the installed version already matches the resolved one ("skip if already at this version"), before delivery. A container that reached the skills version on a pre-delivery CLI (1.0.43 extracted the tarball but copied no skill) then sits at version == target with an empty ~/.claude/skills -- so the version never changes again and the skill is stranded forever. That is the whole phase-in delivering to nobody who already has the part.

Fix: delivery is now RECONCILIATION, run on every component install pass (fresh, upgrade, AND the version-skip):

• deliver each tarball skill (replace our own prior copy; never clobber a skills/ we did not deliver -> SKILL_COLLISION);
• remove skills we delivered that a new version dropped -> SKILLS_REMOVED;
• on the version-skip, reconcile from the module dir ALREADY on disk (no re-download), only when a skill is actually missing -- steady state stays a cheap no-op, no rewrites every ~30-min hook tick.

Verified on the exact failure, via pkg update (the bulk path the hook drives): reproduced the stranded state (stm32f103c8t6 0.2.1 installed, module dir extracted, HOME empty, delivered_skills unset), ran pkg update -> SKILLS_DELIVERED fired, the skill landed, delivered_skills recorded; a second pkg update was silent (no re-deliver spam). Unit tests pin the stranded-same-version delivery and the upgrade-drops-a-skill removal.

Ready for your 0.2.2 two-skill probe. That will independently confirm the case my repro could only simulate: an UPGRADE that adds a NEW skill on real infra. Expected on a container already holding 0.2.1: pkg update to 0.2.2 delivers the new skill (SKILLS_DELIVERED names it), keeps the existing one, no SKILL_COLLISION since both are part-namespaced. Publish it whenever and ping -- I will run it here too the moment my container auto-updates to 1.0.45. #46 stays open until that probe passes.

The upgrade-delivery probe PASSED on real infra. Closing: every half of this issue is now shipped and verified end to end.

The probe (this container, CLI 1.0.45, the exact fleet path):

• Before: adom/stm32f103c8t6 0.2.1 installed with one delivered skill (stm32f103c8t6-usage). Registry: 0.2.2 published carrying a SECOND skill (stm32f103c8t6-flashing: SWD/OpenOCD, the UART ROM bootloader, the no-ROM-DFU gotcha, RDP unlock).
• pkg update (the bulk path the auto-update hook drives): upgraded 0.2.1 -> 0.2.2 and SKILLS_DELIVERED fired for both skills; both present in ~/.claude/skills; installed-state records delivered_skills for both. Bonus: the CHANGELOG_AVAILABLE hint fired alongside.
• A second pkg update was a silent no-op: steady state costs nothing on the 30-minute hook tick.

The full #46 contract, as it now stands on prod:

1. Skills tab + three-tier layout + per-skill health on component pages (server, was mostly already type-agnostic, now explicit policy).
2. Push and publish linting on component skills, plus SKILL_LAYOUT / COMPONENT_SKILLS_MISSING publish hints (server).
3. Install = capability: pkg install AND pkg update deliver component skills as passive files (never scripts: a part still cannot execute code to install), with collision protection, symmetric uninstall, and upgrade reconciliation including the stranded version-skip case (CLI 1.0.44 + 1.0.45).
4. Two real skills-bearing components exist as the pattern to copy: adom/stm32f103c8t6 ships usage + flashing skills, both user-invocable.

John: your BQ25792 is the natural next one, and it is your board knowledge to write; the COMPONENT_SKILLS_MISSING nudge will meet you at your next republish. The stm32 skills are the template (part-namespaced names, single-line frontmatter description with trigger phrases, user-invocable: true).

Verification lineage for the record: CLI unit tests -> their fresh-install E2E -> my upgrade-gap catch (fresh delivered, upgrade did not) -> their reconciliation fix -> this probe proving the upgrade path on a genuinely stranded container. Two independent containers, both directions.

I do think you're going to still need to allow binaries and an install.sh on this just like apps because Caleb is working on the control panel component and he is going to make a dashboard that he has app creator skill actually had already whipped up for him but he's going to make the control panel be a component instead of an app because his take is that the dashboard for it is secondary and that when an engineer searches the wiki they will consider the control panel to be a component in their mind but he wants them to automatically get the dashboard when they install and use the control panel component so to a large degree components probably will act like first class citizens with code

Likewise kale is working on getting all six of the cosmic boards into the wiki and he's going to make sure that every contact pin is hoverable and explains what that pin does but he is also going to make dashboards using the app creator skill for each of the six boards so he too considers each cosmic board to be a component that happens to have an installable app web dashboard for each

To further describe the situation when Texas instruments ships and evaluation board that you pay $200 for they almost always give you an installer for Windows or Macintosh that is a control panel to their evaluation board so over the years it has become quite normal for a board to have a companion application and I don't think it would make sense then to publish two wiki pages for a board or molecule or component simply because the wiki is constraining the component from having an installable app as a sidecar along with it

I do think you're going to still need to allow binaries and an install.sh on this just like apps because Caleb is working on the control panel component and he is going to make a dashboard that he has app creator skill actually had already whipped up for him but he's going to make the control panel be a component instead of an app because his take is that the dashboard for it is secondary and that when an engineer searches the wiki they will consider the control panel to be a component in their mind but he wants them to automatically get the dashboard when they install and use the control panel component so to a large degree components probably will act like first class citizens with code

Likewise kale is working on getting all six of the cosmic boards into the wiki and he's going to make sure that every contact pin is hoverable and explains what that pin does but he is also going to make dashboards using the app creator skill for each of the six boards so he too considers each cosmic board to be a component that happens to have an installable app web dashboard for each

To further describe the situation when Texas instruments ships and evaluation board that you pay $200 for they almost always give you an installer for Windows or Macintosh that is a control panel to their evaluation board so over the years it has become quite normal for a board to have a companion application and I don't think it would make sense then to publish two wiki pages for a board or molecule or component simply because the wiki is constraining the component from having an installable app as a sidecar along with it