portable-agent-layer 0.52.0 → 0.53.0

package/README.md

@@ -83,6 +83,7 @@ pal cli status        # check your setup
 | `pal cli status` | Show current PAL configuration |
 | `pal cli doctor` | Check prerequisites and system health |
 | `pal cli migrate` | Run pending data migrations (non-destructive) |
+| `pal cli analyze [--actionable]` | Learning analysis: rating trends, failure patterns, graduation candidates |
 | `pal cli usage` | Summarize token usage and estimated cost |
 | `pal cli knowledge` | Query & manage the knowledge store (search, graph, stats, hubs, find, show, add, ls, ingest) |
 | `pal cli skill link <name>` | Link a personal `~/.pal/skills/<name>/` into every installed agent so it is discoverable |

package/assets/skills/analyze-pdf/SKILL.md

@@ -22,6 +22,18 @@ Use your native PDF reading capability (e.g. a Read tool or equivalent). Most mo
 
 Do NOT install PDF processing tools (poppler, pdftotext, etc.) unless the user explicitly asks. Native reading is sufficient.
 
+### Fallback: when native Read fails
+
+If the Read tool fails to open the PDF (e.g. error mentioning `pdftoppm`, missing renderer, or unsupported format), fall back to the text-extraction CLI:
+
+```bash
+bun ~/.pal/skills/analyze-pdf/tools/pdf-read.ts -- <path>
+```
+
+Use the stdout output as the document content and proceed with the user's request as normal.
+
+If `pdf-read.ts` also fails, stop completely — report the exact errors from both attempts and ask the user how to proceed. Never infer PDF content from filename, metadata, or assumptions.
+
 ## What to do with it
 
 Follow the user's request. Common tasks:

package/assets/skills/analyze-pdf/tools/pdf-read.ts

@@ -0,0 +1,35 @@
+#!/usr/bin/env bun
+
+/**
+ * PDF Read — Extracts text from a local PDF file, page by page.
+ *
+ * Usage:
+ *   bun pdf-read.ts -- <path/to/file.pdf>
+ *
+ * Prints each page's text to stdout separated by a page marker.
+ */
+
+import { readFile } from "node:fs/promises";
+import { parseArgs } from "node:util";
+import { extractText, getDocumentProxy } from "unpdf";
+
+async function main() {
+  const { positionals } = parseArgs({ allowPositionals: true, options: {} });
+
+  const filePath = positionals[0];
+  if (!filePath) {
+    console.error("Usage: bun pdf-read.ts -- <path/to/file.pdf>");
+    process.exit(1);
+  }
+
+  const buffer = await readFile(filePath);
+  const pdf = await getDocumentProxy(new Uint8Array(buffer));
+  const { totalPages, text } = await extractText(pdf, { mergePages: false });
+
+  for (let i = 0; i < totalPages; i++) {
+    console.log(`--- Page ${i + 1} ---`);
+    console.log(text[i]);
+  }
+}
+
+void main();

package/assets/skills/pal-analyze/SKILL.md

@@ -0,0 +1,54 @@
+---
+name: pal-analyze
+description: Run learning analysis — surface rating trends, recurring failure patterns, and graduation candidates. Use when learning analysis is due, or when the user asks about performance patterns, low ratings, or what to improve.
+argument-hint: [optional: --actionable for AI-generated recommendations]
+---
+
+When `/pal-analyze` is invoked (by you in response to a nudge, or by the user directly):
+
+## 1. Run the analyze tool
+
+```bash
+pal cli analyze
+```
+
+If the user passed `--actionable` or wants recommendations, append it: `pal cli analyze --actionable`
+
+## 2. Parse and present the output
+
+Read the console output and summarize the key signals. Focus on what's actionable, not exhaustive lists:
+
+**Ratings section:**
+- Lead with the average and trend direction
+- Call out any striking low-rating clusters (e.g. "47 low ratings, mostly around scope drift corrections")
+
+**Graduation candidates:**
+- Name the top 1-3 patterns ready to crystallize
+- Suggest the wisdom domain they'd live in
+
+**Emerging patterns:**
+- Name any 2-occurrence patterns worth watching
+
+Format example:
+```
+Analysis complete:
+
+Ratings: X.X/10 avg | N low (≤4) | N high (≥7)
+Top low-rating context: "[cluster description]"
+
+Ready to graduate (3+ occurrences):
+- "[pattern]" → suggest adding to wisdom/[domain].md
+
+Emerging (2 occurrences — one more to graduate):
+- "[pattern]"
+```
+
+## 3. Offer to act
+
+After showing results, ask:
+> "Want to crystallize any of these into a wisdom frame, or dig into the low-rating clusters?"
+
+If yes to crystallizing:
+```bash
+bun ~/.pal/tools/wisdom-frame.ts --domain <domain> --observation "<principle>"
+```

