@axtary/cli 0.2.0 → 0.4.0

package/dist/index.js

@@ -1,5 +1,6 @@
 import { createPrivateKey, createPublicKey, generateKeyPairSync, randomUUID, } from "node:crypto";
 import { createServer } from "node:http";
+import { readFileSync } from "node:fs";
 import { chmod, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
 import { dirname, extname, relative, resolve } from "node:path";
 import { createInterface } from "node:readline";
@@ -8,10 +9,11 @@ import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
 import { ACTIONPASS_V2_VERSION, ACTIONPASS_V1_VERSION, analyzePostgresSelect, AxtaryDecisionSchema, FileDpopReplayStore, LocalActionPassStatusStore, LocalCaepMappingStore, LocalSsfReplayStore, LocalActionPassTrustStore, createApprovalArtifact, demoAction, hashPayload, issuerJwks, issuerSigningKey, issuerVerificationKeyResolver, explainDecision, loadOrCreateIssuerKeyring, parseNormalizedAction, processCaepSessionRevoked, rotateIssuerKeyring, signStatusListToken, } from "@axtary/actionpass";
 import { createFakeAdapterState, createFakeHandlers, buildNativeConnectorDoctorPlans, createAwsRestHandlers, createActionPassVerifiedHandler, createGcpRestHandlers, createGitHubRestHandlers, createJiraRestHandlers, createLinearGraphqlHandlers, createLocalDocsHandlers, createPostgresNativeHandlers, createDriveRestHandlers, createSlackWebHandlers, GITHUB_NATIVE_CONNECTOR, githubAppRequiredEnv, mintGithubInstallationToken, resolveGithubAppCredentials, smokeAwsRestCredentials, smokeGcpRestCredentials, smokeGithubAppCredentials, smokeGitHubRestCredentials, smokeJiraRestCredentials, smokeLinearGraphqlCredentials, smokeLocalDocsRoots, smokePostgresCredentials, smokeDriveRestCredentials, smokeSlackWebCredentials, } from "@axtary/adapters";
 import { loadAxtaryConfig, CachedConfigLoader } from "@axtary/config";
-import { analyzeForensics, attestLedgerExport, buildLedgerAttestationBundle, exportLedgerRecords, formatLedgerExport, LedgerAttestationBundleSchema, LedgerExportFormatSchema, LocalJsonlLedger, OtlpHttpTraceExporter, proveLedgerConsistency, proveLedgerInclusion, syncLedgerExport, exportLedgerRecordsToOtlp, verifyLedgerAttestationBundle, verifyLedgerConsistencyProof, verifyLedgerInclusionProof, } from "@axtary/ledger";
+import { analyzeForensics, attestLedgerExport, buildLedgerAttestationBundle, CROSS_ISSUER_TRUST_ROOT_VERSION, evaluateLedgerEquivalence, exportLedgerRecords, formatLedgerExport, LedgerAttestationBundleSchema, LedgerExportFormatSchema, LocalJsonlLedger, OtlpHttpTraceExporter, proveLedgerConsistency, proveLedgerInclusion, syncLedgerExport, exportLedgerRecordsToOtlp, verifyLedgerAttestationBundle, verifyLedgerConsistencyProof, verifyLedgerInclusionProof, } from "@axtary/ledger";
 import { MCP_TOOL_CALL, McpHttpClient, McpStdioClient, createMcpAction, createMcpFixtureToolHandler, createMcpToolDefinition, createMcpToolRouter, createMcpWrapperServer, createMcpWrapperTool, evaluateMcpVersionChain, findMcpSignedDefinition, findMcpToolPin, loadMcpConformanceRegistry, loadMcpPinManifest, loadMcpPublisherTrustStore, loadMcpSignedDefinitionRegistry, McpPublisherKeySchema, mcpPublisherKeyResolver, pinMcpDefinitions, reconcileMcpPins, saveMcpConformanceRegistry, saveMcpPinManifest, saveMcpPublisherTrustStore, trustMcpPublisher, upsertMcpConformanceReceipt, verifyMcpSignedDefinition, } from "@axtary/mcp";
 import { createPollingHostedApprovalResolver } from "@axtary/approvals";
 import { applyPolicyTemplate, evaluatePolicy, explainPolicyDecision, getPolicyTemplate, getPolicyTemplates, runPolicyFixtures as runPolicyTemplateFixtures, simulatePolicy, } from "@axtary/policy";
+import { actionFromAcsToolCallSnapshot, createAxtaryAcsManifest, evaluateAcsIntervention, } from "@axtary/policy/acs";
 import { createProxyRuntime, } from "@axtary/proxy";
 import { runClaudeCodeHook } from "./claude-code-hook.js";
 import { runCodexHook } from "./codex-hook.js";
@@ -37,6 +39,7 @@ export const LEDGER_OTEL_EXPORT_RUN_SCHEMA_VERSION = "axtary.ledger_otel_export_
 export const LEDGER_ATTEST_RUN_SCHEMA_VERSION = "axtary.ledger_attest_run.v0";
 export const LEDGER_VERIFY_EXPORT_RUN_SCHEMA_VERSION = "axtary.ledger_verify_export_run.v0";
 export const LEDGER_PROVE_INCLUSION_RUN_SCHEMA_VERSION = "axtary.ledger_prove_inclusion_run.v0";
+export const LEDGER_PROVE_EQUIVALENCE_RUN_SCHEMA_VERSION = "axtary.ledger_prove_equivalence_run.v0";
 export const LEDGER_PROVE_CONSISTENCY_RUN_SCHEMA_VERSION = "axtary.ledger_prove_consistency_run.v0";
 export const LEDGER_VERIFY_PROOF_RUN_SCHEMA_VERSION = "axtary.ledger_verify_proof_run.v0";
 export const LEDGER_FORENSICS_RUN_SCHEMA_VERSION = "axtary.ledger_forensics_run.v0";
@@ -95,6 +98,7 @@ export function authorizeDecisionHints(decision, policy) {
     return hints;
 }
 export const POLICY_PARITY_SCHEMA_VERSION = "axtary.policy_parity.v0";
+export const ACS_CONFORMANCE_SCHEMA_VERSION = "axtary.acs_conformance.v0";
 const MCP_DEMO_TOOL_DEFINITION = createMcpToolDefinition({
     serverIdentity: "mcp:axtary-demo-fixtures",
     serverVersion: "1.0.0",
@@ -295,6 +299,9 @@ export async function startProxyServer(input = {}) {
                 endpoint: input.otlpEndpoint,
                 serviceName: input.otlpServiceName ?? "axtary-local-proxy",
                 timeoutMs: input.otlpTimeoutMs,
+                // The ledger library no longer falls back to ambient fetch; the
+                // CLI is the app boundary that supplies the transport.
+                fetch: globalThis.fetch,
             }),
         }
         : {});
@@ -375,6 +382,20 @@ export async function startProxyServer(input = {}) {
                 writeJson(response, 200, issuerJwks(keyring));
                 return;
             }
