docs: Diátaxis restructure + pocketbase-typegen migration guide

[Karnak19]

Why

The docs had grown reference-heavy with how-tos tangled into reference pages and no standalone Explanation content. This restructures the site around the four Diátaxis modes and fills the gaps, plus adds the requested migration guide.

What changed

New migration guide — how-to/migrate-from-pocketbase-typegen.md: dependency swap, CLI-flags → pbkit.config.ts mapping (--db/--url/--json), type-name remapping, pb.collection(...) → generated-function table, typed expand, auth, verification.

Diátaxis restructure — sidebar rebuilt into four sections:

Section	Pages
Tutorials	Your first typed SDK (reframed Quick Start)
How-to Guides	Install · Configure collections · Add TanStack Query · Add Zod schemas · Write a plugin · Migrate from pocketbase-typegen
Reference	CLI · Configuration · Generated types · Generated SDK · Field type mapping · Expand types · Programmatic API
Explanation	How pbkit works · The generated files · Relations and expand paths · Why a generated SDK (all new)

• Pages moved with git mv (history preserved), retitled to verb-form for how-tos, re-ordered per section
• expand-types split into lean reference + a new conceptual explanation page
• All internal links and nav links rewritten to the new paths

Verification

• bun run build passes — 20 pages, no broken internal links, search index rebuilt
• No stale old-path links remain (grep-verified)

Note for review

The four new Explanation pages describe the parse→IR→generate pipeline and cycle/depth handling at a conceptual level, grounded in the public API (SchemaIR, parseApi/parseJson/parseSqlite, expandDepth). I did not read the generator internals — worth a sanity check that the described mechanisms match the implementation.

🤖 Generated with Claude Code

[github-actions]

Docs restructure looks well-organized. Two small accuracy issues found:

• getArticles is referenced as a generated function name but doesn't exist — the list function is listArticles
• A cross-reference link text ("Expand Types") points to a page with a different title

[github-actions]

Docs restructure looks solid — Diátaxis classification is clean and the migration guide is thorough. Three minor issues in the new migration guide:

• devDependency: bun add installs pbkit as a runtime dependency; it should be a devDependency since it's a build-time tool.
• Token auth gap: The email/password → token mapping doesn't explain how to obtain a PocketBase API token, which will block migrants.
• Missing Zod link: The "Next steps" section mentions Zod schemas in the description but only links to the TanStack Query page.

[github-actions]

Three remaining documentation accuracy issues in the migration guide:

• pbkit installed as regular dependency instead of devDependency (medium — affects deploy bundles)
• API token concept unexplained for users coming from email/password auth (high — blocks migration at step 2)
• Zod schemas mentioned in "Next steps" but not linked (low — discoverability)

[github-actions]

Problem: bun add @karnak19/pbkit pocketbase installs both packages as regular dependencies. pbkit is a build-time code generator and should be a devDependency — it has no role in production and pulling it into serverless/edge bundles adds unnecessary weight.

Impact: Users migrating from pocketbase-typegen (which was almost certainly a devDependency) would inadvertently move their code-gen tool into dependencies, potentially increasing deploy size and install time in production environments.

Fix: Split the install commands so pbkit goes to devDependencies and pocketbase (the runtime SDK) stays as a regular dependency:

bun remove pocketbase-typegen
bun add -d @karnak19/pbkit
bun add pocketbase

[Karnak19]

Good catch — fixed in 6d8202c. Split the install so pbkit goes in as a dev dependency (bun add -d @karnak19/pbkit) and pocketbase stays a runtime dependency, and updated the surrounding prose to call out that pbkit is build-time only.

[github-actions]

Problem: The table maps --email ... --password ... to token: "..." but never explains what this token is or how to obtain one. pocketbase-typegen authenticates with admin email/password credentials; pbkit uses an API token. This is a conceptual shift that will block users at this step.

Impact: A developer following this guide will see token: "ADMIN_AUTH_TOKEN" and have no idea where to get that value — it's not the same as their old email/password pair.

Fix: Add a short note (or a callout block) explaining that pbkit uses a PocketBase admin API token instead of email+password, and link to the PocketBase docs on how to generate one (e.g., via the admin UI or the POST /api/admins/auth-with-password endpoint to obtain a token). Something like:

pbkit authenticates with an API token rather than email/password. Generate one from the PocketBase admin UI under Settings → API tokens, or obtain one via the admin auth endpoint.

[Karnak19]

Agreed, this was a real gap — fixed in 6d8202c. Added a callout explaining that pbkit takes a superuser auth token (not email/password), how to obtain one via POST /api/collections/_superusers/auth-with-password, that it is only needed for non-public schemas, and to load it from an env var. Also updated the config example to use process.env.PB_ADMIN_TOKEN.

[github-actions]

Problem: The description says "generate TanStack Query options or Zod schemas" but the link only points to the TanStack Query page. The Zod schemas page (/how-to/add-zod-schemas) is not linked, so users looking for Zod guidance will have to find it manually.

Impact: Minor discoverability issue — the text promises two options but only provides a link for one.

Fix: Link to both pages, matching the pattern used in the tutorial's "Next steps" section:

- [Add TanStack Query](/how-to/add-tanstack-query) or [Zod schemas](/how-to/add-zod-schemas) via plugins

[Karnak19]

Fixed in 6d8202c — the Next steps bullet now links both Add TanStack Query and Zod schemas, matching the tutorial pattern.

[github-actions]

All three previously flagged issues in the migration guide are confirmed fixed in the current diff. One remaining inconsistency found in the SKILL.md agent instructions:

• SKILL.md missing -d flag (medium): The condensed migration instructions say add @karnak19/pbkit without -d, contradicting the fix already applied to the full migration guide. An AI agent following this literally would install pbkit as a runtime dependency.

[github-actions]

Problem: This line says add @karnak19/pbkit without the -d flag. The same issue was caught and fixed in the migration guide (how-to/migrate-from-pocketbase-typegen.md) during the previous review round — the guide now correctly uses bun add -d @karnak19/pbkit — but the fix was not propagated to this condensed SKILL.md summary.

Impact: An AI coding agent following these instructions literally would run bun add @karnak19/pbkit, installing the code generator as a regular dependency instead of a devDependency. This is the exact same class of bug that was already fixed in the user-facing guide, and it would silently undo that fix for any project where an agent handles the migration.

Fix: Add -d to match the migration guide:

- Swap dependencies: remove `pocketbase-typegen`, add `-d @karnak19/pbkit`. Keep `pocketbase`.

[Karnak19]

Good consistency catch — fixed in 90fd421. The migration bullet in SKILL.md now uses add -d @karnak19/pbkit and notes pocketbase stays a runtime dependency, matching the migration guide.

[github-actions]

No new major issues found. All four previously raised issues (devDependency install, token explanation, dual plugin links, SKILL.md consistency) have been verified as correctly addressed in the latest commits (00c98d2). The Diátaxis restructuring is clean — new explanation/tutorial/how-to/reference pages are technically accurate, internal links are consistently updated, and install commands correctly separate devDependencies from runtime dependencies across all pages. Review threads could not be auto-resolved due to permissions but all fixes are confirmed.