package/assets/skills/pal-reflect/SKILL.md

@@ -0,0 +1,52 @@
+---
+name: pal-reflect
+description: Run relationship reflect — promote recurring behavioral observations into tracked opinions. Use when relationship reflect is due, or when the user asks to review what patterns have been observed.
+argument-hint: [optional: --dry-run to preview without writing]
+---
+
+When `/pal-reflect` is invoked (by you in response to a nudge, or by the user directly):
+
+## 1. Run the reflect tool
+
+```bash
+bun run tool:reflect
+```
+
+If the user passed `--dry-run`, append it: `bun run tool:reflect -- --dry-run`
+
+## 2. Parse and present the output
+
+Read the console output and present a concise summary:
+
+**If opinions were promoted or strengthened:**
+```
+Reflect complete — here's what changed:
+
+NEW opinions (confidence seeded from recurring observations):
+- [statement] (XX%)
+
+STRENGTHENED opinions (evidence accumulated):
+- [statement]: XX% → YY%
+```
+
+**If nothing changed:**
+```
+Reflect complete — no patterns strong enough yet.
+[N] observations loaded. An opinion promotes when the same pattern appears 2+ times.
+Most recent observations:
+- [list up to 3 recent O notes]
+```
+
+## 3. Offer a follow-up
+
+After showing results, say:
+> "Want to review the full opinions list, or is there a specific pattern you'd like to reinforce or correct?"
+
+If the user confirms or corrects something, use the opinion tool:
+```bash
+# Confirmed
+bun ~/.pal/skills/opinion/tools/opinion.ts evidence "keywords" --confirmation "what they confirmed"
+
+# Corrected
+bun ~/.pal/skills/opinion/tools/opinion.ts evidence "keywords" --contradiction "what they corrected"
+```

package/assets/templates/PAL/ALGORITHM.md

@@ -175,6 +175,8 @@ Don't just *list* what must be true — actively confirm the load-bearing facts
 
 No criterion may rest on an unverified premise. If a premise can't be verified now, mark it explicitly as an assumption and add a criterion to check it during EXECUTE. After 2 failed attempts at the same sub-problem, stop and re-ground — re-run OBSERVE rather than iterating on a bad premise.
 
+**Retrieval failure is a hard block.** If a grounding tool call (Read, fetch, API, query) returns an error or no content, stop here — do not enter EXECUTE. Report the exact error, do not infer content from filename, metadata, or prior context, and ask the user for direction before proceeding.
+
 Output: `🧭 GROUNDING: [premises verified, or assumptions flagged]`
 
 ### ━━━ ⚡ EXECUTE ━━━ 3/5
@@ -234,16 +236,43 @@ bun ~/.pal/tools/algorithm-reflect.ts --task "description" --criteria N --passed
 
 Set `--scope task-specific` when the Q2 idea is bound to this one task (e.g. a criterion that only matters for the specific file, API, or dataset you were handling) and would not generalize to the algorithm; use `general` (the default) for reusable structural improvements. This keeps the algorithm-update synthesis focused on changes worth folding into ALGORITHM.md.
 
