@przeprogramowani/10x-cli 1.26.5 → 1.27.0

package/README.md

@@ -173,6 +173,7 @@ remain visible. Full lesson downloads and other commands remain available below.
 | `10x list` | Browse modules and lessons in your course |
 | `10x get <ref>` | Fetch a lesson and apply artifacts to your workspace |
 | `10x sync` | Bulk-download / refresh lessons and report what changed upstream |
+| `10x changelog` | Show 10x-toolkit release notes since your last sync |
 | `10x doctor` | Diagnose auth, API connectivity, and local config |
 | `10x bench` | Live top-10 AI model leaderboard from [10xbench.ai](https://10xbench.ai) — no login needed |
 | `10x bench-kit <action>` | Create (`init`) and update (`update`) a company benchmark instance from the [10x-bench-kit](https://github.com/przeprogramowani/10x-bench-kit) template |
@@ -278,6 +279,44 @@ all for skills and prompts. Config templates are create-only. Course rules retai
 conflict is reported, not a failure), `1` if any lesson failed to fetch. The full
 report is still emitted on a partial failure.
 
+### `10x changelog`
+
+`10x changelog` shows the **10x-toolkit release notes** — which course skills,
+prompts, rules and config templates changed in each toolkit release — since your
+project's baseline. It describes toolkit releases, not your files: to see what a
+sync would actually download or update in this project, run `10x sync --dry-run`.
+It needs a login and never writes anything.
+
+The baseline is recorded per project: after a successful `10x sync` (not
+`--dry-run`, no failed lessons) or a full, unfiltered `10x get`, the CLI stores the newest
+toolkit release version in the project manifest (`toolkit.version`). If the
+backend cannot answer, nothing is recorded and the sync/get result is unchanged.
+Without a recorded version, `10x changelog` falls back to the date of the last
+lesson applied in the project; in a project with no manifest it shows the latest 5
+releases and suggests running `10x sync`.
+
+| Flag | Description |
+|------|-------------|
+| `--since <ref>` | Ignore the baseline: `vX.Y.Z` lists releases **after** that version; `YYYY-MM-DD` lists releases **from** the start of that UTC day |
+| `--limit <n>` | Maximum number of releases, 1-100 (default 20; 5 without a baseline) |
+
+```bash
+# What changed in the toolkit since this project's last sync
+10x changelog
+
+# Browse history regardless of the baseline
+10x changelog --since v2.55.0
+10x changelog --since 2026-10-01 --limit 50
+```
+
+Releases are listed newest first as `vX.Y.Z — <date>` followed by their notes, or
+`No toolkit changes since <baseline>.` Exit code is `0` whether or not there are
+new releases; an invalid `--since`/`--limit` exits `2`, a missing login `3`. Against
+a backend that does not serve the changelog yet the command fails with
+`changelog_unsupported` (exit `1`); `get` and `sync` keep working. JSON output
+(`--json` or piped) is `{ baseline: { source, version?, date? }, newEntries,
+entries }`, where `source` is `flag`, `sync`, `applied` or `none`.
+
 ### `10x bench`
 
 Shows the [10xBench](https://10xbench.ai) leaderboard — the top 10 AI models

package/dist/index.mjs

@@ -3183,7 +3183,7 @@ var cac = (name = "") => new CAC(name);
 // package.json
 var package_default = {
   name: "@przeprogramowani/10x-cli",
-  version: "1.26.5",
+  version: "1.27.0",
   description: "Open-source CLI for 10xDevs course content",
   repository: {
     type: "git",
@@ -3402,6 +3402,7 @@ var ERROR_CODE_MESSAGES = {
   module_locked: "This module is not available yet.",
   signing_failed: "Could not sign the download URL. Try again in a moment.",
   invalid_json: "The server received a malformed request.",
+  changelog_unsupported: "The backend does not support the toolkit changelog yet.",
   unauthorized: "You are not signed in. Run `10x auth` first.",
   no_membership: "No active course membership was found for this email.",
   invalid_refresh_token: "Your session has expired. Run `10x auth` again.",
@@ -3922,6 +3923,60 @@ async function fetchCourses(token) {
     return { ok: false, status: 0, code: "discovery_invalid", error: "Invalid course discovery response; no course was selected." };
   return result;
 }
+var CHANGELOG_STATUSES = ["added", "modified", "removed", "renamed"];
+var CHANGELOG_ARTIFACT_KINDS = ["skills", "prompts", "rules", "configTemplates"];
+function isChangelogEntry(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const e2 = value;
+  if (e2["schemaVersion"] !== undefined && typeof e2["schemaVersion"] !== "number")
+    return false;
+  if (typeof e2["version"] !== "string" || !e2["version"])
+    return false;
+  if (e2["previousVersion"] !== null && typeof e2["previousVersion"] !== "string")
+    return false;
+  if (typeof e2["releasedAt"] !== "string" || typeof e2["markdown"] !== "string")
+    return false;
+  if (e2["model"] !== null && typeof e2["model"] !== "string")
+    return false;
+  const artifacts = e2["artifacts"];
+  if (!artifacts || typeof artifacts !== "object" || Array.isArray(artifacts))
+    return false;
+  return CHANGELOG_ARTIFACT_KINDS.every((kind) => {
+    const list = artifacts[kind];
+    return Array.isArray(list) && list.every((item) => {
+      if (!item || typeof item !== "object")
+        return false;
+      const change = item;
+      return typeof change["name"] === "string" && typeof change["status"] === "string" && CHANGELOG_STATUSES.includes(change["status"]);
+    });
+  });
+}
+function validateChangelogResponse(value) {
+  if (!value || typeof value !== "object")
+    return false;
+  const entries = value["entries"];
+  return Array.isArray(entries) && entries.every(isChangelogEntry);
+}
+async function fetchChangelog(token, query = {}) {
+  const params = new URLSearchParams;
+  if (query.since !== undefined)
+    params.set("since", query.since);
+  if (query.sinceDate !== undefined)
+    params.set("sinceDate", query.sinceDate);
+  if (query.limit !== undefined)
+    params.set("limit", String(query.limit));
+  const qs = params.toString();
+  const result = await apiGet(`/api/changelog${qs ? `?${qs}` : ""}`, { token });
+  if (!result.ok) {
+    if (result.status === 404)
+      return { ...result, code: "changelog_unsupported", error: "The backend does not support the toolkit changelog yet." };
+    return result;
+  }
+  if (!validateChangelogResponse(result.data))
+    return { ok: false, status: 0, code: "changelog_invalid", error: "Invalid toolkit changelog response." };
+  return result;
+}
 function catalogRelease(catalog) {
   if (catalog.course !== "10xdevs4")
     return;
@@ -4953,8 +5008,24 @@ function readManifest(dir) {
   }
   if (!isManifest(parsed))
     return null;
+  if (parsed.toolkit !== undefined && !isToolkitBaseline(parsed.toolkit))
+    delete parsed.toolkit;
   return parsed;
 }
+function isToolkitBaseline(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return false;
+  const v3 = value;
+  return typeof v3["version"] === "string" && v3["version"].length > 0 && typeof v3["recordedAt"] === "string";
+}
+function recordToolkitVersion(dir, version, now) {
+  const manifest = readManifest(dir);
+  if (!manifest)
+    return false;
+  manifest.toolkit = { version, recordedAt: now.toISOString() };
+  writeManifest(dir, manifest);
+  return true;
+}
 function writeManifest(dir, manifest) {
   assertProjectFilePath(dirname2(dir), join3(dir, MANIFEST_FILENAME));
   assertProjectFilePath(dirname2(dir), join3(dir, `${MANIFEST_FILENAME}.tmp`));
@@ -5682,9 +5753,164 @@ var defaultDeps = {
   now: () => new Date
 };
 
+// src/commands/changelog.ts
+import { join as join6 } from "node:path";
+var DEFAULT_CHANGELOG_LIMIT = 20;
+var NO_BASELINE_LIMIT = 5;
+var MAX_LIMIT = 100;
+var VERSION_RE = /^v\d+\.\d+\.\d+$/;
+var DATE_RE = /^(\d{4})-(\d{2})-(\d{2})$/;
+function registerChangelogCommand(cli) {
+  cli.command("changelog", "Show 10x-toolkit changes since your last sync").option("--since <ref>", "Show changes after a version (vX.Y.Z) or from a date (YYYY-MM-DD)").option("--limit <n>", `Maximum number of entries, 1-${MAX_LIMIT} (default: ${DEFAULT_CHANGELOG_LIMIT})`).action(async (options) => {
+    const ctx = resolveContext(options);
+    await runChangelog(ctx, options);
+  });
+}
+async function runChangelog(ctx, options) {
+  const flagBaseline = options.since === undefined ? null : parseSinceFlag(ctx, options.since);
+  const explicitLimit = options.limit === undefined ? undefined : parseLimitFlag(ctx, options.limit);
+  const auth = await requireAuth(ctx);
+  const baseline = flagBaseline ?? resolveManifestBaseline(ctx, process.cwd());
+  const limit = explicitLimit ?? (baseline.source === "none" ? NO_BASELINE_LIMIT : DEFAULT_CHANGELOG_LIMIT);
+  const query = { limit };
+  if (baseline.version !== undefined)
+    query.since = baseline.version;
+  else if (baseline.date !== undefined)
+    query.sinceDate = baseline.date;
+  verbose(ctx, `fetching changelog ${JSON.stringify(query)}`);
+  const result = await fetchChangelog(auth.access_token, query);
+  if (!result.ok)
+    handleChangelogError(ctx, result.status, result.code, result.error);
+  render(ctx, baseline, result.data.entries);
+}
+function parseSinceFlag(ctx, raw) {
+  const value = typeof raw === "string" ? raw.trim() : "";
+  if (VERSION_RE.test(value))
+    return { source: "flag", version: value };
+  if (isCalendarDate(value))
+    return { source: "flag", date: value };
+  outputError(ctx, "invalid_since", `'${typeof raw === "string" ? raw : String(raw)}' is not a valid --since value.`, ExitCodes.USAGE, "Pass a toolkit version like 'v2.55.0' or a date like '2026-10-01'.");
+}
+function isCalendarDate(value) {
+  const match = DATE_RE.exec(value);
+  if (!match)
+    return false;
+  const [, y3, m3, d2] = match;
+  const year = Number(y3);
+  const month = Number(m3);
+  const day = Number(d2);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  return date.getUTCFullYear() === year && date.getUTCMonth() === month - 1 && date.getUTCDate() === day;
+}
+function parseLimitFlag(ctx, raw) {
+  const text = typeof raw === "number" ? String(raw) : typeof raw === "string" ? raw.trim() : "";
+  if (/^\d+$/.test(text)) {
+    const n = Number(text);
+    if (n >= 1 && n <= MAX_LIMIT)
+      return n;
+  }
+  outputError(ctx, "invalid_limit", `'${typeof raw === "string" || typeof raw === "number" ? raw : String(raw)}' is not a valid --limit value.`, ExitCodes.USAGE, `Pass a whole number between 1 and ${MAX_LIMIT}.`);
+}
+function findProjectManifest(projectRoot) {
+  const configured = getToolProfile(readToolConfig()?.tool ?? DEFAULT_TOOL) ?? PROFILES[DEFAULT_TOOL];
+  const candidates = [configured, ...Object.values(PROFILES).filter((p2) => p2.toolId !== configured.toolId)];
+  for (const profile of candidates) {
+    const manifest = readManifest(join6(projectRoot, profile.manifestDir));
+    if (manifest)
+      return { profile, manifest };
+  }
+  return null;
+}
+function resolveManifestBaseline(ctx, projectRoot) {
+  const found = findProjectManifest(projectRoot);
+  if (!found) {
+    verbose(ctx, "no project manifest found");
+    return { source: "none" };
+  }
+  const { profile, manifest } = found;
+  verbose(ctx, `using manifest in ${profile.manifestDir}/`);
+  if (manifest.toolkit)
+    return { source: "sync", version: manifest.toolkit.version };
+  const applied = newestAppliedAt(manifest);
+  if (applied)
+    return { source: "applied", date: applied };
+  return { source: "none" };
+}
+function newestAppliedAt(manifest) {
+  let newest;
+  for (const lesson of Object.values(manifest.lessons ?? {})) {
+    const t = Date.parse(lesson.appliedAt);
+    if (Number.isFinite(t) && (newest === undefined || t > newest))
+      newest = t;
+  }
+  if (newest === undefined) {
+    const t = Date.parse(manifest.lastApplied);
+    if (Number.isFinite(t))
+      newest = t;
+  }
+  return newest === undefined ? undefined : new Date(newest).toISOString();
+}
+function handleChangelogError(ctx, status, code, error) {
+  if (code === "changelog_unsupported") {
+    outputError(ctx, code, "The 10x-toolkit API does not support the toolkit changelog yet.", ExitCodes.ERROR, "The changelog endpoint has not been deployed yet. Try again later; '10x sync' still updates your files.");
+  }
+  if (status === 401) {
+    outputError(ctx, "auth_required", "Your session is no longer valid.", ExitCodes.AUTH_REQUIRED, "Run '10x auth' to log in again.");
+  }
+  if (status === 0 && code === "network_error") {
+    outputError(ctx, "network_error", "Could not reach the 10x-toolkit API.", ExitCodes.ERROR, "Check your internet connection and run '10x changelog' again.");
+  }
+  outputError(ctx, code || "changelog_failed", error || "Failed to load the toolkit changelog.", ExitCodes.ERROR);
+}
+function describeBaseline(baseline) {
+  return baseline.version ?? baseline.date ?? "";
+}
+function describeSource(baseline) {
+  switch (baseline.source) {
+    case "flag":
+      return "from --since";
+    case "sync":
+      return "recorded by your last 10x sync";
+    case "applied":
+      return "last lesson applied in this project";
+    case "none":
+      return "no baseline recorded";
+  }
+}
+function render(ctx, baseline, entries) {
+  if (ctx.json) {
+    output(ctx, "", { baseline, newEntries: entries.length, entries });
+    return;
+  }
+  const lines = [];
+  if (baseline.source === "none") {
+    lines.push(`Latest toolkit changes (${describeSource(baseline)})`);
+  } else {
+    lines.push(`Toolkit changes since ${describeBaseline(baseline)} (${describeSource(baseline)})`);
+  }
+  lines.push("");
+  if (entries.length === 0) {
+    lines.push(baseline.source === "none" ? "No toolkit changes published yet." : `No toolkit changes since ${describeBaseline(baseline)}.`);
+  } else {
+    entries.forEach((entry, index) => {
+      if (index > 0)
+        lines.push("");
+      lines.push(`${entry.version} — ${entry.releasedAt.slice(0, 10)}`);
+      lines.push("");
+      lines.push(entry.markdown.trimEnd());
+    });
+  }
+  if (baseline.source === "none") {
+    lines.push("");
+    lines.push("Run 10x sync to record your baseline.");
+  }
+  output(ctx, lines.join(`
+`), undefined);
+}
+
 // src/commands/doctor.ts
 import { existsSync as existsSync5, accessSync, constants } from "node:fs";
-import { join as join6 } from "node:path";
+import { join as join7 } from "node:path";
 
 // src/lib/sentinel-migration.ts
 var OLD_BEGIN = "<!-- BEGIN @przeprogramowani/10x-toolkit -->";
@@ -6085,7 +6311,7 @@ function checkToolDirectory() {
   const toolId = readToolConfig()?.tool ?? DEFAULT_TOOL;
   const profile = getToolProfile(toolId) ?? PROFILES[DEFAULT_TOOL];
   const dirName = profile.manifestDir;
-  const toolDir = join6(cwd, dirName);
+  const toolDir = join7(cwd, dirName);
   if (!existsSync5(toolDir)) {
     return {
       name: "tool-dir",
@@ -6118,7 +6344,7 @@ function checkToolDirectory() {
 }
 
 // src/commands/get.ts
-import { join as join10 } from "node:path";
+import { join as join11 } from "node:path";
 
 // src/lib/conflict-prompt.ts
 init_dist2();
@@ -6207,7 +6433,7 @@ init_dist2();
 
 // src/lib/tool-switch.ts
 import { existsSync as existsSync9, mkdirSync as mkdirSync5, readFileSync as readFileSync8, renameSync as renameSync3, rmSync as rmSync6, writeFileSync as writeFileSync5, statSync, chmodSync as chmodSync3, openSync, closeSync } from "node:fs";
-import { dirname as dirname5, join as join9 } from "node:path";
+import { dirname as dirname5, join as join10 } from "node:path";
 import { randomUUID as randomUUID3 } from "node:crypto";
 
 // src/lib/managed-removal.ts
@@ -6260,13 +6486,13 @@ function pruneEmptyParents(root, file, boundary) {
 
 // src/lib/managed-rules.ts
 import { existsSync as existsSync7, readFileSync as readFileSync6 } from "node:fs";
-import { join as join7 } from "node:path";
+import { join as join8 } from "node:path";
 function otherRulesOwners(root, profile) {
   const owners = [];
   for (const candidate of [...Object.values(PROFILES), ...Object.values(LEGACY_PROFILES)]) {
     if (candidate.manifestDir === profile.manifestDir || candidate.rulesFile !== profile.rulesFile)
       continue;
-    const manifest = readManifest(join7(root, candidate.manifestDir));
+    const manifest = readManifest(join8(root, candidate.manifestDir));
     if (!manifest)
       continue;
     if (manifest.managedRules || !manifest.lessons || Object.values(manifest.lessons).some((lesson) => lesson.representation?.courseRules !== false))
@@ -6282,7 +6508,7 @@ function inspectExisting(content, begin, end) {
   }
 }
 function planManagedRules(root, profile, body, enabled, baseline) {
-  const path = join7(root, profile.rulesFile);
+  const path = join8(root, profile.rulesFile);
   assertProjectFilePath(root, path);
   const existing = existsSync7(path) ? readFileSync6(path, "utf8") : "";
   const current = inspectExisting(existing, profile.sentinelBegin, profile.sentinelEnd);
@@ -6328,7 +6554,7 @@ import {
   readFileSync as readFileSync7,
   writeFileSync as writeFileSync4
 } from "node:fs";
-import { dirname as dirname4, join as join8 } from "node:path";
+import { dirname as dirname4, join as join9 } from "node:path";
 var CLI_VERSION = package_default.version;
 async function applyBundle(bundle, projectRoot, options) {
   const dryRun = options.dryRun === true;
@@ -6337,7 +6563,7 @@ async function applyBundle(bundle, projectRoot, options) {
   const profile = options.profile ?? PROFILES[DEFAULT_TOOL];
   const applyCourseRules = options.applyCourseRules !== false;
   const plan = planBundle(bundle, projectRoot, { course, profile, applyCourseRules });
-  const manifestDir = join8(projectRoot, profile.manifestDir);
+  const manifestDir = join9(projectRoot, profile.manifestDir);
   const previous = readManifest(manifestDir);
   const ledger = previous ? structuredClone(previous) : {
     package: CLI_PACKAGE_NAME,
@@ -6454,22 +6680,22 @@ async function applyBundle(bundle, projectRoot, options) {
   let rulesDelivered = !rules.isConflict;
   let rulesBackup;
   if (rules.isConflict && !rules.blocked && !dryRun) {
-    const resolution = await options.onConflict?.({ artifactType: "rules", artifactName: "course-rules", filePath: join8(projectRoot, profile.rulesFile), relativePath: profile.rulesFile }) ?? "skip";
+    const resolution = await options.onConflict?.({ artifactType: "rules", artifactName: "course-rules", filePath: join9(projectRoot, profile.rulesFile), relativePath: profile.rulesFile }) ?? "skip";
     if (resolution !== "skip") {
       rulesDelivered = true;
       rulesAction = resolution === "save_user" ? "conflict_saved_user" : "conflict_overwritten";
       if (resolution === "save_user") {
-        rulesBackup = buildUserBackupPath(join8(projectRoot, profile.rulesFile));
+        rulesBackup = buildUserBackupPath(join9(projectRoot, profile.rulesFile));
         assertProjectFilePath(projectRoot, rulesBackup);
-        assertProjectFilePath(projectRoot, join8(projectRoot, profile.rulesFile));
-        copyFileSync(join8(projectRoot, profile.rulesFile), rulesBackup);
+        assertProjectFilePath(projectRoot, join9(projectRoot, profile.rulesFile));
+        copyFileSync(join9(projectRoot, profile.rulesFile), rulesBackup);
       }
     }
   }
   if (rulesDelivered) {
     if (!dryRun && rulesAction !== "unchanged") {
-      assertProjectFilePath(projectRoot, join8(projectRoot, profile.rulesFile));
-      const path = join8(projectRoot, profile.rulesFile);
+      assertProjectFilePath(projectRoot, join9(projectRoot, profile.rulesFile));
+      const path = join9(projectRoot, profile.rulesFile);
       if (!existsSync8(path) || readFileSync7(path, "utf8") !== rules.content)
         writeFileAt(path, rules.content);
     }
@@ -6546,14 +6772,14 @@ function planBundle(bundle, projectRoot, options) {
     assertSafeName(prompt.name, "prompt");
   for (const config of bundle.configs)
     assertSafeName(config.name, "config");
-  const manifestDir = join8(projectRoot, profile.manifestDir);
-  assertProjectFilePath(projectRoot, join8(manifestDir, MANIFEST_FILENAME));
+  const manifestDir = join9(projectRoot, profile.manifestDir);
+  assertProjectFilePath(projectRoot, join9(manifestDir, MANIFEST_FILENAME));
   const prevManifest = readManifest(manifestDir);
   const skills = bundle.skills.map((skill) => {
-    const skillDir = join8(projectRoot, profile.skillDir(skill.name));
+    const skillDir = join9(projectRoot, profile.skillDir(skill.name));
     const prevEntry = prevManifest?.files.skills[skill.name];
     const files = skill.files.map((file) => {
-      const target = join8(skillDir, file.path);
+      const target = join9(skillDir, file.path);
       assertProjectFilePath(projectRoot, target);
       const storedHash = prevEntry?.contentHashes?.[file.path];
       const { action, isConflict } = computeFileAction(target, file.content, storedHash);
@@ -6568,7 +6794,7 @@ function planBundle(bundle, projectRoot, options) {
     return { name: skill.name, files };
   });
   const prompts = bundle.prompts.map((prompt) => {
-    const target = join8(projectRoot, profile.promptPath(prompt.name));
+    const target = join9(projectRoot, profile.promptPath(prompt.name));
     assertProjectFilePath(projectRoot, target);
     const storedHash = prevManifest?.files.promptHashes?.[`${prompt.name}.md`];
     const { action, isConflict } = computeFileAction(target, prompt.content, storedHash);
@@ -6580,12 +6806,12 @@ function planBundle(bundle, projectRoot, options) {
       upstreamChanged: computeUpstreamChanged(prompt.content, storedHash, action)
     };
   });
-  const rulesFilePath = join8(projectRoot, profile.rulesFile);
+  const rulesFilePath = join9(projectRoot, profile.rulesFile);
   const rulesPlan = planManagedRules(projectRoot, profile, bundle.rules.length ? bundle.rules.map((r2) => r2.content.trim()).join(`
 
 `) : undefined, applyCourseRules, prevManifest?.managedRules);
   const configs = bundle.configs.map((config) => {
-    const target = join8(projectRoot, profile.configPath(config.name));
+    const target = join9(projectRoot, profile.configPath(config.name));
     assertProjectFilePath(projectRoot, target);
     const action = existsSync8(target) ? "skipped" : "created";
     return {
@@ -6598,8 +6824,8 @@ function planBundle(bundle, projectRoot, options) {
   });
   const removed = computeRemovals(prevManifest, bundle, profile, projectRoot);
   const targets = [
-    join8(manifestDir, MANIFEST_FILENAME),
-    join8(manifestDir, `${MANIFEST_FILENAME}.tmp`),
+    join9(manifestDir, MANIFEST_FILENAME),
+    join9(manifestDir, `${MANIFEST_FILENAME}.tmp`),
     rulesFilePath,
     buildUserBackupPath(rulesFilePath),
     ...skills.flatMap((skill) => skill.files.flatMap((file) => [file.path, buildUserBackupPath(file.path)])),
@@ -6692,7 +6918,7 @@ function computeRemovals(previous, bundle, profile, root) {
         throw new Error("Unsafe skill path in manifest");
       if (bundle.skills.some((entry) => entry.name === name && entry.files.some((entry2) => entry2.path === file)))
         continue;
-      out.skills.push(planManagedRemoval(root, { name: `${name}/${file}`, path: join8(root, profile.skillDir(name), file), storedHash: previous.files.skills[name]?.contentHashes?.[file], protected: others.some((entry) => entry.skills[name]?.files.includes(file)), pruneRoot: join8(root, profile.skillDir(name)) }));
+      out.skills.push(planManagedRemoval(root, { name: `${name}/${file}`, path: join9(root, profile.skillDir(name), file), storedHash: previous.files.skills[name]?.contentHashes?.[file], protected: others.some((entry) => entry.skills[name]?.files.includes(file)), pruneRoot: join9(root, profile.skillDir(name)) }));
     }
   }
   for (const kind of ["prompts", "configs"])
@@ -6701,7 +6927,7 @@ function computeRemovals(previous, bundle, profile, root) {
         throw new Error("Unsafe file name in manifest");
       if ((kind === "prompts" ? bundle.prompts.map((p2) => `${p2.name}.md`) : bundle.configs.map((c2) => c2.name)).includes(name))
         continue;
-      const path = join8(root, kind === "prompts" ? profile.promptPath(name.replace(/\.md$/, "")) : profile.configPath(name));
+      const path = join9(root, kind === "prompts" ? profile.promptPath(name.replace(/\.md$/, "")) : profile.configPath(name));
       out[kind].push(planManagedRemoval(root, { name, path, storedHash: kind === "prompts" ? previous.files.promptHashes?.[name] : previous.files.configHashes?.[name], protected: others.some((entry) => entry[kind].includes(name)), config: kind === "configs" }));
     }
   return out;
@@ -6711,10 +6937,10 @@ function findOrphanedManifests(projectRoot, currentProfile) {
   for (const profile of [...Object.values(PROFILES), ...Object.values(LEGACY_PROFILES)]) {
     if (profile.toolId === currentProfile.toolId)
       continue;
-    const manifestPath = join8(projectRoot, profile.manifestDir, MANIFEST_FILENAME);
+    const manifestPath = join9(projectRoot, profile.manifestDir, MANIFEST_FILENAME);
     if (!existsSync8(manifestPath))
       continue;
-    const manifest = readManifest(join8(projectRoot, profile.manifestDir));
+    const manifest = readManifest(join9(projectRoot, profile.manifestDir));
     if (!manifest)
       continue;
     out.push({ profile, manifestPath, manifest });
@@ -6789,7 +7015,7 @@ function entries(manifest) {
 function entryPath(root, profile, entry) {
   if (!isSafeName(entry.name) || entry.file !== undefined && !isSafeSkillFilePath(entry.file))
     throw new Error("unsafe name or path in manifest");
-  return join9(root, entry.kind === "skills" ? join9(profile.skillDir(entry.name), entry.file) : entry.kind === "prompts" ? profile.promptPath(entry.name.replace(/\.md$/, "")) : profile.configPath(entry.name));
+  return join10(root, entry.kind === "skills" ? join10(profile.skillDir(entry.name), entry.file) : entry.kind === "prompts" ? profile.promptPath(entry.name.replace(/\.md$/, "")) : profile.configPath(entry.name));
 }
 function owns(lesson, entry) {
   return entry.kind === "skills" ? !!lesson.skills[entry.name]?.files.includes(entry.file) : lesson[entry.kind].includes(entry.name);
@@ -6841,19 +7067,19 @@ function record(summary, entry) {
 }
 function persistSource(root, profile, source) {
   rebuildManifestFiles(source);
-  const dir = join9(root, profile.manifestDir);
+  const dir = join10(root, profile.manifestDir);
   if (entries(source).length || source.managedRules) {
     writeManifest(dir, source);
     return;
   }
-  const path = join9(dir, MANIFEST_FILENAME);
+  const path = join10(dir, MANIFEST_FILENAME);
   assertProjectFilePath(root, path);
   rmSync6(path, { force: true });
   pruneEmptyParents(root, path, dir);
 }
 function commitSourceRules(root, profile, source, update) {
-  const rulesPath = join9(root, profile.rulesFile);
-  const manifestPath = join9(root, profile.manifestDir, MANIFEST_FILENAME);
+  const rulesPath = join10(root, profile.rulesFile);
+  const manifestPath = join10(root, profile.manifestDir, MANIFEST_FILENAME);
   assertProjectFilePath(root, rulesPath);
   assertProjectFilePath(root, manifestPath);
   const rulesBefore = existsSync9(rulesPath) ? readFileSync8(rulesPath) : undefined;
@@ -6899,16 +7125,16 @@ function copyForTransfer(root, from, to, bytes) {
 function preflightProfilePaths(root, orphan, destination) {
   assertProjectFilePath(root, orphan.manifestPath);
   for (const profile of destination ? [orphan.profile, destination] : [orphan.profile]) {
-    assertProjectPath(root, join9(root, profile.manifestDir));
+    assertProjectPath(root, join10(root, profile.manifestDir));
     for (const file of [MANIFEST_FILENAME, `${MANIFEST_FILENAME}.tmp`])
-      assertProjectFilePath(root, join9(root, profile.manifestDir, file));
-    assertProjectFilePath(root, join9(root, profile.rulesFile));
+      assertProjectFilePath(root, join10(root, profile.manifestDir, file));
+    assertProjectFilePath(root, join10(root, profile.rulesFile));
     for (const entry of entries(orphan.manifest)) {
       const path = entryPath(root, profile, entry);
       assertProjectFilePath(root, path);
       assertProjectFilePath(root, `${path}.tmp`);
     }
-    const rulesPath = join9(root, profile.rulesFile);
+    const rulesPath = join10(root, profile.rulesFile);
     if (existsSync9(rulesPath))
       inspectRulesBlock(readFileSync8(rulesPath, "utf8"), profile.sentinelBegin, profile.sentinelEnd);
   }
@@ -6923,7 +7149,7 @@ function begin(root, orphan, destination) {
   const source = structuredClone(orphan.manifest);
   source.course = course;
   source.lessons = seedLessons(source);
-  const rulesPath = join9(root, orphan.profile.rulesFile);
+  const rulesPath = join10(root, orphan.profile.rulesFile);
   if (!source.managedRules && existsSync9(rulesPath) && inspectRulesBlock(readFileSync8(rulesPath, "utf8"), orphan.profile.sentinelBegin, orphan.profile.sentinelEnd)) {
     source.managedRules = { path: orphan.profile.rulesFile, begin: orphan.profile.sentinelBegin, end: orphan.profile.sentinelEnd };
   }
@@ -6934,7 +7160,7 @@ function migrateArtifacts(root, orphan, profile) {
   if (!existsSync9(orphan.manifestPath))
     return summary;
   const source = begin(root, orphan, profile);
-  const destination = readManifest(join9(root, profile.manifestDir)) ?? { ...structuredClone(source), tool: profile.toolId, files: { skills: {}, prompts: [], configs: [] }, lessons: {}, managedRules: undefined };
+  const destination = readManifest(join10(root, profile.manifestDir)) ?? { ...structuredClone(source), tool: profile.toolId, files: { skills: {}, prompts: [], configs: [] }, lessons: {}, managedRules: undefined };
   destination.lessons = seedLessons(destination);
   destination.course = source.course;
   destination.tool = profile.toolId;
@@ -6954,7 +7180,7 @@ function migrateArtifacts(root, orphan, profile) {
     if (!existsSync9(to))
       copyForTransfer(root, from, to, bytes);
     acquire(destination, source, entry);
-    writeManifest(join9(root, profile.manifestDir), destination);
+    writeManifest(join10(root, profile.manifestDir), destination);
     record(summary, entry);
     try {
       assertProjectFilePath(root, from);
@@ -6977,7 +7203,7 @@ function migrateArtifacts(root, orphan, profile) {
       }
       throw error;
     }
-    pruneEmptyParents(root, from, join9(root, orphan.profile.manifestDir));
+    pruneEmptyParents(root, from, join10(root, orphan.profile.manifestDir));
   }
   commitSourceRules(root, orphan.profile, source, () => {
     transferRules(root, orphan.profile, profile, source, destination, summary);
@@ -6988,7 +7214,7 @@ function transferRules(root, old, profile, source, destination, summary) {
   const metadata = source.managedRules;
   if (!metadata)
     return;
-  const from = join9(root, old.rulesFile);
+  const from = join10(root, old.rulesFile);
   if (!existsSync9(from)) {
     delete source.managedRules;
     return;
@@ -7009,24 +7235,24 @@ function transferRules(root, old, profile, source, destination, summary) {
       return;
     }
     destination.managedRules = { ...metadata };
-    writeManifest(join9(root, profile.manifestDir), destination);
+    writeManifest(join10(root, profile.manifestDir), destination);
     if (!entries(source).length)
       delete source.managedRules;
     return;
   }
   const plan = planManagedRules(root, profile, block.body, true, destination.managedRules);
   if (plan.isConflict) {
-    summary.skipped.push({ path: join9(root, profile.rulesFile), reason: plan.reason ?? "rules conflict" });
+    summary.skipped.push({ path: join10(root, profile.rulesFile), reason: plan.reason ?? "rules conflict" });
     return;
   }
-  const to = join9(root, profile.rulesFile);
+  const to = join10(root, profile.rulesFile);
   if (plan.action !== "unchanged") {
     assertProjectFilePath(root, to);
     mkdirSync5(dirname5(to), { recursive: true });
     writeFileSync5(to, plan.content);
   }
   destination.managedRules = plan.next;
-  writeManifest(join9(root, profile.manifestDir), destination);
+  writeManifest(join10(root, profile.manifestDir), destination);
   if (entries(source).length)
     return;
   if (!otherRulesOwners(root, old).length) {
@@ -7044,7 +7270,7 @@ function deleteArtifacts(root, orphan) {
   const source = begin(root, orphan);
   for (const entry of entries(source)) {
     const path = entryPath(root, orphan.profile, entry);
-    const plan = planManagedRemoval(root, { name: entry.name, path, storedHash: entry.hash, config: entry.kind === "configs", pruneRoot: join9(root, orphan.profile.manifestDir) });
+    const plan = planManagedRemoval(root, { name: entry.name, path, storedHash: entry.hash, config: entry.kind === "configs", pruneRoot: join10(root, orphan.profile.manifestDir) });
     const result = executeManagedRemoval(root, plan);
     if (result.action === "removed")
       record(summary, entry);
@@ -7055,7 +7281,7 @@ function deleteArtifacts(root, orphan) {
   }
   commitSourceRules(root, orphan.profile, source, () => {
     if (source.managedRules) {
-      const path = join9(root, orphan.profile.rulesFile);
+      const path = join10(root, orphan.profile.rulesFile);
       const plan = planManagedRules(root, orphan.profile, undefined, false, source.managedRules);
       if (plan.isConflict)
         summary.skipped.push({ path, reason: "managed rules require explicit resolution: missing baseline or local edits" });
@@ -7204,6 +7430,28 @@ function printMigrationSummary(summary, newProfile) {
 `));
 }
 
+// src/lib/toolkit-baseline.ts
+async function recordLatestToolkitVersion(ctx, token, manifestDir, now = () => new Date) {
+  try {
+    if (!readManifest(manifestDir))
+      return;
+    const result = await fetchChangelog(token, { limit: 1 });
+    if (!result.ok) {
+      verbose(ctx, `toolkit version not recorded: ${result.code}`);
+      return;
+    }
+    const latest = result.data.entries[0];
+    if (!latest) {
+      verbose(ctx, "toolkit version not recorded: no changelog entries");
+      return;
+    }
+    if (recordToolkitVersion(manifestDir, latest.version, now()))
+      verbose(ctx, `recorded toolkit ${latest.version}`);
+  } catch (error) {
+    verbose(ctx, `toolkit version not recorded: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
 // src/commands/get.ts
 var ARTIFACT_TYPES = ["skills", "prompts", "rules", "configs"];
 function isArtifactType(s) {
@@ -7277,7 +7525,7 @@ async function runGet(ctx, ref, options) {
   const isFiltered = options.type !== undefined;
   const bundle = filterBundle(ctx, result.data, options);
   const isTTY = process.stdout.isTTY === true;
-  const prevManifest = readManifest(join10(process.cwd(), profile.manifestDir));
+  const prevManifest = readManifest(join11(process.cwd(), profile.manifestDir));
   if (prevManifest && prevManifest.manifestVersion === 2) {
     showUpgradeNotice(isTTY);
   }
@@ -7302,6 +7550,9 @@ async function runGet(ctx, ref, options) {
   } catch (error) {
     reportCourseError(ctx, error);
   }
+  if (!dryRun && !isFiltered) {
+    await recordLatestToolkitVersion(ctx, auth.access_token, join11(process.cwd(), profile.manifestDir));
+  }
   renderGetResult(ctx, bundle, writeResult, dryRun, profile, {
     course,
     selectionReason: selection.reason,
@@ -7534,7 +7785,7 @@ function renderGetResult(ctx, bundle, writeResult, dryRun, profile, langMeta) {
 
 // src/commands/helpers.ts
 import { existsSync as existsSync10, mkdirSync as mkdirSync6, readFileSync as readFileSync9, writeFileSync as writeFileSync6 } from "node:fs";
-import { dirname as dirname6, join as join11, resolve as resolve3 } from "node:path";
+import { dirname as dirname6, join as join12, resolve as resolve3 } from "node:path";
 
 // skills/10x-cli-setup/SKILL.md
 var SKILL_default = `---
@@ -8023,7 +8274,7 @@ their own evidence; do not imply a Windows or translated-content walkthrough ran
 // skills/10x-cli-guide/SKILL.md
 var SKILL_default2 = `---
 name: 10x-cli-guide
-description: "Use when the user wants to download, use or update 10xDevs CLI skills, choose a helper installation channel, inspect course content, switch tool profiles or troubleshoot CLI/auth/content conflicts. Guides filtered get → an actual agent task → sync while preserving local work and course/tool/language context. For first installation or authentication preparation, use an available 10x-cli-setup copy. Does not implement CLI runtime or grant course access."
+description: "Use when the user wants to download, use or update 10xDevs CLI skills, choose a helper installation channel, inspect course content, switch tool profiles, see what changed in 10x-toolkit releases (changelog) or troubleshoot CLI/auth/content conflicts. Guides filtered get → an actual agent task → sync while preserving local work and course/tool/language context. For first installation or authentication preparation, use an available 10x-cli-setup copy. Does not implement CLI runtime or grant course access."
 ---
 
 # 10x-cli: download, use, update
@@ -8239,6 +8490,22 @@ skill/prompt edits and does not bypass protected rules or safe removal. Config
 templates remain create-only. Cleanup preserves modified/untracked files and
 files owned elsewhere; do not manually sweep a skill directory after sync.
 
+To see what changed in the course toolkit itself, use \`changelog\`. This command
+is **unreleased**: check the actual runner's \`changelog --help\` first.
+
+\`\`\`bash
+10x_cli changelog                      # toolkit releases since this project's last sync
+10x_cli changelog --since v2.55.0      # releases after a version
+10x_cli changelog --since 2026-10-01   # releases from that UTC day on
+\`\`\`
+
+It lists toolkit release notes (skills, prompts, rules, config templates per
+release), not this project's files: \`sync --dry-run\` remains the authority for
+what would be downloaded. A successful sync (or full unfiltered get) records the
+newest toolkit version in the project manifest as the baseline; without it the
+command falls back to the last applied lesson's date, or shows the latest 5
+releases. "No toolkit changes" with exit 0 is normal. It never writes files.
+
 Three updates are independent: changing the npm/binary version updates the CLI;
 repeating pinned public \`skills add\` with a deliberately chosen new retained SHA
 updates a public helper; CLI sync updates CLI-owned course skills. It does not
@@ -8299,6 +8566,7 @@ visible. Doctor exit 78 can coexist with outer JSON \`status: "ok"\`.
 | Denied course access | Confirm selected course and membership; changing tool/reinstalling does not grant access. |
 | Locked or unpublished v4 | Inspect module availability/release evidence; do not bypass the gate or fall back to v3. |
 | Unsupported name/missing index | Verify exact CLI package and content release; preserve the error for the release owner. |
+| \`changelog_unsupported\` | The backend does not serve the toolkit changelog yet; sync/get still work. Retry later; do not treat it as a content failure. |
 | Network/API failure | Keep diagnostics, retry the same context when service returns; no config reset. |
 | Missing \`10x-idea-check\` after setup | Older helper journeys selected only init/shape/prd. Check the actual commands, selected profile path and manifest; use the idea-check preview/get above to add its complete tree. If the files already exist, read that exact SKILL.md and check the agent's discovery/reload behavior before reinstalling. An absent slash command alone does not prove missing files. |
 | Wrong directory/profile | Recheck cwd and explicit flags; a fresh project may legitimately have no tool directory. |
@@ -8662,7 +8930,7 @@ function registerHelpersCommand(cli) {
     const root = process.cwd();
     try {
       const files = Object.entries(BUNDLED_HELPERS).flatMap(([name, tree]) => Object.entries(tree).map(([file, content]) => {
-        const path = join11(profile.skillDir(name), file);
+        const path = join12(profile.skillDir(name), file);
         const absolute = resolve3(root, path);
         assertProjectFilePath(root, absolute);
         const state = !existsSync10(absolute) ? "missing" : readFileSync9(absolute).equals(Buffer.from(content)) ? "unchanged" : "conflict";
@@ -8841,11 +9109,11 @@ function renderModuleDetail(ctx, module, course, reason) {
 }
 
 // src/commands/sync.ts
-import { join as join13 } from "node:path";
+import { join as join14 } from "node:path";
 
 // src/lib/sync-freshness.ts
 import { existsSync as existsSync11, readFileSync as readFileSync10 } from "node:fs";
-import { join as join12 } from "node:path";
+import { join as join13 } from "node:path";
 function isLessonFresh(root, manifest, id, profile, lang, courseRules) {
   const lesson = manifest?.lessons?.[id];
   const representation = lesson?.representation;
@@ -8860,16 +9128,16 @@ function isLessonFresh(root, manifest, id, profile, lang, courseRules) {
       if (!isSafeName(name))
         return false;
       for (const file of skill.files)
-        if (!isSafeSkillFilePath(file) || !matches(join12(root, profile.skillDir(name), file), manifest.files.skills[name]?.contentHashes?.[file]))
+        if (!isSafeSkillFilePath(file) || !matches(join13(root, profile.skillDir(name), file), manifest.files.skills[name]?.contentHashes?.[file]))
           return false;
     }
     for (const name of lesson.prompts)
-      if (!isSafeName(name) || !matches(join12(root, profile.promptPath(name.replace(/\.md$/, ""))), manifest.files.promptHashes?.[name]))
+      if (!isSafeName(name) || !matches(join13(root, profile.promptPath(name.replace(/\.md$/, ""))), manifest.files.promptHashes?.[name]))
         return false;
     for (const name of lesson.configs)
-      if (!isSafeName(name) || !matches(join12(root, profile.configPath(name)), manifest.files.configHashes?.[name]))
+      if (!isSafeName(name) || !matches(join13(root, profile.configPath(name)), manifest.files.configHashes?.[name]))
         return false;
-    const rulesPath = join12(root, profile.rulesFile);
+    const rulesPath = join13(root, profile.rulesFile);
     assertProjectFilePath(root, rulesPath);
     const existing = existsSync11(rulesPath) ? readFileSync10(rulesPath, "utf8") : "";
     const block = inspectRulesBlock(existing, profile.sentinelBegin, profile.sentinelEnd);
@@ -8930,7 +9198,7 @@ async function runSync(ctx, options) {
     }
     return true;
   });
-  const manifest = readManifest(join13(process.cwd(), profile.manifestDir));
+  const manifest = readManifest(join14(process.cwd(), profile.manifestDir));
   const manifestLessonIds = new Set(manifest?.lessons ? Object.keys(manifest.lessons) : manifest ? [manifest.lessonId] : []);
   let targets = unlocked;
   if (moduleFilter !== undefined)
@@ -8973,6 +9241,9 @@ async function runSync(ctx, options) {
   } finally {
     process.removeListener("SIGINT", onSigint);
   }
+  if (!dryRun && !controller.signal.aborted && !outcomes.some((o) => o.status === "errored")) {
+    await recordLatestToolkitVersion(ctx, auth.access_token, join14(process.cwd(), profile.manifestDir));
+  }
   renderReport(ctx, profile, {
     course,
     selectionReason: selection.reason,
@@ -8988,7 +9259,7 @@ async function runSync(ctx, options) {
   }
 }
 async function syncLesson(ctx, lesson, opts) {
-  const currentManifest = readManifest(join13(process.cwd(), opts.profile.manifestDir));
+  const currentManifest = readManifest(join14(process.cwd(), opts.profile.manifestDir));
   const stored = currentManifest?.lessons?.[lesson.lessonId]?.catalogContentHash;
   if (!opts.force && lesson.contentHash !== undefined && stored !== undefined && lesson.contentHash === stored && isLessonFresh(process.cwd(), currentManifest, lesson.lessonId, opts.profile, opts.lang, opts.applyCourseRules)) {
     verbose(ctx, `${lesson.lessonId}: upstream unchanged (digest match) — skipping fetch`);
@@ -9339,6 +9610,7 @@ registerGetCommand(cli);
 registerHelpersCommand(cli);
 registerListCommand(cli);
 registerSyncCommand(cli);
+registerChangelogCommand(cli);
 registerDoctorCommand(cli);
 registerBenchCommand(cli);
 registerBenchKitCommand(cli);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@przeprogramowani/10x-cli",
-  "version": "1.26.5",
+  "version": "1.27.0",
   "description": "Open-source CLI for 10xDevs course content",
   "repository": {
     "type": "git",

package/skills/10x-cli-guide/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: 10x-cli-guide
-description: "Use when the user wants to download, use or update 10xDevs CLI skills, choose a helper installation channel, inspect course content, switch tool profiles or troubleshoot CLI/auth/content conflicts. Guides filtered get → an actual agent task → sync while preserving local work and course/tool/language context. For first installation or authentication preparation, use an available 10x-cli-setup copy. Does not implement CLI runtime or grant course access."
+description: "Use when the user wants to download, use or update 10xDevs CLI skills, choose a helper installation channel, inspect course content, switch tool profiles, see what changed in 10x-toolkit releases (changelog) or troubleshoot CLI/auth/content conflicts. Guides filtered get → an actual agent task → sync while preserving local work and course/tool/language context. For first installation or authentication preparation, use an available 10x-cli-setup copy. Does not implement CLI runtime or grant course access."
 ---
 
 # 10x-cli: download, use, update
@@ -216,6 +216,22 @@ skill/prompt edits and does not bypass protected rules or safe removal. Config
 templates remain create-only. Cleanup preserves modified/untracked files and
 files owned elsewhere; do not manually sweep a skill directory after sync.
 
+To see what changed in the course toolkit itself, use `changelog`. This command
+is **unreleased**: check the actual runner's `changelog --help` first.
+
+```bash
+10x_cli changelog                      # toolkit releases since this project's last sync
+10x_cli changelog --since v2.55.0      # releases after a version
+10x_cli changelog --since 2026-10-01   # releases from that UTC day on
+```
+
+It lists toolkit release notes (skills, prompts, rules, config templates per
+release), not this project's files: `sync --dry-run` remains the authority for
+what would be downloaded. A successful sync (or full unfiltered get) records the
+newest toolkit version in the project manifest as the baseline; without it the
+command falls back to the last applied lesson's date, or shows the latest 5
+releases. "No toolkit changes" with exit 0 is normal. It never writes files.
+
 Three updates are independent: changing the npm/binary version updates the CLI;
 repeating pinned public `skills add` with a deliberately chosen new retained SHA
 updates a public helper; CLI sync updates CLI-owned course skills. It does not
@@ -276,6 +292,7 @@ visible. Doctor exit 78 can coexist with outer JSON `status: "ok"`.
 | Denied course access | Confirm selected course and membership; changing tool/reinstalling does not grant access. |
 | Locked or unpublished v4 | Inspect module availability/release evidence; do not bypass the gate or fall back to v3. |
 | Unsupported name/missing index | Verify exact CLI package and content release; preserve the error for the release owner. |
+| `changelog_unsupported` | The backend does not serve the toolkit changelog yet; sync/get still work. Retry later; do not treat it as a content failure. |
 | Network/API failure | Keep diagnostics, retry the same context when service returns; no config reset. |
 | Missing `10x-idea-check` after setup | Older helper journeys selected only init/shape/prd. Check the actual commands, selected profile path and manifest; use the idea-check preview/get above to add its complete tree. If the files already exist, read that exact SKILL.md and check the agent's discovery/reload behavior before reinstalling. An absent slash command alone does not prove missing files. |
 | Wrong directory/profile | Recheck cwd and explicit flags; a fresh project may legitimately have no tool directory. |