@ngockhoale/ukit 1.1.6

package/CHANGELOG.md

@@ -0,0 +1,179 @@
+# Changelog
+
+All notable changes to UKit are documented here.
+
+## Unreleased
+
+## 1.1.6 - 2026-04-23
+
+### Hidden Runtime Root
+
+- Moved the shared runtime install target from visible `ukit/` to hidden `.ukit/` so end-user projects no longer see a confusing extra root folder beside `.claude/ukit/`.
+- Kept `.claude/ukit/` for installed helper/index/hook machinery and installer metadata, instead of mixing mutable runtime storage into that helper tree.
+- Added safe reinstall migration so rerunning `ukit install` moves legacy runtime assets from `ukit/README.md` and `ukit/storage/` into `.ukit/` when the new target paths are free, without force-overwriting newer state.
+- Preserved conservative legacy cleanup: unknown user files under old `ukit/` still survive, and the old root is removed only when it becomes empty after migration/cleanup.
+- Updated manifest targets, gitignore/uninstall ownership handling, current docs, and release/package smoke expectations to align on the new hidden runtime root.
+- Promoted the current runtime/version surfaces to `@ngockhoale/ukit@1.1.6` while keeping the same `ukit` binary and the same install-first teammate workflow.
+
+## 1.1.5 - 2026-04-23
+
+### Owned-Scope npm Distribution Alignment
+
+- Realigned the published npm package name from `@ukit/cli` to `@ngockhoale/ukit` so release distribution uses a maintainer-owned scope that can actually publish today.
+- Kept the installed CLI binary name as `ukit`, so the human-facing workflow inside projects remains exactly the same: teammates still only need `ukit install`.
+- Preserved the existing GitHub `v1.1.4` release history and cut the package-identity change as a clean follow-up patch release instead of rewriting an already-pushed tag.
+- Updated current install/documentation surfaces to point maintainers at `npm install -g @ngockhoale/ukit` while keeping UKit’s install-first product contract unchanged.
+
+## 1.1.4 - 2026-04-23
+
+### Recovery-Safe Output Compaction
+
+- Added recovery-safe output compaction on top of the existing command-aware compression lane instead of introducing a second output/history subsystem.
+- Preserved raw tool output in `ukit/storage/cache/tee/` for high-value recovery cases such as failed commands, large raw outputs, or unusually high token savings.
+- Extended output-history entries with recovery metadata (`rawSaved`, `rawPath`, `rawBytes`, `recoveryReason`) so routed/runtime consumers can reuse the same shared artifact instead of rerunning noisy commands blindly.
+- Appended a compact `Full output:` recovery hint only when it still preserves net token savings; when it would erase the savings, UKit still keeps the raw artifact and metadata without bloating the inline summary.
+- Kept source runtime behavior and shipped Claude hook behavior aligned for recovery-safe compaction, including prompt-cache reuse of recovery metadata and history dedupe that ignores the recovery-hint line.
+- Extended `ukit status` output-compression reporting to show recovery counts so maintainers can see when the runtime preserved raw evidence in addition to saving tokens.
+- Updated shared runtime docs/version surfaces to reflect the new v1.1.4 recovery-safe compaction lane while keeping the teammate workflow centered on `ukit install`.
+
+## 1.1.3 - 2026-04-22
+
+### Vietnamese-friendly retrieval + routing hardening
+
+- Added shared Unicode-aware query normalization so Vietnamese prompts can match English-heavy code paths and symbols more reliably without forcing users to switch to English.
+- Added compact Vietnamese alias expansion for routing/search intent (for example review/auth/permission/cache/route-style terms) in both source runtime and shipped installed helpers.
+- Hardened shared route scoring so normalized prompt signals improve skill selection without leaking prompt aliases into unrelated file-signal matches.
+- Kept installed Claude/Codex hook/helper behavior aligned with the source runtime, including safe fallback behavior for hook/template test environments and legacy route-task stubs.
+- Added regression coverage for Vietnamese retrieval/routing across source query/index, source task routing, installed route-task/query helpers, and the Claude skill-router hook.
+- Added a simple direct-target fast path in shared `resolveContext` so when direct test context already localizes a simple/trivial change, UKit keeps the context bundle compact and skips widening into shared abstractions/analogs unless broader evidence is still needed.
+- Skipped previous-context memory injection for localized simple/trivial route lanes with an explicit file target in both the installed `route-task` helper and the Claude `skill-router` hook, reducing unnecessary memory scanning on already-localized tasks while keeping non-trivial routes unchanged.
+- Skipped recent-output snapshot reads for localized simple/trivial direct-target testing lanes in the installed `route-task` helper, so test-focused routes stop reading `ukit/storage/cache/output-history.json` when that compressed terminal context would not change the chosen next step.
+- Reused the installed `route-task` verification environment snapshot when `package.json` already declares `packageManager`, so UKit no longer re-reads `package.json` or stats every lockfile candidate just to derive the same verification commands.
+- Aligned the source verification planner and shipped `verify-context` helper with that same declared-`packageManager` fast path, so direct verification lanes also skip redundant lockfile fingerprint probes while reusing the parsed `package.json` snapshot.
+- Applied the same declared-`packageManager` fingerprint fast path to the Claude `skill-router` hook and reused the parsed package snapshot for verification recommendations, removing another avoidable lockfile-probe burst from pure Claude flows.
+
+## 1.1.2 - 2026-04-22
+
+### Live compact + compress runtime slice
+
+- Added real `src/core/token/`, `src/core/compact/`, and `src/core/output/` runtime modules so compact/compress are no longer config-only switches.
+- Added a threshold-based compact pressure planner with soft/hard phases, hysteresis, cooldown reuse, and layered compact plans so long sessions can auto-compact near the configured context limit without flapping.
+- Threshold compact memory-bridge output now dedupes bulky `Previous context` snapshots into compact anchors such as active task, key decision, rule, and next step instead of replaying the same context blob twice.
+- `ukit memory recall` now uses live input compaction, prompt-cache reuse, and compaction-history metrics.
+- Memory recall now tightens its own budget under compact pressure, preserving project anchors and key decisions while dropping lower-value extras when the runtime is already under hard pressure.
+- Added a real Claude `PreCompact` runtime lane that re-injects compact routed context, previous shared memory context, and recent compressed command output from shared runtime cache.
+- Added a Claude `PostToolUse` Bash output-compression hook that compresses noisy terminal output into reusable summaries under `ukit/storage/cache/output-history.json`.
+- Added an automatic previous-context bridge in the installed `route-task` helper so Codex-routed flows can carry compact shared memory context in `.claude/ukit/skill-router-state.json` without relying on manual recall commands.
+- Added a compact recent-output bridge in the installed `route-task` helper so Codex-routed flows can carry the latest compressed terminal summary into `.claude/ukit/skill-router-state.json` and invalidate reuse when that output snapshot changes.
+- Added safe-zone terminal compression profiles for repeated search/file-list/tree/git output so UKit keeps anchor paths and test signals while dropping noisy repeated lines.
+- Claude reinject now reuses that compact shared `previousContext` snapshot before rescanning `ukit/storage/memory/`, cutting duplicate memory retrieval work across Codex/Claude continuation flows while keeping the same safety fallback.
+- Claude `skill-router` now persists compact shared `previousContext` snapshots earlier in `.claude/ukit/skill-router-state.json` and invalidates same-prompt reuse when that memory snapshot changes, so pure Claude flows also benefit from lower repeated memory drag before `PreCompact`.
+- Updated shared adapter guidance so OpenCode (`AGENTS.md`) and Antigravity (`.antigravity/rules/rules.md`) reuse compact `previous-context` / `recent-output` snapshots from the shared route state before widening reads or replaying noisy logs.
+- OpenCode and Antigravity guidance now also points both adapters at the canonical `node .claude/ukit/index/route-task.mjs ...` helper for complex/ambiguous routing so they can refresh the same shared route memory path Codex/Claude already use.
+- OpenCode now ships native `opencode.json` command entrypoints for shared UKit route/context/index/query/verify/triage flows, pins `--adapter opencode`, and keeps those helpers internal so end users still only need `ukit install`.
+- Shared `route-task` state now records the originating adapter (`claude`, `codex`, `antigravity`, `opencode`) so OpenCode/Claude continuations do not accidentally reuse the same cached route snapshot just because the task text matches.
+- Antigravity can now call its native symlinked helper path (`node .antigravity/ukit/index/route-task.mjs ...`) and route/resolve/triage using `.antigravity/ukit/index/...` lanes instead of falling back to Claude-shaped helper paths.
+- `verify-context` and maintainer `ukit index verify` output now compact repeated targeted test commands and verbose docs-only notes into shorter canonical display lines without changing verification policy.
+- Memory recall / previous-context snippets now use compact canonical `project=...` / `session=...` display lines so agents spend fewer tokens on repeated prose while keeping decisions, rules, actions, and next steps visible.
+- `ukit status` now surfaces prompt-cache and output-compression metrics so maintainers can see live savings instead of only static config toggles.
+- Maintainer `release:verify` now defaults to a local `npm pack --dry-run --json` packaging check instead of hitting npmjs during the normal release-ready workflow.
+
+## 1.1.0 - 2026-04-21
+
+### Production-ready v1.1.0 runtime foundation
+
+- Promoted UKit to **v1.1.0** with a shared project-local runtime at `ukit/` for config, cache, and cross-agent memory.
+- Added maintainer-facing runtime commands:
+  - `ukit status`
+  - `ukit memory list|search|recall|forget|export`
+- Hardened lifecycle commands around the new runtime:
+  - `ukit doctor` now validates `ukit/storage/` health and runtime config integrity
+  - uninstall now removes tracked runtime config/cache files under `ukit/` safely
+- Updated installed Claude/Codex/AGENTS guidance so adapters know to reuse `ukit/storage/config.json`, `ukit/storage/memory/`, and the shared runtime cache files.
+- Added a safe recall lane for non-trivial work: `ukit memory recall "<task>"` now prints a compact `## Previous Context` block from shared local memory before widening docs/context.
+- Hardened recall before release so it stays inside the current project boundary and fails closed when `ukit/storage/config.json` is corrupted.
+- Fixed publish packaging so the OpenCode adapter preset is included in the npm artifact even though `opencode.json` is globally gitignored in the repo.
+
+## 1.0.1 - 2026-04-21
+
+### Patch release
+
+- Added **OpenCode** as a first-class optional coding adapter in the default `ukit install` surface.
+- Kept the human workflow unchanged: teammates still only need to remember **`ukit install`**.
+- Reused the canonical `AGENTS.md` + `.claude/skills/` workspace shape for OpenCode instead of generating a duplicate mirror tree, keeping the adapter leaner for production.
+- Added a production-tuned managed `opencode.json` with:
+  - safe default build agent behavior
+  - compaction enabled
+  - noisy watcher paths ignored
+  - index/test/lint/build commands auto-allowed where safe
+  - destructive git/rm flows denied or forced through confirmation
+- Extended adapter selection, gitignore management, uninstall ownership handling, docs, and integration coverage for the new OpenCode adapter.
+- Re-verified the release lane after the patch with artifact smoke, full core suite, and `npm publish --dry-run`.
+
+## 1.0.0 - 2026-04-16
+
+### Product promise
+
+- Teammates should remember only **`ukit install`** for normal in-project workflow.
+- The same command handles first-time workspace setup and refresh inside a project.
+- The AI should absorb the complexity: routing, hidden skill activation, context pulling, verification scope, and selective delegation.
+
+### Core capabilities
+
+- **Index-first code localization** so Claude Code, Codex, and Antigravity can find the right files/tests quickly without broad repo reads.
+- **Automatic skill routing** from prompt + file/tool evidence, including hidden lanes such as Docker packaging and DuraOne.
+- **Scoped verification** that prefers related tests and only widens when shared/risky scope justifies it.
+- **Shared multi-adapter workspace** authored once and reused across Claude, Codex, and Antigravity.
+
+### Release hardening
+
+- Made index freshness **source-aware**, not just age-based:
+  - stale detection now rebuilds when indexed source/style files changed immediately after the last build
+  - symlinked source directories are deduplicated to avoid duplicate/cyclic indexing
+  - shipped helpers/mirror follow the same freshness rule after **`ukit install`**
+- Broadened hidden index test handling for co-located `.test.mjs`, `.spec.mjs`, `.test.cjs`, and `.spec.cjs`, and kept likely test files out of normal query top matches unless the prompt explicitly asks for tests/specs.
+- Tightened the Claude auto-allow hook so interpreter entrypoints (`node`, `python`, `bash`, etc.) are not silently whitelisted as generic safe Bash rules.
+- Removed empty `frontend-vue` placeholder components from the shipped hidden skill bundle by replacing them with real reference wrappers for mobile dropdown and form-view usage.
+- Cut one extra stale-path freshness reread from shipped index helpers by returning `generatedAtMs` directly from index rebuild summaries and reusing it after rebuild.
+- Added packed-artifact smoke coverage proving the published npm tarball can:
+  - run `ukit install`
+  - ship working index helpers
+  - build the shipped index
+  - route Docker packaging work
+  - support default adapters
+  - support nested DuraOne monorepo activation
+- Fixed index graph resolution for extensionless React-style internal imports (`.jsx`, `.tsx`, and directory `index.jsx` / `index.tsx`) so rerunning **`ukit install`** rebuilds correct relations/analogs in JSX/TSX projects too.
+- Fixed source discovery for supported **symlinked source files** in both the repo runtime and the shipped installed mirror, so alias file paths inside the project remain indexed/searchable even when the real file lives elsewhere.
+- Stopped `ukit install` from claiming success before the required source-code index actually finishes; if index build fails, the command now tells maintainers to fix the repo state and rerun **`ukit install`**.
+- Slimmed the bundled hidden `canvas-design` asset lane to a curated built-in font set, cutting the published tarball from roughly **3.3 MB** to **1.5 MB** while preserving immediate post-install usability and the one-command `ukit install` workflow.
+- Deduped the heavy hidden **OOXML** support bundle used by PPTX/DOCX into a shared installed lane, preserving the same skill paths after `ukit install` via symlinks and safely migrating previously managed real directories on reinstall.
+- Hardened uninstall against stale tracked metadata under managed symlink roots: if old install records still mention descendants like `.claude/skills/pptx/ooxml/...` after the root became a tracked link, uninstall now removes only the tracked link and refuses to follow that symlink into the shared target bundle.
+- Hardened reinstall migration for shared OOXML symlink targets so UKit only auto-replaces an old real directory when every nested path is still clearly UKit-managed; untracked empty subdirectories now block replacement instead of being silently deleted.
+- Hardened reinstall migration again so even an **empty real directory** at a managed symlink target is treated as ambiguous user content; UKit now warns and keeps the directory instead of silently replacing it during `ukit install`.
+- Hardened legacy reinstall cleanup so `ukit install` no longer deletes the whole old `ukit/.ukit/` directory tree; it now removes only the legacy `install.json` file and keeps any user files that may still live under that folder.
+- Hardened legacy flat-file cleanup so paths like `.claude/skills/delivery.md` are removed only when they are actual files/symlinks; if a user has a real directory with the same legacy name, UKit now preserves it instead of recursively deleting it.
+- Hardened adapter deselection metadata cleanup so removing a managed link path also removes stale tracked descendants under that path, preventing old `.antigravity/skills/...` or `.codex/skills/...` entries from lingering in install metadata after `ukit install --tools=...` changes.
+- Hardened maintainer preview flows so `ukit diff` / dry-run install planning no longer delete a previously managed real directory before showing the preview; only the real install path may perform safe managed-directory replacement.
+- Fixed index import resolution for **single-segment `baseUrl` imports** (for example `import { loadUser } from 'userApi'` with `baseUrl: "./src/services"`), in both the source runtime and the shipped installed mirror, so source-code indexing keeps relations/query ranking correct for that TypeScript layout too.
+- Hardened adapter deselection safety again so UKit only prunes deselected adapter files when install metadata proves UKit actually owns them; a first `ukit install` no longer deletes a teammate’s pre-existing `.codex/.antigravity` files just because the adapter is currently deselected.
+- Tightened deselection ownership handling so when adapter cleanup is skipped (non-interactive mode, user says no, or the path is a real directory), UKit immediately drops those deselected paths from install metadata instead of carrying stale ownership forward to uninstall.
+- Restored **index-first routing** for prompt-only hybrid lanes where a standalone specialist (for example Docker packaging) is selected together with a real code skill; source runtime, shipped `route-task`, and the Claude `skill-router` hook now keep `resolve-context` available instead of falling straight to `read-skill-instructions`.
+- Hardened fresh `ukit install` ownership handling against stray/non-UKit `install.json` files: obsolete-path pruning and metadata carry-forward now trust previous tracked files only when metadata proves the prior install was actually written by UKit, so a first install no longer deletes or inherits ownership of user files from foreign/stale metadata.
+- Stopped tracking **skip-strategy bootstrap files** (for example `docs/PROJECT.md`, `docs/MEMORY.md`, `docs/WORKLOG.md`, `CLAUDE.md`, `AGENTS.md`, `.claude/settings.local.json`, `.codex/settings.local.json`) as uninstall-owned outputs, so UKit preserves team memory/local settings even when those files were first created by `ukit install`.
+- Kept **test-like direct targets** targeted even when filenames omit `.test` / `.spec` (for example `tests/pages/LoginFlow.js`): source verification planning and shipped `resolve-context` / `verify-context` helpers now treat `tests/` / `specs/` targets as related tests instead of downgrading to minimal verification.
+- Hardened source `deriveVerificationPlan(...)` again so callers that pass a precomputed/raw `contextResult` still normalize direct `tests/` / `specs/` primary targets into targeted verification; direct test files no longer fall back to `mode=minimal` just because `relatedTests` was not pre-expanded upstream.
+- Fixed source + shipped index discovery so root-level **`specs/` / `spec/` / `test/` / `__tests__/`** lanes are scanned and treated consistently as likely tests; spec-root tests now feed `tests-map` / relations correctly and stay deprioritized in normal file search unless the prompt explicitly asks for tests/specs.
+- Completed the root test-lane hardening so **root `test/`, `spec/`, and `__tests__/`** paths are recognized consistently across index build, query ranking, and direct test-target routing/verification heuristics in both source and shipped helpers.
+- Aligned shipped helper cache keys with route-task seeding for **target-only helper invocations** (`--target ...` with no prompt text), so direct `resolve-context` / `verify-context` calls can reuse the route-seeded cache instead of recomputing indexed context.
+- Reused relations/analogs safely for alias-based projects when code + alias config stay unchanged, reducing wasted rebuild work on repeated refreshes.
+- Fixed package file modes so published regular files are readable and shipped hook/bin entrypoints stay executable in the npm artifact.
+- Installed full hidden-skill companion bundles (references/scripts/assets) for default skill packs that need them, while keeping the teammate workflow unchanged: remember only **`ukit install`**.
+- Cleared stale routed state when a later prompt has no matching skill, preventing old verification policies from leaking into unrelated work.
+- Expanded explicit “full suite” verification intent detection so Vietnamese prompts like `chạy full test suite` are honored too.
+- Hardened packaging for release-critical templates and adapter presets so publish artifacts match repo behavior.
+- Added maintainer-facing production release checklist and completed the missing npm/GitHub release metadata.
+
+### Migration notes
+
+- The old legacy delegation stack is **not** part of the UKit 1.0.0 product surface.
+- If you are upgrading an older workspace, rerun **`ukit install`** to refresh the installed files and hidden routing logic.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 lengockhoa
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,189 @@
+# UKit
+
+UKit installs a project-local AI workspace (`.claude/`, adapters, docs, and index helpers) so your team can work with Claude Code, Antigravity, OpenAI Codex, and OpenCode from the same repo setup.
+
+## Highest-Priority Team Rule
+
+**For normal team usage, the only UKit command anyone should need to remember is `ukit install`.**
+
+After `ukit install` finishes:
+- open your AI tool
+- describe the task in natural language
+- let the workspace instructions route the flow
+
+How the CLI binary itself gets installed or refreshed is a maintainer/platform concern.
+Inside projects, the command teammates should remember remains **`ukit install`**.
+
+Do **not** onboard the whole team around `ukit doctor`, `ukit diff`, `ukit uninstall`, or `ukit index ...`. Those commands can still exist for maintainers/debugging, but they are intentionally **not** the default human workflow.
+
+## Team Workflow
+
+1. Install the UKit CLI globally.
+   ```bash
+   npm install -g @ngockhoale/ukit
+   ```
+2. Open any project root in the terminal.
+3. Run:
+
+```bash
+ukit install
+```
+
+4. Fill in the generated docs baseline:
+   - `docs/PROJECT.md`
+   - `docs/MEMORY.md`
+   - `docs/WORKLOG.md`
+5. Open your AI tool and work in natural language.
+
+## Update Policy
+
+The same command handles both first-time setup and refreshes:
+
+```bash
+ukit install
+```
+
+If UKit changes, your templates change, or a teammate needs to re-apply the workspace, rerun `ukit install`.
+If maintainers roll out a newer CLI build, the in-project workflow still stays the same: rerun `ukit install`.
+
+## What `ukit install` Creates
+
+**Core workspace**
+- `.claude/skills/` — canonical skills
+- `.claude/agents/` — specialist agents
+- `.claude/hooks/` — tool hooks
+- `CLAUDE.md` — Claude Code instructions
+- `AGENTS.md` — shared instructions for AGENTS-compatible tools
+
+**Adapters**
+- `.antigravity/skills/` → symlink to `.claude/skills/`
+- `.antigravity/rules/` — Antigravity rules
+- `.codex/settings.json` + `.codex/settings.local.json` — Codex config
+- `opencode.json` — OpenCode project config with UKit-safe guardrails
+
+**Project support files**
+- `.claude/ukit/.ukit/` — installer manifests, metadata, backups
+- `.ukit/` — hidden shared runtime storage for config, cache, and cross-agent memory
+- `docs/` — PROJECT / MEMORY / WORKLOG baseline
+
+## UKit v1.1.6 Runtime
+
+UKit now installs a hidden shared local runtime at `.ukit/` for production-oriented state that should survive across agent sessions:
+
+- `.ukit/storage/config.json` — runtime defaults for compact/router/memory/validation
+- `.ukit/storage/cache/` — reusable prompt-cache, compact history, compact-pressure state, and output summaries
+- `.ukit/storage/memory/` — cross-agent local memory
+
+If an older repo still has a visible legacy `ukit/` runtime folder, rerunning `ukit install` now migrates the shared runtime into hidden `.ukit/` when the target paths are free.
+
+When long sessions approach the compact threshold, UKit now uses a conservative pressure lane:
+
+- soft threshold = configured compact token threshold
+- hard threshold = roughly 20% above soft
+- compact only safe-zone history/noise
+- preserve active task, rules, decisions, and current code focus
+
+UKit v1.1.6 keeps the same shared runtime contract while the npm distribution now lives under the owned maintainer scope:
+
+- install globally with `npm install -g @ngockhoale/ukit`
+- keep using the exact same human workflow inside projects: `ukit install`
+- preserve the same `ukit` binary, hooks, and install-first orchestration while standardizing the runtime root as hidden `.ukit/`
+
+UKit v1.1.6 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
+- routed verification lanes reuse declared `packageManager` metadata so helpers/hooks stop probing every lockfile candidate unnecessarily
+
+For maintainers, the runtime is inspectable with:
+
+- `ukit status`
+- `ukit memory list`
+- `ukit memory recall "<current task>"`
+- `ukit memory export`
+
+Normal teammates should still only need **`ukit install`**.
+
+## Installer Behavior
+
+- idempotent install (safe to rerun)
+- timestamped backups before overwrite
+- template rendering with project-aware variables
+- dependency-ordered manifest execution
+- path safety checks for template and target traversal
+- shared-skill adapter linking across supported tools
+- post-install docs baseline reminders
+- automatic code-index build + refresh hook install
+
+## Working Style After Install
+
+UKit is built so the team can stop memorizing UKit subcommands and focus on product work:
+- ask for fixes, reviews, implementations, tests, or docs in natural language
+- let the installed instructions choose the right workflow
+- let the AI use the indexed source code first so it can find the right files/tests fast
+- 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
+- rerun `ukit install` when you need to refresh the workspace
+
+End users should **not** need to know or memorize skill names.
+
+## Upstream Skill Alignment
+
+To keep UKit strong over time, maintainer work should track the current upstream skill ecosystem:
+- official Anthropic skills: [anthropics/skills](https://github.com/anthropics/skills)
+- official OpenAI skills: [openai/skills](https://github.com/openai/skills)
+- Agent Skills open standard: [agentskills.io](https://agentskills.io/)
+- curated discovery lists such as [awesome-claude-code](https://github.com/hesreallyhim/awesome-claude-code) and [awesome-agent-skills](https://github.com/VoltAgent/awesome-agent-skills)
+
+But this is a **maintainer concern**, not a team-onboarding burden.
+
+The rule remains:
+
+> ship curated improvements through UKit, then ask teammates to rerun **`ukit install`**
+
+Do **not** require normal contributors to learn marketplace/plugin commands just to use the workspace.
+
+## Maintainer / Debug Commands
+
+These commands are still available, but they are **advanced workflows**, not default team onboarding:
+
+- `ukit diff` — preview file changes before install
+- `ukit doctor` — validate UKit state and docs baseline
+- `ukit uninstall` — remove UKit-managed assets
+- `ukit status` — inspect shared UKit runtime state
+- `ukit memory ...` — inspect/export/forget shared memory items
+- `ukit index ...` — run repo indexing/query/triage tools directly
+- `ukit build index` — alias for `ukit index build`
+
+Use them when maintaining UKit, debugging workspace setup, or developing the CLI itself — not as the day-to-day path every teammate must learn.
+
+## Repo Development
+
+For maintainers evolving **UKit itself**, the key repo references live in:
+
+- `docs/UKIT_CODEV_PRINCIPLES.md`
+- `docs/RELEASE_1_1_3_SIGNOFF.md`
+
+Run the test suite from the UKit repo root:
+
+```bash
+yarn test
+```
+
+For deeper index development, repo-level scripts are available:
+- `yarn index:build`
+- `yarn index:refresh`
+- `yarn index:query -- "<error|symbol|path>"`
+- `yarn bug:triage -- "<error signature>"`
+
+## Tool Support
+
+| Tool | Instructions | Skills | Config |
+|------|-------------|--------|--------|
+| Claude Code | `CLAUDE.md` | `.claude/skills/` (canonical) | `.claude/settings.json` |
+| Antigravity | `AGENTS.md` | `.antigravity/skills/` (symlink) | `.antigravity/rules/`, `.antigravity/README.md` |
+| OpenAI Codex | `AGENTS.md` | `.claude/skills/` (referenced) | `.codex/settings.json`, `.codex/settings.local.json`, `.codex/README.md` |
+| OpenCode | `AGENTS.md` | `.claude/skills/` (native Claude-compatible support) | `opencode.json` |
+
+All supported tools share the same SKILL.md ecosystem so the workspace is authored once and reused everywhere.

package/bin/ukit

@@ -0,0 +1,30 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { runCli } from '../src/cli/index.js';
+
+async function readPackageVersion(packageRoot) {
+  const raw = await fs.readFile(path.join(packageRoot, 'package.json'), 'utf8');
+  const packageJson = JSON.parse(raw);
+  return packageJson.version;
+}
+
+async function main() {
+  const currentFile = fileURLToPath(import.meta.url);
+  const packageRoot = path.resolve(path.dirname(currentFile), '..');
+  const packageVersion = await readPackageVersion(packageRoot);
+
+  await runCli({
+    argv: process.argv.slice(2),
+    packageRoot,
+    projectRoot: process.cwd(),
+    packageVersion,
+  });
+}
+
+main().catch((error) => {
+  console.error(`[UKit] ${error?.message ?? String(error)}`);
+  process.exitCode = 1;
+});