+            if (request.method === "GET" &&
+                request.url === "/.well-known/axtary-trust-root.json") {
+                writeJson(response, 200, {
+                    schemaVersion: CROSS_ISSUER_TRUST_ROOT_VERSION,
+                    issuer: loadedConfig.config.issuer,
+                    jwks: issuerJwks(keyring),
+                    statusListUri,
+                    federationProfile: {
+                        profile: "axtary.openid-federation-anchor.v0",
+                        entityStatementTyp: "entity-statement+jwt",
+                    },
+                });
+                return;
+            }
             if (request.method === "GET" &&
                 request.url === "/statuslists/actionpasses") {
                 const signed = await signStatusListToken({
@@ -421,6 +442,7 @@ export async function startProxyServer(input = {}) {
                     issuer: caepConfig.issuer,
                     audience: caepConfig.audience,
                     jwksUri: caepConfig.jwksUri,
+                    fetch: globalThis.fetch,
                     mappingStore: caepMappingStore,
                     replayStore: caepReplayStore,
                     revoke: async (rootPassId, claims) => {
@@ -564,7 +586,7 @@ runtime:
     mappingPath: .axtary/caep-mappings.json
     replayPath: .axtary/ssf-replay.json
 adapters:
-  # Start in fake mode: deterministic local adapters, no credentials needed.
+  # Start in credential-free deterministic demo mode; no provider credentials needed.
   # Switch a provider to its real mode (rest/web/graphql) once its env token is set.
   github:
     mode: fake
@@ -686,7 +708,7 @@ export function formatInitResult(result) {
     });
     const rail = [
         "  Next steps (the ten-minute rail — https://docs.axtary.com/quickstart):",
-        "    1. axtary doctor connectors --config axtary.yml   # readiness checklist; fake mode needs no credentials",
+        "    1. axtary doctor connectors --config axtary.yml   # readiness checklist; demo mode needs no credentials",
         ...policyTestStep.map((line) => `  ${line}`),
         `    ${gateStepNumber}. Gate a live agent — https://docs.axtary.com/integrate-agent (Claude Code / Cursor / Codex / MCP)`,
         "",
@@ -1000,7 +1022,11 @@ async function connectMcpUpstream(target) {
             });
             headers = { ...headers, authorization };
         }
-        client = await McpHttpClient.start({ url: target.wrapUrl, headers });
+        client = await McpHttpClient.start({
+            url: target.wrapUrl,
+            headers,
+            fetch: globalThis.fetch,
+        });
     }
     else if (target.wrap) {
         const [command, ...commandArgs] = target.wrap.split(/\s+/).filter(Boolean);
@@ -1899,6 +1925,17 @@ export async function runDemo(input = {}) {
                 verificationKey: publicKey,
             }),
         },
+        // Same exact-payload approval primitive as the real workflows: the
+        // artifact binds the payload hash, and the proxy stamps the
+        // approved/executed hash pair on the execution record.
+        approvalResolver: input.approveStepUp
+            ? async ({ action }) => createApprovalArtifact({
+                action,
+                mode: "human",
+                approvedBy: input.approvedBy ?? "user:local-reviewer",
+                reason: "Local exact approval for the demo step-up action.",
+            }).artifact
+            : undefined,
     });
     const results = [];
     for (const demo of DEMO_ACTIONS) {
@@ -2591,18 +2628,172 @@ export async function runPolicyParity(input = {}) {
         results.push({ id: fixture.id, passed, expected, engines });
     }
     const failed = results.filter((result) => !result.passed).length;
+    const agentCore = parity.buildAgentCoreCedarExport({
+        fixtures: fixturesFile.fixtures.map((fixture) => ({
+            id: fixture.id,
+            action: fixture.action,
+        })),
+        policyVersion: policyConfig.version,
+    });
     return {
         schemaVersion: POLICY_PARITY_SCHEMA_VERSION,
         engines: ["native", "cedar", "rego"],
         fixturesPath,
         cedarPath,
         regoWasmPath,
+        agentCore: {
+            schemaVersion: agentCore.schemaVersion,
+            status: agentCore.status,
+            gatewayResource: agentCore.gatewayResource,
+            fixtureCount: agentCore.fixtures.length,
+            sample: (agentCore.fixtures[0] ?? null),
+        },
         passed: failed === 0,
         total: results.length,
         failed,
         results,
     };
 }
