diff --git a/README.md b/README.md
index afe76467b9..9157d1474f 100644
--- a/README.md
+++ b/README.md
@@ -37,7 +37,7 @@ deno init --npm veryfront
 The default starter is `ai-agent`. Choose another template directly:
 
 ```bash
-npx veryfront init <PROJECT_NAME> --template <TEMPLATE>
+npx veryfront@latest init <PROJECT_NAME> --template <TEMPLATE>
 ```
 
 Available starters: `ai-agent`, `minimal`, `agentic-workflow`.
diff --git a/cli/commands/init/init.integration.test.ts b/cli/commands/init/init.integration.test.ts
index bfd09fa8ec..74609deb0f 100644
--- a/cli/commands/init/init.integration.test.ts
+++ b/cli/commands/init/init.integration.test.ts
@@ -187,6 +187,7 @@ describe("init command integration", () => {
       assertEquals(result.stdout?.includes("Deploy:"), true);
       assertEquals(result.stdout?.includes("Project structure"), false);
       assertEquals(result.stdout?.includes("npm run deploy"), true);
+      assertEquals(result.stdout?.includes("npx veryfront@latest deploy"), false);
       assertEquals(result.stdout?.includes("npx veryfront deploy"), false);
       assertEquals(result.stdout?.includes("Project files created"), false);
       assertEquals(result.stdout?.includes("Dependencies installed"), false);
diff --git a/cli/main.ts b/cli/main.ts
index aedd8498b7..1f4a738e99 100644
--- a/cli/main.ts
+++ b/cli/main.ts
@@ -5,7 +5,7 @@
  *
  * @example
  * ```sh
- * npx veryfront dev
+ * npx veryfront@latest dev
  * ```
  */
 
diff --git a/cli/shared/update-check.test.ts b/cli/shared/update-check.test.ts
index 3c840e4984..ff9cc37542 100644
--- a/cli/shared/update-check.test.ts
+++ b/cli/shared/update-check.test.ts
@@ -1,7 +1,14 @@
 import "#veryfront/schemas/_test-setup.ts";
 import { assertEquals } from "#veryfront/testing/assert.ts";
 import { describe, it } from "#veryfront/testing/bdd.ts";
-import { compareVersions, shouldSkip } from "./update-check.ts";
+import {
+  checkForUpdates,
+  compareVersions,
+  getUpdateInstallCommand,
+  shouldSkip,
+  UPDATE_INSTALL_COMMAND,
+  UPDATE_REGISTRY_URL,
+} from "./update-check.ts";
 import { setJsonMode } from "./json-output.ts";
 import { setQuietMode } from "../utils/index.ts";
 
@@ -115,4 +122,119 @@ describe("update-check", () => {
       }
     });
   });
+
+  describe("registry lookup", () => {
+    it("selects update commands that preserve the active install method", () => {
+      assertEquals(
+        getUpdateInstallCommand({
+          standalone: false,
+          executablePath: "prefix/homebrew/bin/node",
+        }),
+        "npm install -g veryfront@latest",
+      );
+      assertEquals(
+        getUpdateInstallCommand({
+          standalone: true,
+          executablePath: "prefix/homebrew/lib/node_modules/veryfront/bin/veryfront",
+        }),
+        "npm install -g veryfront@latest",
+      );
+      assertEquals(
+        getUpdateInstallCommand({
+          standalone: true,
+          executablePath: "prefix/homebrew/bin/veryfront",
+        }),
+        "brew upgrade veryfront/tap/veryfront",
+      );
+      assertEquals(
+        getUpdateInstallCommand({
+          standalone: true,
+          executablePath: "prefix/.veryfront/bin/veryfront",
+        }),
+        "curl -fsSL https://veryfront.com/install.sh | sh",
+      );
+    });
+
+    it("reads and caches the npm latest response", async () => {
+      const writes: Array<{ path: string; data: string }> = [];
+      const notices: Array<{ current: string; latest: string }> = [];
+
+      await checkForUpdates("1.2.3", {
+        shouldSkip: () => false,
+        cacheLocation: {
+          directory: "cache/veryfront",
+          file: "cache/veryfront/update-check.json",
+        },
+        fileSystem: {
+          readTextFile: () => Promise.reject(new Error("missing")),
+          mkdir: () => Promise.resolve(),
+          writeTextFile: (path, data) => {
+            writes.push({ path, data });
+            return Promise.resolve();
+          },
+        },
+        fetcher: (input) => {
+          assertEquals(String(input), "https://registry.npmjs.org/veryfront/latest");
+          return Promise.resolve(Response.json({ version: "1.2.4" }));
+        },
+        now: () => 123,
+        printNotice: (current, latest) => notices.push({ current, latest }),
+      });
+
+      assertEquals(UPDATE_REGISTRY_URL, "https://registry.npmjs.org/veryfront/latest");
+      assertEquals(UPDATE_INSTALL_COMMAND, "npm install -g veryfront@latest");
+      assertEquals(writes, [{
+        path: "cache/veryfront/update-check.json",
+        data: JSON.stringify({ lastCheck: 123, latestVersion: "1.2.4" }),
+      }]);
+      assertEquals(notices, [{ current: "1.2.3", latest: "1.2.4" }]);
+    });
+
+    it("prints a valid update notice when cache persistence fails", async () => {
+      const diagnostics: string[] = [];
+      const notices: Array<{ current: string; latest: string }> = [];
+
+      await checkForUpdates("1.2.3", {
+        shouldSkip: () => false,
+        cacheLocation: {
+          directory: "cache/veryfront",
+          file: "cache/veryfront/update-check.json",
+        },
+        fileSystem: {
+          readTextFile: () => Promise.reject(new Error("missing")),
+          mkdir: () => Promise.resolve(),
+          writeTextFile: () => Promise.reject(new Error("read-only cache")),
+        },
+        fetcher: () => Promise.resolve(Response.json({ version: "1.2.4" })),
+        printNotice: (current, latest) => notices.push({ current, latest }),
+        debug: (message) => diagnostics.push(message),
+      });
+
+      assertEquals(notices, [{ current: "1.2.3", latest: "1.2.4" }]);
+      assertEquals(diagnostics, ["Veryfront could not cache the update check."]);
+    });
+
+    it("reports a broken registry endpoint in verbose diagnostics", async () => {
+      const diagnostics: string[] = [];
+
+      await checkForUpdates("1.2.3", {
+        shouldSkip: () => false,
+        cacheLocation: {
+          directory: "cache/veryfront",
+          file: "cache/veryfront/update-check.json",
+        },
+        fileSystem: {
+          readTextFile: () => Promise.reject(new Error("missing")),
+          mkdir: () => Promise.resolve(),
+          writeTextFile: () => Promise.resolve(),
+        },
+        fetcher: () => Promise.resolve(new Response(null, { status: 404 })),
+        debug: (message) => diagnostics.push(message),
+      });
+
+      assertEquals(diagnostics, [
+        "Veryfront could not check for updates: npm registry returned 404.",
+      ]);
+    });
+  });
 });
