sneakoscope 0.6.6 → 0.6.8

package/README.md

@@ -28,6 +28,14 @@ sks setup
 sks doctor --fix
 ```
 
+Use local-only setup when the generated SKS files must never appear in git status:
+
+```bash
+sks setup --local-only
+```
+
+This writes repo-local excludes to `.git/info/exclude` for `.sneakoscope/`, `.codex/`, `.agents/`, and `AGENTS.md`. If `AGENTS.md` already exists, local-only setup does not modify it.
+
 The npm package name is `sneakoscope`; the command is branded as SKS and exposed as lowercase `sks` for shell portability. The package also exposes a `sneakoscope` command alias, so `sks setup` and `sneakoscope setup` are equivalent.
 Global installation is the default and recommended setup. During `sks setup` or `sks init`, SKS resolves the global binary when possible and writes that absolute path into `.codex/hooks.json`, which avoids PATH issues in GUI or hook execution environments. For a project-only install, use `npm i -D sneakoscope` and initialize hooks with `npx sks setup --install-scope project`; this writes hook commands that call the local `node_modules/sneakoscope` binary.
 
@@ -378,10 +386,10 @@ sks aliases
 sks --help
 sneakoscope --help
 
-sks setup [--install-scope global|project] [--force] [--json]
+sks setup [--install-scope global|project] [--local-only] [--force] [--json]
 sks fix-path [--install-scope global|project] [--json]
-sks doctor [--fix] [--json] [--install-scope global|project]
-sks init [--force] [--install-scope global|project]
+sks doctor [--fix] [--local-only] [--json] [--install-scope global|project]
+sks init [--force] [--local-only] [--install-scope global|project]
 sks selftest [--mock]
 
 sks ralph prepare "task"
@@ -589,7 +597,6 @@ sks hproof check latest
 .codex/skills/        Codex App local project skills
 .codex/agents/        Codex App custom agents for Team mode
 .codex/SNEAKOSCOPE.md Codex App quick reference
-.agents/skills/       Sneakoscope Codex helper skills
 AGENTS.md             managed repository rules block
 ```
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sneakoscope",
   "displayName": "Sneakoscope Codex",
-  "version": "0.6.6",
+  "version": "0.6.8",
   "description": "Sneakoscope Codex: update-aware, database-safe Codex CLI harness with multi-agent Team orchestration, Ralph no-question execution, autoresearch-style loops, and H-Proof gates.",
   "type": "module",
   "homepage": "https://github.com/mandarange/Sneakoscope-Codex#readme",

package/src/cli/main.mjs

