@carlonicora/nestjs-neo4jsonapi 4.4.0 → 4.6.0

package/dist/foundations/handbook/repositories/handbook-thread.repository.js

@@ -0,0 +1,86 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandbookThreadRepository = void 0;
+const common_1 = require("@nestjs/common");
+const nestjs_cls_1 = require("nestjs-cls");
+const abstract_repository_1 = require("../../../core/neo4j/abstracts/abstract.repository");
+const neo4j_service_1 = require("../../../core/neo4j/services/neo4j.service");
+const security_service_1 = require("../../../core/security/services/security.service");
+const handbook_thread_1 = require("../entities/handbook-thread");
+const handbook_thread_meta_1 = require("../entities/handbook-thread.meta");
+const handbook_thread_message_meta_1 = require("../entities/handbook-thread-message.meta");
+/**
+ * HandbookThreadRepository
+ *
+ * `HandbookThread` is `isCompanyScoped: false`, so `buildDefaultMatch()` emits
+ * no company filter at all — the `CREATED_BY` owner edge asserted here is the
+ * ENTIRE security boundary. Without this override every administrator would
+ * read and mutate every other administrator's threads.
+ *
+ * `$currentUserId` is auto-injected into queryParams by
+ * `Neo4jService.initQuery()` (it reads `clsService.get("userId")`), exactly as
+ * `AssistantRepository` relies on.
+ */
+let HandbookThreadRepository = class HandbookThreadRepository extends abstract_repository_1.AbstractRepository {
+    constructor(neo4j, securityService, clsService) {
+        super(neo4j, securityService, clsService);
+        this.descriptor = handbook_thread_1.HandbookThreadDescriptor;
+    }
+    buildUserHasAccess() {
+        const { nodeName } = this.descriptor.model;
+        return `WITH ${nodeName}
+            WHERE EXISTS {
+              MATCH (${nodeName})-[:CREATED_BY]->(:User {id: $currentUserId})
+            }
+            WITH ${nodeName}`;
+    }
+    /**
+     * Bump `updatedAt` so the thread list — ordered by the descriptor default
+     * `updatedAt DESC` — surfaces the conversation a user just spoke in. Neither
+     * creating a child message nor writing the `HAS_MESSAGE` edge touches the
+     * parent node, so without this an active thread would sink below a thread
+     * that was merely renamed.
+     */
+    async touch(params) {
+        await this.neo4j.writeOne({
+            query: `
+        MATCH (${handbook_thread_meta_1.handbookThreadMeta.nodeName}:${handbook_thread_meta_1.handbookThreadMeta.labelName} {id: $id})
+        SET ${handbook_thread_meta_1.handbookThreadMeta.nodeName}.updatedAt = datetime()
+      `,
+            queryParams: { id: params.id },
+        });
+    }
+    /**
+     * Delete the thread AND its messages. `DETACH DELETE` on the thread alone
+     * would drop the `HAS_MESSAGE` edges and orphan every message node, which
+     * — because the messages are only ever reachable through their thread —
+     * means they could never be read or deleted again.
+     *
+     * Mirrors `AssistantRepository.delete`.
+     */
+    async delete(params) {
+        await this.neo4j.writeOne({
+            query: `
+        MATCH (${handbook_thread_meta_1.handbookThreadMeta.nodeName}:${handbook_thread_meta_1.handbookThreadMeta.labelName} {id: $id})
+        OPTIONAL MATCH (${handbook_thread_meta_1.handbookThreadMeta.nodeName})-[:HAS_MESSAGE]->(${handbook_thread_message_meta_1.handbookThreadMessageMeta.nodeName}:${handbook_thread_message_meta_1.handbookThreadMessageMeta.labelName})
+        DETACH DELETE ${handbook_thread_meta_1.handbookThreadMeta.nodeName}, ${handbook_thread_message_meta_1.handbookThreadMessageMeta.nodeName}
+      `,
+            queryParams: { id: params.id },
+        });
+    }
+};
+exports.HandbookThreadRepository = HandbookThreadRepository;
+exports.HandbookThreadRepository = HandbookThreadRepository = __decorate([
+    (0, common_1.Injectable)(),
+    __metadata("design:paramtypes", [neo4j_service_1.Neo4jService, security_service_1.SecurityService, nestjs_cls_1.ClsService])
+], HandbookThreadRepository);
+//# sourceMappingURL=handbook-thread.repository.js.map

