blume 0.7.0 → 1.0.0

package/docs/content/syntax.mdx

@@ -261,7 +261,7 @@ Hide the language icons or wrap long lines instead of scrolling with `markdown:
 
 ## Package install
 
-A `package-install` block turns a single install command into a tabbed snippet for npm, pnpm, yarn, and bun — so readers copy the one that matches their setup.
+A `package-install` block turns a single install command into a tabbed snippet for npm, pnpm, yarn, and bun — so readers copy the one that matches their setup. Like diagrams and math, this is an MDX-only feature — in a `.md` file the block renders as a plain code fence.
 
 ```package-install
 npm i blume
@@ -297,7 +297,7 @@ Diagrams render on the client, so this is an MDX-only feature, and the Mermaid l
 
 ## Callouts
 
-Callouts pull a reader's attention to context, advice, or risk. Write them as `:::type` directives; add a title in brackets, like `:::warning[Heads up]`.
+Callouts pull a reader's attention to context, advice, or risk. Write them as `:::type` directives; add a title in brackets, like `:::warning[Heads up]`. Directives are an MDX-only feature — in a `.md` file a `:::note` line stays literal text.
 
 ### Note
 
@@ -345,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. The [FAQ](/docs/faq) walks through how that compares to Mintlify, Fumadocs, and the rest.
 
 ## What makes Blume different
 

package/docs/reference/cli.mdx

@@ -1,6 +1,6 @@
 ---
 title: CLI
-description: The Blume command-line interface.
+description: Every Blume command and flag — init, dev, build, preview, add, sync, and eject.
 ---
 
 ```bash
@@ -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/docs/reference/frontmatter.mdx

@@ -1,6 +1,6 @@
 ---
 title: Frontmatter
-description: The page metadata schema.
+description: Every frontmatter field a page accepts — title, description, sidebar, SEO, search, and more.
 ---
 
 Every page accepts the following frontmatter. All fields are optional.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.7.0",
+  "version": "1.0.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",
@@ -92,7 +94,6 @@
     "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",
@@ -106,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"
   },
@@ -124,6 +126,10 @@
   },
   "peerDependencies": {
     "@ai-sdk/openai-compatible": "^1.0.41",
+    "@astrojs/cloudflare": "^14.0.0",
+    "@astrojs/netlify": "^8.0.0",
+    "@astrojs/svelte": "^9.0.0",
+    "@astrojs/vue": "^7.0.0",
     "@mixedbread/sdk": "^0.76.0",
     "@notionhq/client": "^2.2.15",
     "@openrouter/ai-sdk-provider": "^1.5.4",
@@ -137,6 +143,18 @@
     "@ai-sdk/openai-compatible": {
       "optional": true
     },
+    "@astrojs/cloudflare": {
+      "optional": true
+    },
+    "@astrojs/netlify": {
+      "optional": true
+    },
+    "@astrojs/svelte": {
+      "optional": true
+    },
+    "@astrojs/vue": {
+      "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

@@ -32,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
@@ -43,13 +44,13 @@ export const buildAgentReadability = (
   }
 
   const site = config.deployment.site ?? null;
-  // Every artifact is served under `deployment.base`; concatenate rather than
-  // `new URL()` so the subpath is preserved.
+  // 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 =>
-    site
-      ? `${site.replace(/\/+$/u, "")}${withBasePath(deployBase, path)}`
-      : path;
+  const abs = (path: string): string => {
+    const based = withBasePath(deployBase, path);
+    return site ? `${site.replace(/\/+$/u, "")}${based}` : based;
+  };
 
   const artifacts: Record<string, unknown> = {
     markdown: {
@@ -57,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,
   });