+export async function runAcsConformance(input = {}) {
+    const loadedConfig = await loadAxtaryConfig({
+        filePath: input.configPath,
+        cwd: input.cwd,
+    });
+    const cwd = resolve(input.cwd ?? process.cwd());
+    const ledgerPath = input.ledgerPath
+        ? resolve(cwd, input.ledgerPath)
+        : resolve(cwd, ".axtary/acs-conformance.jsonl");
+    const ledger = new LocalJsonlLedger(ledgerPath);
+    const { privateKey } = generateKeyPairSync("ec", { namedCurve: "P-256" });
+    const manifest = createAxtaryAcsManifest();
+    const runtime = createProxyRuntime({
+        issuer: loadedConfig.config.issuer,
+        tenant: loadedConfig.config.tenant,
+        ledger,
+        policy: loadedConfig.config.policy,
+        signingKey: privateKey,
+        keyId: "local-acs-conformance-key",
+        allowUnsignedExecution: false,
+        handlerTimeoutMs: loadedConfig.config.runtime.handlerTimeoutMs,
+        budget: loadedConfig.config.runtime.budget,
+        handlers: {
+            "slack.chat.postMessage": async () => ({
+                ok: true,
+                provider: "acs-fixture",
+            }),
+        },
+    });
+    const vectors = [
+        {
+            id: "pre-tool-call-allow",
+            interventionPoint: "pre_tool_call",
+            snapshot: acsSlackSnapshot({
+                channel: "#axtary-dev",
+                message: "M9.4 ACS conformance allow",
+            }),
+            expectedVerdict: "allow",
+            expectedProxyStatus: "executed",
+            mode: "handle",
+        },
+        {
+            id: "pre-tool-call-deny",
+            interventionPoint: "pre_tool_call",
+            snapshot: acsSlackSnapshot({
+                channel: "#not-allowed",
+                message: "M9.4 ACS conformance deny",
+            }),
+            expectedVerdict: "deny",
+            expectedProxyStatus: "blocked",
+            mode: "handle",
+        },
+        {
+            id: "pre-tool-call-step-up",
+            interventionPoint: "pre_tool_call",
+            snapshot: acsSlackSnapshot({
+                channel: "#axtary-dev",
+                message: "M9.4 ACS conformance step-up",
+                externalRecipients: ["customer@example.com"],
+            }),
+            expectedVerdict: "escalate",
+            expectedProxyStatus: "step_up",
+            mode: "authorize",
+        },
+    ];
+    const results = [];
+    for (const vector of vectors) {
+        const acs = evaluateAcsIntervention({
+            manifest,
+            interventionPoint: vector.interventionPoint,
+            snapshot: vector.snapshot,
+            config: loadedConfig.config.policy,
+        });
+        const action = actionFromAcsToolCallSnapshot(vector.snapshot);
+        const proxy = vector.mode === "authorize"
+            ? await runtime.authorize(action)
+            : await runtime.handle(action);
+        const proxyStatus = "status" in proxy ? proxy.status : null;
+        const ledgerLine = "ledger" in proxy ? proxy.ledger.lineNumber : null;
+        const executionLedgerLine = "executionLedger" in proxy ? proxy.executionLedger.lineNumber : null;
+        const actionPassId = "actionPass" in proxy && proxy.actionPass
+            ? proxy.actionPass.claims.jti
+            : null;
+        const passed = acs.verdict === vector.expectedVerdict &&
+            proxyStatus === vector.expectedProxyStatus &&
+            (vector.expectedProxyStatus !== "executed" || actionPassId !== null) &&
+            ledgerLine !== null;
+        results.push({
+            id: vector.id,
+            interventionPoint: vector.interventionPoint,
+            expectedVerdict: vector.expectedVerdict,
+            actualVerdict: acs.verdict,
+            expectedProxyStatus: vector.expectedProxyStatus,
+            actualProxyStatus: proxyStatus,
+            passed,
+            reasons: acs.reasons,
+            actionHash: acs.evidence.actionHash ?? null,
+            payloadHash: acs.evidence.payloadHash ?? null,
+            actionPassId,
+            ledgerLine,
+            executionLedgerLine,
+        });
+    }
+    const failed = results.filter((result) => !result.passed).length;
+    return {
+        schemaVersion: ACS_CONFORMANCE_SCHEMA_VERSION,
+        manifestVersion: manifest.agent_control_specification_version,
+        ledgerPath,
+        passed: failed === 0,
+        total: results.length,
+        failed,
+        vectors: results,
+    };
+}
+function acsSlackSnapshot(input) {
+    return {
+        schemaVersion: "axtary.acs_snapshot.v0",
+        actor: {
+            agentId: "agent:codex-prod",
+            humanOwner: "user:asrar@company.com",
+            runtime: "codex-cli",
+            tenant: "org:axtary",
+        },
+        intent: {
+            taskId: "AXT-M9-4",
+            declaredGoal: "Verify ACS pre_tool_call routing through Axtary",
+        },
+        tool_call: {
+            tool: "slack.chat.postMessage",
+            resource: "slack:workspace/company",
+            arguments: {
+                channel: input.channel,
+                message: input.message,
+                ...(input.externalRecipients
+                    ? { externalRecipients: input.externalRecipients }
+                    : {}),
+            },
+        },
+    };
+}
 export async function runLedgerExport(input = {}) {
     const loadedConfig = await loadAxtaryConfig({
         filePath: input.configPath,
@@ -2660,7 +2851,7 @@ export async function runLedgerSync(input) {
         tenant: input.tenant ?? loadedConfig.config.tenant,
         token,
         export: exported,
-        fetch: input.fetch,
+        fetch: input.fetch ?? globalThis.fetch,
     });
     return {
         schemaVersion: LEDGER_SYNC_RUN_SCHEMA_VERSION,
@@ -2690,7 +2881,7 @@ export async function runLedgerOtelExport(input) {
         serviceName: input.serviceName ?? "axtary-ledger-export",
         timeoutMs: input.timeoutMs,
         records: exported.records,
-        fetch: input.fetch,
+        fetch: input.fetch ?? globalThis.fetch,
     });
     return {
         schemaVersion: LEDGER_OTEL_EXPORT_RUN_SCHEMA_VERSION,
@@ -2819,13 +3010,56 @@ export async function runLedgerVerifyExport(input) {
     const cwd = input.cwd ?? process.cwd();
     const bundlePath = resolve(cwd, input.bundlePath);
     const text = await readFile(bundlePath, "utf8");
-    const result = await verifyLedgerAttestationBundle(JSON.parse(text), {
+    const parsedBundle = JSON.parse(text);
+    const result = await verifyLedgerAttestationBundle(parsedBundle, {
         issuer: input.issuer,
     });
+    const equivalence = result.valid
+        ? evaluateLedgerEquivalence(LedgerAttestationBundleSchema.parse(parsedBundle).export.records)
+        : null;
     return {
         schemaVersion: LEDGER_VERIFY_EXPORT_RUN_SCHEMA_VERSION,
         bundlePath,
         result,
+        equivalence,
+    };
+}
+/**
+ * `axtary prove-equivalence` — the queryable, exportable approval↔execution
+ * equivalence proof. Reads the ledger through the fail-closed export path
+ * (a tampered chain refuses to export at all), then reports, per execution
+ * record, the approved payload hash, the executed payload hash, and whether
+ * they are equal. Executions without approval evidence report `unproven`,
+ * never fake-proved.
+ */
+export async function runLedgerProveEquivalence(input = {}) {
+    const loadedConfig = await loadAxtaryConfig({
+        filePath: input.configPath,
+        cwd: input.cwd,
+    });
+    const cwd = input.cwd ?? process.cwd();
+    const ledgerPath = resolveConfiguredLedgerPath(input, loadedConfig);
+    const exported = await exportLedgerRecords({
+        filePath: ledgerPath,
+        from: input.from,
+        to: input.to,
+        decisions: input.decisions,
+    });
+    const report = evaluateLedgerEquivalence(exported.records);
+    const outputPath = input.outputPath ? resolve(cwd, input.outputPath) : null;
+    if (outputPath) {
+        await mkdir(dirname(outputPath), { recursive: true });
+        await writeFile(outputPath, `${JSON.stringify(report, null, 2)}\n`, "utf8");
+    }
+    return {
+        schemaVersion: LEDGER_PROVE_EQUIVALENCE_RUN_SCHEMA_VERSION,
+        config: {
+            filePath: loadedConfig.filePath,
+            tenant: loadedConfig.config.tenant,
+        },
+        ledgerPath,
+        outputPath,
+        report,
     };
 }
 async function readAttestationBundle(cwd, bundlePath) {
@@ -3374,6 +3608,7 @@ export async function runRealWorkflow(input = {}) {
                 mutation: tamperSetup.mutation,
                 approvedPayloadHash: tamperSetup.approvedPayloadHash,
                 attemptedPayloadHash: tamperSetup.attemptedPayloadHash,
+                scopedAuthority: tamperSetup.scopedAuthority,
                 reached: tamperStep !== null,
                 blocked: tamperStep?.status === "blocked",
                 blockReasons: tamperStep?.reasons ?? [],
@@ -3989,6 +4224,15 @@ export async function runAxtaryCli(argv = process.argv.slice(2), io = {}) {
             stdout(helpText());
             return 0;
         }
+        if (command === "--version" || command === "-v" || command === "version") {
+            stdout(`${cliPackageVersion()}\n`);
+            return 0;
+        }
+        const commandHelp = commandHelpText(command, args);
+        if (commandHelp) {
+            stdout(commandHelp);
+            return 0;
+        }
         if (command === "init") {
             const parsed = parseInitArgs(args);
             const result = await runInit({
@@ -4046,6 +4290,8 @@ export async function runAxtaryCli(argv = process.argv.slice(2), io = {}) {
                 configPath: parsed.configPath,
                 ledgerPath: parsed.ledgerPath,
                 cwd: io.cwd ?? parsed.cwd,
+                approveStepUp: parsed.approveStepUp,
+                approvedBy: parsed.approvedBy,
             });
             if (parsed.json) {
                 stdout(`${JSON.stringify(result, null, 2)}\n`);
@@ -4230,6 +4476,25 @@ export async function runAxtaryCli(argv = process.argv.slice(2), io = {}) {
             }
             return result.result.valid ? 0 : 1;
         }
+        if (command === "prove-equivalence") {
+            const parsed = parseProveEquivalenceArgs(args);
+            const result = await runLedgerProveEquivalence({
+                configPath: parsed.configPath,
+                ledgerPath: parsed.ledgerPath,
+                cwd: io.cwd ?? parsed.cwd,
+                from: parsed.from,
+                to: parsed.to,
+                decisions: parsed.decisions,
+                outputPath: parsed.outputPath,
+            });
+            if (parsed.json) {
+                stdout(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                stdout(formatProveEquivalenceResult(result));
+            }
+            return result.report.failed === 0 ? 0 : 1;
+        }
         if (command === "prove-inclusion") {
             const parsed = parseProveInclusionArgs(args);
             const result = await runLedgerProveInclusion({
@@ -4711,6 +4976,21 @@ export async function runAxtaryCli(argv = process.argv.slice(2), io = {}) {
             }
             return result.passed ? 0 : 1;
         }
+        if (command === "acs") {
+            const parsed = parseAcsArgs(args);
+            const result = await runAcsConformance({
+                configPath: parsed.configPath,
+                ledgerPath: parsed.ledgerPath,
+                cwd: io.cwd ?? parsed.cwd,
+            });
+            if (parsed.json) {
+                stdout(`${JSON.stringify(result, null, 2)}\n`);
+            }
+            else {
+                stdout(formatAcsConformanceResult(result));
+            }
+            return result.passed ? 0 : 1;
+        }
         if (command === "connect") {
             const parsed = parseConnectArgs(args);
             const result = await runConnect({
@@ -5627,6 +5907,39 @@ function parseTestPolicyArgs(args) {
     }
     return parsed;
 }
+function parseAcsArgs(args) {
+    const subcommand = args[0];
+    if (subcommand !== "conformance") {
+        throw new Error("acs_requires_conformance");
+    }
+    const parsed = {
+        subcommand,
+        json: false,
+    };
+    for (let index = 1; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case "--config":
+                parsed.configPath = requireValue(args, index, "--config");
+                index += 1;
+                break;
+            case "--ledger":
+                parsed.ledgerPath = requireValue(args, index, "--ledger");
+                index += 1;
+                break;
+            case "--cwd":
+                parsed.cwd = requireValue(args, index, "--cwd");
+                index += 1;
+                break;
+            case "--json":
+                parsed.json = true;
+                break;
+            default:
+                throw new Error(`unknown_acs_flag:${arg}`);
+        }
+    }
+    return parsed;
+}
 function parseSmokeArgs(args) {
     const parsed = {};
     for (let index = 0; index < args.length; index += 1) {
@@ -6000,6 +6313,51 @@ function parseLedgerAttestArgs(args) {
     }
     return parsed;
 }
+function parseProveEquivalenceArgs(args) {
+    const parsed = {
+        json: false,
+        decisions: [],
+    };
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        switch (arg) {
+            case "--config":
+                parsed.configPath = requireValue(args, index, "--config");
+                index += 1;
+                break;
+            case "--ledger":
+                parsed.ledgerPath = requireValue(args, index, "--ledger");
+                index += 1;
+                break;
+            case "--cwd":
+                parsed.cwd = requireValue(args, index, "--cwd");
+                index += 1;
+                break;
+            case "--from":
+                parsed.from = requireValue(args, index, "--from");
+                index += 1;
+                break;
+            case "--to":
+                parsed.to = requireValue(args, index, "--to");
+                index += 1;
+                break;
+            case "--decision":
+                parsed.decisions.push(parseDecisionFlag(requireValue(args, index, "--decision")));
+                index += 1;
+                break;
+            case "--out":
+                parsed.outputPath = requireValue(args, index, "--out");
+                index += 1;
+                break;
+            case "--json":
+                parsed.json = true;
+                break;
+            default:
+                throw new Error(`unknown_prove_equivalence_flag:${arg}`);
+        }
+    }
+    return parsed;
+}
 function parseVerifyExportArgs(args) {
     const parsed = { bundlePath: "", json: false };
     for (let index = 0; index < args.length; index += 1) {
@@ -6328,6 +6686,13 @@ function parseDemoArgs(args) {
                 parsed.templateId = requireValue(args, index, "--template");
                 index += 1;
                 break;
+            case "--approve-step-up":
+                parsed.approveStepUp = true;
+                break;
+            case "--approved-by":
+                parsed.approvedBy = requireValue(args, index, "--approved-by");
+                index += 1;
+                break;
             case "--json":
                 parsed.json = true;
                 break;
@@ -6536,6 +6901,14 @@ function prepareTamperedSlackStep(actions, approvedBy) {
         approvedPayloadHash: artifact.payloadHash,
         attemptedPayloadHash: hashPayload(tamperedPayload),
         mutation: "Slack message payload mutated after exact approval while reusing the original approval artifact.",
+        scopedAuthority: {
+            tool: target.action.capability.tool,
+            resource: target.action.capability.resource,
+            approvedBy: artifact.approvedBy,
+            artifactId: artifact.id,
+            scopeUnchanged: target.action.capability.tool === approvedAction.capability.tool &&
+                target.action.capability.resource === approvedAction.capability.resource,
+        },
     };
 }
 function assertRealWorkflowModes(loadedConfig) {
@@ -6581,8 +6954,8 @@ async function doctorProvider(input) {
             requiredScopes: input.requiredScopes,
             smokeCheck: input.smokeCheck,
             summary: input.capability === "fake"
-                ? "fake mode configured; no real provider credentials are used"
-                : "connector is off",
+                ? "credential-free demo mode; no provider calls are made"
+                : "implemented connector is disabled in this config",
         };
     }
     const missingEnv = input.requiredEnv.filter((name) => !input.env[name]);
@@ -6658,7 +7031,7 @@ function formatDemoResult(result) {
         rows: [
             ["ledger", `${ledgerField(result.ledger)} · ${result.ledgerPath}`],
             [
-                "fake side effects",
+                "demo side effects",
                 `${result.adapters.github.pullRequests.length} GitHub PR, ${result.adapters.slack.messages.length} Slack, ${result.adapters.issueTrackers.linear.comments.length} Linear, ${result.adapters.issueTrackers.jira.comments.length} Jira`,
             ],
         ],
@@ -6796,6 +7169,36 @@ function formatPolicyParityResult(result) {
             ["fixtures", result.fixturesPath],
             ["cedar", result.cedarPath],
             ["rego", result.regoWasmPath],
+            [
+                "agentcore",
+                `${result.agentCore.status} · ${result.agentCore.fixtureCount} Cedar-shaped Gateway requests`,
+            ],
+        ],
+    });
+}
+function formatAcsConformanceResult(result) {
+    return renderWorkflow({
+        command: "acs conformance",
+        state: result.passed ? "ok" : "failed",
+        verdict: result.passed
+            ? `All ${result.total} ACS intervention vectors passed`
+            : `${result.failed} of ${result.total} ACS intervention vectors failed`,
+        steps: result.vectors.map((entry) => ({
+            state: entry.passed ? "ok" : "failed",
+            name: entry.id,
+            detail: `${entry.interventionPoint} -> ${entry.actualVerdict}` +
+                ` · proxy ${entry.actualProxyStatus ?? "none"}` +
+                ` · ${entry.reasons.join(", ")}`,
+        })),
+        rows: [
+            ["manifest", result.manifestVersion],
+            ["ledger", result.ledgerPath],
+            [
+                "actionpass",
+                result.vectors.some((entry) => entry.actionPassId)
+                    ? "issued for allow vector"
+                    : "not issued",
+            ],
         ],
     });
 }
@@ -6850,17 +7253,41 @@ function formatLedgerAttestResult(result) {
         ],
     });
 }
+/**
+ * One line summarizing the approval↔execution equivalence over a set of
+ * execution records. Verification fails closed on any failed pair, so a
+ * summary rendered for a VALID export can only contain proved + unproven.
+ */
+export function equivalenceSummaryLine(report) {
+    if (report.executions === 0) {
+        return "no execution records";
+    }
+    const parts = [
+        `${report.proved} of ${report.executions} execution${report.executions === 1 ? "" : "s"} proved approved == executed`,
+    ];
+    if (report.unproven > 0) {
+        parts.push(`${report.unproven} without approval evidence (unproven)`);
+    }
+    if (report.failed > 0) {
+        parts.push(`${report.failed} FAILED`);
+    }
+    return parts.join(" · ");
+}
 function formatVerifyExportResult(result) {
     if (result.result.valid) {
+        const rows = [
+            ["bundle", result.bundlePath],
+            ["issuer", result.result.claims.iss],
+            ["export digest", shortHash(result.result.recomputedDigest)],
+        ];
+        if (result.equivalence) {
+            rows.push(["equivalence", equivalenceSummaryLine(result.equivalence)]);
+        }
         return renderWorkflow({
             command: "verify-export",
             state: "ok",
             verdict: `Export VALID · ${result.result.claims.recordCount} record${result.result.claims.recordCount === 1 ? "" : "s"} independently verified`,
-            rows: [
-                ["bundle", result.bundlePath],
-                ["issuer", result.result.claims.iss],
-                ["export digest", shortHash(result.result.recomputedDigest)],
-            ],
+            rows,
         });
     }
     return renderWorkflow({
@@ -6873,6 +7300,35 @@ function formatVerifyExportResult(result) {
         ],
     });
 }
+function formatProveEquivalenceResult(result) {
+    const report = result.report;
+    const failed = report.entries.filter((entry) => entry.status === "failed");
+    const stepRows = failed.map((entry) => ({
+        state: "failed",
+        name: `record ${entry.line}${entry.tool ? ` (${entry.tool})` : ""}`,
+        detail: `${entry.failure} · approved ${entry.approvedPayloadHash ? shortHash(entry.approvedPayloadHash) : "absent"} vs executed ${entry.executedPayloadHash ? shortHash(entry.executedPayloadHash) : "absent"}`,
+    }));
+    return renderWorkflow({
+        command: "prove-equivalence",
+        state: report.failed > 0 ? "failed" : "ok",
+        verdict: report.failed > 0
+            ? `Equivalence FAILED · ${report.failed} execution record${report.failed === 1 ? "" : "s"} broke approved == executed`
+            : report.executions === 0
+                ? "No execution records to prove · the ledger chain is intact"
+                : report.proved === 0
+                    ? `No approved executions to prove · ${report.unproven} execution${report.unproven === 1 ? "" : "s"} without approval evidence · chain intact`
+                    : `Equivalence holds · ${equivalenceSummaryLine(report)}`,
+        steps: stepRows,
+        rows: [
+            ["ledger", result.ledgerPath],
+            ["executions", report.executions],
+            ["proved", report.proved],
+            ["unproven", report.unproven],
+            ["failed", report.failed],
+            ...(result.outputPath ? [["out", result.outputPath]] : []),
+        ],
+    });
+}
 /** Map a per-connector readiness status to a render state. */
 function doctorProviderState(status) {
     if (status === "ready")
@@ -6884,8 +7340,22 @@ function doctorProviderState(status) {
     return "warn"; // missing — needs setup
 }
 function formatConnectorDoctorResult(result) {
-    const ready = result.providers.filter((p) => p.status === "ready").length;
-    const total = result.providers.length;
+    const configured = result.providers.filter((provider) => provider.status !== "skipped");
+    const ready = configured.filter((provider) => provider.status === "ready").length;
+    const needsSetup = configured.length - ready;
+    const demo = result.providers.filter((provider) => provider.capability === "fake").length;
+    const disabled = result.providers.filter((provider) => provider.capability === "off").length;
+    const summaryParts = [
+        configured.length === 0
+            ? "No live or local connector checks configured"
+            : needsSetup === 0
+                ? `${ready} configured connector check${ready === 1 ? "" : "s"} passed`
+                : `${ready} of ${configured.length} configured connector checks passed · ${needsSetup} need setup`,
+        ...(demo > 0
+            ? [`${demo} in credential-free demo mode`]
+            : []),
+        ...(disabled > 0 ? [`${disabled} disabled`] : []),
+    ];
     const stepRows = result.providers.map((provider) => {
         const extras = [];
         if (provider.missingEnv.length > 0) {
@@ -6899,16 +7369,14 @@ function formatConnectorDoctorResult(result) {
             : provider.summary;
         return {
             state: doctorProviderState(provider.status),
-            name: `${provider.provider} (${provider.mode})`,
+            name: `${provider.provider} (${provider.mode === "fake" ? "demo" : provider.mode === "off" ? "disabled" : provider.mode})`,
             detail,
         };
     });
     return renderWorkflow({
         command: "doctor connectors",
         state: result.status === "ready" ? "ok" : "warn",
-        verdict: result.status === "ready"
-            ? `All ${total} connectors ready`
-            : `${ready} of ${total} connectors ready · the rest need setup before real mode`,
+        verdict: summaryParts.join(" · "),
         steps: stepRows,
         rows: [["config", result.config.filePath ?? "default"]],
     });
@@ -6919,6 +7387,20 @@ function formatConnectorDoctorResult(result) {
  * step failed before Slack, so the tamper was never exercised — must never be
  * reported as the tampered payload executing).
  */
+/**
+ * The scoped-authority contrast line — the differentiation beat spelled out:
+ * the agent still held a valid, exact-payload human approval whose tool +
+ * resource scope matched the attempted call, so an authorizer that checks
+ * scope alone would have let the swapped payload through. Only claim that
+ * when `scopeUnchanged` was actually computed true; otherwise state the
+ * scope changed too, which any authorizer should reject.
+ */
+export function scopedAuthorityLine(authority) {
+    const held = `valid approval by ${authority.approvedBy} for ${authority.tool} on ${authority.resource}`;
+    return authority.scopeUnchanged
+        ? `${held} · scope unchanged - a scope-only check would allow this call; Axtary binds the approval to the exact payload hash`
+        : `${held} · scope changed by the mutation`;
+}
 export function tamperOutcomeLine(tamper) {
     if (!tamper.reached) {
         return "tamper step not reached - a prior step failed before Slack, so content binding was not exercised this run (re-run with a fresh --head). The tampered payload did NOT execute.";
@@ -6953,6 +7435,7 @@ function formatRealWorkflowRunResult(result) {
                 ? "executed"
                 : "failed";
         rows.push(["tamper", `${result.tamper.step} (${result.tamper.tool}) · ${result.tamper.mutation}`]);
+        rows.push(["scoped authority", scopedAuthorityLine(result.tamper.scopedAuthority)]);
         rows.push(["approved hash", shortHash(result.tamper.approvedPayloadHash)]);
         rows.push(["attempted hash", shortHash(result.tamper.attemptedPayloadHash)]);
         rows.push(["tamper outcome", `${stateGlyph(tamperState)} ${tamperOutcomeLine(result.tamper)}`]);
@@ -7345,57 +7828,111 @@ function createProxyHandlers(loadedConfig, adapterState, verification, options =
         adapterModes,
     };
 }
+/**
+ * The CLI's own published version, read from its package manifest at runtime
+ * so `axtary --version` can never drift from what npm actually installed.
+ */
+function cliPackageVersion() {
+    const manifestUrl = new URL("../package.json", import.meta.url);
+    const manifest = JSON.parse(readFileSync(manifestUrl, "utf8"));
+    return manifest.version ?? "unknown";
+}
+const DETAILED_USAGE_LINES = [
+    "Usage:",
+    "  axtary init [--template repo-only-coding|staging-reads|incident-investigation|ticket-updates|doc-search|guarded-prod] [--config axtary.yml] [--force] [--json]  (scaffold a starter config and optional scope-template harness)",
+    "  axtary demo [--config axtary.yml] [--template <name>] [--ledger .axtary/actions.jsonl] [--approve-step-up [--approved-by user:you@example.com]] [--json]   (--approve-step-up attaches a local exact-payload approval so step-up actions execute with the approved/executed hash pair recorded)",
+    "  axtary revoke <actionpass-jti> [--trust-store .axtary/actionpass-trust-store.json] [--status-store .axtary/actionpass-status.json] [--by user:you@example.com] [--reason 'task cancelled'] [--json]",
+    "  axtary revocations [--trust-store .axtary/actionpass-trust-store.json] [--json]",
+    "  axtary issuer-keys [--keyring .axtary/keys/actionpass-issuer-keyring.json] [--rotate] [--retire-after 1200]  (metadata + public JWKS only; never prints private keys)",
+    "  axtary status [--store .axtary/actionpass-status.json]  (local ActionPass status-list allocation/state)",
+    "  axtary caep-map --issuer https://idp.example --subject '{\"format\":\"opaque\",\"id\":\"session\"}' --root ap_... [--root ap_...]  (map an SSF subject to live delegation roots)",
+    "  axtary doctor connectors [--config axtary.yml] [--json]",
+    "  axtary connect linear [--client-id <id> | --client-id-env NAME] [--client-secret-env NAME] [--redirect-port 7878] [--json]  (browser OAuth via http loopback; token stored in the local credential broker, never pasted)",
+    "  axtary connect slack --redirect-uri https://<tunnel>/callback ...  (Slack rejects http loopback; needs an HTTPS redirect — or keep SLACK_BOT_TOKEN in env)",
+    "  axtary connect jira --redirect-uri https://<tunnel>/callback [--cloud-id ID] ...  (Atlassian 3LO + site discovery + rotating refresh token in the local broker)",
+    "  axtary connect drive --redirect-uri https://<tunnel>/callback ...  (Google desktop Picker + drive.file only; stores the selected file id and OAuth token locally)",
+    "  axtary connections [--json]  (list connected providers — metadata only, never secrets)",
+    "  axtary disconnect <provider>  (remove a stored credential)",
+    "  axtary run workflow github-pr-review --real --config examples/axtary.real.yml --repo owner/repo --linear-issue AXT-418 --slack-channel '#axtary-dev' [--approve-step-up | --hosted-approval --approval-endpoint https://app.example [--approval-token-env AXTARY_APPROVAL_TOKEN] [--approval-poll-interval 3] [--approval-timeout 600]] [--tamper] [--approved-by user:you@example.com] [--ledger .axtary/actions.jsonl] [--json]",
+    "  axtary run workflow github-depth --real --config examples/axtary.real.yml --repo owner/repo [--linear-issue AXT-418] [--head axtary/axt-418-github-depth] [--check-name axtary/governed-check] [--review-line 1] [--approve-step-up] [--approved-by user:you@example.com] [--ledger .axtary/actions.jsonl] [--json]   (GitHub-only: opens a draft PR then writes an inline review comment, a check run, and an issue comment, all governed + ledgered)",
+    "  axtary run workflow postgres-read --real --config examples/axtary.postgres.yml --database appdb --statement 'SELECT id FROM public.items WHERE tenant_id = $1' --parameters '[\"tenant-a\"]' [--max-rows 100] [--approve-step-up] [--ledger .axtary/postgres-actions.jsonl] [--json]   (Postgres-only: one parameterized SELECT through policy, ActionPass, read-only transaction, RLS checks, and ledger)",
+    "  axtary run workflow drive-read --real --config examples/axtary.drive.yml [--file-id GOOGLE_FILE_ID] [--max-bytes 100000] [--ledger .axtary/drive-actions.jsonl] [--json]   (Google Drive-only: reads one Picker-authorized drive.file resource through policy, ActionPass, adapter, and ledger)",
+    "  axtary export-ledger [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--format json|jsonl|siem-jsonl] [--out export.json] [--json]",
+    "  axtary sync-ledger --endpoint https://app.example/api/ledger/sync [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--tenant org:company] [--token-env AXTARY_LEDGER_SYNC_TOKEN] [--json]",
+    "  axtary export-otel --endpoint http://127.0.0.1:4318/v1/traces [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--service-name axtary-local] [--json]   # opt-in OTLP/HTTP GenAI execute_tool spans, payload-free",
+    "  axtary attest-ledger [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--out attestation.json] [--key .axtary/keys/attestation-key.json] [--json]",
+    "  axtary verify-export <attestation.json> [--issuer https://local.axtary.dev] [--json]   # standalone: signature + chain + digest + approval↔execution equivalence",
+    "  axtary prove-equivalence [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--out equivalence.json] [--json]   # per-execution approved_payload_hash == executed_payload_hash proof, exportable",
+    "  axtary prove-inclusion <attestation.json> (--record <jti> | --index <n>) [--out proof.json] [--json]   # RFC 6962 inclusion proof",
+    "  axtary prove-consistency <first.json> <second.json> [--out proof.json] [--json]   # RFC 6962 consistency proof across two heads",
+    "  axtary verify-proof <proof.json> (--bundle <b.json> | --first <a.json> --second <b.json>) [--issuer ...] [--json]   # standalone proof verifier",
+    "  axtary forensics [<attestation.json>] [--ledger .axtary/actions.jsonl] [--json]   # offline incident reconstruction: attenuation, reconstructibility, cascade containment",
+    "  axtary proxy [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--trust-store .axtary/actionpass-trust-store.json] [--host 127.0.0.1] [--port 7331] [--otlp-endpoint http://127.0.0.1:4318/v1/traces]",
+    "  axtary hook install <claude|cursor|codex> [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000] [--cwd path] [--json]  (write an idempotent project hook config with resolved CLI paths)",
+    "  axtary hook claude-code [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000]  (reads a Claude Code PreToolUse payload from stdin)",
+    "  axtary hook cursor [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000]  (reads a Cursor beforeMCPExecution payload from stdin; emits {permission,user_message,agent_message})",
+    "  axtary hook codex [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000]  (reads a Codex PreToolUse payload from stdin; gates file-touching shell commands, apply_patch, and MCP fs tools)",
+    "  axtary mcp serve [--config axtary.yml] [--wrap 'npx -y @modelcontextprotocol/server-everything' | --wrap-url https://host/mcp [--header 'Authorization: Bearer …'] [--oauth]] [--owner user:you@example.com] [--ledger .axtary/actions.jsonl] [--trust-store .axtary/actionpass-trust-store.json] [--pins axtary.mcp-pins.json] [--strict]  (stdio or Streamable-HTTP MCP server; wrapped tools are policy-gated, pass-signed, revocation-checked, ledger-recorded, and pinned by definition hash; --oauth resolves the local OAuth bearer)",
+    "  axtary mcp login --wrap-url https://host/mcp [--scope 'a b'] [--client-id id] [--redirect-port 7878] [--json]  (OAuth-2.1 discovery + PKCE consent for an OAuth-protected remote MCP server; bearer stored in the local broker, never printed)",
+    "  axtary mcp sessions [--json]  (list remote MCP OAuth sessions from the local broker — resource/issuer/scopes/expiry, never tokens)",
+    "  axtary mcp logout --wrap-url https://host/mcp [--json]  (delete the locally stored OAuth session for a remote MCP server)",
+    "  axtary mcp pins [--pins axtary.mcp-pins.json] [--json]  (list the persisted tool-definition pins)",
+    "  axtary mcp trust-publisher --publisher mcp-publisher://acme --jwks publisher.jwks.json [--publisher-trust .axtary/mcp-publisher-trust.json]  (register public publisher keys; no TOFU)",
+    "  axtary mcp publishers [--publisher-trust .axtary/mcp-publisher-trust.json] [--json]  (list trusted publisher identities and public key ids)",
+    "  axtary mcp verify-definition --definition tool.json --statement tool.jwt --publisher mcp-publisher://acme [--publisher-trust path] [--json]  (verify publisher signature against the exact definition)",
+    "  axtary mcp review (--wrap 'npx -y <server>' | --wrap-url https://host/mcp [--header 'K: V'] [--oauth]) [--pins axtary.mcp-pins.json] [--publisher-trust path] [--signed-definitions registry.json] [--accept] [--json]  (diff pins and surface verified publisher/version-chain evidence)",
+    "  axtary mcp conformance (--wrap 'npx -y <server>' | --wrap-url https://host/mcp [--header 'K: V'] [--oauth]) --tool <name> --arguments '<json-object>' [--accept] [--pins path] [--publisher-trust path] [--signed-definitions registry.json] [--ledger path] [--status path] [--attestation path] [--key path] [--json]  (live governed call + publisher/pin evidence + v1/DPoP ledger + drift quarantine + attestation)",
+    "  axtary mcp drift-demo [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--json]  (reproducible tool-poisoning block: definition mutates after review, hash drift denies the call)",
+    "  axtary smoke [--config axtary.yml]",
+    "  axtary policy simulate <action.json> [--config axtary.yml] [--json]  (dry-run rule matches, decision, and obligations)",
+    "  axtary policy test <policies.test.yml> [--config axtary.yml] [--json]  (CI policy harness)",
+    "  axtary test-policy --fixtures ./fixtures [--config axtary.yml] [--json]",
+    "  axtary test-policy --parity [--fixtures parity-fixtures.json] [--cedar <file.cedar>] [--rego-wasm <policy.wasm>] [--json]",
+    "  axtary acs conformance [--config axtary.yml] [--ledger .axtary/acs-conformance.jsonl] [--json]  (credential-free ACS pre_tool_call vectors through Axtary policy, ActionPass, and ledger)",
+    "  axtary --version   (print the installed CLI version)",
+];
 function helpText() {
     return [
+        "Axtary — content authorization for AI-agent actions",
+        "",
         "Usage:",
-        "  axtary init [--template repo-only-coding|staging-reads|incident-investigation|ticket-updates|doc-search|guarded-prod] [--config axtary.yml] [--force] [--json]  (scaffold a starter config and optional scope-template harness)",
-        "  axtary demo [--config axtary.yml] [--template <name>] [--ledger .axtary/actions.jsonl] [--json]",
-        "  axtary revoke <actionpass-jti> [--trust-store .axtary/actionpass-trust-store.json] [--status-store .axtary/actionpass-status.json] [--by user:you@example.com] [--reason 'task cancelled'] [--json]",
-        "  axtary revocations [--trust-store .axtary/actionpass-trust-store.json] [--json]",
-        "  axtary issuer-keys [--keyring .axtary/keys/actionpass-issuer-keyring.json] [--rotate] [--retire-after 1200]  (metadata + public JWKS only; never prints private keys)",
-        "  axtary status [--store .axtary/actionpass-status.json]  (local ActionPass status-list allocation/state)",
-        "  axtary caep-map --issuer https://idp.example --subject '{\"format\":\"opaque\",\"id\":\"session\"}' --root ap_... [--root ap_...]  (map an SSF subject to live delegation roots)",
-        "  axtary doctor connectors [--config axtary.yml] [--json]",
-        "  axtary connect linear [--client-id <id> | --client-id-env NAME] [--client-secret-env NAME] [--redirect-port 7878] [--json]  (browser OAuth via http loopback; token stored in the local credential broker, never pasted)",
-        "  axtary connect slack --redirect-uri https://<tunnel>/callback ...  (Slack rejects http loopback; needs an HTTPS redirect — or keep SLACK_BOT_TOKEN in env)",
-        "  axtary connect jira --redirect-uri https://<tunnel>/callback [--cloud-id ID] ...  (Atlassian 3LO + site discovery + rotating refresh token in the local broker)",
-        "  axtary connect drive --redirect-uri https://<tunnel>/callback ...  (Google desktop Picker + drive.file only; stores the selected file id and OAuth token locally)",
-        "  axtary connections [--json]  (list connected providers — metadata only, never secrets)",
-        "  axtary disconnect <provider>  (remove a stored credential)",
-        "  axtary run workflow github-pr-review --real --config examples/axtary.real.yml --repo owner/repo --linear-issue AXT-418 --slack-channel '#axtary-dev' [--approve-step-up | --hosted-approval --approval-endpoint https://app.example [--approval-token-env AXTARY_APPROVAL_TOKEN] [--approval-poll-interval 3] [--approval-timeout 600]] [--tamper] [--approved-by user:you@example.com] [--ledger .axtary/actions.jsonl] [--json]",
-        "  axtary run workflow github-depth --real --config examples/axtary.real.yml --repo owner/repo [--linear-issue AXT-418] [--head axtary/axt-418-github-depth] [--check-name axtary/governed-check] [--review-line 1] [--approve-step-up] [--approved-by user:you@example.com] [--ledger .axtary/actions.jsonl] [--json]   (GitHub-only: opens a draft PR then writes an inline review comment, a check run, and an issue comment, all governed + ledgered)",
-        "  axtary run workflow postgres-read --real --config examples/axtary.postgres.yml --database appdb --statement 'SELECT id FROM public.items WHERE tenant_id = $1' --parameters '[\"tenant-a\"]' [--max-rows 100] [--approve-step-up] [--ledger .axtary/postgres-actions.jsonl] [--json]   (Postgres-only: one parameterized SELECT through policy, ActionPass, read-only transaction, RLS checks, and ledger)",
-        "  axtary run workflow drive-read --real --config examples/axtary.drive.yml [--file-id GOOGLE_FILE_ID] [--max-bytes 100000] [--ledger .axtary/drive-actions.jsonl] [--json]   (Google Drive-only: reads one Picker-authorized drive.file resource through policy, ActionPass, adapter, and ledger)",
-        "  axtary export-ledger [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--format json|jsonl|siem-jsonl] [--out export.json] [--json]",
-        "  axtary sync-ledger --endpoint https://app.example/api/ledger/sync [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--tenant org:company] [--token-env AXTARY_LEDGER_SYNC_TOKEN] [--json]",
-        "  axtary export-otel --endpoint http://127.0.0.1:4318/v1/traces [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--service-name axtary-local] [--json]   # opt-in OTLP/HTTP GenAI execute_tool spans, payload-free",
-        "  axtary attest-ledger [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--from ISO] [--to ISO] [--decision allow|deny|step_up] [--out attestation.json] [--key .axtary/keys/attestation-key.json] [--json]",
-        "  axtary verify-export <attestation.json> [--issuer https://local.axtary.dev] [--json]   # standalone: signature + chain + digest",
-        "  axtary prove-inclusion <attestation.json> (--record <jti> | --index <n>) [--out proof.json] [--json]   # RFC 6962 inclusion proof",
-        "  axtary prove-consistency <first.json> <second.json> [--out proof.json] [--json]   # RFC 6962 consistency proof across two heads",
-        "  axtary verify-proof <proof.json> (--bundle <b.json> | --first <a.json> --second <b.json>) [--issuer ...] [--json]   # standalone proof verifier",
-        "  axtary forensics [<attestation.json>] [--ledger .axtary/actions.jsonl] [--json]   # offline incident reconstruction: attenuation, reconstructibility, cascade containment",
-        "  axtary proxy [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--trust-store .axtary/actionpass-trust-store.json] [--host 127.0.0.1] [--port 7331] [--otlp-endpoint http://127.0.0.1:4318/v1/traces]",
-        "  axtary hook install <claude|cursor|codex> [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000] [--cwd path] [--json]  (write an idempotent project hook config with resolved CLI paths)",
-        "  axtary hook claude-code [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000]  (reads a Claude Code PreToolUse payload from stdin)",
-        "  axtary hook cursor [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000]  (reads a Cursor beforeMCPExecution payload from stdin; emits {permission,user_message,agent_message})",
-        "  axtary hook codex [--proxy http://127.0.0.1:7331] [--repo owner/repo] [--owner user:you@example.com] [--branch main] [--timeout 5000]  (reads a Codex PreToolUse payload from stdin; gates file-touching shell commands, apply_patch, and MCP fs tools)",
-        "  axtary mcp serve [--config axtary.yml] [--wrap 'npx -y @modelcontextprotocol/server-everything' | --wrap-url https://host/mcp [--header 'Authorization: Bearer …'] [--oauth]] [--owner user:you@example.com] [--ledger .axtary/actions.jsonl] [--trust-store .axtary/actionpass-trust-store.json] [--pins axtary.mcp-pins.json] [--strict]  (stdio or Streamable-HTTP MCP server; wrapped tools are policy-gated, pass-signed, revocation-checked, ledger-recorded, and pinned by definition hash; --oauth resolves the local OAuth bearer)",
-        "  axtary mcp login --wrap-url https://host/mcp [--scope 'a b'] [--client-id id] [--redirect-port 7878] [--json]  (OAuth-2.1 discovery + PKCE consent for an OAuth-protected remote MCP server; bearer stored in the local broker, never printed)",
-        "  axtary mcp sessions [--json]  (list remote MCP OAuth sessions from the local broker — resource/issuer/scopes/expiry, never tokens)",
-        "  axtary mcp logout --wrap-url https://host/mcp [--json]  (delete the locally stored OAuth session for a remote MCP server)",
-        "  axtary mcp pins [--pins axtary.mcp-pins.json] [--json]  (list the persisted tool-definition pins)",
-        "  axtary mcp trust-publisher --publisher mcp-publisher://acme --jwks publisher.jwks.json [--publisher-trust .axtary/mcp-publisher-trust.json]  (register public publisher keys; no TOFU)",
-        "  axtary mcp publishers [--publisher-trust .axtary/mcp-publisher-trust.json] [--json]  (list trusted publisher identities and public key ids)",
-        "  axtary mcp verify-definition --definition tool.json --statement tool.jwt --publisher mcp-publisher://acme [--publisher-trust path] [--json]  (verify publisher signature against the exact definition)",
-        "  axtary mcp review (--wrap 'npx -y <server>' | --wrap-url https://host/mcp [--header 'K: V'] [--oauth]) [--pins axtary.mcp-pins.json] [--publisher-trust path] [--signed-definitions registry.json] [--accept] [--json]  (diff pins and surface verified publisher/version-chain evidence)",
-        "  axtary mcp conformance (--wrap 'npx -y <server>' | --wrap-url https://host/mcp [--header 'K: V'] [--oauth]) --tool <name> --arguments '<json-object>' [--accept] [--pins path] [--publisher-trust path] [--signed-definitions registry.json] [--ledger path] [--status path] [--attestation path] [--key path] [--json]  (live governed call + publisher/pin evidence + v1/DPoP ledger + drift quarantine + attestation)",
-        "  axtary mcp drift-demo [--config axtary.yml] [--ledger .axtary/actions.jsonl] [--json]  (reproducible tool-poisoning block: definition mutates after review, hash drift denies the call)",
-        "  axtary smoke [--config axtary.yml]",
-        "  axtary policy simulate <action.json> [--config axtary.yml] [--json]  (dry-run rule matches, decision, and obligations)",
-        "  axtary policy test <policies.test.yml> [--config axtary.yml] [--json]  (CI policy harness)",
-        "  axtary test-policy --fixtures ./fixtures [--config axtary.yml] [--json]",
-        "  axtary test-policy --parity [--fixtures parity-fixtures.json] [--cedar <file.cedar>] [--rego-wasm <policy.wasm>] [--json]",
+        "  axtary <command> [options]",
+        "",
+        "Get started:",
+        "  init · doctor · demo · proxy · smoke",
+        "",
+        "Policy and ActionPass:",
+        "  policy · test-policy · revoke · revocations · issuer-keys · status · caep-map",
+        "",
+        "Agent runtimes and connectors:",
+        "  hook · mcp · connect · connections · disconnect · run",
+        "",
+        "Evidence and verification:",
+        "  export-ledger · sync-ledger · export-otel · attest-ledger · verify-export",
+        "  prove-equivalence · prove-inclusion · prove-consistency · verify-proof · forensics · acs",
+        "",
+        "Run `axtary <command> --help` for detailed usage. Nested groups work too,",
+        "for example `axtary mcp conformance --help`.",
+        "",
+        "Global options: --help, --version, --no-color",
+        "",
+    ].join("\n");
+}
+function commandHelpText(command, args) {
+    const helpIndex = args.findIndex((arg) => arg === "--help" || arg === "-h");
+    if (helpIndex < 0)
+        return null;
+    const nested = args.slice(0, helpIndex).filter((arg) => !arg.startsWith("-"));
+    const prefix = [command, ...nested].join(" ");
+    const matching = DETAILED_USAGE_LINES.filter((line) => {
+        const usage = line.trimStart();
+        return usage === `axtary ${prefix}` || usage.startsWith(`axtary ${prefix} `);
+    });
+    if (matching.length === 0)
+        return null;
+    return [
+        `Usage for \`${prefix}\`:`,
+        ...matching,
         "",
     ].join("\n");
 }