@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/docs-retrieval.d.ts

@@ -0,0 +1,67 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type AssistDocsSection } from './docs-index.generated';
+/** Lowercase word tokens, stop words removed, length >= 2. */
+export declare function tokenize(text: string): string[];
+export interface ScoredSection {
+    section: AssistDocsSection;
+    score: number;
+}
+/**
+ * Top-`limit` docs sections for a user question. Returns an empty array when
+ * nothing scores above zero — the caller then answers without docs grounding
+ * rather than citing an irrelevant page.
+ */
+export declare function retrieveDocsSections(question: string, limit?: number, sections?: readonly AssistDocsSection[]): ScoredSection[];
+export declare function docsDocumentFrequency(): {
+    frequency: ReadonlyMap<string, number>;
+    sections: number;
+};
+/**
+ * Public docs-site origin for deep links the assistant hands the user.
+ *
+ * Configurable (AGL-2016): a self-hoster who publishes the `apps/docs` site on
+ * their own domain otherwise had every Assist citation deep-link into
+ * `docs.aglyn.com` — our documentation, describing our deployment's flags and
+ * plans, cited as if it were theirs.
+ *
+ * Unlike the operator CONTACT values this keeps our value as the default, and
+ * the difference is deliberate: an unset citation origin degrades to a page
+ * that genuinely exists and is genuinely about this software, so it is wrong
+ * in the way a stale bookmark is wrong. An unset contact address would
+ * misroute a legal notice, which is why that one refuses to guess.
+ *
+ * ⚠️ RE-EXPORTED FROM `DOCS_BASE_URL` RATHER THAN READ AGAIN HERE (AGL-2014).
+ * This module had its own `process.env.NEXT_PUBLIC_DOCS_ORIGIN || 'https://
+ * docs.aglyn.com'`, which accepted ONLY the canonical name — while
+ * `constants/docs-links.ts` also honours the older `NEXT_PUBLIC_AGLYN_DOCS_URL`.
+ * So AGL-2186's own defect survived, inverted, in the one file it did not
+ * touch: a deployment configured under the older name retargeted every console
+ * and besigner help link and left every ASSIST CITATION pointing at
+ * `docs.aglyn.com` — our documentation, cited inside their product as theirs.
+ * That is the same "one value, two env names" split AGL-733 is the record of.
+ * One reader means an operator's docs site cannot be honoured on some surfaces
+ * and ignored on others.
+ */
+export declare const DOCS_SITE_ORIGIN: string;
+/**
+ * The grounding block injected into the system prompt: the retrieved
+ * sections, each with its citable URL, wrapped so the model can quote and
+ * link them. Kept AFTER the stable system prefix so prompt caching of the
+ * static prefix survives per-question variation.
+ */
+export declare function docsGroundingBlock(scored: readonly ScoredSection[]): string;

package/src/lib/app-utils/docs-retrieval.js

