maka-agent 0.2.0-dev.6.20260830 → 0.2.0-dev.64.20260929

package/DISCLAIMER-WIP

@@ -11,7 +11,12 @@ policy. For example, releases may have incomplete or un-reviewed licensing
 conditions. What follows is a list of issues the project is currently aware of
 (this list is likely to be incomplete):
 
- * The software grant and committer ICLAs are not yet complete.
+ * The initial-code authorization review remains open at
+   https://github.com/apache/maka/issues/3268. Since RC1, the ASF has recorded
+   the ICLA of contributor Mingqwqqaq, and the Deep Research implementation
+   has been removed. The review still needs to record the authorization basis
+   for the retained initial code; these changes do not establish that an SGA
+   has been filed.
 
 If you are planning to incorporate this work into your product/project, please
 be aware that you will need to conduct a thorough licensing review to determine

package/LICENSE

@@ -203,15 +203,32 @@
 
 THIRD-PARTY COMPONENTS
 
+Vercel Code Mode and run execution-budget patches
+
+Source: https://www.npmjs.com/package/@ai-sdk/code-mode/v/1.0.79
+        https://www.npmjs.com/package/run/v/2.1.4
+Repository: https://github.com/vercel/ai/tree/main/packages/code-mode
+            https://github.com/vercel-labs/run/tree/run%402.1.4/packages/run
+Dependency patches: patches/@ai-sdk+code-mode+1.0.79.patch
+                    patches/run+2.1.4.patch
+Readable source changes: patches/run-2.1.4-source.diff
+Copyright 2023 Vercel, Inc.
+License: Apache-2.0
+
+These patches modify the execution time policy and its SDK forwarding. The
+Apache License, Version 2.0 above applies. The generated run Worker includes
+embedded third-party code; its upstream notices and license texts are retained
+in patches/run-2.1.4-notices.md.
+
 Vercel AI SDK
 
 Source: https://www.npmjs.com/package/@ai-sdk/provider-utils/v/5.0.11
         https://www.npmjs.com/package/@ai-sdk/provider/v/4.0.3
-Patched package: https://www.npmjs.com/package/@ai-sdk/provider-utils/v/5.0.28
+Patched package: https://www.npmjs.com/package/@ai-sdk/provider-utils/v/5.0.51
 Repository: https://github.com/vercel/ai/tree/main/packages/provider-utils
             https://github.com/vercel/ai/tree/main/packages/provider
 Adapted declarations: @ai-sdk/provider-utils 5.0.11, @ai-sdk/provider 4.0.3
-Dependency patch: patches/@ai-sdk+provider-utils+5.0.28.patch
+Dependency patch: patches/@ai-sdk+provider-utils+5.0.51.patch
 Copyright 2023 Vercel, Inc.
 License: Apache-2.0
 
@@ -223,7 +240,7 @@ License, Version 2.0 above applies to the adapted material.
 The pinned versions are the ones present when the adaptation was made. The
 adapted declarations are unchanged through @ai-sdk/provider-utils 5.0.25 and
 @ai-sdk/provider 4.0.7, the versions recorded by the code origin audit. Maka
-also redistributes a patch against @ai-sdk/provider-utils 5.0.28; that patch
+also redistributes a patch against @ai-sdk/provider-utils 5.0.40; that patch
 modifies Apache-2.0 source and is covered by the license reproduced above.
 
 Astryx
@@ -234,9 +251,11 @@ Theme revision: ea888ef33283ea44e37817d36bc8e84a0568bc30
 Copyright (c) 2026 Meta Platforms, Inc.
 License: MIT
 
