@notis_ai/cli 0.2.15 → 0.2.17

package/dist/base-skills/notis-apps/SKILL.md

@@ -23,10 +23,33 @@ All Notis apps are built using the Notis CLI, either locally in a repo workspace
 ## App Workspace Tool Rules
 
 - Apps are the top-level packaging unit in Notis.
-- Use `apps dev [folder]` to register a new local app for development. After the
-  user tests it and explicitly asks to deploy, `apps deploy` promotes that DEV
-  app in place. Use `LOCAL_NOTIS_CREATE_APP` only for non-CLI administrative
-  flows that explicitly require a server-side app row.
+- Choose the execution path before changing an app. A prompt that says the
+  shell is a hosted/Vercel sandbox, or a shell rooted at `/vercel/sandbox`, is
+  the **hosted sandbox** path. A shell on the user's computer with Notis
+  Desktop available is the **local Desktop** path.
+- In a hosted sandbox, do not run `apps dev`: the user's Desktop cannot mount
+  that sandbox filesystem. Unless the user explicitly requests preview-only,
+  read-only, or no deployment, a request to create or edit an app authorizes
+  deploying that app to the user's Workspace after `apps build` and automated
+  `apps verify` pass. An opt-out stops after those tests with no remote app
+  create/link, database mutation, deploy, or post-deploy checks. Pulling an existing app provides its exact link. For a new
+  app, test first, then reconcile profile state and `apps list --json` against
+  the canonical `notis.config.ts` `name` and intended personal/team scope: link
+  one exact editable non-development match after a metadata-only
+  (`include_documents: false`) detail read proves scope, fail on ambiguity or
+  scope mismatch, or create only when none exists. New CLI-created apps default
+  to personal scope. Before creation, prove that canonicalizing the config
+  `title` yields the config `name`. For personal scope, run `apps create
+  "<canonical-config-title>" . --json` exactly once. For explicitly requested
+  team scope, discover and inspect `LOCAL_NOTIS_CREATE_APP`, dry-run it, execute
+  it exactly once with team visibility and the verified current team scope,
+  verify the returned id/slug/team scope/edit permission, then `apps link` that
+  exact id. Stop for read-only
+  reconciliation if creation is ambiguous or outcome-unknown. In the local
+  Desktop path, use `apps dev [folder]`, let the user test the DEV app, and deploy
+  that development identity directly only after an explicit request. Use
+  `LOCAL_NOTIS_CREATE_APP` only for a hosted team-scoped creation or another
+  non-CLI administrative flow that explicitly requires a server-side app row.
 - Use `LOCAL_NOTIS_UPDATE_APP` to update app metadata.
 - Use `LOCAL_NOTIS_LIST_APPS` to discover the user's apps.
 - The full app lifecycle uses the CLI in the shell. Always run it through the registry-resolved package, for example `npx --package @notis_ai/cli@latest -- notis apps init`; use the same prefix for `build` and `deploy`. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`.
@@ -97,16 +120,17 @@ App code never accesses the runtime directly -- it uses SDK hooks (`useTool`, `u
 12. **Portal-owned sidebars stay portal-owned** -- If a route uses `collection.sidebar`, treat that sidebar as platform chrome. Do not remove it, recreate it inside app JSX, or replace it with a custom in-app folder rail.
 13. **Portal globals are off-limits** -- Never use `window.__NOTIS_RUNTIME__`, query portal-owned DOM hooks, or create global DOM portals.
 14. **Prefer inline optimistic edits** -- Rename-like edits for collections, app-owned rows, and sidebar-backed entities should use inline editing with an optimistic UI update, then roll back on backend failure. Use modals only when the edit requires multiple fields or destructive confirmation.
-15. **Local development first; deploy is user-gated** -- Run `apps dev [folder]` once to register the root, then let the **user** test the automatically mounted app in its Workspace entry (compact `DEV` badge). The registration and host survive the command; no terminal must remain open. Do NOT run `apps create` or `apps deploy` on your own initiative, even after a clean build and verify. Building through local testing without deploying is the expected, complete outcome.
-16. **Installed app identity is exact and profile-scoped** -- Identity precedence is: explicit persisted link for this API/user profile; one accessible non-development app with the exact canonical slug; isolated development runtime. Persist one unique exact-slug match, fail closed on ambiguity, and never infer from display name. After first install, keep the profile-scoped link so Portal and CLI update the same app instead of creating duplicates.
+15. **The execution environment determines the deploy gate** -- In the local Desktop path, run `apps dev [folder]`, let the **user** test the automatically mounted DEV app, and do not deploy until the user asks; first deploy promotes that `dev_app_id` directly, so never create a second app first. In a hosted sandbox, `apps dev` cannot reach the user's Desktop; bootstrap `agent-browser`, build and verify first, then resolve exact identity/resources and deploy to the user's Workspace, verify the remote version and live runtime, and return the exact Portal URL. Automatic deployment is the default for create/edit requests only; an explicit preview-only, read-only, or no-deploy request wins. This standing sandbox authorization does not authorize Store submission.
+16. **Installed app identity is exact, editable, and scope-proven** -- Validate an explicit persisted link for this API/user profile before using it. Otherwise inspect every accessible exact-canonical-slug row, including development rows; link only one editable non-development candidate whose exact detail proves the intended personal/team scope. Fail closed on a development collision, multiple matches, missing scope proof, or scope mismatch, and never infer identity from display name. After first install, keep the validated profile-scoped link so Portal and CLI update the same app instead of creating duplicates.
 17. **Development identities stay separate** -- `.notis/state.json` uses `dev_app_id` for the hidden development-runtime row and `app_id` only for an accessible installed workspace app, scoped under the authenticated environment. Never pass a runtime app whose manifest has `is_dev: true` to `notis apps link`.
 18. **Automatic mounts are multi-instance and least-authority** -- Prod, Beta, and source-development Desktop instances may mount the same source simultaneously with independent authenticated runtimes. Automatic mounting never grants capabilities: reuse existing grants and leave restricted capabilities denied until approved. Consumer leases expire after crashes so the shared host exits after the last live instance. There are no offline rows or manual start/stop controls.
 19. **Store submission is user-gated** -- Run `apps publish --confirm-ready` only after the user explicitly confirms the current App Details page and Store listing are ready. Deploy the exact approved local state first. The command must reject missing confirmation, incomplete listing media, a local/deployed version mismatch, private visibility, or an existing pending review.
