sneakoscope 0.7.4 → 0.7.11

package/README.md

@@ -44,16 +44,18 @@ sks selftest --mock
 | Area | What it does |
 | --- | --- |
 | CLI runtime | `sks warp open` and `sks --mad` explicitly launch Codex CLI with Warp; bare `sks` only prints help/readiness surfaces. |
-| Codex App commands | Installs generated skills so `$Team`, `$From-Chat-IMG`, `$DFix`, `$QA-LOOP`, `$Goal`, `$DB`, `$Wiki`, `$Help`, and related routes are visible in prompt workflows. |
+| Codex App commands | Installs generated skills so `$Team`, `$From-Chat-IMG`, `$DFix`, `$QA-LOOP`, `$PPT`, `$Goal`, `$DB`, `$Wiki`, `$Help`, and related routes are visible in prompt workflows. |
 | Pipeline plans | Writes `pipeline-plan.json` for stateful routes so the runtime lane, kept stages, skipped stages, verification commands, and no-unrequested-fallback invariant are visible with `sks pipeline plan`. |
 | Team orchestration | Runs substantial work through ambiguity handling, scouts, TriWiki refresh, debate, runtime task graphs, worker inboxes, implementation, review, cleanup, reflection, and Honest Mode; narrow work should use Proof Field evidence to skip unrelated pipeline work instead of expanding Team. |
 | Skill dreaming | Records cheap generated-skill usage counters in JSON and only periodically scans `.agents/skills` for keep, merge, prune, and improvement candidates. Reports are recommendation-only and never delete skills automatically. |
 | From-Chat-IMG | Turns chat screenshots plus original attachments into source-bound work orders, then requires scoped QA evidence before completion. |
 | QA loop | Dogfoods UI/API behavior with safety gates, Codex Computer Use-only UI evidence, safe fixes, and rechecks. |
+| PPT pipeline | Uses `$PPT` for simple, restrained, information-first HTML/PDF presentation artifacts, first asking delivery context, audience profile, STP strategy, decision context, and 3+ pain-point to solution/aha mappings before source research, design-system work, HTML/PDF export, and render QA. Editable source HTML is preserved under `source-html/`, PPT-only temporary build files are cleaned after completion, and generated image assets must prefer Codex App built-in image generation through `$imagegen`. |
 | Computer Use fast lane | Uses `$Computer-Use` / `$CU` for UI/browser/visual work that needs maximum speed: skip Team debate and upfront TriWiki loops, use Codex Computer Use directly, then refresh/validate TriWiki and run Honest Mode at final closeout. |
 | Goal | Provides a fast SKS bridge overlay for Codex native persisted `/goal` create, pause, resume, and clear controls; implementation continues through the selected SKS execution route. |
 | TriWiki voxels | Maintains `.sneakoscope/wiki/context-pack.json` as the context SSOT with coordinate anchors, voxel metadata, `attention.use_first`, and `attention.hydrate_first`. |
 | Context7 | Requires current docs for external packages, APIs, MCPs, SDKs, and framework/runtime behavior when correctness depends on current guidance. |
+| getdesign.md | Grounds `design.md`, UI/UX design systems, and presentation-like HTML/PDF artifacts in the official getdesign.md reference and Codex skill path. |
 | DB safety | Treats SQL, migrations, Supabase, RLS, and destructive operations as high risk. |
 | Release hygiene | Checks versioning, changelog, package contents, tarball size, syntax, selftests, and dry-run publishing. |
 
@@ -95,6 +97,8 @@ sks bootstrap
 
 Project setup writes shared `.gitignore` entries for generated SKS files: `.sneakoscope/`, `.codex/`, `.agents/`, and managed `AGENTS.md`. Use `sks setup --local-only` when you want those excludes kept only in `.git/info/exclude`.
 
