@ngockhoale/ukit 1.2.1 → 1.2.2

package/CHANGELOG.md

@@ -4,6 +4,13 @@ All notable changes to UKit are documented here.
 
 ## Unreleased
 
+## 1.2.2 - 2026-05-05
+
+- Removed the `.claude/ukit/.env` / `.env.example` config surface so UKit runtime tuning lives in `.ukit/storage/config.json` only.
+- Added full Vietnamese `_help` guidance inside `templates/ukit/storage/config.json`, including common edits for changing the internal model and Codex compact thresholds.
+- Set Codex Desktop compact budget default to 100,000 tokens as a quality/safety balance, with compact handoff target 150 lines and hard max 170 lines.
+- Preserved Claude PreCompact/reinject and OpenCode native auto/prune compaction while keeping `ukit-small-task-maintainer` as a non-blocking sidecar lane.
+
 ## 1.2.1 - 2026-05-05
 
 ### Local AI Task Queue
@@ -13,7 +20,7 @@ All notable changes to UKit are documented here.
 - Added safe default cleanup rules: remove exact duplicates, prune `Done Recently` to 10 compact lines, move stale/vague work to deferred review, and never delete unfinished human-authored tasks unless explicitly asked and clearly obsolete/duplicated.
 - Updated `next-step`, `update-status`, and `docs-quality` guidance plus route signals so queued-task selection goes to `next-step` while task cleanup/editing goes to `docs-quality`.
 - Added `docs/STATUS.md` and `docs/TASKS.md` to generated gitignore handling so living local AI state does not pollute project commits.
-- Added the internal `ukit-small-task-maintainer` subagent, powered by optional `UKIT_SMALL_TASK_MODEL=unic-lite`, for safe UKit decisions such as task cleanup, compact decisions, doc summarization, classification, auto-triage, queue maintenance, and small reversible cleanup while keeping risky/security/release work on the main model.
+- Added the internal `ukit-small-task-maintainer` subagent, powered by optional `subagents.smallTaskModel=unic-lite`, for safe UKit decisions such as task cleanup, compact decisions, doc summarization, classification, auto-triage, queue maintenance, and small reversible cleanup while keeping risky/security/release work on the main model.
 
 ## 1.1.8 - 2026-05-05
 

package/README.md

