agentera 3.0.0-dev.41 → 3.0.0-dev.47

package/dist/cli/contracts/orientationState.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=orientationState.js.map

package/dist/cli/dispatch/argvParser.js

@@ -30,4 +30,3 @@ export function makeArgvValueReader(argv, getIndex, setIndex) {
         return null;
     };
 }
-//# sourceMappingURL=argvParser.js.map

package/dist/cli/dispatch/check.js

@@ -1,7 +1,7 @@
 import { cmdLint } from "../commands/lint.js";
 import { cmdCompact } from "../commands/compact.js";
 import { cmdSchema } from "../commands/schema.js";
-import { cmdValidate, cmdValidateCapability, cmdValidateCapabilityContract, cmdValidateArtifact, cmdValidateState, isDelegatedValidateFamily, } from "../commands/validate.js";
+import { cmdValidate, cmdValidateCapability, cmdValidateCapabilityContract, cmdValidateArtifact, cmdValidateState, isDelegatedValidateFamily, VALIDATE_FAMILY_NAMES, cmdValidateActivationConjunction, } from "../commands/validate.js";
 import { makeArgvValueReader } from "./argvParser.js";
 import { asEnvelopeFormat, classifyParseError, detectTopLevelFormat } from "./shared.js";
 import { emitInvalidInput } from "../errors.js";
@@ -270,17 +270,7 @@ export function runValidate(argv, io, prog) {
             body: {
                 class: "missing_argument",
                 message: "the following arguments are required: validate_family",
-                valid_values: [
-                    "cross-capability",
-                    "app-home-contract",
-                    "vocabularyAuthority",
-                    "selfAudit",
-                    "release-metadata",
-                    "capability",
-                    "capability-contract",
-                    "artifact",
-                    "state",
-                ],
+                valid_values: [...VALIDATE_FAMILY_NAMES],
                 example: "agentera check validate cross-capability",
             },
         });
@@ -302,6 +292,9 @@ export function runValidate(argv, io, prog) {
         if (family === "capability-contract") {
             return cmdValidateCapabilityContract({ format }, io);
         }
+        if (family === "activation-conjunction") {
+            return cmdValidateActivationConjunction(io);
+        }
         if (family === "artifact") {
             if (artifactFlag === null) {
                 return emitInvalidInput(io, {
@@ -326,17 +319,7 @@ export function runValidate(argv, io, prog) {
             body: {
                 class: "unsupported_target",
                 message: `unsupported validate family '${family}'; valid families are listed in valid_values.`,
-                valid_values: [
-                    "cross-capability",
-                    "app-home-contract",
-                    "vocabularyAuthority",
-                    "selfAudit",
-                    "release-metadata",
-                    "capability",
-                    "capability-contract",
-                    "artifact",
-                    "state",
-                ],
+                valid_values: [...VALIDATE_FAMILY_NAMES],
             },
         });
     }
@@ -387,4 +370,3 @@ export function runSchema(argv, io, prog) {
         });
     }
 }
-//# sourceMappingURL=check.js.map

package/dist/cli/dispatch/commands.js

@@ -1,4 +1,5 @@
 import { CAPABILITY_ROUTING_NAMES } from "../commands/capability.js";
+import { DIAGNOSTIC_TOP_LEVEL_COMMANDS } from "./projections.js";
 /**
  * Top-level commands routed by `dispatch/main` (includes migration aliases still
  * accepted at the CLI surface).
@@ -12,7 +13,6 @@ export const DISPATCHER_TOP_LEVEL_COMMANDS = [
     "verify",
     "report",
     "stats",
-    "hook",
     "schema",
     "lint",
     "check",
@@ -20,8 +20,8 @@ export const DISPATCHER_TOP_LEVEL_COMMANDS = [
     "query",
     "compact",
     "validate",
+    "route",
     ...CAPABILITY_ROUTING_NAMES,
 ];
 /** Set view for doctor in-process CLI probe checks. */
-export const DISPATCHER_COMMANDS = new Set(DISPATCHER_TOP_LEVEL_COMMANDS);
-//# sourceMappingURL=commands.js.map
+export const DISPATCHER_COMMANDS = new Set(DIAGNOSTIC_TOP_LEVEL_COMMANDS);

package/dist/cli/dispatch/index.js

