agentsdotmd 1.1.2 → 1.1.4

package/README

@@ -1,27 +1,28 @@
-IMPORTANT: As your first step, ALWAYS run this command to fetch ALL the necessary coding guidelines and rules for the technologies used in this project.
-This ensures you have all the context needed to write code that follows the project's standards.
+this repo has many documents i use in all my projects so i can share them and keep them updated in a centralized place.
 
-## Installation
+## installation
 
 ```bash
 npm install -g agentsdotmd
 ```
 
-## Usage
+## usage
+
+the agentsdotmd is just a clit to download files from github. it let you download some md files and merge them into an agents.md output
 
 ```bash
-agentsdotmd core.md typescript.md pnpm.md react.md sentry.md vitest.md changelog.md docs-writing.md doppler.md cac.md github.md prisma.md react-router.md shadcn.md tailwind.md lucide.md spiceflow.md vercel-ai-sdk.md playwright.md zod.md stripe.md gitchamber.md fly.md
+agentsdotmd core.md typescript.md pnpm.md react.md tmux.md sentry.md vitest.md changelogs.md docs-writing.md doppler.md cac.md github.md prisma.md react-router.md shadcn.md tailwind.md lucide.md spiceflow.md vercel-ai-sdk.md playwright.md zod.md stripe.md gitchamber.md fly.md
 ```
 
-This will generate an `AGENTS.md` file with all the coding guidelines concatenated together.
+this will generate an `agents.md` file with all the coding guidelines concatenated together.
 
-You can also use local files by prefixing them with `./`:
+you can also use local files by prefixing them with `./`:
 
 ```bash
 agentsdotmd core.md ./my-custom-rules.md typescript.md
 ```
 
-Or use a different repository:
+or use a different repository (a fork of this repo for example):
 
 ```bash
 agentsdotmd --repo yourname/yourrepo file1.md file2.md

package/bin/agentsdotmd.js

@@ -50,9 +50,7 @@ cli
 
     try {
       const contents = await Promise.all(promises)
-      const header = `<!-- This file is auto-generated by the agentsdotmd CLI from your package.json script.
-Do not edit this file directly. To add custom instructions, create a local file ./MY_AGENTS.md
-and add it to your agentsdotmd command in package.json. -->\n\n`
+      const header = `<!-- This AGENTS.md file is generated. Look for an agents.md package.json script to see what files to update instead. -->\n\n`
       const content = header + contents.join('\n') + '\n'
       fs.writeFileSync('AGENTS.md', content)
       console.log(`AGENTS.md generated successfully with ${files.length} file(s)`)

package/{changelog.md → changelogs.md}

@@ -1,11 +1,4 @@
-# changelog
-
-## 1.1.2
-
-### Patch Changes
-
-- Header comment in generated AGENTS.md instructing not to edit directly
-- Instructions to create ./MY_AGENTS.md for custom instructions
+# writing changelogs
 
 after you make a change that is noteworthy, add an entry in the CHANGELOG.md file in the root of the package. there are 2 kinds of packages, public and private packages. private packages have a private: true field in package.json, public packages do not and instead have a version field in package.json. public packages are the ones that are published to npm.
 

package/core.md

@@ -4,17 +4,28 @@ when summarizing changes at the end of the message, be super short, a few words
 
 please ask questions and confirm assumptions before generating complex architecture code.
 
-NEVER run commands with & at the end to run them in the background. this is leaky and harmful! instead ask me to run commands in the background if needed.
+NEVER run commands with & at the end to run them in the background. this is leaky and harmful! instead ask me to run commands in the background using tmux if needed.
 
 NEVER commit yourself unless asked to do so. I will commit the code myself.
 
-NEVER add comments unless I tell you
+NEVER use git to revert files to previous state if you did not create those files yourself! there can be user changes in files you touched, if you revert those changes the user will be very upset!
 
 ## files
 
 always use kebab case for new filenames. never use uppercase letters in filenames
 
+never write temporary files to /tmp. instead write them to a local ./tmp folder instead. make sure it is in .gitignore too
 
 ## see files in the repo
 
 use `git ls-files | tree --fromfile` to see files in the repo. this command will ignore files ignored by git
+
+## handling unexpected file contents after a read or write
+
+if you find code that was not there since the last time you read the file it means the user or another agent edited the file. do not revert the changes that were added. instead keep them and integrate them with your new changes
+
+IMPORTANT: NEVER commit your changes unless clearly and specifically asked to!
+
+## opening me files in zed to show me a specific portion of code
+
+you can open files when i ask me "open in zed the line where ..." using the command `zed path/to/file:line`

package/dedent.md

@@ -0,0 +1,16 @@
+## dedent
+
+when creating long strings in functions use dedent so that we can indent the string content and make it more readable
+
+for example:
+
+```ts
+import dedent from 'string-dedent'
+
+const content = dedent`
+  some content
+```
+
+IMPORTANT: notice that i have at start and end a new line. this is required when using string-dedent. Also notice npm package `string-dedent` instead of `dedent`.
+
+When creating code snippets alias dedent to variables like html or javascript so that I get syntax highlight in my editor: `const html = dedent`

