@microsoft/rayfin-docs 1.27.0

package/LICENSE

@@ -0,0 +1,21 @@
+Copyright (c) Microsoft Corporation.
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/assets/catalog.json

@@ -0,0 +1,132 @@
+{
+  "schemaVersion": 1,
+  "generatedAt": "2026-05-07T05:00:00Z",
+  "packages": [
+    {
+      "name": "@microsoft/rayfin-core",
+      "kind": "sdk",
+      "summary": "Code-first decorators for data model definition. The CLI reads this metadata to generate Data API Builder configuration.",
+      "topics": [
+        "entity",
+        "decorator",
+        "data-model",
+        "schema",
+        "dab",
+        "fabric"
+      ],
+      "modules": ["rayfin-core"]
+    },
+    {
+      "name": "@microsoft/rayfin-data",
+      "kind": "sdk",
+      "summary": "DAB-compliant data client for GraphQL access patterns against the generated DAB endpoint.",
+      "topics": ["graphql", "data", "client", "query", "mutation", "dab"],
+      "modules": ["rayfin-data"]
+    },
+    {
+      "name": "@microsoft/rayfin-auth",
+      "kind": "sdk",
+      "summary": "Authentication helpers: magic-link sign-in, token management, sign-in flows for Rayfin Builder apps.",
+      "topics": [
+        "auth",
+        "authentication",
+        "magic-link",
+        "signin",
+        "login",
+        "token",
+        "session"
+      ],
+      "modules": ["rayfin-auth"]
+    },
+    {
+      "name": "@microsoft/rayfin-client",
+      "kind": "sdk",
+      "summary": "High-level Rayfin client entrypoint composing auth and data APIs behind a single configured client.",
+      "topics": ["client", "service", "composition", "high-level"],
+      "modules": ["rayfin-client"]
+    },
+    {
+      "name": "@microsoft/rayfin-lib",
+      "kind": "sdk",
+      "summary": "Shared HTTP and client utilities used by higher-level Rayfin SDKs.",
+      "topics": ["http", "shared", "utility", "internal"],
+      "modules": ["rayfin-lib"]
+    },
+    {
+      "name": "@microsoft/rayfin-functions",
+      "kind": "sdk",
+      "summary": "TypeScript helpers for function-style workflows on top of Rayfin core.",
+      "topics": ["functions", "serverless", "azure-functions", "workflow"],
+      "modules": []
+    },
+    {
+      "name": "@microsoft/rayfin-storage",
+      "kind": "sdk",
+      "summary": "Type-safe blob storage client for Rayfin storage backends.",
+      "topics": ["storage", "blob", "azure-blob", "file", "upload"],
+      "modules": []
+    },
+    {
+      "name": "@microsoft/rayfin-auth-provider-fabric",
+      "kind": "sdk",
+      "summary": "Microsoft Fabric token provider for Rayfin auth flows.",
+      "topics": ["fabric", "auth-provider", "token", "msal"],
+      "modules": ["rayfin-auth-provider-fabric"]
+    },
+    {
+      "name": "@microsoft/rayfin-cli",
+      "kind": "tool",
+      "summary": "Rayfin command-line interface: scaffolding, configuration, deployment, and the `rayfin docs` command group for offline-friendly agent grounding.",
+      "topics": ["cli", "scaffolding", "init", "deploy", "docs"],
+      "modules": []
+    },
+    {
+      "name": "@microsoft/rayfin-mcp",
+      "kind": "tool",
+      "summary": "Model Context Protocol server exposing Rayfin docs as `list_docs`, `search_docs`, `get_doc`, and `discover_packages` tools.",
+      "topics": ["mcp", "agent", "docs-server", "model-context-protocol"],
+      "modules": []
+    },
+    {
+      "name": "@microsoft/rayfin-docs",
+      "kind": "tool",
+      "summary": "Docs indexing/discovery library powering the CLI and MCP server. Handles the `rayfinDocs` per-package convention and merges installed package docs.",
+      "topics": ["docs-library", "indexer", "search", "discovery"],
+      "modules": []
+    },
+    {
+      "name": "@microsoft/rayfin-guide",
+      "kind": "guide",
+      "summary": "Cross-cutting Builder guides — getting started, auth overview, data permissions, CLI commands. Discovered via the `rayfinDocs` field.",
+      "topics": [
+        "guide",
+        "tutorial",
+        "quickstart",
+        "builder",
+        "getting-started"
+      ],
+      "modules": ["rayfin-guide"]
+    },
+    {
+      "name": "@microsoft/rayfin-host-docs",
+      "kind": "host",
+      "summary": "Host service reference docs for Rayfin .NET hosting components (WebService, Auth, Storage, DataApi, Function). Discovered via the rayfinDocs field.",
+      "topics": [
+        "host",
+        "dotnet",
+        "web-service",
+        "asp-net-core",
+        "graphql-endpoint",
+        "data-api-builder"
+      ],
+      "modules": ["rayfin-host"]
+    },
+    {
+      "name": "@microsoft/create-rayfin",
+      "kind": "tool",
+      "summary": "App scaffolding tool for bootstrapping new Rayfin projects via `npm create rayfin@latest`.",
+      "topics": ["scaffolding", "create", "init", "bootstrap"],
+      "modules": []
+    }
+  ]
+}

