secondbrain-py 0.2.1__py3-none-any.whl

brain/quartz_overrides/quartz/plugins/transformers/index.ts

@@ -0,0 +1,114 @@
+// Brain wiki — transformer barrel re-export with brain extensions wired in.
+//
+// PARSER CACHE CONTRACT — READ BEFORE ADDING A TRANSFORMER:
+//
+// MDAST transformers in this directory MUST be pure functions of
+// (file bytes, slug). "Pure" means: given the same file bytes and the
+// same slug, a transformer MUST produce the same output AST every time,
+// with no dependence on sibling files, the build graph, or any mutable
+// global state.
+//
+// Why this matters: the parser cache in
+// `quartz_overrides/quartz/processors/parser_cache.ts` keys each
+// cached [MDAST, file.data] entry on:
+//
+//   sha256(CACHE_VERSION as 4 bytes || slug as UTF-8 || file bytes)
+//
+// If a transformer reads data from other files, a database, or any
+// external source at the parse stage, a cache hit for an unchanged file
+// would return stale output even though a dependency changed.
+//
+// Cross-file context (backlinks, contentIndex, related-docs, derived
+// edges) belongs in the EMITTER phase, which runs on the in-memory
+// ProcessedContent[] collection AFTER parseMarkdown returns. No
+// transformer here may reach across files at parse time.
+//
+// Version bumping: if you change a transformer in a way that alters its
+// output for the same input (e.g. new data attributes, changed tree
+// structure), bump CACHE_VERSION in parser_cache.ts in the SAME COMMIT
+// as the transformer change. A version bump invalidates all existing
+// cache entries globally (by changing every key) so the next build
+// re-derives correct output for every file.
+//
+// Audit checklist for new transformers:
+//   [x] Pure function of (file bytes, slug) — no cross-file reads
+//   [x] No mutable module-level state that varies across files
+//   [x] If output format changes: CACHE_VERSION bumped in same commit
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/index.ts` by `brain
+// vault render --overlay`, OVERWRITING the stock Quartz barrel. The
+// overlay is a 1:1 file copy (`src/brain/vault/quartz_overlay.py`),
+// so this is the canonical seam for ensuring the brain-extension
+// transformer files in this directory get re-exported under the
+// `Plugin.*` namespace consumed by `quartz.config.ts`.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz
+// version adds a new stock transformer, append its export below; the
+// ones that already exist are sourced verbatim from
+// https://github.com/jackyzha0/quartz/blob/v4/quartz/plugins/transformers/index.ts
+// and the brain extensions are appended at the bottom in their own
+// block.
+//
+// brain: stock Quartz transformer exports — keep in lock-step with
+// the upstream `index.ts` linked above. If you upgrade Quartz, diff
+// upstream against this block and apply additions.
+export { FrontMatter } from "./frontmatter"
+export { GitHubFlavoredMarkdown } from "./gfm"
+export { Citations } from "./citations"
+export { CreatedModifiedDate } from "./lastmod"
+export { Latex } from "./latex"
+export { Description } from "./description"
+export { CrawlLinks } from "./links"
+export { ObsidianFlavoredMarkdown } from "./ofm"
+export { OxHugoFlavouredMarkdown } from "./oxhugofm"
+export { SyntaxHighlighting } from "./syntax"
+export { TableOfContents } from "./toc"
+export { HardLineBreaks } from "./linebreaks"
+export { RoamFlavoredMarkdown } from "./roam"
+
+// brain-extension: brain-only transformers added by the overlay. Each
+// is documented in its own file's top-of-file comment.
+//   * DerivedFenceMark — stamps Phase D fence links with
+//     `data-brain-derived` so the contentIndex emitter and the Lane B
+//     link classifier can recognise them as evidence edges.
+//   * ReloadSignal     — injects the polling reload watcher when
+//     `BRAIN_WIKI_RELOAD=1` (dev path); see the blue-green serve plan.
+//   * LinkKindMark     — Lane B redesign — stamps every `<a>` with
+//     `data-brain-link-kind` so the redesigned link styles can
+//     distinguish wiki / external / tag / ingested / derived kinds.
+//   * LinkSourceTag    — Lane B redesign — injects
+//     `/static/linkSourceTag.js` to add `data-brain-source` to
+//     ingested links at runtime (source identity is in the URL path
+//     but extraction at build-time would require a doc lookup).
+//   * CodeCopy         — Lane C redesign — injects
+//     `/static/codeCopy.js` to add a brain-themed copy button to
+//     every `<pre>` in the article (supersedes stock Quartz's
+//     `.clipboard-button`, which `_code.scss` hides) and to lift
+//     the `data-language` attribute from inner `<code>` to outer
+//     `<pre>` so the CSS-only language label can render via
+//     `attr()`.
+export { DerivedFenceMark } from "./derivedFenceMark"
+export { ReloadSignal } from "./reloadSignal"
+export { LinkKindMark } from "./linkKindMark"
+export { LinkSourceTag } from "./linkSourceTag"
+//   * RelativeDate     — Recent rail — injects `/static/relativeDate.js`
+//     to recompute the home-page Recent rail's relative timestamps
+//     ("3d ago") live on every page load, instead of baking a decaying
+//     string at build time. Pairs with the `<span class="brain-rel-date"
+//     data-date="<ISO>">` markup emitted by `build_homepage`.
+export { RelativeDate } from "./relativeDate"
+export { CodeCopy } from "./codeCopy"
+//   * EmptyDoorFilter   — P4.1 — strips home-page list-items whose
+//     internal link resolves to an empty folder (e.g. `daily/` when
+//     no daily notes exist). Pairs with the brain CLI's auto-generated
+//     `<folder>/index.md` so the door appears iff the folder has
+//     content.
+export { EmptyDoorFilter } from "./emptyDoorFilter"
+//   * EmailThreadReader — P4.4 — injects the email-thread reading-mode
+//     runtime (`/static/emailThread.js`) plus an inline
+//     `window.BRAIN_USER_EMAIL` global (read from
+//     `process.env.BRAIN_USER_EMAIL` at build time). The runtime
+//     enhances `email_thread` pages with per-message data attributes
+//     and a "Show only my replies" filter button.
+export { EmailThreadReader } from "./emailThread"

