quukk-clawmessenger 0.1.0-beta.1

package/LICENSE

@@ -0,0 +1,328 @@
+# Multica License
+
+Multica is provided under the terms of the Apache License, Version 2.0 —
+the complete, unmodified text of which is reproduced in Part II of this
+file — subject to the additional conditions in Part I.
+
+Part I and Part II together constitute the "Multica License". Neither part
+grants any rights on its own. Condition 3 states how the two parts fit
+together and what must be delivered when you redistribute.
+
+------------------------------------------------------------------------
+
+                       Part I — Additional Conditions
+
+1. Multica may be utilized commercially, including as a backend service for
+   other applications or as a task management platform for enterprises,
+   subject to the following conditions:
+
+   a. Hosted or embedded service: Unless you have obtained a commercial
+      license from the producer, you may not use the Multica source code
+      to provide a hosted service to third parties, or embed Multica as a
+      component of a product or service that is sold, licensed, or
+      otherwise commercially distributed to third parties.
+
+      - This restriction applies to offering Multica (in whole or
+        substantial part) as a SaaS platform, a managed service, or as
+        an integrated component within another commercial offering.
+      - Providing a hosted service to third parties is restricted whether
+        or not you charge for it. A publicly accessible instance operated
+        for users outside your own organization requires a commercial
+        license even when it is offered free of charge, carries no
+        advertising, and sells no paid tier.
+      - Internal use within a single organization (including multiple
+        workspaces) does not require a commercial license.
+      - Making the source code available, including publishing the source
+        code of a fork in a public repository, is not itself a hosted
+        service and does not require a commercial license. Any such
+        distribution remains subject to all applicable terms of this
+        Multica License, including conditions (b) and (c) below and
+        condition 3. Source distribution does not grant recipients the
+        right to operate a hosted service; each operator must obtain its
+        own commercial license.
+
+   b. Branding and copyright information: Unless the producer has granted
+      you a written branding waiver, you may not remove or modify the
+      Multica LOGO, the Multica product name, or the copyright and
+      attribution information displayed by a Multica user interface.
+
+      - User Interface Definition: For the purposes of this license, a
+        "Multica user interface" means any user interface derived, in whole
+        or in substantial part, from the user interface code in this
+        repository. This includes the components located in the
+        `apps/web/`, `apps/desktop/`, `apps/mobile/`, `packages/views/`,
+        and `packages/ui/` directories when running Multica from the raw
+        source code, the frontend container image (published as
+        `ghcr.io/multica-ai/multica-web`) when running Multica with
+        Docker, and any compiled desktop or mobile application built from
+        that code. That enumeration is illustrative rather than
+        exhaustive: user interface code remains covered when it is
+        modified, moved, renamed, or extracted into another package or
+        repository.
+      - This restriction is inapplicable to uses of Multica that do not
+        involve a Multica user interface, such as running only the
+        `server/` backend, the daemon, or the CLI without redistributing
+        or operating any Multica user interface. Such uses remain subject
+        to condition (c) below.
+
+   c. Attribution for non-interface use: If you redistribute or operate a
+      product or service built on Multica's backend, daemon, or CLI
+      without a Multica user interface, you must retain all copyright,
+      patent, trademark, and attribution notices present in the source
+      code and in the NOTICE file, and state in your user-facing
+      documentation that the product is built on Multica, including a link
+      to https://github.com/multica-ai/multica.
+
+   d. Relationship between grants: A branding waiver is not a commercial
+      license and does not permit any use restricted by condition (a). A
+      commercial license does not by itself waive condition (b) or
+      condition (c). Each grant must be obtained from the producer
+      expressly and separately, and neither may be inferred from the other
+      or from the producer's silence, review, or acceptance of your
+      contributions.
+
+2. Contributions: By submitting a contribution to Multica, you agree that:
+
+   a. The producer can adjust this Multica License to be more strict or
+      relaxed as deemed necessary.
+
+   b. Your contributed code may be used for commercial purposes, including
+      but not limited to its cloud business operations.
+
+   c. Your contribution is submitted under this Multica License as a whole,
+      as described in condition 3, and not under Part II alone.
+
+3. Composition, precedence, and redistribution:
+
+   a. This entire file is the Multica License. Part I (these additional
+      conditions) and Part II (the incorporated Apache License, Version
+      2.0) together form a single set of terms. Apart from the conditions
+      stated in Part I, all other rights and restrictions follow Part II.
+
+   b. Wherever Part II refers to "this License", that reference means the
+      Multica License as a whole — Part I and Part II together — and not
+      Part II in isolation. This includes the copy of the License that
+      section 4(a) of Part II requires you to give to recipients, and the
+      terms under which section 5 of Part II treats a contribution as
+      submitted.
+
+   c. If Part I and Part II conflict, Part I controls.
+
+   d. If you redistribute Multica or a derivative work of it, you must
+      deliver this complete file. Delivering Part II alone does not
+      satisfy the Multica License or section 4(a) of Part II.
+
+© 2025-2026 Multica, Inc.
+
+------------------------------------------------------------------------
+
+               Part II — Incorporated Apache License 2.0 Text
+
+The text below is reproduced verbatim and unmodified from
+https://www.apache.org/licenses/LICENSE-2.0.txt. It is incorporated into
+the Multica License as described in condition 3 above.
+
+------------------------------------------------------------------------
+
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed 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.

