sneakoscope 0.9.6 → 0.9.8

package/README.md

@@ -491,6 +491,8 @@ Run local checks:
 npm run repo-audit
 npm run changelog:check
 npm run packcheck
+npm run feature:check
+npm run all-features:selftest
 npm run selftest
 npm run sizecheck
 npm run registry:check
@@ -498,7 +500,7 @@ npm run release:check
 npm run publish:dry
 ```
 
-`release:check` runs audit, changelog, syntax, selftest, size, and registry checks. `publish:dry` runs that same gate and then performs an npm dry-run publish against the public registry.
+`release:check` runs audit, changelog, syntax, feature-registry coverage, all-features contract selftest, selftest, size, and registry checks. Generate the human-readable registry with `sks features inventory --write-docs`. `publish:dry` runs that same gate and then performs an npm dry-run publish against the public registry.
 
 Version bumps are manual. Run `sks versioning bump` only when preparing release metadata; SKS will not create `.git/hooks/pre-commit` or auto-bump during ordinary commits.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "description": "Sneakoscope Codex: database-safe Codex CLI/App harness with Team, Goal, AutoResearch, TriWiki, and Honest Mode.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",
@@ -38,7 +38,9 @@
     "changelog:check": "node ./scripts/changelog-check.mjs",
     "sizecheck": "node ./scripts/sizecheck.mjs",
     "registry:check": "node ./scripts/release-registry-check.mjs",
-    "release:check": "npm run repo-audit && npm run changelog:check && npm run packcheck && npm run selftest && npm run sizecheck && npm run registry:check",
+    "feature:check": "node ./bin/sks.mjs features check --json",
+    "all-features:selftest": "node ./bin/sks.mjs all-features selftest --mock --json",
+    "release:check": "npm run repo-audit && npm run changelog:check && npm run packcheck && npm run feature:check && npm run all-features:selftest && npm run selftest && npm run sizecheck && npm run registry:check",
     "publish:dry": "npm run release:check && npm --cache /tmp/sks-npm-cache publish --dry-run --registry https://registry.npmjs.org/ --access public",
     "publish:npm": "npm --cache /tmp/sks-npm-cache publish --registry https://registry.npmjs.org/ --access public",
     "prepublishOnly": "npm run release:check && node ./scripts/release-registry-check.mjs --require-unpublished"

package/src/cli/feature-commands.mjs

@@ -0,0 +1,131 @@
+import path from 'node:path';
+import { projectRoot } from '../core/fsx.mjs';
+import { CODEX_ACCESS_TOKENS_DOCS_URL } from '../core/codex-app.mjs';
+import { buildAllFeaturesSelftest, buildFeatureRegistry, validateFeatureRegistry, writeFeatureInventoryDocs } from '../core/feature-registry.mjs';
+
+const flag = (args, name) => args.includes(name);
+
+export async function featuresCommand(sub = 'list', args = []) {
+  const action = sub || 'list';
+  const root = await projectRoot();
+  if (action === 'list' || action === 'status' || action === 'registry') {
+    const registry = await buildFeatureRegistry({ root });
+    if (flag(args, '--json')) return console.log(JSON.stringify(registry, null, 2));
+    printFeatureRegistrySummary(registry);
+    if (!registry.coverage.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'check') {
+    const registry = await buildFeatureRegistry({ root });
+    const coverage = validateFeatureRegistry(registry);
+    const result = { schema: 'sks.feature-registry-check.v1', generated_at: registry.generated_at, ok: coverage.ok, coverage };
+    if (flag(args, '--json')) console.log(JSON.stringify(result, null, 2));
+    else printFeatureCoverage(coverage);
+    if (!coverage.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'inventory') {
+    const writeDocs = flag(args, '--write-docs');
+    const result = writeDocs
+      ? await writeFeatureInventoryDocs({ root })
+      : { ok: true, registry: await buildFeatureRegistry({ root }), path: path.join(root, 'docs', 'feature-inventory.md') };
+    if (flag(args, '--json')) return console.log(JSON.stringify({ ok: result.ok, path: result.path, coverage: result.registry.coverage }, null, 2));
+    if (writeDocs) console.log(`Feature inventory written: ${path.relative(root, result.path)}`);
+    printFeatureRegistrySummary(result.registry);
+    if (!result.registry.coverage.ok) process.exitCode = 1;
+    return;
+  }
+  console.error('Usage: sks features list|check|inventory [--json] [--write-docs]');
+  process.exitCode = 1;
+}
+
+export async function allFeaturesCommand(sub = 'selftest', args = []) {
+  const action = sub || 'selftest';
+  if (action !== 'selftest') {
+    console.error('Usage: sks all-features selftest --mock [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const root = await projectRoot();
+  const registry = await buildFeatureRegistry({ root });
+  const result = buildAllFeaturesSelftest(registry);
+  if (flag(args, '--json')) console.log(JSON.stringify(result, null, 2));
+  else {
+    console.log('SKS all-features selftest');
+    console.log(`Status: ${result.status}`);
+    for (const check of result.checks) console.log(`- ${check.ok ? 'ok' : 'blocked'} ${check.id}${check.blockers.length ? `: ${check.blockers.join(', ')}` : ''}`);
+    if (result.note) console.log(`\n${result.note}`);
+  }
+  if (!result.ok) process.exitCode = 1;
+}
+
+export function hooksCommand(sub = 'explain', args = []) {
+  const action = sub || 'explain';
+  if (action !== 'explain' && action !== 'status') {
+    console.error('Usage: sks hooks explain [--json]');
+    process.exitCode = 1;
+    return;
+  }
+  const report = hooksExplainReport();
+  if (flag(args, '--json')) return console.log(JSON.stringify(report, null, 2));
+  console.log('SKS hooks explain\n');
+  console.log(`Status: ${report.status}`);
+  console.log(`Feature key: ${report.feature_key}`);
+  console.log(`Config paths: ${report.config_paths.join(', ')}`);
+  console.log(`Events: ${report.events.join(', ')}`);
+  console.log(`Handlers: ${report.handlers.supported.join(', ')} supported; ${report.handlers.parsed_but_skipped.join(', ')} parsed but skipped`);
+  console.log('\nPolicies:');
+  for (const policy of report.sks_policies) console.log(`- ${policy}`);
+  console.log('\nSources:');
+  for (const source of report.sources) console.log(`- ${source.title}: ${source.url}`);
+}
+
+export function hooksExplainReport() {
+  return {
+    schema: 'sks.hooks-explain.v1',
+    status: 'supported_by_official_docs_and_local_config',
+    feature_key: 'features.hooks',
+    deprecated_feature_alias: 'features.codex_hooks',
+    config_paths: ['~/.codex/hooks.json', '~/.codex/config.toml', '<repo>/.codex/hooks.json', '<repo>/.codex/config.toml'],
+    events: ['SessionStart', 'PreToolUse', 'PermissionRequest', 'PostToolUse', 'UserPromptSubmit', 'Stop'],
+    handlers: {
+      supported: ['command'],
+      parsed_but_skipped: ['prompt', 'agent'],
+      async_command_hooks: 'parsed_but_not_supported'
+    },
+    runtime_notes: [
+      'Matching hooks from multiple files all run.',
+      'Multiple matching command hooks for the same event are launched concurrently.',
+      'Project-local hooks require a trusted project .codex layer.',
+      'Repo-local hook commands should resolve from git root instead of assuming the session cwd.'
+    ],
+    sks_policies: [
+      'secret_scan_policy',
+      'directory_rule_policy',
+      'db_safety_policy',
+      'visual_claim_source_policy',
+      'proof_required_policy',
+      'codex_lb_health_policy'
+    ],
+    sources: [
+      { title: 'OpenAI Codex Hooks', url: 'https://developers.openai.com/codex/hooks' },
+      { title: 'OpenAI Codex Configuration Reference', url: 'https://developers.openai.com/codex/config-reference' },
+      { title: 'OpenAI Codex Access Tokens', url: CODEX_ACCESS_TOKENS_DOCS_URL }
+    ]
+  };
+}
+
+function printFeatureRegistrySummary(registry) {
+  console.log('SKS feature registry\n');
+  console.log(`Schema:   ${registry.schema}`);
+  console.log(`Features: ${registry.features.length}`);
+  printFeatureCoverage(registry.coverage);
+}
+
+function printFeatureCoverage(coverage = {}) {
+  console.log(`Coverage: ${coverage.ok ? 'ok' : 'blocked'} (${coverage.status || 'unknown'})`);
+  for (const [kind, values] of Object.entries(coverage.unmapped || {})) {
+    console.log(`- ${kind}: ${values.length ? values.join(', ') : 'none'}`);
+  }
+  if (coverage.blockers?.length) console.log(`Blockers: ${coverage.blockers.join(', ')}`);
+}

package/src/cli/install-helpers.mjs

@@ -95,6 +95,17 @@ async function reportPostinstallCodexLbAuth() {
   } else if (reconcile?.status === 'failed') {
     console.log(`codex-lb auth: ChatGPT OAuth reconciliation could not complete (${reconcile.reason || 'unknown'}${reconcile.error ? `: ${reconcile.error}` : ''}). Run \`sks codex-lb repair\` to retry.`);
   }
