Merge remote-tracking branch 'origin/main' into matt/be-4815-lint-scope

# Conflicts:
#	eslint.config.ts
#	lint-staged.config.ts

Author: mattmillerai

.agents/checks/pattern-compliance.md

@@ -22,6 +22,7 @@ Steps:
 - Explicit return types on exported functions
 - Use `es-toolkit` for utility functions, NOT lodash. Flag any new `import ... from 'lodash'` or `import ... from 'lodash/*'`
 - Never use `z.any()` in Zod schemas — use `z.unknown()` and narrow
+- Never hand-declare or duplicate server/API response types locally — flag any local interface/type that reimplements a type already generated from an OpenAPI spec (e.g. `@comfyorg/ingest-types`, `@comfyorg/registry-types` in `packages/`) instead of importing it. This caused real bugs in PR #14771 (see `docs/guidance/typescript.md`)
 
 ### Vue (if applicable)
 

.agents/setup

@@ -3,6 +3,11 @@ set -euo pipefail
 
 repo_root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
 cd "$repo_root"
+
+if [[ "${AMP_ORB:-}" == 1 ]]; then
+  gh auth setup-git
+fi
+
 node_major="$(tr -d '[:space:]' < "$repo_root/.nvmrc")"
 node_home="$HOME/.local/share/comfyui-frontend-node-v$node_major"
 
@@ -56,16 +61,10 @@ if [[ ! -x "$node_home/bin/pnpm" ]] ||
   npm install --global --prefix "$node_home" "pnpm@$pnpm_version"
 fi
 
-profile_marker="# ComfyUI Frontend orb toolchain"
-if ! grep -Fqx "$profile_marker" "$HOME/.bash_profile" 2>/dev/null; then
-  cat >> "$HOME/.bash_profile" <<EOF
-
-$profile_marker
-if [[ "\${PWD:-}" == "$repo_root" || "\${PWD:-}" == "$repo_root/"* ]]; then
-  export PATH="$node_home/bin:\$PATH"
-fi
-EOF
-fi
+mkdir -p "$HOME/.local/bin"
+for executable in node npm npx pnpm pnpx; do
+  ln -sfn "$node_home/bin/$executable" "$HOME/.local/bin/$executable"
+done
 
 echo "Installing workspace dependencies"
 pnpm install --frozen-lockfile

.amp/services.yaml

@@ -0,0 +1,6 @@
+services:
+  frontend:
+    command: pnpm dev:cloud --host 0.0.0.0 --port "$PORT"
+    portal:
+      title: ComfyUI Frontend
+      description: Frontend dev server connected to the Comfy test cloud backend.

.claude/commands/comprehensive-pr-review.md

@@ -146,6 +146,7 @@ Look for:
 - Proper abstraction levels
 - Interface design and API clarity
 - Leftover debug code (console.log, commented code, TODO comments)
+- Hand-declared/inlined server or API response types that duplicate a type already generated from an OpenAPI spec (`@comfyorg/ingest-types`, `@comfyorg/registry-types` under `packages/`) instead of importing it — these silently drift from the real contract and caused real bugs in PR #14771
 
 ### 3.3 Library Usage Enforcement
 

.claude/commands/create-hotfix-release.md

@@ -280,6 +280,8 @@ For each commit:
 5. **Click "Publish release"**
 6. **CONFIRMATION REQUIRED**: Draft release published with "latest" unchecked?
 
+Note: the `release-enforce-latest.yaml` workflow now auto-corrects the "latest" flag back to the highest stable semver release within a minute if this step is missed, so this checkbox is no longer a silent single point of failure. Still uncheck it manually — the workflow is a safety net, not a replacement for doing this right the first time.
+
 ### Step 14: Create ComfyUI Requirements.txt Update PR
 
 **IMPORTANT**: Create PR to update ComfyUI's requirements.txt via fork:

.claude/skills/publishing-a-new-package/SKILL.md