package/dist/foundations/handbook/repositories/handbook-thread.repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handbook-thread.repository.js","sourceRoot":"","sources":["../../../../src/foundations/handbook/repositories/handbook-thread.repository.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,2CAA4C;AAC5C,2CAAwC;AACxC,2FAAuF;AACvF,8EAA0E;AAC1E,uFAAmF;AACnF,iEAAuF;AACvF,2EAAsE;AACtE,2FAAqF;AAErF;;;;;;;;;;;GAWG;AAEI,IAAM,wBAAwB,GAA9B,MAAM,wBAAyB,SAAQ,wCAG7C;IAGC,YAAY,KAAmB,EAAE,eAAgC,EAAE,UAAsB;QACvF,KAAK,CAAC,KAAK,EAAE,eAAe,EAAE,UAAU,CAAC,CAAC;QAHzB,eAAU,GAAG,0CAAwB,CAAC;IAIzD,CAAC;IAES,kBAAkB;QAC1B,MAAM,EAAE,QAAQ,EAAE,GAAG,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC;QAC3C,OAAO,QAAQ,QAAQ;;uBAEJ,QAAQ;;mBAEZ,QAAQ,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,KAAK,CAAC,MAAsB;QAChC,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;YACxB,KAAK,EAAE;iBACI,yCAAkB,CAAC,QAAQ,IAAI,yCAAkB,CAAC,SAAS;cAC9D,yCAAkB,CAAC,QAAQ;OAClC;YACD,WAAW,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;OAOG;IACH,KAAK,CAAC,MAAM,CAAC,MAAsB;QACjC,MAAM,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC;YACxB,KAAK,EAAE;iBACI,yCAAkB,CAAC,QAAQ,IAAI,yCAAkB,CAAC,SAAS;0BAClD,yCAAkB,CAAC,QAAQ,sBAAsB,wDAAyB,CAAC,QAAQ,IAAI,wDAAyB,CAAC,SAAS;wBAC5H,yCAAkB,CAAC,QAAQ,KAAK,wDAAyB,CAAC,QAAQ;OACnF;YACD,WAAW,EAAE,EAAE,EAAE,EAAE,MAAM,CAAC,EAAE,EAAE;SAC/B,CAAC,CAAC;IACL,CAAC;CACF,CAAA;AAtDY,4DAAwB;mCAAxB,wBAAwB;IADpC,IAAA,mBAAU,GAAE;qCAOQ,4BAAY,EAAmB,kCAAe,EAAc,uBAAU;GAN9E,wBAAwB,CAsDpC"}

package/dist/foundations/handbook/services/handbook-ingest.service.d.ts