@@ -0,0 +1,188 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { ASSIST_DOCS_INDEX } from "./docs-index.generated.js";
+import { DOCS_BASE_URL } from "./docs-help.js";
+/**
+ * Lexical docs retrieval for Aglyn Assist (AGL-1860, phase 1) — deliberately
+ * no vector store: a BM25-flavoured term-frequency score over the generated
+ * docs section index, with title/heading term boosts. Good enough to ground
+ * "how do I…" answers in the right docs section and cheap enough to run on
+ * every message inside the API route.
+ */ /** Words too common in this corpus to carry signal. */ const STOP_WORDS = new Set([
+    'a',
+    'an',
+    'and',
+    'are',
+    'as',
+    'at',
+    'be',
+    'by',
+    'can',
+    'do',
+    'does',
+    'for',
+    'from',
+    'how',
+    'i',
+    'in',
+    'is',
+    'it',
+    'my',
+    'of',
+    'on',
+    'or',
+    'that',
+    'the',
+    'this',
+    'to',
+    'what',
+    'when',
+    'where',
+    'which',
+    'why',
+    'with',
+    'you',
+    'your'
+]);
+/** Lowercase word tokens, stop words removed, length >= 2. */ export function tokenize(text) {
+    var _text_toLowerCase_match;
+    return ((_text_toLowerCase_match = text.toLowerCase().match(RegExp("[\\u0041-\\u005A\\u0061-\\u007A\\u00AA\\u00B5\\u00BA\\u00C0-\\u00D6\\u00D8-\\u00F6\\u00F8-\\u02C1\\u02C6-\\u02D1\\u02E0-\\u02E4\\u02EC\\u02EE\\u0370-\\u0374\\u0376-\\u0377\\u037A-\\u037D\\u037F\\u0386\\u0388-\\u038A\\u038C\\u038E-\\u03A1\\u03A3-\\u03F5\\u03F7-\\u0481\\u048A-\\u052F\\u0531-\\u0556\\u0559\\u0560-\\u0588\\u05D0-\\u05EA\\u05EF-\\u05F2\\u0620-\\u064A\\u066E-\\u066F\\u0671-\\u06D3\\u06D5\\u06E5-\\u06E6\\u06EE-\\u06EF\\u06FA-\\u06FC\\u06FF\\u0710\\u0712-\\u072F\\u074D-\\u07A5\\u07B1\\u07CA-\\u07EA\\u07F4-\\u07F5\\u07FA\\u0800-\\u0815\\u081A\\u0824\\u0828\\u0840-\\u0858\\u0860-\\u086A\\u0870-\\u0887\\u0889-\\u088F\\u08A0-\\u08C9\\u0904-\\u0939\\u093D\\u0950\\u0958-\\u0961\\u0971-\\u0980\\u0985-\\u098C\\u098F-\\u0990\\u0993-\\u09A8\\u09AA-\\u09B0\\u09B2\\u09B6-\\u09B9\\u09BD\\u09CE\\u09DC-\\u09DD\\u09DF-\\u09E1\\u09F0-\\u09F1\\u09FC\\u0A05-\\u0A0A\\u0A0F-\\u0A10\\u0A13-\\u0A28\\u0A2A-\\u0A30\\u0A32-\\u0A33\\u0A35-\\u0A36\\u0A38-\\u0A39\\u0A59-\\u0A5C\\u0A5E\\u0A72-\\u0A74\\u0A85-\\u0A8D\\u0A8F-\\u0A91\\u0A93-\\u0AA8\\u0AAA-\\u0AB0\\u0AB2-\\u0AB3\\u0AB5-\\u0AB9\\u0ABD\\u0AD0\\u0AE0-\\u0AE1\\u0AF9\\u0B05-\\u0B0C\\u0B0F-\\u0B10\\u0B13-\\u0B28\\u0B2A-\\u0B30\\u0B32-\\u0B33\\u0B35-\\u0B39\\u0B3D\\u0B5C-\\u0B5D\\u0B5F-\\u0B61\\u0B71\\u0B83\\u0B85-\\u0B8A\\u0B8E-\\u0B90\\u0B92-\\u0B95\\u0B99-\\u0B9A\\u0B9C\\u0B9E-\\u0B9F\\u0BA3-\\u0BA4\\u0BA8-\\u0BAA\\u0BAE-\\u0BB9\\u0BD0\\u0C05-\\u0C0C\\u0C0E-\\u0C10\\u0C12-\\u0C28\\u0C2A-\\u0C39\\u0C3D\\u0C58-\\u0C5A\\u0C5C-\\u0C5D\\u0C60-\\u0C61\\u0C80\\u0C85-\\u0C8C\\u0C8E-\\u0C90\\u0C92-\\u0CA8\\u0CAA-\\u0CB3\\u0CB5-\\u0CB9\\u0CBD\\u0CDC-\\u0CDE\\u0CE0-\\u0CE1\\u0CF1-\\u0CF2\\u0D04-\\u0D0C\\u0D0E-\\u0D10\\u0D12-\\u0D3A\\u0D3D\\u0D4E\\u0D54-\\u0D56\\u0D5F-\\u0D61\\u0D7A-\\u0D7F\\u0D85-\\u0D96\\u0D9A-\\u0DB1\\u0DB3-\\u0DBB\\u0DBD\\u0DC0-\\u0DC6\\u0E01-\\u0E30\\u0E32-\\u0E33\\u0E40-\\u0E46\\u0E81-\\u0E82\\u0E84\\u0E86-\\u0E8A\\u0E8C-\\u0EA3\\u0EA5\\u0EA7-\\u0EB0\\u0EB2-\\u0EB3\\u0EBD\\u0EC0-\\u0EC4\\u0EC6\\u0EDC-\\u0EDF\\u0F00\\u0F40-\\u0F47\\u0F49-\\u0F6C\\u0F88-\\u0F8C\\u1000-\\u102A\\u103F\\u1050-\\u1055\\u105A-\\u105D\\u1061\\u1065-\\u1066\\u106E-\\u1070\\u1075-\\u1081\\u108E\\u10A0-\\u10C5\\u10C7\\u10CD\\u10D0-\\u10FA\\u10FC-\\u1248\\u124A-\\u124D\\u1250-\\u1256\\u1258\\u125A-\\u125D\\u1260-\\u1288\\u128A-\\u128D\\u1290-\\u12B0\\u12B2-\\u12B5\\u12B8-\\u12BE\\u12C0\\u12C2-\\u12C5\\u12C8-\\u12D6\\u12D8-\\u1310\\u1312-\\u1315\\u1318-\\u135A\\u1380-\\u138F\\u13A0-\\u13F5\\u13F8-\\u13FD\\u1401-\\u166C\\u166F-\\u167F\\u1681-\\u169A\\u16A0-\\u16EA\\u16F1-\\u16F8\\u1700-\\u1711\\u171F-\\u1731\\u1740-\\u1751\\u1760-\\u176C\\u176E-\\u1770\\u1780-\\u17B3\\u17D7\\u17DC\\u1820-\\u1878\\u1880-\\u1884\\u1887-\\u18A8\\u18AA\\u18B0-\\u18F5\\u1900-\\u191E\\u1950-\\u196D\\u1970-\\u1974\\u1980-\\u19AB\\u19B0-\\u19C9\\u1A00-\\u1A16\\u1A20-\\u1A54\\u1AA7\\u1B05-\\u1B33\\u1B45-\\u1B4C\\u1B83-\\u1BA0\\u1BAE-\\u1BAF\\u1BBA-\\u1BE5\\u1C00-\\u1C23\\u1C4D-\\u1C4F\\u1C5A-\\u1C7D\\u1C80-\\u1C8A\\u1C90-\\u1CBA\\u1CBD-\\u1CBF\\u1CE9-\\u1CEC\\u1CEE-\\u1CF3\\u1CF5-\\u1CF6\\u1CFA\\u1D00-\\u1DBF\\u1E00-\\u1F15\\u1F18-\\u1F1D\\u1F20-\\u1F45\\u1F48-\\u1F4D\\u1F50-\\u1F57\\u1F59\\u1F5B\\u1F5D\\u1F5F-\\u1F7D\\u1F80-\\u1FB4\\u1FB6-\\u1FBC\\u1FBE\\u1FC2-\\u1FC4\\u1FC6-\\u1FCC\\u1FD0-\\u1FD3\\u1FD6-\\u1FDB\\u1FE0-\\u1FEC\\u1FF2-\\u1FF4\\u1FF6-\\u1FFC\\u2071\\u207F\\u2090-\\u209C\\u2102\\u2107\\u210A-\\u2113\\u2115\\u2119-\\u211D\\u2124\\u2126\\u2128\\u212A-\\u212D\\u212F-\\u2139\\u213C-\\u213F\\u2145-\\u2149\\u214E\\u2183-\\u2184\\u2C00-\\u2CE4\\u2CEB-\\u2CEE\\u2CF2-\\u2CF3\\u2D00-\\u2D25\\u2D27\\u2D2D\\u2D30-\\u2D67\\u2D6F\\u2D80-\\u2D96\\u2DA0-\\u2DA6\\u2DA8-\\u2DAE\\u2DB0-\\u2DB6\\u2DB8-\\u2DBE\\u2DC0-\\u2DC6\\u2DC8-\\u2DCE\\u2DD0-\\u2DD6\\u2DD8-\\u2DDE\\u2E2F\\u3005-\\u3006\\u3031-\\u3035\\u303B-\\u303C\\u3041-\\u3096\\u309D-\\u309F\\u30A1-\\u30FA\\u30FC-\\u30FF\\u3105-\\u312F\\u3131-\\u318E\\u31A0-\\u31BF\\u31F0-\\u31FF\\u3400-\\u4DBF\\u4E00-\\uA48C\\uA4D0-\\uA4FD\\uA500-\\uA60C\\uA610-\\uA61F\\uA62A-\\uA62B\\uA640-\\uA66E\\uA67F-\\uA69D\\uA6A0-\\uA6E5\\uA717-\\uA71F\\uA722-\\uA788\\uA78B-\\uA7DC\\uA7F1-\\uA801\\uA803-\\uA805\\uA807-\\uA80A\\uA80C-\\uA822\\uA840-\\uA873\\uA882-\\uA8B3\\uA8F2-\\uA8F7\\uA8FB\\uA8FD-\\uA8FE\\uA90A-\\uA925\\uA930-\\uA946\\uA960-\\uA97C\\uA984-\\uA9B2\\uA9CF\\uA9E0-\\uA9E4\\uA9E6-\\uA9EF\\uA9FA-\\uA9FE\\uAA00-\\uAA28\\uAA40-\\uAA42\\uAA44-\\uAA4B\\uAA60-\\uAA76\\uAA7A\\uAA7E-\\uAAAF\\uAAB1\\uAAB5-\\uAAB6\\uAAB9-\\uAABD\\uAAC0\\uAAC2\\uAADB-\\uAADD\\uAAE0-\\uAAEA\\uAAF2-\\uAAF4\\uAB01-\\uAB06\\uAB09-\\uAB0E\\uAB11-\\uAB16\\uAB20-\\uAB26\\uAB28-\\uAB2E\\uAB30-\\uAB5A\\uAB5C-\\uAB69\\uAB70-\\uABE2\\uAC00-\\uD7A3\\uD7B0-\\uD7C6\\uD7CB-\\uD7FB\\uF900-\\uFA6D\\uFA70-\\uFAD9\\uFB00-\\uFB06\\uFB13-\\uFB17\\uFB1D\\uFB1F-\\uFB28\\uFB2A-\\uFB36\\uFB38-\\uFB3C\\uFB3E\\uFB40-\\uFB41\\uFB43-\\uFB44\\uFB46-\\uFBB1\\uFBD3-\\uFD3D\\uFD50-\\uFD8F\\uFD92-\\uFDC7\\uFDF0-\\uFDFB\\uFE70-\\uFE74\\uFE76-\\uFEFC\\uFF21-\\uFF3A\\uFF41-\\uFF5A\\uFF66-\\uFFBE\\uFFC2-\\uFFC7\\uFFCA-\\uFFCF\\uFFD2-\\uFFD7\\uFFDA-\\uFFDC\\u{10000}-\\u{1000B}\\u{1000D}-\\u{10026}\\u{10028}-\\u{1003A}\\u{1003C}-\\u{1003D}\\u{1003F}-\\u{1004D}\\u{10050}-\\u{1005D}\\u{10080}-\\u{100FA}\\u{10280}-\\u{1029C}\\u{102A0}-\\u{102D0}\\u{10300}-\\u{1031F}\\u{1032D}-\\u{10340}\\u{10342}-\\u{10349}\\u{10350}-\\u{10375}\\u{10380}-\\u{1039D}\\u{103A0}-\\u{103C3}\\u{103C8}-\\u{103CF}\\u{10400}-\\u{1049D}\\u{104B0}-\\u{104D3}\\u{104D8}-\\u{104FB}\\u{10500}-\\u{10527}\\u{10530}-\\u{10563}\\u{10570}-\\u{1057A}\\u{1057C}-\\u{1058A}\\u{1058C}-\\u{10592}\\u{10594}-\\u{10595}\\u{10597}-\\u{105A1}\\u{105A3}-\\u{105B1}\\u{105B3}-\\u{105B9}\\u{105BB}-\\u{105BC}\\u{105C0}-\\u{105F3}\\u{10600}-\\u{10736}\\u{10740}-\\u{10755}\\u{10760}-\\u{10767}\\u{10780}-\\u{10785}\\u{10787}-\\u{107B0}\\u{107B2}-\\u{107BA}\\u{10800}-\\u{10805}\\u{10808}\\u{1080A}-\\u{10835}\\u{10837}-\\u{10838}\\u{1083C}\\u{1083F}-\\u{10855}\\u{10860}-\\u{10876}\\u{10880}-\\u{1089E}\\u{108E0}-\\u{108F2}\\u{108F4}-\\u{108F5}\\u{10900}-\\u{10915}\\u{10920}-\\u{10939}\\u{10940}-\\u{10959}\\u{10980}-\\u{109B7}\\u{109BE}-\\u{109BF}\\u{10A00}\\u{10A10}-\\u{10A13}\\u{10A15}-\\u{10A17}\\u{10A19}-\\u{10A35}\\u{10A60}-\\u{10A7C}\\u{10A80}-\\u{10A9C}\\u{10AC0}-\\u{10AC7}\\u{10AC9}-\\u{10AE4}\\u{10B00}-\\u{10B35}\\u{10B40}-\\u{10B55}\\u{10B60}-\\u{10B72}\\u{10B80}-\\u{10B91}\\u{10C00}-\\u{10C48}\\u{10C80}-\\u{10CB2}\\u{10CC0}-\\u{10CF2}\\u{10D00}-\\u{10D23}\\u{10D4A}-\\u{10D65}\\u{10D6F}-\\u{10D85}\\u{10E80}-\\u{10EA9}\\u{10EB0}-\\u{10EB1}\\u{10EC2}-\\u{10EC7}\\u{10F00}-\\u{10F1C}\\u{10F27}\\u{10F30}-\\u{10F45}\\u{10F70}-\\u{10F81}\\u{10FB0}-\\u{10FC4}\\u{10FE0}-\\u{10FF6}\\u{11003}-\\u{11037}\\u{11071}-\\u{11072}\\u{11075}\\u{11083}-\\u{110AF}\\u{110D0}-\\u{110E8}\\u{11103}-\\u{11126}\\u{11144}\\u{11147}\\u{11150}-\\u{11172}\\u{11176}\\u{11183}-\\u{111B2}\\u{111C1}-\\u{111C4}\\u{111DA}\\u{111DC}\\u{11200}-\\u{11211}\\u{11213}-\\u{1122B}\\u{1123F}-\\u{11240}\\u{11280}-\\u{11286}\\u{11288}\\u{1128A}-\\u{1128D}\\u{1128F}-\\u{1129D}\\u{1129F}-\\u{112A8}\\u{112B0}-\\u{112DE}\\u{11305}-\\u{1130C}\\u{1130F}-\\u{11310}\\u{11313}-\\u{11328}\\u{1132A}-\\u{11330}\\u{11332}-\\u{11333}\\u{11335}-\\u{11339}\\u{1133D}\\u{11350}\\u{1135D}-\\u{11361}\\u{11380}-\\u{11389}\\u{1138B}\\u{1138E}\\u{11390}-\\u{113B5}\\u{113B7}\\u{113D1}\\u{113D3}\\u{11400}-\\u{11434}\\u{11447}-\\u{1144A}\\u{1145F}-\\u{11461}\\u{11480}-\\u{114AF}\\u{114C4}-\\u{114C5}\\u{114C7}\\u{11580}-\\u{115AE}\\u{115D8}-\\u{115DB}\\u{11600}-\\u{1162F}\\u{11644}\\u{11680}-\\u{116AA}\\u{116B8}\\u{11700}-\\u{1171A}\\u{11740}-\\u{11746}\\u{11800}-\\u{1182B}\\u{118A0}-\\u{118DF}\\u{118FF}-\\u{11906}\\u{11909}\\u{1190C}-\\u{11913}\\u{11915}-\\u{11916}\\u{11918}-\\u{1192F}\\u{1193F}\\u{11941}\\u{119A0}-\\u{119A7}\\u{119AA}-\\u{119D0}\\u{119E1}\\u{119E3}\\u{11A00}\\u{11A0B}-\\u{11A32}\\u{11A3A}\\u{11A50}\\u{11A5C}-\\u{11A89}\\u{11A9D}\\u{11AB0}-\\u{11AF8}\\u{11BC0}-\\u{11BE0}\\u{11C00}-\\u{11C08}\\u{11C0A}-\\u{11C2E}\\u{11C40}\\u{11C72}-\\u{11C8F}\\u{11D00}-\\u{11D06}\\u{11D08}-\\u{11D09}\\u{11D0B}-\\u{11D30}\\u{11D46}\\u{11D60}-\\u{11D65}\\u{11D67}-\\u{11D68}\\u{11D6A}-\\u{11D89}\\u{11D98}\\u{11DB0}-\\u{11DDB}\\u{11EE0}-\\u{11EF2}\\u{11F02}\\u{11F04}-\\u{11F10}\\u{11F12}-\\u{11F33}\\u{11FB0}\\u{12000}-\\u{12399}\\u{12480}-\\u{12543}\\u{12F90}-\\u{12FF0}\\u{13000}-\\u{1342F}\\u{13441}-\\u{13446}\\u{13460}-\\u{143FA}\\u{14400}-\\u{14646}\\u{16100}-\\u{1611D}\\u{16800}-\\u{16A38}\\u{16A40}-\\u{16A5E}\\u{16A70}-\\u{16ABE}\\u{16AD0}-\\u{16AED}\\u{16B00}-\\u{16B2F}\\u{16B40}-\\u{16B43}\\u{16B63}-\\u{16B77}\\u{16B7D}-\\u{16B8F}\\u{16D40}-\\u{16D6C}\\u{16E40}-\\u{16E7F}\\u{16EA0}-\\u{16EB8}\\u{16EBB}-\\u{16ED3}\\u{16F00}-\\u{16F4A}\\u{16F50}\\u{16F93}-\\u{16F9F}\\u{16FE0}-\\u{16FE1}\\u{16FE3}\\u{16FF2}-\\u{16FF3}\\u{17000}-\\u{18CD5}\\u{18CFF}-\\u{18D1E}\\u{18D80}-\\u{18DF2}\\u{1AFF0}-\\u{1AFF3}\\u{1AFF5}-\\u{1AFFB}\\u{1AFFD}-\\u{1AFFE}\\u{1B000}-\\u{1B122}\\u{1B132}\\u{1B150}-\\u{1B152}\\u{1B155}\\u{1B164}-\\u{1B167}\\u{1B170}-\\u{1B2FB}\\u{1BC00}-\\u{1BC6A}\\u{1BC70}-\\u{1BC7C}\\u{1BC80}-\\u{1BC88}\\u{1BC90}-\\u{1BC99}\\u{1D400}-\\u{1D454}\\u{1D456}-\\u{1D49C}\\u{1D49E}-\\u{1D49F}\\u{1D4A2}\\u{1D4A5}-\\u{1D4A6}\\u{1D4A9}-\\u{1D4AC}\\u{1D4AE}-\\u{1D4B9}\\u{1D4BB}\\u{1D4BD}-\\u{1D4C3}\\u{1D4C5}-\\u{1D505}\\u{1D507}-\\u{1D50A}\\u{1D50D}-\\u{1D514}\\u{1D516}-\\u{1D51C}\\u{1D51E}-\\u{1D539}\\u{1D53B}-\\u{1D53E}\\u{1D540}-\\u{1D544}\\u{1D546}\\u{1D54A}-\\u{1D550}\\u{1D552}-\\u{1D6A5}\\u{1D6A8}-\\u{1D6C0}\\u{1D6C2}-\\u{1D6DA}\\u{1D6DC}-\\u{1D6FA}\\u{1D6FC}-\\u{1D714}\\u{1D716}-\\u{1D734}\\u{1D736}-\\u{1D74E}\\u{1D750}-\\u{1D76E}\\u{1D770}-\\u{1D788}\\u{1D78A}-\\u{1D7A8}\\u{1D7AA}-\\u{1D7C2}\\u{1D7C4}-\\u{1D7CB}\\u{1DF00}-\\u{1DF1E}\\u{1DF25}-\\u{1DF2A}\\u{1E030}-\\u{1E06D}\\u{1E100}-\\u{1E12C}\\u{1E137}-\\u{1E13D}\\u{1E14E}\\u{1E290}-\\u{1E2AD}\\u{1E2C0}-\\u{1E2EB}\\u{1E4D0}-\\u{1E4EB}\\u{1E5D0}-\\u{1E5ED}\\u{1E5F0}\\u{1E6C0}-\\u{1E6DE}\\u{1E6E0}-\\u{1E6E2}\\u{1E6E4}-\\u{1E6E5}\\u{1E6E7}-\\u{1E6ED}\\u{1E6F0}-\\u{1E6F4}\\u{1E6FE}-\\u{1E6FF}\\u{1E7E0}-\\u{1E7E6}\\u{1E7E8}-\\u{1E7EB}\\u{1E7ED}-\\u{1E7EE}\\u{1E7F0}-\\u{1E7FE}\\u{1E800}-\\u{1E8C4}\\u{1E900}-\\u{1E943}\\u{1E94B}\\u{1EE00}-\\u{1EE03}\\u{1EE05}-\\u{1EE1F}\\u{1EE21}-\\u{1EE22}\\u{1EE24}\\u{1EE27}\\u{1EE29}-\\u{1EE32}\\u{1EE34}-\\u{1EE37}\\u{1EE39}\\u{1EE3B}\\u{1EE42}\\u{1EE47}\\u{1EE49}\\u{1EE4B}\\u{1EE4D}-\\u{1EE4F}\\u{1EE51}-\\u{1EE52}\\u{1EE54}\\u{1EE57}\\u{1EE59}\\u{1EE5B}\\u{1EE5D}\\u{1EE5F}\\u{1EE61}-\\u{1EE62}\\u{1EE64}\\u{1EE67}-\\u{1EE6A}\\u{1EE6C}-\\u{1EE72}\\u{1EE74}-\\u{1EE77}\\u{1EE79}-\\u{1EE7C}\\u{1EE7E}\\u{1EE80}-\\u{1EE89}\\u{1EE8B}-\\u{1EE9B}\\u{1EEA1}-\\u{1EEA3}\\u{1EEA5}-\\u{1EEA9}\\u{1EEAB}-\\u{1EEBB}\\u{20000}-\\u{2A6DF}\\u{2A700}-\\u{2B81D}\\u{2B820}-\\u{2CEAD}\\u{2CEB0}-\\u{2EBE0}\\u{2EBF0}-\\u{2EE5D}\\u{2F800}-\\u{2FA1D}\\u{30000}-\\u{3134A}\\u{31350}-\\u{33479}\\u0030-\\u0039\\u00B2-\\u00B3\\u00B9\\u00BC-\\u00BE\\u0660-\\u0669\\u06F0-\\u06F9\\u07C0-\\u07C9\\u0966-\\u096F\\u09E6-\\u09EF\\u09F4-\\u09F9\\u0A66-\\u0A6F\\u0AE6-\\u0AEF\\u0B66-\\u0B6F\\u0B72-\\u0B77\\u0BE6-\\u0BF2\\u0C66-\\u0C6F\\u0C78-\\u0C7E\\u0CE6-\\u0CEF\\u0D58-\\u0D5E\\u0D66-\\u0D78\\u0DE6-\\u0DEF\\u0E50-\\u0E59\\u0ED0-\\u0ED9\\u0F20-\\u0F33\\u1040-\\u1049\\u1090-\\u1099\\u1369-\\u137C\\u16EE-\\u16F0\\u17E0-\\u17E9\\u17F0-\\u17F9\\u1810-\\u1819\\u1946-\\u194F\\u19D0-\\u19DA\\u1A80-\\u1A89\\u1A90-\\u1A99\\u1B50-\\u1B59\\u1BB0-\\u1BB9\\u1C40-\\u1C49\\u1C50-\\u1C59\\u2070\\u2074-\\u2079\\u2080-\\u2089\\u2150-\\u2182\\u2185-\\u2189\\u2460-\\u249B\\u24EA-\\u24FF\\u2776-\\u2793\\u2CFD\\u3007\\u3021-\\u3029\\u3038-\\u303A\\u3192-\\u3195\\u3220-\\u3229\\u3248-\\u324F\\u3251-\\u325F\\u3280-\\u3289\\u32B1-\\u32BF\\uA620-\\uA629\\uA6E6-\\uA6EF\\uA830-\\uA835\\uA8D0-\\uA8D9\\uA900-\\uA909\\uA9D0-\\uA9D9\\uA9F0-\\uA9F9\\uAA50-\\uAA59\\uABF0-\\uABF9\\uFF10-\\uFF19\\u{10107}-\\u{10133}\\u{10140}-\\u{10178}\\u{1018A}-\\u{1018B}\\u{102E1}-\\u{102FB}\\u{10320}-\\u{10323}\\u{10341}\\u{1034A}\\u{103D1}-\\u{103D5}\\u{104A0}-\\u{104A9}\\u{10858}-\\u{1085F}\\u{10879}-\\u{1087F}\\u{108A7}-\\u{108AF}\\u{108FB}-\\u{108FF}\\u{10916}-\\u{1091B}\\u{109BC}-\\u{109BD}\\u{109C0}-\\u{109CF}\\u{109D2}-\\u{109FF}\\u{10A40}-\\u{10A48}\\u{10A7D}-\\u{10A7E}\\u{10A9D}-\\u{10A9F}\\u{10AEB}-\\u{10AEF}\\u{10B58}-\\u{10B5F}\\u{10B78}-\\u{10B7F}\\u{10BA9}-\\u{10BAF}\\u{10CFA}-\\u{10CFF}\\u{10D30}-\\u{10D39}\\u{10D40}-\\u{10D49}\\u{10E60}-\\u{10E7E}\\u{10F1D}-\\u{10F26}\\u{10F51}-\\u{10F54}\\u{10FC5}-\\u{10FCB}\\u{11052}-\\u{1106F}\\u{110F0}-\\u{110F9}\\u{11136}-\\u{1113F}\\u{111D0}-\\u{111D9}\\u{111E1}-\\u{111F4}\\u{112F0}-\\u{112F9}\\u{11450}-\\u{11459}\\u{114D0}-\\u{114D9}\\u{11650}-\\u{11659}\\u{116C0}-\\u{116C9}\\u{116D0}-\\u{116E3}\\u{11730}-\\u{1173B}\\u{118E0}-\\u{118F2}\\u{11950}-\\u{11959}\\u{11BF0}-\\u{11BF9}\\u{11C50}-\\u{11C6C}\\u{11D50}-\\u{11D59}\\u{11DA0}-\\u{11DA9}\\u{11DE0}-\\u{11DE9}\\u{11F50}-\\u{11F59}\\u{11FC0}-\\u{11FD4}\\u{12400}-\\u{1246E}\\u{16130}-\\u{16139}\\u{16A60}-\\u{16A69}\\u{16AC0}-\\u{16AC9}\\u{16B50}-\\u{16B59}\\u{16B5B}-\\u{16B61}\\u{16D70}-\\u{16D79}\\u{16E80}-\\u{16E96}\\u{16FF4}-\\u{16FF6}\\u{1CCF0}-\\u{1CCF9}\\u{1D2C0}-\\u{1D2D3}\\u{1D2E0}-\\u{1D2F3}\\u{1D360}-\\u{1D378}\\u{1D7CE}-\\u{1D7FF}\\u{1E140}-\\u{1E149}\\u{1E2F0}-\\u{1E2F9}\\u{1E4F0}-\\u{1E4F9}\\u{1E5F1}-\\u{1E5FA}\\u{1E8C7}-\\u{1E8CF}\\u{1E950}-\\u{1E959}\\u{1EC71}-\\u{1ECAB}\\u{1ECAD}-\\u{1ECAF}\\u{1ECB1}-\\u{1ECB4}\\u{1ED01}-\\u{1ED2D}\\u{1ED2F}-\\u{1ED3D}\\u{1F100}-\\u{1F10C}\\u{1FBF0}-\\u{1FBF9}]{2,}", "gu"))) != null ? _text_toLowerCase_match : []).filter((token)=>!STOP_WORDS.has(token));
+}
+/**
+ * Score one section against query tokens. Term frequency saturates quickly
+ * (BM25-ish k=1.2) so one section mentioning "domain" ten times does not
+ * drown a section about the actual task; title and heading hits carry
+ * dedicated boosts because those are the docs' own statement of topic.
+ */ function scoreSection(section, queryTokens, bodyTokenCounts, titleTokens, headingTokens) {
+    let score = 0;
+    for (const token of queryTokens){
+        var _bodyTokenCounts_get;
+        const tf = (_bodyTokenCounts_get = bodyTokenCounts.get(token)) != null ? _bodyTokenCounts_get : 0;
+        if (tf > 0) score += tf * 2.2 / (tf + 1.2);
+        if (titleTokens.has(token)) score += 2.5;
+        if (headingTokens.has(token)) score += 2;
+    }
+    return score;
+}
+/** Tokenized once per process — module scope, ~650 sections. */ let indexed = null;
+function buildIndex(sections) {
+    return sections.map((section)=>{
+        const bodyTokenCounts = new Map();
+        for (const token of tokenize(section.text)){
+            var _bodyTokenCounts_get;
+            bodyTokenCounts.set(token, ((_bodyTokenCounts_get = bodyTokenCounts.get(token)) != null ? _bodyTokenCounts_get : 0) + 1);
+        }
+        return {
+            section,
+            bodyTokenCounts,
+            titleTokens: new Set(tokenize(section.title)),
+            headingTokens: new Set(tokenize(section.heading))
+        };
+    });
+}
+/**
+ * Top-`limit` docs sections for a user question. Returns an empty array when
+ * nothing scores above zero — the caller then answers without docs grounding
+ * rather than citing an irrelevant page.
+ */ export function retrieveDocsSections(question, limit = 6, sections = ASSIST_DOCS_INDEX) {
+    const queryTokens = [
+        ...new Set(tokenize(question))
+    ];
+    if (!queryTokens.length) return [];
+    const index = sections === ASSIST_DOCS_INDEX ? indexed != null ? indexed : indexed = buildIndex(sections) : buildIndex(sections);
+    return index.map((entry)=>({
+            section: entry.section,
+            score: scoreSection(entry.section, queryTokens, entry.bodyTokenCounts, entry.titleTokens, entry.headingTokens)
+        })).filter((scored)=>scored.score > 0).sort((a, b)=>b.score - a.score).slice(0, limit);
+}
+/**
+ * How many indexed sections each token appears in — the raw material for an
+ * IDF weight (AGL-2486).
+ *
+ * Lives here rather than in the deflection module because the tokenized index
+ * is already built here and rebuilding it there would tokenize ~500KB of docs
+ * a second time, per process, to reach the same numbers. Memoised alongside
+ * `indexed` and derived from it, so the two can never disagree about what a
+ * token is.
+ *
+ * Counts SECTIONS, not pages: a term confined to one page but repeated in
+ * every section of it is still a specific term, and page-level counting would
+ * flatten exactly the distinction the weight exists to make.
+ */ let documentFrequency = null;
+export function docsDocumentFrequency() {
+    if (!documentFrequency) {
+        const index = indexed != null ? indexed : indexed = buildIndex(ASSIST_DOCS_INDEX);
+        const frequency = new Map();
+        for (const entry of index){
+            const seen = new Set([
+                ...entry.bodyTokenCounts.keys(),
+                ...entry.titleTokens,
+                ...entry.headingTokens
+            ]);
+            for (const token of seen){
+                var _frequency_get;
+                frequency.set(token, ((_frequency_get = frequency.get(token)) != null ? _frequency_get : 0) + 1);
+            }
+        }
+        documentFrequency = frequency;
+    }
+    return {
+        frequency: documentFrequency,
+        sections: ASSIST_DOCS_INDEX.length
+    };
+}
+/**
+ * Public docs-site origin for deep links the assistant hands the user.
+ *
+ * Configurable (AGL-2016): a self-hoster who publishes the `apps/docs` site on
+ * their own domain otherwise had every Assist citation deep-link into
+ * `docs.aglyn.com` — our documentation, describing our deployment's flags and
+ * plans, cited as if it were theirs.
+ *
+ * Unlike the operator CONTACT values this keeps our value as the default, and
+ * the difference is deliberate: an unset citation origin degrades to a page
+ * that genuinely exists and is genuinely about this software, so it is wrong
+ * in the way a stale bookmark is wrong. An unset contact address would
+ * misroute a legal notice, which is why that one refuses to guess.
+ *
+ * ⚠️ RE-EXPORTED FROM `DOCS_BASE_URL` RATHER THAN READ AGAIN HERE (AGL-2014).
+ * This module had its own `process.env.NEXT_PUBLIC_DOCS_ORIGIN || 'https://
+ * docs.aglyn.com'`, which accepted ONLY the canonical name — while
+ * `constants/docs-links.ts` also honours the older `NEXT_PUBLIC_AGLYN_DOCS_URL`.
+ * So AGL-2186's own defect survived, inverted, in the one file it did not
+ * touch: a deployment configured under the older name retargeted every console
+ * and besigner help link and left every ASSIST CITATION pointing at
+ * `docs.aglyn.com` — our documentation, cited inside their product as theirs.
+ * That is the same "one value, two env names" split AGL-733 is the record of.
+ * One reader means an operator's docs site cannot be honoured on some surfaces
+ * and ignored on others.
+ */ export const DOCS_SITE_ORIGIN = DOCS_BASE_URL;
+/**
+ * The grounding block injected into the system prompt: the retrieved
+ * sections, each with its citable URL, wrapped so the model can quote and
+ * link them. Kept AFTER the stable system prefix so prompt caching of the
+ * static prefix survives per-question variation.
+ */ export function docsGroundingBlock(scored) {
+    if (!scored.length) return '';
+    const parts = scored.map(({ section })=>{
+        const url = `${DOCS_SITE_ORIGIN}${section.path}${section.anchor}`;
+        const heading = section.heading ? `${section.title} — ${section.heading}` : section.title;
+        return `<doc url="${url}" title="${heading}">\n${section.text}\n</doc>`;
+    });
+    return `\n\nRelevant documentation sections (cite these URLs when they answer the question):\n${parts.join('\n')}`;
+}
+
+//# sourceMappingURL=docs-retrieval.js.map

