crewly 1.11.3 → 1.11.4

package/dist/cli/backend/src/services/wiki/wiki-ingest.service.js

@@ -0,0 +1,212 @@
+/**
+ * WikiIngestService — write canonical pages into a vault's `llm-curated/`.
+ *
+ * Phase A scope per v2.1 spec: append entries to `llm-curated/log.md` for
+ * every chat/spec/learning source. Decisions/pattern pages (separate files
+ * under `llm-curated/decisions/`) are gated behind the LLM routing layer
+ * which lands in Phase B.
+ *
+ * Frozen-path contract (§2): refuses ANY write whose target lives under a
+ * `hardcoded:` folder. SchemaLoaderService.isFrozenPath() is the gate.
+ *
+ * @module services/wiki/wiki-ingest.service
+ */
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { existsSync } from 'fs';
+import { LoggerService } from '../core/logger.service.js';
+import { SchemaLoaderService } from './schema-loader.service.js';
+const DEFAULT_LOG_RELATIVE_PATH = 'llm-curated/log.md';
+const MAX_BODY_BYTES = 64 * 1024;
+// Spec note (Steve, 2026-05-22): the earlier keyword-based
+// `detectMessageShape` heuristic + `buildDecisionSlug` + `ingestDecision`
+// dual-write were REMOVED. Routing into `llm-curated/<folder>/<page>.md`
+// is now agent-driven via `wiki-process-queue` + the agent's own LLM gate
+// — see WikiQueueService for the queue + the orchestrator system prompt
+// for the rule that says "queue worth-saving content as you see it." This
+// service stays low-level: it only writes the path the caller (skill,
+// route, queue processor) specifies, after the frozen-path gate.
+/**
+ * Writes ingest pages to a vault. Construct one per process; stateless.
+ */
+export class WikiIngestService {
+    static instance = null;
+    logger;
+    schemaLoader;
+    constructor(schemaLoader) {
+        this.logger = LoggerService.getInstance().createComponentLogger('WikiIngest');
+        this.schemaLoader = schemaLoader ?? new SchemaLoaderService();
+    }
+    static getInstance() {
+        if (!this.instance) {
+            this.instance = new WikiIngestService();
+        }
+        return this.instance;
+    }
+    /** Test-only reset. */
+    static _resetForTesting() {
+        this.instance = null;
+    }
+    /**
+     * Ingest a single source into the vault.
+     *
+     * Errors are returned as structured outcomes — this method never throws
+     * on legitimate refusals (frozen path, missing schema, empty body) so
+     * callers can fold the result into their normal control flow.
+     */
+    async ingest(input) {
+        const validation = this.validateInput(input);
+        if (validation) {
+            return validation;
+        }
+        let schema;
+        try {
+            schema = await this.schemaLoader.load(input.vaultPath);
+        }
+        catch (err) {
+            return {
+                ok: false,
+                reason: 'schema_missing',
+                message: err.message,
+            };
+        }
+        const target = input.targetRelativePath ?? DEFAULT_LOG_RELATIVE_PATH;
+        if (this.schemaLoader.isFrozenPath(schema, target)) {
+            return {
+                ok: false,
+                reason: 'frozen_path',
+                attemptedPath: target,
+                frozenFolders: this.schemaLoader.getFrozenPaths(schema),
+            };
+        }
+        const absoluteTarget = path.join(input.vaultPath, target);
+        await fs.mkdir(path.dirname(absoluteTarget), { recursive: true });
+        const logEntry = this.formatLogEntry(input);
+        await this.appendOrCreate(absoluteTarget, logEntry, input);
+        this.logger.info('WikiIngest wrote log entry', {
+            vault: input.vaultPath,
+            target,
+            sourceType: input.sourceType,
+            sourceRef: input.sourceRef,
+            bodyBytes: input.sourceBody.length,
+        });
+        return {
+            ok: true,
+            pagesWritten: [target],
+            logEntry,
+            frozenPathsTouched: [],
+        };
+    }
+    // ---------------------------------------------------------------------------
+    // Internals
+    // ---------------------------------------------------------------------------
+    validateInput(input) {
+        if (!input.vaultPath || !path.isAbsolute(input.vaultPath)) {
+            return {
+                ok: false,
+                reason: 'invalid_input',
+                message: `vaultPath must be an absolute path, got "${input.vaultPath ?? ''}"`,
+            };
+        }
+        if (!input.sourceType) {
+            return { ok: false, reason: 'invalid_input', message: 'sourceType is required' };
+        }
+        if (!input.sourceRef) {
+            return { ok: false, reason: 'invalid_input', message: 'sourceRef is required' };
+        }
+        const body = input.sourceBody ?? '';
+        if (body.trim().length === 0) {
+            return {
+                ok: false,
+                reason: 'empty_body',
+                message: 'sourceBody is empty after trimming whitespace',
+            };
+        }
+        if (Buffer.byteLength(body, 'utf8') > MAX_BODY_BYTES) {
+            return {
+                ok: false,
+                reason: 'invalid_input',
+                message: `sourceBody exceeds ${MAX_BODY_BYTES} bytes`,
+            };
+        }
+        return null;
+    }
+    /**
+     * Build the markdown entry. Format is chosen to be safely append-only
+     * (no preceding section to rewrite) and grep-friendly:
+     *
+     *   ## [<ISO>] <sourceType> | <callerSession or sourceRef>
+     *
+     *   ref: <sourceRef>
+     *
+     *   <body>
+     */
+    formatLogEntry(input) {
+        const ts = new Date().toISOString();
+        const header = this.sanitizeOneLine(input.callerSession ?? input.sourceRef, 80);
+        const body = this.sanitizeBody(input.sourceBody);
+        const ref = this.sanitizeOneLine(input.sourceRef, 200);
+        return [
+            '',
+            `## [${ts}] ${input.sourceType} | ${header}`,
+            '',
+            `ref: ${ref}`,
+            '',
+            body,
+            '',
+        ].join('\n');
+    }
+    async appendOrCreate(absolutePath, entry, input) {
+        if (!existsSync(absolutePath)) {
+            const header = this.buildPageHeader(absolutePath, input);
+            await fs.writeFile(absolutePath, header + entry, 'utf8');
+            return;
+        }
+        await fs.appendFile(absolutePath, entry, 'utf8');
+    }
+    /**
+     * Pick the right header for a freshly-created page:
+     *   - `log.md`            → audit-log preamble (append-only)
+     *   - `decisions/*.md`    → decision-page title + provenance block
+     *   - anything else       → minimal title block from the source ref
+     */
+    buildPageHeader(absolutePath, input) {
+        const basename = absolutePath.split(/[/\\]/).pop() ?? '';
+        if (basename === 'log.md') {
+            return '# Activity log\n\nAppend-only log of ingested sources. Each entry: `## [<ISO>] <sourceType> | <caller>`.\n';
+        }
+        if (absolutePath.includes('/decisions/')) {
+            const title = this.sanitizeOneLine(input.sourceBody, 80);
+            const caller = input.callerSession ?? input.sourceRef;
+            return [
+                `# ${title}`,
+                '',
+                `> **source:** \`${this.sanitizeOneLine(input.sourceRef, 200)}\`  `,
+                `> **caller:** \`${this.sanitizeOneLine(caller, 80)}\`  `,
+                `> **recorded:** ${new Date().toISOString()}`,
+                '',
+                '---',
+                '',
+            ].join('\n');
+        }
+        // Generic non-log target: minimal title block.
+        return `# ${this.sanitizeOneLine(input.sourceRef, 80)}\n\n`;
+    }
+    /**
+     * Defuse markers a future skill might mis-route on: `[CHAT]`, `[NOTIFY]`,
+     * `[EVENT]`, `[ESCALATION]` get a zero-width space inserted so they're
+     * still human-readable but don't trigger regex matchers downstream.
+     * (Mirrors the escalation-router sanitizer from PR #606.)
+     */
+    sanitizeBody(body) {
+        const trimmed = body.replace(/\r\n/g, '\n').trim();
+        return trimmed.replace(/\[(CHAT|NOTIFY|EVENT|ESCALATION)\]/g, (_match, tag) => `[​${tag}]`);
+    }
+    sanitizeOneLine(value, maxLen) {
+        const flat = value.replace(/[\r\n]+/g, ' ').replace(/\s+/g, ' ').trim();
+        if (flat.length <= maxLen)
+            return flat;
+        return flat.slice(0, maxLen - 1) + '…';
+    }
+}
+//# sourceMappingURL=wiki-ingest.service.js.map