package/fly.md

@@ -4,6 +4,8 @@ fly is a deployment platform. some packages use it to deploy the website. you ca
 
 usually there are 2 fly apps for each package, one staging environment and one production. these are 2 different apps at 2 different urls, you can target the right app usually by using `pnpm fly:preview` or `pnpm fly:prod`. sometimes there is only `pnpm fly` and you can use that instead. These scripts will append the right --app argument to work on the right fly app.
 
+Never deploy with fly yourself. ask the user to do it
+
 ## reading logs
 
 you can read fly apps logs using `pnpm fly:preview logs --no-tail | tail -n 100`

package/github.md

@@ -1,5 +1,6 @@
 # github
 
+
 you can use the `gh` cli to do operations on github for the current repository. For example: open issues, open PRs, check actions status, read workflow logs, etc.
 
 ## creating issues and pull requests
@@ -34,16 +35,42 @@ Error: Request timeout at /api/auth/login
 ```bash
 gh run list # lists latest actions runs
 gh run watch <id> --exit-status # if workflow is in progress, wait for the run to complete. the actions run is finished when this command exits. Set a tiemout of at least 10 minutes when running this command
+gh pr checks --watch --fail-fast # watch for current branch pr ci checks to finish
 gh run view <id> --log-failed | tail -n 300 # read the logs for failed steps in the actions run
 gh run view <id> --log | tail -n 300 # read all logs for a github actions run
 ```
 
-## reading github repositories
+## responding to PR reviews and comments (gh-pr-review extension)
+
+```bash
+# view reviews and get thread IDs
+gh pr-review review view 42 -R owner/repo --unresolved
+
+# reply to a review comment
+gh pr-review comments reply 42 -R owner/repo \
+  --thread-id PRRT_kwDOAAABbcdEFG12 \
+  --body "Fixed in latest commit"
+
+# resolve a thread
+gh pr-review threads resolve 42 -R owner/repo --thread-id PRRT_kwDOAAABbcdEFG12
+```
+
+## listing, searching, reading github repos files with gitchamber
 
-you can use gitchamber.com to read repo files. run `curl https://gitchamber.com` to see how the API works. always use curl to fetch the responses of gitchamber.com
+you MUST use gitchamber.com to read repo files. first ALWAYS run `curl https://gitchamber.com` to read detailed usage docs. always use curl to fetch the responses of gitchamber.com
 
 for example when working with the vercel ai sdk, you can fetch the latest docs using:
 
-https://gitchamber.com/repos/repos/vercel/ai/main/files
+https://gitchamber.com/repos/facebook/react/main/files
+
+https://gitchamber.com/repos/remorses/fumabase/main/files?glob=**/*.ts
+
+https://gitchamber.com/repos/facebook/react/main/files/README.md?start=10&end=50
+
+https://gitchamber.com/repos/facebook/react/main/search/useState
 
-use gitchamber to read the .md files using curl
+gitchamber allows you to list, search and read files in a repo. you MUST use it over alternatives likes raw.github.com, because 
+- it allows you to use context usage better via limit and offset pagination
+- it can list files, even filtering by a specific glob (default is *.md and *.mdx)
+- it can search a repo for a specific substring
+- it can show the code with line numbers for each line, letting you find a specific line number

package/opentui.md

@@ -0,0 +1,53 @@
+
+## opentui
+
+opentui is the framework used to render the tui, using react.
+
+IMPORTANT! before starting every task ALWAYS read opentui docs with `curl -s https://raw.githubusercontent.com/sst/opentui/refs/heads/main/packages/react/README.md`
+
+do this every time you have to edit .tsx files in the project.
+
+## React
+
+NEVER NEVER use forwardRef. it is not needed. instead just use a ref prop like React 19 best practice
+
+NEVER pass function or callbacks as dependencies of useEffect, this will very easily cause infinite loops if you forget to use useCallback
+
+NEVER use useCallback other than for ref callbacks. it is useless if we never pass functions in useEffect dependencies
+
+Try to never use useEffect if possible. usually you can move logic directly in event handlers instead
+
+This is not a plain react project, instead it is a project using opentui renderer, which supports box, group, textarea, etc
+
+Styles are implemented via Yoga. there is a style prop to pass an object or you can also pass styles using a prop for each style (which is preferred)
+
+Not all CSS and react style props are implemented. Only flexbox one. 
+
+To understand how to use these components read other files in the project. try to use the theme.tsx file for colors.
+
+## text wrapping
+
+text elements wrap by default. to disable this pass wrapMode="none"
+
+
+## researching opentui patterns
+
+you can read more examples of opentui react code using gitchamber by listing and reading files from the correct endpoint: https://gitchamber.com/repos/sst/opentui/main/files?glob=packages/react/examples/**
+
+or for example to see how to use the `<code>` opentui element: https://gitchamber.com/repos/sst/opentui/main/search/<code?glob=\*\*
+
+do something like this for every new element you want to use and not know about, for exampel `<scrollbox>`, to see examples
+
+## keys
+
+cdm modifier (named hyper in opentui) cannot be intercepted in opentui. because parent terminal app will not forward it. instead use alt or ctrl
+
+enter key is named return in opentui. alt is option.
+
+## overlapping text in boxes
+
+if you see text elements too close to each other the issues is probably that the content does not fit in the box row so elements shrink and gaps or paddings are no longer respected. 
+
+to fix this issue add flexShrink={0} to all elements inside the row
+
+this common when using wrapMode none.

