feat: rewarding build UX + Docker fixes + web docs cleanup

Docker:
- Dockerfile: add ENV PYTHONPATH=/app, mkdir designs/ & artifacts/,
make sby install resilient (pip first, then git clone fallback)
- docker-compose.yml: add ./designs:/app/designs volume, add healthcheck
pointing at GET /health

Web docs:
- Remove raw README from in-app docs index; replace with user-friendly
Getting Started (USER_GUIDE.md) and Cloud Deployment guide

Build UX (rewarding / less frustrating):
- StageProgressBar: each active/completed stage now shows a brief
encouraging description (e.g. 'Writing synthesizable Verilog')
- Milestone stages (RTL_GEN, VERIFICATION, HARDENING, SIGNOFF) get a
gold dot badge when completed
- HumanInLoopBuild: bottom status bar now shows stage-aware contextual
message instead of generic 'Building autonomously'
- HumanInLoopBuild: milestone celebration toast slides in when a key
stage is approved (auto-dismisses after 5s)
- hitl.css: stage description subtitle, milestone badge, toast-in
animation, indicator top-alignment fix

Dockerfile

@@ -17,13 +17,16 @@ RUN apt-get update && apt-get install -y --no-install-recommends \
     yosys \
     && rm -rf /var/lib/apt/lists/*
 
-# Install SymbiYosys from source
-RUN git clone --depth 1 https://github.com/YosysHQ/sby /tmp/sby \
-    && cd /tmp/sby && make install \
-    && rm -rf /tmp/sby
+# Install SymbiYosys (try pip first, fall back to source)
+RUN pip install --no-cache-dir symbiyosys 2>/dev/null || \
+    (git clone --depth 1 https://github.com/YosysHQ/sby /tmp/sby \
+     && cd /tmp/sby && make install && rm -rf /tmp/sby) || true
 
 WORKDIR /app
 
+# Ensure module resolution works from /app
+ENV PYTHONPATH=/app
+
 # Install Python dependencies first (layer cache)
 COPY requirements.txt .
 RUN pip install --no-cache-dir --upgrade pip && \
@@ -33,6 +36,9 @@ RUN pip install --no-cache-dir --upgrade pip && \
 # Copy application code
 COPY . .
 
+# Create runtime directories that the build pipeline writes into
+RUN mkdir -p /app/designs /app/artifacts
+
 # HuggingFace Spaces runs as non-root user 1000
 RUN useradd -m -u 1000 appuser && chown -R appuser:appuser /app
 USER appuser

docker-compose.yml

@@ -12,4 +12,11 @@ services:
     volumes:
       - ./artifacts:/app/artifacts
       - ./training:/app/training
+      - ./designs:/app/designs
     restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "curl", "-sf", "http://localhost:7860/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+      start_period: 20s

server/api.py

@@ -251,11 +251,11 @@ def _repo_root() -> str:
 def _docs_index() -> Dict[str, Dict[str, str]]:
     root = _repo_root()
     return {
-        "readme": {
-            "title": "README",
+        "getting_started": {
+            "title": "Getting Started",
             "section": "Product",
-            "path": os.path.join(root, "README.md"),
-            "summary": "Full platform overview, flow, quality gates, and upgrade details.",
+            "path": os.path.join(root, "docs", "USER_GUIDE.md"),
+            "summary": "Quick-start guide — build your first chip in minutes.",
         },
         "web_guide": {
             "title": "Web App Guide",
@@ -269,11 +269,11 @@ def _docs_index() -> Dict[str, Dict[str, str]]:
             "path": os.path.join(root, "docs", "INSTALL.md"),
             "summary": "Installation and environment setup steps.",
         },
-        "user_guide": {
-            "title": "User Guide",
-            "section": "Usage",
-            "path": os.path.join(root, "docs", "USER_GUIDE.md"),
-            "summary": "Operator guide for build flows and outputs.",
+        "cloud_deploy": {
+            "title": "Cloud Deployment",
+            "section": "Setup",
+            "path": os.path.join(root, "docs", "CLOUD_DEPLOY.md"),
+            "summary": "Deploy AgentIC on HuggingFace Spaces or any cloud.",
         },
     }
 

web/src/components/StageProgressBar.tsx

@@ -17,6 +17,27 @@ const STAGES = [
     { key: 'SIGNOFF', label: 'Signoff' },
 ];
 
+// Brief, encouraging descriptions shown when a stage is active or just completed
+const STAGE_DESCRIPTIONS: Record<string, string> = {
+    INIT:              'Setting up build context',
+    SPEC:              'Translating your idea into chip spec',
+    RTL_GEN:           'Writing synthesizable Verilog',
+    RTL_FIX:           'Resolving any RTL issues',
+    VERIFICATION:      'Running simulation testbench',
+    FORMAL_VERIFY:     'Proving correctness mathematically',
+    COVERAGE_CHECK:    'Checking test coverage',
+    REGRESSION:        'Running regression suite',
+    SDC_GEN:           'Generating timing constraints',
+    FLOORPLAN:         'Laying out chip floorplan',
+    HARDENING:         'Physical design & routing',
+    CONVERGENCE_REVIEW:'Checking timing convergence',
+    ECO_PATCH:         'Patching for final sign-off',
+    SIGNOFF:           'Final LVS/DRC checks',
+};
+
+// Key milestones displayed with a special accent in the sidebar
+const MILESTONES = new Set(['RTL_GEN', 'VERIFICATION', 'HARDENING', 'SIGNOFF']);
+
 interface Props {
     currentStage: string;
     completedStages: Set<string>;
@@ -42,6 +63,7 @@ export const StageProgressBar: React.FC<Props> = ({
                     const isFailed = stage.key === failedStage;
                     const isWaiting = isCurrent && waitingForApproval;
                     const isSkipped = skippedStages?.has(stage.key) && !isCompleted && !isCurrent && !isFailed;
+                    const isMilestone = MILESTONES.has(stage.key);
 
                     let status = 'pending';
                     if (isSkipped) status = 'skipped';
@@ -50,8 +72,13 @@ export const StageProgressBar: React.FC<Props> = ({
                     if (isWaiting) status = 'waiting';
                     if (isFailed) status = 'failed';
 
+                    const showDesc = (isCurrent || isCompleted) && !isSkipped && !isFailed;
+
                     return (
-                        <div key={stage.key} className={`hitl-sidebar-stage hitl-stage--${status}`}>
+                        <div
+                            key={stage.key}
+                            className={`hitl-sidebar-stage hitl-stage--${status}${isMilestone ? ' hitl-stage--milestone' : ''}`}
+                        >
                             <div className="hitl-sidebar-indicator">
                                 {isCompleted && (
                                     <svg width="14" height="14" viewBox="0 0 14 14" fill="none">
@@ -75,7 +102,17 @@ export const StageProgressBar: React.FC<Props> = ({
                                     <span className="hitl-sidebar-dot-empty" />
                                 )}
                             </div>
-                            <span className="hitl-sidebar-stage-name">{stage.label}</span>
+                            <div className="hitl-sidebar-stage-info">
+                                <span className="hitl-sidebar-stage-name">{stage.label}</span>
+                                {showDesc && (
+                                    <span className="hitl-sidebar-stage-desc">
+                                        {STAGE_DESCRIPTIONS[stage.key]}
+                                    </span>
+                                )}
+                            </div>
+                            {isMilestone && isCompleted && (
+                                <span className="hitl-sidebar-milestone-dot" title="Milestone reached" />
+                            )}
                         </div>
                     );
                 })}

web/src/hitl.css

@@ -377,7 +377,7 @@
 
 .hitl-sidebar-stage {
   display: flex;
-  align-items: center;
+  align-items: flex-start;
   gap: 0.625rem;
   padding: 0.4375rem 1.25rem;
   border-left: 2px solid transparent;
@@ -391,6 +391,7 @@
   align-items: center;
   justify-content: center;
   flex-shrink: 0;
+  margin-top: 0.125rem;
 }
 
 .hitl-sidebar-dot-empty {
@@ -415,6 +416,45 @@
   transition: color 150ms;
 }
 
+/* Stage info wrapper (name + description) */
+.hitl-sidebar-stage-info {
+  display: flex;
+  flex-direction: column;
+  gap: 0.1rem;
+  min-width: 0;
+  flex: 1;
+}
+
+.hitl-sidebar-stage-desc {
+  font-size: 0.6875rem;
+  color: var(--text-tertiary);
+  opacity: 0.7;
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  line-height: 1.3;
+}
+
+/* Milestone dot badge (gold star after milestone stages complete) */
+.hitl-sidebar-milestone-dot {
+  width: 6px;
+  height: 6px;
+  border-radius: 50%;
+  background: #f6ad55;
+  flex-shrink: 0;
+  box-shadow: 0 0 4px rgba(246,173,85,0.6);
+}
+
+/* Milestone stage: subtly bolder left bar on active */
+.hitl-stage--milestone.hitl-stage--active {
+  border-left-color: #f6ad55;
+}
+
+/* Stage completion flash for milestone stages */
+.hitl-stage--milestone.hitl-stage--completed .hitl-sidebar-stage-name {
+  color: var(--text-secondary);
+}
+
 /* Stage status modifiers */
 .hitl-stage--completed .hitl-sidebar-stage-name {
   color: var(--text-secondary);
@@ -438,6 +478,70 @@
   font-weight: 500;
 }
 
