maka-agent 0.1.0-beta.1 → 0.2.0-dev.3.20260830

package/DISCLAIMER-WIP

@@ -0,0 +1,20 @@
+Apache Maka is an effort undergoing incubation at The Apache Software Foundation
+(ASF), sponsored by the Apache Incubator PMC. Incubation is required of all
+newly accepted projects until a further review indicates that the
+infrastructure, communications, and decision-making process have stabilized in a
+manner consistent with other successful ASF projects. While incubation status is
+not necessarily a reflection of the completeness or stability of the code, it
+does indicate that the project has yet to be fully endorsed by the ASF.
+
+Some of the incubating project's releases may not be fully compliant with ASF
+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.
+
+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
+the overall implications of including this work. For the current status of this
+project through the Apache Incubator, visit:
+https://incubator.apache.org/projects/maka.html

package/LICENSE

@@ -203,6 +203,135 @@
 
 THIRD-PARTY COMPONENTS
 
+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
+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
+Copyright 2023 Vercel, Inc.
+License: Apache-2.0
+
+`packages/runtime/src/model-protocol.ts` adapts the JSON value, provider
+option, file data, content part, and message shapes from these components and
+modifies them. That file carries the required modification notice. The Apache
+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
+modifies Apache-2.0 source and is covered by the license reproduced above.
+
+Astryx
+
+Source: https://github.com/facebook/astryx
+ChatReasoning revision: c9fe4379e9959b9ba5eeff56def34c752223450e
+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
+core package. The following MIT License applies to that material:
+
+MIT License
+
+Copyright (c) 2026 Meta Platforms, Inc.
+
+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
+Repository: https://github.com/microsoft/node-pty
+Version: 1.2.0-beta.15
+Dependency patch: patches/node-pty+1.2.0-beta.15.patch
+License: MIT
+
+Maka redistributes a source patch for node-pty's Unix PTY write lifecycle. The
+following license notices are reproduced from node-pty 1.2.0-beta.15:
+
+Copyright (c) 2012-2015, 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.
+
+Copyright (c) 2016, Daniel Imms (http://www.growingwiththeweb.com)
+
+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.
+
+Copyright (c) 2018 - present Microsoft Corporation
+
+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
@@ -236,107 +365,174 @@ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
 SOFTWARE.
 
 
-Geist and Geist Mono (bundled webfonts)
-
-Source: https://github.com/vercel/geist-font
-Emitted by: @fontsource-variable/geist 5.3.0, @fontsource-variable/geist-mono 5.3.0
-Copyright 2024 The Geist Project Authors
-License: SIL Open Font License, Version 1.1
-
-Maka's desktop renderer bundle embeds Geist Variable and Geist Mono Variable
-webfont files. The packages that carry them are build-time dependencies, but
-the `.woff2` files themselves are emitted into the renderer bundle and are
-therefore redistributed in binary artifacts. The upstream license text for
-that material follows verbatim:
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at:
-http://scripts.sil.org/OFL
-
-
------------------------------------------------------------
-SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
------------------------------------------------------------
-
-PREAMBLE
-The goals of the Open Font License (OFL) are to stimulate worldwide
-development of collaborative font projects, to support the font creation
-efforts of academic and linguistic communities, and to provide a free and
-open framework in which fonts may be shared and improved in partnership
-with others.
-
-The OFL allows the licensed fonts to be used, studied, modified and
-redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded,
-redistributed and/or sold with any software provided that any reserved
-names are not used by derivative works. The fonts and derivatives,
-however, cannot be released under any other type of license. The
-requirement for fonts to remain under this license does not apply
-to any document created using the fonts or their derivatives.
-
-DEFINITIONS
-"Font Software" refers to the set of files released by the Copyright
-Holder(s) under this license and clearly marked as such. This may
-include source files, build scripts and documentation.
-
-"Reserved Font Name" refers to any names specified as such after the
-copyright statement(s).
-
-"Original Version" refers to the collection of Font Software components as
-distributed by the Copyright Holder(s).
-
-"Modified Version" refers to any derivative made by adding to, deleting,
-or substituting -- in part or in whole -- any of the components of the
-Original Version, by changing formats or by porting the Font Software to a
-new environment.
-
-"Author" refers to any designer, engineer, programmer, technical
-writer or other person who contributed to the Font Software.
-
-PERMISSION & CONDITIONS
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of the Font Software, to use, study, copy, merge, embed, modify,
-redistribute, and sell modified and unmodified copies of the Font
-Software, subject to the following conditions:
-
-1) Neither the Font Software nor any of its individual components,
-in Original or Modified Versions, may be sold by itself.
-
-2) Original or Modified Versions of the Font Software may be bundled,
-redistributed and/or sold with any software, provided that each copy
-contains the above copyright notice and this license. These can be
-included either as stand-alone text files, human-readable headers or
-in the appropriate machine-readable metadata fields within text or
-binary files as long as those fields can be easily viewed by the user.
-
-3) No Modified Version of the Font Software may use the Reserved Font
-Name(s) unless explicit written permission is granted by the corresponding
-Copyright Holder. This restriction only applies to the primary font name as
-presented to the users.
-
-4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
-Software shall not be used to promote, endorse or advertise any
-Modified Version, except to acknowledge the contribution(s) of the
-Copyright Holder(s) and the Author(s) or with their explicit written
-permission.
-
-5) The Font Software, modified or unmodified, in part or in whole,
-must be distributed entirely under this license, and must not be
-distributed under any other license. The requirement for fonts to
-remain under this license does not apply to any document created
-using the Font Software.
-
-TERMINATION
-This license becomes null and void if any of the above conditions are
-not met.
-
-DISCLAIMER
-THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
-OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
-OTHER DEALINGS IN THE FONT SOFTWARE.
+anomalyco/opencode (adapted source)
+
+Source: https://github.com/anomalyco/opencode
+Revision: fc80874f45a595ff6874a4d36b1090f6a64424d2
+Copyright (c) 2025 opencode
+License: MIT
+
+Maka's tool-output truncation (packages/runtime/src/tool-output.ts) and
+string-edit matching strategies (packages/runtime/src/edit-replace.ts) include
+adaptations of this software. Each file marks the adapted portion in its header;
+the surrounding Maka source stays under this repository's Apache-2.0 license.
+
+Maka took the string-edit strategies from opencode, but opencode's edit.ts
+credits cline diff-apply and the gemini-cli editCorrector upstream of itself,
+and both are Apache-2.0. That region of edit-replace.ts is therefore not
+uniformly MIT, and its header lists each piece with the license that governs
+it. The two Apache-2.0 pieces are recorded separately below. The MIT License
+here applies to the rest: tool-output.ts, and opencode's own additions and
+modifications in edit-replace.ts.
+
+MIT License
+
+Copyright (c) 2025 opencode
+
+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.
+
+
+cline/cline diff-apply (adapted source, reached through opencode)
+
+Source: https://github.com/cline/cline
+Revision: 50b43c0559a9658a4fda79645b2cfe66cfa2f133
+Path: evals/diff-edits/diff-apply/diff-06-23-25.ts
+Copyright 2025 Cline Bot Inc.
+License: Apache-2.0
+
+The line-trimmed matcher in packages/runtime/src/edit-replace.ts is adapted
+from this file's lineTrimmedFallbackMatch. Maka reached it through opencode
+rather than directly. The Apache License 2.0 that governs it is the same
+license reproduced at the top of this file; cline ships no NOTICE file. The
+modifications Maka made are stated in the header of edit-replace.ts, as
+Apache-2.0 section 4(b) requires.
+
+
+google-gemini/gemini-cli editCorrector (adapted source, reached through opencode)
+
+Source: https://github.com/google-gemini/gemini-cli
+Revision: 93909a2dd3bf901e8f98a9fd41e1300faa585a84
+Path: packages/core/src/utils/editCorrector.ts
+Copyright 2025 Google LLC
+License: Apache-2.0
+
+The escape-normalizing matcher in packages/runtime/src/edit-replace.ts carries
+the regular expression and the first eight escape branches, in order, from this
+file's unescapeStringForGeminiBug. opencode added a ninth branch and changed the
+pattern; Maka took opencode's result. The Apache License 2.0 that governs it is
+the same license reproduced at the top of this file; gemini-cli ships no NOTICE
+file. The modifications Maka made are stated in the header of edit-replace.ts,
+as Apache-2.0 section 4(b) requires.
+
+
+anomalyco/models.dev (generated model catalog snapshot)
+
+Source: https://models.dev/api.json
+Repository: https://github.com/anomalyco/models.dev
+Copyright (c) 2025 models.dev
+License: MIT
+
+packages/core/src/model-metadata.generated.ts and
+packages/runtime/src/telemetry/model-pricing.generated.ts are generated from the
+models.dev catalog by scripts/sync-model-metadata.mjs during installation or
+build and are redistributed with compiled Maka packages, but are not tracked as
+source. The exact selected input projection is stored at
+scripts/model-metadata/models-dev-api.snapshot.json. Its origin record either
+binds a refresh to the downloaded response digest or identifies the exact Maka
+commit whose generated outputs seeded the migration snapshot. The snapshot
+is the sole build input for a particular repository revision and release;
+models.dev remains the upstream source used by an explicit refresh. Normal
+installation and build paths do not fetch the latest catalog implicitly. The
+snapshot also carries a digest of its normalized projection; the generated-file
+headers bind each output to that digest. They copy and transform selected model
+and provider metadata from that catalog, including upstream display names and
+descriptive text, lifecycle status values, reasoning effort options, context
+and output limits, modalities, and prices. Which providers are kept, which
+fields are kept, and the order they appear in are decided by the generator. The
+following MIT License applies to the material taken from upstream:
+
+MIT License
+
+Copyright (c) 2025 models.dev
+
+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.
+
+
+DeepSeek Harness (adapted source)
+
+Source: https://github.com/deepseek-ai/deepseek-harness
+Revision: 47f943859bef60e4160492346772ded9b24f765a
+Path: examples/jsonrpc-agent/minimal.cordis.yml
+Copyright (c) 2026 DeepSeek
+License: MIT
+
+`packages/eval/harbor/deepseek-harness-profile/cordis.patch.yml` adapts the
+upstream plugin composition, persistent-bash description, and persona. The
+file identifies Maka's modifications and scopes this MIT notice to the derived
+material; the surrounding modifications are Apache-2.0.
+
+MIT License
+
+Copyright (c) 2026 DeepSeek
+
+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.
+
+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,
+copyright notices, and license texts are in:
+
+  apps/desktop/src/renderer/public/THIRD_PARTY_LICENSES.txt
+
+Additional verbatim license texts referenced by that inventory are in:
+
+  apps/desktop/resources/licenses/renderer/

