@codyswann/lisa 2.20.0 → 2.21.1

package/package.json

@@ -81,7 +81,7 @@
     "lodash": ">=4.18.1"
   },
   "name": "@codyswann/lisa",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "description": "Claude Code governance framework that applies guardrails, guidance, and automated enforcement to projects",
   "main": "dist/index.js",
   "exports": {

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "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.20.0",
+  "version": "2.21.1",
   "description": "Universal governance: agents, skills, commands, hooks, and rules for all projects.",
   "author": {
     "name": "Cody Swann"

package/plugins/lisa/rules/base-rules.md

@@ -56,7 +56,7 @@ Git Discipline:
 - When opening a PR, watch the PR. If any status checks fail, fix them. For all bot code reviews, if the feedback is valid, implement it and push the change to the PR. Then resolve the feedback. If the feedback is not valid, reply to the feedback explaining why it's not valid and then resolve the feedback. Do this in a loop until the PR is able to be merged and then merge it.
 - When merging a PR into an environment branch (dev, staging, main), watch the resultant deploy until it fully succeeds. If it fails for any reason, fix the failure and then open a new PR with the fix.
 - When referencing a PR in a response, always include the url
-- **Promotion PRs (environment branch → environment branch — e.g., `dev` → `staging`, `staging` → `main`) MUST be merged with a regular merge commit (`gh pr merge --merge`), NEVER squash-merged.** Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into a single commit titled with the PR title, which (a) strips the `[skip ci]` markers so the release workflow re-runs and double-bumps the version on the destination branch, and (b) breaks the release workflow's promotion-detection regex (which inspects the merge-commit subject for `Merge branch 'X' into Y` or `Merge pull request #N from .../<env-branch>`). The merge commit produced by `--merge` keeps the subject clean and the per-commit `[skip ci]` markers attached where they belong. Feature PRs (anything → `dev`) use `--squash` as usual.
+- **Promotion PRs (environment branch → environment branch — e.g., `dev` → `staging`, `staging` → `main`) MUST be merged with a regular merge commit (`gh pr merge --merge`), NEVER squash-merged.** Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into a single commit titled with the PR title, which (a) strips the `[skip ci]` markers so the release workflow re-runs and double-bumps the version on the destination branch, and (b) breaks the release workflow's promotion-detection regex (which inspects the merge-commit subject for `Merge branch 'X' into Y` or `Merge pull request #N from .../<env-branch>`). The merge commit produced by `--merge` keeps the subject clean and the per-commit `[skip ci]` markers attached where they belong. Feature PRs (anything → `dev`) use a regular merge commit (`gh pr merge --merge`) as well.
 
 Testing Discipline:
 - Never skip or disable any tests or quality checks.

package/plugins/lisa/skills/git-submit-pr/SKILL.md

@@ -26,7 +26,7 @@ Push current branch and create or update a pull request. Optional hint: $ARGUMEN
    - If not: Create PR with comprehensive description (not a draft)
 5. **Auto-merge**: Choose merge strategy by PR type:
    - **Promotion PRs** (env → env, e.g. `dev` → `staging`): use `gh pr merge --auto --merge` (never squash). Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into one commit titled with the PR title, stripping the `[skip ci]` markers and breaking the release workflow's promotion-detection regex — the destination branch then double-bumps its version. `--merge` keeps each `chore(release)` commit (and its `[skip ci]` marker) intact under a clean merge commit subject the workflow can recognize.
-   - **Feature PRs** (anything → `dev`): use `gh pr merge --auto --squash`.
+   - **Feature PRs** (anything → `dev`): use `gh pr merge --auto --merge`.
 
 ### PR Description Format
 

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-cdk",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "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.20.0",
+  "version": "2.21.1",
   "description": "AWS CDK-specific Lisa plugin.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-expo",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "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.20.0",
+  "version": "2.21.1",
   "description": "Expo and 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.20.0",
+  "version": "2.21.1",
   "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.20.0",
+  "version": "2.21.1",
   "description": "Harper/Fabric-specific Lisa rules for TypeScript component apps.",
   "author": {
     "name": "Cody Swann"
@@ -14,6 +14,7 @@
   "dependencies": [
     "lisa-typescript"
   ],
+  "skills": "./skills/",
   "interface": {
     "displayName": "Lisa Harper/Fabric",
     "shortDescription": "Harper/Fabric workflow guidance",

package/plugins/lisa-harper-fabric/skills/harper-build-and-deploy/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: harper-build-and-deploy
+description: This skill should be used when building, running locally, or deploying a Harper (HarperDB/Fabric) component — running harper dev/run, producing the generated resources.js and web/** from TypeScript via the project build, packaging the harper-app component, deploying to Harper Fabric, or handling deploy-time secrets. Use it for any change that affects the deployable surface or the dev loop. Pairs with harper-component-model, harper-config-yaml, and harper-resources.
+---
+
+# Harper Build and Deploy
+
+## Overview
+
+The Harper lifecycle is: **develop locally → build TypeScript into the deployable
+component → run/iterate → deploy to Fabric**. This skill covers the CLI, the
+project's build step, and the deploy surface so a change is provably finished, not
+just compiling.
+
+## Local dev and run (the CLI)
+
+The CLI binary is `harper` (v5; older installs use `harperdb`). Key commands:
+
+| Command | What it does |
+| --- | --- |
+| `harper dev <path/to/app>` | Dev mode: **watches files, single-threaded, auto-restarts worker threads** on change, with console logging. The fast iteration loop. Does **not** restart the main thread. |
+| `harper run <path/to/app>` | Run an app from any directory. Use when you need the main thread to (re)start; manage start/stop yourself. |
+| `harper start` / `stop` / `restart` | Background (daemon) lifecycle. |
+| `harper status` | Harper and clustering status. |
+| `harper get_components` | List installed components. |
+
+In this project, dev typically runs against the component dir, e.g.
+`harper dev harper-app` (use the project's documented run command if it wraps this).
+
+## The build step (TypeScript → generated artifacts)
+
+Harper loads JavaScript (`resources.js`) and serves static files (`web/**`). In this
+project those are **generated**, not authored:
+
+- **TypeScript under `src/` is source.** `bun run build` compiles it into
+  `harper-app/resources.js` and `harper-app/web/**`.
+- **Never edit `resources.js` or `web/**` directly** — change the TypeScript and
+  rebuild. See [[harper-resources]] and [[harper-component-model]].
+- **Build before symlinking, packaging, or deploying `harper-app/`.** Deploying
+  stale artifacts ships code that does not match `src/`.
+
+## The deployable surface
+
+A deployable Harper component must keep these at the component root Fabric packages:
+
+- `config.yaml` — active extensions ([[harper-config-yaml]])
+- `schema.graphql` — data model ([[harper-schema-graphql]])
+- `resources.js` — generated custom logic
+- `web/**` — generated static assets
+
+If a change touches this surface, it is not done until the local build and the
+relevant deployed or smoke path agree.
+
+## Deploying to Fabric
+
+Fabric is Harper's distributed deploy network. Deploy packages the component and
+sends it to a target instance:
+
+```bash
+harper deploy_component \
+  project=<app-name> \
+  package=<path-or-git-url> \
+  target=https://<instance>:9925 \
+  username=<user> \
+  password=<pass> \
+  restart=true \
+  replicated=true
+```
+
+- Omitting `package` deploys the current directory.
+- `restart=true` restarts threads after deploy so new code loads.
+- `replicated=true` replicates the deploy across all nodes in a cluster — include it
+  when targeting Fabric/a cluster.
+- Credentials can come from `CLI_TARGET_USERNAME` / `CLI_TARGET_PASSWORD` instead of
+  inline flags — prefer that so secrets never land in shell history or tracked files.
+
+## Secrets
+
+Keep runtime secrets out of tracked files. Use environment variables, the
+`loadEnv` extension, or an OS keychain helper. Document *where* secrets live (which
+env var, which store) without recording their values.
+
+## Verification (required before reporting done)
+
+1. `bun run build` — produces fresh `resources.js` / `web/**`.
+2. `bun run typecheck`.
+3. The smallest relevant test command.
+4. For deploy-affecting changes, the project **smoke command** against the local or
+   deployed Harper endpoint.
+
+If a verification command cannot run, report the exact command and the blocker —
+do not claim completion. When you hit a Harper/Fabric limitation or workaround,
+record the symptom, root cause, fix, and the tempting-but-broken alternatives in
+the project's Fabric runbook.
+
+## Sources
+
+- [Harper CLI overview](https://docs.harperdb.io/reference/v4/cli/overview)
+- [Harper CLI](https://docs.harperdb.io/docs/deployments/harper-cli)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Harper Fabric](https://www.harper.fast/)

package/plugins/lisa-harper-fabric/skills/harper-component-model/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: harper-component-model
+description: This skill should be used when reasoning about how a Harper (formerly HarperDB) Fabric application is structured — what a component, application, extension, or plugin is, where code and assets belong, and how the pieces depend on each other. Use it before adding a new capability, wiring an extension, deciding where a file should live, or explaining the runtime to someone. Pairs with harper-config-yaml, harper-resources, harper-schema-graphql, and harper-build-and-deploy.
+---
+
+# Harper Component Model
+
+## Overview
+
+Harper (formerly HarperDB; the product and company now at harper.fast) is an
+open-source Node.js platform that fuses **database, cache, application logic, and
+messaging into a single in-memory process**. **Fabric** is Harper's distributed
+deploy network: you develop locally, then deploy the same component to Fabric.
+
+Everything you build is a **component**. Understanding the component hierarchy is
+the prerequisite for every other Harper decision — config, resources, schema, and
+deploy all hang off it.
+
+## The three tiers
+
+Harper organizes functionality into three tiers, top to bottom:
+
+1. **Applications** — the user-facing product. An application *is* a type of
+   component. It implements business logic (REST/GraphQL endpoints, web UI,
+   real-time) by depending on extensions/plugins. This is what this project is.
+2. **Plugins** (v5) / **Extensions** (deprecated) — the building blocks an
+   application depends on. A plugin exports a single `handleApplication(scope)`
+   method and always runs on worker threads. The deprecated Extension API used
+   `start`, `handleFile`, `handleDirectory`, and `setupDirectory` instead.
+   `handleApplication()` cannot coexist with Extension API methods — defining
+   both throws. Prefer the Plugin API for any custom building block.
+3. **Core services** — the high-performance database, networking middleware, and
+   the component manager. You configure these; you don't reimplement them.
+
+> An *application* is the component you ship. *Extensions/plugins* are the
+> capabilities it consumes. Built-in extensions (`graphqlSchema`, `jsResource`,
+> `rest`, `static`, …) are provided by core; you only *enable* them in
+> `config.yaml`. See [[harper-config-yaml]].
+
+## Built-in extensions an application typically uses
+
+These ship with Harper and are enabled (not installed) via `config.yaml`:
+
+- `graphqlSchema` — define database tables/types from GraphQL schema files. See [[harper-schema-graphql]].
+- `jsResource` — load custom JavaScript resources (`resources.js`). See [[harper-resources]].
+- `rest` — auto-generate REST endpoints for exported resources/tables.
+- `static` — serve static files (the `web/**` directory) over HTTP.
+- `roles` — role-based access control from `roles.yaml`.
+- `loadEnv` — load environment variables from `.env`.
+- `dataLoader` — seed Harper tables from JSON/YAML.
+- `fastifyRoutes` — custom Fastify route handlers.
+
+## Where things live in this project
+
+This project wraps Harper's native model with a fixed layout under `harper-app/`:
+
+| Path | Role | Source or generated |
+| --- | --- | --- |
+| `harper-app/config.yaml` | Component config — which extensions are active | **Source** |
+| `harper-app/schema.graphql` | Table/type definitions | **Source** |
+| `src/**` (TypeScript) | Resources, browser modules, shared libs, scripts | **Source** |
+| `harper-app/resources.js` | Loaded by `jsResource` | **Generated** — never edit; build from TS |
+| `harper-app/web/**` | Served by `static` | **Generated** — never edit; build from TS |
+
+The TypeScript under `src/` is the source of truth. `resources.js` and `web/**`
+are deploy artifacts produced by `bun run build`. Never hand-edit them — change
+the matching TypeScript and rebuild. See [[harper-build-and-deploy]].
+
+## Decision guide
+
+- **Adding a backend behavior?** It's almost always a *resource* (custom logic) or
+  a *schema* change (new table/field), enabled through `config.yaml`. Don't ship a
+  client-side workaround for missing backend behavior — make the Harper change.
+- **Adding a reusable building block / npm-publishable capability?** That's a
+  *plugin* (`pluginModule`), not application code.
+- **Adding static UI?** It belongs in `web/**` (generated from `src/` UI code), served
+  by the `static` extension.
+- **Not sure if it deploys?** A deployable Harper app must keep `config.yaml`,
+  `schema.graphql`, `resources.js`, and `web/**` at the component root that Fabric
+  packages. If your change touches that surface, build before packaging.
+
+## Sources
+
+- [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)
+- [Harper platform](https://www.harper.fast/)

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

@@ -0,0 +1,107 @@
+---
+name: harper-config-yaml
+description: This skill should be used when creating or editing a Harper (HarperDB/Fabric) component's config.yaml — enabling a built-in extension (graphqlSchema, jsResource, rest, static, roles, loadEnv, dataLoader, fastifyRoutes), wiring an external component, or troubleshooting why an extension is not loading. Critical: it documents the no-merge footgun where a custom config.yaml replaces Harper's default config entirely. Pairs with harper-component-model, harper-resources, and harper-schema-graphql.
+---
+
+# Harper config.yaml
+
+## Overview
+
+A Harper component is configured by a single `config.yaml` at the component root
+(`harper-app/config.yaml` in this project). It declares **which extensions are
+active** and which files each extension reads. Extensions are *enabled* here, not
+installed — the built-ins ship with Harper.
+
+The structure is a map of extension name to its options:
+
+```yaml
+extensionName:
+  option-1: value
+  option-2: value
+```
+
+## ⚠️ The no-merge footgun
+
+If a component has **no** `config.yaml`, Harper applies this default automatically:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: '*.graphql'
+roles:
+  files: 'roles.yaml'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: '.'
+static:
+  files: 'web/**'
+```
+
+The moment you add a **custom `config.yaml`, it replaces this default entirely —
+Harper does not merge your file with the defaults.** If you write a `config.yaml`
+that only enables `static`, you have silently turned off `rest`, `graphqlSchema`,
+`jsResource`, and `roles`. This is the most common Harper config mistake.
+
+**Rule:** when you add or edit `config.yaml`, re-declare every extension the app
+actually needs — start from the default block above and add to it. Do not assume
+unmentioned extensions stay on.
+
+## Built-in extensions
+
+| Key | Purpose | Common options |
+| --- | --- | --- |
+| `rest` | Auto REST endpoints for exported resources/tables | `true`, or an object with options |
+| `graphqlSchema` | Define tables/types from GraphQL files | `files: '*.graphql'` — see [[harper-schema-graphql]] |
+| `jsResource` | Load custom JS resources | `files: 'resources.js'` — see [[harper-resources]] |
+| `static` | Serve static files over HTTP | `files: 'web/**'`, `urlPath` |
+| `roles` | Role-based access control | `files: 'roles.yaml'` |
+| `loadEnv` | Load env vars from `.env` | `files` |
+| `dataLoader` | Seed tables from JSON/YAML | `files` |
+| `fastifyRoutes` | Custom Fastify routes | `files: 'routes/*.js'`, `urlPath` |
+
+## External components and custom plugins
+
+A component you depend on from npm needs a `package:` directive matching a
+`package.json` dependency:
+
+```yaml
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  files: './'
+```
+
+A custom plugin you author is wired with `pluginModule` (point at the built JS, not
+TypeScript source):
+
+```yaml
+pluginModule: ./dist/index.js
+```
+
+The deprecated Extension API used `extensionModule` instead. Prefer `pluginModule`.
+See [[harper-component-model]] for the plugin-vs-extension distinction.
+
+## Project conventions
+
+- `config.yaml` is **source** and lives at `harper-app/config.yaml`. It is part of
+  the deployable surface Fabric packages — keep it at the component root.
+- The files `config.yaml` points to (`resources.js`, `web/**`) are **generated** by
+  `bun run build` from TypeScript under `src/`. Editing `config.yaml` to point at a
+  new file means the build must produce that file. See [[harper-build-and-deploy]].
+- A `config.yaml` change is a deploy-shape change: update the matching project doc
+  (the Fabric runbook) in the same change, and re-run the smoke command.
+- Keep secrets out of `config.yaml`. Use `loadEnv` / environment variables and
+  document *where* secrets live without recording their values.
+
+## Verification
+
+After editing `config.yaml`, confirm the app still boots and the expected surface
+is live: run `harper dev harper-app` (or the project's run command) and check that
+the REST/GraphQL/static endpoints you rely on respond. A config that silently
+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)

package/plugins/lisa-harper-fabric/skills/harper-resources/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: harper-resources
+description: This skill should be used when writing or editing Harper (HarperDB/Fabric) resources — the classes in resources.js (built from TypeScript under src/) that expose custom data logic over REST and GraphQL. Use it when adding an endpoint, overriding table behavior, wrapping an external API, or wiring real-time subscriptions. Covers the Resource method-to-HTTP mapping and the TS-is-source build convention. Pairs with harper-schema-graphql, harper-config-yaml, and harper-build-and-deploy.
+---
+
+# Harper Resources
+
+## Overview
+
+A **Resource** is a class that provides a unified interface for a set of records or
+entities. Resources are how you add custom server-side behavior to a Harper app.
+They are loaded by the `jsResource` extension (default file `resources.js`) and,
+when **exported**, become live REST and GraphQL endpoints.
+
+A resource either **extends a database table** (to customize an existing table's
+behavior) or **extends the base `Resource` class** (to expose data from anywhere —
+an external API, a computed view, an in-memory source).
+
+## Method → HTTP verb mapping
+
+The Resource API mirrors REST. Override the method matching the operation you want
+to customize:
+
+| Method | HTTP | Use |
+| --- | --- | --- |
+| `get(target)` | GET | Retrieve a record/collection |
+| `post(data)` | POST | Create |
+| `put(target, data)` | PUT | Replace |
+| `patch(target, data)` | PATCH | Partial update |
+| `delete(target)` | DELETE | Remove |
+| `search(query)` | GET (query) | Query with conditions |
+| `subscribe` / `publish` | MQTT/WebSocket | Real-time |
+
+## Extending a table
+
+Add computed fields or guard logic while keeping the table's built-in behavior via
+`super`:
+
+```javascript
+export class MyTable extends tables.MyTable {
+  static async get(target) {
+    const record = await super.get(target);
+    return { ...record, computedField: 'value' };
+  }
+}
+```
+
+## Wrapping an external source
+
+```javascript
+export class MyExternalData extends Resource {
+  static async get(target) {
+    const response = await fetch(`https://api.example.com/${target.id}`);
+    return response.json();
+  }
+}
+```
+
+## Making a resource an endpoint
+
+A resource becomes an endpoint when it is **exported** and `rest: true` (and/or
+`graphqlSchema`) is enabled in `config.yaml`:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: schema.graphql
+jsResource:
+  files: resources.js
+```
+
+Resources can also be registered programmatically with `server.resources.set()`.
+See [[harper-config-yaml]] for the extension wiring and [[harper-schema-graphql]]
+for how the schema defines the tables resources extend.
+
+## Project conventions (TS is source)
+
+- **Write resources in TypeScript under `src/`. `harper-app/resources.js` is a
+  generated artifact** produced by `bun run build`. Never edit `resources.js` by
+  hand — change the TypeScript and rebuild. See [[harper-build-and-deploy]].
+- Operational scripts that touch resources (seed, smoke, verify, ingest, crawl,
+  extraction) must run from compiled JavaScript or generated Harper assets, not
+  stale checked-in JS.
+- Prefer immutable data flow: `readonly` types, pure transformations, copies, and
+  explicit returns. Do not mutate parameters, records, arrays, or config objects
+  unless an API forces it, and document the exception locally.
+- Avoid `any`, broad casts, and `ts-ignore`. If an external API forces an escape
+  hatch, isolate it behind a typed adapter.
+
+## Build the real thing
+
+If an endpoint needs a schema change, a seed path, or a deploy script change, make
+that change — do not ship a client-side workaround or silently downgrade to a stub
+or mock. A change is unfinished until the local build and the relevant deployed or
+smoke path agree.
+
+## Verification
+
+Run `bun run build`, `bun run typecheck`, and the smallest relevant test. For an
+endpoint change, also hit the actual REST/GraphQL route against a local or deployed
+Harper instance (the project smoke command) and confirm the response shape.
+
+## Sources
+
+- [Resources overview](https://docs.harperdb.io/reference/v5/resources/overview)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)

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

@@ -0,0 +1,72 @@
+---
+name: harper-schema-graphql
+description: This skill should be used when editing a Harper (HarperDB/Fabric) schema.graphql — defining or changing database tables, types, fields, relationships, or indexes that the graphqlSchema extension turns into Harper tables and API surface. Use it when adding a table, changing the data model, or when a resource/verify path depends on schema shape. Pairs with harper-resources, harper-config-yaml, and harper-component-model.
+---
+
+# Harper schema.graphql
+
+## Overview
+
+Harper defines its database tables and types from **GraphQL schema files**, loaded
+by the `graphqlSchema` extension (default `*.graphql`; this project uses
+`harper-app/schema.graphql`). The schema is the source of truth for the data model:
+the tables it declares are what resources extend ([[harper-resources]]) and what
+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:
+
+```graphql
+type Dog @table {
+  id: ID @primaryKey
+  name: String @indexed
+  breed: String
+  owner: String
+}
+```
+
+- `@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.
+
+## How the schema drives the app
+
+- The `graphqlSchema` extension creates/migrates tables from the schema on load.
+- `rest: true` exposes exported tables/resources as REST endpoints; the GraphQL
+  surface is generated from the same schema.
+- Resources that `extends tables.X` depend on `X` existing in the schema. A rename
+  or removal in the schema is a breaking change for every resource and verify path
+  that references it.
+
+## Project conventions
+
+- `schema.graphql` is **source** and lives at the component root that Fabric
+  packages (`harper-app/schema.graphql`). Keep it there.
+- A schema change is a data-model change. In the **same change**:
+  - Update the conceptual schema docs.
+  - Update any verify/smoke paths that assert joins, relationships, or row counts —
+    those assertions encode the data model and must track it.
+  - Update resources and seed/data-loader paths that reference changed tables.
+- Document deploy-affecting consequences (new tables, migrations) in the Fabric
+  runbook. See [[harper-build-and-deploy]].
+
+## Verification
+
+After a schema change, boot the app (`harper dev harper-app` or the project run
+command) and confirm tables migrate cleanly and the dependent endpoints respond.
+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)

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-nestjs",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "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.20.0",
+  "version": "2.21.1",
   "description": "NestJS-specific skills and migration write-protection hooks.",
   "author": {
     "name": "Cody Swann"

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

@@ -1,6 +1,6 @@
 {
   "name": "lisa-rails",
-  "version": "2.20.0",
+  "version": "2.21.1",
   "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.20.0",
+  "version": "2.21.1",
   "description": "Ruby on Rails-specific skills and hooks for RuboCop 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.20.0",
+  "version": "2.21.1",
   "description": "TypeScript-specific hooks — Prettier formatting, ESLint linting, and ast-grep scanning on edit",
   "author": {
     "name": "Cody Swann"

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

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

package/plugins/src/base/rules/base-rules.md

@@ -56,7 +56,7 @@ Git Discipline:
 - When opening a PR, watch the PR. If any status checks fail, fix them. For all bot code reviews, if the feedback is valid, implement it and push the change to the PR. Then resolve the feedback. If the feedback is not valid, reply to the feedback explaining why it's not valid and then resolve the feedback. Do this in a loop until the PR is able to be merged and then merge it.
 - When merging a PR into an environment branch (dev, staging, main), watch the resultant deploy until it fully succeeds. If it fails for any reason, fix the failure and then open a new PR with the fix.
 - When referencing a PR in a response, always include the url
-- **Promotion PRs (environment branch → environment branch — e.g., `dev` → `staging`, `staging` → `main`) MUST be merged with a regular merge commit (`gh pr merge --merge`), NEVER squash-merged.** Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into a single commit titled with the PR title, which (a) strips the `[skip ci]` markers so the release workflow re-runs and double-bumps the version on the destination branch, and (b) breaks the release workflow's promotion-detection regex (which inspects the merge-commit subject for `Merge branch 'X' into Y` or `Merge pull request #N from .../<env-branch>`). The merge commit produced by `--merge` keeps the subject clean and the per-commit `[skip ci]` markers attached where they belong. Feature PRs (anything → `dev`) use `--squash` as usual.
+- **Promotion PRs (environment branch → environment branch — e.g., `dev` → `staging`, `staging` → `main`) MUST be merged with a regular merge commit (`gh pr merge --merge`), NEVER squash-merged.** Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into a single commit titled with the PR title, which (a) strips the `[skip ci]` markers so the release workflow re-runs and double-bumps the version on the destination branch, and (b) breaks the release workflow's promotion-detection regex (which inspects the merge-commit subject for `Merge branch 'X' into Y` or `Merge pull request #N from .../<env-branch>`). The merge commit produced by `--merge` keeps the subject clean and the per-commit `[skip ci]` markers attached where they belong. Feature PRs (anything → `dev`) use a regular merge commit (`gh pr merge --merge`) as well.
 
 Testing Discipline:
 - Never skip or disable any tests or quality checks.

package/plugins/src/base/skills/git-submit-pr/SKILL.md

@@ -26,7 +26,7 @@ Push current branch and create or update a pull request. Optional hint: $ARGUMEN
    - If not: Create PR with comprehensive description (not a draft)
 5. **Auto-merge**: Choose merge strategy by PR type:
    - **Promotion PRs** (env → env, e.g. `dev` → `staging`): use `gh pr merge --auto --merge` (never squash). Squashing flattens the constituent `chore(release): X.Y.Z [skip ci]` commits into one commit titled with the PR title, stripping the `[skip ci]` markers and breaking the release workflow's promotion-detection regex — the destination branch then double-bumps its version. `--merge` keeps each `chore(release)` commit (and its `[skip ci]` marker) intact under a clean merge commit subject the workflow can recognize.
-   - **Feature PRs** (anything → `dev`): use `gh pr merge --auto --squash`.
+   - **Feature PRs** (anything → `dev`): use `gh pr merge --auto --merge`.
 
 ### PR Description Format
 

package/plugins/src/harper-fabric/skills/harper-build-and-deploy/SKILL.md

@@ -0,0 +1,101 @@
+---
+name: harper-build-and-deploy
+description: This skill should be used when building, running locally, or deploying a Harper (HarperDB/Fabric) component — running harper dev/run, producing the generated resources.js and web/** from TypeScript via the project build, packaging the harper-app component, deploying to Harper Fabric, or handling deploy-time secrets. Use it for any change that affects the deployable surface or the dev loop. Pairs with harper-component-model, harper-config-yaml, and harper-resources.
+---
+
+# Harper Build and Deploy
+
+## Overview
+
+The Harper lifecycle is: **develop locally → build TypeScript into the deployable
+component → run/iterate → deploy to Fabric**. This skill covers the CLI, the
+project's build step, and the deploy surface so a change is provably finished, not
+just compiling.
+
+## Local dev and run (the CLI)
+
+The CLI binary is `harper` (v5; older installs use `harperdb`). Key commands:
+
+| Command | What it does |
+| --- | --- |
+| `harper dev <path/to/app>` | Dev mode: **watches files, single-threaded, auto-restarts worker threads** on change, with console logging. The fast iteration loop. Does **not** restart the main thread. |
+| `harper run <path/to/app>` | Run an app from any directory. Use when you need the main thread to (re)start; manage start/stop yourself. |
+| `harper start` / `stop` / `restart` | Background (daemon) lifecycle. |
+| `harper status` | Harper and clustering status. |
+| `harper get_components` | List installed components. |
+
+In this project, dev typically runs against the component dir, e.g.
+`harper dev harper-app` (use the project's documented run command if it wraps this).
+
+## The build step (TypeScript → generated artifacts)
+
+Harper loads JavaScript (`resources.js`) and serves static files (`web/**`). In this
+project those are **generated**, not authored:
+
+- **TypeScript under `src/` is source.** `bun run build` compiles it into
+  `harper-app/resources.js` and `harper-app/web/**`.
+- **Never edit `resources.js` or `web/**` directly** — change the TypeScript and
+  rebuild. See [[harper-resources]] and [[harper-component-model]].
+- **Build before symlinking, packaging, or deploying `harper-app/`.** Deploying
+  stale artifacts ships code that does not match `src/`.
+
+## The deployable surface
+
+A deployable Harper component must keep these at the component root Fabric packages:
+
+- `config.yaml` — active extensions ([[harper-config-yaml]])
+- `schema.graphql` — data model ([[harper-schema-graphql]])
+- `resources.js` — generated custom logic
+- `web/**` — generated static assets
+
+If a change touches this surface, it is not done until the local build and the
+relevant deployed or smoke path agree.
+
+## Deploying to Fabric
+
+Fabric is Harper's distributed deploy network. Deploy packages the component and
+sends it to a target instance:
+
+```bash
+harper deploy_component \
+  project=<app-name> \
+  package=<path-or-git-url> \
+  target=https://<instance>:9925 \
+  username=<user> \
+  password=<pass> \
+  restart=true \
+  replicated=true
+```
+
+- Omitting `package` deploys the current directory.
+- `restart=true` restarts threads after deploy so new code loads.
+- `replicated=true` replicates the deploy across all nodes in a cluster — include it
+  when targeting Fabric/a cluster.
+- Credentials can come from `CLI_TARGET_USERNAME` / `CLI_TARGET_PASSWORD` instead of
+  inline flags — prefer that so secrets never land in shell history or tracked files.
+
+## Secrets
+
+Keep runtime secrets out of tracked files. Use environment variables, the
+`loadEnv` extension, or an OS keychain helper. Document *where* secrets live (which
+env var, which store) without recording their values.
+
+## Verification (required before reporting done)
+
+1. `bun run build` — produces fresh `resources.js` / `web/**`.
+2. `bun run typecheck`.
+3. The smallest relevant test command.
+4. For deploy-affecting changes, the project **smoke command** against the local or
+   deployed Harper endpoint.
+
+If a verification command cannot run, report the exact command and the blocker —
+do not claim completion. When you hit a Harper/Fabric limitation or workaround,
+record the symptom, root cause, fix, and the tempting-but-broken alternatives in
+the project's Fabric runbook.
+
+## Sources
+
+- [Harper CLI overview](https://docs.harperdb.io/reference/v4/cli/overview)
+- [Harper CLI](https://docs.harperdb.io/docs/deployments/harper-cli)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Harper Fabric](https://www.harper.fast/)

package/plugins/src/harper-fabric/skills/harper-component-model/SKILL.md

@@ -0,0 +1,87 @@
+---
+name: harper-component-model
+description: This skill should be used when reasoning about how a Harper (formerly HarperDB) Fabric application is structured — what a component, application, extension, or plugin is, where code and assets belong, and how the pieces depend on each other. Use it before adding a new capability, wiring an extension, deciding where a file should live, or explaining the runtime to someone. Pairs with harper-config-yaml, harper-resources, harper-schema-graphql, and harper-build-and-deploy.
+---
+
+# Harper Component Model
+
+## Overview
+
+Harper (formerly HarperDB; the product and company now at harper.fast) is an
+open-source Node.js platform that fuses **database, cache, application logic, and
+messaging into a single in-memory process**. **Fabric** is Harper's distributed
+deploy network: you develop locally, then deploy the same component to Fabric.
+
+Everything you build is a **component**. Understanding the component hierarchy is
+the prerequisite for every other Harper decision — config, resources, schema, and
+deploy all hang off it.
+
+## The three tiers
+
+Harper organizes functionality into three tiers, top to bottom:
+
+1. **Applications** — the user-facing product. An application *is* a type of
+   component. It implements business logic (REST/GraphQL endpoints, web UI,
+   real-time) by depending on extensions/plugins. This is what this project is.
+2. **Plugins** (v5) / **Extensions** (deprecated) — the building blocks an
+   application depends on. A plugin exports a single `handleApplication(scope)`
+   method and always runs on worker threads. The deprecated Extension API used
+   `start`, `handleFile`, `handleDirectory`, and `setupDirectory` instead.
+   `handleApplication()` cannot coexist with Extension API methods — defining
+   both throws. Prefer the Plugin API for any custom building block.
+3. **Core services** — the high-performance database, networking middleware, and
+   the component manager. You configure these; you don't reimplement them.
+
+> An *application* is the component you ship. *Extensions/plugins* are the
+> capabilities it consumes. Built-in extensions (`graphqlSchema`, `jsResource`,
+> `rest`, `static`, …) are provided by core; you only *enable* them in
+> `config.yaml`. See [[harper-config-yaml]].
+
+## Built-in extensions an application typically uses
+
+These ship with Harper and are enabled (not installed) via `config.yaml`:
+
+- `graphqlSchema` — define database tables/types from GraphQL schema files. See [[harper-schema-graphql]].
+- `jsResource` — load custom JavaScript resources (`resources.js`). See [[harper-resources]].
+- `rest` — auto-generate REST endpoints for exported resources/tables.
+- `static` — serve static files (the `web/**` directory) over HTTP.
+- `roles` — role-based access control from `roles.yaml`.
+- `loadEnv` — load environment variables from `.env`.
+- `dataLoader` — seed Harper tables from JSON/YAML.
+- `fastifyRoutes` — custom Fastify route handlers.
+
+## Where things live in this project
+
+This project wraps Harper's native model with a fixed layout under `harper-app/`:
+
+| Path | Role | Source or generated |
+| --- | --- | --- |
+| `harper-app/config.yaml` | Component config — which extensions are active | **Source** |
+| `harper-app/schema.graphql` | Table/type definitions | **Source** |
+| `src/**` (TypeScript) | Resources, browser modules, shared libs, scripts | **Source** |
+| `harper-app/resources.js` | Loaded by `jsResource` | **Generated** — never edit; build from TS |
+| `harper-app/web/**` | Served by `static` | **Generated** — never edit; build from TS |
+
+The TypeScript under `src/` is the source of truth. `resources.js` and `web/**`
+are deploy artifacts produced by `bun run build`. Never hand-edit them — change
+the matching TypeScript and rebuild. See [[harper-build-and-deploy]].
+
+## Decision guide
+
+- **Adding a backend behavior?** It's almost always a *resource* (custom logic) or
+  a *schema* change (new table/field), enabled through `config.yaml`. Don't ship a
+  client-side workaround for missing backend behavior — make the Harper change.
+- **Adding a reusable building block / npm-publishable capability?** That's a
+  *plugin* (`pluginModule`), not application code.
+- **Adding static UI?** It belongs in `web/**` (generated from `src/` UI code), served
+  by the `static` extension.
+- **Not sure if it deploys?** A deployable Harper app must keep `config.yaml`,
+  `schema.graphql`, `resources.js`, and `web/**` at the component root that Fabric
+  packages. If your change touches that surface, build before packaging.
+
+## Sources
+
+- [Components overview](https://docs.harperdb.io/reference/v5/components/overview)
+- [Plugin API](https://docs.harperdb.io/reference/v5/components/plugin-api)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)
+- [Harper platform](https://www.harper.fast/)

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

@@ -0,0 +1,107 @@
+---
+name: harper-config-yaml
+description: This skill should be used when creating or editing a Harper (HarperDB/Fabric) component's config.yaml — enabling a built-in extension (graphqlSchema, jsResource, rest, static, roles, loadEnv, dataLoader, fastifyRoutes), wiring an external component, or troubleshooting why an extension is not loading. Critical: it documents the no-merge footgun where a custom config.yaml replaces Harper's default config entirely. Pairs with harper-component-model, harper-resources, and harper-schema-graphql.
+---
+
+# Harper config.yaml
+
+## Overview
+
+A Harper component is configured by a single `config.yaml` at the component root
+(`harper-app/config.yaml` in this project). It declares **which extensions are
+active** and which files each extension reads. Extensions are *enabled* here, not
+installed — the built-ins ship with Harper.
+
+The structure is a map of extension name to its options:
+
+```yaml
+extensionName:
+  option-1: value
+  option-2: value
+```
+
+## ⚠️ The no-merge footgun
+
+If a component has **no** `config.yaml`, Harper applies this default automatically:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: '*.graphql'
+roles:
+  files: 'roles.yaml'
+jsResource:
+  files: 'resources.js'
+fastifyRoutes:
+  files: 'routes/*.js'
+  urlPath: '.'
+static:
+  files: 'web/**'
+```
+
+The moment you add a **custom `config.yaml`, it replaces this default entirely —
+Harper does not merge your file with the defaults.** If you write a `config.yaml`
+that only enables `static`, you have silently turned off `rest`, `graphqlSchema`,
+`jsResource`, and `roles`. This is the most common Harper config mistake.
+
+**Rule:** when you add or edit `config.yaml`, re-declare every extension the app
+actually needs — start from the default block above and add to it. Do not assume
+unmentioned extensions stay on.
+
+## Built-in extensions
+
+| Key | Purpose | Common options |
+| --- | --- | --- |
+| `rest` | Auto REST endpoints for exported resources/tables | `true`, or an object with options |
+| `graphqlSchema` | Define tables/types from GraphQL files | `files: '*.graphql'` — see [[harper-schema-graphql]] |
+| `jsResource` | Load custom JS resources | `files: 'resources.js'` — see [[harper-resources]] |
+| `static` | Serve static files over HTTP | `files: 'web/**'`, `urlPath` |
+| `roles` | Role-based access control | `files: 'roles.yaml'` |
+| `loadEnv` | Load env vars from `.env` | `files` |
+| `dataLoader` | Seed tables from JSON/YAML | `files` |
+| `fastifyRoutes` | Custom Fastify routes | `files: 'routes/*.js'`, `urlPath` |
+
+## External components and custom plugins
+
+A component you depend on from npm needs a `package:` directive matching a
+`package.json` dependency:
+
+```yaml
+'@harperdb/nextjs':
+  package: '@harperdb/nextjs'
+  files: './'
+```
+
+A custom plugin you author is wired with `pluginModule` (point at the built JS, not
+TypeScript source):
+
+```yaml
+pluginModule: ./dist/index.js
+```
+
+The deprecated Extension API used `extensionModule` instead. Prefer `pluginModule`.
+See [[harper-component-model]] for the plugin-vs-extension distinction.
+
+## Project conventions
+
+- `config.yaml` is **source** and lives at `harper-app/config.yaml`. It is part of
+  the deployable surface Fabric packages — keep it at the component root.
+- The files `config.yaml` points to (`resources.js`, `web/**`) are **generated** by
+  `bun run build` from TypeScript under `src/`. Editing `config.yaml` to point at a
+  new file means the build must produce that file. See [[harper-build-and-deploy]].
+- A `config.yaml` change is a deploy-shape change: update the matching project doc
+  (the Fabric runbook) in the same change, and re-run the smoke command.
+- Keep secrets out of `config.yaml`. Use `loadEnv` / environment variables and
+  document *where* secrets live without recording their values.
+
+## Verification
+
+After editing `config.yaml`, confirm the app still boots and the expected surface
+is live: run `harper dev harper-app` (or the project's run command) and check that
+the REST/GraphQL/static endpoints you rely on respond. A config that silently
+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)

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

@@ -0,0 +1,106 @@
+---
+name: harper-resources
+description: This skill should be used when writing or editing Harper (HarperDB/Fabric) resources — the classes in resources.js (built from TypeScript under src/) that expose custom data logic over REST and GraphQL. Use it when adding an endpoint, overriding table behavior, wrapping an external API, or wiring real-time subscriptions. Covers the Resource method-to-HTTP mapping and the TS-is-source build convention. Pairs with harper-schema-graphql, harper-config-yaml, and harper-build-and-deploy.
+---
+
+# Harper Resources
+
+## Overview
+
+A **Resource** is a class that provides a unified interface for a set of records or
+entities. Resources are how you add custom server-side behavior to a Harper app.
+They are loaded by the `jsResource` extension (default file `resources.js`) and,
+when **exported**, become live REST and GraphQL endpoints.
+
+A resource either **extends a database table** (to customize an existing table's
+behavior) or **extends the base `Resource` class** (to expose data from anywhere —
+an external API, a computed view, an in-memory source).
+
+## Method → HTTP verb mapping
+
+The Resource API mirrors REST. Override the method matching the operation you want
+to customize:
+
+| Method | HTTP | Use |
+| --- | --- | --- |
+| `get(target)` | GET | Retrieve a record/collection |
+| `post(data)` | POST | Create |
+| `put(target, data)` | PUT | Replace |
+| `patch(target, data)` | PATCH | Partial update |
+| `delete(target)` | DELETE | Remove |
+| `search(query)` | GET (query) | Query with conditions |
+| `subscribe` / `publish` | MQTT/WebSocket | Real-time |
+
+## Extending a table
+
+Add computed fields or guard logic while keeping the table's built-in behavior via
+`super`:
+
+```javascript
+export class MyTable extends tables.MyTable {
+  static async get(target) {
+    const record = await super.get(target);
+    return { ...record, computedField: 'value' };
+  }
+}
+```
+
+## Wrapping an external source
+
+```javascript
+export class MyExternalData extends Resource {
+  static async get(target) {
+    const response = await fetch(`https://api.example.com/${target.id}`);
+    return response.json();
+  }
+}
+```
+
+## Making a resource an endpoint
+
+A resource becomes an endpoint when it is **exported** and `rest: true` (and/or
+`graphqlSchema`) is enabled in `config.yaml`:
+
+```yaml
+rest: true
+graphqlSchema:
+  files: schema.graphql
+jsResource:
+  files: resources.js
+```
+
+Resources can also be registered programmatically with `server.resources.set()`.
+See [[harper-config-yaml]] for the extension wiring and [[harper-schema-graphql]]
+for how the schema defines the tables resources extend.
+
+## Project conventions (TS is source)
+
+- **Write resources in TypeScript under `src/`. `harper-app/resources.js` is a
+  generated artifact** produced by `bun run build`. Never edit `resources.js` by
+  hand — change the TypeScript and rebuild. See [[harper-build-and-deploy]].
+- Operational scripts that touch resources (seed, smoke, verify, ingest, crawl,
+  extraction) must run from compiled JavaScript or generated Harper assets, not
+  stale checked-in JS.
+- Prefer immutable data flow: `readonly` types, pure transformations, copies, and
+  explicit returns. Do not mutate parameters, records, arrays, or config objects
+  unless an API forces it, and document the exception locally.
+- Avoid `any`, broad casts, and `ts-ignore`. If an external API forces an escape
+  hatch, isolate it behind a typed adapter.
+
+## Build the real thing
+
+If an endpoint needs a schema change, a seed path, or a deploy script change, make
+that change — do not ship a client-side workaround or silently downgrade to a stub
+or mock. A change is unfinished until the local build and the relevant deployed or
+smoke path agree.
+
+## Verification
+
+Run `bun run build`, `bun run typecheck`, and the smallest relevant test. For an
+endpoint change, also hit the actual REST/GraphQL route against a local or deployed
+Harper instance (the project smoke command) and confirm the response shape.
+
+## Sources
+
+- [Resources overview](https://docs.harperdb.io/reference/v5/resources/overview)
+- [Applications](https://docs.harperdb.io/docs/developers/applications)

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

@@ -0,0 +1,72 @@
+---
+name: harper-schema-graphql
+description: This skill should be used when editing a Harper (HarperDB/Fabric) schema.graphql — defining or changing database tables, types, fields, relationships, or indexes that the graphqlSchema extension turns into Harper tables and API surface. Use it when adding a table, changing the data model, or when a resource/verify path depends on schema shape. Pairs with harper-resources, harper-config-yaml, and harper-component-model.
+---
+
+# Harper schema.graphql
+
+## Overview
+
+Harper defines its database tables and types from **GraphQL schema files**, loaded
+by the `graphqlSchema` extension (default `*.graphql`; this project uses
+`harper-app/schema.graphql`). The schema is the source of truth for the data model:
+the tables it declares are what resources extend ([[harper-resources]]) and what
+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:
+
+```graphql
+type Dog @table {
+  id: ID @primaryKey
+  name: String @indexed
+  breed: String
+  owner: String
+}
+```
+
+- `@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.
+
+## How the schema drives the app
+
+- The `graphqlSchema` extension creates/migrates tables from the schema on load.
+- `rest: true` exposes exported tables/resources as REST endpoints; the GraphQL
+  surface is generated from the same schema.
+- Resources that `extends tables.X` depend on `X` existing in the schema. A rename
+  or removal in the schema is a breaking change for every resource and verify path
+  that references it.
+
+## Project conventions
+
+- `schema.graphql` is **source** and lives at the component root that Fabric
+  packages (`harper-app/schema.graphql`). Keep it there.
+- A schema change is a data-model change. In the **same change**:
+  - Update the conceptual schema docs.
+  - Update any verify/smoke paths that assert joins, relationships, or row counts —
+    those assertions encode the data model and must track it.
+  - Update resources and seed/data-loader paths that reference changed tables.
+- Document deploy-affecting consequences (new tables, migrations) in the Fabric
+  runbook. See [[harper-build-and-deploy]].
+
+## Verification
+
+After a schema change, boot the app (`harper dev harper-app` or the project run
+command) and confirm tables migrate cleanly and the dependent endpoints respond.
+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)