@phren/cli 0.0.3 → 0.0.5

package/mcp/dist/cli-search.js

@@ -16,7 +16,7 @@ const SEARCH_TYPES = new Set([
     "task",
     "changelog",
     "canonical",
-    "memory-queue",
+    "review-queue",
     "skill",
     "other",
 ]);
@@ -45,7 +45,7 @@ function printSearchUsage() {
     console.error("  phren search --project <name> [--type <type>] [--limit <n>] [--all]");
     console.error("  phren search --history                    Show recent searches");
     console.error("  phren search --from-history <n>           Re-run search #n from history");
-    console.error("  type: claude|summary|findings|reference|task|changelog|canonical|memory-queue|skill|other");
+    console.error("  type: claude|summary|findings|reference|task|changelog|canonical|review-queue|skill|other");
 }
 function validateAndNormalizeSearchOptions(phrenPath, queryParts, project, type, limit, showHistory, fromHistory, searchAll) {
     if (showHistory) {

package/mcp/dist/content-citation.js

@@ -1,9 +1,11 @@
 import * as fs from "fs";
+import { statSync } from "fs";
 import * as path from "path";
 import { debugLog, EXEC_TIMEOUT_MS, EXEC_TIMEOUT_QUICK_MS } from "./shared.js";
 import { errorMessage, runGitOrThrow } from "./utils.js";
 import { findingIdFromLine } from "./finding-impact.js";
 import { METADATA_REGEX, isArchiveStart, isArchiveEnd } from "./content-metadata.js";
+import { FINDING_TYPE_DECAY, extractFindingType } from "./finding-lifecycle.js";
 export const FINDING_PROVENANCE_SOURCES = [
     "human",
     "agent",
@@ -270,6 +272,16 @@ function confidenceForAge(ageDays, decay) {
         return d90 - ((d90 - d120) * ((ageDays - 90) / 30));
     return d120; // don't decay further past d120; TTL handles final expiry
 }
+function wasFileModifiedAfter(filePath, findingDate) {
+    try {
+        const stat = statSync(filePath);
+        const fileModified = stat.mtime.toISOString().slice(0, 10);
+        return fileModified > findingDate;
+    }
+    catch {
+        return false; // File doesn't exist or can't stat — handled by citation validation
+    }
+}
 export function filterTrustedFindings(content, ttlDays) {
     return filterTrustedFindingsDetailed(content, { ttlDays }).content;
 }
@@ -356,11 +368,41 @@ export function filterTrustedFindingsDetailed(content, opts) {
         else {
             confidence = DEFAULT_UNDATED_CONFIDENCE;
         }
+        // Type-specific decay adjustment
+        const findingType = extractFindingType(line);
+        if (findingType) {
+            const typeConfig = FINDING_TYPE_DECAY[findingType];
+            if (typeConfig) {
+                // Override max age for this type
+                if (effectiveDate && typeConfig.maxAgeDays !== Infinity) {
+                    const age = ageDaysForDate(effectiveDate);
+                    if (age !== null && age > typeConfig.maxAgeDays) {
+                        issues.push({ date: effectiveDate || "unknown", bullet: line, reason: "stale" });
+                        if (citation)
+                            i++;
+                        continue;
+                    }
+                }
+                // Apply type-specific decay multiplier
+                confidence *= typeConfig.decayMultiplier;
+                // Decisions and anti-patterns get a floor boost (never drop below 0.6)
+                if (typeConfig.maxAgeDays === Infinity) {
+                    confidence = Math.max(confidence, 0.6);
+                }
+            }
+        }
         if (citation && !validateFindingCitation(citation)) {
             issues.push({ date: effectiveDate || "unknown", bullet: line, reason: "invalid_citation" });
             i++;
             continue;
         }
+        // If cited file was modified after finding was created, lower confidence
+        if (citation && effectiveDate && citation.file) {
+            const fileModifiedAfterFinding = wasFileModifiedAfter(citation.file, effectiveDate);
+            if (fileModifiedAfterFinding) {
+                confidence *= 0.7; // File changed since finding was written — may be stale
+            }
+        }
         if (!citation)
             confidence *= 0.8;
         const provenance = parseSourceComment(line)?.source ?? "unknown";

package/mcp/dist/content-dedup.js

@@ -187,7 +187,7 @@ export function jaccardSimilarity(a, b) {
 const PROSE_ENTITY_RE = UNIVERSAL_TECH_TERMS_RE;
 const POSITIVE_RE = /\b(always|prefer|should|must|works|recommend|enable)\b/i;
 const NEGATIVE_RE = /\b(never|avoid|don't|do not|shouldn't|must not|broken|deprecated|disable)\b/i;
-// ── Dynamic entity extraction ─────────────────────────────────────────────────
+// ── Dynamic fragment extraction ────────────────────────────────────────────────
 const ENTITY_CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
 // Patterns that suggest a token is a proper noun / tool name:
 //   - CamelCase word (at least one interior uppercase): PhotonMappingEngine, GameKit
@@ -257,7 +257,7 @@ function extractProseEntities(text, dynamicEntities) {
     let m;
     while ((m = re.exec(text)) !== null)
         found.add(m[0].toLowerCase());
-    // Match additional entity patterns (versions, env keys, file paths, error codes, dates)
+    // Match additional fragment patterns (versions, env keys, file paths, error codes, dates)
     for (const { re: pattern } of EXTRA_ENTITY_PATTERNS) {
         const pRe = new RegExp(pattern.source, pattern.flags);
         let pm;
@@ -265,7 +265,7 @@ function extractProseEntities(text, dynamicEntities) {
             found.add(pm[0].toLowerCase());
     }
     if (dynamicEntities) {
-        // Also check whether any dynamic entity appears (case-insensitive word match)
+        // Also check whether any dynamic fragment appears (case-insensitive word match)
         for (const entity of dynamicEntities) {
             const escaped = entity.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
             if (new RegExp(`\\b${escaped}\\b`, "i").test(text)) {

package/mcp/dist/content-learning.js

@@ -204,20 +204,20 @@ export function upsertCanonical(phrenPath, project, memory) {
     const resolvedDir = safeProjectPath(phrenPath, project);
     if (!resolvedDir || !fs.existsSync(resolvedDir))
         return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
-    const canonicalPath = path.join(resolvedDir, "CANONICAL_MEMORIES.md");
+    const canonicalPath = path.join(resolvedDir, "truths.md");
     const today = new Date().toISOString().slice(0, 10);
     const bullet = memory.startsWith("- ") ? memory : `- ${memory}`;
     withFileLock(canonicalPath, () => {
         if (!fs.existsSync(canonicalPath)) {
-            fs.writeFileSync(canonicalPath, `# ${project} Canonical Memories\n\n## Pinned\n\n${bullet} _(pinned ${today})_\n`);
+            fs.writeFileSync(canonicalPath, `# ${project} Truths\n\n## Truths\n\n${bullet} _(added ${today})_\n`);
         }
         else {
             const existing = fs.readFileSync(canonicalPath, "utf8");
-            const line = `${bullet} _(pinned ${today})_`;
+            const line = `${bullet} _(added ${today})_`;
             if (!existing.includes(bullet)) {
-                const updated = existing.includes("## Pinned")
-                    ? existing.replace("## Pinned", `## Pinned\n\n${line}`)
-                    : `${existing.trimEnd()}\n\n## Pinned\n\n${line}\n`;
+                const updated = existing.includes("## Truths")
+                    ? existing.replace("## Truths", `## Truths\n\n${line}`)
+                    : `${existing.trimEnd()}\n\n## Truths\n\n${line}\n`;
                 const content = updated.endsWith("\n") ? updated : updated + "\n";
                 const tmpPath = canonicalPath + `.tmp-${crypto.randomUUID()}`;
                 fs.writeFileSync(tmpPath, content);
@@ -226,7 +226,7 @@ export function upsertCanonical(phrenPath, project, memory) {
         }
     });
     appendAuditLog(phrenPath, "pin_memory", `project=${project} memory=${JSON.stringify(memory)}`);
-    return phrenOk(`Pinned canonical memory in ${project}.`);
+    return phrenOk(`Truth saved in ${project}.`);
 }
 export function addFindingToFile(phrenPath, project, learning, citationInput, opts) {
     const findingError = validateFinding(learning);

package/mcp/dist/entrypoint.js

@@ -31,7 +31,7 @@ Usage:
   phren search <query> [--project <n>] [--type <t>] [--limit <n>]
                                          Search what phren remembers
   phren add-finding <project> "..."     Tell phren what you learned
-  phren pin <project> "..."             Pin a canonical memory
+  phren pin <project> "..."             Save a truth
   phren tasks                           Cross-project task view
   phren skill-list                      List installed skills
   phren doctor [--fix] [--check-data] [--agents]

package/mcp/dist/finding-lifecycle.js

@@ -6,6 +6,24 @@ const LIFECYCLE_PREFIX = "phren";
 import { withFileLock } from "./governance-locks.js";
 import { isValidProjectName, safeProjectPath } from "./utils.js";
 import { parseCreatedDate as parseCreatedDateMeta, parseStatusField, parseStatus, parseSupersession, parseContradiction, parseFindingId as parseFindingIdMeta, stripLifecycleMetadata, stripRelationMetadata, } from "./content-metadata.js";
+export const FINDING_TYPE_DECAY = {
+    'pattern': { maxAgeDays: 365, decayMultiplier: 1.0 }, // Slow decay, long-lived
+    'decision': { maxAgeDays: Infinity, decayMultiplier: 1.0 }, // Never decays
+    'pitfall': { maxAgeDays: 365, decayMultiplier: 1.0 }, // Slow decay
+    'anti-pattern': { maxAgeDays: Infinity, decayMultiplier: 1.0 }, // Never decays
+    'observation': { maxAgeDays: 14, decayMultiplier: 0.7 }, // Fast decay, short-lived
+    'workaround': { maxAgeDays: 60, decayMultiplier: 0.85 }, // Medium decay
+    'bug': { maxAgeDays: 30, decayMultiplier: 0.8 }, // Medium-fast decay
+    'tooling': { maxAgeDays: 180, decayMultiplier: 0.95 }, // Medium-slow decay
+    'context': { maxAgeDays: 30, decayMultiplier: 0.75 }, // Fast decay (contextual facts)
+};
+export function extractFindingType(line) {
+    const match = line.match(/\[(\w[\w-]*)\]/);
+    if (!match)
+        return null;
+    const tag = match[1].toLowerCase();
+    return tag in FINDING_TYPE_DECAY ? tag : null;
+}
 export const FINDING_LIFECYCLE_STATUSES = [
     "active",
     "superseded",

package/mcp/dist/governance-policy.js

@@ -387,7 +387,7 @@ export function appendReviewQueue(phrenPath, project, section, entries) {
     const resolvedDir = safeProjectPath(phrenPath, project);
     if (!resolvedDir || !fs.existsSync(resolvedDir))
         return phrenErr(`Project "${project}" not found in phren.`, PhrenError.PROJECT_NOT_FOUND);
-    const queuePath = path.join(resolvedDir, "MEMORY_QUEUE.md");
+    const queuePath = path.join(resolvedDir, "review.md");
     const today = new Date().toISOString().slice(0, 10);
     const normalized = [];
     for (const entry of entries) {

package/mcp/dist/governance-scores.js

@@ -270,7 +270,7 @@ export function recordInjection(phrenPath, key, sessionId) {
         debugLog(`Usage log rotation failed: ${errorMessage(err)}`);
     }
 }
-export function recordFeedback(phrenPath, key, feedback) {
+export function recordFeedback(phrenPath, key, feedback, sessionId) {
     const delta = {};
     if (feedback === "helpful")
         delta.helpful = 1;
@@ -280,6 +280,14 @@ export function recordFeedback(phrenPath, key, feedback) {
         delta.regressionPenalty = 1;
     appendScoreJournal(phrenPath, key, delta);
     appendAuditLog(phrenPath, "memory_feedback", `key=${key} feedback=${feedback}`);
+    // When feedback is "helpful", mark correlated query entries for future boost
+    if (feedback === "helpful" && sessionId) {
+        import("./query-correlation.js").then(({ markCorrelationsHelpful: markHelpful }) => {
+            const colonIdx = key.indexOf(":");
+            const docKey = colonIdx >= 0 ? key.slice(0, colonIdx) : key;
+            markHelpful(phrenPath, sessionId, docKey);
+        }).catch(() => { });
+    }
 }
 // Module-level cache for the journal aggregation used by getQualityMultiplier.
 // Invalidated whenever flushEntryScores runs (at which point the journal is cleared).

package/mcp/dist/link-checksums.js

@@ -34,7 +34,7 @@ export function updateFileChecksums(phrenPath, profileName) {
     const tracked = [];
     const dirs = getProjectDirs(phrenPath, profileName);
     for (const dir of dirs) {
-        for (const name of ["FINDINGS.md", ...TASK_FILE_ALIASES, "CANONICAL_MEMORIES.md"]) {
+        for (const name of ["FINDINGS.md", ...TASK_FILE_ALIASES, "truths.md"]) {
             const full = path.join(dir, name);
             if (!fs.existsSync(full))
                 continue;

package/mcp/dist/link-doctor.js

@@ -533,7 +533,7 @@ export async function runDoctor(phrenPath, fix = false, checkData = false) {
             const projectName = path.basename(projectDir);
             if (projectName === "global")
                 continue;
-            for (const mdFile of ["FINDINGS.md", ...TASK_FILE_ALIASES, "MEMORY_QUEUE.md", "CLAUDE.md", "REFERENCE.md"]) {
+            for (const mdFile of ["FINDINGS.md", ...TASK_FILE_ALIASES, "review.md", "CLAUDE.md", "REFERENCE.md"]) {
                 const filePath = path.join(projectDir, mdFile);
                 if (!fs.existsSync(filePath))
                     continue;

package/mcp/dist/mcp-memory.js

@@ -10,10 +10,10 @@ export function register(server, ctx) {
     const { phrenPath, withWriteQueue, updateFileInIndex } = ctx;
     server.registerTool("pin_memory", {
         title: "◆ phren · pin memory",
-        description: "Promote an important memory into CANONICAL_MEMORIES.md so retrieval prioritizes it.",
+        description: "Write a truth — a high-confidence, always-inject entry in truths.md that never decays.",
         inputSchema: z.object({
             project: z.string().describe("Project name."),
-            memory: z.string().describe("Canonical memory text to pin."),
+            memory: z.string().describe("Truth text."),
         }),
     }, async ({ project, memory }) => {
         if (!isValidProjectName(project))
@@ -22,8 +22,8 @@ export function register(server, ctx) {
             const result = upsertCanonical(phrenPath, project, memory);
             if (!result.ok)
                 return mcpResponse({ ok: false, error: result.error });
-            // Update FTS index so newly pinned memory is immediately searchable
-            const canonicalPath = path.join(phrenPath, project, "CANONICAL_MEMORIES.md");
+            // Update FTS index so newly added truth is immediately searchable
+            const canonicalPath = path.join(phrenPath, project, "truths.md");
             updateFileInIndex(canonicalPath);
             return mcpResponse({ ok: true, message: result.data, data: { project, memory } });
         });

package/mcp/dist/mcp-ops.js

@@ -294,7 +294,7 @@ export function register(server, ctx) {
     // ── get_review_queue ─────────────────────────────────────────────────────
     server.registerTool("get_review_queue", {
         title: "◆ phren · get review queue",
-        description: "List all items in a project's memory review queue (MEMORY_QUEUE.md), or across all projects when omitted. " +
+        description: "List all items in a project's review queue (review.md), or across all projects when omitted. " +
             "Returns items with their id, section (Review/Stale/Conflicts), date, text, confidence, and risky flag.",
         inputSchema: z.object({
             project: z.string().optional().describe("Project name. Omit to read the review queue across all projects in the active profile."),

package/mcp/dist/memory-ui-data.js

@@ -264,7 +264,7 @@ export async function buildGraph(phrenPath, profile, focusProject) {
     catch {
         // task loading failed — continue with other data sources
     }
-    // ── Fragments (entity graph) ───────────────────────────────────────
+    // ── Fragments (fragment graph) ──────────────────────────────────────
     let db = null;
     try {
         db = await buildIndex(phrenPath, profile);
@@ -326,7 +326,7 @@ export async function buildGraph(phrenPath, profile, focusProject) {
                     entityType: type,
                     refDocs: refs,
                 });
-                // Link entity to each project it appears in
+                // Link fragment to each project it appears in
                 const linkedProjects = new Set();
                 for (const ref of refs) {
                     if (ref.project && projectSet.has(ref.project))
@@ -339,7 +339,7 @@ export async function buildGraph(phrenPath, profile, focusProject) {
         }
     }
     catch {
-        // entity loading failed — continue with other data sources
+        // fragment loading failed — continue with other data sources
     }
     finally {
         if (db) {

package/mcp/dist/phren-art.js

@@ -1,8 +1,12 @@
 /**
- * Phren character ASCII/Unicode art and spinner for CLI presence.
+ * Phren character ASCII/Unicode art, animation engine, and spinner for CLI presence.
  *
  * Based on the pixel art: purple 8-bit brain with diamond eyes,
  * smile, little legs, and cyan sparkle.
+ *
+ * Animation system provides lifelike movement through composable effects:
+ * bob, blink, sparkle, and lean — all driven by setTimeout with randomized
+ * intervals for organic timing.
  */
 const ESC = "\x1b[";
 const RESET = `${ESC}0m`;
@@ -14,6 +18,7 @@ const DARK_PURPLE = `${ESC}38;5;57m`; // deep purple — shadow/outline
 const LIGHT_PURPLE = `${ESC}38;5;141m`; // lavender — brain highlights
 const MID_PURPLE = `${ESC}38;5;98m`; // mid tone
 const NAVY = `${ESC}38;5;18m`; // darkest outline
+// ── Art constants (24px wide, truecolor half-blocks) ─────────────────────────
 /**
  * Phren truecolor art (24px wide, generated from phren-transparent.png).
  * Uses half-block ▀ with RGB foreground+background for pixel-faithful rendering.
@@ -33,6 +38,268 @@ export const PHREN_ART = [
     "                        ",
     "                        ",
 ];
+/** The art width in visible columns */
+const ART_WIDTH = 24;
+// ── Sparkle row: the cyan pixels at row 2 ────────────────────────────────────
+// Sparkle uses ▄ half-blocks with cyan truecolor. For animation we cycle through
+// decorative unicode characters at different brightness levels.
+const SPARKLE_ROW = 2;
+const SPARKLE_CHARS = ["\u2726", "\u2727", "\u2736", " "]; // ✦ ✧ ✶ (dim/blank)
+// ── Eye detection: dark navy pixels in row 6 (fg R<30, G<45, B<120) ──────────
+// Row 6 has two eye pixels at segments 1 and 5 (visual positions 7 and 11).
+// When blinking, we replace their dark fg color with the surrounding body purple.
+const EYE_ROW = 6;
+// Dark-pixel fg threshold
+const EYE_R_MAX = 30;
+const EYE_G_MAX = 45;
+const EYE_B_MAX = 120;
+// Body-purple color to use when "closing" eyes (average of surrounding pixels)
+const BLINK_COLOR = "146;130;250";
+/**
+ * Flip a single art line horizontally. Reverses the order of colored pixel
+ * segments and swaps leading/trailing whitespace so the character faces right.
+ * Half-block characters (▀ ▄) are horizontally symmetric so no char swap needed.
+ */
+function flipLine(line) {
+    const stripped = line.replace(/\x1b\[[^m]*m/g, "");
+    const leadSpaces = stripped.match(/^( *)/)[1].length;
+    const trailSpaces = stripped.match(/( *)$/)[1].length;
+    // Parse pixel segments: each is one or two ANSI color codes followed by a block char.
+    // We strip any leading reset (\x1b[0m) from captured codes — it's an artifact from
+    // the original per-pixel reset pattern and will be re-added during reassembly.
+    const pixels = [];
+    const pixelRegex = /((?:\x1b\[[^m]*m)+)([\u2580\u2584])/g;
+    let match;
+    while ((match = pixelRegex.exec(line)) !== null) {
+        const codes = match[1].replace(/\x1b\[0m/g, "");
+        if (codes)
+            pixels.push({ codes, char: match[2] });
+    }
+    if (pixels.length === 0)
+        return line; // blank or space-only line
+    const reversed = [...pixels].reverse();
+    const newLead = " ".repeat(trailSpaces);
+    const newTrail = " ".repeat(leadSpaces);
+    let result = newLead;
+    for (const px of reversed) {
+        result += px.codes + px.char + "\x1b[0m";
+    }
+    result += newTrail;
+    return result;
+}
+/**
+ * Generate horizontally flipped art (facing right).
+ */
+function generateFlippedArt(art) {
+    return art.map(flipLine);
+}
+/** Pre-computed right-facing art */
+export const PHREN_ART_RIGHT = generateFlippedArt(PHREN_ART);
+/** Random integer in [min, max] inclusive */
+function randInt(min, max) {
+    return Math.floor(Math.random() * (max - min + 1)) + min;
+}
+/**
+ * Replace eye pixels on a single line with the blink color.
+ * Eye pixels are identified by their dark navy fg color (R<30, G<45, B<120).
+ * We replace the fg color code while preserving the bg code and character.
+ */
+function applyBlinkToLine(line) {
+    // Match ANSI color sequences: each pixel is \e[38;2;R;G;Bm (optionally with \e[48;2;...m) then a block char
+    // We scan for fg codes that match the eye threshold and replace them with the blink color
+    return line.replace(/\x1b\[38;2;(\d+);(\d+);(\d+)m/g, (full, rStr, gStr, bStr) => {
+        const r = Number(rStr);
+        const g = Number(gStr);
+        const b = Number(bStr);
+        if (r < EYE_R_MAX && g < EYE_G_MAX && b < EYE_B_MAX) {
+            return `\x1b[38;2;${BLINK_COLOR}m`;
+        }
+        return full;
+    });
+}
+/**
+ * Replace the sparkle pixels on the sparkle row with the current sparkle character.
+ * The sparkle row has two cyan ▄ half-blocks. During sparkle animation we replace
+ * them with decorative Unicode characters from SPARKLE_CHARS.
+ */
+function applySparkleToLine(line, frame, active) {
+    if (!active)
+        return line;
+    const sparkleChar = SPARKLE_CHARS[frame % SPARKLE_CHARS.length];
+    if (sparkleChar === " ") {
+        // Dim: replace the cyan-colored segments with spaces (they disappear)
+        return line.replace(/\x1b\[38;2;\d+;2\d\d;2\d\dm[\u2580\u2584]\x1b\[0m/g, " ");
+    }
+    // Replace the half-block characters with the sparkle unicode char, keeping the cyan color
+    return line.replace(/(\x1b\[38;2;\d+;2\d\d;2\d\dm)[\u2580\u2584](\x1b\[0m)/g, `$1${sparkleChar}$2`);
+}
+/**
+ * Apply lean (horizontal shift) to a line.
+ * Positive offset = shift right (prepend spaces, trim from end).
+ * Negative offset = shift left (trim from start, append spaces).
+ */
+function applyLean(line, offset) {
+    if (offset === 0)
+        return line;
+    if (offset > 0) {
+        // Shift right: prepend spaces
+        return " ".repeat(offset) + line;
+    }
+    // Shift left: remove leading spaces (up to |offset|)
+    const trimCount = Math.min(-offset, line.match(/^( *)/)[1].length);
+    return line.slice(trimCount);
+}
+/**
+ * Create an animated phren character controller.
+ *
+ * @param options.facing - 'left' (default, original) or 'right' (flipped)
+ * @param options.size - art width; unused but reserved for future scaling (default 24)
+ */
+export function createPhrenAnimator(options) {
+    const facing = options?.facing ?? "left";
+    const baseArt = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
+    const state = {
+        bobUp: false,
+        isBlinking: false,
+        sparkleFrame: 0,
+        sparkleActive: false,
+        leanOffset: 0,
+    };
+    const timers = [];
+    function scheduleTimer(fn, ms) {
+        const t = setTimeout(fn, ms);
+        timers.push(t);
+    }
+    // ── Bob animation: toggles bobUp every ~500ms ──────────────────────────
+    function scheduleBob() {
+        scheduleTimer(() => {
+            state.bobUp = !state.bobUp;
+            scheduleBob();
+        }, 500);
+    }
+    // ── Blink animation: eyes close for 150ms, random 2-8s intervals ──────
+    function scheduleBlink() {
+        const interval = randInt(2000, 8000);
+        scheduleTimer(() => {
+            // Perform blink
+            state.isBlinking = true;
+            scheduleTimer(() => {
+                state.isBlinking = false;
+                // 30% chance of double-blink
+                if (Math.random() < 0.3) {
+                    scheduleTimer(() => {
+                        state.isBlinking = true;
+                        scheduleTimer(() => {
+                            state.isBlinking = false;
+                            scheduleBlink();
+                        }, 150);
+                    }, 200);
+                }
+                else {
+                    scheduleBlink();
+                }
+            }, 150);
+        }, interval);
+    }
+    // ── Sparkle animation: fast cycle during bursts, long pauses between ───
+    function scheduleSparkle() {
+        // Wait 1-5 seconds before next sparkle burst
+        const pause = randInt(1000, 5000);
+        scheduleTimer(() => {
+            state.sparkleActive = true;
+            state.sparkleFrame = 0;
+            sparkleStep(0);
+        }, pause);
+    }
+    function sparkleStep(step) {
+        if (step >= SPARKLE_CHARS.length) {
+            // Burst complete
+            state.sparkleActive = false;
+            scheduleSparkle();
+            return;
+        }
+        state.sparkleFrame = step;
+        scheduleTimer(() => {
+            sparkleStep(step + 1);
+        }, 200);
+    }
+    // ── Lean animation: shift 1 col left or right every 4-10s, hold 1-2s ──
+    function scheduleLean() {
+        const interval = randInt(4000, 10000);
+        scheduleTimer(() => {
+            const direction = Math.random() < 0.5 ? -1 : 1;
+            state.leanOffset = direction;
+            const holdTime = randInt(1000, 2000);
+            scheduleTimer(() => {
+                state.leanOffset = 0;
+                scheduleLean();
+            }, holdTime);
+        }, interval);
+    }
+    return {
+        getFrame() {
+            let lines = baseArt.map((line, i) => {
+                let result = line;
+                // Apply blink to the eye row
+                if (state.isBlinking && i === EYE_ROW) {
+                    result = applyBlinkToLine(result);
+                }
+                // Apply sparkle to sparkle row
+                if (i === SPARKLE_ROW) {
+                    result = applySparkleToLine(result, state.sparkleFrame, state.sparkleActive);
+                }
+                // Apply lean
+                result = applyLean(result, state.leanOffset);
+                return result;
+            });
+            // Apply bob: when bobUp, prepend a blank line (shift everything down visually)
+            if (state.bobUp) {
+                lines = ["", ...lines.slice(0, -1)];
+            }
+            return lines;
+        },
+        start() {
+            scheduleBob();
+            scheduleBlink();
+            scheduleSparkle();
+            scheduleLean();
+        },
+        stop() {
+            for (const t of timers) {
+                clearTimeout(t);
+            }
+            timers.length = 0;
+        },
+    };
+}
+// ── Startup frames (pre-baked, no timers) ────────────────────────────────────
+/**
+ * Returns 4 pre-baked animation frames for shell startup display.
+ * No timers needed — the caller cycles through them manually.
+ *
+ * Frames: [neutral, bob-up, neutral, bob-down(sparkle)]
+ *
+ * @param facing - 'left' (default) or 'right'
+ */
+export function getPhrenStartupFrames(facing) {
+    const art = facing === "right" ? PHREN_ART_RIGHT : PHREN_ART;
+    // Frame 0: neutral
+    const frame0 = [...art];
+    // Frame 1: bob up (prepend blank line, drop last line)
+    const frame1 = ["", ...art.slice(0, -1)];
+    // Frame 2: neutral (same as frame 0)
+    const frame2 = [...art];
+    // Frame 3: bob down with sparkle burst — shift down by removing first line, append blank
+    const frame3WithSparkle = art.map((line, i) => {
+        if (i === SPARKLE_ROW) {
+            return applySparkleToLine(line, 0, true); // ✦ sparkle
+        }
+        return line;
+    });
+    const frame3 = [...frame3WithSparkle.slice(1), ""];
+    return [frame0, frame1, frame2, frame3];
+}
+// ── Legacy exports (unchanged) ───────────────────────────────────────────────
 /** Single-line compact phren for inline use */
 export const PHREN_INLINE = `${PURPLE}◆${RESET}`;
 /** Phren spinner frames for search/sync operations — cycles through in purple */

package/mcp/dist/phren-core.js

@@ -1,6 +1,6 @@
 // Shared Phren result types, validation tags, and low-level helpers.
 /**
- * Minimal cross-domain starter set for entity/conflict detection.
+ * Minimal cross-domain starter set for fragment/conflict detection.
  *
  * Kept intentionally small: only terms that are genuinely universal across
  * disciplines (languages, infra primitives, version control). Framework-specific
@@ -9,8 +9,8 @@
  */
 export const UNIVERSAL_TECH_TERMS_RE = /\b(Python|Rust|Go|Java|TypeScript|JavaScript|Docker|Kubernetes|AWS|GCP|Azure|SQL|Git)\b/gi;
 /**
- * Additional entity patterns beyond CamelCase and acronyms.
- * Each pattern has a named group so callers can identify the entity type.
+ * Additional fragment patterns beyond CamelCase and acronyms.
+ * Each pattern has a named group so callers can identify the fragment type.
  */
 export const EXTRA_ENTITY_PATTERNS = [
     // Semantic version numbers: v1.2.3, 2.0.0-beta.1
@@ -91,7 +91,7 @@ export const FINDING_TAGS = FINDING_TYPES;
 /** Canonical set of known observation tags — derived from FINDING_TYPES */
 export const KNOWN_OBSERVATION_TAGS = new Set(FINDING_TYPES);
 /** Document types in the FTS index */
-export const DOC_TYPES = ["claude", "findings", "reference", "skills", "summary", "task", "changelog", "canonical", "memory-queue", "skill", "other"];
+export const DOC_TYPES = ["claude", "findings", "reference", "skills", "summary", "task", "changelog", "canonical", "review-queue", "skill", "other"];
 // ── Cache eviction helper ────────────────────────────────────────────────────
 const CACHE_MAX = 1000;
 const CACHE_EVICT = 100;

package/mcp/dist/phren-paths.js

@@ -433,7 +433,7 @@ export function computePhrenLiveStateToken(phrenPath) {
     for (const projectDir of projectDirs) {
         const project = path.basename(projectDir);
         parts.push(`project:${project}`);
-        for (const file of ["CLAUDE.md", "summary.md", "FINDINGS.md", "tasks.md", "MEMORY_QUEUE.md", "CANONICAL_MEMORIES.md", "topic-config.json", "phren.project.yaml"]) {
+        for (const file of ["CLAUDE.md", "summary.md", "FINDINGS.md", "tasks.md", "review.md", "truths.md", "topic-config.json", "phren.project.yaml"]) {
             pushFileToken(parts, path.join(projectDir, file));
         }
         pushDirTokens(parts, path.join(projectDir, "reference"));

package/mcp/dist/profile-store.js

@@ -209,7 +209,7 @@ function buildProjectCard(dir) {
         .split("\n")
         .map((line) => line.trim())
         .find((line) => line && !line.startsWith("#")) || "";
-    const docs = ["CLAUDE.md", "FINDINGS.md", "summary.md", "MEMORY_QUEUE.md"]
+    const docs = ["CLAUDE.md", "FINDINGS.md", "summary.md", "review.md"]
         .filter((file) => fs.existsSync(path.join(dir, file)));
     const taskFile = TASK_FILE_ALIASES.find((file) => fs.existsSync(path.join(dir, file)));
     if (taskFile)