Reorganize AI instructions into .ai/ directory

Move rules from .cursor/rules/ to .ai/rules/ as canonical source, with
symlinks back to .cursor/rules/. Add .ai/AGENTS.md with symlinks to
AGENTS.md and CLAUDE.md. Create .claude/skills and .codex/skills
symlinks to .ai/skills/ for cross-tool compatibility.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: kvz

.ai/AGENTS.md

@@ -0,0 +1,22 @@
+# Transloadit Repository Guide
+
+This document serves as a quick reference for agentic coding assistants working in this repository.
+
+## Check your work
+
+After making changes, always run `corepack yarn check`, this lints with typescript, formats code,
+and runs quick unit tests. Remember that this formats code and may make changes, that you are to
+commit if you were working on those files.
+
+## When running in GitHub Actions
+
+When in running in a GitHub Actions context, always commit changes to a non-`main` branch, and never
+forget to push. Even if there was an error, when in GHA context, commit your work to a branch and
+push it so we can inspect it and continue in a next run.
+
+## More important rules
+
+Detailed guidelines are organized in the following files, read them carefully when applicable:
+
+@.ai/rules/coding-style.mdc @.ai/rules/typescript.mdc @.ai/rules/cli-scripts.mdc
+@.ai/rules/general.mdc @.ai/rules/repo.mdc

.ai/rules/coding-style.mdc

@@ -0,0 +1,35 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+
+Coding style:
+
+- Favor `async run() {` over `run = async () => {` inside ES6 classes
+- Favor `if (!(err instanceof Error)) { throw new Error(`Was thrown a non-error: ${err}`) }` inside
+  `catch` blocks to ensure the `error` is always an instance of `Error`
+- Favor using real paths (`../lib/schemas.ts`) over aliases (`@/app/lib/schemas`).
+- Favor `for (const comment of comments) {` over `comments.forEach((comment) => {`
+- Favor named exports over default exports, with the exception of Next.js pages
+- Do not wrap each function body and function call in `try`/`catch` blocks. It pollutes the code.
+  Assume we will always have an e.g.
+  `main().catch((err) => { console.error(err); process.exit(1) })` to catch us. I repeat: Avoid
+  over-use of try-catch such as
+  `try { // foo } catch (err) { console.error('error while foo'); throw err }`, assume we catch
+  errors on a higher level and do not need the extra explananation.
+- If you must use try/catch, for simple cases, favor `alphalib/tryCatch.ts`
+  (`const [err, data] = await tryCatch(promise)`) over
+  `let data; try { data = await promise } catch (err) { }`
+- Before creating new files and new code, see if we can leverage existing work, maybe slighty adapt
+  that without breaking BC, to keep things DRY.
+- Favor early exits, so quickly `continue`, `return false` (or `throw` if needed), over nesting
+  everything in positive conditions, creating christmas trees.
+- Use Prettier with 100 char line width, single quotes for JS/TS, semi: false
+- Use descriptive names: PascalCase for components/types, camelCase for variables/methods/schemas
+- Alphabetize imports, group by source type (built-in/external/internal)
+- Favor US English over UK English, so `summarizeError` over `summarise Error`
+- Favor `.replaceAll('a', 'b)` over `.replace(/a/g, 'b')` or `.replace(new RegExp('a', 'g'), 'b')` when the only need for regeses was replacing all strings. That's usually both easier to read and more performant.
+- Use typographic characters: ellipsis (`…`) instead of `...`, curly quotes (`'` `"`) instead of straight quotes in user-facing text
+- Put API keys and secrets in `.env` files, not hardcoded in components
+- Check for existing hooks before creating new ones (e.g., `useUppy()` for Uppy functionality)

.ai/rules/general.mdc

