@productbrain/cli 0.1.0-beta.95 → 0.1.0-beta.951

package/dist/generators/region.js

@@ -0,0 +1,87 @@
+/**
+ * Region mechanism for non-destructive augmentation of user-owned adapter files (TEN-2155).
+ * Pure, surface-agnostic: sentinels, classification, EOL detection, and the splice transforms.
+ * Per-surface CONTENT lives in region-projections.ts; the write loop wires them together.
+ *
+ * Invariant (asserted by region.test.ts): the sentinels are disjoint from the whole-file
+ * MARKER ('auto-generated by pb handshake'), so an augmented file is never classified pb-managed
+ * and never whole-file-overwritten.
+ */
+import { MARKER } from './adapters.js';
+export const REGION_START = '<!-- pb:region:start — managed by `pb handshake`; edit only OUTSIDE this block -->';
+export const REGION_END = '<!-- pb:region:end -->';
+// Opt-out sentinel (TEN-2155): a file carrying this declares "pb handshake must NOT augment me".
+// Generic + consumer-usable — and the mechanism by which this repo's own committed CLAUDE.md/AGENTS.md
+// (the static constitution the constitution forbids handshake from writing) decline a PB region.
+export const REGION_OPT_OUT = '<!-- pb:no-augment -->';
+// Compile-time guard against a future MARKER rename silently colliding (belt-and-suspenders to the test).
+if (REGION_START.includes(MARKER) || REGION_END.includes(MARKER)) {
+    throw new Error('pb:region sentinels must not contain the whole-file MARKER substring');
+}
+// The opt-out sentinel must stay distinguishable from MARKER + the region sentinels, else a
+// region-present or pb-managed file could misclassify as opt-out (and silently stop being managed).
+if (REGION_OPT_OUT.includes(MARKER) ||
+    REGION_START.includes(REGION_OPT_OUT) ||
+    REGION_END.includes(REGION_OPT_OUT)) {
+    throw new Error('pb:no-augment sentinel must be disjoint from the MARKER and region sentinels');
+}
+// Precondition: needle.length > 0 (callers are internal, always non-empty sentinels). An empty needle would not terminate.
+function countOccurrences(haystack, needle) {
+    let count = 0;
+    let i = 0;
+    for (;;) {
+        const idx = haystack.indexOf(needle, i);
+        if (idx === -1)
+            break;
+        count += 1;
+        i = idx + needle.length;
+    }
+    return count;
+}
+/**
+ * Classify an EXISTING adapter file's content. Caller decides routing.
+ * Precedence: MARKER (whole-file pb-managed) → opt-out (user declined augmentation) → region balance.
+ */
+export function classifyAdapterFile(content) {
+    if (content.includes(MARKER))
+        return 'pb-managed';
+    if (content.includes(REGION_OPT_OUT))
+        return 'opt-out';
+    const starts = countOccurrences(content, REGION_START);
+    const ends = countOccurrences(content, REGION_END);
+    if (starts === 0 && ends === 0)
+        return 'augmentable';
+    if (starts === 1 && ends === 1 && content.indexOf(REGION_START) < content.indexOf(REGION_END)) {
+        return 'region-present';
+    }
+    return 'malformed';
+}
+/** Dominant EOL of the file. LF for empty / no-newline / ties. */
+export function detectEol(content) {
+    const crlf = (content.match(/\r\n/g) ?? []).length;
+    const loneLf = (content.match(/(?<!\r)\n/g) ?? []).length;
+    return crlf > loneLf ? '\r\n' : '\n';
+}
+/**
+ * Append a region to a file that has none. Never removes meaningful user content
+ * (a whitespace-only file is treated as empty) — only adds a blank-line separator
+ * when one is not already present. `region` includes both sentinels.
+ */
+export function spliceAppend(disk, region, eol) {
+    // The region body's EOL is the caller's responsibility (region-projections renders it in `eol`); this function only controls the separator + trailing newline.
+    if (disk.trim() === '')
+        return region + eol;
+    const sep = disk.endsWith(eol + eol) ? '' : disk.endsWith(eol) ? eol : eol + eol;
+    return disk + sep + region + eol;
+}
+/**
+ * Replace an existing region body in place. Bytes before REGION_START and after REGION_END
+ * are preserved verbatim. Caller guarantees `disk` classifies as 'region-present'.
+ * `region` includes both sentinels.
+ */
+export function spliceReplace(disk, region) {
+    const start = disk.indexOf(REGION_START);
+    const end = disk.indexOf(REGION_END) + REGION_END.length;
+    return disk.slice(0, start) + region + disk.slice(end);
+}
+//# sourceMappingURL=region.js.map