package/dist/cli/backend/src/services/wiki/wiki-ingest.service.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-ingest.service.js","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-ingest.service.ts"],"names":[],"mappings":"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"}

package/dist/cli/backend/src/services/wiki/wiki-overlay.resolver.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Wiki canonical-folder overlay resolver.
+ *
+ * Some schema-frozen folders in a team vault (`sop/`, `team-norm/`) are
+ * reserved canonical homes whose content actually lives elsewhere on disk and
+ * is read directly by the engine — they were never wired to receive wiki
+ * writes, so they always render empty. Rather than copy/migrate that content
+ * (which would drift), the wiki tree + page endpoints read THROUGH to the real
+ * source so the folders always reflect live content.
+ *
+ * Overlay sources (both PER-TEAM siblings of the vault, so the wiki shows only
+ * what the team actually owns — config/sops/ is a catalog you install FROM,
+ * never shown directly in a team folder):
+ *   - `sop/`       → `<vault>/../sops/`                  (SOPs the team has installed from the catalog)
+ *   - `team-norm/` → `<vault>/../norms/`                 (per-team norms written by update-team-norm)
+ *
+ * @module services/wiki/wiki-overlay.resolver
+ */
+/** Top-level vault folders that read through to a live external source. */
+export type OverlayFolder = 'sop' | 'team-norm';
+/**
+ * Return the real on-disk directory backing a top-level canonical folder, or
+ * null when the folder is not overlayed (the vault's own directory is used).
+ * Both overlay folders resolve to a per-team sibling of the vault.
+ *
+ * @param vaultPath - Absolute path to the vault root (e.g. `.../teams/<id>/wiki`).
+ * @param topFolder - The top-level folder name (e.g. `sop`, `team-norm`, `llm-curated`).
+ * @returns Absolute source directory for read-through, or null.
+ */
+export declare function overlayRootFor(vaultPath: string, topFolder: string): string | null;
+/**
+ * Resolve the absolute file path to read for an overlayed page request, with a
+ * traversal guard against escaping the overlay source root. Returns null when
+ * the relativePath is not under an overlay folder; callers then fall back to
+ * the normal in-vault resolution.
+ *
+ * @param vaultPath - Absolute path to the vault root.
+ * @param relativePath - Vault-relative page path, e.g. `sop/pm/progress-tracking.md`.
+ * @returns Absolute real file path, or null if not overlayed.
+ * @throws Error tagged `overlay_escape` when the path would escape the source root.
+ */
+export declare function resolveOverlayFilePath(vaultPath: string, relativePath: string): string | null;
+//# sourceMappingURL=wiki-overlay.resolver.d.ts.map

