@webjskit/cli 0.1.0

package/lib/saas-template.js

@@ -0,0 +1,238 @@
+/**
+ * SaaS template files for `webjs create --template saas`.
+ * Extracted to avoid nested template literal escaping issues.
+ */
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+
+/**
+ * @param {string} appDir
+ */
+export async function writeSaasFiles(appDir) {
+  // lib/prisma.ts
+  await mkdir(join(appDir, 'lib'), { recursive: true });
+  await writeFile(join(appDir, 'lib', 'prisma.ts'), [
+    "import { PrismaClient } from '@prisma/client';",
+    "",
+    "const globalForPrisma = globalThis as unknown as { prisma: PrismaClient };",
+    "export const prisma = globalForPrisma.prisma || new PrismaClient();",
+    "if (process.env.NODE_ENV !== 'production') globalForPrisma.prisma = prisma;",
+    "",
+  ].join('\n'));
+
+  // lib/password.ts
+  await writeFile(join(appDir, 'lib', 'password.ts'), [
+    "import { scrypt, randomBytes, timingSafeEqual } from 'node:crypto';",
+    "import { promisify } from 'node:util';",
+    "",
+    "const scryptAsync = promisify(scrypt);",
+    "",
+    "export async function hash(password: string): Promise<string> {",
+    "  const salt = randomBytes(16).toString('hex');",
+    "  const buf = (await scryptAsync(password, salt, 64)) as Buffer;",
+    "  return salt + ':' + buf.toString('hex');",
+    "}",
+    "",
+    "export async function compare(password: string, stored: string): Promise<boolean> {",
+    "  const [salt, key] = stored.split(':');",
+    "  const buf = (await scryptAsync(password, salt, 64)) as Buffer;",
+    "  return timingSafeEqual(buf, Buffer.from(key, 'hex'));",
+    "}",
+    "",
+  ].join('\n'));
+
+  // lib/auth.ts
+  await writeFile(join(appDir, 'lib', 'auth.ts'), [
+    "import { createAuth, Credentials } from '@webjskit/server';",
+    "import { prisma } from './prisma.ts';",
+    "import { compare } from './password.ts';",
+    "",
+    "export const { auth, signIn, signOut, handlers } = createAuth({",
+    "  providers: [",
+    "    Credentials({",
+    "      async authorize(credentials: { email: string; password: string }) {",
+    "        const user = await prisma.user.findUnique({ where: { email: credentials.email } });",
+    "        if (!user || !await compare(credentials.password, user.passwordHash)) return null;",
+    "        return { id: String(user.id), name: user.name, email: user.email };",
+    "      },",
+    "    }),",
+    "  ],",
+    "  secret: process.env.AUTH_SECRET,",
+    "});",
+    "",
+  ].join('\n'));
+
+  // prisma/schema.prisma
+  await mkdir(join(appDir, 'prisma'), { recursive: true });
+  await writeFile(join(appDir, 'prisma', 'schema.prisma'), [
+    'datasource db {',
+    '  provider = "sqlite"',
+    '  url      = env("DATABASE_URL")',
+    '}',
+    '',
+    'generator client {',
+    '  provider = "prisma-client-js"',
+    '}',
+    '',
+    'model User {',
+    '  id           Int      @id @default(autoincrement())',
+    '  email        String   @unique',
+    '  name         String?',
+    '  passwordHash String',
+    '  createdAt    DateTime @default(now())',
+    '}',
+    '',
+  ].join('\n'));
+
+  // modules/auth/actions/signup.server.ts
+  await mkdir(join(appDir, 'modules', 'auth', 'actions'), { recursive: true });
+  await mkdir(join(appDir, 'modules', 'auth', 'queries'), { recursive: true });
+
+  await writeFile(join(appDir, 'modules', 'auth', 'actions', 'signup.server.ts'), [
+    "'use server';",
+    "",
+    "import { prisma } from '../../../lib/prisma.ts';",
+    "import { hash } from '../../../lib/password.ts';",
+    "",
+    "export async function signup(input: { name: string; email: string; password: string }) {",
+    "  const exists = await prisma.user.findUnique({ where: { email: input.email } });",
+    "  if (exists) return { success: false as const, error: 'Email already registered', status: 409 };",
+    "  const user = await prisma.user.create({",
+    "    data: { name: input.name, email: input.email, passwordHash: await hash(input.password) },",
+    "  });",
+    "  return { success: true as const, data: { id: user.id, name: user.name, email: user.email } };",
+    "}",
+    "",
+  ].join('\n'));
+
+  // modules/auth/queries/current-user.server.ts
+  await writeFile(join(appDir, 'modules', 'auth', 'queries', 'current-user.server.ts'), [
+    "'use server';",
+    "",
+    "import { auth } from '../../../lib/auth.ts';",
+    "",
+    "export async function currentUser() {",
+    "  const session = await auth();",
+    "  return session?.user ?? null;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // modules/auth/types.ts
+  await writeFile(join(appDir, 'modules', 'auth', 'types.ts'), [
+    "export interface User {",
+    "  id: number;",
+    "  name: string | null;",
+    "  email: string;",
+    "}",
+    "",
+    "export type ActionResult<T> =",
+    "  | { success: true; data: T }",
+    "  | { success: false; error: string; status: number };",
+    "",
+  ].join('\n'));
+
+  // app/api/auth/[...path]/route.ts
+  await mkdir(join(appDir, 'app', 'api', 'auth', '[...path]'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'api', 'auth', '[...path]', 'route.ts'), [
+    "import { handlers } from '../../../../../lib/auth.ts';",
+    "export const GET = handlers.GET;",
+    "export const POST = handlers.POST;",
+    "",
+  ].join('\n'));
+
+  // app/login/page.ts
+  await mkdir(join(appDir, 'app', 'login'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'login', 'page.ts'), [
+    "import { html } from '@webjskit/core';",
+    "",
+    "export const metadata = { title: 'Login' };",
+    "",
+    "export default function LoginPage() {",
+    "  return html`",
+    "    <h1>Login</h1>",
+    "    <form method=\"POST\" action=\"/api/auth/callback/credentials\">",
+    "      <label>Email <input type=\"email\" name=\"email\" required></label>",
+    "      <label>Password <input type=\"password\" name=\"password\" required></label>",
+    "      <button type=\"submit\">Sign in</button>",
+    "    </form>",
+    "    <p>Don't have an account? <a href=\"/signup\">Sign up</a></p>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/signup/page.ts
+  await mkdir(join(appDir, 'app', 'signup'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'signup', 'page.ts'), [
+    "import { html } from '@webjskit/core';",
+    "",
+    "export const metadata = { title: 'Sign up' };",
+    "",
+    "export default function SignupPage() {",
+    "  return html`",
+    "    <h1>Sign up</h1>",
+    "    <form id=\"signup-form\">",
+    "      <label>Name <input type=\"text\" name=\"name\" required></label>",
+    "      <label>Email <input type=\"email\" name=\"email\" required></label>",
+    "      <label>Password <input type=\"password\" name=\"password\" required minlength=\"8\"></label>",
+    "      <button type=\"submit\">Create account</button>",
+    "    </form>",
+    "    <p>Already have an account? <a href=\"/login\">Log in</a></p>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/dashboard/middleware.ts
+  await mkdir(join(appDir, 'app', 'dashboard', 'settings'), { recursive: true });
+  await writeFile(join(appDir, 'app', 'dashboard', 'middleware.ts'), [
+    "import { auth } from '../../lib/auth.ts';",
+    "",
+    "export default async function requireAuth(req: Request, next: () => Promise<Response>) {",
+    "  const session = await auth();",
+    "  if (!session?.user) {",
+    "    return new Response(null, { status: 302, headers: { location: '/login' } });",
+    "  }",
+    "  return next();",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/dashboard/page.ts
+  await writeFile(join(appDir, 'app', 'dashboard', 'page.ts'), [
+    "import { html } from '@webjskit/core';",
+    "import { currentUser } from '../../modules/auth/queries/current-user.server.ts';",
+    "",
+    "export const metadata = { title: 'Dashboard' };",
+    "",
+    "export default async function Dashboard() {",
+    "  const user = await currentUser();",
+    "  return html`",
+    "    <h1>Dashboard</h1>",
+    "    <p>Welcome, ${`\\$\\{user?.name || user?.email\\}`}!</p>",
+    "    <a href=\"/dashboard/settings\">Settings</a>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+
+  // app/dashboard/settings/page.ts
+  await writeFile(join(appDir, 'app', 'dashboard', 'settings', 'page.ts'), [
+    "import { html } from '@webjskit/core';",
+    "import { currentUser } from '../../../modules/auth/queries/current-user.server.ts';",
+    "",
+    "export const metadata = { title: 'Settings' };",
+    "",
+    "export default async function Settings() {",
+    "  const user = await currentUser();",
+    "  return html`",
+    "    <h1>Settings</h1>",
+    "    <p>Email: ${`\\$\\{user?.email\\}`}</p>",
+    "    <p>Name: ${`\\$\\{user?.name || 'Not set'\\}`}</p>",
+    "  `;",
+    "}",
+    "",
+  ].join('\n'));
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@webjskit/cli",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "webjs CLI — dev, start, create, db",
+  "bin": {
+    "webjs": "bin/webjs.js"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "templates",
+    "README.md"
+  ],
+  "dependencies": {
+    "@webjskit/server": "0.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vivek7405/webjs.git",
+    "directory": "packages/cli"
+  },
+  "homepage": "https://github.com/vivek7405/webjs#readme",
+  "bugs": "https://github.com/vivek7405/webjs/issues",
+  "license": "MIT",
+  "keywords": [
+    "webjs",
+    "cli",
+    "dev",
+    "scaffold"
+  ]
+}

package/templates/.claude/hooks/guard-branch-context.sh

@@ -0,0 +1,39 @@
+#!/bin/bash
+#
+# guard-branch-context.sh — Claude Code PreToolUse hook
+#
+# Rules:
+#   - On main/master → ask (agent should create a feature branch first)
+#   - On any other branch → allow (feature branches are free to edit)
+#   - Bypass mode → allow everything
+
+INPUT=$(cat /dev/stdin)
+
+# Bypass mode — full autonomy
+SETTINGS="$HOME/.claude/settings.json"
+if [ -f "$SETTINGS" ]; then
+  BYPASS=$(jq -r '.skipDangerousModePermissionPrompt // false' "$SETTINGS" 2>/dev/null)
+  if [ "$BYPASS" = "true" ]; then
+    exit 0
+  fi
+fi
+
+if ! git rev-parse --is-inside-work-tree >/dev/null 2>&1; then
+  exit 0
+fi
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null || echo "")
+[ -z "$BRANCH" ] && exit 0
+
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  jq -n --arg reason "You are on '$BRANCH'. Create a feature branch first (git checkout -b feature/<name>), or approve to edit on '$BRANCH'." '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "ask",
+      permissionDecisionReason: $reason
+    }
+  }'
+  exit 0
+fi
+
+exit 0

package/templates/.claude/hooks/guard-main-merge.sh

@@ -0,0 +1,44 @@
+#!/bin/bash
+#
+# guard-main-merge.sh — Claude Code PreToolUse hook
+#
+# Rules:
+#   - git merge → ask (merging to parent branch needs approval)
+#   - git push on a feature branch → allow (free to push)
+#   - git push targeting main → ask
+#   - Bypass mode → allow everything
+
+COMMAND=$(jq -r '.tool_input.command // empty' < /dev/stdin)
+[ -z "$COMMAND" ] && exit 0
+
+# Bypass mode — full autonomy
+SETTINGS="$HOME/.claude/settings.json"
+if [ -f "$SETTINGS" ]; then
+  BYPASS=$(jq -r '.skipDangerousModePermissionPrompt // false' "$SETTINGS" 2>/dev/null)
+  if [ "$BYPASS" = "true" ]; then
+    exit 0
+  fi
+fi
+
+NORMALIZED=$(printf '%s' "$COMMAND" | tr -s '[:space:]' ' ')
+
+ask_with_reason() {
+  jq -n --arg reason "$1" '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "ask",
+      permissionDecisionReason: $reason
+    }
+  }'
+  exit 0
+}
+
+if [[ "$NORMALIZED" == *"git merge"* ]]; then
+  ask_with_reason "This command contains 'git merge'. Merging requires approval. After merging, should the source branch be deleted or kept? Approve to proceed."
+fi
+
+if [[ "$NORMALIZED" == *"git push"* ]] && [[ "$NORMALIZED" == *"main"* ]]; then
+  ask_with_reason "This looks like 'git push' targeting main. Approve to proceed."
+fi
+
+exit 0

package/templates/.claude/settings.json

@@ -0,0 +1,24 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/guard-main-merge.sh"
+          }
+        ]
+      },
+      {
+        "matcher": "Edit|Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": ".claude/hooks/guard-branch-context.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/templates/.claude.json

@@ -0,0 +1,9 @@
+{
+  "mcpServers": {
+    "playwright": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"]
+    }
+  }
+}

package/templates/.cursorrules

@@ -0,0 +1,63 @@
+# Cursor Rules — webjs app
+
+You are working on a webjs app — an AI-first, no-build, web-components-first
+framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
+project-specific conventions before writing any code.
+
+## Before starting ANY work
+
+FIRST, before writing any code:
+1. Run `git branch --show-current` to check the branch.
+   - If on main/master: STOP. Ask the user which branch to use, or create
+     one with `git checkout -b feature/<name>`.
+   - If on a feature branch: verify it matches the current task. Ask if unsure.
+2. Sync with parent: `git fetch origin && git log HEAD..origin/main --oneline`
+   - If upstream has new commits: `git rebase origin/main` before starting.
+   - Resolve any conflicts before proceeding with the task.
+
+## Autonomous mode (sandbox / no-prompt mode)
+
+If running without interactive approval, auto-decide:
+- On main? Auto-create feature/<task-slug> branch
+- Parent has new commits? Auto-rebase before starting
+- Merge? Auto-merge in autonomous mode, delete feature branches after
+- Commit message? Auto-generate (meaningful, no AI attribution)
+- Tests failing? Fix them. Convention violations? Fix them.
+Quality bar stays the same — just no blocking on questions.
+
+## Mandatory workflow (never skip)
+
+1. TESTS: Server tests in test/unit/ (node:test), browser tests in
+   test/browser/ (WTR + Playwright, real Chromium). Run `npx webjs test`
+   after every change. Never deliver code without passing tests.
+
+2. DOCS: Update AGENTS.md for API changes. Update docs/ and website/ if
+   they exist. The user should never have to ask for tests or docs.
+
+3. CONVENTIONS: Run `npx webjs check` and fix violations before committing.
+
+## Git rules
+
+- COMMIT AND PUSH OFTEN. After each logical unit of work — don't accumulate
+  changes. Always `git push` after committing. This is automatic.
+- Write meaningful commit messages: what changed and why, not "update files"
+- NEVER add "Co-Authored-By", "Generated by", "AI-assisted" or similar
+  attribution trailers to commits
+- Work on feature branches, not main
+- NEVER push directly to main — create a pull request
+- NEVER merge any branch without explicit user permission. Always ask:
+  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
+  Wait for approval AND the delete/keep preference before proceeding.
+  This applies to ALL merges, not just merges into main.
+- Run tests before every commit
+- Keep commits small and focused
+
+## Framework rules
+
+- No build step: source files are served as ES modules
+- Web components with shadow DOM: use `static styles = css` not inline styles
+- One function per server action file (*.server.ts)
+- Components must call customElements.define('tag', Class)
+- Never import @prisma/client or node:* from client components
+- Use directives (classMap, styleMap, ref, etc.) from '@webjskit/core/directives'
+- See AGENTS.md for the complete directive decision guide

package/templates/.editorconfig

@@ -0,0 +1,18 @@
+# EditorConfig — consistent formatting across editors and AI agents
+# https://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 2
+end_of_line = lf
+charset = utf-8
+trim_trailing_whitespace = true
+insert_final_newline = true
+
+[*.md]
+trim_trailing_whitespace = false
+
+[Makefile]
+indent_style = tab

package/templates/.env.example

@@ -0,0 +1,27 @@
+# webjs environment variables
+# Copy to .env and fill in your values: cp .env.example .env
+#
+# Opinionated defaults: set these and the framework auto-configures.
+
+# ── Server ──────────────────────────────────────────────────────────
+PORT=3000
+
+# ── Auth (required for authentication) ──────────────────────────────
+# Generate: node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+AUTH_SECRET=
+
+# ── OAuth providers (optional — enable the ones you need) ───────────
+# AUTH_GOOGLE_ID=
+# AUTH_GOOGLE_SECRET=
+# AUTH_GITHUB_ID=
+# AUTH_GITHUB_SECRET=
+
+# ── Redis (production scaling) ──────────────────────────────────────
+# Set this and cache, sessions, rate limiting, and pub/sub all
+# automatically use Redis. Without it, everything uses in-memory
+# defaults (great for development).
+# REDIS_URL=redis://localhost:6379
+
+# ── Database ────────────────────────────────────────────────────────
+# Used by Prisma. SQLite for dev, PostgreSQL/MySQL for production.
+DATABASE_URL=file:./dev.db

package/templates/.github/copilot-instructions.md

@@ -0,0 +1,59 @@
+# GitHub Copilot Instructions — webjs app
+
+You are working on a webjs app — an AI-first, no-build, web-components-first
+framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
+project-specific conventions.
+
+## Before starting ANY work
+
+FIRST, before writing any code:
+1. Check `git branch --show-current`.
+   - If on main/master: create a feature branch before editing.
+   - If on a feature branch: verify it matches the task at hand.
+2. Sync: `git fetch origin && git rebase origin/main` if behind.
+
+## Autonomous mode
+
+If running without interactive approval (sandbox, auto-approve, etc.):
+- On main? Auto-create feature/<task-slug> branch
+- Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
+- Auto-generate meaningful commit messages. Fix tests and violations.
+
+## Mandatory workflow
+
+Every code change must include:
+1. Commit and push — COMMIT AND PUSH after each logical unit of work.
+   Always `git push` after committing. Don't accumulate changes. Automatic.
+2. Server tests in test/unit/*.test.ts (node:test for actions, queries, utilities)
+3. Browser tests in test/browser/*.test.js (WTR + Playwright, real Chromium)
+4. Documentation updates (AGENTS.md for API, docs/ for user guides)
+5. Convention validation: `npx webjs check` must pass
+
+## Git rules
+
+- Commit after each logical unit of work
+- Meaningful commit messages: what changed and why
+- NEVER add Co-Authored-By or AI attribution trailers to commits
+- Work on feature branches, create PRs, never push directly to main
+- NEVER merge any branch without explicit user permission. Always ask:
+  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
+  Wait for approval AND the delete/keep preference. Applies to ALL merges.
+- Run `npx webjs test` before every commit
+
+## Code patterns
+
+- Tagged template: html`<div>${value}</div>` with css`...` for styles
+- Components: extend WebComponent, use static tag/styles/properties, call Class.register('tag')
+- Server actions: *.server.ts files with one exported async function each
+- Directives: import { classMap, styleMap, ref, when, ... } from '@webjskit/core/directives'
+- Context: import { createContext, ContextProvider, ContextConsumer } from '@webjskit/core/context'
+- Task: import { Task, TaskStatus } from '@webjskit/core/task'
+- Routing: file-based under app/ (page.ts, layout.ts, route.ts, middleware.ts)
+
+## What NOT to do
+
+- Don't introduce build tools or bundlers in the critical path
+- Don't import @prisma/client or node:* from client components
+- Don't use inline style="..." on components (use static styles = css`...`)
+- Don't mutate this.state directly (use this.setState())
+- Don't skip tests or documentation updates

package/templates/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## Summary
+
+<!-- What does this PR do? 1-3 bullet points. -->
+
+## Test plan
+
+- [ ] Unit tests added/updated (`npx webjs test` passes)
+- [ ] E2E tests added/updated for user-facing changes (`npx webjs test --e2e` passes)
+- [ ] `npx webjs check` passes (no convention violations)
+
+## Documentation
+
+- [ ] AGENTS.md updated (if API surface changed)
+- [ ] Docs updated (if docs/ exists and feature is documented)

package/templates/.hooks/pre-commit

@@ -0,0 +1,24 @@
+#!/bin/bash
+#
+# pre-commit hook — blocks commits on main/master.
+#
+# No AI agent, no editor, no human can commit to main directly.
+# Create a feature branch first. This is git-level enforcement.
+#
+# To bypass in emergencies: git commit --no-verify
+
+BRANCH=$(git symbolic-ref --short HEAD 2>/dev/null)
+
+if [ "$BRANCH" = "main" ] || [ "$BRANCH" = "master" ]; then
+  echo ""
+  echo "ERROR: Cannot commit directly to '$BRANCH'."
+  echo ""
+  echo "Create a feature branch first:"
+  echo "  git checkout -b feature/<name>"
+  echo ""
+  echo "To bypass (emergencies only): git commit --no-verify"
+  echo ""
+  exit 1
+fi
+
+exit 0

package/templates/.windsurfrules

@@ -0,0 +1,53 @@
+# Windsurf Rules — webjs app
+
+You are working on a webjs app — an AI-first, no-build, web-components-first
+framework. Read AGENTS.md for the full API reference and CONVENTIONS.md for
+project-specific conventions before writing any code.
+
+## Before starting ANY work
+
+FIRST, before writing any code:
+1. Check `git branch --show-current`.
+   - If on main/master: create a feature branch before editing.
+   - If on a feature branch: verify it matches the current task.
+2. Sync: `git fetch origin && git rebase origin/main` if behind.
+
+## Autonomous mode (sandbox / no-prompt)
+
+If running without interactive approval, auto-decide:
+- On main? Auto-create feature/<task-slug> branch
+- Parent behind? Auto-rebase. Merge? Auto-merge + delete feature branches.
+- Auto-generate commit messages. Fix failing tests and violations.
+Quality bar stays the same — no blocking on questions.
+
+## Mandatory workflow (never skip)
+
+Every code change must include:
+1. Server tests in test/unit/*.test.ts (node:test)
+2. Browser tests in test/browser/*.test.js (WTR + Playwright, real Chromium)
+3. Documentation updates (AGENTS.md, docs/, website/ if they exist)
+4. Convention check: `npx webjs check` must pass
+
+The user should never have to ask for tests or documentation.
+
+## Git rules
+
+- COMMIT AND PUSH OFTEN. After each logical unit of work — don't accumulate
+  changes. Always `git push` after committing. This is automatic.
+- Meaningful commit messages: what changed and why
+- NEVER add Co-Authored-By or AI attribution trailers to commits
+- Work on feature branches, never push directly to main
+- Create pull requests for review
+- NEVER merge any branch without explicit user permission. Always ask:
+  "Ready to merge <branch> into <target>? Delete or keep <branch> after?"
+  Wait for approval AND the delete/keep preference. Applies to ALL merges.
+- Run `npx webjs test` before every commit
+
+## Framework specifics
+
+- No build step: ES modules served directly
+- Web components with shadow DOM by default
+- One function per server action file (*.server.ts)
+- Use webjs directives: classMap, styleMap, ref, when, choose, guard, etc.
+- Use Context for cross-component data, Task for async data in components
+- Full API reference in AGENTS.md