[freeqaz]

Problem

docs:check-length enforces a 2,500-word hard limit, and it was the most common CI failure on 2026-10-03. #1077 and #1078 trimmed ten at-cap pages. Fourteen more sat at 2,461-2,499 words, so almost any edit to them failed CI. This PR covers seven of them. The companion PR covers the other seven.

The channels guide also named the Slack card buttons Configure, Edit and Disable, but the console renders Configure Slack, Edit Slack and Disable Slack (apps/controller/src/console/channels/shared-ui.mjs).

Page	Before	After
docs/flows/native-service-account-credential-delivery.md	2,499	2,301
docs/flows/workspace-files.md	2,497	2,312
docs/flows/harness-execution-topology.md	2,493	2,301
docs/guides/deploy/local-kubernetes-development.md	2,490	2,295
docs/guides/topics/agent-logs.md	2,489	2,303
docs/contributing/console-storybook.md	2,478	2,309
docs/guides/deploy/production-installation.md	2,461	2,294

Change

• Merge sentences that restate a fact already on the same page.
• Where a page repeats detail that another page owns, replace the copy with a link to that page's section, following the one-owner rule in AGENTS.md. Each target section was checked to state the removed fact.
• No headings were added, removed or renamed, so inbound anchors are unchanged. No page was split.
• Mid-sentence "gateway" is lowercase where it means the Agent's gateway, as docs/guides/concepts.md defines. Proper names (OpenShell Gateway, Envoy Gateway, the Kubernetes Gateway API) keep their capitals.
• docs/guides/console/channels-and-credentials.md: use the rendered Slack button labels.
• docs/reference/cli.md: occ agent logs needs Agent read_logs or administer, as the API authorizes (getAgentDeploymentRuntimeLogs) and the logs guide and security reference already say, not administer only.
• docs/guides/topics/agent-logs.md no longer says the CLI waits out 429 in general; the CLI reference (linked) says it waits only with --follow, which matches internal/occcli/cli.go.
• The length limit itself is unchanged.

Verification

• pnpm docs:check on the combined state of both PRs: no page over the hard limit; 237 pages and 3,635 links validated; 76 spec documents validated.
• prettier --check on the changed files: clean.
• An independent review compared every page before and after, sentence by sentence, and checked each linked section. It found no wrong facts and no broken links, but six small lost or weakened facts (the draft is not a version, deleted Pods keep no logs, API and worker Pods wait for the root Secret, local checks do not prove deployed acceptance, initial deployments share the startup path, two Storybook notes) and one narrowed link. The second commit restores them.
• Button labels checked against shared-ui.mjs and tests/browser/console-agent-channels.test.mjs, which click Edit Slack and Disable Slack.
• Docs-only change, so no tests were run (per AGENTS.md).

Risks

Low; documentation only. Open PRs that also edit these pages may need a textual conflict resolution: #925, #913, #906, #884, #830, #662, #519, #489, #479, #307, #302, #299, #253 and #252.

[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]

ClawSweeper status: review started.

I am starting a fresh review of this pull request: docs: trim seven near-cap flow and guide pages under the word limit This is item 1/1 in the current shard. Shard 0/1.

This temporary status tracks the active review worker. The completed review will appear in the durable ClawSweeper review comment.

Crustacean status: shell secured, claws on keyboard, evidence pebbles being sorted.