@lorekit/cli 1.33.2 → 1.33.4

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 —
@@ -724,7 +754,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.
@@ -113,6 +112,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 +299,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 +340,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
 
@@ -527,6 +555,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 +629,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.2",
+  "version": "1.33.4",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

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

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/mcp.mjs

@@ -138,6 +138,26 @@ export function normalizeCorrelationId(raw) {
   return /^[A-Za-z0-9_\-./:#@]+$/.test(t) ? t : null;
 }
 
+/**
+ * Normalise a deployment-environment marker restFetch attaches as
+ * X-LoreKit-Deployment-Environment when DEPLOYMENT_ENVIRONMENT (or
+ * OTEL_DEPLOYMENT_ENVIRONMENT) is set. It lets a smoke/test run tell the edge to
+ * report `deployment.environment.name` for that request — the edge honours only
+ * the synthetic `test` value, so real traffic (no env set) is never tagged and a
+ * caller can never relabel itself as another real environment. This is the SAME
+ * value `resolveDeploymentEnvironment` (packages/cli/src/telemetry.mjs) puts on
+ * the CLI's own resource, so one `DEPLOYMENT_ENVIRONMENT=test` marks both the CLI
+ * span and its downstream edge spans. Bounded + charset-restricted (fail-safe: a
+ * bad value is not sent). Zero-dep, so the small regex is duplicated
+ * intentionally, like `normalizeCorrelationId`.
+ */
+export function normalizeRunEnvironment(raw) {
+  if (typeof raw !== 'string') return null;
+  const t = raw.trim();
+  if (!t || t.length > 64) return null;
+  return /^[A-Za-z0-9_.\-:]+$/.test(t) ? t : null;
+}
+
 export async function restFetch(baseUrl, token, path, { method = 'GET', body, timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -148,12 +168,21 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
     // /memories/usage?correlation_id=… can report "usage for this PR". Absent env
     // ⇒ no header ⇒ existing behaviour unchanged.
     const correlationId = normalizeCorrelationId(process.env.LOREKIT_CORRELATION_ID);
+    // Opt-in test-run marker: when DEPLOYMENT_ENVIRONMENT is set (a deploy/CI
+    // smoke sets it to `test`), tell the edge to report that
+    // `deployment.environment.name` for this request so Dash0 can filter synthetic
+    // smoke traffic apart from real usage. Absent env ⇒ no header ⇒ existing
+    // behaviour unchanged. The edge honours only `test` (see otel.ts).
+    const runEnv = normalizeRunEnvironment(
+      process.env.DEPLOYMENT_ENVIRONMENT ?? process.env.OTEL_DEPLOYMENT_ENVIRONMENT,
+    );
     const headers = {
       accept: 'application/json',
       ...(body !== undefined ? { 'content-type': 'application/json' } : {}),
       ...(token ? { authorization: `Bearer ${token}` } : {}),
       ...(traceparent ? { traceparent } : {}),
       ...(correlationId ? { 'x-lorekit-correlation-id': correlationId } : {}),
+      ...(runEnv ? { 'x-lorekit-deployment-environment': runEnv } : {}),
       // Name the calling surface so usage analytics can tell a CLI read from a
       // dashboard one. Not cosmetic: `GET /memories/read-activity` EXCLUDES the
       // `dashboard` client (a human browsing lore is not consuming it), so a

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') {