Resolve #5

.claude/commands/review.md

@@ -0,0 +1,20 @@
+Review my staged and unstaged changes before committing:
+
+**CRITICAL: NEVER stage changes with `git add` and NEVER commit changes with `git commit`. This is a review-only command.**
+
+1. Run `git diff` and `git diff --staged` to see all changes
+2. Read the relevant rules from `.claude/rules/` (e.g., `react.md` for .tsx files, `typescript.md` for .ts files, `rust.md` for .rs files)
+3. For each changed file:
+   - Summarize what changed
+   - Check for potential issues (bugs, security, performance)
+   - Verify it follows the rules in `.claude/rules/`
+4. Give me a brief summary:
+   - What's good
+   - Any concerns or suggestions
+   - Ready to commit? (yes/no with reason)
+5. Suggest a commit message:
+   - Extract issue number from branch name (e.g., `3-focuscat-poc` → `#3`)
+   - Format: `#<issue> <short description>`
+   - Keep it concise (50 chars or less)
+
+Keep the review concise and actionable.

.claude/rules

@@ -0,0 +1 @@
+../.cursor/rules

.cursor/rules/comments.mdc

@@ -0,0 +1,191 @@
+---
+description: Comment guidelines for clear, valuable code documentation
+globs: ["**/*.rs", "**/*.ts", "**/*.tsx"]
+alwaysApply: true
+---
+
+# Comment Guidelines
+
+The goal is balance: enough signposts to navigate, not so many that they become noise.
+
+## Core Principles
+
+- **Value-Driven** - Always ask "Does this help the next reader?"
+- **Long-Term** - Comments should still be useful in weeks or months. Prefer explaining *what exists and why* (constraints, tradeoffs, environment). Avoid comments that only make sense during the current task or refactor.
+- **Balanced** - Never over-comment obvious code, never under-comment complex logic.
+- **Context over history** - Document the design and its reasons, not the change you just made or alternatives you rejected (unless that explains a non-obvious constraint).
+
+## What TO Comment
+
+### Section Headers
+Short labels to help readers skim longer functions.
+
+✅ Good:
+```rust
+// Validate input
+...
+
+// Process data
+...
+
+// Save results
+...
+```
+
+❌ Bad:
+```rust
+// This section validates the input by checking all required fields
+...
+```
+
+### WHY Comments
+Explain non-obvious constraints or tradeoffs. Place them next to the code they explain (e.g. above the function or block), not floating near unrelated declarations. Use "do X so that Y" (what the code does and what problem it solves), not "we chose X over Y."
+
+✅ Good (states the reason something is done):
+```rust
+// Validate here; caller may be untrusted.
+let input = parse(raw)?;
+```
+
+✅ Good (constraint or tradeoff):
+```typescript
+// Process in batches so we stay under the rate limit.
+for (const chunk of chunks(data, 100)) {
+  await submit(chunk);
+}
+```
+
+❌ Bad (restates the operation, no why):
+```rust
+// Insert into database
+db.insert(...).await;
+```
+
+### Domain Logic
+Explain business rules that need context.
+
+✅ Good:
+```rust
+// Overtime = time beyond planned (base + extensions)
+let overtime = actual.saturating_sub(planned + extended);
+```
+
+### Thresholds and Config Values
+Explain what a value means, not its literal value. Document on props/parameters.
+
+✅ Good:
+```typescript
+interface TProps {
+    /** Minimum size (px) for element to be visible */
+    minSizePx?: number;
+}
+```
+
+❌ Bad:
+```typescript
+interface TProps {
+    minSizePx?: number; // 8
+}
+```
+
+### Data State Documentation
+Document non-obvious data states.
+
+✅ Good:
+```rust
+/// Insert new record (ended_at is NULL until complete).
+pub async fn insert(...) -> Result<i64>
+```
+
+❌ Bad:
+```rust
+/// Insert a new record into the database.
+pub async fn insert(...) -> Result<i64>
+```
+
+## What NOT TO Comment
+
+### Restating Code
+Never restate what the code literally does.
+
+✅ Good - Intent helps readers skim:
+```typescript
+if (current == null || current.id !== id) {
+    // Start new group
+    ...
+} else {
+    // Extend current group
+    ...
+}
+```
+
+❌ Bad - Restates mechanics:
+```rust
+// Get the timer
+let timer = state.lock();
+
+// Loop through items
+for item in items {
+
+// Check if null or id different
+if (current == null || current.id !== id) {
+```
+
+### Session Rationale and Bloat
+Never document design choices that only matter during the current refactor or agent session. Comments that explain "what we changed," "what we didn't use," or "why we chose X over Y" (without a lasting constraint) become noise once the change is done.
+
+❌ Bad (documents what's NOT there):
+```typescript
+// We don't validate here; that's done in the parent.
+```
+
+❌ Bad (only relevant during this refactor/session):
+```typescript
+// Changed from string to enum for type safety
+```
+
+❌ Bad (choice without lasting reason; doesn't help in 6 months):
+```typescript
+// We use a queue here because we tried direct calls but had race conditions.
+```
+Rewrite to state the lasting reason only.
+
+✅ Good (what exists and why, long-term):
+```typescript
+// Use a queue so events are processed in order and we avoid races.
+```
+
+### Em Dashes
+Never use em dashes (—) in comments. Use commas, semicolons, or plain sentences instead.
+
+### Type Information
+Never restate what types already document.
+
+✅ Good:
+```rust
+// Unix timestamp in seconds
+let timestamp: i64 = row.get("created_at");
+```
+
+❌ Bad:
+```rust
+// The ID as an integer
+let id: i64 = row.get("id");
+```
+
+## Before Adding a Comment
+
+- **Would a reader in 6 months benefit?** If the comment only explains "what we changed" or "what we considered," rewrite it to describe *what the code does and why* (constraint, tradeoff, rule), or omit it.
+- **Is it next to the code it explains?** WHY and context comments belong above the block or function they describe, not on unrelated fields or earlier in the file.
+
+## Language Specifics
+
+### Rust
+- `//` for inline comments
+- `///` for doc comments (only when adding value)
+- `// MARK: -` for IDE navigation (sparingly)
+
+### TypeScript
+- `//` for inline comments
+- `/** */` for JSDoc (only when adding value)
+- `// MARK: -` for IDE navigation (sparingly)