[aitrawog]

Closes #201

Summary

Head 27ab818daa661629f7ae103958fb69858152b031 — the commit this PR pushes. 5 files changed, 112 insertions(+), 17 deletions(-): the marketplace submodule gitlink (1 file, +1 −1) and the four generated recipe pages the corpus projects (4 files, +111 −16).

The site stops projecting a corpus that is eight commits behind the published one. This repo's marketplace submodule advanced 5feb9c8b8350849fd2d46d252b486844c18bd0a4 → 197f42a57ab88fcaed6a044bf312d753a72062b2 — the head opencharly/marketplace's merged main serves. It is one commit above that repo's tag v2026.302.0622 because tag-on-merge writes CHANGELOG/ after the tag, so the pin names what main serves, not the tag and not the merge commit.

The four pages are the projection of exactly the four corpus bodies that changed. The corpus's own diff between the two pins touches four SKILL.md bodies and nothing else that this site projects:

$ git -C /tmp/mkt/marketplace-repo diff --stat 5feb9c8b 197f42a5 -- '*/SKILL.md'
 .../skills/plugin/references/authoring-recipes.md  |  3 +-
 internals/skills/marketplace/SKILL.md               | 25 +-
 kubevirt/skills/kubevirt/SKILL.md                   | 39 ++-
 tools/skills/docs-site/SKILL.md                     | 60 +++++-
 4 files changed, 121 insertions(+), 8 deletions(-)

and the site's four changed pages are those four bodies, one for one:

corpus body	this site's page	diff
internals/skills/marketplace/SKILL.md	recipes/internals/marketplace.md	+20 −5
internals/skills/plugin/references/authoring-recipes.md	recipes/internals/plugin/authoring-recipes.md	+2 −1
kubevirt/skills/kubevirt/SKILL.md	recipes/kubevirt/kubevirt.md	+38 −1
tools/skills/docs-site/SKILL.md	recipes/tools/docs-site.md	+51 −9

One symptom was visible in the published tree, and it is now gone. The page still taught the corpus drift gate's OLD instrument — "including UNTRACKED regenerated files (git status --porcelain, not just git diff --exit-code)". That command aborts on the refresh job's own tree, because the refresh stages its regenerated corpus on purpose. The corpus's own copy of the same body had already been corrected (opencharly/marketplace#599), and the site now carries the corrected text — the third and last surface of opencharly/plugin-marketplace#56.

How tested

1 — the baseline: a regeneration at the OLD pin is a byte-exact no-op. This is what makes the diff attributable to the corpus bump alone, and it was measured BEFORE the bump.

$ /tmp/mkt/docs-generator/plugin-docs-bin generate \
    --root /tmp/mkt/charly-gen \
    --narrative <umbrella worktree @ 1c88fcf> \
    --plugins /tmp/mkt/marketplace-5feb \
    --out /tmp/mkt/docs-out-baseline2/src/content/docs
charly docs: 395 recipe pages, 196 plugin pages (205 provider words), 79 cli pages, 834 candy pages, 216 box pages (1726 generated pages cleared before regeneration)
GEN_RC=0

$ diff -rq src/content/docs /tmp/mkt/docs-out-baseline2/src/content/docs | wc -l
0

The toolchain is CI's: plugin-docs v2026.289.0814 built from cmd/serve, charly at this repo's CHARLY_PIN be7a505f476c1a5b0302d878e0b5686a2cde3e07, the umbrella at its UMBRELLA_PIN 1c88fcf15f8fb9dd8b2814210472a63d3a79d0e2, the corpus at this repo's own submodule pin 5feb9c8b.

2 — the regeneration at the NEW pin, on the committed tree.

$ /tmp/mkt/docs-generator/plugin-docs-bin generate \
    --root /tmp/mkt/charly-gen \
    --narrative <umbrella worktree @ 1c88fcf> \
    --plugins <the marketplace submodule @ 197f42a5> \
    --out <this repo>/src/content/docs
charly: resolving github.com/opencharly/plugin-example-stepkind:v2026.239.1641 (707 resolved, 195 queued)
charly: resolving github.com/opencharly/layer-playwright:v2026.274.0640 (708 resolved, 178 queued)
charly: resolving github.com/opencharly/pod-dbus:v2026.235.2057 (709 resolved, 149 queued)
charly: resolving github.com/opencharly/layer-ssh-client:v2026.237.458 (710 resolved, 124 queued)
charly docs: 395 recipe pages, 196 plugin pages (205 provider words), 79 cli pages, 834 candy pages, 216 box pages (1726 generated pages cleared before regeneration)
GEN_RC=0