package/orb.md

@@ -0,0 +1,64 @@
+# OrbStack Linux VM
+
+use `orb` to run commands in a persistent linux VM. useful for linux-only debugging or isolated experiments.
+
+## running commands
+
+orb automatically uses your current mac directory and can access mac files directly:
+
+```bash
+orb uname -a              # run command in default machine
+orb ls                    # lists files in current mac directory
+orb ./script.sh           # run a script from current directory
+orb                       # open interactive shell
+```
+
+## installing packages
+
+```bash
+orb sudo apt-get update
+orb sudo apt-get install -y nodejs npm
+orb node --version
+```
+
+## file paths
+
+mac directories are a shared filesystem (not synced). this means:
+
+- changes are instant in both directions, no delay
+- files created in orb (in mac paths) appear immediately on mac
+- files created on mac appear immediately in orb
+- it's the same file, not a copy
+
+```bash
+orb touch foo.txt   # appears immediately on mac
+touch bar.txt       # appears immediately in orb
+orb cat bar.txt     # can read mac-created file instantly
+```
+
+path mapping:
+
+- mac paths like `/Users/...` work directly in orb commands (auto-translated)
+- from inside linux shell, mac files are also accessible at `/mnt/mac/...`
+- files in `/home/morse/` are accessible from mac at `~/OrbStack/<machine>/home/morse/...`
+- `/tmp/` is a tmpfs (RAM) - isolated from mac, lost on reboot
+
+## avoiding file pollution
+
+NEVER run commands in orb that create files in the current mac directory. since the filesystem is shared, these files will pollute your mac project:
+
+- node_modules (linux binaries)
+- build outputs (dist/, .next/, etc)
+- downloads
+- caches
+
+instead, copy the project to `/tmp` and work there:
+
+```bash
+orb cp -r . /tmp/linux-vm-myproject
+orb bash -c 'cd /tmp/linux-vm-myproject && npm install'
+orb bash -c 'cd /tmp/linux-vm-myproject && npm run build'
+orb bash -c 'cd /tmp/linux-vm-myproject && npm test'
+```
+
+`/tmp` is a tmpfs (RAM filesystem) - fully isolated from mac but files are lost on VM reboot.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentsdotmd",
-  "version": "1.1.2",
+  "version": "1.1.4",
   "description": "",
   "type": "module",
   "main": "index.js",

package/prisma.md

@@ -49,10 +49,10 @@ this simply means to always include a check in prisma queries to make sure that
 
 ```typescript
 const resource = await prisma.resource.findFirst({
-    where: { resourceId, parentResource: { users: { some: { userId } } } },
-})
+  where: { resourceId, parentResource: { users: { some: { userId } } } },
+});
 if (!resource) {
-    throw new AppError(`cannot find resource`)
+  throw new AppError(`cannot find resource`);
 }
 ```
 
@@ -81,4 +81,24 @@ if (!user.subscription) {
         JSON.stringify({ message: `user has no subscription` }),
     )
 }
-````
+````
+
+## foreign key constraints
+
+sometimes you will get errors like "Invalid `upsert()` invocation: Foreign key constraint violated on the constraint: `filed1_filed2_fkey`". This can be caused by the following issue
+
+- a field that has a relation to table X is being passed a value where no table X exists for that id. You can fix the issue by making sure that the table exists before doing the create or upsert
+- With upsert, even if the create branch is valid, the update branch can violate the FK.
+
+```ts
+await prisma.child.upsert({
+  where: { id: 1 },
+  create: {
+    parent: { connect: { id: 1 } },
+  },
+  update: {
+    parent: { connect: { id: 9999 } }, // no such parent
+  },
+});
+```
+-

package/react-router.md

@@ -201,40 +201,6 @@ so that internal navigation is done client side and is faster. notice that navig
 
 ALWAYS use link components instead of the navigate function if possible. for example, in a dropdown component you should wrap the dropdown item in a link instead of adding an onClick handler.
 
