Repository navigation
TTHW squeeze: parallel install, 3-key BYOK truth, README Quick Start inversion - #8
Conversation
Squeezes ~30-60s off first-run TTHW by running `<pkgManager> install` in
the background alongside the LLM generation call instead of serially
after it. Install captures stdout/stderr into buffers so it doesn't
clobber the spinner that the generation phase owns.
Collapses the 3-way auth prompt (Log in / BYOK paste / Skip) to a single
confirm("Log in to helpbase free?"). The no-key founder persona always
picked Log in; the BYOK paste option was cognitive noise. BYOK users
still route via env var — the scaffolder now detects any of
AI_GATEWAY_API_KEY / ANTHROPIC_API_KEY / OPENAI_API_KEY via isByokMode()
and skips the prompt entirely in that case (not just Gateway).
Drops the now-unused writeAiGatewayKey helper + its test.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
inline-auth.ts only checked AI_GATEWAY_API_KEY when deciding to skip the hosted-login prompt. Users with only ANTHROPIC_API_KEY or OPENAI_API_KEY set would see a pointless "sign in?" prompt even though the downstream callLlm* path already bypasses the proxy via isByokMode(). Source of truth is now isByokMode() from @workspace/shared/llm, so the prompt and the actual LLM routing agree. auth-device.ts default polling interval drops from 2s to 1s. RFC 8628 says `interval` is the minimum between polls, not a target, so 1s is spec-compliant and cuts ~1s of perceived wait after the user clicks Authorize in the browser. Server-supplied interval still wins. The "slow_down" RFC branch still adds +5s per the spec. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ntext The BYOK feature expanded from AI_GATEWAY_API_KEY only to three keys (ANTHROPIC_API_KEY, OPENAI_API_KEY, AI_GATEWAY_API_KEY) but the prose surfaces kept saying "use your own Vercel AI Gateway key." Trust signal off — the docs lied about what the tool does. Rewrites apps/web/content/guides/byok.mdx into a "three ways to skip the hosted proxy" reference with per-provider examples (Anthropic direct, OpenAI direct, Gateway for multi-provider). Syncs to the registry + scaffolder-template copies. Pulls one source-of-truth byokHint() helper in llm-errors-cli.ts so the three LLM-failure paths (quota, global cap, network) name all three keys in lockstep. Touches the matching stale hints in generate.ts, context.ts, and sync.ts — the --help text and the MissingApiKey fallback now reference login AND all three BYOK keys, not just Gateway. README Quick Start inversion: the <90s path (`helpbase login` + `helpbase context .`) is now the primary entry point. The scaffolder moves to a secondary "Scaffold a full Next.js help-center site" heading for users who want a deployable site, not just `.helpbase/` MDX in an existing repo. The scaffolder note now mentions all three BYOK keys too. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Warning Rate limit exceeded
Your organization is not enrolled in usage-based pricing. Contact your admin to enable usage-based pricing to continue reviews beyond the rate limit, or try again in 24 minutes and 50 seconds. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (21)
📝 WalkthroughWalkthroughThis PR expands BYOK (Bring Your Own Key) authentication to support three provider environment variables— Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 2 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (2 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (3)
packages/cli/src/commands/sync.ts (1)
66-67:⚠️ Potential issue | 🟡 MinorStale
addHelpTextcontradicts the PR's three-key BYOK message.
helpbase sync --helpstill reads "SetAI_GATEWAY_API_KEYfirst — https://vercel.com/ai-gateway", while the error copy (lines 163-167) and demo-mode next-step (line 376) were correctly updated to the three-key +helpbase loginframing. Users hitting--helpwill see the old guidance.🛠️ Suggested fix — align with
context.ts/generate.ts-Set AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway +Auth: run ${pc.cyan("helpbase login")} (free, 500k tokens/day) + 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)🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/src/commands/sync.ts` around lines 66 - 67, Update the stale help text added by addHelpText in the sync command so it matches the PR's three-key BYOK + login guidance used elsewhere (e.g. context.ts/generate.ts); locate the addHelpText call in packages/cli/src/commands/sync.ts and replace the single-line "Set AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway" message with the same three-key + `helpbase login` phrasing used in the error copy and demo-mode next-step so --help shows the current guidance.packages/cli/src/commands/context.ts (1)
117-128:⚠️ Potential issue | 🟡 MinorStale single-key hint in
GatewayErrorfix copy.This fallback still tells users to "Check your
AI_GATEWAY_API_KEYis valid", which contradicts the PR-wide three-key BYOK framing and will mislead users who are on BYOK viaANTHROPIC_API_KEY/OPENAI_API_KEY. Note thattoCliLlmErroron line 100 already handlesGatewayErrorvia the sharedgatewayError()helper inllm-errors-cli.ts(which is BYOK-agnostic), so this second branch is also dead code when the error is aGatewayError(it's caught and rethrown asHelpbaseErrorabove on line 103).🛠️ Suggested fix
Since
toCliLlmErroralready translatesGatewayError, consider removing this branch entirely:- if (err instanceof GatewayError) { - throw new HelpbaseError({ - code: "E_NETWORK", - problem: "The LLM gateway call failed.", - cause: err.message, - fix: [ - "Retry in a moment — transient gateway errors are common.", - "Check your AI_GATEWAY_API_KEY is valid.", - "Try --model anthropic/claude-sonnet-4.6 to switch providers.", - ], - }) - }🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/cli/src/commands/context.ts` around lines 117 - 128, The GatewayError handling branch that throws a HelpbaseError in context.ts is stale and duplicates/contradicts the BYOK-agnostic translation already performed by toCliLlmError (which uses gatewayError in llm-errors-cli.ts); remove the entire if (err instanceof GatewayError) { ... } branch (the throw of HelpbaseError) so GatewayError is only handled by toCliLlmError/gatewayError and no misleading single-key API hint remains.packages/create-helpbase/src/index.ts (1)
227-227:⚠️ Potential issue | 🟠 MajorDon’t start the dev server after a failed install.
When the background install fails, this prints a manual-install note but still runs
<pkgManager> devafterward. That will usually fail immediately with missing dependencies and bury the actionable recovery message.🐛 Proposed fix
let generationSucceeded = false + let installSucceeded = opts.install === false if (opts.install !== false) { s.start(`Finishing ${pkgManager} install...`) const installResult = await installPromise if (installResult.success) { + installSucceeded = true s.stop("Dependencies installed!") } else { + installSucceeded = false s.stop(pc.yellow("Failed to install dependencies.")) note( `Run ${pc.cyan(`cd ${projectName as string} && ${pkgManager} install`)} manually.\n` + ` Reason: ${installResult.reason}`, "Manual install needed", ) } }- if (opts.install !== false && opts.open !== false) { + if (opts.install !== false && installSucceeded && opts.open !== false) { await startDevServerWithAutoOpen(pkgManager, projectDir) }Also applies to: 257-269, 306-307
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@packages/create-helpbase/src/index.ts` at line 227, The code sets generationSucceeded = false but still starts the dev server after a failed background install; update the install/launch flow so generationSucceeded is set to true only after installDependencies (or the function that performs the background install) completes successfully, and add a guard before invoking the dev server command (the code that runs `${pkgManager} dev` or the function that spawns/execs the dev process) to skip launching when generationSucceeded is false; apply the same guard to the other places mentioned (the blocks around the code at the sections referenced 257-269 and 306-307) so the manual-install recovery message is not buried by a failing dev start.
🧹 Nitpick comments (1)
apps/web/content/guides/byok.mdx (1)
1-152: Duplicate of template guide — keep them in sync.This file is byte-identical in intent to
packages/create-helpbase/templates/content/guides/byok.mdx. Same verification note about thewhoamioutput on lines 121-123 applies here. Consider a lint/check or a generator that prevents these two sources from drifting; a future BYOK env-var change will otherwise need to be remembered in two places.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@apps/web/content/guides/byok.mdx` around lines 1 - 152, The byok.mdx guide ("Bring your own key (BYOK)") is duplicated between the app content and the template (both byok.mdx) and can drift; add a deterministic sync check to CI (or a small verification script) that compares the two byok.mdx sources and fails the build if they differ, or replace the duplicate with a generated/single-source approach; ensure the check targets the byok.mdx content including the "whoami" verification note so future edits must update the template or the single source rather than leaving them divergent.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@packages/create-helpbase/src/index.ts`:
- Around line 617-621: The spawn call that creates the background installer
(const child = spawn(pkgManager, ["install"], { cwd: projectDir, stdio:
["ignore","pipe","pipe"], timeout: 120000 })) can fail on Windows because .cmd
shims require a shell; update the options to set shell: true when
process.platform === "win32" and include windowsHide: true to suppress the
console window, leaving cwd, stdio and timeout unchanged so the install still
runs in the background; reference the existing pkgManager, projectDir and child
variables when making this change.
In `@README.md`:
- Around line 138-141: Update the README to consistently reflect that BYOK
accepts ANTHROPIC_API_KEY, OPENAI_API_KEY, or AI_GATEWAY_API_KEY (first-found)
instead of only "AI Gateway"; search for references to "AI Gateway", "one env
var", `AI_GATEWAY_API_KEY`/`ai-gateway-key` (notably the later sections
referenced) and change wording to either list the three supported env vars or
explicitly state when a feature is Gateway-only (e.g., config-file persistence)
and keep those Gateway-only callouts next to the feature; ensure examples and
docs mention all three env var names (`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`,
`AI_GATEWAY_API_KEY`) and clarify which features are exclusive to the AI
Gateway.
In `@registry/helpbase/content/guides/byok.mdx`:
- Around line 22-34: Update the BYOK guide language so it clarifies that BYOK
prevents helpbase.dev from seeing prompts but that AI_GATEWAY_API_KEY does not
route "provider-direct" — it routes via the Vercel AI Gateway as an
intermediary; edit the header sentence ("You want zero helpbase.dev
round-trips.") and the env var table description for AI_GATEWAY_API_KEY to
explicitly state that AI_GATEWAY routes through Vercel AI Gateway (not directly
to the provider) and keep the precedence note (`AI_GATEWAY_API_KEY` >
`ANTHROPIC_API_KEY` > `OPENAI_API_KEY`) and the ANTHROPIC/OPENAI rows unchanged;
apply the same clarification to the duplicate wording around lines 36-42 so both
occurrences consistently state BYOK bypasses helpbase but may still pass through
intermediaries like Vercel AI Gateway.
---
Outside diff comments:
In `@packages/cli/src/commands/context.ts`:
- Around line 117-128: The GatewayError handling branch that throws a
HelpbaseError in context.ts is stale and duplicates/contradicts the
BYOK-agnostic translation already performed by toCliLlmError (which uses
gatewayError in llm-errors-cli.ts); remove the entire if (err instanceof
GatewayError) { ... } branch (the throw of HelpbaseError) so GatewayError is
only handled by toCliLlmError/gatewayError and no misleading single-key API hint
remains.
In `@packages/cli/src/commands/sync.ts`:
- Around line 66-67: Update the stale help text added by addHelpText in the sync
command so it matches the PR's three-key BYOK + login guidance used elsewhere
(e.g. context.ts/generate.ts); locate the addHelpText call in
packages/cli/src/commands/sync.ts and replace the single-line "Set
AI_GATEWAY_API_KEY first — https://vercel.com/ai-gateway" message with the same
three-key + `helpbase login` phrasing used in the error copy and demo-mode
next-step so --help shows the current guidance.
In `@packages/create-helpbase/src/index.ts`:
- Line 227: The code sets generationSucceeded = false but still starts the dev
server after a failed background install; update the install/launch flow so
generationSucceeded is set to true only after installDependencies (or the
function that performs the background install) completes successfully, and add a
guard before invoking the dev server command (the code that runs `${pkgManager}
dev` or the function that spawns/execs the dev process) to skip launching when
generationSucceeded is false; apply the same guard to the other places mentioned
(the blocks around the code at the sections referenced 257-269 and 306-307) so
the manual-install recovery message is not buried by a failing dev start.
---
Nitpick comments:
In `@apps/web/content/guides/byok.mdx`:
- Around line 1-152: The byok.mdx guide ("Bring your own key (BYOK)") is
duplicated between the app content and the template (both byok.mdx) and can
drift; add a deterministic sync check to CI (or a small verification script)
that compares the two byok.mdx sources and fails the build if they differ, or
replace the duplicate with a generated/single-source approach; ensure the check
targets the byok.mdx content including the "whoami" verification note so future
edits must update the template or the single source rather than leaving them
divergent.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 5fdb98e4-ac4d-47da-a8fd-b2cdeee3203e
📒 Files selected for processing (13)
README.mdapps/web/content/guides/byok.mdxpackages/cli/src/commands/context.tspackages/cli/src/commands/generate.tspackages/cli/src/commands/sync.tspackages/cli/src/lib/auth-device.tspackages/cli/src/lib/inline-auth.tspackages/cli/src/lib/llm-errors-cli.tspackages/create-helpbase/src/env-local.tspackages/create-helpbase/src/index.tspackages/create-helpbase/templates/content/guides/byok.mdxpackages/create-helpbase/test/env-local.unit.test.tsregistry/helpbase/content/guides/byok.mdx
💤 Files with no reviewable changes (2)
- packages/create-helpbase/src/env-local.ts
- packages/create-helpbase/test/env-local.unit.test.ts
| const child = spawn(pkgManager, ["install"], { | ||
| cwd: projectDir, | ||
| stdio: ["ignore", "pipe", "pipe"], | ||
| timeout: 120000, | ||
| }) |
There was a problem hiding this comment.
🧩 Analysis chain
🌐 Web query:
Node.js child_process.spawn Windows .cmd npm shell option official documentation
💡 Result:
In Node.js child_process.spawn on Windows, to execute .cmd or .bat files (including npm scripts via npm.cmd), set the shell option to true. This spawns cmd.exe (via process.env.ComSpec) to run the command, as .cmd/.bat files require a shell and are not directly executable. Official documentation states: "On Windows, however, .bat and .cmd files are not executable on their own without a terminal, and therefore cannot be launched using child_process.execFile. When running on Windows, .bat and .cmd files can be invoked using child_process.spawn with the shell option set..." Example for npm: const { spawn } = require('node:child_process'); const npmProcess = spawn('npm', ['--version'], { shell: true }); Note: Using shell: true has security risks if passing unsanitized input (shell injection). It's marked as not recommended in recent docs (DEP0190), prefer spawning cmd.exe directly: spawn('cmd.exe', ['/c', 'npm', '--version']). Recent change (post CVE-2024-27980 fix in Node.js 18.20.2+, 20.12.2+, etc.): Direct spawn of .cmd/.bat without shell: true now throws EINVAL for security; must use shell: true explicitly.
Citations:
- 1: https://nodejs.org/api/child_process.html
- 2: https://nodejs.org/docs/latest-v18.x/api/child_process.html
- 3: https://nodejs.org/docs/latest/api/child_process.html
- 4: https://nodejs.org/docs/v22.11.0/api/child_process.html
- 5: https://wiz.io/vulnerability-database/cve/cve-2024-27980
- 6: https://www.openwall.com/lists/oss-security/2024/04/10/15
🏁 Script executed:
# First, let's look at the actual code at the specified lines
head -625 packages/create-helpbase/src/index.ts | tail -15Repository: Codehagen/helpbase
Length of output: 579
🏁 Script executed:
# Check the Node.js version requirements in package.json
cat packages/create-helpbase/package.json | grep -A 5 '"engines"'Repository: Codehagen/helpbase
Length of output: 44
🏁 Script executed:
# Search for all spawn calls in the file to see if there are similar patterns
rg "spawn\(" packages/create-helpbase/src/index.ts -A 3Repository: Codehagen/helpbase
Length of output: 592
🏁 Script executed:
# Check root package.json for engines
cat package.json | jq '.engines' 2>/dev/null || grep -A 2 '"engines"' package.jsonRepository: Codehagen/helpbase
Length of output: 99
🏁 Script executed:
# Also check if there's an .nvmrc or similar
cat .nvmrc 2>/dev/null || cat .node-version 2>/dev/null || echo "No version file found"Repository: Codehagen/helpbase
Length of output: 83
🏁 Script executed:
# Let's look at the context around each spawn call to understand what they do
rg "spawn\(" packages/create-helpbase/src/index.ts -B 2 -A 5 | head -60Repository: Codehagen/helpbase
Length of output: 1129
Use a Windows-safe spawn path for package-manager commands.
On Windows with Node.js 20.19.0+ and 22.12.0+ (which this project targets), .cmd package manager shims require either shell: true or explicit spawning of cmd.exe. Without it, the spawn call will fail with EINVAL, breaking the background install feature for Windows users.
Add the shell option conditionally for Windows and use windowsHide to suppress the console window:
Proposed fix
+ const useShell = process.platform === "win32"
const child = spawn(pkgManager, ["install"], {
cwd: projectDir,
stdio: ["ignore", "pipe", "pipe"],
timeout: 120000,
+ shell: useShell,
+ windowsHide: true,
})📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| const child = spawn(pkgManager, ["install"], { | |
| cwd: projectDir, | |
| stdio: ["ignore", "pipe", "pipe"], | |
| timeout: 120000, | |
| }) | |
| const useShell = process.platform === "win32" | |
| const child = spawn(pkgManager, ["install"], { | |
| cwd: projectDir, | |
| stdio: ["ignore", "pipe", "pipe"], | |
| timeout: 120000, | |
| shell: useShell, | |
| windowsHide: true, | |
| }) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@packages/create-helpbase/src/index.ts` around lines 617 - 621, The spawn call
that creates the background installer (const child = spawn(pkgManager,
["install"], { cwd: projectDir, stdio: ["ignore","pipe","pipe"], timeout: 120000
})) can fail on Windows because .cmd shims require a shell; update the options
to set shell: true when process.platform === "win32" and include windowsHide:
true to suppress the console window, leaving cwd, stdio and timeout unchanged so
the install still runs in the background; reference the existing pkgManager,
projectDir and child variables when making this change.
| - **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/<id>`. | | ||
| | `OPENAI_API_KEY` | `@ai-sdk/openai` direct | You already have an OpenAI key. Pair with `--model openai/<id>`. | | ||
| | `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. | |
There was a problem hiding this comment.
Clarify that AI Gateway is not provider-direct.
This page says every BYOK call goes “direct to your provider,” but AI_GATEWAY_API_KEY routes through Vercel AI Gateway. For privacy-sensitive workflows, the distinction matters: BYOK bypasses helpbase, not necessarily every intermediary.
📝 Proposed wording
-- **You want zero helpbase.dev round-trips.** Every BYOK call goes direct to
- your provider. helpbase never sees your prompts.
+- **You want zero helpbase.dev round-trips.** BYOK bypasses helpbase.dev:
+ Anthropic/OpenAI keys call those providers directly; AI Gateway keys route
+ through Vercel AI Gateway. helpbase never sees your prompts.-│ helpbase CLI │─────► Vercel AI SDK direct ─────► your provider
-│ │ (your key, your bill)
+│ helpbase CLI │─────► Vercel AI SDK ─────► Anthropic/OpenAI direct
+│ │ └───────► Vercel AI Gateway ─────► provider
+│ │ (your key, your bill)Also applies to: 36-42
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@registry/helpbase/content/guides/byok.mdx` around lines 22 - 34, Update the
BYOK guide language so it clarifies that BYOK prevents helpbase.dev from seeing
prompts but that AI_GATEWAY_API_KEY does not route "provider-direct" — it routes
via the Vercel AI Gateway as an intermediary; edit the header sentence ("You
want zero helpbase.dev round-trips.") and the env var table description for
AI_GATEWAY_API_KEY to explicitly state that AI_GATEWAY routes through Vercel AI
Gateway (not directly to the provider) and keep the precedence note
(`AI_GATEWAY_API_KEY` > `ANTHROPIC_API_KEY` > `OPENAI_API_KEY`) and the
ANTHROPIC/OPENAI rows unchanged; apply the same clarification to the duplicate
wording around lines 36-42 so both occurrences consistently state BYOK bypasses
helpbase but may still pass through intermediaries like Vercel AI Gateway.
Two follow-ups from the /devex-review audit of the live site: 1) apps/web/app/(main)/errors/[code]/page.tsx had 8 stale Gateway-only hints across 5 error codes (e-missing-api-key, e-auth-required, e-quota-exceeded, e-global-cap, e-llm-network, e-llm-gateway). The CLI-side copy was updated in #8; these web-rendered pages at helpbase.dev/errors/<code> still said "export AI_GATEWAY_API_KEY=..." as the only BYOK option. Rewrote each to the 3-key pattern matching llm-errors-cli.ts. 2) /docs/byok was a 404 everywhere. The live guide lives at /guides/byok. Nine surfaces (README, waitlist page, sync guide, CLI error hints, workflow README, BYOK_DOCS_URL const) pointed at the broken URL — every link a new user followed was dead. Updated BYOK_DOCS_URL in shared/llm-wire.ts as the source of truth, plus all hardcoded strings that didn't flow through it. Test fixtures updated for consistency. Ran pnpm sync:templates + pnpm registry:build so the scaffolder template + registry JSON pick up the fixed sync-in-5-minutes.mdx copy and the workflow README change. 654/654 tests green across shared/cli/scaffolder/web (excluding 2 pre-existing env-bleed cli tests unrelated to this change). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Greps the repo for `https://helpbase.dev/<path>` URLs and HEAD-checks each. Fails on 4xx (broken), treats 401/403/405 as OK (auth-gated or method-gated endpoints are still real), warns on 5xx/timeouts. Exclusions cut noise: test dirs (negative-test fixtures point at fake URLs), planning docs (*_PLAN.md / *_PROMPT.md), CHANGELOG.md, lockfiles. Scheme-ful URLs only — bare `helpbase.dev` in comments isn't a clickable link. Not wired into CI yet — run manually with `pnpm check:links`. Would have caught the 9 broken `/docs/byok` references fixed in the previous commit. First run on main surfaces 9 real 404s not yet fixed: `/docs` (README Demo link), `/docs/cli` (HELPBASE.md template — ships to users), `/docs/troubleshooting#*` (generate.ts error hints ×5), `/account/tokens` (README), plus one bare `/errors` const and a magic-link placeholder. Left for a follow-up so this commit stays scoped. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Ships the follow-up cleanup hinted at in the previous commit. Every fix targets a URL that a real user would click (README badges, CLI error hints, HELPBASE.md in scaffolded projects), not a cosmetic one. - README.md:20 — Demo badge pointed at /docs (404). Now points at /getting-started/introduction (200), which is the canonical "what helpbase is" article for a first-time visitor. - README.md:295 — "Tokens are issued from helpbase.dev/account/tokens" was aspirational (the web dashboard isn't built yet). Replaced with the real workflow: helpbase login + jq the access_token out of ~/.helpbase/auth.json, set as HELPBASE_TOKEN secret in CI. - HELPBASE.md.template + synced template — "Full reference at helpbase.dev/docs/cli" → /cli/commands (200). This file ships into every scaffolded project, so the broken link was in every new user's repo. - packages/cli/src/commands/generate.ts — 7 stale /docs/troubleshooting#* URLs in error messages. 4 had matching /errors/e-* pages (remapped: #bad-frontmatter → e-invalid-frontmatter, #gateway-errors → e-llm-gateway). 3 were generic catchalls with no matching page (printRepoError, printScrapeError, generic printGenerateError) — the "Docs:" line is removed; the error already has Reason + Fix. - packages/create-helpbase/src/index.ts:297 — scaffolder outro banner's "Docs: helpbase.dev/docs" → /getting-started/introduction. - scripts/sync-templates.mjs:435 — the DEFAULT_HELPBASE_MD generator (fallback when no .template file exists) had the same /docs reference. Tooling additions: - scripts/check-links.sh now treats 429 (rate-limited) as "exists" and supports a .linkcheckignore file for known-template-base URLs. - .linkcheckignore lists 3 known false positives: ERROR_DOC_BASE const (template base, never linked directly) and two magic-link verify placeholder strings (illustrative prompt text + React Email preview fixture). Post-fix: 22/22 links pass, 0 broken. Was 9 broken two commits ago. Typecheck green. Shared (152/152) and scaffolder (31/31) tests green. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
/review caught it: the .linkcheckignore filter was building a pipe-joined
regex union and only escaping [, ], ., ^, $, * — leaving ?, =, +, {, },
|, (, ) as regex metacharacters. URLs with query strings like
`/verify?token=` matched nothing in the ignore list, so they leaked past
the filter and only appeared as "exists" because helpbase.dev rate-limited
(429) those probes, which /check-links treats as PASS.
If the server stopped rate-limiting, those URLs would resurface as FAIL.
Silent fragility in what's supposed to be a correctness gate.
Fix: `printf '%s\n' "${URLS[@]}" | grep -F -x -v -f <ignore>` — fixed
strings, exact line, invert match. URLs with any metacharacter now match
literally. Confirmed with a debug run: 22 → 20 checked after the fix
(the two magic-link placeholders now filtered properly instead of passing
on rate-limit luck).
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
CI caught it: removing the `Docs:` line from printRepoError, printScrapeError, and the generic printGenerateError catchall broke `generate.test.ts:48` and `cli.integration.test.ts:84`, both of which enforce the "every error has problem / cause / fix / docs" contract. Restored the line. Now points at https://helpbase.dev/cli/commands (200, confirmed by check-links) — the CLI command reference is a useful landing spot for a user hit with a generic scrape / repo-read / generate error. Was pointing at /docs/troubleshooting#generate-errors, which 404ed. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Summary
Lands the 6 fixes from
/plan-devex-reviewon BYOK onboarding (2026-04-17). Target TTHW: Champion tier (<2 min) for the no-key YC founder persona. Expected post-merge: scaffolder ~1:30,helpbase contextpath ~0:55.guides/byok.mdx, error messages,--helptext, and inline-auth logic — the docs used to claim Gateway-only even after Anthropic/OpenAI direct shipped.helpbase login+helpbase context .(the <90s path) instead of the scaffolder.isByokMode()is now the source of truth;ANTHROPIC_API_KEY/OPENAI_API_KEYusers no longer see a pointless login prompt.Commits
8e6dd08feat(scaffolder): parallel install + single-confirm auth promptdc25907fix(cli): inline-auth uses isByokMode; device-flow poll interval 1s4a52869docs(byok): kill stale Gateway-only framing; lead Quick Start with contextEach commit is independently reviewable.
Test plan
pnpm typecheck— 5/5 greenpnpm build— 4/4 greenpnpm test— 726/726 green across scaffolder / shared / web / mcp / cli (excluding 2 pre-existing env-bleed tests in cli that read the dev machine's real~/.helpbase/auth.json— CI uses a clean env withHELPBASE_SMOKE_TOKENso they pass there)pnpm sync:templates— registry + scaffolder template copies ofbyok.mdxre-syncednpx create-helpbase /tmp/tthw-probe --source ./some/repo— observe install + generation running in parallel; install finishes in background while LLM call is in flightANTHROPIC_API_KEY=sk-ant-test helpbase context .— no spurious hosted-login prompt; routes directhelpbase login— polling spinner ticks at 1s instead of 2s after "Waiting for browser approval…"helpbase.dev/docs/guides/byokafter merge + deploy — new 3-key table renders🤖 Generated with Claude Code
Summary by CodeRabbit
New Features
Documentation
Chores