@@ -0,0 +1,162 @@
+---
+name: publishing-a-new-package
+description: 'Publishes a new package from this monorepo to npm under @comfyorg and proves it is consumable from another repo. Covers workflow scaffolding, the first-publish 404, catalog: rewriting, trusted publishing, and the consumer smoke test. Use when adding a package to packages/, publishing to npm for the first time, or when an npm publish workflow fails.'
+---
+
+# Publishing a New Package
+
+Getting a package onto npm is not done when the workflow goes green. It is done
+when someone in another repo can install it and it works. Most of the failures
+below happen after the "publish succeeded" line.
+
+## The first publish is different
+
+**A brand-new package name will fail the first CI publish unless the token was
+scoped for it**, and the error does not say so. npm returns:
+
+```text
+[E404] 404 Not Found - PUT https://registry.npmjs.org/@comfyorg%2fyour-package
+```
+
+A 404 on `PUT` means the token may publish _existing_ packages in the scope but
+may not _create_ a new name — a granular token whose write access is a
+hand-picked package list cannot include a package that does not exist yet. It
+reads like "the package doesn't exist" — which is true and irrelevant — and
+sends you looking for a workflow bug that isn't there. `--access public` is
+already set; the registry URL is already right.
+
+Two ways out, both fine:
+
+1. Give the CI token read+write on the whole `@comfyorg` scope — the narrowest
+   grant that can create a new name, and preferable to all-packages access —
+   then re-run the workflow.
+2. Publish once by hand, then make sure the CI token covers the new name.
+
+Trusted publishing (OIDC) cannot bootstrap either — npm requires the package to
+exist before a trusted publisher can be configured ([npm/cli#8544](https://github.com/npm/cli/issues/8544)).
+So the ordering is always: first publish by token → configure trusted publisher
+→ switch CI to OIDC.
+
+## Never `npm publish` from this repo
+
+Workspace packages use pnpm catalog specifiers:
+
+```json
+"dependencies": { "@iconify/utils": "catalog:" }
+```
+
+`pnpm publish` rewrites those to real ranges when it packs. `npm publish` ships
+the literal string `"catalog:"`, and every consumer install breaks. The tarball
+looks fine locally either way — the damage only shows up in the consumer.
+
+Check before you publish anything:
+
+```sh
+cd packages/<name>
+pnpm pack --pack-destination /tmp
+tar -xzOf /tmp/comfyorg-<name>-<version>.tgz package/package.json | jq .dependencies
+```
+
+Every value must be a real range. If you see `catalog:`, you used the wrong tool.
+
+## Scaffolding the workflows
+
+Copy the four-workflow set from an existing package — `design-system` and
+`desktop-ui` are the references:
+
+| Workflow                      | Role                                                    |
+| ----------------------------- | ------------------------------------------------------- |
+| `publish-<pkg>.yaml`          | `workflow_call` + `workflow_dispatch`; does the publish |
+| `publish-<pkg>-on-merge.yaml` | fires on merged PR with the `Release` label             |
+| `version-bump-<pkg>.yaml`     | dispatch → opens a version PR labelled `Release`        |
+| `ci-<pkg>-pack.yaml`          | on PR — typecheck + assert tarball contents             |
+
+The pack check must allowlist `package.json`, `LICENSE`, **and `README.md`**.
+npm force-includes all three regardless of the `files` field, so a guard that
+only permits the first two rejects any package that has a readme.
+
+## Before the first publish
+
+- **Write a README.** Without one the npm page renders empty, which defeats
+  publishing for another team to discover.
+- **Declare peer dependencies.** Anything the consumer must supply — Tailwind,
+  Vue — belongs in `peerDependencies`, not `devDependencies`. A devDependency
+  tells the consumer nothing.
+- **Export `./package.json`.** Tooling reads it; an `exports` map that omits it
+  throws `ERR_PACKAGE_PATH_NOT_EXPORTED`.
+- **Check `files` against the exports map.** Every path in `exports` must be
+  covered by `files`, or the target is simply absent from the tarball. Nothing
+  catches this at install time — neither `npm pack` nor `npm install` resolves
+  export targets — so it surfaces as a consumer resolution error the first time
+  something imports that entry.
+
+## Releasing after the first time
+
+Run the version-bump workflow → it opens a PR labelled `Release` → merge it →
+`publish-<pkg>-on-merge` publishes and posts to Slack. A manual dispatch at an
+already-published version is a **no-op**: the `Check if version already on npm`
+step finds it and skips. If you want to test the pipeline, you need a new
+version number.
+
+## Prove it is consumable
+
+This is the step people skip, and it is the only one that finds real problems.
+In a _different_ repo — ideally one on npm rather than pnpm, since that is the
+path where `catalog:` would explode:
+
+```sh
+npm install @comfyorg/<name>
+```
+
+Then import it somewhere real, build, and grep the build output to confirm the
+thing you imported actually reached the bundle. Import **every** entry in the
+`exports` map while you are there — a subpath whose target never made it into
+the tarball fails only here. A green build proves the import resolved; it does
+not prove the values landed. For CSS, point the check at the consumer's own
+build output — the path below is Nuxt's, so substitute whatever your consumer
+emits:
+
+```sh
+grep -o -- "--your-token:[^;]*" .output/public/_nuxt/*.css
+```
+
+Open that consumer change as a PR and keep the preview link — it is the
+evidence that the publish worked end to end.
+
+## Trusted publishing
+
+Once the package exists, configure it on npmjs.com under package settings:
+
+- Organization / repository / **workflow filename** — use the reusable workflow
+  that actually runs the publish (`publish-<pkg>.yaml`), not the on-merge wrapper.
+- **Environment name — leave blank** unless the publish job declares
+  `environment:`. A mismatch fails every publish.
+- **Allow `npm publish` only.** `npm stage publish` publishes unlisted pending
+  manual approval; we do not use it.
+
+Then grant OIDC at **both** workflow layers — the caller job that does
+`uses: ./.github/workflows/publish-<pkg>.yaml`, and the publish job inside the
+reusable workflow. A called workflow can never hold more than the calling job
+does, so setting this on the inner job alone leaves it with no token and the
+publish quietly falls back to `NPM_TOKEN`:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+```
+
+Keep `NODE_AUTH_TOKEN` in place until an OIDC publish has actually succeeded.
+`[WARN] Skipped OIDC` in the log means it silently fell back to the token —
+treat that as a failure to chase down, not a warning to scroll past. Suspect
+`pnpm/action-setup` first: every workflow here still pins `v4.4.0`
+(`fc06bc1257f339d1d5d8b3a19a8cae5388b55320`), the version that broke pnpm's OIDC
+publish in [pnpm#11513](https://github.com/pnpm/pnpm/issues/11513) — closed once
+the reporter bumped the action, not by a pnpm release. Only after a real OIDC
+publish should you tighten the org to require 2FA and disallow tokens; doing it
+earlier removes the only working path.
+
+## Announce it
+
+Post the npm link, the install line, and the consumer PR preview link. "It's
+published" is not actionable; "here is the import and here is it working" is.

.coderabbit.yaml

@@ -65,12 +65,39 @@ reviews:
           When warning, reference the specific ADR by number and link to `docs/adr/` for context. Frame findings as directional guidance since ADR 0003 and 0008 are in Proposed status.
 
   path_instructions:
+    - path: '**/*.ts'
+      instructions: |
+        Treat `docs/guidance/typescript.md` as required review context.
+    - path: '**/*.vue'
+      instructions: |
+        Treat `docs/guidance/typescript.md` and
+        `docs/guidance/vue-components.md` as required review context. For
+        changed components or views under `src/components/` or `src/views/`,
+        also apply `docs/guidance/design-standards.md` and assess accessibility.
+    - path: '**/*.stories.ts'
+      instructions: |
+        Treat `docs/guidance/storybook.md` as required review context.
+    - path: 'src/lib/litegraph/**'
+      instructions: |
+        Treat `docs/adr/README.md` as required review context. For widget
+        serialization changes, also read
+        `docs/WIDGET_SERIALIZATION.md`.
     - path: '**/*.test.ts'
       instructions: |
-        Treat `.agents/checks/test-quality.md`, `docs/testing/README.md`, and `docs/guidance/vitest.md` as required review context for every changed Vitest test file.
+        Treat `.agents/checks/test-quality.md`, `docs/testing/README.md`,
+        `docs/guidance/vitest.md`, and `docs/testing/vitest-patterns.md` as
+        required review context for every changed Vitest test file.
     - path: 'src/lib/litegraph/**/*.test.ts'
       instructions: |
-        Treat `.agents/checks/test-quality.md`, `docs/testing/README.md`, `docs/guidance/vitest.md`, and `docs/testing/litegraph-testing.md` as required review context for every changed litegraph Vitest test file.
+        Treat `.agents/checks/test-quality.md`, `docs/testing/README.md`,
+        `docs/guidance/vitest.md`, `docs/testing/vitest-patterns.md`, and
+        `docs/testing/litegraph-testing.md` as required review context for
+        every changed LiteGraph Vitest test file.
     - path: '{browser_tests,apps/website/e2e}/**/*.spec.ts'
       instructions: |
-        Treat `.agents/checks/test-quality.md`, `docs/testing/README.md`, and `docs/guidance/playwright.md` as required review context for every changed Playwright test file.
+        Treat `.agents/checks/test-quality.md`, `docs/testing/README.md`,
+        and `docs/guidance/playwright.md` as required review context for every
+        changed Playwright test file. For
+        `browser_tests/`, also read `browser_tests/README.md` and
+        `browser_tests/AGENTS.md`, and apply
+        `.agents/checks/playwright-e2e.md`.