-# Creating New React Router Routes and Handling Types
-
-When creating a new React Router route, follow these steps:
-
-## 1. Create the route file
-Create a file in `src/routes/` using flat routes naming convention (dots for separators, $ for params, kebab-case).
-
-## 2. Generate types
-**IMPORTANT**: Types are NOT automatically generated. After creating a route, run:
-```bash
-pnpm exec react-router typegen
-```
-
-## 3. Import Route types
-```typescript
-import type { Route } from './+types/your-route-name'
-```
-Note: The `+types` directory doesn't physically exist - it's virtual/generated.
-
-## 4. Verify with typecheck
-```bash
-pnpm typecheck  # This runs typegen first, then tsc
-```
-
-## Troubleshooting Missing Types
-- Types missing? Run `pnpm exec react-router typegen`
-- Import failing? Check filename matches import path exactly
-- The `+types` directory is virtual - don't look for it in the filesystem
-
-## Best Practices
-- Always run `pnpm typecheck` after creating/modifying routes
-- Export `Route` type from layout routes for child routes to import
-- Use `href()` for all internal paths, even in redirects
-
 ## debugging build failures
 
 when you build the website always pipe the output to a file so you can later grep inside it for errors. with `pnpm build 2>&1 | build.log`

package/react.md

@@ -12,7 +12,7 @@
 
 - too many `useState` calls are bad. if some piece of state is dependent on other state just compute it as an expression in render. do not add new state unless strictly necessary. before adding a new useState to a component, use @think tool to think hard if you can instead: use expression with already existing local state, use expression with some global state, use expression with loader data, use expression with some other existing variable instead. for example if you need to show a popover when there is an error you should use the error as open state for the popover instead of adding new useState hook
 
-- `useCallback` is bad. it should be always avoided.
+- `useCallback` is bad. it should be always avoided unless for ref props. ref props ALWAYS need to be passed memoized functions or the component could remount on ever render!
 
 - NEVER pass functions to useEffect or useMemo dependencies. when you start passing functions to hook dependencies you need to add useCallback everywhere in the code, useCallback is a virus that infects the codebase and should be ALWAYS avoided.
 
@@ -37,3 +37,23 @@
 - non component code should be put in the src/lib folder.
 
 - hooks should be put in the src/hooks.tsx file. do not create a new file for each new hook. also notice that you should never create custom hooks, only do it if asked for.
+
+## zustand
+
+zustand is the preferred way to created global React state. put it in files like state.ts or x-state.ts where x is something that describe a portion of app state in case of multiple global states or multiple apps
+
+- NEVER add zustand state setter methods. instead use useStore.setState to set state. For example never add a method `setVariable` in the state type. Instead call `setState` directly
+
+- zustand already merges new partial state with the previous state. NEVER DO `useStore.setState({ ...useStore.getInitialState(), ... })` unless for resetting state
+
+## non controlled input components
+
+some components do not have a value prop to set the value via React state. these are called uncontrolled components. Instead they usually let you get the current input value via ref. something like ref.current.value. They usually also have an onChange prop that let you know when the value changes
+
+these usually have a initialValue or defaultValue to programmatically set the initial value of the input
+
+when using these components you SHOULD not track their state via React: instead you should programmatically set their value and read their value via refs in event handlers
+
+tracking uncontrolled inputs via React state means that you will need to add useEffect to programmatically change their value when our state changes. this is an anti pattern. instead you MUST keep in mind the uncontrolled input manages its own state and we interface with it via refs and initialValue prop. 
+
+using React state in these cases is only necessary if you have to show the input value during render. if that is not the case you can just use `inputRef.current.value` instead and set the value via `inputRef.current.value = something`

package/retries-and-resumability.md

