@pablozaiden/webapp 0.1.0 → 0.2.1

package/README.md

@@ -1,10 +1,10 @@
 # @pablozaiden/webapp
 
-Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, passkey auth, API keys, device auth, realtime websocket state, settings, binary builds and Docker images.
+Opinionated Bun + React framework for single-server TypeScript webapps: one Bun process serves the React UI, API routes, multi-user passkey auth, user-owned API keys, device auth, realtime websocket state, scoped settings, binary builds and Docker images.
 
 ## Quick start
 
-Use one of the examples while the package is private:
+Use one of the examples during framework development:
 
 ```bash
 bun install
@@ -19,8 +19,9 @@ Both examples run with Bun native hot reload through `bun --hot`, with no standa
 | Export | Use |
 | --- | --- |
 | `@pablozaiden/webapp/server` | `createWebAppServer`, route helpers, responses, SQLite store |
-| `@pablozaiden/webapp/web` | `WebAppRoot`, sidebar types, UI controls, realtime hooks |
+| `@pablozaiden/webapp/web` | `WebAppRoot`, `renderWebApp`, sidebar types, UI controls, realtime hooks |
 | `@pablozaiden/webapp/contracts` | Shared auth/config/device/API-key types |
+| `@pablozaiden/webapp/cli` | One-binary command helpers, device-auth credentials and generic API CLI caller |
 | `@pablozaiden/webapp/build` | Bun single-binary compile helper |
 
 See `docs/getting-started.md` for the minimum app shape and `examples/notes-todo` for a realistic app. Use `docs/github-actions.md` when adding CI, Docker and release workflows to an app built with the framework. Use `bun run screenshots` for reproducible manual visual captures. Release/publishing details for this package are in `docs/release.md`.

package/docs/auth-validation.md

@@ -1,17 +1,36 @@
 # Auth validation checklist
 
-Run this checklist before migrating an app or cutting a checkpoint.
+Run this checklist before releasing a framework app or cutting a checkpoint.
 
 ## Passkeys
 
 1. Start the app with passkeys enabled and an empty data dir.
-2. Confirm the bootstrap screen appears before the shell.
-3. Register a passkey with the browser/platform authenticator.
-4. Confirm the app shell loads and Settings shows passkey configured.
+2. Confirm the owner bootstrap screen appears before the shell.
+3. Register the owner username and passkey with the browser/platform authenticator.
+4. Confirm the app shell loads and Settings shows the owner account and passkey configured.
 5. Click Logout and confirm reload/login requires passkey authentication.
 6. Authenticate with the registered passkey and confirm the shell loads again.
 7. Delete passkey from Settings, confirm the dialog supports Escape, X and Cancel.
-8. Confirm deleting returns to bootstrap on reload.
+8. Confirm deleting the owner passkey shows owner re-setup on reload.
+
+## Users and roles
+
+1. As owner/admin, create a non-admin user and copy the one-time setup link.
+2. Open `/setup?token=...` in a fresh context and register that user's passkey.
+3. Confirm the new user can sign in and does not see admin-only settings.
+4. Confirm app data is empty for a newly-created non-owner user unless explicitly provisioned.
+5. Promote the user to admin and confirm user management appears.
+6. Demote the user and confirm admin settings disappear.
+7. Reset the user and confirm old sessions/API keys/device sessions no longer work.
+8. Confirm owner cannot be reset, deleted, or demoted.
+
+## App data isolation
+
+1. Create data as owner and as a non-owner user.
+2. Confirm list endpoints return only the current user's data.
+3. Confirm item endpoints return 404 for another user's IDs.
+4. Confirm user-owned realtime events reach only sockets authenticated as the owning user.
+5. Confirm public endpoints intentionally attach data to the correct owner/user and never broadcast user-owned IDs globally.
 
 ## API keys
 

package/docs/auth.md

@@ -2,19 +2,43 @@
 
 The framework provides three auth modes designed to coexist.
 
-## Passkeys
+## Users and passkeys
 
-Passkeys follow a single-passkey bootstrap model:
+Passkeys are multi-user. The first run creates the immutable owner user and that user's passkey.
 
-1. If no passkey exists, registration is allowed.
-2. Once a passkey exists, protected routes require an authenticated passkey browser session, API key, or device bearer token.
-3. Additional public registration is rejected after bootstrap.
+1. If no users exist, the UI asks for the owner username and passkey.
+2. The owner cannot be deleted or demoted.
+3. Owners and admins create users from Settings, which returns a one-time 24h setup link.
+4. Users complete setup from `/setup?token=...`; usernames are lowercase, immutable and unique.
+5. Admin resets clear the user's passkey, API keys and device sessions, then issue a new one-time setup link.
+6. If the owner passkey is deleted, the owner setup screen is shown again.
 
-Settings owns passkey logout/delete UX.
+Route handlers get `ctx.auth.user` plus helpers:
+
+```ts
+const user = ctx.requireUser();
+const admin = ctx.requireAdmin();
+ctx.assertUser(userId);
+```
+
+For app-owned data, prefer the ownership helpers so every route has the same self-only behavior:
+
+```ts
+GET: (_req, ctx) => jsonResponse(ctx.filterOwned(items));
+
+PATCH: (_req, ctx) => {
+  const item = ctx.requireOwned(items.find((candidate) => candidate.id === ctx.params.id));
+  return jsonResponse(item);
+}
+```
+
+`ctx.requireOwned()` returns 404 for missing resources and for resources owned by another user, avoiding cross-user existence leaks. For user-owned realtime updates, publish through `ctx.userRealtime` instead of the global `ctx.realtime`.
+
+`{PREFIX}_DISABLE_PASSKEY=true` is an emergency bypass that logs in as the existing owner only. It does not create the owner.
 
 ## API keys
 
-API keys are bearer tokens for scripts and agents. They are stored hashed in SQLite and shown only once at creation. Route `scopes` are enforced for API-key requests; `*` grants all scopes.
+API keys are user-owned bearer tokens for scripts and agents. They are stored hashed in SQLite and shown only once at creation. Route `scopes` are enforced for API-key requests; `*` grants all scopes.
 
 Same-origin checks are skipped for API-key and device bearer requests unless a route sets `sameOrigin: "always"`, because non-browser clients usually do not send `Origin`.
 
@@ -26,9 +50,9 @@ Device auth is included in V1:
 2. Server returns `device_code`, human `user_code`, `verification_uri`, and polling interval.
 3. Browser user opens `/device?user_code=...` and approves from the same-origin UI.
 4. Client exchanges the approved code at `/api/auth/token`.
-5. Access tokens are JWT bearer tokens; refresh tokens rotate on every refresh.
+5. Access tokens are JWT bearer tokens whose `sub` is the approving user id; refresh tokens rotate on every refresh.
 
-Device codes are one-use. Reusing a consumed device code or stale refresh token returns `invalid_grant`.
+Device codes are one-use. Device sessions are self-only in Settings. Reusing a consumed device code or stale refresh token returns `invalid_grant`.
 
 ## Same-origin policy
 

package/docs/cli.md

@@ -0,0 +1,45 @@
+# CLI helpers
+
+Apps built with the framework should be one app and one binary. The binary can expose subcommands such as `serve`, `version`, `update`, app-specific commands, and optional framework-backed commands like `auth`, `status`, `api` and `schema`.
+
+Use `@pablozaiden/webapp/cli` for small composable helpers, not a mandatory CLI framework:
+
+```ts
+import { dispatchCliCommand, printCliResult } from "@pablozaiden/webapp/cli";
+
+const result = await dispatchCliCommand({
+  args: Bun.argv.slice(2),
+  help: "Usage: my-app <serve|version|notify>",
+  defaultCommand: "serve",
+  commands: {
+    serve: async () => {
+      app.start();
+      await new Promise(() => undefined);
+      return { exitCode: 0 };
+    },
+    version: () => ({ exitCode: 0, output: version }),
+    notify: (args) => runNotifyCommand(args),
+  },
+});
+
+process.exitCode = printCliResult(result);
+```
+
+Device-auth CLI helpers can be composed into apps that need authenticated CLI calls. Public-token commands, such as webhook notification commands, can stay app-owned and do not need framework auth.
+
+Route metadata can power generic API commands:
+
+```ts
+import { runApiCliCommand } from "@pablozaiden/webapp/cli";
+import { createRouteCatalog } from "@pablozaiden/webapp/server";
+
+const catalog = createRouteCatalog(routes);
+const result = await runApiCliCommand({
+  catalog,
+  args,
+  baseUrl: "http://localhost:3000",
+  credentials,
+});
+```
+
+`runApiCliCommand` can list endpoints, print schema metadata, call endpoints with `--method` and `--payload`, attach bearer credentials, and refresh once on `401`.

package/docs/deployment.md

@@ -22,8 +22,11 @@ Run the binary with the same CLI contract:
 ```bash
 MY_APP_PORT=3300 ./dist/my-app serve
 ./dist/my-app version
