{"owner":"remix-run","repo":"remix","hasSkills":true,"hasMcp":false,"mcpConfig":null,"found":["CLAUDE.md","AGENTS.md",".agents/skills/make-demo/SKILL.md",".agents/skills/make-pr/SKILL.md"],"skills":{"CLAUDE.md":"# Claude Guide\n\nFollow the repository guidance in `AGENTS.md`.\n\nWhen contributing to GitHub, do not identify, credit, or attribute work to Claude or any other AI or agentic tool. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar attribution to commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Present the work transparently in terms of the changes made and their rationale.\n","AGENTS.md":"# Remix Agent Guide\n\nThis repository includes the source code for Remix 3, a web framework for building modern web applications using TypeScript/JavaScript and web standard APIs.\n\n## Repo Shape\n\n- **Monorepo**: pnpm workspace with most product code under `packages/`\n- **Public API layout**: every `exports` entry in `package.json` should map to a dedicated top-level `src/*.ts` file\n- **Implementation layout**: `src/lib` is implementation-only; do not add barrel re-exports or thin pass-through wrappers inside `src/lib`\n- **Cross-package boundaries**: do not re-export APIs or types from another package; import from the owning package directly\n- **Platform stance**: prefer Web APIs and standards-aligned primitives over Node-specific APIs whenever possible\n\n## Default Development Loop\n\n- **Fast local loop**: `pnpm run validate-package-meta`, `pnpm run lint`, `pnpm run test:changed`, `pnpm run typecheck:changed`\n- **Full CI-style validation**: `pnpm test` and `pnpm run typecheck`\n- **When to use full runs locally**: broad cross-workspace changes, shared root config changes, release/publish flow changes, or anything that could affect the whole repo\n- **Single package commands**: `pnpm --filter @remix-run/<package> run test --quiet`, `pnpm --filter @remix-run/<package> run typecheck`, `pnpm --filter @remix-run/<package> run build`\n- **Single test file**: `cd packages/<package> && pnpm test --quiet src/**/<filename>.test.ts`\n- **Scoped test names**: add `--only '<suite-or-test-regex>'` to focus tests by full suite/test name without editing source, for example `pnpm test --quiet --only 'loader redirects'`\n- **Lint**: `pnpm run lint` or `pnpm run lint:fix`\n- **Format**: `pnpm run format` or `pnpm run format:check`\n\nThe changed-workspace commands default to diffing against `origin/main` and include uncommitted working tree changes when `head-ref` is `HEAD`.\n\n## Code Style\n\n- **Imports**: use `import type { X }` and `export type { X }`; include `.ts` extensions\n- **Variables**: use `let` for locals, `const` for module scope, never `var`\n- **Functions**: use regular functions by default; use arrow functions for callbacks; use concise arrow bodies when they only return an expression\n- **Object methods**: use shorthand method syntax\n- **Classes**: omit TS accessibility modifiers; use native fields and `#private`\n- **Generics**: use descriptive lowercase names like `source`, `pattern`, or `method`\n- **Comments**: add non-JSDoc comments only when behavior is surprising or non-obvious\n- **Formatting**: Oxfmt with `printWidth: 100`, no semicolons, single quotes, spaces not tabs\n\n## Tests And Docs\n\n- **Tests run from source**: no build step required\n- **Test structure**: do not generate tests inside `describe()` with loops or conditionals; it breaks per-test IDE execution\n- **Test guidance**: use the `write-tests` skill when adding, refactoring, or reviewing tests, fixtures, test scripts, or test-only dependencies\n- **Docs and examples**: if you change a public API, update the related docs, JSDoc, README examples, and tests in the same change\n- **README/install conventions**: use `npm i remix` in install snippets and import from `remix`, not `@remix-run/*`\n- **README link conventions**: use full GitHub URLs for cross-file or cross-package repo links so copied docs render correctly; keep same-document anchors and README self-links relative\n\n## GitHub\n\n- **GitHub work**: when commenting on issues or pull requests, inspecting GitHub state, or otherwise working with GitHub, always use the `gh` command line tool when possible instead of an agent-specific connector\n- **Agent attribution**: do not identify, credit, or attribute work to yourself or any other AI or agentic tool in commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar agent-specific attribution. Present the work transparently in terms of the changes made and their rationale.\n- **Branch names**: use `<author>/<pr-description>`, where `author` is the GitHub username of the person making the commit and `pr-description` is a few meaningful, hyphen-separated words describing the pull request, for example `mjackson/fix-flaky-bun-test`\n\n## Release Notes\n\n- If a change affects published packages, add or update the appropriate change file.\n- Package `.changes/` directories are optional. Create `packages/<package>/.changes/` on demand when adding a change file or prerelease config.\n- Prerelease channels come from `packages/*/.changes/config.json` and control the version suffix such as `alpha` or `beta`; prerelease packages still publish to the npm `next` dist-tag.\n- If you modify release or publish flow code, validate it with the preview or dry-run scripts before finishing.\n\n## Repo Skills\n\nFor work on this repository itself, use the skills in `.agents/skills/`:\n\n- `add-package` at `.agents/skills/add-package/SKILL.md`: Create or align a package under `packages/` with repo conventions.\n- `author-ui-components` at `.agents/skills/author-ui-components/SKILL.md`: Build idiomatic `packages/ui` components, including first-party UI style mixins, headless primitives, styled component wrappers, and shared component utilities.\n- `fix-issue` at `.agents/skills/fix-issue/SKILL.md`: Fix bugs reported in GitHub issues.\n- `make-changes` at `.agents/skills/make-changes/SKILL.md`: Create or update package change files under `packages/*/.changes`.\n- `make-decision-doc` at `.agents/skills/make-decision-doc/SKILL.md`: Add a numbered decision document under `decisions/` capturing a non-obvious architectural choice.\n- `make-demo` at `.agents/skills/make-demo/SKILL.md`: Create or revise demos in this repository with production-quality Remix patterns.\n- `make-pr` at `.agents/skills/make-pr/SKILL.md`: Prepare and open clear, reviewer-friendly pull requests.\n- `make-tracking-issue` at `.agents/skills/make-tracking-issue/SKILL.md`: Create or revise focused GitHub tracking issues with implementor context, a concise work plan, and required gates.\n- `publish-placeholder-package` at `.agents/skills/publish-placeholder-package/SKILL.md`: Publish a `0.0.0` placeholder package to reserve an npm name.\n- `review-pr` at `.agents/skills/review-pr/SKILL.md`: Review Remix pull requests from a local checkout.\n- `remix` at `.agents/skills/remix/SKILL.md`: Build, review, and refactor Remix apps end to end, including project layout, routes, controllers, middleware, validation, data access, auth, sessions, uploads, UI, hydration, navigation, animations, and tests.\n- `supersede-pr` at `.agents/skills/supersede-pr/SKILL.md`: Replace one pull request with another and close the superseded PR safely.\n- `typescript-expert` at `.agents/skills/typescript-expert/SKILL.md`: Write, refactor, or review TypeScript with strict, precise, maintainable types.\n- `update-pr` at `.agents/skills/update-pr/SKILL.md`: Rewrite an existing pull request title and body to match the current diff.\n- `write-api-docs` at `.agents/skills/write-api-docs/SKILL.md`: Write or tighten JSDoc for exported public APIs.\n- `write-readme` at `.agents/skills/write-readme/SKILL.md`: Draft or revise package READMEs in the repo's style.\n- `write-tests` at `.agents/skills/write-tests/SKILL.md`: Write, refactor, or review tests with repo runner, fixture, assertion, dependency, and validation conventions.\n- `write-ui-module-readme` at `.agents/skills/write-ui-module-readme/SKILL.md`: Write concise module README files for `packages/ui/src/lib/*` primitives.\n\n## App And Demo Skills\n\nFor working on Remix code in demos or writing Remix app code, use the root `remix` skill listed above.\n\nThe CLI prepack step copies `.agents/skills/remix` into the default app template so scaffolded apps can refer to `./.agents/skills/remix/SKILL.md`.\n",".agents/skills/make-demo/SKILL.md":"---\nname: make-demo\ndescription: Create or revise demos in the Remix repository. Use when adding a new demo under demos/, updating an existing demo, or reviewing demo code to ensure it showcases Remix packages, strong code hygiene, and production-quality patterns.\n---\n\n# Make Demo\n\n## Overview\n\nDemos in this repository are not throwaway prototypes. They are durable code artifacts that should teach people and other agents how to write Remix code well.\n\nA good demo should:\n\n- exercise Remix framework behavior in a realistic way\n- push the target APIs through meaningful edge cases and composition points\n- model clean structure, naming, and accessibility\n- be code that a reader could adapt into a real application\n\n## Workflow\n\n1. Read the target APIs and at least one or two existing demos before writing new code.\n2. Choose a focused scenario that exists to demonstrate Remix behavior, not a generic app shell.\n3. Build the demo under `demos/<name>/` using the same conventions as the existing demos.\n4. Treat the code as a reference artifact, not as temporary sample code.\n5. Validate the demo locally before finishing.\n\n## Rules\n\n- Use Remix library packages for the demo's framework behavior. Do not introduce unrelated routers, component frameworks, state managers, or middleware stacks that distract from the Remix patterns being demonstrated.\n- Treat each demo as its own pnpm workspace consumer. Give it a normal `package.json` with `remix` as a dependency when appropriate, and import from package exports such as `remix/ui` instead of reaching back into `packages/` with relative imports.\n- Keep any non-Remix dependency incidental to the runtime environment only. If a database driver, asset bundler, or type package is needed, it should support the demo rather than define its architecture.\n- Demos should push Remix to its limits in a focused way. Prefer realistic edge cases, composition, streaming, middleware, routing, navigation, forms, or request-handling scenarios over toy examples.\n- When demos use `remix/ui`, prefer idiomatic Remix component patterns. Use normal JSX composition and built-in styling/mixin props such as `css={...}` or `mix={css(...)}` and `mix={[...]}` instead of dropping down to manual DOM mutation or ad hoc class management.\n- When a demo uses `remix/ui` JSX, configure that demo's `tsconfig.json` with `jsx: \"react-jsx\"` and `jsxImportSource: \"remix/ui\"`. Do not set `preserveSymlinks` or add `paths` entries that point back into `packages/remix/src`. The goal is for TypeScript to resolve `remix` through the demo's own package dependency under pnpm's default symlink behavior.\n- For demos that run through `remix/node-tsx`, do not enable `erasableSyntaxOnly`; the runtime intentionally supports TypeScript syntax that needs transformation.\n- Treat development HMR as an optional mode for rapid UI edits. Keep `server.ts` as the real app server, keep `pnpm dev` running it directly, and put `remix/node-hmr` supervision in `hmr.ts` behind a `pnpm hmr` script. Use a stable public proxy with `createHmrReadyFetch()` when browser requests can race child server restarts.\n- For demos that combine HMR with `remix/ui`, use `--import remix/ui-hmr/node` for the child server and add `uiHmr()` to the asset server's loaders. Keep all HMR wiring development-only.\n- For HTML responses rendered with `remix/ui`, prefer a local `app/middleware/render.tsx` middleware that uses `renderWith(...)`, calls `renderToStream(...)`, wraps it with `createHtmlResponse(...)` from `remix/response/html`, and lets actions render with `context.get(Renderer)(...)`.\n- Prefer direct use of Remix and package APIs in demo code. Do not add custom wrappers around simple calls like `session.get()`, `session.set()`, `session.flash()`, `session.unset()`, `redirect()`, or `context.get(...)` unless the wrapper adds real domain logic, reusable policy, or a genuinely clearer abstraction.\n- Demo code must have good hygiene. Use clear names, small focused modules, explicit control flow, and accessible markup. Avoid hacks, dead code, unexplained shortcuts, or patterns that would be poor examples for users to copy.\n- Make the demo teach good patterns. Assume readers and future agents will study it as an example of how Remix code should be written in this repository.\n- All demo servers should use port `44100`.\n- Demo servers should handle `SIGINT` and `SIGTERM` cleanly by closing the server and exiting.\n\n## Typical Structure\n\nUse only the files the scenario needs, but prefer this shape:\n\n- `demos/<name>/package.json`\n- `demos/<name>/tsconfig.json` when the demo has TypeScript or JSX source\n- `demos/<name>/server.ts`\n- `demos/<name>/hmr.ts` when the demo offers an optional development HMR runner\n- `demos/<name>/README.md`\n- `demos/<name>/app/`\n- `demos/<name>/public/` when serving built assets or other static files\n\n## Remix Application Layout\n\nWhen a demo is a real application, prefer a uniform Remix application layout instead of inventing a new structure for each demo.\n\n### Root layout\n\nUse these root directories consistently:\n\n- `app/` for runtime application code\n- `db/` for database artifacts such as migrations and local SQLite files\n- `test/` for shared test helpers, fixtures, and any true cross-application integration tests\n- `public/` for static files served as-is\n- `tmp/` for runtime scratch files such as sessions, uploads, and caches\n\n### App layout\n\nInside `app/`, organize code by responsibility:\n\n- `actions/` for all controller-owned route actions and route-local UI/helpers. The root route map lives in `actions/controller.tsx`; nested route maps live in route-key folders such as `actions/auth/controller.tsx` or `actions/account/controller.tsx`\n- `data/` for runtime data definitions such as table schema and setup helpers used by the application at startup\n- `middleware/` for request-layer concerns such as auth, database injection, sessions, and other request lifecycle setup\n- `ui/` for shared UI primitives used across route areas\n- `utils/` for shared runtime support code that does not clearly belong to one of the other app layers\n\n### Naming and ownership rules\n\n- Keep controllers thin. They should read request context, talk to the database or other runtime services, and return a response.\n- `actions/controller.tsx` owns top-level leaf route actions, and each nested route map gets its own explicit `actions/<route-key>/controller.tsx` file. A controller's `actions` object contains direct leaf route keys from the route map passed to its `router.map()` call.\n- Name directories under `app/actions/` after route-map keys, not URL path segments.\n- If a component or helper is only used by one controller feature, keep it in that controller feature folder.\n- If UI is shared across route areas, keep it in `app/ui/`.\n- Do not put shared UI under `app/actions/`, and do not create a generic `app/components/` dumping ground.\n- Do not create a generic `app/lib/` dumping ground.\n- Avoid feature barrel files such as `index.ts`. Import feature modules directly.\n- If a non-UI helper is shared only by controllers, keep it under `actions/`.\n- If a helper is part of request or session setup, keep it under `middleware/`.\n- Keep table definitions, row types, and runtime database setup in `app/data/`.\n- Keep database artifacts such as migrations and SQLite files in `db/`.\n- Use `utils/` only for genuinely cross-layer support code. Prefer a topic-specific name like `utils/external-auth.ts` over catch-all names like `helpers.ts` or `misc.ts`.\n- Co-locate tests with the app modules they cover whenever those tests primarily exercise one implementation file or one small feature area.\n- Use the root `test/` directory only for shared test code, fixtures, and truly broad integration coverage that does not belong to a single app module.\n\n### Example layout\n\n```text\ndemos/<name>/\n  app/\n    router.ts\n    router.test.ts\n    routes.ts\n\n    actions/\n      controller.tsx\n\n      auth/\n        controller.tsx\n        signup/\n          controller.tsx\n        resolve-external-auth.ts\n\n      account/\n        controller.tsx\n        account-page.tsx\n\n    data/\n      schema.ts\n      setup.ts\n      setup.test.ts\n\n    middleware/\n      render.tsx\n      auth.ts\n      database.ts\n      session.ts\n\n    utils/\n      auth-session.ts\n      auth-session.test.ts\n      password-hash.ts\n      external-auth.ts\n\n    ui/\n      auth-card.tsx\n      document.tsx\n      form-field.tsx\n      notice.tsx\n      icons.tsx\n      design-system.ts\n\n  db/\n    migrations/\n    app.sqlite\n\n  test/\n    fixtures/\n    helpers.ts\n\n  public/\n  tmp/\n```\n\n## README Expectations\n\n- Explain what the demo proves or teaches.\n- Document how to run it locally.\n- Point out the key Remix APIs or patterns being demonstrated.\n- Keep code examples and imports aligned with repo guidance: use `remix` package exports where available.\n\n## Validation\n\n- Run `pnpm -C demos/<name> typecheck` when the demo defines a typecheck script.\n- Run `pnpm -C demos/<name> test` when the demo defines tests.\n- Smoke-test the demo server locally when behavior depends on live requests or browser interaction.\n- Smoke-test HMR demos through their `hmr` script when the change depends on live server or browser updates.\n- Run `pnpm run lint` before finishing.\n",".agents/skills/make-pr/SKILL.md":"---\nname: make-pr\ndescription: Create GitHub pull requests with clear, reviewer-friendly descriptions. Use when asked to open or prepare a PR, especially when the PR needs strong context, related links, and feature usage examples. This skill enforces concise PR structure, avoids redundant sections like validation/testing, and creates the PR with gh CLI.\n---\n\n# Make PR\n\n## Overview\n\nUse this skill to draft and open a PR with consistent, high-signal writing. Keep headings sparse and focus on the problem/feature explanation, context links, and practical code examples. Optimize for the shortest path to a credible PR, not the fullest possible context-gathering pass.\n\n## Workflow\n\n1. Check the fast-path blockers first.\n\n- Check `git status --short --branch` and `git branch --show-current` before doing deeper prep.\n- If the repo is in a detached HEAD or worktree state and the user wants a PR opened, create a branch early.\n\n1. Gather only the context needed to write the PR.\n\n- Capture what changed, why it changed, and who it affects.\n- Find related issues/PRs and include links when relevant.\n- Prefer `git diff --stat` plus the relevant diff over broad repo archaeology when the change is small.\n- If the user supplies a report, issue, or related PR, treat that as the primary context source.\n\n1. Get the branch into a PR-ready state quickly.\n\n- If changes are still uncommitted and the user wants a PR, branch first, then commit.\n- Prefer a single clean commit unless the user asks for a different history shape.\n\n1. Check whether this PR also needs a change file.\n\n- Do not assume every PR needs one.\n- Before opening the PR, decide whether the change is user-facing enough to require release notes in `packages/*/.changes`.\n- If a change file is needed or likely needed, use the `make-changes` skill instead of re-deriving that workflow here.\n\n1. Draft the PR body with minimal structure.\n\n- Start with 1-2 short introductory paragraphs.\n- After the intro, include clear bullets describing:\n  - the feature and/or issue addressed\n  - key behavior/API changes\n  - expected impact\n- If the change is extensive, expand to up to 3-4 paragraphs and include background context with related links.\n\n1. Add required usage examples for feature work.\n\n- If the PR introduces a new feature, include a comprehensive usage snippet.\n- If it replaces or improves an older approach, include before/after examples.\n\n1. Exclude redundant sections.\n\n- Do not include `Validation`, `Testing`, or other process sections that are already implicit in PR workflow.\n- Do not add boilerplate sections that do not help review.\n\n1. Create the PR.\n\n- Save the body to a temporary file and run:\n\n```bash\ngh pr create --base main --head <branch> --title \"<title>\" --body-file <file>\n```\n\n- If `gh pr create` fails, leave the branch pushed when possible and give the user a ready-to-open compare URL plus the prepared title/body details.\n\n## Body Template\n\nUse this as a base and fill with concrete repo-specific details:\n\n````md\n<One or two short intro paragraphs explaining the change and why it matters.>\n\n- <Feature/issue addressed>\n- <What changed in behavior or API>\n- <Why this is needed now>\n\n<Optional additional context paragraph(s), up to 3-4 total for large changes, including links to related PRs/issues.>\n\n```ts\n// New feature usage example\n```\n\n```ts\n// Before\n```\n\n```ts\n// After\n```\n````\n"},"files":{"CLAUDE.md":"# Claude Guide\n\nFollow the repository guidance in `AGENTS.md`.\n\nWhen contributing to GitHub, do not identify, credit, or attribute work to Claude or any other AI or agentic tool. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar attribution to commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Present the work transparently in terms of the changes made and their rationale.\n","AGENTS.md":"# Remix Agent Guide\n\nThis repository includes the source code for Remix 3, a web framework for building modern web applications using TypeScript/JavaScript and web standard APIs.\n\n## Repo Shape\n\n- **Monorepo**: pnpm workspace with most product code under `packages/`\n- **Public API layout**: every `exports` entry in `package.json` should map to a dedicated top-level `src/*.ts` file\n- **Implementation layout**: `src/lib` is implementation-only; do not add barrel re-exports or thin pass-through wrappers inside `src/lib`\n- **Cross-package boundaries**: do not re-export APIs or types from another package; import from the owning package directly\n- **Platform stance**: prefer Web APIs and standards-aligned primitives over Node-specific APIs whenever possible\n\n## Default Development Loop\n\n- **Fast local loop**: `pnpm run validate-package-meta`, `pnpm run lint`, `pnpm run test:changed`, `pnpm run typecheck:changed`\n- **Full CI-style validation**: `pnpm test` and `pnpm run typecheck`\n- **When to use full runs locally**: broad cross-workspace changes, shared root config changes, release/publish flow changes, or anything that could affect the whole repo\n- **Single package commands**: `pnpm --filter @remix-run/<package> run test --quiet`, `pnpm --filter @remix-run/<package> run typecheck`, `pnpm --filter @remix-run/<package> run build`\n- **Single test file**: `cd packages/<package> && pnpm test --quiet src/**/<filename>.test.ts`\n- **Scoped test names**: add `--only '<suite-or-test-regex>'` to focus tests by full suite/test name without editing source, for example `pnpm test --quiet --only 'loader redirects'`\n- **Lint**: `pnpm run lint` or `pnpm run lint:fix`\n- **Format**: `pnpm run format` or `pnpm run format:check`\n\nThe changed-workspace commands default to diffing against `origin/main` and include uncommitted working tree changes when `head-ref` is `HEAD`.\n\n## Code Style\n\n- **Imports**: use `import type { X }` and `export type { X }`; include `.ts` extensions\n- **Variables**: use `let` for locals, `const` for module scope, never `var`\n- **Functions**: use regular functions by default; use arrow functions for callbacks; use concise arrow bodies when they only return an expression\n- **Object methods**: use shorthand method syntax\n- **Classes**: omit TS accessibility modifiers; use native fields and `#private`\n- **Generics**: use descriptive lowercase names like `source`, `pattern`, or `method`\n- **Comments**: add non-JSDoc comments only when behavior is surprising or non-obvious\n- **Formatting**: Oxfmt with `printWidth: 100`, no semicolons, single quotes, spaces not tabs\n\n## Tests And Docs\n\n- **Tests run from source**: no build step required\n- **Test structure**: do not generate tests inside `describe()` with loops or conditionals; it breaks per-test IDE execution\n- **Test guidance**: use the `write-tests` skill when adding, refactoring, or reviewing tests, fixtures, test scripts, or test-only dependencies\n- **Docs and examples**: if you change a public API, update the related docs, JSDoc, README examples, and tests in the same change\n- **README/install conventions**: use `npm i remix` in install snippets and import from `remix`, not `@remix-run/*`\n- **README link conventions**: use full GitHub URLs for cross-file or cross-package repo links so copied docs render correctly; keep same-document anchors and README self-links relative\n\n## GitHub\n\n- **GitHub work**: when commenting on issues or pull requests, inspecting GitHub state, or otherwise working with GitHub, always use the `gh` command line tool when possible instead of an agent-specific connector\n- **Agent attribution**: do not identify, credit, or attribute work to yourself or any other AI or agentic tool in commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar agent-specific attribution. Present the work transparently in terms of the changes made and their rationale.\n- **Branch names**: use `<author>/<pr-description>`, where `author` is the GitHub username of the person making the commit and `pr-description` is a few meaningful, hyphen-separated words describing the pull request, for example `mjackson/fix-flaky-bun-test`\n\n## Release Notes\n\n- If a change affects published packages, add or update the appropriate change file.\n- Package `.changes/` directories are optional. Create `packages/<package>/.changes/` on demand when adding a change file or prerelease config.\n- Prerelease channels come from `packages/*/.changes/config.json` and control the version suffix such as `alpha` or `beta`; prerelease packages still publish to the npm `next` dist-tag.\n- If you modify release or publish flow code, validate it with the preview or dry-run scripts before finishing.\n\n## Repo Skills\n\nFor work on this repository itself, use the skills in `.agents/skills/`:\n\n- `add-package` at `.agents/skills/add-package/SKILL.md`: Create or align a package under `packages/` with repo conventions.\n- `author-ui-components` at `.agents/skills/author-ui-components/SKILL.md`: Build idiomatic `packages/ui` components, including first-party UI style mixins, headless primitives, styled component wrappers, and shared component utilities.\n- `fix-issue` at `.agents/skills/fix-issue/SKILL.md`: Fix bugs reported in GitHub issues.\n- `make-changes` at `.agents/skills/make-changes/SKILL.md`: Create or update package change files under `packages/*/.changes`.\n- `make-decision-doc` at `.agents/skills/make-decision-doc/SKILL.md`: Add a numbered decision document under `decisions/` capturing a non-obvious architectural choice.\n- `make-demo` at `.agents/skills/make-demo/SKILL.md`: Create or revise demos in this repository with production-quality Remix patterns.\n- `make-pr` at `.agents/skills/make-pr/SKILL.md`: Prepare and open clear, reviewer-friendly pull requests.\n- `make-tracking-issue` at `.agents/skills/make-tracking-issue/SKILL.md`: Create or revise focused GitHub tracking issues with implementor context, a concise work plan, and required gates.\n- `publish-placeholder-package` at `.agents/skills/publish-placeholder-package/SKILL.md`: Publish a `0.0.0` placeholder package to reserve an npm name.\n- `review-pr` at `.agents/skills/review-pr/SKILL.md`: Review Remix pull requests from a local checkout.\n- `remix` at `.agents/skills/remix/SKILL.md`: Build, review, and refactor Remix apps end to end, including project layout, routes, controllers, middleware, validation, data access, auth, sessions, uploads, UI, hydration, navigation, animations, and tests.\n- `supersede-pr` at `.agents/skills/supersede-pr/SKILL.md`: Replace one pull request with another and close the superseded PR safely.\n- `typescript-expert` at `.agents/skills/typescript-expert/SKILL.md`: Write, refactor, or review TypeScript with strict, precise, maintainable types.\n- `update-pr` at `.agents/skills/update-pr/SKILL.md`: Rewrite an existing pull request title and body to match the current diff.\n- `write-api-docs` at `.agents/skills/write-api-docs/SKILL.md`: Write or tighten JSDoc for exported public APIs.\n- `write-readme` at `.agents/skills/write-readme/SKILL.md`: Draft or revise package READMEs in the repo's style.\n- `write-tests` at `.agents/skills/write-tests/SKILL.md`: Write, refactor, or review tests with repo runner, fixture, assertion, dependency, and validation conventions.\n- `write-ui-module-readme` at `.agents/skills/write-ui-module-readme/SKILL.md`: Write concise module README files for `packages/ui/src/lib/*` primitives.\n\n## App And Demo Skills\n\nFor working on Remix code in demos or writing Remix app code, use the root `remix` skill listed above.\n\nThe CLI prepack step copies `.agents/skills/remix` into the default app template so scaffolded apps can refer to `./.agents/skills/remix/SKILL.md`.\n",".agents/skills/make-demo/SKILL.md":"---\nname: make-demo\ndescription: Create or revise demos in the Remix repository. Use when adding a new demo under demos/, updating an existing demo, or reviewing demo code to ensure it showcases Remix packages, strong code hygiene, and production-quality patterns.\n---\n\n# Make Demo\n\n## Overview\n\nDemos in this repository are not throwaway prototypes. They are durable code artifacts that should teach people and other agents how to write Remix code well.\n\nA good demo should:\n\n- exercise Remix framework behavior in a realistic way\n- push the target APIs through meaningful edge cases and composition points\n- model clean structure, naming, and accessibility\n- be code that a reader could adapt into a real application\n\n## Workflow\n\n1. Read the target APIs and at least one or two existing demos before writing new code.\n2. Choose a focused scenario that exists to demonstrate Remix behavior, not a generic app shell.\n3. Build the demo under `demos/<name>/` using the same conventions as the existing demos.\n4. Treat the code as a reference artifact, not as temporary sample code.\n5. Validate the demo locally before finishing.\n\n## Rules\n\n- Use Remix library packages for the demo's framework behavior. Do not introduce unrelated routers, component frameworks, state managers, or middleware stacks that distract from the Remix patterns being demonstrated.\n- Treat each demo as its own pnpm workspace consumer. Give it a normal `package.json` with `remix` as a dependency when appropriate, and import from package exports such as `remix/ui` instead of reaching back into `packages/` with relative imports.\n- Keep any non-Remix dependency incidental to the runtime environment only. If a database driver, asset bundler, or type package is needed, it should support the demo rather than define its architecture.\n- Demos should push Remix to its limits in a focused way. Prefer realistic edge cases, composition, streaming, middleware, routing, navigation, forms, or request-handling scenarios over toy examples.\n- When demos use `remix/ui`, prefer idiomatic Remix component patterns. Use normal JSX composition and built-in styling/mixin props such as `css={...}` or `mix={css(...)}` and `mix={[...]}` instead of dropping down to manual DOM mutation or ad hoc class management.\n- When a demo uses `remix/ui` JSX, configure that demo's `tsconfig.json` with `jsx: \"react-jsx\"` and `jsxImportSource: \"remix/ui\"`. Do not set `preserveSymlinks` or add `paths` entries that point back into `packages/remix/src`. The goal is for TypeScript to resolve `remix` through the demo's own package dependency under pnpm's default symlink behavior.\n- For demos that run through `remix/node-tsx`, do not enable `erasableSyntaxOnly`; the runtime intentionally supports TypeScript syntax that needs transformation.\n- Treat development HMR as an optional mode for rapid UI edits. Keep `server.ts` as the real app server, keep `pnpm dev` running it directly, and put `remix/node-hmr` supervision in `hmr.ts` behind a `pnpm hmr` script. Use a stable public proxy with `createHmrReadyFetch()` when browser requests can race child server restarts.\n- For demos that combine HMR with `remix/ui`, use `--import remix/ui-hmr/node` for the child server and add `uiHmr()` to the asset server's loaders. Keep all HMR wiring development-only.\n- For HTML responses rendered with `remix/ui`, prefer a local `app/middleware/render.tsx` middleware that uses `renderWith(...)`, calls `renderToStream(...)`, wraps it with `createHtmlResponse(...)` from `remix/response/html`, and lets actions render with `context.get(Renderer)(...)`.\n- Prefer direct use of Remix and package APIs in demo code. Do not add custom wrappers around simple calls like `session.get()`, `session.set()`, `session.flash()`, `session.unset()`, `redirect()`, or `context.get(...)` unless the wrapper adds real domain logic, reusable policy, or a genuinely clearer abstraction.\n- Demo code must have good hygiene. Use clear names, small focused modules, explicit control flow, and accessible markup. Avoid hacks, dead code, unexplained shortcuts, or patterns that would be poor examples for users to copy.\n- Make the demo teach good patterns. Assume readers and future agents will study it as an example of how Remix code should be written in this repository.\n- All demo servers should use port `44100`.\n- Demo servers should handle `SIGINT` and `SIGTERM` cleanly by closing the server and exiting.\n\n## Typical Structure\n\nUse only the files the scenario needs, but prefer this shape:\n\n- `demos/<name>/package.json`\n- `demos/<name>/tsconfig.json` when the demo has TypeScript or JSX source\n- `demos/<name>/server.ts`\n- `demos/<name>/hmr.ts` when the demo offers an optional development HMR runner\n- `demos/<name>/README.md`\n- `demos/<name>/app/`\n- `demos/<name>/public/` when serving built assets or other static files\n\n## Remix Application Layout\n\nWhen a demo is a real application, prefer a uniform Remix application layout instead of inventing a new structure for each demo.\n\n### Root layout\n\nUse these root directories consistently:\n\n- `app/` for runtime application code\n- `db/` for database artifacts such as migrations and local SQLite files\n- `test/` for shared test helpers, fixtures, and any true cross-application integration tests\n- `public/` for static files served as-is\n- `tmp/` for runtime scratch files such as sessions, uploads, and caches\n\n### App layout\n\nInside `app/`, organize code by responsibility:\n\n- `actions/` for all controller-owned route actions and route-local UI/helpers. The root route map lives in `actions/controller.tsx`; nested route maps live in route-key folders such as `actions/auth/controller.tsx` or `actions/account/controller.tsx`\n- `data/` for runtime data definitions such as table schema and setup helpers used by the application at startup\n- `middleware/` for request-layer concerns such as auth, database injection, sessions, and other request lifecycle setup\n- `ui/` for shared UI primitives used across route areas\n- `utils/` for shared runtime support code that does not clearly belong to one of the other app layers\n\n### Naming and ownership rules\n\n- Keep controllers thin. They should read request context, talk to the database or other runtime services, and return a response.\n- `actions/controller.tsx` owns top-level leaf route actions, and each nested route map gets its own explicit `actions/<route-key>/controller.tsx` file. A controller's `actions` object contains direct leaf route keys from the route map passed to its `router.map()` call.\n- Name directories under `app/actions/` after route-map keys, not URL path segments.\n- If a component or helper is only used by one controller feature, keep it in that controller feature folder.\n- If UI is shared across route areas, keep it in `app/ui/`.\n- Do not put shared UI under `app/actions/`, and do not create a generic `app/components/` dumping ground.\n- Do not create a generic `app/lib/` dumping ground.\n- Avoid feature barrel files such as `index.ts`. Import feature modules directly.\n- If a non-UI helper is shared only by controllers, keep it under `actions/`.\n- If a helper is part of request or session setup, keep it under `middleware/`.\n- Keep table definitions, row types, and runtime database setup in `app/data/`.\n- Keep database artifacts such as migrations and SQLite files in `db/`.\n- Use `utils/` only for genuinely cross-layer support code. Prefer a topic-specific name like `utils/external-auth.ts` over catch-all names like `helpers.ts` or `misc.ts`.\n- Co-locate tests with the app modules they cover whenever those tests primarily exercise one implementation file or one small feature area.\n- Use the root `test/` directory only for shared test code, fixtures, and truly broad integration coverage that does not belong to a single app module.\n\n### Example layout\n\n```text\ndemos/<name>/\n  app/\n    router.ts\n    router.test.ts\n    routes.ts\n\n    actions/\n      controller.tsx\n\n      auth/\n        controller.tsx\n        signup/\n          controller.tsx\n        resolve-external-auth.ts\n\n      account/\n        controller.tsx\n        account-page.tsx\n\n    data/\n      schema.ts\n      setup.ts\n      setup.test.ts\n\n    middleware/\n      render.tsx\n      auth.ts\n      database.ts\n      session.ts\n\n    utils/\n      auth-session.ts\n      auth-session.test.ts\n      password-hash.ts\n      external-auth.ts\n\n    ui/\n      auth-card.tsx\n      document.tsx\n      form-field.tsx\n      notice.tsx\n      icons.tsx\n      design-system.ts\n\n  db/\n    migrations/\n    app.sqlite\n\n  test/\n    fixtures/\n    helpers.ts\n\n  public/\n  tmp/\n```\n\n## README Expectations\n\n- Explain what the demo proves or teaches.\n- Document how to run it locally.\n- Point out the key Remix APIs or patterns being demonstrated.\n- Keep code examples and imports aligned with repo guidance: use `remix` package exports where available.\n\n## Validation\n\n- Run `pnpm -C demos/<name> typecheck` when the demo defines a typecheck script.\n- Run `pnpm -C demos/<name> test` when the demo defines tests.\n- Smoke-test the demo server locally when behavior depends on live requests or browser interaction.\n- Smoke-test HMR demos through their `hmr` script when the change depends on live server or browser updates.\n- Run `pnpm run lint` before finishing.\n",".agents/skills/make-pr/SKILL.md":"---\nname: make-pr\ndescription: Create GitHub pull requests with clear, reviewer-friendly descriptions. Use when asked to open or prepare a PR, especially when the PR needs strong context, related links, and feature usage examples. This skill enforces concise PR structure, avoids redundant sections like validation/testing, and creates the PR with gh CLI.\n---\n\n# Make PR\n\n## Overview\n\nUse this skill to draft and open a PR with consistent, high-signal writing. Keep headings sparse and focus on the problem/feature explanation, context links, and practical code examples. Optimize for the shortest path to a credible PR, not the fullest possible context-gathering pass.\n\n## Workflow\n\n1. Check the fast-path blockers first.\n\n- Check `git status --short --branch` and `git branch --show-current` before doing deeper prep.\n- If the repo is in a detached HEAD or worktree state and the user wants a PR opened, create a branch early.\n\n1. Gather only the context needed to write the PR.\n\n- Capture what changed, why it changed, and who it affects.\n- Find related issues/PRs and include links when relevant.\n- Prefer `git diff --stat` plus the relevant diff over broad repo archaeology when the change is small.\n- If the user supplies a report, issue, or related PR, treat that as the primary context source.\n\n1. Get the branch into a PR-ready state quickly.\n\n- If changes are still uncommitted and the user wants a PR, branch first, then commit.\n- Prefer a single clean commit unless the user asks for a different history shape.\n\n1. Check whether this PR also needs a change file.\n\n- Do not assume every PR needs one.\n- Before opening the PR, decide whether the change is user-facing enough to require release notes in `packages/*/.changes`.\n- If a change file is needed or likely needed, use the `make-changes` skill instead of re-deriving that workflow here.\n\n1. Draft the PR body with minimal structure.\n\n- Start with 1-2 short introductory paragraphs.\n- After the intro, include clear bullets describing:\n  - the feature and/or issue addressed\n  - key behavior/API changes\n  - expected impact\n- If the change is extensive, expand to up to 3-4 paragraphs and include background context with related links.\n\n1. Add required usage examples for feature work.\n\n- If the PR introduces a new feature, include a comprehensive usage snippet.\n- If it replaces or improves an older approach, include before/after examples.\n\n1. Exclude redundant sections.\n\n- Do not include `Validation`, `Testing`, or other process sections that are already implicit in PR workflow.\n- Do not add boilerplate sections that do not help review.\n\n1. Create the PR.\n\n- Save the body to a temporary file and run:\n\n```bash\ngh pr create --base main --head <branch> --title \"<title>\" --body-file <file>\n```\n\n- If `gh pr create` fails, leave the branch pushed when possible and give the user a ready-to-open compare URL plus the prepared title/body details.\n\n## Body Template\n\nUse this as a base and fill with concrete repo-specific details:\n\n````md\n<One or two short intro paragraphs explaining the change and why it matters.>\n\n- <Feature/issue addressed>\n- <What changed in behavior or API>\n- <Why this is needed now>\n\n<Optional additional context paragraph(s), up to 3-4 total for large changes, including links to related PRs/issues.>\n\n```ts\n// New feature usage example\n```\n\n```ts\n// Before\n```\n\n```ts\n// After\n```\n````\n"},"items":[{"name":"CLAUDE.md","path":"CLAUDE.md","title":"CLAUDE.md","content":"# Claude Guide\n\nFollow the repository guidance in `AGENTS.md`.\n\nWhen contributing to GitHub, do not identify, credit, or attribute work to Claude or any other AI or agentic tool. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar attribution to commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Present the work transparently in terms of the changes made and their rationale.\n","category":"root","tokens":118},{"name":"AGENTS.md","path":"AGENTS.md","title":"AGENTS.md","content":"# Remix Agent Guide\n\nThis repository includes the source code for Remix 3, a web framework for building modern web applications using TypeScript/JavaScript and web standard APIs.\n\n## Repo Shape\n\n- **Monorepo**: pnpm workspace with most product code under `packages/`\n- **Public API layout**: every `exports` entry in `package.json` should map to a dedicated top-level `src/*.ts` file\n- **Implementation layout**: `src/lib` is implementation-only; do not add barrel re-exports or thin pass-through wrappers inside `src/lib`\n- **Cross-package boundaries**: do not re-export APIs or types from another package; import from the owning package directly\n- **Platform stance**: prefer Web APIs and standards-aligned primitives over Node-specific APIs whenever possible\n\n## Default Development Loop\n\n- **Fast local loop**: `pnpm run validate-package-meta`, `pnpm run lint`, `pnpm run test:changed`, `pnpm run typecheck:changed`\n- **Full CI-style validation**: `pnpm test` and `pnpm run typecheck`\n- **When to use full runs locally**: broad cross-workspace changes, shared root config changes, release/publish flow changes, or anything that could affect the whole repo\n- **Single package commands**: `pnpm --filter @remix-run/<package> run test --quiet`, `pnpm --filter @remix-run/<package> run typecheck`, `pnpm --filter @remix-run/<package> run build`\n- **Single test file**: `cd packages/<package> && pnpm test --quiet src/**/<filename>.test.ts`\n- **Scoped test names**: add `--only '<suite-or-test-regex>'` to focus tests by full suite/test name without editing source, for example `pnpm test --quiet --only 'loader redirects'`\n- **Lint**: `pnpm run lint` or `pnpm run lint:fix`\n- **Format**: `pnpm run format` or `pnpm run format:check`\n\nThe changed-workspace commands default to diffing against `origin/main` and include uncommitted working tree changes when `head-ref` is `HEAD`.\n\n## Code Style\n\n- **Imports**: use `import type { X }` and `export type { X }`; include `.ts` extensions\n- **Variables**: use `let` for locals, `const` for module scope, never `var`\n- **Functions**: use regular functions by default; use arrow functions for callbacks; use concise arrow bodies when they only return an expression\n- **Object methods**: use shorthand method syntax\n- **Classes**: omit TS accessibility modifiers; use native fields and `#private`\n- **Generics**: use descriptive lowercase names like `source`, `pattern`, or `method`\n- **Comments**: add non-JSDoc comments only when behavior is surprising or non-obvious\n- **Formatting**: Oxfmt with `printWidth: 100`, no semicolons, single quotes, spaces not tabs\n\n## Tests And Docs\n\n- **Tests run from source**: no build step required\n- **Test structure**: do not generate tests inside `describe()` with loops or conditionals; it breaks per-test IDE execution\n- **Test guidance**: use the `write-tests` skill when adding, refactoring, or reviewing tests, fixtures, test scripts, or test-only dependencies\n- **Docs and examples**: if you change a public API, update the related docs, JSDoc, README examples, and tests in the same change\n- **README/install conventions**: use `npm i remix` in install snippets and import from `remix`, not `@remix-run/*`\n- **README link conventions**: use full GitHub URLs for cross-file or cross-package repo links so copied docs render correctly; keep same-document anchors and README self-links relative\n\n## GitHub\n\n- **GitHub work**: when commenting on issues or pull requests, inspecting GitHub state, or otherwise working with GitHub, always use the `gh` command line tool when possible instead of an agent-specific connector\n- **Agent attribution**: do not identify, credit, or attribute work to yourself or any other AI or agentic tool in commit messages, pull request titles or bodies, issue comments, release notes, or other GitHub-facing content. Do not add `Generated by`, `Co-authored-by`, tool branding, signatures, or similar agent-specific attribution. Present the work transparently in terms of the changes made and their rationale.\n- **Branch names**: use `<author>/<pr-description>`, where `author` is the GitHub username of the person making the commit and `pr-description` is a few meaningful, hyphen-separated words describing the pull request, for example `mjackson/fix-flaky-bun-test`\n\n## Release Notes\n\n- If a change affects published packages, add or update the appropriate change file.\n- Package `.changes/` directories are optional. Create `packages/<package>/.changes/` on demand when adding a change file or prerelease config.\n- Prerelease channels come from `packages/*/.changes/config.json` and control the version suffix such as `alpha` or `beta`; prerelease packages still publish to the npm `next` dist-tag.\n- If you modify release or publish flow code, validate it with the preview or dry-run scripts before finishing.\n\n## Repo Skills\n\nFor work on this repository itself, use the skills in `.agents/skills/`:\n\n- `add-package` at `.agents/skills/add-package/SKILL.md`: Create or align a package under `packages/` with repo conventions.\n- `author-ui-components` at `.agents/skills/author-ui-components/SKILL.md`: Build idiomatic `packages/ui` components, including first-party UI style mixins, headless primitives, styled component wrappers, and shared component utilities.\n- `fix-issue` at `.agents/skills/fix-issue/SKILL.md`: Fix bugs reported in GitHub issues.\n- `make-changes` at `.agents/skills/make-changes/SKILL.md`: Create or update package change files under `packages/*/.changes`.\n- `make-decision-doc` at `.agents/skills/make-decision-doc/SKILL.md`: Add a numbered decision document under `decisions/` capturing a non-obvious architectural choice.\n- `make-demo` at `.agents/skills/make-demo/SKILL.md`: Create or revise demos in this repository with production-quality Remix patterns.\n- `make-pr` at `.agents/skills/make-pr/SKILL.md`: Prepare and open clear, reviewer-friendly pull requests.\n- `make-tracking-issue` at `.agents/skills/make-tracking-issue/SKILL.md`: Create or revise focused GitHub tracking issues with implementor context, a concise work plan, and required gates.\n- `publish-placeholder-package` at `.agents/skills/publish-placeholder-package/SKILL.md`: Publish a `0.0.0` placeholder package to reserve an npm name.\n- `review-pr` at `.agents/skills/review-pr/SKILL.md`: Review Remix pull requests from a local checkout.\n- `remix` at `.agents/skills/remix/SKILL.md`: Build, review, and refactor Remix apps end to end, including project layout, routes, controllers, middleware, validation, data access, auth, sessions, uploads, UI, hydration, navigation, animations, and tests.\n- `supersede-pr` at `.agents/skills/supersede-pr/SKILL.md`: Replace one pull request with another and close the superseded PR safely.\n- `typescript-expert` at `.agents/skills/typescript-expert/SKILL.md`: Write, refactor, or review TypeScript with strict, precise, maintainable types.\n- `update-pr` at `.agents/skills/update-pr/SKILL.md`: Rewrite an existing pull request title and body to match the current diff.\n- `write-api-docs` at `.agents/skills/write-api-docs/SKILL.md`: Write or tighten JSDoc for exported public APIs.\n- `write-readme` at `.agents/skills/write-readme/SKILL.md`: Draft or revise package READMEs in the repo's style.\n- `write-tests` at `.agents/skills/write-tests/SKILL.md`: Write, refactor, or review tests with repo runner, fixture, assertion, dependency, and validation conventions.\n- `write-ui-module-readme` at `.agents/skills/write-ui-module-readme/SKILL.md`: Write concise module README files for `packages/ui/src/lib/*` primitives.\n\n## App And Demo Skills\n\nFor working on Remix code in demos or writing Remix app code, use the root `remix` skill listed above.\n\nThe CLI prepack step copies `.agents/skills/remix` into the default app template so scaffolded apps can refer to `./.agents/skills/remix/SKILL.md`.\n","category":"root","tokens":1963},{"name":"SKILL.md","path":".agents/skills/make-demo/SKILL.md","title":"make-demo Skill","content":"---\nname: make-demo\ndescription: Create or revise demos in the Remix repository. Use when adding a new demo under demos/, updating an existing demo, or reviewing demo code to ensure it showcases Remix packages, strong code hygiene, and production-quality patterns.\n---\n\n# Make Demo\n\n## Overview\n\nDemos in this repository are not throwaway prototypes. They are durable code artifacts that should teach people and other agents how to write Remix code well.\n\nA good demo should:\n\n- exercise Remix framework behavior in a realistic way\n- push the target APIs through meaningful edge cases and composition points\n- model clean structure, naming, and accessibility\n- be code that a reader could adapt into a real application\n\n## Workflow\n\n1. Read the target APIs and at least one or two existing demos before writing new code.\n2. Choose a focused scenario that exists to demonstrate Remix behavior, not a generic app shell.\n3. Build the demo under `demos/<name>/` using the same conventions as the existing demos.\n4. Treat the code as a reference artifact, not as temporary sample code.\n5. Validate the demo locally before finishing.\n\n## Rules\n\n- Use Remix library packages for the demo's framework behavior. Do not introduce unrelated routers, component frameworks, state managers, or middleware stacks that distract from the Remix patterns being demonstrated.\n- Treat each demo as its own pnpm workspace consumer. Give it a normal `package.json` with `remix` as a dependency when appropriate, and import from package exports such as `remix/ui` instead of reaching back into `packages/` with relative imports.\n- Keep any non-Remix dependency incidental to the runtime environment only. If a database driver, asset bundler, or type package is needed, it should support the demo rather than define its architecture.\n- Demos should push Remix to its limits in a focused way. Prefer realistic edge cases, composition, streaming, middleware, routing, navigation, forms, or request-handling scenarios over toy examples.\n- When demos use `remix/ui`, prefer idiomatic Remix component patterns. Use normal JSX composition and built-in styling/mixin props such as `css={...}` or `mix={css(...)}` and `mix={[...]}` instead of dropping down to manual DOM mutation or ad hoc class management.\n- When a demo uses `remix/ui` JSX, configure that demo's `tsconfig.json` with `jsx: \"react-jsx\"` and `jsxImportSource: \"remix/ui\"`. Do not set `preserveSymlinks` or add `paths` entries that point back into `packages/remix/src`. The goal is for TypeScript to resolve `remix` through the demo's own package dependency under pnpm's default symlink behavior.\n- For demos that run through `remix/node-tsx`, do not enable `erasableSyntaxOnly`; the runtime intentionally supports TypeScript syntax that needs transformation.\n- Treat development HMR as an optional mode for rapid UI edits. Keep `server.ts` as the real app server, keep `pnpm dev` running it directly, and put `remix/node-hmr` supervision in `hmr.ts` behind a `pnpm hmr` script. Use a stable public proxy with `createHmrReadyFetch()` when browser requests can race child server restarts.\n- For demos that combine HMR with `remix/ui`, use `--import remix/ui-hmr/node` for the child server and add `uiHmr()` to the asset server's loaders. Keep all HMR wiring development-only.\n- For HTML responses rendered with `remix/ui`, prefer a local `app/middleware/render.tsx` middleware that uses `renderWith(...)`, calls `renderToStream(...)`, wraps it with `createHtmlResponse(...)` from `remix/response/html`, and lets actions render with `context.get(Renderer)(...)`.\n- Prefer direct use of Remix and package APIs in demo code. Do not add custom wrappers around simple calls like `session.get()`, `session.set()`, `session.flash()`, `session.unset()`, `redirect()`, or `context.get(...)` unless the wrapper adds real domain logic, reusable policy, or a genuinely clearer abstraction.\n- Demo code must have good hygiene. Use clear names, small focused modules, explicit control flow, and accessible markup. Avoid hacks, dead code, unexplained shortcuts, or patterns that would be poor examples for users to copy.\n- Make the demo teach good patterns. Assume readers and future agents will study it as an example of how Remix code should be written in this repository.\n- All demo servers should use port `44100`.\n- Demo servers should handle `SIGINT` and `SIGTERM` cleanly by closing the server and exiting.\n\n## Typical Structure\n\nUse only the files the scenario needs, but prefer this shape:\n\n- `demos/<name>/package.json`\n- `demos/<name>/tsconfig.json` when the demo has TypeScript or JSX source\n- `demos/<name>/server.ts`\n- `demos/<name>/hmr.ts` when the demo offers an optional development HMR runner\n- `demos/<name>/README.md`\n- `demos/<name>/app/`\n- `demos/<name>/public/` when serving built assets or other static files\n\n## Remix Application Layout\n\nWhen a demo is a real application, prefer a uniform Remix application layout instead of inventing a new structure for each demo.\n\n### Root layout\n\nUse these root directories consistently:\n\n- `app/` for runtime application code\n- `db/` for database artifacts such as migrations and local SQLite files\n- `test/` for shared test helpers, fixtures, and any true cross-application integration tests\n- `public/` for static files served as-is\n- `tmp/` for runtime scratch files such as sessions, uploads, and caches\n\n### App layout\n\nInside `app/`, organize code by responsibility:\n\n- `actions/` for all controller-owned route actions and route-local UI/helpers. The root route map lives in `actions/controller.tsx`; nested route maps live in route-key folders such as `actions/auth/controller.tsx` or `actions/account/controller.tsx`\n- `data/` for runtime data definitions such as table schema and setup helpers used by the application at startup\n- `middleware/` for request-layer concerns such as auth, database injection, sessions, and other request lifecycle setup\n- `ui/` for shared UI primitives used across route areas\n- `utils/` for shared runtime support code that does not clearly belong to one of the other app layers\n\n### Naming and ownership rules\n\n- Keep controllers thin. They should read request context, talk to the database or other runtime services, and return a response.\n- `actions/controller.tsx` owns top-level leaf route actions, and each nested route map gets its own explicit `actions/<route-key>/controller.tsx` file. A controller's `actions` object contains direct leaf route keys from the route map passed to its `router.map()` call.\n- Name directories under `app/actions/` after route-map keys, not URL path segments.\n- If a component or helper is only used by one controller feature, keep it in that controller feature folder.\n- If UI is shared across route areas, keep it in `app/ui/`.\n- Do not put shared UI under `app/actions/`, and do not create a generic `app/components/` dumping ground.\n- Do not create a generic `app/lib/` dumping ground.\n- Avoid feature barrel files such as `index.ts`. Import feature modules directly.\n- If a non-UI helper is shared only by controllers, keep it under `actions/`.\n- If a helper is part of request or session setup, keep it under `middleware/`.\n- Keep table definitions, row types, and runtime database setup in `app/data/`.\n- Keep database artifacts such as migrations and SQLite files in `db/`.\n- Use `utils/` only for genuinely cross-layer support code. Prefer a topic-specific name like `utils/external-auth.ts` over catch-all names like `helpers.ts` or `misc.ts`.\n- Co-locate tests with the app modules they cover whenever those tests primarily exercise one implementation file or one small feature area.\n- Use the root `test/` directory only for shared test code, fixtures, and truly broad integration coverage that does not belong to a single app module.\n\n### Example layout\n\n```text\ndemos/<name>/\n  app/\n    router.ts\n    router.test.ts\n    routes.ts\n\n    actions/\n      controller.tsx\n\n      auth/\n        controller.tsx\n        signup/\n          controller.tsx\n        resolve-external-auth.ts\n\n      account/\n        controller.tsx\n        account-page.tsx\n\n    data/\n      schema.ts\n      setup.ts\n      setup.test.ts\n\n    middleware/\n      render.tsx\n      auth.ts\n      database.ts\n      session.ts\n\n    utils/\n      auth-session.ts\n      auth-session.test.ts\n      password-hash.ts\n      external-auth.ts\n\n    ui/\n      auth-card.tsx\n      document.tsx\n      form-field.tsx\n      notice.tsx\n      icons.tsx\n      design-system.ts\n\n  db/\n    migrations/\n    app.sqlite\n\n  test/\n    fixtures/\n    helpers.ts\n\n  public/\n  tmp/\n```\n\n## README Expectations\n\n- Explain what the demo proves or teaches.\n- Document how to run it locally.\n- Point out the key Remix APIs or patterns being demonstrated.\n- Keep code examples and imports aligned with repo guidance: use `remix` package exports where available.\n\n## Validation\n\n- Run `pnpm -C demos/<name> typecheck` when the demo defines a typecheck script.\n- Run `pnpm -C demos/<name> test` when the demo defines tests.\n- Smoke-test the demo server locally when behavior depends on live requests or browser interaction.\n- Smoke-test HMR demos through their `hmr` script when the change depends on live server or browser updates.\n- Run `pnpm run lint` before finishing.\n","category":".agents","tokens":2317},{"name":"SKILL.md","path":".agents/skills/make-pr/SKILL.md","title":"make-pr Skill","content":"---\nname: make-pr\ndescription: Create GitHub pull requests with clear, reviewer-friendly descriptions. Use when asked to open or prepare a PR, especially when the PR needs strong context, related links, and feature usage examples. This skill enforces concise PR structure, avoids redundant sections like validation/testing, and creates the PR with gh CLI.\n---\n\n# Make PR\n\n## Overview\n\nUse this skill to draft and open a PR with consistent, high-signal writing. Keep headings sparse and focus on the problem/feature explanation, context links, and practical code examples. Optimize for the shortest path to a credible PR, not the fullest possible context-gathering pass.\n\n## Workflow\n\n1. Check the fast-path blockers first.\n\n- Check `git status --short --branch` and `git branch --show-current` before doing deeper prep.\n- If the repo is in a detached HEAD or worktree state and the user wants a PR opened, create a branch early.\n\n1. Gather only the context needed to write the PR.\n\n- Capture what changed, why it changed, and who it affects.\n- Find related issues/PRs and include links when relevant.\n- Prefer `git diff --stat` plus the relevant diff over broad repo archaeology when the change is small.\n- If the user supplies a report, issue, or related PR, treat that as the primary context source.\n\n1. Get the branch into a PR-ready state quickly.\n\n- If changes are still uncommitted and the user wants a PR, branch first, then commit.\n- Prefer a single clean commit unless the user asks for a different history shape.\n\n1. Check whether this PR also needs a change file.\n\n- Do not assume every PR needs one.\n- Before opening the PR, decide whether the change is user-facing enough to require release notes in `packages/*/.changes`.\n- If a change file is needed or likely needed, use the `make-changes` skill instead of re-deriving that workflow here.\n\n1. Draft the PR body with minimal structure.\n\n- Start with 1-2 short introductory paragraphs.\n- After the intro, include clear bullets describing:\n  - the feature and/or issue addressed\n  - key behavior/API changes\n  - expected impact\n- If the change is extensive, expand to up to 3-4 paragraphs and include background context with related links.\n\n1. Add required usage examples for feature work.\n\n- If the PR introduces a new feature, include a comprehensive usage snippet.\n- If it replaces or improves an older approach, include before/after examples.\n\n1. Exclude redundant sections.\n\n- Do not include `Validation`, `Testing`, or other process sections that are already implicit in PR workflow.\n- Do not add boilerplate sections that do not help review.\n\n1. Create the PR.\n\n- Save the body to a temporary file and run:\n\n```bash\ngh pr create --base main --head <branch> --title \"<title>\" --body-file <file>\n```\n\n- If `gh pr create` fails, leave the branch pushed when possible and give the user a ready-to-open compare URL plus the prepared title/body details.\n\n## Body Template\n\nUse this as a base and fill with concrete repo-specific details:\n\n````md\n<One or two short intro paragraphs explaining the change and why it matters.>\n\n- <Feature/issue addressed>\n- <What changed in behavior or API>\n- <Why this is needed now>\n\n<Optional additional context paragraph(s), up to 3-4 total for large changes, including links to related PRs/issues.>\n\n```ts\n// New feature usage example\n```\n\n```ts\n// Before\n```\n\n```ts\n// After\n```\n````\n","category":".agents","tokens":847}]}