blume 0.6.7 → 0.8.0

package/docs/content/sources.mdx

@@ -159,7 +159,7 @@ Two flags control how remote content is fetched and what's included:
 blume dev --preview      # author workflow: see drafts live
 blume build --preview    # render a full preview build
 blume sync               # refresh remote content now
-blume sync --force        # ...ignoring any cached snapshot
+blume sync --force       # ...ignoring any cached snapshot
 ```
 
 ## Custom sources

package/docs/content/syntax.mdx

@@ -33,6 +33,7 @@ For footnote markers, ordinals, and scientific or chemical notation inline.
 
 E = mc^2^ and H~2~O.
 
+{/* prettier-ignore */}
 ```md
 E = mc^2^ and H~2~O.
 ```
@@ -141,6 +142,18 @@ export default defineConfig({
 
 Inline code can be highlighted too: add a `{:lang}` marker inside a backtick span and it's colored like a tiny code block — `useState(){:js}` or `T extends object{:ts}`. It only kicks in when you add the marker, so plain inline code stays untouched — nothing to switch on.
 
+Highlighting uses the `github-light`/`github-dark` themes by default. Swap in any [bundled Shiki theme](https://shiki.style/themes) per color mode with `markdown.codeBlocks.theme` — it colors every code surface at once (fences, inline snippets, `<CodeBlock>`, and `<Diff>`):
+
+```ts blume.config.ts
+export default defineConfig({
+  markdown: {
+    codeBlocks: {
+      theme: { light: "github-light", dark: "vesper" },
+    },
+  },
+});
+```
+
 ### Line numbers
 
 Append `lineNumbers` to render a line-number gutter — on its own or alongside a title:
@@ -332,11 +345,13 @@ Your docs built successfully and are ready to deploy.
 
 Flag something that needs care to avoid a mistake or surprising behavior.
 
-:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy.
+:::warning[Heads up]
+Switching to `output: "server"` requires an adapter before you can deploy.
 :::
 
 ```md
-:::warning[Heads up] Switching to `output: "server"` requires an adapter before you can deploy.
+:::warning[Heads up]
+Switching to `output: "server"` requires an adapter before you can deploy.
 :::
 ```
 

package/docs/index.mdx

@@ -19,9 +19,9 @@ Drop Markdown or MDX into a folder, run `blume dev`, and get a production-grade
 
 ## Why Blume exists
 
-Docs should be fast, AI-ready and require zero configuration — down to not needing a starter template at all. Some docs tools hand you an entire codebase to maintain before you've written a word. Others build the template around your content, but lock you in to their managed service.
+Docs should be fast, AI-ready, and zero-config — down to not needing a starter template at all. Some docs tools hand you an entire codebase to maintain before you've written a word. Others build the template around your content, but lock you in to their managed service.
 
-Blume takes the best of both worlds. The framework is the template, so the only thing you ever touch is your content. When you want to customize, you can start replacing the built-in components, modifying the single configuration file or even ejecting if you want the Astro site directly.
+Blume takes the best of both worlds. The framework is the template, so the only thing you ever touch is your content. When you want to customize, you can start by replacing the built-in components, modifying the single configuration file, or even ejecting if you want the Astro site directly.
 
 ## What makes Blume different
 

package/docs/reference/cli.mdx

@@ -11,7 +11,7 @@ blume <command> [options]
 
 | Command            | Description                                      |
 | ------------------ | ------------------------------------------------ |
-| `blume init`       | Scaffold a minimal project.                      |
+| `blume init [dir]` | Scaffold a project (interactive by default).     |
 | `blume dev`        | Start the dev server with hot reload.            |
 | `blume build`      | Build the static (or server) site.               |
 | `blume preview`    | Preview the last build.                          |
@@ -24,7 +24,9 @@ blume <command> [options]
 
 ## Common flags
 
-- `blume init --content-dir <dir> --yes` — set the content folder (default `docs`) and skip prompts.
+- `blume init` — in a terminal, walks you through a few questions (where to create the project, site name, template, content sources); each flag below pre-answers its question.
+- `blume init --yes` — skip the prompts and scaffold with defaults (also the behavior in CI or when stdin isn't a terminal).
+- `blume init --content-dir <dir>` — set the content folder (default `docs`).
 - `blume init --template docs|api|sdk|changelog` — scaffold from a starter (API reference, SDK, or changelog instead of the plain docs seed).
 - `blume init --package-manager npm|pnpm|yarn|bun` — tailor the printed next-steps to your package manager.
 - `blume init --eject` — scaffold, then eject to a standalone Astro project (falls back to guiding you through `blume eject` when dependencies aren't installed yet).
@@ -53,9 +55,9 @@ blume <command> [options]
 `blume dev` serves a live Astro server rooted at the generated `.blume/` runtime and regenerates it on every change. `blume build` and `blume check` regenerate the _same_ `.blume/`, so running either while the dev server is live would corrupt it — both refuse with an error and exit non-zero:
 
 ```
