durar-ai 2026.4.4

package/docs/providers/volcengine.md

@@ -0,0 +1,94 @@
+---
+title: "Volcengine (Doubao)"
+summary: "Volcano Engine setup (Doubao models, general + coding endpoints)"
+read_when:
+  - You want to use Volcano Engine or Doubao models with Durar
+  - You need the Volcengine API key setup
+---
+
+# Volcengine (Doubao)
+
+The Volcengine provider gives access to Doubao models and third-party models
+hosted on Volcano Engine, with separate endpoints for general and coding
+workloads.
+
+- Providers: `volcengine` (general) + `volcengine-plan` (coding)
+- Auth: `VOLCANO_ENGINE_API_KEY`
+- API: OpenAI-compatible
+
+## Quick start
+
+1. Set the API key:
+
+```bash
+Durar onboard --auth-choice volcengine-api-key
+```
+
+2. Set a default model:
+
+```json5
+{
+  agents: {
+    defaults: {
+      model: { primary: "volcengine-plan/ark-code-latest" },
+    },
+  },
+}
+```
+
+## Non-interactive example
+
+```bash
+Durar onboard --non-interactive \
+  --mode local \
+  --auth-choice volcengine-api-key \
+  --volcengine-api-key "$VOLCANO_ENGINE_API_KEY"
+```
+
+## Providers and endpoints
+
+| Provider          | Endpoint                                  | Use case       |
+| ----------------- | ----------------------------------------- | -------------- |
+| `volcengine`      | `ark.cn-beijing.volces.com/api/v3`        | General models |
+| `volcengine-plan` | `ark.cn-beijing.volces.com/api/coding/v3` | Coding models  |
+
+Both providers are configured from a single API key. Setup registers both
+automatically.
+
+## Available models
+
+General provider (`volcengine`):
+
+| Model ref                                    | Name                            | Input       | Context |
+| -------------------------------------------- | ------------------------------- | ----------- | ------- |
+| `volcengine/doubao-seed-1-8-251228`          | Doubao Seed 1.8                 | text, image | 256,000 |
+| `volcengine/doubao-seed-code-preview-251028` | doubao-seed-code-preview-251028 | text, image | 256,000 |
+| `volcengine/kimi-k2-5-260127`                | Kimi K2.5                       | text, image | 256,000 |
+| `volcengine/glm-4-7-251222`                  | GLM 4.7                         | text, image | 200,000 |
+| `volcengine/deepseek-v3-2-251201`            | DeepSeek V3.2                   | text, image | 128,000 |
+
+Coding provider (`volcengine-plan`):
+
+| Model ref                                         | Name                     | Input | Context |
+| ------------------------------------------------- | ------------------------ | ----- | ------- |
+| `volcengine-plan/ark-code-latest`                 | Ark Coding Plan          | text  | 256,000 |
+| `volcengine-plan/doubao-seed-code`                | Doubao Seed Code         | text  | 256,000 |
+| `volcengine-plan/glm-4.7`                         | GLM 4.7 Coding           | text  | 200,000 |
+| `volcengine-plan/kimi-k2-thinking`                | Kimi K2 Thinking         | text  | 256,000 |
+| `volcengine-plan/kimi-k2.5`                       | Kimi K2.5 Coding         | text  | 256,000 |
+| `volcengine-plan/doubao-seed-code-preview-251028` | Doubao Seed Code Preview | text  | 256,000 |
+
+`Durar onboard --auth-choice volcengine-api-key` currently sets
+`volcengine-plan/ark-code-latest` as the default model while also registering
+the general `volcengine` catalog.
+
+During onboarding/configure model selection, the Volcengine auth choice prefers
+both `volcengine/*` and `volcengine-plan/*` rows. If those models are not
+loaded yet, Durar falls back to the unfiltered catalog instead of showing an
+empty provider-scoped picker.
+
+## Environment note
+
+If the Gateway runs as a daemon (launchd/systemd), make sure
+`VOLCANO_ENGINE_API_KEY` is available to that process (for example, in
+`~/.Durar/.env` or via `env.shellEnv`).

