vilvona 1.0.0

package/docs/announcements/bluebubbles-imessage.md

@@ -0,0 +1,79 @@
+---
+summary: "BlueBubbles support was removed from OpenClaw. Use the bundled iMessage plugin with imsg for new and migrated iMessage setups."
+read_when:
+  - You used the old BlueBubbles channel and need to move to iMessage
+  - You are choosing the supported OpenClaw iMessage setup
+  - You need a short explanation of the BlueBubbles removal
+title: "BlueBubbles removal and the imsg iMessage path"
+---
+
+# BlueBubbles removal and the imsg iMessage path
+
+OpenClaw no longer ships the BlueBubbles channel. iMessage support now runs through the bundled `imessage` plugin, which starts [`imsg`](https://github.com/steipete/imsg) locally or through an SSH wrapper and talks JSON-RPC over stdin/stdout.
+
+If your config still contains `channels.bluebubbles`, migrate it to `channels.imessage`. The legacy `/channels/bluebubbles` docs URL redirects to [Coming from BlueBubbles](/channels/imessage-from-bluebubbles), which has the full config translation table and cutover checklist.
+
+## What changed
+
+- There is no BlueBubbles HTTP server, webhook route, REST password, or BlueBubbles plugin runtime in the supported OpenClaw iMessage path.
+- OpenClaw reads and watches Messages through `imsg` on the Mac where Messages.app is signed in.
+- Basic send, receive, history, and media use the normal `imsg` surfaces and macOS permissions.
+- Advanced actions such as threaded replies, tapbacks, edit, unsend, effects, read receipts, typing indicators, and group management require `imsg launch` with the private API bridge available.
+- Linux and Windows gateways can still use iMessage by setting `channels.imessage.cliPath` to an SSH wrapper that runs `imsg` on the signed-in Mac.
+
+## What to do
+
+1. Install and verify `imsg` on the Messages Mac:
+
+   ```bash
+   brew install steipete/tap/imsg
+   imsg --version
+   imsg chats --limit 3
+   imsg rpc --help
+   ```
+
+2. Grant Full Disk Access and Automation permissions to the process context that runs `imsg` and OpenClaw.
+
+3. Translate the old config:
+
+   ```json5
+   {
+     channels: {
+       imessage: {
+         enabled: true,
+         cliPath: "/opt/homebrew/bin/imsg",
+         dmPolicy: "pairing",
+         allowFrom: ["+15555550123"],
+         groupPolicy: "allowlist",
+         groupAllowFrom: ["+15555550123"],
+         groups: {
+           "*": { requireMention: true },
+         },
+         includeAttachments: true,
+       },
+     },
+   }
+   ```
+
+4. Restart the gateway and verify:
+
+   ```bash
+   openclaw channels status --probe
+   ```
+
+5. Test DMs, groups, attachments, and any private API actions you depend on before deleting your old BlueBubbles server.
+
+## Migration notes
+
+- `channels.bluebubbles.serverUrl` and `channels.bluebubbles.password` have no iMessage equivalent.
+- `channels.bluebubbles.allowFrom`, `groupAllowFrom`, `groups`, `includeAttachments`, attachment roots, media size limits, chunking, and action toggles have iMessage equivalents.
+- `channels.imessage.includeAttachments` is still off by default. Set it explicitly if you expect inbound photos, voice memos, videos, or files to reach the agent.
+- With `groupPolicy: "allowlist"`, copy the old `groups` block, including any `"*"` wildcard entry. Group sender allowlists and the group registry are separate gates.
+- ACP bindings that matched `channel: "bluebubbles"` must be changed to `channel: "imessage"`.
+- Old BlueBubbles session keys do not become iMessage session keys. Pairing approvals carry over by handle, but conversation history under BlueBubbles session keys does not.
+
+## See also
+
+- [Coming from BlueBubbles](/channels/imessage-from-bluebubbles)
+- [iMessage](/channels/imessage)
+- [Configuration reference - iMessage](/gateway/config-channels#imessage)

package/docs/auth-credential-semantics.md

@@ -0,0 +1,124 @@
+---
+summary: "Canonical credential eligibility and resolution semantics for auth profiles"
+title: "Auth credential semantics"
+read_when:
+  - Working on auth profile resolution or credential routing
+  - Debugging model auth failures or profile order
+---
+
+This document defines the canonical credential eligibility and resolution semantics used across:
+
+- `resolveAuthProfileOrder`
+- `resolveApiKeyForProfile`
+- `models status --probe`
+- `doctor-auth`
+
+The goal is to keep selection-time and runtime behavior aligned.
+
+## Stable probe reason codes
+
+- `ok`
+- `excluded_by_auth_order`
+- `missing_credential`
+- `invalid_expires`
+- `expired`
+- `unresolved_ref`
+- `no_model`
+
+## Token credentials
+
+Token credentials (`type: "token"`) support inline `token` and/or `tokenRef`.
+
+### Eligibility rules
+
+1. A token profile is ineligible when both `token` and `tokenRef` are absent.
+2. `expires` is optional.
+3. If `expires` is present, it must be a finite number greater than `0`.
+4. If `expires` is invalid (`NaN`, `0`, negative, non-finite, or wrong type), the profile is ineligible with `invalid_expires`.
+5. If `expires` is in the past, the profile is ineligible with `expired`.
+6. `tokenRef` does not bypass `expires` validation.
+
+### Resolution rules
+
+1. Resolver semantics match eligibility semantics for `expires`.
+2. For eligible profiles, token material may be resolved from inline value or `tokenRef`.
+3. Unresolvable refs produce `unresolved_ref` in `models status --probe` output.
+
+## Agent copy portability
+
+Agent auth inheritance is read-through. When an agent has no local profile, it
+can resolve profiles from the default/main agent store at runtime without
+copying secret material into its own `auth-profiles.json`.
+
+Explicit copy flows, such as `openclaw agents add`, use this portability policy:
+
+- `api_key` profiles are portable unless `copyToAgents: false`.
+- `token` profiles are portable unless `copyToAgents: false`.
+- `oauth` profiles are not portable by default because refresh tokens can be
+  single-use or rotation-sensitive.
+- Provider-owned OAuth flows may opt in with `copyToAgents: true` only when
+  copying refresh material across agents is known safe.
+
+Non-portable profiles remain available through read-through inheritance unless
+the target agent signs in separately and creates its own local profile.
+
+## Config-only auth routes
+
+`auth.profiles` entries with `mode: "aws-sdk"` are routing metadata, not stored
+credentials. They are valid when the target provider uses
+`models.providers.<id>.auth: "aws-sdk"` or plugin-owned Amazon Bedrock setup
+AWS SDK route. These profile ids may appear in `auth.order` and session
+overrides even when no matching entry exists in `auth-profiles.json`.
+
+Do not write `type: "aws-sdk"` into `auth-profiles.json`. If a legacy install
+has such a marker, `openclaw doctor --fix` moves it to `auth.profiles` and
+removes the marker from the credential store.
+
+## Explicit auth order filtering
+
+- When `auth.order.<provider>` or the auth-store order override is set for a
+  provider, `models status --probe` only probes profile ids that remain in the
+  resolved auth order for that provider.
+- A stored profile for that provider that is omitted from the explicit order is
+  not silently tried later. Probe output reports it with
+  `reasonCode: excluded_by_auth_order` and the detail
+  `Excluded by auth.order for this provider.`
+
+## Probe target resolution
+
+- Probe targets can come from auth profiles, environment credentials, or
+  `models.json`.
+- If a provider has credentials but OpenClaw cannot resolve a probeable model
+  candidate for it, `models status --probe` reports `status: no_model` with
+  `reasonCode: no_model`.
+
+## External CLI credential discovery
+
+- Runtime-only credentials owned by external CLIs are discovered only when the
+  provider, runtime, or auth profile is in scope for the current operation, or
+  when a stored local profile for that external source already exists.
+- Auth-store callers should choose an explicit external-CLI discovery mode:
+  `none` for persisted/plugin auth only, `existing` for refreshing already
+  stored external CLI profiles, or `scoped` for a concrete provider/profile set.
+- Read-only/status paths pass `allowKeychainPrompt: false`; they use file-backed
+  external CLI credentials only and do not read or reuse macOS Keychain results.
+
+## OAuth SecretRef Policy Guard
+
+- SecretRef input is for static credentials only.
+- If a profile credential is `type: "oauth"`, SecretRef objects are not supported for that profile credential material.
+- If `auth.profiles.<id>.mode` is `"oauth"`, SecretRef-backed `keyRef`/`tokenRef` input for that profile is rejected.
+- Violations are hard failures in startup/reload auth resolution paths.
+
+## Legacy-Compatible Messaging
+
+For script compatibility, probe errors keep this first line unchanged:
+
+`Auth profile credentials are missing or expired.`
+
+Human-friendly detail and stable reason codes may be added on subsequent lines.
+
+## Related
+
+- [Secrets management](/gateway/secrets)
+- [Auth storage](/concepts/oauth)

package/docs/automation/auth-monitoring.md

@@ -0,0 +1,11 @@
+---
+summary: "Redirect to /gateway/authentication"
+title: "Auth monitoring"
+---
+
+Auth monitoring lives under [Authentication](/gateway/authentication).
+
+## Related
+
+- [Automation troubleshooting](/automation/troubleshooting)
+- [Hooks](/automation/hooks)

package/docs/automation/clawflow.md

@@ -0,0 +1,12 @@
+---
+summary: "Redirect to Task Flow"
+title: "ClawFlow"
+---
+
+ClawFlow was renamed to [Task flow](/automation/taskflow).
+
+## Related
+
+- [Task flow](/automation/taskflow)
+- [Standing orders](/automation/standing-orders)
+- [Hooks](/automation/hooks)