@codyswann/lisa 2.121.0 → 2.122.0

package/plugins/lisa-harper-fabric-agy/skills/exploratory-qa/SKILL.md

@@ -0,0 +1,145 @@
+---
+name: exploratory-qa
+description: First-time-user exploratory QA walkthrough for web apps that FEEDS THE LIFECYCLE. Use when asked to experience an app the way a brand-new human user would — landing cold on the home page and clicking through to find anything confusing, broken, or hard to understand (machine-style labels, slow or unclear loads, cramped or cut-off UI, inconsistent/non-standard UX, awkward scroll behavior, unclear affordances) across all breakpoints. Instead of writing a report file, it files every finding as a tracked work item via lisa:tracker-write (bugs and usability/UX issues). A `ready` parameter controls whether those tickets are created build-ready (auto-picked-up by lisa:intake) or left in the backlog for human triage (default). For gaps in the automated Playwright test suite, use the e2e-coverage-gaps skill instead.
+---
+
+# Exploratory QA
+
+## Overview
+
+Experience the app the way a **brand-new human user** would: land cold on the home page with no prior
+knowledge, then click through and actually try to use it — just like a real person. The goal is to
+surface anything **confusing, broken, or hard to understand**, and to do so at **every breakpoint**.
+
+This is a usability/experience pass, **not** a test-coverage audit. It does not look at the Playwright
+suite or hunt for coverage gaps — for that, use the `e2e-coverage-gaps` skill. Here, every finding is
+filed as a tracked work item so it enters the Lisa lifecycle — no static report file.
+
+## Parameters
+
+- **`target-url | env`** (first positional) — what to explore.
+- **`ready=true|false`** — the build-ready state for the tickets this pass creates.
+  - `ready=true` → created build-ready, so `lisa:intake` / the build-intake scanner auto-picks them up.
+  - `ready=false` (**default**) → created in the backlog (not build-ready) for a human to review and
+    promote into the queue.
+
+## Core Workflow
+
+### 1. Establish Scope
+
+- Identify the target environment, account type, and browser requirement, and read the `ready` flag
+  (default `false`).
+- **Confirm the tracker is configured.** Findings are filed as tickets, so read `tracker` from
+  `.lisa.config.json` (local overrides global). If it is unset, stop and report that the tracker must
+  be configured (via `/lisa:setup:jira` / `:github` / `:linear`) before exploratory QA can file
+  findings — do not silently fall back to a report file.
+- If credentials, tenant, or seed data are missing and cannot be discovered safely, ask one concise
+  clarifying question.
+- Treat production-like environments conservatively. Do not mutate production data unless the user
+  explicitly approves it. Prefer a test user, dev/staging environment, or isolated seeded account.
+
+### 2. Arrive Cold
+
+- Start at the home/landing page with **no prior knowledge of the app**. Do **not** pre-read the
+  codebase to learn the intended flows — discover them the way a user would, by looking and clicking.
+- Form a first impression: is it obvious what this app is, what to do first, and where to go next?
+
+### 3. Use It Like a Human
+
+Click through the visible paths and actually attempt real tasks — a first-time user explores, makes
+mistakes, and tries the obvious thing. Cover at least these dimensions unless the user narrows scope:
+
+- **Comprehension & labeling:** machine-style or developer labels shown to users (raw IDs, enum keys,
+  `snake_case`, `null`/`undefined`, untranslated i18n keys), jargon, unclear button/menu names, icons
+  with no discernible meaning.
+- **Navigation clarity:** is it obvious how to get somewhere and back? Dead ends, hidden entry points,
+  surprising redirects, broken links, no clear "home".
+- **Visual/layout quality:** cut-off or truncated text, overlap, cramped/crowded density, offscreen or
+  unreachable controls, accidental horizontal scroll, awkward empty space.
+- **Consistency / standard UX:** components, spacing, button styles, terminology, and interaction
+  patterns should be consistent across the app and follow common conventions. Flag anything
+  non-standard or that differs screen-to-screen.
+- **Load & responsiveness:** long or unclear load times, blank screens, spinners / `Loading...` /
+  `Connecting...` with no progress, anything that feels slow or janky.
+- **Scroll behavior:** unexpected scroll position, scroll jumps, nested or locked scroll, sticky
+  elements that cover content, content that cannot be reached.
+- **Behavior correctness:** does the obvious action do what a user expects? Confusing errors, silent
+  failures, disabled controls with no explanation, state that does not persist.
+- **Affordance clarity:** can the user tell what is clickable, required, in-progress, or complete?
+
+### 4. Cover All Breakpoints
+
+- Discover breakpoints from the app (design tokens, CSS, responsive layout changes) when possible; if
+  unknown, use a practical baseline: phone, tablet/narrow, desktop, plus any app-specific cutoff.
+- At each breakpoint, walk the key paths again and confirm the experience holds: expected
+  shell/navigation variant, critical controls visible and reachable, no unintended horizontal
+  overflow, intentional scroll containers still usable, nothing cut off or crowded.
+
+### 5. Watch Load & Latency
+
+- Notice time to first meaningful content and time spent in blank/loading/spinner/connecting states.
+- A page can be technically interactive but still visually incomplete — note that.
+- Treat long waits without clear progress, error, retry, or cancellation as findings. Use practical
+  labels (noticeable, slow, unacceptable) and include observed durations when available.
+
+## Mutation Discipline
+
+A real first-time user creates, edits, and deletes things — exercise those flows when the environment
+is safe.
+
+- Use unique names with a clear prefix such as `qa-` or `codex-`.
+- Before mutating, identify the cleanup path. After mutating, make a best effort to clean up through
+  the UI, then verify cleanup. If UI cleanup is unavailable, that itself is a usability finding.
+- Avoid destructive bulk actions unless the user explicitly asks or the account is clearly disposable.
+- Record all mutations performed, cleanup attempts, and any residue left behind.
+
+## Filing findings as tracked work
+
+This skill does **not** write a report file. Every finding becomes a **leaf work item** created via
+`lisa:tracker-write` (the vendor-neutral writer — it dispatches to the configured tracker and runs the
+validation gate; never call a vendor `*-write-*` skill directly). Map each finding to a type:
+
+| Finding | `issue_type` | `build_ready` |
+|---------|--------------|---------------|
+| User-visible **bug** (broken behavior) | `Bug` | the `ready` flag (default `false`) |
+| **Usability / UX / clarity issue** | `Improvement` | the `ready` flag (default `false`) |
+
+Each finding is a flat leaf (no children), so `build_ready` applies directly — pass it explicitly on
+every create. Each ticket MUST be a complete spec (the validator rejects thin tickets):
+
+- **Three-audience description** (context / business value, technical approach, stakeholder impact).
+- **For a bug:** exact reproduction steps, observed-vs-expected, the env / account / breakpoint it
+  occurred at, and console/network evidence.
+- **For a usability issue:** the observed friction (what was confusing, cramped, inconsistent, or hard
+  to understand), who it affects, **where** (route + breakpoint), and the proposed improvement.
+- **Gherkin acceptance criteria** describing the fixed behavior.
+
+### Idempotency — don't spam duplicates
+
+Re-running a pass must not refile the same finding. Before creating a ticket, search the tracker for an
+**open** ticket carrying a stable marker `[lisa-exploratory-qa] <finding-key>` in its body (the
+`<finding-key>` is a stable slug of surface + symptom, e.g. `settings-modal/horizontal-overflow@tablet`).
+If one exists, reference/update it instead of creating a duplicate; only create when none exists.
+**Match by the marker, never by title** (titles get edited). A *closed* prior ticket does not suppress a
+new one — a recurrence after a fix is a genuine regression.
+
+## Output
+
+No report file. Emit a concise in-session summary:
+
+- **Scope:** target URL/env, browser/tool, account type, build/version if visible, date.
+- **First impression:** could a new user tell what the app is and what to do first?
+- **Findings filed**, bucketed by type — bugs, usability/clarity issues — each with its **created or
+  referenced ticket ref** and its **build-ready state** (`ready` vs `triage/backlog`).
+- **Observed but not filed:** anything noticed but intentionally not ticketed, with why.
+
+## Quality Bar
+
+- Explore as a true first-time user — judge clarity, not whether you (who can read the code) can figure
+  it out.
+- Prefer concrete, reproducible findings. Every ticket must stand alone for an implementer who was not
+  in the session.
+- Do not claim cleanup succeeded unless verified.
+- File tickets per the `ready` flag (default: backlog for human triage).
+- This skill is about the human experience only — route automated-coverage gaps to `e2e-coverage-gaps`.
+- Preserve unrelated repo changes.

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

