@vivix-labs/studio-workbench 0.0.0-stage → 1.0.0-beta.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (105) hide show
  1. package/dist/Inter-LICENSE.txt +93 -0
  2. package/dist/UI-LICENSE.txt +21 -0
  3. package/dist/assets/35a50-G5EJUNOC.svg +6 -0
  4. package/dist/assets/369ca-BISNKZ3M.svg +6 -0
  5. package/dist/assets/441bc-BCMNQ72W.svg +6 -0
  6. package/dist/assets/483f0-T6ZAGTDG.svg +6 -0
  7. package/dist/assets/6911b-ESLYKSC6.svg +6 -0
  8. package/dist/assets/Inter-LICENSE.txt +93 -0
  9. package/dist/assets/UI-system-LICENSE.txt +21 -0
  10. package/dist/assets/add-JY533O73.svg +5 -0
  11. package/dist/assets/area-P2WOMBT5.svg +9 -0
  12. package/dist/assets/b70bb-BTTOKPOH.svg +6 -0
  13. package/dist/assets/b9919-3S3O6YOT.svg +6 -0
  14. package/dist/assets/calendar-JI6USFRJ.svg +1 -0
  15. package/dist/assets/check-JSRRIXN5.svg +5 -0
  16. package/dist/assets/check-on-content-FQUVG3IZ.svg +5 -0
  17. package/dist/assets/chevron-down-K7YKS2EY.svg +5 -0
  18. package/dist/assets/chevron-left-JQCLK2WZ.svg +3 -0
  19. package/dist/assets/chevron-right-TNE35DBJ.svg +3 -0
  20. package/dist/assets/chevron-up-VBHYAJVB.svg +5 -0
  21. package/dist/assets/clear-XNEZJKFC.svg +5 -0
  22. package/dist/assets/close-GO5F7YFS.svg +10 -0
  23. package/dist/assets/dccd4-CZJXWICW.svg +6 -0
  24. package/dist/assets/dd163-3S3O6YOT.svg +6 -0
  25. package/dist/assets/detail-E52XPONK.svg +4 -0
  26. package/dist/assets/draw-FOFX5TOM.svg +6 -0
  27. package/dist/assets/e8aed-CZJXWICW.svg +6 -0
  28. package/dist/assets/ea990-CZJXWICW.svg +6 -0
  29. package/dist/assets/edit-JUVJDD5A.svg +6 -0
  30. package/dist/assets/expand-IAV75AFA.svg +6 -0
  31. package/dist/assets/export-W2OBXZDQ.svg +6 -0
  32. package/dist/assets/fullscreen-L2JCXIN2.svg +6 -0
  33. package/dist/assets/fullscreen-large-MPLIWDMI.svg +6 -0
  34. package/dist/assets/grid-TLG5JYWB.svg +8 -0
  35. package/dist/assets/hero-base-5KRPU5WN.png +0 -0
  36. package/dist/assets/hero-blossom-YNVLGEJJ.webp +0 -0
  37. package/dist/assets/hero-blossom-sequence-TZ74A6VV.webp +0 -0
  38. package/dist/assets/hero-breeze-sequence-CEWDK3QZ.webp +0 -0
  39. package/dist/assets/hero-landscape-H35LYO4H.png +0 -0
  40. package/dist/assets/hero-placeholder-strip-WAPZ6XF4.svg +28 -0
  41. package/dist/assets/hero-pointer-OOZJGR5D.svg +17 -0
  42. package/dist/assets/hero-shot-CNLBX3OX.png +0 -0
  43. package/dist/assets/import-AFBUV2VV.svg +4 -0
  44. package/dist/assets/inria-serif-latin-700-italic-UNRIXGAH.woff2 +0 -0
  45. package/dist/assets/inter-latin-400-normal-55WT6UWF.woff2 +0 -0
  46. package/dist/assets/inter-latin-500-normal-W62DVTXI.woff2 +0 -0
  47. package/dist/assets/inter-latin-600-normal-R6Y2SZCR.woff2 +0 -0
  48. package/dist/assets/inter-latin-700-normal-SU5XVJMF.woff2 +0 -0
  49. package/dist/assets/list-5VUAOZUH.svg +9 -0
  50. package/dist/assets/local-user-MIBWBA6X.png +0 -0
  51. package/dist/assets/magic-OMME7FOV.svg +9 -0
  52. package/dist/assets/more-AEJ5MHWV.svg +5 -0
  53. package/dist/assets/mute-SXOSCR2U.svg +6 -0
  54. package/dist/assets/mute-large-LSZZ44HF.svg +6 -0
  55. package/dist/assets/nav-assets-35EAQZQX.svg +7 -0
  56. package/dist/assets/nav-home-BMDOUQGN.svg +5 -0
  57. package/dist/assets/nav-projects-N5UV3GAG.svg +6 -0
  58. package/dist/assets/nav-queue-2I5E65F4.svg +8 -0
  59. package/dist/assets/pause-2E4UY4FW.svg +6 -0
  60. package/dist/assets/pause-large-XEUBL4KC.svg +6 -0
  61. package/dist/assets/placeholder-audio-EJEBE7OB.svg +11 -0
  62. package/dist/assets/placeholder-image-NOVXFVRL.svg +10 -0
  63. package/dist/assets/placeholder-script-LR2GKWKS.svg +7 -0
  64. package/dist/assets/placeholder-video-ZFOYHYCR.svg +7 -0
  65. package/dist/assets/play-WIIT3XQK.svg +5 -0
  66. package/dist/assets/play-cover-WQLOHHPZ.svg +5 -0
  67. package/dist/assets/playback-play-YRMIX5W4.svg +5 -0
  68. package/dist/assets/playback-play-large-TM3QUJGG.svg +5 -0
  69. package/dist/assets/player-cover-shade-LLH6KOCQ.png +0 -0
  70. package/dist/assets/reset-JESMTEMV.svg +6 -0
  71. package/dist/assets/search-JUOSGQRM.svg +6 -0
  72. package/dist/assets/select-VU7WR7B4.svg +7 -0
  73. package/dist/assets/social-preview-F36PFR67.svg +91 -0
  74. package/dist/assets/sound-file-YYY6VNYN.svg +3 -0
  75. package/dist/assets/template-1-NR5GMMN5.png +0 -0
  76. package/dist/assets/template-2-YUHY6VN5.png +0 -0
  77. package/dist/assets/template-3-JHX6FHCZ.png +0 -0
  78. package/dist/assets/template-4-TAVSM3BI.png +0 -0
  79. package/dist/assets/template-5-ESABL4EM.png +0 -0
  80. package/dist/assets/template-6-4FAHO5N4.png +0 -0
  81. package/dist/assets/template-7-2KRMROJ6.png +0 -0
  82. package/dist/assets/volume-2TYGJL6F.svg +6 -0
  83. package/dist/assets/volume-large-QNULSJ2I.svg +6 -0
  84. package/dist/client.bundle.js +5693 -0
  85. package/dist/client.css +3914 -0
  86. package/dist/client.d.ts +15 -0
  87. package/dist/client.js +3 -0
  88. package/dist/server.d.ts +9 -0
  89. package/dist/server.js +381 -0
  90. package/dist/shared.d.ts +57 -0
  91. package/dist/shared.js +78 -0
  92. package/home-media/product-ad.mp4 +0 -0
  93. package/home-media/short-drama.mp4 +0 -0
  94. package/home-media/tree-shadow-blossom.mp4 +0 -0
  95. package/home-media/tree-shadow-breeze.mp4 +0 -0
  96. package/licenses/Inria-Serif-OFL.txt +93 -0
  97. package/package.json +77 -3
  98. package/presets/table.json +61 -0
  99. package/presets/user-base.json +118 -0
  100. package/skills/SKILL.md +100 -0
  101. package/skills/references/assets-and-views.md +30 -0
  102. package/skills/references/sql-custom-views.md +8 -0
  103. package/skills/scripts/initialize-home.mjs +245 -0
  104. package/studio-plugin.json +31 -0
  105. package/README.md +0 -3
