cbrowser 18.78.0 → 18.80.0

package/dist/mcp-tools/persona-creation-tools.js

@@ -14,7 +14,12 @@
  * @license MIT
  */
 import { z } from "zod";
-import { generatePersonaQuestionnaire, buildTraitsFromAnswers, deriveValuesFromTraits, TRAIT_REFERENCE_MATRIX, } from "../persona-questionnaire.js";
+import { generatePersonaQuestionnaire, buildTraitsFromAnswers, buildBigFiveFromAnswers, deriveValuesFromTraits, TRAIT_REFERENCE_MATRIX, } from "../persona-questionnaire.js";
+import { bigFiveInferenceReference, validateInferredBigFive } from "../values/big-five-inference.js";
+import { deriveValuesFromBigFive } from "../values/big-five-values.js";
+import { TRAIT_INFERENCE_CRITERIA, ALL_TRAITS, assessTraitCompleteness } from "../values/persona-completeness.js";
+import { summariseTraits } from "../values/persona-diff.js";
+import { widgetUri } from "./widget-kit.js";
 const VALUES_QUESTIONS = [
     {
         id: "security",
@@ -168,8 +173,7 @@ function getTraitHeader(trait) {
         emotionalContagion: "Emotional",
         fearOfMissingOut: "FOMO",
         socialProofSensitivity: "Social Proof",
-        mentalModelRigidity: "Flexibility",
-        siteFamiliarity: "Site Memory",
+        mentalModelFlexibility: "Flexibility",
     };
     return headers[trait] || trait;
 }
@@ -203,7 +207,7 @@ export function registerPersonaCreationTools(server) {
         description: "Start creating a custom persona. Best practice: present the choice to the user via AskUserQuestion (questionnaire vs description mode) rather than showing raw JSON.",
         inputSchema: {
             persona_name: z.string().describe("Name for the new persona (e.g., 'tech-savvy-millennial')"),
-            comprehensive: z.boolean().optional().describe("Include all 25 traits (true) or just core 8 traits (false, default)"),
+            comprehensive: z.boolean().optional().describe("Include all 26 traits (true) or just core 8 traits (false, default)"),
         },
         annotations: {
             title: "Start Persona Creation",
@@ -259,7 +263,7 @@ IMPORTANT: Do NOT show this text to the user. USE AskUserQuestion to present the
         description: "Start the questionnaire mode for persona creation. Each question is best presented via AskUserQuestion for interactive selection.",
         inputSchema: {
             persona_name: z.string().describe("Name for the new persona"),
-            comprehensive: z.boolean().optional().describe("Include all 25 traits (default: false, core 8 traits only)"),
+            comprehensive: z.boolean().optional().describe("Include all 26 traits (default: false, core 8 traits only)"),
         },
         annotations: {
             title: "Start Persona Questionnaire",
@@ -296,7 +300,7 @@ IMPORTANT: Do NOT show this text to the user. USE AskUserQuestion to present the
 Question 1 of ${totalQuestions} (Trait: ${firstQuestion.trait})
 "${thirdPersonQuestion}"
 
-Header: "${getTraitHeader(firstQuestion.trait)}"
+Header: "${firstQuestion.trait ? getTraitHeader(firstQuestion.trait) : firstQuestion.id}"
 
 Options:
 ${firstQuestion.options.map((o, i) => `${i + 1}. "${o.label}" - ${o.description}`).join("\n")}
@@ -338,8 +342,10 @@ IMPORTANT: Use AskUserQuestion - do NOT just display this text.`,
         const now = Date.now();
         if (session.phase === "traits") {
             const currentQuestion = session.questions[session.currentIndex];
-            session.answers[currentQuestion.trait] = answer_value;
-            session.answerMetadata[currentQuestion.trait] = {
+            // Keyed by id so Big Five items, which carry no trait, land somewhere
+            // real. For a trait question id and trait are the same string.
+            session.answers[currentQuestion.id] = answer_value;
+            session.answerMetadata[currentQuestion.id] = {
                 value: answer_value,
                 answeredAt: now,
                 questionIndex: session.currentIndex,
@@ -366,6 +372,13 @@ IMPORTANT: Use AskUserQuestion - do NOT just display this text.`,
         // Check if completely done
         if (session.phase === "values" && session.currentIndex >= session.valueQuestions.length) {
             const traits = buildTraitsFromAnswers(session.answers);
+            // Big Five answers, if the questionnaire included them. Kept on the
+            // persona so anything deriving values later has the layer the research
+            // actually relates to values, rather than re-deriving from cognitive
+            // traits and crossing a gap the literature does not cover. Without
+            // this the five items would have been asked and thrown away.
+            // (2026-08-01)
+            const bigFive = buildBigFiveFromAnswers(session.answers);
             const derivedResult = deriveValuesFromTraits(traits);
             const derivedValues = derivedResult.values;
             const values = {
@@ -389,6 +402,7 @@ IMPORTANT: Use AskUserQuestion - do NOT just display this text.`,
                         text: JSON.stringify({
                             questionnaire_complete: true,
                             persona_name: personaName,
+                            ...(Object.keys(bigFive).length ? { bigFive } : {}),
                             duration_seconds: Math.round(duration / 1000),
                             traits,
                             values,
@@ -413,7 +427,7 @@ IMPORTANT: Use AskUserQuestion - do NOT just display this text.`,
 Question ${answeredCount + 1} of ${totalQuestions} (Trait: ${nextQuestion.trait})
 "${thirdPersonQuestion}"
 
-Header: "${getTraitHeader(nextQuestion.trait)}"
+Header: "${nextQuestion.trait ? getTraitHeader(nextQuestion.trait) : nextQuestion.id}"
 
 Options:
 ${nextQuestion.options.map((o, i) => `${i + 1}. "${o.label}" - ${o.description}`).join("\n")}
@@ -486,8 +500,19 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
                         mode: "manual_inference",
                         persona_name,
                         user_description: description,
-                        instruction: `Based on the user's description, infer appropriate trait values (0.0 to 1.0) for each cognitive trait. Use the trait reference matrix below to guide your inference. If the description mentions ANY physical or sensory disability (vision loss, motor impairment, color blindness, hearing loss, tremor, etc.), you MUST also include accessibilityTraits. Without accessibilityTraits, the persona gets cognitive-only modeling and the perceptual transport layer will report near-perfect perception — which is wrong for someone with a disability. Return the traits via persona_create_submit_traits.`,
+                        instruction: `Based on the user's description, infer appropriate trait values (0.0 to 1.0) for each cognitive trait. ALSO estimate the persona's Big Five profile from the same description and return it as bigFive with bigFiveEvidence — see big_five_inference below. This is not optional decoration: without it the persona's values are derived from cognitive traits, and that route cannot reach hedonism, power, universalism or the relatedness need, so those four stay at the 0.5 baseline. Use the trait reference matrix below to guide your inference. If the description mentions ANY disability or impairment — sensory (vision loss, colour blindness, hearing loss), physical (motor impairment, tremor), OR cognitive and attentional (ADHD, dyslexia, autism, brain fog, fatigue, low processing speed) — you MUST also include accessibilityTraits. Cognitive conditions map onto attentionSpan and processingSpeed in that same block; listing only physical and sensory examples led to ADHD personas getting no accessibility modeling at all. Without accessibilityTraits, the persona gets cognitive-only modeling and the perceptual transport layer will report near-perfect perception — which is wrong for someone with a disability. Return the traits via persona_create_submit_traits.`,
                         trait_reference: traitInfo,
+                        big_five_inference: bigFiveInferenceReference(),
+                        // What to look for, per trait, so the caller is not guessing at
+                        // what counts as evidence. The submit tool REJECTS a persona with
+                        // unaccounted traits, so this is the contract rather than advice.
+                        trait_criteria: TRAIT_INFERENCE_CRITERIA,
+                        completeness_contract: {
+                            rule: `All ${ALL_TRAITS.length} traits must be accounted for. Give each one a value inferred from the description, OR list it in unsupportedTraits.`,
+                            why: "An unsupplied trait is filled from a population baseline and the result is indistinguishable from a considered value — the persona looks complete either way. Naming what the description cannot support keeps that visible.",
+                            unsupportedTraits: "string[] — traits this description genuinely does not speak to. A legitimate answer, not a failure.",
+                            enforcement: "persona_create_submit_traits returns an error listing the unaccounted traits and writes nothing.",
+                        },
                         ...(includeTraitReference ? {} : { trait_reference_note: "Compact form: trait names and meanings. For per-level behaviours call persona_traits_list, or pass includeTraitReference:true." }),
                         accessibility_traits_reference: {
                             visionLevel: "0=blind, 0.3=legally blind, 0.5=low vision (needs magnification), 0.7=mild vision loss, 1.0=sighted",
@@ -540,7 +565,23 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
                 hearingLevel: z.number().min(0).max(1).optional().describe("Hearing level: 0=deaf, 1=full hearing"),
             }).optional().describe("Sensory/motor/physical traits for disability modeling. Without these, the persona gets cognitive-only modeling (no vision/motor simulation in empathy_audit)."),
             ageRange: z.string().optional().describe("Age range: '18-24', '25-45', '45-65', '65+'"),
+            discardBigFive: z.boolean().optional().describe("Deliberately drop an existing Big Five profile on this persona and derive values from cognitive traits instead. Without this, an existing profile is carried forward rather than silently downgraded — omitting bigFive on a rewrite used to demote the persona from thirteen value axes to nine and say nothing."),
+            traitProvenance: z.record(z.string(), z.enum(["supported", "asserted"])).optional().describe("Per trait: 'supported' if the description says it, 'asserted' if you decided it anyway. Both are legitimate. Supplying this is what makes the trait count mean something — '26 of 26 supplied' reads as quality whether the values were read out of the description or invented, and without this field nothing can tell those apart."),
+            unsupportedTraits: z.array(z.string()).optional().describe("Traits the description genuinely does not speak to. Required for any trait you are not supplying a value for — see completeness_contract. Naming them is a valid answer; omitting them is not."),
+            bigFive: z.object({
+                openness: z.number().min(0).max(1),
+                conscientiousness: z.number().min(0).max(1),
+                extraversion: z.number().min(0).max(1),
+                agreeableness: z.number().min(0).max(1),
+                neuroticism: z.number().min(0).max(1),
+            }).optional().describe("Big Five profile INFERRED from the description. Unlocks all 13 motivational values through published correlations instead of the 9 the cognitive-trait route reaches. Requires bigFiveEvidence."),
+            bigFiveEvidence: z.array(z.object({
+                factor: z.string(),
+                score: z.number().min(0).max(1),
+                quote: z.string().describe("The words in the description justifying this score"),
+            })).optional().describe("One entry per factor, quoting the description. Required whenever bigFive is supplied — an estimate nobody can check against the source is not evidence."),
         },
+        _meta: { ui: { resourceUri: widgetUri("persona-created") } },
         annotations: {
             title: "Submit Persona Traits",
             readOnlyHint: false,
@@ -548,9 +589,86 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ persona_name, traits, description, accessibilityTraits, ageRange }) => {
+    }, async ({ persona_name, traits, description, accessibilityTraits, ageRange, bigFive, bigFiveEvidence, unsupportedTraits, traitProvenance, discardBigFive }) => {
+        // Refused, not warned.
+        //
+        // A warning is read once by a model already moving to its next call, and
+        // the persona is written regardless -- the gap surfaces months later when
+        // someone audits. Five personas on this install are missing the same four
+        // traits because one session skipped them and nothing objected. Declining
+        // the write is the only version of this that changes what gets stored.
+        const completeness = assessTraitCompleteness(traits, unsupportedTraits, traitProvenance);
+        if (!completeness.ok) {
+            return {
+                content: [{ type: "text", text: JSON.stringify({
+                            error: "incomplete_persona",
+                            message: completeness.message,
+                            unaccountedTraits: completeness.unaccounted,
+                            traitCriteria: Object.fromEntries(completeness.unaccounted.map((t) => [t, TRAIT_INFERENCE_CRITERIA[t]])),
+                            howToProceed: "Re-submit with a value for each trait the description supports, and the rest listed in unsupportedTraits. Nothing was written.",
+                            written: false,
+                        }, null, 2) }],
+            };
+        }
         const builtTraits = buildTraitsFromAnswers(traits);
-        const derivedResult = deriveValuesFromTraits(builtTraits);
+        // Big Five, when the caller inferred one from the description.
+        //
+        // Preferred over the cognitive-trait derivation because it reaches all
+        // thirteen axes through published correlations instead of nine through
+        // our own bridge — but recorded as its OWN route, not merged into stated
+        // Big Five. A model reading prose and five numbers a human supplied are
+        // different evidence, and collapsing them would erase the distinction the
+        // route ordering exists to express. Rejected rather than degraded when it
+        // fails validation: a bad profile silently replacing a working
+        // trait-derivation is worse than no profile. (2026-08-01)
+        let bigFiveAccepted;
+        let bigFiveRejected;
+        let bigFiveUnrelated;
+        if (bigFive) {
+            const verdict = validateInferredBigFive(bigFive, bigFiveEvidence, description);
+            if (verdict.ok) {
+                bigFiveAccepted = bigFive;
+                bigFiveUnrelated = verdict.unrelatedQuotes;
+            }
+            else
+                bigFiveRejected = verdict.reason;
+        }
+        // A rewrite must not silently demote a persona's values route.
+        //
+        // Submitting without bigFive is the honest answer when the description
+        // does not support one -- and on an EXISTING persona that already had a
+        // Big Five profile, it quietly rewrote the record from `big_five` (or
+        // `bigfive_inferred`, thirteen axes) down to `cognitive_traits` (nine
+        // axes, four frozen at baseline). Following the instruction correctly
+        // made the persona worse, and nothing said so. Nobody would notice until
+        // they wondered why four values had gone flat.
+        //
+        // The existing profile is CARRIED FORWARD rather than dropped, because a
+        // downgrade nobody asked for is the worse error -- and it is reported
+        // loudly, with the traits it was inferred from now changed underneath it.
+        // `discardBigFive: true` is the way to actually mean the downgrade.
+        // (2026-08-01)
+        let carriedBigFive;
+        if (!bigFiveAccepted && !discardBigFive) {
+            try {
+                const { loadCustomPersonas } = await import("../personas.js");
+                const prior = loadCustomPersonas()[persona_name];
+                const priorDeriv = prior?.valuesDerivation;
+                const priorMethod = priorDeriv?.method;
+                const priorBigFive = prior?.bigFive;
+                if (priorBigFive && (priorMethod === "big_five" || priorMethod === "bigfive_inferred")) {
+                    bigFiveAccepted = priorBigFive;
+                    carriedBigFive = {
+                        from: priorMethod,
+                        note: `This persona already had a ${priorMethod} profile and this submission supplied none, which would have downgraded it to cognitive_traits — nine of thirteen value axes, with hedonism, power, universalism and the relatedness need frozen at 0.5. The existing profile was kept. It was inferred against the PREVIOUS description and traits, so if the persona has genuinely changed, re-supply bigFive with evidence from the new description. To downgrade on purpose, re-submit with discardBigFive:true.`,
+                    };
+                }
+            }
+            catch { /* no prior persona; nothing to carry */ }
+        }
+        const derivedResult = bigFiveAccepted
+            ? deriveValuesFromBigFive(bigFiveAccepted)
+            : deriveValuesFromTraits(builtTraits);
         // buildTraitsFromAnswers fills every unsupplied trait from research
         // baselines, so a caller who names 3 traits gets back a complete 26-trait
         // persona with no way to tell which 23 were invented. Report both lists.
@@ -564,24 +682,57 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
         const personaObj = createCognitivePersona(persona_name, description || persona_name, builtTraits, { ageRange: ageRange || undefined });
         // Attach accessibility traits — either from explicit parameter or inferred from name/description
         let resolvedAccessibilityTraits = accessibilityTraits;
+        // Which keywords fired, so an inferred number can be argued with rather
+        // than just noticed.
+        let inferredFrom = [];
         if (!resolvedAccessibilityTraits || Object.keys(resolvedAccessibilityTraits).length === 0) {
             // Infer disability traits from persona name and description
             const text = `${persona_name} ${description || ''}`.toLowerCase();
             const hasVision = /vision|blind|magnif|low.?vis|sight|visual.?impair/.test(text);
             const hasMotor = /motor|tremor|parkinson|arthrit|dexterity|mobility/.test(text);
-            const hasCognitive = /adhd|dyslexic|dyslexia|cognitive|autism|intellectual/.test(text);
             const hasHearing = /deaf|hearing|hard.?of.?hearing/.test(text);
             const hasElderly = /elderly|senior|65|70|75|80|retired|aging|aged/.test(text);
+            // Cognitive conditions are NOT one bucket, and treating them as one
+            // produced a wrong number with a confident label. ADHD, dyslexia,
+            // autism and intellectual disability all matched a single regex and all
+            // came out as processingSpeed 0.4 / attentionSpan 0.3 -- so an ADHD
+            // persona whose previous record said processingSpeed 0.9 was rewritten
+            // to 0.4 by a keyword. ADHD is an attention-regulation condition; it is
+            // not a claim about how fast someone processes information, and plenty
+            // of people with ADHD process quickly. Autism is not a speed claim
+            // either. Dyslexia slows READING specifically. Only the conditions that
+            // genuinely bear on speed set speed. (2026-08-01)
+            const hasAdhd = /adhd|add\b|attention deficit|executive function/.test(text);
+            const hasDyslexia = /dyslexi/.test(text);
+            const hasAutism = /autis|asperger|neurodiver/.test(text);
+            const hasSlowProcessing = /intellectual disab|brain fog|processing (speed )?(disorder|difficult|impair)|slow (to )?process|cognitive impair|dementia|traumatic brain/.test(text);
+            const hasCognitive = hasAdhd || hasDyslexia || hasAutism || hasSlowProcessing;
             if (hasVision || hasMotor || hasCognitive || hasHearing || hasElderly) {
+                // Left undefined where the description supports no claim, so the
+                // block below falls back to the persona's own traits rather than to a
+                // number this inference invented.
+                const speed = hasSlowProcessing ? 0.35
+                    : hasDyslexia ? 0.6
+                        : hasElderly ? 0.5
+                            : undefined;
+                const attention = hasAdhd ? 0.3
+                    : hasAutism ? undefined
+                        : undefined;
                 resolvedAccessibilityTraits = {
                     visionLevel: hasVision ? 0.4 : hasElderly ? 0.6 : 1.0,
                     contrastSensitivity: hasVision ? 0.3 : hasElderly ? 0.5 : 1.0,
                     motorControl: hasMotor ? 0.3 : hasElderly ? 0.6 : 1.0,
                     tremor: hasMotor,
-                    processingSpeed: hasCognitive ? 0.4 : hasElderly ? 0.5 : builtTraits.comprehension ?? 0.8,
-                    attentionSpan: hasCognitive ? 0.3 : builtTraits.patience ?? 0.7,
+                    ...(speed !== undefined ? { processingSpeed: speed } : {}),
+                    ...(attention !== undefined ? { attentionSpan: attention } : {}),
                     hearingLevel: hasHearing ? 0.2 : 1.0,
                 };
+                inferredFrom = [
+                    hasVision && "vision", hasMotor && "motor", hasHearing && "hearing", hasElderly && "age",
+                    hasAdhd && "ADHD (attention only — not a processing-speed claim)",
+                    hasDyslexia && "dyslexia (reading speed)", hasAutism && "autism (no speed or attention claim inferred)",
+                    hasSlowProcessing && "processing-speed condition",
+                ].filter(Boolean);
             }
         }
         if (resolvedAccessibilityTraits && Object.keys(resolvedAccessibilityTraits).length > 0) {
@@ -597,9 +748,53 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
                 fatigueSusceptibility: (resolvedAccessibilityTraits.visionLevel ?? 1.0) < 0.7 || (resolvedAccessibilityTraits.motorControl ?? 1.0) < 0.7 ? 0.7 : 0.3,
             };
         }
+        // The route that produced the values, recorded ON the persona so every
+        // reader gets the same answer. bigFive is stored too, so the derivation
+        // can be re-run and checked rather than taken on trust.
+        personaObj.valuesDerivation = bigFiveAccepted
+            ? { method: "bigfive_inferred", squash: "tanh", precision: 3,
+                inferredFrom: "description", evidence: bigFiveEvidence ?? [] }
+            : { method: "cognitive_traits", squash: "tanh", precision: 3 };
+        if (bigFiveAccepted) {
+            personaObj.bigFive = bigFiveAccepted;
+        }
+        personaObj.schwartzValues = derivedResult.values;
+        // Kept ON the persona: which traits are baseline-by-declaration rather
+        // than by omission. Without it the distinction is lost the moment the
+        // response is discarded.
+        if (unsupportedTraits?.length) {
+            personaObj.unsupportedTraits = unsupportedTraits;
+        }
+        // The attention pattern createCognitivePersona stamps from its template is
+        // NOT a declaration.
+        //
+        // A recreate flipped a stored persona from "thorough" to "skim" while still
+        // reporting attentionPatternSource: "declared" -- nobody declared either
+        // value. The template's default arrived through humanBehavior, which is
+        // exactly where a real declaration lives, so the profile could not tell
+        // them apart. Dropping it lets the derivation run and report itself as
+        // derived; a caller who wants a declaration sets it through
+        // persona_update, which is the surface that takes one. (2026-08-01)
+        const hb = personaObj.humanBehavior;
+        if (hb?.attention && "pattern" in hb.attention)
+            delete hb.attention.pattern;
         registerPersonas([personaObj]);
+        // Persist to disk. registerPersonas writes to an in-memory map that dies
+        // with the process, so a creation whose CMS write also failed left the
+        // persona existing NOWHERE -- while the response said registered: true.
+        // "Registered" described RAM and read as "saved". (2026-08-01)
+        let savedToFile;
+        let fileSaveError;
+        try {
+            const { saveCustomPersona } = await import("../personas.js");
+            savedToFile = saveCustomPersona(personaObj);
+        }
+        catch (e) {
+            fileSaveError = e?.message ?? String(e);
+        }
         // Also save to CMS if an API key is configured (makes it persistent across sessions)
         let savedToCms = false;
+        let cmsError;
         try {
             const { getSessionApiKey } = await import("./base/cognitive-tools.js");
             const apiKey = getSessionApiKey();
@@ -618,6 +813,13 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
                         accessibility_traits: resolvedAccessibilityTraits || null,
                         age_range: ageRange || personaObj.demographics?.age_range || null,
                         source: "mcp",
+                        // Sent so the row is not re-labelled by guesswork later. A stored
+                        // block with no provenance reads as `stated`, which would claim a
+                        // human wrote numbers this route inferred.
+                        values_derivation: bigFiveAccepted
+                            ? { method: "bigfive_inferred", squash: "tanh", precision: 3,
+                                inferredFrom: "description", evidence: bigFiveEvidence ?? [] }
+                            : { method: "cognitive_traits", squash: "tanh", precision: 3 },
                     }),
                 });
                 if (res.ok) {
@@ -626,10 +828,20 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
                 }
                 else {
                     const errBody = await res.text().catch(() => "");
+                    // The REASON travels to the caller. "savedToCms: false" alone does
+                    // not distinguish an unreachable CMS from a credential the CMS
+                    // will never accept -- and the second is the actual situation on
+                    // an OAuth connector, where the bearer forwarded here is an OAuth
+                    // token and /api/personas only accepts cbk_ account keys. Those
+                    // need different responses from whoever reads this.
+                    cmsError = res.status === 401 || res.status === 403
+                        ? `CMS rejected the credential (${res.status}). The session bearer is forwarded as-is, so an OAuth connector token reaches an endpoint that only accepts cbk_ account keys. Set an account key with set_api_key to make CMS writes succeed.`
+                        : `CMS returned ${res.status}: ${errBody.slice(0, 120)}`;
                     console.warn(`[persona] CMS save failed (${res.status}): ${errBody.slice(0, 100)}`);
                 }
             }
             else {
+                cmsError = "no API key in this session — nothing was sent to the CMS";
                 console.warn(`[persona] No API key in session — cannot save to CMS`);
             }
         }