-A `blume dev` server is running against .blume; building would corrupt it.
-Stop the dev server, or re-run with --isolated to build/verify against
-.blume-verify without touching it.
+A `blume dev` server is running at http://localhost:3000; building would
+corrupt its .blume runtime. Reuse that server, stop it first, or re-run with
+--isolated to build/verify against .blume-verify without touching it.
 ```
 
 The `--isolated` flag is the escape hatch. It relocates the entire generated runtime (and, for `build`, its output `dist/`) to a sibling `.blume-verify/` directory, so the verification never writes anything the dev server — or your real `dist/` — depends on:
@@ -66,7 +68,7 @@ blume check --isolated   # fast: type-check the .astro/config changes
 blume build --isolated   # thorough: full production render into .blume-verify/dist
 ```
 
-`check --isolated` is the quick path (Astro type + template diagnostics, no `dist/`); `build --isolated` is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, `llms.txt`, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. Blume adds `.blume-verify/` to your `.gitignore` automatically.
+`check --isolated` is the quick path (Astro type + template diagnostics, no `dist/`); `build --isolated` is the heavier one that also catches runtime render errors. Isolated builds skip the deploy post-steps (search index, hosted-provider sync, `llms.txt`, sitemap/robots, redirects) — a verify only needs to confirm the site compiles and renders, not publish it. `--analyze` and the `--budget-js`/`--budget-css` gates still run, measured against the isolated output. Blume adds `.blume-verify/` to your `.gitignore` automatically.
 
 This is especially useful when a coding agent needs to verify changes while you keep the dev server open. To make plain `blume build`/`blume check` isolate without the flag — for example in an agent's shell — set `BLUME_RUNTIME_DIR` to the runtime directory to use:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.6.7",
+  "version": "0.8.0",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -29,7 +29,8 @@
     "src",
     "bin",
     "docs",
-    "skills"
+    "skills",
+    "CHANGELOG.md"
   ],
   "type": "module",
   "types": "./dist/types/index.d.ts",
@@ -71,6 +72,7 @@
     "@astrojs/node": "^11.0.0",
     "@astrojs/react": "^6.0.0",
     "@astrojs/vercel": "^11.0.0",
+    "@clack/prompts": "^1.7.0",
     "@iconify-json/lucide": "^1.2.115",
     "@iconify/types": "^2.0.0",
     "@iconify/utils": "^3.1.3",
@@ -89,9 +91,9 @@
     "@vercel/analytics": "^2.0.1",
     "ai": "^5.0.0",
     "astro": "^7.0.2",
+    "babel-plugin-react-compiler": "^1.0.0",
     "citty": "^0.1.6",
     "consola": "^3.4.0",
-    "deepmerge": "^4.3.1",
     "dompurify": "^3.4.11",
     "epub-gen-memory": "^1.1.2",
     "github-slugger": "^2.0.0",
@@ -105,11 +107,12 @@
     "pathe": "^2.0.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
+    "satteri": "^0.9.5",
     "shiki": "^4.2.0",
     "simple-icons": "^13.0.0",
     "tailwindcss": "^4",
     "tinyglobby": "^0.2.10",
-    "typescript": "^5.7.0",
+    "typescript": "^6.0.3",
     "undici": "^8.6.0",
     "zod": "^3.24.0"
   },