-**3. Relationship note** — write one Session entry capturing what was done this session:
+**3. Relationship note** — write behavioral observations (O, W) and a session diary entry (--b).
+
+The goal is behavioral intelligence about the user, not a session log. Session logs belong in handoff notes and project history. This step captures *who the user is* — observable patterns, preferences, world facts.
 
 ```bash
-bun ~/.pal/tools/relationship-note.ts --b "description"
+# Opinion — behavioral observation about the user (what you noticed about how they work):
+bun ~/.pal/tools/relationship-note.ts --o "User prefers reviewing existing code before adding anything new" --confidence 0.80
+
+# World fact — objective fact about the user's situation (tech stack, project state, context):
+bun ~/.pal/tools/relationship-note.ts --w "User is building a backend service in TypeScript with Bun"
+
+# Session diary — what the agent did this session (first-person, specific):
+bun ~/.pal/tools/relationship-note.ts --b "Refactored the auth middleware to support refresh token rotation"
+
+# Multiple notes in one call:
+bun ~/.pal/tools/relationship-note.ts --o "User prefers one verified change at a time, not batches" --confidence 0.80 --b "Fixed the path-normalization bug in the hook merge logic"
 ```
 
-- 1-2 sentences, first-person, specific — name the actual system/file/concept worked on
-- ✓ "Debugged the React Query cache split logic and resolved stuck message state in the onFinish callback"
-- ✗ "Helped with memory improvements" — too vague, no system named
-- Skip only if the session was a trivial lookup or typo fix (same rule as step 2)
+**O (Opinion) — what to write:**
+- Preference patterns: "User prefers short answers with a recommendation over exhaustive options"
+- Correction patterns: "User redirects scope drift immediately without elaborating on why"
+- Working style: "User verifies each change before asking for the next one"
+- Confidence guide: 0.70 = single observation, 0.80 = confirmed twice, 0.85+ = established pattern
+
+**W (World) — what to write:**
+- Tech stack facts: "User's current project uses PostgreSQL, tRPC, and Next.js"
+- Situation facts: "User is in the middle of a database migration with live traffic"
+
+**--b (Session diary) — keep it sharp:**
+- ✓ "Debugged the race condition in the message queue consumer and fixed the ack logic"
+- ✗ "Helped with backend improvements" — too vague, no system named
+
+**When to write O vs use the opinion tool (step 6):**
+- O notes → subtle patterns you observed, not yet confirmed → goes into daily file → synthesis promotes to opinions.json over time
+- Opinion tool → explicit user confirmation/correction → goes directly to opinions.json immediately
+
+Skip only if the session was a trivial lookup or typo fix (same rule as step 2).
 
 **4. Handoff note** — if work is unfinished, write what remains so the next session can pick up immediately:
 

package/assets/templates/PAL/SYSTEM_ARCHITECTURE.md

@@ -111,14 +111,13 @@ Before any code, before any architecture — there must be clear thinking:
 - Each tool is a standalone CLI program
 - Each skill is a self-contained capability
 - Hooks compose via `Promise.allSettled` — independent, parallel, isolated failures
-- Tools compose via `bun run tool:<name>` — standard I/O, exit codes
+- Tools compose via `pal cli <name>` — standard I/O, exit codes
 
 ### 9. CLI as Interface
 
 **Every operation should be accessible via command line.**
 
-- `pal cli <command>` for system management
-- `bun run tool:<name>` for utilities
+- `pal cli <command>` for system management and user-facing utilities
 - Skills triggered via agent slash commands
 - No hidden operations — everything is scriptable and testable
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -50,9 +50,10 @@
     "uninstall": "bun run src/cli/index.ts cli uninstall",
     "tool:synthesize": "bun run src/tools/agent/synthesize.ts",
     "tool:thread": "bun run src/tools/agent/thread.ts",
-    "tool:analyze": "bun run src/tools/agent/analyze.ts",
     "tool:wisdom-frame": "bun run src/tools/agent/wisdom-frame.ts",