+  if (codexLbAuth.base_url && codexLbAuth.codex_lb?.env_key_configured && canAskYesNo() && process.env.SKS_SKIP_CODEX_LB_KEY_PROMPT !== '1') {
+    const changeKey = (await askPostinstallQuestion('codex-lb key changed? Update now? [y/N] ')).trim();
+    if (/^(y|yes|예|네|응)$/i.test(changeKey)) {
+      const newKey = (await askPostinstallQuestion('New codex-lb API key (sk-clb-...): ')).trim();
+      if (newKey) {
+        const result = await configureCodexLb({ host: codexLbAuth.base_url, apiKey: newKey });
+        if (result.ok) console.log(`codex-lb key updated: ${result.base_url}`);
+        else console.log(`codex-lb key update failed: ${result.status}${result.error ? `: ${result.error}` : ''}`);
+      }
+    }
+  }
   return codexLbAuth;
 }
 
@@ -457,6 +468,7 @@ export async function repairCodexLbAuth(opts = {}) {
       codex_lb: status
     };
   }
+  await migrateCodexAuthKeyFormat({ home: opts.home });
   const codexEnvironment = await syncCodexLbProviderEnvironment(status, opts);
   const apiKey = parseCodexLbEnvKey(await readText(status.env_path, ''));
   const codexLogin = await maybeSyncCodexLbSharedLogin(apiKey, { ...opts, home: opts.home || process.env.HOME || os.homedir(), force: true });
