Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions .linkcheckignore
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
# .linkcheckignore — URLs that the grep picks up but aren't real links.
# One exact URL per line. Lines starting with `#` are comments.
# Consumed by scripts/check-links.sh.

# ERROR_DOC_BASE const in packages/cli/src/lib/errors.ts. Used only as
# a template base: `${ERROR_DOC_BASE}/${code}` → /errors/e-foo (real).
# The bare string is never linked directly.
https://helpbase.dev/errors

# Placeholder text in `helpbase login --email` prompt (login.ts). The
# endpoint exists; the shown `token=` value is illustrative only.
https://helpbase.dev/api/auth/magic-link/verify?token=

# Default prop in the React Email preview component. Never sent to real
# users; only rendered in dev preview tooling.
https://helpbase.dev/api/auth/magic-link/verify?token=preview_token_1234567890abcdef
52 changes: 34 additions & 18 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -17,7 +17,7 @@ built on shadcn/ui.

<br />

**[Website](https://helpbase.dev)** · **[Demo](https://helpbase.dev/docs)** · **[Registry](https://helpbase.dev/r/help-center.json)** · **[@CodeHagen](https://x.com/CodeHagen)**
**[Website](https://helpbase.dev)** · **[Demo](https://helpbase.dev/getting-started/introduction)** · **[Registry](https://helpbase.dev/r/help-center.json)** · **[@CodeHagen](https://x.com/CodeHagen)**

</div>

Expand Down Expand Up @@ -58,20 +58,22 @@ log into.
- **Reduced-motion aware** — animations respect `prefers-reduced-motion`
- **Production-tested** — 300+ tests across the CLI, scaffolder, MCP server, and content pipeline, plus an install-path smoke test in CI

## Try it on your repo in 60 seconds
## Quick start

Point `helpbase context` at any repo. It synthesizes task-oriented how-to
guides grounded in cited files, writes MDX to `.helpbase/docs/`, emits
`llms.txt` + an MCP config hint, and can answer questions in-terminal
without any MCP client setup. Same content, two surfaces: humans read
the MDX, agents query over MCP.
Point `helpbase context` at any repo. Under 90 seconds from zero to
generated docs. Works on macOS, Linux, and Windows. Requires Node 20+.

```bash
npx helpbase login # magic-link, no card, free 500k tokens/day
npx helpbase login # magic-link device flow, free 500k tokens/day, no card
npx helpbase context . # synthesize cited how-tos from your repo
npx helpbase context . --ask "how do I log in?" # answer in terminal, no MCP client required
```

`helpbase context` walks your code + markdown, synthesizes task-oriented
how-to guides grounded in cited files, writes MDX to `.helpbase/docs/`,
and emits `llms.txt` + an MCP config hint. Same content, two surfaces:
humans read the MDX, agents query over MCP.

Every generated doc cites specific files + line ranges. Citations that
don't match the repo literally are dropped before write — no hallucinated
docs. Secret-shaped content aborts the run before any file hits disk.
Expand All @@ -80,10 +82,11 @@ docs. Secret-shaped content aborts the run before any file hits disk.
Paste one of the blocks from `.helpbase/mcp.json` into Claude Desktop,
Cursor, or Claude Code and your agent has your repo as docs.

## Quick start
## Scaffold a full Next.js help-center site

The fastest way to try helpbase. Works on macOS, Linux, and Windows. Requires
Node 20+ and pnpm or npm.
Want a standalone docs site you can deploy, not just `.helpbase/` MDX in
the current repo? Use the scaffolder. Takes ~2 minutes end-to-end
(install runs in parallel with AI generation).

```bash
npx create-helpbase my-help-center
Expand All @@ -92,9 +95,14 @@ npx create-helpbase my-help-center
The scaffolder asks what to seed content from:

- **A website** — paste a URL, it scrapes the page and generates articles.
- **A code repository** — paste a local path or a `github.com` URL. The scaffolder walks your source, synthesizes cited how-to guides with file + line refs, and writes them to `content/`. Needs a helpbase login (free, 500k tokens/day) or `AI_GATEWAY_API_KEY`.
- **A code repository** — paste a local path or a `github.com` URL. The scaffolder walks your source, synthesizes cited how-to guides with file + line refs, and writes them to `content/`.
- **Skip** — ship with sample articles.

If you're not logged in, the scaffolder offers one-click inline login
(free, 500k tokens/day, no card). If you prefer BYOK, export
`ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `AI_GATEWAY_API_KEY` before
running and the scaffolder uses that directly.

Dependencies install, the dev server starts, and your browser opens at
`http://localhost:3000`. Edit the markdown in `content/` and the dev
server hot-reloads.
Expand Down Expand Up @@ -127,10 +135,10 @@ The `--test` flag uses Gemini 3.1 Flash Lite for cheap, fast generation. Pass
`--model anthropic/claude-sonnet-4.6` (or any Gateway-supported model) to
override.

**Power users + CI:** skip the helpbase proxy entirely with your own
[Vercel AI Gateway](https://vercel.com/ai-gateway) key — `export
AI_GATEWAY_API_KEY=...` before running. See
[helpbase.dev/docs/byok](https://helpbase.dev/docs/byok).
**Power users + CI:** skip the helpbase proxy with whichever key you
already have — `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or
`AI_GATEWAY_API_KEY` (any one works, first found wins). See
[helpbase.dev/guides/byok](https://helpbase.dev/guides/byok).

### Drop into an existing Next.js app

Expand Down Expand Up @@ -284,8 +292,16 @@ automatically; pass `--json` or `--quiet` to guarantee composable output.
| `helpbase generate` | `--url <url>` (or `--repo <path>`) + `--yes` |
| `helpbase new` | `--type <type> --title "..."` (optional `--category`, `--slug`) |

Tokens are issued from `https://helpbase.dev/account/tokens`. Export
once in CI and the CLI auths non-interactively for every command.
Grab a session token by running `helpbase login` locally, then reading
it from `~/.helpbase/auth.json`:

```bash
jq -r .access_token ~/.helpbase/auth.json
```

Set the value as a `HELPBASE_TOKEN` secret in your CI and the CLI auths
non-interactively for every command. (A web dashboard for token management
is not yet live — cut one from the local file for now.)

## Shell completion

Expand Down
31 changes: 17 additions & 14 deletions apps/web/app/(main)/errors/[code]/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -158,13 +158,16 @@ const ERRORS: Record<string, ErrorDoc> = {
},
"e-missing-api-key": {
code: "E_MISSING_API_KEY",
title: "AI_GATEWAY_API_KEY not set",
title: "No helpbase session or BYOK key",
summary:
"helpbase generate needs an AI gateway key to call the model provider.",
causes: ["AI_GATEWAY_API_KEY isn't in your environment."],
"helpbase generate needs either a helpbase session (free tier) or a BYOK provider key to call the LLM.",
causes: [
"You're not signed in (no `~/.helpbase/auth.json`) and no BYOK env var is set.",
],
fixes: [
"Get a key at https://vercel.com/ai-gateway.",
"Export it: `export AI_GATEWAY_API_KEY=<your-key>`.",
"Run `helpbase login` — free, 500k tokens/day, no card.",
"Or export any one of `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, `AI_GATEWAY_API_KEY` (first found wins).",
"See https://helpbase.dev/guides/byok for per-provider setup.",
],
},
"e-no-mcp-token": {
Expand Down Expand Up @@ -291,9 +294,9 @@ const ERRORS: Record<string, ErrorDoc> = {
fixes: [
"Run `helpbase login` — free tier, no card, 500k tokens/day.",
"For CI: set `HELPBASE_TOKEN` to a valid session token.",
"Or bring your own key: `export AI_GATEWAY_API_KEY=…` (see /docs/byok).",
"Or bring your own key: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `AI_GATEWAY_API_KEY` (first found wins — see /guides/byok).",
],
seeAlso: [{ label: "BYOK docs", href: "/docs/byok" }],
seeAlso: [{ label: "BYOK docs", href: "/guides/byok" }],
},
"e-quota-exceeded": {
code: "E_QUOTA_EXCEEDED",
Expand All @@ -307,11 +310,11 @@ const ERRORS: Record<string, ErrorDoc> = {
fixes: [
"Wait for the UTC-midnight reset.",
"Join the paid-tier waitlist: https://helpbase.dev/waitlist",
"Bring your own Vercel AI Gateway key: `export AI_GATEWAY_API_KEY=…` (unlimited, your own bill).",
"Bring your own key: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `AI_GATEWAY_API_KEY` (unlimited on your own bill, first found wins).",
],
seeAlso: [
{ label: "Waitlist", href: "/waitlist" },
{ label: "BYOK docs", href: "/docs/byok" },
{ label: "BYOK docs", href: "/guides/byok" },
],
},
"e-global-cap": {
Expand All @@ -325,9 +328,9 @@ const ERRORS: Record<string, ErrorDoc> = {
],
fixes: [
"Wait for the UTC-midnight reset.",
"Bring your own Vercel AI Gateway key to bypass the hosted proxy entirely: `export AI_GATEWAY_API_KEY=…`",
"Bring your own key to bypass the hosted proxy entirely: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `AI_GATEWAY_API_KEY`.",
],
seeAlso: [{ label: "BYOK docs", href: "/docs/byok" }],
seeAlso: [{ label: "BYOK docs", href: "/guides/byok" }],
},
"e-llm-network": {
code: "E_LLM_NETWORK",
Expand All @@ -342,17 +345,17 @@ const ERRORS: Record<string, ErrorDoc> = {
fixes: [
"Check your connection and retry — transient blips are common.",
"If you're behind a corporate proxy, verify helpbase.dev is reachable.",
"Fall back to BYOK so calls don't go through helpbase.dev: `export AI_GATEWAY_API_KEY=…`",
"Fall back to BYOK so calls don't go through helpbase.dev: `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`, or `AI_GATEWAY_API_KEY`.",
],
seeAlso: [{ label: "BYOK docs", href: "/docs/byok" }],
seeAlso: [{ label: "BYOK docs", href: "/guides/byok" }],
},
"e-llm-gateway": {
code: "E_LLM_GATEWAY",
title: "LLM provider returned an error",
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.",
],
Expand Down
4 changes: 2 additions & 2 deletions apps/web/app/(main)/waitlist/page.tsx
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,8 @@ async function WaitlistContent({

<p className="mt-2 text-sm text-muted-foreground">
Need more tokens right now?{" "}
<a href="/docs/byok" className="underline hover:text-foreground">
Bring your own Vercel AI Gateway key
<a href="/guides/byok" className="underline hover:text-foreground">
Bring your own key (Anthropic, OpenAI, or Gateway)
</a>{" "}
— unlimited, your own cost.
</p>
Expand Down
Loading
Loading