@codyswann/lisa 2.166.3 → 2.166.5

package/plugins/lisa-harper-fabric-agy/skills/harper-config-yaml/SKILL.md

@@ -66,6 +66,175 @@ For real-time work, component `config.yaml` keeps `rest`, `graphqlSchema`, and
 MQTT topic paths. Broker ports and MQTT authentication live in the root
 `harper-config.yaml`, not the component file. See [[harper-realtime]].
 
+## `dataLoader`: seed data
+
+Use `dataLoader` for versioned seed/reference records that should exist whenever
+the component is deployed. Define table shape first with `graphqlSchema`, then
+point `dataLoader.files` at one or more JSON/YAML files:
+
+```yaml
+graphqlSchema:
+  files: 'schema.graphql'
+dataLoader:
+  files:
+    - 'data/roles.yaml'
+    - 'data/reference/*.json'
+```
+
+Each data file targets exactly one table and has `database`, `table`, and
+`records` keys:
+
+```yaml
+database: app
+table: Role
+records:
+  - id: admin
+    name: Administrator
+    permissions:
+      - users:read
+      - users:write
+  - id: viewer
+    name: Viewer
+    permissions:
+      - users:read
+```
+
+Harper runs the loader on full system starts and component deployments. It is
+safe to re-run when files are idempotent: new records are inserted, unchanged
+records are skipped, and records are updated from the file only when the tracked
+file content changed. User-created records and user edits made after an initial
+load are preserved; changed data-loaded records are patched instead of blindly
+replaced.
+
+Choose `dataLoader` for small, source-controlled reference/configuration data
+that should ship with the component. Use a REST/Operations API script or job for
+large imports, environment-specific backfills, or one-off migrations where retry
+scope and operator approval matter.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -s http://localhost:9926/app/Role/admin
+harper dev harper-app # restart/redeploy and confirm the seed did not duplicate
+```
+
+## `fastifyRoutes`: custom HTTP routes
+
+Prefer `jsResource` plus `rest` for normal CRUD/action APIs. Use `fastifyRoutes`
+only when the route shape does not fit the Resource model: webhooks, custom
+serialization, unusual path matching, or a compatibility endpoint.
+
+```yaml
+rest: true
+graphqlSchema:
+  files: 'schema.graphql'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: 'hooks'
+```
+
+Route modules default-export an async function that receives the Fastify server
+and Harper helpers:
+
+```js
+export default async (server, { hdbCore, logger }) => {
+  server.route({
+    method: 'POST',
+    url: '/payment/:provider',
+    preValidation: hdbCore.preValidation,
+    handler: async (request, reply) => {
+      logger.debug(`payment webhook ${request.params.provider}`);
+      request.body = {
+        operation: 'insert',
+        schema: 'app',
+        table: 'WebhookEvent',
+        records: [
+          {
+            id: request.headers['x-event-id'],
+            provider: request.params.provider,
+            payload: request.body,
+          },
+        ],
+      };
+      const result = await hdbCore.request(request);
+      return { ok: true, result };
+    },
+  });
+};
+```
+
+Use Fastify's `request.params`, `request.query`, `request.body`, and `request.headers`
+for route inputs. Keep auth explicit: `hdbCore.request` should be paired with
+`hdbCore.preValidation` so Harper authenticates the request. Avoid
+`requestWithoutAuthentication` unless the route has its own signature/JWT check
+and all user-provided values are bound or escaped; never build SQL strings by
+interpolating params/body values.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -i -X POST http://localhost:9926/app/hooks/payment/stripe \
+  -H 'Authorization: Basic ...' \
+  -H 'Content-Type: application/json' \
+  -H 'x-event-id: evt_123' \
+  --data '{"status":"paid"}'
+```
+
+## `static`: serve web assets and SPAs
+
+Use `static` to serve generated browser output or other immutable assets from
+the component. In Lisa Harper Fabric projects, `harper-app/web/**` is generated
+by the project build; edit the source UI under `src/`, not the deployed files.
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+```
+
+`files` selects what is served. `urlPath` mounts those files under a URL prefix:
+`urlPath: 'app'` makes `web/index.html` available at `/app/index.html`; the
+default application path still includes the Harper project/component prefix. Use
+`index: true` to serve `index.html` for directory requests, and `extensions:
+['html']` when clean URLs should resolve to `.html` files.
+
+For client-side-routed SPAs, return the app shell for unmatched asset paths:
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+  fallthrough: false
+  notFound:
+    file: 'web/index.html'
+    statusCode: 200
+```
+
+That fallback is for browser routes such as `/reports/weekly`; it should not hide
+missing API endpoints or broken asset names. Keep API routes under a clear
+prefix, and check that hashed JS/CSS assets still return their actual files.
+
+Harper's documented `static` config controls path matching and not-found
+behavior, not custom cache policy. Treat MIME type and cache headers as runtime
+behavior to verify with `curl -I`; if the app needs precise cache headers,
+front it with an edge/proxy policy or a custom route designed for that asset
+surface.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -I http://localhost:9926/app/
+curl -I http://localhost:9926/app/assets/index.js
+curl -I http://localhost:9926/app/client-side-route
+```
+
 ## External components and custom plugins
 
 A component you depend on from npm needs a `package:` directive matching a
@@ -109,4 +278,6 @@ dropped an extension often fails only at runtime, not at build time.
 ## Sources
 
 - [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
-- [Built-in extensions](https://docs.harperdb.io/docs/reference/components/built-in-extensions)
+- [Data Loader](https://docs.harperdb.io/reference/v5/database/data-loader)
+- [Fastify Routes](https://docs.harperdb.io/reference/v5/fastify-routes/overview)
+- [Static Files](https://docs.harperdb.io/reference/v5/static-files/overview)

package/plugins/lisa-harper-fabric-agy/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/lisa-harper-fabric-copilot/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.166.3",
+  "version": "2.166.5",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric-copilot/skills/harper-config-yaml/SKILL.md

@@ -66,6 +66,175 @@ For real-time work, component `config.yaml` keeps `rest`, `graphqlSchema`, and
 MQTT topic paths. Broker ports and MQTT authentication live in the root
 `harper-config.yaml`, not the component file. See [[harper-realtime]].
 
+## `dataLoader`: seed data
+
+Use `dataLoader` for versioned seed/reference records that should exist whenever
+the component is deployed. Define table shape first with `graphqlSchema`, then
+point `dataLoader.files` at one or more JSON/YAML files:
+
+```yaml
+graphqlSchema:
+  files: 'schema.graphql'
+dataLoader:
+  files:
+    - 'data/roles.yaml'
+    - 'data/reference/*.json'
+```
+
+Each data file targets exactly one table and has `database`, `table`, and
+`records` keys:
+
+```yaml
+database: app
+table: Role
+records:
+  - id: admin
+    name: Administrator
+    permissions:
+      - users:read
+      - users:write
+  - id: viewer
+    name: Viewer
+    permissions:
+      - users:read
+```
+
+Harper runs the loader on full system starts and component deployments. It is
+safe to re-run when files are idempotent: new records are inserted, unchanged
+records are skipped, and records are updated from the file only when the tracked
+file content changed. User-created records and user edits made after an initial
+load are preserved; changed data-loaded records are patched instead of blindly
+replaced.
+
+Choose `dataLoader` for small, source-controlled reference/configuration data
+that should ship with the component. Use a REST/Operations API script or job for
+large imports, environment-specific backfills, or one-off migrations where retry
+scope and operator approval matter.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -s http://localhost:9926/app/Role/admin
+harper dev harper-app # restart/redeploy and confirm the seed did not duplicate
+```
+
+## `fastifyRoutes`: custom HTTP routes
+
+Prefer `jsResource` plus `rest` for normal CRUD/action APIs. Use `fastifyRoutes`
+only when the route shape does not fit the Resource model: webhooks, custom
+serialization, unusual path matching, or a compatibility endpoint.
+
+```yaml
+rest: true
+graphqlSchema:
+  files: 'schema.graphql'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: 'hooks'
+```
+
+Route modules default-export an async function that receives the Fastify server
+and Harper helpers:
+
+```js
+export default async (server, { hdbCore, logger }) => {
+  server.route({
+    method: 'POST',
+    url: '/payment/:provider',
+    preValidation: hdbCore.preValidation,
+    handler: async (request, reply) => {
+      logger.debug(`payment webhook ${request.params.provider}`);
+      request.body = {
+        operation: 'insert',
+        schema: 'app',
+        table: 'WebhookEvent',
+        records: [
+          {
+            id: request.headers['x-event-id'],
+            provider: request.params.provider,
+            payload: request.body,
+          },
+        ],
+      };
+      const result = await hdbCore.request(request);
+      return { ok: true, result };
+    },
+  });
+};
+```
+
+Use Fastify's `request.params`, `request.query`, `request.body`, and `request.headers`
+for route inputs. Keep auth explicit: `hdbCore.request` should be paired with
+`hdbCore.preValidation` so Harper authenticates the request. Avoid
+`requestWithoutAuthentication` unless the route has its own signature/JWT check
+and all user-provided values are bound or escaped; never build SQL strings by
+interpolating params/body values.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -i -X POST http://localhost:9926/app/hooks/payment/stripe \
+  -H 'Authorization: Basic ...' \
+  -H 'Content-Type: application/json' \
+  -H 'x-event-id: evt_123' \
+  --data '{"status":"paid"}'
+```
+
+## `static`: serve web assets and SPAs
+
+Use `static` to serve generated browser output or other immutable assets from
+the component. In Lisa Harper Fabric projects, `harper-app/web/**` is generated
+by the project build; edit the source UI under `src/`, not the deployed files.
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+```
+
+`files` selects what is served. `urlPath` mounts those files under a URL prefix:
+`urlPath: 'app'` makes `web/index.html` available at `/app/index.html`; the
+default application path still includes the Harper project/component prefix. Use
+`index: true` to serve `index.html` for directory requests, and `extensions:
+['html']` when clean URLs should resolve to `.html` files.
+
+For client-side-routed SPAs, return the app shell for unmatched asset paths:
+
+```yaml
+static:
+  files: 'web/**'
+  urlPath: '.'
+  index: true
+  fallthrough: false
+  notFound:
+    file: 'web/index.html'
+    statusCode: 200
+```
+
+That fallback is for browser routes such as `/reports/weekly`; it should not hide
+missing API endpoints or broken asset names. Keep API routes under a clear
+prefix, and check that hashed JS/CSS assets still return their actual files.
+
+Harper's documented `static` config controls path matching and not-found
+behavior, not custom cache policy. Treat MIME type and cache headers as runtime
+behavior to verify with `curl -I`; if the app needs precise cache headers,
+front it with an edge/proxy policy or a custom route designed for that asset
+surface.
+
+Verify locally:
+
+```bash
+harper dev harper-app
+curl -I http://localhost:9926/app/
+curl -I http://localhost:9926/app/assets/index.js
+curl -I http://localhost:9926/app/client-side-route
+```
+
 ## External components and custom plugins
 
 A component you depend on from npm needs a `package:` directive matching a
@@ -109,4 +278,6 @@ dropped an extension often fails only at runtime, not at build time.
 ## Sources
 
 - [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
-- [Built-in extensions](https://docs.harperdb.io/docs/reference/components/built-in-extensions)
+- [Data Loader](https://docs.harperdb.io/reference/v5/database/data-loader)
+- [Fastify Routes](https://docs.harperdb.io/reference/v5/fastify-routes/overview)
+- [Static Files](https://docs.harperdb.io/reference/v5/static-files/overview)

package/plugins/lisa-harper-fabric-copilot/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/lisa-harper-fabric-cursor/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa-harper-fabric",
-  "version": "2.166.3",
+  "version": "2.166.5",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"