@ninkch/dsh-artcraft 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,209 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+
+----------------------------------------------------------------------
+
+The above Apache License, Version 2.0 applies to this project
+(dsh-artcraft / @ninkch/dsh-artcraft).
+
+Copyright 2026 NINKCH

package/NOTICE.md

@@ -0,0 +1,72 @@
+# Third-party notices
+
+## ArtCraft (PhotoCraft / FilmCraft / EffectCraft — getartcraft.com)
+
+The ArtCraft applications that this plugin drives are distributed by the ArtCraft team under the
+**ArtCraft License (WIP)** — a "fair source" license. The text below is reproduced **verbatim** as
+published by the project (~ Brandon Thomas). This plugin contains **no ArtCraft code**; it only
+drives the apps' public automation surfaces (headless CLI + JSON control channel).
+
+---
+
+## ArtCraft License (WIP)
+
+(Warning: This isn't a real lawyery license full of legitimate legalese yet, but we'll take care of that ASAP.)
+
+ArtCraft is a form of "fair source" software. It's like free beer in that we give you the code, but there are a few small limitations on what you can do with it.
+
+First, what you can do with ArtCraft:
+
+You do not have to pay us to use ArtCraft. It's free.
+
+You can back up, copy, modify, compile, and use the code for your own private personal purposes.
+
+You can do anything you want with the media you create with ArtCraft. Generated assets are yours.
+
+What you can't do with ArtCraft:
+
+You cannot sell the ArtCraft software commercially (eg. as your own software).
+
+You cannot use the ArtCraft code to develop a competing business or product (eg. selling AI image and video tools).
+
+You cannot fork ArtCraft and remove ArtCraft community, donation links, or paid model services. We intend to make money to improve ArtCraft for everyone.
+
+You cannot use the ArtCraft name, logo, or mascot characters to promote your business without permission.
+
+This license means you can see what we're doing and not be at risk of having the rug pulled out from under you (eg. if our founders die, if our business collapses, if zombies or space aliens invade). It also gives you a really great way to customize the software or lend a hand in reporting (or even fixing) bugs.
+
+Our desire is to support artists, designers, and filmmakers. We want to help you build your own creative studios and businesses. We want to give you creative software you can use forever.
+
+ArtCraft is free. We do offer models available through us where you can pay us and support our development, but we also offer the ability for you to use other providers - and we'll keep adding more options so you have maximum flexibility.
+
+### Our Promise
+
+All development and business plans will be communicated openly with the community.
+
+Except for minor test scripts or a few small places where we might need to use licensed 3rd party code, all of our engineering efforts will live in a single publicly available monorepo. You can see everything we do and even benefit from using it for personal use. We plan on building a lot more than what you see today, and you'll get all of it.
+
+We will not "rug pull" our users. If our business shuts down, gets acquired, or otherwise changes, the tools we create will always continue to function in the same way.
+
+If the business ends and our founders quit working in this space, we'll make it so the software transitions to an OSI-approved open source license. (We don't intend to quit!)
+
+### Why not OSI Open Source?
+
+Philosophical answer: The OSI is an industry body led by hyperscalers. They poach from open source all the time, yet hyperscaler systems and code (AWS, GCP, YouTube, etc.) remain closed source. The tiniest nuggets are open, but the vast machinery surrounding it - systems, user behaviors, funnels, at-scale moneymakers - is totally closed.
+
+Practical answer: OSI licenses make it exceptionally challenging to grow big things commercially. And many of the licenses leave room for hyperscalers to reach in and cherry-pick pieces for themselves that they can better commercialize than the original authors.
+
+Then there's completely open source software that doesn't even attempt to be a business.
+
+We love software like Blender, but (1) developing ArtCraft is our full-time job, (2) we want to build something at scale that is much bigger than what you presently see, and (3) this will eventually become much more capital intensive than just writing code - we want to train novel models that work directly in conjunction with the user interface.
+
+If and when we do get to scale, we intend to keep every bit of our work in the open, including the models. Available for use, inspection, learning, fitting onto consumer GPU hardware, and more.
+
+Not having a way to make money is unfortunately what killed Stability.ai. Stability.ai walked so that others could eventually run. (Black Forest Labs, et al.) We're not egotistical enough to count ourselves in that party yet, but we believe in the original Stability.ai ethos and that their model can work with a few tweaks.
+
+We want to build big and incredible tools the world hasn't seen before. We want to keep them free and entirely source available. You don't have to pay us, but if you do, all of your investment goes right back into the engineering and the tools. We're writing code you can clone and keep.
+
+### Inspiration
+
+We took inspiration for this from Fair Source, Fair Code, the Defold License, and Hacker News discussions. The folks at Obsidian have some pretty good thoughts on this as well.
+
+~ Brandon Thomas

