@compaction/cli 0.1.0

package/dist/cli/commands/eval.js

@@ -0,0 +1,66 @@
+import { stat } from "node:fs/promises";
+import chalk from "chalk";
+import { runEngineCommand } from "../engine-degrade.js";
+export function registerEvalCommand(program) {
+    program
+        .command("eval")
+        .description("Run the deterministic recoverability eval over a compaction-input fixture/bundle (or a directory of them). " +
+        "Proves byte/hash/source-pointer recoverability ONLY — semantic and commitment preservation are NOT evaluated.")
+        .argument("<fixture-or-directory>", "Path to an eval fixture/bundle JSON file, or a directory of them")
+        .option("--out <dir>", "Directory where eval report artifacts should be written")
+        .action(async (inputPath, options) => {
+        await runEngineCommand(async () => {
+            // The deterministic recoverability eval IS the proprietary methodology; the whole command is
+            // engine-gated (no public structural part). Lazy-load the engine: present in-repo/API, excluded
+            // from the public package. When absent, runEngineCommand prints the boundary message and exits
+            // cleanly (no stack trace) before any filesystem access.
+            const { evaluateFixtureDirectory, evaluateFixtureFile, writeCorpusEvalArtifacts, writeEvalArtifacts } = await import("../../engine/eval-fixtures.js");
+            console.log(chalk.cyan("compaction eval"));
+            console.log("Deterministic byte/hash/source-pointer recoverability check. " +
+                "No model call, no fuzzy matching, no savings claim. " +
+                "Semantic preservation and task-critical commitment preservation are NOT evaluated (reported as not_evaluated).");
+            const stats = await stat(inputPath);
+            if (stats.isDirectory()) {
+                const corpus = await evaluateFixtureDirectory(inputPath);
+                console.log("");
+                console.log(`Corpus: ${corpus.trace_count} trace(s) — ` +
+                    `recoverability passed=${corpus.recoverability_rollup.passed}, ` +
+                    `failed=${corpus.recoverability_rollup.failed}, ` +
+                    `not_computed(fail-closed)=${corpus.recoverability_rollup.not_computed}`);
+                console.log(`Recoverability pass rate (over computed): ${corpus.recoverability_pass_rate === null ? "n/a" : `${(corpus.recoverability_pass_rate * 100).toFixed(1)}%`}`);
+                console.log(`Real-captured results: ${corpus.real_captured_count}`);
+                console.log("Semantic preservation: not_evaluated (never scored). Commitment preservation: not_evaluated (never scored).");
+                if (options.out) {
+                    const paths = await writeCorpusEvalArtifacts(corpus, options.out);
+                    console.log(chalk.green(`Wrote ${paths.evalReportJsonPath}`));
+                    console.log(chalk.green(`Wrote ${paths.evalReportMarkdownPath}`));
+                }
+                // Non-zero exit if any trace failed recoverability (fail-closed signal for CI use).
+                if (corpus.recoverability_rollup.failed > 0) {
+                    process.exitCode = 1;
+                }
+                return;
+            }
+            const result = await evaluateFixtureFile(inputPath);
+            console.log("");
+            console.log(`Recoverability: ${result.recoverability.toUpperCase()}`);
+            console.log(`  ${result.recoverability_reason}`);
+            console.log(`Evidence source: ${result.evidence_source} (from ${result.evidence_source_type})`);
+            console.log(`Real captured: ${result.real_captured}`);
+            console.log(`Semantic preservation: ${result.semantic_preservation} (NOT scored). ` +
+                `Commitment preservation: ${result.commitment_preservation} (NOT scored).`);
+            for (const check of result.recoverability_checks) {
+                console.log(`  [${check.status}] ${check.label}`);
+            }
+            if (options.out) {
+                const paths = await writeEvalArtifacts(result, options.out);
+                console.log(chalk.green(`Wrote ${paths.evalReportJsonPath}`));
+                console.log(chalk.green(`Wrote ${paths.evalReportMarkdownPath}`));
+            }
+            if (result.recoverability === "failed") {
+                process.exitCode = 1;
+            }
+        });
+    });
+}
+//# sourceMappingURL=eval.js.map

