v2: Quartz digital garden replaces the SPA; original URL re-routed

Date: 2026-09-01 Project: astro-starter-template (second-brain)

Decision

The Quartz digital garden (repo [usuario]/quartz, branch v4) is the site (v2). The old zero-framework SPA (site/, docs/cloud surfaces) is retired — kept in git history only.

Architecture (three steps in npm run build)

1. scripts/build.mjs — derive graph.json + curriculum.json (integrity gate).
2. scripts/garden.mjs — materialise vault into ~/Proyectos/quartz/content: nodes → notes, typed edges injected as [[slug|Title]] wikilinks, study docs cleaned (LaTeX frontmatter stripped, \newpage → hr), generated index.md home with all 18 tracks.
3. npx quartz build in the quartz repo → copy public/ → dist/.

Deploy unchanged: npm run deploy → wrangler assets ./dist → https://astro-starter-template.nef.workers.dev (account 162ab69a40524314530193e8a3e8f414). wrangler.jsonc now pins account_id (two accounts exist — deployment fails without it).

Quartz gotchas learned

• Wikilinks resolve against FILE SLUGS only — titles/aliases are NOT matched. [[Attention]] → ../Attention (broken) until rewritten to [[attention|Attention]] (linkify pass in garden.mjs).
• --serve --port 3001 clashes with the default WebSocket wsPort 3001 — always pass --wsPort 3002.
• baseUrl must be a valid URL (404 emitter throws “Invalid URL” on "").
• execFileSync/execSync live in node:child_process, not node:fs.
• The bash tool kills background processes on exit — long-running servers must be started via Terminal.app (osascript) by the user.
• Gray-matter frontmatter: never round-trip through stringify (dates→ISO).

Local dev

• npm run garden:dev (astro repo): sync vault + serve :3001 (Terminal window).
• Garden UI is es-ES; theme = paper-light + concept-green (graph identity).
• Old /docs + /cloud surfaces are gone; the garden’s graph view + search cover that experience.

Pending

• RSS feed is emitted (baseUrl set) — nothing subscribed yet.
• Custom OG images active (build ~15s); comment out if slow.