joopjs 2.0.5 → 2.1.0

package/.cursor/rules/joopjs.mdc

@@ -0,0 +1,150 @@
+---
+description: Rules for using joopjs — enterprise financial SDK
+globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
+alwaysApply: true
+---
+
+# JoopJS SDK Rules for Cursor
+
+**Author:** Kundan Singh
+
+This project uses **joopjs** — a framework-agnostic TypeScript SDK for enterprise financial apps. Apply these rules whenever you generate or suggest code that involves joopjs.
+
+## Import Rules
+
+Always import from the package root or named sub-paths:
+```ts
+// Correct
+import { JoopDigitalWalletService, JoopAuthService } from 'joopjs';
+import { JoopGcmService } from 'joopjs/encryption';
+
+// Wrong — never import from internal paths
+import { JoopDigitalWalletService } from 'joopjs/src/banking/digital-wallet.service';
+```
+
+Available sub-paths: `auth`, `encryption`, `banking`, `security`, `api`, `core`, `session`, `device`, `observability`, `theme`, `i18n`, `ui`, `forms`, `router`, `state`, `workers`, `workflow`, `sync`, `platform`, `cache`, `network`, `analytics`, `validation`, `utilities`, `pwa`, `native-bridge`, `deeplink`, `react`, `angular`, `vue`, `india`.
+
+## Service Instantiation
+
+All services are plain classes with no dependencies:
+```ts
+const wallet  = new JoopDigitalWalletService();
+const auth    = new JoopAuthService();
+const loans   = new JoopLoanServicingService();
+const gcm     = new JoopGcmService();
+```
+
+Create them once at module/app level and share as singletons. No `@Injectable`, no DI container needed.
+
+## Observables — Critical Rules
+
+```ts
+// Subscribe
+const unsub = service.someEvent$().subscribe(value => { /* handler */ });
+
+// Emit (from inside a service or your own subject)
+mySubject.next(value);   // CORRECT
+mySubject.emit(value);   // WRONG — will throw
+
+// Read current value (BehaviorSubject only)
+const current = myBehaviorSubject.getValue();
+
+// Unsubscribe
+unsub();   // call the returned function — not .unsubscribe()
+
+// Do NOT use RxJS operators
+service.alert$().pipe(map(x => x))   // WRONG — not RxJS
+```
+
+## Data Types
+
+- Amounts: `number` (no Money class or BigDecimal)
+- Currencies: ISO-4217 string literal — `'USD'`, `'EUR'`, `'AED'`, `'INR'`
+- Timestamps: Unix epoch milliseconds as `number` — `Date.now()`, never `new Date()`
+- All IDs: `string`
+
+## Error Handling
+
+Services throw `Error` objects on invalid operations. Always use try/catch:
+```ts
+try {
+  const result = await service.doSomething();
+} catch (error) {
+  console.error(error.message);
+}
+```
+
+## Reference Formats
+
+Auto-generated reference numbers follow predictable patterns:
+- Loans: `LN-YYYY-000001`
+- FX Forwards: `FWD-YYYY-000001`
+- Journal Entries: `JE-YYYY-000001`
+- Standing Orders: `SO-YYYY-000001`
+- Remittances: `RMT-YYYY-000001`
+
+## Framework Integration
+
+### React
+```tsx
+useEffect(() => {
+  const unsub = service.event$().subscribe(handleEvent);
+  return unsub;    // cleanup on unmount
+}, []);
+```
+
+### Angular
+`joopjs/angular` ships real Angular 17+ DI. Bootstrap with `provideJoopAngular(instance)`, then inject and bridge observables to signals (auto-teardown via `DestroyRef`):
+```ts
+const joop = injectJoop();
+balance = joopSignal(joop.wallet.balance$());   // Angular signal
+```
+Also available: `joopAuthGuard()` (CanActivateFn), `joopAuthInterceptor()` (HttpInterceptorFn). Legacy `provideJoop`, `JoopModule`, `fromJoop` are deprecated but still work.
+
+### Vue
+```ts
+onMounted(() => { unsub = service.event$().subscribe(handleEvent); });
+onUnmounted(() => unsub?.());
+```
+
+## Key Services Quick Reference
+
+| Use Case | Service | Key Methods |
+|----------|---------|-------------|
+| Digital wallet | `JoopDigitalWalletService` | `createWallet`, `topUp`, `pay`, `transfer`, `getBalance`, `balance$` |
+| Loan management | `JoopLoanServicingService` | `createLoan`, `recordPayment`, `getSchedule`, `getOutstandingBalance` |
+| FX forwards | `JoopFxForwardService` | `setSpotRate`, `createForward`, `settleForward`, `getMarkToMarket` |
+| Mutual funds | `JoopMutualFundService` | `registerFund`, `invest`, `redeem`, `updateNav`, `createSip`, `executeSip` |
+| Sanctions | `JoopSanctionsScreeningService` | `loadList`, `screen`, `hit$` |
+| AML | `JoopAmlService` | `addRule`, `checkTransaction`, `alert$` |
+| Auth | `JoopAuthService` | `login`, `logout`, `refresh`, `getCurrentUser`, `session$` |
+| JWT | `JoopJwtService` | `sign`, `verify`, `decode`, `revoke` |
+| Encryption | `JoopGcmService` | `generateKey`, `encrypt`, `decrypt` |
+| Key exchange | `JoopX25519Service` | `generateKeyPair`, `deriveSharedSecret`, `deriveAesKey` |
+| Double-entry | `JoopLedgerService` | `addAccount`, `postEntry`, `getBalance`, `getTrialBalance` |
+| Reconciliation | `JoopReconciliationService` | `createSession`, `autoMatch`, `manualMatch`, `getSummary` |
+
+---
+
+## What Gets Published to npm
+
+Controlled by `"files"` in `package.json` — acts as an allowlist. Only these two are included:
+
+| Published to npm | Never published |
+|-----------------|----------------|
+| `dist/` — ESM + CJS + `.d.ts` for all 34 sub-paths | `src/` — TypeScript source |
+| `CHANGELOG.md` — release history | `tests/` — test suite |
+| | `scripts/` — release automation |
+| | `playground/` — Vite demo app |
+| | `.claude/` — Claude skills |
+| | `.cursor/` — these Cursor rules |
+| | `.windsurf/` — Windsurf rules |
+| | `GEMINI.md`, `AGENTS.md` — AI tool instructions |
+| | `tsup.config.ts`, `vitest.config.ts`, `tsconfig.json` |
+
+Source code, AI rules, and dev tooling are **never** published to npm.
+
+Verify the tarball contents before any publish:
+```bash
+npm pack --dry-run
+```

