@lorekit/cli 1.66.0 → 1.68.0

package/bin/lorekit.mjs

@@ -103,7 +103,8 @@ ${c.bold('Commands')}
               purge: remote only, account-wide, irreversible, --yes required
               non-interactively. Takes no options.
   groom       Preview (default) or --run a retention sweep: --policy-id <id> or
-              --scope <s> [+ --min-age-days/--unseen-days/--max-seen-count/--max-read-count].
+              --scope <s> [+ --min-age-days/--unseen-days/--max-seen-count/
+              --max-read-count/--max-opened-count].
               Remote only. --run soft-archives matches (recoverable via
               restore); prompts for confirmation, --yes to skip. --json.
   policy      Manage saved retention rules: list / create / update / delete.
@@ -385,6 +386,7 @@ ${c.bold('Options')}
       --ttl-days <n>       Days until auto-expiry 1–365 (local or remote)
       --clear-ttl          Remove any existing expiry (make it permanent)
       --org <slug>         Write to this org's scope (remote only)
+      --cited <a,b>        \`scope::key\` refs this lesson applied (remote only)
       --origin-repo <o/n>  Override the derived provenance repository
       --origin-branch <b>  Override the derived provenance branch
       --origin-commit <s>  Override the derived provenance commit SHA
@@ -899,7 +901,8 @@ ${c.bold('Options')}
 
 ${c.bold('Usage')}
   lorekit groom --policy-id <id> [--run] [--yes] [--json]
-  lorekit groom --scope <s> [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>] [--max-read-count <n>] [--run] [--yes] [--json]
+  lorekit groom --scope <s> [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>]
+                            [--max-read-count <n>] [--max-opened-count <n>] [--run] [--yes] [--json]
 
 Resolves the SAME candidates a saved policy or an inline condition set would
 catch, via the retention-policy candidate query — a previewed count always
@@ -919,8 +922,11 @@ ${c.bold('Options')}
       --min-age-days <n>     Match only lessons at least n days old
       --unseen-days <n>      Match lessons unseen for at least n days (never-seen always matches)
       --max-seen-count <n>   Match only lessons that recurred at most n times (WRITES)
-      --max-read-count <n>   Match only lessons READ at most n times. Bulk list/search
-                             reads count here, unlike --unseen-days
+      --max-read-count <n>   Match only lessons DELIVERED at most n times. Bulk list/search
+                             reads count here, unlike --unseen-days, so this runs to
+                             the hundreds — a small value matches nothing
+      --max-opened-count <n> Match only lessons an agent DELIBERATELY fetched at most n
+                             times. Bulk reads do NOT count, so 0 means never chosen
       --run                  Archive the matches instead of previewing
   -y, --yes                  Confirm --run; required when non-interactive
       --json                 Machine-readable result
@@ -934,13 +940,14 @@ ${c.bold('Usage')}
   lorekit policy list [--json]
   lorekit policy create --scope <s> --name <n> [--mode review|auto] [--enabled]
                          [--min-age-days <n>] [--unseen-days <n>] [--max-seen-count <n>]
-                         [--max-read-count <n>]
+                         [--max-read-count <n>] [--max-opened-count <n>]
   lorekit policy update <id> [--name <n>] [--mode review|auto] [--enabled|--disabled]
                          [--min-age-days <n>|--clear-min-age-days] [...] [--json]
   lorekit policy delete <id> [--yes] [--json]
 
 A policy is a saved retention rule: a scope plus AND-ed conditions
-(min-age-days / unseen-days / max-seen-count / max-read-count). \`mode: review\` surfaces it for
+(min-age-days / unseen-days / max-seen-count / max-read-count / max-opened-count).
+\`mode: review\` surfaces it for
 you to run by hand with ${c.cyan('lorekit groom --policy-id')}; \`mode: auto\` gets swept
 nightly, but ONLY once you also pass --enabled — auto starts disabled on
 every new policy so a saved rule never archives anything unattended.
@@ -952,9 +959,11 @@ ${c.bold('Options')}
       --name <n>             Policy name (create) / new name (update)
       --mode <review|auto>   Match mode (create/update)
       --enabled / --disabled Turn auto-mode on/off (create/update)
-      --min-age-days <n>, --unseen-days <n>, --max-seen-count <n>, --max-read-count <n>
+      --min-age-days <n>, --unseen-days <n>, --max-seen-count <n>, --max-read-count <n>,
+      --max-opened-count <n>
                              Conditions (create/update)
-      --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count, --clear-max-read-count
+      --clear-min-age-days, --clear-unseen-days, --clear-max-seen-count,
+      --clear-max-read-count, --clear-max-opened-count
                              Remove a condition (update only)
   -y, --yes                  Confirm delete; required when non-interactive
       --json                 Machine-readable result
@@ -1059,7 +1068,8 @@ const KNOWN_FLAGS = [
   'dir', 'project', 'global', 'endpoint', 'token', 'mode', 'store',
   'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'mcp-json', 'completions', 'complete', 'force', 'deep', 'adapter',
   'event', 'json', 'scope', 'key', 'threshold', 'help', 'version', 'telemetry',
-  'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'remote', 'local',
+  'value', 'tags', 'source-agent', 'trigger', 'kind', 'host', 'ttl-days', 'clear-ttl', 'org', 'cited',
+  'remote', 'local',
   // `view` is accepted-and-IGNORED, not documented: the Explorer dropped the
   // scope/time tab so the flag is a no-op, but `link` is a HUMAN_COMMAND that
   // rejects UNKNOWN options — so keeping `view` listed for a release stops an
@@ -1074,9 +1084,10 @@ const KNOWN_FLAGS = [
   // `invariants candidates`
   'min-seen-count',
   // groom / policy / protect / pin / unpin
-  'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'run',
+  'policy-id', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'max-opened-count', 'run',
   'name', 'mode', 'enabled', 'disabled',
-  'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'off',
+  'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count',
+  'clear-max-opened-count', 'off',
   // `obligations`
   'files', 'strict', 'strict-all',
 ];
@@ -1091,7 +1102,7 @@ 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', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'strict', 'strict-all'],
+    booleans: ['yes', 'force', 'deep', 'apply', 'help', 'version', 'global', 'project', 'no-hooks', 'mcp-json', 'no-origin', 'json', 'remote', 'local', 'link', 'archived', 'clear-ttl', 'telemetry', 'all', 'run', 'enabled', 'disabled', 'off', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'clear-max-opened-count', 'strict', 'strict-all'],
     known: KNOWN_FLAGS,
   });
 

package/package.json

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

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

@@ -175,3 +175,13 @@ new count. Then either move to the next scope or close out the pass.
 - **Someone else's lesson deserves more caution.** A lesson tagged from another
   agent or a teammate is not automatically yours to delete — when in doubt,
   archive rather than hard-delete, and flag it in the plan.
+- **`codebase-knowledge` is durable structure, not an audit log.** The shared
+  `codebase-knowledge` bucket (tag `codebase-knowledge`, `knowledge::<symbol>@<path>`
+  and `hotspot::<path>` keys — see the `lorekit-setup` skill) is a live,
+  multi-loop signal store: every LoreKit loop in the repo both reads and feeds it.
+  Groom it like a signal store, never like the audit-log prose it superficially
+  resembles. Lint its structure and dedupe genuine key collisions, but do **not**
+  mass-archive by age or volume, and do **not** re-key a `knowledge::<symbol>@<path>`
+  entry off its structural key — that key is the join a reader matches against.
+  A stale fact carries `verified_at_sha`; prefer letting its TTL expire or the
+  owning loop overwrite it over hand-removing it.

package/skill/lorekit-memory/SKILL.md

@@ -75,7 +75,12 @@ Read at the moments where prior lessons change what you do:
 
 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.
+and treat matches as *considerations*, not commands. When a run is about to
+change code, intake step 6 reads the standard shared **`codebase-knowledge`**
+bucket — the cross-loop `hotspot::<path>` / `knowledge::<symbol>@<path>` record
+for the files this run will touch, matched by `symbol@path`. A run that verifies
+a structural fact contributes it back, so the layer compounds across every
+LoreKit loop in the repo (contract in the `lorekit-setup` skill).
 
 ## When to write (retrospective)
 

package/skill/lorekit-memory/rules/intake.md

@@ -59,3 +59,44 @@ If lessons matched, note them in one or two lines before proceeding
 ("LoreKit: 2 relevant lessons — worktree naming, migration order").
 If nothing matched, say nothing and continue.
 If the MCP tools are not connected, note it once and continue without them.
+
+## 6. When the run will change code — read the shared codebase-knowledge
+
+Steps 1–4 read **your own** bucket. When this run is about to change code, do one
+more read — not optional, it is how the cross-loop synergy reaches you: the shared
+**`codebase-knowledge`** bucket. This is the repo-scoped, cross-loop record of what
+the codebase has taught every LoreKit loop that touched it
+(`knowledge::<symbol>@<path>` facts, `hotspot::<path>` counters). Its keys are
+**structural** (`symbol@path`, a file path) rather than prose, so you match them
+against the concrete files and symbols this run will touch and pull only the
+records that apply. Read it for exactly the files you will change:
+
+```text
+memory.list { scope: "repo::{owner}/{repo}", tags: ["codebase-knowledge"], limit: 100 }
+# keep only hotspot::<path> / knowledge::<symbol>@<path> whose <path> (and <symbol>)
+# the current change will actually touch — a known regression hotspot or a
+# repeatedly-flagged symbol is then planned with that history in hand.
+```
+
+If this run **verifies** a structural fact about a symbol or file (a consumer
+count you swept, an invariant you confirmed, a defect you fixed at a SHA),
+contribute it back so the next code-changer benefits — write it to
+`codebase-knowledge` under the write contract in the `lorekit-setup` skill,
+`rules/self-improvement-loops.md § Shared codebase-knowledge`. The layer fills
+because its readers also feed it.
+
+Four rules make this safe, and they are non-negotiable:
+
+- Match **structurally and narrowly** — the paths/symbols of this run, never the
+  whole bucket.
+- It **raises care, never lowers a bar** — plan more coverage on a hotspot; an
+  absent record is not evidence of safety.
+- A fact may be **stale** (it carries the writer's `verified_at_sha`) — treat it
+  as a consideration and re-verify against the code.
+- **Read-only.** Never write another host's bucket; write ownership stays with
+  its one owner.
+
+Do **not** cross-read another host's `loop::<host>-lessons` — those are prose
+advice with no structural key to match on. The full contract and when to wire a
+cross-read into a host is the `lorekit-setup` skill,
+`rules/self-improvement-loops.md § Cross-bucket reads (targeted, read-only)`.

package/skill/lorekit-memory/rules/retrospective.md

@@ -14,6 +14,13 @@ Ask the 30-second question:
 If no, stop — write nothing. Empty retrospectives are skipped.
 If yes, continue.
 
+> A retrospective records **prose advice** ("last time X went wrong when Y"). A
+> *structural fact* this run verified about a symbol or file — a consumer count
+> you swept, an invariant you confirmed, a defect you fixed at a SHA — is a
+> different thing: it belongs in the shared **`codebase-knowledge`** bucket under
+> a `knowledge::<symbol>@<path>` key, not here. See the intake step 6 write-back
+> note and the `lorekit-setup` skill, `§ Shared codebase-knowledge`.
+
 ## 2. Phrase it as an observation
 
 Write what happened and what worked, not a commandment.
@@ -69,7 +76,8 @@ memory.write {
   value:        "<observation in markdown>",
   tags:         ["skill::lorekit-memory", "source::stuck-loop"],
   source_agent: "<your agent name, if known>",
-  trigger:      "stuck-loop"
+  trigger:      "stuck-loop",
+  cited:        ["global::pnpm-first"]
 }
 ```
 
