my-patina 0.6.0 → 0.8.0

package/dist/cli.js

@@ -7,7 +7,7 @@ import { Command } from "commander";
 import * as p from "@clack/prompts";
 import chalk from "chalk";
 import { dirname as dirname4, join as join7, resolve } from "path";
-import { existsSync as existsSync6, mkdirSync as mkdirSync3, readFileSync as readFileSync7, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
+import { existsSync as existsSync7, mkdirSync as mkdirSync3, readFileSync as readFileSync8, unlinkSync, writeFileSync as writeFileSync4 } from "fs";
 import yaml3 from "js-yaml";
 
 // src/detect.ts
@@ -23,7 +23,7 @@ function loadProfile(root) {
 }
 
 // src/scaffold.ts
-import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3 } from "fs";
+import { mkdirSync as mkdirSync2, writeFileSync as writeFileSync3, existsSync as existsSync5, readFileSync as readFileSync6 } from "fs";
 import { join as join5, dirname as dirname3 } from "path";
 import yaml2 from "js-yaml";
 
@@ -64,7 +64,8 @@ var LI_COMMANDS = [
 ];
 var LI_MANAGED_PATHS = [
   ...LI_COMMANDS.map((c) => `.claude/commands/${c}`),
-  ".claude/modules/linkedin/manifest.md"
+  ".claude/modules/linkedin/manifest.md",
+  ".claude/modules/linkedin/CLAUDE.md"
 ];
 var CONTENT_FILE_NAMES = [
   "INSTRUCTIONS.md",
@@ -91,6 +92,10 @@ var linkedinModule = {
       ".claude/modules/linkedin/manifest.md",
       render(tpl("modules/linkedin/manifest.md"), vars)
     ]);
+    files.push([
+      ".claude/modules/linkedin/CLAUDE.md",
+      render(tpl("modules/linkedin/CLAUDE.md"), vars)
+    ]);
     return files;
   },
   contentFiles(vars, contentDir) {
@@ -109,12 +114,46 @@ var linkedinModule = {
     const updated = { ...profile };
     delete updated.linkedin;
     return updated;
+  },
+  readmeBlock(vars) {
+    return [
+      "## LinkedIn module",
+      "",
+      "Drafts and refines your LinkedIn profile from your graph.",
+      "",
+      "### Folder additions",
+      "",
+      "```",
+      `${vars.CONTENT_DIR}/linkedin/`,
+      "  INSTRUCTIONS.md              \u2014 module rules and guidance",
+      "  LinkedIn Current State.md    \u2014 your current live profile copy",
+      "  LinkedIn About.md            \u2014 draft for the About section",
+      "  LinkedIn Headline.md         \u2014 draft for your headline",
+      "  LinkedIn Experience.md       \u2014 draft for your experience entries",
+      "  LinkedIn Skills.md           \u2014 draft for your skills section",
+      "  LinkedIn Featured.md         \u2014 draft for featured content",
+      "  LinkedIn Activity.md         \u2014 draft for activity/posts section",
+      "```",
+      "",
+      "### Commands",
+      "",
+      "| Command | What it does |",
+      "|---------|-------------|",
+      "| `/li-all` | Run all LinkedIn section drafts in sequence |",
+      "| `/li-about` | Draft or refine your LinkedIn About section |",
+      "| `/li-headline` | Draft or refine your LinkedIn headline |",
+      "| `/li-experience` | Draft or refine your LinkedIn experience entries |",
+      "| `/li-skills` | Draft or refine your LinkedIn skills section |",
+      "| `/li-featured` | Draft or refine your LinkedIn featured content |",
+      "| `/li-activity` | Draft or refine your LinkedIn activity section |"
+    ].join("\n");
   }
 };
 
 // src/modules/resume/index.ts
 var RESUME_MANAGED_PATHS = [
   ".claude/commands/resume-refresh.md",
+  ".claude/modules/resume/CLAUDE.md",
   ".claude/modules/resume/manifest.md"
 ];
 var CONTENT_FILE_NAMES2 = [
@@ -129,10 +168,10 @@ var resumeModule = {
   managedPaths: RESUME_MANAGED_PATHS,
   contentFileNames: CONTENT_FILE_NAMES2,
   managedFiles(vars) {
-    const [commandPath, manifestPath] = RESUME_MANAGED_PATHS;
     return [
-      [commandPath, render(tpl("modules/resume/commands/resume-refresh.md"), vars)],
-      [manifestPath, render(tpl("modules/resume/manifest.md"), vars)]
+      [".claude/commands/resume-refresh.md", render(tpl("modules/resume/commands/resume-refresh.md"), vars)],
+      [".claude/modules/resume/CLAUDE.md", render(tpl("modules/resume/CLAUDE.md"), vars)],
+      [".claude/modules/resume/manifest.md", render(tpl("modules/resume/manifest.md"), vars)]
     ];
   },
   contentFiles(vars, contentDir) {
@@ -140,6 +179,28 @@ var resumeModule = {
       `${contentDir}/resume/${file}`,
       render(tpl(`modules/resume/graph/${file}`), vars)
     ]);
+  },
+  readmeBlock(vars) {
+    return [
+      "## Resume module",
+      "",
+      "Keeps your resume current by synthesising it from your graph.",
+      "",
+      "### Folder additions",
+      "",
+      "```",
+      `${vars.CONTENT_DIR}/resume/`,
+      "  INSTRUCTIONS.md              \u2014 module rules and guidance",
+      "  Resume Working Draft.md      \u2014 the resume you are actively editing",
+      "  Resume Last Submitted.md     \u2014 the version you last sent to an employer",
+      "```",
+      "",
+      "### Commands",
+      "",
+      "| Command | What it does |",
+      "|---------|-------------|",
+      "| `/resume-refresh` | Refresh your resume working draft from your graph |"
+    ].join("\n");
   }
   // Resume has no module-specific profile fields — no onAdd/onRemove needed.
 };