package/.github/copilot-instructions.md

@@ -0,0 +1,143 @@
+# GitHub Copilot Instructions — JoopJS SDK
+
+**Author:** Kundan Singh
+
+This workspace uses **joopjs** (`npm install joopjs`), a framework-agnostic TypeScript SDK for enterprise financial applications.
+
+## Always Follow These Rules
+
+### Imports
+- Import everything from `'joopjs'` (single entry point), or from sub-paths like `'joopjs/auth'`, `'joopjs/encryption'`
+- Never import from internal paths like `'joopjs/src/...'` or `'joopjs/dist/...'`
+
+### Service instantiation
+- All services are plain classes: `const svc = new JoopXxxService();`
+- No dependency injection or Angular `@Injectable` needed for the core SDK
+- For Angular 17+ apps, `joopjs/angular` offers real DI: `provideJoopAngular`, `injectJoop`, `joopSignal`, `joopAuthGuard`, `joopAuthInterceptor`
+- Create one instance per module/app (treat as singletons)
+
+### Reactive observables
+- Use `.subscribe(callback)` — returns an unsubscribe function, call it to stop listening
+- Emit values with `.next(value)` — **never** `.emit(value)`
+- Read current value with `.getValue()` on JoopBehaviorSubject
+- Do NOT use RxJS operators (`.pipe()`, `.map()`, etc.) — these are not RxJS Observables
+- Emission is error-isolated — one throwing subscriber does not block the others
+
+### Data conventions
+- Amounts: plain `number`, never a Money class
+- Currencies: ISO-4217 string (`'USD'`, `'EUR'`, `'AED'`)
+- Timestamps: Unix epoch milliseconds (`number`), never `Date` objects
+- IDs: pass as `string`
+
+### Error handling
+- All services throw standard `Error` on invalid input
+- Wrap service calls in `try/catch`
+
+---
+
+## Common Completions to Suggest
+
+### Digital Wallet
+```ts
+import { JoopDigitalWalletService } from 'joopjs';
+const wallet = new JoopDigitalWalletService();
+const w = wallet.createWallet('user-001', { currency: 'USD', label: 'Primary' });
+wallet.topUp(w.id, 500);
+wallet.pay(w.id, 50, 'merchant-id', 'description');
+const bal = wallet.getBalance(w.id);
+wallet.balance$().subscribe(({ walletId, balance }) => { /* update UI */ });
+```
+
+### Auth + JWT
+```ts
+import { JoopAuthService, JoopJwtService } from 'joopjs';
+const auth = new JoopAuthService();
+const jwt  = new JoopJwtService({ secret: process.env.JWT_SECRET!, expiryMs: 3600_000 });
+const session = await auth.login(email, password);
+const token   = jwt.sign({ userId: session.userId, role: 'user' });
+```
+
+### AES-GCM Encryption
+```ts
+import { JoopGcmService } from 'joopjs';
+const gcm = new JoopGcmService();
+const key = await gcm.generateKey();
+const enc = await gcm.encrypt(sensitiveData, key);
+const dec = await gcm.decrypt(enc.ciphertext, key, enc.iv);
+```
+
+### Loan Servicing
+```ts
+import { JoopLoanServicingService } from 'joopjs';
+const loans = new JoopLoanServicingService();
+const loan  = loans.createLoan({ borrowerName, borrowerId, principalAmount, annualInterestRatePercent, tenureMonths, currency: 'USD' });
+loans.recordPayment(loan.id, loan.emiAmount);
+const schedule = loans.getSchedule(loan.id);
+```
+
+### Sanctions Screening
+```ts
+import { JoopSanctionsScreeningService } from 'joopjs';
+const sanctions = new JoopSanctionsScreeningService();
+sanctions.loadList('ofac', entities);
+const result = sanctions.screen({ name: customerName, country: customerCountry });
+if (result.status !== 'clear') { /* block or escalate */ }
+```
+
+### Mutual Fund SIP
+```ts
+import { JoopMutualFundService } from 'joopjs';
+const mf = new JoopMutualFundService();
+const sip = mf.createSip(fundId, investorId, monthlyAmount, 'monthly', Date.now());
+mf.executeSip(sip.id);
+```
+
+---
+
+## TypeScript Types (prefix `Joop*`)
+
+```ts
+// Auth
+JoopAuthUser, JoopAuthSession, JoopAuthToken
+
+// Banking
+JoopWallet, JoopWalletTransaction, JoopWalletTxnType
+JoopLoanAccount, JoopInstallment, JoopLoanAccountStatus
+JoopFxForward, JoopForwardType, JoopForwardStatus
+JoopLedgerAccount, JoopJournalEntry, JoopTrialBalance
+
+// Finance
+JoopMutualFund, JoopFundHolding, JoopSip, JoopSipStatus, JoopFundCategory
+
+// Security
+JoopSanctionsEntity, JoopScreeningResult, JoopSanctionMatchType
+JoopAmlAlert, JoopCompliancePolicy
+```
+
+All types are exported from `'joopjs'`.
+
+---
+
+## What Gets Published to npm
+
+Controlled by `"files"` in `package.json` — acts as an allowlist. Only these two are included:
+
+| Published to npm | Never published |
+|-----------------|----------------|
+| `dist/` — ESM + CJS + `.d.ts` for all 34 sub-paths | `src/` — TypeScript source |
+| `CHANGELOG.md` — release history | `tests/` — test suite |
+| | `scripts/` — release automation |
+| | `playground/` — Vite demo app |
+| | `.claude/` — Claude skills |
+| | `.cursor/` — Cursor rules |
+| | `.windsurf/` — Windsurf rules |
+| | `GEMINI.md`, `AGENTS.md` — AI tool instructions |
+| | `.github/copilot-instructions.md` — this file |
+| | `tsup.config.ts`, `vitest.config.ts`, `tsconfig.json` |
+
+Source code, AI rules, and dev tooling are **never** published to npm.
+
+Verify the tarball contents before any publish:
+```bash
+npm pack --dry-run
+```

