facult 1.0.3 → 1.2.0

package/src/index-builder.ts

@@ -1,8 +1,36 @@
 import { mkdir, readdir } from "node:fs/promises";
-import { basename, join, relative } from "node:path";
-import { facultRootDir } from "./paths";
+import { basename, dirname, join, relative } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseCliContextArgs, resolveCliContextRoot } from "./cli-context";
+import {
+  type AssetScope,
+  type AssetSourceKind,
+  extractExplicitReferences,
+  type FacultGraph,
+  type GraphEdge,
+  makeGraphNodeId,
+  snippetMarkerToSnippetRef,
+} from "./graph";
+import {
+  facultAiGraphPath,
+  facultAiIndexPath,
+  facultGeneratedStateDir,
+  facultRootDir,
+  projectRootFromAiRoot,
+  projectSlugFromAiRoot,
+} from "./paths";
 import { lastModified } from "./util/skills";
 
+interface AssetEntryBase {
+  sourceKind?: AssetSourceKind;
+  scope?: AssetScope;
+  canonicalRef?: string;
+  projectRoot?: string;
+  projectSlug?: string;
+  sourceRoot?: string;
+  shadow?: boolean;
+}
+
 export interface SkillEntry {
   name: string;
   path: string;
@@ -34,15 +62,38 @@ export interface McpEntry {
 export interface AgentEntry {
   name: string;
   path: string;
+  description?: string;
   lastModifiedAt?: string;
 }
 
 export interface SnippetEntry {
   name: string;
   path: string;
+  description?: string;
+  tags?: string[];
+  lastModifiedAt?: string;
+}
+
+export interface InstructionEntry {
+  name: string;
+  path: string;
+  description: string;
+  tags: string[];
   lastModifiedAt?: string;
 }
 
+interface ToolAssetEntry extends AssetEntryBase {
+  name: string;
+  path: string;
+  lastModifiedAt?: string;
+}
+
+export interface SkillEntry extends AssetEntryBase {}
+export interface McpEntry extends AssetEntryBase {}
+export interface AgentEntry extends AssetEntryBase {}
+export interface SnippetEntry extends AssetEntryBase {}
+export interface InstructionEntry extends AssetEntryBase {}
+
 export interface FacultIndex {
   version: number;
   updatedAt: string;
@@ -50,6 +101,41 @@ export interface FacultIndex {
   mcp: { servers: Record<string, McpEntry> };
   agents: Record<string, AgentEntry>;
   snippets: Record<string, SnippetEntry>;
+  instructions: Record<string, InstructionEntry>;
+}
+
+interface IndexedSource {
+  sourceKind: AssetSourceKind;
+  scope: AssetScope;
+  rootDir: string;
+  projectRoot?: string;
+  projectSlug?: string;
+}
+
+interface SourceAssets {
+  skills: Record<string, SkillEntry>;
+  mcpServers: Record<string, McpEntry>;
+  agents: Record<string, AgentEntry>;
+  snippets: Record<string, SnippetEntry>;
+  instructions: Record<string, InstructionEntry>;
+  toolConfigs: Record<string, ToolAssetEntry>;
+  toolRules: Record<string, ToolAssetEntry>;
+}
+
+interface ManagedToolStateLite {
+  tool: string;
+  agentsDir?: string;
+  toolHome?: string;
+  globalAgentsPath?: string;
+  globalAgentsOverridePath?: string;
+  mcpConfig?: string;
+  rulesDir?: string;
+  toolConfig?: string;
+}
+
+interface ManagedStateLite {
+  version?: number;
+  tools?: Record<string, ManagedToolStateLite>;
 }
 
 function isSafePathString(p: string): boolean {
@@ -120,6 +206,8 @@ function stripQuotes(s: string): string {
 const NEWLINE_RE = /\r?\n/;
 const FRONTMATTER_KEY_RE = /^([A-Za-z0-9_-]+)\s*:\s*(.*)$/;
 const FRONTMATTER_LIST_ITEM_RE = /^\s*-\s*(.+)$/;
+const MARKDOWN_FILE_SUFFIX_RE = /\.md$/i;
+const REFS_PREFIX_RE = /^refs\./;
 
 function normalizeTags(tags: string[]): string[] {
   return [...new Set(tags.map((t) => t.trim()).filter(Boolean))].sort();
@@ -275,7 +363,7 @@ function parseFrontmatter(md: string): {
   return { description, tags, body: block.body };
 }
 
-export function parseSkillMarkdown(md: string): {
+function parseMarkdownAsset(md: string): {
   description: string;
   tags: string[];
 } {
@@ -287,6 +375,13 @@ export function parseSkillMarkdown(md: string): {
   return { description, tags: normalizeTags(fm.tags) };
 }
 
+export function parseSkillMarkdown(md: string): {
+  description: string;
+  tags: string[];
+} {
+  return parseMarkdownAsset(md);
+}
+
 async function statIsoTime(p: string): Promise<string | undefined> {
   const lm = await lastModified(p);
   return lm ? lm.toISOString() : undefined;
@@ -297,6 +392,54 @@ async function readJsonSafe(p: string): Promise<unknown> {
   return JSON.parse(txt);
 }
 
+function builtinAssetsRoot(): string {
+  const here = dirname(fileURLToPath(import.meta.url));
+  return join(here, "..", "assets", "packs", "facult-operating-model");
+}
+
+function canonicalRefForPath(
+  source: IndexedSource,
+  category:
+    | "skills"
+    | "agents"
+    | "snippets"
+    | "instructions"
+    | "mcp"
+    | "doc"
+    | "rendered",
+  filePath: string
+): string | undefined {
+  const rel = relative(source.rootDir, filePath).replace(/\\/g, "/");
+  if (!rel || rel.startsWith("..")) {
+    return undefined;
+  }
+  if (source.sourceKind === "global") {
+    return `@ai/${rel}`;
+  }
+  if (source.sourceKind === "project") {
+    return `@project/${rel}`;
+  }
+  if (source.sourceKind === "builtin") {
+    return `@builtin/facult-operating-model/${category}/${rel}`;
+  }
+  return undefined;
+}
+
+function entryScopeMeta(
+  source: IndexedSource
+): Pick<
+  AssetEntryBase,
+  "sourceKind" | "scope" | "projectRoot" | "projectSlug" | "sourceRoot"
+> {
+  return {
+    sourceKind: source.sourceKind,
+    scope: source.scope,
+    projectRoot: source.projectRoot,
+    projectSlug: source.projectSlug,
+    sourceRoot: source.rootDir,
+  };
+}
+
 async function listDirFiles(dir: string): Promise<string[]> {
   try {
     const ents = await readdir(dir, { withFileTypes: true });
@@ -325,6 +468,7 @@ async function listSubdirs(dir: string): Promise<string[]> {
 
 async function indexSkills(
   skillsDir: string,
+  source: IndexedSource,
   previous?: Record<string, unknown>
 ): Promise<Record<string, SkillEntry>> {
   const out: Record<string, SkillEntry> = {};
@@ -349,6 +493,7 @@ async function indexSkills(
         path: d,
         description,
         tags,
+        canonicalRef: canonicalRefForPath(source, "skills", d),
         lastModifiedAt: await statIsoTime(skillMd),
         enabledFor: meta.enabledFor,
         trusted: meta.trusted ?? false,
@@ -356,6 +501,7 @@ async function indexSkills(
         trustedBy: meta.trustedBy,
         auditStatus: meta.auditStatus ?? "pending",
         lastAuditAt: meta.lastAuditAt,
+        ...entryScopeMeta(source),
       };
     } catch {
       // Ignore missing/invalid skill entries.
@@ -366,6 +512,7 @@ async function indexSkills(
 
 async function indexMcpServers(
   mcpConfigPath: string,
+  source: IndexedSource,
   previous?: Record<string, unknown>
 ): Promise<Record<string, McpEntry>> {
   const out: Record<string, McpEntry> = {};
@@ -403,6 +550,7 @@ async function indexMcpServers(
       out[name] = {
         name,
         path: mcpConfigPath,
+        canonicalRef: canonicalRefForPath(source, "mcp", mcpConfigPath),
         lastModifiedAt: lm,
         definition: serversObj[name],
         enabledFor: meta.enabledFor,
@@ -411,6 +559,7 @@ async function indexMcpServers(
         trustedBy: meta.trustedBy,
         auditStatus: meta.auditStatus ?? "pending",
         lastAuditAt: meta.lastAuditAt,
+        ...entryScopeMeta(source),
       };
     }
   } catch {
@@ -421,23 +570,53 @@ async function indexMcpServers(
 }
 
 async function indexAgents(
-  agentsDir: string
+  agentsDir: string,
+  source: IndexedSource
 ): Promise<Record<string, AgentEntry>> {
   const out: Record<string, AgentEntry> = {};
-  const files = await listDirFiles(agentsDir);
+  const files: string[] = [];
+  const directFiles = await listDirFiles(agentsDir);
+  files.push(...directFiles);
+  for (const dir of await listSubdirs(agentsDir)) {
+    const candidate = join(dir, "agent.toml");
+    try {
+      const st = await Bun.file(candidate).stat();
+      if (st.isFile()) {
+        files.push(candidate);
+      }
+    } catch {
+      // Ignore missing nested manifests.
+    }
+  }
   for (const p of files) {
-    const name = basename(p);
+    const name =
+      basename(p) === "agent.toml" ? basename(dirname(p)) : basename(p);
+    let description: string | undefined;
+    try {
+      const raw = await Bun.file(p).text();
+      const parsed = Bun.TOML.parse(raw) as Record<string, unknown>;
+      const parsedDescription = parsed.description;
+      if (typeof parsedDescription === "string" && parsedDescription.trim()) {
+        description = parsedDescription.trim();
+      }
+    } catch {
+      description = undefined;
+    }
     out[name] = {
       name,
       path: p,
+      description,
+      canonicalRef: canonicalRefForPath(source, "agents", p),
       lastModifiedAt: await statIsoTime(p),
+      ...entryScopeMeta(source),
     };
   }
   return out;
 }
 
 async function indexSnippets(
-  snippetsDir: string
+  snippetsDir: string,
+  source: IndexedSource
 ): Promise<Record<string, SnippetEntry>> {
   const out: Record<string, SnippetEntry> = {};
   try {
@@ -459,33 +638,758 @@ async function indexSnippets(
   for (const p of files.sort()) {
     const rel = relative(snippetsDir, p);
     const name = rel || basename(p);
+    let description: string | undefined;
+    let tags: string[] | undefined;
+    try {
+      const raw = await Bun.file(p).text();
+      const parsed = parseMarkdownAsset(raw);
+      description = parsed.description || undefined;
+      tags = parsed.tags.length ? parsed.tags : undefined;
+    } catch {
+      description = undefined;
+      tags = undefined;
+    }
     out[name] = {
       name,
       path: p,
+      description,
+      tags,
+      canonicalRef: canonicalRefForPath(source, "snippets", p),
       lastModifiedAt: await statIsoTime(p),
+      ...entryScopeMeta(source),
     };
   }
   return out;
 }
 
-export async function buildIndex(opts?: {
-  force?: boolean;
-  /** Override the default canonical root dir (useful for tests). */
-  rootDir?: string;
-}): Promise<{ index: FacultIndex; outputPath: string }> {
-  const force = Boolean(opts?.force);
+function instructionNameFromRelativePath(relPath: string): string {
+  return relPath.replace(MARKDOWN_FILE_SUFFIX_RE, "");
+}
+
+async function indexInstructions(
+  instructionsDir: string,
+  source: IndexedSource
+): Promise<Record<string, InstructionEntry>> {
+  const out: Record<string, InstructionEntry> = {};
+  try {
+    const st = await Bun.file(instructionsDir).stat();
+    if (!st.isDirectory()) {
+      return out;
+    }
+  } catch {
+    return out;
+  }
+
+  const glob = new Bun.Glob("**/*.md");
+  const files: string[] = [];
+  for await (const rel of glob.scan({
+    cwd: instructionsDir,
+    onlyFiles: true,
+  })) {
+    files.push(join(instructionsDir, rel));
+  }
+
+  for (const p of files.sort()) {
+    try {
+      const rel = relative(instructionsDir, p);
+      const raw = await Bun.file(p).text();
+      const parsed = parseMarkdownAsset(raw);
+      const name = instructionNameFromRelativePath(rel || basename(p));
+      out[name] = {
+        name,
+        path: p,
+        description: parsed.description,
+        tags: parsed.tags,
+        canonicalRef: canonicalRefForPath(source, "instructions", p),
+        lastModifiedAt: await statIsoTime(p),
+        ...entryScopeMeta(source),
+      };
+    } catch {
+      // Ignore unreadable instruction files.
+    }
+  }
 
-  const rootDir = opts?.rootDir ?? facultRootDir();
-  const skillsDir = join(rootDir, "skills");
-  const agentsDir = join(rootDir, "agents");
-  const snippetsDir = join(rootDir, "snippets");
-  const serversJsonPath = join(rootDir, "mcp", "servers.json");
-  const mcpJsonPath = join(rootDir, "mcp", "mcp.json");
+  return out;
+}
+
+async function indexToolAssets(
+  toolsDir: string,
+  source: IndexedSource
+): Promise<{
+  toolConfigs: Record<string, ToolAssetEntry>;
+  toolRules: Record<string, ToolAssetEntry>;
+}> {
+  const toolConfigs: Record<string, ToolAssetEntry> = {};
+  const toolRules: Record<string, ToolAssetEntry> = {};
+  try {
+    const st = await Bun.file(toolsDir).stat();
+    if (!st.isDirectory()) {
+      return { toolConfigs, toolRules };
+    }
+  } catch {
+    return { toolConfigs, toolRules };
+  }
+
+  const configGlob = new Bun.Glob("*/config.toml");
+  for await (const rel of configGlob.scan({ cwd: toolsDir, onlyFiles: true })) {
+    const pathValue = join(toolsDir, rel);
+    const name = rel.replace(/\\/g, "/");
+    toolConfigs[name] = {
+      name,
+      path: pathValue,
+      canonicalRef: canonicalRefForPath(source, "rendered", pathValue),
+      lastModifiedAt: await statIsoTime(pathValue),
+      ...entryScopeMeta(source),
+    };
+  }
+
+  const ruleGlob = new Bun.Glob("*/rules/**/*.rules");
+  for await (const rel of ruleGlob.scan({ cwd: toolsDir, onlyFiles: true })) {
+    const pathValue = join(toolsDir, rel);
+    const name = rel.replace(/\\/g, "/");
+    toolRules[name] = {
+      name,
+      path: pathValue,
+      canonicalRef: canonicalRefForPath(source, "rendered", pathValue),
+      lastModifiedAt: await statIsoTime(pathValue),
+      ...entryScopeMeta(source),
+    };
+  }
+
+  return { toolConfigs, toolRules };
+}
+
+async function indexSourceAssets(
+  source: IndexedSource,
+  previousIndex?: Record<string, unknown> | null
+): Promise<SourceAssets> {
+  const skillsDir = join(source.rootDir, "skills");
+  const agentsDir = join(source.rootDir, "agents");
+  const snippetsDir = join(source.rootDir, "snippets");
+  const instructionsDir = join(source.rootDir, "instructions");
+  const toolsDir = join(source.rootDir, "tools");
+  const serversJsonPath = join(source.rootDir, "mcp", "servers.json");
+  const mcpJsonPath = join(source.rootDir, "mcp", "mcp.json");
   const canonicalMcpPath = (await Bun.file(serversJsonPath).exists())
     ? serversJsonPath
     : mcpJsonPath;
 
-  const outputPath = join(rootDir, "index.json");
+  const prevSkills = isPlainObject(previousIndex?.skills)
+    ? (previousIndex?.skills as Record<string, unknown>)
+    : undefined;
+  const prevMcpMap =
+    isPlainObject(previousIndex?.mcp) &&
+    isPlainObject((previousIndex.mcp as Record<string, unknown>).servers)
+      ? ((previousIndex.mcp as Record<string, unknown>).servers as Record<
+          string,
+          unknown
+        >)
+      : undefined;
+
+  const [skills, mcpServers, agents, snippets, instructions, toolAssets] =
+    await Promise.all([
+      indexSkills(skillsDir, source, prevSkills),
+      indexMcpServers(canonicalMcpPath, source, prevMcpMap),
+      indexAgents(agentsDir, source),
+      indexSnippets(snippetsDir, source),
+      indexInstructions(instructionsDir, source),
+      indexToolAssets(toolsDir, source),
+    ]);
+
+  return {
+    skills,
+    mcpServers,
+    agents,
+    snippets,
+    instructions,
+    toolConfigs: toolAssets.toolConfigs,
+    toolRules: toolAssets.toolRules,
+  };
+}
+
+function mergeByName<T extends { name: string }>(
+  sources: Record<string, T>[]
+): Record<string, T> {
+  const merged: Record<string, T> = {};
+  for (const source of sources) {
+    for (const [name, entry] of Object.entries(source)) {
+      merged[name] = entry;
+    }
+  }
+  return merged;
+}
+
+function registerGraphEntries<
+  T extends AssetEntryBase & {
+    name: string;
+    path: string;
+  },
+>(
+  graph: FacultGraph,
+  entries: Record<string, T>,
+  kind:
+    | "skill"
+    | "mcp"
+    | "agent"
+    | "snippet"
+    | "instruction"
+    | "doc"
+    | "tool-config"
+    | "tool-rule",
+  activeSelections?: Map<string, string>
+) {
+  for (const entry of Object.values(entries)) {
+    const sourceKind = entry.sourceKind ?? "global";
+    const scope = entry.scope ?? "global";
+    const activeIdentity = activeSelections?.get(
+      activeEntryKey(kind, entry.name)
+    );
+    const shadow =
+      entry.shadow ??
+      (activeIdentity
+        ? sourceIdentity({ sourceKind, scope }) !== activeIdentity
+        : false);
+    const id = makeGraphNodeId({
+      kind,
+      sourceKind,
+      scope,
+      name: entry.name,
+    });
+    graph.nodes[id] = {
+      id,
+      kind,
+      name: entry.name,
+      sourceKind,
+      scope,
+      path: entry.path,
+      canonicalRef: entry.canonicalRef,
+      projectRoot: entry.projectRoot,
+      projectSlug: entry.projectSlug,
+      shadow,
+    };
+  }
+}
+
+async function readTomlRefs(rootDir: string): Promise<Record<string, string>> {
+  const file = Bun.file(join(rootDir, "config.toml"));
+  if (!(await file.exists())) {
+    return {};
+  }
+  try {
+    const parsed = Bun.TOML.parse(await file.text()) as Record<string, unknown>;
+    const refs = parsed.refs;
+    if (!isPlainObject(refs)) {
+      return {};
+    }
+    return Object.fromEntries(
+      Object.entries(refs)
+        .filter(([, value]) => typeof value === "string")
+        .map(([key, value]) => [key, String(value)])
+    );
+  } catch {
+    return {};
+  }
+}
+
+function graphNodeIdByCanonicalRef(graph: FacultGraph): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const node of Object.values(graph.nodes)) {
+    if (node.canonicalRef) {
+      out[node.canonicalRef] = node.id;
+    }
+  }
+  return out;
+}
+
+function activeEntryKey(kind: string, name: string): string {
+  return `${kind}:${name}`;
+}
+
+function sourceIdentity(entry: {
+  sourceKind?: AssetSourceKind;
+  scope?: AssetScope;
+}): string {
+  return `${entry.sourceKind ?? "global"}:${entry.scope ?? "global"}`;
+}
+
+function buildActiveEntryMap(
+  sourceIndexes: {
+    source: IndexedSource;
+    assets: SourceAssets;
+    docs: Record<string, AgentEntry>;
+  }[]
+): Map<string, string> {
+  const active = new Map<string, string>();
+  for (const sourceEntry of sourceIndexes) {
+    for (const [name, entry] of Object.entries(sourceEntry.assets.skills)) {
+      active.set(activeEntryKey("skill", name), sourceIdentity(entry));
+    }
+    for (const [name, entry] of Object.entries(sourceEntry.assets.mcpServers)) {
+      active.set(activeEntryKey("mcp", name), sourceIdentity(entry));
+    }
+    for (const [name, entry] of Object.entries(sourceEntry.assets.agents)) {
+      active.set(activeEntryKey("agent", name), sourceIdentity(entry));
+    }
+    for (const [name, entry] of Object.entries(sourceEntry.assets.snippets)) {
+      active.set(activeEntryKey("snippet", name), sourceIdentity(entry));
+    }
+    for (const [name, entry] of Object.entries(
+      sourceEntry.assets.instructions
+    )) {
+      active.set(activeEntryKey("instruction", name), sourceIdentity(entry));
+    }
+    for (const [name, entry] of Object.entries(
+      sourceEntry.assets.toolConfigs
+    )) {
+      active.set(activeEntryKey("tool-config", name), sourceIdentity(entry));
+    }
+    for (const [name, entry] of Object.entries(sourceEntry.assets.toolRules)) {
+      active.set(activeEntryKey("tool-rule", name), sourceIdentity(entry));
+    }
+    for (const [name, entry] of Object.entries(sourceEntry.docs)) {
+      active.set(activeEntryKey("doc", name), sourceIdentity(entry));
+    }
+  }
+  return active;
+}
+
+function addGraphEdge(
+  graph: FacultGraph,
+  edge: { from: string; to: string; kind: GraphEdge["kind"]; locator: string }
+) {
+  if (!(graph.nodes[edge.from] && graph.nodes[edge.to])) {
+    return;
+  }
+  if (
+    graph.edges.some(
+      (existing) =>
+        existing.from === edge.from &&
+        existing.to === edge.to &&
+        existing.kind === edge.kind &&
+        existing.locator === edge.locator
+    )
+  ) {
+    return;
+  }
+  graph.edges.push(edge);
+}
+
+function renderedTargetNodeName(
+  targetPath: string,
+  renderRoot: string
+): string {
+  const rel = relative(renderRoot, targetPath).replace(/\\/g, "/");
+  return rel || basename(targetPath);
+}
+
+async function readManagedState(
+  homeDir: string,
+  rootDir: string
+): Promise<ManagedStateLite | null> {
+  const statePath = join(
+    facultGeneratedStateDir({ home: homeDir, rootDir }),
+    "managed.json"
+  );
+  try {
+    const file = Bun.file(statePath);
+    if (!(await file.exists())) {
+      return null;
+    }
+    const parsed = JSON.parse(await file.text()) as ManagedStateLite;
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+async function addReferenceEdgesForEntries<
+  T extends AssetEntryBase & {
+    name: string;
+    path: string;
+  },
+>(
+  graph: FacultGraph,
+  entries: Record<string, T>,
+  kind:
+    | "skill"
+    | "agent"
+    | "snippet"
+    | "instruction"
+    | "doc"
+    | "tool-config"
+    | "tool-rule",
+  refsByRoot: Map<string, Record<string, string>>
+) {
+  const refsByCanonical = graphNodeIdByCanonicalRef(graph);
+  for (const entry of Object.values(entries)) {
+    const sourceKind = entry.sourceKind ?? "global";
+    const scope = entry.scope ?? "global";
+    const from = makeGraphNodeId({
+      kind,
+      sourceKind,
+      scope,
+      name: entry.name,
+    });
+    let raw = "";
+    try {
+      raw = await Bun.file(entry.path).text();
+    } catch {
+      continue;
+    }
+    const refs = extractExplicitReferences(raw);
+    const refsConfig = refsByRoot.get(entry.sourceRoot ?? "") ?? {};
+    for (const ref of refs) {
+      if (ref.kind === "snippet_marker") {
+        const targetName = snippetMarkerToSnippetRef(ref.value);
+        const target = Object.values(graph.nodes).find(
+          (node) =>
+            node.kind === "snippet" &&
+            (node.name === targetName ||
+              node.name === `global/${targetName}` ||
+              node.name.endsWith(`/${targetName}`))
+        );
+        if (target) {
+          addGraphEdge(graph, {
+            from,
+            to: target.id,
+            kind: "snippet_marker",
+            locator: ref.value,
+          });
+        }
+        continue;
+      }
+
+      if (ref.kind === "ref_symbol") {
+        const key = ref.value.replace(REFS_PREFIX_RE, "");
+        const targetRef = refsConfig[key];
+        const target = targetRef ? refsByCanonical[targetRef] : undefined;
+        if (target) {
+          addGraphEdge(graph, {
+            from,
+            to: target,
+            kind: "ref_symbol",
+            locator: ref.value,
+          });
+        }
+        continue;
+      }
+
+      const target = refsByCanonical[ref.value];
+      if (target) {
+        addGraphEdge(graph, {
+          from,
+          to: target,
+          kind: ref.kind === "project_ref" ? "project_ref" : "canonical_ref",
+          locator: ref.value,
+        });
+      }
+    }
+  }
+}
+
+async function discoverDocs(
+  source: IndexedSource
+): Promise<Record<string, AgentEntry>> {
+  const out: Record<string, AgentEntry> = {};
+  const candidates = [
+    join(source.rootDir, "AGENTS.global.md"),
+    join(source.rootDir, "AGENTS.override.global.md"),
+  ];
+  for (const filePath of candidates) {
+    try {
+      const st = await Bun.file(filePath).stat();
+      if (!st.isFile()) {
+        continue;
+      }
+      const name = basename(filePath);
+      out[name] = {
+        name,
+        path: filePath,
+        description: undefined,
+        canonicalRef: canonicalRefForPath(source, "doc", filePath),
+        lastModifiedAt: await statIsoTime(filePath),
+        ...entryScopeMeta(source),
+      };
+    } catch {
+      // Ignore missing docs.
+    }
+  }
+  return out;
+}
+
+function registerRenderedTargetNode(args: {
+  graph: FacultGraph;
+  currentScope: IndexedSource;
+  targetPath: string;
+  targetType: string;
+  sourceNodeId: string;
+  sourceName: string;
+  sourceKind: AssetSourceKind;
+  sourceScope: AssetScope;
+  renderRoot: string;
+  targetTool: string;
+}) {
+  const id = makeGraphNodeId({
+    kind: "rendered-target",
+    sourceKind: args.currentScope.sourceKind,
+    scope: args.currentScope.scope,
+    name: renderedTargetNodeName(args.targetPath, args.renderRoot),
+  });
+  args.graph.nodes[id] = {
+    id,
+    kind: "rendered-target",
+    name: renderedTargetNodeName(args.targetPath, args.renderRoot),
+    sourceKind: args.currentScope.sourceKind,
+    scope: args.currentScope.scope,
+    path: args.targetPath,
+    projectRoot: args.currentScope.projectRoot,
+    projectSlug: args.currentScope.projectSlug,
+    shadow: true,
+    meta: {
+      targetTool: args.targetTool,
+      targetType: args.targetType,
+      sourceKind: args.sourceKind,
+      sourceScope: args.sourceScope,
+      sourceName: args.sourceName,
+    },
+  };
+
+  addGraphEdge(args.graph, {
+    from: args.sourceNodeId,
+    to: id,
+    kind: "render_source",
+    locator: args.targetPath,
+  });
+}
+
+function sourceNodeIdForEntry(args: {
+  kind:
+    | "skill"
+    | "mcp"
+    | "agent"
+    | "snippet"
+    | "instruction"
+    | "doc"
+    | "tool-config"
+    | "tool-rule";
+  entry: {
+    name: string;
+    sourceKind?: AssetSourceKind;
+    scope?: AssetScope;
+  };
+}): string {
+  return makeGraphNodeId({
+    kind: args.kind,
+    sourceKind: args.entry.sourceKind ?? "global",
+    scope: args.entry.scope ?? "global",
+    name: args.entry.name,
+  });
+}
+
+function registerManagedRenderedTargets(args: {
+  graph: FacultGraph;
+  index: FacultIndex;
+  sourceIndexes: {
+    source: IndexedSource;
+    assets: SourceAssets;
+    docs: Record<string, AgentEntry>;
+  }[];
+  currentScope: IndexedSource;
+  renderRoot: string;
+  managedState: ManagedStateLite | null;
+}) {
+  const mergedDocs = mergeByName(args.sourceIndexes.map((entry) => entry.docs));
+  const mergedToolConfigs = mergeByName(
+    args.sourceIndexes.map((entry) => entry.assets.toolConfigs)
+  );
+  const mergedToolRules = mergeByName(
+    args.sourceIndexes.map((entry) => entry.assets.toolRules)
+  );
+  const toolStates = Object.values(args.managedState?.tools ?? {});
+  if (!toolStates.length) {
+    return;
+  }
+
+  const nodes = args.graph.nodes;
+  for (const toolState of toolStates) {
+    if (toolState.agentsDir) {
+      for (const entry of Object.values(args.index.agents)) {
+        const sourceNodeId = sourceNodeIdForEntry({
+          kind: "agent",
+          entry,
+        });
+        if (!nodes[sourceNodeId]) {
+          continue;
+        }
+        const targetPath = join(toolState.agentsDir, `${entry.name}.toml`);
+        registerRenderedTargetNode({
+          graph: args.graph,
+          currentScope: args.currentScope,
+          targetPath,
+          targetType: "agent",
+          sourceNodeId,
+          sourceName: entry.name,
+          sourceKind: entry.sourceKind ?? "global",
+          sourceScope: entry.scope ?? "global",
+          renderRoot: args.renderRoot,
+          targetTool: toolState.tool,
+        });
+      }
+    }
+
+    const globalDocTargets = [
+      {
+        name: "AGENTS.global.md",
+        path: toolState.globalAgentsPath,
+      },
+      {
+        name: "AGENTS.override.global.md",
+        path: toolState.globalAgentsOverridePath,
+      },
+    ];
+    for (const target of globalDocTargets) {
+      if (!target.path) {
+        continue;
+      }
+      const entry = mergedDocs[target.name];
+      if (!entry) {
+        continue;
+      }
+      const sourceNodeId = sourceNodeIdForEntry({
+        kind: "doc",
+        entry,
+      });
+      if (!nodes[sourceNodeId]) {
+        continue;
+      }
+      registerRenderedTargetNode({
+        graph: args.graph,
+        currentScope: args.currentScope,
+        targetPath: target.path,
+        targetType: "doc",
+        sourceNodeId,
+        sourceName: entry.name,
+        sourceKind: entry.sourceKind ?? "global",
+        sourceScope: entry.scope ?? "global",
+        renderRoot: args.renderRoot,
+        targetTool: toolState.tool,
+      });
+    }
+
+    if (toolState.mcpConfig) {
+      for (const entry of Object.values(args.index.mcp.servers)) {
+        const sourceNodeId = sourceNodeIdForEntry({
+          kind: "mcp",
+          entry,
+        });
+        if (!nodes[sourceNodeId]) {
+          continue;
+        }
+        registerRenderedTargetNode({
+          graph: args.graph,
+          currentScope: args.currentScope,
+          targetPath: toolState.mcpConfig,
+          targetType: "mcp",
+          sourceNodeId,
+          sourceName: entry.name,
+          sourceKind: entry.sourceKind ?? "global",
+          sourceScope: entry.scope ?? "global",
+          renderRoot: args.renderRoot,
+          targetTool: toolState.tool,
+        });
+      }
+    }
+
+    if (toolState.toolConfig) {
+      const entry = mergedToolConfigs[`${toolState.tool}/config.toml`];
+      if (entry) {
+        const sourceNodeId = sourceNodeIdForEntry({
+          kind: "tool-config",
+          entry,
+        });
+        if (nodes[sourceNodeId]) {
+          registerRenderedTargetNode({
+            graph: args.graph,
+            currentScope: args.currentScope,
+            targetPath: toolState.toolConfig,
+            targetType: "tool-config",
+            sourceNodeId,
+            sourceName: entry.name,
+            sourceKind: entry.sourceKind ?? "global",
+            sourceScope: entry.scope ?? "global",
+            renderRoot: args.renderRoot,
+            targetTool: toolState.tool,
+          });
+        }
+      }
+    }
+
+    if (toolState.rulesDir) {
+      for (const entry of Object.values(mergedToolRules)) {
+        if (!entry.name.startsWith(`${toolState.tool}/rules/`)) {
+          continue;
+        }
+        const relativeRulePath = entry.name.slice(
+          `${toolState.tool}/rules/`.length
+        );
+        const sourceNodeId = sourceNodeIdForEntry({
+          kind: "tool-rule",
+          entry,
+        });
+        if (!nodes[sourceNodeId]) {
+          continue;
+        }
+        registerRenderedTargetNode({
+          graph: args.graph,
+          currentScope: args.currentScope,
+          targetPath: join(toolState.rulesDir, relativeRulePath),
+          targetType: "tool-rule",
+          sourceNodeId,
+          sourceName: entry.name,
+          sourceKind: entry.sourceKind ?? "global",
+          sourceScope: entry.scope ?? "global",
+          renderRoot: args.renderRoot,
+          targetTool: toolState.tool,
+        });
+      }
+    }
+  }
+}
+
+export async function buildIndex(opts?: {
+  force?: boolean;
+  /** Override the default canonical root dir (useful for tests). */
+  rootDir?: string;
+  /** Override home directory for generated state placement (useful for tests). */
+  homeDir?: string;
+}): Promise<{
+  index: FacultIndex;
+  outputPath: string;
+  graph: FacultGraph;
+  graphPath: string;
+}> {
+  const force = Boolean(opts?.force);
+  const homeDir = opts?.homeDir ?? process.env.HOME ?? "";
+  const rootDir =
+    opts?.rootDir ?? (homeDir ? facultRootDir(homeDir) : facultRootDir());
+  const outputPath = facultAiIndexPath(homeDir, rootDir);
+  const graphPath = facultAiGraphPath(homeDir, rootDir);
+  const projectRoot = projectRootFromAiRoot(rootDir, homeDir);
+  const projectSlug = projectSlugFromAiRoot(rootDir, homeDir);
+  const currentScope: IndexedSource = projectRoot
+    ? {
+        sourceKind: "project",
+        scope: "project",
+        rootDir,
+        projectRoot,
+        projectSlug: projectSlug ?? undefined,
+      }
+    : {
+        sourceKind: "global",
+        scope: "global",
+        rootDir,
+      };
+  const managedState = await readManagedState(homeDir, rootDir);
 
   let previousIndex: Record<string, unknown> | null = null;
   if (!force) {
@@ -510,24 +1414,52 @@ export async function buildIndex(opts?: {
     }
   }
 
-  const prevSkills = isPlainObject(previousIndex?.skills)
-    ? (previousIndex?.skills as Record<string, unknown>)
-    : undefined;
-  const prevMcpMap =
-    isPlainObject(previousIndex?.mcp) &&
-    isPlainObject((previousIndex.mcp as Record<string, unknown>).servers)
-      ? ((previousIndex.mcp as Record<string, unknown>).servers as Record<
-          string,
-          unknown
-        >)
-      : undefined;
+  const globalRoot = facultRootDir(homeDir);
+  const sources: IndexedSource[] = [];
+  const builtinRoot = builtinAssetsRoot();
+  try {
+    const st = await Bun.file(builtinRoot).stat();
+    if (st.isDirectory()) {
+      sources.push({
+        sourceKind: "builtin",
+        scope: "global",
+        rootDir: builtinRoot,
+      });
+    }
+  } catch {
+    // Ignore missing builtin asset packs in development.
+  }
+  sources.push({
+    sourceKind: "global",
+    scope: "global",
+    rootDir: globalRoot,
+  });
+  if (projectRoot) {
+    sources.push({
+      ...currentScope,
+    });
+  }
 
-  const [skills, servers, agents, snippets] = await Promise.all([
-    indexSkills(skillsDir, prevSkills),
-    indexMcpServers(canonicalMcpPath, prevMcpMap),
-    indexAgents(agentsDir),
-    indexSnippets(snippetsDir),
-  ]);
+  const sourceIndexes = await Promise.all(
+    sources.map(async (source) => ({
+      source,
+      assets: await indexSourceAssets(source, previousIndex),
+      docs: await discoverDocs(source),
+      refs: await readTomlRefs(source.rootDir),
+    }))
+  );
+
+  const skills = mergeByName(sourceIndexes.map((entry) => entry.assets.skills));
+  const servers = mergeByName(
+    sourceIndexes.map((entry) => entry.assets.mcpServers)
+  );
+  const agents = mergeByName(sourceIndexes.map((entry) => entry.assets.agents));
+  const snippets = mergeByName(
+    sourceIndexes.map((entry) => entry.assets.snippets)
+  );
+  const instructions = mergeByName(
+    sourceIndexes.map((entry) => entry.assets.instructions)
+  );
 
   const index: FacultIndex = {
     version: 1,
@@ -536,27 +1468,155 @@ export async function buildIndex(opts?: {
     mcp: { servers },
     agents,
     snippets,
+    instructions,
+  };
+
+  const graph: FacultGraph = {
+    version: 1,
+    generatedAt: new Date().toISOString(),
+    nodes: {},
+    edges: [],
   };
 
-  await mkdir(rootDir, { recursive: true });
+  const activeSelections = buildActiveEntryMap(sourceIndexes);
+
+  for (const sourceEntry of sourceIndexes) {
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.skills,
+      "skill",
+      activeSelections
+    );
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.mcpServers,
+      "mcp",
+      activeSelections
+    );
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.agents,
+      "agent",
+      activeSelections
+    );
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.snippets,
+      "snippet",
+      activeSelections
+    );
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.instructions,
+      "instruction",
+      activeSelections
+    );
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.toolConfigs,
+      "tool-config",
+      activeSelections
+    );
+    registerGraphEntries(
+      graph,
+      sourceEntry.assets.toolRules,
+      "tool-rule",
+      activeSelections
+    );
+    registerGraphEntries(graph, sourceEntry.docs, "doc", activeSelections);
+  }
+
+  registerManagedRenderedTargets({
+    graph,
+    index,
+    sourceIndexes,
+    currentScope,
+    renderRoot: projectRoot ?? homeDir,
+    managedState,
+  });
+
+  const refsByRoot = new Map<string, Record<string, string>>();
+  for (const sourceEntry of sourceIndexes) {
+    refsByRoot.set(sourceEntry.source.rootDir, sourceEntry.refs);
+  }
+
+  for (const sourceEntry of sourceIndexes) {
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.assets.skills,
+      "skill",
+      refsByRoot
+    );
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.assets.agents,
+      "agent",
+      refsByRoot
+    );
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.assets.snippets,
+      "snippet",
+      refsByRoot
+    );
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.assets.instructions,
+      "instruction",
+      refsByRoot
+    );
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.assets.toolConfigs,
+      "tool-config",
+      refsByRoot
+    );
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.assets.toolRules,
+      "tool-rule",
+      refsByRoot
+    );
+    await addReferenceEdgesForEntries(
+      graph,
+      sourceEntry.docs,
+      "doc",
+      refsByRoot
+    );
+  }
+
+  await mkdir(dirname(outputPath), { recursive: true });
   await Bun.write(outputPath, `${JSON.stringify(index, null, 2)}\n`);
+  await Bun.write(graphPath, `${JSON.stringify(graph, null, 2)}\n`);
 
-  return { index, outputPath };
+  return { index, outputPath, graph, graphPath };
 }
 
 export async function indexCommand(argv: string[]) {
-  if (argv.includes("--help") || argv.includes("-h") || argv[0] === "help") {
-    console.log(`facult index — rebuild index.json under the canonical store
+  const parsed = parseCliContextArgs(argv);
+  if (
+    parsed.argv.includes("--help") ||
+    parsed.argv.includes("-h") ||
+    parsed.argv[0] === "help"
+  ) {
+    console.log(`facult index — rebuild the generated index for the canonical store
 
 Usage:
-  facult index [--force]
+  facult index [--force] [--root PATH|--global|--project]
 
 Options:
   --force   Rebuild index from scratch (ignore existing metadata)
 `);
     return;
   }
-  const force = argv.includes("--force");
-  const { outputPath } = await buildIndex({ force });
+  const force = parsed.argv.includes("--force");
+  const { outputPath } = await buildIndex({
+    force,
+    rootDir: resolveCliContextRoot({
+      rootArg: parsed.rootArg,
+      scope: parsed.scope,
+      cwd: process.cwd(),
+    }),
+  });
   console.log(`Index written to ${outputPath}`);
 }