@nanonets/graft 0.23.0 → 0.24.0

package/dist/notes/notes.d.ts

@@ -1,8 +1,14 @@
+import type { NoteHit } from "./find-notes.js";
+import { type LearningFields } from "./learning-fields.js";
+export { findNotes, type NoteHit } from "./find-notes.js";
+export { mentionedFiles, noteTargets, type NoteTarget } from "./targets.js";
+export { commitLines, namesLabel, PR_SPEEDUP, setupCommitLine, TOKEN_CREDIT_FLOOR, tokensLabel, tokensWorthSaying } from "./credit.js";
 export interface NoteCost {
     minutes?: number;
     tokens?: number;
 }
-export interface Note {
+/** A learning. Its id, kind, scope, status and the rest are in `LearningFields`. */
+export interface Note extends LearningFields {
     /** Where the note is: an absolute path on this machine. */
     path: string;
     title: string;
@@ -16,12 +22,14 @@ export interface Note {
     body: string;
     /** Written by someone other than whoever is asking. */
     teammate?: boolean;
-    /** `repo`: in the repo's `.trail/learnings/`, for everyone. `personal`: in ~/.trail, this machine only. */
-    scope?: "repo" | "personal";
     /** A rule or preference for every session here, not knowledge about one
      * task: what the user kept having to tell Claude. The session-start hook
      * lists these up front, since no single task would bring them up. */
     standing?: boolean;
+    /** The file name of an earlier learning this one takes over from. The old
+     * file stays, as the record of what that session knew, but `listNotes`
+     * reads this one instead. */
+    replaces?: string;
     /** Found on a teammate's pushed branch (`origin/kumar/jitter`) rather than in
      * this checkout. `path` is then `<ref>:.trail/learnings/<name>`, readable
      * with `git show`, and the whole body travels with the note. */
@@ -44,7 +52,11 @@ export declare const SECTIONS: readonly [{
     readonly label: "watch out";
 }];
 export declare function renderNote(n: Omit<Note, "path">): string;
-/** A note file, or null when it isn't one (no title in its frontmatter). */
+/**
+ * A note file, or null when it isn't one (no title in its frontmatter), or
+ * when its front matter is refused (anchors, aliases, a list for a title) or
+ * isn't valid YAML, which says so once on stderr.
+ */
 export declare function parseNote(text: string, path: string): Note | null;
 /** The file name a note is known by, wherever it sits: one learning on a branch and in the tree is one learning. */
 export declare function noteName(n: Note): string;
@@ -75,65 +87,32 @@ export interface WriteNoteInput {
     cost?: NoteCost;
     touches?: string[];
     standing?: boolean;
+    /** The fields a new learning may be given; its id, status and scope come from where it is written. */
+    kind?: LearningFields["kind"];
+    replaces?: string;
+    src?: LearningFields["src"];
+    evidence?: string;
+    /** Personal only: defaults to this repo. */
+    applies?: string;
 }
 /**
  * Write a new learning for the repo `dir` is in, and return it: into the
  * repo's `.trail/learnings/` (made if needed), or with `scope: "personal"`,
  * or outside git, into ~/.trail. Never overwrites: a second one with the same
- * name on the same day gets `-2`, `-3`.
+ * name on the same day gets `-2`, `-3`. Its id is 8 hex digits from the file
+ * name it gets (`newLearningId`), written into the file.
  */
 export declare function writeNote(dir: string, input: WriteNoteInput, scope?: LearningScope): Note;
 /**
  * The standing learnings for `dir`: the team's in the checkout and the
  * person's own, never ones on a teammate's unmerged branch, which nobody has
- * reviewed yet.
+ * reviewed yet, and only live ones (nothing retired or replaced).
  */
 export declare function standingLearnings(dir: string): Note[];
 /** Where a learning is, as the agent and the person read it: `.trail/learnings/x.md`, `~/.trail/…`, or `origin/b:.trail/…`. */
 export declare function notePlace(n: Note): string;
-export interface NoteTarget {
-    /** A folder in the repo the note goes to. */
-    dir: string;
-    /** What the session touched there, relative to the top of that checkout. */
-    touches: string[];
-}
-/**
- * Which repos a session's note belongs in, and what it touched in each.
- *
- * The repo the note was saved from gets the files it has uncommitted or
- * committed since `since`. Every other repo the session edited (`edited`:
- * absolute paths, from the agent's transcript) gets the note too, with its
- * own files, so a session that changed a backend and the library it calls
- * leaves a note in both. Saved from a folder that holds several repos, the
- * note goes to each repo the session changed, or stays with the folder when
- * it changed none. Two worktrees of one repo are one repo.
- */
-export declare function noteTargets(dir: string, edited?: string[], since?: number): NoteTarget[];
-/**
- * Files of the checkout at `dir` that a note's text names by path. A session
- * that only read code edits nothing, so without these its note would touch no
- * file, and nothing that looks a note up by file (`trail check`, the ranked
- * search) would ever find it.
- */
-export declare function mentionedFiles(dir: string, body: string): string[];
-export interface NoteHit {
-    note: Note;
-    score: number;
-    /** Files the note touches that this query's results also point into. */
-    shared: string[];
-}
-/**
- * The notes worth showing next to a query's results: ones whose title or body
- * share the query's words, or that touch a file the results point into. At
- * most `limit`, best first. A note has to clear a bar — two of the query's
- * words, or one in its title, or a shared file — so an unrelated note never
- * rides along just because it exists.
- */
-export declare function findNotes(notes: Note[], query: string, files?: string[], limit?: number): NoteHit[];
 /** `2026-10-07` → `Oct 7`; anything else as it came. */
 export declare function shortDate(date: string): string;
-/** `~9.6k tokens`, `~600 tokens`. */
-export declare function tokensLabel(n: number): string;
 /** `took 12 min and ~9.6k tokens to work out`, or null when the note has no cost. */
 export declare function costLabel(cost?: NoteCost): string | null;
 /** What reading a note costs an agent, in tokens: its text at ~4 characters a token. */
@@ -143,7 +122,7 @@ export declare function readingTokens(n: Note): number;
  * it costs. 0 when it carries no token cost, or reading it costs as much.
  */
 export declare function savedByNote(n: Note): number;
-/** `Anirudh's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
+/** `Maya's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
 export declare function whoseLearning(n: Note): string;
 /**
  * The block `ask` prints above its results: whose learning each is, when,
@@ -151,39 +130,12 @@ export declare function whoseLearning(n: Note): string;
  * where to read the rest. A learning on a teammate's unmerged branch says so,
  * with the `git show` that prints it, since there's no file here to open. An agent
  * relays the cost when it says what the turn saved, which is how the saving
- * becomes countable.
+ * becomes countable. Every field is flattened to one line: a learning's text
+ * comes from whoever wrote it, and a line of its own could pass for trail's.
  */
 export declare function formatNoteHits(hits: NoteHit[]): string[];
 /** The line an agent closes its reply with after saving a learning just for the user. */
 export declare const PERSONAL_SAVED_LINE = "\uD83D\uDCDD Saved just for you \u00B7 stays on this machine, out of the repo";
-/** `Anay`, `Anay and Rushil`, `Anay, Rushil and 3 others`. */
-export declare function namesLabel(names: string[]): string;
-/** What starting from a teammate's learning is worth when its tokens are too few to say: time to a PR. */
-export declare const PR_SPEEDUP = "3x faster";
-/**
- * Below this many tokens, what a learning saves is too small a number to
- * impress, so trail credits it as a faster PR instead.
- */
-export declare const TOKEN_CREDIT_FLOOR = 80000;
-/** Whether a token count is big enough to be the credit. */
-export declare function tokensWorthSaying(tokens: number | undefined): boolean;
-/**
- * The lines that close a reply after a team learning is saved, one for each
- * way the turn can end, since only the agent knows whether it committed the
- * learning by then. Uncommitted, it makes the case for committing: who else
- * works on the same files, and the head start their agents would get, which
- * is what the learning took to work out, or a faster PR when that's small.
- */
-export declare function commitLines(note: Pick<Note, "cost">, teammates: string[], where?: "files" | "repo"): {
-    committed: string;
-    uncommitted: string;
-};
-/**
- * The line asking for trail's shared setup to be committed, once: `.trail/`
- * and the SessionStart entry in `.claude/settings.json` are what let a
- * teammate's Claude read the learnings before they install anything.
- */
-export declare function setupCommitLine(teammates: string[]): string;
 /**
  * What starting from these learnings is worth, for the agent's closing line:
  * the tokens they saved, less what reading them costs, when that's worth

package/dist/notes/notes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/notes/notes.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"notes.d.ts","sourceRoot":"","sources":["../../src/notes/notes.ts"],"names":[],"mappings":"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"}

package/dist/notes/notes.js

@@ -17,13 +17,19 @@
  * source files or prompts into it.
  */
 import { readdirSync, readFileSync, existsSync, writeFileSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, join, relative, resolve, sep } from "node:path";
-import { matter } from "../util/front-matter.js";
+import { join, relative, resolve, sep } from "node:path";
+import { matter, textList, warnSkipped } from "../util/front-matter.js";
 import { readBranchCache } from "./branches.js";
-import { changedFiles, ownPath } from "./git-facts.js";
-import { checkoutRoot, childCheckouts, ensureRepoHome, notePlaces, repoPlace, shownPath } from "./home.js";
+import { PR_SPEEDUP, tokensLabel, tokensWorthSaying } from "./credit.js";
+import { flatLine } from "./flatten.js";
+import { ensureRepoHome, notePlaces, shownPath } from "./home.js";
+import { LEARNING_KEYS, learningFileName, liveLearnings, newLearningId, readLearningFields } from "./learning-fields.js";
 import { ensureRepoTrail, LEARNINGS_DIR, learningsDir } from "./repo-trail.js";
+import { TOUCH_CHARS, TOUCH_LIMIT } from "./targets.js";
+// Where a learning goes, which to show for a query and how one is credited live in their own files.
+export { findNotes } from "./find-notes.js";
+export { mentionedFiles, noteTargets } from "./targets.js";
+export { commitLines, namesLabel, PR_SPEEDUP, setupCommitLine, TOKEN_CREDIT_FLOOR, tokensLabel, tokensWorthSaying } from "./credit.js";
 /** The three sections a note is written under. Notes may have others; these are the ones `ask` quotes. */
 export const SECTIONS = [
     { key: "decided", heading: "Decided", label: "decided" },
@@ -50,6 +56,10 @@ export function renderNote(n) {
         fm.push(`cost: { ${cost.join(", ")} }`);
     if (n.standing)
         fm.push("standing: true");
+    // Evidence is free text, always quoted so YAML never reads "12" back as a number.
+    for (const k of LEARNING_KEYS)
+        if (n[k])
+            fm.push(`${k}: ${k === "evidence" ? JSON.stringify(n[k]) : scalar(n[k])}`);
     if (n.touches.length)
         fm.push("touches:", ...n.touches.map((t) => `  - ${scalar(t)}`));
     fm.push("---", "");
@@ -58,32 +68,47 @@ export function renderNote(n) {
 function num(v) {
     return typeof v === "number" && Number.isFinite(v) ? v : undefined;
 }
-/** A note file, or null when it isn't one (no title in its frontmatter). */
+/** Front matter keys that hold one value: a list or a map under one refuses the file. */
+const NOTE_SCALARS = ["title", "author", "date", "branch"];
+/**
+ * A note file, or null when it isn't one (no title in its frontmatter), or
+ * when its front matter is refused (anchors, aliases, a list for a title) or
+ * isn't valid YAML, which says so once on stderr.
+ */
 export function parseNote(text, path) {
     let parsed;
     try {
-        parsed = matter(text);
+        parsed = matter(text, { scalars: NOTE_SCALARS });
     }
     catch {
+        // The parser's own message quotes the file; the warning names it instead.
+        warnSkipped("the learning", path, "its front matter isn't valid YAML");
+        return null;
+    }
+    if (parsed.refused) {
+        warnSkipped("the learning", path, parsed.refused);
         return null;
     }
     const d = parsed.data;
-    if (typeof d.title !== "string" || !d.title.trim())
+    // Title, author and date reach what agents read: one line each (flatten.ts).
+    const title = typeof d.title === "string" ? flatLine(d.title) : "";
+    if (!title)
         return null;
-    const date = d.date instanceof Date ? d.date.toISOString().slice(0, 10) : String(d.date ?? "");
+    const date = d.date instanceof Date ? d.date.toISOString().slice(0, 10) : flatLine(d.date, 40);
     const cost = (d.cost ?? {});
     const minutes = num(cost.minutes);
     const tokens = num(cost.tokens);
     return {
         path,
-        title: d.title.trim(),
-        author: typeof d.author === "string" ? d.author : "",
+        title,
+        author: typeof d.author === "string" ? flatLine(d.author, 80) : "",
         date,
         branch: typeof d.branch === "string" ? d.branch : undefined,
         cost: minutes !== undefined || tokens !== undefined ? { minutes, tokens } : undefined,
-        touches: Array.isArray(d.touches) ? d.touches.map(String) : [],
+        touches: textList(d.touches, TOUCH_LIMIT, TOUCH_CHARS),
         body: parsed.content.trim(),
         ...(d.standing === true ? { standing: true } : {}),
+        ...readLearningFields(d, learningFileName(path)),
     };
 }
 /** A touch saved relative to `checkout`, as a path relative to `here`. */
@@ -118,7 +143,7 @@ function readNotesIn(notesDir, checkout, here, scope) {
 }
 /** The file name a note is known by, wherever it sits: one learning on a branch and in the tree is one learning. */
 export function noteName(n) {
-    return n.path.slice(Math.max(n.path.lastIndexOf("/"), n.path.lastIndexOf(":")) + 1);
+    return learningFileName(n.path);
 }
 /**
  * Every learning that bears on the folder `dir`, newest first: the repo's
@@ -153,7 +178,7 @@ export function listNotes(dir, opts = {}) {
     }
     return out.sort((a, b) => (a.date === b.date ? b.path.localeCompare(a.path) : b.date.localeCompare(a.date)));
 }
-/** The learnings on teammates' pushed branches, from the branch cache. */
+/** The learnings on teammates' pushed branches, from the branch cache. One that won't read is skipped, never the rest. */
 function branchNotes(checkout, here) {
     const cache = readBranchCache(checkout);
     if (!cache)
@@ -161,9 +186,15 @@ function branchNotes(checkout, here) {
     const out = [];
     for (const b of cache.branches) {
         for (const l of b.learnings) {
-            const n = parseNote(l.text, `${b.ref}:${LEARNINGS_DIR}/${l.name}`);
-            if (n)
-                out.push({ ...n, scope: "repo", ref: b.ref, touches: n.touches.map((t) => rebaseTouch(t, checkout, here)) });
+            const where = `${b.ref}:${LEARNINGS_DIR}/${l.name}`;
+            try {
+                const n = parseNote(l.text, where);
+                if (n)
+                    out.push({ ...n, scope: "repo", ref: b.ref, touches: n.touches.map((t) => rebaseTouch(t, checkout, here)) });
+            }
+            catch (e) {
+                warnSkipped("the learning", where, e instanceof Error ? e.message : String(e));
+            }
         }
     }
     return out;
@@ -198,7 +229,8 @@ export function slug(s, words = 6) {
  * Write a new learning for the repo `dir` is in, and return it: into the
  * repo's `.trail/learnings/` (made if needed), or with `scope: "personal"`,
  * or outside git, into ~/.trail. Never overwrites: a second one with the same
- * name on the same day gets `-2`, `-3`.
+ * name on the same day gets `-2`, `-3`. Its id is 8 hex digits from the file
+ * name it gets (`newLearningId`), written into the file.
  */
 export function writeNote(dir, input, scope = "repo") {
     const { place } = ensureRepoHome(dir);
@@ -215,16 +247,17 @@ export function writeNote(dir, input, scope = "repo") {
     let name = `${base}.md`;
     for (let i = 2; existsSync(join(notes, name)); i++)
         name = `${base}-${i}.md`;
+    // One line each, as every reader would show them (flatten.ts): what's written reads back the same.
     const note = {
-        title: input.title.trim(),
-        author: input.author,
+        title: flatLine(input.title),
+        author: flatLine(input.author, 80),
         date: input.date,
         branch: input.branch,
         cost: input.cost,
         touches: input.touches ?? [],
         body: input.body,
-        scope: inRepo ? "repo" : "personal",
         ...(input.standing ? { standing: true } : {}),
+        ...readLearningFields({ ...input, id: newLearningId(name), scope: inRepo ? "repo" : "personal", applies: inRepo ? undefined : (input.applies ?? place.key), status: "active" }, name),
     };
     writeFileSync(join(notes, name), renderNote(note));
     return { ...note, path: join(notes, name) };
@@ -232,10 +265,10 @@ export function writeNote(dir, input, scope = "repo") {
 /**
  * The standing learnings for `dir`: the team's in the checkout and the
  * person's own, never ones on a teammate's unmerged branch, which nobody has
- * reviewed yet.
+ * reviewed yet, and only live ones (nothing retired or replaced).
  */
 export function standingLearnings(dir) {
-    return listNotes(dir, { branches: false }).filter((n) => n.standing && !n.ref);
+    return liveLearnings(listNotes(dir, { branches: false })).filter((n) => n.standing && !n.ref);
 }
 /** Where a learning is, as the agent and the person read it: `.trail/learnings/x.md`, `~/.trail/…`, or `origin/b:.trail/…`. */
 export function notePlace(n) {
@@ -246,122 +279,6 @@ export function notePlace(n) {
     const at = path.lastIndexOf(`/${LEARNINGS_DIR}/`);
     return at === -1 ? shownPath(n.path) : path.slice(at + 1);
 }
-/** Most files one note lists per repo. */
-const TOUCH_LIMIT = 10;
-/**
- * Which repos a session's note belongs in, and what it touched in each.
- *
- * The repo the note was saved from gets the files it has uncommitted or
- * committed since `since`. Every other repo the session edited (`edited`:
- * absolute paths, from the agent's transcript) gets the note too, with its
- * own files, so a session that changed a backend and the library it calls
- * leaves a note in both. Saved from a folder that holds several repos, the
- * note goes to each repo the session changed, or stays with the folder when
- * it changed none. Two worktrees of one repo are one repo.
- */
-export function noteTargets(dir, edited = [], since) {
-    const here = repoPlace(dir);
-    const byKey = new Map();
-    const add = (checkout, files) => {
-        const key = repoPlace(checkout).key;
-        const entry = byKey.get(key) ?? { dir: checkout, files: [] };
-        for (const f of files)
-            if (f && !ownPath(f) && !entry.files.includes(f))
-                entry.files.push(f);
-        byKey.set(key, entry);
-    };
-    if (here.git)
-        add(here.checkout, changedFiles(here.checkout, since));
-    else if (edited.length === 0)
-        for (const c of childCheckouts(here.checkout))
-            add(c, changedFiles(c, since));
-    // The agent's own files (memory, plans, scratch under ~/.claude) aren't what a note is about.
-    const agentFiles = join(homedir(), ".claude") + sep;
-    for (const f of edited) {
-        if (f.startsWith(agentFiles))
-            continue;
-        const top = checkoutRoot(dirname(f));
-        if (top)
-            add(top, [relative(top, f).split(sep).join("/")]);
-        else if (!here.git && !relative(here.checkout, f).startsWith(".."))
-            add(here.checkout, [relative(here.checkout, f).split(sep).join("/")]);
-    }
-    const out = [...byKey.entries()]
-        .filter(([key, e]) => e.files.length > 0 || key === here.key)
-        .map(([, e]) => ({ dir: e.dir, touches: e.files.slice(0, TOUCH_LIMIT) }));
-    // The repo it was saved from first; a folder of repos only when nothing else was touched.
-    out.sort((a, b) => Number(repoPlace(b.dir).key === here.key) - Number(repoPlace(a.dir).key === here.key));
-    const touched = out.filter((t) => t.touches.length > 0);
-    if (!here.git && touched.length > 0)
-        return touched;
-    return out.length ? out : [{ dir: here.checkout, touches: [] }];
-}
-/** A path-shaped word in a note: `client.go`, `src/a/b.ts:12-30`, `x.go#Fn`. */
-const MENTION = /(?:^|[\s(`'"\[])((?:[\w.-]+\/)*[\w-][\w.-]*\.[A-Za-z][A-Za-z0-9]{0,5})(?=$|[\s:#)`'",.;\]])/gm;
-/**
- * Files of the checkout at `dir` that a note's text names by path. A session
- * that only read code edits nothing, so without these its note would touch no
- * file, and nothing that looks a note up by file (`trail check`, the ranked
- * search) would ever find it.
- */
-export function mentionedFiles(dir, body) {
-    const out = [];
-    for (const m of body.matchAll(MENTION)) {
-        const f = m[1].replace(/^\.\//, "");
-        if (out.includes(f) || ownPath(f) || f.startsWith(".."))
-            continue;
-        if (existsSync(join(dir, f)))
-            out.push(f);
-        if (out.length >= TOUCH_LIMIT)
-            break;
-    }
-    return out;
-}
-/* -------------------------------------------------------------------------- */
-/* finding the notes that matter for a query                                  */
-/* -------------------------------------------------------------------------- */
-const STOP = new Set("the and for with from that this what when where which into does how why are was were not but you your our out its it's can should would could about after before over under use using used fix find make".split(" "));
-function terms(s) {
-    return [...new Set(s.toLowerCase().split(/[^a-z0-9_]+/).filter((t) => t.length >= 3 && !STOP.has(t)))];
-}
-/** The file part of a `file#Symbol` touch. */
-function touchFile(t) {
-    return t.split("#")[0];
-}
-/**
- * The notes worth showing next to a query's results: ones whose title or body
- * share the query's words, or that touch a file the results point into. At
- * most `limit`, best first. A note has to clear a bar — two of the query's
- * words, or one in its title, or a shared file — so an unrelated note never
- * rides along just because it exists.
- */
-export function findNotes(notes, query, files = [], limit = 2) {
-    const q = terms(query);
-    const hitFiles = new Set(files);
-    const out = [];
-    for (const note of notes) {
-        const title = new Set(terms(note.title));
-        const text = new Set(terms(`${note.body} ${note.touches.join(" ")}`));
-        let score = 0;
-        let matched = 0;
-        for (const t of q) {
-            if (title.has(t)) {
-                score += 3;
-                matched++;
-            }
-            else if (text.has(t)) {
-                score += 1;
-                matched++;
-            }
-        }
-        const shared = [...new Set(note.touches.map(touchFile))].filter((f) => hitFiles.has(f));
-        score += shared.length * 4;
-        const clears = shared.length > 0 || matched >= 2 || [...title].some((t) => q.includes(t));
-        if (clears && score >= 3)
-            out.push({ note, score, shared });
-    }
-    return out.sort((a, b) => b.score - a.score || b.note.date.localeCompare(a.note.date)).slice(0, limit);
-}
 /* -------------------------------------------------------------------------- */
 /* how a note reads inside a query's output                                   */
 /* -------------------------------------------------------------------------- */
@@ -373,12 +290,6 @@ export function shortDate(date) {
         return date;
     return `${MONTHS[Number(m[2]) - 1] ?? m[2]} ${Number(m[3])}`;
 }
-/** `~9.6k tokens`, `~600 tokens`. */
-export function tokensLabel(n) {
-    if (n >= 1000)
-        return `~${(n / 1000).toFixed(n >= 10_000 ? 0 : 1).replace(/\.0$/, "")}k tokens`;
-    return `~${n} tokens`;
-}
 /** `took 12 min and ~9.6k tokens to work out`, or null when the note has no cost. */
 export function costLabel(cost) {
     if (!cost)
@@ -394,9 +305,6 @@ export function costLabel(cost) {
 function shellQuote(s) {
     return `'${s.replace(/'/g, `'\\''`)}'`;
 }
-function clip(s, n = 88) {
-    return s.length > n ? `${s.slice(0, n - 1).trimEnd()}…` : s;
-}
 /** What reading a note costs an agent, in tokens: its text at ~4 characters a token. */
 export function readingTokens(n) {
     return Math.ceil(renderNote(n).length / 4);
@@ -409,10 +317,11 @@ export function savedByNote(n) {
     const took = n.cost?.tokens ?? 0;
     return Math.max(0, took - readingTokens(n));
 }
-/** `Anirudh's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
+/** `Maya's learning`, `a learning`, `Kumar's learning on kumar/jitter`. */
 export function whoseLearning(n) {
-    const who = n.author ? `${n.author}'s learning` : "a learning";
-    return n.ref ? `${who} on ${n.ref.replace(/^origin\//, "")}` : who;
+    const author = flatLine(n.author, 80);
+    const who = author ? `${author}'s learning` : "a learning";
+    return n.ref ? `${who} on ${flatLine(n.ref.replace(/^origin\//, ""), 80)}` : who;
 }
 /**
  * The block `ask` prints above its results: whose learning each is, when,
@@ -420,103 +329,35 @@ export function whoseLearning(n) {
  * where to read the rest. A learning on a teammate's unmerged branch says so,
  * with the `git show` that prints it, since there's no file here to open. An agent
  * relays the cost when it says what the turn saved, which is how the saving
- * becomes countable.
+ * becomes countable. Every field is flattened to one line: a learning's text
+ * comes from whoever wrote it, and a line of its own could pass for trail's.
  */
 export function formatNoteHits(hits) {
     const lines = [];
     for (const { note } of hits) {
-        const who = `${note.author ? `${note.author}'s learning` : "a learning"}${note.teammate ? ", a teammate's" : ""}`;
-        lines.push(`from ${who} · ${shortDate(note.date)} · ${note.title}`);
+        const author = flatLine(note.author, 80);
+        const who = `${author ? `${author}'s learning` : "a learning"}${note.teammate ? ", a teammate's" : ""}`;
+        lines.push(`from ${who} · ${flatLine(shortDate(note.date), 40)} · ${flatLine(note.title)}`);
         const cost = costLabel(note.cost);
         for (const s of SECTIONS) {
             const lead = sectionLead(note.body, s.heading);
             if (lead)
-                lines.push(`  ${s.label.padEnd(11)} ${clip(lead)}`);
+                lines.push(`  ${s.label.padEnd(11)} ${flatLine(lead, 88)}`);
         }
         if (note.ref) {
             // On a teammate's branch, not reviewed yet: where to read the rest, and that it's unmerged.
-            lines.push(`  on ${note.ref.replace(/^origin\//, "")}, pushed and not merged yet · git show ${shellQuote(note.path)}${cost ? ` · ${cost}` : ""}`);
+            const ref = flatLine(note.ref.replace(/^origin\//, ""), 80);
+            lines.push(`  on ${ref}, pushed and not merged yet · git show ${shellQuote(flatLine(note.path, 300))}${cost ? ` · ${cost}` : ""}`);
             lines.push("");
             continue;
         }
-        lines.push(`  ${notePlace(note)}${cost ? ` · ${cost}` : ""}`);
+        lines.push(`  ${flatLine(notePlace(note), 300)}${cost ? ` · ${cost}` : ""}`);
         lines.push("");
     }
     return lines;
 }
 /** The line an agent closes its reply with after saving a learning just for the user. */
 export const PERSONAL_SAVED_LINE = "📝 Saved just for you · stays on this machine, out of the repo";
-/** `Anay`, `Anay and Rushil`, `Anay, Rushil and 3 others`. */
-export function namesLabel(names) {
-    if (names.length <= 2)
-        return names.join(" and ");
-    if (names.length === 3)
-        return `${names[0]}, ${names[1]} and ${names[2]}`;
-    return `${names[0]}, ${names[1]} and ${names.length - 2} others`;
-}
-/** `48k`, `3.8k`, `600`. */
-function tokensShort(n) {
-    return tokensLabel(n).replace(/^~/, "").replace(" tokens", "");
-}
-/** What starting from a teammate's learning is worth when its tokens are too few to say: time to a PR. */
-export const PR_SPEEDUP = "3x faster";
-/**
- * Below this many tokens, what a learning saves is too small a number to
- * impress, so trail credits it as a faster PR instead.
- */
-export const TOKEN_CREDIT_FLOOR = 80_000;
-/** Whether a token count is big enough to be the credit. */
-export function tokensWorthSaying(tokens) {
-    return (tokens ?? 0) >= TOKEN_CREDIT_FLOOR;
-}
-/**
- * The lines that close a reply after a team learning is saved, one for each
- * way the turn can end, since only the agent knows whether it committed the
- * learning by then. Uncommitted, it makes the case for committing: who else
- * works on the same files, and the head start their agents would get, which
- * is what the learning took to work out, or a faster PR when that's small.
- */
-export function commitLines(note, teammates, where = "files") {
-    const tokens = note.cost?.tokens;
-    const short = tokensWorthSaying(tokens) ? tokensShort(tokens) : null;
-    // "an 80k-token", "an 11k-token": said aloud, they start with a vowel.
-    const start = short ? `${/^8|^1[18]k$/.test(short) ? "an" : "a"} ${short}-token head start` : null;
-    const place = where === "files" ? "this part of the codebase" : "this repo";
-    if (!teammates.length) {
-        return start
-            ? {
-                committed: `📝 Committed · your teammates' agents now get ${start}`,
-                uncommitted: `🌱 Commit what you learned and give your teammates' agents ${start}`,
-            }
-            : {
-                committed: `📝 Committed · your teammates' agents now get to a PR ${PR_SPEEDUP}`,
-                uncommitted: `🌱 Commit what you learned and your teammates' agents get to a PR ${PR_SPEEDUP}`,
-            };
-    }
-    const who = namesLabel(teammates);
-    const work = teammates.length === 1 ? "works" : "work";
-    return start
-        ? {
-            committed: `📝 Committed · ${who} ${work} in ${place}, and their agents now get ${start}`,
-            uncommitted: `🌱 ${who} ${work} in ${place}. Commit what you learned and give their agents ${start}`,
-        }
-        : {
-            committed: `📝 Committed · ${who} ${work} in ${place}, and their agents now get to a PR ${PR_SPEEDUP}`,
-            uncommitted: `🌱 ${who} ${work} in ${place}. Commit what you learned and their agents get to a PR ${PR_SPEEDUP}`,
-        };
-}
-/**
- * The line asking for trail's shared setup to be committed, once: `.trail/`
- * and the SessionStart entry in `.claude/settings.json` are what let a
- * teammate's Claude read the learnings before they install anything.
- */
-export function setupCommitLine(teammates) {
-    const ask = "Commit .trail/ and .claude/settings.json once";
-    if (!teammates.length)
-        return `🌱 ${ask}, and your teammates' Claude starts from your learnings, even before they install trail`;
-    const work = teammates.length === 1 ? "works" : "work";
-    return `🌱 ${namesLabel(teammates)} ${work} in this repo. ${ask}, and their Claude starts from your learnings, even before they install trail`;
-}
 /**
  * What starting from these learnings is worth, for the agent's closing line:
  * the tokens they saved, less what reading them costs, when that's worth