uc-config 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,35 @@
+# Changelog
+
+Each release says whether upgrading needs any **action**. To upgrade a config
+workspace:
+
+```sh
+npm install uc-config@latest
+npx uc-config init --refresh-docs
+npx uc-config compile && npx uc-config plan   # must show 0 operations
+```
+
+## 0.2.1
+
+Action required: run `npx uc-config init --refresh-docs`. It updates the
+scaffolded AGENTS.md, whose upgrade instructions were wrong.
+
+- `init --refresh-docs` updates AGENTS.md and CLAUDE.md to the installed
+  version. Files you edited are kept, and the new version is written beside
+  them as `.new`.
+- `doctor` prints a notice when a newer version is published. Set
+  `UC_NO_UPDATE_CHECK=1` to disable it.
+- The scaffolded upgrade instructions use `npm install uc-config@latest`.
+  `npm update` doesn't move between 0.x minor versions.
+
+## 0.2.0
+
+Action required: none.
+
+- `init` asks for the remote's IP and the web configurator PIN, then connects
+  and authenticates. It can be rerun safely.
+- `init` writes CLAUDE.md, which points Claude Code at AGENTS.md.
+
+## 0.1.0
+
+First release.

package/README.md

@@ -16,24 +16,88 @@ hardware. Humans can use it directly too.
 > for copy-paste recipes. Ask the user only for what you cannot discover:
 > the remote's IP address and the web configurator PIN.
 
-## Quick start
+## Quick start (for humans)
 
