@aglyn/aglyn 1.0.0-beta.143

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

@@ -0,0 +1,547 @@
+/**
+ * @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 { DOCS_SITE_ORIGIN, docsDocumentFrequency, tokenize } from "./docs-retrieval.js";
+/**
+ * Retrieval-first answering for Aglyn Assist (AGL-2486) — the deflection gate.
+ *
+ * Most assist traffic is "how do I X", and the answer to "how do I X" is
+ * already written down in `apps/docs/docs`. Sending that question to a model
+ * so the model can read the docs section back to the user pays provider money
+ * to reformat prose we wrote ourselves. This module decides when retrieval is
+ * confident enough to hand the docs straight over, and composes the answer
+ * when it is. Escalation to the model is what happens the rest of the time —
+ * it is the fallback, not the default.
+ *
+ * ## The one rule: never fabricate
+ *
+ * A deflected answer contains exactly two kinds of text:
+ *
+ *   1. Fixed template strings from this file, which say nothing about the
+ *      product — they name the page and introduce the quote.
+ *   2. Section text copied VERBATIM out of the docs index, with the URL of
+ *      the page it came from.
+ *
+ * There is no summarisation, no paraphrase and no stitching of adjacent
+ * sections into a claim neither one makes. The spec asserts it by
+ * RECONSTRUCTION — "never fabricate — every word is template or verbatim
+ * docs" — stripping the template from a composed answer and requiring what is
+ * left to be a prefix of a real section's `text`. That property is the whole
+ * safety argument, because a wrong retrieval answer is worse than an
+ * escalation — it is confidently wrong prose delivered to a paying customer
+ * with a citation under it, which is the shape people trust most.
+ *
+ * ## What "confident" means
+ *
+ * Seven conditions, ALL of which must hold. Any one failing escalates; there
+ * is no partial-credit path where a weak match produces a hedged answer,
+ * because a hedged wrong answer is still a wrong answer and it has already
+ * cost the user the click.
+ *
+ *   1. **The question stands on its own.** A follow-up is usually not
+ *      self-contained: "does that work on the free plan?" retrieves the
+ *      billing pages beautifully and answers a question nobody asked. The
+ *      conversation is the missing half and only the model has it.
+ *
+ *      The gate is NOT "no prior turn" (AGL-2486). Not every follow-up leans
+ *      on the transcript: the second question in a thread is very often a
+ *      fresh, complete question that happens to be asked second. Refusing all
+ *      of them means a thread answers its first question from the docs and
+ *      then escalates forever — and on a deployment with no AI provider
+ *      key that reads as "Aglyn Assist is not configured",
+ *      one question in, to a user who just watched it work. A product that
+ *      answers exactly once per thread is worse than one that never answers,
+ *      because the second refusal looks like a fault rather than a limit.
+ *
+ *      So the gate now asks whether THIS question stands alone, and holds a
+ *      raised bar when it does — see {@link questionStandsAlone} and the
+ *      `FOLLOW_UP_*` constants.
+ *   2. **Enough question.** At least {@link MIN_QUESTION_TOKENS} distinct
+ *      content tokens after stop-word removal. Below that there is not enough
+ *      of a question to be confident ABOUT.
+ *   3. **Not a generative request.** "write me a hero headline" is the copy
+ *      assistant's job, not a docs lookup, and no docs page answers it.
+ *   4. **Not a diagnostic.** "why isn't my domain verifying" has a
+ *      troubleshooting page, and dumping that page at someone whose actual
+ *      problem is one of nine listed causes is exactly the confidently-wrong
+ *      failure. Diagnostics need the workspace's own state, which is the
+ *      level-2 context only the model gets.
+ *   5. **Absolute score.** The top section scores at least
+ *      {@link MIN_TOP_SCORE}.
+ *   6. **Page dominance.** The winning page beats the best RIVAL page by at
+ *      least {@link MIN_PAGE_MARGIN}. Measured against the runner-up page
+ *      rather than as a share of the whole retrieved set, because the set is
+ *      six sections wide: a page that is unambiguously right still holds a
+ *      minority of a six-way split the moment three neighbouring pages use the
+ *      same nouns, and a share test reads that dilution as doubt. And the
+ *      comparison is page-to-page, not section-to-section — sections of ONE
+ *      page scoring alike is agreement, which a section margin scores as a tie.
+ *   7. **Substance.** The winning section carries at least
+ *      {@link MIN_SECTION_CHARS} of text. A three-word stub under a heading is
+ *      a pointer, not an answer.
+ *
+ * Below the bar the request proceeds exactly as it did before this module
+ * existed: the same sections are still retrieved and still ground the model's
+ * prompt. Deflection removes model calls; it never removes grounding.
+ *
+ * ## The thresholds are measured, not guessed
+ *
+ * `docs-deflection.spec.ts` carries a fixed set of realistic questions —
+ * positives written in user vocabulary rather than lifted from docs headings,
+ * and negatives that MUST escalate — and asserts a floor on the deflection
+ * rate and a ceiling of zero on the negatives. Retuning a constant here
+ * without rerunning that spec is how a threshold ends up set by whoever
+ * touched it last.
+ */ /**
+ * Distinct content tokens a question needs before it can be answered.
+ *
+ * Two, not three, and the difference is most of the corpus: "how do I install
+ * a plugin", "what are dataset relations" and "how do I cancel my
+ * subscription" all reduce to exactly two content tokens once the stop words
+ * go, and every one of them is a plain docs lookup. Three excluded them all.
+ *
+ * Two is safe here only because the gates below are not a checklist a weak
+ * question can pass by being short: a two-token question must have BOTH
+ * tokens carried by the winning page (the IDF weighting cannot rescue it —
+ * there is nothing generic to discount), and the page must still clear the
+ * score floor and out-score its rival. "is my site down" has two tokens and
+ * fails on dominance, not on length.
+ */ const MIN_QUESTION_TOKENS = 2;
+/**
+ * Absolute floor on the winning section's retrieval score.
+ *
+ * The scorer gives 2.5 for a title hit, 2 for a heading hit and up to ~2.2 per
+ * body term — about 6.7 for one term landing everywhere at once. 5 is
+ * therefore roughly "two question terms landed and at least one of them hit
+ * the page's own statement of topic". Below that the match is incidental
+ * vocabulary rather than a page about the thing.
+ *
+ * Measured down from 6, which cost five ordinary lookups scoring 4.4–5.9
+ * ("how do I cancel my subscription", "how do I set up sso for my team") and
+ * bought nothing: the negative set does not move between the two values,
+ * because what actually stops those is coverage and dominance, not the floor.
+ */ const MIN_TOP_SCORE = 5;
+/**
+ * How far the winning page must out-score the best rival page.
+ *
+ * 1.3x — the winner needs a visible lead, not a photo finish. Two pages
+ * within 30% of each other on the same question means retrieval genuinely
+ * does not know which one the user meant, and picking is a coin flip dressed
+ * up as an answer.
+ *
+ * A question that retrieves only ONE page has no rival and passes this gate
+ * outright; the score floor and coverage are what bound it there.
+ */ const MIN_PAGE_MARGIN = 1.3;
+/**
+ * Weighted fraction of the question the winning page must actually contain.
+ * Coverage and score answer different questions: score says the page matched
+ * strongly, coverage says the page did not IGNORE part of what was asked.
+ * "how do I password protect a screen on the free plan" scores highly on the
+ * site-protection page while silently dropping "free plan", and the answer
+ * that comes back is then wrong in the one way that matters.
+ *
+ * ⚠️ WEIGHTED BY IDF, and an unweighted version of this test is why nine
+ * perfectly ordinary questions escalated in the first measurement. "how do I
+ * make a reusable component" covers `reusable` and `component` and misses
+ * `make`, because the page says "create" — 2/3, under the bar, escalated. The
+ * miss carried no information: `make` appears in a third of the corpus, so
+ * its absence from one page says nothing, while `reusable` appearing says
+ * almost everything. Counting tokens equally lets the most common words in
+ * English veto a match on the rarest. Weighting by how rare a term is in THIS
+ * corpus makes the test ask what it always meant to ask — did the page cover
+ * the DISTINCTIVE part of the question.
+ */ const MIN_COVERAGE = 0.7;
+/**
+ * The relaxed coverage floor, reachable ONLY by a page that has also won
+ * overwhelmingly ({@link STRONG_PAGE_MARGIN}).
+ *
+ * Coverage and dominance are evidence about the same thing from opposite
+ * directions, and holding both as independent hard floors throws away the
+ * cases where one is emphatic. "how do I edit text directly on the canvas"
+ * covers 0.68 — a hair under the bar, and the miss is `directly`, which the
+ * text-editing page never says — while winning so completely that every
+ * retrieved section belongs to it and there is no rival page to divide by.
+ * There is no reading of that evidence in which the text-editing page is the
+ * wrong page, and escalating it pays a provider to agree.
+ *
+ * The floor still binds, and it binds on questions that HAVE cleared
+ * {@link STRONG_PAGE_MARGIN}: "how do I customise the error screens" wins its
+ * page by 4.1x and still escalates at 0.42, because a page that ignores that
+ * much of the question is not answering it however clearly it wins. That is
+ * the case this pair of numbers is calibrated to keep out.
+ *
+ * ⚠️ Both figures are measurements over the CURRENT `apps/docs` corpus, and
+ * the corpus moves. `docs-deflection.spec.ts` asserts the first one's band
+ * rather than only its verdict, so a worked example that drifts out of the
+ * band fails there by name instead of going quietly wrong here.
+ */ const RELAXED_COVERAGE = 0.6;
+/** The margin that buys {@link RELAXED_COVERAGE}. */ const STRONG_PAGE_MARGIN = 3;
+/**
+ * ── The follow-up bar (AGL-2486) ──────────────────────────────────────────
+ *
+ * A question asked mid-thread is held to a HIGHER standard than the same
+ * question asked first, and the asymmetry is the whole idea rather than
+ * timidity about a new path.
+ *
+ * On turn one, a mediocre match costs a mediocre answer to the question that
+ * was actually asked, and the closing line invites the user to ask again.
+ * Mid-thread, a mediocre match means something else as well: it is EVIDENCE
+ * that the words in front of us are not the whole question. A thread is where
+ * ellipsis lives, so "retrieval is unsure" and "the missing half is in the
+ * transcript" are the same observation seen twice. Only an emphatic match —
+ * one where the page is right whatever came before — may be answered without
+ * reading the conversation.
+ *
+ * The calibration case is the second question, "how do I add an
+ * element to my page": top score 7.9, and the winning page beats its rival by
+ * 1.80 with a coming-soon LAUNCH GUIDE, because that guide happens to say
+ * "add", "element" and "page". As a first question that is retrieval doing
+ * its honest best. As a follow-up it is a coin flip that also ignores the
+ * conversation, and it escalates.
+ */ const FOLLOW_UP_MIN_TOP_SCORE = 8;
+/** @see FOLLOW_UP_MIN_TOP_SCORE — 1.3x is a lead; 2x is not arguable. */ const FOLLOW_UP_MIN_PAGE_MARGIN = 2;
+/**
+ * A follow-up must ASK something, not merely name a topic.
+ *
+ * Mid-thread, a bare fragment — "the free plan?", "on mobile" — is the shape
+ * ellipsis takes: the verb it belongs to was in the previous turn, and the
+ * fragment is a modifier of a question we cannot see. A first turn cannot be
+ * elliptical in that way, which is why this cue is required only when
+ * something precedes it.
+ *
+ * The count of tokens was tried here first and thrown away: it excluded "how
+ * do I install a plugin" and "how do I create a site" — two content tokens
+ * each, and both complete questions that a user asks second as readily as
+ * first. Length is not what separates a question from a fragment; a verb is.
+ */ const QUESTION_CUES = /\b(how|what|what'?s|where|when|which|who|whose|whom|can|could|do|does|did|is|are|am|was|were|will|would|should|must|may|explain|show|tell|list|need|want)\b/i;
+/**
+ * Words and shapes that make a question depend on what came before it.
+ *
+ * Deliberately BROAD, and the asymmetry of the costs is why: a false positive
+ * here escalates a question that could have been answered from the docs — the
+ * behaviour that existed for every follow-up until this change, so the worst
+ * case is the status quo. A false negative answers a question nobody asked,
+ * with a citation under it, in a thread where the user can see we had the
+ * context and ignored it. These patterns are only ever consulted for a turn
+ * WITH history; a first question may say "that" as much as it likes.
+ */ const CONTEXT_DEPENDENT_PATTERNS = [
+    // Pronouns and demonstratives standing in for a noun in the transcript.
+    // "does IT work on mobile", "how do I move THOSE".
+    /\b(it|its|it'?s|they|them|their|theirs|he|him|his|she|her|hers)\b/i,
+    /\b(that|this|these|those)\b/i,
+    // Naming an item of the previous answer by its position in it.
+    /\b(the|either|any|another|each)\s+(other|first|second|third|last|next|same|previous|latter|former)\b/i,
+    /\b(other|another|either)\s+one\b/i,
+    // Opening by attaching to the previous turn rather than starting a question.
+    /^\s*(and|but|so|or|then|also|plus|what about|how about|ok(ay)?|yes|no|yeah|nope|thanks?)\b/i,
+    // Elliptical follow-ups that carry the previous turn's verb phrase over.
+    /\b(why not|instead|as well|again|neither|both)\b/i
+];
+/** Minimum characters of section text before a section counts as an answer. */ const MIN_SECTION_CHARS = 200;
+/** Sections of the winning page quoted verbatim, at most. */ const MAX_QUOTED_SECTIONS = 2;
+/** Total verbatim characters in one deflected answer. */ const MAX_ANSWER_CHARS = 2600;
+/**
+ * A request is generative when it asks for something to be WRITTEN, not
+ * explained. Anchored to the start of a word and paired with the objects
+ * people actually name, because "how do I create a redirect" is a docs
+ * question and "create a headline for my hero" is not.
+ */ const GENERATIVE_PATTERNS = [
+    /\b(write|draft|compose|generate|rewrite|reword|rephrase|summari[sz]e|translate|brainstorm|suggest)\b/i,
+    /\b(make|build|create|give)\s+(me|us)\b/i,
+    /\b(come up with|help me write)\b/i
+];
+/**
+ * A request is diagnostic when it describes something not working. These have
+ * docs pages and must still escalate: the page lists every cause, and the
+ * user has exactly one of them. Only the model, with the level-2 view context,
+ * can narrow it — and when it cannot, saying so is better than quoting nine
+ * causes at someone.
+ */ const DIAGNOSTIC_PATTERNS = [
+    /\bwhy\s+(is|are|isn'?t|aren'?t|does|doesn'?t|did|didn'?t|won'?t|can'?t|cannot|do)\b/i,
+    /\b(not working|isn'?t working|doesn'?t work|stopped working|no longer works)\b/i,
+    /\b(was|were|is|are|never)\s+not\s+\w+ed\b/i,
+    /\b(broken|failing|failed|stuck|blank|missing|502|404|500)\b/i,
+    /\b(troubleshoot|debug|diagnose)\b/i,
+    // "error" needs a verb of appearance in front of it, within a clause.
+    // Bare `\berrors?\b` reads "how do I customise the error screens" as a
+    // support ticket — the docs page for error screens is titled with the word,
+    // so the one question the pattern must not catch is the one it caught.
+    /\b(getting|got|see|seeing|shows?|showing|throws?|returns?|says?|hit)\b[^.?!]{0,40}\berrors?\b/i
+];
+function refuse(refusal, topScore = 0, pageMargin = 0, coverage = 0) {
+    return {
+        answered: false,
+        refusal,
+        answer: '',
+        quoted: [],
+        page: '',
+        topScore,
+        pageMargin,
+        coverage
+    };
+}
+/**
+ * Inverse document frequency for one token, over the docs corpus.
+ *
+ * Smoothed (`+1` inside the log's argument and on the denominator) so a token
+ * absent from the index — a product name we have not documented, a typo —
+ * gets a large but finite weight rather than a division by zero or an
+ * infinity that would swallow every other term in the question.
+ */ function tokenWeight(token) {
+    var _frequency_get;
+    const { frequency, sections } = docsDocumentFrequency();
+    const seen = (_frequency_get = frequency.get(token)) != null ? _frequency_get : 0;
+    return Math.log(1 + sections / (1 + seen));
+}
+/** The docs-site URL for one section. */ export function sectionUrl(section) {
+    return `${DOCS_SITE_ORIGIN}${section.path}${section.anchor}`;
+}
+/** `Title — Heading`, or just the title on a page intro. */ export function sectionLabel(section) {
+    return section.heading ? `${section.title} — ${section.heading}` : section.title;
+}
+/**
+ * Trim verbatim text to `limit` characters on a sentence boundary, so a quote
+ * never ends mid-clause. Returns the text unchanged when it already fits.
+ *
+ * A truncated quote is still verbatim — it is a PREFIX of the section, which
+ * is what the spec's substring check asserts. Cutting on a boundary matters
+ * for a different reason: a sentence stopped halfway reads as a broken
+ * feature, and the user cannot tell whether the missing half contradicted the
+ * visible one.
+ */ export function trimToSentence(text, limit) {
+    const trimmed = text.trim();
+    if (trimmed.length <= limit) return trimmed;
+    const window = trimmed.slice(0, limit);
+    const lastStop = Math.max(window.lastIndexOf('. '), window.lastIndexOf('! '), window.lastIndexOf('? '));
+    // A boundary in the first third would throw most of the quote away; better
+    // a hard cut with an ellipsis than an answer reduced to one sentence.
+    if (lastStop > limit / 3) return window.slice(0, lastStop + 1);
+    return `${window.trimEnd()}…`;
+}
+/** Question intent, ahead of any retrieval work. */ export function questionIsAnswerableFromDocs(question) {
+    const tokens = new Set(tokenize(question));
+    if (tokens.size < MIN_QUESTION_TOKENS) return 'too-short';
+    for (const pattern of GENERATIVE_PATTERNS){
+        if (pattern.test(question)) return 'generative';
+    }
+    for (const pattern of DIAGNOSTIC_PATTERNS){
+        if (pattern.test(question)) return 'diagnostic';
+    }
+    return null;
+}
+/**
+ * Whether a question can be read WITHOUT the conversation it was asked in.
+ *
+ * Only consulted for a turn that has history — see
+ * {@link CONTEXT_DEPENDENT_PATTERNS} for why the test errs towards "no", and
+ * the class docstring for why the gate is no longer simply "did anything
+ * precede this".
+ *
+ * Purely lexical, and that is a real limit worth naming: "how do I do the
+ * same for a blog post" is caught by `the same`, while "how do I change the
+ * colour" after a paragraph about buttons is not — nothing in those words
+ * says which colour. What saves that case is not this function but the raised
+ * evidence bar behind it, which such a question does not clear. The two gates
+ * are one argument in two halves: this one reads the question, that one reads
+ * the retrieval, and a follow-up must pass both.
+ */ export function questionStandsAlone(question) {
+    if (!QUESTION_CUES.test(question)) return false;
+    for (const pattern of CONTEXT_DEPENDENT_PATTERNS){
+        if (pattern.test(question)) return false;
+    }
+    return true;
+}
+/**
+ * Decide whether the retrieved sections answer the question on their own, and
+ * compose the answer when they do.
+ *
+ * `hasHistory` is passed rather than derived because the caller holds the
+ * clamped history and this module must not grow an opinion about how history
+ * is budgeted. It is not a hard gate any more (AGL-2486): a turn with history
+ * must additionally stand on its own words and clear the raised `FOLLOW_UP_*`
+ * bar, and escalates when it does not.
+ */ export function deflectToDocs(question, scored, hasHistory) {
+    if (hasHistory && !questionStandsAlone(question)) return refuse('follow-up');
+    const intent = questionIsAnswerableFromDocs(question);
+    if (intent) return refuse(intent);
+    if (!scored.length) return refuse('low-score');
+    const minTopScore = hasHistory ? FOLLOW_UP_MIN_TOP_SCORE : MIN_TOP_SCORE;
+    const minPageMargin = hasHistory ? FOLLOW_UP_MIN_PAGE_MARGIN : MIN_PAGE_MARGIN;
+    const top = scored[0];
+    const topScore = top.score;
+    if (!(topScore >= minTopScore)) return refuse('low-score', topScore);
+    // Score by PAGE. Sections of one page agreeing is the signal; treating them
+    // as rivals is how a strong, unambiguous match reads as a tie.
+    const perPage = new Map();
+    for (const entry of scored){
+        var _perPage_get;
+        perPage.set(entry.section.path, ((_perPage_get = perPage.get(entry.section.path)) != null ? _perPage_get : 0) + entry.score);
+    }
+    // The winning page is the highest-scoring PAGE, not the home of the
+    // highest-scoring section — three mid-scoring sections of one page can beat
+    // one strong section elsewhere, and when they do, that page is the answer.
+    let winner = '';
+    let winnerScore = 0;
+    let rivalScore = 0;
+    for (const [path, score] of perPage){
+        if (score > winnerScore) {
+            rivalScore = winnerScore;
+            winner = path;
+            winnerScore = score;
+        } else if (score > rivalScore) {
+            rivalScore = score;
+        }
+    }
+    // No rival is not a tie — it is the cleanest possible result, one page and
+    // nothing else. `Infinity` would be honest but propagates badly through the
+    // telemetry, so a lone winner reports its own score as the margin.
+    const pageMargin = rivalScore > 0 ? winnerScore / rivalScore : winnerScore;
+    if (!(pageMargin >= minPageMargin)) return refuse('ambiguous', topScore, pageMargin);
+    const pageSections = scored.filter((entry)=>entry.section.path === winner);
+    const pageTokens = new Set();
+    for (const entry of pageSections){
+        for (const token of tokenize(entry.section.title))pageTokens.add(token);
+        for (const token of tokenize(entry.section.heading))pageTokens.add(token);
+        for (const token of tokenize(entry.section.text))pageTokens.add(token);
+    }
+    const questionTokens = [
+        ...new Set(tokenize(question))
+    ];
+    let wanted = 0;
+    let covered = 0;
+    for (const token of questionTokens){
+        const weight = tokenWeight(token);
+        wanted += weight;
+        if (pageTokens.has(token)) covered += weight;
+    }
+    const coverage = wanted > 0 ? covered / wanted : 0;
+    // The relaxed floor is a FIRST-TURN allowance. It exists because coverage
+    // and dominance are evidence about the same thing, so an emphatic winner
+    // may carry a coverage miss — but mid-thread a coverage miss has a second
+    // reading: the part of the question the page ignored may be the part the
+    // conversation supplied. Turn one cannot mean that; a follow-up can, so it
+    // pays full coverage.
+    const coveredEnough = coverage >= MIN_COVERAGE || !hasHistory && coverage >= RELAXED_COVERAGE && pageMargin >= STRONG_PAGE_MARGIN;
+    if (!coveredEnough) {
+        return refuse('low-coverage', topScore, pageMargin, coverage);
+    }
+    const usable = pageSections.filter((entry)=>entry.section.text.trim().length >= MIN_SECTION_CHARS);
+    if (!usable.length) return refuse('thin-section', topScore, pageMargin, coverage);
+    const quoted = usable.slice(0, MAX_QUOTED_SECTIONS).map((entry)=>entry.section);
+    return {
+        answered: true,
+        refusal: null,
+        answer: composeDocsAnswer(quoted),
+        quoted,
+        page: winner,
+        topScore,
+        pageMargin,
+        coverage
+    };
+}
+/**
+ * The deflected answer: template + verbatim docs + real links, and nothing
+ * else. Kept exported so the spec can assert the reconstruction property
+ * against it directly rather than through the route.
+ *
+ * ⚠️ COMPOSED FOR A SURFACE THAT DOES NOT RENDER MARKDOWN. The Assist panel
+ * says so in its own docstring — `renderAssistText` turns `[label](url)` and
+ * bare URLs into links and renders everything else literally, under
+ * `whiteSpace: 'pre-wrap'`. That is a deliberate phase-1 decision, not a gap.
+ *
+ * This template shipped once with the heading wrapped in `**…**`, and the * besigner drawer duly showed `**Drag-and-drop hierarchy — Moving an element
+ * without dragging**`, asterisks and all. The lesson is not "escape the
+ * asterisks" — it is that the composer has to know what renders it.
+ *
+ * So the heading is a bare `[label](url)` on its own line — a LINK, which is
+ * the one markup the panel speaks, and which is why the title in the * screenshot was correctly clickable even while the asterisks around it were
+ * not. Everything else is carried by NEWLINES, which `pre-wrap` renders,
+ * rather than by markup, which it does not.
+ *
+ * The link has to live in the TEXT, and that is still true now that the
+ * `docs` array on the `done` event IS rendered (AGL-2486, `AssistSources`).
+ * It was tempting to treat that array as the structural home for the citation
+ * even when nothing rendered it; it is still the wrong home, for a different
+ * reason. `docs` carries every section RETRIEVED, whereas this template
+ * quotes only the sections it actually used — so the array is a superset, and
+ * a citation moved there would credit pages this answer never drew a word
+ * from. `AssistSources` drops any url already linked in the text, which means
+ * a deflected answer renders exactly as it does below and gains no duplicate
+ * list underneath.
+ *
+ * Three specs in `docs-deflection.spec.ts` hold the line — no emphasis
+ * markers, no heading markers, and a link still present.
+ *
+ * The closing line is not decoration. A user who reads this and finds it did
+ * not answer them needs to know that asking again in different words reaches
+ * something else — otherwise the cheap path looks like the assistant simply
+ * being worse, and the next thing they do is stop using it.
+ */ export function composeDocsAnswer(sections) {
+    const parts = [];
+    let budget = MAX_ANSWER_CHARS;
+    for (const section of sections){
+        if (budget <= MIN_SECTION_CHARS) break;
+        const quote = trimToSentence(section.text, budget);
+        budget -= quote.length;
+        parts.push(`[${sectionLabel(section)}](${sectionUrl(section)})\n${quote}`);
+    }
+    parts.push('That is straight from the documentation — the headings above link to the full page. If it did not cover what you meant, ask again with more detail and I will work through it with you.');
+    return parts.join('\n\n');
+}
+/** Closest-pages links offered when nothing could be answered outright. */ const MAX_LINKED_SECTIONS = 4;
+/**
+ * The graceful degrade: the closest pages we found, and an honest sentence
+ * saying why that is all there is (AGL-2486).
+ *
+ * ## Why this exists
+ *
+ * A deployment with no AI provider key — which includes every self-hosted
+ * one on the day it comes up, and Aglyn's own production today — can answer
+ * only what retrieval is confident about. A bare 501 for everything else
+ * reaches the panel as "Assist is not configured on this deployment" — and it
+ * can arrive on the SECOND question of a thread whose first question was just
+ * answered in full. A capability refusal that lands after a working answer
+ * reads as a fault, not a limit.
+ *
+ * The self-host charter says every Aglyn-operated dependency must be
+ * configurable AND degrade cleanly. "Degrades cleanly" cannot mean "answers
+ * one question per thread and then refuses" — a keyless deployment still has
+ * the entire documentation corpus and a retrieval index over it, so the floor
+ * is the best pages we found, not nothing.
+ *
+ * ## What it may and may not say
+ *
+ * The no-fabrication rule applies here exactly as it does to a deflected
+ * answer, and is tighter in one respect: these pages did NOT clear the
+ * confidence bar, so this text must not claim they answer the question. It
+ * says they are the closest, which is true by construction — they are the
+ * top of the retrieval ranking — and every word around them is a fixed
+ * template plus a real section label and URL.
+ *
+ * It also must not name an env var. A user who wanted to read `501` would
+ * have opened the network tab; the operator-facing detail stays in the API
+ * error body, where an operator looks. This is the plain-English half.
+ */ export function composeDocsLinksAnswer(sections) {
+    const links = sections.slice(0, MAX_LINKED_SECTIONS).map((section)=>`[${sectionLabel(section)}](${sectionUrl(section)})`);
+    if (!links.length) return '';
+    return [
+        'I could not find one page in the documentation that clearly answers that, and the part of me that talks a question through with you is not switched on for this deployment yet — an administrator has to finish setting it up.',
+        'These are the closest pages I found:',
+        links.join('\n'),
+        'If none of them cover it, asking again in different words often lands somewhere better.'
+    ].join('\n\n');
+}
+
+//# sourceMappingURL=docs-deflection.js.map

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

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/docs-deflection.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 { AssistDocsSection } from './docs-index.generated'\nimport {\n  DOCS_SITE_ORIGIN,\n  docsDocumentFrequency,\n  tokenize,\n  type ScoredSection,\n} from './docs-retrieval'\n\n/**\n * Retrieval-first answering for Aglyn Assist (AGL-2486) — the deflection gate.\n *\n * Most assist traffic is \"how do I X\", and the answer to \"how do I X\" is\n * already written down in `apps/docs/docs`. Sending that question to a model\n * so the model can read the docs section back to the user pays provider money\n * to reformat prose we wrote ourselves. This module decides when retrieval is\n * confident enough to hand the docs straight over, and composes the answer\n * when it is. Escalation to the model is what happens the rest of the time —\n * it is the fallback, not the default.\n *\n * ## The one rule: never fabricate\n *\n * A deflected answer contains exactly two kinds of text:\n *\n *   1. Fixed template strings from this file, which say nothing about the\n *      product — they name the page and introduce the quote.\n *   2. Section text copied VERBATIM out of the docs index, with the URL of\n *      the page it came from.\n *\n * There is no summarisation, no paraphrase and no stitching of adjacent\n * sections into a claim neither one makes. The spec asserts it by\n * RECONSTRUCTION — \"never fabricate — every word is template or verbatim\n * docs\" — stripping the template from a composed answer and requiring what is\n * left to be a prefix of a real section's `text`. That property is the whole\n * safety argument, because a wrong retrieval answer is worse than an\n * escalation — it is confidently wrong prose delivered to a paying customer\n * with a citation under it, which is the shape people trust most.\n *\n * ## What \"confident\" means\n *\n * Seven conditions, ALL of which must hold. Any one failing escalates; there\n * is no partial-credit path where a weak match produces a hedged answer,\n * because a hedged wrong answer is still a wrong answer and it has already\n * cost the user the click.\n *\n *   1. **The question stands on its own.** A follow-up is usually not\n *      self-contained: \"does that work on the free plan?\" retrieves the\n *      billing pages beautifully and answers a question nobody asked. The\n *      conversation is the missing half and only the model has it.\n *\n *      The gate is NOT \"no prior turn\" (AGL-2486). Not every follow-up leans\n *      on the transcript: the second question in a thread is very often a\n *      fresh, complete question that happens to be asked second. Refusing all\n *      of them means a thread answers its first question from the docs and\n *      then escalates forever — and on a deployment with no AI provider\n *      key that reads as \"Aglyn Assist is not configured\",\n *      one question in, to a user who just watched it work. A product that\n *      answers exactly once per thread is worse than one that never answers,\n *      because the second refusal looks like a fault rather than a limit.\n *\n *      So the gate now asks whether THIS question stands alone, and holds a\n *      raised bar when it does — see {@link questionStandsAlone} and the\n *      `FOLLOW_UP_*` constants.\n *   2. **Enough question.** At least {@link MIN_QUESTION_TOKENS} distinct\n *      content tokens after stop-word removal. Below that there is not enough\n *      of a question to be confident ABOUT.\n *   3. **Not a generative request.** \"write me a hero headline\" is the copy\n *      assistant's job, not a docs lookup, and no docs page answers it.\n *   4. **Not a diagnostic.** \"why isn't my domain verifying\" has a\n *      troubleshooting page, and dumping that page at someone whose actual\n *      problem is one of nine listed causes is exactly the confidently-wrong\n *      failure. Diagnostics need the workspace's own state, which is the\n *      level-2 context only the model gets.\n *   5. **Absolute score.** The top section scores at least\n *      {@link MIN_TOP_SCORE}.\n *   6. **Page dominance.** The winning page beats the best RIVAL page by at\n *      least {@link MIN_PAGE_MARGIN}. Measured against the runner-up page\n *      rather than as a share of the whole retrieved set, because the set is\n *      six sections wide: a page that is unambiguously right still holds a\n *      minority of a six-way split the moment three neighbouring pages use the\n *      same nouns, and a share test reads that dilution as doubt. And the\n *      comparison is page-to-page, not section-to-section — sections of ONE\n *      page scoring alike is agreement, which a section margin scores as a tie.\n *   7. **Substance.** The winning section carries at least\n *      {@link MIN_SECTION_CHARS} of text. A three-word stub under a heading is\n *      a pointer, not an answer.\n *\n * Below the bar the request proceeds exactly as it did before this module\n * existed: the same sections are still retrieved and still ground the model's\n * prompt. Deflection removes model calls; it never removes grounding.\n *\n * ## The thresholds are measured, not guessed\n *\n * `docs-deflection.spec.ts` carries a fixed set of realistic questions —\n * positives written in user vocabulary rather than lifted from docs headings,\n * and negatives that MUST escalate — and asserts a floor on the deflection\n * rate and a ceiling of zero on the negatives. Retuning a constant here\n * without rerunning that spec is how a threshold ends up set by whoever\n * touched it last.\n */\n\n/**\n * Distinct content tokens a question needs before it can be answered.\n *\n * Two, not three, and the difference is most of the corpus: \"how do I install\n * a plugin\", \"what are dataset relations\" and \"how do I cancel my\n * subscription\" all reduce to exactly two content tokens once the stop words\n * go, and every one of them is a plain docs lookup. Three excluded them all.\n *\n * Two is safe here only because the gates below are not a checklist a weak\n * question can pass by being short: a two-token question must have BOTH\n * tokens carried by the winning page (the IDF weighting cannot rescue it —\n * there is nothing generic to discount), and the page must still clear the\n * score floor and out-score its rival. \"is my site down\" has two tokens and\n * fails on dominance, not on length.\n */\nconst MIN_QUESTION_TOKENS = 2\n\n/**\n * Absolute floor on the winning section's retrieval score.\n *\n * The scorer gives 2.5 for a title hit, 2 for a heading hit and up to ~2.2 per\n * body term — about 6.7 for one term landing everywhere at once. 5 is\n * therefore roughly \"two question terms landed and at least one of them hit\n * the page's own statement of topic\". Below that the match is incidental\n * vocabulary rather than a page about the thing.\n *\n * Measured down from 6, which cost five ordinary lookups scoring 4.4–5.9\n * (\"how do I cancel my subscription\", \"how do I set up sso for my team\") and\n * bought nothing: the negative set does not move between the two values,\n * because what actually stops those is coverage and dominance, not the floor.\n */\nconst MIN_TOP_SCORE = 5\n\n/**\n * How far the winning page must out-score the best rival page.\n *\n * 1.3x — the winner needs a visible lead, not a photo finish. Two pages\n * within 30% of each other on the same question means retrieval genuinely\n * does not know which one the user meant, and picking is a coin flip dressed\n * up as an answer.\n *\n * A question that retrieves only ONE page has no rival and passes this gate\n * outright; the score floor and coverage are what bound it there.\n */\nconst MIN_PAGE_MARGIN = 1.3\n\n/**\n * Weighted fraction of the question the winning page must actually contain.\n * Coverage and score answer different questions: score says the page matched\n * strongly, coverage says the page did not IGNORE part of what was asked.\n * \"how do I password protect a screen on the free plan\" scores highly on the\n * site-protection page while silently dropping \"free plan\", and the answer\n * that comes back is then wrong in the one way that matters.\n *\n * ⚠️ WEIGHTED BY IDF, and an unweighted version of this test is why nine\n * perfectly ordinary questions escalated in the first measurement. \"how do I\n * make a reusable component\" covers `reusable` and `component` and misses\n * `make`, because the page says \"create\" — 2/3, under the bar, escalated. The\n * miss carried no information: `make` appears in a third of the corpus, so\n * its absence from one page says nothing, while `reusable` appearing says\n * almost everything. Counting tokens equally lets the most common words in\n * English veto a match on the rarest. Weighting by how rare a term is in THIS\n * corpus makes the test ask what it always meant to ask — did the page cover\n * the DISTINCTIVE part of the question.\n */\nconst MIN_COVERAGE = 0.7\n\n/**\n * The relaxed coverage floor, reachable ONLY by a page that has also won\n * overwhelmingly ({@link STRONG_PAGE_MARGIN}).\n *\n * Coverage and dominance are evidence about the same thing from opposite\n * directions, and holding both as independent hard floors throws away the\n * cases where one is emphatic. \"how do I edit text directly on the canvas\"\n * covers 0.68 — a hair under the bar, and the miss is `directly`, which the\n * text-editing page never says — while winning so completely that every\n * retrieved section belongs to it and there is no rival page to divide by.\n * There is no reading of that evidence in which the text-editing page is the\n * wrong page, and escalating it pays a provider to agree.\n *\n * The floor still binds, and it binds on questions that HAVE cleared\n * {@link STRONG_PAGE_MARGIN}: \"how do I customise the error screens\" wins its\n * page by 4.1x and still escalates at 0.42, because a page that ignores that\n * much of the question is not answering it however clearly it wins. That is\n * the case this pair of numbers is calibrated to keep out.\n *\n * ⚠️ Both figures are measurements over the CURRENT `apps/docs` corpus, and\n * the corpus moves. `docs-deflection.spec.ts` asserts the first one's band\n * rather than only its verdict, so a worked example that drifts out of the\n * band fails there by name instead of going quietly wrong here.\n */\nconst RELAXED_COVERAGE = 0.6\n\n/** The margin that buys {@link RELAXED_COVERAGE}. */\nconst STRONG_PAGE_MARGIN = 3\n\n/**\n * ── The follow-up bar (AGL-2486) ──────────────────────────────────────────\n *\n * A question asked mid-thread is held to a HIGHER standard than the same\n * question asked first, and the asymmetry is the whole idea rather than\n * timidity about a new path.\n *\n * On turn one, a mediocre match costs a mediocre answer to the question that\n * was actually asked, and the closing line invites the user to ask again.\n * Mid-thread, a mediocre match means something else as well: it is EVIDENCE\n * that the words in front of us are not the whole question. A thread is where\n * ellipsis lives, so \"retrieval is unsure\" and \"the missing half is in the\n * transcript\" are the same observation seen twice. Only an emphatic match —\n * one where the page is right whatever came before — may be answered without\n * reading the conversation.\n *\n * The calibration case is the second question, \"how do I add an\n * element to my page\": top score 7.9, and the winning page beats its rival by\n * 1.80 with a coming-soon LAUNCH GUIDE, because that guide happens to say\n * \"add\", \"element\" and \"page\". As a first question that is retrieval doing\n * its honest best. As a follow-up it is a coin flip that also ignores the\n * conversation, and it escalates.\n */\nconst FOLLOW_UP_MIN_TOP_SCORE = 8\n\n/** @see FOLLOW_UP_MIN_TOP_SCORE — 1.3x is a lead; 2x is not arguable. */\nconst FOLLOW_UP_MIN_PAGE_MARGIN = 2\n\n/**\n * A follow-up must ASK something, not merely name a topic.\n *\n * Mid-thread, a bare fragment — \"the free plan?\", \"on mobile\" — is the shape\n * ellipsis takes: the verb it belongs to was in the previous turn, and the\n * fragment is a modifier of a question we cannot see. A first turn cannot be\n * elliptical in that way, which is why this cue is required only when\n * something precedes it.\n *\n * The count of tokens was tried here first and thrown away: it excluded \"how\n * do I install a plugin\" and \"how do I create a site\" — two content tokens\n * each, and both complete questions that a user asks second as readily as\n * first. Length is not what separates a question from a fragment; a verb is.\n */\nconst QUESTION_CUES =\n  /\\b(how|what|what'?s|where|when|which|who|whose|whom|can|could|do|does|did|is|are|am|was|were|will|would|should|must|may|explain|show|tell|list|need|want)\\b/i\n\n/**\n * Words and shapes that make a question depend on what came before it.\n *\n * Deliberately BROAD, and the asymmetry of the costs is why: a false positive\n * here escalates a question that could have been answered from the docs — the\n * behaviour that existed for every follow-up until this change, so the worst\n * case is the status quo. A false negative answers a question nobody asked,\n * with a citation under it, in a thread where the user can see we had the\n * context and ignored it. These patterns are only ever consulted for a turn\n * WITH history; a first question may say \"that\" as much as it likes.\n */\nconst CONTEXT_DEPENDENT_PATTERNS: readonly RegExp[] = [\n  // Pronouns and demonstratives standing in for a noun in the transcript.\n  // \"does IT work on mobile\", \"how do I move THOSE\".\n  /\\b(it|its|it'?s|they|them|their|theirs|he|him|his|she|her|hers)\\b/i,\n  /\\b(that|this|these|those)\\b/i,\n  // Naming an item of the previous answer by its position in it.\n  /\\b(the|either|any|another|each)\\s+(other|first|second|third|last|next|same|previous|latter|former)\\b/i,\n  /\\b(other|another|either)\\s+one\\b/i,\n  // Opening by attaching to the previous turn rather than starting a question.\n  /^\\s*(and|but|so|or|then|also|plus|what about|how about|ok(ay)?|yes|no|yeah|nope|thanks?)\\b/i,\n  // Elliptical follow-ups that carry the previous turn's verb phrase over.\n  /\\b(why not|instead|as well|again|neither|both)\\b/i,\n]\n\n/** Minimum characters of section text before a section counts as an answer. */\nconst MIN_SECTION_CHARS = 200\n\n/** Sections of the winning page quoted verbatim, at most. */\nconst MAX_QUOTED_SECTIONS = 2\n\n/** Total verbatim characters in one deflected answer. */\nconst MAX_ANSWER_CHARS = 2600\n\n/**\n * A request is generative when it asks for something to be WRITTEN, not\n * explained. Anchored to the start of a word and paired with the objects\n * people actually name, because \"how do I create a redirect\" is a docs\n * question and \"create a headline for my hero\" is not.\n */\nconst GENERATIVE_PATTERNS: readonly RegExp[] = [\n  /\\b(write|draft|compose|generate|rewrite|reword|rephrase|summari[sz]e|translate|brainstorm|suggest)\\b/i,\n  /\\b(make|build|create|give)\\s+(me|us)\\b/i,\n  /\\b(come up with|help me write)\\b/i,\n]\n\n/**\n * A request is diagnostic when it describes something not working. These have\n * docs pages and must still escalate: the page lists every cause, and the\n * user has exactly one of them. Only the model, with the level-2 view context,\n * can narrow it — and when it cannot, saying so is better than quoting nine\n * causes at someone.\n */\nconst DIAGNOSTIC_PATTERNS: readonly RegExp[] = [\n  /\\bwhy\\s+(is|are|isn'?t|aren'?t|does|doesn'?t|did|didn'?t|won'?t|can'?t|cannot|do)\\b/i,\n  /\\b(not working|isn'?t working|doesn'?t work|stopped working|no longer works)\\b/i,\n  /\\b(was|were|is|are|never)\\s+not\\s+\\w+ed\\b/i,\n  /\\b(broken|failing|failed|stuck|blank|missing|502|404|500)\\b/i,\n  /\\b(troubleshoot|debug|diagnose)\\b/i,\n  // \"error\" needs a verb of appearance in front of it, within a clause.\n  // Bare `\\berrors?\\b` reads \"how do I customise the error screens\" as a\n  // support ticket — the docs page for error screens is titled with the word,\n  // so the one question the pattern must not catch is the one it caught.\n  /\\b(getting|got|see|seeing|shows?|showing|throws?|returns?|says?|hit)\\b[^.?!]{0,40}\\berrors?\\b/i,\n]\n\n/** Why a question was not answered from the docs. `null` reason = answered. */\nexport type DeflectionRefusal =\n  | 'follow-up'\n  | 'too-short'\n  | 'generative'\n  | 'diagnostic'\n  | 'low-score'\n  | 'ambiguous'\n  | 'low-coverage'\n  | 'thin-section'\n\nexport interface DeflectionVerdict {\n  /** True when the docs answer this without a model call. */\n  answered: boolean\n  /** Set when `answered` is false — which gate refused. */\n  refusal: DeflectionRefusal | null\n  /** The composed answer; `''` unless `answered`. */\n  answer: string\n  /** Sections quoted in the answer; `[]` unless `answered`. */\n  quoted: readonly AssistDocsSection[]\n  /** The winning page's path; `''` when nothing won. */\n  page: string\n  /** Top section's retrieval score. 0 when nothing was retrieved. */\n  topScore: number\n  /** Winning page's score over the best rival page's. 0 when unscored. */\n  pageMargin: number\n  /** IDF-weighted share of the question the winning page carries. */\n  coverage: number\n}\n\nfunction refuse(\n  refusal: DeflectionRefusal,\n  topScore = 0,\n  pageMargin = 0,\n  coverage = 0,\n): DeflectionVerdict {\n  return {\n    answered: false,\n    refusal,\n    answer: '',\n    quoted: [],\n    page: '',\n    topScore,\n    pageMargin,\n    coverage,\n  }\n}\n\n/**\n * Inverse document frequency for one token, over the docs corpus.\n *\n * Smoothed (`+1` inside the log's argument and on the denominator) so a token\n * absent from the index — a product name we have not documented, a typo —\n * gets a large but finite weight rather than a division by zero or an\n * infinity that would swallow every other term in the question.\n */\nfunction tokenWeight(token: string): number {\n  const { frequency, sections } = docsDocumentFrequency()\n  const seen = frequency.get(token) ?? 0\n  return Math.log(1 + sections / (1 + seen))\n}\n\n/** The docs-site URL for one section. */\nexport function sectionUrl(section: AssistDocsSection): string {\n  return `${DOCS_SITE_ORIGIN}${section.path}${section.anchor}`\n}\n\n/** `Title — Heading`, or just the title on a page intro. */\nexport function sectionLabel(section: AssistDocsSection): string {\n  return section.heading ? `${section.title} — ${section.heading}` : section.title\n}\n\n/**\n * Trim verbatim text to `limit` characters on a sentence boundary, so a quote\n * never ends mid-clause. Returns the text unchanged when it already fits.\n *\n * A truncated quote is still verbatim — it is a PREFIX of the section, which\n * is what the spec's substring check asserts. Cutting on a boundary matters\n * for a different reason: a sentence stopped halfway reads as a broken\n * feature, and the user cannot tell whether the missing half contradicted the\n * visible one.\n */\nexport function trimToSentence(text: string, limit: number): string {\n  const trimmed = text.trim()\n  if (trimmed.length <= limit) return trimmed\n  const window = trimmed.slice(0, limit)\n  const lastStop = Math.max(\n    window.lastIndexOf('. '),\n    window.lastIndexOf('! '),\n    window.lastIndexOf('? '),\n  )\n  // A boundary in the first third would throw most of the quote away; better\n  // a hard cut with an ellipsis than an answer reduced to one sentence.\n  if (lastStop > limit / 3) return window.slice(0, lastStop + 1)\n  return `${window.trimEnd()}…`\n}\n\n/** Question intent, ahead of any retrieval work. */\nexport function questionIsAnswerableFromDocs(question: string): DeflectionRefusal | null {\n  const tokens = new Set(tokenize(question))\n  if (tokens.size < MIN_QUESTION_TOKENS) return 'too-short'\n  for (const pattern of GENERATIVE_PATTERNS) {\n    if (pattern.test(question)) return 'generative'\n  }\n  for (const pattern of DIAGNOSTIC_PATTERNS) {\n    if (pattern.test(question)) return 'diagnostic'\n  }\n  return null\n}\n\n/**\n * Whether a question can be read WITHOUT the conversation it was asked in.\n *\n * Only consulted for a turn that has history — see\n * {@link CONTEXT_DEPENDENT_PATTERNS} for why the test errs towards \"no\", and\n * the class docstring for why the gate is no longer simply \"did anything\n * precede this\".\n *\n * Purely lexical, and that is a real limit worth naming: \"how do I do the\n * same for a blog post\" is caught by `the same`, while \"how do I change the\n * colour\" after a paragraph about buttons is not — nothing in those words\n * says which colour. What saves that case is not this function but the raised\n * evidence bar behind it, which such a question does not clear. The two gates\n * are one argument in two halves: this one reads the question, that one reads\n * the retrieval, and a follow-up must pass both.\n */\nexport function questionStandsAlone(question: string): boolean {\n  if (!QUESTION_CUES.test(question)) return false\n  for (const pattern of CONTEXT_DEPENDENT_PATTERNS) {\n    if (pattern.test(question)) return false\n  }\n  return true\n}\n\n/**\n * Decide whether the retrieved sections answer the question on their own, and\n * compose the answer when they do.\n *\n * `hasHistory` is passed rather than derived because the caller holds the\n * clamped history and this module must not grow an opinion about how history\n * is budgeted. It is not a hard gate any more (AGL-2486): a turn with history\n * must additionally stand on its own words and clear the raised `FOLLOW_UP_*`\n * bar, and escalates when it does not.\n */\nexport function deflectToDocs(\n  question: string,\n  scored: readonly ScoredSection[],\n  hasHistory: boolean,\n): DeflectionVerdict {\n  if (hasHistory && !questionStandsAlone(question)) return refuse('follow-up')\n  const intent = questionIsAnswerableFromDocs(question)\n  if (intent) return refuse(intent)\n  if (!scored.length) return refuse('low-score')\n\n  const minTopScore = hasHistory ? FOLLOW_UP_MIN_TOP_SCORE : MIN_TOP_SCORE\n  const minPageMargin = hasHistory ? FOLLOW_UP_MIN_PAGE_MARGIN : MIN_PAGE_MARGIN\n\n  const top = scored[0]\n  const topScore = top.score\n  if (!(topScore >= minTopScore)) return refuse('low-score', topScore)\n\n  // Score by PAGE. Sections of one page agreeing is the signal; treating them\n  // as rivals is how a strong, unambiguous match reads as a tie.\n  const perPage = new Map<string, number>()\n  for (const entry of scored) {\n    perPage.set(entry.section.path, (perPage.get(entry.section.path) ?? 0) + entry.score)\n  }\n  // The winning page is the highest-scoring PAGE, not the home of the\n  // highest-scoring section — three mid-scoring sections of one page can beat\n  // one strong section elsewhere, and when they do, that page is the answer.\n  let winner = ''\n  let winnerScore = 0\n  let rivalScore = 0\n  for (const [path, score] of perPage) {\n    if (score > winnerScore) {\n      rivalScore = winnerScore\n      winner = path\n      winnerScore = score\n    } else if (score > rivalScore) {\n      rivalScore = score\n    }\n  }\n  // No rival is not a tie — it is the cleanest possible result, one page and\n  // nothing else. `Infinity` would be honest but propagates badly through the\n  // telemetry, so a lone winner reports its own score as the margin.\n  const pageMargin = rivalScore > 0 ? winnerScore / rivalScore : winnerScore\n  if (!(pageMargin >= minPageMargin)) return refuse('ambiguous', topScore, pageMargin)\n\n  const pageSections = scored.filter((entry) => entry.section.path === winner)\n  const pageTokens = new Set<string>()\n  for (const entry of pageSections) {\n    for (const token of tokenize(entry.section.title)) pageTokens.add(token)\n    for (const token of tokenize(entry.section.heading)) pageTokens.add(token)\n    for (const token of tokenize(entry.section.text)) pageTokens.add(token)\n  }\n  const questionTokens = [...new Set(tokenize(question))]\n  let wanted = 0\n  let covered = 0\n  for (const token of questionTokens) {\n    const weight = tokenWeight(token)\n    wanted += weight\n    if (pageTokens.has(token)) covered += weight\n  }\n  const coverage = wanted > 0 ? covered / wanted : 0\n  // The relaxed floor is a FIRST-TURN allowance. It exists because coverage\n  // and dominance are evidence about the same thing, so an emphatic winner\n  // may carry a coverage miss — but mid-thread a coverage miss has a second\n  // reading: the part of the question the page ignored may be the part the\n  // conversation supplied. Turn one cannot mean that; a follow-up can, so it\n  // pays full coverage.\n  const coveredEnough =\n    coverage >= MIN_COVERAGE ||\n    (!hasHistory && coverage >= RELAXED_COVERAGE && pageMargin >= STRONG_PAGE_MARGIN)\n  if (!coveredEnough) {\n    return refuse('low-coverage', topScore, pageMargin, coverage)\n  }\n\n  const usable = pageSections.filter(\n    (entry) => entry.section.text.trim().length >= MIN_SECTION_CHARS,\n  )\n  if (!usable.length) return refuse('thin-section', topScore, pageMargin, coverage)\n\n  const quoted = usable.slice(0, MAX_QUOTED_SECTIONS).map((entry) => entry.section)\n  return {\n    answered: true,\n    refusal: null,\n    answer: composeDocsAnswer(quoted),\n    quoted,\n    page: winner,\n    topScore,\n    pageMargin,\n    coverage,\n  }\n}\n\n/**\n * The deflected answer: template + verbatim docs + real links, and nothing\n * else. Kept exported so the spec can assert the reconstruction property\n * against it directly rather than through the route.\n *\n * ⚠️ COMPOSED FOR A SURFACE THAT DOES NOT RENDER MARKDOWN. The Assist panel\n * says so in its own docstring — `renderAssistText` turns `[label](url)` and\n * bare URLs into links and renders everything else literally, under\n * `whiteSpace: 'pre-wrap'`. That is a deliberate phase-1 decision, not a gap.\n *\n * This template shipped once with the heading wrapped in `**…**`, and the * besigner drawer duly showed `**Drag-and-drop hierarchy — Moving an element\n * without dragging**`, asterisks and all. The lesson is not \"escape the\n * asterisks\" — it is that the composer has to know what renders it.\n *\n * So the heading is a bare `[label](url)` on its own line — a LINK, which is\n * the one markup the panel speaks, and which is why the title in the * screenshot was correctly clickable even while the asterisks around it were\n * not. Everything else is carried by NEWLINES, which `pre-wrap` renders,\n * rather than by markup, which it does not.\n *\n * The link has to live in the TEXT, and that is still true now that the\n * `docs` array on the `done` event IS rendered (AGL-2486, `AssistSources`).\n * It was tempting to treat that array as the structural home for the citation\n * even when nothing rendered it; it is still the wrong home, for a different\n * reason. `docs` carries every section RETRIEVED, whereas this template\n * quotes only the sections it actually used — so the array is a superset, and\n * a citation moved there would credit pages this answer never drew a word\n * from. `AssistSources` drops any url already linked in the text, which means\n * a deflected answer renders exactly as it does below and gains no duplicate\n * list underneath.\n *\n * Three specs in `docs-deflection.spec.ts` hold the line — no emphasis\n * markers, no heading markers, and a link still present.\n *\n * The closing line is not decoration. A user who reads this and finds it did\n * not answer them needs to know that asking again in different words reaches\n * something else — otherwise the cheap path looks like the assistant simply\n * being worse, and the next thing they do is stop using it.\n */\nexport function composeDocsAnswer(sections: readonly AssistDocsSection[]): string {\n  const parts: string[] = []\n  let budget = MAX_ANSWER_CHARS\n  for (const section of sections) {\n    if (budget <= MIN_SECTION_CHARS) break\n    const quote = trimToSentence(section.text, budget)\n    budget -= quote.length\n    parts.push(`[${sectionLabel(section)}](${sectionUrl(section)})\\n${quote}`)\n  }\n  parts.push(\n    'That is straight from the documentation — the headings above link to the full page. If it did not cover what you meant, ask again with more detail and I will work through it with you.',\n  )\n  return parts.join('\\n\\n')\n}\n\n/** Closest-pages links offered when nothing could be answered outright. */\nconst MAX_LINKED_SECTIONS = 4\n\n/**\n * The graceful degrade: the closest pages we found, and an honest sentence\n * saying why that is all there is (AGL-2486).\n *\n * ## Why this exists\n *\n * A deployment with no AI provider key — which includes every self-hosted\n * one on the day it comes up, and Aglyn's own production today — can answer\n * only what retrieval is confident about. A bare 501 for everything else\n * reaches the panel as \"Assist is not configured on this deployment\" — and it\n * can arrive on the SECOND question of a thread whose first question was just\n * answered in full. A capability refusal that lands after a working answer\n * reads as a fault, not a limit.\n *\n * The self-host charter says every Aglyn-operated dependency must be\n * configurable AND degrade cleanly. \"Degrades cleanly\" cannot mean \"answers\n * one question per thread and then refuses\" — a keyless deployment still has\n * the entire documentation corpus and a retrieval index over it, so the floor\n * is the best pages we found, not nothing.\n *\n * ## What it may and may not say\n *\n * The no-fabrication rule applies here exactly as it does to a deflected\n * answer, and is tighter in one respect: these pages did NOT clear the\n * confidence bar, so this text must not claim they answer the question. It\n * says they are the closest, which is true by construction — they are the\n * top of the retrieval ranking — and every word around them is a fixed\n * template plus a real section label and URL.\n *\n * It also must not name an env var. A user who wanted to read `501` would\n * have opened the network tab; the operator-facing detail stays in the API\n * error body, where an operator looks. This is the plain-English half.\n */\nexport function composeDocsLinksAnswer(\n  sections: readonly AssistDocsSection[],\n): string {\n  const links = sections\n    .slice(0, MAX_LINKED_SECTIONS)\n    .map((section) => `[${sectionLabel(section)}](${sectionUrl(section)})`)\n  if (!links.length) return ''\n  return [\n    'I could not find one page in the documentation that clearly answers that, and the part of me that talks a question through with you is not switched on for this deployment yet — an administrator has to finish setting it up.',\n    'These are the closest pages I found:',\n    links.join('\\n'),\n    'If none of them cover it, asking again in different words often lands somewhere better.',\n  ].join('\\n\\n')\n}\n"],"names":["DOCS_SITE_ORIGIN","docsDocumentFrequency","tokenize","MIN_QUESTION_TOKENS","MIN_TOP_SCORE","MIN_PAGE_MARGIN","MIN_COVERAGE","RELAXED_COVERAGE","STRONG_PAGE_MARGIN","FOLLOW_UP_MIN_TOP_SCORE","FOLLOW_UP_MIN_PAGE_MARGIN","QUESTION_CUES","CONTEXT_DEPENDENT_PATTERNS","MIN_SECTION_CHARS","MAX_QUOTED_SECTIONS","MAX_ANSWER_CHARS","GENERATIVE_PATTERNS","DIAGNOSTIC_PATTERNS","refuse","refusal","topScore","pageMargin","coverage","answered","answer","quoted","page","tokenWeight","token","frequency","sections","seen","get","Math","log","sectionUrl","section","path","anchor","sectionLabel","heading","title","trimToSentence","text","limit","trimmed","trim","length","window","slice","lastStop","max","lastIndexOf","trimEnd","questionIsAnswerableFromDocs","question","tokens","Set","size","pattern","test","questionStandsAlone","deflectToDocs","scored","hasHistory","intent","minTopScore","minPageMargin","top","score","perPage","Map","entry","set","winner","winnerScore","rivalScore","pageSections","filter","pageTokens","add","questionTokens","wanted","covered","weight","has","coveredEnough","usable","map","composeDocsAnswer","parts","budget","quote","push","join","MAX_LINKED_SECTIONS","composeDocsLinksAnswer","links"],"mappings":"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"}