Docs Overhaul Implementation Plan

For Claude: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.

Goal: Rewrite all hatk documentation to reflect the current API (generated client, SQLite-only, SvelteKit remote commands, parseViewer/login/logout from $hatk/client).

Architecture: VitePress site at docs/site/. Rewrite every page in-place, add new frontend/ section, update nav config. Source examples from ~/code/hatk-template-statusphere and ~/code/hatk-template-teal.

Tech Stack: VitePress, Markdown, TypeScript code blocks

Design doc: docs/plans/2026-03-18-docs-overhaul-design.md

---

Batch 1: Foundation (config + landing page + nav)

Task 1: Update VitePress config and nav

Files:

• Modify: docs/site/.vitepress/config.ts

Step 1: Rewrite the config

Replace the full config with updated nav and sidebar. Add Frontend section, remove api-client, rename OAuth → Auth & OAuth, remove Deployment from guides (move to CLI build page).

import { defineConfig } from 'vitepress'

export default defineConfig({
  title: 'hatk',
  description: 'Build AT Protocol applications with typed XRPC endpoints.',

  themeConfig: {
    nav: [
      { text: 'Guide', link: '/getting-started/quickstart' },
      { text: 'Frontend', link: '/frontend/setup' },
      { text: 'CLI', link: '/cli/' },
      { text: 'API', link: '/api/' },
    ],

    sidebar: [
      {
        text: 'Getting Started',
        items: [
          { text: 'Quickstart', link: '/getting-started/quickstart' },
          { text: 'Project Structure', link: '/getting-started/project-structure' },
          { text: 'Configuration', link: '/getting-started/configuration' },
        ],
      },
      {
        text: 'Guides',
        items: [
          { text: 'Feeds', link: '/guides/feeds' },
          { text: 'XRPC Handlers', link: '/guides/xrpc-handlers' },
          { text: 'Auth & OAuth', link: '/guides/auth' },
          { text: 'Seeds', link: '/guides/seeds' },
          { text: 'Labels', link: '/guides/labels' },
          { text: 'OpenGraph', link: '/guides/opengraph' },
          { text: 'Hooks', link: '/guides/hooks' },
        ],
      },
      {
        text: 'Frontend',
        items: [
          { text: 'SvelteKit Setup', link: '/frontend/setup' },
          { text: 'Data Loading', link: '/frontend/data-loading' },
          { text: 'Mutations', link: '/frontend/mutations' },
        ],
      },
      {
        text: 'CLI Reference',
        items: [
          { text: 'Overview', link: '/cli/' },
          { text: 'Scaffolding', link: '/cli/scaffold' },
          { text: 'Development', link: '/cli/development' },
          { text: 'Testing', link: '/cli/testing' },
          { text: 'Build & Deploy', link: '/cli/build' },
        ],
      },
      {
        text: 'API Reference',
        items: [
          { text: 'Overview', link: '/api/' },
          { text: 'Records', link: '/api/records' },
          { text: 'Feeds', link: '/api/feeds' },
          { text: 'Search', link: '/api/search' },
          { text: 'Blobs', link: '/api/blobs' },
          { text: 'Preferences', link: '/api/preferences' },
          { text: 'Labels', link: '/api/labels' },
        ],
      },
    ],

    socialLinks: [{ icon: 'github', link: 'https://github.com/bigmoves/hatk' }],
  },
})

Step 2: Verify

Run: cd docs/site && npx vitepress build 2>&1 | tail -5 Expected: Build succeeds (some dead links expected until pages are written)

Step 3: Commit

git add docs/site/.vitepress/config.ts
git commit -m "docs: update nav structure for docs overhaul"

Task 2: Rewrite landing page

Files:

• Modify: docs/site/index.md

Step 1: Rewrite with project tree and feature cards

---
layout: home

hero:
  name: hatk
  tagline: Build AT Protocol apps with typed XRPC endpoints.
  actions:
    - theme: brand
      text: Get Started
      link: /getting-started/quickstart
    - theme: alt
      text: CLI Reference
      link: /cli/

features:
  - title: Typed end-to-end
    details: Lexicons generate TypeScript types for records, queries, and feeds. Your editor catches mistakes before your users do.
  - title: SQLite by default
    details: No external database to configure. Data lives in a single file that just works — locally and in production.
  - title: OAuth built-in
    details: AT Protocol auth with session cookies. Login, logout, and viewer resolution with zero setup.
  - title: SvelteKit-first
    details: Full-stack with SSR, remote commands, and typed XRPC calls from a generated client.
---

## Project Structure

A hatk app looks like this:

my-app/ ├── app/ # SvelteKit frontend │ ├── routes/ │ │ ├── +layout.server.ts # parseViewer(cookies) │ │ └── +page.svelte # Your UI │ └── lib/ ├── server/ # Backend handlers │ ├── feeds/ # Feed generators │ │ └── recent.ts # defineFeed({ ... }) │ └── xrpc/ # Custom XRPC endpoints │ └── getProfile.ts # defineQuery('...', ...) ├── seeds/ │ └── seed.ts # Test fixture data ├── lexicons/ # AT Protocol schemas (like Prisma models) ├── hatk.config.ts # Server configuration └── hatk.generated.ts # Auto-generated types from lexicons

