@zhama/tego-plugin-sdk 1.36.1 → 1.37.0

package/README.md

@@ -563,7 +563,10 @@ import { resolve } from 'node:path';
 import { tegoPluginFrontend, tegoPluginTailwind } from '@tego/plugin-sdk/vite';
 import tailwindcss from 'tailwindcss';
 
-const config = tegoPluginFrontend({ entry: 'frontend/src/index.tsx', pluginId: 'acme-crm' });
+const config = tegoPluginFrontend({
+  entry: 'frontend/src/index.tsx',
+  pluginId: 'acme-crm',
+});
 config.css = {
   postcss: {
     plugins: [
@@ -600,6 +603,45 @@ await packPlugin({ root: process.cwd(), backend: { external: ['sharp'] } });
 Without this, changing one line of frontend code costs a pack, an upload, an
 install and a refresh.
 
+### Preview without a Tego server: `tego-plugin dev`
+
+```bash
+pnpm run dev                                            # scaffolded plugins have "dev": "tego-plugin dev"
+DATABASE_URL=postgres://me:pw@localhost:5432/dev pnpm run dev   # with the backend
+```
+
+It prints the address (`http://127.0.0.1:5280/p/<id>/`, or the next free port;
+`--port 0` takes any) and a machine-readable `TEGO_DEV_READY {"url":…}` line.
+Everything is served from that one origin:
+
+- **Frontend**: a stand-in for the shell's plugin page mounts your entry from
+  source through Vite, with your own `vite.config.ts` and Tailwind. Saving
+  reloads the page. The context is built as the shell builds it — `basePath`
+  `/p/<id>`, history routing, `ctx.api` at `/api/v1/tego-os/plugin-api/<id>/*`,
+  the frontend config's defaults — and the top bar switches page, language
+  (your locale files, the access UI's strings merged in), light/dark, and the
+  user and roles the API calls are made as (`ctx.can` answers for any nav key
+  the manifest declares).
+- **Backend** (with `DATABASE_URL`, unless `--no-backend`): built with the
+  packer's own settings and started with the environment `serveBackend` reads.
+  Requests carry the same signed identity headers the gateway adds. Migrations
+  run first, each file in its own transaction with `search_path` set to
+  `tego_dev_<id>` alone, recorded in a `tego_dev_migrations` table in that
+  schema so each file runs once; the backend's connection is pinned to the
+  schema too. Saving under `backend/` or `shared/` rebuilds, migrates and
+  restarts it. The database is yours to provide; any PostgreSQL works.
+- **Host API stand-in**: `config` (the backend section's defaults), `log`,
+  `storage` (files under `.tego-dev/storage/`), `events` and `notifications`
+  (printed), and a `directory` that knows the users you previewed as. Anything
+  else — mail, knowledge, accounts, delegations, AI, Office, live events —
+  answers 501 naming the path; test those on a real server.
+
+Without `DATABASE_URL` the page still works and API calls answer 503 saying
+why. `.tego-dev/` holds the generated shell, the backend build and local
+storage; keep it out of git. Python backends run on a server only.
+
+### Inside the shell
+
 ```bash
 pnpm exec tego-plugin-pack --watch                    # serves the bundle on :5180
 VITE_TEGO_LOCAL_PLUGINS=acme-crm=http://localhost:5180/index.js pnpm -F @tego/ai-studio dev
@@ -614,7 +656,7 @@ Hot replacement across the SystemJS boundary means unmounting the plugin's React
 root and re-registering shared modules, which is a lot of machinery for
 something that would silently desync; a one-second reload is always right.
 
-The backend runs on the host instead of in a container:
+Against a full local server, the backend runs on the host instead of in a container:
 
 ```bash
 TEGO_PLUGIN_BACKEND_BASE_URL=http://localhost:18800 pnpm -F @tego/server dev
@@ -779,7 +821,12 @@ const unregister = ctx.ai?.registerForm({
   element: formElement,
   getSnapshot: () => ({
     fields: [
-      { name: 'quantity', label: '数量', type: 'number', value: state.quantity },
+      {
+        name: 'quantity',
+        label: '数量',
+        type: 'number',
+        value: state.quantity,
+      },
       { name: 'note', label: '说明', type: 'text', value: state.note },
     ],
     instructions: '数量使用件，不推测未提供的数量。',

package/agent/RULES.md

@@ -0,0 +1,123 @@
+# Tego plugin rules
+
+A Tego plugin runs inside the Tego platform: its frontend inside the **web app** and the
+**desktop app** (Tauri), its backend in a platform-managed container, its claw part inside an
+employee's container. These rules are what makes a plugin load, pass upload, and behave the same
+in both shells. Read the guide named in each section before writing that kind of code.
+
+Rules with an id are checked by `tego-plugin doctor` (`--json` for tools). A line can opt out with
+`tego-doctor-ignore <RULE-ID>: <reason>` on it or on the line above; give a real reason.
+
+## Working loop
+
+1. Read the relevant guide (`agent/guides/*.md`) and the code you change.
+2. Make focused changes; reuse the SDK's helpers (`@tego/plugin-sdk/react`, `/hono`, `/testing`)
+   instead of writing your own versions.
+3. Run the gates: `tego-plugin doctor`, then lint, type-check, test, build. Fix everything they
+   report; never weaken a check or a test to make it pass.
+4. Every new user-visible string goes into all ten locales.
+
+## Manifest and packaging — guides/manifest.md, guides/host-api-versions.md
+
+- **TP-MAN-001** `tego.plugin.json` is valid: `manifestVersion: 1`, stable `id`, semver `version`
+  (never lower it), `scope`, at least one part, non-overlapping part directories.
+- **TP-MAN-002** `hostApiRange` (`^X.Y.Z`) admits every host capability the code uses. Declare the
+  lowest version you need, and raise it when you use something newer (table in the guide) — or
+  feature-detect it (`if (ctx.download) … else …`) to keep supporting older shells.
+- In-plugin routes have no dotted segment (`/p/x/report.pdf`): the desktop app serves a reloaded
+  URL like that as a file, not your page. (Nav paths are already refused by the manifest schema.)
+- **TP-PKG-001** SDK packages are installed as npm aliases (`"@tego/ui": "npm:@zhama/tego-ui@^1.37.0"`)
+  or workspace links. On npm, a plain `@tego/*` name belongs to another project.
+- **TP-PKG-002** `package.json` has the four gates: `lint`, `type-check` (tsgo), `test` (vitest),
+  `build` (`tego-plugin-pack`).
+- Never import `@tego/shared`, host app code, or anything not published to plugins.
+
+## Running in the web app and the desktop app — guides/desktop-web.md
+
+The two shells share one frontend but differ in CSP, origin, network proxy and file handling. Code
+that works in a browser tab can fail on desktop, and the reverse.
+
+- **TP-DESK-001** No `eval` / `new Function` (desktop CSP: `script-src 'self' 'wasm-unsafe-eval'`),
+  including in libraries you add.
+- **TP-DESK-002** Never build addresses from `location.origin` (it is `tauri://localhost` on
+  desktop). Use `ctx.hostUrl(path)` for host paths and `ctx.publicPagesUrl` for share links.
+- **TP-DESK-003** Open external links with `ctx.openExternal(url)`, not `window.open`.
+- **TP-DESK-004** Save files with `ctx.download({ path | blob, fileName })`, not `<a download>`.
+- **TP-DESK-005** Do not stream from the frontend: desktop buffers `ctx.api` responses whole and caps
+  them at 100 MB. Large files go through storage paths; live updates come from `ctx.events`.
+- **TP-DESK-006** Copy text with `ctx.copyText(text)`.
+- **TP-WEB-001** The frontend calls no third-party URL (the web CSP only allows the platform). The
+  backend calls it, with the host declared in `parts.backend.egress`.
+- **TP-WEB-002** No remote or injected scripts; all code ships in the bundle.
+- No cookie-based auth: `ctx.api` carries the credentials in both shells.
+
+## Frontend — guides/frontend.md
+
+- **TP-UI-004** The frontend has its own error boundary (`PluginErrorBoundary`); the shell's cannot
+  see into your React root.
+- Root order: `I18nextProvider` (plugin namespace) → error boundary → `QueryClientProvider` →
+  `AccessProvider` (with access) → `HostProvider`; the root element carries the scope class.
+- Route with `ctx.route` / `ctx.navigate` under `ctx.basePath`; the page is not remounted when the
+  in-plugin path changes.
+- Call your backend only through `ctx.api` (via `createApiClient`), keeping the error body.
+
+## UI and design — guides/ui.md
+
+- **TP-UI-001** Colors only through token classes (`bg-card`, `text-muted-foreground`, `bg-primary`…):
+  no hex, `rgb()`, palette classes (`bg-blue-500`, `text-white`) or `dark:` overrides.
+- **TP-UI-002** Use `@tego/ui` components; never import `@radix-ui/*` directly.
+- **TP-UI-003** With `tegoPluginTailwind`, the root element (and portalled content, or use
+  `tegoPluginScopeRoot`) carries `className="<pluginId>"`, or none of your utilities apply.
+- Status uses text or an icon, not color alone; machine data (ids, numbers, times) uses
+  `font-mono tabular-nums`.
+
+## i18n — guides/i18n.md
+
+- **TP-I18N-001** All ten locales — `zh-CN zh-TW en ja ko de es fr it pt` — in
+  `frontend/i18n/<locale>.json`, with exactly the keys of `zh-CN`; every nav `labelKey` exists.
+- **TP-I18N-002** Every value keeps the `{{placeholders}}` of `zh-CN` and is not empty.
+- **TP-I18N-003** Every literal `t('…')` key exists.
+- **TP-I18N-004** Say 数字员工 / Employee through `{{avatarTerm}}`; never 数字分身 / digital avatar.
+- Keys live under one root named after the plugin (`notes.home.title`); don't copy `tegoAccess.*`.
+
+## Backend — guides/backend.md, guides/storage.md
+
+- **TP-BE-001** The caller is the verified `ctx` that `serveBackend` hands you. Never read the raw
+  `x-tego-plugin-*` headers; a user id in a path or body names a target, never the caller.
+- **TP-BE-005** Log through `host.log`, never `console`.
+- Every error becomes JSON (`pluginErrorHandler`): coded 4xx for the caller's mistakes, a generic
+  500 that never echoes SQL; host 429s pass through with `Retry-After`.
+- Validate every body and query with zod (`readBody` / `readQuery`).
+- Data lives in your schema only (`host.db`); configuration in `host.config.current()`, never env.
+- Storage: `put` up to 25 MiB; larger files upload from the browser to `uploadPath` and are
+  verified with `head`. Download paths are `signedPath` / `managedPath`, opened via `ctx.hostUrl`.
+- Background work in `start()` never acts as a user.
+
+## Migrations — guides/migrations.md
+
+- **TP-BE-003** `backend/migrations/<ordinal>_<name>.sql`, unique ordinals.
+- **TP-BE-004** Committed migrations are append-only: never edit or delete one; add a new file.
+- Generate them from the drizzle schema (`tego-plugin migrations sync`); hand-write only what
+  drizzle cannot express (functions, triggers, RLS).
+
+## Access control — guides/access.md
+
+- **TP-BE-002** Never decide by host role names (`roles.includes('admin')`); declare permissions in
+  the catalog (`hostRoleBindings`) and ask the engine.
+- **TP-ACC-001** With `access.catalog`, every route carries exactly one policy, and a test calls
+  `assertRouteCoverage(app)`.
+- **TP-ACC-002** With `access.catalog`, `start()` calls `access.reconcile(host)`.
+- Lists use `session.filter`, single records `policy.resource`; what the frontend hides is
+  presentation only.
+
+## Claw part — guides/claw.md
+
+- **TP-CLAW-002** Each `claw/skills/<name>/SKILL.md` declares `name: <name>`.
+- Tools are listed in `contracts.tools`; the claw config schema lives in `openclaw.plugin.json`,
+  never in the manifest.
+
+## Tests — guides/testing.md
+
+- **TP-TEST-001** The plugin has tests: backend routes against a real database
+  (`createTestPluginHost`), pure frontend logic in `.ts` files. No component tests.
+- Each test file starts with a Business Cases list; each `it` title starts with its case id.

package/agent/guides/access.md

@@ -0,0 +1,39 @@
+# Access control
+
+Accounts come from the host; what someone may do _inside_ the plugin is declared in your catalog,
+stored in your own tables and decided by the SDK. Design: `docs/design/plugin-access.md` in tego-os.
+
+Add it as soon as some users may do something others may not:
+
+1. `"access": { "catalog": "shared/access.json" }` in the manifest; `hostApiRange` ≥ `^1.22.0`;
+   `directory.read` permission when you use `unit` principals.
+2. Catalog: permissions (with `implies`, and `agent.requires` for what employees may use), scopes,
+   built-in roles, `hostRoleBindings` (how host roles map to yours), default role, `menus`
+   (nav key → permissions).
+3. Backend:
+   ```ts
+   export const access = createAccess({
+     catalog: accessCatalogFromJson(catalogJson),
+   });
+   const { policy, routes } = accessHono({ session: c => c.env.access });
+   app.get('/records', policy.permission('record.view'), list);
+   app.delete(
+     '/records/:id',
+     policy.resource('record.delete', loadRecord, { conceal: true }),
+     remove
+   );
+   app.route('/', routes()); // /access/me, /access/roles, …
+   // start(host): await access.reconcile(host)          (TP-ACC-002)
+   ```
+   - **Exactly one policy per route** — `public()` (only for `publicRoutes`), `authenticated()`,
+     `permission()`, `resource()` — and a test: `assertRouteCoverage(app, { publicRoutes })` (TP-ACC-001).
+   - Lists: `session.filter('record.view', { alias: 'r' })` gives the SQL condition; single records:
+     `policy.resource` / `authorize`. Never write a second copy of scope logic in SQL.
+   - Tables: re-export `@tego/plugin-sdk/access/drizzle` in your schema and generate migrations.
+   - Derived data (compiled rules, caches) updates in `hooks.onChange`, in the same transaction.
+4. Frontend: `<AccessProvider api={ctx.api}>` under your `QueryClientProvider`; gate with
+   `useAccess()`, `<Can>`, `filterNav`; embed `<AccessSettings />` in your settings page;
+   install `@tego/plugin-access-ui` under the npm alias.
+
+Never (TP-BE-002): check host role names (`ctx.roles.includes('admin')`), invent `isAdmin`, keep a
+parallel role table, let background jobs act as a user, or treat frontend gating as the boundary.

package/agent/guides/backend.md

@@ -0,0 +1,76 @@
+# Backend part
+
+```ts
+// backend/src/index.ts
+import { serveBackend } from '@tego/plugin-sdk/server-runtime';
+import { backend } from './app';
+serveBackend(backend);
+```
+
+`definePluginBackend({ fetch, start?, stop?, fetchPublic?, authorizeStorage? })`. `fetch(request, ctx, host)`
+receives a request whose identity the gateway signed and `serveBackend` verified: `ctx.userId`,
+`ctx.tenantId`, `ctx.roles`, and for claw calls `ctx.avatarId` / `ctx.delegation`.
+
+## Identity (TP-BE-001)
+
+The caller is `ctx`, always. A `userId` in a path or body names a _target_ (whose role to change),
+never who is asking. Do not parse `x-tego-plugin-*` headers yourself.
+
+## Routes with Hono
+
+```ts
+import { Hono } from 'hono';
+import {
+  HttpError,
+  jsonNotFound,
+  pluginErrorHandler,
+  readBody,
+} from '@tego/plugin-sdk/hono';
+import { z } from 'zod';
+
+type Env = {
+  Bindings: {
+    host: PluginHostApi;
+    ctx: PluginUserContext;
+    access: AccessSession;
+  };
+};
+const app = new Hono<Env>();
+app.onError(pluginErrorHandler()); // access denials, HttpError, host 429 → JSON; other errors logged via host.log, generic 500
+app.notFound(jsonNotFound);
+
+const NoteInput = z.object({ body: z.string().trim().min(1).max(4000) });
+app.post('/notes', policy.permission('note.create'), async c => {
+  const { body } = await readBody(c, NoteInput); // 400 { error: { code: 'invalid_body', path } }
+  const [row] = await c.env.host.db.query<{ id: string }>(
+    'INSERT INTO notes (author_id, body) VALUES ($1, $2) RETURNING id',
+    [c.env.ctx.userId, body]
+  );
+  return c.json({ id: row!.id }, 201);
+});
+
+export const backend = definePluginBackend({
+  fetch: (request, ctx, host) =>
+    app.fetch(request, { host, ctx, access: access.forRequest(ctx, host) }),
+  start: async host => {
+    await access.reconcile(host);
+    maintenance.start(host);
+  },
+  stop: () => maintenance.stop(),
+});
+```
+
+- Throw `new HttpError(409, 'note_locked', 'This note is locked')` for the caller's mistakes; the
+  frontend translates `code`.
+- Never return SQL or stack traces; `pluginErrorHandler` logs them with `host.log.error` (TP-BE-005).
+- Query only the columns you need; parameterize everything.
+- Data: only your schema through `host.db` (one schema per install). Config: `host.config.current()`;
+  `host.config.refresh()` after a credential rotation. Never read config from env.
+- Changes users should see live: `host.events.publish('changed', { kind })` (no personal data — the
+  stream is tenant-wide); `changedEventsMiddleware()` does it for every successful write.
+- `start()` runs installation-level maintenance (timers, queues) as trusted system code: it never
+  acts as a user. Keep each step isolated so one failure does not stop the others
+  (`createMaintenance` from `@tego/plugin-sdk/server-runtime`).
+- Outbound HTTP only to hosts in `parts.backend.egress`.
+
+See storage.md for files and access.md for permissions.

package/agent/guides/claw.md

@@ -0,0 +1,18 @@
+# Claw part
+
+Anything inside a conversation (tools, skills, cards) is the claw part, running inside the employee's
+OpenClaw container.
+
+- `claw/openclaw.plugin.json`: `id`, `contracts.tools` (every tool you register), `configSchema`
+  (closed object; integer min/max/default; `uiHints` labels in all ten locales), audit notes for
+  tools. The packer stamps the plugin's version into it and `claw/package.json`.
+- `claw/src/index.ts`: `definePluginEntry`; register tools only when the Tego API is installed;
+  `register()` must be idempotent and tolerate early-phase config. `api.logger` takes one string.
+- Call your backend from a tool with the Tego API's `request({ path: '/api/v1/tego-os/plugin-api/<id>/…',
+executionContext: 'current-user' })`; return 400/404/409/422 as values the model can read, throw
+  for anything else with a message written for the model.
+- Tool results: JSON in both `content` and `details`.
+- Skills (TP-CLAW-002): `claw/skills/<prefix>-<name>/SKILL.md` with `name: <prefix>-<name>` and a
+  `description`; every tool a skill mentions exists. `assertClawSkills(skillsDir, toolNames)` from
+  `@tego/plugin-sdk/testing` tests it.
+- Config marked secret comes back as `__OPENCLAW_REDACTED__` in some reads; treat it as unusable.

package/agent/guides/desktop-web.md

@@ -0,0 +1,48 @@
+# Running in both shells: web and desktop
+
+The plugin's frontend is loaded by two shells built from one codebase:
+
+|                                   | Web app (browser)                       | Desktop app (Tauri v2)                                                                                                                                                              |
+| --------------------------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Origin                            | the platform's https origin             | `tauri://localhost` (macOS), `https://tauri.localhost` (Windows)                                                                                                                    |
+| Script CSP                        | nonce + `'strict-dynamic'`              | `'self' 'wasm-unsafe-eval'` — no `eval`, no `new Function`, no `blob:` scripts                                                                                                      |
+| `connect-src`                     | the platform only (plus its fixed CDNs) | any http(s)                                                                                                                                                                         |
+| `ctx.api` transport               | browser fetch to the platform           | a Rust protocol proxy that **buffers the whole response**, caps it at **100 MB** (413), strips `accept-encoding`, and answers 403 `LICENSE_INVALID` when the desktop licence lapses |
+| Reloaded URL ending in `name.ext` | the SPA page                            | proxied to the server as a file                                                                                                                                                     |
+| `window.open`, `<a download>`     | browser behaviour                       | not reliably handled by the webview                                                                                                                                                 |
+| Cookies                           | not used                                | not available                                                                                                                                                                       |
+
+`ctx.platform` tells you which one you run in (host API 1.37), but **write code that is correct in
+both** rather than branching on it.
+
+## Do / don't
+
+| Instead of                                                                                       | Use                                                                                                  | Rule                      |
+| ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------- | ------------------------- |
+| `eval`, `new Function`, libraries that compile strings (some template engines, older chart libs) | precompiled code; check a new dependency with `tego-plugin doctor` and the preview's desktop mode    | TP-DESK-001               |
+| `` `${location.origin}/…` ``                                                                     | `ctx.hostUrl(path)` for host paths, `ctx.publicPagesUrl` for share/QR links                          | TP-DESK-002               |
+| `window.open(url)`                                                                               | `ctx.openExternal(url)`                                                                              | TP-DESK-003               |
+| `<a download>`, `a.download = …`, `URL.createObjectURL` + click                                  | `ctx.download({ path })` for a stored file, `ctx.download({ blob, fileName })` for generated content | TP-DESK-004               |
+| `response.body.getReader()`, `EventSource`, NDJSON over `ctx.api`                                | `ctx.events.subscribe` for pushed changes; storage paths for big files                               | TP-DESK-005               |
+| `navigator.clipboard.writeText`                                                                  | `ctx.copyText(text)`                                                                                 | TP-DESK-006               |
+| `fetch('https://api.example.com/…')` from the frontend                                           | a backend route that calls it, with `parts.backend.egress: ["api.example.com"]`                      | TP-WEB-001                |
+| `<script src>`, `import('https://…')`, CDN loaders                                               | bundle the dependency                                                                                | TP-WEB-002                |
+| `/p/<id>/report.pdf` style routes                                                                | `/p/<id>/report?file=…`                                                                              | (manifest schema for nav) |
+
+## Files
+
+- **Upload**: ask your backend for a grant (`host.storage.uploadPath(key, { maxBytes, ttlSeconds })`),
+  `fetch(ctx.hostUrl(grant.path), { method: 'PUT', body: file })`, then tell the backend to register it
+  (it checks with `host.storage.head(key)`). Never send large files through `ctx.api`.
+- **Download**: the backend returns `signedPath` / `managedPath`; the frontend calls
+  `ctx.download({ path, fileName })`.
+- **Generated content** (CSV, a template): `ctx.download({ blob, fileName })`.
+
+Before host API 1.37 (plugins that cannot raise `hostApiRange` yet), feature-detect:
+`ctx.download ? ctx.download(...) : legacyDownload(...)`, and mark the legacy line with
+`tego-doctor-ignore TP-DESK-004: <reason>`.
+
+## Checking
+
+`tego-plugin dev --target desktop` serves the preview with the desktop CSP and a buffering proxy, and
+reports CSP violations; try every page there before releasing.

package/agent/guides/frontend.md

@@ -0,0 +1,83 @@
+# Frontend part
+
+The entry (`frontend/src/index.tsx`) default-exports `definePluginFrontend({ mount(el, ctx) })` and
+returns a function that fully tears down. The shell shares `react`, `react-dom`, `@tego/ui`,
+`react-i18next` and `lucide-react` with you (`SHARED_MODULE_IDS`); everything else you bundle.
+
+## Root
+
+```tsx
+import { getI18n, I18nextProvider } from 'react-i18next';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { pluginI18nNamespace } from '@tego/plugin-sdk';
+import { HostProvider, PluginErrorBoundary } from '@tego/plugin-sdk/react';
+
+export function App({ ctx }: { ctx: PluginHostContext }) {
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({ defaultOptions: { queries: { staleTime: 10_000 } } })
+  );
+  return (
+    <I18nextProvider
+      i18n={getI18n()}
+      defaultNS={pluginI18nNamespace(ctx.pluginId)}
+    >
+      <PluginErrorBoundary
+        fallback={(_error, reset) => <Crashed onRetry={reset} />}
+      >
+        <QueryClientProvider client={queryClient}>
+          {/* <AccessProvider api={ctx.api}> when the plugin has an access catalog */}
+          <HostProvider value={ctx}>
+            <div className={`${ctx.pluginId} flex h-full min-h-0 flex-col`}>
+              <Routes />
+            </div>
+          </HostProvider>
+        </QueryClientProvider>
+      </PluginErrorBoundary>
+    </I18nextProvider>
+  );
+}
+```
+
+- **Error boundary (TP-UI-004)**: the shell's boundary is outside your React root; without your own,
+  a render error is a blank page. `Crashed` is your translated `EmptyState` with a retry button.
+- **Namespace**: the shell merged your locale files under `plugin.<id>`; name it once at the root.
+- **Scope class (TP-UI-003)**: `tegoPluginTailwind` compiles your utilities under `.<pluginId>`.
+
+## Routing
+
+`ctx.basePath` is `/p/<id>`. The shell does not remount the page when the in-plugin path changes:
+
+```ts
+const route = usePluginRoute(); // { path: '/deals/42', search: '?tab=x' }
+const host = useHost();
+host.navigate('/deals/42'); // relative to basePath; absolute /p/... also fine
+```
+
+Keep route parsing in a pure `lib/route.ts` (`parseRoute(path, search)` returning a union) and test it.
+`ctx.can(navKey)` only says whether the manifest declares that page; real permissions come from the
+access catalog (`useAccess`).
+
+## Calling the backend
+
+```ts
+import { createApiClient, PluginApiError } from '@tego/plugin-sdk/react';
+export const api = createApiClient(ctx.api);
+const notes = await api.get<{ notes: Note[] }>('/notes');
+await api.post('/notes', { body: text });
+// errors: PluginApiError { status, code, message, details } — both the backend's {error:{code,message}}
+// and the gateway's {success:false,error:{message}} shapes are understood
+```
+
+Never use `ctx.api.json` for calls whose errors you show (it drops the body). Show errors with
+`describeApiError(error, '<ns>')` → `{ key, message }`: `key ? t(key, { defaultValue: message }) : message`.
+
+## Live data
+
+`useLiveUpdates(() => queryClient.invalidateQueries({ queryKey: ['<ns>'] }))` subscribes to
+`ctx.events` (your backend's `host.events.publish`), batching bursts; React Query's `refetchInterval` should be slow
+(120 s) while `ctx.events.connected()` and faster (15 s) when not.
+
+## Optional host capabilities
+
+`ctx.office`, `ctx.ai`, `ctx.delegation` may be absent: feature-detect and keep a fallback.

package/agent/guides/host-api-versions.md

@@ -0,0 +1,34 @@
+# Host API versions
+
+`hostApiRange` (`^X.Y.Z` or exact `X.Y.Z`) says which shells can run the plugin. Declare the
+**lowest** version whose features you use; the shell refuses a plugin whose range it does not satisfy,
+and upload refuses a manifest field newer than the range (TP-MAN-001), as does doctor for code
+(TP-MAN-002). New plugins with an access catalog start at `^1.22.0`; the scaffold uses `^1.37.0`.
+
+| Host API        | Adds                                                                             |
+| --------------- | -------------------------------------------------------------------------------- |
+| 1.2.0           | frontend route store, user display name                                          |
+| 1.3.0           | frontend event stream (`ctx.events`)                                             |
+| 1.4.0           | plugin configuration                                                             |
+| 1.5.0           | `host.directory`                                                                 |
+| 1.9.0           | AI form filling (`ctx.ai`)                                                       |
+| 1.10.0          | Python backends, `egress`, public routes and pages, plugin knowledge collections |
+| 1.12.0          | `storage.uploadPath`, `get(key, { firstBytes })`, `ctx.hostUrl`                  |
+| 1.14.0          | `ctx.layout.collapseSidebar`                                                     |
+| 1.15.0          | managed downloads (`storage.managedPath`, `authorizeStorage`)                    |
+| 1.17.0 / 1.18.0 | account provisioning / password reset                                            |
+| 1.19.0          | `storage.copy`, streams                                                          |
+| 1.20.0          | Mermaid and HTML diagram rendering                                               |
+| 1.21.0          | `ctx.office`                                                                     |
+| 1.22.0          | access catalog, `@tego/plugin-sdk/access`, `host.tenantId`                       |
+| 1.23.0          | `knowledge.manage`                                                               |
+| 1.26.0          | `proactive.emit`                                                                 |
+| 1.29.0          | `mail.send`                                                                      |
+| 1.30.0          | `agentReadiness`, `settingsRoute`                                                |
+| 1.33.0          | `workDelegation`                                                                 |
+| 1.34.0          | `attention.request`                                                              |
+| 1.37.0          | `ctx.platform`, `ctx.openExternal`, `ctx.download`, `ctx.copyText`               |
+
+Optional members (`ctx.office`, `ctx.ai`, `ctx.delegation`, `ctx.download` before 1.37) must be
+feature-detected when the range admits an older shell. The full API is in
+`agent/reference/plugin-sdk-api.md`.

package/agent/guides/i18n.md

@@ -0,0 +1,17 @@
+# i18n
+
+- **Ten locales (TP-I18N-001)**: `zh-CN zh-TW en ja ko de es fr it pt` in
+  `frontend/i18n/<locale>.json`. `zh-CN` is the reference: every other file has exactly its keys.
+  Upload refuses a missing locale, a missing key, or a nav `labelKey` that no file defines.
+- **One root**: every key under the plugin's own root (`notes.home.title`, `notes.nav.home`,
+  `notes.errors.<code>`). No flat keys with dots in them.
+- **Placeholders (TP-I18N-002)**: `{{name}}` sets match `zh-CN` in every locale; no empty strings.
+- **Literal keys (TP-I18N-003)**: `t('notes.home.title')` must exist. For keys built at runtime
+  (`t(\`notes.status.${status}\`)`) list the variants in a test.
+- **Terms (TP-I18N-004)**: 数字员工 / Employee via `{{avatarTerm}}` (`{{avatarTermShort}}`); 空间
+  Workspace; 技能 Skill; 模板 Template. Never 数字分身 / digital avatar.
+- **Access strings**: with `@tego/plugin-access-ui`, `tego-plugin-pack` merges `tegoAccess.*` into
+  your files; don't copy them.
+- **Test**: `assertLocaleParity(fileURLToPath(new URL('../i18n', import.meta.url)))` from
+  `@tego/plugin-sdk/testing` in a frontend test file runs these checks in `pnpm test`.
+- Translate everything you add in the same change: adding a key to `zh-CN` only fails the build.

package/agent/guides/manifest.md

@@ -0,0 +1,26 @@
+# Manifest and packaging
+
+`tego.plugin.json` at the package root (TP-MAN-001):
+
+- `manifestVersion: 1`; `id` `^[a-z0-9][a-z0-9._-]*$`, stable forever; `version` semver — upgrades
+  install over the same id, downgrades are refused.
+- `displayName` / `description` per locale; `scope`: `avatar` (a capability of chosen employees;
+  required for a claw part) or `tenant` (a workspace app for everyone).
+- `parts.frontend` — `icon` from the closed `PLUGIN_NAV_ICONS` list; `nav` (≤ 20 entries, unique
+  `key`, `labelKey` in your locales, optional `path` of letters, digits, `/_-` only). No `nav` = no page.
+- `parts.backend` — `limits`, `egress` (hosts the backend may call; a bare host means 443),
+  `publicRoutes` (served by `fetchPublic`, no user), `migrationsDir`.
+- `parts.claw` — `claw/openclaw.plugin.json` + `claw/package.json`; the packer stamps the version.
+- `declares` (`database`, `storage`, `events`, `notifications`) are disclosures shown at install and
+  need a backend part.
+- Configuration: `parts.frontend.config` / `parts.backend.config` hold a flat schema (scalars,
+  string enums, string arrays; ≤ 50 fields). `sensitive` only in the backend section. Read it with
+  `host.config.current()` (backend) or `ctx.config` (frontend). Claw config is
+  `configSchema` in `openclaw.plugin.json`, never in the manifest.
+- `hostApiRange`: see host-api-versions.md.
+
+Packaging: `tego-plugin-pack` (the `build` script) builds every part, merges access UI strings,
+runs the upload-blocking doctor checks and writes `build/<id>-<version>.zip`. Never hand-roll the
+SystemJS output. Dependencies (TP-PKG-001): SDK packages under npm aliases —
+`"@tego/plugin-sdk": "npm:@zhama/tego-plugin-sdk@^1.37.0"`, likewise `@tego/ui`,
+`@tego/plugin-access-ui` — or `workspace:*` inside a tego-os checkout.

package/agent/guides/migrations.md

@@ -0,0 +1,17 @@
+# Database migrations
+
+Each install has its own Postgres schema and a restricted role. The host applies
+`backend/migrations/*.sql` in ordinal order, one transaction per file, with `search_path` set to your
+schema only — so nothing is schema-qualified and nothing references a platform table.
+
+- **Names (TP-BE-003)**: `0001_initial.sql`, `0002_add_tags.sql` — numeric ordinal, unique.
+- **Append-only (TP-BE-004)**: a committed migration may already have run on an install; never edit or
+  delete it. Fix forward with a new file.
+- **Source of truth**: the drizzle schema in `backend/schema/*.ts`. `pnpm db:generate` runs
+  `drizzle-kit generate` into `backend/.drizzle/` (committed), then `tego-plugin migrations sync` copies
+  new files into `backend/migrations/` with the next free ordinal and strips `"public".`.
+  `tego-plugin migrations check` (part of `build`) fails when they are out of sync.
+- Hand-write only what drizzle cannot express: functions, triggers, RLS policies.
+- Never `drizzle-kit push`.
+- Test SQL against a real database with `createTestPluginHost({ pluginId, migrationsDir })`
+  (`TEST_DATABASE_URL`); it applies your migrations into a throwaway schema.

package/agent/guides/storage.md

@@ -0,0 +1,18 @@
+# Files and storage
+
+`declares.storage: true`. Keys are relative to your install's prefix.
+
+| Need                                  | Backend                                                                | Frontend                                                                               |
+| ------------------------------------- | ---------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| Small file (≤ 25 MiB) you produce     | `host.storage.put(key, bytes, contentType)`                            | —                                                                                      |
+| User uploads a file                   | `uploadPath(key, { maxBytes, ttlSeconds: 900 })` → return `{ path }`   | `fetch(ctx.hostUrl(path), { method: 'PUT', body: file })`, then POST `/files/register` |
+| Check an upload                       | `head(key)` (size, type), `get(key, { firstBytes: 8 })` (magic bytes)  | —                                                                                      |
+| Let a user download                   | `signedPath(key, 300)` or `managedPath(key, policy, 300)`              | `ctx.download({ path, fileName })`                                                     |
+| Re-check permission on every download | `managedPath` + `authorizeStorage` (needs `storage.managed`)           | same                                                                                   |
+| Copy / stream                         | `copy`, `getStream`, `putStream` (needs `storage.transfer`, host 1.19) | —                                                                                      |
+
+- Never move large files through `ctx.api`: the desktop app buffers it and caps it at 100 MB.
+- Validate type and size on the client first (shared limits in `shared/`), and again on the backend.
+- `authorizeStorage` decides with the access engine:
+  `access.forSubject(await access.subjectFor(userId, host), host)`; deny on any error, and test
+  both allow and deny.

package/agent/guides/testing.md

@@ -0,0 +1,17 @@
+# Tests
+
+Gates (TP-PKG-002): `lint` (eslint), `type-check` (`tsgo --noEmit` per part), `test` (`vitest run`),
+`build` (`tego-plugin-pack`). Run them, plus `tego-plugin doctor`, after every change.
+
+- **Backend**: routes against a real Postgres with `createTestPluginHost({ pluginId, migrationsDir })`
+  (`TEST_DATABASE_URL`); call `backend.fetch(new Request(...), CALLER, harness.host)`. A missing
+  database fails the run, it never silently skips.
+- **Access**: `assertRouteCoverage(app)`; allow _and_ deny cases for every permission you add.
+- **Frontend**: pure logic in `.ts` files (route parser, formatters, API error mapping) — no
+  component tests.
+- **i18n**: `assertLocaleParity(dir)`.
+- **Claw**: `assertClawSkills(skillsDir, toolNames)`; registered tools equal `contracts.tools`.
+- **Style**: each test file starts with a Business Cases comment (domain, then one line per case
+  `NOTE-001  posting a note → 201 and visible on the next list`); every `it` title starts with
+  `[NOTE-001]`. Assert exact status codes and values; at least one failure path per file; no
+  conditional assertions.

package/agent/guides/ui.md

@@ -0,0 +1,22 @@
+# UI and design
+
+Your page sits inside the shell next to its own UI; it must look like part of it in light and dark.
+
+- **Components (TP-UI-002)**: `@tego/ui` first — Button, Input, Select, Dialog, Popover, Tooltip,
+  Tabs, Table, Badge, EmptyState, Loading, Skeleton, toast/Toaster, charts. Never import
+  `@radix-ui/*`; never rebuild a primitive locally.
+- **Colors (TP-UI-001)**: token classes only — surfaces `bg-background bg-card bg-sunken bg-inset
+bg-popover`, text `text-foreground text-muted-foreground`, lines `border-border border-border-strong`,
+  semantic `bg-X text-X-foreground` / `bg-X-soft text-X` with X in
+  `primary signal success warning destructive info`. No hex, `rgb()`, palette classes
+  (`bg-slate-50`, `text-white`, `bg-black/40`) or `dark:` — tokens carry both themes.
+  `primary` means selection/focus, `signal` means "happening now".
+- **Scope (TP-UI-003)**: `tegoPluginTailwind` scopes utilities under `.<pluginId>` (no preflight).
+  Put the class on your root element; portalled content (dialogs, popovers, selects) renders outside
+  it — add `tegoPluginScopeRoot(pluginId)` to PostCSS, or put the class on each `*Content`.
+- **Status** is text or an icon plus color, never color alone. Machine data (ids, amounts, times,
+  versions) uses `font-mono tabular-nums`.
+- **Shapes**: `rounded-control rounded-card rounded-container`; cards `shadow-card`; no card inside
+  a card. Motion: `duration-hover duration-enter`, no decorative infinite animation.
+- **Copy**: short and specific; no explanatory paragraphs on pages; an empty state is one line plus
+  one action. Chinese copy follows the platform terms (空间、数字员工、技能、模板).