package/src/lib/app-utils/docs-retrieval.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/docs-retrieval.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport {\n  ASSIST_DOCS_INDEX,\n  type AssistDocsSection,\n} from './docs-index.generated'\nimport { DOCS_BASE_URL } from './docs-help'\n\n/**\n * Lexical docs retrieval for Aglyn Assist (AGL-1860, phase 1) — deliberately\n * no vector store: a BM25-flavoured term-frequency score over the generated\n * docs section index, with title/heading term boosts. Good enough to ground\n * \"how do I…\" answers in the right docs section and cheap enough to run on\n * every message inside the API route.\n */\n\n/** Words too common in this corpus to carry signal. */\nconst STOP_WORDS = new Set([\n  'a', 'an', 'and', 'are', 'as', 'at', 'be', 'by', 'can', 'do', 'does',\n  'for', 'from', 'how', 'i', 'in', 'is', 'it', 'my', 'of', 'on', 'or',\n  'that', 'the', 'this', 'to', 'what', 'when', 'where', 'which', 'why',\n  'with', 'you', 'your',\n])\n\n/** Lowercase word tokens, stop words removed, length >= 2. */\nexport function tokenize(text: string): string[] {\n  return (text.toLowerCase().match(/[\\p{L}\\p{N}]{2,}/gu) ?? []).filter(\n    (token) => !STOP_WORDS.has(token),\n  )\n}\n\nexport interface ScoredSection {\n  section: AssistDocsSection\n  score: number\n}\n\n/**\n * Score one section against query tokens. Term frequency saturates quickly\n * (BM25-ish k=1.2) so one section mentioning \"domain\" ten times does not\n * drown a section about the actual task; title and heading hits carry\n * dedicated boosts because those are the docs' own statement of topic.\n */\nfunction scoreSection(\n  section: AssistDocsSection,\n  queryTokens: readonly string[],\n  bodyTokenCounts: Map<string, number>,\n  titleTokens: Set<string>,\n  headingTokens: Set<string>,\n): number {\n  let score = 0\n  for (const token of queryTokens) {\n    const tf = bodyTokenCounts.get(token) ?? 0\n    if (tf > 0) score += (tf * 2.2) / (tf + 1.2)\n    if (titleTokens.has(token)) score += 2.5\n    if (headingTokens.has(token)) score += 2\n  }\n  return score\n}\n\ninterface IndexedSection {\n  section: AssistDocsSection\n  bodyTokenCounts: Map<string, number>\n  titleTokens: Set<string>\n  headingTokens: Set<string>\n}\n\n/** Tokenized once per process — module scope, ~650 sections. */\nlet indexed: IndexedSection[] | null = null\n\nfunction buildIndex(sections: readonly AssistDocsSection[]): IndexedSection[] {\n  return sections.map((section) => {\n    const bodyTokenCounts = new Map<string, number>()\n    for (const token of tokenize(section.text)) {\n      bodyTokenCounts.set(token, (bodyTokenCounts.get(token) ?? 0) + 1)\n    }\n    return {\n      section,\n      bodyTokenCounts,\n      titleTokens: new Set(tokenize(section.title)),\n      headingTokens: new Set(tokenize(section.heading)),\n    }\n  })\n}\n\n/**\n * Top-`limit` docs sections for a user question. Returns an empty array when\n * nothing scores above zero — the caller then answers without docs grounding\n * rather than citing an irrelevant page.\n */\nexport function retrieveDocsSections(\n  question: string,\n  limit = 6,\n  sections: readonly AssistDocsSection[] = ASSIST_DOCS_INDEX,\n): ScoredSection[] {\n  const queryTokens = [...new Set(tokenize(question))]\n  if (!queryTokens.length) return []\n  const index =\n    sections === ASSIST_DOCS_INDEX\n      ? (indexed ??= buildIndex(sections))\n      : buildIndex(sections)\n  return index\n    .map((entry) => ({\n      section: entry.section,\n      score: scoreSection(\n        entry.section,\n        queryTokens,\n        entry.bodyTokenCounts,\n        entry.titleTokens,\n        entry.headingTokens,\n      ),\n    }))\n    .filter((scored) => scored.score > 0)\n    .sort((a, b) => b.score - a.score)\n    .slice(0, limit)\n}\n\n/**\n * How many indexed sections each token appears in — the raw material for an\n * IDF weight (AGL-2486).\n *\n * Lives here rather than in the deflection module because the tokenized index\n * is already built here and rebuilding it there would tokenize ~500KB of docs\n * a second time, per process, to reach the same numbers. Memoised alongside\n * `indexed` and derived from it, so the two can never disagree about what a\n * token is.\n *\n * Counts SECTIONS, not pages: a term confined to one page but repeated in\n * every section of it is still a specific term, and page-level counting would\n * flatten exactly the distinction the weight exists to make.\n */\nlet documentFrequency: Map<string, number> | null = null\n\nexport function docsDocumentFrequency(): {\n  frequency: ReadonlyMap<string, number>\n  sections: number\n} {\n  if (!documentFrequency) {\n    const index = (indexed ??= buildIndex(ASSIST_DOCS_INDEX))\n    const frequency = new Map<string, number>()\n    for (const entry of index) {\n      const seen = new Set<string>([\n        ...entry.bodyTokenCounts.keys(),\n        ...entry.titleTokens,\n        ...entry.headingTokens,\n      ])\n      for (const token of seen) {\n        frequency.set(token, (frequency.get(token) ?? 0) + 1)\n      }\n    }\n    documentFrequency = frequency\n  }\n  return { frequency: documentFrequency, sections: ASSIST_DOCS_INDEX.length }\n}\n\n/**\n * Public docs-site origin for deep links the assistant hands the user.\n *\n * Configurable (AGL-2016): a self-hoster who publishes the `apps/docs` site on\n * their own domain otherwise had every Assist citation deep-link into\n * `docs.aglyn.com` — our documentation, describing our deployment's flags and\n * plans, cited as if it were theirs.\n *\n * Unlike the operator CONTACT values this keeps our value as the default, and\n * the difference is deliberate: an unset citation origin degrades to a page\n * that genuinely exists and is genuinely about this software, so it is wrong\n * in the way a stale bookmark is wrong. An unset contact address would\n * misroute a legal notice, which is why that one refuses to guess.\n *\n * ⚠️ RE-EXPORTED FROM `DOCS_BASE_URL` RATHER THAN READ AGAIN HERE (AGL-2014).\n * This module had its own `process.env.NEXT_PUBLIC_DOCS_ORIGIN || 'https://\n * docs.aglyn.com'`, which accepted ONLY the canonical name — while\n * `constants/docs-links.ts` also honours the older `NEXT_PUBLIC_AGLYN_DOCS_URL`.\n * So AGL-2186's own defect survived, inverted, in the one file it did not\n * touch: a deployment configured under the older name retargeted every console\n * and besigner help link and left every ASSIST CITATION pointing at\n * `docs.aglyn.com` — our documentation, cited inside their product as theirs.\n * That is the same \"one value, two env names\" split AGL-733 is the record of.\n * One reader means an operator's docs site cannot be honoured on some surfaces\n * and ignored on others.\n */\nexport const DOCS_SITE_ORIGIN = DOCS_BASE_URL\n\n/**\n * The grounding block injected into the system prompt: the retrieved\n * sections, each with its citable URL, wrapped so the model can quote and\n * link them. Kept AFTER the stable system prefix so prompt caching of the\n * static prefix survives per-question variation.\n */\nexport function docsGroundingBlock(scored: readonly ScoredSection[]): string {\n  if (!scored.length) return ''\n  const parts = scored.map(({ section }) => {\n    const url = `${DOCS_SITE_ORIGIN}${section.path}${section.anchor}`\n    const heading = section.heading\n      ? `${section.title} — ${section.heading}`\n      : section.title\n    return `<doc url=\"${url}\" title=\"${heading}\">\\n${section.text}\\n</doc>`\n  })\n  return `\\n\\nRelevant documentation sections (cite these URLs when they answer the question):\\n${parts.join('\\n')}`\n}\n"],"names":["ASSIST_DOCS_INDEX","DOCS_BASE_URL","STOP_WORDS","Set","tokenize","text","toLowerCase","match","filter","token","has","scoreSection","section","queryTokens","bodyTokenCounts","titleTokens","headingTokens","score","tf","get","indexed","buildIndex","sections","map","Map","set","title","heading","retrieveDocsSections","question","limit","length","index","entry","scored","sort","a","b","slice","documentFrequency","docsDocumentFrequency","frequency","seen","keys","DOCS_SITE_ORIGIN","docsGroundingBlock","parts","url","path","anchor","join"],"mappings":"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"}

