blume 1.5.2 → 1.6.0

package/src/astro/templates.ts

@@ -8,6 +8,7 @@ import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
 import { buildHomeLinkHeader } from "../ai/link-headers.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
+import { TOC_HIDDEN_KEY } from "../core/heading-markers.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import { trimChar } from "../core/trim.ts";
@@ -16,7 +17,7 @@ import { applyBaseToAstroRedirects } from "../deploy/redirects.ts";
 import type { OgFont, OgFontFamilies } from "../og/card.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
-import { buildFontEntries } from "../theme/fonts.ts";
+import { buildFontEntries, fontLocaleCodes } from "../theme/fonts.ts";
 import type { ExampleSpec } from "./examples.ts";
 import type { BlumePageRoute } from "./integration.ts";
 import type { IslandSpec } from "./islands.ts";
@@ -307,35 +308,6 @@ const reactIntegration = (compilerPath: string | null | undefined): string =>
     ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] }, ${REACT_EXCLUDE} })`
     : `react({ ${REACT_EXCLUDE} })`;
 
-/**
- * The `server.watch` block for the generated dev config. Keeps the watcher out
- * of Astro's cache dir — but ONLY when the docs collection is rooted at a
- * directory containing the runtime dir (a migrated, `content.root: "."`
- * project). There, the glob loader's watcher match (`picomatch.isMatch(entry,
- * pattern)` with array-OR semantics, where any negated pattern matches
- * unrelated files) fires on every `.blume/.astro` write — "No entry type
- * found" noise, and a `data-store.json` event can re-ingest the store file as
- * a JSON entry and loop the sync. Everywhere else the watcher MUST see
- * `.astro/data-store.json`: its change events are the only trigger for
- * Astro's dev-time content invalidation (see vite-plugin-content-virtual-mod),
- * and `.md` bodies are rendered into the store at load time — so ignoring the
- * file serves stale `.md` HTML on every request until the server restarts,
- * even though the loader logs a reload.
- */
-const devWatchOption = (
-  outDir: string,
-  contentWatchesRuntimeDir: boolean | undefined
-): string =>
-  contentWatchesRuntimeDir
-    ? `
-      // Astro's cache dir sits inside the docs collection, whose watcher would
-      // otherwise churn (and can loop) on Astro's own writes. Trade-off: .md
-      // body edits need a dev-server restart in this layout.
-      watch: {
-        ignored: ${JSON.stringify([join(outDir, ".astro", "**")])},
-      },`
-    : "";
-
 interface IntegrationBridgeOptions {
   /** Config path relative to the generated Astro config. */
   configFile: string;
@@ -387,8 +359,11 @@ interface OptimizeDepsConfig {
  * the Vite root is the generated runtime, so user pages, convention islands,
  * and alias-reachable components all live outside it and are otherwise only
  * crawled when first requested. The compiler runtime rides the include list
- * because it is Babel-injected and no source scan can see it. See the
- * optimizeDeps comment in the generated config for the failure this prevents.
+ * because it is Babel-injected and no source scan can see it. @vitejs/plugin-react
+ * would add it itself, but only when the babel plugin is passed by its bare
+ * name (`getReactCompilerPlugin` is an exact string match) — Blume passes an
+ * absolute path (see `reactIntegration`), which that check never matches. See
+ * the optimizeDeps comment in the generated config for the failure this prevents.
  */
 const resolveOptimizeDeps = (options: {
   aliases: Record<string, string> | undefined;
@@ -445,12 +420,10 @@ export const astroConfigTemplate = (options: {
   /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
   aliases?: Record<string, string>;
   /**
-   * Whether the filesystem `docs` collection is rooted at a directory that
-   * contains the runtime dir (a migrated, `content.root: "."` project) — the
-   * only layout where the dev watcher must be kept out of Astro's cache dir.
-   * See {@link devWatchOption} for why this must stay scoped.
+   * The docs collection's content root; bounds `<include>` resolution in the
+   * processors and locates the include graph for dev-server invalidation.
    */
-  contentWatchesRuntimeDir?: boolean;
+  contentRoot?: string;
   /** Bridge used to load configured integrations without serializing them. */
   integrationBridge?: IntegrationBridgeOptions;
 }): string => {
@@ -552,7 +525,12 @@ export const astroConfigTemplate = (options: {
   // `fontProviders` is only imported when at least one font is configured.
   // Local variant sources are emitted as absolute paths (the Astro root is
   // `.blume/`, not the user's project, so root-relative paths would miss).
-  const fontEntries = buildFontEntries(config.theme.fonts);
+  // Subsets follow the configured locales (a Vietnamese site loads the
+  // `vietnamese` faces) unless a family pins its own.
+  const fontEntries = buildFontEntries(
+    config.theme.fonts,
+    fontLocaleCodes(config.i18n)
+  );
   const fontsOption = fontEntries.length
     ? `\n  fonts: [${fontEntries
         .map((font) =>
@@ -588,6 +566,8 @@ export const astroConfigTemplate = (options: {
                 font.cssVariable
               )}, weights: ${JSON.stringify(
                 font.weights
+              )}, subsets: ${JSON.stringify(
+                font.subsets
               )}, fallbacks: ${JSON.stringify(font.fallbacks)} }`
         )
         .join(", ")}],`
@@ -606,8 +586,8 @@ export const astroConfigTemplate = (options: {
     : "";
   const blumeImports = [
     "blumeIntegration",
+    "includeHmrPlugin",
     "prerenderDepsPlugin",
-    "serverAppResolvePlugin",
     ...(adapterOption.includes("withAdapterRoot") ? ["withAdapterRoot"] : []),
   ];
   const blumeImport = `import { ${blumeImports.join(", ")} } from "blume/astro";\n`;
@@ -632,6 +612,7 @@ export const astroConfigTemplate = (options: {
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
       basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
+      contentRoot: options.contentRoot,
       deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}) })`,
@@ -657,10 +638,6 @@ export const astroConfigTemplate = (options: {
     })})`
   );
 
-  const watchOption = devWatchOption(
-    context.outDir,
-    options.contentWatchesRuntimeDir
-  );
   const {
     configSourceMarker,
     userConfigImports,
@@ -685,6 +662,7 @@ ${userConfigSetup}export default defineConfig({
     processor: blumeMarkdownProcessor(${JSON.stringify({
       basePath: config.basePath,
       codeThemes: config.markdown.codeBlocks.theme,
+      contentRoot: options.contentRoot,
       deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}),
@@ -706,7 +684,9 @@ ${userConfigSetup}export default defineConfig({
   // instantly.
   prefetch: { prefetchAll: true },
   vite: {
-    plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
+    plugins: [tailwindcss(), includeHmrPlugin(${JSON.stringify(
+      `${context.outDir}/src/generated/includes.json`
+    )}), prerenderDepsPlugin()],
     // Everything hydration can reach must be part of the dev dep optimizer's
     // FIRST run. The Vite root is the generated runtime, so user pages,
     // islands, and aliased components live outside it and are only crawled
@@ -764,7 +744,7 @@ ${userConfigSetup}export default defineConfig({
     server: {
       fs: {
         allow: ${JSON.stringify(fsAllow)},
-      },${watchOption}
+      },
     },
   },
 });
@@ -778,14 +758,11 @@ export const stagedContentDir = (outDir: string): string =>
 /**
  * The runtime dir relative to the docs collection `base` when it sits inside
  * it (a migrated, `content.root: "."` project) — null when it lives elsewhere.
- * Drives both the collection's negative glob (`contentConfigTemplate`) and
- * whether the dev watcher is kept out of Astro's cache dir (the
- * `contentWatchesRuntimeDir` option of `astroConfigTemplate`).
+ * Drives the collection's negative glob in `contentConfigTemplate`, which both
+ * keeps runtime-dir files out of the collection and (Astro's watcher honors
+ * negated patterns) keeps the content watcher off Astro's own `.astro` writes.
  */
-export const runtimeDirWithin = (
-  base: string,
-  outDir: string
-): string | null => {
+const runtimeDirWithin = (base: string, outDir: string): string | null => {
   const rel = relative(base, outDir);
   return rel && !rel.startsWith("..") && !isAbsolute(rel) ? rel : null;
 };
@@ -836,15 +813,11 @@ export const contentConfigTemplate = (options: {
   const outDirRel = runtimeDirWithin(collectionBase, context.outDir);
   const outDirIgnore = outDirRel ? [`!${outDirRel}/**`] : [];
 
-  // With no filesystem source, no route renders through `docs`, so glob nothing.
-  // Beyond skipping wasted work, this is the only thing that keeps Astro's
-  // content-layer *watcher* out of `.blume/`: an all-staged project roots the
-  // collection at the project dir (which contains `.blume/.astro/fonts`, rewritten on every
-  // request), and the watcher's match test is `picomatch.isMatch(path, pattern)`
-  // — with array-OR semantics, any `!ignored/**` negation *matches* unrelated
-  // files, so negative patterns can't exclude a subtree there. An empty pattern
-  // matches nothing, so the watcher stays silent. The collection is still
-  // declared below so `getCollection("docs")` / `getEntry` resolve (to empty).
+  // With no filesystem source, no route renders through `docs`, so glob
+  // nothing: an all-staged project roots the collection at the project dir,
+  // and a patterned glob would scan (and watch) the whole project for nothing.
+  // The collection is still declared below so `getCollection("docs")` /
+  // `getEntry` resolve (to empty).
   const filesystem = options.filesystem ?? true;
   const docsPattern = filesystem
     ? [
@@ -880,13 +853,17 @@ const staged = defineCollection({
   return `// Generated by Blume. Do not edit.
 import { defineCollection } from "astro:content";
 import { glob } from "astro/loaders";
+import { withIncludeRefresh } from "blume/astro";
 
+// withIncludeRefresh keeps <include>-bearing pages fresh: plain .md entries
+// are rendered at sync time and digest-cached on the page file alone, so a
+// partial edit (or a warm-cache rebuild after one) would serve stale HTML.
 const docs = defineCollection({
-  loader: glob({
+  loader: withIncludeRefresh(glob({
     pattern: ${JSON.stringify(docsPattern)},
     base: ${JSON.stringify(astroGlobBase(collectionBase))},
     generateId: ({ entry }) => entry,
-  }),
+  }), ${JSON.stringify(`${context.outDir}/src/generated/includes.json`)}),
 });
 ${stagedBlock}
 export const collections = { docs${options.staged ? ", staged" : ""} };
@@ -1560,10 +1537,11 @@ export function getStaticPaths() {
   return paths;
 }
 
-// Footer branding shared by every card. The repo slug reuses the header link
-// URL; the site text (host plus deployment base) is resolved at generate time.
-const repoSlug = data.config.repoUrl
-  ? data.config.repoUrl.split("github.com/")[1]
+// Footer branding shared by every card. The slug comes from the configured
+// repo rather than the URL, so an Enterprise host reads the same as github.com;
+// the site text (host plus deployment base) is resolved at generate time.
+const repoSlug = data.config.github
+  ? \`\${data.config.github.owner}/\${data.config.github.repo}\`
   : undefined;
 
 export async function GET({ props }: { props: { title: string } }) {
@@ -1786,7 +1764,18 @@ const entry = await getEntry(collection as CollectionKey, entryId);
 if (!entry) {
   return new Response(null, { status: 404 });
 }
-const { Content, headings } = await render(entry);
+const { Content, headings: allHeadings, remarkPluginFrontmatter } = await render(entry);
+// \`[!toc]\`-marked headings render on the page but stay out of the table of
+// contents; the heading plugin reports their slugs through the render's
+// frontmatter (see markdown/heading-anchors.ts). Only the plugin's array
+// counts: \`frontmatter.extend\` can declare the same key, and on a page with
+// no headings that user-supplied value would pass straight through.
+const tocHiddenRaw = remarkPluginFrontmatter?.${TOC_HIDDEN_KEY};
+const tocHidden = new Set(Array.isArray(tocHiddenRaw) ? tocHiddenRaw : []);
+const headings =
+  tocHidden.size > 0
+    ? allHeadings.filter((heading) => !tocHidden.has(heading.slug))
+    : allHeadings;
 const frontmatter = entry.data ?? {};
 
 const seo = frontmatter.seo ?? {};
@@ -2312,6 +2301,7 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
  */
 export const notFoundPageTemplate = (): string => `---
 // Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
+import Icon from "blume/components/Icon.astro";
 import PageLayout from "blume/components/layout/PageLayout.astro";
 import { withBase } from "blume/components/islands/base-path.ts";
 import data from "blume:data";
@@ -2329,6 +2319,24 @@ const localeMeta = i18n
   : null;
 const dir = localeMeta?.dir ?? "ltr";
 const htmlLang = i18n ? i18n.defaultLocale : "en";
+
+// Recovery links, so a reader — or an agent that followed a stale URL — can
+// get back on track without guessing: every top-level section, then the
+// machine-readable indexes the build emits (the sitemap only exists with a
+// \`deployment.site\`; llms.txt only when \`ai.llmsTxt\` is on). Tabs link to
+// their resolved target when the section has no index page of its own.
+const suggestions = [
+  ...data.navigation.tabs.map((tab) => ({
+    href: withBase(tab.href ?? tab.path),
+    label: tab.label,
+  })),
+  ...(data.config.discovery.sitemap
+    ? [{ href: withBase("/sitemap.xml"), label: nf.sitemap }]
+    : []),
+  ...(data.config.discovery.llmsTxt
+    ? [{ href: withBase("/llms.txt"), label: nf.llms }]
+    : []),
+];
 ---
 
 <PageLayout
@@ -2349,15 +2357,56 @@ const htmlLang = i18n ? i18n.defaultLocale : "en";
   noindex={true}
 >
   <div
-    class="mx-auto flex min-h-[60vh] max-w-2xl flex-col items-center justify-center gap-4 px-6 py-24 text-center"
+    class="mx-auto grid w-full max-w-5xl gap-12 px-6 py-20 sm:py-28 md:grid-cols-[3fr_2fr] md:gap-16 lg:gap-24 lg:py-36"
   >
-    <p class="text-6xl font-bold text-muted-foreground">404</p>
-    <h1 class="text-2xl font-semibold text-foreground">{nf.title}</h1>
-    <p class="text-muted-foreground">{nf.description}</p>
-    <a
-      class="mt-2 rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-foreground"
-      href={withBase("/")}>{nf.home}</a
-    >
+    <div class="flex flex-col items-start">
+      <p
+        class="font-mono text-xs font-medium tracking-widest text-muted-foreground"
+      >
+        404
+      </p>
+      <h1
+        class="mt-4 text-balance text-4xl font-semibold tracking-tight text-foreground sm:text-5xl"
+      >
+        {nf.title}
+      </h1>
+      <p class="mt-4 max-w-md text-pretty text-lg text-muted-foreground">
+        {nf.description}
+      </p>
+      <a
+        class="mt-8 inline-flex items-center gap-1.5 rounded-full bg-accent py-2 pe-4 ps-3.5 text-sm font-medium text-accent-foreground transition-opacity hover:opacity-90"
+        href={withBase("/")}
+      >
+        <Icon class="rtl:-scale-x-100" name="arrow-left" size={14} />
+        {nf.home}
+      </a>
+    </div>
+    {
+      suggestions.length > 0 && (
+        <nav aria-label={nf.suggestions} class="md:border-s md:border-border md:ps-12 lg:ps-16">
+          <h2 class="text-xs font-medium uppercase tracking-widest text-muted-foreground">
+            {nf.suggestions}
+          </h2>
+          <ul class="mt-4 divide-y divide-border border-y border-border">
+            {suggestions.map((link) => (
+              <li>
+                <a
+                  class="group flex items-center justify-between gap-4 py-3 text-sm font-medium text-foreground transition-colors hover:text-accent"
+                  href={link.href}
+                >
+                  <span>{link.label}</span>
+                  <Icon
+                    class="shrink-0 text-muted-foreground transition-transform group-hover:translate-x-0.5 rtl:-scale-x-100 rtl:group-hover:-translate-x-0.5"
+                    name="arrow-right"
+                    size={14}
+                  />
+                </a>
+              </li>
+            ))}
+          </ul>
+        </nav>
+      )
+    }
   </div>
 </PageLayout>
 `;

package/src/cli/commands/build.ts

@@ -25,6 +25,7 @@ import {
   buildSkillsIndex,
   collectSkills,
 } from "../../ai/skills.ts";
+import type { SkillArtifact } from "../../ai/skills.ts";
 import {
   buildSignaturesDirectory,
   SIGNATURES_DIRECTORY_PATH,
@@ -46,6 +47,11 @@ import {
   injectWorkerNegotiation,
   NEGOTIATION_WORKER_FILE,
 } from "../../deploy/cloudflare-negotiation.ts";
+import {
+  auditVercelFunctions,
+  blumeDependencyNames,
+  functionBundleVerdict,
+} from "../../deploy/function-bundle.ts";
 import { buildNetlifyHeaders } from "../../deploy/headers.ts";
 import {
   buildNetlifyRedirects,
@@ -195,29 +201,29 @@ export const emitHeaderFiles = async (
 };
 
 /**
- * Publish the configured Agent Skills: copy each skill artifact under
- * `.well-known/agent-skills/` and emit the discovery index. A user-shipped
- * `public/.well-known/agent-skills/index.json` takes over the whole surface,
- * matching every other generated artifact.
+ * Collect the Agent Skills `ai.skills` publishes, once per build, so both the
+ * skills surface and llms.txt (which lists them) read the same set. Empty
+ * when the feature is off, the directory is missing, nothing in it is
+ * publishable (each with a warning), or a user-shipped
+ * `public/.well-known/agent-skills/index.json` already owns the surface.
  */
-const emitAgentSkills = async (
+const collectConfiguredSkills = async (
   project: BlumeProject,
   distDir: string
-): Promise<void> => {
+): Promise<SkillArtifact[]> => {
   const configured = project.config.ai.skills;
   if (!configured) {
-    return;
+    return [];
   }
   const dir = resolve(project.context.root, configured);
   if (!existsSync(dir)) {
     logger.warn(
       `ai.skills points at "${configured}" (${dir}), which does not exist; no skills published.`
     );
-    return;
+    return [];
   }
-  const outDir = join(distDir, AGENT_SKILLS_DIR.slice(1));
-  if (existsSync(join(outDir, "index.json"))) {
-    return;
+  if (existsSync(join(distDir, AGENT_SKILLS_DIR.slice(1), "index.json"))) {
+    return [];
   }
   const { skills, warnings } = await collectSkills(dir);
   for (const warning of warnings) {
@@ -225,8 +231,26 @@ const emitAgentSkills = async (
   }
   if (skills.length === 0) {
     logger.warn(`ai.skills: no publishable skills found in "${configured}".`);
+  }
+  return skills;
+};
+
+/**
+ * Publish the collected Agent Skills: copy each skill artifact under
+ * `.well-known/agent-skills/` and emit the discovery index. A user-shipped
+ * `public/.well-known/agent-skills/index.json` takes over the whole surface
+ * (the collector returns nothing then), matching every other generated
+ * artifact.
+ */
+const emitAgentSkills = async (
+  project: BlumeProject,
+  distDir: string,
+  skills: readonly SkillArtifact[]
+): Promise<void> => {
+  if (skills.length === 0) {
     return;
   }
+  const outDir = join(distDir, AGENT_SKILLS_DIR.slice(1));
   await Promise.all(
     skills.map(async (skill) => {
       const target = join(outDir, skill.path);
@@ -329,6 +353,38 @@ const emitVercelNegotiation = async (
   );
 };
 
+/**
+ * Refuse to ship a Vercel function bundle that would crash at runtime: a bare
+ * import the adapter's dependency trace silently dropped (see
+ * `deploy/function-bundle.ts`). A missing package that is one of Blume's own
+ * dependencies is fatal — the generated runtime imports it, so every request
+ * would die; a project's own external import is reported as a warning and left
+ * to the author.
+ */
+const checkVercelFunctionBundles = async (
+  outputDir: string,
+  root: string
+): Promise<void> => {
+  const audits = await auditVercelFunctions(outputDir);
+  if (audits.length === 0) {
+    return;
+  }
+  const own = blumeDependencyNames();
+  let fatal = false;
+  for (const audit of audits) {
+    const verdict = functionBundleVerdict(audit, root, own);
+    if (verdict.fatal) {
+      fatal = true;
+      logger.error(verdict.message);
+    } else {
+      logger.warn(verdict.message);
+    }
+  }
+  if (fatal) {
+    process.exit(1);
+  }
+};
+
 const warnCloudflareNegotiationSkipped = (): void =>
   logger.warn(
     "Could not wire Accept: text/markdown negotiation into dist/server/wrangler.json — raw Markdown stays available at the .md URLs."
@@ -559,7 +615,8 @@ export const isolatedStaticDir = (
  */
 const publishLlmsFiles = async (
   project: BlumeProject,
-  distDir: string
+  distDir: string,
+  skills: readonly SkillArtifact[]
 ): Promise<void> => {
   const indexPath = join(distDir, "llms.txt");
   const fullPath = join(distDir, "llms-full.txt");
@@ -568,7 +625,7 @@ const publishLlmsFiles = async (
   if (!(writeIndex || writeFull)) {
     return;
   }
-  const { index, full } = await buildLlmsFiles(project);
+  const { index, full } = await buildLlmsFiles(project, { skills });
   const writes: Promise<void>[] = [];
   if (writeIndex) {
     writes.push(writeFile(indexPath, index, "utf-8"));
@@ -613,8 +670,10 @@ const publishBuildArtifacts = async (
     warn: (message) => logger.warn(message),
   });
 
+  // Collected once: llms.txt lists the skills the build publishes below.
+  const skills = await collectConfiguredSkills(project, distDir);
   if (project.config.ai.llmsTxt.enabled) {
-    await publishLlmsFiles(project, distDir);
+    await publishLlmsFiles(project, distDir, skills);
   }
 
   // A user's own public/ file (copied into dist by Astro) always wins.
@@ -652,7 +711,7 @@ const publishBuildArtifacts = async (
   }
 
   await emitWellKnownFiles(project.config, distDir);
-  await emitAgentSkills(project, distDir);
+  await emitAgentSkills(project, distDir, skills);
 
   await emitRedirectFiles(project.config, distDir);
   await emitHeaderFiles(project, distDir);
@@ -798,6 +857,15 @@ export const buildCommand = defineCommand({
     // 100` exiting 0 without measuring anything would be a silent false pass
     // in CI.
     if (runtimeDir) {
+      if (
+        project.config.deployment.output === "server" &&
+        project.config.deployment.adapter === "vercel"
+      ) {
+        await checkVercelFunctionBundles(
+          isolatedOutputDir(project.config, project.context),
+          root
+        );
+      }
       await runClientAssetChecks(
         isolatedStaticDir(project.config, project.context),
         args
@@ -831,6 +899,7 @@ export const buildCommand = defineCommand({
     }
 
     if (project.config.deployment.output === "server" && adapter === "vercel") {
+      await checkVercelFunctionBundles(join(root, ".vercel", "output"), root);
       await emitVercelNegotiation(project, markdownRoutePaths(project), root);
     }
 

package/src/cli/init/questions.ts

@@ -111,6 +111,7 @@ export const collectAnswers = async (
     message: "Where does your content live?",
     options: [
       { hint: "Local .mdx files", label: "filesystem", value: "filesystem" },
+      { hint: "An Obsidian vault", label: "obsidian", value: "obsidian" },
       {
         hint: "Changelog from GitHub Releases",
         label: "github-releases",

package/src/cli/init/scaffold.ts

@@ -15,6 +15,7 @@ export type PackageManager = (typeof PACKAGE_MANAGERS)[number];
 /** The content-source kinds `init` can scaffold a config block for. */
 export const SOURCE_KINDS = [
   "filesystem",
+  "obsidian",
   "github-releases",
   "notion",
   "sanity",
@@ -209,8 +210,12 @@ export const titleize = (raw: string): string => {
         .join(" ");
 };
 
-/** True when any selected source is remote (everything except `filesystem`). */
-const hasRemoteSource = (sources: SourceKind[]): boolean =>
+/**
+ * True when any selected source needs an explicit `content.sources` array —
+ * everything except `filesystem`, which is what the implicit default already
+ * desugars to.
+ */
+const needsExplicitSources = (sources: SourceKind[]): boolean =>
   sources.some((source) => source !== "filesystem");
 
 /**
@@ -239,6 +244,14 @@ const SOURCE_SNIPPETS = {
         database: "your-database-id",
         prefix: "notion",
       },`,
+  obsidian: `      // An Obsidian vault, read in place. No export step, and no
+      // generated notes in your repo. Point \`vault\` at your vault directory,
+      // relative to this config file.
+      {
+        type: "obsidian",
+        vault: "vault",
+        prefix: "notes",
+      },`,
   sanity: `      // Documents from a Sanity dataset. Private datasets read SANITY_TOKEN
       // from the environment.
       {
@@ -258,7 +271,7 @@ const SOURCE_SNIPPETS = {
 const contentBlockFor = (answers: InitAnswers): string => {
   const sources =
     answers.sources.length === 0 ? ["filesystem" as const] : answers.sources;
-  if (!hasRemoteSource(sources)) {
+  if (!needsExplicitSources(sources)) {
     return answers.contentDir === "docs"
       ? ""
       : `
@@ -267,7 +280,7 @@ const contentBlockFor = (answers: InitAnswers): string => {
   },`;
   }
   // Explicit sources replace the implicit filesystem desugar, so the local
-  // content dir must be listed alongside the remote sources to stay included.
+  // content dir must be listed alongside the other sources to stay included.
   const entries = SOURCE_KINDS.filter((kind) => sources.includes(kind)).map(
     (kind) =>
       kind === "filesystem"
@@ -328,6 +341,16 @@ export const buildPlan = (
         .map((file) => ({ ...file, path: join(root, file.path) }))
     );
   }
+  // The obsidian snippet points at `vault/`; seed the directory with a first
+  // note so the scaffolded project passes the source's `validate()` and boots
+  // before the user has opened Obsidian at all.
+  if (answers.sources.includes("obsidian")) {
+    files.push({
+      content:
+        "# Welcome\n\nThis folder is read by Blume's `obsidian` source. Open it as a vault in Obsidian and write notes — `[[Wikilinks]]` become site links.\n",
+      path: join(root, "vault", "Welcome.md"),
+    });
+  }
   return files;
 };