@happyvertical/smrt-cli 0.60.9 → 0.60.10

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.

package/dist/knowledge/intents/relationships-and-trees.md

@@ -0,0 +1,56 @@
+---
+type: Capability
+title: "Polymorphic links, junctions and trees"
+description: "Extend SmrtJunction, SmrtHierarchical and SmrtPolymorphicAssociation instead of writing link tables, parent_id traversal or type/id pairs by hand."
+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/hierarchical.ts
+    path: packages/core/src/hierarchical.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/hierarchical.ts (SmrtHierarchical.moveTo, getDescendants)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/junction.ts
+    path: packages/core/src/junction.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/junction.ts (SmrtJunction.attach, setLinks)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/polymorphic-association.ts
+    path: packages/core/src/polymorphic-association.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/polymorphic-association.ts (SmrtPolymorphicAssociation)"
+---
+
+# Polymorphic links, junctions and trees
+
+# Entry point
+
+All three are exported from `@happyvertical/smrt-core`. Trees: `class Place extends SmrtHierarchical` (a `parentId` self-reference) gives `getAncestors()`, `getDescendants()`, `getHierarchy()` and a cycle-checked `moveTo()`. Many-to-many: a collection extending `SmrtJunction` declares `leftField`/`rightField` and gets `attach()`, `detach()`, `byLeft()`, `byRight()` and `setLinks()`; composite-key owners extend `SmrtJunctionBase`. Links to any model: `class CommentAssociation extends SmrtPolymorphicAssociation` stores `metaType` (qualified class name), `metaId` and `role`, and `hydrate()` resolves the target through the registry. Classes whose self-reference means something else (an evolution chain, a derivation DAG) must not extend `SmrtHierarchical`.
+
+# Why not hand-roll it
+
+`SmrtHierarchical.moveTo()` in `hierarchical.ts` refuses to move a node to itself or beneath one of its own descendants before it saves, which a bare `parentId` update does not, and traversal is breadth-first with one batched query per level.[^s1] `SmrtJunction.attach()` in `junction.ts` spreads caller options first so the fixed left and right keys always win and untrusted options cannot retarget the write, and it upserts on the model's `conflictColumns` (with the documented caveat that a duplicate rewrites the row id); `setLinks()` replaces a left id's full set and is documented as not transactional.[^s2] `SmrtPolymorphicAssociation` keeps `metaId` a bare string with `metaType` resolved through `ObjectRegistry`, rather than an untyped foreign key per target.[^s3]
+
+# Component pages
+
+- [smrt-core](/components/smrt-core.md)
+
+# Detection signals
+
+- `regex:parent_?[iI]d\s*[:=]`
+- `regex:WITH RECURSIVE`
+- `regex:entity_?type`
+
+[^s1]: `packages/core/src/hierarchical.ts` at `478ae36900`: SmrtHierarchical.moveTo, getDescendants.
+[^s2]: `packages/core/src/junction.ts` at `478ae36900`: SmrtJunction.attach, setLinks.
+[^s3]: `packages/core/src/polymorphic-association.ts` at `478ae36900`: SmrtPolymorphicAssociation.

package/dist/knowledge/intents/scheduled-runs.md