@@ -0,0 +1,121 @@
+import { AppLoggingService } from "../../../core/logging/services/logging.service";
+import { ModelService } from "../../../core/llm/services/model.service";
+import { HandbookModuleConfig } from "../interfaces/handbook.config.interface";
+import { HandbookPageRepository } from "../repositories/handbook-page.repository";
+import { HandbookSectionRepository } from "../repositories/handbook-section.repository";
+import { HandbookPageService } from "./handbook-page.service";
+export type HandbookSyncResult = {
+    created: number;
+    updated: number;
+    unchanged: number;
+    deleted: number;
+    /** Repo-relative paths whose ingest threw. The walk continues past them. */
+    failed: string[];
+};
+export declare class HandbookIngestService {
+    private readonly config;
+    private readonly handbookPageRepository;
+    private readonly handbookSectionRepository;
+    private readonly handbookPageService;
+    private readonly modelService;
+    private readonly logger;
+    constructor(config: Required<HandbookModuleConfig>, handbookPageRepository: HandbookPageRepository, handbookSectionRepository: HandbookSectionRepository, handbookPageService: HandbookPageService, modelService: ModelService, logger: AppLoggingService);
+    sync(): Promise<HandbookSyncResult>;
+    /**
+     * Writes the display translation onto the pages the English walk produced.
+     *
+     * The English tree is the source of truth for WHICH pages exist: a translated
+     * file whose path has no English counterpart is counted and skipped, never
+     * created. Creating it would put an unindexed page in the manual and — worse,
+     * once someone pressed sync again — an English-less page in the retrieval
+     * store.
+     *
+     * Nothing here chunks, embeds or enqueues. `updateDisplay` writes three
+     * properties; `content`, `contentHash` and `aiStatus` are untouched, so the
+     * index after this pass is byte-for-byte the index before it.
+     */
+    private syncDisplay;
+    private walk;
+    /**
+     * Glob support is deliberately the smallest thing that serves the config:
+     * a literal prefix with a trailing `**`, or an exact path. No dependency,
+     * nothing to misread.
+     */
+    private isExcluded;
+    /**
+     * Splits a leading YAML frontmatter block off a markdown file and returns its
+     * scalar keys.
+     *
+     * Still not a YAML parser: the block this reads is a handful of `key: value`
+     * lines, and a dependency buys nothing but new failure modes on a malformed
+     * block. Nested structures and lists are ignored rather than half-parsed.
+     */
+    private splitFrontmatter;
+    /**
+     * The tree's own `README.md` index, parsed — or empty maps when it has none.
+     *
+     * Both roots go through this: the English tree and, when one is configured,
+     * the display tree. A display README's link paths are relative to the display
+     * root, which IS the English relative path, so the summaries it yields key
+     * straight onto the English pages.
+     */
+    private readIndex;
+    private emptyIndex;
+    /**
+     * Reads the tree's own `README.md` index, when it has one.
+     *
+     * Two maps come out: section key to its heading title and blurb, and
+     * repo-relative path to the one-line description the index gives it. Both are
+     * optional by construction — an application with no README gets empty maps,
+     * prettified section titles and pages with no summary, and the manual still
+     * renders.
+     */
+    private parseIndex;
+    /**
+     * Splits a section heading into the key it names and the title to print.
+     *
+     * Two forms are accepted:
+     *
+     * - `## 03-backend` — the bare directory key. The title is derived from it,
+     *   which is all a tree with no authored section names can offer.
+     * - `## 03-backend — Backend` — the key, a dash, and an authored title. The
+     *   title is taken as written.
+     *
+     * The second form is the only place a section name can be written at all: a
+     * section is a DIRECTORY, and a directory has no front matter to carry a
+     * title. It is what lets a translated index name its sections in its own
+     * language, and what lets an English one write "AI" where derivation would
+     * sentence-case `06-ai` into "Ai".
+     *
+     * The separator must carry whitespace on both sides. Keys contain hyphens
+     * (`00-start-here`), so a bare `-` would split the key itself.
+     */
+    private headingOf;
+    /**
+     * The paragraph beneath a section heading, rebuilt into one sentence.
+     *
+     * A README wraps its prose, so the blurb arrives as several lines; joining
+     * the contiguous run is the difference between a summary and a sentence cut
+     * at "and an index". Collection starts at the first line that is neither
+     * blank, nor a list item, nor inside a fenced code block, and stops at the
+     * first blank line or list item after that.
+     *
+     * Fenced blocks are stepped over whole: a section that opens with one — the
+     * a360 handbook's own `## Checking the handbook` does — must be summarised by
+     * its prose, not by a fence or by the command inside it.
+     */
+    private blurbOf;
+    /**
+     * `00-start-here` becomes "Start here". The numeric prefix orders the
+     * directories on disk and is noise on screen; a key with no prefix is used
+     * as written.
+     */
+    private sectionTitle;
+    /**
+     * Frontmatter `title` first, then the first H1, then the filename. The
+     * handbook this was built against uses frontmatter and no H1 at all, so the
+     * H1 branch exists for directories that are written the other way.
+     */
+    private titleOf;
+}
+//# sourceMappingURL=handbook-ingest.service.d.ts.map

