[aitrawog]

Summary

Docs-only leg of umbrella campaign opencharly/opencharly#286 for the
opencharly/layer-docs-site repo. This repo gets its tailored pair:

• README.md — user overview only. Rewritten from the generic candy-catalog
  boilerplate into a real user overview: the Astro + Starlight toolchain that
  clones opencharly/docs at a pinned commit and builds the production site;
  the docs-site-app box and check-docs disposable: true bed; the
  load-bearing docs-site-runtime-plugin-page check; a pinned
  @github.com/opencharly/layer-docs-site:v2026.269.1347 consumption example; a
  brief layout; and pointers to the owning skill.
• AGENTS.md — new, thin, harness-neutral agent signpost. What the repo is
  and its canonical files; the R0 skill list (/charly-tools:docs-site +
  /charly-check:check + /charly-image:layer); the exact build/validate/test
  statement (the org-wide charly/pr-validator gate, validate / validate —
  this repo has no per-repo candy gate); the edit rules (incl. the
  two-occurrence DOCS_REF pin); and landing, which points at the owning
  rulebook + /charly-internals:git-workflow instead of restating the rules.

No functional or architecture file is touched; charly.yml, CHANGELOG/ and
the workflow are byte-identical to origin/main.

Review round

The first head 208dfd2e4bca904c2dd2dc139523e81ccf8ef0e5 returned one BLOCK with
two findings, both fixed in ONE follow-up commit on the same branch:

1. R1 — mutually exclusive check-context claims. The README said "every check
   is build-context"; the charly.yml checks all declare
   context: [build, runtime]. Corrected the README to state the real context
   set (both build and runtime) once, matching the manifest.
2. A1 — the signpost restated landing rules. The AGENTS.md "Landing"
   section now points at the authoritative rulebook and
   /charly-internals:git-workflow and names the CHANGELOG/ home, rather than
   restating "PR-only … direct pushes are blocked".

How tested

On the final committed head a1343145440946e1fad6787c2546f6b5e010cd05:

### layer-docs-site
$ git -C <cwt> ls-files .github/workflows
.github/workflows/tag-on-merge.yml

$ git -C <cwt> diff --stat origin/main..HEAD
 AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 README.md | 81 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++----
 2 files changed, 137 insertions(+), 5 deletions(-)

$ git -C <cwt> diff --name-only origin/main..HEAD | grep -v '\.md$' || echo '(none)'
(none)

Docs-only: every changed path is *.md; no non-.md file changed, so the
manifest and the workflow are untouched.

Rulebook compliance

Umbrella AGENTS.md rules 1–11:

1. Never edit inside a submodule — HOW: edited only in the session worktree .worktrees/layer-docs-site-docs11; the tracked submodule checkout stays clean/detached.
2. Git op rule (git -C <abs>) — HOW: every git/gh action ran via git -C <absolute-path> / --repo.
3. No nested go.work — N/A — no Go workspace file touched.
4. Sessions root at the umbrella; edits in a session worktree off fresh origin/main — HOW: worktree branched off origin/main; base confirmed unchanged (merge-base == origin/main).
5. Pin discipline (merged refs only) — N/A — no pin/gitlink changed.
6. Policy B (distro pins == charly gitlinks) — N/A — no submodule gitlink touched.
7. Read the subrepo's own rulebook first — HOW: read the umbrella AGENTS.md, charly/AGENTS.md, and the dispatched skills (git-workflow, skills, layer, check).
8. Harness config: shared core + deliberate forks — N/A — no harness config changed.
9. Session-scoped ownership — HOW: only this session's worktree/branch/PR touched; other sessions' worktrees untouched.
10. Before ANY update push, read the PR's live state AND write the body — HOW: the BLOCK verdict was read IN FULL, both findings fixed in ONE commit, and the whole body re-keyed to the new head before the update push, footer last.
11. Agent identity & comment coordination footer (extends rule 9) — HOW: two-line Agent:-then-Assisted-by: footer in canonical order; solo/uncontended scope.

Ground-truth rules R1–R10 (charly/AGENTS.md):

