@starterculture/devkeep-actions 0.1.0 → 0.3.0

package/dist/consolidate-release.js

@@ -128,6 +128,11 @@ var EMPTY_PROJECT_USAGE = {
   draftLogEntry: ZERO_USAGE,
   consolidateRelease: ZERO_USAGE,
   syncUserManual: ZERO_USAGE,
+  syncTestPlan: ZERO_USAGE,
+  syncVisualizer: ZERO_USAGE,
+  analyzeCodebase: ZERO_USAGE,
+  syncOnboarding: ZERO_USAGE,
+  releaseNotes: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {

package/dist/draft-log-entry.js

@@ -128,6 +128,11 @@ var EMPTY_PROJECT_USAGE = {
   draftLogEntry: ZERO_USAGE,
   consolidateRelease: ZERO_USAGE,
   syncUserManual: ZERO_USAGE,
+  syncTestPlan: ZERO_USAGE,
+  syncVisualizer: ZERO_USAGE,
+  analyzeCodebase: ZERO_USAGE,
+  syncOnboarding: ZERO_USAGE,
+  releaseNotes: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {

package/dist/draft-release-notes.js

@@ -0,0 +1,446 @@
+#!/usr/bin/env node
+
+// ../../modules/core/dist/github/client.js
+import { Octokit } from "@octokit/rest";
+function createGithubClient(token) {
+  if (!token) {
+    throw new Error("GitHub token is required");
+  }
+  return new Octokit({ auth: token });
+}
+
+// ../../modules/core/dist/github/retryOnConflict.js
+async function retryOnConflict(attempt, maxAttempts = 3) {
+  for (let tryNumber = 1; ; tryNumber++) {
+    try {
+      return await attempt();
+    } catch (error) {
+      const status = error.status;
+      if (tryNumber >= maxAttempts || status !== 409 && status !== 422) {
+        throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 300 * tryNumber));
+    }
+  }
+}
+
+// ../../modules/core/dist/tokenUsage.js
+var ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
+function addTokenUsage(a, b) {
+  return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+}
+
+// ../../modules/core/dist/rollover.js
+var ZERO_ROLLOVER_USAGE = {
+  today: { key: "", usage: ZERO_USAGE },
+  month: { key: "", usage: ZERO_USAGE }
+};
+function todayKey(now = /* @__PURE__ */ new Date()) {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function monthKey(now = /* @__PURE__ */ new Date()) {
+  return todayKey(now).slice(0, 7);
+}
+function addRolloverUsage(current, delta, now = /* @__PURE__ */ new Date()) {
+  const nowTodayKey = todayKey(now);
+  const nowMonthKey = monthKey(now);
+  return {
+    today: {
+      key: nowTodayKey,
+      usage: addTokenUsage(current.today.key === nowTodayKey ? current.today.usage : ZERO_USAGE, delta)
+    },
+    month: {
+      key: nowMonthKey,
+      usage: addTokenUsage(current.month.key === nowMonthKey ? current.month.usage : ZERO_USAGE, delta)
+    }
+  };
+}
+
+// ../../modules/core/dist/claude/client.js
+import Anthropic from "@anthropic-ai/sdk";
+function createClaudeClient(apiKey) {
+  const key = apiKey ?? process.env.ANTHROPIC_API_KEY;
+  if (!key) {
+    throw new Error("ANTHROPIC_API_KEY is not set");
+  }
+  return new Anthropic({ apiKey: key });
+}
+
+// ../../modules/core/dist/claude/complete.js
+var DEFAULT_MAX_CONTINUATIONS = 5;
+var CONTINUATION_USER_MESSAGE = "Continue exactly where you left off. Do not repeat any text already written, and do not add any preamble or commentary \u2014 resume the previous response verbatim from the exact cutoff point.";
+async function createCompleteMessage(claude, params, { maxContinuations = DEFAULT_MAX_CONTINUATIONS, timeoutMs, signal } = {}) {
+  let fullText = "";
+  let usage = ZERO_USAGE;
+  const requestOptions = timeoutMs !== void 0 || signal !== void 0 ? { timeout: timeoutMs, signal } : void 0;
+  for (let attempt = 0; attempt <= maxContinuations; attempt++) {
+    const messages = fullText ? [
+      ...params.messages,
+      { role: "assistant", content: fullText },
+      { role: "user", content: CONTINUATION_USER_MESSAGE }
+    ] : params.messages;
+    const message = requestOptions ? await claude.messages.create({ ...params, messages }, requestOptions) : await claude.messages.create({ ...params, messages });
+    const text = message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+    fullText += text;
+    usage = addTokenUsage(usage, {
+      inputTokens: message.usage?.input_tokens ?? 0,
+      outputTokens: message.usage?.output_tokens ?? 0
+    });
+    if (message.stop_reason !== "max_tokens") {
+      return { text: fullText, usage };
+    }
+  }
+  throw new Error(`Claude response still hit max_tokens after ${maxContinuations} continuation attempts \u2014 refusing to return truncated content.`);
+}
+
+// ../../modules/core/dist/modelRegistry.js
+var MODEL_REGISTRY = {
+  fast: {
+    description: "Quick, cheap work where depth matters least.",
+    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5" }]
+  },
+  balanced: {
+    description: "The everyday tier: chat, log entries, release notes, the daily digest. Frequent enough that cost matters.",
+    models: [{ id: "claude-sonnet-5", label: "Sonnet 5" }]
+  },
+  capable: {
+    description: "Deeper reasoning for infrequent, high-value work where getting it right outweighs the cost.",
+    models: [{ id: "claude-opus-5", label: "Opus 5" }]
+  },
+  max: {
+    description: "Maximum depth, for long-running agentic work. Opt-in \u2014 the most expensive tier.",
+    models: [{ id: "claude-fable-5", label: "Fable 5" }]
+  }
+};
+function defaultModelFor(tier) {
+  const [current] = MODEL_REGISTRY[tier].models;
+  if (!current) {
+    throw new Error(`Model tier "${tier}" has no models registered`);
+  }
+  return current.id;
+}
+
+// ../../modules/devlore/dist/prompt.js
+function buildReleaseNotesPrompt(input) {
+  return [
+    `Project: ${input.projectName}`,
+    `Release: ${input.tag}`,
+    input.previousTag ? `Previous release: ${input.previousTag}. The entries below are the work done since then.` : "This is the first release, so the entries below cover everything so far.",
+    "",
+    "Below are the decision log entries Devkeep recorded for the work in this release.",
+    "",
+    ...input.logEntries,
+    "",
+    "Write release notes for the people who use this product. Lead with what they can now do that they could not before, and what changed in behaviour they will notice. Group related changes rather than listing entries one by one.",
+    "",
+    "Plain language, not commit-history jargon: no file paths, no function names, no internal module names unless the user genuinely interacts with them by name.",
+    "",
+    'If this release contains nothing user-facing \u2014 internal refactoring, tooling, workflow changes \u2014 say exactly that in a sentence or two. Do not manufacture user-facing significance that is not there; an honest "this release contains internal changes only" is the correct output, and inventing a feature to fill the page is worse than a short note.',
+    "",
+    "Do NOT include a top-level heading \u2014 one is added automatically. Start directly with the content.",
+    "",
+    "Return the notes only \u2014 no preamble, no meta-commentary."
+  ].join("\n");
+}
+
+// ../../modules/devlore/dist/redact.js
+var REDACTED = "[REDACTED]";
+var KNOWN_SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /gh[pousr]_[A-Za-z0-9]{36,}/g,
+  /github_pat_[A-Za-z0-9_]{20,}/g,
+  /sk-ant-[A-Za-z0-9_-]{20,}/g,
+  /sk-[A-Za-z0-9]{20,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+  /xox[baprs]-[A-Za-z0-9-]{10,}/g,
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g
+];
+var SECRET_KEYWORD = "(?:API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CREDENTIAL)";
+var ASSIGNMENT_PATTERN = new RegExp(`((?:[A-Za-z0-9]+[_-])*${SECRET_KEYWORD}(?:[_-][A-Za-z0-9]+)*\\s*[:=]\\s*)(["']?)([^"'\`\\s]+)\\2`, "gi");
+function redactText(text) {
+  let result = text;
+  for (const pattern of KNOWN_SECRET_PATTERNS) {
+    result = result.replace(pattern, REDACTED);
+  }
+  result = result.replace(ASSIGNMENT_PATTERN, (_match, prefix, quote) => `${prefix}${quote}${REDACTED}${quote}`);
+  return result;
+}
+
+// ../../modules/devlore/dist/ciUsage.js
+var EMPTY_PROJECT_USAGE = {
+  draftLogEntry: ZERO_USAGE,
+  consolidateRelease: ZERO_USAGE,
+  syncUserManual: ZERO_USAGE,
+  syncTestPlan: ZERO_USAGE,
+  syncVisualizer: ZERO_USAGE,
+  analyzeCodebase: ZERO_USAGE,
+  syncOnboarding: ZERO_USAGE,
+  releaseNotes: ZERO_USAGE,
+  rollover: ZERO_ROLLOVER_USAGE
+};
+function usagePath(projectName) {
+  return `projects/${projectName}/usage.json`;
+}
+async function getUsageFile(octokit, { owner, repo, projectName }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({
+      owner,
+      repo,
+      path: usagePath(projectName)
+    });
+    if (Array.isArray(data) || data.type !== "file") {
+      return { usage: EMPTY_PROJECT_USAGE };
+    }
+    const parsed = JSON.parse(Buffer.from(data.content, "base64").toString("utf-8"));
+    const usage = { ...EMPTY_PROJECT_USAGE, ...parsed };
+    return { usage, sha: data.sha };
+  } catch (error) {
+    if (isNotFound(error)) {
+      return { usage: EMPTY_PROJECT_USAGE };
+    }
+    throw error;
+  }
+}
+function addUsage(current, source, delta, now = /* @__PURE__ */ new Date()) {
+  return {
+    ...current,
+    [source]: addTokenUsage(current[source], delta),
+    rollover: addRolloverUsage(current.rollover, delta, now)
+  };
+}
+async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */ new Date()) {
+  const { owner, repo, projectName, branch } = params;
+  await retryOnConflict(async () => {
+    const { usage: current, sha } = await getUsageFile(octokit, { owner, repo, projectName });
+    const updated = addUsage(current, source, delta, now);
+    await octokit.rest.repos.createOrUpdateFileContents({
+      owner,
+      repo,
+      path: usagePath(projectName),
+      message: `Record ${source} token usage: ${projectName}`,
+      content: Buffer.from(JSON.stringify(updated, null, 2), "utf-8").toString("base64"),
+      branch,
+      sha
+    });
+  });
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/logEntries.js
+function logEntriesDir(projectName) {
+  return `projects/${projectName}/log`;
+}
+async function listLogEntries(octokit, { owner, repo, projectName }) {
+  const dir = logEntriesDir(projectName);
+  let files;
+  try {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: dir });
+    if (!Array.isArray(data)) {
+      return [];
+    }
+    files = data;
+  } catch (error) {
+    if (isNotFound2(error)) {
+      return [];
+    }
+    throw error;
+  }
+  const entries = await Promise.all(files.filter((file) => file.type === "file").map(async (file) => {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: file.path });
+    if (Array.isArray(data) || data.type !== "file") {
+      return null;
+    }
+    return { path: file.path, content: Buffer.from(data.content, "base64").toString("utf-8") };
+  }));
+  return entries.filter((entry) => entry !== null).sort((a, b) => a.path.localeCompare(b.path));
+}
+function isNotFound2(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/releaseScope.js
+var TAG_PATTERN = /^v(\d+)\.(\d+)\.(\d+)$/;
+function parseTag(tag) {
+  const match = tag.match(TAG_PATTERN);
+  if (!match) {
+    return null;
+  }
+  return [Number(match[1]), Number(match[2]), Number(match[3])];
+}
+function compareTags(a, b) {
+  return a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
+}
+async function findPreviousTag(octokit, { owner, repo, currentTag }) {
+  const current = parseTag(currentTag);
+  if (!current) {
+    return null;
+  }
+  const tags = await octokit.paginate(octokit.rest.repos.listTags, { owner, repo, per_page: 100 });
+  let best = null;
+  for (const tag of tags) {
+    const version = parseTag(tag.name);
+    if (!version || compareTags(version, current) >= 0) {
+      continue;
+    }
+    if (!best || compareTags(version, best.version) > 0) {
+      best = { name: tag.name, version };
+    }
+  }
+  return best?.name ?? null;
+}
+async function listCommitShasSince(octokit, { owner, repo, previousTag, currentTag }) {
+  try {
+    const { data } = await octokit.rest.repos.compareCommitsWithBasehead({
+      owner,
+      repo,
+      basehead: `${previousTag}...${currentTag}`
+    });
+    return new Set(data.commits.map((commit) => commit.sha));
+  } catch {
+    return null;
+  }
+}
+function logEntryCommitSha(entry) {
+  const filename = entry.path.split("/").pop() ?? "";
+  return filename.replace(/\.md$/, "");
+}
+async function selectLogEntriesSincePreviousRelease({ vaultOctokit, projectOctokit, vaultOwner, vaultRepoName, projectName, projectOwner, projectRepoName, tag }) {
+  const allEntries = await listLogEntries(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName });
+  const previousTag = await findPreviousTag(projectOctokit, {
+    owner: projectOwner,
+    repo: projectRepoName,
+    currentTag: tag
+  });
+  if (!previousTag) {
+    return { logEntries: allEntries, previousTag: null };
+  }
+  const commitShas = await listCommitShasSince(projectOctokit, {
+    owner: projectOwner,
+    repo: projectRepoName,
+    previousTag,
+    currentTag: tag
+  });
+  if (!commitShas) {
+    return { logEntries: allEntries, previousTag };
+  }
+  return { logEntries: allEntries.filter((entry) => commitShas.has(logEntryCommitSha(entry))), previousTag };
+}
+
+// ../../modules/devlore/dist/releaseNotes.js
+function releaseNotePath(projectName, tag) {
+  return `${releaseNotesDir(projectName)}/${tag}.md`;
+}
+function releaseNotesHeading(projectName, tag) {
+  return `# ${projectName} \u2014 ${tag}`;
+}
+function releaseNotesBanner() {
+  return "> **Do not move, rename, or edit this file.** Devkeep drafted these release notes when this tag was cut.";
+}
+function releaseNotesDir(projectName) {
+  return `projects/${projectName}/releases`;
+}
+
+// ../../modules/devlore/dist/actions/draftReleaseNotes.js
+var MODEL_TIER = "balanced";
+var MAX_TOKENS = 2e4;
+var MAX_CONTINUATIONS = 8;
+var VAULT_BRANCH = "main";
+async function draftReleaseNotes({ projectOctokit, vaultOctokit, claude, projectOwner, projectRepoName, vaultOwner, vaultRepoName, projectName, tag }) {
+  const { logEntries, previousTag } = await selectLogEntriesSincePreviousRelease({
+    vaultOctokit,
+    projectOctokit,
+    vaultOwner,
+    vaultRepoName,
+    projectName,
+    projectOwner,
+    projectRepoName,
+    tag
+  });
+  const prompt = buildReleaseNotesPrompt({
+    projectName,
+    tag,
+    previousTag,
+    logEntries: logEntries.map((entry) => redactText(entry.content))
+  });
+  const { text, usage } = await createCompleteMessage(claude, { model: defaultModelFor(MODEL_TIER), max_tokens: MAX_TOKENS, messages: [{ role: "user", content: prompt }] }, { maxContinuations: MAX_CONTINUATIONS });
+  const content = `${releaseNotesBanner()}
+
+${releaseNotesHeading(projectName, tag)}
+
+${text.trim()}
+`;
+  const path = releaseNotePath(projectName, tag);
+  await vaultOctokit.rest.repos.createOrUpdateFileContents({
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    path,
+    message: `Draft release notes: ${projectName} ${tag}`,
+    content: Buffer.from(content, "utf-8").toString("base64"),
+    branch: VAULT_BRANCH,
+    sha: await getExistingSha(vaultOctokit, vaultOwner, vaultRepoName, path)
+  });
+  if (usage.inputTokens > 0 || usage.outputTokens > 0) {
+    await recordUsage(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName, branch: VAULT_BRANCH }, "releaseNotes", usage);
+  }
+  return { path, previousTag, entryCount: logEntries.length, content, usage };
+}
+async function getExistingSha(octokit, owner, repo, path) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path });
+    return Array.isArray(data) || data.type !== "file" ? void 0 : data.sha;
+  } catch {
+    return void 0;
+  }
+}
+
+// ../../modules/devlore/dist/bin/draftReleaseNotesCli.js
+function requireEnv(env, name) {
+  const value = env[name];
+  if (!value) {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+}
+var defaultDeps = {
+  env: process.env,
+  draftReleaseNotes,
+  createGithubClient,
+  createClaudeClient,
+  log: console.log
+};
+async function main(deps = defaultDeps) {
+  const { env } = deps;
+  const projectName = requireEnv(env, "PROJECT_NAME");
+  const [projectOwner, projectRepoName] = requireEnv(env, "PROJECT_REPO").split("/");
+  const [vaultOwner, vaultRepoName] = requireEnv(env, "VAULT_REPO").split("/");
+  const vaultOctokit = deps.createGithubClient(requireEnv(env, "DEVKEEP_GITHUB_TOKEN"));
+  const projectOctokit = deps.createGithubClient(requireEnv(env, "GITHUB_TOKEN"));
+  const claude = deps.createClaudeClient(requireEnv(env, "ANTHROPIC_API_KEY"));
+  const result = await deps.draftReleaseNotes({
+    projectOctokit,
+    vaultOctokit,
+    claude,
+    projectOwner,
+    projectRepoName,
+    vaultOwner,
+    vaultRepoName,
+    projectName,
+    tag: requireEnv(env, "TAG")
+  });
+  deps.log(`Drafted release notes: ${result.path} (previous tag: ${result.previousTag ?? "none"}, ${result.entryCount} entries)`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+export {
+  main,
+  requireEnv
+};

package/dist/sync-onboarding.js

@@ -0,0 +1,454 @@
+#!/usr/bin/env node
+
+// ../../modules/core/dist/github/client.js
+import { Octokit } from "@octokit/rest";
+function createGithubClient(token) {
+  if (!token) {
+    throw new Error("GitHub token is required");
+  }
+  return new Octokit({ auth: token });
+}
+
+// ../../modules/core/dist/github/retryOnConflict.js
+async function retryOnConflict(attempt, maxAttempts = 3) {
+  for (let tryNumber = 1; ; tryNumber++) {
+    try {
+      return await attempt();
+    } catch (error) {
+      const status = error.status;
+      if (tryNumber >= maxAttempts || status !== 409 && status !== 422) {
+        throw error;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 300 * tryNumber));
+    }
+  }
+}
+
+// ../../modules/core/dist/tokenUsage.js
+var ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
+function addTokenUsage(a, b) {
+  return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+}
+
+// ../../modules/core/dist/rollover.js
+var ZERO_ROLLOVER_USAGE = {
+  today: { key: "", usage: ZERO_USAGE },
+  month: { key: "", usage: ZERO_USAGE }
+};
+function todayKey(now = /* @__PURE__ */ new Date()) {
+  const year = now.getFullYear();
+  const month = String(now.getMonth() + 1).padStart(2, "0");
+  const day = String(now.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+function monthKey(now = /* @__PURE__ */ new Date()) {
+  return todayKey(now).slice(0, 7);
+}
+function addRolloverUsage(current, delta, now = /* @__PURE__ */ new Date()) {
+  const nowTodayKey = todayKey(now);
+  const nowMonthKey = monthKey(now);
+  return {
+    today: {
+      key: nowTodayKey,
+      usage: addTokenUsage(current.today.key === nowTodayKey ? current.today.usage : ZERO_USAGE, delta)
+    },
+    month: {
+      key: nowMonthKey,
+      usage: addTokenUsage(current.month.key === nowMonthKey ? current.month.usage : ZERO_USAGE, delta)
+    }
+  };
+}
+
+// ../../modules/core/dist/claude/client.js
+import Anthropic from "@anthropic-ai/sdk";
+function createClaudeClient(apiKey) {
+  const key = apiKey ?? process.env.ANTHROPIC_API_KEY;
+  if (!key) {
+    throw new Error("ANTHROPIC_API_KEY is not set");
+  }
+  return new Anthropic({ apiKey: key });
+}
+
+// ../../modules/core/dist/claude/complete.js
+var DEFAULT_MAX_CONTINUATIONS = 5;
+var CONTINUATION_USER_MESSAGE = "Continue exactly where you left off. Do not repeat any text already written, and do not add any preamble or commentary \u2014 resume the previous response verbatim from the exact cutoff point.";
+async function createCompleteMessage(claude, params, { maxContinuations = DEFAULT_MAX_CONTINUATIONS, timeoutMs, signal } = {}) {
+  let fullText = "";
+  let usage = ZERO_USAGE;
+  const requestOptions = timeoutMs !== void 0 || signal !== void 0 ? { timeout: timeoutMs, signal } : void 0;
+  for (let attempt = 0; attempt <= maxContinuations; attempt++) {
+    const messages = fullText ? [
+      ...params.messages,
+      { role: "assistant", content: fullText },
+      { role: "user", content: CONTINUATION_USER_MESSAGE }
+    ] : params.messages;
+    const message = requestOptions ? await claude.messages.create({ ...params, messages }, requestOptions) : await claude.messages.create({ ...params, messages });
+    const text = message.content.filter((block) => block.type === "text").map((block) => block.text).join("");
+    fullText += text;
+    usage = addTokenUsage(usage, {
+      inputTokens: message.usage?.input_tokens ?? 0,
+      outputTokens: message.usage?.output_tokens ?? 0
+    });
+    if (message.stop_reason !== "max_tokens") {
+      return { text: fullText, usage };
+    }
+  }
+  throw new Error(`Claude response still hit max_tokens after ${maxContinuations} continuation attempts \u2014 refusing to return truncated content.`);
+}
+
+// ../../modules/core/dist/modelRegistry.js
+var MODEL_REGISTRY = {
+  fast: {
+    description: "Quick, cheap work where depth matters least.",
+    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5" }]
+  },
+  balanced: {
+    description: "The everyday tier: chat, log entries, release notes, the daily digest. Frequent enough that cost matters.",
+    models: [{ id: "claude-sonnet-5", label: "Sonnet 5" }]
+  },
+  capable: {
+    description: "Deeper reasoning for infrequent, high-value work where getting it right outweighs the cost.",
+    models: [{ id: "claude-opus-5", label: "Opus 5" }]
+  },
+  max: {
+    description: "Maximum depth, for long-running agentic work. Opt-in \u2014 the most expensive tier.",
+    models: [{ id: "claude-fable-5", label: "Fable 5" }]
+  }
+};
+function defaultModelFor(tier) {
+  const [current] = MODEL_REGISTRY[tier].models;
+  if (!current) {
+    throw new Error(`Model tier "${tier}" has no models registered`);
+  }
+  return current.id;
+}
+
+// ../../modules/devlore/dist/decisionEntries.js
+function decisionEntriesDir(projectName) {
+  return `projects/${projectName}/decisions`;
+}
+async function listDecisionEntries(octokit, { owner, repo, projectName }) {
+  const dir = decisionEntriesDir(projectName);
+  let files;
+  try {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: dir });
+    if (!Array.isArray(data)) {
+      return [];
+    }
+    files = data;
+  } catch (error) {
+    if (isNotFound(error)) {
+      return [];
+    }
+    throw error;
+  }
+  const entries = await Promise.all(files.filter((file) => file.type === "file").map(async (file) => {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: file.path });
+    if (Array.isArray(data) || data.type !== "file") {
+      return null;
+    }
+    return { path: file.path, content: Buffer.from(data.content, "base64").toString("utf-8") };
+  }));
+  return entries.filter((entry) => entry !== null).sort((a, b) => a.path.localeCompare(b.path));
+}
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/prompt.js
+function buildOnboardingGuidePrompt(input) {
+  return [
+    `Project: ${input.projectName}`,
+    "",
+    'Write a "start here" guide for a developer joining this project. Not an end-user manual, and not a changelog \u2014 an orientation for someone about to read and change the code.',
+    "",
+    input.currentState ? `--- Current state ---
+${input.currentState}` : "",
+    input.masterDocs ? `--- Master docs ---
+${input.masterDocs}` : "",
+    input.decisions.length > 0 ? `--- Decisions ---
+${input.decisions.join("\n\n")}` : "",
+    "",
+    "Cover, in whatever order serves a newcomer best:",
+    "",
+    "- Where the important logic lives, and what to read first.",
+    "- Why the significant past decisions were made \u2014 a newcomer who does not know the reasoning will undo it.",
+    "- Common gotchas: the things that look wrong but are deliberate, and the mistakes this codebase has actually made before.",
+    "- How to get from a clean checkout to a working change.",
+    "",
+    "Draw only on what the documents above actually say. Where they do not cover something a newcomer would need, say so plainly rather than inventing a plausible answer \u2014 this guide is read by someone with no way to tell the difference.",
+    "",
+    "Return the guide only \u2014 no preamble, no meta-commentary."
+  ].filter((line) => line !== "").join("\n");
+}
+
+// ../../modules/devlore/dist/redact.js
+var REDACTED = "[REDACTED]";
+var KNOWN_SECRET_PATTERNS = [
+  /-----BEGIN [A-Z ]*PRIVATE KEY-----[\s\S]*?-----END [A-Z ]*PRIVATE KEY-----/g,
+  /gh[pousr]_[A-Za-z0-9]{36,}/g,
+  /github_pat_[A-Za-z0-9_]{20,}/g,
+  /sk-ant-[A-Za-z0-9_-]{20,}/g,
+  /sk-[A-Za-z0-9]{20,}/g,
+  /AKIA[0-9A-Z]{16}/g,
+  /xox[baprs]-[A-Za-z0-9-]{10,}/g,
+  /eyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}/g
+];
+var SECRET_KEYWORD = "(?:API[_-]?KEY|SECRET|TOKEN|PASSWORD|PASSWD|PRIVATE[_-]?KEY|CREDENTIAL)";
+var ASSIGNMENT_PATTERN = new RegExp(`((?:[A-Za-z0-9]+[_-])*${SECRET_KEYWORD}(?:[_-][A-Za-z0-9]+)*\\s*[:=]\\s*)(["']?)([^"'\`\\s]+)\\2`, "gi");
+function redactText(text) {
+  let result = text;
+  for (const pattern of KNOWN_SECRET_PATTERNS) {
+    result = result.replace(pattern, REDACTED);
+  }
+  result = result.replace(ASSIGNMENT_PATTERN, (_match, prefix, quote) => `${prefix}${quote}${REDACTED}${quote}`);
+  return result;
+}
+
+// ../../modules/devlore/dist/ciUsage.js
+var EMPTY_PROJECT_USAGE = {
+  draftLogEntry: ZERO_USAGE,
+  consolidateRelease: ZERO_USAGE,
+  syncUserManual: ZERO_USAGE,
+  syncTestPlan: ZERO_USAGE,
+  syncVisualizer: ZERO_USAGE,
+  analyzeCodebase: ZERO_USAGE,
+  syncOnboarding: ZERO_USAGE,
+  releaseNotes: ZERO_USAGE,
+  rollover: ZERO_ROLLOVER_USAGE
+};
+function usagePath(projectName) {
+  return `projects/${projectName}/usage.json`;
+}
+async function getUsageFile(octokit, { owner, repo, projectName }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({
+      owner,
+      repo,
+      path: usagePath(projectName)
+    });
+    if (Array.isArray(data) || data.type !== "file") {
+      return { usage: EMPTY_PROJECT_USAGE };
+    }
+    const parsed = JSON.parse(Buffer.from(data.content, "base64").toString("utf-8"));
+    const usage = { ...EMPTY_PROJECT_USAGE, ...parsed };
+    return { usage, sha: data.sha };
+  } catch (error) {
+    if (isNotFound2(error)) {
+      return { usage: EMPTY_PROJECT_USAGE };
+    }
+    throw error;
+  }
+}
+function addUsage(current, source, delta, now = /* @__PURE__ */ new Date()) {
+  return {
+    ...current,
+    [source]: addTokenUsage(current[source], delta),
+    rollover: addRolloverUsage(current.rollover, delta, now)
+  };
+}
+async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */ new Date()) {
+  const { owner, repo, projectName, branch } = params;
+  await retryOnConflict(async () => {
+    const { usage: current, sha } = await getUsageFile(octokit, { owner, repo, projectName });
+    const updated = addUsage(current, source, delta, now);
+    await octokit.rest.repos.createOrUpdateFileContents({
+      owner,
+      repo,
+      path: usagePath(projectName),
+      message: `Record ${source} token usage: ${projectName}`,
+      content: Buffer.from(JSON.stringify(updated, null, 2), "utf-8").toString("base64"),
+      branch,
+      sha
+    });
+  });
+}
+function isNotFound2(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/masterDocs.js
+function masterDocsPath(projectName) {
+  return `projects/${projectName}/master/README.md`;
+}
+async function getMasterDocs(octokit, params) {
+  return (await getMasterDocsFile(octokit, params)).content;
+}
+async function getMasterDocsFile(octokit, { owner, repo, projectName }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({
+      owner,
+      repo,
+      path: masterDocsPath(projectName)
+    });
+    if (Array.isArray(data) || data.type !== "file") {
+      return { content: "" };
+    }
+    return { content: Buffer.from(data.content, "base64").toString("utf-8"), sha: data.sha };
+  } catch (error) {
+    if (isNotFound3(error)) {
+      return { content: "" };
+    }
+    throw error;
+  }
+}
+function isNotFound3(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/codebaseSnapshot.js
+function currentStatePath(projectName) {
+  return `projects/${projectName}/current-state.md`;
+}
+
+// ../../modules/devlore/dist/onboardingDoc.js
+var ONBOARDING_PATH = "docs/ONBOARDING.md";
+var BANNER_BLOCKQUOTE_PATTERN = /^> \*\*Do not move.*$\n?/m;
+function onboardingBanner() {
+  return "> **Do not move, rename, or edit this file.** Devkeep generates and maintains this onboarding guide automatically at each release \u2014 manual edits will be overwritten the next time a release is tagged.";
+}
+function stripOnboardingMeta(content) {
+  return content.replace(BANNER_BLOCKQUOTE_PATTERN, "").trim();
+}
+async function getExistingOnboarding(octokit, { owner, repo }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({ owner, repo, path: ONBOARDING_PATH });
+    if (Array.isArray(data) || data.type !== "file") {
+      return null;
+    }
+    return { content: Buffer.from(data.content, "base64").toString("utf-8"), sha: data.sha };
+  } catch (error) {
+    if (isNotFound4(error)) {
+      return null;
+    }
+    throw error;
+  }
+}
+function onboardingVaultPath(projectName) {
+  return `projects/${projectName}/onboarding.md`;
+}
+async function getVaultOnboarding(octokit, { owner, repo, projectName }) {
+  try {
+    const { data } = await octokit.rest.repos.getContent({
+      owner,
+      repo,
+      path: onboardingVaultPath(projectName)
+    });
+    if (Array.isArray(data) || data.type !== "file") {
+      return { content: "" };
+    }
+    return { content: Buffer.from(data.content, "base64").toString("utf-8"), sha: data.sha };
+  } catch (error) {
+    if (isNotFound4(error)) {
+      return { content: "" };
+    }
+    throw error;
+  }
+}
+function isNotFound4(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../modules/devlore/dist/actions/syncOnboarding.js
+var MODEL_TIER = "balanced";
+var MAX_TOKENS = 2e4;
+var MAX_CONTINUATIONS = 8;
+var VAULT_BRANCH = "main";
+async function readVaultFile(octokit, owner, repo, path) {
+  const { data } = await octokit.rest.repos.getContent({ owner, repo, path }).catch(() => ({ data: null }));
+  return data && !Array.isArray(data) && data.type === "file" ? Buffer.from(data.content, "base64").toString("utf-8") : "";
+}
+async function syncOnboarding({ projectOctokit, vaultOctokit, claude, projectOwner, projectRepoName, vaultOwner, vaultRepoName, projectName }) {
+  const [currentState, masterDocs, entries] = await Promise.all([
+    readVaultFile(vaultOctokit, vaultOwner, vaultRepoName, currentStatePath(projectName)),
+    getMasterDocs(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName }).catch(() => ""),
+    listDecisionEntries(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName }).catch(() => [])
+  ]);
+  const prompt = buildOnboardingGuidePrompt({
+    projectName,
+    currentState: redactText(currentState),
+    masterDocs: redactText(masterDocs),
+    decisions: entries.map((entry) => redactText(entry.content))
+  });
+  const { text, usage } = await createCompleteMessage(claude, { model: defaultModelFor(MODEL_TIER), max_tokens: MAX_TOKENS, messages: [{ role: "user", content: prompt }] }, { maxContinuations: MAX_CONTINUATIONS });
+  const content = `${onboardingBanner()}
+
+${text.trim()}
+`;
+  const existing = await getExistingOnboarding(projectOctokit, { owner: projectOwner, repo: projectRepoName });
+  await projectOctokit.rest.repos.createOrUpdateFileContents({
+    owner: projectOwner,
+    repo: projectRepoName,
+    path: ONBOARDING_PATH,
+    message: existing ? "Update onboarding guide" : "Add onboarding guide",
+    content: Buffer.from(content, "utf-8").toString("base64"),
+    sha: existing?.sha
+  });
+  const vaultPath = onboardingVaultPath(projectName);
+  const mirrored = stripOnboardingMeta(content);
+  const existingVault = await getVaultOnboarding(vaultOctokit, {
+    owner: vaultOwner,
+    repo: vaultRepoName,
+    projectName
+  });
+  if (existingVault.content !== mirrored) {
+    await vaultOctokit.rest.repos.createOrUpdateFileContents({
+      owner: vaultOwner,
+      repo: vaultRepoName,
+      path: vaultPath,
+      message: `Mirror onboarding guide: ${projectName}`,
+      content: Buffer.from(mirrored, "utf-8").toString("base64"),
+      branch: VAULT_BRANCH,
+      sha: existingVault.sha
+    });
+  }
+  if (usage.inputTokens > 0 || usage.outputTokens > 0) {
+    await recordUsage(vaultOctokit, { owner: vaultOwner, repo: vaultRepoName, projectName, branch: VAULT_BRANCH }, "syncOnboarding", usage);
+  }
+  return { path: ONBOARDING_PATH, vaultPath, content, usage };
+}
+
+// ../../modules/devlore/dist/bin/syncOnboardingCli.js
+function requireEnv(env, name) {
+  const value = env[name];
+  if (!value) {
+    throw new Error(`${name} is not set`);
+  }
+  return value;
+}
+var defaultDeps = {
+  env: process.env,
+  syncOnboarding,
+  createGithubClient,
+  createClaudeClient,
+  log: console.log
+};
+async function main(deps = defaultDeps) {
+  const { env } = deps;
+  const projectName = requireEnv(env, "PROJECT_NAME");
+  const [projectOwner, projectRepoName] = requireEnv(env, "PROJECT_REPO").split("/");
+  const [vaultOwner, vaultRepoName] = requireEnv(env, "VAULT_REPO").split("/");
+  const octokit = deps.createGithubClient(requireEnv(env, "DEVKEEP_GITHUB_TOKEN"));
+  const claude = deps.createClaudeClient(requireEnv(env, "ANTHROPIC_API_KEY"));
+  const result = await deps.syncOnboarding({
+    projectOctokit: octokit,
+    vaultOctokit: octokit,
+    claude,
+    projectOwner,
+    projectRepoName,
+    vaultOwner,
+    vaultRepoName,
+    projectName
+  });
+  deps.log(`Synced onboarding guide: ${result.path} (mirrored to ${result.vaultPath})`);
+}
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().catch((error) => {
+    console.error(error);
+    process.exit(1);
+  });
+}
+export {
+  main,
+  requireEnv
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@starterculture/devkeep-actions",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Devkeep's GitHub Actions entrypoints, bundled for CI runners.",
   "license": "UNLICENSED",
   "type": "module",