@indigoai-us/hq-cli 5.273.0 → 5.274.0

package/CHANGELOG.md

@@ -2,10 +2,50 @@
 
 ## [Unreleased]
 
+## [5.274.0] — 2026-09-28
+
+### Fixed
+
+- `hq lanes grant` and other senior-authorized actions treat a missing `senior`
+  key in valid session metadata as `user`; explicit non-user values still refuse
+  authorization with a reason.
+- Native Outpost message and resume routes now carry the owner's hire hierarchy,
+  authorize local-host resume contexts on their owner, and continue lane lookup
+  when another registered Outpost is unavailable.
+
+### Added
+
+- Guide interactive CLI users to their first work-bearing sync and confirm it
+  once, behind the `cli.first-sync-next-step` HQ flag.
+- Add `hq core commands --json` for the registered command catalog and guard the fast path, sibling references, and packaged assets.
+- Add a corpus recorder and differential runner for scaffold migration scripts.
+- Add `hq deploy comments list` and `read` for comments on apps in the caller's org.
+- Checkpoint ontology: behind `checkpoint.ontology.named-evidence` (off by
+  default), a knowledge link to the company's own company entity, or a
+  concept linked to its same-name project, needs evidence that names it as a
+  word. A name that only appears inside a path, domain, handle or tag, such as
+  `indigoai-us/hq` or `scope: company:indigo`, is rejected as
+  `unnamed_in_evidence` (CO-57).
+
+### Fixed
+
+- Add byte-for-byte checks for files fetched by `hq files get` and for
+  `company.yaml` after cloud demotion, using hq-core-staging's company seed.
+
+### Changed
+
+- Internal: moved the move, move-target and placement subcommands out of
+  `src/commands/lanes.ts`; no behaviour change.
+
 ## [5.273.0] — 2026-09-28
 
 ### Fixed
 
+- `hq doctor --fix` rechecks after each repair and applies newly found fixes
+  for up to three passes. It reports each repair's pass and lists every backup
+  restore command.
+- `hq doctor --fix --json` includes each repair's pass and backup, and its
+  restore command now undoes changes from every repair pass.
 - Wrapped merge commands now pass through both hold and review checks. If a
   merge command cannot be parsed, it is allowed with an unresolved repository
   when no enabled hold or review check applies.

package/README.md

@@ -7,6 +7,25 @@ npm install -g @indigoai-us/hq-cli
 hq --help
 ```
 
+## Deploy comments
+
+List comments left on an app in your current hq-deploy organization. Use the
+app's id or exact name; the CLI resolves it from the apps visible in that org.
+The list shows id, status, creation time, author display name, anchor mode and
+the first body line. `--status` accepts `open`, `resolved` or `all` (default).
+Use `--json` to print the API's comment objects with the `commentsEnabled`
+value.
+
+```bash
+hq deploy comments list <app> [--status open|resolved|all] [--json]
+hq deploy comments read <app> <commentId>
+```
+
+`read` prints the complete comment, including body, anchor, deploy id, status
+and timestamps. Reading works when comments are disabled on the app. The
+control-plane API requires the app owner or an org admin; comments are scoped
+to the caller's organization. Resolve/reopen commands are not included.
+
 ## Telemetry
 
 When you are signed in, `hq` may POST one `cli_session_started` event to
@@ -19,10 +38,14 @@ When you are signed in, `hq` may POST one `cli_session_started` event to
 - `consentBasis`: `disclosed` after the first-run notice, otherwise `no-consent`
 - `schemaVersion`: `1`
 - `properties.version`: the CLI version
+- for the optional first-sync guidance, `properties.step` (`first_sync_next_step`),
+  `properties.outcome` (`shown` or `followed`), and `properties.flagKey`
+  (`cli.first-sync-next-step`)
 
 The request is authenticated with your cached session token so the control
 plane can accept the event. The body does not include command names, arguments,
-timings, file contents, or secrets.
+timings, file contents, or secrets. The guidance fields are sent only when that
+optional feature is enabled and a person sees or follows its next step.
 
 The first signed-in interactive run (stdout is a TTY, and the command is not
 `--json`) prints this line once on stderr and records that it was shown under
@@ -32,6 +55,14 @@ The first signed-in interactive run (stdout is a TTY, and the command is not
 HQ sends a usage event when you run a signed-in command (CLI version and a timestamp, never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.
 ```
 