Step 2: Commit

git add docs/site/index.md
git commit -m "docs: rewrite landing page with project tree and features"

---

Batch 2: Getting Started (3 pages)

Task 3: Rewrite quickstart

Files:

• Modify: docs/site/getting-started/quickstart.md

Rewrite to reflect current CLI (hatk new with --svelte default, npm run dev instead of npx hatk dev, hatk.config.ts not config.yaml). Steps:

1. Prerequisites (Node 22+, Docker for local dev)
2. npx hatk new my-app — show the project it creates
3. cd my-app && npm run dev — starts PDS, seeds, dev server
4. Open http://localhost:5173, see the app
5. Next steps links

Source accurate project structure from ~/code/hatk-template-statusphere. Reference hatk.config.ts not config.yaml. No DuckDB mentions.

Step 1: Rewrite the page Step 2: Commit

git add docs/site/getting-started/quickstart.md
git commit -m "docs: rewrite quickstart for current CLI and project structure"

Task 4: Rewrite project structure

Files:

• Modify: docs/site/getting-started/project-structure.md

Expanded annotated tree matching actual template layout:

• app/ — SvelteKit frontend, routes, lib
• server/ — feeds, xrpc handlers, hooks, labels, og, setup
• seeds/ — test fixtures
• lexicons/ — AT Protocol schemas with brief explanation
• hatk.config.ts — link to configuration page
• hatk.generated.ts / hatk.generated.client.ts — what they contain
• vite.config.ts, svelte.config.js, tsconfig.json — brief notes

Each directory gets 2-3 sentences and a link to the relevant guide.

Step 1: Rewrite the page Step 2: Commit

git add docs/site/getting-started/project-structure.md
git commit -m "docs: rewrite project structure with annotated tree"

Task 5: Rewrite configuration

Files:

• Modify: docs/site/getting-started/configuration.md

Reference: read ~/code/hatk/packages/hatk/src/cli.ts for the config type definition, and ~/code/hatk-template-statusphere/hatk.config.ts for a real example.

Structure:

1. Minimal config example at top
2. Full reference table grouped by: Server, Database, Backfill, OAuth
3. Each option: name, type, default, description
4. No DuckDB options. No config.yaml references.

Step 1: Rewrite the page Step 2: Commit

git add docs/site/getting-started/configuration.md
git commit -m "docs: rewrite configuration for hatk.config.ts"

---

Batch 3: Guides — core (3 pages)

Task 6: Rewrite feeds guide

Files:

• Modify: docs/site/guides/feeds.md

Source examples from ~/code/hatk-template-statusphere/server/recent.ts and ~/code/hatk-template-teal/server/feeds/. Replace all DuckDB references with SQLite. Keep the generate/hydrate context tables but update them.

Pattern: what feeds do → minimal example → generate context reference → paginate helper → hydrate context reference → full example with hydration.

Step 1: Rewrite the page Step 2: Commit

git add docs/site/guides/feeds.md
git commit -m "docs: rewrite feeds guide with SQLite examples"

Task 7: Rewrite XRPC handlers guide

Files:

• Modify: docs/site/guides/xrpc-handlers.md

Source examples from ~/code/hatk-template-teal/server/xrpc/. Cover defineQuery() and defineProcedure() with typed Ctx<K>. Show ctx.ok(), ctx.db.query(), ctx.lookup(), ctx.viewer.

Step 1: Read current page and template examples Step 2: Rewrite the page Step 3: Commit

git add docs/site/guides/xrpc-handlers.md
git commit -m "docs: rewrite XRPC handlers guide"

Task 8: Rewrite auth guide (rename oauth.md → auth.md)

Files:

• Create: docs/site/guides/auth.md
• Delete: docs/site/guides/oauth.md
• Delete: docs/site/guides/api-client.md
• Delete: docs/site/guides/frontend.md

Complete rewrite. No OAuthClient class. Structure:

1. Overview — hatk handles OAuth server-side with session cookies
2. Config — hatk.config.ts oauth section with scopes and clients
3. Frontend auth — login(handle) and logout() from $hatk/client
4. Server-side — parseViewer(cookies) in +layout.server.ts, getViewer() in handlers, ctx.viewer
5. Complete example showing config → layout → login form → protected route

Source from ~/code/hatk-template-statusphere for the simple case.

Also delete api-client.md and frontend.md since their content moves to the new Frontend section.

Step 1: Write new auth.md Step 2: Delete old files Step 3: Commit

git add docs/site/guides/auth.md
git rm docs/site/guides/oauth.md docs/site/guides/api-client.md docs/site/guides/frontend.md
git commit -m "docs: rewrite auth guide, remove obsolete oauth/api-client/frontend pages"

---

Batch 4: Guides — remaining (4 pages)

Task 9: Rewrite seeds guide

Files:

• Modify: docs/site/guides/seeds.md