package/dist/generators/region.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"region.js","sourceRoot":"","sources":["../../src/generators/region.ts"],"names":[],"mappings":"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"}

package/dist/generators/region.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=region.test.d.ts.map

package/dist/generators/region.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"region.test.d.ts","sourceRoot":"","sources":["../../src/generators/region.test.ts"],"names":[],"mappings":""}

package/dist/generators/region.test.js

@@ -0,0 +1,126 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, it, expect } from 'vitest';
+import { MARKER } from './adapters.js';
+import { REGION_START, REGION_END, REGION_OPT_OUT, classifyAdapterFile, detectEol, spliceAppend, spliceReplace, } from './region.js';
+describe('region sentinels', () => {
+    it('are disjoint from the whole-file MARKER (both directions)', () => {
+        expect(REGION_START.includes(MARKER)).toBe(false);
+        expect(REGION_END.includes(MARKER)).toBe(false);
+        expect(MARKER.includes(REGION_START)).toBe(false);
+        expect(MARKER.includes(REGION_END)).toBe(false);
+    });
+    it('opt-out sentinel is disjoint from MARKER and the region sentinels', () => {
+        expect(REGION_OPT_OUT.includes(MARKER)).toBe(false);
+        expect(REGION_START.includes(REGION_OPT_OUT)).toBe(false);
+        expect(REGION_END.includes(REGION_OPT_OUT)).toBe(false);
+    });
+});
+describe('detectEol', () => {
+    it('returns LF for empty / no-newline / LF-dominant', () => {
+        expect(detectEol('')).toBe('\n');
+        expect(detectEol('one line')).toBe('\n');
+        expect(detectEol('a\nb\nc\n')).toBe('\n');
+    });
+    it('returns CRLF when CRLF-dominant', () => {
+        expect(detectEol('a\r\nb\r\nc\r\n')).toBe('\r\n');
+    });
+    it('returns LF when CRLF and lone-LF counts tie (tie-breaks to LF)', () => {
+        expect(detectEol('a\r\nb\n')).toBe('\n');
+    });
+});
+describe('classifyAdapterFile', () => {
+    const region = `${REGION_START}\n## x\n${REGION_END}`;
+    it('pb-managed when MARKER present (even with sentinel-looking text)', () => {
+        expect(classifyAdapterFile(`<!-- ${MARKER} -->\n${region}`)).toBe('pb-managed');
+    });
+    it('augmentable when no MARKER and no sentinels', () => {
+        expect(classifyAdapterFile('# my file\n')).toBe('augmentable');
+    });
+    it('region-present for exactly one balanced pair', () => {
+        expect(classifyAdapterFile(`# mine\n\n${region}\n`)).toBe('region-present');
+    });
+    it('malformed: start without end', () => {
+        expect(classifyAdapterFile(`# mine\n${REGION_START}\n`)).toBe('malformed');
+    });
+    it('malformed: end without start', () => {
+        expect(classifyAdapterFile(`# mine\n${REGION_END}\n`)).toBe('malformed');
+    });
+    it('malformed: duplicate starts', () => {
+        expect(classifyAdapterFile(`${REGION_START}\n${REGION_START}\n${REGION_END}`)).toBe('malformed');
+    });
+    it('malformed: duplicate ends', () => {
+        expect(classifyAdapterFile(`${REGION_START}\n${REGION_END}\n${REGION_END}`)).toBe('malformed');
+    });
+    it('malformed: end before start', () => {
+        expect(classifyAdapterFile(`${REGION_END}\nx\n${REGION_START}`)).toBe('malformed');
+    });
+    it('opt-out when the pb:no-augment sentinel is present (no MARKER)', () => {
+        expect(classifyAdapterFile(`# constitution\n${REGION_OPT_OUT}\n`)).toBe('opt-out');
+    });
+    it('opt-out wins over an existing region (user froze the file)', () => {
+        expect(classifyAdapterFile(`${REGION_OPT_OUT}\n${region}`)).toBe('opt-out');
+    });
+    it('opt-out wins over malformed sentinels (decline beats refusal)', () => {
+        expect(classifyAdapterFile(`${REGION_OPT_OUT}\n${REGION_START}\n(no end)\n`)).toBe('opt-out');
+    });
+    it('MARKER still wins over opt-out (whole-file pb-managed precedence)', () => {
+        expect(classifyAdapterFile(`<!-- ${MARKER} -->\n${REGION_OPT_OUT}\n`)).toBe('pb-managed');
+    });
+});
+describe('spliceAppend (never strips user bytes)', () => {
+    const region = `${REGION_START}\n## x\n${REGION_END}`;
+    it('empty/whitespace-only → region only (identical for both)', () => {
+        expect(spliceAppend('', region, '\n')).toBe(region + '\n');
+        expect(spliceAppend('   \n\n', region, '\n')).toBe(region + '\n');
+    });
+    it('no trailing newline → adds blank-line separator', () => {
+        expect(spliceAppend('last line', region, '\n')).toBe(`last line\n\n${region}\n`);
+    });
+    it('one trailing newline → one more for a blank line', () => {
+        expect(spliceAppend('body\n', region, '\n')).toBe(`body\n\n${region}\n`);
+    });
+    it('two+ trailing newlines → preserved verbatim, no extra separator', () => {
+        expect(spliceAppend('body\n\n\n', region, '\n')).toBe(`body\n\n\n${region}\n`);
+    });
+    it('exactly two trailing newlines → no extra separator', () => {
+        expect(spliceAppend('body\n\n', region, '\n')).toBe(`body\n\n${region}\n`);
+    });
+    it('CRLF file → region rendered + separated with CRLF; user bytes preserved', () => {
+        expect(spliceAppend('a\r\n', region, '\r\n')).toBe(`a\r\n\r\n${region}\r\n`);
+    });
+});
+describe('spliceReplace (only between sentinels; surrounding bytes verbatim)', () => {
+    it('replaces region body, preserves prefix + suffix byte-for-byte', () => {
+        const before = '# mine\nkeep me\n\n';
+        const after = '\nmore user text\n';
+        const oldRegion = `${REGION_START}\nOLD\n${REGION_END}`;
+        const newRegion = `${REGION_START}\nNEW\n${REGION_END}`;
+        const disk = before + oldRegion + after;
+        expect(spliceReplace(disk, newRegion)).toBe(before + newRegion + after);
+    });
+});
+describe('append → replace convergence (idempotency)', () => {
+    it('appending once then replacing with identical region is byte-stable', () => {
+        const region = `${REGION_START}\n## x\n${REGION_END}`;
+        const appended = spliceAppend('# mine\nbody\n', region, '\n');
+        expect(classifyAdapterFile(appended)).toBe('region-present');
+        expect(spliceReplace(appended, region)).toBe(appended);
+    });
+});
+// Reads the ACTUAL committed constitution files (not a copy of the sentinel string), so it catches
+// drift in EITHER REGION_OPT_OUT or the files themselves — the exact bug class where a paraphrased
+// comment was not a substring of the literal sentinel and the files would have been spliced anyway.
+describe('committed constitution declines augmentation (TEN-2155 governance regression)', () => {
+    // This test lives at <repo>/packages/cli/src/generators — walk up 4 to the repo root.
+    const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..', '..', '..', '..');
+    for (const file of ['CLAUDE.md', 'AGENTS.md']) {
+        it(`${file} carries the literal opt-out sentinel and classifies 'opt-out'`, () => {
+            const content = readFileSync(join(repoRoot, file), 'utf8');
+            expect(content.includes(REGION_OPT_OUT), `${file} must contain the literal sentinel ${JSON.stringify(REGION_OPT_OUT)}`).toBe(true);
+            expect(classifyAdapterFile(content), `${file} must classify 'opt-out' so handshake never splices it`).toBe('opt-out');
+        });
+    }
+});
+//# sourceMappingURL=region.test.js.map

