@happyvertical/smrt-cli 0.60.9 → 0.60.11

package/dist/knowledge/intents/auth-and-users.md

@@ -0,0 +1,67 @@
+---
+type: Capability
+title: "Auth, users and sessions"
+description: "Reach for smrt-users before writing password hashing, sessions, login throttling or role checks."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/users/src/services/credential-hash.ts
+    path: packages/users/src/services/credential-hash.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/users/src/services/credential-hash.ts (scrypt hash, timingSafeEqual, scryptHashNeedsUpgrade)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/users/src/services/LoginAttemptLimiter.ts
+    path: packages/users/src/services/LoginAttemptLimiter.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/users/src/services/LoginAttemptLimiter.ts (LoginAttemptLimiter.reserve, DEFAULT_LOGIN_*)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/users/src/services/SessionService.ts
+    path: packages/users/src/services/SessionService.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/users/src/services/SessionService.ts (SessionService.createSession)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/users/AGENTS.md
+    path: packages/users/AGENTS.md
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/users/AGENTS.md (models and authority)"
+---
+
+# Auth, users and sessions
+
+# Entry point
+
+Import from `@happyvertical/smrt-users` (SvelteKit handlers from `@happyvertical/smrt-users/sveltekit`). Identity is `User` (global) plus `Membership` per `Tenant` with `Role` permissions resolved by `PermissionResolver`; sessions by `SessionService.createSession(userId, tenantId)`; email-and-password sign-in by `PasswordCredentialService`, with passkey, device PIN, OIDC and mobile services alongside. Request-scoped tenant context comes from smrt-tenancy adapters (`createSvelteKitHandle`, `createExpressMiddleware`).[^s3]
+
+# Why not hand-roll it
+
+`credential-hash.ts` stores a self-describing `scrypt$N$r$p$salt$hash` string, compares with `timingSafeEqual`, and exposes `scryptHashNeedsUpgrade()` so stronger parameters roll out at the next sign-in.[^s1] `LoginAttemptLimiter` draws attempts from two independent budgets, the submitted subject and the source, stores both as hashes, locks out with exponential backoff (defaults: 5 attempts per 5 minutes, 60 s base, doubling, capped at one hour), and its contract says the credential check always runs so a response never reveals whether an identifier maps to an account.[^s2] The package invariants also make users global with tenant access only through `Membership`, and derive tenant hierarchy paths on save rather than trusting callers.[^s4] A hand-rolled login with bcrypt or a JWT library has none of the throttling, non-enumeration or tenant model.
+
+# Component pages
+
+- [smrt-users](/components/smrt-users.md)
+- [smrt-tenancy](/components/smrt-tenancy.md)
+
+# Detection signals
+
+- `import:bcrypt`
+- `import:bcryptjs`
+- `import:argon2`
+- `import:jsonwebtoken`
+- `import:passport`
+- `import:express-session`
+- `import:lucia`
+
+[^s1]: `packages/users/src/services/credential-hash.ts` at `478ae36900`: scrypt hash, timingSafeEqual, scryptHashNeedsUpgrade.
+[^s2]: `packages/users/src/services/LoginAttemptLimiter.ts` at `478ae36900`: LoginAttemptLimiter.reserve, DEFAULT_LOGIN_*.
+[^s3]: `packages/users/src/services/SessionService.ts` at `478ae36900`: SessionService.createSession.
+[^s4]: `packages/users/AGENTS.md` at `478ae36900`: models and authority.

package/dist/knowledge/intents/background-work.md

