playcanvas-agent-bridge-cli 0.6.0 → 0.6.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.
@@ -18,7 +18,8 @@ terminal. For `LOOPBACK_ACCESS_DENIED`, retry with local-loopback permission ins
18
18
  second daemon. If no PlayCanvas target appears, ask the user to run `pcbridge install-extension`,
19
19
  load the printed directory in `chrome://extensions`, and refresh the Editor or Launch tab.
20
20
 
21
- The directory where `pcbridge daemon start` runs is the workspace root. Each ready Editor project
21
+ The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
22
+ selects it explicitly, and `daemon stop` stops the authenticated daemon. Each ready Editor project
22
23
  is mirrored into `<projectId>-<projectName>/` below it. After choosing an explicit target, run
23
24
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
24
25
  or sync error.
@@ -33,13 +34,17 @@ project-picker and scene Editor navigations; change the remembered mode only thr
33
34
  The CLI/daemon, copied agent skills, generated Chrome extension, and custom Editor frontend update
34
35
  independently. For an explicit update request:
35
36
 
36
- 1. Have the user stop the foreground daemon with Ctrl+C and preserve its working directory; no
37
- `daemon stop` command exists.
38
- 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
37
+ 1. Record the workspace root reported by `pcbridge daemon status`.
38
+ 2. Run `bun add --global playcanvas-agent-bridge-cli@latest`, check `pcbridge version`, and rerun
39
39
  `pcbridge install-skill --agent all`.
40
+ For a custom or project-local parent directory, use
41
+ `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
42
+ standard artifact name and cannot be combined with `--agent all`.
40
43
  3. Run `pcbridge install-extension --no-open`; the user must click **Reload** in
41
44
  `chrome://extensions` and refresh every open Editor/Launch tab.
42
- 4. Restart the daemon from the same workspace root and verify `pcbridge doctor`.
45
+ 4. Run `pcbridge daemon restart --workspace <original-root>` and verify `pcbridge doctor`. For a
46
+ one-time migration from a daemon without authenticated shutdown, have the user stop the old
47
+ daemon with Ctrl+C, then start the updated daemon with the same `--workspace` value.
43
48
  5. Use `pcbridge frontend update` plus `frontend status` for the separately published Editor build.
44
49
  That update is read dynamically by a running daemon, but the user must refresh the Editor page
45
50
  and choose **Use custom frontend** in the popup if official mode is selected.
@@ -56,6 +61,8 @@ pcbridge help script
56
61
  pcbridge help store
57
62
  pcbridge help target
58
63
  pcbridge help workspace
64
+ pcbridge help processing
65
+ pcbridge help import
59
66
  pcbridge help frontend
60
67
  pcbridge help entity
61
68
  pcbridge help asset
@@ -71,23 +78,53 @@ Workspace layout:
71
78
 
72
79
  ```text
73
80
  <workspace root>/<projectId>-<projectName>/
74
- pcbridge.project.json # project metadata and agent-readable asset catalog
75
- assets/ # collision-safe projection of the remote folder tree
76
- tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
77
- .pcbridge/ # internal state and object cache; do not edit
81
+ pcbridge.project.json # project metadata, scenes list, and agent-readable asset catalog (with meta summaries)
82
+ scenes/ # active writable .scene.json plus read-only (0o444) mirrors of inactive scenes
83
+ assets/ # collision-safe projection of the remote folder tree (text, *.<type>.json, pulled binaries)
84
+ tmp/ # agent files, builds, conflicts, captures, and local/remote deletion trash; never synchronized
85
+ .pcbridge/ # internal sync state, 3-way JSON baselines, and object cache; do not edit
78
86
  ```
79
87
 
