@notis_ai/cli 0.2.0-beta.158.1 → 0.2.0-beta.159.1

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

@@ -7,62 +7,45 @@ mcp_tool_patterns: ["LOCAL_NOTIS_INSTALL_APP"]
 mcp_references: ["references/release.md", "references/architecture.md", "references/design.md", "references/sdk.md", "references/troubleshooting.md"]
 ---
 
-# Notis Apps Skill
-
-Use this skill when the user wants a packaged Notis app -- task manager, CRM, dashboard, internal tool, etc. Notis apps are **Vite + React projects** that deploy into the Notis portal as installed apps for the current user or team.
-
-Run the Notis CLI through NPX, for example `npx --package @notis_ai/cli@latest -- notis apps list`. Sign the CLI in once with `notis login`; each account you authorize is a profile you can switch between with `notis profile use`. The CLI bundles this `notis-apps` base skill and refreshes its canonical copy under `~/.notis/skills/base/` on every launch. It is independent of account-skill sync, feature flags, target selection, and cloud deletion.
-## User and repository policy takes precedence
-
-Default delivery below applies only when no more restrictive user or repository
-instruction exists. Explicit preview-only/no-deploy requests and standing requirements
-for explicit deployment consent override the default. Preserve that authority across
-local and cloud runs. For local-only work, build and run stub verification; do not
-create remote resources or activate an app. `apps dev` is not a supported delivery
-path; use the CLI's documented build/verification harness. Store publication remains
-separately authorized.
-
-## Hard Rules
-
-1. **React + Vite only** -- No Next.js, no custom server
-2. **ES module bundle** -- Vite builds a library-mode bundle with React externalized
-3. **Component rendering** -- Apps render as React components directly in the portal. Do not create your own iframe; the host chooses the trusted shadow-root or isolated Store rendering path.
-   The portal owns the `ShadowRoot`, theme tokens, and runtime provider.
-4. **HTTP bridge** -- Runtime calls use fetch to `/portal_views/runtime_query`
-5. **Declarative tools** -- Tool access is declared in `notis.config.ts` by the final names returned by tool discovery and enforced server-side. Views can call native Notis, connected integrations, PostForMe, and MCP tools directly; metered calls use the same credit-cap and usage-billing path as the CLI.
-6. **shadcn + Notis theme** -- Apps must use shadcn components with the live Notis theme provided by the portal
-7. **Phosphor icons only** -- Always `phosphor:` prefix. Never emojis.
-8. **Database refs only** -- `notis.config.ts` references existing databases by slug. The schema source of truth lives in the `databases` table, not in the manifest. Every native database is owned by exactly one app (`databases.owner_app_id`): creating one through `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` requires the owning app's slug or id in the `app` argument, installation stamps ownership automatically, and deleting an app deletes its databases and their documents.
-   An app-owned database slug is a stable deployed contract because bundles and
-   collection routes may call it directly. Do not try to rename that slug with
-   a schema tool; rename the display title instead.
-9. **Use NPX for CLI commands** -- Always run `npx --package @notis_ai/cli@latest -- notis ...`.
-10. **`apps deploy` is not store publishing** -- `apps deploy` updates an installed app only and persists its source snapshot. Store review starts separately with `apps publish --confirm-ready` after explicit user approval.
-11. **Routes are canonical** -- Define navigation only in `manifest.routes`. Every configured route must declare an explicit `slug`. Do not rely on legacy `manifest.views`.
-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. **One delivery gate** -- Follow the release guide on local and cloud computers, subject to the policy precedence above. No DEV runtime exists.
-16. **Exact identity** -- Preserve the intended profile, editable app ID, personal/team scope and current deployment base. Never silently advance a stale checkout.
-17. **Automatic source updates** -- Build and check requested app source changes, then update Workspace only when allowed by the user/repository policy above. Store publication stays separate.
-18. **Runtime permissions stay least-authority** -- Release activation preserves existing grants and keeps restricted capabilities denied until approved.
-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. **Source restoration** -- Restore historical source as a new release using the current deployment base; never revert data or decrement 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 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`.
-
-## Task guides
-
-Read only the guide needed for this task. Relative links resolve in the skill bundle.
-For hosted MCP, fetch the matching `notis://docs/notis-apps/references/<file>.md` URI
-with resources/read or the available Notis resource-fetch tool; the root resource
-also rewrites these links to their published URIs.
-
-- [Release-only delivery](references/release.md)
-- [How Apps Are Built](references/architecture.md)
-- [Building an App](references/design.md)
-- [SDK Hook Reference](references/sdk.md)
-- [Anti-patterns -- NEVER do these](references/troubleshooting.md)
+# Notis Apps
+
+Build apps that feel native to Notis: compact, readable, responsive, and useful.
+Use Vite + React, `@notis/sdk`, and the existing scaffold components. Use the Notis
+CLI for app operations: `npx --package @notis_ai/cli@latest -- notis ...`.
+
+## Build → inspect → fix → deliver
+
+For every app UI create/edit task, read both [Design](references/design.md) and
+[Delivery](references/release.md). Then:
+
+1. **Understand the result.** Identify the main user action and the requested
+   change. For a reported visual bug, describe what is wrong in the actual
+   screen before editing. Preserve what already works.
+2. **Start from native patterns.** Pull the existing app or choose the closest
+   Store scaffold. Use the appropriate page layout instead of inventing a new
+   visual system. Make routine choices yourself; ask only for missing decisions
+   that materially change the result.
+3. **Build, look, improve.** Run build and verification, then actually inspect
+   the rendered app. Follow the short visual check in the design guide. Fix what
+   is wrong and recheck the affected screen; a passing build is not visual approval.
+4. **Deliver the checked result.** Follow the delivery guide and existing user
+   authorization. Confirm the released result inside Notis before calling it
+   verified. Say plainly what is local, deployed, or still unverified.
+
+## Keep these boundaries
+
+- User and repository instructions take precedence, including preview-only,
+  no-deploy, and explicit-consent requirements. Store publication is separate.
+- Preserve the exact app identity, account/team scope, permissions, and user data.
+  Reconcile an uncertain release instead of blindly retrying it.
+- Use SDK hooks and declared tools. Let Notis own its sidebar, search, runtime,
+  and rendering boundary; do not query host DOM or recreate that chrome in the app.
+
+## References — only as needed
+
+- [SDK hooks](references/sdk.md): reads, edits, selection, and navigation.
+- [App contracts](references/architecture.md): configuration, packaging, and data ownership.
+- [Troubleshooting](references/troubleshooting.md): a specific failure or mismatch.
+
+The CLI distributes this skill and its references from the canonical product
+source. Do not maintain competing copies.

