update

ASG_Framework.md

@@ -625,9 +625,12 @@ Describe the high-level approach to solving the problem.
 
 Explain the design reasoning behind each major decision — why the solution was designed this way, and how each decision connects to form a cohesive approach that solves the user problem.
 
+| Decision ID | Decision | Rationale | Alternatives Rejected |
+|-------------|----------|-----------|----------------------|
 | Decision ID | Decision | Rationale | Alternatives Rejected |
 |-------------|----------|-----------|----------------------|
 | SD-001 | Use NATS for async messaging | Required for real-time messaging with low overhead | Kafka - too complex for current scale |
+| SD-001.1 | NATS subject naming | Use `catalog:updates` for inventory changes | Static polling |
 | SD-002 | Use WebSockets for real-time updates | Required for <100ms feedback | REST polling - too slow, too many requests |
 | SD-003 | Store comparison list in localStorage | Allows offline comparison editing | Redux - overkill for this feature |
 | SD-004 | Server-side rendering for comparison view | SEO for comparison pages shared via unique links | Client-side rendering - no SEO benefit |
@@ -681,6 +684,161 @@ Link each solution component to specific requirements and assign Solution Design
 | Export comparison | FR-201 | SD-005 | Export comparison to PDF/CSV (uses server-side rendering) |
 
 
+### Walkthrough Template
+
+```markdown
+# Walkthrough: Feature Name
+
+## Structural Guidance
+
+- One **overview sequence diagram** per participant (high-level flow, all major steps)
+- **Detailed sub-diagrams** for complex interaction points (e.g., multi-step checkout, validation error paths)
+- Use sequence diagrams for request/response patterns; use state machine diagrams for multi-participant state transitions
+
+---
+
+## Customer
+
+### Session Start
+
+**WT-001**: User opens app, navigates to `/compare`
+
+> Cross-reference: `2-solution_design.md:SD-004` (SSR for SEO-friendly comparison links)
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant User as Customer (Browser)
+    participant UI as SvelteKit SSR
+    participant WineAPI as Wine Service
+
+    User->>UI: GET /compare
+    UI->>WineAPI: Get wine list
+    WineAPI-->>UI: JSON response
+    UI-->>User: Rendered HTML
+```
+
+---
+
+### Select Wines for Comparison
+
+**WT-002**: User selects 3 wines from inventory table
+
+| Step | Action | System Response | Traceability |
+|------|--------|-----------------|--------------|
+| WT-002.1 | Clicks "Add to Compare" on Wine A | Adds to localStorage comparison array | FR-101, SD-003 |
+| WT-002.2 | Clicks "Add to Compare" on Wine B | Adds to array, updates sidebar count | FR-101, SD-003 |
+| WT-002.3 | Clicks "Add to Compare" on Wine C | Adds to array, triggers comparison preview | FR-101, SD-003 |
+
+**WT-003**: Comparison preview renders with selected wines
+
+> Cross-reference: `5-ui_specification.md:UI-002` (Wine Table)
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as StateStore
+    participant Sidebar as ComparisonSidebar
+
+    User->>UI: addToCompare(wine)
+    UI->>Sidebar: emit 'comparison:updated'
+    Sidebar->>Sidebar: Render preview (3 wines)
+    Sidebar-->>User: Visual feedback
+```
+
+---
+
+### Edit Wine Details
+
+**WT-004**: User modifies price or notes for a selected wine
+
+> Cross-reference: `2-solution_design.md:SD-003` (localStorage storage)
+
+**WT-005**: User clicks "Save Changes"
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as FormComponent
+    participant Local as localStorage
+    participant Backend as WineAPI
+
+    User->>UI: Edit form fields
+    UI->>Local: Update cached values
+    User->>UI: Click Save
+    UI->>Backend: PUT /api/v1/wine/:id
+    Backend-->>UI: 200 OK
+    UI-->>User: Confirmation toast
+```
+
+---
+
+### Error Paths
+
+**WT-006**: Backend rejects edit (validation error)
+
+> Same participant POV — shows rejection from customer's perspective
+
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as FormComponent
+    participant Backend as WineAPI
+
+    User->>UI: Click Save
+    UI->>Backend: PUT /api/v1/wine/:id
+    Backend-->>UI: 422 Unprocessable Entity
+    UI->>UI: Render field-level errors
+    UI-->>User: "Price must be numeric" inline message
+```
+
+**WT-007**: User clears comparison list
+
+> See Retailer section step 4.2 — retailer sees updated catalog
+
+```mermaid
+sequenceDiagram
+    participant User as Customer
+    participant UI as StateStore
+    participant Local as localStorage
+
+    User->>UI: Click "Clear All"
+    UI->>Local: Set comparison = []
+    Local-->>UI: Confirm write
+    UI-->>User: Sidebar collapses
+```
+
+---
+
+## Retailer
+
+### Receive Updated Catalog
+
+**WT-008**: Retailer views updated wine inventory
+
+> Cross-reference: `3-walkthrough.md:#Customer` (WT-005 save event triggers notification)
+
+**Sequence**:
+```mermaid
+sequenceDiagram
+    participant Retailer as Retailer Dashboard
+    participant Nats as NATS Bridge
+    participant Backend as WineService
+
+    Retailer->>Nats: Listen to catalog:updates
+    Backend-->>Nats: catalog:updated {wine_ids:[...]}
+    Nats-->>Retailer: Push notification
+    Retailer->>Retailer: Refresh inventory table
+```
+
+> Cross-reference: `2-solution_design.md:SD-001` (NATS async messaging)
+
+---
+
+```
+
 ### Specification Template
 
 ```yaml