uc-config 0.1.0

package/docs/cli.md

@@ -0,0 +1,125 @@
+# CLI reference
+
+Run as `npm run uc -- <command>` inside this repo, or `npx uc-config <command>`
+when installed as a dependency. Global option: `--workspace <dir>` (directory
+holding `remote.config.ts` and `.uc/`; default: current directory).
+
+Most commands take `--target <name>`. The default is `$UC_TARGET`; otherwise
+the workspace's only target if exactly one is connected; otherwise `home`.
+
+## Commands
+
+| Command                                        | Writes to remote  | Purpose                                                                 |
+| ---------------------------------------------- | ----------------- | ----------------------------------------------------------------------- |
+| `init`                                         | no                | Scaffold a private config workspace. Never overwrites files.            |
+| `connect <name> --host <url>`                  | no                | Record a target (identity, firmware). Rerun after firmware updates.     |
+| `auth`                                         | API key only      | Exchange the web-configurator PIN (`UC_PIN` or prompt) for an API key.  |
+| `doctor`                                       | no                | Verify identity and read access to every required endpoint.             |
+| `diagnose [--json]`                            | no                | Orphaned entity references, disconnected integrations, suggested fixes. |
+| `inventory [--out f] [--bindings f.ts]`        | no                | Raw (redacted) remote state; optional typed entity/command bindings.    |
+| `import [--out f.ts]`                          | no                | Generate editable config from the live remote. Never overwrites.        |
+| `compile [--config f] [--out f]`               | no                | Evaluate TS config into `.uc/build.json`. Offline.                      |
+| `plan [--out f] [--prune] [--overwrite-drift]` | no                | Three-way diff: source vs last-applied vs live.                         |
+| `apply <plan> [--adopt-only]`                  | yes               | Execute a saved plan after re-verifying preconditions.                  |
+| `check`                                        | no                | Re-plan and exit 2 if anything differs.                                 |
+| `resume`                                       | maybe             | Continue paused setup; reconcile an interrupted apply.                  |
+| `setup status/respond <key>`                   | yes               | Drive interactive integration/dock setup.                               |
+| `pairing status/respond <remoteId>`            | yes               | Bluetooth pairing steps.                                                |
+| `ir learn/capture <emitterId>`                 | yes               | Learn IR codes from a physical remote.                                  |
+| `state adopt <key> <id>` / `forget` / `move`   | no                | Edit local ownership bindings.                                          |
+| `rollback [--out f]`                           | no                | Build a compensating plan from the last journal.                        |
+| `backup --out f`                               | stops intgs       | Native full backup. Disruptive; not for routine use.                    |
+| `api <METHOD> <path> [--data json] [--write]`  | only with --write | Raw authenticated Core API call; output redacted.                       |
+
+Exit codes: `0` ok, `1` error, `2` drift/conflicts/deferred/diagnose findings,
+`3` paused for a human step.
+
+## Authentication
+
+`auth` prompts for the web configurator PIN. Enable the web configurator on the
+remote first, and approve the key on the remote if asked. Non-interactive
+options: set `UC_PIN`, or set `UC_API_KEY` to an existing key (`connect
+--token-env NAME` changes the variable name). The key is stored in
+`.uc/credentials.json` with mode 0600. Never commit or print it.
+
+Configuration secrets use `secret('env:NAME')` or, on macOS,
+`secret('keychain:service/account')`. An optional second argument is a
+non-secret version label that triggers rotation. Raw secret values never appear
+in plans, state or journals.
+
+## Adopting an existing remote
+
+`import` generates config without taking ownership. The first `plan` shows
+`= adopt` operations; `apply <plan> --adopt-only` records the baseline locally
+and refuses any remote write. Import warnings list what can't be recovered,
+such as original setup credentials, driver archives and binary assets.
+
+## Provisioning (new integrations, docks, remotes)
+
+A new dependency is created before its dependents. When a plan reports
+**deferred** resources, apply the current phase, then **plan again**. Newly
+created activities and macros first receive their entity membership, which
+exposes the command metadata needed to validate their sequences and buttons.
+
+```sh
+npm run uc -- setup status media
+npm run uc -- setup respond media --input setup-response.json   # {"input_values": {...}}
+npm run uc -- setup respond media --confirm
+npm run uc -- resume
+npm run uc -- plan
+```
+
+Secret-bearing setup values can be written as `{"$secret":"env:DEVICE_PIN"}`.
+Expired or rejected setup sessions are reported, never silently restarted.
+
+```sh
+npm run uc -- pairing status REMOTE_ENTITY_ID
+npm run uc -- pairing respond REMOTE_ENTITY_ID --input pairing-response.json  # {"id":11,"passkey":{"$secret":"env:BT_PASSKEY"}}
+npm run uc -- ir learn EMITTER_ID
+npm run uc -- ir capture EMITTER_ID --out learned.json
+```
+
+Installing _community_ integrations (download, version selection, updates) is
+the [UC Integration Manager](https://github.com/JackJPowell/uc-intg-manager)'s
+job. uc-config's `driver()` registers an already-running external driver, and
+`driverArchive()` uploads a local archive.
+
+## Ownership, recovery and removal
+
+- Plans compare three things: source, the last applied state and live data.
+  Live edits to owned fields produce conflicts. Copy the live value into source
+  to accept it; `plan --overwrite-drift` restores the source value instead.
+- Apply verifies identity, firmware, state revision, plan integrity and live
+  preconditions, and re-reads before each mutation. The Core API is not
+  transactional, so avoid configurator edits while an apply runs.
+- Per-target locks prevent two local writers. A lock left by a crashed process
+  is kept until someone inspects it.
+- Failed or uncertain writes block the next apply until `resume` runs. A create
+  whose outcome is unknown is never replayed; inspect inventory and run
+  `state adopt KEY EXACT_ID` if it succeeded.
+- `state move OLD NEW` keeps the remote ID when you rename a logical key.
+  `state forget KEY` gives up ownership without deleting anything.
+- Removing a managed resource from source needs `plan --prune` or
+  `state forget`. Pruning checks inbound references and never bulk-deletes.
+  Integration, driver, dock and entity removal is blocked; handle it explicitly.
+- `rollback` refuses when there is later drift, created or deleted resources,
+  fields that were previously absent, or irreversible provisioning.
+  Earlier journals stay in `.uc/journals/history/`.
+
+## Ownership rules for arrays and fields
+
+Arrays (page items, sequences, entity membership) are owned as whole fields.
+Omitting a scalar or object field gives up ownership without clearing it. To
+clear a collection, declare `[]`. Page-item defaults returned by the remote are
+ignored when you didn't declare them.
+
+## Limits
+
+- Import is not a full disaster-recovery export. Setup secrets, driver binaries
+  and some assets cannot be read back.
+- The API doesn't expose installed driver digests, so a driver replaced out of
+  band can't be fully detected.
+- Immutable creation fields (e.g. IR remote codeset) need an explicit
+  replacement.
+- Firmware installs, Wi-Fi bootstrap and external-service deployment are out of
+  scope.

package/docs/configuration-authoring.md

@@ -0,0 +1,196 @@
+# Authoring Remote 3 configuration
+
+Edit `remote.config.ts`. It exports a `defineRemote({ schemaVersion: 1, resources })`
+object. TypeScript constants, functions, imports, and object spreads can reuse
+configuration, but the final value must be plain JSON-compatible data. Avoid
+`undefined`, functions, class instances, cycles, non-finite numbers, and side effects.
+Compile executes this trusted code locally; it does not install JavaScript on the remote.
+
+## Resource anatomy and identity
+
+Each `resources` key is a stable local name. The resource describes native API data:
+
+```ts
+import { defineRemote, ref } from "uc-config";
+
+export default defineRemote({
+  schemaVersion: 1,
+  resources: {
+    "activity.watch_tv": {
+      kind: "activity",
+      id: "EXISTING_ACTIVITY_ID",
+      data: { name: { en_US: "Watch TV" } },
+    },
+    "activity.watch_tv.button.volume_up_short_press": {
+      kind: "activityButton",
+      parent: ref("activity.watch_tv"),
+      id: "VOLUME_UP/short_press",
+      data: {
+        short_press: {
+          entity_id: "EXACT_CONFIGURED_ENTITY_ID",
+          cmd_id: "EXACT_SUPPORTED_COMMAND_ID",
+          params: {},
+        },
+      },
+    },
+  },
+});
+```
+
+This is a structural example with placeholders, not a deployable setup. The command
+target also needs to be in the activity's `options.entity_ids` before using the binding.
+
+| Field                  | Meaning                                                                                                   |
+| ---------------------- | --------------------------------------------------------------------------------------------------------- |
+| Resource map key       | Local identity used by references, plans, and state; not a display name.                                  |
+| `kind`                 | Supported resource kind from `src/model.ts`.                                                              |
+| `id`                   | Exact native remote ID, or kind-specific identity such as `VOLUME_UP/short_press`. Preserve existing IDs. |
+| `parent`               | Native parent ID or `ref("logical.key")`.                                                                 |
+| `data`                 | Desired writable fields this configuration owns.                                                          |
+| `create`               | Native creation/setup payload; distinct from update data. Imported resources may lack it.                 |
+| `dependsOn`            | Additional logical resource keys that must be ready first. References also establish dependencies.        |
+| `file`, `resourceType` | Local artifact path and asset type for the applicable helpers. Compilation records a content hash.        |
+
+Use unique keys. JavaScript object construction can overwrite duplicate keys before
+validation. Renaming a key requires updating its references and running
+`npm run uc -- state move OLD NEW`; changing `data.name` does not.
+
+## Editing the imported setup
+
+Keep the existing native objects unless a reusable helper makes the requested change
+clearer. Rewriting an imported activity with `activity()` can change its locale map
+(`en_US` versus the helper's `en`), add creation inputs, or change owned fields.
+
+- **Rename a displayed activity:** edit its existing `data.name` locale entry.
+  Preserve its logical key, `id`, and other locales.
+- **Change a physical button:** locate its `activityButton` or `remoteButton`
+  resource by parent and button ID. Edit the command under `data.short_press` or
+  `data.long_press`; preserve the other bindings. Button IDs use uppercase names
+  and a press suffix, for example `HOME/long_press`.
+- **Change a sequence:** edit `data.options.sequences.on` or `.off` for activities,
+  or `data.options.sequence` for macros. Native command steps use
+  `{ type: "command", command: { entity_id, cmd_id, params } }`; delays use
+  `{ type: "delay", delay: 500 }` (milliseconds). Preserve order and other steps.
+- **Change a screen:** edit the appropriate child `activityPage` or `remotePage`.
+  Native items use `location: { x, y }` and optional `size: { width, height }`.
+  Coordinates are zero-based; items must fit the grid and not overlap.
+- **Use another device:** verify its exact configured entity ID and supported
+  command metadata, then include it in the activity/macro's entity membership.
+  Display names and available integration entity IDs are not interchangeable with
+  configured command target IDs.
+
+Arrays are owned as whole fields, including page items, sequences, and entity
+membership. Keep unrelated entries when editing one item. Omitting a field gives
+up ownership without clearing its live value; `[]` explicitly clears a collection.
+Use only native-schema-supported empty values for other fields.
+
+Do not reimport over the active source to change one setting. If live values must
+be inspected, import to a new file and selectively reconcile the relevant fields.
+Treat generated inventory/bindings as discovery snapshots that may need refreshing.
+
+## Composing new resources with helpers
+
+The helper API produces the same resource objects. This example uses placeholders
+that must be replaced with verified inventory values:
+
+```ts
+import {
+  activity,
+  bind,
+  button,
+  command,
+  defineRemote,
+  delay,
+  page,
+  ref,
+} from "uc-config";
+
+const player = "EXACT_CONFIGURED_ENTITY_ID";
+const home = command(player, "EXACT_SUPPORTED_HOME_COMMAND_ID");
+
+export default defineRemote({
+  schemaVersion: 1,
+  resources: {
+    "activity.watch": activity({
+      name: "Watch",
+      entities: [player],
+      on: [home, delay(500)],
+    }),
+    "activity.watch.home": bind(ref("activity.watch"), "HOME", home),
+    "activity.watch.controls": page(ref("activity.watch"), {
+      name: "Controls",
+      grid: { width: 4, height: 6 },
+      items: [button({ label: "Home", at: [0, 0], command: home })],
+    }),
+  },
+});
+```
+
+Helpers `activity({ on, off })` and `macro({ steps })` wrap command steps for you;
+do not pass already-wrapped native command steps to these arrays. `button()` takes
+`at: [x, y]` and optional `size: [width, height]`, unlike native item objects.
+
+`bind(parent, button, command, press, scope)` defaults to `short_press` and
+`activity`. `page(parent, data, id, scope)` also defaults to activity scope.
+For remote children choose `"remote"`; for commands local to that remote use
+`localCommand(cmdId, params?)`, which omits `entity_id`. Verify supported commands
+instead of inferring their names.
+
+For native structures without a dedicated helper, use `resource(kind, options)`.
+Exported `Schemas` exposes native request types. See [the complete template](../examples/full-setup.ts)
+and [the helper implementation](../src/dsl.ts) for exact signatures.
+
+## Integrations and provisioning
+
+Use the driver's advertised setup schema; there is no universal device setup payload.
+`integration()` takes a driver ID/reference, name, and driver-specific `setup` data.
+`entity()` selects one exact available entity using its integration parent and
+`entityId`. Do not configure every discovered entity implicitly.
+
+`driver()` registers an already-running external service; it does not deploy that
+service. `driverArchive()` installs a local archive. `dock()`, `remote()`,
+`pairing()`, and `irCode()` cover their respective native setup resources. See the
+README and complete template before adding these resources.
+
+Use `secret("env:VARIABLE")` or `secret("keychain:service/account")` for secret
+inputs. An optional second argument is a non-secret rotation version. Never put
+PINs/API keys into source or print `.uc/credentials.json`.
+
+New resources may require multiple plan/apply phases. Integration setup and pairing
+can pause for user interaction. Inspect `setup status`, provide the requested input
+through `setup respond`, and use `resume` as documented in [the CLI reference](cli.md). Replan after
+each completed phase; never bypass deferred dependency or command validation.
+
+Imported configuration is not a full disaster-recovery backup: original setup
+credentials, driver archives, and binary assets may be missing. Installing and
+updating community integrations is handled by the
+[UC Integration Manager](https://github.com/JackJPowell/uc-intg-manager); run
+`npm run uc -- diagnose` after any integration update.
+
+## Review and apply
+
+```sh
+npm run check:examples
+npm run uc -- compile
+npm run uc -- plan --out .uc/plan.json
+```
+
+Typechecking checks source shape. Compile evaluates source and validates local
+structure into `.uc/build.json`. Plan reads the remote and compares desired values,
+live values, and the local baseline; it does not deploy changes. Inspect all
+operations, deferred work, and conflicts. Do not automatically resolve drift by
+adding `--overwrite-drift`. Removing resources requires an intentional prune or
+`state forget`; see [the CLI reference](cli.md) for supported removal behavior.
+
+When deployment is authorized, apply the reviewed plan, then verify:
+
+```sh
+npm run uc -- apply .uc/plan.json
+npm run uc -- check
+```
+
+After any source change, compile and plan again. Never hand-edit a plan or local
+state to bypass validation. A plan with no changes needs no apply. An adoption-only
+plan can use `apply .uc/plan.json --adopt-only` to record ownership locally while
+refusing remote writes. `npm run build` builds the CLI itself; it is separate from
+configuration compilation.

package/docs/handoff.md

@@ -0,0 +1,24 @@
+# Local state that git does not hold
+
+Your remote's configuration and operating state are deliberately kept out of
+this repository. A fresh clone contains the tool only.
+
+| Path                   | Contents                                                     | Back up?                  |
+| ---------------------- | ------------------------------------------------------------ | ------------------------- |
+| `remote.config.ts`     | Your desired configuration                                   | Yes (private git repo)    |
+| `generated/devices.ts` | Entity/command bindings from `inventory --bindings`          | Optional (regenerable)    |
+| `.uc/targets/`         | Remote address, identity and firmware                        | Yes                       |
+| `.uc/credentials.json` | API key (mode 0600)                                          | No; re-run `auth` if lost |
+| `.uc/state/`           | Logical key → remote ID bindings and the last applied values | **Yes, critical**         |
+| `.uc/journals/`        | Apply journals used by `resume` and `rollback`               | Yes                       |
+| `.uc/*.json`           | Builds, plans, inventories                                   | No                        |
+
+If you lose `.uc/state`, the next plan becomes an adoption pass. Recreate it
+with `import`, review the result, and then `apply --adopt-only`. Never apply a
+plan that unexpectedly creates resources which already exist on the remote.
+
+When you move to a new machine, copy `.uc/` across (e.g. `rsync -a old/.uc/ new/.uc/`)
+rather than re-running `connect`/`auth`/`import`. A new session or new clone
+should reuse existing state, not start over.
+
+For the full first-run procedure see the README's "Setup (agent runbook)".

package/docs/snippets.md

@@ -0,0 +1,312 @@
+# Snippets: common tasks
+
+Copy-paste recipes for the things people most often ask for. Each one ends with
+the same validation loop:
+
+```sh
+npm run uc -- compile && npm run uc -- plan --out .uc/plan.json
+# review: only the intended resources may change
+npm run uc -- apply .uc/plan.json && npm run uc -- check
+```
+
+Ground rules (see [AGENTS.md](../AGENTS.md)):
+
+- Get every entity ID and `cmd_id` from `generated/devices.ts` or a fresh
+  inventory. Never guess command names.
+- A command used in an activity must belong to an entity in that activity's
+  `entity_ids`.
+- Arrays (`entity_ids`, sequences, page `items`) are replaced whole. Keep the
+  existing entries and their order.
+- Imported configs use native objects; new resources can use the helpers
+  (`activity()`, `bind()`, `page()`, ...). Both forms are valid together.
+
+## Finding things
+
+```sh
+# Which entities exist and what commands do they accept?
+grep -n 'name:' generated/devices.ts
+grep -n 'Apple TV' generated/devices.ts
+
+# Refresh bindings after adding devices/integrations (files are never overwritten)
+npm run uc -- inventory --bindings .uc/devices-$(date +%F).ts
+
+# Where is a resource defined?
+grep -n '"activity\.' remote.config.ts | grep -v '\.button\.\|\.page\.'   # activities
+grep -n 'activity.watch_tv.button' remote.config.ts                        # its buttons
+grep -n '<entity-id>' remote.config.ts                                     # every use of an entity
+
+# Raw API reads (redacted)
+npm run uc -- api GET /activities
+npm run uc -- api GET '/intg/instances/<integration_id>/entities?filter=ALL'
+```
+
+Physical button names: `BACK HOME VOICE VOLUME_UP VOLUME_DOWN MUTE DPAD_UP
+DPAD_DOWN DPAD_LEFT DPAD_RIGHT DPAD_MIDDLE CHANNEL_UP CHANNEL_DOWN PREV PLAY
+NEXT POWER RECORD MENU STOP`. Check `npm run uc -- api GET /cfg/device/button_layout` for the exact list.
+
+## Remap a physical button in an activity
+
+Imported form: change only `cmd_id` (and `entity_id` if needed).
+
+```ts
+"activity.watch_kaleidescape.button.next_short_press": {
+  kind: "activityButton",
+  parent: { $ref: "activity.watch_kaleidescape" },
+  id: "NEXT/short_press",
+  data: {
+    short_press: {
+      entity_id: "kaleidescape.main.media_player.XXXX",
+      cmd_id: "media_player.next",          // was media_player.fast_forward
+      params: {},
+    },
+  },
+},
+```
+
+New binding with the helper:
+
+```ts
+import { bind, command, ref } from "uc-config";
+
+"activity.watch_tv.button.menu": bind(
+  ref("activity.watch_tv"),
+  "MENU",
+  command(appleTv, "media_player.context_menu"),
+),
+```
+
+## Add a long-press action
+
+```ts
+"activity.watch_tv.button.home_long": bind(
+  ref("activity.watch_tv"),
+  "HOME",
+  command(appleTv, "APP_SWITCHER"),
+  "long_press",
+),
+```
+
+## Route volume to the receiver in every activity
+
+```ts
+const receiver = "onkyo_driver.main.media_player.XXXX";
+const volumeButtons = (activityKey: string) => ({
+  [`${activityKey}.button.vol_up`]: bind(ref(activityKey), "VOLUME_UP", command(receiver, "media_player.volume_up")),
+  [`${activityKey}.button.vol_down`]: bind(ref(activityKey), "VOLUME_DOWN", command(receiver, "media_player.volume_down")),
+  [`${activityKey}.button.mute`]: bind(ref(activityKey), "MUTE", command(receiver, "media_player.mute_toggle")),
+});
+
+resources: {
+  ...volumeButtons("activity.watch_tv"),
+  ...volumeButtons("activity.play_ps5"),
+}
+```
+
+If an activity already has imported `VOLUME_UP/short_press` resources, edit
+those instead. Two resources with the same parent and `id` conflict.
+
+## Add an entity to an activity
+
+Append to `entity_ids` and keep the existing order. Required before any of its
+commands can be used in that activity.
+
+```ts
+options: {
+  entity_ids: [
+    "lgwebos_driver.main.media_player.XXXX",
+    "onkyo_driver.main.media_player.XXXX",
+    "kaleidescape.main.remote.XXXX",        // added
+  ],
+},
+```
+
+## Change an activity's power-on / power-off sequence
+
+```ts
+sequences: {
+  on: [
+    { type: "command", command: { entity_id: tv, cmd_id: "media_player.on", params: {} } },
+    { type: "delay", delay: 2000 },
+    { type: "command", command: { entity_id: receiver, cmd_id: "media_player.select_source", params: { source: "BD/DVD" } } },
+  ],
+  off: [
+    { type: "command", command: { entity_id: receiver, cmd_id: "media_player.off", params: {} } },
+    { type: "command", command: { entity_id: tv, cmd_id: "media_player.off", params: {} } },
+  ],
+},
+```
+
+`select_source` values are entity-specific. Copy them from an existing sequence
+or the entity's `attributes.source_list` (`npm run uc -- api GET /entities/<id>`).
+
+## Create a new activity
+
+```ts
+import { activity, command, delay, ref, bind, page, button } from "uc-config";
+
+"activity.movie_night": activity({
+  name: "Movie Night",
+  entities: [tv, receiver, player, lights],
+  on: [
+    command(lights, "light.off"),
+    command(tv, "media_player.on"),
+    delay(1500),
+    command(receiver, "media_player.on"),
+  ],
+  off: [command(receiver, "media_player.off"), command(tv, "media_player.off")],
+}),
+"activity.movie_night.button.play": bind(ref("activity.movie_night"), "PLAY", command(player, "media_player.play_pause")),
+```
+
+New activities apply in two phases: the first apply creates the activity and
+its entity membership, then **plan again** to apply buttons/pages (`deferred`
+in the plan output tells you this).
+
+## Add a touchscreen page with buttons
+
+```ts
+"activity.watch_tv.page.apps": page(ref("activity.watch_tv"), {
+  name: "Apps",
+  grid: { width: 4, height: 6 },
+  items: [
+    button({ label: "Netflix", at: [0, 0], size: [2, 1], command: command(tv, "NETFLIX") }),
+    button({ label: "Prime",   at: [2, 0], size: [2, 1], command: command(tv, "AMAZON") }),
+    button({ label: "Fix Inputs", at: [1, 2], size: [2, 2], command: command(fixMacro, "macro.run") }),
+  ],
+}),
+```
+
+Items must fit within the grid and must not overlap. For an existing imported
+page, edit its `items` array in place.
+
+## Create a macro ("fix inputs" style)
+
+```ts
+import { macro, command, delay } from "uc-config";
+
+"macro.fix_inputs": macro({
+  name: "Fix Inputs",
+  entities: [tv, receiver],
+  steps: [
+    command(tv, "media_player.select_source", { source: "HDMI 2" }),
+    delay(500),
+    command(receiver, "media_player.select_source", { source: "BD/DVD" }),
+  ],
+}),
+```
+
+Run it from a button or page with `command("<macro entity id>", "macro.run")`.
+For an existing macro the entity ID is its `id` in `remote.config.ts`. For a
+new one, apply first, then read it from `npm run uc -- api GET /macros`.
+
+## Touch slider target
+
+```ts
+options: {
+  touch_slider: { enabled: true, target: { entity_id: "lutron_driver.main.light.XXXX" } },
+},
+```
+
+## Rename an activity / page
+
+Change the display name only; keep the resource key and `id`:
+
+```ts
+data: { name: { en_US: "Watch Movies" } },   // was "Watch Kaleidescape"
+```
+
+To rename the _logical key_ too, edit the key and every `ref()`/`$ref` to it,
+then run `npm run uc -- state move OLD_KEY NEW_KEY`.
+
+## Device settings
+
+```ts
+import { settings } from "uc-config";
+
+"settings.display": settings("display", { brightness: 60, auto_brightness: true }),
+"settings.haptic": settings("haptic", { enabled: true }),
+```
+
+Only declared fields are owned. Sections: `device display button haptic
+localization power_saving sound bt profile voice_control`.
+
+## Repair after an integration update (orphaned entities)
+
+```sh
+npm run uc -- diagnose
+```
+
+**Entity dropped but still offered** (diagnose prints `fix: Re-add ...`):
+
+```sh
+npm run uc -- api POST '/intg/instances/<integration_id>/entities/<local_id>' --data '{}' --write
+npm run uc -- diagnose          # expect All clear
+npm run uc -- plan              # expect 0 operations
+```
+
+**Entity re-keyed** (diagnose lists a `candidate`):
+
+```sh
+npm run uc -- api POST '/intg/instances/<integration_id>/entities/<candidate_local_id>' --data '{}' --write
+grep -n '<old-entity-id>' remote.config.ts      # entity_ids, sequences, buttons, pages, macros
+# replace every occurrence with the new ID, then:
+npm run uc -- compile && npm run uc -- plan --out .uc/plan.json && npm run uc -- apply .uc/plan.json
+npm run uc -- diagnose
+```
+
+If the plan reports `Cannot verify command` for the swapped entity, the
+activity's live `included_entities` still lists the old one. Apply the
+`entity_ids` change first, then replan for the buttons and sequences.
+
+**Drift from a driver renaming something** (`Drift at data.name`): copy the
+live value (shown in the plan) into source, then:
+
+```sh
+npm run uc -- state forget <key> && npm run uc -- state adopt <key> <native-id>
+npm run uc -- compile && npm run uc -- plan --out .uc/plan.json
+npm run uc -- apply .uc/plan.json --adopt-only
+```
+
+## Pull changes made in the web configurator
+
+```sh
+npm run uc -- import --out .uc/imported-$(date +%F).config.ts
+npm run uc -- compile --config .uc/imported-$(date +%F).config.ts --out .uc/imported-build.json
+diff <(jq -S . .uc/build.json) <(jq -S . .uc/imported-build.json) | less
+```
+
+Imported keys are generic (`activity3`). Match resources by `kind` + `id` and
+copy the changed fields into `remote.config.ts`. Then `plan` should report
+0 operations.
+
+## Undo the last apply
+
+```sh
+npm run uc -- rollback --out .uc/rollback.json   # builds a compensating plan
+# review it like any plan, then:
+npm run uc -- apply .uc/rollback.json
+```
+
+## Back up everything (scheduled job friendly)
+
+```sh
+D=backups/$(date +%F); mkdir -p "$D"
+npm run -s uc -- inventory --out "$D/inventory.json"           # redacted raw state
+npm run -s uc -- import --out "$D/remote.config.ts"            # readable snapshot
+tar czf "$D/dotuc.tgz" --exclude credentials.json .uc          # ownership state
+curl -sf http://<REMOTE_IP>:9999/api/backups/download -o "$D/intg-manager.json"  # Integration Manager
+```
+
+`npm run uc -- backup --out PRIVATE_PATH` produces the remote's native full
+backup, but it **temporarily stops integrations and docks**, so don't schedule it.
+
+## Nightly health check (for an agent cron job)
+
+```sh
+npm run -s uc -- diagnose --json > .uc/diagnose.json; d=$?
+npm run -s uc -- plan --out .uc/plan-nightly.json; p=$?
+echo "diagnose=$d plan=$p"     # 0/0 = healthy; 2 = needs attention
+```
+
+Report findings, and fix only the clear-cut cases (re-add a dropped entity that
+is still offered). Escalate everything else to the user.