Free, open-source AI video generator for Mac. Run LTX-2.5 and MiniMax H3 (Hailuo) locally on Apple Silicon: text-to-video and image-to-video with sound, lip-sync, character LoRA training, songs from lyrics (YuE2) and image editing (Qwen-Image-Edit). One-click install via Pinokio. Offline: no cloud, no API key, no NVIDIA GPU.
Python ai-filmmakingai-videoai-video-generatorapple-siliconhailuoimage-to-videolip-synclocal-ailora-trainingltx-2ltx-2-5ltx-videomacosminimax-h3mlxmusic-generationoffline-aipinokiotext-to-videovideo-generation
fix: ship-readiness pass — 4 P0s + 22 P1s across train, panel, docs, security
mrbizarrob024bb54ff88
diff --git a/.clinerules b/.clinerulesindex 340c0db..c81b8bd 100644--- a/.clinerules+++ b/.clinerules@@ -28,7 +28,7 @@ The panel itself is MIT. Model weights have Lightricks' own license.separate dev folder. Old "local dev" copy was deleted to consolidate.```-/Users/salo/pinokio/api/phosphene.git/ ← edit here+~/pinokio/api/phosphene.git/ ← edit here├── .git/ ← real working copy of mrbizarro/phosphene├── ltx-2-mlx/ ← upstream package, cloned at install│ ├── env/ ← Python 3.11 venv@@ -48,7 +48,7 @@ separate dev folder. Old "local dev" copy was deleted to consolidate.└── required_files.json ← single source of truth for "installed"```-To work: `cd /Users/salo/pinokio/api/phosphene.git/`, edit, `git commit`,+To work: `cd ~/pinokio/api/phosphene.git/`, edit, `git commit`,`git push`. Pinokio's Update button does `git pull` here. No separatecopy to keep in sync.@@ -311,7 +311,7 @@ that already pulled 0.31.2 can recover by clicking Update.and click Start.### Disk consolidation-- Old `/Users/salo/Documents/Codex/...` dev folder was deleted.+- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.- `~/.cache/huggingface/hub/models--*` was also deleted. Pinokioinstall pulls weights into `mlx_models/` directly via `hf@@ -1121,8 +1121,8 @@ precedence on conflict.)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. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `/Users/salo/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.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.+3. **Example Lock-in:** Identify the closest matching script in `~/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.+4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.5. **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.6. **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.@@ -1155,9 +1155,9 @@ on: [{Deviation from this pattern requires written approval from the user.-- Make sure to keep this entire document and `PINOKIO.md` at /Users/salo/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 /Users/salo/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 /Users/salo/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.+- Make sure to keep this entire document and `PINOKIO.md` at ~/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 ~/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 ~/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.@@ -1251,7 +1251,7 @@ project-root/└── pinokio.json # Metadata (title, description, icon)```-IMPORTANT: ALWAYS try to follow the best practices in the examples folder (/Users/salo/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/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@@ -1303,7 +1303,7 @@ If we are starting with existing launcher script files, work with the existing f- **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 (/Users/salo/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/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 resortIf there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.@@ -1408,8 +1408,8 @@ module.exports = {## APIThis 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 /Users/salo/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md further documentation on the full syntax+1. Check the examples in the ~/pinokio/prototype/system/examples folder+2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax### Script API@@ -1538,7 +1538,7 @@ logs/- 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 `/Users/salo/pinokio/api/phosphene.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.+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.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.@@ -1564,12 +1564,12 @@ logs/- 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 /Users/salo/pinokio/prototype/system/examples folder to see how these are being used.+ - Check the examples in the ~/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 `/Users/salo/pinokio/api/phosphene.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.+- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.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. Retrofitting an already-working setup- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.@@ -1586,7 +1586,7 @@ logs/### 12. 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 `/Users/salo/pinokio/api/phosphene.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`.+ - If the git repository for the `~/pinokio/api/phosphene.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`.### 13. 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@@ -1655,9 +1655,9 @@ The `torch.js` script also includes ways to install pytorch dependent libraries## Quick Reference### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at /Users/salo/pinokio/prototype/PTERM.md+- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section+- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section+- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md### Common Patterns- **Python Virtual Env:** `shell.run` with `venv` attribute- **Cross-platform Commands:** Always test on multiple platformsdiff --git a/.cursorrules b/.cursorrulesindex 340c0db..c81b8bd 100644--- a/.cursorrules+++ b/.cursorrules@@ -28,7 +28,7 @@ The panel itself is MIT. Model weights have Lightricks' own license.separate dev folder. Old "local dev" copy was deleted to consolidate.```-/Users/salo/pinokio/api/phosphene.git/ ← edit here+~/pinokio/api/phosphene.git/ ← edit here├── .git/ ← real working copy of mrbizarro/phosphene├── ltx-2-mlx/ ← upstream package, cloned at install│ ├── env/ ← Python 3.11 venv@@ -48,7 +48,7 @@ separate dev folder. Old "local dev" copy was deleted to consolidate.└── required_files.json ← single source of truth for "installed"```-To work: `cd /Users/salo/pinokio/api/phosphene.git/`, edit, `git commit`,+To work: `cd ~/pinokio/api/phosphene.git/`, edit, `git commit`,`git push`. Pinokio's Update button does `git pull` here. No separatecopy to keep in sync.@@ -311,7 +311,7 @@ that already pulled 0.31.2 can recover by clicking Update.and click Start.### Disk consolidation-- Old `/Users/salo/Documents/Codex/...` dev folder was deleted.+- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.- `~/.cache/huggingface/hub/models--*` was also deleted. Pinokioinstall pulls weights into `mlx_models/` directly via `hf@@ -1121,8 +1121,8 @@ precedence on conflict.)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. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `/Users/salo/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.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.+3. **Example Lock-in:** Identify the closest matching script in `~/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.+4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.5. **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.6. **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.@@ -1155,9 +1155,9 @@ on: [{Deviation from this pattern requires written approval from the user.-- Make sure to keep this entire document and `PINOKIO.md` at /Users/salo/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 /Users/salo/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 /Users/salo/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.+- Make sure to keep this entire document and `PINOKIO.md` at ~/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 ~/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 ~/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.@@ -1251,7 +1251,7 @@ project-root/└── pinokio.json # Metadata (title, description, icon)```-IMPORTANT: ALWAYS try to follow the best practices in the examples folder (/Users/salo/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/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@@ -1303,7 +1303,7 @@ If we are starting with existing launcher script files, work with the existing f- **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 (/Users/salo/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/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 resortIf there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.@@ -1408,8 +1408,8 @@ module.exports = {## APIThis 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 /Users/salo/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md further documentation on the full syntax+1. Check the examples in the ~/pinokio/prototype/system/examples folder+2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax### Script API@@ -1538,7 +1538,7 @@ logs/- 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 `/Users/salo/pinokio/api/phosphene.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.+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.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.@@ -1564,12 +1564,12 @@ logs/- 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 /Users/salo/pinokio/prototype/system/examples folder to see how these are being used.+ - Check the examples in the ~/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 `/Users/salo/pinokio/api/phosphene.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.+- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.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. Retrofitting an already-working setup- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.@@ -1586,7 +1586,7 @@ logs/### 12. 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 `/Users/salo/pinokio/api/phosphene.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`.+ - If the git repository for the `~/pinokio/api/phosphene.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`.### 13. 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@@ -1655,9 +1655,9 @@ The `torch.js` script also includes ways to install pytorch dependent libraries## Quick Reference### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at /Users/salo/pinokio/prototype/PTERM.md+- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section+- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section+- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md### Common Patterns- **Python Virtual Env:** `shell.run` with `venv` attribute- **Cross-platform Commands:** Always test on multiple platformsdiff --git a/.windsurfrules b/.windsurfrulesindex 340c0db..c81b8bd 100644--- a/.windsurfrules+++ b/.windsurfrules@@ -28,7 +28,7 @@ The panel itself is MIT. Model weights have Lightricks' own license.separate dev folder. Old "local dev" copy was deleted to consolidate.```-/Users/salo/pinokio/api/phosphene.git/ ← edit here+~/pinokio/api/phosphene.git/ ← edit here├── .git/ ← real working copy of mrbizarro/phosphene├── ltx-2-mlx/ ← upstream package, cloned at install│ ├── env/ ← Python 3.11 venv@@ -48,7 +48,7 @@ separate dev folder. Old "local dev" copy was deleted to consolidate.└── required_files.json ← single source of truth for "installed"```-To work: `cd /Users/salo/pinokio/api/phosphene.git/`, edit, `git commit`,+To work: `cd ~/pinokio/api/phosphene.git/`, edit, `git commit`,`git push`. Pinokio's Update button does `git pull` here. No separatecopy to keep in sync.@@ -311,7 +311,7 @@ that already pulled 0.31.2 can recover by clicking Update.and click Start.### Disk consolidation-- Old `/Users/salo/Documents/Codex/...` dev folder was deleted.+- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.- `~/.cache/huggingface/hub/models--*` was also deleted. Pinokioinstall pulls weights into `mlx_models/` directly via `hf@@ -1121,8 +1121,8 @@ precedence on conflict.)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. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `/Users/salo/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.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.+3. **Example Lock-in:** Identify the closest matching script in `~/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.+4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.5. **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.6. **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.@@ -1155,9 +1155,9 @@ on: [{Deviation from this pattern requires written approval from the user.-- Make sure to keep this entire document and `PINOKIO.md` at /Users/salo/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 /Users/salo/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 /Users/salo/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.+- Make sure to keep this entire document and `PINOKIO.md` at ~/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 ~/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 ~/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.@@ -1251,7 +1251,7 @@ project-root/└── pinokio.json # Metadata (title, description, icon)```-IMPORTANT: ALWAYS try to follow the best practices in the examples folder (/Users/salo/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/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@@ -1303,7 +1303,7 @@ If we are starting with existing launcher script files, work with the existing f- **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 (/Users/salo/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/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 resortIf there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.@@ -1408,8 +1408,8 @@ module.exports = {## APIThis 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 /Users/salo/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md further documentation on the full syntax+1. Check the examples in the ~/pinokio/prototype/system/examples folder+2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax### Script API@@ -1538,7 +1538,7 @@ logs/- 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 `/Users/salo/pinokio/api/phosphene.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.+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.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.@@ -1564,12 +1564,12 @@ logs/- 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 /Users/salo/pinokio/prototype/system/examples folder to see how these are being used.+ - Check the examples in the ~/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 `/Users/salo/pinokio/api/phosphene.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.+- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.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. Retrofitting an already-working setup- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.@@ -1586,7 +1586,7 @@ logs/### 12. 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 `/Users/salo/pinokio/api/phosphene.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`.+ - If the git repository for the `~/pinokio/api/phosphene.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`.### 13. 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@@ -1655,9 +1655,9 @@ The `torch.js` script also includes ways to install pytorch dependent libraries## Quick Reference### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at /Users/salo/pinokio/prototype/PTERM.md+- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section+- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section+- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md### Common Patterns- **Python Virtual Env:** `shell.run` with `venv` attribute- **Cross-platform Commands:** Always test on multiple platformsdiff --git a/AGENTS.md b/AGENTS.mdindex 19eacc3..af1a878 100644--- a/AGENTS.md+++ b/AGENTS.md@@ -91,11 +91,11 @@ in 8 m 07 s. That's the recommended default for "fast HD with audio".### Repository layout (now — both clones documented)-`/Users/salo/pinokio/api/phosphene.git/` is the **production** clone.+`~/pinokio/api/phosphene.git/` is the **production** clone.Tracks `main`. Pinokio's daily-driver Phosphene panel runs from here onport 8198.-`/Users/salo/pinokio/api/phosphene-dev.git/` is the **dev** clone.+`~/pinokio/api/phosphene-dev.git/` is the **dev** clone.Tracks `dev`. Set up via `scripts/setup_dev_panel.sh`. Runs on port 8199with the amber `DEV` profile badge in the header. Symlinks`mlx_models/`, `mlx_outputs/`, `panel_uploads/`, and `state/` from a@@ -127,7 +127,7 @@ The panel itself is MIT. Model weights have Lightricks' own license.separate dev folder. Old "local dev" copy was deleted to consolidate.```-/Users/salo/pinokio/api/phosphene.git/ ← edit here+~/pinokio/api/phosphene.git/ ← edit here├── .git/ ← real working copy of mrbizarro/phosphene├── ltx-2-mlx/ ← upstream package, cloned at install│ ├── env/ ← Python 3.11 venv@@ -147,7 +147,7 @@ separate dev folder. Old "local dev" copy was deleted to consolidate.└── required_files.json ← single source of truth for "installed"```-To work: `cd /Users/salo/pinokio/api/phosphene.git/`, edit, `git commit`,+To work: `cd ~/pinokio/api/phosphene.git/`, edit, `git commit`,`git push`. Pinokio's Update button does `git pull` here. No separatecopy to keep in sync.@@ -427,7 +427,7 @@ that already pulled 0.31.2 can recover by clicking Update.and click Start.### Disk consolidation-- Old `/Users/salo/Documents/Codex/...` dev folder was deleted.+- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.- `~/.cache/huggingface/hub/models--*` was also deleted. Pinokioinstall pulls weights into `mlx_models/` directly via `hf@@ -1249,8 +1249,8 @@ precedence on conflict.)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. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `/Users/salo/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.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.+3. **Example Lock-in:** Identify the closest matching script in `~/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.+4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.5. **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.6. **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.@@ -1283,9 +1283,9 @@ on: [{Deviation from this pattern requires written approval from the user.-- Make sure to keep this entire document and `PINOKIO.md` at /Users/salo/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 /Users/salo/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 /Users/salo/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.+- Make sure to keep this entire document and `PINOKIO.md` at ~/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 ~/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 ~/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.@@ -1379,7 +1379,7 @@ project-root/└── pinokio.json # Metadata (title, description, icon)```-IMPORTANT: ALWAYS try to follow the best practices in the examples folder (/Users/salo/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/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@@ -1431,7 +1431,7 @@ If we are starting with existing launcher script files, work with the existing f- **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 (/Users/salo/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/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 resortIf there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.@@ -1536,8 +1536,8 @@ module.exports = {## APIThis 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 /Users/salo/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md further documentation on the full syntax+1. Check the examples in the ~/pinokio/prototype/system/examples folder+2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax### Script API@@ -1666,7 +1666,7 @@ logs/- 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 `/Users/salo/pinokio/api/phosphene.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.+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.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.@@ -1692,12 +1692,12 @@ logs/- 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 /Users/salo/pinokio/prototype/system/examples folder to see how these are being used.+ - Check the examples in the ~/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 `/Users/salo/pinokio/api/phosphene.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.+- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.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. Retrofitting an already-working setup- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.@@ -1714,7 +1714,7 @@ logs/### 12. 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 `/Users/salo/pinokio/api/phosphene.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`.+ - If the git repository for the `~/pinokio/api/phosphene.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`.### 13. 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@@ -1783,9 +1783,9 @@ The `torch.js` script also includes ways to install pytorch dependent libraries## Quick Reference### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at /Users/salo/pinokio/prototype/PTERM.md+- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section+- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section+- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md### Common Patterns- **Python Virtual Env:** `shell.run` with `venv` attribute- **Cross-platform Commands:** Always test on multiple platformsdiff --git a/CLAUDE.md b/CLAUDE.mdindex e26639a..2b0c6c9 100644--- a/CLAUDE.md+++ b/CLAUDE.md@@ -91,11 +91,11 @@ in 8 m 07 s. That's the recommended default for "fast HD with audio".### Repository layout (now — both clones documented)-`/Users/salo/pinokio/api/phosphene.git/` is the **production** clone.+`~/pinokio/api/phosphene.git/` is the **production** clone.Tracks `main`. Pinokio's daily-driver Phosphene panel runs from here onport 8198.-`/Users/salo/pinokio/api/phosphene-dev.git/` is the **dev** clone.+`~/pinokio/api/phosphene-dev.git/` is the **dev** clone.Tracks `dev`. Set up via `scripts/setup_dev_panel.sh`. Runs on port 8199with the amber `DEV` profile badge in the header. Symlinks`mlx_models/`, `mlx_outputs/`, `panel_uploads/`, and `state/` from a@@ -127,7 +127,7 @@ The panel itself is MIT. Model weights have Lightricks' own license.separate dev folder. Old "local dev" copy was deleted to consolidate.```-/Users/salo/pinokio/api/phosphene.git/ ← edit here+~/pinokio/api/phosphene.git/ ← edit here├── .git/ ← real working copy of mrbizarro/phosphene├── ltx-2-mlx/ ← upstream package, cloned at install│ ├── env/ ← Python 3.11 venv@@ -147,7 +147,7 @@ separate dev folder. Old "local dev" copy was deleted to consolidate.└── required_files.json ← single source of truth for "installed"```-To work: `cd /Users/salo/pinokio/api/phosphene.git/`, edit, `git commit`,+To work: `cd ~/pinokio/api/phosphene.git/`, edit, `git commit`,`git push`. Pinokio's Update button does `git pull` here. No separatecopy to keep in sync.@@ -427,7 +427,7 @@ that already pulled 0.31.2 can recover by clicking Update.and click Start.### Disk consolidation-- Old `/Users/salo/Documents/Codex/...` dev folder was deleted.+- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.- `~/.cache/huggingface/hub/models--*` was also deleted. Pinokioinstall pulls weights into `mlx_models/` directly via `hf@@ -1285,8 +1285,8 @@ precedence on conflict.)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. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `/Users/salo/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.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.+3. **Example Lock-in:** Identify the closest matching script in `~/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.+4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.5. **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.6. **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.@@ -1319,9 +1319,9 @@ on: [{Deviation from this pattern requires written approval from the user.-- Make sure to keep this entire document and `PINOKIO.md` at /Users/salo/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 /Users/salo/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 /Users/salo/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.+- Make sure to keep this entire document and `PINOKIO.md` at ~/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 ~/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 ~/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.@@ -1415,7 +1415,7 @@ project-root/└── pinokio.json # Metadata (title, description, icon)```-IMPORTANT: ALWAYS try to follow the best practices in the examples folder (/Users/salo/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/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@@ -1467,7 +1467,7 @@ If we are starting with existing launcher script files, work with the existing f- **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 (/Users/salo/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/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 resortIf there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.@@ -1572,8 +1572,8 @@ module.exports = {## APIThis 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 /Users/salo/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md further documentation on the full syntax+1. Check the examples in the ~/pinokio/prototype/system/examples folder+2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax### Script API@@ -1702,7 +1702,7 @@ logs/- 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 `/Users/salo/pinokio/api/phosphene.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.+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.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.@@ -1728,12 +1728,12 @@ logs/- 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 /Users/salo/pinokio/prototype/system/examples folder to see how these are being used.+ - Check the examples in the ~/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 `/Users/salo/pinokio/api/phosphene.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.+- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.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. Retrofitting an already-working setup- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.@@ -1750,7 +1750,7 @@ logs/### 12. 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 `/Users/salo/pinokio/api/phosphene.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`.+ - If the git repository for the `~/pinokio/api/phosphene.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`.### 13. 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@@ -1819,9 +1819,9 @@ The `torch.js` script also includes ways to install pytorch dependent libraries## Quick Reference### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at /Users/salo/pinokio/prototype/PTERM.md+- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section+- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section+- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md### Common Patterns- **Python Virtual Env:** `shell.run` with `venv` attribute- **Cross-platform Commands:** Always test on multiple platformsdiff --git a/GEMINI.md b/GEMINI.mdindex 19eacc3..af1a878 100644--- a/GEMINI.md+++ b/GEMINI.md@@ -91,11 +91,11 @@ in 8 m 07 s. That's the recommended default for "fast HD with audio".### Repository layout (now — both clones documented)-`/Users/salo/pinokio/api/phosphene.git/` is the **production** clone.+`~/pinokio/api/phosphene.git/` is the **production** clone.Tracks `main`. Pinokio's daily-driver Phosphene panel runs from here onport 8198.-`/Users/salo/pinokio/api/phosphene-dev.git/` is the **dev** clone.+`~/pinokio/api/phosphene-dev.git/` is the **dev** clone.Tracks `dev`. Set up via `scripts/setup_dev_panel.sh`. Runs on port 8199with the amber `DEV` profile badge in the header. Symlinks`mlx_models/`, `mlx_outputs/`, `panel_uploads/`, and `state/` from a@@ -127,7 +127,7 @@ The panel itself is MIT. Model weights have Lightricks' own license.separate dev folder. Old "local dev" copy was deleted to consolidate.```-/Users/salo/pinokio/api/phosphene.git/ ← edit here+~/pinokio/api/phosphene.git/ ← edit here├── .git/ ← real working copy of mrbizarro/phosphene├── ltx-2-mlx/ ← upstream package, cloned at install│ ├── env/ ← Python 3.11 venv@@ -147,7 +147,7 @@ separate dev folder. Old "local dev" copy was deleted to consolidate.└── required_files.json ← single source of truth for "installed"```-To work: `cd /Users/salo/pinokio/api/phosphene.git/`, edit, `git commit`,+To work: `cd ~/pinokio/api/phosphene.git/`, edit, `git commit`,`git push`. Pinokio's Update button does `git pull` here. No separatecopy to keep in sync.@@ -427,7 +427,7 @@ that already pulled 0.31.2 can recover by clicking Update.and click Start.### Disk consolidation-- Old `/Users/salo/Documents/Codex/...` dev folder was deleted.+- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.- `~/.cache/huggingface/hub/models--*` was also deleted. Pinokioinstall pulls weights into `mlx_models/` directly via `hf@@ -1249,8 +1249,8 @@ precedence on conflict.)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. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `/Users/salo/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.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.+3. **Example Lock-in:** Identify the closest matching script in `~/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.+4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.5. **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.6. **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.@@ -1283,9 +1283,9 @@ on: [{Deviation from this pattern requires written approval from the user.-- Make sure to keep this entire document and `PINOKIO.md` at /Users/salo/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 /Users/salo/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 /Users/salo/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.+- Make sure to keep this entire document and `PINOKIO.md` at ~/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 ~/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 ~/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.@@ -1379,7 +1379,7 @@ project-root/└── pinokio.json # Metadata (title, description, icon)```-IMPORTANT: ALWAYS try to follow the best practices in the examples folder (/Users/salo/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/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@@ -1431,7 +1431,7 @@ If we are starting with existing launcher script files, work with the existing f- **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 (/Users/salo/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/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 resortIf there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.@@ -1536,8 +1536,8 @@ module.exports = {## APIThis 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 /Users/salo/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md further documentation on the full syntax+1. Check the examples in the ~/pinokio/prototype/system/examples folder+2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax### Script API@@ -1666,7 +1666,7 @@ logs/- 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 `/Users/salo/pinokio/api/phosphene.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.+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.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.@@ -1692,12 +1692,12 @@ logs/- 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 /Users/salo/pinokio/prototype/system/examples folder to see how these are being used.+ - Check the examples in the ~/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 `/Users/salo/pinokio/api/phosphene.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.+- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.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. Retrofitting an already-working setup- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.@@ -1714,7 +1714,7 @@ logs/### 12. 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 `/Users/salo/pinokio/api/phosphene.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`.+ - If the git repository for the `~/pinokio/api/phosphene.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`.### 13. 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@@ -1783,9 +1783,9 @@ The `torch.js` script also includes ways to install pytorch dependent libraries## Quick Reference### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at /Users/salo/pinokio/prototype/PTERM.md+- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section+- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section+- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md### Common Patterns- **Python Virtual Env:** `shell.run` with `venv` attribute- **Cross-platform Commands:** Always test on multiple platformsdiff --git a/QWEN.md b/QWEN.mdindex 19eacc3..af1a878 100644--- a/QWEN.md+++ b/QWEN.md@@ -91,11 +91,11 @@ in 8 m 07 s. That's the recommended default for "fast HD with audio".### Repository layout (now — both clones documented)-`/Users/salo/pinokio/api/phosphene.git/` is the **production** clone.+`~/pinokio/api/phosphene.git/` is the **production** clone.Tracks `main`. Pinokio's daily-driver Phosphene panel runs from here onport 8198.-`/Users/salo/pinokio/api/phosphene-dev.git/` is the **dev** clone.+`~/pinokio/api/phosphene-dev.git/` is the **dev** clone.Tracks `dev`. Set up via `scripts/setup_dev_panel.sh`. Runs on port 8199with the amber `DEV` profile badge in the header. Symlinks`mlx_models/`, `mlx_outputs/`, `panel_uploads/`, and `state/` from a@@ -127,7 +127,7 @@ The panel itself is MIT. Model weights have Lightricks' own license.separate dev folder. Old "local dev" copy was deleted to consolidate.```-/Users/salo/pinokio/api/phosphene.git/ ← edit here+~/pinokio/api/phosphene.git/ ← edit here├── .git/ ← real working copy of mrbizarro/phosphene├── ltx-2-mlx/ ← upstream package, cloned at install│ ├── env/ ← Python 3.11 venv@@ -147,7 +147,7 @@ separate dev folder. Old "local dev" copy was deleted to consolidate.└── required_files.json ← single source of truth for "installed"```-To work: `cd /Users/salo/pinokio/api/phosphene.git/`, edit, `git commit`,+To work: `cd ~/pinokio/api/phosphene.git/`, edit, `git commit`,`git push`. Pinokio's Update button does `git pull` here. No separatecopy to keep in sync.@@ -427,7 +427,7 @@ that already pulled 0.31.2 can recover by clicking Update.and click Start.### Disk consolidation-- Old `/Users/salo/Documents/Codex/...` dev folder was deleted.+- Old `~/Documents/Codex/...` dev folder was deleted.Don't recreate. The Pinokio install is canonical.- `~/.cache/huggingface/hub/models--*` was also deleted. Pinokioinstall pulls weights into `mlx_models/` directly via `hf@@ -1249,8 +1249,8 @@ precedence on conflict.)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. **Destination Resolution:** Before creating or editing any Pinokio launcher files, resolve `PINOKIO_HOME` to an absolute path and record the intended destination root. If running outside Pinokio's own managed runtime, resolve in this order: `~/.pinokio/config.json` `home`, then `GET http://127.0.0.1:42000/pinokio/home` and use its `path` value, and if loopback is unreachable but `access` exists in `~/.pinokio/config.json`, retry the same request against `<protocol>://<host>:<port>/pinokio/home`, then the `PINOKIO_HOME` environment variable. If `PINOKIO_HOME` is still unresolved, stop and ask the user. Never silently use the current workspace as the launcher destination.-3. **Example Lock-in:** Identify the closest matching script in `/Users/salo/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.-4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.+3. **Example Lock-in:** Identify the closest matching script in `~/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.+4. **Pre-flight Checklist:** Convert the applicable rules from this document and `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md into a task-specific checklist (install/start/reset/update structure, regex patterns, menu defaults, log checks, destination path, etc.). Confirm each item is ticked **before** making changes.5. **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.6. **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.@@ -1283,9 +1283,9 @@ on: [{Deviation from this pattern requires written approval from the user.-- Make sure to keep this entire document and `PINOKIO.md` at /Users/salo/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 /Users/salo/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 /Users/salo/pinokio/prototype/PINOKIO.md to use the correct syntax instead of assuming the syntax.+- Make sure to keep this entire document and `PINOKIO.md` at ~/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 ~/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 ~/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.@@ -1379,7 +1379,7 @@ project-root/└── pinokio.json # Metadata (title, description, icon)```-IMPORTANT: ALWAYS try to follow the best practices in the examples folder (/Users/salo/pinokio/prototype/system/examples) instead of trying to come up with your own structure. The examples have been optimized for the best user experience.+IMPORTANT: ALWAYS try to follow the best practices in the examples folder (~/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@@ -1431,7 +1431,7 @@ If we are starting with existing launcher script files, work with the existing f- **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 (/Users/salo/pinokio/prototype/system/examples) to see if you can adopt them instead of coming up everything from scratch.+- If starting from scratch, first determine what type of project you will be building, and then check the examples folder (~/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 resortIf there are relevant examples to adopt from, write the scripts from scratch, but just make sure to follow the requirements in the next section.@@ -1536,8 +1536,8 @@ module.exports = {## APIThis 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 /Users/salo/pinokio/prototype/system/examples folder-2. Read the `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md further documentation on the full syntax+1. Check the examples in the ~/pinokio/prototype/system/examples folder+2. Read the `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md further documentation on the full syntax### Script API@@ -1666,7 +1666,7 @@ logs/- 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 `/Users/salo/pinokio/api/phosphene.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.+- When building launchers for existing projects cloned from a repository, try to stay away from modifying the project folder (the `~/pinokio/api/phosphene.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.@@ -1692,12 +1692,12 @@ logs/- 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 /Users/salo/pinokio/prototype/system/examples folder to see how these are being used.+ - Check the examples in the ~/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 `/Users/salo/pinokio/api/phosphene.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.+- In most cases, the `README.md` file in the `~/pinokio/api/phosphene.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. Retrofitting an already-working setup- Sometimes the user starts outside Pinokio, gets an app working through ad-hoc commands, and only later asks to turn that work into a Pinokio launcher.@@ -1714,7 +1714,7 @@ logs/### 12. 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 `/Users/salo/pinokio/api/phosphene.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`.+ - If the git repository for the `~/pinokio/api/phosphene.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`.### 13. 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@@ -1783,9 +1783,9 @@ The `torch.js` script also includes ways to install pytorch dependent libraries## Quick Reference### Essential Documentation-- **Pinokio Programming:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section-- **Dynamic Menus:** See `PINOKIO.md` at /Users/salo/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section-- **CLI Commands:** See `PTERM.md` at /Users/salo/pinokio/prototype/PTERM.md+- **Pinokio Programming:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Programming Pinokio" section+- **Dynamic Menus:** See `PINOKIO.md` at ~/pinokio/prototype/PINOKIO.md → "Dynamic menu rendering" section+- **CLI Commands:** See `PTERM.md` at ~/pinokio/prototype/PTERM.md### Common Patterns- **Python Virtual Env:** `shell.run` with `venv` attribute- **Cross-platform Commands:** Always test on multiple platformsdiff --git a/README.md b/README.mdindex 9dcfe77..dc4c65c 100644--- a/README.md+++ b/README.md@@ -3,8 +3,8 @@</p><p align="center">- <strong>Local generative video, image, and character training for Apple Silicon.</strong><br>- Native MLX. One-click install via <a href="https://pinokio.computer">Pinokio</a>. No cloud, no API key.<br>+ <strong>Generative video, image, and character training on your Mac.</strong><br>+ MLX. No PyTorch, no CUDA, no cloud, no API key.<br><a href="https://x.com/PhospheneAI">@PhospheneAI</a> on X · <a href="https://github.com/mrbizarro/phosphene">github.com/mrbizarro/phosphene</a></p>@@ -12,101 +12,110 @@<img src="assets/screenshots/phos_01_video_tab.png" alt="Phosphene panel — Video tab" width="100%"></p>----+## You can train a character on your laptop now-## Phosphene 3.0+Drop 15 to 50 photos of a face into the Train tab. Click Train. Walk away. About three hours later you have a character LoRA, with optional voice, both ready to use from the Video tab. The captions are written by a local Gemma 3. Nothing leaves the machine.-3.0 is a new panel. Same single-window feel, but the surface is rebuilt-around three workflows and a hardware-aware capability tier — so a 32 GB-Mac sees a clean Q4 panel, and a 64 GB+ Mac sees the full thing.+This is the part of Phosphene 3.0 I keep showing people first, because it's still the thing nobody believes works until they watch a clip render. A 7-second 1024x576 character clip lands in about six minutes on an M4 Max.-**Headline ships**+The panel adapts to your Mac. Under 48 GB? You get a simple surface with Q4 video and the image tab. 64 GB or more? Character training, first/last-frame keyframing, extend, and the Q8 HQ modes all show up. There is one repo and two clean surfaces. You don't have to know which one you're on.-- **Image Studio** is its own workflow. HiDream-O1-Image-Dev, Qwen-Image-Edit-2511, and the FLUX / Klein family. All native MLX. Multi-reference subject composition. Adaptive wall-time estimates that learn per-engine on your rig.-- **Train Character** is in the panel. Drop 30–80 photos, click Train, walk away. Local Gemma 3 12B auto-captioner. Optional voice LoRA from a short clip. Letterbox-crop strategy preserves wide-shot proportions. ~3 hours for a face LoRA on M4 Max 64 GB.-- **Character mode** is promoted from a buried chip to a first-class mode pill. Compact avatar picker at the top of the form, click to switch, voice / silent indicators, Manage Characters modal for rename + delete.-- **Q8 HQ is the default character-quality path.** A 7-second character clip at 1024×576 lands in ~6 minutes on M4 Max — down from ~12+ min in 2.0 — thanks to the capability-tier refactor + Codex's skip-step optimization. Server-side guardrails refuse character + Q4 so identity can't silently degrade.-- **Capability tier system.** `body[data-cap-tier="q4|q8"]` is set at boot from detected RAM. Q4 panel hides Q8-only intents (HQ, FFLF, Extend, Character). Q8 panel shows the full surface. One repo, two clean surfaces.-- **TeaCache in Extend** (today). Plus the mflux image-gen path fix, mflux binary path resolver fix, and the Q8-HQ boot-cascade fix that kept the Fast pill from firing on first render.+## What's actually in there-**Major behind-the-scenes**+**Video.** Text-to-video, image-to-video, and audio-to-video. Every clip comes back with synced audio in the same diffusion pass: lip-sync, footsteps, room tone, whatever the prompt described. First/last-frame keyframing and clip extension are there on the Q8 surface.-- Workflow tabs renamed and reordered: **Video / Images / Train Character**. Phone-icon orientation picker. Multi-subject prompt coaching when 2+ references are loaded. Vertical-player chrome moved outside the right edge so it stops covering 9:16 clips. Voice opt-out toggle for character generation. Improved Load Params (restores Character mode + actual seed used, not the -1 sentinel).-- Boot-time HQ skip-step bug fixed. HF cache fallback hardened. Train preflight finds the dev transformer in either q4 or q8 dirs. Server-side validation for character + quality combinations.+**Images.** Two engines on the same tab. Qwen-Image-Edit-2511 for instruction edits and multi-subject composition. HiDream-O1-Image-Dev for photoreal at HD (separate one-time clone — see Setup below). Both are MLX ports, so they share GPU memory cleanly when you switch between them. Cards drop into a unified gallery, and there's an Animate button on each one that pre-fills the I2V form.-If you came from 2.0: **Stop · Update · Start** in Pinokio. Your renders, settings, queue, models, and LoRAs all survive (Pinokio's `fs.link` persistent drive). Update can take a few minutes the first time.+**Train Character.** A full LoRA training pipeline inside the panel. Face plus optional voice from the same dataset. Letterbox crop preserves wide-shot proportions, which used to be the silent killer of identity capture. Auto-captioning runs Gemma 3 12B on-device in about ninety seconds for 37 images. The validated default (rank 32, alpha 32, 5000 steps) is the preset, and it is load-bearing. Every time I tuned it I made it worse.----+**Audio-to-Video.** New as of today. Drop a WAV or MP3, optionally drop a reference image to anchor frame zero, hit Generate. The audio drives the video. Two-stage pipeline: low-res with CFG, then full-res with the distilled LoRA fused on top. Original input audio is muxed onto the result.-## What Phosphene does--- **Video** — text → video, image → video, first/last-frame keyframing, extend an existing clip. Every clip ships with synced audio in one diffusion pass (lip-sync, footsteps, ambient bed).-- **Character** — generate with a trained face LoRA. Optional voice LoRA stacks automatically. Q8 HQ path, ~6 min for a 7 s 1024×576 clip on M4 Max.-- **Image Studio** — HiDream-O1-Image-Dev (BF16), Qwen-Image-Edit-2511 (Q6/Q8 via mflux), FLUX.1 family. Single-shot or multi-reference subject composition. Edit by instruction ("change the white jacket to red") preserves scene + identity.-- **Train Character** — in-panel LoRA training pipeline. Face LoRA + optional voice LoRA from one dataset. Gemma 3 12B auto-captions on-device.-- **LoRAs and CivitAI** — drop `.safetensors` in `mlx_models/loras/`, or browse and install CivitAI LTX 2.3 LoRAs from the panel. Per-row rename, download, and companion-aware delete.--Hardware tier auto-detected at boot. The panel shows you what's available; what isn't is hidden, not greyed out.-----+**LoRAs and CivitAI.** Drop `.safetensors` into `mlx_models/loras/`, or browse and install LTX 2.3 LoRAs from CivitAI inside the panel. Rename, download, and delete from each row.## Hardware-Apple Silicon only. MLX is Apple-only by design — no Intel, no Linux, no Windows.+Apple Silicon only. MLX is Apple-only by design.| RAM | Tier | What runs ||---|---|---|-| **Under 48 GB** | Compact (Q4 surface) | Text / Image video at smaller sizes (≤ 768 px long side). Image Studio works. Character / FFLF / Extend / HQ hidden — they need Q8. |-| **48–79 GB** | Comfortable (Q8 surface) | The canonical tier — built on M4 Max 64 GB. Every mode works. FFLF / Extend capped at 768 px. |-| **80–119 GB** | Roomy | Most modes at full size. FFLF / Extend up to 1024 px. |-| **120 GB+** | Studio | No size limits. |--LTX 2.3's working memory is real — there's no shortcut. Standard 1280×704 generation peaks ~22 GiB resident; HQ with the Q8 dev transformer is closer to 38 GiB. The tier system enforces this honestly instead of letting jobs fall out of the OOM killer.--Use `LTX_FORCE_CAP_TIER=q4` to view the Q4 surface from a Q8 machine (useful for testing or just to see what the entry-level panel looks like).+| Under 48 GB | Compact (Q4 surface) | Text and image-to-video at smaller sizes. Image tab works. Character, FFLF, Extend, and HQ are hidden. They need Q8. |+| 48 to 79 GB | Comfortable (Q8 surface) | The canonical tier, built on M4 Max 64 GB. Everything works. FFLF and Extend capped at 768 px long side. |+| 80 to 119 GB | Roomy | Most modes at full size. FFLF and Extend up to 1024 px. |+| 120 GB+ | Studio | No size limits. |----+LTX 2.3's working memory is real. Standard 1280x704 generation peaks around 22 GiB resident. HQ with the Q8 dev transformer is closer to 38 GiB. Tier detection is at boot, from `body[data-cap-tier="q4|q8"]`, and the panel hides things rather than greying them out. If you want to see what the Q4 surface looks like from a 64 GB machine, set `LTX_FORCE_CAP_TIER=q4`.## Install### Via Pinokio (recommended)1. Install [Pinokio](https://pinokio.computer).-2. In Pinokio: **Discover → Download from URL** → paste `https://github.com/mrbizarro/phosphene`.+2. In Pinokio: **Discover** -> **Download from URL** -> paste `https://github.com/mrbizarro/phosphene`.3. Click **Install**.-4. Click **Start** → **Open Panel** → http://127.0.0.1:8198.+4. Click **Start** -> **Open Panel** -> http://127.0.0.1:8198.-Pinokio handles the rest: Apple Silicon hardware gate, the upstream `dgrauet/ltx-2-mlx` clone, the uv-managed Python 3.11 venv, the codec + memory patches, and the filtered model download (~28 GB: Q4 + Gemma encoder).+Pinokio handles the hardware gate, the upstream `dgrauet/ltx-2-mlx` clone, the uv-managed Python 3.11 venv, the runtime patches, and the filtered model download (~28 GB: Q4 plus the Gemma encoder).-<!-- Pinokio install screenshot can land here once we record one. -->+For the Q8 HQ tier (required for Character, FFLF, Extend), click **Download Q8** in the panel sidebar after first launch. About 37 GB, one time.-For the Q8 HQ tier (required for Character, FFLF, Extend), click **Download Q8** in the panel sidebar after first launch (~37 GB, one-time).--For ~10× faster downloads, open **⚙ Settings** in the panel and paste a Hugging Face token. The same token unlocks gated LoRAs (HDR + Lightricks Control LoRAs).+If you have a Hugging Face token, paste it under **Settings** in the panel. Downloads run roughly 10x faster, and the same token unlocks the gated LoRAs (HDR and Lightricks Control).### Manual install```bash+# 1. Clone Phosphene + the upstream MLX port (pinned to v0.14.0).git clone https://github.com/mrbizarro/phosphene.gitcd phosphenegit clone https://github.com/dgrauet/ltx-2-mlx.git ltx-2-mlx+cd ltx-2-mlx && git checkout v0.14.0 && cd ..++# 2. Create the Python 3.11 venv inside ltx-2-mlx (uv-managed).cd ltx-2-mlxuv venv --python 3.11 --seed env-./env/bin/pip install ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx-./env/bin/pip install pillow numpy 'huggingface-hub>=1.0' \++# 3. Install the MLX pipeline + trainer packages. Pin mlx to 0.31.1 —+# 0.31.2 attenuates the LTX vocoder by 22 dB.+./env/bin/uv pip install --python env/bin/python \'mlx==0.31.1' 'mlx-lm==0.31.1' 'mlx-metal==0.31.1'+./env/bin/uv pip install --python env/bin/python \+ ./packages/ltx-core-mlx ./packages/ltx-pipelines-mlx ./packages/ltx-trainer+./env/bin/uv pip install --python env/bin/python \+ pyyaml pydantic tqdm rich+# mlx-vlm powers Gemma 3 auto-caption. --no-deps so it doesn't drag mlx-lm past 0.31.1.+./env/bin/uv pip install --python env/bin/python --no-deps 'mlx-vlm==0.4.4'+# Agent + downloader + hub pin range.+./env/bin/pip install pillow numpy 'huggingface-hub>=1.5.0,<2.0' \+ 'hf_transfer>=0.1.6' 'litellm>=1.83.14' 'smolagents>=1.24.0'cd ..++# 4. Apply the runtime patches (idempotent, fail loud on upstream drift)../ltx-2-mlx/env/bin/python3.11 patch_ltx_codec.py++# 5. Download the Q4 LTX weights + the Gemma 3 4-bit encoder (~28 GB total).+HF_HUB_ENABLE_HF_TRANSFER=1 ./ltx-2-mlx/env/bin/hf download \+ dgrauet/ltx-2.3-mlx-q4 --local-dir mlx_models/ltx-2.3-mlx-q4+HF_HUB_ENABLE_HF_TRANSFER=1 ./ltx-2-mlx/env/bin/hf download \+ mlx-community/gemma-3-12b-it-4bit --local-dir mlx_models/gemma-3-12b-it-4bit++# 6. (Optional) Image tab — install mflux + apply the FBCache patch.+./ltx-2-mlx/env/bin/pip install 'mflux==0.17.5'+./ltx-2-mlx/env/bin/pip install --force-reinstall --no-deps 'mflux==0.17.5'+./ltx-2-mlx/env/bin/python3.11 patch_mflux_fbcache.py++# 7. (Optional) HiDream — separate one-time clone for the photoreal engine.+# Clone HIDREAM-O1-MLX-LAB-active into your home directory, or set+# HIDREAM_LAB_DIR to point at it.+# git clone <hidream-lab-repo> ~/HIDREAM-O1-MLX-LAB-active++# 8. Launch the panel../ltx-2-mlx/env/bin/python3.11 mlx_ltx_panel.py```-> **Why the version pins?** `mlx 0.31.2` attenuates the LTX vocoder by ~22 dB. Stay on 0.31.1.+About the version pins: `mlx 0.31.2` attenuates the LTX vocoder by 22 dB. Stay on 0.31.1. `ltx-2-mlx` is pinned to `v0.14.0` — upstream is about to ship breaking changes. `mflux 0.17.5` is the version `patch_mflux_fbcache.py` is line-targeted against.----+## Using it-## Quick start--Pick a workflow at the top: **Video**, **Images**, **Audio**, or **Train Character**. Each one is a single page.+There are four workflow tabs at the top: **Video**, **Images**, **Audio**, **Train Character**. Each one is a single page.<table><tr>@@ -114,102 +123,76 @@ Pick a workflow at the top: **Video**, **Images**, **Audio**, or **Train Charact<td width="50%"><img src="assets/screenshots/phos_02_images_tab.png" alt="Images tab — multi-reference subject composition"></td></tr><tr>-<td align="center"><sub><b>Video / Character mode</b> — round-avatar picker, voice indicator, manage modal</sub></td>-<td align="center"><sub><b>Images</b> — Qwen Edit / HiDream-O1 / FLUX, multi-ref subject composition</sub></td>+<td align="center"><sub><b>Video / Character mode</b> · round-avatar picker, voice indicator, manage modal</sub></td>+<td align="center"><sub><b>Images</b> · Qwen Edit, HiDream-O1, multi-ref composition</sub></td></tr><tr><td width="50%"><img src="assets/screenshots/phos_03_audio_tab.png" alt="Audio tab — audio drives the generation"></td><td width="50%"><img src="assets/screenshots/phos_04_train_tab.png" alt="Train Character tab — dataset + auto-caption + voice LoRA"></td></tr><tr>-<td align="center"><sub><b>Audio</b> — voice or music clip drives generation; optional reference image anchors frame 0</sub></td>-<td align="center"><sub><b>Train Character</b> — drop 30–80 photos, Gemma 3 auto-captions, optional voice LoRA</sub></td>+<td align="center"><sub><b>Audio</b> · voice or music clip drives generation; optional reference image anchors frame 0</sub></td>+<td align="center"><sub><b>Train Character</b> · drop 15-50 photos, Gemma 3 auto-captions, optional voice LoRA</sub></td></tr></table>+A few things worth knowing as you go:-**Text → video**-1. Video tab → **Text** mode pill.-2. Type a prompt. Describe the soundscape the same way you describe the scene.-3. Pick a Quality pill (Quick / Balanced / Standard / High).-4. Generate.--**Image → video**-1. Video tab → **Image** mode pill.-2. Drop a reference image. The panel covers and crops to model dims for you.-3. Prompt with explicit motion beats (not the still-image description). ~1 beat per 2–3 seconds of clip.-4. Generate.+- **Video, text mode.** Describe the soundscape the same way you describe the scene. The audio generation reads your prompt.+- **Video, image mode.** Prompt with motion beats, not the still-image description. About one beat per two to three seconds of clip.+- **Video, character mode.** Pick an avatar, include your trigger word in the prompt. Q8 Draft (736x416) for iteration, Q8 Pro (1024x576) for final.+- **Images.** Drop one to three references for edit or multi-ref work. Empty zone is text-only. Qwen-Image-Edit handles instructions like "change the white jacket to red" while preserving the rest of the scene.+- **Train Character.** Center crop is for tight portraits. Letterbox is for wide-shot proportions. The rank-32, alpha-32, 5000-step preset is the one I'd start with.-**Character (trained face + voice)**-1. Video tab → **Character** mode pill.-2. Pick an avatar from the chip strip at the top of the form.-3. Type a prompt that includes your character's trigger word.-4. Q8 Draft (736×416) for fast iteration, Q8 Pro (1024×576) for final.-5. Generate. ~6 min for a 7 s clip on M4 Max.+## Migrating from 2.0-**Image Studio**-1. **Images** tab.-2. Pick an engine. HiDream-O1 (Fast / Medium / Quality) for photoreal at HD. Qwen-Image-Edit-2511 for instruction edits and subject composition.-3. Drop 1–3 reference images for edit / multi-ref work, or leave empty for text-only.-4. Generate. Cards land in the unified Outputs gallery — click **Animate** on a card to pre-fill the I2V form.+Quit Pinokio (or the panel terminal), then **Update**, then **Start**. Renders, settings, queue, models, and LoRAs all survive (Pinokio's `fs.link` persistent drive). The first update can take a few minutes.-**Train Character**-1. **Train Character** tab.-2. Drop 30–80 photos of one person. Optional: drop a short voice clip (15–60s of clean speech).-3. Pick a crop strategy: **Center crop** for tight portraits, **Letterbox** for wide-shot proportions.-4. Click **Auto-caption** (Gemma 3 runs locally, ~90 s for 37 images), or write captions yourself.-5. Pick a preset (rank 32, alpha 32, 5000 steps is the validated default).-6. **Train**. ~3 hours for a face LoRA on M4 Max 64 GB. The avatar shows up under Character mode when it's done.+> **If you came from 2.0 and Train Character or auto-caption look broken after the first Update, click Update once more.** The first run uses the old 2.0 update script that already sits on your disk; only after that does the new 3.0 script land. Running Update a second time installs the trainer and mlx-vlm packages 3.0 added.----+A few other things worth knowing about 3.0:-## Architecture notes+- Character is its own mode pill on Video now, not a buried chip.+- Q8 HQ is the default for character clips. The server refuses Q4 with a character selected, so identity can't silently degrade.+- TeaCache is wired through Extend and A2V stage 1.+- Vertical-player chrome lives outside the right edge, so 9:16 clips aren't covered.-- **`mlx_ltx_panel.py`** — the panel HTTP server. Single file (~22 k lines). HTML + CSS + JS inlined as the page string. Worker thread + helper subprocess management. Capability tier detection.-- **`mlx_warm_helper.py`** — long-running inference subprocess. Holds T2V / I2V / Extend / HQ / Keyframe pipelines from `ltx_pipelines_mlx`. Reads job specs from stdin, emits events to stdout.-- **`image_engine.py`** — Image Studio dispatch. Backends: `hidream`, `mflux`, `mock`. Each engine spawns its own subprocess with `start_new_session=True` so `/stop` can kill the whole tree.-- **`patch_ltx_codec.py`** — idempotent runtime patches against the installed upstream. Codec → lossless H.264, free-DiT-before-decode, VAE temporal streaming for long clips.-- **`lora_lab/`** — vendored from the [`lora-lab`](https://github.com/mrbizarro/lora-lab) authoring tree. In-panel character LoRA training works out of the box for installer-only users. Set `LTX_LORA_LAB_ROOT` to iterate against an external clone.-- **`mlx_models/`** — weights (~63 GB, fs.link symlink). Persists across Pinokio Reset.-- **`mlx_outputs/`** — rendered mp4s + sidecar JSON. Persists across Reset.+## What's in the repo-**MLX ports (Mr Bizarro's own work):**-- **HiDream-O1-Image-Dev BF16** — published to [`mlx-community/HiDream-O1-Image-Dev-mlx-bf16`](https://huggingface.co/mlx-community/HiDream-O1-Image-Dev-mlx-bf16). 8B Qwen3-VL backbone, unified pixel-patch transformer (no VAE). MIT. Native edit + multi-reference at 1024 / 1440 / 2048 trained dims.-- **Qwen-Image-Edit-2511** — runs via mflux (Q6 / Q8). Instruction edit + multi-subject composition.+- `mlx_ltx_panel.py` is the panel HTTP server. One file, around 22k lines, with HTML, CSS, and JS inlined as the page string. Worker thread plus helper subprocess management plus capability tier detection.+- `mlx_warm_helper.py` is the long-running inference subprocess. Holds T2V, I2V, Extend, HQ, and Keyframe pipelines. Reads job specs from stdin, emits events to stdout.+- `image_engine.py` dispatches the Image tab. Backends `hidream`, `mflux`, `mock`. Each spawns its own subprocess with `start_new_session=True` so `/stop` kills the whole tree.+- `patch_ltx_codec.py` applies idempotent runtime patches: lossless H.264, free-DiT-before-decode, VAE temporal streaming for long clips.+- `lora_lab/` is vendored from the [`lora-lab`](https://github.com/mrbizarro/lora-lab) authoring tree. Training works out of the box; set `LTX_LORA_LAB_ROOT` to iterate against an external clone.+- `mlx_models/` and `mlx_outputs/` both persist across Pinokio Reset via fs.link.----+I also ported [HiDream-O1-Image-Dev BF16](https://huggingface.co/mlx-community/HiDream-O1-Image-Dev-mlx-bf16) (8B Qwen3-VL backbone, unified pixel-patch transformer, MIT) for the Images tab. HiDream is a separate one-time clone (see Setup below).-## License + credits+## License and credits-**Panel:** MIT — see [LICENSE](LICENSE).-**LTX Video 2.3 weights:** Lightricks' own license.-**MLX:** Apache 2.0. **Gemma 3 12B:** Google's terms. **PiperSR:** AGPL-3.0 (model usage requires ModelPiper attribution).+Panel: MIT, see [LICENSE](LICENSE). LTX Video 2.3 weights: Lightricks' license. MLX: Apache 2.0. Gemma 3 12B: Google's terms. PiperSR: AGPL-3.0.-Phosphene is a wrapper over good model work. Credits to:+Phosphene is a wrapper over good model work. The names that matter:-- **[Lightricks](https://github.com/Lightricks/LTX-Video)** — LTX 2.3, weights, joint audio + video architecture-- **[@dgrauet](https://github.com/dgrauet/ltx-2-mlx)** — the MLX port. The reason LTX runs on Apple Silicon.-- **[Apple ML team](https://github.com/ml-explore/mlx)** — MLX-- **[HiDream-ai](https://huggingface.co/HiDream-ai/HiDream-O1-Image-Dev)** — HiDream-O1 weights + reference implementation-- **[filipstrand/mflux](https://github.com/filipstrand/mflux)** — MLX-native FLUX / Qwen-Edit family-- **[mlx-community](https://huggingface.co/mlx-community)** — Gemma 3 12B 4-bit-- **[ModelPiper / PiperSR](https://github.com/ModelPiper/PiperSR)** — optional Sharp 2× upscale on the Apple Neural Engine-- **[@cocktailpeanut](https://twitter.com/cocktailpeanut)** — Pinokio+- [Lightricks](https://github.com/Lightricks/LTX-Video) for LTX 2.3 and the joint audio-plus-video architecture+- [@dgrauet](https://github.com/dgrauet/ltx-2-mlx) for the MLX port. The reason any of this runs on Apple Silicon.+- [Apple ML team](https://github.com/ml-explore/mlx) for MLX+- [HiDream-ai](https://huggingface.co/HiDream-ai/HiDream-O1-Image-Dev) for HiDream-O1 weights and the reference implementation+- [filipstrand/mflux](https://github.com/filipstrand/mflux) for the MLX-native FLUX and Qwen-Edit family+- [mlx-community](https://huggingface.co/mlx-community) for Gemma 3 12B 4-bit+- [ModelPiper / PiperSR](https://github.com/ModelPiper/PiperSR) for optional 2x upscale on the Apple Neural Engine+- [@cocktailpeanut](https://twitter.com/cocktailpeanut) for Pinokio-Phosphene adds: persistent batch queue, warm helper subprocess, hardware-tier feature gating, lossless H.264 + faststart output, output gallery with sidecars, the capability-tier UI surface, in-panel character training pipeline, Image Studio dispatch + adaptive estimates, and the Pinokio install scripts.-----+What Phosphene adds on top: persistent batch queue, warm helper subprocess, hardware-tier feature gating, lossless H.264 output with sidecars, the capability-tier UI surface, the in-panel character training pipeline, the Image tab dispatch and adaptive estimates, and the Pinokio install scripts.## Support developmentPhosphene is free and open source.- Follow [@PhospheneAI](https://x.com/PhospheneAI) on X for releases and clips-- Patreon: <!-- PATREON_LINK_PLACEHOLDER --> (coming soon — https://www.patreon.com/PhospheneAI)-- Issues + PRs: https://github.com/mrbizarro/phosphene-----+- Patreon: https://www.patreon.com/PhospheneAI+- Issues and PRs: https://github.com/mrbizarro/phosphene## Network note-Phosphene runs locally. No telemetry. Clean production installs check GitHub every 30 minutes for an update badge, and reach Hugging Face / CivitAI only when you download models or LoRAs. Disable the update check with `PHOSPHENE_DISABLE_VERSION_CHECK=1`. Panel binds to `127.0.0.1` with no auth — not designed for LAN exposure or tunneling.+Phosphene runs locally. No telemetry. A clean production install checks GitHub every 30 minutes for an update badge, and only touches Hugging Face or CivitAI when you download models or LoRAs. Disable the update check with `PHOSPHENE_DISABLE_VERSION_CHECK=1`. The panel binds to `127.0.0.1` with no auth. It's not designed for LAN exposure or tunneling.diff --git a/caption_with_gemma.py b/caption_with_gemma.pyindex b2c3061..51c9934 100644--- a/caption_with_gemma.py+++ b/caption_with_gemma.py@@ -132,15 +132,30 @@ def main() -> int:return 1# Default Gemma path is the same one the panel's preflight already- # downloads — no extra disk required.+ # downloads — no extra disk required. Resolve via lora_lab's shared+ # helper so this honors `LTX_MODELS_DIR` the same way every other+ # lora_lab module does; anchoring to `__file__.parent` previously broke+ # when this script ran from a Pinokio install where the panel had set+ # LTX_MODELS_DIR to a different root than the script's directory.if args.gemma_path:gemma_path = pathlib.Path(args.gemma_path).resolve()else:- here = pathlib.Path(__file__).resolve().parent- gemma_path = here / "mlx_models" / "gemma-3-12b-it-4bit"+ try:+ from lora_lab import resolve_default_text_encoder+ resolved = resolve_default_text_encoder()+ except ImportError:+ # lora_lab not on PYTHONPATH (shouldn't happen via the panel's+ # spawn path, but keep a sane fallback so the standalone CLI+ # still works in a clean checkout).+ resolved = str(pathlib.Path(__file__).resolve().parent+ / "mlx_models" / "gemma-3-12b-it-4bit")+ gemma_path = pathlib.Path(resolved).resolve()if not gemma_path.is_dir():- _emit("error", message=f"Gemma model dir not found: {gemma_path} — "- f"run /train/preflight via the panel.")+ _emit("error",+ message=f"Gemma model dir not found: {gemma_path} — "+ f"run /train/preflight via the panel, or set "+ f"LTX_MODELS_DIR to a root that contains "+ f"gemma-3-12b-it-4bit/.")return 1# mlx_vlm + Gemma 3. Imports here (not module top) so the JSON-eventdiff --git a/docs/IMAGE_GEN_RESEARCH_2026-05.md b/docs/IMAGE_GEN_RESEARCH_2026-05.mdindex 35cda04..de67680 100644--- a/docs/IMAGE_GEN_RESEARCH_2026-05.md+++ b/docs/IMAGE_GEN_RESEARCH_2026-05.md@@ -88,7 +88,7 @@ All share the same argparse mixins — `--prompt`, `--negative-prompt`, `--widthmflux is great but only ships diffusion-based families. **HiDream-O1-Image-Dev** is a different beast: a single 8B Qwen3-VL backbone that does pixel-level patch generation directly (no separate VAE), distilled from a 50-step teacher into a 28-step student via flow matching. License is MIT (cleaner than FLUX.2-dev's NC).-The lab port lives outside Phosphene at `/Users/salo/HIDREAM-O1-MLX-LAB-active/` so its mlx-vlm dep tree doesn't fight Phosphene's ltx-2-mlx env. Phosphene shells out to the lab's python via subprocess (mirrors mflux pattern). Module path: `agent/image_engine.py`, `kind="hidream"`.+The lab port lives outside Phosphene at `~/HIDREAM-O1-MLX-LAB-active/` so its mlx-vlm dep tree doesn't fight Phosphene's ltx-2-mlx env. Phosphene shells out to the lab's python via subprocess (mirrors mflux pattern). Module path: `agent/image_engine.py`, `kind="hidream"`.### Why ship it alongside mfluxdiff --git a/docs/STATE.md b/docs/STATE.mdindex 2660dec..b0c9ebc 100644--- a/docs/STATE.md+++ b/docs/STATE.md@@ -1,6 +1,6 @@# Phosphene — project state, history, open work-Current `dev` head: `04d2ffd` (May 17 2026, evening) — Codex C+ 7-pass UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) + Train tab polish (Gemma 3 auto-caption, voice-on default, letterbox crop) + LoRA picker chrome (rename, download, companion-aware delete) + vendored `lora_lab/` for installer-only users + Codex 12.6% skip-step optimization on Q8 HQ.+Current `dev` head: see `git log -1` for the live SHA. The arc landed on May 17 2026 — Codex C+ 7-pass UI restructure (capability tiers, Q4 surface, Character as 5th mode pill, accel kill, HQ-speed move) + Train tab polish (Gemma 3 auto-caption, voice-on default, letterbox crop) + LoRA picker chrome (rename, download, companion-aware delete) + vendored `lora_lab/` for installer-only users + Codex 12.6% skip-step optimization on Q8 HQ.Latest `main`: still `v2.0.6` — `dev` carries ~30 commits ahead awaiting Mr Bizarro's ship verdict.@@ -16,8 +16,8 @@ Two clones on Mr Bizarro's Mac, both managed by Pinokio:| Path | Branch tracked | Port | Role ||---|---|---|---|-| `/Users/salo/pinokio/api/phosphene-dev.git/` | `dev` | 8199 | Active development. Most edits land here first. |-| `/Users/salo/pinokio/api/phosphene.git/` | `main` | 8198 | Production / daily driver. Mr Bizarro's actual usage. |+| `~/pinokio/api/phosphene-dev.git/` | `dev` | 8199 | Active development. Most edits land here first. |+| `~/pinokio/api/phosphene.git/` | `main` | 8198 | Production / daily driver. Mr Bizarro's actual usage. |GitHub is the source of truth (memory: `feedback_github_source_of_truth.md`). Branch policy is strict: **NEVER push to `main` without Mr Bizarro's explicit OK** (memory: `phosphene_dev_workflow.md`). When ready to promote, fast-forward only — `git merge --ff-only dev` from main, never a merge commit.@@ -149,18 +149,25 @@ A Pinokio Reset wipes the install dir but preserves all four — Mr Bizarro canSettings)- Plan/Interactive mode pill toggle in agent header-**Image Studio (v2.0.6+, May 8 2026)**-- Five engines in dropdown: Qwen-Edit-2511 Lightning (4-step distilled,- fast preview), Qwen-Edit-2511 standard, Qwen-Edit-2511 high-quality,- Klein-Edit fast (distilled flux2_edit Q4), and Klein-Base-Edit- photoreal (`flux2_edit_high`, klein-base-4b Q8 25-step guidance 4.0- — non-distilled, real photographic look)-- Q6 default quantization (was Q4) — Apple-Silicon community sweet- spot, ~4-6% quality loss vs full precision (Q4 was 8-12%), per-image- speed gap negligible on M4 Max+**Image Studio (dev head — Klein retired 2026-05-13)**+- Two engine families in the dropdown. Six tiers total:+ - **Qwen-Image-Edit-2511** — Fast (Lightning, 4-step Q6 + FBCache,+ ~1:20 / image, multi-ref), Medium (8-step Q6 + FBCache, ~2:05 /+ image, multi-ref), Quality (40-step Q8 + CFG 4.0 + FBCache, ~3:50+ / image, multi-ref).+ - **HiDream-O1-Image-Dev** — Fast (3-step, ~3:45 / 4-img batch,+ slight bg softness), Medium (6-step + FBCache, ~6 min / 4-img+ batch, character-preserving), Quality (12-step + light FBCache,+ ~9 min / 4-img batch, best detail).+- HiDream is a separate one-time clone (`HIDREAM_LAB_DIR` env var or+ `~/HIDREAM-O1-MLX-LAB-active`); resolved in `image_engine.py`.+- Q6 default quantization for mflux Qwen tiers — Apple-Silicon+ community sweet spot, ~4-6% quality loss vs full precision (Q4 was+ 8-12%), per-image speed gap negligible on M4 Max. Q8 reserved for+ the Quality tier.- Image jobs go through the same queue worker as video — they appearin Now / Queue / Recent / Logs alongside video jobs (was: synchronous- HTTP, invisible in panel)+ HTTP, invisible in panel).- Right-pane viewer is mode-aware: `<img>` tag for image mode,`<video>` for video. Carousel thumbnails ditto.- OUTPUTS gallery filter chips: All / Videos / Photos. Auto-flips@@ -178,6 +185,11 @@ A Pinokio Reset wipes the install dir but preserves all four — Mr Bizarro canlog lines, generates a github.com/.../issues/new link withlabels=bug, optionally bundles the latest 5 .ips crash files into/tmp/phosphene-bug-TS.zip.+- FLUX / Klein-Edit / Klein-Base-Edit were retired 2026-05-13 — the+ flux2_edit family stopped being competitive with Qwen-Edit-2511 ++ HiDream at the same step counts, and dropping it freed UI vocabulary+ for the new Qwen Fast/Medium/Quality + HiDream Fast/Medium/Quality+ six-tier grid above.**Frontend extraction (parked on `frontend-extraction` branch)**- `webapp/` directory: index.html, style/all.css, js/main.js,@@ -532,16 +544,7 @@ research-grade work on token merging.## 10. Memory pointers (for next-Claude)-Files in `/Users/salo/.claude/projects/-Users-salo-AI/memory/`:--- `phosphene_dev_workflow.md` — branch + dev-panel discipline-- `phosphene_linear_project.md` — Linear project location + credentials-- `feedback_copy_edit_dont_rewrite.md` — when Mr Bizarro asks me to look at his writing-- `feedback_writing_style.md` — schematic, short, plain-- `feedback_github_source_of_truth.md` — git fetch first, surface drift-- `feedback_dont_ask_to_save_memory.md` — when Mr Bizarro states a fact, save it; don't ask-- `claudio_repo.md` — shared infra, hosts `.env` with Linear key-- `ltx_video_setup.md` — older notes from MLX vs Comfy decisions+See local memory files for the cross-cutting workflow context — branch discipline (`phosphene_dev_workflow`), Linear credentials (`phosphene_linear_project`), writing style feedback (`feedback_copy_edit_dont_rewrite`, `feedback_writing_style`), source-of-truth discipline (`feedback_github_source_of_truth`), memory-save reflex (`feedback_dont_ask_to_save_memory`), shared infra (`claudio_repo`), historical MLX/Comfy decisions (`ltx_video_setup`).## 11. Linear board@@ -561,7 +564,7 @@ Issue prefixes are `HAI-NN` because of the team constraint. Active:## 12. How to start a fresh session-1. `cd /Users/salo/pinokio/api/phosphene-dev.git/`+1. `cd ~/pinokio/api/phosphene-dev.git/`2. `git fetch origin && git status -sb` — surface any drift first3. Read this file (`docs/STATE.md`) AND check `git log --oneline dev -25` — recent commits move faster than this doc; the v2.0.6 May 8 batch is a good example (~18 commits in one session). Read `CLAUDE.md` for architecture.4. Skim Linear `HAI-150` through `HAI-158` for state of each workstreamdiff --git a/image_engine.py b/image_engine.pyindex def7559..c63e372 100644--- a/image_engine.py+++ b/image_engine.py@@ -62,6 +62,7 @@ import osimport threadingimport timeimport urllib.error+import urllib.parseimport urllib.requestfrom dataclasses import asdict, dataclass, fieldfrom pathlib import Path@@ -1128,7 +1129,19 @@ def _generate_bfl(prompt: str, n: int, width: int, height: int,if sample_url is None:raise RuntimeError(f"BFL task {task_id} timed out after 180s")- # Download+ # Download. Validate the URL before fetching: BFL hands us back a+ # sample URL from a JSON response, and a compromised/MITM'd response+ # could substitute file:///... (local file read) or an attacker host+ # (exfil of poll_headers via Referer / credential reuse). Pin to+ # https on bfl.ai / bfl.ml only.+ parsed = urllib.parse.urlparse(sample_url)+ host = (parsed.hostname or "").lower()+ allowed = ("bfl.ai", "bfl.ml")+ host_ok = any(host == d or host.endswith("." + d) for d in allowed)+ if parsed.scheme != "https" or not host_ok:+ raise RuntimeError(+ f"BFL returned unexpected URL: {parsed.scheme}://{parsed.hostname}"+ )try:with urllib.request.urlopen(sample_url, timeout=60) as r:data = r.read()diff --git a/lora_lab/train.py b/lora_lab/train.pyindex 9f13578..9b4e72c 100644--- a/lora_lab/train.py+++ b/lora_lab/train.py@@ -46,16 +46,54 @@ def _patch_loader_prefer_dev_transformer() -> None:that point toward the wrong target — coarse features (hair/age/beard) survive themismatch but fine face geometry doesn't. Switching the trainer to the dev transformereliminates the objective mismatch.++ Q4/Q8 sibling fallback (2026-05-18):+ The trainer config hardcodes the Q4 model dir, but on a Q8-only install+ the dev transformer lives at ``<panel>/mlx_models/ltx-2.3-mlx-q8/+ transformer-dev.safetensors`` and the Q4 dir doesn't exist (or has only+ the distilled file). The panel's preflight (_train_required_models in+ mlx_ltx_panel.py) already accepts either location via ``extra_dirs=+ [q8_local_dir]``, but the trainer process — running in a separate venv+ — has to do its own probing. We look at ``<model_dir>`` first+ (matches existing behavior), then at the sibling ``ltx-2.3-mlx-q8/``+ next to it, and pin to whichever exists. If NEITHER exists we raise+ a clear, actionable error instead of letting the loader silently fall+ back to the distilled file — silent fallback was the original bug:+ identity capture quietly broke because the trainer was optimizing+ against the wrong sigma schedule."""from pathlib import Path_orig = ml_module.load_transformerdef patched(model_dir, transformer_file=None):if transformer_file is None:- dev = Path(model_dir) / "transformer-dev.safetensors"- if dev.exists():- transformer_file = "transformer-dev.safetensors"- logger.info("training-side override: using transformer-dev.safetensors (not distilled)")+ primary = Path(model_dir) / "transformer-dev.safetensors"+ sibling = Path(model_dir).parent / "ltx-2.3-mlx-q8" / "transformer-dev.safetensors"+ if primary.exists():+ logger.info(+ "training-side override: using transformer-dev.safetensors "+ "from %s (not distilled)",+ primary.parent,+ )+ return _orig(model_dir, transformer_file="transformer-dev.safetensors")+ if sibling.exists():+ # Repoint the loader at the Q8 sibling directory. We invoke+ # the upstream loader with the sibling DIR as `model_dir` so+ # `load_split_safetensors` resolves the shards relative to+ # the right snapshot — passing only the basename would still+ # join against the Q4 dir and miss the sibling's shard files.+ logger.info(+ "training-side override: using transformer-dev.safetensors "+ "from Q8 sibling at %s (Q4 dir has no dev transformer)",+ sibling.parent,+ )+ return _orig(str(sibling.parent),+ transformer_file="transformer-dev.safetensors")+ raise FileNotFoundError(+ f"transformer-dev.safetensors not found in {primary.parent} "+ f"or {sibling.parent}. Open Phosphene → Train Character → "+ f"Preflight to download it (~11 GB)."+ )return _orig(model_dir, transformer_file=transformer_file)ml_module.load_transformer = patcheddiff --git a/lora_lab/train_character.py b/lora_lab/train_character.pyindex 03d2321..d27a543 100644--- a/lora_lab/train_character.py+++ b/lora_lab/train_character.py@@ -252,11 +252,19 @@ def _framing_for_image(width: int, height: int) -> str:def _make_caption(trigger: str, strategy: str, width: int, height: int) -> str:+ # Emit LTX's canonical `[VISUAL]: ...\n[TEXT]: None\n` format so the+ # fallback rows match what caption_with_gemma.py writes for the auto-+ # caption path. Mixed-format datasets (some rows naked `<trigger> man`,+ # others `[VISUAL]:...`) caused identity drift on the fallback images+ # because the trainer's tokenizer saw two distinct prompt styles for+ # the same character. See ~/.claude/skills/ltx-lora/SKILL.md for the+ # validated v2 recipe.if strategy == "trigger_only":- return f"a photo of {trigger}"- # class_word (default) and auto_caption fallback- framing = _framing_for_image(width, height)- return f"{trigger} man, {framing}"+ body = "a photo"+ else:+ # class_word (default) and auto_caption fallback+ body = _framing_for_image(width, height)+ return f"[VISUAL]: {trigger}, {body}\n[TEXT]: None\n"def crop_and_caption(@@ -389,7 +397,21 @@ def crop_and_caption(emit("crop_progress", done=i, total=len(source_files), path=str(png_path))except Exception as exc: # noqa: BLE001- raise RuntimeError(f"failed to crop {src.name}: {exc}") from exc+ # One unreadable / corrupt image must not kill the whole pass.+ # Mirrors preprocess_images.preprocess_images_to_latents which+ # logs+continues on per-image encode failure (preprocess_images.py+ # :174-176). Re-raising used to fail the entire crop stage, so+ # users with one bad JPEG in a 30-image dataset lost the whole run.+ logger.warning(+ "failed to crop %s: %s — skipping this image", src.name, exc+ )+ emit(+ "warning",+ stage="crop",+ message=f"skipped {src.name}: {exc}",+ file=src.name,+ )+ continueemit("crop_done")return out_paths, out_captionsdiff --git a/mlx_ltx_panel.py b/mlx_ltx_panel.pyindex c463263..ff25db6 100644--- a/mlx_ltx_panel.py+++ b/mlx_ltx_panel.py@@ -20,6 +20,7 @@ import jsonimport osimport randomimport re+import selectimport shleximport shutilimport signal@@ -800,6 +801,14 @@ TRAIN_MAX_IMAGES = 50TRAIN_IMAGE_EXTS = {".png", ".jpg", ".jpeg", ".webp"}TRAIN_MAX_BYTES_PER_IMAGE = 32 * 1024 * 1024 # 32 MB per image upload+# Hard cap on bodies for the generic urlencoded POST fallback (the catch-all+# at the end of do_POST that handles /run, /queue/add, characters, etc.).+# Endpoints with their own larger caps (uploads, multipart, JSON bodies)+# enforce those locally before reading. 1 MB is well above any legitimate+# urlencoded form on Phosphene; without this cap a malformed Content-Length+# 500s the handler and a multi-GB declared CL allocates before any check.+MAX_FORM_BYTES = 1024 * 1024+# User-provided captions. Industry convention: `image_001.png` pairs with# `image_001.txt` (same stem) in the same upload. Caption body uses LTX's# canonical format:@@ -3445,12 +3454,24 @@ def _ensure_downscaled(src: Path, max_dim: int = 768, align: int = 32) -> Path:cached = src.parent / f"{src.stem}_dn{new_w}x{new_h}.mp4"if cached.exists() and cached.stat().st_size > 1024:return cached+ # Write to a .partial sibling and atomically rename on success so a+ # cancelled-mid-encode run can't leave a broken mp4 at `cached` that+ # the next call would treat as a valid cache hit.+ partial = cached.with_suffix(cached.suffix + ".partial")cmd = [str(FFMPEG), "-y", "-i", str(src),"-vf", f"scale={new_w}:{new_h}","-c:v", "libx264", "-pix_fmt", "yuv444p", "-crf", "0", "-preset", "veryfast","-c:a", "copy", # don't re-encode audio — extend doesn't need it transformed- str(cached)]- subprocess.run(cmd, check=True, capture_output=True, timeout=120)+ str(partial)]+ try:+ subprocess.run(cmd, check=True, capture_output=True, timeout=120)+ os.replace(partial, cached) # atomic on POSIX+ except Exception:+ try:+ partial.unlink()+ except FileNotFoundError:+ pass+ raisereturn cached@@ -3712,7 +3733,14 @@ def load_queue() -> None:class WarmHelper:def __init__(self):self.proc: subprocess.Popen | None = None+ # `lock` guards proc lifecycle (spawn / kill / restart).self.lock = threading.Lock()+ # `run_lock` serializes the write+read pair inside run() so two+ # concurrent callers (worker thread + /prompt/enhance) can't both+ # land in _read_until and steal each other's events. Kept separate+ # from `lock` so a /stop or /helper/restart can still kill the proc+ # while a run is mid-flight (the kill interrupts readline via EOF).+ self.run_lock = threading.Lock()def _ensure(self) -> None:with self.lock:@@ -3767,11 +3795,25 @@ class WarmHelper:if not self.proc or not self.proc.stdout:return Nonedeadline = time.time() + timeout if timeout else None+ # Poll-and-check loop: blocking readline() used to mean a hung helper+ # froze the worker thread until /stop. select() with a small interval+ # gives us deterministic deadline enforcement; readline() is only+ # called once we know there's data waiting.+ poll_interval = 0.5+ stdout = self.proc.stdoutwhile True:if deadline and time.time() > deadline:return None- line = self.proc.stdout.readline()+ rlist, _, _ = select.select([stdout], [], [], poll_interval)+ if not rlist:+ continue # idle slice — re-check deadline+ try:+ line = stdout.readline()+ except (OSError, ValueError):+ # Pipe closed underneath us (kill from another thread).+ return Noneif not line:+ # EOF — helper closed stdout (likely crashed or was killed).return Noneline = line.strip()if not line:@@ -3790,15 +3832,22 @@ class WarmHelper:push(f"helper {ev_type}: {json.dumps(ev)[:200]}")def run(self, job_spec: dict) -> dict:- self._ensure()- with self.lock:- assert self.proc is not None and self.proc.stdin is not None- try:- self.proc.stdin.write(json.dumps(job_spec) + "\n")- self.proc.stdin.flush()- except (BrokenPipeError, OSError) as exc:- raise RuntimeError(f"helper stdin closed: {exc}")- ev = self._read_until(["done", "error", "exit"])+ # Whole-run serialization so concurrent callers don't both park in+ # _read_until and grab each other's done/error events. See __init__+ # for why this is distinct from self.lock.+ with self.run_lock:+ self._ensure()+ with self.lock:+ assert self.proc is not None and self.proc.stdin is not None+ try:+ self.proc.stdin.write(json.dumps(job_spec) + "\n")+ self.proc.stdin.flush()+ except (BrokenPipeError, OSError) as exc:+ raise RuntimeError(f"helper stdin closed: {exc}")+ ev = self._read_until(["done", "error", "exit"])+ return self._dispatch_run_event(ev)++ def _dispatch_run_event(self, ev: dict | None) -> dict:if ev is None:# Pipe closed without an event. peanut review correction: don't# claim "SIGKILL" with certainty — could be SIGKILL (OOM jetsam),@@ -3860,10 +3909,17 @@ class WarmHelper:self.proc = Nonedef is_alive(self) -> bool:- return self.proc is not None and self.proc.poll() is None+ # Snapshot the ref so a concurrent kill() can't null self.proc between+ # the `is not None` and `.poll()` calls below (which would AttributeError+ # and bubble up to /status as a 500).+ proc = self.proc+ return proc is not None and proc.poll() is Nonedef pid(self) -> int | None:- return self.proc.pid if self.is_alive() else None+ proc = self.proc+ if proc is None or proc.poll() is not None:+ return None+ return proc.pidHELPER = WarmHelper()@@ -3913,6 +3969,38 @@ def _kill_caption_proc() -> None:atexit.register(_kill_caption_proc)+def _kill_train_proc() -> None:+ """Atexit hook — SIGTERM any training/audio subprocess by its pgid.+ Mirrors the kill path inside stop_current_job so the panel doesn't leave+ a training run hanging when the user CMD-Qs Pinokio or shuts down."""+ try:+ pgid = STATE.get("train_pgid")+ except Exception:+ pgid = None+ if not pgid:+ return+ try:+ os.killpg(pgid, signal.SIGTERM)+ except (OSError, ProcessLookupError):+ pass+++def _kill_image_procs() -> None:+ """Atexit hook — SIGTERM any in-flight image-engine subprocesses+ (HiDream BF16 helper, mflux per-family binaries). Each engine registers+ its Popen via _register_active_proc; kill_active_image_procs walks+ the set and SIGTERMs each process group."""+ try:+ agent_image_engine.kill_active_image_procs()+ except Exception:+ # Atexit handlers must not raise — they're best-effort.+ pass+++atexit.register(_kill_train_proc)+atexit.register(_kill_image_procs)++# ---- generation pipeline -----------------------------------------------------def compute_pad(w: int, h: int) -> tuple[int, int, str | None]:@@ -4130,25 +4218,56 @@ def _validate_character_quality(form: dict[str, list[str]] | dict[str, str]) ->forgets the chip-swap logic could submit the broken combo. Returningan error keeps the trainer-base contract honest at the API boundary.+ Also catches the loras=[] back-door: a scripted POST with a raw+ train_character-kind LoRA in the `loras` JSON array (no character_id)+ + quality=balanced would otherwise bypass this check — the UI's+ updateQualityChipsForLora handles it client-side but the server+ must enforce the same rule.+Returns None when valid, or an error string to surface as a 400."""def _f(name: str, default: str = "") -> str:v = form.get(name, default)if isinstance(v, list):v = v[0] if v else defaultreturn (v or "").strip()- cid = _f("character_id", "")- if not cid:- return None # no character; nothing to validatequality = _f("quality", "balanced").lower()- if quality != "high":- return (- f"character {cid!r} requires quality=high (Q8 HQ pipeline). "- f"Got quality={quality!r}. Character LoRAs are trained against "- f"the Q8 dev transformer's sigma schedule; the Q4 distilled "- f"pipeline fuses them into the wrong base and produces "- f"identity-mushed output. Pick Q8 Pro or Q8 Draft in the "- f"Character quality strip."- )+ cid = _f("character_id", "")+ if cid:+ if quality != "high":+ return (+ f"character {cid!r} requires quality=high (Q8 HQ pipeline). "+ f"Got quality={quality!r}. Character LoRAs are trained against "+ f"the Q8 dev transformer's sigma schedule; the Q4 distilled "+ f"pipeline fuses them into the wrong base and produces "+ f"identity-mushed output. Pick Q8 Pro or Q8 Draft in the "+ f"Character quality strip."+ )+ return None+ # No character_id — but a raw train_character LoRA in `loras` triggers+ # the same incompatibility. Resolve each entry's sidecar and refuse if+ # any one of them is kind == "train_character" and quality != high.+ if quality == "high":+ return None # the only outcome that needs to fail is non-high here+ try:+ loras = parse_loras_from_form(form)+ except Exception:+ loras = []+ for entry in loras:+ try:+ p = Path(str(entry.get("path") or ""))+ if not p.exists():+ continue+ meta = _read_lora_sidecar(p)+ except Exception:+ continue+ if (meta.get("kind") or "") == "train_character":+ return (+ f"a character LoRA ({p.name!r}) requires quality=high "+ f"(Q8 HQ pipeline). Got quality={quality!r}. Character LoRAs "+ f"are trained against the Q8 dev transformer's sigma schedule; "+ f"the Q4 distilled pipeline fuses them into the wrong base "+ f"and produces identity-mushed output. Pick Q8 Pro or Q8 Draft."+ )return None@@ -5050,12 +5169,20 @@ def run_train_job_inner(job: dict) -> None:for w in recon_warnings:push(f"[train] caption reconcile: {w}")+ # Use LTX canonical `[VISUAL]: <trigger>, <body>\n[TEXT]: None\n` format+ # so the fallback rows match the auto-caption path (caption_with_gemma.py+ # writes the same shape). Mixed-format datasets — some rows naked+ # `<trigger> man`, others `[VISUAL]: ...` — caused identity drift on+ # the fallback rows because the trainer's tokenizer saw two distinct+ # prompt styles for the same identity. v2 recipe in+ # ~/.claude/skills/ltx-lora/SKILL.md is the validated baseline.if caption_strategy == "trigger_only":- fallback_text = trigger+ fallback_body = "a photo"elif is_style:- fallback_text = f"{trigger} shot"+ fallback_body = "shot"else:- fallback_text = f"{trigger} man"+ fallback_body = "man"+ fallback_text = f"[VISUAL]: {trigger}, {fallback_body}\n[TEXT]: None\n"user_caps = 0auto_caps = 0@@ -5070,14 +5197,17 @@ def run_train_job_inner(job: dict) -> None:except OSError as e:push(f"[train] warn: could not write caption for {img.name}: {e}")+ # Single-line summary of the fallback caption for log readability —+ # avoids dumping the multi-line `[VISUAL]:\n[TEXT]:` payload into the log.+ fallback_summary = f"[VISUAL]: {trigger}, {fallback_body}"total_imgs = len(image_files)if user_caps:push(f"[train] using user-provided captions: {user_caps} / {total_imgs} images"- + (f" (auto-filled {auto_caps} with '{fallback_text}')"+ + (f" (auto-filled {auto_caps} with '{fallback_summary}')"if auto_caps else ""))elif caption_strategy == "user_provided":push(f"[train] caption_strategy=user_provided but no .txt files found — "- f"auto-filled all {total_imgs} images with '{fallback_text}'")+ f"auto-filled all {total_imgs} images with '{fallback_summary}'")# Output path for the trained LoRA. Going straight into# mlx_models/loras/ so the existing picker scan finds it.@@ -8838,8 +8968,22 @@ class Handler(BaseHTTPRequestHandler):self._json({"ok": True, "issueUrl": issue_url, "zipPath": zip_path})return- # All other POST endpoints expect urlencoded body- length = int(self.headers.get("Content-Length", "0"))+ # All other POST endpoints expect urlencoded body. Validate+ # Content-Length: int() on garbage 500s the handler; an absurd+ # declared length would allocate before any size check. See+ # MAX_FORM_BYTES near the top of the file.+ try:+ length = int(self.headers.get("Content-Length", "0"))+ except (TypeError, ValueError):+ self._json({"error": "bad content-length"}, 400); return+ if length < 0:+ self._json({"error": "bad content-length"}, 400); return+ if length > MAX_FORM_BYTES:+ self._json(+ {"error": f"request too large (max {MAX_FORM_BYTES} bytes)"},+ 413,+ )+ returnbody = self.rfile.read(length).decode() if length else ""form = parse_qs(body)@@ -9465,6 +9609,22 @@ class Handler(BaseHTTPRequestHandler):if source is None:self._json({"error": f"job {source_id!r} not found in history/queue"}, 404); returnsrc_params = source.get("params") or {}+ # Defense-in-depth: re-queuing a historical job with character_id+ # + balanced quality (or a raw train_character LoRA + non-high+ # quality) reproduces the bug /queue/add already rejects. Wrap+ # src_params into the form-shape the validator expects: it reads+ # `character_id`, `quality`, and `loras`. The first two are+ # already strings; `loras` lives in src_params as a parsed list+ # and needs to be re-encoded as JSON so parse_loras_from_form+ # round-trips it cleanly.+ _retry_form = {+ "character_id": src_params.get("character_id") or "",+ "quality": src_params.get("quality") or "",+ "loras": json.dumps(src_params.get("loras") or []),+ }+ err = _validate_character_quality(_retry_form)+ if err:+ self._json({"error": err}, 400); return# Build a fresh job — copy params verbatim, mint a new id, drop# any open_when_done flag (retries are usually background; user# is mid-other-work and doesn't want the OS jumping windows).@@ -9759,6 +9919,13 @@ class Handler(BaseHTTPRequestHandler):self._json({"unhidden_count": count}); returnif path == "/helper/restart":+ # Mark any in-flight job as user-cancelled BEFORE killing the+ # helper. Otherwise the worker sees the helper exit and writes+ # status=failed/"helper exited" instead of status=cancelled.+ with LOCK:+ cur = STATE.get("current")+ if cur is not None:+ cur["cancel_requested"] = TrueHELPER.kill()self._json({"ok": True}); return@@ -10214,6 +10381,14 @@ class Handler(BaseHTTPRequestHandler):"(takes effect on next job).")if codec_changed or tokens_changed:+ # Settings change forces a helper restart. Mark any in-flight+ # job as user-cancelled so the worker reports it that way+ # instead of as a "helper exited" failure (same shape as+ # /helper/restart and stop_current_job).+ with LOCK:+ cur = STATE.get("current")+ if cur is not None:+ cur["cancel_requested"] = TrueHELPER.kill()# Return only the public-safe view — never echo the saved# key back to the client even on success.@@ -11239,6 +11414,7 @@ HTML = r"""<!doctype html>body[data-cap-tier="q4"] #charactersPickerDivider,body[data-cap-tier="q4"] #qualityGroupCharacter,body[data-cap-tier="q4"] #charSkipstepToggleWrap,+ body[data-cap-tier="q4"] #workflowTabs button[data-workflow="audio"],body[data-cap-tier="q4"] #qualityGroup [data-quality="high"] { display: none !important; }/* Quality strip becomes a 3-col grid (Quick/Balanced/Standard)since the 4th column ("High") is gone. */@@ -18934,12 +19110,12 @@ function syncAvoidRowFromValue() {}function setMode(mode) {- // Capability guard — Q4 (sub-48GB) tier can't run FFLF or Extend; the- // pipeline classes are HQ-only. CSS already hides the chips, but a- // stale localStorage or a JS caller could still try to switch. Snap- // to t2v with a console warning so we never end up in an unrenderable- // mode by accident.- if (window.PHOSPHENE_CAP_TIER === 'q4' && (mode === 'keyframe' || mode === 'extend')) {+ // Capability guard — Q4 (sub-48GB) tier can't run FFLF, Extend, or+ // Character (HQ-only pipelines + Q8 trainer-base contract). CSS already+ // hides the chips, but a stale localStorage, charactersLoadParams(), or+ // a JS caller could still try to switch. Snap to t2v with a console+ // warning so we never end up in an unrenderable mode by accident.+ if (window.PHOSPHENE_CAP_TIER === 'q4' && (mode === 'keyframe' || mode === 'extend' || mode === 'character')) {console.warn(`setMode(${mode}): not available on Q4 tier — snapping to t2v`);mode = 't2v';}@@ -26713,7 +26889,10 @@ setInterval(refreshVersionPill, 5 * 60 * 1000);// inline style changes on the modals themselves; whoever toggles// display gets the side-effects for free.(function _phosModalScaffold() {- const MODAL_SEL = '.models-modal, .model-browser-modal, .expand-lightbox';+ // .modal-bg.show covers the batch modal (and any future modal that+ // uses the same .modal-bg + .show idiom). Including it here so Esc /+ // Tab focus-trap / body.modal-open scroll-lock all work for it too.+ const MODAL_SEL = '.models-modal, .model-browser-modal, .expand-lightbox, .modal-bg.show';const isVisible = el => {const d = el.style.display;// Some modals open by adding an .open class (.model-browser-modal);@@ -26847,6 +27026,12 @@ function workflowSwitch(name) {// chip strip is integrated into Manual (T2V). If we get a stale// 'characters' value from localStorage, snap to 'manual'.if (name === 'characters') name = 'manual';+ // Q4 cap-tier doesn't ship the audio workflow. If 'audio' is requested+ // anyway (stale localStorage, Load Params on a historical A2V job,+ // scripted caller), snap to 'manual' before any pane logic runs.+ if (name === 'audio' && document.body.dataset.capTier === 'q4') {+ name = 'manual';+ }document.querySelectorAll('#workflowTabs button[data-workflow]').forEach(b => b.classList.toggle('active', b.dataset.workflow === name));const manual = document.getElementById('genForm');diff --git a/pinokio.json b/pinokio.jsonindex b2b36a7..0155f60 100644--- a/pinokio.json+++ b/pinokio.json@@ -1,12 +1,12 @@{"title": "Phosphene",- "description": "[MAC ONLY] Local generative video panel for Apple Silicon. Joint audio+video via LTX 2.3 (MLX). T2V, I2V, FFLF, Extend. Lossless h264. LoRA picker + CivitAI browser. Free, open source.",+ "description": "Local generative video, image, and character training on Apple Silicon. Train face + voice LoRAs in-app. Q8 HQ for character clips. MLX native — no cloud, no API key.","icon": "icon.png","links": [{"title": "Phosphene (panel by Mr. Bizarro)","links": [{"title": "X / Twitter",- "value": "https://x.com/AIBizarrothe"+ "value": "https://x.com/PhospheneAI"}, {"title": "GitHub","value": "https://github.com/mrbizarro/phosphene"diff --git a/scripts/upscale_compare_pipersr.py b/scripts/upscale_compare_pipersr.pyindex e55632a..11d0446 100755--- a/scripts/upscale_compare_pipersr.py+++ b/scripts/upscale_compare_pipersr.py@@ -23,8 +23,8 @@ from PIL import ImageROOT = Path(__file__).resolve().parents[1]-PINOKIO_FFMPEG = Path("/Users/salo/pinokio/bin/ffmpeg-env/bin/ffmpeg")-PINOKIO_FFPROBE = Path("/Users/salo/pinokio/bin/ffmpeg-env/bin/ffprobe")+PINOKIO_FFMPEG = Path.home() / "pinokio" / "bin" / "ffmpeg-env" / "bin" / "ffmpeg"+PINOKIO_FFPROBE = Path.home() / "pinokio" / "bin" / "ffmpeg-env" / "bin" / "ffprobe"def run(cmd: list[str], label: str) -> None: