@happyvertical/smrt-cli 0.60.9 → 0.60.10

package/dist/index.js

@@ -51,77 +51,77 @@ var _cookbookCommands = null;
 var _kitchenCommands = null;
 async function getGnodeCommands() {
 	if (!_gnodeCommands) {
-		const { gnodeCommands } = await import("./commands-DNssH5Dv.js");
+		const { gnodeCommands } = await import("./commands-CGfM14Uj.js");
 		_gnodeCommands = gnodeCommands;
 	}
 	return _gnodeCommands;
 }
 async function getGitCommands() {
 	if (!_gitCommands) {
-		const { gitCommands } = await import("./commands-DNssH5Dv.js");
+		const { gitCommands } = await import("./commands-CGfM14Uj.js");
 		_gitCommands = gitCommands;
 	}
 	return _gitCommands;
 }
 async function getGenerateCommands() {
 	if (!_generateCommands) {
-		const { generateCommands } = await import("./commands-DNssH5Dv.js");
+		const { generateCommands } = await import("./commands-CGfM14Uj.js");
 		_generateCommands = generateCommands;
 	}
 	return _generateCommands;
 }
 async function getInitCommands() {
 	if (!_initCommands) {
-		const { initCommands } = await import("./commands-DNssH5Dv.js");
+		const { initCommands } = await import("./commands-CGfM14Uj.js");
 		_initCommands = initCommands;
 	}
 	return _initCommands;
 }
 async function getUtilityCommands() {
 	if (!_utilityCommands) {
-		const { utilityCommands } = await import("./commands-DNssH5Dv.js");
+		const { utilityCommands } = await import("./commands-CGfM14Uj.js");
 		_utilityCommands = utilityCommands;
 	}
 	return _utilityCommands;
 }
 async function getDispatchCommands() {
 	if (!_dispatchCommands) {
-		const { dispatchCommands } = await import("./commands-DNssH5Dv.js");
+		const { dispatchCommands } = await import("./commands-CGfM14Uj.js");
 		_dispatchCommands = dispatchCommands;
 	}
 	return _dispatchCommands;
 }
 async function getDocsCommands() {
 	if (!_docsCommands) {
-		const { docsCommands } = await import("./commands-DNssH5Dv.js");
+		const { docsCommands } = await import("./commands-CGfM14Uj.js");
 		_docsCommands = docsCommands;
 	}
 	return _docsCommands;
 }
 async function getPlaygroundCommands() {
 	if (!_playgroundCommands) {
-		const { playgroundCommands } = await import("./commands-DNssH5Dv.js");
+		const { playgroundCommands } = await import("./commands-CGfM14Uj.js");
 		_playgroundCommands = playgroundCommands;
 	}
 	return _playgroundCommands;
 }
 async function getCookbookCommands() {
 	if (!_cookbookCommands) {
-		const { cookbookCommands } = await import("./commands-DNssH5Dv.js");
+		const { cookbookCommands } = await import("./commands-CGfM14Uj.js");
 		_cookbookCommands = cookbookCommands;
 	}
 	return _cookbookCommands;
 }
 async function getKitchenCommands() {
 	if (!_kitchenCommands) {
-		const { kitchenCommands } = await import("./commands-DNssH5Dv.js");
+		const { kitchenCommands } = await import("./commands-CGfM14Uj.js");
 		_kitchenCommands = kitchenCommands;
 	}
 	return _kitchenCommands;
 }
 async function getWorkbenchCommands() {
 	if (!_workbenchCommands) {
-		const { workbenchCommands } = await import("./commands-DNssH5Dv.js");
+		const { workbenchCommands } = await import("./commands-CGfM14Uj.js");
 		_workbenchCommands = workbenchCommands;
 	}
 	return _workbenchCommands;

package/dist/knowledge/intents/audit-trail.md

@@ -0,0 +1,63 @@
+---
+type: Capability
+title: "Audit trail and change feed"
+description: "Use @smrt({ audit }) for who-changed-what records and the _smrt_changes feed for observing writes, instead of history tables or triggers."
+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/audit.ts
+    path: packages/core/src/audit.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/audit.ts (requireAuditOptions, auditSnapshot, writeAudit, AuditWriter)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/change-feed.ts
+    path: packages/core/src/change-feed.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/change-feed.ts (appendChange, getChangesSince, getTenantScopedChangesSince)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/change-feed-sensitivity.ts
+    path: packages/core/src/change-feed-sensitivity.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/change-feed-sensitivity.ts (sensitive tables)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/smrt-dev-mcp/src/tool-catalog.ts
+    path: packages/smrt-dev-mcp/src/tool-catalog.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/smrt-dev-mcp/src/tool-catalog.ts (recent-changes tool)"
+---
+
+# Audit trail and change feed
+
+# Entry point
+
+Two different things. Audit (who changed which fields): put `audit: true` in the model's `@smrt()` config and bind identity with `withAuditContext({ actorId, writer, reason, source }, fn)` from `@happyvertical/smrt-core`; the `writer` receives an `AuditEntry` with per-field before/after. Change feed (what changed, in order): every framework `save()`/`delete()` appends a row to `_smrt_changes`; read it with `getChangesSince(db, { since, tables, limit })` or, for request handlers, `getTenantScopedChangesSince()`. For a deployed database, the `recent-changes` tool of `smrt-dev-mcp` tails the same table read-only.[^s4]
+
+# Why not hand-roll it
+
+`requireAuditOptions()` in `audit.ts` throws when an audited mutation has no writer or no authenticated `actorId`, `auditSnapshot()` records the public projection so credential and permission-gated fields never enter the audit row, `writeAudit()` refuses an entity with ambiguous tenant ownership, and the writer contract requires using the same transaction handle and propagating failures.[^s1] The change feed in `change-feed.ts` allocates `seq` as `MAX(seq)+1` inside the append rather than a native identity column, so a polling cursor cannot skip a change under concurrent writers on SQLite, PostgreSQL or DuckDB; deletes are tombstones, and `getTenantScopedChangesSince()` fails closed to global rows when tenancy is on and no tenant is active.[^s2] Credential-bearing tables are refused by the feed (`change-feed-sensitivity.ts`) because a row id such as a session id is itself a secret.[^s3]
+
+# Component pages
+
+- [smrt-core](/components/smrt-core.md)
+- [smrt-dev-mcp](/components/smrt-dev-mcp.md)
+
+# Detection signals
+
+- `regex:audit_?log`
+- `regex:audit_?trail`
+- `regex:CREATE TABLE\s+\w*audit`
+
+[^s1]: `packages/core/src/audit.ts` at `478ae36900`: requireAuditOptions, auditSnapshot, writeAudit, AuditWriter.
+[^s2]: `packages/core/src/change-feed.ts` at `478ae36900`: appendChange, getChangesSince, getTenantScopedChangesSince.
+[^s3]: `packages/core/src/change-feed-sensitivity.ts` at `478ae36900`: sensitive tables.
+[^s4]: `packages/smrt-dev-mcp/src/tool-catalog.ts` at `478ae36900`: recent-changes tool.

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.