Skip to content

docs: fix unrendered bold, stale names, and stale values - #5625

Open
MasamiYui wants to merge 1 commit into
apache:mainfrom
MasamiYui:docs/fix-doc-rendering-and-stale-values
Open

MasamiYui wants to merge 1 commit into
apache:mainfrom
MasamiYui:docs/fix-doc-rendering-and-stale-values

Conversation

@MasamiYui

Copy link
Copy Markdown
Member

Summary

Point fixes for documentation that either renders wrong on GitHub or npm, or contradicts the code it describes. #5624 lists every item with the source line it was checked against.

  • Unrendered bold. A closing ** right after a full-width : and before a letter is not right-flanking under CommonMark, so the asterisks print literally. The colon moves outside the emphasis in three places: the CLI Chinese README, the agent-graph scheduling draft, and the Chinese Nightly notice that scripts/release-cli-package.mjs prepends to the npm README.
  • Stale names. ARCHITECTURE.zh-CN.md: Runtime Runner → RuntimeKernel (matching the English edition and the code), [ENGLISH] → [English]. docs/agent-swarm.md: AiSdkTurn, not AiSdkBackend, appends the swarm prompt. The README native/ entry now names the Windows task launcher.
  • Stale values.
    • DESIGN.md: drop the info-light/info-dark frontmatter the document itself says does not exist, set surface-overlay-dark to the derived 0.223, and repair one unparseable sentence.
    • packages/ui/README.md: five export surfaces, not four.
    • docs/cli-npm-release*.md: drop a stray version=0.1.0.
    • ACP README: state the 175 → 176 epoch bump as past (feat(cli): isolate ACP MCP per Session (PR5 γ) #5386).
    • Eval troubleshooting: correct the cause of machine path ... is unavailable and refresh stale line references.
    • website/README.md: mention staging.profile: ~.

Fixes #5624

Left out to avoid overlapping open work: the ARCHITECTURE.md projection status (#5292), and the same bold problem in docs/architecture/windows-sandbox-rfc-v1.zh-CN.md (#5342).

Verification

  • GitHub's renderer (gh api -X POST /markdown -f mode=gfm): > **Beta:**CLI renders literal **; > **Beta**:CLI renders <strong>Beta</strong>. The repository's marked gives the same result for all five changed emphasis spans.
  • A whole-document marked render of every non-archive Markdown file finds no remaining literal **, except windows-sandbox-rfc-v1.zh-CN.md, which is left for docs(architecture): reconcile Windows sandbox RFC bilingual pair #5342.
  • Relative-link and heading-anchor checks across all tracked Markdown: 0 broken.
  • npx biome format ., npx biome lint ., npm run check:asf-headers, and node --check scripts/release-cli-package.mjs all pass.
  • Each factual edit was re-checked against the cited source line at 0cb4fc32b.
  • Not run: build, typecheck, and test suites. The only non-Markdown change is one string literal in the release script, and no test asserts on it.

AI use

Select exactly one:

  • No generative tool made a substantive contribution
  • Generative tooling made a substantive contribution

Tool(s) and scope: Claude Code audited the docs against the code, verified each item, and drafted the edits, the issue, and this description. The commit carries a Generated-by: Claude Code trailer.

Checklist

  • Tests cover the change and fail without it (not applicable: documentation and one notice string)
  • Lint, format, typecheck and the affected suites pass locally (lint and format pass; typecheck and suites not run, no TypeScript changed)

Does this PR entail a change in behavior?

  • Yes — described under Summary above
  • No

🤖 Generated with Claude Code

- Bold closed right after a full-width colon and before a letter is not
  right-flanking under CommonMark, so GitHub and npm print the asterisks.
  Move the colon outside the emphasis in the CLI Chinese README, the
  agent-graph scheduling draft, and the Chinese Nightly npm notice.
- ARCHITECTURE.zh-CN.md: `Runtime Runner` -> `RuntimeKernel`, and
  `[ENGLISH]` -> `[English]`.
- agent-swarm.md: `AiSdkTurn`, not `AiSdkBackend`, appends the swarm prompt.
- README native/ entry: name the Windows Runtime Host task launcher.
- DESIGN.md: drop `info-light`/`info-dark` (the document states there is no
  info colour), correct `surface-overlay-dark` to the derived 0.223, and
  repair the unparseable `--warning` sentence.
- ui README: five export surfaces, not four.
- cli-npm-release: drop the stray `version=0.1.0` from the dist-tags step.
- ACP README: state the 175 -> 176 epoch bump as past (apache#5386).
- eval README: `machine path ... is unavailable` means the env var is unset;
  refresh stale install-preflight line references.
- website README: the published .asf.yaml also sets `staging.profile: ~`.

Fixes apache#5624

Generated-by: Claude Code
Co-Authored-By: Claude Code <noreply@anthropic.com>
@github-actions github-actions Bot added the effort/S Under 100 readable lines label Sep 23, 2026

@hqhq1025 hqhq1025 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Reviewed the current 14-file documentation and prompt-text change. I found no substantiated P0–P3 issue in the inspected text and cross-references; the diff check and script syntax check pass. I did not run the complete test suite or render all affected documentation/UI surfaces, so this comment does not establish visual or end-to-end correctness.

Automated review notice: This comment was posted by an automated review agent operated by hqhq1025. It is not an independent human review and does not replace one.

@me2seeks me2seeks left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Automated review notice: This comment was posted by an automated review agent operated by me2seeks make. It is not an independent human review and does not replace one.

Summary

Docs-only PR fixing CommonMark unrendered bold (closing ** after full-width : before a letter is not right-flanking, so it prints literally), stale symbol names, and stale values across READMEs/DESIGN.md, plus one notice string in scripts/release-cli-package.mjs. The premise is real in base (e.g. packages/cli/README.zh-CN.md:36 has > **Beta:**CLI; packages/eval/README.md:285 misattributes the machine path ... is unavailable cause), and every factual edit I re-checked against the PR-head tree matches the code. Direction is right: point fixes at the doc layer, no new abstractions.

Findings

  1. [P3] packages/ui/README.md:45 — The PR corrects "Four export surfaces" to "Five" to match the layer-map table (verified: 5 rows), but the same file's Consuming section still lists only four sub-path exports (artifact-preview-registry, assistant-stream, icons, maka-uri) while packages/ui/package.json:10-21 declares 12 subpaths (client-plugin, client-plugin-runtime, testing, styles.css, composer-attachments, pending-items, use-composer-attachments, …). Same class of stale-doc defect this PR exists to fix, left behind in the same file.

Verification log (all confirmed against PR-head worktree, no other material findings):

  • Bold fix validity: CommonMark right-flanking rule confirmed; closing ** preceded by : (punctuation) and followed by a letter/CJK cannot close emphasis. Applies to all three sites; windows-sandbox-rfc-v1.zh-CN.md exclusion is disclosed and tracked in #5342.
  • ARCHITECTURE.zh-CN.md:30 RuntimeKernel matches ARCHITECTURE.md:30; docs/agent-swarm.md:68 AiSdkTurn matches packages/runtime/src/ai-sdk-turn.ts:610 (class) and :1440 (renderSwarmModePrompt() appended).
  • DESIGN.md:17 0.223 matches the derived value stated in apps/desktop/src/renderer/maka-tokens.css:130-133 ("OKLab L 0.223"); info-light/info-dark have zero references repo-wide, so dropping the frontmatter pair is safe.
  • packages/eval/README.md line refs exact: install-preflight.ts:297,303 (if (!value) throw … is unavailable), :285,289 (is not a directory / is not writable and searchable), :173 (Docker), :155-157 (Python env). Cause correction (unset/empty vs. bad path) matches code.
  • ACP epoch phrasing corroborated by packages/cli/src/acp/VALIDATION.md:25 (175→176); past-tense anchoring is an improvement since the live epoch is now 182 (packages/runtime-host/src/protocol/index.ts:106).
  • native/runtime-host-windows-task-launcher exists, matching the README native/ entry.
  • No test asserts on the changed nightly-notice string (scripts/smoke-release-cli-package.mjs does not match it); CI rollup is all-pass.
  • Unverifiable from repo (not a defect): website/README.md:51 staging: profile: ~ describes the published branch's .asf.yaml, which is not tracked in-tree; consistent with asfyaml/OpenDAL convention.

Verdict

merge-ready — every factual claim re-verified against the code; the single minor item is an adjacent stale export list in packages/ui/README.md that can land as a follow-up.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

effort/S Under 100 readable lines

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: unrendered bold, stale names, and stale values across READMEs and design docs

3 participants