@@ -0,0 +1,35 @@
+{
+  "name": "lisa-harper-fabric",
+  "version": "2.122.0",
+  "description": "Harper/Fabric-specific rules for TypeScript component apps",
+  "author": {
+    "name": "Cody Swann"
+  },
+  "dependencies": [
+    "lisa-typescript"
+  ],
+  "hooks": {
+    "sessionStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ],
+    "subagentStart": [
+      {
+        "matcher": "",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/hooks/inject-rules.sh"
+          }
+        ]
+      }
+    ]
+  }
+}

package/plugins/lisa-harper-fabric-copilot/commands/e2e-coverage-gaps.md

@@ -0,0 +1,7 @@
+---
+description: "Explore gaps in the automated Playwright/e2e suite: inventory the app's routes and existing tests, find routes with no coverage or flows tested only on the happy path (missing error, permission, empty, loading, and edge cases), confirm each in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write. The optional ready flag (default true) controls build-ready vs backlog. For human usability issues, use exploratory-qa instead."
+allowed-tools: ["Skill"]
+argument-hint: "[target-url | env] [ready=true|false]"
+---
+
+Use the /lisa-harper-fabric:e2e-coverage-gaps skill to inventory the app's routes and the existing Playwright suite, find uncovered and happy-path-only paths, confirm each gap in the running app, and file one build-ready missing-test ticket per gap via lisa:tracker-write (build-ready per the ready flag, default true). For human usability/experience findings, use /lisa-harper-fabric:exploratory-qa. $ARGUMENTS