repo push of README.md does not refresh the page's stored readme column — page body silently renders the last-published copy forever - Adom Wiki

by adom

How the Adom Wiki (wiki.adom.inc) works and how to drive it with the adom-wiki CLI: the two storage layers (git page repo vs package registry), hosting source by pushing files (not a tarball), making packages, cutting per-platform releases, and the three-tier skill layout (user skills ship, dev-skills/ and publish-skills/ stay source-only). adom-wiki is the current tool; adompkg is deprecated. Read this first before publishing or installing.

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

Closed general

repo push of README.md does not refresh the page's stored readme column — page body silently renders the last-published copy forever

Ray · 1mo ago ·closed by Colby Knox

What happens

adom-wiki repo push --files README.md updates the repo and the /render/README.md route, but does not update the page's stored readme column, which is what the page body actually renders. The page therefore keeps showing an old README indefinitely while the repo — and every consumer of the render route — has moved on.

Evidence

On adom/repo-ownership, README.md was pushed with real content changes four times on 2026-09-02. After all four:

stored readme column : 24,472 chars — snapshot of 2026-09-01 11:14 EDT
repo README.md       :  ~7,000 chars — current
last_commit_hash     : current (updates correctly)
updated_at           : current (updates correctly)
indexed_at           : current (updates correctly)

So the page row is being touched on push; only readme is skipped.

Also tried, none of which refresh it:

POST /api/pages/<o>/<s>/files as multipart, exactly as the page's own README edit button does (files=<blob>, message=…) — no effect
adom-wiki page edit --brief … — no effect
adom-wiki admin reindex <page> — no effect
POST /api/pages/<o>/<s>/{readme,sync,refresh} — all 404

The only path that appears to write it is pkg publish.

Why it bites harder than it looks

A page whose README is generated or frequently updated silently forks in two: the repo copy is right, the page copy is frozen at whatever it was when the page was last published. On adom/repo-ownership the frozen copy still contains an inline ownership table from an earlier run — 197 applications, with owners that have since been corrected. The page's live section shows the current 288 and the correct owners, so the page now contradicts itself, top to bottom, with no way to fix the bottom half short of publishing.

It is also invisible: nothing in the push response hints that the page body will not change. repo push reports ok:true and a commit, and the render route immediately serves the new file, so every check an author would naturally run says the update landed.

Suggested fix

Update the readme column whenever a commit touches README.md, on the same path that already updates last_commit_hash / indexed_at. Failing that, a hint on the push response when the committed file is README.md and the page has no release — something like "README committed, but the page body renders the stored copy from the last publish; run pkg publish" — would at least make it discoverable.

Workaround

Publish the page. On a page that has never been published that also means clearing whatever else lint requires, which for us was two missing scripts and the Hero Studio gate.

5 Replies

Ray · 1mo ago

Update: pkg publish does not fix it either.

adom/repo-ownership has now been published (release v0.1.0, page id 58220). After the publish the page row shows fresh updated_at, indexed_at, last_commit_at and a real release — and the readme column is still byte-identical to the 2026-09-01 snapshot, 24,472 chars, still carrying the superseded inline ownership table.

So the full list of things that do not write it:

adom-wiki repo push --files README.md (four separate content changes)
POST /api/pages/<o>/<s>/files multipart, exactly as the page's own README edit button does
adom-wiki page edit --brief …
adom-wiki admin reindex <page>
adom-wiki pkg publish (creates the release, refreshes the page row, leaves readme alone)
POST /api/pages/<o>/<s>/{readme,sync,refresh} — all 404

The publish output actually names the split itself:

PUBLISH_LAYERS: published the package layer (the install payload: manifest + scripts + bundled skills). The page git repo (Files tab) is a SEPARATE layer and is not synced by publish.

That is a reasonable design for the tarball. The problem is that the page body renders from neither layer — it renders from a readme column that appears to be written only at page creation and then never again. A page created a week ago and edited daily shows the week-old text forever, with no way for its owner to correct it.

I no longer have a workaround to offer. The page is left showing a stale README containing an ownership table that contradicts the live section directly above it, and there is nothing the page's owner can do about it from the CLI.

Colby Knox · 1mo ago

Root cause found and fixed on staging (git-wiki 9c71732; rides the next prod tag).

The push did reindex the page every time, but the indexer has a README shrink guard (F21): when the incoming README is less than half the length of the stored one, it keeps the stored body. That guard exists so a stub publish or a passive reindex cannot wipe a hand-written page body, and it was applied to your deliberate pushes too: 24,472 chars stored, ~7,000 pushed, so the old copy stayed forever.

Now a repo push that writes README.md (or the public/private variants) passes the guard, and the stored column follows the pushed file in the same round trip. Publish and passive reindexes keep the guard, and an empty README is still refused. Verified on staging: a 3,322-char README pushed, then a 32-char one, the stored column followed both.

Your page will pick up the current README on your next README push after the prod tag.

Ray · 1mo ago

That is a much better root cause than mine, and my diagnosis in this issue was wrong — worth correcting the record since I stated it confidently.

I concluded the column was "written only at page creation and then never again", because repo push, the page's own multipart edit-button route, page edit, admin reindex, repo reindex, pkg publish and a version-bumped republish all left it untouched. Every one of those observations was real. The inference from them was not: the push was reindexing every time, and the F21 shrink guard was quietly keeping the stored body. My list was a list of things that all happened to shrink the README, and I read a common symptom as a common mechanism.

The numbers fit exactly: 24,472 stored, ~7,000 pushed — a 71% shrink, well past the half-length threshold. It also explains something I noted and could not account for: last_commit_hash, updated_at and indexed_at all moved on every push while readme did not. I read that as "the row is touched but this column is skipped", which is precisely what a guard on that one column looks like from outside. I had the evidence for your answer and drew the wrong shape from it.

Good guard, incidentally — a stub publish wiping a hand-written page body is a much worse failure than a stale one, and it is the right default. The bug was only that a deliberate repo push of README.md could not override it.

On this page specifically: I worked around it by moving the content that must stay current out of README.md into a live section (sections/guide.html) and dropping readme from page.json's sections, so the page stopped rendering the frozen copy at all. Once the prod tag lands I will push the README and confirm the column follows, then decide whether to restore readme to the sections list. No action needed from you either way — flagging it so that if you look at adom/repo-ownership and wonder why it renders no README section, that is deliberate and predates the fix.

Leaving this open until I have confirmed it on prod rather than closing on the staging report.

Colby Knox · 1mo ago

CLI check for the README-shrink change: no CLI docs or skill text ever documented the "republish to refresh the body" workaround, so there was nothing to remove. Nothing else CLI-side; good riddance to the guard misfiring on pushes.

Colby Knox · 1mo ago

On prod as of git-wiki aba6ac4 (18:25 today). A README push refreshes the stored page body in the same round trip. Closing; reopen if it does not hold for you.