package/dist/_internal/build-index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Internal subpath export for build tooling that needs the lower-level
+ * docs index primitives (loader + index-builder + serializer) — for
+ * example, build-time compatibility tooling that emits a static search
+ * index from package docs.
+ *
+ * Not part of the public API. Subject to change between minor versions.
+ * Library consumers should use `DocsService` from the package root.
+ */
+export { loadDocs } from '../loader.js';
+export { createDocsIndex, serializeDocsIndex, DOCS_INDEX_SCHEMA_VERSION, DOCS_SEARCH_CONFIG_FINGERPRINT, } from '../search.js';
+export { DOCS_DEFAULT_MODULES } from '../index.js';
+export type { DocModule } from '../types.js';
+//# sourceMappingURL=build-index.d.ts.map

package/dist/_internal/build-index.js

@@ -0,0 +1,13 @@
+/**
+ * Internal subpath export for build tooling that needs the lower-level
+ * docs index primitives (loader + index-builder + serializer) — for
+ * example, build-time compatibility tooling that emits a static search
+ * index from package docs.
+ *
+ * Not part of the public API. Subject to change between minor versions.
+ * Library consumers should use `DocsService` from the package root.
+ */
+export { loadDocs } from '../loader.js';
+export { createDocsIndex, serializeDocsIndex, DOCS_INDEX_SCHEMA_VERSION, DOCS_SEARCH_CONFIG_FINGERPRINT, } from '../search.js';
+export { DOCS_DEFAULT_MODULES } from '../index.js';
+//# sourceMappingURL=build-index.js.map