@@ -640,13 +852,42 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
             content: [{
                     type: "text",
                     text: JSON.stringify({
-                        success: true,
+                        // success is computed below from what actually persisted.
                         persona_name,
                         description,
                         traits: builtTraits,
                         providedTraits,
                         defaultedTraits,
-                        traitCompleteness: `${providedTraits.length} of ${allTraitNames.length} supplied; ${defaultedTraits.length} filled from research baselines`,
+                        // The old line was `${n} of ${n} supplied; 0 filled from research
+                        // baselines`, and it read as a quality signal no matter how the
+                        // numbers were arrived at -- a caller who invented six of them got
+                        // the same clean sentence as one who read all 26 out of the text.
+                        // The count measures ACCOUNTING. Whether the description supports a
+                        // value is a different question, and the sentence has to stop
+                        // answering it by implication.
+                        traitCompleteness: (() => {
+                            const base = `${providedTraits.length} of ${allTraitNames.length} supplied; ${defaultedTraits.length} filled from research baselines`;
+                            const a = completeness.asserted?.length ?? 0;
+                            const u = completeness.unlabelled?.length ?? 0;
+                            if (a || u) {
+                                const parts = [
+                                    a ? `${a} asserted by the caller rather than read from the description` : "",
+                                    u ? `${u} with no provenance stated` : "",
+                                ].filter(Boolean);
+                                return `${base}. ${parts.join("; ")}. This counts accounting, not support — a supplied value can still be an invention.`;
+                            }
+                            return `${base}; all supplied values marked as supported by the description`;
+                        })(),
+                        ...(completeness.asserted?.length ? { assertedTraits: completeness.asserted } : {}),
+                        ...(completeness.unlabelled?.length ? {
+                            unlabelledTraits: completeness.unlabelled,
+                            provenanceNote: "These were supplied with no traitProvenance entry, so whether the description supports them is unknown — not assumed. Pass traitProvenance to say which values you read out of the text and which you decided.",
+                        } : {}),
+                        ...(carriedBigFive ? { bigFiveCarriedForward: carriedBigFive } : {}),
+                        ...(bigFiveUnrelated?.length ? {
+                            bigFiveQuotesUnrelated: bigFiveUnrelated,
+                            bigFiveQuoteNote: "These quotes are in the description but contain no word bearing on the factor they were cited for. The profile was accepted — the check is a heuristic — but a quote that is not about the factor is not evidence for it.",
+                        } : {}),
                         // A misspelled trait name was previously accepted in silence and had
                         // no effect, since buildTraitsFromAnswers only applies keys already
                         // present in the trait table.
@@ -655,15 +896,117 @@ Phase: VALUES (${session.currentIndex + 1} of ${session.valueQuestions.length})`
                             warning: `Ignored ${unknownTraits.length} unrecognized trait name(s): ${unknownTraits.join(", ")}. These had no effect.`,
                         } : {}),
                         values: derivedResult.values,
-                        derivations: derivedResult.derivations,
+                        // The two routes report their working differently -- the trait
+                        // derivation lists `derivations`, the Big Five one `contributions`.
+                        // Both are surfaced under their own name so a caller can tell which
+                        // route ran from the response alone, without inferring it from
+                        // which key happens to be present.
+                        ...("derivations" in derivedResult
+                            ? { derivations: derivedResult.derivations }
+                            : {}),
+                        ...("contributions" in derivedResult
+                            ? { bigFiveContributions: derivedResult.contributions,
+                                hypothesisAxes: derivedResult.hypothesisAxes }
+                            : {}),
+                        valuesRoute: bigFiveAccepted ? "bigfive_inferred" : "cognitive_traits",
+                        traitSummary: summariseTraits(builtTraits),
+                        // Named at creation, which is the only moment the distinction is
+                        // free: a declared-unsupported trait sits at a population baseline
+                        // and is indistinguishable from a considered value in every later
+                        // view of this persona.
+                        ...(unsupportedTraits?.length ? {
+                            unsupportedTraits,
+                            unsupportedDetail: unsupportedTraits.map((t) => ({
+                                trait: t, value: builtTraits[t],
+                                source: "population baseline — the description did not speak to this",
+                            })),
+                        } : {}),
+                        ...(bigFiveAccepted ? { bigFive: bigFiveAccepted, bigFiveEvidence: bigFiveEvidence ?? [] } : {}),
+                        // A rejected profile is REPORTED, never swallowed. Silently falling
+                        // back would leave the caller believing the Big Five route ran.
+                        ...(bigFiveRejected ? {
+                            bigFiveRejected,
+                            bigFiveRejectedNote: "The inferred profile was not stored and values were derived from cognitive traits instead, which cannot reach hedonism, power, universalism or the relatedness need. Fix the profile and resubmit to reach all thirteen.",
+                        } : {}),
                         accessibilityTraits: resolvedAccessibilityTraits || null,
-                        hasDisabilityModeling: !!(resolvedAccessibilityTraits && Object.keys(resolvedAccessibilityTraits).length > 0),
+                        // Presence of the block is not impairment. A persona with vision,
+                        // motor and hearing all at 1.0 has accessibility traits and no
+                        // disability, and flagging it flipped an instruction claiming the
+                        // perceptual layer "will simulate sensory impairment" -- a false
+                        // statement about what the run does. ADHD is cognitive; supplying
+                        // ceiling sensory values must not read as a sensory disability.
+                        hasDisabilityModeling: (() => {
+                            const a = resolvedAccessibilityTraits;
+                            if (!a)
+                                return false;
+                            const below = (k, t = 0.95) => typeof a[k] === "number" && a[k] < t;
+                            return below("visionLevel") || below("motorControl") || below("hearingLevel")
+                                || below("contrastSensitivity") || below("processingSpeed", 0.6)
+                                || below("attentionSpan", 0.6) || a.tremor === true || !!a.colorBlindness;
+                        })(),
                         disabilityTraitsSource: accessibilityTraits ? 'explicit' : resolvedAccessibilityTraits ? 'inferred_from_description' : 'none',
+                        ...(inferredFrom.length ? {
+                            disabilityInferredFrom: inferredFrom,
+                            disabilityInferenceNote: "Keyword inference, not a diagnosis. It sets a trait only where the condition bears on it — a condition named in the description does not license a number for every accessibility trait. Pass accessibilityTraits explicitly to override any of it.",
+                        } : {}),
                         ageRange: ageRange || personaObj.demographics?.age_range || null,
                         registered: true,
+                        // Both stores named, and whether the persona SURVIVES stated
+                        // outright. savedToCms alone read as a minor caveat when combined
+                        // with registered:true it meant the persona was in RAM and nowhere
+                        // else.
                         savedToCms,
+                        savedToFile: savedToFile ? true : false,
+                        ...(savedToFile ? { filePath: savedToFile } : {}),
+                        ...(fileSaveError ? { fileSaveError } : {}),
+                        // Agentic callers branch on success. A partial write that reports
+                        // success is a write nobody retries, which is how the two stores
+                        // drift apart in the first place -- so a half-completed write is
+                        // reported as a failure with the half that landed named, rather
+                        // than as a success with a caveat.
+                        success: !!savedToFile && savedToCms,
+                        ...(savedToFile && !savedToCms ? { partialWrite: true } : {}),
+                        writeStatus: { fileStore: savedToFile ? "ok" : "failed", cms: savedToCms ? "ok" : "failed" },
+                        ...(cmsError ? { cmsError } : {}),
+                        persisted: !!savedToFile || savedToCms,
+                        persistenceNote: savedToFile && savedToCms
+                            ? "Written to the file store and the CMS."
+                            : savedToFile
+                                ? "Written to the file store. The CMS copy was NOT written, so the two stores disagree — the persona survives restarts but will not appear for other clients of the CMS."
+                                : savedToCms
+                                    ? "Written to the CMS only. The file store did NOT take it, so tools reading the file store will not find this persona."
+                                    : "NOT PERSISTED. The persona exists only in this server process's memory and will be gone when it restarts. `registered: true` above means RAM, not storage.",
                         instruction: resolvedAccessibilityTraits
-                            ? `Persona "${persona_name}" created with disability modeling (vision=${resolvedAccessibilityTraits.visionLevel ?? 'default'}, motor=${resolvedAccessibilityTraits.motorControl ?? 'default'}). The perceptual transport layer will simulate sensory impairment. Use with empathy_audit for accurate disability scoring.`
+                            // Names the modalities actually impaired instead of claiming
+                            // "sensory impairment" wholesale. An ADHD persona with vision,
+                            // motor and hearing at 1.0 and a short attention span has
+                            // something real to model -- but nothing SENSORY, and the old
+                            // text promised a simulation that would not happen. A claim about
+                            // what a run will do has to match what the numbers support.
+                            ? (() => {
+                                const a = resolvedAccessibilityTraits;
+                                const impaired = [];
+                                const lo = (k, label, t = 0.95) => {
+                                    if (typeof a[k] === "number" && a[k] < t)
+                                        impaired.push(`${label} ${a[k]}`);
+                                };
+                                lo("visionLevel", "vision");
+                                lo("contrastSensitivity", "contrast");
+                                lo("motorControl", "motor");
+                                lo("hearingLevel", "hearing");
+                                lo("processingSpeed", "processing speed", 0.6);
+                                lo("attentionSpan", "attention span", 0.6);
+                                if (a.tremor === true)
+                                    impaired.push("tremor");
+                                if (a.colorBlindness)
+                                    impaired.push(`colour vision (${String(a.colorBlindness)})`);
+                                const sensory = impaired.some((x) => /^(vision|contrast|hearing|colour)/.test(x));
+                                return `Persona "${persona_name}" created with accessibility modeling on: ${impaired.join(", ")}. `
+                                    + (sensory
+                                        ? "The perceptual transport layer will simulate the sensory limits above. "
+                                        : "No SENSORY channel is impaired, so perception is simulated as intact; the limits above are cognitive and motor. ")
+                                    + "Use with empathy_audit for disability scoring.`".slice(0, -1);
+                            })()
                             : `Persona "${persona_name}" created with cognitive-only modeling. For disability-specific scoring (vision impairment, motor difficulty, etc.), recreate with accessibilityTraits parameter.`,
                         usage_example: {
                             tool: "empathy_audit",