+/* Milestone toast ─────────────────────────────────────────────────── */
+.hitl-milestone-toast {
+  position: absolute;
+  top: 0.875rem;
+  right: 1rem;
+  z-index: 50;
+  display: flex;
+  align-items: flex-start;
+  gap: 0.625rem;
+  background: var(--bg-card, #1a1917);
+  border: 1px solid rgba(246,173,85,0.35);
+  border-left: 3px solid #f6ad55;
+  border-radius: 8px;
+  padding: 0.625rem 0.875rem;
+  min-width: 240px;
+  max-width: 320px;
+  box-shadow: 0 8px 24px rgba(0,0,0,0.4);
+  cursor: pointer;
+  animation: hitl-toast-in 280ms cubic-bezier(0.22,1,0.36,1) both;
+}
+
+@keyframes hitl-toast-in {
+  from { opacity: 0; transform: translateX(16px); }
+  to   { opacity: 1; transform: translateX(0); }
+}
+
+.hitl-milestone-toast-icon {
+  font-size: 0.875rem;
+  color: #f6ad55;
+  flex-shrink: 0;
+  padding-top: 0.06rem;
+}
+
+.hitl-milestone-toast-body {
+  display: flex;
+  flex-direction: column;
+  gap: 0.1875rem;
+  flex: 1;
+  min-width: 0;
+}
+
+.hitl-milestone-toast-title {
+  font-size: 0.8125rem;
+  font-weight: 600;
+  color: var(--text-primary, #e8e5e0);
+}
+
+.hitl-milestone-toast-msg {
+  font-size: 0.75rem;
+  color: var(--text-secondary, #9a9590);
+  line-height: 1.45;
+}
+
+.hitl-milestone-toast-close {
+  background: none;
+  border: none;
+  font-size: 0.9rem;
+  color: var(--text-tertiary);
+  cursor: pointer;
+  padding: 0;
+  flex-shrink: 0;
+  line-height: 1;
+}
+
 .hitl-stage--failed {
   border-left-color: var(--red);
 }

web/src/pages/HumanInLoopBuild.tsx

@@ -13,6 +13,32 @@ const PIPELINE_STAGES = [
 ];
 const TOTAL = PIPELINE_STAGES.length;
 
+// Contextual messages for the bottom status bar — what the agent is doing right now
+const STAGE_ENCOURAGEMENTS: Record<string, string> = {
+    INIT:              'Setting up your build environment…',
+    SPEC:              'Translating your description into a chip specification…',
+    RTL_GEN:           'Writing Verilog — your chip is taking shape…',
+    RTL_FIX:           'Fixing any RTL issues automatically…',
+    VERIFICATION:      'Running simulation — making sure your logic is correct…',
+    FORMAL_VERIFY:     'Proving your chip is correct with formal methods…',
+    COVERAGE_CHECK:    'Measuring how thoroughly the tests cover your design…',
+    REGRESSION:        'Running the full regression suite…',
+    SDC_GEN:           'Generating timing constraints for physical design…',
+    FLOORPLAN:         'Planning the physical layout of your chip…',
+    HARDENING:         'Running place-and-route — turning RTL into real silicon…',
+    CONVERGENCE_REVIEW:'Checking that timing is met across all corners…',
+    ECO_PATCH:         'Applying final tweaks for clean sign-off…',
+    SIGNOFF:           'Almost there — running final LVS/DRC checks…',
+};
+
+// Milestone stages that deserve a special celebration toast
+const MILESTONE_TOASTS: Record<string, { title: string; msg: string }> = {
+    RTL_GEN:   { title: 'RTL Complete', msg: 'Your chip can now run instructions. Verilog is ready.' },
+    VERIFICATION: { title: 'Verification Passed', msg: 'All simulation tests passed. Design is logically correct.' },
+    HARDENING: { title: 'Silicon Layout Done', msg: 'Place-and-route complete. Your chip has a physical form.' },
+    SIGNOFF:   { title: 'Chip Signed Off', msg: 'All checks passed. Ready for tape-out.' },
+};
+
 // Human-readable stage names
 const STAGE_LABELS: Record<string, string> = {
     INIT: 'Initialization', SPEC: 'Specification', RTL_GEN: 'RTL Generation',
@@ -121,6 +147,10 @@ export const HumanInLoopBuild = () => {
     // Thinking indicator (Improvement 1)
     const [thinkingData, setThinkingData] = useState<{ agent_name: string; message: string } | null>(null);
 
+    // Milestone toast: shown briefly when a key stage completes
+    const [milestoneToast, setMilestoneToast] = useState<{ title: string; msg: string } | null>(null);
+    const milestoneTimerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+
     useEffect(() => {
         if (prompt.length > 8) {
             setDesignName(slugify(prompt));
@@ -297,6 +327,13 @@ export const HumanInLoopBuild = () => {
                 next.add(approvalData.stage_name);
                 return next;
             });
+            // Fire milestone toast if this is a key stage
+            const toast = MILESTONE_TOASTS[approvalData.stage_name];
+            if (toast) {
+                if (milestoneTimerRef.current) clearTimeout(milestoneTimerRef.current);
+                setMilestoneToast(toast);
+                milestoneTimerRef.current = setTimeout(() => setMilestoneToast(null), 5000);
+            }
         } catch (e: any) {
             setError(e?.response?.data?.detail || 'Failed to approve');
         }
@@ -571,6 +608,18 @@ export const HumanInLoopBuild = () => {
                         </div>
                     </header>
 
+                    {/* Milestone celebration toast */}
+                    {milestoneToast && (
+                        <div className="hitl-milestone-toast" onClick={() => setMilestoneToast(null)}>
+                            <span className="hitl-milestone-toast-icon">✦</span>
+                            <div className="hitl-milestone-toast-body">
+                                <span className="hitl-milestone-toast-title">{milestoneToast.title}</span>
+                                <span className="hitl-milestone-toast-msg">{milestoneToast.msg}</span>
+                            </div>
+                            <button className="hitl-milestone-toast-close">×</button>
+                        </div>
+                    )}
+
                     {/* Body: sidebar + main */}
                     <div className="hitl-build-body">
                         <StageProgressBar
@@ -598,8 +647,13 @@ export const HumanInLoopBuild = () => {
                     <footer className="hitl-bottombar">
                         <span className="hitl-bottombar-msg">
                             {thinkingData && <span className="hitl-thinking-pulse" />}
-                            {waitingForApproval ? 'Awaiting approval' : thinkingData ? thinkingData.message : 'Building autonomously'} · Step {stepNum} of {TOTAL}
-                            {estMinutes > 0 ? ` · ~${estMinutes} min remaining` : ''}
+                            {waitingForApproval
+                                ? 'Your review is needed — inspect the stage output above'
+                                : thinkingData
+                                    ? thinkingData.message
+                                    : (STAGE_ENCOURAGEMENTS[currentStage] || 'Building autonomously…')}
+                            {' · '}{pct}% complete
+                            {estMinutes > 0 ? ` · ~${estMinutes} min left` : ''}
                         </span>
                         <div className="hitl-bottombar-progress">
                             <div className="hitl-bottombar-track">