feat: trail, with learnings in .trail/, a local check, and workspaces

.claude/helpers/graft-hooks.cjs

@@ -1,19 +1,68 @@
 #!/usr/bin/env node
 const path = require('path');
 const fs = require('fs');
+const os = require('os');
 const { pathToFileURL } = require('url');
 const { execFileSync } = require('child_process');
 const dir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const BAKED = "/Users/shrishdwivedi/Documents/Context graphs/context-graph-engine/dist/claude";
 
-// The dist/claude dir of @nanonets/graft resolved from a base whose node_modules is searched.
-function fromPkg(base) {
+// The same code ships as @trailhq/trail and as @nanonets/graft, its old name;
+// either one answers, and the newer wins.
+const PKGS = ['@trailhq/trail', '@nanonets/graft'];
+const BINS = process.platform === 'win32' ? ['trail.cmd', 'graft.cmd'] : ['trail', 'graft'];
+
+// The dist/claude dir this machine's last init ran from, kept in the trail home
+// rather than in this committed file. Only a file we own and no one else can
+// write: it names code we import.
+function remembered() {
   try {
-    const pkg = require.resolve('@nanonets/graft/package.json', { paths: [base] });
-    return path.join(path.dirname(pkg), 'dist', 'claude');
+    const home = process.env.TRAIL_HOME ? path.resolve(process.env.TRAIL_HOME) : path.join(os.homedir(), '.trail');
+    const file = path.join(home, "install.json");
+    const st = fs.statSync(file);
+    if (process.getuid && (st.uid !== process.getuid() || (st.mode & 0o022))) return null;
+    const d = JSON.parse(fs.readFileSync(file, 'utf8')).claudeDist;
+    return typeof d === 'string' && path.isAbsolute(d) ? d : null;
   } catch { return null; }
 }
 
+// The dist/claude dir of each package resolved from a base whose node_modules is searched.
+function fromPkg(base) {
+  return PKGS.map((name) => {
+    try {
+      const pkg = require.resolve(name + '/package.json', { paths: [base] });
+      return path.join(path.dirname(pkg), 'dist', 'claude');
+    } catch { return null; }
+  });
+}
+
+// The dist/claude dir of the package a file belongs to: the nearest package.json
+// above it that names one of PKGS.
+function pkgAbove(file) {
+  for (let d = path.dirname(file), i = 0; i < 6; d = path.dirname(d), i++) {
+    try {
+      if (PKGS.includes(JSON.parse(fs.readFileSync(path.join(d, 'package.json'), 'utf8')).name)) return path.join(d, 'dist', 'claude');
+    } catch { /* not this one */ }
+  }
+  return null;
+}
+
+// The package behind each trail/graft command on PATH: the bin is a link into
+// the package (dist/cli.js in older releases, dist/bin/<name>.js now), and a
+// Windows .cmd sits beside the node_modules that holds it.
+function onPath() {
+  const out = [];
+  for (const d of (process.env.PATH || '').split(path.delimiter)) {
+    if (!d || !path.isAbsolute(d)) continue;
+    for (const bin of BINS) {
+      const p = path.join(d, bin);
+      if (!fs.existsSync(p)) continue;
+      try { out.push(pkgAbove(fs.realpathSync(p))); } catch { /* dangling link */ }
+      out.push(...fromPkg(d));
+    }
+  }
+  return out;
+}
+
 // The global node_modules dir per npm (handles Homebrew/Windows/volta). Queried on demand.
 function globalRoot() {
   try {
@@ -22,20 +71,45 @@ function globalRoot() {
   } catch { return null; /* npm unavailable */ }
 }
 
-function candidates() {
-  const out = [];
-  if (BAKED) out.push(BAKED);
-  const local = fromPkg(dir); if (local) out.push(local);
-  const legacy = fromPkg(path.join(path.dirname(process.execPath), '..', 'lib')); if (legacy) out.push(legacy);
-  const gr = globalRoot(); if (gr) out.push(path.join(gr, '@nanonets', 'graft', 'dist', 'claude'));
-  return out;
+// The version of the package a dist/claude dir belongs to, or null if unreadable.
+function versionOf(distClaude) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(distClaude, '..', '..', 'package.json'), 'utf8')).version || null;
+  } catch { return null; }
 }
 
