From bc44d2b62fe516a310dd1167a80be4bff3504f8c Mon Sep 17 00:00:00 2001
From: Artur Flis <contact@artur.zone>
Date: Tue, 14 Jul 2026 11:52:53 +0200
Subject: [PATCH 1/6] Change outro message to include a sad face

---
 src/index.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/index.ts b/src/index.ts
index bec3c95..d3cf20e 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -42,7 +42,7 @@ const main = async () => {
     const action = await p.select({ message: t.muted("what do you want to do?"), options })
 
     if (p.isCancel(action) || action === "exit") {
-      p.outro(t.muted("bye"))
+      p.outro(t.muted("bye :C"))
       process.exit(0)
     }
 

From 280364facd70d280355a74cdcbd0e63b73344eb9 Mon Sep 17 00:00:00 2001
From: Fernando Campione <fernandocampione@Fernandos-MacBook-Pro-2.local>
Date: Mon, 21 Sep 2026 16:20:57 +0100
Subject: [PATCH 2/6] add nojs templates to cli

---
 README.md               |  2 ++
 src/generators/theme.ts | 27 +++++++++++++++++++++++++++
 2 files changed, 29 insertions(+)

diff --git a/README.md b/README.md
index 7813408..30f79c5 100644
--- a/README.md
+++ b/README.md
@@ -100,6 +100,8 @@ Every extension gets:
 
 Themes also get `style.css` with all CSS variables pre-filled to the degoog defaults (light and dark), plus a `templates/logo.html` example showing how to override a template section.
 
+The generated theme README also covers the script-free `/nojs` page, which reuses your ordinary templates and takes per-file overrides from a `nojs/` folder by filename instead of through `theme.json`.
+
 Plugin types also have `isClientExposed` already in the template. Set it to `true` if your plugin causes the browser to fetch external URLs directly, `false` if everything goes through the server. Leaving it unset shows a warning badge in degoog settings.
 
 ## Docker Compose
diff --git a/src/generators/theme.ts b/src/generators/theme.ts
index 9f84e77..d0363c0 100644
--- a/src/generators/theme.ts
+++ b/src/generators/theme.ts
@@ -187,6 +187,33 @@ The file contains blocks for \`:root\` (light), \`[data-theme="dark"]\`,
 Templates listed under the \`templates\` key in \`theme.json\` replace individual
 UI sections without touching anything else. Only include keys you want to change.
 
+## The no-JS page
+
+If the instance serves the script-free page at \`/nojs\`, your theme already
+covers it. That page loads the same \`html\` shells and the same \`templates\`
+entries listed above and fills them in on the server, so anything you restyle
+here shows up there.
+
+Only override a section that genuinely cannot work without scripts. Drop a
+\`nojs/<name>.html\` file in your theme folder, no \`theme.json\` entry needed.
+Each name resolves through your \`nojs/\` folder, then degoog's, then your own
+template for that name, then degoog's.
+
+\`\`\`
+nojs/
+  logo.html    tabs.html    pagination.html
+\`\`\`
+
+Those three are the ones degoog itself overrides: a monospace logo, a filter
+form of real \`<select>\`s instead of JS dropdowns, and page links the client
+otherwise builds in code. Everything else is inherited.
+
+You do not need to strip your own scripts. Every template the no-JS page renders
+is sanitised first, \`<script>\` blocks, inline \`on*=\` handlers and module
+preloads removed, and the CSS bot check link is injected for you. Do check what
+a template looks like with its behaviour taken away, because a section that only
+fills in once a script runs will render empty.
+
 ## Static assets
 
 Any file inside your theme folder is served at \`/themes/<theme-id>/<path>\`.

From 2fb45fb4c05e3e017ea3c40e85a0e13d162003a6 Mon Sep 17 00:00:00 2001
From: fccview <f.campioneuk@gmail.com>
Date: Wed, 30 Sep 2026 09:16:12 +0100
Subject: [PATCH 3/6] prepare for next release with all the cool stuff incoming

---
 README.md                             |  3 +-
 src/commands/create.ts                | 34 ++++++++++---------
 src/commands/doctor/checks.ts         |  6 ++--
 src/commands/doctor/detect.ts         |  7 ++--
 src/commands/doctor/index.ts          | 18 +++++-----
 src/commands/doctor/report.ts         |  4 +--
 src/commands/doctor/store-orphans.ts  | 13 ++++----
 src/commands/doctor/store-validate.ts |  4 +--
 src/commands/doctor/store.ts          | 14 ++++----
 src/commands/doctor/types.ts          |  7 ++--
 src/commands/login.ts                 |  6 ++--
 src/commands/search.ts                |  6 ++--
 src/config/store.ts                   |  4 +--
 src/generators/autocomplete.ts        |  4 +--
 src/generators/engine.ts              |  4 +--
 src/generators/favicon.ts             | 48 +++++++++++++++++++++++++++
 src/generators/plugin-bang.ts         |  4 +--
 src/generators/plugin-intercept.ts    |  4 +--
 src/generators/plugin-mid.ts          |  4 +--
 src/generators/plugin-route.ts        |  4 +--
 src/generators/plugin-slot.ts         |  4 +--
 src/generators/plugin-tab.ts          |  4 +--
 src/generators/theme.ts               |  8 ++---
 src/generators/transport.ts           |  4 +--
 src/index.ts                          | 12 +++----
 src/prompts/ext-type.ts               |  3 +-
 src/types/index.ts                    |  1 +
 src/utils/api.ts                      |  4 +--
 src/utils/files.ts                    |  4 +--
 src/utils/logger.ts                   |  2 +-
 src/utils/prompts.ts                  |  2 +-
 src/utils/store.ts                    | 10 +++---
 32 files changed, 157 insertions(+), 99 deletions(-)
 create mode 100644 src/generators/favicon.ts

diff --git a/README.md b/README.md
index 30f79c5..d76888e 100644
--- a/README.md
+++ b/README.md
@@ -82,6 +82,7 @@ Any flag you omit will still be asked interactively. Available types:
 | `engine`            | Custom search engine                                        |
 | `transport`         | Custom HTTP fetch strategy                                  |
 | `autocomplete`      | Search suggestions provider                                 |
+| `favicon`           | Favicon provider for search results                         |
 | `theme`             | UI theme with CSS variables and optional template overrides |
 | `plugin-bang`       | Bang command (`!trigger query`)                             |
 | `plugin-slot`       | Panel injected into search results                          |
@@ -94,7 +95,7 @@ Any flag you omit will still be asked interactively. Available types:
 
 Every extension gets:
 
-- `index.ts` - entry file pre-filled with the correct contract for the type you picked
+- `index.ts` - entry file pre-filled with the correct contract for the type you picked (favicon providers get `index.js`, matching the official store)
 - `README.md` - fill this in, it shows as docs on the extension's settings page
 - `author.json` - auto-filled from your login details
 
diff --git a/src/commands/create.ts b/src/commands/create.ts
index 09b57ae..59e198b 100644
--- a/src/commands/create.ts
+++ b/src/commands/create.ts
@@ -1,26 +1,27 @@
 import * as p from "@clack/prompts";
 import { join } from "node:path";
-import { ExtType, type GeneratorCtx } from "../types/index.ts";
-import { promptExtType } from "../prompts/ext-type.ts";
-import { generateEngine } from "../generators/engine.ts";
-import { generateTransport } from "../generators/transport.ts";
-import { generateAutocomplete } from "../generators/autocomplete.ts";
-import { generateTheme } from "../generators/theme.ts";
-import { generatePluginBang } from "../generators/plugin-bang.ts";
-import { generatePluginSlot } from "../generators/plugin-slot.ts";
-import { generatePluginTab } from "../generators/plugin-tab.ts";
-import { generatePluginIntercept } from "../generators/plugin-intercept.ts";
-import { generatePluginMid } from "../generators/plugin-mid.ts";
-import { generatePluginRoute } from "../generators/plugin-route.ts";
-import { loadConfig } from "../config/store.ts";
-import { argv } from "../utils/argv.ts";
+import { ExtType, type GeneratorCtx } from "../types";
+import { promptExtType } from "../prompts/ext-type";
+import { generateEngine } from "../generators/engine";
+import { generateTransport } from "../generators/transport";
+import { generateAutocomplete } from "../generators/autocomplete";
+import { generateFavicon } from "../generators/favicon";
+import { generateTheme } from "../generators/theme";
+import { generatePluginBang } from "../generators/plugin-bang";
+import { generatePluginSlot } from "../generators/plugin-slot";
+import { generatePluginTab } from "../generators/plugin-tab";
+import { generatePluginIntercept } from "../generators/plugin-intercept";
+import { generatePluginMid } from "../generators/plugin-mid";
+import { generatePluginRoute } from "../generators/plugin-route";
+import { loadConfig } from "../config/store";
+import { argv } from "../utils/argv";
 import {
   extTypeToCategory,
   findStoreRoot,
   registerExtensionInStore,
   scaffoldStore,
-} from "../utils/store.ts";
-import { t } from "../utils/theme.ts";
+} from "../utils/store";
+import { t } from "../utils/theme";
 
 const SLUG_RE = /^[a-z][a-z0-9-]*$/;
 
@@ -30,6 +31,7 @@ const GENERATORS: Record<ExtType, (ctx: GeneratorCtx) => Promise<string>> = {
   [ExtType.Engine]: generateEngine,
   [ExtType.Transport]: generateTransport,
   [ExtType.Autocomplete]: generateAutocomplete,
+  [ExtType.Favicon]: generateFavicon,
   [ExtType.Theme]: generateTheme,
   [ExtType.PluginBang]: generatePluginBang,
   [ExtType.PluginSlot]: generatePluginSlot,
diff --git a/src/commands/doctor/checks.ts b/src/commands/doctor/checks.ts
index ebd869e..5fb47cb 100644
--- a/src/commands/doctor/checks.ts
+++ b/src/commands/doctor/checks.ts
@@ -1,8 +1,8 @@
 import { readFile, writeFile, readdir } from "node:fs/promises"
 import { join, basename } from "node:path"
-import { exists } from "./detect.ts"
-import { findStoreRoot } from "../../utils/store.ts"
-import type { CheckResult, ExtensionKind, RunSummary } from "./types.ts"
+import { exists } from "./detect"
+import { findStoreRoot } from "../../utils/store"
+import type { CheckResult, ExtensionKind, RunSummary } from "./types"
 
 const readJson = async <T>(path: string): Promise<T | null> => {
   try {
diff --git a/src/commands/doctor/detect.ts b/src/commands/doctor/detect.ts
index 2d27adc..79c1a76 100644
--- a/src/commands/doctor/detect.ts
+++ b/src/commands/doctor/detect.ts
@@ -1,7 +1,7 @@
 import { join, basename, dirname } from "node:path"
-import { exists } from "../../utils/files.ts"
-import { readStoreManifest } from "../../utils/store.ts"
-import type { ExtensionKind, Target } from "./types.ts"
+import { exists } from "../../utils/files"
+import { readStoreManifest } from "../../utils/store"
+import type { ExtensionKind, Target } from "./types"
 
 export { exists }
 
@@ -11,6 +11,7 @@ const KIND_FROM_FOLDER: Record<string, ExtensionKind> = {
   engines: "engine",
   transports: "transport",
   autocomplete: "autocomplete",
+  favicon: "favicon",
 }
 
 const detectKindFromParent = (dir: string): ExtensionKind => {
diff --git a/src/commands/doctor/index.ts b/src/commands/doctor/index.ts
index 961229f..237d718 100644
--- a/src/commands/doctor/index.ts
+++ b/src/commands/doctor/index.ts
@@ -1,13 +1,13 @@
 import { resolve } from "node:path"
 import * as p from "@clack/prompts"
-import { t } from "../../utils/theme.ts"
-import { logger } from "../../utils/logger.ts"
-import { promptText, promptConfirm } from "../../utils/prompts.ts"
-import { exists, detectTarget } from "./detect.ts"
-import { runChecks } from "./checks.ts"
-import { runStoreChecks } from "./store.ts"
-import { printResults } from "./report.ts"
-import type { StoreRunSummary } from "./types.ts"
+import { t } from "../../utils/theme"
+import { logger } from "../../utils/logger"
+import { promptText, promptConfirm } from "../../utils/prompts"
+import { exists, detectTarget } from "./detect"
+import { runChecks } from "./checks"
+import { runStoreChecks } from "./store"
+import { printResults } from "./report"
+import type { StoreRunSummary } from "./types"
 
 type ParsedArgs = {
   pathArg: string | undefined
@@ -56,7 +56,7 @@ export const doctorCmd = async (): Promise<void> => {
     logger.error(
       `not a recognisable extension or store: ${targetDir}\n` +
         "  - an extension has theme.json or index.{ts,js}\n" +
-        "  - a store has a package.json with plugins/themes/engines/transports/autocomplete arrays",
+        "  - a store has a package.json with plugins/themes/engines/transports/autocomplete/favicon arrays",
     )
     process.exit(1)
   }
diff --git a/src/commands/doctor/report.ts b/src/commands/doctor/report.ts
index d9fd8a9..3b7d25a 100644
--- a/src/commands/doctor/report.ts
+++ b/src/commands/doctor/report.ts
@@ -1,5 +1,5 @@
-import { t } from "../../utils/theme.ts"
-import type { CheckResult, CheckStatus } from "./types.ts"
+import { t } from "../../utils/theme"
+import type { CheckResult, CheckStatus } from "./types"
 
 const PASS = t.success("PASS")
 const FAIL = t.danger("FAIL")
diff --git a/src/commands/doctor/store-orphans.ts b/src/commands/doctor/store-orphans.ts
index 8dc4696..e06680f 100644
--- a/src/commands/doctor/store-orphans.ts
+++ b/src/commands/doctor/store-orphans.ts
@@ -1,11 +1,11 @@
 import { readdir, stat } from "node:fs/promises"
 import { join, basename } from "node:path"
 import * as p from "@clack/prompts"
-import { t } from "../../utils/theme.ts"
-import { promptConfirm, promptSelect } from "../../utils/prompts.ts"
-import { exists } from "./detect.ts"
-import type { ExtensionCategory, StoreEntry } from "./types.ts"
-import { PLUGIN_TYPES, type PluginType } from "./types.ts"
+import { t } from "../../utils/theme"
+import { promptConfirm, promptSelect } from "../../utils/prompts"
+import { exists } from "./detect"
+import type { ExtensionCategory, StoreEntry } from "./types"
+import { EXTENSION_CATEGORIES, PLUGIN_TYPES, type PluginType } from "./types"
 
 export type Orphan = {
   category: ExtensionCategory
@@ -55,8 +55,7 @@ export const collectOrphans = async (
   manifest: { [K in ExtensionCategory]?: StoreEntry[] },
 ): Promise<Orphan[]> => {
   const orphans: Orphan[] = []
-  const categories: ExtensionCategory[] = ["plugins", "themes", "engines", "transports", "autocomplete"]
-  for (const category of categories) {
+  for (const category of EXTENSION_CATEGORIES) {
     const entries = manifest[category] ?? []
     const found = await listOrphansInCategory(storeDir, category, entries)
     for (const relPath of found) orphans.push({ category, relPath })
diff --git a/src/commands/doctor/store-validate.ts b/src/commands/doctor/store-validate.ts
index 4e4e8fd..f072397 100644
--- a/src/commands/doctor/store-validate.ts
+++ b/src/commands/doctor/store-validate.ts
@@ -1,7 +1,7 @@
 import { stat } from "node:fs/promises"
 import { join } from "node:path"
-import { exists } from "./detect.ts"
-import type { CheckResult, ExtensionCategory, StoreEntry, StoreManifest } from "./types.ts"
+import { exists } from "./detect"
+import type { CheckResult, ExtensionCategory, StoreEntry, StoreManifest } from "./types"
 
 export const validateTopLevel = (manifest: StoreManifest): CheckResult[] => {
   const results: CheckResult[] = []
diff --git a/src/commands/doctor/store.ts b/src/commands/doctor/store.ts
index cfcac4f..96ef94b 100644
--- a/src/commands/doctor/store.ts
+++ b/src/commands/doctor/store.ts
@@ -1,17 +1,17 @@
 import { writeFile } from "node:fs/promises"
 import { join, basename } from "node:path"
 import * as p from "@clack/prompts"
-import { t } from "../../utils/theme.ts"
-import { exists } from "./detect.ts"
-import { runChecks } from "./checks.ts"
-import { printResults } from "./report.ts"
+import { t } from "../../utils/theme"
+import { exists } from "./detect"
+import { runChecks } from "./checks"
+import { printResults } from "./report"
 import {
   validateTopLevel,
   validateEntry,
   validatePathExistence,
   findDuplicateEntries,
-} from "./store-validate.ts"
-import { collectOrphans, resolveOrphans } from "./store-orphans.ts"
+} from "./store-validate"
+import { collectOrphans, resolveOrphans } from "./store-orphans"
 import {
   EXTENSION_CATEGORIES,
   CATEGORY_TO_KIND,
@@ -20,7 +20,7 @@ import {
   type StoreEntry,
   type StoreManifest,
   type StoreRunSummary,
-} from "./types.ts"
+} from "./types"
 
 const writeManifest = async (path: string, manifest: StoreManifest): Promise<void> => {
   await writeFile(path, JSON.stringify(manifest, null, 2) + "\n", "utf-8")
diff --git a/src/commands/doctor/types.ts b/src/commands/doctor/types.ts
index 3f3edcd..b2df5e4 100644
--- a/src/commands/doctor/types.ts
+++ b/src/commands/doctor/types.ts
@@ -6,9 +6,9 @@ export type CheckResult = {
   detail?: string | undefined
 }
 
-export type ExtensionKind = "theme" | "plugin" | "engine" | "transport" | "autocomplete" | "unknown"
+export type ExtensionKind = "theme" | "plugin" | "engine" | "transport" | "autocomplete" | "favicon" | "unknown"
 
-export type ExtensionCategory = "themes" | "plugins" | "engines" | "transports" | "autocomplete"
+export type ExtensionCategory = "themes" | "plugins" | "engines" | "transports" | "autocomplete" | "favicon"
 
 export const EXTENSION_CATEGORIES: ExtensionCategory[] = [
   "plugins",
@@ -16,6 +16,7 @@ export const EXTENSION_CATEGORIES: ExtensionCategory[] = [
   "engines",
   "transports",
   "autocomplete",
+  "favicon",
 ]
 
 export const CATEGORY_TO_KIND: Record<ExtensionCategory, Exclude<ExtensionKind, "unknown">> = {
@@ -24,6 +25,7 @@ export const CATEGORY_TO_KIND: Record<ExtensionCategory, Exclude<ExtensionKind,
   engines: "engine",
   transports: "transport",
   autocomplete: "autocomplete",
+  favicon: "favicon",
 }
 
 export const PLUGIN_TYPES = ["command", "slot", "interceptor", "search-result-tab"] as const
@@ -50,6 +52,7 @@ export type StoreManifest = {
   engines?: StoreEntry[]
   transports?: StoreEntry[]
   autocomplete?: StoreEntry[]
+  favicon?: StoreEntry[]
 } & Record<string, unknown>
 
 export type Target =
diff --git a/src/commands/login.ts b/src/commands/login.ts
index 33bd8c5..ae4ccfd 100644
--- a/src/commands/login.ts
+++ b/src/commands/login.ts
@@ -1,7 +1,7 @@
 import * as p from "@clack/prompts"
-import { loadConfig, saveConfig } from "../config/store.ts"
-import { logger } from "../utils/logger.ts"
-import type { Config } from "../types/index.ts"
+import { loadConfig, saveConfig } from "../config/store"
+import { logger } from "../utils/logger"
+import type { Config } from "../types"
 
 const isValidUrl = (val: string) => {
   if (!val) return undefined
diff --git a/src/commands/search.ts b/src/commands/search.ts
index c05702e..8c1a417 100644
--- a/src/commands/search.ts
+++ b/src/commands/search.ts
@@ -1,7 +1,7 @@
 import * as p from "@clack/prompts";
-import { loadConfig } from "../config/store.ts";
-import { apiGet } from "../utils/api.ts";
-import { t } from "../utils/theme.ts";
+import { loadConfig } from "../config/store";
+import { apiGet } from "../utils/api";
+import { t } from "../utils/theme";
 
 type Result = {
   title: string;
diff --git a/src/config/store.ts b/src/config/store.ts
index d562eb9..8786290 100644
--- a/src/config/store.ts
+++ b/src/config/store.ts
@@ -1,8 +1,8 @@
 import { readFile, writeFile, mkdir } from "node:fs/promises"
 import { join, dirname } from "node:path"
 import { homedir } from "node:os"
-import { logger } from "../utils/logger.ts"
-import type { Config } from "../types/index.ts"
+import { logger } from "../utils/logger"
+import type { Config } from "../types"
 
 const CONFIG_BASE = process.env.DEGOOG_CONFIG_HOME ?? join(homedir(), ".config", "degoog")
 const CONFIG_PATH = join(CONFIG_BASE, "config.json")
diff --git a/src/generators/autocomplete.ts b/src/generators/autocomplete.ts
index 5adb877..49de386 100644
--- a/src/generators/autocomplete.ts
+++ b/src/generators/autocomplete.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = (name: string) => `type RichSuggestion = {
   description?: string
diff --git a/src/generators/engine.ts b/src/generators/engine.ts
index 065edee..9fef034 100644
--- a/src/generators/engine.ts
+++ b/src/generators/engine.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts";
-import type { GeneratorCtx } from "../types/index.ts";
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files";
+import type { GeneratorCtx } from "../types";
 
 const indexTpl = (name: string) => `export const type = "web" // string or array - e.g. "web", "books", ["web", "any-type"]
 
diff --git a/src/generators/favicon.ts b/src/generators/favicon.ts
new file mode 100644
index 0000000..a70566a
--- /dev/null
+++ b/src/generators/favicon.ts
@@ -0,0 +1,48 @@
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
+
+const toClassName = (name: string): string =>
+  name
+    .split("-")
+    .filter(Boolean)
+    .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+    .join("") + "FaviconProvider"
+
+const indexTpl = (name: string) => `export default class ${toClassName(name)} {
+  name = "${name}";
+  description = "Favicons for search results.";
+
+  settingsSchema = [
+    {
+      key: "endpoint",
+      label: "Endpoint",
+      type: "url",
+      default: "https://icons.example.com",
+      description: "Base URL of the favicon service.",
+    },
+  ];
+
+  endpoint = "https://icons.example.com";
+
+  configure(settings) {
+    if (typeof settings.endpoint === "string" && settings.endpoint.trim()) {
+      this.endpoint = settings.endpoint.trim().replace(/\\/+$/, "");
+    }
+  }
+
+  async getFavicon(host, context) {
+    if (!host) return null;
+    const size = context?.size ?? 32;
+    return {
+      url: \`\${this.endpoint}/\${encodeURIComponent(host)}.png?size=\${size}\`,
+    };
+  }
+}
+`
+
+export const generateFavicon = async (ctx: GeneratorCtx): Promise<string> =>
+  scaffoldDir(ctx.outDir, ctx.name, {
+    "index.js": indexTpl(ctx.name),
+    "README.md": readmeTpl(ctx.name, "A custom favicon provider for degoog."),
+    "author.json": authorJsonTpl(ctx.config),
+  })
diff --git a/src/generators/plugin-bang.ts b/src/generators/plugin-bang.ts
index 332745c..17fc0ed 100644
--- a/src/generators/plugin-bang.ts
+++ b/src/generators/plugin-bang.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = (name: string) => `// If this file also exports other hooks (slot, interceptor, tab, etc.) and
 // you want a single settings card for all of them, add a top-level plugin identity:
diff --git a/src/generators/plugin-intercept.ts b/src/generators/plugin-intercept.ts
index 3faf9c6..23a62fb 100644
--- a/src/generators/plugin-intercept.ts
+++ b/src/generators/plugin-intercept.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = (name: string) => `// If this file also exports a slot or command and you want a single settings
 // card for all of them, add a top-level plugin identity export:
diff --git a/src/generators/plugin-mid.ts b/src/generators/plugin-mid.ts
index 720800a..016578f 100644
--- a/src/generators/plugin-mid.ts
+++ b/src/generators/plugin-mid.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = (name: string) => `// If this file also exports other hooks (slot, interceptor, command, etc.) and
 // you want a single settings card for all of them, add a top-level plugin identity:
diff --git a/src/generators/plugin-route.ts b/src/generators/plugin-route.ts
index fc78310..ed14c95 100644
--- a/src/generators/plugin-route.ts
+++ b/src/generators/plugin-route.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = () => `// Routes are served at /api/plugin/<pluginId>/<path>, where <pluginId> is the
 // installed folder ID assigned by degoog (e.g. <author>-<repo>-<plugin>). Never
diff --git a/src/generators/plugin-slot.ts b/src/generators/plugin-slot.ts
index c9b6bcd..e9cf8e7 100644
--- a/src/generators/plugin-slot.ts
+++ b/src/generators/plugin-slot.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = (name: string) => `// If this file also exports other hooks (interceptor, command, tab, etc.) and
 // you want a single settings card for all of them, add a top-level plugin identity:
diff --git a/src/generators/plugin-tab.ts b/src/generators/plugin-tab.ts
index 269a84f..3b3599a 100644
--- a/src/generators/plugin-tab.ts
+++ b/src/generators/plugin-tab.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = (name: string) => `// If this file also exports other hooks (slot, interceptor, command, etc.) and
 // you want a single settings card for all of them, add a top-level plugin identity:
diff --git a/src/generators/theme.ts b/src/generators/theme.ts
index d0363c0..4a9c525 100644
--- a/src/generators/theme.ts
+++ b/src/generators/theme.ts
@@ -1,7 +1,7 @@
 import * as p from "@clack/prompts"
-import { scaffoldDir, authorJsonTpl } from "../utils/files.ts"
-import { t } from "../utils/theme.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl } from "../utils/files"
+import { t } from "../utils/theme"
+import type { GeneratorCtx } from "../types"
 import {
   layoutHtml, indexHtml, searchHtml, html404,
   gandalfHtml, robotsHtml,
@@ -9,7 +9,7 @@ import {
   srchHeaderHtml, srchTabsHtml, srchResultHtml,
   srchImageCardHtml, srchVideoCardHtml,
   srchMediaPreviewHtml, srchLightboxHtml, srchAtAGlanceHtml,
-} from "../templates/theme-assets.ts"
+} from "../templates/theme-assets"
 import { HTMLBundle } from "bun"
 
 export const HTML_PAGE_KEYS = ["layout", "index", "search", "404", "gandalf", "robots-takeover"] as const
diff --git a/src/generators/transport.ts b/src/generators/transport.ts
index bee97ee..1f62dd6 100644
--- a/src/generators/transport.ts
+++ b/src/generators/transport.ts
@@ -1,5 +1,5 @@
-import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files.ts"
-import type { GeneratorCtx } from "../types/index.ts"
+import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
+import type { GeneratorCtx } from "../types"
 
 const indexTpl = (name: string) => `export const transport = {
   name: "${name}",
diff --git a/src/index.ts b/src/index.ts
index d3cf20e..2b7c695 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -1,10 +1,10 @@
 import * as p from "@clack/prompts"
-import { loginCmd } from "./commands/login.ts"
-import { createCmd } from "./commands/create.ts"
-import { searchCmd } from "./commands/search.ts"
-import { doctorCmd } from "./commands/doctor/index.ts"
-import { title, t } from "./utils/theme.ts"
-import { checkLatest, VERSION, updateCmd } from "./utils/version.ts"
+import { loginCmd } from "./commands/login"
+import { createCmd } from "./commands/create"
+import { searchCmd } from "./commands/search"
+import { doctorCmd } from "./commands/doctor"
+import { title, t } from "./utils/theme"
+import { checkLatest, VERSION, updateCmd } from "./utils/version"
 
 const SUBCOMMANDS: Record<string, () => Promise<void>> = {
   create: async () => { await createCmd() },
diff --git a/src/prompts/ext-type.ts b/src/prompts/ext-type.ts
index 1230c00..87dadc4 100644
--- a/src/prompts/ext-type.ts
+++ b/src/prompts/ext-type.ts
@@ -1,5 +1,5 @@
 import * as p from "@clack/prompts"
-import { ExtType } from "../types/index.ts"
+import { ExtType } from "../types"
 
 type SelectOption = { value: string; label: string; hint?: string }
 
@@ -16,6 +16,7 @@ const TOP_LEVEL: SelectOption[] = [
   { value: ExtType.Engine, label: "Engine", hint: "custom search engine" },
   { value: ExtType.Transport, label: "Transport", hint: "custom HTTP fetch strategy" },
   { value: ExtType.Autocomplete, label: "Autocomplete Provider", hint: "search suggestions" },
+  { value: ExtType.Favicon, label: "Favicon Provider", hint: "result favicons" },
   { value: ExtType.Theme, label: "Theme", hint: "UI theme with CSS and templates" },
   { value: "plugin", label: "Plugin", hint: "bang command, slot, tab, interceptor, middleware or route" },
 ]
diff --git a/src/types/index.ts b/src/types/index.ts
index a4dc814..e7b843b 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -2,6 +2,7 @@ export enum ExtType {
   Engine = "engine",
   Transport = "transport",
   Autocomplete = "autocomplete",
+  Favicon = "favicon",
   Theme = "theme",
   PluginBang = "plugin-bang",
   PluginSlot = "plugin-slot",
diff --git a/src/utils/api.ts b/src/utils/api.ts
index 39b3a40..4e652e4 100644
--- a/src/utils/api.ts
+++ b/src/utils/api.ts
@@ -1,5 +1,5 @@
-import type { Config } from "../types/index.ts"
-import { logger } from "./logger.ts"
+import type { Config } from "../types"
+import { logger } from "./logger"
 
 type ApiResult<T> =
   | { ok: true; data: T }
diff --git a/src/utils/files.ts b/src/utils/files.ts
index 74a6ecd..bd05de3 100644
--- a/src/utils/files.ts
+++ b/src/utils/files.ts
@@ -1,7 +1,7 @@
 import { mkdir, writeFile, access } from "node:fs/promises"
 import { join, resolve, dirname } from "node:path"
-import { logger } from "./logger.ts"
-import type { Config } from "../types/index.ts"
+import { logger } from "./logger"
+import type { Config } from "../types"
 import { HTMLBundle } from "bun"
 
 export const mkdirp = async (dir: string) => {
diff --git a/src/utils/logger.ts b/src/utils/logger.ts
index 6fa4f55..b1fbda5 100644
--- a/src/utils/logger.ts
+++ b/src/utils/logger.ts
@@ -1,4 +1,4 @@
-import { t } from "./theme.ts"
+import { t } from "./theme"
 
 export const logger = {
   info:    (msg: string) => console.log(`${t.muted("info")}  ${msg}`),
diff --git a/src/utils/prompts.ts b/src/utils/prompts.ts
index be1e9c7..93e26ef 100644
--- a/src/utils/prompts.ts
+++ b/src/utils/prompts.ts
@@ -1,5 +1,5 @@
 import * as p from "@clack/prompts"
-import { t } from "./theme.ts"
+import { t } from "./theme"
 import { Option } from "@clack/prompts"
 
 const exitCancelled = (): never => {
diff --git a/src/utils/store.ts b/src/utils/store.ts
index 739f7ec..d5380c1 100644
--- a/src/utils/store.ts
+++ b/src/utils/store.ts
@@ -6,10 +6,10 @@ import {
   type PluginType,
   type StoreEntry,
   type StoreManifest,
-} from "../commands/doctor/types.ts"
-import { ExtType, type Config } from "../types/index.ts"
-import { exists, mkdirp } from "./files.ts"
-import { logger } from "./logger.ts"
+} from "../commands/doctor/types"
+import { ExtType, type Config } from "../types"
+import { exists, mkdirp } from "./files"
+import { logger } from "./logger"
 
 export type StoreRoot = {
   dir: string
@@ -47,6 +47,7 @@ const EXT_TYPE_CATEGORY: Record<ExtType, ExtensionCategory> = {
   [ExtType.Engine]: "engines",
   [ExtType.Transport]: "transports",
   [ExtType.Autocomplete]: "autocomplete",
+  [ExtType.Favicon]: "favicon",
   [ExtType.Theme]: "themes",
   [ExtType.PluginBang]: "plugins",
   [ExtType.PluginSlot]: "plugins",
@@ -114,6 +115,7 @@ export const scaffoldStore = async (dir: string, config: Config): Promise<void>
     engines: [],
     transports: [],
     autocomplete: [],
+    favicon: [],
   }
 
   const manifestPath = join(resolved, "package.json")

From 8f05141b4ae0a86c7a1c19529e33cc6bfd4af4e7 Mon Sep 17 00:00:00 2001
From: fccview <f.campioneuk@gmail.com>
Date: Wed, 30 Sep 2026 19:29:18 +0100
Subject: [PATCH 4/6] update cli to kickass

---
 README.md                             |  29 ++++++-
 src/commands/create.ts                |  70 +++++++++++++++--
 src/commands/doctor/checks.ts         |  76 ++++++++++++++++++-
 src/commands/doctor/index.ts          |  30 ++++----
 src/commands/doctor/store-orphans.ts  |  44 ++++++++---
 src/commands/doctor/store-validate.ts |  44 ++++++++++-
 src/commands/doctor/store.ts          |  15 ++--
 src/commands/doctor/types.ts          |   4 +
 src/commands/login.ts                 |  38 +++++++++-
 src/commands/search.ts                |  85 ++++++++++++++++++---
 src/generators/engine.ts              |   6 +-
 src/generators/theme.ts               |  55 ++++++++------
 src/generators/transport.ts           |   6 +-
 src/index.ts                          |  64 +++++++++++++++-
 src/types/index.ts                    |   3 +
 src/utils/argv.ts                     | 105 ++++++++++++++++++++++++--
 src/utils/headless.ts                 |  19 +++++
 src/utils/prompts.ts                  |   8 ++
 src/utils/store.ts                    |  13 +++-
 src/utils/theme.ts                    |  13 +++-
 src/utils/ui.ts                       |  39 ++++++++++
 21 files changed, 666 insertions(+), 100 deletions(-)
 create mode 100644 src/utils/headless.ts
 create mode 100644 src/utils/ui.ts

diff --git a/README.md b/README.md
index d76888e..7e774d8 100644
--- a/README.md
+++ b/README.md
@@ -75,7 +75,7 @@ Select **Create extension** from the menu and follow the prompts, or skip them w
 degoog-cli create --name my-engine --type engine --out ./extensions
 ```
 
-Any flag you omit will still be asked interactively. Available types:
+Any flag you omit will still be asked interactively, unless the CLI is running headless (see below). Available types:
 
 | Type                | What it is                                                  |
 | ------------------- | ----------------------------------------------------------- |
@@ -105,6 +105,33 @@ The generated theme README also covers the script-free `/nojs` page, which reuse
 
 Plugin types also have `isClientExposed` already in the template. Set it to `true` if your plugin causes the browser to fetch external URLs directly, `false` if everything goes through the server. Leaving it unset shows a warning badge in degoog settings.
 
+Engines ask whether the site puts an Anubis proof-of-work page in front of its results. Answer yes and the template sets `challenges: ["anubis"]`, so degoog solves the page before your engine reads the response. Inside a store, the package.json entry also gets `minDegoogVersion: "1.0.0"`, because degoog solves these pages from 1.0.0 onwards.
+
+Transports ask whether they drive a real browser that gets through proof-of-work pages. Answer yes and the template sets `handlesChallenges: true`, so degoog leaves those pages to the engine.
+
+Doctor checks both values. It fails on an unknown `challenges` kind or a `handlesChallenges` that isn't `true` or `false`, and warns when an engine with `challenges` has a `minDegoogVersion` below 1.0.0.
+
+## Running without prompts
+
+Every command also runs with no interactive UI, for scripts, CI, or piping. The CLI goes headless when you pass `-y` / `--yes`, when stdin or stdout is not a terminal, or when `CI` or `DEGOOG_HEADLESS=1` is set. Headless runs never prompt: they read flags, fall back to defaults, and exit `1` when a required value is missing or a check fails. Colours are dropped when output is not a terminal, or with `--no-color` / `NO_COLOR`.
+
+```sh
+degoog-cli login --yes --instance-url https://search.example.com --api-key "$DEGOOG_API_KEY" --username "Jane Dev"
+degoog-cli create --yes --name my-engine --type engine --challenges
+degoog-cli create --yes --name my-theme --type theme --init-store --include css,home-logo
+degoog-cli search --json --limit 5 "degoog extensions"
+degoog-cli doctor ./my-store --fix --plugin-type command
+```
+
+| Command  | Flags                                                                                                                                       | Headless defaults                                                                             |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
+| `create` | `--name`, `--type`, `--out`, `--init-store`, `--challenges`, `--handles-challenges`, `--include <parts\|all>`                               | `--name` and `--type` are required. Output goes to the detected store category, otherwise `.` |
+| `search` | `<query>`, `--json`, `--limit <n>`                                                                                                          | Query is required. `--json` always skips the result browser                                   |
+| `login`  | `--instance-url` (or `DEGOOG_INSTANCE_URL`), `--api-key` (or `DEGOOG_API_KEY`), `--username`, `--website`                                   | Only the values you pass are changed                                                          |
+| `doctor` | `[path]`, `--fix`, `--plugin-type <command\|slot\|interceptor\|search-result-tab>`                                                          | Path defaults to the current directory. Orphan folders are only registered with `--fix`       |
+
+Boolean flags accept `--flag=false`. Themes created headless without `--include` get `css` only. Orphan plugin folders are skipped unless `--plugin-type` is given, since doctor cannot guess their type. Run `degoog-cli --help` for the full list.
+
 ## Docker Compose
 
 If you prefer compose over the wrapper script:
diff --git a/src/commands/create.ts b/src/commands/create.ts
index 59e198b..8ff2f42 100644
--- a/src/commands/create.ts
+++ b/src/commands/create.ts
@@ -6,7 +6,7 @@ import { generateEngine } from "../generators/engine";
 import { generateTransport } from "../generators/transport";
 import { generateAutocomplete } from "../generators/autocomplete";
 import { generateFavicon } from "../generators/favicon";
-import { generateTheme } from "../generators/theme";
+import { generateTheme, THEME_PARTS } from "../generators/theme";
 import { generatePluginBang } from "../generators/plugin-bang";
 import { generatePluginSlot } from "../generators/plugin-slot";
 import { generatePluginTab } from "../generators/plugin-tab";
@@ -22,6 +22,8 @@ import {
   scaffoldStore,
 } from "../utils/store";
 import { t } from "../utils/theme";
+import { ui } from "../utils/ui";
+import { isHeadless, fail } from "../utils/headless";
 
 const SLUG_RE = /^[a-z][a-z0-9-]*$/;
 
@@ -51,11 +53,13 @@ const resolveOutDir = async (
   let store = await findStoreRoot(process.cwd());
 
   if (store) {
-    p.log.info(t.muted(`store detected — creating in ${category}/`));
+    ui.info(t.muted(`store detected — creating in ${category}/`));
     return join(store.dir, category);
   }
 
-  const setup = await p.confirm({
+  if (isHeadless && !argv.initStore) return ".";
+
+  const setup = argv.initStore || await p.confirm({
     message: "No store detected. Set up a store in the current directory?",
     initialValue: true,
   });
@@ -65,7 +69,7 @@ const resolveOutDir = async (
     await scaffoldStore(process.cwd(), config);
     store = await findStoreRoot(process.cwd());
     if (store) {
-      p.log.info(t.muted(`store created — creating in ${category}/`));
+      ui.info(t.muted(`store created — creating in ${category}/`));
       return join(store.dir, category);
     }
   }
@@ -78,11 +82,37 @@ const resolveOutDir = async (
   return input || ".";
 };
 
+const parseThemeParts = (): string[] | undefined => {
+  if (argv.include === undefined) return undefined
+  const parts = argv.include.split(",").map((s) => s.trim()).filter(Boolean)
+  if (parts.includes("all")) return THEME_PARTS
+  const unknown = parts.filter((s) => !THEME_PARTS.includes(s))
+  if (unknown.length) {
+    fail(`unknown --include value(s): ${unknown.join(", ")}. Valid: all, ${THEME_PARTS.join(", ")}`)
+  }
+  return parts
+}
+
+const askConfirm = async (
+  preset: boolean | undefined,
+  message: string,
+): Promise<boolean | null> => {
+  if (preset !== undefined) return preset
+  if (isHeadless) return false
+  const picked = await p.confirm({ message, initialValue: false })
+  if (p.isCancel(picked)) return null
+  return picked
+}
+
 export const createCmd = async () => {
   let name: string
 
   if (argv.name && SLUG_RE.test(argv.name)) {
     name = argv.name
+  } else if (isHeadless) {
+    return fail(argv.name
+      ? `invalid --name "${argv.name}": lowercase letters, numbers and hyphens only`
+      : "--name is required when running without a terminal")
   } else {
     const input = await p.text({
       message: "Extension name",
@@ -101,26 +131,52 @@ export const createCmd = async () => {
 
   if (argv.type && VALID_TYPES.includes(argv.type)) {
     extType = argv.type as ExtType
+  } else if (isHeadless) {
+    return fail(`${argv.type ? `invalid --type "${argv.type}"` : "--type is required when running without a terminal"}. Valid: ${VALID_TYPES.join(", ")}`)
   } else {
     const picked = await promptExtType()
     if (!picked) return
     extType = picked
   }
 
+  let challenges = false
+  let handlesChallenges = false
+
+  if (extType === ExtType.Engine) {
+    const picked = await askConfirm(
+      argv.challenges,
+      "Does the site put an Anubis proof-of-work page in front of its results?",
+    )
+    if (picked === null) return
+    challenges = picked
+  }
+
+  if (extType === ExtType.Transport) {
+    const picked = await askConfirm(
+      argv.handlesChallenges,
+      "Does this transport drive a real browser that gets through proof-of-work pages?",
+    )
+    if (picked === null) return
+    handlesChallenges = picked
+  }
+
+  const themeParts = extType === ExtType.Theme ? parseThemeParts() : undefined
+
   const config = await loadConfig()
   const outDir = await resolveOutDir(extType, config)
   if (!outDir) return
 
-  const ctx: GeneratorCtx = { name, outDir, config }
+  const ctx: GeneratorCtx = { name, outDir, config, challenges, handlesChallenges }
+  if (themeParts) ctx.themeParts = themeParts
 
   const createdPath = await GENERATORS[extType](ctx)
 
   const store = await findStoreRoot(createdPath)
   if (store) {
-    await registerExtensionInStore(store.dir, name, extType)
+    await registerExtensionInStore(store.dir, name, extType, challenges)
   }
 
-  p.note(
+  ui.note(
     `That's it, you now have a sexy template for your extension. Have fun making it your own!`,
     "done",
   )
diff --git a/src/commands/doctor/checks.ts b/src/commands/doctor/checks.ts
index 5fb47cb..7288dbe 100644
--- a/src/commands/doctor/checks.ts
+++ b/src/commands/doctor/checks.ts
@@ -2,7 +2,7 @@ import { readFile, writeFile, readdir } from "node:fs/promises"
 import { join, basename } from "node:path"
 import { exists } from "./detect"
 import { findStoreRoot } from "../../utils/store"
-import type { CheckResult, ExtensionKind, RunSummary } from "./types"
+import { ENGINE_CHALLENGES, type CheckResult, type ExtensionKind, type RunSummary } from "./types"
 
 const readJson = async <T>(path: string): Promise<T | null> => {
   try {
@@ -182,6 +182,74 @@ const checkRouteConventions = async (dir: string, doFix: boolean): Promise<Check
   return results
 }
 
+const ENTRY_FILES = ["index.ts", "index.js"]
+const CHALLENGES_RE = /(?<![.\w$])challenges\s*[:=]\s*(\[[^\]]*\]|[^\s,;}]+)/
+const HANDLES_CHALLENGES_RE = /(?<![.\w$])handlesChallenges\s*[:=]\s*([^\s,;}]+)/
+const STRING_LITERAL_RE = /^(["'`])([^"'`]*)\1$/
+
+const readEntrySource = async (dir: string): Promise<string | null> => {
+  for (const file of ENTRY_FILES) {
+    try {
+      return await readFile(join(dir, file), "utf-8")
+    } catch {
+      continue
+    }
+  }
+  return null
+}
+
+export const checkChallengesValue = (raw: string): CheckResult => {
+  const label = '"challenges" is valid'
+  if (!raw.startsWith("[")) {
+    return { label, status: "fail", detail: 'must be an array, e.g. ["anubis"]' }
+  }
+  const items = raw
+    .slice(1, -1)
+    .split(",")
+    .map((item) => item.trim())
+    .filter(Boolean)
+  const unknown = items.filter((item) => {
+    const kind = STRING_LITERAL_RE.exec(item)?.[2]
+    return kind === undefined || !ENGINE_CHALLENGES.includes(kind)
+  })
+  if (unknown.length > 0) {
+    return {
+      label,
+      status: "fail",
+      detail: `unknown kind ${unknown.join(", ")} - supported: ${ENGINE_CHALLENGES.map((k) => `"${k}"`).join(", ")}`,
+    }
+  }
+  return { label, status: "pass" }
+}
+
+export const checkHandlesChallengesValue = (raw: string): CheckResult => {
+  const label = '"handlesChallenges" is valid'
+  if (raw === "true" || raw === "false") return { label, status: "pass" }
+  return { label, status: "fail", detail: `must be true or false, got ${raw}` }
+}
+
+export const declaresChallenges = async (dir: string): Promise<boolean> => {
+  const src = await readEntrySource(dir)
+  return src !== null && CHALLENGES_RE.test(src)
+}
+
+const checkChallengeProps = async (
+  dir: string,
+  kind: ExtensionKind,
+): Promise<CheckResult[]> => {
+  const src = await readEntrySource(dir)
+  if (src === null) return []
+  if (kind === "engine") {
+    const raw = CHALLENGES_RE.exec(src)?.[1]
+    return raw === undefined ? [] : [checkChallengesValue(raw)]
+  }
+  if (kind === "transport") {
+    const raw = HANDLES_CHALLENGES_RE.exec(src)?.[1]
+    return raw === undefined ? [] : [checkHandlesChallengesValue(raw)]
+  }
+  return []
+}
+
 const runThemeChecks = async (dir: string, doFix: boolean): Promise<RunSummary> => {
   const results: CheckResult[] = []
   let failed = false
@@ -287,6 +355,12 @@ export const runChecks = async (
     if (authorRes.failed) failed = true
   }
 
+  if (kind === "engine" || kind === "transport") {
+    const challengeChecks = await checkChallengeProps(dir, kind)
+    results.push(...challengeChecks)
+    if (challengeChecks.some((c) => c.status === "fail")) failed = true
+  }
+
   if (kind === "plugin") {
     const routeChecks = await checkRouteConventions(dir, doFix)
     results.push(...routeChecks)
diff --git a/src/commands/doctor/index.ts b/src/commands/doctor/index.ts
index 237d718..13cb3a4 100644
--- a/src/commands/doctor/index.ts
+++ b/src/commands/doctor/index.ts
@@ -1,7 +1,8 @@
 import { resolve } from "node:path"
-import * as p from "@clack/prompts"
 import { t } from "../../utils/theme"
 import { logger } from "../../utils/logger"
+import { argv, positionalsAfter } from "../../utils/argv"
+import { ui } from "../../utils/ui"
 import { promptText, promptConfirm } from "../../utils/prompts"
 import { exists, detectTarget } from "./detect"
 import { runChecks } from "./checks"
@@ -14,13 +15,10 @@ type ParsedArgs = {
   doFix: boolean
 }
 
-const parseArgs = (): ParsedArgs => {
-  const argStart = process.argv[2] === "doctor" ? 3 : 2
-  const args = process.argv.slice(argStart)
-  const doFix = args.includes("--fix")
-  const pathArg = args.find((a) => !a.startsWith("-"))
-  return { pathArg, doFix }
-}
+const parseArgs = (): ParsedArgs => ({
+  pathArg: positionalsAfter("doctor")[0],
+  doFix: argv.fix,
+})
 
 const summaryLine = (s: StoreRunSummary): string =>
   [
@@ -34,7 +32,7 @@ const summaryLine = (s: StoreRunSummary): string =>
 export const doctorCmd = async (): Promise<void> => {
   const { pathArg, doFix: fixFlag } = parseArgs()
 
-  p.intro(t.brand("degoog doctor"))
+  ui.intro(t.brand("degoog doctor"))
 
   const cwd = process.cwd()
   const targetDir = pathArg
@@ -62,7 +60,7 @@ export const doctorCmd = async (): Promise<void> => {
   }
 
   if (target.kind === "store") {
-    p.log.info(t.muted(`checking store at ${targetDir}`))
+    ui.info(t.muted(`checking store at ${targetDir}`))
     const summary = await runStoreChecks(
       target.dir,
       target.manifestPath,
@@ -71,25 +69,25 @@ export const doctorCmd = async (): Promise<void> => {
     )
     console.log("")
     if (summary.failed > 0) {
-      p.outro(t.danger(`store has issues - ${summaryLine(summary)}`))
+      ui.outro(t.danger(`store has issues - ${summaryLine(summary)}`))
       process.exit(1)
     }
-    p.outro(t.success(`store looks good - ${summaryLine(summary)}`))
+    ui.outro(t.success(`store looks good - ${summaryLine(summary)}`))
     return
   }
 
-  p.log.info(t.muted(`checking extension at ${targetDir}`))
+  ui.info(t.muted(`checking extension at ${targetDir}`))
   const { results, failed } = await runChecks(target.dir, applyFix, target.extKind)
   printResults(results)
   console.log("")
 
   if (failed && !applyFix) {
-    p.outro(t.danger("issues found - re-run and choose to apply fixes, or pass --fix"))
+    ui.outro(t.danger("issues found - re-run and choose to apply fixes, or pass --fix"))
     process.exit(1)
   }
   if (failed) {
-    p.outro(t.warning("some issues could not be auto-fixed (see WARN above)"))
+    ui.outro(t.warning("some issues could not be auto-fixed (see WARN above)"))
     process.exit(1)
   }
-  p.outro(t.success("all checks passed"))
+  ui.outro(t.success("all checks passed"))
 }
diff --git a/src/commands/doctor/store-orphans.ts b/src/commands/doctor/store-orphans.ts
index e06680f..fbebc72 100644
--- a/src/commands/doctor/store-orphans.ts
+++ b/src/commands/doctor/store-orphans.ts
@@ -1,7 +1,9 @@
 import { readdir, stat } from "node:fs/promises"
 import { join, basename } from "node:path"
-import * as p from "@clack/prompts"
 import { t } from "../../utils/theme"
+import { ui } from "../../utils/ui"
+import { argv } from "../../utils/argv"
+import { isHeadless } from "../../utils/headless"
 import { promptConfirm, promptSelect } from "../../utils/prompts"
 import { exists } from "./detect"
 import type { ExtensionCategory, StoreEntry } from "./types"
@@ -80,7 +82,22 @@ export type OrphanResolution = {
   skipped: number
 }
 
-export const resolveOrphans = async (orphans: Orphan[]): Promise<OrphanResolution> => {
+const isPluginType = (v: string | undefined): v is PluginType =>
+  (PLUGIN_TYPES as readonly string[]).includes(v ?? "")
+
+const pickPluginType = async (orphan: Orphan): Promise<PluginType | undefined> => {
+  if (isPluginType(argv.pluginType)) return argv.pluginType
+  if (isHeadless) return undefined
+  return promptSelect<PluginType>(
+    t.muted(`plugin type for "${orphan.relPath}"`),
+    PLUGIN_TYPES.map((v) => ({ value: v, label: v })),
+  )
+}
+
+export const resolveOrphans = async (
+  orphans: Orphan[],
+  doFix: boolean,
+): Promise<OrphanResolution> => {
   const result: OrphanResolution = {
     byCategory: new Map(),
     added: 0,
@@ -88,15 +105,17 @@ export const resolveOrphans = async (orphans: Orphan[]): Promise<OrphanResolutio
   }
   if (orphans.length === 0) return result
 
-  p.log.step(t.brand("orphan folders"))
+  ui.step(t.brand("orphan folders"))
   for (const o of orphans) {
     console.log(`  ${t.warning("WARN")}  ${o.relPath} ${t.muted("- folder exists but not in package.json")}`)
   }
 
-  const register = await promptConfirm(
-    t.muted(`register all ${orphans.length} folder(s) in package.json? (defaults: name=folder, version=1.0.0)`),
-    true,
-  )
+  const register = isHeadless
+    ? doFix
+    : await promptConfirm(
+      t.muted(`register all ${orphans.length} folder(s) in package.json? (defaults: name=folder, version=1.0.0)`),
+      true,
+    )
 
   if (!register) {
     result.skipped = orphans.length
@@ -106,11 +125,12 @@ export const resolveOrphans = async (orphans: Orphan[]): Promise<OrphanResolutio
   for (const o of orphans) {
     let type: PluginType | undefined
     if (o.category === "plugins") {
-      const picked = await promptSelect<PluginType>(
-        t.muted(`plugin type for "${o.relPath}"`),
-        PLUGIN_TYPES.map((v) => ({ value: v, label: v })),
-      )
-      type = picked
+      type = await pickPluginType(o)
+      if (!type) {
+        console.log(`  ${t.warning("WARN")}  ${o.relPath} ${t.muted(`- skipped, pass --plugin-type <${PLUGIN_TYPES.join("|")}> to register it`)}`)
+        result.skipped++
+        continue
+      }
     }
     const entry = buildEntry(o, type)
     const list = result.byCategory.get(o.category) ?? []
diff --git a/src/commands/doctor/store-validate.ts b/src/commands/doctor/store-validate.ts
index f072397..7b013a2 100644
--- a/src/commands/doctor/store-validate.ts
+++ b/src/commands/doctor/store-validate.ts
@@ -1,7 +1,13 @@
 import { stat } from "node:fs/promises"
 import { join } from "node:path"
 import { exists } from "./detect"
-import type { CheckResult, ExtensionCategory, StoreEntry, StoreManifest } from "./types"
+import {
+  CHALLENGES_MIN_DEGOOG_VERSION,
+  type CheckResult,
+  type ExtensionCategory,
+  type StoreEntry,
+  type StoreManifest,
+} from "./types"
 
 export const validateTopLevel = (manifest: StoreManifest): CheckResult[] => {
   const results: CheckResult[] = []
@@ -122,3 +128,39 @@ export const validatePathExistence = async (
 
   return { results, toRemove }
 }
+
+const versionParts = (version: string): number[] =>
+  (version.trim().replace(/^v/, "").split("-")[0] ?? "")
+    .split(".")
+    .map((part) => Number.parseInt(part, 10) || 0)
+
+export const isVersionAtLeast = (version: string, minimum: string): boolean => {
+  const have = versionParts(version)
+  const want = versionParts(minimum)
+  for (let i = 0; i < Math.max(have.length, want.length); i++) {
+    const a = have[i] ?? 0
+    const b = want[i] ?? 0
+    if (a !== b) return a > b
+  }
+  return true
+}
+
+export const validateChallengesMinVersion = (entry: StoreEntry): CheckResult => {
+  const label = `package.json minDegoogVersion >= ${CHALLENGES_MIN_DEGOOG_VERSION}`
+  const v = entry.minDegoogVersion
+  if (typeof v !== "string" || v.trim() === "") {
+    return {
+      label,
+      status: "warn",
+      detail: `missing - engines that set "challenges" need degoog ${CHALLENGES_MIN_DEGOOG_VERSION} or newer`,
+    }
+  }
+  if (!isVersionAtLeast(v, CHALLENGES_MIN_DEGOOG_VERSION)) {
+    return {
+      label,
+      status: "warn",
+      detail: `set to ${v} - engines that set "challenges" need degoog ${CHALLENGES_MIN_DEGOOG_VERSION} or newer`,
+    }
+  }
+  return { label, status: "pass" }
+}
diff --git a/src/commands/doctor/store.ts b/src/commands/doctor/store.ts
index 96ef94b..5f05e5f 100644
--- a/src/commands/doctor/store.ts
+++ b/src/commands/doctor/store.ts
@@ -1,15 +1,16 @@
 import { writeFile } from "node:fs/promises"
 import { join, basename } from "node:path"
-import * as p from "@clack/prompts"
 import { t } from "../../utils/theme"
+import { ui } from "../../utils/ui"
 import { exists } from "./detect"
-import { runChecks } from "./checks"
+import { declaresChallenges, runChecks } from "./checks"
 import { printResults } from "./report"
 import {
   validateTopLevel,
   validateEntry,
   validatePathExistence,
   findDuplicateEntries,
+  validateChallengesMinVersion,
 } from "./store-validate"
 import { collectOrphans, resolveOrphans } from "./store-orphans"
 import {
@@ -35,7 +36,7 @@ const tallyResults = (results: CheckResult[], summary: StoreRunSummary): void =>
 }
 
 const sectionHeader = (label: string): void => {
-  p.log.step(t.brand(label))
+  ui.step(t.brand(label))
 }
 
 const collectEntryIssues = async (
@@ -85,12 +86,13 @@ const processCategory = async (
 const handleOrphans = async (
   storeDir: string,
   manifest: StoreManifest,
+  doFix: boolean,
   summary: StoreRunSummary,
 ): Promise<boolean> => {
   const orphans = await collectOrphans(storeDir, manifest)
   if (orphans.length === 0) return false
 
-  const resolution = await resolveOrphans(orphans)
+  const resolution = await resolveOrphans(orphans, doFix)
   summary.fixed += resolution.added
   summary.failed += resolution.skipped
 
@@ -122,6 +124,9 @@ const runExtensionChecks = async (
 
       sectionHeader(`${category}/${basename(entry.path)}`)
       const { results } = await runChecks(full, doFix, kind)
+      if (kind === "engine" && (await declaresChallenges(full))) {
+        results.push(validateChallengesMinVersion(entry))
+      }
       printResults(results)
       tallyResults(results, summary)
     }
@@ -147,7 +152,7 @@ export const runStoreChecks = async (
     if (changed) manifestMutated = true
   }
 
-  const addedOrphans = await handleOrphans(storeDir, manifest, summary)
+  const addedOrphans = await handleOrphans(storeDir, manifest, doFix, summary)
   if (addedOrphans) manifestMutated = true
 
   if (manifestMutated) {
diff --git a/src/commands/doctor/types.ts b/src/commands/doctor/types.ts
index b2df5e4..04e9844 100644
--- a/src/commands/doctor/types.ts
+++ b/src/commands/doctor/types.ts
@@ -32,6 +32,10 @@ export const PLUGIN_TYPES = ["command", "slot", "interceptor", "search-result-ta
 
 export type PluginType = typeof PLUGIN_TYPES[number]
 
+export const ENGINE_CHALLENGES: readonly string[] = ["anubis"]
+
+export const CHALLENGES_MIN_DEGOOG_VERSION = "1.0.0"
+
 export type StoreEntry = {
   path?: string
   name?: string
diff --git a/src/commands/login.ts b/src/commands/login.ts
index ae4ccfd..c20a0bb 100644
--- a/src/commands/login.ts
+++ b/src/commands/login.ts
@@ -1,6 +1,8 @@
 import * as p from "@clack/prompts"
 import { loadConfig, saveConfig } from "../config/store"
 import { logger } from "../utils/logger"
+import { argv } from "../utils/argv"
+import { isHeadless, fail } from "../utils/headless"
 import type { Config } from "../types"
 
 const isValidUrl = (val: string) => {
@@ -14,13 +16,40 @@ const isValidUrl = (val: string) => {
   }
 }
 
+const loginHeadless = async (existing: Config) => {
+  const instanceUrl = argv.instanceUrl ?? process.env.DEGOOG_INSTANCE_URL
+  const apiKey = argv.apiKey ?? process.env.DEGOOG_API_KEY
+  const username = argv.username
+  const website = argv.website
+
+  if (!instanceUrl && !apiKey && !username && !website) {
+    return fail("nothing to save, pass at least one of --instance-url, --api-key, --username, --website")
+  }
+
+  for (const [flag, val] of [["--instance-url", instanceUrl], ["--website", website]] as const) {
+    const err = val ? isValidUrl(val) : undefined
+    if (err) return fail(`${flag}: ${err}`)
+  }
+
+  const cfg: Config = { ...existing }
+  if (instanceUrl) cfg.instanceUrl = instanceUrl
+  if (apiKey) cfg.apiKey = apiKey
+  if (username) cfg.username = username
+  if (website) cfg.website = website
+
+  await saveConfig(cfg)
+  logger.success("config saved")
+}
+
 export const loginCmd = async () => {
   const existing = await loadConfig()
 
+  if (isHeadless) return loginHeadless(existing)
+
   const instanceUrl = await p.text({
     message: "degoog instance URL",
     placeholder: "http://localhost:4444",
-    initialValue: existing.instanceUrl ?? "",
+    initialValue: argv.instanceUrl ?? existing.instanceUrl ?? "",
     validate: isValidUrl,
   })
   if (p.isCancel(instanceUrl)) return
@@ -38,21 +67,22 @@ export const loginCmd = async () => {
   const username = await p.text({
     message: "Your name (used in author.json when scaffolding extensions)",
     placeholder: "Jane Dev",
-    initialValue: existing.username ?? "",
+    initialValue: argv.username ?? existing.username ?? "",
   })
   if (p.isCancel(username)) return
 
   const website = await p.text({
     message: "Your website or GitHub URL (optional)",
     placeholder: "https://github.com/username",
-    initialValue: existing.website ?? "",
+    initialValue: argv.website ?? existing.website ?? "",
     validate: isValidUrl,
   })
   if (p.isCancel(website)) return
 
   const cfg: Config = { ...existing }
   if (instanceUrl) cfg.instanceUrl = instanceUrl
-  if (apiKey) cfg.apiKey = apiKey
+  const key = apiKey || argv.apiKey
+  if (key) cfg.apiKey = key
   if (username) cfg.username = username
   if (website) cfg.website = website
   else if (!website && existing.website) cfg.website = existing.website
diff --git a/src/commands/search.ts b/src/commands/search.ts
index 8c1a417..fcd8e66 100644
--- a/src/commands/search.ts
+++ b/src/commands/search.ts
@@ -2,6 +2,8 @@ import * as p from "@clack/prompts";
 import { loadConfig } from "../config/store";
 import { apiGet } from "../utils/api";
 import { t } from "../utils/theme";
+import { argv, positionalsAfter } from "../utils/argv";
+import { isHeadless, fail } from "../utils/headless";
 
 type Result = {
   title: string;
@@ -19,11 +21,17 @@ type SearchResp = {
 const PAGE_SIZE = 10;
 
 const parseSearchQuery = (): string | undefined => {
-  const argStart = process.argv[2] === "search" ? 3 : 2;
-  const args = process.argv.slice(argStart).filter((a) => !a.startsWith("-"));
+  const args = positionalsAfter("search");
   return args.length ? args.join(" ") : undefined;
 };
 
+const parseLimit = (): number | undefined => {
+  if (argv.limit === undefined) return undefined;
+  const n = Number(argv.limit);
+  if (!Number.isInteger(n) || n < 1) fail(`invalid --limit "${argv.limit}"`);
+  return n;
+};
+
 const openUrl = (url: string) => {
   const cmd = process.platform === "darwin" ? "open" : "xdg-open";
   try {
@@ -56,25 +64,22 @@ const truncate = (s: string, max: number) =>
 
 const totalPages = (count: number) => Math.max(1, Math.ceil(count / PAGE_SIZE));
 
-const renderResults = (
+const renderResultList = (
   data: SearchResp,
-  page: number,
+  results: Result[],
+  start: number,
+  header: string,
   showRelated: boolean,
 ) => {
   const cols = process.stdout.columns ?? 100;
   const maxWidth = Math.min(cols - 8, 90);
   const pad = "      ";
-  const pages = totalPages(data.results.length);
-  const start = (page - 1) * PAGE_SIZE;
-  const pageResults = data.results.slice(start, start + PAGE_SIZE);
 
   console.log();
-  console.log(
-    `  ${t.muted(`page ${page}/${pages} · ${data.results.length} results · ${data.totalTime}ms`)}`,
-  );
+  console.log(`  ${t.muted(header)}`);
   console.log();
 
-  pageResults.forEach((r, i) => {
+  results.forEach((r, i) => {
     const num = t.dim(`  ${String(start + i + 1).padStart(2)}  `);
     console.log(`${num}${t.bold(t.brand(truncate(r.title, maxWidth)))}`);
     console.log(`${pad}${t.success(truncate(r.url, maxWidth))}`);
@@ -101,6 +106,22 @@ const renderResults = (
   }
 };
 
+const renderResults = (
+  data: SearchResp,
+  page: number,
+  showRelated: boolean,
+) => {
+  const pages = totalPages(data.results.length);
+  const start = (page - 1) * PAGE_SIZE;
+  renderResultList(
+    data,
+    data.results.slice(start, start + PAGE_SIZE),
+    start,
+    `page ${page}/${pages} · ${data.results.length} results · ${data.totalTime}ms`,
+    showRelated,
+  );
+};
+
 const doSearch = async (
   query: string,
   config: Awaited<ReturnType<typeof loadConfig>>,
@@ -183,9 +204,51 @@ const browseResults = async (data: SearchResp): Promise<"again" | "back"> => {
   }
 };
 
+const searchHeadless = async (
+  query: string | undefined,
+  config: Awaited<ReturnType<typeof loadConfig>>,
+) => {
+  if (!config.instanceUrl) {
+    return fail("no instance configured - run: degoog-cli login --instance-url <url>");
+  }
+  if (!query) return fail("a query is required: degoog-cli search <query>");
+
+  const limit = parseLimit();
+  const result = await apiGet<SearchResp>(
+    config,
+    `/api/search?q=${encodeURIComponent(query)}`,
+  );
+  if (!result.ok) return fail(result.error);
+
+  const data = result.data;
+  const results = limit ? data.results.slice(0, limit) : data.results;
+
+  if (argv.json) {
+    console.log(JSON.stringify({ ...data, results }, null, 2));
+    return;
+  }
+
+  if (!results.length) {
+    console.log(t.muted("no results found"));
+    return;
+  }
+
+  renderResultList(
+    data,
+    results,
+    0,
+    `${results.length} of ${data.results.length} results · ${data.totalTime}ms`,
+    true,
+  );
+};
+
 export const searchCmd = async () => {
   const config = await loadConfig();
 
+  if (isHeadless || argv.json) {
+    return searchHeadless(parseSearchQuery(), config);
+  }
+
   if (!config.instanceUrl) {
     p.log.warn(t.warning("no instance configured - run Login / Setup first"));
     return;
diff --git a/src/generators/engine.ts b/src/generators/engine.ts
index 9fef034..41e0628 100644
--- a/src/generators/engine.ts
+++ b/src/generators/engine.ts
@@ -1,7 +1,7 @@
 import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files";
 import type { GeneratorCtx } from "../types";
 
-const indexTpl = (name: string) => `export const type = "web" // string or array - e.g. "web", "books", ["web", "any-type"]
+const indexTpl = (name: string, challenges: boolean) => `export const type = "web" // string or array - e.g. "web", "books", ["web", "any-type"]
 
 // filters example (image engines only):
 // Declare which image filter groups/values this engine actually supports.
@@ -24,7 +24,7 @@ const indexTpl = (name: string) => `export const type = "web" // string or array
 export const engine = {
   name: "${name}",
   bangShortcut: "${name}",
-
+${challenges ? `  challenges: ["anubis"],\n` : ""}
   // settingsSchema: [
   //   { key: "apiKey", label: "API Key", type: "password", required: true },
   // ],
@@ -83,7 +83,7 @@ export const engine = {
 
 export const generateEngine = async (ctx: GeneratorCtx) =>
   scaffoldDir(ctx.outDir, ctx.name, {
-    "index.ts": indexTpl(ctx.name),
+    "index.ts": indexTpl(ctx.name, ctx.challenges ?? false),
     "README.md": readmeTpl(ctx.name, "A custom search engine for degoog."),
     "author.json": authorJsonTpl(ctx.config),
   });
diff --git a/src/generators/theme.ts b/src/generators/theme.ts
index 4a9c525..4585f6e 100644
--- a/src/generators/theme.ts
+++ b/src/generators/theme.ts
@@ -1,6 +1,7 @@
 import * as p from "@clack/prompts"
 import { scaffoldDir, authorJsonTpl } from "../utils/files"
 import { t } from "../utils/theme"
+import { isHeadless } from "../utils/headless"
 import type { GeneratorCtx } from "../types"
 import {
   layoutHtml, indexHtml, searchHtml, html404,
@@ -269,30 +270,35 @@ const buildThemeJson = (name: string, sel: Selection): string => {
   return JSON.stringify(manifest, null, 2) + "\n"
 }
 
-export const generateTheme = async (ctx: GeneratorCtx) => {
+const THEME_PART_OPTIONS = [
+  { value: "css", label: t.text("Custom styles"), hint: "CSS variable overrides for colours and spacing" },
+  { value: "layout", label: t.text("Base layout"), hint: "Full HTML shell - head, scripts, tokens. Override with care" },
+  { value: "index", label: t.text("Home page"), hint: "index.html - the landing page" },
+  { value: "search", label: t.text("Search results page"), hint: "search.html - the full results listing" },
+  { value: "404", label: t.text("404 page"), hint: "Custom not-found page" },
+  { value: "easter-eggs", label: t.text("Easter eggs"), hint: "Gandalf and robots-takeover pages" },
+  { value: "home-logo", label: t.text("Home: logo"), hint: "Replace the logo area on the home page" },
+  { value: "home-search", label: t.text("Home: search bar"), hint: "Replace the search form on the home page" },
+  { value: "home-header", label: t.text("Home: header"), hint: "Replace the top navigation on the home page" },
+  { value: "home-footer", label: t.text("Home: footer"), hint: "Replace the page footer" },
+  { value: "search-header", label: t.text("Search: header bar"), hint: "Logo + search bar + settings gear on results page" },
+  { value: "search-tabs", label: t.text("Search: result tabs"), hint: "Web / Images / Videos / News tab strip" },
+  { value: "result", label: t.text("Search: result card"), hint: "Individual web and news result items" },
+  { value: "image-card", label: t.text("Search: image card"), hint: "Image grid thumbnails" },
+  { value: "video-card", label: t.text("Search: video card"), hint: "Video result cards" },
+  { value: "search-media-preview", label: t.text("Search: media preview"), hint: "Expanded image/video preview panel" },
+  { value: "search-lightbox", label: t.text("Search: lightbox"), hint: "Full-screen image lightbox" },
+  { value: "at-a-glance", label: t.text("Search: at-a-glance"), hint: "AI / knowledge panel" },
+  { value: "settings-schema", label: t.text("User settings"), hint: "Adds configurable options (e.g. colour variants)" },
+] as const
+
+export const THEME_PARTS: string[] = THEME_PART_OPTIONS.map((o) => o.value)
+
+const pickThemeParts = async (): Promise<string[]> => {
+  if (isHeadless) return ["css"]
   const chosen = await p.multiselect<string>({
     message: t.muted("what do you want to include in your theme?"),
-    options: [
-      { value: "css", label: t.text("Custom styles"), hint: "CSS variable overrides for colours and spacing" },
-      { value: "layout", label: t.text("Base layout"), hint: "Full HTML shell - head, scripts, tokens. Override with care" },
-      { value: "index", label: t.text("Home page"), hint: "index.html - the landing page" },
-      { value: "search", label: t.text("Search results page"), hint: "search.html - the full results listing" },
-      { value: "404", label: t.text("404 page"), hint: "Custom not-found page" },
-      { value: "easter-eggs", label: t.text("Easter eggs"), hint: "Gandalf and robots-takeover pages" },
-      { value: "home-logo", label: t.text("Home: logo"), hint: "Replace the logo area on the home page" },
-      { value: "home-search", label: t.text("Home: search bar"), hint: "Replace the search form on the home page" },
-      { value: "home-header", label: t.text("Home: header"), hint: "Replace the top navigation on the home page" },
-      { value: "home-footer", label: t.text("Home: footer"), hint: "Replace the page footer" },
-      { value: "search-header", label: t.text("Search: header bar"), hint: "Logo + search bar + settings gear on results page" },
-      { value: "search-tabs", label: t.text("Search: result tabs"), hint: "Web / Images / Videos / News tab strip" },
-      { value: "result", label: t.text("Search: result card"), hint: "Individual web and news result items" },
-      { value: "image-card", label: t.text("Search: image card"), hint: "Image grid thumbnails" },
-      { value: "video-card", label: t.text("Search: video card"), hint: "Video result cards" },
-      { value: "search-media-preview", label: t.text("Search: media preview"), hint: "Expanded image/video preview panel" },
-      { value: "search-lightbox", label: t.text("Search: lightbox"), hint: "Full-screen image lightbox" },
-      { value: "at-a-glance", label: t.text("Search: at-a-glance"), hint: "AI / knowledge panel" },
-      { value: "settings-schema", label: t.text("User settings"), hint: "Adds configurable options (e.g. colour variants)" },
-    ],
+    options: [...THEME_PART_OPTIONS],
     required: false,
   })
 
@@ -300,6 +306,11 @@ export const generateTheme = async (ctx: GeneratorCtx) => {
     p.cancel(t.muted("cancelled"))
     process.exit(0)
   }
+  return chosen
+}
+
+export const generateTheme = async (ctx: GeneratorCtx) => {
+  const chosen = ctx.themeParts ?? (await pickThemeParts())
 
   const sel: Selection = {
     includeCss: chosen.includes("css"),
diff --git a/src/generators/transport.ts b/src/generators/transport.ts
index 1f62dd6..4505e16 100644
--- a/src/generators/transport.ts
+++ b/src/generators/transport.ts
@@ -1,11 +1,11 @@
 import { scaffoldDir, authorJsonTpl, readmeTpl } from "../utils/files"
 import type { GeneratorCtx } from "../types"
 
-const indexTpl = (name: string) => `export const transport = {
+const indexTpl = (name: string, handlesChallenges: boolean) => `export const transport = {
   name: "${name}",
   displayName: "${name}",
   description: "Custom transport for degoog",
-
+${handlesChallenges ? `  handlesChallenges: true,\n` : ""}
   // settingsSchema: [
   //   { key: "proxyUrl", label: "Proxy URL", type: "url", required: true },
   // ],
@@ -43,7 +43,7 @@ const indexTpl = (name: string) => `export const transport = {
 
 export const generateTransport = async (ctx: GeneratorCtx) =>
   scaffoldDir(ctx.outDir, ctx.name, {
-    "index.ts": indexTpl(ctx.name),
+    "index.ts": indexTpl(ctx.name, ctx.handlesChallenges ?? false),
     "README.md": readmeTpl(ctx.name, "A custom HTTP transport for degoog."),
     "author.json": authorJsonTpl(ctx.config),
   })
diff --git a/src/index.ts b/src/index.ts
index 2b7c695..3c7a505 100644
--- a/src/index.ts
+++ b/src/index.ts
@@ -5,6 +5,11 @@ import { searchCmd } from "./commands/search"
 import { doctorCmd } from "./commands/doctor"
 import { title, t } from "./utils/theme"
 import { checkLatest, VERSION, updateCmd } from "./utils/version"
+import { argv } from "./utils/argv"
+import { isHeadless } from "./utils/headless"
+import { logger } from "./utils/logger"
+import { THEME_PARTS } from "./generators/theme"
+import { ExtType } from "./types"
 
 const SUBCOMMANDS: Record<string, () => Promise<void>> = {
   create: async () => { await createCmd() },
@@ -13,12 +18,69 @@ const SUBCOMMANDS: Record<string, () => Promise<void>> = {
   doctor: async () => { await doctorCmd() },
 }
 
+const usage = () => `degoog-cli v${VERSION}
+
+usage: degoog-cli [command] [options]
+
+Run with no command in a terminal to get the interactive menu. Every command
+also runs without prompts: pass -y/--yes, or pipe it, or set CI or DEGOOG_HEADLESS=1.
+
+commands:
+  create   scaffold a new extension
+             --name <slug>            required without a terminal
+             --type <type>            required without a terminal
+                                      ${Object.values(ExtType).join(", ")}
+             --out <dir>              output directory (default: store category, else .)
+             --init-store             create a store in the current directory if none is found
+             --challenges             engine: site uses an Anubis proof-of-work page
+             --handles-challenges     transport: drives a real browser past proof-of-work pages
+             --include <parts>        theme: comma-separated parts, or "all" (default: css)
+                                      ${THEME_PARTS.join(", ")}
+  search   search your instance
+             <query>                  required without a terminal
+             --json                   print raw JSON (implies no prompts)
+             --limit <n>              only print the first n results
+  login    save instance and author details
+             --instance-url <url>     or DEGOOG_INSTANCE_URL
+             --api-key <key>          or DEGOOG_API_KEY
+             --username <name>
+             --website <url>
+  doctor   validate an extension folder or store
+             [path]                   default: current directory
+             --fix                    apply safe fixes, including registering orphan folders
+             --plugin-type <type>     type used when registering orphan plugin folders
+
+global:
+  -y, --yes, --headless    never prompt, use flags and defaults
+  --no-color               disable colours (also NO_COLOR, or when output is not a terminal)
+  -h, --help               show this help
+  -v, --version            print the version
+`
+
 const main = async () => {
-  const sub = process.argv[2]
+  if (argv.help) {
+    console.log(usage())
+    process.exit(0)
+  }
+  if (argv.version) {
+    console.log(VERSION)
+    process.exit(0)
+  }
+
+  const sub = argv.command
   if (sub && sub in SUBCOMMANDS) {
     await SUBCOMMANDS[sub]!()
     process.exit(0)
   }
+  if (sub) {
+    logger.error(`unknown command: ${sub}`)
+    console.log(usage())
+    process.exit(1)
+  }
+  if (isHeadless) {
+    console.log(usage())
+    process.exit(1)
+  }
 
   p.intro(title)
 
diff --git a/src/types/index.ts b/src/types/index.ts
index e7b843b..bd6b2a2 100644
--- a/src/types/index.ts
+++ b/src/types/index.ts
@@ -16,6 +16,9 @@ export type GeneratorCtx = {
   name: string
   outDir: string
   config: Config
+  challenges?: boolean
+  handlesChallenges?: boolean
+  themeParts?: string[]
 }
 
 export type Config = {
diff --git a/src/utils/argv.ts b/src/utils/argv.ts
index 90103f4..0d61a85 100644
--- a/src/utils/argv.ts
+++ b/src/utils/argv.ts
@@ -1,12 +1,103 @@
-const args = process.argv.slice(2)
+const BOOLEAN_FLAGS = new Set([
+  "-y",
+  "--yes",
+  "--headless",
+  "--fix",
+  "--json",
+  "--challenges",
+  "--handles-challenges",
+  "--init-store",
+  "--no-color",
+  "-h",
+  "--help",
+  "-v",
+  "--version",
+])
 
-const flag = (name: string): string | undefined => {
-  const i = args.indexOf(name)
-  return i !== -1 ? args[i + 1] : undefined
+type Parsed = {
+  positionals: string[]
+  flags: Map<string, string | true>
 }
 
+const parse = (args: string[]): Parsed => {
+  const positionals: string[] = []
+  const flags = new Map<string, string | true>()
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+    if (!arg.startsWith("-") || arg === "-") {
+      positionals.push(arg)
+      continue
+    }
+    if (arg === "--") {
+      positionals.push(...args.slice(i + 1))
+      break
+    }
+    const eq = arg.indexOf("=")
+    if (eq !== -1) {
+      flags.set(arg.slice(0, eq), arg.slice(eq + 1))
+      continue
+    }
+    if (BOOLEAN_FLAGS.has(arg)) {
+      flags.set(arg, true)
+      continue
+    }
+    const next = args[i + 1]
+    if (next !== undefined && !next.startsWith("-")) {
+      flags.set(arg, next)
+      i++
+    } else {
+      flags.set(arg, true)
+    }
+  }
+
+  return { positionals, flags }
+}
+
+const parsed = parse(process.argv.slice(2))
+
+const str = (...names: string[]): string | undefined => {
+  for (const name of names) {
+    const v = parsed.flags.get(name)
+    if (typeof v === "string") return v
+  }
+  return undefined
+}
+
+const bool = (...names: string[]): boolean | undefined => {
+  for (const name of names) {
+    const v = parsed.flags.get(name)
+    if (v === undefined) continue
+    if (v === true) return true
+    const lower = v.toLowerCase()
+    if (["false", "0", "no", "off"].includes(lower)) return false
+    return true
+  }
+  return undefined
+}
+
+export const positionalsAfter = (command: string): string[] =>
+  parsed.positionals[0] === command ? parsed.positionals.slice(1) : parsed.positionals
+
 export const argv = {
-  name: flag("--name"),
-  type: flag("--type"),
-  out:  flag("--out"),
+  command: parsed.positionals[0],
+  name: str("--name"),
+  type: str("--type"),
+  out: str("--out"),
+  include: str("--include"),
+  initStore: bool("--init-store") ?? false,
+  challenges: bool("--challenges"),
+  handlesChallenges: bool("--handles-challenges"),
+  instanceUrl: str("--instance-url"),
+  apiKey: str("--api-key"),
+  username: str("--username"),
+  website: str("--website"),
+  fix: bool("--fix") ?? false,
+  pluginType: str("--plugin-type"),
+  json: bool("--json") ?? false,
+  limit: str("--limit"),
+  headless: bool("-y", "--yes", "--headless") ?? false,
+  noColor: bool("--no-color") ?? false,
+  help: bool("-h", "--help") ?? false,
+  version: bool("-v", "--version") ?? false,
 }
diff --git a/src/utils/headless.ts b/src/utils/headless.ts
new file mode 100644
index 0000000..64304c4
--- /dev/null
+++ b/src/utils/headless.ts
@@ -0,0 +1,19 @@
+import { argv } from "./argv"
+import { logger } from "./logger"
+
+const envFlag = (name: string): boolean => {
+  const v = process.env[name]
+  return !!v && !["0", "false", "no", "off"].includes(v.toLowerCase())
+}
+
+export const isHeadless =
+  argv.headless ||
+  envFlag("DEGOOG_HEADLESS") ||
+  envFlag("CI") ||
+  !process.stdin.isTTY ||
+  !process.stdout.isTTY
+
+export const fail = (msg: string): never => {
+  logger.error(msg)
+  process.exit(1)
+}
diff --git a/src/utils/prompts.ts b/src/utils/prompts.ts
index 93e26ef..9a82c7d 100644
--- a/src/utils/prompts.ts
+++ b/src/utils/prompts.ts
@@ -1,6 +1,7 @@
 import * as p from "@clack/prompts"
 import { t } from "./theme"
 import { Option } from "@clack/prompts"
+import { isHeadless, fail } from "./headless"
 
 const exitCancelled = (): never => {
   p.cancel(t.muted("cancelled"))
@@ -14,6 +15,7 @@ type TextOpts = {
 }
 
 export const promptText = async (opts: TextOpts): Promise<string> => {
+  if (isHeadless) return opts.defaultValue
   const input = await p.text({
     message: opts.message,
     placeholder: opts.placeholder ?? opts.defaultValue,
@@ -27,6 +29,7 @@ export const promptConfirm = async (
   message: string,
   initialValue = false,
 ): Promise<boolean> => {
+  if (isHeadless) return initialValue
   const ans = await p.confirm({ message, initialValue })
   if (p.isCancel(ans)) exitCancelled()
   return ans === true
@@ -40,7 +43,12 @@ type SelectOption<T extends string> = {
 export const promptSelect = async <T extends string>(
   message: string,
   options: SelectOption<T>[],
+  headlessDefault?: T,
 ): Promise<T> => {
+  if (isHeadless) {
+    if (headlessDefault !== undefined) return headlessDefault
+    return fail(`cannot answer "${message}" without a terminal, pass the matching flag`)
+  }
   const picked = await p.select<T>({ message, options: options as Option<T>[] })
   if (p.isCancel(picked)) exitCancelled()
   return picked as T
diff --git a/src/utils/store.ts b/src/utils/store.ts
index d5380c1..af22afc 100644
--- a/src/utils/store.ts
+++ b/src/utils/store.ts
@@ -1,6 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises"
 import { join, basename, dirname, resolve } from "node:path"
 import {
+  CHALLENGES_MIN_DEGOOG_VERSION,
   EXTENSION_CATEGORIES,
   type ExtensionCategory,
   type PluginType,
@@ -67,7 +68,11 @@ const EXT_TYPE_PLUGIN_TYPE: Partial<Record<ExtType, PluginType>> = {
   [ExtType.PluginIntercept]: "interceptor",
 }
 
-export const buildStoreEntry = (name: string, extType: ExtType): StoreEntry => {
+export const buildStoreEntry = (
+  name: string,
+  extType: ExtType,
+  challenges = false,
+): StoreEntry => {
   const category = extTypeToCategory(extType)
   const entry: StoreEntry = {
     path: `${category}/${name}`,
@@ -78,6 +83,9 @@ export const buildStoreEntry = (name: string, extType: ExtType): StoreEntry => {
   if (category === "plugins") {
     entry.type = EXT_TYPE_PLUGIN_TYPE[extType] ?? "command"
   }
+  if (extType === ExtType.Engine && challenges) {
+    entry.minDegoogVersion = CHALLENGES_MIN_DEGOOG_VERSION
+  }
   return entry
 }
 
@@ -85,12 +93,13 @@ export const registerExtensionInStore = async (
   storeDir: string,
   name: string,
   extType: ExtType,
+  challenges = false,
 ): Promise<void> => {
   const store = await readStoreManifest(storeDir)
   if (!store) return
 
   const category = extTypeToCategory(extType)
-  const entry = buildStoreEntry(name, extType)
+  const entry = buildStoreEntry(name, extType, challenges)
   const manifest = { ...store.manifest }
   const existing = manifest[category]
   const list = Array.isArray(existing) ? [...(existing as StoreEntry[])] : []
diff --git a/src/utils/theme.ts b/src/utils/theme.ts
index d20e2aa..9fa431d 100644
--- a/src/utils/theme.ts
+++ b/src/utils/theme.ts
@@ -1,7 +1,12 @@
-const fg = (r: number, g: number, b: number) => `\x1b[38;2;${r};${g};${b}m`
-const RESET = "\x1b[0m"
-const BOLD = "\x1b[1m"
-const DIM = "\x1b[2m"
+const COLOR =
+  !process.env.NO_COLOR &&
+  !process.argv.includes("--no-color") &&
+  (process.stdout.isTTY || !!process.env.FORCE_COLOR)
+
+const fg = (r: number, g: number, b: number) => (COLOR ? `\x1b[38;2;${r};${g};${b}m` : "")
+const RESET = COLOR ? "\x1b[0m" : ""
+const BOLD = COLOR ? "\x1b[1m" : ""
+const DIM = COLOR ? "\x1b[2m" : ""
 
 const c = {
   primary:   fg(86,  115, 172),
diff --git a/src/utils/ui.ts b/src/utils/ui.ts
new file mode 100644
index 0000000..46e6ad7
--- /dev/null
+++ b/src/utils/ui.ts
@@ -0,0 +1,39 @@
+import * as p from "@clack/prompts"
+import { isHeadless } from "./headless"
+
+type Spinner = {
+  start: (msg?: string) => void
+  stop: (msg?: string) => void
+}
+
+const silentSpinner: Spinner = {
+  start: () => {},
+  stop: () => {},
+}
+
+export const ui = {
+  intro: (msg: string) => {
+    if (!isHeadless) p.intro(msg)
+  },
+  outro: (msg: string) => {
+    if (isHeadless) console.log(msg)
+    else p.outro(msg)
+  },
+  info: (msg: string) => {
+    if (isHeadless) console.log(msg)
+    else p.log.info(msg)
+  },
+  step: (msg: string) => {
+    if (isHeadless) console.log(msg)
+    else p.log.step(msg)
+  },
+  warn: (msg: string) => {
+    if (isHeadless) console.warn(msg)
+    else p.log.warn(msg)
+  },
+  note: (msg: string, title?: string) => {
+    if (isHeadless) console.log(msg)
+    else p.note(msg, title)
+  },
+  spinner: (): Spinner => (isHeadless ? silentSpinner : p.spinner()),
+}

From 698db3ba0360016097c5db162d829bc7a93d30aa Mon Sep 17 00:00:00 2001
From: fccview <112867047+fccview@users.noreply.github.com>
Date: Thu, 1 Oct 2026 20:32:46 +0100
Subject: [PATCH 5/6] Bump little asshole

---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index ba9045d..74506c8 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "degoog-cli",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "description": "CLI toolset for degoog",
   "type": "module",
   "scripts": {

From ed8123be295f3326fa1ea388e21021a6b92d1a6a Mon Sep 17 00:00:00 2001
From: fccview <f.campioneuk@gmail.com>
Date: Sat, 3 Oct 2026 15:48:10 +0100
Subject: [PATCH 6/6] add favicon support

---
 src/commands/doctor/checks.ts         | 49 +++++++++++++++++++++++++++
 src/commands/doctor/store-validate.ts | 25 +++++++-------
 src/commands/doctor/store.ts          |  6 +++-
 src/commands/doctor/types.ts          |  2 ++
 src/generators/plugin-bang.ts         |  2 ++
 src/generators/plugin-intercept.ts    |  2 ++
 src/generators/plugin-slot.ts         |  5 ++-
 src/generators/plugin-tab.ts          |  2 ++
 8 files changed, 78 insertions(+), 15 deletions(-)

diff --git a/src/commands/doctor/checks.ts b/src/commands/doctor/checks.ts
index 7288dbe..eaf8302 100644
--- a/src/commands/doctor/checks.ts
+++ b/src/commands/doctor/checks.ts
@@ -1,4 +1,5 @@
 import { readFile, writeFile, readdir } from "node:fs/promises"
+import type { Dirent } from "node:fs"
 import { join, basename } from "node:path"
 import { exists } from "./detect"
 import { findStoreRoot } from "../../utils/store"
@@ -182,6 +183,51 @@ const checkRouteConventions = async (dir: string, doFix: boolean): Promise<Check
   return results
 }
 
+const FAVICON_SOURCE_EXT = /\.(js|mjs|cjs|ts|html)$/
+const HAND_BUILT_FAVICON_RE = /\/api\/proxy\/favicon\?domain=/
+const FAVICON_SIGNER_RE = /\bsignFaviconUrl\b/
+
+const readPluginSources = async (dir: string, rel = ""): Promise<{ file: string; src: string }[]> => {
+  let entries: Dirent[]
+  try {
+    entries = await readdir(join(dir, rel), { withFileTypes: true })
+  } catch {
+    return []
+  }
+  const out: { file: string; src: string }[] = []
+  for (const entry of entries) {
+    const file = rel ? `${rel}/${entry.name}` : entry.name
+    if (entry.isDirectory()) {
+      if (entry.name === "node_modules" || entry.name.startsWith(".")) continue
+      out.push(...(await readPluginSources(dir, file)))
+    } else if (FAVICON_SOURCE_EXT.test(entry.name)) {
+      try {
+        out.push({ file, src: await readFile(join(dir, file), "utf-8") })
+      } catch {
+        continue
+      }
+    }
+  }
+  return out
+}
+
+export const checkFaviconUrls = async (dir: string): Promise<CheckResult[]> => {
+  const offenders = (await readPluginSources(dir))
+    .filter(({ src }) => HAND_BUILT_FAVICON_RE.test(src))
+    .map(({ file }) => file)
+  if (offenders.length === 0) {
+    return [{ label: "favicon URLs are signed by degoog", status: "pass" }]
+  }
+  return offenders.map((file) => ({
+    label: `${file} favicon URLs`,
+    status: "fail",
+    detail: "hand-built /api/proxy/favicon URL gets a 403 - sign it on the server with ctx.signFaviconUrl(url)",
+  }))
+}
+
+export const usesFaviconSigner = async (dir: string): Promise<boolean> =>
+  (await readPluginSources(dir)).some(({ src }) => FAVICON_SIGNER_RE.test(src))
+
 const ENTRY_FILES = ["index.ts", "index.js"]
 const CHALLENGES_RE = /(?<![.\w$])challenges\s*[:=]\s*(\[[^\]]*\]|[^\s,;}]+)/
 const HANDLES_CHALLENGES_RE = /(?<![.\w$])handlesChallenges\s*[:=]\s*([^\s,;}]+)/
@@ -365,6 +411,9 @@ export const runChecks = async (
     const routeChecks = await checkRouteConventions(dir, doFix)
     results.push(...routeChecks)
     if (routeChecks.some((c) => c.status === "fail")) failed = true
+    const faviconChecks = await checkFaviconUrls(dir)
+    results.push(...faviconChecks)
+    if (faviconChecks.some((c) => c.status === "fail")) failed = true
   }
 
   return { results, failed }
diff --git a/src/commands/doctor/store-validate.ts b/src/commands/doctor/store-validate.ts
index 7b013a2..b236ecb 100644
--- a/src/commands/doctor/store-validate.ts
+++ b/src/commands/doctor/store-validate.ts
@@ -3,6 +3,7 @@ import { join } from "node:path"
 import { exists } from "./detect"
 import {
   CHALLENGES_MIN_DEGOOG_VERSION,
+  FAVICON_SIGNER_MIN_DEGOOG_VERSION,
   type CheckResult,
   type ExtensionCategory,
   type StoreEntry,
@@ -145,22 +146,20 @@ export const isVersionAtLeast = (version: string, minimum: string): boolean => {
   return true
 }
 
-export const validateChallengesMinVersion = (entry: StoreEntry): CheckResult => {
-  const label = `package.json minDegoogVersion >= ${CHALLENGES_MIN_DEGOOG_VERSION}`
+const validateMinVersion = (entry: StoreEntry, minimum: string, who: string): CheckResult => {
+  const label = `package.json minDegoogVersion >= ${minimum}`
   const v = entry.minDegoogVersion
   if (typeof v !== "string" || v.trim() === "") {
-    return {
-      label,
-      status: "warn",
-      detail: `missing - engines that set "challenges" need degoog ${CHALLENGES_MIN_DEGOOG_VERSION} or newer`,
-    }
+    return { label, status: "warn", detail: `missing - ${who} need degoog ${minimum} or newer` }
   }
-  if (!isVersionAtLeast(v, CHALLENGES_MIN_DEGOOG_VERSION)) {
-    return {
-      label,
-      status: "warn",
-      detail: `set to ${v} - engines that set "challenges" need degoog ${CHALLENGES_MIN_DEGOOG_VERSION} or newer`,
-    }
+  if (!isVersionAtLeast(v, minimum)) {
+    return { label, status: "warn", detail: `set to ${v} - ${who} need degoog ${minimum} or newer` }
   }
   return { label, status: "pass" }
 }
+
+export const validateChallengesMinVersion = (entry: StoreEntry): CheckResult =>
+  validateMinVersion(entry, CHALLENGES_MIN_DEGOOG_VERSION, 'engines that set "challenges"')
+
+export const validateFaviconSignerMinVersion = (entry: StoreEntry): CheckResult =>
+  validateMinVersion(entry, FAVICON_SIGNER_MIN_DEGOOG_VERSION, "plugins that call signFaviconUrl")
diff --git a/src/commands/doctor/store.ts b/src/commands/doctor/store.ts
index 5f05e5f..c6948cc 100644
--- a/src/commands/doctor/store.ts
+++ b/src/commands/doctor/store.ts
@@ -3,7 +3,7 @@ import { join, basename } from "node:path"
 import { t } from "../../utils/theme"
 import { ui } from "../../utils/ui"
 import { exists } from "./detect"
-import { declaresChallenges, runChecks } from "./checks"
+import { declaresChallenges, runChecks, usesFaviconSigner } from "./checks"
 import { printResults } from "./report"
 import {
   validateTopLevel,
@@ -11,6 +11,7 @@ import {
   validatePathExistence,
   findDuplicateEntries,
   validateChallengesMinVersion,
+  validateFaviconSignerMinVersion,
 } from "./store-validate"
 import { collectOrphans, resolveOrphans } from "./store-orphans"
 import {
@@ -127,6 +128,9 @@ const runExtensionChecks = async (
       if (kind === "engine" && (await declaresChallenges(full))) {
         results.push(validateChallengesMinVersion(entry))
       }
+      if (kind === "plugin" && (await usesFaviconSigner(full))) {
+        results.push(validateFaviconSignerMinVersion(entry))
+      }
       printResults(results)
       tallyResults(results, summary)
     }
diff --git a/src/commands/doctor/types.ts b/src/commands/doctor/types.ts
index 04e9844..f53845e 100644
--- a/src/commands/doctor/types.ts
+++ b/src/commands/doctor/types.ts
@@ -36,6 +36,8 @@ export const ENGINE_CHALLENGES: readonly string[] = ["anubis"]
 
 export const CHALLENGES_MIN_DEGOOG_VERSION = "1.0.0"
 
+export const FAVICON_SIGNER_MIN_DEGOOG_VERSION = "1.0.0"
+
 export type StoreEntry = {
   path?: string
   name?: string
diff --git a/src/generators/plugin-bang.ts b/src/generators/plugin-bang.ts
index 17fc0ed..869944b 100644
--- a/src/generators/plugin-bang.ts
+++ b/src/generators/plugin-bang.ts
@@ -54,6 +54,8 @@ export default {
   //   ctx.routeUrl // (path) => /api/plugin/<ctx.pluginId>/<path>
   //   ctx.dir      // absolute path to plugin folder (do NOT derive route IDs from it)
   //   ctx.readFile // async file reader
+  //   ctx.signProxyUrl   // (url) => signed /api/proxy/image URL for an external image
+  //   ctx.signFaviconUrl // (url) => signed /api/proxy/favicon URL for the url's host, "" when no favicon provider is enabled
   // },
 
   async execute(args: string, context: {
diff --git a/src/generators/plugin-intercept.ts b/src/generators/plugin-intercept.ts
index 23a62fb..dd272a8 100644
--- a/src/generators/plugin-intercept.ts
+++ b/src/generators/plugin-intercept.ts
@@ -30,6 +30,8 @@ export const interceptor = {
   //   ctx.routeUrl // (path) => /api/plugin/<ctx.pluginId>/<path>
   //   ctx.dir      // absolute path to plugin folder (do NOT derive route IDs from it)
   //   ctx.readFile // async file reader
+  //   ctx.signProxyUrl   // (url) => signed /api/proxy/image URL for an external image
+  //   ctx.signFaviconUrl // (url) => signed /api/proxy/favicon URL for the url's host, "" when no favicon provider is enabled
   // },
 
   async intercept(query: string, context: {
diff --git a/src/generators/plugin-slot.ts b/src/generators/plugin-slot.ts
index e9cf8e7..6a3dd9e 100644
--- a/src/generators/plugin-slot.ts
+++ b/src/generators/plugin-slot.ts
@@ -22,7 +22,7 @@ export const slot = {
   /**
    * Set to true if your execute() returns HTML that causes the browser
    * to fetch external URLs (images, scripts, etc.).
-   * Set to false if all network access goes through context.fetch / signProxyUrl.
+   * Set to false if all network access goes through context.fetch / signProxyUrl / signFaviconUrl.
    * Leaving this unset shows an ambiguous badge in the degoog settings page.
    */
   isClientExposed: false,
@@ -43,6 +43,8 @@ export const slot = {
   //   ctx.routeUrl // (path) => /api/plugin/<ctx.pluginId>/<path>
   //   ctx.dir      // absolute path to plugin folder (do NOT derive route IDs from it)
   //   ctx.readFile // async file reader
+  //   ctx.signProxyUrl   // (url) => signed /api/proxy/image URL for an external image
+  //   ctx.signFaviconUrl // (url) => signed /api/proxy/favicon URL for the url's host, "" when no favicon provider is enabled
   // },
 
   async trigger(query: string): Promise<boolean> {
@@ -54,6 +56,7 @@ export const slot = {
     dir: string
     readFile: (filename: string) => Promise<string>
     signProxyUrl: (url: string) => string
+    signFaviconUrl: (url: string) => string
     fetch: typeof fetch
     useCache: <T>(namespace: string, defaultTtlMs: number) => {
       get: (key: string) => Promise<T | null>
diff --git a/src/generators/plugin-tab.ts b/src/generators/plugin-tab.ts
index 3b3599a..87e4cdb 100644
--- a/src/generators/plugin-tab.ts
+++ b/src/generators/plugin-tab.ts
@@ -42,6 +42,8 @@ export const tab = {
   //   ctx.routeUrl // (path) => /api/plugin/<ctx.pluginId>/<path>
   //   ctx.dir      // absolute path to plugin folder (do NOT derive route IDs from it)
   //   ctx.readFile // async file reader
+  //   ctx.signProxyUrl   // (url) => signed /api/proxy/image URL for an external image
+  //   ctx.signFaviconUrl // (url) => signed /api/proxy/favicon URL for the url's host, "" when no favicon provider is enabled
   // },
   // dependencies: [],