package/MODIFICATIONS.md

@@ -0,0 +1,98 @@
+# Quukk ClawMessenger Modifications
+
+## Fork baseline
+
+- Fork repository: https://github.com/quukk/quukk-clawmessenger
+- Upstream repository: https://github.com/multica-ai/multica
+- Upstream baseline commit: `54027ba763fa7da0699b2fe89df4a6b2c13d1c6f`
+- Fork development branch: `codex/quukk-clawmessenger`
+- Upstream remote is read-only for fork development.
+
+## Bridge additions
+
+- `packages/quukk-clawmessenger`: publishable Node.js entry package for the local ClawMessenger bridge.
+- `apps/bridge`: private React/Vite workspace that builds local Bridge UI assets into the entry package.
+- `server/internal/daemon/bridge*.go`: injected, bounded discovery for local OpenCode, OpenClaw, Codex, and Hermes runtimes, kept separate from the existing daemon lifecycle.
+- Synchronous agent probe output shares a 64 KiB cap so noisy version and catalog commands safely fail instead of growing daemon memory without bound; Task 14/CI must watch for real catalog output above that limit.
+- The fork now includes the runtime workers, registration transport, session routing, local
+  service/CLI, and Bridge UI described below.
+
+## Local runtime selection UI
+
+- `apps/bridge/src` adds the Multica-attributed Quukk ClawMessenger setup and local operations interface for OpenCode, OpenClaw, Codex, and Hermes.
+- Setup defaults to detected ready runtimes, requires an explicit submit, discloses headless permissions, and requires a real authorized work root plus a default working directory before describing a registered runtime as task-ready.
+- Registration progress is isolated per runtime so a successful RongCloud identity stays successful when another runtime fails.
+- The UI uses one-use local session tickets, removes the ticket from browser history before exchange, and adds the returned CSRF token only to same-origin mutations.
+- Generated `packages/quukk-clawmessenger/dist/ui` assets are intentionally excluded from Git. `pnpm --dir apps/bridge build` creates them deterministically before package assembly.
+
+## Authenticated Bridge transport
+
+- `server/internal/daemon/bridge_http.go` and `server/internal/daemon/bridge_http_test.go` add the loopback-only, per-install bearer-authenticated Bridge JSON/SSE API, bounded request decoding, runtime refresh, task streaming/cancellation, health reporting, and graceful shutdown. The Node supervisor owns and protects the installation secret; the Go child receives it only through bounded startup stdin and retains it only in memory.
+- `server/cmd/multica/cmd_bridge.go` and `server/cmd/multica/cmd_bridge_test.go` add the hidden `multica daemon bridge` entrypoint with bounded strict stdin, fixed ephemeral IPv4 loopback binding, process identity generation, and a single post-refresh readiness record.
+- The serving lifecycle synchronously fences parent cancellation against discovery/readiness, seals new handler entries at shutdown, drains cooperative handlers and every started Bridge task within one deadline, and force-closes timed-out HTTP connections without waiting indefinitely for a non-cooperative Go handler. The command reuses the existing cross-platform shutdown context and rejects changed inherited flags before startup I/O.
+
+## External service prerequisite
+
+- `clawmessenger-server` commit `68496a3edf934c90b9af03a5c1c81422ab2d9ef7` adds Hermes to the server's supported AI node identity types. Deploy that server commit before enabling Hermes registration from the Quukk bridge; existing node types remain unchanged.
+- `clawmessenger-server` commit `8a29e4e24af00145c072ccca568a0e9049842d29` retires the anonymous user-token route, allowlists public node responses, redacts RongCloud token logs/errors, and adds no-store to sensitive responses. Enrollment enforcement and owner/node authorization remain mandatory follow-up server gates before npm publication.
+
+## Local identity and enrollment
+
+- `packages/quukk-clawmessenger/src/config`, `src/registration`, and `src/bindings` add strict versioned config/state/credential storage, protected per-install identity, fail-closed work-directory authorization, bounded atomic JSON recovery, four-provider registration, per-runtime enrollment proof, credentials-first token swaps, and provider-isolated lifecycle coordination.
+- The enrollment proof is derived locally from the decoded 32-byte Bridge secret, full normalized server base URL, and runtime ID. Only the domain-separated HMAC result crosses HTTPS; raw Bridge and RongCloud credentials remain outside request bodies, URLs, errors, logs, state, and ordinary config.
+
+## Legacy migration and package audit
+
+- `packages/quukk-clawmessenger/src/migration` discovers only the fixed OpenCode
+  ClawMessenger configuration locations under an explicitly supplied home directory. It reads
+  only the bounded main settings file, projects validated non-secret server/work-directory/path
+  settings, reports registration caches without opening them, and requires explicit confirmation
+  before writing through `LocalStore`.
+- Migration never moves or deletes a legacy file and never imports tokens, AppKey/AppSecret,
+  passwords, node/MAC identity, bindings, sessions, or logs. Validation and atomic-write failures
+  leave the legacy bytes and destination config unchanged.
+- `packages/quukk-clawmessenger/scripts/prepare-package.mjs` copies the exact four root legal
+  files into the entry package and the exact root `LICENSE`, `NOTICE`, `MODIFICATIONS.md`, and
+  `GO_THIRD_PARTY_NOTICES.md` into either zero or the complete six binary-only platform staging
+  packages while rejecting partial matrices, traversal, and symbolic-link/junction components.
+  Platform manifests record the exact linked Go modules and the tarball audit requires every
+  module to appear in the bundled notice generated from checksum-verified module sources.
+- `packages/quukk-clawmessenger/scripts/audit-tarball.mjs` consumes bounded `npm pack --json`
+  reports and strictly checks legal files, README, npm/platform manifests, bin, compiled worker,
+  Bridge UI assets, source-map absence, path containment, symlinks, credential-like literals, and
+  developer-specific paths. Failure output is a fixed code and does not echo matched content.
+- The entry TypeScript build excludes tests and disables source/declaration maps so rejected
+  development artifacts cannot enter the npm tarball.
+
+## Modified upstream files
+
+- `.gitignore`: excludes a repository-local Quukk ClawMessenger runtime-data directory.
+- `docs/superpowers/specs/2026-08-26-quukk-clawmessenger-fork-design.md`: records the initial workspace scaffold and its intentionally limited scope.
+- `pnpm-workspace.yaml`: adds the catalog-pinned Vite version required by the Bridge UI workspace.
+- `pnpm-lock.yaml`: records the fork workspaces and the focused Bridge UI dependencies used by the local package build.
+- `README.md`: adds the Quukk ClawMessenger derivative entry point while retaining Multica as the
+  primary product and attribution.
+- `MODIFICATIONS.md`, `THIRD_PARTY_NOTICES.md`, and `GO_THIRD_PARTY_NOTICES.md`: record
+  migration/package hardening, pin the matching RongCloud 5.38.0 package pair whose registry
+  metadata points to the identical integrity-verified embedded license, and carry the exact
+  notices for Go modules linked into runtime binaries.
+- `server/pkg/agent/launch.go`: bounds synchronous probe output while preserving process ownership and timeout errors.
+- `server/pkg/agent/agent_test.go`: covers oversized version output and timeout precedence without executing an installed agent CLI.
+- `server/internal/daemon/bridge_http_test.go`: uses OS-native absolute runtime fixture paths so
+  the Bridge HTTP lifecycle contracts run consistently on Windows and Linux.
+- `.github/workflows/quukk-clawmessenger-runtime.yml`: supplies the GitHub-hosted runner's
+  temporary directory to entry-package tests without weakening the package's fail-closed runtime
+  requirement for `TEMP`/`TMP`, and prefixes runtime package directories with `./` so npm treats
+  them as local folders rather than GitHub repository shorthands.
+- `packages/quukk-clawmessenger/src/process/service-identity.test.ts`,
+  `src/rongcloud/worker-supervisor.test.ts`, `src/router/message-router.test.ts`,
+  `src/router/router.integration.test.ts`, and `src/service.test.ts`: use OS-native temporary and
+  absolute fixture paths so the same security and lifecycle contracts run on Windows and Linux.
+- `packages/quukk-clawmessenger/scripts/audit-tarball.mjs`: excludes bounded HTTP(S) URL text
+  before applying local developer-path checks while continuing to reject checkout paths outside
+  URLs; its package-artifact tests cover Linux CI paths explicitly.
+- `packages/quukk-clawmessenger/src/go/binary.test.ts`, `src/logging/redact.test.ts`, and
+  `src/process/service-identity.test.ts`: remove host-path assumptions and explicitly mock the
+  platform-dependent filesystem behavior exercised by each contract.
+
+New fork-specific files are listed in this task's commit and do not replace upstream source files.

