@palettelab/cli 0.3.26 → 0.3.28

package/README.md

@@ -195,6 +195,10 @@ internal platform parity checks with `pltt dev --platform`.
 
 ## App-Owned Data, Migrations, And Python Backends
 
+For a detailed Python backend SDK guide with route examples, app-owned data,
+migrations, Data Rooms, config, secrets, lifecycle hooks, and hosted sandbox
+testing, see [Python Backend SDK Developer Guide](./docs/python-backend-sdk.md).
+
 Palette apps can own their own Python backend, database tables, migrations, and
 organization-scoped data. The generated database template uses this structure:
 
@@ -366,13 +370,19 @@ By default this starts:
 
 - A small local app shell on the first available port starting at http://localhost:3000
 - A local FastAPI backend runner on the first available port starting at http://localhost:8000
-- A mock Palette platform context for `usePlatform()`, toasts, org/user data, and authenticated API calls
+- A mock Palette platform context for `usePlatform()`, OS language, toasts, org/user data, and authenticated API calls
 - A plugin-local SQLite database under `.palette/dev/` when `capabilities.database` or `database` is enabled
 
 Your frontend entry is bundled and watched. Your backend entry is loaded under
 `/api/v1/plugins/<your-id>/*` with a dev `PluginContext`, so normal SDK calls
 work without Docker or platform source.
 
+The simulator also provides the same language fields that Palette OS provides:
+`language`, `fallbackLanguage`, `supportedLanguages`, and `setLanguage()`.
+Generated frontend templates include app-owned `frontend/src/translations.ts`
+files wired through `usePluginTranslations()`, so apps can switch when the OS
+language changes without storing copy in the platform.
+
 For Python apps with database tables, `ctx.db` is an async SQLAlchemy session in
 local dev. The simulator imports `backend/api/models.py` when present and creates
 tables from `palette_sdk.db.PluginBase.metadata`. Production installs still use