package/dist/foundations/handbook/services/handbook-ingest.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handbook-ingest.service.d.ts","sourceRoot":"","sources":["../../../../src/foundations/handbook/services/handbook-ingest.service.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,gDAAgD,CAAC;AACnF,OAAO,EAAE,YAAY,EAAE,MAAM,0CAA0C,CAAC;AAExE,OAAO,EAAmB,oBAAoB,EAAE,MAAM,yCAAyC,CAAC;AAChG,OAAO,EAAE,sBAAsB,EAAE,MAAM,0CAA0C,CAAC;AAClF,OAAO,EAAE,yBAAyB,EAAE,MAAM,6CAA6C,CAAC;AACxF,OAAO,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAC;AAE9D,MAAM,MAAM,kBAAkB,GAAG;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,4EAA4E;IAC5E,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CAAC;AA4BF,qBACa,qBAAqB;IAEL,OAAO,CAAC,QAAQ,CAAC,MAAM;IAChD,OAAO,CAAC,QAAQ,CAAC,sBAAsB;IACvC,OAAO,CAAC,QAAQ,CAAC,yBAAyB;IAC1C,OAAO,CAAC,QAAQ,CAAC,mBAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,YAAY;IAC7B,OAAO,CAAC,QAAQ,CAAC,MAAM;gBALmB,MAAM,EAAE,QAAQ,CAAC,oBAAoB,CAAC,EAC/D,sBAAsB,EAAE,sBAAsB,EAC9C,yBAAyB,EAAE,yBAAyB,EACpD,mBAAmB,EAAE,mBAAmB,EACxC,YAAY,EAAE,YAAY,EAC1B,MAAM,EAAE,iBAAiB;IAGtC,IAAI,IAAI,OAAO,CAAC,kBAAkB,CAAC;IAsJzC;;;;;;;;;;;;OAYG;YACW,WAAW;IAoCzB,OAAO,CAAC,IAAI;IA+CZ;;;;OAIG;IACH,OAAO,CAAC,UAAU;IAQlB;;;;;;;OAOG;IACH,OAAO,CAAC,gBAAgB;IAexB;;;;;;;OAOG;IACH,OAAO,CAAC,SAAS;IAQjB,OAAO,CAAC,UAAU;IAOlB;;;;;;;;OAQG;IACH,OAAO,CAAC,UAAU;IAwBlB;;;;;;;;;;;;;;;;;;OAkBG;IACH,OAAO,CAAC,SAAS;IASjB;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,OAAO;IAwBf;;;;OAIG;IACH,OAAO,CAAC,YAAY;IAMpB;;;;OAIG;IACH,OAAO,CAAC,OAAO;CAShB"}

package/dist/foundations/handbook/services/handbook-ingest.service.js

