@neopress/cli 4.0.0 → 4.2.0

package/dist/bin.cjs

@@ -3387,6 +3387,7 @@ function fail(message, code = 1) {
 // src/utils/config.ts
 var import_node_fs2 = require("fs");
 var import_node_path2 = require("path");
+var import_node_os2 = require("os");
 
 // src/utils/token-store.ts
 var import_node_fs = require("fs");
@@ -3421,31 +3422,55 @@ function clearSession() {
 // src/utils/config.ts
 var PROJECT_CONFIG = ".neopressrc.json";
 var WORKSPACE_CONFIG = ".neopress/config.json";
-function readProjectConfig() {
-  let config2 = {};
-  for (const file2 of [PROJECT_CONFIG, WORKSPACE_CONFIG]) {
-    try {
-      const parsed = JSON.parse((0, import_node_fs2.readFileSync)(file2, "utf-8"));
-      config2 = {
-        ...config2,
-        ...typeof parsed.siteId === "number" ? { siteId: parsed.siteId } : {},
-        ...typeof parsed.baseUrl === "string" ? { baseUrl: parsed.baseUrl } : {}
-      };
-    } catch {
+function readConfigFileAt(path) {
+  try {
+    const parsed = JSON.parse((0, import_node_fs2.readFileSync)(path, "utf-8"));
+    return {
+      ...typeof parsed.siteId === "number" ? { siteId: parsed.siteId } : {},
+      ...typeof parsed.baseUrl === "string" ? { baseUrl: parsed.baseUrl } : {}
+    };
+  } catch {
+    return {};
+  }
+}
+function locateProjectConfig(startDir = process.cwd()) {
+  const home = (0, import_node_path2.resolve)((0, import_node_os2.homedir)());
+  let dir = (0, import_node_path2.resolve)(startDir);
+  while (true) {
+    let merged = {};
+    let foundPath;
+    for (const rel of [PROJECT_CONFIG, WORKSPACE_CONFIG]) {
+      const p = (0, import_node_path2.join)(dir, rel);
+      const cfg = readConfigFileAt(p);
+      if (Object.keys(cfg).length > 0) {
+        merged = { ...merged, ...cfg };
+        if (!foundPath) foundPath = p;
+      }
     }
+    if (Object.keys(merged).length > 0) return { config: merged, path: foundPath };
+    const parent = (0, import_node_path2.dirname)(dir);
+    if (dir === home || parent === dir) break;
+    dir = parent;
   }
-  return config2;
+  return { config: {} };
+}
+function readProjectConfig() {
+  return locateProjectConfig().config;
 }
 function writeWorkspaceConfig(next) {
   (0, import_node_fs2.mkdirSync)((0, import_node_path2.dirname)(WORKSPACE_CONFIG), { recursive: true });
   (0, import_node_fs2.writeFileSync)(WORKSPACE_CONFIG, JSON.stringify(next, null, 2) + "\n", "utf-8");
 }
-function getSiteId() {
-  const envSiteId = process.env.NEOPRESS_SITE_ID;
-  if (envSiteId) return parseInt(envSiteId, 10);
-  const projectConfig = readProjectConfig();
-  if (projectConfig.siteId) return projectConfig.siteId;
-  return loadSession().activeSiteId;
+function writeProjectSiteId(siteId) {
+  let raw = {};
+  try {
+    const parsed = JSON.parse((0, import_node_fs2.readFileSync)(PROJECT_CONFIG, "utf-8"));
+    if (parsed && typeof parsed === "object") raw = parsed;
+  } catch {
+  }
+  const next = { ...raw, siteId };
+  (0, import_node_fs2.writeFileSync)(PROJECT_CONFIG, JSON.stringify(next, null, 2) + "\n", "utf-8");
+  return (0, import_node_path2.resolve)(PROJECT_CONFIG);
 }
 function getBaseUrl() {
   return process.env.NEOPRESS_BASE_URL || readProjectConfig().baseUrl || "https://app.neopress.ai";
@@ -3461,12 +3486,24 @@ var siteOverride;
 function setSiteOverride(value) {
   siteOverride = value;
 }
-function getSiteTarget() {
+function resolveSiteTarget() {
   if (siteOverride) {
     const n = parseInt(siteOverride, 10);
-    return String(n) === siteOverride ? n : siteOverride;
+    const value = String(n) === siteOverride ? n : siteOverride;
+    return { value, source: "flag", detail: "--site" };
   }
-  return getSiteId();
+  const envSiteId = process.env.NEOPRESS_SITE_ID;
+  if (envSiteId) return { value: parseInt(envSiteId, 10), source: "env", detail: "NEOPRESS_SITE_ID" };
+  const located = locateProjectConfig();
+  if (typeof located.config.siteId === "number") {
+    return { value: located.config.siteId, source: "project-config", detail: located.path };
+  }
+  const active = loadSession().activeSiteId;
+  if (active) return { value: active, source: "global-active", detail: "sites use" };
+  return { value: void 0, source: "none" };
+}
+function getSiteTarget() {
+  return resolveSiteTarget().value;
 }
 
 // src/utils/pkce.ts
@@ -3652,7 +3689,12 @@ function parseImplicitCallbackTokens(callbackUrl) {
   };
 }
 function registerAuthCommands(program3) {
-  program3.command("login").description("Authenticate with Neopress").option("--provider <provider>", "OAuth provider (google)", "google").option("--manual", "Paste the OAuth callback URL manually instead of running a local callback server").action(async (options) => {
+  program3.command("login").description("Authenticate with Neopress").addHelpText("after", `
+Examples:
+  $ neopress login
+  $ neopress login --manual
+  $ neopress login --provider google
+Default flow opens a browser and listens on a local callback port; use --manual on a headless host to paste the callback URL by hand. After login, run \`neopress sites use <siteId>\` to select a site.`).option("--provider <provider>", "OAuth provider (google)", "google").option("--manual", "Paste the OAuth callback URL manually instead of running a local callback server").action(async (options) => {
     console.log(options.manual ? "Starting manual browser login..." : "Opening browser for login...");
     const codeVerifier = generateCodeVerifier();
     const codeChallenge = generateCodeChallenge(codeVerifier);
@@ -3754,11 +3796,11 @@ function __rest(s, e) {
 }
 function __awaiter(thisArg, _arguments, P, generator) {
   function adopt(value) {
-    return value instanceof P ? value : new P(function(resolve) {
-      resolve(value);
+    return value instanceof P ? value : new P(function(resolve2) {
+      resolve2(value);
     });
   }
-  return new (P || (P = Promise))(function(resolve, reject) {
+  return new (P || (P = Promise))(function(resolve2, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -3774,7 +3816,7 @@ function __awaiter(thisArg, _arguments, P, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve2(result.value) : adopt(result.value).then(fulfilled, rejected);
     }
     step((generator = generator.apply(thisArg, _arguments || [])).next());
   });
@@ -4145,18 +4187,18 @@ var PostgrestError = class extends Error {
   }
 };
 function sleep(ms, signal) {
-  return new Promise((resolve) => {
+  return new Promise((resolve2) => {
     if (signal === null || signal === void 0 ? void 0 : signal.aborted) {
-      resolve();
+      resolve2();
       return;
     }
     const id = setTimeout(() => {
       signal === null || signal === void 0 || signal.removeEventListener("abort", onAbort);
-      resolve();
+      resolve2();
     }, ms);
     function onAbort() {
       clearTimeout(id);
-      resolve();
+      resolve2();
     }
     signal === null || signal === void 0 || signal.addEventListener("abort", onAbort);
   });
@@ -12105,15 +12147,15 @@ var RealtimeChannel = class _RealtimeChannel {
         }
       }
     } else {
-      return new Promise((resolve) => {
+      return new Promise((resolve2) => {
         var _a3, _b2, _c;
         const push = this.channelAdapter.push(args.type, args, opts.timeout || this.timeout);
         if (args.type === "broadcast" && !((_c = (_b2 = (_a3 = this.params) === null || _a3 === void 0 ? void 0 : _a3.config) === null || _b2 === void 0 ? void 0 : _b2.broadcast) === null || _c === void 0 ? void 0 : _c.ack)) {
-          resolve("ok");
+          resolve2("ok");
         }
-        push.receive("ok", () => resolve("ok"));
-        push.receive("error", () => resolve("error"));
-        push.receive("timeout", () => resolve("timed out"));
+        push.receive("ok", () => resolve2("ok"));
+        push.receive("error", () => resolve2("error"));
+        push.receive("timeout", () => resolve2("timed out"));
       });
     }
   }
@@ -12138,8 +12180,8 @@ var RealtimeChannel = class _RealtimeChannel {
    * @category Realtime
    */
   async unsubscribe(timeout = this.timeout) {
-    return new Promise((resolve) => {
-      this.channelAdapter.unsubscribe(timeout).receive("ok", () => resolve("ok")).receive("timeout", () => resolve("timed out")).receive("error", () => resolve("error"));
+    return new Promise((resolve2) => {
+      this.channelAdapter.unsubscribe(timeout).receive("ok", () => resolve2("ok")).receive("timeout", () => resolve2("timed out")).receive("error", () => resolve2("error"));
     });
   }
   /**
@@ -12220,8 +12262,8 @@ var RealtimeChannel = class _RealtimeChannel {
   }
   /** @internal */
   _notThisChannelEvent(event, ref) {
-    const { close, error: error48, leave, join: join2 } = CHANNEL_EVENTS;
-    const events = [close, error48, leave, join2];
+    const { close, error: error48, leave, join: join3 } = CHANNEL_EVENTS;
+    const events = [close, error48, leave, join3];
     return ref && events.includes(event) && ref !== this.joinPush.ref;
   }
   /** @internal */
@@ -12334,11 +12376,11 @@ var SocketAdapter = class {
     this.socket.connect();
   }
   disconnect(callback, code, reason, timeout = 1e4) {
-    return new Promise((resolve) => {
-      setTimeout(() => resolve("timeout"), timeout);
+    return new Promise((resolve2) => {
+      setTimeout(() => resolve2("timeout"), timeout);
       this.socket.disconnect(() => {
         callback();
-        resolve("ok");
+        resolve2("ok");
       }, code, reason);
     });
   }
@@ -13752,7 +13794,7 @@ var _getRequestParams = (method, options, parameters, body) => {
   return _objectSpread22(_objectSpread22({}, params), parameters);
 };
 async function _handleRequest(fetcher, method, url2, options, parameters, body, namespace) {
-  return new Promise((resolve, reject) => {
+  return new Promise((resolve2, reject) => {
     fetcher(url2, _getRequestParams(method, options, parameters, body)).then((result) => {
       if (!result.ok) throw result;
       if (options === null || options === void 0 ? void 0 : options.noResolveJson) return result;
@@ -13762,7 +13804,7 @@ async function _handleRequest(fetcher, method, url2, options, parameters, body,
         if (!contentType || !contentType.includes("application/json")) return {};
       }
       return result.json();
-    }).then((data) => resolve(data)).catch((error48) => handleError(error48, reject, options, namespace));
+    }).then((data) => resolve2(data)).catch((error48) => handleError(error48, reject, options, namespace));
   });
 }
 function createFetchApi(namespace = "storage") {
@@ -24007,11 +24049,11 @@ var DEFAULT_TRACE_PROPAGATION_OPTIONS = {
 };
 function __awaiter2(thisArg, _arguments, P, generator) {
   function adopt(value) {
-    return value instanceof P ? value : new P(function(resolve) {
-      resolve(value);
+    return value instanceof P ? value : new P(function(resolve2) {
+      resolve2(value);
     });
   }
-  return new (P || (P = Promise))(function(resolve, reject) {
+  return new (P || (P = Promise))(function(resolve2, reject) {
     function fulfilled(value) {
       try {
         step(generator.next(value));
@@ -24027,7 +24069,7 @@ function __awaiter2(thisArg, _arguments, P, generator) {
       }
     }
     function step(result) {
-      result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected);
+      result.done ? resolve2(result.value) : adopt(result.value).then(fulfilled, rejected);
     }
     step((generator = generator.apply(thisArg, _arguments || [])).next());
   });
@@ -24882,6 +24924,27 @@ function serializeTemplate(t) {
     createdAt: t.created_at
   };
 }
+function serializeHeadshot(h) {
+  return {
+    id: h.id,
+    imageUrl: h.image_url,
+    width: h.width,
+    height: h.height,
+    aspectRatio: h.aspect_ratio,
+    mimeType: h.mime_type,
+    byteSize: h.byte_size,
+    ageBand: h.age_band,
+    gender: h.gender,
+    ethnicity: h.ethnicity,
+    attire: h.attire,
+    variationIndex: h.variation_index,
+    gptPrompt: h.gpt_prompt,
+    tags: h.tags ?? [],
+    isActive: h.is_active,
+    createdAt: h.created_at,
+    updatedAt: h.updated_at
+  };
+}
 function serializeSite(site) {
   return {
     id: site.id,
@@ -39228,8 +39291,8 @@ var SiteHistoryService = class _SiteHistoryService {
     const previousLock = _SiteHistoryService.sessionLocks.get(key) ?? Promise.resolve();
     let releaseCurrentLock = () => {
     };
-    const currentLock = new Promise((resolve) => {
-      releaseCurrentLock = resolve;
+    const currentLock = new Promise((resolve2) => {
+      releaseCurrentLock = resolve2;
     });
     const queuedLock = previousLock.catch(() => {
     }).then(() => currentLock);
@@ -40564,6 +40627,113 @@ var TemplatesEndpoint = class {
   }
 };
 
+// ../sdk/dist/endpoints/headshots.js
+var HeadshotsEndpoint = class {
+  client;
+  constructor(client) {
+    this.client = client;
+  }
+  async list(params) {
+    const { page, limit, offset } = this.client.resolvePagination(params);
+    let query = this.client.db.from("headshot_pool").select("*", { count: "exact" });
+    if (params?.ageBand)
+      query = query.eq("age_band", params.ageBand);
+    if (params?.gender)
+      query = query.eq("gender", params.gender);
+    if (params?.ethnicity)
+      query = query.eq("ethnicity", params.ethnicity);
+    if (params?.attire)
+      query = query.eq("attire", params.attire);
+    if (params?.isActive !== void 0)
+      query = query.eq("is_active", params.isActive);
+    const { data, error: error48, count } = await query.order("age_band", { ascending: true }).order("gender", { ascending: true }).order("ethnicity", { ascending: true }).order("variation_index", { ascending: true }).range(offset, offset + limit - 1);
+    if (error48)
+      throw new NeopressApiError("DB_ERROR", error48.message, 0, error48);
+    return {
+      data: (data ?? []).map((r) => serializeHeadshot(r)),
+      pagination: this.client.paginationMeta(page, limit, offset, count ?? 0)
+    };
+  }
+  async get(id) {
+    const { data, error: error48 } = await this.client.db.from("headshot_pool").select("*").eq("id", id).single();
+    if (error48)
+      throw new NeopressApiError("DB_ERROR", error48.message, 0, error48);
+    return serializeHeadshot(data);
+  }
+  async create(params) {
+    const values = {
+      image_url: params.imageUrl,
+      age_band: params.ageBand,
+      gender: params.gender,
+      ethnicity: params.ethnicity,
+      variation_index: params.variationIndex
+    };
+    if (params.attire !== void 0)
+      values.attire = params.attire;
+    if (params.width !== void 0)
+      values.width = params.width;
+    if (params.height !== void 0)
+      values.height = params.height;
+    if (params.aspectRatio !== void 0)
+      values.aspect_ratio = params.aspectRatio;
+    if (params.mimeType !== void 0)
+      values.mime_type = params.mimeType;
+    if (params.byteSize !== void 0)
+      values.byte_size = params.byteSize;
+    if (params.gptPrompt !== void 0)
+      values.gpt_prompt = params.gptPrompt;
+    if (params.tags !== void 0)
+      values.tags = params.tags;
+    if (params.isActive !== void 0)
+      values.is_active = params.isActive;
+    const { data, error: error48 } = await this.client.db.from("headshot_pool").insert(values).select().single();
+    if (error48)
+      throw new NeopressApiError("DB_ERROR", error48.message, 0, error48);
+    return serializeHeadshot(data);
+  }
+  async update(id, params) {
+    const values = {};
+    if (params.imageUrl !== void 0)
+      values.image_url = params.imageUrl;
+    if (params.ageBand !== void 0)
+      values.age_band = params.ageBand;
+    if (params.gender !== void 0)
+      values.gender = params.gender;
+    if (params.ethnicity !== void 0)
+      values.ethnicity = params.ethnicity;
+    if (params.attire !== void 0)
+      values.attire = params.attire;
+    if (params.variationIndex !== void 0)
+      values.variation_index = params.variationIndex;
+    if (params.width !== void 0)
+      values.width = params.width;
+    if (params.height !== void 0)
+      values.height = params.height;
+    if (params.aspectRatio !== void 0)
+      values.aspect_ratio = params.aspectRatio;
+    if (params.mimeType !== void 0)
+      values.mime_type = params.mimeType;
+    if (params.byteSize !== void 0)
+      values.byte_size = params.byteSize;
+    if (params.gptPrompt !== void 0)
+      values.gpt_prompt = params.gptPrompt;
+    if (params.tags !== void 0)
+      values.tags = params.tags;
+    if (params.isActive !== void 0)
+      values.is_active = params.isActive;
+    const { data, error: error48 } = await this.client.db.from("headshot_pool").update(values).eq("id", id).select().single();
+    if (error48)
+      throw new NeopressApiError("DB_ERROR", error48.message, 0, error48);
+    return serializeHeadshot(data);
+  }
+  async delete(id) {
+    const { error: error48 } = await this.client.db.from("headshot_pool").delete().eq("id", id);
+    if (error48)
+      throw new NeopressApiError("DB_ERROR", error48.message, 0, error48);
+    return { id, deleted: true };
+  }
+};
+
 // ../sdk/dist/client.js
 var NeopressClient = class {
   baseUrl;
@@ -40584,6 +40754,7 @@ var NeopressClient = class {
   entryReferences;
   analytics;
   templates;
+  headshots;
   constructor(options) {
     this.baseUrl = (options.baseUrl || "https://app.neopress.ai").replace(/\/$/, "");
     this.accessToken = options.accessToken || "";
@@ -40602,6 +40773,7 @@ var NeopressClient = class {
     this.entryReferences = new EntryReferencesEndpoint(this);
     this.analytics = new AnalyticsEndpoint(this);
     this.templates = new TemplatesEndpoint(this);
+    this.headshots = new HeadshotsEndpoint(this);
   }
   get siteBasePath() {
     return `/api/v1/sites/${this.siteId}`;
@@ -40731,39 +40903,42 @@ async function getClientAsync(siteIdOverride) {
   const sb = getSupabaseConfig();
   return new NeopressClient({ accessToken, siteId, baseUrl: getBaseUrl(), supabaseUrl: sb.url, supabaseAnonKey: sb.anonKey });
 }
+async function getGlobalClientAsync() {
+  const token = process.env.NEOPRESS_ACCESS_TOKEN || await getValidAccessToken();
+  if (!token) {
+    fail("Not authenticated. Run `neopress login` or set NEOPRESS_ACCESS_TOKEN.");
+  }
+  const sb = getSupabaseConfig();
+  return new NeopressClient({ accessToken: token, siteId: 0, baseUrl: getBaseUrl(), supabaseUrl: sb.url, supabaseAnonKey: sb.anonKey });
+}
 
 // src/commands/sites.ts
 function registerSiteCommands(program3) {
-  const sites = program3.command("sites").description("Manage sites");
+  const sites = program3.command("sites").description("Manage sites").addHelpText("after", `
+Examples:
+  $ neopress sites list
+  $ neopress sites create --name "My Site" --handle my-site --use
+  $ neopress sites create --name "My Site" --handle my-site --pin
+  $ neopress sites use my-site
+  $ neopress sites current
+Run \`sites use <id|handle>\` to set the global active site, or \`sites create --pin\` to scope a site to the current directory. \`sites current\` shows which site commands will target and why.`);
   sites.command("list").description("List accessible sites").action(async () => {
-    const token = process.env.NEOPRESS_ACCESS_TOKEN || await getValidAccessToken() || void 0;
-    if (!token) {
-      fail("Not authenticated. Run `neopress login`.");
-    }
-    const client = new NeopressClient({
-      accessToken: token,
-      siteId: 0,
-      baseUrl: getBaseUrl()
-    });
+    const client = await getGlobalClientAsync();
     const sitesList = await client.site.list();
     output(sitesList);
   });
-  sites.command("use <siteIdOrHandle>").description("Set active site (ID or handle)").action(async (siteIdOrHandle) => {
+  sites.command("use <siteIdOrHandle>").description("Set active site (ID or handle)").addHelpText("after", `
+Examples:
+  $ neopress sites use 12
+  $ neopress sites use my-site
+Accepts a numeric site ID or a handle (resolved via \`sites list\`). Sets the active site used by all other commands.`).action(async (siteIdOrHandle) => {
     const id = parseInt(siteIdOrHandle, 10);
     if (!isNaN(id)) {
       setActiveSiteId(id);
       ok(`Active site set to ${id}`);
       return;
     }
-    const token = process.env.NEOPRESS_ACCESS_TOKEN || await getValidAccessToken() || void 0;
-    if (!token) {
-      fail("Not authenticated. Run `neopress login`.");
-    }
-    const client = new NeopressClient({
-      accessToken: token,
-      siteId: 0,
-      baseUrl: getBaseUrl()
-    });
+    const client = await getGlobalClientAsync();
     const sitesList = await client.site.list();
     const match = sitesList.find((s) => s.handle === siteIdOrHandle);
     if (!match) {
@@ -40772,37 +40947,51 @@ function registerSiteCommands(program3) {
     setActiveSiteId(match.id);
     ok(`Active site set to ${match.id} (${match.handle})`);
   });
-  sites.command("create").description("Create a new site").option("--name <name>", "Site name").option("--handle <handle>", "Site handle").option("--prompt <prompt>", "Prompt to generate site name/handle").option("--language <locale>", "Default content locale", "en").option("--use", "Set the created site as active").action(async (options) => {
+  sites.command("create").description("Create a new site").addHelpText("after", `
+Examples:
+  $ neopress sites create --name "My Site" --handle my-site
+  $ neopress sites create --prompt "a portfolio for a freelance photographer" --use
+  $ neopress sites create --name Acme --handle acme --language en
+Pass --prompt to auto-generate name/handle, or supply both --name and --handle. --language sets the default content locale (default en).
+--use sets the new site as the GLOBAL active site (shared across all directories). --pin instead writes ./.neopressrc.json for THIS directory only, leaving the global active site untouched \u2014 prefer it for parallel/automated runs so concurrent builds don't stomp each other's active site.`).option("--name <name>", "Site name").option("--handle <handle>", "Site handle").option("--prompt <prompt>", "Prompt to generate site name/handle").option("--language <locale>", "Default content locale", "en").option("--use", "Set the created site as the global active site").option("--pin", "Pin the created site to this directory via ./.neopressrc.json (no global state)").action(async (options) => {
     if (!options.prompt && !(options.name && options.handle)) {
       fail("Provide --prompt or both --name and --handle.");
     }
-    const token = process.env.NEOPRESS_ACCESS_TOKEN || await getValidAccessToken() || void 0;
-    if (!token) {
-      fail("Not authenticated. Run `neopress login`.");
+    if (options.use && options.pin) {
+      fail("Pass only one of --use (global active site) or --pin (this directory only).");
     }
-    const client = new NeopressClient({
-      accessToken: token,
-      siteId: 0,
-      baseUrl: getBaseUrl()
-    });
+    const client = await getGlobalClientAsync();
     const site = await client.site.create({
       siteName: options.name,
       siteHandle: options.handle,
       prompt: options.prompt,
       language: options.language
     });
-    if (options.use) {
-      setActiveSiteId(site.id);
-    }
+    if (options.use) setActiveSiteId(site.id);
+    let pinnedPath;
+    if (options.pin) pinnedPath = writeProjectSiteId(site.id);
     output(site);
-    if (options.use && !isJsonMode()) ok(`Active site set to ${site.id}`);
+    if (!isJsonMode()) {
+      if (options.use) ok(`Active site set to ${site.id}`);
+      if (options.pin) ok(`Pinned site ${site.id} for this directory (${pinnedPath})`);
+    }
   });
   sites.command("get").description("Get current site info").action(async () => {
     const client = await getClientAsync();
     const site = await client.site.get();
     output(site);
   });
-  sites.command("update").description("Update site settings").option("--name <name>", "Site name").option("--locale-config <json>", "Locale config JSON").action(async (options) => {
+  sites.command("current").description("Show which site commands will target, and where it resolved from").addHelpText("after", `
+Resolution order: --site flag > NEOPRESS_SITE_ID > .neopressrc.json/.neopress/config.json (cwd and up) > global active site (set by \`sites use\`).
+Local check only \u2014 it does not contact the server. Unlike \`whoami\` (which always reports the global active site), this reports the site your next command will actually hit.`).action(() => {
+    const { value, source, detail } = resolveSiteTarget();
+    output({ siteId: value ?? null, source, resolvedFrom: detail ?? null });
+  });
+  sites.command("update").description("Update site settings").addHelpText("after", `
+Examples:
+  $ neopress sites update --name "New Name"
+  $ neopress sites update --locale-config '{"locales":["en","ko"],"defaultLocale":"en"}'
+Updates the active site. --locale-config takes inline JSON. Pass at least one of --name or --locale-config.`).option("--name <name>", "Site name").option("--locale-config <json>", "Locale config JSON").action(async (options) => {
     const client = await getClientAsync();
     const data = {};
     if (options.name) data.name = options.name;
@@ -40819,7 +41008,11 @@ function registerSiteCommands(program3) {
     const site = await client.site.update(data);
     output(site);
   });
-  sites.command("delete <siteIdOrHandle>").description("Delete a site and all its content (workspace admin only)").option("--yes", "Skip confirmation (required in non-interactive mode)").action(async (siteIdOrHandle, options) => {
+  sites.command("delete <siteIdOrHandle>").description("Delete a site and all its content (workspace admin only)").addHelpText("after", `
+Examples:
+  $ neopress sites delete my-site
+  $ neopress sites delete 12 --yes
+Permanently deletes the site and all its content (workspace admin only) \u2014 this is a hard delete, not recoverable. Interactive runs prompt for the id/handle to confirm; --yes is required in non-interactive mode.`).option("--yes", "Skip confirmation (required in non-interactive mode)").action(async (siteIdOrHandle, options) => {
     const interactive = process.stdout.isTTY && process.stdin.isTTY;
     if (!options.yes && !interactive) {
       fail("Refusing to delete without --yes in non-interactive mode.");
@@ -40828,9 +41021,9 @@ function registerSiteCommands(program3) {
       const { createInterface } = await import("readline");
       const rl = createInterface({ input: process.stdin, output: process.stdout });
       const answer = await new Promise(
-        (resolve) => rl.question(`Delete site "${siteIdOrHandle}" and ALL its content? Type the id/handle to confirm: `, (a) => {
+        (resolve2) => rl.question(`Delete site "${siteIdOrHandle}" and ALL its content? Type the id/handle to confirm: `, (a) => {
           rl.close();
-          resolve(a.trim());
+          resolve2(a.trim());
         })
       );
       if (answer !== siteIdOrHandle) {
@@ -40878,7 +41071,13 @@ function mergeQueryConfigIntoDraftMeta(draftMetaInput, queryConfigInput) {
   };
 }
 function registerPageCommands(program3) {
-  const pages = program3.command("pages").description("Manage pages");
+  const pages = program3.command("pages").description("Manage pages").addHelpText("after", `
+Examples:
+  $ neopress pages create --path /about --title About --tsx ./about.tsx
+  $ neopress pages update <pageId> --tsx ./about.tsx
+  $ neopress pages compile <pageId>
+
+Draft content fields (--tsx/--i18n/--draft-meta) need \`neopress publish\` to go live. \`pages delete\` is a soft delete.`);
   pages.command("list").description("List pages").option("--status <status>", "Filter by status (draft/published)").option("--page <n>", "Page number", "1").option("--limit <n>", "Results per page", "20").action(async (options) => {
     const client = await getClientAsync();
     const res = await client.pages.list({
@@ -40893,7 +41092,17 @@ function registerPageCommands(program3) {
     const page = await client.pages.get(parseInt(pageId, 10));
     output(page);
   });
-  pages.command("create").description("Create a new page").requiredOption("--path <path>", "Page path (e.g., /about)").option("--title <title>", "Page title").option("--tsx <file>", "TSX file path").option("--i18n <json>", "Page i18n JSON string or @file path").option("--public-locales <locales>", "Comma-separated locale list or JSON string array").option("--metadata <json>", "Page metadata JSON string or @file path").option("--draft-meta <json>", "Draft runtime metadata JSON string or @file path").option("--query-config <json>", "Query config JSON string or @file path; stored as draftMeta.queryConfig").option("--collection <id>", "Collection ID for dynamic pages").option("--type <type>", "Page type (static/dynamic)", "static").action(async (options) => {
+  pages.command("create").description("Create a new page").requiredOption("--path <path>", "Page path (e.g., /about)").option("--title <title>", "Page title").option("--tsx <file>", "TSX file path").option("--i18n <json>", "Page i18n JSON string or @file path").option("--public-locales <locales>", "Comma-separated locale list or JSON string array").option("--metadata <json>", "Page metadata JSON string or @file path").option("--draft-meta <json>", "Draft runtime metadata JSON string or @file path").option("--query-config <json>", "Query config JSON string or @file path; stored as draftMeta.queryConfig").option("--collection <id>", "Collection ID for dynamic pages").option("--type <type>", "Page type (static/dynamic)", "static").addHelpText(
+    "after",
+    `
+Examples:
+  $ neopress pages create --path /about --title About --tsx ./about.tsx
+  $ neopress pages create --path /blog --type dynamic --collection 12 --tsx ./blog.tsx
+  $ neopress pages create --path /about --i18n @i18n.json --public-locales en,ko
+
+--tsx reads the component from a file. JSON options take inline JSON or @file (e.g. --i18n @i18n.json).
+Pages are created as drafts \u2014 run \`neopress publish\` to make them live.`
+  ).action(async (options) => {
     const client = await getClientAsync();
     const draftTsx = options.tsx ? (0, import_node_fs3.readFileSync)(options.tsx, "utf-8") : void 0;
     const draftI18n = parseJsonInput(options.i18n);
@@ -40914,7 +41123,13 @@ function registerPageCommands(program3) {
     });
     output(page);
   });
-  pages.command("update <pageId>").description("Update a page").option("--path <path>", "New page path").option("--title <title>", "New title").option("--tsx <file>", "TSX file path").option("--i18n <json>", "Page i18n JSON string or @file path").option("--public-locales <locales>", "Comma-separated locale list or JSON string array").option("--metadata <json>", "Page metadata JSON string or @file path").option("--draft-meta <json>", "Draft runtime metadata JSON string or @file path").option("--query-config <json>", "Query config JSON string or @file path; stored as draftMeta.queryConfig").option("--collection <id>", "Collection ID for dynamic pages").action(async (pageId, options) => {
+  pages.command("update <pageId>").description("Update a page").addHelpText("after", `
+Examples:
+  $ neopress pages update 12 --tsx ./about.tsx
+  $ neopress pages update 12 --title About --path /about-us
+  $ neopress pages update 12 --collection 12 --query-config @query.json
+
+Pass at least one field flag. --tsx reads the component from a file; JSON options take inline JSON or @file. Draft content (--tsx/--i18n/--draft-meta/--query-config) needs \`neopress publish\` to go live; --title/--path/--collection apply immediately.`).option("--path <path>", "New page path").option("--title <title>", "New title").option("--tsx <file>", "TSX file path").option("--i18n <json>", "Page i18n JSON string or @file path").option("--public-locales <locales>", "Comma-separated locale list or JSON string array").option("--metadata <json>", "Page metadata JSON string or @file path").option("--draft-meta <json>", "Draft runtime metadata JSON string or @file path").option("--query-config <json>", "Query config JSON string or @file path; stored as draftMeta.queryConfig").option("--collection <id>", "Collection ID for dynamic pages").action(async (pageId, options) => {
     const client = await getClientAsync();
     const data = {};
     if (options.path) data.path = options.path;
@@ -40938,7 +41153,11 @@ function registerPageCommands(program3) {
     await client.pages.delete(parseInt(pageId, 10));
     ok(`Page ${pageId} deleted`);
   });
-  pages.command("compile <pageId>").description("Validate TSX compilation").action(async (pageId) => {
+  pages.command("compile <pageId>").description("Validate TSX compilation").addHelpText("after", `
+Examples:
+  $ neopress pages compile 12
+
+Validates the page's draft TSX and reports compile status \u2014 it does not save or publish.`).action(async (pageId) => {
     const client = await getClientAsync();
     const result = await client.pages.compile(parseInt(pageId, 10));
     output(result);
@@ -40952,7 +41171,13 @@ function parseJsonInput2(input) {
   return input.startsWith("@") ? JSON.parse((0, import_node_fs4.readFileSync)(input.slice(1), "utf-8")) : JSON.parse(input);
 }
 function registerCollectionCommands(program3) {
-  const collections = program3.command("collections").description("Manage collections");
+  const collections = program3.command("collections").description("Manage collections").addHelpText("after", `
+Examples:
+  $ neopress collections create --name Posts --schema @schema.json
+  $ neopress collections list
+  $ neopress collections update 12 --schema @schema.json
+
+Collections are identified by numeric id, never name. delete is a soft delete \u2014 the collection is hidden from list/get but its row is retained.`);
   collections.command("list").description("List collections").action(async () => {
     const client = await getClientAsync();
     const data = await client.collections.list();
@@ -40963,7 +41188,13 @@ function registerCollectionCommands(program3) {
     const data = await client.collections.get(parseInt(collectionId, 10));
     output(data);
   });
-  collections.command("create").description("Create a collection").requiredOption("--name <name>", "Collection name").option("--schema <json>", "Draft schema as JSON string or @file path").action(async (options) => {
+  collections.command("create").description("Create a collection").addHelpText("after", `
+Examples:
+  $ neopress collections create --name Posts
+  $ neopress collections create --name Posts --schema @schema.json
+  $ neopress collections create --name Posts --schema '{"title":{"type":"text"}}'
+
+--schema takes inline JSON or @file and is keyed by field id. It is written to the draft schema \u2014 publish the site to make it live.`).requiredOption("--name <name>", "Collection name").option("--schema <json>", "Draft schema as JSON string or @file path").action(async (options) => {
     const client = await getClientAsync();
     const data = await client.collections.create({
       name: options.name,
@@ -40971,7 +41202,12 @@ function registerCollectionCommands(program3) {
     });
     output(data);
   });
-  collections.command("update <collectionId>").description("Update a collection").option("--name <name>", "Collection name").option("--schema <json>", "Draft schema as JSON string or @file path").action(async (collectionId, options) => {
+  collections.command("update <collectionId>").description("Update a collection").addHelpText("after", `
+Examples:
+  $ neopress collections update 12 --name Articles
+  $ neopress collections update 12 --schema @schema.json
+
+Identify the collection by numeric id. Pass at least one of --name or --schema. --schema (inline JSON or @file, field-id keyed) replaces the draft schema; publish the site to make it live.`).option("--name <name>", "Collection name").option("--schema <json>", "Draft schema as JSON string or @file path").action(async (collectionId, options) => {
     const client = await getClientAsync();
     const data = {};
     if (options.name) data.name = options.name;
@@ -40995,7 +41231,13 @@ function registerCollectionCommands(program3) {
 // src/commands/entries.ts
 var import_node_fs5 = require("fs");
 function registerEntryCommands(program3) {
-  const entries = program3.command("entries").description("Manage entries");
+  const entries = program3.command("entries").description("Manage entries").addHelpText("after", `
+Examples:
+  $ neopress entries list --collection 12 --status published --locale en
+  $ neopress entries create --collection 12 --data @entry.json --title Hello
+  $ neopress entries publish <entryId>
+
+Entries are created as drafts \u2014 run \`neopress entries publish <entryId>\` to make them live. create/update/delete revalidate the reader cache; delete is a soft delete.`);
   entries.command("list").description("List entries in a collection").requiredOption("--collection <id>", "Collection ID").option("--status <status>", "Filter by status").option("--locale <locale>", "Filter by locale").option("--page <n>", "Page number", "1").option("--limit <n>", "Results per page", "20").action(async (options) => {
     const client = await getClientAsync();
     const res = await client.entries.list(parseInt(options.collection, 10), {
@@ -41011,7 +41253,15 @@ function registerEntryCommands(program3) {
     const data = await client.entries.get(parseInt(entryId, 10));
     output(data);
   });
-  entries.command("create").description("Create an entry").requiredOption("--collection <id>", "Collection ID").option("--data <json>", "Entry data as JSON string or @file path").option("--title <title>", "Entry title").option("--slug <slug>", "Entry slug").option("--locale <locale>", "Entry locale").action(async (options) => {
+  entries.command("create").description("Create an entry").requiredOption("--collection <id>", "Collection ID").option("--data <json>", "Entry data as JSON string or @file path").option("--title <title>", "Entry title").option("--slug <slug>", "Entry slug").option("--locale <locale>", "Entry locale").addHelpText(
+    "after",
+    `
+Examples:
+  $ neopress entries create --collection 12 --data '{"body":"Hello"}' --title Hello
+  $ neopress entries create --collection 12 --data @entry.json --locale ko
+
+--data takes inline JSON or @file. After creating, run \`neopress entries publish <entryId>\` to publish it.`
+  ).action(async (options) => {
     const client = await getClientAsync();
     let data;
     if (options.data?.startsWith("@")) {
@@ -41030,7 +41280,12 @@ function registerEntryCommands(program3) {
     await client.entries.revalidateReaderCache(entry.id);
     output(entry);
   });
-  entries.command("update <entryId>").description("Update an entry").option("--data <json>", "Entry data as JSON string or @file path").option("--title <title>", "Entry title").option("--slug <slug>", "Entry slug").option("--locale <locale>", "Entry locale").action(async (entryId, options) => {
+  entries.command("update <entryId>").description("Update an entry").addHelpText("after", `
+Examples:
+  $ neopress entries update <entryId> --title "New title"
+  $ neopress entries update <entryId> --data @entry.json --locale ko
+
+--data takes inline JSON or @file and replaces the entry data. At least one field is required. Updating revalidates the reader cache; publish state is unchanged.`).option("--data <json>", "Entry data as JSON string or @file path").option("--title <title>", "Entry title").option("--slug <slug>", "Entry slug").option("--locale <locale>", "Entry locale").action(async (entryId, options) => {
     const client = await getClientAsync();
     const updateData = {};
     if (options.data) {
@@ -41071,7 +41326,12 @@ function parseJsonInput3(input) {
   return input.startsWith("@") ? JSON.parse((0, import_node_fs6.readFileSync)(input.slice(1), "utf-8")) : JSON.parse(input);
 }
 function registerFormCommands(program3) {
-  const forms = program3.command("forms").description("Manage forms");
+  const forms = program3.command("forms").description("Manage forms").addHelpText("after", `
+Examples:
+  $ neopress forms create --name Contact --schema @schema.json --layout @layout.json
+  $ neopress forms publish <formId>
+  $ neopress forms responses <formId> --limit 50
+Forms are created as drafts \u2014 run \`neopress forms publish <formId>\` to make them live. JSON options take inline JSON or @file.`);
   forms.command("list").description("List forms").action(async () => {
     const client = await getClientAsync();
     const data = await client.forms.list();
@@ -41082,7 +41342,12 @@ function registerFormCommands(program3) {
     const data = await client.forms.get(parseInt(formId, 10));
     output(data);
   });
-  forms.command("create").description("Create a form").requiredOption("--name <name>", "Form name").option("--schema <json>", "Draft form schema JSON string or @file path").option("--layout <json>", "Draft form layout JSON string or @file path").option("--style <json>", "Draft form style JSON string or @file path").option("--i18n <json>", "Draft form i18n JSON string or @file path").option("--settings <json>", "Form settings JSON string or @file path").action(async (options) => {
+  forms.command("create").description("Create a form").addHelpText("after", `
+Examples:
+  $ neopress forms create --name Contact
+  $ neopress forms create --name Contact --schema @schema.json --layout @layout.json --i18n @i18n.json
+  $ neopress forms create --name Signup --settings '{"redirectUrl":"/thanks"}'
+Only --name is required. --schema/--layout/--style/--i18n/--settings each take inline JSON or @file and write the draft state. The form is created as a draft \u2014 run \`neopress forms publish\` to make it live.`).requiredOption("--name <name>", "Form name").option("--schema <json>", "Draft form schema JSON string or @file path").option("--layout <json>", "Draft form layout JSON string or @file path").option("--style <json>", "Draft form style JSON string or @file path").option("--i18n <json>", "Draft form i18n JSON string or @file path").option("--settings <json>", "Form settings JSON string or @file path").action(async (options) => {
     const client = await getClientAsync();
     const data = await client.forms.create({
       name: options.name,
@@ -41094,7 +41359,11 @@ function registerFormCommands(program3) {
     });
     output(data);
   });
-  forms.command("update <formId>").description("Update a form").option("--name <name>", "Form name").option("--schema <json>", "Draft form schema JSON string or @file path").option("--layout <json>", "Draft form layout JSON string or @file path").option("--style <json>", "Draft form style JSON string or @file path").option("--i18n <json>", "Draft form i18n JSON string or @file path").option("--settings <json>", "Form settings JSON string or @file path").action(async (formId, options) => {
+  forms.command("update <formId>").description("Update a form").addHelpText("after", `
+Examples:
+  $ neopress forms update <formId> --name Contact
+  $ neopress forms update <formId> --schema @schema.json --layout @layout.json
+Only the supplied fields change; pass at least one of --name/--schema/--layout/--style/--i18n/--settings. JSON options take inline JSON or @file and update the draft state \u2014 run \`neopress forms publish\` to push changes live.`).option("--name <name>", "Form name").option("--schema <json>", "Draft form schema JSON string or @file path").option("--layout <json>", "Draft form layout JSON string or @file path").option("--style <json>", "Draft form style JSON string or @file path").option("--i18n <json>", "Draft form i18n JSON string or @file path").option("--settings <json>", "Form settings JSON string or @file path").action(async (formId, options) => {
     const client = await getClientAsync();
     const data = {};
     if (options.name) data.name = options.name;
@@ -41109,12 +41378,19 @@ function registerFormCommands(program3) {
     const updated = await client.forms.update(parseInt(formId, 10), data);
     output(updated);
   });
-  forms.command("publish <formId>").description("Publish a form").action(async (formId) => {
+  forms.command("publish <formId>").description("Publish a form").addHelpText("after", `
+Examples:
+  $ neopress forms publish <formId>
+Copies the form's draft state (schema/layout/style/i18n) to its live state. Required after create/update before the form renders publicly.`).action(async (formId) => {
     const client = await getClientAsync();
     const result = await client.forms.publish(parseInt(formId, 10));
     output(result);
   });
-  forms.command("responses <formId>").description("List form responses").option("--page <n>", "Page number", "1").option("--limit <n>", "Results per page", "20").action(async (formId, options) => {
+  forms.command("responses <formId>").description("List form responses").addHelpText("after", `
+Examples:
+  $ neopress forms responses <formId>
+  $ neopress forms responses <formId> --page 2 --limit 50
+Returns submitted responses newest-first, paginated (--page/--limit, default page 1, limit 20).`).option("--page <n>", "Page number", "1").option("--limit <n>", "Results per page", "20").action(async (formId, options) => {
     const client = await getClientAsync();
     const res = await client.forms.listResponses(parseInt(formId, 10), {
       page: parseInt(options.page, 10),
@@ -41133,7 +41409,11 @@ function registerFormCommands(program3) {
 var import_node_fs7 = require("fs");
 var import_node_path3 = require("path");
 function registerAssetCommands(program3) {
-  const assets = program3.command("assets").description("Manage assets");
+  const assets = program3.command("assets").description("Manage assets").addHelpText("after", `
+Examples:
+  $ neopress assets upload ./hero.png --folder images
+  $ neopress assets list --limit 50
+Upload runs presign \u2192 PUT to storage \u2192 register in one step; content type is inferred from the file extension.`);
   assets.command("list").description("List assets").option("--page <n>", "Page number", "1").option("--limit <n>", "Results per page", "20").action(async (options) => {
     const client = await getClientAsync();
     const res = await client.assets.list({
@@ -41142,7 +41422,11 @@ function registerAssetCommands(program3) {
     });
     output(res);
   });
-  assets.command("upload <filePath>").description("Upload a file (presign \u2192 upload \u2192 register)").option("--folder <folder>", "Target folder path").action(async (filePath, options) => {
+  assets.command("upload <filePath>").description("Upload a file (presign \u2192 upload \u2192 register)").addHelpText("after", `
+Examples:
+  $ neopress assets upload ./hero.png
+  $ neopress assets upload ./docs/guide.pdf --folder downloads
+<filePath> is a local file path; its extension sets the content type. --folder is the storage subfolder (defaults to uploads/); omit it and the asset record's folder is left unset. Prints the registered asset and its public URL.`).option("--folder <folder>", "Target folder path").action(async (filePath, options) => {
     const client = await getClientAsync();
     const fileName = (0, import_node_path3.basename)(filePath);
     const stats = (0, import_node_fs7.statSync)(filePath);
@@ -41188,7 +41472,13 @@ function registerAssetCommands(program3) {
 
 // src/commands/publish.ts
 function registerPublishCommands(program3) {
-  const publish = program3.command("publish").description("Publish site or preview changes").action(async () => {
+  const publish = program3.command("publish").description("Publish site or preview changes").addHelpText(
+    "after",
+    `
+Examples:
+  $ neopress publish preview     Show what would change
+  $ neopress publish             Publish all pending changes live`
+  ).action(async () => {
     const client = await getClientAsync();
     const result = await client.publish.site();
     output(result);
@@ -41203,13 +41493,22 @@ function registerPublishCommands(program3) {
 
 // src/commands/redirects.ts
 function registerRedirectCommands(program3) {
-  const redirects = program3.command("redirects").description("Manage redirect rules");
+  const redirects = program3.command("redirects").description("Manage redirect rules").addHelpText("after", `
+Examples:
+  $ neopress redirects create --source /old --dest /about
+  $ neopress redirects create --source /docs --dest /guide --type 308
+  $ neopress redirects list
+Rules are created enabled. delete <ruleId> removes a rule permanently.`);
   redirects.command("list").description("List redirect rules").action(async () => {
     const client = await getClientAsync();
     const data = await client.redirects.list();
     output(data);
   });
-  redirects.command("create").description("Create a redirect rule").requiredOption("--source <path>", "Source path").requiredOption("--dest <path>", "Destination path").option("--type <type>", "Redirect type (307/308)", "307").action(async (options) => {
+  redirects.command("create").description("Create a redirect rule").addHelpText("after", `
+Examples:
+  $ neopress redirects create --source /old --dest /about
+  $ neopress redirects create --source /docs --dest /guide --type 308
+--source and --dest are both required. --type is 307 (temporary, default) or 308 (permanent). The rule is created enabled.`).requiredOption("--source <path>", "Source path").requiredOption("--dest <path>", "Destination path").option("--type <type>", "Redirect type (307/308)", "307").action(async (options) => {
     const client = await getClientAsync();
     const rule = await client.redirects.create({
       source: options.source,
@@ -41228,13 +41527,22 @@ function registerRedirectCommands(program3) {
 // src/commands/layout.ts
 var import_node_fs8 = require("fs");
 function registerLayoutCommands(program3) {
-  const layout = program3.command("layout").description("Manage site layout");
+  const layout = program3.command("layout").description("Manage site layout").addHelpText("after", `
+Examples:
+  $ neopress layout get
+  $ neopress layout update --tsx ./layout.tsx --global-css ./globals.css
+  $ neopress layout update --not-found-tsx ./not-found.tsx
+Layout edits land in draft state \u2014 run \`neopress publish\` to make them live.`);
   layout.command("get").description("Get current site layout").action(async () => {
     const client = await getClientAsync();
     const data = await client.site.getLayout();
     output(data);
   });
-  layout.command("update").description("Update site layout").option("--tsx <file>", "Layout TSX file path").option("--not-found-tsx <file>", "Not-found page TSX file path").option("--global-css <file>", "Global CSS file path").action(async (options) => {
+  layout.command("update").description("Update site layout").addHelpText("after", `
+Examples:
+  $ neopress layout update --tsx ./layout.tsx
+  $ neopress layout update --tsx ./layout.tsx --not-found-tsx ./not-found.tsx --global-css ./globals.css
+Each flag reads its content from a file path. Pass at least one of --tsx, --not-found-tsx, or --global-css. Updates write to the draft layout only \u2014 run \`neopress publish\` to make them live.`).option("--tsx <file>", "Layout TSX file path").option("--not-found-tsx <file>", "Not-found page TSX file path").option("--global-css <file>", "Global CSS file path").action(async (options) => {
     const client = await getClientAsync();
     const data = {};
     if (options.tsx) data.draftTsx = (0, import_node_fs8.readFileSync)(options.tsx, "utf-8");
@@ -41250,7 +41558,12 @@ function registerLayoutCommands(program3) {
 
 // src/commands/entry-references.ts
 function registerEntryReferenceCommands(program3) {
-  const refs = program3.command("entry-references").description("Manage entry reference relations");
+  const refs = program3.command("entry-references").description("Manage entry reference relations").addHelpText("after", `
+Examples:
+  $ neopress entry-references create --from-entry 12 --to-entry 34 --field author
+  $ neopress entry-references list --from-entry 12
+  $ neopress entry-references delete <referenceId>
+--field is a reference field key from the source entry's collection schema. delete is a hard delete and removes the relation immediately.`);
   refs.command("list").description("List entry references").option("--from-entry <id>", "Filter by source entry ID").option("--to-entry <id>", "Filter by target entry ID").action(async (options) => {
     const client = await getClientAsync();
     const data = await client.entryReferences.list({
@@ -41259,7 +41572,11 @@ function registerEntryReferenceCommands(program3) {
     });
     output(data);
   });
-  refs.command("create").description("Create an entry reference").requiredOption("--from-entry <id>", "Source entry ID").requiredOption("--to-entry <id>", "Target entry ID").requiredOption("--field <key>", "Reference field key from the source collection schema").action(async (options) => {
+  refs.command("create").description("Create an entry reference").addHelpText("after", `
+Examples:
+  $ neopress entry-references create --from-entry 12 --to-entry 34 --field author
+  $ neopress entry-references create --from-entry 100 --to-entry 7 --field relatedPosts
+All three flags are required. --field is a reference field key defined in the source entry's collection schema; --from-entry and --to-entry must be numeric entry IDs.`).requiredOption("--from-entry <id>", "Source entry ID").requiredOption("--to-entry <id>", "Target entry ID").requiredOption("--field <key>", "Reference field key from the source collection schema").action(async (options) => {
     const client = await getClientAsync();
     const fromEntryId = parseInt(options.fromEntry, 10);
     const toEntryId = parseInt(options.toEntry, 10);
@@ -41326,9 +41643,19 @@ function parseSearchConsoleDimensions(raw) {
   return dimensions;
 }
 function registerAnalyticsCommands(program3) {
-  const analytics = program3.command("analytics").description("Read site analytics and Search Console data");
+  const analytics = program3.command("analytics").description("Read site analytics and Search Console data").addHelpText("after", `
+Examples:
+  $ neopress analytics summary --date-from 2026-01-01 --date-to 2026-01-31
+  $ neopress analytics pages --date-from 2026-01-01 --date-to 2026-01-31 --limit 20
+  $ neopress analytics search-console --date-from 2026-01-01 --date-to 2026-01-31 --dimensions query,page
+All analytics commands are read-only. Convenience commands (summary, pages, sources, forms, crawlers, pageviews) share --date-from/--date-to/--timezone/--limit.`);
   addDateOptions(
-    analytics.command("query").description("Run an allowed analytics pipe").requiredOption("--pipe <pipe>", "Analytics pipe name")
+    analytics.command("query").description("Run an allowed analytics pipe").addHelpText("after", `
+Examples:
+  $ neopress analytics query --pipe get_top_pages --date-from 2026-01-01 --date-to 2026-01-31
+  $ neopress analytics query --pipe get_pageviews --params '{"device":"mobile"}'
+  $ neopress analytics query --pipe get_top_pages --params @params.json --limit 50
+--pipe is required. --params takes inline JSON or @file and adds extra pipe params; reserved keys (pipe, site, site_id, timezone, token, q) are ignored.`).requiredOption("--pipe <pipe>", "Analytics pipe name")
   ).action(async (options) => {
     const client = await getClientAsync();
     const data = await client.analytics.query({
@@ -41373,7 +41700,12 @@ function registerAnalyticsCommands(program3) {
     const client = await getClientAsync();
     output(await client.analytics.crawlerSummary(readDateOptions(options)));
   });
-  analytics.command("search-console").description("Query Google Search Console performance data").requiredOption("--date-from <date>", "Start date in YYYY-MM-DD").requiredOption("--date-to <date>", "End date in YYYY-MM-DD").option("--dimensions <csv>", "CSV dimensions: query,page,country,device", "query").option("--query-filter <query>", "Exact query filter").option("--page-filter <url>", "Exact page URL filter").option("--row-limit <n>", "Maximum rows to return", "100").action(async (options) => {
+  analytics.command("search-console").description("Query Google Search Console performance data").addHelpText("after", `
+Examples:
+  $ neopress analytics search-console --date-from 2026-01-01 --date-to 2026-01-31
+  $ neopress analytics search-console --date-from 2026-01-01 --date-to 2026-01-31 --dimensions query,page --row-limit 50
+  $ neopress analytics search-console --date-from 2026-01-01 --date-to 2026-01-31 --page-filter https://example.com/about
+--date-from and --date-to are required. --dimensions is a CSV of query,page,country,device (defaults to query).`).requiredOption("--date-from <date>", "Start date in YYYY-MM-DD").requiredOption("--date-to <date>", "End date in YYYY-MM-DD").option("--dimensions <csv>", "CSV dimensions: query,page,country,device", "query").option("--query-filter <query>", "Exact query filter").option("--page-filter <url>", "Exact page URL filter").option("--row-limit <n>", "Maximum rows to return", "100").action(async (options) => {
     const client = await getClientAsync();
     const data = await client.analytics.searchConsole({
       dateFrom: options.dateFrom,
@@ -41392,7 +41724,12 @@ function collectPreviewImgUrl(value, previous = []) {
   return previous.concat(value);
 }
 function registerTemplateCommands(program3) {
-  const templates = program3.command("templates").description("Manage template metadata for the active site");
+  const templates = program3.command("templates").description("Manage template metadata for the active site").addHelpText("after", `
+Examples:
+  $ neopress templates mark --name "SaaS Landing" --industry saas --reference-url https://example.com --preview-img-url https://cdn.example.com/1.png
+  $ neopress templates list --industry saas --limit 50
+  $ neopress templates delete
+\`templates mark\` operates on the active site. \`templates delete\` permanently removes the template metadata AND the connected site \u2014 it is destructive and not recoverable.`);
   templates.command("list").description("List templates across sites you can access").option("--name-prefix <prefix>", "Filter by template name prefix").option("--industry <industry>", "Filter by industry key").option("--limit <n>", "Max results (default 100, max 500)").action(async (options) => {
     const token = process.env.NEOPRESS_ACCESS_TOKEN || await getValidAccessToken() || void 0;
     if (!token) {
@@ -41411,7 +41748,11 @@ function registerTemplateCommands(program3) {
     const template = await client.templates.get();
     output(template);
   });
-  templates.command("mark").description("Mark or update the active site as a template").requiredOption("--name <name>", "Template display name").option("--description <description>", "Template description, up to 150 characters").requiredOption("--industry <industry>", "Template industry key").requiredOption(
+  templates.command("mark").description("Mark or update the active site as a template").addHelpText("after", `
+Examples:
+  $ neopress templates mark --name "SaaS Landing" --industry saas --reference-url https://example.com --preview-img-url https://cdn.example.com/1.png
+  $ neopress templates mark --name Portfolio --industry creative --reference-url https://example.com --preview-img-url https://cdn.example.com/a.png --preview-img-url https://cdn.example.com/b.png --description "Minimal portfolio"
+--name, --industry, and --reference-url are all required, and at least one --preview-img-url must be given (repeat the flag for multiple images). Upserts the template metadata for the active site and sets the site status to active; running it again updates the existing template.`).requiredOption("--name <name>", "Template display name").option("--description <description>", "Template description, up to 150 characters").requiredOption("--industry <industry>", "Template industry key").requiredOption(
     "--reference-url <url>",
     "Reference URL for template provenance"
   ).option(
@@ -41437,9 +41778,226 @@ function registerTemplateCommands(program3) {
   });
 }
 
+// src/commands/headshots.ts
+var AGE_BANDS = ["young", "middle"];
+var GENDERS = ["male", "female"];
+var ETHNICITIES = ["asian", "white", "black", "latino"];
+var ATTIRES = ["formal"];
+function validateEnum(value, allowed, flag) {
+  if (value !== void 0 && !allowed.includes(value)) {
+    fail(`${flag} must be one of: ${allowed.join(", ")}`);
+  }
+}
+function parseNonNegativeInt(raw, flag) {
+  if (raw === void 0) return void 0;
+  const value = Number(raw);
+  if (!Number.isInteger(value) || value < 0) {
+    fail(`${flag} must be a non-negative integer`);
+  }
+  return value;
+}
+function registerHeadshotCommands(program3) {
+  const headshots = program3.command("headshots").description("Manage the shared headshot pool (super-admin only)").addHelpText("after", `
+Examples:
+  $ neopress headshots list --gender female --ethnicity asian
+  $ neopress headshots create --image-url https://cdn/x.webp --age-band young --gender male --ethnicity white --variation-index 0
+  $ neopress headshots update 12 --inactive
+The pool is global and RLS-gated: only the super-admin account can read or write it. No active site is needed.`);
+  headshots.command("list").description("List headshot pool entries").option("--age-band <band>", `Filter by age band (${AGE_BANDS.join("/")})`).option("--gender <gender>", `Filter by gender (${GENDERS.join("/")})`).option("--ethnicity <ethnicity>", `Filter by ethnicity (${ETHNICITIES.join("/")})`).option("--attire <attire>", `Filter by attire (${ATTIRES.join("/")})`).option("--active", "Only active entries").option("--inactive", "Only inactive entries").option("--page <n>", "Page number", "1").option("--limit <n>", "Results per page", "20").addHelpText("after", `
+Examples:
+  $ neopress headshots list
+  $ neopress headshots list --gender female --age-band middle --active
+Filters are equality matches on the pool's demographic columns; results are paginated.`).action(async (options) => {
+    validateEnum(options.ageBand, AGE_BANDS, "--age-band");
+    validateEnum(options.gender, GENDERS, "--gender");
+    validateEnum(options.ethnicity, ETHNICITIES, "--ethnicity");
+    validateEnum(options.attire, ATTIRES, "--attire");
+    if (options.active && options.inactive) {
+      fail("Use only one of --active or --inactive.");
+    }
+    const params = {
+      page: parseInt(options.page, 10),
+      limit: parseInt(options.limit, 10),
+      ageBand: options.ageBand,
+      gender: options.gender,
+      ethnicity: options.ethnicity,
+      attire: options.attire
+    };
+    if (options.active) params.isActive = true;
+    else if (options.inactive) params.isActive = false;
+    const client = await getGlobalClientAsync();
+    const res = await client.headshots.list(params);
+    output(res);
+  });
+  headshots.command("get <id>").description("Get a headshot pool entry").action(async (id) => {
+    const client = await getGlobalClientAsync();
+    const data = await client.headshots.get(parseInt(id, 10));
+    output(data);
+  });
+  headshots.command("create").description("Add a headshot to the pool").requiredOption("--image-url <url>", "Public image URL").requiredOption("--age-band <band>", `Age band (${AGE_BANDS.join("/")})`).requiredOption("--gender <gender>", `Gender (${GENDERS.join("/")})`).requiredOption("--ethnicity <ethnicity>", `Ethnicity (${ETHNICITIES.join("/")})`).requiredOption("--variation-index <n>", "Variation index within the demographic cell (>= 0)").option("--attire <attire>", `Attire (${ATTIRES.join("/")}; default formal)`).option("--width <n>", "Image width in px").option("--height <n>", "Image height in px").option("--aspect-ratio <ratio>", "Aspect ratio, e.g. 2:3").option("--mime-type <type>", "MIME type, e.g. image/webp").option("--byte-size <n>", "File size in bytes").option("--gpt-prompt <prompt>", "Generation prompt (for provenance)").option("--tags <csv>", "Comma-separated tags").option("--inactive", "Create as inactive (default active)").addHelpText("after", `
+Examples:
+  $ neopress headshots create --image-url https://cdn/a.webp --age-band young --gender female --ethnicity asian --variation-index 0
+  $ neopress headshots create --image-url https://cdn/b.webp --age-band middle --gender male --ethnicity black --variation-index 1 --tags suit,studio
+(age-band, gender, ethnicity, attire, variation-index) must be unique. The DB rejects out-of-range enum values.`).action(async (options) => {
+    validateEnum(options.ageBand, AGE_BANDS, "--age-band");
+    validateEnum(options.gender, GENDERS, "--gender");
+    validateEnum(options.ethnicity, ETHNICITIES, "--ethnicity");
+    validateEnum(options.attire, ATTIRES, "--attire");
+    const variationIndex = parseNonNegativeInt(options.variationIndex, "--variation-index");
+    const params = {
+      imageUrl: options.imageUrl,
+      ageBand: options.ageBand,
+      gender: options.gender,
+      ethnicity: options.ethnicity,
+      variationIndex
+    };
+    if (options.attire) params.attire = options.attire;
+    const width = parseNonNegativeInt(options.width, "--width");
+    if (width !== void 0) params.width = width;
+    const height = parseNonNegativeInt(options.height, "--height");
+    if (height !== void 0) params.height = height;
+    if (options.aspectRatio) params.aspectRatio = options.aspectRatio;
+    if (options.mimeType) params.mimeType = options.mimeType;
+    const byteSize = parseNonNegativeInt(options.byteSize, "--byte-size");
+    if (byteSize !== void 0) params.byteSize = byteSize;
+    if (options.gptPrompt) params.gptPrompt = options.gptPrompt;
+    if (options.tags) params.tags = String(options.tags).split(",").map((t) => t.trim()).filter(Boolean);
+    if (options.inactive) params.isActive = false;
+    const client = await getGlobalClientAsync();
+    const data = await client.headshots.create(params);
+    output(data);
+  });
+  headshots.command("update <id>").description("Update a headshot pool entry").option("--image-url <url>", "Public image URL").option("--age-band <band>", `Age band (${AGE_BANDS.join("/")})`).option("--gender <gender>", `Gender (${GENDERS.join("/")})`).option("--ethnicity <ethnicity>", `Ethnicity (${ETHNICITIES.join("/")})`).option("--attire <attire>", `Attire (${ATTIRES.join("/")})`).option("--variation-index <n>", "Variation index (>= 0)").option("--width <n>", "Image width in px").option("--height <n>", "Image height in px").option("--aspect-ratio <ratio>", "Aspect ratio, e.g. 2:3").option("--mime-type <type>", "MIME type, e.g. image/webp").option("--byte-size <n>", "File size in bytes").option("--gpt-prompt <prompt>", "Generation prompt").option("--tags <csv>", "Comma-separated tags (replaces existing)").option("--active", "Mark active").option("--inactive", "Mark inactive").addHelpText("after", `
+Examples:
+  $ neopress headshots update 12 --inactive
+  $ neopress headshots update 12 --image-url https://cdn/new.webp --tags suit,studio
+Pass at least one field. --active/--inactive toggle is_active; --tags replaces the tag list.`).action(async (id, options) => {
+    validateEnum(options.ageBand, AGE_BANDS, "--age-band");
+    validateEnum(options.gender, GENDERS, "--gender");
+    validateEnum(options.ethnicity, ETHNICITIES, "--ethnicity");
+    validateEnum(options.attire, ATTIRES, "--attire");
+    if (options.active && options.inactive) {
+      fail("Use only one of --active or --inactive.");
+    }
+    const params = {};
+    if (options.imageUrl) params.imageUrl = options.imageUrl;
+    if (options.ageBand) params.ageBand = options.ageBand;
+    if (options.gender) params.gender = options.gender;
+    if (options.ethnicity) params.ethnicity = options.ethnicity;
+    if (options.attire) params.attire = options.attire;
+    const variationIndex = parseNonNegativeInt(options.variationIndex, "--variation-index");
+    if (variationIndex !== void 0) params.variationIndex = variationIndex;
+    const width = parseNonNegativeInt(options.width, "--width");
+    if (width !== void 0) params.width = width;
+    const height = parseNonNegativeInt(options.height, "--height");
+    if (height !== void 0) params.height = height;
+    if (options.aspectRatio) params.aspectRatio = options.aspectRatio;
+    if (options.mimeType) params.mimeType = options.mimeType;
+    const byteSize = parseNonNegativeInt(options.byteSize, "--byte-size");
+    if (byteSize !== void 0) params.byteSize = byteSize;
+    if (options.gptPrompt) params.gptPrompt = options.gptPrompt;
+    if (options.tags) params.tags = String(options.tags).split(",").map((t) => t.trim()).filter(Boolean);
+    if (options.active) params.isActive = true;
+    else if (options.inactive) params.isActive = false;
+    if (Object.keys(params).length === 0) {
+      fail("No fields to update.");
+    }
+    const client = await getGlobalClientAsync();
+    const data = await client.headshots.update(parseInt(id, 10), params);
+    output(data);
+  });
+  headshots.command("delete <id>").description("Delete a headshot pool entry (hard delete)").action(async (id) => {
+    const client = await getGlobalClientAsync();
+    await client.headshots.delete(parseInt(id, 10));
+    ok(`Headshot ${id} deleted`);
+  });
+}
+
+// src/commands/guide.ts
+function describeOption(opt) {
+  const info = { flags: opt.flags, description: opt.description || "" };
+  if (opt.defaultValue !== void 0) info.default = opt.defaultValue;
+  return info;
+}
+function describeArgument(arg) {
+  return {
+    name: arg.name(),
+    required: arg.required,
+    variadic: arg.variadic,
+    description: arg.description || ""
+  };
+}
+function describeCommand(cmd, prefix) {
+  const path = `${prefix} ${cmd.name()}`;
+  return {
+    path,
+    aliases: cmd.aliases(),
+    description: cmd.description(),
+    arguments: cmd.registeredArguments.map(describeArgument),
+    options: cmd.options.map(describeOption),
+    subcommands: cmd.commands.filter((c) => c.name() !== "help").map((c) => describeCommand(c, path))
+  };
+}
+function buildGuide(program3) {
+  return {
+    name: program3.name(),
+    version: program3.version() ?? "",
+    description: program3.description(),
+    globalOptions: program3.options.map(describeOption),
+    commands: program3.commands.filter((c) => c.name() !== "help").map((c) => describeCommand(c, program3.name()))
+  };
+}
+function pad(s, width) {
+  return s.length >= width ? `${s} ` : s + " ".repeat(width - s.length);
+}
+function argSignature(args) {
+  return args.map((a) => {
+    const inner = a.variadic ? `${a.name}...` : a.name;
+    return a.required ? `<${inner}>` : `[${inner}]`;
+  }).join(" ");
+}
+function printCommandNode(node, lines, depth) {
+  const indent = " ".repeat(depth * 2);
+  const sig = argSignature(node.arguments);
+  const head2 = `${indent}${node.path}${sig ? ` ${sig}` : ""}`;
+  lines.push(`${pad(head2, 46)}${node.description}`);
+  if (node.subcommands.length === 0) {
+    for (const o of node.options) {
+      const def = o.default !== void 0 ? ` (default: ${JSON.stringify(o.default)})` : "";
+      lines.push(`${pad(`${indent}    ${o.flags}`, 46)}${o.description}${def}`);
+    }
+  }
+  for (const sub of node.subcommands) printCommandNode(sub, lines, depth + 1);
+}
+function printHuman(guide) {
+  const lines = [];
+  lines.push(`${guide.name} ${guide.version} \u2014 ${guide.description}`);
+  lines.push("");
+  if (guide.globalOptions.length) {
+    lines.push("GLOBAL OPTIONS");
+    for (const o of guide.globalOptions) lines.push(`${pad(`  ${o.flags}`, 46)}${o.description}`);
+    lines.push("");
+  }
+  lines.push("COMMANDS");
+  for (const c of guide.commands) printCommandNode(c, lines, 1);
+  lines.push("");
+  lines.push("Run `neopress <command> --help` for details, or `neopress guide --json` for the full surface.");
+  console.log(lines.join("\n"));
+}
+function registerGuideCommands(program3) {
+  program3.command("guide").description("Print the full command reference (human tree, or --json for AI tools)").option("--json", "Output the command surface as JSON").action(() => {
+    const guide = buildGuide(program3);
+    if (isJsonMode()) {
+      console.log(JSON.stringify(guide, null, 2));
+    } else {
+      printHuman(guide);
+    }
+  });
+}
+
 // src/bin.ts
 var program2 = new Command();
-program2.name("neopress").description("Neopress CLI \u2014 manage your site from the terminal").version("4.0.0").option("--json", "Output in JSON format (for AI tools and pipes)").option("--site <idOrHandle>", "Target a specific site (overrides active site; not persisted)").option("--no-input", "Non-interactive mode").hook("preAction", (thisCommand) => {
+program2.name("neopress").description("Neopress CLI \u2014 manage your site from the terminal").version("4.2.0").option("--json", "Output in JSON format (for AI tools and pipes)").option("--site <idOrHandle>", "Target a specific site (overrides active site; not persisted)").option("--no-input", "Non-interactive mode").hook("preAction", (thisCommand) => {
   const opts = thisCommand.optsWithGlobals();
   if (opts.site) setSiteOverride(String(opts.site));
   if (opts.json || !process.stdout.isTTY) setJsonMode(true);
@@ -41457,6 +42015,28 @@ registerLayoutCommands(program2);
 registerEntryReferenceCommands(program2);
 registerAnalyticsCommands(program2);
 registerTemplateCommands(program2);
+registerHeadshotCommands(program2);
+registerGuideCommands(program2);
+program2.addHelpText(
+  "after",
+  `
+Quickstart:
+  $ neopress login                       Authenticate (or set NEOPRESS_ACCESS_TOKEN)
+  $ neopress sites list                  See sites you can access
+  $ neopress sites use <id|handle>       Pick the active site
+  $ neopress pages list                  List pages on the active site
+  $ neopress guide                       Full command reference (add --json for AI tools)
+
+AI / scripting:
+  Output is JSON automatically when piped or redirected; force it with --json.
+  Run \`neopress guide --json\` to get the entire command surface in one call.
+
+Env vars:
+  NEOPRESS_ACCESS_TOKEN   Auth token (skips \`neopress login\`)
+  NEOPRESS_SITE_ID        Default site id (overrides the active site)
+  NEOPRESS_BASE_URL       API base URL (defaults to the hosted Neopress app)
+`
+);
 program2.parseAsync(process.argv).catch((err) => {
   if (err?.code) {
     console.error(JSON.stringify({ ok: false, error: err.message, code: err.code }));