@genesislcap/genx 15.23.3 → 15.24.0-FUI-2603.10

package/README.md

@@ -26,6 +26,39 @@ To enable this module in your application, follow the steps below.
 
 ## [API Docs](./docs/api/index.md)
 
+## Agent rules
+
+`genx agent-rules` installs the shared AI agent rules that ship with this package
+([`agent-rules/`](./agent-rules)) into a consumer project, and wires them into whichever assistants
+that project uses.
+
+```bash
+npx genx agent-rules                                  # install and wire up detected assistants
+npx genx agent-rules ..                               # target another folder (see below)
+npx genx agent-rules --tools claude,cursor,gemini     # wire up specific assistants
+npx genx agent-rules --check                          # CI: fail when installed rules are stale
+```
+
+`[folder]` defaults to the current directory, and it should be the folder the assistants read -
+usually the repo root. In a Genesis app that is one level **above** `client/`, where `package.json`
+lives, so run `npx genx agent-rules ..` from `client/`. Run bare in a folder with no assistant
+files, the command looks up the tree as far as the repo root and, if it finds the real root, points
+at it and writes nothing rather than leaving an orphaned second copy behind (`--tools` installs in
+the current folder anyway).
+
+The rule markdown is copied to `docs/agent-rules/` and referenced from a managed block in
+`CLAUDE.md`, `GEMINI.md`, or `AGENTS.md`, and from a generated `.cursor/rules/<rule>.mdc` for
+Cursor. Content outside the managed block is never touched. Installed copies are managed — re-run
+the command after `genx upgrade` to pick up rule changes, and propose edits in
+[foundation-ui](https://github.com/genesislcap/foundation-ui) rather than locally.
+
+Currently shipped:
+
+| Rule | Purpose |
+| --- | --- |
+| `report-upstream-bug.md` | Something **broken** upstream: file a bug in `genesislcap/foundation-ui` — with the human's confirmation — instead of quietly working around it in the consumer project. |
+| `propose-upstream-feature.md` | Something **missing** upstream: propose the capability instead of building the fifth private copy of it. Includes a generality test so app code stays app code. |
+
 ## Event type codegen
 
 When `eventTypes.enabled` is set in `genx.config.*` or `package.json` (`genx` / `genesis` keys), `genx build` and `genx generate event-types` emit typed `EventDetailsMap` from Kotlin handler DTOs and generated table DAOs. See [@genesislcap/event-type-codegen](../event-type-codegen/README.md) for configuration, limitations, and migration.

package/agent-rules/manifest.json

@@ -0,0 +1,20 @@
+{
+  "version": 1,
+  "targetDir": "docs/agent-rules",
+  "rules": [
+    {
+      "file": "report-upstream-bug.md",
+      "name": "report-upstream-bug",
+      "title": "Report Foundation UI bugs upstream",
+      "description": "File a bug upstream in genesislcap/foundation-ui instead of working around it locally. Use whenever a defect is traced into a @genesislcap/* package - a stack frame in node_modules/@genesislcap, or behaviour contradicting the package's docs or types - or before writing any monkey-patch, patch-package entry, vendored copy, version pin, or cast that exists to route around upstream behaviour.",
+      "cursorDescription": "Use when a bug is traced into a @genesislcap package, when weighing a workaround for upstream behaviour, or before patching node_modules or pinning a @genesislcap version."
+    },
+    {
+      "file": "propose-upstream-feature.md",
+      "name": "propose-upstream-feature",
+      "title": "Propose platform features upstream",
+      "description": "Propose a missing platform capability in genesislcap/foundation-ui instead of building the fifth private copy of it. Use before building a generic component, formatter, or adapter with no business rules in it, before wrapping or re-implementing a @genesislcap/* component that lacks one option, or when the same thing has already been built in another Genesis app.",
+      "cursorDescription": "Use before building a generic component, utility, or adapter that has no business rules in it, when extending a @genesislcap component that lacks an option, or when the same capability already exists privately in another Genesis app."
+    }
+  ]
+}

package/agent-rules/propose-upstream-feature.md

@@ -0,0 +1,219 @@
+<!-- Managed by `genx agent-rules` (@genesislcap/genx). Do not edit this copy — it is overwritten on every run. Propose changes in genesislcap/foundation-ui. -->
+
+# Propose platform features upstream (don't build the fifth private copy)
+
+> **Purpose**: Some of what a Genesis app needs is app-specific, and some of it is platform
+> capability that simply hasn't been built yet. The second kind gets built privately in one app,
+> then again in the next, and every copy has to be maintained against upstream API changes forever.
+> This rule catches that at the moment of writing: if the thing belongs in a `@genesislcap/*`
+> package, it gets proposed in
+> [`genesislcap/foundation-ui`](https://github.com/genesislcap/foundation-ui) — and only then, with
+> approval, built locally as a temporary seam.
+>
+> The sibling rule for defects is `report-upstream-bug.md`. Something that is *broken* upstream is a
+> bug; something that is *missing* upstream is this rule.
+
+## When this rule applies
+
+Apply it before writing code, as soon as any of these is true:
+
+- You are about to build a generic capability — a UI component, a formatter, a datasource or grid
+  adapter, an auth/comms/layout concern — with no business rules in it.
+- You are extending an existing `@genesislcap/*` component by wrapping, subclassing, or
+  re-implementing it, because it lacks one attribute, slot, event, or option.
+- Someone says "we built this in the other app" or you can see code copied in from another Genesis
+  project.
+- The thing would have to track an upstream API to keep working — a private fork of platform
+  behaviour rather than a consumer of it.
+- Upstream documents or types the capability partially and you are filling the gap locally.
+
+It does **not** apply to app code, and most code is app code:
+
+- Business rules, pricing, workflow, entitlements, domain validation.
+- Client-specific branding, copy, layout, or one-off screens.
+- Anything whose API you cannot describe without this app's domain nouns.
+- Spikes and prototypes you intend to delete.
+- Work under a deadline where waiting on upstream is not an option — build it locally now, and
+  propose it in parallel (Step 6 covers the seam).
+
+## Non-negotiables
+
+1. **Apply the generality test in Step 2 before proposing anything.** A proposal for app-specific
+   code wastes the platform team's time and teaches them to ignore the next one.
+2. **Never** run `gh issue create` unprompted. Draft the proposal, show it to the human, wait for a
+   clear yes. Filing is an outward-facing action on a shared repo.
+3. **Never** fork or vendor an upstream component to change a few lines without approval — propose
+   the option upstream and wrap locally instead.
+4. **Building the local version needs explicit human approval** (Step 6), like any workaround.
+5. **Don't overclaim demand.** "Two apps need this" is only true if you can name them.
+
+---
+
+## Step 1 — Check it doesn't already exist
+
+Platform surface is large and under-documented; assume it might already be there.
+
+```bash
+# Search the installed packages' public types for the capability.
+grep -rl "<CapabilityName>" node_modules/@genesislcap/*/dist/dts 2>/dev/null | head
+
+# What does the package actually export?
+cat node_modules/@genesislcap/<pkg>/dist/dts/index.d.ts | grep -i "<keyword>"
+
+# Newer versions may already have it.
+npm view @genesislcap/<pkg> version
+npm view @genesislcap/<pkg> dist-tags
+```
+
+Also check the package's `README.md` and `docs/api/` inside `node_modules`, and the showcase apps
+if you have the monorepo to hand. If it exists, use it and stop here.
+
+## Step 2 — Apply the generality test
+
+Answer all four. Any "no" means it is app code: build it locally and stop.
+
+1. **Name two independent consumers.** Two real projects or teams that would use this, not two
+   screens in this app.
+2. **Describe the API without this app's domain nouns.** If the signature needs
+   `Trade`, `Counterparty`, or your client's name to make sense, it is not platform capability.
+3. **No app-specific dependencies.** It must not reach into this app's services, routes, config
+   shape, or backend contract.
+4. **The behaviour is stable, not still being discovered.** If the design is likely to change twice
+   more this sprint, it is not ready to be someone else's API.
+
+Borderline cases exist. When it half-passes, the honest proposal is usually smaller than the thing
+you were about to build: a new attribute, slot, event, or option on an existing component rather
+than a new component.
+
+## Step 3 — Check it isn't already proposed
+
+```bash
+gh issue list --repo genesislcap/foundation-ui --state all --search "<keywords>" --limit 20
+gh pr list --repo genesislcap/foundation-ui --state all --search "<keywords>" --limit 20
+```
+
+- **An open issue matches** → add your use case and your second consumer to it, after the human
+  approves. That is worth more to the platform team than a duplicate: it is evidence of demand.
+- **A closed issue matches** → read why. If it was declined, respect the decision and build locally
+  (Step 6); the reasoning usually tells you what shape *would* be accepted.
+- **A merged PR matches** → it may be released already, or available on a pre-release dist-tag.
+
+## Step 4 — Decide the shape, smallest first
+
+Pick the least invasive option that solves it, and say in the proposal which you chose and why:
+
+| Shape | Use when | Cost to upstream |
+| --- | --- | --- |
+| New attribute / slot / event / option on an existing component | The component does 90% of it | Lowest — usually additive and non-breaking |
+| New export from an existing package | It is a utility, formatter, or type that fits a package's remit | Low |
+| New component in an existing package | It is a peer of what that package already ships | Medium |
+| New package | Nothing existing has the remit | Highest — expect to justify it |
+
+Additive and backward-compatible beats elegant-but-breaking. If your idea only works as a breaking
+change, say so explicitly and expect it to be scheduled rather than accepted outright.
+
+## Step 5 — Draft the proposal, then file it once the human confirms
+
+Title: what the capability is, in the platform's vocabulary — not your app's.
+
+- Good: `grid-pro: expose a column-level formatter hook for cell values`
+- Bad: `Need to format trade dates in the blotter`
+
+Body:
+
+````markdown
+## What's missing
+
+One paragraph: the capability, and where it would live (`@genesislcap/<pkg>`, ideally the exact
+component or module).
+
+## Who needs it
+
+The projects or teams that would use this, named. If it has already been built privately more
+than once, say where — a duplicated implementation is the strongest argument for adopting it.
+
+## What we do today
+
+The local implementation or workaround, with its cost: lines of code, what it forks, what breaks
+when upstream changes.
+
+## Proposed API
+
+```ts
+// The smallest shape that solves it — attribute, option, export, or signature.
+```
+
+Include the default, and confirm existing behaviour is unchanged when the new option is absent.
+
+## Alternatives considered
+
+Including "keep it app-side", and why that loses.
+
+## Breaking change?
+
+No / yes, with the migration if yes.
+
+## Can we contribute it?
+
+Whether this team can raise the PR, and by when.
+````
+
+Then, after an explicit yes — with the body in a relative file, so this works on Windows too, and
+deleted afterwards rather than committed:
+
+```bash
+gh issue create \
+  --repo genesislcap/foundation-ui \
+  --title "<title>" \
+  --body-file temp-upstream-proposal.md \
+  --label "Enhancement" \
+  --label "<area label>"
+```
+
+Use `gh label list --repo genesislcap/foundation-ui --limit 100` for the area label — the same
+areas as the bug rule (`Grids`, `COMMS`, `Design System`, `Forms`, `Layout`,
+`Frontends Compatibility`, …). Add `Next` when it is capability the platform is expected to grow
+into rather than something needed this sprint. Delete the temp file, then report the URL.
+
+## Step 6 — Build locally as a seam, with approval
+
+A filed proposal does not ship your feature. Once the issue URL exists:
+
+1. **Present the options and their costs** — build behind a local seam now, wait for upstream, or
+   contribute the PR yourself and consume a pre-release. Include "wait" when it is viable.
+2. **Wait for an explicit choice.** Do not start editing before that.
+3. **Once approved**, build it so it can be deleted rather than untangled:
+   - Keep it behind **one boundary** — an adapter, a wrapper component, a single module the app
+     imports from. When upstream lands, one file changes, not thirty call sites.
+   - Match the proposed upstream API, so adopting the real thing is an import swap.
+   - Mark it with the issue and the removal condition:
+
+     ```ts
+     // UPSTREAM-CANDIDATE(genesislcap/foundation-ui#2501):
+     // Column-level value formatter; grid-pro has no hook for this yet.
+     // Remove when: the hook ships in @genesislcap/grid-pro and this app adopts it.
+     ```
+
+4. **Log it** in the shared tracking file (create it if absent — `docs/upstream-tracking.md`):
+
+   ````markdown
+   | Kind | Issue | Package | What we do locally | Remove when |
+   | --- | --- | --- | --- | --- |
+   | feature | genesislcap/foundation-ui#2501 | grid-pro | local formatter adapter | hook released and adopted |
+   ````
+
+## Step 7 — Offer the PR
+
+Proposals with a PR attached land far sooner than proposals without one, and you have already
+written the implementation once. `foundation-ui` accepts contributions from consumer teams — see its
+[CONTRIBUTING.md](https://github.com/genesislcap/foundation-ui/blob/master/CONTRIBUTING.md) for
+setup, commit format, and the PR template. A pre-release can be cut from the branch so this app can
+adopt it before it merges (`@genesislcap/<pkg>@<dist-tag>`); ask in the issue.
+
+## Never
+
+- Propose app business logic as platform capability.
+- Fork or vendor an upstream component to change a few lines instead of proposing the option.
+- Claim demand you cannot name, or a use case you have not built.
+- Design an API around this app's backend contract and present it as generic.
+- Leave the local implementation as the only record — the marker must name the issue.

package/agent-rules/report-upstream-bug.md

@@ -0,0 +1,253 @@
+<!-- Managed by `genx agent-rules` (@genesislcap/genx). Do not edit this copy — it is overwritten on every run. Propose changes in genesislcap/foundation-ui. -->
+
+# Report Foundation UI bugs upstream (don't silently work around them)
+
+> **Purpose**: When a bug in this project turns out to live inside a `@genesislcap/*` package,
+> the fix belongs in [`genesislcap/foundation-ui`](https://github.com/genesislcap/foundation-ui),
+> not in a local patch. A workaround that is never reported keeps every other consumer project
+> broken and quietly becomes permanent. This rule makes "raise it upstream" the default path and
+> a local workaround the deliberate, approved, clearly-marked exception.
+>
+> The sibling rule for missing capability is `propose-upstream-feature.md`. Something that is
+> *broken* upstream is this rule; something that is *missing* upstream is that one.
+
+## When this rule applies
+
+Apply it as soon as any of these is true:
+
+- A stack frame, breakpoint, or console error points into `node_modules/@genesislcap/**`.
+- The behaviour of a `@genesislcap/*` package contradicts its own docs, types, JSDoc, or
+  README — including a `CustomEvent<unknown>` where a typed detail is documented.
+- You are about to write, or have caught yourself considering, any of these:
+  - a monkey-patch, prototype override, or `patch-package` entry against a `@genesislcap/*` package;
+  - a copy of an upstream component/function into this repo so a few lines can be changed;
+  - `as any` / `@ts-expect-error` / `// eslint-disable` purely to route around a wrong upstream type;
+  - a CSS override fighting an upstream style (`!important` into a shadow part, etc.);
+  - pinning or downgrading a `@genesislcap/*` version to dodge a regression;
+  - a `setTimeout`, extra re-render, retry, or "nudge" that exists only to compensate for
+    upstream timing.
+
+It does **not** apply when the cause is on this side: wrong usage of a documented API, a version
+mismatch between `@genesislcap/*` packages, missing peer dependencies, or local configuration.
+Step 1 exists to tell those apart.
+
+## Non-negotiables
+
+1. **The upstream issue is filed before local code is changed** to route around the bug.
+2. **Never** modify anything under `node_modules/` (or add a `patch-package` patch, or vendor a
+   copy of upstream source) without explicit human approval.
+3. **Never** run `gh issue create` unprompted. Draft the issue, show it to the human, wait for a
+   clear yes, then file it. Filing an issue is an outward-facing action on a shared repo.
+4. **Any workaround needs explicit human approval** — present the options and the trade-offs, do
+   not pick one and start editing (see Step 6).
+5. **Be honest about what you verified.** Separate "confirmed by running it" from "suspected".
+   A confidently-wrong root cause wastes more upstream time than no root cause at all.
+
+---
+
+## Step 1 — Rule out the boring causes
+
+Do this before writing a single line of the issue.
+
+```bash
+# What is actually installed (the lockfile, not the range in package.json)?
+npm ls @genesislcap/<package>            # or: pnpm why @genesislcap/<package>
+
+# Is it the latest? Is there a newer patch or a prerelease dist-tag?
+npm view @genesislcap/<package> version
+npm view @genesislcap/<package> dist-tags
+
+# Are the @genesislcap/* packages on matching versions? Mixed majors/minors cause
+# symptoms that look exactly like upstream bugs but are dependency drift.
+npm ls --all 2>/dev/null | grep @genesislcap
+```
+
+Then confirm the calling code follows the documented API — read the package's own `dist/dts/*.d.ts`
+and README rather than assuming. If the answer is "we were holding it wrong", fix it locally and
+stop here; this rule is done.
+
+## Step 2 — Check it isn't already known or already fixed
+
+```bash
+# Open AND closed issues — a closed one may name the release that fixed it.
+gh issue list --repo genesislcap/foundation-ui --state all --search "<keywords>" --limit 20
+
+# Same for PRs — a fix may be merged but not yet released.
+gh pr list --repo genesislcap/foundation-ui --state all --search "<keywords>" --limit 20
+```
+
+Outcomes:
+
+- **An open issue matches** → don't file a duplicate. Add a comment with your new evidence
+  (your version, your repro, your environment) after the human approves, and link it in your report.
+- **A closed issue matches and a newer version exists** → the fix is likely released. Recommend the
+  upgrade instead of an issue.
+- **Nothing matches** → continue to Step 3.
+
+## Step 3 — Collect the evidence
+
+An upstream maintainer needs to reproduce this without access to your app. Gather:
+
+| What | How |
+| --- | --- |
+| Root-cause package + exact version | The package the broken code lives in, e.g. `@genesislcap/foundation-comms@15.3.1` |
+| Symptom package + exact version | Where it *appears* to break, if different, e.g. `@genesislcap/grid-pro@15.3.1` |
+| The offending code | Real path + quoted snippet from `node_modules/@genesislcap/<pkg>/dist/...` |
+| Minimal reproduction | Numbered steps. Say plainly whether you executed them or are proposing them |
+| Expected vs actual | Both stated as observable behaviour, not as internal state |
+| Environment | Framework + version (React 19, Angular, etc.), bundler, browser, and relevant third-party versions (`ag-grid-community`, `@microsoft/fast-element`, …) |
+| Evidence | Console output, network/websocket trace, screenshots — trimmed to the relevant lines |
+| Workaround status | What unblocks the app today (even if it's "nothing yet") |
+
+Redact anything client-confidential: hostnames, credentials, real user data, and business-specific
+resource names. Replace them with placeholders (`SOME_DATASERVER_QUERY`) — a repro does not need
+them to be real.
+
+## Step 4 — Draft the issue
+
+Title: a specific, searchable one-liner that names the mechanism, not just the symptom. No
+conventional-commit prefix.
+
+- Good: `sendForStream() defers DATA_LOGON via DOM.queueUpdate — StrictMode double-mount discards it, leaving every dataserver grid empty`
+- Bad: `Grid is empty`
+
+Body — use this structure (it mirrors
+[#2442](https://github.com/genesislcap/foundation-ui/issues/2442), a good reference report):
+
+````markdown
+## Package + version
+
+Root cause: **`@genesislcap/<pkg>@<version>`**
+Visible symptom in: **`@genesislcap/<pkg>@<version>`** (if different)
+
+From the consumer's `package.json`:
+
+```
+"@genesislcap/<pkg>": "<version>"
+"<relevant third-party dep>": "<version>"
+```
+
+## Summary
+
+One paragraph: the mechanism and its user-visible consequence.
+
+## Reproduction
+
+State up front whether this was confirmed end-to-end or is a proposed reduction.
+
+1. …
+2. …
+3. Observe: …
+
+## Expected vs Actual
+
+**Expected**
+- …
+
+**Actual**
+- …
+
+## Root cause
+
+`<pkg>/dist/<path>`:
+
+```js
+// the offending snippet, quoted
+```
+
+Explain why this is wrong. If parts are inferred rather than observed, say so explicitly.
+
+## Impact
+
+Who and what is affected — one app, every consumer using this component, dev-only, production.
+
+## Workaround in place downstream
+
+What the consumer project is doing right now to stay unblocked, or "none".
+
+## Environment
+
+- Framework: …
+- Browser / Node: …
+- Other relevant versions: …
+````
+
+Show the draft to the human. Do not file it yet.
+
+## Step 5 — File it (after the human says yes)
+
+Write the body to a file in the project first — passing markdown inline mangles backticks and
+special characters. Keep the path relative so this works on Windows as well as macOS and Linux, and
+delete it afterwards rather than committing it:
+
+```bash
+gh issue create \
+  --repo genesislcap/foundation-ui \
+  --title "<title>" \
+  --body-file temp-upstream-issue.md \
+  --label "Bug" \
+  --label "<area label>"
+```
+
+Pick area labels from the repo's own list — `gh label list --repo genesislcap/foundation-ui --limit 100`.
+Common ones:
+
+| Area | Label |
+| --- | --- |
+| grid-pro, data-grid, rapid-grid-pro | `Grids` |
+| foundation-comms, datasources, websockets | `COMMS`, `Datasource` |
+| design system, FAST, rapid components | `Design System`, `Rapid` |
+| foundation-forms / criteria / filters | `Forms`, `Criteria` |
+| foundation-layout, golden/dynamic layout | `Layout` |
+| foundation-entity-management | `Entity Management` |
+| React/Angular/Vue wrappers, typings | `Frontends Compatibility` |
+| build, bundling, genx/CLI | `Build`, `Rollup & Webpack`, `CLI & GENX` |
+| production-blocking | `High Priority`, or `CRITICAL` if the app is down |
+
+Then delete the temp file, and report the issue URL back to the human.
+
+## Step 6 — Workaround: only after the issue exists, only with approval
+
+Filing the issue does not unblock this app. Once the issue URL exists:
+
+1. **Present the options**, with the cost of each — e.g. upgrade/downgrade, use a different
+   documented API, local subclass/override, wait for the upstream fix, `patch-package`.
+   Include "do nothing yet" when it is viable.
+2. **Wait for an explicit choice.** Do not start editing consumer code before that.
+3. **Once approved**, keep it minimal and make it self-deleting on upgrade:
+   - Mark every touched site with a marker comment carrying the issue URL and the removal condition:
+
+     ```ts
+     // UPSTREAM-WORKAROUND(genesislcap/foundation-ui#2442):
+     // foundation-comms defers DATA_LOGON via DOM.queueUpdate, so a StrictMode remount drops it.
+     // Remove when: @genesislcap/foundation-comms ships the fix (> 15.3.1) and this app upgrades.
+     ```
+
+   - Prefer wrapping over forking: a subclass, a decorator, or an adapter at one boundary beats a
+     vendored copy of upstream source scattered across the codebase.
+   - Never leave the workaround as the only record of the bug. The marker must name the issue.
+4. **Log it** in a single tracking file the team can grep at upgrade time, shared with the feature
+   rule (create it if absent — `docs/upstream-tracking.md`):
+
+   ````markdown
+   | Kind | Issue | Package + version | What we do locally | Remove when |
+   | --- | --- | --- | --- | --- |
+   | bug | genesislcap/foundation-ui#2442 | foundation-comms@15.3.1 | ... | fix released and adopted |
+   ````
+
+## Step 7 — Offer the upstream fix
+
+If the fix is small and you can see it, say so in the issue and offer a PR. `foundation-ui` accepts
+contributions from consumer teams — see its
+[CONTRIBUTING.md](https://github.com/genesislcap/foundation-ui/blob/master/CONTRIBUTING.md) for
+setup, commit format, and the PR template. A pre-release build can be cut from a branch so this app
+can validate the fix before it lands (`@genesislcap/<pkg>@<dist-tag>`); ask in the issue.
+
+## Never
+
+- Edit `node_modules/` directly, or add a `patch-package` patch, without approval — and never
+  without an issue link in the patch's commit message.
+- Present a suspected root cause as confirmed.
+- Paste client-confidential data (hostnames, credentials, real records) into a shared repo.
+- Delete, skip, or weaken a test to make an upstream bug invisible.
+- Ship a workaround with no marker comment and no issue reference.

package/dist/commands/agent-rules.d.ts

@@ -0,0 +1,6 @@
+declare const _default: (folder?: string, options?: {
+    tools?: string;
+    check?: boolean;
+}) => Promise<void>;
+export default _default;
+//# sourceMappingURL=agent-rules.d.ts.map

package/dist/commands/agent-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rules.d.ts","sourceRoot":"","sources":["../../src/commands/agent-rules.ts"],"names":[],"mappings":"yBAyCE,eAAsB,EACtB,UAAS;IAAE,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO;AAFnD,wBAkEE"}

package/dist/commands/agent-rules.js

@@ -0,0 +1,79 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const tslib_1 = require("tslib");
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const build_kit_1 = require("@genesislcap/build-kit");
+const consola_1 = tslib_1.__importDefault(require("consola"));
+const agent_rules_1 = require("../utils/agent-rules");
+/** The packaged rules live at the root of this package, alongside `bin` and `dist`. */
+const packagedRulesDir = () => (0, node_path_1.resolve)(__dirname, '../../agent-rules');
+const loadManifest = (rulesDir) => JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)(rulesDir, 'manifest.json'), 'utf8'));
+const readRuleContents = (rulesDir, manifest) => manifest.rules.reduce((contents, rule) => {
+    contents[rule.file] = (0, node_fs_1.readFileSync)((0, node_path_1.join)(rulesDir, rule.file), 'utf8');
+    return contents;
+}, {});
+const resolveTools = (dir, requested) => {
+    if (!requested) {
+        return (0, agent_rules_1.detectTools)(dir);
+    }
+    try {
+        return (0, agent_rules_1.parseTools)(requested);
+    }
+    catch (error) {
+        // A typo in --tools is a user error, not a bug: report it without a stack trace.
+        consola_1.default.error((0, agent_rules_1.errorMessage)(error));
+        process.exit(1);
+    }
+};
+exports.default = (...args_1) => tslib_1.__awaiter(void 0, [...args_1], void 0, function* (folder = process.cwd(), options = {}) {
+    const dir = (0, node_path_1.resolve)(folder);
+    const rulesDir = packagedRulesDir();
+    const manifest = loadManifest(rulesDir);
+    const ruleContents = readRuleContents(rulesDir, manifest);
+    const tools = resolveTools(dir, options.tools);
+    if (!tools.length && !options.tools) {
+        // Writing rule files into a package directory whose assistant files live higher up leaves an
+        // orphaned second copy behind, so point at the real root instead of quietly installing here.
+        const assistantRoot = (0, agent_rules_1.findAssistantRoot)(dir);
+        if (assistantRoot) {
+            consola_1.default.error(`No assistant detected in ${dir}, but ${assistantRoot} has one.`);
+            consola_1.default.info(`Run \`genx agent-rules ${assistantRoot}\` to install there instead.`);
+            consola_1.default.info('Pass --tools to install in this folder anyway.');
+            process.exit(1);
+        }
+        consola_1.default.warn(`No assistant detected in ${dir}. The rule files will be installed, but nothing will be wired up. Pass --tools claude,cursor,gemini,agents to wire one explicitly.`);
+    }
+    let planned;
+    try {
+        planned = (0, agent_rules_1.planFiles)(dir, manifest, tools, ruleContents, (path) => (0, node_fs_1.readFileSync)(path, 'utf8'));
+    }
+    catch (error) {
+        // A hand-mangled managed block is the user's to repair - we will not guess and overwrite prose.
+        consola_1.default.error((0, agent_rules_1.errorMessage)(error));
+        process.exit(1);
+    }
+    const drift = (0, agent_rules_1.findDrift)(dir, planned);
+    if (options.check) {
+        if (drift.length) {
+            consola_1.default.error(`Agent rules are out of date in ${dir}:`);
+            drift.forEach((file) => consola_1.default.log((0, build_kit_1.white)(`  ${(0, build_kit_1.bold)(file.path)} ${(0, node_fs_1.existsSync)((0, node_path_1.join)(dir, file.path)) ? 'differs' : 'missing'}`)));
+            consola_1.default.info('Run `genx agent-rules` to update.');
+            process.exit(1);
+        }
+        consola_1.default.success(`Agent rules are up to date (${manifest.rules.length} rule(s)).`);
+        return;
+    }
+    if (!drift.length) {
+        consola_1.default.info('Agent rules already up to date. Nothing to do.');
+        return;
+    }
+    drift.forEach((file) => {
+        const path = (0, node_path_1.join)(dir, file.path);
+        (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(path), { recursive: true });
+        (0, node_fs_1.writeFileSync)(path, file.contents, 'utf8');
+        consola_1.default.log((0, build_kit_1.white)(`  ${(0, build_kit_1.bold)(file.path)}`));
+    });
+    consola_1.default.success(`Installed ${manifest.rules.length} agent rule(s)${tools.length ? ` for: ${tools.join(', ')}` : ''}.`);
+    consola_1.default.info('Commit the changes so the whole team gets them.');
+});

package/dist/commands/index.d.ts

@@ -1,4 +1,8 @@
 export declare const commands: {
+    agentRules: () => Promise<(folder?: string, options?: {
+        tools?: string;
+        check?: boolean;
+    }) => Promise<void>>;
     clean: () => Promise<(paths?: string[]) => Promise<void>>;
     generateEventTypes: () => Promise<(folder?: string, options?: {
         fromMetadata?: string;

package/dist/commands/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,QAAQ;;;oBAEI,CAAC;;;;;;;CAMzB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,QAAQ,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/commands/index.ts"],"names":[],"mappings":"AACA,eAAO,MAAM,QAAQ;;aAY2qB,CAAC;aAAe,CAAC;;;;oBAVlsB,CAAA;;;;;;;CAOd,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,MAAM,OAAO,QAAQ,CAAC"}

package/dist/commands/index.js

@@ -36,6 +36,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.commands = void 0;
 // lazy loading command definitions
 exports.commands = {
+    agentRules: () => Promise.resolve().then(() => __importStar(require('./agent-rules'))).then((r) => r.default),
     clean: () => Promise.resolve().then(() => __importStar(require('./clean'))).then((r) => r.default),
     generateEventTypes: () => Promise.resolve().then(() => __importStar(require('./generate-event-types'))).then((r) => r.default),
     run: () => Promise.resolve().then(() => __importStar(require('./run'))).then((r) => r.default),

package/dist/index.js

@@ -42,6 +42,23 @@ cli
     consola_1.consola.error(`Unknown generate type "${type}". Supported: event-types`);
     process.exit(1);
 }));
+cli
+    .command('agent-rules [folder]', 'Install shared AI agent rules into a project')
+    .option('-t, --tools <list>', 'Comma-separated assistants to wire: claude, cursor, gemini, agents (defaults to those detected)')
+    .option('-c, --check', 'Verify the installed rules are up to date, exit 1 otherwise (for CI)')
+    .action((folder, options) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {
+    const action = yield commands_1.commands.agentRules();
+    yield action(folder, options);
+})).example(`
+  ${(0, build_kit_1.bold)('genx agent-rules')}
+    Install the shared rules into docs/agent-rules and wire up every assistant detected in the project
+
+  ${(0, build_kit_1.bold)('genx agent-rules --tools claude,cursor')}
+    Wire up Claude Code and Cursor explicitly
+
+  ${(0, build_kit_1.bold)('genx agent-rules --check')}
+    Fail if the installed rules are missing or out of date (use in CI)
+`);
 cli
     .command('clean [...paths]', 'Delete specified paths (defaults to dist folder)')
     .action((paths) => tslib_1.__awaiter(void 0, void 0, void 0, function* () {

package/dist/utils/agent-rules.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Shareable agent rules are markdown files that ship with this package and are installed into a
+ * consumer project by `genx agent-rules`. The rule body is tool-agnostic; per-assistant wiring is
+ * generated from the manifest below.
+ */
+export interface AgentRule {
+    /** File name of the rule markdown, relative to the packaged `agent-rules` folder. */
+    file: string;
+    /** Slug used for generated file names, e.g. the Cursor `.mdc`. */
+    name: string;
+    /** Human readable title, used in logs and generated pointers. */
+    title: string;
+    /** When the rule applies. Used as the Claude skill / pointer description. */
+    description: string;
+    /** Cursor's trigger phrasing for the `.mdc` front matter. */
+    cursorDescription: string;
+}
+export interface AgentRulesManifest {
+    version: number;
+    /** Where the rule markdown is installed inside the consumer project. */
+    targetDir: string;
+    rules: AgentRule[];
+}
+export declare const AGENT_TOOLS: readonly ["claude", "cursor", "gemini", "agents"];
+export type AgentTool = (typeof AGENT_TOOLS)[number];
+/** Entry file each assistant reads, for the tools wired via a managed block. */
+export declare const TOOL_ENTRY_FILES: Record<Exclude<AgentTool, 'cursor'>, string>;
+export declare const MANAGED_BEGIN = "<!-- BEGIN genx agent-rules -->";
+export declare const MANAGED_END = "<!-- END genx agent-rules -->";
+export interface PlannedFile {
+    /** Path relative to the consumer project root. */
+    path: string;
+    contents: string;
+}
+export type ExistsFn = (path: string) => boolean;
+export type ReadFn = (path: string) => string;
+/**
+ * Narrowed message for a caught value. `catch` bindings are only typed loosely because this
+ * package has not enabled `useUnknownInCatchVariables` yet; don't rely on that staying true.
+ */
+export declare const errorMessage: (error: unknown) => string;
+/**
+ * Replaces the genx-managed block in `content`, or appends one when absent. Everything outside the
+ * markers is left alone — these files belong to the consumer project, not to us.
+ *
+ * Throws when the markers are malformed (an unpaired marker, `END` before `BEGIN`, or more than one
+ * pair). Every way of guessing what the author meant risks eating their prose: appending a second
+ * block leaves the file to be truncated by the *next* run, and treating an unpaired `BEGIN` as
+ * running to end-of-file discards whatever they wrote below it. Refusing to write is the only
+ * option that cannot lose someone's instructions.
+ */
+export declare const upsertManagedBlock: (content: string, body: string) => string;
+/** Import line understood by Claude Code (`CLAUDE.md`) and Gemini CLI (`GEMINI.md`). */
+export declare const renderImportBlock: (rules: AgentRule[], targetDir: string) => string;
+/** Plain pointer for assistants without an import syntax (AGENTS.md, Copilot, Windsurf, …). */
+export declare const renderPointerBlock: (rules: AgentRule[], targetDir: string) => string;
+/** A fully generated Cursor rule that defers to the shared markdown. */
+export declare const renderCursorRule: (rule: AgentRule, targetDir: string) => string;
+/**
+ * Which assistants a project already uses. Wiring an assistant nobody uses is just litter, so we
+ * only touch what we can see evidence of.
+ */
+export declare const detectTools: (dir: string, exists?: ExistsFn) => AgentTool[];
+/**
+ * The nearest ancestor of `dir` that looks like the project's assistant root, or `null`.
+ *
+ * Genesis apps keep `package.json` in `client/` while `CLAUDE.md` and friends sit at the repo
+ * root, so running the installer from the package directory would wire up nothing and leave a
+ * second, orphaned set of rule files behind. Walk up as far as the repo root looking for the
+ * directory the assistants actually read.
+ */
+export declare const findAssistantRoot: (dir: string, exists?: ExistsFn) => string | null;
+/** Parses and validates a `--tools` value. Throws on anything unknown rather than guessing. */
+export declare const parseTools: (value: string) => AgentTool[];
+/**
+ * Everything the command intends to write, as (path, contents) pairs. Kept separate from the
+ * writing itself so `--check` can compare against disk without touching it.
+ */
+export declare const planFiles: (dir: string, manifest: AgentRulesManifest, tools: AgentTool[], ruleContents: Record<string, string>, read: ReadFn, exists?: ExistsFn) => PlannedFile[];
+/** Planned files whose contents differ from what is on disk. */
+export declare const findDrift: (dir: string, planned: PlannedFile[], read?: ReadFn, exists?: ExistsFn) => PlannedFile[];
+//# sourceMappingURL=agent-rules.d.ts.map

package/dist/utils/agent-rules.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-rules.d.ts","sourceRoot":"","sources":["../../src/utils/agent-rules.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,kEAAkE;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,eAAO,MAAM,WAAW,mDAAoD,CAAC;AAC7E,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAC;AAErD,gFAAgF;AAChF,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,EAAE,QAAQ,CAAC,EAAE,MAAM,CAIzE,CAAC;AAEF,eAAO,MAAM,aAAa,oCAAoC,CAAC;AAC/D,eAAO,MAAM,WAAW,kCAAkC,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,MAAM,QAAQ,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;AACjD,MAAM,MAAM,MAAM,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC;AAK9C;;;GAGG;AACH,eAAO,MAAM,YAAY,GAAI,OAAO,OAAO,KAAG,MACU,CAAC;AAEzD;;;;;;;;;GASG;AACH,eAAO,MAAM,kBAAkB,GAAI,SAAS,MAAM,EAAE,MAAM,MAAM,KAAG,MAsBlE,CAAC;AAEF,wFAAwF;AACxF,eAAO,MAAM,iBAAiB,GAAI,OAAO,SAAS,EAAE,EAAE,WAAW,MAAM,KAAG,MAI5D,CAAC;AAEf,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,GAAI,OAAO,SAAS,EAAE,EAAE,WAAW,MAAM,KAAG,MAI7D,CAAC;AAUf,wEAAwE;AACxE,eAAO,MAAM,gBAAgB,GAAI,MAAM,SAAS,EAAE,WAAW,MAAM,KAAG,MAarE,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,WAAW,GAAI,KAAK,MAAM,EAAE,SAAQ,QAAqB,KAAG,SAAS,EAQjF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,GAAI,KAAK,MAAM,EAAE,SAAQ,QAAqB,KAAG,MAAM,GAAG,IAiBvF,CAAC;AAEF,+FAA+F;AAC/F,eAAO,MAAM,UAAU,GAAI,OAAO,MAAM,KAAG,SAAS,EAYnD,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,EACX,UAAU,kBAAkB,EAC5B,OAAO,SAAS,EAAE,EAClB,cAAc,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EACpC,MAAM,MAAM,EACZ,SAAQ,QAAqB,KAC5B,WAAW,EAiCb,CAAC;AAEF,gEAAgE;AAChE,eAAO,MAAM,SAAS,GACpB,KAAK,MAAM,EACX,SAAS,WAAW,EAAE,EACtB,OAAM,MAA6C,EACnD,SAAQ,QAAqB,KAC5B,WAAW,EAIV,CAAC"}

package/dist/utils/agent-rules.js

@@ -0,0 +1,178 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findDrift = exports.planFiles = exports.parseTools = exports.findAssistantRoot = exports.detectTools = exports.renderCursorRule = exports.renderPointerBlock = exports.renderImportBlock = exports.upsertManagedBlock = exports.errorMessage = exports.MANAGED_END = exports.MANAGED_BEGIN = exports.TOOL_ENTRY_FILES = exports.AGENT_TOOLS = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+exports.AGENT_TOOLS = ['claude', 'cursor', 'gemini', 'agents'];
+/** Entry file each assistant reads, for the tools wired via a managed block. */
+exports.TOOL_ENTRY_FILES = {
+    claude: 'CLAUDE.md',
+    gemini: 'GEMINI.md',
+    agents: 'AGENTS.md',
+};
+exports.MANAGED_BEGIN = '<!-- BEGIN genx agent-rules -->';
+exports.MANAGED_END = '<!-- END genx agent-rules -->';
+const countOccurrences = (haystack, needle) => haystack.split(needle).length - 1;
+/**
+ * Narrowed message for a caught value. `catch` bindings are only typed loosely because this
+ * package has not enabled `useUnknownInCatchVariables` yet; don't rely on that staying true.
+ */
+const errorMessage = (error) => error instanceof Error ? error.message : String(error);
+exports.errorMessage = errorMessage;
+/**
+ * Replaces the genx-managed block in `content`, or appends one when absent. Everything outside the
+ * markers is left alone — these files belong to the consumer project, not to us.
+ *
+ * Throws when the markers are malformed (an unpaired marker, `END` before `BEGIN`, or more than one
+ * pair). Every way of guessing what the author meant risks eating their prose: appending a second
+ * block leaves the file to be truncated by the *next* run, and treating an unpaired `BEGIN` as
+ * running to end-of-file discards whatever they wrote below it. Refusing to write is the only
+ * option that cannot lose someone's instructions.
+ */
+const upsertManagedBlock = (content, body) => {
+    const block = `${exports.MANAGED_BEGIN}\n${body.trim()}\n${exports.MANAGED_END}`;
+    const begins = countOccurrences(content, exports.MANAGED_BEGIN);
+    const ends = countOccurrences(content, exports.MANAGED_END);
+    const begin = content.indexOf(exports.MANAGED_BEGIN);
+    const end = content.indexOf(exports.MANAGED_END);
+    if (begins === 1 && ends === 1 && end > begin) {
+        const before = content.slice(0, begin);
+        const after = content.slice(end + exports.MANAGED_END.length);
+        return `${before}${block}${after}`;
+    }
+    if (begins === 0 && ends === 0) {
+        return content.trim() ? `${content.replace(/\s*$/, '')}\n\n${block}\n` : `${block}\n`;
+    }
+    throw new Error(`the genx agent-rules block is malformed: found ${begins} "${exports.MANAGED_BEGIN}" and ${ends} ` +
+        `"${exports.MANAGED_END}" marker(s), expected one matching pair or none. Restore the pair or delete ` +
+        `the block by hand, then run again — refusing to guess, so nothing you wrote is lost.`);
+};
+exports.upsertManagedBlock = upsertManagedBlock;
+/** Import line understood by Claude Code (`CLAUDE.md`) and Gemini CLI (`GEMINI.md`). */
+const renderImportBlock = (rules, targetDir) => [
+    '<!-- Installed by `genx agent-rules`. Re-run it to update; edits inside this block are lost. -->',
+    ...rules.map((rule) => `@${targetDir}/${rule.file}`),
+].join('\n');
+exports.renderImportBlock = renderImportBlock;
+/** Plain pointer for assistants without an import syntax (AGENTS.md, Copilot, Windsurf, …). */
+const renderPointerBlock = (rules, targetDir) => [
+    '<!-- Installed by `genx agent-rules`. Re-run it to update; edits inside this block are lost. -->',
+    ...rules.map((rule) => `- ${rule.description} Read and follow \`${targetDir}/${rule.file}\`.`),
+].join('\n');
+exports.renderPointerBlock = renderPointerBlock;
+/**
+ * YAML double-quoted scalar for a rule description. A colon, a quote, or a leading `-` in the
+ * manifest would otherwise produce front matter Cursor cannot parse — and the rule would then be
+ * silently inert rather than visibly broken.
+ */
+const yamlString = (value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+/** A fully generated Cursor rule that defers to the shared markdown. */
+const renderCursorRule = (rule, targetDir) => `---
+description: ${yamlString(rule.cursorDescription)}
+alwaysApply: false
+---
+
+<!-- Installed by \`genx agent-rules\`. Re-run it to update; local edits are lost. -->
+
+# ${rule.title}
+
+@${targetDir}/${rule.file}
+
+If this reference does not resolve, open \`${targetDir}/${rule.file}\` and follow it directly.
+`;
+exports.renderCursorRule = renderCursorRule;
+/**
+ * Which assistants a project already uses. Wiring an assistant nobody uses is just litter, so we
+ * only touch what we can see evidence of.
+ */
+const detectTools = (dir, exists = node_fs_1.existsSync) => {
+    const markers = {
+        claude: ['CLAUDE.md', '.claude'],
+        cursor: ['.cursor', '.cursorrules'],
+        gemini: ['GEMINI.md', '.gemini'],
+        agents: ['AGENTS.md'],
+    };
+    return exports.AGENT_TOOLS.filter((tool) => markers[tool].some((marker) => exists((0, node_path_1.join)(dir, marker))));
+};
+exports.detectTools = detectTools;
+/**
+ * The nearest ancestor of `dir` that looks like the project's assistant root, or `null`.
+ *
+ * Genesis apps keep `package.json` in `client/` while `CLAUDE.md` and friends sit at the repo
+ * root, so running the installer from the package directory would wire up nothing and leave a
+ * second, orphaned set of rule files behind. Walk up as far as the repo root looking for the
+ * directory the assistants actually read.
+ */
+const findAssistantRoot = (dir, exists = node_fs_1.existsSync) => {
+    let current = (0, node_path_1.dirname)(dir);
+    for (;;) {
+        if ((0, exports.detectTools)(current, exists).length) {
+            return current;
+        }
+        // The repo root is as far as we go - above it is someone else's project.
+        if (exists((0, node_path_1.join)(current, '.git'))) {
+            return null;
+        }
+        const parent = (0, node_path_1.dirname)(current);
+        if (parent === current) {
+            return null;
+        }
+        current = parent;
+    }
+};
+exports.findAssistantRoot = findAssistantRoot;
+/** Parses and validates a `--tools` value. Throws on anything unknown rather than guessing. */
+const parseTools = (value) => {
+    const requested = value
+        .split(',')
+        .map((tool) => tool.trim().toLowerCase())
+        .filter(Boolean);
+    const unknown = requested.filter((tool) => !exports.AGENT_TOOLS.includes(tool));
+    if (unknown.length) {
+        throw new Error(`Unknown agent tool(s): ${unknown.join(', ')}. Supported: ${exports.AGENT_TOOLS.join(', ')}`);
+    }
+    return exports.AGENT_TOOLS.filter((tool) => requested.includes(tool));
+};
+exports.parseTools = parseTools;
+/**
+ * Everything the command intends to write, as (path, contents) pairs. Kept separate from the
+ * writing itself so `--check` can compare against disk without touching it.
+ */
+const planFiles = (dir, manifest, tools, ruleContents, read, exists = node_fs_1.existsSync) => {
+    const { targetDir, rules } = manifest;
+    const planned = rules.map((rule) => ({
+        path: `${targetDir}/${rule.file}`,
+        contents: ruleContents[rule.file],
+    }));
+    tools.forEach((tool) => {
+        if (tool === 'cursor') {
+            rules.forEach((rule) => {
+                planned.push({
+                    path: `.cursor/rules/${rule.name}.mdc`,
+                    contents: (0, exports.renderCursorRule)(rule, targetDir),
+                });
+            });
+            return;
+        }
+        const entryFile = exports.TOOL_ENTRY_FILES[tool];
+        const entryPath = (0, node_path_1.join)(dir, entryFile);
+        const current = exists(entryPath) ? read(entryPath) : '';
+        const body = tool === 'agents'
+            ? (0, exports.renderPointerBlock)(rules, targetDir)
+            : (0, exports.renderImportBlock)(rules, targetDir);
+        try {
+            planned.push({ path: entryFile, contents: (0, exports.upsertManagedBlock)(current, body) });
+        }
+        catch (error) {
+            throw new Error(`${entryFile}: ${(0, exports.errorMessage)(error)}`);
+        }
+    });
+    return planned;
+};
+exports.planFiles = planFiles;
+/** Planned files whose contents differ from what is on disk. */
+const findDrift = (dir, planned, read = (path) => (0, node_fs_1.readFileSync)(path, 'utf8'), exists = node_fs_1.existsSync) => planned.filter((file) => {
+    const path = (0, node_path_1.join)(dir, file.path);
+    return !exists(path) || read(path) !== file.contents;
+});
+exports.findDrift = findDrift;

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@genesislcap/genx",
   "description": "Genx CLI",
-  "version": "15.23.3",
+  "version": "15.24.0-FUI-2603.10",
   "license": "SEE LICENSE IN license.txt",
   "engines": {
     "node": ">=22.0.0"
@@ -10,6 +10,7 @@
     "build": "npm run clean && tsc -b ./tsconfig.json",
     "clean": "rimraf dist temp tsconfig.tsbuildinfo",
     "dev": "tsc -b ./tsconfig.json -w",
+    "test": "genx test",
     "lint": "genx lint -l ox",
     "lint:fix": "genx lint -l ox --fix"
   },
@@ -17,18 +18,21 @@
     "genx": "./bin/genx"
   },
   "dependencies": {
-    "@genesislcap/build-kit": "15.23.3",
-    "@genesislcap/eslint-stylelint-builder": "15.23.3",
-    "@genesislcap/event-type-codegen": "15.23.3",
-    "@genesislcap/rollup-builder": "15.23.3",
-    "@genesislcap/ts-builder": "15.23.3",
-    "@genesislcap/uvu-playwright-builder": "15.23.3",
-    "@genesislcap/vite-builder": "15.23.3",
-    "@genesislcap/webpack-builder": "15.23.3",
+    "@genesislcap/build-kit": "15.24.0-FUI-2603.10",
+    "@genesislcap/eslint-stylelint-builder": "15.24.0-FUI-2603.10",
+    "@genesislcap/event-type-codegen": "15.24.0-FUI-2603.10",
+    "@genesislcap/rollup-builder": "15.24.0-FUI-2603.10",
+    "@genesislcap/ts-builder": "15.24.0-FUI-2603.10",
+    "@genesislcap/uvu-playwright-builder": "15.24.0-FUI-2603.10",
+    "@genesislcap/vite-builder": "15.24.0-FUI-2603.10",
+    "@genesislcap/webpack-builder": "15.24.0-FUI-2603.10",
     "cac": "^6.7.14",
     "consola": "^3.0.2",
     "serve-handler": "^6.1.5"
   },
+  "devDependencies": {
+    "@genesislcap/foundation-testing": "15.24.0-FUI-2603.10"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/genesislcap/foundation-ui.git",