package/dist/base-skills/notis-apps/references/architecture.md

@@ -6,6 +6,14 @@ All Notis apps are built using the Notis CLI, either locally in a repo workspace
 - the app is packaged as an ES module bundle
 - the portal renders it as a React component inside the portal's React tree
 
+Use standard React pages in `app/`, not Next.js or a custom server. The host
+chooses a trusted shadow root or an isolated Store frame; do not create your own
+iframe, query Portal-owned DOM, or install a window-global runtime. The host owns
+theme injection and authentication. App code uses SDK hooks and the final tool
+names discovered through the CLI, declared in `notis.config.ts` and enforced by
+the backend. Runtime permissions stay least-authority; releasing an app does not
+grant new capabilities.
+
 ## Architecture
 
 ```
@@ -71,9 +79,15 @@ Generated by `npx --package @notis_ai/cli@latest -- notis apps build` at `.notis
 }
 ```
 
-Use canonical `notis-*` tool names for explicit app tool declarations. App-specific TypeScript shapes for tool arguments and results live in the app code; the SDK exposes the generic `useTool<TArgs, TResult>()` hook instead of database-specific tool hooks.
+Use the exact final names returned by tool discovery for explicit app tool declarations. App-specific TypeScript shapes for tool arguments and results live in the app code; the SDK exposes generic tool hooks alongside its native database hooks.
+
+Routes are canonical: define navigation in `routes`, give every route an explicit
+`slug`, and do not rely on legacy `views`. A configured `collection.sidebar` tree
+belongs to the host, not app JSX.
 
 Database strings package schema only. The object form shown above opts that database into copying its current rows as Store starter content. Use it sparingly and only for non-personal fixtures/templates every installer is meant to receive.
+Never seed user-created notes, history, leads, or other private records. In source
+config the explicit opt-in is `{ slug: 'templates', seedDocuments: true }`.
 
 For a read-only database catalog app, declare `["LOCAL_NOTIS_DATABASE_LIST_DATABASES", "LOCAL_NOTIS_DATABASE_GET_DATABASE"]`. Use the list tool for the left/catalog pane and the get tool for the selected database detail pane.
 
@@ -108,6 +122,9 @@ Every row in the `databases` table carries `owner_app_id` (uuid FK to
 deleting the app deletes its databases and their documents (`documents` cascade
 from `databases`). Install, resource preparation, and Store updates stamp
 `owner_app_id` automatically; standalone creation requires the `app` argument.
+The app config references existing database slugs; it does not own the schema.
+The database row is the schema source of truth. Treat deployed slugs as stable
+contracts: rename display titles rather than changing slugs behind live callers.
 
 ### Storage (Supabase)
 

package/dist/base-skills/notis-apps/references/design.md

@@ -1,13 +1,56 @@
 ## Building an App
 
+### Design defaults
+
+- Start from the closest Store scaffold (`apps scaffolds list`, then `apps init
+  --from <slug>`), or preserve the existing app's good patterns.
+- Make the main task obvious. Use compact spacing, readable text, plain page
+  titles, Phosphor icons, and the scaffold's buttons, filters, rows, and cards.
+- Match Notis in light and dark mode. Use theme tokens and restrained accents;
+  prefer flat surfaces and selection tints over decorative boxes and shadows.
+- Choose the right layout: `notis-app-shell` for ordinary content;
+  `notis-app-split`, `notis-app-pane-list`, and `notis-app-pane-detail` for a
+  full-viewport list and reader. Keep reading text comfortably sized. Let mobile
+  stack or adapt the content rather than squeeze a desktop layout onto a phone.
+- Let Notis own navigation, folder trees, and search. Use `PageHeading`,
+  `NativeSelect`, `.list-row`, and `useTopBarSearch` instead of duplicating chrome.
+- Prefer inline optimistic edits for simple changes, with rollback on failure.
+  Use a dialog for multi-field edits or destructive confirmation.
+
+Build enforces the existing design rules and reports violations by file/line.
+Use those diagnostics to fix specific problems; passing them does not establish
+that the design is good. See [troubleshooting](troubleshooting.md) when needed.
+
+### Look at the result
+
+Run build and verification, then inspect screenshots of the affected view at a
+normal desktop width and a phone width. For new layouts or theme changes, check
+both themes. Keep the review focused on the task, not a new report or approval cycle:
+
+- Does the layout use the available viewport correctly, including while loading?
+- Do sizing, spacing, text, and scrolling look right? Is anything clipped or overflowing?
+- Do loading placeholders match the real content instead of changing the layout?
+- Does the main interaction work, and do empty/error states explain what to do?
+
+Use temporary fixtures to expose slow reads, empty results, and errors where
+relevant; do not alter real user records for a screenshot. Actually inspect the
+images, fix what is wrong, and recheck the affected state. After an authorized
+release, repeat the affected-view check inside Notis as described in
+[Delivery](release.md). A standalone harness is not proof of the host layout.
+
 ### Step 1: Define the config
 
+Use `~/.notis/apps/<slug>` by default, or pass the user's intended directory to
+`apps init` / `apps pull`. Avoid a parent workspace that selects an unrelated CLI
+profile. Keep the exact installed identity when editing; do not rename a machine
+slug just to correct its display title.
+
 Create `notis.config.ts` with:
 - **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.
+- **tools** -- Final tool names the app can call at runtime. Discover tools with `notis tools search "<what you need>"`, inspect their schemas with `notis tools describe <tool>`, 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.
 
 For collection-backed sidebars, use the route schema directly:
 
@@ -64,7 +107,7 @@ Build a client-side, multi-route app with one persistent `app/layout.tsx` shell.
 
 | State | Required UI |
 | --- | --- |
-| First read, no successful data | Keep headings/navigation/layout visible; use content-shaped skeletons only in missing regions. No page spinner or whole-page `Loading...`. |
+| First read, no successful data | Keep headings/navigation/layout visible; use content-shaped skeletons only in missing regions, with the same pane bounds as the loaded view. No page spinner or whole-page `Loading...`. |
 | Cached view / successful empty result | Render synchronously from the shared SDK cache. Empty results are real cached results. |
 | Background refresh | Keep current content and selection. Never replace populated content with a skeleton; do not drive the top-bar spinner from mount/refetch state. |
 | Explicit Save / Upload / submitted search | Progress belongs in that button or affected section. Disable only the conflicting action. |
@@ -109,38 +152,6 @@ await upsertTask.call({
 
 Do NOT pass Notion-style wrappers (`{select: {name: "Todo"}}`) when upserting.
 
-### Design bar (enforced)
-
-Every page must read as a native, flat Notis page. `npx --package @notis_ai/cli@latest -- notis apps build` and the deploy endpoint fail on the banned patterns below with the exact file and line; the only override is an inline `// notis-design-allow: <rule-id> <reason>` comment on the line before (reason required, at least 12 characters). Do not work around a failure by moving the markup elsewhere; fix it.
-
-Banned in `app/` and `components/` (form controls in `components/ui/{input,textarea,checkbox,switch,button}.tsx` are exempt):
-
-- Four-side `border` boxes, `border-dashed`, `divide-*`, `<hr>`, thick `border-l-2` bars, `ring-*` as a box or selection indicator (`focus-visible:ring-2` on controls is fine).
-- `shadow-*` on panels, tiles, rows, or bubbles. Only a floating popover or menu may use `shadow-lg` together with `bg-popover`.
-- Tailwind palette hues (`emerald-500`, `slate-200`, ...), hex colors, gradients, `backdrop-blur`, `font-serif`.
-- Uppercase `tracking-wide` eyebrows and marketing headlines. Page titles are plain nouns matching the route ("Dashboard", "Meetings").
-- Text below 12px (`text-[11px]`); use `text-xs` at minimum and `text-sm` for body.
-- `Badge variant="outline"`, raw `<select>`, in-app search inputs, duplicate sidebars, untouched scaffold placeholder copy.
-- Loading text ("Loading...") or whole-page spinners. Keep headings visible and render `Skeleton` / `ViewSkeleton` from `@notis/sdk` only in the missing region (see the Instant-view contract).
-
-Use instead:
-
-- `Card` from the scaffold: a flat `bg-muted` panel that becomes `bg-background` when nested. Page sections can also be plain `h2` + content with `space-y-8`.
-- `.list-row` / `.list-row-selected` from `@notis/sdk/styles.css` for rows and table bodies (tinted on mobile, transparent with hover tint on desktop, selection by tint). Tables are flat on the page: `text-xs` muted header, `text-sm` rows, no wrapping panel.
-- Stats as bare figures: `text-xs` label over `text-2xl font-semibold tabular-nums`. Tiles (`rounded-2xl bg-muted p-5`) only when they are the page's single grouping device.
-- `PageHeading` for the header, `NativeSelect` for filters, `Badge` variants `default | secondary | destructive`, tokens only (`text-foreground`, `text-muted-foreground`, `text-primary`, `bg-primary/10`, `text-destructive`, `bg-destructive/10`), `tabular-nums` on numbers, `min-w-0` on every grid item that can hold long text.
-- One hairline (`border-t` / `border-b border-border`) between major sections or large list entries is the only allowed line.
-- List-plus-detail pages are full-bleed: `notis-app-split` with `notis-app-pane-list` (tinted, one `border-r` hairline, fixed width on desktop, stacked on mobile) and `notis-app-pane-detail` (`bg-background`), never the centered `notis-app-shell`.
-- Respect the portal theme in both modes. Never hardcode dark mode or an app palette.
-- For Notes-style apps, the folder tree belongs to the portal sidebar when configured via `collection.sidebar`. The page content should complement that chrome, not duplicate or replace it.
-- Do not render any search input inside the app (in-page search rails, "Ask Notis…" pills, command-palette-style bars, etc.). The portal already owns the top-bar search field. Wire your view to it with `useTopBarSearch({ value, onChange, placeholder, onSubmit })` from `@notis/sdk` and let the page filter or refetch on the values it receives. Use its `setLoading` only for an explicit submitted search, never initial view loading or background refresh.
-
-### Sidebar invariants
-
-- When a user asks for folders, sections, or hierarchy in the app sidebar, express that through `routes` and `collection.sidebar` in `notis.config.ts`.
-- Treat an existing collection-tree sidebar as a locked structural requirement unless the user explicitly asks to change navigation architecture.
-- If the sidebar appears missing for the installed app, do not silently redesign around it. Preserve the manifest contract, call out the discrepancy, and treat it as a portal/runtime bug.
-
 ### Step 3: Root layout
 
 ```tsx

package/dist/base-skills/notis-apps/references/release.md

@@ -1,93 +1,99 @@
-## Release-only delivery
-
-Workspace runs released app versions only. Local and cloud agents use the same workflow.
-A request to create or edit app source authorizes updating that app in Workspace after checks pass.
-Explicit read-only, preview-only or no-deploy requests stop at local artifacts and checks: no remote
-app/resource creation or mutation, Workspace preview, deployment or live verification. Store
-publication always needs separate explicit approval.
-
-1. Inspect the effective CLI profile and the exact app's current version with `apps list --json`.
-   For an existing released app, preserve local edits and pull its exact app ID into the intended
-   directory. Retain the profile/app link, deployment version and revision. An unreleased container
-   has no source to pull: recover its original local source and edits, or scaffold locally only if
-   that source cannot be recovered. Confirm its exact ID, edit permission and personal/team scope,
-   then run `apps link <app-id> <source-directory> --expected-version 0` to resume that same container.
-   If a release has appeared, preserve local source separately, pull the current release into a fresh
-   directory and reapply the intended edits. The link guard compares against the same remote read
-   whose version/revision it saves; deploy still rejects a release racing after that read. Do not pull
-   missing source or create another remote app to recover a failed first release.
-2. Scaffold a new app locally, or edit the pulled source. Run `apps build` and automated
-   `apps verify` before new remote creation. Missing browser tooling or failed checks blocks delivery;
-   printed URLs and `--no-browser` are not passing verification. Install browser tooling with
-   `npm exec --yes --package agent-browser@latest -- agent-browser install`; if needed run
-   `npx --yes --package @notis_ai/cli@latest --package agent-browser@latest -- notis apps verify`.
-3. Reconcile `apps list --json` and the exact intended name/slug, edit permission and personal/team
-   scope. Default to personal only when no team was requested. Reuse a matching editable identity;
-   stop on ambiguous matches or conflicting identity/scope. Create only when none exists, using
-   `apps create "<exact app name>" .` (or `--team-id <verified team ID>`). Read back the same ID.
-   A failed first release leaves a container: reuse it, never duplicate or automatically delete it.
-4. Compare existing app-owned schemas. Create only necessary missing databases against that exact
-   app ID. Change existing schemas by verified database ID and ownership, and only with backward-
-   compatible changes before release. Read back each change. Breaking changes need separate coordination.
-   Ordinary note/record edits and existing resource editors remain immediate.
-5. Run `apps deploy` against the same linked app. It builds, verifies a frozen source/artifact
-   snapshot with stubs, then sends that snapshot to the backend. `--skip-build` accepts only unchanged,
-   valid output and still verifies. Do not bypass the backend or create implicitly on deploy.
-6. Read back the exact installed app ID, integer version and Portal URL with `apps list --json`.
-   Run `apps verify --mode live` and open the installed app in the actual Portal for surface proof.
-   A live harness check alone does not prove the deployed bundle rendered in Portal.
-7. Report **failed before activation**, **deployed but unverified**, or **outcome unknown** accurately.
-   Never blindly replay an uncertain create/deploy response; reconcile its exact identity/version first.
-   `apps publish --confirm-ready` is **Publish to Store**, separately approved and listing-gated.
-   Workspace delivery is **Update app**, with no Store screenshot/readiness requirement.
-
-### Restore historical source as a new release
-
-Pull the current release into a fresh checkout first. Retrieve historical source into a different
-folder (`apps pull <id> <historical-dir> --source-version <n>`). Replace source in the current checkout
-without replacing its `.notis` profile/app link or deployment base. Update `package.json`'s
-`notisAppVersion`, check compatibility with current resources, build, verify and deploy as a new
-release. Preserve app/database/skill IDs. Never decrement the deployment counter, rewrite snapshots,
-or claim to undo user data or external actions.
-
-## Workflow
-
-Follow the Release-only delivery steps in this guide, subject to the entrypoint’s user/repository policy precedence. Use `apps scaffolds list` to discover public Store starting
-points, `apps init` to scaffold locally, and `apps pull` for existing source. App file operations go
-through the CLI, never raw storage/database writes. Run all Notis commands through NPX.
-
-## Testing
-
-Build and automated stub verification precede release. `verify` and `screenshot` start temporary,
-explicit test servers only: no folder discovery, watchers, Desktop registration, persistent roots,
-consumer leases or Workspace mounting. They close server/browser resources at completion or interruption.
-Build also enforces the design bar and refreshes the app's embedded SDK copy. Automated verification
-checks every route at desktop (1280px) and phone (390px) widths, including nested boxes, text below
-12px, lingering loading placeholders and horizontal overflow. Standalone verification writes a
-local diagnostic report; deploy always verifies its own frozen snapshot, with no stamp or environment bypass.
-After release, verify live runtime integration and open the installed bundle in Portal. Source edits
-and Desktop restarts cannot change the running version.
-
-### Screenshots
-
-`apps screenshot` supports declared screenshot scenarios and stub fixtures. A scenario can set
-`theme: 'dark'`; use `--raw` for uncomposited captures. Store screenshots and listing readiness
-are required only for Publish to Store, never for Update app.
-
-### 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. 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
-
-- Hooks that mount but throw on first read (`useTool` called with the wrong tool name or argument shape, accessing nested props that are undefined).
-- Runtime database queries whose slug is not declared by the app, and collection routes that never query their configured collection database. Declared databases may also support automations or agent workflows, so ordinary routes do not need to query every app database.
-- Tool names referenced by hooks but missing from `notis.config.ts -> tools`.
-- Suspense / async boundaries that never resolve because a runtime stub returned the wrong shape.
-- Render-time exceptions that the portal would surface as the `View crashed` error boundary.
-
-#### What the harness does not catch
-
-- Bugs that only manifest with real backend data (auth-scoped filters, RLS, malformed prod records). For those, swap the stub runtime for a real one that posts to `/portal_views/runtime_query` with a JWT.
-- Pixel-level visual regressions beyond the automated design checks (the harness does flag nested boxes, sub-12px text, lingering loading placeholders, and horizontal overflow at 390px). For anything else, use `agent-browser screenshot` + a baseline compare.
-- Bugs that depend on the portal's shadow-DOM stylesheet wrapping. The harness mounts in light DOM, so global Tailwind/shadcn classes work normally; portal-specific theme tokens injected as inline styles are not present.
+## Delivery
+
+Workspace runs released versions only. Local and cloud agents use the same
+workflow. Run Notis commands through
+`npx --package @notis_ai/cli@latest -- notis ...`.
+
+A create/edit request normally authorizes updating that app after checks pass,
+**unless user or repository policy requires explicit deployment consent**.
+Preserve authorization already given. Read-only, preview-only, and no-deploy
+instructions stop at local source, build, and stub verification: no remote
+resource mutation, app activation, or live verification. Store publication always
+needs separate explicit approval. Do not deploy just to obtain visual proof when
+deployment is not authorized; report that the host check remains unverified.
+
+## Update an app
+
+1. **Check identity.** Inspect the effective CLI profile and `apps list --json`.
+   Preserve local edits, then pull the exact editable app ID and intended
+   personal/team scope. Keep its profile-scoped link, current version, and revision.
+   Never silently advance a stale checkout or create a duplicate to avoid a conflict.
+2. **Build and inspect.** Edit the source, increment `notisAppVersion`, and update
+   `CHANGELOG.md`. Run `apps build` and automated `apps verify`, then do the
+   [visual check](design.md#look-at-the-result). For a new app, complete these
+   local checks before creating remote resources.
+3. **Prepare only missing resources.** For an existing app, retain its identity.
+   For a new app, reconcile the exact canonical name, edit permission, and scope
+   against `apps list --json`; reuse one matching editable identity, stop on
+   ambiguity, or create only when none exists. Use `apps create "<display title>"
+   <dir>` (with a verified `--team-id` for team scope), and read back the same ID.
+   Create only necessary missing databases against that app. Verify ownership
+   and database IDs before changing schemas; read back changes. Breaking changes
+   require separate coordination. Never mutate user data merely to test the UI.
+4. **Update Workspace.** Run `apps deploy` against that linked app. It builds and
+   verifies a frozen source/artifact snapshot before activation. `--skip-build`
+   accepts only unchanged valid output and still verifies. Use the supported
+   backend path; do not bypass checks or write directly to storage.
+5. **Verify delivery.** Read back the app ID, integer version, and Portal URL with
+   `apps list --json`. Run `apps verify --mode live`, then open the released app
+   inside Notis and inspect the affected screen and main interaction. Confirm the
+   intended bundle/version, not just the existence of an app with the same name.
+   A successful live harness check alone is not visual proof inside Notis.
+6. **Report accurately.** Give the app link and a brief description of what changed
+   and what was verified. Distinguish local-only, deployed and verified, deployed
+   but unverified, failed before activation, and outcome unknown. If create/deploy
+   has an uncertain outcome, reconcile its exact identity/version before retrying.
+
+## What the checks prove
+
+`build` validates the package, enforces design rules, and refreshes its embedded
+SDK. Automated `verify` checks every route at desktop (1280px) and phone (390px)
+widths, render errors, runtime calls, nested boxes, small text, lingering loading
+placeholders, and horizontal overflow. It uses a temporary server and browser;
+printed URLs or `--no-browser` are not passing verification. If tooling is missing,
+install it with `npm exec --yes --package agent-browser@latest -- agent-browser install`.
+
+Stub verification does not establish real account data, permissions, host layout,
+or visual quality. Live verification exercises the authenticated runtime but still
+uses the harness. The final installed-app check establishes the result inside Notis.
+If that surface cannot be inspected, say so rather than claim it passed. No extra
+approval round is needed for an already-authorized check.
+
+`apps screenshot` supports declared scenarios and stub fixtures, including
+`theme: 'dark'`; `--raw` gives uncomposited captures. Store listing screenshots are
+not required for an ordinary Workspace update.
+
+## Special cases — read only when relevant
+
+### Unreleased container or stale checkout
+
+An unreleased container has no source to pull. Recover its original local source,
+or scaffold only if it cannot be recovered; verify the exact ID and scope and use
+`apps link <app-id> <dir> --expected-version 0`. Reuse the container after a failed
+first release; do not duplicate or automatically delete it. If another release
+has appeared, pull it into a fresh directory and reapply the intended edits without
+replacing its deployment base. Link/deploy guards must reject races and conflicts.
+
+### Restore an older source
+
+Pull the current release into a fresh checkout and the historical source into a
+separate folder (`apps pull <id> <dir> --source-version <n>`). Replace source without
+replacing the current `.notis` link/base, then check and deploy as a new release.
+Preserve app/database/skill IDs. Never decrement versions or imply that source
+restoration undoes user data or external actions.
+
+### Release history and Store publication
+
+Keep all release history in root `CHANGELOG.md`, newest first, with headings
+`## [Release title] - YYYY-MM-DD` (or `{PR_MERGE_DATE}` while unpublished). Do not add
+`versionNotes` to the config. App Details reads deployed history; the Store reads
+its published snapshot. Local edits must not change the published listing.
+
+`apps deploy` updates Workspace only. Use `apps publish --confirm-ready` only after
+the user explicitly approves the current App Details and Store listing. Deploy the
+exact approved source first. Respect listing completeness, visibility, version,
+and pending-review guards. A public submission includes editable source, Store
+assets, source-declared database schemas, and only explicitly opted-in starter
+rows. Do not hand-edit `notis-listing.json` or strip files to pass review; fix the
+source, redeploy, and resubmit. To start from a Store app, use `apps init --from
+<slug>`; `apps pull` is for an accessible installed app, not a Store listing clone.

