@tikoci/centrs 0.1.9-next.23 → 0.1.9-next.24

package/docs/errors/cmr/caller-policy-not-enforced.md

@@ -22,9 +22,11 @@ re-proves it (CMR15 in `commands/execute/examples.md`):
 | `read,test,api,rest-api` | `not enough permissions (9)` | `run-script` wrote to the controller's own row; `/cmr/device/reboot` rebooted a client |
 
 MikroTik [says](https://forum.mikrotik.com/t/7-26beta-development-is-released/273582/139) this is fixed for 7.26beta2: a `read` group will not
-be allowed to do it. That has not been checked on a beta2 build yet. centrs
-still warns on any version, because the warning reads the login's policy, not
-the RouterOS version. On a build that refuses the write, the members fail
+be allowed to do it. #527 now carries direct 7.26beta3 evidence that a
+restricted caller is refused, with the first refusing release still
+unbracketed. centrs still warns on any version, because the warning reads
+the login's policy, not the RouterOS version. On a build that refuses the
+write, the members fail
 instead and the warning only says what the login lacks.
 
 `context` names the login (`username`, `group`), the policies it lacks

package/docs/errors/routeros/permission-denied.md

@@ -0,0 +1,24 @@
+# `routeros/permission-denied`
+
+RouterOS refused the command because the user's group lacks a policy it needs.
+The router answered, and a retry gives the same result. A single refused
+command did not run. A multi-statement script run through `/execute` can be
+partly applied: statements before the refused one already ran.
+
+## Typical RouterOS strings
+
+- `not enough permissions (9)`: the command needs a policy the group does not
+  have, for example a `set` without `write`.
+- `std failure: not allowed (9)`: on REST before RouterOS 7.26beta3, every
+  request fails this way (a plain GET included) when the group has `rest-api`
+  but not `api`. 7.26beta3 fixed it.
+
+Over REST both arrive as HTTP 500 with the string in `detail`; over the native
+API as a `!trap`. Grounded on CHR 7.23.8, 7.25, 7.26beta1 and 7.26beta3.
+
+## Fix
+
+Grant the missing policy to the user's group in `/user/group`: `read` for
+reads, `write` for changes. Before 7.26beta3 a REST user needs both `api` and
+`rest-api`. Avoid the built-in `read` group for a least-privilege user: it also
+carries `reboot`, `sensitive`, `password` and others.

package/docs/errors/transport/edge-auth-failed.md

@@ -0,0 +1,22 @@
+# `transport/edge-auth-failed`
+
+An HTTP layer in front of RouterOS (auth proxy, tunnel edge, WAF) refused the
+request before RouterOS answered it.
+
+## How centrs tells
+
+RouterOS answers every REST auth refusal with a JSON body whose `error` equals
+the HTTP status (`{"error":401,"message":"Unauthorized"}`), adding
+`WWW-Authenticate: Basic` only when no credentials were sent. A 401 or 403 with
+any other body, or a challenge for another scheme (Cloudflare Access sends
+`Bearer`), came from something in front of the router. `context` records the
+challenge scheme, `server`, content type and whether a `cf-ray` header was
+present. A `cf-ray` header alone does not decide it: a tunnel passes RouterOS's
+own 401 through with one.
+
+## Fix
+
+centrs sends only RouterOS Basic credentials, so changing the RouterOS username
+or password will not help. Point `--host` at an address that reaches RouterOS
+directly, or at a local proxy that authenticates to the front layer for you.
+The request never reached RouterOS, so a write was not applied.

package/docs/errors/transport/write-outcome-unknown.md

@@ -9,6 +9,9 @@ whether the write happened.
 
 - A connection closed or reset after an `execute` or `api` write was sent.
 - A REST 5xx or a timeout on a write.
+- A multi-statement `execute` or `api /execute` script refused with
+  `routeros/permission-denied`: statements before the refused one may already
+  have run (#549). A single refused statement did not run and warns nothing.
 
 centrs never retries a write that it has sent, in single-target or fan-out
 mode, because replaying an `add`, a script run or a counter change would apply

package/docs/errors/usage/invalid-cursor.md

@@ -0,0 +1,20 @@
+# `usage/invalid-cursor`
+
+An explain --cursor is not a byte offset inside the input being analyzed.
+
+## Typical trigger
+
+`centrs explain <router> '<input>' --complete --cursor <byte>` with a value that
+is not a whole number, or that is larger than the input's UTF-8 byte length.
+Library callers get the same code for an original-document position
+(`{ line, character }`) that addresses no character in the input.
+
+The check runs before any connection is made, so nothing is sent to the router.
+
+## Fix
+
+- Count the cursor in **UTF-8 bytes**, not characters: `é` is two bytes and
+  `🛰` is four. The end of the input (the default) is the input's byte length.
+- A cursor inside a multi-byte character is accepted and moves back to that
+  character's first byte.
+- Omit `--cursor` to complete or describe at the end of the input.

package/docs/errors/validation/unknown-path.md

@@ -19,3 +19,12 @@ Two sources raise it:
 
 Check the spelling of the segment in `error.context.segment`. `centrs explain
 '<command>'` shows how the rest of the command reads offline.
+
+One path is not a typo: `/system/routerboard` exists only on MikroTik
+hardware, so `retrieve` answers its absence on CHR and x86 systems with a
+targeted remediation instead of the generic one. For the device's license
+ID, read `/system/license` (`system-id` on CHR, `software-id` on x86):
+
+```bash
+centrs retrieve <router> /system/license
+```

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.9-next.23",
+	"version": "0.1.9-next.24",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {
@@ -40,7 +40,7 @@
 	"bin": {
 		"centrs": "src/cli.ts"
 	},
-	"description": "All-in-one TypeScript library/CLI/TUI/MCP for interacting with MikroTik RouterOS devices",
+	"description": "All-in-one TypeScript library/CLI/MCP for interacting with MikroTik RouterOS devices (TUI stub)",
 	"engines": {
 		"bun": ">=1.3.11 <2"
 	},

package/src/api.ts

@@ -62,6 +62,7 @@ import {
 	promptForWriteConfirmation,
 	validateRouterOsScript,
 } from "./execute.ts";
+import { countExecutableStatements } from "./explain/segment.ts";
 import {
 	assertOfflineSyntax,
 	isOfflineGateRejection,
@@ -541,7 +542,7 @@ async function* streamResolvedApi(
 			trace.validation = validation;
 			resolved = await withQueryBooleans(resolved, backend, result.queryMenu);
 		} else {
-			validation = disabledValidationMeta();
+			validation = disabledApiValidationMeta(resolved);
 		}
 	} catch (error) {
 		await backend.close();
@@ -824,16 +825,6 @@ function adapterForResolved(resolved: ResolvedApiRequest): ProtocolAdapter {
 	});
 }
 
-function disabledValidationMeta(): EnvelopeValidationMeta {
-	return {
-		enabled: false,
-		source: "disabled",
-		result: "skipped",
-		syntax: false,
-		semantic: false,
-	};
-}
-
 export async function resolveApiRequest(
 	request: ApiRequest,
 	env: Record<string, string | undefined>,
@@ -1347,7 +1338,8 @@ interface ApiValidationResult {
  * validator is `/console/inspect`, never `:put [:parse]`. Path existence and
  * add/set attribute validity both come from `request=child` — command-level
  * `request=completion` is unsafe on RouterOS 7.12.2 (`core/inspect.ts`). A
- * `/execute` script is a CLI string → `semantic: not-applicable`.
+ * `/execute` script is a CLI string, so it has no `semantic` summary; a
+ * structured request runs no `:parse`, so it has no `syntax` summary (#535).
  */
 async function validateApiRequest(
 	resolved: ResolvedApiRequest,
@@ -1383,8 +1375,7 @@ async function validateApiRequest(
 						? "not-applicable"
 						: API_SCRIPT_DEVICE_STAGE_SOURCE,
 				result: "passed",
-				syntax: script !== undefined,
-				semantic: "not-applicable",
+				...(script !== undefined ? { syntax: true } : {}),
 				stages: [
 					{
 						stage: "offline",
@@ -1468,13 +1459,7 @@ async function validateApiRequest(
 			}
 		}
 		return {
-			validation: {
-				enabled: true,
-				source: "/console/inspect request=child",
-				result: "passed",
-				syntax: false,
-				semantic: true,
-			},
+			validation: structuredValidationPassed(resolved),
 			tips,
 			queryMenu: isCommand ? `/${parent.join("/")}` : resolved.path,
 		};
@@ -1513,11 +1498,7 @@ async function validateApiRequest(
 		}
 		return {
 			validation: {
-				enabled: true,
-				source: "/console/inspect request=child",
-				result: "passed",
-				syntax: false,
-				semantic: true,
+				...structuredValidationPassed(resolved),
 				availableAttributes: available,
 			},
 			tips,
@@ -1526,13 +1507,7 @@ async function validateApiRequest(
 	}
 
 	return {
-		validation: {
-			enabled: true,
-			source: "/console/inspect request=child",
-			result: "passed",
-			syntax: false,
-			semantic: true,
-		},
+		validation: structuredValidationPassed(resolved),
 		tips,
 		queryMenu: resolved.path,
 	};
@@ -1857,6 +1832,12 @@ export function buildApiErrorEnvelopeFromResolved(
 	trace?: ValidationTrace,
 ): ApiErrorEnvelope {
 	const centrsError = asApiError(error);
+	// A structured request is one operation; only a `/execute` script can
+	// carry several statements into one dispatch (#549), at the top level or
+	// inside an executed control scope.
+	const script = resolved.scriptMode ? scriptOf(resolved) : undefined;
+	const multiStatement =
+		script !== undefined && countExecutableStatements(script) > 1;
 	return {
 		ok: false,
 		error: serializeCentrsError(centrsError),
@@ -1866,6 +1847,7 @@ export function buildApiErrorEnvelopeFromResolved(
 				isApiMutating(resolved.method, resolved.path),
 				centrsError,
 				trace,
+				multiStatement,
 			),
 		],
 		tips: [],
@@ -1877,6 +1859,22 @@ export function buildApiErrorEnvelopeFromResolved(
 	};
 }
 
+/** A structured request the device stage passed; stage 1 does not apply to it. */
+function structuredValidationPassed(
+	resolved: ResolvedApiRequest,
+): EnvelopeValidationMeta {
+	return {
+		enabled: true,
+		source: API_DEVICE_STAGE_SOURCE,
+		result: "passed",
+		semantic: true,
+		stages: [
+			offlineApiStage(resolved),
+			{ stage: "device", source: API_DEVICE_STAGE_SOURCE, result: "passed" },
+		],
+	};
+}
+
 /**
  * `meta.validation` for an api error envelope. A stage-1 rejection opened no
  * connection, so the meta must not report `/console/inspect` as the validator
@@ -1896,7 +1894,6 @@ function failedApiValidationMeta(
 			source: OFFLINE_GATE_SOURCE,
 			result: "failed",
 			syntax: false,
-			semantic: "not-applicable",
 			stages: [
 				{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "failed" },
 				{
@@ -1911,14 +1908,14 @@ function failedApiValidationMeta(
 	// Only a `validation/*` error identifies the device stage as the rejecter.
 	// Everything downstream of a passed gate — a RouterOS fault on the request,
 	// a transport drop — is served by `trace.validation` before this function is
-	// ever reached.
+	// ever reached. A script is refused by `:parse` (syntax); a structured
+	// request by `/console/inspect` (names) (#535).
 	if (error.code.startsWith("validation/")) {
 		return {
 			enabled: true,
 			source: apiDeviceStageSource(resolved),
 			result: "failed",
-			syntax: false,
-			semantic: resolved.scriptMode ? "not-applicable" : false,
+			...(resolved.scriptMode ? { syntax: false } : { semantic: false }),
 			stages: [offlineApiStage(resolved, trace), deviceStageFailed(resolved)],
 		};
 	}
@@ -2012,8 +2009,6 @@ function disabledApiValidationMeta(
 		enabled: false,
 		source: "disabled",
 		result: "skipped",
-		syntax: false,
-		semantic: resolved.scriptMode ? "not-applicable" : false,
 		stages: [
 			{ stage: "offline", source: OFFLINE_GATE_SOURCE, result: "skipped" },
 			{

package/src/cli/explain.ts

@@ -1,6 +1,6 @@
 /**
  * `centrs explain` CLI surface: command metadata, arg parsing, dispatch, and
- * envelope rendering for the phase-1 OFFLINE analysis (#202b, #202c-2).
+ * envelope rendering for offline analysis and read-only live evidence (#491).
  *
  * ## The positional grammar is conditional, and that is deliberate
  *
@@ -20,9 +20,8 @@
  *
  * ## What this surface refuses to do
  *
- * - **The live form is rejected, not degraded.** Phase 2 owns the probes; a
- *   phase-1 run that silently analyzed offline while a router was named would
- *   report `mode: "offline"` about an invocation that asked for more.
+ * - **Live probes never execute the input.** The shared live module attaches
+ *   device evidence, `--schema` and `--complete` to the offline result.
  * - **Fan-out is rejected** (`usage/fanout-not-supported`, the `terminal`
  *   pattern): `explain` takes at most one router.
  * - **`--complete` / `--schema` enumerate nothing offline.** They are accepted,
@@ -45,9 +44,17 @@ import {
 	renderExplainEnvelope,
 	resolveExplainFormat,
 } from "../explain.ts";
+import {
+	assertExplainTarget,
+	type ExplainLiveRequest,
+	explainLiveEnvelope,
+} from "../explain-live.ts";
+import { resolveExplainCursor } from "../explain-live-facets.ts";
 import { describeCentrs } from "../index.ts";
 import { loadEnvFileDefaults } from "../resolver/config-file.ts";
+import { redactTargetInput } from "../resolver/index.ts";
 import type { ResolvedSetting } from "../resolver/settings.ts";
+import { apiCommand } from "./api.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
@@ -59,10 +66,30 @@ import { selectionFlagTokens } from "./selection.ts";
 
 export const explainCliCommand: CliCommandMetadata = {
 	name: "explain",
-	usage: "centrs explain '<input>' [flags]",
+	usage: "centrs explain [<router>] '<input>' [flags]",
 	summary:
-		"Analyze a RouterOS command offline: canonical form, structure, and syntax diagnostics.",
+		"Analyze RouterOS input offline or add read-only device evidence from one router.",
 	options: [
+		...apiCommand.options.filter((o) =>
+			[
+				"--via",
+				"--host",
+				"--port",
+				"--username / --user / -u",
+				"--password",
+				"--timeout",
+				"--insecure",
+				"--cdb-file",
+				"--cdb-password",
+				"--resolve",
+			].includes(o.flag),
+		),
+		{ flag: "-p", valueName: "<secret>", description: "Alias for --password." },
+		{
+			flag: "--quickchr",
+			valueName: "<name>",
+			description: "Resolve one running quickchr VM by name.",
+		},
 		{
 			flag: "--file",
 			valueName: "<path>",
@@ -78,12 +105,23 @@ export const explainCliCommand: CliCommandMetadata = {
 		{
 			flag: "--complete",
 			description:
-				"Continuation candidates at the cursor. Live evidence — offline emits a tip and enumerates nothing.",
+				"Candidates at the cursor: menus and verbs, argument names, or values. Live evidence — offline emits a tip and enumerates nothing.",
 		},
 		{
 			flag: "--schema",
 			description:
-				"Path enumeration (verbs, args, types, enums). Live evidence — offline emits a tip and enumerates nothing.",
+				"Describe the path at the cursor: a menu's verbs and submenus, a command's arguments, `print`'s proplist. Live evidence — offline emits a tip and enumerates nothing.",
+		},
+		{
+			flag: "--cursor",
+			valueName: "<byte>",
+			description:
+				"UTF-8 byte offset for --complete/--schema. Default: the end of the input.",
+		},
+		{
+			flag: "--full",
+			description:
+				"Lift --complete/--schema sizing to its safety ceiling (1024 names, 128 expansion probes).",
 		},
 		{
 			flag: "--curl",
@@ -106,16 +144,20 @@ export const explainCliCommand: CliCommandMetadata = {
 	],
 };
 
-export interface ExplainCliArgs {
+export interface ExplainCliArgs extends Omit<ExplainLiveRequest, "input"> {
 	help?: boolean;
 	positionals: string[];
 	filePath?: string;
 	failOn: ExplainFailOn;
 	facets: string[];
+	cursor?: number;
+	full?: boolean;
 	curl?: boolean;
 	tokens?: boolean;
 	format?: ExplainOutputFormat;
 	verbose?: boolean;
+	/** First explicitly supplied connection flag, for the missing-target refusal. */
+	connectionFlag?: string;
 }
 
 export function parseExplainCliArgs(args: readonly string[]): ExplainCliArgs {
@@ -133,6 +175,7 @@ export function parseExplainCliArgs(args: readonly string[]): ExplainCliArgs {
 			parsed.positionals.push(arg);
 			continue;
 		}
+		if (LIVE_CONNECTION_FLAGS.has(arg)) parsed.connectionFlag ??= arg;
 		switch (arg) {
 			case "--":
 				// Everything after `--` is input, however command-shaped it looks:
@@ -144,6 +187,54 @@ export function parseExplainCliArgs(args: readonly string[]): ExplainCliArgs {
 			case "-h":
 				parsed.help = true;
 				break;
+			case "--via":
+				parsed.via = expectValue(args, ++index, arg);
+				break;
+			case "--host":
+				parsed.host = expectValue(args, ++index, arg);
+				break;
+			case "--quickchr":
+				if (parsed.quickchr !== undefined)
+					throw fanoutNotSupportedError({ flag: arg });
+				parsed.quickchr = expectValue(args, ++index, arg);
+				break;
+			case "--timeout":
+				parsed.timeout = expectValue(args, ++index, arg);
+				break;
+			case "--cdb-file":
+				parsed.cdbFile = expectValue(args, ++index, arg);
+				break;
+			case "--cdb-password":
+				parsed.cdbPassword = expectValue(args, ++index, arg);
+				break;
+			case "--resolve":
+				parsed.resolve = expectValue(args, ++index, arg);
+				break;
+			case "--password":
+				parsed.password = expectValue(args, ++index, arg);
+				break;
+			case "-p":
+				parsed.password = expectValue(args, ++index, arg);
+				break;
+			case "-u":
+			case "--user":
+			case "--username":
+				parsed.username = expectValue(args, ++index, arg);
+				break;
+			case "--insecure":
+				parsed.insecure = true;
+				break;
+			case "--port": {
+				const value = expectValue(args, ++index, arg);
+				if (!/^\d+$/.test(value))
+					throw new CentrsError({
+						code: "input/invalid-command",
+						summary: "Port must be an integer.",
+						remediation: "Pass a TCP port between 1 and 65535.",
+					});
+				parsed.port = Number(value);
+				break;
+			}
 			case "--file":
 				parsed.filePath = expectValue(args, ++index, arg);
 				break;
@@ -167,6 +258,22 @@ export function parseExplainCliArgs(args: readonly string[]): ExplainCliArgs {
 			case "--schema":
 				parsed.facets.push("--schema");
 				break;
+			case "--cursor": {
+				const value = expectValue(args, ++index, arg);
+				if (!/^\d+$/.test(value))
+					throw new CentrsError({
+						code: "usage/invalid-cursor",
+						summary: `--cursor must be a non-negative byte offset; got ${value}.`,
+						remediation:
+							"Pass a UTF-8 byte offset into the input, or omit --cursor to complete at the end.",
+						context: { cursor: value },
+					});
+				parsed.cursor = Number(value);
+				break;
+			}
+			case "--full":
+				parsed.full = true;
+				break;
 			case "--curl":
 				parsed.curl = true;
 				break;
@@ -236,35 +343,11 @@ function fanoutNotSupportedError(context: {
 			...(context.flag === undefined ? {} : { flag: context.flag }),
 			...(context.targets === undefined
 				? {}
-				: { targets: [...context.targets] }),
+				: { targets: context.targets.map(redactTargetInput) }),
 		},
 	});
 }
 
-/**
- * The one live-form error.
- *
- * Named separately because it is a PHASE boundary, not a usage mistake: the
- * invocation is the ratified grammar and will work unchanged when phase 2
- * lands, so the remediation points at the offline form rather than at `--help`.
- */
-function liveNotImplementedError(router: string): CentrsError {
-	// A "router" that starts `/` or `:` is almost always an unquoted input the
-	// shell split, so name that reading first rather than reporting a router
-	// nobody meant to give.
-	const looksLikeInput = /^[/:]/.test(router);
-	return new CentrsError({
-		code: "usage/not-implemented",
-		summary: looksLikeInput
-			? `Read \`${router}\` as a router, because two positionals mean \`<router> '<input>'\` — the input was probably not quoted.`
-			: `\`centrs explain <router> '<input>'\` needs live \`/console/inspect\` evidence, which is phase 2; the router \`${router}\` was not contacted.`,
-		remediation: looksLikeInput
-			? "Quote the whole input as one argument: `centrs explain '/ip/route print'`."
-			: "Drop the router for the offline analysis (`centrs explain '<input>'`), or use `rosetta` for documented RouterOS schema facts.",
-		context: { router, phase: "2" },
-	});
-}
-
 /**
  * Is fd 0 attached to something that could be carrying input?
  *
@@ -290,11 +373,8 @@ function stdinMayCarryInput(): boolean {
 /**
  * Split the positionals into targets and the one that may be the input.
  *
- * Pure and cheap **on purpose**: the caller must be able to refuse the live and
- * fan-out forms BEFORE any input source is touched. Reading first meant
- * `centrs explain router --file -` blocked on EOF before returning
- * `usage/not-implemented`, and `… --file missing` reported a file error instead
- * of the live refusal — the wrong answer, arrived at slowly.
+ * Pure and cheap: fan-out and unsupported facets are refused before any file
+ * or stdin is read. Supported live calls read the input before connecting.
  *
  * `--file` replaces the input positional, so with it every positional is a
  * target. Otherwise the LAST positional is the input and everything before it is
@@ -320,7 +400,7 @@ function splitPositionals(parsed: ExplainCliArgs): {
 }
 
 /**
- * Read the input text, once the invocation is known to be offline.
+ * Read the input text after the invocation shape has been checked.
  *
  * ## Ambient stdin is read ONLY when nothing else could be the input
  *
@@ -396,7 +476,40 @@ async function readFileInput(path: string): Promise<string> {
 }
 
 /** Flags whose NEXT token is a value, so a scanner must skip it. */
-const VALUE_FLAGS = new Set(["--file", "--fail-on", "--format"]);
+const VALUE_FLAGS = new Set([
+	"--file",
+	"--fail-on",
+	"--format",
+	"--via",
+	"--host",
+	"--port",
+	"--username",
+	"--user",
+	"-u",
+	"--password",
+	"-p",
+	"--timeout",
+	"--cdb-file",
+	"--cdb-password",
+	"--resolve",
+	"--quickchr",
+	"--cursor",
+]);
+
+const LIVE_CONNECTION_FLAGS = new Set([
+	"--via",
+	"--port",
+	"--username",
+	"--user",
+	"-u",
+	"--password",
+	"-p",
+	"--timeout",
+	"--insecure",
+	"--cdb-file",
+	"--cdb-password",
+	"--resolve",
+]);
 
 /**
  * The render options, recovered when the parse loop THREW.
@@ -472,22 +585,68 @@ export async function runExplainCli(args: readonly string[]): Promise<number> {
 		const { targets, inputPositional } = splitPositionals(parsed);
 		if (targets.length > 1) throw fanoutNotSupportedError({ targets });
 		const router = targets[0];
-		if (router !== undefined) throw liveNotImplementedError(router);
+		assertExplainTarget({ targetInput: router, quickchr: parsed.quickchr });
+		if (router !== undefined && (/^\//.test(router) || /^:[a-z]/i.test(router)))
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary:
+					"The input was probably not quoted; two positionals mean router then input.",
+				remediation:
+					"Quote the whole input as one argument: `centrs explain '/ip/route print'`.",
+			});
+		const live =
+			router !== undefined ||
+			parsed.quickchr !== undefined ||
+			parsed.host !== undefined;
+		if (!live && parsed.connectionFlag !== undefined)
+			throw new CentrsError({
+				code: "input/invalid-command",
+				summary: `${parsed.connectionFlag} requires a router target for live explain.`,
+				remediation:
+					"Add <router>, --host <host>, or --quickchr <name>; remove the connection flag for offline analysis.",
+				context: { flag: parsed.connectionFlag },
+			});
+		if (
+			parsed.facets.length === 0 &&
+			(parsed.cursor !== undefined || parsed.full)
+		)
+			throw new CentrsError({
+				code: "usage/conflicting-flags",
+				summary: `${parsed.cursor !== undefined ? "--cursor" : "--full"} applies only with --complete or --schema.`,
+				remediation: "Add --complete or --schema, or remove the flag.",
+			});
 
 		const { input, warnings } = await readInput(parsed, inputPositional);
+		resolveExplainCursor(input, parsed.cursor);
 
-		const envelope = explainEnvelope(input, {
+		const options = {
 			format,
 			curl: parsed.curl,
 			tokens: parsed.tokens,
 			warnings,
 			tips:
-				parsed.facets.length > 0
+				!live && parsed.facets.length > 0
 					? [buildExplainFacetTip(parsed.facets)]
 					: undefined,
-		});
-		console.log(renderExplainEnvelope(envelope, format.value));
-		return explainExitCode(envelope.data.verdict, parsed.failOn);
+		};
+		const envelope = live
+			? await explainLiveEnvelope(
+					{
+						...parsed,
+						targetInput: router,
+						input,
+						schema: parsed.facets.includes("--schema"),
+						complete: parsed.facets.includes("--complete"),
+					},
+					options,
+					env,
+				)
+			: explainEnvelope(input, options);
+		if (envelope.ok) console.log(renderExplainEnvelope(envelope, format.value));
+		else console.error(renderExplainEnvelope(envelope, format.value));
+		return envelope.ok
+			? explainExitCode(envelope.data.verdict, parsed.failOn)
+			: 1;
 	} catch (error) {
 		// Only here is the parser's answer unavailable — it threw. `config` is
 		// whatever loaded before the throw, which is `{}` when the loader itself is