@dmthepm/commune 0.2.0 → 0.3.0

package/README.md

@@ -99,8 +99,133 @@ That route is a starting point, not an interface. The package ships the mechanis
 - **Markdown twins.** Every published content entry gets its source written beside it, so `/notes/hello/` also answers at `/notes/hello.md`. Entries in the content directories only — a hand-written route under `src/pages/` has no source file to twin. Agents and readers get the same document without scraping HTML.
 - **External links.** Anything off your `site` origin gets `target="_blank" rel="noopener noreferrer"` without you marking it up.
 - **The graph as a library.** `@dmthepm/commune/graph` exports the content loader, the link resolver and the graph builder. The Astro build and the CLI both call it. That is the point: one resolver, not two that drift.
+- **Updates.** A fourth collection, `src/content/updates/`, for the dated entries that say what changed. `Updates.astro` renders the newest few as a card. See [Updates](#updates) below.
+- **Honest dates.** `updated:` in frontmatter wins where you wrote one; where you did not, the date comes from the file's last commit, and from its mtime in a tree with no history. Every entry says which, so a page can show the honest one. See [Dates](#dates) below.
+- **A site-wide last-updated.** The build writes `site.json` beside `backlinks.json`: the newest date across the whole wiki, which entry it belongs to, and the newest commit date whatever the entries claim.
 - **Components and stylesheets.** `@dmthepm/commune/components/*.astro` and `@dmthepm/commune/styles/*.css`, shipped as source. These are the components off my own site rather than a theme system — take them as a starting point, not an API.
 
+## Dates
+
+Two frontmatter fields decide a page's dates, and neither is required:
+
+```markdown
+---
+created: 2025-10-09
+updated: 2026-01-21
+---
+```
+
+Where they are absent the engine reads the repository instead — `updated` is the file's last commit date, `created` its first — from one `git log` walk per build. A tree with no history at all (a tarball, a `COPY` in a Dockerfile, a host with no `git`) falls back to file mtimes rather than failing the build.
+
+Every entry carries `updatedSource`, one of `frontmatter`, `git`, `mtime` or `none`, and `modifiedInGit`, which is the commit date whatever `updated` ended up being. The pair is the point: a note whose `updated:` says January and whose last commit was September changed on a day nobody wrote down, and a page that shows both says so.
+
+### Shallow clones
+
+**A shallow checkout produces no derived dates at all.** In a `--depth 1` clone every file's only commit is the one that was fetched, so every file would date from the day of the build — one confident wrong answer on every entry at once. The engine refuses it rather than reporting it: dates come from frontmatter only, entries without one get `updatedSource: "none"` and no date, and the build prints this once on stderr:
+
+```
+git history is shallow: dates come from frontmatter only. Fetch full history (fetch-depth: 0 / unshallow) to derive dates from commits.
+```
+
+The same refusal applies to file mtimes anywhere inside a repository, and to a file that has never been committed. Inside a checkout an mtime is the moment the file reached that disk — on CI, the moment of the build — so it is the same falsehood wearing a different hat. mtimes are used in one place only: a project that is not in a repository at all.
+
+The fix is to fetch the history. On **GitHub Actions**, `actions/checkout` defaults to depth 1, so set it explicitly:
+
+```yaml
+- uses: actions/checkout@v7
+  with:
+    fetch-depth: 0
+```
+
+On **Cloudflare Workers Builds**, check the build log for the warning above — if it is there, the clone was shallow. Whether Workers Builds exposes a clone-depth setting is not documented here; if it does not, an alternative is to keep `updated:` in frontmatter for anything whose date matters, which wins over history anyway. A build step that runs `git fetch --unshallow` before the build has the same effect wherever the build has network access and credentials for the repository.
+
+**Known gap: renames.** History is read without `--follow`, so a file's derived `created` is the date of the commit that gave it its current path, not the date the writing began. Renaming a note therefore resets its `created` and leaves `updated` correct. `--follow` is per-file by design — it cannot be asked for in the single batched walk this uses — so the fix is a `created:` in frontmatter, which wins over history.
+
+`commune graph query --json` carries all four fields. The build writes the site-wide version to `site.json`:
+
+```json
+{
+  "lastUpdated": "2026-09-02",
+  "lastUpdatedPath": "/about-this-wiki/",
+  "lastUpdatedSource": "frontmatter",
+  "lastModifiedInGit": "2026-09-03",
+  "entries": 12
+}
+```
+
+It is a sibling of `backlinks.json` rather than a key inside it, because every top-level key of `backlinks.json` is a urlPath and its readers walk it as one. Generated, not committed: a date derived from history changes on the same commit that changes it, so a committed copy would be stale exactly when it mattered. Add `public/site.json` to your `.gitignore`.
+
+## Updates
+
+A wiki's front door has to answer "what changed" before it answers anything else. Commune's answer is content: one dated entry per batch of work, in `src/content/updates/`, which the graph treats as a collection like any other — twins, backlinks, `check`, `graph query --collection updates`.
+
+```markdown
+---
+title: "New notes and a working loop"
+date: 2026-09-03
+summary: "Rewrote the home note and added two notes."
+links:
+  - Atomic Notes
+  - /notes/evergreen-notes/
+---
+
+I rewrote the home note. [[Atomic Notes]] and [[Evergreen Notes]] are new.
+```
+
+`links:` is the one place in frontmatter where a bare string is a link. Everywhere else a link has to be spelled `[[like this]]` — a page's own `url:` would otherwise become a self-edge — but `links:` means nothing else, so a title or a site path both resolve and both become real edges. Write it or don't: `[[wikilinks]]` in the body work the same way, and naming a page in both places is still one edge.
+
+Register the collection alongside your notes in `src/content.config.ts`:
+
+```ts
+updates: defineCollection({
+  loader: glob({ pattern: '**/*.{md,mdx}', base: './src/content/updates' }),
+  schema: z.object({
+    title: z.string(),
+    date: z.string(),
+    summary: z.string(),
+    aiGenerated: z.boolean().default(false),
+    links: z.array(z.string()).default([]),
+  }),
+}),
+```
+
+Then render the card wherever it belongs — the home page, an index, a sidebar:
+
+```astro
+---
+import Updates from '@dmthepm/commune/components/Updates.astro';
+---
+<Updates limit={5} heading="Recent updates" />
+```
+
+It reads the collection at build time and emits markup. No fetch, no client script.
+
+### A feed
+
+The engine ships no routes, so it ships no RSS either — a feed is a route, and routes are yours. It is two lines with `@astrojs/rss`, in `src/pages/updates/rss.xml.ts`:
+
+```ts
+import rss from '@astrojs/rss';
+import { getCollection } from 'astro:content';
+
+export async function GET(context) {
+  const updates = await getCollection('updates');
+  return rss({
+    title: 'Updates',
+    description: 'What changed',
+    site: context.site,
+    items: updates
+      .sort((a, b) => b.data.date.localeCompare(a.data.date))
+      .map((update) => ({
+        title: update.data.title,
+        description: update.data.summary,
+        pubDate: new Date(`${update.data.date}T12:00:00Z`),
+        link: `/updates/${update.id}/`,
+      })),
+  });
+}
+```
+
 ## The CLI
 
 `commune` installs as a bin. It reads markdown off disk and answers without an Astro process running, which is what makes it useful while you are still writing.
@@ -108,6 +233,8 @@ That route is a starting point, not an interface. The package ships the mechanis
 ```bash
 commune check
 commune graph query --collection notes --orphans
+commune graph query --recent 7d
+commune update --recent 7d
 commune graph related src/content/notes/hello.md
 echo "a rough dump that mentions World" | commune graph related -
 commune gate
@@ -115,13 +242,18 @@ commune gate
 
 | Verb | What it answers |
 | --- | --- |
-| `graph query` | Every entry with its edges. Filter with `--collection`, `--tag`, `--status`, `--orphans`, `--deadends`. |
+| `graph query` | Every entry with its edges and dates. Filter with `--collection`, `--tag`, `--status`, `--orphans`, `--deadends`, `--recent`. |
 | `graph related <path\|text\|->` | What this connects to. It takes stdin, so you can ask about a draft before it is a note. |
+| `update` | Scaffold a dated update entry from what changed. Prints it; `--write` files it. |
 | `check` | Broken links, duplicate names, ambiguous targets, non-canonical titles. |
 | `gate` | Run after a build, against the built site. |
 
+`--recent` takes `7d`, `2w` or a date, and reports the day it resolved to in the summary — which is what a weekly update job needs, since `7d` means a different day tomorrow. Entries with no date at all are not returned: "unchanged since Monday" and "nobody knows" are different answers.
+
 Every verb takes `--json` and emits one document on stdout with everything else on stderr. The human-readable text is the fallback rendering; the JSON is the contract.
 
+`update` is the only verb that can write, and it only does so when asked: without `--write` the entry goes to stdout, and with it the command refuses to overwrite an update that already exists. `summary` comes out empty — summarizing a week is a judgement, and the CLI has none.
+
 Exit codes report whether the command finished, never what it found — `0` finished, `1` could not finish, `2` invalid invocation. Findings live in the payload. A command that exits non-zero because it *found* something is indistinguishable, to a shell, from one that crashed. `gate` is the one deliberate exception: a gate's entire job is a yes/no and a build has to stop on it, so `gate` exits `1` when the build it checked is wrong.
 
 `commune --help` prints the full surface. `commune --version` prints the installed version, which is the honest way to know what you have.

package/lib/cli/errors.d.ts

@@ -8,11 +8,12 @@
  */
 /** The command ran to completion. Findings, if any, are in the payload. */
 export declare const EXIT_OK = 0;
-/** The command could not finish: bad root, unreadable file, unparseable frontmatter. */
+/** The command could not finish: bad root, unreadable file, unparseable frontmatter,
+ *  or a file it would have written already being there. */
 export declare const EXIT_FAILED = 1;
 /** The command was invoked wrongly: unknown flag, missing value, unknown subcommand. */
 export declare const EXIT_USAGE = 2;
-export type ErrorCode = 'EUSAGE' | 'ENOCONTENT' | 'EPARSE' | 'EINTERNAL';
+export type ErrorCode = 'EUSAGE' | 'ENOCONTENT' | 'EPARSE' | 'EEXISTS' | 'EINTERNAL';
 /** An error the CLI knows how to render on either side of the `--json` switch. */
 export declare class CliError extends Error {
     readonly code: ErrorCode;

package/lib/cli/errors.js

@@ -8,7 +8,8 @@
  */
 /** The command ran to completion. Findings, if any, are in the payload. */
 export const EXIT_OK = 0;
-/** The command could not finish: bad root, unreadable file, unparseable frontmatter. */
+/** The command could not finish: bad root, unreadable file, unparseable frontmatter,
+ *  or a file it would have written already being there. */
 export const EXIT_FAILED = 1;
 /** The command was invoked wrongly: unknown flag, missing value, unknown subcommand. */
 export const EXIT_USAGE = 2;

package/lib/cli/main.js

@@ -15,10 +15,12 @@ import { parseArgs } from 'node:util';
 import { CliError, EXIT_OK, EXIT_USAGE, isParseArgsError, usageError } from "./errors.js";
 import { writeError } from "./render.js";
 import { resolveRoot } from "./root.js";
-import { queryCommand } from "./query.js";
+import { toIsoDay } from "../lib/graph.js";
+import { parseRecent, queryCommand } from "./query.js";
 import { checkCommand } from "./check.js";
 import { gateCommand } from "./gate.js";
 import { relatedCommand } from "./related.js";
+import { updateCommand } from "./update.js";
 import { COMMAND_USAGE, USAGE } from "./usage.js";
 import { readVersion } from "./version.js";
 /** Options understood everywhere, in any position. */
@@ -34,13 +36,19 @@ const QUERY_OPTIONS = {
     status: { type: 'string' },
     orphans: { type: 'boolean', default: false },
     deadends: { type: 'boolean', default: false },
+    recent: { type: 'string' },
+};
+const UPDATE_OPTIONS = {
+    ...GLOBAL,
+    recent: { type: 'string', default: '7d' },
+    write: { type: 'boolean', default: false },
 };
 const GATE_OPTIONS = {
     ...GLOBAL,
     dist: { type: 'string' },
 };
 /** Every route, longest first, so `graph query` is matched before a bare `graph`. */
-const ROUTES = ['graph query', 'graph related', 'check', 'gate'];
+const ROUTES = ['graph query', 'graph related', 'check', 'gate', 'update'];
 /**
  * Find which command this argv names, without committing to its schema yet.
  *
@@ -69,6 +77,26 @@ function route(args) {
     }
     throw usageError(`unknown command: ${positionals.slice(0, 2).join(' ')}`, USAGE);
 }
+/**
+ * Resolve `--recent` to a day, or fail the invocation.
+ *
+ * Resolved here rather than inside a command so an unparseable duration is
+ * exit 2 beside every other bad flag, instead of an empty result set that
+ * looks like an answer.
+ */
+function resolveRecent(value, usage) {
+    if (value === undefined)
+        return undefined;
+    const since = parseRecent(value);
+    if (since === undefined) {
+        throw usageError(`--recent takes a number of days or weeks (7d, 2w) or a date (2026-09-01), not ${value}`, usage);
+    }
+    return since;
+}
+/** Today, as a local calendar day: the date a scaffolded update is filed under. */
+function today() {
+    return toIsoDay(new Date());
+}
 /** Turn `parseArgs`'s typed failures into the CLI's usage error. */
 function parseStrict(args, options, allowPositionals, usage) {
     try {
@@ -90,12 +118,14 @@ async function dispatch(args) {
                 process.stdout.write(`${usage}\n`);
                 return EXIT_OK;
             }
+            const since = resolveRecent(values.recent, usage);
             const filters = {
                 collections: values.collection,
                 tags: values.tag,
                 status: values.status,
                 orphans: values.orphans,
                 deadends: values.deadends,
+                ...(since !== undefined ? { since } : {}),
             };
             return queryCommand(await resolveRoot(values.root), filters, values.json);
         }
@@ -120,6 +150,14 @@ async function dispatch(args) {
             }
             return checkCommand(await resolveRoot(values.root), values.json);
         }
+        case 'update': {
+            const { values } = parseStrict(rest, UPDATE_OPTIONS, false, usage);
+            if (values.help) {
+                process.stdout.write(`${usage}\n`);
+                return EXIT_OK;
+            }
+            return updateCommand(await resolveRoot(values.root), resolveRecent(values.recent, usage), today(), values.write, values.json);
+        }
         case 'gate': {
             const { values } = parseStrict(rest, GATE_OPTIONS, false, usage);
             if (values.help) {

package/lib/cli/query.d.ts

@@ -6,14 +6,33 @@
  * per note. Filters narrow which entries are *returned*; they never change how
  * links resolve, so an entry's degree is the same whether or not you filtered.
  */
-import { type CollectionName } from '../lib/graph.ts';
+import { type CollectionName, type DateSource } from '../lib/graph.ts';
 export interface QueryFilters {
     collections: string[];
     tags: string[];
     status?: string;
     orphans: boolean;
     deadends: boolean;
+    /** Inclusive `yyyy-mm-dd` cutoff from `--recent`. Entries older than it, and
+     *  entries with no date at all, are not returned. */
+    since?: string;
 }
+/**
+ * Resolve `--recent` to the day it means.
+ *
+ * Two spellings, because the two questions are different: `7d` is "since I
+ * last looked", which a weekly update job asks relative to now, and
+ * `2026-09-01` is "since this happened", which a person asks about a date they
+ * remember. `w` is offered because "the last two weeks" is a thing people say;
+ * months are not, since `m` would read as minutes to half the people who type
+ * it.
+ *
+ * Returns `undefined` for anything it cannot parse, so the caller can render
+ * it as the usage error it is rather than silently querying the epoch. The day
+ * is local: `7d` should mean seven of the reader's days, and the dates in
+ * content are calendar days with no timezone of their own.
+ */
+export declare function parseRecent(value: string, today?: Date): string | undefined;
 export interface QueryEntry {
     urlPath: string;
     title: string;
@@ -24,6 +43,11 @@ export interface QueryEntry {
     status: string;
     aliases: string[];
     updated?: string;
+    /** Where `updated` came from: frontmatter, git history, the file's mtime, or nowhere. */
+    updatedSource: DateSource;
+    created?: string;
+    /** The file's last commit date, whatever `updated` ended up being. */
+    modifiedInGit?: string;
     outbound: string[];
     inbound: string[];
 }

package/lib/cli/query.js

@@ -6,9 +6,35 @@
  * per note. Filters narrow which entries are *returned*; they never change how
  * links resolve, so an entry's degree is the same whether or not you filtered.
  */
-import { buildGraph, loadContentEntries, } from "../lib/graph.js";
+import { buildGraph, loadContentEntries, toIsoDay, } from "../lib/graph.js";
 import { SCHEMA, writeJson, writeLines } from "./render.js";
 import { EXIT_OK } from "./errors.js";
+/**
+ * Resolve `--recent` to the day it means.
+ *
+ * Two spellings, because the two questions are different: `7d` is "since I
+ * last looked", which a weekly update job asks relative to now, and
+ * `2026-09-01` is "since this happened", which a person asks about a date they
+ * remember. `w` is offered because "the last two weeks" is a thing people say;
+ * months are not, since `m` would read as minutes to half the people who type
+ * it.
+ *
+ * Returns `undefined` for anything it cannot parse, so the caller can render
+ * it as the usage error it is rather than silently querying the epoch. The day
+ * is local: `7d` should mean seven of the reader's days, and the dates in
+ * content are calendar days with no timezone of their own.
+ */
+export function parseRecent(value, today = new Date()) {
+    if (/^\d{4}-\d{2}-\d{2}$/.test(value))
+        return value;
+    const duration = /^(\d+)([dw])$/.exec(value);
+    if (!duration)
+        return undefined;
+    const days = Number(duration[1]) * (duration[2] === 'w' ? 7 : 1);
+    const cutoff = new Date(today);
+    cutoff.setDate(cutoff.getDate() - days);
+    return toIsoDay(cutoff);
+}
 /** Project one loaded entry against the built graph. */
 function toQueryEntry(entry, graph) {
     const node = graph.nodes[entry.urlPath];
@@ -22,6 +48,9 @@ function toQueryEntry(entry, graph) {
         status: entry.status,
         aliases: entry.aliases,
         ...(entry.updated ? { updated: entry.updated } : {}),
+        updatedSource: entry.updatedSource,
+        ...(entry.created ? { created: entry.created } : {}),
+        ...(entry.modifiedInGit ? { modifiedInGit: entry.modifiedInGit } : {}),
         outbound: node.outbound,
         inbound: node.inbound,
     };
@@ -60,6 +89,11 @@ function matches(entry, filters) {
         return false;
     if (filters.deadends && !isDeadend(entry))
         return false;
+    // An entry with no date is not "unchanged since the cutoff", it is unknown —
+    // and a list of what changed this week is worth less with unknowns in it.
+    if (filters.since !== undefined && !(entry.updated && entry.updated >= filters.since)) {
+        return false;
+    }
     return true;
 }
 /**
@@ -74,19 +108,23 @@ function matches(entry, filters) {
  * Free to compute: `outbound` and `inbound` are already materialized on every
  * node by the time a query can be filtered at all.
  */
-function summarize(results) {
+function summarize(results, since) {
     return {
         entries: results.length,
         edges: results.reduce((total, entry) => total + entry.outbound.length, 0),
         orphans: results.filter(isOrphan).length,
         deadends: results.filter(isDeadend).length,
+        // The resolved cutoff, not the string the caller typed: `--recent 7d`
+        // means a different day tomorrow, and a job that records what it asked
+        // needs the day, not the duration.
+        ...(since !== undefined ? { since } : {}),
     };
 }
 export async function queryCommand(root, filters, json) {
     const entries = await loadContentEntries({ root });
     const graph = buildGraph(entries);
     const results = entries.map((entry) => toQueryEntry(entry, graph)).filter((entry) => matches(entry, filters));
-    const summary = summarize(results);
+    const summary = summarize(results, filters.since);
     if (json) {
         // `count` predates `summary` and stays as its alias: the field shipped in
         // the contract #10 and #19 are written against, and removing it would be
@@ -97,7 +135,9 @@ export async function queryCommand(root, filters, json) {
     writeLines([
         ...results.map((entry) => `${entry.urlPath}\t${entry.title}\t${entry.collection}\t${entry.status}\t` +
             `→${entry.outbound.length} ←${entry.inbound.length}`),
-        `${summary.entries} entries, ${summary.edges} edges, ${summary.orphans} orphans, ${summary.deadends} dead ends`,
+        `${summary.entries} entries, ${summary.edges} edges, ${summary.orphans} orphans, ` +
+            `${summary.deadends} dead ends` +
+            (summary.since !== undefined ? `, updated since ${summary.since}` : ''),
     ]);
     return EXIT_OK;
 }

package/lib/cli/update.d.ts

@@ -0,0 +1,16 @@
+/**
+ * `commune update` — a dated update entry, scaffolded from what changed.
+ *
+ * The one verb here that can write. Everything else in this CLI answers
+ * questions about a content tree; this one drafts a file into it, so the
+ * writing is opt-in: without `--write` it prints the entry on stdout, which is
+ * both a preview and a redirect away from a file of your choosing. With
+ * `--write` it refuses to overwrite an existing entry — a scaffold that
+ * clobbers a day's writing is worse than no scaffold.
+ *
+ * What it produces is a draft and says so: `summary` is empty, because a
+ * one-line summary of a week is a judgement and this command has no taste.
+ * The parts it can be trusted with — which pages moved, what they are called,
+ * what date it is — are filled in.
+ */
+export declare function updateCommand(root: string, since: string, day: string, write: boolean, json: boolean): Promise<number>;

package/lib/cli/update.js

@@ -0,0 +1,91 @@
+/**
+ * `commune update` — a dated update entry, scaffolded from what changed.
+ *
+ * The one verb here that can write. Everything else in this CLI answers
+ * questions about a content tree; this one drafts a file into it, so the
+ * writing is opt-in: without `--write` it prints the entry on stdout, which is
+ * both a preview and a redirect away from a file of your choosing. With
+ * `--write` it refuses to overwrite an existing entry — a scaffold that
+ * clobbers a day's writing is worse than no scaffold.
+ *
+ * What it produces is a draft and says so: `summary` is empty, because a
+ * one-line summary of a week is a judgement and this command has no taste.
+ * The parts it can be trusted with — which pages moved, what they are called,
+ * what date it is — are filled in.
+ */
+import { mkdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { CONTENT_DIRS, loadContentEntries } from "../lib/graph.js";
+import { SCHEMA, writeJson, writeLines } from "./render.js";
+import { EXIT_OK, failure } from "./errors.js";
+/**
+ * The entry, as markdown.
+ *
+ * `links:` carries the urlPaths and the body carries the titles, which is the
+ * same edge written twice on purpose: the frontmatter is what the graph reads
+ * without rendering anything, and the prose is what a reader reads. They
+ * deduplicate into one edge, so writing both costs nothing.
+ */
+function scaffold(day, changed) {
+    const lines = [
+        '---',
+        `title: "Updates for ${day}"`,
+        `date: ${day}`,
+        'summary: ""',
+        'aiGenerated: false',
+    ];
+    if (changed.length) {
+        lines.push('links:', ...changed.map((entry) => `  - ${entry.urlPath}`));
+    }
+    lines.push('---', '');
+    lines.push(...(changed.length
+        ? changed.map((entry) => `- [[${entry.title}]]${entry.summary ? ` — ${entry.summary}` : ''}`)
+        : ['Nothing changed in this window.']));
+    return `${lines.join('\n')}\n`;
+}
+async function exists(filePath) {
+    try {
+        await stat(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function updateCommand(root, since, day, write, json) {
+    const entries = await loadContentEntries({ root });
+    // Updates are excluded from their own roll-up: an update that lists last
+    // week's update says nothing about the wiki.
+    const changed = entries.filter((entry) => entry.collection !== 'updates' && entry.updated !== undefined && entry.updated >= since);
+    const file = `${CONTENT_DIRS.updates}/${day}.md`;
+    const content = scaffold(day, changed);
+    if (write) {
+        const destination = path.join(root, file);
+        if (await exists(destination)) {
+            throw failure('EEXISTS', `${file} already exists. Edit it, or delete it first — this command does not overwrite an update that has been written.`);
+        }
+        await mkdir(path.dirname(destination), { recursive: true });
+        await writeFile(destination, content);
+    }
+    if (json) {
+        writeJson({
+            schema: SCHEMA,
+            root,
+            since,
+            date: day,
+            file,
+            written: write,
+            entries: changed.map((entry) => ({
+                urlPath: entry.urlPath,
+                title: entry.title,
+                collection: entry.collection,
+                updated: entry.updated,
+                updatedSource: entry.updatedSource,
+            })),
+            content,
+        });
+        return EXIT_OK;
+    }
+    writeLines(write ? [`wrote ${file} — ${changed.length} entries since ${since}`] : [content.trimEnd()]);
+    return EXIT_OK;
+}

package/lib/cli/usage.d.ts

@@ -1,3 +1,3 @@
 /** Usage text. Hand-written: `parseArgs` generates none, which is its one real cost. */
-export declare const USAGE = "commune \u2014 query the content graph without an Astro process\n\nUsage:\n  commune [--root <dir>] graph query   [filters] [--json]\n  commune [--root <dir>] graph related <path|text|-> [--json]\n  commune [--root <dir>] check         [--json]\n  commune [--root <dir>] gate          [--dist <dir>] [--json]\n  commune --version\n\nGlobal options:\n  --root <dir>   Project root: the directory containing src/content. Default: cwd.\n  --json         Emit one JSON document on stdout. Everything else goes to stderr.\n  --help         Show this text.\n  --version      Print the version of the installed package and exit.\n\ngraph query filters (any-of within a flag, all-of across flags):\n  --collection <notes|research|pages>   Repeatable.\n  --tag <tag>                           Repeatable.\n  --status <status>\n  --orphans                             Zero inbound and zero outbound.\n  --deadends                            Zero outbound.\n\ngate options:\n  --dist <dir>   The built site to check, relative to --root. Default: dist.\n\nExit codes:\n  0  finished, findings or not\n  1  could not finish\n  2  invalid invocation\n\n  gate is the one exception, and the only verb whose exit code encodes a\n  finding: it exits 1 when the build it checked is wrong. That is what a gate\n  is for \u2014 a build stops on a non-zero exit \u2014 so gate cannot report a finding\n  the way every other verb does, in the payload with exit 0.";
+export declare const USAGE = "commune \u2014 query the content graph without an Astro process\n\nUsage:\n  commune [--root <dir>] graph query   [filters] [--json]\n  commune [--root <dir>] graph related <path|text|-> [--json]\n  commune [--root <dir>] update        [--recent <duration|date>] [--write] [--json]\n  commune [--root <dir>] check         [--json]\n  commune [--root <dir>] gate          [--dist <dir>] [--json]\n  commune --version\n\nGlobal options:\n  --root <dir>   Project root: the directory containing src/content. Default: cwd.\n  --json         Emit one JSON document on stdout. Everything else goes to stderr.\n  --help         Show this text.\n  --version      Print the version of the installed package and exit.\n\ngraph query filters (any-of within a flag, all-of across flags):\n  --collection <notes|research|pages|updates>   Repeatable.\n  --tag <tag>                                   Repeatable.\n  --status <status>\n  --orphans                                     Zero inbound and zero outbound.\n  --deadends                                    Zero outbound.\n  --recent <7d|2w|2026-09-01>                   Updated on or since then. Entries\n                                                with no date are not returned.\n\nupdate options:\n  --recent <7d|2w|2026-09-01>   What to roll up. Default: 7d.\n  --write                       Write src/content/updates/<today>.md. Without it,\n                                the entry is printed on stdout. Never overwrites.\n\ngate options:\n  --dist <dir>   The built site to check, relative to --root. Default: dist.\n\nExit codes:\n  0  finished, findings or not\n  1  could not finish\n  2  invalid invocation\n\n  gate is the one exception, and the only verb whose exit code encodes a\n  finding: it exits 1 when the build it checked is wrong. That is what a gate\n  is for \u2014 a build stops on a non-zero exit \u2014 so gate cannot report a finding\n  the way every other verb does, in the payload with exit 0.";
 export declare const COMMAND_USAGE: Record<string, string>;

package/lib/cli/usage.js

@@ -4,6 +4,7 @@ export const USAGE = `commune — query the content graph without an Astro proce
 Usage:
   commune [--root <dir>] graph query   [filters] [--json]
   commune [--root <dir>] graph related <path|text|-> [--json]
+  commune [--root <dir>] update        [--recent <duration|date>] [--write] [--json]
   commune [--root <dir>] check         [--json]
   commune [--root <dir>] gate          [--dist <dir>] [--json]
   commune --version
@@ -15,11 +16,18 @@ Global options:
   --version      Print the version of the installed package and exit.
 
 graph query filters (any-of within a flag, all-of across flags):
-  --collection <notes|research|pages>   Repeatable.
-  --tag <tag>                           Repeatable.
+  --collection <notes|research|pages|updates>   Repeatable.
+  --tag <tag>                                   Repeatable.
   --status <status>
-  --orphans                             Zero inbound and zero outbound.
-  --deadends                            Zero outbound.
+  --orphans                                     Zero inbound and zero outbound.
+  --deadends                                    Zero outbound.
+  --recent <7d|2w|2026-09-01>                   Updated on or since then. Entries
+                                                with no date are not returned.
+
+update options:
+  --recent <7d|2w|2026-09-01>   What to roll up. Default: 7d.
+  --write                       Write src/content/updates/<today>.md. Without it,
+                                the entry is printed on stdout. Never overwrites.
 
 gate options:
   --dist <dir>   The built site to check, relative to --root. Default: dist.
@@ -34,8 +42,14 @@ Exit codes:
   is for — a build stops on a non-zero exit — so gate cannot report a finding
   the way every other verb does, in the payload with exit 0.`;
 export const COMMAND_USAGE = {
-    'graph query': 'Usage: commune [--root <dir>] graph query [--collection <c>]... [--tag <t>]... [--status <s>] [--orphans] [--deadends] [--json]',
+    'graph query': 'Usage: commune [--root <dir>] graph query [--collection <c>]... [--tag <t>]... [--status <s>] [--orphans] [--deadends] [--recent <duration|date>] [--json]',
     'graph related': 'Usage: commune [--root <dir>] graph related <path|text|-> [--json]',
+    update: `Usage: commune [--root <dir>] update [--recent <duration|date>] [--write] [--json]
+
+Scaffold a dated update entry from the pages that changed. The draft is
+printed on stdout unless --write is given, and --write refuses to overwrite an
+update that already exists. \`summary\` is left empty on purpose: summarizing a
+week is a judgement, and this command has none.`,
     check: 'Usage: commune [--root <dir>] check [--json]',
     gate: `Usage: commune [--root <dir>] gate [--dist <dir>] [--json]