@codyswann/lisa 2.121.1 → 2.123.0

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

@@ -0,0 +1,11 @@
+{
+  "name": "lisa-harper-fabric",
+  "version": "2.123.0",
+  "description": "Harper/Fabric-specific rules for TypeScript component apps",
+  "author": {
+    "name": "Cody Swann"
+  },
+  "dependencies": [
+    "lisa-typescript"
+  ]
+}

package/plugins/lisa-harper-fabric-cursor/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

package/plugins/lisa-harper-fabric-cursor/commands/exploratory-qa.md

@@ -0,0 +1,7 @@
+---
+description: "Run a first-time-user exploratory QA walkthrough: experience the app like a brand-new human user, clicking through to find anything confusing, broken, or hard to understand (machine-style labels, slow or unclear loads, cramped or cut-off UI, inconsistent UX, awkward scroll behavior) across all breakpoints, and file each finding (bug or usability issue) as a tracked work item via lisa:tracker-write. The optional ready flag marks tickets build-ready (auto-picked-up by lisa:intake) or leaves them in the backlog for human triage (default). For gaps in the automated Playwright suite, use e2e-coverage-gaps instead."
+allowed-tools: ["Skill"]
+argument-hint: "[target-url | env] [ready=true|false]"
+---
+
+Use the /lisa-harper-fabric:exploratory-qa skill to experience the app like a brand-new first-time user — landing cold on the home page and clicking through to find anything confusing, broken, or hard to understand across all breakpoints — and file each finding (bugs, usability/clarity issues) as a tracked work item via lisa:tracker-write, build-ready or in triage per the ready flag (default: triage). For automated Playwright coverage gaps, use /lisa-harper-fabric:e2e-coverage-gaps. $ARGUMENTS

package/plugins/lisa-harper-fabric-cursor/rules/harper-fabric.md

@@ -0,0 +1,51 @@
+# Harper/Fabric Project Rules
+
+These rules apply to Harper/Fabric component apps managed by Lisa.
+
+## Build The Real Thing
+
+- Do not ship client-side workarounds for missing backend behavior. If a change needs a Harper resource, schema update, seed path, or deploy script change, make that change.
+- Do not silently downgrade a feature to a stub, mock, or partial path. Only use a stop-gap when the user explicitly asks for one.
+- Treat deployed Fabric behavior as part of the product. A change is unfinished until the local build and the relevant deployed or smoke path agree.
+
+## TypeScript Is Source
+
+- TypeScript under `src/` is the source of truth for Harper resources, browser modules, shared libraries, and operational scripts.
+- `harper-app/config.yaml`, `harper-app/schema.graphql`, HTML, CSS, docs, and research fixtures are source assets.
+- `harper-app/resources.js` and `harper-app/web/**/*.js` are generated deploy artifacts. Never edit them directly; change the matching TypeScript and run `bun run build`.
+- Deployment, bootstrap, smoke, seed, verify, preview, token, crawl, ingest, and extraction commands must run from compiled JavaScript or generated Harper assets, not stale checked-in JavaScript.
+
+## Harper/Fabric Deploy Surface
+
+- A deployable Harper app must keep `config.yaml`, `schema.graphql`, `resources.js`, and `web/**` at the component root that Fabric packages.
+- Build before symlinking, packaging, or deploying `harper-app/`.
+- Keep runtime secrets out of tracked files. Prefer environment variables or OS keychain helpers; document secret locations without recording secret values.
+- When discovering a Harper/Fabric limitation or workaround, document the symptom, root cause, fix, and tempting broken alternatives in the project runbook.
+
+## Documentation Sync
+
+- Project docs are operational contracts. When commands, schema, deploy shape, data model, seeded-data summary, crawler behavior, credential handling, or UI components change, update the matching project doc in the same change.
+- Harper schema changes must update the conceptual schema docs and any verify paths that assert joins or row counts.
+- Deploy topology, credential rotation, generated-artifact layout, and Fabric workarounds belong in the Fabric runbook.
+- UI component, token, variant, or design-system changes must update the design-system catalog.
+
+## UI Work
+
+- Browser UI must be composed from the project design system. Search the existing design-system catalog and components before adding markup.
+- Add or extend the design-system component first, then consume it from pages.
+- Pages should import UI components through the design-system barrel, not deep component paths.
+- Do not introduce raw colors or ad hoc spacing in UI styles. Use design tokens and update the token docs when adding tokens.
+- Every UI change needs Playwright verification that checks DOM behavior and captures screenshots. Type checks and unit tests are not enough for visual changes.
+
+## Immutable Code
+
+- Prefer immutable data flow: `readonly` types, pure transformations, object/array copies, and explicit returned values.
+- Do not mutate parameters, imported singletons, fixture objects, records, arrays, DOM-derived state, or config objects unless an API requires mutation and the exception is documented locally.
+- Avoid `let`; use `const` and small pure helper functions instead.
+- Avoid `any`, broad casts, and `ts-ignore`. If an external API forces an escape hatch, isolate it behind a typed adapter.
+
+## Verification
+
+- Run `bun run build`, `bun run typecheck`, and the smallest relevant test command before reporting completion.
+- For deploy-affecting changes, also run the project smoke command against the local or deployed Harper endpoint.
+- If a verification command cannot run, report the exact command and blocker.

