@neopress/cli 4.0.0 → 4.1.0

package/README.md

@@ -0,0 +1,109 @@
+# @neopress/cli
+
+Manage your [Neopress](https://app.neopress.ai) site from the terminal — pages,
+collections, entries, forms, assets, redirects, analytics, and publishing.
+
+Designed to be driven by humans **and** by AI agents (Claude Code, Codex, etc.):
+every command speaks JSON, and `neopress guide` prints the entire command
+surface in one call.
+
+## Install
+
+```bash
+npm i -g @neopress/cli
+neopress --version
+```
+
+Or run without installing:
+
+```bash
+npx @neopress/cli guide
+```
+
+## Authenticate
+
+Log in once; the session is stored in `~/.config/neopress/tokens.json` and
+refreshed automatically.
+
+```bash
+neopress login            # OAuth in the browser
+neopress whoami           # confirm who you are
+```
+
+For CI or headless agents, skip the browser and pass a token instead:
+
+```bash
+export NEOPRESS_ACCESS_TOKEN="<token>"
+```
+
+## Quickstart
+
+```bash
+neopress sites list               # sites you can access
+neopress sites use <id|handle>    # pick the active site (persisted)
+neopress pages list               # list pages on the active site
+neopress guide                    # full command reference
+```
+
+Target a one-off site without changing the active one:
+
+```bash
+neopress --site my-blog pages list
+```
+
+## Common tasks
+
+```bash
+# Create a page from a TSX file (created as a draft)
+neopress pages create --path /about --title About --tsx ./about.tsx
+
+# Localize a page — JSON options take inline JSON or @file
+neopress pages create --path /about --i18n @i18n.json --public-locales en,ko
+
+# Create and publish a collection entry
+neopress entries create --collection 12 --data @entry.json --title Hello
+neopress entries publish <entryId>
+
+# Preview, then publish the whole site
+neopress publish preview
+neopress publish
+```
+
+Run `neopress <command> --help` for the flags and examples of any command.
+
+## JSON / AI mode
+
+Output is human-readable in a terminal and **automatically switches to JSON when
+piped or redirected**, so it composes with `jq` and tools out of the box:
+
+```bash
+neopress pages list | jq '.data[].path'
+```
+
+Force JSON in a terminal with `--json`. For agents that want the whole CLI in a
+single introspectable payload:
+
+```bash
+neopress guide --json
+```
+
+`neopress guide` is generated from the live command tree, so it never drifts from
+the installed version — treat it as the source of truth for what the CLI can do.
+
+## Configuration
+
+Resolution order for the active site: `--site` flag → `NEOPRESS_SITE_ID` →
+project config file → the site saved by `neopress sites use`.
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `NEOPRESS_ACCESS_TOKEN` | — | Auth token (skips `neopress login`) |
+| `NEOPRESS_SITE_ID` | — | Default site id (overrides the active site) |
+| `NEOPRESS_BASE_URL` | `https://app.neopress.ai` | API base URL (staging/local targets) |
+
+Per-project defaults can also live in `.neopressrc.json` (or
+`.neopress/config.json`):
+
+```json
+{ "siteId": 42, "baseUrl": "https://app.neopress.ai" }
+```

package/dist/bin.cjs

@@ -3652,7 +3652,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);
@@ -24882,6 +24887,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,
@@ -40564,6 +40590,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 +40717,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 +40736,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 +40866,40 @@ 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 use my-site
+Run \`sites use <id|handle>\` to set the active site for all other commands.`);
   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,19 +40908,16 @@ 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 active.`).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) => {
     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`.");
-    }
-    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,
@@ -40802,7 +40935,11 @@ function registerSiteCommands(program3) {
     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("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 +40956,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.");
@@ -40878,7 +41019,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 +41040,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 +41071,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 +41101,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 +41119,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 +41136,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 +41150,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 +41179,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 +41201,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 +41228,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 +41274,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 +41290,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 +41307,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 +41326,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 +41357,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 +41370,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 +41420,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 +41441,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 +41475,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 +41506,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 +41520,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 +41591,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 +41648,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 +41672,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 +41696,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 +41726,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.1.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 +41963,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 }));

package/dist/index.js

@@ -21146,6 +21146,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,
@@ -36828,6 +36849,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;
@@ -36848,6 +36976,7 @@ var NeopressClient = class {
   entryReferences;
   analytics;
   templates;
+  headshots;
   constructor(options) {
     this.baseUrl = (options.baseUrl || "https://app.neopress.ai").replace(/\/$/, "");
     this.accessToken = options.accessToken || "";
@@ -36866,6 +36995,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}`;

package/package.json

@@ -1,15 +1,25 @@
 {
   "name": "@neopress/cli",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "description": "Neopress CLI — manage your Neopress site from the terminal",
   "type": "module",
+  "keywords": [
+    "neopress",
+    "cli",
+    "cms",
+    "headless-cms",
+    "website-builder",
+    "content-management",
+    "ai-agent"
+  ],
   "bin": {
     "neopress": "./dist/bin.cjs"
   },
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "README.md"
   ],
   "publishConfig": {
     "access": "public"