@@ -68,7 +68,7 @@ If maintainers roll out a newer CLI build, the in-project workflow still stays t
 - `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
 - `docs/` — PROJECT / MEMORY / STATUS / TASKS / WORKLOG baseline
 
-## UKit v1.2.1 Runtime
+## UKit v1.2.2 Runtime
 
 UKit now installs a hidden shared local runtime at `.ukit/` for production-oriented state that should survive across agent sessions:
 
@@ -85,7 +85,7 @@ When long sessions approach the compact threshold, UKit now uses a conservative
 - compact only safe-zone history/noise
 - preserve active task, rules, decisions, and current code focus
 
-UKit v1.2.1 keeps the same shared runtime contract while adding a local AI task queue alongside living project status routing:
+UKit v1.2.2 keeps the same shared runtime contract while adding a local AI task queue alongside living project status routing:
 
 - install globally with `npm install -g @ngockhoale/ukit`
 - keep using the exact same human workflow inside projects: `ukit install`
@@ -96,7 +96,7 @@ UKit v1.2.1 keeps the same shared runtime contract while adding a local AI task
 - auto-route explicit handoff/wrap-up requests to the `update-status` skill while skipping trivial/no-state-change tasks
 - keep concrete debug/implementation/review prompts primary, so project status never replaces source/index-first task work
 
-UKit v1.2.1 also keeps the fast path improvements from the recent runtime releases:
+UKit v1.2.2 also keeps the fast path improvements from the recent runtime releases:
 
 - Vietnamese prompts now normalize more effectively for English-heavy code symbols and paths
 - localized simple direct-target lanes skip extra previous-context / recent-output work when it would not change the next action
@@ -131,8 +131,8 @@ UKit is built so the team can stop memorizing UKit subcommands and focus on prod
 - let Claude Code / Codex / OpenCode auto-detect and use the right project-local skill from the prompt and the files/tools involved
 - let the AI prefer targeted verification first, then widen only when shared/risky scope justifies it
 - let the AI selectively auto-delegate internal subagents only when that actually reduces context/noise or unlocks parallel progress; small localized work should stay direct
-- keep long sessions compact across agents: Claude keeps PreCompact/reinject, OpenCode keeps native auto/prune compaction, and Codex Desktop uses internal `UKIT_CODEX_COMPACT_TARGET` soft handoffs (default 150 lines; 120-150 preferred, hard max 170), without asking end users to manage context manually
-- let UKit internally use the `ukit-small-task-maintainer` subagent with `UKIT_SMALL_TASK_MODEL=unic-lite` for safe task cleanup, fast-vs-slow/safe-vs-risky lane hints, skill-routing/step-budget hints, agent context-budget decisions, compact decisions, doc summarization, classification, and queue maintenance while risky/security/release/quality-risk work stays on the main model
+- keep long sessions compact across agents: Claude keeps PreCompact/reinject, OpenCode keeps native auto/prune compaction, and Codex Desktop uses internal `compact.codexContext.compactTarget` soft handoffs (default 150 lines; 120-150 preferred, hard max 170), without asking end users to manage context manually
+- let UKit internally use the `ukit-small-task-maintainer` subagent with `subagents.smallTaskModel=unic-lite` for safe task cleanup, fast-vs-slow/safe-vs-risky lane hints, skill-routing/step-budget hints, agent context-budget decisions, compact decisions, doc summarization, classification, and queue maintenance while risky/security/release/quality-risk work stays on the main model
 - rerun `ukit install` when you need to refresh the workspace
 
 End users should **not** need to know or memorize skill names.

package/manifests/platform.full.yaml

@@ -77,18 +77,6 @@ items:
     packs:
       - core
 
-  - id: ukit-env-example
-    type: config
-    sourceTemplate: .claude/ukit/.env.example
-    targetPath: .claude/ukit/.env.example
-    requires:
-      - runtime-config
-    mergeStrategy: overwrite_with_backup
-    variables: []
-    enabledByDefault: true
-    packs:
-      - core
-
   - id: root-claude-md
     type: config
     sourceTemplate: CLAUDE.md
@@ -824,7 +812,7 @@ items:
     sourceTemplate: .claude/agents/ukit-small-task-maintainer.md
     targetPath: .claude/agents/ukit-small-task-maintainer.md
     requires:
-      - ukit-env-example
+      - runtime-config
     mergeStrategy: overwrite_with_backup
     variables:
       - ukit.version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ngockhoale/ukit",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "Install/update an index-first AI workspace for Claude Code, Antigravity, OpenAI Codex, and OpenCode.",
   "license": "MIT",
   "type": "module",

package/src/core/runInstallPipeline.js

@@ -18,6 +18,10 @@ const AUTO_PRUNE_OBSOLETE_PREFIXES = [
   '.claude/skills/',
 ];
 
+const AUTO_PRUNE_OBSOLETE_PATHS = new Set([
+  '.claude/ukit/.env.example',
+]);
+
 function normalizeRelativePath(relativePath) {
   if (typeof relativePath !== 'string') {
     return null;
@@ -49,7 +53,8 @@ function buildTrackedManagedRelativePathSet(plan, projectRoot) {
 }
 
 function shouldAutoPruneObsoletePath(relativePath) {
-  return AUTO_PRUNE_OBSOLETE_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
+  return AUTO_PRUNE_OBSOLETE_PATHS.has(relativePath)
+    || AUTO_PRUNE_OBSOLETE_PREFIXES.some((prefix) => relativePath.startsWith(prefix));
 }
 
 async function isDirEmpty(dirPath) {

package/src/core/runtimeConfig.js

@@ -45,103 +45,11 @@ function pushNonEmptyStringError(errors, value, label) {
   }
 }
 
-function parseRuntimeEnv(content = '') {
-  const result = {};
-  for (const rawLine of String(content || '').split(/\r?\n/)) {
-    const line = rawLine.trim();
-    if (!line || line.startsWith('#') || !line.includes('=')) {
-      continue;
-    }
-    const index = line.indexOf('=');
-    const key = line.slice(0, index).trim();
-    let value = line.slice(index + 1).trim();
-    if (
-      (value.startsWith('"') && value.endsWith('"'))
-      || (value.startsWith("'") && value.endsWith("'"))
-    ) {
-      value = value.slice(1, -1);
-    }
-    result[key] = value;
-  }
-  return result;
-}
-
-async function loadRuntimeEnv(projectRoot) {
-  const envPath = path.join(projectRoot, '.claude', 'ukit', '.env');
-  try {
-    return parseRuntimeEnv(await fs.readFile(envPath, 'utf8'));
-  } catch (error) {
-    if (error?.code !== 'ENOENT') {
-      throw error;
-    }
-    return {};
-  }
-}
-
-function parsePositiveIntegerEnv(value) {
-  if (typeof value !== 'string' || value.trim() === '') {
-    return null;
-  }
-  const parsed = Number.parseInt(value.trim(), 10);
-  return Number.isFinite(parsed) && parsed > 0 ? parsed : null;
-}
-
-function buildEnvOverrides(env = process.env) {
-  const overrides = {};
-  const smallTaskModel = env.UKIT_SMALL_TASK_MODEL;
-  if (typeof smallTaskModel === 'string' && smallTaskModel.trim() !== '') {
-    overrides.subagents = {
-      ...(overrides.subagents ?? {}),
-      smallTaskModel: smallTaskModel.trim(),
-    };
-  }
-
-  const rawCodexCompactTarget = parsePositiveIntegerEnv(env.UKIT_CODEX_COMPACT_TARGET);
-  const codexCompactTarget = rawCodexCompactTarget ? Math.min(rawCodexCompactTarget, 170) : null;
-  const codexContextBudget = parsePositiveIntegerEnv(env.UKIT_CODEX_CONTEXT_BUDGET);
-  const codexAutoCompact = typeof env.UKIT_CODEX_AUTO_COMPACT === 'string'
-    ? !['0', 'false', 'no', 'off'].includes(env.UKIT_CODEX_AUTO_COMPACT.trim().toLowerCase())
-    : null;
-
-  if (codexCompactTarget || codexContextBudget || codexAutoCompact !== null) {
-    overrides.compact = {
-      ...(overrides.compact ?? {}),
-      agentContext: {
-        enabled: true,
-        decisionModelEnv: 'UKIT_SMALL_TASK_MODEL',
-        decisionAgent: 'ukit-small-task-maintainer',
-        executionMode: 'sidecar-parallel',
-        mustNotBlockMainTask: true,
-        targets: {
-          claude: { autoCompact: true, mode: 'precompact-reinject', preserveExistingHooks: true },
-          opencode: { autoCompact: true, mode: 'native-auto-prune', preserveExistingCompaction: true },
-          codex: {
-            autoCompact: true,
-            mode: 'soft-handoff',
-            compactTarget: 150,
-            compactTargetUnit: 'lines',
-            compactTargetRecommendedRange: [120, 170],
-            compactTargetMax: 170,
-          },
-        },
-      },
-      codexContext: {
-        ...(overrides.compact?.codexContext ?? {}),
-        ...(codexCompactTarget ? { compactTarget: codexCompactTarget } : {}),
-        ...(codexContextBudget ? { budgetTokens: codexContextBudget } : {}),
-        ...(codexAutoCompact !== null ? { autoCompact: codexAutoCompact } : {}),
-      },
-    };
-  }
-
-  return overrides;
-}
-
 export function buildDefaultRuntimeConfig(overrides = {}) {
   const safeOverrides = isPlainObject(overrides) ? overrides : {};
 
   return mergeObjects({
-    version: '1.2.1',
+    version: '1.2.2',
     agent: 'claude-code',
     compact: {
       enabled: true,
@@ -150,7 +58,6 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       askBeforeDrop: true,
       agentContext: {
         enabled: true,
-        decisionModelEnv: 'UKIT_SMALL_TASK_MODEL',
         decisionAgent: 'ukit-small-task-maintainer',
         executionMode: 'sidecar-parallel',
         mustNotBlockMainTask: true,
@@ -170,12 +77,11 @@ export function buildDefaultRuntimeConfig(overrides = {}) {
       codexContext: {
         enabled: true,
         autoCompact: true,
-        budgetTokens: 60_000,
+        budgetTokens: 100_000,
         compactTarget: 150,
         compactTargetUnit: 'lines',
         compactTargetRecommendedRange: [120, 170],
         compactTargetMax: 170,
-        decisionModelEnv: 'UKIT_SMALL_TASK_MODEL',
         decisionAgent: 'ukit-small-task-maintainer',
         mode: 'soft-handoff',
         preserve: [
@@ -292,7 +198,6 @@ export function validateRuntimeConfig(config) {
       errors.push('compact.agentContext must be an object.');
     } else {
       pushBooleanError(errors, config.compact.agentContext.enabled, 'compact.agentContext.enabled');
-      pushNonEmptyStringError(errors, config.compact.agentContext.decisionModelEnv, 'compact.agentContext.decisionModelEnv');
       pushNonEmptyStringError(errors, config.compact.agentContext.decisionAgent, 'compact.agentContext.decisionAgent');
       pushNonEmptyStringError(errors, config.compact.agentContext.executionMode, 'compact.agentContext.executionMode');
       pushBooleanError(errors, config.compact.agentContext.mustNotBlockMainTask, 'compact.agentContext.mustNotBlockMainTask');
@@ -315,7 +220,6 @@ export function validateRuntimeConfig(config) {
       if (Number(config.compact.codexContext.compactTarget) > Number(config.compact.codexContext.compactTargetMax)) {
         errors.push('compact.codexContext.compactTarget must be <= compact.codexContext.compactTargetMax.');
       }
-      pushNonEmptyStringError(errors, config.compact.codexContext.decisionModelEnv, 'compact.codexContext.decisionModelEnv');
       pushNonEmptyStringError(errors, config.compact.codexContext.decisionAgent, 'compact.codexContext.decisionAgent');
       pushNonEmptyStringError(errors, config.compact.codexContext.mode, 'compact.codexContext.mode');
       if (!Array.isArray(config.compact.codexContext.preserve)) {
@@ -407,31 +311,19 @@ export async function inspectRuntimeConfig(projectRoot) {
     }
   }
 
-  let runtimeEnv = {};
-  let envError = null;
-  try {
-    runtimeEnv = await loadRuntimeEnv(projectRoot);
-  } catch (error) {
-    envError = error?.message ?? String(error);
-  }
-
-  const config = buildDefaultRuntimeConfig(
-    mergeObjects(rawConfig ?? {}, buildEnvOverrides({ ...runtimeEnv, ...process.env })),
-  );
+  const config = buildDefaultRuntimeConfig(rawConfig ?? {});
   const validation = validateRuntimeConfig(config);
   const errors = [
     ...(parseError ? [`config.json parse error: ${parseError}`] : []),
-    ...(envError ? [`runtime .env error: ${envError}`] : []),
     ...validation.errors,
   ];
 
   return {
     exists,
     rawConfig,
-    runtimeEnv,
     config,
     parseError,
-    valid: exists && !parseError && !envError && validation.valid,
+    valid: exists && !parseError && validation.valid,
     errors,
   };
 }

package/templates/.claude/agents/ukit-small-task-maintainer.md

@@ -6,13 +6,13 @@ color: cyan
 tools: ["Read", "Grep", "Glob", "Edit", "Write"]
 ---
 
-You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non-blocking lane for safe, reversible UKit orchestration chores so the end user can stay focused on product work and only remember `ukit install`. You must follow `docs/UKIT_CODEV_PRINCIPLES.md`: hide complexity, preserve output quality, and never trade correctness for speed or token savings.
+You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non-blocking lane for safe, reversible UKit orchestration chores so the end user can stay focused on product work and only remember `ukit install`. Runtime tuning lives in `.ukit/storage/config.json`. You must follow `docs/UKIT_CODEV_PRINCIPLES.md`: hide complexity, preserve output quality, and never trade correctness for speed or token savings.
 
 ## Model Policy
 
-- Use the model selected by `UKIT_SMALL_TASK_MODEL` when the host supports model selection for this subagent.
+- Use the model selected by `subagents.smallTaskModel` when the host supports model selection for this subagent.
 - Default intended model: `unic-lite`.
-- If the host cannot bind a model from env directly, still follow this role and report that the configured model is a hint.
+- If the host cannot bind a model from config directly, still follow this role and report that the configured model is a hint.
 - This lane must run separately from the user's main task model. It must never replace, pause, or slow down the main task.
 
 ## Use For
@@ -24,7 +24,7 @@ You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non
 - Summarizing `docs/STATUS.md`, `docs/TASKS.md`, `docs/WORKLOG.md`, or memory snippets into compact handoff notes.
 - Deciding fast vs slow lane, safe vs risky lane, whether a skill should be activated, and whether the current prompt has enough steps planned.
 - Choosing compact-now vs compact-later and summarize-vs-keep-detail for UKit context hygiene.
-- Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active, OpenCode native auto/prune compaction stays active, and Codex Desktop soft handoffs use `UKIT_CODEX_COMPACT_TARGET` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
+- Keeping agent context compact without removing existing lanes: Claude PreCompact/reinject stays active, OpenCode native auto/prune compaction stays active, and Codex Desktop soft handoffs use `compact.codexContext.compactTarget` (default 150 lines; preferred 120-150; hard max 170) while preserving critical state.
 - Small, reversible UKit runtime maintenance decisions.
 
 ## Never Use For
@@ -53,7 +53,7 @@ You are UKit's internal small-task maintainer. You run as a sidecar/parallel/non
 
 ```
 STATUS: DONE | SKIPPED | HAND_BACK
