@lorekit/cli 1.33.3 → 1.34.0

package/README.md

@@ -231,8 +231,8 @@ Inspect **one** lesson in full — its complete, **untruncated** value plus scop
 key, updated date, tags, and which store(s) it lives in:
 
 ```bash
-lorekit show global prefer-guard-clauses
-lorekit show project::widget build-flags --json
+lorekit show global::prefer-guard-clauses
+lorekit show repo::acme/widget::build-flags --json
 ```
 
 If the same `scope::key` exists in **both** the offline and remote stores —
@@ -242,6 +242,36 @@ missing. It exits **non-zero** when the key is found in no readable store, so it
 fits scripts. `--json` emits the full normalized record(s) and which store each
 came from. Both a scope and a key are required (else a usage error).
 
+### Addressing a memory: `<scope::key>`
+
+`show`, `write` and `link` all take a memory the same way, and the single-token
+`<scope::key>` form is canonical — it is exactly what `list` and `search` print
+and what `write` echoes back, so a key copy-pasted out of any output resolves.
+The explicit two-positional form is also accepted, and `--scope` / `--key` name
+each half outright:
+
+```bash
+lorekit show repo::acme/widget::build-flags        # canonical
+lorekit show repo::acme/widget build-flags         # explicit positionals
+lorekit show --scope repo::acme/widget --key build-flags
+```
+
+The single-token form is split at the **last** `::`, and only when the left side
+is itself a **complete valid scope** — so a multi-segment scope stays whole
+(`repo::acme/widget::build-flags` is scope `repo::acme/widget`, key
+`build-flags`), and a bare `repo::acme/widget` is never mis-read as scope `repo`
+plus a bogus key. Because `::` is reserved as the scope separator, a key that
+itself contains `::` cannot be written as one token — use `--key` for those:
+
+```bash
+lorekit write --scope global --key "loop::aw-lessons" "body"
+```
+
+The scope is validated before any store is touched, so a typo is rejected by
+name (`invalid scope foo — unrecognized scope type`) instead of surfacing later
+as a missing value or, worse, a memory quietly filed under a scope that does not
+exist. See [scope format](../../docs/scope-format.md) for the grammar.
+
 ### `lorekit stats`
 
 An at-a-glance overview of how many lessons apply to the current directory —
@@ -351,7 +381,10 @@ lorekit lint --json           # { total, offline, remote } structured findings
 
 Rules: **empty-value** (blank/whitespace-only body), **short-value** (a non-empty
 body below a small length threshold), **untrimmed-value** (real content with
-surrounding whitespace), **empty-key** (blank key), and **malformed-scope** (e.g.
+surrounding whitespace), **empty-key** (blank key), **volatile-key** (the key
+carries a per-sighting identifier — a run of 6+ digits such as a GitHub comment
+id, or a `pr<n>` / `issue<n>` segment — so it never collides, never dedups, and
+freezes `seen_count` at 1), and **malformed-scope** (e.g.
 a single `:` where `::` is expected). `lint` **exits non-zero (1) when any issue
 is found**, so it is usable as a CI gate (`lorekit lint || exit 1`); a clean run —
 or one where only a store is unavailable — exits 0. The pure rule predicates live
@@ -724,7 +757,8 @@ also returns their headroom against the plan's memory cap.
 | `--force` | Overwrite existing skill files (`install`) |
 | `--deep` | Write/read/delete round-trip (`doctor`) |
 | `--json` | Machine-readable output (`list` / `search` / `show` / `stats` / `scopes` / `diff` / `tree` / `lint` / `dedupe` / `link`) |
-| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe` / `link`; default: all applicable). For `scopes` it is a **substring filter** over the inventory |
+| `--scope <scope>` | Restrict to a single scope (`list` / `search` / `stats` / `diff` / `tree` / `lint` / `dedupe` / `link`; default: all applicable). For `scopes` it is a **substring filter** over the inventory. On `show` / `write` it **names** the scope, overriding the positional |
+| `--key <key>` | Name the key outright (`show` / `write` / `link`) — the way to address a key that itself contains `::` |
 | `--link` | Print the equivalent dashboard deep-link URL instead of running (`show` / `search` / `list` / `tree`) |
 | `--base <url>` | Dashboard base URL for deep links (`link` / `--link`; else `LOREKIT_APP_URL`, default `https://lorekit.io`) |
 | `--threshold <0..1>` | Duplicate-similarity cutoff (`dedupe`; default `0.8`) |

package/bin/lorekit.mjs

@@ -58,10 +58,9 @@ ${c.bold('Commands')}
               rendered in the same Offline/Remote split. --json, --scope <s>.
   show        Inspect one memory in full: its complete value, scope, key, updated
               date, tags, and which store(s) it lives in (noting any divergence
-              when it is in both). Accepts show <scope> <key> or the combined
-              show <scope::key> shorthand (copy-paste directly from list output).
-              --json.
-  write       Create or update a memory. Accepts the same <scope::key> shorthand.
+              when it is in both). Takes show <scope::key> — the format list and
+              search print — or the explicit show <scope> <key>. --json.
+  write       Create or update a memory, addressed the same <scope::key> way.
               Value is a positional, --value flag, or piped stdin. Writes to the
               remote store when configured, falling back to local. --local /
               --remote to force.
@@ -79,8 +78,9 @@ ${c.bold('Commands')}
     (resolve) hierarchy and mark, per key, which scope's memory WINS and which are
               shadowed — the real hook-resolution order. --json, --scope <s>.
   lint        Flag low-quality memories (empty/short/untrimmed value, empty key,
-              malformed scope) across the applicable scopes and both stores. Exits
-              non-zero when issues are found (CI gate). --json, --scope <s>.
+              volatile key, malformed scope) across the applicable scopes and
+              both stores. Exits non-zero when issues are found (CI gate).
+              --json, --scope <s>.
   dedupe      Find likely-duplicate memories via a zero-dep word-overlap HEURISTIC
               (Jaccard >= threshold, not semantic), grouped into clusters per
               store. --json, --scope <s>, --threshold <0..1>.