package/package.json CHANGED
@@ -1,6 +1,80 @@
1
1
  {
2
2
  "name": "@vivix-labs/studio-workbench",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "1.0.0-beta.2",
4
+ "type": "module",
5
+ "publishConfig": {
6
+ "access": "public",
7
+ "registry": "https://registry.npmjs.org/",
8
+ "tag": "beta"
9
+ },
10
+ "license": "MIT",
11
+ "files": [
12
+ "dist",
13
+ "home-media",
14
+ "licenses",
15
+ "studio-plugin.json",
16
+ "skills",
17
+ "presets/user-base.json",
18
+ "presets/table.json"
19
+ ],
20
+ "engines": {
21
+ "node": ">=22.12.0"
22
+ },
23
+ "exports": {
24
+ "./studio-plugin.json": "./studio-plugin.json",
25
+ "./server": {
26
+ "types": "./dist/server.d.ts",
27
+ "import": "./dist/server.js"
28
+ },
29
+ "./shared": {
30
+ "types": "./dist/shared.d.ts",
31
+ "import": "./dist/shared.js"
32
+ },
33
+ "./client": {
34
+ "types": "./dist/client.d.ts",
35
+ "import": "./dist/client.js"
36
+ }
37
+ },
38
+ "peerDependencies": {
39
+ "vivix-studio": ">=2.2.0",
40
+ "react": "19.3.1",
41
+ "react-dom": "^19.0.0"
42
+ },
43
+ "dependencies": {
44
+ "archiver": "7.0.1"
45
+ },
46
+ "devDependencies": {
47
+ "@types/archiver": "7.0.0",
48
+ "@vivix-labs/project-studio": "1.0.0-beta.2",
49
+ "@vivix-labs/ui-system": "1.0.0-beta.2"
50
+ },
51
+ "vivixStudio": {
52
+ "runtimePlugins": {
53
+ "@vivix-labs/ads-compare": "1.0.0-beta.2",
54
+ "@vivix-labs/ads-storyboard": "1.0.0-beta.2",
55
+ "@vivix-labs/creative-data": "1.0.0-beta.2",
56
+ "@vivix-labs/dashboard-assets": "1.0.0-beta.2",
57
+ "@vivix-labs/dashboard-projects": "1.0.0-beta.2",
58
+ "@vivix-labs/magic-edit": "1.0.0-beta.2",
59
+ "@vivix-labs/material-library": "1.0.0-beta.2",
60
+ "@vivix-labs/media-tools": "1.0.0-beta.2",
61
+ "@vivix-labs/project-studio": "1.0.0-beta.2",
62
+ "@vivix-labs/short-drama-characters": "1.0.0-beta.2",
63
+ "@vivix-labs/short-drama-compare": "1.0.0-beta.2",
64
+ "@vivix-labs/short-drama-production": "1.0.0-beta.2",
65
+ "@vivix-labs/short-drama-script-editor": "1.0.0-beta.2",
66
+ "@vivix-labs/short-drama-social-preview": "1.0.0-beta.2",
67
+ "@vivix-labs/short-drama-storyboard": "1.0.0-beta.2",
68
+ "@vivix-labs/short-drama-workbench": "1.0.0-beta.2",
69
+ "@vivix-labs/studio-asset-list": "1.0.0-beta.2",
70
+ "@vivix-labs/studio-workbench": "1.0.0-beta.2",
71
+ "@vivix-labs/vivix-api": "1.0.0-beta.2",
72
+ "@vivix-labs/ads-workbench": "1.0.0-beta.2",
73
+ "@vivix-labs/chat-components": "1.0.0-beta.2",
74
+ "@vivix-labs/short-drama-authoring": "1.0.0-beta.2"
75
+ }
76
+ },
77
+ "scripts": {
78
+ "build": "node ../../scripts/build-product-packages.mjs studio-workbench"
79
+ }
6
80
  }