• R1 (RCA every anomaly) — HOW: the first head's validator BLOCK named the README-vs-manifest check-context divergence; the README now states the manifest's real context: [build, runtime] set. No other failure/warning surfaced.
• R2 (finish the whole cutover; no parking) — HOW: the docs-only change class is delivered in full (README user overview + AGENTS signpost), and both BLOCK findings are fixed in the same branch; the candy carries a skill: entity, so the signpost names the projected owning skill.
• R3 (no duplication) — HOW: README points at the owning skill instead of restating it; AGENTS points at the rulebook + /charly-internals:git-workflow instead of restating landing rules.
• R4 (no workarounds) — HOW: no ad-hoc substitute command; the change is prose only.
• R5 (delete legacy completely) — HOW: the generic catalog boilerplate README was replaced, not appended; no stale scaffold claim remains.
• R6 (git safety) — HOW: status inspected before/after; the fix is an ADDED commit (no force-push, no hook bypass, no direct push to main); no other session's work touched.
• R7 (prove the gate, not the plan) — HOW: the pasted evidence above is from the final committed tree; every changed path is a .md.
• R8 (preserve emitted artifacts) — N/A — docs-only; no emitted artifact/config changed.
• R9 (binary equals source) — N/A — this repo ships no charly source/binary.
• R10 (fresh proof by change class) — HOW: Documentation-only change class → documentation reviewed tier (charly/AGENTS.md R10: "Documentation-only changes run every non-runtime standard and no invented bed"); the structural proof is the docs-only diff on the final tree, pasted above.

RDD / ADE / SDD — N/A — documentation-only.

Change classification

• Change class: Documentation-only.
• Gate: the org-wide charly/pr-validator (validate / validate); this repo has no per-repo candy gate.
• Attribution tier: documentation reviewed.

Refs #286

Agent: layer-wave11 (subagent of org-readme-agents) · session ses_wave11_layer_docs
Assisted-by: opencode deepseek-v4.1-flash (documentation reviewed)

[github-actions]

Review — BLOCK

Head SHA: 208dfd2e4bca904c2dd2dc139523e81ccf8ef0e5 (branch: feat/tailored-docs)

Change class: Documentation-only (2 changed files, both *.md; no code/config/workflow/submodule touched — confirmed by the diff and the body's --name-only evidence, which is internally consistent: 65+76=141 insertions, 0+5=5 deletions, matching the pasted --stat).

Blocks

1. R1 — the two new docs make mutually exclusive claims about the check contexts. README.md, "How to use it", asserts "every check is build-context"; AGENTS.md, "Build / validate / test", asserts the candy's plan: check: steps "run in BOTH build and runtime contexts". A check: step cannot be build-context-only and simultaneously execute in the runtime context — at least one of these load-bearing statements is false, and the README leans on it to justify "verify without deploying". Reconcile the two to the single true context set (state the actual context(s) once) and re-derive the body's R1 compliance line, which currently asserts "no failure/warning surfaced … no anomaly to root-cause" while this divergence is exactly such an anomaly.

2. A1 — the body's characterization of AGENTS.md is contradicted by the diff. The Summary states AGENTS.md "restates no rule and names no harness", but its "Landing" section restates the org landing rules — "PR-only … Direct pushes to main are blocked" — immediately after declaring "Do not restate its rules here." Either drop the restated rule text so the signpost stays thin (as the umbrella campaign requires) or correct the body's claim; the summary must accurately account for what the file contains.

Verdict: BLOCK

---

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

View action run

[github-actions]

Review — PASS

Head SHA: a1343145440946e1fad6787c2546f6b5e010cd05 (branch: feat/tailored-docs)

Security screen: PASS — docs-only (AGENTS.md, README.md), no secrets/egress/guardrail/supply-chain edits, no embedded directive to the validator.
Checklist: All applicable rules PASS or NA. Docs-only diff (*.md only) → documentation reviewed tier is legal (A3); no bed required (A2/R10); body accounts for both files, pastes internally-consistent --stat (61+76=137 insertions, 5 deletions) and a --name-only | grep -v '\.md$' → (none) sweep; footer ends with the Assisted-by: line preceded by the Agent: line; placement CORRECT (repo-root docs, no code layer touched).

Comment disposition:

• @github-actions[bot] #5881660971 (BLOCK on head 208dfd2e4bca) — stale-superseded against the current head. Finding 1 (R1 context divergence) is resolved: README now reads "every check runs in both the build and runtime contexts", agreeing with AGENTS.md "run in BOTH build and runtime contexts" (the two docs no longer make mutually exclusive claims). Finding 2 (A1 restated landing rule) is resolved: the AGENTS.md "Landing" section now only points at the rulebook + /charly-internals:git-workflow and names CHANGELOG/, containing no restated "PR-only / direct pushes blocked" text.

Verdict: PASS

---

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

View action run