@remnic/core 9.69.12 → 9.69.13

package/src/activity/config.test.ts

@@ -17,7 +17,30 @@ test("parseActivityConfig defaults to an inert, search-only configuration", () =
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
-    timeline: { enabled: false, journal: { enabled: false, source: "file" }, qa: { enabled: false, maxRangeDays: 31 } },
+    timeline: {
+      enabled: false,
+      journal: { enabled: false, source: "file" },
+      qa: { enabled: false, maxRangeDays: 31 },
+      vault: {
+        enabled: false,
+        vaultPath: "",
+        dailyNotePath: "{yyyy}-{MM}-{dd}.md",
+        weeklyNotePath: "",
+        createMissingNotes: false,
+        noteTemplate: "",
+        sectionStrategy: "markers",
+        publish: {
+          timeline: { enabled: true, target: "daily", section: "Timeline" },
+          standup: { enabled: false, target: "daily", section: "Standup" },
+          weekly: { enabled: false, target: "weekly", section: "Weekly Review" },
+          locations: { enabled: false, target: "daily", section: "Locations" },
+        },
+        insertUnderHeading: "",
+        wikilinks: { places: false, placesFolder: "Places" },
+        properties: { mode: "off", prefix: "remnic_" },
+        autoPublish: true,
+      },
+    },
   });
   assert.deepEqual(parseActivityConfig(undefined), defaultActivityConfig());
 });
@@ -150,3 +173,73 @@ test("activity config rejects a null extractionMode instead of silently defaulti
 test("activity config rejects a null maxMemoriesPerDay instead of silently uncapping", () => {
   assert.throws(() => parseActivityConfig({ maxMemoriesPerDay: null }), /maxMemoriesPerDay/);
 });
+
+test("vault publish section names are rejected at config load when the publisher would reject them", () => {
+  // `Timeline-->` and an embedded newline both pass a trimmed-string check
+  // but break the `<!-- remnic:<name>:start -->` marker, so `publishVaultNote`
+  // throws. The accepted config domain must equal the publisher's.
+  for (const section of ["Timeline-->", "Time\nline"]) {
+    assert.throws(
+      () =>
+        parseActivityConfig({
+          timeline: { vault: { publish: { timeline: { section } } } },
+        }),
+      /publish\.timeline\.section must not contain a line break or "-->"/,
+    );
+  }
+  const ok = parseActivityConfig({
+    timeline: { vault: { publish: { timeline: { section: "Timeline" } } } },
+  });
+  assert.equal(ok.timeline.vault.publish.timeline.section, "Timeline");
+});
+
+test("noteTemplate path shape is validated at config load when createMissingNotes is true", () => {
+  // The field is documented vault-relative; an absolute or `..`-bearing
+  // value would only fail later as a publish-time `template_escape`.
+  for (const noteTemplate of ["/vault/daily.md", "../daily.md", "Daily/../daily.md"]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { vault: { createMissingNotes: true, noteTemplate } } }),
+      /activity\.timeline\.vault\.noteTemplate:/,
+    );
+  }
+  const ok = parseActivityConfig({
+    timeline: { vault: { createMissingNotes: true, noteTemplate: "Templates/daily.md" } },
+  });
+  assert.equal(ok.timeline.vault.noteTemplate, "Templates/daily.md");
+});
+
+test("an explicitly disabled weekly target loads identically to an omitted one", () => {
+  // Tools that serialize schema defaults write `publish.weekly.enabled: false`;
+  // that must behave exactly like leaving the object out, not demand a
+  // weeklyNotePath the disabled target never uses.
+  const explicit = parseActivityConfig({
+    timeline: { vault: { publish: { weekly: { enabled: false } } } },
+  });
+  const omitted = parseActivityConfig({ timeline: { vault: {} } });
+  assert.deepEqual(explicit.timeline.vault, omitted.timeline.vault);
+
+  assert.throws(
+    () => parseActivityConfig({ timeline: { vault: { publish: { weekly: { enabled: true } } } } }),
+    /weeklyNotePath is empty/,
+  );
+});
+
+test("an enabled vault rejects relative or whitespace-only vaultPath at config load", () => {
+  // A relative root resolves against the process working directory, so the
+  // same config would update different files depending on how the daemon or
+  // CLI was launched. The contract is absolute or `~`-rooted, enforced at
+  // parse time — not as a publish-time surprise.
+  for (const vaultPath of [".", "vault", "../notes", "   "]) {
+    assert.throws(
+      () => parseActivityConfig({ timeline: { vault: { enabled: true, vaultPath } } }),
+      /vaultPath must be an absolute or `~`-rooted path/,
+    );
+  }
+  for (const vaultPath of ["/home/user/notes", "~", "~/notes"]) {
+    const ok = parseActivityConfig({ timeline: { vault: { enabled: true, vaultPath } } });
+    assert.equal(ok.timeline.vault.vaultPath, vaultPath);
+  }
+  // A disabled vault may carry any placeholder — nothing resolves it.
+  const inert = parseActivityConfig({ timeline: { vault: { enabled: false, vaultPath: "." } } });
+  assert.equal(inert.timeline.vault.vaultPath, ".");
+});