package/NOTICE

@@ -1,8 +1,5 @@
-Maka
-Copyright 2026 The Maka Authors
+Apache Maka (incubating)
+Copyright 2026 The Apache Software Foundation
 
-This product includes software developed by the Maka project.
-
-Third-party components remain subject to their respective licenses and
-attribution notices. Those notices are distributed with the applicable
-components and application artifacts.
+This product includes software developed at
+The Apache Software Foundation (https://www.apache.org/).

package/README.md

@@ -1,10 +1,59 @@
-# Maka CLI
+> **Developer snapshot:** This Nightly is not an Apache release and is not intended for production use. Its version is bound to one exact `apache/maka` commit.
 
-[简体中文](https://github.com/maka-agent/maka-agent/blob/main/packages/cli/README.zh-CN.md)
+<!--
+  Licensed to the Apache Software Foundation (ASF) under one
+  or more contributor license agreements.  See the NOTICE file
+  distributed with this work for additional information
+  regarding copyright ownership.  The ASF licenses this file
+  to you under the Apache License, Version 2.0 (the
+  "License"); you may not use this file except in compliance
+  with the License.  You may obtain a copy of the License at
+
+      http://www.apache.org/licenses/LICENSE-2.0
+
+  Unless required by applicable law or agreed to in writing,
+  software distributed under the License is distributed on an
+  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+  KIND, either express or implied.  See the License for the
+  specific language governing permissions and limitations
+  under the License.
+-->
+
+# Apache Maka (Incubating) CLI
+
+[简体中文](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.
 
+## Apache Incubation Disclaimer
+
+Apache Maka is undergoing incubation at The Apache Software Foundation. The published npm README
+includes the canonical work-in-progress disclaimer below directly from the release commit's
+[DISCLAIMER-WIP](https://github.com/apache/maka/blob/main/DISCLAIMER-WIP); the
+[Maka podling status page](https://incubator.apache.org/projects/maka.html) records current status.
+
+Apache Maka is an effort undergoing incubation at The Apache Software Foundation
+(ASF), sponsored by the Apache Incubator PMC. Incubation is required of all
+newly accepted projects until a further review indicates that the
+infrastructure, communications, and decision-making process have stabilized in a
+manner consistent with other successful ASF projects. While incubation status is
+not necessarily a reflection of the completeness or stability of the code, it
+does indicate that the project has yet to be fully endorsed by the ASF.
+
+Some of the incubating project's releases may not be fully compliant with ASF
+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.
+
+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
+the overall implications of including this work. For the current status of this
+project through the Apache Incubator, visit:
+https://incubator.apache.org/projects/maka.html
+
 > **Beta:** The CLI is under active development. Commands and local data formats may change before
 > the stable release.
 
@@ -21,6 +70,7 @@ The release gate validates the following installed-package matrix:
 | --- | --- | --- | --- | --- |
 | Linux | x64 | 22.19 | Validated | Preflight only |
 | Linux | x64 | 24 | Validated | Validated |
+| Linux | arm64 | 24 | Validated | Preflight only |
 | macOS | arm64 | 24 | Validated | Preflight only |
 | Windows | x64 | 24 | Validated | Preflight only |
 
@@ -37,8 +87,10 @@ maka --version
 maka --help
 ```
 
-`maka-agent` is an alias for `maka`. For a one-off invocation, use
-`npx --yes maka-agent@next`; the unrelated `maka` package on npm is not this project.
+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.
+`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`.
 
 ## First run
 
@@ -56,7 +108,7 @@ to switch models.
 API keys and workspace state stay in the local `Maka` profile. The current credential vault is a
 local plaintext file protected by the operating-system account boundary; on POSIX systems Maka
 enforces owner-only directory and file modes. It is not an OS keychain. See the repository
-[security policy](https://github.com/maka-agent/maka-agent/blob/main/SECURITY.md) for the current
+[security policy](https://github.com/apache/maka/blob/main/SECURITY.md) for the current
 boundary.
 
 Run one non-interactive turn with:
@@ -75,21 +127,70 @@ modify.
 While using prereleases, keep the `next` tag explicit:
 
 ```sh
-npm install --global maka-agent@next
+maka update --target next
 maka --version
 ```
 
-Do not use a bare `npm update --global maka-agent` for beta upgrades: global npm updates follow the
-`latest` tag and may select a different release line. After a stable release is available, install it
-with `npm install --global maka-agent@latest`.
+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`.
+
+## 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 \
+  --principal my-client \
+  --preset terminal-client
+```
+
+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:
+
+```sh
+maka runtime-host service check-update --target next --json
+```
+
+The result pins the selected channel to an exact version and package integrity. It also reports
+whether the package carries enough compatibility evidence for unattended use; this command never
+installs or switches a package. Installation-management callers can pass the same selector to
+`service update --target`. That path verifies the archive and extracted manifest before delegating
+to the existing exact-package update transaction, and does not mutate a candidate that requires
+manual review.
+
+The installation owner can persist one update target and reconcile it with the same verified
+transaction:
+
+```sh
+maka runtime-host service update-policy --target latest \
+  --expected-service-id <service-id> \
+  --expected-root-path <state-root> \
+  --expected-root-id <root-id>
+maka runtime-host service reconcile-update --json
+```
+
+Use `update-policy --target manual` to disable automatic reconciliation. Reconciliation is a
+bounded one-shot command: it never interrupts active work and does not install a scheduler.
 
 ## Uninstall
 
 ```sh
+# When a managed Runtime Host service was installed on Linux or macOS
+npx --yes --package maka-agent@next maka runtime-host service uninstall
+
+# If Maka was installed globally
 npm uninstall --global maka-agent
 ```
 
-Uninstalling the package does not delete model connections, credentials, sessions, or artifacts.
+Remove the managed service before removing a global package so the OS service manager does not
+retain a service pointing to the deleted CLI. Neither command deletes model connections,
+credentials, sessions, or artifacts.
 Those remain in the profile shared by the released CLI and Desktop app:
 
 | Platform | Profile directory |
@@ -137,7 +238,7 @@ python3.12 -m venv ~/.venvs/maka-pier-0.3.0
 Set the spec's `pythonPathEnv` to the corresponding `bin/python` path. Do not reuse one environment
 for both frameworks: their dependency and trial contracts differ. Advanced experiment and
 toolchain details live in the
-[Eval documentation](https://github.com/maka-agent/maka-agent/tree/main/packages/eval).
+[Eval documentation](https://github.com/apache/maka/tree/main/packages/eval).
 
 ## Troubleshooting
 
@@ -157,10 +258,10 @@ maka --version
 - When reporting a problem, include the three versions above, the operating system and
   architecture, the command, and the complete error with credentials removed.
 
-Report issues at <https://github.com/maka-agent/maka-agent/issues>.
+Report issues at <https://github.com/apache/maka/issues>.
 
 ## Links
 
-- [Repository](https://github.com/maka-agent/maka-agent)
-- [Release operations](https://github.com/maka-agent/maka-agent/blob/main/docs/cli-npm-release.md)
-- [License](https://github.com/maka-agent/maka-agent/blob/main/LICENSE)
+- [Repository](https://github.com/apache/maka)
+- [Release operations](https://github.com/apache/maka/blob/main/docs/cli-npm-release.md)
+- [License](https://github.com/apache/maka/blob/main/LICENSE)