@starterculture/devkeep-actions 0.5.1 → 0.5.2

package/dist/consolidate-release.js

@@ -25,9 +25,41 @@ async function retryOnConflict(attempt, maxAttempts = 3) {
 }
 
 // ../../modules/core/dist/tokenUsage.js
+function usageForModel(model, tokens) {
+  return { ...tokens, byModel: { [model]: tokens } };
+}
 var ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
 function addTokenUsage(a, b) {
-  return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+  const cacheReadTokens = (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0);
+  const cacheWriteTokens = (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0);
+  const byModel = mergeByModel(a.byModel, b.byModel);
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    // Kept absent rather than zero when nothing was cached, so a ledger
+    // entry from before caching and one from a run that cached nothing
+    // look the same.
+    ...cacheReadTokens > 0 ? { cacheReadTokens } : {},
+    ...cacheWriteTokens > 0 ? { cacheWriteTokens } : {},
+    // Absent for the same reason: a record with no model attribution and
+    // one with an empty map should not read differently.
+    ...byModel ? { byModel } : {}
+  };
+}
+function mergeByModel(a, b) {
+  if (!a && !b)
+    return void 0;
+  const merged = { ...a };
+  for (const [model, tokens] of Object.entries(b ?? {})) {
+    const existing = merged[model];
+    merged[model] = existing ? {
+      inputTokens: existing.inputTokens + tokens.inputTokens,
+      outputTokens: existing.outputTokens + tokens.outputTokens,
+      ...(existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) > 0 ? { cacheReadTokens: (existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) } : {},
+      ...(existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) > 0 ? { cacheWriteTokens: (existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) } : {}
+    } : tokens;
+  }
+  return merged;
 }
 
 // ../../modules/core/dist/rollover.js
@@ -89,10 +121,10 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
     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, {
+    usage = addTokenUsage(usage, usageForModel(params.model, {
       inputTokens: message.usage?.input_tokens ?? 0,
       outputTokens: message.usage?.output_tokens ?? 0
-    });
+    }));
     if (message.stop_reason !== "max_tokens") {
       return { text: fullText, usage };
     }
@@ -104,19 +136,19 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
 var MODEL_REGISTRY = {
   fast: {
     description: "Quick, cheap work where depth matters least.",
-    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5" }]
+    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5", contextTokens: 2e5 }]
   },
   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" }]
+    models: [{ id: "claude-sonnet-5", label: "Sonnet 5", contextTokens: 2e5 }]
   },
   capable: {
     description: "Deeper reasoning for infrequent, high-value work where getting it right outweighs the cost.",
-    models: [{ id: "claude-opus-5", label: "Opus 5" }]
+    models: [{ id: "claude-opus-5", label: "Opus 5", contextTokens: 2e5 }]
   },
   max: {
     description: "Maximum depth, for long-running agentic work. Opt-in \u2014 the most expensive tier.",
-    models: [{ id: "claude-fable-5", label: "Fable 5" }]
+    models: [{ id: "claude-fable-5", label: "Fable 5", contextTokens: 2e5 }]
   }
 };
 function defaultModelFor(tier) {
@@ -280,7 +312,7 @@ async function runCiEntrypoint(source, main2, deps = defaultDeps) {
   }
 }
 
