Merge pull request #324 from forecast-bio/release/v0.5.0

Release v0.5.0

Author: maxine-at-forecast

.claude/settings.json

@@ -15,6 +15,15 @@
           }
         ],
         "matcher": "Write|Edit"
+      },
+      {
+        "hooks": [
+          {
+            "command": "HOOK=\"$(git rev-parse --show-toplevel 2>/dev/null)/.claude/hooks/heartbeat.py\"; if [ -f \"$HOOK\" ]; then python3 \"$HOOK\"; else exit 0; fi",
+            "timeout": 3,
+            "type": "command"
+          }
+        ]
       }
     ],
     "PreToolUse": [

.crosslink/.gitignore

@@ -2,8 +2,19 @@
 agent.json
 .hub-cache/
 .knowledge-cache/
+.cache/
 keys/
 integrations/
 
-# Machine-local hook overrides
+# Machine-local state
+issues.db
+issues.db-wal
+issues.db-shm
+session.json
+daemon.pid
+daemon.log
+last_test_run
+
+# Machine-local overrides
 hook-config.local.json
+rules.local/

.crosslink/hook-config.json

@@ -1,52 +1,37 @@
 {
-  "allowed_bash_prefixes": [
-    "crosslink ",
-    "git status",
-    "git diff",
-    "git log",
-    "git branch",
-    "git show",
-    "cargo test",
-    "cargo build",
-    "cargo check",
-    "cargo clippy",
-    "cargo fmt",
-    "npm test",
-    "npm run",
-    "npx ",
-    "tsc",
-    "node ",
-    "python ",
-    "ls",
-    "dir",
-    "pwd",
-    "echo"
-  ],
+  "tracking_mode": "strict",
+  "intervention_tracking": true,
+  "cpitd_auto_install": true,
+  "comment_discipline": "encouraged",
+  "kickoff_verification": "local",
+  "signing_enforcement": "audit",
+  "auto_steal_stale_locks": false,
   "blocked_git_commands": [
-    "git push",
-    "git merge",
-    "git rebase",
-    "git cherry-pick",
-    "git reset",
-    "git checkout .",
-    "git restore .",
-    "git clean",
-    "git stash",
-    "git tag",
-    "git am",
-    "git apply",
-    "git branch -d",
-    "git branch -D",
-    "git branch -m"
+    "git push", "git merge", "git rebase", "git cherry-pick",
+    "git reset", "git checkout .", "git restore .", "git clean",
+    "git stash", "git tag", "git am", "git apply",
+    "git branch -d", "git branch -D", "git branch -m"
   ],
-  "comment_discipline": "encouraged",
-  "cpitd_auto_install": true,
   "gated_git_commands": [
     "git commit"
   ],
-  "intervention_tracking": true,
-  "kickoff_verification": "local",
-  "reminder_drift_threshold": 5,
-  "signing_enforcement": "audit",
-  "tracking_mode": "strict"
+  "allowed_bash_prefixes": [
+    "crosslink ",
+    "git status", "git diff", "git log", "git branch", "git show",
+    "cargo test", "cargo build", "cargo check", "cargo clippy", "cargo fmt",
+    "npm test", "npm run", "npx ",
+    "tsc", "node ", "python ",
+    "ls", "dir", "pwd", "echo"
+  ],
+  "reminder_drift_threshold": 3,
+  "agent_overrides": {
+    "tracking_mode": "relaxed",
+    "blocked_git_commands": [
+      "git push --force", "git push -f",
+      "git reset --hard",
+      "git clean -f", "git clean -fd", "git clean -fdx",
+      "git checkout .", "git restore ."
+    ],
+    "gated_git_commands": []
+  }
 }

.crosslink/knowledge/forecast-visual-design-system.md

@@ -0,0 +1,113 @@
+# Forecast Visual Design System
+
+Reference for the Forecast brand visual language as implemented in crosslink docs and reusable across projects.
+
+## Brand Palette (from `_brand.yml`)
+
+| Name   | Hex       | Usage                                    |
+|--------|-----------|------------------------------------------|
+| Red    | `#F95838` | Primary accent, CTAs, crosslink branding |
+| Green  | `#007C35` | Success, agents, session markers         |
+| Blue   | `#00A6DB` | Links, info, agent identity              |
+| Yellow | `#FFCE02` | Warnings, highlights, knowledge          |
+| Pink   | `#FFB6C6` | Soft backgrounds, decorative             |
+| Grey   | `#ede2e4` | Confetti base (warm pinkish grey)        |
+| Bg     | `#F9F4F5` | Page background                          |
+
+## Typography
+
+- **Headings (h1)**: Helvetica, bold
+- **Subheadings (h2)**: Times New Roman, italic
+- **Body text**: Helvetica
+- **Code / slash-commands only**: IBM Plex Mono — never use mono for non-code text
+
+## Shape Vocabulary
+
+Shapes use only: ellipses, circles, rounded rectangles. No triangles or crescents.
+
+All shapes use `mix-blend-mode: multiply` — no alpha transparency on shapes. This creates the layered, overlapping Forecast look where colors interact.
+
+## Confetti Dots
+
+Small colored circles scattered as decorative accents, always with `mix-blend-mode: multiply`.
+
+### Color distribution (from forecast.bio homepage)
+
+Weighted random sampling matching the original site's `kConfetti` array:
+
+| Color       | Hex       | Weight | Probability |
+|-------------|-----------|--------|-------------|
+| Warm grey   | `#ede2e4` | 25     | 57%         |
+| Blue        | `#00A6DB` | 7      | 16%         |
+| Yellow      | `#FFCE02` | 6      | 14%         |
+| Pink        | `#FFB6C6` | 3      | 7%          |
+| Red         | `#F95838` | 3      | 7%          |
+
+Grey-dominant with colored accents. This keeps confetti subtle while the colored dots pop.
+
+### Static confetti (SVG diagrams)
+
+- Uniform radius (tunable via `CONFETTI_RADIUS` in `brand.py`, default: 5)
+- Wrapped in `<g style="mix-blend-mode: multiply">`
+- Uses solid brand colors only (red, green, blue, yellow, pink) — no grey in static diagrams
+
+### Animated confetti (footer JS)
+
+- 14 dots, 11px diameter
+- Positioned in a **cone shape** emanating up-right from the Forecast wordmark
+- Cone origin at logo baseline, slope drifts upward (-0.28 rise per px)
+- Spread grows with distance (cone half-angle 0.22)
+- Extra noise (±10px) on both axes for fuzzy edges
+- Fade in left-to-right on scroll (IntersectionObserver, 50ms stagger)
+- Random on every page load (`Math.random()`)
+
+## Diagram Generation Pipeline
+
+All diagrams generated programmatically via Python scripts in `scripts/`:
+
+- `scripts/brand.py` — shared module: palette, primitives, confetti, typography CSS
+- `scripts/generate-banner.py` — home page banner (1500×500)
+- `scripts/generate-diagram-*.py` — per-guide diagrams
+- `scripts/generate-card-icons.py` — 12 feature card icons (150×100 each)
+- `scripts/generate-all.sh` — regenerates everything
+
+### Diagram conventions
+
+- Sentence case titles (not Title Case)
+- Mono class only for actual code/commands
+- Subheading (Times italic) for secondary labels
+- Background: `#F9F4F5` (brand bg)
+- Confetti in top corners, 4-6 dots per cluster
+- Seeded RNG for reproducible output
+
+## Card Icons
+
+Small 2-4 shape compositions for feature cards, each evocative of the feature:
+- Session Memory: linked ellipses (continuity)
+- Local-First: stacked DB layers
+- Multi-Agent: triangle of overlapping circles
+- Hooks: tall rail with guided shape
+- Swarm: honeycomb cluster
+- Knowledge: fanned pages with search lens
+- TUI: terminal with content lines
+- Web Dashboard: browser with panels
+- Containers: nested boxes
+- Workflow: diagonal arrow flow
+- Maintenance: interlocking gears
+- Everywhere: dispersed shapes (breadth)
+
+## Footer
+
+Matches forecast.bio card pages:
+1. Thin rule (`#ede3e3`, 220px)
+2. Wordmark + animated confetti cone (same row, flex, aligned to baseline)
+3. Copyright notice (`© 2026 Forecast Bio, Inc. · Built with Quarto`)
+
+Footer is injected via `include-after-body` and JS-relocated into Quarto's `<main class="content">` for proper content-column alignment.
+
+## Quarto Layout
+
+- Two-column pattern: 35% / 5% spacer / 60% for chat-vs-command pages
+- `code-overflow: scroll` (not wrap)
+- `.column-page-right` on wider diagrams (>700px), wrapped in `:::` div fences
+- Full-width banner on index via CSS viewport breakout

.crosslink/rules/c.md

@@ -0,0 +1,43 @@
+### C Best Practices
+
+#### Memory Safety
+- Always check return values of malloc/calloc
+- Free all allocated memory (use tools like valgrind)
+- Initialize all variables before use
+- Use sizeof() with the variable, not the type
+
+```c
+// GOOD: Safe memory allocation
+int *arr = malloc(n * sizeof(*arr));
+if (arr == NULL) {
+    return -1;  // Handle allocation failure
+}
+// ... use arr ...
+free(arr);
+
+// BAD: Unchecked allocation
+int *arr = malloc(n * sizeof(int));
+arr[0] = 1;  // Crash if malloc failed
+```
+
+#### Buffer Safety
+- Always bounds-check array access
+- Use `strncpy`/`snprintf` instead of `strcpy`/`sprintf`
+- Validate string lengths before copying
+
+```c
+// GOOD: Safe string copy
+char dest[64];
+strncpy(dest, src, sizeof(dest) - 1);
+dest[sizeof(dest) - 1] = '\0';
+
+// BAD: Buffer overflow risk
+char dest[64];
+strcpy(dest, src);  // No bounds check
+```
+
+#### Security
+- Never use `gets()` (use `fgets()`)
+- Validate all external input
+- Use constant-time comparison for secrets
+- Avoid integer overflow in size calculations

.crosslink/rules/cpp.md

@@ -0,0 +1,39 @@
+### C++ Best Practices
+
+#### Modern C++ (C++17+)
+- Use smart pointers (`unique_ptr`, `shared_ptr`) over raw pointers
+- Use RAII for resource management
+- Prefer `std::string` and `std::vector` over C arrays
+- Use `auto` for complex types, explicit types for clarity
+
+```cpp
+// GOOD: Modern C++ with smart pointers
+auto config = std::make_unique<Config>();
+auto users = std::vector<User>{};
+
+// BAD: Manual memory management
+Config* config = new Config();
+// ... forgot to delete
+```
+
+#### Error Handling
+- Use exceptions for exceptional cases
+- Use `std::optional` for values that may not exist
+- Use `std::expected` (C++23) or result types for expected failures
+
+```cpp
+// GOOD: Optional for missing values
+std::optional<User> findUser(const std::string& id) {
+    auto it = users.find(id);
+    if (it == users.end()) {
+        return std::nullopt;
+    }
+    return it->second;
+}
+```
+
+#### Security
+- Validate all input boundaries
+- Use `std::string_view` for non-owning string references
+- Avoid C-style casts; use `static_cast`, `dynamic_cast`
+- Never use `sprintf`; use `std::format` or streams

.crosslink/rules/csharp.md

@@ -0,0 +1,51 @@
+### C# Best Practices
+
+#### Code Style
+- Follow .NET naming conventions (PascalCase for public, camelCase for private)
+- Use `var` when type is obvious from right side
+- Use expression-bodied members for simple methods
+- Enable nullable reference types
+
+```csharp
+// GOOD: Modern C# style
+public class UserService
+{
+    private readonly IUserRepository _repository;
+
+    public UserService(IUserRepository repository)
+        => _repository = repository;
+
+    public async Task<User?> GetUserAsync(string id)
+        => await _repository.FindByIdAsync(id);
+}
+```
+
+#### Error Handling
+- Use specific exception types
+- Never catch and swallow exceptions silently
+- Use `try-finally` or `using` for cleanup
+
+```csharp
+// GOOD: Proper async error handling
+public async Task<Result<User>> GetUserAsync(string id)
+{
+    try
+    {
+        var user = await _repository.FindByIdAsync(id);
+        return user is null
+            ? Result<User>.NotFound()
+            : Result<User>.Ok(user);
+    }
+    catch (DbException ex)
+    {
+        _logger.LogError(ex, "Database error fetching user {Id}", id);
+        throw;
+    }
+}
+```
+
+#### Security
+- Use parameterized queries (never string interpolation for SQL)
+- Validate all input with data annotations or FluentValidation
+- Use ASP.NET's built-in anti-forgery tokens
+- Store secrets in Azure Key Vault or similar