new workflows based on past issues

4 files changed, 137 insertions, 0 deletions

diff --git a/.agent/workflows/crank_but_verify.md b/.agent/workflows/crank_but_verify.md
new file mode 100644
index 0000000..8d983b6
--- /dev/null
+++ b/.agent/workflows/crank_but_verify.md
@@ -0,0 +1,16 @@
+---
+description: Turn the crank with Thicket - but *verify*
+---
+
+Your goal is to improve the project by resolving tickets and discovering additional work for future agents.
+
+1. Work on the ticket described by `thicket ready`.
+2. When resolved, run `thicket close <CURRENT_TICKET_ID>`.
+3. Verify your resolution by ensuring the project still builds cleanly and tests pass.
+4. Think of additional work and create tickets for future agents:
+   ```bash
+   thicket add --title "Brief descriptive title" --description "Detailed context" --priority=<N> --type=<TYPE> --created-from <CURRENT_TICKET_ID>
+   ```
+5. Commit your changes.
+
+**CRITICAL**: NEVER edit `.thicket/tickets.jsonl` directly. Always use the `thicket` CLI.
\ No newline at end of file
diff --git a/.agent/workflows/deploy-check.md b/.agent/workflows/deploy-check.md
new file mode 100644
index 0000000..51ab1ae
--- /dev/null
+++ b/.agent/workflows/deploy-check.md
@@ -0,0 +1,36 @@
+---
+description: Run tests in a safe, controlled manner to avoid VM crashes
+---
+
+Use this workflow to run tests with extra precautions, especially Playwright/E2E tests that have historical stability issues.
+1. **Pre-flight checks:**
+   ```bash
+   # Ensure clean environment
+   ./clean_test_env.sh
+   # Check for stray processes
+   ps aux | grep -E 'neko|playwright|chrome'
+   ```
+2. **Backend tests (Go):**
+   // turbo
+   ```bash
+   go test -v -timeout=5m ./...
+   ```
+3. **Frontend unit tests (Node):**
+   // turbo
+   ```bash
+   cd frontend && npm test -- --run
+   ```
+4. **E2E tests (Safe Wrapper):**
+   Use the safe wrapper script which handles timeouts and automatic cleanup.
+   ```bash
+   ./run_e2e_safe.sh
+   ```
+   
+   If E2E tests fail or hang:
+   - Check `backend.log` for server issues
+   - Run `./clean_test_env.sh` to reset the database and environment
+   - Create a ticket in Thicket for any flaky tests discovered
+5. **Report results:**
+   - Document any flaky tests in the relevant Thicket ticket
+   - Update the ticket with coverage information if applicable
+**CRITICAL**: NEVER run Playwright tests directly via `npm run test:e2e` if you are unsure of stability. Always use the `./run_e2e_safe.sh` wrapper.
diff --git a/.agent/workflows/test-safe.md b/.agent/workflows/test-safe.md
new file mode 100644
index 0000000..bba4adb
--- /dev/null
+++ b/.agent/workflows/test-safe.md
@@ -0,0 +1,42 @@
+---
+description: Run tests in a safe, controlled manner to avoid VM crashes
+---
+
+Use this workflow to run tests with extra precautions, especially Playwright/E2E tests that have historical stability issues.
+
+1. **Pre-flight checks:**
+   ```bash
+   # Ensure clean environment
+   ./clean_test_env.sh
+   # Check for stray processes
+   ps aux | grep -E 'neko|playwright|chrome'
+   ```
+
+2. **Backend tests (Go):**
+   // turbo
+   ```bash
+   go test -v -timeout=5m ./...
+   ```
+
+3. **Frontend unit tests (Node):**
+   // turbo
+   ```bash
+   cd frontend && npm test -- --run
+   ```
+
+4. **E2E tests (Safe Wrapper):**
+   Use the safe wrapper script which handles timeouts and automatic cleanup.
+   ```bash
+   ./run_e2e_safe.sh
+   ```
+   
+   If E2E tests fail or hang:
+   - Check `backend.log` for server issues
+   - Run `./clean_test_env.sh` to reset the database and environment
+   - Create a ticket in Thicket for any flaky tests discovered
+
+5. **Report results:**
+   - Document any flaky tests in the relevant Thicket ticket
+   - Update the ticket with coverage information if applicable
+
+**CRITICAL**: NEVER run Playwright tests directly via `npm run test:e2e` if you are unsure of stability. Always use the `./run_e2e_safe.sh` wrapper.
diff --git a/.agent/workflows/ui-iterate.md b/.agent/workflows/ui-iterate.md
new file mode 100644
index 0000000..7582587
--- /dev/null
+++ b/.agent/workflows/ui-iterate.md
@@ -0,0 +1,43 @@
+---
+description: Iterate on frontend UI changes quickly with hot-reload and production verification
+---
+
+Use this workflow when working on React components or styling to ensure a fast feedback loop and correct integration.
+
+1. **Start dev server for live iteration:**
+   ```bash
+   cd frontend
+   npm run dev
+   ```
+   This runs the React dev server (Vite) at `http://localhost:5173`. Changes to `frontend/src/` will hot-reload.
+
+2. **Make UI changes:**
+   - Edit React components in `frontend/src/components/`
+   - Edit CSS in `frontend/src/`
+   - Verify visually in the browser
+
+3. **Production Build & Integration:**
+   Once satisfied, build the production assets and integrate them into the Go binary.
+   ```bash
+   # Build React assets
+   cd frontend && npm run build
+   # Copy to web/dist/v2 for embedding
+   cd .. && make ui
+   # Rebuild Go binary with new assets
+   make build
+   ```
+
+4. **Verify Production Build:**
+   Run the baked-in binary to ensure embedding worked correctly.
+   ```bash
+   ./neko --http=4994 --database=.data/test.db
+   ```
+   Visit `http://localhost:4994` to verify.
+
+5. **Commit both Source and Dist:**
+   **CRITICAL**: You must check in both the source code (`frontend/src/`) AND the built assets (`web/dist/v2/`). This project relies on pre-built assets being in the repo for simple deployments.
+
+**Use this workflow when:**
+- Working on CSS/styling changes
+- Adjusting component layouts
+- Tweaking UI animations or interactions