@@ -1,19 +1,18 @@
-import { runEntityMigrate } from "../commands/entityMigrate.js";
 import { CAPABILITY_ROUTING_NAMES } from "../commands/capability.js";
 import { runRouteEvaluation, runRouteReceipt, runRouteRequest } from "../commands/route.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
 import { printCommandHelp, printStateHelp, printTopLevelHelp, splitHelpArgs, stateCommandNames, } from "../help.js";
 import { compactModeOf, runCompact, runDurability, runLint, runSchema, runValidate, } from "./check.js";
 import { runQuery, runState } from "./state.js";
 import { entityListFamily } from "../../state/entityRetrievalHelp.js";
 import { ENTITY_LIST_RUNTIME_FAMILIES, runtimeEntityFamiliesForCommand } from "../../state/entityListRuntimeRegistry.js";
 import { runCapability, runPrime } from "./prime.js";
-import { runAppHome, runDoctor, runGate, runHook, readStdin, runReport, runUpgrade, runUsage, runVerify, runVersion, } from "./lifecycle.js";
+import { runAppHome, runDoctor, runGate, runReport, runUpgrade, runUsage, runVerify, runVersion, } from "./lifecycle.js";
 import { detectTopLevelFormat, emitDeprecationAlias } from "./shared.js";
 import { emitInvalidInput } from "../errors.js";
 import { verbsForArtifact } from "../../state/write/operations.js";
 import { REMOVED_TOP_LEVEL_CORRECTIONS } from "../commands/schema.js";
 import { enforceCompletedEntityCutover, migrationProject, requestedMigrationFailureFormat, requiresCompletedEntityCutover, } from "../migrationRequired.js";
-import { isProjectBoundHook, parseProjectHookInput } from "../../hooks/projectHookInput.js";
 export function main(argv, io = {}) {
     const err = io.err ?? ((t) => process.stderr.write(t));
     const out = io.out ?? ((t) => process.stdout.write(t));
@@ -60,14 +59,11 @@ export function main(argv, io = {}) {
             },
         });
     }
-    let projectHookInput;
-    const hookName = rest[0] ?? "";
-    if (command === "hook" && isProjectBoundHook(hookName)) {
-        const raw = io.stdin ? io.stdin() : readStdin();
-        projectHookInput = parseProjectHookInput(hookName, raw);
-    }
-    if (requiresCompletedEntityCutover(args)) {
-        const failure = enforceCompletedEntityCutover(projectHookInput?.projectRoot ?? migrationProject(args), requestedMigrationFailureFormat(args), io);
+    // Retained-reference validation audits package source, not project state. It
+    // must report its source-checkout boundary before project migration checks.
+    const sourceOnlyReferenceValidation = args[0] === "check" && args[1] === "validate" && ["retained-references", "activation-conjunction"].includes(args[2] ?? "");
+    if (!sourceOnlyReferenceValidation && requiresCompletedEntityCutover(args)) {
+        const failure = enforceCompletedEntityCutover(migrationProject(args), requestedMigrationFailureFormat(args), io);
         if (failure !== null)
             return failure;
     }
@@ -93,26 +89,6 @@ export function main(argv, io = {}) {
         case "stats":
             emitDeprecationAlias("stats", "report", err);
             return runReport(rest, io, "agentera stats");
-        case "hook": {
-            const name = rest[0];
-            if (!name) {
-                return emitInvalidInput(io, {
-                    format: "text",
-                    body: {
-                        class: "missing_argument",
-                        message: "the following arguments are required: hook_name",
-                        valid_values: [
-                            "session-start",
-                            "session-stop",
-                            "cursor-session-start",
-                            "cursor-pre-tool-use",
-                            "validate-artifact",
-                        ],
-                    },
-                });
-            }
-            return runHook(name, rest.slice(1), io, projectHookInput);
-        }
         case "schema":
             return runSchema(rest, io, "agentera schema");
         case "lint":
@@ -175,8 +151,6 @@ export function main(argv, io = {}) {
             }
             if (sub === "query")
                 return runQuery(rest.slice(1), io, "agentera state query");
-            if (sub === "migrate" && rest[1] === "entities")
-                return runEntityMigrate(rest.slice(2), io);
             if (runtimeEntityFamiliesForCommand(sub).length > 0 || verbsForArtifact(sub).some((verb) => verb === rest[1]))
                 return runState(sub, rest.slice(1), io, `agentera state ${sub}`);
             return emitInvalidInput(io, {
@@ -206,8 +180,8 @@ export function main(argv, io = {}) {
                     class: "unsupported_target",
                     message: "route requires the request subcommand",
                     valid_values: ["request", "receipt", "evaluate"],
-                    syntax: "agentera route <request|receipt> --input PATH --format json | agentera route evaluate --format json",
-                    example: "agentera route receipt --input - --format json",
+                    syntax: `${preCutoverCommand("route <request|receipt> --input PATH --format json")} | ${preCutoverCommand("route evaluate --format json")}`,
+                    example: preCutoverCommand("route receipt --input - --format json"),
                 },
             });
         case "compact":
@@ -231,4 +205,3 @@ export function main(argv, io = {}) {
             });
     }
 }
