@happyvertical/smrt-dev-mcp 0.60.8 → 0.60.10

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/knowledge/okf-bundle.d.ts

@@ -0,0 +1,61 @@
+import type { KnowledgeIssue } from './index.js';
+export declare const OKF_BUNDLE_FORMAT = "smrt-okf-bundle/1";
+export declare const OKF_BUNDLE_DIR_NAME = "smrt-knowledge";
+export declare const OKF_BUNDLE_MANIFEST = "bundle.json";
+/** Project-relative directories a bundle may live under (`docs:agents`, `docs:claude`). */
+export declare const OKF_BUNDLE_PARENT_DIRS: readonly [".agents", ".claude"];
+/** File a published package ships its component page as, next to `smrt-knowledge.json`. */
+export declare const OKF_SHIPPED_COMPONENT_PAGE = "smrt-knowledge.okf.md";
+/** Directory under a home package's `dist/` that ships the full intent pages. */
+export declare const OKF_SHIPPED_INTENTS_DIR = "knowledge/intents";
+/**
+ * Packages that ship the full intent set: `smrt-cli` (the `docs:agents` export
+ * source) and this package (the trusted duplicate-detection index, #4690).
+ * Mirrored by `INTENT_HOME_PACKAGES` in `scripts/ship-knowledge-pages.mjs`.
+ */
+export declare const OKF_INTENT_HOME_PACKAGES: readonly ["@happyvertical/smrt-cli", "@happyvertical/smrt-dev-mcp"];
+/** Bundles older than this draw a warning even when every version matches. */
+export declare const OKF_BUNDLE_MAX_AGE_DAYS = 90;
+export interface OkfBundlePackage {
+    /** Full package name, e.g. `@happyvertical/smrt-jobs`. */
+    name: string;
+    /** Installed version at export time; equals the page's `package_version`. */
+    version: string;
+    /** Concept ID of the exported page, e.g. `/components/smrt-jobs.md`. */
+    concept: string;
+}
+export interface OkfBundleManifest {
+    format: typeof OKF_BUNDLE_FORMAT;
+    exportedBy: string;
+    /**
+     * First export of this exact content. Re-running `docs:agents` with nothing
+     * changed keeps it, so the committed bundle does not churn.
+     */
+    exportedAt: string;
+    /** `sha256:` over the exported pages and package versions. */
+    contentHash: string;
+    packages: OkfBundlePackage[];
+    /** Exported intent slugs. */
+    intents: string[];
+}
+/** Reads a top-level scalar from a page's YAML frontmatter, unquoted. */
+export declare function readFrontmatterScalar(page: string, key: string): string | undefined;
+/**
+ * Sets `package_version` in a page's frontmatter, leaving every other field
+ * byte-identical. The value is quoted when the page quotes its scalars.
+ */
+export declare function stampPackageVersion(page: string, version: string): string;
+export declare function readOkfBundleManifest(bundleDir: string): OkfBundleManifest | null;
+export interface OkfBundleFreshnessOptions {
+    now?: Date;
+    maxAgeDays?: number;
+}
+/**
+ * Reports each exported bundle's age and whether it still matches
+ * `node_modules`. Drift is `stale-okf-bundle`, which the caller downgrades to a
+ * warning outside strict mode like every other `stale-*` finding; the age is an
+ * `info` line, escalating to `okf-bundle-aged` past the age limit. Projects
+ * without an exported bundle yield nothing.
+ */
+export declare function checkOkfBundleFreshness(rootDir: string, options?: OkfBundleFreshnessOptions): KnowledgeIssue[];
+//# sourceMappingURL=okf-bundle.d.ts.map