3 — the drift gate, and its own fixtures. The gate is the repo's: .github/docs-corpus/check_drift.sh, which compares the committed pages with what the PINNED inputs regenerate, untracked files included.

$ bash .github/docs-corpus/check_drift.sh
content: committed tree matches the pinned inputs (regeneration is a no-op).
DRIFT_GATE_RC=0

$ python3 .github/docs-corpus/test_check_drift.py
test_clean_content ... ok
test_deleted_content ... ok
test_modified_content ... ok
test_staged_content ... ok
test_unrelated_change ... ok
test_untracked_route_without_tracked_diff ... ok
Ran 6 tests in 0.042s
OK

4 — the pin-currency report. This repo reports each pinned input's currency and never fails on it, because the remedy for a stale pin is a regeneration PR that bumps the pin, not a gate that fails.

$ bash .github/scripts/check_pin_currency.sh .
corpus pin: 197f42a57ab88fcaed6a044bf312d753a72062b2 is cur — at the corpus's merged main (merged main: 197f42a57ab88fcaed6a044bf312d753a72062b2)
charly pin: be7a505f476c1a5b0302d878e0b5686a2cde3e07 is behind — 2 commit(s) behind charly's merged main; an advance available NOW (a pin-bump PR in this repo) (merged main: 1637a5e43380550b68d53b2e1167e0628768cd52)
umbrella pin: 1c88fcf15f8fb9dd8b2814210472a63d3a79d0e2 is cur — at the umbrella's merged main (merged main: 1c88fcf15f8fb9dd8b2814210472a63d3a79d0e2)
CURRENCY_RC=0

The corpus pin is cur after this change — it was 8 commits behind before it. The charly pin is behind by 2 commits and is a DIFFERENT pin class with its own producer; it is filed as #202, below.

5 — the rest of this repo's own workflow gates, on the committed tree.

$ python3 .github/scripts/check_step_timeouts.py
check-step-timeouts: OK (1 workflow file(s) asserted; every job and every step carries a deadline)

$ python3 .github/scripts/check_step_timeouts.py --self-test
check-step-timeouts self-test: OK (unbounded steps, jobs and traps are all caught, and the org-distributed copy is reported)

$ python3 .github/scripts/test_check_step_timeouts.py
ok  mutA-nomark — the block-scalar marking removed, and the self-test turned red on it
ok  mutB-crossjob — the cross-job step bound removed, and the self-test turned red on it
ok  mutC-jobsend — the jobs-mapping end bound removed, and the self-test turned red on it
ok  mutE-deadbound — the dead-step-bound rule removed, and the self-test turned red on it
ok  mutF-orgdistributed — the org-distributed exclusion removed, and the self-test turned red on it
test_check_step_timeouts: OK (5 mutants; every one of them turns the self-test red)

$ python3 .github/scripts/check_dependency_advisories.py
check-dependency-advisories: OK (no known advisory in the production tree or the dev tree)

$ python3 .github/scripts/check_dependency_advisories.py --self-test
check-dependency-advisories self-test: OK (a production finding, a dev finding and a clean tree are all told apart, and an unauditable tree is an error)

$ python3 .github/scripts/test_check_dependency_advisories.py
ok  mutA-noproductionaudit — the production audit removed, and the self-test turned red on it
ok  mutB-nofindings — the findings loop removed, and the self-test turned red on it
ok  mutC-invertedlabel — the tree label removed, and the self-test turned red on it
ok  mutD-swallowederror — the report guard removed, and the self-test turned red on it
ok  mutE-noadvisories — the advisory extraction removed, and the self-test turned red on it
test_check_dependency_advisories: OK (5 mutants; every one of them turns the self-test red)

$ bash .github/scripts/test_check_pin_currency.sh
PASS=40  FAIL=0
test_check_pin_currency: OK (every state is reported, and none of them fails)

Every gate exits 0, with zero warnings.

6 — the site itself builds, under the node version this repo pins (.node-version 22.23.4):