diff --git a/cli/shared/update-check.ts b/cli/shared/update-check.ts
index 3201aa9a7b..47a2cec70a 100644
--- a/cli/shared/update-check.ts
+++ b/cli/shared/update-check.ts
@@ -8,28 +8,54 @@
  */
 
 import { getEnv } from "veryfront/platform";
-import { createFileSystem } from "veryfront/platform";
+import { createFileSystem, type FileSystem } from "veryfront/platform";
 import { join } from "veryfront/platform/path";
 import { getEnvironmentConfig } from "veryfront/config";
 import { isJsonMode } from "./json-output.ts";
 import { brand, dim, warning as warningColor } from "../ui/colors.ts";
-import { isQuiet } from "../utils/index.ts";
+import { cliLogger, isQuiet } from "../utils/index.ts";
 import { detectCI } from "./interactive.ts";
 
 const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
-const REGISTRY_URL = "https://jsr.io/@veryfront/veryfront/meta.json";
-const INSTALL_CMD = "deno install -gArf jsr:@veryfront/veryfront";
+export const UPDATE_REGISTRY_URL = "https://registry.npmjs.org/veryfront/latest";
+export const UPDATE_INSTALL_COMMAND = "npm install -g veryfront@latest";
+const HOMEBREW_UPDATE_COMMAND = "brew upgrade veryfront/tap/veryfront";
+const INSTALL_SCRIPT_COMMAND = "curl -fsSL https://veryfront.com/install.sh | sh";
+const STABLE_SEMVER_PATTERN = /^\d+\.\d+\.\d+$/;
 
 interface UpdateCache {
   lastCheck: number;
   latestVersion: string | null;
 }
 
