You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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:
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:
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>
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:
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:**CLIdocs/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 readsAgentRun + Runtime Runner. No such symbol exists; the English edition and the code useRuntimeKernel.ARCHITECTURE.zh-CN.md:20: the language link reads[ENGLISH], where other bilingual documents use[English].docs/agent-swarm.md:68: saysAiSdkBackendappendsrenderSwarmModePrompt(). It isAiSdkTurn(packages/runtime/src/ai-sdk-turn.ts:1440).README.md:174/README.zh-CN.md:173: thenative/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 declaresinfo-light/info-dark, while the Status families paragraph (line 184) states that Maka has no--infocolour. No token file defines one.DESIGN.md:17:surface-overlay-darkis0.225.apps/desktop/src/renderer/maka-tokens.cssderives 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 strayversion=0.1.0in the dist-tags step. The command does not use it, and it overwrites the0.2.0the 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 saysmachine path <name> is unavailablemeans 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:172for the throw on:173.website/README.md:51: says the published.asf.yamlcarries "just"whoamiandautostage. The workflow also writesstaging.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:Render the CLI README line with GitHub's renderer:
git grep -n "Runtime Runner\|RuntimeRunner" -- '*.ts'returns nothing.Compare each remaining item with the source line cited next to it.
Environment
0cb4fc32bdff3587bd5cc609fbe0eb28efa4233fLogs, 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:
ARCHITECTURE.mdreading-path status for the Desktop conversation projection, fixed in docs: fix stale file references and statuses #5292;docs/architecture/windows-sandbox-rfc-v1.zh-CN.md:159, which docs(architecture): reconcile Windows sandbox RFC bilingual pair #5342 is reconciling.I'd like to fix this myself and will open a PR shortly.
Prepared and posted by Claude Code on behalf of @MasamiYui.