From 402e33e99214cb2bc17c2921a07a2720050aa1c9 Mon Sep 17 00:00:00 2001
From: Silviu Druma <silviudr@gmail.com>
Date: Thu, 22 Jan 2026 07:20:12 -0500
Subject: [PATCH 1/2] feat: add final polish

---
 CONTRIBUTING.md                        |   1 +
 apps/api/static/app.js                 |  23 +--
 apps/api/static/index.html             |  36 ++++-
 apps/api/static/styles.css             | 186 ++++++++++++++++++++++++-
 docs/assistant_prompts/claude_tasks.md |   1 +
 5 files changed, 227 insertions(+), 20 deletions(-)

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index c34e7cb..4374e23 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -185,6 +185,7 @@ PlanProof values correctness over persuasion.
 - [X] PR 3.3: Failure/Rejection Styles
 - [X] PR 3.4: Assumptions & Questions (Show the AI's "Why").
 - [X] PR 4.1: Opik Trace Link (Show the "View Trace" button for the judges).
+- [X] PR 4.2: Final Polish & UX Tooltips
 
 ## Backend Lane (Codex)
 
diff --git a/apps/api/static/app.js b/apps/api/static/app.js
index e8c5dc5..e894f8e 100644
--- a/apps/api/static/app.js
+++ b/apps/api/static/app.js
@@ -216,28 +216,31 @@ function renderErrors(errors, isPriority = false) {
 }
 
 // ==========================================================================
-// Opik Trace Link (PR 4.1)
+// Opik Trace Link (PR 4.1, updated PR 4.2)
 // ==========================================================================
 
 /**
- * Shows or hides the Opik trace link section.
- * @param {boolean} visible - Whether to show the trace link
+ * Enables or disables the Opik trace link button.
+ * @param {boolean} enabled - Whether the trace link should be clickable
  * @param {string|null} traceUrl - Optional custom trace URL
  */
-function renderTraceLink(visible, traceUrl = null) {
-  const section = elements.traceSection;
+function renderTraceLink(enabled, traceUrl = null) {
   const link = elements.traceLink;
-  if (!section) return;
+  if (!link) return;
 
-  if (!visible) {
-    section.classList.add('trace-section--hidden');
+  if (!enabled) {
+    link.classList.add('btn-trace--disabled');
+    link.setAttribute('aria-disabled', 'true');
+    link.setAttribute('title', 'Generate a plan first to view the technical trace.');
     return;
   }
 
-  section.classList.remove('trace-section--hidden');
+  link.classList.remove('btn-trace--disabled');
+  link.setAttribute('aria-disabled', 'false');
+  link.setAttribute('title', 'Inspect the agentic logic, deterministic logs, and LLM spans in the Opik observability suite.');
   
   // Update URL if provided (for future per-trace linking)
-  if (traceUrl && link) {
+  if (traceUrl) {
     link.href = traceUrl;
   }
 }
diff --git a/apps/api/static/index.html b/apps/api/static/index.html
index 7ccbb5f..07230c9 100644
--- a/apps/api/static/index.html
+++ b/apps/api/static/index.html
@@ -96,8 +96,17 @@ <h3 class="callout-title">Clarifying Questions</h3>
         <div id="timeline-container" class="timeline">
           <!-- Timeline items will be rendered here by app.js -->
           <div class="timeline-empty">
-            <p class="empty-message">No plan generated yet.</p>
-            <p class="empty-hint">Enter your context and click "Generate Plan"</p>
+            <div class="empty-illustration">
+              <div class="empty-icon-ring">
+                <span class="empty-icon">📋</span>
+              </div>
+              <div class="empty-sparkle empty-sparkle--1">✦</div>
+              <div class="empty-sparkle empty-sparkle--2">✧</div>
+              <div class="empty-sparkle empty-sparkle--3">✦</div>
+            </div>
+            <h3 class="empty-title">Ready When You Are</h3>
+            <p class="empty-message">Paste your context, constraints, and goals on the left.</p>
+            <p class="empty-hint">We'll build a mathematically verified plan—no hallucinations, no overlaps.</p>
           </div>
           <!-- Loading State (PR 3.1) -->
           <div id="timeline-loading" class="timeline-loading">
@@ -130,7 +139,13 @@ <h3 class="section-title">Extracted Constraints</h3>
         
         <!-- Pre-Flight Checklist -->
         <div class="checklist-section">
-          <h3 class="section-title">Pre-Flight Checks</h3>
+          <h3 class="section-title">
+            Pre-Flight Checks
+            <button type="button" class="info-tooltip" aria-label="What are Pre-Flight Checks?">
+              <span class="info-icon">ⓘ</span>
+              <span class="tooltip-content">Binary pass/fail gates that must ALL pass for a valid plan. Zero tolerance for constraint violations, time overlaps, or hallucinated tasks.</span>
+            </button>
+          </h3>
           <ul id="checklist" class="checklist">
             <li class="checklist-item checklist-item--pending">
               <span class="check-icon">○</span>
@@ -157,7 +172,13 @@ <h3 class="section-title">Pre-Flight Checks</h3>
         
         <!-- Metrics Grid (PR 1.4) -->
         <div class="metrics-section">
-          <h3 class="section-title">Validation Metrics</h3>
+          <h3 class="section-title">
+            Validation Metrics
+            <button type="button" class="info-tooltip" aria-label="What are Validation Metrics?">
+              <span class="info-icon">ⓘ</span>
+              <span class="tooltip-content">Quantitative measurements from deterministic Python validators. These numbers are computed, not guessed—an LLM never grades its own plan.</span>
+            </button>
+          </h3>
           <div id="metrics-grid" class="metrics-grid">
             <div class="metric-tile" data-metric="constraint_violation_count">
               <span class="metric-value mono">—</span>
@@ -215,14 +236,15 @@ <h3 class="section-title section-title--error">Errors</h3>
         </div>
         
         <!-- Opik Trace Link (PR 4.1) -->
-        <div id="trace-section" class="trace-section trace-section--hidden">
+        <div id="trace-section" class="trace-section">
           <a 
             id="trace-link" 
             href="https://www.comet.com/opik/planproof" 
             target="_blank" 
             rel="noopener noreferrer"
-            class="btn-trace"
-            title="Inspect the agentic logic, deterministic logs, and LLM spans in the Opik observability suite."
+            class="btn-trace btn-trace--disabled"
+            title="Generate a plan first to view the technical trace."
+            aria-disabled="true"
           >
             <span class="trace-icon">🔍</span>
             <span class="trace-text">View Technical Trace</span>
diff --git a/apps/api/static/styles.css b/apps/api/static/styles.css
index 8015f8f..01ea602 100644
--- a/apps/api/static/styles.css
+++ b/apps/api/static/styles.css
@@ -297,21 +297,114 @@ body {
   border-radius: 1px;
 }
 
+/* --------------------------------------------------------------------------
+   Empty State (PR 4.2)
+   -------------------------------------------------------------------------- */
 .timeline-empty {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
   text-align: center;
   padding: var(--space-2xl) var(--space-lg);
+  min-height: 320px;
+}
+
+.empty-illustration {
+  position: relative;
+  margin-bottom: var(--space-xl);
+}
+
+.empty-icon-ring {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 80px;
+  height: 80px;
+  background: linear-gradient(
+    135deg,
+    rgba(139, 92, 246, 0.15) 0%,
+    rgba(14, 165, 233, 0.1) 100%
+  );
+  border: 2px solid rgba(139, 92, 246, 0.3);
+  border-radius: 50%;
+  animation: pulse-ring 3s ease-in-out infinite;
+}
+
+.empty-icon {
+  font-size: 2rem;
+  filter: grayscale(0.2);
+}
+
+@keyframes pulse-ring {
+  0%, 100% {
+    transform: scale(1);
+    border-color: rgba(139, 92, 246, 0.3);
+  }
+  50% {
+    transform: scale(1.05);
+    border-color: rgba(139, 92, 246, 0.5);
+  }
+}
+
+.empty-sparkle {
+  position: absolute;
+  font-size: 0.75rem;
+  color: var(--color-accent-violet);
+  opacity: 0.6;
+  animation: sparkle 2s ease-in-out infinite;
+}
+
+.empty-sparkle--1 {
+  top: -5px;
+  right: -8px;
+  animation-delay: 0s;
+}
+
+.empty-sparkle--2 {
+  bottom: 5px;
+  left: -10px;
+  animation-delay: 0.7s;
+}
+
+.empty-sparkle--3 {
+  top: 10px;
+  right: -15px;
+  font-size: 0.5rem;
+  animation-delay: 1.3s;
+}
+
+@keyframes sparkle {
+  0%, 100% {
+    opacity: 0.4;
+    transform: scale(1);
+  }
+  50% {
+    opacity: 1;
+    transform: scale(1.2);
+  }
+}
+
+.empty-title {
+  font-family: var(--font-human);
+  font-size: 1.25rem;
+  font-weight: 600;
+  color: var(--color-text);
+  margin-bottom: var(--space-sm);
 }
 
 .empty-message {
-  font-size: 1rem;
+  font-size: 0.9375rem;
   color: var(--color-text-muted);
-  margin-bottom: var(--space-sm);
+  margin-bottom: var(--space-xs);
+  max-width: 280px;
 }
 
 .empty-hint {
-  font-size: 0.875rem;
+  font-size: 0.8125rem;
   color: var(--color-text-muted);
   opacity: 0.7;
+  max-width: 300px;
 }
 
 /* Rejected State (PR 3.3) */
@@ -539,6 +632,9 @@ body {
    Checklist Section
    -------------------------------------------------------------------------- */
 .section-title {
+  display: flex;
+  align-items: center;
+  gap: var(--space-sm);
   font-size: 0.6875rem;
   font-weight: 600;
   text-transform: uppercase;
@@ -551,6 +647,77 @@ body {
   color: var(--color-failure);
 }
 
+/* --------------------------------------------------------------------------
+   Info Tooltips (PR 4.2)
+   -------------------------------------------------------------------------- */
+.info-tooltip {
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  height: 1rem;
+  padding: 0;
+  background: transparent;
+  border: none;
+  cursor: help;
+  text-transform: none;
+  letter-spacing: normal;
+}
+
+.info-icon {
+  font-size: 0.75rem;
+  color: var(--color-text-muted);
+  opacity: 0.6;
+  transition: opacity var(--transition-fast), color var(--transition-fast);
+}
+
+.info-tooltip:hover .info-icon {
+  opacity: 1;
+  color: var(--color-accent-violet);
+}
+
+.tooltip-content {
+  position: absolute;
+  bottom: calc(100% + 8px);
+  left: 50%;
+  transform: translateX(-50%);
+  width: 220px;
+  padding: var(--space-sm) var(--space-md);
+  background-color: var(--color-bg-primary);
+  border: 1px solid var(--color-bg-elevated);
+  border-radius: var(--radius-md);
+  box-shadow: 0 8px 24px rgba(0, 0, 0, 0.4);
+  font-family: var(--font-human);
+  font-size: 0.75rem;
+  font-weight: 400;
+  line-height: 1.5;
+  color: var(--color-text);
+  text-align: left;
+  white-space: normal;
+  opacity: 0;
+  visibility: hidden;
+  pointer-events: none;
+  transition: opacity var(--transition-fast), visibility var(--transition-fast);
+  z-index: 100;
+}
+
+.tooltip-content::after {
+  content: '';
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  transform: translateX(-50%);
+  border: 6px solid transparent;
+  border-top-color: var(--color-bg-elevated);
+}
+
+.info-tooltip:hover .tooltip-content,
+.info-tooltip:focus .tooltip-content {
+  opacity: 1;
+  visibility: visible;
+}
+
 /* Errors Priority State (PR 3.3) */
 .errors-section--priority {
   order: -1;
@@ -1030,6 +1197,19 @@ body {
   background-color: rgba(139, 92, 246, 0.1);
 }
 
+/* Disabled state until plan is generated (PR 4.2) */
+.btn-trace--disabled {
+  opacity: 0.4;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+.btn-trace--disabled:hover {
+  color: var(--color-text-muted);
+  border-color: var(--color-bg-elevated);
+  background-color: transparent;
+}
+
 .trace-icon {
   font-size: 0.875rem;
 }
diff --git a/docs/assistant_prompts/claude_tasks.md b/docs/assistant_prompts/claude_tasks.md
index 6f96eca..9d096a6 100644
--- a/docs/assistant_prompts/claude_tasks.md
+++ b/docs/assistant_prompts/claude_tasks.md
@@ -45,6 +45,7 @@ You are Claude working as a coding assistant in VS Code.
 - [X] **PR 3.3:** Apply "Rejected" styling (gray/muted) to plans where `validation.status == "fail"`.
 - [X] **PR 3.4:** Assumptions & Questions (Show the AI's "Why").
 - [X] **PR 4.1:** Opik Trace Link (Show the "View Trace" button for the judges).
+- [X] **PR 4.2** Final Polish & UX Tooltips
 
 
 ---

From a188e81ef63adca1fbe26c43613e46862f5df823 Mon Sep 17 00:00:00 2001
From: Silviu Druma <silviudr@gmail.com>
Date: Thu, 22 Jan 2026 07:27:17 -0500
Subject: [PATCH 2/2] feat: add better observability

---
 apps/api/static/app.js     | 21 +++++++++++++++------
 apps/api/static/index.html |  3 ++-
 apps/api/static/styles.css | 36 +++++++++++++++++++++++++++++++++++-
 3 files changed, 52 insertions(+), 8 deletions(-)

diff --git a/apps/api/static/app.js b/apps/api/static/app.js
index e894f8e..730a1f6 100644
--- a/apps/api/static/app.js
+++ b/apps/api/static/app.js
@@ -138,14 +138,18 @@ const METRIC_CONFIG = [
 /**
  * Renders the pre-flight checklist with metric values.
  * @param {Object|null} metrics - The validation.metrics object from API response
+ * @param {boolean} planGenerated - Whether a plan was successfully generated (for defensive UI)
  */
-function renderChecklist(metrics) {
+function renderChecklist(metrics, planGenerated = false) {
   const checklist = elements.checklist;
   if (!checklist) return;
 
   // Clear existing items
   checklist.innerHTML = '';
 
+  // Defensive UI: Show "Data Unavailable" if plan was generated but metrics missing
+  const showUnavailable = planGenerated && !metrics;
+
   METRIC_CONFIG.forEach((config) => {
     const li = document.createElement('li');
     li.className = 'checklist-item';
@@ -156,7 +160,9 @@ function renderChecklist(metrics) {
     const passes = hasValue && config.isPass(value);
 
     // Set state class
-    if (!hasValue) {
+    if (showUnavailable) {
+      li.classList.add('checklist-item--unavailable');
+    } else if (!hasValue) {
       li.classList.add('checklist-item--pending');
     } else if (passes) {
       li.classList.add('checklist-item--pass');
@@ -165,8 +171,8 @@ function renderChecklist(metrics) {
     }
 
     // Build inner HTML
-    const icon = !hasValue ? '○' : passes ? '✓' : '✗';
-    const displayValue = hasValue ? config.format(value) : '—';
+    const icon = showUnavailable ? '⚠' : !hasValue ? '○' : passes ? '✓' : '✗';
+    const displayValue = showUnavailable ? 'N/A' : hasValue ? config.format(value) : '—';
 
     li.innerHTML = `
       <span class="check-icon">${icon}</span>
@@ -601,8 +607,8 @@ function renderValidation(validation) {
                  validation.status === 'fail' ? 'fail' : 'pending';
   renderStatusBadge(status);
 
-  // Render checklist with metrics
-  renderChecklist(validation.metrics || null);
+  // Render checklist with metrics (planGenerated=true for defensive UI)
+  renderChecklist(validation.metrics || null, true);
 
   // Render metrics grid (PR 1.4)
   renderMetricsGrid(validation.metrics || null);
@@ -943,6 +949,9 @@ async function generatePlan() {
     }
 
     const data = await response.json();
+    
+    // DEBUG: Log full API response for field verification
+    console.log('DEBUG: Full API Response:', data);
 
     // Determine if plan is rejected (PR 3.3)
     const isRejected = data.validation?.status === 'fail';
diff --git a/apps/api/static/index.html b/apps/api/static/index.html
index 07230c9..b8ee1a7 100644
--- a/apps/api/static/index.html
+++ b/apps/api/static/index.html
@@ -121,6 +121,7 @@ <h3 class="empty-title">Ready When You Are</h3>
       <aside class="proof-sidebar">
         <header class="panel-header">
           <h2 class="panel-title">Validation Proof</h2>
+          <span class="observability-label mono">Observability: Opik / Project: Hackaton</span>
         </header>
         
         <!-- Status Badge -->
@@ -239,7 +240,7 @@ <h3 class="section-title section-title--error">Errors</h3>
         <div id="trace-section" class="trace-section">
           <a 
             id="trace-link" 
-            href="https://www.comet.com/opik/planproof" 
+            href="https://www.comet.com/opik/silviu-druma/projects/Hackaton" 
             target="_blank" 
             rel="noopener noreferrer"
             class="btn-trace btn-trace--disabled"
diff --git a/apps/api/static/styles.css b/apps/api/static/styles.css
index 01ea602..6cddbb4 100644
--- a/apps/api/static/styles.css
+++ b/apps/api/static/styles.css
@@ -19,6 +19,7 @@
   /* Colors: Status */
   --color-success: #10b981;
   --color-failure: #f43f5e;
+  --color-warning: #f59e0b;
   --color-pending: #64748b;
   
   /* Colors: Text */
@@ -252,9 +253,20 @@ body {
 
 .panel-header {
   display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(--space-xs);
+  margin-bottom: var(--space-lg);
+}
+
+.proof-sidebar .panel-header {
+  flex-direction: column;
+}
+
+.timeline-panel .panel-header {
+  flex-direction: row;
   align-items: center;
   justify-content: space-between;
-  margin-bottom: var(--space-lg);
 }
 
 .panel-title {
@@ -263,6 +275,14 @@ body {
   color: var(--color-text-primary);
 }
 
+/* Observability Label (PR 4.2) */
+.observability-label {
+  font-size: 0.625rem;
+  color: var(--color-text-muted);
+  opacity: 0.7;
+  letter-spacing: 0.05em;
+}
+
 .task-count {
   font-family: var(--font-system);
   font-size: 0.75rem;
@@ -774,6 +794,20 @@ body {
   color: var(--color-failure);
 }
 
+/* Unavailable state for missing metrics (PR 4.2 Defensive UI) */
+.checklist-item--unavailable {
+  opacity: 0.6;
+}
+
+.checklist-item--unavailable .check-icon {
+  color: var(--color-warning);
+}
+
+.checklist-item--unavailable .check-value {
+  color: var(--color-text-muted);
+  font-style: italic;
+}
+
 /* --------------------------------------------------------------------------
    Extracted Constraints Section (PR 2.1)
    -------------------------------------------------------------------------- */