@joshski/dust 0.1.100 → 0.1.101

package/dist/dust.js

@@ -7,7 +7,7 @@ var __require = /* @__PURE__ */ createRequire(import.meta.url);
 var require_package = __commonJS((exports, module) => {
   module.exports = {
     name: "@joshski/dust",
-    version: "0.1.100",
+    version: "0.1.101",
     description: "Flow state for AI coding agents",
     type: "module",
     bin: {
@@ -52,13 +52,18 @@ var require_package = __commonJS((exports, module) => {
       "./patch": {
         import: "./dist/patch.js",
         types: "./dist/patch/index.d.ts"
+      },
+      "./core-principles": {
+        import: "./dist/core-principles.js",
+        types: "./dist/core-principles.d.ts"
       }
     },
     files: [
       "dist",
       "bin",
       "lib/istanbul/minimal-reporter.cjs",
-      "biome"
+      "biome",
+      ".dust/principles"
     ],
     repository: {
       type: "git",
@@ -328,12 +333,12 @@ function readEnvConfig(env) {
 }
 
 // lib/cli/wire.ts
-import { existsSync as existsSync2, statSync as statSync2 } from "node:fs";
+import { existsSync as existsSync3, statSync as statSync3 } from "node:fs";
 import {
   chmod as chmod2,
   mkdir as mkdir2,
   readdir as readdir2,
-  readFile as readFile3,
+  readFile as readFile4,
   rename,
   writeFile as writeFile2
 } from "node:fs/promises";
@@ -359,6 +364,7 @@ import { join as join2 } from "node:path";
 var KNOWN_SETTINGS_KEYS = new Set([
   "dustCommand",
   "checks",
+  "excludeCorePrinciples",
   "extraDirectories",
   "installCommand",
   "eventsUrl"
@@ -465,6 +471,23 @@ function validateDustEventsUrl(settings) {
   }
   return [];
 }
+function validateExcludeCorePrinciples(settings) {
+  if (!("excludeCorePrinciples" in settings)) {
+    return [];
+  }
+  if (!Array.isArray(settings.excludeCorePrinciples)) {
+    return [{ message: '"excludeCorePrinciples" must be an array of strings' }];
+  }
+  const violations = [];
+  for (let i = 0;i < settings.excludeCorePrinciples.length; i++) {
+    if (typeof settings.excludeCorePrinciples[i] !== "string") {
+      violations.push({
+        message: `excludeCorePrinciples[${i}] must be a string`
+      });
+    }
+  }
+  return violations;
+}
 function validateSettingsJson(content) {
   const violations = [];
   let parsed;
@@ -491,6 +514,7 @@ function validateSettingsJson(content) {
     }
   }
   violations.push(...validateChecksConfig(settings));
+  violations.push(...validateExcludeCorePrinciples(settings));
   violations.push(...validateExtraDirectories(settings));
   violations.push(...validateDustEventsUrl(settings));
   if ("dustCommand" in settings && typeof settings.dustCommand !== "string") {
@@ -639,7 +663,7 @@ async function loadSettings(cwd, fileSystem, runtime) {
 }
 
 // lib/version.ts
-var DUST_VERSION = "0.1.100";
+var DUST_VERSION = "0.1.101";
 
 // lib/session.ts
 var DUST_UNATTENDED = "DUST_UNATTENDED";
@@ -6979,6 +7003,36 @@ function startRepositoryLoop(repoState, repoDeps, sendEvent, sessionId) {
 function shouldRecloneForBranchChange(existing, incoming) {
   return existing.branch !== incoming.branch;
 }
+function computeRepositoryReconciliation(existing, incoming) {
+  const actions = [];
+  for (const [name, repo] of incoming) {
+    const existingRepo = existing.get(name);
+    if (!existingRepo) {
+      actions.push({ type: "add", repository: repo });
+    } else if (shouldRecloneForBranchChange(existingRepo, repo)) {
+      const from = existingRepo.branch ?? "(default)";
+      const to = repo.branch ?? "(default)";
+      actions.push({
+        type: "reclone",
+        name,
+        repository: repo,
+        reason: `branch changed from ${from} to ${to}`
+      });
+    } else if (existingRepo.agentProvider !== repo.agentProvider) {
+      actions.push({
+        type: "updateProvider",
+        name,
+        newProvider: repo.agentProvider
+      });
+    }
+  }
+  for (const name of existing.keys()) {
+    if (!incoming.has(name)) {
+      actions.push({ type: "remove", name });
+    }
+  }
+  return actions;
+}
 function parseRepository(data) {
   if (typeof data === "object" && data !== null && "name" in data && "gitUrl" in data) {
     const repositoryData = data;
@@ -7070,34 +7124,46 @@ async function removeRepositoryFromManager(repoName, manager, repoDeps, context)
   manager.emit(removedEvent);
   context.stdout(formatBucketEvent(removedEvent));
 }
-async function handleRepositoryList(repositories, manager, repoDeps, context) {
-  const incomingRepos = new Map;
-  for (const data of repositories) {
-    const repo = parseRepository(data);
+function parseRepositoryList(data) {
+  const repos = new Map;
+  for (const item of data) {
+    const repo = parseRepository(item);
     if (repo) {
-      incomingRepos.set(repo.name, repo);
-    }
-  }
-  for (const [name, repo] of incomingRepos) {
-    const existing = manager.repositories.get(name);
-    if (!existing) {
-      await addRepository(repo, manager, repoDeps, context);
-    } else if (shouldRecloneForBranchChange(existing.repository, repo)) {
-      const from = existing.repository.branch ?? "(default)";
-      const to = repo.branch ?? "(default)";
-      log8(`${name}: branch changed from ${from} to ${to}, re-cloning`);
-      await removeRepositoryFromManager(name, manager, repoDeps, context);
-      await addRepository(repo, manager, repoDeps, context);
-    } else if (existing.repository.agentProvider !== repo.agentProvider) {
-      const from = existing.repository.agentProvider ?? "(unset)";
-      const to = repo.agentProvider ?? "(unset)";
-      log8(`${name}: agentProvider changed from ${from} to ${to}`);
-      existing.repository.agentProvider = repo.agentProvider;
+      repos.set(repo.name, repo);
     }
   }
-  for (const name of manager.repositories.keys()) {
-    if (!incomingRepos.has(name)) {
-      await removeRepositoryFromManager(name, manager, repoDeps, context);
+  return repos;
+}
+async function handleRepositoryList(repositories, manager, repoDeps, context) {
+  const incoming = parseRepositoryList(repositories);
+  const existing = new Map;
+  for (const [name, state] of manager.repositories) {
+    existing.set(name, state.repository);
+  }
+  const actions = computeRepositoryReconciliation(existing, incoming);
+  for (const action of actions) {
+    switch (action.type) {
+      case "add":
+        await addRepository(action.repository, manager, repoDeps, context);
+        break;
+      case "remove":
+        await removeRepositoryFromManager(action.name, manager, repoDeps, context);
+        break;
+      case "reclone":
+        log8(`${action.name}: ${action.reason}, re-cloning`);
+        await removeRepositoryFromManager(action.name, manager, repoDeps, context);
+        await addRepository(action.repository, manager, repoDeps, context);
+        break;
+      case "updateProvider": {
+        const repoState = manager.repositories.get(action.name);
+        if (!repoState)
+          break;
+        const from = repoState.repository.agentProvider ?? "(unset)";
+        const to = action.newProvider ?? "(unset)";
+        log8(`${action.name}: agentProvider changed from ${from} to ${to}`);
+        repoState.repository.agentProvider = action.newProvider;
+        break;
+      }
     }
   }
 }
@@ -7199,7 +7265,7 @@ function parseRepositoryItem(r) {
   }
   return item;
 }
-function parseRepositoryList(message) {
+function parseRepositoryList2(message) {
   if (!Array.isArray(message.repositories)) {
     return null;
   }
@@ -7269,7 +7335,7 @@ function parseConnectionRejected(message) {
   return result;
 }
 var messageParsers = {
-  "repository-list": parseRepositoryList,
+  "repository-list": parseRepositoryList2,
   "task-available": parseTaskAvailable,
   "tool-definitions": parseToolDefinitions,
   "connection-ready": parseConnectionReady,
@@ -9056,6 +9122,57 @@ Run \`dust bucket tool ${toolName}\` to see available operations.`);
 // lib/cli/commands/lint-markdown.ts
 import { isAbsolute, join as join9, relative, sep } from "node:path";
 
+// lib/artifacts/principles.ts
+function extractLinksFromSection(content, sectionHeading) {
+  const lines = content.split(`
+`);
+  const links = [];
+  let inSection = false;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      inSection = line.trimEnd() === `## ${sectionHeading}`;
+      continue;
+    }
+    if (!inSection)
+      continue;
+    if (line.startsWith("# "))
+      break;
+    const linkMatch = line.match(MARKDOWN_LINK_PATTERN);
+    if (linkMatch) {
+      const target = linkMatch[2];
+      const slugMatch = target.match(/([^/]+)\.md$/);
+      if (slugMatch) {
+        links.push(slugMatch[1]);
+      }
+    }
+  }
+  return links;
+}
+function extractSingleLinkFromSection(content, sectionHeading) {
+  const links = extractLinksFromSection(content, sectionHeading);
+  return links.length === 1 ? links[0] : null;
+}
+async function parsePrinciple(fileSystem, dustPath, slug) {
+  const principlePath = `${dustPath}/principles/${slug}.md`;
+  if (!fileSystem.exists(principlePath)) {
+    throw new Error(`Principle not found: "${slug}" (expected file at ${principlePath})`);
+  }
+  const content = await fileSystem.readFile(principlePath);
+  const title = extractTitle(content);
+  if (!title) {
+    throw new Error(`Principle file has no title: ${principlePath}`);
+  }
+  const parentPrinciple = extractSingleLinkFromSection(content, "Parent Principle");
+  const subPrinciples = extractLinksFromSection(content, "Sub-Principles");
+  return {
+    slug,
+    title,
+    content,
+    parentPrinciple,
+    subPrinciples
+  };
+}
+
 // lib/artifacts/index.ts
 var ARTIFACT_TYPES = [
   "facts",
@@ -10250,7 +10367,119 @@ async function init(dependencies) {
 }
 
 // lib/cli/commands/list.ts
-import { basename as basename3 } from "node:path";
+import { basename as basename3, resolve as resolve4 } from "node:path";
+
+// lib/core-principles.ts
+import { join as join10, dirname as dirname5 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { existsSync, readdirSync, statSync as statSync2 } from "node:fs";
+import { readFile as readFile3 } from "node:fs/promises";
+
+// lib/artifacts/core-principles.ts
+function sortNodes(nodes) {
+  nodes.sort((a, b) => a.title.localeCompare(b.title));
+  for (const node of nodes) {
+    sortNodes(node.children);
+  }
+}
+function isInternalPrinciple(principleContent) {
+  const lines = principleContent.split(`
+`);
+  let inApplicabilitySection = false;
+  for (const line of lines) {
+    if (line.startsWith("## ")) {
+      inApplicabilitySection = line.trimEnd() === "## Applicability";
+      continue;
+    }
+    if (inApplicabilitySection) {
+      if (line.startsWith("# "))
+        break;
+      if (line.trim() === "Internal") {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function getCorePrincipleTree(allPrinciples, config) {
+  const excludeSet = new Set(config.excludeCorePrinciples ?? []);
+  const filteredPrinciples = allPrinciples.filter((p) => !isInternalPrinciple(p.content) && !excludeSet.has(p.slug));
+  const filteredSlugs = new Set(filteredPrinciples.map((p) => p.slug));
+  const nodeBySlug = new Map;
+  for (const p of filteredPrinciples) {
+    nodeBySlug.set(p.slug, {
+      slug: p.slug,
+      title: p.title,
+      children: []
+    });
+  }
+  const roots = [];
+  for (const p of filteredPrinciples) {
+    const node = nodeBySlug.get(p.slug);
+    const parentSlug = p.parentPrinciple;
+    if (!parentSlug || !filteredSlugs.has(parentSlug)) {
+      roots.push(node);
+    } else {
+      const parentNode = nodeBySlug.get(parentSlug);
+      if (parentNode) {
+        parentNode.children.push(node);
+      }
+    }
+  }
+  sortNodes(roots);
+  return roots;
+}
+
+// lib/core-principles.ts
+function createReadableFileSystem() {
+  return {
+    exists: existsSync,
+    isDirectory: (path2) => {
+      try {
+        return statSync2(path2).isDirectory();
+      } catch {
+        return false;
+      }
+    },
+    readFile: (path2) => readFile3(path2, "utf-8"),
+    readdir: async (path2) => readdirSync(path2)
+  };
+}
+function locatePackagePrinciplesDir() {
+  const thisFile = fileURLToPath(import.meta.url);
+  const thisDir = dirname5(thisFile);
+  const packageRoot = dirname5(thisDir);
+  const principlesDir = join10(packageRoot, ".dust", "principles");
+  if (!existsSync(principlesDir)) {
+    throw new Error(`Core principles directory not found at ${principlesDir}. ` + "Ensure the @joshski/dust package is properly installed.");
+  }
+  return principlesDir;
+}
+async function readAllCorePrinciples() {
+  const principlesDir = locatePackagePrinciplesDir();
+  const packageRoot = dirname5(dirname5(principlesDir));
+  const dustPath = join10(packageRoot, ".dust");
+  const fileSystem = createReadableFileSystem();
+  const files = readdirSync(principlesDir);
+  const mdFiles = files.filter((f) => f.endsWith(".md"));
+  const principles = [];
+  for (const file of mdFiles) {
+    const slug = file.replace(/\.md$/, "");
+    const principle = await parsePrinciple(fileSystem, dustPath, slug);
+    principles.push(principle);
+  }
+  return principles;
+}
+async function getCorePrincipleHierarchy(config = {}) {
+  const allPrinciples = await readAllCorePrinciples();
+  return getCorePrincipleTree(allPrinciples, config);
+}
+function getCorePrinciplesPath() {
+  const principlesDir = locatePackagePrinciplesDir();
+  return `${principlesDir}/`;
+}
+
+// lib/cli/commands/list.ts
 function workflowTypeToStatus(type) {
   switch (type) {
     case "refine-idea":
@@ -10301,6 +10530,24 @@ function emitListEvent(emitEvent, type, items) {
     });
   }
 }
+function formatPrincipleEntry(slug, openingSentence) {
+  const lines = [`* ${slug}.md`];
+  if (openingSentence) {
+    lines.push(`  ${openingSentence}`);
+  }
+  return lines;
+}
+function formatPrinciplesSection(header, entries) {
+  if (entries.length === 0) {
+    return [];
+  }
+  const lines = [header, ""];
+  for (const entry of entries) {
+    lines.push(...formatPrincipleEntry(entry.slug, entry.openingSentence));
+    lines.push("");
+  }
+  return lines;
+}
 async function buildPrincipleHierarchy(principlesPath, fileSystem) {
   const files = await fileSystem.readdir(principlesPath);
   const mdFiles = files.filter((f) => f.endsWith(".md"));
@@ -10347,6 +10594,18 @@ function renderHierarchy(nodes, output, prefix = "") {
     }
   }
 }
+function renderCorePrincipleHierarchy(nodes, output, prefix = "") {
+  for (let i = 0;i < nodes.length; i++) {
+    const node = nodes[i];
+    const isLastNode = i === nodes.length - 1;
+    const connector = isLastNode ? "└── " : "├── ";
+    const childPrefix = isLastNode ? "    " : "│   ";
+    output(`${prefix}${connector}${node.title}`);
+    if (node.children.length > 0) {
+      renderCorePrincipleHierarchy(node.children, output, prefix + childPrefix);
+    }
+  }
+}
 function parseTypesToList(commandArguments) {
   if (commandArguments.length === 0) {
     return [...ARTIFACT_TYPES];
@@ -10383,14 +10642,6 @@ function outputArtifact(parameters) {
 async function processListType(context) {
   const { type, dirPath, mdFiles, colors, fileSystem, workflowTasks } = context;
   const { stdout, emitEvent } = context;
-  if (type === "principles") {
-    const hierarchy = await buildPrincipleHierarchy(dirPath, fileSystem);
-    if (hierarchy.length > 0) {
-      stdout(`${colors.dim}Hierarchy:${colors.reset}`);
-      renderHierarchy(hierarchy, (line) => stdout(line));
-      stdout("");
-    }
-  }
   const collectedItems = [];
   for (const file of mdFiles) {
     const filePath = `${dirPath}/${file}`;
@@ -10417,6 +10668,101 @@ async function processListType(context) {
     emitListEvent(emitEvent, type, collectedItems);
   }
 }
+async function loadCorePrinciples(localDirPath, excludeSet) {
+  const corePath = getCorePrinciplesPath().replace(/\/$/, "");
+  if (resolve4(localDirPath) === resolve4(corePath)) {
+    return [];
+  }
+  const allCorePrinciples = await readAllCorePrinciples();
+  return allCorePrinciples.filter((p) => !isInternalPrinciple(p.content) && !excludeSet.has(p.slug));
+}
+async function processPrinciplesList(context) {
+  const { dustPath, colors, fileSystem, stdout, emitEvent } = context;
+  const { excludeCorePrinciples, tree } = context;
+  const excludeSet = new Set(excludeCorePrinciples ?? []);
+  const localDirPath = `${dustPath}/principles`;
+  const corePrinciples = await loadCorePrinciples(localDirPath, excludeSet);
+  const hasCorePrinciples = corePrinciples.length > 0;
+  const localDirExists = fileSystem.exists(localDirPath);
+  const localFiles = localDirExists ? await fileSystem.readdir(localDirPath) : [];
+  const localMdFiles = localFiles.filter((f) => f.endsWith(".md")).toSorted();
+  const hasLocalPrinciples = localMdFiles.length > 0;
+  if (!hasCorePrinciples && !hasLocalPrinciples) {
+    return false;
+  }
+  stdout(SECTION_HEADERS["principles"]);
+  stdout("");
+  stdout(TYPE_EXPLANATIONS["principles"]);
+  stdout("");
+  if (tree) {
+    if (hasCorePrinciples) {
+      const coreHierarchy = await getCorePrincipleHierarchy({
+        excludeCorePrinciples
+      });
+      stdout(`${colors.bold}Core${colors.reset}`);
+      renderCorePrincipleHierarchy(coreHierarchy, (line) => stdout(line));
+      stdout("");
+    }
+    if (hasLocalPrinciples) {
+      const localHierarchy = await buildPrincipleHierarchy(localDirPath, fileSystem);
+      stdout(`${colors.bold}Local${colors.reset}`);
+      renderHierarchy(localHierarchy, (line) => stdout(line));
+      stdout("");
+      const collectedItems = [];
+      for (const file of localMdFiles) {
+        const filePath = `${localDirPath}/${file}`;
+        const content = await fileSystem.readFile(filePath);
+        const title = extractTitle(content);
+        const relativePath = `.dust/principles/${file}`;
+        const slug = file.replace(".md", "");
+        const displayTitle = title || slug;
+        collectedItems.push({ path: relativePath, title: displayTitle });
+      }
+      if (emitEvent) {
+        emitListEvent(emitEvent, "principles", collectedItems);
+      }
+    } else if (emitEvent) {
+      emitListEvent(emitEvent, "principles", []);
+    }
+  } else {
+    if (hasCorePrinciples) {
+      const corePath = getCorePrinciplesPath();
+      const coreEntries = corePrinciples.toSorted((a, b) => a.slug.localeCompare(b.slug)).map((p) => ({
+        slug: p.slug,
+        openingSentence: extractOpeningSentence(p.content)
+      }));
+      const coreLines = formatPrinciplesSection(`\uD83C\uDFAF Core Principles (${corePath})`, coreEntries);
+      for (const line of coreLines) {
+        stdout(line);
+      }
+    }
+    if (hasLocalPrinciples) {
+      const localEntries = [];
+      const collectedItems = [];
+      for (const file of localMdFiles) {
+        const filePath = `${localDirPath}/${file}`;
+        const content = await fileSystem.readFile(filePath);
+        const title = extractTitle(content);
+        const openingSentence = extractOpeningSentence(content);
+        const relativePath = `.dust/principles/${file}`;
+        const slug = file.replace(".md", "");
+        const displayTitle = title || slug;
+        localEntries.push({ slug, openingSentence });
+        collectedItems.push({ path: relativePath, title: displayTitle });
+      }
+      const localLines = formatPrinciplesSection("\uD83C\uDFAF Local Principles (.dust/principles/)", localEntries);
+      for (const line of localLines) {
+        stdout(line);
+      }
+      if (emitEvent) {
+        emitListEvent(emitEvent, "principles", collectedItems);
+      }
+    } else if (emitEvent) {
+      emitListEvent(emitEvent, "principles", []);
+    }
+  }
+  return true;
+}
 async function list(dependencies) {
   const {
     arguments: commandArguments,
@@ -10431,16 +10777,41 @@ async function list(dependencies) {
     context.stderr("Run 'dust init' to initialize a Dust repository");
     return { exitCode: 1 };
   }
-  const typesToList = parseTypesToList(commandArguments);
-  if (commandArguments.length > 0 && typesToList.length === 0) {
-    context.stderr(`Invalid type: ${commandArguments[0]}`);
+  const treeFlag = commandArguments.includes("--tree");
+  const argsWithoutFlags = commandArguments.filter((a) => !a.startsWith("--"));
+  const typesToList = parseTypesToList(argsWithoutFlags);
+  if (argsWithoutFlags.length > 0 && typesToList.length === 0) {
+    context.stderr(`Invalid type: ${argsWithoutFlags[0]}`);
     context.stderr(`Valid types: ${ARTIFACT_TYPES.join(", ")}`);
     return { exitCode: 1 };
   }
-  const specificTypeRequested = commandArguments.length > 0;
+  const specificTypeRequested = argsWithoutFlags.length > 0;
   const showTaskCreationHint = specificTypeRequested && typesToList.length === 1 && typesToList[0] === "tasks";
   const workflowTasks = typesToList.includes("ideas") && fileSystem.exists(dustPath) ? await findAllWorkflowTasks(fileSystem, dustPath) : null;
   for (const type of typesToList) {
+    if (type === "principles") {
+      const hasContent = await processPrinciplesList({
+        dustPath,
+        colors,
+        fileSystem,
+        stdout: context.stdout,
+        emitEvent: context.emitEvent,
+        excludeCorePrinciples: settings.excludeCorePrinciples,
+        tree: treeFlag
+      });
+      if (!hasContent && specificTypeRequested) {
+        context.stdout(SECTION_HEADERS[type]);
+        context.stdout("");
+        context.stdout(TYPE_EXPLANATIONS[type]);
+        context.stdout("");
+        context.stdout(`No ${type} found.`);
+        context.stdout("");
+        if (context.emitEvent) {
+          emitListEvent(context.emitEvent, type, []);
+        }
+      }
+      continue;
+    }
     const dirPath = `${dustPath}/${type}`;
     const dirExists = fileSystem.exists(dirPath);
     const files = dirExists ? await fileSystem.readdir(dirPath) : [];
@@ -10483,7 +10854,7 @@ async function list(dependencies) {
 }
 
 // lib/loop/loop.ts
-import { existsSync } from "node:fs";
+import { existsSync as existsSync2 } from "node:fs";
 import os3 from "node:os";
 
 // lib/loop/parse-args.ts
@@ -10549,7 +10920,7 @@ async function runLoop(dependencies, loopDependencies) {
   const dockerDeps = {
     spawn: loopDependencies.dockerDeps?.spawn ?? loopDependencies.spawn,
     homedir: loopDependencies.dockerDeps?.homedir ?? os3.homedir,
-    existsSync: loopDependencies.dockerDeps?.existsSync ?? existsSync
+    existsSync: loopDependencies.dockerDeps?.existsSync ?? existsSync2
   };
   const dockerResult = await prepareDockerConfig(context.cwd, dockerDeps, onLoopEvent);
   if ("error" in dockerResult) {
@@ -10702,6 +11073,38 @@ async function migrate(dependencies) {
   return { exitCode: 0 };
 }
 
+// lib/cli/commands/new-fact.ts
+function newFactInstructions(vars) {
+  const intro = vars.isClaudeCodeWeb ? "Follow these steps. Use a todo list to track your progress." : "Follow these steps:";
+  return dedent`
+    ## Adding a New Fact
+
+    Facts are current state documentation. They capture how things work today—implementation details, architectural decisions, and system behavior. Unlike principles (which are aspirational) or ideas/tasks (which are future work), facts answer "how does this work today?"
+
+    ${intro}
+    1. Run \`${vars.bin} facts\` to see existing facts and avoid duplication
+    2. Create a new markdown file in \`.dust/facts/\` with a descriptive kebab-case name (e.g., \`authentication-flow.md\`)
+    3. Add a title as the first line using an H1 heading (e.g., \`# Authentication Flow\`)
+    4. Write an opening sentence that summarizes the fact (this appears in \`${vars.bin} facts\` output)
+    5. Add optional body sections with additional details, examples, or context
+    6. Run \`${vars.bin} lint\` to catch any formatting issues
+    7. Create a single atomic commit with a message in the format "Add fact: <title>"
+    8. Push your commit to the remote repository
+
+    Facts should be:
+    - **Current** - They describe how things work today, not how they should work
+    - **Specific** - They document concrete implementation details
+    - **Discoverable** - The opening sentence should help others find relevant facts
+  `;
+}
+async function newFact(dependencies) {
+  const { context, settings } = dependencies;
+  const hooksInstalled = await manageGitHooks(dependencies);
+  const vars = templateVariables(settings, hooksInstalled);
+  context.stdout(newFactInstructions(vars));
+  return { exitCode: 0 };
+}
+
 // lib/cli/commands/new-idea.ts
 function newIdeaInstructions(vars) {
   return dedent`
@@ -11000,16 +11403,28 @@ async function prePush(dependencies, gitRunner = defaultGitRunner, env = process
 
 // lib/cli/shared/type-list.ts
 async function tasks(dependencies) {
-  return list({ ...dependencies, arguments: ["tasks"] });
+  return list({
+    ...dependencies,
+    arguments: ["tasks", ...dependencies.arguments]
+  });
 }
 async function principles(dependencies) {
-  return list({ ...dependencies, arguments: ["principles"] });
+  return list({
+    ...dependencies,
+    arguments: ["principles", ...dependencies.arguments]
+  });
 }
 async function ideas(dependencies) {
-  return list({ ...dependencies, arguments: ["ideas"] });
+  return list({
+    ...dependencies,
+    arguments: ["ideas", ...dependencies.arguments]
+  });
 }
 async function facts(dependencies) {
-  return list({ ...dependencies, arguments: ["facts"] });
+  return list({
+    ...dependencies,
+    arguments: ["facts", ...dependencies.arguments]
+  });
 }
 
 // lib/cli/main.ts
@@ -11031,6 +11446,7 @@ var commandRegistry = {
   "new task": newTask,
   "new principle": newPrinciple,
   "new idea": newIdea,
+  "new fact": newFact,
   "implement task": implementTask,
   "pick task": pickTask,
   "loop claude": loopClaude,
@@ -11134,9 +11550,9 @@ function createGlobScanner(readdirFn) {
   };
 }
 var defaultFileSystemPrimitives = {
-  existsSync: existsSync2,
-  statSync: statSync2,
-  readFile: readFile3,
+  existsSync: existsSync3,
+  statSync: statSync3,
+  readFile: readFile4,
   writeFile: writeFile2,
   mkdir: mkdir2,
   readdir: readdir2,