@lorekit/cli 1.0.0

package/README.md

@@ -0,0 +1,320 @@
+# @lorekit/cli
+
+Install the **LoreKit shared-memory skill** into a project and run health
+checks against your LoreKit MCP server — a small, zero-dependency Node CLI.
+
+LoreKit gives coding agents a shared, persistent memory: lessons one agent
+learns are stored centrally and read by every other agent, in every session,
+CI included. This CLI wires an agent up to it in two commands.
+
+## Install
+
+```bash
+npx @lorekit/cli install
+npx @lorekit/cli doctor
+```
+
+Requires Node 18+ (for the built-in `fetch`). No dependencies.
+
+## Commands
+
+### `lorekit install`
+
+Scaffolds the `lorekit-memory` skill into `.claude/skills/lorekit-memory/` and
+adds (or updates) a `lorekit` server in the project's `.mcp.json`, preserving
+any other MCP servers already configured.
+
+```bash
+lorekit install \
+  --endpoint https://<project-ref>.supabase.co/functions/v1/mcp \
+  --token    lk_rw_your_token
+```
+
+If run in a TTY without `--endpoint` / `--token`, it prompts for them.
+Use `--yes` for non-interactive environments (endpoint required via flag/env).
+Use `--force` to overwrite an existing skill copy.
+
+### `lorekit doctor`
+
+Verifies the setup and prints a status report:
+
+- Node runtime is 18+
+- the `lorekit-memory` skill is installed
+- the **resolved memory mode and which source decided it**, plus any active
+  deny constraints
+- for `local`: the store path, entry count, and whether it is committed or
+  gitignored
+- for `remote`: `.mcp.json` has a `lorekit` server, the endpoint is real (not
+  the `<project-ref>` placeholder), the token and its permission tier
+  (`lk_rw_*` vs `lk_ro_*`), and that the endpoint is reachable
+- for `off`: a note that memory is disabled
+- the git-derived read/write scopes for the current directory
+
+```bash
+lorekit doctor            # config + connectivity checks
+lorekit doctor --deep     # also does a write → read → delete round-trip (needs lk_rw_*)
+```
+
+Exit code is non-zero if any check fails, so it fits CI gates.
+
+### `lorekit hook`
+
+The **shared hook engine** behind the Claude Code / Cursor / Codex plugins.
+It is not run by hand — the plugins wire it into their hook config. It reads
+the host framework's JSON on stdin and prints that host's injection format on
+stdout (lessons at session start; a nudge on failure or at end of turn),
+always exiting 0 so it can never block the host agent.
+
+```bash
+lorekit hook --adapter <claude|cursor|codex> --event <SessionStart|Stop|…>
+```
+
+One engine serves all three hosts; each `--adapter` only reshapes input/output
+to that host's contract. See [`plugins/`](../../plugins/) for the bundles.
+
+### `lorekit mcp`
+
+A **local stdio MCP server**. It exposes LoreKit's `memory.*` tools backed by
+the store the [control model](#memory-modes--the-control-model) resolves, so an
+agent's `.mcp.json` can point at the CLI instead of `mcp-remote <url>` — giving
+the model discoverable, autonomous `memory.*` tool calls **offline against the
+local `.lorekit/` store** (no network, Bash-restricted contexts included).
+
+```bash
+lorekit mcp                 # serve on stdin/stdout using the resolved mode
+lorekit mcp --mode local --store .lorekit
+```
+
+It speaks JSON-RPC 2.0 over newline-delimited stdin/stdout (the MCP stdio
+transport, hand-rolled — zero dependencies) and is **not run by hand**: only
+JSON-RPC frames reach stdout. It serves whatever mode resolves — `local` serves
+the `.lorekit/` files directly, `remote` passes calls through to the hosted
+endpoint, and `off` advertises no tools. Tools advertised: `memory.write`,
+`memory.read`, `memory.list`, `memory.search`, `memory.delete`,
+`memory.archive`.
+
+Wire it into `.mcp.json` as an alternative to the `mcp-remote <url>` transport —
+this variant needs no endpoint or token for local mode:
+
+```jsonc
+{
+  "mcpServers": {
+    "lorekit": {
+      "command": "npx",
+      "args": ["-y", "@lorekit/cli", "mcp"]
+    }
+  }
+}
+```
+
+## Memory modes & the control model
+
+Memory has a controllable backend. Three **modes**:
+
+| Mode | Where lessons live | Notes |
+|------|--------------------|-------|
+| `off` | nowhere | Memory is disabled — every hook event and store op is a silent no-op. |
+| `local` | markdown files in two tiers (see below) | **Local means _not_ on the hosted website** — local lessons never sync to the LoreKit dashboard. That is the point of local: private-by-default, greppable, git-native. |
+| `remote` | the LoreKit MCP server (hosted) | The shared, cross-machine backend. Reads stay silent until an endpoint + token are configured. This is the default. |
+
+### Local store layout — two tiers
+
+Local mode mirrors the two-tier model used by the `aw` / persistent-memory
+loops: a per-user **home** tier plus an opt-in per-repo **project** tier.
+
+| Tier | Path | Availability |
+|------|------|--------------|
+| **home** | `~/.lorekit/` (override with `LOREKIT_HOME`) | Always available — per-user, cross-repo. |
+| **project** | `<repo>/.lorekit/` (override with `LOREKIT_STORE`) | **Opt-in:** active only when the directory exists. Create it once to start persisting repo/branch lessons in the project. |
+
+Each tier is foldered by canonical scope, one markdown file per lesson, with
+YAML frontmatter (`scope, key, tags, source_agent, trigger, created, updated,
+archived_at`) and the lesson as the body:
+
+```
+~/.lorekit/            <repo>/.lorekit/     (opt-in)
+├── config.json        ├── global/
+├── global/            ├── repo/<owner>/<repo>/
+├── repo/<o>/<r>/      └── branch/<owner>/<repo>/<branch>/
+└── branch/<o>/<r>/…       └── <slug-of-key>.md
+```
+
+**Read = two-tier merge.** For each scope in the read order, entries from both
+tiers are unioned and the **project tier wins on a key collision** (closer scope
+wins), consistent with the remote narrow→broad merge.
+
+**Write routing by scope:**
+
+- `global` → **home** tier.
+- `repo::` / `branch::` → **project** tier when it exists (opted-in), else the
+  **home** tier.
+
+To start persisting repo/branch lessons in the project, create
+`<repo>/.lorekit/` (or run `lorekit migrate --to project --yes`). Commit it to
+share lessons with your team (git-native sharing); add it to `.gitignore` to
+keep them private to your checkout.
+
+**Delete / archive across tiers.** Deleting or archiving a key removes the
+closest (project) copy first; a broader **home** copy, if any, remains and takes
+a second delete. This is deliberate — one `delete` never reaches through and
+erases your cross-repo home lesson.
+
+> **Same tiering, two realizations (local ⟷ remote).** The tiered, closer-wins
+> merge-read is identical in both backends. Local expresses "universal vs
+> team-shared" as two physical **locations** (home dir vs committed project
+> dir); remote expresses the same distinction through the canonical **scopes**
+> in one shared DB (`global` ≈ your cross-repo home, `repo::` ≈ team-shared) —
+> sharing comes from the account/token, so remote needs no second location.
+> Different mechanism, same concept.
+
+### `lorekit migrate` — relocation / rename tool
+
+Moved or renamed a local store (e.g. an old `.lore/`)? `migrate` re-writes its
+entries into the current two-tier layout so lessons are never stranded:
+
+```bash
+lorekit migrate --from .lore              # dry-run: preview counts per scope
+lorekit migrate --from .lore --yes        # apply, routing each entry by scope
+lorekit migrate --from .lore --to project --yes   # force all entries into the project tier
+```
+
+Dry-run (preview) by default; `--yes` (or `--apply`) applies. Idempotent — a
+re-run is a no-op. It reads LoreKit's own on-disk format only (it does **not**
+import persistent-memory's `~/.agent-memory/<bucket>/` format).
+
+### The control model — two layers, deny-wins
+
+Two config layers decide the mode:
+
+- **User / machine** — env `LOREKIT_MODE`, `LOREKIT_HOME`, `LOREKIT_STORE`,
+  `LOREKIT_DENY` (and `LOREKIT_MCP_URL` / `LOREKIT_TOKEN` for remote), plus a
+  user config file `~/.lorekit/config.json`.
+- **Repo / team** — a `.lorekit.json` at the repo root (and/or the existing
+  `lorekit` block in `.mcp.json` for the connection).
+
+Both files share one schema:
+
+```jsonc
+{
+  "mode": "local",        // select a mode (off | local | remote)
+  "store": ".lorekit",    // project-tier store dir (relative to repo root, or absolute)
+  "deny": ["remote"]      // forbid modes outright — deny always wins
+}
+```
+
+**Precedence (a _selection_ within what is allowed):**
+`env LOREKIT_MODE` → user config `mode` → repo config `mode` → built-in default
+(`remote`).
+
+**Constraints (`deny`) always win.** Denies are a **union** across every source
+and only ever accumulate — a user-level hard opt-out is a **ceiling the repo
+cannot override**:
+
+- A user who declares `"deny": ["remote"]` (privacy / compliance) can never be
+  flipped to remote by any repo default or env flag — they resolve to `local`
+  (if they selected it) or `off`, never `remote`.
+- A repo or CI job that declares `"deny": ["local"]` (no `.lorekit/` in the tree)
+  makes local unselectable there — an env `LOREKIT_MODE=local` is capped, and
+  resolution falls through to `remote`, or `off` if both are denied.
+
+`off` is never deniable, so it is always the terminal fallback. Run
+`lorekit doctor` to see the resolved mode, **which source decided it**, and any
+active deny constraints.
+
+## Options
+
+| Flag | Meaning |
+|------|---------|
+| `-d, --dir <path>` | Target project root (default: cwd) |
+| `-e, --endpoint <url>` | LoreKit MCP endpoint |
+| `-t, --token <token>` | LoreKit token |
+| `--mode <mode>` | Memory mode override for `doctor`: `off` / `local` / `remote` |
+| `--store <path>` | Local project-tier store directory (default `.lorekit`) |
+| `--from <path>` | Source store to migrate from (`migrate`) |
+| `--to <tier>` | Migration destination tier: `home` / `project` (`migrate`; default routes by scope) |
+| `--apply` | Apply the migration — alias of `--yes` (`migrate`) |
+| `-y, --yes` | Non-interactive / apply; never prompt |
+| `--force` | Overwrite existing skill files (`install`) |
+| `--deep` | Write/read/delete round-trip (`doctor`) |
+| `--adapter <name>` | Host framework for `hook`: `claude` / `cursor` / `codex` |
+| `--event <name>` | Host hook event for `hook` (else read from the stdin payload) |
+| `-h, --help` | Help |
+| `-v, --version` | Version |
+
+## Environment variables
+
+| Variable | Purpose |
+|----------|---------|
+| `LOREKIT_MODE` | select a mode: `off` / `local` / `remote` |
+| `LOREKIT_DENY` | comma-separated modes to forbid (deny-wins); e.g. `remote` |
+| `LOREKIT_HOME` | home-tier root + config directory (default `~/.lorekit`) |
+| `LOREKIT_STORE` | project-tier store directory (default `.lorekit`) |
+| `LOREKIT_MCP_URL` / `LOREKIT_ENDPOINT` | endpoint fallback |
+| `LOREKIT_TOKEN` | token fallback |
+| `NO_COLOR` | disable colored output |
+
+## What the skill does
+
+The installed `lorekit-memory` skill teaches an agent to:
+
+- **Read** scoped lessons at the start of a task, on first navigation into
+  unfamiliar code, and before risky operations (narrow-to-broad scope merge).
+- **Write** a lesson when something goes wrong — a stuck loop, a repeated
+  failure, a gotcha, a near-miss, or a costly wrong assumption — phrased as an
+  observation and scoped to the narrowest namespace that fits.
+
+This mirrors the read-on-start / write-on-failure loop of the `aw`
+autonomous-workflow agent. See the skill's own `SKILL.md` for the full
+protocol.
+
+The **skill** is model-invoked (the agent chooses to use it). For a
+**deterministic** guarantee — lessons injected on every session start, a nudge
+on every tool failure — use the framework plugins in [`plugins/`](../../plugins/),
+which fire the `lorekit hook` engine on host lifecycle events. The skill and
+the hooks compose: hooks guarantee the *timing*, the skill supplies the
+*authoring judgment*.
+
+## Testing & validating across frameworks
+
+`npm test` (or `node --test test/*.test.mjs`) runs four layers, so you can
+validate all three integrations without launching each agent by hand:
+
+1. **Unit** — scope parsing, failure heuristic, lesson formatting, adapter
+   mapping/emit.
+2. **Engine end-to-end** — spawns the real `lorekit hook` binary for every
+   adapter/event, including a mock MCP server that proves the `SessionStart`
+   read path injects lessons, plus throttling and bad-input handling.
+3. **Cross-framework conformance** — replays payload **fixtures** through the
+   binary and asserts the stdout matches each host's documented contract
+   (`hookSpecificOutput.additionalContext` for Claude/Codex, `followup_message`
+   for Cursor).
+4. **Wiring** — runs `claude plugin validate` on the Claude bundle (skipped if
+   the `claude` CLI is absent) and structurally validates the Cursor and Codex
+   configs; also asserts the vendored skill is in sync with its source.
+
+### Harvesting real fixtures (one run per framework)
+
+Layer 3 ships with documented seed fixtures under `test/fixtures/`. To prove
+conformance against what each framework *actually* sends, record real payloads
+once by pointing its hook command at the recorder:
+
+```bash
+# Temporarily set this env for the hook command in the framework's config,
+# then drive the agent through a session start, a failing command, and a stop:
+LOREKIT_HOOK_RECORD=/abs/path/to/packages/cli/test/fixtures \
+  npx @lorekit/cli hook --adapter claude --event SessionStart
+```
+
+Each invocation overwrites `test/fixtures/<adapter>-<event>.json` with the real
+payload. Commit the updated fixtures; the conformance tests then run offline
+forever. This reduces manual validation to a single capture pass per tool.
+
+> The one thing no offline test can cover is a real model loop (the agent
+> actually consuming the injected context). `claude plugin validate` confirms
+> the real Claude CLI accepts the wiring; for a true live check, install the
+> plugin and start one session per tool.
+
+## Security note
+
+`install` writes your token into `.mcp.json`. Keep that file out of version
+control (LoreKit's root `.gitignore` already ignores `.mcp.json`).

package/bin/lorekit.mjs

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+// LoreKit CLI — install the shared-memory skill and run health checks.
+import process from 'node:process';
+import { parseArgs, log, err, c } from '../src/util.mjs';
+import { install } from '../src/install.mjs';
+import { doctor } from '../src/doctor.mjs';
+import { hook } from '../src/hook.mjs';
+import { migrate } from '../src/migrate.mjs';
+import { mcpServer } from '../src/mcp-server.mjs';
+
+const VERSION = '1.0.0';
+
+const HELP = `${c.bold('lorekit')} — shared persistent memory for coding agents
+
+${c.bold('Usage')}
+  npx @lorekit/cli <command> [options]
+
+${c.bold('Commands')}
+  install     Scaffold the lorekit-memory skill into .claude/skills and
+              add the LoreKit server to .mcp.json.
+  doctor      Verify the skill install, MCP connectivity, token, and scope.
+  migrate     Relocate a LoreKit-format local store into the current layout.
+              Dry-run by default; pass --yes to apply. Idempotent.
+  hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
+              JSON on stdin and injects lessons or a retrospective nudge.
+              Not run by hand — wired into a plugin's hook config.
+  mcp         Local stdio MCP server. Exposes the memory.* tools backed by the
+              resolved store (local .lorekit/ offline, or remote passthrough) so
+              .mcp.json can point at the CLI instead of mcp-remote. Speaks
+              JSON-RPC on stdin/stdout — not run by hand.
+
+${c.bold('Options')}
+  -d, --dir <path>        Target project root (default: current directory)
+  -e, --endpoint <url>    LoreKit MCP endpoint
+  -t, --token <token>     LoreKit token (lk_rw_* to allow writes, lk_ro_* read-only)
+      --mode <mode>       Memory mode: off | local | remote (doctor override)
+      --store <path>      Local project-tier store directory (default: .lorekit)
+      --from <path>       Source store to migrate from (migrate)
+      --to <tier>         Migration destination tier: home | project (migrate;
+                          default routes each entry by scope)
+      --apply             Apply the migration (alias of --yes) (migrate)
+  -y, --yes               Non-interactive / apply; never prompt
+      --force             Overwrite existing skill files (install)
+      --deep              Do a write→read→delete round-trip (doctor)
+      --adapter <name>    Host framework for hook: claude | cursor | codex
+      --event <name>      Host hook event (else read from stdin payload)
+  -h, --help              Show this help
+  -v, --version           Print the version
+
+${c.bold('Environment')}
+  LOREKIT_MODE                         off | local | remote (select a mode)
+  LOREKIT_DENY                         comma list of forbidden modes (deny-wins)
+  LOREKIT_HOME                         home-tier root + config dir (default ~/.lorekit)
+  LOREKIT_STORE                        project-tier store directory (default .lorekit)
+  LOREKIT_MCP_URL / LOREKIT_ENDPOINT   endpoint fallback
+  LOREKIT_TOKEN                        token fallback
+  NO_COLOR                             disable colored output
+
+${c.bold('Examples')}
+  npx @lorekit/cli install --endpoint https://ref.supabase.co/functions/v1/mcp --token lk_rw_xxx
+  npx @lorekit/cli doctor --deep
+  npx @lorekit/cli migrate --from .lore                 # preview a rename
+  npx @lorekit/cli migrate --from .lore --to project --yes
+`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const args = parseArgs(argv, {
+    aliases: { d: 'dir', e: 'endpoint', t: 'token', y: 'yes', h: 'help', v: 'version' },
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version'],
+  });
+
+  // `hook` is machine-facing: it must never print help/errors to stdout
+  // (that would corrupt the JSON the host parses). Handle it before the
+  // help/usage branch and always resolve to exit 0.
+  if (args._[0] === 'hook') {
+    return hook(args);
+  }
+
+  // `mcp` is machine-facing too: only JSON-RPC frames may reach stdout, so it
+  // must bypass the help/usage branch. It serves stdio until the client closes.
+  if (args._[0] === 'mcp') {
+    return mcpServer(args);
+  }
+
+  if (args.version) {
+    log(VERSION);
+    return 0;
+  }
+
+  const command = args._[0];
+
+  if (args.help || !command) {
+    log(HELP);
+    return command ? 0 : args.help ? 0 : 1;
+  }
+
+  switch (command) {
+    case 'install':
+      return install(args);
+    case 'doctor':
+      return doctor(args);
+    case 'migrate':
+      return migrate(args);
+    default:
+      err(`${c.red('Unknown command:')} ${command}\n`);
+      log(HELP);
+      return 1;
+  }
+}
+
+main()
+  .then((code) => process.exit(code ?? 0))
+  .catch((e) => {
+    err(`${c.red('Error:')} ${e && e.stack ? e.stack : e}`);
+    process.exit(1);
+  });

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@lorekit/cli",
+  "version": "1.0.0",
+  "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "lorekit": "bin/lorekit.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "skill",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "lorekit",
+    "mcp",
+    "claude",
+    "agent",
+    "memory",
+    "skill",
+    "cli"
+  ],
+  "scripts": {
+    "start": "node bin/lorekit.mjs",
+    "doctor": "node bin/lorekit.mjs doctor",
+    "test": "node --test test/*.test.mjs"
+  }
+}