package/src/lib/app-utils/document-landmark.d.ts

@@ -0,0 +1,50 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { AglynNodeSchema, NodeId } from '../foundation';
+/**
+ * WHERE A PUBLISHED PAGE'S `main` LANDMARK GOES (AGL-2486).
+ *
+ * The tenant root layout used to wrap every document in one `<main>`. That
+ * guaranteed the landmark existed, and put the site nav and the site footer
+ * INSIDE it — which is the one thing `main` is defined as excluding, and it
+ * makes "skip to content" skip to the top of the chrome it was meant to skip.
+ * It also made `main` unofferable anywhere else: the Section element picker
+ * and the author-HTML allowlist both drop it, because a second `main` is
+ * worse than none, and the root layout already owned the first.
+ *
+ * So the landmark moves to the region it names, and composition decides where
+ * that is:
+ *
+ * 1. An element the AUTHOR chose wins. The Document layer and the Layout Slot
+ *    both offer an HTML-element picker; if either says `main`, that is the
+ *    landmark. When both do, the OUTER one keeps it and the inner is demoted
+ *    to a plain container — the invariant is one per document, and silently
+ *    shipping two is the failure this whole rule exists to prevent.
+ * 2. Otherwise the slot takes it, because a layout's slot is by construction
+ *    "the page content between the chrome".
+ * 3. With no layout there is no slot, so the screen's own root takes it.
+ *
+ * The screens that do NOT compose author nodes — the root error and
+ * not-found boundaries — carry their own; see `StatusScreenPlain` and
+ * `SiteStatusScreen`.
+ *
+ * Inputs are never mutated.
+ */
+export declare const DOCUMENT_LANDMARK_ELEMENT = "main";
+/** Assign the document's single `main` landmark. See the module comment. */
+export declare function stampDocumentLandmark<N extends AglynNodeSchema = AglynNodeSchema>(nodes: Record<NodeId, N>): Record<NodeId, N>;
+export default stampDocumentLandmark;

