Producdevity · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026 · Nov 9, 2026
diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md
@@ -31,7 +31,7 @@ Fixes # (issue)
 
 - [ ] My code follows the [style guidelines](https://github.com/Producdevity/EmuReady/blob/master/CONTRIBUTING.md#code-style) of this project
 - [ ] I have performed a self-review of my code
-- [ ] I have made corresponding changes to the documentation
+- [ ] I have updated relevant documentation, or no documentation update is needed
 - [ ] I have checked that all checks (lint, typecheck, test) pass
 
 ## Notes for reviewers

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -16,8 +16,8 @@ Do not report security issues in public GitHub issues. Contact a maintainer priv
 
 Prerequisites:
 
-- Node.js `v22.17.0`, matching [.nvmrc](.nvmrc)
-- pnpm through Corepack; this repo uses `pnpm@11.1.0`
+- Node.js matching [.nvmrc](.nvmrc)
+- pnpm through Corepack, using the `packageManager` version in [package.json](package.json)
 - PostgreSQL
 - Clerk credentials for authenticated flows
 
@@ -100,6 +100,13 @@ pnpm test:e2e:ci
 
 Playwright reads `.env.test.local` and `.env.test`. See [docs/E2E_TESTING_SETUP.md](docs/E2E_TESTING_SETUP.md).
 
+## Documentation
+
+- Extend an existing topic before adding a guide. New guides should serve a lasting reader task and be linked from the [documentation index](docs/README.md).
+- Keep test results, rollout status, issue audits and review-only screenshots in the pull request. Attach review images to GitHub instead of committing them as documentation assets.
+- Link to schemas and configuration files for exact contracts and tool versions. Validate documented configuration examples against their schemas.
+- Update affected guidance in the same PR as behavior changes. Remove obsolete or duplicated material; a code change does not automatically require a new documentation file.
+
 ## Pull Requests
 
 - Base the branch on the branch the PR targets. Use `master` unless the issue or release flow says to target `staging`.

diff --git a/README.md b/README.md
@@ -20,9 +20,6 @@
   <a href="https://github.com/Producdevity/emuready/actions">
     <img src="https://img.shields.io/github/actions/workflow/status/Producdevity/emuready/ci.yml?style=flat-square&logo=github&label=CI/CD" alt="CI/CD Status">
   </a>
-  <a href="https://vercel.com">
-    <img src="https://img.shields.io/badge/Deployed_on-Vercel-black?style=flat-square&logo=vercel" alt="Deployed on Vercel">
-  </a>
   <!-- Code Quality -->
   <a href="https://github.com/Producdevity/emuready/blob/main/LICENSE">
     <img src="https://img.shields.io/github/license/Producdevity/emuready?style=flat-square&label=License" alt="License">
@@ -143,6 +140,8 @@ Then open [http://localhost:3000](http://localhost:3000).
 Environment setup is documented in [docs/DEVELOPMENT_SETUP.md](docs/DEVELOPMENT_SETUP.md). Docker-specific setup is documented in
 [docs/DOCKER.md](docs/DOCKER.md), and the production container contract is in [docs/SELF_HOSTING.md](docs/SELF_HOSTING.md).
 
+The [documentation index](docs/README.md) links the development, operations, integration and admin guides.
+
 ## Common Commands
 
 ```bash

diff --git a/docs/MOBILE_API.md b/docs/MOBILE_API.md
@@ -1,6 +1,6 @@
 # EmuReady Public Integration API (mobile-compatible tRPC)
 
-*Auto-generated on: 2026-07-06T20:07:17.160Z*
+*Auto-generated on: 2026-11-13T21:18:52.607Z*
 
 ## Summary
 - **Total Endpoints**: 113

diff --git a/docs/README.md b/docs/README.md
@@ -0,0 +1,21 @@
+# Documentation
+
+## Development
+
+- [Development setup](DEVELOPMENT_SETUP.md)
+- [Docker development](DOCKER.md)
+- [Authentication setup](AUTHENTICATION_SETUP.md)
+- [Browser testing](E2E_TESTING_SETUP.md)
+- [Error handling](ERROR_HANDLING.md)
+
+## Operations and integrations
+
+- [Self-hosting](SELF_HOSTING.md)
+- [Container releases](container-image.md)
+- [CORS configuration](CORS_CONFIGURATION.md)
+- [Webhook troubleshooting](WEBHOOK_TROUBLESHOOTING.md)
+- [Mobile API reference](MOBILE_API.md) — generated by `pnpm docs:generate`.
+
+## Administration
+
+- [Edit custom fields as JSON](admin/custom-fields.md)
diff --git a/docs/admin/custom-fields.md b/docs/admin/custom-fields.md
@@ -0,0 +1,48 @@
+# Edit custom fields as JSON
+
+On an emulator's custom fields page, choose **Edit JSON** to paste or edit its fields, attributes, categories and ordering. Choose **Save JSON** and confirm the emulator.
+
+The JSON describes the complete setup. Omitted unused fields and categories are removed. Fields with existing Handheld or PC Report values cannot be removed or changed incompatibly.
+
+## Format
+
+```json
+{
+  "version": 1,
+  "categories": [
+    { "name": "Graphics", "displayOrder": 0 }
+  ],
+  "fields": [
+    {
+      "name": "renderer",
+      "label": "Graphics API",
+      "type": "SELECT",
+      "category": "Graphics",
+      "options": [
+        { "value": "vulkan", "label": "Vulkan" },
+        { "value": "opengl", "label": "OpenGL" }
+      ],
+      "defaultValue": "vulkan",
+      "isRequired": false,
+      "displayOrder": 0,
+      "categoryOrder": 0
+    }
+  ]
+}
+```
+
+- Keep the exported `id` when renaming an existing field or category. This preserves its identity and report values. New items may omit IDs; pasted items without a matching destination ID are matched by name or created.
+- A field's `category` is a category name, or `null` for no group. Update field references when renaming a category. Empty categories are allowed.
+- A category's `displayOrder` controls category order; uncategorized fields appear last. Within a group, fields sort by `categoryOrder`, then by field `displayOrder` to break ties.
+- Use JSON booleans and numbers for Boolean and Range defaults, including `false` and `0`. A Select default must match an option's `value`.
+- Range settings use `rangeMin`, `rangeMax`, `rangeUnit` and `rangeDecimals`. Text, Textarea and URL fields may use `placeholder`.
+
+The [configuration schema](../../src/features/emulators/custom-field-config/shared/config.schemas.ts) defines accepted attributes and validation. The example above is checked against that schema by the test suite.
+
+## Saving and conflicts
+
+Changing populated fields' types, removing select options, changing range units or narrowing ranges is blocked. Rename or relabel items while retaining their IDs to preserve report values.
+
+If another edit changes the setup while the editor is open, saving returns a conflict. Copy the draft, reopen the editor and reconcile it with the current configuration before saving again.
+
+Custom-field management permission is required. Developers must also be verified for the emulator; the [access policy](../../src/features/emulators/custom-field-config/server/config.policy.ts) defines the role checks.
diff --git a/eslint.config.mjs b/eslint.config.mjs
@@ -88,7 +88,8 @@ const featureLayerBoundaryZones = featureLayerRootNames.flatMap((featureRootName
 const featureToAppRouteBoundaryZone = {
   target: './src/features',
   from: './src/app',
-  message: 'Feature modules must not import from Next.js app routes. Compose features in app routes.',
+  message:
+    'Feature modules must not import from Next.js app routes. Compose features in app routes.',
 }
 
 const featureBoundaryZones = [
@@ -103,6 +104,7 @@ const eslintConfig = [
     ignores: [
       '*.log',
       '*.tsbuildinfo',
+      '**/.agents/**',
       '.clerk/**',
       '.husky/**',
       '.idea/**',
@@ -142,14 +144,13 @@ const eslintConfig = [
       'no-case-declarations': 'off',
       'no-prototype-builtins': 'off',
       'no-redeclare': 'off',
-      // TODO: set to error after fixing existing React Compiler rule violations.
-      'react-hooks/purity': 'warn',
-      'react-hooks/static-components': 'warn',
-      'react-hooks/immutability': 'warn',
-      'react-hooks/incompatible-library': 'warn',
-      'react-hooks/preserve-manual-memoization': 'warn',
-      'react-hooks/refs': 'warn',
-      'react-hooks/set-state-in-effect': 'warn',
+      'react-hooks/purity': 'error',
+      'react-hooks/static-components': 'error',
+      'react-hooks/immutability': 'error',
+      'react-hooks/incompatible-library': 'error',
+      'react-hooks/preserve-manual-memoization': 'error',
+      'react-hooks/refs': 'error',
+      'react-hooks/set-state-in-effect': 'error',
     },
   },
   {

diff --git a/next.config.ts b/next.config.ts
@@ -150,6 +150,15 @@ function createContentSecurityPolicy(): string {
 const nextConfig: NextConfig = {
   output: 'standalone',
 
+  async rewrites() {
+    return [
+      {
+        source: '/assets/emulators/:logo.png',
+        destination: '/assets/emulators/:logo.webp',
+      },
+    ]
+  },
+
   // Keep build identity stable and protect clients from version skew while
   // Coolify briefly overlaps the old and new containers during deployment.
   ...(nextBuildId ? { deploymentId: nextBuildId, generateBuildId: () => nextBuildId } : {}),

diff --git a/playwright.config.ts b/playwright.config.ts
@@ -31,6 +31,7 @@ function createWebServerEnv(): { [key: string]: string } {
  */
 export default defineConfig({
   testDir: './tests',
+  testIgnore: ['**/.agents/**'],
   /* Run tests in files in parallel */
   fullyParallel: true,
   /* Fail the build on CI when test.only is left on. */
@@ -74,6 +75,7 @@ export default defineConfig({
       name: 'chromium',
       use: { ...devices['Desktop Chrome'] },
       testIgnore: [
+        '**/.agents/**',
         '**/auth.setup.ts',
         '**/global.setup.ts',
         '**/data-setup.spec.ts',