package/dist/knowledge/okf-bundle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"okf-bundle.d.ts","sourceRoot":"","sources":["../../src/knowledge/okf-bundle.ts"],"names":[],"mappings":"AAwBA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD,eAAO,MAAM,iBAAiB,sBAAsB,CAAC;AACrD,eAAO,MAAM,mBAAmB,mBAAmB,CAAC;AACpD,eAAO,MAAM,mBAAmB,gBAAgB,CAAC;AACjD,2FAA2F;AAC3F,eAAO,MAAM,sBAAsB,iCAAkC,CAAC;AACtE,2FAA2F;AAC3F,eAAO,MAAM,0BAA0B,0BAA0B,CAAC;AAClE,iFAAiF;AACjF,eAAO,MAAM,uBAAuB,sBAAsB,CAAC;AAC3D;;;;GAIG;AACH,eAAO,MAAM,wBAAwB,qEAG3B,CAAC;AACX,8EAA8E;AAC9E,eAAO,MAAM,uBAAuB,KAAK,CAAC;AAE1C,MAAM,WAAW,gBAAgB;IAC/B,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,OAAO,EAAE,MAAM,CAAC;IAChB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,iBAAiB;IAChC,MAAM,EAAE,OAAO,iBAAiB,CAAC;IACjC,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB,8DAA8D;IAC9D,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,gBAAgB,EAAE,CAAC;IAC7B,6BAA6B;IAC7B,OAAO,EAAE,MAAM,EAAE,CAAC;CACnB;AAID,yEAAyE;AACzE,wBAAgB,qBAAqB,CACnC,IAAI,EAAE,MAAM,EACZ,GAAG,EAAE,MAAM,GACV,MAAM,GAAG,SAAS,CAOpB;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAWzE;AAED,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,MAAM,GAChB,iBAAiB,GAAG,IAAI,CAY1B;AAwBD,MAAM,WAAW,yBAAyB;IACxC,GAAG,CAAC,EAAE,IAAI,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,yBAA8B,GACtC,cAAc,EAAE,CAwGlB"}

package/dist/{knowledge-DqoDX-lZ.js → knowledge-DUiMUjEg.js}

@@ -1,4 +1,4 @@
-import { n as TOOLS } from "./tool-catalog-RHq7nyCm.js";
+import { n as TOOLS } from "./tool-catalog-BhnSCF8g.js";
 import { existsSync, lstatSync, opendirSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, matchesGlob, relative, resolve, sep } from "node:path";
 import { createHash } from "node:crypto";
@@ -178,6 +178,186 @@ function compareNames(left, right) {
 	return left < right ? -1 : left > right ? 1 : 0;
 }
 //#endregion
