V2 rewrite

.claude/hooks/check-docker.sh

@@ -0,0 +1,12 @@
+#!/bin/bash
+# Pre-test check: Docker daemon + Postgres container must be running
+
+if ! docker ps > /dev/null 2>&1; then
+  echo "Docker is not running. Start Docker Desktop on Windows, wait ~15 seconds for WSL2 integration, then retry." >&2
+  exit 2
+fi
+
+if ! docker ps --filter "name=wheretf-postgres" --filter "status=running" | grep -q postgres; then
+  echo "Postgres container is not running. Start it with: docker compose -f docker-compose.dev.yml up -d" >&2
+  exit 2
+fi

.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE '(npm test|npx vitest|vitest run)' && /home/nick/projects/nickydoes/wheretf/.claude/hooks/check-docker.sh || true"
+          }
+        ]
+      }
+    ]
+  },
+  "permissions": {
+    "allow": [
+      "Bash(DATABASE_URL=\"postgresql://wheretf:wheretf@localhost:5432/wheretf_test\" npx vitest run)",
+      "WebSearch"
+    ],
+    "additionalDirectories": [
+      "/home/nick/projects/nickydoes/wheretf/web/app/api/modules"
+    ]
+  }
+}

.claude/skills/committing.md

@@ -0,0 +1,4 @@
+# Commit Guidelines
+
+- Do not include Co-Authored-By lines or any AI/Claude attribution in commit messages.
+- Keep commit messages concise and focused on the "why" of the change.

.github/workflows/ci.yml

@@ -0,0 +1,152 @@
+name: CI
+
+on:
+  push:
+    branches: [main, v2-rewrite]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+
+permissions:
+  contents: read
+  packages: write # to push to GHCR on the publish job
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+env:
+  REGISTRY: ghcr.io
+  APP_IMAGE: ghcr.io/${{ github.repository }}/web
+  MIGRATE_IMAGE: ghcr.io/${{ github.repository }}/migrate
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci --prefer-offline --no-audit --no-fund
+        working-directory: web
+      - run: npm run lint
+        working-directory: web
+      - run: npx tsc --noEmit
+        working-directory: web
+
+  test-backend:
+    runs-on: ubuntu-latest
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_DB: wheretf_test
+          POSTGRES_USER: wheretf
+          POSTGRES_PASSWORD: wheretf
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U wheretf"
+          --health-interval 5s
+          --health-timeout 3s
+          --health-retries 10
+    env:
+      DATABASE_URL: postgresql://wheretf:wheretf@localhost:5432/wheretf_test
+      DATABASE_URL_TEST: postgresql://wheretf:wheretf@localhost:5432/wheretf_test
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci --prefer-offline --no-audit --no-fund
+        working-directory: web
+      - run: npm run db:migrate
+        working-directory: web
+      - run: npm run test:backend
+        working-directory: web
+
+  test-frontend:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: "npm"
+          cache-dependency-path: web/package-lock.json
+      - run: npm ci --prefer-offline --no-audit --no-fund
+        working-directory: web
+      - run: npm run test:frontend
+        working-directory: web
+
+  build-and-publish:
+    runs-on: ubuntu-latest
+    needs: [lint, test-backend, test-frontend]
+    # Only publish images on main / tags — PRs run lint+tests only.
+    if: github.event_name == 'push' && (github.ref == 'refs/heads/main' || startsWith(github.ref, 'refs/tags/v'))
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up QEMU (for arm64 emulation)
+        uses: docker/setup-qemu-action@v3
+
+      - name: Set up Buildx
+        uses: docker/setup-buildx-action@v3
+
+      - name: Log in to GHCR
+        uses: docker/login-action@v3
+        with:
+          registry: ${{ env.REGISTRY }}
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Tag metadata (app)
+        id: meta-app
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.APP_IMAGE }}
+          tags: |
+            type=sha,prefix=sha-
+            type=ref,event=branch
+            type=ref,event=tag
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build + push runner image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./web
+          target: runner
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta-app.outputs.tags }}
+          labels: ${{ steps.meta-app.outputs.labels }}
+          cache-from: type=gha,scope=runner
+          cache-to: type=gha,scope=runner,mode=max
+
+      - name: Tag metadata (migrate)
+        id: meta-migrate
+        uses: docker/metadata-action@v5
+        with:
+          images: ${{ env.MIGRATE_IMAGE }}
+          tags: |
+            type=sha,prefix=sha-
+            type=ref,event=branch
+            type=ref,event=tag
+            type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}
+
+      - name: Build + push migrator image
+        uses: docker/build-push-action@v6
+        with:
+          context: ./web
+          target: migrator
+          platforms: linux/amd64,linux/arm64
+          push: true
+          tags: ${{ steps.meta-migrate.outputs.tags }}
+          labels: ${{ steps.meta-migrate.outputs.labels }}
+          cache-from: type=gha,scope=migrator
+          cache-to: type=gha,scope=migrator,mode=max

.gitignore

@@ -0,0 +1,27 @@
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+*.swp
+*.swo
+*~
+
+# Claude Code local state
+.claude/settings.local.json
+.claude/project-context.json
+
+# Environment
+.env
+.env.*
+!.env.*.example
+
+# Data / runtime
+data/
+
+# Node (root-level scripts)
+node_modules/
+
+# Docker volumes
+docker-data/

