@lorekit/cli 1.45.0 → 1.47.0

package/README.md

@@ -466,9 +466,9 @@ that lesson's detail sheet. It sets **both** the `lesson` param (which opens the
 sheet) and `scope` — not because scope is needed to find the lesson (the sidebar
 reads one unfiltered recent set), but so the Explorer list *behind* the sheet is
 filtered to the lesson's own scope. Filter flags mirror the Explorer: `--q`
-(search), `--owner <all|personal|orgId>`, `--tags <a,b,c>` (label filter, AND
+(search), `--owner <all|personal|org-slug>`, `--tags <a,b,c>` (label filter, AND
 across labels; comma-separated or a JSON array), `--range`/`--from`/`--to`,
-`--archived`, `--view <scope|time>`.
+`--archived`.
 
 Every param is `encodeURIComponent(JSON.stringify(value))` — the exact inverse of
 how the dashboard's `useUrlState` reads it back (`JSON.parse`, falling back to the
@@ -717,6 +717,26 @@ Both files share this schema — all fields optional:
                            // memories are RANKED before the budget is spent, so what
                            // survives is the most-recurring and most-recent, not the newest
 
+  "hooks.sessionStart.loopCap": 2,
+                           // how many memories one self-improvement loop (a
+                           // "loop::<bucket>" tag) may contribute to that block
+                           // (default 2, bounded 0–40; 0 excludes loop buckets
+                           // entirely so only general memories are read). Clamped,
+                           // not rejected; repo wins over user with the same
+                           // declared-value-owns-the-layer rule as maxChars
+
+  "hooks.sessionStart.branchHint": "on",
+                           // whether the block is nudged toward the current git
+                           // branch's topic — on "feat/embedding-pipeline",
+                           // embedding memories are lifted (the leading type/author
+                           // segment is ignored). Default "on"; it only ever lifts
+                           // an on-topic memory, never buries one. "off" restores
+                           // the plain most-recurring / most-recent read. Repo wins
+                           // over user, but — following hooks.userPrompt, not the
+                           // maxChars layer-lock — a declared-but-unparseable repo
+                           // value FALLS THROUGH to a valid user value rather than
+                           // owning the layer
+
   "hooks.adapter": "claude",
                            // explicit adapter when auto-detection is ambiguous
                            // values: "claude" | "cursor" | "codex"

package/bin/lorekit.mjs

@@ -88,7 +88,7 @@ ${c.bold('Commands')}
   link (url)  Print a shareable dashboard deep-link URL for the current context,
               a scope, or a specific lesson (opens its detail sheet). No args
               links to the cwd's most-specific scope. Filter flags mirror the
-              Explorer (--q / --owner / --tags / --range / --archived / --view);
+              Explorer (--q / --owner / --tags / --range / --archived);
               --base or LOREKIT_APP_URL override the dashboard host. --json. Pipe it:
               lorekit link | pbcopy.
   bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
@@ -585,13 +585,12 @@ ${c.bold('Options')}
       --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>
+      --owner <o>         Ownership filter: all | personal | <org-slug>
       --tags <a,b,c>      Label filter (AND across labels); comma-separated or a JSON array
       --range <json>      Date range as {"from":"YYYY-MM-DD","to":"YYYY-MM-DD"}
       --from <date>       Range start (shorthand for --range)
       --to <date>         Range end (shorthand for --range)
       --archived          Include archived memories
-      --view <mode>       Explorer view: scope | time
       --base <url>        Dashboard base URL (else LOREKIT_APP_URL, default https://lorekit.io)
       --json              Machine-readable { url, surface, base, params }
 
@@ -658,7 +657,13 @@ const KNOWN_FLAGS = [
   'from', 'to', 'apply', 'yes', 'hooks', 'no-hooks', 'mcp-json', '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',
-  'link', 'base', 'q', 'owner', 'range', 'view', 'archived',
+  // `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
+  // existing `lorekit link --view time` from hard-failing on an unknown-option
+  // error. It is parsed and discarded (nothing reads `args.view`). Remove it once
+  // 1.x links have aged out.
+  'link', 'base', 'q', 'owner', 'range', 'archived', 'view',
   'origin-repo', 'origin-branch', 'origin-commit', 'origin-pr', 'no-origin',
   // Scale-aware survey flags
   'all', 'max', 'since', 'until', 'key-prefix', 'cluster-by-key',

package/package.json

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

package/src/control.mjs

@@ -10,6 +10,8 @@
 //   hooks.stop      — Stop-hook gating ("friction" default | "always" | "off")
 //   hooks.sessionStart          — injected-block shape ("hybrid" default | "index" | "map")
 //   hooks.sessionStart.maxChars — character budget for that block (default 1500)
+//   hooks.sessionStart.loopCap  — max lessons per self-improvement loop bucket (default 2; 0 excludes them)
+//   hooks.sessionStart.branchHint — nudge the read toward the git branch topic ("on" default | "off")
 //   hooks.userPrompt — the per-turn relevance pull ("on" default | "off")
 //   hooks.adapter   — explicit adapter override ("claude" | "cursor" | "codex")
 //
@@ -140,6 +142,31 @@ export function normalizeSessionStartMaxChars(v) {
   return i;
 }
 
+// The default per-loop-bucket cap for the SessionStart read, and the bounds a
+// configured one is held to. 2 keeps each self-improvement loop's top couple of
+// lessons without letting one bucket flood a general session; 0 is a meaningful
+// setting — exclude loop buckets entirely and read only general codebase lessons.
+// The ceiling is a generous backstop against a typo'd cap, not a shared constant:
+// `core/lessons.mjs` bounds the whole read at its own hard lesson ceiling
+// downstream, so any loopCap at or above that never binds regardless of the exact
+// number here — they are deliberately independent, not kept in lockstep.
+export const DEFAULT_SESSION_START_LOOP_CAP = 2;
+export const MIN_SESSION_START_LOOP_CAP = 0;
+export const MAX_SESSION_START_LOOP_CAP = 40;
+
+// Clamp a configured loop cap into range, or null when it is not a usable number
+// (absent, a bare string, NaN). Total: the caller substitutes the default for
+// null. Out-of-range CLAMPS rather than rejecting, like the maxChars budget — and
+// `0` is honoured, not floored away, because "exclude loop buckets" is a real ask.
+export function normalizeSessionStartLoopCap(v) {
+  const n = firstNumber(v);
+  if (n === null) return null;
+  const i = Math.round(n);
+  if (i < MIN_SESSION_START_LOOP_CAP) return MIN_SESSION_START_LOOP_CAP;
+  if (i > MAX_SESSION_START_LOOP_CAP) return MAX_SESSION_START_LOOP_CAP;
+  return i;
+}
+
 // A config value that is meant to be a number, or null when it is absent or is
 // something else entirely. Numeric strings are accepted because JSON configs get
 // hand-edited; the RANGE check happens later, at the point of use.
@@ -328,6 +355,26 @@ export function resolveControl({
   const hooksSessionStartMaxChars =
     normalizeSessionStartMaxChars(sessionStartMaxCharsRaw) ?? DEFAULT_SESSION_START_MAX_CHARS;
 
+  // `hooks.sessionStart.loopCap` — how many lessons one `loop::<bucket>` may
+  // contribute. Same layer-before-parse rule as maxChars (declaresScalar): a repo
+  // that declared a cap owns it even when the value is garbage, so two people on
+  // the same commit get the same read. `0` is a valid, deliberate value, so the
+  // default is only substituted when NOTHING usable was declared.
+  const sessionStartLoopCapRaw = declaresScalar(repoConfig['hooks.sessionStart.loopCap'])
+    ? repoConfig['hooks.sessionStart.loopCap']
+    : userConfig['hooks.sessionStart.loopCap'];
+  const normalizedLoopCap = normalizeSessionStartLoopCap(sessionStartLoopCapRaw);
+  const hooksSessionStartLoopCap =
+    normalizedLoopCap === null ? DEFAULT_SESSION_START_LOOP_CAP : normalizedLoopCap;
+
+  // `hooks.sessionStart.branchHint` — whether the read is nudged toward the git
+  // branch topic. On/off (the `hooks.userPrompt` vocabulary), default `on`, repo
+  // layer wins. Off restores the pre-branch-query read: recency + salience only.
+  const hooksSessionStartBranchHint =
+    normalizeUserPromptMode(repoConfig['hooks.sessionStart.branchHint']) ||
+    normalizeUserPromptMode(userConfig['hooks.sessionStart.branchHint']) ||
+    'on';
+
   // `hooks.adapter` — repo layer wins over user layer (explicit project override).
   const hooksAdapter =
     (typeof repoConfig['hooks.adapter'] === 'string' && repoConfig['hooks.adapter'].trim()) ||
@@ -368,6 +415,8 @@ export function resolveControl({
     hooksUserPrompt,
     hooksSessionStart,
     hooksSessionStartMaxChars,
+    hooksSessionStartLoopCap,
+    hooksSessionStartBranchHint,
     hooksAdapter,
     hooksInstructions,
   };

package/src/core/lessons.mjs

@@ -75,7 +75,9 @@ const HARD_LESSON_CEILING = 40;
 // back by their own host through a tag filter. Two per bucket keeps the signal
 // (a loop's top couple of lessons still surface) without the flood; general,
 // non-loop lessons are never capped. Bounded, not shaped: on a store with no
-// loop lessons it never binds.
+// loop lessons it never binds. This is the DEFAULT — a repo/user can override it
+// with `hooks.sessionStart.loopCap` (0 excludes loop buckets entirely), which
+// `fetchLessons` receives as its `loopCap` option.
 const SESSION_START_LOOP_CAP = 2;
 
 // How many lessons ride along with the scope map in `map` mode. Small on
@@ -115,7 +117,11 @@ export const SCOPE_READ_LIMIT = 25;
 // that already hold a resolved scope and for tests that need a deterministic
 // branch (deriveScope shells out to git, so the ambient branch — often a
 // detached `HEAD` in CI — cannot exercise the branch-seeded read otherwise).
-export async function fetchLessons(store, cwd, { now = Date.now(), scope: scopeOverride = null } = {}) {
+export async function fetchLessons(
+  store,
+  cwd,
+  { now = Date.now(), scope: scopeOverride = null, loopCap = SESSION_START_LOOP_CAP, branchHint = true } = {},
+) {
   const scope = scopeOverride || deriveScope(cwd);
   // Issued BEFORE the per-scope read loop and awaited after it. Nothing in the
   // inventory depends on the loop, so awaiting it afterwards would cost a
@@ -197,11 +203,12 @@ export async function fetchLessons(store, cwd, { now = Date.now(), scope: scopeO
   // objective, and scored with different options those would not line up with the
   // sorted order. `k` is diversification-only; `scopeOrder` is ranking-only and
   // simply ignored by the diversifier's destructuring.
-  const rankOpts = sessionRankOpts(scope, now);
+  const rankOpts = sessionRankOpts(scope, now, { branchHint });
   const ranked = rankLessons(winners, rankOpts);
 
   // AUDIENCE CAP before diversification: no single self-improvement loop may
-  // take more than `SESSION_START_LOOP_CAP` of the injected slots, so a general
+  // take more than `loopCap` (the `hooks.sessionStart.loopCap` option, default
+  // `SESSION_START_LOOP_CAP`) of the injected slots, so a general
   // session is not flooded with one bot's private `loop::<bucket>` bookkeeping.
   // General (non-loop) lessons pass through uncapped — they are what the cap
   // frees room for. Applied to the ranked list so the survivors are each
@@ -217,7 +224,7 @@ export async function fetchLessons(store, cwd, { now = Date.now(), scope: scopeO
   // which the bounded read never fetched. Reaching those is the recency-window
   // limit (the `order=rank` CANDIDATE_LIMIT problem, one scope down), not this
   // cap's to solve; the cap still does its job of unflooding across scopes.
-  const capped = capPerBucket(ranked, { cap: SESSION_START_LOOP_CAP, bucketOf: loopBucketOf });
+  const capped = capPerBucket(ranked, { cap: loopCap, bucketOf: loopBucketOf });
 
   // ── the scope map: EXACT counts when the store can enumerate ───────────────
   //
@@ -587,9 +594,12 @@ export function branchQueryTerms(scope) {
 // the branch never matched. `fetchLessons` feeds the ONE object this returns to
 // both `rankLessons` and (spread) the diversifier, so their scores agree on
 // terms and the clock.
-export function sessionRankOpts(scope, now) {
+export function sessionRankOpts(scope, now, { branchHint = true } = {}) {
   return {
-    terms: branchQueryTerms(scope),
+    // `branchHint: false` (config `hooks.sessionStart.branchHint: off`) restores
+    // the pre-branch-query read — no terms, so relevance contributes nothing and
+    // the order is recency + salience.
+    terms: branchHint ? branchQueryTerms(scope) : [],
     now,
     scopeOrder: scope && scope.readOrder ? scope.readOrder : null,
   };

package/src/deeplink-pure.mjs

@@ -36,7 +36,7 @@ export const LORE_PARAM_DEFAULTS = {
   // accepts ISO instants in that arm and a relative { preset: '7d' } arm
   // (packages/web/src/lib/time-range.ts); neither has a CLI flag yet.
   range: null,
-  owner: 'all', // 'all' | 'personal' | { orgId }
+  owner: 'all', // 'all' | 'personal' | '<org-slug>' — folds into an owner filter (00064)
   // Filter[] | null — the Explorer's multi-dimension filter bar (label / agent /
   // trigger / repo / branch / pr). `null`, NOT `[]`, is the default on purpose:
   // the app has to tell "the param is absent" from "the bar is explicitly
@@ -46,7 +46,6 @@ export const LORE_PARAM_DEFAULTS = {
   // "unfiltered".
   filters: null,
   tags: [], // string[] — legacy label filter (AND across labels); [] means "no filter". Still READ by the app, superseded by `filters`
-  view: 'scope', // 'scope' | 'time'
   // 'active' | 'archived' | 'expiring' | null — the Explorer's Status control.
   // `null`, NOT 'active', is the default for `filters`' reason: the app has to
   // tell "absent" from an explicit choice, because an absent `status` falls back
@@ -60,9 +59,9 @@ export const LORE_PARAM_DEFAULTS = {
 
 // A stable, readable param order (also makes URLs deterministic for tests).
 // Mirrors the `useUrlState` call order in `LoreExplorer.tsx` (+ the `lesson`
-// param last), so `filters` and `tags` sit between `owner` and `view`. `scope`
+// param last), so `filters` and `tags` sit between `owner` and `status`. `scope`
 // precedes `lesson` so a lesson link reads `?scope=…&lesson=…`.
-const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'filters', 'tags', 'view', 'status', 'archived', 'lesson'];
+const PARAM_ORDER = ['scope', 'q', 'range', 'owner', 'filters', 'tags', 'status', 'archived', 'lesson'];
 
 // Strip trailing slashes from a base URL, falling back to the default when the
 // input is empty/absent. Pure.
@@ -148,18 +147,18 @@ export { resolveScopeArg, resolveScopeKeyArgs, isScopeString, scopeIssue } from
 
 // ── Flag → param coercion (pure, shared by the `link` command) ────────────────
 
-// Coerce the `--owner` flag to an `OwnerFilter`: 'all' (default) / 'personal' /
-// any other non-empty string → `{ orgId }`. Pure.
+// Coerce the `--owner` flag to the legacy `owner` param value: `personal`, an
+// org SLUG, or `all` (default → omitted). Returns the STRING the app folds into
+// an owner filter (`filtersFromLegacyOwner`) when the `filters` param is absent
+// — which is why the CLI keeps writing the legacy param rather than `filters`:
+// `owner` and the legacy `tags` param fold together, so `--owner acme --tags
+// perf` yields BOTH, whereas a `filters` param would make the app ignore the
+// legacy tags. NOT the old `{orgId}` OBJECT: the owner facet keys on the SLUG,
+// and the app cannot resolve a uuid to a slug in this pure path, so the object
+// form silently dropped the filter it named (00064). A slug lands verbatim. Pure.
 export function parseOwnerArg(owner) {
-  if (typeof owner !== 'string' || !owner || owner === 'all') return 'all';
-  if (owner === 'personal') return 'personal';
-  return { orgId: owner };
-}
-
-// Coerce the `--view` flag to a `ViewMode`: only 'time' is non-default; anything
-// else (incl. absent/invalid) → 'scope'. Pure.
-export function parseViewArg(view) {
-  return view === 'time' ? 'time' : 'scope';
+  if (typeof owner !== 'string' || !owner) return 'all';
+  return owner;
 }
 
 // Coerce the `--tags` flag to a normalized `string[]` label filter, mirroring the

package/src/hook.mjs

@@ -115,7 +115,10 @@ async function run(args) {
       }
       return 0;
     }
-    const { scope: readScope, lessons, scopeCounts, applicable } = await fetchLessons(store, root);
+    const { scope: readScope, lessons, scopeCounts, applicable } = await fetchLessons(store, root, {
+      loopCap: control.hooksSessionStartLoopCap,
+      branchHint: control.hooksSessionStartBranchHint !== 'off',
+    });
     emit(formatLessons(lessons, readScope, {
       instruction: sessionInstruction,
       mode: control.hooksSessionStart,

package/src/link.mjs

@@ -22,7 +22,6 @@ import {
   buildLoreUrl,
   mostSpecificScope,
   parseOwnerArg,
-  parseViewArg,
   parseRangeArg,
   parseTagsArg,
   resolveScopeKeyArgs,
@@ -55,7 +54,6 @@ export async function link(args) {
   // Filter flags (all optional; each JSON-encoded + default-omitted downstream).
   const q = typeof args.q === 'string' ? args.q : '';
   const owner = parseOwnerArg(args.owner);
-  const view = parseViewArg(args.view);
   const range = parseRangeArg(args);
   const tags = parseTagsArg(args.tags);
   const archived = Boolean(args.archived);
@@ -65,7 +63,6 @@ export async function link(args) {
     (typeof args.scope === 'string' && Boolean(args.scope)) ||
     Boolean(q) ||
     owner !== 'all' ||
-    view !== 'scope' ||
     range !== null ||
     tags.length > 0 ||
     archived;
@@ -84,7 +81,6 @@ export async function link(args) {
   if (q) params.q = q;
   if (owner !== 'all') params.owner = owner;
   if (tags.length) params.tags = tags;
-  if (view !== 'scope') params.view = view;
   if (range !== null) params.range = range;
   if (archived) params.archived = true;