package/NOTICE

@@ -0,0 +1,14 @@
+Multica
+Copyright 2025-2026 Multica, Inc.
+
+This product includes software developed at Multica, Inc.
+(https://github.com/multica-ai/multica).
+
+Multica is distributed under the Multica License, which incorporates the
+complete text of the Apache License, Version 2.0 together with additional
+conditions covering hosted or embedded commercial use, branding and
+copyright information displayed by a Multica user interface, and
+attribution for non-interface use. See the LICENSE file for the full text.
+
+This NOTICE file is provided for attribution purposes only and does not
+modify the Multica License.

package/README.md

@@ -0,0 +1,223 @@
+# Quukk ClawMessenger
+
+Quukk ClawMessenger connects local OpenCode, OpenClaw, Codex, and Hermes agents to
+ClawMessenger. Install one npm package, review the agents detected on this computer, and choose
+which agents to connect. Each selected runtime receives its own RongCloud identity, worker,
+session store, and failure boundary.
+
+**Built on [Multica](https://github.com/multica-ai/multica).** This is a community derivative;
+the local interface retains the Multica product name, logo, copyright, and attribution alongside
+the Quukk ClawMessenger label. Fork source:
+[quukk/quukk-clawmessenger](https://github.com/quukk/quukk-clawmessenger).
+
+## Install and set up
+
+Requirements:
+
+- Node.js 22.13 or newer.
+- A supported Windows, macOS, or Linux desktop build listed below.
+- At least one supported agent CLI installed and authenticated.
+- A compatible ClawMessenger server deployment; Hermes has additional server prerequisites.
+
+Install globally, then open the local setup page:
+
+```bash
+npm install -g quukk-clawmessenger@beta
+quukk-clawmessenger setup
+```
+
+For a terminal-only host, CI, or an environment where a browser must not open:
+
+```bash
+quukk-clawmessenger setup --no-open
+```
+
+The npm `postinstall` hook only launches setup for a global install in an interactive desktop
+session. It does not register an agent, wait for input, or download an executable. CI, local
+installs, non-desktop sessions, and `QUUKK_CLAWMESSENGER_NO_OPEN=1` receive only a setup hint.
+Run `setup` explicitly whenever lifecycle scripts are disabled.
+
+Before upgrading a beta installation, stop the authenticated old daemon so the package manager
+does not reuse or try to replace a running Bridge binary:
+
+```bash
+quukk-clawmessenger stop
+npm install -g quukk-clawmessenger@beta
+quukk-clawmessenger setup
+```
+
+The local service listens only on `127.0.0.1`. Registration starts only after the user reviews
+the detected runtimes and explicitly submits a selection.
+
+## Cloud registration and data disclosure
+
+Before a selected runtime can be registered, setup shows the configured service URL and requires
+a separate confirmation. Registration sends that service a hostname-derived node label, a
+network-interface MAC address when available (or a stable install-derived fallback), the selected
+provider and capability flags, and a runtime-scoped enrollment proof. Each enabled runtime then
+uses its own RongCloud connection; its ClawMessenger chat and task messages traverse that cloud IM
+service.
+
+This beta has no self-service remote identity deletion. Removing a local binding or uninstalling
+the npm package does not delete its server or RongCloud identity. Before enabling a hosted service,
+obtain its operator contact, privacy terms, retention policy, and deletion process. Publication of
+the default hosted service remains blocked until those items and the data-processing review are
+complete.
+
+## Agent login prerequisites
+
+Quukk ClawMessenger does not install, upgrade, or sign in to any agent CLI. Complete the
+provider's own installation and authentication flow first, then run `rescan`:
+
+| Provider | Local prerequisite |
+| --- | --- |
+| OpenCode | `opencode` is runnable and its model/provider credentials are configured. |
+| OpenClaw | `openclaw` is runnable and its gateway/model authentication is configured. |
+| Codex | `codex` is runnable and signed in with the intended OpenAI account or API environment. |
+| Hermes | `hermes` is runnable and its selected model provider is authenticated. |
+
+Detection reports whether a CLI is runnable; it does not prove that every model credential is
+valid. A clear authentication failure from the first task changes that runtime to `needs_auth`.
+Sign in with the provider's CLI, then rescan.
+
+## CLI reference
+
+| Command | Purpose |
+| --- | --- |
+| `quukk-clawmessenger setup` | Start the local service and open the setup page. |
+| `quukk-clawmessenger start` | Start the local service; add `--foreground` to keep it attached. |
+| `quukk-clawmessenger stop` | Gracefully stop verified workers and the local service. |
+| `quukk-clawmessenger status` | Show whether the verified local service is ready. |
+| `quukk-clawmessenger logs` | Read bounded local logs; supports `--lines 1..1000` and `--follow`. |
+| `quukk-clawmessenger doctor` | Show redacted local diagnostics; use `--json` for automation. |
+| `quukk-clawmessenger rescan` | Re-run local detection for all four providers. |
+
+`setup` and `start` accept `--no-open`, `--server-url`, `--workdir`, repeated
+`--authorized-work-root`, four provider-specific `--*-path` overrides, and `--log-level`.
+`status`, `doctor`, and `rescan` accept `--json`. Run `quukk-clawmessenger --help` for the exact
+validated option syntax.
+
+## Headless permission policy
+
+Quukk's local authorization boundary is deny-by-default:
+
+- `authorizedWorkRoots` starts empty. A remote task is rejected until a real local directory is
+  explicitly authorized and the default work directory is inside an authorized root.
+- v1 advertises `approval_events: false`. A CardKit permission action is parsed for compatibility
+  but cannot grant permission or resume a paused provider approval.
+- Quukk does not turn a chat message into arbitrary shell execution. Only the documented message
+  and device-control allowlists are accepted.
+
+The four provider adapters run headlessly and may apply their own non-interactive policy. Review
+the selected CLI's configuration before connecting it. If a provider requires an interactive
+approval that its headless adapter cannot safely resolve, the operation is denied or fails; the
+ClawMessenger client is not treated as an approval authority.
+
+## Configuration and local data
+
+Quukk keeps its data separate from Multica and the legacy single-provider bridges:
+
+| Data | Unix/macOS | Windows |
+| --- | --- | --- |
+| Root | `$HOME/.quukk-clawmessenger/` | `%USERPROFILE%\.quukk-clawmessenger\` |
+| Settings | `config.json` | `config.json` |
+| Protected credentials | `credentials.json` | `credentials.json` |
+| Runtime bindings | `state.json` | `state.json` |
+| Sessions | `sessions.json` | `sessions.json` |
+| Redacted log | `logs/bridge.log` | `logs\bridge.log` |
+| Process identity | `run/bridge.pid`, `run/daemon.pid` | `run\bridge.pid`, `run\daemon.pid` |
+| RongCloud SDK state | `rongcloud/<runtimeId>/` | `rongcloud\<runtimeId>\` |
+
+Configuration precedence is CLI options, then `QUUKK_CLAWMESSENGER_*` environment variables,
+then `config.json`, then built-in defaults. The default server URL is
+`https://newsradar.dreamdt.cn/im`. `config.json` never stores RongCloud tokens or the per-install
+Bridge secret.
+
+## Legacy migration in this beta
+
+The beta CLI and setup page do not automatically inspect or import an older OpenCode
+ClawMessenger installation. Enter the non-secret server, work-directory, authorized-root, and
+provider-path settings again in Quukk setup, then select and register each runtime to obtain its
+new isolated identity.
+
+Legacy files are never moved, changed, or deleted. Do not copy legacy node IDs, MAC-derived
+identities, AppKey/AppSecret values, passwords, tokens, bindings, sessions, or logs into Quukk
+configuration. Automated, explicitly confirmed migration remains disabled until it has a complete
+authenticated setup UI path.
+
+## Diagnostics and recovery
+
+- Start with `quukk-clawmessenger status --json` and `quukk-clawmessenger doctor --json`.
+- Use `quukk-clawmessenger logs --lines 100`; logs and diagnostics redact credentials, tickets,
+  prompts, environment variables, and provider paths.
+- `probe_failed` is a bounded detection failure, not proof that a CLI is absent. Fix the CLI or
+  path override and run `rescan`.
+- Registration and worker failures are isolated per runtime. Re-register only the affected row.
+- A config/state recovery warning is fail-closed. Preserve the files before changing anything,
+  then follow the diagnostic code rather than copying credentials into ordinary config.
+
+## Uninstall
+
+Stop the verified service before removing the package:
+
+```bash
+quukk-clawmessenger stop
+npm uninstall -g quukk-clawmessenger
+```
+
+Uninstall does not silently delete `~/.quukk-clawmessenger` (or the Windows equivalent). That
+directory contains local identity and session data. Remove it manually only when permanent local
+identity/session loss is intended. Remote RongCloud identities are not implicitly deleted by
+uninstalling the local package.
+
+## Supported platforms
+
+| Operating system | x64 | arm64 | Notes |
+| --- | --- | --- | --- |
+| Windows | Supported | Supported | Native platform package; user ACL protects local credentials. |
+| macOS | Supported | Supported | Native platform package. |
+| Linux (glibc) | Supported | Supported | Desktop auto-open requires `DISPLAY` or `WAYLAND_DISPLAY`. |
+
+Unsupported OS/architecture pairs fail with a repair message. The package never falls back to an
+unverified postinstall download.
+
+## Server prerequisite for Hermes and production use
+
+Deploy the matching ClawMessenger server changes before enabling this client. The server must:
+
+- accept `hermes` as its own node type;
+- enforce strict, single-node enrollment proof ownership and shared-edge rate limits;
+- retire anonymous token routes and redact public responses, errors, and logs;
+- enforce node/owner authorization on OM, SaaS, configuration, and download routes; and
+- have an approved rotation or revocation disposition for any credential exposed by an older
+  deployment.
+
+Compatibility enrollment mode is only a migration window and must be off before npm publication.
+The local package cannot make an incompatible or undeployed server safe.
+
+## Packaging checks for maintainers
+
+From a source checkout, copy the exact four root legal files into the entry package and the exact
+root `LICENSE`, `NOTICE`, `MODIFICATIONS.md`, and `GO_THIRD_PARTY_NOTICES.md` into each
+binary-only platform staging package. Build the Node package and Bridge UI, generate
+`npm pack --dry-run --json` output, then pass that report and package directory to
+`scripts/audit-tarball.mjs`. Each platform package also requires its generated `SOURCE.md` and a
+manifest containing the exact linked Go module list. The audit rejects missing legal/module/UI/
+worker/manifest files, unexpected files, source maps, symlinks, traversal, credential-like
+literals, and developer-specific absolute paths. It reports only fixed error codes.
+
+Publishing remains a separate protected action. Do not publish until the server, six-platform
+matrix, clean-install smoke tests, npm ownership/2FA, and legal review gates all pass.
+
+## License and attribution
+
+This derivative is distributed under the complete [Multica License](LICENSE), including its
+additional conditions. The package also carries the unchanged Multica [NOTICE](NOTICE), the fork
+[modification record](MODIFICATIONS.md), and [third-party notices](THIRD_PARTY_NOTICES.md).
+Platform runtime packages additionally carry the checksum-traced Go dependency notices in
+`GO_THIRD_PARTY_NOTICES.md`.
+
+The Multica License restricts hosted service use for third parties and commercial embedding or
+distribution unless the producer grants the required commercial license. A branding waiver is a
+separate grant. This project does not claim either grant. Review the complete license and obtain
+independent legal advice for the intended use.