package/dist/cli/backend/src/services/wiki/wiki-overlay.resolver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-overlay.resolver.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-overlay.resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,2EAA2E;AAC3E,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,WAAW,CAAC;AAIhD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAKlF;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CACpC,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,GACnB,MAAM,GAAG,IAAI,CAgBf"}

package/dist/cli/backend/src/services/wiki/wiki-overlay.resolver.js

@@ -0,0 +1,67 @@
+/**
+ * Wiki canonical-folder overlay resolver.
+ *
+ * Some schema-frozen folders in a team vault (`sop/`, `team-norm/`) are
+ * reserved canonical homes whose content actually lives elsewhere on disk and
+ * is read directly by the engine — they were never wired to receive wiki
+ * writes, so they always render empty. Rather than copy/migrate that content
+ * (which would drift), the wiki tree + page endpoints read THROUGH to the real
+ * source so the folders always reflect live content.
+ *
+ * Overlay sources (both PER-TEAM siblings of the vault, so the wiki shows only
+ * what the team actually owns — config/sops/ is a catalog you install FROM,
+ * never shown directly in a team folder):
+ *   - `sop/`       → `<vault>/../sops/`                  (SOPs the team has installed from the catalog)
+ *   - `team-norm/` → `<vault>/../norms/`                 (per-team norms written by update-team-norm)
+ *
+ * @module services/wiki/wiki-overlay.resolver
+ */
+import * as path from 'path';
+const OVERLAY_FOLDERS = new Set(['sop', 'team-norm']);
+/**
+ * Return the real on-disk directory backing a top-level canonical folder, or
+ * null when the folder is not overlayed (the vault's own directory is used).
+ * Both overlay folders resolve to a per-team sibling of the vault.
+ *
+ * @param vaultPath - Absolute path to the vault root (e.g. `.../teams/<id>/wiki`).
+ * @param topFolder - The top-level folder name (e.g. `sop`, `team-norm`, `llm-curated`).
+ * @returns Absolute source directory for read-through, or null.
+ */
+export function overlayRootFor(vaultPath, topFolder) {
+    if (!OVERLAY_FOLDERS.has(topFolder))
+        return null;
+    // sop → installed SOPs sibling dir; team-norm → norms sibling dir.
+    const sibling = topFolder === 'sop' ? 'sops' : 'norms';
+    return path.resolve(vaultPath, '..', sibling);
+}
+/**
+ * Resolve the absolute file path to read for an overlayed page request, with a
+ * traversal guard against escaping the overlay source root. Returns null when
+ * the relativePath is not under an overlay folder; callers then fall back to
+ * the normal in-vault resolution.
+ *
+ * @param vaultPath - Absolute path to the vault root.
+ * @param relativePath - Vault-relative page path, e.g. `sop/pm/progress-tracking.md`.
+ * @returns Absolute real file path, or null if not overlayed.
+ * @throws Error tagged `overlay_escape` when the path would escape the source root.
+ */
+export function resolveOverlayFilePath(vaultPath, relativePath) {
+    const normalized = relativePath.replace(/\\/g, '/').replace(/^\/+/, '');
+    const slash = normalized.indexOf('/');
+    if (slash <= 0)
+        return null;
+    const topFolder = normalized.slice(0, slash);
+    const root = overlayRootFor(vaultPath, topFolder);
+    if (!root)
+        return null;
+    const subPath = normalized.slice(slash + 1);
+    const resolved = path.resolve(root, subPath);
+    const rootResolved = path.resolve(root);
+    if (resolved !== rootResolved && !resolved.startsWith(rootResolved + path.sep)) {
+        const err = new Error('overlay path escapes source root');
+        err.name = 'overlay_escape';
+        throw err;
+    }
+    return resolved;
+}
+//# sourceMappingURL=wiki-overlay.resolver.js.map