@@ -77,6 +85,25 @@ Pick `trigger` / `source::*` from what actually happened:
 `stuck-loop`, `command-failure`, `gotcha`, `near-miss`, `assumption-wrong`,
 `paid-off`, or `manual`.
 
+## 6b. Credit the lessons you actually applied
+
+`cited` is a list of `scope::key` references to lessons that **shaped this
+turn** — ones you were shown at session start or looked up, and then acted on.
+Omit it when nothing applied.
+
+This is the only signal that distinguishes a lesson that was *used* from one
+that was merely *shown*. LoreKit can count deliveries and deliberate fetches on
+its own, but a lesson injected at session start is already in your context and
+gets applied without ever being fetched again — so nothing but you can report it.
+
+- **Name only what you used.** Citing everything you were shown makes the
+  counter measure delivery again, which it already does.
+- **A wrong guess costs nothing.** A reference that does not resolve is dropped
+  silently, and a lesson cannot cite itself. Naming a lesson you are unsure of
+  is cheaper than omitting one you relied on.
+- **Copy the ref exactly as it was shown to you** (`global::pnpm-first`,
+  `repo::acme/app::migration-order`). Do not reconstruct it from memory.
+
 ## 7. Confirm
 
 State in one line what you recorded and where

package/skill/lorekit-setup/SKILL.md