-20. **Bump `notisAppVersion` for every Store update** -- `package.json` must contain a semver `notisAppVersion`. For an existing Store app, increment it beyond the currently published registry version before deploy and submission; registry CI rejects equal or lower versions.
+20. **Bump `notisAppVersion` before linked development and every Store update** -- `package.json` must contain a semver `notisAppVersion`. A linked local source substitutes its installed Workspace app only when the local version is strictly greater than the installed manifest's `release_version`; equal, lower, missing, or invalid versions keep serving the online bundle. `apps pull` retrieves the online version, so increment `notisAppVersion` before `apps dev` when continuing development. For an existing Store app, also increment it beyond the currently published registry version before deploy and submission; registry CI rejects equal or lower versions.
 21. **`CHANGELOG.md` owns release history** -- Keep the complete release history in one root `CHANGELOG.md`, newest entry first. Do not add new `versionNotes` values to `notis.config.ts`. Use `## [Release title] - YYYY-MM-DD`, or `{PR_MERGE_DATE}` for an unpublished entry. App Details reads **What’s New** and **Version History** from the deployed package manifest, while the Store reads them from the latest published snapshot; unpublished workspace edits must never change the Store page. The manifest also exposes `package.json` `notisAppVersion` as the package version shown in App Details.
 22. **Database rows are private unless explicitly seeded** -- A string declaration such as `databases: ['notes']` publishes schema only and never includes the developer's rows. Use `{ slug: 'templates', seedDocuments: true }` only for small, intentional starter content that every installer should receive. Never enable it for user-created notes, history, leads, or other personal data.
 23. **Public submissions are complete, reviewable packages** -- The registry PR must contain the full editable source tree, Store assets, exact source-declared database schemas, and only explicitly seeded starter rows. Registry CI validates those boundaries before merge; do not hand-edit `notis-listing.json` or strip source files to make a check pass. Fix the app locally, redeploy, and resubmit.
-24. **New projects land in `~/.notis/apps/<slug>`, and `[dir]` overrides it** -- `apps init` and `apps pull` default to that root, the same well-known home the desktop uses for synced skills (`~/.notis/skills`), so a project nobody deliberately placed is always findable and never depends on where the shell happened to be sitting. Pass `[dir]` whenever the app belongs somewhere specific -- a git repo the user tracks, an existing monorepo's `apps/<name>/`, or a path the user named -- and tell the user which location you used. Never place a project inside the Notis source repo or a Conductor worktree: every later CLI call from that directory resolves the worktree's local dev runtime (`.context/notis-runtime.json`) instead of the user's real profile.
+24. **New projects default to `~/.notis/apps/<slug>`, and `[dir]` overrides it** -- `apps init` and `apps pull` use this stable, predictable home unless the app belongs in a specific repository, monorepo, or user-chosen location. In those cases, pass `[dir]` and report the resulting path. Do not nest an app inside a directory whose local workspace metadata selects an unrelated Notis runtime or profile: later CLI calls inherit that routing and may target the wrong environment.
+25. **Machine names and display titles use different casing** -- In `notis.config.ts`, `name` is the stable machine identity and must be lowercase kebab-case (`name: 'link-building'`). `title` is the human-facing app name and must use deliberate display casing (`title: 'Link Building'`), preserving product spelling and acronyms such as `Notis` and `SEO`. Never put a title-cased phrase in `name`, never show a raw slug as the title, and never change an existing canonical `name` or remote slug merely to repair display casing. The persisted `apps.name`, Workspace sidebar, App Details, and Store listing must use `title`.
 
 ## Anti-patterns -- NEVER do these
 
@@ -115,7 +139,7 @@ These are the most common mistakes agents make. Each one wastes time and produce
 - **NEVER assume app deploys create databases for you** -- Create or update databases through native Notis database tools or the assistant first, then reference them by slug in `notis.config.ts`. Database creation requires the owning app to exist: pass its slug or id in the `app` argument of `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` (create the app first with `LOCAL_NOTIS_CREATE_APP` if needed). A database can only be referenced by the app that owns it.
 - **NEVER bypass the supported workflow by manually stitching together low-level save or lint calls from a local workspace** -- Local agents should go through the NPX Notis CLI for `apps pull`, `apps dev`, `apps build`, `apps verify`, `apps create`, `apps link`, and `apps deploy`.
 - **NEVER use `apps pull` to clone a Store listing** -- `npx --package @notis_ai/cli@latest -- notis apps pull` only pulls source for an app the user can already access as an installed app. To fork a published Store app, run `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from <slug>` instead: it downloads that app's source from the public registry, and installing the app first is not required.
-- **NEVER deploy on your own initiative** -- A clean `apps build` + `apps verify` is NOT a signal to deploy. `apps create` / `apps deploy` install the app onto the user's account; run them only after the user has tested the local (`apps dev`) build and explicitly asked you to deploy. When you finish building, hand off for local testing and stop — do not create or deploy unprompted.
+- **NEVER apply the local deploy gate to a hosted sandbox** -- On the user's local computer, a clean `apps build` + `apps verify` is not deploy consent: hand off the DEV app and wait. In a hosted sandbox, the user's create or edit request is deploy consent for that app because `apps dev` cannot reach their Desktop; deploy only after both commands pass, then verify the remote version. Neither path authorizes Store submission.
 - **NEVER submit without explicit approval** -- A deploy request alone does not authorize Store submission. Run `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready` only when the user confirms App Details is ready for Store review.
 - **NEVER write raw `views/<slug>/index.js` files** -- Write standard React pages in `app/`.
 - **NEVER invent `npx --package @notis_ai/cli@latest -- notis apps push` or bypass the review flow** -- Source moves through `apps pull` and `apps deploy`; `apps publish --confirm-ready` submits the deployed snapshot through the same authenticated review endpoint as App Details.