+During npm postinstall, SKS also installs generated Codex App skills and tries the official getdesign Codex skill command, `skills add MohtashamMurshid/getdesign`, when the `skills` CLI is available. If that CLI is missing, setup still installs the generated `getdesign-reference` skill so UI/UX and presentation design-system work keeps using [getdesign.md](https://getdesign.md/) as a required reference.
+
 ### One-Shot Install
 
 Use this when you do not want to keep a global install:
@@ -230,7 +234,7 @@ sks code-structure scan --json
 
 `sks pipeline plan` is the 0.7 runtime map. It reads or refreshes `.sneakoscope/missions/<id>/pipeline-plan.json`, then shows which lane is active, which stages are kept or skipped, which verification commands are required, and whether the no-unrequested-fallback invariant is present.
 
-`sks proof-field scan` is SKS's lightweight outcome rubric: it maps the goal to proof cones, records unrelated work that can be skipped with evidence, reports a simplicity score, and names escalation triggers for when the route must return to the full Team/Honest proof path. When `execution_lane.lane` is `proof_field_fast_lane`, SKS can keep the parent-owned minimal patch plus listed verification and skip Team debate, fresh executor teams, broad route rework, and unrelated checks. Database, security, visual-forensic, unknown, broad, failed, or unsupported-claim signals fail closed to the normal Team/Honest path. Use `sks pipeline plan --proof-field` after changed files are known to bind that Proof Field decision to the mission plan.
+`sks proof-field scan` is SKS's lightweight outcome rubric: it maps the goal to proof cones, records unrelated work that can be skipped with evidence, reports a simplicity score, and names escalation triggers for when the route must return to the full Team/Honest proof path. The rubric embeds Hyperplan-style adversarial pressure as compact lenses instead of a new command: challenge framing, subtract surface, demand evidence, test integration risk, and consider one simpler alternative. When `execution_lane.lane` is `proof_field_fast_lane`, SKS can keep the parent-owned minimal patch plus listed verification and skip Team debate, fresh executor teams, broad route rework, and unrelated checks. Database, security, visual-forensic, unknown, broad, failed, or unsupported-claim signals fail closed to the normal Team/Honest path. Use `sks pipeline plan --proof-field` after changed files are known to bind that Proof Field decision to the mission plan.
 
 `sks skill-dream` keeps generated skill complexity bounded without doing a heavy evaluation on every prompt. Route use writes compact counters to `.sneakoscope/skills/dream-state.json`; after the configured count/cooldown threshold, or when you run `sks skill-dream run`, SKS scans `.agents/skills` and writes `.sneakoscope/reports/skill-dream-latest.json` with keep, merge, prune, and improvement candidates. The report is intentionally advisory: deleting or merging skills requires explicit approval.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "ㅅㅋㅅ",
-  "version": "0.7.4",
+  "version": "0.7.11",
   "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",

package/src/cli/context7-command.mjs

@@ -0,0 +1,163 @@
+import { projectRoot, readJson, runProcess, sksRoot } from '../core/fsx.mjs';
+import { getCodexInfo } from '../core/codex-adapter.mjs';
+import { context7Docs, context7Resolve, context7Text, context7Tools } from '../core/context7-client.mjs';
+import { context7Evidence, recordContext7Evidence } from '../core/pipeline.mjs';
+import { stateFile } from '../core/mission.mjs';
+import { checkContext7, ensureProjectContext7Config } from './install-helpers.mjs';
+
+const flag = (args, name) => args.includes(name);
+
+export async function context7Command(sub = 'check', args = []) {
+  const action = sub || 'check';
+  const setupScope = action === 'setup' ? readOption(args, '--scope', flag(args, '--global') ? 'global' : 'project') : null;
+  const root = action === 'setup' && setupScope === 'project' ? await projectRoot() : await sksRoot();
+  if (action === 'check') {
+    const result = await checkContext7(root);
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    console.log('SKS Context7 MCP\n');
+    console.log(`Project config: ${result.project.ok ? 'ok' : 'missing'} ${result.project.path}`);
+    console.log(`Global config:  ${result.global.ok ? 'ok' : 'missing'} ${result.global.path}`);
+    console.log(`Codex mcp list: ${result.codex_mcp_list.ok ? 'ok' : result.codex_mcp_list.checked ? 'missing' : 'not checked'}`);
+    console.log(`Ready:          ${result.ok ? 'yes' : 'no'}`);
+    if (!result.ok) console.log('\nRun: sks context7 setup --scope project');
+    return;
+  }
+  if (action === 'tools') {
+    const result = await context7Tools({ timeoutMs: readNumberOption(args, '--timeout-ms', 30000) });
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    console.log('SKS Context7 Local MCP Tools\n');
+    console.log(`Server: ${result.server.info?.name || 'context7'} ${result.server.info?.version || ''}`.trim());
+    console.log(`Command: ${result.server.command} ${result.server.args.join(' ')}`);
+    console.log(`Tools:  ${result.tool_names.join(', ') || 'none'}`);
+    if (!result.tool_names.includes('resolve-library-id') || !result.tool_names.some((name) => name === 'query-docs' || name === 'get-library-docs')) {
+      process.exitCode = 1;
+      console.log('\nContext7 local MCP is missing the required resolve/docs tools.');
+    }
+    return;
+  }
+  if (action === 'resolve') {
+    const positional = positionalArgs(args);
+    const libraryName = positional.join(' ').trim();
+    if (!libraryName) throw new Error('Usage: sks context7 resolve <library-name> [--query "..."] [--json]');
+    const result = await context7Resolve(libraryName, {
+      query: readOption(args, '--query', libraryName),
+      timeoutMs: readNumberOption(args, '--timeout-ms', 30000)
+    });
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    console.log('SKS Context7 Resolve\n');
+    console.log(`Library: ${libraryName}`);
+    console.log(`ID:      ${result.library_id || 'not resolved'}`);
+    console.log(`Server:  ${result.server.info?.name || 'context7'} ${result.server.info?.version || ''}`.trim());
+    const text = context7Text(result.result).split(/\n/).slice(0, 24).join('\n').trim();
+    if (text) console.log(`\n${text}`);
+    if (!result.ok || !result.library_id) process.exitCode = 1;
+    return;
+  }
+  if (action === 'docs') {
+    const positional = positionalArgs(args);
+    const libraryNameOrId = positional.join(' ').trim();
+    if (!libraryNameOrId) throw new Error('Usage: sks context7 docs <library-name|/org/project> [--query "..."] [--topic "..."] [--tokens N] [--json]');
+    const result = await context7Docs(libraryNameOrId, {
+      query: readOption(args, '--query', readOption(args, '--topic', libraryNameOrId)),
+      topic: readOption(args, '--topic', libraryNameOrId),
+      tokens: readNumberOption(args, '--tokens', 2000),
+      timeoutMs: readNumberOption(args, '--timeout-ms', 30000)
+    });
+    if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
+    printContext7DocsResult(result, { title: 'SKS Context7 Docs' });
+    if (!result.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'evidence') {
+    const positional = positionalArgs(args);
+    const missionArg = positional.shift();
+    const libraryNameOrId = positional.join(' ').trim();
+    if (!missionArg || !libraryNameOrId) throw new Error('Usage: sks context7 evidence <mission-id|latest> <library-name|/org/project> [--query "..."] [--topic "..."] [--tokens N] [--json]');
+    const missionId = await resolveMissionId(root, missionArg);
+    if (!missionId) throw new Error('No mission found for Context7 evidence.');
+    const result = await context7Docs(libraryNameOrId, {
+      query: readOption(args, '--query', readOption(args, '--topic', libraryNameOrId)),
+      topic: readOption(args, '--topic', libraryNameOrId),
+      tokens: readNumberOption(args, '--tokens', 2000),
+      timeoutMs: readNumberOption(args, '--timeout-ms', 30000)
+    });
+    const state = { ...(await readJson(stateFile(root), {})), mission_id: missionId };
+    await recordContext7Evidence(root, state, { tool_name: 'resolve-library-id', library: libraryNameOrId, library_id: result.library_id, source: result.resolve ? 'sks context7 evidence' : 'sks context7 evidence explicit-library-id' });
+    if (result.docs_tool) {
+      await recordContext7Evidence(root, state, { tool_name: result.docs_tool, library_id: result.library_id, source: 'sks context7 evidence' });
+    }
+    const evidence = await context7Evidence(root, state);
+    const out = { ...result, mission_id: missionId, evidence };
+    if (flag(args, '--json')) return console.log(JSON.stringify(out, null, 2));
+    printContext7DocsResult(result, { title: 'SKS Context7 Evidence' });
+    console.log(`\nMission:  ${missionId}`);
+    console.log(`Evidence: ${evidence.ok ? 'ok' : 'missing'} resolve=${evidence.resolve ? 'yes' : 'no'} docs=${evidence.docs ? 'yes' : 'no'} events=${evidence.count}`);
+    if (!result.ok || !evidence.ok) process.exitCode = 1;
+    return;
+  }
+  if (action === 'setup') {
+    const scope = setupScope;
+    const transport = readOption(args, '--transport', flag(args, '--remote') ? 'remote' : 'local');
+    if (!['project', 'global'].includes(scope)) throw new Error('Invalid Context7 scope. Use project or global.');
+    if (!['local', 'remote'].includes(transport)) throw new Error('Invalid Context7 transport. Use local or remote.');
+    if (scope === 'project') {
+      const changed = await ensureProjectContext7Config(root, transport);
+      const result = await checkContext7(root);
+      if (flag(args, '--json')) return console.log(JSON.stringify({ changed, ...result }, null, 2));
+      console.log(`Context7 project MCP ${changed ? 'configured' : 'already configured'} in .codex/config.toml`);
+      console.log(`Ready: ${result.ok ? 'yes' : 'no'}`);
+      return;
+    }
+    const codex = await getCodexInfo();
+    if (!codex.bin) throw new Error('Codex CLI missing. Install separately: npm i -g @openai/codex, or set SKS_CODEX_BIN.');
+    const cmdArgs = transport === 'remote'
+      ? ['mcp', 'add', 'context7', '--url', 'https://mcp.context7.com/mcp']
+      : ['mcp', 'add', 'context7', '--', 'npx', '-y', '@upstash/context7-mcp@latest'];
+    const result = await runProcess(codex.bin, cmdArgs, { timeoutMs: 30000, maxOutputBytes: 64 * 1024 });
+    if (flag(args, '--json')) return console.log(JSON.stringify({ command: `${codex.bin} ${cmdArgs.join(' ')}`, result }, null, 2));
+    if (result.code !== 0) throw new Error(result.stderr || result.stdout || 'codex mcp add failed');
+    console.log('Context7 global MCP configured.');
+    return;
+  }
+  throw new Error(`Unknown context7 command: ${action}`);
+}
+
+function printContext7DocsResult(result, opts = {}) {
+  console.log(`${opts.title || 'SKS Context7 Docs'}\n`);
+  console.log(`Library ID: ${result.library_id || 'not resolved'}`);
+  console.log(`Docs tool:  ${result.docs_tool || 'missing'}`);
+  console.log(`Server:     ${result.server?.info?.name || 'context7'} ${result.server?.info?.version || ''}`.trim());
+  const text = context7Text(result.docs).split(/\n/).slice(0, 48).join('\n').trim();
+  if (text) console.log(`\n${text}`);
+  if (result.error) console.log(`\nError: ${result.error}`);
+}
+
+function readOption(args, name, fallback) {
+  const i = args.indexOf(name);
+  return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+}
+
+function readNumberOption(args, name, fallback) {
+  const raw = readOption(args, name, null);
+  if (raw == null) return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+function positionalArgs(args = []) {
+  const out = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (String(arg).startsWith('--')) {
+      if (args[i + 1] && !String(args[i + 1]).startsWith('--')) i++;
+      continue;
+    }
+    out.push(arg);
+  }
+  return out;
+}
+
+async function resolveMissionId(root, arg) {
+  const { findLatestMission } = await import('../core/mission.mjs');
+  return (!arg || arg === 'latest') ? findLatestMission(root) : arg;
+}

package/src/cli/install-helpers.mjs

@@ -0,0 +1,326 @@
+import path from 'node:path';
+import os from 'node:os';
+import fsp from 'node:fs/promises';
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { ensureDir, exists, packageRoot, runProcess, which, writeTextAtomic } from '../core/fsx.mjs';
+import { getCodexInfo } from '../core/codex-adapter.mjs';
+import { formatHarnessConflictReport, llmHarnessCleanupPrompt, scanHarnessConflicts } from '../core/harness-conflicts.mjs';
+import { installSkills } from '../core/init.mjs';
+import { context7ConfigToml, DOLLAR_SKILL_NAMES, GETDESIGN_REFERENCE, hasContext7ConfigText, RECOMMENDED_SKILLS } from '../core/routes.mjs';
+import { platformWarpInstallHint, warpReadiness } from '../core/warp-ui.mjs';
+
+export async function postinstall({ bootstrap }) {
+  const installRoot = path.resolve(process.env.INIT_CWD || process.cwd());
+  const conflictScan = await scanHarnessConflicts(installRoot);
+  if (conflictScan.hard_block) {
+    await postinstallHarnessConflictNotice(conflictScan);
+    return;
+  }
+  console.log('\nSKS installed.');
+  const shim = await ensureSksCommandDuringInstall();
+  if (shim.status === 'present') console.log(`SKS command: available (${shim.command}).`);
+  else if (shim.status === 'created') console.log(`SKS command: shim created at ${shim.command}.`);
+  else if (shim.status === 'created_not_on_path') console.log(`SKS command: shim created at ${shim.command}. Add ${path.dirname(shim.command)} to PATH, or run npx -y -p sneakoscope sks.`);
+  else if (shim.status === 'skipped') console.log(`SKS command: skipped (${shim.reason}).`);
+  else console.log(`SKS command: shim unavailable. Use npx -y -p sneakoscope sks. ${shim.error || ''}`.trim());
+  const context7Install = await ensureGlobalContext7DuringInstall();
+  if (context7Install.status === 'present') console.log('Context7 MCP: already configured for Codex.');
+  else if (context7Install.status === 'installed') console.log('Context7 MCP: configured for Codex.');
+  else if (context7Install.status === 'codex_missing') console.log('Context7 MCP: Codex CLI missing. Install @openai/codex or set SKS_CODEX_BIN, then run `sks context7 setup --scope global` or `sks setup` in a project.');
+  else if (context7Install.status === 'skipped') console.log(`Context7 MCP: skipped (${context7Install.reason}).`);
+  else if (context7Install.status === 'failed') console.log(`Context7 MCP: auto setup failed. Run \`sks context7 setup --scope global\` or \`sks setup\`. ${context7Install.error || ''}`.trim());
+  const globalSkills = await ensureGlobalCodexSkillsDuringInstall();
+  if (globalSkills.status === 'installed') console.log(`Codex App global $ skills: installed in ${globalSkills.root} (${globalSkills.installed_count} skills).`);
+  else if (globalSkills.status === 'partial') console.log(`Codex App global $ skills: partial in ${globalSkills.root}; missing ${globalSkills.missing_skills.join(', ')}. Run \`sks doctor --fix\`.`);
+  else if (globalSkills.status === 'skipped') console.log(`Codex App global $ skills: skipped (${globalSkills.reason}).`);
+  else if (globalSkills.status === 'failed') console.log(`Codex App global $ skills: auto setup failed. Run \`sks doctor --fix\`. ${globalSkills.error || ''}`.trim());
+  const getdesignSkill = await ensureGlobalGetdesignSkillDuringInstall();
+  if (getdesignSkill.status === 'installed') console.log('getdesign Codex skill: installed.');
+  else if (getdesignSkill.status === 'present') console.log('getdesign Codex skill: already available.');
+  else if (getdesignSkill.status === 'skills_cli_missing') console.log(`getdesign Codex skill: skills CLI missing; generated getdesign-reference skill is installed. Later run \`${getdesignSkill.install}\` if the skills CLI is available.`);
+  else if (getdesignSkill.status === 'skipped') console.log(`getdesign Codex skill: skipped (${getdesignSkill.reason}).`);
+  else if (getdesignSkill.status === 'failed') console.log(`getdesign Codex skill: auto setup failed; generated getdesign-reference skill remains available. ${getdesignSkill.error || ''}`.trim());
+  const bootstrapDecision = await postinstallBootstrapDecision(installRoot);
+  if (bootstrapDecision.run) {
+    console.log(`SKS bootstrap: ${bootstrapDecision.reason}.`);
+    await runPostinstallBootstrap(installRoot, bootstrap);
+    return;
+  }
+  console.log('\nNext:');
+  console.log('  sks bootstrap');
+  console.log(`\nSKS bootstrap was not run automatically: ${bootstrapDecision.reason}.`);
+  console.log('This initializes the current project, installs SKS Codex App skills, verifies Codex App/Context7 readiness, and checks warp/runtime dependencies.');
+  console.log('Dependency repair: sks deps check; sks deps install warp');
+  console.log('Open runtime after readiness is green: sks\n');
+}
+
+async function postinstallHarnessConflictNotice(conflictScan) {
+  console.log('\nSneakoscope Codex package installed, but SKS setup is blocked.');
+  console.log(formatHarnessConflictReport(conflictScan, { includePrompt: false }));
+  console.log('\nWhat this means: npm can finish installing the package, but `sks setup` and `sks doctor --fix` will refuse to activate SKS until the conflicting harness is removed with human approval.');
+  console.log('No files were removed by postinstall.');
+  console.log('Cleanup requires a human-approved Codex App session. Recommended model: GPT-5.5, reasoning: high.');
+  if (shouldAskPostinstallQuestion()) {
+    const answer = await askPostinstallQuestion('Show the cleanup prompt now? [y/N] ');
+    if (/^(y|yes|예|네|응)$/i.test(answer.trim())) {
+      console.log('\nCleanup prompt:\n');
+      console.log(llmHarnessCleanupPrompt(conflictScan));
+    } else {
+      console.log('Cleanup prompt skipped. You can print it later with: sks conflicts prompt');
+    }
+  } else {
+    console.log('Print the cleanup prompt later with: sks conflicts prompt');
+  }
+  console.log('After approved cleanup, rerun: sks setup && sks doctor --fix && sks selftest --mock\n');
+}
+
+function shouldAskPostinstallQuestion() {
+  if (process.env.SKS_POSTINSTALL_PROMPT === '1') return true;
+  return Boolean(input.isTTY && output.isTTY && process.env.CI !== 'true' && process.env.SKS_POSTINSTALL_NO_PROMPT !== '1');
+}
+
+export async function postinstallBootstrapDecision(root) {
+  if (process.env.SKS_POSTINSTALL_NO_BOOTSTRAP === '1') return { run: false, reason: 'SKS_POSTINSTALL_NO_BOOTSTRAP=1' };
+  if (process.env.SKS_POSTINSTALL_BOOTSTRAP === '0') return { run: false, reason: 'SKS_POSTINSTALL_BOOTSTRAP=0' };
+  const candidate = await isProjectSetupCandidate(path.resolve(root || process.cwd()));
+  if (!candidate && process.env.SKS_POSTINSTALL_BOOTSTRAP !== '1') return { run: false, reason: 'no project marker found in install cwd' };
+  if (process.env.SKS_POSTINSTALL_BOOTSTRAP === '1') return { run: true, reason: 'forced by SKS_POSTINSTALL_BOOTSTRAP=1' };
+  return { run: true, reason: 'auto-running sks setup --bootstrap --install-scope global --force' };
+}
+
+async function runPostinstallBootstrap(root, bootstrap) {
+  const previousCwd = process.cwd();
+  process.chdir(path.resolve(root || previousCwd));
+  try {
+    await bootstrap(['--from-postinstall', '--install-scope', 'global', '--force']);
+  } finally {
+    process.chdir(previousCwd);
+  }
+}
+
+export async function askPostinstallQuestion(question) {
+  const rl = readline.createInterface({ input, output });
+  try {
+    return await rl.question(question);
+  } finally {
+    rl.close();
+  }
+}
+
+export async function ensureSksCommandDuringInstall(opts = {}) {
+  if (process.env.SKS_SKIP_POSTINSTALL_SHIM === '1' && !opts.force) return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_SHIM=1' };
+  const pathEnv = opts.pathEnv ?? process.env.PATH ?? '';
+  const existing = await findCommandOnPath('sks', pathEnv);
+  if (isStableSksBin(existing)) return { status: 'present', command: existing };
+  const nodeBin = opts.nodeBin || process.execPath;
+  const target = opts.target || path.join(packageRoot(), 'bin', 'sks.mjs');
+  const dirs = candidateShimDirs(pathEnv, opts.home || process.env.HOME);
+  const script = process.platform === 'win32'
+    ? `@echo off\r\n"${nodeBin}" "${target}" %*\r\n`
+    : `#!/bin/sh\nexec "${nodeBin}" "${target}" "$@"\n`;
+  const suffix = process.platform === 'win32' ? '.cmd' : '';
+  let createdFallback = null;
+  let lastError = '';
+  for (const entry of dirs) {
+    const dest = path.join(entry.dir, `sks${suffix}`);
+    try {
+      await ensureDir(entry.dir);
+      await writeTextAtomic(dest, script);
+      if (process.platform !== 'win32') await fsp.chmod(dest, 0o755).catch(() => {});
+      if (entry.onPath) return { status: 'created', command: dest };
+      createdFallback ||= dest;
+    } catch (err) {
+      lastError = err.message;
+    }
+  }
+  if (createdFallback) return { status: 'created_not_on_path', command: createdFallback };
+  return { status: 'failed', error: lastError };
+}
+
+function candidateShimDirs(pathEnv, home) {
+  const seen = new Set();
+  const out = [];
+  for (const raw of String(pathEnv || '').split(path.delimiter).filter(Boolean)) {
+    const dir = path.resolve(raw);
+    if (seen.has(dir) || isTransientNpmBinPath(dir)) continue;
+    seen.add(dir);
+    out.push({ dir, onPath: true });
+  }
+  for (const raw of [home && path.join(home, '.local', 'bin'), home && path.join(home, 'bin')].filter(Boolean)) {
+    const dir = path.resolve(raw);
+    if (seen.has(dir)) continue;
+    seen.add(dir);
+    out.push({ dir, onPath: false });
+  }
+  return out;
+}
+
+async function findCommandOnPath(name, pathEnv) {
+  const suffixes = process.platform === 'win32' ? ['.cmd', '.exe', ''] : [''];
+  for (const dir of String(pathEnv || '').split(path.delimiter).filter(Boolean)) {
+    for (const suffix of suffixes) {
+      const candidate = path.join(dir, `${name}${suffix}`);
+      if (await exists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+async function ensureGlobalContext7DuringInstall() {
+  if (process.env.SKS_SKIP_POSTINSTALL_CONTEXT7 === '1') return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_CONTEXT7=1' };
+  const codex = await getCodexInfo().catch(() => ({}));
+  if (!codex.bin) return { status: 'codex_missing' };
+  const list = await runProcess(codex.bin, ['mcp', 'list'], { timeoutMs: 8000, maxOutputBytes: 32 * 1024 }).catch((err) => ({ code: 1, stderr: err.message, stdout: '' }));
+  if (list.code === 0 && /context7/i.test(`${list.stdout}\n${list.stderr}`)) return { status: 'present' };
+  const add = await runProcess(codex.bin, ['mcp', 'add', 'context7', '--', 'npx', '-y', '@upstash/context7-mcp@latest'], { timeoutMs: 30000, maxOutputBytes: 64 * 1024 }).catch((err) => ({ code: 1, stderr: err.message, stdout: '' }));
+  if (add.code === 0) return { status: 'installed' };
+  return { status: 'failed', error: `${add.stderr || add.stdout || 'codex mcp add failed'}`.trim() };
+}
+
+export async function ensureGlobalCodexSkillsDuringInstall(opts = {}) {
+  if (process.env.SKS_SKIP_POSTINSTALL_GLOBAL_SKILLS === '1' && !opts.force) return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_GLOBAL_SKILLS=1' };
+  const home = opts.home || process.env.HOME || os.homedir();
+  if (!home) return { status: 'skipped', reason: 'home directory unavailable' };
+  const root = globalCodexSkillsRoot(home);
+  try {
+    const install = await installSkills(home);
+    const skills = await checkRequiredSkills(home, root);
+    return { status: skills.ok ? 'installed' : 'partial', root, installed_count: install.installed_skills.length, removed_aliases: install.removed_agent_skill_aliases, missing_skills: skills.missing };
+  } catch (err) {
+    return { status: 'failed', root, error: err.message };
+  }
+}
+
+async function ensureGlobalGetdesignSkillDuringInstall() {
+  if (process.env.SKS_SKIP_POSTINSTALL_GETDESIGN === '1') return { status: 'skipped', reason: 'SKS_SKIP_POSTINSTALL_GETDESIGN=1' };
+  const pathEnv = process.env.PATH || '';
+  const skillsBin = await findCommandOnPath('skills', pathEnv);
+  if (!skillsBin) return { status: 'skills_cli_missing', install: GETDESIGN_REFERENCE.codex_skill_install };
+  const add = await runProcess(skillsBin, ['add', GETDESIGN_REFERENCE.codex_skill], {
+    timeoutMs: 30000,
+    maxOutputBytes: 64 * 1024
+  }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+  const out = `${add.stdout || ''}\n${add.stderr || ''}`;
+  if (add.code === 0) return { status: /already|exists|present/i.test(out) ? 'present' : 'installed', command: skillsBin };
+  if (/already|exists|present/i.test(out)) return { status: 'present', command: skillsBin };
+  return { status: 'failed', command: skillsBin, error: out.trim() || 'skills add failed' };
+}
+
+export async function ensureRelatedCliTools(args = []) {
+  const skip = args.includes('--skip-cli-tools') || process.env.SKS_SKIP_CLI_TOOLS === '1';
+  const codex = await ensureCodexCliTool({ skip });
+  const warp = await warpReadiness().catch((err) => ({ ok: false, version: null, error: err.message }));
+  return {
+    codex,
+    warp: {
+      ok: Boolean(warp.ok),
+      app: warp.app || null,
+      cli: warp.cli || null,
+      version: warp.version || null,
+      launch_config_dir: warp.launch_config_dir || null,
+      uri_scheme: warp.uri_scheme || null,
+      install_hint: warp.ok ? null : platformWarpInstallHint(),
+      error: warp.error || null
+    }
+  };
+}
+
+export async function ensureCodexCliTool({ skip = false } = {}) {
+  if (skip) return { status: 'skipped', reason: 'SKS_SKIP_CLI_TOOLS=1 or --skip-cli-tools' };
+  const before = await getCodexInfo().catch(() => ({}));
+  if (before.bin) return { status: 'present', bin: before.bin, version: before.version || null };
+  const npmBin = await which('npm');
+  if (!npmBin) return { status: 'failed', error: 'npm not found on PATH; install Codex CLI manually with npm i -g @openai/codex@latest.' };
+  const install = await runProcess(npmBin, ['i', '-g', '@openai/codex@latest'], {
+    timeoutMs: 120000,
+    maxOutputBytes: 128 * 1024
+  }).catch((err) => ({ code: 1, stdout: '', stderr: err.message }));
+  if (install.code !== 0) {
+    return { status: 'failed', error: `${install.stderr || install.stdout || 'npm i -g @openai/codex@latest failed'}`.trim() };
+  }
+  const after = await getCodexInfo().catch(() => ({}));
+  return {
+    status: after.bin ? 'installed' : 'installed_not_on_path',
+    bin: after.bin || null,
+    version: after.version || null,
+    hint: after.bin ? null : 'npm completed, but codex is not on PATH. Restart the shell or set SKS_CODEX_BIN.'
+  };
+}
+
+async function isProjectSetupCandidate(root) {
+  const markers = ['package.json', '.git', 'AGENTS.md', '.codex', '.sneakoscope'];
+  for (const marker of markers) {
+    if (await exists(path.join(root, marker))) return true;
+  }
+  return false;
+}
+
+export async function checkContext7(root) {
+  const projectPath = path.join(root, '.codex', 'config.toml');
+  const globalPath = path.join(process.env.HOME || '', '.codex', 'config.toml');
+  const projectText = await safeReadText(projectPath);
+  const globalText = await safeReadText(globalPath);
+  const codex = await getCodexInfo().catch(() => ({}));
+  let list = { checked: false, ok: false, stdout: '', stderr: '' };
+  if (codex.bin) {
+    const out = await runProcess(codex.bin, ['mcp', 'list'], { timeoutMs: 8000, maxOutputBytes: 32 * 1024 }).catch((err) => ({ code: 1, stderr: err.message, stdout: '' }));
+    list = { checked: true, ok: out.code === 0 && /context7/i.test(`${out.stdout}\n${out.stderr}`), stdout: out.stdout || '', stderr: out.stderr || '' };
+  }
+  const result = {
+    project: { path: projectPath, ok: hasContext7ConfigText(projectText) },
+    global: { path: globalPath, ok: hasContext7ConfigText(globalText) },
+    codex_mcp_list: list
+  };
+  result.ok = result.project.ok || result.codex_mcp_list.ok || (result.global.ok && !list.checked);
+  return result;
+}
+
+export async function ensureProjectContext7Config(root, transport = 'local') {
+  const configPath = path.join(root, '.codex', 'config.toml');
+  await ensureDir(path.dirname(configPath));
+  const current = await safeReadText(configPath);
+  const block = context7ConfigToml(transport).trim();
+  const existingBlock = /(^|\n)\[mcp_servers\.context7\]\n[\s\S]*?(?=\n\[[^\]]+\]|\s*$)/;
+  if (existingBlock.test(current)) {
+    const next = current.replace(existingBlock, `$1${block}\n`);
+    if (next === current) return false;
+    await writeTextAtomic(configPath, next.endsWith('\n') ? next : `${next}\n`);
+    return true;
+  }
+  if (hasContext7ConfigText(current)) return false;
+  await writeTextAtomic(configPath, `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}\n`);
+  return true;
+}
+
+export async function checkRequiredSkills(root, skillRoot = root ? path.join(root, '.agents', 'skills') : globalCodexSkillsRoot()) {
+  const missing = [];
+  for (const name of [...DOLLAR_SKILL_NAMES, ...RECOMMENDED_SKILLS]) {
+    if (!(await exists(path.join(skillRoot, name, 'SKILL.md')))) missing.push(name);
+  }
+  return { ok: missing.length === 0, root: skillRoot, missing };
+}
+
+export function globalCodexSkillsRoot(home = process.env.HOME || os.homedir()) {
+  return path.join(home, '.agents', 'skills');
+}
+
+function isStableSksBin(candidate) {
+  return Boolean(candidate) && !isTransientNpmBinPath(candidate);
+}
+
+function isTransientNpmBinPath(candidate) {
+  const normalized = String(candidate || '').split(path.sep).join('/');
+  return normalized.includes('/_npx/')
+    || normalized.includes('/_cacache/tmp/')
+    || /\/npm-cache\/_npx\//.test(normalized)
+    || (/\/node_modules\/\.bin\/sks$/.test(normalized) && normalized.includes('/.npm-cache/'));
+}
+
+async function safeReadText(file, fallback = '') {
+  try {
+    return await fsp.readFile(file, 'utf8');
+  } catch {
+    return fallback;
+  }
+}