@vxil/cli 0.20.2 → 0.21.0

package/dist/_vxil-feature-configs-geminiThinking.d.ts

@@ -0,0 +1,16 @@
+export declare const AI_THINKING_LEVELS: readonly ["minimal", "low", "medium", "high"];
+export type GeminiThinkingLevel = (typeof AI_THINKING_LEVELS)[number];
+/** The lowest thinking level the model accepts. 3.x thinks by default; the
+ *  2.5-era `thinkingBudget:0` is INVALID on 3.x, and `thinkingLevel:'minimal'`
+ *  (which zeroes thought tokens) is accepted by gemini-3-flash … 3.6-flash and
+ *  every flash-lite, but REJECTED with a 400 ("Thinking level MINIMAL is not
+ *  supported for this model") by gemini-3.7-flash and gemini-3.8-flash
+ *  (measured 2026-10-03 on the staging key). Unknown model shapes (incl. the
+ *  Pro models) get 'low': it is the one level measured as accepted on every
+ *  3.x model tried. */
+export declare function minimalThinkingLevel(model: string): GeminiThinkingLevel;
+/** Null when `model` is not known to reject `level`, else the reason. Only
+ *  'minimal' is checked (per the table above). Measured: 'low' on every 3.x
+ *  model tried; medium/high are NOT verified per model — a model that rejects
+ *  one fails as a provider 4xx after the reserve (refunded), not here. */
+export declare function geminiThinkingLevelError(model: string, level: GeminiThinkingLevel): string | null;

package/dist/_vxil-feature-configs.d.ts

@@ -1,4 +1,5 @@
 import { type Static, type TSchema } from '@sinclair/typebox';
+export { AI_THINKING_LEVELS, geminiThinkingLevelError, minimalThinkingLevel, type GeminiThinkingLevel } from './_vxil-feature-configs-geminiThinking.js';
 export * from './_vxil-feature-configs-hooks.js';
 export * from './_vxil-feature-configs-readmodels.js';
 export * from './_vxil-feature-configs-apiState.js';
@@ -605,11 +606,12 @@ export declare const AiConfigSchema: import("@sinclair/typebox").TObject<{
             openaiBaseUrl: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
         }>>;
     }>;
-    defaults: import("@sinclair/typebox").TObject<{
+    defaults: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TObject<{
         model: import("@sinclair/typebox").TString;
         maxTokens: import("@sinclair/typebox").TInteger;
         temperature: import("@sinclair/typebox").TNumber;
-    }>;
+        thinkingLevel: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TUnion<import("@sinclair/typebox").TLiteral<"minimal" | "low" | "medium" | "high">[]>>;
+    }>>;
     cache: import("@sinclair/typebox").TObject<{
         ttlSeconds: import("@sinclair/typebox").TInteger;
     }>;

package/dist/vxil.js

@@ -3383,6 +3383,9 @@ var PublicAssetsConfigSchema = Type.Object({
   ))
 });
 
+// ../feature-configs/src/geminiThinking.ts
+var AI_THINKING_LEVELS = ["minimal", "low", "medium", "high"];
+
 // ../feature-configs/src/canonicalJson.ts
 function canonicalJson(v) {
   if (Array.isArray(v)) return `[${v.map((x) => canonicalJson(x) ?? "null").join(",")}]`;
@@ -3963,8 +3966,8 @@ var FilesConfigSchema = Type.Object({
       // (pricing review 2026-07-10). 5 GiB/object, 1 TiB/tenant absolute.
       maxObjectBytes: Type.Integer({ default: 100 * 1024 * 1024, minimum: 1, maximum: 5 * 1024 * 1024 * 1024 }),
       // NO default (2026-10-04): UNSET means "the plan's storage ceiling"
-      // (control-plane plans.ts FILES_MAX_TOTAL_BYTES_BY_TIER — Free/Developer
-      // 10 GiB, Team 50 GiB, Business 256 GiB, Enterprise 1 TiB), resolved by
+      // (control-plane plans.ts FILES_MAX_TOTAL_BYTES_BY_TIER — Free 10 GiB,
+      // Developer 25 GiB, Team 150 GiB, Business 256 GiB, Enterprise 1 TiB), resolved by
       // files-v1 where the quota is enforced, so a plan change applies at once.
       // A value is the project's own LOWER cap (above the plan → 422 at config
       // write; a downgrade clamps it). It used to default to 10 GiB on every
@@ -4469,11 +4472,18 @@ var AiConfigSchema = Type.Object({
       openaiBaseUrl: Type.Optional(Type.String({ maxLength: 512 }))
     }))
   }, { default: {} }),
