@palettelab/cli 0.3.57 → 0.3.58

package/README.md

@@ -4,6 +4,20 @@ Developer CLI for building plugins for the Palette platform. Works without any a
 
 The installed executable is `pltt`.
 
+## API Surface Split
+
+Use the right helper for the runtime you are coding in:
+
+| Runtime | Package/helper | Use it for |
+|---|---|---|
+| Frontend TypeScript/React | `@palettelab/sdk`, `createPaletteClient(...)`, `palette.*` | UI code, current-user OS APIs, frontend broker clients, Data Room browsing/upload from the browser, toasts, and current-user OS notifications |
+| Backend Python/FastAPI | `palette_sdk`, `PluginContext`, `ctx.*`, `services(ctx)` | Backend routes, permission gates, app-owned data, migrations, cross-user notifications, server-side Data Rooms, managed services, app-to-app service handlers, and lifecycle hooks |
+| CLI tooling | `pltt ...` | Scaffolding, local dev, testing, packaging, publishing, hosted sandbox previews, and generating frontend/backend typed service clients |
+
+The CLI bundles `palette_sdk` for local backend simulation, but backend app
+code should import `palette_sdk`, not `@palettelab/sdk`. Frontend app code
+should import `@palettelab/sdk`, not `palette_sdk`.
+
 ## Requirements
 
 - Node.js 18+
@@ -337,7 +351,12 @@ async def sync_invoices(ctx: PluginContext = Depends(get_plugin_context)):
 
 Storage upload responses include both snake_case and camelCase aliases for object metadata (`object_path`/`objectPath`, `file_url`/`fileUrl`, `content_type`/`contentType`) so local simulator and hosted OS responses can be consumed with the same app code.
 
-App storage is different from Data Room uploads. Use `ctx.storage` or `palette.storage` for app-owned files written directly to the OS-configured storage backend, currently GCS in hosted environments. Use `ctx.data_rooms` / `palette.dataRooms` only when the file should be managed as a Data Room document.
+App storage is different from Data Room uploads. Backend Python code uses
+`ctx.storage`; frontend TypeScript code uses `palette.storage`. Both write
+app-owned files directly to the OS-configured storage backend, currently GCS in
+hosted environments. Use backend `ctx.data_rooms` or frontend
+`palette.dataRooms` only when the file should be managed as a Data Room
+document.
 
 Python backend app-storage example:
 

package/docs/python-backend-sdk.md

@@ -881,7 +881,12 @@ Example mock:
 }
 ```
 
-App storage is separate from Data Rooms. Use `ctx.storage` and `palette.storage` for app-owned files that go directly to the OS-configured storage backend, currently GCS in hosted environments. Use `ctx.data_rooms` or `palette.dataRooms` only when the file should be visible and governed as a Data Room document.
+App storage is separate from Data Rooms. Backend Python code uses
+`ctx.storage`; frontend TypeScript code uses `palette.storage`. Both write
+app-owned files directly to the OS-configured storage backend, currently GCS in
+hosted environments. Use backend `ctx.data_rooms` or frontend
+`palette.dataRooms` only when the file should be visible and governed as a Data
+Room document.
 
 Palette scopes storage the same way. Files written through `ctx.storage` or the
 frontend storage client live under:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.57",
+  "version": "0.3.58",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"