@@ -130,23 +154,25 @@ These are the most common mistakes agents make. Each one wastes time and produce
 **Default to the Store scaffold catalog, not a blank project.** Every published Store app is a scaffold: `notis apps scaffolds list` reads the catalog from the public registry, and `notis apps init --from <slug>` downloads that app's source. Most user requests overlap with a published app, and starting from one is faster than a bare app.
 
 1. **Find a starting point.** Run `npx --package @notis_ai/cli@latest -- notis apps scaffolds list` (add `--search <term>` to filter) to list the published Store apps. If something close matches, run `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from <slug>` to download that app's source from the registry. Only run plain `notis apps init "My App"` when no published app fits. Either way the project lands in `~/.notis/apps/<slug>`; add a `[dir]` argument when the user wants it somewhere else (a tracked git repo, an existing monorepo), and report the path you used.
-2. **Pull your own apps; fork Store apps with `--from`.** `apps pull` is for apps the user already has installed or deployed: run `npx --package @notis_ai/cli@latest -- notis apps list`, then `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>` (lands in `~/.notis/apps/<app-slug>`; pass a `[dir]` argument to place it elsewhere). To fork a published Store app, use `apps init --from <slug>` instead -- it downloads the source from the registry and does not require installing the app first.
-3. **Edit the listing source.** Update `name` (slug), `title`, description, icon, accent, author, categories, tagline, databases, routes, and tools in `notis.config.ts`. Declare a database as a string for schema-only Store packaging; use `{ slug: 'templates', seedDocuments: true }` only when its rows are deliberate starter content for every installer. Keep the complete Store release history in the root `CHANGELOG.md`, newest entry first, using `## [Release title] - YYYY-MM-DD` (or `{PR_MERGE_DATE}` before publication). The first entry powers **What’s New** and the same file powers **Version History**. `icon` is a `phosphor:<name>` value or `metadata/icon.png`; when unset the app shows its **two-letter initials** everywhere (store, sidebar, app details). `accent` optionally pins the avatar color to one of `blue|violet|emerald|amber|rose|sky|fuchsia|teal` (default derived from the app id). Icon/accent flow through deploy onto the app row + listing and can also be set later via the `update_app` tool.
+2. **Pull your own apps; fork Store apps with `--from`.** `apps pull` is for apps the user already has installed or deployed: run `npx --package @notis_ai/cli@latest -- notis apps list`, preserve any local edits in the target directory, then run `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>` (lands in `~/.notis/apps/<app-slug>`; pass a `[dir]` argument to place it elsewhere). A pull reproduces the installed release, so increment `package.json` `notisAppVersion` above that release before `apps dev`; until then the online bundle remains active. To fork a published Store app, use `apps init --from <slug>` instead -- it downloads the source from the registry and does not require installing the app first.
+3. **Edit the listing source.** In `notis.config.ts`, set `name` to the stable lowercase kebab-case identity and set `title` to the correctly cased human-facing name; for example, `name: 'link-building'` with `title: 'Link Building'`. Treat acronym and brand casing as editorial input, not something to derive mechanically from the slug. Then update description, icon, accent, author, categories, tagline, databases, routes, and tools. Declare a database as a string for schema-only Store packaging; use `{ slug: 'templates', seedDocuments: true }` only when its rows are deliberate starter content for every installer. Keep the complete Store release history in the root `CHANGELOG.md`, newest entry first, using `## [Release title] - YYYY-MM-DD` (or `{PR_MERGE_DATE}` before publication). The first entry powers **What’s New** and the same file powers **Version History**. `icon` is a `phosphor:<name>` value or `metadata/icon.png`; when unset the app shows its **two-letter initials** everywhere (store, sidebar, app details). `accent` optionally pins the avatar color to one of `blue|violet|emerald|amber|rose|sky|fuchsia|teal` (default derived from the app id). Icon/accent flow through deploy onto the app row + listing and can also be set later via the `update_app` tool.
 4. **Build pages in `app/`.** Reuse scaffold code wherever it fits.
-5. **Iterate live.** Run `npx --package @notis_ai/cli@latest -- notis apps dev [folder]` once. It permanently registers the root; `~/.notis/apps` is already implicit. Running Desktop instances discover the root itself, direct app children, and `apps/*`, then mount each successful build automatically in Workspace. Source edits hot-reload only that app in every instance. Add `--scratch` for isolated empty resources when the work needs fixtures or destructive experiments.
-6. **Capture listing screenshots.** Declare 3–6 screenshots in `notis.config.ts`, each with a stable `path`, descriptive `alt`, and optional `route`/`scenario`/`focus`/`theme`, then run `npx --package @notis_ai/cli@latest -- notis apps screenshot`. Use `focus` to frame a real app root without empty browser canvas; use `theme: 'light'` or `theme: 'dark'` to match both the Portal render and Store backdrop, and pair both modes when that best represents the app. It renders the configured states in a headless harness and writes exact 2000x1250 PNGs under `metadata/`, using the deterministic Store presentation by default (`--raw` is diagnostic only). Apps are icon-led like Raycast — the icon set in `notis.config.ts` represents the app, so there is no cover image, only these screenshots. Never hand-author the PNGs; regenerate them when routes or UI change. A `scenario` names an entry in `metadata/screenshot-fixtures.json`; besides `actions` it may carry its own `tools` and `requests`, shallow-merged per key over the file-level ones for that capture, which is how the same route is shown both populated and in its first-run empty state.
-7. **Verify locally.** Run `npm install`, then `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps verify`. Surface the verify report and fix failures. Incomplete listing media is only a `Store readiness:` warning there; run `notis apps verify --listing` before publish to make it a failure.
-8. **Local-development-first handoff — STOP HERE.** Hand off after the user can see and test the app in its DEV-badged Workspace row. Building a new app to this point, without deploying, is a **complete and expected** result. Do NOT proceed to `apps create` / `apps deploy` yet. **Before handing off, complete all three acceptance checks:**
+5. **Test the source before remote mutation.** Before changing a linked installed app, increment `package.json` `notisAppVersion` above the installed release. In a fresh hosted sandbox, bootstrap Agent Browser with `npm exec --yes --package agent-browser@latest -- agent-browser install`. Generate configured screenshots; use `theme: 'dark'` or `theme: 'light'` where appropriate and reserve screenshot `--raw` for diagnostics. Run `npm install`, run `npx --package @notis_ai/cli@latest -- notis apps build`, then run `npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify` in the sandbox (or the normal NPX verification command locally). Fix every failure. Do not create an app, mutate a database, or deploy before both checks pass. `--no-browser` is manual triage, not a passing automated gate.
+6. **Finish the local Desktop path at the DEV handoff.** Run `npx --package @notis_ai/cli@latest -- notis apps dev [folder]`; it creates the development identity and materializes available scaffold database snapshots without requiring a hosted app id. Hand off after the user can see and test the app in its DEV-badged Workspace row. Do not deploy until the user asks, and then run `apps deploy` directly so the existing `dev_app_id` is promoted in place; never run `apps create` after `apps dev`. **Before handing off, complete all three acceptance checks:**
    1. Root: `apps roots list` contains the intended folder (or the app is under the implicit default root).
    2. Bundle: the loopback `/snapshot` responds successfully and contains the expected manifest/routes.
    3. Mount and render: the app appears exactly once with a compact `DEV` badge and its default route renders. For multi-instance work, verify each requested Desktop independently.
    See Troubleshooting → *App is missing from the sidebar* if any check fails.