-Maka includes an ejected adaptation of Astryx ChatReasoning v0.1.9 and generated
-theme artifacts based on Astryx theme-neutral v0.5.0. Maka also redistributes
-`patches/@astryxdesign+core+0.5.0.patch`, which modifies the MIT-licensed Astryx
+Maka includes an ejected adaptation of Astryx ChatReasoning v0.1.9 in
+`packages/ui/src/astryx-chat-reasoning.tsx` and generated theme artifacts in
+`apps/desktop/src/renderer/astryx-theme/`, based on Astryx theme-neutral v0.6.2.
+Maka also redistributes
+`patches/@astryxdesign+core+0.6.3.patch`, which modifies the MIT-licensed Astryx
 core package. The following MIT License applies to that material:
 
 MIT License
@@ -261,6 +280,230 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+xterm.js dependency patch
+
+Source: https://www.npmjs.com/package/@xterm/xterm/v/6.0.0
+Repository: https://github.com/xtermjs/xterm.js
+Version: 6.0.0
+Dependency patch: patches/@xterm+xterm+6.0.0.patch
+License: MIT
+
+Maka redistributes a patch to the TypeScript source and both shipped JavaScript
+bundles that defers selection rendering while the terminal is hidden. The
+following upstream license applies to that material:
+
+Copyright (c) 2017-2019, The xterm.js authors (https://github.com/xtermjs/xterm.js)
+Copyright (c) 2014-2016, SourceLair Private Company (https://www.sourcelair.com)
+Copyright (c) 2012-2013, Christopher Jeffrey (https://github.com/chjj/)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+Pi TUI dependency patch
+
+Source: https://www.npmjs.com/package/@earendil-works/pi-tui/v/0.87.1
+Repository: https://github.com/earendil-works/pi/tree/v0.87.1/packages/tui
+Version: 0.87.1
+Dependency patch: patches/@earendil-works+pi-tui+0.87.1.patch
+Copyright (c) 2025 Mario Zechner
+License: MIT
+
+Maka redistributes a source patch that copies mutable editor undo state while
+sharing immutable pasted strings. The following MIT License applies to that
+material:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Zod dependency patch
+
+Source: https://www.npmjs.com/package/zod/v/4.6.5
+Repository: https://github.com/colinhacks/zod
+Version: 4.6.5
+Dependency patch: patches/zod+4.6.5.patch
+Copyright (c) 2025 Colin McDonnell
+License: MIT
+
+Maka redistributes a source patch that releases recursive parse state after
+completion or failure. The following MIT License applies to that material:
+
+MIT License
+
+Copyright (c) 2025 Colin McDonnell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Model Context Protocol client dependency patch
+
+Source: https://www.npmjs.com/package/@modelcontextprotocol/client/v/2.1.0
+Repository: https://github.com/modelcontextprotocol/typescript-sdk
+Version: 2.1.0
+Dependency patch: patches/@modelcontextprotocol+client+2.1.0.patch
+Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+Declared package license: MIT
+
+Maka redistributes a source patch that releases settled request observers under
+transport backpressure. The upstream package's LICENSE describes a transition
+from MIT to Apache-2.0: contributions with relicensing consent use Apache-2.0,
+while contributions without that consent retain their original MIT license.
+The Apache License, Version 2.0 is reproduced above. The upstream MIT notice is:
+
+MIT License
+
+Copyright (c) 2024-2025 Model Context Protocol a Series of LF Projects, LLC.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+Sigstore dependency patch
+
+Source: https://www.npmjs.com/package/@sigstore/core/v/4.0.1
+Repository: https://github.com/sigstore/sigstore-js/tree/main/packages/core
+Version: 4.0.1
+Dependency patch: patches/@sigstore+core+4.0.1.patch
+Copyright 2023 The Sigstore Authors
+License: Apache-2.0
+
+Maka redistributes a source patch that selects the signature digest in
+@sigstore/core. The patch modifies Apache-2.0 source and is covered by the
+Apache License, Version 2.0 reproduced above.
+
+TUF metadata models dependency patch
+
+Source: https://www.npmjs.com/package/@tufjs/models/v/5.0.0
+Repository: https://github.com/theupdateframework/tuf-js/tree/main/packages/models
+Version: 5.0.0
+Dependency patch: patches/@tufjs+models+5.0.0.patch
+Copyright (c) 2022 GitHub and the TUF Contributors
+License: MIT
+
+Maka redistributes a source patch that selects the signature digest in
+@tufjs/models. The following MIT License applies to that material:
+
+MIT License
+
+Copyright (c) 2022 GitHub and the TUF Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+electron-builder dependency patches
+
+Source: https://www.npmjs.com/package/app-builder-lib/v/26.17.0
+        https://www.npmjs.com/package/electron-updater/v/6.8.9
+Repository: https://github.com/electron-userland/electron-builder
+Versions: app-builder-lib 26.17.0; electron-updater 6.8.9
+Dependency patch: patches/app-builder-lib+26.17.0.patch
+                  patches/electron-updater+6.8.9.patch
+License: MIT
+
+Maka redistributes source patches that omit modification and access times
+from 7-Zip ZIP archives, keep macOS ZIP archives on the system zip, and skip
+withdrawn prereleases whose update metadata is missing. The following MIT
+License applies to that material:
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Loopline Systems
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 node-pty dependency patch
 
 Source: https://www.npmjs.com/package/node-pty/v/1.2.0-beta.15
@@ -332,6 +575,41 @@ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
 OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
+virtua dependency patch
+
+Source: https://www.npmjs.com/package/virtua/v/0.52.7
+Repository: https://github.com/inokawa/virtua
+Version: 0.52.7
+Dependency patch: patches/virtua+0.52.7.patch
+Copyright (c) 2022 inokawa
+License: MIT
+
+Maka redistributes a source patch that applies virtua's scroll correction
+absolutely after the browser clamps the scroll offset. The following MIT
+License applies to that material:
+
+MIT License
+
+Copyright (c) 2022 inokawa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
 trycua/cua cursor-overlay
 
 Source: https://github.com/trycua/cua
@@ -339,7 +617,9 @@ Revision: 8c921b2b3bf13494724ead4f0a814d80c56a7e8b
 Copyright (c) 2025 Cua AI, Inc.
 License: MIT
 
-Maka's agent-cursor renderer and palette include adaptations of this component.
+`apps/desktop/src/renderer/computer-use-overlay/engine/cursor-engine.ts` and
+`apps/desktop/src/renderer/computer-use-overlay/engine/palette.ts` include
+adaptations of this component.
 The following MIT License applies to that material:
 
 MIT License
@@ -527,8 +807,10 @@ SOFTWARE.
 
 Desktop renderer vendored source assets
 
-The source archive includes third-party SVG paths and source assets used by the
-desktop renderer. Their file-by-file inventory, immutable upstream revisions,
+The source archive includes third-party SVG paths and source assets from
+Lobe Icons (MIT), LocalAI (MIT), Simple Icons (CC0-1.0), TDesign Icons (MIT),
+MingCute (Apache-2.0), Allogo (MIT), Ant Design Icons (MIT), and Semi Design
+(MIT), used by the desktop renderer. Their file-by-file inventory, immutable upstream revisions,
 copyright notices, and license texts are in:
 
   apps/desktop/src/renderer/public/THIRD_PARTY_LICENSES.txt

package/README.md

@@ -24,7 +24,8 @@
 [简体中文](https://github.com/apache/maka/blob/main/packages/cli/README.zh-CN.md)
 
 Maka is a local-first agent workspace. The `maka-agent` npm package installs the interactive
-terminal UI, the non-interactive CLI, Runtime Host tooling, and the Eval command.
+terminal UI, the non-interactive CLI, Runtime Host tooling, and the Eval command. That package is
+published under the `nightly` dist-tag; `latest` holds an early alpha stub (see [Install](#install)).
 
 ## Apache Incubation Disclaimer
 
@@ -46,7 +47,12 @@ policy. For example, releases may have incomplete or un-reviewed licensing
 conditions. What follows is a list of issues the project is currently aware of
 (this list is likely to be incomplete):
 
- * The software grant and committer ICLAs are not yet complete.
+ * The initial-code authorization review remains open at
+   https://github.com/apache/maka/issues/3268. Since RC1, the ASF has recorded
+   the ICLA of contributor Mingqwqqaq, and the Deep Research implementation
+   has been removed. The review still needs to record the authorization basis
+   for the retained initial code; these changes do not establish that an SGA
+   has been filed.
 
 If you are planning to incorporate this work into your product/project, please
 be aware that you will need to conduct a thorough licensing review to determine
@@ -79,19 +85,33 @@ release gate. Real Eval executor validation currently runs on Linux x64 with Nod
 
 ## Install
 
-Install the current beta explicitly from the `next` dist-tag:
+Two dist-tags are live on npm, and they are not interchangeable:
 
-```sh
-npm install --global maka-agent@next
-maka --version
-maka --help
-```
+- `nightly` carries the complete CLI. The line moves daily — resolve the tag (or query its
+  current version) instead of copying a version number from any document:
+
+  ```sh
+  npm install --global maka-agent@nightly
+  maka --version
+  maka --help
+  ```
+
+- `latest` points at an early alpha (`0.0.0-alpha.0`) whose command surface is limited to
+  `doctor`, help, and version. Because of that split, do not use a bare
+  `npm update --global maka-agent`: it follows `latest` and may switch the installation to the
+  other release line.
 
 The public command is `maka`. For a one-off invocation, use
-`npx --yes --package maka-agent@next maka`; the unrelated `maka` package on npm is not this project.
+`npx --yes --package maka-agent@nightly maka`; the unrelated `maka` package on npm is not this project.
 `runtime-host service install` uses the persistent global installation above; `runtime-host setup`
 creates its own managed copy from the exact package invoked by `npx`.
 
+## Container
+
+To build and run a local glibc-based CLI image from an exact published npm version
+with persistent configuration, see the
+[container guide](https://github.com/apache/maka/blob/main/packages/cli/container/README.md).
+
 ## First run
 
 Start Maka from the project directory the agent should work in:
@@ -124,26 +144,31 @@ modify.
 
 ## Upgrade
 
-While using prereleases, keep the `next` tag explicit:
+Update within the nightly line by pinning the exact release (`--target` accepts `latest`,
+`next`, or an exact Maka version — there is no `nightly` channel name). Resolve the current
+nightly version first and pass that exact value: the updater refuses downgrades, so a copied
+version number goes stale as soon as the nightly line moves on.
 
 ```sh
-maka update --target next
+version="$(npm view maka-agent@nightly version --registry=https://registry.npmjs.org)"
+maka update --target "$version"
 maka --version
 ```
 
+Do not use a bare `npm update --global maka-agent` to upgrade: it follows `latest`, which holds
+the early alpha stub, and may switch the installation to the other release line.
+
 The update stages and verifies the exact release before replacing the local Runtime Host or the
 npm-global package. It refuses to interrupt active or durable work by default. Use
 `--allow-interrupt-active-tasks` only after deciding that interruption is safe. A direct
-`npm install --global maka-agent@next` remains available for installation repair; do not use a bare
-`npm update --global maka-agent`, because it follows `latest` and may select a different release
-line. After a stable release is available, select it with `maka update --target latest`.
+`npm install --global maka-agent@nightly` remains available for installation repair.
 
 ## Remote Runtime Host setup
 
 To set up a persistent remote Runtime Host from an exact released package on Linux or macOS:
 
 ```sh
-npx --yes --package maka-agent@next maka runtime-host setup \
+npx --yes --package maka-agent@nightly maka runtime-host setup \
   --principal my-client \
   --preset terminal-client
 ```
@@ -151,10 +176,12 @@ npx --yes --package maka-agent@next maka runtime-host setup \
 Rerunning setup replaces that Client credential. The service no longer depends on the temporary
 `npx` cache after setup succeeds.
 
-Check a managed service against a release channel without changing the running Host:
+Check a managed service against the nightly release it should track, without changing the
+running Host — pass the exact version resolved above rather than `latest`, which holds the
+early alpha:
 
 ```sh
-maka runtime-host service check-update --target next --json
+maka runtime-host service check-update --target "$version" --json
 ```
 
 The result pins the selected channel to an exact version and package integrity. It also reports
@@ -165,10 +192,13 @@ to the existing exact-package update transaction, and does not mutate a candidat
 manual review.
 
 The installation owner can persist one update target and reconcile it with the same verified
-transaction:
+transaction. Pin the exact nightly version resolved above: there is no `nightly` target name,
+and `latest` holds the early alpha, which the reconciliation assesses as a downgrade for a
+nightly installation. Following successive nightlies therefore means resolving the current
+version again and re-running `update-policy` with the fresh value:
 
 ```sh
-maka runtime-host service update-policy --target latest \
+maka runtime-host service update-policy --target "$version" \
   --expected-service-id <service-id> \
   --expected-root-path <state-root> \
   --expected-root-id <root-id>
@@ -182,7 +212,7 @@ bounded one-shot command: it never interrupts active work and does not install a
 
 ```sh
 # When a managed Runtime Host service was installed on Linux or macOS
-npx --yes --package maka-agent@next maka runtime-host service uninstall
+npx --yes --package maka-agent@nightly maka runtime-host service uninstall
 
 # If Maka was installed globally
 npm uninstall --global maka-agent

package/README.zh-CN.md

@@ -24,7 +24,8 @@
 [English](./README.md)
 
 Maka 是一个本地优先的 Agent 工作空间。`maka-agent` npm 包包含交互式终端界面、非交互
-CLI、Runtime Host 工具和 Eval 命令。
+CLI、Runtime Host 工具和 Eval 命令。该包发布在 `nightly` dist-tag 上；`latest` 指向一个
+早期 alpha stub（见[安装](#安装)）。
 
 ## Apache 孵化免责声明
 
@@ -57,18 +58,29 @@ release commit 中的 [DISCLAIMER-WIP](https://github.com/apache/maka/blob/main/
 
 ## 安装
 
-Beta 阶段请明确从 `next` dist-tag 安装：
+npm 上有两条 dist-tag，且二者不可互换：
 
-```sh
-npm install --global maka-agent@next
-maka --version
-maka --help
-```
+- `nightly` 承载完整的 CLI。该发布线每日推进——请解析 tag 本身（或查询其当前版本），不要誊写任何文档里的版本号：
+
+  ```sh
+  npm install --global maka-agent@nightly
+  maka --version
+  maka --help
+  ```
 
-公开命令只有 `maka`。一次性运行请使用 `npx --yes --package maka-agent@next maka`；npm 上与本项目
+- `latest` 指向一个早期 alpha（`0.0.0-alpha.0`），命令面只有 `doctor`、帮助与版本命令。
+  因此不要使用裸的 `npm update --global maka-agent`：它跟随 `latest`，可能把安装切换到
+  另一条发布线。
+
+公开命令只有 `maka`。一次性运行请使用 `npx --yes --package maka-agent@nightly maka`；npm 上与本项目
 无关的 `maka` 包不是本项目。`runtime-host service install` 使用上面的持久全局安装；
 `runtime-host setup` 会从 `npx` 调用的精确 package 创建自己的托管副本。
 
+## 容器
+
+从精确的已发布 npm 版本构建和运行本地 glibc CLI 镜像，并持久化配置，见
+[容器指南](https://github.com/apache/maka/blob/main/packages/cli/container/README.md)。
+
 ## 第一次运行
 
 进入希望 Agent 工作的项目目录，然后启动 Maka：
@@ -98,35 +110,40 @@ Maka 默认会在执行高权限工具操作前询问。`maka run --yolo` 会授
 
 ## 升级
 
-使用预发布版本时，请继续明确指定 `next`：
+在 nightly 线内更新时固定精确版本（`--target` 只接受 `latest`、`next` 或精确的 Maka
+版本号——不存在 `nightly` 这个 channel 名）。先解析当前 nightly 版本再传入精确值：
+updater 拒绝降级，nightly 前进之后誊写的旧版本号会被直接拒绝。
 
 ```sh
-maka update --target next
+version="$(npm view maka-agent@nightly version --registry=https://registry.npmjs.org)"
+maka update --target "$version"
 maka --version
 ```
 
+不要使用裸的 `npm update --global maka-agent` 来升级：它跟随 `latest`（早期 alpha stub），
+可能把安装切换到另一条发布线。
+
 更新流程会先 stage 并验证精确 release，再替换本地 Runtime Host 与 npm-global package；
 默认不会中断 active 或 durable work。只有在你确认可以安全中断后，才使用
-`--allow-interrupt-active-tasks`。`npm install --global maka-agent@next` 仍可用于修复安装；
-不要使用不带 tag 的 `npm update --global maka-agent`，因为它会跟随 `latest`，可能选中
-不同的发布线。稳定版发布后，使用 `maka update --target latest`。
+`--allow-interrupt-active-tasks`。`npm install --global maka-agent@nightly` 仍可用于修复安装。
 
 ## 设置远程 Runtime Host
 
 在 Linux 或 macOS 上从精确的发布 package 设置持久 remote Runtime Host：
 
 ```sh
-npx --yes --package maka-agent@next maka runtime-host setup \
+npx --yes --package maka-agent@nightly maka runtime-host setup \
   --principal my-client \
   --preset terminal-client
 ```
 
 重复设置会替换该 Client credential。设置成功后，service 不再依赖临时 `npx` cache。
 
-可以在不改变当前 Host 的情况下检查 managed service 对应的发布频道：
+检查 managed service 应跟随的 nightly 发布，且不改变当前运行中的 Host——传入上面解析出的
+精确版本，而不是指向早期 alpha 的 `latest`：
 
 ```sh
-maka runtime-host service check-update --target next --json
+maka runtime-host service check-update --target "$version" --json
 ```
 
 结果会把频道固定为精确版本和 package integrity，并说明 package 是否提供足够的兼容性证据，
@@ -134,10 +151,13 @@ maka runtime-host service check-update --target next --json
 selector 传给 `service update --target`。该路径会先校验 archive 与解包后的 manifest，再委托给
 现有的精确 package 更新事务；需要人工审查的候选不会改变当前 Host。
 
-Installation owner 可以持久化一个更新目标，并通过同一套已验证事务执行 reconciliation：
+Installation owner 可以持久化一个更新目标，并通过同一套已验证事务执行 reconciliation。持久化
+上面解析出的精确 nightly 版本：不存在 `nightly` 这个 target 名，而 `latest` 指向早期 alpha，
+reconciliation 会把对一个 nightly 安装而言更旧的候选判为降级。因此要跟随每日推进的 nightly，
+就需要重新解析当前版本，并用新值再次运行 `update-policy`：
 
 ```sh
-maka runtime-host service update-policy --target latest \
+maka runtime-host service update-policy --target "$version" \
   --expected-service-id <service-id> \
   --expected-root-path <state-root> \
   --expected-root-id <root-id>
@@ -151,7 +171,7 @@ maka runtime-host service reconcile-update --json
 
 ```sh
 # 仅限安装过 managed Runtime Host service 的 Linux 或 macOS
-npx --yes --package maka-agent@next maka runtime-host service uninstall
+npx --yes --package maka-agent@nightly maka runtime-host service uninstall
 
 # 如果曾全局安装 Maka
 npm uninstall --global maka-agent