@@ -0,0 +1,61 @@
1
+ {
2
+ "presetVersion": "0.1",
3
+ "id": "table",
4
+ "title": "Project table",
5
+ "scope": "project",
6
+ "plugins": [
7
+ {
8
+ "id": "api",
9
+ "package": "@vivix-labs/vivix-api",
10
+ "version": "1.0.0-beta.2",
11
+ "enabled": true,
12
+ "config": {},
13
+ "requiredAccess": ["official.request"]
14
+ },
15
+ {
16
+ "id": "studio",
17
+ "package": "@vivix-labs/project-studio",
18
+ "version": "1.0.0-beta.2",
19
+ "enabled": true,
20
+ "config": {
21
+ "role": "project",
22
+ "dataInstance": "user:data",
23
+ "apiInstance": "api",
24
+ "libraryInstance": "user:library",
25
+ "coordinatorInstance": "user:coordinator"
26
+ },
27
+ "requiredAccess": ["events.publish"]
28
+ },
29
+ {
30
+ "id": "library",
31
+ "package": "@vivix-labs/material-library",
32
+ "version": "1.0.0-beta.2",
33
+ "enabled": true,
34
+ "config": {
35
+ "role": "client",
36
+ "serviceInstance": "user:library"
37
+ }
38
+ },
39
+ {
40
+ "id": "workbench",
41
+ "package": "@vivix-labs/studio-workbench",
42
+ "version": "1.0.0-beta.2",
43
+ "enabled": true,
44
+ "config": {
45
+ "studioInstance": "studio",
46
+ "apiInstance": "api",
47
+ "dataInstance": "user:data",
48
+ "libraryInstance": "library",
49
+ "libraryServiceInstance": "user:library"
50
+ },
51
+ "requiredAccess": ["events.subscribe"]
52
+ }
53
+ ],
54
+ "workspace": {
55
+ "frontend": {
56
+ "plugin": "workbench",
57
+ "id": "table-workbench"
58
+ },
59
+ "settings": {}
60
+ }
61
+ }
@@ -0,0 +1,118 @@
1
+ {
2
+ "presetVersion": "0.1",
3
+ "id": "user-base",
4
+ "title": "Personal studio",
5
+ "scope": "user",
6
+ "plugins": [
7
+ {
8
+ "id": "data",
9
+ "package": "@vivix-labs/creative-data",
10
+ "version": "1.0.0-beta.2",
11
+ "enabled": true,
12
+ "config": {},
13
+ "requiredAccess": ["project.content.read"]
14
+ },
15
+ {
16
+ "id": "library",
17
+ "package": "@vivix-labs/material-library",
18
+ "version": "1.0.0-beta.2",
19
+ "enabled": true,
20
+ "config": {
21
+ "role": "service",
22
+ "dataInstance": "data",
23
+ "serviceInstance": "library"
24
+ }
25
+ },
26
+ {
27
+ "id": "api",
28
+ "package": "@vivix-labs/vivix-api",
29
+ "version": "1.0.0-beta.2",
30
+ "enabled": true,
31
+ "config": {},
32
+ "requiredAccess": ["official.request"]
33
+ },
34
+ {
35
+ "id": "coordinator",
36
+ "package": "@vivix-labs/project-studio",
37
+ "version": "1.0.0-beta.2",
38
+ "enabled": true,
39
+ "config": {
40
+ "role": "coordinator",
41
+ "dataInstance": "data",
42
+ "apiInstance": "api",
43
+ "libraryInstance": "library"
44
+ },
45
+ "requiredAccess": ["events.publish"]
46
+ },
47
+ {
48
+ "id": "magic-edit",
49
+ "package": "@vivix-labs/magic-edit",
50
+ "version": "1.0.0-beta.2",
51
+ "enabled": true,
52
+ "config": {}
53
+ },
54
+ {
55
+ "id": "dashboard-projects",
56
+ "package": "@vivix-labs/dashboard-projects",
57
+ "version": "1.0.0-beta.2",
58
+ "enabled": true,
59
+ "config": {
60
+ "studioInstance": "coordinator"
61
+ }
62
+ },
63
+ {
64
+ "id": "dashboard-assets",
65
+ "package": "@vivix-labs/dashboard-assets",
66
+ "version": "1.0.0-beta.2",
67
+ "enabled": true,
68
+ "config": {
69
+ "studioInstance": "coordinator"
70
+ }
71
+ },
72
+ {
73
+ "id": "asset-list",
74
+ "package": "@vivix-labs/studio-asset-list",
75
+ "version": "1.0.0-beta.2",
76
+ "enabled": true,
77
+ "config": {}
78
+ },
79
+ {
80
+ "id": "workbench",
81
+ "package": "@vivix-labs/studio-workbench",
82
+ "version": "1.0.0-beta.2",
83
+ "enabled": true,
84
+ "config": {
85
+ "studioInstance": "coordinator",
86
+ "apiInstance": "api",
87
+ "dataInstance": "data",
88
+ "libraryInstance": "library",
89
+ "libraryServiceInstance": "library",
90
+ "magicEditInstance": "magic-edit",
91
+ "dashboard": [
92
+ {
93
+ "plugin": "dashboard-projects",
94
+ "id": "projects"
95
+ },
96
+ {
97
+ "plugin": "dashboard-assets",
98
+ "id": "assets"
99
+ }
100
+ ],
101
+ "views": {
102
+ "assetList": {
103
+ "plugin": "asset-list",
104
+ "id": "asset-list"
105
+ }
106
+ }
107
+ },
108
+ "requiredAccess": ["events.subscribe"]
109
+ }
110
+ ],
111
+ "workspace": {
112
+ "frontend": {
113
+ "plugin": "workbench",
114
+ "id": "studio-home"
115
+ },
116
+ "settings": {}
117
+ }
118
+ }
@@ -0,0 +1,100 @@
1
+ ---
2
+ name: vivix-studio-workbench
3
+ description: Operate the installed Vivix Studio workbench, saved Custom Views, fixed-version favorites. Use for workbench-specific asset selection; use public operation discovery for the installed version.
4
+ ---
5
+
6
+ # Operate the installed workbench
7
+
8
+ Use `agent guide --json` to locate the installed workspace Skill for project
9
+ selection, page opening, and host-adapted result presentation. Discover actual
10
+ instances, operations, and enabled plugin Skills before unfamiliar work.
11
+
12
+ Read [assets and views](references/assets-and-views.md) for project assets,
13
+ immutable versions, fixed favorites, saved SQL views, import/reference semantics,
14
+ and task recovery. Advertising projects use the separately installed advertising
15
+ workbench Skill. Discover available presets with `preset list`.
16
+
17
+ Keep the current choice distinct from the newest candidate. Ordinary file
18
+ projects use explicit adoption. Advertising clips may select their first saved
19
+ readable candidate automatically; later candidates preserve the existing choice.
20
+ Use the installed behavior rather than introducing another selection policy.
21
+
22
+ Persist business changes through public operations with the observed revisions.
23
+ Show the actual selected or edited media in chat and keep the matching workbench
24
+ view available. A recipe, saved view, accepted task, and finished file are different
25
+ results. Read back the corresponding state before reporting completion.
26
+
27
+ ## Project cover
28
+
29
+ On Manage Projects, open a project's action menu to upload, change, or remove
30
+ its cover. An image's menu in Global Asset can use the saved version as the
31
+ cover. For an Agent making the same change, discover `projects.get` and
32
+ `projects.update` on the actual project studio instance. Use the observed project
33
+ revision and set `changes.coverRef` to a saved image's exact VersionRef from that
34
+ project, or to `null` to remove it. Verify the saved reference and refresh Manage
35
+ Projects to see it on both the project card and sidebar.
36
+
37
+ ## Refresh the affected workbench
38
+
39
+ After an operation succeeds and changes data shown in an open workbench, check that the
40
+ affected page has no unsaved edits, then refresh that page once through browser control.
41
+ If edits are unsaved or their state is uncertain, preserve them and ask the user to save
42
+ or finish editing before a refresh. If browser control is unavailable, tell the user which
43
+ workbench page to refresh manually. A failed or unknown operation needs its error or
44
+ original-intent recovery first; refreshing never retries the operation.
45
+
46
+ Workbench lists and details load on navigation and browser refresh. User-initiated
47
+ favorites and completed file imports update the affected list once after success; a batch
48
+ updates once after all items finish. Background generation continues independently. To
49
+ see its latest progress after an Agent operation, use the same saved-edit check and one
50
+ page refresh. Keep the user's current page and fixed media version when checking results.
51
+
52
+ `library.usage` accepts materialId, optional versionId, limit (1–200, default50)
53
+ and offset (default0). Its response is `{items,nextOffset}`; continue until
54
+ nextOffset is null. Usage rows identify the material version and target project,
55
+ asset and version. Usage count is distinct active target assets, not relation rows.
56
+ Use each actual scope's describe output to discover configured instance IDs;
57
+ custom projects need not use the default studio/api IDs or enable the library.
58
+
59
+ For image.edit only, when the raw model is image, explicitly sets
60
+ requires_explicit_source_roles=false and has source_roles=[], the installed
61
+ workbench derives a local implicit-image descriptor (one required fixed image,
62
+ no weight). This is a local mapping, not a Provider-declared role; upload sends
63
+ the real image as source_assets without a remote role. image.generate needs no
64
+ reference. Explicit roles keep their declared validation.
65
+
66
+ ## Set up Studio Home
67
+
68
+ After installing the matching official archives, run this package's
69
+ `skills/scripts/initialize-home.mjs` with Node in the intended Studio profile.
70
+ It applies the user preset and creates two editable example projects. Use
71
+ `--no-open` to print their IDs and the Home bookmark. Rerun it to resume an
72
+ incomplete setup.
73
+
74
+ Home composes user-scope components from the workbench instance's
75
+ `config.dashboard` array of `{ "plugin": "instance-id", "id": "ui-id" }`
76
+ references. The official user preset supplies the separate `dashboard-projects`
77
+ and `dashboard-assets` instances, with the component IDs `projects` and `assets`.
78
+ To add a card, create or reuse a user-scope component, enable its provider, and
79
+ append its reference, for example `{ "plugin": "usage", "id": "summary" }`.
80
+ The card can read operations of its declared dependencies. Render it with Studio UI
81
+ System controls and inherit the workbench's semantic colors.
82
+
83
+ Each official Preset entry identifies its own installable plugin and registered
84
+ component or contributed page. A plugin can still register several views. Read the
85
+ view prompt for the scope, package, component ID and route.
86
+
87
+ Each `config.savedViews` item is one shortcut. A `{ "plugin": "instance-id",
88
+ "id": "ui-id" }` shortcut renders the selected user-scope component inside Home.
89
+ A `{ "projectId": "...", "viewId": "...", "title": "..." }` shortcut opens the
90
+ existing project and its declared navigation ID. To save Social Preview, use
91
+ the actual project ID and the contributed route `social:preview`. Two UI IDs
92
+ from the same enabled plugin can have their own shortcuts. Views saved through
93
+ the Assets table editor appear as table tabs on that page.
94
+
95
+ Enable local component providers in the same user scope before adding
96
+ references. Update the full composition with `project configure --scope user
97
+ --file <file>` and preserve unrelated instance settings. Remove references
98
+ before disabling a provider. If the Host returns `USER_SCOPE_IN_USE`, let the
99
+ active projects finish and restart the Host before applying the user change. An incompatible or disabled dependency can stop
100
+ Home from activating. Restore the prior composition if needed.
@@ -0,0 +1,30 @@
1
+ # Project assets and installed views
2
+
3
+ Use the installed `vivix-studio` executable and its public `--help` commands. When several installations are present, verify `--version` before working.
4
+
5
+ The workspace and project catalog use the installed dev CLI's configuration root. Read `project --help`, `plugin --help` and `preset --help` for the public commands; there is no second workspace runtime or automatic migration of old candidate data. Keep credentials in the Host.
6
+
7
+ 1. Discover instances and operations with `plugin list --scope user --json` and `plugin describe <instance> --scope user --json`.
8
+ 2. Create or register projects through the CLI project commands. Apply the independently distributed `user-base` and `table` presets to their own scopes; explicitly grant required access. Browser pages use the Host catalog and embedded real project workbenches.
9
+ 3. Use `--project <projectId>` for project operations. Browser file upload streams to the configured data instance's `stage` HTTP route, then passes its opaque staging ID to `assets.import`, `assets.importVersion`, `library.import` or `library.importVersion` through ordinary operations. Do not pass arbitrary Host file paths as staging IDs.
10
+ 4. Create text through `assets.createText`; content edits use `assets.saveText` with a fixed parentVersionId. Names and tags use `assets.update` or `library.update`, `expectedRevision` and a stable request key. Tags are `data.tags` arrays, never filenames or metadata. List `tag` is an exact member match.
11
+ 5. Discover the actual model catalog through api capabilities.list/get. Do not invent roles or parameters, silently drop unsupported input, change models or treat a video as an image. Fixed references must be readable VersionRefs in the target project; copy library materials first.
12
+ 6. `generation.submit` explicitly declares `confirm: 'none'` with paid effects and requires the paired API 0.2.2 Host. Image, video, and audio generation submits without local browser approval, including separate shots, changed parameters, and new requests after known failures. Keep estimates, cost records, and the original input and key for each request. Other paid and destructive operations retain their required approvals. Unknown submissions may be charged: use tasks.queryOriginal to recover them. tasks.retryDownload saves original results and never regenerates. A new generation uses a new request key and retryOfTaskId; an unknown original also requires acknowledgeUnknown after reconciliation.
13
+ 7. `files.resolveLocation` returns the absolute path of a specific version and a local preview URL. Existing tools can process a copy; import the result through ordinary business operations. Preserve immutable files and identify externally processed results as imported content.
14
+ 8. For concurrent edits, use the revision you actually read. A conflict retains the input; inspect the current revision and ask which changes should survive. Do not transparently retry against a newer revision.
15
+ 9. Structured records are the source of truth. Use the installed public business operations for scoped reads and writes. When the installed coordinator exposes `global.query` and the workbench exposes `views.*`, read [SQL Custom Views](sql-custom-views.md). Their absence means this package does not supply that workflow; do not add a second runtime or open the live database to bypass the public binding.
16
+ 10. Workspace backups use storage.backup, never a raw copy of an active SQLite file. Restore validates a separate set and requires a stopped-host maintenance switch. Keep the current set until validation succeeds. No credentials belong in backups.
17
+
18
+ `library.usage` accepts materialId, optional versionId, limit (1–200, default50)
19
+ and offset (default0). Its response is `{items,nextOffset}`; continue until
20
+ nextOffset is null. Usage rows identify the material version and target project,
21
+ asset and version. Usage count is distinct active target assets, not relation rows.
22
+ Use each actual scope's describe output to discover configured instance IDs;
23
+ custom projects need not use the default studio/api IDs or enable the library.
24
+
25
+ For image.edit only, when the raw model is image, explicitly sets
26
+ requires_explicit_source_roles=false and has source_roles=[], the installed
27
+ workbench derives a local implicit-image descriptor (one required fixed image,
28
+ no weight). This is a local mapping, not a Provider-declared role; upload sends
29
+ the real image as source_assets without a remote role. image.generate needs no
30
+ reference. Explicit roles keep their declared validation.
@@ -0,0 +1,8 @@
1
+ # SQL Custom Views — capability-dependent reference
2
+
3
+ Use this reference only when the installed `plugin describe` output exposes the named SQL, view, favorite and export operations. The ecommerce baseline may not supply them; this document does not install those implementations.
4
+
5
+ 9. Use the coordinator's `global.query` operation for the full `studio_projects`, `studio_assets`, `studio_asset_versions` and `studio_tasks` SQL sources. Queries are read-only and scoped by the data binding; keep filters and ordering in SQL before pagination. Do not open or attach the live database from a browser or bypass the public binding. Project assets keep their original identity; no library copy is required.
6
+ 10. Discover the workbench's `views.list` and `views.save` operations. Persist SQL, scalar params, column configuration and identity mapping in user data. A column `path` is the exact projected result name, including aliases and dots. `format: categories` applies only to the multivalue metadata projection selected by the Agent; do not hardcode a business classification key or mark every string array as a category. Purpose may be hidden. Aggregate projections without business identity are display-only. Use the saved view's revision for edits.
7
+ 11. Favorites are independent persisted records pinned to the selected VersionRef. The default asset projection shows the latest saved version. Query `studio_asset_versions WHERE favorite = 1` to retain older favorited versions after a new version is saved. Download uses the selected fixed references through `exports.prepare` and the Plugin's native POST attachment stream; never buffer the full archive into a browser Blob.
8
+ 12. Import only text, image, video and audio through a real project's existing import operation. Generic files are rejected. Global Asset aggregates project assets and does not create unowned personal assets. Generation Queue displays persisted task names; recovery operations remain available to agents but are hidden from the redesigned UI.
@@ -0,0 +1,245 @@
1
+ import { execFile, spawn } from 'node:child_process';
2
+ import { mkdir, readFile, readdir, realpath, rename, rm, writeFile } from 'node:fs/promises';
3
+ import { homedir } from 'node:os';
4
+ import { basename, dirname, join, resolve, sep } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { promisify } from 'node:util';
7
+
8
+ const exec = promisify(execFile);
9
+ const args = process.argv.slice(2);
10
+ if (args.includes('--help')) {
11
+ console.log(
12
+ 'Usage: node initialize-home.mjs [--no-open] [--add-cobalt]\nUse VIVIX_STUDIO_CLI to select a CLI executable or built JS entry.',
13
+ );
14
+ process.exit(0);
15
+ }
16
+ if (args.some((arg) => !['--no-open', '--add-cobalt'].includes(arg)))
17
+ throw Error('Unknown option. Use --help.');
18
+ const executable = process.env.VIVIX_STUDIO_CLI || 'vivix-studio';
19
+ const js = /\.[cm]?js$/.test(executable);
20
+ const command = js ? process.execPath : executable;
21
+ const prefix = js ? [resolve(executable)] : [];
22
+ const root = join(process.env.XDG_CONFIG_HOME || join(homedir(), '.config'), 'vivix-studio');
23
+ const userPackage = JSON.parse(
24
+ await readFile(new URL('../../package.json', import.meta.url), 'utf8'),
25
+ );
26
+ const userPreset = `${userPackage.name}@${userPackage.version}:user-base`;
27
+ const adsPackage = '@vivix-labs/ads-workbench';
28
+ const adsVersion = userPackage.vivixStudio.runtimePlugins[adsPackage];
29
+ const adsPreset = `${adsPackage}@${adsVersion}:ads`;
30
+ const dramaPreset = '@vivix-labs/short-drama-workbench:short-drama';
31
+ const scopes = [
32
+ { id: 'out-of-steps', preset: dramaPreset, skill: 'vivix-out-of-steps-example' },
33
+ { id: 'cobalt-headphones', preset: adsPreset, skill: 'vivix-cobalt-example' },
34
+ ];
35
+ const access =
36
+ 'project.content.read,project.content.write,official.request,events.publish,events.subscribe';
37
+ const homeState = join(root, 'home-initialization.json');
38
+ const lock = homeState + '.lock';
39
+ const read = async (path) => JSON.parse(await readFile(path, 'utf8'));
40
+ const state = { projects: {} };
41
+ const save = async () => {
42
+ await writeFile(homeState + '.tmp', JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
43
+ await rename(homeState + '.tmp', homeState);
44
+ };
45
+
46
+ async function linkedSeed(project, skill, packageName, version) {
47
+ const links = join(project.root, '.agents', 'skills');
48
+ const pluginRoot = await realpath(join(root, 'plugins'));
49
+ for (const entry of await readdir(links, { withFileTypes: true })) {
50
+ if (!entry.isSymbolicLink()) continue;
51
+ const target = await realpath(join(links, entry.name)).catch(() => null);
52
+ if (!target?.startsWith(pluginRoot + sep) || basename(target) !== skill) continue;
53
+ const pkg = await read(join(target, '..', '..', 'package.json'));
54
+ if (pkg.name === packageName && pkg.version === version)
55
+ return join(target, 'scripts', 'initialize.mjs');
56
+ }
57
+ throw Error('Cannot find the installed seed Skill: ' + skill);
58
+ }
59
+
60
+ async function cli(...arguments_) {
61
+ let stdout;
62
+ try {
63
+ ({ stdout } = await exec(command, [...prefix, ...arguments_, '--json'], {
64
+ maxBuffer: 8 * 1024 * 1024,
65
+ }));
66
+ } catch (error) {
67
+ if (!error.stdout) throw error;
68
+ stdout = error.stdout;
69
+ }
70
+ const result = JSON.parse(stdout);
71
+ if (!result.ok) throw Error(result.error?.message ?? 'Studio CLI command failed.');
72
+ return result.data;
73
+ }
74
+ let child;
75
+ let stopped = false;
76
+ function interrupt(signal) {
77
+ stopped = true;
78
+ child?.kill(signal);
79
+ }
80
+ function runSeed(path, project) {
81
+ return new Promise((done, reject) => {
82
+ child = spawn(process.execPath, [path, '--project', project, '--apply'], { stdio: 'inherit' });
83
+ child.on('error', reject);
84
+ child.on('close', (code) => {
85
+ child = undefined;
86
+ if (code === 0) done();
87
+ else reject(Error('Example import stopped. Rerun initialization to resume.'));
88
+ });
89
+ });
90
+ }
91
+ function assertRunning() {
92
+ if (stopped) throw Error('Initialization stopped. Rerun it to resume.');
93
+ }
94
+
95
+ await mkdir(dirname(homeState), { recursive: true, mode: 0o700 });
96
+ try {
97
+ await mkdir(lock, { mode: 0o700 });
98
+ } catch (error) {
99
+ if (error.code === 'EEXIST')
100
+ throw Error(
101
+ `Home initialization is locked. If no initializer is running, remove ${lock} and rerun.`,
102
+ );
103
+ throw error;
104
+ }
105
+ const sigint = () => interrupt('SIGINT');
106
+ const sigterm = () => interrupt('SIGTERM');
107
+ process.on('SIGINT', sigint);
108
+ process.on('SIGTERM', sigterm);
109
+ try {
110
+ try {
111
+ Object.assign(state, await read(homeState));
112
+ } catch (error) {
113
+ if (error.code !== 'ENOENT') throw error;
114
+ }
115
+ const addingCobalt = args.includes('--add-cobalt');
116
+ if (!state.complete || (addingCobalt && !state.projects['cobalt-headphones']?.complete)) {
117
+ // Resume an older unfinished Home using its original project identities.
118
+ const requested =
119
+ state.projects['rhode-summer-launch'] && !state.complete && !addingCobalt
120
+ ? [
121
+ scopes[0],
122
+ { id: 'rhode-summer-launch', preset: adsPreset, skill: 'vivix-rhode-example' },
123
+ ]
124
+ : scopes;
125
+ const { presets } = await cli('preset', 'list');
126
+ const dramaPackage = '@vivix-labs/short-drama-workbench';
127
+ const drama = presets.find(
128
+ (item) =>
129
+ item.package === dramaPackage &&
130
+ item.version === userPackage.vivixStudio.runtimePlugins[dramaPackage] &&
131
+ item.presetId === 'short-drama',
132
+ );
133
+ if (
134
+ !drama ||
135
+ !presets.some(
136
+ (item) =>
137
+ item.package === adsPackage && item.version === adsVersion && item.presetId === 'ads',
138
+ ) ||
139
+ !['user-base'].every((presetId) =>
140
+ presets.some(
141
+ (item) =>
142
+ item.package === userPackage.name &&
143
+ item.version === userPackage.version &&
144
+ item.presetId === presetId,
145
+ ),
146
+ )
147
+ )
148
+ throw Error(
149
+ 'Install the matching Home, Short Drama and Advertising preset packages before initializing Home.',
150
+ );
151
+ if (!state.workspace) {
152
+ const user = await cli('plugin', 'list', '--scope', 'user');
153
+ if (user.instances.length) {
154
+ const installed = user.instances.find((item) => item.id === 'workbench');
155
+ if (installed?.package !== userPackage.name || installed.version !== userPackage.version)
156
+ throw Error(
157
+ 'This profile already has a different user workbench. Use a fresh profile for first setup.',
158
+ );
159
+ } else {
160
+ await cli(
161
+ 'preset',
162
+ 'apply',
163
+ userPreset,
164
+ '--scope',
165
+ 'user',
166
+ '--trust',
167
+ '--allow-access',
168
+ access,
169
+ );
170
+ }
171
+ state.workspace = true;
172
+ await save();
173
+ }
174
+ for (const spec of requested) {
175
+ assertRunning();
176
+ const preset =
177
+ spec.preset === dramaPreset ? `${drama.package}@${drama.version}:short-drama` : spec.preset;
178
+ let receipt = state.projects[spec.id];
179
+ const directory = join(root, 'projects', 'studio-home-examples', spec.id);
180
+ const { projects } = await cli('project', 'list');
181
+ if (!receipt) {
182
+ if (projects.some((item) => item.root === directory))
183
+ throw Error('The example directory is already registered: ' + directory);
184
+ receipt = state.projects[spec.id] = { directory, preset };
185
+ await save();
186
+ }
187
+ if (receipt.complete) continue;
188
+ if (!receipt.projectId) {
189
+ const registered = projects.find(
190
+ (item) => item.root === receipt.directory && item.available,
191
+ );
192
+ const project =
193
+ registered ??
194
+ (await cli(
195
+ 'project',
196
+ 'init',
197
+ spec.id,
198
+ '--directory',
199
+ receipt.directory,
200
+ '--preset',
201
+ receipt.preset,
202
+ '--trust',
203
+ '--allow-access',
204
+ access,
205
+ ));
206
+ receipt.projectId = project.id;
207
+ await save();
208
+ }
209
+ assertRunning();
210
+ const project = (await cli('project', 'list')).projects.find(
211
+ (item) => item.id === receipt.projectId && item.available,
212
+ );
213
+ if (!project) throw Error('The example project is unavailable: ' + receipt.projectId);
214
+ await cli('project', 'open', '--project', project.id, '--no-open');
215
+ const seed =
216
+ spec.preset === adsPreset
217
+ ? await linkedSeed(project, spec.skill, adsPackage, adsVersion)
218
+ : await linkedSeed(
219
+ project,
220
+ spec.skill,
221
+ drama.package,
222
+ receipt.preset.split('@').at(-1).split(':')[0],
223
+ );
224
+ await runSeed(seed, project.id);
225
+ receipt.complete = true;
226
+ await save();
227
+ }
228
+ state.complete = true;
229
+ await save();
230
+ }
231
+ assertRunning();
232
+ if (args.includes('--no-open')) {
233
+ const { workbenchUrl } = await cli('project', 'open', '--scope', 'user', '--no-open');
234
+ console.log(JSON.stringify({ ok: true, projects: state.projects, workbenchUrl }));
235
+ } else {
236
+ await exec(command, [...prefix, 'project', 'open', '--scope', 'user']);
237
+ }
238
+ } catch (error) {
239
+ console.error(error.message);
240
+ process.exitCode = 1;
241
+ } finally {
242
+ process.off('SIGINT', sigint);
243
+ process.off('SIGTERM', sigterm);
244
+ await rm(lock, { recursive: true, force: true });
245
+ }