@rashidee/co2 1.2.5

package/plugin/skills/specgen-node-cli-web/SKILL.md

@@ -0,0 +1,561 @@
+---
+name: specgen-node-cli-web
+model: claude-opus-4-8
+effort: high
+description: >
+  Generate a detailed specification document for building a self-hosted Node.js web
+  application distributed as a global npm CLI — installed via `npm install -g <app-name>`,
+  started via `<app-name> start`, and accessed at `http://IP:PORT`. Single-process,
+  local-first architecture: one Node 22 process serves both the REST API (Hono 4) and an
+  embedded pre-built React 19 + Vite 6 SPA styled with Tailwind CSS v4 and vendored
+  shadcn/ui. Data lives in per-user SQLite (better-sqlite3 + Drizzle ORM with shipped
+  migrations, auto-migrated on start). Authentication is hand-rolled scrypt sessions with
+  a first-run auto-generated admin, forced password change, and admin-managed users — no
+  OAuth, no JWT, no email flows. CLI parsing via commander 12, bundling via tsup 8,
+  monorepo via pnpm workspaces, Biome lint/format, Vitest + Playwright tests, mandatory
+  built-binary smoke test. Standardized input: application name (mandatory), version
+  (mandatory), module (optional).
+  Use this skill whenever the user asks to create a spec, specification, blueprint, or
+  technical design document for a self-hosted web app installed as a global CLI, a
+  "local-first web tool", an "npm-installable web dashboard", a "CLI that serves a web
+  UI", or a single-binary-style Node web application with an embedded frontend. Also
+  trigger when the user says things like "spec out a self-hosted Node web app",
+  "design an npm global CLI with a web interface", "write a spec for a local web tool
+  installed with npm -g", or any request describing a web application that end users
+  install on their own machine and open at an IP:PORT. Even if the user only mentions a
+  subset (e.g., "Hono + SQLite app started from the terminal" or "CLI-launched
+  dashboard"), this skill likely applies — ask and confirm.
+---
+
+# Self-Hosted Node.js CLI Web Application Specification Generator
+
+This skill generates a comprehensive specification document (Markdown) that serves as a
+blueprint for building a lightweight Node.js web application that is **installed via
+`npm install -g <app-name>`**, started via **`<app-name> start`**, and accessed at
+**`http://IP:PORT`**. The spec is intended to be followed by a developer or coding agent
+to produce a fully functional, publishable package.
+
+The specification does NOT generate code. It produces a detailed, opinionated technical
+document describing every layer of the application — from the pnpm workspace layout to
+the publish pipeline to the forced-password-change middleware — so that implementation
+becomes a mechanical exercise.
+
+**Architecture model (non-negotiable):** Single-process, local-first. One Node process
+serves both the REST API and the embedded pre-built web UI. All state lives on the user's
+machine. There is no hosted backend. The web app is compiled to static assets at publish
+time; end users never run a build.
+
+## Technology Stack
+
+### Core Stack (Always Included)
+
+These are the fixed versions the spec targets. Do not deviate unless the user explicitly
+requests different versions.
+
+| Layer | Technology | Version Constraint |
+|---|---|---|
+| Runtime | Node.js | 22 LTS (`engines.node: ">=22"`) |
+| Package manager (dev) | pnpm workspaces | `>=9` |
+| Language | TypeScript | `^5.6`, strict mode mandatory |
+| CLI framework | commander | `^12` |
+| Web framework | Hono (`@hono/node-server`) | `^4` |
+| Frontend | React + Vite (built SPA, embedded) | React `^19`, Vite `^6` |
+| Styling | Tailwind CSS | `^4` |
+| Components | shadcn/ui (vendored) | latest |
+| Validation | Zod | `^3` |
+| ORM | Drizzle ORM + drizzle-kit | `^0.36` / `^0.28` |
+| Database | SQLite via better-sqlite3 | `^11` |
+| Auth | Hand-rolled sessions — `node:crypto` only | n/a |
+| CLI/package build | tsup | `^8` |
+| Lint + format | Biome | `^1.9` |
+| Tests | Vitest + Playwright | `^2` / `^1.48` |
+| Terminal output | picocolors | `^1` |
+
+> **Why Hono:** framework-agnostic single-process embedding, ~14 kB core, first-class
+> TypeScript inference, and `serve-static` for shipping the built SPA from inside the
+> installed package.
+
+### Explicitly Excluded
+
+The generated spec must NOT include any of the following — where the coding agent's
+general habits conflict with this list, this list wins:
+
+- **Next.js** — cannot be packaged as a global binary
+- **Express** — Hono supersedes it
+- **Better Auth or any auth framework** — no self-serve signup exists in this model
+- **Any database server** (PostgreSQL, MySQL, MongoDB, Redis, ...)
+- **Docker** — distribution is npm; daemonization is the OS's job
+- **Email flows, self-serve registration, OAuth/social login, JWTs** — see auth rules
+- **CORS middleware** — the UI is same-origin by construction
+
+### Optional Integration Versions
+
+Include in the version table only when the corresponding integration is selected
+(see Determining Optional Components).
+
+| Component | Version | When Selected |
+|---|---|---|
+| @tanstack/react-table | 8.x | DataGrid = yes |
+| recharts | 2.x | Charts = yes |
+| react-day-picker + date-fns | 9.x / 4.x | DatePickers = yes |
+| @tiptap/react + @tiptap/starter-kit | 2.x | RichText = yes |
+| env-paths | 3.x | Optional helper for the data directory (may resolve manually instead) |
+
+New runtime dependencies beyond these require explicit human approval — the published
+tarball SHOULD stay under 5 MB excluding `better-sqlite3`.
+
+## Monorepo Structure (development)
+
+The spec targets this fixed pnpm workspace layout. Package responsibilities are strict:
+
+```
+project-root/
+├── pnpm-workspace.yaml
+├── CLAUDE.md
+├── biome.json
+├── packages/
+│   ├── core/                       # shared: Zod schemas, types, constants
+│   │   └── src/
+│   │       ├── schemas/            # one file per domain (user.ts, session.ts, ...)
+│   │       └── index.ts
+│   ├── server/                     # Hono app + Drizzle + auth
+│   │   ├── drizzle/                # generated SQL migrations (committed, shipped)
+│   │   ├── src/
+│   │   │   ├── app.ts              # Hono app factory (routes + middleware)
+│   │   │   ├── db/
+│   │   │   │   ├── schema.ts
+│   │   │   │   ├── index.ts        # connection factory (takes data dir path)
+│   │   │   │   └── bootstrap.ts    # first-run: migrate + create default admin
+│   │   │   ├── auth/               # sessions, password hashing, middleware
+│   │   │   ├── features/<name>/    # routes.ts, service.ts, schema.ts, __tests__/
+│   │   │   └── lib/                # logger, env/config
+│   │   └── vitest.config.ts
+│   ├── web/                        # React SPA (Vite)
+│   │   ├── src/
+│   │   │   ├── routes/             # login, force-change-password, users, settings, <modules>
+│   │   │   ├── components/ui/      # shadcn vendored
+│   │   │   └── lib/api.ts          # typed fetch client (hono/client RPC)
+│   │   └── vite.config.ts
+│   └── cli/                        # THE published package
+│       ├── package.json            # name: <app-name>, bin, files: ["dist","static","drizzle"]
+│       ├── src/
+│       │   ├── index.ts            # #!/usr/bin/env node — commander program
+│       │   └── commands/           # start.ts, status.ts, reset-admin.ts, <extra commands>
+│       └── tsup.config.ts
+└── e2e/                            # Playwright against a started instance
+```
+
+**Publish pipeline (the critical mechanic):** `packages/cli` is the only published
+artifact. Its build step (1) tsup-bundles the CLI + server into `dist/` with
+`better-sqlite3` marked external — it is a native module and must remain a real
+dependency, (2) runs `vite build` in `packages/web` and copies the output to
+`cli/static/`, (3) copies `server/drizzle/` migrations into the package. The published
+package is therefore self-contained: bundle + static UI + migrations.
+
+Structural rules: feature-folder colocation, no barrel files, <300 lines/file, Zod at
+every boundary, `any` forbidden, types via `z.infer<>`.
+
+## When the Skill Triggers
+
+Generate the spec when the user provides an **application name** and **version** that
+corresponds to one of the custom applications defined in `CLAUDE.md`. The skill reads all
+required inputs from the project's context files — no interactive Q&A is needed for the
+core inputs.
+
+The user invokes this skill by specifying the target application and version, for example:
+- `/specgen-node-cli-web my_tool v1.0.0`
+- `/specgen-node-cli-web my_tool v1.0.0 module:Inventory`
+- `/specgen-node-cli-web "My Tool" v1.0.0`
+
+The skill then locates the matching context folder and reads all input files automatically.
+
+## Version Gate
+
+Before starting any work, resolve the application folder first (see Input Resolution below), then check `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
+
+1. If `<app_folder>/CHANGELOG.md` does not exist, skip this check (first-ever execution for this application).
+2. If `<app_folder>/CHANGELOG.md` exists, scan all `## vX.Y.Z` headings and determine the **highest version** using semantic versioning comparison.
+3. Compare the requested version against the highest version:
+   - If requested version **>=** highest version: proceed normally.
+   - If requested version **<** highest version: **STOP immediately**. Print: `"Version {requested} is lower than the current application version {highest} recorded in <app_folder>/CHANGELOG.md. Execution rejected."` Do NOT proceed with any work.
+
+## Input Resolution
+
+This skill uses standardized input resolution. Provide:
+
+| Argument | Required | Example | Description |
+|----------|----------|---------|-------------|
+| `<application>` | Yes | `my_tool` | Application name to locate the context folder |
+| `<version>` | Yes | `v1.0.0` | Version to scope processing |
+| `module:<name>` | No | `module:Inventory` | Limit generation to a single module |
+
+### Application Folder Resolution
+
+The application name is matched against root-level application folders:
+1. Strip any leading `<number>_` prefix from folder names (e.g., `1_my_tool` → `my_tool`)
+2. Match case-insensitively against the provided application name
+3. Accept snake_case, kebab-case, or title-case input (all match the same folder)
+4. If no match found, list available applications and stop
+
+### Auto-Resolved Paths
+
+| File | Resolved Path |
+|------|---------------|
+| PRD.md | `<app_folder>/context/PRD.md` |
+| Module Models | `<app_folder>/context/model/` |
+| HTML Mockups | `<app_folder>/context/mockup/` |
+| Output (specification) | `<app_folder>/context/specification/` |
+
+### Version Filtering
+
+When a version is provided, only include user stories, NFRs, and constraints from versions
+<= the provided version. For example, if `v1.0.4` is specified:
+- Include items tagged `[v1.0.0]` through `[v1.0.4]`
+- Exclude items tagged `[v1.0.5]` or later
+- Version comparison uses semantic versioning order
+
+### Module Filtering
+
+When `module:<name>` is provided:
+- Only generate the `SPEC.md` for that specific module
+- Other existing module spec files remain untouched
+- `SPECIFICATION.md` (root) gets a partial update — only that module's entry in the TOC
+  is added or updated; all other TOC entries are preserved as-is
+- The mandatory `user-management/SPEC.md` is regenerated only when the filtered module
+  IS the user management module
+
+## Gathering Input
+
+The specification is driven by **six input sources** read from the project's context
+files. The skill does NOT ask the user for auth, ports, or optional component choices —
+it **determines** these automatically from the context.
+
+### Input 1: Application Name (from CLAUDE.md)
+
+From CLAUDE.md (already loaded in context), locate the target application under the
+**Custom Applications** section. Extract:
+
+- **Application name**: The section heading (e.g., "Home Inventory", "Team Board")
+- **Application description**: The description paragraph below the heading
+- **Dependencies**: The "Depends on" list — a self-hosted local-first app normally has
+  none; any external service dependency becomes an optional HTTP integration in the spec
+
+The application name is used to derive:
+- **Package name / binary name**: kebab-case (e.g., `home-inventory`) — the npm package
+  name, the `bin` entry, AND the per-platform data directory name
+- **App title**: Title-case, used in the SPA `<title>` and topbar
+- **Env var prefix**: SCREAMING_SNAKE of the binary name is NOT used — the CLI env vars
+  are always `APP_PORT`, `APP_HOST`, `APP_DATA_DIR`
+
+### Input 2: User Stories (from PRD.md)
+
+Read `<app_folder>/context/PRD.md`. This file contains all user stories organized by
+module. Extract:
+
+- **System modules**: Modules under `# System Module` (e.g., Authentication, User
+  Management). These map onto the mandatory auth/user-management blueprint — merge their
+  IDs into its traceability rather than generating a competing design.
+- **Business modules**: Modules under `# Business Module`. Each becomes a server feature
+  folder (`server/src/features/<module>/`), a set of SPA routes, and a `<module>/SPEC.md`.
+- **CLI-facing stories**: Stories describing terminal interactions (e.g., "start the app
+  from my terminal", "reset the admin password offline") map to CLI commands.
+
+**Important:** Items with strikethrough (`~~text~~`) are deprecated — do NOT include them
+as active requirements. List them in the "Removed / Replaced" subsection of the
+traceability table. Track the `[v1.0.x]` version tag for each item and carry it through
+to the generated specification's traceability section.
+
+### Input 3: Non-Functional Requirements (from PRD.md)
+
+Each module's `### Non Functional Requirement` section informs:
+
+- Pagination, filtering, and list-size decisions (Hono query params + SPA table setup)
+- Validation rules (character limits, formats) → Zod schemas in `core/`
+- Performance constraints (response budgets, LAN access expectations)
+- Security posture beyond the mandatory auth baseline
+
+### Input 4: Constraints (from PRD.md)
+
+Each module's `### Constraint` section defines hard boundaries:
+
+- Status enum values → Drizzle `text({ enum })` columns + shared Zod enums
+- Business rules → service-layer invariants with tests
+- Access control (e.g., "only ADMIN can ...") → route guard configuration
+
+### Input 5: Module Model (from model/ folder)
+
+Read `<app_folder>/context/model/MODEL.md` first as the index, then the individual module
+model files (e.g., `model/inventory/model.md` + `schemas.json`). The module model maps to:
+
+- Drizzle table definitions in `server/src/db/schema.ts` (field-for-field, not placeholder)
+- Zod schemas in `core/src/schemas/<domain>.ts`
+- Service method signatures and route request/response DTOs
+- Generated SQL migrations shipped in `server/drizzle/`
+
+This skill expects **relational models** (`modelgen-relational`) since the datastore is
+SQLite. If only a NoSQL model exists, flatten document structures into relational tables
+and note the mapping decisions in the spec.
+
+### Input 6: HTML Mockup Screens (from mockup/ folder)
+
+Read `<app_folder>/context/mockup/MOCKUP.html` first as the index, then the HTML files
+organized by role in subfolders. The mockups map to:
+
+- React page components in `web/src/routes/` (one per screen)
+- shadcn/ui component selections (Table vs Cards, Dialog vs Sheet, etc.)
+- Navigation structure and per-role menu items
+- Tailwind v4 design tokens (colors, font, radius extracted from mockup CSS)
+
+**Role folders inform access control, NOT URL paths.** `mockup/admin/users.html` means
+the route requires the `admin` role — the URL is `/users`, never `/admin/users`. If no
+mockups exist for the mandatory auth screens (login, force-change-password, users,
+settings), spec them from the auth blueprint anyway — they are not optional.
+
+## PRD.md Extended Sections
+
+Before determining optional components, check PRD.md for the following extended sections:
+
+### Architecture Principle Extraction
+
+If PRD.md contains an `# Architecture Principle` section, extract patterns that affect
+decisions — but remember this skill's architecture model is fixed. Principles like
+"container based deployment" or "microservices" CONFLICT with the single-process
+local-first model; surface the conflict to the user instead of silently complying.
+Compatible principles (e.g., "offline-first", "no external services") are cited in the
+spec's overview.
+
+### Design System Extraction
+
+If PRD.md contains a `# Design System` section with a file reference, resolve and read
+it, then map design tokens into the Tailwind v4 CSS-first theme (`@theme` block in the
+SPA's global CSS) and shadcn/ui CSS variables. If absent, derive tokens from the mockup
+CSS (existing behavior).
+
+### High Level Process Flow Extraction
+
+If PRD.md contains a `# High Level Process Flow` section, flows inform service-method
+sequencing, status enums surfaced in list filters, and the Playwright E2E scenario order.
+If absent, derive flow from user stories only.
+
+## Determining Optional Components
+
+The mandatory baseline (CLI contract, data directory, bootstrap, auth and user lifecycle)
+is never optional. Beyond it, the skill determines optional components by analyzing
+PRD.md NFRs, constraints, and mockups:
+
+| Content Pattern | Component Selection |
+|---|---|
+| NFRs mention "sortable columns", "bulk select", "export CSV", grids | DataGrid = yes (TanStack Table, shadcn Data Table) |
+| NFRs mention "chart", "graph", "statistics", "dashboard metrics" | Charts = yes (Recharts) |
+| NFRs mention "date picker", "date range", "calendar" | DatePickers = yes (react-day-picker) |
+| User stories mention "rich text", "WYSIWYG", "formatted content" | RichText = yes (Tiptap) |
+| User stories mention uploading files/images | FileStorage = yes (files under `<data-dir>/files/`, streamed by a Hono route — never inside the install dir) |
+| NFRs mention periodic/background work ("every hour", "auto-prune", "scheduled") | InProcessJobs = yes (`setInterval` in the server process; no external queue, no daemon) |
+| CLAUDE.md dependencies or NFRs reference an external REST API | HttpIntegration = yes (native `fetch`, config-driven base URL in `config.json`) |
+| PRD.md defines CLI commands beyond start/status/reset-admin | ExtraCommands = yes (list them) |
+
+### Summary of Determination
+
+After analyzing all inputs, produce a determination summary before generating the spec.
+Present it to the user for confirmation:
+
+```
+Mandatory baseline: CLI (start/status/reset-admin) + data dir + bootstrap + scrypt session auth
+Optional Component Determination:
+- DataGrid:        yes (from PRD.md → NFR mentions sortable item list with bulk delete)
+- Charts:          no
+- DatePickers:     yes (from PRD.md → purchase date field)
+- RichText:        no
+- FileStorage:     yes (from PRD.md → item photo upload)
+- InProcessJobs:   no
+- HttpIntegration: no
+- ExtraCommands:   yes (`export` — from PRD.md → offline backup story)
+```
+
+If the user disagrees with any determination, allow them to override before proceeding.
+
+## Generating the Specification
+
+Once inputs are gathered and optional components are determined, generate the
+specification as a **multi-file output split by module**. Read the spec template at
+`references/spec-template.md` for the exact structure and content of each section — it is
+the authoritative guide. Read the pattern references when generating the corresponding
+sections:
+
+| Reference | Read when generating |
+|---|---|
+| `references/spec-template.md` | Always — the authoritative section-by-section template |
+| `references/cli-packaging-patterns.md` | CLI contract, tsup config, publish pipeline, npm distribution sections |
+| `references/server-patterns.md` | Hono composition, data directory, config, DB factory, logger sections |
+| `references/auth-patterns.md` | Bootstrap, sessions, password hashing, user lifecycle sections |
+| `references/testing-patterns.md` | Testing strategy, smoke test, and Playwright E2E sections |
+
+The specification is split into two categories:
+
+1. **Root `SPECIFICATION.md`** — TOC, monorepo + workspace config, CLI contract, data
+   directory, database layer, server composition, first-run bootstrap, authentication,
+   SPA shell, testing strategy, and packaging/distribution.
+2. **Per-module `<module-name>/SPEC.md`** — Each module gets its own folder with a
+   self-contained blueprint spanning server feature (routes + service + schema) and SPA
+   feature (pages + components + typed client usage).
+
+Additionally, generate the **mandatory `user-management/SPEC.md`** covering the auth and
+user lifecycle screens (login, forced change, users list, settings) even when PRD.md has
+no explicit module for it. When PRD.md DOES define an auth/user module, merge its story
+IDs into this file's traceability — the security invariants in `references/auth-patterns.md`
+still win over any conflicting PRD phrasing, and conflicts must be flagged to the user.
+
+**Important:** The generated spec must use **real application data** from the context
+files, not generic placeholders:
+
+- **Modules** use actual module names from PRD.md and MODEL.md
+- **Drizzle tables and TypeScript types** match the model files field-for-field
+- **Routes and services** map to actual user stories
+- **Pages** map to actual mockup screens; URL paths are module-based, not role-prefixed
+- **Zod schemas** enforce the actual PRD constraints
+- **Version tags** on every user story ID, NFR ID, constraint ID, and mockup screen in
+  traceability tables (e.g., `USHI00003 [v1.0.2]`); **ALL traceability sub-tables MUST
+  include the `| Version |` column**
+- **Removed / Replaced** subsection lists deprecated items with the removing version,
+  replacement ID (if any), and reason
+
+### Output Structure
+
+```
+<app_folder>/context/specification/
+├── SPECIFICATION.md              ← Root: TOC + shared infrastructure (CLI, data dir, DB, server, auth, packaging)
+├── user-management/
+│   └── SPEC.md                   ← MANDATORY: auth + user lifecycle blueprint
+├── <module-1>/
+│   └── SPEC.md                   ← Business module blueprint (server feature + SPA feature)
+├── <module-2>/
+│   └── SPEC.md
+└── ...                           ← One folder per business module from PRD.md
+```
+
+**Sample code is mandatory.** Every component described in any spec file must include a
+complete, self-explanatory code sample. The code must be continuous (no `// ...` gaps)
+and usable as a direct reference by a coding agent.
+
+## Changelog Append
+
+After all specification files are successfully generated, append an entry to `CHANGELOG.md` in the application folder (`<app_folder>/CHANGELOG.md`):
+
+1. Read `<app_folder>/CHANGELOG.md`. If it does not exist, create it with:
+   ```markdown
+   # Changelog
+
+   - This file tracks all skill executions by version for this application.
+   - The highest version recorded here is the current application version.
+   - Skills MUST NOT execute for a version lower than the highest version in this file.
+
+   ---
+   ```
+2. Search for a `## {version}` heading matching the current version.
+3. If the section **exists**: append a new row to its table.
+4. If the section **does not exist**: insert a new section after the `---` below the context header and before any existing `## vX.Y.Z` section (newest-first ordering), with a new table header and the first row.
+5. Row format: `| {YYYY-MM-DD} | {application_name} | specgen-node-cli-web | {module or "All"} | Generated self-hosted Node.js CLI web application technical specification |`
+6. **Never modify or delete existing rows.**
+
+## Constraints (Non-Negotiable)
+
+These constraints apply to every code sample in the generated spec. Where the coding
+agent's habits conflict with them, these constraints win.
+
+### Structure & Types
+
+**TypeScript strict mode everywhere.** `"strict": true` in every package. No `any` —
+use `unknown` with Zod narrowing. Types derive from schemas via `z.infer<>`.
+
+**Zod at every boundary.** CLI flags, `config.json`, every API request body/query, and
+every external input are parsed with a Zod schema before use. Shared schemas live in
+`packages/core` and are consumed by both server routes and SPA forms.
+
+**Feature-folder colocation, no barrel files, <300 lines per file.** Each server feature
+is `features/<name>/{routes.ts, service.ts, schema.ts, __tests__/}`. No `index.ts`
+re-export barrels.
+
+**Thin CLI handlers.** Command handlers parse flags with commander, validate with Zod,
+and delegate to `server`/`core` functions. No business logic in `packages/cli`.
+
+### Process & Distribution
+
+**Foreground process only.** `start` runs in the foreground; Ctrl-C stops it with a
+graceful shutdown that closes the SQLite handle. NEVER implement forking/daemon logic —
+daemonization belongs to `systemd`/`pm2`.
+
+**Fail loud on a taken port.** Print a clear message naming the flag to change it
+(`--port`); never auto-increment silently.
+
+**Option resolution order** for every `start` option: CLI flag → environment variable
+(`APP_PORT`, `APP_HOST`, `APP_DATA_DIR`) → `config.json` → default (port `3000`, host
+`0.0.0.0` for LAN access).
+
+**The install directory is read-only at runtime.** Global npm installs may not be
+writable — never write anything next to the installed code. All state (DB, config, files,
+logs) lives in the per-platform data directory, created `0700` on first run.
+
+**`better-sqlite3` stays external.** It is a native module: a real runtime `dependency`
+of the published package, never bundled by tsup, never a devDependency. Everything else
+is bundled into `dist/` — end users must not need pnpm or the workspace.
+
+**Migrations auto-run on every `start`** before the server binds, against the shipped
+`drizzle/` folder. Idempotent; no user-facing migrate command.
+
+### Server & Security
+
+**One Hono app serves everything.** `/api/*` routes first, then `serveStatic` for the SPA
+build, with an SPA fallback rewriting unknown non-API GETs to `index.html`. Middleware
+order: request-id → logger → session resolution → route guards → routes.
+
+**No CORS, security headers on.** `hono/secure-headers` on all responses. The UI is
+same-origin by construction — never add permissive CORS.
+
+**Typed API contract via `hono/client`.** Export the route tree's type from `server`;
+`web` consumes a fully typed RPC client. No OpenAPI codegen step.
+
+**Auth is hand-rolled scrypt sessions — nothing else.** scrypt via `node:crypto`
+(N=2^15, r=8, p=1, 32-byte key, 16-byte salt, `timingSafeEqual` verify). Opaque session
+tokens: raw token client-side in an `httpOnly` `SameSite=Lax` cookie, only the SHA-256
+hash server-side; sliding expiry, 30-day absolute cap. NEVER implement email flows,
+self-serve registration, OAuth/social login, JWTs, or password recovery other than
+`reset-admin` (CLI) and admin-reset (UI).
+
+**Forced password change is server-enforced.** While `must_change_password` is true,
+every API route except login, change-password, and logout returns
+`403 PASSWORD_CHANGE_REQUIRED` from middleware. The SPA redirect is convenience, not the
+control.
+
+**Server-side invariants with tests:** cannot delete the last remaining admin; changing a
+password revokes all other sessions; login is rate-limited in-memory (10 attempts / 15
+min per username+IP); the plaintext bootstrap password is printed once and never written
+to any file or log.
+
+**No module-level DB singletons.** The connection factory takes the resolved data-dir
+path as an argument (so tests inject `:memory:`) and always sets the mandatory pragmas:
+WAL mode, `foreign_keys = ON`, `busy_timeout = 5000`.
+
+### Verification
+
+**`pnpm verify` must pass before any task is complete** — `check` (tsc + Biome), `test`
+(Vitest with real migrations on `:memory:`, never a mocked DB), `build`, and the
+**mandatory smoke stage** that executes the *built* CLI: random port, temp `--data-dir`,
+HTTP 200 on `/` and the health endpoint, login with the printed admin credentials, clean
+shutdown. Shebang, bundling, native-module, and asset-path failures only surface
+post-build — testing source alone is insufficient.
+
+## Principles Embedded in the Spec
+
+- Local-first: the user's machine is the source of truth; filesystem access is the root
+  of trust (hence `reset-admin` instead of email recovery)
+- One printed status block on successful start: local URL, network URL (detected LAN IP),
+  data directory, version — structured logs after that
+- The `package.json` version field equals the version argument from skill invocation;
+  `--version` prints it and the SPA footer renders it
+- Password policy is NIST 800-63B posture: minimum 10 characters, reject
+  username-as-password, no composition-class rules
+- `Secure` cookie flag only when the request arrived over HTTPS — local HTTP on a LAN
+  must still work; TLS termination is a reverse-proxy concern (documented, not built)
+- Definition of Done per task: structure per the monorepo layout, thin CLI handlers, Zod
+  boundaries, shipped migrations, auth invariants tested, `pnpm verify` green including
+  the built-binary smoke test, `CLAUDE.md` and `--help` updated when commands change