Feat/generic diffusers workbench

.github/workflows/ci.yml

@@ -41,8 +41,10 @@ jobs:
         with: { python-version: '${{ matrix.python }}' }
       - uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6
         with: { version: '0.11.26' }
-      - run: python -m modiff.install --accelerator cpu --backend-only --non-interactive --json
+      - run: uv run --no-project --no-sync --python 3.12 -m modiff.dev plan --accelerator cpu --backend-only --json
+      - run: uv run --no-project --no-sync --python 3.12 -m modiff.dev setup --accelerator cpu --backend-only --non-interactive --json
       - run: uv pip install --python ${{ matrix.managed-python }} -r requirements/test.txt
       - run: uv pip check --python ${{ matrix.managed-python }}
-      - run: ${{ matrix.managed-python }} -m modiff.preflight --json --check-port 8088 --fail-on-error
+      - run: uv run --no-project --no-sync --python 3.12 -m modiff.dev check --json --check-port 8088 --fail-on-error
+      - run: ${{ matrix.managed-python }} scripts/smoke_service_package.py
       - run: ${{ matrix.managed-python }} -m pytest -q

.github/workflows/qualify-optional-runtime-macos.yml

@@ -42,9 +42,9 @@ jobs:
              "torchsde>=0.2.6",
              "torchvision>=0.21.0",
           -  "transformers>=4.49.0; sys_platform == 'darwin' or platform_machine == 'aarch64' or platform_machine == 'arm64' or platform_machine == 'ARM64'",
-             "diffusers @ git+https://github.com/huggingface/diffusers.git@2f7e0154a9db246e95c9ede43edba7db5b130805",
+             "diffusers @ git+https://github.com/huggingface/diffusers.git@fbf49e7f35857f76bc57b177e26f12b03687c668",
              "ftfy>=6.3.1",
-             "huggingface-hub>=1.23.0,<2.0",
+             "huggingface-hub>=1.31.0,<2.0",
           PATCH
           git apply --check "$RUNNER_TEMP/prospective-base.patch"
           git apply "$RUNNER_TEMP/prospective-base.patch"

.gitignore

