KORYAO-basic

# 🤝 KORYAO Looking for Collaborators KORYAO is looking for developers, designers, QA engineers, creative-software specialists, and business partners who want to help finish, validate, and ship the product to real customers. Contact: **[jianbaorui07@gmail.com](mailto:jianbaorui07@gmail.com)**. > KORYAO is looking for developers, designers, QA engineers, creative-software specialists, and business partners who want to help finish, validate, and ship the product to real customers. Contact: **[jianbaorui07@gmail.com](mailto:jianbaorui07@gmail.com)**. <p align="center"> <img src="brand/exports/koryao-software-icon.png" width="180" alt="KORYAO software icon"> </p> # KORYAO Basic: A Codex-Powered Local Creative App [](https://github.com/jianbaorui07-dot/KORYAO-basic/actions/workflows/ci.yml)      Current release boundary: **v0.1-alpha**. Core safety probes and local pixel reconstruction are marked as `stable`; desktop and Adobe write links are `experimental`; and the remaining capabilities are marked as `planned` or `not implemented`. > AutoCAD/DXF plan validate / dry-run / guarded write. Photoshop, Illustrator, Blender, and CapCut write flows are experimental or planned. --- # Part I: The Plain-Language Overview <h2 align="center">One Image → Pixel Reconstruction → SVG → Optional AI / PSD</h2> <p align="center"><strong>One image → Pixel Reconstruction → SVG → optional AI / PSD</strong></p> ## Put an Image In, Get a Deliverable File Out KORYAO is not a button-only demo. It brings **Codex conversation, local task execution, image vectorization, result verification, output management, and Adobe delivery** into one Windows desktop application. > KORYAO is not a button-only demo. It brings **Codex conversation, local task execution, image vectorization, result verification, output management, and Adobe delivery** into one Windows desktop application. You can select a project and image, tell Codex what you want in natural language, or operate the workflow directly. KORYAO performs the work locally and does not upload customer images to a KORYAO server. > You can select a project and image, tell Codex what you want in natural language, or operate the workflow directly. KORYAO performs the work locally and does not upload customer images to a KORYAO server. ## Main Feature: Pixel Reconstruction **Pixel Reconstruction** is now a visible card in the five-mode Vectorization page and is selected by default. It redraws every RGBA pixel at the chosen working resolution as real SVG geometry, renders the SVG back, and verifies it pixel by pixel. > **Pixel Reconstruction** is now a visible card in the five-mode Vectorization page and is selected by default. It redraws every RGBA pixel at the chosen working resolution as real SVG geometry, renders the SVG back, and verifies it pixel by pixel. It does not hide a PNG inside an SVG, and it does not call Illustrator Image Trace. The generated result contains no embedded raster, Base64 image, script, or external link. > It does not hide a PNG inside an SVG, and it does not call Illustrator Image Trace. The generated result contains no embedded raster, Base64 image, script, or external link. ### What a Customer Sees ```text Codex chat or direct controls → Choose a project and image → Pixel Reconstruction → Pixel-by-pixel verification → Preview and open the output folder → Optional: choose a new path for AI or PSD ``` The desktop app lets the user choose 512, 1024, 1600, 2048, or the original size as the working longest edge. The SVG safety limit can be set to 64, 128, or 256 MB, with 128 MB as the default. If the selected limit is exceeded, the job stops without overwriting the source or silently falling back to Image Trace. > The desktop app lets the user choose 512, 1024, 1600, 2048, or the original size as the working longest edge. The SVG safety limit can be set to 64, 128, or 256 MB, with 128 MB as the default. If the selected limit is exceeded, the job stops without overwriting the source or silently falling back to Image Trace. ## Five Image Modes | Mode | Plain-language description | Current role | | --- | --- | --- | | **Pixel Reconstruction** (`exact`) | Rebuild every working-resolution pixel as SVG geometry | **Default** | | **Editable 99** (`editable-99`) | Re-render every candidate and minimize complexity only after all five quality gates pass | High-fidelity editing | | **Artisan Vector** | Create editable results with fewer anchors and smoother curves | Advanced editing | | **Smart Vector** | Balance similarity, detail, and editability | General illustration | | **Lightweight Vector** | Reduce colors, fragments, and nodes | Logos, icons, and patterns | ## AI, PSD, and Save Paths The Delivery & Evidence page now provides **AI/PSD format selection, source selection, explicit confirmation, and a native save-path dialog**. On Windows, when the corresponding Adobe application is installed and licensed, KORYAO generates the file in staging, reopens it in the native Adobe application for validation, and only then writes it to the newly selected path; existing files are never overwritten. > The Delivery & Evidence page now provides **AI/PSD format selection, source selection, explicit confirmation, and a native save-path dialog**. On Windows, when the corresponding Adobe application is installed and licensed, KORYAO generates the file in staging, reopens it in the native Adobe application for validation, and only then writes it to the newly selected path; existing files are never overwritten. The Adobe path is implemented and covered by automated tests, but the full compatibility matrix across Photoshop, Illustrator, and customer machines is still under experimental validation. > The Adobe path is implemented and covered by automated tests, but the full compatibility matrix across Photoshop, Illustrator, and customer machines is still under experimental validation. --- # Part II: Technology, Architecture, and Professional Boundaries ## What Codex Does Codex is the reasoning and orchestration layer. The user states a goal in the Codex Conversation page, Codex selects the appropriate Skill and MCP tool, and the KORYAO local runtime performs the actual work, constrains paths, requests confirmation, verifies results, and records redacted evidence. > Codex is the reasoning and orchestration layer. The user states a goal in the Codex Conversation page, Codex selects the appropriate Skill and MCP tool, and the KORYAO local runtime performs the actual work, constrains paths, requests confirmation, verifies results, and records redacted evidence. ```mermaid flowchart LR A["User"] --> B["Codex Conversation"] B --> C["Codex Skills"] C --> D["KORYAO MCP"] D --> E["Local safety layer"] E --> F["Pixel Reconstruction and Vector Engines"] E --> G["Adobe / ComfyUI / CAD / Blender bridges"] F --> H["SVG, preview, report"] G --> I["Controlled app outputs"] ``` ## Pixel Reconstruction Boundaries | Item | Current rule | | --- | --- | | Input | One explicitly authorized PNG or JPEG; no recursive private-directory scan | | Reconstruction | Merge continuous same-color pixels into compound rectangular paths while preserving RGBA | | Working size | Default longest edge 1024; optional 512 / 1600 / 2048 / original | | Safety cap | Selectable 64 / 128 / 256 MB; product hard cap 256 MB | | Verification | Recheck dimensions, paths, colors, alpha, and pixel differences | | Rejected content | Raster images, Base64, scripts, external links, out-of-bounds coordinates | | Failure behavior | Stop and report; never overwrite the source or fall back to Image Trace | Pixel Reconstruction optimizes for verified fidelity, not minimal nodes or easy curve editing. Choose `editable-99` for strict verified quality, or Artisan, Smart, or Lightweight for drawing-oriented editing. The legacy `high-fidelity` gate still allows about 15% structural difference and is not a 99% claim. > Pixel Reconstruction optimizes for verified fidelity, not minimal nodes or easy curve editing. Choose `editable-99` for strict verified quality, or Artisan, Smart, or Lightweight for drawing-oriented editing. The legacy `high-fidelity` gate still allows about 15% structural difference and is not a 99% claim. ### Editable-99 Quality and Illustrator Protection `editable-99` checks `SSIM ≥ 0.990`, `difference ≤ 1.0%`, `normalized MAE ≤ 0.010`, `edge Dice ≥ 0.980`, and `alpha MAE ≤ 0.005`. It generates candidates at 256, 192, 160, 128, 96, 80, 64, 48, and 32 colors and re-renders each; any threshold failure disqualifies the candidate. The remaining candidates are sorted by subpaths, nodes, colors, SVG size, and time; if errors concentrate, 256-color local recovery is allowed and all metrics are recomputed. Illustrator auto-opening is gated at `subpaths ≤ 30,000` and `points ≤ 120,000` for suggested safety. Exceeding the suggestion requires warning and backup; `subpaths > 60,000` or `points > 240,000` forbids auto-opening by default; `subpaths > 300,000` only archives precisely. These are CreNexus engineering guardrails, not Adobe hard limits. Statuses `passed_editable_99`, `passed_quality_high_complexity`, `quality_not_met`, `quality_and_editability_conflict`, `resource_limit_exceeded`, or `execution_failed` do not silently downgrade. ## Native Adobe Delivery Rules - SVG → AI: invoke local Illustrator, save and reopen the file, verify artboards and objects, then publish it to the user-selected path. > SVG → AI: invoke local Illustrator, save and reopen the file, verify artboards and objects, then publish it to the user-selected path. - PNG/JPEG → PSD: invoke local Photoshop, create a layered document, save and reopen it, verify the canvas and layers, then publish it to the user-selected path. > PNG/JPEG → PSD: invoke local Photoshop, create a layered document, save and reopen it, verify the canvas and layers, then publish it to the user-selected path. - Both paths require explicit confirmation. Cancelling the save dialog creates no file, and failed or timed-out exports clean up incomplete files. > Both paths require explicit confirmation. Cancelling the save dialog creates no file, and failed or timed-out exports clean up incomplete files. - Native AI/PSD export currently supports Windows only. macOS returns an explicit unsupported result instead of a false success. > Native AI/PSD export currently supports Windows only. macOS returns an explicit unsupported result instead of a false success. ## Local-First Safety Model - Read-only, planning, or `dry-run` by default; real writes require explicit confirmation. > Read-only, planning, or `dry-run` by default; real writes require explicit confirmation. - Outputs are restricted to safe roots, project artifact directories, or a new path explicitly selected by the user. > Outputs are restricted to safe roots, project artifact directories, or a new path explicitly selected by the user. - Reports store hashes, relative references, and status—not tokens, cookies, OAuth data, customer assets, or absolute save paths. > Reports store hashes, relative references, and status—not tokens, cookies, OAuth data, customer assets, or absolute save paths. - Community is free and requires no login or network connection; the current source revision uses the KORYAO Proprietary License. > Community is free and requires no login or network connection; the current source revision uses the KORYAO Proprietary License. See [Product Facts](docs/PRODUCT_FACTS.md), [Architecture V2](docs/ARCHITECTURE_V2.md), [Vectorization Modes](docs/vectorization-modes.md), and [Pixel Reconstruction](docs/exact-pixel-vectorization.md) for technical details. ## Developer Quick Call ```powershell python -m pip install -e ".[vectorization]" npm.cmd run illustrator:vectorize -- --input "<input.png>" --mode exact --max-dimension 1024 --max-svg-size-mb 128 --reference-id "reference" ``` Editable vector modes: ```powershell npm.cmd run illustrator:vectorize -- --input "<input.png>" --mode artisan --reference-id "reference" npm.cmd run illustrator:vectorize -- --input "<input.png>" --mode editable-99 --quality-preset editable-99 --target-difference 1.0 --reference-id "reference" npm.cmd run illustrator:vectorize -- --input "<input.png>" --mode smart --reference-id "reference" npm.cmd run illustrator:vectorize -- --input "<input.png>" --mode lightweight --reference-id "reference" ``` ## Tool List - **Image Generation Area**: `examples/comfy_bridge/` and related safety probes. - **Engineering Drawing Area**: `cad-mcp-autocad/`, `scripts/` and AutoCAD/DXF plans, validation, and controlled writes. - **AI Vector File Bridge**: Illustrator access, environment variables, and pre-check instructions see [docs/05-codex-illustrator.md](docs/05-codex-illustrator.md). - CapCut integration only provides explicit probes; returns unavailable if **CapCut executable not found**, does not scan private draft directories. For more indexes, see [Adobe Demo Gallery](docs/adobe-demo-gallery.md), [Adobe Demo Smoke Test](docs/adobe-demo-smoke-test.md), and [Draft Release Notes](RELEASE_NOTES_DRAFT.md). ## Release-candidate checks ```powershell python scripts/security_check.py python scripts/collect_bridge_status.py --json python examples/bridge_status.py --json --redact-paths --soft-exit python -m starbridge_mcp.server tools --json --safe-only python -m starbridge_mcp.server evidence --init --json python -m starbridge_mcp.server evidence --validate --json python -m starbridge_mcp.server job-status --json python scripts\starbridge_preflight.py --markdown python scripts\starbridge_preflight.py --write-report --soft-exit ``` # Part III: Iteration Data, Completed Work, and Open Work ## Current Version The current public version is **v0.1.0-alpha.2**. Community baseline capabilities are free and require no activation. The current public source revision uses the KORYAO Proprietary License, while historical revisions retain the license rights distributed with them. The desktop product, installer, and third-party write paths remain labeled stable, experimental, or planned according to their evidence level; code existence must not be presented as acceptance on every customer machine. > The current public version is **v0.1.0-alpha.2**. Community baseline capabilities are free and require no activation. The current public source revision uses the KORYAO Proprietary License, while historical revisions retain the license rights distributed with them. The desktop product, installer, and third-party write paths remain labeled stable, experimental, or planned according to their evidence level; code existence must not be presented as acceptance on every customer machine. ## Small-Scope Measured Results These numbers describe recorded samples only and do not promise identical results for every image. | Sample or iteration | Metric | Result | | --- | --- | ---: | | Central red-carp reconstruction | Output size | 384 × 512 | | Central red-carp reconstruction | SVG size | 8,277,677 bytes | | Central red-carp reconstruction | Runtime | 1.47 s | | Central red-carp reconstruction | Different pixels | 0 | | Central red-carp reconstruction | Maximum channel difference | 0 | | Central red-carp reconstruction | Embedded rasters | 0 | | Artisan Iteration 4 → 5 | Centerline anchors | 30,813 → 24,875 (-19.27%) | | Artisan Iteration 4 → 5 | Subpaths | 10,309 → 8,064 (-21.78%) | | Artisan Iteration 4 → 5 | SVG size | 1,014,783 → 861,890 bytes (-15.07%) | ## Completed or Evidence-Backed | Capability | Current conclusion | | --- | --- | | Windows desktop startup | Local startup, shutdown, relaunch, and sidecar lifecycle are evidenced; overall status remains experimental | | Codex conversation and MCP | Conversation entry, connection state, safe tool registry, and project-level `.codex/config.toml` are implemented | | Image vectorization | Five engines are implemented; Pixel Reconstruction is the desktop default and editable-99 has independent five-metric gates | | Customer main flow | Project and image selection → reconstruction → verification → preview → output folder is connected | | AI/PSD delivery UI | Format, source, confirmation, path picker, receipt history, and no-overwrite rules are implemented | | Automated validation | The feature baseline passed 836 Python, 34 frontend, and 27 Rust tests; CI remains the per-merge source of truth | ## Not Fully Completed Yet | Area | What remains | | --- | --- | | Production Windows release | Authenticode signing, SmartScreen validation, clean-machine matrix, production updater signing | | Full Adobe compatibility | Multiple Photoshop/Illustrator versions, localized installs, recovery cases, and more customer-machine acceptance | | macOS desktop | Darwin sidecar, Tauri desktop startup, macOS CI, native Adobe export | | ComfyUI production loop | More real installations, custom nodes, model environments, and failure-recovery acceptance | | Blender, AutoCAD, CapCut | Currently probe, plan, dry-run, or experimental capabilities; no unified customer-grade loop yet | | Commercial launch | Signed installer, update channel, privacy/support processes, and Pro delivery | The most accurate statement today is: **the Windows local application and the Pixel Reconstruction main path are working well enough for continued customer acceptance testing; a full commercial release, macOS desktop support, and broad compatibility across all third-party creative tools are not finished yet.** # Part IV: Windows / macOS Setup and Fast Codex Installation ## Windows: Full Desktop Path ### Minimum prerequisites - Git 64-bit and Python 3.10+. For the desktop app, also install Node.js 22 LTS, Rust stable MSVC, Microsoft C++ Build Tools, and WebView2. > Git 64-bit and Python 3.10+. For the desktop app, also install Node.js 22 LTS, Rust stable MSVC, Microsoft C++ Build Tools, and WebView2. ### Let Codex Prepare the Core Environment Paste this directly into Codex: ```text Clone https://github.com/jianbaorui07-dot/KORYAO-basic.git, enter the repository, run powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 -Profile auto Do not modify system-level software. Then run the safe preflight and report whether .codex/config.toml was created successfully. ``` Manual equivalent: ```powershell git clone https://github.com/jianbaorui07-dot/KORYAO-basic.git Set-Location .\KORYAO powershell -ExecutionPolicy Bypass -File .\bootstrap.ps1 -Profile auto ``` `bootstrap.ps1` creates a repository-local `.venv`, installs matching Python/MCP dependencies, writes project-level `.codex/config.toml`, and runs safe checks. When it finishes, open a new Codex task in this repository so Codex reloads the MCP configuration. ### Start the Windows Desktop App ```powershell npm.cmd ci --prefix apps\starbridge-desktop powershell -ExecutionPolicy Bypass -File apps\starbridge-desktop\scripts\Build-Sidecar.ps1 npm.cmd run tauri:dev --prefix apps\starbridge-desktop ``` To verify the core first: ```powershell .\.venv\Scripts\python.exe scripts\starbridge_preflight.py --markdown .\.venv\Scripts\python.exe -m starbridge_mcp.server tools --json --safe-only ``` ## macOS: Core MCP First, Desktop Not Yet Promised ### Minimum prerequisites - Git, Python 3.10+. Node.js is only needed for frontend builds or optional bridges. > Install Git and Python 3.10+. Node.js is only needed for frontend builds or optional bridges. ### Let Codex Prepare the Safe Core Paste this directly into Codex: ```text Clone https://github.com/jianbaorui07-dot/KORYAO-basic.git, enter the repository, run bash ./bootstrap.sh --profile auto Do not install or modify Homebrew, Xcode, Rosetta, or system-level software. Then run the safe preflight and report whether .codex/config.toml was created successfully. ``` Manual equivalent: ```bash git clone https://github.com/jianbaorui07-dot/KORYAO-basic.git cd KORYAO bash ./bootstrap.sh --profile auto ``` `bootstrap.sh` creates `.venv`, installs the safe Python/MCP path, writes the project-level Codex MCP configuration, and runs checks. It does not install Homebrew, Xcode, or Rosetta and does not start Tauri. Open a new Codex task in the repository afterward. Verify the macOS core: ```bash ./.venv/bin/python scripts/starbridge_preflight.py --markdown ./.venv/bin/python -m starbridge_mcp.server tools --json --safe-only ``` The frontend can be built separately, but this is not a working macOS desktop release: ```bash npm ci --prefix apps/starbridge-desktop npm run build --prefix apps/starbridge-desktop ``` ## First Checks When Setup Fails | Check | Windows | macOS | | --- | --- | --- | | Python | `python --version` | `python3 --version` | | Git | `git --version` | `git --version` | | Node (desktop/frontend) | `node --version` | `node --version` | | Codex project config | `.codex\config.toml` | `.codex/config.toml` | | Safe preflight | `.\.venv\Scripts\python.exe scripts\starbridge_preflight.py --markdown` | `./.venv/bin/python scripts/starbridge_preflight.py --markdown` | Never commit tokens, cookies, Adobe licensing information, customer assets, or real save paths to GitHub. ## Repository Map | Path | Purpose | | --- | --- | | `.codex/skills/starbridge-*` | Codex Skills, safety boundaries, and verification commands | | `starbridge_mcp/` | MCP server, tool registry, and safety layer | | `apps/starbridge-desktop/` | Tauri 2 + React desktop app | | `product/` | Machine-readable product facts | | `examples/` | Safe-by-default bridge examples | | `tests/` | Offline, integration, and safety tests | | `docs/` | Architecture, integration protocols, and capability boundaries | ## Contributing and License Read [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md) before contributing. The current revision is released under the [KORYAO Proprietary License](LICENSE). Earlier revisions remain subject to the license terms distributed with those revisions.