package/src/activity/config.ts

@@ -1,7 +1,10 @@
+import path from "node:path";
+
 import { coerceBooleanLike, coerceNumber } from "../connectors/coerce.js";
 import { assertValidTimezone } from "./digest.js";
 import { resolveJournalSource } from "./journal-source.js";
-import type { ImportanceLevel } from "../types.js";
+import { validateVaultNoteTemplate } from "./vault-path.js";
+import { validateRegionName } from "./vault-region.js";
 import type {
   ActivityConfig,
   ActivityExtractionMode,
@@ -9,7 +12,10 @@ import type {
   ActivityTimelineConfig,
   ActivityTimelineJournalConfig,
   ActivityTimelineQaConfig,
+  ActivityTimelineVaultConfig,
+  ActivityTimelineVaultTargetConfig,
 } from "./types.js";
+import type { ImportanceLevel } from "../types.js";
 
 const EXTRACTION_MODES: readonly ActivityExtractionMode[] = ["off", "smart"];
 const IMPORTANCE_LEVELS: readonly ImportanceLevel[] = ["critical", "high", "normal", "low", "trivial"];
@@ -30,7 +36,12 @@ export function defaultActivityConfig(): ActivityConfig {
     minConfidence: 0.7,
     minImportance: "normal",
     maxMemoriesPerDay: 0,
-    timeline: { enabled: false, journal: { enabled: false, source: "file" }, qa: { enabled: false, maxRangeDays: 31 } },
+    timeline: {
+      enabled: false,
+      journal: { enabled: false, source: "file" },
+      qa: { enabled: false, maxRangeDays: 31 },
+      vault: parseTimelineVaultConfig(undefined),
+    },
   };
 }
 
@@ -201,7 +212,14 @@ export function parseActivityConfig(raw: unknown): ActivityConfig {
  * is malformed and must fail rather than silently disabling the layer.
  */
 function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
-  if (raw === undefined) return { enabled: false, journal: { enabled: false, source: "file" }, qa: parseTimelineQaConfig(undefined) };
+  if (raw === undefined) {
+    return {
+      enabled: false,
+      journal: { enabled: false, source: "file" },
+      qa: parseTimelineQaConfig(undefined),
+      vault: parseTimelineVaultConfig(undefined),
+    };
+  }
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
     throw new TypeError("activity.timeline must be an object");
   }
@@ -214,9 +232,243 @@ function parseTimelineConfig(raw: unknown): ActivityTimelineConfig {
     enabled: enabledValue ?? false,
     journal: parseTimelineJournalConfig(timeline.journal),
     qa: parseTimelineQaConfig(timeline.qa),
+    vault: parseTimelineVaultConfig(timeline.vault),
+  };
+}
+
+/**
+ * Parse the `activity.timeline.vault.*` block (issue #1985). Default off.
+ * Invalid values are rejected at parse time naming the missing or invalid
+ * prerequisite — never silently defaulted.
+ */
+export function parseTimelineVaultConfig(raw: unknown): ActivityTimelineVaultConfig {
+  if (raw === undefined) return defaultVaultConfig();
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline.vault must be an object");
+  }
+  const vault = raw as Record<string, unknown>;
+  const enabled = requireBool(vault.enabled, "activity.timeline.vault.enabled", false);
+  const createMissingNotes = requireBool(vault.createMissingNotes, "activity.timeline.vault.createMissingNotes", false);
+  const autoPublish = requireBool(vault.autoPublish, "activity.timeline.vault.autoPublish", true);
+  const vaultPath = optionalNonEmptyString(vault.vaultPath, "activity.timeline.vault.vaultPath") ?? "";
+  const dailyNotePath =
+    optionalNonEmptyString(vault.dailyNotePath, "activity.timeline.vault.dailyNotePath") ?? "{yyyy}-{MM}-{dd}.md";
+  const weeklyNotePath = optionalNonEmptyString(vault.weeklyNotePath, "activity.timeline.vault.weeklyNotePath") ?? "";
+  const noteTemplate = optionalNonEmptyString(vault.noteTemplate, "activity.timeline.vault.noteTemplate") ?? "";
+  const insertUnderHeading =
+    optionalNonEmptyString(vault.insertUnderHeading, "activity.timeline.vault.insertUnderHeading") ?? "";
+
+  if (typeof vault.sectionStrategy !== "undefined" && typeof vault.sectionStrategy !== "string") {
+    throw new TypeError("activity.timeline.vault.sectionStrategy must be a string");
+  }
+  const sectionStrategy = (vault.sectionStrategy as string | undefined) ?? "markers";
+  if (sectionStrategy !== "markers" && sectionStrategy !== "heading") {
+    throw new RangeError('activity.timeline.vault.sectionStrategy must be one of "markers", "heading"');
+  }
+
+  // The documented `vaultPath` contract: absolute on the host platform, or
+  // `~` / `~`-rooted for `expandTildePath`. Everything else — `.`, `vault`,
+  // `../notes`, whitespace — is relative and would resolve against whatever
+  // directory the daemon or CLI happened to launch from, so an enabled vault
+  // rejects it at parse time.
+  const tildeRooted = vaultPath === "~" || vaultPath.startsWith("~/") || vaultPath.startsWith("~\\");
+  if (enabled && (vaultPath.trim().length === 0 || (!tildeRooted && !path.isAbsolute(vaultPath)))) {
+    throw new RangeError(
+      "activity.timeline.vault.vaultPath must be an absolute or `~`-rooted path when activity.timeline.vault.enabled is true; " +
+        `a relative path resolves against the process working directory (got ${JSON.stringify(vaultPath)})`,
+    );
+  }
+  try {
+    validateVaultNoteTemplate(dailyNotePath);
+  } catch (err) {
+    throw new RangeError(`activity.timeline.vault.dailyNotePath: ${(err as Error).message}`);
+  }
+  if (weeklyNotePath.length > 0) {
+    try {
+      validateVaultNoteTemplate(weeklyNotePath);
+    } catch (err) {
+      throw new RangeError(`activity.timeline.vault.weeklyNotePath: ${(err as Error).message}`);
+    }
+  }
+  if (createMissingNotes) {
+    if (noteTemplate.length === 0) {
+      throw new RangeError(
+        "activity.timeline.vault.noteTemplate must name a vault-relative template file when activity.timeline.vault.createMissingNotes is true",
+      );
+    }
+    try {
+      validateVaultNoteTemplate(noteTemplate);
+    } catch (err) {
+      throw new RangeError(`activity.timeline.vault.noteTemplate: ${(err as Error).message}`);
+    }
+  }
+
+  const publish = parseVaultPublishBlock(vault.publish, weeklyNotePath);
+  const wikilinksRaw = vault.wikilinks;
+  const wikilinks =
+    wikilinksRaw === undefined
+      ? { places: false, placesFolder: "Places" }
+      : parseVaultWikilinks(wikilinksRaw);
+  const propertiesRaw = vault.properties;
+  const properties: ActivityTimelineVaultConfig["properties"] =
+    propertiesRaw === undefined ? { mode: "off", prefix: "remnic_" } : parseVaultProperties(propertiesRaw);
+
+  return {
+    enabled,
+    vaultPath,
+    dailyNotePath,
+    weeklyNotePath,
+    createMissingNotes,
+    noteTemplate,
+    sectionStrategy,
+    publish,
+    insertUnderHeading,
+    wikilinks,
+    properties,
+    autoPublish,
   };
 }
 
+function defaultVaultConfig(): ActivityTimelineVaultConfig {
+  return {
+    enabled: false,
+    vaultPath: "",
+    dailyNotePath: "{yyyy}-{MM}-{dd}.md",
+    weeklyNotePath: "",
+    createMissingNotes: false,
+    noteTemplate: "",
+    sectionStrategy: "markers",
+    publish: {
+      timeline: { enabled: true, target: "daily", section: "Timeline" },
+      standup: { enabled: false, target: "daily", section: "Standup" },
+      weekly: { enabled: false, target: "weekly", section: "Weekly Review" },
+      locations: { enabled: false, target: "daily", section: "Locations" },
+    },
+    insertUnderHeading: "",
+    wikilinks: { places: false, placesFolder: "Places" },
+    properties: { mode: "off", prefix: "remnic_" },
+    autoPublish: true,
+  };
+}
+
+function requireBool(value: unknown, key: string, fallback: boolean): boolean {
+  const coerced = coerceBooleanLike(value, key);
+  if (value === undefined) return fallback;
+  if (coerced === undefined) {
+    throw new TypeError(`${key} must be a boolean`);
+  }
+  return coerced;
+}
+
+function optionalNonEmptyString(value: unknown, key: string): string | undefined {
+  if (value === undefined) return undefined;
+  if (typeof value !== "string") {
+    throw new TypeError(`${key} must be a string`);
+  }
+  return value;
+}
+
+function parseVaultPublishBlock(
+  raw: unknown,
+  weeklyNotePath: string,
+): ActivityTimelineVaultConfig["publish"] {
+  const defaults = defaultVaultConfig().publish;
+  if (raw === undefined) return defaults;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline.vault.publish must be an object");
+  }
+  const block = raw as Record<string, unknown>;
+  // Each kind is read at its literal path so the config-contract extractor
+  // can attribute publish.<kind>.<leaf> to real parse sites (§40).
+  const publish = {
+    timeline: parseVaultTarget(block.timeline, "timeline", defaults.timeline, weeklyNotePath),
+    standup: parseVaultTarget(block.standup, "standup", defaults.standup, weeklyNotePath),
+    weekly: parseVaultTarget(block.weekly, "weekly", defaults.weekly, weeklyNotePath),
+    locations: parseVaultTarget(block.locations, "locations", defaults.locations, weeklyNotePath),
+  };
+  for (const targetFile of ["daily", "weekly"] as const) {
+    const sections = (["timeline", "standup", "weekly", "locations"] as const)
+      .filter((kind) => publish[kind].target === targetFile && publish[kind].enabled)
+      .map((kind) => publish[kind].section);
+    const duplicates = sections.filter((section, index) => sections.indexOf(section) !== index);
+    if (duplicates.length > 0) {
+      throw new RangeError(
+        `activity.timeline.vault.publish section names must be unique per target file; duplicate ${targetFile} section(s): ${[...new Set(duplicates)].join(", ")}`,
+      );
+    }
+  }
+  return publish;
+}
+
+function parseVaultTarget(
+  raw: unknown,
+  kind: string,
+  fallback: ActivityTimelineVaultTargetConfig,
+  weeklyNotePath: string,
+): ActivityTimelineVaultTargetConfig {
+  if (raw === undefined) return fallback;
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError(`activity.timeline.vault.publish.${kind} must be an object`);
+  }
+  const entry = raw as Record<string, unknown>;
+  const enabled = requireBool(entry.enabled, `activity.timeline.vault.publish.${kind}.enabled`, fallback.enabled);
+  const target = entry.target === undefined ? fallback.target : entry.target;
+  if (target !== "daily" && target !== "weekly") {
+    throw new RangeError(`activity.timeline.vault.publish.${kind}.target must be one of "daily", "weekly"`);
+  }
+  const section = entry.section === undefined ? fallback.section : entry.section;
+  if (typeof section !== "string" || section.trim().length === 0 || section !== section.trim()) {
+    throw new RangeError(`activity.timeline.vault.publish.${kind}.section must be a non-empty trimmed string`);
+  }
+  // The accepted config domain must equal what the publisher accepts: a name
+  // containing `-->` or a line break passes the trimmed-string check above
+  // but is rejected downstream by `publishVaultNote`, which would turn an
+  // apparently valid config into a runtime failure.
+  if (!validateRegionName(section).ok) {
+    throw new RangeError(
+      `activity.timeline.vault.publish.${kind}.section must not contain a line break or "-->"`,
+    );
+  }
+  // The path is required only by an entry that will actually publish to the
+  // weekly file; a disabled entry must load the same whether its object is
+  // explicit (serialized schema default) or omitted entirely.
+  if (enabled && target === "weekly" && weeklyNotePath.length === 0) {
+    throw new RangeError(
+      `activity.timeline.vault.publish.${kind}.target is "weekly" but activity.timeline.vault.weeklyNotePath is empty; configure weeklyNotePath first`,
+    );
+  }
+  return { enabled, target, section };
+}
+
+function parseVaultWikilinks(raw: unknown): ActivityTimelineVaultConfig["wikilinks"] {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline.vault.wikilinks must be an object");
+  }
+  const block = raw as Record<string, unknown>;
+  const places = requireBool(block.places, "activity.timeline.vault.wikilinks.places", false);
+  const placesFolder =
+    optionalNonEmptyString(block.placesFolder, "activity.timeline.vault.wikilinks.placesFolder") ?? "Places";
+  return { places, placesFolder };
+}
+
+function parseVaultProperties(raw: unknown): ActivityTimelineVaultConfig["properties"] {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new TypeError("activity.timeline.vault.properties must be an object");
+  }
+  const block = raw as Record<string, unknown>;
+  const mode = block.mode === undefined ? "off" : block.mode;
+  if (mode !== "off" && mode !== "frontmatter" && mode !== "dataview-inline") {
+    throw new RangeError(
+      'activity.timeline.vault.properties.mode must be one of "off", "frontmatter", "dataview-inline"',
+    );
+  }
+  const prefix = optionalNonEmptyString(block.prefix, "activity.timeline.vault.properties.prefix") ?? "remnic_";
+  if (prefix.trim().length === 0 || prefix !== prefix.trim()) {
+    throw new RangeError("activity.timeline.vault.properties.prefix must be non-empty and trimmed");
+  }
+  return { mode, prefix };
+}
+
 function parseTimelineJournalConfig(raw: unknown): ActivityTimelineJournalConfig {
   if (raw === undefined) return { enabled: false, source: "file" };
   if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
@@ -265,3 +517,4 @@ function parseTimelineQaConfig(raw: unknown): ActivityTimelineQaConfig {
   }
   return { enabled: enabledValue ?? false, maxRangeDays };
 }