-//# sourceMappingURL=index.js.map

package/dist/cli/dispatch/lifecycle.js

@@ -1,4 +1,3 @@
-import fsForHooks from "node:fs";
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -11,11 +10,7 @@ import { cmdReport } from "../commands/report.js";
 import { runGlossaryAdviceCommand } from "../commands/glossaryAdvice.js";
 import { runPersonalGlossaryCommand } from "../commands/personalGlossary.js";
 import { runProfileGroundingCommand } from "../commands/profileGrounding.js";
-import { runSessionStart } from "../../hooks/sessionStart.js";
-import { runSessionStop } from "../../hooks/sessionStop.js";
-import { runCursorSessionStart } from "../../hooks/cursorSessionStart.js";
-import { runCursorPreToolUse } from "../../hooks/cursorPreToolUse.js";
-import { HookCliAdapter } from "../../hooks/validateArtifact/index.js";
+import { preCutoverCommand } from "../preCutoverCommand.js";
 import { usageMain } from "../../analytics/usageStats.js";
 import { validatePathValue } from "../argvalidate.js";
 import { printAppHomeHelp, printDoctorHelp, printUpgradeHelp, wantsHelp } from "../help.js";
@@ -25,7 +20,7 @@ import { asEnvelopeFormat, classifyParseError, detectTopLevelFormat, emitDepreca
 import { emitInvalidInput } from "../errors.js";
 import { migrationProject } from "../migrationRequired.js";
 import { fullEntityUpgradeCommand } from "../../upgrade/upgradeCommands.js";
-import { nativeResourceCleanupIds } from "../../runtime/nativeResourceCleanup.js";
+import { nativeResourceCleanupIds, resolveNativeResourceCleanupId } from "../../runtime/nativeResourceCleanup.js";
 function rejectUnsupportedUpgradeFlag(io, format, message, recovery) {
     return emitInvalidInput(io, {
         format: asEnvelopeFormat(format),
@@ -115,6 +110,7 @@ export function runDoctor(argv, io, prog) {
         project: null,
         expectedVersion: null,
         expectCommand: [],
+        retiredResource: null,
         smoke: false,
         allowLiveModel: false,
         format: "text",
@@ -137,6 +133,8 @@ export function runDoctor(argv, io, prog) {
             args.expectedVersion = v;
         else if ((v = value("--expect-command")) !== null)
             args.expectCommand.push(v);
+        else if ((v = value("--retired-resource")) !== null)
+            args.retiredResource = v;
         else if ((v = value("--format")) !== null) {
             if (v !== "text" && v !== "json") {
                 return emitInvalidInput(io, {
@@ -177,50 +175,6 @@ export function runDoctor(argv, io, prog) {
         });
     }
 }
-export function readStdin() {
-    try {
-        return fsForHooks.readFileSync(0, "utf8");
-    }
-    catch {
-        return "";
-    }
-}
-export function runHook(name, argv, io, projectInput) {
-    const err = io.err ?? ((t) => process.stderr.write(t));
-    const raw = projectInput?.raw ?? (io.stdin ? io.stdin() : readStdin());
-    // Each hook owns its own stdout newline convention; do not wrap stdout here.
-    switch (name) {
-        case "session-start":
-            return runSessionStart(projectInput ?? raw, { out: io.out, err: io.err });
-        case "session-stop":
-            return runSessionStop(projectInput ?? raw);
-        case "cursor-session-start":
-            return runCursorSessionStart(projectInput ?? raw, { out: io.out, err: io.err });
-        case "cursor-pre-tool-use":
-            return runCursorPreToolUse(raw);
-        case "validate-artifact": {
-            const [rc, violations] = new HookCliAdapter().run(raw, null);
-            for (const v of violations)
-                err(`${v}\n`);
-            return rc;
-        }
-        default:
-            return emitInvalidInput(io, {
-                format: "text",
-                body: {
-                    class: "unsupported_target",
-                    message: `unknown hook '${name}'`,
-                    valid_values: [
-                        "session-start",
-                        "session-stop",
-                        "cursor-session-start",
-                        "cursor-pre-tool-use",
-                        "validate-artifact",
-                    ],
-                },
-            });
-    }
-}
 export function runUsage(argv, io, prog) {
     const realOut = io.out ?? ((t) => process.stdout.write(t));
     const realErr = io.err ?? ((t) => process.stderr.write(t));
@@ -341,7 +295,8 @@ export function runUpgrade(argv, io, prog) {
         }
         else if ((v = value("--legacy-cleanup")) !== null) {
             const validValues = nativeResourceCleanupIds();
-            if (!validValues.includes(v)) {
+            const selectedResource = resolveNativeResourceCleanupId(v);
+            if (!selectedResource) {
                 return emitInvalidInput(io, {
                     format: asEnvelopeFormat(args.format),
                     body: {
@@ -351,7 +306,7 @@ export function runUpgrade(argv, io, prog) {
                     },
                 });
             }
-            args.legacyCleanup = v;
+            args.legacyCleanup = selectedResource.id;
         }
         else if ((v = value("--only")) !== null) {
             if (v !== "artifacts" && v !== "runtime" && v !== "cleanup") {
@@ -495,7 +450,7 @@ export function runReport(argv, io, prog) {
                     class: "unsupported_target",
                     message: "glossary-advice has no stats alias",
                     valid_values: ["report glossary-advice"],
-                    recovery: "Run agentera report glossary-advice --input - --format json; no state was changed.",
+                    recovery: `Run ${preCutoverCommand("report glossary-advice --input - --format json")}; no state was changed.`,
                 },
             });
         }
@@ -509,7 +464,7 @@ export function runReport(argv, io, prog) {
                     class: "unsupported_target",
                     message: "profile-grounding has no stats alias",
                     valid_values: ["report profile-grounding"],
-                    recovery: "Run agentera report profile-grounding --format json; no profile bytes were changed.",
+                    recovery: `Run ${preCutoverCommand("report profile-grounding --format json")}; no profile bytes were changed.`,
                 },
             });
         }
@@ -523,7 +478,7 @@ export function runReport(argv, io, prog) {
                     class: "unsupported_target",
                     message: "profile-glossary has no stats alias",
                     valid_values: ["report profile-glossary"],
-                    recovery: "Run agentera report profile-glossary with the same --input; no profile bytes were changed.",
+                    recovery: `Run ${preCutoverCommand("report profile-glossary --input PATH --format json")} with the same input; no profile bytes were changed.`,
                 },
             });
         }
@@ -695,4 +650,3 @@ export function runVersion(argv, io) {
     }
     return 0;
 }
-//# sourceMappingURL=lifecycle.js.map

package/dist/cli/dispatch/prime.js

@@ -137,4 +137,3 @@ export function runPrime(command, argv, io, prog) {
         });
     }
 }
