Merge pull request #16 from lambda-curry/feat/starter-improvements

Author: jaruesink

.beads/.gitignore

@@ -0,0 +1,44 @@
+# SQLite databases
+*.db
+*.db?*
+*.db-journal
+*.db-wal
+*.db-shm
+
+# Daemon runtime files
+daemon.lock
+daemon.log
+daemon.pid
+bd.sock
+sync-state.json
+last-touched
+
+# Local version tracking (prevents upgrade notification spam after git ops)
+.local_version
+
+# Legacy database files
+db.sqlite
+bd.db
+
+# Worktree redirect file (contains relative path to main repo's .beads/)
+# Must not be committed as paths would be wrong in other clones
+redirect
+
+# Merge artifacts (temporary files from 3-way merge)
+beads.base.jsonl
+beads.base.meta.json
+beads.left.jsonl
+beads.left.meta.json
+beads.right.jsonl
+beads.right.meta.json
+
+# Sync state (local-only, per-machine)
+# These files are machine-specific and should not be shared across clones
+.sync.lock
+sync_base.jsonl
+
+# NOTE: Do NOT add negation patterns (e.g., !issues.jsonl) here.
+# They would override fork protection in .git/info/exclude, allowing
+# contributors to accidentally commit upstream issue databases.
+# The JSONL files (issues.jsonl, interactions.jsonl) and config files
+# are tracked by git by default since no pattern above ignores them.

.beads/README.md

@@ -0,0 +1,81 @@
+# Beads - AI-Native Issue Tracking
+
+Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
+
+## What is Beads?
+
+Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
+
+**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
+
+## Quick Start
+
+### Essential Commands
+
+```bash
+# Create new issues
+bd create "Add user authentication"
+
+# View all issues
+bd list
+
+# View issue details
+bd show <issue-id>
+
+# Update issue status
+bd update <issue-id> --status in_progress
+bd update <issue-id> --status done
+
+# Sync with git remote
+bd sync
+```
+
+### Working with Issues
+
+Issues in Beads are:
+- **Git-native**: Stored in `.beads/issues.jsonl` and synced like code
+- **AI-friendly**: CLI-first design works perfectly with AI coding agents
+- **Branch-aware**: Issues can follow your branch workflow
+- **Always in sync**: Auto-syncs with your commits
+
+## Why Beads?
+
+✨ **AI-Native Design**
+- Built specifically for AI-assisted development workflows
+- CLI-first interface works seamlessly with AI coding agents
+- No context switching to web UIs
+
+🚀 **Developer Focused**
+- Issues live in your repo, right next to your code
+- Works offline, syncs when you push
+- Fast, lightweight, and stays out of your way
+
+🔧 **Git Integration**
+- Automatic sync with git commits
+- Branch-aware issue tracking
+- Intelligent JSONL merge resolution
+
+## Get Started with Beads
+
+Try Beads in your own projects:
+
+```bash
+# Install Beads
+curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
+
+# Initialize in your repo
+bd init
+
+# Create your first issue
+bd create "Try out Beads"
+```
+
+## Learn More
+
+- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
+- **Quick Start Guide**: Run `bd quickstart`
+- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
+
+---
+
+*Beads: Issue tracking that moves at the speed of thought* ⚡

.beads/config.yaml