-Before you start: install Node.js 22+, and on the remote enable the web
-configurator (Settings → Profile → Web configurator). Note the remote's IP and PIN.
+### 1. Before you start
+
+- Install [Node.js](https://nodejs.org/) 22 or newer.
+- On the remote, enable the web configurator: **Settings → Profile → Web
+  configurator**. Note the **PIN** it shows.
+- Find the remote's **IP address**. It's shown in the remote's network
+  settings, or in your router's device list. The computer you use must be on the same network as the remote.
+
+### 2. Create your config folder
 
 ```sh
 mkdir my-remote && cd my-remote
-npx uc-config init        # package.json, tsconfig, .gitignore, AGENTS.md
+npx uc-config init
 npm install
 ```
 
-Then start your coding agent in that folder and prompt:
+`init` creates the project files, then asks for the remote's IP address and
+the web configurator PIN. The PIN is typed hidden in your terminal and is only
+used once, to create an API key saved in `.uc/credentials.json`. Press Enter at
+either prompt to skip it; you can rerun `npx uc-config init` at any time and it
+picks up where it left off without overwriting anything.
+
+If `init` says a key named `uc-config` already exists, revoke that key in the
+web configurator and run `npx uc-config init` again.
+
+This folder holds your remote's configuration. It's yours, not part of this
+repo.
+
+### 3. Let your coding agent set it up
+
+Start your coding agent (Claude Code, Codex, Cursor, etc.) in that folder and
+prompt:
 
 > Set up my Remote 3 at `<IP>`
 
-When the agent asks you to authenticate, run `npx uc-config auth` in your own
-terminal and enter the PIN. Don't paste the PIN into chat. That folder is your
-configuration; commit it to a **private** git repo.
+The agent imports your current setup into `remote.config.ts` and records which
+resources it manages. This writes nothing to the remote.
+
+If you skipped the PIN during `init`, the agent will ask you to run
+`npx uc-config auth` in your own terminal. **Don't paste the PIN into the
+chat.**
+
+`init` also writes `CLAUDE.md`, which points Claude Code at `AGENTS.md`;
+Claude Code reads `CLAUDE.md` rather than `AGENTS.md`.
+
+### 4. Save your config
+
+Commit the folder to a **private** git repo. It contains your device IDs and
+IP addresses. `.uc/` (credentials and state) is already gitignored; back it up
+separately.
+
+### Day to day
+
+Ask your agent for changes in plain language, for example:
+
+> Make the NEXT button skip chapters in the movie activity
+
+> Add a page to Watch TV with buttons for Netflix and YouTube
+
+> Something on the remote says "orphaned entity". Fix it.
+
+The agent shows a plan of what will change before applying it. After you update
+an integration in the Integration Manager, ask the agent to run diagnostics.
+
+## Updating
+
+Ask your agent to "update uc-config", or run in your config folder:
+
+```sh
+npm install uc-config@latest
+npx uc-config init --refresh-docs     # refresh AGENTS.md / CLAUDE.md
+npx uc-config compile && npx uc-config plan    # must show 0 operations
+```
+
+Use `npm install uc-config@latest` rather than `npm update`: before 1.0,
+`npm update` doesn't move between minor versions (0.2 → 0.3). `--refresh-docs`
+keeps files you've edited and writes the new version beside them as `.new`.
+`doctor` tells you when a newer version is available. See
+[CHANGELOG.md](CHANGELOG.md) for what changed and whether a release needs any
+action.
 
 ## Requirements
 
@@ -57,6 +121,9 @@ npm install
 npm run build
 npm test                                   # offline, uses a mock Core API
 
+# Steps 2-3 are usually already done by `npx uc-config init`. Skip them if
+# .uc/targets/*.json and .uc/credentials.json exist.
+
 # 2. Register the remote under a target name ("home" here). With a single
 #    target, later commands pick it automatically; otherwise pass --target.
 npm run uc -- connect home --host http://<REMOTE_IP>

package/dist/cli.js

@@ -4,7 +4,7 @@ import { writeFile, mkdir } from "node:fs/promises";
 import { resolve, join } from "node:path";
 import { createInterface } from "node:readline/promises";
 import { Writable } from "node:stream";
-import { CoreClient, resolveSecrets } from "./client.js";
+import { ApiError, CoreClient, resolveSecrets } from "./client.js";
 import { Adapter } from "./adapter.js";
 import { compile, validateConfig } from "./compiler.js";
 import { Engine, PendingSetup } from "./engine.js";
@@ -123,7 +123,18 @@ program
     .requiredOption("--host <url>")
     .option("--token-env <name>", "API key environment variable", "UC_API_KEY")
     .action(async (name, o) => {
-    const client = new CoreClient(o.host);
+    await connectTarget(name, o.host, o.tokenEnv);
+});
+program
+    .command("auth")
+    .option("--target <name>", "target", defaultTarget)
+    .action(async (o) => {
+    await load(o.target); // fail on a missing target before prompting
+    const pin = process.env.UC_PIN ?? (await hiddenPrompt("Web configurator PIN: "));
+    await authenticate(o.target, pin);
+});
+async function connectTarget(name, host, tokenEnv = "UC_API_KEY") {
+    const client = new CoreClient(host);
     const version = await client.version();
     if (version.model !== "UCR3" || typeof version.address !== "string")
         throw new Error("Expected an identifiable Remote 3");
@@ -131,7 +142,7 @@ program
         host: client.base.origin,
         identity: version.address,
         version,
-        tokenEnv: o.tokenEnv,
+        tokenEnv,
     };
     try {
         const old = await readJson(targetFile(name));
@@ -144,35 +155,79 @@ program
     }
     await saveJson(targetFile(name), target);
     console.log(`Connected ${name}: ${version.model}, core ${version.core}, API ${version.api}. No configuration changed.`);
-});
-program
-    .command("auth")
-    .option("--target <name>", "target", defaultTarget)
-    .action(async (o) => {
-    const { target } = await load(o.target);
-    const pin = process.env.UC_PIN ?? (await hiddenPrompt("Web configurator PIN: "));
-    const client = new CoreClient(target.host);
-    validateRequest("/auth/api_keys", "POST", {
-        name: "uc-config",
-        scopes: ["admin"],
-    });
-    const { data } = await client.request("POST", "/auth/api_keys", { name: "uc-config", scopes: ["admin"] }, {
-        Authorization: `Basic ${Buffer.from(`web-configurator:${pin}`).toString("base64")}`,
-    });
-    if (typeof data.api_key !== "string")
-        throw new Error("No API key returned");
-    let credentials = {};
+    return target;
+}
+async function hasCredentials(target) {
+    if (process.env[target.tokenEnv])
+        return true;
     try {
-        credentials = await readJson(local("credentials.json"));
+        const c = await readJson(local("credentials.json"));
+        return typeof c[target.identity] === "string";
     }
-    catch (e) {
-        if (e.code !== "ENOENT")
-            throw e;
+    catch {
+        return false;
     }
-    credentials[target.identity] = data.api_key;
-    await saveJson(local("credentials.json"), credentials);
-    console.log("API key saved in .uc/credentials.json (mode 0600, gitignored). Approve it on the remote if requested, then run doctor.");
-});
+}
+async function authenticate(name, pin) {
+    {
+        const { target } = await load(name);
+        const client = new CoreClient(target.host);
+        validateRequest("/auth/api_keys", "POST", {
+            name: "uc-config",
+            scopes: ["admin"],
+        });
+        const { data } = await client.request("POST", "/auth/api_keys", { name: "uc-config", scopes: ["admin"] }, {
+            Authorization: `Basic ${Buffer.from(`web-configurator:${pin}`).toString("base64")}`,
+        });
+        if (typeof data.api_key !== "string")
+            throw new Error("No API key returned");
+        let credentials = {};
+        try {
+            credentials = await readJson(local("credentials.json"));
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        credentials[target.identity] = data.api_key;
+        await saveJson(local("credentials.json"), credentials);
+        console.log("API key saved in .uc/credentials.json (mode 0600, gitignored). Approve it on the remote if requested, then run doctor.");
+    }
+}
+/** Latest published version, or undefined if offline/disabled. Never throws. */
+async function latestVersion() {
+    if (process.env.UC_NO_UPDATE_CHECK)
+        return undefined;
+    try {
+        const res = await fetch("https://registry.npmjs.org/uc-config/latest", {
+            signal: AbortSignal.timeout(3000),
+        });
+        if (!res.ok)
+            return undefined;
+        const v = (await res.json()).version;
+        return typeof v === "string" ? v : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function newer(a, b) {
+    const p = (v) => v.split("-")[0].split(".").map(Number);
+    const [x, y] = [p(a), p(b)];
+    for (let i = 0; i < 3; i++)
+        if ((x[i] ?? 0) !== (y[i] ?? 0))
+            return (x[i] ?? 0) > (y[i] ?? 0);
+    return false;
+}
+async function question(label) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+        return (await rl.question(label)).trim();
+    }
+    finally {
+        rl.close();
+    }
+}
 program
     .command("doctor")
     .option("--target <name>", "target", defaultTarget)
@@ -180,6 +235,9 @@ program
     const { client, target } = await load(o.target);
     await client.verifyTarget(target);
     console.log(`Identity verified; core ${target.version.core}, reported API ${target.version.api}`);
+    const latest = await latestVersion();
+    if (latest && newer(latest, pkgVersion))
+        console.log(`Update available: uc-config ${pkgVersion} -> ${latest}. Run: npm install uc-config@latest && npx uc-config init --refresh-docs (see CHANGELOG.md)`);
     for (const path of [
         "/entities",
         "/activities",
@@ -506,15 +564,90 @@ ir.command("capture <emitterId>")
 program
     .command("init")
     .description("Scaffold a private config workspace (package.json, tsconfig, .gitignore, AGENTS.md)")
-    .action(async () => {
-    const r = await init(root(), pkgVersion);
+    .option("--host <ip>", "remote IP address (skips the prompt)")
+    .option("--target <name>", "target name", "home")
+    .option("--no-connect", "only create files; don't connect or authenticate")
+    .option("--refresh-docs", "update AGENTS.md/CLAUDE.md to this version (edited files get a .new copy)")
+    .action(async (o) => {
+    const r = await init(root(), pkgVersion, { refreshDocs: o.refreshDocs });
     for (const f of r.written)
         console.log(`created ${f}`);
     if (r.packageJsonUpdated)
         console.log("added uc-config to package.json");
+    for (const f of r.refreshed)
+        console.log(`updated ${f} to v${pkgVersion}`);
+    for (const f of r.conflicts)
+        console.log(`kept ${f} (edited); wrote ${f}.new. Merge your changes, then delete ${f}.new`);
     for (const f of r.skipped)
         console.log(`kept existing ${f}`);
-    console.log("Next: npm install, then start your coding agent here and ask it to set up your Remote 3.");
+    if (o.refreshDocs) {
+        if (r.conflicts.length)
+            process.exitCode = 2;
+        return;
+    }
+    const interactive = Boolean(process.stdin.isTTY);
+    const next = "Next: npm install, then start your coding agent here and ask it to set up your Remote 3.";
+    if (!o.connect)
+        return console.log(next);
+    const name = o.target;
+    // 1. Connect (unless already connected).
+    let target;
+    try {
+        target = await readJson(targetFile(name));
+        console.log(`Already connected to ${target.host} as "${name}".`);
+    }
+    catch (e) {
+        if (e.code !== "ENOENT")
+            throw e;
+    }
+    if (!target) {
+        const host = o.host ??
+            (interactive
+                ? await question("Remote 3 IP address (blank to skip): ")
+                : "");
+        if (!host) {
+            console.log(`Skipped connecting. Later: npx uc-config connect ${name} --host http://<IP>\n${next}`);
+            return;
+        }
+        try {
+            target = await connectTarget(name, host);
+        }
+        catch (e) {
+            console.log(`Could not reach a Remote 3 at ${host}: ${e.message}\n` +
+                "Check the IP, that this computer is on the same network, and that the remote is awake (pick it up).\n" +
+                `Retry: npx uc-config init --host <IP>  (files already created are kept)`);
+            process.exitCode = 1;
+            return;
+        }
+    }
+    // 2. Authenticate (unless a key is already available).
+    if (await hasCredentials(target)) {
+        console.log("Already authenticated.");
+        return console.log(next);
+    }
+    const pin = process.env.UC_PIN ??
+        (interactive
+            ? await hiddenPrompt("Web configurator PIN (Settings → Profile → Web configurator; blank to skip): ")
+            : "");
+    if (!pin) {
+        console.log("Skipped authentication. Run `npx uc-config auth` in this folder when ready.\n" +
+            next);
+        return;
+    }
+    try {
+        await authenticate(name, pin);
+    }
+    catch (e) {
+        const status = e instanceof ApiError ? e.status : 0;
+        console.log(status === 401 || status === 403
+            ? "The remote rejected the PIN. Check that the web configurator is enabled and the PIN is current, then run `npx uc-config auth`."
+            : status === 400 || status === 409 || status === 422
+                ? 'An API key named "uc-config" already exists on the remote. Revoke it in the web configurator, then run `npx uc-config auth`.'
+                : `Authentication failed: ${e.message}. Retry with \`npx uc-config auth\`.`);
+        process.exitCode = 1;
+        return;
+    }
+    console.log(next);
 });
 program
     .command("diagnose")

package/dist/init.d.ts

@@ -1,7 +1,15 @@
+/** True when the file is unedited generated output from any uc-config version. */
+export declare function isPristine(content: string): boolean;
 export interface InitResult {
     written: string[];
     skipped: string[];
     packageJsonUpdated: boolean;
+    /** Generated docs replaced by --refresh-docs. */
+    refreshed: string[];
+    /** Edited docs kept; the new version was written to `<name>.new`. */
+    conflicts: string[];
 }
 /** Scaffold a private config workspace. Never overwrites existing files. */
-export declare function init(dir: string, version: string): Promise<InitResult>;
+export declare function init(dir: string, version: string, options?: {
+    refreshDocs?: boolean;
+}): Promise<InitResult>;

package/dist/init.js

@@ -1,5 +1,23 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises";
 import { join } from "node:path";
+import { createHash } from "node:crypto";
+const sha256 = (s) => createHash("sha256").update(s).digest("hex");
+const MARKER = /^<!-- uc-config:generated v(\S+) sha256:([0-9a-f]{64}) -->\n/;
+/** Prefix generated docs with a marker so --refresh-docs can detect edits. */
+const stamp = (version, body) => `<!-- uc-config:generated v${version} sha256:${sha256(body)} -->\n${body}`;
+/** Exact output of releases that predate the marker (0.1.0, 0.2.0). */
+const LEGACY = new Set([
+    "053dd83c530adb91f58ad52148c9d858cc28864a137b7b5e65c4563338e91b4f",
+    "159e847a6a5b6c5cb9ed96f400e8f5d58cd9acae2e68bf666fc3fae2e4ad249b",
+    "d71e02c349b769c916d166a6b26cc14d80da4142042fa90564bda85c897a9b07",
+]);
+/** True when the file is unedited generated output from any uc-config version. */
+export function isPristine(content) {
+    const m = MARKER.exec(content);
+    if (m)
+        return sha256(content.slice(m[0].length)) === m[2];
+    return LEGACY.has(sha256(content));
+}
 const agents = (version) => `# Remote 3 configuration (uc-config)
 
 This folder holds the user's Unfolded Circle Remote 3 configuration. It is
@@ -10,11 +28,17 @@ managed with the \`uc-config\` CLI (v${version}). Reference docs ship with the p
 - node_modules/uc-config/docs/cli.md: every command, recovery
 - node_modules/uc-config/docs/configuration-authoring.md: config syntax and ownership
 
-## First run (no .uc/targets/ yet)
+## First run
+
+\`npx uc-config init\` usually already connected and authenticated. Check what
+exists, and skip steps that are done:
 
-1. \`npx uc-config connect home --host http://<IP>\`. Ask the user for the IP if not given.
-2. Ask the user to run \`npx uc-config auth\` in their own terminal (the web
-   configurator must be enabled on the remote). Never ask for the PIN in chat.
+1. No \`.uc/targets/*.json\`: run \`npx uc-config connect home --host http://<IP>\`.
+   Ask the user for the IP if not given.
+2. No \`.uc/credentials.json\` (and no \`UC_API_KEY\` env): ask the user to run
+   \`npx uc-config auth\` in their own terminal (the web configurator must be
+   enabled on the remote). Never ask for the PIN in chat, and never run \`auth\`
+   yourself; it needs a real terminal.
 3. \`npx uc-config doctor\`
 4. \`npx uc-config inventory --bindings generated/devices.ts\`
 5. \`npx uc-config import --out remote.config.ts\`
@@ -49,8 +73,22 @@ the UC Integration Manager (http://<remote>:9999); run diagnose after any update
 
 ## Upgrading the tool
 
-\`npm update uc-config\`, then compile and plan. The plan must show 0 operations
-before you make any other change.
+1. \`npm install uc-config@latest\` (not \`npm update\`: it won't cross 0.x minor versions).
+2. \`npx uc-config init --refresh-docs\` to update this file and CLAUDE.md.
+   Files the user edited are kept; the new version is written beside them as \`.new\`.
+3. Read node_modules/uc-config/CHANGELOG.md for any "Action required" notes.
+4. \`npx uc-config compile && npx uc-config plan\`. It must show 0 operations
+   before you make any other change. If not, the upgrade changed how the config
+   is read: show the user the plan and don't apply it.
+`;
+// Claude Code reads CLAUDE.md, not AGENTS.md. Newer releases follow the
+// @-import; the prose line covers releases that don't support imports.
+const claude = `# Remote 3 configuration (uc-config)
+
+Read AGENTS.md in this folder before doing anything. It is the authoritative
+guide for working here: setup steps, editing rules and safety limits.
+
+@AGENTS.md
 `;
 const tsconfig = {
     compilerOptions: {
@@ -70,12 +108,36 @@ const gitignore = `node_modules/
 .env.*
 `;
 /** Scaffold a private config workspace. Never overwrites existing files. */
-export async function init(dir, version) {
+export async function init(dir, version, options = {}) {
     await mkdir(dir, { recursive: true });
     const result = {
         written: [],
         skipped: [],
         packageJsonUpdated: false,
+        refreshed: [],
+        conflicts: [],
+    };
+    const doc = async (name, contents) => {
+        let existing;
+        try {
+            existing = await readFile(join(dir, name), "utf8");
+        }
+        catch (e) {
+            if (e.code !== "ENOENT")
+                throw e;
+        }
+        if (existing === undefined)
+            return put(name, contents);
+        if (!options.refreshDocs || existing === contents)
+            return void result.skipped.push(name);
+        if (isPristine(existing)) {
+            await writeFile(join(dir, name), contents);
+            result.refreshed.push(name);
+        }
+        else {
+            await writeFile(join(dir, `${name}.new`), contents);
+            result.conflicts.push(name);
+        }
     };
     const put = async (name, contents) => {
         try {
@@ -119,6 +181,7 @@ export async function init(dir, version) {
     }
     await put("tsconfig.json", JSON.stringify(tsconfig, null, 2) + "\n");
     await put(".gitignore", gitignore);
-    await put("AGENTS.md", agents(version));
+    await doc("AGENTS.md", stamp(version, agents(version)));
+    await doc("CLAUDE.md", stamp(version, claude));
     return result;
 }

package/docs/cli.md

@@ -9,33 +9,38 @@ 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.                       |
+| Command                                        | Writes to remote  | Purpose                                                                        |
+| ---------------------------------------------- | ----------------- | ------------------------------------------------------------------------------ |
+| `init [--host ip] [--no-connect]`              | API key only      | Scaffold a workspace, then prompt for IP and PIN (connect + auth). Rerunnable. |
+| `init --refresh-docs`                          | no                | Update AGENTS.md/CLAUDE.md; edited files are kept and get a `.new` copy.       |
+| `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
 
+`init` runs `connect` and `auth` for you when started in a terminal. Without a
+terminal (e.g. run by an agent) it only scaffolds files unless `--host` and
+`UC_PIN` are supplied. Steps already completed are skipped on reruns.
+
 `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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "uc-config",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "type": "module",
   "description": "Configuration-as-code for the Unfolded Circle Remote 3, designed to be driven by coding agents",
   "license": "MIT",
@@ -36,6 +36,7 @@
     "examples",
     "remote.config.example.ts",
     "README.md",
+    "CHANGELOG.md",
     "LICENSE"
   ],
   "engines": {