package/docs/providers/xai.md

@@ -0,0 +1,94 @@
+---
+summary: "Use xAI Grok models in Durar"
+read_when:
+  - You want to use Grok models in Durar
+  - You are configuring xAI auth or model ids
+title: "xAI"
+---
+
+# xAI
+
+Durar ships a bundled `xai` provider plugin for Grok models.
+
+## Setup
+
+1. Create an API key in the xAI console.
+2. Set `XAI_API_KEY`, or run:
+
+```bash
+Durar onboard --auth-choice xai-api-key
+```
+
+3. Pick a model such as:
+
+```json5
+{
+  agents: { defaults: { model: { primary: "xai/grok-4" } } },
+}
+```
+
+Durar now uses the xAI Responses API as the bundled xAI transport. The same
+`XAI_API_KEY` can also power Grok-backed `web_search`, first-class `x_search`,
+and remote `code_execution`.
+If you store an xAI key under `plugins.entries.xai.config.webSearch.apiKey`,
+the bundled xAI model provider now reuses that key as a fallback too.
+`code_execution` tuning lives under `plugins.entries.xai.config.codeExecution`.
+
+## Current bundled model catalog
+
+Durar now includes these xAI model families out of the box:
+
+- `grok-3`, `grok-3-fast`, `grok-3-mini`, `grok-3-mini-fast`
+- `grok-4`, `grok-4-0709`
+- `grok-4-fast`, `grok-4-fast-non-reasoning`
+- `grok-4-1-fast`, `grok-4-1-fast-non-reasoning`
+- `grok-4.20-beta-latest-reasoning`, `grok-4.20-beta-latest-non-reasoning`
+- `grok-code-fast-1`
+
+The plugin also forward-resolves newer `grok-4*` and `grok-code-fast*` ids when
+they follow the same API shape.
+
+Fast-model notes:
+
+- `grok-4-fast`, `grok-4-1-fast`, and the `grok-4.20-beta-*` variants are the
+  current image-capable Grok refs in the bundled catalog.
+- `/fast on` or `agents.defaults.models["xai/<model>"].params.fastMode: true`
+  rewrites native xAI requests as follows:
+  - `grok-3` -> `grok-3-fast`
+  - `grok-3-mini` -> `grok-3-mini-fast`
+  - `grok-4` -> `grok-4-fast`
+  - `grok-4-0709` -> `grok-4-fast`
+
+Legacy compatibility aliases still normalize to the canonical bundled ids. For
+example:
+
+- `grok-4-fast-reasoning` -> `grok-4-fast`
+- `grok-4-1-fast-reasoning` -> `grok-4-1-fast`
+- `grok-4.20-reasoning` -> `grok-4.20-beta-latest-reasoning`
+- `grok-4.20-non-reasoning` -> `grok-4.20-beta-latest-non-reasoning`
+
+## Web search
+
+The bundled `grok` web-search provider uses `XAI_API_KEY` too:
+
+```bash
+Durar config set tools.web.search.provider grok
+```
+
+## Known limits
+
+- Auth is API-key only today. There is no xAI OAuth/device-code flow in Durar yet.
+- `grok-4.20-multi-agent-experimental-beta-0304` is not supported on the normal xAI provider path because it requires a different upstream API surface than the standard Durar xAI transport.
+
+## Notes
+
+- Durar applies xAI-specific tool-schema and tool-call compatibility fixes automatically on the shared runner path.
+- Native xAI requests default `tool_stream: true`. Set
+  `agents.defaults.models["xai/<model>"].params.tool_stream` to `false` to
+  disable it.
+- The bundled xAI wrapper strips unsupported strict tool-schema flags and
+  reasoning payload keys before sending native xAI requests.
+- `web_search`, `x_search`, and `code_execution` are exposed as Durar tools. Durar enables the specific xAI built-in it needs inside each tool request instead of attaching all native tools to every chat turn.
+- `x_search` and `code_execution` are owned by the bundled xAI plugin rather than hardcoded into the core model runtime.
+- `code_execution` is remote xAI sandbox execution, not local [`exec`](/tools/exec).
+- For the broader provider overview, see [Model providers](/providers/index).