@@ -0,0 +1,62 @@
+# Beads Configuration File
+# This file configures default behavior for all bd commands in this repository
+# All settings can also be set via environment variables (BD_* prefix)
+# or overridden with command-line flags
+
+# Issue prefix for this repository (used by bd init)
+# If not set, bd init will auto-detect from directory name
+# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
+# issue-prefix: ""
+
+# Use no-db mode: load from JSONL, no SQLite, write back after each command
+# When true, bd will use .beads/issues.jsonl as the source of truth
+# instead of SQLite database
+# no-db: false
+
+# Disable daemon for RPC communication (forces direct database access)
+# no-daemon: false
+
+# Disable auto-flush of database to JSONL after mutations
+# no-auto-flush: false
+
+# Disable auto-import from JSONL when it's newer than database
+# no-auto-import: false
+
+# Enable JSON output by default
+# json: false
+
+# Default actor for audit trails (overridden by BD_ACTOR or --actor)
+# actor: ""
+
+# Path to database (overridden by BEADS_DB or --db)
+# db: ""
+
+# Auto-start daemon if not running (can also use BEADS_AUTO_START_DAEMON)
+# auto-start-daemon: true
+
+# Debounce interval for auto-flush (can also use BEADS_FLUSH_DEBOUNCE)
+# flush-debounce: "5s"
+
+# Git branch for beads commits (bd sync will commit to this branch)
+# IMPORTANT: Set this for team projects so all clones use the same sync branch.
+# This setting persists across clones (unlike database config which is gitignored).
+# Can also use BEADS_SYNC_BRANCH env var for local override.
+# If not set, bd sync will require you to run 'bd config set sync.branch <branch>'.
+# sync-branch: "beads-sync"
+
+# Multi-repo configuration (experimental - bd-307)
+# Allows hydrating from multiple repositories and routing writes to the correct JSONL
+# repos:
+#   primary: "."  # Primary repo (where this database lives)
+#   additional:   # Additional repos to hydrate from (read-only)
+#     - ~/beads-planning  # Personal planning repo
+#     - ~/work-planning   # Work planning repo
+
+# Integration settings (access with 'bd config get/set')
+# These are stored in the database, not in this file:
+# - jira.url
+# - jira.project
+# - linear.url
+# - linear.api-key
+# - github.org
+# - github.repo

.beads/interactions.jsonl

@@ -0,0 +1,4 @@
+{
+  "database": "beads.db",
+  "jsonl_export": "issues.jsonl"
+}

.beads/issues.jsonl

@@ -0,0 +1,51 @@
+---
+description: Project overview and context for react-router-starter
+alwaysApply: true
+---
+
+# Project Context
+
+## What This Repo Is
+
+**react-router-starter** is a monorepo starter for React Router 7 apps with best practices from reportory: Storybook, @lambdacurry/forms, Vitest + React Testing Library, and shared Cursor rules.
+
+## Structure
+
+- **apps/todo-app** – Reference app (React Router 7, Vite, Tailwind v4, forms, Storybook, tests).
+- **packages/** – Shared packages (e.g. `@todo-starter/ui`, `@todo-starter/utils`) used by apps.
+- **.cursorrules/** – Cursor AI rules (project context, React Router, Storybook, forms, testing, monorepo, UI).
+
+## Issue Tracking
+
+This project uses **Beads (bd)** for issues. See `AGENTS.md` for workflow.
+
+```bash
+bd ready              # Find available work
+bd show <id>           # View issue details
+bd update <id> --status in_progress  # Claim work
+bd close <id>          # Complete work
+bd sync                # Sync with git
+```
+
+## Quality Gates (todo-app)
+
+From `apps/todo-app/package.json`:
+
+- **Test:** `npm run test:run` or `npm run test:ci` (Vitest)
+- **Lint:** `npm run lint` (Biome)
+- **Typecheck:** `npm run typecheck` (tsc)
+- **Build:** `npm run build` (react-router build)
+- **Storybook:** `npm run storybook` (dev), `npm run build-storybook` (build)
+
+Run these from `apps/todo-app` or via workspace root scripts if defined.
+
+## Conventions
+
+- **Routing:** File-based routes in `app/routes/`; use loaders/actions and route types.
+- **Forms:** @lambdacurry/forms + remix-hook-form + Zod; see `.cursorrules/lambda-curry-forms.mdc`.
+- **Tests:** Vitest + React Testing Library; use `renderWithRouter` for router-dependent components; see `apps/todo-app/TESTING.md` and `.cursorrules/testing-best-practices.mdc`.
+- **Styling:** Tailwind CSS v4; mobile-first; prefer existing UI components.
+
+## Rule Order
+
+Cursor rules in `.cursorrules/` are applied as configured. `00-project-context.mdc` is intended to load first (naming prefix) to establish project context; other rule files add domain-specific guidance (React Router, Storybook, forms, testing, monorepo, UI).

.beads/metadata.json

@@ -1,59 +1,19 @@
 ---
+description: React Router 7 routing, loaders, actions, and component patterns
+globs: apps/**/app/routes/**/*.tsx, apps/**/app/**/*.tsx
 alwaysApply: true
 ---
 
 # React Router 7 Cursor Rules
 
 ## Route Structure