@@ -495,7 +505,7 @@ If no publish ID is provided, the CLI uses `.palette/last-publish.json` when ava
 Fetch or stream telemetry events for a plugin.
 
 ```bash
-pltt logs hello-sdk --env staging
+pltt logs my-plugin --env staging
 pltt logs --tail 100
 pltt logs --follow
 pltt logs --json

package/backend-sdk/palette_sdk/db/alembic_env.py

@@ -11,8 +11,10 @@ invokes Alembic:
   - ``PALETTE_PLUGIN_ID``  — plugin id; determines the target schema
                              (``app_<sanitized_id>``) and version table schema.
   - ``PALETTE_DB_URL``     — SQLAlchemy async URL for the plugin's DB.
-  - ``PALETTE_PLUGIN_ROLE`` (optional) — role the migration should run as;
-                             defaults to the connecting user (so DDL works).
+  - ``PALETTE_PLUGIN_ROLE`` (optional) — schema-limited role the migration
+                             should run as; the hosted platform sets this to
+                             ``plugin_migrator_<sanitized_id>``. Local/manual
+                             runs default to the connecting user.
 
 Plugin devs running ``alembic upgrade head`` locally without those vars get
 a helpful error rather than a scribbled-on main DB.

package/docs/python-backend-sdk.md

@@ -0,0 +1,641 @@
+# Palette Python Backend SDK Developer Guide
+
+This guide is for developers building Palette apps with a Python/FastAPI
+backend. Frontend code uses the npm package `@palettelab/sdk`; Python backend
+code uses `palette_sdk`, which is embedded in `@palettelab/cli` for local dev
+and provided by the Palette runtime in hosted sandbox and production.
+
+## 1. Where The Backend Runs
+
+Palette supports three backend development modes:
+
+| Mode | Command | Uses real Palette OS services | Docker |
+|---|---|---:|---:|
+| Local SDK simulator | `pltt dev` | No | No |
+| Hosted sandbox preview | `pltt dev --sandbox --env staging` | Yes | No |
+| Internal local platform parity | `pltt dev --platform` | Local platform container | Yes |
+
+Use `pltt dev` for the fastest loop while writing code. Use hosted sandbox
+when the app must use real OS features such as login, organization context,
+Data Rooms, storage, install state, review previews, logs, and platform APIs.
+
+## 2. Generated App Structure
+
+A Python backend app normally looks like this:
+
+```text
+my-app/
+  palette-plugin.json
+  frontend/
+    src/index.tsx
+  backend/
+    api/
+      main.py
+      models.py
+    migrations/
+      env.py
+      versions/
+        001_init.py
+```
+
+The backend entry is declared in `palette-plugin.json`:
+
+```json
+{
+  "id": "finance-tools",
+  "name": "Finance Tools",
+  "frontend": { "entry": "./frontend/src/index.tsx" },
+  "backend": { "entry": "./backend/api/main.py" },
+  "permissions": [
+    "resources:read",
+    "resources:write",
+    "data_rooms:read",
+    "data_rooms:write"
+  ],
+  "capabilities": { "database": true },
+  "database": {
+    "schema": "app_finance_tools",
+    "migrations": "./backend/migrations"
+  }
+}
+```
+
+Declare only the permissions your app actually needs. Backend routes should
+also gate access with `require_permission(...)`.
+
+## 3. Basic Backend Route
+
+Every backend file exports a `PluginRouter`. Routes are mounted by the platform
+under `/api/v1/plugins/<plugin-id>`.
+
+```python
+from fastapi import Depends
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context
+
+router = PluginRouter(tags=["finance-tools"])
+
+
+@router.get("/me")
+async def me(ctx: PluginContext = Depends(get_plugin_context)):
+    return {
+        "user_id": ctx.user_id,
+        "organization_id": ctx.organization_id,
+        "org_role": ctx.org_role,
+        "plugin_id": ctx.plugin_id,
+    }
+```
+
+If the app id is `finance-tools`, this route is available at:
+
+```text
+GET /api/v1/plugins/finance-tools/me
+```
+
+## 4. PluginContext Reference
+
+`PluginContext` is injected into each route:
+
+```python
+async def route(ctx: PluginContext = Depends(get_plugin_context)):
+    ...
+```
+
+Available context values:
+
+| Field/helper | Purpose |
+|---|---|
+| `ctx.db` | Async SQLAlchemy session for the app backend |
+| `ctx.user_id` | Authenticated Palette user id |
+| `ctx.organization_id` | Current organization id |
+| `ctx.org_role` | User role in the current organization |
+| `ctx.plugin_id` | Current app/plugin id |
+| `ctx.permissions` | Permissions granted from `palette-plugin.json` |
+| `ctx.storage` | Runtime storage service, when available |
+| `ctx.data_rooms` | Backend Data Room client |
+| `ctx.config` | App install/config values |
+| `ctx.logger` | Runtime logger for backend code |
+| `ctx.repo(Model)` | Org-safe CRUD helper for app-owned tables |
+| `ctx.has_permission(permission)` | Check one declared permission |
+| `ctx.has_any_permission([...])` | Check at least one permission |
+| `ctx.has_all_permissions([...])` | Check every listed permission |
+| `ctx.config_value(key, default)` | Read optional config |
+| `ctx.require_config(key)` | Read required config or raise |
+| `ctx.secret(key, default)` | Read a secret from app config or environment |
+
+## 5. Permissions
+
+Use route-level permission guards for normal APIs:
+
+```python
+from fastapi import Depends
+from palette_sdk import (
+    PluginRouter,
+    PluginContext,
+    get_plugin_context,
+    require_permission,
+)
+
+router = PluginRouter(tags=["finance-tools"])
+
+
+@router.get("/reports", dependencies=[require_permission("resources:read")])
+async def reports(ctx: PluginContext = Depends(get_plugin_context)):
+    return {"items": []}
+```
+
+Use inline checks only when the route supports multiple behavior paths:
+
+```python
+@router.get("/dashboard", dependencies=[require_permission("resources:read")])
+async def dashboard(ctx: PluginContext = Depends(get_plugin_context)):
+    can_write = ctx.has_permission("resources:write")
+    can_sync = ctx.has_all_permissions(["data_rooms:read", "data_rooms:write"])
+
+    return {
+        "can_write": can_write,
+        "can_sync": can_sync,
+    }
+```
+
+Known permissions currently include:
+
+```text
+tasks:read, tasks:write
+data_rooms:read, data_rooms:write
+agents:read, agents:write
+chat:read, chat:write
+routines:read, routines:write
+members:read
+resources:read, resources:write
+```
+
+## 6. App-Owned Data
+
+Apps can ship their own tables and migrations. Use `OrgScopedTable` for data
+that belongs to an organization.
+
+`backend/api/models.py`:
+
+```python
+from sqlalchemy import Numeric, String
+from sqlalchemy.orm import Mapped, mapped_column
+from palette_sdk import OrgScopedTable
+
+
+class Invoice(OrgScopedTable):
+    __tablename__ = "invoices"
+
+    id: Mapped[int] = mapped_column(primary_key=True)
+    customer_name: Mapped[str] = mapped_column(String(255), nullable=False)
+    amount: Mapped[float] = mapped_column(Numeric(12, 2), nullable=False)
+    status: Mapped[str] = mapped_column(String(32), default="draft")
+```
+
+`OrgScopedTable` adds `organization_id` automatically. Do not manually set
+`organization_id` in route code; `ctx.repo(Model)` handles it.
+
+### Migration Example
+
+`backend/migrations/versions/001_init.py`:
+
+```python
+from alembic import op
+import sqlalchemy as sa
+from palette_sdk.db import ensure_org_rls
+
+
+revision = "001_init"
+down_revision = None
+
+
+def upgrade():
+    op.create_table(
+        "invoices",
+        sa.Column("id", sa.Integer(), primary_key=True),
+        sa.Column("organization_id", sa.BigInteger(), nullable=False),
+        sa.Column("customer_name", sa.String(length=255), nullable=False),
+        sa.Column("amount", sa.Numeric(12, 2), nullable=False),
+        sa.Column("status", sa.String(length=32), nullable=False),
+    )
+    op.create_index("ix_invoices_org", "invoices", ["organization_id"])
+    ensure_org_rls(op, "invoices")
+
+
+def downgrade():
+    op.drop_table("invoices")
+```
+
+`ensure_org_rls(op, "invoices")` enables row-level security so each
+organization can only access its own rows.
+
+## 7. Repository CRUD
+
+Use `ctx.repo(Model)` instead of writing repeated org filters.
+
+```python
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
+from models import Invoice
+
+router = PluginRouter(tags=["finance-tools"])
+
+
+class InvoiceIn(BaseModel):
+    customer_name: str
+    amount: float
+
+
+@router.get("/invoices", dependencies=[require_permission("resources:read")])
+async def list_invoices(ctx: PluginContext = Depends(get_plugin_context)):
+    rows = await ctx.repo(Invoice).list(order_by="-id", limit=100)
+    return [
+        {
+            "id": row.id,
+            "customer_name": row.customer_name,
+            "amount": float(row.amount),
+            "status": row.status,
+        }
+        for row in rows
+    ]
+
+
+@router.post("/invoices", dependencies=[require_permission("resources:write")])
+async def create_invoice(
+    body: InvoiceIn,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    invoice = await ctx.repo(Invoice).create(
+        customer_name=body.customer_name,
+        amount=body.amount,
+    )
+    return {"id": invoice.id}
+
+
+@router.patch("/invoices/{invoice_id}", dependencies=[require_permission("resources:write")])
+async def update_invoice(
+    invoice_id: int,
+    body: InvoiceIn,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    invoice = await ctx.repo(Invoice).update(invoice_id, **body.model_dump())
+    if invoice is None:
+        raise HTTPException(status_code=404, detail="invoice not found")
+    return {"id": invoice.id}
+
+
+@router.delete("/invoices/{invoice_id}", dependencies=[require_permission("resources:write")])
+async def delete_invoice(
+    invoice_id: int,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    deleted = await ctx.repo(Invoice).delete(invoice_id)
+    if not deleted:
+        raise HTTPException(status_code=404, detail="invoice not found")
+    return {"deleted": True}
+```
+
+Repository methods:
+
+```python
+await ctx.repo(Model).list(filters=None, order_by=None, limit=100, offset=0)
+await ctx.repo(Model).count(filters=None)
+await ctx.repo(Model).get(id)
+await ctx.repo(Model).require(id)
+await ctx.repo(Model).create(**values)
+await ctx.repo(Model).update(id, **values)
+await ctx.repo(Model).delete(id)
+```
+
+## 8. Data Rooms From Python
+
+Use `ctx.data_rooms` when backend code needs to create folders, find files, or
+read/write documents in Palette Data Rooms.
+
+### Create Or Find A Room
+
+```python
+@router.post("/setup-data-room", dependencies=[require_permission("data_rooms:write")])
+async def setup_data_room(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.ensure_room(
+        "Finance",
+        description="Finance documents used by the Finance Tools app",
+    )
+    return room
+```
+
+### Create Custom Folders By Name
+
+```python
+@router.post("/setup-folders", dependencies=[require_permission("data_rooms:write")])
+async def setup_folders(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.ensure_room("Finance")
+
+    folder = await ctx.data_rooms.resolve_folder_path(
+        room["id"],
+        "Clients/Acme/Invoices/2026",
+        create=True,
+    )
+
+    return {
+        "room_id": room["id"],
+        "folder_id": folder["id"],
+        "folder_name": folder["name"],
+    }
+```
+
+`resolve_folder_path(..., create=True)` creates missing folders in the path.
+Pass a list instead of a string when folder names can contain `/`:
+
+```python
+folder = await ctx.data_rooms.resolve_folder_path(
+    room["id"],
+    ["Clients", "Acme/International", "Invoices"],
+    create=True,
+)
+```
+
+### Upload A File
+
+```python
+@router.post("/write-summary", dependencies=[require_permission("data_rooms:write")])
+async def write_summary(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.ensure_room("Finance")
+    folder = await ctx.data_rooms.resolve_folder_path(
+        room["id"],
+        "Reports/Monthly",
+        create=True,
+    )
+
+    file = await ctx.data_rooms.upload_file(
+        room["id"],
+        "summary.txt",
+        b"Generated from Python backend",
+        folder_id=folder["id"],
+        content_type="text/plain",
+    )
+
+    return file
+```
+
+### Find And Read A File
+
+```python
+@router.get("/read-summary", dependencies=[require_permission("data_rooms:read")])
+async def read_summary(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.require_room_by_name("Finance")
+    folder = await ctx.data_rooms.resolve_folder_path(room["id"], "Reports/Monthly")
+
+    if folder is None:
+        return {"found": False}
+
+    file = await ctx.data_rooms.find_file_by_name(
+        room["id"],
+        "summary.txt",
+        folder_id=folder["id"],
+    )
+
+    if file is None:
+        return {"found": False}
+
+    content = await ctx.data_rooms.read_file_bytes(file["id"])
+    return {
+        "found": True,
+        "text": content.decode("utf-8"),
+    }
+```
+
+### List Room Contents
+
+```python
+@router.get("/room-contents", dependencies=[require_permission("data_rooms:read")])
+async def room_contents(ctx: PluginContext = Depends(get_plugin_context)):
+    room = await ctx.data_rooms.require_room_by_name("Finance")
+    contents = await ctx.data_rooms.contents(room["id"])
+    return contents
+```
+
+Available Data Room helpers:
+
+```python
+await ctx.data_rooms.list()
+await ctx.data_rooms.create(name, description=None)
+await ctx.data_rooms.find_room_by_name(name, case_sensitive=False)
+await ctx.data_rooms.require_room_by_name(name, case_sensitive=False)
+await ctx.data_rooms.ensure_room(name, description=None)
+await ctx.data_rooms.contents(room_id, folder_id=None)
+await ctx.data_rooms.create_folder(room_id, name, parent_folder_id=None)
+await ctx.data_rooms.find_folder_by_name(
+    room_id,
+    name,
+    parent_folder_id=None,
+    case_sensitive=False,
+)
+await ctx.data_rooms.ensure_folder(room_id, name, parent_folder_id=None)
+await ctx.data_rooms.resolve_folder_path(
+    room_id,
+    "A/B/C",
+    create=False,
+    case_sensitive=False,
+)
+await ctx.data_rooms.find_file_by_name(
+    room_id,
+    name,
+    folder_id=None,
+    case_sensitive=False,
+)
+await ctx.data_rooms.read_file_bytes(file_id)
+await ctx.data_rooms.upload_file(
+    room_id,
+    filename,
+    content,
+    folder_id=None,
+    content_type=None,
+)
+```
+
+In local unit tests outside the Palette runtime, inject a fake Data Room service
+if you need to test routes that call `ctx.data_rooms`. In hosted sandbox and
+real OS runtime, the platform injects the real service.
+
+## 9. Config And Secrets
+
+Use config for app install settings and secrets for sensitive values.
+
+```python
+@router.get("/sync-config", dependencies=[require_permission("resources:read")])
+async def sync_config(ctx: PluginContext = Depends(get_plugin_context)):
+    timezone = ctx.config_value("timezone", "UTC")
+    required_workspace = ctx.require_config("workspace_id")
+    api_key = ctx.secret("FINANCE_API_KEY")
+
+    return {
+        "timezone": timezone,
+        "workspace_id": required_workspace,
+        "has_api_key": bool(api_key),
+    }
+```
+
+`ctx.secret("KEY")` first checks app config secrets and then falls back to the
+process environment variable named `KEY`.
+
+## 10. Lifecycle Hooks
+
+Lifecycle hooks let an app seed defaults or clean up app-owned data when the
+platform installs, updates, enables, disables, or uninstalls the app.
+
+```python
+from palette_sdk import LifecycleHooks, PluginContext
+from models import DefaultSetting
+
+lifecycle = LifecycleHooks()
+
+
+@lifecycle.on_install
+async def seed_defaults(ctx: PluginContext):
+    await ctx.repo(DefaultSetting).create(name="currency", value="USD")
+
+
+@lifecycle.on_enable
+async def on_enable(ctx: PluginContext):
+    ctx.logger.info("finance tools enabled for org %s", ctx.organization_id)
+```
+
+## 11. Calling Backend APIs From Frontend
+
+Frontend code should call backend routes through the platform API helper, not by
+hardcoding backend origins.
+
+```tsx
+import { createPaletteClient } from "@palettelab/sdk"
+
+const palette = createPaletteClient()
+
+async function loadInvoices() {
+  const res = await palette.apiFetch("/api/v1/plugins/finance-tools/invoices")
+  return res.json()
+}
+```
+
+During `pltt dev`, the simulator routes this to the local backend. In hosted
+sandbox or OS runtime, it goes through the real platform shell and auth context.
+
+## 12. Local Development
+
+Create and run an app:
+
+```bash
+npx --yes @palettelab/cli@latest init finance-tools --template database
+cd finance-tools
+npm install
+npx --yes @palettelab/cli@latest dev
+```
+
+Useful local checks:
+
+```bash
+npx --yes @palettelab/cli@latest test
+npx --yes @palettelab/cli@latest package
+```
+
+The CLI checks manifest shape, SDK compatibility, frontend bundling, backend
+imports, backend route permission gates, declared permissions, migration safety,
+package dependency policy, and backend package size.
+
+## 13. Test In Real Palette OS Without Docker
+
+Configure the hosted sandbox once:
+
+```bash
+npx --yes @palettelab/cli@latest login \
+  --env staging \
+  --url https://YOUR-PALETTE-STAGING-URL \
+  --token pltt_xxxxx
+```
+
+Then publish a sandbox preview:
+
+```bash
+npx --yes @palettelab/cli@latest dev --sandbox --env staging
+```
+
+The CLI packages the app, uploads it to the staging Palette environment,
+creates a preview publish, and prints a real OS preview URL. Open that URL to
+test the app with OS shell, auth context, organization context, Data Rooms,
+storage, logs, install/review behavior, and platform APIs.
+
+For internal test sandboxes, the backend environment can set:
+
+```bash
+APPSTORE_AUTO_APPROVE_SANDBOX_PREVIEWS=true
+```
+
+That lets passing preview publishes become active without manual approval.
+
+## 14. Common Mistakes
+
+- Do not import `@palettelab/sdk` from Python. That package is for frontend
+  JavaScript/React code only.
+- Do not hardcode backend URLs in frontend code. Use the platform API helper.
+- Do not manually set `organization_id` when using `ctx.repo(Model).create`.
+- Do not query cross-org data. The platform runtime and RLS are designed around
+  the current organization context.
+- Do not skip `require_permission(...)` on backend routes unless the route is
+  intentionally configured as public in the manifest.
+- Do not commit publish tokens, app secrets, or generated `.palette/` local
+  state.
+- Use hosted sandbox when you need real Data Rooms, login, organization,
+  install, logs, and OS behavior without Docker.
+
+## 15. Complete Minimal Example
+
+`backend/api/main.py`:
+
+```python
+from fastapi import Depends, HTTPException
+from pydantic import BaseModel
+from palette_sdk import PluginRouter, PluginContext, get_plugin_context, require_permission
+from models import Note
+
+router = PluginRouter(tags=["notes-app"])
+
+
+class NoteIn(BaseModel):
+    body: str
+
+
+@router.get("/notes", dependencies=[require_permission("resources:read")])
+async def list_notes(ctx: PluginContext = Depends(get_plugin_context)):
+    rows = await ctx.repo(Note).list(order_by="-id")
+    return [{"id": row.id, "body": row.body} for row in rows]
+
+
+@router.post("/notes", dependencies=[require_permission("resources:write")])
+async def create_note(
+    body: NoteIn,
+    ctx: PluginContext = Depends(get_plugin_context),
+):
+    if not body.body.strip():
+        raise HTTPException(status_code=400, detail="body required")
+
+    note = await ctx.repo(Note).create(body=body.body)
+
+    room = await ctx.data_rooms.ensure_room("Notes")
+    folder = await ctx.data_rooms.resolve_folder_path(
+        room["id"],
+        "Created From Backend",
+        create=True,
+    )
+    await ctx.data_rooms.upload_file(
+        room["id"],
+        f"note-{note.id}.txt",
+        note.body.encode("utf-8"),
+        folder_id=folder["id"],
+        content_type="text/plain",
+    )
+
+    return {"id": note.id, "body": note.body}
+```
+
+This route stores app-owned data in the app database and writes a related file
+into Palette Data Rooms from the Python backend.

package/lib/bundler.js

@@ -132,28 +132,48 @@ async function bundleBackend(pluginDir) {
   pluginDir = path.resolve(pluginDir)
   const { spawnSync } = require("child_process")
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), "palette-bundle-"))
+  const stage = path.join(tmp, "stage")
   const outPath = path.join(tmp, "backend.tar.gz")
 
-  const includes = []
-  if (fs.existsSync(path.join(pluginDir, "backend"))) includes.push("backend")
-  for (const metadataFile of ["package.json", "pyproject.toml"]) {
-    if (fs.existsSync(path.join(pluginDir, metadataFile))) includes.push(metadataFile)
-  }
-  includes.push("palette-plugin.json")
+  try {
+    fs.mkdirSync(stage, { recursive: true })
+    const copy = (from, to) => {
+      fs.cpSync(from, to, {
+        recursive: true,
+        filter(src) {
+          const parts = src.split(path.sep)
+          return !parts.includes("__pycache__") && !parts.includes(".venv")
+        },
+      })
+    }
 
-  const result = spawnSync(
-    "tar",
-    ["-czf", outPath, ...includes.flatMap((f) => ["--exclude=__pycache__", "--exclude=.venv"]), ...includes],
-    { cwd: pluginDir, stdio: "pipe" },
-  )
-  if (result.status !== 0) {
-    throw new Error(
-      `tar failed (exit ${result.status}): ${result.stderr?.toString() || "unknown error"}`,
-    )
+    const backendDir = path.join(pluginDir, "backend")
+    if (fs.existsSync(backendDir)) copy(backendDir, path.join(stage, "backend"))
+    for (const metadataFile of ["package.json", "pyproject.toml", "palette-plugin.json"]) {
+      const src = path.join(pluginDir, metadataFile)
+      if (fs.existsSync(src)) fs.copyFileSync(src, path.join(stage, metadataFile))
+    }
+
+    const sdkDir = path.resolve(__dirname, "..", "backend-sdk", "palette_sdk")
+    const targetSdkDir = path.join(stage, "backend", "palette_sdk")
+    if (fs.existsSync(sdkDir) && fs.existsSync(path.join(stage, "backend"))) {
+      copy(sdkDir, targetSdkDir)
+    }
+
+    const includes = fs.readdirSync(stage)
+    const result = spawnSync("tar", ["-czf", outPath, ...includes], {
+      cwd: stage,
+      stdio: "pipe",
+    })
+    if (result.status !== 0) {
+      throw new Error(
+        `tar failed (exit ${result.status}): ${result.stderr?.toString() || "unknown error"}`,
+      )
+    }
+    return fs.readFileSync(outPath)
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true })
   }
-  const buf = fs.readFileSync(outPath)
-  fs.rmSync(tmp, { recursive: true, force: true })
-  return buf
 }
 
 module.exports = { bundleFrontend, bundleBackend, watchFrontend }

package/lib/commands/build.js

@@ -13,6 +13,10 @@ const BANNED_PATTERNS = [
   { re: /\bpublic\./, reason: "plugin migrations must not reference the platform's public schema" },
   { re: /\bSET\s+ROLE\b/i, reason: "SET ROLE in migrations escalates out of the plugin sandbox" },
   { re: /\bALTER\s+ROLE\b/i, reason: "ALTER ROLE is reserved for the platform" },
+  { re: /\bGRANT\b/i, reason: "GRANT is reserved for the platform" },
+  { re: /\bCREATE\s+EXTENSION\b/i, reason: "CREATE EXTENSION is reserved for the platform" },
+  { re: /\bALTER\s+DATABASE\b/i, reason: "ALTER DATABASE is not allowed in plugin migrations" },
+  { re: /\bDROP\s+SCHEMA\b/i, reason: "DROP SCHEMA is not allowed in plugin migrations" },
 ]
 
 function lintMigrationFile(absPath) {

package/lib/dev-simulator.js

@@ -229,7 +229,7 @@ async function apiFetch(path, init) {
   return fetch(target, init)
 }
 
-const platform = {
+const basePlatform = {
   user: {
     id: "dev-user",
     email: "developer@palette.local",
@@ -263,6 +263,11 @@ const platform = {
   },
 }
 
+function normalizePaletteLanguage(language, fallback = "en") {
+  const value = String(language || "").trim().toLowerCase()
+  return value ? value.split("-")[0] : fallback
+}
+
 function Toasts() {
   const [items, setItems] = React.useState([])
   React.useEffect(() => {
@@ -280,6 +285,30 @@ function Toasts() {
 }
 
 function Shell() {
+  const [language, updateLanguage] = React.useState(() => normalizePaletteLanguage(navigator.language))
+  const platform = React.useMemo(() => ({
+    ...basePlatform,
+    language,
+    fallbackLanguage: "en",
+    supportedLanguages: ["en", "ko"],
+    setLanguage: (nextLanguage) => {
+      const normalized = normalizePaletteLanguage(nextLanguage)
+      updateLanguage(normalized)
+      document.documentElement.lang = normalized
+      window.dispatchEvent(new CustomEvent("palette:language-change", { detail: { language: normalized } }))
+    },
+  }), [language])
+
+  React.useEffect(() => {
+    document.documentElement.lang = language
+  }, [language])
+
+  React.useEffect(() => {
+    const onLanguageChange = () => updateLanguage(normalizePaletteLanguage(navigator.language))
+    window.addEventListener("languagechange", onLanguageChange)
+    return () => window.removeEventListener("languagechange", onLanguageChange)
+  }, [])
+
   return React.createElement(PluginProvider, { value: platform },
     React.createElement("main", { className: "palette-local-shell" },
       React.createElement(Plugin, { platform }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@palettelab/cli",
-  "version": "0.3.26",
+  "version": "0.3.28",
   "description": "Developer CLI for building Palette platform plugins — no platform source access required.",
   "bin": {
     "pltt": "bin/pltt.js"
@@ -8,6 +8,7 @@
   "files": [
     "bin",
     "backend-sdk",
+    "docs",
     "lib",
     "platform-dev",
     "template-fallback",

package/template-fallback/frontend/src/index.tsx

@@ -5,46 +5,58 @@
  *
  * This is the root component that the platform renders when your plugin is opened.
  * It receives a `platform` prop with access to the authenticated user, API client,
- * navigation, and toast notifications.
+ * navigation, toast notifications, and Palette OS language.
  *
  * Available hooks from @palettelab/sdk:
- *   - usePlatform()       — access user, org, apiFetch, navigate, showToast
- *   - usePluginTasks()    — CRUD tasks
- *   - usePluginDataRooms() — browse data rooms and files
- *   - usePluginChat()     — chat with agents
+ *   - usePlatform()           - access user, org, API, language, navigate, showToast
+ *   - usePluginTranslations() - translate app-owned resource files using OS language
+ *   - usePluginTasks()        - CRUD tasks
+ *   - usePluginDataRooms()    - browse data rooms and files
+ *   - usePluginChat()         - chat with agents
  */
 
-import { usePlatform, usePluginTasks } from "@palettelab/sdk"
+import { usePlatform, usePluginTasks, usePluginTranslations } from "@palettelab/sdk"
 import type { PluginComponentProps } from "@palettelab/sdk"
+import { translations } from "./translations"
 
-export default function MyPlugin({ platform }: PluginComponentProps) {
+export default function MyPlugin(_props: PluginComponentProps) {
   const { user, showToast } = usePlatform()
   const { tasks, loading, createTask } = usePluginTasks()
+  const { t, language, setLanguage } = usePluginTranslations(translations)
 
   return (
     <div className="p-6 space-y-6">
-      <div>
-        <h1 className="text-2xl font-bold">My Plugin</h1>
-        <p className="text-muted-foreground mt-1">
-          Hello, {user.name}! This is your plugin template.
-        </p>
+      <div className="flex flex-wrap items-start justify-between gap-3">
+        <div>
+          <h1 className="text-2xl font-bold">{t("title")}</h1>
+          <p className="text-muted-foreground mt-1">
+            {t("greeting", { name: user.name })}
+          </p>
+        </div>
+        <button
+          className="px-3 py-1.5 text-sm border rounded-md hover:bg-muted"
+          onClick={() => setLanguage(language === "ko" ? "en" : "ko")}
+          aria-label={t("language")}
+        >
+          {language === "ko" ? "EN" : "KO"}
+        </button>
       </div>
 
       <div className="rounded-lg border p-4 space-y-3">
-        <h2 className="font-semibold">Quick Start</h2>
+        <h2 className="font-semibold">{t("quickStart")}</h2>
         <ul className="text-sm text-muted-foreground space-y-1 list-disc list-inside">
-          <li>Edit <code>frontend/src/index.tsx</code> to build your UI</li>
-          <li>Edit <code>backend/api/main.py</code> to add API endpoints</li>
-          <li>Use <code>usePlatform()</code> to access the authenticated user and API</li>
-          <li>Use <code>usePluginTasks()</code> to manage tasks</li>
-          <li>Use <code>usePluginDataRooms()</code> to browse files</li>
+          <li>{t("editUi")}</li>
+          <li>{t("editApi")}</li>
+          <li>{t("usePlatform")}</li>
+          <li>{t("useTasks")}</li>
+          <li>{t("useDataRooms")}</li>
         </ul>
       </div>
 
       <div className="rounded-lg border p-4">
-        <h2 className="font-semibold mb-2">Tasks ({loading ? "..." : tasks.length})</h2>
+        <h2 className="font-semibold mb-2">{t("tasks")} ({loading ? "..." : tasks.length})</h2>
         {!loading && tasks.length === 0 && (
-          <p className="text-sm text-muted-foreground">No tasks yet.</p>
+          <p className="text-sm text-muted-foreground">{t("noTasks")}</p>
         )}
         {tasks.slice(0, 5).map(task => (
           <div key={task.id} className="flex items-center justify-between py-1 text-sm">
@@ -55,11 +67,11 @@ export default function MyPlugin({ platform }: PluginComponentProps) {
         <button
           className="mt-3 px-3 py-1.5 text-sm bg-primary text-primary-foreground rounded-md hover:bg-primary/90"
           onClick={async () => {
-            await createTask({ title: "Sample task from plugin", priority: "medium" })
-            showToast("Task created!", "success")
+            await createTask({ title: t("sampleTaskTitle"), priority: "medium" })
+            showToast(t("taskCreated"), "success")
           }}
         >
-          Create Sample Task
+          {t("createSampleTask")}
         </button>
       </div>
     </div>

package/template-fallback/frontend/src/translations.ts

@@ -0,0 +1,36 @@
+import type { TranslationResources } from "@palettelab/sdk"
+
+export const translations = {
+  en: {
+    title: "My Plugin",
+    greeting: "Hello, {{name}}! This plugin follows the Palette OS language.",
+    quickStart: "Quick Start",
+    editUi: "Edit frontend/src/index.tsx to build your UI",
+    editApi: "Edit backend/api/main.py to add API endpoints",
+    usePlatform: "Use usePlatform() to access the authenticated user and API",
+    useTasks: "Use usePluginTasks() to manage tasks",
+    useDataRooms: "Use usePluginDataRooms() to browse files",
+    tasks: "Tasks",
+    noTasks: "No tasks yet.",
+    createSampleTask: "Create Sample Task",
+    sampleTaskTitle: "Sample task from plugin",
+    taskCreated: "Task created!",
+    language: "Language",
+  },
+  ko: {
+    title: "내 플러그인",
+    greeting: "안녕하세요, {{name}}님! 이 플러그인은 Palette OS 언어를 따릅니다.",
+    quickStart: "빠른 시작",
+    editUi: "frontend/src/index.tsx를 수정해 UI를 만드세요",
+    editApi: "backend/api/main.py를 수정해 API 엔드포인트를 추가하세요",
+    usePlatform: "usePlatform()으로 인증 사용자와 API에 접근하세요",
+    useTasks: "usePluginTasks()로 작업을 관리하세요",
+    useDataRooms: "usePluginDataRooms()로 파일을 둘러보세요",
+    tasks: "작업",
+    noTasks: "아직 작업이 없습니다.",
+    createSampleTask: "샘플 작업 만들기",
+    sampleTaskTitle: "플러그인에서 만든 샘플 작업",
+    taskCreated: "작업이 생성되었습니다!",
+    language: "언어",
+  },
+} satisfies TranslationResources

package/template-fallback/package.json

@@ -4,7 +4,7 @@
   "private": true,
   "description": "A Palette platform plugin",
   "dependencies": {
-    "@palettelab/sdk": "^0.1.10"
+    "@palettelab/sdk": "^0.1.11"
   },
   "devDependencies": {
     "typescript": "^5.0.0",

package/template-fallback/palette-plugin.json

@@ -13,7 +13,7 @@
     "text": "#fff"
   },
   "sdk": {
-    "frontend": "^0.1.0",
+    "frontend": "^0.1.11",
     "backend": "^0.1.0"
   },
   "platform": {

package/template-fallback/templates/dashboard/frontend/src/index.tsx

@@ -1,13 +1,15 @@
 "use client"
 
 import { useEffect, useState } from "react"
-import { usePlatform } from "@palettelab/sdk"
+import { usePlatform, usePluginTranslations } from "@palettelab/sdk"
 import type { PluginComponentProps } from "@palettelab/sdk"
+import { translations } from "./translations"
 
 type Series = { label: string; value: number }
 
 export default function DashboardWidget(_props: PluginComponentProps) {
   const { apiFetch } = usePlatform()
+  const { t } = usePluginTranslations(translations)
   const [data, setData] = useState<Series[]>([])
   const [loading, setLoading] = useState(true)
 
@@ -22,9 +24,9 @@ export default function DashboardWidget(_props: PluginComponentProps) {
 
   return (
     <div className="p-6 space-y-4">
-      <h1 className="text-2xl font-bold">Dashboard Widget</h1>
+      <h1 className="text-2xl font-bold">{t("title")}</h1>
       {loading ? (
-        <p className="text-muted-foreground">Loading…</p>
+        <p className="text-muted-foreground">{t("loading")}</p>
       ) : (
         <div className="space-y-2">
           {data.map((d) => (

package/template-fallback/templates/dashboard/frontend/src/translations.ts

@@ -0,0 +1,12 @@
+import type { TranslationResources } from "@palettelab/sdk"
+
+export const translations = {
+  en: {
+    title: "Dashboard Widget",
+    loading: "Loading...",
+  },
+  ko: {
+    title: "대시보드 위젯",
+    loading: "불러오는 중...",
+  },
+} satisfies TranslationResources

package/template-fallback/templates/dashboard/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.10",
+    "@palettelab/sdk": "^0.1.11",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/dashboard/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "A widget that exposes a dashboard data source and renders a chart from it.",
   "icon": "ChartBar",
   "gradient": { "bg": "linear-gradient(135deg, #06B6D4, #6366F1)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.0", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.11", "backend": "^0.1.0" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/database/frontend/src/index.tsx

@@ -1,8 +1,9 @@
 "use client"
 
 import { useEffect, useState } from "react"
-import { usePlatform } from "@palettelab/sdk"
+import { usePlatform, usePluginTranslations } from "@palettelab/sdk"
 import type { PluginComponentProps } from "@palettelab/sdk"
+import { translations } from "./translations"
 
 type Note = { id: number; body: string }
 
@@ -96,6 +97,7 @@ const styles = `
 
 export default function NotesApp(_props: PluginComponentProps) {
   const { apiFetch, showToast, user } = usePlatform()
+  const { t } = usePluginTranslations(translations)
   const [notes, setNotes] = useState<Note[]>([])
   const [body, setBody] = useState("")
   const [loading, setLoading] = useState(true)
@@ -105,7 +107,7 @@ export default function NotesApp(_props: PluginComponentProps) {
     setLoading(true)
     try {
       const response = await apiFetch("/api/v1/plugins/my-db-plugin/notes")
-      if (!response.ok) throw new Error("Could not load notes")
+      if (!response.ok) throw new Error(t("loadError"))
       setNotes(await response.json())
     } finally {
       setLoading(false)
@@ -126,9 +128,9 @@ export default function NotesApp(_props: PluginComponentProps) {
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({ body: cleaned }),
       })
-      if (!response.ok) throw new Error("Could not save note")
+      if (!response.ok) throw new Error(t("saveError"))
       setBody("")
-      showToast("Note saved", "success")
+      showToast(t("saved"), "success")
       await load()
     } finally {
       setSaving(false)
@@ -139,11 +141,10 @@ export default function NotesApp(_props: PluginComponentProps) {
     <div className="notes-app">
       <style>{styles}</style>
       <main className="notes-shell">
-        <p className="notes-kicker">Palette DB App</p>
-        <h1 className="notes-title">Org Notes</h1>
+        <p className="notes-kicker">{t("kicker")}</p>
+        <h1 className="notes-title">{t("title")}</h1>
         <p className="notes-copy">
-          Built for {user.name}. This app uses a Python backend and the Palette
-          SDK database session exposed as <code>ctx.db</code>.
+          {t("copy", { name: user.name })}
         </p>
         <section className="notes-form">
           <input
@@ -153,7 +154,7 @@ export default function NotesApp(_props: PluginComponentProps) {
             onKeyDown={(event) => {
               if (event.key === "Enter") void add()
             }}
-            placeholder="New note..."
+            placeholder={t("placeholder")}
           />
           <button
             type="button"
@@ -161,14 +162,14 @@ export default function NotesApp(_props: PluginComponentProps) {
             disabled={saving || body.trim().length === 0}
             className="notes-button"
           >
-            {saving ? "Saving" : "Add Note"}
+            {saving ? t("saving") : t("add")}
           </button>
         </section>
         <section className="notes-list">
           {loading ? (
-            <p className="notes-empty">Loading notes...</p>
+            <p className="notes-empty">{t("loading")}</p>
           ) : notes.length === 0 ? (
-            <p className="notes-empty">No notes yet.</p>
+            <p className="notes-empty">{t("empty")}</p>
           ) : (
             notes.map((note) => (
               <p key={note.id} className="notes-item">

package/template-fallback/templates/database/frontend/src/translations.ts

@@ -0,0 +1,30 @@
+import type { TranslationResources } from "@palettelab/sdk"
+
+export const translations = {
+  en: {
+    kicker: "Palette DB App",
+    title: "Org Notes",
+    copy: "Built for {{name}}. This app uses a Python backend and the Palette SDK database session exposed as ctx.db.",
+    placeholder: "New note...",
+    add: "Add Note",
+    saving: "Saving",
+    loading: "Loading notes...",
+    empty: "No notes yet.",
+    loadError: "Could not load notes",
+    saveError: "Could not save note",
+    saved: "Note saved",
+  },
+  ko: {
+    kicker: "Palette DB 앱",
+    title: "조직 노트",
+    copy: "{{name}}님을 위해 생성되었습니다. 이 앱은 Python 백엔드와 ctx.db로 제공되는 Palette SDK 데이터베이스 세션을 사용합니다.",
+    placeholder: "새 노트...",
+    add: "노트 추가",
+    saving: "저장 중",
+    loading: "노트를 불러오는 중...",
+    empty: "아직 노트가 없습니다.",
+    loadError: "노트를 불러올 수 없습니다",
+    saveError: "노트를 저장할 수 없습니다",
+    saved: "노트가 저장되었습니다",
+  },
+} satisfies TranslationResources

package/template-fallback/templates/database/package.json

@@ -2,5 +2,5 @@
   "name": "my-db-plugin",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.10", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.11", "react": "^19.0.0" }
 }

package/template-fallback/templates/database/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "Stores notes per organization with RLS-enforced isolation.",
   "icon": "Database",
   "gradient": { "bg": "linear-gradient(135deg, #8B5CF6, #EC4899)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.0", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.11", "backend": "^0.1.0" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/external-service/frontend/src/index.tsx

@@ -1,16 +1,18 @@
 "use client"
 
 import { useState } from "react"
-import { usePlatform } from "@palettelab/sdk"
+import { usePlatform, usePluginTranslations } from "@palettelab/sdk"
 import type { PluginComponentProps } from "@palettelab/sdk"
+import { translations } from "./translations"
 
 export default function ExternalServiceWidget(_props: PluginComponentProps) {
   const { apiFetch } = usePlatform()
+  const { t } = usePluginTranslations(translations)
   const [result, setResult] = useState<string>("")
 
   return (
     <div className="p-6 space-y-3">
-      <h1 className="text-2xl font-bold">External Service</h1>
+      <h1 className="text-2xl font-bold">{t("title")}</h1>
       <button
         className="px-3 py-1.5 rounded bg-primary text-primary-foreground text-sm"
         onClick={async () => {
@@ -18,7 +20,7 @@ export default function ExternalServiceWidget(_props: PluginComponentProps) {
           setResult(await r.text())
         }}
       >
-        Call api.example.com
+        {t("call")}
       </button>
       {result && <pre className="text-xs">{result}</pre>}
     </div>

package/template-fallback/templates/external-service/frontend/src/translations.ts

@@ -0,0 +1,12 @@
+import type { TranslationResources } from "@palettelab/sdk"
+
+export const translations = {
+  en: {
+    title: "External Service",
+    call: "Call api.example.com",
+  },
+  ko: {
+    title: "외부 서비스",
+    call: "api.example.com 호출",
+  },
+} satisfies TranslationResources

package/template-fallback/templates/external-service/package.json

@@ -2,5 +2,5 @@
   "name": "my-external-svc",
   "version": "1.0.0",
   "private": true,
-  "dependencies": { "@palettelab/sdk": "^0.1.10", "react": "^19.0.0" }
+  "dependencies": { "@palettelab/sdk": "^0.1.11", "react": "^19.0.0" }
 }

package/template-fallback/templates/external-service/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "Demonstrates declared external_network access and a scoped per-org config token.",
   "icon": "CloudArrowUp",
   "gradient": { "bg": "linear-gradient(135deg, #10B981, #06B6D4)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.0", "backend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.11", "backend": "^0.1.0" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,

package/template-fallback/templates/frontend-only/frontend/src/index.tsx

@@ -1,15 +1,18 @@
 "use client"
 
-import { usePlatform } from "@palettelab/sdk"
+import { usePlatform, usePluginTranslations } from "@palettelab/sdk"
 import type { PluginComponentProps } from "@palettelab/sdk"
+import { translations } from "./translations"
 
 export default function FrontendOnlyPlugin(_props: PluginComponentProps) {
   const { user } = usePlatform()
+  const { t } = usePluginTranslations(translations)
+
   return (
     <div className="p-6">
-      <h1 className="text-2xl font-bold">Hello, {user.name}</h1>
+      <h1 className="text-2xl font-bold">{t("title", { name: user.name })}</h1>
       <p className="text-muted-foreground mt-2">
-        This plugin runs entirely in the browser sandbox — no backend.
+        {t("body")}
       </p>
     </div>
   )

package/template-fallback/templates/frontend-only/frontend/src/translations.ts

@@ -0,0 +1,12 @@
+import type { TranslationResources } from "@palettelab/sdk"
+
+export const translations = {
+  en: {
+    title: "Hello, {{name}}",
+    body: "This plugin runs entirely in the browser sandbox and follows the Palette OS language.",
+  },
+  ko: {
+    title: "안녕하세요, {{name}}님",
+    body: "이 플러그인은 브라우저 샌드박스에서만 실행되며 Palette OS 언어를 따릅니다.",
+  },
+} satisfies TranslationResources

package/template-fallback/templates/frontend-only/package.json

@@ -3,7 +3,7 @@
   "version": "1.0.0",
   "private": true,
   "dependencies": {
-    "@palettelab/sdk": "^0.1.10",
+    "@palettelab/sdk": "^0.1.11",
     "react": "^19.0.0"
   }
 }

package/template-fallback/templates/frontend-only/palette-plugin.json

@@ -9,7 +9,7 @@
   "description": "A frontend-only plugin — renders inside the platform iframe sandbox with no backend.",
   "icon": "Puzzle",
   "gradient": { "bg": "linear-gradient(135deg, #6366F1, #8B5CF6)", "text": "#fff" },
-  "sdk": { "frontend": "^0.1.0" },
+  "sdk": { "frontend": "^0.1.11" },
   "platform": { "min_version": "0.1.0" },
   "capabilities": {
     "frontend": true,