Skip to content

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

Description

@MasamiYui

What happened

Reading the top-level and package READMEs against the current code turned up a set of small, mechanical documentation errors. None of them changes behavior, but each is either visible to readers or contradicts the code it describes.

Bold text that GitHub prints literally. A closing ** placed right after a full-width : and followed by a letter is not right-flanking under CommonMark, so the asterisks render as text:

  • packages/cli/README.zh-CN.md:36: **Beta:**CLI
  • docs/architecture/agent-graph-stream-scheduling-draft.zh-CN.md:374-376: **Observe:**, **Control:**, **Synthesize:**
  • scripts/release-cli-package.mjs:512: the Chinese Nightly notice prepended to the published npm README, **开发快照:**此

Names that no longer match the code

  • ARCHITECTURE.zh-CN.md:30: the diagram node reads AgentRun + Runtime Runner. No such symbol exists; the English edition and the code use RuntimeKernel.
  • ARCHITECTURE.zh-CN.md:20: the language link reads [ENGLISH], where other bilingual documents use [English].
  • docs/agent-swarm.md:68: says AiSdkBackend appends renderSwarmModePrompt(). It is AiSdkTurn (packages/runtime/src/ai-sdk-turn.ts:1440).
  • README.md:174 / README.zh-CN.md:173: the native/ entry names two Rust crates. native/runtime-host-windows-task-launcher (fix(desktop): enable local remote access on Windows #4728) is the third.

Values that contradict the code or the same document

  • DESIGN.md:21-22: the frontmatter declares info-light / info-dark, while the Status families paragraph (line 184) states that Maka has no --info colour. No token file defines one.
  • DESIGN.md:17: surface-overlay-dark is 0.225. apps/desktop/src/renderer/maka-tokens.css derives it as --background (0.205) + 0.018 and pins "OKLab L 0.223".
  • DESIGN.md:184: "because the time warning sat thirty lines from its siblings is the time it lost its dark value" does not parse.
  • packages/ui/README.md:28: "Four export surfaces" introduces a five-row table.
  • docs/cli-npm-release.md:252 / docs/cli-npm-release.zh-CN.md:227: a stray version=0.1.0 in the dist-tags step. The command does not use it, and it overwrites the 0.2.0 the rest of the runbook uses.
  • packages/cli/src/acp/README.md:138: "move the Host compatibility epoch from 175 to 176" reads as current, but the epoch is now 182 (packages/runtime-host/src/protocol/index.ts:106). The 175 → 176 bump was feat(cli): isolate ACP MCP per Session (PR5 γ) #5386.
  • packages/eval/README.md:285: the troubleshooting row says machine path <name> is unavailable means the directory does not exist or is not writable. That message is thrown only when the env var is unset or empty (packages/eval/src/install-preflight.ts:297,303); unusable paths fail with other messages (:285,289). The cited lines (:273,279) are stale, and row 287 cites :172 for the throw on :173.
  • website/README.md:51: says the published .asf.yaml carries "just" whoami and autostage. The workflow also writes staging.profile: ~ (.github/workflows/website.yml:100).

Expected: each document matches the code it describes, and bold text renders on GitHub and npm.

How to reproduce

From 0cb4fc32bdff3587bd5cc609fbe0eb28efa4233f:

  1. Render the CLI README line with GitHub's renderer:

    gh api -X POST /markdown -f mode=gfm -f text='> **Beta:**CLI 仍在积极开发中'
    # <blockquote><p>**Beta:**CLI 仍在积极开发中</p></blockquote>
    gh api -X POST /markdown -f mode=gfm -f text='> **Beta**:CLI 仍在积极开发中'
    # <blockquote><p><strong>Beta</strong>:CLI 仍在积极开发中</p></blockquote>
  2. git grep -n "Runtime Runner\|RuntimeRunner" -- '*.ts' returns nothing.

  3. Compare each remaining item with the source line cited next to it.

Environment

  • Maka commit: 0cb4fc32bdff3587bd5cc609fbe0eb28efa4233f
  • OS: macOS 26.6.2
  • Surface: documentation (plus one generated npm README string)
  • Node.js: v24.21.0

Logs, screenshots, or additional context

This issue is limited to the point fixes above; it is not a subsystem pass for #3522. It deliberately leaves out two items already covered by open work:

I'd like to fix this myself and will open a PR shortly.

Prepared and posted by Claude Code on behalf of @MasamiYui.

Activity

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

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

No type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions