cbrowser 20.2.2 → 21.0.0

package/dist/mcp-tools/base/audit-tools.js

@@ -8,8 +8,15 @@ import { z } from "zod";
 import { barrierWeightFor, weightedSeverity, weightKeyFor } from "../../visual/perceptual-transport.js";
 import { writeArtifact } from "../../artifact-store.js";
 import { buildContentWithPreviews } from "../inline-image.js";
-import { bridgeCapacityTraits } from "../../visual/cognitive-models.js";
+import { bridgeCapacityTraits, personaRateContext } from "../../visual/cognitive-models.js";
+import { lawTimesReport } from "../../visual/law-times-report.js";
+import { resolveSiteFamiliarity as resolveRunFamiliarity } from "./site-familiarity.js";
 import { refuseHostedUrl } from "../hosted-inputs.js";
+import { activeProvenance, collectPersonaReads, isolatedProvenanceAsync, personaRateProvenance, ATTENTION_PROVENANCE_TEXT } from "../../visual/model-provenance.js";
+import { ctcRank } from "../../visual/ctc-bands.js";
+import { recordedAnswer } from "./answer-provenance.js";
+import { resolveChainValues, valueModulationReport } from "./chain-values.js";
+import { storyEffortSection, storyVerdict } from "./story-narrative.js";
 import { runAgentReadyAudit, pageAgentReadyFindings, runCompetitiveBenchmark, runEmpathyAudit, runWebMCPReadyAudit, } from "../../analysis/index.js";
 import { listAccessibilityPersonas } from "../../personas.js";
 import { barrierElementCount, countAffectedElements } from "../../analysis/accessibility-empathy.js";
@@ -17,7 +24,7 @@ import { getDefaultConfig, effectiveDataDir } from "../../config.js";
 import { describeRenderTarget } from "../../devices.js";
 import { writeFileSync, mkdirSync, existsSync } from "fs";
 import { join } from "path";
-import { makeTempDir } from "../../temp-files.js";
+import { makeTempDir, uniqueStamp } from "../../temp-files.js";
 /**
  * Persist an audit screenshot and return its path.
  *
@@ -39,7 +46,9 @@ export function writeAuditScreenshot(base64, persona) {
         const dir = join(effectiveDataDir(), "audit-screenshots");
         if (!existsSync(dir))
             mkdirSync(dir, { recursive: true });
-        const path = join(dir, `empathy-${safe}-${Date.now()}.png`);
+        // Time plus random bits: two audits of one persona in the same
+        // millisecond wrote one file and both returned its path.
+        const path = join(dir, `empathy-${safe}-${uniqueStamp()}.png`);
         writeFileSync(path, Buffer.from(base64, "base64"));
         out.path = path;
     }
@@ -66,6 +75,10 @@ export function writeAuditScreenshot(base64, persona) {
 /**
  * Register audit tools (4 tools + site_cognitive_assessment + visual_cognitive_story)
  */
+// One shared helper for every attention caller (ISC-48, ISC-48.1): the persona
+// record's own accessibilityTraits, only the fields it sets. It used to be
+// copied here and in the other tool file.
+import { personaStoredAccessibilityTraits as personaAccessibilityTraits } from "../../visual/stored-accessibility-traits.js";
 export function registerAuditTools(server, context) {
     const getBrowserByToken = context?.getBrowserByToken;
     server.registerTool("agent_ready_audit", {
@@ -204,17 +217,16 @@ export function registerAuditTools(server, context) {
     // ── Site Cognitive Assessment (Composite Pipeline) ──
     server.registerTool("site_cognitive_assessment", {
         title: "Site Cognitive Assessment",
-        description: "Three-gate pipeline: (1) bot-detection probe, (2) agent-ready qualification, (3) per-persona cognitive effort analysis. IMPORTANT: If the user requests high-familiarity personas (power-user, confident-user), check site_model_status first. Without site knowledge, these personas are tested as first-time visitors and a familiarityWarning is returned. Ask the user if they want to build site knowledge first.",
+        description: "Three-gate pipeline: (1) bot-detection probe, (2) agent-ready qualification, (3) per-persona cognitive effort analysis. Site familiarity is per run: pass siteFamiliarity (0 first visit, 1 regular user) or every persona is scored as a first visit. No persona carries a familiarity of its own, and site knowledge from crawling is reported but does not change the score.",
         inputSchema: {
             url: z.string().url().describe("URL to assess"),
             personas: z.string().optional().default("first-timer,cognitive-adhd").describe("Comma-separated persona names (default: first-timer,cognitive-adhd)"),
             threshold: z.number().optional().default(60).describe("Minimum agent-ready score to proceed to persona analysis (default: 60)"),
             // Per RUN, not per persona. The same person is familiar with one site and new
-            // to another, so this has no value until a site is named -- a stored value only
-            // ever answered "familiar with which site?" by accident. The persona's value is
-            // the fallback when a caller does not pass one. (2026-08-01)
+            // to another, so this has no value until a site is named. Omitted, the run
+            // scores a first visit (0.0); see site-familiarity.ts. (2026-08-01, 21.0)
             siteFamiliarity: z.number().min(0).max(1).optional()
-                .describe("How familiar these personas are with THIS site: 0 first visit, 1 regular user. Overrides any value stored on the persona. Familiarity is a persona-site pair, not a disposition, so set it per run."),
+                .describe("How familiar these personas are with THIS site: 0 first visit, 1 regular user. Omitted, every persona is scored as a first visit (0). Familiarity is a persona-site pair, not a disposition, so set it per run; site knowledge does not supply it."),
             userLocation: z.string().optional().describe("User's approximate location (e.g., 'Denver, Colorado, US') — for geo-aware content expectations"),
             userTimezone: z.string().optional().describe("User's timezone (e.g., 'America/Denver') — for time-sensitive content evaluation"),
             userLanguage: z.string().optional().describe("User's expected language (e.g., 'en-US') — for readability calibration"),
@@ -233,7 +245,9 @@ export function registerAuditTools(server, context) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ url, personas, threshold, siteFamiliarity, userLocation, userTimezone, userLanguage, proxy, geoRegion, device, waitAfterLoad, waitForSelector, scope, _browserToken }) => {
+    }, recordedAnswer(async ({ url, personas, threshold, siteFamiliarity, userLocation, userTimezone, userLanguage, proxy, geoRegion, device, waitAfterLoad, waitForSelector, scope, _browserToken }) => {
+        // recordedAnswer: one provenance recording per call, across every await,
+        // reported as modelProvenance once gate 3 has scored (answer-provenance.ts).
         // Hosted: http(s) only (sec-paths, 2026-10-10; see hosted-inputs.ts).
         const hostedRefusal = refuseHostedUrl("site_cognitive_assessment", { url });
         if (hostedRefusal)
@@ -492,6 +506,10 @@ export function registerAuditTools(server, context) {
                 }
                 // ── Gate 3: Per-Persona Cognitive Effort ──
                 const personaResults = {};
+                // Each scored persona's rank sentence, for the recommendations below.
+                const rankSentences = {};
+                // Each scored persona's motor and reading rates (personaRateProvenance).
+                const personaRates = {};
                 const { buildOTCognitiveProfile } = await import("../../visual/cognitive-transport.js");
                 const { computeDemandDistribution, computeSequentialCTC } = await import("../../visual/cognitive-transport-chain.js");
                 const { extractPageMetrics } = await import("../../visual/cognitive-transport.js");
@@ -518,7 +536,6 @@ export function registerAuditTools(server, context) {
                 // extractPageMetrics runs its own lazy-load scroll walk at full_page, so
                 // forwarding the scope is the entire fix.
                 const pageMetrics = await extractPageMetrics(metricsPage, auditScope);
-                const demand = computeDemandDistribution(pageMetrics);
                 // Page understanding
                 let pageUnderstanding = null;
                 try {
@@ -536,8 +553,8 @@ export function registerAuditTools(server, context) {
                     };
                 }
                 catch { }
-                // Check site knowledge — binary gate for siteFamiliarity
-                // Has data = persona keeps its familiarity. No data = forced to 0.0 (first visit).
+                // Site knowledge is looked up only to report it. siteFamiliarity is the
+                // caller's value or 0.0 (first visit), whatever this install has crawled.
                 let hasSiteKnowledge = false;
                 try {
                     const domain = new URL(url).hostname;
@@ -554,26 +571,13 @@ export function registerAuditTools(server, context) {
                             resolvePersonaOrThrow(personaName);
                         const personaObj = existingPersona || createCognitivePersona(personaName, personaName, {});
                         const traits = { ...(personaObj.cognitiveTraits || {}) };
-                        // Familiarity is a persona-SITE pair, so the caller's value for THIS
-                        // run wins over anything stored on the persona. A stored value only
-                        // ever answered "familiar with which site?" by accident.
-                        // (2026-08-01)
-                        const reqFam = traits.siteFamiliarity ?? 0.5;
-                        const familiarityFromCaller = typeof siteFamiliarity === "number";
-                        if (familiarityFromCaller) {
-                            traits.siteFamiliarity = siteFamiliarity;
-                        }
-                        else {
-                            // v18.61.0: without an explicit value it stays a binary gate on
-                            // whether this install has crawled the site at all.
-                            if (hasSiteKnowledge) {
-                                if (reqFam > 0.5)
-                                    traits.siteFamiliarity = 1.0;
-                            }
-                            else {
-                                traits.siteFamiliarity = 0.0;
-                            }
-                        }
+                        // Familiarity is the visit's: the caller's value for THIS run, else
+                        // 0.0, the same for every persona. Since 21.0 (Stage C) it is
+                        // Cockburn et al.'s expertise e on the choosing time, handed to the
+                        // demand, not a persona trait. Through 20.x a site-knowledge branch
+                        // left the trait unset, which the chain read as 0.5 (site-familiarity.ts).
+                        const { resolveSiteFamiliarity } = await import("./site-familiarity.js");
+                        const familiarity = resolveSiteFamiliarity(siteFamiliarity, hasSiteKnowledge);
                         // Bridge the derived capacities before building the profile. This was
                         // MISSING here and present in cognitive_effort, so the motor layer --
                         // whose sole trait is motorCapacity -- scored against traitValue's
@@ -589,11 +593,22 @@ export function registerAuditTools(server, context) {
                         // This moves more than motor. readability, readingAttention, totalCTC,
                         // bottleneck and abandonmentRisk all shift for every persona here, all
                         // converging on what cognitive_effort already reported.
-                        bridgeCapacityTraits(personaName, traits, personaObj.accessibilityTraits);
+                        personaRates[personaName] = personaRateProvenance(collectPersonaReads(() => bridgeCapacityTraits(personaName, traits, personaObj.accessibilityTraits, personaRateContext(personaObj))).ids);
                         const otProfile = buildOTCognitiveProfile(personaName, traits);
-                        const result = computeSequentialCTC(otProfile, demand, { asymmetric: true, interactions: true });
+                        // Rebuilt for each persona from the same metrics, so every persona is
+                        // scored against the same demand; this tool has no values option. The
+                        // whole handler is one provenance recording, so the demand curves and
+                        // the chain are counted with everything else the answer read.
+                        const result = computeSequentialCTC(otProfile, computeDemandDistribution(pageMetrics, { siteFamiliarity: familiarity.value }), { asymmetric: true, interactions: true });
+                        const rank = ctcRank(result);
+                        rankSentences[personaName] = rank.sentence;
                         personaResults[personaName] = {
+                            // A percentile of the real reference pages (21.x); `band` names its band.
                             totalCTC: Math.round(result.totalCTC * 1000) / 1000,
+                            // Its 95% interval across bootstrap resamples of the reference pages.
+                            totalCTCInterval: result.totalCTCInterval.map((x) => Math.round(x * 1000) / 1000),
+                            band: rank.band,
+                            referenceScope: result.referenceScope,
                             bottleneck: result.bottleneckLayer,
                             abandonmentRisk: Math.round(result.abandonmentRisk * 100) + "%",
                             deficit: Math.round(result.deficitCost * 1000) / 1000,
@@ -602,13 +617,9 @@ export function registerAuditTools(server, context) {
                                 name: l.name,
                                 cost: Math.round(l.transportCost * 1000) / 1000,
                             })),
-                            // Only warn about the automatic downgrade. A caller who SET the
-                            // value for this run has already answered the question the
-                            // downgrade exists to answer.
-                            ...(!familiarityFromCaller && reqFam > 0.5 && !hasSiteKnowledge ? {
-                                familiarityWarning: `siteFamiliarity downgraded from ${reqFam} to 0.0 — no site knowledge exists for this domain. Pass siteFamiliarity on this call to state it directly, or run page_understand first.`,
-                            } : {}),
-                            ...(familiarityFromCaller ? { siteFamiliaritySource: "supplied for this run" } : {}),
+                            siteFamiliarity: familiarity.value,
+                            siteFamiliaritySource: familiarity.source,
+                            siteKnowledgeAvailable: familiarity.siteKnowledgeAvailable,
                         };
                     }
                     catch (personaErr) {
@@ -616,6 +627,9 @@ export function registerAuditTools(server, context) {
                     }
                 }
                 response.gate3 = { status: "complete", personas: personaResults };
+                // Holds its place in the JSON; filled after the recommendations, which
+                // read the band constants, so the block covers the whole answer.
+                response.modelProvenance = undefined;
                 response.pageMetrics = {
                     informationDensity: Math.round(pageMetrics.informationDensity * 1000) / 1000,
                     visualComplexity: Math.round(pageMetrics.visualComplexity * 1000) / 1000,
@@ -628,6 +642,9 @@ export function registerAuditTools(server, context) {
                     longWordRatio: Math.round(pageMetrics.longWordRatio * 1000) / 1000,
                     technicalDensity: Math.round(pageMetrics.technicalDensity * 1000) / 1000,
                     scriptFamily: pageMetrics.scriptFamily || "alphabetic",
+                    // Stage B: the four law times behind the motor, decision, procedure and reading
+                    // demands; choosing at the run's siteFamiliarity (Stage C).
+                    lawTimes: lawTimesReport(pageMetrics, resolveRunFamiliarity(siteFamiliarity, false).value),
                     // Every ratio above is 0-1 NORMALIZED, not a raw measurement.
                     // cognitive_effort's readability penalties report avg word length in
                     // raw CHARACTERS (e.g. 11.4), so the same name carried two scales
@@ -639,14 +656,24 @@ export function registerAuditTools(server, context) {
                 if (pageUnderstanding)
                     response.pageUnderstanding = pageUnderstanding;
                 // Generate recommendations
+                // The rank, not a bare totalCTC: "CTC=0.41" read as a cost on a scale
+                // it is no longer on (a percentile since 21.x), with no reference named.
                 const recommendations = [];
                 for (const [name, data] of Object.entries(personaResults)) {
                     const d = data;
                     if (d.bottleneck) {
-                        recommendations.push(`${name}: Reduce ${d.bottleneck} complexity (primary bottleneck, CTC=${d.totalCTC})`);
+                        recommendations.push(`${name}: reduce ${d.bottleneck} complexity first, the costliest layer. ${rankSentences[name]}`);
                     }
                 }
                 response.recommendations = recommendations.slice(0, 5);
+                // Reported when at least one persona was scored, as before.
+                if (Object.keys(rankSentences).length > 0) {
+                    response.modelProvenance = activeProvenance();
+                    // Per scored persona, counted apart from the score's constants.
+                    response.personaRateProvenance = Object.fromEntries(Object.keys(rankSentences).map((n) => [n, personaRates[n]]));
+                }
+                else
+                    delete response.modelProvenance;
                 response.result = "COMPLETE";
                 response.duration = `${Date.now() - startTime}ms`;
                 // Auto-save to site dashboard
@@ -683,7 +710,7 @@ export function registerAuditTools(server, context) {
             response.duration = `${Date.now() - startTime}ms`;
         }
         return { content: [{ type: "text", text: JSON.stringify(response, null, 2) }] };
-    });
+    }));
     // ── Visual Cognitive Story ──
     server.registerTool("visual_cognitive_story", {
         title: "Visual Cognitive Story",
@@ -692,7 +719,7 @@ export function registerAuditTools(server, context) {
             url: z.string().url().describe("URL to analyze"),
             persona: z.string().optional().default("cognitive-adhd").describe("Persona name"),
             device: z.string().optional().describe("Device to emulate: 'mobile', 'tablet', 'desktop' (1920x1080), or a specific device like 'iPhone 15', 'Pixel 7', 'iPad Pro 11'. Default: no emulation, at the configured viewport (1920x1080 unless CBROWSER_VIEWPORT_WIDTH/HEIGHT or the config file say otherwise); the response reports the device and viewport used. Ignored with _browserToken (the session keeps its own)."),
-            useValues: z.boolean().optional().default(false).describe("Enable motivational value influence on saliency map generation, attention scoring, and narrative. Default: false."),
+            useValues: z.boolean().optional().default(false).describe("Apply the persona's Schwartz values (opt-in). They change two things: the attention quality scoring (which CTAs and distractors the persona weights), and the effort summary, where they modulate the page's demand inside the chain through its registered coefficients (chain.valueModulation.*, hand-set hypotheses, counted in modelProvenance), exactly as cognitive_effort's useValues does. They do not change the attention heatmap. `valueModulation` in the response says whether values were found for the chain and which scores it used. Default: false."),
             // Goal-directed attention is the largest single lever in the semantic
             // layer: computeGoalRelevance boosts any element whose text matches the
             // goal's keywords, which is what separates "where the eye lands on this
@@ -710,12 +737,15 @@ export function registerAuditTools(server, context) {
             idempotentHint: false,
             openWorldHint: true,
         },
-    }, async ({ url, persona, device, useValues, goal, aiLayer, _browserToken }) => {
+    }, recordedAnswer(async ({ url, persona, device, useValues, goal, aiLayer, _browserToken }) => {
+        // recordedAnswer: one provenance recording per call, across every await,
+        // reported as modelProvenance (answer-provenance.ts).
         // Hosted: http(s) only (sec-paths, 2026-10-10; see hosted-inputs.ts).
         const hostedRefusal = refuseHostedUrl("visual_cognitive_story", { url });
         if (hostedRefusal)
             return hostedRefusal;
         const startTime = Date.now();
+        const { writeFileSync, mkdirSync, existsSync } = await import("fs");
         let ownsVcsBrowser = true;
         // The screenshot's own temp dir, removed in the finally below: a
         // clock-named file in the shared temp dir was read by concurrent calls.
@@ -772,6 +802,7 @@ export function registerAuditTools(server, context) {
                     ? `the PNG at images.${name}`
                     : "not available (the artifact store was unavailable, so the full-resolution PNG was not saved)";
                 // ── 1. Attention Heatmap ──
+                let attentionProvenance;
                 let attentionData = null;
                 try {
                     const { analyzeAttention } = await import("../../visual/attention-transport.js");
@@ -782,12 +813,19 @@ export function registerAuditTools(server, context) {
                     // different model wearing the same name. (2026-07-29)
                     const { collectDomAttentionElements } = await import("../../visual/attention-quality.js");
                     const domAttentionElements = await collectDomAttentionElements(page).catch(() => []);
-                    const attnResult = await analyzeAttention(ssPath, persona, 4, undefined, domAttentionElements, goal);
+                    const a11y = await personaAccessibilityTraits(persona);
+                    // Recorded apart from the score (attentionProvenance): the attention
+                    // model reads fitted gaze calibration and published colour science,
+                    // and counted in modelProvenance they made the effort score look
+                    // partly fitted while the map does not feed it.
+                    const { result: attnResult, provenance } = await isolatedProvenanceAsync(() => analyzeAttention(ssPath, persona, 4, undefined, domAttentionElements, goal, undefined, undefined, a11y), ATTENTION_PROVENANCE_TEXT);
+                    attentionProvenance = provenance;
                     attentionData = {
                         entropy: attnResult.entropy,
                         concentration: attnResult.concentration,
                         hotspots: attnResult.saliencyMap?.hotspots || [],
                         saliencyMap: attnResult.saliencyMap,
+                        perceptualProfile: attnResult.perceptualProfile,
                     };
                     if (attnResult.saliencyMap) {
                         const { generateHeatmapOverlay } = await import("../../visual/heatmap-overlay.js");
@@ -943,6 +981,14 @@ export function registerAuditTools(server, context) {
                 }
                 // ── 4. Cognitive Effort Summary ──
                 let effortData = null;
+                // Unrounded, for the narrative: a band edge must not move with display rounding.
+                let storyEffort = null;
+                // The ids the bridge read for this persona: personaRateProvenance below.
+                let storyPersonaRateIds = new Set();
+                // useValues reaches the chain here exactly as in cognitive_effort: the
+                // persona's Schwartz scores, through the chain's registered modulation.
+                // Through 21.0 the flag never reached this summary at all.
+                const chainValues = useValues ? await resolveChainValues(persona) : undefined;
                 try {
                     const { buildOTCognitiveProfile } = await import("../../visual/cognitive-transport.js");
                     const { computeDemandDistribution, computeSequentialCTC } = await import("../../visual/cognitive-transport-chain.js");
@@ -950,11 +996,24 @@ export function registerAuditTools(server, context) {
                     const { getAnyPersona, createCognitivePersona, resolvePersonaOrThrow } = await import("../../personas.js");
                     // A miss throws instead of yielding an all-midpoint stand-in.
                     const personaObj = getAnyPersona(persona) || resolvePersonaOrThrow(persona);
-                    const traits = (personaObj.cognitiveTraits || {});
+                    // A copy, because the bridge writes into what it is given. This was the
+                    // registry's own object, so one story run left the persona carrying
+                    // three derived capacities for the rest of the process, which
+                    // cognitive_distance then read as stored traits (first-timer to
+                    // power-user moved 0.1512 -> 0.1550). (2026-10-21)
+                    const traits = { ...(personaObj.cognitiveTraits || {}) };
+                    // A first visit, as cognitive_effort and site_cognitive_assessment
+                    // score it when no familiarity is supplied (this tool takes none).
+                    // Left unset, the chain read the missing-trait capacity (0.5) for
+                    // siteFamiliarity, the 20.x defect site-familiarity.ts describes, and
+                    // this summary disagreed with cognitive_effort on the same page and
+                    // persona (first-timer, prose fixture: 0.669 against 0.700).
+                    const { resolveSiteFamiliarity } = await import("./site-familiarity.js");
+                    const familiarity = resolveSiteFamiliarity(undefined, false);
                     // Same bridge as Gate 3 and cognitive_effort. Without it this tool has
                     // the identical missing-capacity defect and would reproduce the motor
                     // disagreement against cognitive_effort the moment anyone compared them.
-                    bridgeCapacityTraits(persona, traits, personaObj.accessibilityTraits);
+                    storyPersonaRateIds = collectPersonaReads(() => bridgeCapacityTraits(persona, traits, personaObj.accessibilityTraits, personaRateContext(personaObj))).ids;
                     const otProfile = buildOTCognitiveProfile(persona, traits);
                     // viewport-by-design: visual_cognitive_story declares no `scope` parameter,
                     // so it promises the caller nothing about how much of the page it read, and
@@ -963,13 +1022,33 @@ export function registerAuditTools(server, context) {
                     // a scope WAS offered, echoed, and then not applied. If this tool ever gains
                     // a scope, this marker must go and the scope must be threaded.
                     const pageMetrics = await extractPageMetrics(page);
-                    const demand = computeDemandDistribution(pageMetrics);
-                    const ctcResult = computeSequentialCTC(otProfile, demand, { asymmetric: true, interactions: true });
+                    const demand = computeDemandDistribution(pageMetrics, { siteFamiliarity: familiarity.value });
+                    const ctcResult = computeSequentialCTC(otProfile, demand, {
+                        asymmetric: true, interactions: true, ...(chainValues ? { schwartzValues: chainValues } : {}),
+                    });
+                    const rank = ctcRank(ctcResult);
                     effortData = {
+                        // A percentile of the real reference pages (21.x); `rank` says it in words.
                         totalCTC: Math.round(ctcResult.totalCTC * 1000) / 1000,
+                        // Its 95% interval across bootstrap resamples of the reference pages.
+                        totalCTCInterval: ctcResult.totalCTCInterval.map((x) => Math.round(x * 1000) / 1000),
+                        band: rank.band,
+                        referenceScope: ctcResult.referenceScope,
+                        rank: rank.sentence,
+                        raw: Math.round(ctcResult.rawCTC * 1000) / 1000,
                         bottleneck: ctcResult.bottleneckLayer,
                         abandonmentRisk: Math.round(ctcResult.abandonmentRisk * 100),
                         layers: ctcResult.layers.map(l => ({ name: l.name, cost: Math.round(l.transportCost * 1000) / 1000 })),
+                        siteFamiliarity: familiarity.value,
+                        siteFamiliaritySource: familiarity.source,
+                    };
+                    storyEffort = {
+                        totalCTC: ctcResult.totalCTC,
+                        totalCTCInterval: ctcResult.totalCTCInterval,
+                        rawCTC: ctcResult.rawCTC,
+                        referenceScope: ctcResult.referenceScope,
+                        bottleneck: ctcResult.bottleneckLayer,
+                        abandonmentRiskPercent: Math.round(ctcResult.abandonmentRisk * 100),
                     };
                 }
                 catch (e) {
@@ -1025,9 +1104,6 @@ export function registerAuditTools(server, context) {
                 // ── Build narrative ──
                 const concentration = attentionData?.concentration ?? 0;
                 const entropy = attentionData?.entropy ?? 0;
-                const ctc = effortData?.totalCTC ?? 0;
-                const bottleneck = effortData?.bottleneck ?? "unknown";
-                const risk = effortData?.abandonmentRisk ?? 0;
                 const qualityData = urls.qualityData;
                 const _nu = new URL(url);
                 let narrative = `## ${persona} on ${_nu.hostname.replace(/^www\d*\./, '')}${_nu.pathname !== '/' ? _nu.pathname.replace(/\/$/, '') : ''}\n\n`;
@@ -1054,11 +1130,10 @@ export function registerAuditTools(server, context) {
                 else {
                     narrative += `Attention is spread evenly (concentration: ${pct}%) without a dominant anchor, though the page is not visually noisy. Nothing is fighting for attention; nothing is claiming it either.\n\n`;
                 }
-                narrative += `### The Effort: How Hard It Is\n`;
-                narrative += `Total cognitive transport cost: ${ctc.toFixed(2)}. `;
-                narrative += ctc < 0.5 ? `This page is comfortable for ${persona}. ` : ctc < 1.0 ? `Moderate effort required. ` : `Significant cognitive burden. `;
-                narrative += `The bottleneck is **${bottleneck}** — this is where the design creates the most friction.\n`;
-                narrative += `Abandonment risk: **${risk}%**.\n\n`;
+                // The rank, from the registered bands (story-narrative.ts). This read
+                // totalCTC on the logistic: "comfortable" below 0.5, "Significant
+                // cognitive burden" from 1.0, and 0 (comfortable) when effort failed.
+                narrative += storyEffortSection(persona, storyEffort);
                 narrative += `### The Question: Do They See What Matters?\n`;
                 if (qualityData) {
                     const cta = qualityData.ctaCaptureRate ?? 0;
@@ -1075,31 +1150,12 @@ export function registerAuditTools(server, context) {
                     narrative += `Attention quality data unavailable.\n`;
                 }
                 narrative += `\n### The Verdict\n`;
-                // The verdict branched on ctc and ctaCaptureRate ONLY, ignoring the
-                // distractor ratio and quality score printed directly above it. So a
-                // page scoring 31/100 with 70% of attention on non-actionable elements
-                // was told "**Strong.** Easy to use AND attention lands on CTAs" — the
-                // verdict contradicting its own evidence one line later. A summary that
-                // reads less of the data than the section above it is worse than no
-                // summary, because it is the line people quote. (2026-07-29)
-                const distractRatio = qualityData?.distractorRatio ?? 0;
-                const qScore = qualityData?.qualityScore ?? 0;
-                const leaking = distractRatio > 0.4 || (qualityData !== undefined && qScore < 50);
-                if (ctc < 0.5 && (qualityData?.ctaCaptureRate ?? 0) > 0.2 && !leaking) {
-                    narrative += `**Strong.** Easy to use AND attention lands on CTAs. This page works for ${persona}.`;
-                }
-                else if (ctc < 0.5 && (qualityData?.ctaCaptureRate ?? 0) > 0.2 && leaking) {
-                    narrative += `**Mixed.** Low cognitive effort and the CTAs do get seen, but attention quality is ${qScore}/100 with ${(distractRatio * 100).toFixed(0)}% going to non-actionable elements. ${persona} can use this page; the design is spending most of their attention on things that do not convert.`;
-                }
-                else if (ctc < 0.5 && (qualityData?.ctaCaptureRate ?? 0) < 0.1) {
-                    narrative += `**Easy but unfocused.** Low cognitive effort, but attention misses the CTAs. The page needs stronger visual hierarchy to guide ${persona} toward conversion.`;
-                }
-                else if (ctc > 1.0 && (qualityData?.ctaCaptureRate ?? 0) > 0.2) {
-                    narrative += `**Hard but focused.** High cognitive effort, but when ${persona} pushes through, they see the CTAs. Reduce complexity to lower the abandonment risk without losing the visual focus.`;
-                }
-                else {
-                    narrative += `**Needs work.** High effort AND low CTA visibility. ${persona} is both struggling to process the page AND not seeing the conversion path. Prioritize: simplify the ${bottleneck} layer, then make CTAs more prominent.`;
-                }
+                // Reads the distractor ratio and quality score as well as the CTA rate:
+                // a verdict that reads less of the data than the section above it is
+                // the line people quote and the one that contradicts it (2026-07-29).
+                // Cost is the registered band; every branch is reachable and tested
+                // (story-narrative.ts, tests/story-verdict.test.ts).
+                narrative += storyVerdict(persona, storyEffort, qualityData).text;
                 // ── Assemble response ──
                 // Third layer, opt-in. Runs AFTER the deterministic layers and is
                 // reported beside them rather than folded in: layers 1 and 2 are
@@ -1133,9 +1189,13 @@ export function registerAuditTools(server, context) {
                     ...(aiAttention ? { aiAttention } : {}),
                     images: urls,
                     effort: effortData,
+                    // Only when useValues asked for it, as in cognitive_effort.
+                    ...(useValues ? { valueModulation: valueModulationReport(chainValues) } : {}),
                     attention: {
                         entropy: Math.round(entropy * 1000) / 1000,
                         concentration: Math.round(concentration * 1000) / 1000,
+                        // Which perceptual filter drew the map, as attention_analysis reports it.
+                        perceptualProfile: attentionData?.perceptualProfile ?? null,
                     },
                     quality: qualityData ? {
                         ctaCaptureRate: qualityData.ctaCaptureRate,
@@ -1143,6 +1203,14 @@ export function registerAuditTools(server, context) {
                         score: qualityData.qualityScore,
                     } : null,
                     duration: `${Date.now() - startTime}ms`,
+                    // Every registered constant the effort score read, the same block
+                    // cognitive_effort reports. Taken here, after every step that reads one;
+                    // fitting the previews below reads none.
+                    modelProvenance: activeProvenance(),
+                    // The scored persona's motor and reading rates, counted apart from the score's constants.
+                    ...(storyEffort ? { personaRateProvenance: personaRateProvenance(storyPersonaRateIds) } : {}),
+                    // The attention analysis's own block, kept out of modelProvenance.
+                    ...(attentionProvenance ? { attentionProvenance } : {}),
                 };
                 // Every overlay rides along as a preview, the budget split between them
                 // so text plus all images stays under the cap; imagePreviews says what
@@ -1165,7 +1233,7 @@ export function registerAuditTools(server, context) {
                     }],
             };
         }
-    });
+    }));
 }
 /**
  * The canonical empathy_audit. Exported on its own so the stdio server can