@mcptoolshop/loadout-os 0.0.0 → 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog — @mcptoolshop/loadout-os
+
+All notable changes to the unified `loadout-os` CLI are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/),
+and this project adheres to [Semantic Versioning](https://semver.org/).
+
+> This is the published package's changelog. For the full monorepo consolidation
+> history (workspace wiring, the runtime hook, the adapters), see the
+> [root CHANGELOG](../../CHANGELOG.md).
+
+## [Unreleased]
+
+### Added
+
+- Unified `loadout-os` binary wrapping the kernel + memories + rules surfaces under one
+  arg parser and one structured `CliError { code, message, hint }` shape.
+- Namespaced adapter commands (`memories`, `rules`) and flat kernel verbs (`resolve`,
+  `explain`, `usage`, `dead`, `overlaps`, `budget`, `validate`).
+- Operational rituals: `doctor` (read-only health screen), `report` (read-only
+  observability), and `refresh` (Index Freshness Ritual with andon halt + `.bak`
+  compensator); plus `hook test`.
+- Per-command `--help` (synopsis, arguments, flags, example, exit codes) for every leaf
+  command.
+
+<!-- ## [1.0.0] - YYYY-MM-DD -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mcp-tool-shop
+
+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

@@ -1,5 +1,89 @@
 # @mcptoolshop/loadout-os
 
-Placeholder release. Real package coming soon.
+The unified **Knowledge OS** CLI. One `loadout-os` binary that wraps the three
+library packages of this workspace and absorbs the operational rituals that used
+to be a multi-step manual sequence.
 
-Source: <https://github.com/mcp-tool-shop-org/loadout-os>
+It wraps:
+
+- **kernel** — [`@mcptoolshop/ai-loadout`](../kernel) — the knowledge router (resolve / match / budget / usage analysis)
+- **memories** — [`@mcptoolshop/claude-memories`](../memories) — MEMORY.md → dispatch index
+- **rules** — [`@mcptoolshop/claude-rules`](../rules) — CLAUDE.md section analysis + rule-file linting
+- the **runtime hook** — [`apps/hook/loadout-hook.mjs`](../../apps/hook) — the `UserPromptSubmit` pointer-injector
+
+Every wrapped surface calls the library export directly (one process, one arg
+parser, one structured-error shape) — `loadout-os` does not shell out to the
+legacy `ai-loadout` / `claude-memories` / `claude-rules` bins.
+
+## Command tree
+
+### Namespaces (wrapped library surfaces)
+
+```
+loadout-os memories index    <MEMORY.md> [--lazy] [--json]
+loadout-os memories validate <MEMORY.md> [--json]
+loadout-os memories stats    <MEMORY.md> [--json]
+loadout-os memories health   [path] [--json]
+
+loadout-os rules analyze  <CLAUDE.md> [--rules-dir <dir>] [--json]
+loadout-os rules validate [--rules-dir <dir>] [--lazy] [--repo-root <dir>] [--json]
+loadout-os rules stats    <CLAUDE.md> [--rules-dir <dir>] [--json]
+loadout-os rules split    # interactive — wrapped via passthrough to the claude-rules bin
+```
+
+### Flat verbs (knowledge router / kernel)
+
+```
+loadout-os resolve                  # resolve layered loadouts (global → org → project → session)
+loadout-os explain <entry-id>       # how an entry resolved across layers
+loadout-os usage <jsonl>            # usage summary from the event log
+loadout-os dead <index> <jsonl>     # entries never loaded
+loadout-os overlaps <index>         # keyword routing ambiguities
+loadout-os budget <index> [jsonl]   # token budget breakdown
+loadout-os validate <index>         # validate index STRUCTURE (kernel)
+```
+
+> **Name collision, resolved by namespacing.** The flat `validate <index>` is the
+> kernel's index-structure validator. The store/rules linters are namespaced —
+> `memories validate <MEMORY.md>` and `rules validate` — so all three coexist.
+
+### Rituals
+
+```
+loadout-os doctor [--json]                    # read-only health screen
+loadout-os report [--index <p>] [--jsonl <p>] # observability over usage.jsonl
+loadout-os hook test [--prompt "<text>"]      # drive the runtime hook on a sample prompt
+loadout-os refresh [--store <d>] [--dest <p>] [--dry-run]   # index → validate → publish
+```
+
+- **`doctor`** — one read-only screen: store `MEMORY.md` validates, the global
+  index parses + validates, the runtime hook mirror matches the repo source (drift
+  check), no malformed resolver layers, at least one core entry, observability
+  loop wired, hook wired in `settings.json`, and `usage.jsonl` growing. `--json`
+  emits `{ checks: [{ id, status, message, hint }], ok }`. Exit 0 when all checks
+  pass or warn; exit 1 on any fail. **Never writes.**
+- **`report`** — composes usage summary + dead-entry detection + token budget,
+  plus a score distribution when usage events carry a `score`. `--json` for the
+  machine-readable shape. Exit 2 when an input is missing. **Read-only.**
+- **`hook test`** — runs the real `loadout-hook.mjs` against a sample prompt in an
+  isolated HOME so the live `usage.jsonl` is never written.
+- **`refresh`** — folds the Index Freshness Ritual into one command: regenerate the
+  store index → validate (andon halt on any error) → rewrite relative paths to
+  absolute + publish to `~/.ai-loadout/index.json`. The irreversible write is guarded
+  by a `.bak` named compensator (restored on failure, undo line printed); `--dry-run`
+  previews without writing. Exit `1` on validation/write failure, `2` on a missing store.
+
+## Build & test
+
+```
+npm run build    # tsc
+npm test         # node --test dist/tests/*.test.js
+npm run verify   # tsc --noEmit && node --test dist/tests/*.test.js
+```
+
+## SDK use
+
+Importing the package is side-effect-free — the dispatcher only runs when the
+file is the process entrypoint. Composable exports: `dispatch`, `runDoctor` /
+`buildReport` / `runHookTest` (and their `print*` renderers + `default*Paths`
+helpers).