@@ -123,6 +126,8 @@
   },
   "peerDependencies": {
     "@ai-sdk/openai-compatible": "^1.0.41",
+    "@astrojs/cloudflare": "^14.0.0",
+    "@astrojs/netlify": "^8.0.0",
     "@mixedbread/sdk": "^0.76.0",
     "@notionhq/client": "^2.2.15",
     "@openrouter/ai-sdk-provider": "^1.5.4",
@@ -136,6 +141,12 @@
     "@ai-sdk/openai-compatible": {
       "optional": true
     },
+    "@astrojs/cloudflare": {
+      "optional": true
+    },
+    "@astrojs/netlify": {
+      "optional": true
+    },
     "@mixedbread/sdk": {
       "optional": true
     },

package/skills/blume/SKILL.md

@@ -18,7 +18,7 @@ The core idea: **the framework _is_ the template.** There's no starter to clone
 
 ## Quickstart
 
-Blume needs **Node.js 22 or newer**. From an empty or existing project:
+Blume needs **Node.js 22.12 or newer**. From an empty or existing project:
 
 ```bash
 npm i blume      # install the package
@@ -41,7 +41,9 @@ description: Welcome to my docs.
 
 Welcome! Use **Markdown** and built-in components — no imports required:
 
-:::note Blume ships callouts, cards, tabs, steps, and more. :::
+:::note
+Blume ships callouts, cards, tabs, steps, and more.
+:::
 ```
 
 Navigation, search, and page metadata are inferred from your files as you add them.
@@ -50,7 +52,7 @@ Navigation, search, and page metadata are inferred from your files as you add th
 
 - **Components** — callouts, cards, steps, tabs, accordions, badges, file trees, and parameter tables, usable in MDX with no imports.
 - **Local search** — Orama in dev and production; Pagefind is one flag away for large sites. No hosted index.
-- **AI** — `llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an Ask AI assistant, and a hosted MCP server.
+- **AI** — `llms.txt`, raw Markdown URLs, Copy as Markdown, Open in chat, an Ask AI assistant, and an MCP server endpoint served by the docs site itself.
 - **Navigation** — inferred from files, refined with `meta.ts` or config.
 - **SEO** — metadata, Open Graph images, RSS feeds, and JSON-LD.
 - **Customization** — component overrides, React islands, custom pages, theme tokens, and a source-component registry via `blume add`.

package/skills/blume-update-docs/SKILL.md

@@ -5,7 +5,7 @@ description: Keep a Blume docs site in sync with the product it documents. Audit
 
 # Update Blume Docs
 
-Blume is a **markdown-first** documentation framework on Astro/Vite: content lives as Markdown/MDX under a content root (default `docs/`), navigation derives from the file tree plus optional `meta.ts` files, and `blume build` validates links, anchors, frontmatter, and routes.
+Blume is a **markdown-first** documentation framework on Astro/Vite: content lives as Markdown/MDX under a content root (default `docs/`), navigation derives from the file tree plus optional `meta.ts` files, `blume build` validates frontmatter and duplicate routes, and `blume validate` checks links and anchors.
 
 Your job is **docs maintenance, not docs authorship**: find where shipped, user-facing behavior has drifted from what the docs claim, fix exactly that, prove the site still builds, and deliver the result as a pull request. A run that finds nothing actionable ends with a short report and **no branch, no commit, no PR** — prefer a no-op over a noisy PR.
 
@@ -39,7 +39,8 @@ Your job is **docs maintenance, not docs authorship**: find where shipped, user-
    - Match the surrounding pages: frontmatter shape, Blume components already in use, code-fence style, root-relative internal links.
 
 5. **Verify.**
-   - Run the docs build (`blume build` or the repo's documented docs QA) — it validates links, anchors, frontmatter, and duplicate routes.
+   - Run the docs build (`blume build` or the repo's documented docs QA) — it validates frontmatter and duplicate routes.
+   - Run `blume validate` to check internal links and anchors.
    - Run lint/format/typecheck when the repo's conventions call for them on docs changes.
    - Fix failures your edits caused; report pre-existing failures separately instead of fixing them in this PR.
 

package/src/ai/agent-readability.ts

@@ -1,3 +1,4 @@
+import { normalizeBasePath, withBasePath } from "../core/base-path.ts";
 import type { BlumeProject } from "../core/project-graph.ts";
 import type { ContentSignalPolicy, ContentSignals } from "../core/schema.ts";
 import { buildRssFeeds } from "../deploy/rss.ts";
@@ -31,7 +32,8 @@ const usagePolicy = (
  * agent-facing surface — llms.txt, the raw-Markdown mirrors, the MCP server,
  * Ask AI, sitemap, and feeds — so agents can discover and cite the docs without
  * scraping HTML. URLs are absolute when a `site` is configured and root-relative
- * otherwise. Returns null when the manifest is disabled.
+ * (still under `deployment.base`) otherwise. Returns null when the manifest is
+ * disabled.
  */
 export const buildAgentReadability = (
   project: BlumeProject
@@ -42,9 +44,13 @@ export const buildAgentReadability = (
   }
 
   const site = config.deployment.site ?? null;
-  // Concatenate rather than `new URL()` so a subpath deployment's base is kept.
-  const abs = (path: string): string =>
-    site ? `${site.replace(/\/+$/u, "")}${path}` : path;
+  // Every artifact is served under `deployment.base` — with or without a
+  // `site`; concatenate rather than `new URL()` so the subpath is preserved.
+  const deployBase = normalizeBasePath(config.deployment.base);
+  const abs = (path: string): string => {
+    const based = withBasePath(deployBase, path);
+    return site ? `${site.replace(/\/+$/u, "")}${based}` : based;
+  };
 
   const artifacts: Record<string, unknown> = {
     markdown: {
@@ -52,7 +58,7 @@ export const buildAgentReadability = (
       pattern: abs("/{route}.md"),
     },
   };
-  if (config.ai.llmsTxt) {
+  if (config.ai.llmsTxt.enabled) {
     artifacts.llmsFullTxt = abs("/llms-full.txt");
     artifacts.llmsTxt = abs("/llms.txt");
   }

package/src/ai/ask-context.ts

@@ -124,8 +124,9 @@ const lastUserMessage = (messages: AskMessage[]): string => {
  * where "How does Ask AI work?" retrieves the right page but only sees its
  * opening paragraph. This centers the window on the densest cluster of query
  * terms so the injected text is the part that actually answers the question.
+ * Exported for testing; {@link createAskContext} is the runtime entry point.
  */
-const relevantExcerpt = (
+export const relevantExcerpt = (
   content: string,
   query: string,
   max: number
@@ -177,7 +178,11 @@ const relevantExcerpt = (
       best = start;
     }
   }
-  return withEllipsis(Math.max(0, best - EXCERPT_LEAD));
+  // Cap the lead-in at half the window: under a tight remaining budget `max`
+  // can be smaller than EXCERPT_LEAD, and an uncapped `best - EXCERPT_LEAD`
+  // start would end the slice before the very match it centered on.
+  const lead = Math.min(EXCERPT_LEAD, Math.floor(max / 2));
+  return withEllipsis(Math.max(0, best - lead));
 };
 
 /**

package/src/ai/ask-data.ts

@@ -9,9 +9,12 @@ import type { AskData } from "./ask-context.ts";
  * MCP snapshot) so retrieval can be filtered to the current page's language, and
  * content is kept as Markdown so grounding sees fenced code examples — the model
  * answers "what does the config look like?" from the docs instead of declining.
+ * The reader is an AI agent, so `<Visibility>` resolves for the agents audience
+ * (web-only content removed, agents-only unwrapped), matching llms-full.txt.
  */
 export const buildAskData = async (project: BlumeProject): Promise<AskData> => {
   const documents = await buildSearchDocuments(project, {
+    audience: "agents",
     content: "markdown",
     includeWhenDisabled: true,
   });

package/src/ai/ask.ts

@@ -30,20 +30,25 @@ interface AskPreset {
  * dedicated AI SDK provider; LLMGateway and Inkeep are OpenAI-compatible
  * endpoints with no dedicated provider, so they reuse `@ai-sdk/openai-compatible`.
  */
+/** The discriminant/name shared by the OpenAI-compatible providers. */
+const OPENAI_COMPATIBLE = "openai-compatible";
+/** The AI SDK provider package the OpenAI-compatible providers install. */
+const OPENAI_COMPATIBLE_DEP = "@ai-sdk/openai-compatible";
+
 const ASK_PRESETS: Record<string, AskPreset> = {
   inkeep: {
     apiKeyEnv: "INKEEP_API_KEY",
     baseUrl: "https://api.inkeep.com/v1",
-    kind: "openai-compatible",
+    kind: OPENAI_COMPATIBLE,
     name: "inkeep",
-    runtimeDep: "@ai-sdk/openai-compatible",
+    runtimeDep: OPENAI_COMPATIBLE_DEP,
   },
   llmgateway: {
     apiKeyEnv: "LLMGATEWAY_API_KEY",
     baseUrl: "https://api.llmgateway.io/v1",
-    kind: "openai-compatible",
+    kind: OPENAI_COMPATIBLE,
     name: "llmgateway",
-    runtimeDep: "@ai-sdk/openai-compatible",
+    runtimeDep: OPENAI_COMPATIBLE_DEP,
   },
   openrouter: {
     apiKeyEnv: "OPENROUTER_API_KEY",
@@ -73,9 +78,9 @@ export const resolveAskBackend = (ask?: AskAiConfig): AskBackend => {
   return {
     apiKeyEnv,
     baseUrl: ask?.baseUrl ?? preset?.baseUrl ?? "",
-    kind: "openai-compatible",
+    kind: OPENAI_COMPATIBLE,
     model,
-    name: preset?.name ?? "openai-compatible",
+    name: preset?.name ?? OPENAI_COMPATIBLE,
   };
 };
 
@@ -89,5 +94,5 @@ export const askBackendRuntimeDep = (ask?: AskAiConfig): string | undefined => {
   if (provider === "gateway") {
     return undefined;
   }
-  return ASK_PRESETS[provider]?.runtimeDep ?? "@ai-sdk/openai-compatible";
+  return ASK_PRESETS[provider]?.runtimeDep ?? OPENAI_COMPATIBLE_DEP;
 };