docs: comprehensive README restructure with improved demos

[t1mmen]

User description

Summary

• Restructured README with clearer hierarchy and improved diff comparison table
• Reorganized demo assets to assets/ and tape files to scripts/
• Fixed WIP template display in build output (sorted to bottom with "promote to build" hint)
• Fixed watch mode event stacking and old entry dimming

README Changes

• Structure: Why → Core Idea → Diff Problem → How To Use It
• Diff comparison: Side-by-side table showing "Without srtd" vs "With srtd"
• Simplified: Replaced Mermaid diagrams with concise bash examples
• Origin story: Restored HN links and Timely/Memory Engine references
• Claude Code: Simplified to single sentence with skill/rule links

Demo Assets

Before	After
readme-demo.gif	assets/demo.gif
readme-workflow-demo.gif	assets/workflow-demo.gif
readme-demo.tape	scripts/demo.tape
readme-workflow-demo.tape	scripts/workflow-demo.tape
-	assets/watch-demo.gif
-	scripts/watch-demo.tape
-	scripts/queue_template_edits.sh

CLI Improvements

• WIP templates sorted to bottom in srtd build output
• Added italic "promote to build" hint for WIP templates
• Watch mode: changed→applied events deduplicated
• Watch mode: entries >1min now dimmed

Test plan

• Verify README renders correctly on GitHub
• Verify GIFs display properly
• Run srtd build with WIP template to confirm sorting/hint
• Run srtd watch to confirm event stacking and dimming

🤖 Generated with Claude Code

---

PR Type

Enhancement, Documentation

---

Description

• Restructured README with clearer hierarchy and improved demos

• Fixed watch mode event stacking to show only applied actions

• WIP templates now sorted to bottom in build output with promotion hint

• Old entries (>1min) dimmed in watch mode for better visual hierarchy

• Reorganized demo assets to assets/ and tape files to scripts/

---

Diagram Walkthrough

flowchart LR
  A["Watch Mode Events"] -->|"changed→applied"| B["Stack Results"]
  B -->|"Show only applied"| C["Simplified Display"]
  D["Build Output"] -->|"Sort WIP to bottom"| E["Better Focus"]
  E -->|"Add promotion hint"| F["Clearer UX"]
  G["Old Entries >1min"] -->|"Dim in watch"| H["Visual Hierarchy"]
  I["README"] -->|"Restructure sections"| J["Clearer Navigation"]
  J -->|"Add diff comparison"| K["Better Documentation"]

Loading

File Walkthrough

	Relevant files
Documentation	2 files README.md Comprehensive README restructure with improved organization +217/-107 watch-demo.tape New watch mode demo with JSON streaming showcase                  +53/-0
Bug fix	1 files watch.ts Simplify event stacking to show only applied status            +9/-14
Enhancement	2 files resultsTable.ts Add recency-based dimming and WIP promotion hint                  +38/-12  queue_template_edits.sh New helper script for queuing template edits                          +33/-0
Tests	1 files watch.test.ts Update tests for simplified event stacking logic                  +6/-5
Configuration changes	2 files demo.tape Update output path to assets directory                                      +1/-1      workflow-demo.tape Update output path and typing speed for SQL                            +4/-4
Miscellaneous	4 files .srtd.buildlog.json Update build log with new experiment template                        +6/-1      .buildlog.local.json Update local build log with experiment entry                          20251231023252_srtd-srtd_demo_greet.sql New generated migration for greeting function                        +24/-0    20251231023406_srtd-experiment.sql New generated migration for experiment function                    +12/-0
Additional files	1 files screenshot.tape [link]

---

[changeset-bot]

⚠️ No Changeset found

Latest commit: 768e2ee

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[qodo-free-for-open-source-projects]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Cross-platform compatibility issue Description: Shell script uses sed -i with empty string backup extension on macOS (sed -i ''), which will fail on Linux systems where the syntax differs, and executes background processes without proper error handling or validation of file existence before modification. queue_template_edits.sh [1-33] Referred Code #!/bin/bash # Queue template edits with delays for demo purposes # Usage: ./scripts/queue_template_edits.sh <template-name> [num-edits] [delay-ms] [initial-delay-ms] TEMPLATE_NAME=${1:-srtd_demo_greet.sql} NUM_EDITS=${2:-3} DELAY_MS=${3:-2000} INITIAL_DELAY_MS=${4:-3000} DELAY_S=$(echo "scale=2; $DELAY_MS / 1000" | bc) INITIAL_S=$(echo "scale=2; $INITIAL_DELAY_MS / 1000" | bc) TEMPLATE="supabase/migrations-templates/$TEMPLATE_NAME" GREETINGS=("Hello" "Hey" "Howdy" "Greetings" "Hi" "Yo" "Hola" "Aloha") echo "Queuing $NUM_EDITS edits to $TEMPLATE_NAME" echo " First in ${INITIAL_S}s, then every ${DELAY_S}s" echo " Hello → Hey → Howdy → Greetings" CURRENT="Hello" for ((i=1; i<=NUM_EDITS; i++)); do ... (clipped 12 lines)
Ticket Compliance
⚪	🎫 No ticket provided Create ticket/issue
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-free-for-open-source-projects]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Improve script portability across operating systems Improve the portability of the demo script by modifying the sed command to be compatible with both GNU and BSD versions, ensuring it runs correctly on Linux and macOS. scripts/queue_template_edits.sh [28-31] ( sleep $WAIT - sed -i '' "s/$CURRENT/$NEXT/" "$TEMPLATE" + sed -i.bak "s/$CURRENT/$NEXT/" "$TEMPLATE" && rm "${TEMPLATE}.bak" ) & Apply / Chat Suggestion importance[1-10]: 5 __ Why: The suggestion correctly identifies a portability issue with the sed command between macOS and Linux systems and provides a standard, cross-compatible solution for this helper script.	Low
Update

[codecov]

Codecov Report

❌ Patch coverage is 94.73684% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 80.17%. Comparing base (7a7eeb8) to head (768e2ee).
⚠️ Report is 1 commits behind head on main.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
src/ui/resultsTable.ts	93.75%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #65      +/-   ##
==========================================
+ Coverage   80.00%   80.17%   +0.16%     
==========================================
  Files          46       46              
  Lines        2221     2229       +8     
  Branches      546      551       +5     
==========================================
+ Hits         1777     1787      +10     
+ Misses        444      442       -2     

Flag	Coverage Δ
e2e	80.17% <94.73%> (+0.16%)	⬆️
unittests	80.17% <94.73%> (+0.16%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.