80
- Prefer local operations for file-backed Assets. Edit scripts under `assets/`; create files and
81
- folders there to upload them through PlayCanvas processing; and rename or move local files to keep
82
- the same remote Asset ID. Deleting a local file only clears its local cache and does not delete the
83
- remote Asset. Use `asset delete --id <id>` only for intentional remote deletion. Scripts are eager,
84
- while binary contents are lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset
85
- <assetId>` before modifying a missing remote binary. Generated GLB Model/Container/material Assets
86
- and font atlases are lazy, read-only projections. Edit the source Asset; derivative edits or moves
87
- are quarantined and restored from `.pcbridge/objects`, never uploaded.
88
-
89
- After local writes, wait for the watcher and poll `workspace status` until `synced`. A brief
90
- `local-change` is normal. If it does not converge, run one `workspace sync`, inspect status and
88
+ Inspect local files first (0 RPC) to understand the project: read `pcbridge.project.json` (which
89
+ includes `scenes[]`, full Asset IDs/paths, and lazy binary `meta` such as texture dimensions), read
90
+ `scenes/<name>.<sceneId>.scene.json` (DFS-ordered `entities` + `settings`), and search `scenes/` and
91
+ `assets/` with `rg` instead of issuing `entity list` / `asset list` / `eval` RPCs for static
92
+ inspection.
93
+
94
+ Synchronization is event-driven via WebSocket `workspace:delta` pushes and targeted local `fs.watch`
95
+ dirty paths (zero idle polling):
96
+ - **Tier 1 (Eager bidirectional)**: Text assets (`script`, `text`, `json`, `html`, `css`, `shader`)
97
+ and structured JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`,
98
+ `bundle`, projected as `<name>.<type>.json`) up to the direct-sync limit (default **2 MB**,
99
+ adjustable **1–10 MB** via the extension popup **Direct sync limit** slider or
100
+ `pcbridge workspace settings --eager-max-mb <1..10>`) sync automatically in both directions.
101
+ - **Scenes (`scenes/<name>.<sceneId>.scene.json`)**: The active Editor scene carries
102
+ `"$pcbridge": { "id": "...", "kind": "scene", "active": true }` (`0o644` writable, automatic
103
+ `parent <-> children` reconciliation). Inactive scenes carry
104
+ `"$pcbridge": { "id": "...", "kind": "scene", "active": false, "readonly": true }` (`0o444`
105
+ read-only); run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before
106
+ editing an inactive scene.
107
+ - **Property-path 3-way merge**: Structured JSON assets and the active `.scene.json` merge against
108
+ `.pcbridge/baselines/` at property/entity granularity so non-overlapping local and Editor edits
109
+ merge cleanly; same-path conflicts write `.local`, `.remote`, and `.conflict.json` under
110
+ `tmp/conflicts/`.
111
+ - **Create, rename, and delete semantics**: Creating files under `assets/` (including new
112
+ `*.<type>.json` structured assets) creates matching remote folders/Assets and writes back
113
+ `$pcbridge.id`. Renaming or moving local files preserves the Asset ID via `$pcbridge.id`, file
114
+ inode, or content hash. **Deleting a local Tier 1 eagerly synced file backs it up to
115
+ `tmp/trash/local/` AND deletes the remote PlayCanvas Asset**; delete Tier 1 files only when remote
116
+ deletion is intended. Deleting a pulled Tier 2 lazy binary (images, models, audio, fonts, or
117
+ over-limit files; pull missing ones with `pcbridge workspace pull --target editor:<sceneId>
118
+ --asset <assetId>`) only evicts the local cache (`pcbridge asset delete --id <id>` deletes remote
119
+ Tier 2 assets).
120
+ - **Derived assets**: Binary derivatives (`container`, `model`, generated font atlases) remain lazy
121
+ and read-only (`0o444`), whereas structured JSON assets linked to a source model (such as
122
+ FBX/GLB-imported `material` files) are writable (`0o644`) and sync bidirectionally while keeping
123
+ `$pcbridge.sourceAssetId` for provenance.
124
+
125
+ After local writes, allow ~0.5–1s for the watcher debounce and poll `workspace status` until
126
+ `synced` (do not mix local file saves and CLI write RPCs on the same asset/scene simultaneously). A
127
+ brief `local-change` is normal. If it does not converge, run one `workspace sync`, inspect status and
91
128
  `tmp/conflicts/`, and never overwrite a conflict automatically. Local file
92
129
  arguments must stay inside the selected project workspace. Do not use `--allow-external-path`
93
130
  unless the user explicitly asks to use a known external file.
@@ -107,10 +144,15 @@ values. CLI equivalents are
107
144
  `pcbridge builder start --target editor:<sceneId> --asset <id>` and
108
145
  `pcbridge builder status --job <jobId>`.
109
146
 
110
- Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
111
- For ordinary file-content edits, prefer the tracked file under `assets/`:
147
+ Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and
148
+ multi-property edits in the active `.scene.json`. Use structured commands for Editor pipelines
149
+ (`scene open`, `template instantiate/create/overrides/apply`, `script parse`, `import`), explicit
150
+ transfers, and live viewport/Launch verification:
112
151
 
113
152
  ```bash
153
+ pcbridge workspace settings --eager-max-mb 2
154
+ pcbridge scene list --target editor:<sceneId>
155
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
114
156
  pcbridge entity list --target editor:<sceneId> --limit 50
115
157
  pcbridge entity create --target editor:<sceneId> --json ./entity.json
116
158
  pcbridge entity create-many --target editor:<sceneId> --json ./entities.json
@@ -122,27 +164,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
122
164
  pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
123
165
  pcbridge asset list --target editor:<sceneId> --type script
124
166
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
125
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
126
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
167
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
168
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
127
169
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
128
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
129
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
170
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
171
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
130
172
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
131
173
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
132
174
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
133
175
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
134
176
  pcbridge scene settings get --target editor:<sceneId>
135
177
  pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
136
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
137
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
178
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts" --parse --wait
179
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts"
138
180
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
139
181
  pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
140
182
  pcbridge logs get --target launch:<sceneId> --limit 100
141
183
  pcbridge logs get --target launch:<sceneId> --level error
142
184
  ```
143
185
 
144
- Organize final file-backed assets under `assets/AI Agent Bridge/<task name>/...` and disposable
145
- generation files under `tmp/<task name>/`. Use `pcbridge eval` for exploratory API inspection,
186
+ Before creating asset folders, inspect the project's existing directory tree and comparable
187
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
188
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
189
+ by task or feature within that structure; if the project groups by resource type first, preserve
190
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
191
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
192
+
193
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
194
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
195
+ illustrative; adapt them to the project's existing conventions before creating folders. Use `pcbridge eval` for exploratory API inspection,
146
196
  custom Editor/Engine workflows, and large multi-step scene edits:
147
197
 