brain/quartz_overrides/quartz/plugins/transformers/linkKindMark.ts

@@ -0,0 +1,205 @@
+// Brain wiki redesign — link-kind classifier transformer plugin (Lane B).
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/linkKindMark.ts`
+// by `brain vault render --overlay`. It does NOT compile or run from
+// the brain repo itself; the imports below resolve against the
+// dependencies Quartz pulls into the cloned workspace via
+// `npm install`, not against any package brain ships.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz
+// version restructures the transformer plugin shape or the mdast
+// types it uses, pull the latest transformer reference from
+// https://github.com/jackyzha0/quartz/tree/v4/quartz/plugins/transformers
+// and re-apply the brain tweaks flagged below — `// brain:` for
+// value/structural choices on upstream-supported fields, and
+// `// brain-extension:` for keys/types that don't exist in stock
+// Quartz.
+//
+// What this transformer does, and why: the 2026 redesign (Lane B)
+// fixes the "every link looks identical" complaint by giving five
+// distinct visual treatments to the five link kinds the brain wiki
+// emits. The styling lives in
+// `quartz_overrides/quartz/styles/brain/_links.scss` and keys off the
+// `data-brain-link-kind` attribute this transformer stamps onto
+// every `<a>` rendered from a markdown `link` mdast node.
+//
+// Classification, in priority order:
+//
+//   1. derived  — already stamped by `derivedFenceMark` with
+//                 `data-brain-derived="true"`. We do NOT re-walk the
+//                 fence; we just trust the upstream stamp and label
+//                 the kind as `derived`. This keeps fence-membership
+//                 truth-source ownership in `derivedFenceMark.ts` and
+//                 prevents drift if the fence shape ever changes.
+//   2. tag      — link URL starts with `tags/` (relative) or contains
+//                 `/tags/` (absolute / slug-prefixed). Quartz's stock
+//                 OFM transformer renders `#tag` syntax + `[[tags/x]]`
+//                 wiki links into mdast `link` nodes whose `url`
+//                 already carries the slug — so a string-prefix check
+//                 is sufficient and cheaper than a slug normaliser.
+//   3. external — URL starts with `http://`, `https://`, or
+//                 `mailto:`. When the host config sets
+//                 `openLinksInNewTab: true`, Quartz adds
+//                 `target="_blank" rel="noopener"` via its CrawlLinks
+//                 pass; the brain config leaves the default off.
+//                 Either way, the classifier reads the URL directly
+//                 so behavior is independent of that flag and of
+//                 plugin ordering.
+//   4. ingested — URL starts with `_ingested/` (vault-internal but
+//                 pointing to mirrored ingested content from
+//                 `brain ingest*`). Source-tinting (krisp/slack/gmail/
+//                 manual) is applied at runtime by `linkSourceTag.js`
+//                 because the source identity lives in the target
+//                 doc's frontmatter, which a transformer can't easily
+//                 look up at build time.
+//   5. wiki     — fallback for everything else. Matches both Quartz's
+//                 stock `internal` class (resolved wiki links) and
+//                 anything that didn't fit the above buckets.
+//
+// brain: registration order matters. This transformer must run
+// AFTER `Plugin.ObsidianFlavoredMarkdown()` (so `[[wiki-link]]` syntax
+// has been converted into mdast `link` nodes) AND AFTER
+// `Plugin.DerivedFenceMark()` (so `data-brain-derived="true"` is
+// already stamped by the time we read it). The brain
+// `quartz.config.ts` template wires it up in the correct slot — see
+// the `transformers: [...]` list there.
+
+import type { Root, RootContent, Link } from "mdast"
+
+import { QuartzTransformerPlugin } from "../types"
+
+// brain-extension: stable string set the SCSS in `_links.scss` keys
+// off. Adding a new kind requires (a) extending this union, (b)
+// extending the classifier, (c) adding a `[data-brain-link-kind="x"]`
+// rule in `_links.scss`. All three live in the same Lane B PR.
+type LinkKind = "derived" | "tag" | "external" | "ingested" | "wiki"
+
+// brain-extension: the attribute the SCSS in `_links.scss` reads.
+// Namespaced `data-brain-` prefix — same convention as
+// `data-brain-derived` in `derivedFenceMark.ts` — so we never collide
+// with a Quartz-internal `data-*` attribute.
+const KIND_ATTR = "data-brain-link-kind"
+
+// brain-extension: the upstream stamp from `derivedFenceMark.ts` that
+// signals "this link lives inside a Phase D fence." Mirrored from
+// that file's `stampDerived` function. If the fence stamp ever
+// changes shape, update both files together.
+const DERIVED_ATTR = "data-brain-derived"
+
+// brain: external-link URL prefixes. `mailto:` is included because
+// markdown autolinks (`<fixture@example.com>`) become mdast `link` nodes with
+// `mailto:` URLs; the SCSS's `↗` indicator suits them. `tel:` is
+// not included — current vault content has none, and adding it later
+// is a one-line change.
+const EXTERNAL_PREFIXES = ["http://", "https://", "mailto:"]
+
+// brain: ingested-tier URL prefix. The vault layout puts every
+// ingested doc under `_ingested/<source>/<slug>/`, and Quartz's
+// CrawlLinks resolves wiki links to those targets with that exact
+// prefix. Both the leading-slash form (`/_ingested/...`) and the
+// relative form (`_ingested/...`) appear in real builds depending on
+// link-resolution mode, so the classifier checks both.
+const INGESTED_PREFIXES = ["_ingested/", "/_ingested/", "./_ingested/"]
+
+// brain: tag-link URL patterns. Quartz emits tag links with URL
+// `tags/<slug>` (relative, default `markdownLinkResolution: "shortest"`)
+// or `/tags/<slug>` (absolute) depending on render context. The check
+// matches both forms; a `tags/` prefix on a non-tag doc is unlikely
+// (the slug `tags` is reserved by Quartz's TagPage emitter) so we
+// don't over-constrain.
+const TAG_PREFIXES = ["tags/", "/tags/", "./tags/"]
+
+// brain: case-insensitive prefix match. URLs SHOULD be lowercase but
+// hand-edited markdown can carry mixed-case `MailTo:` / `HTTPS://`,
+// so we normalise the comparison to be defensive.
+function startsWithAny(url: string, prefixes: readonly string[]): boolean {
+  const lowered = url.toLowerCase()
+  for (const prefix of prefixes) {
+    if (lowered.startsWith(prefix.toLowerCase())) return true
+  }
+  return false
+}
+
+// brain: classify a single mdast Link node into one of the five
+// kinds. Returns a string from the `LinkKind` union. The classifier
+// is pure (no mutation, no I/O) so it can be unit-tested in isolation
+// if we ever add an overlay-side TS test runner.
+//
+// brain: classification order matters — `derived` wins over every
+// other kind because a link inside a Phase D fence is conceptually
+// "an evidence edge to a related doc," not "a wiki link to that
+// doc." The italic-dashed styling in `_links.scss` reflects that
+// distinction. After `derived`, `tag` and `external` are mutually
+// exclusive with the others by URL shape; `ingested` is a refinement
+// of `wiki` (both are vault-internal) so the ingested check runs
+// before the wiki fallback.
+function classifyLink(link: Link): LinkKind {
+  const data = link.data as Record<string, unknown> | undefined
+  const props = data?.hProperties as Record<string, unknown> | undefined
+  if (props !== undefined && props[DERIVED_ATTR] === "true") {
+    return "derived"
+  }
+  const url = link.url ?? ""
+  if (startsWithAny(url, TAG_PREFIXES)) return "tag"
+  if (startsWithAny(url, EXTERNAL_PREFIXES)) return "external"
+  if (startsWithAny(url, INGESTED_PREFIXES)) return "ingested"
+  return "wiki"
+}
+
+// brain: in-place attribute stamper. Same `data.hProperties` extension
+// point used by `derivedFenceMark.stampDerived` — remark-rehype copies
+// these onto the corresponding hast element's properties, which then
+// become real HTML attributes after stringification. Idempotent: if
+// the attribute is already set (e.g. a future plugin pre-stamps it),
+// we don't overwrite — first writer wins, and the attribute's
+// presence is what the SCSS keys off, not its origin.
+function stampKind(link: Link, kind: LinkKind): void {
+  const data = (link.data ??= {}) as Record<string, unknown>
+  const props = (data.hProperties ??= {}) as Record<string, string>
+  if (props[KIND_ATTR] !== undefined) return
+  props[KIND_ATTR] = kind
+}
+
+// brain: top-level mdast walker. Recursively visits every node;
+// stamps any `link` it encounters. Mirrors the `"children" in node`
+// recursion pattern in `derivedFenceMark.annotateFence` so links
+// nested inside lists, headings, blockquotes, and table cells are
+// all reached. No fence-membership tracking is needed here because
+// `derivedFenceMark` runs first and has already stamped
+// `data-brain-derived` on every fence link by the time we walk.
+function annotate(tree: Root): void {
+  const visit = (node: RootContent | Root): void => {
+    if (node.type === "link") {
+      stampKind(node, classifyLink(node))
+    }
+    if ("children" in node && Array.isArray(node.children)) {
+      for (const child of node.children as RootContent[]) {
+        visit(child)
+      }
+    }
+  }
+  visit(tree)
+}
+
+// brain-extension: the transformer plugin itself. Empty options
+// object — the only knobs would be the kind set or the URL prefix
+// lists, both of which are part of the redesign contract documented
+// at the top of this file. Keeping the signature `(opts?: never)`
+// documents that no configuration is expected; if a knob is genuinely
+// needed later (e.g. a per-vault tag prefix override), widen the type
+// at that point rather than guessing now.
+export const LinkKindMark: QuartzTransformerPlugin = (_opts?: never) => {
+  return {
+    name: "LinkKindMark",
+    markdownPlugins() {
+      return [
+        () => {
+          return (tree: Root) => {
+            annotate(tree)
+          }
+        },
+      ]
+    },
+  }
+}