-// ../../modules/devlore/dist/ciUsage.js
+// ../../modules/core/dist/ciUsage.js
 var EMPTY_PROJECT_USAGE = {
   draftLogEntry: ZERO_USAGE,
   consolidateRelease: ZERO_USAGE,
@@ -291,6 +323,7 @@ var EMPTY_PROJECT_USAGE = {
   syncOnboarding: ZERO_USAGE,
   releaseNotes: ZERO_USAGE,
   captureBaseline: ZERO_USAGE,
+  devseerReview: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {
@@ -317,14 +350,24 @@ async function getUsageFile(octokit, { owner, repo, projectName }) {
   }
 }
 function addUsage(current, source, delta, now = /* @__PURE__ */ new Date()) {
+  const bySource = current.rolloverBySource ?? {};
   return {
     ...current,
     [source]: addTokenUsage(current[source], delta),
-    rollover: addRolloverUsage(current.rollover, delta, now)
+    // Both: the combined bucket stays the total it always was, and the
+    // per-source split is what lets the dashboard attribute it.
+    rollover: addRolloverUsage(current.rollover, delta, now),
+    rolloverBySource: {
+      ...bySource,
+      [source]: addRolloverUsage(bySource[source] ?? ZERO_ROLLOVER_USAGE, delta, now)
+    }
   };
 }
 async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */ new Date()) {
   const { owner, repo, projectName, branch } = params;
+  if (delta.inputTokens === 0 && delta.outputTokens === 0) {
+    return;
+  }
   await retryOnConflict(async () => {
     const { usage: current, sha } = await getUsageFile(octokit, { owner, repo, projectName });
     const updated = addUsage(current, source, delta, now);
@@ -376,6 +419,14 @@ function isNotFound2(error) {
 }
 
 // ../../modules/devlore/dist/prompt.js
+var SUPERSEDED_GUIDANCE = [
+  "These documents record how the thinking changed over time, so they contain claims that were later corrected, and the corrected version is still physically present.",
+  "**A correction outranks what it corrects.** Where two passages disagree, the later-dated one is what is true now. A passage struck through, marked superseded, described as decided against, or sitting under a heading that says the earlier view was wrong, records what was believed \u2014 never what is. Do not restate any of it as current."
+].join("\n");
+var SUPERSEDED_GUIDANCE_WITH_LESSONS = [
+  SUPERSEDED_GUIDANCE,
+  "A reversed decision is still worth telling a newcomer about \u2014 but as something the project learned, never as a rule they should follow. Say what is true now first, and mention the earlier version only where the fact that it changed is itself the lesson."
+].join("\n");
 function buildConsolidationPrompt(input) {
   const entriesText = input.logEntries.map((entry) => `--- ${entry.path} ---
 ${entry.content}`).join("\n\n");

package/dist/crypting-candidates-scan.js

@@ -499,7 +499,12 @@ async function main(deps = defaultDeps2) {
   const headSha = requireEnv(env, "HEAD_SHA");
   const projectOctokit = deps.createGithubClient(requireEnv(env, "GITHUB_TOKEN"));
   const vaultOctokit = deps.createGithubClient(requireEnv(env, "DEVKEEP_GITHUB_TOKEN"));
-  const blindIndexKey = Buffer.from(requireEnv(env, "DEVCRYPT_BLIND_INDEX_KEY"), "base64");
+  const rawKey = env.DEVCRYPT_BLIND_INDEX_KEY;
+  if (!rawKey) {
+    deps.log("No DEVCRYPT_BLIND_INDEX_KEY for this project \u2014 Devcrypt has not been used against this vault, so there is nothing to scan for. Re-link once it has been.");
+    return;
+  }
+  const blindIndexKey = Buffer.from(rawKey, "base64");
   const result = await deps.scanCryptingCandidates({
     projectOctokit,
     vaultOctokit,

package/dist/draft-log-entry.js

@@ -25,9 +25,41 @@ async function retryOnConflict(attempt, maxAttempts = 3) {
 }
 
 // ../../modules/core/dist/tokenUsage.js
+function usageForModel(model, tokens) {
+  return { ...tokens, byModel: { [model]: tokens } };
+}
 var ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
 function addTokenUsage(a, b) {
-  return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+  const cacheReadTokens = (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0);
+  const cacheWriteTokens = (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0);
+  const byModel = mergeByModel(a.byModel, b.byModel);
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    // Kept absent rather than zero when nothing was cached, so a ledger
+    // entry from before caching and one from a run that cached nothing
+    // look the same.
+    ...cacheReadTokens > 0 ? { cacheReadTokens } : {},
+    ...cacheWriteTokens > 0 ? { cacheWriteTokens } : {},
+    // Absent for the same reason: a record with no model attribution and
+    // one with an empty map should not read differently.
+    ...byModel ? { byModel } : {}
+  };
+}
+function mergeByModel(a, b) {
+  if (!a && !b)
+    return void 0;
+  const merged = { ...a };
+  for (const [model, tokens] of Object.entries(b ?? {})) {
+    const existing = merged[model];
+    merged[model] = existing ? {
+      inputTokens: existing.inputTokens + tokens.inputTokens,
+      outputTokens: existing.outputTokens + tokens.outputTokens,
+      ...(existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) > 0 ? { cacheReadTokens: (existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) } : {},
+      ...(existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) > 0 ? { cacheWriteTokens: (existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) } : {}
+    } : tokens;
+  }
+  return merged;
 }
 
 // ../../modules/core/dist/rollover.js
@@ -89,10 +121,10 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
     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, {
+    usage = addTokenUsage(usage, usageForModel(params.model, {
       inputTokens: message.usage?.input_tokens ?? 0,
       outputTokens: message.usage?.output_tokens ?? 0
-    });
+    }));
     if (message.stop_reason !== "max_tokens") {
       return { text: fullText, usage };
     }
@@ -104,19 +136,19 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
 var MODEL_REGISTRY = {
   fast: {
     description: "Quick, cheap work where depth matters least.",
-    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5" }]
+    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5", contextTokens: 2e5 }]
   },
   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" }]
+    models: [{ id: "claude-sonnet-5", label: "Sonnet 5", contextTokens: 2e5 }]
   },
   capable: {
     description: "Deeper reasoning for infrequent, high-value work where getting it right outweighs the cost.",
-    models: [{ id: "claude-opus-5", label: "Opus 5" }]
+    models: [{ id: "claude-opus-5", label: "Opus 5", contextTokens: 2e5 }]
   },
   max: {
     description: "Maximum depth, for long-running agentic work. Opt-in \u2014 the most expensive tier.",
-    models: [{ id: "claude-fable-5", label: "Fable 5" }]
+    models: [{ id: "claude-fable-5", label: "Fable 5", contextTokens: 2e5 }]
   }
 };
 function defaultModelFor(tier) {
@@ -280,7 +312,7 @@ async function runCiEntrypoint(source, main2, deps = defaultDeps) {
   }
 }
 
-// ../../modules/devlore/dist/ciUsage.js
+// ../../modules/core/dist/ciUsage.js
 var EMPTY_PROJECT_USAGE = {
   draftLogEntry: ZERO_USAGE,
   consolidateRelease: ZERO_USAGE,
@@ -291,6 +323,7 @@ var EMPTY_PROJECT_USAGE = {
   syncOnboarding: ZERO_USAGE,
   releaseNotes: ZERO_USAGE,
   captureBaseline: ZERO_USAGE,
+  devseerReview: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {
@@ -317,14 +350,24 @@ async function getUsageFile(octokit, { owner, repo, projectName }) {
   }
 }
 function addUsage(current, source, delta, now = /* @__PURE__ */ new Date()) {
+  const bySource = current.rolloverBySource ?? {};
   return {
     ...current,
     [source]: addTokenUsage(current[source], delta),
-    rollover: addRolloverUsage(current.rollover, delta, now)
+    // Both: the combined bucket stays the total it always was, and the
+    // per-source split is what lets the dashboard attribute it.
+    rollover: addRolloverUsage(current.rollover, delta, now),
+    rolloverBySource: {
+      ...bySource,
+      [source]: addRolloverUsage(bySource[source] ?? ZERO_ROLLOVER_USAGE, delta, now)
+    }
   };
 }
 async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */ new Date()) {
   const { owner, repo, projectName, branch } = params;
+  if (delta.inputTokens === 0 && delta.outputTokens === 0) {
+    return;
+  }
   await retryOnConflict(async () => {
     const { usage: current, sha } = await getUsageFile(octokit, { owner, repo, projectName });
     const updated = addUsage(current, source, delta, now);
@@ -503,6 +546,14 @@ function isNotFound3(error) {
 
 // ../../modules/devlore/dist/prompt.js
 var MAX_DIFF_CHARS = 2e4;
+var SUPERSEDED_GUIDANCE = [
+  "These documents record how the thinking changed over time, so they contain claims that were later corrected, and the corrected version is still physically present.",
+  "**A correction outranks what it corrects.** Where two passages disagree, the later-dated one is what is true now. A passage struck through, marked superseded, described as decided against, or sitting under a heading that says the earlier view was wrong, records what was believed \u2014 never what is. Do not restate any of it as current."
+].join("\n");
+var SUPERSEDED_GUIDANCE_WITH_LESSONS = [
+  SUPERSEDED_GUIDANCE,
+  "A reversed decision is still worth telling a newcomer about \u2014 but as something the project learned, never as a rule they should follow. Say what is true now first, and mention the earlier version only where the fact that it changed is itself the lesson."
+].join("\n");
 function buildLogEntryPrompt(input) {
   const diffText = input.files.map((file) => `--- ${file.filename} (${file.status}) ---
 ${file.patch}`).join("\n\n");

package/dist/draft-release-notes.js

@@ -25,9 +25,41 @@ async function retryOnConflict(attempt, maxAttempts = 3) {
 }
 
 // ../../modules/core/dist/tokenUsage.js
+function usageForModel(model, tokens) {
+  return { ...tokens, byModel: { [model]: tokens } };
+}
 var ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
 function addTokenUsage(a, b) {
-  return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+  const cacheReadTokens = (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0);
+  const cacheWriteTokens = (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0);
+  const byModel = mergeByModel(a.byModel, b.byModel);
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    // Kept absent rather than zero when nothing was cached, so a ledger
+    // entry from before caching and one from a run that cached nothing
+    // look the same.
+    ...cacheReadTokens > 0 ? { cacheReadTokens } : {},
+    ...cacheWriteTokens > 0 ? { cacheWriteTokens } : {},
+    // Absent for the same reason: a record with no model attribution and
+    // one with an empty map should not read differently.
+    ...byModel ? { byModel } : {}
+  };
+}
+function mergeByModel(a, b) {
+  if (!a && !b)
+    return void 0;
+  const merged = { ...a };
+  for (const [model, tokens] of Object.entries(b ?? {})) {
+    const existing = merged[model];
+    merged[model] = existing ? {
+      inputTokens: existing.inputTokens + tokens.inputTokens,
+      outputTokens: existing.outputTokens + tokens.outputTokens,
+      ...(existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) > 0 ? { cacheReadTokens: (existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) } : {},
+      ...(existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) > 0 ? { cacheWriteTokens: (existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) } : {}
+    } : tokens;
+  }
+  return merged;
 }
 
 // ../../modules/core/dist/rollover.js
@@ -89,10 +121,10 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
     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, {
+    usage = addTokenUsage(usage, usageForModel(params.model, {
       inputTokens: message.usage?.input_tokens ?? 0,
       outputTokens: message.usage?.output_tokens ?? 0
-    });
+    }));
     if (message.stop_reason !== "max_tokens") {
       return { text: fullText, usage };
     }
@@ -104,19 +136,19 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
 var MODEL_REGISTRY = {
   fast: {
     description: "Quick, cheap work where depth matters least.",
-    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5" }]
+    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5", contextTokens: 2e5 }]
   },
   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" }]
+    models: [{ id: "claude-sonnet-5", label: "Sonnet 5", contextTokens: 2e5 }]
   },
   capable: {
     description: "Deeper reasoning for infrequent, high-value work where getting it right outweighs the cost.",
-    models: [{ id: "claude-opus-5", label: "Opus 5" }]
+    models: [{ id: "claude-opus-5", label: "Opus 5", contextTokens: 2e5 }]
   },
   max: {
     description: "Maximum depth, for long-running agentic work. Opt-in \u2014 the most expensive tier.",
-    models: [{ id: "claude-fable-5", label: "Fable 5" }]
+    models: [{ id: "claude-fable-5", label: "Fable 5", contextTokens: 2e5 }]
   }
 };
 function defaultModelFor(tier) {
@@ -280,30 +312,7 @@ async function runCiEntrypoint(source, main2, deps = defaultDeps) {
   }
 }
 
-// ../../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/ciUsage.js
+// ../../modules/core/dist/ciUsage.js
 var EMPTY_PROJECT_USAGE = {
   draftLogEntry: ZERO_USAGE,
   consolidateRelease: ZERO_USAGE,
@@ -314,6 +323,7 @@ var EMPTY_PROJECT_USAGE = {
   syncOnboarding: ZERO_USAGE,
   releaseNotes: ZERO_USAGE,
   captureBaseline: ZERO_USAGE,
+  devseerReview: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {
@@ -340,14 +350,24 @@ async function getUsageFile(octokit, { owner, repo, projectName }) {
   }
 }
 function addUsage(current, source, delta, now = /* @__PURE__ */ new Date()) {
+  const bySource = current.rolloverBySource ?? {};
   return {
     ...current,
     [source]: addTokenUsage(current[source], delta),
-    rollover: addRolloverUsage(current.rollover, delta, now)
+    // Both: the combined bucket stays the total it always was, and the
+    // per-source split is what lets the dashboard attribute it.
+    rollover: addRolloverUsage(current.rollover, delta, now),
+    rolloverBySource: {
+      ...bySource,
+      [source]: addRolloverUsage(bySource[source] ?? ZERO_ROLLOVER_USAGE, delta, now)
+    }
   };
 }
 async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */ new Date()) {
   const { owner, repo, projectName, branch } = params;
+  if (delta.inputTokens === 0 && delta.outputTokens === 0) {
+    return;
+  }
   await retryOnConflict(async () => {
     const { usage: current, sha } = await getUsageFile(octokit, { owner, repo, projectName });
     const updated = addUsage(current, source, delta, now);
@@ -366,6 +386,37 @@ function isNotFound(error) {
   return typeof error === "object" && error !== null && "status" in error && error.status === 404;
 }
 
+// ../../modules/devlore/dist/prompt.js
+var SUPERSEDED_GUIDANCE = [
+  "These documents record how the thinking changed over time, so they contain claims that were later corrected, and the corrected version is still physically present.",
+  "**A correction outranks what it corrects.** Where two passages disagree, the later-dated one is what is true now. A passage struck through, marked superseded, described as decided against, or sitting under a heading that says the earlier view was wrong, records what was believed \u2014 never what is. Do not restate any of it as current."
+].join("\n");
+var SUPERSEDED_GUIDANCE_WITH_LESSONS = [
+  SUPERSEDED_GUIDANCE,
+  "A reversed decision is still worth telling a newcomer about \u2014 but as something the project learned, never as a rule they should follow. Say what is true now first, and mention the earlier version only where the fact that it changed is itself the lesson."
+].join("\n");
+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/logEntries.js
 function logEntriesDir(projectName) {
   return `projects/${projectName}/log`;

package/dist/sync-onboarding.js

@@ -25,9 +25,41 @@ async function retryOnConflict(attempt, maxAttempts = 3) {
 }
 
 // ../../modules/core/dist/tokenUsage.js
+function usageForModel(model, tokens) {
+  return { ...tokens, byModel: { [model]: tokens } };
+}
 var ZERO_USAGE = { inputTokens: 0, outputTokens: 0 };
 function addTokenUsage(a, b) {
-  return { inputTokens: a.inputTokens + b.inputTokens, outputTokens: a.outputTokens + b.outputTokens };
+  const cacheReadTokens = (a.cacheReadTokens ?? 0) + (b.cacheReadTokens ?? 0);
+  const cacheWriteTokens = (a.cacheWriteTokens ?? 0) + (b.cacheWriteTokens ?? 0);
+  const byModel = mergeByModel(a.byModel, b.byModel);
+  return {
+    inputTokens: a.inputTokens + b.inputTokens,
+    outputTokens: a.outputTokens + b.outputTokens,
+    // Kept absent rather than zero when nothing was cached, so a ledger
+    // entry from before caching and one from a run that cached nothing
+    // look the same.
+    ...cacheReadTokens > 0 ? { cacheReadTokens } : {},
+    ...cacheWriteTokens > 0 ? { cacheWriteTokens } : {},
+    // Absent for the same reason: a record with no model attribution and
+    // one with an empty map should not read differently.
+    ...byModel ? { byModel } : {}
+  };
+}
+function mergeByModel(a, b) {
+  if (!a && !b)
+    return void 0;
+  const merged = { ...a };
+  for (const [model, tokens] of Object.entries(b ?? {})) {
+    const existing = merged[model];
+    merged[model] = existing ? {
+      inputTokens: existing.inputTokens + tokens.inputTokens,
+      outputTokens: existing.outputTokens + tokens.outputTokens,
+      ...(existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) > 0 ? { cacheReadTokens: (existing.cacheReadTokens ?? 0) + (tokens.cacheReadTokens ?? 0) } : {},
+      ...(existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) > 0 ? { cacheWriteTokens: (existing.cacheWriteTokens ?? 0) + (tokens.cacheWriteTokens ?? 0) } : {}
+    } : tokens;
+  }
+  return merged;
 }
 
 // ../../modules/core/dist/rollover.js
@@ -89,10 +121,10 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
     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, {
+    usage = addTokenUsage(usage, usageForModel(params.model, {
       inputTokens: message.usage?.input_tokens ?? 0,
       outputTokens: message.usage?.output_tokens ?? 0
-    });
+    }));
     if (message.stop_reason !== "max_tokens") {
       return { text: fullText, usage };
     }
@@ -104,19 +136,19 @@ async function createCompleteMessage(claude, params, { maxContinuations = DEFAUL
 var MODEL_REGISTRY = {
   fast: {
     description: "Quick, cheap work where depth matters least.",
-    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5" }]
+    models: [{ id: "claude-haiku-4-5-20251001", label: "Haiku 4.5", contextTokens: 2e5 }]
   },
   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" }]
+    models: [{ id: "claude-sonnet-5", label: "Sonnet 5", contextTokens: 2e5 }]
   },
   capable: {
     description: "Deeper reasoning for infrequent, high-value work where getting it right outweighs the cost.",
-    models: [{ id: "claude-opus-5", label: "Opus 5" }]
+    models: [{ id: "claude-opus-5", label: "Opus 5", contextTokens: 2e5 }]
   },
   max: {
     description: "Maximum depth, for long-running agentic work. Opt-in \u2014 the most expensive tier.",
-    models: [{ id: "claude-fable-5", label: "Fable 5" }]
+    models: [{ id: "claude-fable-5", label: "Fable 5", contextTokens: 2e5 }]
   }
 };
 function defaultModelFor(tier) {
@@ -280,66 +312,7 @@ async function runCiEntrypoint(source, main2, deps = defaultDeps) {
   }
 }
 
-// ../../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.canonicalDocs ? `--- Canonical docs ---
-${input.canonicalDocs}` : "",
-    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/ciUsage.js
+// ../../modules/core/dist/ciUsage.js
 var EMPTY_PROJECT_USAGE = {
   draftLogEntry: ZERO_USAGE,
   consolidateRelease: ZERO_USAGE,
@@ -350,6 +323,7 @@ var EMPTY_PROJECT_USAGE = {
   syncOnboarding: ZERO_USAGE,
   releaseNotes: ZERO_USAGE,
   captureBaseline: ZERO_USAGE,
+  devseerReview: ZERO_USAGE,
   rollover: ZERO_ROLLOVER_USAGE
 };
 function usagePath(projectName) {
@@ -369,21 +343,31 @@ async function getUsageFile(octokit, { owner, repo, projectName }) {
     const usage = { ...EMPTY_PROJECT_USAGE, ...parsed };
     return { usage, sha: data.sha };
   } catch (error) {
-    if (isNotFound2(error)) {
+    if (isNotFound(error)) {
       return { usage: EMPTY_PROJECT_USAGE };
     }
     throw error;
   }
 }
 function addUsage(current, source, delta, now = /* @__PURE__ */ new Date()) {
+  const bySource = current.rolloverBySource ?? {};
   return {
     ...current,
     [source]: addTokenUsage(current[source], delta),
-    rollover: addRolloverUsage(current.rollover, delta, now)
+    // Both: the combined bucket stays the total it always was, and the
+    // per-source split is what lets the dashboard attribute it.
+    rollover: addRolloverUsage(current.rollover, delta, now),
+    rolloverBySource: {
+      ...bySource,
+      [source]: addRolloverUsage(bySource[source] ?? ZERO_ROLLOVER_USAGE, delta, now)
+    }
   };
 }
 async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */ new Date()) {
   const { owner, repo, projectName, branch } = params;
+  if (delta.inputTokens === 0 && delta.outputTokens === 0) {
+    return;
+  }
   await retryOnConflict(async () => {
     const { usage: current, sha } = await getUsageFile(octokit, { owner, repo, projectName });
     const updated = addUsage(current, source, delta, now);
@@ -398,10 +382,78 @@ async function recordUsage(octokit, params, source, delta, now = /* @__PURE__ */
     });
   });
 }
+function isNotFound(error) {
+  return typeof error === "object" && error !== null && "status" in error && error.status === 404;
+}
+
+// ../../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 (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/prompt.js
+var SUPERSEDED_GUIDANCE = [
+  "These documents record how the thinking changed over time, so they contain claims that were later corrected, and the corrected version is still physically present.",
+  "**A correction outranks what it corrects.** Where two passages disagree, the later-dated one is what is true now. A passage struck through, marked superseded, described as decided against, or sitting under a heading that says the earlier view was wrong, records what was believed \u2014 never what is. Do not restate any of it as current."
+].join("\n");
+var SUPERSEDED_GUIDANCE_WITH_LESSONS = [
+  SUPERSEDED_GUIDANCE,
+  "A reversed decision is still worth telling a newcomer about \u2014 but as something the project learned, never as a rule they should follow. Say what is true now first, and mention the earlier version only where the fact that it changed is itself the lesson."
+].join("\n");
+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.canonicalDocs ? `--- Canonical docs ---
+${input.canonicalDocs}` : "",
+    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.",
+    SUPERSEDED_GUIDANCE_WITH_LESSONS,
+    "",
+    "Return the guide only \u2014 no preamble, no meta-commentary."
+  ].filter((line) => line !== "").join("\n");
+}
+
 // ../../modules/devlore/dist/canonicalDocs.js
 function canonicalDocsPath(projectName) {
   return `projects/${projectName}/canonical/README.md`;
@@ -511,11 +563,14 @@ async function syncOnboarding({ projectOctokit, vaultOctokit, claude, projectOwn
 ${text.trim()}
 `;
   const existing = await getExistingOnboarding(projectOctokit, { owner: projectOwner, repo: projectRepoName });
+  const releaseTag = releaseTagFromEnvironment();
+  const wrote = existing ? "Update" : "Add";
+  const message = releaseTag ? `${wrote} onboarding guide (release ${releaseTag})` : `${wrote} onboarding guide`;
   await projectOctokit.rest.repos.createOrUpdateFileContents({
     owner: projectOwner,
     repo: projectRepoName,
     path: ONBOARDING_PATH,
-    message: existing ? "Update onboarding guide" : "Add onboarding guide",
+    message,
     content: Buffer.from(content, "utf-8").toString("base64"),
     sha: existing?.sha
   });
@@ -531,7 +586,7 @@ ${text.trim()}
       owner: vaultOwner,
       repo: vaultRepoName,
       path: vaultPath,
-      message: `Mirror onboarding guide: ${projectName}`,
+      message: releaseTag ? `Mirror onboarding guide: ${projectName} (release ${releaseTag})` : `Mirror onboarding guide: ${projectName}`,
       content: Buffer.from(mirrored, "utf-8").toString("base64"),
       branch: VAULT_BRANCH2,
       sha: existingVault.sha
@@ -542,6 +597,12 @@ ${text.trim()}
   }
   return { path: ONBOARDING_PATH, vaultPath, content, usage };
 }
+function releaseTagFromEnvironment() {
+  if (process.env.GITHUB_REF_TYPE !== "tag")
+    return null;
+  const name = process.env.GITHUB_REF_NAME?.trim();
+  return name ? name : null;
+}
 
 // ../../modules/devlore/dist/bin/syncOnboardingCli.js
 function requireEnv(env, name) {

package/package.json

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