@codyswann/lisa 2.166.4 → 2.167.0

package/plugins/lisa-nestjs-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "NestJS-specific skills (GraphQL, TypeORM) and hooks (migration write-protection)",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-openclaw-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-openclaw",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Connect staff roles to Telegram or Slack via OpenClaw — facilitator/specialist hub-and-spoke routing and repo-coding topics, for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-phaser-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-phaser",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Phaser 4 game-development rules for TypeScript projects",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-rails-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Ruby on Rails-specific hooks — RuboCop linting/formatting and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "TypeScript-specific hooks for formatting, linting, and ast-grep scanning on edit.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-typescript-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-typescript",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, ast-grep scanning, and error-suppression blocking on edit",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "Distributable LLM Wiki kernel — ingest, query, lint, and maintain a git-native markdown knowledge base across Claude and Codex.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-wiki-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-wiki",
-  "version": "2.166.4",
+  "version": "2.167.0",
   "description": "LLM Wiki — a distributable, git-native markdown knowledge base for Claude Code and Codex",
   "author": {
     "name": "Cody Swann"

package/plugins/src/harper-fabric/skills/harper-schema-graphql/SKILL.md

@@ -16,28 +16,39 @@ the REST/GraphQL surface exposes.
 ## Defining tables
 
 A table is a GraphQL type. Harper-specific directives mark a type as a persisted
-table and control exposure, primary keys, and indexes. The exact directive set
-depends on the Harper version in use — confirm against the live `schema.graphql`
-in this project and the Harper schema docs before adding new syntax. Common shape:
+table and control exposure, primary keys, indexes, audit timestamps, sealed
+records, and relationships. Lisa's Harper Fabric template pins `harperdb` to the
+Harper 4 line (`^4.7.29`), so use this v4 directive reference for template
+projects:
 
 ```graphql
-type Dog @table {
-  id: ID @primaryKey
+type Dog @table @export(name: "dogs") {
+  id: Long @primaryKey
   name: String @indexed
   breed: String
-  owner: String
+  ownerId: Long @indexed
+  owner: Owner @relationship(from: ownerId)
+  createdAt: Long @createdTime
+  updatedAt: Long @updatedTime
 }
 ```
 
-- `@table` marks the type as a persisted Harper table.
-- `@primaryKey` marks the primary key field.
-- `@indexed` adds a secondary index for query/`search`.
-- Exposure of a type as an API endpoint is controlled by the schema/`rest`
-  configuration — see [[harper-config-yaml]].
-
-> Treat the directive names above as a starting point, not gospel — verify against
-> the project's existing schema and current Harper docs, since directive syntax has
-> evolved across versions.
+| Directive | Scope | Syntax | Use |
+| --- | --- | --- | --- |
+| `@table` | Type | `type Product @table { ... }` | Creates a persisted table named after the type. Optional arguments: `table: "products"` to override the table name, `database: "commerce"` to choose a database, `expiration: 3600` for TTL-style records, and `audit: true` to force audit logging. |
+| `@export` | Type | `type Product @table @export(name: "products") { ... }` | Exposes the table as a resource endpoint for REST/MQTT and related surfaces. `name` is optional; without it the type name is the path segment. |
+| `@sealed` | Type | `type Product @table @sealed { ... }` | Rejects undeclared properties. Omit it when the table intentionally accepts extra record fields. |
+| `@primaryKey` | Field | `id: Long @primaryKey` | Marks the unique table key. If omitted on insert, Harper v4 can auto-generate a UUID for `String`/`ID` keys or an auto-incrementing integer for `Int`/`Long`/`Any` keys. Prefer `Long` or `Any` for generated numeric keys. |
+| `@indexed` | Field | `sku: String @indexed` | Adds a secondary index used by REST filters, SQL, and NoSQL/search paths. Array fields index each element. For vectors in Harper v4.6+, use `embedding: [Float] @indexed(type: "HNSW")`. |
+| `@createdTime` | Field | `createdAt: Long @createdTime` | Writes Unix epoch milliseconds when the record is created. |
+| `@updatedTime` | Field | `updatedAt: Long @updatedTime` | Writes Unix epoch milliseconds whenever the record is updated. |
+| `@relationship(from: field)` | Field | `owner: Owner @relationship(from: ownerId)` | The foreign key is on this table and references the target table primary key. If the foreign key field is an array, the relationship is many-to-many. |
+| `@relationship(to: field)` | Field | `dogs: [Dog] @relationship(to: ownerId)` | The foreign key is on the target table. The relationship field must be an array. |
+| `@relationship(from: field, to: field)` | Field | `product: Product @relationship(from: productSku, to: sku)` | Joins this table's field to a non-primary-key field on the target table. Index both join fields. |
+
+Use v5 docs only when the downstream project has intentionally moved off the Lisa
+template's Harper 4 dependency; do not mix v5-only syntax into a `harperdb`
+`^4.7.29` project.
 
 ## How the schema drives the app
 
@@ -48,6 +59,45 @@ type Dog @table {
   or removal in the schema is a breaking change for every resource and verify path
   that references it.
 
+## Schema evolution
+
+Schema changes are deploy-time data-model changes, not just type edits. Harper's
+`graphqlSchema` extension ensures declared tables and attributes exist when the
+component loads, but it does not perform semantic data migrations such as
+renaming tables, copying field values, or rewriting existing rows for you.
+
+Classify each change before editing:
+
+| Change | Compatibility | What Harper does | Required agent work |
+| --- | --- | --- | --- |
+| Add optional field | Usually safe | Adds the declared attribute shape; existing rows read as missing/`null` until written. | Update resources, seeds, and verification that should include the field. |
+| Add required/non-null field | Breaking for existing rows and writers | The schema can declare the field, but existing records do not magically gain valid values. | Backfill first or deploy as optional, populate, then tighten in a later deploy. |
+| Add `@indexed` | Usually safe, operationally sensitive | Creates/uses a secondary index for the attribute. Large tables may pay rebuild cost. | Verify filtered REST/search paths and note index build risk in the deploy runbook. |
+| Add `@sealed` | Breaking when rows or writers use extra properties | Future writes with undeclared properties are rejected. | Audit current data/writers, declare needed fields, or migrate callers before sealing. |
+| Rename field | Breaking | Treated as a new field; the old field and its values are not transformed. | Add the new field, copy values with a migration, update code, verify, then remove old usage. |
+| Rename type/table | Breaking | Harper v4 does not rename tables; changing the type name creates a new empty table and leaves the old table/data untouched. | Create the new table, copy data, update resources/routes, verify both read/write paths, then retire the old table intentionally. |
+| Change field type | Breaking | Existing stored values are not coerced into the new type in a controlled migration. | Add a replacement field/table, transform data with code, verify, then remove old usage. |
+| Remove field/type | Breaking | Schema no longer declares it, but dependent resources, routes, queries, seeds, and clients can still reference it. | Delete references first, run a migration/cleanup if needed, and verify old API paths fail or redirect intentionally. |
+
+Migration recipe for production data:
+
+1. Add the new schema shape in a backward-compatible way: new table or nullable
+   replacement field, keeping the old field/table available.
+2. Write a one-shot migration using a Harper resource method or Operations
+   API/script that reads old rows, transforms values, and writes the new shape.
+   Make it idempotent; reruns should skip rows already migrated or compare a
+   migration marker.
+3. Deploy to one Fabric environment and run the migration before switching
+   readers/writers. For replicated Fabric deployments, assume every node may see
+   the new code/schema at slightly different times; keep old and new reads
+   compatible until replication and smoke checks are green.
+4. Update resources, REST/GraphQL queries, data-loader seeds, and verify scripts
+   in the same PR. A schema PR is incomplete if `bun run verify` or the project
+   smoke path cannot prove the migrated read/write behavior.
+5. Roll back by reverting code/schema only when the old field/table remains
+   intact. Once cleanup drops old data or callers, rollback needs a reverse
+   migration and a restored compatibility path.
+
 ## Project conventions
 
 - `schema.graphql` is **source** and lives at the component root that Fabric
@@ -68,5 +118,6 @@ Run any verify path that asserts row counts or joins against the changed model.
 
 ## Sources
 
-- [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
-- [Applications](https://docs.harperdb.io/docs/developers/applications)
+- [Harper v4 Schema](https://docs.harperdb.io/reference/v4/database/schema)
+- [Components overview](https://docs.harperdb.io/reference/v4/components/overview)
+- [Operations API](https://docs.harperdb.io/reference/v4/operations-api/operations)

package/plugins/src/harper-fabric/skills/harper-testing/SKILL.md

@@ -0,0 +1,254 @@
+---
+name: harper-testing
+description: This skill should be used when adding, repairing, or designing tests for a Harper (HarperDB/Fabric) component app — Vitest unit tests for pure functions and Resource methods, local Harper integration tests that boot/symlink/seed/assert real endpoints, Playwright e2e tests against REST/GraphQL routes, and schema/verify-script coupling. Use it when a Harper app needs its first test suite, endpoint coverage, seed isolation, or a local smoke/verify path. Pairs with harper-build-and-deploy, harper-schema-graphql, and e2e-coverage-gaps.
+---
+
+# Harper Testing
+
+## Overview
+
+Test Harper apps at the layer that proves the risk:
+
+1. **Pure unit tests** for TypeScript helpers and data transforms.
+2. **Resource unit tests** for `Resource` methods with mocked Harper runtime globals.
+3. **Integration tests** against a running local Harper component with real schema,
+   resources, seed data, and REST/GraphQL responses.
+4. **Playwright e2e tests** against the same HTTP surface a user or client calls.
+
+Harper application source lives in TypeScript under `src/`; deployable
+`harper-app/resources.js`, `harper-app/resource-*.js`, and `harper-app/web/**` are
+generated. Build before integration or e2e tests so the runtime loads the code you
+just changed. See [[harper-build-and-deploy]].
+
+## Test pyramid
+
+| Layer | Tool | Use when | Avoid |
+| --- | --- | --- | --- |
+| Pure unit | Vitest | Validating transforms, validators, serializers, query builders, and other code with no Harper runtime dependency. | Mocking HTTP or tables for logic that can stay pure. |
+| Resource unit | Vitest | Exercising `get`, `post`, `search`, `patch`, or permission/error logic in a resource class without booting Harper. | Treating mocked tables as proof that `config.yaml`, `schema.graphql`, or REST exposure works. |
+| Integration | Vitest or shell smoke | Proving Harper boots, schema loads, `jsResource` registers code, data seeds, and endpoints respond. | Replacing this with resource mocks after config, schema, or generated artifact changes. |
+| E2E | Playwright | Verifying client-observable REST/GraphQL behavior, auth states, error paths, and browser workflows. | Re-testing every pure branch through the browser. |
+
+Use [[e2e-coverage-gaps]] after a suite exists to find missing routes and
+non-happy paths. Use this skill when creating or repairing the test patterns
+themselves.
+
+## Pure unit tests
+
+Keep business transforms importable without Harper globals:
+
+```typescript
+import { describe, expect, it } from 'vitest';
+import { normalizePetName } from '../src/pets/normalize';
+
+describe('normalizePetName', () => {
+  it('trims and title-cases names', () => {
+    expect(normalizePetName('  ada LOVELACE ')).toBe('Ada Lovelace');
+  });
+});
+```
+
+If a resource method contains complex transformation logic, extract the pure part
+and test it directly. Leave a thinner resource test for runtime wiring,
+authorization, and persistence behavior.
+
+## Resource unit tests
+
+Harper injects runtime globals such as `Resource` and `tables` when it loads
+`resources.js`. Unit tests do not get those globals automatically. Test resource
+methods by importing code through a seam that accepts mocks, or by setting the
+minimal globals before importing the resource module.
+
+Prefer dependency injection for new code:
+
+```typescript
+import { describe, expect, it, vi } from 'vitest';
+import { createPetsResource } from '../src/resources/pets';
+
+describe('PetsResource.get', () => {
+  it('adds adoption status from the table record', async () => {
+    const table = {
+      get: vi.fn(async () => ({ id: 'pet-1', name: 'Mina', adoptedAt: null })),
+    };
+    const Pets = createPetsResource({ Resource: class {}, table });
+
+    await expect(Pets.get({ id: 'pet-1' })).resolves.toMatchObject({
+      id: 'pet-1',
+      name: 'Mina',
+      adoptionStatus: 'available',
+    });
+    expect(table.get).toHaveBeenCalledWith({ id: 'pet-1' });
+  });
+});
+```
+
+When existing code must extend `tables.X` directly, isolate the runtime globals in
+a test helper and import the module after setup:
+
+```typescript
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+
+describe('Pets resource', () => {
+  beforeEach(() => {
+    vi.resetModules();
+    vi.stubGlobal('Resource', class {});
+    vi.stubGlobal('tables', {
+      Pets: class {
+        static async get(target: { id: string }) {
+          return { id: target.id, name: 'Mina' };
+        }
+      },
+    });
+  });
+
+  it('wraps the runtime table', async () => {
+    const { Pets } = await import('../src/resources/pets');
+    await expect(Pets.get({ id: 'pet-1' })).resolves.toMatchObject({
+      id: 'pet-1',
+      name: 'Mina',
+    });
+  });
+});
+```
+
+Keep mocks narrow. Mock only the table methods, `Resource` base behavior,
+`server.resources`, or external fetch calls the method actually uses. If the test
+starts recreating Harper's schema, REST routing, or auth behavior, move it to an
+integration test.
+
+## Integration tests with local Harper
+
+Use integration tests to prove the component runs as Harper will load it:
+
+1. Install dependencies and build TypeScript: `bun install --frozen-lockfile`
+   when needed, then `bun run build`.
+2. Start a local Harper process against the component, usually
+   `harper dev harper-app` for watch mode or `harper run harper-app` for a
+   one-shot test process. Use the project's wrapper command when present.
+3. If the test lives outside the app repo, symlink the built component into
+   Harper's component directory rather than copying generated artifacts by hand.
+   Clean the symlink in teardown.
+4. Seed data through `dataLoader` fixtures when the project owns static fixtures,
+   or through REST/Operations API calls when each test needs dynamic setup.
+5. Assert the real REST/GraphQL endpoint and response body.
+6. Stop Harper and remove test data, temp components, and symlinks.
+
+Shell smoke tests are acceptable when the project already has that convention.
+Keep them strict: exit non-zero on boot failure, seed failure, missing endpoint,
+wrong status, or wrong response shape.
+
+Example integration skeleton:
+
+```bash
+#!/usr/bin/env bash
+set -euo pipefail
+
+bun run build
+
+HARPER_APP_DIR="${PWD}/harper-app"
+HARPER_HOME="${HARPER_HOME:-${PWD}/.harper-test}"
+BASE_URL="${BASE_URL:-http://127.0.0.1:9926}"
+
+mkdir -p "$HARPER_HOME/components"
+ln -sfn "$HARPER_APP_DIR" "$HARPER_HOME/components/pets"
+
+HARPER_HOME="$HARPER_HOME" harper run "$HARPER_APP_DIR" > /tmp/harper-test.log 2>&1 &
+HARPER_PID=$!
+trap 'kill "$HARPER_PID" 2>/dev/null || true; rm -f "$HARPER_HOME/components/pets"' EXIT
+
+for _ in {1..30}; do
+  curl -fsS "$BASE_URL/health" >/dev/null && break
+  sleep 1
+done
+
+curl -fsS -X POST "$BASE_URL/Pets" \
+  -H 'content-type: application/json' \
+  --data '{"id":"pet-it-1","name":"Mina"}' >/dev/null
+
+curl -fsS "$BASE_URL/Pets/pet-it-1" | jq -e '.name == "Mina"'
+```
+
+Adjust the health path, component name, port, and endpoint names to the project.
+Do not commit local `HARPER_HOME`, logs, generated component copies, or secrets.
+
+## Seeding and isolation
+
+Use deterministic test data that cannot collide with developer or CI data:
+
+- Prefix IDs with the test name and a run ID, for example
+  `pet-${process.env.GITHUB_RUN_ID ?? Date.now()}`.
+- Prefer per-test setup/teardown through REST or Operations API when tests mutate
+  records.
+- Prefer `dataLoader` fixtures for stable baseline data that every local boot
+  should have.
+- Make teardown idempotent; deleting a record that is already gone should not fail
+  the suite.
+- Keep seed fixtures aligned with [[harper-schema-graphql]]. A field or type rename
+  must update fixtures, resource tests, verify scripts, and Playwright assertions in
+  the same PR.
+
+`dataLoader` is good for fast, declarative baseline rows. REST seeding is better
+when the test must exercise validation, defaults, auth, or generated IDs exactly as
+clients see them.
+
+## Playwright endpoint tests
+
+Use Playwright for HTTP behavior that needs browser tooling, request contexts,
+storage state, tracing, or cross-browser/project coverage. A first endpoint spec
+should cover one happy path and one non-happy path:
+
+```typescript
+import { expect, test } from '@playwright/test';
+
+test.describe('Pets REST endpoint', () => {
+  test('creates and reads a pet', async ({ request }) => {
+    const id = `pet-pw-${Date.now()}`;
+
+    const create = await request.post('/Pets', {
+      data: { id, name: 'Mina' },
+    });
+    expect(create.ok()).toBe(true);
+
+    const read = await request.get(`/Pets/${id}`);
+    expect(read.status()).toBe(200);
+    await expect(read).toHaveJSON(expect.objectContaining({ id, name: 'Mina' }));
+  });
+
+  test('rejects invalid payloads', async ({ request }) => {
+    const response = await request.post('/Pets', {
+      data: { name: '' },
+    });
+
+    expect(response.status()).toBeGreaterThanOrEqual(400);
+    await expect(response).toHaveJSON(
+      expect.objectContaining({
+        error: expect.any(String),
+      }),
+    );
+  });
+});
+```
+
+If the project uses custom auth, set `storageState`, headers, or a request fixture
+in Playwright config instead of embedding credentials in specs. Never commit
+tokens or local `.env` values.
+
+## Schema and verify coupling
+
+A schema rename or resource route change is a breaking change for every verify
+path that names that table, field, endpoint, fixture, or response shape.
+
+In the same PR as a schema/resource change:
+
+- Update `schema.graphql`, TypeScript resources, fixtures, and data loaders.
+- Update Vitest resource tests and Playwright endpoint specs.
+- Update shell smoke or `scripts/verify*` paths that assert row counts, joins, or
+  response keys.
+- Run `bun run build`, `bun run typecheck`, and the smallest relevant test command.
+- For deploy-affecting changes, boot local Harper or run the project smoke command
+  against the deployed endpoint. See [[harper-build-and-deploy]].
+
+Do not report a Harper test change done only because mocks pass. At least one
+verify path must prove the generated app still boots and exposes the expected
+surface whenever config, schema, resources, generated artifacts, or endpoints are
+part of the change.