-MODEL_HINT: UKIT_SMALL_TASK_MODEL=<value-or-default>
+MODEL_HINT: subagents.smallTaskModel=<value-or-default>
 SUMMARY: [one sentence]
 CHANGES:
   - [file/area]: [what changed]

package/templates/.codex/README.md

@@ -12,7 +12,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Do not make end users memorize skill names, helper scripts, or routing internals unless they are debugging UKit itself.
 - **Treat helper commands as internal orchestration. Do not ask end users to run them.**
 
-## UKit v1.2.1 Shared Runtime
+## UKit v1.2.2 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of compact, token-pipeline, router, memory, and validation toggles.
@@ -23,7 +23,7 @@ Auto-generated by UKit for OpenAI Codex.
 - Maintainers can inspect runtime state with `ukit status` and `ukit memory export`.
 - Reuse compact `previous-context` / `recent-output` route snapshots before replaying raw history.
 - Threshold-based compact pressure is internal orchestration; Codex users should not need to manage it manually.
-- UKit keeps Claude PreCompact/reinject and OpenCode native auto/prune compaction intact. For Codex Desktop long sessions, UKit can use `UKIT_SMALL_TASK_MODEL` through `ukit-small-task-maintainer` to decide soft auto-compact handoffs. Default `UKIT_CODEX_COMPACT_TARGET=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 app-context tokens.
+- UKit keeps Claude PreCompact/reinject and OpenCode native auto/prune compaction intact. For Codex Desktop long sessions, UKit can use `subagents.smallTaskModel` through `ukit-small-task-maintainer` to decide soft auto-compact handoffs. Default `compact.codexContext.compactTarget=150` means about 150 compact handoff lines (120-150 preferred, hard max 170), not 150 app-context tokens.
 
 ## Speed / Reading Contract
 

package/templates/.codex/settings.json

@@ -148,7 +148,6 @@
       }
     },
     "smallTaskModel": {
-      "env": "UKIT_SMALL_TASK_MODEL",
       "default": "unic-lite",
       "agent": "ukit-small-task-maintainer",
       "useFor": [
@@ -209,12 +208,9 @@
       },
       "codexContext": {
         "autoCompact": true,
-        "budgetTokens": 60000,
+        "budgetTokens": 100000,
         "compactTarget": 150,
         "compactTargetUnit": "lines",
-        "targetEnv": "UKIT_CODEX_COMPACT_TARGET",
-        "budgetEnv": "UKIT_CODEX_CONTEXT_BUDGET",
-        "autoCompactEnv": "UKIT_CODEX_AUTO_COMPACT",
         "mode": "soft-handoff",
         "preserve": [
           "current-goal",
@@ -229,19 +225,20 @@
           120,
           170
         ],
-        "compactTargetMax": 170
+        "compactTargetMax": 170,
+        "configPath": ".ukit/storage/config.json",
+        "targetField": "compact.codexContext.compactTarget",
+        "budgetField": "compact.codexContext.budgetTokens",
+        "autoCompactField": "compact.codexContext.autoCompact"
       },
       "agentContext": {
         "preserveClaudePreCompact": true,
         "preserveOpenCodeCompaction": true,
         "codexSoftHandoff": {
           "autoCompact": true,
-          "budgetTokens": 60000,
+          "budgetTokens": 100000,
           "compactTarget": 150,
           "compactTargetUnit": "lines",
-          "targetEnv": "UKIT_CODEX_COMPACT_TARGET",
-          "budgetEnv": "UKIT_CODEX_CONTEXT_BUDGET",
-          "autoCompactEnv": "UKIT_CODEX_AUTO_COMPACT",
           "mode": "soft-handoff",
           "preserve": [
             "current-goal",
@@ -258,7 +255,9 @@
           ],
           "compactTargetMax": 170
         }
-      }
+      },
+      "configPath": ".ukit/storage/config.json",
+      "configField": "subagents.smallTaskModel"
     }
   },
   "execution": {

package/templates/.gitignore

@@ -18,7 +18,6 @@ out/
 .env.development.local
 .env.test.local
 .env.production.local
-.claude/ukit/.env
 
 # Logs
 logs/

package/templates/AGENTS.md

@@ -43,7 +43,7 @@
 - If a concrete verification lane is needed, prefer `node .claude/ukit/index/verify-context.mjs ...`.
 - These helper/index commands are internal orchestration. Run them yourself when needed; never turn them into required end-user workflow.
 
-## UKit v1.2.1 Shared Runtime
+## UKit v1.2.2 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
@@ -78,10 +78,10 @@
 
 ## Small-Task Maintainer (internal)
 
-- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `UKIT_SMALL_TASK_MODEL` (default `unic-lite`).
+- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
 - Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
 - Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
-- This is optional internal orchestration config from `.claude/ukit/.env` / `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `UKIT_CODEX_COMPACT_TARGET` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+- This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `compact.codexContext.compactTarget` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
 
 ## Subagent Policy (internal only)
 