package/src/lib/app-utils/document-landmark.js

@@ -0,0 +1,100 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { _ as _extends } from "@swc/helpers/_/_extends";
+import { NODE_ROOT_ID } from "../canvas-manager/canvas-manager.js";
+import { LAYOUT_SLOT_COMPONENT_ID } from "./compose-layout-nodes.js";
+/**
+ * WHERE A PUBLISHED PAGE'S `main` LANDMARK GOES (AGL-2486).
+ *
+ * The tenant root layout used to wrap every document in one `<main>`. That
+ * guaranteed the landmark existed, and put the site nav and the site footer
+ * INSIDE it — which is the one thing `main` is defined as excluding, and it
+ * makes "skip to content" skip to the top of the chrome it was meant to skip.
+ * It also made `main` unofferable anywhere else: the Section element picker
+ * and the author-HTML allowlist both drop it, because a second `main` is
+ * worse than none, and the root layout already owned the first.
+ *
+ * So the landmark moves to the region it names, and composition decides where
+ * that is:
+ *
+ * 1. An element the AUTHOR chose wins. The Document layer and the Layout Slot
+ *    both offer an HTML-element picker; if either says `main`, that is the
+ *    landmark. When both do, the OUTER one keeps it and the inner is demoted
+ *    to a plain container — the invariant is one per document, and silently
+ *    shipping two is the failure this whole rule exists to prevent.
+ * 2. Otherwise the slot takes it, because a layout's slot is by construction
+ *    "the page content between the chrome".
+ * 3. With no layout there is no slot, so the screen's own root takes it.
+ *
+ * The screens that do NOT compose author nodes — the root error and
+ * not-found boundaries — carry their own; see `StatusScreenPlain` and
+ * `SiteStatusScreen`.
+ *
+ * Inputs are never mutated.
+ */ export const DOCUMENT_LANDMARK_ELEMENT = 'main';
+/** What a node renders as when it is not the landmark. */ const PLAIN_ELEMENT = 'div';
+/**
+ * The element a node was told to render as. `component`, the name Box and
+ * Typography already use for it — Section's `element` is the outlier, and it
+ * cannot mint a `main` anyway.
+ */ const elementOf = (node)=>{
+    var _ref;
+    var _node_props;
+    return String((_ref = node == null ? void 0 : (_node_props = node.props) == null ? void 0 : _node_props.component) != null ? _ref : '');
+};
+/** Assign the document's single `main` landmark. See the module comment. */ export function stampDocumentLandmark(nodes) {
+    if (!nodes) return nodes;
+    const slotId = Object.keys(nodes).find((id)=>{
+        var _nodes_id;
+        return ((_nodes_id = nodes[id]) == null ? void 0 : _nodes_id.componentId) === LAYOUT_SLOT_COMPONENT_ID;
+    });
+    const rootId = nodes[NODE_ROOT_ID] ? NODE_ROOT_ID : undefined;
+    // Nothing to hang it on. A tree with neither is not a page — an empty
+    // fragment, a preview of one subtree — and inventing a landmark for it
+    // would be the duplicate this function exists to prevent.
+    if (!slotId && !rootId) return nodes;
+    const rootDeclares = rootId ? elementOf(nodes[rootId]) === 'main' : false;
+    const slotDeclares = slotId ? elementOf(nodes[slotId]) === 'main' : false;
+    // Outermost author choice first, then the first node that has not already
+    // been given an element: a slot an author deliberately made a `section`
+    // keeps it, and the landmark falls to the root rather than overruling them.
+    // When both were chosen away from `main`, the page ships without one — the
+    // author said so twice, and quietly reinstating it would make the picker a
+    // suggestion rather than a choice.
+    const landmarkId = rootDeclares ? rootId : slotDeclares ? slotId : slotId && !elementOf(nodes[slotId]) ? slotId : rootId && !elementOf(nodes[rootId]) ? rootId : undefined;
+    // Exactly one: an author who put `main` on both the Document layer and the
+    // slot gets the outer one, and the inner renders as a plain container.
+    const demoteId = rootDeclares && slotDeclares ? slotId : undefined;
+    const next = _extends({}, nodes);
+    if (landmarkId && elementOf(next[landmarkId]) !== DOCUMENT_LANDMARK_ELEMENT) {
+        next[landmarkId] = _extends({}, next[landmarkId], {
+            props: _extends({}, next[landmarkId].props, {
+                component: DOCUMENT_LANDMARK_ELEMENT
+            })
+        });
+    }
+    if (demoteId) {
+        next[demoteId] = _extends({}, next[demoteId], {
+            props: _extends({}, next[demoteId].props, {
+                component: PLAIN_ELEMENT
+            })
+        });
+    }
+    return next;
+}
+export default stampDocumentLandmark;
+
+//# sourceMappingURL=document-landmark.js.map