package/dist/cli/backend/src/services/wiki/wiki-overlay.resolver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-overlay.resolver.js","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-overlay.resolver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAK7B,MAAM,eAAe,GAAwB,IAAI,GAAG,CAAgB,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC;AAE1F;;;;;;;;GAQG;AACH,MAAM,UAAU,cAAc,CAAC,SAAiB,EAAE,SAAiB;IACjE,IAAI,CAAC,eAAe,CAAC,GAAG,CAAC,SAAS,CAAC;QAAE,OAAO,IAAI,CAAC;IACjD,mEAAmE;IACnE,MAAM,OAAO,GAAG,SAAS,KAAK,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IACvD,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;AAChD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,sBAAsB,CACpC,SAAiB,EACjB,YAAoB;IAEpB,MAAM,UAAU,GAAG,YAAY,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,KAAK,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC;IAC5B,MAAM,SAAS,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,CAAC;IAC7C,MAAM,IAAI,GAAG,cAAc,CAAC,SAAS,EAAE,SAAS,CAAC,CAAC;IAClD,IAAI,CAAC,IAAI;QAAE,OAAO,IAAI,CAAC;IACvB,MAAM,OAAO,GAAG,UAAU,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;IAC5C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;IAC7C,MAAM,YAAY,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,QAAQ,KAAK,YAAY,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,YAAY,GAAG,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/E,MAAM,GAAG,GAAG,IAAI,KAAK,CAAC,kCAAkC,CAAC,CAAC;QAC1D,GAAG,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC5B,MAAM,GAAG,CAAC;IACZ,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/cli/backend/src/services/wiki/wiki-search.service.d.ts