-function getCacheFile(): string | null {
+interface UpdateCacheLocation {
+  directory: string;
+  file: string;
+}
+
+type UpdateCheckFileSystem = Pick<FileSystem, "readTextFile" | "mkdir" | "writeTextFile">;
+type UpdateCheckFetcher = (
+  input: string | URL | Request,
+  init?: RequestInit,
+) => Promise<Response>;
+
+export interface UpdateCheckOptions {
+  shouldSkip?: () => boolean;
+  cacheLocation?: UpdateCacheLocation | null;
+  fileSystem?: UpdateCheckFileSystem;
+  fetcher?: UpdateCheckFetcher;
+  now?: () => number;
+  printNotice?: (current: string, latest: string) => void;
+  debug?: (message: string) => void;
+}
+
+class UpdateCheckFailure extends Error {}
+
+function getCacheLocation(): UpdateCacheLocation | null {
   const env = getEnvironmentConfig();
   if (!env.homeDir) return null;
-  const cacheDir = join(env.homeDir, ".cache", "veryfront");
-  return join(cacheDir, "update-check.json");
+  const directory = join(env.homeDir, ".cache", "veryfront");
+  return { directory, file: join(directory, "update-check.json") };
 }
 
 export function compareVersions(current: string, latest: string): boolean {
@@ -50,62 +76,112 @@ export function shouldSkip(): boolean {
   return false;
 }
 
+export function getUpdateInstallCommand(
+  context: { standalone: boolean; executablePath: string } = {
+    standalone: Deno.build.standalone ?? false,
+    executablePath: Deno.execPath(),
+  },
+): string {
+  if (!context.standalone) return UPDATE_INSTALL_COMMAND;
+
+  const executablePath = context.executablePath.replaceAll("\\", "/").toLowerCase();
+  if (executablePath.includes("/node_modules/veryfront/bin/")) {
+    return UPDATE_INSTALL_COMMAND;
+  }
+
+  if (
+    executablePath.includes("/cellar/") ||
+    executablePath.includes("/homebrew/") ||
+    executablePath.includes("/linuxbrew/")
+  ) {
+    return HOMEBREW_UPDATE_COMMAND;
+  }
+
+  if (!executablePath.endsWith(".exe")) return INSTALL_SCRIPT_COMMAND;
+  return UPDATE_INSTALL_COMMAND;
+}
+
 function printUpdateNotice(current: string, latest: string): void {
   console.error();
   console.error(`  ${warningColor("!")} Update available: ${current} → ${latest}`);
-  console.error(`  ${dim("Run:")} ${brand(INSTALL_CMD)}`);
+  console.error(`  ${dim("Run:")} ${brand(getUpdateInstallCommand())}`);
   console.error();
 }
 
+async function fetchLatestVersion(fetcher: UpdateCheckFetcher): Promise<string> {
+  const response = await fetcher(UPDATE_REGISTRY_URL);
+  if (!response.ok) {
+    await response.body?.cancel();
+    throw new UpdateCheckFailure(
+      `Veryfront could not check for updates: npm registry returned ${response.status}.`,
+    );
+  }
+
+  const data: unknown = await response.json();
+  const latestVersion = data && typeof data === "object" && "version" in data
+    ? (data as { version?: unknown }).version
+    : undefined;
+  if (typeof latestVersion !== "string" || !STABLE_SEMVER_PATTERN.test(latestVersion)) {
+    throw new UpdateCheckFailure(
+      "Veryfront could not check for updates: npm registry returned an invalid version.",
+    );
+  }
+
+  return latestVersion;
+}
+
 export async function checkForUpdates(
   currentVersion: string,
+  options: UpdateCheckOptions = {},
 ): Promise<void> {
-  if (shouldSkip()) return;
+  if ((options.shouldSkip ?? shouldSkip)()) return;
 
-  const cacheFile = getCacheFile();
-  if (!cacheFile) return;
+  const cacheLocation = options.cacheLocation === undefined
+    ? getCacheLocation()
+    : options.cacheLocation;
+  if (!cacheLocation) return;
 
-  const fs = createFileSystem();
+  const fs = options.fileSystem ?? createFileSystem();
+  const now = options.now ?? Date.now;
+  const notice = options.printNotice ?? printUpdateNotice;
+  const debug = options.debug ?? ((message: string) => cliLogger.debug(message));
 
   try {
-    const raw = await fs.readTextFile(cacheFile);
+    const raw = await fs.readTextFile(cacheLocation.file);
     const cache: UpdateCache = JSON.parse(raw);
-    if (Date.now() - cache.lastCheck < CHECK_INTERVAL_MS) {
+    if (now() - cache.lastCheck < CHECK_INTERVAL_MS) {
       if (
         cache.latestVersion &&
         compareVersions(currentVersion, cache.latestVersion)
       ) {
-        printUpdateNotice(currentVersion, cache.latestVersion);
+        notice(currentVersion, cache.latestVersion);
       }
       return;
     }
   } catch {
-    // No cache — proceed
+    // No cache. Continue with the registry check.
   }
 
   try {
-    const resp = await fetch(REGISTRY_URL);
-    if (!resp.ok) {
-      await resp.body?.cancel();
-      return;
+    const latestVersion = await fetchLatestVersion(options.fetcher ?? fetch);
+    if (compareVersions(currentVersion, latestVersion)) {
+      notice(currentVersion, latestVersion);
     }
-    const data = await resp.json();
-    const latestVersion = data.latest as string | undefined;
-    if (!latestVersion) return;
-
-    const env = getEnvironmentConfig();
-    if (!env.homeDir) return;
-    const cacheDir = join(env.homeDir, ".cache", "veryfront");
-    await fs.mkdir(cacheDir, { recursive: true });
-    await fs.writeTextFile(
-      cacheFile,
-      JSON.stringify({ lastCheck: Date.now(), latestVersion }),
-    );
 
-    if (compareVersions(currentVersion, latestVersion)) {
-      printUpdateNotice(currentVersion, latestVersion);
+    try {
+      await fs.mkdir(cacheLocation.directory, { recursive: true });
+      await fs.writeTextFile(
+        cacheLocation.file,
+        JSON.stringify({ lastCheck: now(), latestVersion }),
+      );
+    } catch {
+      debug("Veryfront could not cache the update check.");
     }
-  } catch {
-    // Network error — silently ignore
+  } catch (error) {
+    debug(
+      error instanceof UpdateCheckFailure
+        ? error.message
+        : "Veryfront could not complete the update check.",
+    );
   }
 }
diff --git a/cli/templates/files/docs-agent/README.md b/cli/templates/files/docs-agent/README.md
index 412917b22e..0b0cabc8b3 100644
--- a/cli/templates/files/docs-agent/README.md
+++ b/cli/templates/files/docs-agent/README.md
@@ -24,7 +24,7 @@ A chatbot that answers questions from your own documents using Retrieval-Augment
 2. Start the dev server:
 
    ```bash
-   npx veryfront dev
+   npx veryfront@latest dev
    ```
 
 3. Index the sample docs in `content/`:
diff --git a/cli/templates/integrations/figma/README.md b/cli/templates/integrations/figma/README.md
index 2031b144dd..02012d234a 100644
--- a/cli/templates/integrations/figma/README.md
+++ b/cli/templates/integrations/figma/README.md
@@ -63,7 +63,7 @@ FIGMA_CLIENT_SECRET=your_figma_client_secret
 ### 3. Install the Integration
 
 ```bash
-npx veryfront add figma
+npx veryfront@latest add figma
 ```
 
 ## File Structure
diff --git a/cli/templates/manifest.json b/cli/templates/manifest.json
index cc2f8c5a73..56dfdac3c7 100644
--- a/cli/templates/manifest.json
+++ b/cli/templates/manifest.json
@@ -66,7 +66,7 @@
         "globals.css": "@import \"tailwindcss\";\n",
         "globals.d.ts": "declare module \"*.css\";\n",
         "public/favicon.svg": "<svg xmlns=\"http://www.w3.org/2000/svg\" viewBox=\"0 0 64 64\">\n  <rect width=\"64\" height=\"64\" fill=\"#fff\"/>\n  <circle cx=\"32\" cy=\"32\" r=\"20\" fill=\"#000\"/>\n</svg>\n",
-        "README.md": "# Docs Agent\n\nA chatbot that answers questions from your own documents using Retrieval-Augmented Generation (RAG).\n\n## What's included\n\n- Q&A agent with source citation\n- Embedding-based semantic search with convention-based model selection\n- Document upload supporting PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and Markdown\n- `ragStore()` with local JSON storage by default, and Veryfront Cloud RAG when bootstrap is present\n- Veryfront Cloud AI Gateway routing for generation and embeddings when bootstrap is present\n- Original uploaded files stored in Veryfront Cloud project uploads when cloud bootstrap is present\n- Sample content in `/content` indexed through a dedicated ingestion route\n\n## Getting started\n\n1. Set your Veryfront Cloud bootstrap vars:\n\n   ```bash\n   export VERYFRONT_API_TOKEN=vf_...\n   export VERYFRONT_PROJECT_SLUG=my-project\n   ```\n\n2. Start the dev server:\n\n   ```bash\n   npx veryfront dev\n   ```\n\n3. Index the sample docs in `content/`:\n\n   ```bash\n   curl -X POST http://localhost:3000/api/ingest\n   ```\n\n4. Open the app and upload a document or ask a question.\n\nIf you are using a self-hosted Veryfront API, also set `VERYFRONT_API_URL`.\n\n## Cloud mode\n\nWith `VERYFRONT_API_TOKEN` and `VERYFRONT_PROJECT_SLUG` set, the template uses\nVeryfront Cloud automatically:\n\n- Agent generation routes through Veryfront Cloud model routing.\n- Query and document embeddings route through Veryfront Cloud embedding routing.\n- `veryfront-cloud/openai/...` and `veryfront-cloud/google/...` models use AI Gateway.\n- RAG documents, chunks, and embeddings are stored in the target project.\n\nThe default cloud embedding model is\n`veryfront-cloud/openai/text-embedding-3-small`. Set\n`VERYFRONT_DEFAULT_EMBEDDING_MODEL` only when you need a different embedding\nmodel.\n\n## Architecture\n\nRAG grounds LLM responses in your documents through three pipelines: **Ingestion**, **Query**, and **RAG**. These pipelines are orchestrated around a shared vector store.\n\n```mermaid\nflowchart LR\n    ChatUI_L[\"Chat UI\"]\n\n    subgraph IngestionFlow[\"Ingestion Pipeline\"]\n        D[\"Documents\"] --> EXT[\"Extraction\"] --> DC[\"Chunking\"] --> DE[\"Document\\nEmbedding\"] --> ING[\"Storage\"]\n    end\n\n    subgraph QueryFlow[\"Query Pipeline\"]\n        Q[\"Query\"] --> QE[\"Query\\nEmbedding\"] --> SS[\"Similarity\\nSearch\"]\n    end\n\n    subgraph RAGFlow[\"RAG Pipeline\"]\n        BF[\"beforeStream\\nHook\"] --> RET[\"Retrieval\"] --> AUG[\"Augmentation\"] --> AG[\"Agent\"] --> GEN[\"Generation\"]\n    end\n\n    EMB((\"Embedding\\nModel\"))\n    GEN_LLM((\"Generative\\nModel\"))\n    VS[(\"Vector\\nStore\")]\n    ChatUI_R[\"Chat UI\"]\n\n    ChatUI_L --> D\n    ChatUI_L --> Q\n\n    QE -.- EMB\n    DE -.- EMB\n\n    SS --> VS\n    ING --> VS\n\n    Q --> BF\n    VS --> RET\n    AG -.- GEN_LLM\n    GEN -.- GEN_LLM\n    GEN --> ChatUI_R\n```\n\n### Pipelines\n\n**Ingestion**: Documents are parsed into plain text via the built-in kreuzberg extraction engine (supporting PDF, DOCX, XLSX, PPTX, HTML, RTF, EPUB, and 76+ formats), split into overlapping chunks (~1000 chars, 200 char overlap), and stored in the default `ragStore()`. In local mode that means `data/index.json`; with Veryfront Cloud bootstrap it upgrades to the cloud RAG backend automatically. The original uploaded binary is also stored in the project's Veryfront Cloud uploads store so remote projects retain the source file, not just the extracted text. Uploaded files are ingested by the upload route. Bundled files in `content/` are ingested by the `/api/ingest` route.\n\n**Query**: The user's query is embedded into the same vector space as the documents, then compared against all stored chunks using cosine similarity to find the top-*k* most relevant results.\n\n**RAG**: The `beforeStream` hook in the AG-UI route intercepts each message before it reaches the agent. It searches the document store for relevant chunks, assembles them into context, and prepends them as retrieved reference data. The agent then generates a cited response streamed back to the user.\n\n## Structure\n\n```\nstore.ts                        RAG store config\nagents/rag.ts                   Q&A agent with citation instructions\ncontent/\n  getting-started.md            Sample document\n  architecture.md               Sample document\napp/\n  api/ag-ui/route.ts             AG-UI endpoint\n  api/ingest/route.ts            Bundled content ingestion\n  api/uploads/route.ts           Upload, list, and delete uploads\n  uploads/page.tsx               Upload management panel\n  page.tsx                       Chat UI\n  layout.tsx                     Chat shell with sidebar and tabs\n```\n\n## Framework usage\n\n| What | Framework | Template code |\n|------|-----------|---------------|\n| Chat UI + streaming | app-mode `Chat` | `page.tsx` |\n| Upload management | `AttachmentsPanel`, `useUploadsRegistry` | `uploads/page.tsx` |\n| Source display | Built into the `Chat` preset | `page.tsx` |\n| Upload API route | `createUploadHandler` | 1 line in `route.ts` |\n| AG-UI route | `createAgUiHandler` | 1 line in `route.ts` |\n| Agent definition | `agent()` | Config object in `agents/rag.ts` |\n| RAG retrieval | `beforeStream` hook | Context injection in `api/ag-ui/route.ts` |\n| Vector store | `ragStore()` | Config in `store.ts` |\n\n## Adding documents\n\n- Drop files into `content/`, then run `curl -X POST http://localhost:3000/api/ingest`\n- Or use the upload panel in the UI for PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and MD files\n\n## Production notes\n\nThis is a starter template, not a production-ready setup. For production, consider:\n\n- **Vector store**: Replace the default store with pgvector, Pinecone, or Qdrant for datasets beyond ~10k chunks\n- **Reranking**: Add a cross-encoder reranker (e.g. Cohere Rerank) after retrieval to improve precision\n- **Hybrid search**: Combine dense vectors with BM25 keyword matching for better recall\n",
+        "README.md": "# Docs Agent\n\nA chatbot that answers questions from your own documents using Retrieval-Augmented Generation (RAG).\n\n## What's included\n\n- Q&A agent with source citation\n- Embedding-based semantic search with convention-based model selection\n- Document upload supporting PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and Markdown\n- `ragStore()` with local JSON storage by default, and Veryfront Cloud RAG when bootstrap is present\n- Veryfront Cloud AI Gateway routing for generation and embeddings when bootstrap is present\n- Original uploaded files stored in Veryfront Cloud project uploads when cloud bootstrap is present\n- Sample content in `/content` indexed through a dedicated ingestion route\n\n## Getting started\n\n1. Set your Veryfront Cloud bootstrap vars:\n\n   ```bash\n   export VERYFRONT_API_TOKEN=vf_...\n   export VERYFRONT_PROJECT_SLUG=my-project\n   ```\n\n2. Start the dev server:\n\n   ```bash\n   npx veryfront@latest dev\n   ```\n\n3. Index the sample docs in `content/`:\n\n   ```bash\n   curl -X POST http://localhost:3000/api/ingest\n   ```\n\n4. Open the app and upload a document or ask a question.\n\nIf you are using a self-hosted Veryfront API, also set `VERYFRONT_API_URL`.\n\n## Cloud mode\n\nWith `VERYFRONT_API_TOKEN` and `VERYFRONT_PROJECT_SLUG` set, the template uses\nVeryfront Cloud automatically:\n\n- Agent generation routes through Veryfront Cloud model routing.\n- Query and document embeddings route through Veryfront Cloud embedding routing.\n- `veryfront-cloud/openai/...` and `veryfront-cloud/google/...` models use AI Gateway.\n- RAG documents, chunks, and embeddings are stored in the target project.\n\nThe default cloud embedding model is\n`veryfront-cloud/openai/text-embedding-3-small`. Set\n`VERYFRONT_DEFAULT_EMBEDDING_MODEL` only when you need a different embedding\nmodel.\n\n## Architecture\n\nRAG grounds LLM responses in your documents through three pipelines: **Ingestion**, **Query**, and **RAG**. These pipelines are orchestrated around a shared vector store.\n\n```mermaid\nflowchart LR\n    ChatUI_L[\"Chat UI\"]\n\n    subgraph IngestionFlow[\"Ingestion Pipeline\"]\n        D[\"Documents\"] --> EXT[\"Extraction\"] --> DC[\"Chunking\"] --> DE[\"Document\\nEmbedding\"] --> ING[\"Storage\"]\n    end\n\n    subgraph QueryFlow[\"Query Pipeline\"]\n        Q[\"Query\"] --> QE[\"Query\\nEmbedding\"] --> SS[\"Similarity\\nSearch\"]\n    end\n\n    subgraph RAGFlow[\"RAG Pipeline\"]\n        BF[\"beforeStream\\nHook\"] --> RET[\"Retrieval\"] --> AUG[\"Augmentation\"] --> AG[\"Agent\"] --> GEN[\"Generation\"]\n    end\n\n    EMB((\"Embedding\\nModel\"))\n    GEN_LLM((\"Generative\\nModel\"))\n    VS[(\"Vector\\nStore\")]\n    ChatUI_R[\"Chat UI\"]\n\n    ChatUI_L --> D\n    ChatUI_L --> Q\n\n    QE -.- EMB\n    DE -.- EMB\n\n    SS --> VS\n    ING --> VS\n\n    Q --> BF\n    VS --> RET\n    AG -.- GEN_LLM\n    GEN -.- GEN_LLM\n    GEN --> ChatUI_R\n```\n\n### Pipelines\n\n**Ingestion**: Documents are parsed into plain text via the built-in kreuzberg extraction engine (supporting PDF, DOCX, XLSX, PPTX, HTML, RTF, EPUB, and 76+ formats), split into overlapping chunks (~1000 chars, 200 char overlap), and stored in the default `ragStore()`. In local mode that means `data/index.json`; with Veryfront Cloud bootstrap it upgrades to the cloud RAG backend automatically. The original uploaded binary is also stored in the project's Veryfront Cloud uploads store so remote projects retain the source file, not just the extracted text. Uploaded files are ingested by the upload route. Bundled files in `content/` are ingested by the `/api/ingest` route.\n\n**Query**: The user's query is embedded into the same vector space as the documents, then compared against all stored chunks using cosine similarity to find the top-*k* most relevant results.\n\n**RAG**: The `beforeStream` hook in the AG-UI route intercepts each message before it reaches the agent. It searches the document store for relevant chunks, assembles them into context, and prepends them as retrieved reference data. The agent then generates a cited response streamed back to the user.\n\n## Structure\n\n```\nstore.ts                        RAG store config\nagents/rag.ts                   Q&A agent with citation instructions\ncontent/\n  getting-started.md            Sample document\n  architecture.md               Sample document\napp/\n  api/ag-ui/route.ts             AG-UI endpoint\n  api/ingest/route.ts            Bundled content ingestion\n  api/uploads/route.ts           Upload, list, and delete uploads\n  uploads/page.tsx               Upload management panel\n  page.tsx                       Chat UI\n  layout.tsx                     Chat shell with sidebar and tabs\n```\n\n## Framework usage\n\n| What | Framework | Template code |\n|------|-----------|---------------|\n| Chat UI + streaming | app-mode `Chat` | `page.tsx` |\n| Upload management | `AttachmentsPanel`, `useUploadsRegistry` | `uploads/page.tsx` |\n| Source display | Built into the `Chat` preset | `page.tsx` |\n| Upload API route | `createUploadHandler` | 1 line in `route.ts` |\n| AG-UI route | `createAgUiHandler` | 1 line in `route.ts` |\n| Agent definition | `agent()` | Config object in `agents/rag.ts` |\n| RAG retrieval | `beforeStream` hook | Context injection in `api/ag-ui/route.ts` |\n| Vector store | `ragStore()` | Config in `store.ts` |\n\n## Adding documents\n\n- Drop files into `content/`, then run `curl -X POST http://localhost:3000/api/ingest`\n- Or use the upload panel in the UI for PDF, DOCX, XLSX, PPTX, CSV, HTML, RTF, EPUB, TXT, and MD files\n\n## Production notes\n\nThis is a starter template, not a production-ready setup. For production, consider:\n\n- **Vector store**: Replace the default store with pgvector, Pinecone, or Qdrant for datasets beyond ~10k chunks\n- **Reranking**: Add a cross-encoder reranker (e.g. Cohere Rerank) after retrieval to improve precision\n- **Hybrid search**: Combine dense vectors with BM25 keyword matching for better recall\n",
         "store.ts": "import { ragStore } from \"veryfront/embedding\";\n\nexport const store = ragStore({\n  storagePath: \"data/index.json\",\n  contentDir: \"content\",\n});\n",
         "tsconfig.json": "{\n  \"compilerOptions\": {\n    \"target\": \"ES2022\",\n    \"module\": \"ESNext\",\n    \"moduleResolution\": \"bundler\",\n    \"strict\": true,\n    \"jsx\": \"react-jsx\",\n    \"skipLibCheck\": true,\n    \"esModuleInterop\": true,\n    \"noEmit\": true,\n    \"allowImportingTsExtensions\": true,\n    \"paths\": {\n      \"@/*\": [\"./*\"],\n      \"react-markdown@*\": [\"./node_modules/react-markdown\"],\n      \"remark-gfm@*\": [\"./node_modules/remark-gfm\"]\n    }\n  },\n  \"include\": [\"**/*.ts\", \"**/*.tsx\"],\n  \"exclude\": [\"node_modules\"]\n}\n"
       }
diff --git a/docs/api-reference/veryfront/cli.md b/docs/api-reference/veryfront/cli.md
index 6f01c5796c..dd8d267d39 100644
--- a/docs/api-reference/veryfront/cli.md
+++ b/docs/api-reference/veryfront/cli.md
@@ -7,7 +7,7 @@ order: 4
 ## Examples
 
 ```sh
-npx veryfront dev
+npx veryfront@latest dev
 ```
 
 ## Commands
diff --git a/docs/getting-started/deploy-project.md b/docs/getting-started/deploy-project.md
index 50f7a1576f..9d53ad2665 100644
--- a/docs/getting-started/deploy-project.md
+++ b/docs/getting-started/deploy-project.md
@@ -39,7 +39,7 @@ endpoints work.
 Create or link the cloud project and push the current source to its preview:
 
 ```bash
-npx veryfront push
+npx veryfront@latest push
 ```
 
 `veryfront push` stores local project identity in ignored
@@ -48,13 +48,13 @@ npx veryfront push
 `veryfront.json`.
 
 Push preserves remote-only files by default. Use
-`npx veryfront push --prune --dry-run` to preview an exact remote mirror, then
-run `npx veryfront push --prune` only when those deletions are intentional.
+`npx veryfront@latest push --prune --dry-run` to preview an exact remote mirror, then
+run `npx veryfront@latest push --prune` only when those deletions are intentional.
 
 For a preview deployment per branch:
 
 ```bash
-npx veryfront push --branch feature-x
+npx veryfront@latest push --branch feature-x
 ```
 
 ## Deploy to Veryfront Cloud
@@ -62,7 +62,7 @@ npx veryfront push --branch feature-x
 After checking the preview, deploy the exact pushed source digest:
 
 ```bash
-npx veryfront deploy --env production
+npx veryfront@latest deploy --env production
 ```
 
 Deploy uses the last verified Push receipt, verifies the release source digest,
diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md
index 84d6d1f68c..bc24bcd7e3 100644
--- a/docs/getting-started/installation.md
+++ b/docs/getting-started/installation.md
@@ -99,7 +99,7 @@ bun add -g veryfront
 Use `npx` when you do not want a global install:
 
 ```bash
-npx veryfront
+npx veryfront@latest
 ```
 
 Runs the latest published `veryfront` CLI without installing it globally.
diff --git a/docs/getting-started/quickstart.md b/docs/getting-started/quickstart.md
index 0cf7db8f58..b3d6f5a697 100644
--- a/docs/getting-started/quickstart.md
+++ b/docs/getting-started/quickstart.md
@@ -9,7 +9,7 @@ order: -1
 - Node.js 22.3 or later.
 
 The examples use `veryfront` commands. If you have not installed the CLI
-globally, run them with `npx veryfront ...`.
+globally, run them with `npx veryfront@latest ...`.
 
 ## Create the app
 
@@ -87,7 +87,7 @@ The answer should stream. The curl response should emit `data:` lines.
 From the project directory, push the source to its cloud preview:
 
 ```bash
-npx veryfront push
+npx veryfront@latest push
 ```
 
 The command creates or links the cloud project, stores that local identity in
@@ -95,11 +95,11 @@ ignored `.veryfront/project.json`, and prints the preview URL. When the preview
 is ready for production, deploy the exact pushed source digest:
 
 Push preserves remote-only files by default. Use
-`npx veryfront push --prune --dry-run` to preview an exact remote mirror, then
-run `npx veryfront push --prune` only when those deletions are intentional.
+`npx veryfront@latest push --prune --dry-run` to preview an exact remote mirror, then
+run `npx veryfront@latest push --prune` only when those deletions are intentional.
 
 ```bash
-npx veryfront deploy --env production
+npx veryfront@latest deploy --env production
 ```
 
 Deploy uses the last verified Push receipt. If no receipt exists yet, it first
diff --git a/docs/guides/build-a-rag-app.md b/docs/guides/build-a-rag-app.md
index d1bd3bb57d..285a2512ff 100644
--- a/docs/guides/build-a-rag-app.md
+++ b/docs/guides/build-a-rag-app.md
@@ -13,7 +13,7 @@ document sources.
 ```bash title="Terminal"
 veryfront init my-rag --template docs-agent
 cd my-rag
-npx veryfront dev
+npx veryfront@latest dev
 ```
 
 ## How RAG works
@@ -254,7 +254,7 @@ Set Veryfront Cloud bootstrap variables before starting the app:
 ```bash title="Terminal"
 export VERYFRONT_API_TOKEN=<TOKEN>
 export VERYFRONT_PROJECT_SLUG=<PROJECT_SLUG>
-npx veryfront dev
+npx veryfront@latest dev
 ```
 
 With cloud bootstrap:
diff --git a/docs/guides/deploying.md b/docs/guides/deploying.md
index 430badfb18..5081d22ce6 100644
--- a/docs/guides/deploying.md
+++ b/docs/guides/deploying.md
@@ -65,7 +65,7 @@ and production responses with `curl`.
 Create or link the cloud project and push the current source to its preview:
 
 ```bash
-npx veryfront push
+npx veryfront@latest push
 ```
 
 `veryfront push` stores local project identity in ignored
@@ -74,22 +74,22 @@ npx veryfront push
 `veryfront.json`.
 
 Push preserves remote-only files by default. Use
-`npx veryfront push --prune --dry-run` to preview an exact remote mirror, then
-run `npx veryfront push --prune` only when those deletions are intentional.
+`npx veryfront@latest push --prune --dry-run` to preview an exact remote mirror, then
+run `npx veryfront@latest push --prune` only when those deletions are intentional.
 
 For an existing nonproduction environment named `staging`:
 
 ```bash
-npx veryfront push --branch feature-x
-npx veryfront deploy --branch feature-x --env staging
+npx veryfront@latest push --branch feature-x
+npx veryfront@latest deploy --branch feature-x --env staging
 ```
 
 Deploy uses the last verified Push receipt and verifies the release was built
 from that exact source digest before assigning it to the environment. If no Push
 receipt exists, Deploy first runs a quiet Push so the first deployment still
-works as one command. Use `veryfront open` after deployment to open the project.
-Deploy prints the environment URL; use `veryfront open --json` when automation
-needs the same URL later.
+works as one command. Use `npx veryfront@latest open` after deployment to open
+the project. Deploy prints the environment URL; use
+`npx veryfront@latest open --json` when automation needs the same URL later.
 
 Project reference precedence is `VERYFRONT_PROJECT_SLUG` or environment
 configuration, then `veryfront.config.ts`, then legacy `veryfront.json`, then
diff --git a/docs/rfcs/0001-ui-primitive-adapters.md b/docs/rfcs/0001-ui-primitive-adapters.md
index 389668f0c8..5b89233e7d 100644
--- a/docs/rfcs/0001-ui-primitive-adapters.md
+++ b/docs/rfcs/0001-ui-primitive-adapters.md
@@ -511,7 +511,7 @@ contract demands: `onOpenChange` drops Base UI's 2nd arg; positioning goes to
 surface inside the token scope; and we re-emit `data-vf-state`:
 
 ```tsx
-// ./ui-adapters/base-ui.tsx — vendored into YOUR repo (npx veryfront add adapter base-ui)
+// ./ui-adapters/base-ui.tsx — vendored into YOUR repo (npx veryfront@latest add adapter base-ui)
 import * as React from "react";
 import { Popover as Base } from "@base-ui/react/popover"; // YOUR dependency, YOUR version
 import { useTokenScopeRef, type PopoverParts } from "veryfront/ui/adapter";
@@ -558,7 +558,7 @@ parts, so the adapter *owns the DOM* and spreads prop-getters, absorbs the
 `isOpen` naming and the two-step `useOverlayTrigger → useButton` trigger:
 
 ```tsx
-// ./ui-adapters/react-aria.tsx — vendored into YOUR repo (npx veryfront add adapter react-aria)
+// ./ui-adapters/react-aria.tsx — vendored into YOUR repo (npx veryfront@latest add adapter react-aria)
 import * as React from "react";
 import { DismissButton, Overlay, useButton, useOverlayTrigger, usePopover } from "react-aria";
 import { useOverlayTriggerState } from "react-stately";
diff --git a/scripts/postinstall.js b/scripts/postinstall.js
index eed0f23ce0..c46d288ea0 100644
--- a/scripts/postinstall.js
+++ b/scripts/postinstall.js
@@ -115,8 +115,8 @@ async function install() {
 
     console.log('✅ Veryfront CLI installed successfully!');
     console.log('\n🚀 Get started:');
-    console.log('   npx veryfront --help');
-    console.log('   npx veryfront create my-app');
+    console.log('   npx veryfront@latest --help');
+    console.log('   npx veryfront@latest create my-app');
 
   } catch (error) {
     // Clean up unverified binary so the JS fallback is used instead
diff --git a/tests/docs/guide-code-examples.test.ts b/tests/docs/guide-code-examples.test.ts
index 63f23bbfaf..e0f43edbb1 100644
--- a/tests/docs/guide-code-examples.test.ts
+++ b/tests/docs/guide-code-examples.test.ts
@@ -541,8 +541,8 @@ describe("Guide: deploying.md", () => {
         "veryfront dev",
         "veryfront build",
         "veryfront serve",
-        "npx veryfront deploy",
-        "npx veryfront deploy --branch feature-x --env staging",
+        "npx veryfront@latest deploy",
+        "npx veryfront@latest deploy --branch feature-x --env staging",
         "veryfront open",
       ]
     ) {
@@ -924,7 +924,7 @@ describe("Guide: installation.md", () => {
       "pnpm add -g veryfront",
       "yarn global add veryfront",
       "bun add -g veryfront",
-      "npx veryfront",
+      "npx veryfront@latest",
       "veryfront install agents",
       "veryfront --version",
     ];
@@ -1013,8 +1013,8 @@ describe("Guide: deploy-project.md", () => {
       const command of [
         "veryfront build",
         "veryfront serve",
-        "npx veryfront deploy",
-        "npx veryfront push --branch feature-x",
+        "npx veryfront@latest deploy",
+        "npx veryfront@latest push --branch feature-x",
         "veryfront open",
       ]
     ) {
diff --git a/tests/docs/guide-content.test.ts b/tests/docs/guide-content.test.ts
index 315b866140..bd3cc83b91 100644
--- a/tests/docs/guide-content.test.ts
+++ b/tests/docs/guide-content.test.ts
@@ -143,7 +143,7 @@ describe("guide content contracts", () => {
     const guide = await Deno.readTextFile("docs/guides/deploying.md");
 
     assertStringIncludes(guide, "prints the environment URL");
-    assertStringIncludes(guide, "veryfront open");
+    assertStringIncludes(guide, "npx veryfront@latest open");
   });
 
   it("uses serve for local production builds", async () => {
@@ -165,12 +165,13 @@ describe("guide content contracts", () => {
       "docs/getting-started/deploy-project.md",
       "docs/guides/deploying.md",
     ];
-    const deploy = "npx veryfront deploy";
+    const deploy = "npx veryfront@latest deploy";
 
     for (const path of docs) {
       const text = await Deno.readTextFile(path);
 
       assertStringIncludes(text, deploy);
+      assertEquals(text.includes("npx veryfront deploy"), false);
       assertStringIncludes(text, "It does not write");
       assertStringIncludes(text, "`veryfront.json`");
       assertStringIncludes(text, "last verified Push receipt");
diff --git a/tests/docs/guide-contracts.test.ts b/tests/docs/guide-contracts.test.ts
index a9272f2249..20b493edce 100644
--- a/tests/docs/guide-contracts.test.ts
+++ b/tests/docs/guide-contracts.test.ts
@@ -228,7 +228,7 @@ const GUIDE_CONTRACTS: Record<string, GuideContract> = {
     ],
     snippets: [
       "npm create veryfront@latest support-agent",
-      "npx veryfront deploy",
+      "npx veryfront@latest deploy",
       "calculator.ts",
       "What is 128 divided by 8?",
       "curl -N -X POST",
@@ -260,7 +260,7 @@ const GUIDE_CONTRACTS: Record<string, GuideContract> = {
       "Pick one production path",
       "veryfront build",
       "veryfront serve",
-      "npx veryfront deploy",
+      "npx veryfront@latest deploy",
       "last verified Push receipt",
       "prints the environment URL",
       "veryfront open",
@@ -634,7 +634,7 @@ const GUIDE_CONTRACTS: Record<string, GuideContract> = {
       "deno add npm:veryfront",
       "npm create veryfront",
       "npm install -g veryfront",
-      "npx veryfront",
+      "npx veryfront@latest",
       "veryfront install agents",
     ],
   },
@@ -704,7 +704,7 @@ const GUIDE_CONTRACTS: Record<string, GuideContract> = {
     snippets: [
       "veryfront build",
       "veryfront serve",
-      "npx veryfront deploy",
+      "npx veryfront@latest deploy",
       "last verified Push receipt",
       "prints the environment URL",
       "veryfront open",