package/dist/cli/commands/export-session-seed.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+/**
+ * `compaction export-session-seed --apply-dir <dir> [--out <file>]`
+ *
+ * Turns an APPROVED `apply-context` artifacts directory into a pasteable Lane B treatment
+ * session-seed prompt (FIXED-PLAN WORKFLOW-EFFICIENCY TREATMENT SETUP). Refusal-by-default:
+ * requires a valid approval record (`approved_for_in_workflow_use`), a hash-matching approved
+ * context, and a hash-matching retained original — otherwise it refuses, exits non-zero, and writes
+ * NO seed. Strictly read-only over the apply artifacts. No provider call, no network, no auto-apply.
+ */
+export declare function registerExportSessionSeedCommand(program: Command): void;

package/dist/cli/commands/export-session-seed.js

@@ -0,0 +1,42 @@
+import chalk from "chalk";
+import { runEngineCommand } from "../engine-degrade.js";
+/**
+ * `compaction export-session-seed --apply-dir <dir> [--out <file>]`
+ *
+ * Turns an APPROVED `apply-context` artifacts directory into a pasteable Lane B treatment
+ * session-seed prompt (FIXED-PLAN WORKFLOW-EFFICIENCY TREATMENT SETUP). Refusal-by-default:
+ * requires a valid approval record (`approved_for_in_workflow_use`), a hash-matching approved
+ * context, and a hash-matching retained original — otherwise it refuses, exits non-zero, and writes
+ * NO seed. Strictly read-only over the apply artifacts. No provider call, no network, no auto-apply.
+ */
+export function registerExportSessionSeedCommand(program) {
+    program
+        .command("export-session-seed")
+        .description("Export a PASTEABLE Lane B treatment session-seed (TREATMENT SETUP, NOT billing-confirmed savings; operator-applied, NOT auto-apply) from an APPROVED apply-context artifacts dir. Refuses unless approved + hashes match. Read-only; no provider call.")
+        .requiredOption("--apply-dir <dir>", "The apply-context artifacts directory (must contain an approval record)")
+        .option("--out <file>", "Where to write the session seed (default: <apply-dir>/session-seed.md)")
+        .action(async (options) => {
+        await runEngineCommand(async () => {
+            // Lazy-load the proprietary engine: present in-repo/API, excluded from the public package.
+            // When absent, runEngineCommand prints the boundary message and exits cleanly (no stack trace).
+            const { exportSessionSeed } = await import("../../engine/session-seed-export.js");
+            console.log(chalk.cyan("compaction export-session-seed (Lane B treatment setup)"));
+            console.log("Operator-applied, NOT auto-apply. compaction.dev starts no session and applies no context automatically. No provider call, no network.");
+            const result = await exportSessionSeed({
+                applyDir: options.applyDir,
+                outFile: options.out
+            });
+            if (result.refused) {
+                console.error(chalk.red("Refused — no session seed written:"));
+                for (const reason of result.reasons) {
+                    console.error(chalk.red(`- ${reason}`));
+                }
+                process.exitCode = 1;
+                return;
+            }
+            console.log(result.consoleSummary);
+            console.log(chalk.green(`Wrote ${result.seedPath}`));
+        });
+    });
+}
+//# sourceMappingURL=export-session-seed.js.map

package/dist/cli/commands/feedback.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerFeedbackCommand(program: Command): void;

package/dist/cli/commands/feedback.js