@@ -0,0 +1,166 @@
+/**
+ * Wiki Search Service
+ *
+ * In-process full-text search across a wiki vault's `.md` files. Returns
+ * per-file matches with line numbers + short snippets so the UI can render
+ * a result list and let the user jump straight to a page.
+ *
+ * Ranking: Okapi **BM25** (term-frequency saturation via `k1`, length
+ * normalisation via `b`, inverse-document-frequency weighting) computed
+ * per request. No external index — the vaults here are O(100s) of pages so
+ * a per-request scan + score is fine; revisit with a persisted index when
+ * volumes justify it. Tokenisation is Unicode-aware: Latin word tokens plus
+ * individual CJK characters, so Chinese/Japanese content is searchable.
+ *
+ * Scope: walks the vault directory AND the per-team overlay sources
+ * (`sop/` → installed/custom SOPs, `team-norm/` → team norms) so SOP and
+ * norm content is searchable even though it lives outside the vault.
+ *
+ * @module services/wiki/wiki-search.service
+ */
+/** Cap on how many .md files are inspected per search. */
+export declare const WIKI_SEARCH_MAX_FILES = 500;
+/** Cap on how many results returned to the caller. */
+export declare const WIKI_SEARCH_MAX_RESULTS = 50;
+/** Cap on how many snippets surfaced per matching file. */
+export declare const WIKI_SEARCH_MAX_SNIPPETS_PER_FILE = 3;
+/** Maximum query length — guards against pathological input. */
+export declare const WIKI_SEARCH_MAX_QUERY_LENGTH = 200;
+/** Cap on per-file size we will read; larger files are skipped. */
+export declare const WIKI_SEARCH_MAX_FILE_BYTES: number;
+export interface WikiSearchSnippet {
+    /** 1-based line number where the match was found. */
+    lineNumber: number;
+    /** The matching line (trimmed for display). */
+    text: string;
+}
+export interface WikiSearchHit {
+    /** Relative path inside the vault, with forward slashes. */
+    relativePath: string;
+    /** True when the filename itself contains the query. */
+    filenameMatch: boolean;
+    /** Number of total content matches across the file. */
+    matchCount: number;
+    /** BM25 relevance score (higher = better). */
+    score: number;
+    /** Up to `WIKI_SEARCH_MAX_SNIPPETS_PER_FILE` matching lines. */
+    snippets: WikiSearchSnippet[];
+    /** Owning vault path (set for all-vault search; absent for single-vault). */
+    vaultPath?: string;
+    /** Human label for the owning vault (all-vault search only). */
+    vaultLabel?: string;
+}
+export interface WikiSearchResult {
+    ok: true;
+    /** Searched vault path, or '' for an all-vault search. */
+    vaultPath: string;
+    query: string;
+    hits: WikiSearchHit[];
+    /** True when the file/result cap was hit; UI should hint "narrow your search". */
+    truncated: boolean;
+}
+export interface WikiSearchFailure {
+    ok: false;
+    reason: 'vault_missing' | 'invalid_input' | 'invalid_query';
+    message: string;
+}
+export interface WikiSearchInput {
+    vaultPath: string;
+    query: string;
+}
+/** A vault to include in an all-vault search. */
+export interface VaultRef {
+    vaultPath: string;
+    label?: string;
+}
+export interface WikiMultiSearchInput {
+    vaults: VaultRef[];
+    query: string;
+}
+/**
+ * Tokenise text into searchable terms: lowercase Latin word runs
+ * (`[a-z0-9]+`) plus individual CJK characters (Han, Hiragana, Katakana),
+ * so both English and Chinese/Japanese content is matched.
+ *
+ * @param text - Raw text to tokenise.
+ * @returns Array of lowercase tokens (order preserved, duplicates kept).
+ */
+export declare function tokenize(text: string): string[];
+/**
+ * Service exposing `search()`. Stateless singleton — matches the pattern of
+ * the other wiki services (`WikiBookkeepService.getInstance()`, etc.).
+ */
+export declare class WikiSearchService {
+    private static instance;
+    /** Singleton accessor. */
+    static getInstance(): WikiSearchService;
+    /** Reset for tests. */
+    static resetInstance(): void;
+    /** Validate + normalise a query, or return a structured failure. */
+    private validateQuery;
+    /**
+     * Search a single vault and rank results with BM25. Returns either
+     * `{ok:true, hits}` or a structured failure. Filesystem read errors are
+     * silently skipped so one bad file doesn't blank the whole result.
+     */
+    search(input: WikiSearchInput): Promise<WikiSearchResult | WikiSearchFailure>;
+    /**
+     * Search across MANY vaults and return one merged BM25-ranked list. IDF is
+     * computed over the combined corpus so scores are comparable across vaults.
+     * Each hit carries its owning `vaultPath` (+ `vaultLabel` when provided).
+     */
+    searchAllVaults(input: WikiMultiSearchInput): Promise<WikiSearchResult | WikiSearchFailure>;
+    /**
+     * BM25-rank an explicit list of documents (rather than auto-collecting the
+     * whole vault). Lets callers that need their own eligibility rules — e.g. the
+     * `wiki-query` skill, which ranks only `llm-curated/` pages and skips
+     * `log.md` — reuse the exact same Okapi BM25 scoring with IDF computed over
+     * precisely the documents they supply.
+     *
+     * @param vaultPath - Owning vault (stamped on each hit's `vaultPath`).
+     * @param docs - Candidate documents as `{ relativePath, absPath }`.
+     * @param query - Raw query string (validated/normalised here).
+     * @returns BM25-ranked hits, or an empty array for an invalid/empty query.
+     */
+    searchCorpus(vaultPath: string, docs: Array<{
+        relativePath: string;
+        absPath: string;
+    }>, query: string): Promise<WikiSearchHit[]>;
+    /**
+     * Core BM25 search over an arbitrary corpus of doc refs (one or many vaults).
+     * Builds the combined corpus statistics, scores, ranks, and attaches snippets
+     * for the top results. Each hit carries its owning `vaultPath`.
+     */
+    private _searchCorpus;
+    /**
+     * Collect candidate `.md` documents: the vault tree plus the per-team
+     * overlay sources (`sop/`, `team-norm/`). Overlay paths are prefixed with
+     * the folder name so they resolve back through the page endpoint.
+     *
+     * @param vaultPath - Absolute vault root.
+     * @returns Deduped list of `{ relativePath, absPath }`, capped at the limit.
+     */
+    private collectDocs;
+    /**
+     * Recursively collect `.md` files under `root`, returned as root-relative
+     * POSIX paths. Skips dotfile dirs (`.git`, `.queue`) and stops at the cap.
+     */
+    private walkMd;
+    /**
+     * Read a doc and compute its length + per-query-term frequencies. Filename
+     * tokens are folded in (weighted) so title relevance contributes to BM25.
+     * Returns null only on unreadable/oversize files with no filename match.
+     */
+    private statDoc;
+    /**
+     * Standard Okapi BM25 score for a doc against the query terms.
+     */
+    private bm25Score;
+    /**
+     * Re-read a top-ranked file and extract matching-line snippets (a line
+     * matches when it contains any query term as a substring). Returns the
+     * total content match count + up to the snippet cap.
+     */
+    private buildSnippets;
+}
+//# sourceMappingURL=wiki-search.service.d.ts.map

package/dist/cli/backend/src/services/wiki/wiki-search.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wiki-search.service.d.ts","sourceRoot":"","sources":["../../../../../../backend/src/services/wiki/wiki-search.service.ts"],"names":[],"mappings":"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"}