CLAUDE.md

@@ -0,0 +1,83 @@
+# WhereTF — Development Directives
+
+## Claude project notes
+- Keep this file under 150 lines.
+- Prefer higher level CLAUDE.md files for generalized instructions
+
+## Folder structure
+- Specifications belong in `specification/`
+
+## Stack
+
+Next.js (App Router) + React, PostgreSQL, Tailwind v4. Storage grid rendered as SVG within React components; DOM overlays for tooltips and detail panels. Single-user for initial implementation. Designed for future multi-user, multi-tenant (users belong to orgs). AI integration (OpenAI) deferred — build core storage and item management first.
+
+## Dev Commands
+
+From `web/`:
+- `npm run dev` — next dev (requires local PostgreSQL)
+- `npm test` — Vitest unit and integration tests
+- `npm run test:watch` — Vitest in watch mode
+- `npm run db:migrate` — run Drizzle migrations
+- `npm run db:generate` — generate migration from schema changes
+- `npm run db:studio` — Drizzle Studio (database browser)
+
+## Testing
+
+TDD for data model and repository layers. Tests run against a real PostgreSQL database with per-test transaction rollback — no mocks, no in-memory fakes.
+
+- **Unit tests** — repository functions, domain logic, path utilities
+- **Integration tests** — API routes, multi-step operations (insert placement, assignment resolution)
+- **Component tests** — React Testing Library + Vitest, test behavior not rendering
+
+## Architecture
+
+Three-layer data access — no exceptions:
+
+- **Schema** (`web/db/schema/`) — Drizzle schema definitions, no business logic
+- **Repository** (`web/repositories/`) — All business logic, validation, org-scoped queries
+- **API route** (`web/app/api/`) — Thin: parse request, check auth, call repository, format response
+
+## Repository Conventions
+
+- All methods take a single destructured object: `create({ userId, name, location })`
+- All user-data queries must scope by `userId` — no unscoped queries. Future: `orgId` scoping when multi-tenant is implemented; items will be global (shared across orgs).
+- Repositories throw errors; API routes catch and return `{ error: "msg" }`
+
+## API Response Shape
+
+```
+Success: { items: [...] } or { item: {...} }
+Error:   { error: "Error message" }
+```
+
+## Naming
+
+| Type | Convention | Example |
+|------|-----------|---------|
+| Components, models | PascalCase | `ChatContainer.tsx`, `Module.ts` |
+| Utilities, functions, variables | camelCase | `agentRunner.ts`, `userId` |
+| Constants | UPPER_SNAKE | `MAX_TOKENS` |
+| Database fields | camelCase | `createdAt` |
+| Module names (domain) | Short, not descriptive | `MUSE`, `FLUX`, `NEON` |
+| Parameter keys (domain) | lowercase_underscore | `thread_size`, `voltage_rating` |
+
+## Styling
+
+Tailwind v4 with custom `accent` color (#ff6600 orange). Dark mode supported. Grid labeling: rows=alpha (A,B,C), cols=numeric (1,2,3), origin=top-left.
+
+## Adding Things
+
+**New model:** Drizzle schema in `web/db/schema/` → generate migration → repository in `web/repositories/` → API routes in `web/app/api/` → tests first
+
+## Specification
+
+- [specification/project-intent.md](specification/project-intent.md) — what WhereTF is, interaction model, domain concepts
+- [specification/storage-model.md](specification/storage-model.md) — storage data model (modules, templates, inserts, overrides, paths)
+- [specification/deployment.md](specification/deployment.md) — CI/CD pipeline and deployment
+- [specification/storage-navigator-design.md](specification/storage-navigator-design.md) — grid visualization UI/UX spec
+- [specification/storage-definition-design.md](specification/storage-definition-design.md) — module/template/insert definition UI/UX spec
+- [specification/item-taxonomy.md](specification/item-taxonomy.md) — item classification (categories, parameters, aspects)
+- [specification/item-maintenance.md](specification/item-maintenance.md) — item lifecycle use cases
+- [specification/item-management-design.md](specification/item-management-design.md) — item management UI/UX spec
+- [specification/ui-paradigms.md](specification/ui-paradigms.md) — cross-cutting UI/UX rules
+- [specification/ai-agent-architecture.md](specification/ai-agent-architecture.md) — AI agent patterns (deferred, reference only)

CODE_OF_CONDUCT.md

@@ -0,0 +1,28 @@
+# Code of Conduct
+
+## In short
+
+Be decent. Don't be a jerk.
+
+## Longer version
+
+- Assume good faith. People miscommunicate, especially over text.
+- Disagreement about technical choices is fine and expected. Framing
+  disagreement as attacks on a person is not.
+- No harassment, no slurs, no threats, no doxxing. Obvious.
+- This project has one maintainer. Decisions that can't be resolved
+  by discussion fall to them. If you don't like a decision, fork —
+  that's your right under AGPL.
+
+## Scope
+
+Applies to interactions in this repo (issues, PRs, discussions) and
+any WhereTF-branded channels elsewhere.
+
+## Enforcement
+
+Report violations by emailing the maintainer (address in the commit
+log). Warnings escalate to ban from project spaces. No appeals
+process — this is a solo-run project, not a committee.
+
+— The Maintainer