brain/quartz_overrides/quartz/plugins/transformers/linkSourceTag.ts

@@ -0,0 +1,104 @@
+// Brain wiki redesign — link source-tagger transformer plugin (Lane B).
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/linkSourceTag.ts`
+// by `brain vault render --overlay`. It does NOT compile or run from
+// the brain repo itself; the imports below resolve against the
+// dependencies Quartz pulls into the cloned workspace via
+// `npm install`, not against any package brain ships.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz
+// version restructures the transformer plugin shape or the
+// `externalResources()` hook contract, pull the latest transformer
+// reference from
+// https://github.com/jackyzha0/quartz/tree/v4/quartz/plugins/transformers
+// and re-apply the brain tweaks flagged below — `// brain:` for
+// value/structural choices on upstream-supported fields, and
+// `// brain-extension:` for keys/types that don't exist in stock
+// Quartz.
+//
+// What this transformer does, and why: the companion `linkKindMark`
+// transformer stamps `data-brain-link-kind="ingested"` on every `<a>`
+// pointing into `_ingested/<source>/<slug>`, but it can't determine
+// the source segment without a build-time document lookup that's
+// expensive and brittle. We instead inject a tiny client script
+// (`/static/linkSourceTag.js`, also installed by the overlay) that
+// extracts the source from the href on `DOMContentLoaded` and stamps
+// `data-brain-source="krisp"` (or slack/gmail/manual). `_links.scss`
+// reads that attribute via `&[data-brain-source="krisp"]` rules to
+// pick the source-tinted left-rail color from the `--brain-source-*`
+// token palette.
+//
+// brain: this transformer ALWAYS injects the script — unlike
+// `Plugin.ReloadSignal` which is gated on `BRAIN_WIKI_RELOAD=1`,
+// source tagging is part of the production redesign and must run
+// whether the build is dev (`bin/brain-up`) or prod (`brain vault
+// render`). The injected script is tiny (~25 lines, ~1.2 KB) and
+// runs once per page load + once per SPA navigation.
+//
+// brain: cross-references for the source-tagging contract:
+//   * `quartz_overrides/quartz/static/linkSourceTag.js` — the runtime
+//     tagger this transformer points page `<head>` at.
+//   * `quartz_overrides/quartz/plugins/transformers/linkKindMark.ts`
+//     — the build-time classifier whose `data-brain-link-kind="ingested"`
+//     stamp this script complements with `data-brain-source="..."`.
+//   * `quartz_overrides/quartz/styles/brain/_links.scss` — the SCSS
+//     consumer that reads both attributes to render the source-tinted
+//     left rail on ingested links.
+//   * `quartz_overrides/quartz/styles/brain/_tokens.scss` — defines
+//     the `--brain-source-{krisp,slack,gmail,manual}` palette both the
+//     graph and link styles share.
+//
+// Registration: this transformer has NO ordering requirement among
+// the other transformers — it doesn't touch the mdast tree, only
+// contributes a `<script>` tag via `externalResources()`. Place it
+// anywhere in the `transformers: [...]` list; the brain
+// `quartz.config.ts` template wires it next to `LinkKindMark` so the
+// Lane B plugins stay grouped.
+
+import { QuartzTransformerPlugin } from "../types"
+
+// brain-extension: the path the page `<script src=...>` tag points
+// at. Leading slash is intentional — Quartz emits pages at arbitrary
+// slug depths (e.g. `/notes/foo/index.html`) and a relative
+// `static/linkSourceTag.js` would break for any non-root page.
+// Server-rooted `/static/linkSourceTag.js` resolves consistently
+// regardless of which page the user landed on. This works because
+// Caddy's `file_server` (and Quartz's stock `file_server` in dev)
+// serves the build dir as the site root
+// (`<vault>/.quartz/current/static/linkSourceTag.js`).
+const SCRIPT_SRC = "/static/linkSourceTag.js"
+
+// brain-extension: the transformer plugin itself. Empty options
+// shape — the script path is part of the contract documented above
+// and the script body is fixed at the static-asset level. Keeping
+// the signature `(opts?: never)` documents that no configuration is
+// expected; if a knob is genuinely needed later (e.g. a per-vault
+// source-allowlist override), widen the type at that point rather
+// than guessing now.
+export const LinkSourceTag: QuartzTransformerPlugin = (_opts?: never) => {
+  return {
+    name: "LinkSourceTag",
+    externalResources() {
+      return {
+        js: [
+          {
+            // brain: `afterDOMReady` so the script runs after
+            // `</body>` (see Quartz's `renderPage.tsx` for the
+            // dispatch). The tagger reads + writes DOM attributes
+            // and uses its own `DOMContentLoaded` listener as a
+            // fallback for the loading-state edge case.
+            loadTime: "afterDOMReady",
+            // brain-extension: external script (URL src) rather than
+            // inline. The linkSourceTag.js file is bundled into every
+            // build's `static/` dir by Quartz's stock `Plugin.Static()`
+            // emitter; pointing at it by URL keeps the script body
+            // out of every page's HTML and lets the browser cache it.
+            contentType: "external",
+            src: SCRIPT_SRC,
+          },
+        ],
+      }
+    },
+  }
+}

