chadtmiller.com/hatk
AT Protocol app framework
1
0
# 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).
```ts
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**
```bash
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**
```markdown
---
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
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**
```bash
git add -A docs/site/
git commit -m "docs: final cleanup, remove dead references"
```