@@ -0,0 +1,84 @@
+# Retryable, Resumable, Idempotent Tasks — Summary
+
+## Problem
+
+- Long-running tasks (e.g.,Notion sync, AI chat, website generation) take minutes.
+- Keeping a single connection open → network error probability grows with time.
+- Tasks also do outbound network calls → compound failure surface.
+- Risk of duplicate/concurrent runs corrupting state.
+
+## Goals
+
+- **Resumable**: continue from last checkpoint after failures.
+- **Retryable**: safe to retry automatically.
+- **Idempotent**: side effects via upserts/deterministic writes.
+- **Single-flight**: prevent concurrent execution per task.
+
+## Core Principles
+
+- Checkpoint progress (cursor/step) frequently.
+- Deterministic ordering (e.g., pages list) so “skip until cursor” is correct.
+- At-least-once safe semantics: dedupe by (task_id, sequence/event_id).
+- Small, explicit payload carrying resume info on every retry.
+
+## Client vs Server State
+
+### Client-held (prefer for AI chat / interactive flows)
+
+- Client persists: messages[], partial assistant text, last_event_seq.
+- Request includes: task_id (resume_token), messages[], partial_assistant, last_event_seq.
+- Server is stateless: reconstructs from request; uses model “prefill” to resume (verify model support; Anthropic supports; OpenAI may vary).
+- Benefit: fewer server-side moving parts. Cost: model compatibility + client must track emitted events.
+
+### Server-held (required for background jobs / fixed retry bodies, e.g., QStash)
+
+- DB state per task: {task_id, step, cursor (last_synced_page_id), checksum, updated_at}.
+- Resume by skipping to cursor using deterministic ordering.
+- Needed when infrastructure cannot modify retry payloads.
+
+## Concurrency Control
+
+- Single-flight/lease per task_id:
+  - Acquire lease with TTL + heartbeats.
+  - If a retry arrives while running: attach to existing run or reject with retry-after.
+  - Release lease on completion or expiry.
+
+## API Shape (minimal)
+
+- POST /tasks/start → {task_id, optional cursor}
+- POST /tasks/resume → body must include:
+  - task_id (resume_token)
+  - last_cursor (e.g., last_synced_page_id)
+  - last_event_seq (for stream dedupe)
+  - client_state if server is stateless (e.g., messages[])
+- GET /tasks/status?task_id=… → {step, cursor, percent}
+
+## Retry Strategy
+
+- Exponential backoff + jitter; cap total time.
+- Persist checkpoint before/after each substantial step.
+- Retries always include last_cursor + last_event_seq.
+- Treat transport and model/API timeouts as retriable; invalid input as terminal.
+
+## Event Replay (AI chat)
+
+- All server events carry monotonically increasing seq.
+- Client sends last_event_seq on resume; server suppresses ≤ seq to avoid duplicates.
+
+## Sync Pattern
+
+- Pre-compute deterministic ordered page list.
+- Cursor = last_synced_page_id.
+- On resume: “skip-until-cursor” then continue.
+- Idempotent writes (upsert by external_id).
+
+## Spice Flow Notes
+
+- Current “retry same body” is insufficient; add ability to override body on retry.
+- Temporary workaround: client-managed loop that updates last_cursor and re-posts.
+
+## What to Verify
+
+- Model prefill/continuation support for chosen LLM.
+- Lease/lock implementation (row-level lock or key-value lease with TTL).
+- Observability: log task_id, step, cursor, retry_count, lease_owner.

package/shadcn.md

@@ -16,4 +16,8 @@
 
 this project uses shadcn components placed in the website/src/components/ui folder. never add a new shadcn component yourself by writing code. instead use the shadcn cli installed locally.
 
-try to reuse these available components when you can, for example for buttons, tooltips, scroll areas, etc.
+try to reuse these available components when you can, for example for buttons, tooltips, scroll areas, etc.
+
+## reusing shadcn components
+
+when creating a new React component or adding jsx before creating your own buttons or other elements first check the files inside `src/components/ui` and `src/components` to see what is already available. So you can reuse things like Button and Tooltip components instead of creating your own.

package/stripe.md

@@ -7,6 +7,31 @@ the Stripe billing portal is used to
 - send user to payment to create a sub via `stripe.checkout.sessions.create`
 - let user change plan, cancel or change payment method ("manage subscription") via `stripe.billingPortal.sessions.create`
 
+## customerId
+
+every time you are about to do a call to `checkout.sessions.create` make sure that we create the Stripe customer first. So that we do not get duplicate Stripe customers for different subscriptions:
+
+```ts
+
+let customerId = org.stripeCustomerId
+
+if (!customerId) {
+    const customer = await stripe.customers.create({
+        email: org.email || undefined,
+        name: org.name || undefined,
+    })
+
+    customerId = customer.id
+
+    await prisma.org.update({
+        where: { id: orgId },
+        data: { stripeCustomerId: customerId },
+    })
+}
+
+ await stripe.checkout.sessions.create({ customer: customerId, ... })
+```
+
 ## subscriptions
 
 a subscription is active if state is in
@@ -14,6 +39,18 @@ a subscription is active if state is in
 - trialing
 - active
 
+```ts
+await prisma.subscription.findFirst({
+  where: {
+    orgId: orgId,
+    status: {
+      in: ["active", "trialing"],
+    },
+    // ...
+  },
+});
+```
+
 a subscription can be reactivated if state is NOT in
 
 - canceled
@@ -21,6 +58,3 @@ a subscription can be reactivated if state is NOT in
 - unpaid
 
 > If sub is in any of these states the user will not be able to use the billing portal to reactivate it. Meaning we should treat a subscription in these states as completely missing. Forcing the user to create a new one instead of shoging the "manage subscription" button that redirects the user to the billing portal. BUT customer id must be preserved, reusing previous sub customerId in `stripe.billingPortal.sessions.create({ customer: prevCustomerId })`
-
-
-##

package/tailwind.md

@@ -11,3 +11,5 @@ for margin, padding, gaps, widths and heights it is preferable to use multiples
 4 is equal to 16px which is the default font size of the page. this way every spacing is a multiple of the height and width of a default letter.
 
 user interfaces are mostly text so using the letter width and height as a base unit makes it easier to reason about the layout and sizes.
