agentsdotmd 1.1.3 → 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/{changelog.md → changelogs.md}

@@ -1,17 +1,4 @@
-# changelog
-
-## 1.1.3
-
-### Patch Changes
-
-- vitest.md instructions update
-
-## 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/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.3",
+  "version": "1.1.4",
   "description": "",
   "type": "module",
   "main": "index.js",

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.
 
@@ -42,10 +42,18 @@
 
 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
 
-- minimize number of props. do not use props if you can use zustand state instead. the app has global zustand state that lets you get a piece of state down from the component tree by using something like `useStore(x => x.something)` or `useLoaderData<typeof loader>()` or even useRouteLoaderData if you are deep in the react component tree
-
-- do not consider local state truthful when interacting with server. when interacting with the server with rpc or api calls never use state from the render function as input for the api call. this state can easily become stale or not get updated in the closure context. instead prefer using zustand `useStore.getState().stateValue`. notice that useLoaderData or useParams should be fine in this case.
-
 - 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/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

@@ -24,8 +24,6 @@
 
 - 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.
@@ -40,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,25 +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.