[freeqaz]

Problem

After the Credential Proxy implementation (#2487), several docs no longer matched the code (finding 2220):

• Production startup flow. docs/flows/production-startup.md still cited platform.ts:composeRepoDriver. It also said the Installation's drivers.repo must select the Backend's Driver. Composition is now composeRepositoryAccess, keyed on repository.id, and startup refuses an Installation drivers.repo.
• Breaking-changes guide. docs/guides/deploy/breaking-changes.md had no entry for Credential Proxy Implementation #2487's retirements: Installation drivers.repo, drivers.conduit, Helm openshellGit.mode: broker-trial, and preview databases. Those refusals reach the pod log only as STARTUP_FAILED.
• Backend examples. The examples in docs/reference/backends.md and docs/reference/drivers/openshell-credential-gateway.md used /etc/openclaw/openshell/token, operator.crt and operator.key. Helm backend.openshell.clientSecretName projects only ca.crt, tls.crt and tls.key, so chart users following those pages hit missing files at the first gateway call.

Change

• Production startup flow: traces composeRepositoryAccess. It says the Backend's drivers.repo member must equal repository.id, that native delivery adds the public CA and the Unix client, and that the retired Installation drivers.repo is refused. Total words go down.

• Breaking changes: a new 2026-10-22 entry in the usual format (what breaks, who is affected, how to tell, steps). It covers:

  • the Helm repositoryCredentials signing-broker retirement (authority must be prepared-git with preparedCustodySecretName);
  • Installation drivers.repo;
  • Installation or Backend drivers.conduit;
  • openshellGit.mode: broker-trial;
  • the migrator's refusal of preview databases.

  It says which refusals come from Helm render, which from the upgrade check and which from the migrator. It also says that the startup logs show only STARTUP_FAILED or WORKER_STARTUP_FAILED. It links the Credential Proxy upgrade guide and says to drain on the original release.

• Breaking-changes archive: the 2026-10-14 notices move unchanged to a new breaking-changes-before-2026-10-15.md. That keeps the page under the word limit with this week's entries (other open PRs add two more). The new page is in docs.json, and the main page and every older archive page link to it. The one inbound anchor link, from the production-startup flow, now points to the new page.

• Backend examples: both now use mode: mtls with the chart-projected tls.crt, tls.key and ca.crt. backends.md says which files the chart mounts. Because the chart mounts no separate operatorTls pair, chart installs cannot retrieve Codex OAuth access tokens. The Credential Gateway example's comment now says Codex also needs operatorTls, with no change in word count.

Verification

• docs:check passes locally: word limits, the docs-site build check (290 pages, 4549 links) and the spec check.

• Word counts: breaking-changes.md 751, the new page 1748, production-startup.md 2485, backends.md 2422, openshell-credential-gateway.md 2493.

• Internal review: changes requested, all applied:

  • the missing Helm broker retirement;
  • preview-only scoping;
  • which tool reports each refusal;
  • the Codex OAuth consequence;
  • the Backend drivers.conduit member;
  • links from every older archive page.

  The reviewer confirmed against the code that the startup-flow paragraph is accurate, that the moved notices are byte-identical, and that the examples match the chart and the Backend schema.

• Docs only, so no tests (repo policy).

• It merges cleanly with the other open fixes in this series that touch the same pages (fix(repository): refuse an App key that cannot sign at worker startup #3258, fix(helm): refuse authority file paths the chart does not mount #3261).

Risks

• Docs only. Moving the 2026-10-14 notices changes their URLs. The one inbound anchor in the repo is updated, but external bookmarks to breaking-changes.md#2026-10-14-... will land on the page top.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge.

What this changes

This PR updates repository startup documentation, adds Credential Proxy retirement guidance, corrects OpenShell certificate examples, and archives older notices.

Example: An operator configures the OpenShell Backend using Helm backend.openshell.clientSecretName.

• Before: The example selects bearerTokenFile at /etc/openclaw/openshell/token, which the chart does not mount.
• After: The example selects mtls using the chart-projected /etc/openclaw/openshell/tls.crt and tls.key.

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A useful, source-backed documentation correction with passing exact-head checks and no actionable findings; no local build or runtime execution was performed.
Proof confidence	🌊 off-meta tidepool	Not applicable: Documentation-only changes were checked against composition, configuration parsing, Helm mounts, startup diagnostics, and existing coverage; the runtime proof gate does not apply.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Product

Kind: Docs · Worth it: Yes · Fix scope: Complete
User problem: Operators following the current documentation encounter missing credential files or outdated repository configuration guidance.
Reason: The maintainer-authored direction corrects source-verifiable documentation errors with a focused change.

Merge readiness

✅ Ready for maintainer review

Keep this PR open for maintainer triage: it corrects documentation that remains stale on current main, and no actionable defect was found in the introduced changes.

Priority: P3
Reviewed head: b58b652fa47215e3c20e68dd7b0afeef5775046b

Before merge

None.

Findings

None.

Agent review details

How this fits together

The documentation connects Installation configuration and Helm-projected credentials to controller startup, repository access composition, and OpenShell gateway clients.

flowchart LR
  A[Operator configuration] --> B[Helm file mounts]
  A --> C[Installation loader]
  B --> D[API and worker composition]
  C --> D
  D --> E[Repository policy and senders]
  D --> F[OpenShell gateway clients]

Loading

Technical review

Best possible solution:

Land the focused documentation corrections while preserving the existing runtime contracts and explicit OpenShell qualification limits.

Do we have a high-confidence way to reproduce the issue?

Source inspection confirms that current main documents a removed composition symbol and certificate files absent from the chart; no runtime execution was needed to establish those mismatches.

Is this the best way to solve the issue?

The change uses the existing documentation owners, matches the current loader and chart, and preserves archived notice text without introducing another runtime path.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 6f6a955813f7.

Provenance checked

• Repository startup composition changes intended behavior with a stated reason (f267d95: The earlier repository lifecycle work documented GitHubRepoDriver composition; the merged Credential Proxy implementation replaced that composition with repository policy and optional native delivery.)
• OpenShell Backend authentication example changes intended behavior with a stated reason (d4f544c: The Credential Gateway implementation introduced the shared OpenShell Backend and bearer-token example; this PR aligns the example with the files Helm actually projects while retaining bearer authentication in the reference contract.)
• Codex OAuth operator certificate example keeps the original intent (23965d6: Codex OAuth added a separate operator identity for access-token retrieval; this PR preserves that requirement and explains why the standard chart mounts do not supply it.)
• Breaking-change archive rotation keeps the original intent (c742f82: The earlier archive split established date-based pages to stay within the documentation word limit while preserving notice bodies and repairing links.)

Security

None.

Evidence

What I checked:

• Policy applied: Read the complete root AGENTS.md and technical-writing guidance; no nested AGENTS.md, maintainer-notes directory, or pr-simplify skill was found for these paths. Documentation-only changes require no tests. (AGENTS.md, b58b652fa472)
• Current main still needs the corrections: Current main retains composeRepoDriver and the unmounted bearer-token/operator certificate examples; the PR replaces them with the current composition symbol and chart-projected certificate paths. (docs/reference/backends.md:139, 6f6a955813f7)
• Startup description matches source: composeRepositoryAccess checks the Backend repository member, loads the registry, constructs GitHubRepositoryPolicy, and adds the public CA and Unix client for native delivery; Installation loading explicitly refuses drivers.repo and drivers.conduit. (apps/controller/src/composition/repository-credentials/platform.ts:24, b58b652fa472)
• Certificate examples match packaging: The chart projects only ca.crt, tls.crt, and tls.key into /etc/openclaw/openshell; existing packaging coverage asserts those exact files, while credential retrieval separately requires operatorTls. (deploy/helm/openclaw-enterprise/templates/deployments.yaml:68, b58b652fa472)
• Archive content preserved: A direct comparison found the moved notice bodies identical. Navigation and the incoming hostname anchor link point to the new page. The author explicitly accepts changed external bookmark destinations; the longer pages retain coherent startup, reference, or dated-notice scopes. (docs/guides/deploy/breaking-changes-before-2026-10-15.md:9, b58b652fa472)
• Linked implementation and distinct follow-ups: The merged Credential Proxy implementation at Credential Proxy Implementation #2487 explains the retired selections and preview-history refusals. The signing-key repair at fix(repository): refuse an App key that cannot sign at worker startup #3258 and chart-path validation at fix(helm): refuse authority file paths the chart does not mount #3261 address separate behavior and do not replace these corrections. (docs/guides/deploy/breaking-changes.md:56, 31156790238d)

Likely related people:

• Mrunal Patel: Raw commit d4f544c adds docs/reference/backends.md:120 relative to its recorded parents. This identifies author metadata, not feature responsibility or a PR merger. (role: source-line author; confidence: high; commits: d4f544c4eee8; files: docs/reference/backends.md)

Labels

Label changes:

• add P3: This is documentation maintenance that corrects operator examples and upgrade guidance without changing runtime behavior.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Label justifications:

• P3: This is documentation maintenance that corrects operator examples and upgrade guidance without changing runtime behavior.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR.

Rating scale

6/6 🦀 challenger crab · 5/6 🦞 diamond lobster · 4/6 🐚 platinum hermit · 3/6 🦐 gold shrimp · 2/6 🦪 silver shellfish · 1/6 🧂 unranked krab. Overall follows the weaker of proof and patch quality; ✨ marks media proof (a screenshot, video, or linked artifact) that directly shows the changed behavior.

Workflow

ClawSweeper edits this one comment on every review. Comment @clawsweeper re-review for a fresh review only. Repair and merge execution lanes are retired.

Reviewed October 22, 2026, 10:57 PM ET / October 23, 2026, 02:57 UTC.