@puredesktop/create-app 2.1.7 → 2.1.9

package/template/docs/theme-vars.md

@@ -1,138 +1,138 @@
-# Theme CSS Variables
-
-This file is generated from `packages/ui/src/theme/tokens.ts`.
-
-PureDesktop injects these variables through `AppFrame` and the shell bridge
-theme payload. Use them in app styling instead of hardcoded platform colors,
-spacing, typography, radii, shadows, transitions, or app stacking values.
-
-This static reference is generated by PureDesktop maintainers before the
-create-app package is released.
-
-| Variable | Domain | Light value | Dark value |
-| --- | --- | --- | --- |
-| `--platform-colors-accent` | colors | `#1b1b1e` | `#e5e5e9` |
-| `--platform-colors-accent-hover` | colors | `#1b1b1e` | `#eaeaee` |
-| `--platform-colors-accent-muted` | colors | `#eaeaee` | `#313135` |
-| `--platform-colors-app-viewport` | colors | `#fbfbfc` | `#202024` |
-| `--platform-colors-bg` | colors | `#fbfbfc` | `#202024` |
-| `--platform-colors-border` | colors | `#e5e5e9` | `#313135` |
-| `--platform-colors-border-strong` | colors | `#dadade` | `#43434a` |
-| `--platform-colors-chrome-tab-strip` | colors | `#ececef` | `#1b1b1e` |
-| `--platform-colors-chrome-titlebar` | colors | `#fbfbfc` | `#202024` |
-| `--platform-colors-danger` | colors | `#b23a2e` | `#e0796e` |
-| `--platform-colors-divider` | colors | `#e5e5e9` | `#313135` |
-| `--platform-colors-elevated` | colors | `#ffffff` | `#26262a` |
-| `--platform-colors-focus` | colors | `#1b1b1e` | `#e5e5e9` |
-| `--platform-colors-info` | colors | `#3b6fb0` | `#6fa0e0` |
-| `--platform-colors-selection` | colors | `#eaeaee` | `#313135` |
-| `--platform-colors-semantic-blue` | colors | `#3b6fb0` | `#6fa0e0` |
-| `--platform-colors-semantic-blue-border` | colors | `#b9cbe4` | `#365373` |
-| `--platform-colors-semantic-blue-muted` | colors | `#e8f0fb` | `#1c2a3c` |
-| `--platform-colors-semantic-blue-text` | colors | `#244f87` | `#a8c8f0` |
-| `--platform-colors-semantic-green` | colors | `#1f8a55` | `#57b988` |
-| `--platform-colors-semantic-green-border` | colors | `#1f8a55` | `#32684d` |
-| `--platform-colors-semantic-green-muted` | colors | `#eef7f1` | `#18342a` |
-| `--platform-colors-semantic-green-text` | colors | `#16683f` | `#8fe0b6` |
-| `--platform-colors-semantic-orange` | colors | `#c98a2b` | `#e0b257` |
-| `--platform-colors-semantic-orange-border` | colors | `#e3c98f` | `#6d5b2f` |
-| `--platform-colors-semantic-orange-muted` | colors | `#f3e5c8` | `#3a3322` |
-| `--platform-colors-semantic-orange-text` | colors | `#7a5114` | `#f0ce8a` |
-| `--platform-colors-semantic-red` | colors | `#b23a2e` | `#e0796e` |
-| `--platform-colors-semantic-red-border` | colors | `#dfb7b1` | `#753f38` |
-| `--platform-colors-semantic-red-muted` | colors | `#f4dfdc` | `#3a211d` |
-| `--platform-colors-semantic-red-text` | colors | `#8a2d24` | `#f0a89e` |
-| `--platform-colors-success` | colors | `#1f8a55` | `#57b988` |
-| `--platform-colors-surface` | colors | `#f8f8fa` | `#26262a` |
-| `--platform-colors-surface-active` | colors | `#eaeaee` | `#161619` |
-| `--platform-colors-surface-hover` | colors | `#eaeaee` | `#2c2c30` |
-| `--platform-colors-text` | colors | `#1b1b1e` | `#ececef` |
-| `--platform-colors-text-danger` | colors | `#b23a2e` | `#e0796e` |
-| `--platform-colors-text-disabled` | colors | `#9a9aa0` | `#6e6e74` |
-| `--platform-colors-text-inverse` | colors | `#ffffff` | `#1b1b1e` |
-| `--platform-colors-text-secondary` | colors | `#3a3a3e` | `#c9c9cf` |
-| `--platform-colors-warning` | colors | `#c98a2b` | `#e0b257` |
-| `--platform-radius-full` | radius | `999px` | `999px` |
-| `--platform-radius-lg` | radius | `0px` | `0px` |
-| `--platform-radius-md` | radius | `0px` | `0px` |
-| `--platform-radius-sm` | radius | `0px` | `0px` |
-| `--platform-shadow-lg` | shadow | `0 18px 48px rgb(18 18 22 / 0.13)` | `0 18px 44px rgba(0, 0, 0, 0.38)` |
-| `--platform-shadow-md` | shadow | `0 8px 24px rgb(18 18 22 / 0.08)` | `0 8px 24px rgba(0, 0, 0, 0.3)` |
-| `--platform-shadow-sm` | shadow | `none` | `none` |
-| `--platform-spacing-lg` | spacing | `16px` | `16px` |
-| `--platform-spacing-md` | spacing | `12px` | `12px` |
-| `--platform-spacing-sm` | spacing | `8px` | `8px` |
-| `--platform-spacing-xl` | spacing | `24px` | `24px` |
-| `--platform-spacing-xs` | spacing | `4px` | `4px` |
-| `--platform-spacing-xxl` | spacing | `32px` | `32px` |
-| `--platform-transition-base` | transition | `200ms ease` | `200ms ease` |
-| `--platform-transition-fast` | transition | `120ms ease` | `120ms ease` |
-| `--platform-transition-slow` | transition | `320ms ease` | `320ms ease` |
-| `--platform-typography-font-family` | typography | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` |
-| `--platform-typography-font-family-content` | typography | `'Source Serif 4', Georgia, serif` | `'Source Serif 4', Georgia, serif` |
-| `--platform-typography-font-family-mono` | typography | `'JetBrains Mono', ui-monospace, monospace` | `'JetBrains Mono', ui-monospace, monospace` |
-| `--platform-typography-font-size-base` | typography | `14.5px` | `14.5px` |
-| `--platform-typography-font-size-lg` | typography | `17px` | `17px` |
-| `--platform-typography-font-size-sm` | typography | `13px` | `13px` |
-| `--platform-typography-font-size-xl` | typography | `24px` | `24px` |
-| `--platform-typography-font-size-xs` | typography | `11px` | `11px` |
-| `--platform-typography-font-weight-bold` | typography | `600` | `600` |
-| `--platform-typography-font-weight-medium` | typography | `500` | `500` |
-| `--platform-typography-font-weight-normal` | typography | `400` | `400` |
-| `--platform-typography-line-height-base` | typography | `1.6` | `1.6` |
-| `--platform-typography-line-height-tight` | typography | `1.25` | `1.25` |
-| `--platform-z-index-zi-app-base` | zIndex | `0` | `0` |
-| `--platform-z-index-zi-app-chrome` | zIndex | `20` | `20` |
-| `--platform-z-index-zi-app-menus` | zIndex | `100` | `100` |
-| `--platform-z-index-zi-app-modal` | zIndex | `300` | `300` |
-| `--platform-z-index-zi-app-sidebar` | zIndex | `10` | `10` |
-| `--platform-z-index-zi-app-toast` | zIndex | `200` | `200` |
-| `--platform-z-index-zi-app-viewport-toolbar` | zIndex | `25` | `25` |
-
-## App-Owned Colors
-
-Use platform variables for the base app shell, text, surfaces, borders,
-spacing, typography, radius, shadows, transitions, and z-index.
-
-When the app domain needs colors beyond the platform set, define app-prefixed
-variables and keep them synchronized with the shell theme through
-`data-platform-theme`.
-
-Good use cases for app-owned colors:
-
-- chart series;
-- calendar categories;
-- tags and labels;
-- syntax or document annotations;
-- domain-specific status colors not covered by platform semantic colors.
-
-Pattern:
-
-```ts
-const Root = styled.div`
-  --myapp-chart-blue: #3b73d9;
-  --myapp-chart-blue-muted: color-mix(
-    in srgb,
-    var(--myapp-chart-blue) 12%,
-    var(--platform-colors-surface)
-  );
-
-  [data-platform-theme='dark'] & {
-    --myapp-chart-blue: #8ab4ff;
-    --myapp-chart-blue-muted: color-mix(
-      in srgb,
-      var(--myapp-chart-blue) 18%,
-      var(--platform-colors-surface)
-    );
-  }
-`
-```
-
-Rules for app-owned colors:
-
-- prefix app variables with the app slug or a short app namespace;
-- provide dark-mode values inside `[data-platform-theme='dark'] &`;
-- derive muted fills, hovers, selections, and outlines with `color-mix()` and
-  platform surface, text, border, or background variables;
-- use `--platform-colors-accent` for primary app identity and actions;
-- reserve app-owned colors for domain meaning.
+# Theme CSS Variables
+
+This file is generated from `packages/ui/src/theme/tokens.ts`.
+
+PureDesktop injects these variables through `AppFrame` and the shell bridge
+theme payload. Use them in app styling instead of hardcoded platform colors,
+spacing, typography, radii, shadows, transitions, or app stacking values.
+
+This static reference is generated by PureDesktop maintainers before the
+create-app package is released.
+
+| Variable | Domain | Light value | Dark value |
+| --- | --- | --- | --- |
+| `--platform-colors-accent` | colors | `#1b1b1e` | `#e5e5e9` |
+| `--platform-colors-accent-hover` | colors | `#1b1b1e` | `#eaeaee` |
+| `--platform-colors-accent-muted` | colors | `#eaeaee` | `#313135` |
+| `--platform-colors-app-viewport` | colors | `#fbfbfc` | `#202024` |
+| `--platform-colors-bg` | colors | `#fbfbfc` | `#202024` |
+| `--platform-colors-border` | colors | `#e5e5e9` | `#313135` |
+| `--platform-colors-border-strong` | colors | `#dadade` | `#43434a` |
+| `--platform-colors-chrome-tab-strip` | colors | `#ececef` | `#1b1b1e` |
+| `--platform-colors-chrome-titlebar` | colors | `#fbfbfc` | `#202024` |
+| `--platform-colors-danger` | colors | `#b23a2e` | `#e0796e` |
+| `--platform-colors-divider` | colors | `#e5e5e9` | `#313135` |
+| `--platform-colors-elevated` | colors | `#ffffff` | `#26262a` |
+| `--platform-colors-focus` | colors | `#1b1b1e` | `#e5e5e9` |
+| `--platform-colors-info` | colors | `#3b6fb0` | `#6fa0e0` |
+| `--platform-colors-selection` | colors | `#eaeaee` | `#313135` |
+| `--platform-colors-semantic-blue` | colors | `#3b6fb0` | `#6fa0e0` |
+| `--platform-colors-semantic-blue-border` | colors | `#b9cbe4` | `#365373` |
+| `--platform-colors-semantic-blue-muted` | colors | `#e8f0fb` | `#1c2a3c` |
+| `--platform-colors-semantic-blue-text` | colors | `#244f87` | `#a8c8f0` |
+| `--platform-colors-semantic-green` | colors | `#1f8a55` | `#57b988` |
+| `--platform-colors-semantic-green-border` | colors | `#1f8a55` | `#32684d` |
+| `--platform-colors-semantic-green-muted` | colors | `#eef7f1` | `#18342a` |
+| `--platform-colors-semantic-green-text` | colors | `#16683f` | `#8fe0b6` |
+| `--platform-colors-semantic-orange` | colors | `#c98a2b` | `#e0b257` |
+| `--platform-colors-semantic-orange-border` | colors | `#e3c98f` | `#6d5b2f` |
+| `--platform-colors-semantic-orange-muted` | colors | `#f3e5c8` | `#3a3322` |
+| `--platform-colors-semantic-orange-text` | colors | `#7a5114` | `#f0ce8a` |
+| `--platform-colors-semantic-red` | colors | `#b23a2e` | `#e0796e` |
+| `--platform-colors-semantic-red-border` | colors | `#dfb7b1` | `#753f38` |
+| `--platform-colors-semantic-red-muted` | colors | `#f4dfdc` | `#3a211d` |
+| `--platform-colors-semantic-red-text` | colors | `#8a2d24` | `#f0a89e` |
+| `--platform-colors-success` | colors | `#1f8a55` | `#57b988` |
+| `--platform-colors-surface` | colors | `#f8f8fa` | `#26262a` |
+| `--platform-colors-surface-active` | colors | `#eaeaee` | `#161619` |
+| `--platform-colors-surface-hover` | colors | `#eaeaee` | `#2c2c30` |
+| `--platform-colors-text` | colors | `#1b1b1e` | `#ececef` |
+| `--platform-colors-text-danger` | colors | `#b23a2e` | `#e0796e` |
+| `--platform-colors-text-disabled` | colors | `#9a9aa0` | `#6e6e74` |
+| `--platform-colors-text-inverse` | colors | `#ffffff` | `#1b1b1e` |
+| `--platform-colors-text-secondary` | colors | `#3a3a3e` | `#c9c9cf` |
+| `--platform-colors-warning` | colors | `#c98a2b` | `#e0b257` |
+| `--platform-radius-full` | radius | `999px` | `999px` |
+| `--platform-radius-lg` | radius | `0px` | `0px` |
+| `--platform-radius-md` | radius | `0px` | `0px` |
+| `--platform-radius-sm` | radius | `0px` | `0px` |
+| `--platform-shadow-lg` | shadow | `0 18px 48px rgb(18 18 22 / 0.13)` | `0 18px 44px rgba(0, 0, 0, 0.38)` |
+| `--platform-shadow-md` | shadow | `0 8px 24px rgb(18 18 22 / 0.08)` | `0 8px 24px rgba(0, 0, 0, 0.3)` |
+| `--platform-shadow-sm` | shadow | `none` | `none` |
+| `--platform-spacing-lg` | spacing | `16px` | `16px` |
+| `--platform-spacing-md` | spacing | `12px` | `12px` |
+| `--platform-spacing-sm` | spacing | `8px` | `8px` |
+| `--platform-spacing-xl` | spacing | `24px` | `24px` |
+| `--platform-spacing-xs` | spacing | `4px` | `4px` |
+| `--platform-spacing-xxl` | spacing | `32px` | `32px` |
+| `--platform-transition-base` | transition | `200ms ease` | `200ms ease` |
+| `--platform-transition-fast` | transition | `120ms ease` | `120ms ease` |
+| `--platform-transition-slow` | transition | `320ms ease` | `320ms ease` |
+| `--platform-typography-font-family` | typography | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` | `"Archivo", system-ui, -apple-system, "Segoe UI", sans-serif` |
+| `--platform-typography-font-family-content` | typography | `'Source Serif 4', Georgia, serif` | `'Source Serif 4', Georgia, serif` |
+| `--platform-typography-font-family-mono` | typography | `'JetBrains Mono', ui-monospace, monospace` | `'JetBrains Mono', ui-monospace, monospace` |
+| `--platform-typography-font-size-base` | typography | `14.5px` | `14.5px` |
+| `--platform-typography-font-size-lg` | typography | `17px` | `17px` |
+| `--platform-typography-font-size-sm` | typography | `13px` | `13px` |
+| `--platform-typography-font-size-xl` | typography | `24px` | `24px` |
+| `--platform-typography-font-size-xs` | typography | `11px` | `11px` |
+| `--platform-typography-font-weight-bold` | typography | `600` | `600` |
+| `--platform-typography-font-weight-medium` | typography | `500` | `500` |
+| `--platform-typography-font-weight-normal` | typography | `400` | `400` |
+| `--platform-typography-line-height-base` | typography | `1.6` | `1.6` |
+| `--platform-typography-line-height-tight` | typography | `1.25` | `1.25` |
+| `--platform-z-index-zi-app-base` | zIndex | `0` | `0` |
+| `--platform-z-index-zi-app-chrome` | zIndex | `20` | `20` |
+| `--platform-z-index-zi-app-menus` | zIndex | `100` | `100` |
+| `--platform-z-index-zi-app-modal` | zIndex | `300` | `300` |
+| `--platform-z-index-zi-app-sidebar` | zIndex | `10` | `10` |
+| `--platform-z-index-zi-app-toast` | zIndex | `200` | `200` |
+| `--platform-z-index-zi-app-viewport-toolbar` | zIndex | `25` | `25` |
+
+## App-Owned Colors
+
+Use platform variables for the base app shell, text, surfaces, borders,
+spacing, typography, radius, shadows, transitions, and z-index.
+
+When the app domain needs colors beyond the platform set, define app-prefixed
+variables and keep them synchronized with the shell theme through
+`data-platform-theme`.
+
+Good use cases for app-owned colors:
+
+- chart series;
+- calendar categories;
+- tags and labels;
+- syntax or document annotations;
+- domain-specific status colors not covered by platform semantic colors.
+
+Pattern:
+
+```ts
+const Root = styled.div`
+  --myapp-chart-blue: #3b73d9;
+  --myapp-chart-blue-muted: color-mix(
+    in srgb,
+    var(--myapp-chart-blue) 12%,
+    var(--platform-colors-surface)
+  );
+
+  [data-platform-theme='dark'] & {
+    --myapp-chart-blue: #8ab4ff;
+    --myapp-chart-blue-muted: color-mix(
+      in srgb,
+      var(--myapp-chart-blue) 18%,
+      var(--platform-colors-surface)
+    );
+  }
+`
+```
+
+Rules for app-owned colors:
+
+- prefix app variables with the app slug or a short app namespace;
+- provide dark-mode values inside `[data-platform-theme='dark'] &`;
+- derive muted fills, hovers, selections, and outlines with `color-mix()` and
+  platform surface, text, border, or background variables;
+- use `--platform-colors-accent` for primary app identity and actions;
+- reserve app-owned colors for domain meaning.

package/template/docs/tool-handlers.md

@@ -7,6 +7,9 @@ App agent tools have two halves:
 
 The names must match exactly.
 
+For the exact edit checklist when adding a new tool, read
+[Adding an app agent tool](./adding-agent-tool.md).
+
 ## Generated Structure
 
 When the manifest includes `app.agents.tools`, the generator creates this

package/template/docs/ui-and-components.md

@@ -1,35 +1,56 @@
-# UI And Components
-
-The generated app starts intentionally small. Build the real workflow in
-`src/components/AppShell.tsx` and move domain logic into `src/lib/` as it grows.
-
-## AppFrame
-
-Every render path in `src/App.tsx` uses `AppFrame`. This gives the iframe the
-PureDesktop reset, theme CSS variables, and shell-compatible surface styling.
-
-## Component Shape
-
-Start with controlled, simple components:
-
-```text
-src/
-  components/
-    AppShell.tsx
-    ItemList.tsx
-    ItemDetail.tsx
-  lib/
-    items.ts
-    items.test.ts
-```
-
-Keep app state close to the workflow until a shared hook or reducer removes real
-duplication.
-
-## Platform Components
-
+# UI And Components
+
+The generated app starts with a small starter workspace so the iframe has a
+useful screen while the first builder task runs. Treat the starter as temporary
+scaffold, not product UI.
+
+`src/App.tsx` owns bridge readiness and `AppFrame`. `src/components/AppShell.tsx`
+is the thin composition root after boot succeeds. Do not turn either file into
+the product implementation.
+
+## AppFrame
+
+Every render path in `src/App.tsx` uses `AppFrame`. This gives the iframe the
+PureDesktop reset, theme CSS variables, and shell-compatible surface styling.
+
+## App Structure
+
+Use the first real product task to replace the starter workspace with app-owned
+surfaces. Keep responsibilities split:
+
+- `src/App.tsx`: bridge readiness, boot loading, error states, and `AppFrame`.
+- `src/components/AppShell.tsx`: thin composition root that wires boot data into
+  product surfaces.
+- `src/components/*`: product screens, panels, lists, editors, dialogs, and
+  controls.
+- `src/hooks/*`: reusable workflow state, effects, synchronization, and bridge
+  orchestration.
+- `src/lib/*`: domain types, reducers, rules, transforms, fixtures, and tests.
+
+Start with controlled, simple modules:
+
+```text
+src/
+  components/
+    AppShell.tsx
+    StarterWorkspace.tsx       # replace when the first product surface exists
+    ProjectBoard.tsx
+    ProjectDetail.tsx
+  hooks/
+    useProjects.ts
+  lib/
+    projects.ts
+    projects.test.ts
+```
+
+Keep state local only while it is display-only. When state drives multiple
+components, persistence, agent tools, bridge calls, or domain rules, move it into
+an app hook or `src/lib` module before adding more screens.
+
+## Platform Components
+
 Import shared UI by exact exported package paths before creating custom
-primitives. Do not invent component folders.
+primitives. Use existing app folders before creating new ones.
 
 Useful starting points:
 
@@ -38,23 +59,26 @@ Useful starting points:
 - `Heading` from `@puredesktop/puredesktop-ui-bridge/components/common/typography/Heading`
 - `Text` from `@puredesktop/puredesktop-ui-bridge/components/common/typography/Text`
 - `Button` from `@puredesktop/puredesktop-ui-bridge/components/common/buttons/Button`
-
-## Styling
-
-Use styled-components and platform CSS variables:
-
-```ts
-const Root = styled.div`
-  display: flex;
-  flex-direction: column;
-  gap: var(--platform-spacing-md);
-  color: var(--platform-colors-text);
-  background: var(--platform-colors-bg);
-`
-```
-
-Use app-local CSS variables only for app-specific meaning, for example
-`--{{APP_SLUG}}-accent`.
-
-See [Theme CSS variables](./theme-vars.md) for the generated list of available
-platform variables by domain.
+
+## Styling
+
+Use styled-components and platform CSS variables:
+
+```ts
+const Root = styled.div`
+  display: flex;
+  flex-direction: column;
+  gap: var(--platform-spacing-md);
+  color: var(--platform-colors-text);
+  background: var(--platform-colors-bg);
+`
+```
+
+Use app-local CSS variables only for app-specific meaning, for example
+`--{{APP_SLUG}}-accent`.
+
+See [Theme CSS variables](./theme-vars.md) for the generated list of available
+platform variables by domain.
+
+Avoid inline styles except for tiny dynamic values that cannot be represented as
+props on a styled component.

package/template/package.json

@@ -10,7 +10,7 @@
     "puredesktop:check": "node scripts/validate-puredesktop-app.mjs"
   },
   "dependencies": {
-    "@puredesktop/puredesktop-ui-bridge": "2.1.7",
+    "@puredesktop/puredesktop-ui-bridge": "2.1.8",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
     "styled-components": "^6.1.18"

package/template/plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "id": "{{PLUGIN_ID}}",
   "name": "{{APP_TITLE}}",
-  "permissions": ["network", "settings", "agents"],
+  "permissions": ["network", "settings", "filesystem", "agents"],
   "entrypoint": {
     "kind": "dev-url",
     "url": "http://localhost:{{APP_PORT}}"

package/template/scripts/validate-puredesktop-app.mjs

@@ -20,9 +20,10 @@ if (packageJson) {
   validatePackageJson(packageJson)
 }
 
-if (manifest) {
-  validateManifest(manifest)
-}
+if (manifest) {
+  validateManifest(manifest)
+  await validateBridgePermissionUsage(manifest)
+}
 
 if (await isDirectory(distPath)) {
   info.push('dist folder is present for static registration.')
@@ -135,7 +136,7 @@ function validateManifest(manifest) {
   if (errors.length === 0) info.push('plugin.json is valid.')
 }
 
-function validateEntrypoint(entrypoint, permissions) {
+function validateEntrypoint(entrypoint, permissions) {
   if (!isPlainObject(entrypoint)) {
     errors.push('entrypoint is required.')
     return
@@ -169,10 +170,47 @@ function validateEntrypoint(entrypoint, permissions) {
     }
     return
   }
-  errors.push(`Unsupported entrypoint kind: ${String(entrypoint.kind ?? '') || '(missing)'}.`)
-}
-
-async function validateAgentTools(manifest, distPath) {
+  errors.push(`Unsupported entrypoint kind: ${String(entrypoint.kind ?? '') || '(missing)'}.`)
+}
+
+async function validateBridgePermissionUsage(manifest) {
+  const permissions = Array.isArray(manifest.permissions) ? manifest.permissions : []
+  const sourceText = await readProjectText(join(ROOT, 'src'))
+  const requirements = [
+    {
+      permission: 'filesystem',
+      hints: [
+        '/bridge/storage',
+        '/bridge/fs',
+        '/bridge/dialog',
+        '/bridge/react/usePlatformJsonStore',
+      ],
+    },
+    {
+      permission: 'settings',
+      hints: [
+        '/bridge/appSettings',
+        '/bridge/preferences',
+        '/bridge/react/usePlatformAppSettings',
+        '/bridge/react/usePlatformPreferences',
+      ],
+    },
+    {
+      permission: 'network',
+      hints: ['/bridge/network', '/bridge/vision'],
+    },
+  ]
+
+  for (const requirement of requirements) {
+    if (permissions.includes(requirement.permission)) continue
+    if (!requirement.hints.some(hint => sourceText.includes(hint))) continue
+    errors.push(
+      `Source imports ${requirement.permission}-gated bridge helpers, so plugin.json must include the ${requirement.permission} permission.`,
+    )
+  }
+}
+
+async function validateAgentTools(manifest, distPath) {
   const tools = manifest.app?.agents?.tools ?? []
   if (!Array.isArray(tools) || tools.length === 0) {
     info.push('No app agent tools declared.')

package/template/src/App.tsx

@@ -1,9 +1,10 @@
 import { AppFrame } from '@puredesktop/puredesktop-ui-bridge/components/common/containers/AppFrame'
 import { EmptyState } from '@puredesktop/puredesktop-ui-bridge/components/common/feedback/EmptyState'
 import { usePlatformBridge } from '@puredesktop/puredesktop-ui-bridge/bridge/react/usePlatformBridge'
-import { AppShell } from './components/AppShell'
-import { isStandaloneDevMode } from './bridge/platformBridge'
-import { useAppBoot } from './hooks/useAppBoot'
+import { AppShell } from './components/AppShell'
+import { isStandaloneDevMode } from './bridge/platformBridge'
+import { APP_TITLE } from './constants'
+import { useAppBoot } from './hooks/useAppBoot'
 
 export function App(): React.ReactElement {
   const { error: bridgeError, ready } = usePlatformBridge()
@@ -28,7 +29,7 @@ export function App(): React.ReactElement {
       <AppFrame>
         <EmptyState
           tone={bootError ? 'error' : 'neutral'}
-          title={bootError ? 'Boot failed' : '{{APP_TITLE}}'}
+          title={bootError ? 'Boot failed' : APP_TITLE}
           message={
             bootError
               ? bootError.message

package/template/src/components/AppShell.tsx

@@ -1,33 +1,11 @@
-import styled from 'styled-components'
-import { Heading } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Heading'
-import { Text } from '@puredesktop/puredesktop-ui-bridge/components/common/typography/Text'
-import type { AppSettings } from '../types'
-
-const Root = styled.div`
-  display: flex;
-  flex-direction: column;
-  gap: 12px;
-  padding: 32px;
-  max-width: 720px;
-`
-
-export interface AppShellProps {
-  settings: AppSettings
-}
-
-export function AppShell({ settings }: AppShellProps): React.ReactElement {
-  return (
-    <Root>
-      <Heading level={1}>{{APP_TITLE}}</Heading>
-      <Text>
-        Start building in <code>src/components/AppShell.tsx</code>. Bridge boot
-        is wired — AppFrame, settings load, and standalone browser dev all work.
-      </Text>
-      {Object.keys(settings).length > 0 ? (
-        <Text size="sm" tone="secondary">
-          Loaded {Object.keys(settings).length} setting key(s).
-        </Text>
-      ) : null}
-    </Root>
-  )
-}
+import type { AppSettings } from '../types'
+import { APP_TITLE } from '../constants'
+import { StarterWorkspace } from './StarterWorkspace'
+
+export interface AppShellProps {
+  settings: AppSettings
+}
+
+export function AppShell({ settings }: AppShellProps): React.ReactElement {
+  return <StarterWorkspace appName={APP_TITLE} settings={settings} />
+}