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
32 changes: 16 additions & 16 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,9 +6,9 @@

Helpbase ships MCP, `llms.txt`, and (soon) codebase-grounded doc sync as
primitives that run in your repo, not services in someone else's cloud.
Scaffold in two minutes with `npx create-helpbase`, or drop it into an
existing Next.js app with `shadcn add`. Open source, self-hostable,
built on shadcn/ui.
Create your help center in two minutes with `npx create-helpbase`, or
drop it into an existing Next.js app with `shadcn add`. Open source,
self-hostable, built on shadcn/ui.

[![npm version](https://img.shields.io/npm/v/helpbase.svg?color=111)](https://www.npmjs.com/package/helpbase)
[![license](https://img.shields.io/badge/license-AGPL--3.0-111)](./LICENSE)
Expand Down Expand Up @@ -46,7 +46,7 @@ log into.

## Features

- **One command to ship** — `npx create-helpbase` scaffolds a working help center in under two minutes
- **One command to ship** — `npx create-helpbase` creates a working help center in under two minutes
- **Drop into existing apps** — `npx shadcn add https://helpbase.dev/r/help-center.json` adds the full block to any Next.js + shadcn/ui project
- **AI article generation** — point the CLI at a URL, a local repo, or a folder of screenshots and get real MDX articles back, grounded in the source
- **MDX content pipeline** — gray-matter frontmatter, remark-gfm, rehype-slug, syntax highlighting, zero config
Expand All @@ -56,12 +56,12 @@ log into.
- **Type-safe content** — Zod schemas validate frontmatter at build time, catch missing fields before deploy
- **Content audit CLI** — `helpbase audit` catches missing titles, broken schemas, and empty categories in CI
- **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
- **Production-tested** — 300+ tests across the CLI, `create-helpbase`, MCP server, and content pipeline, plus an install-path smoke test in CI

## Quick start

Live help center in 90 seconds. Scaffold, answer Y, you're on the
public internet. Works on macOS, Linux, and Windows. Requires Node 20+.
Live help center in 90 seconds. Create the project, answer Y, you're on
the public internet. Works on macOS, Linux, and Windows. Requires Node 20+.

```bash
pnpm dlx create-helpbase@latest my-docs # or: npx create-helpbase@latest my-docs
Expand All @@ -72,7 +72,7 @@ pnpm dlx create-helpbase@latest my-docs # or: npx create-helpbase@latest my-d
That's it. Answering Y at the end runs `helpbase login` (browser
device-flow, free 500k tokens/day, no card) and `helpbase deploy`
back-to-back and prints the public URL + MCP config block. Answer `n`
to keep the classic flow: the scaffolder starts `pnpm dev` locally and
to keep the classic flow: `create-helpbase` starts `pnpm dev` locally and
you run `helpbase login` + `helpbase deploy` yourself when ready. CI /
pipelines pass `--no-deploy` (or `--deploy` with `HELPBASE_TOKEN`) to
skip the prompt.
Expand All @@ -85,7 +85,7 @@ removal lands. `helpbase rename acme` claims a vanity slug
the URL is locked so existing links don't break. Run `helpbase whoami`
to see what's reserved + deployed.

> **Already have a Next.js app?** Skip the scaffolder:
> **Already have a Next.js app?** Skip `create-helpbase`:
> `npx shadcn add https://helpbase.dev/r/help-center.json`

### Local: point ingest at any repo
Expand Down Expand Up @@ -113,26 +113,26 @@ 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.

## Scaffold a full Next.js help-center site
## Create a full Next.js help-center site

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
the current repo? Use `create-helpbase`. Takes ~2 minutes end-to-end
(install runs in parallel with AI generation).

```bash
npx create-helpbase my-help-center
```

The scaffolder asks what to seed content from:
`create-helpbase` 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/`.
- **A code repository** — paste a local path or a `github.com` URL. `create-helpbase` 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
If you're not logged in, `create-helpbase` 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.
running and `create-helpbase` 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
Expand Down Expand Up @@ -274,7 +274,7 @@ no runtime transforms, nothing to audit or mistrust.
helpbase uses the [Vercel AI SDK](https://ai-sdk.dev) + [AI Gateway](https://vercel.com/ai-gateway)
for generation. One env var, one string-typed model ID, no provider SDKs.

Generate articles any time after scaffolding:
Generate articles any time after creating the project:

```bash
helpbase generate --url https://yourproduct.com # default model
Expand Down
2 changes: 1 addition & 1 deletion packages/cli/src/commands/doctor.ts
Original file line number Diff line number Diff line change
Expand Up @@ -219,7 +219,7 @@ async function collectChecks(opts: CheckOptions): Promise<Check[]> {
category: "project",
severity: "warn",
value: "missing",
fix: "Run from a project root, or scaffold with `npx create-helpbase`",
fix: "Run from a project root, or create one with `npx create-helpbase`",
})
}

Expand Down
20 changes: 10 additions & 10 deletions packages/create-helpbase/src/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -91,15 +91,15 @@ const program = new Command()
.option("--model <id>", "Override the AI model ID")
.option(
"--internal",
"Scaffold an internal-KB layout (handbook + runbooks + ADRs, auth-ready MCP via HELPBASE_MCP_TOKEN)",
"Use the internal-KB layout (handbook + runbooks + ADRs, auth-ready MCP via HELPBASE_MCP_TOKEN)",
)
.option(
"--deploy",
"Ship to helpbase cloud immediately after scaffold (skip the prompt, assume yes)",
"Publish to helpbase cloud immediately after creation (skip the prompt, assume yes)",
)
.option(
"--no-deploy",
"Skip the ship-it-now prompt (scaffold only, keep today's behavior)",
"Skip the ship-it-now prompt (create only, don't publish)",
)
.action(run)

Expand Down Expand Up @@ -216,7 +216,7 @@ async function run(directory: string | undefined, opts: RunOptions) {
const loginResult = await runHelpbaseLogin()
if (loginResult === "failed") {
note(
`Couldn't complete login. You can still scaffold + use sample content. Run ${pc.cyan("npx helpbase@latest login")} later to claim a subdomain.`,
`Couldn't complete login. You can still create the project + use sample content. Run ${pc.cyan("npx helpbase@latest login")} later to claim a subdomain.`,
"Login skipped",
)
} else {
Expand Down Expand Up @@ -257,7 +257,7 @@ async function run(directory: string | undefined, opts: RunOptions) {
internal: opts.internal,
})

s.stop("Project scaffolded!")
s.stop("Help center ready!")

// 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
Expand Down Expand Up @@ -696,7 +696,7 @@ async function runUrlGeneration(opts: {
s.stop("Articles generated!")
return true
} catch (err) {
s.stop(pc.yellow("Couldn't generate articles. Sample content shipped with the scaffold remains."))
s.stop(pc.yellow("Couldn't generate articles. Sample content shipped with the help center remains."))
printGenerationFallbackHint(err, url)
return false
}
Expand Down Expand Up @@ -751,7 +751,7 @@ async function runRepoGeneration(opts: {
return true
} catch (err) {
if (lastPhase !== null) {
s.stop(pc.yellow("Couldn't generate articles. Sample content shipped with the scaffold remains."))
s.stop(pc.yellow("Couldn't generate articles. Sample content shipped with the help center remains."))
}
printRepoGenerationFallbackHint(err, repoPath)
return false
Expand Down Expand Up @@ -907,7 +907,7 @@ function printRepoGenerationFallbackHint(err: unknown, repoPath: string): void {
note(
`${err.message}\n` +
`Point at a subdirectory with more focused content, or run:\n` +
` ${pc.cyan(`helpbase ingest ${quotedRepoPath} --max-tokens 200000`)} after scaffold.`,
` ${pc.cyan(`helpbase ingest ${quotedRepoPath} --max-tokens 200000`)} from the new project.`,
"Repo is too large",
)
return
Expand All @@ -925,15 +925,15 @@ function printRepoGenerationFallbackHint(err: unknown, repoPath: string): void {
`This is common on cheap models that paraphrase quoted code.\n\n` +
`Retry with:\n` +
` ${pc.cyan(`helpbase ingest ${quotedRepoPath} --model anthropic/claude-sonnet-4.6`)}\n` +
`after scaffold to regenerate with a stronger model.`,
`from the new project to regenerate with a stronger model.`,
"All articles dropped",
)
return
}
if (err instanceof GatewayError) {
note(
`Gateway error: ${err.message}\n` +
`Retry with ${pc.cyan(`helpbase ingest ${quotedRepoPath} --test`)} after scaffold to use a cheap fallback model.`,
`Retry with ${pc.cyan(`helpbase ingest ${quotedRepoPath} --test`)} from the new project to use a cheap fallback model.`,
"AI generation failed",
)
return
Expand Down
Loading