148
198
  ```bash
@@ -182,3 +232,8 @@ scene edits or runtime verification. Use upload manifests only when explicit imp
182
232
  non-watched source path is required, then capture under `tmp/captures/` after smoke tests.
183
233
 
184
234
  Do not pre-place runtime-generated content just to prove a game exists. Keep procedural maps, pickups, enemies, and VFX in the runtime script, with only a small durable Editor root and helper entities when needed. If Editor entities must be created, use structured commands and small `entity create-many` batches with read-back verification; large eval scripts that create many entities in a tight loop can briefly show objects and then lose them from the Editor data model.
235
+
236
+
237
+ ## Self-hosted local processing
238
+
239
+ Use `pcbridge help processing` and `pcbridge help import` for self-hosted conversion. Diagnose with `processing status --target editor:<sceneId>`; tools require explicit installation and `processing enable`. Do not enable local conversion on official targets. Use `import submit --asset <id> --kind model|texture --json options.json`, then `import wait --job <id> --sync-workspace`. Server `complete` means published; workspace synchronization is separate and keeps binary lazy loading. On a wait timeout query the same job before repeating a write. Browser authentication, leases and signed URLs must never be copied into CLI arguments. Extension source upgrades require regenerating the unpacked extension, reloading it in Chrome and refreshing target pages. Custom host permissions are granted by the user through the popup.
@@ -26,8 +26,10 @@ pcbridge daemon start
26
26
  Do not start a second daemon for `LOOPBACK_ACCESS_DENIED`. That means the current execution
27
27
  environment cannot access `127.0.0.1`; retry with local-loopback permission instead.
28
28
 
29
- The directory where `pcbridge daemon start` runs is the workspace root. Choose it intentionally;
30
- each connected Editor project is mirrored into `<projectId>-<projectName>/` below that directory.
29
+ The directory where `pcbridge daemon start` runs is the default workspace root; use
30
+ `--workspace <directory>` to select it explicitly. Use `pcbridge daemon restart --workspace
31
+ <directory>` to switch roots safely, and `pcbridge daemon stop` to stop the authenticated daemon.
32
+ Each connected Editor project is mirrored into `<projectId>-<projectName>/` below that directory.
31
33
 
32
34
  If no target appears, tell the user to run `pcbridge install-extension`, load the printed directory in `chrome://extensions`, then refresh the PlayCanvas Editor or Launch tab.
33
35
 
@@ -42,14 +44,18 @@ project-picker and scene Editor navigations; change the remembered mode only thr
42
44
  Treat the CLI/daemon, installed agent skill, generated Chrome extension, and custom Editor frontend
43
45
  as separate components. When the user asks to update pcbridge:
44
46
 
45
- 1. Ask the user to stop the foreground daemon with Ctrl+C; there is no `daemon stop` command. Record
46
- its working directory so it can restart from the same workspace root.
47
- 2. Run `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
47
+ 1. Record the current workspace root from `pcbridge daemon status`.
48
+ 2. Run `bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, and reinstall
48
49
  copied skills with `pcbridge install-skill --agent all`.
50
+ For a custom or project-local parent directory, use
51
+ `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; `--path` appends the
52
+ standard artifact name and cannot be combined with `--agent all`.
49
53
  3. Run `pcbridge install-extension --no-open`. The user must click **Reload** for PlayCanvas Agent
50
54
  Bridge in `chrome://extensions` and refresh open Editor/Launch tabs; rewriting the unpacked
51
55
  directory is not enough.
52
- 4. Restart `pcbridge daemon start` from the original workspace root and verify with `pcbridge doctor`.
56
+ 4. Run `pcbridge daemon restart --workspace <original-root>` and verify with `pcbridge doctor`.
57
+ When migrating from a daemon version without authenticated shutdown, ask the user to stop that
58
+ old daemon once with Ctrl+C, then start the updated daemon with the same `--workspace` value.
53
59
  5. Update the independently published Editor build with `pcbridge frontend update`, then verify
54
60
  `frontend status`. A frontend-only update does not require daemon restart, but the user must
55
61
  refresh the Editor tab and select **Use custom frontend** in the popup when currently in official
@@ -63,21 +69,26 @@ steps have been acknowledged or verified.
63
69
  1. Run `pcbridge targets`. Use `editor:<sceneId>` for Editor writes and `launch:<sceneId>` for
64
70
  runtime verification; use `tab:<id>` when either selector is ambiguous.
65
71
  2. Run `pcbridge workspace status --target editor:<sceneId>`. Do not write while it reports a conflict or sync error.
66
- 3. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
67
- 4. Edit asset file contents locally under the selected project's `assets/` tree and let the daemon synchronize them. Keep temporary files, manifests, and captures under `tmp/`, which is not synchronized.
68
- 5. Use structured commands for scene structure and non-file Asset operations that map cleanly to one Editor action.
69
- 6. Use `pcbridge eval` for exploratory API inspection, custom Editor/Engine workflows, Launch runtime debugging, and large multi-step scene edits where one script is clearer than many CLI calls.
70
- 7. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
71
- 8. Use PlayCanvas history options for writes when available and verify writes with a read-only command.
72
+ 3. **Inspect local files first (0 RPC)** to understand the project before calling Editor RPCs:
73
+ - Read `pcbridge.project.json` for `scenes[]` (active/writable vs inactive/read-only), full asset IDs, paths, and lazy binary `meta` (texture dimensions/format, model/audio summaries).
74
+ - Read `scenes/<name>.<sceneId>.scene.json` (DFS-ordered `entities` + `settings`) and search `scenes/` + `assets/` with `rg` to trace entities, script attachments, `<name>.material.json`, `<name>.template.json`, scripts, and shaders across the entire project.
75
+ 4. Use layered help to load only the command group you need: `pcbridge help`, then `pcbridge help core|workspace|processing|import|frontend|target|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
76
+ 5. **Choose the right write path** (never mix local file edits and CLI write RPCs on the same target concurrently):
77
+ - **Edit local files** under `assets/` and `scenes/` for scripts, shaders, CSS/HTML/JSON/text, `<name>.material.json` / `<name>.template.json` / other `*.<type>.json` structured assets (including batch edits and creating new `*.<type>.json` files), file renames/moves, and ordinary property or entity edits in the **active** `.scene.json` (`"$pcbridge": { "active": true }`).
78
+ - **Use structured CLI commands** for Editor-specific pipelines: `scene open` (required before editing an inactive read-only scene), `template instantiate`, `template create --entity-id`, `template overrides`, `template apply` / `apply-many` (never hand-edit `template_ent_ids`), `script parse`, `import submit/wait`, `viewport focus/capture`, and `launch` diagnostics/logs.
79
+ 6. Keep temporary files, manifests, and captures under `tmp/`, which is never synchronized.
80
+ 7. Use `pcbridge eval` for exploratory Editor/Engine API inspection, Launch runtime debugging (`runtimeApp`), and custom Editor workflows not covered by local projections or structured commands.
81
+ 8. Return compact JSON from snippets. Never return raw `editor`, `Entity`, `Asset`, `entities.root`, or app objects.
72
82
 
73
83
  ## Workspace
74
84
 
75
85
  ```text