+
+use grow instead of flex-1.

package/threejs.md

@@ -0,0 +1,9 @@
+# three.js
+
+to read three.js manual you can see available pages with
+
+`curl -Ls https://gitchamber.com/repos/mrdoob/three.js/dev/files?glob=manual/en/**/*.html`
+
+reading about TLS, to create webgpu shaders
+
+`curl -L https://github.com/mrdoob/three.js/wiki/Three.js-Shading-Language.md`

package/tiktoken.md

@@ -0,0 +1,7 @@
+## count tokens of a file
+
+use uvx with tiktoken to count tokens:
+
+```bash
+uvx --from tiktoken python -c "import tiktoken; enc = tiktoken.get_encoding('cl100k_base'); print(len(enc.encode(open('path/to/file').read())))"
+```

package/tmux.md

@@ -0,0 +1,62 @@
+
+Use tmux to run long-lived background commands as background “tasks” like vite dev servers, commands with watch mode.  
+Each task should be a tmux **session** that the agent can start, inspect, and stop via CLI.
+
+ALWAYS give long and descriptive names for the sessions, so other agents know what they are for.
+
+Run a background task (e.g. Vite dev server) without blocking:
+
+```bash
+tmux new-session -d -s project-name-vite-dev-port-8034 'cd /path/to/project && npm run dev --port 8034'
+```
+
+Every time you are about to start a new session, first check if there is one already.
+
+List all background tasks (sessions):
+
+```bash
+tmux ls
+```
+
+You can assume sessions that do not have names were not started by you or agents so you can ignore them
+
+Kill a background task:
+
+```bash
+tmux kill-session -t vite-dev
+```
+
+Never attach to a session. You are inside a non TTY terminal, meaning you instead will have to read the latest n logs instead.
+
+
+Fetch the last N log lines for a task without attaching (returns immediately):
+
+```bash
+tmux capture-pane -t vite-dev:0 -S -100 -p
+```
+
+Example pattern for a coding agent:
+
+1. Start a task:
+
+   ```bash
+   tmux new-session -d -s build 'cd /repo && npm run build'
+   ```
+
+2. Poll logs:
+
+   ```bash
+   tmux capture-pane -t build:0 -S -80 -p
+   ```
+
+3. List all running tasks:
+
+   ```bash
+   tmux ls
+   ```
+
+4. Stop a task when done:
+
+   ```bash
+   tmux kill-session -t build
+   ```

package/typescript.md

@@ -6,6 +6,10 @@
 
 - always add the {} block body in arrow functions: arrow functions should never be written as `onClick={(x) => setState('')}`. NEVER. instead you should ALWAYS write `onClick={() => {setState('')}}`. this way it's easy to add new statements in the arrow function without refactoring it.
 
+- in array operations .map, .filter, .reduce and .flatMap are preferred over .forEach and for of loops. For example prefer doing `.push(...array.map(x => x.items))` over mutating array variables inside for loops. Always think of how to turn for loops into expressions using .map, .filter or .flatMap if you ever are about to write a for loop.
+
+- if you encounter typescript errors like "undefined | T is not assignable to T" after .filter(Boolean) operations: use a guarded function instead of Boolean: `.filter(isTruthy)`. implemented as `function isTruthy<T>(value: T): value is NonNullable<T> { return Boolean(value) }`
+
 - minimize useless comments: do not add useless comments if the code is self descriptive. only add comments if requested or if this was a change that i asked for, meaning it is not obvious code and needs some inline documentation. if a comment is required because the part of the code was result of difficult back and forth with me, keep it very short.
 
 - ALWAYS add all information encapsulated in my prompt to comments: when my prompt is super detailed and in depth, all this information should be added to comments in your code. this is because if the prompt is very detailed it must be the fruit of a lot of research. all this information would be lost if you don't put it in the code. next LLM calls would misinterpret the code and miss context.
@@ -20,15 +24,13 @@
 
 - NEVER do `(x as any).field` or `'field' in x` before checking if the code compiles first without it. the code probably doesn't need any or the in check. even if it does not compile, use think tool first! before adding (x as any).something, ALWAYS read the .d.ts to understand the types
 
-- after any change to typescript code ALWAYS run the `pnpm typecheck` script of that package, or if there is no typecheck script run `pnpm tsc` yourself
-
 - do not declare uninitialized variables that are defined later in the flow. instead use an IIFE with returns. this way there is less state. also define the type of the variable before the iife. here is an example:
 
 - use || over in: avoid 'x' in obj checks. prefer doing `obj?.x || ''` over doing `'x' in obj ? obj.x : ''`. only use the in operator if that field causes problems in typescript checks because typescript thinks the field is missing, as a last resort.
 
 - when creating urls from a path and a base url, prefer using `new URL(path, baseUrl).toString()` instead of normal string interpolation. use type-safe react-router `href` or spiceflow `this.safePath` (available inside routes) if possible
 