-9. **Deploy only when the user asks.** Once the user has tested locally and explicitly requests a deploy, run `npx --package @notis_ai/cli@latest -- notis apps deploy`. A first deploy promotes the development app in place; do not create a second app or use `--direct`. For an existing remote app, link first with `npx --package @notis_ai/cli@latest -- notis apps link <id> .` and then deploy. After first install, `.notis/state.json` must point at that same promoted app id so future local-dev actions become **Update**, not another **Install**.
+7. **Gate and resolve one hosted identity after tests pass.** If the request is preview-only, read-only, or no-deploy, stop after step 5: do not create or link an app, mutate a database, deploy, or run post-deploy checks. Otherwise, existing edits keep the exact profile-scoped id linked by `apps pull`, after a metadata-only (`include_documents: false`) app-detail read validates its edit permission and scope without materializing databases. For a new hosted app, default the intended scope to personal unless the user explicitly requests team scope, inspect `.notis/state.json`, and run `apps list --json`. Consider every accessible exact canonical-slug row, including development rows. Link only one editable, non-development candidate whose metadata-only exact app-detail read proves the intended scope; fail on multiple matches, development-row collisions, missing scope proof, or scope mismatch. Create only when there are zero exact-slug rows. First prove that lowercasing the config `title`, replacing non-alphanumeric runs with `-`, and trimming hyphens yields the config `name`. For personal scope, run `npx --package @notis_ai/cli@latest -- notis apps create "<canonical-config-title>" . --json` exactly once and verify the returned id, remote slug, edit permission, and personal scope. For explicitly requested team scope, use `notis tools search` to discover the team-capable app-creation tool, inspect its schema, dry-run it, then execute `LOCAL_NOTIS_CREATE_APP` exactly once with the canonical display title, `visibility: "team"`, and the exact current `team_id` when resolved. Verify the result's id, canonical slug, `team_id`, team visibility, and edit permission, then run `notis apps link <returned-id> .` before database reconciliation. Never retry an outcome-unknown create; reconcile read-only and stop on ambiguity or any returned identity/scope mismatch.
+8. **Reconcile hosted database schemas safely.** Read the exact app detail and current schemas first; mutate only missing or changed declarations. For creation, pass the exact app id in the database tool's `app` argument. For an update, resolve the exact `database_id`, verify its `owner_app_id` equals the linked app id, update by that `database_id`, then read back slug, owner, and schema. Apply only backward-compatible schema expansion before deployment. Stage breaking or destructive changes through an expand-contract sequence and obtain the required destructive approval; never make the currently deployed bundle incompatible before its replacement is live.
+9. **Deploy and prove the hosted sandbox result.** Use only the exact id established in step 7. Run `npx --package @notis_ai/cli@latest -- notis apps deploy`, read the matching row back with `npx --package @notis_ai/cli@latest -- notis apps list --json`, confirm its id and deployed version, then run `npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify --mode live`. Return that row's exact profile-appropriate `portal_url` only after every proof passes. Report state precisely: a definite pre-commit rejection is **tested but not deployed**; a timeout/network/incomplete mutation response is **tested, deployment outcome unknown**; a confirmed deploy followed by failed readback is **deployed but not remotely verified**; a failed live check is **deployed but live verification failed**. Never retry an outcome-unknown mutation.
 10. **Submit only after confirmation.** When the user explicitly confirms the current App Details page is ready, ensure the approved state is deployed, then run `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready`. The command submits Team apps immediately or opens the Public Store registry review PR. Without that confirmation, stop after deploy.
 
 ### Quick start
 
-Steps 1–3 are the agent's job on a build request. Step 4 is **user-gated** — do not run it until the user has tested the local build and asked you to deploy.
+Choose the local or hosted finish after verification. Local deployment is
+user-gated; hosted-sandbox deployment is the default for app create or edit
+tasks unless the user explicitly requests preview-only, read-only, or no deploy.
 
 ```bash
 # 1. Pick a published Store app as the scaffold (catalog comes from the public registry)
@@ -157,22 +183,39 @@ npx --package @notis_ai/cli@latest -- notis apps init "My App" --from <slug>
 cd ~/.notis/apps/my-app
 npm install
 
-# 2. Develop against the Electron Portal, then HAND OFF for the user to test.
-#    Keep this running — it is what substitutes the local build into the app's
-#    sidebar group. This is the finish line for a build request.
+# 2. LOCAL COMPUTER: register with Desktop and iterate. After the user approves
+#    deployment, run deploy directly to promote the existing dev_app_id.
 npx --package @notis_ai/cli@latest -- notis apps dev
-# ... iterate until the app looks right in its Workspace entry (DEV badge) ...
-
-# 3. Build, capture listing screenshots, and verify (still local — no deploy)
+# ... user tests the DEV-badged app ...
 npx --package @notis_ai/cli@latest -- notis apps build
 npx --package @notis_ai/cli@latest -- notis apps screenshot
 npx --package @notis_ai/cli@latest -- notis apps verify
+npx --package @notis_ai/cli@latest -- notis apps deploy
+```
+
+Hosted sandbox finish — never run `apps dev`. Test first, then reconcile the
+exact app identity and changed databases before deployment:
 