+./dist/my-app api items
 ```
 
+Keep server and CLI modes in the same binary. App-specific commands and framework-backed commands should be subcommands of that binary rather than separate executables.
+
 ## Docker
 
 Examples include Dockerfiles that copy a Bun-compiled Linux binary into a runtime image. Build the binary for the container architecture first, then build the image:

package/docs/getting-started.md

@@ -4,11 +4,25 @@ Apps are one Bun application: backend routes, websocket, React UI and static ass
 
 ```ts
 import webIndex from "./index.html";
-import { createWebAppServer, defineRoutes, jsonResponse } from "@pablozaiden/webapp/server";
+import { createWebAppServer, defineRoutes, jsonResponse, parseJson } from "@pablozaiden/webapp/server";
+
+const items: Array<{ id: string; userId: string; title: string }> = [];
 
 const routes = defineRoutes({
   "/api/items": {
-    GET: () => jsonResponse([{ id: "one", title: "One" }]),
+    auth: "user",
+    description: "List or create items.",
+    cliPath: "items",
+    tags: ["items"],
+    GET: (_req, ctx) => jsonResponse(ctx.filterOwned(items)),
+    async POST(req, ctx) {
+      const user = ctx.requireUser();
+      const body = await parseJson<{ title: string }>(req);
+      const item = { id: crypto.randomUUID(), userId: user.id, title: body.title };
+      items.push(item);
+      ctx.userRealtime.publishEntityChanged("items", item.id);
+      return jsonResponse(item);
+    },
   },
   "/api/webhooks/:source/:token": {
     auth: "public",
@@ -29,13 +43,39 @@ const app = createWebAppServer({
 await app.runFromCli();
 ```
 
-Frontend entrypoints should import the framework CSS explicitly so Bun hot reload observes style changes:
+Apps should stay one app and one binary. Use subcommands for different modes:
 
-```ts
-import { WebAppRoot } from "@pablozaiden/webapp/web";
+```bash
+my-app serve
+my-app version
+my-app api items
+my-app notify --message "optional app-owned command"
+```
+
+See `docs/cli.md` for framework CLI helpers and generic API command support.
+
+Frontend entrypoints should use `renderWebApp` so Bun/browser hot reload reuses the existing React root instead of calling `createRoot()` twice. Import the framework CSS explicitly so Bun hot reload observes style changes:
+
+```tsx
+import { WebAppRoot, renderWebApp } from "@pablozaiden/webapp/web";
 import "@pablozaiden/webapp/web/styles.css";
+
+function Home() {
+  return <main className="wapp-main-content">Hello</main>;
+}
+
+renderWebApp(
+  <WebAppRoot
+    appName="My App"
+    homeRoute={{ view: "home" }}
+    sidebar={{ getNodes: () => [] }}
+    routes={{ home: <Home /> }}
+  />,
+);
 ```
 
+`renderWebApp` renders into `#root` by default and reuses the existing React root across hot reloads. Pass a custom element id or `Element` only when the app uses a different mount point.
+
 Recommended dev script:
 
 ```json
@@ -50,11 +90,11 @@ The app configures an uppercase `envPrefix`; the framework reads only variables
 
 | Variable | Default | Description |
 | --- | --- | --- |
-| `{PREFIX}_HOST` | `127.0.0.1` | Bind host |
+| `{PREFIX}_HOST` | `localhost` | Bind host |
 | `{PREFIX}_PORT` | `3000` | Bind port |
 | `{PREFIX}_DATA_DIR` | `./data` | SQLite persistence directory |
 | `{PREFIX}_LOG_LEVEL` | `info` | `trace`, `debug`, `info`, `warn`, `error`; locks settings log-level control when set |
-| `{PREFIX}_DISABLE_PASSKEY` | unset | Development escape hatch |
+| `{PREFIX}_DISABLE_PASSKEY` | unset | Emergency bypass that logs in as the existing owner; it does not create users |
 | `{PREFIX}_DISABLE_SAME_ORIGIN_CHECK` | unset | Development/testing escape hatch |
 | `{PREFIX}_PUBLIC_BASE_URL` | request origin | External URL for device auth links |
 | `{PREFIX}_AUTH_ISSUER` | `urn:{prefix}:webapp` | JWT issuer override |

package/docs/github-actions.md

@@ -1,6 +1,6 @@
 # GitHub Actions for framework apps
 
-Use these templates for applications built with `@pablozaiden/webapp`. They follow the same deployment pattern as the reference apps:
+Use these templates for applications built with `@pablozaiden/webapp`. They follow the framework deployment pattern:
 
 1. Pull requests install, build, test and smoke-test the Bun dev server.
 2. Merges to `main` publish a `main` Docker image to GHCR.
@@ -31,6 +31,8 @@ The templates assume these package scripts:
 
 If the app uses TypeScript typechecking separately, add a `tsc` script and call it from the PR workflow before tests.
 
+The smoke templates only hit health/static/public endpoints. `MY_APP_DISABLE_PASSKEY=true` authenticates as the existing owner when one exists; it does not create an owner in an empty data directory. If a smoke test needs protected app APIs, seed a test owner in `MY_APP_DATA_DIR` first or add a deliberate public smoke endpoint.
+
 ## Dockerfile
 
 Place this at `Dockerfile` in the app repository root. It builds the app inside Docker, copies only the standalone Bun binary into a slim runtime image, runs as a non-root user, and exposes `/api/health` as the container healthcheck.
@@ -255,11 +257,11 @@ jobs:
         id: image
         run: echo "name=ghcr.io/${GITHUB_REPOSITORY,,}" >> "$GITHUB_OUTPUT"
 
-      - name: Build and push Docker image
+      - name: Build Docker image
         uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7
         with:
           context: .
-          push: true
+          push: false
           load: true
           tags: ${{ steps.image.outputs.name }}:main
           cache-from: type=gha
@@ -286,6 +288,9 @@ jobs:
 
           test "$(docker inspect --format='{{.State.Health.Status}}' my-app-main-smoke)" = "healthy"
           curl -fsS http://127.0.0.1:8080/api/health >/dev/null
+
+      - name: Push Docker image
+        run: docker push ${{ steps.image.outputs.name }}:main
 ```
 
 ## Binary release workflow

package/docs/realtime.md

@@ -8,8 +8,9 @@ type AppEvent = ResourceRealtimeEvent;
 const routes = defineRoutes<AppEvent>({
   "/api/todos": {
     async POST(req, ctx) {
-      const todo = await createTodo(req);
-      ctx.realtime.publishEntityChanged("todos", todo.id);
+      const user = ctx.requireUser();
+      const todo = await createTodo(user.id, req);
+      ctx.userRealtime.publishEntityChanged("todos", todo.id);
       return jsonResponse(todo);
     },
   },
@@ -25,6 +26,8 @@ Standard events have `type`, `resource`, `action`, optional `id`, optional `scop
 | `publishDeleted("todos", id)` | `{ type: "todos.deleted", resource: "todos", action: "deleted", id }` |
 | `publishSettingsChanged()` | `{ type: "settings.changed", resource: "settings", action: "changed" }` |
 
+For records that belong to the signed-in user, use `ctx.userRealtime.publishChanged`, `publishEntityChanged`, `publishDeleted`, or `publishSettingsChanged`. These helpers target only websocket connections authenticated as that user, so other users do not receive entity ids or timing signals.
+
 Frontend code can refresh declaratively:
 
 ```tsx
@@ -58,4 +61,6 @@ useRealtimeRefresh({
 ctx.realtime.publishEntityChanged("todos", todo.id, { scope: workspaceId });
 ```
 
+Use scoped/global `ctx.realtime` for non-user scopes only when the server validates access to that scope. For per-user app data, prefer `ctx.userRealtime` instead of trusting a client-provided websocket filter.
+
 `ctx.realtime.publish(customEvent)` and `useRealtime({ onEvent })` still exist as low-level escape hatches. The hook reconnects with exponential backoff and uses the same origin as the page.

package/docs/server.md

@@ -5,17 +5,34 @@ Use `createWebAppServer` with `defineRoutes`. Route patterns support exact path
 ```ts
 const routes = defineRoutes<AppEvent>({
   "/api/projects": {
-    GET: () => jsonResponse(projects),
+    auth: "user",
+    description: "List or create projects.",
+    cliPath: "projects",
+    tags: ["projects"],
+    GET: (_req, ctx) => {
+      return jsonResponse(ctx.filterOwned(projects));
+    },
     async POST(req, ctx) {
+      const user = ctx.requireUser();
       const body = await parseJson<{ name: string }>(req);
-      const project = createProject(body.name);
-      ctx.realtime.publishEntityChanged("projects", project.id);
+      const project = createProject(user.id, body.name);
+      ctx.userRealtime.publishEntityChanged("projects", project.id);
       return jsonResponse(project);
     },
   },
   "/api/projects/:id": {
+    auth: "user",
     scopes: ["projects:write"],
-    PATCH: updateProject,
+    async PATCH(req, ctx) {
+      const project = ctx.requireOwned(await findProject(ctx.params.id));
+      Object.assign(project, await parseJson<Partial<Project>>(req));
+      ctx.userRealtime.publishEntityChanged("projects", project.id);
+      return jsonResponse(project);
+    },
+  },
+  "/api/admin/summary": {
+    auth: "admin",
+    GET: () => jsonResponse(adminSummary()),
   },
 });
 ```
@@ -27,9 +44,38 @@ Route defaults are intentionally secure:
 | `auth` | `required` | Requires passkey session, API key or device bearer token once auth is configured |
 | `sameOrigin` | `mutations` | Requires `Origin`/`Referer` for cookie/browser mutations |
 | `scopes` | `[]` | Checked for API keys and device tokens; `*` grants all |
+| `userParam` | unset | Optional route param name that must match the current user id |
 
 Set `auth: "public", sameOrigin: "never"` only for deliberate unauthenticated endpoints such as health probes, webhooks or callback receivers.
 
+Route definitions can include optional metadata. This keeps the API route table as the single source of truth for handlers, CLI endpoint listing, schema output and docs:
+
+| Field | Meaning |
+| --- | --- |
+| `description` | Human-readable route description |
+| `cliPath` | CLI-friendly path; defaults to the API path without `/api/` |
+| `tags` | Grouping labels for docs/CLI |
+| `requestSchema`, `querySchema`, `responseSchema` | Optional schema objects for CLI/docs |
+| `catalog: false` | Exclude a route from generated catalogs |
+
+Use `createRouteCatalog(routes)` and `findRouteCatalogEntry(catalog, input)` to power app CLI commands without maintaining a second route catalog.
+
+Prefer explicit `auth: "user"`, `auth: "admin"` or `auth: "owner"` on app routes. They enforce the role before the handler runs, including API-key and device bearer requests.
+
+Route context is user-aware:
+
+| Helper | Meaning |
+| --- | --- |
+| `ctx.requireUser()` | Returns the current user or throws 401 |
+| `ctx.requireAdmin()` | Returns owner/admin users or throws 403 |
+| `ctx.requireOwner()` | Returns the owner or throws 403 |
+| `ctx.assertUser(userId)` | Throws unless the current user id matches |
+| `ctx.filterOwned(records)` | Returns only records whose `userId` is the current user id |
+| `ctx.requireOwned(record)` | Returns a user-owned record or throws 404 for missing/other-user records |
+| `ctx.userRealtime.*` | Publishes realtime events only to sockets authenticated as the current user |
+
+Use `ctx.filterOwned(records, getUserId)` and `ctx.requireOwned(record, getUserId)` when app records use a different ownership field. Return 404 for other-user resources so route responses do not reveal whether another user's id exists.
+
 Built-in endpoints include:
 
 | Endpoint | Purpose |
@@ -37,9 +83,48 @@ Built-in endpoints include:
 | `GET /api/health` | Health/version |
 | `GET /api/config` | Safe framework config for UI |
 | `/api/passkey-auth/*` | Passkey bootstrap/login/logout/delete |
+| `/api/user-setup*` | One-time invite/reset setup links |
+| `/setup` | Browser setup screen for one-time invite/reset links |
+| `/api/users`, `/api/users/:id/*`, `/api/audit-events` | Admin user management and audit log |
 | `/api/api-keys` | Browser-managed API key create/list/delete |
 | `/api/auth/device`, `/api/auth/token`, `/api/auth/refresh`, `/api/auth/revoke` | Device auth and refresh-token flow |
+| `/device` | Browser device-code approval screen |
 | `/.well-known/jwks.json`, `/.well-known/openid-configuration` | Token verification metadata |
 | `/api/preferences/theme`, `/api/preferences/log-level` | Settings persistence |
 | `/api/server/kill` | Authenticated server shutdown |
 | `/api/ws` | Realtime websocket by default |
+
+## Public/static routes
+
+Declare public non-API assets explicitly with `publicRoutes`:
+
+```ts
+createWebAppServer({
+  // ...
+  publicRoutes: {
+    "/manifest.webmanifest": {
+      headers: { "content-type": "application/manifest+json" },
+      GET: manifestJson,
+    },
+    "/service-worker": serviceWorker,
+  },
+});
+```
+
+Only declared public routes are served this way. Unknown `/api/*` paths still return `404`, while normal frontend paths still return the React index.
+
+## App-owned websocket upgrades
+
+Normal app state should use framework realtime. For raw transports such as terminals, VNC, or port-forward proxies, route handlers may call `ctx.server?.upgrade(...)` and return `undefined`:
+
+```ts
+"/api/terminal": {
+  auth: "user",
+  sameOrigin: "always",
+  GET: (req, ctx) => ctx.server?.upgrade(req, {
+    data: { webappSocketHandler: "terminal", sessionId: ctx.params.id },
+  }) ? undefined : new Response("Upgrade failed", { status: 400 }),
+}
+```
+
+Register matching handlers with `websockets`. Framework auth and same-origin checks run before the upgrade route handler.

package/docs/settings.md

@@ -2,13 +2,19 @@
 
 Settings is framework-owned so apps stay consistent. It includes:
 
-- Passkey logout/delete
-- API key create/list/delete when enabled
-- Theme preference: system/light/dark
-- Log-level preference unless `{PREFIX}_LOG_LEVEL` is set
-- Server kill
+- Account summary and passkey logout/delete
+- API key create/list/delete for the current user when enabled
+- Device-auth sessions for the current user when enabled
+- Theme preference: system/light/dark, stored per user
+- Admin user management
+- Admin log-level preference unless `{PREFIX}_LOG_LEVEL` is set
+- Admin server kill
 - Version/about
 
+Destructive actions in Settings use the framework `ConfirmDialog` before mutating. This includes deleting users, deleting API keys, deleting passkeys, revoking device-auth sessions, and killing the server.
+
+The server kill control follows the normal Settings row layout: explanation on the left, action on the right. After confirmation and a successful response, Settings shows a 15-second shutdown countdown progress bar that visibly drains before reloading the page.
+
 Apps can append structured custom sections:
 
 ```tsx
@@ -18,6 +24,7 @@ Apps can append structured custom sections:
       {
         id: "sync",
         title: "Sync",
+        scope: "user",
         rows: [
           {
             id: "last-sync",
@@ -28,6 +35,7 @@ Apps can append structured custom sections:
           {
             id: "disconnect",
             title: "Disconnect",
+            scope: "admin",
             description: "Stops syncing this workspace.",
             danger: true,
             actions: [{ id: "disconnect", label: "Disconnect", variant: "danger", onAction: disconnect }],
@@ -40,3 +48,5 @@ Apps can append structured custom sections:
 ```
 
 `render` remains available as an escape hatch for custom controls inside a section. Prefer structured `rows` for simple settings because the framework keeps spacing, typography and danger-zone styling consistent.
+
+`scope` can be `user`, `admin` or `owner` on both sections and rows. Omitted scope behaves like `user`. Use `admin` for global app/server settings and `user` for preferences or data that belong to the signed-in user.

package/docs/sidebar.md

@@ -9,7 +9,7 @@
   sidebar={{
     topActions: [
       { id: "activity", title: "Activity", route: { view: "home" } },
-      { id: "new", title: "New item", route: { view: "new" } },
+      { id: "inbox", title: "Inbox", route: { view: "inbox" } },
     ],
     getNodes: ({ search }) => buildSidebarNodes(search),
   }}
@@ -29,7 +29,7 @@ Sidebar nodes support:
 | `type` | `section` or `item` |
 | `route` | Hash route object used by `WebAppRoot` |
 | `children` | Collapsible nesting |
-| `action` | Per-section/item action such as `New` |
+| `action` | Single inline per-section/item action; use sparingly and prefer `actions` menus when possible |
 | `actions` | Context menu items shown on sidebar right-click |
 | `pinnable` | Enables framework Pin/Unpin actions |
 | `pinId` | Stable pin identity when it should differ from `id` |
@@ -38,7 +38,7 @@ Sidebar nodes support:
 
 Search is intentionally app-defined: `getNodes({ search })` receives raw search text and returns the tree that should be rendered.
 
-Use `actions` when an entity needs a context menu in the sidebar. The same `ActionMenuItem[]` should also be returned from `header.getActions` for that entity route so right-click actions and the title-bar three-line menu stay consistent:
+Use `actions` when an entity needs commands in the sidebar. The same `ActionMenuItem[]` should also be returned from `header.getActions` for that entity route so right-click actions and the title-bar three-line menu stay consistent:
 
 ```tsx
 const actions = projectActions(project);

package/docs/ui-guidelines.md

@@ -19,7 +19,7 @@ Use these first:
 | `Toolbar` | Page title/actions inside main content |
 | `Panel` | Cards/sections; use `actions` for a top-right menu/action area |
 | `ActionMenu` | Three-line action menu for secondary surfaces; entity-level menus should usually be exposed through `WebAppRoot.header.getActions` so they render in the fixed title bar |
-| `Button` / `IconButton` | Actions |
+| `Button` / `IconButton` | Form submission and true inline controls; prefer action menus for entity/app commands |
 | `Badge` | Status/count labels |
 | `EntityHeader` | Main-content entity title/description/actions |
 | `DataList` / `DataListRow` | Lists with title, description, metadata, badge and actions |
@@ -43,13 +43,19 @@ Generated screenshots live in `artifacts/screenshots`:
 | `notes-desktop-light.png` | Realistic app, desktop shell |
 | `notes-settings-desktop-light.png` | Framework settings |
 | `notes-mobile-light.png` | Mobile shell |
+| `notes-mobile-sidebar-light.png` | Mobile drawer/sidebar |
 | `notes-desktop-dark.png` | Dark mode |
 | `kitchen-desktop-light.png` | Kitchen sink desktop |
 | `kitchen-mobile-light.png` | Kitchen sink mobile |
 | `kitchen-sidebar-collapsed-light.png` | Collapsed sidebar title bar |
 | `kitchen-context-menu-light.png` | Sidebar context menu |
 | `kitchen-dialog-dark.png` | Confirm dialog overlay |
+| `kitchen-device-light.png` | Device auth approval flow |
 
 Use `bun run screenshots` to regenerate these captures with Playwright. Browser automation and screenshot capture must stay Playwright-based and cross-platform; do not hard-code local Chrome or OS-specific browser paths.
 
-Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles.
+Use these captures as the manual visual baseline before changing shell, sidebar, settings or dialog styles. When screenshots are captured to validate a visual change, review them against the specific goal; capturing files without checking the result is not validation.
+
+All destructive delete actions must use the framework `ConfirmDialog` before calling the delete endpoint. Server lifecycle actions such as kill/reboot must also require confirmation and show the standard 15-second shutdown countdown progress bar after the request succeeds.
+
+Prefer the framework action-menu pattern for app commands. Actions such as New task, New note, New project, archive, delete, or state transitions should live in `SidebarNode.actions` and/or `WebAppRoot.header.getActions` so they appear behind the three-line title-bar/item action menus. Use discrete buttons mainly for form submission or inline controls that cannot reasonably live in an action menu.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pablozaiden/webapp",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Opinionated Bun + React webapp framework for single-server apps",
   "license": "MIT",
   "type": "module",
@@ -26,6 +26,7 @@
     "./web": "./src/web/index.ts",
     "./web/styles.css": "./src/web/styles.css",
     "./contracts": "./src/contracts/index.ts",
+    "./cli": "./src/cli/index.ts",
     "./build": "./src/build/index.ts"
   },
   "scripts": {