@@ -258,6 +319,28 @@ function mergeSections(existing, newSections, storedChecksums, relativePath, ove
   }
   return { content: result, sections: outcomes };
 }
+function removeSection(id, content) {
+  const sections = parseSections(content);
+  const section = sections.find((s) => s.id === id);
+  if (!section) return content;
+  const { start, end } = section;
+  let before = content.slice(0, start);
+  before = before.replace(/(\r?\n)+$/, "");
+  let after = content.slice(end);
+  after = after.replace(/^(\r?\n)+/, "");
+  let result;
+  if (before === "" && after === "") {
+    result = "";
+  } else if (before === "") {
+    result = after;
+  } else if (after === "") {
+    result = before;
+  } else {
+    result = before + "\n\n" + after;
+  }
+  result = result.replace(/\n{3,}/g, "\n\n");
+  return result;
+}
 function inspectSections(relativePath, existing, storedChecksums) {
   const sections = parseSections(existing);
   const editedIds = [];
@@ -417,6 +500,11 @@ function validateManifestFrontmatter(moduleName, content) {
 }
 function profileToVars(profile, liProfileUrl) {
   const today = (/* @__PURE__ */ new Date()).toISOString().split("T")[0];
+  const modulesSection = (profile.modules ?? []).length ? profile.modules.map((id) => {
+    const def = getModule(id);
+    const label2 = def?.label ?? id;
+    return `- [${label2} module context](.claude/modules/${id}/CLAUDE.md)`;
+  }).join("\n") : "_No modules installed._";
   return {
     PATINA_NAME: profile.patina_name,
     USER_NAME: profile.name,
@@ -427,11 +515,17 @@ function profileToVars(profile, liProfileUrl) {
     CONTENT_DIR: profile.content_dir,
     EDITOR: profile.editor,
     LI_PROFILE_URL: liProfileUrl ?? profile.linkedin?.profile_url ?? "",
-    TODAY: today
+    TODAY: today,
+    STALENESS_THRESHOLD: (() => {
+      const d = Number(profile.staleness_threshold_days ?? 30);
+      return String(Number.isFinite(d) && d > 0 ? d : 30);
+    })(),
+    MODULES_SECTION: modulesSection
   };
 }
 function baseManagedFiles(vars, editor, targetDir) {
   const files = [
+    ["README.md", render(tpl("README.md"), vars)],
     ["CLAUDE.md", render(tpl("CLAUDE.md"), vars)],
     [".claude/settings.json", tpl(".claude/settings.json")],
     [".claude/commands/add.md", render(tpl(".claude/commands/add.md"), vars)],
@@ -484,22 +578,24 @@ async function scaffold(opts) {
     created: today,
     ...modules.includes("linkedin") && liProfileUrl ? { linkedin: { profile_url: liProfileUrl } } : {}
   };
-  const vars = {
-    PATINA_NAME: patinaName,
-    USER_NAME: userName,
-    USER_TITLE: title ?? "",
-    ROLE_DESCRIPTION: roleDescription,
-    COMPANY_NAME: work.company_name,
-    COMPANY_DESCRIPTION: work.company_description ?? "",
-    CONTENT_DIR: contentDir,
-    EDITOR: editor,
-    LI_PROFILE_URL: liProfileUrl,
-    TODAY: today
-  };
+  const vars = profileToVars(tempProfile, liProfileUrl);
   mkdirSync2(targetDir, { recursive: true });
   const checksums = {};
+  const baseFiles = baseManagedFiles(vars, editor, targetDir);
+  const readmePath = join5(targetDir, "README.md");
+  const filteredBaseFiles = baseFiles.filter(([rel]) => {
+    if (rel === "README.md") {
+      if (existsSync5(readmePath)) {
+        const existing = readFileSync6(readmePath, "utf8");
+        if (!hasFences(existing)) {
+          return false;
+        }
+      }
+    }
+    return true;
+  });
   const managedFiles = [
-    ...baseManagedFiles(vars, editor, targetDir),
+    ...filteredBaseFiles,
     ...modules.flatMap((m) => moduleManagedFiles(m, vars))
   ];
   for (const module of modules) {
@@ -513,6 +609,17 @@ async function scaffold(opts) {
       checksums[`${relativePath}:${s.id}`] = s.newChecksum;
     }
   }
+  for (const module of modules) {
+    const def = getModule(module);
+    if (def?.readmeBlock) {
+      const block = renderSection(module, def.readmeBlock(vars));
+      const result = writeManagedFile(targetDir, "README.md", block, checksums);
+      checksums["README.md"] = result.checksum;
+      for (const s of result.sections ?? []) {
+        checksums[`README.md:${s.id}`] = s.newChecksum;
+      }
+    }
+  }
   const baseDirs = ["notes", "skills", "posts"];
   for (const dir of baseDirs) {
     touch(targetDir, `${contentDir}/${dir}/.gitkeep`);
@@ -533,16 +640,16 @@ ${STATE_FILENAME}
 }
 
 // src/validate.ts
-import { existsSync as existsSync5, readFileSync as readFileSync6, readdirSync } from "fs";
+import { existsSync as existsSync6, readFileSync as readFileSync7, readdirSync } from "fs";
 import { join as join6, relative, sep, basename } from "path";
 var NOTES = CONTENT_SUBDIRS[0];
 var SKILLS = CONTENT_SUBDIRS[1];
 var POSTS = CONTENT_SUBDIRS[2];
 function findPatinaRoot(cwd) {
-  return existsSync5(join6(cwd, "profile.yaml")) ? cwd : null;
+  return existsSync6(join6(cwd, "profile.yaml")) ? cwd : null;
 }
 function listMarkdownFiles(dir) {
-  if (!existsSync5(dir)) return [];
+  if (!existsSync6(dir)) return [];
   const results = [];
   for (const entry of readdirSync(dir, { withFileTypes: true })) {
     const fullPath = join6(dir, entry.name);
@@ -605,7 +712,7 @@ function checkSkillNotes(root, profile) {
   const noteSlugs = new Set(noteFiles.map((f) => basename(f, ".md")));
   const issues = [];
   for (const skillFile of listMarkdownFiles(skillsDir)) {
-    const content = readFileSync6(skillFile, "utf8");
+    const content = readFileSync7(skillFile, "utf8");
     const links = extractWikiLinks(content);
     for (const { target, line } of links) {
       if (!noteSlugs.has(target)) {
@@ -632,7 +739,7 @@ function checkWikiLinks(root, profile) {
     ...listMarkdownFiles(postsDir)
   ];
   for (const file of filesToScan) {
-    const content = readFileSync6(file, "utf8");
+    const content = readFileSync7(file, "utf8");
     const links = extractWikiLinks(content);
     for (const { target, line } of links) {
       if (!noteSlugs.has(target)) {
@@ -651,8 +758,8 @@ function checkExclusions(root, profile) {
   const contentDir = join6(root, profile.content_dir ?? "graph");
   const notesDir = join6(contentDir, NOTES);
   const exclusionsPath = join6(notesDir, "exclusions.md");
-  if (!existsSync5(exclusionsPath)) return [];
-  const content = readFileSync6(exclusionsPath, "utf8");
+  if (!existsSync6(exclusionsPath)) return [];
+  const content = readFileSync7(exclusionsPath, "utf8");
   const items = parseExclusions(content);
   if (items.length === 0) return [];
   const skillsDir = join6(contentDir, SKILLS);
@@ -664,7 +771,7 @@ function checkExclusions(root, profile) {
   const issues = [];
   const seen = /* @__PURE__ */ new Set();
   for (const file of filesToScan) {
-    const fileContent = readFileSync6(file, "utf8");
+    const fileContent = readFileSync7(file, "utf8");
     const lines = fileContent.split("\n");
     for (let i = 0; i < lines.length; i++) {
       const lineText = lines[i];
@@ -900,8 +1007,8 @@ function writeProfile(cwd, profile) {
 }
 function removeManagedFileIfUnmodified(targetDir, rel, stored) {
   const fullPath = join7(targetDir, rel);
-  if (!existsSync6(fullPath)) return "deleted";
-  const fileContent = readFileSync7(fullPath, "utf8");
+  if (!existsSync7(fullPath)) return "deleted";
+  const fileContent = readFileSync8(fullPath, "utf8");
   if (hasFences(fileContent)) {
     const editedIds = inspectSections(rel, fileContent, stored);
     if (editedIds.length > 0) {
@@ -992,6 +1099,32 @@ function applyProfileUpdate(cwd, profile, fields, overwrite) {
       updated.push(rel);
     }
   }
+  for (const module of updatedProfile.modules) {
+    const def = getModule(module);
+    if (def?.readmeBlock) {
+      const readmePath = join7(cwd, "README.md");
+      const readmeExists = existsSync7(readmePath);
+      const readmeHasFences = readmeExists ? hasFences(readFileSync8(readmePath, "utf8")) : false;
+      if (!readmeExists || readmeHasFences) {
+        const block = renderSection(module, def.readmeBlock(vars));
+        const result = writeManagedFile(cwd, "README.md", block, newChecksums, overwrite);
+        newChecksums["README.md"] = result.checksum;
+        for (const s of result.sections ?? []) {
+          const sKey = `README.md:${s.id}`;
+          if (s.outcome !== "skipped") newChecksums[sKey] = s.newChecksum;
+          else {
+            newChecksums[sKey] = stored[sKey] ?? "";
+            keptSections.push(sKey);
+          }
+        }
+        if (result.outcome === "skipped") {
+          skipped.push(`README.md:${module}`);
+        } else if (result.outcome !== "updated" || result.sections?.some((s) => s.id === module && s.outcome !== "unchanged")) {
+          updated.push(`README.md:${module}`);
+        }
+      }
+    }
+  }
   for (const [rel, hash] of Object.entries(stored)) {
     if (!(rel in newChecksums)) {
       newChecksums[rel] = hash;
@@ -1086,8 +1219,8 @@ async function runUpdateProfile(cwd, profile) {
   for (const [rel, content] of previewFiles) {
     if (hasFences(content)) {
       const fullPath = join7(cwd, rel);
-      if (existsSync6(fullPath)) {
-        const existingContent = readFileSync7(fullPath, "utf8");
+      if (existsSync7(fullPath)) {
+        const existingContent = readFileSync8(fullPath, "utf8");
         const editedIds = inspectSections(rel, existingContent, storedChecksums);
         for (const sectionId of editedIds) {
           const confirmed = await p.confirm({
@@ -1149,12 +1282,28 @@ function applyModuleChanges(cwd, profile, toAdd, toRemove, moduleInputs) {
     }
     for (const [relativePath, content] of moduleContentFiles(module, vars, contentDir)) {
       const fullPath = join7(cwd, relativePath);
-      if (!existsSync6(fullPath)) {
+      if (!existsSync7(fullPath)) {
         mkdirSync3(dirname4(fullPath), { recursive: true });
         writeFileSync4(fullPath, content, "utf8");
         added.push(relativePath);
       }
     }
+    if (def?.readmeBlock) {
+      const readmePath = join7(cwd, "README.md");
+      const readmeExists = existsSync7(readmePath);
+      const readmeHasFences = readmeExists ? hasFences(readFileSync8(readmePath, "utf8")) : false;
+      if (!readmeExists || readmeHasFences) {
+        const block = renderSection(module, def.readmeBlock(vars));
+        const result = writeManagedFile(cwd, "README.md", block, newChecksums);
+        newChecksums["README.md"] = result.checksum;
+        for (const s of result.sections ?? []) {
+          newChecksums[`README.md:${s.id}`] = s.newChecksum;
+        }
+        if (result.outcome !== "skipped") added.push(`README.md:${module}`);
+      } else {
+        kept.push("README.md");
+      }
+    }
     if (!updatedProfile.modules.includes(module)) {
       updatedProfile.modules = [...updatedProfile.modules, module];
     }
@@ -1175,11 +1324,40 @@ function applyModuleChanges(cwd, profile, toAdd, toRemove, moduleInputs) {
         kept.push(rel);
       }
     }
+    const readmePath = join7(cwd, "README.md");
+    if (existsSync7(readmePath)) {
+      const before = readFileSync8(readmePath, "utf8");
+      const editedIds = inspectSections("README.md", before, stored);
+      if (!editedIds.includes(module)) {
+        const after = removeSection(module, before);
+        if (after !== before) {
+          writeFileSync4(readmePath, after, "utf8");
+          newChecksums["README.md"] = hashContent(after);
+          delete newChecksums[`README.md:${module}`];
+          deleted.push(`README.md:${module}`);
+        }
+      } else {
+        keptSections.push(`README.md:${module}`);
+      }
+    }
     updatedProfile.modules = updatedProfile.modules.filter((m) => m !== module);
     if (def?.onRemove) {
       updatedProfile = def.onRemove(updatedProfile);
     }
   }
+  const finalVars = profileToVars(updatedProfile);
+  for (const [rel, content] of baseManagedFiles(finalVars, updatedProfile.editor, cwd)) {
+    const result = writeManagedFile(cwd, rel, content, newChecksums);
+    newChecksums[rel] = result.checksum;
+    for (const s of result.sections ?? []) {
+      const sKey = `${rel}:${s.id}`;
+      if (s.outcome !== "skipped") newChecksums[sKey] = s.newChecksum;
+      else {
+        newChecksums[sKey] = newChecksums[sKey] ?? "";
+        keptSections.push(sKey);
+      }
+    }
+  }
   writeState(cwd, { checksums: newChecksums });
   const finalProfile = stripLegacyChecksums(updatedProfile);
   writeProfile(cwd, finalProfile);
@@ -1208,6 +1386,16 @@ async function runUpdateModules(cwd, profile) {
     p.outro(chalk.hex("#94A3B8")("No changes \u2014 modules unchanged."));
     return;
   }
+  const changeLines = [];
+  for (const m of toAdd) {
+    const def = getModule(m);
+    changeLines.push(`Adding ${def?.label ?? m}: appends a section to README.md, adds a link to CLAUDE.md`);
+  }
+  for (const m of toRemove) {
+    const def = getModule(m);
+    changeLines.push(`Removing ${def?.label ?? m}: removes its section from README.md and its link from CLAUDE.md`);
+  }
+  p.note(changeLines.join("\n"), label("Planned changes"));
   let liProfileUrl;
   if (toAdd.includes("linkedin") && !profile.linkedin?.profile_url) {
     const url = await p.text({

package/dist/templates/CLAUDE.md

@@ -44,9 +44,34 @@ The graph is the source of truth. Nothing gets added to generated content unless
 - Never delete skill files automatically. Surface them to the user and wait for confirmation.
 - `{{CONTENT_DIR}}/notes/exclusions.md` overrides everything. If something is listed there, it must not appear in any generated output.
 
+## On session start
+
+Before anything else, scan the graph for stale content and surface a brief report.
+
+Read the file modification times for all three areas — skip `.gitkeep`, `README.md`, and `exclusions.md` in every directory:
+- `{{CONTENT_DIR}}/notes/`
+- `{{CONTENT_DIR}}/skills/`
+- `{{CONTENT_DIR}}/posts/`
+
+List items not modified in the last **{{STALENESS_THRESHOLD}} days**, grouped by area:
+
+- **Notes** — stale note slugs
+- **Skills** — stale skill slugs
+- **Posts** — stale draft slugs
+
+Skip any area with nothing stale. If everything is fresh, say so in one line. Keep the report brief — one line per area. Then ask:
+
+> What are we working on today?
+
 ## Slash commands
 
 | Command | What it does |
 |---------|-------------|
 | `/add <description>` | Add a skill, project, or experience to your graph |
 | `/reflect [slug]` | Review your graph for gaps, completions, and stale skills — also runs all installed module hooks |
+
+## Modules
+
+<!-- patina:modules:start -->
+{{MODULES_SECTION}}
+<!-- patina:modules:end -->

package/dist/templates/README.md

@@ -0,0 +1,12 @@
+# {{PATINA_NAME}}
+
+<!-- patina:base:start -->
+This is your patina — a personal knowledge base for your professional story.
+
+- Profile and config live in `profile.yaml` and `CLAUDE.md`.
+- Your notes, skills, and posts live in `{{CONTENT_DIR}}/`.
+
+## Installed modules
+
+Module-specific sections are appended below as you install modules.
+<!-- patina:base:end -->

package/dist/templates/modules/linkedin/CLAUDE.md

@@ -0,0 +1,35 @@
+# LinkedIn Module Context
+
+This module helps you draft and refine your LinkedIn profile using your patina graph as the source of truth.
+
+## Folder structure
+
+```
+{{CONTENT_DIR}}/linkedin/
+  INSTRUCTIONS.md              — module-specific rules and guidance
+  LinkedIn Current State.md    — your current live profile copy
+  LinkedIn About.md            — draft for the About section
+  LinkedIn Headline.md         — draft for your headline
+  LinkedIn Experience.md       — draft for your experience entries
+  LinkedIn Skills.md           — draft for your skills section
+  LinkedIn Featured.md         — draft for featured content
+  LinkedIn Activity.md         — draft for activity/posts section
+```
+
+## Slash commands
+
+| Command | What it does |
+|---------|-------------|
+| `/li-all` | Run all LinkedIn section drafts in sequence |
+| `/li-about` | Draft or refine your LinkedIn About section |
+| `/li-headline` | Draft or refine your LinkedIn headline |
+| `/li-experience` | Draft or refine your LinkedIn experience entries |
+| `/li-skills` | Draft or refine your LinkedIn skills section |
+| `/li-featured` | Draft or refine your LinkedIn featured content |
+| `/li-activity` | Draft or refine your LinkedIn activity section |
+
+## How it works
+
+LinkedIn commands read your `{{CONTENT_DIR}}/` graph — notes, skills, and posts — and draft profile copy grounded in that evidence. They never invent claims not supported by your notes.
+
+The `/reflect` command also runs the LinkedIn reflect hook (`/li-all`) to keep your drafts current.

package/dist/templates/modules/resume/CLAUDE.md

@@ -0,0 +1,24 @@
+# Resume Module Context
+
+This module helps you keep your resume current by synthesising it from your patina graph.
+
+## Folder structure
+
+```
+{{CONTENT_DIR}}/resume/
+  INSTRUCTIONS.md              — module-specific rules and guidance
+  Resume Working Draft.md      — the resume you are actively editing
+  Resume Last Submitted.md     — the version you last sent to an employer
+```
+
+## Slash commands
+
+| Command | What it does |
+|---------|-------------|
+| `/resume-refresh` | Refresh your resume working draft from your graph |
+
+## How it works
+
+The `/resume-refresh` command reads your `{{CONTENT_DIR}}/` graph — notes, skills, and experience — and updates your Resume Working Draft to reflect your current professional state. It never overwrites Resume Last Submitted; that file is yours to update manually when you send an application.
+
+The working draft is compared against the last submitted version so you can see what has changed before sending.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "my-patina",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Personal professional knowledge graph — setup and management",
   "type": "module",
   "bin": {