-- Use file-based routing in `app/routes/`
-- Route files should export default component and optional meta, loader, action functions
-- Use `+types` for route-specific TypeScript types
-
-## Component Patterns
-```tsx
-// Route component example
-import type { Route } from './+types/home';
-
-export const meta: Route.MetaFunction = () => {
-  return [
-    { title: 'Page Title' },
-    { name: 'description', content: 'Page description' }
-  ];
-};
-
-export default function Home() {
-  return <div>Content</div>;
-}
-```
-
-## Data Loading
-- Use loaders for server-side data fetching
-- Use actions for form submissions and mutations
-- Prefer server-side data loading over client-side when possible
 
-## Error Handling
-- Implement ErrorBoundary components for route-level error handling
-- Use isRouteErrorResponse for proper error type checking
-
-## Navigation
-- Use Link component for internal navigation
-- Use NavLink for navigation with active states
-- Prefer declarative navigation over imperative
-
-## Best Practices
-- Keep route components focused on layout and data orchestration
-- Extract business logic into custom hooks or utilities
-- Use proper TypeScript types from route type definitions
-- Implement proper loading and error states
-
-# React Router 7 Cursor Rules
-
-## Route Structure
 - Use file-based routing in `app/routes/`
 - Route files should export default component and optional meta, loader, action functions
 - Use `+types` for route-specific TypeScript types
 
 ## Component Patterns
+
 ```tsx
 // Route component example
 import type { Route } from './+types/home';
@@ -71,22 +31,25 @@ export default function Home() {
 ```
 
 ## Data Loading
+
 - Use loaders for server-side data fetching
 - Use actions for form submissions and mutations
 - Prefer server-side data loading over client-side when possible
 
 ## Error Handling
+
 - Implement ErrorBoundary components for route-level error handling
 - Use isRouteErrorResponse for proper error type checking
 
 ## Navigation
+
 - Use Link component for internal navigation
 - Use NavLink for navigation with active states
 - Prefer declarative navigation over imperative
 
 ## Best Practices
+
 - Keep route components focused on layout and data orchestration
 - Extract business logic into custom hooks or utilities
 - Use proper TypeScript types from route type definitions
 - Implement proper loading and error states
-

.cursorrules/00-project-context.mdc

@@ -0,0 +1,53 @@
+---
+description: Storybook setup and patterns for React Router apps
+globs: apps/**/.storybook/**/*.ts, apps/**/.storybook/**/*.tsx, apps/**/*.stories.@(ts|tsx)
+alwaysApply: false
+---
+
+# Storybook Cursor Rules
+
+## Setup (todo-app)
+
+- **Framework:** `@storybook/react-vite` with Vite config from app root
+- **Stories:** `../app/**/*.stories.@(ts|tsx)`
+- **Addons:** `@storybook/addon-essentials`, `@storybook/addon-links`
+- **Config:** `main.ts` uses `viteFinal` to resolve `vite.config.ts` for path aliases and Tailwind
+
+## React Router in Storybook
+
+Components that use `Link`, `useNavigate`, `useFetcher`, or `useHref` need router context. Use a global decorator in `preview.tsx`:
+
+```tsx
+import type { ComponentType } from 'react';
+import { createMemoryRouter, RouterProvider } from 'react-router-dom';
+
+const withRouter = (Story: ComponentType) => {
+  const router = createMemoryRouter(
+    [{ path: '/', element: <Story /> }],
+    { initialEntries: ['/'] }
+  );
+  return <RouterProvider router={router} />;
+};
+
+const preview: Preview = {
+  decorators: [withRouter, withTodoProvider], // add app providers as needed
+  // ...
+};
+```
+
+## Patterns
+
+- **Single route:** One route with `element: <Story />` and `initialEntries: ['/']` (or desired path)
+- **App providers:** Add decorators for context providers (e.g. TodoProvider) so stories match app behavior
+- **Global styles:** Import app `globals.css` in `preview.tsx` so Tailwind and theme apply
+
+## Scripts
+
+- **Dev:** `npm run storybook` (port 6006)
+- **Build:** `npm run build-storybook` (static output for deployment)
+
+## Best Practices
+
+- Keep stories colocated with components (`component.stories.tsx`)
+- Use args and controls for props; use decorators for router and providers
+- Prefer one default export with a descriptive title; use named exports for variants