granite-mem 0.1.6 → 0.1.8

package/dist/index.js

@@ -16,85 +16,53 @@ var DEFAULT_CONFIG = {
   vault_name: "My Vault",
   version: 1,
   note_types: {
-    fleeting: {
-      folder: "notes/fleeting",
-      description: "Quick captures, inbox items",
-      template: "",
-      line_limit: 50,
-      warn_only: true,
-      slug_format: "date",
-      instructions: "Write a short thought, observation, or idea. Keep it raw \u2014 refine later into a permanent note."
-    },
-    permanent: {
-      folder: "notes/permanent",
+    note: {
+      folder: "notes/notes",
       description: "Refined, linked notes \u2014 one idea per note",
       template: "## Summary\n\n## Details\n\n## Links\n",
       line_limit: 200,
       warn_only: false,
-      instructions: "One atomic idea per note. Write a clear summary, then expand in details. Link to related notes with [[wikilinks]]. If the note grows too long, split it."
-    },
-    reference: {
-      folder: "notes/reference",
-      description: "Notes on external sources (articles, books, talks)",
-      template: "## Source\n\nURL or citation here.\n\n## Date\n\n## Key Points\n\n- \n\n## My Take\n\n",
-      line_limit: 300,
-      warn_only: true,
-      instructions: "Capture the source, the key points in your own words, and your reaction. Link to permanent notes that relate."
+      instructions: "One atomic idea per note. Write a clear summary, then expand in details. Link to related notes with [[wikilinks]]. If the note grows too long, split it.",
+      frontmatter_defaults: {
+        durability: "canonical"
+      }
     },
-    person: {
-      folder: "notes/people",
-      description: "Card for a person \u2014 contact, context, history",
-      template: "## Role\n\n## Context\n\nHow I know them, what we work on.\n\n## Contact\n\n## Notes\n\n- \n\n## Links\n\n",
-      line_limit: 150,
+    source: {
+      folder: "notes/sources",
+      description: "Imported or observed source material kept close to the original",
+      template: "## Summary\n\n## Key Facts\n\n- \n\n## Raw Content\n\n## Links\n",
+      line_limit: 400,
       warn_only: true,
-      instructions: "Fill in their role and context. Add timestamped notes as you interact (meetings, emails, calls). Link to projects, companies, or topics they relate to.",
-      fields: {
-        role: { type: "text", description: "Job title or role" },
-        org: { type: "text", description: "Organization or company" },
-        contact: { type: "text", description: "Email, Slack, phone" }
+      instructions: "Keep the source close to the original. Capture provenance in frontmatter, summarize the essentials, and link to durable notes or syntheses.",
+      frontmatter_defaults: {
+        durability: "canonical"
       }
     },
-    meeting: {
-      folder: "notes/meetings",
-      description: "Meeting notes with attendees, decisions, and actions",
-      template: "## Attendees\n\n- \n\n## Agenda\n\n- \n\n## Notes\n\n\n\n## Decisions\n\n- \n\n## Actions\n\n- [ ] \n",
+    synthesis: {
+      folder: "notes/syntheses",
+      description: "Compiled knowledge that connects multiple notes or sources",
+      template: "## Scope\n\n## Executive Summary\n\n## Main Themes\n\n## Open Questions\n\n## Links\n",
       line_limit: 300,
       warn_only: true,
-      instructions: "List attendees as [[person]] links. Capture decisions and action items clearly. Link to relevant projects or topics.",
-      fields: {
-        attendees: { type: "list", of: "wikilink", description: "People present" },
-        date: { type: "date", description: "Meeting date" },
-        project: { type: "wikilink", description: "Related project" }
+      instructions: "Use syntheses for durable compiled knowledge. Keep the scope explicit, summarize clearly, and point back to the notes or sources in derived_from.",
+      frontmatter_defaults: {
+        durability: "canonical"
       }
     },
-    project: {
-      folder: "notes/projects",
-      description: "Project overview \u2014 goals, status, people, links",
-      template: "## Goal\n\n## Status\n\n## People\n\n- \n\n## Key Decisions\n\n- \n\n## Links\n\n",
+    output: {
+      folder: "notes/outputs",
+      description: "Audience-specific outputs such as briefs, reports, or slides",
+      template: "## Goal\n\n## Audience\n\n## Output\n\n## References\n",
       line_limit: 300,
       warn_only: true,
-      instructions: "Define the goal clearly. Keep status updated. Link to people involved, meeting notes, and related permanent notes.",
-      fields: {
-        people: { type: "list", of: "wikilink", description: "Team members involved" },
-        project_status: { type: "enum", options: ["planning", "active", "paused", "completed"], default: "active", description: "Project lifecycle" }
-      }
-    },
-    decision: {
-      folder: "notes/decisions",
-      description: "Record of a decision \u2014 context, options, outcome",
-      template: "## Context\n\nWhat prompted this decision.\n\n## Options Considered\n\n1. \n2. \n\n## Decision\n\n\n\n## Rationale\n\n## Status\n\nActive\n",
-      line_limit: 200,
-      warn_only: false,
-      instructions: "Document the context, what options were considered, what was decided, and why. This is a permanent record \u2014 future-you will thank you. Link to the project or topic.",
-      fields: {
-        context_for: { type: "wikilink", description: "Project or area this decision belongs to" },
-        decision_status: { type: "enum", options: ["active", "superseded", "revisit"], default: "active", description: "Decision lifecycle" },
-        superseded_by: { type: "wikilink", description: "Replacement decision if superseded" }
+      instructions: "Outputs are situational deliverables. Keep them readable, point back to the durable knowledge they derive from, and make them easy to regenerate or archive.",
+      frontmatter_defaults: {
+        durability: "ephemeral"
       }
     }
   },
   defaults: {
-    note_type: "fleeting",
+    note_type: "note",
     editor: "$EDITOR"
   },
   index: {
@@ -147,6 +115,9 @@ function requireVaultRoot(from) {
   }
   return root;
 }
+function getGraniteDir(vaultRoot) {
+  return path2.join(vaultRoot, ".granite");
+}
 function getIndexDbPath(vaultRoot) {
   if (path2.basename(path2.resolve(vaultRoot)) === DEFAULT_VAULT_DIRNAME) {
     return path2.join(vaultRoot, "index.db");
@@ -180,11 +151,18 @@ function initVault(dir = getDefaultVaultRoot()) {
     console.log(`  ${typeConfig.folder}/  (${name})`);
   }
   console.log("");
-  console.log('Next: granite new "My first note" --type fleeting');
+  console.log("The knowledge loop: capture \u2192 compile \u2192 query \u2192 output \u2192 lint");
+  console.log("");
+  console.log("  source \u2192 note \u2192 synthesis \u2192 output");
+  console.log("");
+  console.log("Get started:");
+  console.log('  granite add "Your first thought"          # Capture something');
+  console.log('  granite new "Topic" --type source          # Import source material');
+  console.log("  granite status                             # See what to do next");
 }
 
 // src/commands/new.ts
-import fs10 from "fs";
+import fs6 from "fs";
 
 // src/core/note.ts
 import fs4 from "fs";
@@ -198,6 +176,55 @@ function slugify(title) {
 
 // src/core/frontmatter.ts
 import matter from "gray-matter";
+
+// src/core/json-output.ts
+function jsonSuccess(data) {
+  return JSON.stringify({ success: true, data }, null, 2);
+}
+function jsonError(error) {
+  return JSON.stringify({ success: false, error }, null, 2);
+}
+var VALID_STATUSES = ["inbox", "active", "archived"];
+var VALID_SOURCES = ["human", "agent", "extraction"];
+var VALID_REVIEW_STATES = ["draft", "reviewed", "locked"];
+var VALID_DURABILITY = ["canonical", "working", "ephemeral"];
+function validateStatus(value) {
+  if (!VALID_STATUSES.includes(value)) {
+    throw new Error(`Invalid status: "${value}". Expected one of: ${VALID_STATUSES.join(", ")}`);
+  }
+}
+function validateSource(value) {
+  if (!VALID_SOURCES.includes(value)) {
+    throw new Error(`Invalid source: "${value}". Expected one of: ${VALID_SOURCES.join(", ")}`);
+  }
+}
+function validateReviewState(value) {
+  if (!VALID_REVIEW_STATES.includes(value)) {
+    throw new Error(`Invalid review_state: "${value}". Expected one of: ${VALID_REVIEW_STATES.join(", ")}`);
+  }
+}
+function validateDurability(value) {
+  if (!VALID_DURABILITY.includes(value)) {
+    throw new Error(`Invalid durability: "${value}". Expected one of: ${VALID_DURABILITY.join(", ")}`);
+  }
+}
+function normalizeStatus(value, fallback = "active") {
+  return typeof value === "string" && VALID_STATUSES.includes(value) ? value : fallback;
+}
+function normalizeSource(value, fallback = "human") {
+  return typeof value === "string" && VALID_SOURCES.includes(value) ? value : fallback;
+}
+function normalizeReviewState(value, fallback = "draft") {
+  return typeof value === "string" && VALID_REVIEW_STATES.includes(value) ? value : fallback;
+}
+function normalizeDurability(value, fallback = "working") {
+  return typeof value === "string" && VALID_DURABILITY.includes(value) ? value : fallback;
+}
+function normalizeStringArray(value) {
+  return Array.isArray(value) ? value.map((item) => String(item)) : [];
+}
+
+// src/core/frontmatter.ts
 function parseFrontmatter(content) {
   const { data, content: body } = matter(content);
   const fm = {
@@ -206,10 +233,13 @@ function parseFrontmatter(content) {
     type: toFrontmatterString(data.type),
     created: toFrontmatterString(data.created),
     modified: toFrontmatterString(data.modified),
-    tags: data.tags ?? [],
-    aliases: data.aliases ?? [],
-    status: data.status ?? "active",
-    source: data.source ?? "human"
+    tags: normalizeStringArray(data.tags),
+    aliases: normalizeStringArray(data.aliases),
+    status: normalizeStatus(data.status),
+    source: normalizeSource(data.source),
+    review_state: normalizeReviewState(data.review_state),
+    durability: normalizeDurability(data.durability),
+    derived_from: normalizeStringArray(data.derived_from)
   };
   for (const [key, value] of Object.entries(data)) {
     if (!(key in fm)) {
@@ -255,6 +285,7 @@ function createNote(vaultRoot, config, typeName, title, bodyOverride) {
     }
   }
   const now = (/* @__PURE__ */ new Date()).toISOString();
+  const defaults = typeConfig.frontmatter_defaults ?? {};
   const frontmatter = {
     id: uuidv4(),
     title,
@@ -263,8 +294,11 @@ function createNote(vaultRoot, config, typeName, title, bodyOverride) {
     modified: now,
     tags: [],
     aliases: [],
-    status: "active",
-    source: "human"
+    status: normalizeStatus(defaults.status),
+    source: normalizeSource(defaults.source),
+    review_state: normalizeReviewState(defaults.review_state),
+    durability: normalizeDurability(defaults.durability),
+    derived_from: normalizeStringArray(defaults.derived_from)
   };
   const body = bodyOverride ?? typeConfig.template;
   const content = serializeFrontmatter(frontmatter, body);
@@ -308,26 +342,6 @@ function findNoteBySlug(vaultRoot, config, slug) {
   return null;
 }
 
-// src/core/json-output.ts
-function jsonSuccess(data) {
-  return JSON.stringify({ success: true, data }, null, 2);
-}
-function jsonError(error) {
-  return JSON.stringify({ success: false, error }, null, 2);
-}
-var VALID_STATUSES = ["inbox", "active", "archived"];
-var VALID_SOURCES = ["human", "agent", "extraction"];
-function validateStatus(value) {
-  if (!VALID_STATUSES.includes(value)) {
-    throw new Error(`Invalid status: "${value}". Expected one of: ${VALID_STATUSES.join(", ")}`);
-  }
-}
-function validateSource(value) {
-  if (!VALID_SOURCES.includes(value)) {
-    throw new Error(`Invalid source: "${value}". Expected one of: ${VALID_SOURCES.join(", ")}`);
-  }
-}
-
 // src/core/index-db.ts
 import Database from "better-sqlite3";
 import fs5 from "fs";
@@ -748,8 +762,7 @@ var STOP_WORDS = /* @__PURE__ */ new Set([
   "meeting",
   "person",
   "reference",
-  "permanent",
-  "fleeting",
+  "note",
   "how",
   "know",
   "work",
@@ -924,50 +937,31 @@ function getTagRecommendations(note, nearbyNotes) {
   })).sort((a, b) => b.weight - a.weight || a.tag.localeCompare(b.tag)).slice(0, MAX_TAG_RECOMMENDATIONS);
 }
 function getNextSteps(note, nearbyNotes) {
-  const projectLink = nearbyNotes.find((link) => link.type === "project");
-  const personLink = nearbyNotes.find((link) => link.type === "person");
+  const canonicalLink = nearbyNotes.find((link) => link.type === "note" || link.type === "synthesis");
   switch (note.frontmatter.type) {
-    case "fleeting":
-      return [{
-        type: "permanent",
-        title_hint: note.frontmatter.title,
-        reason: "Promote this into a durable note if it keeps mattering."
-      }];
-    case "reference":
-      return [{
-        type: "permanent",
-        title_hint: `Idea from ${note.frontmatter.title}`,
-        reason: "Distill one durable idea from this source."
-      }];
-    case "person":
-      return [{
-        type: projectLink ? "meeting" : "project",
-        title_hint: projectLink ? `${note.frontmatter.title} + ${projectLink.title}` : `${note.frontmatter.title} collaboration`,
-        reason: projectLink ? "Capture the latest interaction connected to this person." : "Anchor this person to a company, project, or collaboration note."
-      }];
-    case "meeting":
+    case "source":
       return [{
-        type: "decision",
-        title_hint: `Decision from ${note.frontmatter.title}`,
-        reason: "Extract the main decision so it can be linked independently."
+        type: "synthesis",
+        title_hint: `${note.frontmatter.title} synthesis`,
+        reason: "Compile the main ideas from this source into a durable synthesis."
       }];
-    case "project":
+    case "note":
       return [{
-        type: personLink ? "meeting" : "decision",
-        title_hint: personLink ? `${note.frontmatter.title} sync` : `${note.frontmatter.title} decision`,
-        reason: personLink ? "Capture the next concrete conversation for this project." : "Record the decision that drives this project forward."
+        type: canonicalLink ? "synthesis" : "source",
+        title_hint: canonicalLink ? `${note.frontmatter.title} synthesis` : `${note.frontmatter.title} source`,
+        reason: canonicalLink ? "Compile this durable idea with adjacent notes into a reusable synthesis." : "Attach this durable idea to an explicit source or source note."
       }];
-    case "decision":
+    case "synthesis":
       return [{
-        type: "project",
-        title_hint: `${note.frontmatter.title} rollout`,
-        reason: "Attach this decision to the project where it applies."
+        type: "output",
+        title_hint: `${note.frontmatter.title} brief`,
+        reason: "Turn this durable synthesis into a situational output for a specific audience."
       }];
-    case "permanent":
+    case "output":
       return [{
-        type: projectLink ? "decision" : "project",
-        title_hint: projectLink ? `Decision from ${note.frontmatter.title}` : `${note.frontmatter.title} in practice`,
-        reason: projectLink ? "Capture the concrete decision this idea supports." : "Anchor this idea in a project, company, or active thread."
+        type: canonicalLink ? canonicalLink.type : "synthesis",
+        title_hint: canonicalLink ? canonicalLink.title : `${note.frontmatter.title} synthesis`,
+        reason: canonicalLink ? "Link this output back to the durable knowledge it should depend on." : "Promote durable insights from this output into a reusable synthesis."
       }];
     default:
       return [];
@@ -979,72 +973,45 @@ function getAdditionRecommendations(note, config) {
   const existingLinks = parseWikilinks(body);
   const templateBody = config?.note_types[note.frontmatter.type]?.template ?? "";
   switch (note.frontmatter.type) {
-    case "person":
-      if (isSectionSparse(body, "Role", templateBody)) {
-        recommendations.push({ text: "Add a one-line role, company, or why this person matters." });
+    case "source":
+      if (isSectionSparse(body, "Summary", templateBody)) {
+        recommendations.push({ text: "Write a short summary so this source is understandable without rereading the whole document." });
       }
-      if (isSectionSparse(body, "Context", templateBody)) {
-        recommendations.push({ text: "Add how you know them or what you work on together." });
+      if (!hasMeaningfulBullets(body, "Key Facts")) {
+        recommendations.push({ text: "Capture 2-3 concrete facts worth preserving from the source." });
       }
       if (existingLinks.length === 0) {
-        recommendations.push({ text: "Link one project, company, or topic in the Links section." });
+        recommendations.push({ text: "Link one note or synthesis that this source supports." });
       }
       break;
-    case "reference":
-      if (!hasUrl(body) || body.includes("URL or citation here.")) {
-        recommendations.push({ text: "Add the source URL or citation." });
-      }
-      if (!hasMeaningfulBullets(body, "Key Points")) {
-        recommendations.push({ text: "Write 2-3 key points in your own words." });
+    case "note":
+      if (isSectionSparse(body, "Summary", templateBody)) {
+        recommendations.push({ text: "Write a one-line summary before expanding the idea." });
       }
       if (existingLinks.length === 0) {
-        recommendations.push({ text: "Link one permanent note, project, or topic this source relates to." });
-      }
-      break;
-    case "project":
-      if (isSectionSparse(body, "Goal", templateBody)) {
-        recommendations.push({ text: "Add a one-line goal so the project has a clear anchor." });
-      }
-      if (isSectionSparse(body, "People", templateBody)) {
-        recommendations.push({ text: "Link the people involved in the project." });
-      }
-      if (!hasMeaningfulBullets(body, "Key Decisions")) {
-        recommendations.push({ text: "Record one key decision or current status update." });
+        recommendations.push({ text: "Link one source, synthesis, or adjacent durable idea." });
       }
       break;
-    case "meeting":
-      if (!hasAnyWikilinks(body)) {
-        recommendations.push({ text: "Link the attendees directly in the note." });
-      }
-      if (!hasMeaningfulBullets(body, "Actions")) {
-        recommendations.push({ text: "Capture at least one next action." });
-      }
-      if (!hasMeaningfulBullets(body, "Decisions")) {
-        recommendations.push({ text: "Capture one decision or open question." });
+    case "synthesis":
+      if (isSectionSparse(body, "Scope", templateBody)) {
+        recommendations.push({ text: "Define the scope so this synthesis has a clear boundary." });
       }
-      break;
-    case "permanent":
-      if (isSectionSparse(body, "Summary", templateBody)) {
-        recommendations.push({ text: "Write a one-line summary before expanding the idea." });
+      if (isSectionSparse(body, "Executive Summary", templateBody)) {
+        recommendations.push({ text: "Write a short executive summary before expanding the synthesis." });
       }
       if (existingLinks.length === 0) {
-        recommendations.push({ text: "Link one project, company, person, or adjacent idea." });
+        recommendations.push({ text: "Link the notes or sources this synthesis pulls together." });
       }
       break;
-    case "decision":
-      if (isSectionSparse(body, "Context", templateBody)) {
-        recommendations.push({ text: "Add the context that forced this decision." });
+    case "output":
+      if (isSectionSparse(body, "Goal", templateBody)) {
+        recommendations.push({ text: "State the goal so the output is grounded in a concrete need." });
       }
-      if (isSectionSparse(body, "Decision", templateBody)) {
-        recommendations.push({ text: "State the decision in one sentence." });
+      if (isSectionSparse(body, "Audience", templateBody)) {
+        recommendations.push({ text: "Name the audience so the tone and content stay focused." });
       }
       if (existingLinks.length === 0) {
-        recommendations.push({ text: "Link the project, meeting, or note affected by this decision." });
-      }
-      break;
-    case "fleeting":
-      if (tokenize(body).length < 8) {
-        recommendations.push({ text: "Add one more sentence if this capture is worth keeping." });
+        recommendations.push({ text: "Link the source note or synthesis this output derives from." });
       }
       break;
     default:
@@ -1169,12 +1136,6 @@ function getSectionContent(body, heading) {
   }
   return collected.join("\n");
 }
-function hasUrl(body) {
-  return /https?:\/\/\S+/i.test(body);
-}
-function hasAnyWikilinks(body) {
-  return parseWikilinks(body).length > 0;
-}
 function getNoteMetadata(db, slug) {
   if (!slug) return null;
   const row = db.prepare(`
@@ -1200,489 +1161,6 @@ function parseJsonArray(raw) {
   }
 }
 
-// src/core/sync/manager.ts
-import fs9 from "fs";
-import path9 from "path";
-
-// src/core/sync/client.ts
-var SyncClient = class {
-  baseUrl;
-  apiKey;
-  timeoutMs;
-  constructor(config, timeoutMs = 5e3) {
-    this.baseUrl = config.server.replace(/\/$/, "");
-    this.apiKey = config.api_key;
-    this.timeoutMs = timeoutMs;
-  }
-  async request(method, endpoint, body) {
-    const controller = new AbortController();
-    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
-    try {
-      const response = await fetch(`${this.baseUrl}${endpoint}`, {
-        method,
-        headers: {
-          "Authorization": `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json"
-        },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      if (!response.ok) {
-        const text = await response.text().catch(() => "");
-        throw new SyncApiError(response.status, text || response.statusText);
-      }
-      return await response.json();
-    } finally {
-      clearTimeout(timer);
-    }
-  }
-  async push(payload) {
-    return this.request("POST", "/v1/sync/push", payload);
-  }
-  async pull(sinceSeq, deviceId) {
-    return this.request("GET", `/v1/sync/pull?since_seq=${sinceSeq}&device_id=${deviceId}`);
-  }
-  async quickPull(sinceSeq, deviceId, timeoutMs = 200) {
-    const oldTimeout = this.timeoutMs;
-    this.timeoutMs = timeoutMs;
-    try {
-      return await this.pull(sinceSeq, deviceId);
-    } catch {
-      return null;
-    } finally {
-      this.timeoutMs = oldTimeout;
-    }
-  }
-  async listDevices() {
-    return this.request("GET", "/v1/sync/devices");
-  }
-  async ping() {
-    try {
-      await this.request("GET", "/v1/sync/ping");
-      return true;
-    } catch {
-      return false;
-    }
-  }
-};
-var SyncApiError = class extends Error {
-  constructor(statusCode, body) {
-    super(`Sync API error ${statusCode}: ${body}`);
-    this.statusCode = statusCode;
-    this.body = body;
-    this.name = "SyncApiError";
-  }
-};
-
-// src/core/sync/device.ts
-import fs6 from "fs";
-import path6 from "path";
-import os2 from "os";
-import { v4 as uuidv42 } from "uuid";
-var DEVICE_FILE = "device.json";
-function getDeviceFilePath(vaultRoot) {
-  const graniteDir = path6.join(vaultRoot, ".granite");
-  fs6.mkdirSync(graniteDir, { recursive: true });
-  return path6.join(graniteDir, DEVICE_FILE);
-}
-function getOrCreateDeviceId(vaultRoot, deviceName) {
-  const filePath = getDeviceFilePath(vaultRoot);
-  if (fs6.existsSync(filePath)) {
-    const raw = fs6.readFileSync(filePath, "utf-8");
-    return JSON.parse(raw);
-  }
-  const info = {
-    device_id: uuidv42(),
-    device_name: deviceName || os2.hostname(),
-    created: (/* @__PURE__ */ new Date()).toISOString()
-  };
-  fs6.writeFileSync(filePath, JSON.stringify(info, null, 2), "utf-8");
-  return info;
-}
-function getDeviceId(vaultRoot) {
-  return getOrCreateDeviceId(vaultRoot).device_id;
-}
-
-// src/core/sync/changelog.ts
-import Database2 from "better-sqlite3";
-import fs7 from "fs";
-import path7 from "path";
-import crypto from "crypto";
-var SYNC_DB_FILE = "sync.db";
-var SYNC_SCHEMA_SQL = `
-CREATE TABLE IF NOT EXISTS changelog (
-  seq         INTEGER PRIMARY KEY AUTOINCREMENT,
-  note_id     TEXT NOT NULL,
-  operation   TEXT NOT NULL,
-  timestamp   TEXT NOT NULL,
-  device_id   TEXT NOT NULL,
-  checksum    TEXT NOT NULL,
-  synced      INTEGER NOT NULL DEFAULT 0
-);
-
-CREATE INDEX IF NOT EXISTS idx_changelog_note_id ON changelog(note_id);
-CREATE INDEX IF NOT EXISTS idx_changelog_synced ON changelog(synced);
-
-CREATE TABLE IF NOT EXISTS sync_meta (
-  key   TEXT PRIMARY KEY,
-  value TEXT
-);
-`;
-function getSyncDbPath(vaultRoot) {
-  const graniteDir = path7.join(vaultRoot, ".granite");
-  fs7.mkdirSync(graniteDir, { recursive: true });
-  return path7.join(graniteDir, SYNC_DB_FILE);
-}
-function openSyncDb(vaultRoot) {
-  const dbPath = getSyncDbPath(vaultRoot);
-  const db = new Database2(dbPath);
-  db.pragma("journal_mode = WAL");
-  db.exec(SYNC_SCHEMA_SQL);
-  return db;
-}
-function computeChecksum(content) {
-  return crypto.createHash("sha256").update(content, "utf-8").digest("hex");
-}
-function recordChange(db, noteId, operation, deviceId, fileContent) {
-  const now = (/* @__PURE__ */ new Date()).toISOString();
-  const checksum = computeChecksum(fileContent);
-  const stmt = db.prepare(`
-    INSERT INTO changelog (note_id, operation, timestamp, device_id, checksum, synced)
-    VALUES (?, ?, ?, ?, ?, 0)
-  `);
-  const result = stmt.run(noteId, operation, now, deviceId, checksum);
-  return {
-    seq: result.lastInsertRowid,
-    note_id: noteId,
-    operation,
-    timestamp: now,
-    device_id: deviceId,
-    checksum,
-    synced: false
-  };
-}
-function getPendingChanges(db) {
-  return db.prepare("SELECT * FROM changelog WHERE synced = 0 ORDER BY seq ASC").all();
-}
-function markChangesSynced(db, upToSeq) {
-  db.prepare("UPDATE changelog SET synced = 1 WHERE seq <= ?").run(upToSeq);
-}
-function getLastServerSeq(db) {
-  const row = db.prepare("SELECT value FROM sync_meta WHERE key = 'last_server_seq'").get();
-  return row ? Number(row.value) : 0;
-}
-function setLastServerSeq(db, seq) {
-  db.prepare("INSERT OR REPLACE INTO sync_meta (key, value) VALUES ('last_server_seq', ?)").run(String(seq));
-}
-function getLastSyncTime(db) {
-  const row = db.prepare("SELECT value FROM sync_meta WHERE key = 'last_sync'").get();
-  return row?.value ?? null;
-}
-function setLastSyncTime(db) {
-  db.prepare("INSERT OR REPLACE INTO sync_meta (key, value) VALUES ('last_sync', ?)").run((/* @__PURE__ */ new Date()).toISOString());
-}
-function getPendingCount(db) {
-  const row = db.prepare("SELECT COUNT(*) as c FROM changelog WHERE synced = 0").get();
-  return row.c;
-}
-
-// src/core/sync/conflict.ts
-import fs8 from "fs";
-import path8 from "path";
-var CONFLICTS_DIR = ".granite/conflicts";
-function getConflictsDir(vaultRoot) {
-  const dir = path8.join(vaultRoot, CONFLICTS_DIR);
-  fs8.mkdirSync(dir, { recursive: true });
-  return dir;
-}
-function detectConflict(localNote, remoteChange) {
-  if (remoteChange.operation === "delete") return false;
-  if (!remoteChange.frontmatter) return false;
-  const localModified = new Date(localNote.frontmatter.modified).getTime();
-  const remoteModified = new Date(remoteChange.frontmatter.modified).getTime();
-  return localModified !== remoteModified && remoteChange.checksum !== "";
-}
-function resolveConflict(vaultRoot, localNote, remoteChange, deviceId) {
-  if (!remoteChange.frontmatter || remoteChange.body === void 0) return null;
-  const localModified = new Date(localNote.frontmatter.modified).getTime();
-  const remoteModified = new Date(remoteChange.frontmatter.modified).getTime();
-  const remoteWins = remoteModified > localModified;
-  if (remoteWins) {
-    const conflictFile2 = saveConflictBackup(vaultRoot, localNote, deviceId);
-    return {
-      note_id: localNote.frontmatter.id,
-      local_modified: localNote.frontmatter.modified,
-      remote_modified: remoteChange.frontmatter.modified,
-      resolved: true,
-      conflict_file: conflictFile2
-    };
-  }
-  const conflictFile = saveRemoteConflictBackup(vaultRoot, remoteChange);
-  return {
-    note_id: localNote.frontmatter.id,
-    local_modified: localNote.frontmatter.modified,
-    remote_modified: remoteChange.frontmatter.modified,
-    resolved: true,
-    conflict_file: conflictFile
-  };
-}
-function saveConflictBackup(vaultRoot, note, deviceId) {
-  const conflictsDir = getConflictsDir(vaultRoot);
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const filename = `${note.frontmatter.id}_${deviceId}_${timestamp}.md`;
-  const filePath = path8.join(conflictsDir, filename);
-  const content = serializeFrontmatter(note.frontmatter, note.body);
-  fs8.writeFileSync(filePath, content, "utf-8");
-  return filePath;
-}
-function saveRemoteConflictBackup(vaultRoot, change) {
-  const conflictsDir = getConflictsDir(vaultRoot);
-  const timestamp = (/* @__PURE__ */ new Date()).toISOString().replace(/[:.]/g, "-");
-  const filename = `${change.note_id}_remote_${timestamp}.md`;
-  const filePath = path8.join(conflictsDir, filename);
-  if (change.frontmatter && change.body !== void 0) {
-    const content = serializeFrontmatter(change.frontmatter, change.body);
-    fs8.writeFileSync(filePath, content, "utf-8");
-  }
-  return filePath;
-}
-function listConflicts(vaultRoot) {
-  const conflictsDir = path8.join(vaultRoot, CONFLICTS_DIR);
-  if (!fs8.existsSync(conflictsDir)) return [];
-  return fs8.readdirSync(conflictsDir).filter((f) => f.endsWith(".md")).map((f) => path8.join(conflictsDir, f));
-}
-function clearResolvedConflicts(vaultRoot) {
-  const files = listConflicts(vaultRoot);
-  for (const f of files) {
-    fs8.unlinkSync(f);
-  }
-  return files.length;
-}
-
-// src/core/sync/manager.ts
-var SyncManager = class {
-  vaultRoot;
-  config;
-  syncConfig;
-  client;
-  deviceId;
-  constructor(vaultRoot, config) {
-    if (!config.sync?.enabled) {
-      throw new Error("Sync is not enabled. Add a sync section to granite.yml.");
-    }
-    this.vaultRoot = vaultRoot;
-    this.config = config;
-    this.syncConfig = config.sync;
-    this.client = new SyncClient(this.syncConfig);
-    this.deviceId = getDeviceId(vaultRoot);
-  }
-  /**
-   * Track a local mutation and push it in the background (fire-and-forget).
-   * This is the hook called after every note create/update/delete.
-   */
-  trackAndPush(note, operation) {
-    const db = openSyncDb(this.vaultRoot);
-    try {
-      const content = fs9.existsSync(note.filepath) ? fs9.readFileSync(note.filepath, "utf-8") : "";
-      recordChange(db, note.frontmatter.id, operation, this.deviceId, content);
-    } finally {
-      db.close();
-    }
-    this.push().catch(() => {
-    });
-  }
-  /**
-   * Push all pending local changes to the relay server.
-   */
-  async push() {
-    const db = openSyncDb(this.vaultRoot);
-    try {
-      const pending = getPendingChanges(db);
-      if (pending.length === 0) {
-        return { pushed: 0, server_seq: getLastServerSeq(db) };
-      }
-      const changes = [];
-      for (const entry of pending) {
-        const note = this.findNoteById(entry.note_id);
-        changes.push({
-          note_id: entry.note_id,
-          operation: entry.operation,
-          timestamp: entry.timestamp,
-          checksum: entry.checksum,
-          slug: note?.slug ?? "",
-          frontmatter: note?.frontmatter,
-          body: note?.body
-        });
-      }
-      const lastSeq = getLastServerSeq(db);
-      const result = await this.client.push({
-        device_id: this.deviceId,
-        last_server_seq: lastSeq,
-        changes
-      });
-      const maxSeq = Math.max(...pending.map((p) => p.seq));
-      markChangesSynced(db, maxSeq);
-      setLastServerSeq(db, result.server_seq);
-      setLastSyncTime(db);
-      return { pushed: result.accepted, server_seq: result.server_seq };
-    } finally {
-      db.close();
-    }
-  }
-  /**
-   * Pull remote changes and apply them locally.
-   */
-  async pull() {
-    const db = openSyncDb(this.vaultRoot);
-    try {
-      const lastSeq = getLastServerSeq(db);
-      const response = await this.client.pull(lastSeq, this.deviceId);
-      let applied = 0;
-      let conflicts = 0;
-      for (const change of response.changes) {
-        const result = this.applyRemoteChange(change);
-        if (result === "applied") applied++;
-        if (result === "conflict") conflicts++;
-      }
-      setLastServerSeq(db, response.server_seq);
-      setLastSyncTime(db);
-      return { applied, conflicts };
-    } finally {
-      db.close();
-    }
-  }
-  /**
-   * Quick pull with a tight timeout — used before read commands.
-   * Returns silently if server is unreachable.
-   */
-  async quickPull() {
-    const db = openSyncDb(this.vaultRoot);
-    try {
-      const lastSeq = getLastServerSeq(db);
-      const response = await this.client.quickPull(lastSeq, this.deviceId);
-      if (!response) return;
-      for (const change of response.changes) {
-        this.applyRemoteChange(change);
-      }
-      setLastServerSeq(db, response.server_seq);
-      setLastSyncTime(db);
-    } finally {
-      db.close();
-    }
-  }
-  /**
-   * Full bidirectional sync: push then pull.
-   */
-  async sync() {
-    const pushResult = await this.push();
-    const pullResult = await this.pull();
-    return {
-      pushed: pushResult.pushed,
-      pulled: pullResult.applied,
-      conflicts: pullResult.conflicts
-    };
-  }
-  /**
-   * Get current sync status.
-   */
-  status() {
-    const db = openSyncDb(this.vaultRoot);
-    try {
-      const deviceInfo = getOrCreateDeviceId(this.vaultRoot);
-      return {
-        device_id: deviceInfo.device_id,
-        device_name: deviceInfo.device_name,
-        last_sync: getLastSyncTime(db),
-        pending_changes: getPendingCount(db),
-        server_seq: getLastServerSeq(db)
-      };
-    } finally {
-      db.close();
-    }
-  }
-  /**
-   * List connected devices.
-   */
-  async devices() {
-    return this.client.listDevices();
-  }
-  /**
-   * List unresolved conflict files.
-   */
-  conflicts() {
-    return listConflicts(this.vaultRoot);
-  }
-  applyRemoteChange(change) {
-    switch (change.operation) {
-      case "create":
-        return this.applyRemoteCreate(change);
-      case "update":
-        return this.applyRemoteUpdate(change);
-      case "delete":
-        return this.applyRemoteDelete(change);
-      default:
-        return "skipped";
-    }
-  }
-  applyRemoteCreate(change) {
-    if (!change.frontmatter || change.body === void 0) return "skipped";
-    const existing = this.findNoteById(change.note_id);
-    if (existing) return "skipped";
-    const typeConfig = this.config.note_types[change.frontmatter.type];
-    if (!typeConfig) return "skipped";
-    const folder = path9.join(this.vaultRoot, typeConfig.folder);
-    fs9.mkdirSync(folder, { recursive: true });
-    const slug = change.slug || change.note_id;
-    const filepath = path9.join(folder, `${slug}.md`);
-    const content = serializeFrontmatter(change.frontmatter, change.body);
-    fs9.writeFileSync(filepath, content, "utf-8");
-    return "applied";
-  }
-  applyRemoteUpdate(change) {
-    if (!change.frontmatter || change.body === void 0) return "skipped";
-    const localNote = this.findNoteById(change.note_id);
-    if (!localNote) {
-      return this.applyRemoteCreate(change);
-    }
-    const localContent = fs9.readFileSync(localNote.filepath, "utf-8");
-    const localChecksum = computeChecksum(localContent);
-    if (localChecksum === change.checksum) return "skipped";
-    if (detectConflict(localNote, change)) {
-      resolveConflict(this.vaultRoot, localNote, change, this.deviceId);
-      const localTime = new Date(localNote.frontmatter.modified).getTime();
-      const remoteTime = new Date(change.frontmatter.modified).getTime();
-      if (remoteTime > localTime) {
-        const content2 = serializeFrontmatter(change.frontmatter, change.body);
-        fs9.writeFileSync(localNote.filepath, content2, "utf-8");
-      }
-      return "conflict";
-    }
-    const content = serializeFrontmatter(change.frontmatter, change.body);
-    fs9.writeFileSync(localNote.filepath, content, "utf-8");
-    return "applied";
-  }
-  applyRemoteDelete(change) {
-    const localNote = this.findNoteById(change.note_id);
-    if (!localNote) return "skipped";
-    if (fs9.existsSync(localNote.filepath)) {
-      fs9.unlinkSync(localNote.filepath);
-    }
-    return "applied";
-  }
-  findNoteById(noteId) {
-    const allNotes = listNotes(this.vaultRoot, this.config);
-    return allNotes.find((n) => n.frontmatter.id === noteId) ?? null;
-  }
-};
-function getSyncManager(vaultRoot, config) {
-  if (!config.sync?.enabled) return null;
-  try {
-    return new SyncManager(vaultRoot, config);
-  } catch {
-    return null;
-  }
-}
-
 // src/commands/new.ts
 function newNote(title, options) {
   const vaultRoot = requireVaultRoot();
@@ -1691,22 +1169,27 @@ function newNote(title, options) {
   const typeConfig = config.note_types[resolvedType];
   const bodyOverride = typeConfig?.slug_format === "date" ? title + "\n" : void 0;
   const note = createNote(vaultRoot, config, resolvedType, title, bodyOverride);
-  if (options.source || options.status) {
-    if (options.source) validateSource(options.source);
-    if (options.status) validateStatus(options.status);
-    const raw = fs10.readFileSync(note.filepath, "utf-8");
+  if (options.source !== void 0 || options.status !== void 0 || options.reviewState !== void 0 || options.durability !== void 0 || options.derivedFrom !== void 0) {
+    if (options.source !== void 0) validateSource(options.source);
+    if (options.status !== void 0) validateStatus(options.status);
+    if (options.reviewState !== void 0) validateReviewState(options.reviewState);
+    if (options.durability !== void 0) validateDurability(options.durability);
+    const raw = fs6.readFileSync(note.filepath, "utf-8");
     const { frontmatter, body } = parseFrontmatter(raw);
-    if (options.source) frontmatter.source = options.source;
-    if (options.status) frontmatter.status = options.status;
-    fs10.writeFileSync(note.filepath, serializeFrontmatter(frontmatter, body), "utf-8");
+    if (options.source !== void 0) frontmatter.source = options.source;
+    if (options.status !== void 0) frontmatter.status = options.status;
+    if (options.reviewState !== void 0) frontmatter.review_state = options.reviewState;
+    if (options.durability !== void 0) frontmatter.durability = options.durability;
+    if (options.derivedFrom !== void 0) {
+      frontmatter.derived_from = options.derivedFrom.split(",").map((value) => value.trim()).filter(Boolean);
+    }
+    fs6.writeFileSync(note.filepath, serializeFrontmatter(frontmatter, body), "utf-8");
     note.frontmatter = frontmatter;
   }
   const recommendationStrategy = typeConfig?.slug_format === "date" ? "incremental" : "rebuild";
   const recommendations = recommendNote(vaultRoot, config, note, { strategy: recommendationStrategy });
   const lines = note.body.split("\n").length;
   const overLimit = typeConfig && typeConfig.line_limit && lines > typeConfig.line_limit;
-  const sync = getSyncManager(vaultRoot, config);
-  sync?.trackAndPush(note, "create");
   if (options.json) {
     console.log(jsonSuccess({
       slug: note.slug,
@@ -1714,6 +1197,9 @@ function newNote(title, options) {
       type: resolvedType,
       status: note.frontmatter.status,
       source: note.frontmatter.source,
+      review_state: note.frontmatter.review_state,
+      durability: note.frontmatter.durability,
+      derived_from: note.frontmatter.derived_from,
       filepath: note.filepath,
       suggestions: recommendations.links.map((link) => ({
         slug: link.slug,
@@ -1741,19 +1227,36 @@ function newNote(title, options) {
       console.log(line);
     }
   }
+  console.log("");
+  switch (resolvedType) {
+    case "source":
+      console.log(`Next: Fill the note, then compile \u2192 granite recommend ${note.slug}`);
+      break;
+    case "note":
+      console.log(`Next: Link to related notes \u2192 granite suggest-links ${note.slug}`);
+      break;
+    case "synthesis":
+      console.log(`Next: Review connections \u2192 granite backlinks ${note.slug}`);
+      break;
+    case "output":
+      console.log(`Next: Verify provenance \u2192 granite show ${note.slug}`);
+      break;
+    default:
+      console.log(`Next: granite recommend ${note.slug}`);
+  }
 }
 
 // src/commands/add.ts
-import fs11 from "fs";
+import fs7 from "fs";
 function addNote(text, options = {}) {
   const vaultRoot = requireVaultRoot();
   const config = loadConfig(vaultRoot);
   const typeName = config.defaults.note_type;
-  let content;
+  let content = "";
   if (text) {
     content = text;
   } else if (!process.stdin.isTTY) {
-    content = fs11.readFileSync(0, "utf-8").trim();
+    content = fs7.readFileSync(0, "utf-8").trim();
   } else {
     console.error('Usage: granite add "some text" or echo "text" | granite add');
     process.exit(1);
@@ -1766,8 +1269,6 @@ function addNote(text, options = {}) {
   const title = firstLine.length > 60 ? firstLine.slice(0, 60).trim() + "..." : firstLine;
   const note = createNote(vaultRoot, config, typeName, title, content + "\n");
   const recommendations = recommendNote(vaultRoot, config, note, { strategy: "incremental" });
-  const sync = getSyncManager(vaultRoot, config);
-  sync?.trackAndPush(note, "create");
   if (options.json) {
     console.log(jsonSuccess({
       slug: note.slug,
@@ -1787,6 +1288,9 @@ function addNote(text, options = {}) {
       console.log(line);
     }
   }
+  console.log("");
+  console.log(`Captured as "${note.frontmatter.title}" (${note.slug})`);
+  console.log(`Next: Refine \u2192 granite edit ${note.slug} | Find links \u2192 granite suggest-links ${note.slug}`);
 }
 
 // src/commands/open.ts
@@ -1799,12 +1303,13 @@ function openNote(slug) {
     console.error(`Note not found: "${slug}"`);
     process.exit(1);
   }
+  const existingNote = note;
   const editor = config.defaults.editor === "$EDITOR" ? process.env.EDITOR || "vi" : config.defaults.editor;
-  execSync(`${editor} "${note.filepath}"`, { stdio: "inherit" });
+  execSync(`${editor} "${existingNote.filepath}"`, { stdio: "inherit" });
 }
 
 // src/commands/show.ts
-import fs12 from "fs";
+import fs8 from "fs";
 function showCommand(slug, options) {
   const vaultRoot = requireVaultRoot();
   const config = loadConfig(vaultRoot);
@@ -1817,30 +1322,36 @@ function showCommand(slug, options) {
     }
     process.exit(1);
   }
+  const existingNote = note;
   if (options.json) {
     console.log(jsonSuccess({
-      slug: note.slug,
-      title: note.frontmatter.title,
-      type: note.frontmatter.type,
-      created: note.frontmatter.created,
-      modified: note.frontmatter.modified,
-      tags: note.frontmatter.tags,
-      aliases: note.frontmatter.aliases,
-      status: note.frontmatter.status,
-      source: note.frontmatter.source,
-      body: note.body,
-      filepath: note.filepath
+      slug: existingNote.slug,
+      title: existingNote.frontmatter.title,
+      type: existingNote.frontmatter.type,
+      created: existingNote.frontmatter.created,
+      modified: existingNote.frontmatter.modified,
+      tags: existingNote.frontmatter.tags,
+      aliases: existingNote.frontmatter.aliases,
+      status: existingNote.frontmatter.status,
+      source: existingNote.frontmatter.source,
+      review_state: existingNote.frontmatter.review_state,
+      durability: existingNote.frontmatter.durability,
+      derived_from: existingNote.frontmatter.derived_from,
+      body: existingNote.body,
+      filepath: existingNote.filepath
     }));
     return;
   }
   if (options.body) {
-    process.stdout.write(note.body);
+    process.stdout.write(existingNote.body);
     return;
   }
-  console.log(`# ${note.frontmatter.title}  (${note.slug})`);
-  console.log(`# type: ${note.frontmatter.type}  |  modified: ${note.frontmatter.modified.slice(0, 10)}`);
+  console.log(`# ${existingNote.frontmatter.title}  (${existingNote.slug})`);
+  console.log(
+    `# type: ${existingNote.frontmatter.type}  |  modified: ${existingNote.frontmatter.modified.slice(0, 10)}  |  review: ${existingNote.frontmatter.review_state}  |  durability: ${existingNote.frontmatter.durability}`
+  );
   console.log("");
-  const content = fs12.readFileSync(note.filepath, "utf-8");
+  const content = fs8.readFileSync(existingNote.filepath, "utf-8");
   console.log(content);
 }
 
@@ -1881,6 +1392,8 @@ function searchCommand(query, options) {
   }
   if (results.length === 0) {
     console.log("No results found.");
+    console.log("");
+    console.log(`Nothing in the vault matches "${query}". Capture it: granite add "${query}"`);
     return;
   }
   for (const r of results) {
@@ -1888,6 +1401,9 @@ function searchCommand(query, options) {
     console.log(`    ${r.snippet}`);
     console.log("");
   }
+  console.log(`${results.length} result(s) for "${query}"`);
+  console.log("");
+  console.log(`Dive deeper: granite show ${results[0].slug} | granite backlinks ${results[0].slug}`);
 }
 
 // src/core/backlinks.ts
@@ -1918,6 +1434,9 @@ function backlinksCommand(slug, options) {
   }
   if (backlinks.length === 0) {
     console.log(`No backlinks found for "${slug}".`);
+    console.log("");
+    console.log("This note is an orphan \u2014 nothing links to it.");
+    console.log(`Connect it: granite suggest-links ${slug} | granite recommend ${slug}`);
     return;
   }
   console.log(`Backlinks to "${slug}":`);
@@ -1929,6 +1448,7 @@ function backlinksCommand(slug, options) {
     }
     console.log("");
   }
+  console.log(`${backlinks.length} note(s) link here. Strengthen: granite suggest-links ${slug}`);
 }
 
 // src/commands/suggest-links.ts
@@ -1944,22 +1464,27 @@ function suggestLinksCommand(slug, options) {
     }
     process.exit(1);
   }
+  const existingNote = note;
   const db = ensureIndex(vaultRoot, config);
-  const suggestions = suggestLinks(db, note);
+  const suggestions = suggestLinks(db, existingNote);
   db.close();
   if (options.json) {
     console.log(jsonSuccess(suggestions));
     return;
   }
   if (suggestions.length === 0) {
-    console.log("No link suggestions found.");
+    console.log(`No unlinked mentions found for "${existingNote.frontmatter.title}".`);
+    console.log("");
+    console.log(`All mentions are linked. See what else to do: granite recommend ${slug}`);
     return;
   }
-  console.log(`Suggested links for "${note.frontmatter.title}":`);
+  console.log(`Unlinked mentions in "${existingNote.frontmatter.title}":`);
   console.log("");
   for (const s of suggestions) {
     console.log(`  \u2192 [[${s.target_title}]] \u2014 ${s.mentions} mention${s.mentions > 1 ? "s" : ""}`);
   }
+  console.log("");
+  console.log(`Add [[wikilinks]] to strengthen the graph. Then: granite recommend ${slug}`);
 }
 
 // src/commands/recommend.ts
@@ -1975,37 +1500,48 @@ function recommendCommand(slug, options) {
     }
     process.exit(1);
   }
-  const recommendations = recommendNote(vaultRoot, config, note);
+  const existingNote = note;
+  const recommendations = recommendNote(vaultRoot, config, existingNote);
   if (options.json) {
     console.log(jsonSuccess({
-      slug: note.slug,
-      title: note.frontmatter.title,
-      type: note.frontmatter.type,
+      slug: existingNote.slug,
+      title: existingNote.frontmatter.title,
+      type: existingNote.frontmatter.type,
       recommendations
     }));
     return;
   }
   const lines = formatRecommendations(recommendations);
   if (lines.length === 0) {
-    console.log(`No recommendations found for "${note.frontmatter.title}".`);
+    console.log(`"${existingNote.frontmatter.title}" is well-connected. No actions needed.`);
+    console.log("");
+    console.log("Keep the loop going: granite status");
     return;
   }
-  console.log(`Recommendations for "${note.frontmatter.title}":`);
+  console.log(`Recommendations for "${existingNote.frontmatter.title}" (${existingNote.frontmatter.type}):`);
   console.log("");
   for (const line of lines) {
     console.log(line);
   }
+  console.log("");
+  if (recommendations.next_steps.length > 0) {
+    const step = recommendations.next_steps[0];
+    const hint = step.title_hint ? ` "${step.title_hint}"` : "";
+    console.log(`The vault is asking for: granite new${hint} --type ${step.type}`);
+  } else if (recommendations.links.length > 0) {
+    console.log(`Strengthen this note: granite edit ${slug} --append $'See also: [[${recommendations.links[0].slug}]]'`);
+  }
 }
 
 // src/core/doctor.ts
-import fs13 from "fs";
-import path10 from "path";
+import fs9 from "fs";
+import path6 from "path";
 function runDoctor(vaultRoot, config, db) {
   const issues = [];
   const notes = listNotes(vaultRoot, config);
   for (const [name, typeConfig] of Object.entries(config.note_types)) {
-    const folder = path10.join(vaultRoot, typeConfig.folder);
-    if (!fs13.existsSync(folder)) {
+    const folder = path6.join(vaultRoot, typeConfig.folder);
+    if (!fs9.existsSync(folder)) {
       issues.push({
         level: "error",
         file: `granite.yml`,
@@ -2027,6 +1563,26 @@ function runDoctor(vaultRoot, config, db) {
     if (!fm.created) {
       issues.push({ level: "warning", file: note.filepath, message: "Missing frontmatter field: created" });
     }
+    try {
+      validateReviewState(fm.review_state);
+    } catch (error) {
+      issues.push({ level: "warning", file: note.filepath, message: error.message });
+    }
+    try {
+      validateDurability(fm.durability);
+    } catch (error) {
+      issues.push({ level: "warning", file: note.filepath, message: error.message });
+    }
+    if (!Array.isArray(fm.derived_from)) {
+      issues.push({ level: "warning", file: note.filepath, message: "Invalid derived_from: expected a list of note IDs or slugs" });
+    }
+    if ((fm.type === "synthesis" || fm.type === "output") && (!Array.isArray(fm.derived_from) || fm.derived_from.length === 0)) {
+      issues.push({
+        level: "warning",
+        file: note.filepath,
+        message: `Type "${fm.type}" should declare derived_from to preserve provenance`
+      });
+    }
   }
   for (const note of notes) {
     const links = parseWikilinks(note.body);
@@ -2107,19 +1663,33 @@ function runDoctor(vaultRoot, config, db) {
 }
 
 // src/commands/doctor.ts
-function doctorCommand() {
+function doctorCommand(options = {}) {
   const vaultRoot = requireVaultRoot();
   const config = loadConfig(vaultRoot);
   const db = ensureIndex(vaultRoot, config);
   const issues = runDoctor(vaultRoot, config, db);
   db.close();
-  if (issues.length === 0) {
-    console.log("No issues found. Vault is healthy.");
-    return;
-  }
   const errors = issues.filter((i) => i.level === "error");
   const warnings = issues.filter((i) => i.level === "warning");
   const infos = issues.filter((i) => i.level === "info");
+  if (options.json) {
+    console.log(jsonSuccess({
+      healthy: errors.length === 0,
+      issues,
+      counts: {
+        errors: errors.length,
+        warnings: warnings.length,
+        infos: infos.length
+      }
+    }));
+    return;
+  }
+  if (issues.length === 0) {
+    console.log("Vault is healthy. No issues found.");
+    console.log("");
+    console.log("Keep the loop going: granite status");
+    return;
+  }
   const print = (label, items) => {
     if (items.length === 0) return;
     console.log(`
@@ -2134,14 +1704,26 @@ ${label}:`);
   print("Info", infos);
   console.log(`
 ${errors.length} error(s), ${warnings.length} warning(s), ${infos.length} info(s)`);
+  console.log("");
+  const brokenLinks = issues.filter((i) => i.message.includes("Broken wikilink") || i.message.includes("broken"));
+  const overLimit = issues.filter((i) => i.message.includes("line limit") || i.message.includes("exceeds"));
+  if (brokenLinks.length > 0) {
+    console.log(`Fix broken links: ${brokenLinks.length} wikilink(s) point to notes that don't exist.`);
+    console.log("  \u2192 Create the missing notes or fix the [[wikilinks]].");
+  }
+  if (overLimit.length > 0) {
+    console.log(`Split oversized notes: ${overLimit.length} note(s) exceed their line limit.`);
+    console.log("  \u2192 Break them into smaller, linked notes. One idea per note.");
+  }
   if (errors.length > 0) process.exit(1);
 }
 
 // src/web/server.ts
 import { Hono } from "hono";
 import { serve } from "@hono/node-server";
-import path11 from "path";
-import fs14 from "fs";
+import path7 from "path";
+import fs10 from "fs";
+import { fileURLToPath } from "url";
 function createApp(vaultRoot, config) {
   const app = new Hono();
   app.get("/api/notes", (c) => {
@@ -2179,6 +1761,11 @@ function createApp(vaultRoot, config) {
       modified: note.frontmatter.modified,
       tags: note.frontmatter.tags,
       aliases: note.frontmatter.aliases,
+      status: note.frontmatter.status,
+      source: note.frontmatter.source,
+      review_state: note.frontmatter.review_state,
+      durability: note.frontmatter.durability,
+      derived_from: note.frontmatter.derived_from,
       body: note.body,
       outgoing_links: resolvedLinks,
       backlinks
@@ -2210,13 +1797,14 @@ function createApp(vaultRoot, config) {
     }
     try {
       const note = createNote(vaultRoot, config, type, title, noteBody || void 0);
-      const sync = getSyncManager(vaultRoot, config);
-      sync?.trackAndPush(note, "create");
       return c.json({
         slug: note.slug,
         title: note.frontmatter.title,
         type: note.frontmatter.type,
-        created: note.frontmatter.created
+        created: note.frontmatter.created,
+        review_state: note.frontmatter.review_state,
+        durability: note.frontmatter.durability,
+        derived_from: note.frontmatter.derived_from
       });
     } catch (err) {
       return c.json({ error: err.message }, 400);
@@ -2229,17 +1817,17 @@ function createApp(vaultRoot, config) {
     db.close();
     return c.json({ nodes, edges });
   });
-  const publicDir = path11.join(import.meta.dirname, "public");
+  const publicDir = path7.join(path7.dirname(fileURLToPath(import.meta.url)), "public");
   app.get("/*", (c) => {
     const reqPath = c.req.path === "/" ? "/index.html" : c.req.path;
-    const filePath = path11.join(publicDir, reqPath);
-    if (!fs14.existsSync(filePath)) {
-      const indexPath = path11.join(publicDir, "index.html");
-      const html = fs14.readFileSync(indexPath, "utf-8");
+    const filePath = path7.join(publicDir, reqPath);
+    if (!fs10.existsSync(filePath)) {
+      const indexPath = path7.join(publicDir, "index.html");
+      const html = fs10.readFileSync(indexPath, "utf-8");
       return c.html(html);
     }
-    const content = fs14.readFileSync(filePath);
-    const ext = path11.extname(filePath);
+    const content = fs10.readFileSync(filePath);
+    const ext = path7.extname(filePath);
     const mimeTypes = {
       ".html": "text/html",
       ".css": "text/css",
@@ -2273,7 +1861,7 @@ function serveCommand(options) {
 function typesCommand() {
   const vaultRoot = requireVaultRoot();
   const config = loadConfig(vaultRoot);
-  console.log("Available note types:\n");
+  console.log("Note types \u2014 the natural flow is: source \u2192 note \u2192 synthesis \u2192 output\n");
   for (const [name, tc] of Object.entries(config.note_types)) {
     console.log(`  ${name}`);
     console.log(`    ${tc.description}`);
@@ -2281,15 +1869,25 @@ function typesCommand() {
     if (tc.instructions) {
       console.log(`    guide: ${tc.instructions}`);
     }
+    if (tc.frontmatter_defaults) {
+      const defaults = Object.entries(tc.frontmatter_defaults).map(([k, v]) => `${k}: ${v}`).join(", ");
+      console.log(`    defaults: ${defaults}`);
+    }
     console.log("");
   }
   console.log(`Default type: ${config.defaults.note_type}`);
-  console.log(`
-Usage: granite new <type> <title>`);
+  console.log("");
+  console.log("When to use what:");
+  console.log("  source     Raw material \u2014 articles, tweets, papers. Keep it close to the original.");
+  console.log("  note       One durable idea. If it's two ideas, make two notes.");
+  console.log("  synthesis  Compile multiple notes into new understanding. The most valuable type.");
+  console.log("  output     Audience-specific deliverable. Ephemeral \u2014 always derived_from something durable.");
+  console.log("");
+  console.log('Usage: granite new "Title" --type <type>');
 }
 
 // src/commands/list.ts
-var AVAILABLE_FIELDS = ["slug", "title", "type", "created", "modified", "tags", "aliases", "status", "source", "filepath"];
+var AVAILABLE_FIELDS = ["slug", "title", "type", "created", "modified", "tags", "aliases", "status", "source", "review_state", "durability", "derived_from", "filepath"];
 function pickFields(note, fields) {
   const out = {};
   for (const f of fields) {
@@ -2321,6 +1919,15 @@ function pickFields(note, fields) {
       case "source":
         out.source = note.frontmatter.source;
         break;
+      case "review_state":
+        out.review_state = note.frontmatter.review_state;
+        break;
+      case "durability":
+        out.durability = note.frontmatter.durability;
+        break;
+      case "derived_from":
+        out.derived_from = note.frontmatter.derived_from;
+        break;
       case "filepath":
         out.filepath = note.filepath;
         break;
@@ -2362,6 +1969,12 @@ function listCommand(options) {
   }
   if (notes.length === 0) {
     console.log("No notes found.");
+    if (options.type) {
+      console.log(`
+No ${options.type} notes yet. Create one: granite new "Title" --type ${options.type}`);
+    } else {
+      console.log('\nVault is empty. Start: granite add "Your first thought"');
+    }
     return;
   }
   for (const note of notes) {
@@ -2372,10 +1985,13 @@ function listCommand(options) {
   }
   console.log(`
 ${notes.length} note(s)`);
+  if (options.status === "inbox") {
+    console.log("\nProcess inbox: granite show <slug> \u2192 granite edit <slug> --status active");
+  }
 }
 
 // src/commands/edit.ts
-import fs15 from "fs";
+import fs11 from "fs";
 import { execSync as execSync2 } from "child_process";
 function editCommand(slug, options) {
   const vaultRoot = requireVaultRoot();
@@ -2385,9 +2001,10 @@ function editCommand(slug, options) {
     console.error(`Note not found: ${slug}`);
     process.exit(1);
   }
-  const hasFlags = options.body !== void 0 || options.append !== void 0 || options.title !== void 0 || options.tag !== void 0 || options.alias !== void 0 || options.status !== void 0 || options.source !== void 0;
+  const existingNote = note;
+  const hasFlags = options.body !== void 0 || options.append !== void 0 || options.title !== void 0 || options.tag !== void 0 || options.alias !== void 0 || options.status !== void 0 || options.source !== void 0 || options.reviewState !== void 0 || options.durability !== void 0 || options.derivedFrom !== void 0;
   if (hasFlags) {
-    let { frontmatter, body } = parseFrontmatter(fs15.readFileSync(note.filepath, "utf-8"));
+    let { frontmatter, body } = parseFrontmatter(fs11.readFileSync(existingNote.filepath, "utf-8"));
     if (options.title) {
       frontmatter.title = options.title;
     }
@@ -2403,14 +2020,25 @@ function editCommand(slug, options) {
       for (const a of newAliases) existing.add(a);
       frontmatter.aliases = [...existing];
     }
-    if (options.status) {
+    if (options.status !== void 0) {
       validateStatus(options.status);
       frontmatter.status = options.status;
     }
-    if (options.source) {
+    if (options.source !== void 0) {
       validateSource(options.source);
       frontmatter.source = options.source;
     }
+    if (options.reviewState !== void 0) {
+      validateReviewState(options.reviewState);
+      frontmatter.review_state = options.reviewState;
+    }
+    if (options.durability !== void 0) {
+      validateDurability(options.durability);
+      frontmatter.durability = options.durability;
+    }
+    if (options.derivedFrom !== void 0) {
+      frontmatter.derived_from = options.derivedFrom.split(",").map((value) => value.trim()).filter(Boolean);
+    }
     if (options.body !== void 0) {
       body = options.body + "\n";
     }
@@ -2418,32 +2046,26 @@ function editCommand(slug, options) {
       body = body.trimEnd() + "\n" + options.append + "\n";
     }
     frontmatter.modified = (/* @__PURE__ */ new Date()).toISOString();
-    fs15.writeFileSync(note.filepath, serializeFrontmatter(frontmatter, body), "utf-8");
-    const sync = getSyncManager(vaultRoot, config);
-    const updatedForSync = readNote(note.filepath);
-    sync?.trackAndPush(updatedForSync, "update");
-    console.log(note.filepath);
+    fs11.writeFileSync(existingNote.filepath, serializeFrontmatter(frontmatter, body), "utf-8");
+    console.log(existingNote.filepath);
     const recommendationStrategy = options.title !== void 0 || options.alias !== void 0 ? "rebuild" : "incremental";
-    printRecommendations(vaultRoot, config, note.filepath, recommendationStrategy);
+    printRecommendations(vaultRoot, config, existingNote.filepath, recommendationStrategy);
   } else {
     const editor = process.env.EDITOR || "vi";
-    const statBefore = fs15.statSync(note.filepath).mtimeMs;
+    const statBefore = fs11.statSync(existingNote.filepath).mtimeMs;
     try {
-      execSync2(`${editor} "${note.filepath}"`, { stdio: "inherit" });
+      execSync2(`${editor} "${existingNote.filepath}"`, { stdio: "inherit" });
     } catch {
       console.error(`Failed to open editor: ${editor}`);
       process.exit(1);
     }
-    const statAfter = fs15.statSync(note.filepath).mtimeMs;
+    const statAfter = fs11.statSync(existingNote.filepath).mtimeMs;
     if (statAfter !== statBefore) {
-      const { frontmatter, body } = parseFrontmatter(fs15.readFileSync(note.filepath, "utf-8"));
+      const { frontmatter, body } = parseFrontmatter(fs11.readFileSync(existingNote.filepath, "utf-8"));
       frontmatter.modified = (/* @__PURE__ */ new Date()).toISOString();
-      fs15.writeFileSync(note.filepath, serializeFrontmatter(frontmatter, body), "utf-8");
-      const sync = getSyncManager(vaultRoot, config);
-      const updatedForSync = readNote(note.filepath);
-      sync?.trackAndPush(updatedForSync, "update");
-      console.log(`Updated: ${note.filepath}`);
-      printRecommendations(vaultRoot, config, note.filepath, "rebuild");
+      fs11.writeFileSync(existingNote.filepath, serializeFrontmatter(frontmatter, body), "utf-8");
+      console.log(`Updated: ${existingNote.filepath}`);
+      printRecommendations(vaultRoot, config, existingNote.filepath, "rebuild");
     }
   }
 }
@@ -2451,16 +2073,102 @@ function printRecommendations(vaultRoot, config, filepath, strategy) {
   const updatedNote = readNote(filepath);
   const recommendations = recommendNote(vaultRoot, config, updatedNote, { strategy });
   const lines = formatRecommendations(recommendations);
-  if (lines.length === 0) return;
+  if (lines.length > 0) {
+    console.log("");
+    console.log("Recommendations:");
+    for (const line of lines) {
+      console.log(line);
+    }
+  }
   console.log("");
-  console.log("Recommendations:");
-  for (const line of lines) {
-    console.log(line);
+  console.log(`Next: Check connections \u2192 granite suggest-links ${updatedNote.slug} | Compile \u2192 granite recommend ${updatedNote.slug}`);
+}
+
+// src/commands/status.ts
+function statusCommand(options = {}) {
+  const vaultRoot = requireVaultRoot();
+  const config = loadConfig(vaultRoot);
+  const notes = listNotes(vaultRoot, config);
+  const byType = {};
+  for (const note of notes) {
+    byType[note.frontmatter.type] = (byType[note.frontmatter.type] ?? 0) + 1;
+  }
+  const inbox = notes.filter((n) => n.frontmatter.status === "inbox");
+  const drafts = notes.filter((n) => n.frontmatter.review_state === "draft" && n.frontmatter.status === "active");
+  const orphans = [];
+  const db = ensureIndex(vaultRoot, config);
+  const issues = runDoctor(vaultRoot, config, db);
+  for (const note of notes.slice(0, 50)) {
+    const bl = getBacklinks(db, note.slug);
+    if (bl.length === 0 && note.outgoing_links.length === 0) {
+      orphans.push(note.slug);
+    }
+  }
+  db.close();
+  const errors = issues.filter((i) => i.level === "error");
+  const nextActions = [];
+  if (notes.length === 0) {
+    nextActions.push('Your vault is empty. Start capturing: granite add "Your first thought"');
+  } else {
+    if (inbox.length > 0) {
+      nextActions.push(`Process your inbox: ${inbox.length} note(s) waiting \u2192 granite show ${inbox[0].slug}`);
+    }
+    if (drafts.length > 0) {
+      nextActions.push(`Review drafts: ${drafts.length} active draft(s) \u2192 granite show ${drafts[0].slug}`);
+    }
+    if (errors.length > 0) {
+      nextActions.push(`Fix ${errors.length} error(s) found by doctor \u2192 granite doctor`);
+    }
+    if (orphans.length > 0) {
+      nextActions.push(`Connect ${orphans.length} orphan note(s) \u2192 granite suggest-links ${orphans[0]}`);
+    }
+    const syntheses = byType["synthesis"] ?? 0;
+    const notesAndSources = (byType["note"] ?? 0) + (byType["source"] ?? 0);
+    if (notesAndSources >= 5 && syntheses === 0) {
+      nextActions.push("You have enough notes to compile a synthesis \u2192 granite recommend <slug>");
+    }
+    if (nextActions.length === 0) {
+      nextActions.push("Vault is healthy. Keep capturing or run: granite doctor");
+    }
+  }
+  if (options.json) {
+    console.log(jsonSuccess({
+      vault_name: config.vault_name,
+      note_count: notes.length,
+      notes_by_type: byType,
+      inbox_count: inbox.length,
+      draft_count: drafts.length,
+      orphan_count: orphans.length,
+      error_count: errors.length,
+      next_actions: nextActions
+    }));
+    return;
+  }
+  console.log(`${config.vault_name}`);
+  console.log("");
+  const typeLine = Object.entries(byType).map(([type, count]) => `${count} ${type}${count > 1 ? "s" : ""}`).join(", ");
+  console.log(`  ${notes.length} notes: ${typeLine || "none"}`);
+  if (inbox.length > 0 || drafts.length > 0 || orphans.length > 0) {
+    const parts = [];
+    if (inbox.length > 0) parts.push(`${inbox.length} inbox`);
+    if (drafts.length > 0) parts.push(`${drafts.length} drafts`);
+    if (orphans.length > 0) parts.push(`${orphans.length} orphans`);
+    console.log(`  Attention: ${parts.join(", ")}`);
+  }
+  if (errors.length > 0) {
+    console.log(`  Health: ${errors.length} error(s) \u2014 run granite doctor`);
+  }
+  console.log("");
+  console.log("Next:");
+  for (const action of nextActions) {
+    console.log(`  \u2192 ${action}`);
   }
 }
 
 // src/commands/mcp.ts
-import path13 from "path";
+import fs13 from "fs";
+import path9 from "path";
+import { spawn as spawn2 } from "child_process";
 
 // src/mcp/server.ts
 import { serve as serve2 } from "@hono/node-server";
@@ -2514,6 +2222,9 @@ var noteSummarySchema = z.object({
   aliases: z.array(z.string()),
   status: z.enum(["inbox", "active", "archived"]),
   source: z.enum(["human", "agent", "extraction"]),
+  review_state: z.enum(["draft", "reviewed", "locked"]),
+  durability: z.enum(["canonical", "working", "ephemeral"]),
+  derived_from: z.array(z.string()),
   filepath: z.string(),
   resource_uri: z.string()
 });
@@ -2590,11 +2301,40 @@ function createGraniteMcpServer(runtime) {
     {
       capabilities: { logging: {} },
       instructions: [
-        "Granite exposes a local-first markdown vault.",
-        "Prefer read tools and resources first, then write with granite_create_note or granite_update_note.",
-        "Resources are read-only views; notes live on disk and the SQLite index is derived state.",
-        "Use granite_recommend_note_actions to preserve Granite\u2019s capture -> link -> recommend loop."
-      ].join(" ")
+        "# Granite \u2014 Knowledge Compilation System",
+        "",
+        "You are operating a local-first markdown knowledge base. You are the primary writer and gardener of this vault \u2014 the human rarely edits notes directly.",
+        "",
+        "## Core Loop",
+        "",
+        "Granite follows a continuous knowledge compilation loop:",
+        "",
+        "1. **Capture** \u2014 Ingest raw information quickly (granite_capture_note or granite_create_note). Don't over-structure at this stage.",
+        "2. **Compile** \u2014 Turn raw captures and sources into durable, linked notes and syntheses. Use granite_recommend_note_actions to find what to connect.",
+        "3. **Query** \u2014 Search and traverse the vault (granite_search_notes, granite_get_backlinks, granite_suggest_links) to answer questions by researching across notes.",
+        "4. **Output** \u2014 Generate audience-specific deliverables (type: output) that derive from durable notes. Always set derived_from.",
+        "5. **Lint** \u2014 Run granite_run_doctor and granite_recommend_note_actions regularly to find gaps, broken links, and opportunities to strengthen the vault.",
+        "",
+        "Every interaction should advance the vault. Queries become notes. Outputs feed back in. Knowledge compounds.",
+        "",
+        "## Note Types",
+        "",
+        "- **note**: Atomic, durable ideas \u2014 one idea per note, well-linked. The backbone of the vault.",
+        "- **source**: Imported material kept close to the original. Capture provenance, summarize essentials.",
+        "- **synthesis**: Compiled knowledge connecting multiple notes or sources. The most valuable type.",
+        "- **output**: Situational deliverables (reports, briefs). Ephemeral by default, always derived_from something durable.",
+        "",
+        "The natural flow is: source \u2192 note \u2192 synthesis \u2192 output",
+        "",
+        "## Working Principles",
+        "",
+        "- **Read before writing.** Use granite_search_notes and granite_list_notes to understand what already exists before creating new notes. Avoid duplicates.",
+        "- **Link aggressively.** Use [[wikilinks]] in note bodies. After writing, check granite_suggest_links to find missed connections.",
+        "- **Act on recommendations.** Every create/update returns recommendations \u2014 follow them. They are the compiler's suggestions for what to connect or write next.",
+        "- **Use the right type.** Don't dump everything into notes. Sources stay as sources. Syntheses emerge when you have enough connected notes.",
+        "- **Set metadata intentionally.** Use source: agent when you write, source: human when the human dictates. Use review_state: draft for first passes. Set durability to match the note's role.",
+        "- **Prefer read tools and resources first.** Resources (granite://vault/overview, granite://notes/{slug}) are lightweight reads. Use tools for writes and complex queries."
+      ].join("\n")
     }
   );
   registerTools(server, runtime);
@@ -2665,7 +2405,7 @@ async function withResponseCleanup(response, cleanup) {
 function registerTools(server, runtime) {
   server.registerTool("granite_get_vault_overview", {
     title: "Granite Vault Overview",
-    description: "Summarize the current Granite vault, including counts by type and recent notes.",
+    description: "Start here. Get a snapshot of the vault: note counts by type, recent activity, and configuration. Use this to orient yourself before reading or writing notes.",
     inputSchema: {
       recent_limit: z.number().int().min(1).max(20).optional().describe("How many recent notes to include. Defaults to 10.")
     },
@@ -2680,7 +2420,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_list_note_types", {
     title: "Granite Note Types",
-    description: "List the note types configured in the vault.",
+    description: "List the note types configured in the vault, including their templates, line limits, and instructions. Check this before creating a note to use the right type.",
     outputSchema: z.object({
       default_type: z.string(),
       note_types: z.array(noteTypeInfoSchema)
@@ -2695,7 +2435,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_list_notes", {
     title: "List Granite Notes",
-    description: "List notes from the Granite vault with optional filters.",
+    description: "Browse the vault with filters. Use this to find existing notes before creating new ones (avoid duplicates), to review inbox notes that need processing, or to find notes by type/status/source.",
     inputSchema: {
       type: z.string().optional().describe("Filter by note type."),
       status: z.enum(["inbox", "active", "archived"]).optional().describe("Filter by note status."),
@@ -2717,7 +2457,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_get_note", {
     title: "Get Granite Note",
-    description: "Read a Granite note by slug, including frontmatter, body, and resolved outgoing links.",
+    description: "Read a note in full: frontmatter, body, and resolved outgoing wikilinks. Use this to understand a note before updating it, to follow links in the knowledge graph, or to gather context for a synthesis.",
     inputSchema: {
       slug: z.string().describe("The note slug.")
     },
@@ -2735,7 +2475,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_search_notes", {
     title: "Search Granite Notes",
-    description: "Run full-text search against the Granite index.",
+    description: "Full-text search across all notes. Use this to research a topic before answering questions, to find related notes before creating a new one, or to discover connections across the vault.",
     inputSchema: {
       query: z.string().describe("Full-text query for the SQLite FTS index."),
       limit: z.number().int().min(1).max(50).optional().describe("Maximum number of search results. Defaults to 10.")
@@ -2754,7 +2494,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_create_note", {
     title: "Create Granite Note",
-    description: "Create a new note in the Granite vault.",
+    description: "Create a structured note. Use this when you have a clear title and know the type. For raw captures, prefer granite_capture_note instead. Always search first to avoid duplicates. Returns recommendations \u2014 act on them to strengthen the vault.",
     inputSchema: {
       title: z.string().describe("Note title."),
       type: z.string().optional().describe("Note type. Defaults to the vault default type."),
@@ -2762,7 +2502,10 @@ function registerTools(server, runtime) {
       tags: z.array(z.string()).optional().describe("Tags to add immediately."),
       aliases: z.array(z.string()).optional().describe("Aliases to add immediately."),
       status: z.enum(["inbox", "active", "archived"]).optional().describe("Initial note status."),
-      source: z.enum(["human", "agent", "extraction"]).optional().describe("Initial note source.")
+      source: z.enum(["human", "agent", "extraction"]).optional().describe("Initial note source."),
+      review_state: z.enum(["draft", "reviewed", "locked"]).optional().describe("Initial review state."),
+      durability: z.enum(["canonical", "working", "ephemeral"]).optional().describe("Initial durability."),
+      derived_from: z.array(z.string()).optional().describe("Source note IDs or slugs this note derives from.")
     },
     outputSchema: z.object({
       note: noteDetailsSchema,
@@ -2771,18 +2514,21 @@ function registerTools(server, runtime) {
     annotations: writeAnnotations
   }, async (args) => {
     const result = runtime.createNote(args);
-    return toolResult(result, `Created "${result.note.title}" (${result.note.slug}).`);
+    return toolResult(result, buildWriteSummary("Created", result, runtime));
   });
   server.registerTool("granite_capture_note", {
     title: "Capture Granite Note",
-    description: "Quick-capture a note from free-form text, similar to granite add.",
+    description: "Quick-capture from raw text \u2014 the fastest way to get information into the vault. The title is auto-generated. Use this for rapid ingestion (conversations, ideas, observations). The note lands in inbox status, ready to be refined later. Returns recommendations for immediate linking.",
     inputSchema: {
       text: z.string().describe("Raw capture text."),
       type: z.string().optional().describe("Optional note type override. Defaults to the vault default type."),
       tags: z.array(z.string()).optional().describe("Tags to add immediately."),
       aliases: z.array(z.string()).optional().describe("Aliases to add immediately."),
       status: z.enum(["inbox", "active", "archived"]).optional().describe("Initial note status."),
-      source: z.enum(["human", "agent", "extraction"]).optional().describe("Initial note source.")
+      source: z.enum(["human", "agent", "extraction"]).optional().describe("Initial note source."),
+      review_state: z.enum(["draft", "reviewed", "locked"]).optional().describe("Initial review state."),
+      durability: z.enum(["canonical", "working", "ephemeral"]).optional().describe("Initial durability."),
+      derived_from: z.array(z.string()).optional().describe("Source note IDs or slugs this note derives from.")
     },
     outputSchema: z.object({
       note: noteDetailsSchema,
@@ -2791,11 +2537,11 @@ function registerTools(server, runtime) {
     annotations: writeAnnotations
   }, async (args) => {
     const result = runtime.captureNote(args);
-    return toolResult(result, `Captured "${result.note.title}" (${result.note.slug}).`);
+    return toolResult(result, buildWriteSummary("Captured", result, runtime));
   });
   server.registerTool("granite_update_note", {
     title: "Update Granite Note",
-    description: "Update frontmatter or body fields for an existing Granite note.",
+    description: "Update an existing note. Use this to refine captures into durable notes, add tags and links, change status (inbox\u2192active\u2192archived), append new information, or promote review_state. Use append to add without replacing the body.",
     inputSchema: {
       slug: z.string().describe("Slug of the note to update."),
       title: z.string().optional().describe("Replace the note title."),
@@ -2804,7 +2550,10 @@ function registerTools(server, runtime) {
       tags: z.array(z.string()).optional().describe("Tags to add."),
       aliases: z.array(z.string()).optional().describe("Aliases to add."),
       status: z.enum(["inbox", "active", "archived"]).optional().describe("New note status."),
-      source: z.enum(["human", "agent", "extraction"]).optional().describe("New note source.")
+      source: z.enum(["human", "agent", "extraction"]).optional().describe("New note source."),
+      review_state: z.enum(["draft", "reviewed", "locked"]).optional().describe("New review state."),
+      durability: z.enum(["canonical", "working", "ephemeral"]).optional().describe("New durability."),
+      derived_from: z.array(z.string()).optional().describe("Source note IDs or slugs this note derives from.")
     },
     outputSchema: z.object({
       note: noteDetailsSchema,
@@ -2813,11 +2562,11 @@ function registerTools(server, runtime) {
     annotations: writeAnnotations
   }, async ({ slug, ...updates }) => {
     const result = runtime.updateNote(slug, updates);
-    return toolResult(result, `Updated "${result.note.title}" (${result.note.slug}).`);
+    return toolResult(result, buildWriteSummary("Updated", result, runtime));
   });
   server.registerTool("granite_get_backlinks", {
     title: "Granite Backlinks",
-    description: "List notes that link to a given Granite note.",
+    description: "Find all notes that link to a given note. Use this to understand a note's role in the knowledge graph, to find context for a synthesis, or to check the impact before modifying a note.",
     inputSchema: {
       slug: z.string().describe("Slug of the target note.")
     },
@@ -2835,7 +2584,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_suggest_links", {
     title: "Suggest Granite Links",
-    description: "Suggest missing wikilinks for a Granite note based on mentions.",
+    description: "Find unlinked mentions \u2014 places where a note references another note's title or alias without a [[wikilink]]. Use this after creating or updating a note to strengthen the knowledge graph.",
     inputSchema: {
       slug: z.string().describe("Slug of the note to inspect.")
     },
@@ -2853,7 +2602,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_recommend_note_actions", {
     title: "Recommend Granite Actions",
-    description: "Recommend follow-up links, tags, additions, and next notes for a Granite note.",
+    description: "The heart of Granite's compile loop. Returns suggested links, tags, content additions, and next notes to create. Call this after every write operation and act on the results \u2014 this is how the vault grows into a connected knowledge base instead of a pile of files.",
     inputSchema: {
       slug: z.string().describe("Slug of the note to analyze.")
     },
@@ -2871,7 +2620,7 @@ function registerTools(server, runtime) {
   });
   server.registerTool("granite_run_doctor", {
     title: "Run Granite Doctor",
-    description: "Validate vault health and report structural issues.",
+    description: "Lint the vault. Finds broken wikilinks, missing frontmatter fields, notes exceeding line limits, and other structural issues. Run this periodically to maintain vault integrity \u2014 part of the lint phase of the knowledge loop.",
     outputSchema: z.object({
       issues: z.array(doctorIssueSchema),
       counts: z.object({
@@ -2951,7 +2700,7 @@ function registerResources(server, runtime) {
 function registerPrompts(server, runtime) {
   server.registerPrompt("granite_refine_note", {
     title: "Refine Granite Note",
-    description: "Create a prompt for turning a note into a cleaner permanent note draft.",
+    description: "Turn a raw capture or draft into a durable, well-structured note. Use this on inbox notes to promote them to active status.",
     argsSchema: {
       slug: z.string().describe("Slug of the note to refine.")
     }
@@ -2965,7 +2714,7 @@ function registerPrompts(server, runtime) {
           content: {
             type: "text",
             text: [
-              "Refine the attached Granite note into a durable, well-structured permanent note.",
+              "Refine the attached Granite note into a durable, well-structured note.",
               "Keep the meaning intact, avoid inventing facts, preserve useful wikilinks, and use Granite-style headings when appropriate."
             ].join(" ")
           }
@@ -2986,7 +2735,7 @@ function registerPrompts(server, runtime) {
   });
   server.registerPrompt("granite_review_connections", {
     title: "Review Granite Connections",
-    description: "Create a prompt for improving note links, tags, and next steps.",
+    description: "Analyze a note's place in the knowledge graph and propose better links, tags, and the most valuable follow-up note to create.",
     argsSchema: {
       slug: z.string().describe("Slug of the note to inspect.")
     }
@@ -3028,6 +2777,142 @@ function registerPrompts(server, runtime) {
       ]
     };
   });
+  server.registerPrompt("granite_process_inbox", {
+    title: "Process Granite Inbox",
+    description: "Review all inbox notes and decide what to do with each: refine into a durable note, merge into an existing note, archive, or delete. This is the compile phase of the knowledge loop."
+  }, async () => {
+    const inboxNotes = runtime.listNotes({ status: "inbox", limit: 50 });
+    const overview = runtime.getVaultOverview(5);
+    return {
+      description: "Process the inbox: triage, refine, and compile captured notes.",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Process the Granite inbox. For each inbox note below, decide:",
+              "",
+              "1. **Refine** \u2014 If it contains a durable idea, refine it into a well-structured note (update body, set status: active, review_state: reviewed).",
+              "2. **Merge** \u2014 If it overlaps with an existing note, append the new information to that note and archive the inbox note.",
+              "3. **Promote to source** \u2014 If it's raw reference material, update its type to source and refine it.",
+              "4. **Archive** \u2014 If it's been processed or is no longer relevant, set status: archived.",
+              "",
+              "After processing each note, run granite_suggest_links to find connections, and granite_recommend_note_actions to see what to write next.",
+              "",
+              `Vault context: ${overview.note_count} notes total (${Object.entries(overview.notes_by_type).map(([t, c]) => `${c} ${t}s`).join(", ")}).`,
+              "",
+              `Inbox notes to process (${inboxNotes.length}):`,
+              "",
+              ...inboxNotes.map((n) => `- **${n.slug}**: "${n.title}" (type: ${n.type}, created: ${n.created})`)
+            ].join("\n")
+          }
+        }
+      ]
+    };
+  });
+  server.registerPrompt("granite_compile_synthesis", {
+    title: "Compile Granite Synthesis",
+    description: "Analyze a set of related notes and compile them into a synthesis note \u2014 the most valuable operation in the knowledge loop. Creates durable compiled knowledge from scattered notes.",
+    argsSchema: {
+      topic: z.string().describe("The topic or theme to synthesize notes around.")
+    }
+  }, async ({ topic }) => {
+    const searchResults = runtime.search(topic, 20);
+    const noteDetails = searchResults.map((r) => {
+      try {
+        return runtime.getNote(r.slug);
+      } catch {
+        return null;
+      }
+    }).filter(Boolean);
+    return {
+      description: `Compile a synthesis on "${topic}" from ${noteDetails.length} related notes.`,
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              `Compile a synthesis note on "${topic}" from the related notes below.`,
+              "",
+              "A good synthesis:",
+              "- Connects ideas across multiple sources and notes",
+              "- Identifies patterns, tensions, and open questions",
+              "- Uses [[wikilinks]] to link back to every source note",
+              "- Sets derived_from to the slugs of the notes it draws from",
+              "- Is more valuable than any individual note because it creates new understanding",
+              "",
+              "Steps:",
+              "1. Read the related notes below",
+              "2. Create a synthesis note (type: synthesis) with granite_create_note",
+              "3. Write a body that connects the key ideas, with [[wikilinks]] to sources",
+              "4. Set derived_from to the source note slugs",
+              "5. Run granite_recommend_note_actions on the new synthesis",
+              "",
+              `Related notes (${noteDetails.length} found for "${topic}"):`,
+              "",
+              ...noteDetails.map((n) => n ? [
+                `### ${n.title} (${n.slug}, type: ${n.type})`,
+                n.body.slice(0, 500) + (n.body.length > 500 ? "..." : ""),
+                ""
+              ].join("\n") : "")
+            ].join("\n")
+          }
+        }
+      ]
+    };
+  });
+  server.registerPrompt("granite_vault_health_review", {
+    title: "Granite Vault Health Review",
+    description: "Run a comprehensive vault review: structural health, content gaps, orphan notes, and suggestions for strengthening the knowledge graph. The lint phase of the knowledge loop."
+  }, async () => {
+    const doctorResult = runtime.runDoctor();
+    const overview = runtime.getVaultOverview(10);
+    const notes = runtime.listNotes({ limit: 200 });
+    const orphanCandidates = [];
+    for (const note of notes.slice(0, 50)) {
+      const backlinks = runtime.getBacklinks(note.slug);
+      if (backlinks.length === 0) {
+        orphanCandidates.push(`${note.slug} ("${note.title}", type: ${note.type})`);
+      }
+    }
+    return {
+      description: "Comprehensive vault health review.",
+      messages: [
+        {
+          role: "user",
+          content: {
+            type: "text",
+            text: [
+              "Run a comprehensive health review of this Granite vault and take action to improve it.",
+              "",
+              "## Structural Issues (from granite_run_doctor)",
+              "",
+              doctorResult.issues.length === 0 ? "No structural issues found." : doctorResult.issues.map((i) => `- [${i.level}] ${i.file}: ${i.message}`).join("\n"),
+              "",
+              "## Vault Overview",
+              "",
+              `${overview.note_count} notes: ${Object.entries(overview.notes_by_type).map(([t, c]) => `${c} ${t}s`).join(", ")}`,
+              "",
+              "## Orphan Notes (no backlinks)",
+              "",
+              orphanCandidates.length === 0 ? "No orphans found in the first 50 notes." : orphanCandidates.map((o) => `- ${o}`).join("\n"),
+              "",
+              "## Actions to Take",
+              "",
+              "1. Fix any structural errors reported by doctor",
+              "2. For each orphan note, use granite_suggest_links and granite_recommend_note_actions to find connections",
+              "3. If orphan notes should be linked from other notes, update those notes to add [[wikilinks]]",
+              "4. Look for clusters of notes that could be compiled into a synthesis",
+              "5. Check if any inbox notes need processing",
+              "6. Report a summary of what you found and what you fixed"
+            ].join("\n")
+          }
+        }
+      ]
+    };
+  });
 }
 function toolResult(structuredContent, summary) {
   return {
@@ -3044,6 +2929,18 @@ function createNoteResourceLink(name, uri) {
     description: "Read the markdown resource for this note."
   };
 }
+function buildWriteSummary(verb, result, runtime) {
+  const lines = [`${verb} "${result.note.title}" (${result.note.slug}).`];
+  const instructions = runtime.getTypeInstructions(result.note.type);
+  if (instructions) {
+    lines.push("", `Type guidance for "${result.note.type}": ${instructions}`);
+  }
+  const recSummary = recommendationSummary(result.recommendations);
+  if (recSummary) {
+    lines.push("", `Recommendations: ${recSummary}. Act on these to strengthen the vault.`);
+  }
+  return lines.join("\n");
+}
 function recommendationSummary(recommendations) {
   return [
     `${recommendations.links.length} link suggestion(s)`,
@@ -3158,8 +3055,8 @@ function corsHeaders(origin, allowedOrigins) {
 }
 
 // src/mcp/runtime.ts
-import fs16 from "fs";
-import path12 from "path";
+import fs12 from "fs";
+import path8 from "path";
 var GraniteMcpRuntime = class {
   vaultRoot;
   config;
@@ -3168,7 +3065,7 @@ var GraniteMcpRuntime = class {
   lastSignature;
   lastIndexCheckAt = 0;
   constructor(vaultRoot, options = {}) {
-    this.vaultRoot = path12.resolve(vaultRoot);
+    this.vaultRoot = path8.resolve(vaultRoot);
     this.config = loadConfig(this.vaultRoot);
     this.db = openDatabase(this.vaultRoot);
     this.indexCheckIntervalMs = options.indexCheckIntervalMs ?? 1500;
@@ -3280,7 +3177,10 @@ var GraniteMcpRuntime = class {
       tags: input.tags,
       aliases: input.aliases,
       status: input.status,
-      source: input.source
+      source: input.source,
+      review_state: input.review_state,
+      durability: input.durability,
+      derived_from: input.derived_from
     };
     if (hasMetadataMutations(metadataMutations)) {
       this.applyMutations(created.filepath, metadataMutations);
@@ -3301,7 +3201,10 @@ var GraniteMcpRuntime = class {
       tags: input.tags,
       aliases: input.aliases,
       status: input.status,
-      source: input.source
+      source: input.source,
+      review_state: input.review_state,
+      durability: input.durability,
+      derived_from: input.derived_from
     });
   }
   updateNote(slug, input) {
@@ -3321,7 +3224,7 @@ var GraniteMcpRuntime = class {
     };
   }
   readVaultConfigRaw() {
-    return fs16.readFileSync(path12.join(this.vaultRoot, CONFIG_FILENAME), "utf-8");
+    return fs12.readFileSync(path8.join(this.vaultRoot, CONFIG_FILENAME), "utf-8");
   }
   readVaultTypesJson() {
     return JSON.stringify({
@@ -3334,12 +3237,15 @@ var GraniteMcpRuntime = class {
   }
   readNoteMarkdown(slug) {
     const note = this.requireNote(slug);
-    return fs16.readFileSync(note.filepath, "utf-8");
+    return fs12.readFileSync(note.filepath, "utf-8");
   }
   completeSlugs(prefix = "") {
     const normalizedPrefix = prefix.toLowerCase();
     return this.readAllNotes().sort((a, b) => b.frontmatter.modified.localeCompare(a.frontmatter.modified)).map((note) => note.slug).filter((slug) => slug.toLowerCase().startsWith(normalizedPrefix)).slice(0, 25);
   }
+  getTypeInstructions(typeName) {
+    return this.config.note_types[typeName]?.instructions;
+  }
   noteResourceUri(slug) {
     return `granite://notes/${encodeURIComponent(slug)}`;
   }
@@ -3390,12 +3296,15 @@ var GraniteMcpRuntime = class {
       aliases: note.frontmatter.aliases,
       status: note.frontmatter.status,
       source: note.frontmatter.source,
+      review_state: note.frontmatter.review_state,
+      durability: note.frontmatter.durability,
+      derived_from: note.frontmatter.derived_from,
       filepath: note.filepath,
       resource_uri: this.noteResourceUri(note.slug)
     };
   }
   applyMutations(filepath, input) {
-    const raw = fs16.readFileSync(filepath, "utf-8");
+    const raw = fs12.readFileSync(filepath, "utf-8");
     const { frontmatter, body: existingBody } = parseFrontmatter(raw);
     let body = existingBody;
     if (input.title !== void 0) {
@@ -3415,6 +3324,17 @@ var GraniteMcpRuntime = class {
       validateSource(input.source);
       frontmatter.source = input.source;
     }
+    if (input.review_state !== void 0) {
+      validateReviewState(input.review_state);
+      frontmatter.review_state = input.review_state;
+    }
+    if (input.durability !== void 0) {
+      validateDurability(input.durability);
+      frontmatter.durability = input.durability;
+    }
+    if (input.derived_from !== void 0) {
+      frontmatter.derived_from = [...input.derived_from];
+    }
     if (input.body !== void 0) {
       body = ensureTrailingNewline(input.body);
     }
@@ -3424,7 +3344,7 @@ ${input.append}
 `;
     }
     frontmatter.modified = (/* @__PURE__ */ new Date()).toISOString();
-    fs16.writeFileSync(filepath, serializeFrontmatter(frontmatter, body), "utf-8");
+    fs12.writeFileSync(filepath, serializeFrontmatter(frontmatter, body), "utf-8");
   }
   afterWrite(slug, fullRebuild) {
     if (fullRebuild) {
@@ -3449,16 +3369,16 @@ ${input.append}
     let noteCount = 0;
     let latestNoteMtimeMs = 0;
     for (const typeConfig of Object.values(this.config.note_types)) {
-      const folder = path12.join(this.vaultRoot, typeConfig.folder);
-      if (!fs16.existsSync(folder)) {
+      const folder = path8.join(this.vaultRoot, typeConfig.folder);
+      if (!fs12.existsSync(folder)) {
         continue;
       }
-      for (const entry of fs16.readdirSync(folder)) {
+      for (const entry of fs12.readdirSync(folder)) {
         if (!entry.endsWith(".md")) {
           continue;
         }
         noteCount += 1;
-        const stat = fs16.statSync(path12.join(folder, entry));
+        const stat = fs12.statSync(path8.join(folder, entry));
         latestNoteMtimeMs = Math.max(latestNoteMtimeMs, stat.mtimeMs);
       }
     }
@@ -3470,8 +3390,8 @@ ${input.append}
     };
   }
   getConfigMtimeMs() {
-    const configPath = path12.join(this.vaultRoot, CONFIG_FILENAME);
-    return fs16.existsSync(configPath) ? fs16.statSync(configPath).mtimeMs : 0;
+    const configPath = path8.join(this.vaultRoot, CONFIG_FILENAME);
+    return fs12.existsSync(configPath) ? fs12.statSync(configPath).mtimeMs : 0;
   }
   getLastRebuildMs() {
     const value = this.getMetaValue("last_rebuild");
@@ -3504,15 +3424,215 @@ function mergeUnique(existing, incoming) {
   return [...merged];
 }
 function hasMetadataMutations(input) {
-  return (input.tags?.length ?? 0) > 0 || (input.aliases?.length ?? 0) > 0 || input.status !== void 0 || input.source !== void 0;
+  return (input.tags?.length ?? 0) > 0 || (input.aliases?.length ?? 0) > 0 || input.status !== void 0 || input.source !== void 0 || input.review_state !== void 0 || input.durability !== void 0 || (input.derived_from?.length ?? 0) > 0;
+}
+
+// src/tunnel.ts
+import { spawn } from "child_process";
+async function startTunnel(options) {
+  if (options.provider === "cloudflare") {
+    return startCloudflareTunnel(options);
+  }
+  return startTailscaleFunnel(options);
+}
+function stopTunnel(tunnelProcess) {
+  if (!tunnelProcess.killed) {
+    tunnelProcess.kill("SIGTERM");
+  }
+}
+function spawnError(binary, installUrl, err) {
+  if (err.code === "ENOENT") {
+    return new Error(`${binary} is not installed. Install it from ${installUrl}`);
+  }
+  return new Error(`Failed to start ${binary}: ${err.message}`);
+}
+function startCloudflareTunnel(options) {
+  return new Promise((resolve, reject) => {
+    const localUrl = `http://${options.host}:${options.port}`;
+    const child = spawn("cloudflared", ["tunnel", "--url", localUrl], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let settled = false;
+    const settle = (fn) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+    const onData = (chunk) => {
+      const match = chunk.toString().match(/https:\/\/[^\s]+\.trycloudflare\.com/);
+      if (match) {
+        clearTimeout(timer);
+        settle(() => resolve({ url: match[0], process: child }));
+      }
+    };
+    child.stderr?.on("data", onData);
+    child.stdout?.on("data", onData);
+    child.on("error", (err) => {
+      clearTimeout(timer);
+      settle(() => reject(spawnError(
+        "cloudflared",
+        "https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
+        err
+      )));
+    });
+    child.on("exit", (code) => {
+      clearTimeout(timer);
+      settle(() => reject(new Error(`cloudflared exited with code ${code} before establishing tunnel`)));
+    });
+    const timer = setTimeout(() => {
+      child.kill("SIGTERM");
+      settle(() => reject(new Error("Timed out waiting for cloudflared to establish tunnel")));
+    }, 3e4);
+  });
+}
+async function getTailscaleHostname() {
+  return new Promise((resolve, reject) => {
+    const status = spawn("tailscale", ["status", "--json"], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let settled = false;
+    let output = "";
+    status.stdout?.on("data", (chunk) => {
+      output += chunk.toString();
+    });
+    status.on("error", (err) => {
+      if (!settled) {
+        settled = true;
+        reject(spawnError("tailscale", "https://tailscale.com/download", err));
+      }
+    });
+    status.on("exit", (code) => {
+      if (settled) return;
+      settled = true;
+      if (code !== 0) {
+        reject(new Error(`tailscale status exited with code ${code}. Is Tailscale running?`));
+        return;
+      }
+      try {
+        const parsed = JSON.parse(output);
+        const dnsName = parsed.Self?.DNSName ?? "";
+        const hostname = dnsName.replace(/\.$/, "");
+        if (!hostname) {
+          reject(new Error("Could not determine Tailscale hostname"));
+        } else {
+          resolve(hostname);
+        }
+      } catch {
+        reject(new Error("Failed to parse tailscale status output"));
+      }
+    });
+  });
+}
+async function startTailscaleFunnel(options) {
+  const hostname = await getTailscaleHostname();
+  const publicUrl = `https://${hostname}:${options.port}`;
+  return new Promise((resolve, reject) => {
+    const child = spawn("tailscale", ["funnel", String(options.port)], {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let settled = false;
+    child.on("error", (err) => {
+      if (!settled) {
+        settled = true;
+        reject(new Error(`Failed to start tailscale funnel: ${err.message}`));
+      }
+    });
+    const timer = setTimeout(() => {
+      settled = true;
+      resolve({ url: publicUrl, process: child });
+    }, 2e3);
+    child.on("exit", (exitCode) => {
+      if (!settled) {
+        settled = true;
+        clearTimeout(timer);
+        reject(new Error(
+          `tailscale funnel exited with code ${exitCode}. Make sure Tailscale Funnel is enabled: https://tailscale.com/kb/1223/funnel`
+        ));
+      }
+    });
+  });
 }
 
 // src/commands/mcp.ts
+function pidPath(vaultRoot) {
+  return path9.join(getGraniteDir(vaultRoot), "mcp.pid");
+}
+function urlPath(vaultRoot) {
+  return path9.join(getGraniteDir(vaultRoot), "mcp.url");
+}
+function ensureGraniteDir(vaultRoot) {
+  fs13.mkdirSync(getGraniteDir(vaultRoot), { recursive: true });
+}
+function readPid(vaultRoot) {
+  try {
+    const raw = fs13.readFileSync(pidPath(vaultRoot), "utf-8").trim();
+    const pid = Number.parseInt(raw, 10);
+    if (Number.isNaN(pid)) return null;
+    try {
+      process.kill(pid, 0);
+      return pid;
+    } catch {
+      return null;
+    }
+  } catch {
+    return null;
+  }
+}
+function writeDaemonState(vaultRoot, pid, url) {
+  ensureGraniteDir(vaultRoot);
+  fs13.writeFileSync(pidPath(vaultRoot), String(pid), "utf-8");
+  fs13.writeFileSync(urlPath(vaultRoot), url, "utf-8");
+}
+function cleanupFiles(vaultRoot) {
+  try {
+    fs13.unlinkSync(pidPath(vaultRoot));
+  } catch {
+  }
+  try {
+    fs13.unlinkSync(urlPath(vaultRoot));
+  } catch {
+  }
+}
 async function mcpCommand(options) {
-  const transport = parseTransport(options.transport);
+  const tunnel = options.tunnel;
+  const transport = tunnel ? "http" : parseTransport(options.transport);
   const vaultRoot = resolveVaultRoot(options.vault);
+  if (options.background) {
+    if (transport !== "http") {
+      console.error("--background requires --transport http or --tunnel");
+      process.exit(1);
+    }
+    const running = readPid(vaultRoot);
+    if (running) {
+      console.error(`MCP server already running (PID ${running}). Use "granite mcp stop" first.`);
+      process.exit(1);
+    }
+    const logFile = path9.join(getGraniteDir(vaultRoot), "mcp.log");
+    ensureGraniteDir(vaultRoot);
+    const fd = fs13.openSync(logFile, "a");
+    const child = spawn2(process.execPath, process.argv.slice(1), {
+      detached: true,
+      stdio: ["ignore", fd, fd],
+      env: { ...process.env, GRANITE_MCP_DAEMONIZED: "1" }
+    });
+    child.unref();
+    fs13.closeSync(fd);
+    if (!child.pid) {
+      console.error("Failed to start background process");
+      process.exit(1);
+    }
+    writeDaemonState(vaultRoot, child.pid, "(starting...)");
+    console.error(`MCP server starting in background (PID ${child.pid})`);
+    console.error(`Log: ${logFile}`);
+    console.error(`Stop with: granite mcp stop`);
+    process.exit(0);
+  }
+  const isDaemon = process.env.GRANITE_MCP_DAEMONIZED === "1";
   const runtime = new GraniteMcpRuntime(vaultRoot);
+  let tunnelProcess = null;
   const shutdown = () => {
+    if (tunnelProcess) stopTunnel(tunnelProcess);
+    if (isDaemon) cleanupFiles(vaultRoot);
     runtime.close();
     process.exit(0);
   };
@@ -3520,23 +3640,74 @@ async function mcpCommand(options) {
   process.once("SIGTERM", shutdown);
   if (transport === "http") {
     const port = parsePort(options.port);
+    const host = options.host ?? "127.0.0.1";
+    const localUrl = `http://${host}:${port}/mcp`;
     startGraniteMcpHttpServer(runtime, {
-      host: options.host ?? "127.0.0.1",
+      host,
       port,
       allowedOrigins: options.allowOrigin ?? [],
       jsonResponse: options.jsonResponse ?? false
     });
+    if (isDaemon) writeDaemonState(vaultRoot, process.pid, localUrl);
+    if (tunnel) {
+      try {
+        console.error(`
+Starting ${tunnel} tunnel...`);
+        const result = await startTunnel({ provider: tunnel, port, host });
+        tunnelProcess = result.process;
+        const publicMcpUrl = `${result.url}/mcp`;
+        console.error(`
+\u{1F687} Tunnel active!
+`);
+        console.error(`  Public MCP endpoint: ${publicMcpUrl}`);
+        console.error(`  Provider: ${tunnel}`);
+        console.error(`
+Use this URL in your remote MCP client configuration.
+`);
+        if (isDaemon) writeDaemonState(vaultRoot, process.pid, publicMcpUrl);
+      } catch (err) {
+        console.error(`
+Failed to start tunnel: ${err instanceof Error ? err.message : err}`);
+        shutdown();
+      }
+    }
     return;
   }
   await startGraniteMcpStdioServer(runtime);
 }
+function mcpStopCommand(options) {
+  const vaultRoot = resolveVaultRoot(options.vault);
+  const pid = readPid(vaultRoot);
+  if (!pid) {
+    console.error("No running MCP server found.");
+    process.exit(1);
+  }
+  process.kill(pid, "SIGTERM");
+  cleanupFiles(vaultRoot);
+  console.error(`MCP server stopped (PID ${pid}).`);
+}
+function mcpStatusCommand(options) {
+  const vaultRoot = resolveVaultRoot(options.vault);
+  const pid = readPid(vaultRoot);
+  if (!pid) {
+    console.error("MCP server is not running.");
+    process.exit(1);
+  }
+  let url = "";
+  try {
+    url = fs13.readFileSync(urlPath(vaultRoot), "utf-8").trim();
+  } catch {
+  }
+  console.error(`MCP server is running (PID ${pid})`);
+  if (url) console.error(`  Endpoint: ${url}`);
+}
 function resolveVaultRoot(explicitVault) {
   const fromEnv = process.env.GRANITE_VAULT;
   if (explicitVault) {
-    return path13.resolve(explicitVault);
+    return path9.resolve(explicitVault);
   }
   if (fromEnv) {
-    return path13.resolve(fromEnv);
+    return path9.resolve(fromEnv);
   }
   return requireVaultRoot();
 }
@@ -3559,141 +3730,62 @@ function parsePort(value) {
   return parsed;
 }
 
-// src/commands/sync.ts
-async function syncCommand(options) {
-  const vaultRoot = requireVaultRoot();
-  const config = loadConfig(vaultRoot);
-  const manager = new SyncManager(vaultRoot, config);
-  const result = await manager.sync();
-  if (options.json) {
-    console.log(JSON.stringify(result));
-    return;
-  }
-  console.log(`Sync complete: ${result.pushed} pushed, ${result.pulled} pulled`);
-  if (result.conflicts > 0) {
-    console.log(`  ${result.conflicts} conflict(s) resolved (backups in .granite/conflicts/)`);
-  }
-}
-async function syncStatusCommand(options) {
-  const vaultRoot = requireVaultRoot();
-  const config = loadConfig(vaultRoot);
-  const manager = new SyncManager(vaultRoot, config);
-  const status = manager.status();
-  const conflictFiles = manager.conflicts();
-  if (options.json) {
-    console.log(JSON.stringify({ ...status, conflicts: conflictFiles.length }));
-    return;
-  }
-  console.log(`Device:          ${status.device_name} (${status.device_id.slice(0, 8)}...)`);
-  console.log(`Last sync:       ${status.last_sync ?? "never"}`);
-  console.log(`Pending changes: ${status.pending_changes}`);
-  console.log(`Server seq:      ${status.server_seq}`);
-  if (conflictFiles.length > 0) {
-    console.log(`Conflicts:       ${conflictFiles.length} file(s) in .granite/conflicts/`);
-  }
-}
-async function syncDevicesCommand(options) {
-  const vaultRoot = requireVaultRoot();
-  const config = loadConfig(vaultRoot);
-  const manager = new SyncManager(vaultRoot, config);
-  const devices = await manager.devices();
-  if (options.json) {
-    console.log(JSON.stringify(devices));
-    return;
-  }
-  if (devices.length === 0) {
-    console.log("No devices registered yet.");
-    return;
-  }
-  for (const d of devices) {
-    console.log(`  ${d.device_name} (${d.device_id.slice(0, 8)}...) \u2014 last seen ${d.last_seen}`);
-  }
-}
-function syncConflictsCommand(options) {
-  const vaultRoot = requireVaultRoot();
-  if (options.clear) {
-    const cleared = clearResolvedConflicts(vaultRoot);
-    if (options.json) {
-      console.log(JSON.stringify({ cleared }));
-    } else {
-      console.log(`Cleared ${cleared} conflict file(s).`);
-    }
-    return;
-  }
-  const files = listConflicts(vaultRoot);
-  if (options.json) {
-    console.log(JSON.stringify({ conflicts: files }));
-    return;
-  }
-  if (files.length === 0) {
-    console.log("No conflicts.");
-    return;
-  }
-  console.log(`${files.length} conflict file(s):`);
-  for (const f of files) {
-    console.log(`  ${f}`);
-  }
-}
-
 // src/index.ts
 var program = new Command();
-program.name("granite").description("Granite \u2014 a local-first markdown memory system").version(GRANITE_VERSION);
-program.command("init").description("Initialize the default vault in ~/.granite").action(() => {
+program.name("granite").description("Granite \u2014 a local-first knowledge compiler. capture \u2192 compile \u2192 query \u2192 output \u2192 lint").version(GRANITE_VERSION);
+program.command("init").description("Create a new vault and start the knowledge loop").action(() => {
   initVault();
 });
-program.command("new").description("Create a new note").argument("<title>", "Note title").option("-t, --type <type>", "Note type (e.g. fleeting, permanent, reference)").option("--source <source>", "Set source (human, agent, extraction)").option("--status <status>", "Set status (inbox, active, archived)").option("--json", "Output as JSON (agent-friendly)").action((title, options) => {
+program.command("status").description("See where your vault stands and what to do next").option("--json", "Output as JSON").action((options) => {
+  statusCommand(options);
+});
+program.command("new").description("Create a structured note \u2014 search first to avoid duplicates").argument("<title>", "Note title").option("-t, --type <type>", "Note type (note, source, synthesis, output)").option("--source <source>", "Who created it (human, agent, extraction)").option("--status <status>", "Lifecycle state (inbox, active, archived)").option("--review-state <state>", "Editorial state (draft, reviewed, locked)").option("--durability <durability>", "Knowledge permanence (canonical, working, ephemeral)").option("--derived-from <refs>", "Provenance: slugs this note derives from (comma-separated)").option("--json", "Output as JSON (agent-friendly)").action((title, options) => {
   newNote(title, options);
 });
-program.command("add").description("Quick-capture a fleeting note (reads stdin if no text given)").argument("[text]", "Note text (or pipe via stdin)").option("--json", "Output as JSON (agent-friendly)").action((text, options) => {
+program.command("add").description("Quick-capture raw text into the vault \u2014 the fastest way to get something in").argument("[text]", "Note text (or pipe via stdin)").option("--json", "Output as JSON (agent-friendly)").action((text, options) => {
   addNote(text, options);
 });
-program.command("list").alias("ls").description("List notes").option("-t, --type <type>", "Filter by note type").option("-s, --status <status>", "Filter by status (inbox, active, archived)").option("--source <source>", "Filter by source (human, agent, extraction)").option("--since <date>", "Filter notes modified since date (YYYY-MM-DD)").option("--json [fields]", "Output as JSON; optionally specify fields (e.g. --json slug,title,type)").action((options) => {
+program.command("list").alias("ls").description("Browse the vault \u2014 filter by type, status, source, or date").option("-t, --type <type>", "Filter by note type").option("-s, --status <status>", "Filter by status (inbox, active, archived)").option("--source <source>", "Filter by source (human, agent, extraction)").option("--since <date>", "Only notes modified since (YYYY-MM-DD)").option("--json [fields]", "Output as JSON; optionally select fields (e.g. --json slug,title,type)").action((options) => {
   listCommand(options);
 });
-program.command("edit").description("Edit a note (opens $EDITOR, or use flags for programmatic edits)").argument("<slug>", "Note slug").option("--body <text>", "Replace the note body").option("--append <text>", "Append text to the note body").option("--title <title>", "Update the note title").option("--tag <tags>", "Add tags (comma-separated)").option("--alias <aliases>", "Add aliases (comma-separated)").option("--status <status>", "Set status (inbox, active, archived)").option("--source <source>", "Set source (human, agent, extraction)").action((slug, options) => {
-  editCommand(slug, options);
-});
-program.command("open").description("Open a note in your editor (alias for edit)").argument("<slug>", "Note slug").action((slug) => {
-  openNote(slug);
-});
-program.command("show").alias("cat").description("Display a note by slug").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").option("--body", "Output body only (no frontmatter)").action((slug, options) => {
+program.command("show").alias("cat").description("Read a note in full \u2014 frontmatter, body, and metadata").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").option("--body", "Output body only (for piping)").action((slug, options) => {
   showCommand(slug, options);
 });
-program.command("search").description("Full-text search across notes").argument("<query>", "Search query").option("--json", "Output as JSON (agent-friendly)").action((query, options) => {
+program.command("search").description("Research a topic across the vault \u2014 use before creating to avoid duplicates").argument("<query>", "Search query").option("--json", "Output as JSON (agent-friendly)").action((query, options) => {
   searchCommand(query, options);
 });
-program.command("backlinks").description("Show notes that link to a given note").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").action((slug, options) => {
+program.command("edit").description("Refine a note \u2014 append, rewrite, promote status, add tags and links").argument("<slug>", "Note slug").option("--body <text>", "Replace the note body").option("--append <text>", "Append text to the note body").option("--title <title>", "Update the note title").option("--tag <tags>", "Add tags (comma-separated)").option("--alias <aliases>", "Add aliases (comma-separated)").option("--status <status>", "Set status (inbox, active, archived)").option("--source <source>", "Set source (human, agent, extraction)").option("--review-state <state>", "Set review state (draft, reviewed, locked)").option("--durability <durability>", "Set durability (canonical, working, ephemeral)").option("--derived-from <refs>", "Set derived_from references (comma-separated slugs)").action((slug, options) => {
+  editCommand(slug, options);
+});
+program.command("open").description("Open a note in your editor").argument("<slug>", "Note slug").action((slug) => {
+  openNote(slug);
+});
+program.command("backlinks").description("See a note's role in the graph \u2014 who links here and why").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").action((slug, options) => {
   backlinksCommand(slug, options);
 });
-program.command("suggest-links").description("Suggest wikilinks based on unlinked mentions").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").action((slug, options) => {
+program.command("suggest-links").description("Find unlinked mentions \u2014 strengthen the graph by adding missed [[wikilinks]]").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").action((slug, options) => {
   suggestLinksCommand(slug, options);
 });
-program.command("recommend").description("Suggest links, tags, and the next note to create").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").action((slug, options) => {
+program.command("recommend").description("The heart of the compile loop \u2014 what to link, tag, and write next").argument("<slug>", "Note slug").option("--json", "Output as JSON (agent-friendly)").action((slug, options) => {
   recommendCommand(slug, options);
 });
-program.command("types").description("List available note types").action(() => {
-  typesCommand();
+program.command("doctor").description("Health-check the vault \u2014 broken links, missing fields, line limit violations").option("--json", "Output as JSON").action((options) => {
+  doctorCommand(options);
 });
-program.command("doctor").description("Validate vault health").action(() => {
-  doctorCommand();
+program.command("types").description("See the note types and the natural flow: source \u2192 note \u2192 synthesis \u2192 output").action(() => {
+  typesCommand();
 });
-program.command("serve").description("Start the local web UI").option("-p, --port <port>", "Port number", "4321").action((options) => {
+program.command("serve").description("Start the local web UI \u2014 browse, search, and visualize the knowledge graph").option("-p, --port <port>", "Port number", "4321").action((options) => {
   serveCommand(options);
 });
-program.command("mcp").description("Start Granite as an MCP server").option("--vault <path>", "Vault root. Defaults to the current Granite vault or $GRANITE_VAULT").option("--transport <transport>", "Transport to use: stdio or http", parseTransportOption, "stdio").option("--host <host>", "Host for HTTP transport", "127.0.0.1").option("--port <port>", "Port for HTTP transport", "3321").option("--allow-origin <origin>", "Allow an HTTP Origin for browser-based HTTP clients", collectValues, []).option("--json-response", "Prefer JSON HTTP responses instead of SSE streams").action(async (options) => {
+var mcpCmd = program.command("mcp").description("Start Granite as an MCP server").option("--vault <path>", "Vault root. Defaults to the current Granite vault or $GRANITE_VAULT").option("--transport <transport>", "Transport to use: stdio or http", parseTransportOption, "stdio").option("--host <host>", "Host for HTTP transport", "127.0.0.1").option("--port <port>", "Port for HTTP transport", "3321").option("--allow-origin <origin>", "Allow an HTTP Origin for browser-based HTTP clients", collectValues, []).option("--json-response", "Prefer JSON HTTP responses instead of SSE streams").option("--tunnel <provider>", "Expose MCP over internet via tunnel (cloudflare or tailscale)").option("--background", "Run MCP server as a background daemon").action(async (options) => {
   await mcpCommand(options);
 });
-var syncCmd = program.command("sync").description("Sync vault across devices").option("--json", "Output as JSON").action(async (options) => {
-  await syncCommand(options);
-});
-syncCmd.command("status").description("Show sync status").option("--json", "Output as JSON").action(async (options) => {
-  await syncStatusCommand(options);
-});
-syncCmd.command("devices").description("List connected devices").option("--json", "Output as JSON").action(async (options) => {
-  await syncDevicesCommand(options);
+mcpCmd.command("stop").description("Stop a background MCP server").option("--vault <path>", "Vault root").action((options) => {
+  mcpStopCommand(options);
 });
-syncCmd.command("conflicts").description("List or clear conflict files").option("--clear", "Remove all conflict backup files").option("--json", "Output as JSON").action((options) => {
-  syncConflictsCommand(options);
+mcpCmd.command("status").description("Show status of background MCP server").option("--vault <path>", "Vault root").action((options) => {
+  mcpStatusCommand(options);
 });
 await program.parseAsync();
 function collectValues(value, previous) {