brain/quartz_overrides/quartz/plugins/transformers/relativeDate.ts

@@ -0,0 +1,100 @@
+// Brain wiki — live relative-date transformer plugin (Recent rail).
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/relativeDate.ts`
+// by `brain vault render --overlay`. It does NOT compile or run from
+// the brain repo itself; the imports below resolve against the
+// dependencies Quartz pulls into the cloned workspace via
+// `npm install`, not against any package brain ships.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz
+// version restructures the transformer plugin shape or the
+// `externalResources()` hook contract, pull the latest transformer
+// reference from
+// https://github.com/jackyzha0/quartz/tree/v4/quartz/plugins/transformers
+// and re-apply the brain tweaks flagged below — `// brain:` for
+// value/structural choices on upstream-supported fields, and
+// `// brain-extension:` for keys/types that don't exist in stock
+// Quartz.
+//
+// What this transformer does, and why: the home-page Recent rail
+// (`brain.wiki.build_homepage`) used to bake a relative date string
+// ("today", "3d ago") into `index.md` at build time. That string decays
+// because the home note isn't re-rendered daily, so a doc ingested 3
+// days before a build still reads "3d ago" weeks later. The rail now
+// emits the ABSOLUTE date as a `data-date` attribute on a
+// `<span class="brain-rel-date">` plus a non-decaying "Jun 10"-style
+// fallback as the span's text. We inject a tiny client script
+// (`/static/relativeDate.js`, also installed by the overlay) that reads
+// each `data-date` and recomputes the relative text live on every page
+// load (and on Quartz SPA `nav` events), keeping the rail honest.
+//
+// brain: this transformer ALWAYS injects the script — unlike
+// `Plugin.ReloadSignal` which is gated on `BRAIN_WIKI_RELOAD=1`, the
+// live relative date is part of the production behavior and must run
+// whether the build is dev (`bin/brain-up`) or prod (`brain vault
+// render`). The injected script is tiny (~30 lines) and runs once per
+// page load + once per SPA navigation.
+//
+// brain: cross-references for the live-relative-date contract:
+//   * `quartz_overrides/quartz/static/relativeDate.js` — the runtime
+//     recomputer this transformer points page `<head>` at; its bucket
+//     logic mirrors `build_homepage._format_relative_date`.
+//   * `src/brain/wiki/build_homepage.py` — the server side that emits
+//     `<span class="brain-rel-date" data-date="<ISO>">{absolute}</span>`
+//     into the Recent fence (`_render_bullets` / `_format_absolute_date`).
+//
+// Registration: this transformer has NO ordering requirement among
+// the other transformers — it doesn't touch the mdast tree, only
+// contributes a `<script>` tag via `externalResources()`. Place it
+// anywhere in the `transformers: [...]` list; the brain
+// `quartz.config.ts` template wires it next to `LinkSourceTag` so the
+// script-only brain transformers stay grouped.
+
+import { QuartzTransformerPlugin } from "../types"
+
+// brain-extension: the path the page `<script src=...>` tag points at.
+// Leading slash is intentional — Quartz emits pages at arbitrary slug
+// depths (e.g. `/notes/foo/index.html`) and a relative
+// `static/relativeDate.js` would break for any non-root page.
+// Server-rooted `/static/relativeDate.js` resolves consistently
+// regardless of which page the user landed on. (In practice only the
+// home page carries `.brain-rel-date` spans today, but injecting site-
+// wide keeps the contract simple and future-proof if other surfaces
+// adopt the span.) This works because Caddy's `file_server` (and
+// Quartz's stock `file_server` in dev) serves the build dir as the site
+// root (`<vault>/.quartz/current/static/relativeDate.js`).
+const SCRIPT_SRC = "/static/relativeDate.js"
+
+// brain-extension: the transformer plugin itself. Empty options shape —
+// the script path is part of the contract documented above and the
+// script body is fixed at the static-asset level. Keeping the signature
+// `(opts?: never)` documents that no configuration is expected; if a
+// knob is genuinely needed later, widen the type at that point rather
+// than guessing now.
+export const RelativeDate: QuartzTransformerPlugin = (_opts?: never) => {
+  return {
+    name: "RelativeDate",
+    externalResources() {
+      return {
+        js: [
+          {
+            // brain: `afterDOMReady` so the script runs after `</body>`
+            // (see Quartz's `renderPage.tsx` for the dispatch). The
+            // recomputer reads + writes DOM text and uses its own
+            // `DOMContentLoaded` listener as a fallback for the
+            // loading-state edge case.
+            loadTime: "afterDOMReady",
+            // brain-extension: external script (URL src) rather than
+            // inline. The relativeDate.js file is bundled into every
+            // build's `static/` dir by Quartz's stock `Plugin.Static()`
+            // emitter; pointing at it by URL keeps the script body out
+            // of every page's HTML and lets the browser cache it.
+            contentType: "external",
+            src: SCRIPT_SRC,
+          },
+        ],
+      }
+    },
+  }
+}