package/dist/base-skills/notis-apps/references/sdk.md

@@ -6,8 +6,9 @@ already installs `ShortcutProvider`; app code should not add a second provider.
 | API | Signature | Description |
 |-----|-----------|-------------|
 | `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 |
+| `useTool<TArgs, TResult>(name)` | `(name: string) => { call, loading, error }` | Call a declared tool with app-defined argument/result types. Identified reads use `call(args, { readOnly: true, dedupe: true })`; never dedupe writes. See [cached-read ownership](design.md#instant-view-loading-contract-required). |
 | `useTools()` | `() => { tools, loading }` | List available tools |
+| `useDocuments(slug, opts?)` | `(slug: string, opts?) => { documents, loading, hasData, error, refetch }` | Query an app database. Bodies are included by default. For metadata-only lists, opt into `includeContent: false`; load the opened record with `useDocument` and defer any full-body search query until needed. Metadata and full-content query caches are separate. |
 | `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 |

package/dist/base-skills/notis-apps/references/troubleshooting.md

@@ -1,26 +1,23 @@
-## Anti-patterns -- NEVER do these
-
-These are the most common mistakes agents make. Each one wastes time and produces broken results.
-
-- **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 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.
-- **One local/cloud delivery contract** -- The default permits Workspace delivery after checks only when user/repository policy allows it. Explicit read-only, preview-only and no-deploy requests prohibit remote mutations. Neither authorizes Store publication.
-- **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.
-- **NEVER treat `apps deploy` as store submission** -- It updates the linked installed app for the current account or team scope only. Store submission is a separate, explicitly confirmed step.
-- **NEVER explore server code or tool schemas to invent an alternative app workflow** -- Use the Notis CLI.
-- **NEVER work around a missing `collection.sidebar` portal tree by rendering a duplicate sidebar inside the app** -- keep the route manifest as the source of truth and escalate the missing portal sidebar as a platform bug instead.
-- **NEVER invent a custom visual language** -- Do not ship full-screen gradients, glassmorphism, bright neon palettes, or raw HTML controls as the primary UI. Apps should look like a natural extension of the portal.
-- **NEVER hand-roll buttons/cards/badges when the scaffold already provides flat primitives** -- Prefer `@/components/ui/*` and portal token classes such as `bg-background`, `bg-muted`, and `text-muted-foreground`. Never add `border` or `shadow` classes to `Card`; a `Card` nested in a `Card` is flat automatically. See Design bar.
-
 ## Troubleshooting
 