@@ -93,6 +93,23 @@ It covers: when to add a loop (and when not to), the bucket convention (tag
 read/write steps, the promotion gate, the entrenchment guards, a wiring
 checklist, and an interactive setup flow.
 
+## The shared codebase-knowledge layer (automatic cross-loop synergy)
+
+A per-host lessons bucket is private to one host. There is also **one shared
+bucket every code-touching host reads and, under a contract, writes**:
+`codebase-knowledge` — a repo-scoped, structurally-keyed record
+(`knowledge::<symbol>@<path>` facts, `hotspot::<path>` counters) of what the
+codebase has taught every LoreKit loop that touched it. Because the name is fixed
+and the key is structural, a loop wired by one person compounds with a loop wired
+by another: a host about to change code reads the history for exactly the files it
+will touch, and a host that verifies a structural fact contributes it back. That
+is the synergy that appears for a user who wired a single skill and nothing else.
+
+Wire it whenever a host changes code (read at its plan/apply seam) or verifies a
+durable structural fact (write under the contract). The full specification — the
+bucket table, the automatic read side, and the seven-bullet multi-writer write
+contract — is [rules/self-improvement-loops.md § Shared codebase-knowledge](./rules/self-improvement-loops.md#shared-codebase-knowledge-the-standard-cross-loop-layer).
+
 ## Set up CI state (deterministic hosts)
 
 Follow [rules/ci-state-records.md](./rules/ci-state-records.md). It covers: when

package/skill/lorekit-setup/rules/self-improvement-loops.md

@@ -21,6 +21,8 @@ The design has two tiers connected by a recurrence gate. Both run on LoreKit.
 - [Read step (start of every run)](#read-step-start-of-every-run)
 - [Write step (on failure / at the end of a run)](#write-step-on-failure--at-the-end-of-a-run)
 - [The reconcile-on-re-run flow (resolve + record)](#the-reconcile-on-re-run-flow-resolve--record)
+- [Cross-bucket reads (targeted, read-only)](#cross-bucket-reads-targeted-read-only)
+- [Shared codebase-knowledge (the standard cross-loop layer)](#shared-codebase-knowledge-the-standard-cross-loop-layer)
 - [Promotion (fast → slow)](#promotion-fast--slow)
 - [Entrenchment guards (do not skip these)](#entrenchment-guards-do-not-skip-these)
 - [Wiring checklist](#wiring-checklist)
@@ -247,6 +249,134 @@ record shape are specified in `agents/shared/rules/comment-relevance-memory.md`.
 
 ---
 
+## Cross-bucket reads (targeted, read-only)
+
+The default is strict: a loop reads **only its own bucket**, filtered by
+`loop::<host>-lessons`. That isolation is deliberate — it keeps one loop's
+lessons from drowning another's, and lets each read fire at its own cadence
+against its own decision point. Wholesale "read every lesson this repo knows"
+is an **anti-pattern**: it reintroduces exactly the noise the tag split exists
+to prevent, and buries the matches that would have fired.
+
+There is **one** shape of cross-bucket read that is safe and worth wiring: a host
+reading **another host's Signal or Knowledge bucket, matched by a structural key,
+strictly read-only**. Wire it only when all four hold:
+
+1. **The other bucket is keyed by something structural** — a `symbol@path`, a
+   file path, a stable fingerprint — never by prose. A structural key is what
+   makes a cross-host read meaningful: it matches the reader's own concrete work
+   (the files or symbols it is about to touch), not a vague topic.
+2. **The read is bounded to the reader's current work.** Match the other bucket's
+   keys against the paths / symbols this run will actually touch and ignore the
+   rest — never load the whole bucket as advice.
+3. **The reader treats it as advisory and re-verifies.** A cross-host fact can be
+   stale — it carries the *writer's* `verified_at_sha`, not the reader's. It
+   **raises care** (more coverage on a hotspot, design around a known invariant)
+   but never lowers a bar, skips a step, or suppresses a finding. An absent
+   record is never evidence of safety.
+4. **The reader never writes the other bucket.** Write ownership stays with the
+   one owning host; a second writer corrupts its provenance. Cross-host is a
+   **read** relationship only.
+
+Do **not** cross-read another host's `loop::<host>-lessons`. Lessons are prose
+"how to do better" advice tuned to that host's own decisions; they re-key on
+rephrasing and carry no structural anchor to match against, so a cross-read of
+them is the wholesale anti-pattern above. Only Signal / Knowledge buckets with
+structural keys qualify.
+
+LoreKit ships **one** standard instance of this pattern — the shared
+`codebase-knowledge` bucket that every code-touching loop reads and writes. It is
+the mechanism behind the automatic synergy below, and it is what makes a
+structural key worth insisting on: a fixed name plus a `symbol@path` key is what
+lets a loop wired by one person be consumed by a loop wired by another. It is
+specified in full next.
+
+---
+
+## Shared codebase-knowledge (the standard cross-loop layer)
+
+The cross-bucket read above becomes **automatic** through one bucket every LoreKit
+loop shares by name: `codebase-knowledge`. This is the reason two skills wired
+independently — by different people, in different sessions, in the same repo —
+still compound: they read and write the *same* repo-scoped, structurally-keyed
+record of what the codebase has taught every loop that touched it. A code-changing
+loop plans and edits with that history in hand instead of blind; and because the
+loops that consume it also feed it, the synergy appears for a user who wired a
+single skill and nothing else.
+
+### The bucket
+
+| Field | Value |
+| --- | --- |
+| **Tag** | `codebase-knowledge` |
+| **Kind** | `signal` (a durable per-repo filter, read on every run that touches code) |
+| **Scope** | `repo::{owner}/{repo}` — a codebase fact is repo-bound |
+| **TTL** | ~90 days, refreshed on re-verification |
+| **Keys** | `knowledge::<symbol>@<path>` — verified facts about one symbol (an invariant it holds, its consumer/dependent count, a defect it produced before); `hotspot::<path>` — per-file counters (`confirmed`, `regressed`, `missed`) |
+
+The keys are **structural** (`symbol@path`, `path`) on purpose: a key survives a
+rename of the *finding* but not a rename of the *code*, which is exactly the
+sensitivity that lets a different loop match it against the files it is about to
+touch. Set `kind: signal` and `host` explicitly on every write — LoreKit infers
+them only from a `loop::` tag, and this bucket is not tagged that way.
+
+### Read side — automatic for any code-touching host
+
+Wire it at the host's **plan/apply seam** — the moment it has the concrete
+file/symbol list it will change (a plan's File Changes list, an apply pack, a
+fix's target file):
+
+```text
+memory.list { scope: "repo::{owner}/{repo}", tags: ["codebase-knowledge"], limit: 100 }
+# keep only hotspot::<path> / knowledge::<symbol>@<path> whose <path> (and <symbol>)
+# this run will actually touch. Apply as PLANNING INPUTS: raise coverage on a
+# hotspot, design around a known invariant / consumer count. Advisory and
+# re-verified against the code — never a reason to skip a step or suppress a finding.
+```
+
+This is the read-side contract from [Cross-bucket reads](#cross-bucket-reads-targeted-read-only)
+made concrete: structural match, bounded to this run, advisory, an absent record
+never evidence of safety.
+
+### Write side — how the layer fills, and why many writers stay safe
+
+A host that **verifies** a structural fact contributes it back, so the next loop
+reads it. This is what makes the synergy automatic even for a user with one skill
+and no dedicated reviewer: the loops that consume the layer also feed it.
+Multi-writer is safe **only** behind this write contract — bake in every bullet,
+or do not wire the write:
+
+- **Structural key from a real symbol/path list**, never composed from prose. A
+  prose key accumulates nothing and no reader can match it.
+- **`verified_at_sha` on every fact** — the HEAD this run verified it at. It is the
+  whole mechanism the next reader uses to decide "fact stands" vs "re-verify"; an
+  absent or stale SHA makes the fact permanently unverifiable, and it is dropped.
+- **`source_agent` stamped** — which host verified it. Together with
+  `verified_at_sha` this is what makes many writers safe: a reader sees who
+  verified what, and when, so no writer silently overwrites another's provenance.
+- **Only what THIS run actually verified**, grounded in the code — never a guess,
+  and never a value about a person or a telemetry reading. A fact about code,
+  keyed to code.
+- **Merge, never clobber.** Read the existing record first; append to `history[]`
+  or increment counters (each capped) and carry the rest through unchanged. A
+  clobbered counter is indistinguishable from a first write.
+- **Raise care, never suppress.** These records only raise priority/coverage on a
+  file or symbol. They never lower a bar or silence a finding, and an absent record
+  is never evidence of safety. Suppression, if a host needs it, is a different
+  bucket behind verification (the Signal in the reconcile flow above).
+- **Explicit `kind: signal` + `host`, a TTL, and the privacy pre-flight** — as
+  every write in this skill.
+
+Because the name is fixed, the read is the same call in every host, and the write
+follows one contract, **any two LoreKit-wired loops in the same repo compound
+automatically** — which is the whole reason to standardize the name instead of
+letting each host invent its own. The reference ecosystem is `agent-skills`: the
+`pr-reviewer` agent is the primary writer (it verifies symbol facts and file
+hotspots during review), and every code-changing host — `aw`, `implement-suggestion`,
+`fix-bug`, `ci-auto-fix` — reads the layer at its plan/apply seam.
+
+---
+
 ## Promotion (fast → slow)
 
 After a read or write, a lesson is **promotion-eligible** when either:
@@ -316,6 +446,10 @@ To add a loop to a host called `<host>`:
 - [ ] State the **entrenchment guards** so a future maintainer does not "optimize
       them away".
 - [ ] Confirm the loop **degrades silently** when `memory.*` is not connected.
+- [ ] If the host **touches code**, wire the **[codebase-knowledge](#shared-codebase-knowledge-the-standard-cross-loop-layer)
+      read** at its plan/apply seam (match `hotspot::<path>` /
+      `knowledge::<symbol>@<path>` to the files it will change). If it **verifies**
+      a structural fact, wire the **write** behind that section's contract.
 
 ---
 

package/src/commands/groom.mjs

@@ -31,6 +31,8 @@ export function parseGroomRequest(args) {
   if (maxSeen.error) return { error: maxSeen.error };
   const maxRead = parseIntFlag(args['max-read-count'], 'max-read-count');
   if (maxRead.error) return { error: maxRead.error };
+  const maxOpened = parseIntFlag(args['max-opened-count'], 'max-opened-count');
+  if (maxOpened.error) return { error: maxOpened.error };
 
   return {
     request: {
@@ -39,6 +41,7 @@ export function parseGroomRequest(args) {
       unseen_days: unseen.value,
       max_seen_count: maxSeen.value,
       max_read_count: maxRead.value,
+      max_opened_count: maxOpened.value,
     },
   };
 }

package/src/commands/hook.mjs

@@ -333,7 +333,11 @@ async function run(args, meter) {
     }
     if (!shouldRetrospect(stopMode, friction)) return 0;
     if (!firstTimeThisSession(parsed.sessionId, 'retro')) return 0;
-    emit(retrospectiveNudge(scope, control, { reasons }));
+    // The shown set is what BOTH injection paths recorded this session, so the
+    // citation ask names the actual candidates rather than a convention. Read
+    // here and not earlier: every return above this line emits nothing, and the
+    // read is a file the throttled path should not pay for.
+    emit(retrospectiveNudge(scope, control, { reasons, shown: [...shownLessons(parsed.sessionId)] }));
     return 0;
   }
 

package/src/commands/policy.mjs

@@ -31,6 +31,7 @@ function formatPolicy(p) {
   if (p.unseen_days != null) conditions.push(`unseen_days=${p.unseen_days}`);
   if (p.max_seen_count != null) conditions.push(`max_seen_count=${p.max_seen_count}`);
   if (p.max_read_count != null) conditions.push(`max_read_count=${p.max_read_count}`);
+  if (p.max_opened_count != null) conditions.push(`max_opened_count=${p.max_opened_count}`);
   const mode = p.mode === 'auto' ? (p.enabled ? c.green('auto (enabled)') : c.dim('auto (disabled)')) : c.dim('review');
   return `${c.cyan(p.id)}  ${c.bold(p.name)}  ${c.dim(p.scope)}  ${mode}${conditions.length ? `  ${c.dim(conditions.join(', '))}` : ''}`;
 }
@@ -51,7 +52,7 @@ async function list(args, store) {
 
 async function create(args, store) {
   if (!args.scope || !args.name) {
-    err(`${c.red('Usage:')} lorekit policy create --scope <scope> --name <name> [--mode review|auto] [--enabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N]`);
+    err(`${c.red('Usage:')} lorekit policy create --scope <scope> --name <name> [--mode review|auto] [--enabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N] [--max-opened-count N]`);
     return 1;
   }
   const minAge = parseIntFlag(args['min-age-days'], 'min-age-days');
@@ -62,6 +63,8 @@ async function create(args, store) {
   if (maxSeen.error) { err(`${c.red('Error:')} ${maxSeen.error}`); return 1; }
   const maxRead = parseIntFlag(args['max-read-count'], 'max-read-count');
   if (maxRead.error) { err(`${c.red('Error:')} ${maxRead.error}`); return 1; }
+  const maxOpened = parseIntFlag(args['max-opened-count'], 'max-opened-count');
+  if (maxOpened.error) { err(`${c.red('Error:')} ${maxOpened.error}`); return 1; }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
     err(`${c.red('Error:')} --mode must be "review" or "auto"`);
     return 1;
@@ -76,6 +79,7 @@ async function create(args, store) {
     unseen_days: unseen.value,
     max_seen_count: maxSeen.value,
     max_read_count: maxRead.value,
+    max_opened_count: maxOpened.value,
   });
   if (!res.ok) {
     const msg = res.error?.message ?? res.error ?? res.networkError ?? 'the server rejected the request';
@@ -91,7 +95,7 @@ async function create(args, store) {
 async function update(args, store) {
   const id = args._[2];
   if (!id) {
-    err(`${c.red('Usage:')} lorekit policy update <id> [--name N] [--mode review|auto] [--enabled|--disabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N]`);
+    err(`${c.red('Usage:')} lorekit policy update <id> [--name N] [--mode review|auto] [--enabled|--disabled] [--min-age-days N] [--unseen-days N] [--max-seen-count N] [--max-read-count N] [--max-opened-count N]`);
     return 1;
   }
   if (args.mode !== undefined && args.mode !== 'review' && args.mode !== 'auto') {
@@ -109,6 +113,7 @@ async function update(args, store) {
     ['unseen-days', 'clear-unseen-days', 'unseen_days'],
     ['max-seen-count', 'clear-max-seen-count', 'max_seen_count'],
     ['max-read-count', 'clear-max-read-count', 'max_read_count'],
+    ['max-opened-count', 'clear-max-opened-count', 'max_opened_count'],
   ]) {
     if (args[clearFlag]) { patch[field] = null; continue; }
     if (args[flag] === undefined) continue;

package/src/commands/write.mjs

@@ -29,6 +29,14 @@
 //                          omitted, a configured default may apply — see below.
 //   --clear-ttl            Remove any existing expiry (make the memory permanent)
 //   --org <slug>           Write to this org (remote only)
+//   --cited <ref,ref>      `scope::key` refs this lesson APPLIED (remote only)
+//
+// `--cited` credits the lore that shaped the work being written up. It is the
+// only signal that distinguishes a lesson that was read from one that was used:
+// a lesson injected at SessionStart is already in context and is applied without
+// ever being fetched, so the delivered/chosen ratio cannot see it. Unresolvable
+// refs cost nothing — the server drops them — so naming a lesson you are unsure
+// of is cheaper than omitting one you relied on.
 //
 // Provenance — where the lesson is being recorded FROM. Derived automatically
 // from git + the CI environment (repo, branch, commit, and the pull request
@@ -222,6 +230,16 @@ export async function write(args) {
 
   const orgSlug = typeof args.org === 'string' ? args.org : undefined;
 
+  // Split on commas like `--tags`, so there is one list-flag convention. The
+  // refs themselves are NOT parsed here: `scope::key` splits on the first `::`
+  // whose left half is a legal scope, a rule that lives once in
+  // `parseMemoryRef` (mcp-core + its edge mirror) and would become a second,
+  // weaker implementation if this seam guessed at it. A ref this command cannot
+  // resolve is dropped server-side, silently and by design.
+  const cited = args.cited
+    ? String(args.cited).split(',').map((r) => r.trim()).filter(Boolean)
+    : [];
+
   // ── Provenance ────────────────────────────────────────────────────────────
   // Derived from git + CI unless --no-origin; explicit --origin-* flags win.
   // A field that is neither supplied nor derivable is omitted, never sent as
@@ -300,6 +318,16 @@ export async function write(args) {
     return 1;
   }
 
+  // The offline store has no citation ledger — migration 00107's table lives in
+  // Postgres — so a local write would accept the flag and record nothing. Named
+  // rather than dropped: a credit that silently went nowhere is invisible in
+  // exactly the place the whole signal exists to be visible.
+  if (cited.length && storeName === 'local') {
+    err(`${c.red('Error:')} --cited is remote-only (the offline store records no citations)`);
+    err(`Re-run with ${c.cyan('--remote')}, or drop --cited to write the lesson locally.`);
+    return 1;
+  }
+
   // ── Write ──────────────────────────────────────────────────────────────────
   const writeArgs = {
     scope,
@@ -313,6 +341,7 @@ export async function write(args) {
     ...(ttlDays ? { ttl_days: ttlDays } : {}),
     ...(clearTtl ? { clear_ttl: true } : {}),
     ...(orgSlug ? { org: orgSlug } : {}),
+    ...(cited.length ? { cited } : {}),
     ...origin,
   };
 
@@ -346,6 +375,7 @@ export async function write(args) {
       trigger: trigger || null,
       ttl_days: reportedTtlDays,
       ttl_source: reportedTtlSource,
+      cited,
       origin,
     }, null, 2));
   } else {

package/src/core/lessons.mjs

@@ -828,6 +828,43 @@ function ttlHint(writeScope, control) {
   return ` Set ttl_days: ${days} (this scope's configured default) unless the lesson is durable enough to keep forever.`;
 }
 
+// How many injected lesson refs the citation hint names before it summarises the
+// rest. The nudge competes for the same context the lessons themselves occupy, so
+// the list is a prompt for recall, not an inventory — an agent that applied a
+// lesson beyond the cap can still name it, because `cited` takes any ref.
+export const CITED_HINT_MAX = 8;
+
+// Build the citation clause appended to the retrospective nudge, from the
+// `scope::key` ids this session has already injected (core/state.mjs's shown
+// set). Empty string when nothing was injected — with no candidates the ask
+// would be an instruction to invent references.
+//
+// WHY THE ASK EXISTS. `opened_count / read_count` measures whether a lesson was
+// deliberately FETCHED, and a lesson injected at SessionStart is already in
+// context and gets applied without ever being fetched. So the ratio under-counts
+// the dominant delivery path by construction, and only the agent knows the
+// difference. `cited` (migration 00107) is where it says so.
+//
+// The ids are taken in the store's own order, which is injection order, so the
+// SessionStart set leads — it is both the largest and the one in context for the
+// whole turn. Taking the newest instead would favour a per-prompt injection that
+// arrived seconds before the nudge.
+export function citationHint(shown) {
+  const ids = (Array.isArray(shown) ? shown : [...(shown || [])]).filter(
+    (id) => typeof id === 'string' && id.length > 0,
+  );
+  if (ids.length === 0) return '';
+  const named = ids.slice(0, CITED_HINT_MAX);
+  const rest = ids.length - named.length;
+  const more = rest > 0 ? ` (+${rest} more)` : '';
+  return (
+    ` If any injected lesson shaped this turn, name it on the write as` +
+    ` cited: [${named.map((id) => JSON.stringify(id)).join(', ')}]${more} —` +
+    ` drop the ones you did not use. LoreKit can see which lessons were delivered,` +
+    ` never which were applied; this is the only signal that says so.`
+  );
+}
+
 // One-line phrases for the detected friction reason codes (see core/friction.mjs),
 // so the nudge names what happened instead of a generic prompt.
 const REASON_PHRASES = {
@@ -851,11 +888,14 @@ function describeReasons(reasons) {
 // scopeDefaults when the repo/user config defines them. `opts.reasons` is the
 // detected friction reason codes (from core/friction.mjs) when `hooks.stop` is
 // `friction`; when present the nudge names them so the reflection is grounded.
-// Kept to a single line — the lore deep-link lives on the write CONFIRMATION,
-// which is where a link is actually actionable.
-export function retrospectiveNudge(scope, control, { reasons = [] } = {}) {
+// `opts.shown` is the session's injected `scope::key` set (core/state.mjs), which
+// turns the citation ask into a list the agent can pick from rather than a
+// convention it has to remember; omitting it drops the clause entirely.
+// The lore deep-link lives on the write CONFIRMATION, which is where a link is
+// actually actionable.
+export function retrospectiveNudge(scope, control, { reasons = [], shown = [] } = {}) {
   const writeScope = scope.repoScope || 'global';
-  const hint = `${tagsHint(writeScope, control)}${ttlHint(writeScope, control)}`;
+  const hint = `${tagsHint(writeScope, control)}${ttlHint(writeScope, control)}${citationHint(shown)}`;
   const instruction = control && control.hooksInstructions && control.hooksInstructions.Stop
     ? `\n\nProject instruction: ${control.hooksInstructions.Stop}` : '';
   const detected = describeReasons(reasons);

package/src/shared/completions.mjs

@@ -55,6 +55,7 @@ const FLAG = {
   'ttl-days': { desc: 'Days until auto-expiry (1..365)', arg: 'n' },
   'clear-ttl': { desc: 'Remove any existing expiry' },
   org: { desc: "Write to this org's scope (remote)", arg: 'slug' },
+  cited: { desc: 'scope::key refs this lesson applied (remote)', arg: 'a,b' },
   'origin-repo': { desc: 'Override the provenance repository', arg: 'owner/name' },
   'origin-branch': { desc: 'Override the provenance branch', arg: 'branch' },
   'origin-commit': { desc: 'Override the provenance commit', arg: 'sha' },
@@ -77,7 +78,8 @@ const FLAG = {
   'min-age-days': { desc: 'Match lessons at least n days old', arg: 'n' },
   'unseen-days': { desc: 'Match lessons unseen for at least n days', arg: 'n' },
   'max-seen-count': { desc: 'Match lessons that recurred at most n times', arg: 'n' },
-  'max-read-count': { desc: 'Match lessons read at most n times (bulk reads count)', arg: 'n' },
+  'max-read-count': { desc: 'Match lessons delivered at most n times (bulk reads count)', arg: 'n' },
+  'max-opened-count': { desc: 'Match lessons deliberately fetched at most n times (0 = never chosen)', arg: 'n' },
   run: { desc: 'Archive the matches instead of previewing' },
   name: { desc: 'Policy name', arg: 'name' },
   enabled: { desc: 'Turn auto-mode on' },
@@ -86,6 +88,7 @@ const FLAG = {
   'clear-unseen-days': { desc: 'Remove the unseen-days condition' },
   'clear-max-seen-count': { desc: 'Remove the max-seen-count condition' },
   'clear-max-read-count': { desc: 'Remove the max-read-count condition' },
+  'clear-max-opened-count': { desc: 'Remove the max-opened-count condition' },
   off: { desc: 'Unprotect instead of protect' },
 };
 
@@ -138,7 +141,7 @@ const COMMANDS = [
     flags: ['yes', 'endpoint', 'token'] },
   { name: 'write', summary: 'Create or update a memory', positional: 'address',
     flags: ['dir', 'scope', 'key', 'value', 'tags', 'source-agent', 'trigger', 'ttl-days', 'clear-ttl',
-      'org', 'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin', 'remote', 'local',
+      'org', 'cited', 'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin', 'remote', 'local',
       'json', 'endpoint', 'token', 'store'] },
   { name: 'archive', summary: 'Hide a memory without losing it', positional: 'address',
     flags: ['scope', 'key', 'remote', 'local', 'json'] },
@@ -153,11 +156,13 @@ const COMMANDS = [
     flags: ['yes', 'json', 'endpoint', 'token'] },
   { name: 'groom', summary: 'Preview or run a retention sweep',
     values: { mode: ['review', 'auto'] },
-    flags: ['policy-id', 'scope', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'run', 'yes', 'json', 'endpoint', 'token'] },
+    flags: ['policy-id', 'scope', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count', 'max-opened-count',
+      'run', 'yes', 'json', 'endpoint', 'token'] },
   { name: 'policy', summary: 'Manage saved retention rules',
     values: { mode: ['review', 'auto'] },
     flags: ['scope', 'name', 'mode', 'enabled', 'disabled', 'min-age-days', 'unseen-days', 'max-seen-count', 'max-read-count',
-      'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count', 'yes', 'json', 'endpoint', 'token'] },
+      'max-opened-count', 'clear-min-age-days', 'clear-unseen-days', 'clear-max-seen-count', 'clear-max-read-count',
+      'clear-max-opened-count', 'yes', 'json', 'endpoint', 'token'] },
   { name: 'protect', summary: 'Mark a memory protected, excluded from every grooming sweep', positional: 'address',
     flags: ['off', 'scope', 'key', 'json', 'endpoint', 'token'] },
   { name: 'pin', summary: 'Shorthand for `protect` (protected=true)', positional: 'address',

package/src/store/remote.mjs

@@ -283,7 +283,7 @@ class RemoteStore {
   async write(args = {}) {
     const {
       scope, key, value, tags, source_agent, trigger, kind, host, org, ttl_days, clear_ttl, created_at,
-      origin_repo, origin_branch, origin_commit, origin_pr,
+      cited, origin_repo, origin_branch, origin_commit, origin_pr,
     } = args;
     const body = { scope, key, value };
     if (tags !== undefined) body.tags = tags;
@@ -295,6 +295,11 @@ class RemoteStore {
     if (ttl_days !== undefined) body.ttl_days = ttl_days;
     if (clear_ttl !== undefined) body.clear_ttl = clear_ttl;
     if (created_at !== undefined) body.created_at = created_at;
+    // Citations are a fact about the RUN this write belongs to, not a column on
+    // the row (migration 00107) — the server resolves each ref, records the
+    // credit, and drops what it cannot resolve. Sent verbatim: which refs are
+    // legal is the server's grammar to decide, not this transport's.
+    if (cited !== undefined) body.cited = cited;
     // Provenance — only sent when known. Omitting a field leaves whatever the
     // row already recorded intact (the RPC coalesces), which is what makes a
     // write from a machine with no git context non-destructive.
@@ -707,8 +712,8 @@ class RemoteStore {
   }
 
   // POST /policies → the created policy object.
-  async policyCreate({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count } = {}) {
-    const body = stripUndefined({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count });
+  async policyCreate({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
+    const body = stripUndefined({ scope, name, mode, enabled, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
     const res = await this._rest('/memories/policies', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, policy: res.data };
@@ -735,8 +740,8 @@ class RemoteStore {
   // POST /groom/preview → { count, keys: [{ scope, key }] } — the SAME
   // candidates a groom() run would archive. Pass either `policy_id` or
   // `scope` (+ optional conditions), never both.
-  async groomPreview({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count });
+  async groomPreview({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
+    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
     const res = await this._rest('/memories/groom/preview', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, count: res.data?.count ?? 0, keys: Array.isArray(res.data?.keys) ? res.data.keys : [] };
@@ -744,8 +749,8 @@ class RemoteStore {
 
   // POST /groom/run → archives every previewed candidate, in one transaction.
   // Soft-archive only (recoverable via restore); never hard-deletes.
-  async groomRun({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count } = {}) {
-    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count });
+  async groomRun({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count } = {}) {
+    const body = stripUndefined({ policy_id, scope, min_age_days, unseen_days, max_seen_count, max_read_count, max_opened_count });
     const res = await this._rest('/memories/groom/run', { method: 'POST', body });
     if (!res.ok) return { ok: false, error: res.error, httpStatus: res.httpStatus, networkError: res.networkError };
     return { ok: true, archived: res.data?.archived ?? 0, keys: Array.isArray(res.data?.keys) ? res.data.keys : [] };

package/src/surfaces.generated.mjs

@@ -147,6 +147,13 @@ export const MCP_TOOL_DEFS = [
           "type": "integer",
           "minimum": 1,
           "description": "Provenance: the pull request number this memory was recorded from. Combined with origin_repo it renders as a link to the PR."
+        },
+        "cited": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "The lessons that actually shaped this run, as `scope::key` strings — exactly the labels they were injected under. Name only the ones you applied; an empty or omitted list is the honest answer when none were. Silently ignored where a reference names nothing you can see, so a wrong guess costs nothing and the write always succeeds."
         }
       }
     }
@@ -535,6 +542,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -720,6 +733,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned. Omit to leave unchanged; pass explicit null to clear."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat. Omit to leave unchanged; pass explicit null to clear."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -906,6 +925,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat."
+        },
         "tags": {
           "type": "array",
           "items": {
@@ -1076,6 +1101,12 @@ export const MCP_TOOL_DEFS = [
           "maximum": 100000,
           "description": "Match only lessons READ at most this many times — the counter that says whether a lesson was ever actually used, unlike `max_seen_count` which counts WRITES. Counts EVERY read, a bulk `memory.list`/`memory.search` appearance included (unlike `unseen_days`, which only counts targeted opens). Reads have only been counted since the counter shipped, so a long-lived lesson can show a low count it never earned."
         },
+        "max_opened_count": {
+          "type": "integer",
+          "minimum": 0,
+          "maximum": 100000,
+          "description": "Match only lessons an agent DELIBERATELY fetched at most this many times — the count behind `last_opened_at`. Unlike `max_read_count` a bulk `memory.list`/`memory.search` ride-along does NOT count, so `0` means \"nothing ever chose this\" rather than \"this lesson happens to live in a narrow scope\". Backfilled over the whole recorded history, so it carries no cutover caveat."
+        },
         "tags": {
           "type": "array",
           "items": {