= {
summary:
"The underlying model provider (e.g. Anthropic, Google) returned a non-success response. No tokens were charged against your quota.",
causes: [
- "The model ID is wrong or unsupported by Vercel AI Gateway.",
+ "The model ID is wrong or unsupported by the provider you're routed to (Gateway, Anthropic, or OpenAI direct).",
"Upstream provider is degraded.",
"The prompt triggered a provider-side safety filter.",
],
diff --git a/apps/web/app/(main)/waitlist/page.tsx b/apps/web/app/(main)/waitlist/page.tsx
index 39b7778..e7fdeee 100644
--- a/apps/web/app/(main)/waitlist/page.tsx
+++ b/apps/web/app/(main)/waitlist/page.tsx
@@ -42,8 +42,8 @@ async function WaitlistContent({
Need more tokens right now?{" "}
-
- Bring your own Vercel AI Gateway key
+
+ Bring your own key (Anthropic, OpenAI, or Gateway)
{" "}
— unlimited, your own cost.
diff --git a/apps/web/content/guides/byok.mdx b/apps/web/content/guides/byok.mdx
index b09b1b3..810c7a0 100644
--- a/apps/web/content/guides/byok.mdx
+++ b/apps/web/content/guides/byok.mdx
@@ -1,40 +1,41 @@
---
schemaVersion: 1
-title: "Bring your own Gateway key (BYOK)"
-description: "When and how to bypass the helpbase hosted proxy with your own Vercel AI Gateway key. For CI, power users, and privacy-sensitive workflows."
+title: "Bring your own key (BYOK)"
+description: "Three ways to skip the helpbase hosted proxy and call your LLM provider directly. For CI, power users, and privacy-sensitive workflows."
tags: ["byok", "advanced", "ci"]
order: 99
featured: false
---
-helpbase is free to use with a one-command login — 500,000 tokens per day, no
-credit card. That covers most people.
+helpbase is free to use with a one-command login — 500,000 tokens per day,
+no credit card. That covers most people.
You might want your own key instead when:
-- **You're running in CI.** helpbase sessions are designed for interactive use;
- machines need a token.
-- **You're already paying for Vercel AI Gateway.** Route everything through
- the account you already meter and bill.
+- **You're running in CI.** helpbase sessions are designed for interactive
+ use; machines need a token they already have.
+- **You already have a provider key.** Most teams have an Anthropic or OpenAI
+ key lying around. Use it directly — no second provider to sign up for.
- **Free-tier limits are too low for your workload.** 500k/day is ~10 full
- `generate` runs or ~250 `context --ask` calls. If you run more, BYOK is
- unlimited (well — limited to your own Gateway spend cap).
-- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct
- to Vercel AI Gateway. helpbase never sees your prompts.
+ `generate` runs or ~250 `context --ask` calls. BYOK is unlimited (within
+ your provider's own spend cap).
+- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct to
+ your provider. helpbase never sees your prompts.
-## How it works
+## Three keys, any one works
-Set `AI_GATEWAY_API_KEY` in your environment. That's it. The CLI detects it
-and bypasses the helpbase proxy for every LLM call:
+Set whichever one you already have. First key found wins; precedence is
+`AI_GATEWAY_API_KEY` > `ANTHROPIC_API_KEY` > `OPENAI_API_KEY`.
-```bash
-export AI_GATEWAY_API_KEY=vck_live_...
-helpbase generate --url https://docs.example.com
-```
+| Env var | Routes to | Use when |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | `@ai-sdk/anthropic` direct | You already have an Anthropic key. Pair with `--model anthropic/`. |
+| `OPENAI_API_KEY` | `@ai-sdk/openai` direct | You already have an OpenAI key. Pair with `--model openai/`. |
+| `AI_GATEWAY_API_KEY` | [Vercel AI Gateway](https://vercel.com/ai-gateway) | You want one key to route any provider (Anthropic, OpenAI, Google, etc.) with one bill. |
```
┌──────────────────┐
-│ helpbase CLI │─────► Vercel AI SDK direct ─────► Vercel AI Gateway
+│ helpbase CLI │─────► Vercel AI SDK direct ─────► your provider
│ │ (your key, your bill)
└──────────────────┘
(no quota check, no usage log, no helpbase.dev round-trip)
@@ -43,7 +44,43 @@ helpbase generate --url https://docs.example.com
No changes to prompts, no different models — same output as the hosted
path, just routed direct.
-## Getting a key
+## Anthropic direct
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+helpbase generate --url https://docs.example.com \
+ --model anthropic/claude-3-5-sonnet-latest
+```
+
+The `--model` prefix must be `anthropic/` when only `ANTHROPIC_API_KEY` is
+set. Any other prefix will error with a clear message telling you the
+exact command to try instead.
+
+Get a key at [console.anthropic.com](https://console.anthropic.com).
+
+## OpenAI direct
+
+```bash
+export OPENAI_API_KEY=sk-...
+helpbase generate --url https://docs.example.com \
+ --model openai/gpt-4o-mini
+```
+
+Same rule: the `--model` prefix must be `openai/` when only `OPENAI_API_KEY`
+is set.
+
+Get a key at [platform.openai.com](https://platform.openai.com).
+
+## Vercel AI Gateway (multi-provider)
+
+```bash
+export AI_GATEWAY_API_KEY=vck_live_...
+helpbase generate --url https://docs.example.com
+# Any --model works:
+helpbase generate --url https://docs.example.com --model anthropic/claude-sonnet-4.6
+helpbase generate --url https://docs.example.com --model google/gemini-3.1-flash-lite-preview
+helpbase generate --url https://docs.example.com --model openai/gpt-4o-mini
+```
1. Sign in at [vercel.com/ai-gateway](https://vercel.com/ai-gateway).
2. Create an API key.
@@ -52,25 +89,24 @@ path, just routed direct.
## CI usage
-In GitHub Actions and other CI, set `AI_GATEWAY_API_KEY` as a repo secret
-and pass it through:
+In GitHub Actions and other CI, set whichever key you use as a repo secret:
```yaml
- run: helpbase generate --url https://docs.example.com
env:
- AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```
CI users don't need `helpbase login`. If you still want to run `helpbase
deploy` from CI (which requires a helpbase account), set `HELPBASE_TOKEN`
-as well — that's the helpbase session, separate from the Gateway key.
+as well — that's the helpbase session, separate from the provider key.
## Switching back to hosted
-Unset the env var:
+Unset whichever key is active:
```bash
-unset AI_GATEWAY_API_KEY
+unset ANTHROPIC_API_KEY # or OPENAI_API_KEY, or AI_GATEWAY_API_KEY
```
The next CLI command will use the helpbase hosted proxy again. No state to
@@ -82,32 +118,35 @@ clear, no account to delete.
helpbase whoami
```
-If `AI_GATEWAY_API_KEY` is set, `whoami` will show "BYOK mode active — calls
-bypass helpbase (no quota applied)". Otherwise it shows your usage against
-the free-tier cap.
+`whoami` names the active key if BYOK is on: "BYOK mode: `ANTHROPIC_API_KEY`
+is set — calls bypass helpbase (no quota applied)". Otherwise it shows your
+usage against the free-tier cap.
## Costs
-BYOK costs are whatever Gateway charges for the model you pick. As of this
-writing the default and `--test` are both `google/gemini-3.1-flash-lite-preview`
-(cheap + fast, ~1M context). Rough costs for a 9-article `helpbase generate`
-run (~50,000 tokens):
+BYOK costs are whatever your provider charges for the model you pick.
+Rough costs for a 9-article `helpbase generate` run (~50,000 tokens):
-- Gemini 3.1 Flash Lite (default / `--test`): ~$0.004 per run.
+- Gemini 3.1 Flash Lite (Gateway default, `--test`): ~$0.004 per run.
- Claude Sonnet 4.6 (`--model anthropic/claude-sonnet-4.6`): ~$0.20–0.40.
- GPT-4o-mini (`--model openai/gpt-4o-mini`): ~$0.01–0.03.
## Troubleshooting
-**"AI_GATEWAY_API_KEY is not set" but I just exported it.** New terminal sessions
-don't see variables from old sessions. Re-export in the current shell, or
-persist in `.env.local`.
+**"ANTHROPIC_API_KEY is set but the model is '...'"** Direct-key mode
+requires the `--model` prefix to match your key. Either pass
+`--model anthropic/`, or set `AI_GATEWAY_API_KEY` instead to route any
+provider through Gateway.
+
+**"`ANTHROPIC_API_KEY` is not set" but I just exported it.** New terminal
+sessions don't see variables from old sessions. Re-export in the current
+shell, or persist in `.env.local`.
-**"BYOK mode active" but I want to use hosted.** Run `unset
-AI_GATEWAY_API_KEY`. You can also delete the line from `.env.local`.
+**"BYOK mode active" but I want to use hosted.** Run `unset `
+using whichever key `helpbase whoami` names. You can also delete the line
+from `.env.local`.
**CI passes the env var but still shows "not signed in".** `helpbase login`
-and `AI_GATEWAY_API_KEY` serve different purposes. Login is for hosted
-quota + deploy authorization. BYOK bypasses quota only. For deploy in CI,
-you also need `HELPBASE_TOKEN` (a helpbase session token) alongside the
-Gateway key.
+and BYOK serve different purposes. Login is for hosted quota + deploy
+authorization. BYOK bypasses quota only. For deploy in CI, you also need
+`HELPBASE_TOKEN` (a helpbase session token) alongside your provider key.
diff --git a/apps/web/content/guides/sync-in-5-minutes.mdx b/apps/web/content/guides/sync-in-5-minutes.mdx
index 0353613..ad6c75f 100644
--- a/apps/web/content/guides/sync-in-5-minutes.mdx
+++ b/apps/web/content/guides/sync-in-5-minutes.mdx
@@ -47,9 +47,10 @@ Magic-link flow. Free tier is 500,000 tokens per day — enough for roughly 10
full generates or 250 `context --ask` calls.
-Prefer your own key? Set `AI_GATEWAY_API_KEY` and helpbase will route through
-your Vercel AI Gateway account instead. See
-[helpbase.dev/docs/byok](https://helpbase.dev/docs/byok).
+Prefer your own key? Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or
+`AI_GATEWAY_API_KEY` — helpbase routes direct to whichever provider you set
+(first found wins). See
+[helpbase.dev/guides/byok](https://helpbase.dev/guides/byok).
## Step 3 — Make a code change worth documenting
diff --git a/apps/web/public/r/helpbase-workflow.json b/apps/web/public/r/helpbase-workflow.json
index 9b8ea77..8ceb02f 100644
--- a/apps/web/public/r/helpbase-workflow.json
+++ b/apps/web/public/r/helpbase-workflow.json
@@ -12,7 +12,7 @@
},
{
"path": "registry/helpbase-workflow/README.md",
- "content": "# helpbase-workflow\n\nDrop-in GitHub Actions workflow that runs `helpbase sync` on a schedule and\non every push to your main branch. When a code change would make an MDX\ndoc wrong, the workflow opens a PR with the proposed update, grounded in\ncitations into your source.\n\nNo SaaS in the path. Runs in your Actions minutes, reads your secrets,\nwrites to your repo.\n\n## Install\n\n```bash\nnpx shadcn add https://helpbase.dev/r/helpbase-workflow.json\n```\n\nThat drops a single file into your repo:\n\n```\n.github/workflows/helpbase-sync.yml\n```\n\n## Configure\n\nAdd one secret to your GitHub repo (**Settings → Secrets and variables →\nActions → New repository secret**). You have two options:\n\n- **`AI_GATEWAY_API_KEY`** (recommended for CI) — your key from\n [vercel.com/ai-gateway](https://vercel.com/ai-gateway). Bypasses helpbase's\n hosted proxy entirely. Your Gateway account, your bill, no daily quota\n limit. See [helpbase.dev/docs/byok](https://helpbase.dev/docs/byok).\n- **`HELPBASE_TOKEN`** — a helpbase session access token. After running\n `helpbase login` locally, pull the value from `~/.helpbase/auth.json`:\n `jq -r .access_token ~/.helpbase/auth.json`. Uses helpbase's hosted proxy\n and the free-tier 500k tokens/day cap. Note: session tokens are relatively\n short-lived — rotate the secret when it expires.\n\nIf both are set, `AI_GATEWAY_API_KEY` wins (BYOK mode).\n\n`GH_TOKEN` is read from `github.token` automatically, so you don't need\nto provision it manually.\n\n## Customize\n\nThe workflow ships with sensible defaults you'll likely want to tweak:\n\n- **Schedule** — default is Monday 09:00 UTC (`cron: \"0 9 * * 1\"`). Edit\n the `cron` line to match when your team starts the week.\n- **Base branch** — default assumes `main`. Change both `branches: [main]`\n under `push:` and `--since origin/main` in the run step if you use\n `master`, `trunk`, or something else.\n- **Content directory** — default assumes `content/`. If your docs live\n elsewhere, append `--content docs/` to the `helpbase sync` command.\n\n## What the PR looks like\n\nEvery edit in the generated PR carries a `citations` trailer pointing at\nspecific lines of source code that justified the change. Review those\ncitations first — if a citation is missing or wrong, reject the PR; the\nschema makes this rare but not impossible.\n\n## Run locally\n\nTo preview what the workflow would propose, run the same command on your\nmachine:\n\n```bash\nAI_GATEWAY_API_KEY=your_key_here \\\n npx helpbase sync --since origin/main --dry-run\n```\n\nDrop `--dry-run` when you're ready to see the real proposals.\n",
+ "content": "# helpbase-workflow\n\nDrop-in GitHub Actions workflow that runs `helpbase sync` on a schedule and\non every push to your main branch. When a code change would make an MDX\ndoc wrong, the workflow opens a PR with the proposed update, grounded in\ncitations into your source.\n\nNo SaaS in the path. Runs in your Actions minutes, reads your secrets,\nwrites to your repo.\n\n## Install\n\n```bash\nnpx shadcn add https://helpbase.dev/r/helpbase-workflow.json\n```\n\nThat drops a single file into your repo:\n\n```\n.github/workflows/helpbase-sync.yml\n```\n\n## Configure\n\nAdd one secret to your GitHub repo (**Settings → Secrets and variables →\nActions → New repository secret**). You have two options:\n\n- **Any BYOK key** (recommended for CI) — `ANTHROPIC_API_KEY`,\n `OPENAI_API_KEY`, or `AI_GATEWAY_API_KEY`. Bypasses helpbase's hosted\n proxy entirely. Your provider account, your bill, no daily quota\n limit. First key found wins. See\n [helpbase.dev/guides/byok](https://helpbase.dev/guides/byok).\n- **`HELPBASE_TOKEN`** — a helpbase session access token. After running\n `helpbase login` locally, pull the value from `~/.helpbase/auth.json`:\n `jq -r .access_token ~/.helpbase/auth.json`. Uses helpbase's hosted proxy\n and the free-tier 500k tokens/day cap. Note: session tokens are relatively\n short-lived — rotate the secret when it expires.\n\nIf both are set, `AI_GATEWAY_API_KEY` wins (BYOK mode).\n\n`GH_TOKEN` is read from `github.token` automatically, so you don't need\nto provision it manually.\n\n## Customize\n\nThe workflow ships with sensible defaults you'll likely want to tweak:\n\n- **Schedule** — default is Monday 09:00 UTC (`cron: \"0 9 * * 1\"`). Edit\n the `cron` line to match when your team starts the week.\n- **Base branch** — default assumes `main`. Change both `branches: [main]`\n under `push:` and `--since origin/main` in the run step if you use\n `master`, `trunk`, or something else.\n- **Content directory** — default assumes `content/`. If your docs live\n elsewhere, append `--content docs/` to the `helpbase sync` command.\n\n## What the PR looks like\n\nEvery edit in the generated PR carries a `citations` trailer pointing at\nspecific lines of source code that justified the change. Review those\ncitations first — if a citation is missing or wrong, reject the PR; the\nschema makes this rare but not impossible.\n\n## Run locally\n\nTo preview what the workflow would propose, run the same command on your\nmachine:\n\n```bash\nAI_GATEWAY_API_KEY=your_key_here \\\n npx helpbase sync --since origin/main --dry-run\n```\n\nDrop `--dry-run` when you're ready to see the real proposals.\n",
"type": "registry:file",
"target": ".github/workflows/helpbase-sync.README.md"
}
diff --git a/package.json b/package.json
index 202ac6e..c73b626 100644
--- a/package.json
+++ b/package.json
@@ -18,6 +18,7 @@
"smoke:deploy": "bash scripts/smoke-deploy.sh",
"eval:hosted-parity": "node packages/cli/eval/run-hosted-parity.mjs",
"check:supabase-types": "node scripts/check-supabase-types.mjs",
+ "check:links": "bash scripts/check-links.sh",
"sync:templates": "node scripts/sync-templates.mjs"
},
"devDependencies": {
diff --git a/packages/cli/src/commands/context.ts b/packages/cli/src/commands/context.ts
index 519db55..bf717c2 100644
--- a/packages/cli/src/commands/context.ts
+++ b/packages/cli/src/commands/context.ts
@@ -85,8 +85,9 @@ Examples:
$ helpbase context . --only auth # regen just one category
$ helpbase context . --require-clean # fail if tree is dirty (CI mode)
-Pick one: set ${pc.cyan("ANTHROPIC_API_KEY")}, ${pc.cyan("OPENAI_API_KEY")}, or ${pc.cyan("AI_GATEWAY_API_KEY")}.
-BYOK — helpbase calls the provider directly. First key found wins; --model overrides.
+Auth: run ${pc.cyan("helpbase login")} (free, 500k tokens/day, no card)
+ OR export one of ${pc.cyan("ANTHROPIC_API_KEY")} / ${pc.cyan("OPENAI_API_KEY")} / ${pc.cyan("AI_GATEWAY_API_KEY")}
+ (BYOK — first key found wins; --model overrides)
`,
)
.action(async (repoPathArg: string, opts) => {
diff --git a/packages/cli/src/commands/generate.ts b/packages/cli/src/commands/generate.ts
index 2dbae18..c41e458 100644
--- a/packages/cli/src/commands/generate.ts
+++ b/packages/cli/src/commands/generate.ts
@@ -68,7 +68,8 @@ Examples:
$ helpbase generate --screenshots ./flow --title "How to invite a teammate"
$ helpbase generate --url https://myproduct.com --dry-run # preview without spending tokens
-Set AI_GATEWAY_API_KEY first — get a key at https://vercel.com/ai-gateway.
+Auth: run ${"`helpbase login`"} (free, 500k tokens/day) OR export one of
+${"ANTHROPIC_API_KEY"} / ${"OPENAI_API_KEY"} / ${"AI_GATEWAY_API_KEY"} (BYOK, first found wins).
`,
)
.action(async (repoPath: string | undefined, opts) => {
@@ -301,7 +302,7 @@ Set AI_GATEWAY_API_KEY first — get a key at https://vercel.com/ai-gateway.
`\n${pc.red("✖")} Generated file has invalid frontmatter: ${plan.filePath}\n` +
` Reason: ${parseErr instanceof Error ? parseErr.message : "parse error"}\n` +
` Fix: This is a bug in articleToMdx — please file an issue with the file contents.\n` +
- ` Docs: https://helpbase.dev/docs/troubleshooting#bad-frontmatter\n`,
+ ` Docs: https://helpbase.dev/errors/e-invalid-frontmatter\n`,
)
process.exit(1)
}
@@ -437,7 +438,7 @@ Set AI_GATEWAY_API_KEY first — get a key at https://vercel.com/ai-gateway.
`\n${pc.red("✖")} Generated file has invalid frontmatter: ${plan.filePath}\n` +
` Reason: ${parseErr instanceof Error ? parseErr.message : "parse error"}\n` +
` Fix: This is a bug in articleToMdx — please file an issue with the file contents.\n` +
- ` Docs: https://helpbase.dev/docs/troubleshooting#bad-frontmatter\n`,
+ ` Docs: https://helpbase.dev/errors/e-invalid-frontmatter\n`,
)
process.exit(1)
}
@@ -559,7 +560,7 @@ Set AI_GATEWAY_API_KEY first — get a key at https://vercel.com/ai-gateway.
`\n${pc.red("✖")} Generated file has invalid frontmatter: ${plan.filePath}\n` +
` Reason: ${parseErr instanceof Error ? parseErr.message : "parse error"}\n` +
` Fix: This is a bug in articleToMdx — please file an issue with the file contents.\n` +
- ` Docs: https://helpbase.dev/docs/troubleshooting#bad-frontmatter\n`,
+ ` Docs: https://helpbase.dev/errors/e-invalid-frontmatter\n`,
)
process.exit(1)
}
@@ -612,7 +613,7 @@ function printRepoError(repoPath: string, err: unknown): void {
`\n${pc.red("✖")} Could not read repository ${pc.cyan(repoPath)}\n` +
` Reason: ${reason}\n` +
` Fix: Pass a local path to a directory with markdown files (e.g. ${pc.cyan("--repo .")}).\n` +
- ` Docs: https://helpbase.dev/docs/troubleshooting#generate-errors\n`,
+ ` Docs: https://helpbase.dev/cli/commands\n`,
)
}
@@ -622,7 +623,7 @@ function printScrapeError(url: string, err: unknown): void {
`\n${pc.red("✖")} Could not generate articles from ${pc.cyan(url)}\n` +
` Reason: ${reason}\n` +
` Fix: Check the URL is accessible and try again.\n` +
- ` Docs: https://helpbase.dev/docs/troubleshooting#generate-errors\n`,
+ ` Docs: https://helpbase.dev/cli/commands\n`,
)
}
@@ -645,9 +646,9 @@ function printGenerateError(err: unknown, opts?: { url?: string; repo?: string;
// scaffolder / scripts that bypass the command layer.
console.error(
`\n${pc.red("✖")} Could not generate articles\n` +
- ` Reason: Not signed in and no AI_GATEWAY_API_KEY is set.\n` +
+ ` Reason: Not signed in and no BYOK key is set.\n` +
` Fix: Run ${pc.cyan("helpbase login")} (free, no card), then re-run.\n` +
- ` Or bring your own key: ${pc.cyan("export AI_GATEWAY_API_KEY=...")} (docs: helpbase.dev/docs/byok)\n`,
+ ` Or bring your own key: ${pc.cyan("ANTHROPIC_API_KEY")}, ${pc.cyan("OPENAI_API_KEY")}, or ${pc.cyan("AI_GATEWAY_API_KEY")} (docs: helpbase.dev/guides/byok)\n`,
)
return
}
@@ -658,7 +659,7 @@ function printGenerateError(err: unknown, opts?: { url?: string; repo?: string;
` Reason: ${err.message}\n` +
` Fix: Check the model ID is valid and your Gateway quota is not exhausted.\n` +
` Try ${pc.cyan("--test")} to use a cheap fallback model, or ${pc.cyan("--model ")} to override.\n` +
- ` Docs: https://helpbase.dev/docs/troubleshooting#gateway-errors\n`,
+ ` Docs: https://helpbase.dev/errors/e-llm-gateway\n`,
)
return
}
@@ -668,7 +669,7 @@ function printGenerateError(err: unknown, opts?: { url?: string; repo?: string;
`\n${pc.red("✖")} Could not generate articles\n` +
` Reason: ${reason}\n` +
` Fix: Check the source and try again.\n` +
- ` Docs: https://helpbase.dev/docs/troubleshooting#generate-errors\n`,
+ ` Docs: https://helpbase.dev/cli/commands\n`,
)
}
diff --git a/packages/cli/src/commands/sync.ts b/packages/cli/src/commands/sync.ts
index 8eff0f3..aa80307 100644
--- a/packages/cli/src/commands/sync.ts
+++ b/packages/cli/src/commands/sync.ts
@@ -160,12 +160,12 @@ Set AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway
if (err instanceof MissingApiKeyError) {
throw new HelpbaseError({
code: "E_AUTH_REQUIRED",
- problem: "Not signed in and no AI_GATEWAY_API_KEY set",
+ problem: "Not signed in and no BYOK key set",
cause: "helpbase sync calls an LLM to propose doc edits; it needs auth or a BYOK key.",
fix: [
`Run ${pc.cyan("helpbase login")} (free, no card), then re-run.`,
- `Or bring your own key: ${pc.cyan("export AI_GATEWAY_API_KEY=...")}`,
- "Docs: https://helpbase.dev/docs/byok",
+ `Or bring your own key: ${pc.cyan("ANTHROPIC_API_KEY")}, ${pc.cyan("OPENAI_API_KEY")}, or ${pc.cyan("AI_GATEWAY_API_KEY")} (first found wins).`,
+ "Docs: https://helpbase.dev/guides/byok",
],
})
}
@@ -373,5 +373,5 @@ async function runDemo(_opts: SyncOptions): Promise {
process.stdout.write(rendered + "\n")
note("")
ok(`Demo complete — ${proposals.length} proposal${proposals.length === 1 ? "" : "s"}, all citation-grounded.`)
- info(`Next: ${pc.cyan("export AI_GATEWAY_API_KEY=...")} and run ${pc.cyan("helpbase sync")} in your repo.`)
+ info(`Next: run ${pc.cyan("helpbase login")} (free) or export ${pc.cyan("ANTHROPIC_API_KEY")} / ${pc.cyan("OPENAI_API_KEY")} / ${pc.cyan("AI_GATEWAY_API_KEY")}, then ${pc.cyan("helpbase sync")} in your repo.`)
}
diff --git a/packages/cli/src/lib/auth-device.ts b/packages/cli/src/lib/auth-device.ts
index 3118dd2..84b9499 100644
--- a/packages/cli/src/lib/auth-device.ts
+++ b/packages/cli/src/lib/auth-device.ts
@@ -36,7 +36,11 @@ export async function deviceLogin(opts: DeviceLoginOptions = {}): Promise {
- if (process.env.AI_GATEWAY_API_KEY) {
+ // Any of AI_GATEWAY_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY skips
+ // the hosted-login prompt. The downstream `callLlmObject` / `callLlmText`
+ // branch on isByokMode() too, so this keeps the UI consistent with the
+ // actual LLM-call routing.
+ if (isByokMode()) {
return { byok: true }
}
diff --git a/packages/cli/src/lib/llm-errors-cli.ts b/packages/cli/src/lib/llm-errors-cli.ts
index e00cc03..2b0d809 100644
--- a/packages/cli/src/lib/llm-errors-cli.ts
+++ b/packages/cli/src/lib/llm-errors-cli.ts
@@ -52,6 +52,17 @@ export function authRequiredError(retryCommand?: string): HelpbaseError {
})
}
+/**
+ * Shared BYOK hint line. One source of truth so every stale "Gateway-only"
+ * error copy updates in lockstep when the set of accepted keys changes.
+ */
+function byokHint(): string {
+ return (
+ `Or bring your own key: ${pc.cyan("ANTHROPIC_API_KEY")}, ${pc.cyan("OPENAI_API_KEY")}, or ${pc.cyan("AI_GATEWAY_API_KEY")} ` +
+ `(any one works, first found wins)`
+ )
+}
+
export function quotaExceededError(
err: QuotaExceededError,
retryCommand?: string,
@@ -65,7 +76,7 @@ export function quotaExceededError(
problem: `You've used today's free allocation (${used} / ${cap} tokens). Resets in ${reset}.`,
fix: [
`Join the waitlist for the paid tier → ${pc.cyan(err.upgradeUrl)}${rerun}`,
- `Or use your own Vercel AI Gateway key: ${pc.cyan("export AI_GATEWAY_API_KEY=...")}`,
+ byokHint(),
`Docs: ${pc.cyan(err.byokDocsUrl)}`,
],
})
@@ -78,7 +89,7 @@ export function globalCapError(err: GlobalCapError): HelpbaseError {
problem: `helpbase is over its daily cap. Retry in ${reset}.`,
fix: [
"Wait for the daily reset.",
- `Or use your own Vercel AI Gateway key: ${pc.cyan("export AI_GATEWAY_API_KEY=...")}`,
+ byokHint(),
`Docs: ${pc.cyan(err.byokDocsUrl)}`,
],
})
@@ -92,7 +103,7 @@ export function llmNetworkError(err: LlmNetworkError): HelpbaseError {
fix: [
"Check your internet connection.",
"Retry — transient network blips are common.",
- `Or bypass the proxy entirely: ${pc.cyan("export AI_GATEWAY_API_KEY=...")} (your own key).`,
+ `${byokHint()} — all three bypass the proxy.`,
],
})
}
diff --git a/packages/create-helpbase/HELPBASE.md.template b/packages/create-helpbase/HELPBASE.md.template
index 97595c9..eb45f6c 100644
--- a/packages/create-helpbase/HELPBASE.md.template
+++ b/packages/create-helpbase/HELPBASE.md.template
@@ -74,4 +74,4 @@ and OS.
## Full reference
`helpbase --help` for any command. Full reference:
-.
+.
diff --git a/packages/create-helpbase/src/env-local.ts b/packages/create-helpbase/src/env-local.ts
deleted file mode 100644
index 338d71c..0000000
--- a/packages/create-helpbase/src/env-local.ts
+++ /dev/null
@@ -1,34 +0,0 @@
-import fs from "node:fs"
-import path from "node:path"
-
-/**
- * Write `AI_GATEWAY_API_KEY=` into the scaffolded project's
- * `.env.local`. Idempotent: if the key already exists, replace the line.
- * If `.env.local` doesn't exist, create it. Next.js + the helpbase CLI
- * both read `.env.local` at the project root, so one file serves both.
- */
-export function writeAiGatewayKey(projectDir: string, key: string): void {
- const envPath = path.join(projectDir, ".env.local")
- const line = `AI_GATEWAY_API_KEY=${key}`
-
- if (!fs.existsSync(envPath)) {
- fs.writeFileSync(envPath, `${line}\n`, { mode: 0o600 })
- return
- }
-
- const existing = fs.readFileSync(envPath, "utf-8")
- const lines = existing.split("\n")
- let replaced = false
- const next = lines.map((l) => {
- if (l.startsWith("AI_GATEWAY_API_KEY=")) {
- replaced = true
- return line
- }
- return l
- })
- if (!replaced) {
- if (next.length > 0 && next[next.length - 1] !== "") next.push(line)
- else next.splice(next.length - 1, 0, line)
- }
- fs.writeFileSync(envPath, next.join("\n"), { mode: 0o600 })
-}
diff --git a/packages/create-helpbase/src/index.ts b/packages/create-helpbase/src/index.ts
index 2e2f193..9d79e59 100644
--- a/packages/create-helpbase/src/index.ts
+++ b/packages/create-helpbase/src/index.ts
@@ -19,8 +19,8 @@ import {
generateArticlesFromContent,
} from "@workspace/shared/ai-text"
import { scaffoldProject, clearSampleContent } from "./scaffold.js"
-import { writeAiGatewayKey } from "./env-local.js"
import { readHelpbaseAuthToken } from "./auth.js"
+import { isByokMode } from "@workspace/shared/llm"
import {
generateFromRepo,
AllDocsDroppedError,
@@ -153,44 +153,23 @@ async function run(directory: string | undefined, opts: RunOptions) {
// 3. Auth resolution — conditional on existing state.
// Skip entirely when the user already has a helpbase session on disk
- // or AI_GATEWAY_API_KEY set. Otherwise offer a three-way choice that
- // leads with `helpbase login` (free, captures email) instead of
- // asking for a Vercel Gateway key most users don't have.
- // Saves ~10-15s of dead-air friction for returning developers, and
- // surfaces the login path in the CLI where evaluation actually
- // happens, instead of hiding it behind an error message.
+ // or any BYOK env var set (ANTHROPIC_API_KEY / OPENAI_API_KEY /
+ // AI_GATEWAY_API_KEY via isByokMode()).
+ // Otherwise offer a single confirm — the target persona (YC founder
+ // with no key) always picks "log in free," so a 3-way select was
+ // cognitive noise. BYOK users route via env var before running;
+ // paste-a-key was removed to cut prompt count for the common path.
let authToken = readHelpbaseAuthToken()
- const byokAlreadyResolved = Boolean(process.env.AI_GATEWAY_API_KEY)
- let aiGatewayKey: string | undefined
- if (isInteractive && source.kind !== "skip" && !authToken && !byokAlreadyResolved) {
- const authChoice = await select({
- message: "AI generation needs auth. Pick one:",
- options: [
- {
- value: "login",
- label: "Log in (free, no card, 500k tokens/day)",
- hint: "runs `helpbase login` — 30 seconds",
- },
- {
- value: "byok",
- label: "Paste a Vercel AI Gateway key",
- hint: "BYOK — unlimited on your own billing",
- },
- {
- value: "skip",
- label: "Skip",
- hint: "ship with sample content",
- },
- ],
- initialValue: "login",
+ if (isInteractive && source.kind !== "skip" && !authToken && !isByokMode()) {
+ const wantsLogin = await confirm({
+ message: "Log in to helpbase free? (500k tokens/day, no card — 30s browser flow)",
+ initialValue: true,
})
-
- if (isCancel(authChoice)) {
+ if (isCancel(wantsLogin)) {
cancel("Setup cancelled.")
process.exit(0)
}
-
- if (authChoice === "login") {
+ if (wantsLogin) {
const loginResult = await runHelpbaseLogin()
if (loginResult === "failed") {
note(
@@ -201,22 +180,9 @@ async function run(directory: string | undefined, opts: RunOptions) {
// Re-read the token file — login just wrote it.
authToken = readHelpbaseAuthToken()
}
- } else if (authChoice === "byok") {
- const keyResponse = await text({
- message: "Paste your Vercel AI Gateway key",
- placeholder: "vck_...",
- })
- if (isCancel(keyResponse)) {
- cancel("Setup cancelled.")
- process.exit(0)
- }
- const trimmed = (keyResponse as string | undefined)?.trim()
- if (trimmed && trimmed.length > 0 && trimmed !== "skip") {
- aiGatewayKey = trimmed
- }
}
- // authChoice === "skip" → fall through with no token, generation
- // will error with the MissingApiKey path and sample content stays.
+ // Declined → fall through with no token, generation will error with
+ // the MissingApiKey path and the scaffolded sample content stays.
}
// 4. Scaffold the project
@@ -229,13 +195,27 @@ async function run(directory: string | undefined, opts: RunOptions) {
internal: opts.internal,
})
- if (aiGatewayKey) {
- writeAiGatewayKey(projectDir, aiGatewayKey)
- }
-
s.stop("Project scaffolded!")
- // 5. AI content generation — branches by source kind.
+ // 5. Kick off `pnpm install` in the background so it runs while the LLM
+ // call is in flight. Install is network + disk I/O, LLM synthesis is
+ // network I/O — they don't compete. Cuts 30-60s off TTHW on the first
+ // real run (install used to be strictly serial, after generation).
+ // Install's stdout/stderr are captured (not piped to terminal) so they
+ // don't clobber the spinner that generation owns.
+ const pkgManager = detectPackageManager()
+ const installPromise: Promise<{ success: true } | { success: false; reason: string }> =
+ opts.install !== false
+ ? runInstallInBackground(projectDir, pkgManager)
+ : Promise.resolve({ success: true } as const)
+
+ if (opts.install !== false) {
+ console.log(
+ ` ${pc.dim("›")} Installing dependencies with ${pc.cyan(pkgManager)} in background...`,
+ )
+ }
+
+ // 6. AI content generation — branches by source kind.
//
// Invariant (Issue 1 fix from /plan-eng-review 2026-04-17): sample
// content stays on disk until LLM synthesis SUCCEEDS. The old flow
@@ -264,28 +244,26 @@ async function run(directory: string | undefined, opts: RunOptions) {
})
}
- // 6. Emit mcp.json at project root if generation produced docs.
+ // 7. Emit mcp.json at project root if generation produced docs.
// For `skip` source we keep the sample content + skip emit (sample
// content has no citations worth wiring into MCP for a stranger).
if (generationSucceeded) {
emitMcpJson(projectDir)
}
- // 7. Install dependencies
- const pkgManager = detectPackageManager()
+ // 8. Wait for install to finish. If the LLM path was slower, install is
+ // already done and this resolves instantly; if install was slower, the
+ // spinner tells the user we're still waiting on it.
if (opts.install !== false) {
- s.start(`Installing dependencies with ${pkgManager}... (this may take a minute)`)
- try {
- execSync(`${pkgManager} install`, {
- cwd: projectDir,
- stdio: ["pipe", "pipe", "pipe"],
- timeout: 120000, // 2 minute timeout
- })
+ s.start(`Finishing ${pkgManager} install...`)
+ const installResult = await installPromise
+ if (installResult.success) {
s.stop("Dependencies installed!")
- } catch {
+ } else {
s.stop(pc.yellow("Failed to install dependencies."))
note(
- `Run ${pc.cyan(`cd ${projectName as string} && ${pkgManager} install`)} manually.`,
+ `Run ${pc.cyan(`cd ${projectName as string} && ${pkgManager} install`)} manually.\n` +
+ ` Reason: ${installResult.reason}`,
"Manual install needed",
)
}
@@ -316,7 +294,7 @@ async function run(directory: string | undefined, opts: RunOptions) {
outro(
`${pc.green("Your help center is ready!")}\n` +
- ` Docs: ${pc.dim("https://helpbase.dev/docs")}`,
+ ` Docs: ${pc.dim("https://helpbase.dev/getting-started/introduction")}`,
)
// 9. Start dev server + auto-open browser on "Ready" signal.
@@ -619,6 +597,50 @@ function detectPackageManager(): string {
return "npm"
}
+/**
+ * Spawn ` install` as a background child process and resolve
+ * once it exits. Captures stdout + stderr into buffers (not piped to the
+ * terminal) so it doesn't interleave with the spinner owned by AI
+ * generation. On non-zero exit we keep the last 500 chars of stderr so
+ * the manual-retry note gives a real reason.
+ *
+ * 2-minute timeout matches the previous `execSync` behavior — slow CI
+ * networks occasionally hit it, but 3min+ is almost always a cold Docker
+ * image pulling the registry for the first time, not a normal user run.
+ */
+function runInstallInBackground(
+ projectDir: string,
+ pkgManager: string,
+): Promise<{ success: true } | { success: false; reason: string }> {
+ return new Promise((resolve) => {
+ let stderrTail = ""
+ const child = spawn(pkgManager, ["install"], {
+ cwd: projectDir,
+ stdio: ["ignore", "pipe", "pipe"],
+ timeout: 120000,
+ })
+ child.stdout?.on("data", () => {
+ // drain to keep the pipe flowing; output is intentionally dropped
+ })
+ child.stderr?.on("data", (chunk: Buffer) => {
+ // Retain only the tail — package managers can be very chatty, and
+ // we only surface the reason on failure.
+ stderrTail = (stderrTail + chunk.toString()).slice(-500)
+ })
+ child.once("error", (err) => {
+ resolve({ success: false, reason: err.message })
+ })
+ child.once("exit", (code) => {
+ if (code === 0) {
+ resolve({ success: true })
+ } else {
+ const reason = stderrTail.trim() || `${pkgManager} install exited ${code}`
+ resolve({ success: false, reason })
+ }
+ })
+ })
+}
+
/**
* Write generated articles into `/content//*.mdx` and
* scaffold the matching `_category.json` files. URL branch only — the repo
@@ -664,8 +686,8 @@ function printGenerationFallbackHint(err: unknown, url: string): void {
note(
`Run ${pc.cyan("helpbase login")} (free, no card) then:\n` +
` ${pc.cyan(`helpbase generate --url ${url}`)}\n\n` +
- `Or bring your own key: ${pc.cyan("export AI_GATEWAY_API_KEY=...")} ` +
- `(docs: ${pc.cyan("helpbase.dev/docs/byok")})`,
+ `Or bring your own key: ${pc.cyan("ANTHROPIC_API_KEY")}, ${pc.cyan("OPENAI_API_KEY")}, or ${pc.cyan("AI_GATEWAY_API_KEY")} ` +
+ `(docs: ${pc.cyan("helpbase.dev/guides/byok")})`,
"AI generation skipped",
)
return
@@ -689,8 +711,8 @@ function printRepoGenerationFallbackHint(err: unknown, repoPath: string): void {
note(
`Run ${pc.cyan("helpbase login")} (free, no card) then:\n` +
` ${pc.cyan(`helpbase context ${repoPath}`)}\n\n` +
- `Or bring your own key: ${pc.cyan("export AI_GATEWAY_API_KEY=...")} ` +
- `(docs: ${pc.cyan("helpbase.dev/docs/byok")})`,
+ `Or bring your own key: ${pc.cyan("ANTHROPIC_API_KEY")}, ${pc.cyan("OPENAI_API_KEY")}, or ${pc.cyan("AI_GATEWAY_API_KEY")} ` +
+ `(docs: ${pc.cyan("helpbase.dev/guides/byok")})`,
"AI generation skipped",
)
return
diff --git a/packages/create-helpbase/templates/HELPBASE.md b/packages/create-helpbase/templates/HELPBASE.md
index 97595c9..eb45f6c 100644
--- a/packages/create-helpbase/templates/HELPBASE.md
+++ b/packages/create-helpbase/templates/HELPBASE.md
@@ -74,4 +74,4 @@ and OS.
## Full reference
`helpbase --help` for any command. Full reference:
-.
+.
diff --git a/packages/create-helpbase/templates/content/guides/byok.mdx b/packages/create-helpbase/templates/content/guides/byok.mdx
index b09b1b3..810c7a0 100644
--- a/packages/create-helpbase/templates/content/guides/byok.mdx
+++ b/packages/create-helpbase/templates/content/guides/byok.mdx
@@ -1,40 +1,41 @@
---
schemaVersion: 1
-title: "Bring your own Gateway key (BYOK)"
-description: "When and how to bypass the helpbase hosted proxy with your own Vercel AI Gateway key. For CI, power users, and privacy-sensitive workflows."
+title: "Bring your own key (BYOK)"
+description: "Three ways to skip the helpbase hosted proxy and call your LLM provider directly. For CI, power users, and privacy-sensitive workflows."
tags: ["byok", "advanced", "ci"]
order: 99
featured: false
---
-helpbase is free to use with a one-command login — 500,000 tokens per day, no
-credit card. That covers most people.
+helpbase is free to use with a one-command login — 500,000 tokens per day,
+no credit card. That covers most people.
You might want your own key instead when:
-- **You're running in CI.** helpbase sessions are designed for interactive use;
- machines need a token.
-- **You're already paying for Vercel AI Gateway.** Route everything through
- the account you already meter and bill.
+- **You're running in CI.** helpbase sessions are designed for interactive
+ use; machines need a token they already have.
+- **You already have a provider key.** Most teams have an Anthropic or OpenAI
+ key lying around. Use it directly — no second provider to sign up for.
- **Free-tier limits are too low for your workload.** 500k/day is ~10 full
- `generate` runs or ~250 `context --ask` calls. If you run more, BYOK is
- unlimited (well — limited to your own Gateway spend cap).
-- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct
- to Vercel AI Gateway. helpbase never sees your prompts.
+ `generate` runs or ~250 `context --ask` calls. BYOK is unlimited (within
+ your provider's own spend cap).
+- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct to
+ your provider. helpbase never sees your prompts.
-## How it works
+## Three keys, any one works
-Set `AI_GATEWAY_API_KEY` in your environment. That's it. The CLI detects it
-and bypasses the helpbase proxy for every LLM call:
+Set whichever one you already have. First key found wins; precedence is
+`AI_GATEWAY_API_KEY` > `ANTHROPIC_API_KEY` > `OPENAI_API_KEY`.
-```bash
-export AI_GATEWAY_API_KEY=vck_live_...
-helpbase generate --url https://docs.example.com
-```
+| Env var | Routes to | Use when |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | `@ai-sdk/anthropic` direct | You already have an Anthropic key. Pair with `--model anthropic/`. |
+| `OPENAI_API_KEY` | `@ai-sdk/openai` direct | You already have an OpenAI key. Pair with `--model openai/`. |
+| `AI_GATEWAY_API_KEY` | [Vercel AI Gateway](https://vercel.com/ai-gateway) | You want one key to route any provider (Anthropic, OpenAI, Google, etc.) with one bill. |
```
┌──────────────────┐
-│ helpbase CLI │─────► Vercel AI SDK direct ─────► Vercel AI Gateway
+│ helpbase CLI │─────► Vercel AI SDK direct ─────► your provider
│ │ (your key, your bill)
└──────────────────┘
(no quota check, no usage log, no helpbase.dev round-trip)
@@ -43,7 +44,43 @@ helpbase generate --url https://docs.example.com
No changes to prompts, no different models — same output as the hosted
path, just routed direct.
-## Getting a key
+## Anthropic direct
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+helpbase generate --url https://docs.example.com \
+ --model anthropic/claude-3-5-sonnet-latest
+```
+
+The `--model` prefix must be `anthropic/` when only `ANTHROPIC_API_KEY` is
+set. Any other prefix will error with a clear message telling you the
+exact command to try instead.
+
+Get a key at [console.anthropic.com](https://console.anthropic.com).
+
+## OpenAI direct
+
+```bash
+export OPENAI_API_KEY=sk-...
+helpbase generate --url https://docs.example.com \
+ --model openai/gpt-4o-mini
+```
+
+Same rule: the `--model` prefix must be `openai/` when only `OPENAI_API_KEY`
+is set.
+
+Get a key at [platform.openai.com](https://platform.openai.com).
+
+## Vercel AI Gateway (multi-provider)
+
+```bash
+export AI_GATEWAY_API_KEY=vck_live_...
+helpbase generate --url https://docs.example.com
+# Any --model works:
+helpbase generate --url https://docs.example.com --model anthropic/claude-sonnet-4.6
+helpbase generate --url https://docs.example.com --model google/gemini-3.1-flash-lite-preview
+helpbase generate --url https://docs.example.com --model openai/gpt-4o-mini
+```
1. Sign in at [vercel.com/ai-gateway](https://vercel.com/ai-gateway).
2. Create an API key.
@@ -52,25 +89,24 @@ path, just routed direct.
## CI usage
-In GitHub Actions and other CI, set `AI_GATEWAY_API_KEY` as a repo secret
-and pass it through:
+In GitHub Actions and other CI, set whichever key you use as a repo secret:
```yaml
- run: helpbase generate --url https://docs.example.com
env:
- AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```
CI users don't need `helpbase login`. If you still want to run `helpbase
deploy` from CI (which requires a helpbase account), set `HELPBASE_TOKEN`
-as well — that's the helpbase session, separate from the Gateway key.
+as well — that's the helpbase session, separate from the provider key.
## Switching back to hosted
-Unset the env var:
+Unset whichever key is active:
```bash
-unset AI_GATEWAY_API_KEY
+unset ANTHROPIC_API_KEY # or OPENAI_API_KEY, or AI_GATEWAY_API_KEY
```
The next CLI command will use the helpbase hosted proxy again. No state to
@@ -82,32 +118,35 @@ clear, no account to delete.
helpbase whoami
```
-If `AI_GATEWAY_API_KEY` is set, `whoami` will show "BYOK mode active — calls
-bypass helpbase (no quota applied)". Otherwise it shows your usage against
-the free-tier cap.
+`whoami` names the active key if BYOK is on: "BYOK mode: `ANTHROPIC_API_KEY`
+is set — calls bypass helpbase (no quota applied)". Otherwise it shows your
+usage against the free-tier cap.
## Costs
-BYOK costs are whatever Gateway charges for the model you pick. As of this
-writing the default and `--test` are both `google/gemini-3.1-flash-lite-preview`
-(cheap + fast, ~1M context). Rough costs for a 9-article `helpbase generate`
-run (~50,000 tokens):
+BYOK costs are whatever your provider charges for the model you pick.
+Rough costs for a 9-article `helpbase generate` run (~50,000 tokens):
-- Gemini 3.1 Flash Lite (default / `--test`): ~$0.004 per run.
+- Gemini 3.1 Flash Lite (Gateway default, `--test`): ~$0.004 per run.
- Claude Sonnet 4.6 (`--model anthropic/claude-sonnet-4.6`): ~$0.20–0.40.
- GPT-4o-mini (`--model openai/gpt-4o-mini`): ~$0.01–0.03.
## Troubleshooting
-**"AI_GATEWAY_API_KEY is not set" but I just exported it.** New terminal sessions
-don't see variables from old sessions. Re-export in the current shell, or
-persist in `.env.local`.
+**"ANTHROPIC_API_KEY is set but the model is '...'"** Direct-key mode
+requires the `--model` prefix to match your key. Either pass
+`--model anthropic/`, or set `AI_GATEWAY_API_KEY` instead to route any
+provider through Gateway.
+
+**"`ANTHROPIC_API_KEY` is not set" but I just exported it.** New terminal
+sessions don't see variables from old sessions. Re-export in the current
+shell, or persist in `.env.local`.
-**"BYOK mode active" but I want to use hosted.** Run `unset
-AI_GATEWAY_API_KEY`. You can also delete the line from `.env.local`.
+**"BYOK mode active" but I want to use hosted.** Run `unset `
+using whichever key `helpbase whoami` names. You can also delete the line
+from `.env.local`.
**CI passes the env var but still shows "not signed in".** `helpbase login`
-and `AI_GATEWAY_API_KEY` serve different purposes. Login is for hosted
-quota + deploy authorization. BYOK bypasses quota only. For deploy in CI,
-you also need `HELPBASE_TOKEN` (a helpbase session token) alongside the
-Gateway key.
+and BYOK serve different purposes. Login is for hosted quota + deploy
+authorization. BYOK bypasses quota only. For deploy in CI, you also need
+`HELPBASE_TOKEN` (a helpbase session token) alongside your provider key.
diff --git a/packages/create-helpbase/templates/content/guides/sync-in-5-minutes.mdx b/packages/create-helpbase/templates/content/guides/sync-in-5-minutes.mdx
index 0353613..ad6c75f 100644
--- a/packages/create-helpbase/templates/content/guides/sync-in-5-minutes.mdx
+++ b/packages/create-helpbase/templates/content/guides/sync-in-5-minutes.mdx
@@ -47,9 +47,10 @@ Magic-link flow. Free tier is 500,000 tokens per day — enough for roughly 10
full generates or 250 `context --ask` calls.
-Prefer your own key? Set `AI_GATEWAY_API_KEY` and helpbase will route through
-your Vercel AI Gateway account instead. See
-[helpbase.dev/docs/byok](https://helpbase.dev/docs/byok).
+Prefer your own key? Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or
+`AI_GATEWAY_API_KEY` — helpbase routes direct to whichever provider you set
+(first found wins). See
+[helpbase.dev/guides/byok](https://helpbase.dev/guides/byok).
## Step 3 — Make a code change worth documenting
diff --git a/packages/create-helpbase/test/env-local.unit.test.ts b/packages/create-helpbase/test/env-local.unit.test.ts
deleted file mode 100644
index 1f7084a..0000000
--- a/packages/create-helpbase/test/env-local.unit.test.ts
+++ /dev/null
@@ -1,51 +0,0 @@
-import { describe, it, expect, afterEach } from "vitest"
-import fs from "node:fs"
-import os from "node:os"
-import path from "node:path"
-import { writeAiGatewayKey } from "../src/env-local.js"
-
-const tempDirs: string[] = []
-
-function mkTempDir(): string {
- const dir = fs.mkdtempSync(path.join(os.tmpdir(), "create-helpbase-env-"))
- tempDirs.push(dir)
- return dir
-}
-
-afterEach(() => {
- for (const dir of tempDirs.splice(0)) {
- if (fs.existsSync(dir)) fs.rmSync(dir, { recursive: true, force: true })
- }
-})
-
-describe("writeAiGatewayKey", () => {
- it("creates .env.local with the key when the file doesn't exist", () => {
- const dir = mkTempDir()
- writeAiGatewayKey(dir, "sk-test-123")
- const contents = fs.readFileSync(path.join(dir, ".env.local"), "utf-8")
- expect(contents).toBe("AI_GATEWAY_API_KEY=sk-test-123\n")
- })
-
- it("appends the key when .env.local exists without it", () => {
- const dir = mkTempDir()
- fs.writeFileSync(path.join(dir, ".env.local"), "FOO=bar\n")
- writeAiGatewayKey(dir, "sk-xyz")
- const contents = fs.readFileSync(path.join(dir, ".env.local"), "utf-8")
- expect(contents).toContain("FOO=bar")
- expect(contents).toContain("AI_GATEWAY_API_KEY=sk-xyz")
- })
-
- it("replaces the existing AI_GATEWAY_API_KEY line", () => {
- const dir = mkTempDir()
- fs.writeFileSync(
- path.join(dir, ".env.local"),
- "FOO=bar\nAI_GATEWAY_API_KEY=old\nBAZ=qux\n",
- )
- writeAiGatewayKey(dir, "new-key")
- const contents = fs.readFileSync(path.join(dir, ".env.local"), "utf-8")
- expect(contents).toContain("AI_GATEWAY_API_KEY=new-key")
- expect(contents).not.toContain("old")
- expect(contents).toContain("FOO=bar")
- expect(contents).toContain("BAZ=qux")
- })
-})
diff --git a/packages/shared/src/__tests__/llm-errors.test.ts b/packages/shared/src/__tests__/llm-errors.test.ts
index 08ecac2..6a1499f 100644
--- a/packages/shared/src/__tests__/llm-errors.test.ts
+++ b/packages/shared/src/__tests__/llm-errors.test.ts
@@ -80,7 +80,7 @@ describe("Error classes carry code + shape", () => {
dailyLimit: 500_000,
resetAt: "2026-04-18T00:00:00Z",
upgradeUrl: "https://helpbase.dev/waitlist",
- byokDocsUrl: "https://helpbase.dev/docs/byok",
+ byokDocsUrl: "https://helpbase.dev/guides/byok",
})
expect(e.code).toBe("quota_exceeded")
expect(e.usedToday).toBe(500_000)
@@ -89,7 +89,7 @@ describe("Error classes carry code + shape", () => {
it("GlobalCapError", () => {
const e = new GlobalCapError({
resetAt: "2026-04-18T00:00:00Z",
- byokDocsUrl: "https://helpbase.dev/docs/byok",
+ byokDocsUrl: "https://helpbase.dev/guides/byok",
})
expect(e.code).toBe("global_cap_hit")
})
diff --git a/packages/shared/src/__tests__/llm.test.ts b/packages/shared/src/__tests__/llm.test.ts
index 8e93998..100cde7 100644
--- a/packages/shared/src/__tests__/llm.test.ts
+++ b/packages/shared/src/__tests__/llm.test.ts
@@ -255,7 +255,7 @@ describe("callLlmObject hosted path — error mapping", () => {
dailyLimit: 500_000,
resetAt: "2026-04-18T00:00:00Z",
upgradeUrl: "https://helpbase.dev/waitlist",
- byokDocsUrl: "https://helpbase.dev/docs/byok",
+ byokDocsUrl: "https://helpbase.dev/guides/byok",
})
try {
await callLlmObject({ model: "x/y", prompt: "p", schema, authToken: "ok" })
@@ -274,7 +274,7 @@ describe("callLlmObject hosted path — error mapping", () => {
error: "global_cap_hit",
message: "global",
resetAt: "2026-04-18T00:00:00Z",
- byokDocsUrl: "https://helpbase.dev/docs/byok",
+ byokDocsUrl: "https://helpbase.dev/guides/byok",
})
await expect(
callLlmObject({ model: "x/y", prompt: "p", schema, authToken: "ok" }),
diff --git a/packages/shared/src/llm-wire.ts b/packages/shared/src/llm-wire.ts
index fa71cdc..4366357 100644
--- a/packages/shared/src/llm-wire.ts
+++ b/packages/shared/src/llm-wire.ts
@@ -144,4 +144,4 @@ export type WireErrorCode =
export const UPGRADE_URL = "https://helpbase.dev/waitlist" as const
/** URL that BYOK hints in errors point at. */
-export const BYOK_DOCS_URL = "https://helpbase.dev/docs/byok" as const
+export const BYOK_DOCS_URL = "https://helpbase.dev/guides/byok" as const
diff --git a/packages/shared/src/llm.ts b/packages/shared/src/llm.ts
index ee37a51..8a3078f 100644
--- a/packages/shared/src/llm.ts
+++ b/packages/shared/src/llm.ts
@@ -407,13 +407,13 @@ async function throwOnWireError(res: Response): Promise {
dailyLimit: body.dailyLimit ?? 0,
resetAt: body.resetAt ?? new Date().toISOString(),
upgradeUrl: body.upgradeUrl ?? "https://helpbase.dev/waitlist",
- byokDocsUrl: body.byokDocsUrl ?? "https://helpbase.dev/docs/byok",
+ byokDocsUrl: body.byokDocsUrl ?? "https://helpbase.dev/guides/byok",
message: body.message,
})
case "global_cap_hit":
throw new GlobalCapError({
resetAt: body.resetAt ?? new Date().toISOString(),
- byokDocsUrl: body.byokDocsUrl ?? "https://helpbase.dev/docs/byok",
+ byokDocsUrl: body.byokDocsUrl ?? "https://helpbase.dev/guides/byok",
message: body.message,
})
case "gateway_error":
diff --git a/registry/helpbase-workflow/README.md b/registry/helpbase-workflow/README.md
index 3b53716..c4dbd68 100644
--- a/registry/helpbase-workflow/README.md
+++ b/registry/helpbase-workflow/README.md
@@ -25,10 +25,11 @@ That drops a single file into your repo:
Add one secret to your GitHub repo (**Settings → Secrets and variables →
Actions → New repository secret**). You have two options:
-- **`AI_GATEWAY_API_KEY`** (recommended for CI) — your key from
- [vercel.com/ai-gateway](https://vercel.com/ai-gateway). Bypasses helpbase's
- hosted proxy entirely. Your Gateway account, your bill, no daily quota
- limit. See [helpbase.dev/docs/byok](https://helpbase.dev/docs/byok).
+- **Any BYOK key** (recommended for CI) — `ANTHROPIC_API_KEY`,
+ `OPENAI_API_KEY`, or `AI_GATEWAY_API_KEY`. Bypasses helpbase's hosted
+ proxy entirely. Your provider account, your bill, no daily quota
+ limit. First key found wins. See
+ [helpbase.dev/guides/byok](https://helpbase.dev/guides/byok).
- **`HELPBASE_TOKEN`** — a helpbase session access token. After running
`helpbase login` locally, pull the value from `~/.helpbase/auth.json`:
`jq -r .access_token ~/.helpbase/auth.json`. Uses helpbase's hosted proxy
diff --git a/registry/helpbase/content/guides/byok.mdx b/registry/helpbase/content/guides/byok.mdx
index b09b1b3..810c7a0 100644
--- a/registry/helpbase/content/guides/byok.mdx
+++ b/registry/helpbase/content/guides/byok.mdx
@@ -1,40 +1,41 @@
---
schemaVersion: 1
-title: "Bring your own Gateway key (BYOK)"
-description: "When and how to bypass the helpbase hosted proxy with your own Vercel AI Gateway key. For CI, power users, and privacy-sensitive workflows."
+title: "Bring your own key (BYOK)"
+description: "Three ways to skip the helpbase hosted proxy and call your LLM provider directly. For CI, power users, and privacy-sensitive workflows."
tags: ["byok", "advanced", "ci"]
order: 99
featured: false
---
-helpbase is free to use with a one-command login — 500,000 tokens per day, no
-credit card. That covers most people.
+helpbase is free to use with a one-command login — 500,000 tokens per day,
+no credit card. That covers most people.
You might want your own key instead when:
-- **You're running in CI.** helpbase sessions are designed for interactive use;
- machines need a token.
-- **You're already paying for Vercel AI Gateway.** Route everything through
- the account you already meter and bill.
+- **You're running in CI.** helpbase sessions are designed for interactive
+ use; machines need a token they already have.
+- **You already have a provider key.** Most teams have an Anthropic or OpenAI
+ key lying around. Use it directly — no second provider to sign up for.
- **Free-tier limits are too low for your workload.** 500k/day is ~10 full
- `generate` runs or ~250 `context --ask` calls. If you run more, BYOK is
- unlimited (well — limited to your own Gateway spend cap).
-- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct
- to Vercel AI Gateway. helpbase never sees your prompts.
+ `generate` runs or ~250 `context --ask` calls. BYOK is unlimited (within
+ your provider's own spend cap).
+- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct to
+ your provider. helpbase never sees your prompts.
-## How it works
+## Three keys, any one works
-Set `AI_GATEWAY_API_KEY` in your environment. That's it. The CLI detects it
-and bypasses the helpbase proxy for every LLM call:
+Set whichever one you already have. First key found wins; precedence is
+`AI_GATEWAY_API_KEY` > `ANTHROPIC_API_KEY` > `OPENAI_API_KEY`.
-```bash
-export AI_GATEWAY_API_KEY=vck_live_...
-helpbase generate --url https://docs.example.com
-```
+| Env var | Routes to | Use when |
+|---|---|---|
+| `ANTHROPIC_API_KEY` | `@ai-sdk/anthropic` direct | You already have an Anthropic key. Pair with `--model anthropic/`. |
+| `OPENAI_API_KEY` | `@ai-sdk/openai` direct | You already have an OpenAI key. Pair with `--model openai/`. |
+| `AI_GATEWAY_API_KEY` | [Vercel AI Gateway](https://vercel.com/ai-gateway) | You want one key to route any provider (Anthropic, OpenAI, Google, etc.) with one bill. |
```
┌──────────────────┐
-│ helpbase CLI │─────► Vercel AI SDK direct ─────► Vercel AI Gateway
+│ helpbase CLI │─────► Vercel AI SDK direct ─────► your provider
│ │ (your key, your bill)
└──────────────────┘
(no quota check, no usage log, no helpbase.dev round-trip)
@@ -43,7 +44,43 @@ helpbase generate --url https://docs.example.com
No changes to prompts, no different models — same output as the hosted
path, just routed direct.
-## Getting a key
+## Anthropic direct
+
+```bash
+export ANTHROPIC_API_KEY=sk-ant-...
+helpbase generate --url https://docs.example.com \
+ --model anthropic/claude-3-5-sonnet-latest
+```
+
+The `--model` prefix must be `anthropic/` when only `ANTHROPIC_API_KEY` is
+set. Any other prefix will error with a clear message telling you the
+exact command to try instead.
+
+Get a key at [console.anthropic.com](https://console.anthropic.com).
+
+## OpenAI direct
+
+```bash
+export OPENAI_API_KEY=sk-...
+helpbase generate --url https://docs.example.com \
+ --model openai/gpt-4o-mini
+```
+
+Same rule: the `--model` prefix must be `openai/` when only `OPENAI_API_KEY`
+is set.
+
+Get a key at [platform.openai.com](https://platform.openai.com).
+
+## Vercel AI Gateway (multi-provider)
+
+```bash
+export AI_GATEWAY_API_KEY=vck_live_...
+helpbase generate --url https://docs.example.com
+# Any --model works:
+helpbase generate --url https://docs.example.com --model anthropic/claude-sonnet-4.6
+helpbase generate --url https://docs.example.com --model google/gemini-3.1-flash-lite-preview
+helpbase generate --url https://docs.example.com --model openai/gpt-4o-mini
+```
1. Sign in at [vercel.com/ai-gateway](https://vercel.com/ai-gateway).
2. Create an API key.
@@ -52,25 +89,24 @@ path, just routed direct.
## CI usage
-In GitHub Actions and other CI, set `AI_GATEWAY_API_KEY` as a repo secret
-and pass it through:
+In GitHub Actions and other CI, set whichever key you use as a repo secret:
```yaml
- run: helpbase generate --url https://docs.example.com
env:
- AI_GATEWAY_API_KEY: ${{ secrets.AI_GATEWAY_API_KEY }}
+ ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```
CI users don't need `helpbase login`. If you still want to run `helpbase
deploy` from CI (which requires a helpbase account), set `HELPBASE_TOKEN`
-as well — that's the helpbase session, separate from the Gateway key.
+as well — that's the helpbase session, separate from the provider key.
## Switching back to hosted
-Unset the env var:
+Unset whichever key is active:
```bash
-unset AI_GATEWAY_API_KEY
+unset ANTHROPIC_API_KEY # or OPENAI_API_KEY, or AI_GATEWAY_API_KEY
```
The next CLI command will use the helpbase hosted proxy again. No state to
@@ -82,32 +118,35 @@ clear, no account to delete.
helpbase whoami
```
-If `AI_GATEWAY_API_KEY` is set, `whoami` will show "BYOK mode active — calls
-bypass helpbase (no quota applied)". Otherwise it shows your usage against
-the free-tier cap.
+`whoami` names the active key if BYOK is on: "BYOK mode: `ANTHROPIC_API_KEY`
+is set — calls bypass helpbase (no quota applied)". Otherwise it shows your
+usage against the free-tier cap.
## Costs
-BYOK costs are whatever Gateway charges for the model you pick. As of this
-writing the default and `--test` are both `google/gemini-3.1-flash-lite-preview`
-(cheap + fast, ~1M context). Rough costs for a 9-article `helpbase generate`
-run (~50,000 tokens):
+BYOK costs are whatever your provider charges for the model you pick.
+Rough costs for a 9-article `helpbase generate` run (~50,000 tokens):
-- Gemini 3.1 Flash Lite (default / `--test`): ~$0.004 per run.
+- Gemini 3.1 Flash Lite (Gateway default, `--test`): ~$0.004 per run.
- Claude Sonnet 4.6 (`--model anthropic/claude-sonnet-4.6`): ~$0.20–0.40.
- GPT-4o-mini (`--model openai/gpt-4o-mini`): ~$0.01–0.03.
## Troubleshooting
-**"AI_GATEWAY_API_KEY is not set" but I just exported it.** New terminal sessions
-don't see variables from old sessions. Re-export in the current shell, or
-persist in `.env.local`.
+**"ANTHROPIC_API_KEY is set but the model is '...'"** Direct-key mode
+requires the `--model` prefix to match your key. Either pass
+`--model anthropic/`, or set `AI_GATEWAY_API_KEY` instead to route any
+provider through Gateway.
+
+**"`ANTHROPIC_API_KEY` is not set" but I just exported it.** New terminal
+sessions don't see variables from old sessions. Re-export in the current
+shell, or persist in `.env.local`.
-**"BYOK mode active" but I want to use hosted.** Run `unset
-AI_GATEWAY_API_KEY`. You can also delete the line from `.env.local`.
+**"BYOK mode active" but I want to use hosted.** Run `unset `
+using whichever key `helpbase whoami` names. You can also delete the line
+from `.env.local`.
**CI passes the env var but still shows "not signed in".** `helpbase login`
-and `AI_GATEWAY_API_KEY` serve different purposes. Login is for hosted
-quota + deploy authorization. BYOK bypasses quota only. For deploy in CI,
-you also need `HELPBASE_TOKEN` (a helpbase session token) alongside the
-Gateway key.
+and BYOK serve different purposes. Login is for hosted quota + deploy
+authorization. BYOK bypasses quota only. For deploy in CI, you also need
+`HELPBASE_TOKEN` (a helpbase session token) alongside your provider key.
diff --git a/registry/helpbase/content/guides/sync-in-5-minutes.mdx b/registry/helpbase/content/guides/sync-in-5-minutes.mdx
index 0353613..ad6c75f 100644
--- a/registry/helpbase/content/guides/sync-in-5-minutes.mdx
+++ b/registry/helpbase/content/guides/sync-in-5-minutes.mdx
@@ -47,9 +47,10 @@ Magic-link flow. Free tier is 500,000 tokens per day — enough for roughly 10
full generates or 250 `context --ask` calls.
-Prefer your own key? Set `AI_GATEWAY_API_KEY` and helpbase will route through
-your Vercel AI Gateway account instead. See
-[helpbase.dev/docs/byok](https://helpbase.dev/docs/byok).
+Prefer your own key? Set `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or
+`AI_GATEWAY_API_KEY` — helpbase routes direct to whichever provider you set
+(first found wins). See
+[helpbase.dev/guides/byok](https://helpbase.dev/guides/byok).
## Step 3 — Make a code change worth documenting
diff --git a/scripts/check-links.sh b/scripts/check-links.sh
new file mode 100755
index 0000000..818b654
--- /dev/null
+++ b/scripts/check-links.sh
@@ -0,0 +1,154 @@
+#!/usr/bin/env bash
+#
+# scripts/check-links.sh — Verify every `helpbase.dev/` URL in the
+# repo actually resolves. Catches the bug class that shipped on
+# 2026-04-17 (nine `helpbase.dev/docs/byok` references, all 404 because
+# the real URL is `/guides/byok`).
+#
+# What this checks: any URL matching `helpbase.dev/` in source
+# files (md, mdx, ts, tsx, json, yml, yaml). Bare `helpbase.dev` without
+# a path is skipped (brand mention, not a link).
+#
+# What this skips: CHANGELOG.md (historical), pnpm-lock.yaml (no
+# helpbase.dev links should live there anyway), node_modules, dist, .next.
+#
+# Exit codes:
+# 0 — every URL returned 2xx or 3xx
+# 1 — at least one URL returned 4xx / 5xx
+# Timeouts and DNS failures print a warning but do NOT fail — transient
+# network blips shouldn't block a local run.
+#
+# Usage:
+# pnpm check:links # check against production
+# LINK_CHECK_BASE=https://staging.helpbase.dev pnpm check:links
+# LINK_CHECK_TIMEOUT=20 pnpm check:links # override 10s default
+
+set -uo pipefail
+
+BASE="${LINK_CHECK_BASE:-https://helpbase.dev}"
+TIMEOUT="${LINK_CHECK_TIMEOUT:-10}"
+
+REPO_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+cd "$REPO_ROOT"
+
+# Colors (respect NO_COLOR / non-TTY)
+if [ -t 1 ] && [ -z "${NO_COLOR:-}" ]; then
+ R=$'\033[31m'; G=$'\033[32m'; Y=$'\033[33m'; D=$'\033[2m'; B=$'\033[1m'; N=$'\033[0m'
+else
+ R=""; G=""; Y=""; D=""; B=""; N=""
+fi
+
+echo "${B}Checking helpbase.dev links${N} against ${D}${BASE}${N}"
+echo
+
+# Extract every `https://helpbase.dev/` URL from source files.
+# - Scheme-ful match only — bare `helpbase.dev` in comments + display text
+# isn't a clickable link, so skipping it cuts false positives cleanly.
+# - Strip trailing punctuation (period, comma, paren, bracket, quote).
+# - Dedupe + sort.
+# - Exclude test files (negative-test fixtures point at fake URLs) and
+# planning docs (drafts at repo root that may reference TBD pages).
+# (Using `while read` instead of `mapfile` so this works on macOS bash 3.2.)
+URLS=()
+while IFS= read -r line; do
+ [ -n "$line" ] && URLS+=("$line")
+done < <(
+ grep -rohE 'https://helpbase\.dev/[A-Za-z0-9/_.?=%~-]+' \
+ --include='*.md' --include='*.mdx' \
+ --include='*.ts' --include='*.tsx' \
+ --include='*.js' --include='*.mjs' --include='*.cjs' \
+ --include='*.json' --include='*.yml' --include='*.yaml' \
+ --exclude-dir=node_modules --exclude-dir=dist --exclude-dir=.next \
+ --exclude-dir=.turbo --exclude-dir=.vercel --exclude-dir=.git \
+ --exclude-dir=test --exclude-dir=tests --exclude-dir=__tests__ \
+ --exclude='*.test.*' --exclude='*.spec.*' \
+ --exclude='CHANGELOG.md' --exclude='pnpm-lock.yaml' --exclude='package-lock.json' \
+ --exclude='*_PLAN.md' --exclude='*_PROMPT.md' --exclude='NEXT_SESSION_*.md' \
+ . 2>/dev/null \
+ | sed -E 's|[\.\,\;\:\)\]\}\"]+$||' \
+ | grep -vE '/$' \
+ | sort -u
+)
+
+# Apply .linkcheckignore (one URL per line, exact match, # for comments).
+# Lets us allow-list known template bases like ERROR_DOC_BASE const, which
+# reads as a bare URL in source but only ever renders as ${base}/${code}.
+#
+# Uses `grep -F -x -v -f` (fixed strings, exact line, invert match, file-driven)
+# so URLs with regex metacharacters like `?` or `=` match literally — building
+# a regex union on the fly was broken for query-string URLs.
+if [ -f .linkcheckignore ]; then
+ # Strip comments + blank lines into a temp file grep can consume.
+ IGNORE_TMP=$(mktemp)
+ grep -vE '^\s*(#|$)' .linkcheckignore > "$IGNORE_TMP" || true
+ if [ -s "$IGNORE_TMP" ]; then
+ FILTERED=()
+ while IFS= read -r line; do
+ [ -n "$line" ] && FILTERED+=("$line")
+ done < <(printf '%s\n' "${URLS[@]}" | grep -F -x -v -f "$IGNORE_TMP" || true)
+ URLS=("${FILTERED[@]}")
+ fi
+ rm -f "$IGNORE_TMP"
+fi
+
+TOTAL=${#URLS[@]}
+if [ "$TOTAL" -eq 0 ]; then
+ echo "${Y}No helpbase.dev links found in source files.${N} Nothing to check."
+ exit 0
+fi
+
+FAIL=0
+WARN=0
+PASS=0
+
+for url in "${URLS[@]}"; do
+ # Rewrite the host if LINK_CHECK_BASE overrides the default.
+ probe="${url/https:\/\/helpbase.dev/$BASE}"
+
+ # HEAD first. If the server doesn't allow HEAD (some static hosts), retry GET.
+ status=$(curl -sIo /dev/null -w '%{http_code}' \
+ --max-time "$TIMEOUT" -L \
+ -A 'helpbase-link-check/1.0' \
+ "$probe" 2>/dev/null || echo "000")
+
+ if [ "$status" = "405" ] || [ "$status" = "000" ]; then
+ # HEAD not allowed or network blip — try GET (discard body).
+ status=$(curl -so /dev/null -w '%{http_code}' \
+ --max-time "$TIMEOUT" -L \
+ -A 'helpbase-link-check/1.0' \
+ "$probe" 2>/dev/null || echo "000")
+ fi
+
+ case "$status" in
+ 2*|3*)
+ printf ' %s✓%s %s %s(%s)%s\n' "$G" "$N" "$url" "$D" "$status" "$N"
+ PASS=$((PASS + 1))
+ ;;
+ 401|403|405|429)
+ # URL exists but is auth-gated, rejects HEAD, or is rate-limited —
+ # not a broken link.
+ printf ' %s✓%s %s %s(%s, exists)%s\n' "$G" "$N" "$url" "$D" "$status" "$N"
+ PASS=$((PASS + 1))
+ ;;
+ 000|5*)
+ printf ' %s?%s %s %s(%s, transient?)%s\n' "$Y" "$N" "$url" "$D" "$status" "$N"
+ WARN=$((WARN + 1))
+ ;;
+ *)
+ printf ' %s✗%s %s %s(%s)%s\n' "$R" "$N" "$url" "$D" "$status" "$N"
+ FAIL=$((FAIL + 1))
+ ;;
+ esac
+done
+
+echo
+echo "${B}${TOTAL}${N} checked ${G}${PASS} ok${N} ${R}${FAIL} broken${N} ${Y}${WARN} timeouts${N}"
+
+if [ "$FAIL" -gt 0 ]; then
+ echo
+ echo "${R}FAIL${N}: at least one helpbase.dev link returned 4xx/5xx."
+ echo " Fix the source files that reference these URLs, or update the target page."
+ exit 1
+fi
+
+exit 0
diff --git a/scripts/sync-templates.mjs b/scripts/sync-templates.mjs
index 7dafa4b..0261db5 100644
--- a/scripts/sync-templates.mjs
+++ b/scripts/sync-templates.mjs
@@ -432,7 +432,7 @@ function writeTemplatesHelpbaseMd() {
const DEFAULT_HELPBASE_MD = `# helpbase
-This is your help center. See https://helpbase.dev/docs for the full guide.
+This is your help center. See https://helpbase.dev/getting-started/introduction for the full guide.
`
function generateTemplatesGitignore() {