+

package/src/activity/digest.ts

@@ -141,6 +141,27 @@ export function activityDayWindow(date: string, timezone: string): { startUtc: s
   };
 }
 
+/**
+ * The local calendar day (YYYY-MM-DD) an instant falls in for an IANA
+ * timezone — the day key `activityDayWindow` buckets on. Callers that need
+ * "today" for activity artifacts MUST use this rather than the host-local
+ * date, which drifts a day near either timezone's midnight.
+ */
+export function activityDateInTimezone(instant: Date, timezone: string): string {
+  try {
+    const parts = new Intl.DateTimeFormat("en-CA", {
+      timeZone: timezone,
+      year: "numeric",
+      month: "2-digit",
+      day: "2-digit",
+    }).formatToParts(instant);
+    const get = (type: string): string => parts.find((part) => part.type === type)?.value ?? "";
+    return `${get("year")}-${get("month")}-${get("day")}`;
+  } catch {
+    return instant.toISOString().slice(0, 10);
+  }
+}
+
 // ── Rendering ───────────────────────────────────────────────────────────────
 
 function sortedByTime(snapshots: ActivitySnapshot[]): ActivitySnapshot[] {

package/src/activity/index.ts

@@ -27,6 +27,8 @@ export * from "./privacy-status.js";
 export * from "./privacy-gate-resolve.js";
 export * from "./privacy-window.js";
 export * from "./vault-path.js";
+export * from "./vault-publisher.js";
+export * from "./vault-region-pair.js";
 export * from "./vault-publish.js";
 export * from "./vault-status.js";
 export * from "./vault-insert.js";

package/src/activity/runner.ts

@@ -24,6 +24,7 @@
 import { ActivityStore } from "./store.js";
 import { syncActivitySource } from "./pipeline.js";
 import { ActivityHttpSourceClient } from "./source-client.js";
+import { activityDateInTimezone } from "./digest.js";
 import { displayErrorDetail } from "../runtime/better-sqlite.js";
 import type { ActivityConfig, ActivitySourceClient, ActivitySourceConfig } from "./types.js";
 
@@ -87,22 +88,6 @@ export interface ActivitySyncRunOptions {
   reindexSearch?: (signal?: AbortSignal) => Promise<void>;
 }
 
-/** Format a Date as YYYY-MM-DD in an IANA timezone (local calendar day). */
-function localDateInTimezone(instant: Date, timezone: string): string {
-  try {
-    const parts = new Intl.DateTimeFormat("en-CA", {
-      timeZone: timezone,
-      year: "numeric",
-      month: "2-digit",
-      day: "2-digit",
-    }).formatToParts(instant);
-    const get = (type: string): string => parts.find((part) => part.type === type)?.value ?? "";
-    return `${get("year")}-${get("month")}-${get("day")}`;
-  } catch {
-    return instant.toISOString().slice(0, 10);
-  }
-}
-
 /** Previous calendar date via pure date arithmetic (no DST wall-clock drift). */
 function previousIsoDate(date: string): string {
   const parsed = new Date(`${date}T00:00:00Z`);
@@ -117,7 +102,7 @@ function previousIsoDate(date: string): string {
  */
 export function resolveActivitySyncDates(syncDays: number, timezone: string, now: Date): string[] {
   const dates: string[] = [];
-  let cursor = localDateInTimezone(now, timezone);
+  let cursor = activityDateInTimezone(now, timezone);
   for (let count = 0; count < syncDays; count++) {
     dates.unshift(cursor);
     cursor = previousIsoDate(cursor);

package/src/activity/timeline/publish-cli.test.ts

@@ -0,0 +1,169 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import path from "node:path";
+
+import { parseConfig } from "../../config.js";
+import type { PluginConfig } from "../../types.js";
+import { runTimelineCliCommand } from "./query.js";
+
+const DATE = "2026-08-21";
+const RECAP = "- 09:00-10:00 code review (60m)";
+
+interface Capture {
+  out: string;
+  err: string;
+  io: { stdout: { write(chunk: string): unknown }; stderr: { write(chunk: string): unknown } };
+}
+
+function capture(): Capture {
+  const sink: Capture = {
+    out: "",
+    err: "",
+    io: {
+      stdout: {
+        write(chunk: string) {
+          sink.out += chunk;
+          return true;
+        },
+      },
+      stderr: {
+        write(chunk: string) {
+          sink.err += chunk;
+          return true;
+        },
+      },
+    },
+  };
+  return sink;
+}
+
+function makeFixture(): { config: PluginConfig; notePath: string; note: string } {
+  const root = mkdtempSync(path.join(tmpdir(), "remnic-publish-cli-"));
+  const memoryDir = path.join(root, "memory");
+  const vaultPath = path.join(root, "vault");
+  mkdirSync(path.join(memoryDir, "journal"), { recursive: true });
+  mkdirSync(vaultPath, { recursive: true });
+  writeFileSync(path.join(memoryDir, "journal", `${DATE}.md`), `${RECAP}\n`, "utf8");
+
+  const note = [
+    "# Daily",
+    "",
+    "human text that must survive",
+    "",
+    "<!-- remnic:Timeline:start -->",
+    "stale",
+    "<!-- remnic:Timeline:end -->",
+    "",
+  ].join("\n");
+  const notePath = path.join(vaultPath, `${DATE}.md`);
+  writeFileSync(notePath, note, "utf8");
+
+  const config = parseConfig({
+    memoryDir,
+    activity: {
+      timezone: "UTC",
+      timeline: { vault: { enabled: true, vaultPath, dailyNotePath: "{yyyy}-{MM}-{dd}.md" } },
+    },
+  });
+  return { config, notePath, note };
+}
+
+test("the shared timeline runner dispatches publish and writes the managed region", async () => {
+  const { config, notePath } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    // qa stays disabled: publish is not a qa surface and must not be gated by it.
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "--date", DATE],
+    sink.io,
+  );
+
+  assert.equal(code, 0, sink.err);
+  assert.doesNotMatch(sink.err, /unknown command publish/);
+  assert.match(sink.out, /updated=1/);
+  const after = readFileSync(notePath, "utf8");
+  assert.ok(after.includes(RECAP), "the recap is published into the managed region");
+  assert.ok(after.includes("human text that must survive"));
+});
+
+test("the shared timeline runner reports publish as a valid command", async () => {
+  const sink = capture();
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: true, maxRangeDays: 31 }, timelineEnabled: true },
+    ["bogus"],
+    sink.io,
+  );
+  assert.equal(code, 1);
+  assert.match(sink.err, /valid: range, search, publish/);
+});
+
+test("publish without a config refuses instead of throwing", async () => {
+  const sink = capture();
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: true, maxRangeDays: 31 }, timelineEnabled: true },
+    ["publish"],
+    sink.io,
+  );
+  assert.equal(code, 1);
+  assert.match(sink.err, /requires the Remnic config/);
+});
+
+test("--what with only separators is rejected with a validation error", async () => {
+  const { config, notePath, note } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "--date", DATE, "--what", ",,"],
+    sink.io,
+  );
+
+  assert.equal(code, 1);
+  assert.match(sink.err, /--what must name at least one artifact/);
+  assert.equal(readFileSync(notePath, "utf8"), note, "nothing is published");
+});
+
+test("publish rejects query-only flags instead of silently publishing today's note", async () => {
+  const { config, notePath, note } = makeFixture();
+  const sink = capture();
+
+  const code = await runTimelineCliCommand(
+    { cards: null, qa: { enabled: false, maxRangeDays: 31 }, timelineEnabled: true, config },
+    ["publish", "--from", "2026-08-01"],
+    sink.io,
+  );
+
+  assert.equal(code, 1);
+  assert.match(sink.err, /unknown flag --from \(valid: --date, --dry-run, --week, --what\)/);
+  assert.equal(readFileSync(notePath, "utf8"), note, "no note is touched by unsupported syntax");
+});
+
+test("range and search reject publish-only flags instead of ignoring them", async () => {
+  const { config } = makeFixture();
+  const deps = {
+    cards: null,
+    qa: { enabled: true, maxRangeDays: 31 },
+    timelineEnabled: true,
+    config,
+  } as const;
+
+  const rangeSink = capture();
+  const rangeCode = await runTimelineCliCommand(
+    deps,
+    ["range", "--date", DATE, "--from", `${DATE}T00:00:00.000Z`, "--to", `${DATE}T00:00:00.000Z`],
+    rangeSink.io,
+  );
+  assert.equal(rangeCode, 1);
+  assert.match(
+    rangeSink.err,
+    /unknown flag --date \(valid: --categories, --format, --from, --include-distractions, --to\)/,
+  );
+
+  const searchSink = capture();
+  const searchCode = await runTimelineCliCommand(deps, ["search", "--query", "x", "--dry-run"], searchSink.io);
+  assert.equal(searchCode, 1);
+  assert.match(searchSink.err, /unknown flag --dry-run \(valid: --from, --limit, --query, --to\)/);
+});