brain/quartz_overrides/quartz/plugins/transformers/reloadSignal.ts

@@ -0,0 +1,131 @@
+// Brain blue-green serve — reload-signal transformer plugin.
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/plugins/transformers/reloadSignal.ts`
+// by `brain vault render --overlay`. It does NOT compile or run
+// from the brain repo itself; the imports below resolve against
+// the dependencies Quartz pulls into the cloned workspace via
+// `npm install`, not against any package brain ships.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz
+// version restructures the transformer plugin shape or the
+// `externalResources()` hook contract, pull the latest
+// transformer reference from
+// https://github.com/jackyzha0/quartz/tree/v4/quartz/plugins/transformers
+// and re-apply the brain tweaks flagged below — `// brain:` for
+// value/structural choices on upstream-supported fields, and
+// `// brain-extension:` for keys/types that don't exist in stock
+// Quartz.
+//
+// What this transformer does, and why: in the blue-green serve
+// architecture (see
+// `docs/plans/2026-05-01-quartz-blue-green-serve.md`), Caddy
+// serves whichever build dir `<vault>/.quartz/current` symlinks
+// to, and the brain build watcher atomically retargets that
+// symlink at a fresh `<vault>/.quartz/builds/<id>/` after every
+// rebuild. Stock Quartz's `--serve` mode opens a WebSocket from
+// the dev server back to the page so it can push a reload — but
+// `--serve` is dead in our flow (Caddy serves the static output
+// directly; Quartz only builds), so the WebSocket-reload path is
+// gone. This transformer injects an ETag-aware polling client
+// (`quartz/static/reload.js`, also installed by the overlay) that
+// fetches `/.build-id` every 3s, revalidates with `If-None-Match`
+// after the first ETag-bearing response, and calls
+// `location.reload()` when the value changes. The polling target is
+// the per-build identifier file `brain.wiki.build_swap` writes at
+// each build dir's root; Caddy serves it directly because the build
+// dir IS the site root.
+//
+// brain-extension: env-var contract. The script is injected only
+// when `process.env.BRAIN_WIKI_RELOAD === "1"` at BUILD time
+// (not at runtime — the gate is read while Quartz is producing
+// HTML, then baked into the page). Any other value (including
+// unset) means `externalResources()` returns an empty object and
+// no `<script>` tag goes out. `bin/brain-up` (the dev daily-use
+// path) sets the env to `"1"`; `brain vault render` (the prod
+// one-shot path) leaves it unset, so prod builds ship without
+// any polling chatter. The reload.js asset itself is still
+// copied into `static/` by Quartz's `Plugin.Static()` emitter
+// either way — it's just unreferenced unless the gate flips.
+//
+// brain: cross-references for the full reload contract:
+//   * `quartz_overrides/quartz/static/reload.js` — the polling
+//     client this transformer points page `<head>` at.
+//   * `src/brain/wiki/build_swap.py` — writes `<build>/.build-id`
+//     after every successful build, then atomically retargets
+//     `<vault>/.quartz/current` at the new build dir.
+//   * `bin/brain-up` — sets `BRAIN_WIKI_RELOAD=1` for the build
+//     watcher subprocess; spawns Caddy as the static file server
+//     pointed at `<vault>/.quartz/current/`.
+//   * Caddyfile — must serve `/.build-id` at root (default
+//     behavior of `file_server` since the file lives at the
+//     build dir's root).
+//
+// Registration: this transformer has NO ordering requirement
+// among the other transformers — it doesn't touch the mdast
+// tree. It only contributes a `<script>` tag via
+// `externalResources()`. Place it anywhere in the
+// `transformers: [...]` list; the brain `quartz.config.ts`
+// template wires it AFTER `Plugin.DerivedFenceMark()` so the two
+// brain-extension transformers stay grouped.
+
+import { QuartzTransformerPlugin } from "../types"
+
+// brain-extension: the path the page `<script src=...>` tag
+// points at. Leading slash is intentional — Quartz emits pages
+// at arbitrary slug depths (e.g. `/notes/foo/index.html`) and a
+// relative `static/reload.js` would break for any non-root page.
+// Server-rooted `/static/reload.js` resolves consistently
+// regardless of which page the user landed on. This works
+// because Caddy's `file_server` serves the build dir as the site
+// root (`<vault>/.quartz/current/static/reload.js`); see
+// `docs/plans/2026-05-01-quartz-blue-green-serve.md` for the
+// Caddyfile shape.
+const RELOAD_SCRIPT_SRC = "/static/reload.js"
+
+// brain-extension: build-time env var that gates injection. Read
+// inside `externalResources()` so each plugin instance evaluates
+// the gate fresh per build (matters for tests + for `bin/brain-up`
+// re-invocations where the env may differ between runs).
+const RELOAD_ENV_VAR = "BRAIN_WIKI_RELOAD"
+
+// brain-extension: the transformer plugin itself. Empty options
+// shape — the only knobs would be the script path and the env
+// var name, both of which are part of the contract documented
+// above. Keeping the signature `(opts?: never)` documents that
+// no configuration is expected; if a knob is genuinely needed
+// later (e.g. a per-vault interval override), widen the type at
+// that point rather than guessing now.
+export const ReloadSignal: QuartzTransformerPlugin = (_opts?: never) => {
+  return {
+    name: "ReloadSignal",
+    externalResources() {
+      // brain: strict equality with `"1"` rather than truthiness
+      // so accidental values like `"0"` / `"false"` / `"no"`
+      // don't enable the script. Symmetric with the contract
+      // documented in `bin/brain-up` (which sets exactly `"1"`).
+      if (process.env[RELOAD_ENV_VAR] !== "1") {
+        return {}
+      }
+      return {
+        js: [
+          {
+            // brain: `afterDOMReady` so the script runs after
+            // `</body>` (see Quartz's `renderPage.tsx` for the
+            // dispatch). The poller doesn't touch the DOM at
+            // load time, and afterDOMReady avoids blocking
+            // initial paint on the network round-trip.
+            loadTime: "afterDOMReady",
+            // brain-extension: external script (URL src) rather
+            // than inline. The reload.js file is bundled into
+            // every build's `static/` dir by Quartz's stock
+            // `Plugin.Static()` emitter; pointing at it by URL
+            // keeps the script body out of every page's HTML.
+            contentType: "external",
+            src: RELOAD_SCRIPT_SRC,
+          },
+        ],
+      }
+    },
+  }
+}