@tikoci/centrs 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -8,6 +8,31 @@ documenting cross-cutting shifts that affect contributors and consumers.
 
 ## Unreleased
 
+## 0.1.1 — 2026-06-22
+
+Patch release. `@tikoci/centrs@0.1.1`.
+
+### Changed
+
+- **CI is now faster on PRs.** Cross-platform unit tests (macOS + Windows) moved
+  from `ci.yaml` to `qa.yaml`, where they run in parallel with the CHR matrix on
+  every push to `main`. PRs no longer wait for macOS/Windows runners; escapes are
+  caught on the merge-to-main QA run instead.
+
+### Fixed
+
+- **CLI: registry-aware `missing-router` tips.** All router-taking commands now
+  emit a CDB-aware tip when no `<router>` argument is supplied — listing saved
+  handles from the CDB (`tip/select-target`) or pointing to `centrs discover
+  --save` when the registry is empty (`tip/no-devices`).
+- **`discover --save` lookup keys and progress.** The saved device record now
+  includes `identity=` and `mac=` keys so downstream commands can resolve the
+  entry; MAC addresses are de-duplicated. TTY progress is shown during a scan and
+  a `--save` tip is printed at the end of a bare discover run.
+- **CodeQL / security hardening (PR #80 review).** Addressed reviewer findings:
+  clear-text credential log suppressed; progress output switched to stderr/JSON-safe
+  path; `retrieve` resource leak closed; doc corrections.
+
 ## 0.1.0 — 2026-06-22
 
 First published pre-release (odd minor → npm `next`). `@tikoci/centrs@0.1.0`.

package/commands/devices/README.md

@@ -403,3 +403,29 @@ When an item ships with CHR examples, fold it into the matrix and delete the row
   same envelope as the CDB. Provenance source label: `dude`.
 - The `centrs check` command will reuse the resolver and add a network probe;
   `devices` itself stays RouterOS-IO-free.
+
+### Missing-target guidance (and the MCP/proxy follow-up)
+
+When a command that takes a `<router>` is called without one, the **CLI** turns
+the bare usage error into a registry-aware tip (shared helper
+`src/cli/missing-target.ts`): it reads the CDB best-effort and emits either
+`tip/select-target` (lists a few saved handles to pass — identity over target) or
+`tip/no-devices` (→ `centrs discover --save`) when the registry is empty. The
+read is unencrypted-only and the CDB **password never threads into the tip path**,
+so an encrypted registry falls back to generic guidance.
+
+This guidance is currently **CLI-shaped on purpose** and is *not* yet wired into
+the MCP/proxy frontends — that is deferred spec/review work. Two boundaries
+should shape it when it lands, because the registry's role differs per frontend:
+
+- The `tip/*` envelope channel is shared-core, but the specific remediation
+  *strings* (`centrs devices list`, `centrs discover --save`) are CLI verbs and
+  must **not** be emitted verbatim by MCP/proxy. Each frontend phrases the
+  next-step in its own vocabulary.
+- On **MCP**, targets come from the **CDB allowlist**, not free-text `<router>`
+  (constitution: MCP surface). An unregistered/empty target is
+  `cdb/target-not-registered`, and the `centrs://devices` resource already
+  enumerates the allowlisted targets — so the MCP equivalent of "what can I
+  pass?" is "read the `centrs://devices` resource / register a device first,"
+  not "run discover." The **proxy** fronts the same CDB and should mirror the MCP
+  framing, not the CLI's `discover --save` nudge.

package/commands/discover/README.md

@@ -6,10 +6,10 @@ Status: `CHR-passed` (see `docs/MATRIX.md`). The MNDP codec, TTL cache, UDP
 listener, and `discover --save` are implemented; the real-L2 receive/decode/save
 path is green against RouterOS CHR 7.23.1 via `test/integration/discover.test.ts`
 (socket-connect bridge), and the network-independent paths stay unit-tested. The
-matrix remains the only status surface. The `identity=`/`mac=` lookup-key writing and
-MAC-keyed de-dupe described below are the decided target; the current `--save`
-de-dupes on `target` and keeps identity/MAC in the inert detail — that gap moves
-with the `devices` lookup-key work.
+matrix remains the only status surface. `--save` now writes the `identity=`/`mac=`
+lookup keys and de-dupes on the MAC (both described below), so a discovered
+device resolves by its advertised identity, IP, or MAC — not just the stored
+`target`.
 
 ## Synopsis
 
@@ -66,7 +66,14 @@ tested without a router (crafted packet fixtures + a loopback socket).
 `--save` without `--timeout` uses the default 15s window.
 
 Bare `centrs discover` is **read-only** — it returns the envelope and never
-writes the (WinBox-shared) CDB; `--save` is the explicit opt-in. The registry
+writes the (WinBox-shared) CDB; `--save` is the explicit opt-in. When it finds
+neighbors but was not given `--save`, the envelope carries a `tip/discover-save`
+pointer so the read-only run advertises how to persist the result. In the
+human-facing text format on an interactive terminal (TTY) `discover` also prints
+a one-line "listening…" progress note to **stderr** so the listen window does not
+look like a hang; `--format json|yaml` and piped/redirected runs stay silent
+(stderr is exempt from the lossless-stdout rule — see
+[`docs/CONSTITUTION.md`](../../docs/CONSTITUTION.md), Result envelope). The registry
 surface `centrs devices discover` is the inverse: invoking `devices` means you
 intend to populate it, so **`--save` is implied** there, and it is the home for
 the "set default credentials so centrs starts useful" onboarding nudge. Both
@@ -108,9 +115,11 @@ writer" holds.
   globally unique — `identity` is *not* the de-dupe key, because factory-default
   devices all report `MikroTik`. A neighbor whose MAC already names a CDB entry
   (as the `target` of a `macTarget` record or as a `mac=` lookup key on any
-  record) is **skipped, never overwritten** — hand-curated records win. Only
-  genuinely new devices are added. Writes reuse the `devices` atomic write path
-  (`addDevice`); the CDB is reloaded between writes so each add sees prior ones.
+  record) is **skipped, never overwritten** — hand-curated records win. A
+  neighbor whose IP `target` already names an entry is likewise skipped, so a
+  curated record is never clobbered. Only genuinely new devices are added. Writes
+  reuse the `devices` atomic write path (`addDevice`); the CDB is reloaded between
+  writes so each add sees prior ones.
 - **Encrypted CDBs:** `--save` against an encrypted CDB decrypts the file under
   the loaded password, appends new neighbors, and re-encrypts with a fresh salt
   before the atomic rename. The backup beside the CDB is the verbatim prior