package/src/lib/app-utils/document-landmark.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/document-landmark.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { AglynNodeSchema, NodeId } from '../foundation'\nimport { NODE_ROOT_ID } from '../canvas-manager/canvas-manager'\nimport { LAYOUT_SLOT_COMPONENT_ID } from './compose-layout-nodes'\n\n/**\n * WHERE A PUBLISHED PAGE'S `main` LANDMARK GOES (AGL-2486).\n *\n * The tenant root layout used to wrap every document in one `<main>`. That\n * guaranteed the landmark existed, and put the site nav and the site footer\n * INSIDE it — which is the one thing `main` is defined as excluding, and it\n * makes \"skip to content\" skip to the top of the chrome it was meant to skip.\n * It also made `main` unofferable anywhere else: the Section element picker\n * and the author-HTML allowlist both drop it, because a second `main` is\n * worse than none, and the root layout already owned the first.\n *\n * So the landmark moves to the region it names, and composition decides where\n * that is:\n *\n * 1. An element the AUTHOR chose wins. The Document layer and the Layout Slot\n *    both offer an HTML-element picker; if either says `main`, that is the\n *    landmark. When both do, the OUTER one keeps it and the inner is demoted\n *    to a plain container — the invariant is one per document, and silently\n *    shipping two is the failure this whole rule exists to prevent.\n * 2. Otherwise the slot takes it, because a layout's slot is by construction\n *    \"the page content between the chrome\".\n * 3. With no layout there is no slot, so the screen's own root takes it.\n *\n * The screens that do NOT compose author nodes — the root error and\n * not-found boundaries — carry their own; see `StatusScreenPlain` and\n * `SiteStatusScreen`.\n *\n * Inputs are never mutated.\n */\nexport const DOCUMENT_LANDMARK_ELEMENT = 'main'\n\n/** What a node renders as when it is not the landmark. */\nconst PLAIN_ELEMENT = 'div'\n\n/**\n * The element a node was told to render as. `component`, the name Box and\n * Typography already use for it — Section's `element` is the outlier, and it\n * cannot mint a `main` anyway.\n */\nconst elementOf = (node: AglynNodeSchema | undefined): string =>\n  String((node?.props as { component?: unknown } | undefined)?.component ?? '')\n\n/** Assign the document's single `main` landmark. See the module comment. */\nexport function stampDocumentLandmark<\n  N extends AglynNodeSchema = AglynNodeSchema,\n>(nodes: Record<NodeId, N>): Record<NodeId, N> {\n  if (!nodes) return nodes\n  const slotId = Object.keys(nodes).find(\n    (id) => nodes[id]?.componentId === LAYOUT_SLOT_COMPONENT_ID,\n  )\n  const rootId = nodes[NODE_ROOT_ID] ? NODE_ROOT_ID : undefined\n  // Nothing to hang it on. A tree with neither is not a page — an empty\n  // fragment, a preview of one subtree — and inventing a landmark for it\n  // would be the duplicate this function exists to prevent.\n  if (!slotId && !rootId) return nodes\n\n  const rootDeclares = rootId ? elementOf(nodes[rootId]) === 'main' : false\n  const slotDeclares = slotId ? elementOf(nodes[slotId]) === 'main' : false\n\n  // Outermost author choice first, then the first node that has not already\n  // been given an element: a slot an author deliberately made a `section`\n  // keeps it, and the landmark falls to the root rather than overruling them.\n  // When both were chosen away from `main`, the page ships without one — the\n  // author said so twice, and quietly reinstating it would make the picker a\n  // suggestion rather than a choice.\n  const landmarkId = rootDeclares\n    ? rootId\n    : slotDeclares\n      ? slotId\n      : slotId && !elementOf(nodes[slotId])\n        ? slotId\n        : rootId && !elementOf(nodes[rootId])\n          ? rootId\n          : undefined\n  // Exactly one: an author who put `main` on both the Document layer and the\n  // slot gets the outer one, and the inner renders as a plain container.\n  const demoteId =\n    rootDeclares && slotDeclares ? slotId : undefined\n\n  const next: Record<NodeId, N> = { ...nodes }\n  if (landmarkId && elementOf(next[landmarkId]) !== DOCUMENT_LANDMARK_ELEMENT) {\n    next[landmarkId] = {\n      ...next[landmarkId],\n      props: {\n        ...(next[landmarkId].props as object),\n        component: DOCUMENT_LANDMARK_ELEMENT,\n      },\n    } as N\n  }\n  if (demoteId) {\n    next[demoteId] = {\n      ...next[demoteId],\n      props: { ...(next[demoteId].props as object), component: PLAIN_ELEMENT },\n    } as N\n  }\n  return next\n}\n\nexport default stampDocumentLandmark\n"],"names":["NODE_ROOT_ID","LAYOUT_SLOT_COMPONENT_ID","DOCUMENT_LANDMARK_ELEMENT","PLAIN_ELEMENT","elementOf","node","String","props","component","stampDocumentLandmark","nodes","slotId","Object","keys","find","id","componentId","rootId","undefined","rootDeclares","slotDeclares","landmarkId","demoteId","next"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC;AAGD,SAASA,YAAY,QAAQ,sCAAkC;AAC/D,SAASC,wBAAwB,QAAQ,4BAAwB;AAEjE;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA4BC,GACD,OAAO,MAAMC,4BAA4B,OAAM;AAE/C,wDAAwD,GACxD,MAAMC,gBAAgB;AAEtB;;;;CAIC,GACD,MAAMC,YAAY,CAACC;;QACTA;WAARC,eAAQD,yBAAAA,cAAAA,KAAME,KAAK,qBAAZ,AAACF,YAAqDG,SAAS,mBAAI;;AAE5E,0EAA0E,GAC1E,OAAO,SAASC,sBAEdC,KAAwB;IACxB,IAAI,CAACA,OAAO,OAAOA;IACnB,MAAMC,SAASC,OAAOC,IAAI,CAACH,OAAOI,IAAI,CACpC,CAACC;YAAOL;eAAAA,EAAAA,YAAAA,KAAK,CAACK,GAAG,qBAATL,UAAWM,WAAW,MAAKf;;IAErC,MAAMgB,SAASP,KAAK,CAACV,aAAa,GAAGA,eAAekB;IACpD,sEAAsE;IACtE,uEAAuE;IACvE,0DAA0D;IAC1D,IAAI,CAACP,UAAU,CAACM,QAAQ,OAAOP;IAE/B,MAAMS,eAAeF,SAASb,UAAUM,KAAK,CAACO,OAAO,MAAM,SAAS;IACpE,MAAMG,eAAeT,SAASP,UAAUM,KAAK,CAACC,OAAO,MAAM,SAAS;IAEpE,0EAA0E;IAC1E,wEAAwE;IACxE,4EAA4E;IAC5E,2EAA2E;IAC3E,2EAA2E;IAC3E,mCAAmC;IACnC,MAAMU,aAAaF,eACfF,SACAG,eACET,SACAA,UAAU,CAACP,UAAUM,KAAK,CAACC,OAAO,IAChCA,SACAM,UAAU,CAACb,UAAUM,KAAK,CAACO,OAAO,IAChCA,SACAC;IACV,2EAA2E;IAC3E,uEAAuE;IACvE,MAAMI,WACJH,gBAAgBC,eAAeT,SAASO;IAE1C,MAAMK,OAA0B,aAAKb;IACrC,IAAIW,cAAcjB,UAAUmB,IAAI,CAACF,WAAW,MAAMnB,2BAA2B;QAC3EqB,IAAI,CAACF,WAAW,GAAG,aACdE,IAAI,CAACF,WAAW;YACnBd,OAAO,aACDgB,IAAI,CAACF,WAAW,CAACd,KAAK;gBAC1BC,WAAWN;;;IAGjB;IACA,IAAIoB,UAAU;QACZC,IAAI,CAACD,SAAS,GAAG,aACZC,IAAI,CAACD,SAAS;YACjBf,OAAO,aAAMgB,IAAI,CAACD,SAAS,CAACf,KAAK;gBAAaC,WAAWL;;;IAE7D;IACA,OAAOoB;AACT;AAEA,eAAed,sBAAqB"}

package/src/lib/app-utils/duplicate-resource.d.ts

@@ -0,0 +1,101 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * Duplicating a resource whole (AGL-2936): the catalog every surface reads.
+ *
+ * One list of the kinds that can be copied, what a copy is called, how its
+ * name and slug are made unique, and the activity code the copy writes —
+ * shared by the row menus and More menus that offer the action, the routes
+ * that perform it, the AI tool that exposes it, and the feed that reports
+ * it. A kind missing from the catalog cannot be offered anywhere, so the
+ * three surfaces cannot disagree about what is duplicable.
+ *
+ * The activity rows are CODES rather than the prose sentences the rest of
+ * the feed stores, for the reason the AI rows are (`ai-activity-actions`):
+ * the code names the kind, the feed translates it once, and a reader who
+ * filters on "duplicated" sees every kind's copies together.
+ *
+ * A theme is absent on purpose. A site holds exactly one, as fields on its
+ * host document rather than as a row in a collection, so there is no list
+ * for a second one to appear in: copying a theme means carrying it to
+ * another site or saving it into a template, and both of those doors
+ * already exist (marketplace install, Save as template).
+ */
+/** The resource kinds a whole copy can be made of. */
+export declare const DUPLICABLE_RESOURCE_KINDS: readonly ["screen", "component", "layout", "template", "form", "emailDesign", "emailTemplate", "campaign", "workflow"];
+export type DuplicableResourceKind = (typeof DUPLICABLE_RESOURCE_KINDS)[number];
+export declare function isDuplicableResourceKind(value: unknown): value is DuplicableResourceKind;
+/**
+ * The kinds that live under a site and are copied by the core server module;
+ * the other two belong to the plugins that own their collections.
+ */
+export declare const DUPLICABLE_HOST_RESOURCE_KINDS: readonly ["screen", "component", "layout", "template", "form", "emailDesign", "workflow"];
+export type DuplicableHostResourceKind = (typeof DUPLICABLE_HOST_RESOURCE_KINDS)[number];
+export declare function isDuplicableHostResourceKind(value: unknown): value is DuplicableHostResourceKind;
+/** The one-line refusal a client shows when the copy is already being made. */
+export declare const DUPLICATE_BUSY_MESSAGE = "That copy is still being made";
+/** What a person calls one of each, in the dialog and the feed. */
+export declare const DUPLICABLE_RESOURCE_NOUNS: Record<DuplicableResourceKind, string>;
+/**
+ * What the copy carries, per kind — the sentence the dialog shows before the
+ * copy is made, so nobody is surprised by what came along and what did not.
+ */
+export declare const DUPLICATE_COPIES: Record<DuplicableResourceKind, readonly string[]>;
+/** The action code each copy writes to the activity logs. */
+export declare const DUPLICATE_ACTIVITY_ACTIONS: Record<DuplicableResourceKind, string>;
+/** What a person reads for each code, in the feed and the actor table. */
+export declare const DUPLICATE_ACTIVITY_ACTION_LABELS: Record<string, string>;
+/** Whether a stored action is one of the duplicate codes. */
+export declare function isDuplicateActivityAction(action: unknown): boolean;
+/** The readable label for a duplicate code; `undefined` for any other action. */
+export declare function duplicateActivityActionLabel(action: unknown): string | undefined;
+/** The name a copy is offered under before anyone edits it. */
+export declare const DUPLICATE_NAME_PREFIX = "Copy of ";
+/** The longest name a copy may carry, matching the create drawers' field. */
+export declare const DUPLICATE_NAME_MAX = 200;
+/**
+ * The default name for a copy of `sourceName`, before uniqueness.
+ *
+ * A copy of a copy does not stack prefixes — `Copy of Copy of Home` tells
+ * nobody anything — so a name already carrying the prefix keeps it, and the
+ * counter {@link uniqueDuplicateName} appends is what tells the two apart.
+ */
+export declare function duplicateDisplayName(sourceName: string | null | undefined): string;
+/**
+ * The first of `requested`, `requested 2`, `requested 3`, … that no sibling
+ * already carries, compared case-insensitively so `Home` and `home` are one
+ * name. A blank request falls back to the prefix alone, never to an empty
+ * name; the counter starts at 2 because the unnumbered name IS the first.
+ */
+export declare function uniqueDuplicateName(requested: string | null | undefined, taken: Iterable<string | null | undefined>): string;
+/** The suffix a copied slug takes so it never claims the original's address. */
+export declare const DUPLICATE_SLUG_SUFFIX = "-copy";
+/**
+ * `<slug>-copy`, then `<slug>-copy-2`, `<slug>-copy-3`, … — the first the
+ * siblings do not carry. A source with no slug yields no slug: the copy is a
+ * draft with no address, and inventing one would be a publish decision made
+ * by a copy button.
+ *
+ * A source that is itself a copy (`about-copy`) does not stack suffixes:
+ * its base is recovered and numbered instead, so a copy of a copy is
+ * `about-copy-2` rather than `about-copy-copy`.
+ */
+export declare function uniqueDuplicateSlug(sourceSlug: string | null | undefined, taken: Iterable<string | null | undefined>): string | undefined;
+/** The note the copy's first version carries: `Duplicated from Home v3`. */
+export declare function duplicateVersionNote(sourceName: string | null | undefined, sourceVersionNumber: number | null | undefined): string;
+/** The AI runtime tool that opens this door for the planner. */
+export declare const DUPLICATE_RESOURCE_TOOL_NAME = "duplicate_resource";