+When the optional first-sync guidance is enabled, the first interactive run that
+is about to send its fields prints this line once instead, and records it under
+`~/.hq/cli-telemetry-disclosed-first-sync-v1`:
+
+```
+HQ sends a usage event when you run a signed-in command (CLI version and a timestamp; when enabled, first-sync guidance shown or followed and the flag key cli.first-sync-next-step; never command names, file contents, or secrets) to improve the CLI. Set HQ_TELEMETRY=0 to turn this off.
+```
+
 Turn telemetry off:
 
 ```bash

package/dist/command-catalog.generated.d.ts

@@ -5458,6 +5458,18 @@ export declare const COMMAND_CATALOG: readonly [{
             }];
             readonly subcommands: readonly [];
         }];
+    }, {
+        readonly name: "commands";
+        readonly description: "List registered hq core commands as JSON";
+        readonly aliases: readonly [];
+        readonly hidden: true;
+        readonly usage: "[options]";
+        readonly arguments: readonly [];
+        readonly options: readonly [{
+            readonly flags: "--json";
+            readonly description: "Print the command catalog as JSON";
+        }];
+        readonly subcommands: readonly [];
     }];
 }, {
     readonly name: "search";
@@ -9472,6 +9484,66 @@ export declare const COMMAND_CATALOG: readonly [{
         }];
         readonly subcommands: readonly [];
     }];
+}, {
+    readonly name: "deploy";
+    readonly description: "Manage deployments in hq-deploy";
+    readonly aliases: readonly [];
+    readonly hidden: false;
+    readonly usage: "[options] [command]";
+    readonly arguments: readonly [];
+    readonly options: readonly [];
+    readonly subcommands: readonly [{
+        readonly name: "comments";
+        readonly description: "List and read comments on your deployed apps";
+        readonly aliases: readonly [];
+        readonly hidden: false;
+        readonly usage: "[options] [command]";
+        readonly arguments: readonly [];
+        readonly options: readonly [];
+        readonly subcommands: readonly [{
+            readonly name: "list";
+            readonly description: "List comments on an app in your org";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <app>";
+            readonly arguments: readonly [{
+                readonly name: "app";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "use this company instead of the active company";
+            }, {
+                readonly flags: "--json";
+                readonly description: "print the API comment array as JSON";
+            }, {
+                readonly flags: "--status <status>";
+                readonly description: "filter by open, resolved, or all";
+            }];
+            readonly subcommands: readonly [];
+        }, {
+            readonly name: "read";
+            readonly description: "Read a comment on an app in your org";
+            readonly aliases: readonly [];
+            readonly hidden: false;
+            readonly usage: "[options] <app> <commentId>";
+            readonly arguments: readonly [{
+                readonly name: "app";
+                readonly required: true;
+                readonly variadic: false;
+            }, {
+                readonly name: "commentId";
+                readonly required: true;
+                readonly variadic: false;
+            }];
+            readonly options: readonly [{
+                readonly flags: "--company <slug>";
+                readonly description: "use this company instead of the active company";
+            }];
+            readonly subcommands: readonly [];
+        }];
+    }];
 }, {
     readonly name: "staff";
     readonly description: "Staff-only commands (super-admin required)";

package/dist/command-catalog.generated.js

@@ -7040,6 +7040,21 @@ export const COMMAND_CATALOG = [
                         "subcommands": []
                     }
                 ]
+            },
+            {
+                "name": "commands",
+                "description": "List registered hq core commands as JSON",
+                "aliases": [],
+                "hidden": true,
+                "usage": "[options]",
+                "arguments": [],
+                "options": [
+                    {
+                        "flags": "--json",
+                        "description": "Print the command catalog as JSON"
+                    }
+                ],
+                "subcommands": []
             }
         ]
     },
@@ -12252,6 +12267,83 @@ export const COMMAND_CATALOG = [
             }
         ]
     },
+    {
+        "name": "deploy",
+        "description": "Manage deployments in hq-deploy",
+        "aliases": [],
+        "hidden": false,
+        "usage": "[options] [command]",
+        "arguments": [],
+        "options": [],
+        "subcommands": [
+            {
+                "name": "comments",
+                "description": "List and read comments on your deployed apps",
+                "aliases": [],
+                "hidden": false,
+                "usage": "[options] [command]",
+                "arguments": [],
+                "options": [],
+                "subcommands": [
+                    {
+                        "name": "list",
+                        "description": "List comments on an app in your org",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <app>",
+                        "arguments": [
+                            {
+                                "name": "app",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "use this company instead of the active company"
+                            },
+                            {
+                                "flags": "--json",
+                                "description": "print the API comment array as JSON"
+                            },
+                            {
+                                "flags": "--status <status>",
+                                "description": "filter by open, resolved, or all"
+                            }
+                        ],
+                        "subcommands": []
+                    },
+                    {
+                        "name": "read",
+                        "description": "Read a comment on an app in your org",
+                        "aliases": [],
+                        "hidden": false,
+                        "usage": "[options] <app> <commentId>",
+                        "arguments": [
+                            {
+                                "name": "app",
+                                "required": true,
+                                "variadic": false
+                            },
+                            {
+                                "name": "commentId",
+                                "required": true,
+                                "variadic": false
+                            }
+                        ],
+                        "options": [
+                            {
+                                "flags": "--company <slug>",
+                                "description": "use this company instead of the active company"
+                            }
+                        ],
+                        "subcommands": []
+                    }
+                ]
+            }
+        ]
+    },
     {
         "name": "staff",
         "description": "Staff-only commands (super-admin required)",

package/dist/command-registration-plan.d.ts

@@ -432,6 +432,18 @@ export declare const REGISTRATION_PLAN: readonly [{
     readonly parent: "program";
     readonly module: "./commands/report.js";
     readonly exportName: "registerReportCommand";
+}, {
+    readonly type: "group";
+    readonly root: "deploy";
+    readonly id: "deploy";
+    readonly name: "deploy";
+    readonly description: "Manage deployments in hq-deploy";
+}, {
+    readonly type: "registrar";
+    readonly root: "deploy";
+    readonly parent: "deploy";
+    readonly module: "./commands/deploy-comments.js";
+    readonly exportName: "registerDeployCommentsCommand";
 }, {
     readonly type: "group";
     readonly root: "staff";

package/dist/command-registration-plan.js

@@ -74,6 +74,8 @@ export const REGISTRATION_PLAN = [
     { type: "registrar", root: "daemon", parent: "program", module: "./commands/daemon.js", exportName: "registerDaemonCommand", hidden: true },
     { type: "registrar", root: "bot", parent: "program", module: "./commands/bot.js", exportName: "registerBotCommand" },
     { type: "registrar", root: "report", parent: "program", module: "./commands/report.js", exportName: "registerReportCommand" },
+    { type: "group", root: "deploy", id: "deploy", name: "deploy", description: "Manage deployments in hq-deploy" },
+    { type: "registrar", root: "deploy", parent: "deploy", module: "./commands/deploy-comments.js", exportName: "registerDeployCommentsCommand" },
     // onboarding-test-accounts US-007 — super-admin staff CLI wrappers over the
     // hq-pro admin surface. New wrappers land under this group; the reset
     // command mirrors POST /v1/admin/test-account/reset.

package/dist/commands/cloud.js

@@ -21,6 +21,7 @@ import { DEFAULT_HQ_ROOT, ensureCognitoToken, buildVaultConfig, } from "../utils
 import { resolveUploadAuthor } from "../utils/upload-author.js";
 import { companyFolderExceedsThreshold, emitNarrowHint, isStrictRefusal, resolveBannerLevel, resolveNarrowHintPresentationLevel, resolveNarrowHintMinBytes, } from "../lib/narrow-hint-banner.js";
 import { beginSyncHealthReport, } from "../utils/client-health.js";
+import { recordFirstWorkBearingSync } from "../lib/first-sync-next-step.js";
 /**
  * Terminal-failure signal for the sync fanout runners. The runners
  * (`runPushAll` / `runPullAll` / `runPullPersonal` / `runNowSingle` /
@@ -882,6 +883,11 @@ export function registerCloudCommands(program) {
                 await syncHealth.failed();
                 process.exit(1);
             }
+            recordFirstWorkBearingSync({
+                filesUploaded: result.filesUploaded,
+                filesDeleted: result.filesDeleted,
+                aborted: result.aborted,
+            });
             if (result.filesExcludedByScope > 0) {
                 log(chalk.yellow(`\n⚠ Pushed ${result.filesUploaded} file(s) (${formatBytes(result.bytesUploaded)}, ` +
                     `${result.filesSkipped} skipped, ${result.filesExcludedByScope} scope-excluded)`));
@@ -1026,6 +1032,10 @@ export function registerCloudCommands(program) {
                 await syncHealth.failed();
                 process.exit(1);
             }
+            recordFirstWorkBearingSync({
+                filesDownloaded: result.filesDownloaded,
+                aborted: result.aborted,
+            });
             console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
             // Emit the hint banner after success so it appears alongside the
             // summary line. Mirrors the wiring in runPullAll and runNowSingle.
@@ -1325,6 +1335,14 @@ async function runPullAll(hqRoot, onConflict, modeAllOverride, skipPersonal, for
         `(${formatBytes(result.bytesDownloaded)}) across ${result.attempted} ` +
         `target(s); ${result.conflicts} conflict(s); ${errored} error(s)`;
     console.log(errored > 0 ? chalk.yellow(summary) : chalk.green(summary));
+    for (const row of result.perCompany) {
+        if (row.result && !row.error) {
+            recordFirstWorkBearingSync({
+                filesDownloaded: row.result.filesDownloaded,
+                aborted: row.result.aborted,
+            });
+        }
+    }
     if (errored > 0)
         throw new SyncExitError(1);
 }
@@ -1355,6 +1373,10 @@ export async function runPullPersonal(hqRoot, onConflict) {
             throw new SyncExitError(1);
         }
         console.log(chalk.green(`\n✓ Pulled ${result.filesDownloaded} file(s) (${formatBytes(result.bytesDownloaded)}, ${result.filesSkipped} skipped, ${result.conflicts} conflicts)`));
+        recordFirstWorkBearingSync({
+            filesDownloaded: result.filesDownloaded,
+            aborted: result.aborted,
+        });
     }
     catch (err) {
         if (err instanceof SyncExitError)
@@ -1454,6 +1476,15 @@ async function runPushAll(hqRoot, message, onConflict, skipPersonal) {
     console.log(errored > 0 || result.filesExcludedByScope > 0
         ? chalk.yellow(summary)
         : chalk.green(summary));
+    for (const row of result.perCompany) {
+        if (row.result && !row.error) {
+            recordFirstWorkBearingSync({
+                filesUploaded: row.result.filesUploaded,
+                filesDeleted: row.result.filesDeleted,
+                aborted: row.result.aborted,
+            });
+        }
+    }
     for (const row of result.perCompany) {
         const excluded = row.result?.filesExcludedByScope ?? 0;
         for (const line of scopeExcludedLines(excluded, row.prefixSet)) {
@@ -1544,6 +1575,11 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             console.log(chalk.yellow("\n⚠ Sync now aborted on push leg; pull skipped."));
             throw new SyncExitError(1);
         }
+        recordFirstWorkBearingSync({
+            filesUploaded: pushResult.filesUploaded,
+            filesDeleted: pushResult.filesDeleted,
+            aborted: pushResult.aborted,
+        });
         // US-011: resolve membership sync-config so we can either nudge an
         // all-mode owner or refuse the pull when strict-mode is on. Skipped
         // for personal targets (personal vault has no membership row) and
@@ -1635,6 +1671,10 @@ async function runNowSingle(hqRoot, company, personal, message, onConflict, mode
             console.log(chalk.yellow("\n⚠ Sync now finished with pull leg aborted."));
             throw new SyncExitError(1);
         }
+        recordFirstWorkBearingSync({
+            filesDownloaded: pullResult.filesDownloaded,
+            aborted: pullResult.aborted,
+        });
         // Emit the hint banner after a successful pull so it appears at the
         // bottom of the summary rather than mid-stream. Size-gated: only a large
         // local folder is nudged.

package/dist/commands/core-checkpoint.js

@@ -17,6 +17,7 @@ import { toHqStateWriteError } from "../utils/hq-state-write-error.js";
 import { checkpointStampWriteErrorFor, isCheckpointStampWriteError, } from "../utils/checkpoint-stamp-write-error.js";
 import { readBackendPreference } from "../lib/checkpoint-ontology/plan.js";
 import { resolveOntologyCompany } from "../lib/checkpoint-ontology/company.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
 const DEFAULT_TRIGGER = "stop-gate";
 const BACKENDS = new Set(["auto", "claude", "codex", "grok", "none"]);
 // Pinned by operator directive 2026-09-15; change defaults here deliberately.
@@ -1175,7 +1176,7 @@ function reportUsage(error) {
 }
 /** Attach the native checkpoint command to the hidden `hq core` group. */
 export function registerCoreCheckpointCommand(core) {
-    core
+    const checkpoint = core
         .command("checkpoint")
         .description("Record an end-of-turn checkpoint and start HQ maintenance")
         .option("--summary <text>", "1–2 sentence outcome summary")
@@ -1211,5 +1212,6 @@ export function registerCoreCheckpointCommand(core) {
             throw error;
         }
     });
+    describeCoreCommand(checkpoint, { execution: "native", root: "live" });
 }
 //# sourceMappingURL=core-checkpoint.js.map

package/dist/commands/core-command-catalog.d.ts

@@ -0,0 +1,32 @@
+import type { Command } from "commander";
+export type CoreCommandExecution = "native" | "bundled-shell" | "bundled-node";
+export type CoreCommandRoot = "live" | "source" | "cwd";
+export type CoreCommandListingEntry = {
+    name: string;
+    execution: CoreCommandExecution;
+    asset?: string;
+    root: CoreCommandRoot;
+};
+type CoreCommandMetadata = (Omit<CoreCommandListingEntry, "name"> & {
+    entries?: never;
+}) | {
+    entries: readonly CoreCommandListingEntry[];
+};
+/** Mark the exact Commander registration that supplies a catalog row. */
+export declare function describeCoreCommand(command: Command, metadata: CoreCommandMetadata): Command;
+/**
+ * Reflect executable leaf commands from the Commander tree. Asset-backed rows
+ * are attached at the point where core.ts registers each table entry, so the
+ * JSON output cannot drift into a second, hand-maintained command list.
+ */
+export declare function registeredCoreCommandListing(core: Command): CoreCommandListingEntry[];
+export declare function fastScaffoldListingMismatches(listing: readonly CoreCommandListingEntry[], fastScripts: readonly {
+    name: string;
+    asset: string;
+}[]): string[];
+export declare function assertFastScaffoldListingParity(listing: readonly CoreCommandListingEntry[], fastScripts: readonly {
+    name: string;
+    asset: string;
+}[]): void;
+export {};
+//# sourceMappingURL=core-command-catalog.d.ts.map

package/dist/commands/core-command-catalog.js

@@ -0,0 +1,58 @@
+const metadataByCommand = new WeakMap();
+/** Mark the exact Commander registration that supplies a catalog row. */
+export function describeCoreCommand(command, metadata) {
+    metadataByCommand.set(command, metadata);
+    return command;
+}
+/**
+ * Reflect executable leaf commands from the Commander tree. Asset-backed rows
+ * are attached at the point where core.ts registers each table entry, so the
+ * JSON output cannot drift into a second, hand-maintained command list.
+ */
+export function registeredCoreCommandListing(core) {
+    const entries = [];
+    const visit = (parent, parents) => {
+        for (const command of parent.commands) {
+            const path = [...parents, command.name()].join(" ");
+            if (command.commands.length > 0) {
+                visit(command, [...parents, command.name()]);
+                continue;
+            }
+            const metadata = metadataByCommand.get(command);
+            if (!metadata) {
+                throw new Error(`hq core command ${path} has no listing metadata`);
+            }
+            const described = metadata.entries
+                ? metadata.entries
+                : [{
+                        name: path,
+                        execution: metadata.execution,
+                        ...(metadata.asset ? { asset: metadata.asset } : {}),
+                        root: metadata.root,
+                    }];
+            entries.push(...described);
+        }
+    };
+    visit(core, []);
+    return entries.sort((a, b) => a.name.localeCompare(b.name));
+}
+export function fastScaffoldListingMismatches(listing, fastScripts) {
+    const mismatches = [];
+    for (const fast of fastScripts) {
+        const listed = listing.find((entry) => entry.name === fast.name);
+        if (!listed) {
+            mismatches.push(`${fast.name} is missing from hq core commands`);
+        }
+        else if (listed.asset !== fast.asset) {
+            mismatches.push(`${fast.name} lists ${listed.asset ?? "no asset"}, fast path uses ${fast.asset}`);
+        }
+    }
+    return mismatches;
+}
+export function assertFastScaffoldListingParity(listing, fastScripts) {
+    const mismatches = fastScaffoldListingMismatches(listing, fastScripts);
+    if (mismatches.length > 0) {
+        throw new Error(mismatches.join("\n"));
+    }
+}
+//# sourceMappingURL=core-command-catalog.js.map

package/dist/commands/core-ontology.js

@@ -10,6 +10,7 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
 import { resolveLiveRoot } from "../utils/hq-roots.js";
+import { describeCoreCommand } from "./core-command-catalog.js";
 import { readLanesRegistryFlag } from "../lib/lanes/registry-flag.js";
 import { MULTI_WRITER_FLAG, planOntologyRun, } from "../lib/checkpoint-ontology/plan.js";
 import { applyOntologyRun, ApplyError } from "../lib/checkpoint-ontology/apply.js";
@@ -205,7 +206,7 @@ export function registerCoreOntologyCommand(core) {
         .command("ontology")
         .description("Checkpoint ontology steps run by the checkpoint sibling (gated by checkpoint.ontology)");
     const rootFor = (options) => resolveLiveRoot({ hqRoot: options.hqRoot ?? core.opts().hqRoot });
-    ontology
+    const plan = ontology
         .command("plan")
         .description("Check the flag and list the changed company files for this checkpoint run")
         .option("--run-dir <path>", "checkpoint sibling run directory holding payload.json")
@@ -218,7 +219,8 @@ export function registerCoreOntologyCommand(core) {
             fail(error);
         }
     });
-    ontology
+    describeCoreCommand(plan, { execution: "native", root: "live" });
+    const duplicates = ontology
         .command("duplicates")
         .description("List same-type entities whose names collide, with a proposed survivor (read-only)")
         .requiredOption("--company <slug>", "company to scan")
@@ -232,7 +234,8 @@ export function registerCoreOntologyCommand(core) {
             fail(error);
         }
     });
-    ontology
+    describeCoreCommand(duplicates, { execution: "native", root: "live" });
+    const mergeCopies = ontology
         .command("merge-copies")
         .description("Merge '<name> N.md' entity copies into their original, then delete them from the vault (dry run by default)")
         .requiredOption("--company <slug>", "company to change")
@@ -249,7 +252,8 @@ export function registerCoreOntologyCommand(core) {
             fail(error);
         }
     });
-    ontology
+    describeCoreCommand(mergeCopies, { execution: "native", root: "live" });
+    const apply = ontology
         .command("apply")
         .description("Validate the run's entity candidates and write them to the payload company")
         .option("--run-dir <path>", "checkpoint sibling run directory holding the plan and candidates")
@@ -262,5 +266,6 @@ export function registerCoreOntologyCommand(core) {
             fail(error);
         }
     });
+    describeCoreCommand(apply, { execution: "native", root: "live" });
 }
 //# sourceMappingURL=core-ontology.js.map

package/dist/commands/core.d.ts

@@ -68,6 +68,8 @@ export type ScaffoldCommand = ScaffoldAsset & {
 export type RebuildIndexTarget = {
     /** Rebuild target — `hq core rebuild-index <target>`. */
     target: string;
+    /** Legacy scaffold companion, retained for compatibility and packaging. */
+    asset: string;
     /** Native renderer identifier. */
     renderer: IndexTarget;
     /** One-line summary, shown in `hq core --help`. */
@@ -87,6 +89,8 @@ export type NativeScaffoldCommand = ScaffoldAsset & {
 };
 type NativeUtilityCommand = {
     name: string;
+    /** Retained loose-file companion for old scaffold callers. */
+    asset: string;
     root: ScaffoldRoot;
     summary: string;
     run: (args: string[], context: {