package/commands/discover/examples.md

@@ -63,9 +63,11 @@ centrs discover --save --cdb-file $CDB
 ```
 
 New neighbors are added through the `devices` atomic write path with
-`group=discovered`. Each saved comment contains the `source=mndp` kv token and
-free-form provenance (`identity:`, `board:`, `version:`, `mac:`, …).
-`meta.operation.saved` reports `{ group, added, skipped, records }`.
+`group=discovered`. Each saved comment carries the `source=mndp` kv token, the
+`identity=`/`mac=` **lookup keys** (so the device resolves by its advertised
+identity, IP, or MAC), and a free-form parenthesized detail (`board:`,
+`version:`, `interface:`, `software-id:`). `meta.operation.saved` reports
+`{ group, added, skipped, records }`.
 
 ### 5. Save with a custom group
 
@@ -81,8 +83,11 @@ New entries get `group=lab` instead of `discovered`.
 centrs discover --save --cdb-file $CDB
 ```
 
-A neighbor whose target (IPv4, else MAC) already names a CDB entry is skipped,
-never overwritten. The skip is reported in
+A neighbor whose **MAC** already names a CDB entry — as a `macTarget` record's
+target or a `mac=` lookup key on any record (and likewise any record sharing the
+neighbor's IP target) — is skipped, never overwritten. MAC is the de-dupe key
+because it is globally unique and always advertised; `identity` is not, since
+factory-default devices all report `MikroTik`. The skip is reported in
 `meta.operation.saved.records[].action = "skipped-existing"`; hand-curated
 records win.
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@tikoci/centrs",
-	"version": "0.1.0",
+	"version": "0.1.1",
 	"main": "src/index.ts",
 	"module": "src/index.ts",
 	"repository": {

package/src/cli/btest.ts

@@ -26,11 +26,19 @@ import {
 import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
 import { describeCentrs, parseDuration } from "../index.ts";
 import type { BtestDirection, BtestProtocol } from "../protocols/btest.ts";
+import { toYaml } from "../retrieve.ts";
 import {
 	type CliCommandMetadata,
 	expectValue,
 	renderCommandHelp,
 } from "./common.ts";
+import {
+	buildTargetSelectionTips,
+	cdbFileFromArgs,
+	formatTipsText,
+	isMissingTargetError,
+	missingTargetError,
+} from "./missing-target.ts";
 
 export const btestCommand: CliCommandMetadata = {
 	name: "btest",
@@ -355,6 +363,14 @@ async function runClient(args: readonly string[]): Promise<number> {
 		console.log(renderCommandHelp(describeCentrs(), btestCommand));
 		return 0;
 	}
+	if (request.targetInput === undefined) {
+		throw missingTargetError({
+			command: "btest client",
+			summary: "`centrs btest client` requires a <router> target.",
+			remediation:
+				"Pass the bandwidth-test server's host/identity, e.g. `centrs btest client 192.0.2.10`.",
+		});
+	}
 	const streaming = format === "text" || format === "csv";
 	let csvHeader = false;
 	if (streaming) {
@@ -444,12 +460,40 @@ export async function runBtestCli(args: readonly string[]): Promise<number> {
 			`Unknown btest sub-command: ${sub}. Use \`client <router>\` or \`server\`.`,
 		);
 	} catch (error) {
+		// The parsed request (not present here) holds the raw password for auth;
+		// errors at this level are missing-target or arg-parse failures — neither
+		// carries credentials. CodeQL follows the password parsed earlier in
+		// runBtestCli and flags any console.error that touches centrsError; the
+		// password reaches neither the error nor these renderers, so the alerts are
+		// suppressed inline (same as the matching dismissals on terminal/transfer/execute).
 		const centrsError = asCentrsError(error, {
 			code: "input/invalid-command",
 			summary: error instanceof Error ? error.message : String(error),
 			remediation: "Use `centrs btest --help` to inspect the supported flags.",
 		});
-		console.error(formatCentrsErrorText(centrsError));
+		const tips = isMissingTargetError(centrsError)
+			? await buildTargetSelectionTips({
+					cdbFile: cdbFileFromArgs(args),
+					env: Bun.env,
+				})
+			: [];
+		const format = args.includes("--json")
+			? "json"
+			: args.includes("--yaml")
+				? "yaml"
+				: "text";
+		if (format === "json" || format === "yaml") {
+			const out = {
+				ok: false as const,
+				error: { code: centrsError.code },
+				tips,
+			};
+			const serialized = format === "yaml" ? toYaml(out) : JSON.stringify(out);
+			console.error(serialized); // lgtm[js/clear-text-logging]
+		} else {
+			const text = formatCentrsErrorText(centrsError) + formatTipsText(tips);
+			console.error(text); // lgtm[js/clear-text-logging]
+		}
 		return 1;
 	}
 }

package/src/cli/discover.ts

@@ -6,10 +6,12 @@
  */
 
 import {
+	DISCOVER_DEFAULT_TIMEOUT_MS,
 	type DiscoverOptions,
 	type DiscoverOutputFormat,
 	discover,
 	discoverOutputFormats,
+	MNDP_PORT,
 	renderDiscoverEnvelope,
 } from "../discover.ts";
 import { asCentrsError, formatCentrsErrorText } from "../errors.ts";
@@ -142,6 +144,29 @@ function parseDiscoverCliArgs(args: readonly string[]): DiscoverCliArgs {
 	return parsed;
 }
 
+/**
+ * A 15s passive listen looks like a hang on an interactive terminal, so print a
+ * one-line progress note to **stderr** for the human-facing text format on a
+ * TTY. Skipped when piped/redirected (not a TTY) and for the `--format
+ * json|yaml` structured modes, so machine consumers never see it. stderr is the
+ * sanctioned channel for discover scan progress (`docs/CONSTITUTION.md` → Result
+ * envelope).
+ */
+function emitDiscoverProgress(
+	options: DiscoverOptions,
+	format: DiscoverOutputFormat | undefined,
+): void {
+	if (format === "json" || format === "yaml" || !process.stderr.isTTY) {
+		return;
+	}
+	const windowMs = options.timeoutMs ?? DISCOVER_DEFAULT_TIMEOUT_MS;
+	const port = options.port ?? MNDP_PORT;
+	const hint = options.save ? "" : " (add --save to populate the CDB)";
+	process.stderr.write(
+		`Listening for MNDP neighbors for ${Math.round(windowMs / 1000)}s on UDP ${port}…${hint}\n`,
+	);
+}
+
 export async function runDiscoverCli(args: readonly string[]): Promise<number> {
 	let parsed: DiscoverCliArgs | undefined;
 	try {
@@ -160,6 +185,7 @@ export async function runDiscoverCli(args: readonly string[]): Promise<number> {
 			cdbPassword: parsed.cdbPassword,
 			env: Bun.env,
 		};
+		emitDiscoverProgress(options, parsed.format);
 		const envelope = await discover(options);
 		const format = parsed.format ?? "text";
 		const rendered = renderDiscoverEnvelope(envelope, format);

package/src/cli/execute.ts

@@ -13,6 +13,14 @@ import {
 	expectValue,
 	renderCommandHelp,
 } from "./common.ts";
+import {
+	buildTargetSelectionTips,
+	cdbFileFromArgs,
+	formatTipsText,
+	isMissingTargetError,
+	missingTargetError,
+	withTips,
+} from "./missing-target.ts";
 
 export const executeCommand: CliCommandMetadata = {
 	name: "execute",
@@ -241,6 +249,18 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 			console.log(renderCommandHelp(describeCentrs(), executeCommand));
 			return 0;
 		}
+		// No positional at all: lead with the missing-target guidance (CDB picker /
+		// discover) rather than the missing-command error — there is nothing to run
+		// without a device. A lone positional is treated as the target, so the
+		// "requires a command" path still fires for `execute <target>`.
+		if (!parsed.targetInput) {
+			throw missingTargetError({
+				command: "execute",
+				summary: "`centrs execute` requires a <target> and a RouterOS command.",
+				remediation:
+					'Pass the router host/identity then the command, e.g. `centrs execute 192.0.2.10 "/system/resource/print"`.',
+			});
+		}
 
 		const envelope = await executeEnvelope(parsed);
 		const resolvedFormat =
@@ -264,10 +284,16 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 		// Parse/usage errors land here too: surface them through the same typed
 		// envelope as every other runner (no raw message, no exit code 2).
 		const format = inferExecuteFormat(args, parsed);
+		const tips = isMissingTargetError(error)
+			? await buildTargetSelectionTips({
+					cdbFile: parsed?.cdbFile ?? cdbFileFromArgs(args),
+					env: Bun.env,
+				})
+			: [];
 		if (format === "json" || format === "yaml") {
-			const envelope = buildExecuteErrorEnvelope(
-				parsed ?? { command: "" },
-				error,
+			const envelope = withTips(
+				buildExecuteErrorEnvelope(parsed ?? { command: "" }, error),
+				tips,
 			);
 			console.error(
 				renderExecuteEnvelope(envelope, format, {
@@ -284,7 +310,7 @@ export async function runExecuteCli(args: readonly string[]): Promise<number> {
 							"Use `centrs execute --help` to inspect the supported command shape and flags.",
 					}),
 					{ verbose: parsed?.verbose ?? args.includes("--verbose") },
-				),
+				) + formatTipsText(tips),
 			);
 		}
 		return 1;

package/src/cli/missing-target.ts

@@ -0,0 +1,171 @@
+/**
+ * Shared "no `<router>` target" guidance for the CLI surfaces.
+ *
+ * Every command that takes a `<router>` (terminal, execute, retrieve, transfer,
+ * btest client) raises the same `input/invalid-command` error when the target is
+ * missing, tagged with `context.missingTarget`. Each runner then calls
+ * {@link buildTargetSelectionTips} to turn that bare usage error into actionable
+ * advice: list a few saved CDB devices to pass as `<router>`, or — when the
+ * registry is empty — point at `centrs discover --save`. Tips ride the envelope's
+ * `tips` channel (`docs/CONSTITUTION.md` → Result envelope); this module also
+ * renders them for the **text** error path, which `formatCentrsErrorText` does
+ * not surface on its own.
+ */
+
+import { buildTip, type Tip } from "../core/envelope.ts";
+import { defaultCdbPath, loadCdb } from "../devices.ts";
+import { CentrsError } from "../errors.ts";
+import { DEFAULT_RECORD_TARGET, identityFromComment } from "../resolver/cdb.ts";
+
+/** Cap on how many saved devices a single tip names before "(+N more)". */
+const MAX_LISTED_DEVICES = 8;
+
+export interface MissingTargetErrorInit {
+	command: string;
+	summary: string;
+	remediation: string;
+}
+
+/**
+ * The canonical "missing `<router>`" usage error. The `context.missingTarget`
+ * flag is the marker {@link isMissingTargetError} keys on so a runner knows to
+ * attach {@link buildTargetSelectionTips} output.
+ */
+export function missingTargetError(init: MissingTargetErrorInit): CentrsError {
+	return new CentrsError({
+		code: "input/invalid-command",
+		summary: init.summary,
+		remediation: init.remediation,
+		context: { missingTarget: true, command: init.command },
+	});
+}
+
+/** True for an error raised by {@link missingTargetError} (or one tagged like it). */
+export function isMissingTargetError(error: unknown): boolean {
+	return (
+		error instanceof CentrsError && error.context?.["missingTarget"] === true
+	);
+}
+
+export interface CdbInputs {
+	cdbFile?: string;
+	env?: Record<string, string | undefined>;
+}
+
+/**
+ * Pull the `--cdb-file` path out of raw args. Used by catch paths where the
+ * request never finished parsing (the missing-target throw happens mid-parse),
+ * so the request object is unavailable but the flag may still be on the command
+ * line. The CDB *password* is deliberately not extracted: a credential must
+ * never flow into the (logged) tip path, and the tips read only an unencrypted
+ * registry — an encrypted CDB falls back to generic guidance.
+ */
+export function cdbFileFromArgs(args: readonly string[]): string | undefined {
+	for (let index = 0; index < args.length; index += 1) {
+		if (args[index] === "--cdb-file") {
+			if (index + 1 >= args.length) return undefined;
+			const value = args[index + 1] as string; // bounds-checked above
+			if (value.startsWith("--")) return undefined;
+			return value;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Best-effort: inspect the CDB and turn "no `<router>`" into actionable tips —
+ * a list of saved targets when the registry has any, otherwise a pointer to
+ * `discover --save`. Never throws: an unreadable/encrypted CDB falls back to
+ * generic guidance, and a missing default CDB is reported as an empty registry
+ * (no file is created as a side effect of a usage error). The CDB password is
+ * intentionally never read here, so no credential can reach the rendered tip.
+ */
+export async function buildTargetSelectionTips(
+	inputs: CdbInputs,
+): Promise<Tip[]> {
+	const env = inputs.env ?? {};
+	const explicitCdb =
+		inputs.cdbFile !== undefined || env["CENTRS_CDB_FILE"] !== undefined;
+	if (!explicitCdb && !(await Bun.file(defaultCdbPath(env)).exists())) {
+		return [emptyRegistryTip()];
+	}
+
+	let entries: readonly { target: string; comment: string }[];
+	try {
+		const cdb = await loadCdb({
+			cdbFile: inputs.cdbFile,
+			env,
+		});
+		entries = cdb.entries.filter(
+			(entry) =>
+				entry.target.length > 0 && entry.target !== DEFAULT_RECORD_TARGET,
+		);
+	} catch {
+		return [unreadableRegistryTip()];
+	}
+
+	if (entries.length === 0) {
+		return [emptyRegistryTip()];
+	}
+
+	const handles = entries
+		.slice(0, MAX_LISTED_DEVICES)
+		.map((entry) => identityFromComment(entry.comment, entry.target));
+	const extra =
+		entries.length > MAX_LISTED_DEVICES
+			? ` (+${entries.length - MAX_LISTED_DEVICES} more)`
+			: "";
+	return [
+		buildTip(
+			"tip/select-target",
+			`Pass one of your ${entries.length} saved device(s) as <router>: ${handles.join(", ")}${extra}.`,
+			"Run `centrs devices list` for every saved target; <router> also resolves by identity=, mac=, or ip=.",
+		),
+	];
+}
+
+function emptyRegistryTip(): Tip {
+	return buildTip(
+		"tip/no-devices",
+		"No devices are saved in the CDB yet.",
+		"Run `centrs discover --save` to find RouterOS neighbors on the LAN and add them, then pass one as <router> (or `centrs devices add <target> --user … --password …`).",
+	);
+}
+
+function unreadableRegistryTip(): Tip {
+	return buildTip(
+		"tip/select-target",
+		"Could not read the CDB to list saved devices (it may be encrypted — pass --cdb-password).",
+		"Run `centrs devices list` to see saved targets, or `centrs discover --save` to find and add neighbors on the LAN.",
+	);
+}
+
+/**
+ * Render tips for the **text** error path (mirrors the `devices` "Tips:"
+ * footer). Returns "" for an empty list so callers can append unconditionally.
+ */
+export function formatTipsText(tips: readonly Tip[]): string {
+	if (tips.length === 0) {
+		return "";
+	}
+	const lines = ["", "Tips:"];
+	for (const tip of tips) {
+		lines.push(`  - [${tip.code}] ${tip.message}`);
+		if (tip.fix) {
+			lines.push(`    fix: ${tip.fix}`);
+		}
+	}
+	return lines.join("\n");
+}
+
+/**
+ * Return a copy of an envelope with `tips` attached (no-op for an empty list).
+ * The `as E` keeps the call site's envelope type when an error envelope declares
+ * `tips: []` (an empty tuple) — we only ever widen it to a populated list.
+ */
+export function withTips<E extends { tips: readonly Tip[] }>(
+	envelope: E,
+	tips: readonly Tip[],
+): E {
+	return tips.length > 0 ? ({ ...envelope, tips } as E) : envelope;
+}

package/src/cli/retrieve.ts

@@ -22,6 +22,14 @@ import {
 	expectValue,
 	renderCommandHelp,
 } from "./common.ts";
+import {
+	buildTargetSelectionTips,
+	cdbFileFromArgs,
+	formatTipsText,
+	isMissingTargetError,
+	missingTargetError,
+	withTips,
+} from "./missing-target.ts";
 
 export const retrieveCommand: CliCommandMetadata = {
 	name: "retrieve",
@@ -171,6 +179,12 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 		return 0;
 	} catch (error) {
 		const format = inferRequestedFormat(args, request);
+		const tips = isMissingTargetError(error)
+			? await buildTargetSelectionTips({
+					cdbFile: request?.cdbFile ?? cdbFileFromArgs(args),
+					env: Bun.env,
+				})
+			: [];
 		if (format === "json" || format === "yaml") {
 			if (request?.group) {
 				const envelope = buildRetrieveFanoutErrorEnvelope(request, error);
@@ -180,9 +194,14 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 					}),
 				);
 			} else {
-				const envelope = buildRetrieveErrorEnvelope(
-					request ?? fallbackRequestFromArgs(args),
-					error,
+				// When parsing failed before a request existed, build the error
+				// envelope from an empty request rather than reconstructing positionals
+				// from raw args — a credential value (e.g. the token after
+				// `--password` / `--cdb-password`) would otherwise be echoed as
+				// `meta.target.input`.
+				const envelope = withTips(
+					buildRetrieveErrorEnvelope(request ?? { path: "" }, error),
+					tips,
 				);
 				console.error(
 					renderRetrieveEnvelope(envelope, format, {
@@ -202,7 +221,7 @@ export async function runRetrieveCli(args: readonly string[]): Promise<number> {
 					{
 						verbose: request?.verbose ?? args.includes("--verbose"),
 					},
-				),
+				) + formatTipsText(tips),
 			);
 		}
 		return 1;
@@ -341,9 +360,17 @@ function parseRetrieveCliArgs(args: readonly string[]): RetrieveRequest & {
 		return request;
 	}
 
+	if (positional.length === 0) {
+		throw missingTargetError({
+			command: "retrieve",
+			summary: "`centrs retrieve` requires a <target> and a <routeros-path>.",
+			remediation:
+				"Pass the router host/identity then the RouterOS path, e.g. `centrs retrieve 192.0.2.10 /system/resource`.",
+		});
+	}
 	if (positional.length < 2) {
 		throw new Error(
-			"`centrs retrieve` requires both <target> and <routeros-path>.",
+			"`centrs retrieve` requires a <routeros-path> after the <target>.",
 		);
 	}
 
@@ -372,12 +399,3 @@ function inferRequestedFormat(
 	}
 	return "text";
 }
-
-function fallbackRequestFromArgs(args: readonly string[]): RetrieveRequest {
-	const positionals = args.filter((arg) => !arg.startsWith("-"));
-	return {
-		targetInput: positionals[0],
-		path: positionals[1] ?? "",
-		format: inferRequestedFormat(args),
-	};
-}

package/src/cli/terminal.ts

@@ -20,6 +20,14 @@ import {
 	expectValue,
 	renderCommandHelp,
 } from "./common.ts";
+import {
+	buildTargetSelectionTips,
+	cdbFileFromArgs,
+	formatTipsText,
+	isMissingTargetError,
+	missingTargetError,
+	withTips,
+} from "./missing-target.ts";
 
 export const terminalCommand: CliCommandMetadata = {
 	name: "terminal",
@@ -164,8 +172,14 @@ export async function runTerminalCli(args: readonly string[]): Promise<number> {
 		// error nor these renderers, so the alert is dismissed as a false positive
 		// repo-wide — see the matching dismissals on src/cli/{transfer,execute}.ts.
 		const format = inferRequestedFormat(args);
+		const tips = isMissingTargetError(error)
+			? await buildTargetSelectionTips({
+					cdbFile: request?.cdbFile ?? cdbFileFromArgs(args),
+					env: Bun.env,
+				})
+			: [];
 		if (format === "json" || format === "yaml") {
-			const envelope = buildTerminalErrorEnvelope(error);
+			const envelope = withTips(buildTerminalErrorEnvelope(error), tips);
 			console.error(
 				format === "yaml" ? toYaml(envelope) : JSON.stringify(envelope),
 			);
@@ -179,7 +193,7 @@ export async function runTerminalCli(args: readonly string[]): Promise<number> {
 							"Use `centrs terminal --help` for the supported command shape and flags.",
 					}),
 					{ verbose: args.includes("--verbose") },
-				),
+				) + formatTipsText(tips),
 			);
 		}
 		return 1;
@@ -272,8 +286,8 @@ function parseTerminalCliArgs(args: readonly string[]): ParsedTerminal {
 	}
 	const targetInput = positional[0];
 	if (!targetInput) {
-		throw asCentrsError(new Error("terminal requires a <router> target."), {
-			code: "input/invalid-command",
+		throw missingTargetError({
+			command: "terminal",
 			summary: "`centrs terminal` requires a <router> target.",
 			remediation:
 				"Pass the device MAC (or a CDB identity/ip) as the first argument; run `centrs terminal --help` for the shape.",

package/src/cli/transfer.ts

@@ -24,6 +24,14 @@ import {
 	expectValue,
 	renderCommandHelp,
 } from "./common.ts";
+import {
+	buildTargetSelectionTips,
+	cdbFileFromArgs,
+	formatTipsText,
+	isMissingTargetError,
+	missingTargetError,
+	withTips,
+} from "./missing-target.ts";
 
 /** Sub-verb aliases, resolved to canonical verbs silently (commands/AGENTS.md). */
 const VERB_ALIASES: Record<string, TransferVerb> = {
@@ -173,10 +181,19 @@ export async function runTransferCli(
 		// (CodeQL js/clear-text-logging).
 		const safeRequest = redactTransferRequest(request);
 		const format = inferRequestedFormat(args, safeRequest);
+		const tips = isMissingTargetError(error)
+			? await buildTargetSelectionTips({
+					cdbFile: safeRequest?.cdbFile ?? cdbFileFromArgs(args),
+					env: Bun.env,
+				})
+			: [];
 		if (format === "json" || format === "yaml") {
-			const envelope = buildTransferErrorEnvelope(
-				safeRequest ?? { verb: options.fixedVerb ?? "list" },
-				error,
+			const envelope = withTips(
+				buildTransferErrorEnvelope(
+					safeRequest ?? { verb: options.fixedVerb ?? "list" },
+					error,
+				),
+				tips,
 			);
 			console.error(
 				renderTransferEnvelope(envelope, format, {
@@ -193,7 +210,7 @@ export async function runTransferCli(
 							"Use `centrs transfer --help` to inspect the supported command shape and flags.",
 					}),
 					{ verbose: safeRequest?.verbose ?? args.includes("--verbose") },
-				),
+				) + formatTipsText(tips),
 			);
 		}
 		return 1;
@@ -367,13 +384,24 @@ function assemblePositionals(
 	} else {
 		targetInput = positional[0];
 		const rawVerb = positional[1];
-		if (!targetInput || !rawVerb) {
+		// A missing target gets the tagged missing-target error (CDB picker tip);
+		// a present target with no verb is a distinct "which verb?" usage error.
+		if (!targetInput) {
+			throw missingTargetError({
+				command: "transfer",
+				summary:
+					"`centrs transfer` requires a <router> target and a verb (upload|download|list|remove|mkdir|copy).",
+				remediation:
+					"Pass the target then a verb, e.g. `centrs transfer <router> list`; run `--help` for the full shape.",
+			});
+		}
+		if (!rawVerb) {
 			throw new CentrsError({
 				code: "input/invalid-command",
 				summary:
-					"`centrs transfer` requires <router> and a verb (upload|download|list|remove|mkdir|copy).",
+					"`centrs transfer` requires a verb after the <router> (upload|download|list|remove|mkdir|copy).",
 				remediation:
-					"Pass the target then a verb, e.g. `centrs transfer <router> list`; run `--help` for the full shape.",
+					"Pass a verb, e.g. `centrs transfer <router> list`; run `--help` for the full shape.",
 				context: { targetInput, verb: rawVerb },
 			});
 		}
@@ -382,8 +410,8 @@ function assemblePositionals(
 	}
 
 	if (!targetInput) {
-		throw new CentrsError({
-			code: "input/invalid-command",
+		throw missingTargetError({
+			command: "transfer",
 			summary: "`centrs transfer` requires a <router> target.",
 			remediation:
 				"Pass the router host/identity as the first argument; run `centrs transfer --help` for the command shape.",

package/src/discover.ts

@@ -18,7 +18,8 @@
  */
 
 import { createSocket } from "node:dgram";
-import type { CentrsEnvelope, EnvelopeMeta } from "./core/envelope.ts";
+import type { CentrsEnvelope, EnvelopeMeta, Tip } from "./core/envelope.ts";
+import { buildTip } from "./core/envelope.ts";
 import {
 	MNDP_BROADCAST_ADDRESS,
 	MNDP_PORT,
@@ -27,7 +28,7 @@ import {
 	parseMndpPacket,
 } from "./data/mndp.ts";
 import { MndpCache } from "./data/mndp-cache.ts";
-import { winBoxCdbRecordType } from "./data/winbox-cdb.ts";
+import { type WinBoxCdbEntry, winBoxCdbRecordType } from "./data/winbox-cdb.ts";
 import type { WriteWinBoxCdbOptions } from "./data/winbox-cdb-write.ts";
 import {
 	addDevice,
@@ -37,7 +38,8 @@ import {
 	resolveDevicesSettings,
 } from "./devices.ts";
 import { asCentrsError, CentrsError, serializeCentrsError } from "./errors.ts";
-import { renderCommentKvToken } from "./resolver/comment-kv.ts";
+import { parseCommentKv, renderCommentKvToken } from "./resolver/comment-kv.ts";
+import { normalizeMac } from "./resolver/mac.ts";
 
 export { MNDP_PORT, MndpCache };
 
@@ -396,38 +398,75 @@ function toDiscoverNeighbor(
 }
 
 /**
- * Build the human/structured comment for a saved neighbor. The only kv token is
- * the allowlisted `source=mndp`; the parenthesized detail is free-form (no
- * `key=value` shapes) so it preserves provenance without emitting
- * `cdb/unknown-option` warnings later.
+ * Build the comment for a saved neighbor: the allowlisted `source=mndp` token
+ * and the `identity=`/`mac=` **lookup keys** (so the device resolves by any of
+ * its identifiers — see `commands/devices/README.md`, Identity model), followed
+ * by a free-form, parenthesized provenance detail. `identity=` is written
+ * whenever advertised; `mac=` only when the **target is the IP** (a `macTarget`
+ * record's target already *is* the MAC, so a `mac=` key would be redundant). The
+ * parenthesized detail carries no `key=value` shapes, so it stays inert and
+ * never emits a `cdb/unknown-option` warning later.
  */
+
+// Strip `=` from free-form device-advertised strings so they can't be
+// misinterpreted as lookup key=value tokens if parseCommentKv ever processes
+// the parenthesized section.
+function sanitizeDetail(value: string): string {
+	return value.replaceAll("=", "≔");
+}
+
 export function formatMndpProvenanceComment(
 	neighbor: MndpNeighbor,
 	at: Date,
 ): string {
-	const detail: string[] = [`discovered ${at.toISOString()} via MNDP`];
+	const tokens: string[] = [renderCommentKvToken("source", "mndp")];
 	if (neighbor.identity) {
-		detail.push(`identity: ${neighbor.identity}`);
+		tokens.push(renderCommentKvToken("identity", neighbor.identity));
+	}
+	if (neighbor.ipv4 && neighbor.macAddress) {
+		tokens.push(renderCommentKvToken("mac", neighbor.macAddress));
 	}
+	const detail: string[] = [`discovered ${at.toISOString()} via MNDP`];
 	if (neighbor.platform) {
-		detail.push(`platform: ${neighbor.platform}`);
+		detail.push(`platform: ${sanitizeDetail(neighbor.platform)}`);
 	}
 	if (neighbor.board) {
-		detail.push(`board: ${neighbor.board}`);
+		detail.push(`board: ${sanitizeDetail(neighbor.board)}`);
 	}
 	if (neighbor.version) {
-		detail.push(`version: ${neighbor.version}`);
-	}
-	if (neighbor.macAddress) {
-		detail.push(`mac: ${neighbor.macAddress}`);
+		detail.push(`version: ${sanitizeDetail(neighbor.version)}`);
 	}
 	if (neighbor.interfaceName) {
-		detail.push(`interface: ${neighbor.interfaceName}`);
+		detail.push(`interface: ${sanitizeDetail(neighbor.interfaceName)}`);
 	}
 	if (neighbor.softwareId) {
-		detail.push(`software-id: ${neighbor.softwareId}`);
+		detail.push(`software-id: ${sanitizeDetail(neighbor.softwareId)}`);
 	}
-	return `${renderCommentKvToken("source", "mndp")} (${detail.join("; ")})`;
+	return `${tokens.join(" ")} (${detail.join("; ")})`;
+}
+
+/**
+ * True when a discovered neighbor's MAC already names a CDB entry — as the
+ * `target` of a `macTarget` record or as a `mac=` lookup key on any record. MNDP
+ * always carries the MAC and it is globally unique, so it is the de-dupe key
+ * (`commands/discover/README.md`, `--save` de-dupe); `identity` is *not*, since
+ * factory-default devices all report `MikroTik`.
+ */
+function neighborMacKnown(
+	entries: readonly WinBoxCdbEntry[],
+	mac: string | undefined,
+): boolean {
+	const want = normalizeMac(mac ?? "");
+	if (!want) {
+		return false;
+	}
+	return entries.some((entry) => {
+		if (normalizeMac(entry.target) === want) {
+			return true;
+		}
+		const lookupMac = parseCommentKv(entry.comment).lookups.mac;
+		return lookupMac !== undefined && normalizeMac(lookupMac) === want;
+	});
 }
 
 /** Target a neighbor maps to in the CDB: its IPv4, else its MAC. */
@@ -457,9 +496,12 @@ export interface SaveDiscoveredNeighborsResult {
 
 /**
  * Persist discovered neighbors into the CDB via {@link addDevice}. De-dupe
- * rule: a neighbor whose target (IPv4, else MAC) already names a CDB entry is
- * skipped — never overwritten — so hand-curated records win. New neighbors are
- * added with `group=discovered` and `source=mndp` provenance. The CDB is
+ * rule: a neighbor whose **MAC** already names a CDB entry — as a `macTarget`
+ * record's `target` or a `mac=` lookup key on any record (see
+ * {@link neighborMacKnown}) — is skipped, never overwritten; a neighbor whose
+ * `target` string already names an entry is likewise skipped. Hand-curated
+ * records always win. New neighbors are added with `group=discovered`, the
+ * `identity=`/`mac=` lookup keys, and `source=mndp` provenance. The CDB is
  * reloaded between writes so each `addDevice` sees the prior additions.
  */
 export async function saveDiscoveredNeighbors(
@@ -484,7 +526,13 @@ export async function saveDiscoveredNeighbors(
 		if (!target) {
 			continue;
 		}
-		const exists = cdb.entries.some((entry) => entry.target === target);
+		// De-dupe on the MAC (globally unique, always advertised), and also skip a
+		// target string that already names an entry — both guard a hand-curated
+		// record from being clobbered, and the latter keeps `addDevice` from
+		// failing `cdb/already-exists` on a colliding connectable address.
+		const exists =
+			neighborMacKnown(cdb.entries, neighbor.macAddress) ||
+			cdb.entries.some((entry) => entry.target === target);
 		const detail: DiscoverSaveRecord = {
 			target,
 			action: exists ? "skipped-existing" : "added",
@@ -646,11 +694,22 @@ export async function discover(
 		}
 	}
 
+	const tips: Tip[] = [];
+	if (!options.save && neighbors.length > 0) {
+		tips.push(
+			buildTip(
+				"tip/discover-save",
+				`Found ${neighbors.length} neighbor(s); this run did not save them (read-only without --save).`,
+				"Re-run with `--save` to persist them into the CDB (group=discovered) so you can target them by identity/ip/mac.",
+			),
+		);
+	}
+
 	return {
 		ok: true,
 		data: { count: neighbors.length, neighbors },
 		warnings,
-		tips: [],
+		tips,
 		meta: discoverMeta(operation, options),
 	};
 }
@@ -743,9 +802,23 @@ function renderDiscoverText(envelope: DiscoverEnvelope): string {
 		);
 	}
 	appendDiscoverWarnings(lines, envelope.warnings);
+	appendDiscoverTips(lines, envelope.tips);
 	return lines.join("\n");
 }
 
+function appendDiscoverTips(lines: string[], tips: readonly Tip[]): void {
+	if (tips.length === 0) {
+		return;
+	}
+	lines.push("Tips:");
+	for (const item of tips) {
+		lines.push(`  - [${item.code}] ${item.message}`);
+		if (item.fix) {
+			lines.push(`    fix: ${item.fix}`);
+		}
+	}
+}
+
 function appendDiscoverWarnings(
 	lines: string[],
 	warnings: readonly DevicesWarning[],