[aitrawog]

Closes #8

Summary

DOCS_REF moves from f1c823b181e8316b20184f4b4d6dd8a495ff1e78 — the docs repo's main
head of 2026-08-24, 93 commits and two months stale — to
c5568310f0409676728f552712f0896359a789c5, the docs repo's current main head
(origin/main at the time of writing). Both occurrences move together: the var: that
fixes the clone layer's cache key, and the literal in the docs-site-pinned-commit check's
contains: matcher, which the candy documents as a deliberate, non-collapsible
duplication (a check step's substitution does not resolve a candy var:).

Re-pinning it exposes a defect the stale pin was hiding, and this change fixes it too.

The two corpus-projected page checks asserted paths the site stopped producing. The
docs repo dropped the unversioned reference/candy/charly.md and
reference/plugin/plugin-cdp.md in its own #106 (41b0b22, 2026-08-31) and replaced them
with one page per corpus version, under a version-stamped directory
(<repo>-<name>-v<calver>/). The bed kept asserting the unversioned paths and stayed green
only because DOCS_REF still pointed at a docs commit from before that change — a stale
pin hiding a broken assertion.

Both checks now resolve their page by name and read the newest version, and each
fails when no page exists at all — a generator that narrowed to documenting nothing
would otherwise leave cat reading an empty path, and the check would pass on an empty
stdout. The assertions themselves are unchanged: a generated candy page still publishes its
Acceptance plan, and plugin-cdp's page still renders its out-of-process placement and its
CUE parameter schema. A literal path would redden this bed on the next corpus advance — a
false alarm about a change that never touched the site.

The skill body (/charly-tools:docs-site) carries the same account, so it states how the
pages are located and why the unversioned paths are gone.

How tested

charly box validate — the manifest changed:

$ charly box validate
charly box validate: OK — checked 3 candies, 1 box, 1 deploy, 7 distros, 7 builders; 0 warnings, 0 errors
rc=0

charly check run check-docs — the R10 bed, a fresh rebuild of the docs-site-app image
on the committed tree of this PR's head (e4d0342; the run saw the same tree, byte for
byte — the commit was re-worded afterwards to carry the attribution tier it earned):

charly check run check-docs: [image-build] PASS after 1m34.682s
charly check run check-docs: [check-image] PASS after 15.097s
charly check run check-docs: [deploy-add] PASS after 4.683s
charly check run check-docs: [config] PASS after 1.67s
charly check run check-docs: [start] PASS after 1.393s
charly check run check-docs: [wait-ready] PASS after 127ms
charly check run check-docs: [bring-up-members] PASS after 30ms
charly check run check-docs: [check-live] PASS after 5.712s
charly check run check-docs: [feature-run] PASS after 3.354s
charly check run check-docs: [update] PASS after 17.981s
charly check run check-docs: [rebuild-ready] PASS after 100ms
charly check run check-docs: [check-live-rebuild] PASS after 3.838s
charly check run check-docs: [wait-ready] PASS after 127ms
charly check run check-docs: [feature-run-rebuild] PASS after 3.341s
charly check run check-docs: [cleanup] PASS after 10.991s
charly check run check-docs: [cleanup-members] PASS after 0s
charly check run check-docs: PASS (steps=16)
BED_RC=0

and the image build's own check ledger — the two repaired checks, and the whole set:

PASS check the cloned site is the pinned commit, not a stale cached layer [docs-site-pinned-commit] exit=0
PASS check a generated candy page publishes its plan as a runnable acceptance spec (the ADE surface a reader can see without cloning anything) [docs-site-candy-acceptance-plan] exit=0
PASS check a RUNTIME (out-of-process) plugin's page renders both its placement and its CUE parameter schema — the assertion that fails if the generator ever documents only what is compiled in [docs-site-runtime-plugin-page] exit=0; stdout truncated to 1MiB of 1068608 bytes
...
22 steps: 18 passed, 0 failed, 4 skipped

(The four skipped steps are the candy's mutating `run:` steps, skipped in verify-only mode —
the same four the first run skipped.)

The bed was RED before this change, and the same failure is the reason the change is
more than a re-pin. On the tree with the new DOCS_REF and the old check literals:

  FAIL  check a generated candy page publishes its plan as a runnable acceptance spec (the ADE surface a reader can see without cloning anything)  [docs-site-candy-acceptance-plan]  exit=1, want 0 (stderr: cat: /srv/docs/dist/reference/candy/charly/index.html: No such file or directory)
  FAIL  check a RUNTIME (out-of-process) plugin's page renders both its placement and its CUE parameter schema — the assertion that fails if the generator ever documents only what is compiled in  [docs-site-runtime-plugin-page]  exit=1, want 0 (stderr: cat: /srv/docs/dist/reference/plugin/plugin-cdp/index.html: No such file or directory)