-# 4. ONLY after the user tested locally and asked to deploy. First deploy
-#    promotes the dev app in place and writes the installed link.
+```bash
+npm exec --yes --package agent-browser@latest -- agent-browser install
+npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps screenshot
+npx --package @notis_ai/cli@latest -- notis apps build
+npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify
+# New unlinked app only: reconcile exact canonical slug with apps list. If no
+# match exists, create once with the config title and verify the returned slug.
+npx --package @notis_ai/cli@latest -- notis apps list --json
+# Before create, prove canonicalize(config.title) == config.name.
+npx --package @notis_ai/cli@latest -- notis apps create "<canonical-config-title>" . --json
+# Compare schemas, then create only missing databases or update changed ones by
+# verified database_id and read back owner/schema before continuing.
 npx --package @notis_ai/cli@latest -- notis apps deploy
+npx --package @notis_ai/cli@latest -- notis apps list --json
+npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify --mode live
+```
 
-# 5. ONLY after the user explicitly confirms App Details is ready for Store review
+Store submission on either path remains a separate approval-gated action:
+
+```bash
 npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready
 ```
 
@@ -184,13 +227,14 @@ npx --package @notis_ai/cli@latest -- notis apps link <app-id> .
 npx --package @notis_ai/cli@latest -- notis apps deploy
 ```
 
-Or if editing an installed app:
+Or if editing an installed app locally:
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis apps list
 npx --package @notis_ai/cli@latest -- notis apps pull <installed-app-id>
 cd ~/.notis/apps/my-app
 npm install
+# Increment package.json notisAppVersion above the pulled online release.
 npx --package @notis_ai/cli@latest -- notis apps dev
 npx --package @notis_ai/cli@latest -- notis apps build
 npx --package @notis_ai/cli@latest -- notis apps verify
@@ -199,12 +243,20 @@ npx --package @notis_ai/cli@latest -- notis apps link <installed-app-id> .
 npx --package @notis_ai/cli@latest -- notis apps deploy
 ```
 
+In a hosted sandbox, use the same pull/build/verify sequence but omit `apps
+dev`; bootstrap `agent-browser`, materialize any new or changed database schemas
+against the exact linked id, deploy automatically after verification, read back
+the exact app id/version and `portal_url` with `apps list --json`, run live verification, and return that
+exact Portal URL. Never run `apps publish --confirm-ready` without separate
+Store approval.
+
 ## Building an App
 
 ### Step 1: Define the config
 
 Create `notis.config.ts` with:
-- **name** -- Display name
+- **name** -- Stable machine identity in lowercase kebab-case, such as `link-building`; do not use display casing here
+- **title** -- Human-facing app name with deliberate casing, such as `Link Building`; preserve brands and acronyms exactly
 - **databases** -- Slug references to existing Notis databases
 - **routes** -- Route-first sidebar entries with explicit `slug`, optional `parentSlug`, and optional `collection.sidebar` tree config
 - **tools** -- Final tool names the app can call at runtime. Use the shared discovery flow (`COMPOSIO_SEARCH_TOOLS`, then `COMPOSIO_GET_TOOL_SCHEMAS`) while building the app, and copy the returned final names into this list. Examples include `LOCAL_NOTIS_DATABASE_QUERY`, `LOCAL_NOTIS_MONID_RUN`, `GMAIL_SEND_EMAIL`, `LOCAL_POSTFORME_CREATE_POST`, and `LOCAL_MCP_<SERVER>_<TOOL>`. App code calls each declared name directly through `useTool`; it does not wrap provider or MCP calls in `COMPOSIO_MULTI_EXECUTE_TOOL`. Access stays scoped to the signed-in user's own connections, native database tools stay scoped to the app's databases unless `capabilities.workspaceDatabases: 'read'` is granted, and metered tools use the CLI-equivalent credit-cap and fail-closed usage-billing path.