@@ -0,0 +1,233 @@
+import { readFile } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import os from "node:os";
+import readline from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+import chalk from "chalk";
+import { writeJsonArtifact, writeTextArtifact } from "../../core/artifact-writer.js";
+import { readCompactionRunReports } from "../../core/run-aggregator.js";
+import { buildFeedbackBundle, filterUsageMetadata, formatBundlePreview, renderBundleReadme, UNKNOWN } from "../../core/feedback-bundle.js";
+const BUNDLE_DIR_DEFAULT = path.join(".compaction", "feedback-bundle");
+async function readPackageVersion() {
+    try {
+        const here = path.dirname(fileURLToPath(import.meta.url));
+        // dist/cli/commands -> dist -> package root
+        const pkgPath = path.resolve(here, "..", "..", "..", "package.json");
+        const pkg = JSON.parse(await readFile(pkgPath, "utf8"));
+        return typeof pkg.version === "string" ? pkg.version : UNKNOWN;
+    }
+    catch {
+        return UNKNOWN;
+    }
+}
+/** Best-effort install-method classification from argv0 — NON-sensitive, no paths leaked. */
+function detectInstallMethod() {
+    const argv0 = process.argv[1] ?? "";
+    if (argv0.includes(`${path.sep}_npx${path.sep}`) || argv0.includes(`${path.sep}npx${path.sep}`)) {
+        return "npx";
+    }
+    if (argv0.includes(`${path.sep}node_modules${path.sep}.bin${path.sep}`)) {
+        return "local-node_modules";
+    }
+    if (argv0.includes(`${path.sep}lib${path.sep}node_modules${path.sep}`) || argv0.includes(`${path.sep}global${path.sep}`)) {
+        return "global-npm";
+    }
+    return UNKNOWN;
+}
+function parseTriState(value, flag) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "yes" || normalized === "no" || normalized === "unknown") {
+        return normalized;
+    }
+    throw new Error(`Invalid value for ${flag}: "${value}". Expected one of: yes, no, unknown.`);
+}
+/**
+ * Evidence levels this COMMAND accepts, weakest→strongest. `billing_confirmed` is
+ * deliberately ABSENT: this flow collects no invoice/billing/export evidence, so it must
+ * never be allowed to emit a billing-confirmed label. Supplying it is an explicit error.
+ */
+const ACCEPTED_EVIDENCE = [
+    "measured_input_token_reduction",
+    "output_token_delta_observed",
+    "recoverability_verified",
+    "applied_context",
+    "workflow_confirmed",
+    "usage_confirmed"
+];
+const ACCEPTED_EVIDENCE_SET = new Set([...ACCEPTED_EVIDENCE, "unknown"]);
+function parseEvidenceLevel(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "billing_confirmed") {
+        throw new Error('Invalid --evidence-level: "billing_confirmed" is not accepted by `feedback`. ' +
+            "This command collects NO invoice/billing/export evidence, so it cannot emit a " +
+            "billing-confirmed label. Use at most usage_confirmed (only with --usage-metadata).");
+    }
+    if (!ACCEPTED_EVIDENCE_SET.has(normalized)) {
+        throw new Error(`Invalid --evidence-level: "${value}". Allowed: ${[...ACCEPTED_EVIDENCE_SET].join(", ")}.`);
+    }
+    return normalized;
+}
+/**
+ * Cap a tester-supplied evidence level at what the inputs actually support — never emit a
+ * label stronger than the evidence. `usage_confirmed` requires real usage metadata; without
+ * it the strongest reachable rung is `workflow_confirmed`. Returns the (possibly lowered)
+ * level plus a flag when it was capped, so stdout can explain the downgrade honestly.
+ */
+function capEvidenceLevel(level, hasUsageMetadata) {
+    if (level === undefined || level === "unknown")
+        return { level, capped: false };
+    if (level === "usage_confirmed" && !hasUsageMetadata) {
+        // No usage metadata supplied → the strongest honest rung is workflow_confirmed.
+        return { level: "workflow_confirmed", capped: true };
+    }
+    return { level, capped: false };
+}
+function parseWorkflowOutcome(value) {
+    if (value === undefined)
+        return undefined;
+    const normalized = value.trim().toLowerCase();
+    if (["succeeded", "failed", "partial", "unknown"].includes(normalized)) {
+        return normalized;
+    }
+    throw new Error(`Invalid --workflow-outcome: "${value}". Expected: succeeded, failed, partial, unknown.`);
+}
+async function readUsageMetadata(filePath) {
+    if (!filePath)
+        return undefined;
+    const raw = await readFile(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new Error("--usage-metadata file must contain a JSON object of metadata fields.");
+    }
+    return parsed;
+}
+async function readDiagnostics(filePath) {
+    if (!filePath)
+        return undefined;
+    return readFile(filePath, "utf8");
+}
+/** Aggregate INPUT-token signals from local run reports. Output-token delta stays unknown
+ *  unless a report carries it (reports do not, so it remains unknown — honest by default). */
+async function aggregateSignals(runsDir) {
+    const { reports } = await readCompactionRunReports(runsDir);
+    let originalInput = 0;
+    let compactedInput = 0;
+    let inputSaved = 0;
+    let costDelta = 0;
+    let costObserved = false;
+    for (const { report } of reports) {
+        originalInput += report.original_input_tokens;
+        compactedInput += report.compacted_input_tokens;
+        inputSaved += report.tokens_saved;
+        if (Number.isFinite(report.saving_per_run)) {
+            costDelta += report.saving_per_run;
+            costObserved = true;
+        }
+    }
+    return {
+        run_count: reports.length,
+        total_original_input_tokens: originalInput,
+        total_compacted_input_tokens: compactedInput,
+        total_input_tokens_saved: inputSaved,
+        // Reports carry INPUT-token deltas only; output-token delta is not observable here.
+        output_token_delta: UNKNOWN,
+        estimated_cost_delta_usd: costObserved ? Math.round((costDelta + Number.EPSILON) * 1e6) / 1e6 : UNKNOWN
+    };
+}
+async function confirmWrite() {
+    if (!input.isTTY) {
+        // No interactive terminal and no explicit flag → fail closed.
+        return false;
+    }
+    const rl = readline.createInterface({ input, output });
+    try {
+        const answer = await rl.question("Write this feedback bundle locally? It will NOT be uploaded. Type yes to confirm: ");
+        return answer.trim().toLowerCase() === "yes";
+    }
+    finally {
+        rl.close();
+    }
+}
+export function registerFeedbackCommand(program) {
+    program
+        .command("feedback")
+        .description("Build a REDACTED, privacy-safe feedback bundle (local file only — never uploaded) for the beta learning loop.")
+        .option("--redact", "Build the redacted feedback bundle (default behavior; kept for explicitness)")
+        .option("--yes", "Confirm writing the bundle without an interactive prompt (explicit gesture)")
+        .option("--confirm", "Alias for --yes: explicitly confirm writing the bundle")
+        .option("--out <dir>", "Output directory for the bundle", BUNDLE_DIR_DEFAULT)
+        .option("--runs <dir>", "Compaction runs directory to aggregate", ".compaction/runs")
+        .option("--command-path <name>", "Which compaction command produced the run (e.g. compact)")
+        .option("--evidence-level <level>", "Weakest-supported evidence label (billing_confirmed NOT accepted; usage_confirmed needs --usage-metadata)")
+        .option("--recoverability <status>", "Recoverability status string (e.g. verified, unverified)")
+        .option("--applied-context <yes|no|unknown>", "Was compacted context applied to the workflow?")
+        .option("--workflow-outcome <outcome>", "Workflow outcome: succeeded|failed|partial|unknown")
+        .option("--missing-context <yes|no|unknown>", "Did the workflow report missing context?")
+        .option("--provider <name>", "Provider name, IF you choose to supply it")
+        .option("--model <name>", "Model name, IF you choose to supply it")
+        .option("--usage-metadata <file>", "Path to a JSON file of provider usage metadata to include")
+        .option("--diagnostics-file <file>", "Path to an error/log file to include AFTER best-effort redaction")
+        .action(async (options) => {
+        console.log(chalk.cyan("compaction feedback"));
+        console.log("Local-first, fail-closed. NO network, NO upload, NO telemetry. Redaction is BEST-EFFORT, not perfect.");
+        const usageMetadata = await readUsageMetadata(options.usageMetadata);
+        // "Usage supplied" for capping = the allowlist keeps at least one non-sensitive
+        // field; a file of only unrecognized keys does NOT support a usage_confirmed label.
+        // It must carry at least one NUMERIC token count — `model`/`provider` strings
+        // alone do not substantiate `usage_confirmed` (Codex P2 on #300).
+        const filteredUsage = filterUsageMetadata(usageMetadata);
+        const hasUsageMetadata = Boolean(filteredUsage &&
+            Object.values(filteredUsage.kept).some((v) => typeof v === "number"));
+        const requestedEvidence = parseEvidenceLevel(options.evidenceLevel);
+        const { level: cappedEvidence, capped } = capEvidenceLevel(requestedEvidence, hasUsageMetadata);
+        if (capped) {
+            console.log(chalk.yellow(`Note: --evidence-level "${requestedEvidence}" exceeds the supported evidence ` +
+                `(no usage metadata supplied); capped to "${cappedEvidence}". A label is never emitted above the evidence.`));
+        }
+        const supplied = {
+            command_path: options.commandPath,
+            evidence_level: cappedEvidence,
+            recoverability_status: options.recoverability,
+            applied_context: parseTriState(options.appliedContext, "--applied-context"),
+            workflow_outcome: parseWorkflowOutcome(options.workflowOutcome),
+            missing_context: parseTriState(options.missingContext, "--missing-context"),
+            provider: options.provider,
+            model: options.model,
+            usage_metadata: usageMetadata,
+            diagnostic_text: await readDiagnostics(options.diagnosticsFile)
+        };
+        const environment = {
+            cli_version: await readPackageVersion(),
+            os: `${os.platform()} ${os.release()}`,
+            node_version: process.version,
+            package_version: await readPackageVersion(),
+            install_method: detectInstallMethod()
+        };
+        const aggregate = await aggregateSignals(options.runs ?? ".compaction/runs");
+        const bundleInput = { environment, aggregate, supplied };
+        const bundle = buildFeedbackBundle(bundleInput);
+        // PREVIEW EXACTLY what will be written — always, before any write.
+        console.log("");
+        console.log(formatBundlePreview(bundle));
+        console.log("");
+        // Explicit-confirm gate, fail-closed.
+        const explicit = Boolean(options.yes) || Boolean(options.confirm);
+        const confirmed = explicit || (await confirmWrite());
+        if (!confirmed) {
+            console.log(chalk.yellow("Preview only — nothing written. Re-run with --yes (or --confirm) to write the bundle locally."));
+            return;
+        }
+        const outDir = options.out ?? BUNDLE_DIR_DEFAULT;
+        const jsonPath = await writeJsonArtifact(outDir, "feedback-bundle.json", bundle);
+        const readmePath = await writeTextArtifact(outDir, "README.md", renderBundleReadme(bundle));
+        console.log(chalk.green(`Wrote ${jsonPath}`));
+        console.log(chalk.green(`Wrote ${readmePath}`));
+        console.log("This bundle is LOCAL only — it was NOT uploaded. You choose whether to send it. Redaction is best-effort; inspect before sending.");
+    });
+}
+//# sourceMappingURL=feedback.js.map