@@ -0,0 +1,61 @@
+---
+type: Capability
+title: "Scheduled and recurring runs"
+description: "Reach for the smrt-jobs ScheduleRunner and smrt-agents AgentSchedule before writing a cron loop or setInterval poller."
+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/schedule-runner.ts
+    path: packages/jobs/src/schedule-runner.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/schedule-runner.ts (ScheduleRunner.triggerSchedule, validateCronExpression, getNextCronDate)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/agents/src/schedule.ts
+    path: packages/agents/src/schedule.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/agents/src/schedule.ts (AgentSchedule, getNextCronDate import)"
+  - id: s3
+    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 (ScheduleRunner, SCHEDULED_JOB_QUEUE exports)"
+---
+
+# Scheduled and recurring runs
+
+# Entry point
+
+Schedules are rows, not code. Define an `AgentSchedule` (`@happyvertical/smrt-agents`: agent type, method, args, 5-field `cron`, IANA `timezone`, optional `tenantId`) and run one `ScheduleRunner` (`createScheduleRunner()` from `@happyvertical/smrt-jobs`). Each due schedule is turned into a `SmrtJob` on the `SCHEDULED_JOB_QUEUE`, so a scheduled run gets the same retries, tenant cap and recovery as any other background job (see [background-work](/intents/background-work.md)). `validateCronExpression()` and `getNextCronDate()` are exported for write-time validation.[^s3]
+
+# Why not hand-roll it
+
+`ScheduleRunner.triggerSchedule()` in `schedule-runner.ts` validates the cron and time zone first and moves a schedule with an invalid expression to `status = 'error'` instead of retrying it on every poll; it then enqueues the job before advancing `next_run`, so a transient failure (a tenant-cap hit, a database blip) leaves the due slot to be retried rather than silently losing the run (#1401), and it enqueues through `enqueueJob` so the per-tenant cap and retry ceiling apply (#1402).[^s1] Cron is evaluated in the row's IANA zone with UTC as the default, never the host process zone (#3859).[^s1] `AgentSchedule.calculateNextRun()` imports `getNextCronDate` from smrt-jobs so the model and the runner cannot compute different next-run times.[^s2] A hand-written `setInterval` loop has none of this.
+
+# Component pages
+
+- [smrt-jobs](/components/smrt-jobs.md)
+- [smrt-agents](/components/smrt-agents.md)
+
+# Detection signals
+
+- `import:node-cron`
+- `import:cron`
+- `import:node-schedule`
+- `import:agenda`
+- `import:croner`
+- `call:setInterval`
+- `regex:cron\.schedule\(`
+
+[^s1]: `packages/jobs/src/schedule-runner.ts` at `478ae36900`: ScheduleRunner.triggerSchedule, validateCronExpression, getNextCronDate.
+[^s2]: `packages/agents/src/schedule.ts` at `478ae36900`: AgentSchedule, getNextCronDate import.
+[^s3]: `packages/jobs/src/index.ts` at `478ae36900`: ScheduleRunner, SCHEDULED_JOB_QUEUE exports.

package/dist/knowledge/intents/search-facts-knowledge.md

@@ -0,0 +1,68 @@
+---
+type: Capability
+title: "Search, facts and extracted knowledge"
+description: "Reach for core semanticSearch, smrt-facts reconciliation and smrt-ingestion before writing embedding search or a facts 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/facts/src/facts.ts
+    path: packages/facts/src/facts.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/facts/src/facts.ts (FactCollection.reconcile)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/collection.ts
+    path: packages/core/src/collection.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/collection.ts (SmrtCollection.findSimilarToEmbedding, semanticSearch)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/embeddings/storage.ts
+    path: packages/core/src/embeddings/storage.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/embeddings/storage.ts (EmbeddingStorage.searchSimilar)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/ingestion/AGENTS.md
+    path: packages/ingestion/AGENTS.md
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/ingestion/AGENTS.md (ingestion invariants)"
+---
+
+# Search, facts and extracted knowledge
+
+# Entry point
+
+Search: any SmrtCollection with embeddings configured exposes `semanticSearch(query, options)` (core). Knowledge: `FactCollection.reconcile(options)` from `@happyvertical/smrt-facts` decides whether new text creates, merges into or branches an existing `Fact`, with provenance in `FactSource`, entity links in `FactSubject` and document links in `FactContent` (to smrt-content `Content`). Extraction pipelines: smrt-ingestion owns sources, extraction attempts, proposals, review and execution; server-only services are under its `/server` subpath and generated mutation routes are disabled.
+
+# Why not hand-roll it
+
+`FactCollection.reconcile()` in `facts.ts` serializes under a PostgreSQL advisory lock keyed on the reconciliation identity and applies three zones over embedding similarity: at or above 0.85 merge (add a source, bump `sourceCount`), between 0.60 and 0.85 a typed decision or AI disambiguation, below 0.60 create.[^s1] In core, `findSimilarToEmbedding()` runs the tenant interceptor's list prefilter and ranks only that tenant's ids through `EmbeddingStorage.searchSimilar(..., { objectIds })`, where an empty id set returns no results rather than falling through to an unrestricted search, because `_smrt_embeddings` has no tenant column.[^s2][^s3] The ingestion package requires a tenant and confidentiality scope on every record and keeps analysis input, attempts, proposals and decisions append-only.[^s4] A hand-rolled vector search ranks across tenants first and filters afterwards, which both leaks and truncates.
+
+# Component pages
+
+- [smrt-facts](/components/smrt-facts.md)
+- [smrt-content](/components/smrt-content.md)
+- [smrt-ingestion](/components/smrt-ingestion.md)
+- [smrt-core](/components/smrt-core.md)
+
+# Detection signals
+
+- `import:@pinecone-database/pinecone`
+- `import:pgvector`
+- `import:minisearch`
+- `import:flexsearch`
+- `import:lunr`
+- `regex:cosine_?[sS]imilarity`
+
+[^s1]: `packages/facts/src/facts.ts` at `478ae36900`: FactCollection.reconcile.
+[^s2]: `packages/core/src/collection.ts` at `478ae36900`: SmrtCollection.findSimilarToEmbedding, semanticSearch.
+[^s3]: `packages/core/src/embeddings/storage.ts` at `478ae36900`: EmbeddingStorage.searchSimilar.
+[^s4]: `packages/ingestion/AGENTS.md` at `478ae36900`: ingestion invariants.

package/dist/knowledge/intents/secrets-and-config.md

@@ -0,0 +1,66 @@
+---
+type: Capability
+title: "Secrets and configuration"
+description: "Reach for smrt-secrets for per-tenant encrypted secrets and smrt-config for application configuration instead of raw env reads and ad-hoc encryption."
+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/secrets/src/services/SecretService.ts
+    path: packages/secrets/src/services/SecretService.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/secrets/src/services/SecretService.ts (SecretService.store)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/secrets/src/index.ts
+    path: packages/secrets/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/secrets/src/index.ts (public exports)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/config/src/loaded-config.ts
+    path: packages/config/src/loaded-config.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/config/src/loaded-config.ts (globalThis.__smrtConfigCache)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/config/src/index.ts
+    path: packages/config/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/config/src/index.ts (loadConfig)"
+---
+
+# Secrets and configuration
+
+# Entry point
+
+Secrets: `SecretService.create({ db, ... })` from `@happyvertical/smrt-secrets`, then `store(name, value, { description, category, expiresAt })` inside a tenant context (`storeForTenant()` outside one). Values are envelope-encrypted by the @happyvertical/secrets store under a per-tenant data key, and key drift is diagnosed with `diagnoseTenantSecretKeyDrift()`. Config: `await loadConfig()` once at startup (finds `smrt.config.*`), then `getConfig()`, `getModuleConfig()` or `getPackageConfig()` from `@happyvertical/smrt-config`; `defineConfig()` types the file.[^s2][^s4]
+
+# Why not hand-roll it
+
+`SecretService.store()` in `SecretService.ts` looks the secret up for the current tenant only (an unscoped lookup once found another tenant's same-named row and overwrote it with an envelope encrypted under the wrong key, #1501), refuses to save over a foreign row even if a lookup regresses, keys the upsert on slug plus `context = tenantId` so tenants can reuse names, and writes a `SecretAuditLog` row for create, update and failure alike, classifying tenant-key failures.[^s1] For config, `loaded-config.ts` keeps the parsed config on `globalThis.__smrtConfigCache` so every module instance, including pnpm workspace packages loaded from different paths, sees the same object.[^s3] Raw `process.env` reads and home-made AES have no tenant boundary, rotation or audit trail.
+
+# Component pages
+
+- [smrt-secrets](/components/smrt-secrets.md)
+- [smrt-config](/components/smrt-config.md)
+
+# Detection signals
+
+- `import:dotenv`
+- `import:node-vault`
+- `import:cosmiconfig`
+- `import:convict`
+- `regex:process\.env\.\w*SECRET`
+- `regex:createCipheriv\(`
+
+[^s1]: `packages/secrets/src/services/SecretService.ts` at `478ae36900`: SecretService.store.
+[^s2]: `packages/secrets/src/index.ts` at `478ae36900`: public exports.
+[^s3]: `packages/config/src/loaded-config.ts` at `478ae36900`: globalThis.__smrtConfigCache.
+[^s4]: `packages/config/src/index.ts` at `478ae36900`: loadConfig.

package/dist/knowledge/intents/tenant-scoping.md

@@ -0,0 +1,63 @@
+---
+type: Capability
+title: "Tenant scoping and cross-tenant reads"
+description: "Reach for smrt-tenancy and the core allowCrossTenant opt-in instead of filtering by tenant_id by hand."
+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/tenancy/src/interceptor.ts
+    path: packages/tenancy/src/interceptor.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/tenancy/src/interceptor.ts (createTenantInterceptor, rawQueryPolicy)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/tenancy/src/index.ts
+    path: packages/tenancy/src/index.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/tenancy/src/index.ts (withTenant, withSystemContext, queryGlobal, queryWithGlobals)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/object.ts
+    path: packages/core/src/object.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/object.ts (SmrtObject.assertRelatedTenant, allowCrossTenant)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/collection.ts
+    path: packages/core/src/collection.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/collection.ts (SmrtCollection.findSimilarToEmbedding tenant prefilter)"
+---
+
+# Tenant scoping and cross-tenant reads
+
+# Entry point
+
+Import from `@happyvertical/smrt-tenancy`. Declare a model with `@TenantScoped({ mode })` and a `@tenantId()` field, call `enableTenancy()` once at startup, and run request work inside `withTenant({ tenantId }, fn)` (adapters: `createSvelteKitHandle`, `createExpressMiddleware`, `createCliContext`). Collections then filter by tenant automatically. Read shared rows with `queryWithGlobals()`/`queryGlobal()`, use `withSystemContext()` only for reviewed system work, and opt into a cross-tenant relationship load with `{ allowCrossTenant: true }` on `loadRelated`/`getRelated` (core).[^s2]
+
+# Why not hand-roll it
+
+A hand-written `WHERE tenant_id = ?` covers only the query you wrote. The interceptor in `interceptor.ts` throws `TenantIsolationError` for any raw SQL against a tenant-scoped class unless the call passes `allowRawOnTenantScoped` (default `rawQueryPolicy: 'throw'`).[^s1] In core, `SmrtObject.assertRelatedTenant()` makes relationship loads, including cache hits from an earlier eager load, throw on a cross-tenant reference, and only the exact value `allowCrossTenant === true` bypasses it, not a truthy value from untyped callers (#1321).[^s3] Semantic search runs the tenant interceptor's list prefilter first and ranks only that tenant's ids, because the embeddings table has no tenant column.[^s4]
+
+# Component pages
+
+- [smrt-tenancy](/components/smrt-tenancy.md)
+- [smrt-core](/components/smrt-core.md)
+
+# Detection signals
+
+- `regex:WHERE\s+tenant_id`
+- `regex:tenant_?[iI]d\s*=\s*\?`
+- `regex:tenantId\s*[!=]==`
+
+[^s1]: `packages/tenancy/src/interceptor.ts` at `478ae36900`: createTenantInterceptor, rawQueryPolicy.
+[^s2]: `packages/tenancy/src/index.ts` at `478ae36900`: withTenant, withSystemContext, queryGlobal, queryWithGlobals.
+[^s3]: `packages/core/src/object.ts` at `478ae36900`: SmrtObject.assertRelatedTenant, allowCrossTenant.
+[^s4]: `packages/core/src/collection.ts` at `478ae36900`: SmrtCollection.findSimilarToEmbedding tenant prefilter.

package/dist/knowledge/intents/webhooks-and-events.md

@@ -0,0 +1,71 @@
+---
+type: Capability
+title: "Webhooks and events"
+description: "Reach for smrt-webhooks for outbound signed delivery and the core DispatchBus for in-process events; there is no generic inbound webhook receiver at this revision."
+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/webhooks/src/security.ts
+    path: packages/webhooks/src/security.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/webhooks/src/security.ts (assertWebhookUrl, assertHmacSecret, sendPublicWebhook)"
+  - id: s2
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/webhooks/src/dispatcher.ts
+    path: packages/webhooks/src/dispatcher.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/webhooks/src/dispatcher.ts (WebhookDispatcher.deliver)"
+  - id: s3
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/core/src/dispatch/bus.ts
+    path: packages/core/src/dispatch/bus.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/core/src/dispatch/bus.ts (DispatchBus.emit, process)"
+  - id: s4
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/jobs/src/forge-projection.ts
+    path: packages/jobs/src/forge-projection.ts
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/jobs/src/forge-projection.ts (ForgeDelivery inbox)"
+  - id: s5
+    resource: https://github.com/happyvertical/smrt/blob/478ae3690052b825b79b28235369ee7a5f6d2f20/packages/events/package.json
+    path: packages/events/package.json
+    source_revision: 478ae3690052b825b79b28235369ee7a5f6d2f20
+    title: "packages/events/package.json (description)"
+---
+
+# Webhooks and events
+
+# Entry point
+
+Outbound: `@happyvertical/smrt-webhooks` is server-only. Subscribers are `WebhookSubscription` rows managed through `WebhookAdminService`; publish from the change feed with `WebhookChangeFeed` (preferred) or `registerWebhookModelEvents()` (never both for one model), and run deliveries with `runWebhookDeliveryJob` on the smrt-jobs queue. In-process events: `createDispatchBus()` / `DispatchBus` (`emit()`, `on()`, `subscribe()`, `process()`) in `@happyvertical/smrt-core`. Corrections to the expected home: [smrt-events](/components/smrt-events.md) is the calendar and event-hierarchy model, not an event bus; and no package provides a generic inbound webhook receiver at this revision. The closest inbound pattern is the provider-neutral forge delivery inbox in smrt-jobs (`ForgeDelivery`, `ForgeProjectionRuntime`).[^s4][^s5]
+
+# Why not hand-roll it
+
+`sendPublicWebhook()` in `security.ts` validates every DNS answer as a public address, pins the socket lookup to the validated answer so a second resolution cannot rebind, follows no redirects, uses no proxy or pooled sockets, and bounds DNS (5 s) and request (10 s) time; `assertWebhookUrl()` rejects non-HTTPS, ports other than 443, embedded credentials and localhost, and `assertHmacSecret()` requires a 32 to 4096 byte secret.[^s1] `WebhookDispatcher.deliver()` signs `timestamp.payload` with HMAC-SHA256 over the exact stored bytes and sends a stable `x-smrt-delivery` id because HTTP delivery is at-least-once and receivers must deduplicate.[^s2] `DispatchBus` derives the tenant server-side from the active context and claims a dispatch with a conditional UPDATE on `status = 'pending'`, so a subscriber in one tenant cannot see another tenant's dispatches.[^s3]
+
+# Component pages
+
+- [smrt-webhooks](/components/smrt-webhooks.md)
+- [smrt-core](/components/smrt-core.md)
+- [smrt-jobs](/components/smrt-jobs.md)
+- [smrt-events](/components/smrt-events.md)
+
+# Detection signals
+
+- `import:svix`
+- `regex:createHmac\(`
+- `regex:x-[a-z-]*signature`
+
+[^s1]: `packages/webhooks/src/security.ts` at `478ae36900`: assertWebhookUrl, assertHmacSecret, sendPublicWebhook.
+[^s2]: `packages/webhooks/src/dispatcher.ts` at `478ae36900`: WebhookDispatcher.deliver.
+[^s3]: `packages/core/src/dispatch/bus.ts` at `478ae36900`: DispatchBus.emit, process.
+[^s4]: `packages/jobs/src/forge-projection.ts` at `478ae36900`: ForgeDelivery inbox.
+[^s5]: `packages/events/package.json` at `478ae36900`: description.

package/dist/{oidcProvisioningPrimitives-KpIiLmG4-CnRTofeV.js → oidcProvisioningPrimitives-KpIiLmG4-Csnh1ENp.js}

@@ -1,8 +1,8 @@
 import { t as __exportAll } from "./rolldown-runtime-8H4AJuhK.js";
 import { n as __exportAll$1 } from "./NostrIdentity-RJaATTCt-BbRHWyee.js";
-import { t as OidcIdentity } from "./OidcIdentity-COeMidoC-B-cVovG3.js";
-import { l as saveOidcRaceArbiter, n as Profile, r as ProfileCollection } from "./ProfileCollection-CmRaiE9U-52qjwbhJ.js";
-import { t as ProfileTypeCollection } from "./ProfileTypeCollection-BRLK8cHS-QVwjfqe8.js";
+import { t as OidcIdentity } from "./OidcIdentity-COeMidoC-BDr8b6iW.js";
+import { l as saveOidcRaceArbiter, n as Profile, r as ProfileCollection } from "./ProfileCollection-CmRaiE9U-n8apgXIh.js";
+import { t as ProfileTypeCollection } from "./ProfileTypeCollection-BRLK8cHS-COCy6yqF.js";
 import { smrt } from "@happyvertical/smrt-core";
 //#region ../profiles/dist/chunks/oidcProvisioningPrimitives-KpIiLmG4.js
 var oidcProvisioningPrimitives_KpIiLmG4_exports = /* @__PURE__ */ __exportAll({

package/dist/{operator-fwao3Y1j.js → operator-DCwooIiI.js}

@@ -1,5 +1,5 @@
-import { m as withSystemContext } from "./dist-BJABhykg.js";
-import { Ct as TenantStatus, E as PasswordCredentialService, K as UserCollection, N as RoleCollection, Q as UsersPasswordCredentialCollection, V as TenantCollection, dt as normalizeUsername, g as MembershipCollection, ht as verifySecretHash, j as PermissionResolver, lt as normalizeEmail, st as isValidEmail, wt as UserStatus, yt as MembershipStatus } from "./PasswordCredentialService-DHJNKEeJ-DQlR62e-.js";
+import { m as withSystemContext } from "./dist-B00KCyNE.js";
+import { Ct as TenantStatus, E as PasswordCredentialService, K as UserCollection, N as RoleCollection, Q as UsersPasswordCredentialCollection, V as TenantCollection, dt as normalizeUsername, g as MembershipCollection, ht as verifySecretHash, j as PermissionResolver, lt as normalizeEmail, st as isValidEmail, wt as UserStatus, yt as MembershipStatus } from "./PasswordCredentialService-BSSP_kyT-DlxlWy6b.js";
 import { isPostgresDatabase, withEmbeddedWriteTransaction } from "@happyvertical/smrt-core";
 //#region ../users/dist/operator.js
 var OperatorProvisioningError = class extends Error {