$ node --version && npm --version
v22.23.4    10.9.9
$ npm ci --no-audit --no-fund
added 306 packages in 2s
NPM_CI_RC=0
$ npm run build
07:37:51 [build] ✓ Completed in 39.06s.
07:37:56 [starlight:pagefind] Finished building search index in 4.56s.
07:37:56 [@astrojs/sitemap] `sitemap-index.xml` created at `dist`
07:37:56 [build] 1749 page(s) built in 47.97s
07:37:56 [build] Complete!
NPM_BUILD_RC=0
$ test -f dist/index.html && find dist -name '*.html' | wc -l
1749

7 — the R5 sweep, keyed on the retired text itself. The claim is that the published site no longer teaches the gate's old instrument.

$ grep -rn "including UNTRACKED regenerated files" --include='*.md' src/
(no hits)
$ grep -rn "git status --porcelain" src/content/docs/recipes/internals/marketplace.md
src/content/docs/recipes/internals/marketplace.md:73:deliberately does NOT use `git status --porcelain`: that command reports the index column

The only surviving hit is the corrected NEGATION — the page now explains why the gate does not use that command.

Rulebook compliance

• R0 — skills first. The dispatcher rows this change selects were read before the first tool action: /charly-build:docs (the charly docs generate verb, this repo's generation workflow and the drift-gate recipe), /charly-tools:docs-site (the Astro/Starlight candy and the site's build), /charly-internals:git-workflow (the pin contract, the PR body's form and the landing rules), /charly-internals:strict-policy (the discipline rules this change is judged by) and /charly-internals:root-cause-analyzer (the RCA the filed finding carries). This repo's own AGENTS.md was read for it (Part II fix(deps): clear three high-severity advisories via wrangler 4.118.0 #4).
• R1 — every anomaly gets a root-cause analysis, and every finding is fixed or filed. The anomaly this change carries is the site's blindness to a stale pin: the drift gate compares the committed pages with what the PINNED inputs regenerate, and the pinned corpus regenerates its own (old) pages perfectly — so the gate is green over a corpus that is eight commits behind the published one, and nothing in the tree said so. The RCA names the mechanism (the corpus repo's daily refresh advances main; this repo's submodule gitlink is advanced only by a manual regeneration PR), the missed control (the pin-currency comparison against the corpus's merged main — which exists and REPORTS, and which this change brings back to cur), the blast radius (the site's recipe pages projected a corpus that is no longer the published one, and one of them taught an instrument that aborts on the refresh's own tree) and the root fix (this PR: the gitlink advanced and the REGENERATED pages carried in the same change, since a stale submodule plus pages generated from the new corpus would drift). One further finding is separable by construction and is FILED: the charly CI-time pin is 2 commits behind charly's merged main — a different pin class with its own producer and its own remedy — in the pinned charly CI-time commit is behind charly's merged main — the drift gate cannot see it #202, with its own RCA.
• R2 — one canonical implementation, no second copy. The corpus pin lives in exactly one place — the committed gitlink — and the pages are generated from it, never hand-edited. No page in this repo restates the corpus's gate prose; it is projected.
• R3 — no workaround. No hand-edited generated page, no hand-pinned gitlink, no sleep, no blind retry, no suppression. The gitlink moved to the corpus's merged main head and the pages came out of the generator.
• R4 — the product before the prose. The corpus's producer-side fixes are merged and merged-into-main already (chore: refresh the refs list marketplace#599, and the source edit behind the marketplace skill names the drift gate's old instrument (git status --porcelain) — the gate is now scripts/drift-gate.sh and does NOT compare the index with HEAD plugin-marketplace#56). This PR points the projection at them and regenerates; it does not restate their rules in prose of its own.
• R5 — the legacy is deleted, proven by a claim-keyed sweep. The claim is that the published site no longer teaches the drift gate's old instrument. The sweep in How tested is keyed on the retired sentence itself, and the only surviving hit is the corrected negation.
• R6 — user work and git safety. The work ran in the session worktree .worktrees/docs-refresh/docs — a clone of this repo alone — on feat/marketplace-submodule-bump, branched from this repo's fresh origin/main (674bf53). The tree's status was empty before the change and is empty after it. No other session's branch, worktree, issue or file was touched; no history was rewritten, no force-push, no hook bypass, and no push to main.
• R7 — behavior is proved, not compilation. The coverage for a projection change IS the projection: the regeneration is the changed path, executed live against the real pinned inputs, and the drift gate proves the committed tree matches them exactly, untracked files included. The attribution of the diff is proved by a byte-exact no-op regeneration at the OLD pin, so the 4-page diff cannot have come from anything but the corpus bump. The site's own gates are proved by their own mutation harnesses — ten mutants across the two self-tested gates, every one of them turning its suite red.
• R8 — live or skip, never a mock. This change crosses no service boundary: it advances one pin and regenerates prose from it. The build that proves the site assembles is the real Astro build over the real content.
• R9 — binary equals source. The generator is the plugin-docs CLI built from the tag this repo's own workflow pins (v2026.289.0814), from its own source, in this session — not a shared install.
• R10 — a fresh, disposable proof. The change class is a pin change plus the pages it projects, and the gate that owns it is this repo's own generation workflow, run on the committed tree: the regeneration, the drift check, the pin-currency report, the dependency-advisory gate, the step-deadline gate and the Astro build — every step, zero failures, zero warnings. This change touches no disposable: true target.
• Hard Cutover. One cutover, one PR: the gitlink advance and the regenerated pages land together, with no phase deferred and no shim. Carrying the pages without the bump, or the bump without the pages, is exactly the drift the gate would catch on the next run.
• Part II feat: bootstrap the opencharly.ai documentation site #1: no submodule was edited. The corpus was read from this repo and advanced by its own gitlink entry; nothing inside marketplace/ was touched.
• Part II ci: deploy to Cloudflare Pages from Actions, and fix the duplicate home title #2: the work ran in a session worktree, and the working set it needed was materialized in it.
• Part II docs: regenerate after the plugins skill corrections #3: the pin advances to a MERGED ref — the head opencharly/marketplace's merged main serves — through this repo's own committed gitlink, never by a hand-pin or a branch checkout; the currency question was asked with this repo's own report, and the corpus's answer is cur.
• Part II fix(deps): clear three high-severity advisories via wrangler 4.118.0 #4: this repo's own AGENTS.md was read before any change here.
• Part II fix(docs): correct CHANGELOG heading left stale by a validator merge slip #6: the leg's issue is the marketplace submodule is pinned behind the corpus's served head — the recipe pages are generated from an old corpus #201, CLAIMED, and a STATUS is posted on it at each milestone. The separable finding was filed as the pinned charly CI-time commit is behind charly's merged main — the drift gate cannot see it #202, with a STATUS recording that it is not claimed by this session.
• Part II docs: regenerate the git-workflow pages for plugins v2026.215.1627 #7: this body's footer carries the Agent: line before the italic trailer, and every coordination comment on this scope is in the nine-label grammar, with the attribution block LAST in each.
• Part II docs!: gourmet-kitchen landing + a twelve-part concepts curriculum #8: every new comment and the validator's full report are read before the next push, and each round appends one commit.
• Part II docs(landing): a front page with a spine, and /grievances/ on the site #9, docs: sync the generated catalog to four landed skill changes #11: the session ledger carries this PR, the marketplace submodule is pinned behind the corpus's served head — the recipe pages are generated from an old corpus #201 and the pinned charly CI-time commit is behind charly's merged main — the drift gate cannot see it #202, and a STATUS comment lands on the marketplace submodule is pinned behind the corpus's served head — the recipe pages are generated from an old corpus #201 at each milestone.

Change classification

• Change class: a pin change (the marketplace submodule gitlink this repo records) plus the generated recipe pages that pin projects. The pin carries CONTENT — the corpus bodies the site's recipes/** pages are generated from — so this is not the documentation-only class, and the tier is a runtime tier.
• Diffstat: 5 files changed, 112 insertions(+), 17 deletions(-) — the marketplace gitlink (1 file, +1 −1) and the four generated recipe pages (+111 −16).
• Gate run: this repo's own generation workflow on the committed tree — the regeneration, the drift check (content: committed tree matches the pinned inputs), the pin-currency report, the dependency-advisory gate with its self-test and its mutation harness, the step-deadline gate with its self-test and its mutation harness, the pin-currency fixtures and the Astro build — every step, zero failures, zero warnings.
• Attribution tier: fully tested and validated — the change-class gate passed on the final tree, and the changed path (the generator, run against the real pinned inputs) was executed live, with the "before" retained as a byte-exact no-op.
• No rebuild leg applies: this change touches no disposable: true target; the site is built by the real Astro build, pasted above.

Filed issues

• the pinned charly CI-time commit is behind charly's merged main — the drift gate cannot see it #202 — the charly CI-time pin is behind charly's merged main: be7a505f476c1a5b0302d878e0b5686a2cde3e07 is 2 commits behind 1637a5e43380550b68d53b2e1167e0628768cd52, and the two commits it misses are not changelog noise (ab38dff1 chore(deps): adopt spec v0.2026302.327 and its changelog commit). The mechanism (this repo's CHARLY_PIN is advanced only by a manual regeneration PR, so it drifts apart at every charly release), the missed control (none is missing — the pin-currency report exists and names this state as behind, "an advance available NOW"; what was missing is a reader who acts on it, because the report is a step summary line), the blast radius (the site's reference/** half is generated from a charly source tree that charly has moved past, so the published catalog, the provider words and the candy pages describe an older charly than the one in use) and the root fix (a regeneration PR that advances CHARLY_PIN and carries the regenerated pages in the same change — the regeneration is what proves the bump is coherent) are on that issue, with the measured evidence. Not blocking here: it is a different pin class with its own producer and its own remedy, and this change's claim is about the corpus pin, which is cur after it. Separable by construction; it pre-dates this change; it is filed, not folded in.

Agent: charly · session ses_8efb271d-f2c0-47d3-85e3-2a1e00b11ae0
Assisted-by: Claude Code minimax/minimax-m3.1-flash:cloud (fully tested and validated)

[github-actions]

Review — PASS

I re-derived every claim in the body against the complete diff, the commit list, and the (empty) comment thread.

Correctness

• Pin advance matches the gitlink. marketplace moves 5feb9c8b… → 197f42a5…, exactly as the body and head SHA describe.
• File/line counts reconcile. The diff contains 5 files. Insertions: 1 (gitlink) + 20 + 2 + 38 + 51 = 112; deletions: 1 + 5 + 1 + 1 + 9 = 17. The body's "112 insertions(+), 17 deletions(-)" and its "four generated recipe pages (+111 −16)" both hold exactly.
• Projection is one-for-one with the corpus bodies. The body's corpus diffstat lists four SKILL.md-class bodies; the site diff carries exactly four pages, and the per-page changed-line totals match the corpus stat lines: marketplace 20+5=25, authoring-recipes 2+1=3, kubevirt 38+1=39, docs-site 51+9=60 — each equal to the corresponding corpus body's +/− line count. This is strong internal evidence the pages are the projection of the four changed bodies.
• The claimed symptom fix is reproduced. The removed sentence "including UNTRACKED regenerated files (git status --porcelain, not just git diff --exit-code)" is present in the marketplace.md deletion hunk and replaced by the corrected "deliberately does NOT use git status --porcelain" explanation — matching the body's §1 claim.

Honesty

• The body's counts, the gitlink, the head SHA, and the diffstat are mutually consistent; no contradiction found. The self-disclosed charly-pin-behind finding is explicitly scoped out as a separate pin class and filed (the pinned charly CI-time commit is behind charly's merged main — the drift gate cannot see it #202), which is the correct disposition rather than folding an unrelated pin into this PR.

Tests

• The changed path for a pin/projection change is the regeneration itself; the body documents a byte-exact no-op at the OLD pin (attribution), the drift gate with its mutation fixtures, the pin-currency fixtures, and the Astro build. The pages themselves are generated (DO-NOT-EDIT headers intact), not hand-authored, consistent with "no hand-edited generated page." Coverage is proportionate to a documentation-generation change.

Security

• Documentation prose and a submodule gitlink only. No secrets, no injection surface, no privilege or dependency changes introduced.

Scope & cleanliness

• Coherent single cutover: gitlink + regenerated pages together, no deferred phase, no shim, no leftover legacy text (the old instrument sentence is fully replaced).

Comments

• The comment thread is empty; there are no maintainer sign-offs to weigh and none are required (none configured). The change stands on its own consistent evidence.

No blocking findings. The change is internally consistent, matches its diff line-for-line, and the self-disclosed out-of-scope item is filed rather than folded in.

Verdict: PASS

---

ollama-cloud/deepseek-v4.1-flash — action-review.

View action run