package/dist/generators/region.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"region.test.js","sourceRoot":"","sources":["../../src/generators/region.test.ts"],"names":[],"mappings":"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"}

package/dist/generators/surface-profiles.d.ts

@@ -4,8 +4,7 @@
  * BET-270 Slice 0: type system + registry only. Generators accept but do not yet use the profile.
  * BET-270 Slice 4: pluggable surface registration + fallback.
  */
-import type { TargetName } from './portable-knowledge.js';
-export type { TargetName };
+export type TargetName = 'cursor' | 'claude' | 'copilot' | 'codex';
 export interface SurfaceProfile {
     /** How the agent executes work in this surface. */
     executionModel: 'batch' | 'interactive' | 'passive';

package/dist/generators/surface-profiles.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"surface-profiles.d.ts","sourceRoot":"","sources":["../../src/generators/surface-profiles.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAC;AAE1D,YAAY,EAAE,UAAU,EAAE,CAAC;AAI3B,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,cAAc,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;IACpD,8EAA8E;IAC9E,MAAM,EAAE,YAAY,GAAG,aAAa,CAAC;IACrC,oDAAoD;IACpD,YAAY,EAAE,WAAW,GAAG,gBAAgB,GAAG,YAAY,CAAC;IAC5D,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACrD;AAID,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,cAAc,CA6B/D,CAAC;AAKF;;;GAGG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,cAAc,CAWlF;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAY3E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAKpE"}
+{"version":3,"file":"surface-profiles.d.ts","sourceRoot":"","sources":["../../src/generators/surface-profiles.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,OAAO,CAAC;AAEnE,MAAM,WAAW,cAAc;IAC7B,mDAAmD;IACnD,cAAc,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAAC;IACpD,8EAA8E;IAC9E,MAAM,EAAE,YAAY,GAAG,aAAa,CAAC;IACrC,oDAAoD;IACpD,YAAY,EAAE,WAAW,GAAG,gBAAgB,GAAG,YAAY,CAAC;IAC5D,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,8DAA8D;IAC9D,aAAa,EAAE,cAAc,GAAG,QAAQ,GAAG,QAAQ,CAAC;CACrD;AAID,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,UAAU,EAAE,cAAc,CA6B/D,CAAC;AAKF;;;GAGG;AACH,wBAAgB,+BAA+B,IAAI,IAAI,CAEtD;AAID;;;;GAIG;AACH,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,IAAI,cAAc,CAWlF;AAID;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,CAY3E;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,EAAE,CAEhD;AAID;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAKpE"}

package/dist/generators/surface-profiles.js.map

@@ -1 +1 @@
-{"version":3,"file":"surface-profiles.js","sourceRoot":"","sources":["../../src/generators/surface-profiles.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAqBH,0EAA0E;AAE1E,MAAM,CAAC,MAAM,gBAAgB,GAAuC;IAClE,MAAM,EAAE;QACN,cAAc,EAAE,aAAa;QAC7B,MAAM,EAAE,YAAY;QACpB,YAAY,EAAE,gBAAgB;QAC9B,WAAW,EAAE,KAAK;QAClB,aAAa,EAAE,cAAc;KAC9B;IACD,MAAM,EAAE;QACN,cAAc,EAAE,aAAa;QAC7B,MAAM,EAAE,YAAY;QACpB,YAAY,EAAE,gBAAgB;QAC9B,WAAW,EAAE,KAAK;QAClB,aAAa,EAAE,cAAc;KAC9B;IACD,KAAK,EAAE;QACL,cAAc,EAAE,OAAO;QACvB,MAAM,EAAE,YAAY;QACpB,YAAY,EAAE,YAAY;QAC1B,WAAW,EAAE,MAAM;QACnB,aAAa,EAAE,QAAQ;KACxB;IACD,OAAO,EAAE;QACP,cAAc,EAAE,SAAS;QACzB,MAAM,EAAE,aAAa;QACrB,YAAY,EAAE,WAAW;QACzB,WAAW,EAAE,KAAK;QAClB,aAAa,EAAE,QAAQ;KACxB;CACF,CAAC;AAEF,iGAAiG;AACjG,MAAM,gBAAgB,GAAG,IAAI,GAAG,EAA0B,CAAC;AAE3D;;;GAGG;AACH,MAAM,UAAU,+BAA+B;IAC7C,gBAAgB,CAAC,KAAK,EAAE,CAAC;AAC3B,CAAC;AAED,yEAAyE;AAEzE;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CAAC,OAAgB;IACrD,IAAI,CAAC,OAAO,IAAI,OAAO,OAAO,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC1D,MAAM,CAAC,GAAG,OAAkC,CAAC;IAC7C,OAAO,CACL,CAAC,OAAO,EAAE,aAAa,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,cAAwB,CAAC;QACxE,CAAC,YAAY,EAAE,aAAa,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAgB,CAAC;QAC1D,CAAC,WAAW,EAAE,gBAAgB,EAAE,YAAY,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAsB,CAAC;QAChF,OAAO,CAAC,CAAC,WAAW,KAAK,QAAQ;QACjC,CAAC,CAAC,WAAW,GAAG,CAAC;QACjB,CAAC,cAAc,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAuB,CAAC,CACzE,CAAC;AACJ,CAAC;AAED,yEAAyE;AAEzE;;;;GAIG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY,EAAE,OAAuB;IACnE,IAAI,IAAI,IAAI,gBAAgB,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,sCAAsC,IAAI,qCAAqC,CAChF,CAAC;IACJ,CAAC;IACD,IAAI,CAAC,sBAAsB,CAAC,OAAO,CAAC,EAAE,CAAC;QACrC,MAAM,IAAI,KAAK,CACb,gCAAgC,IAAI,+DAA+D,CACpG,CAAC;IACJ,CAAC;IACD,gBAAgB,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;AACtC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,qBAAqB;IACnC,OAAO,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,gBAAgB,CAAC,EAAE,GAAG,gBAAgB,CAAC,IAAI,EAAE,CAAC,CAAC;AACxE,CAAC;AAED,yEAAyE;AAEzE;;;;GAIG;AACH,MAAM,UAAU,qBAAqB,CAAC,MAAc;IAClD,MAAM,OAAO,GAAG,gBAAgB,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IAC7C,IAAI,OAAO;QAAE,OAAO,OAAO,CAAC;IAC5B,MAAM,KAAK,GAAG,gBAAgB,CAAC,MAAoB,CAAC,CAAC;IACrD,OAAO,KAAK,IAAI,gBAAgB,CAAC,KAAK,CAAC;AACzC,CAAC"}
+{"version":3,"file":"surface-profiles.js","sourceRoot":"","sources":["../../src/generators/surface-profiles.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -17,6 +17,9 @@ import { runGet, runGetMany } from './commands/get.js';
 import { runConnect } from './commands/connect.js';
 import { runLogin } from './commands/login.js';
 import { runSetup } from './commands/setup.js';
+import { runSetupDetectSurfaces, formatDetectSurfacesSummary } from './commands/setup-detect-surfaces.js';
+import { runSetupState } from './commands/setup-state.js';
+import { runSetupAudit } from './commands/setup-audit.js';
 import { runOrient } from './commands/orient.js';
 import { runSearch } from './commands/search.js';
 import { runHandshake, runHandshakeInit } from './commands/handshake.js';
@@ -41,8 +44,10 @@ import { runVerify } from './commands/verify.js';
 import { runCodexPrep } from './commands/codex-prep.js';
 import { runCollectionsList, runCollectionsGet, runCollectionsAudit, runCollectionsExport } from './commands/collections.js';
 import { runWorkspaceVerify, runWorkspaceRepair, runDefinitionsDiff } from './commands/workspace.js';
-import { runAuthorityDomainsActivateCutover, runAuthorityDomainsBenchmark, runAuthorityDomainsDiscardPending, runAuthorityDomainsPropose, runAuthorityDomainsRatify, runAuthorityDomainsReadiness, runAuthorityDomainsRecordSample, runAuthorityDomainsReject, runAuthorityDomainsReview, } from './commands/authority-domains.js';
+import { runAuthorityDomainsActivateCutover, runAuthorityDomainsDeactivateCutover, runAuthorityDomainsBenchmark, runAuthorityDomainsDiscardPending, runAuthorityDomainsPropose, runAuthorityDomainsRatify, runAuthorityDomainsReadiness, runAuthorityDomainsRecordSample, runAuthorityDomainsReject, runAuthorityDomainsReview, runAuthorityDomainsPrincipleDistribution, } from './commands/authority-domains.js';
 import { runDoctor } from './commands/doctor.js';
+import { runWhoami } from './commands/whoami.js';
+import { runUpgrade } from './commands/upgrade.js';
 import { runProfileList, runProfileCreate, runProfileUse, runProfileDelete } from './commands/profile.js';
 import { runInit } from './commands/init.js';
 import { runMethodList, runMethodShow, runMethodDiff, runMethodPublish } from './commands/method.js';
@@ -50,10 +55,56 @@ import { createAdminCommand } from './commands/admin/index.js';
 import { runUsage } from './commands/usage.js';
 import { GLOSSARY, formatGlossary } from './lib/glossary.js';
 import { API_KEY_PREFIX } from './lib/tokenConstants.js';
-import { hint, heading, bold, dim, green, icons } from './lib/style.js';
+import { hint, heading, bold, dim, green, icons, yellow } from './lib/style.js';
+import { getPreviewBinding } from './lib/config.js';
 import { checkForUpdate } from './lib/update-check.js';
+import { UPGRADE_COMMAND } from './lib/constants.js';
 import { resolveSetupState, detectRenderTier } from './lib/state.js';
 const program = new Command();
+/**
+ * Top-level Chain-write commands that receive the throwaway-writes advisory in
+ * addition to the PREVIEW banner. Each is registered directly on `program`, so
+ * `actionCommand.name()` matches verbatim. We gate on top-level (parent === program)
+ * to avoid false positives from nested commands whose leaf name collides
+ * (e.g. `pb workspace verify`, which is a health check, not a Chain write).
+ */
+const PREVIEW_WRITE_COMMANDS = new Set([
+    'capture',
+    'update',
+    'verify',
+    'promote',
+    'relate',
+    'unrelate',
+    'ingest',
+    'accept',
+    'reject',
+]);
+/**
+ * Print a loud PREVIEW banner to stderr when pb is bound to a throwaway preview.
+ *
+ * Writes to stderr (NOT stdout) so stdout stays clean JSON for agents — and so the
+ * banner appears even when --json or --quiet are set, which is the whole point: the
+ * agent must see it every time. Cheap + synchronous (one file read). Never throws.
+ *
+ * For every Chain-write command (see PREVIEW_WRITE_COMMANDS), also writes an
+ * advisory reminding the user that real learnings belong in the real Chain.
+ */
+function printPreviewBanner(actionCommand) {
+    try {
+        const binding = getPreviewBinding();
+        if (!binding)
+            return;
+        const name = binding.workspaceName ?? 'preview';
+        process.stderr.write(yellow(bold(`⚠ PREVIEW ${name} — writes are throwaway. npm run pb:real to return to the real Chain`)) + '\n');
+        const isTopLevel = actionCommand.parent?.name() === 'pb';
+        if (isTopLevel && PREVIEW_WRITE_COMMANDS.has(actionCommand.name())) {
+            process.stderr.write(`  → real learnings belong in the real Chain. Switch back with: npm run pb:real\n`);
+        }
+    }
+    catch {
+        // Never let the banner crash the CLI
+    }
+}
 /**
  * Global error handler — single exit point for all CLI errors.
  * CLIError: format with code + category + guidance.
@@ -112,7 +163,10 @@ program
     .option('-q, --quiet', 'Suppress non-essential output (banners, hints, progress)')
     .exitOverride(); // Throw CommanderError instead of calling process.exit directly
 // Apply global output mode BEFORE subcommand actions run
-program.hook('preAction', (thisCommand) => {
+// Commander preAction hook signature: (hookedCommand, actionCommand)
+// hookedCommand = the command where hook was registered (root program)
+// actionCommand = the subcommand actually being invoked
+program.hook('preAction', (_hookedCommand, actionCommand) => {
     const globalOpts = program.opts();
     if (globalOpts.json) {
         setOutputMode('json');
@@ -126,7 +180,9 @@ program.hook('preAction', (thisCommand) => {
     }
     // Ambient update notification — non-blocking, suppressed in JSON mode (WP-322 S1)
     checkForUpdate(cliPackageVersion.version);
-    void thisCommand;
+    // PREVIEW banner — writes to stderr so it's always visible even in --json/--quiet mode.
+    // Advisory line added for top-level Chain-write commands: real learnings belong in the real Chain.
+    printPreviewBanner(actionCommand);
 });
 // Default action — status dashboard when `pb` is invoked with no command.
 // `pb --help` still works because Commander intercepts --help before the action runs.
@@ -347,8 +403,9 @@ program
     .option('-t, --task <task>', 'Task description for task-shaped governance and context')
     // SYNC: domain list must match TaskDomain in convex/agentKnowledge/startupResolver.ts
     .option('-s, --scope <domain>', 'Domain scope for governance filtering. Accepts authority roots, child scopes such as product-design/ux and data/analytics, and legacy internal scopes.')
+    .option('--full', 'Full depth orient (tier=full). Use for thorough context loading.')
     .action(async (opts) => {
-    await runOrient({ brief: opts.brief, task: opts.task?.trim() || undefined, scope: opts.scope?.trim() || undefined });
+    await runOrient({ brief: opts.brief, task: opts.task?.trim() || undefined, scope: opts.scope?.trim() || undefined, full: opts.full });
 });
 program
     .command('handshake')
@@ -360,24 +417,29 @@ program
     .option('--level <level>', 'With --init: trust level (guide|work|silent|full-trust). Without --init: content tier (beginner|intermediate|expert)')
     .option('--generate', 'Fetch governance entries from the Chain and merge generated rules (BET-286)')
     .option('--surfaces <list>', 'Comma-separated surfaces to write (cursor,claude,copilot,codex)')
+    .option('--no-prompt', 'Headless mode: refuse on tampered projection files (WP-421 S3, doneWhen #17). Always implied when stdout is not a TTY.')
+    .option('--lenient', 'WP-439 S4: continue past setup-asset body fetch failures with a warning (legacy behaviour). By default, body fetch failures are hard errors; run `pb setup-audit --repair` to fix orphaned rows.')
     .action(async (opts) => {
     if (opts.init) {
         await runHandshakeInit({ level: opts.level, dryRun: opts.dryRun });
         return;
     }
-    await runHandshake({ force: opts.force, apply: opts.apply, dryRun: opts.dryRun, level: opts.level, generate: opts.generate, surfaces: opts.surfaces?.split(',') });
+    // Commander turns `--no-prompt` into `prompt: false`. We invert so HandshakeOptions sees noPrompt=true.
+    const noPrompt = opts.prompt === false;
+    await runHandshake({ force: opts.force, apply: opts.apply, dryRun: opts.dryRun, level: opts.level, generate: opts.generate, surfaces: opts.surfaces?.split(','), noPrompt, lenient: opts.lenient });
 });
 program
     .command('codex-prep <task...>')
     .description('Generate task-specific governance context for Codex (.codex/task-context.md)')
     .option('--dry-run', 'Print to stdout instead of writing file')
+    .option('--full', 'Full depth orient (tier=full). Use for thorough context loading.')
     .action(async (taskParts, opts) => {
     const task = taskParts.join(' ').trim();
     if (!task) {
         program.commands.find((c) => c.name() === 'codex-prep')?.help();
         return;
     }
-    await runCodexPrep({ task, dryRun: opts.dryRun });
+    await runCodexPrep({ task, dryRun: opts.dryRun, full: opts.full });
 });
 program
     .command('init')
@@ -387,14 +449,15 @@ program
 });
 program
     .command('connect <token>')
-    .description('Redeem an onboarding token and save your API key locally (FEAT-958). Uses CONVEX_SITE_URL if set, otherwise the production gateway. Override with --gateway or PB_CONNECT_GATEWAY_URL.')
+    .description('Redeem an onboarding token and save your API key locally (FEAT-958). Uses CONVEX_SITE_URL if set, otherwise the production gateway. Override with --gateway or PB_CONNECT_GATEWAY_URL. Optional --name sets the key label in workspace settings (useful in non-interactive shells).')
     .option('--gateway <url>', 'Override redeem gateway (default: CONVEX_SITE_URL or production). Use when token came from a different Convex deployment.')
+    .option('--name <label>', 'Optional label for this API key in workspace settings. In non-interactive terminals, use this instead of a prompt.')
     .action(async (token, opts) => {
     if (!token?.trim()) {
         program.commands.find((c) => c.name() === 'connect')?.help();
         return;
     }
-    await runConnect(token.trim(), { gateway: opts.gateway });
+    await runConnect(token.trim(), { gateway: opts.gateway, name: opts.name });
 });
 program
     .command('login')
@@ -410,12 +473,49 @@ program
     .action(async (opts) => {
     await runDoctor({ fix: opts.fix, dryRun: opts.dryRun });
 });
+program
+    .command('whoami')
+    .alias('status')
+    .description('Show the active profile + workspace (fast; no session required).')
+    .action(async () => {
+    await runWhoami();
+});
 program
     .command('setup')
-    .description('Guided first-time setup: account, login, workspace, first capture')
+    .description('Canonical pb-setup entry (DEC-995): detect surfaces, read state, emit JSON for the skill body.')
     .action(async () => {
     await runSetup();
 });
+program
+    .command('setup-detect-surfaces')
+    .description('Detect local surface markers and union-merge into manifest.surfaces (STD-235 forward-only)')
+    .action(async () => {
+    const result = await runSetupDetectSurfaces();
+    if (process.stdout.isTTY) {
+        process.stdout.write(formatDetectSurfacesSummary(result) + '\n');
+    }
+    else {
+        process.stderr.write(formatDetectSurfacesSummary(result) + '\n');
+    }
+});
+program
+    .command('setup-state')
+    .description('Emit compact JSON of getPbSetupState (machine-readable, used by the pb-setup skill body)')
+    .action(async () => {
+    await runSetupState();
+});
+// WP-439 S2: setup-asset orphan audit. Read-only diagnostic; exits 1 if any
+// setup_asset row has a broken body wiring (will fail at handshake).
+// WP-439 S3: --repair attempts to restore class III/II orphans from STARTER_*
+// constants. Class I (inline-only) and IV (hash drift) are NOT touched.
+program
+    .command('setup-audit')
+    .description('Audit setup_asset rows for orphaned bodies (WP-439 S2/S3). Exits 1 if any orphan or repair-failure.')
+    .option('--json', 'Emit machine-readable JSON (overrides pretty output for this command)')
+    .option('--repair', 'Attempt to restore class III/II orphans from STARTER_* constants (WP-439 S3)')
+    .action(async (opts) => {
+    await runSetupAudit({ json: opts.json, repair: opts.repair });
+});
 // --- Write commands (require active session) ---
 const sessionCmd = program
     .command('session')
@@ -595,7 +695,7 @@ program
 // --- Audit command (BET-182 Slice 2) ---
 program
     .command('audit <entry-ids...>')
-    .description('Run STD-113 hygiene audit on bet(s) — 13 gates, exit code reflects verdict')
+    .description('Run hygiene audit on bet(s) — 13 gates (shaping) / 18 gates (handoff), exit code reflects verdict')
     .option('--phase <phase>', 'Override phase detection (shaping | handoff)')
     .option('--gate <name>', 'Run only specified gate(s) (repeatable)', (val, prev) => [...prev, val], [])
     .option('--fix', 'Auto-execute exact fixes via pb update, rerun once')
@@ -764,8 +864,23 @@ authorityDomainsCmd
 authorityDomainsCmd
     .command('activate-cutover')
     .description('Activate graph retrieval after WP-354 evidence gates pass')
+    .option('--force-pre-production', 'Bypass the permanently-locked valueProof gate (requires --dec-id, DEC-864)')
+    .option('--dec-id <decId>', 'Chain DEC ID authorizing the bypass')
+    .action(async (opts) => {
+    await runAuthorityDomainsActivateCutover({ forcePreProduction: opts.forcePreProduction, decId: opts.decId });
+});
+authorityDomainsCmd
+    .command('deactivate-cutover')
+    .description('Deactivate the active WP-354 authorityDomain cutover for this workspace (DEC-864 rollback).')
+    .option('--clerk-user-id <clerkUserId>', 'Override the Clerk user ID for audit trail')
+    .action(async (opts) => {
+    await runAuthorityDomainsDeactivateCutover({ clerkUserId: opts.clerkUserId });
+});
+authorityDomainsCmd
+    .command('principle-distribution')
+    .description('Pre-merge gate: check governance category match rate for principles entries')
     .action(async () => {
-    await runAuthorityDomainsActivateCutover();
+    await runAuthorityDomainsPrincipleDistribution();
 });
 // --- Definitions diff command (WP-305 Slice 4) ---
 const definitionsCmd = program
@@ -838,10 +953,11 @@ profileCmd
 });
 profileCmd
     .command('use <name>')
-    .description('Switch active profile (closes any active session). Use --local to pin profile in project config.local.json instead.')
-    .option('--local', 'Write profile pin to .productbrain/config.local.json in the project root (machine-local, gitignored)')
+    .description('Switch profile: reconciles the repo pin + global by default. --local = repo pin only; --global = global only.')
+    .option('--local', 'Write the profile pin only to .productbrain/config.local.json (repo-local, gitignored)')
+    .option('--global', 'Switch only the global active profile (does not change a locally-pinned repo)')
     .action(async (name, opts) => {
-    await runProfileUse({ name, local: opts.local });
+    await runProfileUse({ name, local: opts.local, global: opts.global });
 });
 profileCmd
     .command('delete <name>')
@@ -849,6 +965,14 @@ profileCmd
     .action(async (name) => {
     await runProfileDelete({ name });
 });
+program
+    .command('use <name>')
+    .description('Switch the active workspace profile (alias for `pb profile use`).')
+    .option('--local', 'Write the profile pin only to .productbrain/config.local.json (repo-local, gitignored)')
+    .option('--global', 'Switch only the global active profile (does not change a locally-pinned repo)')
+    .action(async (name, opts) => {
+    await runProfileUse({ name, local: opts.local, global: opts.global });
+});
 // --- Glossary command (WP-302 Slice 4) ---
 program
     .command('glossary')
@@ -880,18 +1004,9 @@ program.addCommand(createAdminCommand());
 // --- Upgrade command (WP-322 S1: ambient update notification) ---
 program
     .command('upgrade')
-    .description('Upgrade pb CLI to the latest version (npm install -g @productbrain/cli@latest)')
-    .action(() => {
-    if (isJsonMode()) {
-        process.stdout.write(JSON.stringify({
-            command: 'npm install -g @productbrain/cli@latest',
-            hint: 'Run the command above to upgrade pb CLI.',
-        }) + '\n');
-        return;
-    }
-    process.stdout.write('\n');
-    process.stdout.write(`${bold('Upgrade pb CLI')}  ${dim('—')} run the command below:\n\n`);
-    process.stdout.write(`  npm install -g @productbrain/cli@latest\n\n`);
+    .description(`Upgrade pb CLI to the latest beta (${UPGRADE_COMMAND})`)
+    .action(async () => {
+    await runUpgrade({ currentVersion: cliPackageVersion.version });
 });
 // Parse with global error handler — all uncaught errors route through handleError
 program.parseAsync(process.argv).catch(handleError);