@@ -234,6 +286,8 @@ routes: [
 
 Use the same page template for the root Notes route and collection/sub-collection detail states. The portal sidebar injects live collection items under the static route row when `collection.sidebar.mode === 'tree'`.
 
+For arbitrary app-owned resources that are not Notis collection rows, set `resourceDeepLinks: true` on the route. Read the decoded `?resource=` identifier from `useNotis().resourceId`, and link between routes with `toRoute('/inbox', { resourceId })`. Keep collection links on `?item=`. Publish external preview/source links as the resource `url`; the host separately supplies the exact Notis review link as `active_resource.view_url` for opted-in routes. Handle missing or deleted identifiers with a safe view-level fallback.
+
 ### Step 2: Build pages
 
 Standard React pages in `app/`. Use generic SDK tool hooks for data and build on top of the scaffolded shadcn components and portal shell classes (`notis-app-shell`, `notis-app-surface`):
@@ -341,7 +395,7 @@ Generated by `npx --package @notis_ai/cli@latest -- notis apps build` at `.notis
 {
   "version": 1,
   "spec_version": 4,
-  "app": { "name": "My App", "description": "...", "icon": "phosphor:..." },
+  "app": { "name": "My App", "slug": "my-app", "title": "My App", "description": "...", "icon": "phosphor:..." },
   "routes": [
     {
       "path": "/",
@@ -444,10 +498,10 @@ already installs `ShortcutProvider`; app code should not add a second provider.
 
 | API | Signature | Description |
 |-----|-----------|-------------|
-| `useNotis()` | `() => { app, route, context, ready }` | App metadata, current route, generic portal context, ready state |
+| `useNotis()` | `() => { app, route, databases, collectionItem, resourceId, ready }` | App metadata, current route, selected collection item, decoded exact-resource id, ready state |
 | `useTool<TArgs, TResult>(name)` | `(name: string) => { call, loading, error }` | Call a declared tool with app-defined argument/result types. Identical idempotent reads may use `call(args, { dedupe: true })`; never dedupe writes |
 | `useTools()` | `() => { tools, loading }` | List available tools |
-| `useNotisNavigation()` | `() => { toRoute, toDocument, toApp }` | Navigate between routes, documents, or the app root |
+| `useNotisNavigation()` | `() => { toRoute, toDocument, toApp }` | Navigate between routes (including `toRoute(path, { resourceId })`), documents, or the app root |
 | `useTopBarSearch(opts)` | `({ value, onChange, placeholder?, onSubmit? }) => { setLoading }` | Bind the current view to the Portal-owned top-bar search input |
 | `useBackend()` | `() => { request }` | Raw backend request proxy with JWT auth |
 | `useDatabaseSubscription(slug, opts?)` | `(slug: string, opts?) => { rows, documents, loading, error, refetch, live }` | Query a database and refetch it when its rows change. `live` is false on hosts without a change feed (dev harness, vite preview) -- keep a manual refresh for those |
@@ -503,24 +557,34 @@ const result = await queryTasks.call({ database_id: 'tasks-db-id', query: { page
 
 ## Development Modes
 
+### Hosted sandbox development
+
+Do not run `apps dev` in a hosted sandbox. The sandbox filesystem is not on the
+user's computer, so Desktop cannot mount it. Bootstrap sandbox `agent-browser`,
+then build and verify before any remote mutation. For a create or edit request,
+unless the user explicitly says preview-only, read-only, or no-deploy, resolve
+one exact identity, safely materialize only missing or changed database schemas,
+deploy, read back the exact app id/version, run live verification, and return
+the exact Portal URL. Inspection, review, and diagnosis remain read-only.
+
 ### Canonical local development
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis apps dev
 ```
 
-Runs the real desktop-local development workflow. The CLI should discover all apps in the target workspace, serve their bundles from loopback, and surface them in the Electron Portal's Workspace group — each substituted for its installed entry, or appended while unpublished — through the local desktop session registry.
+Runs the real desktop-local development workflow. The CLI should discover all apps in the target workspace and serve their bundles from loopback. Unpublished apps appear in the Electron Portal's Workspace group; linked apps substitute their installed entry only when the local `notisAppVersion` is strictly greater than the installed `release_version`.
 
 ## Testing
 
 1. **Build validation**: `npx --package @notis_ai/cli@latest -- notis apps build` must succeed without errors. Vite surfaces TypeScript and bundling errors during this step.
-2. **Headless render verification** (recommended after every build): run `npx --package @notis_ai/cli@latest -- notis apps verify`. It builds unless `--skip-build` is passed, spins up a loopback harness, drives `agent-browser` against every route, and reports per-route pass/fail with captured render errors and runtime calls.
-3. **Local development acceptance**: Run `notis apps dev [folder]` once to register the root, then verify each signed-in Desktop instance independently: one DEV-badged Workspace row, the default route rendering real app content, and live edits appearing without restarting the CLI or Desktop. Use `notis apps roots list` as the persistence proof. Loopback bundle health alone does not prove that an authenticated instance mounted or rendered the app.
-4. **Post-deploy**: Verify the deployed bundle via `/portal_views/get` -> `runtime_descriptor.bundle.js_url`, then verify the app renders in the portal. The portal renders app bundles directly as React components, so the fastest verification is navigating to the app page in the portal.
+2. **Headless render verification** (recommended after every build): run `npx --package @notis_ai/cli@latest -- notis apps verify` locally. In a hosted sandbox, first run `npm exec --yes --package agent-browser@latest -- agent-browser install`, then run `npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify`. It builds unless `--skip-build` is passed, spins up a loopback harness, drives `agent-browser` against every route, and reports per-route pass/fail with captured render errors and runtime calls.
+3. **Local development acceptance**: Run `notis apps dev [folder]` once to register the root, then verify each signed-in Desktop instance independently. For an unpublished app, expect one DEV-badged Workspace row. For a linked app, first confirm local `notisAppVersion` is strictly greater than installed `release_version`, then expect one substituted DEV-badged row; equal or lower must keep the online row and bundle. Verify the default route renders and live edits appear without restarting the CLI or Desktop. Use `notis apps roots list` as the persistence proof. Loopback bundle health alone does not prove that an authenticated instance mounted or rendered the app.
+4. **Post-deploy**: Read back the exact app id, version, and `portal_url` with `apps list --json`, run `apps verify --mode live`, verify the deployed bundle via `/portal_views/get` -> `runtime_descriptor.bundle.js_url`, and return that profile-appropriate exact Portal URL. A confirmed deploy followed by failed readback is deployed but not remotely verified; a failed live check is deployed but live verification failed. The portal renders app bundles directly as React components, so navigate to the app page when an authenticated browser is available.
 
 ### Headless harness verification
 
-Run `npx --package @notis_ai/cli@latest -- notis apps verify` after `npx --package @notis_ai/cli@latest -- notis apps build`. Use `--mode live` after deploy to exercise the real `/portal_views/runtime_query` with the CLI JWT instead of stub data; live mode also fails a route whose runtime calls all errored, which a well-behaved error state would otherwise hide. If `agent-browser` is unavailable, pass `--no-browser` to print URLs and use `--keep-open` for interactive triage with `notis-browser-control`.
+Run `npx --package @notis_ai/cli@latest -- notis apps verify` after `npx --package @notis_ai/cli@latest -- notis apps build`. Use `--mode live` after deploy to exercise the real `/portal_views/runtime_query` with the CLI JWT instead of stub data; live mode also fails a route whose runtime calls all errored, which a well-behaved error state would otherwise hide. In a hosted sandbox, put `agent-browser` on the verification process's `PATH` with the combined-package command above. `--no-browser` only prints URLs for manual triage and does not satisfy the automated deployment gate.
 
 #### What the harness catches that `npx --package @notis_ai/cli@latest -- notis apps build` does not
 
@@ -544,6 +608,6 @@ Run `npx --package @notis_ai/cli@latest -- notis apps verify` after `npx --packa
   authenticated API available. Do not bypass DEV-app promotion or installed-app
   identity with a direct database/storage write.
 - **App shows old code after deploy**: Bundle cache is stale. Hard refresh (Cmd+Shift+R) or clear site data in DevTools.
-- **App is missing from the sidebar**: Run `apps roots list`, confirm the app is at the root, one direct child, or `apps/*`, and confirm its first build succeeds. Restarting Desktop reattaches the same persistent roots; no terminal process or manual sidebar action is required.
+- **App is missing from the sidebar**: Run `apps roots list`, confirm the app is at the root, one direct child, or `apps/*`, and confirm its first build succeeds. For a linked app, compare `package.json` `notisAppVersion` with the installed manifest's `release_version`: equal, lower, missing, or invalid intentionally keeps the online app without a DEV badge. If source is stale, preserve any local edits, run `apps pull <app-id> <dir> --force` to refresh it, then increment `notisAppVersion` before continuing development. Restarting Desktop reattaches the same persistent roots; no terminal process or manual sidebar action is required.
 - **`LOCAL_NOTIS_DATABASE_QUERY` returns empty documents**: Check that the database ID passed to the tool matches the intended database. Use `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_LIST_DATABASES --arguments '{}'` to verify the ID; use the database slug only as a fallback.
 - **Properties are `undefined`**: Keep app-local result types for `useTool<TArgs, TResult>` and guard optional nested properties when reading live data.

package/dist/base-skills/notis-cli/SKILL.md

@@ -73,43 +73,99 @@ Treat the Notis CLI the same way you would treat a Composio-style tool router fl
 
 ## Section 1: Developing Notis Apps
 
-Use this section when the goal is to create or update a Notis app from a local workspace.
+Use this section when the goal is to create or update a Notis app from a local
+workspace or a hosted sandbox.
 
-Notis apps are Vite + React projects using `@notis/sdk`. The workflow is init or pull, dev, build, verify, create/link, deploy, then an explicitly confirmed Store submission when requested.
+Notis apps are Vite + React projects using `@notis/sdk`. After init or pull and editing, choose one terminal branch: local Desktop uses `dev → build → verify → user approval → deploy`; hosted sandbox uses `build → verify → identity/schema reconciliation → deploy`; Store submission is a later, separately confirmed action.
 
 Important: `deploy` only updates the installed app artifact for the current user or team. Store submission is a separate, user-gated step. After the user explicitly confirms that the current App Details page and Store listing are ready, `apps publish --confirm-ready` submits the matching deployed version through the backend review flow.
 
+Choose the execution path before changing the app:
+
+- **Hosted sandbox**: a sandbox instruction or `/vercel/sandbox` working tree
+  proves that Desktop cannot mount the source. Do not run `apps dev`. A create
+  or edit request authorizes `apps deploy` after `apps build` and automated
+  `apps verify` pass unless the user explicitly requests preview-only,
+  read-only, or no deployment; inspection, review, and diagnosis stay
+  read-only. `apps pull <app-id>` links an existing app. Test before any remote
+  mutation. If an opt-out applies, stop there without create/link, database
+  mutation, deploy, or post-deploy checks. Otherwise, for a new unlinked app,
+  compare profile state and `apps list --json` with the canonical
+  `notis.config.ts` `name` and intended personal/team scope: link one exact
+  editable non-development match after a metadata-only (`include_documents:
+  false`) detail read proves scope, fail on any ambiguity/development
+  collision/scope mismatch, or create only on zero exact matches. Default new
+  apps to personal scope unless the user explicitly asks for team scope. Prove
+  canonicalizing the config title yields its name. For personal creation, run
+  `apps create "<canonical-config-title>" . --json` exactly once. For explicit
+  team scope, discover/describe and dry-run `LOCAL_NOTIS_CREATE_APP`, execute it
+  exactly once with team visibility and verified current team scope, verify the
+  returned identity/scope, and link that exact id. In a fresh sandbox, install Agent Browser with `npm exec --yes --package
+  agent-browser@latest -- agent-browser install` and run verification through
+  `npx --yes --package @notis_ai/cli@latest --package agent-browser@latest --
+  notis apps verify`. Read back the exact app id/version and Portal URL with `apps list --json`, run
+  the same combined command with `apps verify --mode live`, and return the exact
+  Portal URL. Stop before deployment on test failure and before retry on an
+  outcome-unknown create or deploy.
+- **Local computer**: run `apps dev`, let the user test the DEV-badged app, and
+  deploy that development identity directly only after the user explicitly
+  asks; never run `apps create` after `apps dev`.
+
 ### App development workflow
 
 1. Scaffold a new app (every published Store app is a scaffold; `notis apps scaffolds list [--search <term>]` lists them from the public registry, and `--from <slug>` downloads that app's source):
    - `npx --package @notis_ai/cli@latest -- notis apps init ["My App"] [--from <slug>]`
-2. Or pull an existing app's source to edit it locally (the project is linked automatically):
+2. Or pull an existing app's source to edit it (the project is linked automatically):
    - `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>`
-   - then run `npm install`, `npx --package @notis_ai/cli@latest -- notis apps dev`, edit, build, and deploy
-3. Develop locally with live reload:
-   - `npx --package @notis_ai/cli@latest -- notis apps dev`
-4. Build the production artifact:
-   - `npx --package @notis_ai/cli@latest -- notis apps build`
-5. Verify the built artifact headlessly:
-   - `npx --package @notis_ai/cli@latest -- notis apps verify`
-6. For a brand-new app already run with `apps dev`, deploy to promote that development app in place:
-   - `npx --package @notis_ai/cli@latest -- notis apps deploy`
-7. Or link the project to an existing remote app (skip if you used `pull`):
-   - `npx --package @notis_ai/cli@latest -- notis apps link`
-8. Deploy the artifact to Notis:
-   - `npx --package @notis_ai/cli@latest -- notis apps deploy`
-9. Check project health:
+   - then run `npm install`, increment `notisAppVersion`, and edit
+3. **Local Desktop branch:** run `apps dev` for live testing, confirm the DEV
+   app and root/mount acceptance checks, then run `apps build` and `apps verify`.
+   Let the user test the DEV app and stop for explicit user approval. When
+   approved, run exactly one `apps deploy` to promote the existing `dev_app_id`
+   (or update the already linked app), then read it back. Never run `apps create`
+   after `apps dev`.
+4. **Hosted sandbox branch:** bootstrap Agent Browser as described above, then
+   run `apps build` followed by the automated hosted `apps verify`. If automatic
+   deployment is opted out, stop after those tests with no app create/link,
+   database mutation, deploy, or post-deploy check. Otherwise, for a new hosted
+   app, reconcile `.notis/state.json` and `apps list --json` against
+   the canonical config `name` and intended scope (personal by default; team
+   only when explicitly requested). Include
+   development rows as collision checks. Link one exact editable non-dev match
+   only after a metadata-only (`include_documents: false`) exact app detail
+   proves scope; fail on multiple/scope mismatch, or create only on zero. Prove
+   canonicalize(config title) equals config name. For personal creation, run
+   `apps create "<canonical-config-title>" . --json` exactly once and verify id,
+   slug, edit permission, and personal scope. For explicit team scope, discover
+   and describe `LOCAL_NOTIS_CREATE_APP`, dry-run it, then execute it exactly once
+   with the canonical title, team visibility, and verified current team scope;
+   verify id/slug/team scope/edit permission and `apps link` that exact id. Then
+   compare declared databases, mutate only
+   missing/changed backward-compatible schemas with ownership proof, run exactly
+   one `apps deploy`, and read back id/version/Portal URL before live verify.
+5. Check project health:
    - `npx --package @notis_ai/cli@latest -- notis apps doctor`
-10. Only after the user explicitly approves the current Store preview, submit the deployed version:
+6. Only after the user explicitly approves the current Store preview, submit the deployed version:
    - `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready`
 
 ### App development rules
 
 - Always `build` before `deploy`; run `verify` before deploy when validating an app change.
+- Never run `apps dev` in a hosted sandbox. Deploy every successfully verified
+  sandbox app create or edit unless explicitly told preview-only, read-only, or
+  no-deploy, then prove the remote id/version and live runtime. Other app tasks
+  do not authorize mutation.
+- Deploy does not create databases. Compare first; materialize only missing or
+  changed hosted-app schemas, and verify exact ownership before an update.
+- Build and verify before hosted app creation or database mutation. Only
+  backward-compatible schema expansion may happen before deployment.
+- In hosted sandboxes, bootstrap `agent-browser` and include its package on the
+  verification command's `PATH`; `--no-browser` is not a passing automated gate.
+- Never deploy a local Desktop edit until the user tests the DEV app and asks.
 - Prefer `npx --package @notis_ai/cli@latest -- notis apps deploy` for the first deploy of a project already run with `apps dev`; it promotes the development app in place.
 - Link before `deploy`, or pass `--app-id <id>` when intentionally deploying without writing local link state.
 - Use `npx --package @notis_ai/cli@latest -- notis apps doctor` to diagnose configuration or dependency issues.
-- Use `npx --package @notis_ai/cli@latest -- notis apps list` to discover existing app IDs before linking.
+- Use `npx --package @notis_ai/cli@latest -- notis apps list --json` to discover exact slugs, permissions, versions, and Portal links before linking and after deployment; use a metadata-only (`include_documents: false`) exact app-detail read to prove personal/team scope without materializing databases.
 - Never treat deploy approval as Store approval. Set visibility to Team or Public first, then run `apps publish --confirm-ready` only after the user explicitly confirms the current App Details page and Store listing.
 - `apps publish --confirm-ready` submits the deployed snapshot through the same backend review flow as App Details. It must reject missing confirmation, incomplete listing media, a local/deployed version mismatch, private visibility, or an existing pending review.
 
@@ -134,14 +190,16 @@ If the task is specifically about app structure, runtime behavior, or database/v
 
 ## IMPORTANT: When NOT to use tool access for app development
 
-When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for any of these operations:
+When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for app file operations:
 
-- Creating databases -- declare them in `notis.config.ts` instead
 - Loading or saving app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps deploy`
 - Linting app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` which validates automatically
 - Managing app routes -- write standard Vite + React pages in `app/`, not raw JS files
 
-The only `npx --package @notis_ai/cli@latest -- notis tools exec` calls that are valid during app development are for testing the app's runtime behavior after deployment (e.g., querying a database to verify data was created).
+Database schemas are the exception: declaring a slug in `notis.config.ts` does
+not create it. Use the discovery-first native database tool workflow to
+create/update and read back each app-owned schema before deployment. Tool calls
+are also valid for testing runtime behavior after deployment.
 
 ## Section 2: Accessing Tools Through the Notis CLI
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.15",
+  "version": "0.2.17",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {

package/skills/notis-apps/cli.md

@@ -118,7 +118,7 @@ Examples:
 
 Register a development root and connect its apps to the shared local development host.
 
-When to use: Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance.
+When to use: Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance. A linked app substitutes its online bundle only when local notisAppVersion is strictly greater than the installed release.
 
 Options:
 - `--port <number>` — Local bundle server port (default: 5173).
@@ -218,7 +218,7 @@ Examples:
 
 Download a Notis app source snapshot into a local project folder.
 
-When to use: Edit an installed app locally. Pulls the persisted source, links the directory to the app/version, then continue with npm install, notis apps dev, notis apps build, and notis apps deploy.
+When to use: Edit an installed app locally. Preserve any local edits, pull and link the latest persisted source, then increment package.json notisAppVersion above that release before notis apps dev; continue with build and deploy.
 
 Options:
 - `--force` — Overwrite a non-empty target directory.