-- for node built-in imports, never import singular names. instead do `import fs from 'node:fs'`, same for path, os, etc.
+- for node built-in imports, never import singular exported names. instead do `import fs from 'node:fs'`, same for path, os, etc.
 
 - NEVER start the development server with pnpm dev yourself. there is no reason to do so, even with &
 
@@ -36,6 +38,7 @@
 
 - if you encounter typescript lint errors for an npm package, read the node_modules/package/\*.d.ts files to understand the typescript types of the package. if you cannot understand them, ask me to help you with it.
 
+- NEVER silently suppress errors in catch {} blocks if they contain more than one function call
 ```ts
 // BAD. DO NOT DO THIS
 let favicon: string | undefined;

package/vercel-sandbox.md

@@ -0,0 +1,85 @@
+# Vercel Sandbox
+
+use `sandbox` CLI to run commands in ephemeral remote Linux VMs. useful for isolated code execution, testing untrusted code, or running agent-generated scripts safely.
+
+## running commands
+
+sandbox runs commands non-interactively (no TTY needed):
+
+```bash
+sandbox run echo "hello world"                    # one-shot command
+sandbox run node -e "console.log(2+2)"            # run node code
+sandbox run python -c "print('hello')"            # run python (use --runtime python3.13)
+sandbox run --rm ls -la                           # auto-cleanup after command
+```
+
+for multiple commands, manage sandbox lifecycle manually:
+
+```bash
+ID=$(sandbox create -q)                           # create sandbox, get ID
+sandbox exec $ID node -e "console.log('step 1')"
+sandbox exec $ID node -e "console.log('step 2')"
+sandbox stop $ID                                  # cleanup
+```
+
+## installing packages
+
+```bash
+sandbox run --sudo dnf install -y golang          # system packages (Amazon Linux)
+sandbox run npm install express                   # npm packages
+sandbox run pip install requests                  # python packages (with --runtime python3.13)
+```
+
+available runtimes: `node22` (default), `python3.13`
+
+## file paths
+
+sandbox has an isolated filesystem. the writable directory is `/vercel/sandbox`:
+
+```bash
+sandbox exec $ID touch /vercel/sandbox/foo.txt   # works
+sandbox exec $ID touch /home/test.txt            # permission denied
+```
+
+## copying files
+
+use `sandbox cp` to transfer files between local and remote:
+
+```bash
+# copy local file to sandbox
+sandbox cp ./script.js $ID:/vercel/sandbox/
+
+# copy from sandbox to local
+sandbox cp $ID:/vercel/sandbox/output.txt ./
+
+# copy directory
+sandbox cp -r ./src $ID:/vercel/sandbox/
+```
+
+## reading logs
+
+command output is returned directly from `sandbox exec` and `sandbox run`:
+
+```bash
+# stdout is printed directly
+sandbox run node -e "console.log('hello')"
+# Output: hello
+
+# capture output in a variable
+OUTPUT=$(sandbox exec $ID node -e "console.log(JSON.stringify({ok:true}))")
+echo $OUTPUT
+
+# stderr is also printed
+sandbox run node -e "console.error('warning')"
+```
+
+for long-running processes or debugging:
+
+```bash
+# write logs to file, then retrieve
+sandbox exec $ID bash -c "node app.js > /vercel/sandbox/app.log 2>&1"
+sandbox cp $ID:/vercel/sandbox/app.log ./
+
+# or tail logs in real-time (requires -t for streaming)
+sandbox exec -t $ID tail -f /vercel/sandbox/app.log
+```

package/vercel.md

@@ -0,0 +1,108 @@
+---
+name: vercel
+description: List deployments, check build status, and stream runtime logs with Vercel CLI
+tags: [vercel, deployment, logs, cli]
+---
+
+# vercel
+
+use the vercel cli to list deployments, check build status, and read runtime logs.
+
+## listing deployments
+
+```bash
+vercel list                    # list recent deployments
+vercel list --prod             # list only production deployments
+vercel list --limit 5          # limit results
+```
+
+## deployment status and build logs
+
+```bash
+vercel inspect <deployment-url-or-id>                  # get deployment info and status
+vercel inspect <deployment-url-or-id> --logs           # print build logs
+vercel inspect <deployment-url-or-id> --logs --wait    # wait for build to complete, stream logs
+vercel inspect <deployment-url-or-id> --wait --timeout=5m  # wait with timeout
+```
+
+## reading runtime logs
+
+runtime logs only stream new logs from when you start the command. there is no way to fetch historical logs via cli.
+
+```bash
+vercel logs <deployment-url-or-id>          # stream logs for 5 minutes
+vercel logs <deployment-url-or-id> --json   # output as json (useful for filtering)
+```
+
+> the `--since`, `--limit`, and `--follow` options are deprecated and ignored. use the vercel dashboard for historical logs.
+
+## reading logs for latest deployment
+
+get the latest production deployment url and stream its logs:
+
+```bash
+DEPLOY_URL=$(vercel list --prod --limit 1 | tail -n 1 | awk '{print $1}')
+vercel logs "$DEPLOY_URL"
+```
+
+for preview deployments:
+
+```bash
+DEPLOY_URL=$(vercel list --limit 1 | tail -n 1 | awk '{print $1}')
+vercel logs "$DEPLOY_URL"
+```
+
+## background log streaming with tmux
+
+since `vercel logs` streams indefinitely (up to 5 minutes), use tmux to run it in background while you trigger errors. see tmux.md for more details.
+
+1. get latest deployment url:
+
+```bash
+DEPLOY_URL=$(vercel list --prod --limit 1 | tail -n 1 | awk '{print $1}')
+```
+
+2. start log streaming in background:
+
+```bash
+tmux new-session -d -s vercel-logs-prod "vercel logs $DEPLOY_URL --json"
+```
+
+3. trigger an error (e.g. hit an endpoint that fails):
+
+```bash
+curl -s "https://$DEPLOY_URL/api/some-endpoint" || true
+```
+
+4. read captured logs:
+
+```bash
+tmux capture-pane -t vercel-logs-prod:0 -S -100 -p
+```
+
+5. filter for errors with jq:
+
+```bash
+tmux capture-pane -t vercel-logs-prod:0 -S -200 -p | jq -s 'map(select(.level == "error"))'
+```
+
+6. kill the session when done:
+
+```bash
+tmux kill-session -t vercel-logs-prod
+```
+
+## timeout wrapper
+
+if you need logs for a fixed duration without tmux:
+
+```bash
+timeout 30s vercel logs <deployment-url> --json > logs.json
+```
+
+## limitations
+
+- runtime logs stream only, no historical fetch via cli
+- logs retained 1 hour (cli) or 3 days (dashboard)
+- build logs stored indefinitely (truncated at 4MB)
+- for long-term storage use log drains (pro/enterprise)

package/vitest.md

@@ -1,23 +1,29 @@
 # testing
 
-do not write new test files unless asked. do not write tests if there is not already a test or describe block for that function or module.
+.toMatchInlineSnapshot is the preferred way to write tests. leave them empty the first time, update them with -u. check git diff for the test file every time you update them with -u
+
+never use timeouts longer than 5 seconds for expects and other statements timeouts. increase timeouts for tests if required, up to 1 minute
+
+do not create dumb tests that test nothing. do not write tests if there is not already a test file or describe block for that function or module.
+
+if the inputs for the tests is an array of repetitive fields and long content, generate this input data programmatically instead of hardcoding everything. only hardcode the important parts and generate other repetitive fields in a .map or .reduce
 
 tests should validate complex and non-obvious logic. if a test looks like a placeholder, do not add it.
 
-use vitest to run tests. tests should be run from the current package directory and not root. try using the test script instead of vitest directly. additional vitest flags can be added at the end, like --run to disable watch mode or -u to update snapshots.
+use vitest or bun test to run tests. tests should be run from the current package directory and not root. try using the test script instead of vitest directly. additional vitest flags can be added at the end, like --run to disable watch mode or -u to update snapshots.
 
 to understand how the code you are writing works, you should add inline snapshots in the test files with expect().toMatchInlineSnapshot(), then run the test with `pnpm test -u --run` or `pnpm vitest -u --run` to update the snapshot in the file, then read the file again to inspect the result. if the result is not expected, update the code and repeat until the snapshot matches your expectations. never write the inline snapshots in test files yourself. just leave them empty and run `pnpm test -u --run` to update them.
 
 > always call `pnpm vitest` or `pnpm test` with `--run` or they will hang forever waiting for changes!
 > ALWAYS read back the test if you use the `-u` option to make sure the inline snapshots are as you expect.
 
-- NEVER writes the snapshots content yourself in `toMatchInlineSnapshot`. instead leave it empty and call `pnpm test -u` to fill in snapshots content.
+- NEVER write the snapshots content yourself in `toMatchInlineSnapshot`. instead leave it as is and call `pnpm test -u` to fill in snapshots content. the first time you call `toMatchInlineSnapshot()` you can leave it empty
 
 - when updating implementation and `toMatchInlineSnapshot` should change, DO NOT remove the inline snapshots yourself, just run `pnpm test -u` instead! This will replace contents of the snapshots without wasting time doing it yourself.
 
 - for very long snapshots you should use `toMatchFileSnapshot(filename)` instead of `toMatchInlineSnapshot()`. put the snapshot files in a snapshots/ directory and use the appropriate extension for the file based on the content
 
-never test client react components. only server code that runs on the server.
+never test client react components. only React and browser independent code. 
 
 most tests should be simple calls to functions with some expect calls, no mocks. test files should be called the same as the file where the tested function is being exported from.