-function entry(name) {
-  for (const d of candidates()) {
-    const f = path.join(d, name);
-    if (fs.existsSync(f)) return f;
+// Numeric-dotted compare of the release part; an unreadable version loses to any known one.
+function newer(a, b) {
+  if (!a) return false;
+  if (!b) return true;
+  const p = (v) => String(v).split('-')[0].split('.').map((n) => Number(n) || 0);
+  const pa = p(a), pb = p(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d > 0;
   }
+  return false;
+}
+
+// The highest-versioned dir in `dirs` that actually contains `name`, or null.
+function best(dirs, name) {
+  let bestDir = null, bestVer = null;
+  for (const d of dirs) {
+    if (!d || !fs.existsSync(path.join(d, name))) continue;
+    const v = versionOf(d);
+    if (bestDir === null || newer(v, bestVer)) { bestDir = d; bestVer = v; }
+  }
+  return bestDir;
+}
+
+function entry(name) {
+  // Cheap candidates first, and only shell out to npm when every one of them misses.
+  const cheap = [remembered(), ...fromPkg(dir), ...fromPkg(path.join(path.dirname(process.execPath), '..', 'lib')), ...onPath()];
+  const hit = best(cheap, name);
+  if (hit) return path.join(hit, name);
+  const gr = globalRoot();
+  const global = gr && best(PKGS.map((p) => path.join(gr, ...p.split('/'), 'dist', 'claude')), name);
+  if (global) return path.join(global, name);
   return path.join(dir, 'dist', 'claude', name); // last-ditch; import will no-op if absent
 }
 

.claude/helpers/graft-statusline.cjs

@@ -1,19 +1,68 @@
 #!/usr/bin/env node
 const path = require('path');
 const fs = require('fs');
+const os = require('os');
 const { pathToFileURL } = require('url');
 const { execFileSync } = require('child_process');
 const dir = process.env.CLAUDE_PROJECT_DIR || process.cwd();
-const BAKED = "/Users/shrishdwivedi/Documents/Context graphs/context-graph-engine/dist/claude";
 
-// The dist/claude dir of @nanonets/graft resolved from a base whose node_modules is searched.
-function fromPkg(base) {
+// The same code ships as @trailhq/trail and as @nanonets/graft, its old name;
+// either one answers, and the newer wins.
+const PKGS = ['@trailhq/trail', '@nanonets/graft'];
+const BINS = process.platform === 'win32' ? ['trail.cmd', 'graft.cmd'] : ['trail', 'graft'];
+
+// The dist/claude dir this machine's last init ran from, kept in the trail home
+// rather than in this committed file. Only a file we own and no one else can
+// write: it names code we import.
+function remembered() {
   try {
-    const pkg = require.resolve('@nanonets/graft/package.json', { paths: [base] });
-    return path.join(path.dirname(pkg), 'dist', 'claude');
+    const home = process.env.TRAIL_HOME ? path.resolve(process.env.TRAIL_HOME) : path.join(os.homedir(), '.trail');
+    const file = path.join(home, "install.json");
+    const st = fs.statSync(file);
+    if (process.getuid && (st.uid !== process.getuid() || (st.mode & 0o022))) return null;
+    const d = JSON.parse(fs.readFileSync(file, 'utf8')).claudeDist;
+    return typeof d === 'string' && path.isAbsolute(d) ? d : null;
   } catch { return null; }
 }
 
+// The dist/claude dir of each package resolved from a base whose node_modules is searched.
+function fromPkg(base) {
+  return PKGS.map((name) => {
+    try {
+      const pkg = require.resolve(name + '/package.json', { paths: [base] });
+      return path.join(path.dirname(pkg), 'dist', 'claude');
+    } catch { return null; }
+  });
+}
+
+// The dist/claude dir of the package a file belongs to: the nearest package.json
+// above it that names one of PKGS.
+function pkgAbove(file) {
+  for (let d = path.dirname(file), i = 0; i < 6; d = path.dirname(d), i++) {
+    try {
+      if (PKGS.includes(JSON.parse(fs.readFileSync(path.join(d, 'package.json'), 'utf8')).name)) return path.join(d, 'dist', 'claude');
+    } catch { /* not this one */ }
+  }
+  return null;
+}
+
+// The package behind each trail/graft command on PATH: the bin is a link into
+// the package (dist/cli.js in older releases, dist/bin/<name>.js now), and a
+// Windows .cmd sits beside the node_modules that holds it.
+function onPath() {
+  const out = [];
+  for (const d of (process.env.PATH || '').split(path.delimiter)) {
+    if (!d || !path.isAbsolute(d)) continue;
+    for (const bin of BINS) {
+      const p = path.join(d, bin);
+      if (!fs.existsSync(p)) continue;
+      try { out.push(pkgAbove(fs.realpathSync(p))); } catch { /* dangling link */ }
+      out.push(...fromPkg(d));
+    }
+  }
+  return out;
+}
+
 // The global node_modules dir per npm (handles Homebrew/Windows/volta). Queried on demand.
 function globalRoot() {
   try {
@@ -22,20 +71,45 @@ function globalRoot() {
   } catch { return null; /* npm unavailable */ }
 }
 
-function candidates() {
-  const out = [];
-  if (BAKED) out.push(BAKED);
-  const local = fromPkg(dir); if (local) out.push(local);
-  const legacy = fromPkg(path.join(path.dirname(process.execPath), '..', 'lib')); if (legacy) out.push(legacy);
-  const gr = globalRoot(); if (gr) out.push(path.join(gr, '@nanonets', 'graft', 'dist', 'claude'));
-  return out;
+// The version of the package a dist/claude dir belongs to, or null if unreadable.
+function versionOf(distClaude) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(distClaude, '..', '..', 'package.json'), 'utf8')).version || null;
+  } catch { return null; }
 }
 
-function entry(name) {
-  for (const d of candidates()) {
-    const f = path.join(d, name);
-    if (fs.existsSync(f)) return f;
+// Numeric-dotted compare of the release part; an unreadable version loses to any known one.
+function newer(a, b) {
+  if (!a) return false;
+  if (!b) return true;
+  const p = (v) => String(v).split('-')[0].split('.').map((n) => Number(n) || 0);
+  const pa = p(a), pb = p(b);
+  for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+    const d = (pa[i] || 0) - (pb[i] || 0);
+    if (d !== 0) return d > 0;
   }
+  return false;
+}
+
+// The highest-versioned dir in `dirs` that actually contains `name`, or null.
+function best(dirs, name) {
+  let bestDir = null, bestVer = null;
+  for (const d of dirs) {
+    if (!d || !fs.existsSync(path.join(d, name))) continue;
+    const v = versionOf(d);
+    if (bestDir === null || newer(v, bestVer)) { bestDir = d; bestVer = v; }
+  }
+  return bestDir;
+}
+
+function entry(name) {
+  // Cheap candidates first, and only shell out to npm when every one of them misses.
+  const cheap = [remembered(), ...fromPkg(dir), ...fromPkg(path.join(path.dirname(process.execPath), '..', 'lib')), ...onPath()];
+  const hit = best(cheap, name);
+  if (hit) return path.join(hit, name);
+  const gr = globalRoot();
+  const global = gr && best(PKGS.map((p) => path.join(gr, ...p.split('/'), 'dist', 'claude')), name);
+  if (global) return path.join(global, name);
   return path.join(dir, 'dist', 'claude', name); // last-ditch; import will no-op if absent
 }
 

.gitignore

@@ -28,3 +28,6 @@ transcripts/
 
 # graft's local repository settings — not committed.
 /.graft/
+
+# The @trailhq/trail package, laid out by scripts/pack-trail.mjs.
+/build/

README.md

@@ -53,6 +53,7 @@
 
 ## Contents
 
+- [Trail quick start](#trail-quick-start): learnings your agent leaves for the next session, and your team's
 - [Quick start](#quick-start)
 - [The problem](#the-problem)
 - [What Graft does](#what-graft-does)
@@ -73,6 +74,32 @@
 
 ---
 
+## Trail quick start
+
+```bash
+npm install -g @trailhq/trail
+trail init
+claude
+```
+
+Install once. `trail init` asks which agents your team uses, builds the code map and wires up Claude Code. Then work the way you always do.
+
+When a session works something out, your agent saves a learning: what it decided, what it ruled out, and what to watch out for. It goes in the repo's `.trail/learnings/`, and you commit it with the change. The next session on that code, yours or a teammate's, gets it back before it starts digging, and ends with a line saying what it saved, like `📝 Started from Anirudh's learning · saved ~27k tokens`. Teammates' Claude reads the learnings even before they install trail, and learnings on a teammate's pushed branch show up before it merges, along with any overlap with your work.
+
+Before a PR, `trail check` compares your change with what the team has learned and flags anything that goes against it. It runs on your machine; nothing to sign in to.
+
+When you want the team's view across repos, your agent offers a link at the end of a reply. Sign in, create a workspace, tick the repos it gets, and invite your team with a link. The team page shows who is learning what, how often learnings are reused, and where work overlaps.
+
+Trying this branch before `@trailhq/trail` is published:
+
+```bash
+git clone -b feat/trail-cloud https://github.com/trailhq/Graft.git trail && cd trail
+npm install && npm run build && node scripts/pack-trail.mjs
+npm install -g ./build/trail
+```
+
+---
+
 ## Quick start
 
 ```bash

TELEMETRY.md

@@ -34,6 +34,7 @@ Every event carries only these common properties:
 | `node_major` | `20` | Major version only |
 | `ci` | `false` | Always false — CI never sends (see below) |
 | `agent_host` | `claude-code` / `cursor` / `mcp` / `cli` | Which surface graft ran under |
+| `cli_name` | `trail` / `graft` | Which of the two names started the process (graft is trail's old name) |
 | `repo_id` | a random UUID | See "How it stays anonymous" |
 
 The events:
@@ -45,12 +46,17 @@ The events:
 | `init_completed` | `agents` (the ids you selected, sorted), `consent` | `graft init` finishes |
 | `build_completed` | `files_bucket`, `langs`, `mode` (`fast`/`deep`), `duration_bucket`, `incremental` | A build succeeds |
 | `build_failed` | `stage`, `code` — both fixed enums | A build throws |
-| `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only) | Any query command |
-| `brain_signup_opened` | `mode` (`terminal`/`agent`) | `graft trail push` on a repo with no brain opens your browser to make one |
-| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`bad_callback`/`stopped`, and for an agent-run push `agent_link_opened`/`still_waiting`/`expired`/`unsupported`), `mode` (`terminal`/`agent`), `duration_bucket` | That handoff ends, one way or the other — for an agent-run push, each of its runs |
+| `query` | `command`, `surface` (`cli`/`mcp`/`hook`), `hit` (`ask` only), `notes` (`0`/`1`/`2`, how many session notes `ask` showed; only in a repo that keeps notes) | Any query command |
+| `brain_signup_opened` | `mode` (`terminal`/`agent`/`nudge`), and for a nudge `command` (`ask`/`note`/`check`) and `wording` (`share`/`learned`) | `graft trail push` on a repo with no brain opens your browser to make one, or a trail command hands the agent a sign-in link to pass on (at most once a session) |
+| `brain_signup_settled` | `outcome` (`linked`/`timed_out`/`bad_callback`/`stopped`, and for an agent-run push `agent_link_opened`/`still_waiting`/`expired`/`unsupported`), `mode` (`terminal`/`agent`/`nudge`), `duration_bucket` | That handoff ends, one way or the other — for an agent-run push, each of its runs; for a nudge, each background wait for the sign-in (`linked`/`timed_out`/`expired`/`unsupported`) |
 | `trail_pulled` | `outcome` (`written`/`already_present`/`nothing_accepted`/`skipped`/`error`/`dry_run`), `kinds` (which kinds of context file were written: `claude_md`, `folder_claude_md`, `agents_md`, `cursor_rule`, `skill`), `files_bucket`, `changes_bucket`, `skipped_bucket`, `suggested_bucket` (every change Trail has suggested for the wired agents' files, whatever became of it) | `graft trail pull` (or `graft claude-md pull`) finishes |
 | `trail_watch_exit` | `reason` (`suggestions`/`accepted`/`timeout`/`refused`/`no_trail`), `suggested_bucket`, `accepted_bucket`, `duration_bucket` (how long it waited) | `graft trail watch` ends |
 | `trail_autopush` | `outcome` (`started`/`skipped`), `reason` when skipped (`disabled`/`no_head`/`head_unchanged`/`throttled`/`spawn_failed`) | A Claude Code or Codex session starts in a repo with a trail attached, and the hook decides whether to refresh it with a background `graft trail push`. Repos without a trail send nothing |
+| `note_saved` | `has_cost` (`true`/`false`), `touches_bucket` (how many files the learning is about, bucketed), `scope` (`repo`/`personal`) | `trail note` saves a learning, in the repo's `.trail/` or on this machine. The title, the text and the paths are never sent |
+| `learning_reused` | `teammate` (`true`/`false`), `saved_tokens_bucket` | `trail ask` shows learnings from earlier sessions. Which ones, and their text, are never sent |
+| `repo_seen` | `trail_committed` (`true`/`false`), `learnings_bucket`, `workspace` (`true`/`false`) | Once a day per repo, when a Claude Code session starts in a repo trail runs in. The repo's name and paths are never sent; it's identified only by the random `repo_id` every event carries |
+| `takeaway_saved` | `new_skill` (`true`/`false`) | `trail learn` saves a correction as a takeaway on a skill, on this machine (`~/.trail/`). Its text is never sent |
+| `skills_folded` | `takeaways_bucket` (how many takeaways were folded, bucketed) | `trail skills fold` writes takeaways into a skill's SKILL.md |
 | `session_summary` | `graft_reads_bucket`, `source_reads_bucket`, `saved_tokens_bucket`, `graft_turns_bucket`, `reported_turns_bucket` | Once, after an agent session ends |
 
 Two rules govern every value above, and both are enforced in code rather than by
@@ -72,7 +78,7 @@ An example event, in full:
   "timestamp": "2026-08-21T09:14:22.417Z",
   "properties": {
     "app_version": "0.12.0", "os": "darwin", "arch": "arm64",
-    "node_major": "20", "ci": "false", "agent_host": "claude-code",
+    "node_major": "20", "ci": "false", "agent_host": "claude-code", "cli_name": "trail",
     "repo_id": "6f2c1e90-...", "distinct_id": "b1f3a9c2-...",
     "files_bucket": "200-999", "langs": "go,ts", "mode": "deep",
     "duration_bucket": "30s-2m", "incremental": "true",

package.json

@@ -34,7 +34,7 @@
     "./package.json": "./package.json"
   },
   "bin": {
-    "graft": "dist/cli.js"
+    "graft": "dist/bin/graft.js"
   },
   "files": [
     "dist",