@dmthepm/commune 0.3.0 → 0.5.0

package/README.md

@@ -237,27 +237,48 @@ 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 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. |
+| `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.
 
+## Author with the skills
+
+The loop above the CLI ships as four agent skills, in `skills/`, installed straight from this repository rather than from npm:
+
+```bash
+npx skills add dmthepm/commune-wiki
+```
+
+They install for Claude Code and Codex, globally or into one project, and they drive the `commune` your wiki already has — `node_modules/.bin/commune`, called by path, never downloaded — so the CLI a skill runs is the one your site builds with. They need 0.4.0 or newer, they check that first, and they install nothing themselves.
+
+The loop is one dump, four files and two places it stops for you. `commune-dump` takes a dictated or pasted dump, writes it verbatim to `dumps/<date>-<slug>.md`, and asks the graph what it already touches — what it mentions, which of the target's links a rewrite would put at risk, which subjects have no note yet — into `dumps/<slug>.connect.md`. `commune-write` reads your `WRITING.md`, asks one short round of questions whose answers each change a file, stops while you answer them in `dumps/<slug>.answers.md`, then drafts into the real note and renders the original and the draft side by side as `dumps/<slug>.review.html`. `commune-ship` diffs `check` against the baseline, files the `updates` entry, builds, gates, greps `dist/` for every new href, commits and opens the PR — and never merges, because the last word is yours. `commune-setup` runs once per wiki and writes the `WRITING.md` the other three obey.
+
+Status, honestly: the skills, their test and the `WRITING.md` template are here. The loop has been run once end to end by hand, before it was skills; it has not yet been run as skills on a real wiki. That run is [#10](https://github.com/dmthepm/commune-wiki/issues/10), and this paragraph changes when it lands.
+
 ## What it is not
 
 It is not a note-taking app and it is not trying to replace one. I write in Obsidian; Commune is what turns the vault into a site. There is no editor here, no sync, no account, no server. The graph is computed from files on disk at build time, and the files are yours whether or not you ever run this.
@@ -266,7 +287,7 @@ It is not a note-taking app and it is not trying to replace one. I write in Obsi
 
 Commune is the engine under a larger idea: own your canon. The wiki is one output surface, not the product. What I am building toward is an authoring loop — dictate a dump, have agents find what it already connects to, grill it, draft it, ship it — where the graph is what makes connection-finding possible *before* a draft exists. That is why the graph is a queryable library with a CLI on top instead of a build artifact, and why `graph related` reads stdin.
 
-None of that loop is in this package. `pnpm add @dmthepm/commune` gives you the engine and the CLI above, and nothing else. The authoring skills and the email destination are tracked in [the issues](https://github.com/dmthepm/commune-wiki/issues); when they ship, this section shrinks and the one above it grows.
+The authoring half of that loop is here now, as the four skills above; `pnpm add @dmthepm/commune` still gives you the engine and the CLI and nothing else, which is what those skills drive. What is left — the email destination, the weekly intake from GitHub activity — is tracked in [the issues](https://github.com/dmthepm/commune-wiki/issues).
 
 ## Deploy
 

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/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,7 +13,7 @@
  */
 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 { toIsoDay } from "../lib/graph.js";
 import { parseRecent, queryCommand } from "./query.js";
@@ -36,6 +36,7 @@ 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 = {
@@ -43,12 +44,16 @@ const UPDATE_OPTIONS = {
     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', 'update'];
+const ROUTES = ['graph query', 'graph related', 'check', 'gate', 'update', 'render'];
 /**
  * Find which command this argv names, without committing to its schema yet.
  *
@@ -125,6 +130,7 @@ async function dispatch(args) {
                 status: values.status,
                 orphans: values.orphans,
                 deadends: values.deadends,
+                unreferenced: values.unreferenced,
                 ...(since !== undefined ? { since } : {}),
             };
             return queryCommand(await resolveRoot(values.root), filters, values.json);
@@ -142,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) {

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

@@ -13,6 +13,7 @@ export interface QueryFilters {
     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;

package/lib/cli/query.js

@@ -7,7 +7,7 @@
  * links resolve, so an entry's degree is the same whether or not you filtered.
  */
 import { buildGraph, loadContentEntries, toIsoDay, } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./render.js";
+import { SCHEMA, writeJson, writeLines } from "./output.js";
 import { EXIT_OK } from "./errors.js";
 /**
  * Resolve `--recent` to the day it means.
@@ -71,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.
  *
@@ -89,6 +102,17 @@ 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)) {
@@ -114,6 +138,12 @@ function summarize(results, since) {
         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.
@@ -136,7 +166,7 @@ export async function queryCommand(root, filters, json) {
         ...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.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>;

package/lib/cli/related.js

@@ -12,15 +12,19 @@
  *
  * 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.
  */
-import { readFile, stat } from 'node:fs/promises';
-import path from 'node:path';
-import matter from 'gray-matter';
 import { buildGraph, buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, stripCode, } from "../lib/graph.js";
-import { SCHEMA, writeJson, writeLines } from "./render.js";
-import { EXIT_OK, failure } from "./errors.js";
-/** Shortest name worth matching. Below this, a mention is noise. */
+import { SCHEMA, writeJson, writeLines } from "./output.js";
+import { EXIT_OK } from "./errors.js";
+import { readSource } from "./source.js";
+/**
+ * Shortest name worth matching, measured after normalisation. Below this, a
+ * mention is noise — `B` would make every capital B a connection.
+ */
 const MIN_MENTION_LENGTH = 3;
 function toReference(entry) {
     return {
@@ -30,78 +34,73 @@ function toReference(entry) {
         file: entry.file,
     };
 }
+const WHITESPACE = /\s/;
+const WORD = /\w/;
 /**
- * Work out whether the positional is a path, stdin, or literal prose.
+ * Reduce a string to the form mentions are matched in.
+ *
+ * Whitespace is removed rather than collapsed, which is what makes "noon tide"
+ * and `Noontide` the same string — the distortion dictation reliably produces
+ * (#69), and the reason a whole-word matcher over the raw text missed the
+ * titles it most needed to find. The offsets are what keep the answer honest:
+ * the word boundaries removed *inside* a name are still there in the original
+ * at its *edges*, so `Cake` can be found in "pan cake" and refused in
+ * "pancake".
  *
- * A path is tried against the root before the cwd, because the root is the
- * vault being asked about and the cwd is wherever the operator happens to be
- * standing. `-` is stdin, which is how a draft that is not a file yet gets
- * asked "what does this connect to".
+ * Built one output character at a time because `toLowerCase()` is not always
+ * length-preserving (`'İ'.toLowerCase()` is two code units), and one offset per
+ * emitted unit is what keeps the map exact for any input.
  */
-async function readSource(input, root) {
-    if (input === '-') {
-        const text = await readStdin();
-        const { content, data } = matter(text);
-        return { kind: 'stdin', text: content, frontmatter: data };
-    }
-    const candidates = path.isAbsolute(input)
-        ? [input]
-        : [path.join(root, input), path.resolve(input)];
-    for (const candidate of candidates) {
-        if (!(await isFile(candidate)))
+function normalize(text) {
+    let normalized = '';
+    const offsets = [];
+    for (let index = 0; index < text.length; index += 1) {
+        const char = text[index];
+        if (WHITESPACE.test(char))
             continue;
-        let source;
-        try {
-            source = await readFile(candidate, 'utf8');
-        }
-        catch (error) {
-            throw failure('EPARSE', `cannot read ${candidate}: ${error.message}`);
+        const lowered = char.toLowerCase();
+        for (let unit = 0; unit < lowered.length; unit += 1) {
+            normalized += lowered[unit];
+            offsets.push(index);
         }
-        let parsed;
-        try {
-            parsed = matter(source);
-        }
-        catch (error) {
-            throw failure('EPARSE', `cannot parse frontmatter in ${candidate}: ${error.message}`);
-        }
-        const relative = path.relative(root, candidate).split(path.sep).join('/');
-        return {
-            kind: 'file',
-            file: relative,
-            text: parsed.content,
-            frontmatter: parsed.data,
-        };
     }
-    return { kind: 'text', text: input, frontmatter: {} };
-}
-async function isFile(candidate) {
-    try {
-        return (await stat(candidate)).isFile();
-    }
-    catch {
-        return false;
-    }
-}
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(chunk);
-    return Buffer.concat(chunks).toString('utf8');
-}
-/** Escape a title so it can be matched literally: real titles contain `,`, `'`, `(`. */
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    return { text: normalized, offsets };
 }
 /**
- * Count whole-word occurrences of `name` in `text`.
+ * Find every whole-word occurrence of `name`, across whitespace and case.
  *
- * Lookarounds rather than `\b`, because `\b` is defined relative to the
- * character next to it: a title ending in `?` or `)` puts a non-word character
- * where `\b` expects a word one, and the match silently stops happening.
+ * The search runs on the normalised text and the boundary check on the original,
+ * because the two questions want different strings: "is this the same name"
+ * ignores the spaces, "is this a whole word" is only about the characters
+ * outside it. A character index either side is enough — `\w` is asked directly
+ * rather than through `\b`, which is defined relative to its neighbour and so
+ * silently stops matching a title that ends in `?` or `)`.
  */
