@dmthepm/commune 0.2.0 → 0.4.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,20 +233,34 @@ 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 render src/content/notes/hello.md
+echo '[[World]]' | commune render -
 commune gate
 ```
 
 | Verb | What it answers |
 | --- | --- |
-| `graph query` | Every entry with its edges. Filter with `--collection`, `--tag`, `--status`, `--orphans`, `--deadends`. |
-| `graph related <path\|text\|->` | What this connects to. It takes stdin, so you can ask about a draft before it is a note. |
+| `graph query` | Every entry with its edges and dates. Filter with `--collection`, `--tag`, `--status`, `--orphans`, `--deadends`, `--unreferenced`, `--recent`. |
+| `graph related <path\|text\|->` | What this connects to. It takes stdin, so you can ask about a draft before it is a note. Titles are matched across whitespace and case, so a dictated "noon tide" still finds `Noontide`. |
+| `render <path\|->` | The markdown as HTML, through the site's own pipeline: WikiLinks resolved, external links marked. Takes stdin, so you can see a draft before it is a page. |
+| `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. |
 
+`--orphans` and `--unreferenced` are different questions and it is worth knowing which one you are asking. An orphan is *isolated* — nothing links to it and it links nowhere — which on a wiki where most notes link out returns almost nothing. `--unreferenced` is zero inbound with any outbound: the note you wrote, cited three others from, and never linked back to from anywhere. `updates` entries are left out of it, since a dated changelog entry is expected to have nothing pointing at it; `--collection updates` is how you say you meant them.
+
+`--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.
 
+`render` is the site's own markdown processor with no Astro process around it — the same `communeMarkdown()` the config hands to `markdown.processor`, so the HTML is the page's HTML rather than a lookalike. It needs the site's origin to decide which links are external: `--site` says it, and without one the Astro config is read for a `site` declaration, falling back to `https://example.com` with a line on stderr saying so. `--json` adds the document's links and the names among them that resolve to nothing, which the HTML cannot tell you — an unresolved WikiLink renders as plain text, exactly as it does on the site.
+
+`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/check.js

@@ -11,7 +11,7 @@
  * collapse. Frontmatter drift is a follow-up.
  */
 import { buildGraph, checkEntries, loadContentEntries, } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./render.js";
+import { SCHEMA, writeJson, writeLines } from "./output.js";
 import { EXIT_OK } from "./errors.js";
 const RULES = [
     'broken-link',

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/gate.js

@@ -30,7 +30,7 @@ import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { findNoncanonicalTitles, loadContentEntries, stripCode, } from "../lib/graph.js";
 import { EXIT_FAILED, EXIT_OK, failure } from "./errors.js";
-import { SCHEMA, writeJson } from "./render.js";
+import { SCHEMA, writeJson } from "./output.js";
 const WIKILINK = /\[\[([^\]|]+)(?:\|[^\]]+)?\]\]/g;
 async function readSearchIndex(root) {
     // The public artifact, not the built one: `public/backlinks.json` is what

package/lib/cli/main.js

@@ -13,12 +13,14 @@
  */
 import { parseArgs } from 'node:util';
 import { CliError, EXIT_OK, EXIT_USAGE, isParseArgsError, usageError } from "./errors.js";
-import { writeError } from "./render.js";
+import { writeError } from "./output.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,24 @@ const QUERY_OPTIONS = {
     status: { type: 'string' },
     orphans: { type: 'boolean', default: false },
     deadends: { type: 'boolean', default: false },
+    unreferenced: { type: 'boolean', default: false },
+    recent: { type: 'string' },
+};
+const UPDATE_OPTIONS = {
+    ...GLOBAL,
+    recent: { type: 'string', default: '7d' },
+    write: { type: 'boolean', default: false },
+};
+const RENDER_OPTIONS = {
+    ...GLOBAL,
+    site: { type: 'string' },
 };
 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', 'render'];
 /**
  * Find which command this argv names, without committing to its schema yet.
  *
@@ -69,6 +82,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 +123,15 @@ 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,
+                unreferenced: values.unreferenced,
+                ...(since !== undefined ? { since } : {}),
             };
             return queryCommand(await resolveRoot(values.root), filters, values.json);
         }
@@ -112,6 +148,34 @@ async function dispatch(args) {
             }
             return relatedCommand(await resolveRoot(values.root), positionals[0], values.json);
         }
+        case 'render': {
+            const { values, positionals } = parseStrict(rest, RENDER_OPTIONS, true, usage);
+            if (values.help) {
+                process.stdout.write(`${usage}\n`);
+                return EXIT_OK;
+            }
+            if (positionals.length !== 1) {
+                throw usageError(positionals.length
+                    ? `render takes one argument, got ${positionals.length}: ${positionals.join(' ')}. A path containing spaces has to be quoted.`
+                    : 'render needs a path to a markdown file, or - for stdin', usage);
+            }
+            const site = values.site;
+            // Checked here rather than where it is used, so a typo is exit 2
+            // beside every other bad flag instead of an internal error from the
+            // URL parse three calls deeper.
+            if (site !== undefined && !URL.canParse(site)) {
+                throw usageError(`--site takes an origin like https://example.com, not ${site}`, usage);
+            }
+            // Imported here rather than at the top of the file: `render` is the
+            // one verb that needs the markdown pipeline, and
+            // `@astrojs/markdown-remark` is a peer dependency. A static import
+            // would make every other verb load it — a startup cost on every
+            // `check`, and an outright failure in a project that has the CLI but
+            // not the renderer, which is the opposite of the promise the rest of
+            // this CLI makes about running without Astro.
+            const { renderCommand } = await import("./render.js");
+            return renderCommand(await resolveRoot(values.root), positionals[0], site, values.json);
+        }
         case 'check': {
             const { values } = parseStrict(rest, GLOBAL, false, usage);
             if (values.help) {
@@ -120,6 +184,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/output.d.ts

@@ -0,0 +1,20 @@
+/**
+ * How a command's result reaches the caller.
+ *
+ * One rule, and everything else follows from it: in `--json` mode stdout holds
+ * exactly one JSON document and nothing else. Progress, warnings and errors go
+ * to stderr, so `commune check --json > findings.json` yields a parseable file
+ * even on the run that fails.
+ */
+import type { CliError } from './errors.ts';
+/** Every payload carries the contract version, so #10's skills can pin it. */
+export declare const SCHEMA = 1;
+export declare function writeJson(payload: unknown): void;
+export declare function writeLines(lines: string[]): void;
+/**
+ * Render a failure, on stderr, in whichever mode the caller asked for.
+ *
+ * `json` is read from the raw argv rather than the parsed options, because the
+ * errors most worth rendering as JSON are the ones thrown while parsing.
+ */
+export declare function writeError(error: CliError, json: boolean): void;

package/lib/cli/output.js

@@ -0,0 +1,32 @@
+/**
+ * How a command's result reaches the caller.
+ *
+ * One rule, and everything else follows from it: in `--json` mode stdout holds
+ * exactly one JSON document and nothing else. Progress, warnings and errors go
+ * to stderr, so `commune check --json > findings.json` yields a parseable file
+ * even on the run that fails.
+ */
+/** Every payload carries the contract version, so #10's skills can pin it. */
+export const SCHEMA = 1;
+export function writeJson(payload) {
+    process.stdout.write(JSON.stringify(payload, null, 2) + '\n');
+}
+export function writeLines(lines) {
+    if (lines.length)
+        process.stdout.write(lines.join('\n') + '\n');
+}
+/**
+ * Render a failure, on stderr, in whichever mode the caller asked for.
+ *
+ * `json` is read from the raw argv rather than the parsed options, because the
+ * errors most worth rendering as JSON are the ones thrown while parsing.
+ */
+export function writeError(error, json) {
+    if (json) {
+        process.stderr.write(JSON.stringify({ error: { code: error.code, message: error.message } }, null, 2) + '\n');
+        return;
+    }
+    process.stderr.write(`commune: ${error.message}\n`);
+    if (error.detail)
+        process.stderr.write(`${error.detail}\n`);
+}

package/lib/cli/query.d.ts

@@ -6,14 +6,34 @@
  * 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;
+    unreferenced: 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 +44,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 { SCHEMA, writeJson, writeLines } from "./render.js";
+import { buildGraph, loadContentEntries, toIsoDay, } from "../lib/graph.js";
+import { SCHEMA, writeJson, writeLines } from "./output.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,
     };
@@ -42,6 +71,19 @@ function isOrphan(entry) {
 function isDeadend(entry) {
     return entry.outbound.length === 0;
 }
+/**
+ * Nobody links here. Whether it links *out* is a separate question.
+ *
+ * The other half of the orphan split, and the half the connect step actually
+ * wants: a note that cites three others but that nothing cites back is not
+ * isolated, it is unplaced — and a wiki accumulates those silently, because
+ * writing a note is the moment you think about its outbound links and never
+ * about its inbound ones. `--orphans` returns 0 on a vault like that, which is
+ * the true answer to a different question.
+ */
+function isUnreferenced(entry) {
+    return entry.inbound.length === 0;
+}
 /**
  * Repeated values of one flag widen the match; different flags narrow it.
  *
@@ -60,6 +102,22 @@ function matches(entry, filters) {
         return false;
     if (filters.deadends && !isDeadend(entry))
         return false;
+    if (filters.unreferenced) {
+        if (!isUnreferenced(entry))
+            return false;
+        // A dated changelog entry is *expected* to have nothing pointing at it,
+        // so leaving `updates` in would bury the notes this filter exists to
+        // surface under one row per week. Asking for the collection by name is
+        // the way to say you meant it — and it is the only way, so the exclusion
+        // can never quietly hide an answer somebody asked for.
+        if (entry.collection === 'updates' && !filters.collections.includes('updates'))
+            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 +132,29 @@ 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,
+        // Counted over what came back, like every other number here, so it can
+        // never contradict `entries` beside it. Note that on an *unfiltered*
+        // query this includes `updates` entries — the exclusion belongs to
+        // `--unreferenced` the filter, not to "has nothing pointing at it" the
+        // property.
+        unreferenced: results.filter(isUnreferenced).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 +165,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.unreferenced} unreferenced` +
+            (summary.since !== undefined ? `, updated since ${summary.since}` : ''),
     ]);
     return EXIT_OK;
 }

package/lib/cli/related.d.ts

@@ -12,6 +12,9 @@
  *
  * Fuzzy and semantic similarity are out of scope on purpose. They are product
  * direction, not a build decision, and inventing a ranking here would freeze it
- * into the contract before anyone chose it.
+ * into the contract before anyone chose it. What #69 added is not similarity:
+ * whitespace inside a name is not information, so a dictated "noon tide" and a
+ * written `Noontide` are the same name spelled two ways, and matching them is
+ * still an exact match — just of the right string.
  */
 export declare function relatedCommand(root: string, input: string, json: boolean): Promise<number>;