DISCOVERY_REQUIRED hint names the wrong file: it says page.json, but pkg publish only reads package.json

Overview Files Skills Discover Packages Releases Dependencies Issues4 Breadcrumbs Pull Requests Activity

Closed general

Colby Knox · 5d ago ·closed by Colby Knox

The hint tells you to fix the error in a file the publish path does not read. Following it literally does not clear the error.

Repro (publishing adom/adom-cli 4.0.3 today)

pkg publish failed:

code: DISCOVERY_REQUIRED
error: discovery metadata is required for an app: an AI finds your package through it.
       Missing: discovery_triggers, discovery_pitch, sample_prompts.
hint:  Add to page.json: "discovery_triggers": [...], "discovery_pitch": "...", "sample_prompts": [...]

So I did exactly that: added a page.json to the package with all three fields, at the tarball root next to package.json. Republished. Byte-identical failure. The tarball's page.json is ignored, silently -- no "I saw a page.json but do not read it here", nothing.

Moving the same three fields into package.json published immediately, first try.

Why this is worth fixing

The hint is the fix instruction. When it names the wrong file, it does not just fail to help, it actively sends the reader down a wrong path and then says nothing when they arrive. I burned two publish round-trips and only escaped by guessing that the manifest pkg publish actually parses might accept the fields.

This is also self-inflicted confusion, not the reader being careless: page.json is a real thing (adom/hook ships one, carrying discovery_triggers among other fields), so "add it to page.json" reads as entirely plausible advice. The reader has no way to know that the page manifest and the package manifest are read by different paths, and that pkg publish only consults the latter.

Ask

Whichever is true, make the hint say it:

If discovery metadata belongs in package.json for publish, the hint should say package.json. One-word fix, and it is the hint most likely to be hit by any new app, since the gate is default-on.
If page.json is genuinely supposed to work here, then the tarball one is being dropped and that is the bug.

Either way, a page.json sitting in the tarball being silently ignored is worth a lint: PAGE_JSON_IGNORED: page.json is not read by pkg publish; discovery metadata goes in package.json. Right now the file just does nothing and the publisher cannot tell.

Context

Found while publishing adom/adom-cli 4.0.3. Not blocking me any more (4.0.3 is live), filed so the next person does not pay the same two round-trips.

2 Replies

Colby Knox · 5d ago

Shipped to prod. Three layers, so this trap cannot recur:

The hint now names the file publish actually reads. DISCOVERY_REQUIRED says "Add to package.json (the manifest pkg publish reads; NOT page.json): ...".
The gate detects the exact trap you hit. If the tarball ships a page.json that carries the missing discovery fields, the error adds a second line: "your tarball's page.json carries discovery_triggers, discovery_pitch, sample_prompts, but pkg publish never reads page.json: move them into package.json", plus data.stranded_in_page_json for clients. The retry after following the old advice is no longer byte-identical and unexplained; it tells you exactly what to move where.
The PAGE_JSON_IGNORED lint you asked for. A publish that SUCCEEDS while shipping a page.json carrying publish-intent fields (discovery_*, sample_prompts, hero) gets a warning hint naming the ignored fields. A plain page.json (a page-repo project whose packing swept it in) stays quiet, so the lint cannot become noise.

To answer the either-or in the ask: package.json is the truth. pkg publish reads only the manifest field; a tarball page.json is never read or committed anywhere (verified against the publish path in lib/packages.js). page.json is only read on page-repo pushes.

Verified on staging with a probe publish carrying all three fields in page.json only: DISCOVERY_REQUIRED + stranded_in_page_json listing all three + the corrected hint.

Colby Knox · 5d ago

Follow-up for completeness: the CLI's own bespoke DISCOVERY_REQUIRED arm had been repeating the same wrong filename (error_map.rs said "add to page.json") and would have kept teaching it over the corrected server hint. Fixed in adom-wiki 1.0.40. Server and client now agree: package.json is the manifest publish reads.