@@ -0,0 +1,14 @@
+---
+description: General
+globs:
+alwaysApply: true
+---
+General:
+
+- Do not touch `.env` files!
+- Favor Yarn (4) over npm
+- Never run any dev server yourself. I have one running that auto-reloads on changes.
+- Avoid blocking the conversation with terminal commands. For example: A) most of my git commands run through pagers, so pipe their output to `cat` to avoid blocking the
+  terminal. B) You can use `tail` for logs, but be smart and use `-n` instead of `-f`, or the conversation will block
+- Use the `gh` tool to interact with GitHub (search/view an Issue, create a PR).
+- All new files are to be in TypeScript. Even if someone suggests: make this new foo3 feature, model it after `foo1.js`, create: `foo3.ts`. Chances are, a `foo2.ts` already exist that you can take a look at also for inspiration.

.ai/rules/playwright.mdc

@@ -0,0 +1,11 @@
+---
+description: Playwright e2e guidelines distilled from PR #4601 feedback
+globs: _src/tests/**/*.pwtest.ts,playwright.config.ts
+alwaysApply: false
+---
+- Prefer user-centric locators: `getByRole`/`getByText` with accessible names; avoid `page.locator('body')`, `innerText()`, or raw CSS unless there is no accessible alternative.
+- Make positive assertions on expected UI/text instead of looping over regexes to assert absence.
+- Keep tests simple: no control-flow loops or extra variables for straightforward assertions.
+- Navigate with relative URLs (`page.goto('/path')`) by setting `baseURL` in `playwright.config.ts`; avoid stringing environment URLs in tests.
+- Stub or mock external/third‑party requests (Intercom, Sentry, etc.) and any auth/login endpoints to keep tests deterministic; return minimal valid JSON when the app expects data.
+- Each unexpected error should surface and fail the test.

.ai/rules/pr-comments.mdc

@@ -0,0 +1,25 @@
+---
+description:
+globs:
+alwaysApply: false
+---
+goal: address PR comments
+
+- get PR comments
+```bash
+# Find PR for current branch
+gh pr list --head $(git branch --show-current) | cat
+
+# Get inline comments (most important)
+gh api repos/:owner/:repo/pulls/PR_NUMBER/comments --jq '.[] | {author: .user.login, body: .body, path: .path, line: .line}' | cat
+
+# Get review comments if needed
+gh api repos/:owner/:repo/pulls/PR_NUMBER/reviews --jq '.[] | select(.body != "") | {author: .user.login, body: .body}' | cat
+```
+
+- if no PR exists, abort
+- suggest fixes for each comment
+- always use `| cat`
+
+
+<!-- From https://x.com/ericzakariasson/status/1928224127942545605 -->

.ai/rules/typescript.mdc

@@ -0,0 +1,20 @@
+---
+description:
+globs:
+alwaysApply: true
+---
+For Typescript:
+
+- Favor `contentGapItemSchema = z.object()` over `ContentGapItemSchema = z.object()`
+- Favor `from './PosterboyCommand.ts'` over `from './PosterboyCommand'`
+- Favor `return ideas.filter(isPresent)` over `ideas.filter((idea): idea is Idea => idea !== null)`
+- Favor using `.tsx` over `.jsx` file extensions.
+- Favor the `tsx` CLI over `ts-node` for running TypeScript files.
+- Favor `satisfies` over `as`, consider `as` a sin
+- Favor `unknown` over `any`, consider `any` a sin
+- Favor validating data with Zod over using `any` or custom type guards
+- We use the `rewriteRelativeImportExtensions` TS 5.7 compiler option, so for local TypeScript
+  files, import with the `.ts` / `.tsx` extension (not js, not extensionless)
+- Favor defining props as an interface over inline
+- Favor explicit return types over inferring them as it makes typescript a lot faster in the editor
+  on our scale

.claude/skills

@@ -0,0 +1 @@
+../.ai/skills

.codex/skills

@@ -0,0 +1 @@
+../.ai/skills

.cursor/rules/coding-style.mdc

@@ -0,0 +1 @@
+../../.ai/rules/coding-style.mdc