22 steps: 16 passed, 2 failed, 4 skipped
command "check": 2 check(s) failed
BED_RC=2

The R1 RCA of that failure

Mechanism. The docs repo's own history, not this change, moved the pages. The unversioned
pages existed at the old pin and are absent at the new one:

$ git -C docs ls-tree -r --name-only f1c823b181e8316b20184f4b4d6dd8a495ff1e78 -- src/content/docs/reference/candy/charly.md
src/content/docs/reference/candy/charly.md
$ git -C docs ls-tree -r --name-only f1c823b181e8316b20184f4b4d6dd8a495ff1e78 -- src/content/docs/reference/plugin/plugin-cdp.md
src/content/docs/reference/plugin/plugin-cdp.md

$ git -C docs ls-tree -r --name-only c5568310f0409676728f552712f0896359a789c5 -- src/content/docs/reference/candy/charly.md
(no output)
$ git -C docs ls-tree -r --name-only c5568310f0409676728f552712f0896359a789c5 -- src/content/docs/reference/plugin/plugin-cdp.md
(no output)

$ git -C docs log --oneline --diff-filter=D --all -- src/content/docs/reference/candy/charly.md
41b0b22 chore(deploy): standalone plugin-docs generation + charly pin a31f76d7 (#106)

Missed control. Two, and both are the same defect seen from two sides. (1) The bed's
page paths were literals, never re-validated against the site's structure, so the site
could change shape under them. (2) Nothing tied the bed's fitness to a current
DOCS_REF: docs-site-pinned-commit proves the image holds the pin, never that the pin
is the docs repo's head. The control that would have caught the second — task docs:pin,
which compared DOCS_REF with the live docs head — was deleted in charly#452
(665693b9, 2026-08-29) with an explicit delegation to this repo ("charly cannot maintain
another repo's pin; that check belongs to layer-docs-site") and was never implemented here.
The guidance kept naming it anyway. That is filed as #10.

Blast radius. The bed has been green over two broken assertions since 2026-08-31 —
every run since the docs repo's #106 proved nothing about those two pages while reporting
PASS. The same literals would have reddened the bed on the next corpus advance for a
reason unrelated to what the bed asserts.

Root fix. In this change: the pages are resolved by name, the newest version is read,
and the absence of any matching page fails the check. The pin moves to the docs repo's
current main head, so the bed proves the site as it is published today, not as it was
published two months ago. The delegated currency control stays a filed obligation (#10):
it is a task in this repo, and it belongs to its own change.

R5 — the legacy paths are gone. The two literal paths are no longer asserted anywhere:

$ grep -rn "dist/reference/candy/charly/index.html\|dist/reference/plugin/plugin-cdp/index.html" . --exclude-dir=.git
(no match)

(The skill body still NAMES those two unversioned paths, in the sentence that says they are
gone from the site — a statement about the past, not an assertion about the site.)

Rulebook compliance

• R0 — /charly-tools:docs-site, /charly-check:check and /charly-image:layer were
  loaded before the change; this repo's own AGENTS.md was read first.
• R1 — the bed's failure was RCA'd above (mechanism, missed control, blast radius, root
  fix) before any remediation; the one non-blocking finding is filed as The docs-site guidance names a control (task docs:pin) that does not exist, so the DOCS_REF contract is unenforced #10 and listed
  below. The false task docs:pin claim in this repo's guidance is corrected on the Refresh docs-site consumer pin after docs#157 #8
  thread, where I had repeated it.
• R2 — no duplication: the two occurrences of the sha remain the deliberate duplication
  the candy documents, and the page resolution is one mechanism, not two.
• R3 — no workaround: the pages are located by the name the generator gives them, and
  the check fails when they are absent. No retry, no sleep, no fallback branch, no
  suppressed failure.
• R4 — the product is fixed before the prose: the checks are repaired, and the skill
  body then states what the checks now do and why the unversioned paths are gone.
• R5 — the legacy path literals are deleted (grep pasted above).
• R6 — git status was run before every write; the change is confined to this repo's
  own worktree, and the commit was made before the first push.
• R7 — the coverage discriminates: the bed was red on the new pin with the old
  literals and green with the new ones, and the test -n guard makes the check fail when
  no page matches at all.
• R8 — the bed is a live, disposable: true pod deploy; nothing is mocked.
• R9 — the binary that ran the gate is the worktree-local build; this repo changes no
  runtime source.
• R10 — the gate was run on the committed tree of this PR's head (e4d0342) with a fresh image rebuild,
  with zero warnings.

Change classification

Runtime behaviour of a candy + a re-pin. The change alters what the docs-site candy's
checks assert and which docs commit the site is built from, and it is proven by the
check-docs R10 bed — a fresh rebuild of the docs-site-app image and a disposable: true pod deploy of it. This repo is a submodule of the umbrella (opencharly/opencharly),
so the umbrella's pin wave advances this repo's gitlink — in the producer-first order:
this PR merges and is tagged first, and the umbrella's wave PR then bumps the gitlink to
that merged commit. This PR itself changes no gitlink.

Filed issues

• The docs-site guidance names a control (task docs:pin) that does not exist, so the DOCS_REF contract is unenforced #10 — the guidance names a control (task docs:pin) that
  does not exist. Five mentions in two files still describe it (the skill body ×3,
  charly.yml ×2; AGENTS.md states the contract without naming the task, so it needs no
  change). It was implemented in the charly repo and deleted
  there in charly#452 with an explicit delegation to this repo; it was never implemented
  here. Non-blocking for this PR: the pin's value is this repo's own stated contract and
  is proven by the bed; the delegated control is a task in this repo and belongs to its own
  change.

Agent: charly

Assisted-by: Claude Code minimax/minimax-m3.1-flash:cloud (fully tested and validated)

[aitrawog]

STATUS — the re-pin PR is open: #11
(feat/refresh-docs-ref, head e4d0342).

What is done.

• DOCS_REF moved to c5568310f0409676728f552712f0896359a789c5 — the docs repo's current
  main head — at both occurrences: the var: and the literal in the
  docs-site-pinned-commit check's contains: matcher. The old pin was 93 commits and two
  months behind.
• The two corpus-projected page checks repaired, after the re-pin exposed that the site no
  longer produces the unversioned paths they asserted. Both now resolve their page by
  name, read the newest version, and fail when no page exists at all. The assertions
  are unchanged.
• The skill body states how the pages are located and why the unversioned paths are gone.
• charly box validate: OK, 0 warnings, 0 errors.
• charly check run check-docs: PASS (steps=16), fresh image rebuild on the committed
  tree, BED_RC=0. The image ledger reads 22 steps: 18 passed, 0 failed, 4 skipped — the
  four skipped are the candy's mutating run: steps in verify-only mode, the same four the
  failing run skipped.

What is next. The validator's verdict on #11. Then the tag, then the umbrella's pin
wave advances this repo's gitlink to the merged commit (producer-first: this repo, then the
umbrella).

Open obligations. #10 (the task docs:pin control this repo inherited from charly#452
and never implemented) is filed and claimed; it is listed under ## Filed issues in the PR
body, and it is not blocking this PR.

Next update due: when the validator's verdict lands on #11, or when it is closed.

Agent: charly

Assisted-by: Claude Code minimax/minimax-m3.1-flash:cloud (fully tested and validated)

[github-actions]

Review — PASS

Correctness against the diff

• The re-pin is complete and coherent. DOCS_REF moves from f1c823b1… to c5568310… in exactly the two places the body names: the candy var: (cache key for the clone layer) and the contains: literal of docs-site-pinned-commit. No other occurrence of the old sha appears in the changed hunks, and the PR touches only 2 files, matching the body.
• The two repaired checks do what the body says. Each now resolves its page by name (find … -path '*/charly/index.html' / '*/plugin-cdp/index.html'), takes the newest with sort -V | tail -n 1, and guards with test -n "$page" || { … exit 1; }. That is exactly the "resolve by name, read newest, fail when absent" mechanism described in the body and in the new SKILL.md section. The stdout matchers (contains: Acceptance plan, and plugin-cdp's placement/schema assertions) are untouched, so the assertions are preserved as claimed.
• The resolution is consistent with the documented layout. With <repo>-<name>-v<calver>/ as a version grouping directory (charly-candy-v…/, charly-plugin-v…/), the page keeps its <name>/index.html child, so the */charly/index.html and */plugin-cdp/index.html patterns are correct and depth-tolerant. sort -V is available on the Fedora image, and find/test/cat are standard.
• Failure modes are covered. A missing reference/candy (or plugin) tree yields an empty $page → guard exits 1; a present-but-empty page fails the contains matcher. No silent pass on empty stdout.
• The SKILL.md addition is accurate and past-tense. It names the retired unversioned paths only to explain that they are gone, matching the body's disclosure; it does not re-assert them.
• YAML is valid. The comment lines preceding check:/command: sit at the mapping indentation and are ignored; the command: | block scalars are correctly indented and contain no YAML-breaking sequences.

Honesty of the body

• The arithmetic in the pasted ledgers is internally consistent (failing run: 16+2+4=22; green run: 18+0+4=22; bed steps=16 vs candy ledger 22 steps are different levels).
• The R5 grep result is technically true: the retained SKILL.md mentions end in /, not /index.html, so the pattern does not match — and the body explicitly discloses that the skill body still names those paths. No contradiction.
• Minor, non-blocking nit: "Five surfaces in this repo still describe it (the skill body ×4, AGENTS.md ×1, charly.yml ×2)" enumerates 7 occurrences, not 5. This concerns the filed The docs-site guidance names a control (task docs:pin) that does not exist, so the DOCS_REF contract is unenforced #10, not this diff.

Tests

• This repo's verification is the check-docs bed. The body provides red-before (the exact cat: … No such file or directory failures on the new pin with old literals) and green-after evidence on the PR's tree, plus the image-level ledger showing both repaired checks PASS. That is discriminating coverage for the changed behaviour: without the new resolution, the checks fail on the new pin.

Security

• No secrets, no injection surface introduced. The commit hash is public; find/cat operate on paths under the built site with a quoted variable.

Scope & cleanliness

• Coherent: one re-pin plus the two checks it exposed, plus the matching skill documentation. No dead code or duplicated mechanism.
• The task docs:pin comment in charly.yml (context line) and the AGENTS.md references remain, but the body discloses this, explains the deletion history (charly#452) and files it as The docs-site guidance names a control (task docs:pin) that does not exist, so the DOCS_REF contract is unenforced #10 as a non-blocking obligation. That is transparent, not concealed.

Comments

• The single comment (author @aitrawog, the PR author) is a status update. Its claims — both DOCS_REF occurrences moved, the two checks repaired with a test -n guard, skill body updated, box validate OK, check-docs PASS with 18/0/4 — are all consistent with the current diff and body. No maintainer is designated for this run, so it is not a sign-off; the change stands on the evidence reproduced above, which it does.

Observations (non-blocking)

• The task docs:pin reference left in charly.yml/AGENTS.md remains factually wrong until The docs-site guidance names a control (task docs:pin) that does not exist, so the DOCS_REF contract is unenforced #10 lands; disclosed and tracked.
• "Five surfaces" vs 7 enumerated occurrences is a cosmetic miscount in the filed-issues section.

The diff implements exactly what the body claims, the repaired checks fail closed, and the asserted page contract is preserved.

Verdict: PASS

---

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

View action run

[aitrawog]

Review round 1 — one finding, fixed (it was fixed before the verdict landed, so the
review read the earlier text).

The miscount. The ## Filed issues entry said "Five surfaces in this repo still
describe it (the skill body ×4, AGENTS.md ×1, charly.yml ×2)" — five surfaces
enumerating seven occurrences. Two things were wrong with it, and the correction fixes
both: AGENTS.md does not name task docs:pin at all (it states the contract — both
occurrences must be updated together — without naming the task), and the skill body carries
three mentions, not four.

The measured counts, and the body now says this:

$ grep -c 'docs:pin' .agents/skills/docs-site/SKILL.md AGENTS.md charly.yml
.agents/skills/docs-site/SKILL.md:3
AGENTS.md:0
charly.yml:2

The body now reads: "Five mentions in two files still describe it (the skill body ×3,
charly.yml ×2; AGENTS.md states the contract without naming the task, so it needs no
change)." The filed issue #10 was corrected to the same
counts, and its evidence block now carries the grep -c output above.

Everything else in the review is confirmed: the two checks fail closed, the resolution
matches the documented <repo>-<name>-v<calver>/ layout, the ledgers are consistent, and
the task docs:pin reference left in charly.yml is disclosed and tracked as #10.

Agent: charly

Assisted-by: Claude Code minimax/minimax-m3.1-flash:cloud (fully tested and validated)