@squadbase/vantage 0.0.1 → 0.1.0

package/dist/cli.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
-import { PAGE_EXTENSIONS, scanProject, vantagePlugin, generateArtifacts, VANTAGE_DIR, MANIFEST_SCHEMA_VERSION, FORBIDDEN_FILES, API_METHODS, PUBLIC_ENV_PREFIX } from './chunk-ZGDU5YLH.js';
-import './chunk-73J5ZD4C.js';
+import { PAGE_EXTENSIONS, scanProject, vantagePlugin, generateArtifacts, VANTAGE_DIR, MANIFEST_SCHEMA_VERSION, FORBIDDEN_FILES, API_METHODS, PUBLIC_ENV_PREFIX } from './chunk-PRFBSQA4.js';
+import './chunk-YLAB6UQS.js';
 import './chunk-B7LLBNLV.js';
 import path2 from 'path';
-import pc2 from 'picocolors';
+import pc3 from 'picocolors';
 import fs2 from 'fs';
 import { createRequire } from 'module';
 import { loadEnv, createServer, build as build$1 } from 'vite';
 import { build as build$2 } from 'esbuild';
+import { fileURLToPath } from 'url';
 import { spawn } from 'child_process';
 
 // @squadbase/vantage — generated build. Do not edit.
-var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "help", "force", "verbose", "version", "h", "v"]);
+var BOOLEAN_FLAGS = /* @__PURE__ */ new Set(["json", "help", "force", "verbose", "version", "all", "list", "regex", "h", "v"]);
 function parseArgs(argv) {
   const positionals = [];
   const flags = {};
@@ -43,6 +44,12 @@ function parseArgs(argv) {
   }
   return { positionals, flags };
 }