@@ -0,0 +1,434 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HandbookIngestService = void 0;
+const common_1 = require("@nestjs/common");
+const crypto_1 = require("crypto");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const logging_service_1 = require("../../../core/logging/services/logging.service");
+const model_service_1 = require("../../../core/llm/services/model.service");
+const handbook_config_interface_1 = require("../interfaces/handbook.config.interface");
+const handbook_page_repository_1 = require("../repositories/handbook-page.repository");
+const handbook_section_repository_1 = require("../repositories/handbook-section.repository");
+const handbook_page_service_1 = require("./handbook-page.service");
+/**
+ * Bumped whenever the walk changes how a file becomes a page — frontmatter
+ * handling, title derivation, what is stripped before chunking.
+ *
+ * It is mixed into `contentHash`, so a parsing change invalidates every stored
+ * page and the next sync re-ingests them. Without it the hash only tracks the
+ * file's bytes: a fixed parser leaves every already-ingested page frozen in the
+ * shape the old parser gave it, and the fix silently does nothing. That is
+ * exactly what happened on the 2026-09-11 verification run.
+ */
+const INGEST_FORMAT_VERSION = "2";
+let HandbookIngestService = class HandbookIngestService {
+    constructor(config, handbookPageRepository, handbookSectionRepository, handbookPageService, modelService, logger) {
+        this.config = config;
+        this.handbookPageRepository = handbookPageRepository;
+        this.handbookSectionRepository = handbookSectionRepository;
+        this.handbookPageService = handbookPageService;
+        this.modelService = modelService;
+        this.logger = logger;
+    }
+    async sync() {
+        // FIRST, before the directory is even read. Chunking is not work that
+        // degrades gracefully without AI: every chunk is embedded as it is created
+        // and every chunk queues an extraction call, so an unconfigured
+        // installation would write a thousand nodes and queue a thousand jobs that
+        // all fail inside provider construction. Nothing starts.
+        if (!this.modelService.isAiConfigured()) {
+            this.logger.warn("Handbook sync refused: no usable AI configuration (AI_PROVIDER / AI_MODEL / EMBEDDER_*).");
+            throw new common_1.BadRequestException("AI is not configured: set the AI_* and EMBEDDER_* variables (or an AI connection) before ingesting the handbook.");
+        }
+        const root = this.config.path;
+        if (!root)
+            throw new common_1.BadRequestException("No handbook directory configured. Set `handbook.path` on FoundationsModule.forRoot().");
+        if (!(0, fs_1.existsSync)(root) || !(0, fs_1.statSync)(root).isDirectory())
+            throw new common_1.BadRequestException(`Configured handbook directory does not exist: ${root}`);
+        // Read once, before the walk: the index is optional by construction, so an
+        // application whose documentation tree has no README still ingests — it
+        // just gets prettified section titles and pages with no summary.
+        const index = this.readIndex(root);
+        // The display translation, when the application ships one. It is a mirror
+        // of the English tree under `<root>/<displayPath>` — the same relative
+        // paths, translated prose — and it is SHOWN, never INDEXED: the English
+        // walk skips it through `exclude`, and the pass at the foot of this method
+        // writes its text onto pages the English walk already created. Its own
+        // README is read here because the section write below needs it.
+        const displayPath = this.config.displayPath ?? "";
+        const displayRoot = displayPath.length > 0 ? (0, path_1.join)(root, displayPath) : "";
+        const hasDisplay = displayRoot.length > 0 && (0, fs_1.existsSync)(displayRoot) && (0, fs_1.statSync)(displayRoot).isDirectory();
+        const displayIndex = hasDisplay ? this.readIndex(displayRoot) : this.emptyIndex();
+        const files = this.walk(root, index.summaries);
+        const existing = await this.handbookPageRepository.findAllPages();
+        const byPath = new Map(existing.map((page) => [page.path, page]));
+        const result = { created: 0, updated: 0, unchanged: 0, deleted: 0, failed: [] };
+        for (const file of files) {
+            const page = byPath.get(file.path);
+            try {
+                if (!page) {
+                    const id = (0, crypto_1.randomUUID)();
+                    await this.handbookPageRepository.createPage({
+                        id,
+                        path: file.path,
+                        title: file.title,
+                        content: file.content,
+                        contentHash: file.hash,
+                        wordCount: file.wordCount,
+                        section: file.section,
+                        order: file.order,
+                        summary: file.summary,
+                    });
+                    await this.handbookPageService.chunkAndQueue({
+                        handbookPageId: id,
+                        markdown: file.content,
+                        title: file.title,
+                    });
+                    result.created++;
+                }
+                else if (page.contentHash === file.hash) {
+                    // The bytes did not change, so the chunks are still correct — but the
+                    // index fields may be new (a README summary added, a frontmatter
+                    // `section` corrected), and those cost nothing to rewrite.
+                    await this.handbookPageRepository.updateMetadata({
+                        id: page.id,
+                        title: file.title,
+                        section: file.section,
+                        order: file.order,
+                        summary: file.summary,
+                    });
+                    result.unchanged++;
+                }
+                else {
+                    await this.handbookPageRepository.updatePage({
+                        id: page.id,
+                        title: file.title,
+                        content: file.content,
+                        contentHash: file.hash,
+                        wordCount: file.wordCount,
+                        section: file.section,
+                        order: file.order,
+                        summary: file.summary,
+                    });
+                    await this.handbookPageService.chunkAndQueue({
+                        handbookPageId: page.id,
+                        markdown: file.content,
+                        title: file.title,
+                    });
+                    result.updated++;
+                }
+            }
+            catch (error) {
+                // One unreadable or unchunkable file must not abort the pass: the
+                // remaining documentation is still worth indexing, and the caller gets
+                // the list of what failed.
+                this.logger.error(`Handbook ingest failed for ${file.path}: ${error.message}`);
+                result.failed.push(file.path);
+            }
+        }
+        const seen = new Set(files.map((file) => file.path));
+        for (const page of existing) {
+            if (seen.has(page.path))
+                continue;
+            // Through the service, not the repository: it is what also drops the
+            // page's chunks and resizes the key-concept weights they carried.
+            await this.handbookPageService.delete({ id: page.id });
+            result.deleted++;
+        }
+        // Sections come from the files, never from the index. A README's `##`
+        // headings are prose sections as often as they are directories — a360's own
+        // index carries `Reading orders`, `Conventions`, `Checking the handbook`,
+        // `Adding a page`, `Where to look` and `Gaps and drift` — so accepting
+        // arbitrary headings would print six empty junk sections on the contents
+        // page. A section IS a directory of pages; the index only describes one,
+        // contributing a title and a blurb to a key the walk already observed and
+        // nothing at all to a key it did not.
+        const keys = new Set(files.map((file) => file.section));
+        keys.delete("");
+        await this.handbookSectionRepository.replaceAll({
+            sections: [...keys].sort().map((key) => ({
+                id: (0, crypto_1.randomUUID)(),
+                key,
+                title: index.sections.get(key)?.title ?? this.sectionTitle(key),
+                summary: index.sections.get(key)?.summary,
+                order: key,
+                // The display README describes the same keys — it is a mirror — so a
+                // heading it does not carry simply leaves the section untranslated and
+                // the reading surface falls back to the English title.
+                displayTitle: displayIndex.sections.get(key)?.title,
+                displaySummary: displayIndex.sections.get(key)?.summary,
+            })),
+        });
+        if (hasDisplay)
+            await this.syncDisplay({ displayRoot, displayIndex });
+        this.logger.log(`Handbook sync: ${result.created} created, ${result.updated} updated, ${result.unchanged} unchanged, ${result.deleted} deleted, ${result.failed.length} failed`);
+        return result;
+    }
+    /**
+     * Writes the display translation onto the pages the English walk produced.
+     *
+     * The English tree is the source of truth for WHICH pages exist: a translated
+     * file whose path has no English counterpart is counted and skipped, never
+     * created. Creating it would put an unindexed page in the manual and — worse,
+     * once someone pressed sync again — an English-less page in the retrieval
+     * store.
+     *
+     * Nothing here chunks, embeds or enqueues. `updateDisplay` writes three
+     * properties; `content`, `contentHash` and `aiStatus` are untouched, so the
+     * index after this pass is byte-for-byte the index before it.
+     */
+    async syncDisplay(params) {
+        const files = this.walk(params.displayRoot, params.displayIndex.summaries);
+        // Re-read rather than reuse the map built before the walk: on a first sync
+        // that map is empty, because every page was created moments ago, and every
+        // translation would be reported as an orphan.
+        const pages = await this.handbookPageRepository.findAllPages();
+        const byPath = new Map(pages.map((page) => [page.path, page]));
+        let translated = 0;
+        let orphaned = 0;
+        for (const file of files) {
+            const page = byPath.get(file.path);
+            if (!page) {
+                orphaned++;
+                continue;
+            }
+            await this.handbookPageRepository.updateDisplay({
+                id: page.id,
+                displayTitle: file.title,
+                displaySummary: file.summary,
+                displayContent: file.content,
+            });
+            translated++;
+        }
+        this.logger.log(`Handbook display translation (${this.config.displayPath}): ${translated} pages translated, ${orphaned} translated files with no English counterpart`);
+    }
+    walk(root, summaries = new Map()) {
+        const out = [];
+        const visit = (directory) => {
+            for (const entry of (0, fs_1.readdirSync)(directory, { withFileTypes: true })) {
+                const absolute = (0, path_1.join)(directory, entry.name);
+                if (entry.isDirectory()) {
+                    visit(absolute);
+                    continue;
+                }
+                if (!entry.name.endsWith(".md"))
+                    continue;
+                const path = (0, path_1.relative)(root, absolute).split(path_1.sep).join("/");
+                if (this.isExcluded(path))
+                    continue;
+                const raw = (0, fs_1.readFileSync)(absolute, "utf8");
+                const { frontmatter, body } = this.splitFrontmatter(raw);
+                // Declared section first, then the directory the file sits in. A file at
+                // the tree root with no declaration gets "", and is dropped from the
+                // section list rather than inventing an unnamed one.
+                const section = frontmatter.section ?? path.split("/").slice(0, -1)[0] ?? "";
+                out.push({
+                    path,
+                    section,
+                    order: path.toLowerCase(),
+                    summary: summaries.get(path),
+                    // The BODY is what gets stored, rendered and chunked. Frontmatter is
+                    // metadata about the file, not prose about the subject: embedding
+                    // `sources_verified: 2026-09-10` teaches the retriever nothing and
+                    // dilutes the chunk it lands in.
+                    content: body,
+                    title: this.titleOf({ frontmatterTitle: frontmatter.title, content: body, path }),
+                    // Hashed over the RAW file (so editing only the frontmatter still
+                    // re-ingests the page) plus the format version (so changing the parser
+                    // re-ingests every page).
+                    hash: (0, crypto_1.createHash)("sha256").update(`${INGEST_FORMAT_VERSION}\n${raw}`).digest("hex"),
+                    wordCount: body.split(/\s+/).filter(Boolean).length,
+                });
+            }
+        };
+        visit(root);
+        return out;
+    }
+    /**
+     * Glob support is deliberately the smallest thing that serves the config:
+     * a literal prefix with a trailing `**`, or an exact path. No dependency,
+     * nothing to misread.
+     */
+    isExcluded(path) {
+        return this.config.exclude.some((pattern) => {
+            if (pattern.endsWith("/**"))
+                return path.startsWith(pattern.slice(0, -2));
+            if (pattern.endsWith("**"))
+                return path.startsWith(pattern.slice(0, -2));
+            return path === pattern;
+        });
+    }
+    /**
+     * Splits a leading YAML frontmatter block off a markdown file and returns its
+     * scalar keys.
+     *
+     * Still not a YAML parser: the block this reads is a handful of `key: value`
+     * lines, and a dependency buys nothing but new failure modes on a malformed
+     * block. Nested structures and lists are ignored rather than half-parsed.
+     */
+    splitFrontmatter(raw) {
+        const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+        if (!match)
+            return { frontmatter: {}, body: raw };
+        const frontmatter = {};
+        for (const line of match[1].split(/\r?\n/)) {
+            const pair = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+            if (!pair)
+                continue;
+            const value = pair[2].trim().replace(/^["']|["']$/g, "");
+            if (value)
+                frontmatter[pair[1]] = value;
+        }
+        return { frontmatter, body: raw.slice(match[0].length).trimStart() };
+    }
+    /**
+     * The tree's own `README.md` index, parsed — or empty maps when it has none.
+     *
+     * Both roots go through this: the English tree and, when one is configured,
+     * the display tree. A display README's link paths are relative to the display
+     * root, which IS the English relative path, so the summaries it yields key
+     * straight onto the English pages.
+     */
+    readIndex(directory) {
+        const indexPath = (0, path_1.join)(directory, "README.md");
+        return (0, fs_1.existsSync)(indexPath) ? this.parseIndex((0, fs_1.readFileSync)(indexPath, "utf8")) : this.emptyIndex();
+    }
+    emptyIndex() {
+        return { sections: new Map(), summaries: new Map() };
+    }
+    /**
+     * Reads the tree's own `README.md` index, when it has one.
+     *
+     * Two maps come out: section key to its heading title and blurb, and
+     * repo-relative path to the one-line description the index gives it. Both are
+     * optional by construction — an application with no README gets empty maps,
+     * prettified section titles and pages with no summary, and the manual still
+     * renders.
+     */
+    parseIndex(readme) {
+        const sections = new Map();
+        const summaries = new Map();
+        const blocks = readme.split(/^##\s+/m).slice(1);
+        for (const block of blocks) {
+            const lines = block.split(/\r?\n/);
+            const { key, title } = this.headingOf(lines[0]);
+            sections.set(key, { title, summary: this.blurbOf(lines.slice(1)) });
+        }
+        // `- [Title](path) — summary` across the whole file, section blocks included.
+        const entry = /^-\s*\[[^\]]+\]\(([^)]+)\)\s*[—–-]\s*(.+)$/gm;
+        for (const match of readme.matchAll(entry)) {
+            const path = match[1].split("#")[0].trim();
+            if (path.length > 0)
+                summaries.set(path, match[2].trim());
+        }
+        return { sections, summaries };
+    }
+    /**
+     * Splits a section heading into the key it names and the title to print.
+     *
+     * Two forms are accepted:
+     *
+     * - `## 03-backend` — the bare directory key. The title is derived from it,
+     *   which is all a tree with no authored section names can offer.
+     * - `## 03-backend — Backend` — the key, a dash, and an authored title. The
+     *   title is taken as written.
+     *
+     * The second form is the only place a section name can be written at all: a
+     * section is a DIRECTORY, and a directory has no front matter to carry a
+     * title. It is what lets a translated index name its sections in its own
+     * language, and what lets an English one write "AI" where derivation would
+     * sentence-case `06-ai` into "Ai".
+     *
+     * The separator must carry whitespace on both sides. Keys contain hyphens
+     * (`00-start-here`), so a bare `-` would split the key itself.
+     */
+    headingOf(heading) {
+        const trimmed = heading.trim();
+        const split = trimmed.match(/^(\S+)\s+[—–-]\s+(.+)$/);
+        if (!split)
+            return { key: trimmed, title: this.sectionTitle(trimmed) };
+        return { key: split[1], title: split[2].trim() };
+    }
+    /**
+     * The paragraph beneath a section heading, rebuilt into one sentence.
+     *
+     * A README wraps its prose, so the blurb arrives as several lines; joining
+     * the contiguous run is the difference between a summary and a sentence cut
+     * at "and an index". Collection starts at the first line that is neither
+     * blank, nor a list item, nor inside a fenced code block, and stops at the
+     * first blank line or list item after that.
+     *
+     * Fenced blocks are stepped over whole: a section that opens with one — the
+     * a360 handbook's own `## Checking the handbook` does — must be summarised by
+     * its prose, not by a fence or by the command inside it.
+     */
+    blurbOf(lines) {
+        const paragraph = [];
+        let fenced = false;
+        for (const raw of lines) {
+            const line = raw.trim();
+            if (line.startsWith("```")) {
+                fenced = !fenced;
+                continue;
+            }
+            if (fenced)
+                continue;
+            if (line.length === 0 || line.startsWith("-")) {
+                if (paragraph.length > 0)
+                    break;
+                continue;
+            }
+            paragraph.push(line);
+        }
+        return paragraph.length > 0 ? paragraph.join(" ") : undefined;
+    }
+    /**
+     * `00-start-here` becomes "Start here". The numeric prefix orders the
+     * directories on disk and is noise on screen; a key with no prefix is used
+     * as written.
+     */
+    sectionTitle(key) {
+        const words = key.replace(/^\d+-/, "").replace(/-/g, " ").trim();
+        if (words.length === 0)
+            return key;
+        return words.charAt(0).toUpperCase() + words.slice(1);
+    }
+    /**
+     * Frontmatter `title` first, then the first H1, then the filename. The
+     * handbook this was built against uses frontmatter and no H1 at all, so the
+     * H1 branch exists for directories that are written the other way.
+     */
+    titleOf(params) {
+        if (params.frontmatterTitle)
+            return params.frontmatterTitle;
+        const heading = params.content.match(/^#\s+(.+)$/m);
+        if (heading)
+            return heading[1].trim();
+        const name = params.path.split("/").pop() ?? params.path;
+        return name.replace(/\.md$/, "");
+    }
+};
+exports.HandbookIngestService = HandbookIngestService;
+exports.HandbookIngestService = HandbookIngestService = __decorate([
+    (0, common_1.Injectable)(),
+    __param(0, (0, common_1.Inject)(handbook_config_interface_1.HANDBOOK_CONFIG)),
+    __metadata("design:paramtypes", [Object, handbook_page_repository_1.HandbookPageRepository,
+        handbook_section_repository_1.HandbookSectionRepository,
+        handbook_page_service_1.HandbookPageService,
+        model_service_1.ModelService,
+        logging_service_1.AppLoggingService])
+], HandbookIngestService);
+//# sourceMappingURL=handbook-ingest.service.js.map