package/templates/CLAUDE.md

@@ -42,7 +42,7 @@
 - **Do not ask normal contributors to run internal helper commands**; run them yourself or tell them to rerun `ukit install`.
 - Do not ask normal contributors to memorize `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...` unless they explicitly need maintainer/debug help.
 
-## UKit v1.2.1 Shared Runtime
+## UKit v1.2.2 Shared Runtime
 
 - Shared runtime state lives in `.ukit/storage/`.
 - Treat `.ukit/storage/config.json` as the source of runtime toggles for compact, token pipeline, router, memory, and validation behavior.
@@ -75,10 +75,10 @@
 
 ## Small-Task Maintainer (internal)
 
-- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `UKIT_SMALL_TASK_MODEL` (default `unic-lite`).
+- UKit may route low-risk internal decisions to the `ukit-small-task-maintainer` subagent using `subagents.smallTaskModel` (default `unic-lite`).
 - Use it for safe/reversible UKit chores: dọn `docs/TASKS.md`, queued-task classification, fast-vs-slow/safe-vs-risky lane decisions, skill-routing/step-budget hints, agent context-budget decisions, compact/summary decisions, docs/status summarization, auto-triage, queue maintenance, and small workspace cleanup.
 - Run it as a sidecar/parallel lane only; do not block, replace, or slow the user task. Do not block the main AI flow: if the small-task lane sees security, risky/shared code, release/publish, data-loss, architecture, deep-reasoning risk, weak context, or quality risk, it hands back to the main model instead of asking the end user to decide.