+//#region src/knowledge/okf-bundle.ts
+/**
+* Consumer-facing contract for the exported OKF knowledge bundle (#4689).
+*
+* `smrt docs:agents` writes `<dir of the output file>/smrt-knowledge/` (by
+* default `.agents/smrt-knowledge/`) into a consumer project:
+*
+*   bundle.json                 manifest (below)
+*   components/<unscoped>.md    one OKF component page per installed package
+*                               that ships one, `package_version` re-stamped
+*                               from the installed `package.json`
+*   intents/index.md            the intent index, rows limited to intents with
+*                               an installed home package
+*   intents/<slug>.md           those intents' pages
+*
+* Concept IDs keep the monorepo form (`/components/smrt-jobs.md`), resolved
+* against the bundle directory. A link to the page of an uninstalled package
+* dangles by design.
+*
+* This module owns the shape shared by the writer (`smrt-cli`) and the
+* freshness gate (`check-knowledge-freshness` / `dev:knowledge-check`), so the
+* two cannot drift. It has no side effects beyond reading the filesystem.
+*/
+var OKF_BUNDLE_FORMAT = "smrt-okf-bundle/1";
+var OKF_BUNDLE_DIR_NAME = "smrt-knowledge";
+var OKF_BUNDLE_MANIFEST = "bundle.json";
+/** Project-relative directories a bundle may live under (`docs:agents`, `docs:claude`). */
+var OKF_BUNDLE_PARENT_DIRS = [".agents", ".claude"];
+/** File a published package ships its component page as, next to `smrt-knowledge.json`. */
+var OKF_SHIPPED_COMPONENT_PAGE = "smrt-knowledge.okf.md";
+/** Directory under a home package's `dist/` that ships the full intent pages. */
+var OKF_SHIPPED_INTENTS_DIR = "knowledge/intents";
+/**
+* Packages that ship the full intent set: `smrt-cli` (the `docs:agents` export
+* source) and this package (the trusted duplicate-detection index, #4690).
+* Mirrored by `INTENT_HOME_PACKAGES` in `scripts/ship-knowledge-pages.mjs`.
+*/
+var OKF_INTENT_HOME_PACKAGES = ["@happyvertical/smrt-cli", "@happyvertical/smrt-dev-mcp"];
+/** Bundles older than this draw a warning even when every version matches. */
+var OKF_BUNDLE_MAX_AGE_DAYS = 90;
+var FRONTMATTER = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/;
+/** Reads a top-level scalar from a page's YAML frontmatter, unquoted. */
+function readFrontmatterScalar(page, key) {
+	const match = FRONTMATTER.exec(page);
+	if (!match) return void 0;
+	const line = new RegExp(`^${key}:[ \\t]*(.*)$`, "m").exec(match[1]);
+	if (!line) return void 0;
+	return line[1].trim().replace(/^(["'])(.*)\1$/, "$2");
+}
+/**
+* Sets `package_version` in a page's frontmatter, leaving every other field
+* byte-identical. The value is quoted when the page quotes its scalars.
+*/
+function stampPackageVersion(page, version) {
+	const match = FRONTMATTER.exec(page);
+	if (!match) return page;
+	const front = match[1];
+	const existing = /^package_version:[ \t]*(["']?).*$/m.exec(front);
+	const quote = existing?.[1] ?? "\"";
+	const line = `package_version: ${quote}${version}${quote}`;
+	const nextFront = existing ? front.replace(/^package_version:.*$/m, line) : `${front}\n${line}`;
+	return page.replace(front, nextFront);
+}
+function readOkfBundleManifest(bundleDir) {
+	const path = join(bundleDir, OKF_BUNDLE_MANIFEST);
+	if (!existsSync(path)) return null;
+	const parsed = JSON.parse(readFileSync(path, "utf8"));
+	if (parsed?.format !== "smrt-okf-bundle/1" || !Array.isArray(parsed.packages) || typeof parsed.exportedAt !== "string") throw new Error(`unrecognised bundle manifest format in ${path}`);
+	return parsed;
+}
+function installedVersion(rootDir, name) {
+	const path = join(rootDir, "node_modules", name, "package.json");
+	if (!existsSync(path)) return void 0;
+	try {
+		const version = JSON.parse(readFileSync(path, "utf8")).version;
+		return typeof version === "string" ? version : void 0;
+	} catch {
+		return;
+	}
+}
+/** Installed `@happyvertical/*` packages whose published artifact ships a page. */
+function installedPackagesShippingPages(rootDir) {
+	const scopeDir = join(rootDir, "node_modules", "@happyvertical");
+	if (!existsSync(scopeDir)) return [];
+	return readdirSync(scopeDir).filter((entry) => existsSync(join(scopeDir, entry, "dist", OKF_SHIPPED_COMPONENT_PAGE))).map((entry) => `@happyvertical/${entry}`);
+}
+/**
+* Reports each exported bundle's age and whether it still matches
+* `node_modules`. Drift is `stale-okf-bundle`, which the caller downgrades to a
+* warning outside strict mode like every other `stale-*` finding; the age is an
+* `info` line, escalating to `okf-bundle-aged` past the age limit. Projects
+* without an exported bundle yield nothing.
+*/
+function checkOkfBundleFreshness(rootDir, options = {}) {
+	const now = options.now ?? /* @__PURE__ */ new Date();
+	const maxAgeDays = options.maxAgeDays ?? 90;
+	const issues = [];
+	for (const parent of OKF_BUNDLE_PARENT_DIRS) {
+		const bundleDir = join(rootDir, parent, OKF_BUNDLE_DIR_NAME);
+		const where = relative(rootDir, bundleDir);
+		let manifest;
+		try {
+			manifest = readOkfBundleManifest(bundleDir);
+		} catch (error) {
+			issues.push({
+				severity: "warning",
+				code: "okf-bundle-invalid",
+				message: `Exported OKF bundle manifest is unreadable (${error instanceof Error ? error.message : String(error)}). Rerun \`smrt docs:agents\`.`,
+				file: join(where, OKF_BUNDLE_MANIFEST)
+			});
+			continue;
+		}
+		if (!manifest) continue;
+		const exportedMs = Date.parse(manifest.exportedAt);
+		const ageDays = Number.isNaN(exportedMs) ? void 0 : Math.max(0, Math.floor((now.getTime() - exportedMs) / 864e5));
+		const summary = `${manifest.packages.length} package page(s), ${manifest.intents.length} intent page(s), exported ${manifest.exportedAt}`;
+		if (ageDays === void 0) issues.push({
+			severity: "warning",
+			code: "okf-bundle-invalid",
+			message: `Exported OKF bundle has an invalid exportedAt (${manifest.exportedAt}). Rerun \`smrt docs:agents\`.`,
+			file: join(where, OKF_BUNDLE_MANIFEST)
+		});
+		else if (ageDays > maxAgeDays) issues.push({
+			severity: "warning",
+			code: "okf-bundle-aged",
+			message: `Exported OKF bundle is ${ageDays} days old (limit ${maxAgeDays}; ${summary}). Rerun \`smrt docs:agents\`.`,
+			file: join(where, OKF_BUNDLE_MANIFEST)
+		});
+		else issues.push({
+			severity: "info",
+			code: "okf-bundle-age",
+			message: `Exported OKF bundle is ${ageDays} day(s) old (${summary}).`,
+			file: join(where, OKF_BUNDLE_MANIFEST)
+		});
+		const exported = /* @__PURE__ */ new Set();
+		for (const entry of manifest.packages) {
+			exported.add(entry.name);
+			const pagePath = join(bundleDir, entry.concept.replace(/^\/+/, ""));
+			const pageFile = join(where, entry.concept.replace(/^\/+/, ""));
+			const stamped = existsSync(pagePath) ? readFrontmatterScalar(readFileSync(pagePath, "utf8"), "package_version") : void 0;
+			if (stamped === void 0) {
+				issues.push({
+					severity: "error",
+					code: "stale-okf-bundle",
+					message: `Exported OKF page for ${entry.name} is missing or has no package_version. Rerun \`smrt docs:agents\`.`,
+					file: pageFile,
+					packageName: entry.name
+				});
+				continue;
+			}
+			const installed = installedVersion(rootDir, entry.name);
+			if (installed === void 0) issues.push({
+				severity: "error",
+				code: "stale-okf-bundle",
+				message: `Exported OKF page for ${entry.name} (${stamped}) but the package is no longer installed. Rerun \`smrt docs:agents\`.`,
+				file: pageFile,
+				packageName: entry.name
+			});
+			else if (installed !== stamped) issues.push({
+				severity: "error",
+				code: "stale-okf-bundle",
+				message: `Exported OKF page for ${entry.name} is stamped ${stamped} but ${installed} is installed. Rerun \`smrt docs:agents\`.`,
+				file: pageFile,
+				packageName: entry.name
+			});
+		}
+		for (const name of installedPackagesShippingPages(rootDir)) {
+			if (exported.has(name)) continue;
+			issues.push({
+				severity: "error",
+				code: "stale-okf-bundle",
+				message: `${name} is installed and ships a knowledge page the exported OKF bundle does not include. Rerun \`smrt docs:agents\`.`,
+				file: join(where, OKF_BUNDLE_MANIFEST),
+				packageName: name
+			});
+		}
+	}
+	return issues;
+}
+//#endregion
 //#region src/knowledge/index.ts
 var SDK_PACKAGE_NAMES = /* @__PURE__ */ new Set([
 	"@happyvertical/ai",
@@ -514,6 +694,7 @@ async function checkKnowledgeFreshnessFromIndex(index, options = {}) {
 	if (devMcpPackage) issues.push(...checkMcpToolDocumentation(index.rootDir, devMcpPackage.directory, TOOLS));
 	issues.push(...findAgentSurfaceDriftIssues(authoredPackages));
 	issues.push(...findKnowledgeGraphIssues(index.rootDir));
+	issues.push(...checkOkfBundleFreshness(index.rootDir));
 	issues.push(...findStalePatternIssues(index.rootDir, changedFiles));
 	issues.push(...findNumericPrecisionIssues(index, authoredPackages, changedFiles));
 	const effectiveIssues = issues.map((issue) => issue.code.startsWith("stale-") ? {
@@ -1416,14 +1597,46 @@ function readKnowledgePackage(rootDir, directory, includeDocs, options = {}) {
 		checkedObjectPaths: resolvedObjects.checkedPaths
 	};
 }
+/**
+* Artifact locations a package declares through its own export map: a direct
+* `./smrt-knowledge.json` target, and the directory of its `./manifest.json`
+* target (the Vite plugin writes both artifacts beside each other in the
+* library `outDir`). A package that builds its library into `dist/lib` and
+* maps `"./manifest.json": "./dist/lib/manifest.json"` (#2923) is otherwise
+* invisible to the conventional probes below, and the index silently falls
+* back to the scanner view — which a turbo cache replay (`dist/**` restored,
+* `.smrt/` not) turns into a gate that depends on cache state.
+*/
+function exportedArtifactCandidates(directory) {
+	const exportsMap = objectRecord(objectRecord(readJson(join(directory, "package.json"))).exports);
+	const target = (subpath) => {
+		const entry = exportsMap[subpath];
+		const value = typeof entry === "string" ? entry : [
+			"smrt",
+			"node",
+			"import",
+			"default"
+		].map((condition) => objectRecord(entry)[condition]).find((candidate) => typeof candidate === "string");
+		return typeof value === "string" && value.startsWith("./") ? join(directory, value) : void 0;
+	};
+	const knowledge = target("./smrt-knowledge.json");
+	const manifest = target("./manifest.json") ?? target("./manifest");
+	return {
+		knowledge: [...knowledge ? [knowledge] : [], ...manifest ? [join(dirname(manifest), "smrt-knowledge.json")] : []],
+		manifest: manifest ? [manifest] : []
+	};
+}
 /** Artifact paths consulted for a package's objects, in precedence order. */
 function objectArtifactCandidates(directory) {
+	const exported = exportedArtifactCandidates(directory);
 	return [
 		join(directory, ".smrt", "smrt-knowledge.json"),
+		...exported.knowledge,
 		join(directory, "dist", "smrt-knowledge.json"),
 		join(directory, "src", "manifest", "smrt-knowledge.json"),
 		join(directory, "src", "manifest", "manifest.json"),
 		join(directory, ".smrt", "manifest.json"),
+		...exported.manifest,
 		join(directory, "dist", "manifest.json")
 	];
 }
@@ -1537,6 +1750,7 @@ function messageFromError(error) {
 function readDomainKnowledge(directory) {
 	for (const path of [
 		join(directory, ".smrt", "smrt-knowledge.json"),
+		...exportedArtifactCandidates(directory).knowledge,
 		join(directory, "dist", "smrt-knowledge.json"),
 		join(directory, "src", "manifest", "smrt-knowledge.json")
 	]) {
@@ -1557,6 +1771,7 @@ function readManifest(directory) {
 	for (const path of [
 		join(directory, "src", "manifest", "manifest.json"),
 		join(directory, ".smrt", "manifest.json"),
+		...exportedArtifactCandidates(directory).manifest,
 		join(directory, "dist", "manifest.json")
 	]) {
 		const content = readJson(path);
@@ -2725,6 +2940,6 @@ function gitignoredTopLevelEntries(directory) {
 	return ignored;
 }
 //#endregion
-export { buildReviewContext as a, compactContextResult as c, packageDocPaths as d, renderFreshnessResult as f, smrtReview as h, buildPackageSpecialistContext as i, coreCompatibleToSnakeCase as l, smrtArchitecture as m, buildContext as n, checkKnowledgeFreshness as o, renderKnowledgeIndexMarkdown as p, buildKnowledgeIndex as r, checkKnowledgeFreshnessFromIndex as s, buildArchitectureContext as t, diffKnowledgeIndex as u };
+export { OKF_SHIPPED_INTENTS_DIR as C, stampPackageVersion as D, readOkfBundleManifest as E, OKF_SHIPPED_COMPONENT_PAGE as S, readFrontmatterScalar as T, OKF_BUNDLE_FORMAT as _, buildReviewContext as a, OKF_BUNDLE_PARENT_DIRS as b, compactContextResult as c, packageDocPaths as d, renderFreshnessResult as f, OKF_BUNDLE_DIR_NAME as g, smrtReview as h, buildPackageSpecialistContext as i, coreCompatibleToSnakeCase as l, smrtArchitecture as m, buildContext as n, checkKnowledgeFreshness as o, renderKnowledgeIndexMarkdown as p, buildKnowledgeIndex as r, checkKnowledgeFreshnessFromIndex as s, buildArchitectureContext as t, diffKnowledgeIndex as u, OKF_BUNDLE_MANIFEST as v, checkOkfBundleFreshness as w, OKF_INTENT_HOME_PACKAGES as x, OKF_BUNDLE_MAX_AGE_DAYS as y };
 
-//# sourceMappingURL=knowledge-DqoDX-lZ.js.map
+//# sourceMappingURL=knowledge-DUiMUjEg.js.map