Massive sync batch 1

.clinerules

@@ -0,0 +1,473 @@
+# Development Guide for Pinokio Projects
+
+## Non-Negotiable Execution Workflow
+
+To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.
+1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.
+2. **Example Lock-in:** Identify the closest matching script in `C:\pinokio\prototype\system\examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.
+3. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, etc.). Confirm each item is ticked **before** making changes.
+4. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.
+5. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.
+
+If any step cannot be completed, stop immediately and ask the user how to proceed. These five steps are mandatory for every session.
+
+### Critical Pattern Lock: Capturing Web UI URLs
+
+When writing `start.js` (or any script that needs to surface a web URL for a server):
+
+1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**
+```javascript
+on: [{
+  event: "/(http:\\/\\/[0-9.:]+)/",
+  done: true
+}]
+```
+
+2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**
+```javascript
+{
+  method: "local.set",
+  params: {
+    url: "{{input.event[1]}}"
+  }
+}
+```
+
+3. Always try to come up with the most generic regex.
+4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.
+
+Deviation from this pattern requires written approval from the user.
+
+- Make sure to keep this entire document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.
+- When writing pinokio scripts, ALWAYS check the examples folder (in C:\pinokio\prototype\system\examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.
+- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md to use the correct syntax instead of assuming the syntax.
+- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.
+- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.
+
+## Determine User Intent
+If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to
+
+1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.
+2. A Demo: the intent may be a 1-click launcher for the demo
+3. Open source project: the intent may be a 1-click launcher for the project 
+4. Regular website: the intent may be to clone the website and a launcher.
+5. There can be other cases, but try to guess.
+
+## Project Structure
+
+Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:
+
+Pinokio projects follow a standardized structure with app logic separated from launcher scripts:
+
+```
+project-root/
+├── app/                 # Self-contained app logic (can be standalone repo)
+│   ├── package.json     # Node.js projects
+│   ├── requirements.txt # Python projects
+│   └── ...              # Other language-specific files
+├── README.md            # Documentation
+├── install.js           # Installation script
+├── start.js             # Launch script
+├── update.js            # Update script (for updating the scripts and app logic to the latest)
+├── reset.js             # Reset dependencies script
+├── pinokio.js           # UI generator script
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+- Keep app code in `/app` folder only (never in root)
+- Store all launcher files in project root (never in `/app`)
+- `/app` folder should be self-contained and publishable
+
+
+The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):
+
+```
+project-root/
+├── index.html           # The serverless web app entry point
+├── ...
+├── README.md            # Documentation
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (C:\pinokio\prototype\system\examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.
+
+## Launcher Project Working Directory
+
+- The project working directory for a script is always the same directory as the script location.
+- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.
+- If the launcher files are in the project root path, then the default path for shell execution is the project root.
+- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.
+
+Example: in the following project structure:
+
+```
+project-root/
+├── pinokio/                 # Pinokio launcher folder
+│    ├── start.js             # Launch script
+│    ├── pinokio.js           # UI generator script
+│    └── pinokio.json         # Metadata (title, description, icon)
+└─── backend/
+     ├── requirements.txt          # App dependencies
+     └── app.py                    # App code
+```
+
+The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:
+
+```
+{
+  run: [{
+    ...
+  }, {
+    method: "shell.run",
+    params: {
+      message: "python app.py",
+      venv: "env",
+      path: "../backend"
+    }
+  }, {
+    ...
+  }]
+}
+```
+
+## Development Workflow
+
+### 1. Understanding the Project
+- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)
+- If no `SPEC.md` exists, build based on user requirements
+### 2. Modifying Existing Launcher Projects
+If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.
+- **Preserve existing functionality:** Only modify necessary parts
+- **Don't touch working scripts:** Unless adding/updating specific commands
+- **Follow existing conventions:** Match the style and structure already present
+### 3. Try to adopt from examples as much as possible
+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (C:\pinokio\prototype\system\examples) to see if you can adopt them instead of coming up everything from scratch.
+- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.
+### 4. Writing from scratch as a last resort
+If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.
+### 5. Debugging
+When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.
+
+## Script Requirements
+
+### 1. 1-click launchable
+- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.
+
+### 2. Write Documentation
+- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:
+  - What the app does
+  - How to use the app
+  - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)
+
+## Types of launchers
+## 1. Launching servers
+- When an app requires launching a server, here are the commonly used scripts:
+  - `install.js`: a script to install the app
+  - `start.js`: a script to start the app
+  - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch
+  - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)
+  - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.
+  - `pinokio.json`: For metadata
+
+Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:
+
+```javascript
+module.exports = {
+  // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.
+  daemon: true,
+  run: [
+    {
+      // The "shell.run" API for running a shell session
+      method: "shell.run",
+      params: {
+        // Edit 'venv' to customize the venv folder path
+        venv: "env",
+        // Edit 'env' to customize environment variables (see documentation)
+        env: { },
+        // Edit 'path' to customize the path to start the shell from
+        path: "app",
+        // Edit 'message' to customize the commands, or to run multiple commands
+        message: [
+          "python app.py",
+        ],
+        on: [{
+          // The regular expression pattern to monitor.
+          // Whenever each "event" pattern occurs in the shell terminal, the shell will return,
+          // and the script will go onto the next step.
+          // The regular expression match object will be passed on to the next step as `input.event`
+          // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)
+          "event": "/(http:\/\/\\S+)/", 
+
+          // Use "done": true to move to the next step while keeping the shell alive.
+          // Use "kill": true to move to the next step after killing the shell.
+          "done": true
+        }]
+      }
+    },
+    {
+      // This step sets the local variable 'url'.
+      // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.
+      method: "local.set",
+      params: {
+        // the input.event is the regular expression match object from the previous step
+        // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.
+        // Therefore setting the local variable 'url'
+        url: "{{input.event[1]}}"
+      }
+    }
+  ]
+}
+```
+
+## 2. Launching serverless web apps
+
+- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.
+- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do 
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## 3. Launching quick scripts without web UI
+
+- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.
+- This may include TUI (Terminal User Interface) apps, a simple launcher 
+- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.
+- Here are some examples:
+  - A pinokio script to toggle the desktop theme between dark and light
+    - Write some code (python or javascript or whatever)
+    - Write a `toggle.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes
+  - A pinokio script to fetch some file
+    - Write some code (python or javascript or whatever)
+    - Write a `fetch.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## API
+
+This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:
+1. Check the examples in the C:\pinokio\prototype\system\examples folder
+2. Read the `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md further documentation on the full syntax
+
+### Script API
+
+These APIs can be used to describe each step in a pinokio script:
+- shell.run: run shell commands
+- input: accept user input
+- filepicker: accept file upload
+- fs.write: write to file
+- fs.read: read from file
+- fs.copy: copy files
+- fs.download: download files
+- fs.link: create a symbolic link (or junction on windows) for folders
+- fs.open: open the system file explorer at a given path
+- fs.cat: print file contents
+- jump: jump to a specific step
+- local.set: set local variables for the currently running script
+- json.set: update a json file
+- json.rm: remove keys from a json file
+- json.get: get values from a json file
+- log: print to the web terminal
+- net: make network requests
+- notify: display a notification
+- script.download: download a script from a git uri
+- script.start: start a script
+- script.stop: stop a script
+- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`
+- web.open: open a url in web browser
+- hf.download: huggingfac-cli download API
+### Template variables
+The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:
+- input: An input is a variable that gets passed from one RPC call to the next
+- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.
+- local: local variable object that can be set with `local.set` API
+- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.
+- uri: The current script uri
+- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.
+- cwd: The current script execution folder path
+- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`
+- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64
+- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)
+- gpu: the first available GPU (example: `nvidia`)
+- current: The current variable points to the index of the currently executing instruction within the run array.
+- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)
+- envs: You can access the environment variables of the currently running process with envs object.
+- which: Check whether a command exists (example: `{{which('winget')}}`. Can be used in the `when` attribute of a script step to run commands or install first.
+- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- os: Pinokio exposes the node.js os module through the os variable.
+- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`
+
+## System Capabilities
+### Package Management (Use in Order of Preference)
+The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:
+1. **UV** - For Python packages (preferred over pip)
+2. **NPM** - For Node.js packages  
+3. **Conda** - For cross-platform 3rd party binaries
+4. **Brew** - Mac-only fallback when other options unavailable
+5. **Git** - Full access to git is available.
+**Important:** Include all install commands in the install script for reproducibility.
+### HTTPS Proxy Support
+- All HTTP servers automatically get HTTPS endpoints
+- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`
+- Full proxy list available at: `http://localhost:2019/config/`
+### Pterm Features:
+- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)
+- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)
+- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)
+- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)
+- **Git Operations:** Clone repositories, push to GitHub
+- **GitHub Integration:** Full GitHub CLI support (`gh` commands)
+
+## Troubleshooting with Logs
+Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:
+
+### Log Structure
+In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:
+
+```
+pinokio/
+└── logs/   # Direct user interaction logs
+    ├── api/     # Launcher script logs (install.js, start.js, etc.)
+    ├── dev/     # AI coding tool logs (organized by tool)
+    └── shell/   # Direct user interaction logs
+```
+
+Otherwise, the `logs` folder should be found at project root:
+
+```
+logs/
+├── api/     # Launcher script logs (install.js, start.js, etc.)
+├── dev/     # AI coding tool logs (organized by tool)
+└── shell/   # Direct user interaction logs
+```
+
+### Log File Naming
+- Unix timestamps for each session
+- Special "latest" file contains most recent session logs
+- **Default:** Use "latest" files for current issues
+- **Historical:** Use timestamped files for pattern analysis and the full history.
+
+## Best practices
+### 0. Always reference the logs when debugging
+- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.
+### 1. Shell commands for launching programs
+- Launch flags related
+  - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.
+- Launch IP related
+  - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.
+- Launch Port related
+  - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.
+  - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.
+  - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`
+  - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.
+### 2. shell.run API
+- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.
+### 2. Package managers
+- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.
+- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.
+### 3. Minimal Always
+- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.
+- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.
+- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.
+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `C:\pinokio\api\Z-Image-Pinokio.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.
+  - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.
+- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.
+  - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.
+### 4. Try to support Cross-platform as much as possible
+- Use cross-platform shell commands only.
+- This means, prefer to use commands that work on all platforms instead of the current platform.
+- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.
+- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.
+- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.
+- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.
+### 5. Do not make assumptions about Pinokio API
+- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.
+- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.
+### 6. Scripts must be able to replicate install and launch steps 100%
+- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.
+- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.
+### 7 Dynamic UI rendering
+- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.
+  - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:
+    - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.
+  - Check the examples in the C:\pinokio\prototype\system\examples folder to see how these are being used.
+### 8. No need for stop scripts
+- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script
+### 9. Writing launchers for existing projects
+- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.
+- In most cases, the `README.md` file in the `C:\pinokio\api\Z-Image-Pinokio.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.
+- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.
+### 10. Don't use Docker unless really necessary
+- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.
+### 11. pinokio.json
+- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.
+- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.
+  - If the git repository for the `C:\pinokio\api\Z-Image-Pinokio.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`. 
+### 12. Gitignore
+- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:
+  - Cloning git repositories
+  - Downloading files
+  - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.
+- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.
+
+## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)
+If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:
+
+```
+// install.js
+module.exports = {
+  run: [
+    // Delete this step if your project does not use torch
+    {
+      method: "script.start",
+      params: {
+        uri: "torch.js",
+        params: {
+          path: "app",
+          venv: "venv",                // Edit this to customize the venv folder path
+          // xformers: true   // uncomment this line if your project requires xformers
+          // triton: true   // uncomment this line if your project requires triton
+          // sageattention: true   // uncomment this line if your project requires sageattention
+        }
+      }
+    },
+    // Edit this step with your custom install commands
+    {
+      method: "shell.run",
+      params: {
+        venv: "venv",                // Edit this to customize the venv folder path
+        path: "app",
+        message: [
+          "uv pip install -r requirements.txt"
+        ],
+      }
+    },
+  ]
+}
+```
+
+The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.
+
+
+## Quick Reference
+### Essential Documentation
+- **Pinokio Programming:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Programming Pinokio" section
+- **Dynamic Menus:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Dynamic menu rendering" section  
+- **CLI Commands:** See `PTERM.md` at C:\pinokio\prototype\PTERM.md
+### Common Patterns
+- **Python Virtual Env:** `shell.run` with `venv` attribute
+- **Cross-platform Commands:** Always test on multiple platforms
+- **Error Handling:** Check logs/api for launcher issues
+- **GitHub Operations:** Use `gh` CLI for advanced GitHub features
+## Development Principles
+1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands
+2. **Maintain Separation:** Keep app logic and launchers separate
+3. **Follow Conventions:** Match existing project patterns
+4. **Test Thoroughly:** Use CLI to verify launcher functionality
+5. **Document Changes:** Update relevant metadata and documentation

.cursorrules

@@ -0,0 +1,473 @@
+# Development Guide for Pinokio Projects
+
+## Non-Negotiable Execution Workflow
+
+To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.
+1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.
+2. **Example Lock-in:** Identify the closest matching script in `C:\pinokio\prototype\system\examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.
+3. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, etc.). Confirm each item is ticked **before** making changes.
+4. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.
+5. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.
+
+If any step cannot be completed, stop immediately and ask the user how to proceed. These five steps are mandatory for every session.
+
+### Critical Pattern Lock: Capturing Web UI URLs
+
+When writing `start.js` (or any script that needs to surface a web URL for a server):
+
+1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**
+```javascript
+on: [{
+  event: "/(http:\\/\\/[0-9.:]+)/",
+  done: true
+}]
+```
+
+2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**
+```javascript
+{
+  method: "local.set",
+  params: {
+    url: "{{input.event[1]}}"
+  }
+}
+```
+
+3. Always try to come up with the most generic regex.
+4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.
+
+Deviation from this pattern requires written approval from the user.
+
+- Make sure to keep this entire document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.
+- When writing pinokio scripts, ALWAYS check the examples folder (in C:\pinokio\prototype\system\examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.
+- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md to use the correct syntax instead of assuming the syntax.
+- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.
+- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.
+
+## Determine User Intent
+If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to
+
+1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.
+2. A Demo: the intent may be a 1-click launcher for the demo
+3. Open source project: the intent may be a 1-click launcher for the project 
+4. Regular website: the intent may be to clone the website and a launcher.
+5. There can be other cases, but try to guess.
+
+## Project Structure
+
+Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:
+
+Pinokio projects follow a standardized structure with app logic separated from launcher scripts:
+
+```
+project-root/
+├── app/                 # Self-contained app logic (can be standalone repo)
+│   ├── package.json     # Node.js projects
+│   ├── requirements.txt # Python projects
+│   └── ...              # Other language-specific files
+├── README.md            # Documentation
+├── install.js           # Installation script
+├── start.js             # Launch script
+├── update.js            # Update script (for updating the scripts and app logic to the latest)
+├── reset.js             # Reset dependencies script
+├── pinokio.js           # UI generator script
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+- Keep app code in `/app` folder only (never in root)
+- Store all launcher files in project root (never in `/app`)
+- `/app` folder should be self-contained and publishable
+
+
+The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):
+
+```
+project-root/
+├── index.html           # The serverless web app entry point
+├── ...
+├── README.md            # Documentation
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (C:\pinokio\prototype\system\examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.
+
+## Launcher Project Working Directory
+
+- The project working directory for a script is always the same directory as the script location.
+- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.
+- If the launcher files are in the project root path, then the default path for shell execution is the project root.
+- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.
+
+Example: in the following project structure:
+
+```
+project-root/
+├── pinokio/                 # Pinokio launcher folder
+│    ├── start.js             # Launch script
+│    ├── pinokio.js           # UI generator script
+│    └── pinokio.json         # Metadata (title, description, icon)
+└─── backend/
+     ├── requirements.txt          # App dependencies
+     └── app.py                    # App code
+```
+
+The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:
+
+```
+{
+  run: [{
+    ...
+  }, {
+    method: "shell.run",
+    params: {
+      message: "python app.py",
+      venv: "env",
+      path: "../backend"
+    }
+  }, {
+    ...
+  }]
+}
+```
+
+## Development Workflow
+
+### 1. Understanding the Project
+- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)
+- If no `SPEC.md` exists, build based on user requirements
+### 2. Modifying Existing Launcher Projects
+If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.
+- **Preserve existing functionality:** Only modify necessary parts
+- **Don't touch working scripts:** Unless adding/updating specific commands
+- **Follow existing conventions:** Match the style and structure already present
+### 3. Try to adopt from examples as much as possible
+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (C:\pinokio\prototype\system\examples) to see if you can adopt them instead of coming up everything from scratch.
+- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.
+### 4. Writing from scratch as a last resort
+If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.
+### 5. Debugging
+When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.
+
+## Script Requirements
+
+### 1. 1-click launchable
+- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.
+
+### 2. Write Documentation
+- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:
+  - What the app does
+  - How to use the app
+  - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)
+
+## Types of launchers
+## 1. Launching servers
+- When an app requires launching a server, here are the commonly used scripts:
+  - `install.js`: a script to install the app
+  - `start.js`: a script to start the app
+  - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch
+  - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)
+  - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.
+  - `pinokio.json`: For metadata
+
+Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:
+
+```javascript
+module.exports = {
+  // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.
+  daemon: true,
+  run: [
+    {
+      // The "shell.run" API for running a shell session
+      method: "shell.run",
+      params: {
+        // Edit 'venv' to customize the venv folder path
+        venv: "env",
+        // Edit 'env' to customize environment variables (see documentation)
+        env: { },
+        // Edit 'path' to customize the path to start the shell from
+        path: "app",
+        // Edit 'message' to customize the commands, or to run multiple commands
+        message: [
+          "python app.py",
+        ],
+        on: [{
+          // The regular expression pattern to monitor.
+          // Whenever each "event" pattern occurs in the shell terminal, the shell will return,
+          // and the script will go onto the next step.
+          // The regular expression match object will be passed on to the next step as `input.event`
+          // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)
+          "event": "/(http:\/\/\\S+)/", 
+
+          // Use "done": true to move to the next step while keeping the shell alive.
+          // Use "kill": true to move to the next step after killing the shell.
+          "done": true
+        }]
+      }
+    },
+    {
+      // This step sets the local variable 'url'.
+      // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.
+      method: "local.set",
+      params: {
+        // the input.event is the regular expression match object from the previous step
+        // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.
+        // Therefore setting the local variable 'url'
+        url: "{{input.event[1]}}"
+      }
+    }
+  ]
+}
+```
+
+## 2. Launching serverless web apps
+
+- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.
+- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do 
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## 3. Launching quick scripts without web UI
+
+- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.
+- This may include TUI (Terminal User Interface) apps, a simple launcher 
+- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.
+- Here are some examples:
+  - A pinokio script to toggle the desktop theme between dark and light
+    - Write some code (python or javascript or whatever)
+    - Write a `toggle.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes
+  - A pinokio script to fetch some file
+    - Write some code (python or javascript or whatever)
+    - Write a `fetch.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## API
+
+This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:
+1. Check the examples in the C:\pinokio\prototype\system\examples folder
+2. Read the `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md further documentation on the full syntax
+
+### Script API
+
+These APIs can be used to describe each step in a pinokio script:
+- shell.run: run shell commands
+- input: accept user input
+- filepicker: accept file upload
+- fs.write: write to file
+- fs.read: read from file
+- fs.copy: copy files
+- fs.download: download files
+- fs.link: create a symbolic link (or junction on windows) for folders
+- fs.open: open the system file explorer at a given path
+- fs.cat: print file contents
+- jump: jump to a specific step
+- local.set: set local variables for the currently running script
+- json.set: update a json file
+- json.rm: remove keys from a json file
+- json.get: get values from a json file
+- log: print to the web terminal
+- net: make network requests
+- notify: display a notification
+- script.download: download a script from a git uri
+- script.start: start a script
+- script.stop: stop a script
+- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`
+- web.open: open a url in web browser
+- hf.download: huggingfac-cli download API
+### Template variables
+The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:
+- input: An input is a variable that gets passed from one RPC call to the next
+- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.
+- local: local variable object that can be set with `local.set` API
+- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.
+- uri: The current script uri
+- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.
+- cwd: The current script execution folder path
+- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`
+- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64
+- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)
+- gpu: the first available GPU (example: `nvidia`)
+- current: The current variable points to the index of the currently executing instruction within the run array.
+- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)
+- envs: You can access the environment variables of the currently running process with envs object.
+- which: Check whether a command exists (example: `{{which('winget')}}`. Can be used in the `when` attribute of a script step to run commands or install first.
+- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- os: Pinokio exposes the node.js os module through the os variable.
+- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`
+
+## System Capabilities
+### Package Management (Use in Order of Preference)
+The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:
+1. **UV** - For Python packages (preferred over pip)
+2. **NPM** - For Node.js packages  
+3. **Conda** - For cross-platform 3rd party binaries
+4. **Brew** - Mac-only fallback when other options unavailable
+5. **Git** - Full access to git is available.
+**Important:** Include all install commands in the install script for reproducibility.
+### HTTPS Proxy Support
+- All HTTP servers automatically get HTTPS endpoints
+- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`
+- Full proxy list available at: `http://localhost:2019/config/`
+### Pterm Features:
+- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)
+- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)
+- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)
+- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)
+- **Git Operations:** Clone repositories, push to GitHub
+- **GitHub Integration:** Full GitHub CLI support (`gh` commands)
+
+## Troubleshooting with Logs
+Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:
+
+### Log Structure
+In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:
+
+```
+pinokio/
+└── logs/   # Direct user interaction logs
+    ├── api/     # Launcher script logs (install.js, start.js, etc.)
+    ├── dev/     # AI coding tool logs (organized by tool)
+    └── shell/   # Direct user interaction logs
+```
+
+Otherwise, the `logs` folder should be found at project root:
+
+```
+logs/
+├── api/     # Launcher script logs (install.js, start.js, etc.)
+├── dev/     # AI coding tool logs (organized by tool)
+└── shell/   # Direct user interaction logs
+```
+
+### Log File Naming
+- Unix timestamps for each session
+- Special "latest" file contains most recent session logs
+- **Default:** Use "latest" files for current issues
+- **Historical:** Use timestamped files for pattern analysis and the full history.
+
+## Best practices
+### 0. Always reference the logs when debugging
+- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.
+### 1. Shell commands for launching programs
+- Launch flags related
+  - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.
+- Launch IP related
+  - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.
+- Launch Port related
+  - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.
+  - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.
+  - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`
+  - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.
+### 2. shell.run API
+- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.
+### 2. Package managers
+- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.
+- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.
+### 3. Minimal Always
+- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.
+- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.
+- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.
+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `C:\pinokio\api\Z-Image-Pinokio.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.
+  - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.
+- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.
+  - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.
+### 4. Try to support Cross-platform as much as possible
+- Use cross-platform shell commands only.
+- This means, prefer to use commands that work on all platforms instead of the current platform.
+- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.
+- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.
+- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.
+- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.
+### 5. Do not make assumptions about Pinokio API
+- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.
+- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.
+### 6. Scripts must be able to replicate install and launch steps 100%
+- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.
+- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.
+### 7 Dynamic UI rendering
+- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.
+  - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:
+    - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.
+  - Check the examples in the C:\pinokio\prototype\system\examples folder to see how these are being used.
+### 8. No need for stop scripts
+- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script
+### 9. Writing launchers for existing projects
+- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.
+- In most cases, the `README.md` file in the `C:\pinokio\api\Z-Image-Pinokio.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.
+- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.
+### 10. Don't use Docker unless really necessary
+- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.
+### 11. pinokio.json
+- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.
+- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.
+  - If the git repository for the `C:\pinokio\api\Z-Image-Pinokio.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`. 
+### 12. Gitignore
+- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:
+  - Cloning git repositories
+  - Downloading files
+  - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.
+- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.
+
+## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)
+If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:
+
+```
+// install.js
+module.exports = {
+  run: [
+    // Delete this step if your project does not use torch
+    {
+      method: "script.start",
+      params: {
+        uri: "torch.js",
+        params: {
+          path: "app",
+          venv: "venv",                // Edit this to customize the venv folder path
+          // xformers: true   // uncomment this line if your project requires xformers
+          // triton: true   // uncomment this line if your project requires triton
+          // sageattention: true   // uncomment this line if your project requires sageattention
+        }
+      }
+    },
+    // Edit this step with your custom install commands
+    {
+      method: "shell.run",
+      params: {
+        venv: "venv",                // Edit this to customize the venv folder path
+        path: "app",
+        message: [
+          "uv pip install -r requirements.txt"
+        ],
+      }
+    },
+  ]
+}
+```
+
+The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.
+
+
+## Quick Reference
+### Essential Documentation
+- **Pinokio Programming:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Programming Pinokio" section
+- **Dynamic Menus:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Dynamic menu rendering" section  
+- **CLI Commands:** See `PTERM.md` at C:\pinokio\prototype\PTERM.md
+### Common Patterns
+- **Python Virtual Env:** `shell.run` with `venv` attribute
+- **Cross-platform Commands:** Always test on multiple platforms
+- **Error Handling:** Check logs/api for launcher issues
+- **GitHub Operations:** Use `gh` CLI for advanced GitHub features
+## Development Principles
+1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands
+2. **Maintain Separation:** Keep app logic and launchers separate
+3. **Follow Conventions:** Match existing project patterns
+4. **Test Thoroughly:** Use CLI to verify launcher functionality
+5. **Document Changes:** Update relevant metadata and documentation

.geminiignore

@@ -0,0 +1,6 @@
+ENVIRONMENT
+!/logs
+!/GEMINI.md
+!/SPEC.md
+!/app
+!C:\pinokio

.gitattributes

@@ -33,3 +33,113 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+icon.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/0104dcbf4ecd060d0f9908e75116ea3b1283defbe8d1daa5b2aebfdd27a50720/184610_17e9.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/0115b4830ff0665ad782cfb50ea81e83d576c6fe5787c6c33a77c9ea179743ca/174332_8794.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/01ad82d69b6d2baad6c60480ceb366ed05003c5c92b9c21c0cf4c37c411b3ff8/200033_b851.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/03a7badba46e5b655ff716e02c5996baee5f2e7e4ac5f44d0ad24a61489fadc3/image_195204_7aec6c64.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/048523a346ad5312fb0116b07c6cc9d4d7a7fea69ce7027d7fd7beb01268fc18/092559_b8fc.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/09b443d9c4850dd13d4a39a8edff6b7e68c9f5a428a73fc494ece1fa5066ee0c/201057_0a1c.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/0b504490c285e741239ac4793322e48efc91691c04e98a6c7a3af21d304a5aa4/image.webp filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/0c8c8364e4d7ddeb83cc7c5777e36b5f7687da1bb308d2406fd842ea9f46fa95/i2i_133141_5337.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/0fd950fa33ea4eafe5c16b1cc0eed01eb5ebf2f23b1e6f414533b25180379b05/image_205528_7ee5527a.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/104f4b9668733006f0a761e9778c747031df2334a0dd6f389ae5d49d5cc02b9e/200437_0006.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/10c5d8f6cacea6cc5f16e475aa9c4fdff517728969b2629a26c679c5648135d5/193107_4fa5.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/127b98c0ad0f191eff7d10eba1f1bad79fa49c9889aa3a2dfe12c05d28348aba/095514_01ac.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/12d002a8885b4d41fbb41d98e32ce71f728aa5bde8a939300ed6af71179b599d/103637_26f5.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/168afac92d4203ba0e6fad2bf01e3d1a10295a59cad570e0d32316117755b7e3/composite.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/19b76ad6a7d98ae4eb1d1626871e171b636bb0103bd68fea8ff92685d2207695/160727_8256.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/1a0791be9abd585a9187d0f87b23e9ceafb0d09b978af6f11e5b45999d7ff792/image_203420_c47cecb7.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/1aaa830b48dfb49d28389f438e732a2a73cc948878b7f969802687356e75a63c/173952_0241.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/1cc5d28158556bf5a8eb7992502a482d4b898f463262649559b77a1aaa10fd84/161034_21ec.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/213a256e430446bb846446a77053d3c3e2d5a7e3d40adf060bb1358d2929bed1/193806_c514.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/21db64ee5ade0d05ff3961c7df2ee7016e8a13e954396707b37d42de6b2b32d5/image_233514_3851872b.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/235047bf74248ec689408227f1fb364afb770712ddd3da625a3c660c6a29cc35/background.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/25d5add9dafa195a945d962f6064049cdf902c723358c1eb978615f82c47cd54/123145_46ab.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/2ddd025a39e016cbc97dfd9130f9b1302492be2ba4e33b0acefb761adaa1b14d/image.webp filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/30a053ec6f1d5ed7e7c8397450be98cb173037115d5e03394d99102741d0faf7/195841_e909.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/334d0bc165496fef845d69069319d2e574ef489656422f14f8b4553dff7583f8/184528_885b.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/364d8c3a6f8a226ff370cb2e4f59d8f37f6a23520f322adf77ae3d7d996d6176/191110_1134.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/36e56881752c197dfd65a693b7d7134852117eaa97fbff30739a01390082a69e/i2i_132542_eeff.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/3948f38c2fecc017128b1b7eb41f3f327fc06aba806d9bdc886368ef3228319d/193253_2da5.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/3ba5ac95cfc5de2c15635232fb57a2b719388c6891302cbc32127defbdbde758/image_123428_296a1507.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/3ece35a85d9ffae8b8270058ab850d5d419785b01ec68819a3c6aace56673bc4/161239_fdad.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/41fbb34e88e6b1e8e459504ada125267c8bf7acc97ac8d364df233623828879d/i2i_132029_852c.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/42a832bbae0d16a84c93cd3c85948cbd891e5ae55ec6e05ab905fb1dde3af489/190833_457f.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/48c7aa110490f236dc8353a8a4b7a1b9610cd489d0723e9acc4671ffbc1fd9e5/211433_2542.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/4ca1ba410ee0e412d101e38b900f26235b1ac4ba2bd20e3a9cb4695a31770b8b/152321_78e9.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/4dbf29b962ea1a07327116aebf6339935f80e66be6405544b1724c18a97570ca/193937_dfc2.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/581d417e02c3368e61357f1a1962528ed7c811feed930fe2a2b6e516119793f3/173802_a005.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/5a8794b56d666c48284a1a7079db5748f4a7b9cdb518dd73cd49480fd398d0ac/image_072130_c450deca.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/5aa9e5d0f84a6e9ced3ca3d3ed41b6dc6628109bfee2aaa1e5aa42163f4a3b97/215755_3063.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/5bb5d3fcb15276fa3c3d5448ee43411958d13c6609074292b4d18b72712b5ff8/background.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/5cbded92848e091bb7da4277864735a0b999a61c0a6eb4e7d20c4ba5989de823/image_20251215_140351_e26969b3.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/5e36d438233be1a028e08aabe7bec7320eabc9bd57f70469f050d7abe02a41cf/194243_9831.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/5e90cebdccc72250a480557acc5aa3b248778a5bd5767a7a15753da423806b45/215620_c917.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/5e94d91d3600218df343e522fc1ab1d9bf3818bdb467e04a2470680eaac08d09/i2i_212159_0129.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/604753b372bf97c9157362cba3fb9fc06d31e636c6493872e7a87396f948cbc1/194225_7e4f.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/6362b7e79ecbab45c800a3500c6d14b34e7667a7d592c694785cd9741ab32478/173857_2204.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/68805bb2ae22568b71d47b0ab980b2b7a65738ef9b4c42cc26d5c16c7573ef09/image_201312_65ab1f2a.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/6969fe7dea7e67d0f76db8fd75aafea70efced242795740399463f3415a41bab/123351_737c.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/6baa98a710677fb71b4f19984a48a78e17575d907790fedfd6c209192e7d423a/image_082956_a93da5e5.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/6c9ccf2b46e15c78e1a4a78e059da0657cf03c1f92e21c35245db5ff9cff9833/081829_8f85.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/6d1de0d9b12bd2823f705bfe580f21b97530b700445a5d05b142bef29f0e683f/image_144045_e7f50021.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/6fb901af77289410341f57fc6dbb20d7360b0504eadfaaf9e564b9a89d93beeb/image_080709_eeb69d7f.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/73bc0a86c1b286167059ede3951eb45484eb1b8641142775adb88c9655712e26/image_153303_87cc6baf.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/789a6a4f2bfb98534624eaac9b35bffd7c86cfd6a5eb6448270e059b69973a5c/image_223009_335cd589.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/78a983fa831ec39adde863986ad7fbd99f269065027d330abd9cfdf960a2bf6f/161445_2360.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/79f2384913ad201fce177b1cfaefc63274471339f051cd8c07ed1bfa61660155/160932_73bd.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/7bb7366e4ee283ebd19fca4f8866abcd0118d1c4082a961032d2d27759ed080c/174427_026c.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/7ce8afffd4164ec53eae38def96ab0ab0aecf5740b98ef367a4513535862de43/image_235656_313ac3ec.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/80fa2d35192ee203c208228ced366a62942ee43299d805ead746a7babba243b8/173055_9027.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/82584677e390c6b1e631a2f3aa09593c554bb1f9d814c87a873f399f117d8021/212625_ffff.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/8600377e1d617099c004bee769e5277d83c81224a2666ce6bedb9aec8e44719d/184216_652e.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/88098f462101fcaba9f43b9964bfe86ea774e428db93ae0a17cb115f37f0bee1/background.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/8bc420f6018d03774a50f6b6024ea8dc391b186204a1a03c420b4db129a24f96/composite.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/90094265faa035aa3f7c73bf36190fb7a5e673a081764bec856bca319da1bda3/composite.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/9482c3341cc290e034761d3233c1d16cc226d029961d57683519f92174854bd3/193438_a1ee.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/9496fb6dcc061cad6ad2e85f54031653c511e8c3be22010db1bf8d34550c3dce/image_20251218_222807_672f094d.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/9741f9066e124f0ab755d60cba06cd3c1c2225942235d4e57b43f270fb429f7d/184933_cae6.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/99a68ec3226f3adf12302081ec81fc7d4c1b159a5b400c646e37d9eecfcb9df5/i2i_133331_bd3f.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/9d88f78acbbaba9012a69cbdb345a1a04772aa08b95de90503ea7b5b0a7909b5/111425_13dc.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/a310f1f579e215476409d71940c213a4669deb2ad87d93c9cdaa6472ae3ff07f/image_192955_d771b409.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/a327c7e44941b87ce775f556197b5b61e3eb802a20d58157e9ae497291b02fd9/composite.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/a419b1307c2d8b2aae24cd649f67d04e6cbcc8b9bb06b401d02e82ebbf106309/composite.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/a5a2b9cd94e0b16826bad2340e7d415100509e7902b11b04e8e6c0065a59a67e/image_124156_4e4c3b01.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/a61f1a99c73b58c3185054b9691872f4faaf0785579e272d9d1506758ed18fa5/105143_2ebb.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/b224f120a3a95f6b21186549fe6ad1a9cf623a8e19df0b9321e505205c512801/193626_2c54.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/b229f7bc28193e011c40ff909130dba345f2c1ef310c0df20215c6d7a50d30b2/161342_bae4.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/b28b50325c1cf8c0c59528767652b8138426d4f049111cd040b0a8b6071c6cc7/background.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/b5e1abda68bdb09921d5fe24e19a2e4c6f98f27ce8f6fbaccba4e9046faf3fac/174047_6b5c.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/b9e91145e65105a2cdabde49b2c2f66b6dc10588f3724d3ee1c80397f2e0e46d/image_231332_7275a0ba.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/ba095bf3262363416c6b61d8e0a42ab21dda842620af26d2f533725874198e69/image_155912_1b051896.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/ba465b6c2b08d01bcbd889f52b94491df760457cd14e8645c25928ab7dc009ec/122427_380c.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/ba57eb2021b31bf9e58b8bbd2f9d06df8fbbca320d83dcda165d759733c2e407/background.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/ba57eb2021b31bf9e58b8bbd2f9d06df8fbbca320d83dcda165d759733c2e407/composite.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/ba66073accdf211821de826075fb88898d1503bd3d4ccb43b7ef2ae4adccce5b/122925_cb76.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/bf69fd4dbc0c7660c81d7a4d56f57357b4f72e23d6639a91cc4b271fc89441a8/104640_444b.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/bf992d41695be78a26c4c967a21428ecf54daa232524d8afabb1e35610c8ebf0/image_20251219_064526_8667a4f6.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/c83545d19a58472553923ef0830c8e191cf17049ca43d87dfdb46cb51126840f/111707_46ef.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/cab4e1ce944cbd8cb3f4b34c2088008d6e58123b139c604f7d50be376c7e5542/image_213744_925f86e3.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/d451bcbf620bf662e88d6818c1862e555dad7f9fc94d2e3753bc55d08490e571/image_215853_7f190bf1.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/d66d5cfbc1a9e8de88d1e2f4b9c0bc487888e6746a3ed2cb9a71b519b8478d2f/194110_e977.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/d88a6fd16b470f47e5f4d196e2e5ab4b08bee25518b873cc76c7691821509103/image_001837_2435da99.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/dbdd135cd6e0850542cbdeb8904c7088d25fb95407605086aea738e422fcc77d/174238_0267.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/dda7f0466f527a534776315dc588949e9f02727a121b8d06ba5cd2fa8a50052a/161137_1198.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/de579b6cd28da8cc5272e99cf06903d28dd563614e83460e54b027c96f3739de/image_074420_2ebe2973.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/e2faf61c821dd449470a0c5c052a3f598e84f92299b1173ca189a9a4a7b0d4c1/image_004017_cf393c0b.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/e88e22c91caa1107d3b3fc8adf430b6e61271d5e1066156b001e390bd6fc8592/image_133821_be3e1e18.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/e946e222a8e87fd9729a28c94c357e3f222e889a722970a727dfac424b325f1f/composite.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/eb27ebd4d6a857f78595a8907296ec35edb15e0dbfadc62e93217824871e59e2/173523_769d.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/eb2b854a5861e74ee982ddc5e4394aa2e1a345957e719b00eb1a2755389b2823/image_211636_9906c971.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/ec6d4ec205e70da65fdc19331e9b3d02336fe3893aca89f5a97f09154fb5302b/image_225150_27c33ecc.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/ee91807ad68539352d2125c84be145425c53067892649c95de0456ba649a246a/184401_9308.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/efe7381de79d01496132f63365c9442352a2888f7074b022a1db19be4882d55f/174143_0463.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/f215759df2dc00f8204147d4e00c059a8c1edebae52fe79a5273d3bb1f44ff80/i2i_133506_04ce.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/f86e040927a38966bed4f3b18487686c0793aca3fe2e48c517127f8e781edc1c/194021_11a6.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/f8e92be1443adbba50d91201763b6ce49233664ca9b311e815aee2df1e1efad5/160830_7b26.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/fc3de51408f1e65637461b53a0981a7f9c008f178fabbf0aadbd44e6caa4392c/image_010200_60704c43.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/fdb6ba5ae6edc725e2a6205d4bb1c535667ab0fdf5ba5da8c44d55f8b267cc5e/183514_9d21.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/fe921dea56812384a39b85df341f1199e27c1e95f15358a13964a3c2d37fbce0/image_150656_45c20713.png filter=lfs diff=lfs merge=lfs -text
+cache/GRADIO_TEMP_DIR/fe99491cc85d1ad274a96752b812e88d23bb69729a89104b196847af7ae2f7da/i2i_205330_a263.png filter=lfs diff=lfs merge=lfs -text
+cache/HF_HOME/hub/models--Tongyi-MAI--Z-Image-Turbo/snapshots/5f4b9cbb80cc95ba44fe6667dfd75710f7db2947/tokenizer/tokenizer.json filter=lfs diff=lfs merge=lfs -text

.gitignore

@@ -0,0 +1,71 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+env/
+venv/
+ENV/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# Virtual environments
+env/
+venv/
+ENV/
+.venv
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# OS
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Model cache and outputs
+*.ckpt
+*.safetensors
+*.pth
+*.bin
+models/
+checkpoints/
+outputs/
+*.jpg
+*.jpeg
+example.png
+
+# Gradio
+gradio_cached_examples/
+flagged/
+
+# Logs
+*.log
+logs/
+
+# Temporary files
+tmp/
+temp/
+*.tmp
+
+#Custom MOD and Lora
+MOD/
+lora/

.windsurfrules

@@ -0,0 +1,473 @@
+# Development Guide for Pinokio Projects
+
+## Non-Negotiable Execution Workflow
+
+To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.
+1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.
+2. **Example Lock-in:** Identify the closest matching script in `C:\pinokio\prototype\system\examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.
+3. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, etc.). Confirm each item is ticked **before** making changes.
+4. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.
+5. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.
+
+If any step cannot be completed, stop immediately and ask the user how to proceed. These five steps are mandatory for every session.
+
+### Critical Pattern Lock: Capturing Web UI URLs
+
+When writing `start.js` (or any script that needs to surface a web URL for a server):
+
+1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**
+```javascript
+on: [{
+  event: "/(http:\\/\\/[0-9.:]+)/",
+  done: true
+}]
+```
+
+2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**
+```javascript
+{
+  method: "local.set",
+  params: {
+    url: "{{input.event[1]}}"
+  }
+}
+```
+
+3. Always try to come up with the most generic regex.
+4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.
+
+Deviation from this pattern requires written approval from the user.
+
+- Make sure to keep this entire document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.
+- When writing pinokio scripts, ALWAYS check the examples folder (in C:\pinokio\prototype\system\examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.
+- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md to use the correct syntax instead of assuming the syntax.
+- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.
+- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.
+
+## Determine User Intent
+If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to
+
+1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.
+2. A Demo: the intent may be a 1-click launcher for the demo
+3. Open source project: the intent may be a 1-click launcher for the project 
+4. Regular website: the intent may be to clone the website and a launcher.
+5. There can be other cases, but try to guess.
+
+## Project Structure
+
+Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:
+
+Pinokio projects follow a standardized structure with app logic separated from launcher scripts:
+
+```
+project-root/
+├── app/                 # Self-contained app logic (can be standalone repo)
+│   ├── package.json     # Node.js projects
+│   ├── requirements.txt # Python projects
+│   └── ...              # Other language-specific files
+├── README.md            # Documentation
+├── install.js           # Installation script
+├── start.js             # Launch script
+├── update.js            # Update script (for updating the scripts and app logic to the latest)
+├── reset.js             # Reset dependencies script
+├── pinokio.js           # UI generator script
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+- Keep app code in `/app` folder only (never in root)
+- Store all launcher files in project root (never in `/app`)
+- `/app` folder should be self-contained and publishable
+
+
+The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):
+
+```
+project-root/
+├── index.html           # The serverless web app entry point
+├── ...
+├── README.md            # Documentation
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (C:\pinokio\prototype\system\examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.
+
+## Launcher Project Working Directory
+
+- The project working directory for a script is always the same directory as the script location.
+- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.
+- If the launcher files are in the project root path, then the default path for shell execution is the project root.
+- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.
+
+Example: in the following project structure:
+
+```
+project-root/
+├── pinokio/                 # Pinokio launcher folder
+│    ├── start.js             # Launch script
+│    ├── pinokio.js           # UI generator script
+│    └── pinokio.json         # Metadata (title, description, icon)
+└─── backend/
+     ├── requirements.txt          # App dependencies
+     └── app.py                    # App code
+```
+
+The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:
+
+```
+{
+  run: [{
+    ...
+  }, {
+    method: "shell.run",
+    params: {
+      message: "python app.py",
+      venv: "env",
+      path: "../backend"
+    }
+  }, {
+    ...
+  }]
+}
+```
+
+## Development Workflow
+
+### 1. Understanding the Project
+- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)
+- If no `SPEC.md` exists, build based on user requirements
+### 2. Modifying Existing Launcher Projects
+If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.
+- **Preserve existing functionality:** Only modify necessary parts
+- **Don't touch working scripts:** Unless adding/updating specific commands
+- **Follow existing conventions:** Match the style and structure already present
+### 3. Try to adopt from examples as much as possible
+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (C:\pinokio\prototype\system\examples) to see if you can adopt them instead of coming up everything from scratch.
+- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.
+### 4. Writing from scratch as a last resort
+If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.
+### 5. Debugging
+When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.
+
+## Script Requirements
+
+### 1. 1-click launchable
+- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.
+
+### 2. Write Documentation
+- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:
+  - What the app does
+  - How to use the app
+  - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)
+
+## Types of launchers
+## 1. Launching servers
+- When an app requires launching a server, here are the commonly used scripts:
+  - `install.js`: a script to install the app
+  - `start.js`: a script to start the app
+  - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch
+  - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)
+  - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.
+  - `pinokio.json`: For metadata
+
+Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:
+
+```javascript
+module.exports = {
+  // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.
+  daemon: true,
+  run: [
+    {
+      // The "shell.run" API for running a shell session
+      method: "shell.run",
+      params: {
+        // Edit 'venv' to customize the venv folder path
+        venv: "env",
+        // Edit 'env' to customize environment variables (see documentation)
+        env: { },
+        // Edit 'path' to customize the path to start the shell from
+        path: "app",
+        // Edit 'message' to customize the commands, or to run multiple commands
+        message: [
+          "python app.py",
+        ],
+        on: [{
+          // The regular expression pattern to monitor.
+          // Whenever each "event" pattern occurs in the shell terminal, the shell will return,
+          // and the script will go onto the next step.
+          // The regular expression match object will be passed on to the next step as `input.event`
+          // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)
+          "event": "/(http:\/\/\\S+)/", 
+
+          // Use "done": true to move to the next step while keeping the shell alive.
+          // Use "kill": true to move to the next step after killing the shell.
+          "done": true
+        }]
+      }
+    },
+    {
+      // This step sets the local variable 'url'.
+      // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.
+      method: "local.set",
+      params: {
+        // the input.event is the regular expression match object from the previous step
+        // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.
+        // Therefore setting the local variable 'url'
+        url: "{{input.event[1]}}"
+      }
+    }
+  ]
+}
+```
+
+## 2. Launching serverless web apps
+
+- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.
+- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do 
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## 3. Launching quick scripts without web UI
+
+- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.
+- This may include TUI (Terminal User Interface) apps, a simple launcher 
+- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.
+- Here are some examples:
+  - A pinokio script to toggle the desktop theme between dark and light
+    - Write some code (python or javascript or whatever)
+    - Write a `toggle.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes
+  - A pinokio script to fetch some file
+    - Write some code (python or javascript or whatever)
+    - Write a `fetch.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## API
+
+This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:
+1. Check the examples in the C:\pinokio\prototype\system\examples folder
+2. Read the `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md further documentation on the full syntax
+
+### Script API
+
+These APIs can be used to describe each step in a pinokio script:
+- shell.run: run shell commands
+- input: accept user input
+- filepicker: accept file upload
+- fs.write: write to file
+- fs.read: read from file
+- fs.copy: copy files
+- fs.download: download files
+- fs.link: create a symbolic link (or junction on windows) for folders
+- fs.open: open the system file explorer at a given path
+- fs.cat: print file contents
+- jump: jump to a specific step
+- local.set: set local variables for the currently running script
+- json.set: update a json file
+- json.rm: remove keys from a json file
+- json.get: get values from a json file
+- log: print to the web terminal
+- net: make network requests
+- notify: display a notification
+- script.download: download a script from a git uri
+- script.start: start a script
+- script.stop: stop a script
+- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`
+- web.open: open a url in web browser
+- hf.download: huggingfac-cli download API
+### Template variables
+The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:
+- input: An input is a variable that gets passed from one RPC call to the next
+- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.
+- local: local variable object that can be set with `local.set` API
+- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.
+- uri: The current script uri
+- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.
+- cwd: The current script execution folder path
+- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`
+- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64
+- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)
+- gpu: the first available GPU (example: `nvidia`)
+- current: The current variable points to the index of the currently executing instruction within the run array.
+- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)
+- envs: You can access the environment variables of the currently running process with envs object.
+- which: Check whether a command exists (example: `{{which('winget')}}`. Can be used in the `when` attribute of a script step to run commands or install first.
+- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- os: Pinokio exposes the node.js os module through the os variable.
+- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`
+
+## System Capabilities
+### Package Management (Use in Order of Preference)
+The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:
+1. **UV** - For Python packages (preferred over pip)
+2. **NPM** - For Node.js packages  
+3. **Conda** - For cross-platform 3rd party binaries
+4. **Brew** - Mac-only fallback when other options unavailable
+5. **Git** - Full access to git is available.
+**Important:** Include all install commands in the install script for reproducibility.
+### HTTPS Proxy Support
+- All HTTP servers automatically get HTTPS endpoints
+- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`
+- Full proxy list available at: `http://localhost:2019/config/`
+### Pterm Features:
+- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)
+- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)
+- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)
+- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)
+- **Git Operations:** Clone repositories, push to GitHub
+- **GitHub Integration:** Full GitHub CLI support (`gh` commands)
+
+## Troubleshooting with Logs
+Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:
+
+### Log Structure
+In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:
+
+```
+pinokio/
+└── logs/   # Direct user interaction logs
+    ├── api/     # Launcher script logs (install.js, start.js, etc.)
+    ├── dev/     # AI coding tool logs (organized by tool)
+    └── shell/   # Direct user interaction logs
+```
+
+Otherwise, the `logs` folder should be found at project root:
+
+```
+logs/
+├── api/     # Launcher script logs (install.js, start.js, etc.)
+├── dev/     # AI coding tool logs (organized by tool)
+└── shell/   # Direct user interaction logs
+```
+
+### Log File Naming
+- Unix timestamps for each session
+- Special "latest" file contains most recent session logs
+- **Default:** Use "latest" files for current issues
+- **Historical:** Use timestamped files for pattern analysis and the full history.
+
+## Best practices
+### 0. Always reference the logs when debugging
+- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.
+### 1. Shell commands for launching programs
+- Launch flags related
+  - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.
+- Launch IP related
+  - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.
+- Launch Port related
+  - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.
+  - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.
+  - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`
+  - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.
+### 2. shell.run API
+- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.
+### 2. Package managers
+- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.
+- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.
+### 3. Minimal Always
+- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.
+- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.
+- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.
+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `C:\pinokio\api\Z-Image-Pinokio.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.
+  - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.
+- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.
+  - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.
+### 4. Try to support Cross-platform as much as possible
+- Use cross-platform shell commands only.
+- This means, prefer to use commands that work on all platforms instead of the current platform.
+- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.
+- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.
+- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.
+- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.
+### 5. Do not make assumptions about Pinokio API
+- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.
+- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.
+### 6. Scripts must be able to replicate install and launch steps 100%
+- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.
+- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.
+### 7 Dynamic UI rendering
+- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.
+  - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:
+    - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.
+  - Check the examples in the C:\pinokio\prototype\system\examples folder to see how these are being used.
+### 8. No need for stop scripts
+- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script
+### 9. Writing launchers for existing projects
+- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.
+- In most cases, the `README.md` file in the `C:\pinokio\api\Z-Image-Pinokio.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.
+- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.
+### 10. Don't use Docker unless really necessary
+- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.
+### 11. pinokio.json
+- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.
+- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.
+  - If the git repository for the `C:\pinokio\api\Z-Image-Pinokio.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`. 
+### 12. Gitignore
+- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:
+  - Cloning git repositories
+  - Downloading files
+  - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.
+- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.
+
+## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)
+If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:
+
+```
+// install.js
+module.exports = {
+  run: [
+    // Delete this step if your project does not use torch
+    {
+      method: "script.start",
+      params: {
+        uri: "torch.js",
+        params: {
+          path: "app",
+          venv: "venv",                // Edit this to customize the venv folder path
+          // xformers: true   // uncomment this line if your project requires xformers
+          // triton: true   // uncomment this line if your project requires triton
+          // sageattention: true   // uncomment this line if your project requires sageattention
+        }
+      }
+    },
+    // Edit this step with your custom install commands
+    {
+      method: "shell.run",
+      params: {
+        venv: "venv",                // Edit this to customize the venv folder path
+        path: "app",
+        message: [
+          "uv pip install -r requirements.txt"
+        ],
+      }
+    },
+  ]
+}
+```
+
+The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.
+
+
+## Quick Reference
+### Essential Documentation
+- **Pinokio Programming:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Programming Pinokio" section
+- **Dynamic Menus:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Dynamic menu rendering" section  
+- **CLI Commands:** See `PTERM.md` at C:\pinokio\prototype\PTERM.md
+### Common Patterns
+- **Python Virtual Env:** `shell.run` with `venv` attribute
+- **Cross-platform Commands:** Always test on multiple platforms
+- **Error Handling:** Check logs/api for launcher issues
+- **GitHub Operations:** Use `gh` CLI for advanced GitHub features
+## Development Principles
+1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands
+2. **Maintain Separation:** Keep app logic and launchers separate
+3. **Follow Conventions:** Match existing project patterns
+4. **Test Thoroughly:** Use CLI to verify launcher functionality
+5. **Document Changes:** Update relevant metadata and documentation

AGENTS.md

@@ -0,0 +1,473 @@
+# Development Guide for Pinokio Projects
+
+## Non-Negotiable Execution Workflow
+
+To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.
+1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.
+2. **Example Lock-in:** Identify the closest matching script in `C:\pinokio\prototype\system\examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.
+3. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, etc.). Confirm each item is ticked **before** making changes.
+4. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.
+5. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.
+
+If any step cannot be completed, stop immediately and ask the user how to proceed. These five steps are mandatory for every session.
+
+### Critical Pattern Lock: Capturing Web UI URLs
+
+When writing `start.js` (or any script that needs to surface a web URL for a server):
+
+1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**
+```javascript
+on: [{
+  event: "/(http:\\/\\/[0-9.:]+)/",
+  done: true
+}]
+```
+
+2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**
+```javascript
+{
+  method: "local.set",
+  params: {
+    url: "{{input.event[1]}}"
+  }
+}
+```
+
+3. Always try to come up with the most generic regex.
+4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.
+
+Deviation from this pattern requires written approval from the user.
+
+- Make sure to keep this entire document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.
+- When writing pinokio scripts, ALWAYS check the examples folder (in C:\pinokio\prototype\system\examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.
+- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md to use the correct syntax instead of assuming the syntax.
+- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.
+- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.
+
+## Determine User Intent
+If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to
+
+1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.
+2. A Demo: the intent may be a 1-click launcher for the demo
+3. Open source project: the intent may be a 1-click launcher for the project 
+4. Regular website: the intent may be to clone the website and a launcher.
+5. There can be other cases, but try to guess.
+
+## Project Structure
+
+Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:
+
+Pinokio projects follow a standardized structure with app logic separated from launcher scripts:
+
+```
+project-root/
+├── app/                 # Self-contained app logic (can be standalone repo)
+│   ├── package.json     # Node.js projects
+│   ├── requirements.txt # Python projects
+│   └── ...              # Other language-specific files
+├── README.md            # Documentation
+├── install.js           # Installation script
+├── start.js             # Launch script
+├── update.js            # Update script (for updating the scripts and app logic to the latest)
+├── reset.js             # Reset dependencies script
+├── pinokio.js           # UI generator script
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+- Keep app code in `/app` folder only (never in root)
+- Store all launcher files in project root (never in `/app`)
+- `/app` folder should be self-contained and publishable
+
+
+The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):
+
+```
+project-root/
+├── index.html           # The serverless web app entry point
+├── ...
+├── README.md            # Documentation
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (C:\pinokio\prototype\system\examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.
+
+## Launcher Project Working Directory
+
+- The project working directory for a script is always the same directory as the script location.
+- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.
+- If the launcher files are in the project root path, then the default path for shell execution is the project root.
+- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.
+
+Example: in the following project structure:
+
+```
+project-root/
+├── pinokio/                 # Pinokio launcher folder
+│    ├── start.js             # Launch script
+│    ├── pinokio.js           # UI generator script
+│    └── pinokio.json         # Metadata (title, description, icon)
+└─── backend/
+     ├── requirements.txt          # App dependencies
+     └── app.py                    # App code
+```
+
+The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:
+
+```
+{
+  run: [{
+    ...
+  }, {
+    method: "shell.run",
+    params: {
+      message: "python app.py",
+      venv: "env",
+      path: "../backend"
+    }
+  }, {
+    ...
+  }]
+}
+```
+
+## Development Workflow
+
+### 1. Understanding the Project
+- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)
+- If no `SPEC.md` exists, build based on user requirements
+### 2. Modifying Existing Launcher Projects
+If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.
+- **Preserve existing functionality:** Only modify necessary parts
+- **Don't touch working scripts:** Unless adding/updating specific commands
+- **Follow existing conventions:** Match the style and structure already present
+### 3. Try to adopt from examples as much as possible
+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (C:\pinokio\prototype\system\examples) to see if you can adopt them instead of coming up everything from scratch.
+- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.
+### 4. Writing from scratch as a last resort
+If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.
+### 5. Debugging
+When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.
+
+## Script Requirements
+
+### 1. 1-click launchable
+- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.
+
+### 2. Write Documentation
+- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:
+  - What the app does
+  - How to use the app
+  - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)
+
+## Types of launchers
+## 1. Launching servers
+- When an app requires launching a server, here are the commonly used scripts:
+  - `install.js`: a script to install the app
+  - `start.js`: a script to start the app
+  - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch
+  - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)
+  - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.
+  - `pinokio.json`: For metadata
+
+Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:
+
+```javascript
+module.exports = {
+  // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.
+  daemon: true,
+  run: [
+    {
+      // The "shell.run" API for running a shell session
+      method: "shell.run",
+      params: {
+        // Edit 'venv' to customize the venv folder path
+        venv: "env",
+        // Edit 'env' to customize environment variables (see documentation)
+        env: { },
+        // Edit 'path' to customize the path to start the shell from
+        path: "app",
+        // Edit 'message' to customize the commands, or to run multiple commands
+        message: [
+          "python app.py",
+        ],
+        on: [{
+          // The regular expression pattern to monitor.
+          // Whenever each "event" pattern occurs in the shell terminal, the shell will return,
+          // and the script will go onto the next step.
+          // The regular expression match object will be passed on to the next step as `input.event`
+          // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)
+          "event": "/(http:\/\/\\S+)/", 
+
+          // Use "done": true to move to the next step while keeping the shell alive.
+          // Use "kill": true to move to the next step after killing the shell.
+          "done": true
+        }]
+      }
+    },
+    {
+      // This step sets the local variable 'url'.
+      // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.
+      method: "local.set",
+      params: {
+        // the input.event is the regular expression match object from the previous step
+        // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.
+        // Therefore setting the local variable 'url'
+        url: "{{input.event[1]}}"
+      }
+    }
+  ]
+}
+```
+
+## 2. Launching serverless web apps
+
+- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.
+- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do 
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## 3. Launching quick scripts without web UI
+
+- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.
+- This may include TUI (Terminal User Interface) apps, a simple launcher 
+- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.
+- Here are some examples:
+  - A pinokio script to toggle the desktop theme between dark and light
+    - Write some code (python or javascript or whatever)
+    - Write a `toggle.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes
+  - A pinokio script to fetch some file
+    - Write some code (python or javascript or whatever)
+    - Write a `fetch.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## API
+
+This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:
+1. Check the examples in the C:\pinokio\prototype\system\examples folder
+2. Read the `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md further documentation on the full syntax
+
+### Script API
+
+These APIs can be used to describe each step in a pinokio script:
+- shell.run: run shell commands
+- input: accept user input
+- filepicker: accept file upload
+- fs.write: write to file
+- fs.read: read from file
+- fs.copy: copy files
+- fs.download: download files
+- fs.link: create a symbolic link (or junction on windows) for folders
+- fs.open: open the system file explorer at a given path
+- fs.cat: print file contents
+- jump: jump to a specific step
+- local.set: set local variables for the currently running script
+- json.set: update a json file
+- json.rm: remove keys from a json file
+- json.get: get values from a json file
+- log: print to the web terminal
+- net: make network requests
+- notify: display a notification
+- script.download: download a script from a git uri
+- script.start: start a script
+- script.stop: stop a script
+- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`
+- web.open: open a url in web browser
+- hf.download: huggingfac-cli download API
+### Template variables
+The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:
+- input: An input is a variable that gets passed from one RPC call to the next
+- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.
+- local: local variable object that can be set with `local.set` API
+- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.
+- uri: The current script uri
+- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.
+- cwd: The current script execution folder path
+- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`
+- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64
+- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)
+- gpu: the first available GPU (example: `nvidia`)
+- current: The current variable points to the index of the currently executing instruction within the run array.
+- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)
+- envs: You can access the environment variables of the currently running process with envs object.
+- which: Check whether a command exists (example: `{{which('winget')}}`. Can be used in the `when` attribute of a script step to run commands or install first.
+- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- os: Pinokio exposes the node.js os module through the os variable.
+- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`
+
+## System Capabilities
+### Package Management (Use in Order of Preference)
+The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:
+1. **UV** - For Python packages (preferred over pip)
+2. **NPM** - For Node.js packages  
+3. **Conda** - For cross-platform 3rd party binaries
+4. **Brew** - Mac-only fallback when other options unavailable
+5. **Git** - Full access to git is available.
+**Important:** Include all install commands in the install script for reproducibility.
+### HTTPS Proxy Support
+- All HTTP servers automatically get HTTPS endpoints
+- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`
+- Full proxy list available at: `http://localhost:2019/config/`
+### Pterm Features:
+- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)
+- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)
+- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)
+- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)
+- **Git Operations:** Clone repositories, push to GitHub
+- **GitHub Integration:** Full GitHub CLI support (`gh` commands)
+
+## Troubleshooting with Logs
+Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:
+
+### Log Structure
+In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:
+
+```
+pinokio/
+└── logs/   # Direct user interaction logs
+    ├── api/     # Launcher script logs (install.js, start.js, etc.)
+    ├── dev/     # AI coding tool logs (organized by tool)
+    └── shell/   # Direct user interaction logs
+```
+
+Otherwise, the `logs` folder should be found at project root:
+
+```
+logs/
+├── api/     # Launcher script logs (install.js, start.js, etc.)
+├── dev/     # AI coding tool logs (organized by tool)
+└── shell/   # Direct user interaction logs
+```
+
+### Log File Naming
+- Unix timestamps for each session
+- Special "latest" file contains most recent session logs
+- **Default:** Use "latest" files for current issues
+- **Historical:** Use timestamped files for pattern analysis and the full history.
+
+## Best practices
+### 0. Always reference the logs when debugging
+- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.
+### 1. Shell commands for launching programs
+- Launch flags related
+  - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.
+- Launch IP related
+  - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.
+- Launch Port related
+  - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.
+  - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.
+  - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`
+  - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.
+### 2. shell.run API
+- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.
+### 2. Package managers
+- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.
+- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.
+### 3. Minimal Always
+- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.
+- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.
+- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.
+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `C:\pinokio\api\Z-Image-Pinokio.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.
+  - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.
+- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.
+  - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.
+### 4. Try to support Cross-platform as much as possible
+- Use cross-platform shell commands only.
+- This means, prefer to use commands that work on all platforms instead of the current platform.
+- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.
+- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.
+- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.
+- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.
+### 5. Do not make assumptions about Pinokio API
+- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.
+- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.
+### 6. Scripts must be able to replicate install and launch steps 100%
+- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.
+- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.
+### 7 Dynamic UI rendering
+- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.
+  - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:
+    - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.
+  - Check the examples in the C:\pinokio\prototype\system\examples folder to see how these are being used.
+### 8. No need for stop scripts
+- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script
+### 9. Writing launchers for existing projects
+- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.
+- In most cases, the `README.md` file in the `C:\pinokio\api\Z-Image-Pinokio.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.
+- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.
+### 10. Don't use Docker unless really necessary
+- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.
+### 11. pinokio.json
+- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.
+- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.
+  - If the git repository for the `C:\pinokio\api\Z-Image-Pinokio.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`. 
+### 12. Gitignore
+- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:
+  - Cloning git repositories
+  - Downloading files
+  - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.
+- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.
+
+## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)
+If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:
+
+```
+// install.js
+module.exports = {
+  run: [
+    // Delete this step if your project does not use torch
+    {
+      method: "script.start",
+      params: {
+        uri: "torch.js",
+        params: {
+          path: "app",
+          venv: "venv",                // Edit this to customize the venv folder path
+          // xformers: true   // uncomment this line if your project requires xformers
+          // triton: true   // uncomment this line if your project requires triton
+          // sageattention: true   // uncomment this line if your project requires sageattention
+        }
+      }
+    },
+    // Edit this step with your custom install commands
+    {
+      method: "shell.run",
+      params: {
+        venv: "venv",                // Edit this to customize the venv folder path
+        path: "app",
+        message: [
+          "uv pip install -r requirements.txt"
+        ],
+      }
+    },
+  ]
+}
+```
+
+The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.
+
+
+## Quick Reference
+### Essential Documentation
+- **Pinokio Programming:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Programming Pinokio" section
+- **Dynamic Menus:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Dynamic menu rendering" section  
+- **CLI Commands:** See `PTERM.md` at C:\pinokio\prototype\PTERM.md
+### Common Patterns
+- **Python Virtual Env:** `shell.run` with `venv` attribute
+- **Cross-platform Commands:** Always test on multiple platforms
+- **Error Handling:** Check logs/api for launcher issues
+- **GitHub Operations:** Use `gh` CLI for advanced GitHub features
+## Development Principles
+1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands
+2. **Maintain Separation:** Keep app logic and launchers separate
+3. **Follow Conventions:** Match existing project patterns
+4. **Test Thoroughly:** Use CLI to verify launcher functionality
+5. **Document Changes:** Update relevant metadata and documentation

CLAUDE.md

@@ -0,0 +1,473 @@
+# Development Guide for Pinokio Projects
+
+## Non-Negotiable Execution Workflow
+
+To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.
+1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.
+2. **Example Lock-in:** Identify the closest matching script in `C:\pinokio\prototype\system\examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.
+3. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, etc.). Confirm each item is ticked **before** making changes.
+4. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.
+5. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.
+
+If any step cannot be completed, stop immediately and ask the user how to proceed. These five steps are mandatory for every session.
+
+### Critical Pattern Lock: Capturing Web UI URLs
+
+When writing `start.js` (or any script that needs to surface a web URL for a server):
+
+1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**
+```javascript
+on: [{
+  event: "/(http:\\/\\/[0-9.:]+)/",
+  done: true
+}]
+```
+
+2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**
+```javascript
+{
+  method: "local.set",
+  params: {
+    url: "{{input.event[1]}}"
+  }
+}
+```
+
+3. Always try to come up with the most generic regex.
+4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.
+
+Deviation from this pattern requires written approval from the user.
+
+- Make sure to keep this entire document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.
+- When writing pinokio scripts, ALWAYS check the examples folder (in C:\pinokio\prototype\system\examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.
+- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md to use the correct syntax instead of assuming the syntax.
+- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.
+- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.
+
+## Determine User Intent
+If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to
+
+1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.
+2. A Demo: the intent may be a 1-click launcher for the demo
+3. Open source project: the intent may be a 1-click launcher for the project 
+4. Regular website: the intent may be to clone the website and a launcher.
+5. There can be other cases, but try to guess.
+
+## Project Structure
+
+Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:
+
+Pinokio projects follow a standardized structure with app logic separated from launcher scripts:
+
+```
+project-root/
+├── app/                 # Self-contained app logic (can be standalone repo)
+│   ├── package.json     # Node.js projects
+│   ├── requirements.txt # Python projects
+│   └── ...              # Other language-specific files
+├── README.md            # Documentation
+├── install.js           # Installation script
+├── start.js             # Launch script
+├── update.js            # Update script (for updating the scripts and app logic to the latest)
+├── reset.js             # Reset dependencies script
+├── pinokio.js           # UI generator script
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+- Keep app code in `/app` folder only (never in root)
+- Store all launcher files in project root (never in `/app`)
+- `/app` folder should be self-contained and publishable
+
+
+The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):
+
+```
+project-root/
+├── index.html           # The serverless web app entry point
+├── ...
+├── README.md            # Documentation
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (C:\pinokio\prototype\system\examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.
+
+## Launcher Project Working Directory
+
+- The project working directory for a script is always the same directory as the script location.
+- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.
+- If the launcher files are in the project root path, then the default path for shell execution is the project root.
+- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.
+
+Example: in the following project structure:
+
+```
+project-root/
+├── pinokio/                 # Pinokio launcher folder
+│    ├── start.js             # Launch script
+│    ├── pinokio.js           # UI generator script
+│    └── pinokio.json         # Metadata (title, description, icon)
+└─── backend/
+     ├── requirements.txt          # App dependencies
+     └── app.py                    # App code
+```
+
+The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:
+
+```
+{
+  run: [{
+    ...
+  }, {
+    method: "shell.run",
+    params: {
+      message: "python app.py",
+      venv: "env",
+      path: "../backend"
+    }
+  }, {
+    ...
+  }]
+}
+```
+
+## Development Workflow
+
+### 1. Understanding the Project
+- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)
+- If no `SPEC.md` exists, build based on user requirements
+### 2. Modifying Existing Launcher Projects
+If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.
+- **Preserve existing functionality:** Only modify necessary parts
+- **Don't touch working scripts:** Unless adding/updating specific commands
+- **Follow existing conventions:** Match the style and structure already present
+### 3. Try to adopt from examples as much as possible
+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (C:\pinokio\prototype\system\examples) to see if you can adopt them instead of coming up everything from scratch.
+- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.
+### 4. Writing from scratch as a last resort
+If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.
+### 5. Debugging
+When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.
+
+## Script Requirements
+
+### 1. 1-click launchable
+- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.
+
+### 2. Write Documentation
+- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:
+  - What the app does
+  - How to use the app
+  - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)
+
+## Types of launchers
+## 1. Launching servers
+- When an app requires launching a server, here are the commonly used scripts:
+  - `install.js`: a script to install the app
+  - `start.js`: a script to start the app
+  - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch
+  - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)
+  - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.
+  - `pinokio.json`: For metadata
+
+Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:
+
+```javascript
+module.exports = {
+  // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.
+  daemon: true,
+  run: [
+    {
+      // The "shell.run" API for running a shell session
+      method: "shell.run",
+      params: {
+        // Edit 'venv' to customize the venv folder path
+        venv: "env",
+        // Edit 'env' to customize environment variables (see documentation)
+        env: { },
+        // Edit 'path' to customize the path to start the shell from
+        path: "app",
+        // Edit 'message' to customize the commands, or to run multiple commands
+        message: [
+          "python app.py",
+        ],
+        on: [{
+          // The regular expression pattern to monitor.
+          // Whenever each "event" pattern occurs in the shell terminal, the shell will return,
+          // and the script will go onto the next step.
+          // The regular expression match object will be passed on to the next step as `input.event`
+          // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)
+          "event": "/(http:\/\/\\S+)/", 
+
+          // Use "done": true to move to the next step while keeping the shell alive.
+          // Use "kill": true to move to the next step after killing the shell.
+          "done": true
+        }]
+      }
+    },
+    {
+      // This step sets the local variable 'url'.
+      // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.
+      method: "local.set",
+      params: {
+        // the input.event is the regular expression match object from the previous step
+        // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.
+        // Therefore setting the local variable 'url'
+        url: "{{input.event[1]}}"
+      }
+    }
+  ]
+}
+```
+
+## 2. Launching serverless web apps
+
+- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.
+- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do 
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## 3. Launching quick scripts without web UI
+
+- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.
+- This may include TUI (Terminal User Interface) apps, a simple launcher 
+- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.
+- Here are some examples:
+  - A pinokio script to toggle the desktop theme between dark and light
+    - Write some code (python or javascript or whatever)
+    - Write a `toggle.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes
+  - A pinokio script to fetch some file
+    - Write some code (python or javascript or whatever)
+    - Write a `fetch.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## API
+
+This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:
+1. Check the examples in the C:\pinokio\prototype\system\examples folder
+2. Read the `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md further documentation on the full syntax
+
+### Script API
+
+These APIs can be used to describe each step in a pinokio script:
+- shell.run: run shell commands
+- input: accept user input
+- filepicker: accept file upload
+- fs.write: write to file
+- fs.read: read from file
+- fs.copy: copy files
+- fs.download: download files
+- fs.link: create a symbolic link (or junction on windows) for folders
+- fs.open: open the system file explorer at a given path
+- fs.cat: print file contents
+- jump: jump to a specific step
+- local.set: set local variables for the currently running script
+- json.set: update a json file
+- json.rm: remove keys from a json file
+- json.get: get values from a json file
+- log: print to the web terminal
+- net: make network requests
+- notify: display a notification
+- script.download: download a script from a git uri
+- script.start: start a script
+- script.stop: stop a script
+- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`
+- web.open: open a url in web browser
+- hf.download: huggingfac-cli download API
+### Template variables
+The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:
+- input: An input is a variable that gets passed from one RPC call to the next
+- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.
+- local: local variable object that can be set with `local.set` API
+- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.
+- uri: The current script uri
+- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.
+- cwd: The current script execution folder path
+- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`
+- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64
+- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)
+- gpu: the first available GPU (example: `nvidia`)
+- current: The current variable points to the index of the currently executing instruction within the run array.
+- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)
+- envs: You can access the environment variables of the currently running process with envs object.
+- which: Check whether a command exists (example: `{{which('winget')}}`. Can be used in the `when` attribute of a script step to run commands or install first.
+- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- os: Pinokio exposes the node.js os module through the os variable.
+- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`
+
+## System Capabilities
+### Package Management (Use in Order of Preference)
+The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:
+1. **UV** - For Python packages (preferred over pip)
+2. **NPM** - For Node.js packages  
+3. **Conda** - For cross-platform 3rd party binaries
+4. **Brew** - Mac-only fallback when other options unavailable
+5. **Git** - Full access to git is available.
+**Important:** Include all install commands in the install script for reproducibility.
+### HTTPS Proxy Support
+- All HTTP servers automatically get HTTPS endpoints
+- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`
+- Full proxy list available at: `http://localhost:2019/config/`
+### Pterm Features:
+- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)
+- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)
+- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)
+- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)
+- **Git Operations:** Clone repositories, push to GitHub
+- **GitHub Integration:** Full GitHub CLI support (`gh` commands)
+
+## Troubleshooting with Logs
+Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:
+
+### Log Structure
+In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:
+
+```
+pinokio/
+└── logs/   # Direct user interaction logs
+    ├── api/     # Launcher script logs (install.js, start.js, etc.)
+    ├── dev/     # AI coding tool logs (organized by tool)
+    └── shell/   # Direct user interaction logs
+```
+
+Otherwise, the `logs` folder should be found at project root:
+
+```
+logs/
+├── api/     # Launcher script logs (install.js, start.js, etc.)
+├── dev/     # AI coding tool logs (organized by tool)
+└── shell/   # Direct user interaction logs
+```
+
+### Log File Naming
+- Unix timestamps for each session
+- Special "latest" file contains most recent session logs
+- **Default:** Use "latest" files for current issues
+- **Historical:** Use timestamped files for pattern analysis and the full history.
+
+## Best practices
+### 0. Always reference the logs when debugging
+- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.
+### 1. Shell commands for launching programs
+- Launch flags related
+  - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.
+- Launch IP related
+  - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.
+- Launch Port related
+  - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.
+  - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.
+  - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`
+  - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.
+### 2. shell.run API
+- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.
+### 2. Package managers
+- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.
+- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.
+### 3. Minimal Always
+- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.
+- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.
+- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.
+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `C:\pinokio\api\Z-Image-Pinokio.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.
+  - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.
+- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.
+  - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.
+### 4. Try to support Cross-platform as much as possible
+- Use cross-platform shell commands only.
+- This means, prefer to use commands that work on all platforms instead of the current platform.
+- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.
+- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.
+- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.
+- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.
+### 5. Do not make assumptions about Pinokio API
+- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.
+- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.
+### 6. Scripts must be able to replicate install and launch steps 100%
+- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.
+- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.
+### 7 Dynamic UI rendering
+- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.
+  - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:
+    - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.
+  - Check the examples in the C:\pinokio\prototype\system\examples folder to see how these are being used.
+### 8. No need for stop scripts
+- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script
+### 9. Writing launchers for existing projects
+- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.
+- In most cases, the `README.md` file in the `C:\pinokio\api\Z-Image-Pinokio.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.
+- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.
+### 10. Don't use Docker unless really necessary
+- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.
+### 11. pinokio.json
+- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.
+- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.
+  - If the git repository for the `C:\pinokio\api\Z-Image-Pinokio.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`. 
+### 12. Gitignore
+- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:
+  - Cloning git repositories
+  - Downloading files
+  - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.
+- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.
+
+## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)
+If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:
+
+```
+// install.js
+module.exports = {
+  run: [
+    // Delete this step if your project does not use torch
+    {
+      method: "script.start",
+      params: {
+        uri: "torch.js",
+        params: {
+          path: "app",
+          venv: "venv",                // Edit this to customize the venv folder path
+          // xformers: true   // uncomment this line if your project requires xformers
+          // triton: true   // uncomment this line if your project requires triton
+          // sageattention: true   // uncomment this line if your project requires sageattention
+        }
+      }
+    },
+    // Edit this step with your custom install commands
+    {
+      method: "shell.run",
+      params: {
+        venv: "venv",                // Edit this to customize the venv folder path
+        path: "app",
+        message: [
+          "uv pip install -r requirements.txt"
+        ],
+      }
+    },
+  ]
+}
+```
+
+The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.
+
+
+## Quick Reference
+### Essential Documentation
+- **Pinokio Programming:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Programming Pinokio" section
+- **Dynamic Menus:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Dynamic menu rendering" section  
+- **CLI Commands:** See `PTERM.md` at C:\pinokio\prototype\PTERM.md
+### Common Patterns
+- **Python Virtual Env:** `shell.run` with `venv` attribute
+- **Cross-platform Commands:** Always test on multiple platforms
+- **Error Handling:** Check logs/api for launcher issues
+- **GitHub Operations:** Use `gh` CLI for advanced GitHub features
+## Development Principles
+1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands
+2. **Maintain Separation:** Keep app logic and launchers separate
+3. **Follow Conventions:** Match existing project patterns
+4. **Test Thoroughly:** Use CLI to verify launcher functionality
+5. **Document Changes:** Update relevant metadata and documentation

ENVIRONMENT

@@ -0,0 +1,95 @@
+
+##########################################################################
+#
+# PINOKIO_SCRIPT_AUTOLAUNCH
+# the relative file path for auto launching any script
+# the specified script will automatically run when pinokio first launches
+#
+##########################################################################
+PINOKIO_SCRIPT_AUTOLAUNCH=
+
+##########################################################################
+#
+# PINOKIO_SHARE_CLOUDFLARE
+# Set this variable to share the app publicly via cloudflare tunnel.
+#
+##########################################################################
+PINOKIO_SHARE_CLOUDFLARE=false
+
+##########################################################################
+#
+# PINOKIO_SHARE_PASSCODE
+#
+# By default, your publicly shared app will be 100% open to anyone
+# with the link via Cloudflare.
+#
+# You can add authorization by protecting it with a passcode.
+# Set this value, and any access to the app will require a pass code input
+#
+##########################################################################
+PINOKIO_SHARE_PASSCODE=
+
+##########################################################################
+#
+# PINOKIO_SCRIPT_DEFAULT
+# If this variable is false, 'default': true menu items in pinokio.js
+# will NOT automatically run
+#
+##########################################################################
+PINOKIO_SCRIPT_DEFAULT=true
+
+##########################################################################
+#
+# GRADIO_TEMP_DIR
+# All the files uploaded through gradio goes here.
+#
+# Delete this line to store the files under PINOKIO_HOME/cache/GRADIO_TEMPDIR
+# or change the path if you want to use a different path
+#
+##########################################################################
+GRADIO_TEMP_DIR=./cache/GRADIO_TEMP_DIR
+
+##########################################################################
+#
+# HF_HOME
+#
+# Huggingface cache
+# All the model files automatically downloaded through libraries like
+# diffusers, transformers, etc. will be stored under this path
+#
+# You can save disk space by deleting this line, which will store all
+# huggingface files under PINOKIO_HOME/cache/HF_HOME without redundancy.
+#
+##########################################################################
+HF_HOME=./cache/HF_HOME
+
+##########################################################################
+#
+# TORCH_HOME
+#
+# Torch hub cache
+# All the files automatically downloaded by pytorch will be stored here
+#
+# You can save disk space by deleting this line, which will store all
+# torch hub files under PINOKIO_HOME/cache/TORCH_HOME without redundancy.
+#
+##########################################################################
+TORCH_HOME=./cache/TORCH_HOME
+
+##########################################################################
+#
+# PINOKIO_SHARE_LOCAL
+# Set this variable to true to share the app on the local network.
+#
+##########################################################################
+PINOKIO_SHARE_LOCAL=false
+
+##########################################################################
+#
+# PINOKIO_SHARE_LOCAL_PORT
+# Set this variable to use fixed port for the local network sharing feature
+# If not specified, a random port will be assigned to the local proxy used
+# for local sharing.
+#
+##########################################################################
+PINOKIO_SHARE_LOCAL_PORT=

GEMINI.md

@@ -0,0 +1,473 @@
+# Development Guide for Pinokio Projects
+
+## Non-Negotiable Execution Workflow
+
+To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.
+1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.
+2. **Example Lock-in:** Identify the closest matching script in `C:\pinokio\prototype\system\examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.
+3. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, etc.). Confirm each item is ticked **before** making changes.
+4. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.
+5. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.
+
+If any step cannot be completed, stop immediately and ask the user how to proceed. These five steps are mandatory for every session.
+
+### Critical Pattern Lock: Capturing Web UI URLs
+
+When writing `start.js` (or any script that needs to surface a web URL for a server):
+
+1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**
+```javascript
+on: [{
+  event: "/(http:\\/\\/[0-9.:]+)/",
+  done: true
+}]
+```
+
+2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**
+```javascript
+{
+  method: "local.set",
+  params: {
+    url: "{{input.event[1]}}"
+  }
+}
+```
+
+3. Always try to come up with the most generic regex.
+4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.
+
+Deviation from this pattern requires written approval from the user.
+
+- Make sure to keep this entire document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.
+- When writing pinokio scripts, ALWAYS check the examples folder (in C:\pinokio\prototype\system\examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.
+- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md to use the correct syntax instead of assuming the syntax.
+- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.
+- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.
+
+## Determine User Intent
+If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to
+
+1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.
+2. A Demo: the intent may be a 1-click launcher for the demo
+3. Open source project: the intent may be a 1-click launcher for the project 
+4. Regular website: the intent may be to clone the website and a launcher.
+5. There can be other cases, but try to guess.
+
+## Project Structure
+
+Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:
+
+Pinokio projects follow a standardized structure with app logic separated from launcher scripts:
+
+```
+project-root/
+├── app/                 # Self-contained app logic (can be standalone repo)
+│   ├── package.json     # Node.js projects
+│   ├── requirements.txt # Python projects
+│   └── ...              # Other language-specific files
+├── README.md            # Documentation
+├── install.js           # Installation script
+├── start.js             # Launch script
+├── update.js            # Update script (for updating the scripts and app logic to the latest)
+├── reset.js             # Reset dependencies script
+├── pinokio.js           # UI generator script
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+- Keep app code in `/app` folder only (never in root)
+- Store all launcher files in project root (never in `/app`)
+- `/app` folder should be self-contained and publishable
+
+
+The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):
+
+```
+project-root/
+├── index.html           # The serverless web app entry point
+├── ...
+├── README.md            # Documentation
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (C:\pinokio\prototype\system\examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.
+
+## Launcher Project Working Directory
+
+- The project working directory for a script is always the same directory as the script location.
+- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.
+- If the launcher files are in the project root path, then the default path for shell execution is the project root.
+- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.
+
+Example: in the following project structure:
+
+```
+project-root/
+├── pinokio/                 # Pinokio launcher folder
+│    ├── start.js             # Launch script
+│    ├── pinokio.js           # UI generator script
+│    └── pinokio.json         # Metadata (title, description, icon)
+└─── backend/
+     ├── requirements.txt          # App dependencies
+     └── app.py                    # App code
+```
+
+The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:
+
+```
+{
+  run: [{
+    ...
+  }, {
+    method: "shell.run",
+    params: {
+      message: "python app.py",
+      venv: "env",
+      path: "../backend"
+    }
+  }, {
+    ...
+  }]
+}
+```
+
+## Development Workflow
+
+### 1. Understanding the Project
+- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)
+- If no `SPEC.md` exists, build based on user requirements
+### 2. Modifying Existing Launcher Projects
+If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.
+- **Preserve existing functionality:** Only modify necessary parts
+- **Don't touch working scripts:** Unless adding/updating specific commands
+- **Follow existing conventions:** Match the style and structure already present
+### 3. Try to adopt from examples as much as possible
+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (C:\pinokio\prototype\system\examples) to see if you can adopt them instead of coming up everything from scratch.
+- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.
+### 4. Writing from scratch as a last resort
+If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.
+### 5. Debugging
+When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.
+
+## Script Requirements
+
+### 1. 1-click launchable
+- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.
+
+### 2. Write Documentation
+- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:
+  - What the app does
+  - How to use the app
+  - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)
+
+## Types of launchers
+## 1. Launching servers
+- When an app requires launching a server, here are the commonly used scripts:
+  - `install.js`: a script to install the app
+  - `start.js`: a script to start the app
+  - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch
+  - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)
+  - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.
+  - `pinokio.json`: For metadata
+
+Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:
+
+```javascript
+module.exports = {
+  // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.
+  daemon: true,
+  run: [
+    {
+      // The "shell.run" API for running a shell session
+      method: "shell.run",
+      params: {
+        // Edit 'venv' to customize the venv folder path
+        venv: "env",
+        // Edit 'env' to customize environment variables (see documentation)
+        env: { },
+        // Edit 'path' to customize the path to start the shell from
+        path: "app",
+        // Edit 'message' to customize the commands, or to run multiple commands
+        message: [
+          "python app.py",
+        ],
+        on: [{
+          // The regular expression pattern to monitor.
+          // Whenever each "event" pattern occurs in the shell terminal, the shell will return,
+          // and the script will go onto the next step.
+          // The regular expression match object will be passed on to the next step as `input.event`
+          // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)
+          "event": "/(http:\/\/\\S+)/", 
+
+          // Use "done": true to move to the next step while keeping the shell alive.
+          // Use "kill": true to move to the next step after killing the shell.
+          "done": true
+        }]
+      }
+    },
+    {
+      // This step sets the local variable 'url'.
+      // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.
+      method: "local.set",
+      params: {
+        // the input.event is the regular expression match object from the previous step
+        // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.
+        // Therefore setting the local variable 'url'
+        url: "{{input.event[1]}}"
+      }
+    }
+  ]
+}
+```
+
+## 2. Launching serverless web apps
+
+- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.
+- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do 
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## 3. Launching quick scripts without web UI
+
+- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.
+- This may include TUI (Terminal User Interface) apps, a simple launcher 
+- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.
+- Here are some examples:
+  - A pinokio script to toggle the desktop theme between dark and light
+    - Write some code (python or javascript or whatever)
+    - Write a `toggle.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes
+  - A pinokio script to fetch some file
+    - Write some code (python or javascript or whatever)
+    - Write a `fetch.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## API
+
+This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:
+1. Check the examples in the C:\pinokio\prototype\system\examples folder
+2. Read the `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md further documentation on the full syntax
+
+### Script API
+
+These APIs can be used to describe each step in a pinokio script:
+- shell.run: run shell commands
+- input: accept user input
+- filepicker: accept file upload
+- fs.write: write to file
+- fs.read: read from file
+- fs.copy: copy files
+- fs.download: download files
+- fs.link: create a symbolic link (or junction on windows) for folders
+- fs.open: open the system file explorer at a given path
+- fs.cat: print file contents
+- jump: jump to a specific step
+- local.set: set local variables for the currently running script
+- json.set: update a json file
+- json.rm: remove keys from a json file
+- json.get: get values from a json file
+- log: print to the web terminal
+- net: make network requests
+- notify: display a notification
+- script.download: download a script from a git uri
+- script.start: start a script
+- script.stop: stop a script
+- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`
+- web.open: open a url in web browser
+- hf.download: huggingfac-cli download API
+### Template variables
+The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:
+- input: An input is a variable that gets passed from one RPC call to the next
+- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.
+- local: local variable object that can be set with `local.set` API
+- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.
+- uri: The current script uri
+- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.
+- cwd: The current script execution folder path
+- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`
+- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64
+- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)
+- gpu: the first available GPU (example: `nvidia`)
+- current: The current variable points to the index of the currently executing instruction within the run array.
+- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)
+- envs: You can access the environment variables of the currently running process with envs object.
+- which: Check whether a command exists (example: `{{which('winget')}}`. Can be used in the `when` attribute of a script step to run commands or install first.
+- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- os: Pinokio exposes the node.js os module through the os variable.
+- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`
+
+## System Capabilities
+### Package Management (Use in Order of Preference)
+The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:
+1. **UV** - For Python packages (preferred over pip)
+2. **NPM** - For Node.js packages  
+3. **Conda** - For cross-platform 3rd party binaries
+4. **Brew** - Mac-only fallback when other options unavailable
+5. **Git** - Full access to git is available.
+**Important:** Include all install commands in the install script for reproducibility.
+### HTTPS Proxy Support
+- All HTTP servers automatically get HTTPS endpoints
+- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`
+- Full proxy list available at: `http://localhost:2019/config/`
+### Pterm Features:
+- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)
+- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)
+- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)
+- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)
+- **Git Operations:** Clone repositories, push to GitHub
+- **GitHub Integration:** Full GitHub CLI support (`gh` commands)
+
+## Troubleshooting with Logs
+Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:
+
+### Log Structure
+In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:
+
+```
+pinokio/
+└── logs/   # Direct user interaction logs
+    ├── api/     # Launcher script logs (install.js, start.js, etc.)
+    ├── dev/     # AI coding tool logs (organized by tool)
+    └── shell/   # Direct user interaction logs
+```
+
+Otherwise, the `logs` folder should be found at project root:
+
+```
+logs/
+├── api/     # Launcher script logs (install.js, start.js, etc.)
+├── dev/     # AI coding tool logs (organized by tool)
+└── shell/   # Direct user interaction logs
+```
+
+### Log File Naming
+- Unix timestamps for each session
+- Special "latest" file contains most recent session logs
+- **Default:** Use "latest" files for current issues
+- **Historical:** Use timestamped files for pattern analysis and the full history.
+
+## Best practices
+### 0. Always reference the logs when debugging
+- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.
+### 1. Shell commands for launching programs
+- Launch flags related
+  - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.
+- Launch IP related
+  - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.
+- Launch Port related
+  - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.
+  - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.
+  - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`
+  - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.
+### 2. shell.run API
+- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.
+### 2. Package managers
+- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.
+- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.
+### 3. Minimal Always
+- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.
+- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.
+- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.
+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `C:\pinokio\api\Z-Image-Pinokio.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.
+  - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.
+- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.
+  - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.
+### 4. Try to support Cross-platform as much as possible
+- Use cross-platform shell commands only.
+- This means, prefer to use commands that work on all platforms instead of the current platform.
+- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.
+- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.
+- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.
+- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.
+### 5. Do not make assumptions about Pinokio API
+- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.
+- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.
+### 6. Scripts must be able to replicate install and launch steps 100%
+- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.
+- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.
+### 7 Dynamic UI rendering
+- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.
+  - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:
+    - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.
+  - Check the examples in the C:\pinokio\prototype\system\examples folder to see how these are being used.
+### 8. No need for stop scripts
+- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script
+### 9. Writing launchers for existing projects
+- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.
+- In most cases, the `README.md` file in the `C:\pinokio\api\Z-Image-Pinokio.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.
+- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.
+### 10. Don't use Docker unless really necessary
+- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.
+### 11. pinokio.json
+- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.
+- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.
+  - If the git repository for the `C:\pinokio\api\Z-Image-Pinokio.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`. 
+### 12. Gitignore
+- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:
+  - Cloning git repositories
+  - Downloading files
+  - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.
+- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.
+
+## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)
+If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:
+
+```
+// install.js
+module.exports = {
+  run: [
+    // Delete this step if your project does not use torch
+    {
+      method: "script.start",
+      params: {
+        uri: "torch.js",
+        params: {
+          path: "app",
+          venv: "venv",                // Edit this to customize the venv folder path
+          // xformers: true   // uncomment this line if your project requires xformers
+          // triton: true   // uncomment this line if your project requires triton
+          // sageattention: true   // uncomment this line if your project requires sageattention
+        }
+      }
+    },
+    // Edit this step with your custom install commands
+    {
+      method: "shell.run",
+      params: {
+        venv: "venv",                // Edit this to customize the venv folder path
+        path: "app",
+        message: [
+          "uv pip install -r requirements.txt"
+        ],
+      }
+    },
+  ]
+}
+```
+
+The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.
+
+
+## Quick Reference
+### Essential Documentation
+- **Pinokio Programming:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Programming Pinokio" section
+- **Dynamic Menus:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Dynamic menu rendering" section  
+- **CLI Commands:** See `PTERM.md` at C:\pinokio\prototype\PTERM.md
+### Common Patterns
+- **Python Virtual Env:** `shell.run` with `venv` attribute
+- **Cross-platform Commands:** Always test on multiple platforms
+- **Error Handling:** Check logs/api for launcher issues
+- **GitHub Operations:** Use `gh` CLI for advanced GitHub features
+## Development Principles
+1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands
+2. **Maintain Separation:** Keep app logic and launchers separate
+3. **Follow Conventions:** Match existing project patterns
+4. **Test Thoroughly:** Use CLI to verify launcher functionality
+5. **Document Changes:** Update relevant metadata and documentation

QWEN.md

@@ -0,0 +1,473 @@
+# Development Guide for Pinokio Projects
+
+## Non-Negotiable Execution Workflow
+
+To guarantee every contribution follows this guide precisely, obey this checklist **before any edits** and **again before finalizing**. Do not skip or reorder.
+1. **AGENTS Snapshot:** Re-open this file and write down (in your working notes or response draft) the exact sections relevant to the requested task. No work begins until this snapshot exists.
+2. **Example Lock-in:** Identify the closest matching script in `C:\pinokio\prototype\system\examples`. Record its path and keep it open while editing. Every launcher change must mirror that reference unless the user explicitly instructs otherwise.
+3. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, etc.). Confirm each item is ticked **before** making changes.
+4. **Mid-task Verification:** Any time you touch a Pinokio script, cross-check the corresponding example line to ensure syntax and structure match. Document the reference (example path + line) in your reasoning.
+5. **Exit Checklist:** Before responding to the user, revisit the pre-flight checklist and explicitly confirm every item is satisfied. If anything diverges from the example or these rules, fix it first.
+
+If any step cannot be completed, stop immediately and ask the user how to proceed. These five steps are mandatory for every session.
+
+### Critical Pattern Lock: Capturing Web UI URLs
+
+When writing `start.js` (or any script that needs to surface a web URL for a server):
+
+1. **Always copy the capture block from an example such as `system/examples/mochi/start.js`.**
+```javascript
+on: [{
+  event: "/(http:\\/\\/[0-9.:]+)/",
+  done: true
+}]
+```
+
+2. **Set the local variable using the captured match exactly as below (The regex capture object is passed in as `input.event`, so need to use the index 1 inside the parenthesis):**
+```javascript
+{
+  method: "local.set",
+  params: {
+    url: "{{input.event[1]}}"
+  }
+}
+```
+
+3. Always try to come up with the most generic regex.
+4. During the exit checklist, explicitly confirm that the `url` local variable is set via `local.set` API by using the captured regex object as passed in as `input.event` from the previous `shell.run` step.
+
+Deviation from this pattern requires written approval from the user.
+
+- Make sure to keep this entire document and `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md in memory with high priority before making any decision. Pinokio is a system that makes it easy to write launchers through scripting by providing various cross-platform APIs, so whenever possible you should prioritize using Pinokio API over lower level APIs.
+- When writing pinokio scripts, ALWAYS check the examples folder (in C:\pinokio\prototype\system\examples folder) to see if there are existing example scripts you can imitate, instead of assuming syntax.
+- When implementing pinokio script APIs and you cannot infer the syntax just based on the examples, always search the API documentation `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md to use the correct syntax instead of assuming the syntax.
+- When trying to fix something or figure out what's going on, ALWAYS start by checking the `logs` folder before doing anything else, as mentioned in the "Troubleshooting with Logs" section.
+- Finally, make sure to ALWAYS follow all the items in the "best practices" section below.
+
+## Determine User Intent
+If the initial prompt is simply a URL and nothing else, check the website content and determine the intent, and ask the user to confirm. For example a URL may point to
+
+1. A Tutorial: the intent may be to implement a demo for the tutorial and build a launcher.
+2. A Demo: the intent may be a 1-click launcher for the demo
+3. Open source project: the intent may be a 1-click launcher for the project 
+4. Regular website: the intent may be to clone the website and a launcher.
+5. There can be other cases, but try to guess.
+
+## Project Structure
+
+Pinokio projects normally follow a standardized structure with app logic separated from launcher scripts:
+
+Pinokio projects follow a standardized structure with app logic separated from launcher scripts:
+
+```
+project-root/
+├── app/                 # Self-contained app logic (can be standalone repo)
+│   ├── package.json     # Node.js projects
+│   ├── requirements.txt # Python projects
+│   └── ...              # Other language-specific files
+├── README.md            # Documentation
+├── install.js           # Installation script
+├── start.js             # Launch script
+├── update.js            # Update script (for updating the scripts and app logic to the latest)
+├── reset.js             # Reset dependencies script
+├── pinokio.js           # UI generator script
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+- Keep app code in `/app` folder only (never in root)
+- Store all launcher files in project root (never in `/app`)
+- `/app` folder should be self-contained and publishable
+
+
+The only exceptions are serverless web apps---purely frontend only web applications that do NOT have a server component and connect to 3rd party API endpoints--in which case the folder structure looks like the following (No need for launcher scripts since the index.html will automatically launch. The only thing needed is the metadata file named pinokio.json):
+
+```
+project-root/
+├── index.html           # The serverless web app entry point
+├── ...
+├── README.md            # Documentation
+└── pinokio.json         # Metadata (title, description, icon)
+```
+
+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (C:\pinokio\prototype\system\examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.
+
+## Launcher Project Working Directory
+
+- The project working directory for a script is always the same directory as the script location.
+- For example, when you run `shell.run` API inside `pinokio/start.js`, the default path for shell execution is `pinokio`.
+- If the launcher files are in the project root path, then the default path for shell execution is the project root.
+- Therefore, it is important to specify the correct `path` attribute when running `shell.run` API commands.
+
+Example: in the following project structure:
+
+```
+project-root/
+├── pinokio/                 # Pinokio launcher folder
+│    ├── start.js             # Launch script
+│    ├── pinokio.js           # UI generator script
+│    └── pinokio.json         # Metadata (title, description, icon)
+└─── backend/
+     ├── requirements.txt          # App dependencies
+     └── app.py                    # App code
+```
+
+The `pinokio/start.js` should use the correct path `../backend` as the `path` attribute, as follows:
+
+```
+{
+  run: [{
+    ...
+  }, {
+    method: "shell.run",
+    params: {
+      message: "python app.py",
+      venv: "env",
+      path: "../backend"
+    }
+  }, {
+    ...
+  }]
+}
+```
+
+## Development Workflow
+
+### 1. Understanding the Project
+- Check `SPEC.md` in project root. If the file exists, use that to learn about the project details (what and how to build)
+- If no `SPEC.md` exists, build based on user requirements
+### 2. Modifying Existing Launcher Projects
+If we are starting with existing launcher script files, work with the existing files instead of coming up with your own.
+- **Preserve existing functionality:** Only modify necessary parts
+- **Don't touch working scripts:** Unless adding/updating specific commands
+- **Follow existing conventions:** Match the style and structure already present
+### 3. Try to adopt from examples as much as possible
+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (C:\pinokio\prototype\system\examples) to see if you can adopt them instead of coming up everything from scratch.
+- Even if there are no relevant examples, check the examples to get inspiration for how you would structure the script files even if you have to write from scratch.
+### 4. Writing from scratch as a last resort
+If there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.
+### 5. Debugging
+When the user reports something is not working, ALWAYS inspect the logs folder to get all the execution logs. For more info on how this works, check the "Troubleshooting with Logs" section below.
+
+## Script Requirements
+
+### 1. 1-click launchable
+- The main purpose of Pinokio is to provide an easy interface to invoke commands, which may include launching servers, installing programs, etc. Make sure the final product provides ways to install, launch, reset, and update whatever is needed.
+
+### 2. Write Documentation
+- ALWAYS write a documentation. A documentation must be stored as `README.md` in the project root folder, along with the rest of the pinokio launcher script files. A documentation file must contain:
+  - What the app does
+  - How to use the app
+  - API documentation for programmatically accessing the app's main features (Javascript, Python, and Curl)
+
+## Types of launchers
+## 1. Launching servers
+- When an app requires launching a server, here are the commonly used scripts:
+  - `install.js`: a script to install the app
+  - `start.js`: a script to start the app
+  - `reset.js`: a script to reset all the dependencies installed in the `install.js` step. used if the user wants to restart from scratch
+  - `update.js`: a script to update the launcher AND the app in case there are new updates. Involves pulling in the relevant git repositories installed through `install.js` (often it's the script repo and some git repositories cloned through the install steps if any)
+  - `pinokio.js`: the launcher script that ties all of the above scripts together by providing a UI that links to these scripts.
+  - `pinokio.json`: For metadata
+
+Here's a basic server launcher script example (`start.js`). Unless there's a special reason you need to use another pattern, this is the most recommended pattern. Use this or adopt it as needed, but NEVER try something else unless there's a good reason you should not take this approach:
+
+```javascript
+module.exports = {
+  // By setting daemon: true, the script keeps running even after all items in the `run` array finishes running. Mandatory for launching servers, since otherwise the shells running the server process will get killed after the scripts finish running.
+  daemon: true,
+  run: [
+    {
+      // The "shell.run" API for running a shell session
+      method: "shell.run",
+      params: {
+        // Edit 'venv' to customize the venv folder path
+        venv: "env",
+        // Edit 'env' to customize environment variables (see documentation)
+        env: { },
+        // Edit 'path' to customize the path to start the shell from
+        path: "app",
+        // Edit 'message' to customize the commands, or to run multiple commands
+        message: [
+          "python app.py",
+        ],
+        on: [{
+          // The regular expression pattern to monitor.
+          // Whenever each "event" pattern occurs in the shell terminal, the shell will return,
+          // and the script will go onto the next step.
+          // The regular expression match object will be passed on to the next step as `input.event`
+          // Useful for capturing the URL at which the server is running (in case the server prints some message about where the server is running)
+          "event": "/(http:\/\/\\S+)/", 
+
+          // Use "done": true to move to the next step while keeping the shell alive.
+          // Use "kill": true to move to the next step after killing the shell.
+          "done": true
+        }]
+      }
+    },
+    {
+      // This step sets the local variable 'url'.
+      // This local variable will be used in pinokio.js to display the "Open WebUI" tab when the value is set.
+      method: "local.set",
+      params: {
+        // the input.event is the regular expression match object from the previous step
+        // In this example, since the pattern was "/(http:\/\/\\S+)/", input.event[1] will include the exact http url match caputred by the parenthesis.
+        // Therefore setting the local variable 'url'
+        url: "{{input.event[1]}}"
+      }
+    }
+  ]
+}
+```
+
+## 2. Launching serverless web apps
+
+- In case of purely static web apps WITHOUT servers or backends (for example an HTML based app that connects to 3rd party servers--either remote or localhost), we do NOT need the launcher scripts.
+- In these cases, simply include `index.html` in the project root folder and everything should automatically work. No need for any of the pinokio launcher scripts. (Do 
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## 3. Launching quick scripts without web UI
+
+- In many cases, we may not even need a web UI, but instead just a simple way to run scripts.
+- This may include TUI (Terminal User Interface) apps, a simple launcher 
+- In these cases, all we need is the launcher file `pinokio.js`, which may link to multiple scripts. In this case, there are no web apps (no serverless apsp, no servers), but instead just the default pinokio launcher UI that calls a bunch of scripts.
+- Here are some examples:
+  - A pinokio script to toggle the desktop theme between dark and light
+    - Write some code (python or javascript or whatever)
+    - Write a `toggle.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `toggle.js` so the user can simply click the "toggle" button to toggle back and forth between desktop themes
+  - A pinokio script to fetch some file
+    - Write some code (python or javascript or whatever)
+    - Write a `fetch.js` pinokio script that executes the code
+    - Write a `pinokio.js` launcher script to create a sidebar UI that displays the `fetch.js` so the user can simply click the "fetch" button to fetch some data.
+- You still need to include the metadata file so they show up properly on pinokio:
+  - `pinokio.json`: For metadata
+
+## API
+
+This section lists all the script APIs available on Pinokio. To learn the details of how they are used, you can:
+1. Check the examples in the C:\pinokio\prototype\system\examples folder
+2. Read the `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md further documentation on the full syntax
+
+### Script API
+
+These APIs can be used to describe each step in a pinokio script:
+- shell.run: run shell commands
+- input: accept user input
+- filepicker: accept file upload
+- fs.write: write to file
+- fs.read: read from file
+- fs.copy: copy files
+- fs.download: download files
+- fs.link: create a symbolic link (or junction on windows) for folders
+- fs.open: open the system file explorer at a given path
+- fs.cat: print file contents
+- jump: jump to a specific step
+- local.set: set local variables for the currently running script
+- json.set: update a json file
+- json.rm: remove keys from a json file
+- json.get: get values from a json file
+- log: print to the web terminal
+- net: make network requests
+- notify: display a notification
+- script.download: download a script from a git uri
+- script.start: start a script
+- script.stop: stop a script
+- script.return: return values if the current script was called by a caller script, so the caller script can utilize the return value as `input`
+- web.open: open a url in web browser
+- hf.download: huggingfac-cli download API
+### Template variables
+The following variables are accessible inside template expressions (example `{{args.command}` in scripts, resulting in dynamic behaviors of scripts:
+- input: An input is a variable that gets passed from one RPC call to the next
+- args: args is the parameter object that gets passed into the script (via pinokio.js `params`). Unlike `input` which takes the value passed in from the immediately previous step, `args` is a global value that is the same through out the entire script execution.
+- local: local variable object that can be set with `local.set` API
+- self: refers to the script file itself (which is JSON or JavaScript). For example if `start.js` that's currently running has `daemon: true` set, `{{self.daemon}}` will evaluate to true.
+- uri: The current script uri
+- port: The next available port. Very useful when you need to launch an app at a specific port without port conflicts.
+- cwd: The current script execution folder path
+- platform: The current operating system. May be one of the following: `darwin`, `win32`, `linux`
+- arch: The current system architecture. May be one of the following: x32, x64, arm, arm64, s390, s390x, mipsel, ia32, mips, ppc, ppc64
+- gpus: array of available GPUs on the machine (example: `['apple']`, `['nvidia']`)
+- gpu: the first available GPU (example: `nvidia`)
+- current: The current variable points to the index of the currently executing instruction within the run array.
+- next: The next variable points to the index of the next instruction to be executed. (null if the current instruction is the final instruction in the run array)
+- envs: You can access the environment variables of the currently running process with envs object.
+- which: Check whether a command exists (example: `{{which('winget')}}`. Can be used in the `when` attribute of a script step to run commands or install first.
+- exists: Check whether a file or folder exists at the specified relative path (example: `"when": "{{!exists('app')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- running: Check whether a script file is running (example: `"when": "{{!running('start.js')}}"`). Can be used with the `when` attribute to determine a path's existence and trigger custom logic. Use relative paths and it will resolve automatically to the current execution folder. 
+- os: Pinokio exposes the node.js os module through the os variable.
+- path: Pinokio exposes the node.js path module through the os variable (example: `{{path.resolve(...)}}`
+
+## System Capabilities
+### Package Management (Use in Order of Preference)
+The following package managers come pre-installed with Pinokio, so whenever you need to install a 3rd party binary, remember that these are available. Also, you can assume these are available and include the following package manager commands in Pinokio scripts:
+1. **UV** - For Python packages (preferred over pip)
+2. **NPM** - For Node.js packages  
+3. **Conda** - For cross-platform 3rd party binaries
+4. **Brew** - Mac-only fallback when other options unavailable
+5. **Git** - Full access to git is available.
+**Important:** Include all install commands in the install script for reproducibility.
+### HTTPS Proxy Support
+- All HTTP servers automatically get HTTPS endpoints
+- Convention: `http://localhost:<PORT>` → `https://<PORT>.localhost`
+- Full proxy list available at: `http://localhost:2019/config/`
+### Pterm Features:
+- **Clipboard Access:** Read from or Write to system clipboard via pinokio Pterm CLI (`pterm clipboard` command.)
+- **Notifications:** Send desktop alerts via pinokio pterm CLI (`pterm push` command.)
+- **Script Testing:** Run launcher scripts via pinokio pterm CLI (`pterm start` command.)
+- **File Selection:** Use built-in filepicker for user file/folder input (`pterm filepicker` command.)
+- **Git Operations:** Clone repositories, push to GitHub
+- **GitHub Integration:** Full GitHub CLI support (`gh` commands)
+
+## Troubleshooting with Logs
+Pinokio stores the logs for everything that happened in terminal at the following locations, so you can make use of them to determine what's going on:
+
+### Log Structure
+In case there is a `pinokio` folder in the project root folder, you should be able to find the logs folder here:
+
+```
+pinokio/
+└── logs/   # Direct user interaction logs
+    ├── api/     # Launcher script logs (install.js, start.js, etc.)
+    ├── dev/     # AI coding tool logs (organized by tool)
+    └── shell/   # Direct user interaction logs
+```
+
+Otherwise, the `logs` folder should be found at project root:
+
+```
+logs/
+├── api/     # Launcher script logs (install.js, start.js, etc.)
+├── dev/     # AI coding tool logs (organized by tool)
+└── shell/   # Direct user interaction logs
+```
+
+### Log File Naming
+- Unix timestamps for each session
+- Special "latest" file contains most recent session logs
+- **Default:** Use "latest" files for current issues
+- **Historical:** Use timestamped files for pattern analysis and the full history.
+
+## Best practices
+### 0. Always reference the logs when debugging
+- When the user asks to fix something, ALWAYS check the logs folder first to check what went wrong. Check the "Troubleshooting with Logs" section.
+### 1. Shell commands for launching programs
+- Launch flags related
+  - Try as hard as possible to minimize launch flags and parameters when launching an app. For example, instead of `python app.py --port 8610`, try to do `python app.py` unless really necessary. The only exception is when the only way to launch the app is to specify the flags.
+- Launch IP related
+  - Always try to find a way to launch servers at 127.0.0.1 or localhost, often by specifying launch flags or using environment variables. Some apps launch apps at 0.0.0.0 by default but we do not want this.
+- Launch Port related
+  - In case the app itself automatically launches at the next available port by default (for example Gradio does this), do NOT specify port, since it's taken care of by the app itself. Always try to minimize the amount of code.
+  - If the install instruction says to launch at a specific port, don't use the hardcoded port they suggest since there's a risk of port conflicts. Instead, use Pinokio's `{{port}}` template expression to automatically get the next available port.
+  - For example, if the instruction says `python app.py --port 7860`, don't use that hardcoded port since there might be another app running at that port. Instead, automatically assign the next available port like this: `python app.py --port {{port}}`
+  - Note that the `{{port}}` expression always returns the next immediately available port for each step, so if you have multiple steps in a script and use `{{port}}` in multiple steps, the value will be different. So if you want to launch at the next available port and then later reuse that port, you will need to first use `{{port}}` to get the next available port, and save the value in local variable using `local.set`, and then use the `{{local.<variable_name>}}` expression later.
+### 2. shell.run API
+- When writing `shell.run` API requests, always use relative paths (no absolute paths) for the `path` field. For example, if you need to run a command from `app` folder, the `path` attribute should simply be `app`, instead of its full absolute path.
+### 2. Package managers
+- When installing python packages, try best to use `uv` instead of `pip` even if the install instruction says to use pip. Instead of `pip install -r requirements.txt`, you can simply use `uv pip install -r requirements.txt` for example. Even if the project's own README says use pip or poetry, first check if there's a way to use uv instead.
+- When you need to install some global package, try to use `conda` as much as possible. Even on macs, `brew` should be only used if there are no `conda` options.
+### 3. Minimal Always
+- If you are starting with existing script files, before modifying, creating, or removing any script files, first look at `pinokio.js` to understand which script files are actually used in the launcher. The only script files used are the ones mentioned in the `pinokio.js` file. The `pinokio.js` file is the file that constructs the UI dynamically.
+- Do not create a redundant script file that does something that already exists. Instead modify the existing script file for the feature. For example, do not create an `install.json` file for installation if `install.js` already exists. Instead, modify the `install.js` file.
+- Pinokio accepts both JSON and JS script files, so when determining whether a script for a specific purpose already exists, check both JSON and JS files mentioned in the `pinokio.js` file. Do not create script files for rendundant purpose.
+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `C:\pinokio\api\Z-Image-Pinokio.git` folder), even if installations are failing. Instead, try to work around it by creating additional files in the launcher folder, and using those files IN ADDITION to the default project.
+  - The only exception when you may need to make changes to the project folder is when the user explicitly wants to modify the existing project. Otherwise if the purpose is to simply write a launcher, the app logic folder should never be touched.
+- When running shell commands, take full advantage of the Pinokio `shell.run` API, which provides features like `env`, `venv`, `input`, `path`, `sudo`, `on`, etc. which can greatly reduce the amount of script code.
+  - Python apps: Always use virtual environments via `venv` attribute. This attribute automatically creates a venv or uses if it already exists.
+### 4. Try to support Cross-platform as much as possible
+- Use cross-platform shell commands only.
+- This means, prefer to use commands that work on all platforms instead of the current platform.
+- If there are no cross platform commands, use Pinokio's template expressions to conditionally use commands depending on `platform`, `arch`, etc.
+- Also try to utilize Pinokio Pterm APIs for various cross-platform system features.
+- If it is impossible to implement a cross platform solution (due to the nature of the project itself), set the `platform`, `arch`, and/or `gpu` attributes of the `pinokio.json` file to declare the limitation.
+- Pinokio provides various APIs for cross-platform way of calling commonly used system functions, or lets you selectively run commands depending on `platform`, `arch`, etc.
+### 5. Do not make assumptions about Pinokio API
+- Do NOT make assumptions about which Pinokio APIs exist. Check the documentation.
+- Do NOT make assumptions about the Pinokio API syntax. Follow the documentation.
+### 6. Scripts must be able to replicate install and launch steps 100%
+- The whole point of the scripts is for others to easily download and invoke them via Pinokio interface with one click. Therefore, do not assume the end user's system state, and make everything self-contained.
+- When a 3rd party package needs to be installed, or a 3rd party repository needs to be downloaded, include them in the scripts.
+### 7 Dynamic UI rendering
+- The `pinokio.js` launcher script can change dynamically depending on the current state of the script execution. Which means, depending on what the file returns, it can determine what the sidebar looks like at any given moment of the script cycle.
+  - `info.exists(relative_path)`: The `info.exists` can be used to check whether a relative path (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.running(relative_path)`: The `info.running` can be used to check whether a script at a relative path is currently running (relative to the script root path) exists. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `info.local(relative_path)`: The `info.local` can be used to return all the local variables tied to a script that's currently running. The `pinokio.js` file can determine which menu items to return based on this value at any given moment.
+  - `default`: set the `default` attribute on any menu item for whichever menu needs to be selected by default at a given step. Some example scenarios:
+    - during the install process, the `install.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - when launching the `start.js` menu item needs to be set as the `default`, so it automatically executes the script
+    - after the app has launched, the `default` needs to be set on the web UI URL, so the user is sent to the actual app automatically.
+  - Check the examples in the C:\pinokio\prototype\system\examples folder to see how these are being used.
+### 8. No need for stop scripts
+- `pinokio.js` does NOT need a separate `stop` script. Every script that can be started can also be natively stopped through the Pinokio UI, therefore you do not need a separate stop script for start script
+### 9. Writing launchers for existing projects
+- When writing or modifying pinokio launcher scripts, figure out the install/launch steps by reading the project folder `app`.
+- In most cases, the `README.md` file in the `C:\pinokio\api\Z-Image-Pinokio.git` folder contains the instructions needed to install and run the app, but if not, figure out by scanning the rest of the project files.
+- Install scripts should work for each specific operating system, so ignore Docker related instructions. Instead use install/launch instructions for each platform.
+### 10. Don't use Docker unless really necessary
+- Some projects suggest docker as installation options. But even in these cases, try to find "development" options to launch the app without relying on Docker, as much as possible. We do not need Docker since we can automatically install and launch apps specifically for the user's platform, since we can write scripts that run cross platform.
+### 11. pinokio.json
+- Do not touch the `version` field since the version is the script schema version and the one pre-set in `pinokio.js` must be used.
+- `icon`: It's best if we have a user friendly icon to represent the app, so try to get an image and link it from `pinokio.json`.
+  - If the git repository for the `C:\pinokio\api\Z-Image-Pinokio.git` folder points to GitHub (for example https://github.com/<USERNAME>/<REPO_NAME>`, ask the user if they want to download the icon from GitHub, and if approved, get the `avatar_url` by fetching `https://api.github.com/users/<USERNAME>`, and then download the image to the root folder as `icon.png`, and set `icon.png` as the `icon` field of the `pinokio.json`. 
+### 12. Gitignore
+- When a launcher involves cloning 3rd party repositories, downloading files dynamically, or some files to be generated, these need to be included in the .gitignore file. This may include things like:
+  - Cloning git repositories
+  - Downloading files
+  - Dynamically creating files during installation or running, such as Sqlite Databases, or environment variables, or anything specific to the user.
+- Make sure these file paths are included in the .gitignore file, and if not, include them in .gitignore.
+
+## AI Libraries (Pytorch, Xformers, Triton, Sageattention, etc.)
+If the launcher has a dedicated built-in script named `torch.js`, it can be used as follows:
+
+```
+// install.js
+module.exports = {
+  run: [
+    // Delete this step if your project does not use torch
+    {
+      method: "script.start",
+      params: {
+        uri: "torch.js",
+        params: {
+          path: "app",
+          venv: "venv",                // Edit this to customize the venv folder path
+          // xformers: true   // uncomment this line if your project requires xformers
+          // triton: true   // uncomment this line if your project requires triton
+          // sageattention: true   // uncomment this line if your project requires sageattention
+        }
+      }
+    },
+    // Edit this step with your custom install commands
+    {
+      method: "shell.run",
+      params: {
+        venv: "venv",                // Edit this to customize the venv folder path
+        path: "app",
+        message: [
+          "uv pip install -r requirements.txt"
+        ],
+      }
+    },
+  ]
+}
+```
+
+The `torch.js` script also includes ways to install pytorch dependent libraries such as xformers, triton, sagetattention. If any of these libraries need to be installed, use the torch.js to install in order to install them cross platform.
+
+
+## Quick Reference
+### Essential Documentation
+- **Pinokio Programming:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Programming Pinokio" section
+- **Dynamic Menus:** See `PINOKIO.md` at C:\pinokio\prototype\PINOKIO.md → "Dynamic menu rendering" section  
+- **CLI Commands:** See `PTERM.md` at C:\pinokio\prototype\PTERM.md
+### Common Patterns
+- **Python Virtual Env:** `shell.run` with `venv` attribute
+- **Cross-platform Commands:** Always test on multiple platforms
+- **Error Handling:** Check logs/api for launcher issues
+- **GitHub Operations:** Use `gh` CLI for advanced GitHub features
+## Development Principles
+1. **Minimize Shell Usage:** Leverage API parameters instead of raw commands
+2. **Maintain Separation:** Keep app logic and launchers separate
+3. **Follow Conventions:** Match existing project patterns
+4. **Test Thoroughly:** Use CLI to verify launcher functionality
+5. **Document Changes:** Update relevant metadata and documentation

README.md

@@ -1,3 +1,98 @@
----
-license: mit
----
+# Z-Image-Turbo Special Edition for Pinokio
+
+A Gradio web interface for the Z-Image-Turbo model, designed for easy installation via [Pinokio](https://pinokio.computer/).
+This Version is based on https://github.com/PierrunoYT/Z-Image-Pinokio.git
+
+## Features
+
+- **One-Click Install** - Pinokio handles all dependencies automatically
+- **Modern Gradio UI** - Clean interface with all generation options
+- **High-Quality Images** - Uses the Z-Image-Turbo model from Tongyi-MAI
+- **Fast Generation** - Turbo model generates images in just 8 steps
+- **Full Control** - Adjustable dimensions, steps, guidance, and seed
+- **Support Lora** - supports loading LoRA. You can download the LoRA of Z-Image Turbo from C Station for use, or use the LoRA you trained yourself.
+- **Support Select transformer** - supports the use of custom transformers, and you can download the Z-Image model from C Station for use.
+
+## Installation
+
+### Via Pinokio (Recommended)
+
+1. Install [Pinokio](https://pinokio.computer/)
+2. Search for "Z-Image-Turbo" or add this repository URL
+3. Click **Install** - Pinokio will:
+   - Create a Python virtual environment
+   - Install PyTorch with CUDA support
+   - Install diffusers from source (required for ZImagePipeline)
+   - Download the Z-Image-Turbo model (~12GB)
+4. Click **Start** to launch the web UI
+<img width="3192" height="1846" alt="image" src="https://github.com/user-attachments/assets/9eb880f8-7c1e-4e68-b3cf-7d6d6bd7c392" />
+<img width="3200" height="1836" alt="image" src="https://github.com/user-attachments/assets/3b782a31-17eb-4642-b75c-a91b7d8e8858" />
+
+### Manual Installation
+
+```bash
+# Clone the repository
+git clone https://github.com/leewheel/Z-Image-Pinokio-Special-Edition.git
+cd Z-Image-Pinokio-Special-Edition
+
+# Create virtual environment
+python -m venv env
+source env/bin/activate  # Linux/Mac
+# or: env\Scripts\activate  # Windows
+
+# Install dependencies
+pip install -r requirements.txt
+pip install git+https://github.com/huggingface/diffusers
+
+# Run the app
+python app.py
+```
+
+## Usage
+
+1. **Start** the app via Pinokio or `python app.py`
+2. Open `http://localhost:7860` in your browser
+3. Enter a prompt describing your image
+4. Adjust settings:
+   - **Width/Height**: 512-2048px (default 1024x1024)
+   - **Inference Steps**: 1-20 (default 9, recommended for Turbo)
+   - **Guidance Scale**: 0.0-10.0 (default 0.0 for Turbo model)
+   - **Seed**: Set specific seed or randomize
+5. Click **Generate**
+
+## Settings Guide
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| Width/Height | 1024 | Image dimensions (512-2048px) |
+| Inference Steps | 9 | Number of denoising steps (8 actual DiT forwards) |
+| Guidance Scale | 0.0 | CFG scale (0.0 recommended for Turbo) |
+| Seed | Random | Reproducibility control |
+
+## System Requirements
+
+### Minimum
+- **GPU**: 4GB VRAM (NVIDIA with CUDA)
+- **RAM**: 16GB
+- **Storage**: ~15GB for model
+
+### Recommended
+- **GPU**: 16GB+ VRAM (RTX 3090, 4090, etc.)
+- **RAM**: 32GB
+- **Storage**: SSD for faster loading
+
+## Model Info
+
+- **Model**: [Tongyi-MAI/Z-Image-Turbo](https://huggingface.co/Tongyi-MAI/Z-Image-Turbo)
+- **License**: Apache 2.0
+- **Size**: ~12GB
+
+## Credits
+
+- **Z-Image-Turbo**: [Tongyi-MAI (Alibaba)](https://huggingface.co/Tongyi-MAI)
+- **Diffusers**: [Hugging Face](https://github.com/huggingface/diffusers)
+- **Pinokio**: [Pinokio](https://pinokio.computer/)
+
+## License
+
+MIT

Sampleapp.py

@@ -0,0 +1,646 @@
+import os
+os.environ["DIFFUSERS_USE_PEFT_BACKEND"] = "1"  # Enable The PEFT LoRA backend of diffusers
+
+import uuid
+import random
+from datetime import datetime
+import re
+
+import torch
+import gradio as gr
+from diffusers import ZImagePipeline, AutoencoderKL, ZImageTransformer2DModel
+from transformers import AutoModelForCausalLM
+
+
+# =========================
+# Path configuration (all based on the directory where app.py is located)
+# =========================
+
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+
+# Official model: Z-Image-Turbo snapshot in the HF cache
+BASE_SNAPSHOT_DIR = os.path.join(
+    BASE_DIR,
+    "cache",
+    "HF_HOME",
+    "hub",
+    "models--Tongyi-MAI--Z-Image-Turbo",
+    "snapshots",
+    "5f4b9cbb80cc95ba44fe6667dfd75710f7db2947",
+)
+
+TRANSFORMER_ROOT = os.path.join(BASE_SNAPSHOT_DIR, "transformer")
+TEXT_ENCODER_ROOT = os.path.join(BASE_SNAPSHOT_DIR, "text_encoder")
+VAE_ROOT = os.path.join(BASE_SNAPSHOT_DIR, "vae")
+
+# Custom model directory (All the models you added later will be placed here)
+MOD_DIR = os.path.join(BASE_DIR, "MOD")
+MOD_TRANSFORMER = os.path.join(MOD_DIR, "transformer")
+MOD_TEXT_ENCODER = os.path.join(MOD_DIR, "text_encoder")
+MOD_VAE = os.path.join(MOD_DIR, "vae")
+
+# LoRA and output
+LORA_ROOT = os.path.join(BASE_DIR, "lora")
+OUTPUT_DIR = os.path.join(BASE_DIR, "outputs")
+
+for p in [MOD_TRANSFORMER, MOD_TEXT_ENCODER, MOD_VAE, LORA_ROOT, OUTPUT_DIR]:
+    os.makedirs(p, exist_ok=True)
+
+print("=== BASE_DIR ===", BASE_DIR)
+print("=== OFFICIAL SNAPSHOT DIR ===", BASE_SNAPSHOT_DIR)
+print("=== MOD DIR ===", MOD_DIR)
+
+# Global pipeline cache
+pipe = None
+current_model_config = {
+    "transformer": "default",
+    "text_encoder": "default",
+    "vae": "default",
+}
+
+
+# =========================
+# LoRA Tools
+# =========================
+
+def scan_lora_items():
+    """Scan all .safetensors files under ./lora as optional LoRAs."""
+    if not os.path.isdir(LORA_ROOT):
+        return []
+    items = []
+    for name in sorted(os.listdir(LORA_ROOT)):
+        full = os.path.join(LORA_ROOT, name)
+        if os.path.isfile(full) and name.lower().endswith(".safetensors"):
+            items.append(name)
+    return items
+
+
+def build_lora_tags(selected_loras, lora_alpha):
+    """Generate <lora:name:alpha> tags and unify alpha."""
+    tags = []
+    try:
+        alpha = float(lora_alpha)
+    except Exception:
+        alpha = 1.0
+
+    alpha_str = f"{alpha:.2f}".rstrip("0").rstrip(".")
+
+    for fname in selected_loras or []:
+        base = os.path.splitext(os.path.basename(fname))[0]
+        if not base:
+            continue
+        tags.append(f"<lora:{base}:{alpha_str}>")
+    return tags
+
+
+def update_prompt_with_lora(prompt, selected_loras, lora_alpha):
+    """Embed/Update LoRA tags in the prompt"""
+    prompt = prompt or ""
+    # 先清理掉旧的 <lora:...> 标签
+    prompt_clean = re.sub(r"<lora:[^>]+>", "", prompt).strip()
+    tags = build_lora_tags(selected_loras, lora_alpha)
+    if tags:
+        if prompt_clean:
+            prompt_clean = prompt_clean + " " + " ".join(tags)
+        else:
+            prompt_clean = " ".join(tags)
+    return prompt_clean
+
+
+def apply_lora_to_pipeline(pipe_local, selected_loras, lora_alpha):
+    """Inject LoRA into the pipeline (diffusers PEFT backend, multiple LoRAs + alpha)"""
+    if pipe_local is None:
+        return None
+    if not selected_loras:
+        return pipe_local
+
+    try:
+        alpha = float(lora_alpha)
+    except Exception:
+        alpha = 1.0
+
+    adapter_names = []
+
+    for lora_file in selected_loras:
+        lora_path = os.path.join(LORA_ROOT, lora_file)
+        if not os.path.isfile(lora_path):
+            print(f"[LoRA] The file does not exist, skipping.: {lora_path}")
+            continue
+
+        base_name = os.path.splitext(os.path.basename(lora_file))[0]
+        safe_adapter_name = re.sub(r"[^a-zA-Z0-9_]", "_", base_name)
+
+        try:
+            print(f"[LoRA] Loading: {lora_path} as adapter '{safe_adapter_name}'")
+            pipe_local.load_lora_weights(
+                lora_path,
+                adapter_name=safe_adapter_name,
+            )
+            adapter_names.append(safe_adapter_name)
+        except Exception as e:
+            print(f"❌ [LoRA] load failed {lora_file}: {e}")
+
+    if adapter_names:
+        pipe_local.set_adapters(
+            adapter_names=adapter_names,
+            adapter_weights=[alpha] * len(adapter_names),
+        )
+        print(f"✅ [LoRA] activated {len(adapter_names)} LoRAs, alpha={alpha}")
+    else:
+        print("[LoRA] No LoRA adapters were successfully loaded.")
+
+    return pipe_local
+
+
+# =========================
+# Model scanning and loading
+# =========================
+
+def scan_model_variants(root_dir, label="Model"):
+    """
+    Scan the "available model subdirectories" under root_dir.
+
+    Rules: Only consider a directory as an optional model if:
+    - It is a subdirectory
+    - The subdirectory contains config.json
+    - And it contains at least one .safetensors or .safetensors.index.json
+
+    This allows compatibility with:
+    - Diffusers style: config.json + diffusion_pytorch_model.safetensors
+    - Z-Image AE: config.json + ae.safetensors
+    """
+    if not os.path.isdir(root_dir):
+        return []
+
+    variants = []
+    print(f"🔍 [Scan] {label}: {root_dir}")
+
+    for name in sorted(os.listdir(root_dir)):
+        subdir = os.path.join(root_dir, name)
+        if not os.path.isdir(subdir):
+            continue
+
+        has_config = os.path.isfile(os.path.join(subdir, "config.json"))
+
+        has_safetensors = False
+        for f in os.listdir(subdir):
+            if f.endswith(".safetensors") or f.endswith(".safetensors.index.json"):
+                has_safetensors = True
+                break
+
+        if has_config and has_safetensors:
+            variants.append(name)
+
+    return variants
+
+
+def get_choices(mod_root, label):
+    """Scan custom models only from the MOD folder, default = official snapshot"""
+    variants = scan_model_variants(mod_root, label=f"Custom-{label}")
+    return ["default"] + sorted(list(set(variants)))
+
+
+def resolve_model_dir(choice, mod_root):
+    """Parse to the corresponding directory based on the drop-down selection result; return None by default."""
+    if choice == "default":
+        return None
+    subdir = os.path.join(mod_root, choice)
+    if os.path.isdir(subdir):
+        return subdir
+    print(f"❌ [Model] 未找到模型目录: {subdir}")
+    return None
+
+
+def pick_vae_weight_name(vae_dir):
+    """
+    为 VAE 选择合适的 safetensors 文件名：
+    - 优先 ae.safetensors
+    - 其次 diffusion_pytorch_model.safetensors
+    - 否则 None（交给 diffusers 自动判断）
+    """
+    candidates = [
+        "ae.safetensors",
+        "diffusion_pytorch_model.safetensors",
+        "model.safetensors",
+    ]
+    for name in candidates:
+        if os.path.isfile(os.path.join(vae_dir, name)):
+            return name
+    return None
+
+
+def load_pipeline(
+    transformer_choice: str = "default",
+    text_encoder_choice: str = "default",
+    vae_choice: str = "default",
+):
+    """按选择（T / TE / VAE）组装或复用 Z-Image pipeline"""
+    global pipe, current_model_config
+
+    config_tuple = {
+        "transformer": transformer_choice,
+        "text_encoder": text_encoder_choice,
+        "vae": vae_choice,
+    }
+
+    # 如果配置没变，直接复用
+    if pipe is not None and config_tuple == current_model_config:
+        return pipe
+
+    pipe = None
+    try:
+        torch.cuda.empty_cache()
+    except Exception:
+        pass
+
+    use_default = (
+        transformer_choice == "default"
+        and text_encoder_choice == "default"
+        and vae_choice == "default"
+    )
+
+    if use_default:
+        print("🛠 正在加载默认 Z-Image-Turbo Pipeline（全官方组件）...")
+        pipe_local = ZImagePipeline.from_pretrained(
+            "Tongyi-MAI/Z-Image-Turbo",
+            torch_dtype=torch.bfloat16,
+            low_cpu_mem_usage=False,
+        )
+    else:
+        print(
+            f"🛠 正在加载自定义 Pipeline: "
+            f"T={transformer_choice}, TE={text_encoder_choice}, VAE={vae_choice}"
+        )
+        base_repo = "Tongyi-MAI/Z-Image-Turbo"
+
+        # ==== Transformer ====
+        transformer_dir = resolve_model_dir(transformer_choice, MOD_TRANSFORMER)
+        if transformer_dir is not None:
+            print(f"  - 自定义 Transformer: {transformer_dir}")
+            transformer = ZImageTransformer2DModel.from_pretrained(
+                transformer_dir,
+                torch_dtype=torch.bfloat16,
+            )
+        else:
+            transformer = None
+
+        # ==== Text Encoder ====
+        text_encoder_dir = resolve_model_dir(text_encoder_choice, MOD_TEXT_ENCODER)
+        if text_encoder_dir is not None:
+            print(f"  - 自定义 Text Encoder: {text_encoder_dir}")
+            text_encoder = AutoModelForCausalLM.from_pretrained(
+                text_encoder_dir,
+                torch_dtype=torch.bfloat16,
+            )
+        else:
+            text_encoder = None
+
+        # ==== VAE ====
+        vae_dir = resolve_model_dir(vae_choice, MOD_VAE)
+        if vae_dir is not None:
+            print(f"  - 自定义 VAE: {vae_dir}")
+            weight_name = pick_vae_weight_name(vae_dir)
+            if weight_name:
+                print(f"    - 使用权重文件: {weight_name}")
+                vae = AutoencoderKL.from_pretrained(
+                    vae_dir,
+                    torch_dtype=torch.bfloat16,
+                    use_safetensors=True,
+                    weight_name=weight_name,
+                )
+            else:
+                print("    - 未显式找到 safetensors，尝试默认加载")
+                vae = AutoencoderKL.from_pretrained(
+                    vae_dir,
+                    torch_dtype=torch.bfloat16,
+                )
+        else:
+            vae = None
+
+        pipe_local = ZImagePipeline.from_pretrained(
+            base_repo,
+            torch_dtype=torch.bfloat16,
+            low_cpu_mem_usage=False,
+            transformer=transformer,
+            text_encoder=text_encoder,
+            vae=vae,
+        )
+
+    pipe = pipe_local
+    current_model_config = config_tuple
+    print("✅ Pipeline 已加载:", current_model_config)
+    return pipe
+
+
+def normalize_format(fmt: str):
+    fmt = (fmt or "png").lower()
+    if fmt == "jpeg":
+        return "JPEG", "jpeg"
+    if fmt == "webp":
+        return "WEBP", "webp"
+    return "PNG", "png"
+
+
+# =========================
+# 核心生成函数
+# =========================
+
+def generate_image(
+    prompt,
+    selected_loras,
+    lora_alpha,
+    device,
+    num_images,
+    image_format,
+    width,
+    height,
+    num_inference_steps,
+    guidance_scale,
+    seed,
+    randomize_seed,
+    transformer_choice,
+    text_encoder_choice,
+    vae_choice,
+):
+    # 1. 加载 / 切换 pipeline
+    pipe_local = load_pipeline(
+        transformer_choice=transformer_choice,
+        text_encoder_choice=text_encoder_choice,
+        vae_choice=vae_choice,
+    )
+
+    if pipe_local is None:
+        raise gr.Error("Pipeline 加载失败，请查看控制台日志。")
+
+    # 2. 设备
+    if device == "cuda" and not torch.cuda.is_available():
+        print("⚠ 选择了 cuda 但当前环境没有可用 GPU，自动切换到 cpu。")
+        device = "cpu"
+    pipe_local.to(device)
+
+    # 3. 注入 LoRA
+    pipe_local = apply_lora_to_pipeline(
+        pipe_local,
+        selected_loras,
+        lora_alpha,
+    )
+
+    # 4. 种子
+    if randomize_seed:
+        seed = random.randint(0, 2**32 - 1)
+    seed = int(seed)
+    generator_device = "cuda" if device == "cuda" else "cpu"
+    generator = torch.Generator(generator_device).manual_seed(seed)
+
+    # 5. 输出目录
+    date_str = datetime.now().strftime("%Y-%m-%d")
+    day_dir = os.path.join(OUTPUT_DIR, date_str)
+    os.makedirs(day_dir, exist_ok=True)
+
+    pil_format, ext = normalize_format(image_format)
+    effective_prompt = (prompt or "").strip()
+
+    print(
+        f"🚀 生成中: {width}x{height}, steps={num_inference_steps}, "
+        f"guidance={guidance_scale}, seed={seed}, device={device}"
+    )
+
+    filepaths = []
+    try:
+        for _ in range(int(num_images)):
+            result = pipe_local(
+                prompt=effective_prompt,
+                height=height,
+                width=width,
+                num_inference_steps=num_inference_steps,
+                guidance_scale=guidance_scale,
+                generator=generator,
+            )
+            image = result.images[0]
+
+            timestamp = datetime.now().strftime("%H%M%S")
+            unique = str(uuid.uuid4())[:8]
+            filename = os.path.join(day_dir, f"image_{timestamp}_{unique}.{ext}")
+            image.save(filename, format=pil_format)
+            filepaths.append(filename)
+
+        return filepaths, seed
+    except Exception as e:
+        print(f"💥 生成出错: {e}")
+        raise gr.Error(f"生成出错: {e}")
+
+
+# =========================
+# 预扫描 / 默认值
+# =========================
+
+default_device = "cuda" if torch.cuda.is_available() else "cpu"
+initial_lora_items = scan_lora_items()
+
+transformer_choices = get_choices(MOD_TRANSFORMER, "Transformer")
+text_encoder_choices = get_choices(MOD_TEXT_ENCODER, "TextEncoder")
+vae_choices = get_choices(MOD_VAE, "VAE")
+
+
+# =========================
+# Gradio 界面
+# =========================
+
+with gr.Blocks(title="Z-Image-Turbo Pro") as demo:
+    gr.Markdown(
+        """
+        # 🎨 Z-Image-Turbo Pro（MOD 专业版 LeeWheel）
+
+        - 官方底模：HF cache 中的 `Tongyi-MAI/Z-Image-Turbo`
+        - 自定义模型：
+          - `MOD/transformer/<Name>/` → Transformer
+          - `MOD/text_encoder/<Name>/` → Text Encoder
+          - `MOD/vae/<Name>/` → VAE（支持 AE：`config.json + ae.safetensors`）
+        - LoRA：`lora/*.safetensors`
+        """
+    )
+
+    with gr.Row():
+        with gr.Column(scale=1):
+            prompt = gr.Textbox(
+                label="Prompt / 提示词",
+                placeholder="描述你想生成的图像...",
+                lines=3,
+            )
+
+            # LoRA 区域
+            gr.Markdown("### LoRA 设置（C 站 Z-Image LoRA 放在 ./lora）")
+            with gr.Row():
+                refresh_lora_btn = gr.Button("🔄 刷新 LoRA 列表", size="sm")
+            lora_multiselect = gr.CheckboxGroup(
+                label="选择 LoRA（可多选）",
+                choices=initial_lora_items,
+                value=[],
+            )
+            lora_alpha = gr.Slider(
+                label="LoRA 全局强度 alpha",
+                minimum=0.0,
+                maximum=2.0,
+                step=0.05,
+                value=1.0,
+            )
+
+            # 模型选择
+            gr.Markdown("### 底模组件选择（官方 + MOD）")
+
+            transformer_choice = gr.Dropdown(
+                label="Transformer（底模）",
+                choices=transformer_choices,
+                value="default",
+            )
+            text_encoder_choice = gr.Dropdown(
+                label="Text Encoder（文本编码器）",
+                choices=text_encoder_choices,
+                value="default",
+            )
+            vae_choice = gr.Dropdown(
+                label="VAE（图像解码器）",
+                choices=vae_choices,
+                value="default",
+            )
+
+            # 设备与参数
+            device = gr.Radio(
+                label="推理设备 / Device",
+                choices=["cuda", "cpu"],
+                value=default_device,
+            )
+
+            num_images = gr.Slider(
+                label="生成张数 / Number of Images",
+                minimum=1,
+                maximum=8,
+                step=1,
+                value=1,
+            )
+
+            image_format = gr.Dropdown(
+                label="输出格式 / Output Format",
+                choices=["png", "jpeg", "webp"],
+                value="png",
+            )
+
+            gr.Markdown("**分辨率预设 / Resolution Presets**")
+            with gr.Row():
+                preset_512 = gr.Button("512×512", size="sm")
+                preset_768 = gr.Button("768×768", size="sm")
+                preset_1024 = gr.Button("1024×1024", size="sm")
+                preset_landscape = gr.Button("1024×768", size="sm")
+                preset_portrait = gr.Button("768×1024", size="sm")
+
+            with gr.Row():
+                width = gr.Slider(
+                    label="宽度 Width",
+                    minimum=512,
+                    maximum=2048,
+                    step=64,
+                    value=1024,
+                )
+                height = gr.Slider(
+                    label="高度 Height",
+                    minimum=512,
+                    maximum=2048,
+                    step=64,
+                    value=1024,
+                )
+
+            with gr.Row():
+                num_inference_steps = gr.Slider(
+                    label="采样步数 / Inference Steps",
+                    minimum=1,
+                    maximum=50,
+                    step=1,
+                    value=10,
+                )
+                guidance_scale = gr.Slider(
+                    label="Guidance Scale (CFG)",
+                    minimum=0.0,
+                    maximum=10.0,
+                    step=0.1,
+                    value=0.0,
+                )
+
+            with gr.Row():
+                seed = gr.Number(
+                    label="Seed",
+                    value=42,
+                    precision=0,
+                )
+                randomize_seed = gr.Checkbox(
+                    label="Randomize Seed / 随机种子",
+                    value=True,
+                )
+
+            generate_btn = gr.Button("🚀 生成 / Generate", variant="primary", size="lg")
+
+        with gr.Column(scale=1):
+            output_gallery = gr.Gallery(
+                label="Generated Images",
+                show_label=True,
+                columns=2,
+                rows=2,
+                type="filepath",
+            )
+            used_seed = gr.Number(label="Seed Used", interactive=False)
+
+    # LoRA & prompt 绑定
+    refresh_lora_btn.click(
+        fn=lambda: gr.update(choices=scan_lora_items(), value=[]),
+        inputs=[],
+        outputs=lora_multiselect,
+    )
+
+    lora_multiselect.change(
+        fn=update_prompt_with_lora,
+        inputs=[prompt, lora_multiselect, lora_alpha],
+        outputs=prompt,
+    )
+    lora_alpha.change(
+        fn=update_prompt_with_lora,
+        inputs=[prompt, lora_multiselect, lora_alpha],
+        outputs=prompt,
+    )
+
+    # 分辨率预设
+    preset_512.click(fn=lambda: (512, 512), outputs=[width, height])
+    preset_768.click(fn=lambda: (768, 768), outputs=[width, height])
+    preset_1024.click(fn=lambda: (1024, 1024), outputs=[width, height])
+    preset_landscape.click(fn=lambda: (1024, 768), outputs=[width, height])
+    preset_portrait.click(fn=lambda: (768, 1024), outputs=[width, height])
+
+    # 生成按钮
+    generate_btn.click(
+        fn=generate_image,
+        inputs=[
+            prompt,
+            lora_multiselect,
+            lora_alpha,
+            device,
+            num_images,
+            image_format,
+            width,
+            height,
+            num_inference_steps,
+            guidance_scale,
+            seed,
+            randomize_seed,
+            transformer_choice,
+            text_encoder_choice,
+            vae_choice,
+        ],
+        outputs=[output_gallery, used_seed],
+    )
+
+if __name__ == "__main__":
+    demo.queue()
+    demo.launch(
+        server_name="127.0.0.1",
+        server_port=7860,
+        inbrowser=False,
+        show_error=True,
+    )

app.py

@@ -0,0 +1,1092 @@
+import os
+import sys
+import gc
+import uuid
+import random
+import re
+import datetime
+import json
+import tempfile
+import locale
+
+# =========================
+# 语言检测
+# =========================
+try:
+    system_lang = locale.getdefaultlocale()[0]
+    is_chinese = system_lang and system_lang.startswith('zh')
+except:
+    is_chinese = False
+
+def get_message(key, *args):
+    messages = {
+        "peft_loaded": ("✅ PEFT 库已加载，LoRA 功能可用。", "✅ PEFT library loaded, LoRA functionality available."),
+        "peft_not_detected": ("⚠️ 警告: 未检测到 PEFT 库。LoRA 功能将禁用。", "⚠️ Warning: PEFT library not detected. LoRA functionality will be disabled."),
+        "lora_skipped": ("⚠️ [LoRA] 已跳过加载：PEFT 库未安装。", "⚠️ [LoRA] Skipped loading: PEFT library not installed."),
+        "transformer_not_loaded": ("⚠️ Transformer 未加载，无法应用 LoRA", "⚠️ Transformer not loaded, cannot apply LoRA"),
+        "lora_file_not_exist": ("⚠️ LoRA 文件不存在: {}", "⚠️ LoRA file does not exist: {}"),
+        "lora_loading": ("  [LoRA] 正在加载: {} (权重: {} * {} = {:.2f})", "  [LoRA] Loading: {} (weight: {} * {} = {:.2f})"),
+        "lora_loaded": ("✅ LoRA 加载成功: {}", "✅ LoRA loaded successfully: {}"),
+        "lora_failed": ("❌ LoRA 加载严重失败: {}", "❌ LoRA loading failed critically: {}"),
+        "applying_vae": ("正在应用自定义 VAE: {}", "Applying custom VAE: {}"),
+        "vae_loaded": ("✅ 自定义 VAE 加载成功", "✅ Custom VAE loaded successfully"),
+        "vae_failed": ("⚠️ 自定义 VAE 加载失败: {}", "⚠️ Custom VAE loading failed: {}"),
+        "forcing_to_ram": ("  [System] 正在强制将模型搬运至 RAM (请稍候)...", "  [System] Forcing model to RAM (please wait)..."),
+        "model_to_ram": ("  [System] 模型已加载至 RAM。", "  [System] Model loaded to RAM."),
+        "t2i_low_vram": ("  [T2I] 已启用低显存优化模式", "  [T2I] Low VRAM optimization mode enabled"),
+        "t2i_high_end": ("  [T2I] 已启用高端机模式", "  [T2I] High-end GPU mode enabled"),
+        "t2i_pipeline_loaded": ("✅ 文生图 Pipeline 加载完成", "✅ Text-to-Image Pipeline loaded"),
+        "i2i_pipeline_failed": ("加载图生图 Pipeline 失败：{}", "Failed to load Image-to-Image Pipeline: {}"),
+        "i2i_pipeline_loaded": ("✅ 图生图 Pipeline 加载完成", "✅ Image-to-Image Pipeline loaded"),
+        "i2i_low_vram": ("  [I2I] 已启用低显存优化模式", "  [I2I] Low VRAM optimization mode enabled"),
+        "i2i_high_end": ("  [I2I] 已启用高端机模式", "  [I2I] High-end GPU mode enabled"),
+        "generation_stopped": ("🛑 生成已被用户手动停止", "🛑 Generation stopped by user"),
+        "upload_image_first": ("⚠️ 请先上传图片！", "⚠️ Please upload an image first!"),
+        "i2i_model_failed": ("加载图生图模型失败: {}", "Failed to load Image-to-Image model: {}"),
+        "native_inpaint_failed": ("⚠️ 原生 Inpaint 失败 ({})，使用手动混合模式...", "⚠️ Native Inpaint failed ({}), using manual blending mode..."),
+        "paint_area": ("⚠️ 请使用画笔在图片上涂抹要修改的区域。", "⚠️ Please use the brush to paint the area to modify on the image."),
+        "mask_invalid": ("⚠️ Mask 无效，请确保涂抹了区域。", "⚠️ Mask invalid, please ensure an area is painted."),
+        "model_load_failed": ("模型加载失败: {}", "Model loading failed: {}"),
+        "inpainting_failed": ("局部重绘失败: {}", "Inpainting failed: {}"),
+        "generating": ("生成中", "Generating"),
+        "img2img_processing": ("图生图中", "Img2Img processing"),
+    }
+    zh, en = messages[key]
+    return (zh if is_chinese else en).format(*args)
+
+# 环境配置
+os.environ.pop("PYTHONHOME", None)
+os.environ.pop("PYTHONPATH", None)
+os.environ["DIFFUSERS_USE_PEFT_BACKEND"] = "true"
+os.environ["PEFT_DEBUG"] = "false"
+
+import torch
+import numpy as np
+from PIL import Image, ImageFilter, ImageOps, ImageEnhance, ImageDraw
+
+import gradio as gr
+from diffusers import (
+    ZImagePipeline, 
+    ZImageImg2ImgPipeline,
+    AutoencoderKL, 
+    ZImageTransformer2DModel,
+    FlowMatchEulerDiscreteScheduler
+)
+from transformers import AutoModelForCausalLM, AutoTokenizer
+from safetensors.torch import load_file
+
+# =========================
+# 检测 PEFT 环境
+# =========================
+PEFT_AVAILABLE = False
+try:
+    import peft
+    from diffusers.utils import is_peft_available
+    if is_peft_available():
+        PEFT_AVAILABLE = True
+        print(get_message("peft_loaded"))
+    else:
+        raise ImportError
+except ImportError:
+    print(get_message("peft_not_detected"))
+
+# =========================
+# 双语文本字典
+# =========================
+TEXT = {
+    "zh": {
+        "title": "# 🎨 Z-Image-Turbo Low Vram Edition",
+        "lang_btn": "EN",
+        "tab_generate": "图像生成", "tab_edit": "图片编辑", "tab_img2img": "图生图 (增强版)", "tab_inpaint": "局部重绘",
+        "prompt": "Prompt", "prompt_placeholder": "输入你的描述...", "negative_prompt": "负面提示词", "negative_placeholder": "low quality, blurry, bad anatomy",
+        "refresh_lora": "🔄 刷新 LoRA", "refresh_model": "🔄 刷新模型", "lora_label": "LoRA", "lora_strength": "LoRA 强度", "lora_weight": "权重",
+        "model_section": "### 模型选择/Model Selection", "transformer": "Transformer", "vae": "VAE", "vram_type": "显存类型",
+        "vram_low": "24GB以下 (优化模式)", "vram_high": "高端机模式 (>=24GB)", "device": "设备", "num_images": "生成张数",
+        "output_format": "输出格式", "width": "宽度", "height": "高度", "steps": "步数", "cfg": "CFG", "seed": "种子", "random_seed": "随机种子",
+        "generate": "🚀 生成", "stop": "🛑 停止生成", "gallery": "生成结果", "used_seed": "使用种子",
+        "edit_upload": "上传图片", "rotate": "旋转角度 (度)", "crop_x": "裁剪 X (%)", "crop_y": "裁剪 Y (%)", "crop_w": "裁剪宽度 (%)", "crop_h": "裁剪高度 (%)",
+        "hflip": "水平翻转", "vflip": "垂直翻转", "edit_btn": "开始编辑", "edited_image": "编辑后的图片",
+        "filter": "应用滤镜", "brightness": "亮度调整 (%)", "contrast": "对比度调整 (%)", "saturation": "饱和度调整 (%)",
+        "i2i_ref": "上传参考图", "i2i_prompt": "修改提示词", "i2i_ph": "描述你希望图中发生的变化...", "i2i_mode": "Img2Img 模式",
+        "i2i_mode_a": "A. 严格保结构（微调风格）", "i2i_mode_b": "B. 强烈听 prompt（允许大改）", "i2i_out_w": "输出宽 (0=自动)", "i2i_out_h": "输出高 (0=自动)",
+        "i2i_tip": "**提示：** 宽高都为0时自动保持上传图比例并接近1024。", "i2i_strength": "重绘强度", "i2i_btn": "🎨 开始修改", "i2i_note": "注：使用官方 Z-Image Img2Img 引擎。",
+        "inpaint_editor": "绘制 Mask (白色为修改区，黑色为保留区)", "inpaint_tip": "提示：先上传图片，然后用画笔涂抹要修改的区域。", "inpaint_upload": "上传原图并绘制", "inpaint_desc": "📖 使用指南：涂抹区域（白色/彩色）将被重新生成，未涂抹区域保持原样。",
+    },
+    "en": {
+        "title": "# 🎨 Z-Image-Turbo Low Vram Edition", "lang_btn": "中文",
+        "tab_generate": "Image Generation", "tab_edit": "Image Editing", "tab_img2img": "Img2Img (Enhanced)", "tab_inpaint": "Inpainting",
+        "prompt": "Prompt", "prompt_placeholder": "Enter your description...", "negative_prompt": "Negative Prompt", "negative_placeholder": "low quality, blurry",
+        "refresh_lora": "🔄 Refresh LoRA", "refresh_model": "🔄 Refresh Models", "lora_label": "LoRA", "lora_strength": "LoRA Strength", "lora_weight": "Weight",
+        "model_section": "### Model Selection", "transformer": "Transformer", "vae": "VAE", "vram_type": "VRAM Type",
+        "vram_low": "Under 24GB (Optimized)", "vram_high": "High-End GPU Mode (>=24GB)", "device": "Device", "num_images": "Number of Images",
+        "output_format": "Output Format", "width": "Width", "height": "Height", "steps": "Steps", "cfg": "CFG", "seed": "Seed", "random_seed": "Random Seed",
+        "generate": "🚀 Generate", "stop": "🛑 Stop Generation", "gallery": "Generated Images", "used_seed": "Used Seed",
+        "edit_upload": "Upload Image", "rotate": "Rotation (degrees)", "crop_x": "Crop X (%)", "crop_y": "Crop Y (%)", "crop_w": "Crop Width (%)", "crop_h": "Crop Height (%)",
+        "hflip": "Horizontal Flip", "vflip": "Vertical Flip", "edit_btn": "Apply Edit", "edited_image": "Edited Image",
+        "filter": "Apply Filter", "brightness": "Brightness (%)", "contrast": "Contrast (%)", "saturation": "Saturation (%)",
+        "i2i_ref": "Upload Reference", "i2i_prompt": "Modification Prompt", "i2i_ph": "Describe changes...", "i2i_mode": "Img2Img Mode",
+        "i2i_mode_a": "A. Strict Structure (Style tweak)", "i2i_mode_b": "B. Strong Prompt (Allow changes)", "i2i_out_w": "Output Width (0=Auto)", "i2i_out_h": "Output Height (0=Auto)",
+        "i2i_tip": "**Tip:** Auto ratio if both 0.", "i2i_strength": "Denoising Strength", "i2i_btn": "🎨 Start Modification", "i2i_note": "Using official Z-Image Img2Img engine.",
+        "inpaint_editor": "Draw Mask (White=Modify, Black=Keep)", "inpaint_tip": "Tip: Upload image, then paint area to modify.", "inpaint_upload": "Upload & Paint", "inpaint_desc": "📖 Guide: Painted areas (white/color) will be regenerated. Unpainted areas stay original.",
+    }
+}
+
+# =========================
+# 路径配置
+# =========================
+BASE_DIR = os.path.dirname(os.path.abspath(__file__))
+BASE_SNAPSHOT_DIR = os.path.join(BASE_DIR, "cache", "HF_HOME", "hub", "models--Tongyi-MAI--Z-Image-Turbo", "snapshots", "5f4b9cbb80cc95ba44fe6667dfd75710f7db2947")
+if not os.path.exists(BASE_SNAPSHOT_DIR):
+    BASE_SNAPSHOT_DIR = os.path.join(BASE_DIR, "ckpts", "Z-Image-Turbo")
+    if not os.path.exists(BASE_SNAPSHOT_DIR):
+        BASE_SNAPSHOT_DIR = "." 
+
+TRANSFORMER_ROOT = os.path.join(BASE_SNAPSHOT_DIR, "transformer")
+TEXT_ENCODER_ROOT = os.path.join(BASE_SNAPSHOT_DIR, "text_encoder")
+VAE_ROOT = os.path.join(BASE_SNAPSHOT_DIR, "vae")
+
+MOD_DIR = os.path.join(BASE_DIR, "MOD")
+MOD_TRANSFORMER = os.path.join(MOD_DIR, "transformer")
+MOD_VAE = os.path.join(MOD_DIR, "vae")
+LORA_ROOT = os.path.join(BASE_DIR, "lora")
+OUTPUT_DIR = os.path.join(BASE_DIR, "outputs")
+
+for p in [MOD_TRANSFORMER, MOD_VAE, LORA_ROOT, OUTPUT_DIR]:
+    os.makedirs(p, exist_ok=True)
+
+pipe_t2i = None
+pipe_i2i = None
+current_model_config = {"transformer": "default", "vae": "default", "is_low_vram": True}
+is_generating_interrupted = False
+
+DEVICE = "cuda" if torch.cuda.is_available() else "cpu"
+DTYPE = torch.bfloat16 if DEVICE == "cuda" else torch.float32
+
+def auto_flush_vram():
+    gc.collect()
+    if DEVICE == "cuda":
+        torch.cuda.empty_cache()
+
+# =========================
+# 核心优化：LoRA 加载逻辑
+# =========================
+def apply_lora_to_pipeline(pipe_local, lora_choice, lora_alpha, lora_scale=1.0):
+    if not PEFT_AVAILABLE:
+        print(get_message("lora_skipped"))
+        return pipe_local
+
+    if pipe_local is None:
+        return pipe_local
+    if pipe_local.transformer is None:
+        print(get_message("transformer_not_loaded"))
+        return pipe_local
+
+    if hasattr(pipe_local, "unload_lora_weights"):
+        try:
+            pipe_local.unload_lora_weights()
+        except Exception:
+            pass
+
+    if not lora_choice or lora_choice.lower() == "none":
+        return pipe_local
+
+    lora_path = os.path.join(LORA_ROOT, lora_choice)
+    if not os.path.exists(lora_path):
+        print(get_message("lora_file_not_exist", lora_path))
+        return pipe_local
+
+    try:
+        raw_alpha = float(lora_alpha)
+        effective_alpha = raw_alpha * lora_scale
+
+        if effective_alpha <= 0:
+            return pipe_local
+
+        adapter_name = re.sub(r"[^a-zA-Z0-9_]", "_", os.path.splitext(lora_choice)[0])
+
+        print(get_message("lora_loading", lora_choice, raw_alpha, lora_scale, effective_alpha))
+        pipe_local.load_lora_weights(
+            LORA_ROOT,
+            weight_name=lora_choice,
+            adapter_name=adapter_name
+        )
+        pipe_local.set_adapters([adapter_name], adapter_weights=[effective_alpha])
+        print(get_message("lora_loaded", adapter_name))
+
+    except Exception as e:
+        import traceback
+        print(get_message("lora_failed", e))
+
+    return pipe_local
+
+def scan_lora_items():
+    if not os.path.isdir(LORA_ROOT):
+        return []
+    return sorted([f for f in os.listdir(LORA_ROOT) if f.lower().endswith((".safetensors", ".pt", ".pth"))])
+
+def update_prompt_with_lora(prompt, lora_choice, lora_alpha):
+    prompt = (prompt or "").strip()
+    prompt_clean = re.sub(r"<lora:[^>]+>", "", prompt).strip()
+    if lora_choice and lora_choice.lower() != "none":
+        try:
+            alpha = float(lora_alpha)
+        except: alpha = 1.0
+        if alpha > 0:
+            name = os.path.splitext(lora_choice)[0]
+            alpha_str = f"{alpha:.2f}".rstrip("0").rstrip(".")
+            return f"{prompt_clean} <lora:{name}:{alpha_str}>"
+    return prompt_clean
+
+# =========================
+# 模型加载逻辑
+# =========================
+def load_t2i_pipeline(transformer_choice, vae_choice, is_low_vram):
+    global pipe_t2i, current_model_config
+    config_key = ("t2i", transformer_choice, vae_choice, is_low_vram)
+    if pipe_t2i is not None and current_model_config.get("t2i") == config_key:
+        return pipe_t2i
+
+    auto_flush_vram()
+    pipe_t2i = None
+    
+    transformer = ZImageTransformer2DModel.from_pretrained(TRANSFORMER_ROOT, torch_dtype=DTYPE, local_files_only=True)
+    if transformer_choice != "default":
+        t_path = resolve_model_path(transformer_choice, MOD_TRANSFORMER)
+        if t_path:
+            if os.path.isdir(t_path):
+                custom_t = ZImageTransformer2DModel.from_pretrained(t_path, torch_dtype=DTYPE, local_files_only=True)
+                transformer = custom_t
+            else:
+                state = load_file(t_path, device="cpu")
+                processed = {}
+                prefix = "model.diffusion_model."
+                for k, v in state.items():
+                    new_k = k[len(prefix):] if k.startswith(prefix) else k
+                    processed[new_k] = v.to(DTYPE)
+                transformer.load_state_dict(processed, strict=False)
+                del state, processed
+
+    text_encoder = AutoModelForCausalLM.from_pretrained(TEXT_ENCODER_ROOT, torch_dtype=DTYPE, local_files_only=True)
+    
+    pipe_t2i = ZImagePipeline.from_pretrained(
+        BASE_SNAPSHOT_DIR,
+        local_files_only=True,
+        transformer=transformer,
+        text_encoder=text_encoder,
+    )
+    pipe_t2i.to(dtype=DTYPE)
+
+    if vae_choice != "default":
+        v_path = resolve_model_path(vae_choice, MOD_VAE)
+        if v_path:
+            print(get_message("applying_vae", vae_choice))
+            vae_device_map = {"": "cpu"} if is_low_vram else None
+            try:
+                if os.path.isfile(v_path):
+                    with tempfile.TemporaryDirectory() as tmpdir:
+                        config_file_path = os.path.join(tmpdir, "config.json")
+                        vae_config_dict = dict(pipe_t2i.vae.config)
+                        with open(config_file_path, "w", encoding="utf-8") as f:
+                            json.dump(vae_config_dict, f, indent=2)
+                        try:
+                            pipe_t2i.vae = AutoencoderKL.from_single_file(v_path, dtype=DTYPE, config=tmpdir, device_map=vae_device_map)
+                        except TypeError:
+                            pipe_t2i.vae = AutoencoderKL.from_single_file(v_path, torch_dtype=DTYPE, config=tmpdir, device_map=vae_device_map)
+                        print(get_message("vae_loaded"))
+                else:
+                    pipe_t2i.vae = AutoencoderKL.from_pretrained(v_path, torch_dtype=DTYPE, device_map=vae_device_map)
+            except Exception as e:
+                print(get_message("vae_failed", e))
+
+    if DEVICE == "cuda":
+        if is_low_vram:
+            print(get_message("forcing_to_ram"))
+            pipe_t2i.to("cpu")
+            print(get_message("model_to_ram"))
+            pipe_t2i.enable_sequential_cpu_offload()
+            print(get_message("t2i_low_vram"))
+        else:
+            pipe_t2i.to("cuda")
+            print(get_message("t2i_high_end"))
+
+    current_model_config["t2i"] = config_key
+    print("✅ 文生图 Pipeline 加载完成")
+    return pipe_t2i
+
+def load_i2i_pipeline(transformer_choice, vae_choice, is_low_vram):
+    global pipe_i2i, current_model_config
+    config_key = ("i2i", transformer_choice, vae_choice, is_low_vram)
+    if pipe_i2i is not None and current_model_config.get("i2i") == config_key:
+        return pipe_i2i
+
+    auto_flush_vram()
+    pipe_i2i = None
+    
+    transformer = ZImageTransformer2DModel.from_pretrained(TRANSFORMER_ROOT, torch_dtype=DTYPE, local_files_only=True)
+    if transformer_choice != "default":
+        t_path = resolve_model_path(transformer_choice, MOD_TRANSFORMER)
+        if t_path:
+            if os.path.isdir(t_path):
+                custom_t = ZImageTransformer2DModel.from_pretrained(t_path, torch_dtype=DTYPE, local_files_only=True)
+                transformer = custom_t
+            else:
+                state = load_file(t_path, device="cpu")
+                processed = {}
+                prefix = "model.diffusion_model."
+                for k, v in state.items():
+                    new_k = k[len(prefix):] if k.startswith(prefix) else k
+                    processed[new_k] = v.to(DTYPE)
+                transformer.load_state_dict(processed, strict=False)
+                del state, processed
+
+    try:
+        pipe_i2i = ZImageImg2ImgPipeline.from_pretrained(
+            BASE_SNAPSHOT_DIR,
+            local_files_only=True,
+            transformer=transformer,
+        )
+    except Exception as e:
+        raise gr.Error(f"加载图生图 Pipeline 失败：{str(e)}")
+        
+    pipe_i2i.to(dtype=DTYPE)
+
+    if vae_choice != "default":
+        v_path = resolve_model_path(vae_choice, MOD_VAE)
+        if v_path:
+            print(get_message("applying_vae", vae_choice))
+            vae_device_map = {"": "cpu"} if is_low_vram else None
+            try:
+                if os.path.isfile(v_path):
+                    with tempfile.TemporaryDirectory() as tmpdir:
+                        config_file_path = os.path.join(tmpdir, "config.json")
+                        vae_config_dict = dict(pipe_i2i.vae.config)
+                        with open(config_file_path, "w", encoding="utf-8") as f:
+                            json.dump(vae_config_dict, f, indent=2)
+                        try:
+                            pipe_i2i.vae = AutoencoderKL.from_single_file(v_path, dtype=DTYPE, config=tmpdir, device_map=vae_device_map)
+                        except TypeError:
+                            pipe_i2i.vae = AutoencoderKL.from_single_file(v_path, torch_dtype=DTYPE, config=tmpdir, device_map=vae_device_map)
+                        print(get_message("vae_loaded"))
+                else:
+                    pipe_i2i.vae = AutoencoderKL.from_pretrained(v_path, torch_dtype=DTYPE, device_map=vae_device_map)
+            except Exception as e:
+                print(get_message("vae_failed", e))
+
+    if DEVICE == "cuda":
+        if is_low_vram:
+            print(get_message("forcing_to_ram"))
+            pipe_i2i.to("cpu")
+            print(get_message("model_to_ram"))
+            pipe_i2i.enable_sequential_cpu_offload()
+            print(get_message("i2i_low_vram"))
+        else:
+            pipe_i2i.to("cuda")
+            print(get_message("i2i_high_end"))
+
+    current_model_config["i2i"] = config_key
+    print("✅ 图生图 Pipeline 加载完成")
+    return pipe_i2i
+
+def interrupt_callback(pipe, step, timestep, callback_kwargs):
+    global is_generating_interrupted
+    if is_generating_interrupted:
+        raise gr.Error("🛑 生成已被用户手动停止")
+    return callback_kwargs
+
+def scan_model_variants(root_dir):
+    if not os.path.isdir(root_dir):
+        return []
+    items = []
+    for name in os.listdir(root_dir):
+        path = os.path.join(root_dir, name)
+        if os.path.isdir(path):
+            if os.path.isfile(os.path.join(path, "config.json")):
+                items.append(name)
+        elif name.lower().endswith((".safetensors", ".bin")):
+            items.append(name)
+    return sorted(items)
+
+def get_choices(mod_root):
+    return ["default"] + scan_model_variants(mod_root)
+
+def resolve_model_path(choice, mod_root):
+    if choice == "default":
+        return None
+    path = os.path.join(mod_root, choice)
+    if os.path.exists(path):
+        return path
+    return None
+
+def process_mask_for_inpaint(mask_image):
+    if mask_image is None:
+        return None
+    if mask_image.mode == 'RGBA':
+        import numpy as np
+        mask_array = np.array(mask_image)
+        alpha = mask_array[:, :, 3] if mask_array.shape[2] > 3 else None
+        rgb = mask_array[:, :, :3]
+        rgb_gray = np.dot(rgb, [0.299, 0.587, 0.114])
+        if alpha is not None:
+            mask_gray = np.where(alpha > 10, 255, 0).astype(np.uint8)
+        else:
+            mask_gray = np.where(rgb_gray > 10, 255, 0).astype(np.uint8)
+        mask = Image.fromarray(mask_gray, mode='L')
+    else:
+        if mask_image.mode != 'L':
+            mask_image = mask_image.convert('L')
+        mask = mask_image.point(lambda p: 255 if p > 10 else 0)
+    
+    if mask.getextrema()[1] == 0: 
+        return None
+    return mask
+
+# =========================
+# 生成与编辑函数
+# =========================
+
+def generate_image(prompt, lora_choice, lora_alpha, num_images, image_format,
+                   width, height, num_inference_steps, guidance_scale, seed, randomize_seed,
+                   transformer_choice, vae_choice, vram_type_str, progress=gr.Progress()):
+    global is_generating_interrupted
+    is_generating_interrupted = False
+    
+    is_low_vram = "24GB" in vram_type_str or "Under 24GB" in vram_type_str or "24G以下" in vram_type_str or "24GB以下" in vram_type_str
+    
+    pipe_local = load_t2i_pipeline(transformer_choice, vae_choice, is_low_vram)
+    pipe_local = apply_lora_to_pipeline(pipe_local, lora_choice, lora_alpha)
+
+    if randomize_seed:
+        seed = random.randint(0, 2**32 - 1)
+    generator = torch.Generator(DEVICE).manual_seed(int(seed))
+
+    date_str = datetime.datetime.now().strftime("%Y-%m-%d")
+    day_dir = os.path.join(OUTPUT_DIR, date_str)
+    os.makedirs(day_dir, exist_ok=True)
+
+    fmt_map = {"png": ("PNG", "png"), "jpeg": ("JPEG", "jpeg"), "webp": ("WEBP", "webp")}
+    pil_fmt, ext = fmt_map[image_format.lower()]
+
+    results = []
+    try:
+        for _ in progress.tqdm(range(int(num_images)), desc="生成中"):
+            if is_generating_interrupted:
+                break
+            img = pipe_local(
+                prompt=prompt.strip(),
+                width=width,
+                height=height,
+                num_inference_steps=num_inference_steps,
+                guidance_scale=guidance_scale,
+                generator=generator,
+                callback_on_step_end=interrupt_callback,
+            ).images[0]
+            filename = os.path.join(day_dir, f"{datetime.datetime.now():%H%M%S}_{uuid.uuid4().hex[:4]}.{ext}")
+            img.save(filename, format=pil_fmt)
+            results.append(filename)
+    finally:
+        auto_flush_vram()
+
+    return results, seed
+
+def run_img2img_enhanced(input_image, prompt, negative_prompt, lora_choice, lora_alpha, 
+                         num_images, image_format,
+                         out_w, out_h, i2i_mode, strength_ui, steps_ui, cfg_ui, 
+                         seed, randomize_seed,
+                         transformer_choice, vae_choice, vram_type_str, progress=gr.Progress()):
+    global is_generating_interrupted
+    is_generating_interrupted = False
+
+    is_low_vram = "24GB" in vram_type_str or "Under 24GB" in vram_type_str or "24G以下" in vram_type_str or "24GB以下" in vram_type_str
+
+    if input_image is None:
+        raise gr.Error("⚠️ 请先上传图片！")
+
+    try:
+        pipe_local = load_i2i_pipeline(transformer_choice, vae_choice, is_low_vram)
+    except Exception as e:
+        if isinstance(e, gr.Error): raise e
+        raise gr.Error(f"加载图生图模型失败: {str(e)}")
+
+    if i2i_mode.startswith("A"):
+        lora_scale = 0.35 
+        strength = 0.30
+        steps = 8
+        cfg = 1.0
+    else:
+        lora_scale = 0.65 
+        strength = 0.45
+        steps = 6
+        cfg = 1.5
+    
+    pipe_local = apply_lora_to_pipeline(pipe_local, lora_choice, lora_alpha, lora_scale)
+
+    final_strength = strength_ui
+    final_steps = int(steps_ui)
+    final_cfg = cfg_ui
+    
+    if randomize_seed:
+        seed = random.randint(0, 2**32 - 1)
+    generator = torch.Generator(DEVICE).manual_seed(int(seed))
+
+    orig_w, orig_h = input_image.size
+    if out_w == 0 or out_h == 0:
+        target_size = 1024
+        ratio = orig_w / orig_h
+        if ratio > 1:
+            w, h = target_size, int(target_size / ratio)
+        else:
+            w, h = int(target_size * ratio), target_size
+    else:
+        w, h = out_w, out_h
+    
+    w = (w // 16) * 16
+    h = (h // 16) * 16
+    input_image = input_image.resize((w, h), Image.LANCZOS)
+
+    date_str = datetime.datetime.now().strftime("%Y-%m-%d")
+    day_dir = os.path.join(OUTPUT_DIR, date_str)
+    os.makedirs(day_dir, exist_ok=True)
+
+    fmt_map = {"png": ("PNG", "png"), "jpeg": ("JPEG", "jpeg"), "webp": ("WEBP", "webp")}
+    pil_fmt, ext = fmt_map[image_format.lower()]
+
+    results = []
+    
+    try:
+        for _ in progress.tqdm(range(int(num_images)), desc="图生图中"):
+            if is_generating_interrupted:
+                break
+            
+            img = pipe_local(
+                prompt=prompt.strip(),
+                negative_prompt=negative_prompt.strip(),
+                image=input_image,
+                strength=final_strength,
+                num_inference_steps=final_steps,
+                guidance_scale=final_cfg,
+                generator=generator,
+                callback_on_step_end=interrupt_callback,
+            ).images[0]
+            
+            filename = os.path.join(day_dir, f"i2i_{datetime.datetime.now():%H%M%S}_{uuid.uuid4().hex[:4]}.{ext}")
+            img.save(filename, format=pil_fmt)
+            results.append(filename)
+    finally:
+        auto_flush_vram()
+
+    return results, seed
+
+def run_inpainting(image_editor_data, prompt, negative_prompt, lora_choice, lora_alpha,
+                   strength, steps, cfg, seed, randomize_seed,
+                   transformer_choice, vae_choice, vram_type_str, progress=gr.Progress()):
+    global is_generating_interrupted
+    is_generating_interrupted = False
+
+    is_low_vram = "24GB" in vram_type_str or "Under 24GB" in vram_type_str or "24G以下" in vram_type_str or "24GB以下" in vram_type_str
+
+    input_image = None
+    mask_layer = None
+    
+    if isinstance(image_editor_data, dict):
+        if 'background' in image_editor_data:
+            input_image = image_editor_data['background']
+            if image_editor_data.get('layers'):
+                mask_layer = image_editor_data['layers'][0]
+    elif isinstance(image_editor_data, (tuple, list)):
+        input_image = image_editor_data[0]
+        mask_layer = image_editor_data[1]
+    elif isinstance(image_editor_data, Image.Image):
+        input_image = image_editor_data
+
+    if input_image is None:
+        raise gr.Error("⚠️ 请先上传图片！")
+    
+    if input_image.mode == 'RGBA':
+        background = Image.new('RGB', input_image.size, (255,255,255))
+        background.paste(input_image, (0, 0), input_image)
+        input_image = background
+    else:
+        input_image = input_image.convert("RGB")
+
+    if mask_layer is None:
+        raise gr.Error("⚠️ 请使用画笔在图片上涂抹要修改的区域。")
+    
+    mask = process_mask_for_inpaint(mask_layer)
+    if mask is None:
+        raise gr.Error("⚠️ Mask 无效，请确保涂抹了区域。")
+
+    try:
+        pipe_local = load_i2i_pipeline(transformer_choice, vae_choice, is_low_vram)
+    except Exception as e:
+        raise gr.Error(f"模型加载失败: {str(e)}")
+    
+    pipe_local = apply_lora_to_pipeline(pipe_local, lora_choice, lora_alpha, lora_scale=0.6)
+
+    if randomize_seed:
+        seed = random.randint(0, 2**32 - 1)
+    generator = torch.Generator(DEVICE).manual_seed(int(seed))
+
+    orig_w, orig_h = input_image.size
+    if mask.size != (orig_w, orig_h):
+        mask = mask.resize((orig_w, orig_h), Image.LANCZOS)
+
+    date_str = datetime.datetime.now().strftime("%Y-%m-%d")
+    day_dir = os.path.join(OUTPUT_DIR, date_str)
+    os.makedirs(day_dir, exist_ok=True)
+
+    result_img = None
+
+    try:
+        try:
+            result_img = pipe_local(
+                prompt=prompt.strip(),
+                negative_prompt=negative_prompt.strip(),
+                image=input_image,
+                mask_image=mask,
+                strength=float(strength),
+                num_inference_steps=int(steps),
+                guidance_scale=float(cfg),
+                generator=generator,
+                callback_on_step_end=interrupt_callback
+            ).images[0]
+        except (TypeError, AttributeError) as e:
+            print(f"⚠️ 原生 Inpaint 失败 ({e})，使用手动混合模式...")
+            
+            img_array = np.array(input_image).astype(np.float32) /255.0
+            mask_array = np.array(mask.convert('L')).astype(np.float32) / 255.0
+            mask_3d = np.expand_dims(mask_array, axis=2)
+            mask_3d = np.repeat(mask_3d,3, axis=2)
+            
+            noise = np.random.randn(*img_array.shape).astype(np.float32) * 0.1
+            inpaint_input_array = img_array * (1 - mask_3d) + (img_array + noise) * mask_3d
+            inpaint_input_array = np.clip(inpaint_input_array, 0, 1)
+            inpaint_input = Image.fromarray((inpaint_input_array * 255).astype(np.uint8))
+            
+            generated = pipe_local(
+                prompt=prompt.strip(),
+                negative_prompt=negative_prompt.strip(),
+                image=inpaint_input,
+                strength=float(strength),
+                num_inference_steps=int(steps),
+                guidance_scale=float(cfg),
+                generator=generator,
+                callback_on_step_end=interrupt_callback
+            ).images[0]
+            
+            if generated.size != (orig_w, orig_h):
+                generated = generated.resize((orig_w, orig_h), Image.LANCZOS)
+            
+            gen_array = np.array(generated).astype(np.float32) / 255.0
+            orig_array = np.array(input_image).astype(np.float32) / 255.0
+            
+            final_array = orig_array * (1 - mask_3d) + gen_array * mask_3d
+            final_array = np.clip(final_array, 0, 1)
+            result_img = Image.fromarray((final_array * 255).astype(np.uint8))
+
+        filename = os.path.join(day_dir, f"inpaint_{datetime.datetime.now():%H%M%S}_{uuid.uuid4().hex[:4]}.png")
+        result_img.save(filename)
+        
+    except Exception as e:
+        if "任务已手动停止" in str(e): raise
+        import traceback
+        traceback.print_exc()
+        raise gr.Error(f"局部重绘失败: {str(e)}")
+    finally:
+        auto_flush_vram()
+
+    return [result_img], seed
+
+def edit_image(image, angle, x, y, w, h, hflip, vflip, filter_name, brightness, contrast, saturation):
+    if image is None:
+        return None
+    img = image.copy()
+    if angle != 0:
+        img = img.rotate(angle, expand=True)
+    if x or y or w < 100 or h < 100:
+        ow, oh = img.size
+        left = int(ow * x / 100)
+        top = int(oh * y / 100)
+        right = int(ow * (x + w) / 100)
+        bottom = int(oh * (y + h) / 100)
+        img = img.crop((left, top, right, bottom))
+    if hflip:
+        img = ImageOps.mirror(img)
+    if vflip:
+        img = ImageOps.flip(img)
+    if filter_name:
+        filter_map = {
+            "模糊": ImageFilter.BLUR, "轮廓": ImageFilter.CONTOUR, "细节": ImageFilter.DETAIL,
+            "边缘增强": ImageFilter.EDGE_ENHANCE, "更多边缘增强": ImageFilter.EDGE_ENHANCE_MORE,
+            "浮雕": ImageFilter.EMBOSS, "查找边缘": ImageFilter.FIND_EDGES,
+            "锐化": ImageFilter.SHARPEN, "平滑": ImageFilter.SMOOTH, "更多平滑": ImageFilter.SMOOTH_MORE,
+        }
+        f = filter_map.get(filter_name)
+        if f:
+            img = img.filter(f)
+    if brightness != 0:
+        img = ImageEnhance.Brightness(img).enhance(1 + brightness / 100)
+    if contrast != 0:
+        img = ImageEnhance.Contrast(img).enhance(1 + contrast / 100)
+    if saturation != 0:
+        img = ImageEnhance.Color(img).enhance(1 + saturation / 100)
+    return img
+
+# =========================
+# Gradio 界面构建
+# =========================
+TOTAL_VRAM = torch.cuda.get_device_properties(0).total_memory if DEVICE == "cuda" else 0
+DEFAULT_PERF_MODE = "高端机模式 (>=24GB)" if TOTAL_VRAM >= 24 * 1024**3 else "24GB以下 (优化模式)"
+
+with gr.Blocks() as demo:
+    lang_state = gr.State("zh")
+
+    with gr.Row():
+        title_md = gr.Markdown(TEXT["zh"]["title"])
+        lang_btn = gr.Button(TEXT["zh"]["lang_btn"], size="sm")
+
+    with gr.Tabs() as tabs:
+        with gr.Tab(TEXT["zh"]["tab_generate"]) as tab_gen:
+            with gr.Row():
+                with gr.Column(scale=4):
+                    prompt = gr.Textbox(label=TEXT["zh"]["prompt"], lines=4, placeholder=TEXT["zh"]["prompt_placeholder"])
+                    with gr.Row():
+                        refresh_lora = gr.Button(TEXT["zh"]["refresh_lora"], size="sm")
+                        refresh_model_t2i = gr.Button(TEXT["zh"]["refresh_model"], size="sm")
+                    
+                    lora_choices = ["None"] + scan_lora_items()
+                    lora_drop = gr.Dropdown(label=TEXT["zh"]["lora_label"], choices=lora_choices, value="None")
+                    lora_alpha = gr.Slider(0, 2, 1, step=0.05, label=TEXT["zh"]["lora_strength"])
+
+                    model_section_md = gr.Markdown(TEXT["zh"]["model_section"])
+
+                    with gr.Row():
+                        transformer_choice = gr.Dropdown(label=TEXT["zh"]["transformer"], choices=get_choices(MOD_TRANSFORMER), value="default")
+                        vae_choice = gr.Dropdown(label=TEXT["zh"]["vae"], choices=get_choices(MOD_VAE), value="default")
+
+                    vram_type = gr.Radio(
+                        [TEXT["zh"]["vram_low"], TEXT["zh"]["vram_high"]],
+                        label=TEXT["zh"]["vram_type"],
+                        value=DEFAULT_PERF_MODE
+                    )
+                    device_ui = gr.Radio(["cuda", "cpu"], label=TEXT["zh"]["device"], value="cuda" if torch.cuda.is_available() else "cpu", visible=False)
+                    
+                    num_images = gr.Slider(1, 8, 1, step=1, label=TEXT["zh"]["num_images"])
+                    image_format = gr.Dropdown(["png", "jpeg", "webp"], value="png", label=TEXT["zh"]["output_format"])
+
+                    with gr.Row():
+                        width = gr.Slider(512, 2048, 1024, step=64, label=TEXT["zh"]["width"])
+                        height = gr.Slider(512, 2048, 1024, step=64, label=TEXT["zh"]["height"])
+                    num_inference_steps = gr.Slider(1, 50, 10, step=1, label=TEXT["zh"]["steps"])
+                    guidance_scale = gr.Slider(0, 10, 0, step=0.1, label=TEXT["zh"]["cfg"])
+                    seed = gr.Number(label=TEXT["zh"]["seed"], value=42, precision=0)
+                    randomize_seed = gr.Checkbox(label=TEXT["zh"]["random_seed"], value=True)
+
+                    with gr.Row():
+                        generate_btn = gr.Button(TEXT["zh"]["generate"], variant="primary", size="lg")
+                        stop_btn = gr.Button(TEXT["zh"]["stop"], variant="stop", size="lg", interactive=False)
+
+                with gr.Column(scale=6):
+                    gallery = gr.Gallery(label=TEXT["zh"]["gallery"], columns=2, height="80vh")
+                    used_seed = gr.Number(label=TEXT["zh"]["used_seed"], interactive=False)
+
+        with gr.Tab(TEXT["zh"]["tab_edit"]) as tab_edit:
+            with gr.Row():
+                with gr.Column():
+                    image_input = gr.Image(label=TEXT["zh"]["edit_upload"], type="pil")
+                    with gr.Group():
+                        rotate_angle = gr.Slider(-360, 360, 0, step=1, label=TEXT["zh"]["rotate"])
+                        crop_x = gr.Slider(0, 100, 0, step=1, label=TEXT["zh"]["crop_x"])
+                        crop_y = gr.Slider(0, 100, 0, step=1, label=TEXT["zh"]["crop_y"])
+                        crop_width = gr.Slider(0, 100, 100, step=1, label=TEXT["zh"]["crop_w"])
+                        crop_height = gr.Slider(0, 100, 100, step=1, label=TEXT["zh"]["crop_h"])
+                        flip_horizontal = gr.Checkbox(label=TEXT["zh"]["hflip"])
+                        flip_vertical = gr.Checkbox(label=TEXT["zh"]["vflip"])
+                    edit_btn = gr.Button(TEXT["zh"]["edit_btn"], variant="primary")
+
+                with gr.Column():
+                    edited_image_output = gr.Image(label=TEXT["zh"]["edited_image"], type="pil")
+                    with gr.Group():
+                        apply_filter = gr.Dropdown(
+                            ["模糊", "轮廓", "细节", "边缘增强", "更多边缘增强", "浮雕", "查找边缘", "锐化", "平滑", "更多平滑"],
+                            label=TEXT["zh"]["filter"]
+                        )
+                        brightness = gr.Slider(-100, 100, 0, step=1, label=TEXT["zh"]["brightness"])
+                        contrast = gr.Slider(-100, 100, 0, step=1, label=TEXT["zh"]["contrast"])
+                        saturation = gr.Slider(-100, 100, 0, step=1, label=TEXT["zh"]["saturation"])
+
+        with gr.Tab(TEXT["zh"]["tab_img2img"]) as tab_img2img:
+            i2i_status_md = gr.Markdown(TEXT["zh"]["i2i_note"])
+            with gr.Row():
+                with gr.Column(scale=4):
+                    i2i_image_input = gr.Image(label=TEXT["zh"]["i2i_ref"], type="pil")
+                    
+                    i2i_prompt = gr.Textbox(label=TEXT["zh"]["i2i_prompt"], lines=3, placeholder=TEXT["zh"]["i2i_ph"])
+                    i2i_negative_prompt = gr.Textbox(label=TEXT["zh"]["negative_prompt"], lines=2, placeholder=TEXT["zh"]["negative_placeholder"])
+                    
+                    with gr.Row():
+                        i2i_refresh_lora = gr.Button(TEXT["zh"]["refresh_lora"], size="sm")
+                        i2i_refresh_model = gr.Button(TEXT["zh"]["refresh_model"], size="sm")
+                    
+                    i2i_lora_choices = ["None"] + scan_lora_items()
+                    i2i_lora_drop = gr.Dropdown(label=TEXT["zh"]["lora_label"], choices=i2i_lora_choices, value="None")
+                    i2i_lora_alpha = gr.Slider(0, 2, 1, step=0.05, label=TEXT["zh"]["lora_strength"])
+
+                    with gr.Accordion(TEXT["zh"]["model_section"], open=False):
+                        i2i_transformer_choice = gr.Dropdown(label=TEXT["zh"]["transformer"], choices=get_choices(MOD_TRANSFORMER), value="default")
+                        i2i_vae_choice = gr.Dropdown(label=TEXT["zh"]["vae"], choices=get_choices(MOD_VAE), value="default")
+                        i2i_vram_type = gr.Radio(
+                            [TEXT["zh"]["vram_low"], TEXT["zh"]["vram_high"]],
+                            label=TEXT["zh"]["vram_type"],
+                            value=DEFAULT_PERF_MODE
+                        )
+
+                    i2i_mode = gr.Radio(
+                        [TEXT["zh"]["i2i_mode_a"], TEXT["zh"]["i2i_mode_b"]],
+                        label=TEXT["zh"]["i2i_mode"],
+                        value=TEXT["zh"]["i2i_mode_a"]
+                    )
+                    
+                    with gr.Row():
+                        i2i_out_w = gr.Slider(0, 2048, 0, step=16, label=TEXT["zh"]["i2i_out_w"])
+                        i2i_out_h = gr.Slider(0, 2048, 0, step=16, label=TEXT["zh"]["i2i_out_h"])
+                    i2i_tip_md = gr.Markdown(TEXT["zh"]["i2i_tip"])
+                    
+                    i2i_strength = gr.Slider(0.1, 1.0, 0.4, step=0.05, label=TEXT["zh"]["i2i_strength"])
+                    i2i_steps = gr.Slider(1, 50, 6, step=1, label=TEXT["zh"]["steps"])
+                    i2i_cfg = gr.Slider(0.0, 5.0, 1.0, step=0.1, label=TEXT["zh"]["cfg"])
+                    
+                    i2i_num_images = gr.Slider(1, 4, 1, step=1, label=TEXT["zh"]["num_images"])
+                    i2i_image_format = gr.Dropdown(["png", "jpeg", "webp"], value="png", label=TEXT["zh"]["output_format"])
+                    i2i_seed = gr.Number(label=TEXT["zh"]["seed"], value=42, precision=0)
+                    i2i_randomize_seed = gr.Checkbox(label=TEXT["zh"]["random_seed"], value=True)
+
+                    with gr.Row():
+                        i2i_generate_btn = gr.Button(TEXT["zh"]["i2i_btn"], variant="primary", size="lg")
+                        i2i_stop_btn = gr.Button(TEXT["zh"]["stop"], variant="stop", size="lg", interactive=False)
+
+                with gr.Column(scale=6):
+                    i2i_gallery = gr.Gallery(label=TEXT["zh"]["gallery"], columns=2, height="80vh")
+                    i2i_used_seed = gr.Number(label=TEXT["zh"]["used_seed"], interactive=False)
+
+        with gr.Tab(TEXT["zh"]["tab_inpaint"]) as tab_inpaint:
+            with gr.Row():
+                with gr.Column(scale=4):
+                    inpaint_editor = gr.ImageEditor(
+                        label=TEXT["zh"]["inpaint_upload"],
+                        type="pil",
+                        layers=True,
+                        eraser=True,
+                        brush=gr.Brush(colors=["#FFFFFF", "#000000", "#FF0000"], color_mode="fixed")
+                    )
+                    inpaint_tip_md = gr.Markdown(TEXT["zh"]["inpaint_desc"])
+                    
+                    inpaint_prompt = gr.Textbox(label=TEXT["zh"]["i2i_prompt"], lines=3, placeholder=TEXT["zh"]["i2i_ph"])
+                    inpaint_negative_prompt = gr.Textbox(label=TEXT["zh"]["negative_prompt"], lines=2, placeholder=TEXT["zh"]["negative_placeholder"])
+
+                    with gr.Row():
+                        inpaint_refresh_lora = gr.Button(TEXT["zh"]["refresh_lora"], size="sm")
+                        inpaint_refresh_model = gr.Button(TEXT["zh"]["refresh_model"], size="sm")
+                    
+                    inpaint_lora_choices = ["None"] + scan_lora_items()
+                    inpaint_lora_drop = gr.Dropdown(label=TEXT["zh"]["lora_label"], choices=inpaint_lora_choices, value="None")
+                    inpaint_lora_alpha = gr.Slider(0, 2, 1, step=0.05, label=TEXT["zh"]["lora_strength"])
+
+                    with gr.Accordion(TEXT["zh"]["model_section"], open=False):
+                        inpaint_transformer_choice = gr.Dropdown(label=TEXT["zh"]["transformer"], choices=get_choices(MOD_TRANSFORMER), value="default")
+                        inpaint_vae_choice = gr.Dropdown(label=TEXT["zh"]["vae"], choices=get_choices(MOD_VAE), value="default")
+                        inpaint_vram_type = gr.Radio(
+                            [TEXT["zh"]["vram_low"], TEXT["zh"]["vram_high"]],
+                            label=TEXT["zh"]["vram_type"],
+                            value=DEFAULT_PERF_MODE
+                        )
+                    
+                    inpaint_strength = gr.Slider(0.1, 1.0, 0.7, step=0.05, label=TEXT["zh"]["i2i_strength"])
+                    inpaint_steps = gr.Slider(1, 50, 8, step=1, label=TEXT["zh"]["steps"])
+                    inpaint_cfg = gr.Slider(0.0, 5.0, 1.0, step=0.1, label=TEXT["zh"]["cfg"])
+                    
+                    inpaint_seed = gr.Number(label=TEXT["zh"]["seed"], value=42, precision=0)
+                    inpaint_randomize_seed = gr.Checkbox(label=TEXT["zh"]["random_seed"], value=True)
+
+                    with gr.Row():
+                        inpaint_generate_btn = gr.Button(TEXT["zh"]["i2i_btn"], variant="primary", size="lg")
+                        inpaint_stop_btn = gr.Button(TEXT["zh"]["stop"], variant="stop", size="lg", interactive=False)
+
+                with gr.Column(scale=6):
+                    inpaint_gallery = gr.Gallery(label=TEXT["zh"]["gallery"], columns=2, height="80vh")
+                    inpaint_used_seed = gr.Number(label=TEXT["zh"]["used_seed"], interactive=False)
+
+    def switch_language_full(lang):
+        new_lang = "en" if lang == "zh" else "zh"
+        t = TEXT[new_lang]
+        
+        # 修复：根据硬件显存大小，决定当前应该选哪个语言版本的选项
+        is_low_vram_hardware = TOTAL_VRAM < 24 * 1024**3
+        current_vram_val = t['vram_low'] if is_low_vram_hardware else t['vram_high']
+        
+        # 修复：更新显存选项的值，不仅仅是选项列表
+        return (
+            new_lang, t['title'], t['lang_btn'],
+            gr.update(label=t['tab_generate']), gr.update(label=t['tab_edit']), 
+            gr.update(label=t['tab_img2img']), gr.update(label=t['tab_inpaint']),
+            gr.update(label=t['prompt'], placeholder=t['prompt_placeholder']),
+            gr.update(value=t['refresh_lora']), gr.update(value=t['refresh_model']),
+            gr.update(label=t['lora_label']), gr.update(label=t['lora_strength']),
+            t['model_section'], gr.update(label=t['transformer']), gr.update(label=t['vae']),
+            # T2I VRAM: 更新选项和值
+            gr.update(label=t['vram_type'], choices=[t['vram_low'], t['vram_high']], value=current_vram_val), 
+            gr.update(label=t['device']),
+            gr.update(label=t['num_images']), gr.update(label=t['output_format']),
+            gr.update(label=t['width']), gr.update(label=t['height']),
+            gr.update(label=t['steps']), gr.update(label=t['cfg']),
+            gr.update(label=t['seed']), gr.update(label=t['random_seed']),
+            gr.update(value=t['generate']), gr.update(value=t['stop']),
+            gr.update(label=t['gallery']), gr.update(label=t['used_seed']),
+            
+            gr.update(label=t['edit_upload']),
+            gr.update(label=t['rotate']), gr.update(label=t['crop_x']), gr.update(label=t['crop_y']),
+            gr.update(label=t['crop_w']), gr.update(label=t['crop_h']),
+            gr.update(label=t['hflip']), gr.update(label=t['vflip']),
+            gr.update(value=t['edit_btn']), gr.update(label=t['edited_image']),
+            gr.update(label=t['filter']), gr.update(label=t['brightness']), gr.update(label=t['contrast']), gr.update(label=t['saturation']),
+            
+            gr.update(value=t['i2i_note']),
+            gr.update(label=t['i2i_ref']),
+            gr.update(label=t['i2i_prompt'], placeholder=t['i2i_ph']),
+            gr.update(label=t['negative_prompt'], placeholder=t['negative_placeholder']),
+            gr.update(value=t['refresh_lora']), gr.update(value=t['refresh_model']),
+            gr.update(label=t['lora_label']), gr.update(label=t['lora_strength']),
+            gr.update(label=t['transformer']), gr.update(label=t['vae']),
+            # Img2Img VRAM: 更新选项和值
+            gr.update(label=t['vram_type'], choices=[t['vram_low'], t['vram_high']], value=current_vram_val),
+            gr.update(label=t['i2i_mode'], choices=[t['i2i_mode_a'], t['i2i_mode_b']]),
+            gr.update(label=t['i2i_out_w']), gr.update(label=t['i2i_out_h']),
+            gr.update(value=t['i2i_tip']),
+            gr.update(label=t['i2i_strength']),
+            gr.update(label=t['steps']), gr.update(label=t['cfg']),
+            gr.update(label=t['num_images']), gr.update(label=t['output_format']),
+            gr.update(label=t['seed']), gr.update(label=t['random_seed']),
+            gr.update(value=t['i2i_btn']), gr.update(value=t['stop']),
+            gr.update(label=t['gallery']), gr.update(label=t['used_seed']),
+
+            gr.update(label=t['inpaint_upload']),
+            gr.update(value=t['inpaint_desc']),
+            gr.update(label=t['i2i_prompt'], placeholder=t['i2i_ph']),
+            gr.update(label=t['negative_prompt'], placeholder=t['negative_placeholder']),
+            gr.update(value=t['refresh_lora']), gr.update(value=t['refresh_model']),
+            gr.update(label=t['lora_label']), gr.update(label=t['lora_strength']),
+            gr.update(label=t['transformer']), gr.update(label=t['vae']),
+            # Inpaint VRAM: 更新选项和值
+            gr.update(label=t['vram_type'], choices=[t['vram_low'], t['vram_high']], value=current_vram_val),
+            gr.update(label=t['i2i_strength']),
+            gr.update(label=t['steps']), gr.update(label=t['cfg']),
+            gr.update(label=t['seed']), gr.update(label=t['random_seed']),
+            gr.update(value=t['i2i_btn']), gr.update(value=t['stop']),
+            gr.update(label=t['gallery']), gr.update(label=t['used_seed']),
+        )
+
+    lang_btn.click(
+        fn=switch_language_full,
+        inputs=lang_state,
+        outputs=[
+            lang_state, title_md, lang_btn,
+            tab_gen, tab_edit, tab_img2img, tab_inpaint,
+            prompt, refresh_lora, refresh_model_t2i, lora_drop, lora_alpha, model_section_md,
+            transformer_choice, vae_choice, vram_type, device_ui, num_images, image_format,
+            width, height, num_inference_steps, guidance_scale, seed, randomize_seed,
+            generate_btn, stop_btn, gallery, used_seed,
+            image_input, rotate_angle, crop_x, crop_y, crop_width, crop_height,
+            flip_horizontal, flip_vertical, edit_btn, edited_image_output,
+            apply_filter, brightness, contrast, saturation,
+            i2i_status_md, i2i_image_input, i2i_prompt, i2i_negative_prompt, 
+            i2i_refresh_lora, i2i_refresh_model, i2i_lora_drop, i2i_lora_alpha,
+            i2i_transformer_choice, i2i_vae_choice, i2i_vram_type, i2i_mode,
+            i2i_out_w, i2i_out_h, i2i_tip_md,
+            i2i_strength, i2i_steps, i2i_cfg,
+            i2i_num_images, i2i_image_format, i2i_seed, i2i_randomize_seed,
+            i2i_generate_btn, i2i_stop_btn, i2i_gallery, i2i_used_seed,
+            inpaint_editor, inpaint_tip_md,
+            inpaint_prompt, inpaint_negative_prompt,
+            inpaint_refresh_lora, inpaint_refresh_model, inpaint_lora_drop, inpaint_lora_alpha,
+            inpaint_transformer_choice, inpaint_vae_choice, inpaint_vram_type,
+            inpaint_strength, inpaint_steps, inpaint_cfg,
+            inpaint_seed, inpaint_randomize_seed,
+            inpaint_generate_btn, inpaint_stop_btn, inpaint_gallery, inpaint_used_seed
+        ]
+    )
+
+    refresh_lora.click(fn=scan_lora_items, outputs=[lora_drop, i2i_lora_drop, inpaint_lora_drop])
+    lora_drop.change(update_prompt_with_lora, [prompt, lora_drop, lora_alpha], prompt)
+
+    def refresh_models_t2i():
+        return gr.update(choices=get_choices(MOD_TRANSFORMER)), gr.update(choices=get_choices(MOD_VAE))
+    refresh_model_t2i.click(fn=refresh_models_t2i, outputs=[transformer_choice, vae_choice])
+
+    def start_gen(): return gr.update(interactive=False), gr.update(interactive=True)
+    def end_gen(): return gr.update(interactive=True), gr.update(interactive=False)
+    def trigger_stop():
+        global is_generating_interrupted
+        is_generating_interrupted = True
+
+    generate_event = generate_btn.click(fn=start_gen, outputs=[generate_btn, stop_btn]).then(
+        fn=generate_image,
+        inputs=[prompt, lora_drop, lora_alpha, num_images, image_format,
+                width, height, num_inference_steps, guidance_scale, seed, randomize_seed,
+                transformer_choice, vae_choice, vram_type], 
+        outputs=[gallery, used_seed]
+    ).then(fn=end_gen, outputs=[generate_btn, stop_btn])
+
+    stop_btn.click(fn=trigger_stop).then(fn=end_gen, outputs=[generate_btn, stop_btn], cancels=[generate_event])
+
+    i2i_refresh_lora.click(fn=scan_lora_items, outputs=[lora_drop, i2i_lora_drop, inpaint_lora_drop])
+    i2i_lora_drop.change(update_prompt_with_lora, [i2i_prompt, i2i_lora_drop, i2i_lora_alpha], i2i_prompt)
+
+    def refresh_models_i2i():
+        return gr.update(choices=get_choices(MOD_TRANSFORMER)), gr.update(choices=get_choices(MOD_VAE))
+    i2i_refresh_model.click(fn=refresh_models_i2i, outputs=[i2i_transformer_choice, i2i_vae_choice])
+
+    def start_i2i(): return gr.update(interactive=False), gr.update(interactive=True)
+    def end_i2i(): return gr.update(interactive=True), gr.update(interactive=False)
+
+    i2i_generate_event = i2i_generate_btn.click(fn=start_i2i, outputs=[i2i_generate_btn, i2i_stop_btn]).then(
+        fn=run_img2img_enhanced,
+        inputs=[i2i_image_input, i2i_prompt, i2i_negative_prompt, i2i_lora_drop, i2i_lora_alpha, 
+                i2i_num_images, i2i_image_format,
+                i2i_out_w, i2i_out_h, i2i_mode, i2i_strength, i2i_steps, i2i_cfg,
+                i2i_seed, i2i_randomize_seed,
+                i2i_transformer_choice, i2i_vae_choice, i2i_vram_type], 
+        outputs=[i2i_gallery, i2i_used_seed]
+    ).then(fn=end_i2i, outputs=[i2i_generate_btn, i2i_stop_btn])
+
+    i2i_stop_btn.click(fn=trigger_stop).then(fn=end_i2i, outputs=[i2i_generate_btn, i2i_stop_btn], cancels=[i2i_generate_event])
+
+    inpaint_refresh_lora.click(fn=scan_lora_items, outputs=[lora_drop, i2i_lora_drop, inpaint_lora_drop])
+    inpaint_lora_drop.change(update_prompt_with_lora, [inpaint_prompt, inpaint_lora_drop, inpaint_lora_alpha], inpaint_prompt)
+
+    def refresh_models_inpaint():
+        return gr.update(choices=get_choices(MOD_TRANSFORMER)), gr.update(choices=get_choices(MOD_VAE))
+    inpaint_refresh_model.click(fn=refresh_models_inpaint, outputs=[inpaint_transformer_choice, inpaint_vae_choice])
+
+    def start_inpaint(): return gr.update(interactive=False), gr.update(interactive=True)
+    def end_inpaint(): return gr.update(interactive=True), gr.update(interactive=False)
+
+    inpaint_generate_event = inpaint_generate_btn.click(fn=start_inpaint, outputs=[inpaint_generate_btn, inpaint_stop_btn]).then(
+        fn=run_inpainting,
+        inputs=[inpaint_editor, inpaint_prompt, inpaint_negative_prompt, inpaint_lora_drop, inpaint_lora_alpha,
+                inpaint_strength, inpaint_steps, inpaint_cfg,
+                inpaint_seed, inpaint_randomize_seed,
+                inpaint_transformer_choice, inpaint_vae_choice, inpaint_vram_type], 
+        outputs=[inpaint_gallery, inpaint_used_seed]
+    ).then(fn=end_inpaint, outputs=[inpaint_generate_btn, inpaint_stop_btn])
+
+    inpaint_stop_btn.click(fn=trigger_stop).then(fn=end_inpaint, outputs=[inpaint_generate_btn, inpaint_stop_btn], cancels=[inpaint_generate_event])
+
+    edit_btn.click(
+        fn=edit_image,
+        inputs=[image_input, rotate_angle, crop_x, crop_y, crop_width, crop_height,
+                flip_horizontal, flip_vertical, apply_filter, brightness, contrast, saturation],
+        outputs=edited_image_output
+    )
+
+if __name__ == "__main__":
+    demo.queue(max_size=20)
+    demo.launch(show_error=True)