skillwiki 0.8.5 → 0.8.8

package/dist/cli.js

@@ -14,7 +14,7 @@ import {
 } from "./chunk-TPS5XD2J.js";
 
 // src/cli.ts
-import { join as join45 } from "path";
+import { join as join46 } from "path";
 import { Command as Command2 } from "commander";
 
 // ../shared/src/exit-codes.ts
@@ -166,8 +166,14 @@ var MetaSchema = z.object({
   tags: z.array(z.string()),
   confidence: z.enum(["high", "medium", "low"]).optional(),
   provenance: z.enum(["research", "project", "mixed"]).optional(),
-  provenance_projects: z.array(wikilink).min(2, "meta pages must reference \u22652 projects")
+  provenance_projects: z.array(wikilink).optional(),
+  generated_by: z.string().min(1).optional(),
+  generated_at: z.string().datetime().optional(),
+  generated_kind: z.enum(["session-brief"]).optional()
 }).superRefine((v, ctx) => {
+  if (v.generated_kind !== "session-brief" && (!v.provenance_projects || v.provenance_projects.length < 2)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance_projects"], message: "meta pages must reference \u22652 projects" });
+  }
   if (v.provenance && v.provenance !== "research" && (!v.provenance_projects || v.provenance_projects.length === 0)) {
     ctx.addIssue({ code: z.ZodIssueCode.custom, path: ["provenance_projects"], message: "required when provenance != research" });
   }
@@ -3067,6 +3073,7 @@ function buildCliSurface() {
   program2.command("backup");
   program2.command("seed").option("--wiki <name>");
   program2.command("observe").requiredOption("--text <text>").option("--kind <kind>").option("--project <slug>").option("--wiki <name>");
+  program2.command("session-brief").option("--project <slug>").option("--write").option("--wiki <name>");
   program2.command("ingest").requiredOption("--vault <path>").requiredOption("--type <type>").requiredOption("--title <title>").option("--tags <csv>").option("--provenance <provenance>").option("--dry-run");
   const graphCmd = program2.commands.find((c) => c.name() === "graph");
   graphCmd.command("build").option("--out <path>").option("--wiki <name>");
@@ -7386,9 +7393,370 @@ ${input.text.trim()}
   };
 }
 
+// src/commands/session-brief.ts
+import { mkdir as mkdir13, readFile as readFile24, writeFile as writeFile14 } from "fs/promises";
+import { join as join36, relative as relative3, sep as sep3 } from "path";
+var MAX_WORDS = 900;
+async function runSessionBrief(input) {
+  const scan = await scanVault(input.vault);
+  if (!scan.ok) {
+    return { exitCode: ExitCode.VAULT_PATH_INVALID, result: scan };
+  }
+  const now = /* @__PURE__ */ new Date();
+  const generatedAt = now.toISOString().replace(/\.\d{3}Z$/, "Z");
+  const today = generatedAt.slice(0, 10);
+  const project = await resolveProject(input);
+  try {
+    const transcripts = await loadTranscriptInfo(scan.data.raw);
+    const workItems = await loadWorkItems(scan.data.workItems);
+    const digests = await loadTrendDigests(scan.data.typedKnowledge);
+    const healthWarnings = await loadHealthWarnings(input.vault);
+    const latestLogs = newest(transcripts.filter((t) => t.kind === "session-log"), 3);
+    const unclaimedCaptures = newest(transcripts.filter((t) => {
+      if (t.kind !== "task" && t.kind !== "bug") return false;
+      return !t.workItem && (!project || t.project === project);
+    }), 5);
+    const activeWork = newest(workItems.filter((w) => {
+      if (w.status !== "planned" && w.status !== "in-progress") return false;
+      return !project || w.project === project;
+    }), 5);
+    const latestDigest = newest(digests, 1);
+    const projectLogs = project ? newest(transcripts.filter((t) => t.kind === "session-log" && t.project === project), 3) : [];
+    const brief = capWords(renderBrief({
+      project,
+      generatedAt,
+      latestLogs,
+      unclaimedCaptures,
+      activeWork,
+      latestDigest,
+      projectLogs,
+      healthWarnings
+    }), MAX_WORDS);
+    let filesWritten = [];
+    let indexUpdated = false;
+    let logUpdated = false;
+    if (input.write) {
+      const writeResult = await writeBriefArtifacts(input.vault, {
+        project,
+        brief,
+        generatedAt,
+        today,
+        wordCount: countWords(brief)
+      });
+      filesWritten = writeResult.filesWritten;
+      indexUpdated = writeResult.indexUpdated;
+      logUpdated = writeResult.logUpdated;
+    }
+    const humanHint = brief;
+    return {
+      exitCode: ExitCode.OK,
+      result: ok({
+        project,
+        brief,
+        word_count: countWords(brief),
+        files_written: filesWritten,
+        index_updated: indexUpdated,
+        log_updated: logUpdated,
+        generated_at: generatedAt,
+        humanHint
+      })
+    };
+  } catch (e) {
+    return {
+      exitCode: ExitCode.WRITE_FAILED,
+      result: err("WRITE_FAILED", { message: String(e) })
+    };
+  }
+}
+async function resolveProject(input) {
+  if (input.project && input.project !== "auto") return input.project;
+  const envProject = input.env?.SKILLWIKI_PROJECT;
+  if (envProject) return envProject;
+  const cwd = input.cwd ?? process.cwd();
+  const projectDotenv = await readProjectSlug(join36(cwd, ".skillwiki", ".env"));
+  if (projectDotenv) return projectDotenv;
+  const inferred = inferProjectFromPath(input.vault, cwd);
+  if (inferred) return inferred;
+  return void 0;
+}
+async function readProjectSlug(file) {
+  let text;
+  try {
+    text = await readFile24(file, "utf8");
+  } catch {
+    return void 0;
+  }
+  for (const rawLine of text.split(/\r?\n/)) {
+    const line = rawLine.trim();
+    if (line.startsWith("#")) continue;
+    const match = line.match(/^PROJECT_SLUG=(.+)$/);
+    if (match && match[1].trim().length > 0) return unquote(match[1].trim());
+  }
+  return void 0;
+}
+function inferProjectFromPath(vault, cwd) {
+  const rel = relative3(vault, cwd).split(sep3).join("/");
+  const match = rel.match(/^projects\/([^/]+)(?:\/|$)/);
+  return match?.[1];
+}
+function unquote(value) {
+  return value.replace(/^["']|["']$/g, "");
+}
+async function loadTranscriptInfo(rawPages) {
+  const out = [];
+  for (const page of rawPages.filter((p) => p.relPath.startsWith("raw/transcripts/"))) {
+    const text = await readPage(page);
+    const fm = extractFrontmatter(text);
+    if (!fm.ok) continue;
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    out.push({
+      path: page.relPath,
+      title: titleFromFmOrPath(fm.data, page.relPath),
+      summary: summarize(body),
+      date: stringField(fm.data.ingested) || dateFromPath(page.relPath),
+      kind: stringField(fm.data.kind),
+      project: wikilinkSlug(fm.data.project),
+      workItem: wikilinkSlug(fm.data.work_item)
+    });
+  }
+  return out;
+}
+async function loadWorkItems(workItemPages) {
+  const out = [];
+  for (const page of workItemPages.filter((p) => p.relPath.endsWith("/spec.md"))) {
+    const text = await readPage(page);
+    const fm = extractFrontmatter(text);
+    if (!fm.ok) continue;
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    out.push({
+      path: page.relPath,
+      title: titleFromFmOrPath(fm.data, page.relPath),
+      summary: summarize(body),
+      date: stringField(fm.data.updated) || stringField(fm.data.created) || dateFromPath(page.relPath),
+      status: stringField(fm.data.status),
+      project: wikilinkSlug(fm.data.project)
+    });
+  }
+  return out;
+}
+async function loadTrendDigests(typedPages) {
+  const out = [];
+  for (const page of typedPages.filter((p) => p.relPath.startsWith("queries/") && p.relPath.includes("agent-memory-trends"))) {
+    const text = await readPage(page);
+    const fm = extractFrontmatter(text);
+    if (!fm.ok) continue;
+    const split = splitFrontmatter(text);
+    const body = split.ok ? split.data.body : text;
+    out.push({
+      path: page.relPath,
+      title: titleFromFmOrPath(fm.data, page.relPath),
+      summary: summarize(body),
+      date: stringField(fm.data.updated) || stringField(fm.data.created) || dateFromPath(page.relPath)
+    });
+  }
+  return out;
+}
+function renderBrief(input) {
+  const lines = [
+    "# Session Brief",
+    "",
+    `Generated: ${input.generatedAt}`,
+    `Scope: ${input.project ? `[[${input.project}]] plus global context` : "global context"}`,
+    ""
+  ];
+  appendSection(lines, "Active Work", input.activeWork, "No active project work found.");
+  appendSection(lines, "Unclaimed Captures", input.unclaimedCaptures, "No unclaimed task or bug captures found.");
+  appendSection(lines, "Recent Session Logs", input.project ? input.projectLogs : input.latestLogs, "No recent session logs found.");
+  appendSection(lines, "Latest Agent Memory Trends", input.latestDigest, "No agent memory trends digest found.");
+  appendTextSection(lines, "Health Warnings", input.healthWarnings, "No high-level health warnings found.");
+  lines.push(
+    "## Suggested Commands",
+    "",
+    "- `skillwiki status`",
+    input.project ? `- \`skillwiki project-index ${input.project}\`` : '- `skillwiki query "active work"`',
+    "- `skillwiki transcripts --since <date>`",
+    ""
+  );
+  return lines.join("\n").trimEnd() + "\n";
+}
+function appendSection(lines, title, items, empty) {
+  lines.push(`## ${title}`, "");
+  if (items.length === 0) {
+    lines.push(`- ${empty}`, "");
+    return;
+  }
+  for (const item of items) {
+    const status = item.status ? ` [${item.status}]` : "";
+    const date = item.date ? `${item.date} ` : "";
+    const summary = item.summary ? ` \u2014 ${item.summary}` : "";
+    lines.push(`- ${date}${item.title}${status} (${item.path})${summary}`);
+  }
+  lines.push("");
+}
+function appendTextSection(lines, title, items, empty) {
+  lines.push(`## ${title}`, "");
+  if (items.length === 0) {
+    lines.push(`- ${empty}`, "");
+    return;
+  }
+  for (const item of items.slice(0, 5)) {
+    lines.push(`- ${item}`);
+  }
+  lines.push("");
+}
+async function loadHealthWarnings(vault) {
+  const text = await readIfExists2(join36(vault, ".skillwiki", "health.json"));
+  if (!text) return [];
+  try {
+    const parsed = JSON.parse(text);
+    const warnings = Array.isArray(parsed.warnings) ? parsed.warnings.filter((w) => typeof w === "string") : [];
+    const riskFlags = Array.isArray(parsed.risk_flags) ? parsed.risk_flags.filter((w) => typeof w === "string") : [];
+    const status = typeof parsed.status === "string" && parsed.status !== "ok" ? [`health status: ${parsed.status}`] : [];
+    return [...status, ...warnings, ...riskFlags].slice(0, 5);
+  } catch {
+    return [];
+  }
+}
+async function writeBriefArtifacts(vault, input) {
+  const metaPath = join36(vault, "meta", "latest-session-brief.md");
+  const cacheMdPath = join36(vault, ".skillwiki", "session-brief.md");
+  const cacheJsonPath = join36(vault, ".skillwiki", "session-brief.json");
+  await mkdir13(join36(vault, "meta"), { recursive: true });
+  await mkdir13(join36(vault, ".skillwiki"), { recursive: true });
+  const committed = renderCommittedBrief(input);
+  const previousComparable = comparableBrief(await readIfExists2(metaPath));
+  const nextComparable = comparableBrief(committed);
+  const materialChange = previousComparable !== nextComparable;
+  await writeFile14(metaPath, committed, "utf8");
+  await writeFile14(cacheMdPath, input.brief, "utf8");
+  await writeFile14(cacheJsonPath, `${JSON.stringify({
+    project: input.project,
+    brief: input.brief,
+    word_count: input.wordCount,
+    generated_at: input.generatedAt
+  }, null, 2)}
+`, "utf8");
+  const indexUpdated = await ensureIndexEntry(vault);
+  const logUpdated = materialChange ? await appendMaterialLog(vault, input.today) : false;
+  if (materialChange) {
+    appendLastOp(vault, {
+      operation: "session-brief",
+      summary: "refreshed latest session brief",
+      files: [
+        "meta/latest-session-brief.md",
+        ".skillwiki/session-brief.md",
+        ".skillwiki/session-brief.json"
+      ],
+      timestamp: input.generatedAt
+    });
+  }
+  return {
+    filesWritten: [
+      "meta/latest-session-brief.md",
+      ".skillwiki/session-brief.md",
+      ".skillwiki/session-brief.json"
+    ],
+    indexUpdated,
+    logUpdated
+  };
+}
+function renderCommittedBrief(input) {
+  const projectLine = input.project ? `project_hint: "[[${input.project}]]"
+` : "";
+  return [
+    "---",
+    "title: Latest Session Brief",
+    `created: ${input.today}`,
+    `updated: ${input.today}`,
+    "type: meta",
+    "tags: [generated, session-brief]",
+    "confidence: high",
+    "generated_by: skillwiki session-brief",
+    `generated_at: ${input.generatedAt}`,
+    "generated_kind: session-brief",
+    projectLine.trimEnd(),
+    "---",
+    "",
+    input.brief.trimEnd(),
+    ""
+  ].filter((line) => line !== "").join("\n");
+}
+async function ensureIndexEntry(vault) {
+  const indexPath = join36(vault, "index.md");
+  let text = await readIfExists2(indexPath);
+  if (!text) return false;
+  if (text.includes("[[meta/latest-session-brief]]")) return false;
+  const entry = "- [[meta/latest-session-brief]] \u2014 Latest Session Brief";
+  const lines = text.split(/\r?\n/);
+  const sectionIdx = lines.findIndex((line) => line.trim() === "## Meta");
+  if (sectionIdx === -1) {
+    while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
+    lines.push("", "## Meta", entry);
+  } else {
+    let insertAt = sectionIdx + 1;
+    while (insertAt < lines.length && !lines[insertAt].startsWith("## ")) insertAt++;
+    lines.splice(insertAt, 0, entry);
+  }
+  await writeFile14(indexPath, lines.join("\n"), "utf8");
+  return true;
+}
+async function appendMaterialLog(vault, today) {
+  const logPath = join36(vault, "log.md");
+  const text = await readIfExists2(logPath);
+  if (!text) return false;
+  const entry = `
+## [${today}] session-brief | refreshed: meta/latest-session-brief.md`;
+  await writeFile14(logPath, text.trimEnd() + entry + "\n", "utf8");
+  return true;
+}
+async function readIfExists2(path) {
+  try {
+    return await readFile24(path, "utf8");
+  } catch {
+    return "";
+  }
+}
+function comparableBrief(text) {
+  if (!text) return "";
+  return text.split(/\r?\n/).filter((line) => !line.startsWith("created:")).filter((line) => !line.startsWith("updated:")).filter((line) => !line.startsWith("generated_at:")).filter((line) => !line.startsWith("Generated: ")).join("\n").trim();
+}
+function newest(items, limit) {
+  return [...items].sort((a, b) => b.date.localeCompare(a.date) || b.path.localeCompare(a.path)).slice(0, limit);
+}
+function titleFromFmOrPath(fm, path) {
+  return stringField(fm.title) || path.split("/").pop()?.replace(/\.md$/, "") || path;
+}
+function summarize(body) {
+  const lines = body.split(/\r?\n/).map((line) => line.replace(/^#+\s*/, "").trim()).filter((line) => line.length > 0 && !line.startsWith("```"));
+  const summary = lines.join(" ").replace(/\s+/g, " ").trim();
+  return summary.length > 180 ? `${summary.slice(0, 177).trimEnd()}...` : summary;
+}
+function capWords(text, maxWords) {
+  const words = text.trim().split(/\s+/);
+  if (words.length <= maxWords) return text;
+  return words.slice(0, maxWords).join(" ") + "\n";
+}
+function countWords(text) {
+  const trimmed = text.trim();
+  return trimmed.length === 0 ? 0 : trimmed.split(/\s+/).length;
+}
+function stringField(value) {
+  return typeof value === "string" ? value : "";
+}
+function wikilinkSlug(value) {
+  if (typeof value !== "string") return void 0;
+  const match = value.match(/^\[\[([^\]]+)\]\]$/);
+  return match?.[1] ?? value;
+}
+function dateFromPath(path) {
+  return path.match(/\d{4}-\d{2}-\d{2}/)?.[0] ?? "";
+}
+
 // src/commands/ingest.ts
-import { readFile as readFile24, writeFile as writeFile14, mkdir as mkdir13 } from "fs/promises";
-import { join as join36 } from "path";
+import { readFile as readFile25, writeFile as writeFile15, mkdir as mkdir14 } from "fs/promises";
+import { join as join37 } from "path";
 import { createHash as createHash5 } from "crypto";
 var ALLOWED_TYPES = /* @__PURE__ */ new Set(["entity", "concept", "comparison", "query"]);
 var TYPE_DIR = {
@@ -7547,7 +7915,7 @@ async function runIngest(input) {
     sourceContent = fetchResult.data.body;
   } else {
     try {
-      sourceContent = await readFile24(input.source, "utf8");
+      sourceContent = await readFile25(input.source, "utf8");
     } catch {
       return {
         exitCode: ExitCode.FILE_NOT_FOUND,
@@ -7562,8 +7930,8 @@ async function runIngest(input) {
   const rawRelPath = `raw/articles/${slug}.md`;
   const typedDir = TYPE_DIR[input.type] ?? `${input.type}s`;
   const typedRelPath = `${typedDir}/${slug}.md`;
-  const rawAbsPath = join36(input.vault, rawRelPath);
-  const typedAbsPath = join36(input.vault, typedRelPath);
+  const rawAbsPath = join37(input.vault, rawRelPath);
+  const typedAbsPath = join37(input.vault, typedRelPath);
   const identity = assessSourceIdentity({
     rawPath: rawRelPath,
     sourceUrl: sourceUrl ?? void 0,
@@ -7645,8 +8013,8 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir13(join36(input.vault, "raw", "articles"), { recursive: true });
-    await writeFile14(rawAbsPath, rawContent, "utf8");
+    await mkdir14(join37(input.vault, "raw", "articles"), { recursive: true });
+    await writeFile15(rawAbsPath, rawContent, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -7654,8 +8022,8 @@ async function runIngest(input) {
     };
   }
   try {
-    await mkdir13(join36(input.vault, typedDir), { recursive: true });
-    await writeFile14(typedAbsPath, typedContent, "utf8");
+    await mkdir14(join37(input.vault, typedDir), { recursive: true });
+    await writeFile15(typedAbsPath, typedContent, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -7834,11 +8202,11 @@ ${body}`;
 
 // src/commands/sync.ts
 import { existsSync as existsSync16 } from "fs";
-import { join as join38 } from "path";
+import { join as join39 } from "path";
 
 // src/utils/sync-lock.ts
 import { existsSync as existsSync15, mkdirSync as mkdirSync5, readFileSync as readFileSync11, renameSync as renameSync2, unlinkSync as unlinkSync5, writeFileSync as writeFileSync7 } from "fs";
-import { join as join37 } from "path";
+import { join as join38 } from "path";
 import { createHash as createHash6 } from "crypto";
 function getSessionId() {
   if (process.env.CLAUDE_SESSION_ID) return process.env.CLAUDE_SESSION_ID;
@@ -7846,7 +8214,7 @@ function getSessionId() {
   return process.pid.toString();
 }
 function lockPath(vault) {
-  return join37(vault, ".skillwiki", "sync.lock");
+  return join38(vault, ".skillwiki", "sync.lock");
 }
 function readLock(vault) {
   const path = lockPath(vault);
@@ -7865,7 +8233,7 @@ function isStale(lock, now) {
 }
 function acquireLock(vault, opts = {}) {
   const path = lockPath(vault);
-  const dir = join37(vault, ".skillwiki");
+  const dir = join38(vault, ".skillwiki");
   if (!existsSync15(dir)) {
     mkdirSync5(dir, { recursive: true });
   }
@@ -7940,7 +8308,7 @@ function releaseLock(vault, opts = {}) {
 function runSyncStatus(input) {
   const vault = input.vault;
   const includeStashes = input.includeStashes ?? false;
-  if (!existsSync16(join38(vault, ".git"))) {
+  if (!existsSync16(join39(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: ok({
@@ -8018,7 +8386,7 @@ function runSyncStatus(input) {
 }
 async function runSyncPush(input) {
   const vault = input.vault;
-  if (!existsSync16(join38(vault, ".git"))) {
+  if (!existsSync16(join39(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -8141,7 +8509,7 @@ function enableGitLongPathsOnWindows(vault) {
 }
 async function runSyncPull(input) {
   const vault = input.vault;
-  if (!existsSync16(join38(vault, ".git"))) {
+  if (!existsSync16(join39(vault, ".git"))) {
     return {
       exitCode: ExitCode.VAULT_PATH_INVALID,
       result: err("NOT_A_GIT_REPO", { path: vault })
@@ -8382,7 +8750,7 @@ function runSyncUnlock(input) {
 
 // src/commands/backup.ts
 import { statSync as statSync5, readdirSync as readdirSync3, readFileSync as readFileSync12, mkdirSync as mkdirSync6, writeFileSync as writeFileSync8 } from "fs";
-import { join as join39, relative as relative3, dirname as dirname13 } from "path";
+import { join as join40, relative as relative4, dirname as dirname13 } from "path";
 import { PutObjectCommand, HeadObjectCommand, ListObjectsV2Command, GetObjectCommand, DeleteObjectsCommand } from "@aws-sdk/client-s3";
 
 // src/utils/s3-client.ts
@@ -8406,11 +8774,11 @@ var SKIP_DIRS2 = /* @__PURE__ */ new Set([".git", ".obsidian", "_archive", "node
 function* walkMarkdown(dir, base) {
   for (const entry of readdirSync3(dir, { withFileTypes: true })) {
     if (SKIP_DIRS2.has(entry.name)) continue;
-    const full = join39(dir, entry.name);
+    const full = join40(dir, entry.name);
     if (entry.isDirectory()) {
       yield* walkMarkdown(full, base);
     } else if (entry.name.endsWith(".md")) {
-      yield relative3(base, full).replace(/\\/g, "/");
+      yield relative4(base, full).replace(/\\/g, "/");
     }
   }
 }
@@ -8429,7 +8797,7 @@ async function runBackupSync(input) {
   let failed = 0;
   const files = [...walkMarkdown(input.vault, input.vault)];
   for (const relPath of files) {
-    const absPath = join39(input.vault, relPath);
+    const absPath = join40(input.vault, relPath);
     const localStat = statSync5(absPath);
     let needsUpload = true;
     try {
@@ -8505,7 +8873,7 @@ async function runBackupRestore(input) {
     const objects = list.Contents ?? [];
     for (const obj of objects) {
       if (!obj.Key) continue;
-      const localPath = join39(target, obj.Key);
+      const localPath = join40(target, obj.Key);
       try {
         const localStat = statSync5(localPath);
         if (obj.LastModified && localStat.mtime > obj.LastModified) {
@@ -8552,8 +8920,8 @@ async function runBackupRestore(input) {
 
 // src/commands/status.ts
 import { existsSync as existsSync17, statSync as statSync6 } from "fs";
-import { readFile as readFile25 } from "fs/promises";
-import { join as join40 } from "path";
+import { readFile as readFile26 } from "fs/promises";
+import { join as join41 } from "path";
 async function runStatus(input) {
   if (!existsSync17(input.vault)) {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { vault: input.vault }) };
@@ -8580,7 +8948,7 @@ async function runStatus(input) {
   const compound = scan.data.compound.length;
   let schemaVersion = "v1";
   try {
-    const schemaContent = await readFile25(join40(input.vault, "SCHEMA.md"), "utf8");
+    const schemaContent = await readFile26(join41(input.vault, "SCHEMA.md"), "utf8");
     const versionMatch = schemaContent.match(/version:\s*["']?([^"'\s\n]+)/i);
     if (versionMatch) schemaVersion = versionMatch[1];
   } catch {
@@ -8640,8 +9008,8 @@ async function runStatus(input) {
 }
 
 // src/commands/seed.ts
-import { mkdir as mkdir14, writeFile as writeFile15, stat as stat8 } from "fs/promises";
-import { join as join41 } from "path";
+import { mkdir as mkdir15, writeFile as writeFile16, stat as stat8 } from "fs/promises";
+import { join as join42 } from "path";
 var TODAY = (/* @__PURE__ */ new Date()).toISOString().slice(0, 10);
 var EXAMPLE_PAGES = {
   "entities/example-project.md": `---
@@ -8710,30 +9078,30 @@ Real sources are immutable after ingestion \u2014 never edit them.
 `;
 async function runSeed(input) {
   try {
-    await stat8(join41(input.vault, "SCHEMA.md"));
+    await stat8(join42(input.vault, "SCHEMA.md"));
   } catch {
     return { exitCode: ExitCode.VAULT_PATH_INVALID, result: err("VAULT_PATH_INVALID", { root: input.vault, reason: "SCHEMA.md missing \u2014 run `skillwiki init` first" }) };
   }
   const created = [];
   const skipped = [];
   for (const [relPath, content] of Object.entries(EXAMPLE_PAGES)) {
-    const absPath = join41(input.vault, relPath);
+    const absPath = join42(input.vault, relPath);
     try {
       await stat8(absPath);
       skipped.push(relPath);
     } catch {
-      await mkdir14(join41(absPath, ".."), { recursive: true });
-      await writeFile15(absPath, content, "utf8");
+      await mkdir15(join42(absPath, ".."), { recursive: true });
+      await writeFile16(absPath, content, "utf8");
       created.push(relPath);
     }
   }
-  const rawPath = join41(input.vault, "raw", "articles", "example-source.md");
+  const rawPath = join42(input.vault, "raw", "articles", "example-source.md");
   try {
     await stat8(rawPath);
     skipped.push("raw/articles/example-source.md");
   } catch {
-    await mkdir14(join41(rawPath, ".."), { recursive: true });
-    await writeFile15(rawPath, EXAMPLE_RAW, "utf8");
+    await mkdir15(join42(rawPath, ".."), { recursive: true });
+    await writeFile16(rawPath, EXAMPLE_RAW, "utf8");
     created.push("raw/articles/example-source.md");
   }
   if (created.length > 0) {
@@ -8755,9 +9123,9 @@ async function runSeed(input) {
 }
 
 // src/commands/canvas.ts
-import { readFile as readFile26, writeFile as writeFile16 } from "fs/promises";
+import { readFile as readFile27, writeFile as writeFile17 } from "fs/promises";
 import { existsSync as existsSync18 } from "fs";
-import { join as join42 } from "path";
+import { join as join43 } from "path";
 var NODE_WIDTH = 240;
 var NODE_HEIGHT = 60;
 var COLUMN_SPACING = 400;
@@ -8835,7 +9203,7 @@ function buildCanvasEdges(adjacency) {
   return edges;
 }
 async function runCanvasGenerate(input) {
-  const graphPath = input.graphPath ?? join42(input.vault, ".skillwiki", "graph.json");
+  const graphPath = input.graphPath ?? join43(input.vault, ".skillwiki", "graph.json");
   if (!existsSync18(graphPath)) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
@@ -8847,7 +9215,7 @@ async function runCanvasGenerate(input) {
   }
   let raw;
   try {
-    raw = await readFile26(graphPath, "utf8");
+    raw = await readFile27(graphPath, "utf8");
   } catch (e) {
     return {
       exitCode: ExitCode.FILE_NOT_FOUND,
@@ -8873,9 +9241,9 @@ async function runCanvasGenerate(input) {
   const nodes = buildCanvasNodes(paths);
   const edges = buildCanvasEdges(graph.adjacency);
   const canvas = { nodes, edges };
-  const outPath = join42(input.vault, "vault-graph.canvas");
+  const outPath = join43(input.vault, "vault-graph.canvas");
   try {
-    await writeFile16(outPath, JSON.stringify(canvas, null, 2));
+    await writeFile17(outPath, JSON.stringify(canvas, null, 2));
   } catch (e) {
     return {
       exitCode: ExitCode.WRITE_FAILED,
@@ -8895,8 +9263,8 @@ written: ${outPath}`
 }
 
 // src/commands/query.ts
-import { readFile as readFile27, stat as stat9 } from "fs/promises";
-import { join as join43 } from "path";
+import { readFile as readFile28, stat as stat9 } from "fs/promises";
+import { join as join44 } from "path";
 var W_KEYWORD = 2;
 var W_SOURCE_OVERLAP = 4;
 var W_WIKILINK = 3;
@@ -9017,7 +9385,7 @@ function computeKeywordScore(terms, title, tags, body) {
   return score;
 }
 async function loadOrBuildGraph(vault) {
-  const graphPath = join43(vault, ".skillwiki", "graph.json");
+  const graphPath = join44(vault, ".skillwiki", "graph.json");
   let needsBuild = false;
   try {
     const fileStat = await stat9(graphPath);
@@ -9031,7 +9399,7 @@ async function loadOrBuildGraph(vault) {
     if (buildResult.exitCode !== 0) return null;
   }
   try {
-    const raw = await readFile27(graphPath, "utf8");
+    const raw = await readFile28(graphPath, "utf8");
     return JSON.parse(raw);
   } catch {
     return null;
@@ -9040,13 +9408,13 @@ async function loadOrBuildGraph(vault) {
 
 // src/utils/auto-commit.ts
 import { existsSync as existsSync19 } from "fs";
-import { join as join44 } from "path";
+import { join as join45 } from "path";
 async function postCommit(vault, exitCode) {
   if (exitCode !== 0) return;
   const home = process.env.HOME ?? "";
   const dotenv = await parseDotenvFile(configPath(home));
   if (dotenv["AUTO_COMMIT"] === "false") return;
-  if (!existsSync19(join44(vault, ".git"))) return;
+  if (!existsSync19(join45(vault, ".git"))) return;
   const lastOps = readLastOp(vault);
   if (lastOps.length === 0) return;
   const porcelain = git(vault, ["status", "--porcelain"]);
@@ -9097,7 +9465,7 @@ program.command("validate <file>").description("validate vault page frontmatter
   emit(await runValidate({ file, apply: !!opts.apply, vault }), vault);
 });
 program.command("graph").description("graph subcommands").command("build <vault>").option("--out <path>", "graph output path (default: <vault>/.skillwiki/graph.json)").option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
-  const out = opts.out ?? join45(vault, ".skillwiki", "graph.json");
+  const out = opts.out ?? join46(vault, ".skillwiki", "graph.json");
   emit(await runGraphBuild({ vault, out }), vault);
 });
 var canvasCmd = program.command("canvas").description("manage Obsidian canvas files");
@@ -9446,6 +9814,17 @@ program.command("observe [vault]").description("create a raw transcript observat
     project: opts.project
   }), v.vault);
 });
+program.command("session-brief [vault]").description("render or refresh the bounded startup session brief").option("--project <slug>", "project slug, or auto for deterministic detection", "auto").option("--write", "write meta/latest-session-brief.md and local cache files", false).option("--wiki <name>", "wiki profile name").action(async (vault, opts) => {
+  const v = await resolveVaultArg(vault, opts.wiki);
+  if (!v.ok) emit({ exitCode: v.exitCode, result: v.payload });
+  else emit(await runSessionBrief({
+    vault: v.vault,
+    project: opts.project,
+    write: !!opts.write,
+    cwd: process.cwd(),
+    env: { SKILLWIKI_PROJECT: process.env.SKILLWIKI_PROJECT }
+  }), v.vault, { postCommit: !!opts.write });
+});
 program.command("ingest <source>").description("ingest a source URL or local file into the vault").requiredOption("--vault <path>", "vault root directory").requiredOption("--type <type>", "typed-knowledge type (entity|concept|comparison|query)").requiredOption("--title <title>", "page title").option("--tags <csv>", "comma-separated tags").option("--provenance <provenance>", "provenance (research|project)").option("--dry-run", "preview without writing files", false).action(async (source, opts) => {
   const tags = typeof opts.tags === "string" ? opts.tags.split(",").map((s) => s.trim()).filter((s) => s.length > 0) : [];
   emit(await runIngest({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.5",
+  "version": "0.8.8",
   "type": "module",
   "bin": {
     "skillwiki": "dist/cli.js"

package/skills/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.5",
+  "version": "0.8.8",
   "skills": "./",
   "description": "Project-aware Karpathy-style knowledge base for Claude Code: 18 prompt-only skills (wiki-*, proj-*, using-skillwiki) backed by the deterministic `skillwiki` CLI.",
   "author": {

package/skills/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "skillwiki",
-  "version": "0.8.5",
+  "version": "0.8.8",
   "description": "Project-aware Karpathy-style knowledge base for Codex with 18 prompt-only skills backed by the deterministic skillwiki CLI.",
   "author": {
     "name": "karlorz",

package/skills/hooks/session-context

@@ -53,6 +53,136 @@ Use this detected PRD mode as the source of truth. Route generated spec/plan art
 EOF
 }
 
+read_dotenv_key() {
+    local file="$1"
+    local key="$2"
+    local line
+
+    [[ -f "$file" ]] || return 0
+    line=$(grep -E "^[[:space:]]*${key}=" "$file" 2>/dev/null | head -n 1 || true)
+    [[ -n "$line" ]] || return 0
+
+    printf '%s' "$line" \
+        | sed -E "s/^[[:space:]]*${key}=//; s/[[:space:]]+#.*$//; s/[[:space:]]+$//; s/^['\"]//; s/['\"]$//"
+}
+
+resolve_vault_path_for_session() {
+    if [[ -n "${WIKI_PATH:-}" ]]; then
+        printf '%s' "$WIKI_PATH"
+        return 0
+    fi
+
+    local project_env="${PWD}/skillwiki/.env"
+    local project_path
+    project_path=$(read_dotenv_key "$project_env" "WIKI_PATH")
+    if [[ -n "$project_path" ]]; then
+        printf '%s' "$project_path"
+        return 0
+    fi
+
+    local global_path
+    global_path=$(read_dotenv_key "${HOME:-}/.skillwiki/.env" "WIKI_PATH")
+    if [[ -n "$global_path" ]]; then
+        printf '%s' "$global_path"
+        return 0
+    fi
+
+    if command -v skillwiki >/dev/null 2>&1; then
+        skillwiki path 2>/dev/null | sed -n 's/^{"ok":true,"data":{"path":"\([^"]*\)".*$/\1/p' | head -n 1
+    fi
+}
+
+file_mtime_epoch() {
+    local file="$1"
+
+    stat -c %Y "$file" 2>/dev/null || stat -f %m "$file" 2>/dev/null || printf '0'
+}
+
+strip_frontmatter_for_session() {
+    local file="$1"
+
+    awk '
+        NR == 1 && $0 == "---" { in_fm = 1; next }
+        in_fm && $0 == "---" { in_fm = 0; next }
+        !in_fm { print }
+    ' "$file" 2>/dev/null
+}
+
+read_session_brief_candidate() {
+    local vault="$1"
+    local file="$2"
+    local label="$3"
+    local max_age_hours="$4"
+    local strip_frontmatter="${5:-false}"
+
+    [[ -f "$file" ]] || return 1
+
+    local now
+    local mtime
+    local age_seconds
+    local age_hours
+    now=$(date +%s)
+    mtime=$(file_mtime_epoch "$file")
+    [[ "$mtime" =~ ^[0-9]+$ ]] || mtime=0
+    age_seconds=$((now - mtime))
+    if (( age_seconds < 0 )); then age_seconds=0; fi
+    age_hours=$((age_seconds / 3600))
+
+    if (( age_hours > max_age_hours )); then
+        return 1
+    fi
+
+    local freshness="fresh"
+    if (( age_hours >= 24 )); then
+        freshness="stale"
+    fi
+
+    printf '## Dynamic Session Memory\n\n'
+    printf '_Source: %s; Session brief age: %s (%sh)._ \n\n' "$label" "$freshness" "$age_hours"
+
+    if [[ "$strip_frontmatter" == "true" ]]; then
+        strip_frontmatter_for_session "$file"
+    else
+        cat "$file" 2>/dev/null
+    fi
+}
+
+compute_session_brief_readonly() {
+    local vault="$1"
+
+    command -v skillwiki >/dev/null 2>&1 || return 1
+    skillwiki session-brief "$vault" --project auto --human 2>/dev/null || return 1
+}
+
+build_dynamic_session_memory() {
+    local vault
+    vault=$(resolve_vault_path_for_session)
+    [[ -n "$vault" && -d "$vault" ]] || return 0
+
+    local cache_file="${vault}/.skillwiki/session-brief.md"
+    local committed_file="${vault}/meta/latest-session-brief.md"
+    local brief
+
+    if brief=$(read_session_brief_candidate "$vault" "$cache_file" ".skillwiki/session-brief.md" 72 false); then
+        printf '%s' "$brief"
+        return 0
+    fi
+
+    if brief=$(read_session_brief_candidate "$vault" "$committed_file" "meta/latest-session-brief.md" 72 true); then
+        printf '%s' "$brief"
+        return 0
+    fi
+
+    if brief=$(compute_session_brief_readonly "$vault"); then
+        printf '## Dynamic Session Memory\n\n'
+        printf '_Source: read-only `skillwiki session-brief --project auto --human` fallback._\n\n'
+        printf '%s' "$brief"
+        return 0
+    fi
+
+    return 0
+}
+
 escape_for_json() {
     local s="$1"
     s="${s//\\/\\\\}"
@@ -88,11 +218,17 @@ resolve_skill_path() {
 build_skillwiki_session_context() {
     local skill_content="$1"
     local project_prd_context
+    local dynamic_session_memory
     local session_context
 
     project_prd_context=$(build_project_prd_context)
+    dynamic_session_memory=$(build_dynamic_session_memory)
 
     session_context=$'### Skillwiki Activation\n\nSkillwiki is active for this workspace. Below are the capability guidelines for local reference:'
+    if [[ -n "$dynamic_session_memory" ]]; then
+        session_context+=$'\n\n'
+        session_context+="$dynamic_session_memory"
+    fi
     if [[ -n "$project_prd_context" ]]; then
         session_context+=$'\n\n'
         session_context+="$project_prd_context"

package/skills/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skillwiki/skills",
-  "version": "0.8.5",
+  "version": "0.8.8",
   "private": true,
   "files": [
     "wiki-*",