@@ -50,10 +50,10 @@ const COMMAND_CATALOG = [
   { name: 'dollar-commands', usage: 'sks dollar-commands [--json]', description: 'List Codex App $ commands such as $DF.' },
   { name: 'df', usage: 'sks df', description: 'Explain $DF fast design/content fix mode.' },
   { name: 'aliases', usage: 'sks aliases', description: 'Show command aliases and npm binary names.' },
-  { name: 'setup', usage: 'sks setup [--install-scope global|project] [--force] [--json]', description: 'Initialize SKS state, Codex App files, hooks, skills, and rules.' },
+  { name: 'setup', usage: 'sks setup [--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.' },
-  { name: 'doctor', usage: 'sks doctor [--fix] [--json] [--install-scope global|project]', description: 'Check Node, Codex CLI, install scope, hooks, skills, DB guard, and Codex App files.' },
-  { name: 'init', usage: 'sks init [--force] [--install-scope global|project]', description: 'Initialize the local SKS control surface.' },
+  { name: 'doctor', usage: 'sks doctor [--fix] [--local-only] [--json] [--install-scope global|project]', description: 'Check Node, Codex CLI, install scope, hooks, skills, DB guard, and Codex App files.' },
+  { name: 'init', usage: 'sks init [--force] [--local-only] [--install-scope global|project]', description: 'Initialize the local SKS control surface.' },
   { name: 'selftest', usage: 'sks selftest [--mock]', description: 'Run local smoke tests without calling a model.' },
   { name: 'ralph', usage: 'sks ralph prepare|answer|run|status ...', description: 'Run mandatory-clarification Ralph missions with a no-question execution loop.' },
   { name: 'research', usage: 'sks research prepare|run|status ...', description: 'Run frontier-style research missions with novelty and falsification gates.' },
@@ -134,10 +134,10 @@ Usage:
   sks dollar-commands [--json]
   sks df
   sks aliases
-  sks setup [--install-scope global|project] [--force] [--json]
+  sks setup [--install-scope global|project] [--local-only] [--force] [--json]
   sks fix-path [--install-scope global|project] [--json]
-  sks doctor [--fix] [--json] [--install-scope global|project]
-  sks init [--install-scope global|project]
+  sks doctor [--fix] [--local-only] [--json] [--install-scope global|project]
+  sks init [--install-scope global|project] [--local-only]
   sks selftest [--mock]
   sks ralph prepare "task"
   sks ralph answer <mission-id|latest> <answers.json>
@@ -326,6 +326,11 @@ Project-only install:
   npm i -D sneakoscope
   npx sks setup --install-scope project
 
+Local-only install artifacts:
+  sks setup --local-only
+  # writes generated SKS files but excludes .sneakoscope/, .codex/, .agents/, AGENTS.md through .git/info/exclude
+  # existing AGENTS.md is not modified in local-only mode
+
 GitHub install for unreleased commits:
   npm i -g git+${REPOSITORY_URL}
 `);
@@ -563,6 +568,11 @@ Project-only install:
   npm i -D sneakoscope
   npx sks setup --install-scope project
 
+Local-only install artifacts:
+  sks setup --local-only
+  # excludes .sneakoscope/, .codex/, .agents/, AGENTS.md through .git/info/exclude
+  # existing AGENTS.md is not modified in local-only mode
+
 GitHub install for unreleased commits:
   npm i -g git+${REPOSITORY_URL}
   sks setup
@@ -750,8 +760,9 @@ Render and verify:
 async function setup(args) {
   const root = await projectRoot();
   const installScope = installScopeFromArgs(args);
+  const localOnly = flag(args, '--local-only');
   const globalCommand = await globalSksCommand();
-  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand });
+  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand, localOnly });
   const install = await installStatus(root, installScope, { globalCommand });
   const hooksPath = path.join(root, '.codex', 'hooks.json');
   const result = {
@@ -767,6 +778,7 @@ async function setup(args) {
       agents_rules: path.join(root, 'AGENTS.md')
     },
     created: res.created,
+    local_only: localOnly,
     next: ['sks selftest --mock', 'sks doctor', 'sks commands']
   };
   if (flag(args, '--json')) return console.log(JSON.stringify(result, null, 2));
@@ -774,9 +786,10 @@ async function setup(args) {
   console.log(`Project:   ${root}`);
   console.log(`Install:   ${install.ok ? 'ok' : 'missing'} ${install.scope} (${install.command_prefix})`);
   console.log(`Hooks:     ${path.relative(root, hooksPath)}`);
+  if (localOnly) console.log('Git:       local-only (.git/info/exclude; existing AGENTS.md not modified)');
   console.log(`Codex App: .codex/config.toml, .codex/hooks.json, .codex/skills, .codex/agents, .codex/SNEAKOSCOPE.md`);
   console.log(`Prompt:    default optimization pipeline, $DF fast design/content route`);
-  console.log(`Skills:    .codex/skills, .agents/skills`);
+  console.log(`Skills:    .codex/skills`);
   console.log(`Next:      sks selftest --mock; sks commands; sks dollar-commands`);
   if (!install.ok && install.scope === 'global') console.log('\nGlobal command missing. Run: npm i -g sneakoscope');
   if (!install.ok && install.scope === 'project') console.log('\nProject package missing. Run: npm i -D sneakoscope');
@@ -789,7 +802,7 @@ async function fixPath(args) {
     ? installScopeFromArgs(args)
     : normalizeInstallScope(manifest?.installation?.scope || 'global');
   const globalCommand = await globalSksCommand();
-  await initProject(root, { installScope, globalCommand });
+  await initProject(root, { installScope, globalCommand, localOnly: flag(args, '--local-only') || Boolean(manifest?.git?.local_only) });
   const install = await installStatus(root, installScope, { globalCommand });
   const result = {
     root,
@@ -814,7 +827,8 @@ async function doctor(args) {
     : null;
   if (flag(args, '--fix')) {
     const fixScope = requestedScope || 'global';
-    await initProject(root, { installScope: fixScope, globalCommand: await globalSksCommand() });
+    const existingManifest = await readJson(path.join(root, '.sneakoscope', 'manifest.json'), null);
+    await initProject(root, { installScope: fixScope, globalCommand: await globalSksCommand(), localOnly: flag(args, '--local-only') || Boolean(existingManifest?.git?.local_only) });
   }
   const codex = await getCodexInfo();
   const rust = await rustInfo();
@@ -840,7 +854,7 @@ async function doctor(args) {
     sneakoscope: { ok: await exists(path.join(root, '.sneakoscope')) },
     db_guard: { ok: dbPolicyExists && dbScan.ok, policy: dbPolicyExists ? await loadDbSafetyPolicy(root) : null, scan: dbScan },
     hooks: { ok: await exists(path.join(root, '.codex', 'hooks.json')) },
-    skills: { ok: (await exists(path.join(root, '.codex', 'skills'))) && (await exists(path.join(root, '.agents', 'skills'))) },
+    skills: { ok: await exists(path.join(root, '.codex', 'skills')) },
     codex_app: {
       ...codexApp,
       ok: codexApp.config.ok && codexApp.hooks.ok && codexApp.skills.ok && codexApp.agents.ok && codexApp.quick_reference.ok && codexApp.agents_rules.ok
@@ -859,7 +873,7 @@ async function doctor(args) {
   console.log(`DB Guard:  ${result.db_guard.ok ? 'ok' : 'blocked'} ${dbScan.findings?.length || 0} finding(s)`);
   console.log(`Hooks:     ${result.hooks.ok ? 'ok' : 'missing .codex/hooks.json'}`);
   console.log(`Codex App: ${result.codex_app.ok ? 'ok' : 'missing app files'} .codex/config.toml .codex/hooks.json .codex/skills .codex/agents .codex/SNEAKOSCOPE.md`);
-  console.log(`Skills:    ${result.skills.ok ? 'ok' : 'missing .codex/skills or .agents/skills'}`);
+  console.log(`Skills:    ${result.skills.ok ? 'ok' : 'missing .codex/skills'}`);
   console.log(`Package:   ${result.package.human}`);
   console.log(`Storage:   ${storage.total_human || '0 B'}`);
   console.log(`Ready:     ${result.ready ? 'yes' : 'no'}`);
@@ -872,10 +886,12 @@ async function doctor(args) {
 async function init(args) {
   const root = await projectRoot();
   const installScope = installScopeFromArgs(args);
+  const localOnly = flag(args, '--local-only');
   const globalCommand = await globalSksCommand();
-  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand });
+  const res = await initProject(root, { force: flag(args, '--force'), installScope, globalCommand, localOnly });
   console.log(`Initialized Sneakoscope Codex in ${root}`);
   console.log(`Install scope: ${installScope} (${sksCommandPrefix(installScope, { globalCommand })})`);
+  if (localOnly) console.log('Git mode: local-only (.git/info/exclude)');
   for (const x of res.created) console.log(`- ${x}`);
 }
 
@@ -1207,6 +1223,16 @@ async function selftest() {
   await initProject(projectScopeTmp, { installScope: 'project' });
   const projectHooks = await readJson(path.join(projectScopeTmp, '.codex', 'hooks.json'));
   if (projectHooks.hooks.PreToolUse[0].hooks[0].command !== 'node ./node_modules/sneakoscope/bin/sks.mjs hook pre-tool') throw new Error('selftest failed: project install hook command missing');
+  const localOnlyTmp = tmpdir();
+  await ensureDir(path.join(localOnlyTmp, '.git'));
+  await writeTextAtomic(path.join(localOnlyTmp, 'AGENTS.md'), 'existing local rules\n');
+  await initProject(localOnlyTmp, { localOnly: true });
+  const localExclude = await safeReadText(path.join(localOnlyTmp, '.git', 'info', 'exclude'));
+  if (!localExclude.includes('.codex/') || !localExclude.includes('AGENTS.md')) throw new Error('selftest failed: local-only git excludes missing');
+  const localAgents = await safeReadText(path.join(localOnlyTmp, 'AGENTS.md'));
+  if (localAgents.trim() !== 'existing local rules') throw new Error('selftest failed: local-only modified existing AGENTS.md');
+  const localManifest = await readJson(path.join(localOnlyTmp, '.sneakoscope', 'manifest.json'));
+  if (!localManifest.git?.local_only) throw new Error('selftest failed: local-only manifest missing');
   if (!isTransientNpmBinPath('/tmp/.npm/_npx/abc/node_modules/.bin/sks')) throw new Error('selftest failed: npx bin path not recognized as transient');
   if (!isTransientNpmBinPath('/tmp/.npm-cache/_cacache/tmp/git-cloneabc/bin/sks.mjs')) throw new Error('selftest failed: npm cache git clone path not recognized as transient');
   if (isTransientNpmBinPath('/usr/local/bin/sks')) throw new Error('selftest failed: stable global bin marked transient');
@@ -1226,8 +1252,8 @@ async function selftest() {
     if (oldSksBin === undefined) delete process.env.SKS_BIN;
     else process.env.SKS_BIN = oldSksBin;
   }
-  const researchSkillExists = await exists(path.join(tmp, '.agents', 'skills', 'research-discovery', 'SKILL.md'));
-  if (!researchSkillExists) throw new Error('selftest failed: research skill not installed');
+  const legacySkillMirrorExists = await exists(path.join(tmp, '.agents', 'skills', 'research-discovery', 'SKILL.md'));
+  if (legacySkillMirrorExists) throw new Error('selftest failed: legacy .agents/skills mirror still installed');
   const codexAppSkillExists = await exists(path.join(tmp, '.codex', 'skills', 'research-discovery', 'SKILL.md'));
   if (!codexAppSkillExists) throw new Error('selftest failed: Codex App skill not installed');
   const dfSkillExists = await exists(path.join(tmp, '.codex', 'skills', 'DF', 'SKILL.md'));
@@ -1413,7 +1439,7 @@ async function projectWikiClaims(root) {
   const claims = [
     ['wiki-hooks', '.codex/hooks.json routes UserPromptSubmit, tool, permission, and Stop events through SKS guards.', '.codex/hooks.json', 'code', 'high'],
     ['wiki-config', '.codex/config.toml enables Codex App profiles, multi-agent support, and Team agent limits.', '.codex/config.toml', 'code', 'high'],
-    ['wiki-skills', '.codex/skills and .agents/skills provide local routes for DF, Team, Ralph, Research, AutoResearch, DB, GX, wiki, and evaluation workflows.', '.codex/skills', 'code', 'medium'],
+    ['wiki-skills', '.codex/skills provides local routes for DF, Team, Ralph, Research, AutoResearch, DB, GX, wiki, and evaluation workflows.', '.codex/skills', 'code', 'medium'],
     ['wiki-agents', '.codex/agents defines Team planning, implementation, DB safety, and QA reviewer roles.', '.codex/agents', 'code', 'medium'],
     ['wiki-policy', '.sneakoscope/policy.json stores update-check, honest-mode, retention, database, performance, and prompt-pipeline policy.', '.sneakoscope/policy.json', 'contract', 'high'],
     ['wiki-memory', '.sneakoscope/memory stores Q0 raw, Q1 evidence, Q2 facts, Q3 tags, and Q4 control bits for hydratable context.', '.sneakoscope/memory', 'wiki', 'high'],

package/src/core/evaluation.mjs

@@ -38,7 +38,7 @@ export function defaultEvaluationScenario() {
     ['req-wiki-rgba', 'TriWiki stores RGBA-derived trigonometric wiki anchors so compressed context remains hydratable by id, hash, source, and coordinate.', 'code', 'high', 1.2],
     ['req-retention', 'runtime logs and mission artifacts are bounded through retention policy and sks gc.', 'code', 'medium', 0.85],
     ['req-selftest', 'selftest covers contract sealing, DB guard blocking, done-gate evaluation, GX render/validate/drift, snapshot, and retention report.', 'test', 'high', 1.1],
-    ['req-skill', 'sks init installs local skills under .agents/skills so project workflows can trigger domain-specific guidance.', 'code', 'medium', 0.9],
+    ['req-skill', 'sks init installs one canonical local skill set under .codex/skills so project workflows can trigger domain-specific guidance without duplicate commands.', 'code', 'medium', 0.9],
     ['req-design', 'design artifact work should gather design context, build an HTML artifact, expose variations when useful, and verify rendered output.', 'code', 'medium', 0.8]
   ];
   const noise = [

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.6.6';
+export const PACKAGE_VERSION = '0.6.8';
 export const DEFAULT_PROCESS_TAIL_BYTES = 256 * 1024;
 export const DEFAULT_PROCESS_TIMEOUT_MS = 30 * 60 * 1000;
 

package/src/core/init.mjs

@@ -1,5 +1,6 @@
 import path from 'node:path';
-import { ensureDir, readJson, writeJsonAtomic, writeTextAtomic, mergeManagedBlock, nowIso, PACKAGE_VERSION, exists } from './fsx.mjs';
+import fsp from 'node:fs/promises';
+import { ensureDir, readJson, readText, writeJsonAtomic, writeTextAtomic, mergeManagedBlock, nowIso, PACKAGE_VERSION, exists } from './fsx.mjs';
 import { DEFAULT_RETENTION_POLICY } from './retention.mjs';
 import { DEFAULT_DB_SAFETY_POLICY } from './db-safety.mjs';
 
@@ -98,12 +99,15 @@ A task is not done until relevant tests are run or justified, unsupported critic
 export async function initProject(root, opts = {}) {
   const created = [];
   const installScope = normalizeInstallScope(opts.installScope || 'global');
+  const localOnly = Boolean(opts.localOnly);
   const hookCommandPrefix = opts.hookCommandPrefix || sksCommandPrefix(installScope, { globalCommand: opts.globalCommand });
   const sine = path.join(root, '.sneakoscope');
   const dirs = [
-    '.sneakoscope/state', '.sneakoscope/missions', '.sneakoscope/db', '.sneakoscope/bus', '.sneakoscope/hproof', '.sneakoscope/db', '.sneakoscope/wiki', '.sneakoscope/memory/q0_raw', '.sneakoscope/memory/q1_evidence', '.sneakoscope/memory/q2_facts', '.sneakoscope/memory/q3_tags', '.sneakoscope/memory/q4_bits', '.sneakoscope/gx/cartridges', '.sneakoscope/model/fingerprints', '.sneakoscope/genome/candidates', '.sneakoscope/trajectories/raw', '.sneakoscope/locks', '.sneakoscope/tmp', '.sneakoscope/arenas', '.sneakoscope/reports', '.codex', '.codex/skills', '.codex/agents', '.agents/skills'
+    '.sneakoscope/state', '.sneakoscope/missions', '.sneakoscope/db', '.sneakoscope/bus', '.sneakoscope/hproof', '.sneakoscope/db', '.sneakoscope/wiki', '.sneakoscope/memory/q0_raw', '.sneakoscope/memory/q1_evidence', '.sneakoscope/memory/q2_facts', '.sneakoscope/memory/q3_tags', '.sneakoscope/memory/q4_bits', '.sneakoscope/gx/cartridges', '.sneakoscope/model/fingerprints', '.sneakoscope/genome/candidates', '.sneakoscope/trajectories/raw', '.sneakoscope/locks', '.sneakoscope/tmp', '.sneakoscope/arenas', '.sneakoscope/reports', '.codex', '.codex/skills', '.codex/agents'
   ];
   for (const d of dirs) await ensureDir(path.join(root, d));
+  const localExclude = localOnly ? await ensureLocalOnlyGitExclude(root) : null;
+  if (localExclude?.path) created.push(`${path.relative(root, localExclude.path)} local-only excludes`);
 
   await writeJsonAtomic(path.join(sine, 'manifest.json'), {
     package: 'sneakoscope',
@@ -138,6 +142,11 @@ export async function initProject(root, opts = {}) {
       channel_map: { r: 'domainAngle', g: 'layerRadius', b: 'phase', a: 'concentration' },
       continuity_model: 'selected_text_plus_hydratable_rgba_trig_anchors'
     },
+    git: {
+      local_only: localOnly,
+      exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : null,
+      excluded_patterns: localExclude?.patterns || []
+    },
     database_safety: 'destructive_db_operations_denied_always',
     gx_renderer: 'deterministic_svg_html'
   });
@@ -157,7 +166,13 @@ export async function initProject(root, opts = {}) {
     const policy = await readJson(policyPath, {});
     await writeJsonAtomic(policyPath, {
       ...policy,
-      installation: installPolicy(installScope, hookCommandPrefix)
+      installation: installPolicy(installScope, hookCommandPrefix),
+      git: {
+        ...(policy.git || {}),
+        local_only: localOnly || Boolean(policy.git?.local_only),
+        exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : policy.git?.exclude_path || null,
+        excluded_patterns: localExclude?.patterns || policy.git?.excluded_patterns || []
+      }
     });
   }
 
@@ -165,6 +180,11 @@ export async function initProject(root, opts = {}) {
     return {
       schema_version: 1,
       installation: installPolicy(scope, commandPrefix),
+      git: {
+        local_only: localOnly,
+        exclude_path: localExclude?.path ? path.relative(root, localExclude.path) : null,
+        excluded_patterns: localExclude?.patterns || []
+      },
       retention: DEFAULT_RETENTION_POLICY,
       update_check: {
         enabled: true,
@@ -244,8 +264,13 @@ export async function initProject(root, opts = {}) {
     created.push('.sneakoscope/state/current.json');
   }
 
-  await mergeManagedBlock(path.join(root, 'AGENTS.md'), 'Sneakoscope Codex GX MANAGED BLOCK', AGENTS_BLOCK);
-  created.push('AGENTS.md managed block');
+  const agentsMdPath = path.join(root, 'AGENTS.md');
+  if (localOnly && await exists(agentsMdPath)) {
+    created.push('AGENTS.md skipped (local-only existing file)');
+  } else {
+    await mergeManagedBlock(agentsMdPath, 'Sneakoscope Codex GX MANAGED BLOCK', AGENTS_BLOCK);
+    created.push('AGENTS.md managed block');
+  }
 
   await writeTextAtomic(path.join(root, '.codex', 'config.toml'), `[features]\ncodex_hooks = true\nmulti_agent = true\n\n[agents]\nmax_threads = 6\nmax_depth = 1\n\n[agents.team_consensus]\ndescription = "Planning and debate agent for SKS Team mode. Maps options, constraints, risks, and proposes the agreed objective before implementation starts."\nconfig_file = "./agents/team-consensus.toml"\nnickname_candidates = ["Consensus", "Atlas"]\n\n[agents.implementation_worker]\ndescription = "Implementation worker for SKS Team mode. Owns a clearly bounded write set and coordinates with other workers without reverting their edits."\nconfig_file = "./agents/implementation-worker.toml"\nnickname_candidates = ["Builder", "Mason"]\n\n[agents.db_safety_reviewer]\ndescription = "Read-only database safety reviewer for SQL, migrations, RLS, destructive-operation risk, and rollback safety."\nconfig_file = "./agents/db-safety-reviewer.toml"\nnickname_candidates = ["Sentinel", "Ledger"]\n\n[agents.qa_reviewer]\ndescription = "Read-only verification reviewer for correctness, tests, regressions, and missing evidence."\nconfig_file = "./agents/qa-reviewer.toml"\nnickname_candidates = ["Verifier", "Scout"]\n\n[profiles.sks-ralph]\nmodel = "gpt-5.5"\napproval_policy = "never"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "high"\n\n[profiles.sks-research]\nmodel = "gpt-5.5"\napproval_policy = "never"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "xhigh"\n\n[profiles.sks-team]\nmodel = "gpt-5.5"\napproval_policy = "on-request"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "high"\n\n[profiles.sks-default]\nmodel = "gpt-5.5"\napproval_policy = "on-request"\nsandbox_mode = "workspace-write"\nmodel_reasoning_effort = "medium"\n`);
   created.push('.codex/config.toml');
@@ -264,14 +289,40 @@ export async function initProject(root, opts = {}) {
   });
   created.push(`.codex/hooks.json (${installScope})`);
 
-  await installSkills(root);
+  const skillInstall = await installSkills(root);
   created.push('.codex/skills/*');
-  created.push('.agents/skills/*');
+  if (skillInstall.removed_legacy_agent_skill_dirs.length) created.push(`.agents/skills legacy mirrors removed (${skillInstall.removed_legacy_agent_skill_dirs.length})`);
   await installCodexAgents(root);
   created.push('.codex/agents/*');
   return { created };
 }
 
+async function ensureLocalOnlyGitExclude(root) {
+  const gitDir = await resolveGitDir(root);
+  if (!gitDir) return { path: null, patterns: [] };
+  const patterns = ['.sneakoscope/', '.codex/', '.agents/', 'AGENTS.md'];
+  const excludePath = path.join(gitDir, 'info', 'exclude');
+  await ensureDir(path.dirname(excludePath));
+  const markerStart = '# Sneakoscope Codex local-only generated files';
+  const current = await readText(excludePath, '');
+  if (!current.includes(markerStart)) {
+    const block = `${markerStart}\n${patterns.join('\n')}\n`;
+    await writeTextAtomic(excludePath, `${current.trimEnd()}${current.trim() ? '\n\n' : ''}${block}`);
+  }
+  return { path: excludePath, patterns };
+}
+
+async function resolveGitDir(root) {
+  const dotGit = path.join(root, '.git');
+  if (!(await exists(dotGit))) return null;
+  const text = await readText(dotGit, null);
+  if (typeof text === 'string') {
+    const match = text.match(/^gitdir:\s*(.+)\s*$/m);
+    if (match) return path.resolve(root, match[1]);
+  }
+  return dotGit;
+}
+
 function codexAppQuickReference(scope, commandPrefix) {
   return `# Sneakoscope Codex for Codex App
 
@@ -385,12 +436,44 @@ async function installSkills(root) {
     'design-artifact-expert': `---\nname: design-artifact-expert\ndescription: Create or revise high-fidelity HTML, UI, prototype, deck-like, or visual design artifacts using project design context, variations, and rendered verification.\n---\n\nUse when the user asks for design, UI, prototype, HTML artifact, landing page, deck-like visual work, interaction design, or visual refinement.\n\nWorkflow:\n1. Understand the artifact, audience, constraints, fidelity, variants, and existing brand/design system.\n2. Inspect local code, assets, screenshots, or design-system docs before inventing visuals. If context exists, follow its visual vocabulary.\n3. Build the actual usable screen or artifact first; avoid empty landing-page framing unless the task is explicitly marketing.\n4. Use descriptive HTML filenames. Keep large artifacts split into small support files when needed.\n5. For screens/slides, add data-screen-label attributes for comment context. Slide labels are 1-indexed.\n6. Preserve state for decks, videos, or multi-step prototypes with localStorage when refresh continuity matters.\n7. Expose a small Tweaks surface for useful variants such as layout, density, color, copy, or interaction options.\n8. Verify the artifact renders cleanly in a browser or preview. For design tasks, set done-gate.json design_verification_required/present fields and cite evidence.\n\nQuality bar:\n- Root design decisions in available assets and components.\n- Use restrained, domain-appropriate layout and typography.\n- Avoid text overlap, unreadable controls, decorative clutter, one-note palettes, and placeholder-only deliverables.\n- Prefer icons and familiar controls for tool actions, and make repeated UI dimensions stable.\n`
   };
   for (const [name, content] of Object.entries(skills)) {
-    for (const base of ['.codex/skills', '.agents/skills']) {
-      const dir = path.join(root, base, name);
-      await ensureDir(dir);
-      await writeTextAtomic(path.join(dir, 'SKILL.md'), `${content.trim()}\n`);
-    }
+    const dir = path.join(root, '.codex', 'skills', name);
+    await ensureDir(dir);
+    await writeTextAtomic(path.join(dir, 'SKILL.md'), `${content.trim()}\n`);
   }
+  return { removed_legacy_agent_skill_dirs: await removeLegacyAgentSkillMirrors(root, Object.keys(skills)) };
+}
+
+async function removeLegacyAgentSkillMirrors(root, skillNames) {
+  const legacyRoot = path.join(root, '.agents', 'skills');
+  if (!(await exists(legacyRoot))) return [];
+  const removed = [];
+  for (const name of skillNames) {
+    const dir = path.join(legacyRoot, name);
+    const skillPath = path.join(dir, 'SKILL.md');
+    const text = await readText(skillPath, null);
+    if (!isGeneratedSksLegacySkill(text, name)) continue;
+    await fsp.rm(dir, { recursive: true, force: true });
+    removed.push(path.relative(root, dir));
+  }
+  await removeDirIfEmpty(legacyRoot);
+  await removeDirIfEmpty(path.join(root, '.agents'));
+  return removed;
+}
+
+function isGeneratedSksLegacySkill(text, name) {
+  if (typeof text !== 'string') return false;
+  return text.startsWith('---') && new RegExp(`^name:\\s*${escapeRegExp(name)}\\s*$`, 'm').test(text);
+}
+
+function escapeRegExp(value) {
+  return String(value).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+async function removeDirIfEmpty(dir) {
+  try {
+    const entries = await fsp.readdir(dir);
+    if (!entries.length) await fsp.rmdir(dir);
+  } catch {}
 }
 
 async function installCodexAgents(root) {