package/dist/cli/commands/import.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerImportCommand(program: Command): void;

package/dist/cli/commands/import.js

@@ -0,0 +1,60 @@
+import chalk from "chalk";
+import { listTraceAdapters } from "../../core/trace-adapters.js";
+import { importTraceFile } from "../../core/trace-intake.js";
+function printSupportedSources() {
+    console.log(chalk.cyan("compaction import sources"));
+    for (const adapter of listTraceAdapters()) {
+        console.log(`- ${adapter.id}: ${adapter.displayName}`);
+    }
+    console.log("Live provider/runtime integrations remain future work; codex-exec-jsonl reads only local export files.");
+}
+export function registerImportCommand(program) {
+    program
+        .command("import")
+        .argument("[trace-file]", "Path to a local trace JSON, messages JSON, or supported JSONL file")
+        .option("--source <source>", "Input source: agent-trace, messages, codex-exec-jsonl, or unknown")
+        .option("--out <dir>", "Directory where normalized intake artifacts should be written")
+        .option("--operator-export", "Assert this file is your own real `codex exec --json` export (operator provenance). " +
+        "Without this flag, imports default to the weakest honest evidence tier (fixture). " +
+        "With it, a Codex JSONL import is labeled imported_local — still below real_captured and capped at conditional.")
+        .option("--list-sources", "List local trace adapter sources supported by import v0")
+        .description("Import a local trace file into the internal AgentTrace format.")
+        .action(async (traceFile, options) => {
+        if (options.listSources) {
+            printSupportedSources();
+            return;
+        }
+        if (!traceFile) {
+            throw new Error("Missing trace-file. Provide a local JSON file path or run compaction import --list-sources.");
+        }
+        if (!options.source) {
+            throw new Error("Missing required option --source <source>.");
+        }
+        if (!options.out) {
+            throw new Error("Missing required option --out <dir>.");
+        }
+        const artifacts = await importTraceFile(traceFile, options.source, options.out, {
+            operatorExport: options.operatorExport === true
+        });
+        console.log(chalk.cyan("compaction import"));
+        console.log(`Status: ${artifacts.report.status}`);
+        console.log(`Source: ${artifacts.report.source}`);
+        console.log(`Adapter: ${artifacts.report.adapter_id}`);
+        console.log(`Messages: ${artifacts.report.message_count}`);
+        console.log(chalk.green(`Wrote ${artifacts.paths.intakeReportJsonPath}`));
+        console.log(chalk.green(`Wrote ${artifacts.paths.intakeReportMarkdownPath}`));
+        if (artifacts.normalizedTrace) {
+            console.log(chalk.green(`Wrote ${artifacts.paths.normalizedTracePath}`));
+            console.log("");
+            console.log(chalk.bold("Next: analyze the imported trace to see waste attribution:"));
+            console.log(`  ${artifacts.report.recommended_next_command}`);
+        }
+        else {
+            console.log(chalk.red("No normalized trace was generated."));
+            console.log("The input did not normalize to an AgentTrace. See intake-report.md for the per-line reasons, " +
+                "then re-run with the correct --source (compaction import --list-sources).");
+            process.exitCode = 1;
+        }
+    });
+}
+//# sourceMappingURL=import.js.map

