@codyswann/lisa 2.166.4 → 2.166.5

package/package.json

@@ -85,7 +85,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {
@@ -166,7 +166,7 @@
     "@types/jest": "^30.0.0",
     "@types/lodash.merge": "^4.6.0",
     "@types/node": "^22.0.0",
-    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/coverage-v8": "^4.1.9",
     "commander": "^12.0.0",
     "esbuild-register": "^3.6.0",
     "eslint": "^9.39.0",
@@ -205,17 +205,17 @@
     "tsx": "^4.0.0",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.0.0",
-    "vitest": "^4.1.0"
+    "vitest": "^4.1.9"
   },
   "devDependencies": {
-    "@codyswann/lisa": "^2.142.1",
+    "@codyswann/lisa": "^2.166.4",
     "@types/js-yaml": "^4.0.9",
     "@types/semver": "^7.7.1",
     "eslint-plugin-oxlint": "^1.62.0",
     "js-yaml": "^4.1.1",
     "oxlint": "^1.62.0",
     "oxlint-tsgolint": "^0.22.1",
-    "vite": "^8.0.5"
+    "vite": "^8.0.16"
   },
   "type": "module"
 }

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-agy/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "AWS CDK-specific plugin",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Universal governance — agents, skills, commands, hooks, and rules for all projects",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Expo and React Native-specific skills, agents, rules, and MCP servers.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "Expo/React Native-specific skills, agents, rules, and MCP servers",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa-harper-fabric/.claude-plugin/plugin.json

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

package/plugins/lisa-harper-fabric/.codex-plugin/plugin.json

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

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

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

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.4",
+  "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-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.4",
+  "version": "2.166.5",
   "description": "Harper/Fabric-specific rules for TypeScript component apps",
   "author": {
     "name": "Cody Swann"

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

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

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

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

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.166.4",
+  "version": "2.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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.166.5",
   "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)