+function applyApiBaseUrlFlag(args) {
+  const value = args.flags["api-base-url"];
+  if (typeof value === "string" && value.length) {
+    process.env.PUBLIC_API_BASE_URL = value;
+  }
+}
 function parsePort(value, fallback) {
   if (typeof value === "string") {
     const n = Number(value);
@@ -68,18 +75,18 @@ function resolveQuickRoot(target) {
 }
 var log = {
   info: (msg) => console.log(msg),
-  step: (msg) => console.log(pc2.cyan("\u2192 ") + msg),
-  ok: (msg) => console.log(pc2.green("\u2713 ") + msg),
-  warn: (msg) => console.log(pc2.yellow("! ") + msg),
-  error: (msg) => console.error(pc2.red("\u2717 ") + msg),
-  brand: (msg) => console.log(pc2.bold(pc2.magenta("vantage ")) + msg)
+  step: (msg) => console.log(pc3.cyan("\u2192 ") + msg),
+  ok: (msg) => console.log(pc3.green("\u2713 ") + msg),
+  warn: (msg) => console.log(pc3.yellow("! ") + msg),
+  error: (msg) => console.error(pc3.red("\u2717 ") + msg),
+  brand: (msg) => console.log(pc3.bold(pc3.magenta("vantage ")) + msg)
 };
 function printDiagnostics(diags) {
   for (const d of diags) {
-    const badge = d.severity === "error" ? pc2.red(pc2.bold(" ERROR ")) : pc2.yellow(pc2.bold(" WARN "));
-    console.log(`${badge} ${pc2.dim(d.code)} ${d.message}`);
-    if (d.files?.length) console.log(`        ${pc2.dim("files:")} ${d.files.join(", ")}`);
-    if (d.fix) console.log(`        ${pc2.dim("fix:")} ${d.fix}`);
+    const badge = d.severity === "error" ? pc3.red(pc3.bold(" ERROR ")) : pc3.yellow(pc3.bold(" WARN "));
+    console.log(`${badge} ${pc3.dim(d.code)} ${d.message}`);
+    if (d.files?.length) console.log(`        ${pc3.dim("files:")} ${d.files.join(", ")}`);
+    if (d.fix) console.log(`        ${pc3.dim("fix:")} ${d.fix}`);
   }
 }
 function printJson(payload) {
@@ -128,15 +135,96 @@ export async function GET({ request, params }: ApiContext) {
 }
 `;
 }
-function resolveRegistryDir(root) {
+function resolvePackageDir(root, sub) {
   try {
     const require2 = createRequire(path2.join(root, "noop.js"));
     const pkgJson = require2.resolve(`${PKG}/package.json`);
-    return path2.join(path2.dirname(pkgJson), "registry");
+    return path2.join(path2.dirname(pkgJson), sub);
   } catch {
     return null;
   }
 }
+function resolveRegistryDir(root) {
+  return resolvePackageDir(root, "registry");
+}
+function listBundledSkills(skillsDir) {
+  try {
+    return fs2.readdirSync(skillsDir, { withFileTypes: true }).filter((e) => e.isDirectory() && fs2.existsSync(path2.join(skillsDir, e.name, "SKILL.md"))).map((e) => e.name).sort();
+  } catch {
+    return [];
+  }
+}
+function copySkill(root, skillsDir, name, force) {
+  const src = path2.join(skillsDir, name);
+  if (!fs2.existsSync(path2.join(src, "SKILL.md"))) {
+    const available = listBundledSkills(skillsDir);
+    log.error(`Unknown skill "${name}". Available: ${available.join(", ") || "(none)"}`);
+    return 1;
+  }
+  const dest = path2.join(root, ".claude", "skills", name);
+  if (fs2.existsSync(dest) && !force) {
+    log.error(`${path2.relative(root, dest)} already exists. Use --force to overwrite.`);
+    return 1;
+  }
+  fs2.mkdirSync(path2.dirname(dest), { recursive: true });
+  fs2.cpSync(src, dest, { recursive: true, force: true });
+  log.ok(`Added skill ${path2.relative(root, dest)}/`);
+  return 0;
+}
+function addSkill(root, name, all, force) {
+  const skillsDir = resolvePackageDir(root, "skills");
+  if (!skillsDir) {
+    log.error("Could not resolve the Vantage skills directory.");
+    return 1;
+  }
+  const available = listBundledSkills(skillsDir);
+  if (available.length === 0) {
+    log.error("No skills are bundled with this version of Vantage.");
+    return 1;
+  }
+  const targets = all ? available : name ? [name] : [];
+  if (targets.length === 0) {
+    log.error(`Usage: vantage add skill <name>|--all. Available: ${available.join(", ")}`);
+    return 1;
+  }
+  let failed = 0;
+  for (const target of targets) {
+    if (copySkill(root, skillsDir, target, force) !== 0) failed++;
+  }
+  return failed === 0 ? 0 : 1;
+}
+var AGENTS_FILE = "AGENTS.md";
+function bundledAgentsPath(root) {
+  const dir = resolvePackageDir(root, "templates");
+  if (!dir) return null;
+  const src = path2.join(dir, AGENTS_FILE);
+  return fs2.existsSync(src) ? src : null;
+}
+function addAgents(root, force) {
+  const src = bundledAgentsPath(root);
+  if (!src) {
+    log.error("AGENTS.md is not bundled with this version of Vantage.");
+    return 1;
+  }
+  const dest = path2.join(root, AGENTS_FILE);
+  if (fs2.existsSync(dest) && !force) {
+    log.error(`${AGENTS_FILE} already exists. Use --force to overwrite.`);
+    return 1;
+  }
+  fs2.copyFileSync(src, dest);
+  log.ok(`Added ${path2.relative(root, dest) || AGENTS_FILE}`);
+  return 0;
+}
+function syncAgentsFile(root) {
+  const dest = path2.join(root, AGENTS_FILE);
+  if (!fs2.existsSync(dest)) return "absent";
+  const src = bundledAgentsPath(root);
+  if (!src) return "unchanged";
+  const next = fs2.readFileSync(src, "utf8");
+  if (fs2.readFileSync(dest, "utf8") === next) return "unchanged";
+  fs2.writeFileSync(dest, next);
+  return "updated";
+}
 function copyFromRegistry(root, kind, name, force) {
   const registry = resolveRegistryDir(root);
   if (!registry) {
@@ -165,8 +253,11 @@ async function add(root, args) {
   const kind = args.positionals[1];
   const name = args.positionals[2];
   const force = Boolean(args.flags.force);
+  const all = Boolean(args.flags.all);
+  if (kind === "skill") return addSkill(root, name, all, force);
+  if (kind === "agents") return addAgents(root, force);
   if (!kind || !name) {
-    log.error("Usage: vantage add <page|api|ui|block> <name>");
+    log.error("Usage: vantage add <page|api|ui|block|skill|agents> <name>");
     return 1;
   }
   if (kind === "page") {
@@ -194,7 +285,7 @@ async function add(root, args) {
   }
   if (kind === "ui") return copyFromRegistry(root, "ui", name, force);
   if (kind === "block") return copyFromRegistry(root, "block", name, force);
-  log.error(`Unknown add target "${kind}". Use one of: page, api, ui, block.`);
+  log.error(`Unknown add target "${kind}". Use one of: page, api, ui, block, skill, agents.`);
   return 1;
 }
 var ALLOWED_ENV_KEYS = /* @__PURE__ */ new Set(["MODE", "DEV", "PROD", "SSR", "BASE_URL", "PUBLIC_"]);
@@ -419,6 +510,7 @@ async function build(root, args) {
     return 1;
   }
   const mode = "production";
+  applyApiBaseUrlFlag(args);
   const env = { ...process.env, ...loadEnv(mode, root, "") };
   const quiet = Boolean(args.flags.json);
   if (!quiet) log.step("Building client\u2026");
@@ -522,6 +614,7 @@ async function dev(root, args) {
     return 1;
   }
   const mode = "development";
+  applyApiBaseUrlFlag(args);
   const env = { ...process.env, ...loadEnv(mode, root, "") };
   const port = parsePort(args.flags.port, 5173);
   const server = await createServer({
@@ -545,6 +638,158 @@ async function dev(root, args) {
   return new Promise(() => {
   });
 }
+var SUPPORTED_SCHEMA_VERSION = 1;
+var DOC_LANGS = ["ja", "en"];
+var DEFAULT_DOC_LANG = "ja";
+function isDocLang(value) {
+  return typeof value === "string" && DOC_LANGS.includes(value);
+}
+function docsDir() {
+  return fileURLToPath(new URL("../docs/", import.meta.url));
+}
+function loadCatalog() {
+  try {
+    const raw = fs2.readFileSync(path2.join(docsDir(), "index.json"), "utf8");
+    const parsed = JSON.parse(raw);
+    if (parsed.schemaVersion !== SUPPORTED_SCHEMA_VERSION) return null;
+    return Array.isArray(parsed.docs) ? parsed.docs : null;
+  } catch {
+    return null;
+  }
+}
+function docsForLang(catalog, lang) {
+  return catalog.filter((doc) => doc.lang === lang);
+}
+function readDoc(entry) {
+  return fs2.readFileSync(path2.join(docsDir(), entry.file), "utf8");
+}
+function resolveDoc(entries, query) {
+  const needle = query.toLowerCase().replace(/^\/+|\/+$/g, "").replace(/\.mdx?$/, "");
+  const exact = entries.filter((doc) => doc.slug.toLowerCase() === needle);
+  if (exact.length === 1) return { kind: "found", doc: exact[0] };
+  const byLeaf = entries.filter((doc) => (doc.slug.split("/").pop() ?? "").toLowerCase() === needle);
+  if (byLeaf.length === 1) return { kind: "found", doc: byLeaf[0] };
+  if (byLeaf.length > 1) return { kind: "ambiguous", matches: byLeaf };
+  const partial = entries.filter(
+    (doc) => doc.slug.toLowerCase().includes(needle) || doc.title.toLowerCase().includes(needle)
+  );
+  return { kind: "missing", suggestions: partial };
+}
+function groupBySection(entries) {
+  const groups = [];
+  for (const doc of entries) {
+    const last = groups[groups.length - 1];
+    if (last && last.section === doc.section) last.docs.push(doc);
+    else groups.push({ section: doc.section, title: doc.sectionTitle, docs: [doc] });
+  }
+  return groups;
+}
+
+// src/cli/docs.ts
+function paint(markdown) {
+  if (!process.stdout.isTTY) return markdown;
+  let inFence = false;
+  return markdown.split("\n").map((line) => {
+    if (/^\s*(```|~~~)/.test(line)) {
+      inFence = !inFence;
+      return pc3.dim(line);
+    }
+    if (inFence) return line;
+    if (/^#{1,6}\s/.test(line)) return pc3.bold(pc3.magenta(line));
+    if (/^>\s?/.test(line)) return pc3.dim(line);
+    return line;
+  }).join("\n");
+}
+function printList(entries) {
+  const width = Math.max(...entries.map((doc) => doc.slug.length), 0);
+  for (const group of groupBySection(entries)) {
+    console.log("");
+    console.log(pc3.bold(group.title));
+    for (const doc of group.docs) {
+      const slug = doc.slug.padEnd(width);
+      console.log(`  ${pc3.cyan(slug)}  ${doc.description || doc.title}`);
+    }
+  }
+  console.log("");
+  console.log(pc3.dim("vantage docs <name>   show one page      --json   machine-readable"));
+  console.log(pc3.dim("vantage docs --all    show every page    --lang   ja | en"));
+}
+function toJson(doc, content) {
+  return {
+    slug: doc.slug,
+    lang: doc.lang,
+    title: doc.title,
+    description: doc.description,
+    section: doc.section,
+    sectionTitle: doc.sectionTitle,
+    content
+  };
+}
+async function docs(_root, args) {
+  const catalog = loadCatalog();
+  if (!catalog) {
+    log.error("The bundled documentation is missing. Reinstall @squadbase/vantage, or run `pnpm build` in the framework repo.");
+    return 1;
+  }
+  const langFlag = args.flags.lang;
+  if (langFlag !== void 0 && !isDocLang(langFlag)) {
+    log.error(`Unknown --lang "${String(langFlag)}". Available: ${DOC_LANGS.join(", ")}`);
+    return 1;
+  }
+  const lang = isDocLang(langFlag) ? langFlag : DEFAULT_DOC_LANG;
+  const entries = docsForLang(catalog, lang);
+  if (entries.length === 0) {
+    log.error(`No documentation bundled for "${lang}".`);
+    return 1;
+  }
+  const json = Boolean(args.flags.json);
+  const name = args.positionals[1];
+  if (args.flags.all) {
+    const pages = entries.map((doc) => ({ doc, content: readDoc(doc) }));
+    if (json) {
+      printJson({ lang, docs: pages.map(({ doc, content: content2 }) => toJson(doc, content2)) });
+      return 0;
+    }
+    process.stdout.write(pages.map(({ content: content2 }) => content2.trimEnd()).join("\n\n---\n\n") + "\n");
+    return 0;
+  }
+  if (!name || args.flags.list) {
+    if (json) {
+      printJson({
+        lang,
+        docs: entries.map(({ slug, title, description, section, sectionTitle }) => ({
+          slug,
+          title,
+          description,
+          section,
+          sectionTitle
+        }))
+      });
+      return 0;
+    }
+    printList(entries);
+    return 0;
+  }
+  const found = resolveDoc(entries, name);
+  if (found.kind === "ambiguous") {
+    log.error(`"${name}" matches several pages: ${found.matches.map((d) => d.slug).join(", ")}`);
+    return 1;
+  }
+  if (found.kind === "missing") {
+    const suggestions = found.suggestions.map((d) => d.slug);
+    log.error(
+      suggestions.length ? `No page named "${name}". Did you mean: ${suggestions.slice(0, 8).join(", ")}?` : `No page named "${name}". Run \`vantage docs\` to list every page.`
+    );
+    return 1;
+  }
+  const content = readDoc(found.doc);
+  if (json) {
+    printJson(toJson(found.doc, content));
+    return 0;
+  }
+  process.stdout.write(paint(content.trimEnd()) + "\n");
+  return 0;
+}
 async function doctor(root, args) {
   const facets = [];
   const nodeMajor = Number(process.versions.node.split(".")[0]);
@@ -639,67 +884,390 @@ async function routes(root, args) {
     });
     return 0;
   }