@@ -0,0 +1,72 @@
+---
+type: Capability
+title: "Background work and retries"
+description: "Reach for smrt-jobs before writing a queue, worker loop, retry counter or job table."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/smrt-job.ts
+    path: packages/jobs/src/smrt-job.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/smrt-job.ts (SmrtJobCollection.claimReady)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/background-policy.ts
+    path: packages/jobs/src/background-policy.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/background-policy.ts (MAX_JOB_RETRIES, DEFAULT_TENANT_JOB_CAP, clampRetries)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/stale-recovery.ts
+    path: packages/jobs/src/stale-recovery.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/stale-recovery.ts (DEFAULT_LEASE_TTL_MS, getEffectiveLeaseTtlMs)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/object-extension.ts
+    path: packages/jobs/src/object-extension.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/object-extension.ts (withBackgroundJobs, BackgroundCapable, BgOptions)"
+  - id: s5
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/index.ts
+    path: packages/jobs/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/index.ts (public exports)"
+---
+
+# Background work and retries
+
+# Entry point
+
+Import from `@happyvertical/smrt-jobs`. `withBackgroundJobs(Class)` adds `bg(method, args, { delay, retries, priority, queue, timeout })` and a fluent `background(method, args).delay('5m').retries(5).priority('high').enqueue()` to a SmrtObject class; both return a `JobHandle` and persist a `SmrtJob` row. Workers are a `TaskRunner` (`createTaskRunner()`); job progress and events go through `JobContext` and `SmrtJobEvent`. Mark which methods a persisted job may invoke with `backgroundEligible`/`markBackgroundEligible`.[^s4][^s5]
+
+# Why not hand-roll it
+
+A quick queue over a table usually claims work with a SELECT followed by an UPDATE, which lets two workers take the same row. `SmrtJobCollection.claimReady()` in `smrt-job.ts` claims in one conditional UPDATE so concurrent workers cannot receive the same pending row and never claim more than `limit` rows; on PostgreSQL it selects candidates in a `MATERIALIZED` CTE because the earlier `IN (SELECT ... FOR UPDATE SKIP LOCKED)` form let a single claim take the whole backlog (#3145).[^s1] `background-policy.ts` clamps a requested retry count to `MAX_JOB_RETRIES` (25) so a poison job cannot pin a worker, and `assertWithinTenantCreationCap` bounds a tenant to `DEFAULT_TENANT_JOB_CAP` (10,000) non-terminal jobs so one tenant cannot starve the shared pool.[^s2] A crashed worker's `running` jobs are recovered by worker liveness leases (`DEFAULT_LEASE_TTL_MS` 30 s, never fewer than three renewal ticks), not by per-job heartbeats.[^s3]
+
+# Component pages
+
+- [smrt-jobs](/components/smrt-jobs.md)
+- [smrt-core](/components/smrt-core.md)
+
+# Detection signals
+
+- `import:bullmq`
+- `import:bull`
+- `import:bee-queue`
+- `import:pg-boss`
+- `import:kue`
+- `regex:FOR UPDATE SKIP LOCKED`
+
+[^s1]: `packages/jobs/src/smrt-job.ts` at `478ae36900`: SmrtJobCollection.claimReady.
+[^s2]: `packages/jobs/src/background-policy.ts` at `478ae36900`: MAX_JOB_RETRIES, DEFAULT_TENANT_JOB_CAP, clampRetries.
+[^s3]: `packages/jobs/src/stale-recovery.ts` at `478ae36900`: DEFAULT_LEASE_TTL_MS, getEffectiveLeaseTtlMs.
+[^s4]: `packages/jobs/src/object-extension.ts` at `478ae36900`: withBackgroundJobs, BackgroundCapable, BgOptions.
+[^s5]: `packages/jobs/src/index.ts` at `478ae36900`: public exports.

package/dist/knowledge/intents/feature-flags-and-entitlements.md

@@ -0,0 +1,60 @@
+---
+type: Capability
+title: "Feature flags and entitlements"
+description: "Reach for smrt-features for tenant-aware flags and smrt-subscriptions for plan entitlements and usage thresholds."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/features/src/feature-resolver.ts
+    path: packages/features/src/feature-resolver.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/features/src/feature-resolver.ts (FeatureResolver.isEnabled, resolveBaseState)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/subscriptions/src/services/subscription-resolver.ts
+    path: packages/subscriptions/src/services/subscription-resolver.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/subscriptions/src/services/subscription-resolver.ts (SubscriptionResolver)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/subscriptions/src/index.ts
+    path: packages/subscriptions/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/subscriptions/src/index.ts (public exports)"
+---
+
+# Feature flags and entitlements
+
+# Entry point
+
+Flags: import `FeatureResolver` from `@happyvertical/smrt-features` and call `isEnabled(featureKey, { tenantId })` or `isEnabledFor(Class, localId, ctx)`. Defaults are declared in code and synced with `FeatureSyncService`; changes are written through `FeatureOverrideService` as global or tenant `FeatureOverride` rows. Entitlements: `SubscriptionResolver` (resolves a subscriber's plan terms and thresholds into an `EntitlementResolution`) and `TenantUsageMeter` (`record()`/`summarize()`) from `@happyvertical/smrt-subscriptions`.[^s3]
+
+# Why not hand-roll it
+
+`FeatureResolver.isEnabled()` in `feature-resolver.ts` resolves the registry default, then the global override, then walks the tenant's ancestor chain applying each tenant override, inheriting down the chain only where the parent has `cascadePermissions` and the child `inheritPermissions`, and it throws for a key that is neither registered nor synced instead of returning false.[^s1] It also strips host list bounds from its reads, because a configured default list limit would drop an ancestor override and silently change the resolved value (#3056).[^s1] `SubscriptionResolver` resolves terms from the plan version frozen on the subscription, fails closed when a pinned version cannot be found, and rejects a plan whose tenant does not match the subscription.[^s2] An environment variable or a column on the tenant row has no inheritance, audit or pinned-version semantics.
+
+# Component pages
+
+- [smrt-features](/components/smrt-features.md)
+- [smrt-subscriptions](/components/smrt-subscriptions.md)
+
+# Detection signals
+
+- `import:launchdarkly-node-server-sdk`
+- `import:unleash-client`
+- `import:flagsmith-nodejs`
+- `import:@growthbook/growthbook`
+- `regex:FEATURE_[A-Z_]+`
+- `regex:plan\s*===`
+
+[^s1]: `packages/features/src/feature-resolver.ts` at `478ae36900`: FeatureResolver.isEnabled, resolveBaseState.
+[^s2]: `packages/subscriptions/src/services/subscription-resolver.ts` at `478ae36900`: SubscriptionResolver.
+[^s3]: `packages/subscriptions/src/index.ts` at `478ae36900`: public exports.

package/dist/knowledge/intents/file-and-asset-storage.md

@@ -0,0 +1,71 @@
+---
+type: Capability
+title: "File and asset upload and storage"
+description: "Reach for smrt-assets AssetStore and the serving contract before writing an upload handler or file-serving route."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/assets/src/asset-serving.ts
+    path: packages/assets/src/asset-serving.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/assets/src/asset-serving.ts (resolveAssetForServing, AssetServeError, remoteMode)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/assets/src/owned-asset-helpers.ts
+    path: packages/assets/src/owned-asset-helpers.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/assets/src/owned-asset-helpers.ts (assertAssetLinkable)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/assets/src/asset-store.ts
+    path: packages/assets/src/asset-store.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/assets/src/asset-store.ts (AssetStore.store)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/assets-local/src/index.ts
+    path: packages/assets-local/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/assets-local/src/index.ts (createLocalAssetProcessor)"
+  - id: s5
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/assets-ergot/src/index.ts
+    path: packages/assets-ergot/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/assets-ergot/src/index.ts (createErgotAssetProcessor)"
+---
+
+# File and asset upload and storage
+
+# Entry point
+
+Import from `@happyvertical/smrt-assets`. `AssetStore` (`store()`, `read()`, `remove()`, `storeVersion()`) writes bytes through the @happyvertical/files provider layer (loaded lazily, so the storage backend is a configuration choice) and creates the matching `Asset` row. `createAssetRuntime()` bundles the store and collection; `serveAsset()` and `resolveAssetForServing()` are the serving contract; `addOwnedAssetFromCollection()` attaches assets to an owner through noun-specific joins. Correction to the expected home: `smrt-assets-local` and `smrt-assets-ergot` are not storage backends. They are `AssetCapabilityProvider` processors: `createLocalAssetProcessor()` (sharp image variants and metadata) and `createErgotAssetProcessor()` (Ergot workflow and external-source sync).[^s3][^s4][^s5]
+
+# Why not hand-roll it
+
+`resolveAssetForServing()` in `asset-serving.ts` returns 403 when an asset's `tenantId` is set and differs from the caller's, runs the host's `canAccess` hook, and defaults `remoteMode` to `'error'` because `sourceUri` is attacker-settable and proxying it is an SSRF vector (the proxy mode requires a public-IP host, re-validates redirects and caps bytes) (S5 #1396).[^s1] `assertAssetLinkable()` in `owned-asset-helpers.ts` refuses to associate an asset with an owner of another tenant, and refuses a tenant's asset on a shared owner.[^s2] A hand-rolled upload route typically serves `sourceUri` or a path directly and checks neither.
+
+# Component pages
+
+- [smrt-assets](/components/smrt-assets.md)
+- [smrt-assets-local](/components/smrt-assets-local.md)
+- [smrt-assets-ergot](/components/smrt-assets-ergot.md)
+
+# Detection signals
+
+- `import:multer`
+- `import:busboy`
+- `import:formidable`
+- `import:@aws-sdk/client-s3`
+
+[^s1]: `packages/assets/src/asset-serving.ts` at `478ae36900`: resolveAssetForServing, AssetServeError, remoteMode.
+[^s2]: `packages/assets/src/owned-asset-helpers.ts` at `478ae36900`: assertAssetLinkable.
+[^s3]: `packages/assets/src/asset-store.ts` at `478ae36900`: AssetStore.store.
+[^s4]: `packages/assets-local/src/index.ts` at `478ae36900`: createLocalAssetProcessor.
+[^s5]: `packages/assets-ergot/src/index.ts` at `478ae36900`: createErgotAssetProcessor.

package/dist/knowledge/intents/human-approvals.md

@@ -0,0 +1,56 @@
+---
+type: Capability
+title: "Human approval steps"
+description: "Reach for smrt-approvals ApprovalService before writing an approved flag, a status column or an approval table."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/approvals/src/service.ts
+    path: packages/approvals/src/service.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/approvals/src/service.ts (ApprovalService.decide, requestApproval, consume)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/approvals/src/kinds.ts
+    path: packages/approvals/src/kinds.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/approvals/src/kinds.ts (defineApprovalKind, assertPolicyTightens)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/approvals/AGENTS.md
+    path: packages/approvals/AGENTS.md
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/approvals/AGENTS.md (invariants)"
+---
+
+# Human approval steps
+
+# Entry point
+
+Import from `@happyvertical/smrt-approvals`. Register a kind with `defineApprovalKind({ ... })` (default quorum, TTL, required permissions, optional self-approval permission), construct an `ApprovalService`, and call `requestApproval(principal, input)` when an agent or service needs a human gate, `decide(principal, requestId, { decision, reason })` for the human outcome, and `consume()` to spend an approved request exactly where the gated action happens. Tenants may tighten a kind through `ApprovalPolicy`. This is a decision gate and ledger, not a workflow engine.
+
+# Why not hand-roll it
+
+`ApprovalService.decide()` in `service.ts` refuses any principal whose type is not `human` (`not_human`), refuses the requester unless the kind grants a self-approval permission (`self_approval`), checks every permission the request snapshot requires, refuses a non-pending or expired request, and allows one decision per actor.[^s1] Per the package invariants every transition is one guarded UPDATE on tenant, status, version and expiry plus an append-only `ApprovalEvent` in one transaction, so two concurrent approvers cannot both win, and `assertPolicyTightens()` rejects a policy that lowers quorum or lengthens expiry.[^s2][^s3] An `approved` boolean cannot tell who approved, whether they were the requester, or whether the approval was already used.
+
+# Component pages
+
+- [smrt-approvals](/components/smrt-approvals.md)
+
+# Detection signals
+
+- `regex:approved_by`
+- `regex:status\s*=\s*['"]approved['"]`
+- `regex:require_?[aA]pproval`
+
+[^s1]: `packages/approvals/src/service.ts` at `478ae36900`: ApprovalService.decide, requestApproval, consume.
+[^s2]: `packages/approvals/src/kinds.ts` at `478ae36900`: defineApprovalKind, assertPolicyTightens.
+[^s3]: `packages/approvals/AGENTS.md` at `478ae36900`: invariants.

package/dist/knowledge/intents/index.md

@@ -0,0 +1,41 @@
+---
+type: Index
+title: "Developer-intent index"
+description: "What to reach for in smrt before hand-rolling infrastructure, keyed by what you are about to write."
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/AGENTS.md
+    path: AGENTS.md
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "AGENTS.md"
+---
+
+# Developer-intent index
+
+Read this before writing queues, schedulers, mailers, uploaders, tenant filters, money fields, flags, audit tables, secrets handling, approvals, webhooks, search, auth or prompts. Each page names the smrt package and entry point, one verified reason not to hand-roll it, and the generated component page. The last column lists import, call and regex signals that suggest a hand-rolled equivalent.
+
+| Intent | Page | Home package(s) | Entry point | Hand-rolled signals |
+| --- | --- | --- | --- | --- |
+| Background work and retries | [background-work](/intents/background-work.md) | [smrt-jobs](/components/smrt-jobs.md), [smrt-core](/components/smrt-core.md) | `withBackgroundJobs` (`bg()`/`background()`), `SmrtJob`, `TaskRunner` | `import:bullmq`; `import:bull`; `import:bee-queue`; `import:pg-boss`; `import:kue`; `regex:FOR UPDATE SKIP LOCKED` |
+| Scheduled and recurring runs | [scheduled-runs](/intents/scheduled-runs.md) | [smrt-jobs](/components/smrt-jobs.md), [smrt-agents](/components/smrt-agents.md) | `AgentSchedule` + `createScheduleRunner()`/`ScheduleRunner` | `import:node-cron`; `import:cron`; `import:node-schedule`; `import:agenda`; `import:croner`; `call:setInterval`; `regex:cron\.schedule\(` |
+| Outbound email, SMS, chat messages | [outbound-messages](/intents/outbound-messages.md) | [smrt-messages](/components/smrt-messages.md), [smrt-tenancy](/components/smrt-tenancy.md) | `PersonaMessagingService.send()`, `EmailSender`/`SlackSender`/`TelegramSender`/`ZulipSender`, `UserNotificationService` | `import:nodemailer`; `import:@sendgrid/mail`; `import:twilio`; `import:@slack/web-api`; `import:resend`; `import:postmark`; `import:mailgun.js` |
+| File and asset upload, storage backends | [file-and-asset-storage](/intents/file-and-asset-storage.md) | [smrt-assets](/components/smrt-assets.md), [smrt-assets-local](/components/smrt-assets-local.md), [smrt-assets-ergot](/components/smrt-assets-ergot.md) | `AssetStore`, `createAssetRuntime()`, `serveAsset()`/`resolveAssetForServing()` | `import:multer`; `import:busboy`; `import:formidable`; `import:@aws-sdk/client-s3` |
+| Tenant scoping and cross-tenant reads | [tenant-scoping](/intents/tenant-scoping.md) | [smrt-tenancy](/components/smrt-tenancy.md), [smrt-core](/components/smrt-core.md) | `@TenantScoped` + `@tenantId`, `withTenant()`, `enableTenancy()`, `allowCrossTenant` | `regex:WHERE\s+tenant_id`; `regex:tenant_?[iI]d\s*=\s*\?`; `regex:tenantId\s*[!=]==` |
+| Money, rates, confidence fields | [money-and-rates](/intents/money-and-rates.md) | [smrt-core](/components/smrt-core.md), [smrt-subscriptions](/components/smrt-subscriptions.md) | `amount = 0` (integer minor units), `rate = 0.0` (decimal), `@field({ ui: { format } })` | `regex:\.toFixed\(2\)`; `regex:price\w*\s*=\s*0\.0`; `regex:DECIMAL\(\d+,\s*2\)`; `decimal-field:*_cents`; `decimal-field:*_amount` |
+| Feature flags and entitlements | [feature-flags-and-entitlements](/intents/feature-flags-and-entitlements.md) | [smrt-features](/components/smrt-features.md), [smrt-subscriptions](/components/smrt-subscriptions.md) | `FeatureResolver.isEnabled()`, `SubscriptionResolver`, `TenantUsageMeter` | `import:launchdarkly-node-server-sdk`; `import:unleash-client`; `import:flagsmith-nodejs`; `import:@growthbook/growthbook`; `regex:FEATURE_[A-Z_]+`; `regex:plan\s*===` |
+| Audit trail and change feed | [audit-trail](/intents/audit-trail.md) | [smrt-core](/components/smrt-core.md), [smrt-dev-mcp](/components/smrt-dev-mcp.md) | `@smrt({ audit: true })` + `withAuditContext()`, `getChangesSince()`, `recent-changes` tool | `regex:audit_?log`; `regex:audit_?trail`; `regex:CREATE TABLE\s+\w*audit` |
+| Secrets and config | [secrets-and-config](/intents/secrets-and-config.md) | [smrt-secrets](/components/smrt-secrets.md), [smrt-config](/components/smrt-config.md) | `SecretService.create()` + `store()`, `loadConfig()`, `getModuleConfig()`, `defineConfig()` | `import:dotenv`; `import:node-vault`; `import:cosmiconfig`; `import:convict`; `regex:process\.env\.\w*SECRET`; `regex:createCipheriv\(` |
+| Human approval steps | [human-approvals](/intents/human-approvals.md) | [smrt-approvals](/components/smrt-approvals.md) | `ApprovalService` (`requestApproval()`, `decide()`, `consume()`), `defineApprovalKind()` | `regex:approved_by`; `regex:status\s*=\s*['"]approved['"]`; `regex:require_?[aA]pproval` |
+| Inbound and outbound webhooks | [webhooks-and-events](/intents/webhooks-and-events.md) | [smrt-webhooks](/components/smrt-webhooks.md), [smrt-core](/components/smrt-core.md), [smrt-jobs](/components/smrt-jobs.md), [smrt-events](/components/smrt-events.md) | `WebhookDispatcher`, `WebhookAdminService`, `registerWebhookRuntime()`; core `createDispatchBus()` | `import:svix`; `regex:createHmac\(`; `regex:x-[a-z-]*signature` |
+| Search, facts, extracted knowledge | [search-facts-knowledge](/intents/search-facts-knowledge.md) | [smrt-facts](/components/smrt-facts.md), [smrt-content](/components/smrt-content.md), [smrt-ingestion](/components/smrt-ingestion.md), [smrt-core](/components/smrt-core.md) | `FactCollection.reconcile()`, `collection.semanticSearch()`, smrt-ingestion models and `/server` services | `import:@pinecone-database/pinecone`; `import:pgvector`; `import:minisearch`; `import:flexsearch`; `import:lunr`; `regex:cosine_?[sS]imilarity` |
+| Auth, users, sessions | [auth-and-users](/intents/auth-and-users.md) | [smrt-users](/components/smrt-users.md), [smrt-tenancy](/components/smrt-tenancy.md) | `SessionService`, `PasswordCredentialService`, `PermissionResolver`, `LoginAttemptLimiter`, `/sveltekit` handlers | `import:bcrypt`; `import:bcryptjs`; `import:argon2`; `import:jsonwebtoken`; `import:passport`; `import:express-session`; `import:lucia` |
+| Prompts and AI operations | [prompts-and-ai-operations](/intents/prompts-and-ai-operations.md) | [smrt-prompts](/components/smrt-prompts.md), [smrt-core](/components/smrt-core.md), [smrt-agents](/components/smrt-agents.md) | `definePrompt()` + `resolvePrompt()`, `PromptOverrideService`, `@smrt({ ai: { callable } })`, `SmrtObject.is()/do()/describe()` | `import:openai`; `import:@anthropic-ai/sdk`; `import:langchain`; `regex:You are an? [a-z ]+`; `regex:role:\s*['"]system['"]` |
+| Polymorphic links, junctions, trees | [relationships-and-trees](/intents/relationships-and-trees.md) | [smrt-core](/components/smrt-core.md) | `SmrtJunction`/`SmrtJunctionBase`, `SmrtHierarchical`, `SmrtPolymorphicAssociation` | `regex:parent_?[iI]d\s*[:=]`; `regex:WITH RECURSIVE`; `regex:entity_?type` |

package/dist/knowledge/intents/money-and-rates.md

@@ -0,0 +1,65 @@
+---
+type: Capability
+title: "Money, rates and confidence fields"
+description: "Declare money as integer minor units and rates as decimals through the core numeric-default rule instead of floats or custom decimal columns."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/ui-metadata.ts
+    path: packages/core/src/ui-metadata.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/ui-metadata.ts (FIELD_UI_FORMAT_TYPES)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/scanner/manifest-generator.ts
+    path: packages/core/src/scanner/manifest-generator.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/scanner/manifest-generator.ts (ui.format validation against field type)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/migrations/minor-units.ts
+    path: packages/core/src/migrations/minor-units.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/migrations/minor-units.ts (preflightMinorUnitsRescale, rescaleMoneyColumnsToMinorUnits)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/subscriptions/src/index.ts
+    path: packages/subscriptions/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/subscriptions/src/index.ts (migrateSubscriptionsMoneyToMinorUnits)"
+---
+
+# Money, rates and confidence fields
+
+# Entry point
+
+The rule is in the field default: `price = 0` is an integer column holding minor units (`1999` for $19.99), `rate = 0.0` is a decimal for rates and confidence. Mark presentation with `@field({ ui: { format: 'money' } })` (integer only) or `'percent'` (decimal or integer); a currency code is a separate text field. To convert a legacy floating-point money column, use `preflightMinorUnitsRescale()` then `rescaleMoneyColumnsToMinorUnits()` from `@happyvertical/smrt-core/migrations` (per-package wrappers such as `migrateSubscriptionsMoneyToMinorUnits` exist).[^s4]
+
+# Why not hand-roll it
+
+`FIELD_UI_FORMAT_TYPES` in `ui-metadata.ts` lists the only field type each presentation format may sit on (`money: ['integer']`), and the manifest generator fails the build when a `money` format is put on a non-integer field.[^s1][^s2] Converting an existing float column is deliberately not an automatic type change, because `ALTER ... TYPE BIGINT` would truncate `19.99` to `19`; `minor-units.ts` instead provides a read-only preflight that lists rows that would lose information (half-cents, values beyond the JavaScript safe-integer range once scaled) and a rescale guarded by a `BackfillTracker` marker so a re-run can never multiply a table by 100 twice.[^s3] Float money fields and `toFixed(2)` rounding lose exactly these cases silently.
+
+# Component pages
+
+- [smrt-core](/components/smrt-core.md)
+- [smrt-subscriptions](/components/smrt-subscriptions.md)
+
+# Detection signals
+
+- `regex:\.toFixed\(2\)`
+- `regex:price\w*\s*=\s*0\.0`
+- `regex:DECIMAL\(\d+,\s*2\)`
+- `decimal-field:*_cents`
+- `decimal-field:*_amount`
+
+[^s1]: `packages/core/src/ui-metadata.ts` at `478ae36900`: FIELD_UI_FORMAT_TYPES.
+[^s2]: `packages/core/src/scanner/manifest-generator.ts` at `478ae36900`: ui.format validation against field type.
+[^s3]: `packages/core/src/migrations/minor-units.ts` at `478ae36900`: preflightMinorUnitsRescale, rescaleMoneyColumnsToMinorUnits.
+[^s4]: `packages/subscriptions/src/index.ts` at `478ae36900`: migrateSubscriptionsMoneyToMinorUnits.

package/dist/knowledge/intents/outbound-messages.md

@@ -0,0 +1,67 @@
+---
+type: Capability
+title: "Outbound email, SMS and chat messages"
+description: "Reach for smrt-messages before calling a mailer or chat SDK directly from application code."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/messages/src/services/PersonaMessagingService.ts
+    path: packages/messages/src/services/PersonaMessagingService.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/messages/src/services/PersonaMessagingService.ts (PersonaMessagingService.send)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/messages/src/permissions.ts
+    path: packages/messages/src/permissions.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/messages/src/permissions.ts (assertMessagingPermission, SEND_MESSAGES_PERMISSION)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/messages/src/senders/EmailSender.ts
+    path: packages/messages/src/senders/EmailSender.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/messages/src/senders/EmailSender.ts (EmailSender.send)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/messages/src/index.ts
+    path: packages/messages/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/messages/src/index.ts (public exports)"
+---
+
+# Outbound email, SMS and chat messages
+
+# Entry point
+
+Import from `@happyvertical/smrt-messages`. Send through `new PersonaMessagingService({ db, tenantId, principal }).send({ personaId, body, subject, attachments, routeId })`, which resolves a persona-owned route (account plus endpoint), persists a `Message` (or `Email`) row and delivers it. Channel transports are `EmailSender`, `SlackSender`, `TelegramSender`, `ZulipSender` and `TweetSender`; accounts and routes are managed through `MessagingSettingsService`, and in-app notices through `UserNotificationService`. Providers are registered with `registerMessagingProvider()`.[^s4]
+
+# Why not hand-roll it
+
+`PersonaMessagingService.send()` in `PersonaMessagingService.ts` checks `SEND_MESSAGES_PERMISSION` with `assertMessagingPermission` (a principal from another tenant is rejected), runs inside `withTenant`, refuses an account or endpoint that belongs to another tenant, is inactive, or whose channel does not match the route, rejects attachments on non-email routes, and saves the message with `sendStatus: 'pending'` before it calls the transport, so every send has a ledger row.[^s1][^s2] `EmailSender.send()` resolves every attachment before anything reaches the transport, so an unreadable file fails the send instead of leaving a message silently without it (#3808).[^s3] A direct SDK call skips the permission check, the tenant ownership checks and the persisted record.
+
+# Component pages
+
+- [smrt-messages](/components/smrt-messages.md)
+- [smrt-tenancy](/components/smrt-tenancy.md)
+
+# Detection signals
+
+- `import:nodemailer`
+- `import:@sendgrid/mail`
+- `import:twilio`
+- `import:@slack/web-api`
+- `import:resend`
+- `import:postmark`
+- `import:mailgun.js`
+
+[^s1]: `packages/messages/src/services/PersonaMessagingService.ts` at `478ae36900`: PersonaMessagingService.send.
+[^s2]: `packages/messages/src/permissions.ts` at `478ae36900`: assertMessagingPermission, SEND_MESSAGES_PERMISSION.
+[^s3]: `packages/messages/src/senders/EmailSender.ts` at `478ae36900`: EmailSender.send.
+[^s4]: `packages/messages/src/index.ts` at `478ae36900`: public exports.

package/dist/knowledge/intents/prompts-and-ai-operations.md

@@ -0,0 +1,72 @@
+---
+type: Capability
+title: "Prompts and AI operations"
+description: "Register prompts with smrt-prompts and expose AI-callable operations through @smrt({ ai }) instead of inline prompt strings and ad-hoc LLM clients."
+tags:
+  - smrt
+  - intent
+status: draft
+generated:
+  by: claude/smrt-4687
+  at: 2026-11-05T00:00:00Z
+stale_after: 2027-02-03T00:00:00Z
+audience: internal
+evidence_level: source-inspected
+package_version: 0.60.8
+sources:
+  - id: s1
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/prompts/src/models/PromptOverride.ts
+    path: packages/prompts/src/models/PromptOverride.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/prompts/src/models/PromptOverride.ts (PromptOverride.validatePromptOverride)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/prompts/src/prompt-override-service.ts
+    path: packages/prompts/src/prompt-override-service.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/prompts/src/prompt-override-service.ts (assertValidPromptScope, InvalidPromptScopeError)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/prompts/src/prompt-resolver.ts
+    path: packages/prompts/src/prompt-resolver.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/prompts/src/prompt-resolver.ts (resolvePrompt)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/agents/src/ai-config.ts
+    path: packages/agents/src/ai-config.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/agents/src/ai-config.ts (resolveAgentAIOptions)"
+  - id: s5
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/registry/types.ts
+    path: packages/core/src/registry/types.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/registry/types.ts (SmrtClassOptions.ai)"
+---
+
+# Prompts and AI operations
+
+# Entry point
+
+Prompts: `definePrompt({ key, template, ai })` registers a namespaced code default; `await resolvePrompt(key, { override })` returns the effective template, profile, model and params after layering code default, config file, app override, tenant override and runtime override field by field. Writes go through `PromptOverrideService` with a host-supplied authorizer; a management screen uses `PromptSettingsService`. AI operations on models: `@smrt({ ai: { callable: ['analyze'] } })` chooses which methods an AI may call, and `SmrtObject` provides `is()`, `do()` and `describe()`. Agents resolve per-tenant provider keys with `resolveAgentAIOptions()` (smrt-agents).[^s3][^s5]
+
+# Why not hand-roll it
+
+`PromptOverride` validates on save in `PromptOverride.ts` that the prompt key is registered and that no field the definition marks not editable is overridden, so a tenant cannot override a locked template or model.[^s1] `assertValidPromptScope()` in `prompt-override-service.ts` rejects an unknown scope type, an app id other than the app scope constant and blank or untrimmed tenant ids before the authorizer runs, so a malformed tenant write cannot land on the app-wide row, and every write fails closed without a `true` from the authorizer.[^s2] `resolveAgentAIOptions()` takes the provider key from `SecretService` for the current tenant with ancestor-tenant fallback by default, instead of reading one global environment key.[^s4] An inline prompt string has no override layering, no authorization of edits and no key management.
+
+# Component pages
+
+- [smrt-prompts](/components/smrt-prompts.md)
+- [smrt-core](/components/smrt-core.md)
+- [smrt-agents](/components/smrt-agents.md)
+
+# Detection signals
+
+- `import:openai`
+- `import:@anthropic-ai/sdk`
+- `import:langchain`
+- `regex:You are an? [a-z ]+`
+- `regex:role:\s*['"]system['"]`
+
+[^s1]: `packages/prompts/src/models/PromptOverride.ts` at `478ae36900`: PromptOverride.validatePromptOverride.
+[^s2]: `packages/prompts/src/prompt-override-service.ts` at `478ae36900`: assertValidPromptScope, InvalidPromptScopeError.
+[^s3]: `packages/prompts/src/prompt-resolver.ts` at `478ae36900`: resolvePrompt.
+[^s4]: `packages/agents/src/ai-config.ts` at `478ae36900`: resolveAgentAIOptions.
+[^s5]: `packages/core/src/registry/types.ts` at `478ae36900`: SmrtClassOptions.ai.