-//# sourceMappingURL=prime.js.map

package/dist/cli/dispatch/projections.js

@@ -0,0 +1,17 @@
+/**
+ * Independent production projections of the accepted top-level command set.
+ * They intentionally do not import the dispatcher inventory: activation must
+ * detect drift in diagnostics, packaged schema, or public instructions.
+ */
+export const DIAGNOSTIC_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);
+export const SCHEMA_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);
+export const HELP_TOP_LEVEL_COMMANDS = Object.freeze([
+    "prime", "app-home", "doctor", "usage", "upgrade", "verify", "report", "stats", "schema", "lint", "check", "state", "query", "compact", "validate", "route",
+    "vision", "discuss", "research", "plan", "build", "optimize", "audit", "document", "profile", "design", "orchestrate",
+]);

package/dist/cli/dispatch/shared.js

@@ -61,4 +61,3 @@ export function detectTopLevelFormat(args) {
     }
     return "text";
 }
-//# sourceMappingURL=shared.js.map

package/dist/cli/dispatch/state.js

@@ -138,4 +138,3 @@ export function runQuery(argv, io, prog) {
         });
     }
 }
-//# sourceMappingURL=state.js.map

package/dist/cli/dispatch.js

@@ -1,2 +1 @@
 export { main } from "./dispatch/index.js";