package/dist/catalog-types.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Bundled static manifest of Rayfin packages.
+ *
+ * Shipped inside `@microsoft/rayfin-docs` to power:
+ * - `rayfin docs discover <query>` (CLI)
+ * - the `discover_packages` MCP tool
+ *
+ * The catalog answers "what packages exist, what could I install, and
+ * what should I update if the installed docs do not include a feature?"
+ * It is INTENTIONALLY decoupled from runtime discovery (which only sees
+ * what's installed in `node_modules`). The two compose: the agent first
+ * checks installed packages via `DocsService.searchDocs(...)`, and if
+ * nothing relevant comes back, falls through to `discoverPackages(query)`
+ * to surface install recommendations.
+ *
+ * Phase 4 of the `docs-package-architecture` migration. The catalog
+ * shape is hand-curated and bundled with `@microsoft/rayfin-docs`;
+ * updates ship as `rayfin-docs` version bumps (no hosted endpoint).
+ */
+export type CatalogPackageKind = 'sdk' | 'tool' | 'guide' | 'host' | 'sample' | 'external';
+/** A single entry in the catalog. */
+export interface CatalogPackage {
+    /** Full npm name (e.g. `@microsoft/rayfin-core`). */
+    name: string;
+    /** Kind, used to group results in CLI/MCP surfaces. */
+    kind: CatalogPackageKind;
+    /** One-line summary surfaced in discover results. */
+    summary: string;
+    /** Searchable topics - used by the relevance scorer in
+     *  `discoverPackages(query)`. Should be lowercased. */
+    topics: string[];
+    /** Doc modules this package contributes when installed. Mirrors the
+     *  `rayfinDocs.module` field on the package itself. Empty when the
+     *  package doesn't ship docs yet; SDK entries with no modules are
+     *  kept for package awareness but are omitted from discover results. */
+    modules: string[];
+    /** Optional homepage URL - defaults to the npm page. */
+    homepageUrl?: string;
+    /** Optional install command override - defaults to `npm install <name>`. */
+    installCommand?: string;
+    /** Optional update command override - defaults to `npm install <name>@latest`. */
+    updateCommand?: string;
+}
+export interface Catalog {
+    schemaVersion: 1;
+    /** ISO-8601 timestamp when this catalog was last regenerated. Used by
+     *  consumers to display a "catalog generated YYYY-MM-DD" footer when
+     *  `rayfin docs catalog show` is invoked. */
+    generatedAt: string;
+    packages: CatalogPackage[];
+}
+//# sourceMappingURL=catalog-types.d.ts.map

package/dist/catalog-types.js

@@ -0,0 +1,21 @@
+/**
+ * Bundled static manifest of Rayfin packages.
+ *
+ * Shipped inside `@microsoft/rayfin-docs` to power:
+ * - `rayfin docs discover <query>` (CLI)
+ * - the `discover_packages` MCP tool
+ *
+ * The catalog answers "what packages exist, what could I install, and
+ * what should I update if the installed docs do not include a feature?"
+ * It is INTENTIONALLY decoupled from runtime discovery (which only sees
+ * what's installed in `node_modules`). The two compose: the agent first
+ * checks installed packages via `DocsService.searchDocs(...)`, and if
+ * nothing relevant comes back, falls through to `discoverPackages(query)`
+ * to surface install recommendations.
+ *
+ * Phase 4 of the `docs-package-architecture` migration. The catalog
+ * shape is hand-curated and bundled with `@microsoft/rayfin-docs`;
+ * updates ship as `rayfin-docs` version bumps (no hosted endpoint).
+ */
+export {};
+//# sourceMappingURL=catalog-types.js.map

package/dist/catalog.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Catalog of known Rayfin packages - what exists, what each does, how
+ * to install. Lives in `@microsoft/rayfin-docs` alongside the indexer
+ * because catalog updates and indexer changes share the same trigger
+ * ("we shipped a new SDK package"); splitting them across packages
+ * just multiplies release coordination overhead.
+ *
+ * - {@link getCatalog} returns the static manifest (cached, frozen).
+ * - {@link discoverPackages} ranks catalog packages by query relevance —
+ *   used to power `rayfin docs discover <query>` and the MCP
+ *   `discover_packages` tool when an agent's search through the
+ *   installed corpus comes up empty or the installed package version
+ *   appears too old to contain the requested feature.
+ *
+ * The catalog ships as a static JSON file inside this package's
+ * `assets/` directory. Updates are rolled out as `rayfin-docs` version
+ * bumps - there is no hosted-endpoint refresh path.
+ */
+export type { Catalog, CatalogPackage, CatalogPackageKind, } from './catalog-types.js';
+import type { Catalog, CatalogPackage, CatalogPackageKind } from './catalog-types.js';
+export declare function getCatalog(): Catalog;
+/**
+ * Reset the in-memory catalog cache so the next `getCatalog()` re-reads
+ * the bundled JSON. Test-only export.
+ */
+export declare function _resetCatalogForTesting(): void;
+/** Ranking signal score breakdown - exposed for tests + diagnostics. */
+export interface DiscoverScore {
+    package: CatalogPackage;
+    score: number;
+    /** Which fields contributed. Useful for "why did this match?" UX. */
+    matchedOn: Array<'name' | 'summary' | 'topics' | 'kind'>;
+}
+/**
+ * Rank catalog packages by query relevance. Used by CLI/MCP discover
+ * surfaces. Scoring (deterministic, no embedding):
+ *
+ * - **name** exact substring match: +5
+ * - **kind** exact match (e.g. query "sdk"): +3
+ * - **topic** word match: +2 per matching topic
+ * - **summary** word match: +1 per matching token
+ *
+ * Returns scored packages sorted descending by score; ties broken by
+ * alphabetical package name. Packages with score 0 are excluded.
+ * SDK catalog-only entries with no docs modules are also excluded so
+ * discover results never recommend installing an SDK package that cannot
+ * contribute searchable docs yet.
+ *
+ * Stop-words and tokens shorter than 3 chars are ignored to keep the
+ * signal-to-noise ratio high - the rare "auth" 4-char query still
+ * matches because tokenization is on word boundaries, but "is"/"a"
+ * never match.
+ */
+export declare function discoverPackages(query: string, catalog?: Catalog): DiscoverScore[];
+/** Wire-shape item returned by both the CLI `rayfin docs discover --json`
+ *  and the MCP `discover_packages` tool. Defined here so the two
+ *  surfaces stay in lockstep - adding a field once updates both. */
+export interface DiscoverItem {
+    name: string;
+    kind: CatalogPackageKind;
+    summary: string;
+    topics: string[];
+    installCommand: string;
+    updateCommand: string;
+    versionLockedDocs: string;
+    homepageUrl?: string;
+    score: number;
+    matchedOn: Array<'name' | 'summary' | 'topics' | 'kind'>;
+}
+/** Map a {@link DiscoverScore} to the wire shape consumed by both
+ *  CLI and MCP. Defensive copies of array fields ensure consumers
+ *  can't mutate the catalog singleton's frozen inner arrays via the
+ *  result. */
+export declare function mapDiscoverResult(score: DiscoverScore): DiscoverItem;
+/** Derive an install command for a catalog package. Defaults to
+ * `npm install <name>` unless the catalog entry specifies an
+ * `installCommand` override (e.g. `npm create rayfin@latest`).
+ */
+export declare function deriveInstallCommand(pkg: CatalogPackage): string;
+/** Derive an update command for a catalog package. Agents surface this
+ * when the package is already installed but version-locked docs do not
+ * contain the requested feature.
+ */
+export declare function deriveUpdateCommand(pkg: CatalogPackage): string;
+//# sourceMappingURL=catalog.d.ts.map

package/dist/catalog.js

@@ -0,0 +1,227 @@
+import { readFileSync } from 'fs';
+import { fileURLToPath } from 'url';
+/**
+ * Read the static catalog JSON shipped inside this package's `assets/`
+ * directory. `import.meta.url` after compile points at `dist/catalog.js`;
+ * `assets/catalog.json` lives one level up at the package root.
+ *
+ * Loaded once per process and cached for the lifetime of the process.
+ */
+let catalogCache;
+function loadCatalog() {
+    if (catalogCache)
+        return catalogCache;
+    const path = fileURLToPath(new URL('../assets/catalog.json', import.meta.url));
+    const raw = readFileSync(path, 'utf8');
+    catalogCache = JSON.parse(raw);
+    return catalogCache;
+}
+const CATALOG_SCHEMA_VERSION = 1;
+/**
+ * Return the static catalog as shipped by this package version. The
+ * returned object is the package's own data - frozen so consumers
+ * can't mutate the in-memory copy.
+ */
+let frozenCatalog;
+export function getCatalog() {
+    if (!frozenCatalog) {
+        const data = loadCatalog();
+        frozenCatalog = freezeCatalog(data);
+    }
+    return frozenCatalog;
+}
+/**
+ * Reset the in-memory catalog cache so the next `getCatalog()` re-reads
+ * the bundled JSON. Test-only export.
+ */
+export function _resetCatalogForTesting() {
+    frozenCatalog = undefined;
+    catalogCache = undefined;
+}
+function freezeCatalog(data) {
+    const schemaVersion = data.schemaVersion;
+    if (schemaVersion !== CATALOG_SCHEMA_VERSION) {
+        throw new Error('Unsupported Rayfin docs catalog schema version.');
+    }
+    // Deep freeze on first read. Defensive copy of the embedded JSON so
+    // package consumers can't reach in and mutate the singleton.
+    const copy = {
+        schemaVersion: data.schemaVersion,
+        generatedAt: data.generatedAt,
+        packages: data.packages.map((p) => ({
+            ...p,
+            topics: [...p.topics],
+            modules: [...p.modules],
+        })),
+    };
+    Object.freeze(copy);
+    Object.freeze(copy.packages);
+    for (const p of copy.packages) {
+        Object.freeze(p);
+        Object.freeze(p.topics);
+        Object.freeze(p.modules);
+    }
+    return copy;
+}
+/**
+ * Rank catalog packages by query relevance. Used by CLI/MCP discover
+ * surfaces. Scoring (deterministic, no embedding):
+ *
+ * - **name** exact substring match: +5
+ * - **kind** exact match (e.g. query "sdk"): +3
+ * - **topic** word match: +2 per matching topic
+ * - **summary** word match: +1 per matching token
+ *
+ * Returns scored packages sorted descending by score; ties broken by
+ * alphabetical package name. Packages with score 0 are excluded.
+ * SDK catalog-only entries with no docs modules are also excluded so
+ * discover results never recommend installing an SDK package that cannot
+ * contribute searchable docs yet.
+ *
+ * Stop-words and tokens shorter than 3 chars are ignored to keep the
+ * signal-to-noise ratio high - the rare "auth" 4-char query still
+ * matches because tokenization is on word boundaries, but "is"/"a"
+ * never match.
+ */
+export function discoverPackages(query, catalog = getCatalog()) {
+    const tokens = tokenize(query);
+    if (tokens.length === 0)
+        return [];
+    const queryLower = query.toLowerCase().trim();
+    const scored = [];
+    for (const pkg of catalog.packages) {
+        if (pkg.kind === 'sdk' && pkg.modules.length === 0) {
+            continue;
+        }
+        let score = 0;
+        const matchedOn = [];
+        // Name substring match - strongest signal
+        const nameLower = pkg.name.toLowerCase();
+        if (nameLower.includes(queryLower)) {
+            score += 5;
+            matchedOn.push('name');
+        }
+        else {
+            // Word-by-word match on name (e.g. query "auth fabric" matches
+            // `@microsoft/rayfin-auth-provider-fabric`)
+            for (const token of tokens) {
+                if (nameLower.includes(token)) {
+                    score += 2;
+                    if (!matchedOn.includes('name'))
+                        matchedOn.push('name');
+                }
+            }
+        }
+        // Kind match
+        if (tokens.includes(pkg.kind)) {
+            score += 3;
+            matchedOn.push('kind');
+        }
+        // Topic match - strong signal because topics are curated
+        for (const topic of pkg.topics) {
+            const topicLower = topic.toLowerCase();
+            if (tokens.includes(topicLower)) {
+                score += 2;
+                if (!matchedOn.includes('topics'))
+                    matchedOn.push('topics');
+            }
+            else {
+                // Partial topic match (substring) - weaker signal
+                for (const token of tokens) {
+                    if (token.length >= 4 && topicLower.includes(token)) {
+                        score += 1;
+                        if (!matchedOn.includes('topics'))
+                            matchedOn.push('topics');
+                    }
+                }
+            }
+        }
+        // Summary word match - weakest signal
+        const summaryTokens = tokenize(pkg.summary);
+        for (const token of tokens) {
+            if (summaryTokens.includes(token)) {
+                score += 1;
+                if (!matchedOn.includes('summary'))
+                    matchedOn.push('summary');
+            }
+        }
+        if (score > 0) {
+            scored.push({ package: pkg, score, matchedOn });
+        }
+    }
+    scored.sort((a, b) => {
+        if (a.score !== b.score)
+            return b.score - a.score;
+        return a.package.name.localeCompare(b.package.name);
+    });
+    return scored;
+}
+/** Map a {@link DiscoverScore} to the wire shape consumed by both
+ *  CLI and MCP. Defensive copies of array fields ensure consumers
+ *  can't mutate the catalog singleton's frozen inner arrays via the
+ *  result. */
+export function mapDiscoverResult(score) {
+    const item = {
+        name: score.package.name,
+        kind: score.package.kind,
+        summary: score.package.summary,
+        topics: [...score.package.topics],
+        installCommand: deriveInstallCommand(score.package),
+        updateCommand: deriveUpdateCommand(score.package),
+        versionLockedDocs: 'Docs are served from the package version installed in the current project. If this package is already installed but the feature is missing from search results, upgrade the package and re-run the docs query.',
+        score: score.score,
+        matchedOn: [...score.matchedOn],
+    };
+    if (score.package.homepageUrl) {
+        item.homepageUrl = score.package.homepageUrl;
+    }
+    return item;
+}
+/** Derive an install command for a catalog package. Defaults to
+ * `npm install <name>` unless the catalog entry specifies an
+ * `installCommand` override (e.g. `npm create rayfin@latest`).
+ */
+export function deriveInstallCommand(pkg) {
+    if (pkg.installCommand)
+        return pkg.installCommand;
+    if (pkg.name === '@microsoft/create-rayfin') {
+        return 'npm create rayfin@latest';
+    }
+    return `npm install ${pkg.name}`;
+}
+/** Derive an update command for a catalog package. Agents surface this
+ * when the package is already installed but version-locked docs do not
+ * contain the requested feature.
+ */
+export function deriveUpdateCommand(pkg) {
+    if (pkg.updateCommand)
+        return pkg.updateCommand;
+    if (pkg.name === '@microsoft/create-rayfin') {
+        return 'npm create rayfin@latest';
+    }
+    return `npm install ${pkg.name}@latest`;
+}
+const STOPWORDS = new Set([
+    'and',
+    'the',
+    'for',
+    'with',
+    'how',
+    'what',
+    'when',
+    'where',
+    'this',
+    'that',
+    'from',
+    'into',
+    'onto',
+    'use',
+    'using',
+]);
+function tokenize(input) {
+    return input
+        .toLowerCase()
+        .split(/[^a-z0-9]+/)
+        .filter((t) => t.length >= 3 && !STOPWORDS.has(t));
+}
+//# sourceMappingURL=catalog.js.map

package/dist/discovery.d.ts

@@ -0,0 +1,110 @@
+import type { DocKind, RayfinDocsManifest } from './types.js';
+export type { DocKind } from './types.js';
+/**
+ * A package discovered to declare `rayfinDocs`. Returned by
+ * {@link discoverRayfinDocsPackages} for {@link DocsService} to load.
+ */
+export interface DiscoveredPackage {
+    packageName: string;
+    packageVersion: string;
+    packageRoot: string;
+    manifest: RayfinDocsManifest;
+}
+/**
+ * Function deciding whether a candidate package should be considered
+ * trusted enough to discover. The default ({@link defaultTrust}) accepts
+ * only `@microsoft/rayfin-*` packages. Tests override this.
+ */
+export type TrustPredicate = (packageName: string) => boolean;
+/** Default trust predicate. Auto-trusts the Microsoft Rayfin namespace. */
+export declare const defaultTrust: TrustPredicate;
+/**
+ * Inputs to {@link discoverRayfinDocsPackages}. Callers must choose exactly one
+ * discovery source: `candidates` to probe a fixed catalog list,
+ * `packageRoots` for explicit workspace package folders, or
+ * `scanInstalledPackages: true` to walk all packages under ancestor
+ * `node_modules` directories.
+ */
+export interface DiscoveryOptions {
+    /**
+     * Module identifier or directory used as the resolution base. The
+     * walker calls `createRequire(from).resolve('<pkg>/package.json')`
+     * to locate each candidate. Pass `import.meta.url` from the consuming
+     * module, or a directory path that exists in the project.
+     */
+    from: string;
+    /**
+     * Optional candidate package names to probe for `rayfinDocs`.
+     * An empty array is still an explicit source and returns no packages.
+     */
+    candidates?: readonly string[];
+    /**
+     * Optional explicit package roots to inspect. Used by in-repo tooling such
+     * as the Docusaurus site where package docs are read directly from workspace
+     * package folders instead of an installed `node_modules` tree. An empty
+     * array is still an explicit source and returns no packages.
+     */
+    packageRoots?: readonly string[];
+    /**
+     * Explicit opt-in for scanning every installed package under the nearest
+     * `node_modules` chain. Prefer `candidates` for CLI/MCP agent paths so
+     * discovery stays bounded to the Rayfin package catalog.
+     */
+    scanInstalledPackages?: boolean;
+    /** Trust predicate; defaults to {@link defaultTrust}. */
+    trust?: TrustPredicate;
+}
+/**
+ * Returns whether callers already selected a discovery source.
+ * Wrappers use this to decide whether to inject their own bounded defaults.
+ */
+export declare function hasExplicitDiscoverySource(options: DiscoveryOptions): boolean;
+/**
+ * Resolve each candidate package's `package.json`, validate the
+ * `rayfinDocs` field, and return discovered packages.
+ *
+ * Untrusted packages (per {@link TrustPredicate}) are skipped with a
+ * structured `untrustedSkipped` entry so callers can surface the skip.
+ * Packages that fail manifest validation produce a structured
+ * `invalidManifest` entry rather than throwing - discovery is
+ * defensive: a single broken package shouldn't crash the indexer.
+ */
+export interface DiscoveryResult {
+    discovered: DiscoveredPackage[];
+    notInstalled: string[];
+    untrustedSkipped: string[];
+    invalidManifest: Array<{
+        packageName: string;
+        reason: string;
+    }>;
+}
+export declare function discoverRayfinDocsPackages(options: DiscoveryOptions): DiscoveryResult;
+type ManifestValidation = {
+    ok: true;
+    manifest: RayfinDocsManifest;
+} | {
+    ok: false;
+    kind: 'missing';
+} | {
+    ok: false;
+    kind: 'invalid';
+    reason: string;
+};
+/**
+ * Validate the `rayfinDocs` field on a parsed `package.json`. Returns
+ * a discriminated result so callers can distinguish "no manifest"
+ * (silently skip) from "broken manifest" (surface as warning).
+ *
+ * Path validation rejects absolute paths and parent-directory
+ * traversal in `dir` - discovered packages must keep their docs
+ * inside their own root.
+ */
+export declare function validateRayfinDocsManifest(pkgJson: unknown, packageName: string): ManifestValidation;
+/**
+ * Map a `DocKind` to the legacy `DocModule` value used throughout the
+ * existing CLI/MCP surfaces. Phase 2 keeps the `DocModule` union for
+ * back-compat; `--module ts-sdk` continues to mean "all api-reference
+ * docs" for end users.
+ */
+export declare function docKindToModule(kind: DocKind): 'guide' | 'host' | 'ts-sdk';
+//# sourceMappingURL=discovery.d.ts.map