package/plugins/lisa-harper-fabric-cursor/skills/e2e-coverage-gaps/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: e2e-coverage-gaps
+description: Playwright/e2e coverage-gap explorer that FEEDS THE LIFECYCLE. Use when asked to find paths the automated end-to-end suite does NOT cover — routes with no test at all, or flows that are only happy-path tested (missing error, validation, permission, empty, loading, and edge states). It inventories the app's routes and the existing Playwright tests, explores the running app to confirm each uncovered or under-covered path is real and reachable, and files one build-ready missing-test ticket per gap via lisa:tracker-write. For human usability/experience issues (confusing, cramped, or broken UI), use the exploratory-qa skill instead.
+---
+
+# E2E Coverage Gaps
+
+## Overview
+
+Find where the automated end-to-end (Playwright) suite is **blind**: routes with no test at all, and
+flows that only assert the **happy path** while ignoring error, permission, empty, loading, and edge
+cases. Inventory the app's routes and the existing tests, explore the running app to confirm each gap
+is real and reachable, then file each gap as a **build-ready missing-test work item** so it enters the
+Lisa lifecycle.
+
+This skill is purely about **automated-coverage gaps**. It does not judge whether the UI is confusing
+or pretty — for human usability findings, use the `exploratory-qa` skill.
+
+## Parameters
+
+- **`target-url | env`** (first positional) — the app to inventory and explore.
+- **`ready=true|false`** — build-ready state for the missing-test tickets (**default `true`**). Adding
+  missing coverage is safe to queue, so these default to build-ready; pass `ready=false` to leave them
+  in the backlog for human triage.
+
+## Core Workflow
+
+### 1. Establish Scope
+
+- Identify the target environment, account type, and browser requirement, and read the `ready` flag
+  (default `true`).
+- **Confirm the tracker is configured.** Gaps 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 gaps can be filed.
+
+### 2. Inventory App Routes
+
+- Enumerate every route/screen from the project's routing source — filesystem routes, the router
+  config, navigation definitions, or a generated sitemap.
+- For each route capture: its path + params, the auth/role it requires, and the primary user actions
+  reachable from it (forms, mutations, filters, flows).
+
+### 3. Inventory Existing Playwright Coverage
+
+- Inspect the Playwright config, auth/setup projects, fixtures, constants, selectors, spec directories,
+  skipped/TODO/flaky tests, retries, and viewport/device projects.
+- For each spec, record which route(s)/flow(s) it exercises and whether it asserts **behavior** or just
+  **presence**.
+- Use existing test helpers/selectors when exploring — they reveal intended flows and stable hooks.
+
+### 4. Compute the Gap Matrix
+
+Map routes/flows against existing coverage and classify each gap:
+
+- **Uncovered route/flow:** no test touches it at all.
+- **Happy-path-only:** the success case is tested but the non-happy paths are not — missing
+  error/validation, permission/denied, empty/zero-state, loading/slow, and boundary/edge scenarios.
+- **Assertion-thin:** a test exists but asserts presence rather than behavior/outcome.
+- **Skipped/TODO/flaky:** coverage exists but is disabled or unreliable.
+- **Breakpoint gap:** a flow is only tested at a single viewport when behavior changes across
+  breakpoints.
+
+### 5. Explore to Confirm
+
+- Navigate each candidate gap in the running app to confirm it is real, reachable, and worth a test.
+  Discard gaps that aren't actually reachable or are intentionally out of scope.
+
+### 6. File One Ticket Per Gap
+
+Each confirmed gap becomes a leaf **missing-test** 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), `issue_type: Task`, **build-ready per the `ready` flag
+(default `true`)**. Pass `build_ready` explicitly on every create. Each ticket MUST specify:
+
+- The **route/flow** and the exact **user behavior the test must assert**.
+- **Which scenario is missing** (uncovered vs which non-happy path: error / validation / permission /
+  empty / loading / edge / breakpoint).
+- The **stable selector / fixture / flow** to use — concrete and automatable.
+- **Three-audience description** + **Gherkin acceptance criteria** describing the test to add.
+
+### Idempotency — don't spam duplicates
+
+Before creating a ticket, search the tracker for an **open** ticket carrying a stable marker
+`[lisa-e2e-coverage-gaps] <gap-key>` in its body (the `<gap-key>` is a stable slug of route + missing
+scenario, e.g. `checkout/payment-declined` or `dashboard/empty-state@mobile`). If one exists, reference
+it instead of duplicating. **Match by the marker, never by title.** A *closed* prior ticket does not
+suppress a genuine new gap.
+
+## Output
+
+No report file. Emit a concise in-session summary:
+
+- **Route inventory:** count of routes/screens discovered.
+- **Existing coverage:** strengths and thin areas (skipped/flaky, assertion-thin, single-viewport).
+- **Gap matrix:** uncovered vs happy-path-only vs breakpoint gaps.
+- **Tickets filed:** each gap with its created/referenced ticket ref and build-ready state.
+
+## Quality Bar
+
+- Distinguish **no coverage** from **happy-path-only** — both are gaps, but the ticket must say which.
+- Every ticket must stand alone for an implementer who was not in the session and must be concretely
+  automatable (named route, behavior, and stable hook).
+- Do not refile gaps already covered or already ticketed (marker check).
+- This skill is about automated coverage only — route human usability issues to `exploratory-qa`.
+- Preserve unrelated repo changes.

package/plugins/lisa-harper-fabric-cursor/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-cursor/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/)