Phase 0: scaffold — Next.js on Node and Cloudflare, SQLite on D1 and libsql

.env.example

@@ -0,0 +1,4 @@
+# Copy to apps/web/.env.local for Node hosts. Cloudflare uses the D1 binding in wrangler.jsonc.
+
+# libsql URL of the SQLite database (Node hosts only). Relative paths resolve from apps/web.
+DATABASE_URL=file:.data/gitwork.sqlite

.github/workflows/ci.yml

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: corepack enable
+      - run: pnpm install --frozen-lockfile
+      - run: pnpm lint
+      - run: pnpm typecheck
+      # Unit tests run the DB contract on libsql and on D1 (workerd via wrangler).
+      - run: pnpm test
+      - run: pnpm --filter @gitwork/web exec playwright install --with-deps chromium
+      - run: pnpm test:e2e
+      # Builds and serves both runtimes; fails if libsql reaches the Worker bundle.
+      - run: pnpm smoke

CLAUDE.md

@@ -16,14 +16,26 @@ markdown. People without GitHub accounts get role-based access.
 
 ## Commands
 
-Not scaffolded yet. Phase 0 replaces this section with real `pnpm` commands for dev, build, test,
-lint, and typecheck.
+Run from the repo root. pnpm comes from corepack (`corepack enable`).
 
-## Codebase map (planned)
+```bash
+pnpm install
+pnpm dev            # Node + SQLite file (apps/web/.data/), runs migrations first
+pnpm preview        # OpenNext build + local D1 migrations + workerd
+pnpm lint           # ESLint: eslint-config-next in apps/web, typescript-eslint in packages/*
+pnpm typecheck
+pnpm test           # Vitest; the DB contract runs on libsql and on D1 (wrangler getPlatformProxy)
+pnpm test:e2e       # Playwright against the Node runtime
+pnpm smoke          # scripts/smoke.sh: both runtimes end to end + Worker bundle scan
+pnpm db:generate    # drizzle-kit: new migration from packages/db/src/schema.ts
+pnpm db:migrate     # apply migrations to the local SQLite file
+```
+
+## Codebase map
 
 ```
 apps/web        Next.js app, /api/v1 REST API, GitHub webhooks
-apps/mac        Native macOS app (AppKit + TextKit 2)
+apps/mac        Native macOS app (AppKit + TextKit 2) — Phase 6, not created yet
 packages/core   Permissions, visibility filter, GitHub sync, attribution, markdown round trip
 packages/db     Drizzle schema + migrations (SQLite dialect), D1 and file drivers
 docs/           INDEX.md → STATE.md → spec.md, decisions/
@@ -37,10 +49,17 @@ docs/           INDEX.md → STATE.md → spec.md, decisions/
 - The markdown editors must leave untouched lines byte-identical. The round-trip fixture suite
   guards this; never weaken it.
 - Platform services go behind the adapters in decision 004. Core code must run on plain Node.
+- The DB driver is chosen at build time (`GITWORK_TARGET`, see `apps/web/next.config.ts`). Import the
+  database only through `@/server/db`. Never import `@gitwork/db/node` or `/migrate` from app code.
+- Use `db.batch()` for atomic writes. Never `db.transaction()`: D1 does not support it.
+- pnpm enforces a one-day `minimumReleaseAge`. After any `pnpm add`, check `pnpm-workspace.yaml`
+  for a new `minimumReleaseAgeExclude` entry and remove it; pin an older version instead.
+- `next dev` rewrites `apps/web/AGENTS.md`. Commit it as is.
 
 ## Environment variables
 
-`.env.example` arrives in Phase 0. Never commit `.env*` files.
+See `.env.example`. Node hosts read `DATABASE_URL`; Cloudflare uses the `DB` binding in
+`apps/web/wrangler.jsonc`. Never commit `.env*` files.
 
 ## Start here
 

README.md

@@ -0,0 +1,42 @@
+# Gitwork
+
+Project management on top of GitHub. GitHub stays the source of truth for tasks and docs; Gitwork
+gives your clients and stakeholders a fast, permissioned view of it — list, kanban, and timeline
+views of a GitHub Projects v2 board, plus editable markdown from each repo's `docs/` folder.
+
+> **Status:** early development (Phase 0 of 7). Not usable yet. See [docs/STATE.md](docs/STATE.md).
+
+## Run it locally
+
+Requires Node 22+ and corepack (ships with Node 22–24).
+
+```bash
+corepack enable          # provides the pinned pnpm
+pnpm install
+pnpm dev                 # Node + SQLite file at apps/web/.data/ → http://localhost:3000
+pnpm preview             # Cloudflare Workers (workerd) + local D1 → http://localhost:8787
+```
+
+## Checks
+
+```bash
+pnpm lint && pnpm typecheck
+pnpm test                # unit tests; the DB suite runs on both libsql and D1
+pnpm test:e2e            # Playwright against the Node runtime
+pnpm smoke               # builds and serves both runtimes end to end
+```
+
+## Self-hosting
+
+Gitwork runs on Cloudflare Workers (D1) or any Node host (SQLite file). Deploy guides arrive in
+Phase 7. For Cloudflare today: `wrangler d1 create gitwork`, put the ID in
+`apps/web/wrangler.jsonc`, then `wrangler d1 migrations apply DB --remote` and
+`pnpm --filter @gitwork/web exec opennextjs-cloudflare deploy`.
+
+## Docs
+
+Start at [docs/INDEX.md](docs/INDEX.md). The product spec is [docs/spec.md](docs/spec.md).
+
+## License
+
+[AGPL-3.0](LICENSE).

apps/web/.gitignore

@@ -0,0 +1,53 @@
+# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+
+# dependencies
+/node_modules
+/.pnp
+.pnp.*
+.yarn/*
+!.yarn/patches
+!.yarn/plugins
+!.yarn/releases
+!.yarn/versions
+
+# testing
+/coverage
+
+# next.js
+/.next/
+/out/
+
+# production
+/build
+
+# misc
+.DS_Store
+*.pem
+
+# debug
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+.pnpm-debug.log*
+
+# env files (can opt-in for committing if needed)
+.env*
+
+# vercel
+.vercel
+
+# typescript
+*.tsbuildinfo
+next-env.d.ts
+
+# OpenNext / Cloudflare
+/.open-next/
+/.wrangler/
+.dev.vars*
+
+# Local SQLite database
+/.data/
+
+# Playwright
+/test-results/
+/playwright-report/

apps/web/AGENTS.md

@@ -0,0 +1,9 @@
+<!-- BEGIN:nextjs-agent-rules -->
+
+# This is NOT the Next.js you know
+
+This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in `node_modules/next/dist/docs/` (resolved from this file's directory; in monorepos the `next` package may not be visible from the repo root) before writing any code. Heed deprecation notices.
+
+This block is written and re-added by `next dev` — verify at `node_modules/next/dist/server/lib/generate-agent-files.js`. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.
+
+<!-- END:nextjs-agent-rules -->

apps/web/README.md

@@ -0,0 +1,3 @@
+# @gitwork/web
+
+The Gitwork web app and `/api/v1`. See the [root README](../../README.md) for commands.