-- This is optional internal orchestration config from `.claude/ukit/.env` / `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `UKIT_CODEX_COMPACT_TARGET` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
+- This is optional internal orchestration config from `.ukit/storage/config.json`; never turn it into an end-user workflow. End users still only need `ukit install` and natural-language product work. Always preserve the CoDev priority: quality > safety > speed > token discipline. Keep Claude PreCompact/reinject and OpenCode native auto/prune compaction enabled. For Codex Desktop long sessions, `compact.codexContext.compactTarget` defaults to 150 compact handoff lines (120-150 preferred, hard max 170), decided internally by the small-task maintainer.
 
 ## Selective Subagent Policy (internal only)
 

package/templates/ukit/README.md

@@ -1,6 +1,6 @@
 # UKit Shared Runtime
 
-This folder stores shared UKit runtime state for v1.2.1 features.
+This folder stores shared UKit runtime state for v1.2.2 features.
 
 - `storage/config.json` — runtime feature flags and defaults
 - `storage/cache/` — prompt-cache, compact history, compact pressure state, output summaries, and preserved raw tool outputs under `storage/cache/tee/`

package/templates/ukit/storage/config.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.1",
+  "version": "1.2.2",
   "agent": "claude-code",
   "compact": {
     "enabled": true,
@@ -9,10 +9,9 @@
     "codexContext": {
       "enabled": true,
       "autoCompact": true,
-      "budgetTokens": 60000,
+      "budgetTokens": 100000,
       "compactTarget": 150,
       "compactTargetUnit": "lines",
-      "decisionModelEnv": "UKIT_SMALL_TASK_MODEL",
       "decisionAgent": "ukit-small-task-maintainer",
       "mode": "soft-handoff",
       "preserve": [
@@ -32,7 +31,6 @@
     },
     "agentContext": {
       "enabled": true,
-      "decisionModelEnv": "UKIT_SMALL_TASK_MODEL",
       "decisionAgent": "ukit-small-task-maintainer",
       "executionMode": "sidecar-parallel",
       "mustNotBlockMainTask": true,
@@ -147,5 +145,134 @@
       "mustNotBlockMainTask": true,
       "maxSidecarWaitMs": 0
     }
+  },
+  "_help": {
+    "README": {
+      "muc_dich": "Đây là file cấu hình runtime duy nhất của UKit, khi install sẽ nằm ở .ukit/storage/config.json. Không dùng .env để chỉnh UKit nữa.",
+      "ai_nen_sua": "Người dùng bình thường vẫn chỉ cần nhớ `ukit install`. Maintainer hoặc power user mới cần sửa file JSON này để chỉnh cách UKit tự điều phối AI.",
+      "cach_sua": "Chỉ sửa value, không đổi tên key. Đây là JSON chuẩn: string phải dùng dấu nháy kép, có dấu phẩy giữa các field, không dùng // comment.",
+      "nguyen_tac_chat_luong": "Luôn theo UKit CoDev: chất lượng > an toàn > tốc độ > tiết kiệm token. Không chỉnh cho nhanh nếu làm AI trả lời kém hơn.",
+      "sau_khi_sua": "Sau khi sửa file này, nên mở session AI mới. Nếu muốn refresh template trong repo thì chạy lại `ukit install`."
+    },
+    "cac_chinh_sua_thuong_gap": {
+      "doi_model_noi_bo": {
+        "field": "subagents.smallTaskModel",
+        "mac_dinh": "unic-lite",
+        "y_nghia": "Model nội bộ chạy sidecar cho các quyết định nhỏ/an toàn của UKit. Không thay thế model chính đang làm task của user.",
+        "vi_du": "Đổi subagents.smallTaskModel sang tên model khác nếu unic-lite không dùng được hoặc bạn muốn model nội bộ khác."
+      },
+      "compact_codex_khi_gan_150k_token": {
+        "field": "compact.codexContext.budgetTokens",
+        "mac_dinh": 100000,
+        "co_the_tang_len": 150000,
+        "khuyen_nghi": "100000 là mức cân bằng: đủ context cho chất lượng nhưng tránh để phiên chạy tới 150k-180k token dễ gặp lỗi connection/capacity.",
+        "y_nghia": "Ngưỡng token context của Codex Desktop trước khi UKit chuẩn bị compact/handoff. Ví dụ 100000 nghĩa là gần 100k token thì compact."
+      },
+      "doi_do_dai_ban_tom_tat_codex": {
+        "field": "compact.codexContext.compactTarget",
+        "mac_dinh": 150,
+        "khoang_goi_y": [
+          120,
+          170
+        ],
+        "y_nghia": "Độ dài bản handoff sau compact, tính bằng dòng, không phải token. Không set 150000 ở đây."
+      },
+      "tat_auto_compact_codex": {
+        "field": "compact.codexContext.autoCompact",
+        "mac_dinh": true,
+        "y_nghia": "Chỉ set false khi đang debug hành vi compact của UKit."
+      }
+    },
+    "version": "Phiên bản config runtime đi kèm package UKit.",
+    "agent": "Adapter mặc định của workspace. Thường giữ nguyên theo lúc install.",
+    "compact": {
+      "enabled": "Bật/tắt toàn bộ helper compact của UKit.",
+      "tokenThreshold": "Ngưỡng token chung cho runtime compact dùng chung.",
+      "contextRotDetection": "Phát hiện context quá dài/dễ mục để giữ lại state quan trọng trước khi AI nhớ sai.",
+      "askBeforeDrop": "Giữ thái độ thận trọng trước khi bỏ context quan trọng. Nếu rủi ro thì hand back cho main model.",
+      "agentContext": {
+        "enabled": "Bật policy compact context theo từng agent.",
+        "decisionAgent": "Agent nội bộ hỗ trợ quyết định compact/handoff trong trường hợp an toàn.",
+        "executionMode": "sidecar-parallel nghĩa là lane quyết định compact chạy song song với task chính.",
+        "mustNotBlockMainTask": "Nếu true, sidecar nội bộ không được dừng/thay thế/làm chậm task chính của user.",
+        "targets": {
+          "claude": {
+            "autoCompact": "Giữ compact lane của Claude bật.",
+            "mode": "precompact-reinject nghĩa là Claude được bơm context quan trọng trước/sau compact.",
+            "preserveExistingHooks": "Nên giữ true để không gỡ PreCompact/reinject của Claude."
+          },
+          "opencode": {
+            "autoCompact": "Giữ compact lane của OpenCode bật.",
+            "mode": "native-auto-prune nghĩa là OpenCode dùng compaction.auto/prune native.",
+            "preserveExistingCompaction": "Nên giữ true để không gỡ compact native của OpenCode."
+          },
+          "codex": {
+            "autoCompact": "Bật policy soft handoff compact cho Codex Desktop.",
+            "mode": "soft-handoff nghĩa là UKit tạo/dùng state tóm tắt, không can thiệp trực tiếp vào internals của app Codex.",
+            "compactTarget": "Độ dài bản handoff sau compact, tính bằng dòng.",
+            "compactTargetUnit": "Đơn vị của compactTarget. Nên giữ là lines.",
+            "compactTargetRecommendedRange": "Khoảng số dòng khuyến nghị cho bản handoff.",
+            "compactTargetMax": "Số dòng tối đa cho bản handoff, tránh lỡ tay set quá dài."
+          }
+        }
+      },
+      "codexContext": {
+        "enabled": "Bật policy soft context handoff cho Codex Desktop.",
+        "autoCompact": "Cho phép UKit tự quyết định compact/handoff khi context Codex dài.",
+        "budgetTokens": "Ngưỡng token context của Codex Desktop trước khi compact. Mặc định 100000 để cân bằng chất lượng và giảm lỗi capacity/connection. Có thể tăng 150000 nếu cần, nhưng không nên để quá dài.",
+        "compactTarget": "Độ dài bản handoff sau compact, tính bằng dòng, không phải token. Mặc định 150; nên 120-150; tối đa 170.",
+        "compactTargetUnit": "Đơn vị của compactTarget. Nên giữ là lines.",
+        "compactTargetRecommendedRange": "Khoảng số dòng khuyến nghị. Nên ở trong khoảng này nếu không có lý do đặc biệt.",
+        "compactTargetMax": "Số dòng tối đa cho bản handoff. Chặn trường hợp lỡ set 150000 dòng.",
+        "decisionAgent": "Agent nội bộ dùng cho quyết định compact an toàn.",
+        "mode": "soft-handoff nghĩa là UKit tóm tắt state để tiếp tục thay vì replay toàn bộ transcript.",
+        "preserve": "Những thứ bắt buộc phải giữ khi compact: mục tiêu, rule, file đang làm, quyết định, lỗi chưa xử lý, bằng chứng verify, bước tiếp theo."
+      }
+    },
+    "tokenPipeline": {
+      "inputCompression": "Nén/tái sử dụng input context khi an toàn.",
+      "outputCompression": "Tóm tắt output command ồn nhưng vẫn giữ recovery hint.",
+      "promptCache": "Dùng cache prompt/context compact để giảm lặp lại."
+    },
+    "router": {
+      "enabled": "Bật task routing nội bộ.",
+      "defaultModel": "Model hint cân bằng cho công việc bình thường. Adapter/provider có thể map khác.",
+      "advisorModel": "Model hint mạnh hơn cho planning/reasoning khó khi được bật.",
+      "advisorEnabled": "Cho phép advisor-style planning cho task phức tạp.",
+      "maxAdvisorCalls": "Giới hạn số lần gọi advisor để không lãng phí."
+    },
+    "memory": {
+      "enabled": "Bật memory local của UKit.",
+      "autoCapture": "Cho phép UKit lưu decision/rule bền vững khi an toàn.",
+      "progressiveRetrieval": "Lấy memory liên quan nhỏ trước, chỉ mở rộng khi cần.",
+      "maxInjectionTokens": "Số token memory tối đa được inject vào context.",
+      "archiveAfterDays": "Sau bao nhiêu ngày memory có thể được archive/compact.",
+      "maxSessions": "Số session memory gần đây giữ active.",
+      "redactSecrets": "Cố tránh lưu secret vào memory."
+    },
+    "validation": {
+      "enabled": "Bật kiểm tra output nhẹ.",
+      "autoRetry": "Cho phép retry an toàn một lần khi validation thấy lỗi rõ.",
+      "maxRetries": "Số lần retry tối đa.",
+      "confidenceThreshold": "Ngưỡng confidence tối thiểu trước khi báo thận trọng."
+    },
+    "subagents": {
+      "enabled": "Cho phép UKit dùng các lane subagent nội bộ khi hữu ích.",
+      "smallTaskModel": "Model sidecar nội bộ cho quyết định nhỏ/an toàn của UKit. Đổi key này nếu muốn đổi model nội bộ.",
+      "smallTaskAgent": "Tên agent nội bộ phụ trách quyết định nhỏ không block task chính.",
+      "smallTaskUseCases": "Các loại việc an toàn sidecar có thể xử lý: dọn task, compact decision, phân loại, triage, queue maintenance, workspace maintenance.",
+      "keepMainModelFor": "Các việc rủi ro phải giữ ở main model: security, code risky, release, data-loss, architecture, deep reasoning.",
+      "decisionPolicy": {
+        "nonBlocking": "Sidecar nội bộ không được block task chính của user.",
+        "endUserInvisible": "Không biến orchestration nội bộ thành thứ end user phải học.",
+        "handBackOnRisk": "Nếu sidecar thấy rủi ro thì trả lại main model quyết định.",
+        "executionMode": "sidecar-parallel nghĩa là việc nội bộ có thể chạy riêng/song song với task chính.",
+        "mustNotBlockMainTask": "True nghĩa là sidecar không được dừng/thay thế/làm chậm task chính.",
+        "maxSidecarWaitMs": "0 nghĩa là không chờ sidecar trước khi tiếp tục task chính.",
+        "optimizeOrder": "Thứ tự ưu tiên khi ra quyết định nội bộ.",
+        "decisions": "Nhóm quyết định sidecar được phép hỗ trợ.",
+        "stepBudgets": "Gợi ý số bước planning tối đa theo độ lớn task trước khi reassess."
+      }
+    }
   }
 }

package/templates/.claude/ukit/.env.example

@@ -1,17 +0,0 @@
-# UKit optional local runtime overrides.
-# Copy to .claude/ukit/.env only if you need machine-local overrides.
-# This is internal orchestration config; normal teammates still only need `ukit install`.
-
-# Lightweight model for the internal UKit small-task maintainer subagent.
-# Used for safe UKit decisions such as task cleanup, compact decisions,
-# doc summarization, classification, auto-triage, and queue maintenance.
-# It follows UKit CoDev principles: quality > speed > token savings.
-# Risky/shared/security/release/data-loss/architecture work must keep the main model.
-UKIT_SMALL_TASK_MODEL=unic-lite
-
-# Codex Desktop soft auto-compact handoff budget.
-# Target is compact handoff length (lines), not full app context tokens.
-# 120-150 is preferred; 170 lines is the hard max for this lane.
-UKIT_CODEX_AUTO_COMPACT=true
-UKIT_CODEX_CONTEXT_BUDGET=60000
-UKIT_CODEX_COMPACT_TARGET=150