@@ -482,6 +494,7 @@ export async function ensureCodexLbAuthDuringInstall(opts = {}) {
   if (process.env.SKS_SKIP_POSTINSTALL_CODEX_LB_AUTH === '1' && !opts.force) return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_CODEX_LB_AUTH=1' };
   const status = await codexLbStatus(opts);
   if (!status.selected && !status.provider_configured && !status.env_file) return { status: 'not_configured', codex_lb: status };
+  await migrateCodexAuthKeyFormat({ home: opts.home });
   if (status.ok && (!status.selected || !status.provider_requires_openai_auth)) return repairCodexLbAuth(opts);
   if (!status.ok) {
     if (status.base_url && (status.env_key_configured || status.provider_configured || status.selected || status.env_base_url_configured)) return repairCodexLbAuth(opts);
@@ -552,6 +565,28 @@ function parseCodexAuthApiKey(text = '') {
   }
 }
 
+// Migrate auth.json from legacy {"auth_mode":"apikey","key":"..."} to the codex 0.130.0+
+// format {"auth_mode":"apikey","OPENAI_API_KEY":"..."}. Safe: preserves key value, only renames field.
+async function migrateCodexAuthKeyFormat(opts = {}) {
+  const home = opts.home || process.env.HOME || os.homedir();
+  const authPath = opts.authPath || codexAuthPath(home);
+  const text = await readText(authPath, '');
+  if (!text.trim()) return { status: 'skipped', reason: 'empty' };
+  try {
+    const parsed = JSON.parse(text);
+    if (parsed?.auth_mode !== 'apikey') return { status: 'skipped', reason: 'not_apikey' };
+    if (parsed.OPENAI_API_KEY) return { status: 'skipped', reason: 'already_migrated' };
+    const legacyKey = parsed.key || parsed.api_key || parsed.apiKey || parsed.openai_api_key;
+    if (!legacyKey) return { status: 'skipped', reason: 'no_key_found' };
+    const replacement = `${JSON.stringify({ auth_mode: 'apikey', OPENAI_API_KEY: legacyKey })}\n`;
+    await writeTextAtomic(authPath, replacement);
+    await fsp.chmod(authPath, 0o600).catch(() => {});
+    return { status: 'migrated', auth_path: authPath };
+  } catch {
+    return { status: 'skipped', reason: 'parse_error' };
+  }
+}
+
 // When codex-lb is selected with env_key auth AND auth.json also carries a real ChatGPT OAuth
 // token blob, Codex CLI/App can pick the OAuth bearer over the env_key bearer and fail against
 // the load balancer. We back the OAuth blob up to ~/.codex/auth.chatgpt-backup.json and replace
@@ -597,7 +632,7 @@ export async function reconcileCodexLbAuthConflict(opts = {}) {
     };
   }
   try {
-    const replacement = `${JSON.stringify({ auth_mode: 'apikey', key: apiKey }, null, 2)}\n`;
+    const replacement = `${JSON.stringify({ auth_mode: 'apikey', OPENAI_API_KEY: apiKey }, null, 2)}\n`;
     await writeTextAtomic(authPath, replacement);
     await fsp.chmod(authPath, 0o600).catch(() => {});
   } catch (err) {
@@ -1567,7 +1602,7 @@ export async function selftestCodexLb(tmp) {
   // NOTE: printf format uses literal double-quotes inside single-quoted shell strings so the
   // fake login writes proper JSON in both bash and dash (where `\"` is a non-standard printf
   // escape that dash emits literally and bash collapses to `"`).
-  await writeTextAtomic(codexLbFakeCodex, "#!/bin/sh\nif [ \"$1\" = \"--version\" ]; then echo \"codex-cli 99.0.0\"; exit 0; fi\nif [ \"$1\" = \"login\" ] && [ \"$2\" = \"status\" ]; then echo \"logged in with browser auth\"; exit 0; fi\nif [ \"$1\" = \"login\" ] && [ \"$2\" = \"--with-api-key\" ]; then read key; mkdir -p \"$HOME/.codex\"; printf '{\"auth_mode\":\"apikey\",\"key\":\"%s\"}\\n' \"$key\" > \"$HOME/.codex/auth.json\"; printf '%s\\n' \"$key\" >> \"$HOME/.codex/login-calls.log\"; exit 0; fi\necho \"fake codex unsupported\" >&2\nexit 1\n");
+  await writeTextAtomic(codexLbFakeCodex, "#!/bin/sh\nif [ \"$1\" = \"--version\" ]; then echo \"codex-cli 99.0.0\"; exit 0; fi\nif [ \"$1\" = \"login\" ] && [ \"$2\" = \"status\" ]; then echo \"logged in with browser auth\"; exit 0; fi\nif [ \"$1\" = \"login\" ] && [ \"$2\" = \"--with-api-key\" ]; then read key; mkdir -p \"$HOME/.codex\"; printf '{\"auth_mode\":\"apikey\",\"OPENAI_API_KEY\":\"%s\"}\\n' \"$key\" > \"$HOME/.codex/auth.json\"; printf '%s\\n' \"$key\" >> \"$HOME/.codex/login-calls.log\"; exit 0; fi\necho \"fake codex unsupported\" >&2\nexit 1\n");
   await fsp.chmod(codexLbFakeCodex, 0o755);
   await writeTextAtomic(path.join(codexLbHome, '.codex', 'config.toml'), 'model = "gpt-5.5"\nmodel_reasoning_effort = "low"\nservice_tier = "fast"\n\n[profiles.custom]\nmodel_reasoning_effort = "low"\n\n[notice]\nfast_default_opt_out = true\n\n[features]\ncodex_hooks = true\n');
   const codexLbEnvForSelftest = { HOME: codexLbHome, SKS_GLOBAL_ROOT: path.join(tmp, 'codex-lb-global'), PATH: `${codexLbFakeBin}${path.delimiter}${process.env.PATH || ''}`, SKS_SKIP_CODEX_LB_LAUNCH_ENV: '1' };
@@ -1710,7 +1745,7 @@ export async function selftestCodexLb(tmp) {
   // the provider stays selected and whether the backup file is removed after restore.
   const codexLbReleaseConfig = 'model_provider = "codex-lb"\n\n[model_providers.codex-lb]\nname = "OpenAI"\nbase_url = "https://lb.example.test/backend-api/codex"\nwire_api = "responses"\nenv_key = "CODEX_LB_API_KEY"\nsupports_websockets = true\nrequires_openai_auth = true\n';
   const codexLbReleaseEnv = "export CODEX_LB_BASE_URL='https://lb.example.test/backend-api/codex'\nexport CODEX_LB_API_KEY='sk-test'\n";
-  const codexLbReleaseApikeyAuth = '{"auth_mode":"apikey","key":"sk-test"}\n';
+  const codexLbReleaseApikeyAuth = '{"auth_mode":"apikey","OPENAI_API_KEY":"sk-test"}\n';
   const codexLbReleaseOauthBackup = `${oauthAuthJson}\n`;
   // Happy path: deselect model_provider and preserve backup file.
   await writeTextAtomic(path.join(codexLbHome, '.codex', 'auth.json'), codexLbReleaseApikeyAuth);

package/src/cli/main.mjs

@@ -73,8 +73,10 @@ import { MISTAKE_RECALL_ARTIFACT, contractConsumesMistakeRecall } from '../core/
 import { buildPromptContext } from '../core/prompt-context-builder.mjs';
 import { renderTeamDashboardState, writeTeamDashboardState } from '../core/team-dashboard-renderer.mjs';
 import { GOAL_WORKFLOW_ARTIFACT } from '../core/goal-workflow.mjs';
-import { CODEX_APP_DOCS_URL, codexAppIntegrationStatus, formatCodexAppStatus } from '../core/codex-app.mjs';
+import { CODEX_APP_DOCS_URL, codexAccessTokenStatus, codexAppIntegrationStatus, formatCodexAppStatus } from '../core/codex-app.mjs';
+import { buildAllFeaturesSelftest, buildFeatureRegistry, validateFeatureRegistry } from '../core/feature-registry.mjs';
 import { codexAppRemoteControlCommand } from './codex-app-command.mjs';
+import { allFeaturesCommand, featuresCommand, hooksCommand, hooksExplainReport } from './feature-commands.mjs';
 import { OPENCLAW_SKILL_NAME, installOpenClawSkill } from '../core/openclaw.mjs';
 import { buildTmuxLaunchPlan, buildTmuxOpenArgs, codexLaunchCommand, createTmuxSession, defaultCodexLaunchArgs, isTmuxShellSession, runTmuxLaunchPlanSyntaxCheck, shouldAutoAttachTmux, sksAsciiLogo, tmuxReadiness, tmuxStatusKind, defaultTmuxSessionName, formatTmuxBanner, launchMadTmuxUi, launchTmuxTeamView, launchTmuxUi, platformTmuxInstallHint, reconcileTmuxTeamCockpit, runTmuxStatus, sanitizeTmuxSessionName, sweepCodexLbTmuxSessions, sweepTmuxTeamSurfaces, teamLaneStyle } from '../core/tmux-ui.mjs';
 import { autoReviewProfileName, autoReviewStatus, autoReviewSummary, enableAutoReview, disableAutoReview, enableMadHighProfile, madHighProfileName } from '../core/auto-review.mjs';
@@ -111,7 +113,7 @@ export async function main(args) {
   if (String(cmd).toLowerCase() === 'dfix') return dfixHelp();
   const handlers = {
     postinstall: () => postinstall({ bootstrap }), wizard: () => wizard(tail), ui: () => wizard(tail), 'update-check': () => updateCheck(tail), help: () => help(tail), commands: () => commands(tail), usage: () => usage(tail), root: () => rootCommand(tail), quickstart: () => quickstartCommand(), 'codex-app': () => codexAppHelp(tail), 'codex-lb': () => codexLbCommand(sub, rest), auth: () => codexLbCommand(sub, rest), openclaw: () => openClawCommand(tail), bootstrap: () => bootstrap(tail), deps: () => deps(sub, rest),
-    'qa-loop': () => qaLoopCommand(sub, rest), ppt: () => pptCommand(sub, rest), 'image-ux-review': () => imageUxReviewCommand(sub, rest), 'ux-review': () => imageUxReviewCommand(sub, rest), 'visual-review': () => imageUxReviewCommand(sub, rest), 'ui-ux-review': () => imageUxReviewCommand(sub, rest), context7: () => context7Command(sub, rest), recallpulse: () => recallPulseCommand(sub, rest), pipeline: () => pipeline(sub, rest), guard: () => guard(sub, rest), conflicts: () => conflicts(sub, rest), versioning: () => versioning(sub, rest), reasoning: () => reasoningCommand(tail), aliases: () => aliases(), setup: () => setup(tail), 'fix-path': () => fixPath(tail), doctor: () => doctor(tail), init: () => init(tail), selftest: () => selftest(tail),
+    'qa-loop': () => qaLoopCommand(sub, rest), ppt: () => pptCommand(sub, rest), 'image-ux-review': () => imageUxReviewCommand(sub, rest), 'ux-review': () => imageUxReviewCommand(sub, rest), 'visual-review': () => imageUxReviewCommand(sub, rest), 'ui-ux-review': () => imageUxReviewCommand(sub, rest), context7: () => context7Command(sub, rest), recallpulse: () => recallPulseCommand(sub, rest), pipeline: () => pipeline(sub, rest), guard: () => guard(sub, rest), conflicts: () => conflicts(sub, rest), versioning: () => versioning(sub, rest), features: () => featuresCommand(sub, rest), 'all-features': () => allFeaturesCommand(sub, rest), hooks: () => hooksCommand(sub, rest), reasoning: () => reasoningCommand(tail), aliases: () => aliases(), setup: () => setup(tail), 'fix-path': () => fixPath(tail), doctor: () => doctor(tail), init: () => init(tail), selftest: () => selftest(tail),
     goal: () => goalCommand(sub, rest), research: () => researchCommand(sub, rest), hook: () => emitHook(sub), profile: () => profileCommand(sub, rest), hproof: () => hproofCommand(sub, rest), 'validate-artifacts': () => validateArtifactsCommand(tail), perf: () => perfCommand(sub, rest), 'proof-field': () => proofFieldCommand(sub, rest), 'skill-dream': () => skillDreamCommand(sub, rest), 'code-structure': () => codeStructureCommand(sub, rest), memory: () => memoryCommand(sub, rest), gx: () => gxCommand(sub, rest),
     team: () => team(tail), db: () => dbCommand(sub, rest), eval: () => evalCommand(sub, rest), harness: () => harnessCommand(sub, rest), wiki: () => wikiCommand(sub, rest), gc: () => gcCommand(tail), stats: () => statsCommand(tail)
   };
@@ -188,6 +190,8 @@ Usage:
   sks bootstrap [--install-scope global|project] [--local-only] [--json]
   sks deps check|install [tmux|codex|context7|all] [--yes] [--json]
   sks codex-app
+  sks codex-app pat status [--json]
+  sks hooks explain [--json]
   sks codex-lb status|health|repair|release|unselect|setup --host <domain> --api-key <key>
   sks auth status|health|repair|release|unselect|setup --host <domain> --api-key <key>
   sks openclaw install|path|print [--dir path] [--force] [--json]
@@ -218,6 +222,8 @@ Usage:
   sks doctor [--fix] [--local-only] [--json] [--install-scope global|project]
   sks init [--install-scope global|project] [--local-only]
   sks selftest [--mock]
+  sks features list|check|inventory [--json] [--write-docs]
+  sks all-features selftest --mock [--json]
   sks goal create "task"
   sks goal pause|resume|clear <mission-id|latest>
   sks goal status <mission-id|latest>
@@ -1248,13 +1254,20 @@ async function codexLbCommand(action = 'status', args = []) {
     return;
   }
   if (sub === 'setup' || sub === 'reconfigure') {
-    const host = readOption(args, '--host', readOption(args, '--domain', null));
-    const apiKey = readOption(args, '--api-key', readOption(args, '--key', null));
+    let host = readOption(args, '--host', readOption(args, '--domain', null));
+    let apiKey = readOption(args, '--api-key', readOption(args, '--key', null));
     if (!host || !apiKey) {
       if (json) return console.log(JSON.stringify({ ok: false, reason: 'missing_host_or_api_key' }, null, 2));
-      console.error('Usage: sks codex-lb setup|reconfigure --host <domain> --api-key <key>');
-      process.exitCode = 1;
-      return;
+      if (!canAskYesNo()) {
+        console.error('Usage: sks codex-lb setup|reconfigure --host <domain> --api-key <key>');
+        process.exitCode = 1;
+        return;
+      }
+      console.log('codex-lb setup — configure your Codex load balancer connection.\n');
+      if (!host) host = (await askPostinstallQuestion('Your codex-lb domain (e.g. https://codex.example.com/backend-api/codex): ')).trim();
+      if (!host) { console.error('Setup cancelled: no domain provided.'); process.exitCode = 1; return; }
+      if (!apiKey) apiKey = (await askPostinstallQuestion('Your codex-lb API key (sk-clb-...): ')).trim();
+      if (!apiKey) { console.error('Setup cancelled: no API key provided.'); process.exitCode = 1; return; }
     }
     const result = await configureCodexLb({ host, apiKey });
     if (json) return console.log(JSON.stringify(result, null, 2));
@@ -1492,6 +1505,23 @@ async function autoReviewCommand(sub = 'status', args = []) {
 async function codexAppHelp(args = []) {
   const action = args[0] || 'help';
   if (action === 'remote-control' || action === 'remote') return codexAppRemoteControlCommand(args.slice(1));
+  if (action === 'pat') {
+    const patAction = args[1] || 'status';
+    if (patAction !== 'status' && patAction !== 'check') {
+      console.error('Usage: sks codex-app pat status [--json]');
+      process.exitCode = 1;
+      return;
+    }
+    const status = codexAccessTokenStatus();
+    if (flag(args, '--json')) return console.log(JSON.stringify(status, null, 2));
+    console.log('Codex App PAT status\n');
+    console.log(`Status: ${status.status}`);
+    console.log(`Docs:   ${status.docs_url}`);
+    console.log(`Policy: ${status.storage_policy}`);
+    for (const entry of status.access_token_env_vars) console.log(`${entry.name}: ${entry.present ? entry.value : 'missing'}`);
+    for (const warning of status.warnings) console.log(`- ${warning}`);
+    return;
+  }
   if (action === 'check' || action === 'status') {
     const status = await codexAppIntegrationStatus();
     const skills = await codexAppSkillReadiness();
@@ -1519,7 +1549,7 @@ async function codexAppHelp(args = []) {
     'Codex App', '',
     formatCodexAppStatus(status), '',
     `Skills: project=${skills.project.ok ? 'ok' : `missing ${skills.project.missing.length}`} global=${skills.global.ok ? 'ok' : `missing ${skills.global.missing.length}`}`, '',
-    'Setup:', '  sks bootstrap', '  sks deps check', '  sks codex-app check', '  sks codex-app remote-control --status', '  sks tmux check', '',
+    'Setup:', '  sks bootstrap', '  sks deps check', '  sks codex-app check', '  sks codex-app pat status', '  sks codex-app remote-control --status', '  sks tmux check', '',
     'Generated files:', '  .codex/config.toml', '  .codex/hooks.json', '  .agents/skills/', '  .codex/agents/', '  .codex/SNEAKOSCOPE.md', '  AGENTS.md', '',
     'Git ignore:', '  default setup writes .gitignore entries for .sneakoscope/, .codex/, .agents/, AGENTS.md', '  --local-only writes those patterns to .git/info/exclude instead', '',
     'Prompt routes:', formatDollarCommandsCompact('  ')
@@ -2710,7 +2740,18 @@ async function selftest() {
   if (!DOLLAR_DEFAULT_PIPELINE_TEXT.includes('$From-Chat-IMG')) throw new Error('selftest: dollar-commands missing From-Chat-IMG guidance');
   if (!DOLLAR_DEFAULT_PIPELINE_TEXT.includes('$MAD-SKS')) throw new Error('selftest: dollar-commands missing MAD-SKS scoped override guidance');
   if (!DOLLAR_DEFAULT_PIPELINE_TEXT.includes('$Image-UX-Review')) throw new Error('selftest: dollar-commands missing Image UX Review guidance');
-  if (!COMMAND_CATALOG.some((c) => c.name === 'context7') || !COMMAND_CATALOG.some((c) => c.name === 'pipeline') || !COMMAND_CATALOG.some((c) => c.name === 'qa-loop') || !COMMAND_CATALOG.some((c) => c.name === 'image-ux-review') || !COMMAND_CATALOG.some((c) => c.name === 'root') || !COMMAND_CATALOG.some((c) => c.name === 'openclaw')) throw new Error('selftest: context7/pipeline/qa-loop/image-ux-review/root/openclaw commands missing from catalog');
+  for (const name of ['context7', 'pipeline', 'qa-loop', 'image-ux-review', 'root', 'openclaw', 'hooks', 'features', 'all-features']) {
+    if (!COMMAND_CATALOG.some((c) => c.name === name)) throw new Error(`selftest: catalog missing ${name}`);
+  }
+  const featureRegistry = await buildFeatureRegistry({ root: packageRoot() });
+  const featureCoverage = validateFeatureRegistry(featureRegistry);
+  if (!featureCoverage.ok) throw new Error(`selftest: feature registry coverage blocked: ${featureCoverage.blockers.join(', ')}`);
+  const allFeaturesResult = buildAllFeaturesSelftest(featureRegistry);
+  if (!allFeaturesResult.ok) throw new Error(`selftest: all-features contract blocked: ${allFeaturesResult.checks.filter((check) => !check.ok).map((check) => check.id).join(', ')}`);
+  const patRedactionProbe = codexAccessTokenStatus({ CODEX_ACCESS_TOKEN: 'secret-probe-value', CODEX_LB_API_KEY: 'lb-secret-probe' });
+  if (patRedactionProbe.status !== 'present_redacted' || JSON.stringify(patRedactionProbe).includes('secret-probe-value') || JSON.stringify(patRedactionProbe).includes('lb-secret-probe')) throw new Error('selftest: Codex access token status leaked a token value');
+  const hooksReport = hooksExplainReport();
+  if (!hooksReport.events.includes('UserPromptSubmit') || !hooksReport.events.includes('Stop') || !hooksReport.sources.some((source) => source.url.includes('/access-tokens'))) throw new Error('selftest: hooks explain coverage');
   const openClawTmp = tmpdir();
   const openClawResult = await installOpenClawSkill({ targetDir: path.join(openClawTmp, 'skills', OPENCLAW_SKILL_NAME) });
   if (!openClawResult.ok) throw new Error(`selftest: OpenClaw skill install blocked: ${openClawResult.reason}`);

package/src/core/codex-app.mjs

@@ -7,6 +7,7 @@ import { DEFAULT_CODEX_APP_PLUGINS as DEFAULT_CODEX_APP_PLUGIN_TUPLES, RESERVED_
 
 export const CODEX_APP_DOCS_URL = 'https://developers.openai.com/codex/app/features';
 export const CODEX_CHANGELOG_URL = 'https://developers.openai.com/codex/changelog';
+export const CODEX_ACCESS_TOKENS_DOCS_URL = 'https://developers.openai.com/codex/enterprise/access-tokens';
 export const CODEX_REMOTE_CONTROL_MIN_VERSION = '0.130.0';
 const REQUIRED_CODEX_APP_FEATURE_FLAGS = [
   'codex_git_commit',
@@ -253,6 +254,37 @@ export function formatCodexRemoteControlStatus(status) {
   return lines.filter(Boolean).join('\n');
 }
 
+export function codexAccessTokenStatus(env = process.env) {
+  const accessTokenVars = ['CODEX_ACCESS_TOKEN'];
+  const adjacentSecretVars = ['OPENAI_API_KEY', 'CODEX_LB_API_KEY'];
+  const accessTokens = accessTokenVars.map((name) => ({ name, present: Boolean(env[name]), value: env[name] ? '[redacted]' : null }));
+  const adjacentSecrets = adjacentSecretVars.map((name) => ({ name, present: Boolean(env[name]), value: env[name] ? '[redacted]' : null }));
+  const extraTokenLikeVars = Object.keys(env)
+    .filter((name) => /(?:CODEX|OPENAI|CHATGPT).*TOKEN/i.test(name) && !accessTokenVars.includes(name))
+    .sort()
+    .map((name) => ({ name, present: true, value: '[redacted]' }));
+  const present = accessTokens.some((entry) => entry.present);
+  return {
+    schema: 'sks.codex-access-token-status.v1',
+    ok: true,
+    status: present ? 'present_redacted' : 'missing',
+    supported_for: 'ChatGPT Business and Enterprise workspace programmatic local Codex workflows',
+    docs_url: CODEX_ACCESS_TOKENS_DOCS_URL,
+    official_cli_ingest: 'codex login --with-access-token reads CODEX_ACCESS_TOKEN from stdin when the caller provides it',
+    storage_policy: 'Store access tokens in an external secret manager or ephemeral environment variable; never write plaintext tokens into .sneakoscope, hooks, proof, stdout, stderr, or screenshots.',
+    access_token_env_vars: accessTokens,
+    adjacent_secret_env_vars: adjacentSecrets,
+    extra_token_like_env_vars: extraTokenLikeVars,
+    redaction: {
+      ok: true,
+      strategy: 'presence-only reporting with literal [redacted] value placeholders'
+    },
+    warnings: present
+      ? ['Token presence was detected without printing the value. Rotate regularly and use only trusted runners.']
+      : ['No CODEX_ACCESS_TOKEN detected in the current process environment. This is fine for interactive ChatGPT login or API-key auth.']
+  };
+}
+
 export function codexAppGuidance({ appInstalled, codex, mcpList, featureList, requiredFeatureFlags = {}, requiredFeatureFlagsOk = true, defaultPlugins = { ok: true, missing_enabled: [] }, pluginSkillShadows = { ok: true, blocking: [] }, fastModeConfig = { ok: true, blockers: [] }, gitActions = { ok: true, blockers: [] }, imageGenerationReady, inAppBrowserReady, browserUseFeatureReady, computerUseReady, browserUseReady, browserToolReady, computerUseMcpListed, browserUseMcpListed, remoteControl }) {
   const lines = [];
   if (!appInstalled) {

package/src/core/feature-registry.mjs

@@ -0,0 +1,461 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { COMMAND_CATALOG, DOLLAR_COMMAND_ALIASES, DOLLAR_COMMANDS } from './routes.mjs';
+import { exists, nowIso, packageRoot, readJson, readText, writeTextAtomic } from './fsx.mjs';
+
+export const FEATURE_REGISTRY_SCHEMA = 'sks.feature-registry.v1';
+export const FEATURE_INVENTORY_SCHEMA = 'sks.feature-inventory.v1';
+export const ALL_FEATURES_SELFTEST_SCHEMA = 'sks.all-features-selftest.v1';
+
+const HANDLER_ALIAS_TO_COMMAND = Object.freeze({
+  ui: 'wizard',
+  auth: 'codex-lb',
+  hook: 'hooks',
+  memory: 'gc',
+  postinstall: 'postinstall',
+  'ux-review': 'image-ux-review',
+  'visual-review': 'image-ux-review',
+  'ui-ux-review': 'image-ux-review'
+});
+
+const FEATURE_ACCEPTANCE_DEFAULTS = Object.freeze([
+  'contracts tracked',
+  'unknowns explicit',
+  'release-mapped'
+]);
+
+export async function buildFeatureRegistry({ root = packageRoot(), generatedAt = nowIso() } = {}) {
+  const handlerKeys = await parseMainHandlerKeys(root);
+  const skillNames = await listProjectSkillNames(root);
+  const docRouteMentions = await collectDocRouteMentions(root);
+  const handlerToFeature = mapHandlerKeysToFeatureIds(handlerKeys);
+  const features = [];
+
+  for (const command of COMMAND_CATALOG) {
+    const handlerAliases = Object.entries(handlerToFeature)
+      .filter(([, featureId]) => featureId === `cli-${command.name}`)
+      .map(([handler]) => handler)
+      .filter((handler) => handler !== command.name);
+    features.push(commandFeature(command, handlerAliases));
+  }
+
+  for (const handler of handlerKeys) {
+    const featureId = handlerToFeature[handler];
+    if (!features.some((feature) => feature.id === featureId)) {
+      features.push(hiddenHandlerFeature(handler));
+    }
+  }
+
+  for (const route of DOLLAR_COMMANDS) features.push(routeFeature(route));
+  for (const skillName of skillNames) {
+    if (!skillCoveredByRoute(skillName)) features.push(skillFeature(skillName));
+  }
+
+  const registry = {
+    schema: FEATURE_REGISTRY_SCHEMA,
+    generated_at: generatedAt,
+    inventory_sources: {
+      commands_json: 'sks commands --json',
+      main_handlers: 'src/cli/main.mjs',
+      dollar_routes: 'src/core/routes.mjs',
+      docs: ['README.md', '.codex/SNEAKOSCOPE.md', 'AGENTS.md', '.agents/skills/.sks-generated.json'],
+      skills: '.agents/skills'
+    },
+    features,
+    source_inventory: {
+      cli_command_names: COMMAND_CATALOG.map((entry) => entry.name),
+      handler_keys: handlerKeys,
+      dollar_commands: DOLLAR_COMMANDS.map((entry) => entry.command),
+      app_skill_aliases: DOLLAR_COMMAND_ALIASES.map((entry) => entry.app_skill),
+      skills: skillNames,
+      doc_route_mentions: docRouteMentions
+    }
+  };
+  registry.coverage = validateFeatureRegistry(registry);
+  return registry;
+}
+
+export function validateFeatureRegistry(registry = {}) {
+  const features = Array.isArray(registry.features) ? registry.features : [];
+  const source = registry.source_inventory || {};
+  const mappedCli = new Set(flatMapSourceRefs(features, 'cli_command_names'));
+  const mappedHandlers = new Set(flatMapSourceRefs(features, 'handler_keys'));
+  const mappedRoutes = new Set(flatMapSourceRefs(features, 'dollar_commands'));
+  const mappedAliases = new Set(flatMapSourceRefs(features, 'app_skill_aliases'));
+  const mappedSkills = new Set(flatMapSourceRefs(features, 'skills'));
+  const mappedRouteMentions = new Set([...mappedRoutes, ...mappedAliases].map(normalizeDollar));
+
+  const unmapped = {
+    cli_command_names: (source.cli_command_names || []).filter((name) => !mappedCli.has(name)),
+    handler_keys: (source.handler_keys || []).filter((name) => !mappedHandlers.has(name)),
+    dollar_commands: (source.dollar_commands || []).filter((name) => !mappedRoutes.has(name)),
+    app_skill_aliases: (source.app_skill_aliases || []).filter((name) => !mappedAliases.has(name)),
+    skills: (source.skills || []).filter((name) => !mappedSkills.has(name))
+  };
+  const duplicateFeatureIds = duplicateValues(features.map((feature) => feature.id));
+  const routeMentionsWithoutRoute = (source.doc_route_mentions || [])
+    .filter((mention) => !mappedRouteMentions.has(normalizeDollar(mention)) && !isExternalPromptCommandMention(mention));
+  const blockers = [
+    ...Object.entries(unmapped).flatMap(([kind, values]) => values.map((value) => `${kind}:${value}`)),
+    ...duplicateFeatureIds.map((id) => `duplicate_feature_id:${id}`),
+    ...routeMentionsWithoutRoute.map((mention) => `doc_route_mention_without_route:${mention}`)
+  ];
+  return {
+    ok: blockers.length === 0,
+    status: blockers.length ? 'blocked' : 'verified_partial',
+    counts: {
+      features: features.length,
+      cli_command_names: source.cli_command_names?.length || 0,
+      handler_keys: source.handler_keys?.length || 0,
+      dollar_commands: source.dollar_commands?.length || 0,
+      app_skill_aliases: source.app_skill_aliases?.length || 0,
+      skills: source.skills?.length || 0
+    },
+    unmapped,
+    duplicate_feature_ids: duplicateFeatureIds,
+    doc_route_mentions_without_route: routeMentionsWithoutRoute,
+    blockers,
+    nonblocking_known_gaps: [
+      'feature fixtures remain progressive',
+      'registry proves coverage, not full roadmap completion'
+    ]
+  };
+}
+
+export async function writeFeatureInventoryDocs({ root = packageRoot(), outFile = path.join(root, 'docs', 'feature-inventory.md') } = {}) {
+  const registry = await buildFeatureRegistry({ root });
+  const markdown = renderFeatureInventoryMarkdown(registry);
+  await writeTextAtomic(outFile, markdown);
+  return { ok: registry.coverage.ok, path: outFile, registry };
+}
+
+export function buildAllFeaturesSelftest(registry) {
+  const coverage = validateFeatureRegistry(registry);
+  const checks = [
+    checkRow('feature_registry_completeness', coverage.ok, coverage.blockers),
+    checkRow('command_lazy_load_availability', coverage.unmapped.cli_command_names.length === 0 && coverage.unmapped.handler_keys.length === 0, [...coverage.unmapped.cli_command_names, ...coverage.unmapped.handler_keys]),
+    checkRow('json_schema_validation', registry.schema === FEATURE_REGISTRY_SCHEMA && Array.isArray(registry.features), []),
+    checkRow('proof_integration_contracts_present', registry.features.every((feature) => Boolean(feature.completion_proof_integration)), missingFeatureField(registry, 'completion_proof_integration')),
+    checkRow('voxel_triwiki_contracts_present', registry.features.every((feature) => Boolean(feature.voxel_triwiki_integration)), missingFeatureField(registry, 'voxel_triwiki_integration')),
+    checkRow('failure_contracts_present', registry.features.every((feature) => Array.isArray(feature.known_gaps)), missingFeatureField(registry, 'known_gaps'))
+  ];
+  const ok = checks.every((check) => check.ok);
+  return {
+    schema: ALL_FEATURES_SELFTEST_SCHEMA,
+    generated_at: registry.generated_at || nowIso(),
+    ok,
+    status: ok ? 'verified_partial' : 'blocked',
+    checks,
+    coverage,
+    note: 'Mock selftest verifies the shared contract spine; feature fixtures remain progressive.'
+  };
+}
+
+export function renderFeatureInventoryMarkdown(registry) {
+  const coverage = registry.coverage || validateFeatureRegistry(registry);
+  const lines = [
+    '# SKS Feature Inventory',
+    '',
+    `Generated from \`${registry.inventory_sources.commands_json}\`, \`${registry.inventory_sources.main_handlers}\`, \`${registry.inventory_sources.dollar_routes}\`, docs, and skill manifests.`,
+    '',
+    '## Coverage',
+    '',
+    `- Status: ${coverage.ok ? 'coverage-ok' : 'blocked'}`,
+    `- Features: ${coverage.counts.features}`,
+    `- CLI commands: ${coverage.counts.cli_command_names}`,
+    `- Handler keys: ${coverage.counts.handler_keys}`,
+    `- Dollar routes: ${coverage.counts.dollar_commands}`,
+    `- App skill aliases: ${coverage.counts.app_skill_aliases}`,
+    `- Skills: ${coverage.counts.skills}`,
+    '',
+    '## Release Coverage Rule',
+    '',
+    '`sks features check --json` fails when a CLI command, hidden handler, dollar route, app skill alias, or project skill is not mapped to the feature registry. `npm run release:check` runs that check.',
+    '',
+    '## Stable / Beta / Labs Map',
+    '',
+    '| Feature | Category | Maturity | Commands / Routes | Known Gaps |',
+    '| --- | --- | --- | --- | --- |'
+  ];
+  for (const feature of registry.features) {
+    const commands = [...(feature.commands || []), ...(feature.aliases || [])].map(markdownTableCell).join('<br>');
+    const gaps = (feature.known_gaps || []).map(markdownTableCell).join('<br>') || 'none recorded';
+    lines.push(`| \`${feature.id}\` | ${feature.category} | ${feature.maturity} | ${commands || '-'} | ${gaps} |`);
+  }
+  lines.push('', '## Unmapped Coverage', '');
+  for (const [kind, values] of Object.entries(coverage.unmapped || {})) {
+    lines.push(`- ${kind}: ${values.length ? values.join(', ') : 'none'}`);
+  }
+  if (coverage.doc_route_mentions_without_route?.length) {
+    lines.push(`- doc_route_mentions_without_route: ${coverage.doc_route_mentions_without_route.join(', ')}`);
+  }
+  lines.push('', '## Prompt Checklist Coverage', '');
+  lines.push('- [x] Collected `sks commands --json` command surface via `COMMAND_CATALOG`.');
+  lines.push('- [x] Parsed `src/cli/main.mjs` handler keys, including hidden handlers and aliases.');
+  lines.push('- [x] Collected dollar routes and app skill aliases from `src/core/routes.mjs`.');
+  lines.push('- [x] Scanned README, Codex quick reference, AGENTS, and generated skill manifest for dollar-route mentions.');
+  lines.push('- [x] Mapped project skills from `.agents/skills` into the registry.');
+  lines.push('- [x] Exposed the registry through `sks features list --json`.');
+  lines.push('- [x] Added a release coverage check through `sks features check --json`.');
+  lines.push('');
+  return `${lines.join('\n')}\n`;
+}
+
+function commandFeature(command, handlerAliases = []) {
+  const name = command.name;
+  const category = commandCategory(name);
+  const maturity = commandMaturity(name);
+  const aliases = [...new Set(handlerAliases.map((alias) => `sks ${alias}`))];
+  return baseFeature({
+    id: `cli-${name}`,
+    commands: [command.usage],
+    aliases,
+    category,
+    maturity,
+    intent: command.description,
+    completion_proof_integration: proofContract(category),
+    voxel_triwiki_integration: voxelContract(category),
+    known_gaps: knownGapsForCommand(name),
+    source_refs: {
+      cli_command_names: [name],
+      handler_keys: [name, ...handlerAliases],
+      dollar_commands: [],
+      app_skill_aliases: [],
+      skills: []
+    }
+  });
+}
+
+function hiddenHandlerFeature(handler) {
+  return baseFeature({
+    id: `handler-${handler}`,
+    commands: [`sks ${handler}`],
+    aliases: [],
+    category: 'internal',
+    maturity: 'beta',
+    intent: `Hidden or internal handler for ${handler}.`,
+    voxel_triwiki_integration: 'context-anchor optional unless route output creates evidence',
+    completion_proof_integration: 'required for stateful route use',
+    known_gaps: ['hidden handler docs needed if promoted'],
+    source_refs: {
+      cli_command_names: [],
+      handler_keys: [handler],
+      dollar_commands: [],
+      app_skill_aliases: [],
+      skills: []
+    }
+  });
+}
+
+function routeFeature(route) {
+  const aliases = DOLLAR_COMMAND_ALIASES
+    .filter((entry) => entry.canonical === route.command)
+    .map((entry) => entry.app_skill);
+  return baseFeature({
+    id: `route-${slug(route.command)}`,
+    commands: [route.command],
+    aliases,
+    category: 'route',
+    maturity: routeMaturity(route.command),
+    intent: route.description,
+    voxel_triwiki_integration: routeVoxelContract(route.command),
+    completion_proof_integration: 'route gate, reflection, Honest Mode',
+    known_gaps: routeKnownGaps(route.command),
+    source_refs: {
+      cli_command_names: [],
+      handler_keys: [],
+      dollar_commands: [route.command],
+      app_skill_aliases: aliases,
+      skills: aliases.map((alias) => alias.replace(/^\$/, ''))
+    }
+  });
+}
+
+function skillFeature(skillName) {
+  return baseFeature({
+    id: `skill-${slug(skillName)}`,
+    commands: [],
+    aliases: [`$${skillName}`],
+    category: 'skill',
+    maturity: 'labs',
+    intent: `Codex skill surface for ${skillName}.`,
+    voxel_triwiki_integration: 'inherits owning route contract',
+    completion_proof_integration: 'inherits owning route proof',
+    known_gaps: ['runtime fixtures owned by route'],
+    source_refs: {
+      cli_command_names: [],
+      handler_keys: [],
+      dollar_commands: [],
+      app_skill_aliases: [],
+      skills: [skillName]
+    }
+  });
+}
+
+function baseFeature(feature) {
+  return {
+    contract: {
+      input: feature.commands?.[0] || feature.aliases?.[0] || 'skill invocation',
+      output: 'stdout/json/artifacts by command',
+      state: 'route state when stateful',
+      safety: 'policy-gated',
+      proof: feature.completion_proof_integration,
+      voxel: feature.voxel_triwiki_integration,
+      tests: 'release/selftest coverage',
+      docs: 'feature inventory'
+    },
+    acceptance: FEATURE_ACCEPTANCE_DEFAULTS,
+    ...feature
+  };
+}
+
+function mapHandlerKeysToFeatureIds(handlerKeys = []) {
+  const catalogNames = new Set(COMMAND_CATALOG.map((entry) => entry.name));
+  const out = {};
+  for (const handler of handlerKeys) {
+    const commandName = HANDLER_ALIAS_TO_COMMAND[handler] || handler;
+    out[handler] = catalogNames.has(commandName) ? `cli-${commandName}` : `handler-${handler}`;
+  }
+  return out;
+}
+
+async function parseMainHandlerKeys(root) {
+  const text = await readText(path.join(root, 'src', 'cli', 'main.mjs'), '');
+  const match = text.match(/const handlers = \{([\s\S]*?)\n\s*\};/);
+  if (!match) return [];
+  const keys = [];
+  for (const keyMatch of match[1].matchAll(/(?:^|[,\n])\s*(?:'([^']+)'|"([^"]+)"|([A-Za-z_$][\w$-]*))\s*:/g)) {
+    keys.push(keyMatch[1] || keyMatch[2] || keyMatch[3]);
+  }
+  return [...new Set(keys)].sort();
+}
+
+async function listProjectSkillNames(root) {
+  const dir = path.join(root, '.agents', 'skills');
+  if (!await exists(dir)) return [];
+  const entries = await fs.readdir(dir, { withFileTypes: true }).catch(() => []);
+  const names = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+    const skillFile = path.join(dir, entry.name, 'SKILL.md');
+    const text = await readText(skillFile, '').catch(() => '');
+    const name = text.match(/^name:\s*"?([^"\n]+)"?/m)?.[1]?.trim() || entry.name;
+    if (name) names.push(name);
+  }
+  return [...new Set(names)].sort();
+}
+
+async function collectDocRouteMentions(root) {
+  const docs = ['README.md', '.codex/SNEAKOSCOPE.md', 'AGENTS.md', '.agents/skills/.sks-generated.json'];
+  const mentions = new Set();
+  for (const file of docs) {
+    const text = file.endsWith('.json')
+      ? JSON.stringify(await readJson(path.join(root, file), null).catch(() => null) || {})
+      : await readText(path.join(root, file), '').catch(() => '');
+    for (const match of text.matchAll(/\$[A-Za-z][A-Za-z0-9_-]*/g)) mentions.add(canonicalDollar(match[0]));
+  }
+  return [...mentions].sort();
+}
+
+function flatMapSourceRefs(features, key) {
+  return features.flatMap((feature) => feature.source_refs?.[key] || []);
+}
+
+function duplicateValues(values) {
+  const seen = new Set();
+  const dupes = new Set();
+  for (const value of values) {
+    if (seen.has(value)) dupes.add(value);
+    seen.add(value);
+  }
+  return [...dupes].sort();
+}
+
+function markdownTableCell(value) {
+  return String(value || '').replace(/\|/g, '\\|').replace(/\n/g, '<br>');
+}
+
+function skillCoveredByRoute(skillName) {
+  const normalized = String(skillName || '').toLowerCase();
+  return DOLLAR_COMMAND_ALIASES.some((entry) => entry.app_skill.replace(/^\$/, '').toLowerCase() === normalized);
+}
+
+function isExternalPromptCommandMention(mention) {
+  return ['$IMAGEGEN'].includes(String(mention || '').toUpperCase());
+}
+
+function canonicalDollar(value) {
+  const raw = String(value || '').trim();
+  const hit = DOLLAR_COMMANDS.find((entry) => entry.command.toLowerCase() === raw.toLowerCase());
+  if (hit) return hit.command;
+  const aliasHit = DOLLAR_COMMAND_ALIASES.find((entry) => entry.app_skill.toLowerCase() === raw.toLowerCase());
+  return aliasHit ? aliasHit.app_skill : raw;
+}
+
+function normalizeDollar(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function slug(value) {
+  return String(value || '').replace(/^\$/, '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+}
+
+function commandCategory(name) {
+  if (['team', 'pipeline', 'goal', 'hproof', 'proof-field', 'validate-artifacts'].includes(name)) return 'proof-route';
+  if (['qa-loop', 'research', 'recallpulse', 'skill-dream', 'eval', 'perf'].includes(name)) return 'loop';
+  if (['codex-app', 'codex-lb', 'auth', 'hooks', 'context7', 'openclaw'].includes(name)) return 'integration';
+  if (['db', 'guard', 'conflicts', 'harness', 'versioning'].includes(name)) return 'safety';
+  if (['wiki', 'gx', 'image-ux-review', 'ppt'].includes(name)) return 'visual-memory';
+  if (['setup', 'bootstrap', 'doctor', 'deps', 'init', 'postinstall', 'fix-path'].includes(name)) return 'install';
+  return 'core-cli';
+}
+
+function commandMaturity(name) {
+  if (['help', 'version', 'commands', 'usage', 'root', 'quickstart', 'setup', 'doctor', 'selftest', 'update-check'].includes(name)) return 'stable';
+  if (['codex-app', 'codex-lb', 'hooks', 'features', 'all-features', 'wiki', 'team', 'pipeline', 'goal', 'db', 'guard'].includes(name)) return 'beta';
+  return 'labs';
+}
+
+function routeMaturity(command) {
+  if (['$Answer', '$DFix', '$SKS', '$Wiki', '$Help'].includes(command)) return 'stable';
+  if (['$Team', '$Goal', '$DB', '$Computer-Use', '$CU', '$QA-LOOP', '$MAD-SKS'].includes(command)) return 'beta';
+  return 'labs';
+}
+
+function voxelContract(category) {
+  if (category === 'visual-memory') return 'visual/image anchors required';
+  if (category === 'safety') return 'policy voxel required';
+  if (category === 'loop' || category === 'proof-route') return 'context/source/test anchors required';
+  return 'context anchor when evidence is written';
+}
+
+function proofContract(category) {
+  if (['proof-route', 'loop', 'safety', 'visual-memory'].includes(category)) return 'required';
+  return 'required for route/release use';
+}
+
+function knownGapsForCommand(name) {
+  if (['features', 'all-features'].includes(name)) return ['feature fixtures remain progressive'];
+  if (['codex-app', 'hooks'].includes(name)) return ['mobile/event payload details remain unknown'];
+  return [];
+}
+
+function routeVoxelContract(command) {
+  if (['$Image-UX-Review', '$UX-Review', '$PPT', '$From-Chat-IMG', '$GX'].includes(command)) return 'image/source/bbox voxel required';
+  if (command === '$DB' || command === '$MAD-SKS') return 'DB policy voxel required';
+  return 'TriWiki anchors required';
+}
+
+function routeKnownGaps(command) {
+  if (['$Image-UX-Review', '$UX-Review', '$PPT'].includes(command)) return ['live imagegen/CU evidence required'];
+  if (command === '$MAD-SKS') return ['permission closed by owning gate'];
+  return [];
+}
+
+function checkRow(id, ok, blockers = []) {
+  return { id, ok: Boolean(ok), blockers: ok ? [] : blockers };
+}
+
+function missingFeatureField(registry, field) {
+  return (registry.features || []).filter((feature) => !feature[field]).map((feature) => feature.id);
+}

package/src/core/fsx.mjs

@@ -5,7 +5,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 
-export const PACKAGE_VERSION = '0.9.6';
+export const PACKAGE_VERSION = '0.9.8';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/routes.mjs

@@ -28,7 +28,7 @@ export const FROM_CHAT_IMG_CHECKLIST_ARTIFACT = 'from-chat-img-checklist.md';
 export const FROM_CHAT_IMG_TEMP_TRIWIKI_ARTIFACT = 'from-chat-img-temp-triwiki.json';
 export const FROM_CHAT_IMG_QA_LOOP_ARTIFACT = 'from-chat-img-qa-loop.json';
 export const FROM_CHAT_IMG_TEMP_TRIWIKI_SESSIONS = 5;
-export const USAGE_TOPICS = 'install|setup|bootstrap|root|deps|tmux|auto-review|team|qa-loop|ppt|image-ux-review|goal|research|db|codex-app|openclaw|dfix|design|imagegen|dollar|context7|pipeline|reasoning|guard|conflicts|versioning|eval|harness|hproof|gx|wiki|code-structure|proof-field|skill-dream';
+export const USAGE_TOPICS = 'install|setup|bootstrap|root|deps|tmux|auto-review|team|qa-loop|ppt|image-ux-review|goal|research|db|codex-app|hooks|features|all-features|openclaw|dfix|design|imagegen|dollar|context7|pipeline|reasoning|guard|conflicts|versioning|eval|harness|hproof|gx|wiki|code-structure|proof-field|skill-dream';
 export const CODEX_COMPUTER_USE_EVIDENCE_SOURCE = 'codex_computer_use';
 export const CODEX_IMAGEGEN_EVIDENCE_SOURCE = 'codex_app_imagegen_gpt_image_2';
 export const CODEX_APP_IMAGE_GENERATION_DOC_URL = 'https://developers.openai.com/codex/app/features#image-generation';
@@ -531,7 +531,8 @@ export const COMMAND_CATALOG = [
   { name: 'bootstrap', usage: 'sks bootstrap [--install-scope global|project] [--local-only] [--json]', description: 'Initialize the current project, install SKS Codex App files/skills, check Context7/Codex App/tmux, and print ready true/false.' },
   { name: 'root', usage: 'sks root [--json]', description: 'Show whether SKS is using a project root or the per-user global SKS runtime root.' },
   { name: 'deps', usage: 'sks deps check|install [tmux|codex|context7|all] [--yes]', description: 'Check or guided-install Node/npm PATH, Codex CLI/App, Context7, Browser tooling, Computer Use, tmux, and Homebrew on macOS.' },
-  { name: 'codex-app', usage: 'sks codex-app [check|open|remote-control]', description: 'Check Codex App install and first-party MCP/plugin readiness, then show app setup files, examples, and Codex CLI 0.130.0+ remote-control availability.' },
+  { name: 'codex-app', usage: 'sks codex-app [check|open|pat status|remote-control]', description: 'Check Codex App install, PAT-safe status, first-party MCP/plugin readiness, and Codex CLI 0.130.0+ remote-control availability.' },
+  { name: 'hooks', usage: 'sks hooks explain [--json]', description: 'Explain Codex hook events, config locations, handler support, and SKS hook policies without storing raw payloads.' },
   { name: 'codex-lb', usage: 'sks codex-lb status|health|repair|setup --host <domain> --api-key <key>', description: 'Configure, health-check, or repair codex-lb provider auth by writing ~/.codex/config.toml, restoring CODEX_LB_API_KEY env auth from stored or legacy login-cache state, and preserving the shared Codex login cache unless explicitly requested.' },
   { name: 'auth', usage: 'sks auth status|health|repair|setup --host <domain> --api-key <key>', description: 'Shortcut for codex-lb provider auth status, health, repair, and setup commands.' },
   { name: 'openclaw', usage: 'sks openclaw install|path|print [--dir path] [--force] [--json]', description: 'Generate an OpenClaw skill package so OpenClaw agents can discover and use local SKS workflows.' },
@@ -549,6 +550,8 @@ export const COMMAND_CATALOG = [
   { name: 'guard', usage: 'sks guard check [--json]', description: 'Check SKS harness self-protection lock, fingerprints, and source-repo exception state.' },
   { name: 'conflicts', usage: 'sks conflicts check|prompt [--json]', description: 'Detect other Codex harnesses such as OMX/DCodex and print the GPT-5.5 high cleanup prompt.' },
   { name: 'versioning', usage: 'sks versioning status|bump|disable [--json]', description: 'Manage explicit project version syncs; SKS does not install Git pre-commit hooks.' },
+  { name: 'features', usage: 'sks features list|check|inventory [--json] [--write-docs]', description: 'Build and validate the feature registry that maps CLI commands, hidden handlers, dollar routes, app skill aliases, and skills.' },
+  { name: 'all-features', usage: 'sks all-features selftest --mock [--json]', description: 'Run the mock all-features contract selftest for feature registry, proof, Voxel TriWiki, and failure-contract coverage.' },
   { name: 'aliases', usage: 'sks aliases', description: 'Show command aliases and npm binary names.' },
   { name: 'setup', usage: 'sks setup [--bootstrap] [--install-scope global|project] [--local-only] [--force] [--json]', description: 'Initialize SKS state, Codex App files, hooks, skills, and rules.' },
   { name: 'fix-path', usage: 'sks fix-path [--install-scope global|project] [--json]', description: 'Refresh hook commands with the resolved SKS binary path.' },