-### Common issues
+Start with the failing screen or operation. Do not invent a second app workflow;
+use the [delivery guide](release.md) and supported Notis CLI commands.
 
-- **Deploy transport failure**: Run `notis doctor` and read back the exact app/version. Never blindly retry an unknown outcome or write directly to storage.
-- **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 Workspace**: Inspect its exact installed version. Unreleased containers have no runnable routes. A successful release appears through ordinary refresh/navigation.
-- **`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.
+- **App looks wrong despite passing checks:** open it inside Notis and compare
+  the affected region with the request. Check loading and loaded states, viewport
+  sizing, scrolling, and theme. A standalone harness does not reproduce the host's
+  parent layout or shadow boundary. Do not assume the cause from a screenshot alone.
+- **Build reports a design violation:** use the scaffold component or theme token
+  suggested by the diagnostic. Fix the reported file/line rather than hiding the
+  pattern elsewhere. Existing validator exceptions are for justified cases, not a
+  shortcut around visual review.
+- **The configured sidebar is missing:** preserve `routes` and `collection.sidebar`;
+  investigate the host mismatch instead of duplicating the sidebar in app code.
+- **The app shows old code or is missing from Workspace:** check the exact installed
+  app/version and requested bundle first. Local source edits and Desktop restarts
+  do not update a released app. Refresh after confirming the correct release exists.
+- **Deploy transport failure:** run `notis doctor` and read back the exact app/version.
+  Reconcile the outcome before retrying; do not bypass the backend with storage writes.
+- **Database query is empty or properties are undefined:** inspect the actual schema,
+  database ID, and returned property shape through the CLI. Keep types in the app,
+  guard optional fields, and distinguish an error from a successful empty result.

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

@@ -77,8 +77,8 @@ Default delivery below applies only when no more restrictive user or repository
 instruction exists. Explicit preview-only/no-deploy requests and standing requirements
 for explicit deployment consent override the default. Preserve that authority across
 local and cloud runs. For local-only work, build and run stub verification; do not
-create remote resources or activate an app. `apps dev` is not a supported delivery
-path; use the CLI's documented build/verification harness. Store publication remains
+create remote resources or activate an app. Use the CLI's documented
+build/verification harness. Store publication remains
 separately authorized.
 
 ### Tool access workflow

package/package.json

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

package/template/packages/sdk/src/hooks/useDocuments.ts

@@ -19,6 +19,8 @@ export interface UseDocumentsOptions {
   offset?: number;
   /** Fetch every page, starting at offset, instead of returning only one page. */
   fetchAll?: boolean;
+  /** App-view lists can omit bodies until opening/searching a document. Default: true. */
+  includeContent?: boolean;
   enabled?: boolean;
 }
 
@@ -47,7 +49,7 @@ export function useDocuments(
 ): UseDocumentsResult {
   const runtime = useNotisRuntime();
   const query = useQuery<DocumentRecord[]>(
-    ['documents', databaseSlug, options.filter ?? null, options.pageSize ?? null, options.offset ?? 0, Boolean(options.fetchAll)],
+    ['documents', databaseSlug, options.filter ?? null, options.pageSize ?? null, options.offset ?? 0, Boolean(options.fetchAll), options.includeContent !== false],
     async () => {
       if (!runtime) throw new Error('Notis runtime not available');
       const allDocuments: unknown[] = [];
@@ -58,6 +60,7 @@ export function useDocuments(
           query: {
             ...(options.filter ?? {}),
             ...(options.pageSize !== undefined ? { page_size: options.pageSize } : {}),
+            ...(options.includeContent === false ? { include_content: false } : {}),
           },
           ...(offset > 0 ? { offset } : {}),
         }, { dedupe: true, readOnly: true });

package/template/packages/sdk/src/queryCache.ts

@@ -68,6 +68,8 @@ export function createQueryClient(options: {
   maxEntries?: number;
   now?: () => number;
   schedule?: ReturnType<typeof createPrefetchQueue>;
+  /** Bounds idempotent reads only; never retries the underlying callback. */
+  readTimeoutMs?: number;
 } = {}): NotisQueryClient {
   const entries = new Map<string, Entry>();
   const now = options.now ?? Date.now;
@@ -117,14 +119,20 @@ export function createQueryClient(options: {
       const generation = ++value.generation;
       const requestEpoch = epoch;
       const canCommit = () => epoch === requestEpoch && value.generation === generation && entries.get(key) === value;
-      const request = Promise.resolve().then(read).then((data) => {
+      let timeout: ReturnType<typeof setTimeout>;
+      const deadline = new Promise<never>((_, reject) => {
+        timeout = setTimeout(() => reject(new Error('This read took too long. Please retry.')), options.readTimeoutMs ?? 30_000);
+        // Node-based verification must not stay alive for a retired browser read.
+        if (typeof timeout === 'object' && 'unref' in timeout) timeout.unref();
+      });
+      const request = Promise.race([Promise.resolve().then(read), deadline]).then((data) => {
         if (canCommit()) publish(value, { ...value.snapshot, data, hasData: true, isFetching: false, error: null, updatedAt: now() });
         return data;
       }, (reason) => {
         const error = reason instanceof Error ? reason : new Error(String(reason));
         if (canCommit()) publish(value, { ...value.snapshot, isFetching: false, error });
         throw error;
-      }).finally(() => { if (value.pending === request) value.pending = undefined; prune(); });
+      }).finally(() => { clearTimeout(timeout); if (value.pending === request) value.pending = undefined; prune(); });
       value.pending = request;
       publish(value, { ...value.snapshot, isFetching: true, error: null });
       return request;