package/skill/lorekit-memory/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: lorekit-memory
+description: >
+  Shared persistent memory for coding agents, backed by LoreKit's MCP server.
+  Reads scoped lessons at the start of a task or when navigating into
+  unfamiliar code (narrow-to-broad scope resolution across branch, repo,
+  project, and global), and writes a lesson when something goes wrong — a
+  stuck loop, a repeated command failure, a surprising gotcha, a near-miss,
+  or a wrong assumption that cost time. Lessons are phrased as observations
+  (never rigid rules), scoped to the narrowest namespace that fits, and
+  deduplicated on write. Use at task start, before risky operations, and
+  after any failure or retrospective. Triggers on "read lessons", "check
+  memory", "what do we know about", "remember this", "save a lesson",
+  "record this gotcha", "capture this lesson", "/lorekit-memory".
+user-invocable: true
+argument-hint: '[read|write] [scope-hint or lesson]'
+license: MIT
+metadata:
+  author: mthines
+  version: '1.0.0'
+  workflow_type: shared-memory-intake-and-retrospective
+  tags:
+    - lorekit
+    - persistent-memory
+    - shared-memory
+    - mcp
+    - lessons
+    - self-improvement
+    - retrospective
+---
+
+# LoreKit Memory
+
+Give every agent a shared, persistent memory.
+Lessons live in LoreKit (a Supabase-backed MCP server), so what one agent
+learns on one machine — or in CI — is available to every agent, everywhere,
+in the next session.
+
+This skill has two jobs, mirroring the read-on-start / write-on-failure loop
+of the `aw` autonomous-workflow agent:
+
+1. **Read** scoped lessons at the start of a task and before risky steps.
+2. **Write** a lesson when something goes wrong, so the next run avoids it.
+
+Both jobs run through LoreKit's `memory.*` MCP tools.
+If those tools are not connected, this skill is a no-op — say so once and
+continue the task; never block work because memory is unavailable.
+
+> **Modes.** Memory has a controllable backend (`lorekit doctor` shows the
+> resolved one): `remote` (the hosted LoreKit server — the default), `local`
+> (markdown files in two tiers — a per-user **home** tier at `~/.lorekit/` and
+> an opt-in per-repo **project** tier at `<repo>/.lorekit/`), or `off`
+> (disabled). **`local` means _not_ on the hosted website** — local lessons stay
+> on disk and never sync to the LoreKit dashboard. `global` lessons go to home;
+> `repo`/`branch` lessons go to the project tier once you create `<repo>/.lorekit/`
+> (commit it to share with your team, or gitignore it to keep it private), else
+> home. See the `@lorekit/cli` README for the control model, the two-tier merge,
+> and precedence/deny rules.
+
+---
+
+## When to read (intake)
+
+Read at the moments where prior lessons change what you do:
+
+- **Task start** — before planning any non-trivial change.
+- **Navigation** — the first time you open an unfamiliar package, module, or subsystem.
+- **Before a risky operation** — migrations, deploys, worktree/branch surgery, force pushes, anything hard to reverse.
+
+Follow [rules/intake.md](./rules/intake.md).
+The short version: resolve the current scope, list lessons narrow-to-broad,
+and treat matches as *considerations*, not commands.
+
+## When to write (retrospective)
+
+Write when a run produces a durable observation worth carrying forward.
+The trigger is friction, not success. Ask the 30-second question:
+
+> Was there a stuck loop, a repeated failure, a surprise, a near-miss, or a
+> guess that paid off — something a future run would benefit from knowing?
+
+If yes, write it. If the answer is genuinely nothing, write nothing —
+empty retrospectives are skipped entirely.
+
+Follow [rules/retrospective.md](./rules/retrospective.md).
+The short version: phrase the lesson as an observation, pick the narrowest
+scope that fits, check for a near-duplicate first, then `memory.write`.
+
+---
+
+## Scope in one line
+
+Lessons are partitioned by a canonical scope string (`::` is the only separator):
+
+```text
+global                                universal principles
+project::{name}                       monorepo-wide
+repo::{owner}/{repo}                   this repository's codebase
+branch::{owner}/{repo}::{branch}       short-lived, this branch only
+```
+
+Read narrow-to-broad and merge; write to the narrowest scope that correctly
+describes where the lesson applies.
+Full resolution rules: [references/scope-resolution.md](./references/scope-resolution.md).
+
+---
+
+## The MCP tools
+
+| Tool | Use | Token |
+|------|-----|-------|
+| `memory.list` | List lessons for one scope (newest first, tag filter) | read |
+| `memory.search` | Full-text search across scopes (supports `repo::owner/*`) | read |
+| `memory.read` | Read one lesson by scope + key | read |
+| `memory.write` | Store or update a lesson (same scope+key updates in place) | read+write |
+
+Write tools need an `lk_rw_*` token; read tools accept `lk_rw_*` or `lk_ro_*`.
+A read-only token cannot write — if a write fails with an authorization error,
+report it and move on; do not retry.
+
+Every lesson this skill writes carries the tag `skill::lorekit-memory` plus a
+`source::<trigger>` tag (for example `source::stuck-loop`) so lessons are
+easy to find and audit later.
+
+---
+
+## Setup
+
+Install the skill and configure the MCP endpoint with the LoreKit CLI:
+
+```bash
+npx @lorekit/cli install
+npx @lorekit/cli doctor
+```
+
+`install` scaffolds this skill into `.claude/skills/` and adds the LoreKit
+server to `.mcp.json`.
+`doctor` verifies connectivity, token permission, and scope detection.
+See the CLI's own README for flags and troubleshooting.