package/.windsurf/rules/joopjs.md

@@ -0,0 +1,226 @@
+# JoopJS SDK Rules for Windsurf Cascade
+
+**Author:** Kundan Singh
+
+This project uses **joopjs** — a framework-agnostic TypeScript SDK for building enterprise financial applications.
+
+## Package Information
+
+- **Package name:** `joopjs`
+- **Install:** `npm install joopjs`
+- **Version:** 2.0.0
+- **Compatibility:** Any TypeScript/JavaScript project — React, Angular, Vue, Node.js, plain TS
+
+---
+
+## Core Conventions
+
+### All imports come from `'joopjs'`
+
+```ts
+import {
+  JoopAuthService,
+  JoopDigitalWalletService,
+  JoopLoanServicingService,
+  JoopMutualFundService,
+  JoopSanctionsScreeningService,
+  JoopGcmService,
+  JoopX25519Service,
+  JoopSubject,
+  JoopBehaviorSubject,
+} from 'joopjs';
+```
+
+Or use sub-path imports for tree-shaking: `'joopjs/auth'`, `'joopjs/encryption'`, `'joopjs/banking'`, etc.
+
+### Services are plain class instances
+
+```ts
+// Good
+const wallet = new JoopDigitalWalletService();
+
+// Bad — no DI framework needed
+@Injectable() class MyService { constructor(private wallet: JoopDigitalWalletService) {} }
+```
+
+For Angular 17+ apps, `joopjs/angular` provides real DI: bootstrap with `provideJoopAngular(instance)`, then `const joop = injectJoop(); balance = joopSignal(joop.wallet.balance$());` (signal with auto-teardown). The core SDK itself still imports no framework.
+
+---
+
+## Reactive Pattern (Non-RxJS)
+
+```ts
+// Subscribe — returns unsubscribe function
+const stop = service.change$().subscribe(value => handleChange(value));
+
+// Emit
+subject.next(newValue);     // CORRECT
+subject.emit(newValue);     // WILL THROW — wrong method name
+
+// Cleanup
+stop();
+
+// BehaviorSubject current value
+const val = behaviorSubject.getValue();
+```
+
+Emission is error-isolated: a throwing subscriber no longer blocks delivery to the others. Route subscriber errors with `setSubjectErrorHandler(fn)` (defaults to `console.error`). Still not RxJS.
+
+---
+
+## Data Types
+
+| Concept | Type | Example |
+|---------|------|---------|
+| Money amount | `number` | `5000.00` |
+| Currency | `string` (ISO-4217) | `'USD'`, `'AED'` |
+| Timestamp | `number` (epoch ms) | `Date.now()` |
+| Duration | `number` (ms) | `7 * 86_400_000` |
+| ID | `string` | `'u-001'` |
+
+---
+
+## Domain Services Reference
+
+### Banking
+
+```ts
+// Digital Wallet
+const w = wallet.createWallet(userId, { currency: 'USD' });
+wallet.topUp(w.id, amount);
+wallet.pay(w.id, amount, merchantId, description);
+wallet.transfer(w.id, toWalletId, amount);
+wallet.freeze(w.id) / wallet.unfreeze(w.id) / wallet.close(w.id);
+wallet.balance$().subscribe(({ walletId, balance }) => { });
+
+// Loans
+const loan = loans.createLoan({ borrowerName, borrowerId, principalAmount, annualInterestRatePercent, tenureMonths, currency });
+loans.recordPayment(loan.id, amount);         // interest-first allocation
+const schedule = loans.getSchedule(loan.id); // JoopInstallment[]
+
+// FX Forwards
+fx.setSpotRate('USD', 'EUR', 0.92);
+const fwd = fx.createForward({ type: 'sell', baseCurrency, quoteCurrency, notionalAmount, contractRate, maturityDate });
+fx.settleForward(fwd.id, spotRateAtSettlement);  // returns { pnl }
+
+// Ledger
+ledger.addAccount(code, name, 'asset' | 'liability' | 'equity' | 'revenue' | 'expense');
+ledger.postEntry(description, [{ accountCode, debit, credit }, ...]);
+ledger.getTrialBalance();  // { isBalanced, totalDebits, totalCredits }
+```
+
+### Finance
+
+```ts
+// Mutual Funds
+mf.registerFund({ id, name, category: 'equity'|'debt'|'hybrid'|'index'|'etf', currentNav, currency });
+mf.invest(fundId, investorId, amount);
+mf.redeem(fundId, investorId, units);
+const sip = mf.createSip(fundId, investorId, amount, 'monthly'|'weekly'|'quarterly', startDate);
+mf.executeSip(sip.id);
+
+// Budget
+budget.createBudget({ name, period: 'monthly', currency, startDate });
+budget.addCategory(budgetId, { name, limit });
+budget.recordSpend(budgetId, categoryId, amount, description);
+
+// Portfolio
+portfolio.createPortfolio({ name, currency, userId });
+portfolio.addHolding(portfolioId, { symbol, name, quantity, avgCostPrice, currentPrice, assetClass });
+portfolio.updatePrice(portfolioId, symbol, newPrice);
+```
+
+### Security
+
+```ts
+// Sanctions Screening
+sanctions.loadList('ofac' | 'un' | 'eu' | 'uk' | 'custom', entities);
+const result = sanctions.screen({ name, country? });
+// result.status: 'clear' | 'hit' | 'review'
+// result.matches[]: [{ entity, matchType: 'exact'|'alias'|'fuzzy', score }]
+sanctions.hit$().subscribe(hit => { });  // only fires on non-clear results
+
+// AML
+aml.addRule({ id, name, type, threshold, currency, action: 'flag'|'block', enabled });
+const alert = aml.checkTransaction({ id, amount, currency, type, userId, timestamp });
+// null = passes; JoopAmlAlert = flagged/blocked
+
+// Risk Engine
+risk.addFactor({ key, weight, transform? });
+const score = risk.evaluate(signals);  // { total: [0-1], level: 'low'|'medium'|'high'|'critical' }
+```
+
+### Auth & Encryption
+
+```ts
+// Auth
+const session = await auth.login(email, password);
+await auth.logout(session.sessionId);
+auth.session$().subscribe(session => { /* null = logged out */ });
+
+// JWT
+const token = jwt.sign({ userId, role }, secret);
+const claims = jwt.verify(token, secret);  // null if invalid/expired
+
+// AES-GCM
+const key = await gcm.generateKey();
+const { ciphertext, iv } = await gcm.encrypt(plaintext, key);
+const decrypted = await gcm.decrypt(ciphertext, key, iv);
+
+// X25519 Key Exchange
+const keys = x25519.generateKeyPair();
+const shared = x25519.deriveSharedSecret(myPrivKey, theirPubKey);
+const aesKey = await x25519.deriveAesKey(shared);  // use with gcm.encrypt()
+```
+
+---
+
+## Error Handling Pattern
+
+```ts
+try {
+  const result = loans.createLoan({ ... });
+} catch (err) {
+  if (err instanceof Error) {
+    // All joopjs errors are standard Error with descriptive messages
+    console.error(err.message);
+  }
+}
+```
+
+---
+
+## When Cascade Generates JoopJS Code
+
+Always:
+1. Use `new JoopXxxService()` — no DI
+2. Call `.next(value)` to emit — never `.emit(value)`
+3. Use `number` for amounts and timestamps
+4. Wrap service calls in `try/catch`
+5. Store the unsubscribe function from `.subscribe()` and call it to clean up
+6. Use ISO-4217 strings for currency — `'USD'`, not `USD` (no enum)
+
+---
+
+## What Gets Published to npm
+
+Controlled by `"files"` in `package.json` — acts as an allowlist. Only these two are included:
+
+| Published to npm | Never published |
+|-----------------|----------------|
+| `dist/` — ESM + CJS + `.d.ts` for all 34 sub-paths | `src/` — TypeScript source |
+| `CHANGELOG.md` — release history | `tests/` — test suite |
+| | `scripts/` — release automation |
+| | `playground/` — Vite demo app |
+| | `.claude/` — Claude skills |
+| | `.cursor/` — Cursor rules |
+| | `.windsurf/` — these Windsurf rules |
+| | `GEMINI.md`, `AGENTS.md` — AI tool instructions |
+| | `tsup.config.ts`, `vitest.config.ts`, `tsconfig.json` |
+
+Source code, AI rules, and dev tooling are **never** published to npm.
+
+Verify the tarball contents before any publish:
+```bash
+npm pack --dry-run
+```