Source from ~/code/hatk-template-statusphere/seeds/seed.ts and ~/code/hatk-template-teal/seeds/seed.ts. Show seed() with createAccount, createRecord, uploadBlob. Mention hatk seed and hatk reset.

Step 1: Rewrite the page Step 2: Commit

git add docs/site/guides/seeds.md
git commit -m "docs: rewrite seeds guide"

Task 10: Rewrite labels guide

Files:

• Modify: docs/site/guides/labels.md

Brief. Show defineLabel() with evaluate(). Source from actual label files if they exist in templates, otherwise from CLI scaffolding output.

Step 1: Read current page and find examples Step 2: Rewrite the page Step 3: Commit

git add docs/site/guides/labels.md
git commit -m "docs: rewrite labels guide"

Task 11: Rewrite opengraph guide

Files:

• Modify: docs/site/guides/opengraph.md

Brief. Show defineOG() with Satori rendering. Source from template OG files.

Step 1: Read current page and find examples Step 2: Rewrite the page Step 3: Commit

git add docs/site/guides/opengraph.md
git commit -m "docs: rewrite opengraph guide"

Task 12: Rewrite hooks guide

Files:

• Modify: docs/site/guides/hooks.md

Brief. Show defineHook('on-login', ...) with ensureRepo. One example from templates.

Step 1: Rewrite the page Step 2: Commit

git add docs/site/guides/hooks.md
git commit -m "docs: rewrite hooks guide"

---

Batch 5: Frontend section (3 new pages)

Task 13: Write frontend/setup page

Files:

• Create: docs/site/frontend/setup.md

Cover:

• Vite plugin (hatk() in vite.config.ts)
• $hatk and $hatk/client aliases
• What hatk.generated.ts vs hatk.generated.client.ts contain
• The app/ directory convention (svelte.config.js files.src)
• hatk generate types for regeneration after lexicon changes

Source from ~/code/hatk-template-statusphere/vite.config.ts and svelte.config.js.

Step 1: Write the page Step 2: Commit

git add docs/site/frontend/setup.md
git commit -m "docs: add frontend setup page"

Task 14: Write frontend/data-loading page

Files:

• Create: docs/site/frontend/data-loading.md

Cover:

• callXrpc() from $hatk/client
• Server load (+page.server.ts) — uses bridge directly
• Universal load (+page.ts) — works both sides
• customFetch parameter for SvelteKit's fetch deduplication
• getViewer() for accessing current user in server code

Source from ~/code/hatk-template-statusphere/app/routes/+page.server.ts and ~/code/hatk-template-teal/app/routes/+page.ts.

Step 1: Write the page Step 2: Commit

git add docs/site/frontend/data-loading.md
git commit -m "docs: add frontend data loading page"

Task 15: Write frontend/mutations page

Files:

• Create: docs/site/frontend/mutations.md

Cover:

• Remote commands with command('unchecked', ...)
• callXrpc('dev.hatk.createRecord', ...) and deleteRecord
• Optimistic UI pattern

Source from ~/code/hatk-template-statusphere/app/routes/status.remote.ts.

Step 1: Write the page Step 2: Commit

git add docs/site/frontend/mutations.md
git commit -m "docs: add frontend mutations page"

---

Batch 6: CLI and API reference updates

Task 16: Update CLI pages

Files:

• Modify: docs/site/cli/index.md
• Modify: docs/site/cli/scaffold.md
• Modify: docs/site/cli/development.md
• Modify: docs/site/cli/testing.md
• Modify: docs/site/cli/build.md

Read each page, update references: config.yaml → hatk.config.ts, remove DuckDB mentions, update command outputs to match current CLI. Add deployment info (SQLite/Railway) to build.md. Reference current CLI help output from hatk --help.

Step 1: Read all 5 CLI pages Step 2: Update each page Step 3: Commit

git add docs/site/cli/
git commit -m "docs: update CLI reference pages"

Task 17: Update API reference pages

Files:

• Modify: docs/site/api/index.md
• Modify: docs/site/api/records.md
• Modify: docs/site/api/feeds.md
• Modify: docs/site/api/search.md
• Modify: docs/site/api/blobs.md
• Modify: docs/site/api/preferences.md
• Modify: docs/site/api/labels.md

Read each page, update to match current XRPC signatures. Remove DuckDB references. Update authentication section to reference session cookies instead of DPoP browser tokens. Add customFetch where relevant.

Step 1: Read all 7 API pages Step 2: Update each page Step 3: Commit

git add docs/site/api/
git commit -m "docs: update API reference pages"

---

Batch 7: Final cleanup and verify

Task 18: Delete obsolete files and verify build

Files:

• Delete: docs/site/guides/deployment.md (if not already moved to cli/build.md)

Step 1: Check for any remaining dead links or old references

Run: cd docs/site && grep -r "DuckDB\|duckdb\|config\.yaml\|OAuthClient\|@hatk/oauth-client\|TanStack\|tanstack" --include="*.md" . Expected: No matches

Step 2: Build the docs site

Run: cd docs/site && npx vitepress build Expected: Build succeeds with no errors

Step 3: Commit any remaining cleanup

git add -A docs/site/
git commit -m "docs: final cleanup, remove dead references"