package/docs/providers/xiaomi.md

@@ -0,0 +1,89 @@
+---
+summary: "Use Xiaomi MiMo models with Durar"
+read_when:
+  - You want Xiaomi MiMo models in Durar
+  - You need XIAOMI_API_KEY setup
+title: "Xiaomi MiMo"
+---
+
+# Xiaomi MiMo
+
+Xiaomi MiMo is the API platform for **MiMo** models. Durar uses the Xiaomi
+OpenAI-compatible endpoint with API-key authentication. Create your API key in the
+[Xiaomi MiMo console](https://platform.xiaomimimo.com/#/console/api-keys), then configure the
+bundled `xiaomi` provider with that key.
+
+## Built-in catalog
+
+- Base URL: `https://api.xiaomimimo.com/v1`
+- API: `openai-completions`
+- Authorization: `Bearer $XIAOMI_API_KEY`
+
+| Model ref              | Input       | Context   | Max output | Notes                        |
+| ---------------------- | ----------- | --------- | ---------- | ---------------------------- |
+| `xiaomi/mimo-v2-flash` | text        | 262,144   | 8,192      | Default model                |
+| `xiaomi/mimo-v2-pro`   | text        | 1,048,576 | 32,000     | Reasoning-enabled            |
+| `xiaomi/mimo-v2-omni`  | text, image | 262,144   | 32,000     | Reasoning-enabled multimodal |
+
+## CLI setup
+
+```bash
+Durar onboard --auth-choice xiaomi-api-key
+# or non-interactive
+Durar onboard --auth-choice xiaomi-api-key --xiaomi-api-key "$XIAOMI_API_KEY"
+```
+
+## Config snippet
+
+```json5
+{
+  env: { XIAOMI_API_KEY: "your-key" },
+  agents: { defaults: { model: { primary: "xiaomi/mimo-v2-flash" } } },
+  models: {
+    mode: "merge",
+    providers: {
+      xiaomi: {
+        baseUrl: "https://api.xiaomimimo.com/v1",
+        api: "openai-completions",
+        apiKey: "XIAOMI_API_KEY",
+        models: [
+          {
+            id: "mimo-v2-flash",
+            name: "Xiaomi MiMo V2 Flash",
+            reasoning: false,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 8192,
+          },
+          {
+            id: "mimo-v2-pro",
+            name: "Xiaomi MiMo V2 Pro",
+            reasoning: true,
+            input: ["text"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 1048576,
+            maxTokens: 32000,
+          },
+          {
+            id: "mimo-v2-omni",
+            name: "Xiaomi MiMo V2 Omni",
+            reasoning: true,
+            input: ["text", "image"],
+            cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+            contextWindow: 262144,
+            maxTokens: 32000,
+          },
+        ],
+      },
+    },
+  },
+}
+```
+
+## Notes
+
+- Default model ref: `xiaomi/mimo-v2-flash`.
+- Additional built-in models: `xiaomi/mimo-v2-pro`, `xiaomi/mimo-v2-omni`.
+- The provider is injected automatically when `XIAOMI_API_KEY` is set (or an auth profile exists).
+- See [/concepts/model-providers](/concepts/model-providers) for provider rules.

package/docs/providers/zai.md

@@ -0,0 +1,75 @@
+---
+summary: "Use Z.AI (GLM models) with Durar"
+read_when:
+  - You want Z.AI / GLM models in Durar
+  - You need a simple ZAI_API_KEY setup
+title: "Z.AI"
+---
+
+# Z.AI
+
+Z.AI is the API platform for **GLM** models. It provides REST APIs for GLM and uses API keys
+for authentication. Create your API key in the Z.AI console. Durar uses the `zai` provider
+with a Z.AI API key.
+
+## CLI setup
+
+```bash
+# Generic API-key setup with endpoint auto-detection
+Durar onboard --auth-choice zai-api-key
+
+# Coding Plan Global, recommended for Coding Plan users
+Durar onboard --auth-choice zai-coding-global
+
+# Coding Plan CN (China region), recommended for Coding Plan users
+Durar onboard --auth-choice zai-coding-cn
+
+# General API
+Durar onboard --auth-choice zai-global
+
+# General API CN (China region)
+Durar onboard --auth-choice zai-cn
+```
+
+## Config snippet
+
+```json5
+{
+  env: { ZAI_API_KEY: "sk-..." },
+  agents: { defaults: { model: { primary: "zai/glm-5" } } },
+}
+```
+
+`zai-api-key` lets Durar detect the matching Z.AI endpoint from the key and
+apply the correct base URL automatically. Use the explicit regional choices when
+you want to force a specific Coding Plan or general API surface.
+
+## Bundled GLM catalog
+
+Durar currently seeds the bundled `zai` provider with:
+
+- `glm-5.1`
+- `glm-5`
+- `glm-5-turbo`
+- `glm-5v-turbo`
+- `glm-4.7`
+- `glm-4.7-flash`
+- `glm-4.7-flashx`
+- `glm-4.6`
+- `glm-4.6v`
+- `glm-4.5`
+- `glm-4.5-air`
+- `glm-4.5-flash`
+- `glm-4.5v`
+
+## Notes
+
+- GLM models are available as `zai/<model>` (example: `zai/glm-5`).
+- Default bundled model ref: `zai/glm-5`
+- Unknown `glm-5*` ids still forward-resolve on the bundled provider path by
+  synthesizing provider-owned metadata from the `glm-4.7` template when the id
+  matches the current GLM-5 family shape.
+- `tool_stream` is enabled by default for Z.AI tool-call streaming. Set
+  `agents.defaults.models["zai/<model>"].params.tool_stream` to `false` to disable it.
+- See [/providers/glm](/providers/glm) for the model family overview.
+- Z.AI uses Bearer auth with your API key.

package/docs/reference/AGENTS.default.md

@@ -0,0 +1,126 @@
+---
+title: "Default AGENTS.md"
+summary: "Default Durar agent instructions and skills roster for the personal assistant setup"
+read_when:
+  - Starting a new Durar agent session
+  - Enabling or auditing default skills
+---
+
+# AGENTS.md - Durar Personal Assistant (default)
+
+## First run (recommended)
+
+Durar uses a dedicated workspace directory for the agent. Default: `~/.Durar/workspace` (configurable via `agents.defaults.workspace`).
+
+1. Create the workspace (if it doesn’t already exist):
+
+```bash
+mkdir -p ~/.Durar/workspace
+```
+
+2. Copy the default workspace templates into the workspace:
+
+```bash
+cp docs/reference/templates/AGENTS.md ~/.Durar/workspace/AGENTS.md
+cp docs/reference/templates/SOUL.md ~/.Durar/workspace/SOUL.md
+cp docs/reference/templates/TOOLS.md ~/.Durar/workspace/TOOLS.md
+```
+
+3. Optional: if you want the personal assistant skill roster, replace AGENTS.md with this file:
+
+```bash
+cp docs/reference/AGENTS.default.md ~/.Durar/workspace/AGENTS.md
+```
+
+4. Optional: choose a different workspace by setting `agents.defaults.workspace` (supports `~`):
+
+```json5
+{
+  agents: { defaults: { workspace: "~/.Durar/workspace" } },
+}
+```
+
+## Safety defaults
+
+- Don’t dump directories or secrets into chat.
+- Don’t run destructive commands unless explicitly asked.
+- Don’t send partial/streaming replies to external messaging surfaces (only final replies).
+
+## Session start (required)
+
+- Read `SOUL.md`, `USER.md`, and today+yesterday in `memory/`.
+- Read `MEMORY.md` when present; only fall back to lowercase `memory.md` when `MEMORY.md` is absent.
+- Do it before responding.
+
+## Soul (required)
+
+- `SOUL.md` defines identity, tone, and boundaries. Keep it current.
+- If you change `SOUL.md`, tell the user.
+- You are a fresh instance each session; continuity lives in these files.
+
+## Shared spaces (recommended)
+
+- You’re not the user’s voice; be careful in group chats or public channels.
+- Don’t share private data, contact info, or internal notes.
+
+## Memory system (recommended)
+
+- Daily log: `memory/YYYY-MM-DD.md` (create `memory/` if needed).
+- Long-term memory: `MEMORY.md` for durable facts, preferences, and decisions.
+- Lowercase `memory.md` is legacy fallback only; do not keep both root files on purpose.
+- On session start, read today + yesterday + `MEMORY.md` when present, otherwise `memory.md`.
+- Capture: decisions, preferences, constraints, open loops.
+- Avoid secrets unless explicitly requested.
+
+## Tools & skills
+
+- Tools live in skills; follow each skill’s `SKILL.md` when you need it.
+- Keep environment-specific notes in `TOOLS.md` (Notes for Skills).
+
+## Backup tip (recommended)
+
+If you treat this workspace as Clawd’s “memory”, make it a git repo (ideally private) so `AGENTS.md` and your memory files are backed up.
+
+```bash
+cd ~/.Durar/workspace
+git init
+git add AGENTS.md
+git commit -m "Add Clawd workspace"
+# Optional: add a private remote + push
+```
+
+## What Durar Does
+
+- Runs WhatsApp gateway + Pi coding agent so the assistant can read/write chats, fetch context, and run skills via the host Mac.
+- macOS app manages permissions (screen recording, notifications, microphone) and exposes the `Durar` CLI via its bundled binary.
+- Direct chats collapse into the agent's `main` session by default; groups stay isolated as `agent:<agentId>:<channel>:group:<id>` (rooms/channels: `agent:<agentId>:<channel>:channel:<id>`); heartbeats keep background tasks alive.
+
+## Core Skills (enable in Settings → Skills)
+
+- **mcporter** — Tool server runtime/CLI for managing external skill backends.
+- **Peekaboo** — Fast macOS screenshots with optional AI vision analysis.
+- **camsnap** — Capture frames, clips, or motion alerts from RTSP/ONVIF security cams.
+- **oracle** — OpenAI-ready agent CLI with session replay and browser control.
+- **eightctl** — Control your sleep, from the terminal.
+- **imsg** — Send, read, stream iMessage & SMS.
+- **wacli** — WhatsApp CLI: sync, search, send.
+- **discord** — Discord actions: react, stickers, polls. Use `user:<id>` or `channel:<id>` targets (bare numeric ids are ambiguous).
+- **gog** — Google Suite CLI: Gmail, Calendar, Drive, Contacts.
+- **spotify-player** — Terminal Spotify client to search/queue/control playback.
+- **sag** — ElevenLabs speech with mac-style say UX; streams to speakers by default.
+- **Sonos CLI** — Control Sonos speakers (discover/status/playback/volume/grouping) from scripts.
+- **blucli** — Play, group, and automate BluOS players from scripts.
+- **OpenHue CLI** — Philips Hue lighting control for scenes and automations.
+- **OpenAI Whisper** — Local speech-to-text for quick dictation and voicemail transcripts.
+- **Gemini CLI** — Google Gemini models from the terminal for fast Q&A.
+- **agent-tools** — Utility toolkit for automations and helper scripts.
+
+## Usage Notes
+
+- Prefer the `Durar` CLI for scripting; mac app handles permissions.
+- Run installs from the Skills tab; it hides the button if a binary is already present.
+- Keep heartbeats enabled so the assistant can schedule reminders, monitor inboxes, and trigger camera captures.
+- Canvas UI runs full-screen with native overlays. Avoid placing critical controls in the top-left/top-right/bottom edges; add explicit gutters in the layout and don’t rely on safe-area insets.
+- For browser-driven verification, use `Durar browser` (tabs/status/screenshot) with the Durar-managed Chrome profile.
+- For DOM inspection, use `Durar browser eval|query|dom|snapshot` (and `--json`/`--out` when you need machine output).
+- For interactions, use `Durar browser click|type|hover|drag|select|upload|press|wait|navigate|back|evaluate|run` (click/type require snapshot refs; use `evaluate` for CSS selectors).

package/docs/reference/RELEASING.md

@@ -0,0 +1,138 @@
+---
+title: "Release Policy"
+summary: "Public release channels, version naming, and cadence"
+read_when:
+  - Looking for public release channel definitions
+  - Looking for version naming and cadence
+---
+
+# Release Policy
+
+Durar has three public release lanes:
+
+- stable: tagged releases that publish to npm `beta` by default, or to npm `latest` when explicitly requested
+- beta: prerelease tags that publish to npm `beta`
+- dev: the moving head of `main`
+
+## Version naming
+
+- Stable release version: `YYYY.M.D`
+  - Git tag: `vYYYY.M.D`
+- Stable correction release version: `YYYY.M.D-N`
+  - Git tag: `vYYYY.M.D-N`
+- Beta prerelease version: `YYYY.M.D-beta.N`
+  - Git tag: `vYYYY.M.D-beta.N`
+- Do not zero-pad month or day
+- `latest` means the current promoted stable npm release
+- `beta` means the current beta install target
+- Stable and stable correction releases publish to npm `beta` by default; release operators can target `latest` explicitly, or promote a vetted beta build later
+- Every Durar release ships the npm package and macOS app together
+
+## Release cadence
+
+- Releases move beta-first
+- Stable follows only after the latest beta is validated
+- Detailed release procedure, approvals, credentials, and recovery notes are
+  maintainer-only
+
+## Release preflight
+
+- Run `pnpm build && pnpm ui:build` before `pnpm release:check` so the expected
+  `dist/*` release artifacts and Control UI bundle exist for the pack
+  validation step
+- Run `pnpm release:check` before every tagged release
+- Main-branch npm preflight also runs
+  `Durar_LIVE_TEST=1 Durar_LIVE_CACHE_TEST=1 pnpm test:live:cache`
+  before packaging the tarball, using both `OPENAI_API_KEY` and
+  `ANTHROPIC_API_KEY` workflow secrets
+- Run `RELEASE_TAG=vYYYY.M.D node --import tsx scripts/Durar-npm-release-check.ts`
+  (or the matching beta/correction tag) before approval
+- After npm publish, run
+  `node --import tsx scripts/Durar-npm-postpublish-verify.ts YYYY.M.D`
+  (or the matching beta/correction version) to verify the published registry
+  install path in a fresh temp prefix
+- Maintainer release automation now uses preflight-then-promote:
+  - real npm publish must pass a successful npm `preflight_run_id`
+  - stable npm releases default to `beta`
+  - stable npm publish can target `latest` explicitly via workflow input
+  - stable npm promotion from `beta` to `latest` is still available as an explicit manual mode on the trusted `Durar NPM Release` workflow
+  - that promotion mode still needs a valid `NPM_TOKEN` in the `npm-release` environment because npm `dist-tag` management is separate from trusted publishing
+  - public `macOS Release` is validation-only
+  - real private mac publish must pass successful private mac
+    `preflight_run_id` and `validate_run_id`
+  - the real publish paths promote prepared artifacts instead of rebuilding
+    them again
+- For stable correction releases like `YYYY.M.D-N`, the post-publish verifier
+  also checks the same temp-prefix upgrade path from `YYYY.M.D` to `YYYY.M.D-N`
+  so release corrections cannot silently leave older global installs on the
+  base stable payload
+- npm release preflight fails closed unless the tarball includes both
+  `dist/control-ui/index.html` and a non-empty `dist/control-ui/assets/` payload
+  so we do not ship an empty browser dashboard again
+- If the release work touched CI planning, extension timing manifests, or fast
+  test matrices, regenerate and review the planner-owned `checks-fast-extensions`
+  workflow matrix outputs from `.github/workflows/ci.yml`
+  before approval so release notes do not describe a stale CI layout
+- Stable macOS release readiness also includes the updater surfaces:
+  - the GitHub release must end up with the packaged `.zip`, `.dmg`, and `.dSYM.zip`
+  - `appcast.xml` on `main` must point at the new stable zip after publish
+  - the packaged app must keep a non-debug bundle id, a non-empty Sparkle feed
+    URL, and a `CFBundleVersion` at or above the canonical Sparkle build floor
+    for that release version
+
+## NPM workflow inputs
+
+`Durar NPM Release` accepts these operator-controlled inputs:
+
+- `tag`: required release tag such as `v2026.4.2`, `v2026.4.2-1`, or
+  `v2026.4.2-beta.1`
+- `preflight_only`: `true` for validation/build/package only, `false` for the
+  real publish path
+- `preflight_run_id`: required on the real publish path so the workflow reuses
+  the prepared tarball from the successful preflight run
+- `npm_dist_tag`: npm target tag for the publish path; defaults to `beta`
+- `promote_beta_to_latest`: `true` to skip publish and move an already-published
+  stable `beta` build onto `latest`
+
+Rules:
+
+- Stable and correction tags may publish to either `beta` or `latest`
+- Beta prerelease tags may publish only to `beta`
+- The real publish path must use the same `npm_dist_tag` used during preflight;
+  the workflow verifies that metadata before publish continues
+- Promotion mode must use a stable or correction tag, `preflight_only=false`,
+  an empty `preflight_run_id`, and `npm_dist_tag=beta`
+- Promotion mode also requires a valid `NPM_TOKEN` in the `npm-release`
+  environment because `npm dist-tag add` still needs regular npm auth
+
+## Stable npm release sequence
+
+When cutting a stable npm release:
+
+1. Run `Durar NPM Release` with `preflight_only=true`
+2. Choose `npm_dist_tag=beta` for the normal beta-first flow, or `latest` only
+   when you intentionally want a direct stable publish
+3. Save the successful `preflight_run_id`
+4. Run `Durar NPM Release` again with `preflight_only=false`, the same
+   `tag`, the same `npm_dist_tag`, and the saved `preflight_run_id`
+5. If the release landed on `beta`, run `Durar NPM Release` later with the
+   same stable `tag`, `promote_beta_to_latest=true`, `preflight_only=false`,
+   `preflight_run_id` empty, and `npm_dist_tag=beta` when you want to move that
+   published build to `latest`
+
+The promotion mode still requires the `npm-release` environment approval and a
+valid `NPM_TOKEN` in that environment.
+
+That keeps the direct publish path and the beta-first promotion path both
+documented and operator-visible.
+
+## Public references
+
+- [`.github/workflows/Durar-npm-release.yml`](https://github.com/openclaw/openclaw/blob/main/.github/workflows/Durar-npm-release.yml)
+- [`scripts/Durar-npm-release-check.ts`](https://github.com/openclaw/openclaw/blob/main/scripts/Durar-npm-release-check.ts)
+- [`scripts/package-mac-dist.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/package-mac-dist.sh)
+- [`scripts/make_appcast.sh`](https://github.com/openclaw/openclaw/blob/main/scripts/make_appcast.sh)
+
+Maintainers use the private release docs in
+[`Durar/maintainers/release/README.md`](https://github.com/Durar/maintainers/blob/main/release/README.md)
+for the actual runbook.