@@ -113,6 +113,9 @@ ${c.bold('Options')}
       --store <path>      Local project-tier store directory (default: .lorekit)
       --json              Machine-readable output (list / search / show / stats / scopes / diff / tree / lint / dedupe / link)
       --scope <scope>     Restrict to a single scope; a substring filter for scopes (list / search / stats / scopes / diff / tree / lint / dedupe / link)
+                          On show / write it NAMES the scope, overriding the positional
+      --key <key>         Name the key explicitly (show / write / link) — the way to
+                          address a key that itself contains \`::\`
       --link              Print the equivalent dashboard deep-link URL instead of running (show / search / list / tree)
       --base <url>        Dashboard base URL for deep links (link / --link; else LOREKIT_APP_URL, default https://lorekit.io)
       --threshold <0..1>  Duplicate-similarity cutoff (dedupe; default 0.8)
@@ -297,16 +300,27 @@ ${c.bold('Examples')}
   write: `${c.bold('lorekit write')} — create or update a memory from the CLI
 
 ${c.bold('Usage')}
-  npx @lorekit/cli write <scope> <key> <value> [options]
   npx @lorekit/cli write <scope::key> <value> [options]
-  echo "value" | npx @lorekit/cli write <scope> <key> [options]
+  npx @lorekit/cli write <scope> <key> <value> [options]
+  npx @lorekit/cli write --scope <scope> --key <key> <value> [options]
+  echo "value" | npx @lorekit/cli write <scope::key> [options]
 
 Creates or updates a memory (upsert — overwrites if the key exists). Value can
 be a positional, --value, or piped stdin. Writes to the remote store when
 configured, falling back to local.
 