-  defaults: Type.Object({
+  // `defaults` became an OPTIONAL bag (3 leaves → 1, the `streaming` trick) on
+  // 2026-10-10 to carry `thinkingLevel` (AI-THINKING-LEVEL). It KEEPS
+  // `default: {}`, so Value.Default still materializes
+  // defaults.{model,maxTokens,temperature} exactly as before; `thinkingLevel`
+  // has NO default (absent = the model's own default), so an existing manifest
+  // stays byte-identical. Sent to Gemini only; validated per model below.
+  defaults: Type.Optional(Type.Object({
     model: Type.String({ default: "mock-1" }),
     maxTokens: Type.Integer({ default: 1024, minimum: 1, maximum: 2e5 }),
-    temperature: Type.Number({ default: 0.7, minimum: 0, maximum: 2 })
-  }, { default: {} }),
+    temperature: Type.Number({ default: 0.7, minimum: 0, maximum: 2 }),
+    thinkingLevel: Type.Optional(Type.Union(AI_THINKING_LEVELS.map((l) => Type.Literal(l))))
+  }, { default: {} })),
   cache: Type.Object({ ttlSeconds: Type.Integer({ default: 0, minimum: 0 }) }, { default: {} }),
   // 0 = off
   limits: Type.Object({
@@ -5065,14 +5075,16 @@ function lowerAllTriggerBindings(def, name) {
   return bindings;
 }
 var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
-var VXIL_CONFIG_PKG_VERSION = "0.13.0";
-var VXIL_SDK_PKG_VERSION = "0.20.1";
-var VXIL_CLI_PKG_VERSION = "0.20.2";
+var VXIL_CONFIG_PKG_VERSION = "0.14.0";
+var VXIL_SDK_PKG_VERSION = "0.21.0";
+var VXIL_CLI_PKG_VERSION = "0.21.0";
 function ensureScaffoldPackageJson(cwd, opts = {}) {
   const file = resolve(cwd, "package.json");
   const wanted = {
     "@vxil/config": `^${VXIL_CONFIG_PKG_VERSION}`,
-    ...opts.sdkTypes ? { "@vxil/sdk": `^${VXIL_SDK_PKG_VERSION}` } : {}
+    ...opts.sdkTypes ? { "@vxil/sdk": `^${VXIL_SDK_PKG_VERSION}` } : {},
+    // the scaffolded tsconfig.json names `types: ["node"]` (CLI-TS-SCAFFOLD)
+    ...opts.nodeTypes ? { "@types/node": SCAFFOLD_NODE_TYPES_RANGE } : {}
   };
   if (!existsSync(file)) {
     writeFileSync(file, JSON.stringify({
@@ -5102,6 +5114,24 @@ function ensureScaffoldPackageJson(cwd, opts = {}) {
   writeFileSync(file, JSON.stringify(pkg, null, 2) + "\n");
   return { action: "added" };
 }
+var SCAFFOLD_NODE_TYPES_RANGE = "^24.0.0";
+var SCAFFOLD_TSCONFIG = {
+  compilerOptions: {
+    target: "ES2022",
+    module: "ESNext",
+    moduleResolution: "bundler",
+    strict: true,
+    skipLibCheck: true,
+    noEmit: true,
+    types: ["node"]
+  }
+};
+function ensureScaffoldTsconfig(cwd) {
+  const file = resolve(cwd, "tsconfig.json");
+  if (existsSync(file)) return "exists";
+  writeFileSync(file, JSON.stringify(SCAFFOLD_TSCONFIG, null, 2) + "\n");
+  return "created";
+}
 function apiErrText(r) {
   const e = r.body.error;
   if (!e) return `${r.status}`;
@@ -5353,6 +5383,49 @@ async function serverApply({ api, bundle, resume, allowDestructive, onPlan }) {
   );
 }
 var PUSH_READ_CONCURRENCY = 5;
+var CMS_ENABLE_MANIFEST = { enabled: true };
+function cmsEnableManifest(declared) {
+  return declared.limits !== void 0 ? { ...CMS_ENABLE_MANIFEST, limits: declared.limits } : { ...CMS_ENABLE_MANIFEST };
+}
+async function enableCmsBeforeSchema({ api, cfg }) {
+  const declared = cfg.features?.cms;
+  if (!Object.keys(cfg.cms?.collections ?? {}).length || !declared || declared.enabled === false) return null;
+  const cur = await api("GET", "/v1/config/cms");
+  if (classifyRead(cur.status, cur.body?.error?.code) !== "empty") return null;
+  const dry = await api("PUT", "/v1/config/cms?dry_run=true", declared);
+  if (dry.status !== 200) {
+    const e = dry.body.error ?? {};
+    throw new Error(`invalid config for cms: ${e.code ?? dry.status} ${e.message ?? ""} ${e.hint ?? ""}`.trim() + "\n(nothing was pushed)");
+  }
+  const put = await api("PUT", "/v1/config/cms", cmsEnableManifest(declared));
+  if (put.status !== 200) {
+    const e = put.body.error ?? {};
+    throw new Error(`cms: could not enable cms before its schema: ${e.code ?? put.status} ${e.message ?? ""} ${e.hint ?? ""}`.trim());
+  }
+  return put.body.data?.version ?? 0;
+}
+var CMS_PROPAGATION_ATTEMPTS = 4;
+var CMS_PROPAGATION_DELAY_MS = 1e4;
+function retryWhileCmsPropagates(api, opts = {}) {
+  const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+  const attempts = opts.attempts ?? CMS_PROPAGATION_ATTEMPTS;
+  const delayMs = opts.delayMs ?? CMS_PROPAGATION_DELAY_MS;
+  let waited = 0;
+  return async (method, path, body) => {
+    for (; ; ) {
+      const res = await api(method, path, body);
+      const propagating = path.startsWith("/v1/cms/") && res.status === 501 && (res.body?.error?.code ?? "capability_not_enabled") === "capability_not_enabled";
+      if (!propagating || waited >= attempts) return res;
+      waited++;
+      opts.onWait?.(`  \u2026 cms config propagating (just enabled) \u2014 retrying in ${Math.round(delayMs / 1e3)} s (${waited}/${attempts})`);
+      await sleep(delayMs);
+    }
+  };
+}
+function onlyPropagationDeferred(steps) {
+  const errored = steps.filter((st) => st.status === "pending" && st.error);
+  return errored.length > 0 && errored.every((st) => (st.kind === "api-state" || st.kind === "cms.collection" || st.kind === "cms.field") && (st.error ?? "").startsWith("deferred:"));
+}
 async function planOrPush({ api, features, apply, allowDestructive }) {
   const results = [];
   const destructiveQs = allowDestructive ? "&allow_destructive=true" : "";
@@ -9561,7 +9634,7 @@ var API_CHEATSHEET = [
   { feature: "orgs", what: "add / remove a member", cmd: `vxil api POST /v1/orgs/<org_id>/members '{"user_id":"<id>","role":"member"}'   \xB7 vxil api DELETE /v1/orgs/<org_id>/members/<user_id>` },
   { feature: "orgs", what: "invite by e-mail (the token is returned once) / revoke", cmd: `vxil api POST /v1/orgs/<org_id>/invitations '{"email":"a@example.com","role":"member"}'   \xB7 vxil api DELETE /v1/orgs/invitations/<invite_id>` },
   // feeds
-  { feature: "activity-feed", what: "block or mute a feed for a user", cmd: `vxil api POST /v1/feeds/blocks '{"owner":"<user>","blocked":"<user>","mode":"block"}'` },
+  { feature: "activity-feed", what: "block or mute a feed for a user", cmd: `vxil api POST /v1/feeds/blocks '{"owner":"timeline:<reader_id>","blocked":"user:<author_id>","mode":"block"}'` },
   { feature: "activity-feed", what: "remove an activity", cmd: "vxil api DELETE /v1/feeds/<group>/<feed_id>/activities/<ref>" }
 ];
 function apiCheatSheet() {
@@ -11876,7 +11949,9 @@ function genInputFromConfig(cfg) {
 }
 function typesCheckBody(src) {
   const i = src.indexOf("export interface VxilSchema");
-  return i >= 0 ? src.slice(i) : src;
+  const body = i >= 0 ? src.slice(i) : src;
+  const usage = body.indexOf("\n// Usage \u2014 ");
+  return usage >= 0 ? body.slice(0, usage) : body;
 }
 function checkGeneratedTypes(existing, generated, opts) {
   let have = typesCheckBody(withCurrentApiVersionsHead(existing));
@@ -11947,7 +12022,7 @@ export type VxilFilterJson = string | number | boolean | { $eq?: string | number
 // Usage \u2014 narrow the client to THIS tenant's enabled features (a disabled feature
 // becomes a compile error):
 //   import { Vxil } from '@vxil/sdk';
-//   import type { VxilSchema } from './vxil.types';
+//   import type { VxilSchema } from './vxil.types.js';
 //   const vx = Vxil.connect<VxilSchema>({ apiKey: process.env.VXIL_API_KEY! });
 //   await vx.from('${colls[0]?.collection ?? "collection"}').create({ /* field-typed */ });
 `;
@@ -13552,7 +13627,7 @@ var TOOLS = [
   {
     name: "search_query",
     feature: "vector-search",
-    description: "Retrieve the top-k most relevant chunks from a vector-search collection. mode 'hybrid' (default) fuses semantic + keyword via RRF; 'vector' is pure semantic; 'keyword' is lexical. filter is a JSON object of equality constraints over chunk metadata. Returns ranked results with document/chunk attribution: score is the fused rank value (orders the hits, not a similarity); similarity is the cosine similarity to the query (-1..1, null in keyword mode) \u2014 threshold on similarity.",
+    description: "Retrieve the top-k most relevant chunks from a vector-search collection. mode 'hybrid' (default) fuses semantic + keyword via RRF; 'vector' is pure semantic; 'keyword' is lexical. filter is a JSON object of equality constraints over chunk metadata. Returns ranked results with document/chunk attribution: score is the fused rank value (orders the hits, not a similarity); similarity is the cosine similarity to the query (-1..1, null in keyword mode) \u2014 threshold on similarity. embed_provider names the collection's embedder; 'mock' is the deterministic test embedder (ranks by a hash, not meaning), so tell the user search is not semantic until a real provider is set.",
     inputSchema: {
       type: "object",
       properties: {
@@ -13582,6 +13657,11 @@ var TOOLS = [
         model: { type: "string" },
         max_tokens: { type: "number", minimum: 1, maximum: 2e5 },
         temperature: { type: "number", minimum: 0, maximum: 2 },
+        thinking_level: {
+          type: "string",
+          enum: ["minimal", "low", "medium", "high"],
+          description: "Gemini thinking depth (ignored by other providers). Omitted: the tenant's defaults.thinkingLevel, then the model default. 'minimal' on a model that rejects it is a 422 thinking_level_unsupported. Thinking tokens bill as output."
+        },
         json_mode: { type: "boolean", description: "Constrain the output to JSON (no schema \u2014 use response_schema for a guaranteed shape)." },
         response_schema: {
           type: "object",
@@ -13712,7 +13792,7 @@ var TOOLS = [
   {
     name: "rag_answer",
     feature: "rag",
-    description: "Answer a question grounded in a vector-search collection: retrieve \u2192 budget context \u2192 generate \u2192 cite. Defaults the collection/template/top_k/mode from the rag config; override per call. Returns the answer plus citations to the source chunks that grounded it.",
+    description: "Answer a question grounded in a vector-search collection: retrieve \u2192 budget context \u2192 generate \u2192 cite. Defaults the collection/template/top_k/mode from the rag config; override per call. Returns the answer plus citations to the source chunks that grounded it, and embed_provider (the collection's embedder; 'mock' = the deterministic test embedder, so retrieval is not semantic yet). The collection must exist first (POST /v1/search/collections, SDK vx.search.createCollection); a missing one fails retrieval with upstream collection_not_found.",
     inputSchema: {
       type: "object",
       properties: {
@@ -13736,7 +13816,7 @@ var TOOLS = [
   {
     name: "rag_search",
     feature: "rag",
-    description: "Retrieval-only grounding preview: the exact chunks rag_answer would ground on, with rerank + metadata boosts applied \u2014 no generation, no token spend. Use it to inspect/tune retrieval (boost weights, rerank, min_similarity) before paying for an answer.",
+    description: "Retrieval-only grounding preview: the exact chunks rag_answer would ground on, with rerank + metadata boosts applied \u2014 no generation, no token spend. Use it to inspect/tune retrieval (boost weights, rerank, min_similarity) before paying for an answer. embed_provider names the collection's embedder (mock = the deterministic test embedder, not semantic).",
     inputSchema: {
       type: "object",
       properties: {
@@ -13882,7 +13962,7 @@ var TOOLS = [
     // Substrate tool (no `feature` — always-on like users_upsert): usage is a
     // platform property, not a feature you enable.
     name: "usage_current",
-    description: "Current-month usage for this project: requests used, the plan's included quota, remaining (null when the plan has no fixed cap), month-to-date per-feature metered detail (may lag \u2014 it is aggregated periodically), and `routes` \u2014 the same request count split by the surface that served it (the resolved upstream; /v1/fn/* reports as 'fn-invoke', busiest first, observational only). Read-only. Call this before a bulk run to self-check remaining quota: the Free tier is hard-capped (429 quota_exceeded when exhausted); paid tiers are never cut off mid-month. Needs usage:read or features:read.",
+    description: "Current-month usage for this project: requests used, the plan's included quota, remaining (null when the plan has no fixed cap), month-to-date per-feature metered detail (may lag \u2014 it is aggregated periodically), and `routes` \u2014 the same request count split by the surface that served it (the resolved upstream; /v1/fn/* reports as 'fn-invoke', busiest first, observational only), `files` (live private objects and bytes vs the storage `limit` uploads are held to \u2014 422 quota_exceeded at it) and `functions` (today's UTC call count vs the plan's `limit_per_day`; a snapshot that can trail by a minute or two, null when there is no snapshot for today). Read-only. Call this before a bulk run to self-check remaining quota: the Free tier is hard-capped (429 quota_exceeded when exhausted); paid tiers are never cut off mid-month. Needs usage:read or features:read.",
     inputSchema: { type: "object", properties: {} },
     method: "GET",
     path: "/v1/usage"
@@ -14440,6 +14520,21 @@ function notificationsProviderChecks(manifest) {
   }
   return [{ name: "notifications provider", ok: true, warn: true, detail: MOCK_PROVIDER_NOTE }];
 }
+var EMBED_MOCK_NOTE = "vector-search embed provider is 'mock': the deterministic TEST embedder ranks by a hash of the text, not by meaning, so search and rag results look real but are not semantic (responses carry embed_provider: 'mock'). Store a provider key (`vxil secrets set vector-search/<name>`) and set embed: { provider: 'openai' | 'cohere', apiKeyRef } in your vector-search config (or 'byov' to supply your own vectors) before you ship";
+function embedProviderChecks(manifest, collections) {
+  if (!manifest || manifest.enabled === false) return [];
+  const def = manifest.embed?.provider ?? "mock";
+  const mockCols = (collections ?? []).filter((c) => (c.provider ?? def) === "mock").map((c) => c.collection);
+  if (def !== "mock" && !mockCols.length) {
+    return [{ name: "vector-search embed provider", ok: true, detail: def }];
+  }
+  return [{
+    name: "vector-search embed provider",
+    ok: true,
+    warn: true,
+    detail: EMBED_MOCK_NOTE + (mockCols.length ? `. Collections on 'mock': ${mockCols.join(", ")} \u2014 a collection keeps the provider it was created with: create it again with the real embed provider (same name and dimensions) and re-ingest its documents` : "")
+  }];
+}
 var PAYMENTS_WEBHOOK_SECRET_NOTE = "payments provider is real but no per-tenant webhook secret is declared: every inbound provider delivery will be rejected 401 bad_signature and recorded as a sig_failed row (those rows can never be reprocessed, so the money events behind them are lost). There is NO platform-wide fallback. Declare <provider>.webhookSecretRef in your payments config and store the value with `vxil secrets set payments/<name>`";
 function paymentsWebhookSecretChecks(manifest) {
   if (!manifest || manifest.enabled === false) return [];
@@ -15219,10 +15314,10 @@ function renderTryReport(result, opts) {
   if (genOk) {
     lines.push("\n  try it (types were generated in ./vxil.types.ts):");
     lines.push("    import { Vxil } from '@vxil/sdk';");
-    lines.push("    import type { VxilSchema } from './vxil.types';");
+    lines.push("    import type { VxilSchema } from './vxil.types.js';");
     lines.push(`    const vx = Vxil.connect<VxilSchema>({ apiKey: '${result.api_key}', baseUrl: '${opts.base}' });`);
   } else {
-    lines.push("\n  try it (typed client skipped \u2014 `npm i -D vxil && npm i @vxil/sdk`, then `npx vxil gen`):");
+    lines.push("\n  try it (typed client skipped \u2014 `npm i -D @vxil/cli && npm i @vxil/sdk`, then `npx vxil gen`):");
     lines.push("    import { Vxil } from '@vxil/sdk';");
     lines.push(`    const vx = new Vxil({ apiKey: '${result.api_key}', baseUrl: '${opts.base}' });`);
   }
@@ -21455,10 +21550,19 @@ async function runApply(apply, sel = "prod", opts = {}) {
       report.errors++;
     }
   };
+  let cmsApi = api;
+  if (apply) {
+    const enabledAt = await enableCmsBeforeSchema({ api, cfg });
+    if (enabledAt !== null) {
+      console.log(`
+cms: enabled (v${enabledAt}) before its schema \u2014 the declared cms config follows in the config step`);
+      cmsApi = retryWhileCmsPropagates(api, { onWait: (line) => console.log(line) });
+    }
+  }
   await runSection("cms.schema", async () => {
     if (!cfg.cms?.collections || !Object.keys(cfg.cms.collections).length) return;
     const r = await planCmsSchema({
-      api,
+      api: cmsApi,
       collections: cfg.cms.collections,
       apply,
       allowDestructive: hasFlag("allow-destructive"),
@@ -21873,15 +21977,11 @@ ${formatTriggerWiring(w).join("\n")}`);
       say("\napplying server-side\u2026");
     }
   });
-  if (done.status === "running") {
-    const errored = done.steps.filter((st) => st.status === "pending" && st.error);
-    const onlyDeferredApiState = errored.length > 0 && errored.every((st) => st.kind === "api-state" && (st.error ?? "").startsWith("deferred:"));
-    if (onlyDeferredApiState) {
-      report(done, false);
-      say("  \u2026 declared API state deferred (the feature config is still propagating) \u2014 waiting 30 s, then resuming the same apply");
-      await new Promise((r) => setTimeout(r, 3e4));
-      done = await serverApply({ api, resume: done.apply_id });
-    }
+  for (let attempt = 1; done.status === "running" && onlyPropagationDeferred(done.steps) && attempt <= CMS_PROPAGATION_ATTEMPTS; attempt++) {
+    if (attempt === 1) report(done, false);
+    say(`  \u2026 deferred: the feature config is still propagating \u2014 waiting ${CMS_PROPAGATION_DELAY_MS / 1e3} s, then resuming the same apply (${attempt}/${CMS_PROPAGATION_ATTEMPTS})`);
+    await new Promise((r) => setTimeout(r, CMS_PROPAGATION_DELAY_MS));
+    done = await serverApply({ api, resume: done.apply_id });
   }
   report(done, true);
   const problems = { hard: [], strict: [] };
@@ -22142,6 +22242,16 @@ async function runDoctor() {
           ));
         }
       }
+      if (live.has("vector-search")) {
+        const vres = await api("GET", "/v1/config/vector-search");
+        if (vres.status === 200) {
+          const cres = await api("GET", "/v1/search/collections");
+          checks.push(...embedProviderChecks(
+            vres.body.data?.manifest,
+            cres.status === 200 ? cres.body.data?.collections ?? [] : null
+          ));
+        }
+      }
       if (live.has("payments")) {
         const pres = await api("GET", "/v1/config/payments");
         if (pres.status === 200) {
@@ -22279,11 +22389,19 @@ function scaffoldProject(configSrc, fns) {
   const gi = resolve7(cwd, ".gitignore");
   const ignore = ["", "# vxil", ".vxil/", ".env.local", ""].join("\n");
   if (!existsSync8(gi) || !readFileSync8(gi, "utf8").includes(".vxil/")) appendFileSync2(gi, ignore);
-  const pkg = ensureScaffoldPackageJson(cwd, { sdkTypes: entries.some(([, src]) => src.includes("from '@vxil/sdk'")) });
+  const freshFolder = !existsSync8(resolve7(cwd, "package.json"));
+  const tsconfig = freshFolder ? ensureScaffoldTsconfig(cwd) : existsSync8(resolve7(cwd, "tsconfig.json")) ? "exists" : "suggested";
+  const pkg = ensureScaffoldPackageJson(cwd, {
+    sdkTypes: entries.some(([, src]) => src.includes("from '@vxil/sdk'")),
+    nodeTypes: tsconfig === "created"
+  });
   if (pkg.action === "skipped") console.log(`  ! package.json not patched: ${pkg.reason}`);
-  return pkg;
+  if (tsconfig === "suggested") {
+    console.log('  (no tsconfig.json written into an existing app \u2014 to type-check vxil.config.ts / functions, use moduleResolution "bundler" and add @types/node)');
+  }
+  return { ...pkg, tsconfig };
 }
-function initProject() {
+function initProject(opts = {}) {
   const cwd = process.cwd();
   const cfgPath = resolve7(cwd, "vxil.config.ts");
   if (existsSync8(cfgPath) && !hasFlag("force")) fail("vxil.config.ts already exists (use --force to overwrite)");
@@ -22302,8 +22420,10 @@ function initProject() {
     const sdk = Object.values(tpl.functions ?? {}).some((src) => src.includes("from '@vxil/sdk'"));
     console.log(`  package.json       # declares @vxil/config (the config import)${sdk ? " + @vxil/sdk (the functions' envelope types)" : ""}`);
   }
+  if (pkgRes.tsconfig === "created") console.log('  tsconfig.json      # minimal: moduleResolution bundler, types ["node"]');
+  if (opts.fromQuickstart) return;
   console.log("\nnext: `vxil quickstart` (new tenant) or `vxil link <slug>` (existing), then `vxil push`.");
-  console.log("      (`npm install` is optional \u2014 it gives your editor the types; the CLI runs vxil.config.ts and bundles functions without it.)");
+  console.log("      (the CLI runs vxil.config.ts and bundles functions without `npm install`; run it to type-check \u2014 tsc and your editor need the installed types.)");
 }
 function listTemplates() {
   console.log("vxil templates \u2014 the Blueprint Gallery. Scaffold one with `vxil init --template <id>`.\n");
@@ -22381,7 +22501,7 @@ try {
       saveProject(hasFlag("dev") ? { ...merged, dev: { tenant_id: slot.tenant_id, slug: slot.slug, edge_url: slot.edge_url } } : merged);
       const envNotice = quickstartEnvNotice(flag("env"), base2, d.app_slug, { dev: hasFlag("dev") });
       if (envNotice) console.error(`vxil: ${envNotice}`);
-      if (!existsSync8(resolve7(process.cwd(), "vxil.config.ts"))) initProject();
+      if (!existsSync8(resolve7(process.cwd(), "vxil.config.ts"))) initProject({ fromQuickstart: true });
       console.log(`
 \u2713 tenant '${d.app_slug}' created \xB7 enabled: ${(d.enabled ?? []).join(", ")}`);
       if (d.expires_at) console.log(`  dev tenant \u2014 expires ${d.expires_at} (the nightly reaper tears it down; extend by recreating)`);
@@ -22411,11 +22531,12 @@ try {
       console.log(`     types:      ./vxil.types.ts  (generated \u2014 re-run \`vxil gen\` after a schema change)`);
       console.log(`     try it:`);
       console.log(`       import { Vxil } from '@vxil/sdk';`);
-      console.log(`       import type { VxilSchema } from './vxil.types';`);
-      console.log(`       const vx = Vxil.connect<VxilSchema>({ apiKey });   // narrows to YOUR enabled features`);
+      console.log(`       import type { VxilSchema } from './vxil.types.js';`);
+      console.log(`       const vx = Vxil.connect<VxilSchema>({ apiKey: process.env.VXIL_API_KEY! });   // narrows to YOUR enabled features`);
       console.log(`       await vx.from('${firstCollection}').create({ /* field-typed */ });`);
       console.log(`
   key stored in ~/.vxil/credentials.json \xB7 project bound in .vxil/project.json`);
+      console.log("  next: `vxil env pull` writes VXIL_API_KEY (+ VXIL_BASE_URL, VXIL_TENANT_ID) to .env.local for the snippet above");
       break;
     }
     case "try": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vxil/cli",
-  "version": "0.20.2",
+  "version": "0.21.0",
   "private": false,
   "description": "The vxil CLI — init, quickstart, push, gen, secrets, keys, migrate, doctor, diff, functions, payments; installs the `vxil` command (npm i -g @vxil/cli).",
   "license": "MIT",
@@ -45,8 +45,8 @@
     }
   },
   "devDependencies": {
-    "@vxil/config": "0.13.0",
-    "@vxil/feature-configs": "0.11.0",
+    "@vxil/config": "0.14.0",
+    "@vxil/feature-configs": "0.12.0",
     "@vxil/runtime": "0.0.1",
     "@vxil/types": "0.0.1",
     "miniflare": "^4.20260730.0"