-  console.log(pc2.bold("\nPages"));
-  if (model.pages.length === 0) console.log(pc2.dim("  (none)"));
+  console.log(pc3.bold("\nPages"));
+  if (model.pages.length === 0) console.log(pc3.dim("  (none)"));
   for (const p of model.pages) {
-    console.log(`  ${pc2.green(p.routePath.padEnd(28))} ${pc2.dim(p.file)}`);
+    console.log(`  ${pc3.green(p.routePath.padEnd(28))} ${pc3.dim(p.file)}`);
   }
   if (model.layouts.length || model.notFound || model.error) {
-    console.log(pc2.bold("\nSpecial"));
+    console.log(pc3.bold("\nSpecial"));
     for (const l of model.layouts) {
-      console.log(`  ${pc2.cyan(("layout " + (l.dir === "" ? "/" : "/" + l.dir)).padEnd(28))} ${pc2.dim(l.file)}`);
+      console.log(`  ${pc3.cyan(("layout " + (l.dir === "" ? "/" : "/" + l.dir)).padEnd(28))} ${pc3.dim(l.file)}`);
     }
-    if (model.notFound) console.log(`  ${pc2.cyan("404".padEnd(28))} ${pc2.dim(model.notFound)}`);
-    if (model.error) console.log(`  ${pc2.cyan("error".padEnd(28))} ${pc2.dim(model.error)}`);
+    if (model.notFound) console.log(`  ${pc3.cyan("404".padEnd(28))} ${pc3.dim(model.notFound)}`);
+    if (model.error) console.log(`  ${pc3.cyan("error".padEnd(28))} ${pc3.dim(model.error)}`);
   }
   if (model.hasServer) {
-    console.log(pc2.bold("\nAPI"));
-    if (model.apis.length === 0) console.log(pc2.dim("  (none)"));
+    console.log(pc3.bold("\nAPI"));
+    if (model.apis.length === 0) console.log(pc3.dim("  (none)"));
     for (const a of model.apis) {
-      console.log(`  ${pc2.yellow(a.routePath.padEnd(28))} ${pc2.dim(a.file)}`);
+      console.log(`  ${pc3.yellow(a.routePath.padEnd(28))} ${pc3.dim(a.file)}`);
+    }
+  }
+  console.log("");
+  return 0;
+}
+
+// src/cli/search-index.ts
+var FIELD_WEIGHTS = { slug: 3, title: 3, description: 2, body: 1 };
+var K1 = 1.2;
+var B = 0.75;
+var TOKEN_RE = /[a-z0-9]+|[぀-ヿ㐀-䶿一-鿿]+/g;
+var LATIN_RE = /^[a-z0-9]+$/;
+var TOKEN_RE_ANYCASE = /[a-zA-Z0-9]+|[぀-ヿ㐀-䶿一-鿿]+/g;
+var CJK_RE = /[぀-ヿ㐀-䶿一-鿿]/;
+var SCRIPT_RE = /[ぁ-ゟ]+|[゠-ヿ]+|[㐀-䶿一-鿿]+/g;
+var HIRAGANA_RE = /^[ぁ-ゟ]$/;
+function singular(word) {
+  if (word.length >= 5 && word.endsWith("ies")) return `${word.slice(0, -3)}y`;
+  if (word.length >= 4 && word.endsWith("s") && !/(ss|us|is)$/.test(word)) return word.slice(0, -1);
+  return word;
+}
+function tokenize(text) {
+  const normalized = text.normalize("NFKC").replace(/([a-z0-9])([A-Z])/g, "$1 $2").toLowerCase();
+  const tokens = [];
+  for (const match of normalized.matchAll(TOKEN_RE)) {
+    const run = match[0];
+    if (LATIN_RE.test(run)) {
+      tokens.push(singular(run));
+      continue;
+    }
+    for (const segment of run.match(SCRIPT_RE) ?? []) {
+      if (segment.length === 1 && HIRAGANA_RE.test(segment)) continue;
+      if (segment.length <= 2) {
+        tokens.push(segment);
+        continue;
+      }
+      tokens.push(segment);
+      for (let i = 0; i < segment.length - 1; i++) tokens.push(segment.slice(i, i + 2));
+    }
+  }
+  return tokens;
+}
+function queryPhrases(query) {
+  const phrases = [];
+  for (const match of query.normalize("NFKC").matchAll(TOKEN_RE_ANYCASE)) {
+    const run = match[0];
+    if (!CJK_RE.test(run)) {
+      phrases.push(run);
+      continue;
+    }
+    for (const segment of run.match(SCRIPT_RE) ?? []) {
+      if (segment.length === 1 && HIRAGANA_RE.test(segment)) continue;
+      phrases.push(segment);
+    }
+  }
+  return [...new Set(phrases)];
+}
+function buildIndex(entries) {
+  const docs2 = entries.map((entry) => {
+    const body = readDoc(entry);
+    const tf = /* @__PURE__ */ new Map();
+    let length = 0;
+    const add2 = (text, weight) => {
+      for (const token of tokenize(text)) {
+        tf.set(token, (tf.get(token) ?? 0) + weight);
+        length += weight;
+      }
+    };
+    add2(entry.slug, FIELD_WEIGHTS.slug);
+    add2(entry.title, FIELD_WEIGHTS.title);
+    add2(entry.description, FIELD_WEIGHTS.description);
+    add2(body, FIELD_WEIGHTS.body);
+    return { entry, body, tf, length };
+  });
+  const df = /* @__PURE__ */ new Map();
+  for (const doc of docs2) {
+    for (const term of doc.tf.keys()) df.set(term, (df.get(term) ?? 0) + 1);
+  }
+  const total = docs2.length;
+  const avgLength = total ? docs2.reduce((sum, doc) => sum + doc.length, 0) / total : 1;
+  return {
+    search(query) {
+      const terms = [...new Set(tokenize(query))];
+      if (terms.length === 0) return [];
+      const hits = [];
+      for (const doc of docs2) {
+        let score = 0;
+        for (const term of terms) {
+          const tf = doc.tf.get(term);
+          if (!tf) continue;
+          const n = df.get(term) ?? 0;
+          const idf = Math.log(1 + (total - n + 0.5) / (n + 0.5));
+          const norm = 1 - B + B * doc.length / avgLength;
+          score += idf * (tf * (K1 + 1) / (tf + K1 * norm));
+        }
+        if (score > 0) hits.push({ entry: doc.entry, score, terms, body: doc.body });
+      }
+      hits.sort((a, b) => b.score - a.score || a.entry.slug.localeCompare(b.entry.slug));
+      return hits;
+    }
+  };
+}
+var SNIPPET_LENGTH = 150;
+function snippet(body, terms, length = SNIPPET_LENGTH) {
+  let best = "";
+  let bestHits = 0;
+  let bestIndex = 0;
+  let bestIsHeading = true;
+  for (const raw of body.split("\n").slice(1)) {
+    const line = raw.replace(/^\s*[-*]\s+/, "").replace(/\s+/g, " ").trim();
+    if (!line || /^(```|~~~|\|\s*-{2,})/.test(line)) continue;
+    const haystack = line.toLowerCase();
+    const heading = line.startsWith("#");
+    let hits = 0;
+    let first = -1;
+    for (const term of terms) {
+      const at = haystack.indexOf(term);
+      if (at === -1) continue;
+      hits++;
+      if (first === -1 || at < first) first = at;
     }
+    if (hits > bestHits || hits === bestHits && hits > 0 && bestIsHeading && !heading) {
+      best = line;
+      bestHits = hits;
+      bestIndex = first;
+      bestIsHeading = heading;
+    }
+  }
+  if (!bestHits) return "";
+  if (best.length <= length) return best;
+  const start = Math.max(0, bestIndex - Math.floor(length / 4));
+  const text = best.slice(start, start + length).trim();
+  return `${start > 0 ? "\u2026" : ""}${text}${start + length < best.length ? "\u2026" : ""}`;
+}
+
+// src/cli/search.ts
+var DEFAULT_LIMIT = 10;
+var MAX_REGEX_LINES = 3;
+function parseLimit(value, fallback) {
+  if (typeof value === "string") {
+    const n = Number(value);
+    if (Number.isInteger(n) && n > 0) return n;
+  }
+  return fallback;
+}
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function paintMatches(text, re) {
+  if (!process.stdout.isTTY) return text;
+  let out = "";
+  let last = 0;
+  for (const match of text.matchAll(re)) {
+    const at = match.index ?? 0;
+    if (!match[0]) continue;
+    out += pc3.dim(text.slice(last, at)) + pc3.yellow(match[0]);
+    last = at + match[0].length;
   }
+  return out + pc3.dim(text.slice(last));
+}
+function paintTerms(text, words) {
+  if (!process.stdout.isTTY) return text;
+  if (words.length === 0) return pc3.dim(text);
+  return paintMatches(text, new RegExp(words.map(escapeRegExp).join("|"), "gi"));
+}
+function header(count, query, lang, mode) {
+  const label = `${count} result${count === 1 ? "" : "s"} for "${query}"`;
+  console.log("");
+  console.log(pc3.bold(label) + pc3.dim(`  ${lang} \xB7 ${mode}`));
   console.log("");
+}
+function footer(total, shown, lines) {
+  if (total > shown) {
+    console.log("");
+    console.log(pc3.dim(`  ${total - shown} more \u2014 raise --limit to see them`));
+  }
+  console.log("");
+  for (const line of lines) console.log(pc3.dim(line));
+}
+function noResults(query) {
+  log.warn(`Nothing matches "${query}".`);
+  console.log(pc3.dim("  Try fewer or more general words, or run `vantage docs --list` to browse every page."));
+}
+function meta(entry) {
+  return {
+    slug: entry.slug,
+    title: entry.title,
+    description: entry.description,
+    section: entry.section,
+    sectionTitle: entry.sectionTitle,
+    command: `vantage docs ${entry.slug}`
+  };
+}
+function runRanked(entries, query, lang, limit, json) {
+  const hits = buildIndex(entries).search(query);
+  const shown = hits.slice(0, limit);
+  const passage = (hit) => snippet(hit.body, hit.terms);
+  if (json) {
+    printJson({
+      query,
+      mode: "bm25",
+      lang,
+      count: hits.length,
+      results: shown.map((hit) => ({
+        ...meta(hit.entry),
+        score: Math.round(hit.score * 1e3) / 1e3,
+        snippet: passage(hit)
+      }))
+    });
+    return 0;
+  }
+  if (hits.length === 0) {
+    noResults(query);
+    return 0;
+  }
+  const words = queryPhrases(query);
+  const width = Math.max(...shown.map((hit) => hit.entry.slug.length));
+  header(hits.length, query, lang, "bm25");
+  for (const hit of shown) {
+    const title = `${hit.entry.title}${pc3.dim(` \xB7 ${hit.entry.sectionTitle}`)}`;
+    console.log(`  ${pc3.cyan(hit.entry.slug.padEnd(width))}  ${title}`);
+    const text = passage(hit);
+    if (text) console.log(`  ${" ".repeat(width)}  ${paintTerms(text, words)}`);
+  }
+  footer(hits.length, shown.length, [
+    "vantage docs <name>      open one result       --regex   treat the query as a regular expression",
+    "vantage search --json    machine-readable      --limit   max results (default 10)"
+  ]);
   return 0;
 }
+function runRegex(entries, query, lang, limit, json) {
+  let scan;
+  let probe;
+  try {
+    scan = new RegExp(query, "gi");
+    probe = new RegExp(query, "i");
+  } catch (err) {
+    log.error(err instanceof Error ? err.message : `Invalid regular expression: ${String(err)}`);
+    return 1;
+  }
+  const results = [];
+  for (const entry of entries) {
+    const lines = readDoc(entry).split("\n");
+    const matches = [];
+    let matchCount = 0;
+    for (let i = 0; i < lines.length; i++) {
+      const found = [...lines[i].matchAll(scan)];
+      if (found.length === 0) continue;
+      matchCount += found.length;
+      if (matches.length < MAX_REGEX_LINES) {
+        matches.push({ line: i + 1, text: lines[i].replace(/\s+/g, " ").trim() });
+      }
+    }
+    const inMeta = probe.test(entry.slug) || probe.test(entry.title) || probe.test(entry.description);
+    if (matchCount === 0 && !inMeta) continue;
+    results.push({ entry, matchCount, matches });
+  }
+  results.sort((a, b) => b.matchCount - a.matchCount);
+  const shown = results.slice(0, limit);
+  if (json) {
+    printJson({
+      query,
+      mode: "regex",
+      lang,
+      count: results.length,
+      results: shown.map((result) => ({
+        ...meta(result.entry),
+        matchCount: result.matchCount,
+        matches: result.matches
+      }))
+    });
+    return 0;
+  }
+  if (results.length === 0) {
+    noResults(query);
+    return 0;
+  }
+  header(results.length, query, lang, "regex");
+  for (const result of shown) {
+    const count = pc3.dim(
+      result.matchCount ? `  ${result.matchCount} match${result.matchCount === 1 ? "" : "es"}` : "  name match"
+    );
+    console.log(`  ${pc3.cyan(result.entry.slug)}  ${result.entry.title}${count}`);
+    for (const match of result.matches) {
+      console.log(`    ${pc3.dim(String(match.line).padStart(4))}  ${paintMatches(match.text, scan)}`);
+    }
+  }
+  footer(results.length, shown.length, [
+    "vantage docs <name>      open one result       --limit   max results (default 10)",
+    "vantage search --json    machine-readable      --lang    ja | en"
+  ]);
+  return 0;
+}
+async function search(_root, args) {
+  const query = args.positionals.slice(1).join(" ").trim();
+  if (!query) {
+    log.error("Usage: vantage search <query> [--regex] [--limit <n>] [--lang ja|en] [--json]");
+    return 1;
+  }
+  const catalog = loadCatalog();
+  if (!catalog) {
+    log.error("The bundled documentation is missing. Reinstall @squadbase/vantage, or run `pnpm build` in the framework repo.");
+    return 1;
+  }
+  const langFlag = args.flags.lang;
+  if (langFlag !== void 0 && !isDocLang(langFlag)) {
+    log.error(`Unknown --lang "${String(langFlag)}". Available: ${DOC_LANGS.join(", ")}`);
+    return 1;
+  }
+  const lang = isDocLang(langFlag) ? langFlag : DEFAULT_DOC_LANG;
+  const entries = docsForLang(catalog, lang);
+  if (entries.length === 0) {
+    log.error(`No documentation bundled for "${lang}".`);
+    return 1;
+  }
+  const limit = parseLimit(args.flags.limit, DEFAULT_LIMIT);
+  const json = Boolean(args.flags.json);
+  return args.flags.regex ? runRegex(entries, query, lang, limit, json) : runRanked(entries, query, lang, limit, json);
+}
 
 // src/cli/upgrade.ts
 async function upgrade(root, args) {
   const version = frameworkVersion();
   const model = scanProject(root);
   generateArtifacts({ root, model });
+  const agents = syncAgentsFile(root);
   if (args.flags.json) {
-    printJson({ ok: true, version, transforms: [], regenerated: true });
+    printJson({ ok: true, version, transforms: [], regenerated: true, agentsSynced: agents === "updated" });
     return 0;
   }
   log.brand(`upgrade \u2192 v${version}`);
   log.ok("Regenerated .vantage artifacts.");
+  if (agents === "updated") log.ok("Synced AGENTS.md from the framework.");
   log.info("No breaking code transforms required for this version.");
   return 0;
 }
 
 // src/cli.ts
-var HELP = `${pc2.bold(pc2.magenta("vantage"))} \u2014 data dashboard framework for Squadbase
+var HELP = `${pc3.bold(pc3.magenta("vantage"))} \u2014 data dashboard framework for Squadbase
 
-${pc2.bold("Usage")}
+${pc3.bold("Usage")}
   vantage <command> [path] [options]
   vantage <path>                     Quick dev shortcut (folder or entry file)
 
-${pc2.bold("Commands")}
+${pc3.bold("Commands")}
   dev                 Start the dev server (HMR + optional API)
   build               Build client and optional server into dist/
   preview             Run the production build locally
   check               Static verification (routes, boundaries, forbidden files)
   routes              Show page and API URL map
-  add <kind> <name>   Scaffold a page | api | ui | block
+  add <kind> <name>   Scaffold a page | api | ui | block | skill | agents
+  docs [name]         Show the bundled guide and component reference
+  search <query>      Find components and docs by meaning, or by regex
   doctor              Environment and installation health checks
-  upgrade             Regenerate artifacts / apply migrations
+  upgrade             Regenerate artifacts, sync AGENTS.md / apply migrations
 
-${pc2.bold("Options")}
-  --json              Machine-readable output (check, routes, doctor, build)
+${pc3.bold("Options")}
+  --json              Machine-readable output (check, routes, doctor, build, docs, search)
   --port <n>          Port for dev/preview
   --root <dir>        Project root (default: cwd)
   --force             Overwrite when scaffolding
+  --list              List pages without showing one (docs)
+  --lang <ja|en>      Documentation language (docs, search, default: ja)
+  --regex             Treat the query as a regular expression (search)
+  --limit <n>         Max results (search, default: 10)
+  --all               Add every bundled skill (add skill --all) | show every page (docs)
   -v, --version       Print version
   -h, --help          Print this help
 `;
@@ -710,9 +1278,12 @@ var COMMANDS = {
   check,
   routes,
   add,
+  docs,
+  search,
   doctor,
   upgrade
 };
+var NO_ROOT_POSITIONAL = /* @__PURE__ */ new Set(["add", "docs", "search"]);
 async function main() {
   const args = parseArgs(process.argv.slice(2));
   const command = args.positionals[0];
@@ -727,7 +1298,7 @@ async function main() {
   let runFn = COMMANDS[command];
   let root;
   if (runFn) {
-    const targetArg = command !== "add" ? args.positionals[1] : void 0;
+    const targetArg = !NO_ROOT_POSITIONAL.has(command) ? args.positionals[1] : void 0;
     if (targetArg !== void 0) {
       const quick = resolveQuickRoot(targetArg);
       if (!quick) {