@codyswann/lisa 2.121.1 → 2.122.0

package/plugins/lisa-harper-fabric-copilot/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-copilot/hooks/inject-rules.sh

@@ -0,0 +1,16 @@
+#!/usr/bin/env bash
+# Reads all .md files from the plugin's rules/ directory and injects them
+# into Claude context at session/subagent start.
+set -euo pipefail
+
+ROOT="${CLAUDE_PLUGIN_ROOT:-${CODEX_PLUGIN_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}}"
+RULES_DIR="$ROOT/rules"
+
+[ -d "$RULES_DIR" ] || exit 0
+
+for rule in "$RULES_DIR"/*.md; do
+  [ -f "$rule" ] || continue
+  printf '\n<lisa-harper-fabric-rule path="%s">\n' "$rule"
+  cat "$rule"
+  printf '\n</lisa-harper-fabric-rule>\n'
+done

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