76
86
  <workspace root>/<projectId>-<projectName>/
77
- pcbridge.project.json # project metadata and agent-readable asset catalog
78
- assets/ # collision-safe projection of the PlayCanvas folder tree
79
- tmp/ # agent files, builds, cache, conflicts, captures, and deletion quarantine; never synchronized
80
- .pcbridge/ # internal sync state and object cache; do not edit
87
+ pcbridge.project.json # project metadata, scenes list, and agent-readable asset catalog (with meta summaries)
88
+ scenes/ # active writable .scene.json plus read-only (0o444) mirrors of inactive scenes
89
+ assets/ # collision-safe projection of the PlayCanvas folder tree (text, *.<type>.json, pulled binaries)
90
+ tmp/ # agent files, builds, conflicts, captures, and local/remote deletion trash; never synchronized
91
+ .pcbridge/ # internal sync state, 3-way JSON baselines, and object cache; do not edit
81
92
  ```
82
93
 
83
94
  Use:
@@ -85,20 +96,24 @@ Use:
85
96
  ```bash
86
97
  pcbridge workspace status --target editor:<sceneId>
87
98
  pcbridge workspace path --target editor:<sceneId>
99
+ pcbridge workspace settings [--eager-max-mb <1..10>]
88
100
  pcbridge workspace sync --target editor:<sceneId>
89
101
  pcbridge workspace pull --target editor:<sceneId> --asset <assetId>
