secondbrain-py 0.2.1__py3-none-any.whl

brain/quartz_overrides/quartz/util/path.ts

@@ -0,0 +1,358 @@
+// Sample Quartz v4 path utilities for brain vaults.
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/util/path.ts` by `brain vault render --overlay`,
+// replacing the stock upstream module verbatim.
+//
+// Tested against Quartz v4.5.x (April 2026). If a future Quartz version
+// changes the public API of this module — `transformInternalLink`,
+// `transformLink`, `slugifyFilePath`, etc. — pull the latest from
+// https://github.com/jackyzha0/quartz/blob/v4/quartz/util/path.ts and
+// re-apply the brain tweaks flagged below with `// brain:` comments.
+//
+// What this brain tweak does, and why: a Quartz build will crash with
+// `URIError: URI malformed` if any inline-HTML `href`/`src` (or any
+// markdown link target) contains a raw `%` not followed by valid
+// hex — typical for ERB / Liquid / Jinja template fragments embedded
+// in pasted email/HTML content (`<%= loginurl %>`, `{{ url }}`, etc.).
+// Stock Quartz calls `decodeURI(link)` directly, which throws on
+// malformed input. The brain patch wraps that single call in a
+// `safeDecodeURI` helper that catches `URIError` and returns the raw
+// string unchanged, so the build keeps going and the doc still
+// renders (the malformed `href` becomes an opaque link, but no crash).
+// Everything else in this file is upstream verbatim — diff against
+// upstream to see the brain delta isolated to two lines.
+import { slug as slugAnchor } from "github-slugger"
+import type { Element as HastElement } from "hast"
+import { clone } from "./clone"
+
+// this file must be isomorphic so it can't use node libs (e.g. path)
+
+export const QUARTZ = "quartz"
+
+/// Utility type to simulate nominal types in TypeScript
+type SlugLike<T> = string & { __brand: T }
+
+/** Cannot be relative and must have a file extension. */
+export type FilePath = SlugLike<"filepath">
+export function isFilePath(s: string): s is FilePath {
+  const validStart = !s.startsWith(".")
+  return validStart && _hasFileExtension(s)
+}
+
+/** Cannot be relative and may not have leading or trailing slashes. It can have `index` as it's last segment. Use this wherever possible is it's the most 'general' interpretation of a slug. */
+export type FullSlug = SlugLike<"full">
+export function isFullSlug(s: string): s is FullSlug {
+  const validStart = !(s.startsWith(".") || s.startsWith("/"))
+  const validEnding = !s.endsWith("/")
+  return validStart && validEnding && !containsForbiddenCharacters(s)
+}
+
+/** Shouldn't be a relative path and shouldn't have `/index` as an ending or a file extension. It _can_ however have a trailing slash to indicate a folder path. */
+export type SimpleSlug = SlugLike<"simple">
+export function isSimpleSlug(s: string): s is SimpleSlug {
+  const validStart = !(s.startsWith(".") || (s.length > 1 && s.startsWith("/")))
+  const validEnding = !endsWith(s, "index")
+  return validStart && !containsForbiddenCharacters(s) && validEnding && !_hasFileExtension(s)
+}
+
+/** Can be found on `href`s but can also be constructed for client-side navigation (e.g. search and graph) */
+export type RelativeURL = SlugLike<"relative">
+export function isRelativeURL(s: string): s is RelativeURL {
+  const validStart = /^\.{1,2}/.test(s)
+  const validEnding = !endsWith(s, "index")
+  return validStart && validEnding && ![".md", ".html"].includes(getFileExtension(s) ?? "")
+}
+
+export function isAbsoluteURL(s: string): boolean {
+  try {
+    new URL(s)
+  } catch {
+    return false
+  }
+  return true
+}
+
+export function getFullSlug(window: Window): FullSlug {
+  const res = window.document.body.dataset.slug! as FullSlug
+  return res
+}
+
+function sluggify(s: string): string {
+  return s
+    .split("/")
+    .map((segment) =>
+      segment
+        .replace(/\s/g, "-")
+        .replace(/&/g, "-and-")
+        .replace(/%/g, "-percent")
+        .replace(/\?/g, "")
+        .replace(/#/g, ""),
+    )
+    .join("/") // always use / as sep
+    .replace(/\/$/, "")
+}
+
+export function slugifyFilePath(fp: FilePath, excludeExt?: boolean): FullSlug {
+  fp = stripSlashes(fp) as FilePath
+  let ext = getFileExtension(fp)
+  const withoutFileExt = fp.replace(new RegExp(ext + "$"), "")
+  if (excludeExt || [".md", ".html", undefined].includes(ext)) {
+    ext = ""
+  }
+
+  let slug = sluggify(withoutFileExt)
+
+  // treat _index as index
+  if (endsWith(slug, "_index")) {
+    slug = slug.replace(/_index$/, "index")
+  }
+
+  return (slug + ext) as FullSlug
+}
+
+export function simplifySlug(fp: FullSlug): SimpleSlug {
+  const res = stripSlashes(trimSuffix(fp, "index"), true)
+  return (res.length === 0 ? "/" : res) as SimpleSlug
+}
+
+// brain: tolerant wrapper around `decodeURI`. ERB/Liquid/Jinja template
+// fragments pasted into ingested docs (`<%= loginurl %>`, `{{ url }}`,
+// etc.) hit Quartz's link transformer as inline-HTML `href` values and
+// crash the entire build with `URIError: URI malformed` on the lone `%`.
+// Falling back to the raw string lets the build complete; the malformed
+// link is an opaque slug that won't resolve to a vault page, but the
+// surrounding doc still renders and the rest of the corpus is unaffected.
+function safeDecodeURI(link: string): string {
+  try {
+    return decodeURI(link)
+  } catch {
+    return link
+  }
+}
+
+export function transformInternalLink(link: string): RelativeURL {
+  // brain: was `decodeURI(link)` upstream — see safeDecodeURI above.
+  let [fplike, anchor] = splitAnchor(safeDecodeURI(link))
+
+  const folderPath = isFolderPath(fplike)
+  let segments = fplike.split("/").filter((x) => x.length > 0)
+  let prefix = segments.filter(isRelativeSegment).join("/")
+  let fp = segments.filter((seg) => !isRelativeSegment(seg) && seg !== "").join("/")
+
+  // manually add ext here as we want to not strip 'index' if it has an extension
+  const simpleSlug = simplifySlug(slugifyFilePath(fp as FilePath))
+  const joined = joinSegments(stripSlashes(prefix), stripSlashes(simpleSlug))
+  const trail = folderPath ? "/" : ""
+  const res = (_addRelativeToStart(joined) + trail + anchor) as RelativeURL
+  return res
+}
+
+// from micromorph/src/utils.ts
+// https://github.com/natemoo-re/micromorph/blob/main/src/utils.ts#L5
+const _rebaseHtmlElement = (el: Element, attr: string, newBase: string | URL) => {
+  const rebased = new URL(el.getAttribute(attr)!, newBase)
+  el.setAttribute(attr, rebased.pathname + rebased.hash)
+}
+export function normalizeRelativeURLs(el: Element | Document, destination: string | URL) {
+  el.querySelectorAll('[href=""], [href^="./"], [href^="../"]').forEach((item) =>
+    _rebaseHtmlElement(item, "href", destination),
+  )
+  el.querySelectorAll('[src=""], [src^="./"], [src^="../"]').forEach((item) =>
+    _rebaseHtmlElement(item, "src", destination),
+  )
+}
+
+const _rebaseHastElement = (
+  el: HastElement,
+  attr: string,
+  curBase: FullSlug,
+  newBase: FullSlug,
+) => {
+  if (el.properties?.[attr]) {
+    if (!isRelativeURL(String(el.properties[attr]))) {
+      return
+    }
+
+    const rel = joinSegments(resolveRelative(curBase, newBase), "..", el.properties[attr] as string)
+    el.properties[attr] = rel
+  }
+}
+
+export function normalizeHastElement(rawEl: HastElement, curBase: FullSlug, newBase: FullSlug) {
+  const el = clone(rawEl) // clone so we dont modify the original page
+  _rebaseHastElement(el, "src", curBase, newBase)
+  _rebaseHastElement(el, "href", curBase, newBase)
+  if (el.children) {
+    el.children = el.children.map((child) =>
+      normalizeHastElement(child as HastElement, curBase, newBase),
+    )
+  }
+
+  return el
+}
+
+// resolve /a/b/c to ../..
+export function pathToRoot(slug: FullSlug): RelativeURL {
+  let rootPath = slug
+    .split("/")
+    .filter((x) => x !== "")
+    .slice(0, -1)
+    .map((_) => "..")
+    .join("/")
+
+  if (rootPath.length === 0) {
+    rootPath = "."
+  }
+
+  return rootPath as RelativeURL
+}
+
+export function resolveRelative(current: FullSlug, target: FullSlug | SimpleSlug): RelativeURL {
+  const res = joinSegments(pathToRoot(current), simplifySlug(target as FullSlug)) as RelativeURL
+  return res
+}
+
+export function splitAnchor(link: string): [string, string] {
+  let [fp, anchor] = link.split("#", 2)
+  if (fp.endsWith(".pdf")) {
+    return [fp, anchor === undefined ? "" : `#${anchor}`]
+  }
+  anchor = anchor === undefined ? "" : "#" + slugAnchor(anchor)
+  return [fp, anchor]
+}
+
+export function slugTag(tag: string) {
+  return tag
+    .split("/")
+    .map((tagSegment) => sluggify(tagSegment))
+    .join("/")
+}
+
+export function joinSegments(...args: string[]): string {
+  if (args.length === 0) {
+    return ""
+  }
+
+  let joined = args
+    .filter((segment) => segment !== "" && segment !== "/")
+    .map((segment) => stripSlashes(segment))
+    .join("/")
+
+  // if the first segment starts with a slash, add it back
+  if (args[0].startsWith("/")) {
+    joined = "/" + joined
+  }
+
+  // if the last segment is a folder, add a trailing slash
+  if (args[args.length - 1].endsWith("/")) {
+    joined = joined + "/"
+  }
+
+  return joined
+}
+
+export function getAllSegmentPrefixes(tags: string): string[] {
+  const segments = tags.split("/")
+  const results: string[] = []
+  for (let i = 0; i < segments.length; i++) {
+    results.push(segments.slice(0, i + 1).join("/"))
+  }
+  return results
+}
+
+export interface TransformOptions {
+  strategy: "absolute" | "relative" | "shortest"
+  allSlugs: FullSlug[]
+}
+
+export function transformLink(src: FullSlug, target: string, opts: TransformOptions): RelativeURL {
+  let targetSlug = transformInternalLink(target)
+
+  if (opts.strategy === "relative") {
+    return targetSlug as RelativeURL
+  } else {
+    const folderTail = isFolderPath(targetSlug) ? "/" : ""
+    const canonicalSlug = stripSlashes(targetSlug.slice(".".length))
+    let [targetCanonical, targetAnchor] = splitAnchor(canonicalSlug)
+
+    if (opts.strategy === "shortest") {
+      // if the file name is unique, then it's just the filename
+      const matchingFileNames = opts.allSlugs.filter((slug) => {
+        const parts = slug.split("/")
+        const fileName = parts.at(-1)
+        return targetCanonical === fileName
+      })
+
+      // only match, just use it
+      if (matchingFileNames.length === 1) {
+        const targetSlug = matchingFileNames[0]
+        return (resolveRelative(src, targetSlug) + targetAnchor) as RelativeURL
+      }
+    }
+
+    // if it's not unique, then it's the absolute path from the vault root
+    return (joinSegments(pathToRoot(src), canonicalSlug) + folderTail) as RelativeURL
+  }
+}
+
+// path helpers
+export function isFolderPath(fplike: string): boolean {
+  return (
+    fplike.endsWith("/") ||
+    endsWith(fplike, "index") ||
+    endsWith(fplike, "index.md") ||
+    endsWith(fplike, "index.html")
+  )
+}
+
+export function endsWith(s: string, suffix: string): boolean {
+  return s === suffix || s.endsWith("/" + suffix)
+}
+
+export function trimSuffix(s: string, suffix: string): string {
+  if (endsWith(s, suffix)) {
+    s = s.slice(0, -suffix.length)
+  }
+  return s
+}
+
+function containsForbiddenCharacters(s: string): boolean {
+  return s.includes(" ") || s.includes("#") || s.includes("?") || s.includes("&")
+}
+
+function _hasFileExtension(s: string): boolean {
+  return getFileExtension(s) !== undefined
+}
+
+export function getFileExtension(s: string): string | undefined {
+  return s.match(/\.[A-Za-z0-9]+$/)?.[0]
+}
+
+function isRelativeSegment(s: string): boolean {
+  return /^\.{0,2}$/.test(s)
+}
+
+export function stripSlashes(s: string, onlyStripPrefix?: boolean): string {
+  if (s.startsWith("/")) {
+    s = s.substring(1)
+  }
+
+  if (!onlyStripPrefix && s.endsWith("/")) {
+    s = s.slice(0, -1)
+  }
+
+  return s
+}
+
+function _addRelativeToStart(s: string): string {
+  if (s === "") {
+    s = "."
+  }
+
+  if (!s.startsWith(".")) {
+    s = joinSegments(".", s)
+  }
+
+  return s
+}

brain/quartz_overrides/quartz/util/sourceIcons.ts

@@ -0,0 +1,55 @@
+// Brain shared source-icon vocabulary — Phase 3.3 of the Wiki UX Overhaul.
+//
+// This file is a TEMPLATE. It is installed at
+// `<vault>/.quartz/quartz/util/sourceIcons.ts` by `brain vault render
+// --overlay`. It does NOT compile or run from the brain repo itself;
+// imports are resolved by the cloned Quartz workspace.
+//
+// Why this exists: P3.2 hard-coded the source-icon table at module
+// scope inside `Search.tsx` (and a fallback copy inside
+// `search.inline.ts`). P3.3 needs the same vocabulary on the
+// server-rendered tag-content rows. Rather than copy a third time, we
+// factor the table into this small util module so a future ingest
+// source (e.g. notion) is a single-line change. Search, TagContent,
+// RelatedDocs, and CommandPalette all import this canonical table.
+
+// brain: source-icon mapping. Adding a key here is necessary but not
+// sufficient — source chip styles and any source-specific palettes must
+// also gain the new entry. Static tests keep the consumers in lockstep.
+export const SOURCE_ICONS: Record<string, string> = {
+  gmail: "📧",
+  krisp: "🎙️",
+  slack: "💬",
+  manual: "✍️",
+  vault: "🌱",
+}
+
+// brain: ordered chip vocabulary — render order for any UI surface
+// that lists every source. Pinned (vs derived from the index) so the
+// rail renders identically when the live corpus is missing a source.
+export const SOURCE_CHIP_ORDER: ReadonlyArray<keyof typeof SOURCE_ICONS> = [
+  "krisp",
+  "slack",
+  "gmail",
+  "manual",
+  "vault",
+] as const
+
+// brain: fall back to a slug-based source classification when the
+// emitter's frontmatter lift didn't graft a `source` field (e.g.
+// legacy entries written before P1.5). Mirrors the heuristic the
+// contentIndex post-processor uses (`slug.startsWith("_ingested/")`
+// ⇒ ingested-tier; the next path segment is the source).
+export function inferSource(slug: string, source: string | undefined): string {
+  if (typeof source === "string" && source.length > 0) return source
+  const match = slug.match(/^_ingested\/([^/]+)\//)
+  if (match) return match[1]
+  return "vault"
+}
+
+// brain: glyph lookup with a "vault" default fallback. Centralised so
+// every consumer (Search row, tag-content row, future notebook chip,
+// …) renders the same character even when the source is unrecognised.
+export function sourceIconFor(source: string): string {
+  return SOURCE_ICONS[source] ?? SOURCE_ICONS["vault"]
+}

brain/quartz_overrides/quartz.config.ts

@@ -0,0 +1,270 @@
+// Sample Quartz v4 configuration for brain vaults.
+//
+// This file is a TEMPLATE. Copy it into your Quartz workspace as
+// `<vault>/.quartz/quartz.config.ts` after cloning Quartz with
+// `git clone https://github.com/jackyzha0/quartz.git <vault>/.quartz`.
+// 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
+// renames a plugin or its option shape, pull the latest config from
+// https://quartz.jzhao.xyz/ and re-apply the brain-specific tweaks
+// flagged below with `// brain:` comments.
+//
+// brain: this template wires up two brain-specific transformers:
+//
+//   * `Plugin.DerivedFenceMark` (defined in
+//     `<vault>/.quartz/quartz/plugins/transformers/derivedFenceMark.ts`,
+//     installed by `brain vault render --overlay`). It must run after
+//     `Plugin.ObsidianFlavoredMarkdown()` so `[[wiki-link]]` syntax
+//     has been converted into mdast `link` nodes by the time the
+//     fence walker stamps `data-brain-derived` attributes on them.
+//     See the transformer's top-of-file comment for the full contract.
+//
+//   * `Plugin.ReloadSignal` (defined in
+//     `<vault>/.quartz/quartz/plugins/transformers/reloadSignal.ts`,
+//     also installed by the overlay). Injects an ETag-aware polling reload
+//     `<script>` into every page when `BRAIN_WIKI_RELOAD=1` is set in
+//     the build env — replaces Quartz's `--serve` WebSocket reload
+//     path, which is dead in the brain blue-green serve flow because
+//     Caddy (not Quartz) serves the static output. See the
+//     transformer's top-of-file comment for the full contract.
+
+import { QuartzConfig } from "./quartz/cfg"
+import * as Plugin from "./quartz/plugins"
+
+const config: QuartzConfig = {
+  configuration: {
+    // brain: friendlier title than the default "Quartz 4".
+    pageTitle: "Second Brain",
+    pageTitleSuffix: "",
+    enableSPA: true,
+    enablePopovers: true,
+    // brain: analytics off — the wiki is private and rendered locally.
+    // If you deploy the static output somewhere public, set this to your
+    // provider of choice (plausible, google, umami, etc.).
+    analytics: null,
+    locale: "en-US",
+    // brain: localhost for dev; flip to your domain before deploying.
+    baseUrl: "localhost:8080",
+    // brain: skip tooling-managed folders. `_templates` / `_attachments`
+    // are brain conventions; `.quartz` is the workspace itself; `dist` /
+    // `public` are build outputs that must NOT be re-walked as content.
+    ignorePatterns: [
+      "private",
+      "_templates",
+      "_attachments",
+      // brain: P4.7 — server-rendered partials (e.g. `_partials/recent.md`,
+      // the source-of-truth for the home-page "Recently captured" rail) live
+      // outside the public surface. The home note renders them inline via
+      // a fence; the partial itself must never appear as its own page.
+      "_partials",
+      "dist",
+      "public",
+      ".obsidian",
+      ".git",
+      ".quartz",
+    ],
+    defaultDateType: "modified",
+    theme: {
+      fontOrigin: "googleFonts",
+      cdnCaching: true,
+      // brain: Linear-style typography for the tech-forward variant of
+      // the 2026 redesign. Geist (Vercel's grotesk) for both display and
+      // body — clean, neutral, modern; Geist Mono for code and metadata.
+      // Both are on Google Fonts; Quartz's Google Fonts loader uses the
+      // family name verbatim.
+      typography: {
+        header: "Geist",
+        body: "Geist",
+        code: "Geist Mono",
+      },
+      // brain: Linear-style charcoal + indigo-violet palette. Dark mode
+      // is the headline aesthetic — Linear lives in dark — but light mode
+      // is a clean pure-neutral zinc scale for daytime reading.
+      colors: {
+        lightMode: {
+          light: "#ffffff",
+          lightgray: "#e4e4e7",
+          // brain: zinc-500 (#71717a) clears WCAG AA against pure white
+          // bg for muted text, metadata, dingbats.
+          gray: "#71717a",
+          darkgray: "#3f3f46",
+          dark: "#09090b",
+          secondary: "#5e6ad2",
+          tertiary: "#8b5cf6",
+          highlight: "rgba(94, 106, 210, 0.12)",
+          textHighlight: "#fde047b3",
+        },
+        darkMode: {
+          light: "#0a0a0a",
+          lightgray: "#27272a",
+          // brain: zinc-400 (#a1a1aa) clears WCAG AA against #0a0a0a.
+          gray: "#a1a1aa",
+          darkgray: "#d4d4d8",
+          dark: "#fafafa",
+          secondary: "#7170ff",
+          tertiary: "#a78bfa",
+          highlight: "rgba(113, 112, 255, 0.18)",
+          textHighlight: "#fde04766",
+        },
+      },
+    },
+  },
+  plugins: {
+    transformers: [
+      Plugin.FrontMatter(),
+      Plugin.CreatedModifiedDate({
+        priority: ["frontmatter", "git", "filesystem"],
+      }),
+      Plugin.SyntaxHighlighting({
+        theme: { light: "github-light", dark: "github-dark" },
+        keepBackground: false,
+      }),
+      Plugin.ObsidianFlavoredMarkdown({ enableInHtmlEmbed: false }),
+      // brain: tag derived-edge `<a>` tags inside Phase D fences with
+      // `data-brain-derived` / `data-brain-rule` / `data-brain-weight`
+      // so the custom contentIndex emitter can classify them as
+      // `kind: "derived"` in `static/contentIndex.json`. Must run after
+      // ObsidianFlavoredMarkdown so wiki-link syntax has already been
+      // converted to mdast link nodes.
+      Plugin.DerivedFenceMark(),
+      // brain: Lane B redesign — classify every mdast link node into
+      // one of five kinds (wiki / external / tag / ingested / derived)
+      // and stamp `data-brain-link-kind` on `node.data.hProperties`.
+      // The Lane B `_links.scss` consumes that attribute to give each
+      // kind a distinct visual treatment (terracotta underline / dotted
+      // + arrow / pill chip / source-tinted left rail / italic dashed).
+      // Must run AFTER `ObsidianFlavoredMarkdown` (so wiki-link mdast
+      // nodes exist) AND AFTER `DerivedFenceMark` (so its
+      // `data-brain-derived` stamp is already in place — the
+      // classifier reads it to short-circuit the kind to `derived`).
+      // See `quartz/plugins/transformers/linkKindMark.ts` for the
+      // full classification contract.
+      Plugin.LinkKindMark(),
+      // brain: Lane B redesign — inject the runtime source-tagger
+      // (`/static/linkSourceTag.js`) into every page. The tagger
+      // extracts the source segment from `_ingested/<source>/...`
+      // hrefs at `DOMContentLoaded` (and on Quartz SPA `nav` events)
+      // and stamps `data-brain-source="krisp"` etc. on each ingested
+      // link, so `_links.scss`'s source-tinted left-rail rules
+      // (`&[data-brain-source="krisp"]`) can pick the right
+      // `--brain-source-*` color from `_tokens.scss`. Always emits
+      // (no env-var gate, unlike `ReloadSignal`) — the script is part
+      // of the production redesign. No markdown ordering requirement;
+      // grouped here next to `LinkKindMark` so the Lane B plugins
+      // stay co-located. See `quartz/plugins/transformers/linkSourceTag.ts`
+      // for the inject contract and the static script for the
+      // tagging logic.
+      Plugin.LinkSourceTag(),
+      // brain: Recent rail — inject the live relative-date recomputer
+      // (`/static/relativeDate.js`) into every page. The home-page Recent
+      // rail emits `<span class="brain-rel-date" data-date="<ISO>">{abs}</span>`
+      // (see `brain.wiki.build_homepage`); this script reads each
+      // `data-date` and recomputes the relative text ("3d ago") live on
+      // `DOMContentLoaded` + Quartz SPA `nav`, so the rail never decays
+      // between daily builds. Bucket logic mirrors
+      // `build_homepage._format_relative_date`. Always emits (no env-var
+      // gate, like `LinkSourceTag`); no markdown ordering requirement;
+      // grouped here next to `LinkSourceTag` so the brain script-only
+      // transformers stay co-located. See
+      // `quartz/plugins/transformers/relativeDate.ts` for the inject
+      // contract and `quartz/static/relativeDate.js` for the recomputer.
+      Plugin.RelativeDate(),
+      // brain: Lane C redesign — inject the runtime code-copy injector
+      // (`/static/codeCopy.js`) into every page. The injector walks
+      // every `<pre>` in the article body, lifts the `data-language`
+      // attribute from the inner `<code>` to the outer `<pre>` (so
+      // the CSS-only language label in `_code.scss` can read it via
+      // `attr()`), and appends a brain-themed `.brain-code-copy`
+      // button. Stock Quartz's `.clipboard-button` is hidden via
+      // `_code.scss` so the two don't render side-by-side. Always
+      // emits (no env-var gate, like `LinkSourceTag`) — the script is
+      // part of the production redesign. No markdown ordering
+      // requirement; grouped here next to `LinkSourceTag` so the
+      // brain script-only transformers stay co-located. See
+      // `quartz/plugins/transformers/codeCopy.ts` for the inject
+      // contract and `quartz/static/codeCopy.js` for the injector.
+      Plugin.CodeCopy(),
+      // brain: P4.4 — inject 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
+      // (a) annotates each per-message section in an `email_thread`
+      // body with `data-brain-thread-from` + `data-brain-is-mine`,
+      // and (b) renders a "Show only my replies" filter button at
+      // the top of `<article>` that toggles the
+      // `body.brain-replies-only` class — the SCSS partial
+      // `_email_thread.scss` then hides every
+      // `[data-brain-is-mine="false"]` section. Always emits (no
+      // env-var gate, like `LinkSourceTag` and `CodeCopy`) — the
+      // runtime is part of the production redesign and self-gates on
+      // an `_ingested/gmail/` URL pathname. No markdown ordering
+      // requirement; grouped here next to `CodeCopy` so the brain
+      // script-only transformers stay co-located. See
+      // `quartz/plugins/transformers/emailThread.ts` for the inject
+      // contract and `quartz/static/emailThread.js` for the runtime
+      // logic.
+      Plugin.EmailThreadReader(),
+      // brain: inject the ETag-aware reload watcher (`/static/reload.js`)
+      // into every page when `BRAIN_WIKI_RELOAD=1` at build time.
+      // Replaces Quartz's `--serve` WebSocket reload, which is dead in
+      // our blue-green serve flow because Caddy (not Quartz) is the
+      // static file server. `bin/brain-up` sets the env var; `brain
+      // vault render` (prod path) leaves it unset so prod pages ship
+      // without a polling client. The transformer has no markdown
+      // ordering requirement — it only contributes a `<script>` tag
+      // via `externalResources()` — but is grouped here next to
+      // `DerivedFenceMark` so the two brain-extension transformers
+      // stay co-located.
+      Plugin.ReloadSignal(),
+      Plugin.GitHubFlavoredMarkdown(),
+      Plugin.TableOfContents(),
+      // brain: Lane B redesign — `externalLinkIcon: false` disables
+      // Quartz's stock inline-SVG `↗` arrow on external links. The Lane B
+      // `_links.scss` paints its own `↗` via `::after` on
+      // `a[data-brain-link-kind="external"]` so the color/opacity track
+      // the redesign tokens; leaving stock's icon enabled would render
+      // every external link with two arrows side-by-side.
+      Plugin.CrawlLinks({ markdownLinkResolution: "shortest", externalLinkIcon: false }),
+      // brain: P4.1 — strip home-page `<li>`s whose link resolves to an
+      // empty folder (today: `daily/` when the user hasn't created any
+      // daily notes yet). Generic — extend the `folders` option to
+      // protect future top-level subdirs (e.g. a hypothetical
+      // `workbench/`) from the same 404. Must run AFTER `CrawlLinks` so
+      // the rehype-stage `<a href>`s have already been resolved to the
+      // shape the matcher expects (`daily/`, `daily/index`, …); without
+      // that ordering the matcher's normalizer sees raw markdown URLs
+      // and mis-classifies. The transformer reads `ctx.argv.directory`
+      // once per build to compute which folders are empty.
+      Plugin.EmptyDoorFilter(),
+      Plugin.Description(),
+      // strict: "ignore" suppresses KaTeX strict-mode build warnings for
+      // typographic chars (en/em-dashes, », ¢) in math contexts — cosmetic
+      // only, rendering unchanged.
+      Plugin.Latex({ renderEngine: "katex", katexOptions: { strict: "ignore" } }),
+    ],
+    filters: [Plugin.RemoveDrafts()],
+    emitters: [
+      Plugin.AliasRedirects(),
+      Plugin.ComponentResources(),
+      Plugin.ContentPage(),
+      Plugin.FolderPage(),
+      Plugin.TagPage(),
+      Plugin.ContentIndex({
+        enableSiteMap: true,
+        enableRSS: true,
+      }),
+      Plugin.Assets(),
+      Plugin.Static(),
+      Plugin.NotFoundPage(),
+      // brain: the graph view is the killer feature for an Obsidian-style
+      // vault. The actual graph rendering happens via `Component.Graph(...)`
+      // in `quartz.layout.ts`; there is no `Plugin.Graph` emitter in stock
+      // Quartz v4.5.x — only the component is needed here.
+    ],
+  },
+}
+
+export default config