package/README.md

@@ -1,3 +1,308 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# ArtCraft Bridge
+
+**Drive the open-source ArtCraft studio apps — PhotoCraft, FilmCraft, EffectCraft — from DeepSeek Harness, in chat or from your own UI.**
+
+[English](README.md) | [简体中文](README.zh-CN.md)
+
+`@ninkch/dsh-artcraft` · a [DeepSeek Harness](https://github.com/deepseek-ai) plugin · Apache-2.0
+
+</div>
+
+---
+
+## Why this exists
+
+[ArtCraft](https://getartcraft.com/apps) is a family of free, fair-source reinventions of Adobe's
+studio tools, written from scratch in pure Rust: **PhotoCraft** (Photoshop), **FilmCraft**
+(Premiere Pro), **EffectCraft** (After Effects) and more. They share one superpower that most
+desktop apps don't have: **every menu item, slider and dialog is a command**, and the exact same
+commands can be driven from a headless CLI, a JSON control channel, or an MCP server. The apps
+were built for agents from day one.
+
+This plugin brings that surface into DeepSeek Harness, so an AI agent can *operate* the apps —
+not just talk about them:
+
+- **In chat** — four agent tools let any Harness session check the toolchain, run CLI commands,
+  send control-channel commands to a running app, and read/write files in a dedicated data root.
+- **In the browser** — a same-origin HTTP API (`/artcraft/api/*`) that any Harness web UI can call,
+  no CORS, no keys. It was built for [无限画布 / infinite-canvas](../dsh-infinite_canvas/README.md),
+  a node-based AI short-drama storyboard canvas, but any front end can use it.
+- **On disk** — one `dataRoot` per machine where assets, project files and rendered output live,
+  laid out per project (`media/ · craft/ · out/`), so generative pipelines and the desktop apps
+  meet on common ground.
+
+A typical AI short-drama loop looks like this: generate storyboard frames with a model →
+batch color-grade and sharpen them in PhotoCraft → render an animated title in EffectCraft →
+assemble the final cut in FilmCraft with grading, mixing and burned-in subtitles → export H.264.
+Every step after "generate" runs through this plugin, headless.
+
+## How it fits together
+
+```
+┌──────────────── DeepSeek Harness web UI (browser) ────────────────┐
+│   e.g. infinite-canvas: ① upload assets  ② start jobs  ③ fetch   │
+└─────────────────────────────┬─────────────────────────────────────┘
+                              ▼  same-origin fetch, no CORS
+┌──────────────── DSH Host · @ninkch/dsh-artcraft ────────────────┐
+│   HTTP routes /artcraft/api/*   +   agent tools artcraft_*        │
+│        → child processes (the CLIs)  →  TCP control channel       │
+└──────┬───────────────────────┬───────────────────────┬───────────┘
+       ▼                       ▼                       ▼
+  photocraft-cli          filmcraft-cli          effectcraft-cli
+  batch grading, PSD      EDL/XML in-out,        .ecproj (JSON) render,
+  headless edits          cut · grade · mix      Lottie export
+       └───────────────────────┴───────────────────────┘
+                               ▼
+              <dataRoot>/<project>/{media, craft, out}
+```
+
+Everything runs locally. No cloud round-trips, no accounts, no telemetry.
+
+## Requirements
+
+- **DeepSeek Harness** (desktop), any platform the Harness supports.
+- **ArtCraft apps** — grab what you need from [getartcraft.com](https://getartcraft.com/apps)
+  or the [storytold GitHub releases](https://github.com/storytold). The portable/installer builds
+  ship the CLI binaries on Windows and Linux (`photocraft-cli.exe` …); macOS ships them as a
+  separate notarized zip. Versions tested: PhotoCraft 0.6, FilmCraft 0.5, EffectCraft (early).
+- Nothing else. No Python, no FFmpeg — the ArtCraft apps bring their own codecs.
+
+## Setup
+
+**1. Get the plugin onto disk** (this repository). Any folder works; keeping it inside the Harness
+workspace next to your other local plugins is the convention.
+
+**2. Register it with your Harness profile.** A Harness profile is a pnpm package at
+`C:\Users\<you>\.dsh\profiles\<profile>\` (desktop profile by default). Two edits:
+
+```jsonc
+// package.json in the profile
+{
+  "dependencies": {
+    // ...existing deps...
+    "@ninkch/dsh-artcraft": "^0.1.1",                                    // ← from npm
+    // or, for local development, a link into this repository:
+    // "@ninkch/dsh-artcraft": "link:D:/code/deepseek-plugin/dsh-artcraft"
+  },
+  "dsh": { "profile": { "bundles": [
+    // ...existing bundles...
+    "@ninkch/dsh-artcraft"                                               // ← add the name
+  ] } }
+}
+```
+
+Then link and restart the Harness once (Host-side code loads at startup):
+
+```sh
+pnpm install --dir C:/Users/<you>/.dsh/profiles/desktop
+```
+
+> If your Harness build ships a plugin manager UI that installs from a folder, that works too —
+> it ends up writing exactly the two lines above.
+
+**3. Configure** `artcraft.config.json` next to `index.js` (copy from
+`artcraft.config.json.example`; the file is git-ignored and re-read on every request — no restart
+needed for path changes):
+
+```jsonc
+{
+  "dataRoot": "D:/craft-workspace",              // where assets & renders live
+  "bins": {
+    // three accepted forms: a directory (the <name>-cli binary is appended),
+    // a full path to the executable, or a bare name looked up on PATH
+    "photocraft":  "C:/craft/photocraft-0.6.0-windows-x64-portable",
+    "filmcraft":   "C:/craft/filmcraft-0.5.0-windows-x64-portable",
+    "effectcraft": "C:/craft/effectcraft-windows-x64-portable"
+  },
+  "control": { "filmcraft": 9876, "effectcraft": 9877 }
+}
+```
+
+**4. Verify.** In any Harness chat, ask your agent to run `artcraft_status`. Green lights across
+`bins.*.found` and you're done.
+
+## Driving it from chat
+
+The plugin registers four tools. The agent composes them, so plain language works:
+
+> *"Color-grade every PNG in `demo/media` with a soft S-curve and smart sharpening at 80, put the
+> results in `demo/out/graded`."*
+
+Behind that sentence the agent will typically do:
+
+```
+artcraft_cli  { bin:"photocraft", args:["batch","--actions","demo/craft/grade.json",
+                                        "--in","demo/media","--out","demo/out/graded"] }
+```
+
+| Tool | What it does |
+|---|---|
+| `artcraft_status` | Toolchain health check: which CLIs resolved, data root, control ports, running jobs |
+| `artcraft_cli` | Run any CLI subcommand synchronously (`photocraft-cli run/batch`, `filmcraft-cli commands`, …) |
+| `artcraft_control` | One command over the JSON control channel of a *running* FilmCraft / EffectCraft |
+| `artcraft_fs` | list / stat / read / write / mkdir inside `dataRoot` (writing `grade.json`, fetching a rendered `.ecproj`, …) |
+
+## Driving it from the browser
+
+Same-origin HTTP, JSON in and out. The workhorse pattern is the **job lifecycle** — start, poll,
+fetch — which keeps long renders off the request cycle:
+
+```
+POST /artcraft/api/job      { "bin":"effectcraft",
+                              "args":["render","--comp","Main",
+                                      "--out","demo/out/intro.mp4","demo/craft/intro.ecproj"],
+                              "outputs":["demo/out/intro.mp4"] }
+                         →  { "id":"7f2c…" }
+
+GET  /artcraft/api/job?id=7f2c…&tail=30
+                         →  { "status":"running|done|failed|timeout",
+                              "stdout":"…last lines…", "stderr":"…",
+                              "outputs":[{"rel":"demo/out/intro.mp4","exists":true,"size":812345}] }
+
+GET  /artcraft/api/file?rel=demo/out/intro.mp4        → raw bytes (streamed)
+POST /artcraft/api/job/cancel  { "id":"7f2c…" }
+```
+
+Full route list:
+
+| Route | Purpose |
+|---|---|
+| `GET /artcraft/api/status` | Toolchain health (same payload as `artcraft_status`) |
+| `GET /artcraft/api/projects` | Project directories under `dataRoot` |
+| `POST /artcraft/api/fs?action=write&rel=…` | Write a file — raw body (Blob upload) or JSON `{rel, text\|base64}` |
+| `GET /artcraft/api/fs?op=list\|stat\|readtext&rel=…` | Read directories, metadata, small text files |
+| `GET /artcraft/api/file?rel=…` | Download a file — streamed, up to 2 GB |
+| `POST /artcraft/api/job` · `GET ?id=…` · `POST /artcraft/api/job/cancel` | Job lifecycle with output statting and tail logs |
+| `POST /artcraft/api/control` | Synchronous control-channel call |
+
+Uploads are capped at 320 MB per request (Blob direct, no base64 needed for the raw path);
+downloads stream up to 2 GB. Path arguments are always relative to `dataRoot` and confined to it.
+
+## The control channel: drive a running app
+
+CLI runs are headless and one-shot. When you'd rather watch and fine-tune — grading a scene,
+scrubbing a cut — start the desktop app with its control channel and speak to it live:
+
+```sh
+filmcraft --control 9876      # or set FILMCRAFT_CONTROL_PORT; loopback only
+```
+
+```jsonc
+POST /artcraft/api/control
+{ "app": "filmcraft", "method": "engine.execute",
+  "params": { "command": "timeline.place",
+              "params": { "item": 1, "track": "V1", "seconds": 0, "duration": 1270080000000 } } }
+
+// a Lumetri curve on clip 87 …
+{ "command": "effects.setParam",
+  "params": { "clip": 87, "effect": "lumetri", "param": "curve_luma",
+              "value": [[0,0],[0.25,0.21],[0.75,0.82],[1,1]] } }
+
+// …and a look at what the app shows
+{ "method": "ui.screenshot", "params": { "path": "frame.png" } }
+```
+
+Time accepts `seconds`, `frame` or `timecode` (internally FilmCraft counts ticks at
+254,016,000,000/s). `filmcraft-cli commands` lists the 650+ engine commands; the protocol is
+documented in [filmcraft/docs/control-protocol.md](https://github.com/storytold/filmcraft/blob/main/docs/control-protocol.md).
+EffectCraft listens the same way on its own port (default 9877).
+
+> PhotoCraft's control channel is an authenticated variant and is deliberately **not** proxied
+> here — for PhotoCraft the headless CLI covers everything this plugin needs.
+
+## Working with 无限画布 (infinite-canvas)
+
+The two plugins are decoupled — they meet only on HTTP and the disk layout. The canvas:
+
+1. syncs its generated assets (IndexedDB blobs) into `<project>/media/`,
+2. starts PhotoCraft/FilmCraft/EffectCraft jobs with per-project files in `<project>/craft/`,
+3. fetches finished renders from `<project>/out/` back into its asset library.
+
+If you're building a similar front end, mirror that contract: project slug as folder name, keep
+the `media · craft · out` triad, and everything composes.
+
+## Recipes
+
+**Uniform grading across storyboard frames** — `demo/craft/grade.json`:
+
+```json
+{ "actions": [
+  { "cmd": "layer.newAdjustmentLayer.curves", "params": { "points": [[0,0],[64,48],[192,212],[255,255]] } },
+  { "cmd": "filter.sharpen.smartSharpen",     "params": { "amount": 80 } }
+] }
+```
+
+```sh
+photocraft-cli batch --actions demo/craft/grade.json --in demo/media --out demo/out/graded
+```
+
+**Final cut without a browser recorder** — the canvas exports its storyboard as a
+Final Cut Pro 7 XML (`xmeml`) or CMX3600 EDL into `demo/craft/timeline.xml`; FilmCraft imports
+it, links media from `demo/media/`, and exports H.264 (hardware NVENC on Windows), ProRes, DNxHR
+with EBU R128 loudness normalization and burned-in captions. Interchange is where FilmCraft's
+automation really pays off — EDL/XML are plain text your pipeline already knows how to write.
+
+**Animated titles as code** — EffectCraft projects (`.ecproj`) are versioned JSON, so a model can
+write one outright or fill a template. Render to MP4/ProRes — ProRes 4444 with alpha drops
+straight onto a FilmCraft track as a graphics layer — or export **Lottie** and play it inline in
+a web UI.
+
+## Troubleshooting
+
+- **`bins.*.found: false`** — check the path forms above; the CLI must exist next to the app
+  (or be on `PATH`). Changes to `artcraft.config.json` apply on the next request.
+- **404 on `/artcraft/api/*`** — the bundle isn't registered with the profile (see Setup) or the
+  Harness hasn't been restarted since registration. `artcraft_status` from chat is the quick probe.
+- **Control channel refused** — the app must be running with `--control <port>`; the channel is
+  loopback-only and unauthenticated, so nothing else will answer on that port.
+- **A job hangs** — `GET /artcraft/api/job` lists everything with logs; cancel by id. Plugin
+  reloads kill all child jobs by design.
+- **Path escape errors** — by design: every filesystem argument must resolve inside `dataRoot`.
+
+## Security & trust model
+
+The HTTP surface has **no authentication** and rides on the Harness web server, which listens on
+loopback only — treat the port as trusted-local and don't expose it to a network; put a reverse
+proxy with auth in front if you must. Child processes are locked to the three allow-listed
+binaries; file access is locked to `dataRoot`; the control channel only ever dials `127.0.0.1`.
+
+## Publishing
+
+This plugin is published to npm as **`@ninkch/dsh-artcraft`** (scoped packages publish with
+`npm publish --access public`). To consume it, add the package name to your Harness profile's
+`dependencies` and `dsh.profile.bundles` (see Setup) — `pnpm install` in the profile does the
+rest. For local development, swap the dependency for a `"link:<path-to-this-repo>"` instead.
+The three places that must agree on the package name are the profile `package.json`
+(dependency + bundles) and this repo's `cordis.patch.yml`.
+
+GitHub: this repository is self-contained; `README.md` is English-first with a
+[简体中文](README.zh-CN.md) companion.
+
+**Releases run through npm Trusted Publishing** (GitHub Actions OIDC — no tokens, no OTP):
+`.github/workflows/publish.yml` fires on `v*` tags; the trusted publisher on the npm package
+points at `NINKCH/dsh-artcraft` / `publish.yml`. To cut a release: bump `version`, commit,
+`git tag v0.x.y && git push origin v0.x.y`.
+
+## License
+
+**This plugin (`@ninkch/dsh-artcraft`): Apache-2.0** — see [LICENSE](LICENSE). It ships none of the
+ArtCraft apps' code — it only drives their public automation surfaces (headless CLI + JSON
+control channel).
+
+**The ArtCraft apps themselves** are *not* OSI open source: they are distributed under the
+**ArtCraft License (WIP)**, a "fair source" license ([verbatim text](NOTICE.md)). The short
+version for anyone building on them:
+
+- ✅ free to use; back up, copy, modify and compile for private purposes
+- ✅ **every piece of media you create with the apps is yours** — your rendered episodes are
+  commercial assets, full stop
+- ❌ no selling the apps as your own software, no competing products built from their code
+- ❌ no stripping community/donation links from a fork; no using the ArtCraft name, logo or
+  mascots to promote a business without permission
+- 🤝 the team's public promise: if the business ever ends, the software transitions to an
+  OSI-approved open-source license
+
+Practical reading for an AI short-drama studio: run the apps locally, leave their community
+links alone, and sell your films — not the apps.