package/CHANGELOG.md

@@ -8,10 +8,45 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [2.1.0] — 2026-06-25 — Angular DI & Federation-Safe Core
+
+**0 new services · 21 new tests · 2189 tests total**
+
+### Added
+- **`joopjs/angular` — real Angular 17+ DI.** Alongside the existing string tokens (kept for back-compat):
+  - `JOOP_INSTANCE` — typed `InjectionToken<JoopInstance>`, plus `provideJoopAngular()` and `injectJoop()`.
+  - `joopSignal(obs, opts?)` — bridges a `JoopObservable` to an Angular `Signal`, seeded from the current value and torn down automatically via `DestroyRef`.
+  - `joopAuthGuard(opts?)` — functional `CanActivateFn` backed by `JoopAuthService`, returning a redirect `UrlTree` when unauthenticated.
+  - `joopAuthInterceptor(opts?)` — `HttpInterceptorFn` that attaches the access token from `JoopTokenService` (configurable header/scheme).
+- **`joopjs/core` — federation-safe singletons.** `globalSingleton()`, `joopCopyCount()`, and `silenceDuplicateCopyWarning()`. Module-level singletons (`logger`, `configService`, `joopEventBus`, `clipboard`, `clientProfile`) now resolve through a version-keyed `globalThis` registry, so duplicate bundled copies in a micro-frontend converge on one instance instead of fragmenting state. A one-time console warning fires when more than one copy is detected.
+- **`setSubjectErrorHandler()`** in the events module to route subscriber errors.
+- **`scripts/check-core-boundary.mjs`** + `npm run check:boundary` — CI guard enforcing that core never imports a framework (framework imports allowed only in `angular`/`react`/`vue` sub-paths).
+
+### Changed
+- **`JoopSubject` / `JoopBehaviorSubject` emission is now error-isolated.** `next()` snapshots its listeners and wraps each in try/catch, so one throwing subscriber no longer aborts delivery to the rest, and a subscribe/unsubscribe triggered mid-emission can't disturb the in-flight notification.
+- `@angular/common` and `@angular/router` added as **optional** peer dependencies (for `joopAuthGuard` / `joopAuthInterceptor`); `tsup` externalizes them so they are never bundled.
+
+### Deprecated
+- `joopjs/angular`: the string tokens (`JOOP`, `JOOP_AUTH`, …), `provideJoop()`, `JoopModule`, and `fromJoop()` are superseded by `JOOP_INSTANCE` + `provideJoopAngular()` + `joopSignal()`. They remain functional but will be removed in a future major. (`toJoop()` is **not** deprecated — it has no signal equivalent for bringing existing RxJS streams into JoopJS.)
+
+## [2.0.6] — 2026-06-22 — Patch Release
+
+**0 new services · 0 new tests · 2168 tests total**
+
+### Fixed
+- README version badge updated from `v2.0.5` → `v2.0.6`
+
+### Notes
+- Patch bump to correctly reflect the published npm version after the 2.0.5 AI Rules Setup release.
+- All 21 smoke tests pass against the npm-published package (wallet, loans, AML, sanctions, mutual funds, GCM encryption, setup-ai files).
+
 ## Version History
 
 | Version | Codename | New Services | Tests | Total Tests | Sub-paths Added |
 |---|---|---|---|---|---|
+| [2.1.0](#210--angular-di--federation-safe-core) | Angular DI & Federation-Safe Core | — | +21 | **2189** | — |
+| [2.0.6](#206--patch-release) | Patch Release | — | — | **2168** | — |
+| [2.0.5](#205--ai-rules-setup) | AI Rules Setup | — | — | **2168** | — |
 | [2.0.0](#200--vue-composables) | Vue Composables | — | +39 | **1080** | `vue` |
 | [1.9.0](#190--banking-depth) | Banking Depth | 4 | +100 | **1041** | — |
 | [1.8.0](#180--framework-bindings) | Framework Bindings | — | +25 | 941 | `react`, `angular` |
@@ -67,6 +102,52 @@ Versioning follows [Semantic Versioning](https://semver.org/).
 
 ---
 
+## [2.0.5] — AI Rules Setup
+
+**0 new services · 0 new tests · 2168 tests total · DX release**
+
+### Added
+
+- **`npx joopjs setup-ai`** — one-command AI assistant setup for consumers. Copies joopjs-aware rules into the user's project so that Claude Code, Cursor, Windsurf, GitHub Copilot, Gemini CLI, and Codex all understand the joopjs API out of the box.
+
+- **`scripts/setup-ai.mjs`** — the setup script, published as the `joopjs` bin entry. Copies consumer-facing rules from `node_modules/joopjs/` to the correct locations in the user's project. Skips existing files by default; `--force` flag overwrites. Prints a post-install summary with the exact CLAUDE.md skill lines to add.
+
+- **`ai-rules/`** — new directory included in the npm package. Contains consumer-only versions of `GEMINI.md` and `AGENTS.md` (usage guide only, no library-dev content).
+
+- **Consumer AI rules** included in the npm package for the first time:
+  - `.claude/skills/` — 7 consumer skills: `setup`, `banking`, `finance`, `security`, `auth`, `encryption`, `observables`
+  - `.cursor/rules/joopjs.mdc` — Cursor rule (auto-applied to all `.ts` / `.tsx` / `.js` files)
+  - `.windsurf/rules/joopjs.md` — Windsurf Cascade rule
+  - `.github/copilot-instructions.md` — GitHub Copilot instructions
+  - `ai-rules/GEMINI.md` — Gemini CLI consumer guide
+  - `ai-rules/AGENTS.md` — Codex / OpenAI Agents consumer guide
+
+- **Library-dev skills** (not published to npm) — 4 new Claude Code skills for library contributors:
+  - `/dev-build` — dev environment, build commands, tsup config, dist structure
+  - `/dev-testing` — Vitest commands, test conventions, writing tests for new services
+  - `/dev-contributing` — full checklist for adding a service or sub-path, code conventions
+  - `/dev-release` — local and CI release flow, preflight checks, CHANGELOG format
+
+- **Cursor dev rules** (`.cursor/rules/dev-contributing.mdc`) and **Windsurf dev rules** (`.windsurf/rules/dev-contributing.md`) — development-focused rule files for library contributors using Cursor or Windsurf.
+
+- **`GEMINI.md`** and **`AGENTS.md`** at project root — library-dev guides for Gemini CLI and Codex contributors.
+
+### Changed
+
+- `package.json` `"files"` — extended to include `ai-rules/`, `scripts/setup-ai.mjs`, the 7 consumer Claude skills, `.cursor/rules/joopjs.mdc`, `.windsurf/rules/joopjs.md`, and `.github/copilot-instructions.md`.
+- `package.json` `"bin"` — added `"joopjs": "scripts/setup-ai.mjs"` enabling `npx joopjs setup-ai`.
+- `README.md` — added **AI Assistant Setup** section immediately after Install; npm badge updated to v2.0.5.
+
+### User workflow
+
+```bash
+npm install joopjs
+npx joopjs setup-ai           # first time
+npx joopjs setup-ai --force   # after upgrading joopjs
+```
+
+---
+
 ## [2.0.0] — Vue Composables
 
 **0 new core services · 39 new tests · 1080 tests total · 90 test files · 1 new sub-path**