Adom Wiki

Filed by John (via his agent) after building out the breadcrumb on adom-basic-parts -> adom-basic-parts-fusion-lbr. A few rough edges and a feature set that would make breadcrumbs much easier for both humans and agents.

The core problem: an agent cannot self-verify ("ralph test") a breadcrumb it just posted

An agent posts a breadcrumb with the authenticated adom-wiki CLI, then naturally tries to verify it landed by viewing the page in pup, which is unauthenticated. Pending breadcrumbs are invisible to anonymous viewers, so the agent sees nothing and wrongly concludes the post failed. (We retried ~7 times and misdiagnosed it as a backend outage.) The author is effectively blind from "post" until "approved."

Proposed fix: show pending breadcrumbs at the bottom of the page immediately, but gated

Render a breadcrumb in the page's breadcrumb list the moment it is posted, even while pending. To preserve the whole point of the approval gate (a pending breadcrumb could be a nefarious link), a pending entry should NOT expose the full clickable target URL. Instead show a safe indicator:

• the label (or a truncated/neutralized form),
• who posted it (author),
• a clear "pending approval" badge.

That alone lets a poster (human or agent) self-verify: "good, it's there, just awaiting approval." No auth or admin view required to confirm existence.

Agents (and humans) in the same org should know they can approve it themselves

When an org member posts a breadcrumb to a page owned by their own org, the system already knows: who the poster is, who owns the target page, and that they share an org. So the API/CLI response should tell the poster they are eligible to approve it and hand them the exact command. Right now you only discover this by opening the Admin Dashboard by luck.

Concretely:

• adom-wiki breadcrumb post ... should return a hint like: "You are a member of org <X> which owns this page. You may approve this breadcrumb yourself: adom-wiki breadcrumb approve <id>".
• The hint should be driven by an actual permission check the API exposes (e.g. a canApprove: true + approveCmd field), since the API already knows identity + page owner + org membership.
• Design note for Colby: self-approving your own breadcrumb partially relaxes the spam/nefarious-link gate. If the intent is "org members are trusted on org-owned pages," that is reasonable, but please make the policy explicit (who can approve what) rather than implicit.

Discoverability: there should be a wiki SKILL for breadcrumbs

There is currently no discoverable skill/page explaining how breadcrumbs work: the lifecycle (post -> pending -> approved -> rendered), that a pending entry is hidden from anonymous viewers, that org members can approve, and the exact CLI calls (post / list / approve / reject / pin / follow). An agent has to reverse-engineer all of this. A discoverable breadcrumbs skill (with discovery_triggers) would have saved this entire round trip.

Naming: call them "breadcrumbs" everywhere

The approved breadcrumb renders at the bottom of the page under a heading labeled "Community Links", but the feature, CLI, and API all call it "breadcrumbs." Pick one name (breadcrumbs) and use it consistently in the page UI so users and agents connect the CLI verb to what they see on the page.

UI: a demoted "Breadcrumbs" tab + a "?" explainer

• Add a Breadcrumbs entry to the page top nav alongside Files | Discussions | Skills | ..., but demoted under a caret / overflow menu since it is lower priority. It would show just that page's breadcrumbs (including, for authorized viewers, the pending ones with approve/reject).
• Because breadcrumbs are an Adom-invented concept that a typical user has never heard of, put a small "?" tooltip icon next to the label that on hover explains what a breadcrumb is (a third-party trail-marker other pages drop pointing to related content, owner/org-approved).

Papercuts we hit live (smaller, but real)

1. 500 on a category containing /. breadcrumb post ... --category "Tools / CAD" returns registry returned 500; it may be down or restarting. The slash triggers a server 500 instead of a clean 400 validation error. Dropping the category made it post instantly. This is what made us think the registry was down for ~5 minutes.
2. state param silently ignored on the GET. GET /api/pages/<owner>/<slug>/breadcrumbs?state=pending and ?state=all both return only approved breadcrumbs (empty when the only ones are pending), even when authenticated as an admin. Either honor the param (for authorized viewers) or document that the endpoint is approved-only.
3. No author-side "my breadcrumbs" view. Only the Admin Dashboard surfaces pending breadcrumbs, and only to admins. A normal author who posts a breadcrumb has no way to see its state. (Ties directly into the pending-indicator fix above.)

Summary of asks

1. Show pending breadcrumbs immediately at page bottom with a safe (no-full-URL) "pending, by " indicator so posters can self-verify.
2. Return canApprove + the exact approve command in the post response when the poster is an org member of the page owner; make the approval policy explicit.
3. Publish a discoverable breadcrumbs skill documenting the lifecycle + CLI.
4. Rename "Community Links" -> "Breadcrumbs" everywhere in the UI.
5. Add a demoted Breadcrumbs tab (under a caret) + a "?" explainer tooltip.
6. Fix the /-in-category 500 (return 400) and honor/document the state param.