+The single-token <scope::key> form is canonical — it is the format this command
+echoes back and the one list/search print, so it round-trips. It is split at the
+LAST \`::\`, and only when the left side is itself a complete valid scope, so a
+multi-segment scope stays whole: write repo::acme/widget build-flags "..." keeps
+repo::acme/widget as the scope. The scope is validated before anything is
+written, so a typo is rejected rather than stored. Pass --scope/--key to address
+a key that itself contains \`::\`.
+
 ${c.bold('Options')}
   -d, --dir <path>         Target project root (default: current directory)
+      --scope <scope>      Name the scope explicitly (instead of the positional)
+      --key <key>          Name the key explicitly — use for a key containing \`::\`
       --value <text>       Memory value (alternative to positional / stdin)
       --tags <a,b,c>       Comma-separated tags (default: none)
       --source-agent <n>   Source agent name to record (default: none)
@@ -327,35 +341,50 @@ ${c.bold('Options')}
       --store <path>       Local project-tier store directory (default: .lorekit)
 
 ${c.bold('Examples')}
-  npx @lorekit/cli write global my-key "Always prefer guard clauses"
   npx @lorekit/cli write global::my-key "Always prefer guard clauses"
-  cat notes.md | npx @lorekit/cli write global my-key --tags "style,aw"
-  npx @lorekit/cli write global my-key "body" --local
-  npx @lorekit/cli write global my-key "body" --ttl-days 30 --remote
+  npx @lorekit/cli write repo::acme/widget::build-flags "Use --release in CI"
+  npx @lorekit/cli write global my-key "Always prefer guard clauses"
+  cat notes.md | npx @lorekit/cli write global::my-key --tags "style,aw"
+  npx @lorekit/cli write global::my-key "body" --local
+  npx @lorekit/cli write global::my-key "body" --ttl-days 30 --remote
+  npx @lorekit/cli write --scope global --key "loop::aw-lessons" "body"
 `,
   show: `${c.bold('lorekit show')} — inspect one memory in full
 
 ${c.bold('Usage')}
+  npx @lorekit/cli show <scope::key> [options]
   npx @lorekit/cli show <scope> <key> [options]
+  npx @lorekit/cli show --scope <scope> --key <key> [options]
 
 Prints one memory's complete (untruncated) value, scope, key, updated date, tags,
 and which store(s) it lives in. If the same scope::key exists in both the offline
 and remote stores, both are shown and any divergence in their values is flagged.
 Exits non-zero when the key is found in neither readable store.
 
+The single-token <scope::key> form is canonical — it is exactly what list and
+search print, so a key can be copy-pasted straight out of their output. It is
+split at the LAST \`::\`, and only when the left side is itself a complete valid
+scope, so a multi-segment scope stays whole: repo::acme/widget::build-flags is
+scope repo::acme/widget, key build-flags. Pass --scope/--key to address a key
+that itself contains \`::\`.
+
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
       --json              Machine-readable output (the full normalized record(s))
   -e, --endpoint <url>    Remote endpoint override (else .mcp.json / LOREKIT_MCP_URL)
   -t, --token <token>     Remote token override (else .mcp.json / LOREKIT_TOKEN)
       --store <path>      Local project-tier store directory (default: .lorekit)
+      --scope <scope>     Name the scope explicitly (instead of the positional)
+      --key <key>         Name the key explicitly — use for a key containing \`::\`
       --link              Print this memory's dashboard deep-link URL instead of reading (with --base / --json)
 
 ${c.bold('Examples')}
-  npx @lorekit/cli show global prefer-guard-clauses
   npx @lorekit/cli show global::prefer-guard-clauses
+  npx @lorekit/cli show repo::acme/widget::build-flags --json
+  npx @lorekit/cli show global prefer-guard-clauses
   npx @lorekit/cli show project::widget build-flags --json
-  npx @lorekit/cli show global prefer-guard-clauses --link
+  npx @lorekit/cli show --scope global --key "loop::aw-lessons"
+  npx @lorekit/cli show global::prefer-guard-clauses --link
 `,
   stats: `${c.bold('lorekit stats')} — count the applicable memories per scope and per store
 
@@ -467,10 +496,12 @@ ${c.bold('Usage')}
 
 Checks every memory for the current directory's scopes (project/branch/repo/
 global), across both stores, against a small set of quality rules: empty or
-whitespace-only value, suspiciously short value, untrimmed value, empty key, and
-malformed scope (e.g. a single \`:\` where \`::\` is expected). Each finding names
-the rule it violated. Exits NON-ZERO when any issue is found, so it works as a CI
-gate; a clean run — or one where only a store is unavailable — exits 0.
+whitespace-only value, suspiciously short value, untrimmed value, empty key, a
+volatile per-sighting identifier in the key (a run of 6+ digits, or a \`pr<n>\` /
+\`issue<n>\` reference), and malformed scope (e.g. a single \`:\` where \`::\` is
+expected). Each finding names the rule it violated. Exits NON-ZERO when any issue
+is found, so it works as a CI gate; a clean run — or one where only a store is
+unavailable — exits 0.
 
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
@@ -527,6 +558,8 @@ the intended view — a raw ${c.dim('?scope=global')} would silently mean "all s
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
       --scope <scope>     Scope to link to (when no positional scope is given)
+      --key <key>         Name the key explicitly — the way to link to a key
+                          that itself contains \`::\`
       --q <text>          Pre-fill the Explorer search box
       --owner <o>         Ownership filter: all | personal | <orgId>
       --tags <a,b,c>      Label filter (AND across labels); comma-separated or a JSON array
@@ -599,7 +632,7 @@ ${c.bold('Options')}
 const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'force', 'deep', 'adapter',
-  'event', 'json', 'scope', 'threshold', 'help', 'version', 'telemetry',
+  'event', 'json', 'scope', 'key', 'threshold', 'help', 'version', 'telemetry',
   'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
   'link', 'base', 'q', 'owner', 'range', 'view', 'archived',
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.33.3",
+  "version": "1.34.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/skill/lorekit-groom/SKILL.md

@@ -89,8 +89,8 @@ The short version is six phases; the first four are pure analysis.
    `lorekit scopes` (store-wide inventory: every scope with its lesson count)
    show where the mass is. Pick the noisiest scope to start.
 2. **Lint** — `lorekit lint --json` flags structurally bad lessons (empty /
-   whitespace / suspiciously short / untrimmed values, empty keys, malformed
-   scopes). These are the cheapest wins: fix or drop them first.
+   whitespace / suspiciously short / untrimmed values, empty keys, volatile
+   keys, malformed scopes). These are the cheapest wins: fix or drop them first.
 3. **Dedupe** — `lorekit dedupe --json` clusters near-duplicate lessons. Start at
    a high `--threshold` (e.g. `0.85`) for confident duplicates, then lower it to
    surface looser paraphrases. Use `lorekit show <scope::key>` to read each

package/skill/lorekit-groom/rules/grooming-pass.md

@@ -38,6 +38,11 @@ Findings are structural, not semantic — each names its rule:
 - **empty-value / short-value / untrimmed-value** — the lesson carries little or
   no signal, or has stray leading/trailing whitespace.
 - **empty-key** — no key to address it by.
+- **volatile-key** — the key carries a per-sighting identifier (a run of 6+
+  digits such as a GitHub comment id, or a `pr<n>` / `issue<n>` segment), so it
+  never collides with a later write, never dedups, and leaves `seen_count`
+  frozen at 1. Re-key it onto the structural pattern and move the identifier
+  into the body.
 - **malformed-scope** — the scope string is invalid.
 
 These are the cheapest wins and the least controversial, so clear them first.

package/src/deeplink-pure.mjs

@@ -1,8 +1,11 @@
 // Dependency-free deep-link builder for LoreKit dashboard URLs.
 //
-// Zero imports on purpose (the `lessons-pure.mjs` precedent): both the hook hot
-// path (`core/lessons.mjs`) and the `link` command / `--link` flag share this
-// without pulling in `util`/render/store code.
+// Dependency-free on purpose (the `lessons-pure.mjs` precedent): both the hook
+// hot path (`core/lessons.mjs`) and the `link` command / `--link` flag share
+// this without pulling in `util`/render/store code. The ONE import is the
+// re-export of `resolveScopeArg` & friends from `lessons-pure.mjs`, which is
+// itself zero-import — so the property that matters (no util/render/store on
+// the hot path) holds, while the scope grammar stays in a single module.
 //
 // THE governing constraint — every `/lore` Explorer param is read by the web
 // app's `useUrlState` (`packages/web/src/lib/hooks/useUrlState.ts`) via
@@ -123,31 +126,13 @@ export function buildLessonUrl(scope, key, opts = {}) {
   return buildLoreUrl(params, opts);
 }
 
-// Resolve a SINGLE positional `link` argument into a { scope, key } pair,
-// disambiguating a bare scope from the `<scope>::<key>` shorthand. `isScope` is
-// an injected validity predicate (the caller passes a `scopeIssue`-based check),
-// keeping this module zero-import.
-//
-// The rule: split at the LAST `::` and take it as `<scope>::<key>` ONLY when the
-// left side is itself a COMPLETE valid scope — otherwise the whole arg is the
-// scope. Splitting on the last `::` (not the first) keeps a multi-segment scope
-// whole (`repo::owner/name::key` → scope `repo::owner/name`, key `key`); gating
-// on a valid left side means a bare `repo::owner/name` is NOT mis-split, because
-// its left part `repo` is not a valid scope. This is the fix for the prior
-// first-`::` split, which turned `link repo::acme/widget` into scope="repo" plus
-// a bogus `acme/widget` key — breaking the shorthand for EVERY non-`global`
-// scope. A malformed arg falls through to the scope, never a fabricated key. Pure.
-export function resolveScopeArg(arg, isScope = () => false) {
-  const s = typeof arg === 'string' ? arg.trim() : '';
-  if (!s) return { scope: null, key: null };
-  const idx = s.lastIndexOf('::');
-  if (idx !== -1) {
-    const left = s.slice(0, idx).trim();
-    const right = s.slice(idx + 2).trim();
-    if (right && isScope(left)) return { scope: left, key: right };
-  }
-  return { scope: s, key: null };
-}
+// `resolveScopeArg` — the validity-gated `<scope>::<key>` split — now lives in
+// the dependency-free `lessons-pure.mjs` alongside `scopeIssue`, the validator it
+// has to consult, and `resolveScopeKeyArgs`, the full positional/flag parser that
+// `link`, `show` and `write` share. Re-exported here so this module stays the one
+// import site for the `link` command and its tests. `lessons-pure.mjs` is itself
+// zero-import, so this file remains free of the util/render/store stack.
+export { resolveScopeArg, resolveScopeKeyArgs, isScopeString, scopeIssue } from './lessons-pure.mjs';
 
 // ── Flag → param coercion (pure, shared by the `link` command) ────────────────
 

package/src/lessons-pure.mjs

@@ -63,3 +63,139 @@ export function matchesQuery(entry, query) {
   const value = String(entry?.value ?? '').toLowerCase();
   return key.includes(needle) || value.includes(needle);
 }
+
+// ── the scope grammar + the scope/key argument parser ─────────────────────────
+//
+// These three live together, in the dependency-free module, because they are ONE
+// decision: `::` is the scope separator AND the `<scope>::<key>` shorthand's
+// separator, so the only thing that can tell the two uses apart is whether a
+// candidate left-hand side is itself a complete valid scope. A parser that does
+// not consult the validator cannot be correct, and a second copy of either half
+// is how `write`/`show` drifted from `link` in the first place.
+
+// The canonical scope validator: returns null for a well-formed scope, or a
+// short human reason. The grammar (docs/scope-format.md):
+//   global
+//   project::{name}
+//   repo::{owner}/{repo}
+//   branch::{owner}/{repo}::{branch}
+// `::` is RESERVED as the segment separator, so no segment may contain it —
+// that is what makes `resolveScopeArg`'s split decidable. Every scope type
+// enforces it: `project` and `repo` reject a further `::` outright, and
+// `branch` requires exactly two segments after its type.
+export function scopeIssue(scope) {
+  const s = String(scope == null ? '' : scope);
+  if (!s) return 'empty scope';
+  if (s === 'global') return null;
+  const m = /^(project|repo|branch)::(.+)$/.exec(s);
+  if (!m) {
+    // A recognized type followed by a single ':' is the canonical malformed case.
+    if (/^(global|project|repo|branch):(?!:)/.test(s)) return 'single `:` separator (use `::`)';
+    return 'unrecognized scope type (expected global | project | repo | branch)';
+  }
+  const [, type, rest] = m;
+  if (type === 'project') {
+    return rest.includes('::') ? 'project scope takes no further `::` segment' : null;
+  }
+  if (type === 'repo') {
+    // The `::` check comes FIRST and is separate from the `owner/name` shape:
+    // `repo::owner/name::my-key` satisfies `[^/]+/[^/]+` (the key rides along in
+    // the name segment), so without it a `repo::<owner>/<name>::<key>` shorthand
+    // reads as a "valid" scope and the key is swallowed into the repo name.
+    if (rest.includes('::')) return 'repo scope takes no further `::` segment';
+    return /^[^/]+\/[^/]+$/.test(rest) ? null : 'repo scope must be `owner/name`';
+  }
+  // branch
+  const parts = rest.split('::');
+  if (parts.length !== 2 || !/^[^/]+\/[^/]+$/.test(parts[0]) || !parts[1]) {
+    return 'branch scope must be `owner/name::branch`';
+  }
+  return null;
+}
+
+// Is this string a complete, well-formed scope? The predicate form of
+// `scopeIssue`, and the disambiguator every scope/key parse is gated on.
+export function isScopeString(s) {
+  return scopeIssue(s) === null;
+}
+
+// Split a single `<scope>::<key>` argument, or fall back to treating the whole
+// argument as a scope.
+//
+// The rule: split at the LAST `::` and take it as `<scope>::<key>` ONLY when the
+// left side is itself a COMPLETE valid scope — otherwise the whole arg is the
+// scope. Splitting on the last `::` (not the first) keeps a multi-segment scope
+// whole (`repo::owner/name::key` → scope `repo::owner/name`, key `key`); gating
+// on a valid left side means a bare `repo::owner/name` is NOT mis-split, because
+// its left part `repo` is not a valid scope. This is the fix for the prior
+// first-`::` split, which turned `link repo::acme/widget` into scope="repo" plus
+// a bogus `acme/widget` key — breaking the shorthand for EVERY non-`global`
+// scope. A malformed arg falls through to the scope, never a fabricated key.
+//
+// `isScope` is injected rather than closed over so the module stays trivially
+// testable with a stub predicate; callers pass `isScopeString`.
+export function resolveScopeArg(arg, isScope = isScopeString) {
+  const s = typeof arg === 'string' ? arg.trim() : '';
+  if (!s) return { scope: null, key: null };
+  const idx = s.lastIndexOf('::');
+  if (idx !== -1) {
+    const left = s.slice(0, idx).trim();
+    const right = s.slice(idx + 2).trim();
+    if (right && isScope(left)) return { scope: left, key: right };
+  }
+  return { scope: s, key: null };
+}
+
+// Resolve the scope and key a command was given, from its positionals and its
+// `--scope` / `--key` flags. THE single implementation for `write`, `show` and
+// `link`, returning how many positionals it consumed so a command with trailing
+// positionals (`write`'s value) knows where its own arguments start.
+//
+// Precedence, in order:
+//   1. `--scope` / `--key` win outright — an explicit flag is an assertion, so
+//      no `::` split is attempted against the half it names. With BOTH flags no
+//      positional is read at all, which is the ONLY way to express a key that
+//      itself contains `::` (keys are free-form up to 512 chars).
+//   2. A first positional that is ALREADY a complete valid scope is the scope,
+//      verbatim, and the second positional (if any) is the key. This is the
+//      unambiguous two-positional form: `write repo::owner/name my-key value`.
+//   3. Otherwise the first positional is run through `resolveScopeArg` — the
+//      `<scope>::<key>` shorthand. It only splits when that yields a valid
+//      scope, so an unparseable argument becomes the scope and the caller's
+//      `scopeIssue` check reports it as the malformed scope it is.
+//
+// Checking 2 before 3 is what makes `write global::my-key "value"` (shorthand +
+// value) and `write global my-key "value"` (scope + key + value) BOTH resolve
+// correctly from two-and-three positionals: `global::my-key` is not a valid
+// scope, `global` is.
+//
+// Returns `{ scope, key, consumed }`. `scope` is '' and `key` null when nothing
+// was supplied; the caller decides whether that is a usage error (`write`,
+// `show`) or a default (`link`).
+export function resolveScopeKeyArgs(positionals = [], options = {}) {
+  const { scope: scopeFlag, key: keyFlag, isScope = isScopeString } = options;
+  const at = (i) => (typeof positionals[i] === 'string' ? positionals[i].trim() : '');
+  const fScope = typeof scopeFlag === 'string' ? scopeFlag.trim() : '';
+  const fKey = typeof keyFlag === 'string' ? keyFlag.trim() : '';
+
+  if (fScope && fKey) return { scope: fScope, key: fKey, consumed: 0 };
+  if (fScope) {
+    const key = at(0);
+    return { scope: fScope, key: key || null, consumed: key ? 1 : 0 };
+  }
+  if (fKey) {
+    const scope = at(0);
+    return { scope, key: fKey, consumed: scope ? 1 : 0 };
+  }
+
+  const first = at(0);
+  if (!first) return { scope: '', key: null, consumed: 0 };
+
+  if (isScope(first)) {
+    const key = at(1);
+    return { scope: first, key: key || null, consumed: key ? 2 : 1 };
+  }
+
+  const { scope, key } = resolveScopeArg(first, isScope);
+  return { scope: scope || '', key, consumed: 1 };
+}

package/src/lessons-view.mjs

@@ -13,21 +13,19 @@ import { log, heading, status, c } from './util.mjs';
 // hot path can share them without pulling in this file's `util`/render stack.
 // Re-exported here so `search`/`tree` (and their tests) keep one import site;
 // `matchesQuery` is also used internally by `filterGroups` below.
-import { resolvePrecedence, matchesQuery } from './lessons-pure.mjs';
-export { resolvePrecedence, matchesQuery };
-
-// Parse a combined `scope::key` string into { scope, key }, or return null when
-// the input contains no `::`. Uses the FIRST occurrence of `::` as the separator
-// so nested scopes like `branch::owner/repo::feat/x` are handled correctly.
-// Exported so `show`, `write`, and any future commands share one implementation.
-export function parseScopeKey(s) {
-  const idx = s.indexOf('::');
-  if (idx === -1) return null;
-  const scope = s.slice(0, idx).trim();
-  const key = s.slice(idx + 2).trim();
-  if (!scope || !key) return null;
-  return { scope, key };
-}
+// `scopeIssue` (the canonical scope validator) and the scope/key argument
+// parsers live there too — the `lint` rule below and the `write`/`show`/`link`
+// argument handling must agree on ONE scope grammar, and the parser is only
+// decidable because it can ask the validator.
+import {
+  resolvePrecedence,
+  matchesQuery,
+  scopeIssue,
+  isScopeString,
+  resolveScopeArg,
+  resolveScopeKeyArgs,
+} from './lessons-pure.mjs';
+export { resolvePrecedence, matchesQuery, scopeIssue, isScopeString, resolveScopeArg, resolveScopeKeyArgs };
 
 // The scopes that apply to the current directory, most-specific → broadest:
 // project, branch, repo, global. De-duplicated (a repo with no branch scope,
@@ -254,36 +252,6 @@ export function diffGroups(offline = {}, remote = {}) {
 // too terse to carry a durable observation (e.g. "yes", "fixed", "todo").
 export const MIN_VALUE_LEN = 12;
 
-// Validate a scope string against the canonical `::`-separated format
-// (`global`, `project::name`, `repo::owner/name`, `branch::owner/name::branch`).
-// Returns null when valid, else a short human reason. The classic failure is a
-// single `:` where `::` is expected (a 400 on the server). Pure — the lint
-// `malformed-scope` rule and any future scope check share this one validator.
-export function scopeIssue(scope) {
-  const s = String(scope == null ? '' : scope);
-  if (!s) return 'empty scope';
-  if (s === 'global') return null;
-  const m = /^(project|repo|branch)::(.+)$/.exec(s);
-  if (!m) {
-    // A recognized type followed by a single ':' is the canonical malformed case.
-    if (/^(global|project|repo|branch):(?!:)/.test(s)) return 'single `:` separator (use `::`)';
-    return 'unrecognized scope type (expected global | project | repo | branch)';
-  }
-  const [, type, rest] = m;
-  if (type === 'project') {
-    return rest.includes('::') ? 'project scope takes no further `::` segment' : null;
-  }
-  if (type === 'repo') {
-    return /^[^/]+\/[^/]+$/.test(rest) ? null : 'repo scope must be `owner/name`';
-  }
-  // branch
-  const parts = rest.split('::');
-  if (parts.length !== 2 || !/^[^/]+\/[^/]+$/.test(parts[0]) || !parts[1]) {
-    return 'branch scope must be `owner/name::branch`';
-  }
-  return null;
-}
-
 // The lint rule set: each a pure predicate over a normalized entry returning a
 // short reason string when it FIRES, or null when the entry is clean. Kept as
 // discrete named functions so each rule is independently unit-testable and the
@@ -303,6 +271,41 @@ export const LINT_RULES = {
     return v.trim() && v !== v.trim() ? 'value has leading/trailing whitespace' : null;
   },
   'empty-key': (e) => (String(e.key ?? '').trim() ? null : 'key is empty or whitespace-only'),
+  // A key carrying a per-sighting identifier (a comment id, a PR/issue number) is
+  // unique forever, so it never collides, so the upsert never dedups it, so
+  // `seen_count` stays frozen at 1 and the memory can never reach a recurrence
+  // threshold — a write-only record. Detection is deliberately conservative:
+  //   • a run of 6+ digits (a GitHub comment id is ~10; `sha256`, `oauth2`,
+  //     `wcag22`, and semantic versions are all shorter runs);
+  //   • a `pr<n>` / `issue<n>` reference — the number joined by nothing, `-`, or
+  //     `_` — delimited by `:`, `-`, `_`, `/`, or a string boundary, so mid-word
+  //     digits (`oauth2`) never match.
+  // `volatileKeyAllow` is an embedder/test knob mirroring `short-value`'s
+  // `minValueLen` precedent — a list of substrings that exempt a key. There is
+  // no config key and no per-entry marker.
+  'volatile-key': (e, { volatileKeyAllow = [] } = {}) => {
+    const key = String(e.key ?? '');
+    if (!key.trim()) return null; // an empty key is `empty-key`'s to report.
+    // Tolerate a bare string as well as a list, so a caller passing
+    // `{ volatileKeyAllow: 'lorekit-231' }` does not silently iterate characters.
+    const allowList = Array.isArray(volatileKeyAllow) ? volatileKeyAllow : [volatileKeyAllow];
+    for (const allow of allowList) {
+      if (allow && key.includes(String(allow))) return null;
+    }
+    const digitRun = key.match(/\d{6,}/);
+    if (digitRun) {
+      return `key contains a volatile per-sighting identifier: '${digitRun[0]}' (a run of ${digitRun[0].length} digits)`;
+    }
+    // Boundary-anchored rather than split-then-match: splitting on `-` would
+    // separate `pr` from `231` and `pr-231` would slip through. The reference
+    // must start at a boundary (`:`, `-`, `_`, `/`, or the string start) and end
+    // at one, so `oauth2`/`sha256`/`wcag22` still never match.
+    const reference = key.match(/(?:^|[:\-_/])((?:pr|issue)[-_]?\d+)(?=$|[:\-_/])/i);
+    if (reference) {
+      return `key contains a volatile per-sighting identifier: '${reference[1]}' (a pr/issue number segment)`;
+    }
+    return null;
+  },
   'malformed-scope': (e) => {
     const reason = scopeIssue(e.scope);
     return reason ? `malformed scope: ${reason}` : null;

package/src/link.mjs

@@ -17,7 +17,6 @@
 import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
 import { deriveScope } from './scope.mjs';
-import { scopeIssue } from './lessons-view.mjs';
 import {
   resolveAppBase,
   buildLoreUrl,
@@ -26,7 +25,7 @@ import {
   parseViewArg,
   parseRangeArg,
   parseTagsArg,
-  resolveScopeArg,
+  resolveScopeKeyArgs,
   surfaceFor,
 } from './deeplink-pure.mjs';
 import { log, err } from './util.mjs';
@@ -38,26 +37,17 @@ export async function link(args) {
   const base = resolveAppBase({ base: args.base, env });
 
   // Positionals: link [scope] [key] OR link <scope::key>. args._[0] is the
-  // command token ('link' / 'url'), so the first argument is args._[1].
-  const first = typeof args._[1] === 'string' ? args._[1] : '';
-  const second = typeof args._[2] === 'string' ? args._[2] : '';
-  let scope = null;
-  let key = null;
-  if (first && second) {
-    // Two positionals — the first IS the scope (even one containing `::`, like
-    // `repo::owner/name`); the second is the key. The `scope::key` shorthand is
-    // only consulted for a single positional, below.
-    scope = first;
-    key = second;
-  } else if (first) {
-    // One positional: disambiguate a bare scope from the `<scope>::<key>`
-    // shorthand by scope validity, not by a naive first-`::` split — otherwise
-    // `link repo::owner/name` (a valid scope) is misread as scope="repo" + a
-    // bogus key. `scopeIssue(s) === null` is the canonical "is a valid scope".
-    const resolved = resolveScopeArg(first, (s) => scopeIssue(s) === null);
-    scope = resolved.scope;
-    key = resolved.key;
-  }
+  // command token ('link' / 'url'), so the command's positionals start at 1.
+  // The disambiguation rule this command pioneered — split only when the left
+  // side is itself a valid scope — is now the shared `resolveScopeKeyArgs`,
+  // which `show` and `write` use too, so the three can no longer drift.
+  // `--scope` is applied below (positional wins) rather than through the
+  // parser, because for `link` a scope is optional and the flag is a fallback.
+  const positionals = args._.slice(1);
+  const first = typeof positionals[0] === 'string' ? positionals[0] : '';
+  const resolved = resolveScopeKeyArgs(positionals, { key: args.key });
+  let scope = resolved.scope || null;
+  let key = resolved.key;
   // `--scope` sets the scope when no positional scope was given (consistency
   // with the other read commands); an explicit positional always wins.
   if (!scope && typeof args.scope === 'string' && args.scope) scope = args.scope;

package/src/lint.mjs

@@ -1,8 +1,8 @@
 // `lorekit lint` — flag low-quality lessons across the applicable scopes and
 // both stores. Each finding names the rule it violated (empty/whitespace value,
-// suspiciously short value, untrimmed value, empty key, malformed scope). The
-// rules are pure predicates in `lessons-view.mjs` (`LINT_RULES` / `lintEntry`),
-// each independently unit-tested.
+// suspiciously short value, untrimmed value, empty key, volatile key, malformed
+// scope). The rules are pure predicates in `lessons-view.mjs` (`LINT_RULES` /
+// `lintEntry`), each independently unit-tested.
 //
 // Exit convention: `lint` exits NON-ZERO (1) when any finding exists, so it is
 // usable as a CI gate (`lorekit lint || fail`); a clean run — or a run where the

package/src/show.mjs

@@ -1,13 +1,16 @@
-// `lorekit show <scope> <key>` — inspect ONE lesson in full: its complete
+// `lorekit show <scope::key>` — inspect ONE lesson in full: its complete
 // (untruncated) value, scope, key, updated timestamp, tags, and which store(s)
 // it lives in. When the same scope::key exists in BOTH the offline and remote
 // stores — possibly with different values — both are shown and the divergence is
 // flagged.
 //
-// Two positional shapes are accepted:
-//   show <scope> <key>     — classic two-positional form
-//   show <scope::key>      — combined shorthand (the same format `list` prints,
-//                            so you can copy-paste a key directly from list output)
+// Positional shapes accepted (see `resolveScopeKeyArgs` in `lessons-pure.mjs`
+// for the one shared, scope-validity-gated disambiguation rule):
+//   show <scope::key>      — canonical form (the same format `list` prints, so
+//                            you can copy-paste a key directly from list output)
+//   show <scope> <key>     — the explicit two-positional form
+//   show --scope <s> --key <k>
+//                          — flags win; the only way to name a key containing `::`
 //
 // Uses each store's real `read({scope, key})` method (both stores expose it),
 // not a filtered `list` — a single-record lookup is what `read` is for, and it
@@ -18,7 +21,14 @@ import process from 'node:process';
 import { resolveProjectRoot } from './config.mjs';
 import { resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
-import { normalizeEntry, shortDate, describeError, recordsDiverge, parseScopeKey } from './lessons-view.mjs';
+import {
+  normalizeEntry,
+  shortDate,
+  describeError,
+  recordsDiverge,
+  resolveScopeKeyArgs,
+  scopeIssue,
+} from './lessons-view.mjs';
 import { resolveAppBase } from './deeplink-pure.mjs';
 import { emitLink } from './link.mjs';
 import { log, err, heading, status, c } from './util.mjs';
@@ -47,27 +57,40 @@ export async function show(args) {
   const env = { ...process.env };
   if (args.store) env.LOREKIT_STORE = args.store;
 
-  // Two positional shapes are accepted:
-  //   show <scope> <key>    — classic two-positional form (backward-compatible)
-  //   show <scope::key>     — combined shorthand mirroring `list` output format
-  let scope, key;
-  const first = typeof args._[1] === 'string' ? args._[1] : '';
-  const parsed = parseScopeKey(first);
-  if (parsed) {
-    // Combined scope::key — e.g. `show global::claude-mcp-registration-can-hang`
-    scope = parsed.scope;
-    key = parsed.key;
-  } else {
-    // Classic two-positional form — e.g. `show global claude-mcp-registration-can-hang`
-    scope = first;
-    key = typeof args._[2] === 'string' ? args._[2] : '';
+  // Positional shapes (all resolved by the shared, validity-gated parser):
+  //   show <scope::key>            — canonical shorthand, mirrors `list` output
+  //   show <scope> <key>           — explicit two-positional form
+  //   show --scope <s> --key <k>   — flags win; the escape hatch for a key
+  //                                  containing `::`
+  const positionals = args._.slice(1);
+  const { scope, key, consumed } = resolveScopeKeyArgs(positionals, {
+    scope: args.scope,
+    key: args.key,
+  });
+  // Scope validity is checked FIRST, for the same reason as in `write`: a bad
+  // scope is the root cause, and "a key is required" is downstream noise.
+  const badScope = scope ? scopeIssue(scope) : null;
+  if (badScope) {
+    err(`${c.red('Error:')} invalid scope ${c.cyan(scope)} — ${badScope}`);
+    err(`Valid scopes: global | project::<name> | repo::<owner>/<name> | branch::<owner>/<name>::<branch>`);
+    err(`Run ${c.cyan('lorekit show --help')} for options.`);
+    return 1;
   }
   if (!scope || !key) {
-    err(`${c.red('Usage:')} lorekit show <scope> <key> [--json]`);
-    err(`       lorekit show <scope::key> [--json]`);
+    err(`${c.red('Usage:')} lorekit show <scope::key> [--json]`);
+    err(`       lorekit show <scope> <key> [--json]`);
     err(`Both a scope and a key are required. Run ${c.cyan('lorekit show --help')} for options.`);
     return 1;
   }
+  // `show` consumes every positional it is given — unlike `write`, it has no
+  // trailing value — so a leftover one means the caller's mental model differs
+  // from what was parsed. Say so instead of silently reading a different key.
+  if (positionals.length > consumed) {
+    err(`${c.red('Error:')} unexpected argument ${c.cyan(positionals[consumed])}`);
+    err(`Parsed scope ${c.cyan(scope)} and key ${c.cyan(key)} from the arguments before it.`);
+    err(`Run ${c.cyan('lorekit show --help')} for options.`);
+    return 1;
+  }
 
   // `--link` short-circuits: print the deep link that opens THIS lesson's detail
   // sheet (`?scope=…&lesson=…`) for the current args, without touching a store.

package/src/write.mjs

@@ -1,9 +1,21 @@
-// `lorekit write <scope> <key> [value]` — create or update a memory from the CLI.
+// `lorekit write <scope::key> [value]` — create or update a memory from the CLI.
 //
 // Two positional shapes are accepted:
-//   write <scope> <key> [value]       — classic two-positional form
-//   write <scope::key> [value]        — combined shorthand (the same format `list`
-//                                       prints, so you can copy-paste a key directly)
+//   write <scope::key> [value]        — canonical form: ONE token, exactly the
+//                                       format `list`/`search` print and this
+//                                       command echoes back, so a key can be
+//                                       copy-pasted straight from any output
+//   write <scope> <key> [value]       — the explicit two-positional form, kept
+//                                       because it is unambiguous by position
+//   write --scope <s> --key <k> [value]
+//                                     — flags win outright; the ONLY way to
+//                                       express a key that itself contains `::`
+//
+// Disambiguation is `resolveScopeKeyArgs`'s job (`lessons-pure.mjs`) and is
+// gated on scope VALIDITY, never on a naive `::` split: `write repo::o/n k v`
+// keeps `repo::o/n` whole because it is already a valid scope, while
+// `write global::k v` splits because `global::k` is not. The scope is then
+// validated with `scopeIssue` before any store is touched.
 //
 // When no value is supplied as a positional or via --value, the command reads
 // the full stdin (useful for piping). In all cases the value is required — an
@@ -52,7 +64,7 @@ import { resolveProjectRoot } from './config.mjs';
 import { loadControl, resolveDenies } from './control.mjs';
 import { resolveStores, remoteUnavailableReason } from './stores.mjs';
 import { log, err, heading, status, c } from './util.mjs';
-import { parseScopeKey } from './lessons-view.mjs';
+import { resolveScopeKeyArgs, scopeIssue } from './lessons-view.mjs';
 import { deriveOrigin, mergeOrigin } from './origin.mjs';
 import { parseTtlDays, resolveDefaultTtlDays } from './store/ttl.mjs';
 
@@ -72,33 +84,67 @@ export async function write(args) {
   const env = { ...process.env };
   if (args.store) env.LOREKIT_STORE = args.store;
 
-  // ── Parse positionals: two forms ──────────────────────────────────────────
-  // Form A: `write scope key [value]`   → _[1]=scope, _[2]=key, _[3]=value?
-  // Form B: `write scope::key [value]`  → _[1]='scope::key', _[2]=value?
-  let scope, key, positionalValue;
-
-  const first = typeof args._[1] === 'string' ? args._[1] : '';
-  const parsed = parseScopeKey(first);
+  // ── Parse positionals ─────────────────────────────────────────────────────
+  // The shared `resolveScopeKeyArgs` decides between the shorthand and the
+  // two-positional form (and honours --scope/--key), and reports how many
+  // positionals it took so the VALUE is read from the right index in both:
+  //   write <scope::key> <value>     → consumed 1, value at _[2]
+  //   write <scope> <key> <value>    → consumed 2, value at _[3]
+  // `args._[0]` is the command token, so the command's own positionals start
+  // at index 1.
+  const positionals = args._.slice(1);
+  const { scope, key, consumed } = resolveScopeKeyArgs(positionals, {
+    scope: args.scope,
+    key: args.key,
+  });
+  const positionalValue =
+    typeof positionals[consumed] === 'string' ? positionals[consumed] : undefined;
 
-  if (parsed) {
-    // Form B: combined scope::key
-    scope = parsed.scope;
-    key = parsed.key;
-    positionalValue = typeof args._[2] === 'string' ? args._[2] : undefined;
-  } else {
-    // Form A: separate scope and key
-    scope = first;
-    key = typeof args._[2] === 'string' ? args._[2] : '';
-    positionalValue = typeof args._[3] === 'string' ? args._[3] : undefined;
+  // Validate the scope BEFORE the missing-key check, the value, or any store.
+  // Order matters: a bad scope is the ROOT cause and every other complaint is
+  // downstream noise. `write foo "asd"` parses as scope `foo` + key `asd` with
+  // no value left, and used to report "a non-empty value is required" — three
+  // steps removed from the actual mistake. The offline store accepts any
+  // string, so this is also the only thing standing between a local write and
+  // a scope the hosted API would reject with a 400. It is a PARTIAL gate, not
+  // an equivalent one: `scopeIssue` checks the segment SHAPE (`[^/]+/[^/]+`)
+  // where `packages/mcp-core/src/scope.ts` additionally restricts the CHARSET
+  // (`[\w.-]+/[\w.-]+`), so `repo::a b/c,d` and `branch::o/r::a",x` pass here
+  // and still 400 remotely. Tightening the CLI to match would also change what
+  // `lint`'s malformed-scope rule flags in existing offline stores, so it is a
+  // deliberate follow-up rather than a silent widening of this check.
+  const badScope = scope ? scopeIssue(scope) : null;
+  if (badScope) {
+    err(`${c.red('Error:')} invalid scope ${c.cyan(scope)} — ${badScope}`);
+    err(`Valid scopes: global | project::<name> | repo::<owner>/<name> | branch::<owner>/<name>::<branch>`);
+    err(`Run ${c.cyan('lorekit write --help')} for options.`);
+    return 1;
   }
 
   if (!scope || !key) {
-    err(`${c.red('Usage:')} lorekit write <scope> <key> [value] [options]`);
-    err(`       lorekit write <scope::key> [value] [options]`);
+    err(`${c.red('Usage:')} lorekit write <scope::key> <value> [options]`);
+    err(`       lorekit write <scope> <key> <value> [options]`);
     err(`Both a scope and a key are required. Run ${c.cyan('lorekit write --help')} for options.`);
     return 1;
   }
 
+  // Leftover positionals are an error, exactly as in `show` — the difference is
+  // only in how many this command legitimately consumes: the parser's `consumed`
+  // plus ONE for the value, and zero for the value when `--value` already named
+  // it. Without this, `--scope` (which makes the parser take one fewer
+  // positional) silently shifted everything left: `write global my-key "v"
+  // --scope global` resolved scope `global`, key `global`, value `my-key` — it
+  // stored the wrong key, dropped the value, and exited 0. A wrong write that
+  // reports success is worse than any usage error, so the leftover is named.
+  const valueSlots = typeof args.value === 'string' ? 0 : 1;
+  if (positionals.length > consumed + valueSlots) {
+    const stray = positionals[consumed + valueSlots];
+    err(`${c.red('Error:')} unexpected argument ${c.cyan(stray)}`);
+    err(`Parsed scope ${c.cyan(scope)} and key ${c.cyan(key)} from the arguments before it.`);
+    err(`Run ${c.cyan('lorekit write --help')} for options.`);
+    return 1;
+  }
+
   // ── Resolve value: flag → positional → stdin ───────────────────────────────
   let value;
   if (typeof args.value === 'string') {