90
102
  ```
91
103
 
92
- Prefer local file operations for file-backed Assets:
104
+ Synchronization is event-driven via WebSocket `workspace:delta` pushes and targeted local `fs.watch` dirty paths (zero idle polling):
93
105
 
94
- - Edit existing scripts directly under `assets/`; the watcher uploads them to PlayCanvas.
95
- - Create files and folders under `assets/` to upload them into the matching remote folder. Let PlayCanvas infer and process the Asset type.
96
- - Rename or move a local file to rename or move the same remote Asset ID.
97
- - Deleting a local file only removes the local lazy cache. It does not delete the remote Asset; use `pcbridge asset delete --id <id>` only when remote deletion is explicitly intended.
98
- - Scripts are downloaded eagerly. Binary files are lazy; run `workspace pull --asset <id>` before modifying a remote binary that is not present locally.
99
- - PlayCanvas-generated derivatives such as GLB Model/Container/material outputs and font atlases are lazy, read-only projections. Edit the source Asset, not a derivative. A local derivative edit or move is quarantined under `tmp/conflicts/`, restored from `.pcbridge/objects`, and never uploaded.
106
+ - **Tier 1 (Eager bidirectional)**: Text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as `<name>.<type>.json`) up to the direct-sync limit (**default `2 MB`**, adjustable **`1–10 MB`** via the extension popup **Direct sync limit** slider or `pcbridge workspace settings --eager-max-mb <1..10>`) are downloaded automatically and synced bidirectionally.
107
+ - **Scenes (`scenes/<name>.<sceneId>.scene.json`)**: `entities` are ordered in hierarchy DFS pre-order. The open Editor scene has `"$pcbridge": { "id": "...", "kind": "scene", "active": true }` (`0o644` writable); adding/removing entities locally reconciles `parent <-> children` automatically. Inactive scenes have `"$pcbridge": { "id": "...", "kind": "scene", "active": false, "readonly": true }` (`0o444` read-only) — inspect them freely with `rg`, and run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing one.
108
+ - **Property-path 3-way merge**: Structured JSON assets and the active `.scene.json` merge against `.pcbridge/baselines/` at property/entity granularity, so non-overlapping local and Editor edits merge automatically without false whole-file conflicts. True same-path conflicts write `.local`, `.remote`, and `.conflict.json` under `tmp/conflicts/`.
109
+ - **Create, rename, and move locally**: Creating files under `assets/` (including new `<name>.material.json` or other `*.<type>.json` files without an ID) creates matching remote folders and Assets and writes back `$pcbridge.id`. Renaming or moving local files preserves the remote Asset ID via `$pcbridge.id`, file inode, or content hash (even when renamed and edited together).
110
+ - **Tier 2 (Lazy binary / over-limit files)**: Images, models, audio, fonts, binaries, and files above `eagerMaxMb` record metadata, dimensions, and MD5 in `pcbridge.project.json` without downloading bytes. Run `workspace pull --asset <id>` before modifying a missing binary locally.
111
+ - **Deletion semantics (important distinction)**:
112
+ - Deleting a local **Tier 1** eagerly synced file (in-limit text/script/shader or `*.<type>.json`) **backs it up under `tmp/trash/local/` AND deletes the remote PlayCanvas Asset** to keep both sides consistent. Delete Tier 1 files only when remote deletion is intended.
113
+ - Deleting a locally pulled **Tier 2** lazy binary (or over-limit file) only evicts the local cache without deleting the remote Asset; use `pcbridge asset delete --id <id>` to delete a remote Tier 2 Asset.
114
+ - **Derived assets**: Binary derivatives (`source_asset_id != null` with a file, such as GLB `container`/`model` outputs and generated font atlases) remain lazy and read-only (`0o444`); local edits are quarantined to `tmp/conflicts/` and restored. Structured JSON assets linked to a source model (such as FBX/GLB-imported `material` files) **are writable (`0o644`)** and sync bidirectionally while keeping `$pcbridge.sourceAssetId` for provenance.
100
115
 
101
- After a local edit, allow the watcher to react, then poll `workspace status` until it reports
116
+ After a local edit, allow ~0.5–1s for the watcher debounce to flush, then check `workspace status` until it reports
102
117
  `synced`. A brief yellow `local-change` is expected. Do not declare completion or alternate to
103
118
  remote editing while the same file is pending. If it does not converge, run one explicit
104
119
  `workspace sync`, inspect `lastError`, `lastWarning`, and `tmp/conflicts/`, and do not overwrite
@@ -124,9 +139,11 @@ Local file arguments are restricted to the selected project workspace. Never use
124
139
 
125
140
  ## Safe Commands
126
141
 
127
- Inspect a scene:
142
+ Prefer reading local `pcbridge.project.json`, `scenes/*.scene.json`, and `assets/` first for static inspection. Use CLI commands when you need live Editor/Launch state, pipeline actions, or single targeted RPC mutations:
128
143
 
129
144
  ```bash
145
+ pcbridge scene list --target editor:<sceneId>
146
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
130
147
  pcbridge eval --target editor:<sceneId> --code "return { href: location.href, hasEditor: !!editor, entityCount: editor.api.globals.entities.list().length }"
131
148
  ```
132
149
 
@@ -169,25 +186,24 @@ Use exactly one of `--asset-id` and `--script-name`. The name form is for a Scri
169
186
  by a bundle or runtime asset and therefore lacking a standalone script asset id. Verify such a
170
187
  script in Launch; explicit script reordering is not yet a dedicated command.
171
188
 
172
- Work with asset metadata, explicit transfers, and script verification. For ordinary file-content
173
- edits, prefer editing the tracked local file under `assets/` over `script set-text` or re-uploading it:
189
+ Work with asset pipelines, explicit transfers, and script verification. For ordinary script/shader/text or `*.material.json` / `*.template.json` content edits, prefer editing the tracked local file under `assets/` over CLI `patch` / `set-text` or re-uploading:
174
190
 
175
191
  ```bash
176
192
  pcbridge asset list --target editor:<sceneId> --type script --limit 50
177
193
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
178
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
179
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
194
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
195
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
180
196
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
181
197
  pcbridge asset instantiate --target editor:<sceneId> --id <template_asset_id>
182
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
198
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
183
199
  pcbridge material patch --target editor:<sceneId> --asset-id <material_asset_id> --set diffuse='[1,0,0]'
184
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
200
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
185
201
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
186
202
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
187
203
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
188
204
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
189
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
190
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "AI Agent Bridge/My Task/Scripts"
205
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "My Task/Scripts" --parse --wait
206
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./controller.js --folder "My Task/Scripts"
191
207
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./controller.js --parse --wait
192
208
  pcbridge script parse --target editor:<sceneId> --asset-id <id>
193
209
  ```
@@ -241,16 +257,16 @@ authoritative.
241
257
 
242
258
  ## Asset Organization
243
259
 
244
- Create synchronized files directly under a task-scoped path in the project `assets/` tree. Keep
245
- intermediate or disposable generation files under `tmp/` so the watcher does not upload them:
260
+ Before creating asset folders, inspect the project's existing directory tree and comparable
261
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
262
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
263
+ by task or feature within that structure; if the project groups by resource type first, preserve
264
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
265
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
246
266
 
247
- ```text
248
- assets/AI Agent Bridge/<task name>/Textures
249
- assets/AI Agent Bridge/<task name>/Models
250
- assets/AI Agent Bridge/<task name>/Scripts
251
- ```
252
-
253
- Use stable names that describe the asset purpose. Avoid dumping generated files at the project root.
267
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
268
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
269
+ illustrative; adapt them to the project's existing conventions before creating folders.
254
270
 
255
271
  ## Large Task Workflow
256
272
 
@@ -258,11 +274,11 @@ For multi-asset or game-sized tasks:
258
274
 
259
275
  1. Choose an explicit target from `pcbridge targets`, preferably `editor:<sceneId>` for writes or
260
276
  `launch:<sceneId>` for tests; use `tab:<id>` to resolve ambiguity.
261
- 2. Confirm `workspace status` is `synced`. Put disposable generation inputs under `<project>/tmp/<task name>/`.
262
- 3. Put final scripts, textures, models, audio, and other file-backed Assets under `<project>/assets/AI Agent Bridge/<task name>/...`; create or edit them locally and wait for synchronization.
277
+ 2. Confirm `workspace status` is `synced`. Inspect `pcbridge.project.json`, `scenes/*.scene.json`, and `assets/` locally with `rg` to understand existing hierarchy, conventions, and asset IDs without extra RPC traffic. Put disposable generation inputs under `<project>/tmp/<task name>/`.
278
+ 3. Follow existing folder naming and hierarchy. Group new resources within that convention, reuse suitable folders, and create or edit scripts, shaders, `*.material.json` files, and assets locally under `<project>/assets/`; wait for `workspace status` to reach `synced`.
263
279
  4. Use `asset upload-many` only when explicit upload settings or a non-watched source path is required. Do not upload a file again when it is already tracked under `assets/`.
264
280
  5. For an existing script, edit its local file. Use `script parse` after synchronization when parse verification is needed; reserve `script upsert --parse --wait` for recovery or workflows that intentionally bypass the mirror.
265
- 6. Use `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./args.json --timeout-ms 120000` for large scene installation scripts. The JSON object is available as `command.args`; increase `--timeout-ms` instead of splitting a coherent install script just to avoid the default 15s timeout.
281
+ 6. For active scene edits, either edit `scenes/<name>.<sceneId>.scene.json` directly (ideal for multi-entity/property tuning with 3-way merge) or use structured `entity` / `template` commands (or `pcbridge eval --target editor:<sceneId> --file ./install.js --args-json ./args.json --timeout-ms 120000` for procedural Editor setup). Do not edit `.scene.json` and run scene-mutating RPCs at the exact same instant.
266
282
  7. Wait for `workspace status` to become `synced`, then verify with read-only commands, a small smoke-test eval, and a capture under `<project>/tmp/captures/`.
267
283
 
268
284
  If repeated manual glue is needed across tasks, improve the CLI or this skill rather than continuing to hand-roll brittle shell/script sequences.
@@ -285,10 +301,10 @@ That verification is limited to the current Editor observer and does not prove r
285
301
  For a textured scripted box, compose structured commands instead of writing one large eval:
286
302
 
287
303
  ```bash
288
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/Texture Box/Textures"
289
- pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "AI Agent Bridge/Texture Box/Textures"
290
- pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "AI Agent Bridge/Texture Box/Materials" --diffuse-map <texture_asset_id>
291
- pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "AI Agent Bridge/Texture Box/Scripts"
304
+ pcbridge asset folder ensure --target editor:<sceneId> --path "Texture Box/Textures"
305
+ pcbridge asset upload --target editor:<sceneId> --file ./image.png --name TextureBoxImage --folder "Texture Box/Textures"
306
+ pcbridge material create --target editor:<sceneId> --name TextureBoxMaterial --folder "Texture Box/Materials" --diffuse-map <texture_asset_id>
307
+ pcbridge script create --target editor:<sceneId> --filename jumpingBox.js --file ./jumpingBox.js --folder "Texture Box/Scripts"
292
308
  pcbridge entity create --target editor:<sceneId> --json ./box.json
293
309
  pcbridge entity set-material --target editor:<sceneId> --id <box_resource_id> --material-id <material_asset_id>
294
310
  pcbridge entity add-script --target editor:<sceneId> --id <box_resource_id> --asset-id <script_asset_id> --attributes '{"height":0.5,"speed":2.4}'
@@ -333,3 +349,8 @@ return entities.slice(0, 20).map((entity) => ({
333
349
  ```
334
350
 
335
351
  Avoid destructive operations unless the user clearly asked for them. When deleting or overwriting, require explicit stable IDs and report affected counts.
352
+
353
+
354
+ ## Self-hosted local processing
355
+
356
+ Use `pcbridge help processing` and `pcbridge help import` for self-hosted conversion. Diagnose with `processing status --target editor:<sceneId>`; tools require explicit installation and `processing enable`. Do not enable local conversion on official targets. Use `import submit --asset <id> --kind model|texture --json options.json`, then `import wait --job <id> --sync-workspace`. Server `complete` means published; workspace synchronization is separate and keeps binary lazy loading. On a wait timeout query the same job before repeating a write. Browser authentication, leases and signed URLs must never be copied into CLI arguments. Extension source upgrades require regenerating the unpacked extension, reloading it in Chrome and refreshing target pages. Custom host permissions are granted by the user through the popup.
@@ -17,29 +17,51 @@ pcbridge targets
17
17
  Run `pcbridge daemon start` only for `DAEMON_NOT_LISTENING`; for `LOOPBACK_ACCESS_DENIED`, retry
18
18
  with local-loopback permission. If no target appears, ask the user to install/reload the extension.
19
19
 
20
- Updates are component-specific. For an explicit update request, have the user stop the foreground
21
- daemon with Ctrl+C and remember its workspace-root directory; there is no `daemon stop`. Run
22
- `npm install -g playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
23
- `pcbridge install-skill --agent all`. Regenerate the extension with
20
+ Updates are component-specific. For an explicit update request, record the workspace root from
21
+ `pcbridge daemon status`. Run
22
+ `bun add --global playcanvas-agent-bridge-cli@latest`, verify `pcbridge version`, then rerun
23
+ `pcbridge install-skill --agent all`. For a custom or project-local parent directory, use
24
+ `pcbridge install-skill --agent <one-agent> --path <parent-directory>`; it appends the standard
25
+ artifact name and cannot be combined with `--agent all`. Regenerate the extension with
24
26
  `pcbridge install-extension --no-open`; the user must manually click **Reload** in
25
- `chrome://extensions` and refresh Editor/Launch tabs. Restart the daemon from the original workspace
26
- root and verify `pcbridge doctor`. Update the independently published Editor build with
27
+ `chrome://extensions` and refresh Editor/Launch tabs. Run `pcbridge daemon restart --workspace
28
+ <original-root>` and verify `pcbridge doctor`. A daemon version without authenticated shutdown must
29
+ be stopped once with Ctrl+C before starting the updated daemon. Update the independently published Editor build with
27
30
  `pcbridge frontend update` and `frontend status`; a frontend-only update needs no daemon restart,
28
31
  but the Editor tab must be refreshed and custom mode selected in the popup when necessary. Do not
29
32
  claim completion before these manual steps are confirmed.
30
33
 
31
- The daemon start directory is the workspace root. After selecting an explicit target, run
34
+ The current directory is the default workspace root; `daemon start/restart --workspace <directory>`
35
+ selects it explicitly, and `daemon stop` stops the authenticated daemon. After selecting a target, run
32
36
  `pcbridge workspace status --target editor:<sceneId>` and do not write while it reports a conflict
33
- or sync error. Project files live under `<projectId>-<projectName>/{assets,tmp}`. Prefer local
34
- operations for file-backed Assets: edit scripts under `assets/`; create files/folders there to
35
- upload through PlayCanvas processing; rename or move locally to preserve the remote Asset ID.
36
- Deleting locally only clears the cache, never the remote Asset. Scripts are eager and binaries are
37
- lazy; use `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before editing a missing
38
- binary. Generated GLB Model/Container/material Assets and font atlases are lazy, read-only
39
- projections: edit the source Asset. Derivative edits or moves are quarantined, restored from
40
- `.pcbridge/objects`, and never uploaded. `tmp/` is never synced.
41
- After a local write, poll `workspace status` until `synced`; a brief `local-change` is expected.
42
- If it does not converge, run one `workspace sync` and inspect status plus `tmp/conflicts/`.
37
+ or sync error. Project files live under `<projectId>-<projectName>/{pcbridge.project.json,scenes,assets,tmp}`.
38
+ Inspect local files first (0 RPC) to understand the project: read `pcbridge.project.json` (scenes list,
39
+ full asset catalog, and lazy binary `meta` such as texture dimensions), read `scenes/<name>.<sceneId>.scene.json`
40
+ (DFS-ordered `entities` + `settings`), and search `scenes/` + `assets/` with `rg` before calling RPCs.
41
+
42
+ Sync is event-driven via WebSocket `workspace:delta` and targeted `fs.watch` dirty paths (zero idle polling):
43
+ - Tier 1 eager bidirectional: text assets (`script`, `text`, `json`, `html`, `css`, `shader`) and structured
44
+ JSON data assets (`material`, `template`, `cubemap`, `sprite`, `animstategraph`, `bundle`, projected as
45
+ `<name>.<type>.json`) up to the direct-sync limit (default 2 MB, adjustable 1–10 MB via the extension popup
46
+ slider or `pcbridge workspace settings --eager-max-mb <1..10>`).
47
+ - Scenes: the active open scene has `"$pcbridge": { "active": true }` (`0o644` writable, auto-reconciling
48
+ `parent <-> children`); inactive scenes have `"$pcbridge": { "active": false, "readonly": true }` (`0o444`
49
+ read-only — run `pcbridge scene open --target editor:<currentSceneId> --id <targetSceneId>` before editing).
50
+ - Structured JSON assets and the active `.scene.json` use property-path 3-way merge against `.pcbridge/baselines/`
51
+ so non-overlapping local and Editor edits merge automatically; same-path conflicts write `.local`, `.remote`,
52
+ and `.conflict.json` under `tmp/conflicts/`.
53
+ - Create files under `assets/` (including new `*.<type>.json` assets) to create remote folders/Assets; rename or
54
+ move locally to preserve the Asset ID via `$pcbridge.id`, inode, or MD5. **Deleting a local Tier 1 eagerly
55
+ synced file backs it up to `tmp/trash/local/` AND deletes the remote Asset** (delete Tier 1 files only when
56
+ remote deletion is intended). Images, models, audio, fonts, and over-limit files are Tier 2 lazy (use
57
+ `pcbridge workspace pull --target editor:<sceneId> --asset <id>` before modifying missing bytes; deleting a
58
+ pulled Tier 2 file only evicts local cache).
59
+ - Binary derivatives (`container`, `model`, font atlases) remain lazy and read-only (`0o444`), whereas structured
60
+ JSON assets linked to a source model (such as FBX/GLB-imported `material` files) are writable (`0o644`) and
61
+ keep `$pcbridge.sourceAssetId` for provenance. `tmp/` is never synced.
62
+ After a local write, allow ~0.5–1s for debounce and poll `workspace status` until `synced` (do not mix local saves
63
+ and CLI write RPCs on the same asset/scene concurrently). If it does not converge, run one `workspace sync` and
64
+ inspect status plus `tmp/conflicts/`.
43
65
  Read schema-v3 `pcbridge.project.json.assets`: `folder` is the remote display path,
44
66
  `projectionPath` is the unique local path, and `origin`/`remoteFile`/`local` describe role,
45
67
  effective metadata, presence, writability, and hashes. Only collisions gain
@@ -57,12 +79,16 @@ For the optional published Editor build, use `pcbridge frontend install latest`,
57
79
  The popup remembers that choice per project and reapplies it on later project-picker and scene
58
80
  Editor navigations; change the remembered choice only through the popup.
59
81
 
60
- Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help target|workspace|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
82
+ Use layered help to load only the command surface you need: `pcbridge help`, then `pcbridge help core|target|workspace|processing|import|frontend|entity|asset|material|template|script|scene|store|viewport|launch|logs|eval`.
61
83
 
62
- Use structured commands for scene structure, Asset metadata, explicit transfers, and verification.
63
- For normal file-content changes, prefer editing the tracked local file under `assets/`:
84
+ Prefer local file edits for scripts, shaders, text, `*.material.json` / `*.template.json` data, and multi-property
85
+ edits in the active `.scene.json`. Use structured commands for Editor pipelines (`scene open`,
86
+ `template instantiate/create/overrides/apply`, `script parse`, `import`), explicit transfers, and live verification:
64
87
 
65
88
  ```bash
89
+ pcbridge workspace settings --eager-max-mb 2
90
+ pcbridge scene list --target editor:<sceneId>
91
+ pcbridge scene open --target editor:<sceneId> --id <otherSceneId>
66
92
  pcbridge entity list --target editor:<sceneId> --limit 50
67
93
  pcbridge entity patch --target editor:<sceneId> --id <resource_id> --set name=Player
68
94
  pcbridge entity duplicate --target editor:<sceneId> --id <resource_id>
@@ -72,27 +98,35 @@ pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --asset-
72
98
  pcbridge entity add-script --target editor:<sceneId> --id <resource_id> --script-name sdsAudioPlayer --attributes-json ./audio-slots.json
73
99
  pcbridge asset list --target editor:<sceneId> --type script
74
100
  pcbridge asset create --target editor:<sceneId> --json ./assets.json
75
- pcbridge asset folder ensure --target editor:<sceneId> --path "AI Agent Bridge/My Task/Textures"
76
- pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "AI Agent Bridge/My Task/Textures"
101
+ pcbridge asset folder ensure --target editor:<sceneId> --path "My Task/Textures"
102
+ pcbridge asset upload --target editor:<sceneId> --file ./texture.png --name TaskTexture --folder "My Task/Textures"
77
103
  pcbridge asset upload-many --target editor:<sceneId> --json ./upload-manifest.json
78
- pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "AI Agent Bridge/My Task/Materials" --diffuse-map <texture_asset_id>
79
- pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "AI Agent Bridge/My Task/Templates"
104
+ pcbridge material create --target editor:<sceneId> --name TaskMaterial --folder "My Task/Materials" --diffuse-map <texture_asset_id>
105
+ pcbridge template create --target editor:<sceneId> --entity-id <resource_id> --name TaskTemplate --folder "My Task/Templates"
80
106
  pcbridge template instantiate --target editor:<sceneId> --id <template_asset_id>
81
107
  pcbridge template overrides --target editor:<sceneId> --entity-id <resource_id>
82
108
  pcbridge template apply --target editor:<sceneId> --entity-id <resource_id>
83
109
  pcbridge template apply-many --target editor:<sceneId> --json ./template-roots.json
84
110
  pcbridge scene settings get --target editor:<sceneId>
85
111
  pcbridge viewport focus --target editor:<sceneId> --id <resource_id> --view perspective
86
- pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts" --parse --wait
87
- pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "AI Agent Bridge/My Task/Scripts"
112
+ pcbridge script upsert --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts" --parse --wait
113
+ pcbridge script create --target editor:<sceneId> --filename controller.js --file ./script.js --folder "My Task/Scripts"
88
114
  pcbridge script set-text --target editor:<sceneId> --asset-id <id> --file ./script.js --parse --wait
89
115
  pcbridge viewport capture --target editor:<sceneId> --out ./tmp/playcanvas.png
90
116
  pcbridge logs get --target launch:<sceneId> --limit 100
91
117
  pcbridge logs get --target launch:<sceneId> --level error
92
118
  ```
93
119
 
94
- Put final file-backed assets under `assets/AI Agent Bridge/<task name>/...`; keep disposable
95
- generation files under `tmp/<task name>/`.
120
+ Before creating asset folders, inspect the project's existing directory tree and comparable
121
+ resources. Prefer reusing suitable folders and follow the project's naming language, casing,
122
+ separators, hierarchy, and resource grouping when new folders are needed. Organize related assets
123
+ by task or feature within that structure; if the project groups by resource type first, preserve
124
+ that layout rather than imposing a task-first hierarchy. Do not create an `AI Agent Bridge` folder
125
+ by default. If no convention exists, use a descriptive task folder with resource subfolders as needed.
126
+
127
+ Keep final file-backed assets in the project `assets/` tree and intermediate or disposable files
128
+ under `tmp/<task name>/` so the watcher does not upload them. Paths in command examples are
129
+ illustrative; adapt them to the project's existing conventions before creating folders.
96
130
 
97
131
  Use `pcbridge launch diagnose` and `pcbridge launch wait-ready --focus` before runtime assertions.
98
132
  Launch `lifecycleReady` is a best-effort heuristic based on an owned graphics canvas/context,
@@ -119,3 +153,8 @@ explicit import settings or a non-watched path is required. File arguments must
119
153
  workspace; never use `--allow-external-path` without explicit user approval.
120
154
 
121
155
  Do not pre-place runtime-generated content just to prove a game exists. Keep procedural maps, pickups, enemies, and VFX in the runtime script, with only a small durable Editor root and helper entities when needed. If Editor entities must be created, use structured commands and small `entity create-many` batches with read-back verification; large eval scripts that create many entities in a tight loop can briefly show objects and then lose them from the Editor data model.
156
+
157
+
158
+ ## Self-hosted local processing
159
+
160
+ Use `pcbridge help processing` and `pcbridge help import` for self-hosted conversion. Diagnose with `processing status --target editor:<sceneId>`; tools require explicit installation and `processing enable`. Do not enable local conversion on official targets. Use `import submit --asset <id> --kind model|texture --json options.json`, then `import wait --job <id> --sync-workspace`. Server `complete` means published; workspace synchronization is separate and keeps binary lazy loading. On a wait timeout query the same job before repeating a write. Browser authentication, leases and signed URLs must never be copied into CLI arguments. Extension source upgrades require regenerating the unpacked extension, reloading it in Chrome and refreshing target pages. Custom host permissions are granted by the user through the popup.