package/dist/cli/commands/init.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerInitCommand(program: Command): void;

package/dist/cli/commands/init.js

@@ -0,0 +1,216 @@
+import { existsSync } from "node:fs";
+import chalk from "chalk";
+import { defaultProjectsDir, discoverClaudeCodeSessions } from "../../core/adapters/claude-code-discovery.js";
+/**
+ * `compaction init` — first-run, value-led terminal onboarding.
+ *
+ * Converts "I installed a CLI" into "I am one command away from seeing my own
+ * workflow's context waste." It is guidance plus ONE read-only local detection
+ * (does a Claude Code projects directory exist, and how many sessions are in it).
+ *
+ * Invariants (non-negotiable, hold on every path):
+ *  - writes nothing
+ *  - makes no network call
+ *  - reads no provider credential
+ *  - needs no repo access
+ * A provider credential is ONLY ever used if the operator explicitly runs
+ * `capture provider-usage` (or enters operator-run measurement records).
+ *
+ * Proprietary boundary (per mvp-plan.md §13): output names high-level waste
+ * CATEGORIES and policy-FAMILY names plus before/after deltas, risk, safety,
+ * approval requirement, artifacts, and the next action — never the proprietary
+ * scoring formulas, thresholds, hidden heuristics, future-policy internals, or
+ * commercial / moat logic.
+ *
+ * Presentation note: this is a calm, structured, minimal first-run surface.
+ * Hierarchy comes from spacing, dim secondary text, and a few restrained
+ * symbols — not from a wall of enumerated text.
+ */
+// Clean one-line wordmark. The hand-drawn ASCII banner read busy at small
+// terminal sizes; a spaced, bold mark with a rule under it reads premium.
+const MARK = chalk.bold("compaction");
+const RULE = chalk.dim("─".repeat(58));
+const HEADLINE = "Context optimization for AI agents";
+const VALUE_PROP = chalk.dim("Reduce avoidable input/output tokens while preserving task-critical\n  context. Local-first — nothing is applied without your approval.");
+// The value loop, compressed to one line per step. Each step earns its place.
+const LOOP = [
+    ["capture", "a real trace from your own agent workflow"],
+    ["analyze", "where token spend and avoidable context waste are"],
+    ["recommend", "a candidate policy family + estimated before/after delta"],
+    ["compact", "the before/after token delta, and which family produced it"],
+    ["inspect", "safety evidence — source pointers, hashes, recoverable originals"],
+    ["approve", "emit a compacted context for your next call. No auto-apply."]
+];
+// Real-workflow paths only. compaction operates on the user's OWN agent
+// workflow; there is no demo / synthetic first-value path here. Demo fixtures
+// exist solely for tests, package smoke, and explicitly-labeled docs.
+const PRIMARY = {
+    key: "claude-code",
+    title: "Claude Code",
+    command: "compaction capture claude-code --discover"
+};
+const SECONDARY = [
+    {
+        key: "codex",
+        title: "Codex",
+        command: "codex exec --json '<task>' > run.jsonl  &&  compaction import run.jsonl --source codex-exec-jsonl --out ./my-trace"
+    },
+    {
+        key: "openai-agents",
+        title: "OpenAI Agents",
+        command: "compaction capture openai-agents --out ./my-trace -- <your-command>"
+    },
+    {
+        key: "import",
+        title: "Local trace",
+        command: "compaction import --list-sources   # then: import <file> --source <source> --out ./my-trace"
+    }
+];
+// The follow-up sequence is identical for every path once a trace exists.
+const FOLLOW_UP = [
+    "compaction analyze       ./my-trace/captured-trace.json",
+    "compaction recommend     ./my-trace/captured-trace.json",
+    "compaction compact       ./my-trace/captured-trace.json --out ./my-trace/compacted",
+    "compaction apply-context ./my-trace/captured-trace.json --out ./my-trace/apply"
+];
+function header(text) {
+    return chalk.bold(text);
+}
+function loopBlock() {
+    const width = Math.max(...LOOP.map(([verb]) => verb.length));
+    return LOOP.map(([verb, desc]) => `  ${chalk.cyan(verb.padEnd(width))}  ${chalk.dim(desc)}`);
+}
+function primaryBlock(sessionCount) {
+    const tag = chalk.green(`   ✓ ${sessionCount} session(s) found`);
+    return [
+        `${chalk.bold("▸ " + PRIMARY.title)}${chalk.dim("  · recommended")}${tag}`,
+        `  ${chalk.cyan(PRIMARY.command)}`
+    ];
+}
+function secondaryBlock() {
+    const lines = [chalk.dim("Other workflows")];
+    for (const p of SECONDARY) {
+        lines.push(`  ${chalk.dim(p.title)}`);
+        lines.push(`    ${chalk.cyan(p.command)}`);
+    }
+    return lines;
+}
+function emptyStateBlock(projectsDir) {
+    // Calm, premium no-sessions state: explain, show how to create one, and give
+    // the exact rerun command. The secondary real paths follow below.
+    return [
+        `${chalk.bold("▸ " + PRIMARY.title)}${chalk.dim("  · recommended")}`,
+        chalk.dim(`  No sessions found under ${projectsDir}.`),
+        chalk.dim("  Start or run a Claude Code session in any project, then re-run:"),
+        `    ${chalk.cyan("compaction capture claude-code --discover")}`
+    ];
+}
+function afterCaptureBlock() {
+    return [
+        header("Then, on the trace you captured"),
+        "",
+        ...FOLLOW_UP.map((c) => `  ${chalk.cyan(c)}`),
+        "",
+        chalk.dim("  You'll see: waste pattern CATEGORY, high-level POLICY FAMILY,"),
+        chalk.dim("  before/after input/output tokens, the TOKEN-COUNT SOURCE"),
+        chalk.dim("  (provider-reported vs estimated — never an estimate as reported),"),
+        chalk.dim("  RISK LEVEL, safety + source_recoverability, the APPROVAL REQUIREMENT"),
+        chalk.dim("  (--approve-in-workflow-use; no auto-apply), and the next action.")
+    ];
+}
+function footerBlock() {
+    return [
+        chalk.dim("Local-first: no network, no credentials, no repo access for any of the above."),
+        chalk.dim("A provider credential is only ever used if YOU explicitly run"),
+        chalk.dim("`compaction capture provider-usage` or enter operator-run records.")
+    ];
+}
+export function registerInitCommand(program) {
+    program
+        .command("init")
+        .description("First-run onboarding: the value loop, how to capture YOUR first real trace, and the exact next commands. " +
+        "Guidance + one read-only local detection only — writes nothing, no network, no credentials.")
+        .option("--path <path>", "Focus one input path: claude-code | codex | openai-agents | import")
+        .option("--projects-dir <dir>", "Claude Code projects directory to detect against (default: the standard local location)")
+        .action(async (options) => {
+        // Validate --path early so the error stays a clean one-liner.
+        const allKeys = [PRIMARY.key, ...SECONDARY.map((p) => p.key)];
+        if (options.path && !allKeys.includes(options.path)) {
+            console.error(`unknown --path '${options.path}'. Valid: ${allKeys.join(" | ")}`);
+            process.exitCode = 1;
+            return;
+        }
+        // Read-only local detection (no writes, no network).
+        const projectsDir = options.projectsDir ?? defaultProjectsDir();
+        let claudeDetected = false;
+        let sessionCount = 0;
+        if (existsSync(projectsDir)) {
+            try {
+                const discovery = await discoverClaudeCodeSessions({ projectsDir });
+                sessionCount = discovery.sessions.length;
+                claudeDetected = sessionCount > 0;
+            }
+            catch {
+                claudeDetected = false; // detection is best-effort; onboarding never fails on it
+            }
+        }
+        const focus = options.path;
+        const lines = [];
+        // 1. Mark + value prop.
+        lines.push("");
+        lines.push(`${MARK}  ${chalk.dim("·")}  ${HEADLINE}`);
+        lines.push(`  ${VALUE_PROP}`);
+        lines.push("");
+        lines.push(RULE);
+        lines.push("");
+        // 2. The value loop — what the tool actually does, one line per step.
+        lines.push(header("How it works"));
+        lines.push("");
+        lines.push(...loopBlock());
+        lines.push("");
+        lines.push(chalk.dim("  Estimates are labeled as estimates; provider-reported as provider-reported."));
+        lines.push(chalk.dim("  Nothing is called a saving until it is measured."));
+        lines.push("");
+        lines.push(RULE);
+        lines.push("");
+        // 3. Start here — primary path (Claude Code) or a focused secondary path.
+        if (!focus || focus === "claude-code") {
+            lines.push(header("Start here"));
+            lines.push("");
+            if (claudeDetected) {
+                lines.push(...primaryBlock(sessionCount));
+            }
+            else {
+                lines.push(...emptyStateBlock(projectsDir));
+            }
+            lines.push("");
+            // 4. Secondary real-workflow paths (compact, secondary styling).
+            //    Only on the default (unfocused) view.
+            if (!focus) {
+                lines.push(...secondaryBlock());
+                lines.push("");
+            }
+        }
+        else {
+            // Focused secondary path.
+            const p = SECONDARY.find((s) => s.key === focus);
+            lines.push(header("Start here"));
+            lines.push("");
+            lines.push(`  ${chalk.bold(p.title)}`);
+            lines.push(`    ${chalk.cyan(p.command)}`);
+            lines.push("");
+        }
+        lines.push(RULE);
+        lines.push("");
+        // 5. The follow-up sequence + what to expect.
+        lines.push(...afterCaptureBlock());
+        lines.push("");
+        lines.push(RULE);
+        lines.push("");
+        // 6. Local-first footer.
+        lines.push(...footerBlock());
+        lines.push("");
+        console.log(lines.join("\n"));
+    });
+}
+//# sourceMappingURL=init.js.map

package/dist/cli/commands/integrations.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerIntegrationsCommand(program: Command): void;