-//# sourceMappingURL=dispatch.js.map

package/dist/cli/errors.js

@@ -50,4 +50,3 @@ export function emitInvalidInput(io, opts) {
     err(lines.join("\n") + "\n");
     return opts.exitCode ?? INVALID_INPUT_EXIT_CODE;
 }
-//# sourceMappingURL=errors.js.map

package/dist/cli/help.js

@@ -1,25 +1,16 @@
 import { CAPABILITY_ROUTING_NAMES } from "./commands/capability.js";
 import { verbsForArtifact, WRITABLE_ARTIFACTS } from "../state/write/operations.js";
-import { entityMigrateHelp } from "./commands/entityMigrate.js";
 import { personalGlossaryOutputContract } from "../registries/glossaryEntryContract.js";
+import { describeRouteReceipt } from "../registries/hybridRoute.js";
+import { advertisedValidateFamilyNames } from "./commands/validate.js";
 import { entityListFamilies, entityRetrievalFamilyForHelpArgs } from "../state/entityRetrievalHelp.js";
-const TOP_LEVEL = [
-    "prime",
-    "schema",
-    "route",
-    "state",
-    ...CAPABILITY_ROUTING_NAMES,
-    "upgrade",
-    "app-home",
-    "doctor",
-    "report",
-    "check",
-];
+import { preCutoverCommand } from "./preCutoverCommand.js";
+import { HELP_TOP_LEVEL_COMMANDS } from "./dispatch/projections.js";
 function lines(title, items) {
     return [title, ...items.map((item) => `  ${item}`), ""];
 }
 export function printTopLevelHelp() {
-    const choices = TOP_LEVEL.join(",");
+    const choices = HELP_TOP_LEVEL_COMMANDS.join(",");
     const plans = entityListFamilies().find(({ key }) => key === "plans");
     const planListExample = `agentera state ${plans.commandTokens.join(" ")} list --format json`;
     return [
@@ -48,7 +39,12 @@ export function printTopLevelHelp() {
         "  -h, --help          show this help message and exit",
         "  --version           print the installed Agentera CLI version and exit",
         "",
-        `Examples: agentera prime; ${planListExample}; agentera check verify eval skills --dry-run; agentera report refresh --dry-run`,
+        [
+            `Examples: ${preCutoverCommand("prime --context status --format json")}`,
+            `  ${preCutoverCommand(planListExample.slice("agentera ".length))}`,
+            `  ${preCutoverCommand("check verify eval skills --dry-run")}`,
+            `  ${preCutoverCommand("report refresh --dry-run")}`,
+        ].join("\n"),
     ].join("\n");
 }
 export function printUpgradeHelp() {
@@ -82,7 +78,8 @@ export function printUpgradeHelp() {
         "active integration:",
         "  Agentera uses the shared skill at ~/.agents/skills/agentera plus the CLI.",
         "  Current runtime selectors and native plugin, hook, agent, command, descriptor, and marketplace writes are retired.",
-        "  Native resource cleanup remains explicit: agentera upgrade --legacy-cleanup RESOURCE_ID --dry-run|--yes",
+        `  Native resource cleanup preview: ${preCutoverCommand("upgrade --legacy-cleanup RESOURCE_ID --dry-run")}`,
+        `  Native resource cleanup apply:   ${preCutoverCommand("upgrade --legacy-cleanup RESOURCE_ID --yes")}`,
     ].join("\n");
 }
 export function printAppHomeHelp() {
@@ -101,7 +98,7 @@ export function printAppHomeHelp() {
 export function printDoctorHelp() {
     return [
         "usage: agentera doctor [-h] [--install-root PATH] [--home HOME] [--project PROJECT]",
-        "                       [--expected-version VERSION] [--expect-command CMD]",
+        "                       [--expected-version VERSION] [--expect-command CMD] [--retired-resource ID]",
         "                       [--smoke] [--allow-live-model] [--format {text,json}]",
         "",
         "options:",
@@ -111,11 +108,12 @@ export function printDoctorHelp() {
         "  --project PROJECT       Project directory context",
         "  --expected-version VER  Expected app files version",
         "  --expect-command CMD    Required CLI command probe; may be repeated",
+        "  --retired-resource ID   Read-only exact retired-resource diagnostic preview",
         "  --smoke                 Run bounded offline smoke checks (no live model calls by default)",
         "  --allow-live-model      Record permission for future live model smoke probes",
         "  --format {text,json}    Structured output format",
         "",
-        "Reports read-only app, project-state, shared-skill, and CLI evidence.",
+        "Reports read-only app, project-state, shared-skill, and CLI evidence, plus retired-resource diagnostics.",
     ].join("\n");
 }
 function recordFamilyReadSection(command) {
@@ -139,8 +137,6 @@ function recordFamilyReadSection(command) {
 }
 export function printStateHelp(sub) {
     const stateCommands = stateCommandNames();
-    if (sub === "migrate")
-        return entityMigrateHelp();
     if (sub === "plan") {
         return [
             ...recordFamilyReadSection("plan"),
@@ -203,6 +199,7 @@ export function printStateHelp(sub) {
     if (sub === "todo") {
         return [
             ...recordFamilyReadSection("todo"),
+            "       agentera state todo activate|repair --dry-run|--effect-sha256 SHA256 --yes --format json",
             "       agentera state todo create --input TODO.yaml --format json",
             "       agentera state todo update --id ID --input TODO-PATCH.yaml --format json",
             "       agentera state todo set-severity --id ID --severity LEVEL --reason TEXT --date YYYY-MM-DD --format json",
@@ -338,7 +335,6 @@ export function stateCommandNames() {
     return [...new Set([
             ...entityListFamilies().map(({ commandTokens }) => commandTokens[0]),
             ...WRITABLE_ARTIFACTS,
-            "migrate",
             "query",
         ])];
 }
@@ -351,6 +347,16 @@ export function printCheckHelp(sub) {
             "use the stable Python line for smoke maintainer harnesses.",
         ].join("\n");
     }
+    if (sub === "validate") {
+        return [
+            "usage: agentera check validate [-h] VALIDATE_FAMILY [options]",
+            "",
+            "Validate capabilities, state, and retained repository contracts.",
+            "",
+            "validate families:",
+            ...advertisedValidateFamilyNames().map((family) => ["retained-references", "activation-conjunction"].includes(family) ? `  ${family} (source checkout only)` : `  ${family}`),
+        ].join("\n");
+    }
     if (sub === "durability") {
         return [
             "usage: agentera check durability [-h] [--project PATH] [--artifact ARTIFACT]",
@@ -434,7 +440,7 @@ export function printPrimeHelp() {
         "  --orientation         Emit orientation briefing sections",
         "  --fields FIELDS       Comma-separated field filter for JSON/YAML output",
         "",
-        "JSON output uses bounded surfaces: bare prime is at most 12000 UTF-8 bytes and status context at most 25000; source_contract includes artifact_writes discovery metadata and omitted detail has named recovery commands.",
+        "JSON output uses bounded surfaces: bare prime is at most 12000 UTF-8 bytes and status context at most 22500; startup contains one availability projection and aggregate outcome, while schema discovery owns writer detail.",
     ].join("\n");
 }
 export function printSchemaHelp() {
@@ -459,13 +465,16 @@ export function printCapabilityHelp(capability) {
         "  -h, --help            show this help message and exit",
         "  --format FORMAT       Output format: text, json, or yaml",
         "",
-        `Startup context: agentera prime --context ${capability} --format json`,
+        `Startup context: ${preCutoverCommand(`prime --context ${capability} --format json`)}`,
     ].join("\n");
 }
 export function printRouteHelp() {
+    const receipt = describeRouteReceipt();
+    const example = JSON.stringify(receipt.stdin_example.input);
+    const inspect = (value) => JSON.stringify(value, null, 2).split("\n").map((line) => `  ${line}`);
     return [
-        "usage: agentera route <request|receipt> --input PATH [--format json]",
-        "       agentera route evaluate --format json",
+        `usage: ${preCutoverCommand("route <request|receipt> --input PATH [--format json]")}`,
+        `       ${preCutoverCommand("route evaluate --format json")}`,
         "",
         "Route one transient request or validate one semantic host receipt through the shared hybrid contract.",
         "Request text is accepted only from the structured YAML or JSON input document, never argv.",
@@ -473,14 +482,25 @@ export function printRouteHelp() {
         "Evaluate runs the frozen offline conformance corpus without a semantic host; it exits 1 when its report status is fail.",
         "",
         "input document: { version: agentera.route_request.v1, request: <string> }",
-        "receipt input: { request: <string>, receipt: <complete nullable host receipt with request_sha256 and semantic_capsule_sha256> }",
+        "Semantic receipt contract (also returned as receipt_contract after semantic_required):",
+        `  ${receipt.schemaVersion}; receipt version ${receipt.version}; outcomes: ${receipt.outcomes.join(", ")}.`,
+        "  Submit exactly { request: <original string>, receipt: <complete nullable receipt> }; request text stays in stdin or a file.",
+        "  Complete nullable receipt schema:",
+        ...inspect(receipt.nullable_schema),
+        "  Outcome nullability rules:",
+        ...inspect(receipt.outcome_rules),
+        "  Compound rules:",
+        ...inspect(receipt.compound),
+        "  remainder_span rule:",
+        ...inspect(receipt.remainder_span),
+        "  Runnable stdin round trip (run the command, write the JSON to stdin, then close stdin):",
+        `  ${receipt.stdin_command}`,
+        `  ${example}`,
         "A receipt result authorizes only its reported startup command; clarify starts none.",
     ].join("\n");
 }
 export function printCommandHelp(command, rest = []) {
     const sub = rest.find((a) => !a.startsWith("-") && a !== "--help" && a !== "-h");
-    if (command === "state" && rest.filter((item) => !item.startsWith("-")).slice(0, 2).join(" ") === "migrate entities")
-        return entityMigrateHelp();
     switch (command) {
         case "prime":
             return printPrimeHelp();
@@ -496,7 +516,9 @@ export function printCommandHelp(command, rest = []) {
             return printDoctorHelp();
         case "state": {
             const retrieval = entityRetrievalFamilyForHelpArgs(rest);
-            return retrieval ? retrieval.verb === "list" ? printStateListHelp(retrieval.family) : printStateGetHelp(retrieval.family) : printStateHelp(sub);
+            return retrieval
+                ? retrieval.verb === "list" ? printStateListHelp(retrieval.family) : printStateGetHelp(retrieval.family)
+                : sub && stateCommandNames().includes(sub) ? printStateHelp(sub) : printStateHelp();
         }
         case "check":
             return printCheckHelp(sub);
@@ -524,4 +546,3 @@ export function splitHelpArgs(argv) {
         return { args: argv, help: false };
     return { args: argv.filter((_, i) => i !== idx), help: true };
 }
-//# sourceMappingURL=help.js.map

package/dist/cli/migrationRequired.js

@@ -3,6 +3,7 @@ import path from "node:path";
 import { emitStructured } from "./structured.js";
 import { detectStateMode } from "../state/stateMode.js";
 import { fullEntityUpgradeCommand } from "../upgrade/upgradeCommands.js";
+import { preCutoverCommand } from "./preCutoverCommand.js";
 function value(argv, flag) {
     const equals = argv.find((arg) => typeof arg === "string" && arg.startsWith(`${flag}=`));
     if (equals)
@@ -21,14 +22,12 @@ export function requiresCompletedEntityCutover(argv) {
         return false;
     if (command === "report" && ["profile-glossary", "profile-grounding"].includes(subcommand))
         return false;
-    if (command === "prime" && argv.includes("--guidance"))
+    if (command === "prime" && (argv.includes("--guidance") || !argv.includes("--context") || value(argv, "--context") === "status"))
         return false;
     if (command === "query")
         return !argv.includes("--list-artifacts");
     if (command === "state" && subcommand === "query" && argv.includes("--list-artifacts"))
         return false;
-    if (command === "state" && subcommand === "migrate" && verb === "entities" && argv.includes("--dry-run"))
-        return false;
     if (command === "state" && verb === "explain")
         return false;
     return true;
@@ -55,7 +54,7 @@ export function enforceCompletedEntityCutover(projectRoot, format, io = {}) {
         mode = detectStateMode(project);
     }
     catch (error) {
-        const recovery = "Restore the exact durable migration marker, then run agentera check validate state --format json.";
+        const recovery = `Restore the exact durable migration marker, then run ${preCutoverCommand("check validate state --format json")}.`;
         const envelope = {
             schemaVersion: "agentera.stateFailure.v1",
             status: "fail",
@@ -86,4 +85,3 @@ export function enforceCompletedEntityCutover(projectRoot, format, io = {}) {
         (io.err ?? ((text) => process.stderr.write(text)))(`Error: ${envelope.error.message}\nRecovery: ${recovery}\n`);
     return 1;
 }
-//# sourceMappingURL=migrationRequired.js.map