@@ -46,6 +46,7 @@ custom/*
 
 data/*
 !data/model-artifact-catalog.json
+!data/image-prototyping-readiness.v1.json
 !data/huggingface-cluster-promotion-receipts.v1.json
 !data/huggingface-cluster-promotion-receipts.v2.json
 !data/huggingface-cluster-catalog-gates.v1.json

AGENTS.md

@@ -36,6 +36,12 @@ These rules apply to AI-assisted work in this repository. `CONTRIBUTING.md` is t
 - Never commit `config.ini`, tokens, local paths, generated outputs, model caches, qualification workspaces, virtual environments, logs, or template media.
 - Public template media belongs in the configured public Hugging Face Dataset repository. Keep only its versioned source descriptor, hashes, and documentation in Git.
 
+## Custom extensions
+
+- Read [Custom node development](docs/custom-nodes.md) before changing extension discovery, staging, enable, reload, or execution. Keep approvals outside source packages and bind them to inspected source and declared dependency versions.
+- Executable custom Python uses explicit Add/Load/Reload and the existing executor. Bind source/dependency hashes internally; discovery, preview and graph import are not consent. Contract-only Blocks remain non-executable.
+- A custom resource declaration is operator-reviewed code metadata, not catalog or hardware qualification. Do not execute custom suppliers during Auto inspection or assume their Python references are safe for early model eviction.
+
 ## Quality And Evidence
 
 - Add a regression test that fails for the original defect and covers related instances of the same pattern.

CONTRIBUTING.md

@@ -10,6 +10,8 @@ integrating another machine's work, read and follow
 
 ## Development setup
 
+For script-free `uv`/`npm` setup, use [Developer setup](docs/developer-setup.md).
+
 Use Python 3.12 and create the same managed CPU profile used by baseline CI:
 
 ```bash
@@ -26,7 +28,7 @@ uv pip install --python .venv/Scripts/python.exe -r requirements/test.txt
 .\.venv\Scripts\python.exe -m modiff.preflight --json --check-port 8088 --fail-on-error
 ```
 
-Choose the qualified accelerator profile relevant to a hardware-specific change and report that validation separately. Do not use `uv sync` or `uv run`: the project is intentionally `uv`-unmanaged because the installer, not the generic resolver, owns the executable Torch profile.
+Choose the qualified accelerator profile relevant to a hardware-specific change and report that validation separately. Do not use `uv sync` or ordinary `uv run` (the documented `uv run --no-project --no-sync ... -m modiff.dev` bootstrap is the explicit exception): the project is intentionally `uv`-unmanaged because the installer, not the generic resolver, owns the executable Torch profile.
 
 Do not commit `config.ini`, `.env` files, model caches, generated outputs, local logs, virtual environments, or test caches.
 
@@ -38,6 +40,10 @@ Do not commit `config.ini`, `.env` files, model caches, generated outputs, local
 - Treat file access, custom-module installation, remote code, token handling, and mutating routes as security-sensitive changes.
 - Avoid importing the full model registry from lightweight diagnostics such as preflight.
 
+### Custom node development
+
+For local/Git Python nodes and pinned Hub Modular blocks, follow [Custom node development](docs/custom-nodes.md). Stage and inspect without imports, explicitly enable the exact code hash, then review/reload after edits. Do not add an unconditional startup import or install dependencies from discovery. Test stale code, relative helper isolation, approval rejection, import diagnostics, and cache ownership through ordinary graph dispatch.
+
 ### Adding a node module
 
 Built-in node packages live under `modules/<Name>/` and normally contain:
@@ -100,6 +106,17 @@ and child generators. Generated `__pycache__` files inside a sealed overlay are
 integrity drift, not files to whitelist. Keep base-gate and optional-runtime
 results separate; skipped model-library tests are not execution coverage.
 
+Pytest redirects the default extension store to a temporary directory before
+collection so registry imports cannot execute or change the operator's installed
+custom sources. Extension tests use explicit temporary roots. Subprocess tests
+must also isolate extension discovery; they do not inherit Python monkeypatches.
+
+The checked-in image readiness inventory uses a fixed Linux/x86_64 reference
+target; `scripts/generate_image_prototyping_readiness.py --check` must reproduce
+it on every host. This static inventory is not local runtime readiness. Live
+execution profiles continue to resolve the current OS/architecture and installed
+runtime through the normal readiness boundary.
+
 On a host with Git Bash or a POSIX shell:
 
 ```bash

README.md

@@ -4,9 +4,57 @@
 
 MoDiff is a local client/server application for building and running node-based machine-learning workflows with a focus on [Hugging Face Diffusers](https://github.com/huggingface/diffusers). The backend discovers Python node modules, executes graphs, manages models and generated media, and serves a bundled web client from `web/`.
 
+The [Qwen-Image 2.1 integration guide](docs/qwen-image-21.md) describes its generic
+image nodes, attention-context reuse, runtime requirements and qualification status.
+
+The [image demo guide](docs/image-demo.md) lists the tested workflows, settings,
+measured reuse behavior and remaining qualification work.
+
+The [modularity walkthrough](docs/modularity-demo.md) covers editable generation
+stages, a custom image-and-mask node, connected refinement, model switching and
+saved-workflow restoration.
+
 > [!CAUTION]
 > MoDiff is early-stage software. It is not a production service, a multi-user platform, or a security sandbox. The server has no authentication and can execute model workflows, import custom Python modules, and access files inside its configured working directory. Keep it bound to `127.0.0.1`, install only code you trust, and read [SECURITY.md](SECURITY.md) before changing its network exposure.
 
+## Developer setup with uv and npm
+
+Install Git, [uv `0.11.26`](https://docs.astral.sh/uv/getting-started/installation/),
+Node.js `24.12.0`, and npm `11.6.2`. uv can provision Python 3.12.
+Use two terminals for the backend and the editable frontend.
+
+**Terminal 1 — backend:** clone both repositories into the same parent directory,
+then start the backend. These commands work in Linux shells and Windows PowerShell.
+
+```text
+git clone https://github.com/sdevil7th/MoDiff.git MoDiff
+git clone https://github.com/sdevil7th/MoDiff-client.git MoDiff-client
+cd MoDiff
+uv run --no-project --no-sync --python 3.12 -m modiff.dev plan --accelerator cpu --backend-only --json
+uv run --no-project --no-sync --python 3.12 -m modiff.dev setup --accelerator cpu --backend-only --non-interactive
+uv run --no-project --no-sync --python 3.12 -m modiff.dev check --json --check-port 8088 --fail-on-error
+uv run --no-project --no-sync --python 3.12 -m modiff.dev run
+```
+
+The CPU profile is for API/UI development. For NVIDIA inference, replace `cpu`
+with `nvidia` in both `plan` and `setup`; other accelerators are covered in the
+[full setup guide](docs/developer-setup.md). Setup preserves an existing `.venv` and
+does not download model weights. Use the guide for deliberate environment repair;
+ordinary `uv sync` is not supported.
+
+**Terminal 2 — frontend:** from the same parent directory, run:
+
+```text
+cd MoDiff-client
+npm ci
+npm run dev
+```
+
+Keep the backend running at <http://127.0.0.1:8088> and open the URL printed by
+Vite for the editable frontend. Press `Ctrl+C` in each terminal to stop it.
+See the [full developer setup guide](docs/developer-setup.md) for accelerator prerequisites,
+optional runtimes, repair, and bundled-app setup.
+
 ## Before you install
 
 MoDiff is distributed as paired backend and client source checkouts. For normal
@@ -194,18 +242,39 @@ cp config.example.ini config.ini
 
 `config.ini` is intentionally ignored because it may contain a Hugging Face token and machine-local paths.
 
+## Developer tools and service prototyping
+
+For installation, use the [uv/npm quick start](#developer-setup-with-uv-and-npm)
+above and the [full setup guide](docs/developer-setup.md).
+See [service prototyping](docs/service-prototyping.md) to export a named service
+interface from the editor. Services reuse the existing API graph and local runtime.
+
+The frontend has one developer-first editor. Start with **Workflows** for connected
+task stages or choose **Templates**. Inspect implementation/docs and export graph
+JSON or services without changing modes. **Memory: Automatic / Custom** remains
+independent per workflow.
+
+Use **Add image / audio input** on a loader, or drag a media output onto an
+operation. A dropdown lists supported roles; required stages are added inside
+the existing graph, preserving prompts and branches as one Undo operation.
+Video simplification is deferred.
+
+Generic Modular loader and node-field updates can run while another workflow is
+generating without borrowing its model cache. See the [field-action ownership
+contract](docs/api-reference.md#graph-execution-and-queue-state).
+
 ## Managed installation profiles
 
-MoDiff's installer owns the executable Python/Torch environment. The project is intentionally marked `uv`-unmanaged, so `uv sync` and `uv run` are not supported setup or launch commands. The installer stages a fresh environment, checks its package policy and a real device tensor, then atomically promotes it to `.venv/` while retaining the previous environment for rollback. When the sibling client is installed, setup also downloads and SHA-256 verifies the pinned rights-approved Template Gallery snapshot and bundles it under `web/template-gallery` so normal use does not wait on Hub media requests. Four permission-dependent preview files are currently unavailable; their templates remain usable and do not request those files.
+MoDiff's installer owns the executable Python/Torch environment. The project is intentionally marked `uv`-unmanaged, so ordinary `uv sync` and `uv run` are not supported setup or launch commands. The explicit `uv run --no-project --no-sync ... -m modiff.dev` bootstrap described above delegates to this same installer without project resolution. The installer stages a fresh environment, checks its package policy and a real device tensor, then atomically promotes it to `.venv/` while retaining the previous environment for rollback. When the sibling client is installed, setup also downloads and SHA-256 verifies the pinned rights-approved Template Gallery snapshot and bundles it under `web/template-gallery` so normal use does not wait on Hub media requests. Four permission-dependent preview files are currently unavailable; their templates remain usable and do not request those files.
 
-| Installer choice | Managed profile | Current scope |
-| --- | --- | --- |
-| `auto` | Host-dependent | Selects a qualified profile or a safe CPU fallback. |
-| `nvidia` | `nvidia-cuda` | Linux/Windows NVIDIA with the reviewed CUDA 12.8 PyTorch profile. |
-| `amd` | OS-dependent AMD profile | Qualified Linux AMD/ROCm hosts. Windows is a conditional official platform, but MoDiff blocks installation until the complete SDK wheel set and physical proof are pinned. |
-| `intel` | `intel-xpu` | Preview PyTorch XPU profile for supported Intel Arc and integrated graphics on x86-64 Linux/Windows. |
-| `mps` | `apple-mps` | Apple Silicon using the reviewed MPS-capable PyTorch profile. |
-| `cpu` | `cpu` | Portable CPU environment for development and fallback. |
+| Installer choice | Managed profile          | Current scope                                                                                                                                                              |
+| ---------------- | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `auto`           | Host-dependent           | Selects a qualified profile or a safe CPU fallback.                                                                                                                        |
+| `nvidia`         | `nvidia-cuda`            | Linux/Windows NVIDIA with the reviewed CUDA 12.8 PyTorch profile.                                                                                                          |
+| `amd`            | OS-dependent AMD profile | Qualified Linux AMD/ROCm hosts. Windows is a conditional official platform, but MoDiff blocks installation until the complete SDK wheel set and physical proof are pinned. |
+| `intel`          | `intel-xpu`              | Preview PyTorch XPU profile for supported Intel Arc and integrated graphics on x86-64 Linux/Windows.                                                                       |
+| `mps`            | `apple-mps`              | Apple Silicon using the reviewed MPS-capable PyTorch profile.                                                                                                              |
+| `cpu`            | `cpu`                    | Portable CPU environment for development and fallback.                                                                                                                     |
 
 If an installation was interrupted, resume its external journal instead of
 starting unrelated setup work:
@@ -290,6 +359,27 @@ See [docs/api-reference.md](docs/api-reference.md) for route groups and trust im
 
 The Modular Diffusers integration is documented in [modules/ModularDiffusers/README.md](modules/ModularDiffusers/README.md). MoDiff owns the pipeline configuration schema used by its dynamic node contracts while relying on upstream Diffusers for model and pipeline execution.
 
+For the current task browser, picker behavior and qualification limits, see
+[Workflow authoring and model selection](docs/workflow-authoring-ux.md).
+
+## Custom nodes
+
+Open **Nodes → Add custom node** for Local, Hugging Face or Git. Intentional Add/Load
+validates and enables code in one action; remote revisions are pinned internally.
+Drop a structured Python node file onto the canvas to import and insert it.
+Files/packages in `custom/` appear automatically without executing; management
+provides Load/Reload/Disable. Python runs with backend permissions, so only load
+trusted code. Dependencies are checked, not installed automatically.
+See [Developing custom nodes](docs/custom-nodes.md) for contracts and examples.
+
+Approved Modular blocks without model ports receive a **Models** input when their
+Python contract requires components. Connect **Load Models → Pipeline Components**
+to reuse compatible loaded weights. The [VAE reconstruction example](examples/custom_nodes/ModularImageReconstruction)
+demonstrates this without separate family-specific nodes or implicit model downloads.
+For additional weights, approved blocks with official component types also expose
+**Load Models — [block name]**. Select pinned, downloaded component sources and use
+**Custom** memory policy; connect the resulting components to the block's Models input.
+
 ## Updating and recovery
 
 Stop the foreground application with `Ctrl+C` and update both sibling
@@ -339,7 +429,9 @@ Do not edit `web/assets/index.js` or `web/assets/index.css` by hand. They are ge
 
 The normal installer materializes `web/template-gallery/` for that
 installation. Treat it as downloaded runtime data: do not add it to Git or a
-normal remote-asset release package.
+normal remote-asset release package. Gallery status and repair use the same
+immutable Dataset manifest in both the remote release and installer-built
+local bundle.
 
 For adjacent checkouts, an exact mirror can be performed with a platform tool after confirming both paths:
 

SECURITY.md

@@ -12,9 +12,9 @@ Do not expose MoDiff directly to an untrusted LAN, the public internet, a shared
 
 MoDiff is designed to execute Python and model code:
 
-- Custom-module installation can clone a Git repository or copy a local directory into `custom/`, then import it into the live registry.
+- Intentional Add/Load/Reload authorizes custom Python with backend permissions in one action, binding its exact source/dependency hash. Discovery, refresh and workflow imports do not grant permission. Failed imports remain disabled. Custom web fields share the code identity and browser-origin permissions.
 - Reviewed model-execution libraries maintained by Hugging Face run in the backend process with the same filesystem, network, CPU, and accelerator access as MoDiff. Official maintenance reduces neither package supply-chain risk nor the need to review the selected version and integration.
-- Repository-supplied Python would run with backend-process permissions. Current custom Modular Diffusers paths are `contract_only` and reject `trust_remote_code` before model construction; exact cached 40-character commits are still required for Hub contract preview. Do not weaken that fail-closed boundary or accept moving branches/tags if executable support is added later.
+- Repository-supplied Python would run with backend-process permissions. The historical custom Modular Diffusers paths are `contract_only` and reject `trust_remote_code` before model construction; exact cached 40-character commits are still required for Hub contract preview. That historical contract-only path remains fail closed. The separate [Custom nodes flow](docs/custom-nodes.md) can execute operator-approved, content-bound local copies of immutable Hub blocks; graph trust flags cannot authorize it. The Add flow resolves branches/tags to immutable commits before downloading or enabling code.
 - Model deserialization and optional native/CUDA packages have their own supply-chain and memory-safety risks.
 - Workflows can allocate substantial CPU, RAM, accelerator memory, disk, and network bandwidth.