-function countMentions(text, name) {
-    const pattern = new RegExp(`(?<!\\w)${escapeRegExp(name)}(?!\\w)`, 'gi');
-    return text.match(pattern)?.length ?? 0;
+function findMentions(prose, haystack, name) {
+    const needle = normalize(name).text;
+    if (needle.length < MIN_MENTION_LENGTH)
+        return { count: 0 };
+    let count = 0;
+    let matched;
+    for (let at = haystack.text.indexOf(needle); at !== -1; at = haystack.text.indexOf(needle, at + 1)) {
+        const start = haystack.offsets[at];
+        const end = haystack.offsets[at + needle.length - 1];
+        if (WORD.test(prose[start - 1] ?? ''))
+            continue;
+        if (WORD.test(prose[end + 1] ?? ''))
+            continue;
+        count += 1;
+        // The surface form, not the title: the connect step offers the candidate
+        // back with the words Devon actually said, so he can see which phrase in
+        // his dump the link would replace. Lowercased because that is what the
+        // field has always carried, and case is not what distinguishes one
+        // surface form from another here.
+        matched ??= prose
+            .slice(start, end + 1)
+            .toLowerCase()
+            .replace(/\s+/g, ' ');
+    }
+    return { count, matched };
 }
 export async function relatedCommand(root, input, json) {
     const entries = await loadContentEntries({ root });
@@ -109,7 +108,7 @@ export async function relatedCommand(root, input, json) {
     const byName = buildLinkLookup(entries);
     const byUrl = buildUrlLookup(entries);
     const byUrlPath = new Map(entries.map((entry) => [entry.urlPath, entry]));
-    const source = await readSource(input, root);
+    const source = await readSource(input, root, { allowText: true });
     // A file that happens to be a graph entry gets its inbound links too; a
     // draft outside the vault, or raw text, has none by definition.
     const self = source.file ? entries.find((entry) => entry.file === source.file) : undefined;
@@ -123,18 +122,18 @@ export async function relatedCommand(root, input, json) {
         };
     });
     const prose = stripCode(source.text);
+    const haystack = normalize(prose);
     const mentions = entries
         .filter((entry) => entry.urlPath !== self?.urlPath)
         .map((entry) => {
-        const names = [entry.title, ...entry.aliases].filter((name) => name.length >= MIN_MENTION_LENGTH);
         let count = 0;
         let matched;
-        for (const name of names) {
-            const hits = countMentions(prose, name);
-            if (!hits)
+        for (const name of [entry.title, ...entry.aliases]) {
+            const hits = findMentions(prose, haystack, name);
+            if (!hits.count)
                 continue;
-            count += hits;
-            matched ??= name.toLowerCase();
+            count += hits.count;
+            matched ??= hits.matched;
         }
         return { ...toReference(entry), matched, count };
     })

package/lib/cli/render.d.ts

@@ -1,20 +1,22 @@
 /**
- * How a command's result reaches the caller.
+ * `commune render` — a draft as the site will render it.
  *
- * 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.
+ * The review surface the map listed as "not yet specified" needs one thing the
+ * rest of the CLI does not provide: the actual HTML, with `[[WikiLinks]]`
+ * resolved against the real content tree and external links marked, for a
+ * document that is not a page yet and may never be committed. Astro can produce
+ * that, but only by building the whole site, which is a per-turn cost nobody
+ * pays to look at one paragraph.
+ *
+ * So the pipeline is borrowed rather than reimplemented: `communeMarkdown` is
+ * the same processor `astro.config.mjs` hands to `markdown.processor`, and this
+ * verb drives it directly. The rule that keeps it honest is that this file adds
+ * no plugin, no option and no post-processing of its own — anything that made
+ * the CLI's HTML differ from the site's would make the review surface a liar.
  *
- * `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.
+ * `links` and `unresolved` come from the graph core rather than from the
+ * rendered tree. An unresolved wikilink renders as plain text on purpose, so by
+ * the time there is HTML the broken link is indistinguishable from a sentence,
+ * and the one thing a reviewer most needs to be told is gone.
  */
-export declare function writeError(error: CliError, json: boolean): void;
+export declare function renderCommand(root: string, input: string, siteFlag: string | undefined, json: boolean): Promise<number>;

package/lib/cli/render.js

@@ -1,32 +1,74 @@
 /**
- * How a command's result reaches the caller.
+ * `commune render` — a draft as the site will render it.
  *
- * 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.
+ * The review surface the map listed as "not yet specified" needs one thing the
+ * rest of the CLI does not provide: the actual HTML, with `[[WikiLinks]]`
+ * resolved against the real content tree and external links marked, for a
+ * document that is not a page yet and may never be committed. Astro can produce
+ * that, but only by building the whole site, which is a per-turn cost nobody
+ * pays to look at one paragraph.
+ *
+ * So the pipeline is borrowed rather than reimplemented: `communeMarkdown` is
+ * the same processor `astro.config.mjs` hands to `markdown.processor`, and this
+ * verb drives it directly. The rule that keeps it honest is that this file adds
+ * no plugin, no option and no post-processing of its own — anything that made
+ * the CLI's HTML differ from the site's would make the review surface a liar.
  *
- * `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.
+ * `links` and `unresolved` come from the graph core rather than from the
+ * rendered tree. An unresolved wikilink renders as plain text on purpose, so by
+ * the time there is HTML the broken link is indistinguishable from a sentence,
+ * and the one thing a reviewer most needs to be told is gone.
  */
-export function writeError(error, json) {
+import { communeMarkdown } from "../markdown.js";
+import { buildLinkLookup, buildUrlLookup, extractLinks, loadContentEntries, resolveLink, } from "../lib/graph.js";
+import { SCHEMA, writeJson } from "./output.js";
+import { EXIT_OK } from "./errors.js";
+import { readSource } from "./source.js";
+import { resolveSite } from "./site.js";
+export async function renderCommand(root, input, siteFlag, json) {
+    // Read before anything else: `-` has to consume stdin before a slow scan of
+    // the content tree, or a producer writing into the pipe waits on us.
+    const source = await readSource(input, root, { allowText: false });
+    const { site, source: siteSource } = await resolveSite(siteFlag, root);
+    if (siteSource === 'default') {
+        // On stderr, and only when nothing named an origin: `site` decides which
+        // links are the wiki's own, so a caller who did not supply one is
+        // looking at every absolute link marked external and deserves to know
+        // why. In `--json` the field says it too, without the noise.
+        process.stderr.write(`commune: no --site and none found in the Astro config; rendering against ${site}, ` +
+            `so every absolute link counts as external\n`);
+    }
+    const entries = await loadContentEntries({ root });
+    const byName = buildLinkLookup(entries);
+    const byUrl = buildUrlLookup(entries);
+    const byUrlPath = new Map(entries.map((entry) => [entry.urlPath, entry]));
+    const links = extractLinks(source.text, source.frontmatter).map((link) => {
+        const target = resolveLink(link, byName, byUrl);
+        const entry = target ? byUrlPath.get(target.urlPath) : undefined;
+        return {
+            kind: link.kind,
+            target: link.target,
+            resolved: entry
+                ? { urlPath: entry.urlPath, title: entry.title, collection: entry.collection }
+                : null,
+        };
+    });
+    const renderer = await communeMarkdown({ site, root }).createRenderer({});
+    const { code } = await renderer.render(source.text, { frontmatter: source.frontmatter });
     if (json) {
-        process.stderr.write(JSON.stringify({ error: { code: error.code, message: error.message } }, null, 2) + '\n');
-        return;
+        writeJson({
+            schema: SCHEMA,
+            root,
+            site,
+            source: { kind: source.kind, ...(source.file ? { file: source.file } : {}) },
+            html: code,
+            links,
+            // The projection a reviewer acts on: the names in the draft that
+            // point at nothing, which the HTML has already turned into prose.
+            unresolved: links.filter((link) => !link.resolved).map((link) => link.target),
+        });
+        return EXIT_OK;
     }
-    process.stderr.write(`commune: ${error.message}\n`);
-    if (error.detail)
-        process.stderr.write(`${error.detail}\n`);
+    process.stdout.write(code.endsWith('\n') ? code : `${code}\n`);
+    return EXIT_OK;
 }

package/lib/cli/site.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Finding the site's own origin, without starting Astro.
+ *
+ * `site` is what tells the rehype plugin which links are the wiki's own, so
+ * rendering with the wrong one marks every internal absolute link as external.
+ * The value lives in the consumer's `astro.config.*` — but importing that file
+ * would load Astro, the integrations and whatever else the config pulls in,
+ * which is exactly the process this CLI exists to avoid, and would execute the
+ * consumer's code to answer a question about a string.
+ *
+ * So the config is read as text and searched for the two spellings that
+ * actually occur: the property inside `defineConfig`, and the `const` above it
+ * that the property is a shorthand for. Both real wikis use the second. This is
+ * a best effort by construction: `--site` overrides it, and when neither
+ * produces an answer the fallback is announced on stderr rather than assumed.
+ */
+/**
+ * The origin used when nothing else names one.
+ *
+ * A reserved example domain, so a link to it can never collide with a real
+ * host: with this in force, every absolute link renders as external, which is
+ * the safe way to be wrong.
+ */
+export declare const DEFAULT_SITE = "https://example.com";
+export type SiteSource = 'flag' | 'config' | 'default';
+export interface ResolvedSite {
+    site: string;
+    source: SiteSource;
+}
+export declare function resolveSite(flag: string | undefined, root: string): Promise<ResolvedSite>;

package/lib/cli/site.js

@@ -0,0 +1,57 @@
+/**
+ * Finding the site's own origin, without starting Astro.
+ *
+ * `site` is what tells the rehype plugin which links are the wiki's own, so
+ * rendering with the wrong one marks every internal absolute link as external.
+ * The value lives in the consumer's `astro.config.*` — but importing that file
+ * would load Astro, the integrations and whatever else the config pulls in,
+ * which is exactly the process this CLI exists to avoid, and would execute the
+ * consumer's code to answer a question about a string.
+ *
+ * So the config is read as text and searched for the two spellings that
+ * actually occur: the property inside `defineConfig`, and the `const` above it
+ * that the property is a shorthand for. Both real wikis use the second. This is
+ * a best effort by construction: `--site` overrides it, and when neither
+ * produces an answer the fallback is announced on stderr rather than assumed.
+ */
+import { readFile } from 'node:fs/promises';
+import path from 'node:path';
+/**
+ * The origin used when nothing else names one.
+ *
+ * A reserved example domain, so a link to it can never collide with a real
+ * host: with this in force, every absolute link renders as external, which is
+ * the safe way to be wrong.
+ */
+export const DEFAULT_SITE = 'https://example.com';
+const CONFIG_FILES = ['astro.config.mjs', 'astro.config.js', 'astro.config.ts', 'astro.config.mts'];
+/** `site: 'https://…'` inside the config object, or `const site = 'https://…'` above it. */
+const SITE_PATTERNS = [/\bsite\s*:\s*['"`]([^'"`]+)['"`]/, /\bsite\s*=\s*['"`]([^'"`]+)['"`]/];
+/** Read `site` out of a project's Astro config, if it declares one this way. */
+async function readSiteFromConfig(root) {
+    for (const name of CONFIG_FILES) {
+        let source;
+        try {
+            source = await readFile(path.join(root, name), 'utf8');
+        }
+        catch {
+            continue;
+        }
+        for (const pattern of SITE_PATTERNS) {
+            const value = pattern.exec(source)?.[1];
+            // Only a real origin: `site: undefined` and a templated string are
+            // both better answered by the default than by a guess.
+            if (value && URL.canParse(value))
+                return value;
+        }
+    }
+    return undefined;
+}
+export async function resolveSite(flag, root) {
+    if (flag !== undefined)
+        return { site: flag, source: 'flag' };
+    const configured = await readSiteFromConfig(root);
+    if (configured !== undefined)
+        return { site: configured, source: 'config' };
+    return { site: DEFAULT_SITE, source: 'default' };
+}

package/lib/cli/source.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a verb's markdown comes from: a file, stdin, or the argument itself.
+ *
+ * One reader for `graph related` and `render`, because they take the same
+ * positional and have to agree about what it means — including the part that is
+ * easy to get subtly different, which is that a path is tried against `--root`
+ * before the cwd. The root is the vault being asked about; the cwd is wherever
+ * the operator happens to be standing.
+ *
+ * The one difference between the two callers is what a string that names no
+ * file means. `graph related` answers questions about prose, so it is text.
+ * `render` renders a document, and a mistyped path silently rendering as its
+ * own filename would be a wrong answer with no error anywhere, so it fails.
+ */
+export interface Source {
+    kind: 'file' | 'text' | 'stdin';
+    /** Root-relative and POSIX-separated, for a file. */
+    file?: string;
+    /** The markdown body, with any frontmatter split off. */
+    text: string;
+    frontmatter: Record<string, unknown>;
+}
+export interface ReadSourceOptions {
+    /** Whether a string naming no file is prose (`graph related`) or an error (`render`). */
+    allowText: boolean;
+}
+/**
+ * Resolve the positional into markdown and its frontmatter.
+ *
+ * `-` is stdin, which is how a draft that is not a file yet gets asked about —
+ * and it is frontmatter-aware there too, so piping a whole note in behaves the
+ * same as naming it.
+ */
+export declare function readSource(input: string, root: string, { allowText }: ReadSourceOptions): Promise<Source>;

package/lib/cli/source.js

@@ -0,0 +1,74 @@
+/**
+ * Where a verb's markdown comes from: a file, stdin, or the argument itself.
+ *
+ * One reader for `graph related` and `render`, because they take the same
+ * positional and have to agree about what it means — including the part that is
+ * easy to get subtly different, which is that a path is tried against `--root`
+ * before the cwd. The root is the vault being asked about; the cwd is wherever
+ * the operator happens to be standing.
+ *
+ * The one difference between the two callers is what a string that names no
+ * file means. `graph related` answers questions about prose, so it is text.
+ * `render` renders a document, and a mistyped path silently rendering as its
+ * own filename would be a wrong answer with no error anywhere, so it fails.
+ */
+import { readFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { failure } from "./errors.js";
+async function isFile(candidate) {
+    try {
+        return (await stat(candidate)).isFile();
+    }
+    catch {
+        return false;
+    }
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    return Buffer.concat(chunks).toString('utf8');
+}
+/**
+ * Resolve the positional into markdown and its frontmatter.
+ *
+ * `-` is stdin, which is how a draft that is not a file yet gets asked about —
+ * and it is frontmatter-aware there too, so piping a whole note in behaves the
+ * same as naming it.
+ */
+export async function readSource(input, root, { allowText }) {
+    if (input === '-') {
+        const { content, data } = matter(await readStdin());
+        return { kind: 'stdin', text: content, frontmatter: data };
+    }
+    const candidates = path.isAbsolute(input) ? [input] : [path.join(root, input), path.resolve(input)];
+    for (const candidate of candidates) {
+        if (!(await isFile(candidate)))
+            continue;
+        let source;
+        try {
+            source = await readFile(candidate, 'utf8');
+        }
+        catch (error) {
+            throw failure('EPARSE', `cannot read ${candidate}: ${error.message}`);
+        }
+        let parsed;
+        try {
+            parsed = matter(source);
+        }
+        catch (error) {
+            throw failure('EPARSE', `cannot parse frontmatter in ${candidate}: ${error.message}`);
+        }
+        return {
+            kind: 'file',
+            file: path.relative(root, candidate).split(path.sep).join('/'),
+            text: parsed.content,
+            frontmatter: parsed.data,
+        };
+    }
+    if (!allowText) {
+        throw failure('EPARSE', `cannot read ${input}: no such file under ${root} or the cwd`);
+    }
+    return { kind: 'text', text: input, frontmatter: {} };
+}

package/lib/cli/update.js

@@ -16,7 +16,7 @@
 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 { SCHEMA, writeJson, writeLines } from "./output.js";
 import { EXIT_OK, failure } from "./errors.js";
 /**
  * The entry, as markdown.

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>] 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 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>] render        <path|-> [--site <origin>] [--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  --unreferenced                                Zero inbound, any outbound. Skips\n                                                updates, which are expected to have\n                                                none, unless --collection updates\n                                                asks for them.\n  --recent <7d|2w|2026-09-01>                   Updated on or since then. Entries\n                                                with no date are not returned.\n\nrender options:\n  --site <origin>   The wiki's own origin, which is what decides whether a link\n                    is external. Read from the Astro config when it declares\n                    one; otherwise https://example.com, and it says so.\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>] render        <path|-> [--site <origin>] [--json]
   commune [--root <dir>] update        [--recent <duration|date>] [--write] [--json]
   commune [--root <dir>] check         [--json]
   commune [--root <dir>] gate          [--dist <dir>] [--json]
@@ -21,9 +22,18 @@ graph query filters (any-of within a flag, all-of across flags):
   --status <status>
   --orphans                                     Zero inbound and zero outbound.
   --deadends                                    Zero outbound.
+  --unreferenced                                Zero inbound, any outbound. Skips
+                                                updates, which are expected to have
+                                                none, unless --collection updates
+                                                asks for them.
   --recent <7d|2w|2026-09-01>                   Updated on or since then. Entries
                                                 with no date are not returned.
 
+render options:
+  --site <origin>   The wiki's own origin, which is what decides whether a link
+                    is external. Read from the Astro config when it declares
+                    one; otherwise https://example.com, and it says so.
+
 update options:
   --recent <7d|2w|2026-09-01>   What to roll up. Default: 7d.
   --write                       Write src/content/updates/<today>.md. Without it,
@@ -42,7 +52,7 @@ 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] [--recent <duration|date>] [--json]',
+    'graph query': 'Usage: commune [--root <dir>] graph query [--collection <c>]... [--tag <t>]... [--status <s>] [--orphans] [--deadends] [--unreferenced] [--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]
 
@@ -50,6 +60,13 @@ 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.`,
+    render: `Usage: commune [--root <dir>] render <path|-> [--site <origin>] [--json]
+
+Render markdown to HTML through the site's own pipeline, with WikiLinks
+resolved against the content tree and external links marked. Frontmatter is
+split off and not rendered. --json adds the links the document contains and
+the names among them that resolve to nothing — which the HTML cannot tell
+you, since an unresolved WikiLink renders as plain text.`,
     check: 'Usage: commune [--root <dir>] check [--json]',
     gate: `Usage: commune [--root <dir>] gate [--dist <dir>] [--json]
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dmthepm/commune",
   "type": "module",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "An Astro wiki engine with WikiLinks, sliding panes, backlinks and static search, plus a commune CLI that queries the content graph and checks links",
   "license": "MIT",
   "keywords": [