-    "tool:reflect": "bun run src/tools/relationship-reflect.ts"
+    "tool:reflect": "bun run src/tools/relationship-reflect.ts",
+    "eval:sentiment": "bun eval/run.ts sentiment",
+    "eval:failure-principle": "bun eval/run.ts failure-principle"
   },
   "lint-staged": {
     "*.ts": [
@@ -75,6 +76,7 @@
     "jscpd": "^4.2.3",
     "knip": "^6.14.1",
     "lint-staged": "17.0.5",
+    "promptfoo": "0.121.14",
     "semantic-release": "^25.0.3",
     "typescript": "^5.9.3"
   },
@@ -83,6 +85,7 @@
     "adm-zip": "^0.5.17",
     "marked": "18.0.4",
     "pdf-lib": "1.17.1",
-    "playwright": "^1.60.0"
+    "playwright": "^1.60.0",
+    "unpdf": "^0.12.0"
   }
 }

package/src/cli/index.ts

@@ -192,6 +192,11 @@ async function runCli(command: string | undefined, args: string[]) {
       runMigrate(args);
       break;
     }
+    case "analyze": {
+      const { run: runAnalyze } = await import("../tools/agent/analyze");
+      await runAnalyze(args);
+      break;
+    }
     case "usage": {
       const { usage } = await import("../tools/token-cost");
       usage();
@@ -251,6 +256,7 @@ function showHelp() {
     pal cli status                          Show PAL configuration
     pal cli doctor [--probe-inference]      Check prerequisites and health (--probe fires real inference per route)
     pal cli migrate [--list] [--dry-run]    Run pending data migrations
+    pal cli analyze [--actionable]          Learning analysis: ratings, failure patterns, graduation candidates
     pal cli usage                           Summarize token usage and cost
     pal cli knowledge <sub> [args]          Query & manage the knowledge store
                                             (search · graph · stats · hubs · find · show · add · ls)

package/src/hooks/handlers/failure-principle.ts

@@ -57,13 +57,7 @@ async function processFailurePrinciple(
           .join("\n\n");
 
         const result = await inference({
-          system: `Analyze this failed AI interaction. The user rated it ${pending.rating}/10.
-
-Return JSON:
-{
-  "principle": "<one actionable rule the AI should follow, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>",
-  "detailed_context": "<what went wrong and why, 50-150 words>"
-}`,
+          system: `Analyze this failed AI interaction (rated ${pending.rating}/10). Return JSON: {"principle": "<verb-first actionable rule, 10-20 words — write a full sentence, not a fragment>", "detailed_context": "<root cause and what to do differently, 50-150 words>"}.`,
           user: `User feedback: ${pending.context}\n\nConversation:\n${recent}`,
           maxTokens: 400,
           timeout: 60000,

package/src/hooks/handlers/rating.ts

@@ -196,51 +196,21 @@ OUTPUT FORMAT (JSON only):
   "rating": <1-10 or null>,
   "sentiment": "positive" | "negative" | "neutral",
   "confidence": <0.0-1.0>,
-  "summary": "<brief explanation, 10 words max>",
-  "detailed_context": "<comprehensive analysis, 50-150 words>",
-  "principle": "<one actionable rule the AI should follow to avoid this failure or repeat this success, 10-20 words. Start with a verb: 'Verify...', 'Always...', 'Never...', 'Ask before...'>"
+  "summary": "<10 words max>",
+  "detailed_context": "<what the user wanted, what the AI did or failed to do, root cause, and what to do differently — 50-150 words>",
+  "principle": "<one actionable rule, 10-20 words, start with a verb: Verify / Always / Never / Ask>"
 }
 
-DETAILED_CONTEXT REQUIREMENTS:
-1. What the user was trying to accomplish
-2. What the AI did (or failed to do)
-3. Why the user reacted this way (root cause)
-4. What specific behavior triggered this reaction
-5. What the AI should do differently (negative) or what worked (positive)
-
-RATING SCALE:
-- 1-2: Strong frustration, anger, disappointment
-- 3-4: Mild frustration, dissatisfaction
-- 5: Neutral
-- 6-7: Satisfaction, approval
-- 8-9: Strong approval, impressed
-- 10: Extraordinary enthusiasm
-
-CRITICAL DISTINCTIONS:
-- Profanity can indicate EITHER frustration OR excitement — use context
-- Sarcasm: "Oh great, another error" = negative despite "great"
-- Short praise ("great job", "nice") = STRONG APPROVAL (8-9), not mild
-
-IMPLIED SENTIMENT (most feedback is implied, not explicit):
-
-Implied NEGATIVE (rate 2-4):
-- CORRECTIONS: "No, I meant..." / "That's not what I said" -> 3-4
-- REPEATED REQUESTS: Having to ask the same thing twice -> 2-3
-- BEHAVIORAL CORRECTIONS: "Don't do that" / "Stop doing X" -> 3
-- EXASPERATED QUESTIONS: "Why is this still broken?" -> 2-3
-- SHORT DISMISSALS: "whatever" / "fine" / "just do it" -> 3-4
-- POINTING OUT OMISSIONS: "What about X?" (obviously required) -> 4
-
-Implied POSITIVE (rate 6-8):
-- TRUST SIGNALS: "Alright, fix all of it" / "Go ahead" -> 7
-- BUILDING ON WORK: "Now also add..." / "Next, do..." -> 6-7
-- ENGAGED FOLLOW-UPS: "What about X?" (exploring, not correcting) -> 6
-- MOVING FORWARD: Accepting output and giving next task -> 6
-
-WHEN TO RETURN null FOR RATING:
-- Neutral technical questions ("Can you check the logs?")
-- Simple commands ("Do it", "Yes", "Continue")
-- No emotional indicators present`;
+RATING SCALE: 1-2 strong frustration · 3-4 mild frustration · 5 neutral · 6-7 approval · 8-9 strong approval · 10 exceptional · null = no emotional signal
+Short praise ("great job", "nice") = STRONG APPROVAL (8-9), not mild.
+
+TASK DIRECTIVES — short imperatives with "pls" are approval or sequencing signals (null or 6-7, NOT negative):
+"write it pls" / "do it pls" / "step 3 pls" / "option 2 pls" = user directing or approving the AI's own proposal.
+EXCEPTION: "fix X pls" / "fix that pls" is always negative — "fix" implies a problem regardless of "pls".
+
+IMPLIED NEGATIVE (rate 2-4): corrections ("that's wrong", "I meant..."), repeats ("again pls", "still broken", "doesn't work again"), behavioral corrections ("don't do that"), exasperated questions ("why is this still broken?"), failure confirmations ("nothing is fixed").
+IMPLIED POSITIVE (rate 6-8): trust signals ("go ahead", "fix all of it"), continuation ("now also add X", "next do..."), moving forward with the next task.
+NULL rating: neutral questions, simple continuations ("yes", "continue"), task directives without failure context.`;
 
 const MIN_CONFIDENCE = 0.5;
 

package/src/hooks/handlers/reflect-trigger.ts

@@ -43,6 +43,21 @@ function countNotesSince(since: string): number {
   return count;
 }
 
+/**
+ * Session-start nudge: surfaces when ≥5 new O/W/B notes are pending review.
+ * Returns a formatted reminder string, or "" when nothing is due.
+ */
+export function loadReflectNudge(): string {
+  const lastReflect = getLastReflectDate();
+  const newNotes = countNotesSince(lastReflect || "2000-01-01");
+  if (newNotes < MIN_NEW_NOTES) return "";
+  const since = lastReflect || "the start";
+  return [
+    "## Relationship Reflect Due",
+    `🔄 ${newNotes} new relationship observations since ${since} — offer to run \`/pal-reflect\` to promote recurring patterns into tracked opinions.`,
+  ].join("\n");
+}
+
 export async function checkReflectTrigger(): Promise<void> {
   const lastReflect = getLastReflectDate();
   const now = new Date();

package/src/hooks/lib/analyze-nudge.ts

@@ -0,0 +1,47 @@
+/**
+ * Analyze nudge — surfaces a session-start reminder when the learning analysis
+ * is overdue (≥7 days since last run, or never run).
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { paths } from "./paths";
+
+const MAX_DAYS = 7;
+const DAY_MS = 86_400_000;
+
+function markFile(): string {
+  return resolve(paths.state(), "last-analyze.json");
+}
+
+function readLastAnalyzeDate(): string | null {
+  try {
+    const parsed = JSON.parse(readFileSync(markFile(), "utf-8"));
+    return typeof parsed.lastAnalyzedTs === "string" ? parsed.lastAnalyzedTs : null;
+  } catch {
+    return null;
+  }
+}
+
+export function writeLastAnalyzeDate(ts: string): void {
+  writeFileSync(markFile(), `${JSON.stringify({ lastAnalyzedTs: ts }, null, 2)}\n`);
+}
+
+export function loadAnalyzeNudge(now: Date = new Date()): string {
+  const last = readLastAnalyzeDate();
+  if (!last) {
+    return [
+      "## Learning Analysis Due",
+      "📊 Learning analysis has never been run — offer to run `/pal-analyze` (`pal cli analyze`) for a health check on ratings, failure patterns, and graduation candidates.",
+    ].join("\n");
+  }
+
+  const daysSince = (now.getTime() - new Date(last).getTime()) / DAY_MS;
+  if (daysSince < MAX_DAYS) return "";
+
+  const since = new Date(last).toISOString().slice(0, 10);
+  return [
+    "## Learning Analysis Due",
+    `📊 Learning analysis last run ${Math.floor(daysSince)}d ago (${since}) — offer to run \`/pal-analyze\` for a health check.`,
+  ].join("\n");
+}

package/src/hooks/lib/context.ts

@@ -6,7 +6,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { resolve } from "node:path";
+import { loadReflectNudge } from "../handlers/reflect-trigger";
 import { loadAlgorithmReviewNudge } from "./algorithm-review";
+import { loadAnalyzeNudge } from "./analyze-nudge";
 import { readLearnings } from "./learning-store";
 import { loadOpinionContext } from "./opinions";
 import { paths } from "./paths";
@@ -300,10 +302,14 @@ export function buildSystemReminder(opts: { agent?: AgentTarget } = {}): string
   const handoff = settings.isEnabled("handoff") ? loadHandoff() : "";
   // Maintainer-only: self-gates to a repo checkout, "" for everyone else.
   const algoReview = loadAlgorithmReviewNudge();
+  const reflectNudge = loadReflectNudge();
+  const analyzeNudge = loadAnalyzeNudge();
   const parts: string[] = [];
   if (startup) parts.push(startup);
   if (handoff) parts.push(handoff);
   if (algoReview) parts.push(algoReview);
+  if (reflectNudge) parts.push(reflectNudge);
+  if (analyzeNudge) parts.push(analyzeNudge);
   if (selfModel) parts.push(selfModel);
   if (wisdom) parts.push(wisdom);
   if (opinions) parts.push(opinions);

package/src/tools/agent/analyze.ts

@@ -9,6 +9,7 @@
  */
 
 import { parseArgs } from "node:util";
+import { writeLastAnalyzeDate } from "../../hooks/lib/analyze-nudge";
 import { type AnalysisResult, analyze } from "../../hooks/lib/graduation";
 
 // ── ANSI Colors ──
@@ -23,7 +24,7 @@ const c = {
   magenta: (s: string) => `\x1b[35m${s}\x1b[0m`,
 };
 
-export function printReport(result: AnalysisResult): void {
+function printReport(result: AnalysisResult): void {
   const hasPatterns = result.candidates.length > 0 || result.emerging.length > 0;
   const hasRatings = result.ratings !== null;
 
@@ -117,9 +118,9 @@ export function printReport(result: AnalysisResult): void {
   }
 }
 
-async function run() {
+export async function run(argv: string[] = Bun.argv.slice(2)) {
   const { values } = parseArgs({
-    args: Bun.argv.slice(2),
+    args: argv,
     options: {
       help: { type: "boolean", short: "h" },
       actionable: { type: "boolean", short: "a" },
@@ -145,13 +146,14 @@ async function run() {
   To crystallize a graduated pattern, add it to the target wisdom frame:
     - Your principle here [CRYSTAL: 85%]
 
-  Usage: bun run tool:analyze [--actionable] [--help]
+  Usage: pal cli analyze [--actionable]
 `);
     process.exit(0);
   }
 
   const result = await analyze({ actionable: values.actionable });
   printReport(result);
+  writeLastAnalyzeDate(new Date().toISOString());
 }
 
 if (import.meta.main) await run();

package/src/tools/agent/relationship-note.ts

@@ -1,12 +1,19 @@
 #!/usr/bin/env bun
 /**
- * RelationshipNote — Write a B entry to today's relationship log.
+ * RelationshipNote — Write W/O/Session entries to today's relationship log.
  *
- * Called in the ALGORITHM LEARN phase. Claude writes the B entry directly
- * from full session context — no inference call needed.
+ * Called in the ALGORITHM LEARN phase. Writes behavioral observations about
+ * the user (O, W) and session diary entries (--b).
  *
  * Usage:
- *   bun ~/.pal/tools/relationship-note.ts --b "what I did this session"
+ *   bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
+ *   bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+ *   bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+ *
+ * Note types:
+ *   --o   Opinion/behavioral observation about the user (requires --confidence)
+ *   --w   World fact about the user's situation (objective, observable)
+ *   --b   Session diary — what Jarvis did this session (first-person, specific)
  */
 
 import { parseArgs } from "node:util";
@@ -16,35 +23,72 @@ function run() {
   const { values } = parseArgs({
     args: Bun.argv.slice(2),
     options: {
+      o: { type: "string", multiple: true },
+      w: { type: "string", multiple: true },
       b: { type: "string" },
+      confidence: { type: "string" },
       help: { type: "boolean", short: "h" },
     },
   });
 
   if (values.help) {
     console.log(`
-RelationshipNote — Append a B entry to today's relationship log
+RelationshipNote — Append W/O/Session entries to today's relationship log
 
 Usage:
-  bun ~/.pal/tools/relationship-note.ts --b "description"
+  bun ~/.pal/tools/relationship-note.ts --o "Rico prefers X" --confidence 0.80
+  bun ~/.pal/tools/relationship-note.ts --w "Rico is building X in TypeScript"
+  bun ~/.pal/tools/relationship-note.ts --b "Debugged the cache split logic"
+
+Flags:
+  --o TEXT          Opinion/behavioral observation about the user
+  --confidence N    Confidence for --o (0.0–1.0, default 0.75)
+  --w TEXT          World fact about the user's situation
+  --b TEXT          Session diary — what Jarvis did (first-person, specific)
 
-Arguments:
-  --b   What happened this session (1-2 sentences, first-person, specific)
+Multiple flags may be combined in one call. At least one of --o, --w, --b is required.
 
 Output: appends to memory/relationship/YYYY-MM/YYYY-MM-DD.md
 `);
     process.exit(0);
   }
 
-  if (!values.b) {
-    console.error("Required: --b");
+  if (!values.o && !values.w && !values.b) {
+    console.error("Required: at least one of --o, --w, --b");
     process.exit(1);
   }
 
-  appendNotes([{ type: "Session", text: values.b }]);
+  const notes = [];
+
+  if (values.o && values.o.length > 0) {
+    const confidence = values.confidence ? Number.parseFloat(values.confidence) : 0.75;
+    if (Number.isNaN(confidence) || confidence < 0 || confidence > 1) {
+      console.error("--confidence must be a number between 0.0 and 1.0");
+      process.exit(1);
+    }
+    for (const text of values.o) {
+      notes.push({ type: "O" as const, text, confidence });
+    }
+  }
+
+  if (values.w && values.w.length > 0) {
+    for (const text of values.w) {
+      notes.push({ type: "W" as const, text });
+    }
+  }
+
+  if (values.b) {
+    notes.push({ type: "Session" as const, text: values.b });
+  }
+
+  appendNotes(notes);
 
   console.log(
-    JSON.stringify({ success: true, message: "Relationship note written" }, null, 2)
+    JSON.stringify(
+      { success: true, message: "Relationship note written", count: notes.length },
+      null,
+      2
+    )
   );
 }