package/skill/lorekit-memory/references/scope-resolution.md

@@ -0,0 +1,65 @@
+# Scope resolution
+
+A scope string names the namespace a lesson belongs to.
+`::` is the **only** valid separator — a single `:` returns a 400 error.
+All segments are lowercased by the server.
+
+## The four scope types
+
+| Type | Format | Example |
+|------|--------|---------|
+| Global | `global` | `global` |
+| Project (monorepo) | `project::{name}` | `project::agent-skills` |
+| Repository | `repo::{owner}/{repo}` | `repo::mthines/lorekit` |
+| Branch | `branch::{owner}/{repo}::{branch}` | `branch::mthines/lorekit::feat/x` |
+
+## Deriving scope from the working directory
+
+1. Read the `origin` remote URL and normalize it to `owner/repo`:
+   - `git@github.com:mthines/lorekit.git` → `mthines/lorekit`
+   - `https://github.com/mthines/lorekit.git` → `mthines/lorekit`
+   - strip a trailing `.git`, lowercase the result.
+2. Read the current branch: `git rev-parse --abbrev-ref HEAD`.
+3. Compose:
+   - `repo::mthines/lorekit`
+   - `branch::mthines/lorekit::{branch}`
+4. If there is no git remote, there is no repo/branch scope — use `global`,
+   and optionally `project::{basename-of-repo-root}` for a monorepo.
+
+The LoreKit CLI's `doctor` command prints the scope it derives, which is a
+quick way to confirm the agent will read and write to the right place.
+
+## Read order (intake)
+
+Query most specific first, then merge; more specific scopes win on key collisions:
+
+```text
+branch::{owner}/{repo}::{branch}   →   repo::{owner}/{repo}   →   project::{name}   →   global
+```
+
+## Write scope (retrospective)
+
+Use the narrowest scope that correctly describes where the lesson applies:
+
+- Branch-scoped lessons do not pollute the repo's lesson set.
+- Repo-scoped lessons do not pollute global.
+- Only truly universal lessons belong in `global`.
+
+## Wildcards (search only)
+
+`memory.search` accepts an owner-level wildcard in `scopes`:
+
+```json
+{ "scopes": ["repo::mthines/*", "global"] }
+```
+
+Wildcards work **only** in `memory.search` — not in `memory.list`,
+`memory.read`, or `memory.write`.
+
+## Validation rules
+
+1. `::` is the only separator; a single `:` → 400.
+2. `repo::` must include a `/` (owner/repo); `repo::mthines` → 400.
+3. `branch::` must have exactly two `::` separators.
+4. Only `global`, `project`, `repo`, `branch` prefixes are valid.
+5. Segments are trimmed and lowercased on ingest.