@notis_ai/cli 0.2.0-beta.155.1 → 0.2.0-beta.156.1

package/dist/agent-hooks/notis-agent-hook.mjs

@@ -13830,7 +13830,7 @@ function runtimeCallLabel(call) {
   }
   return call?.op || "runtime call";
 }
-function assertHarnessResult(result, route, databaseSlugs, mode = "stub") {
+function assertHarnessResult(result, route, databaseSlugs, mode = "stub", capabilities = {}) {
   const assertions = [];
   if (result.tool_error) {
     assertions.push({
@@ -13869,7 +13869,7 @@ function assertHarnessResult(result, route, databaseSlugs, mode = "stub") {
   );
   for (const call of databaseQueries) {
     const databaseSlug = call?.args?.arguments?.database_slug;
-    if (databaseSlug && !declaredDatabaseSet.has(databaseSlug)) {
+    if (databaseSlug && !declaredDatabaseSet.has(databaseSlug) && capabilities.workspaceDatabases !== "read") {
       assertions.push({
         ok: false,
         code: "undeclared_database_query",
@@ -14963,7 +14963,8 @@ ${listing.errors.map((error) => `  - ${error}`).join("\n")}`);
           result,
           route,
           declaredDatabaseSlugs(appConfig, manifest, route),
-          mode
+          mode,
+          manifest.capabilities || appConfig.capabilities || {}
         );
         return {
           ...result,
@@ -14988,7 +14989,8 @@ ${listing.errors.map((error) => `  - ${error}`).join("\n")}`);
           result,
           route,
           declaredDatabaseSlugs(appConfig, manifest, route),
-          mode
+          mode,
+          manifest.capabilities || appConfig.capabilities || {}
         );
         results.push({
           route: route.slug,

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

@@ -104,7 +104,7 @@ App code never accesses the runtime directly -- it uses SDK hooks (`useTool`, `u
 
 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. No iframes.
+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.
@@ -293,40 +293,43 @@ For arbitrary app-owned resources that are not Notis collection rows, set `resou
 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`):
 
 ```tsx
-'use client';
-import { useEffect, useState } from 'react';
-import { useTool } from '@notis/sdk';
+import { useDocuments, ViewSkeleton } from '@notis/sdk';
 import { Card } from '@/components/ui/card';
 
-type QueryTasksArgs = { database_id?: string; database_slug?: string; query: { page_size?: number } };
-type TaskDoc = { document_id?: string; id?: string; title?: string; properties?: Record<string, unknown> };
-type QueryTasksResult = { documents?: TaskDoc[] };
-
 export default function TasksPage() {
-  const queryTasks = useTool<QueryTasksArgs, QueryTasksResult>('LOCAL_NOTIS_DATABASE_QUERY');
-  const [documents, setDocuments] = useState<TaskDoc[]>([]);
-
-  useEffect(() => {
-    void queryTasks
-      .call({ database_id: 'tasks-db-id', query: { page_size: 25 } })
-      .then((result) => setDocuments(result.documents || []));
-  }, [queryTasks.call]);
-
-  if (queryTasks.loading) return <div>Loading...</div>;
-
-  return (
-    <div className="p-6 space-y-4">
-      {documents.map((doc) => (
-        <Card key={doc.id || doc.document_id} className="p-4">
-          <h3>{doc.title || 'Untitled'}</h3>
-          <p className="text-muted-foreground">{String(doc.properties?.status || '')}</p>
-        </Card>
-      ))}
-    </div>
-  );
+  const tasks = useDocuments('tasks', { pageSize: 25 });
+  return <section className="space-y-4 p-6">
+    <h1 className="text-xl font-semibold">Tasks</h1>
+    {tasks.error && <p role="alert">{tasks.error.message} <button onClick={tasks.refetch}>Retry</button></p>}
+    {tasks.loading ? <ViewSkeleton variant="table" rows={5} /> : tasks.hasData ? (
+      tasks.documents.length ? tasks.documents.map((task) => (
+        <Card key={task.id} className="p-4"><h2>{task.title || 'Untitled'}</h2></Card>
+      )) : <p>No tasks yet.</p>
+    ) : null}
+  </section>;
 }
 ```
 
+### Instant-view loading contract (required)
+
+Build a client-side, multi-route app with one persistent `app/layout.tsx` shell. Navigate with `useNotisNavigation`; never use a document reload for an internal route. “SPA” means preserving that shell and reusing reads, **not** mounting every page or fetching every database at startup.
+
+| 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...`. |
+| 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. |
+| Failed read | Show a scoped error and Retry; keep usable cached content. Never show an empty-state message before `hasData` is true. |
+
+Use `useDocuments`, `useDocument`, `useDatabaseSchema`, and `useDatabaseSubscription` for native reads. `loading` means no first successful response; `isFetching` includes silent refresh. Do not copy their data into mount-only state, clear rows on error, or gate the entire app on `isFetching`.
+
+For another **explicitly identified idempotent read**, use `useToolQuery<Result>(toolName, exactArguments, { readOnly: true })`, or `useQuery(keyArray, readCallback, { readOnly: true })`. Include every filter, selected resource, pagination option, and other input in the key. Call tools within a custom read with `{ readOnly: true, dedupe: true }`; the same SQL/shell tool can also perform writes, so never mark a whole toolkit read-only. Leave mutations as ordinary `useTool` actions.
+
+`useQueryClient().prefetch(keyArray, readCallback, { readOnly: true })` prepares small known reads after the current view has rendered or on hover/focus. It shares the host's two-request speculative budget. Match the exact foreground query key. Never prefetch a mutation, login/polling action, provider sweep, `fetchAll` query, or an aggregate that fans out into more requests. Do not invent tool names to prepare a view. Older hosts safely fall back to uncached hook-local reads and skip prefetch.
+
+Caches belong to the host's in-memory account/environment/app/version/effective-permission scope. Do not add module-global or `localStorage` caches of user data. Writes and realtime events invalidate reads; logout, access loss, and updates retire scopes. Preserve the last successful snapshot on an ordinary network failure.
+
 ### Discovering database schema
 
 Before writing app code, inspect the database schema to know what properties exist:
@@ -367,7 +370,7 @@ Do NOT pass Notion-style wrappers (`{select: {name: "Todo"}}`) when upserting.
 - If a screen looks like a standalone microsite instead of a portal tool, it is too custom.
 - 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.
 - Never indicate selected items with a heavy left-border bar (e.g. `border-l-2 border-l-foreground` paired with a muted background). It looks dated and clashes with the portal chrome. Use a single subtle background change (`bg-muted` for selected, `hover:bg-muted/50` for hover) and let typography or an icon carry the rest of the state.
-- 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. The hook also exposes `setLoading` so the standard top-bar spinner reflects in-flight queries.
+- 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
 

package/package.json

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

package/src/command-specs/apps.js

@@ -516,7 +516,7 @@ function runtimeCallLabel(call) {
   return call?.op || 'runtime call';
 }
 
-function assertHarnessResult(result, route, databaseSlugs, mode = 'stub') {
+function assertHarnessResult(result, route, databaseSlugs, mode = 'stub', capabilities = {}) {
   const assertions = [];
   if (result.tool_error) {
     assertions.push({
@@ -557,7 +557,7 @@ function assertHarnessResult(result, route, databaseSlugs, mode = 'stub') {
   );
   for (const call of databaseQueries) {
     const databaseSlug = call?.args?.arguments?.database_slug;
-    if (databaseSlug && !declaredDatabaseSet.has(databaseSlug)) {
+    if (databaseSlug && !declaredDatabaseSet.has(databaseSlug) && capabilities.workspaceDatabases !== 'read') {
       assertions.push({
         ok: false,
         code: 'undeclared_database_query',
@@ -1842,6 +1842,7 @@ async function appsVerifyHandler(ctx) {
           route,
           declaredDatabaseSlugs(appConfig, manifest, route),
           mode,
+          manifest.capabilities || appConfig.capabilities || {},
         );
         return {
           ...result,
@@ -1867,6 +1868,7 @@ async function appsVerifyHandler(ctx) {
           route,
           declaredDatabaseSlugs(appConfig, manifest, route),
           mode,
+          manifest.capabilities || appConfig.capabilities || {},
         );
         results.push({
           route: route.slug,

package/template/app/page.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { getDocumentPreview, useDocuments, useNotis } from '@notis/sdk';
+import { getDocumentPreview, useDocuments, useNotis, Skeleton, ViewSkeleton } from '@notis/sdk';
 import { Badge } from '@/components/ui/badge';
 import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
 
@@ -8,7 +8,7 @@ export default function HomePage() {
   const { app, ready } = useNotis();
   // Documents come back normalized: plain property values, camelCase fields,
   // and typed content (contentMarkdown / contentBlocknote / plainText).
-  const { documents, loading } = useDocuments('items', { pageSize: 25 });
+  const { documents, loading, hasData, error, refetch } = useDocuments('items', { pageSize: 25 });
 
   return (
     <main className="notis-app-shell space-y-6">
@@ -16,9 +16,9 @@ export default function HomePage() {
         <CardHeader className="space-y-3">
           <Badge variant="secondary" className="w-fit">Installed app</Badge>
           <div className="space-y-2">
-            <CardTitle>{ready ? app?.name : 'Loading...'}</CardTitle>
+            <CardTitle>{ready ? app?.name : <Skeleton style={{ width: 160 }} />}</CardTitle>
             <CardDescription>
-              {ready ? app?.description : 'Loading app metadata...'}
+              {ready ? app?.description : <Skeleton style={{ width: 240 }} />}
             </CardDescription>
           </div>
         </CardHeader>
@@ -30,11 +30,12 @@ export default function HomePage() {
           <CardDescription>Use shadcn surfaces and portal tokens so the app feels native inside Notis.</CardDescription>
         </CardHeader>
         <CardContent>
+          {error && <p role="alert" className="mb-3 text-sm text-destructive">{error.message} <button onClick={refetch}>Retry</button></p>}
           {loading ? (
-            <p className="text-sm text-muted-foreground">Loading...</p>
-          ) : documents.length === 0 ? (
+            <ViewSkeleton variant="table" rows={4} />
+          ) : !hasData ? null : documents.length === 0 ? (
             <div className="rounded-xl border border-dashed border-border px-4 py-10 text-center text-sm text-muted-foreground">
-              No items yet. Deploy the app and create some.
+              No items yet. Create your first item.
             </div>
           ) : (
             <div className="space-y-3">

package/template/packages/sdk/src/components/MultiSelectActionBar.tsx

@@ -1,7 +1,9 @@
 'use client';
 
 import React, {
+  useEffect,
   useMemo,
+  useRef,
   useState,
   type CSSProperties,
   type ReactElement,
@@ -29,7 +31,7 @@ export interface MultiSelectActionBarProps {
 
 const containerBaseStyle: CSSProperties = {
   position: 'fixed',
-  bottom: '1rem',
+  bottom: 'calc(var(--notis-viewport-bottom, 0px) + max(1rem, var(--notis-safe-area-bottom, env(safe-area-inset-bottom, 0px))))',
   left: '50%',
   transform: 'translateX(-50%)',
   zIndex: 60,
@@ -46,6 +48,8 @@ const containerBaseStyle: CSSProperties = {
   pointerEvents: 'auto',
   fontSize: '13px',
   lineHeight: 1.2,
+  width: 'max-content',
+  maxWidth: 'calc(100% - 2rem)',
 };
 
 const countStyle: CSSProperties = {
@@ -115,6 +119,26 @@ export function MultiSelectActionBar({
   shortcutsEnabled = true,
   shortcutScope = 'collection',
 }: MultiSelectActionBarProps): ReactElement | null {
+  const barRef = useRef<HTMLDivElement>(null);
+  const visible = selectedCount > 0;
+  useEffect(() => {
+    const bar = barRef.current;
+    if (!visible || !bar) return;
+    // Also reaches a Portal launcher when an app renders inside a shadow root.
+    const root = document.documentElement;
+    const property = '--notis-bulk-actions-height';
+    const previous = root.style.getPropertyValue(property);
+    const update = () => root.style.setProperty(property, `${bar.getBoundingClientRect().height + 12}px`);
+    update();
+    const observer = typeof ResizeObserver === 'undefined' ? null : new ResizeObserver(update);
+    observer?.observe(bar);
+    return () => {
+      observer?.disconnect();
+      if (previous) root.style.setProperty(property, previous);
+      else root.style.removeProperty(property);
+    };
+  }, [visible]);
+
   const actionShortcuts = useMemo<ShortcutDefinition[]>(() => {
     return actions.flatMap((action): ShortcutDefinition[] => {
         if (!action.shortcut || action.disabled || action.pending) return [];
@@ -147,16 +171,33 @@ export function MultiSelectActionBar({
 
   return (
     <div
+      ref={barRef}
+      data-notis-bulk-actions
       role="toolbar"
       aria-label={`Bulk actions for ${selectedCount} selected ${countWord}`}
       className={className}
       style={composedStyle}
     >
-      <span style={countStyle}>{countLabel}</span>
-      {actions.length > 0 ? <span aria-hidden style={dividerStyle} /> : null}
-      {actions.map((action) => (
-        <ActionButton key={action.id} action={action} />
-      ))}
+      <style>{`
+        [data-notis-bulk-action-icon][data-has-shortcut] { display: none !important; }
+        @media (max-width: 639px) {
+          [data-notis-bulk-actions] { flex-wrap: wrap; width: calc(100% - 2rem) !important; }
+          [data-notis-bulk-count] { flex-basis: 100%; padding: 0.375rem 0.5rem !important; font-size: 14px !important; }
+          [data-notis-bulk-divider] { display: none; }
+          [data-notis-bulk-action-list] { width: 100%; }
+          [data-notis-bulk-actions] button { min-height: 48px; font-size: 16px !important; }
+          [data-notis-bulk-actions] kbd { display: none !important; }
+          [data-notis-bulk-action-icon][data-has-shortcut] { display: inline-flex !important; }
+        }
+        @media (hover: none) { [data-notis-bulk-actions] kbd { display: none !important; } }
+      `}</style>
+      <span data-notis-bulk-count style={countStyle}>{countLabel}</span>
+      {actions.length > 0 ? <span data-notis-bulk-divider aria-hidden style={dividerStyle} /> : null}
+      <div data-notis-bulk-action-list style={{ display: 'flex', minWidth: 0, overflowX: 'auto', overscrollBehaviorX: 'contain', gap: '0.25rem' }}>
+        {actions.map((action) => (
+          <ActionButton key={action.id} action={action} />
+        ))}
+      </div>
     </div>
   );
 }
@@ -192,8 +233,8 @@ function ActionButton({ action }: { action: MultiSelectAction }) {
       onBlur={() => setHover(false)}
       style={buttonStyle}
     >
-      {!action.shortcut && action.icon ? (
-        <span aria-hidden style={iconSlotStyle}>{action.icon}</span>
+      {action.icon ? (
+        <span data-notis-bulk-action-icon data-has-shortcut={action.shortcut ? '' : undefined} aria-hidden style={iconSlotStyle}>{action.icon}</span>
       ) : null}
       {display ? <kbd aria-hidden style={keycapStyle}>{display}</kbd> : null}
       <span>{action.pending ? `${action.label}…` : action.label}</span>

package/template/packages/sdk/src/components/Skeleton.tsx

@@ -0,0 +1,24 @@
+import type { CSSProperties } from 'react';
+
+/** Content-shaped placeholder. Never use it to replace a successful cached result. */
+export function Skeleton({ className, style }: { className?: string; style?: CSSProperties }) {
+  return <span aria-hidden="true" className={className} style={{ display: 'block', height: 16,
+    // Apps may define --muted as HSL channels or a complete CSS color. A
+    // neutral default remains visible with either token format and no theme.
+    borderRadius: 6, background: 'rgba(128,128,128,.18)', ...style }} />;
+}
+
+export function ViewSkeleton({ variant = 'table', rows = 5 }: {
+  variant?: 'table' | 'cards' | 'graph' | 'detail'; rows?: number;
+}) {
+  return <div role="status" aria-label="Loading content" aria-busy="true" data-notis-content-skeleton
+    style={{ width: '100%', display: 'grid', gap: 16, padding: 24 }}>
+    <Skeleton style={{ width: '32%', height: 28 }} />
+    {variant === 'graph' ? <Skeleton style={{ height: 420 }} /> :
+      <div style={{ display: 'grid', gap: 12, gridTemplateColumns: variant === 'cards' ? 'repeat(auto-fit,minmax(180px,1fr))' : '1fr' }}>
+        {Array.from({ length: rows }, (_, index) => <Skeleton key={index}
+          style={{ height: variant === 'cards' ? 112 : variant === 'detail' ? 20 : 44,
+            width: variant === 'detail' && index === rows - 1 ? '65%' : '100%' }} />)}
+      </div>}
+  </div>;
+}

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

@@ -1,6 +1,7 @@
 'use client';
 
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useCallback, useRef } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import type { CloudComputerFacts } from '../runtime';
 
@@ -11,6 +12,7 @@ export interface UseCloudComputerResult {
    */
   facts: CloudComputerFacts | null;
   loading: boolean;
+  isFetching: boolean;
   error: Error | null;
   /** Re-read the facts. The platform caches them for a few minutes. */
   refresh: () => Promise<void>;
@@ -47,51 +49,16 @@ const UNAVAILABLE: CloudComputerFacts = {
  */
 export function useCloudComputer(): UseCloudComputerResult {
   const runtime = useNotisRuntime();
-  const [facts, setFacts] = useState<CloudComputerFacts | null>(null);
-  // True from the first committed render: the initial read is already queued
-  // in an effect, and `{ loading: false, facts: null }` would flash a
-  // consumer's fallback branch before the answer arrives.
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const mounted = useRef(true);
-
-  useEffect(() => {
-    mounted.current = true;
-    return () => {
-      mounted.current = false;
-    };
-  }, []);
-
-  const read = useCallback(async (options?: { refresh?: boolean }) => {
-    if (!runtime?.cloudComputerFacts) {
-      setFacts(UNAVAILABLE);
-      setLoading(false);
-      return;
-    }
-
-    setLoading(true);
-    setError(null);
-    try {
-      const next = await runtime.cloudComputerFacts(options);
-      if (mounted.current) setFacts(next);
-    } catch (err) {
-      const e = err instanceof Error ? err : new Error(String(err));
-      if (mounted.current) {
-        setError(e);
-        // A refused or failed read is the same product state as a host that
-        // cannot answer: the app shows its fallback instead of an error.
-        setFacts(UNAVAILABLE);
-      }
-    } finally {
-      if (mounted.current) setLoading(false);
-    }
-  }, [runtime]);
-
-  useEffect(() => {
-    void read();
-  }, [read]);
-
-  const refresh = useCallback(() => read({ refresh: true }), [read]);
-
-  return { facts, loading, error, refresh };
+  const explicitRefresh = useRef(false);
+  const query = useQuery<CloudComputerFacts>(['cloud-computer-facts'], async () => {
+    const refresh = explicitRefresh.current;
+    explicitRefresh.current = false;
+    return runtime?.cloudComputerFacts ? runtime.cloudComputerFacts(refresh ? { refresh: true } : undefined) : UNAVAILABLE;
+  }, { readOnly: true });
+  const refresh = useCallback(async () => {
+    explicitRefresh.current = true;
+    await query.refetch();
+  }, [query.refetch]);
+  return { facts: query.data ?? (query.error ? UNAVAILABLE : null), loading: query.loading,
+    isFetching: query.isFetching, error: query.error, refresh };
 }

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useState } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import { normalizeDatabaseProperty, optionalString } from '../documents';
 import type { DatabaseProperty } from '../runtime';
@@ -22,6 +22,8 @@ export interface UseDatabaseSchemaResult {
   description: string | null;
   properties: DatabaseProperty[];
   loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
   error: Error | null;
   refetch: () => void;
 }
@@ -29,57 +31,19 @@ export interface UseDatabaseSchemaResult {
 /** Fetch a database's schema (normalized properties + metadata). */
 export function useDatabaseSchema(databaseSlug: string): UseDatabaseSchemaResult {
   const runtime = useNotisRuntime();
-  const [name, setName] = useState<string | null>(null);
-  const [description, setDescription] = useState<string | null>(null);
-  const [properties, setProperties] = useState<DatabaseProperty[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const refetch = useCallback(() => {
-    setFetchKey((key) => key + 1);
-  }, []);
-
-  useEffect(() => {
-    if (!runtime) {
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    runtime
-      .callTool<GetDatabaseResult>('LOCAL_NOTIS_DATABASE_GET_DATABASE', {
-        database_slug: databaseSlug,
-      })
-      .then((result) => {
-        if (cancelled) return;
-        const message = result.error ?? result.message;
-        if (!result.database && message) {
-          throw new Error(message);
-        }
-        setName(optionalString(result.database?.name));
-        setDescription(optionalString(result.database?.description));
-        const rawProperties = result.database?.schema?.properties ?? [];
-        setProperties(
-          rawProperties
-            .map(normalizeDatabaseProperty)
-            .filter((property): property is DatabaseProperty => Boolean(property)),
-        );
-        setLoading(false);
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
+  const query = useQuery(['database-schema', databaseSlug], async () => {
+    const result = await runtime!.callTool<GetDatabaseResult>('LOCAL_NOTIS_DATABASE_GET_DATABASE', {
+      database_slug: databaseSlug,
+    }, { dedupe: true, readOnly: true });
+    if (!result.database) throw new Error(result.error || result.message || 'Database not found');
+    return {
+      name: optionalString(result.database.name),
+      description: optionalString(result.database.description),
+      properties: (result.database.schema?.properties ?? []).map(normalizeDatabaseProperty)
+        .filter((property): property is DatabaseProperty => Boolean(property)),
     };
-  }, [runtime, databaseSlug, fetchKey]);
-
-  return { name, description, properties, loading, error, refetch };
+  }, { readOnly: true });
+  return { ...query, name: query.data?.name ?? null, description: query.data?.description ?? null,
+    properties: query.data?.properties ?? EMPTY_PROPERTIES };
 }
+const EMPTY_PROPERTIES: DatabaseProperty[] = [];

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

@@ -36,7 +36,7 @@ export function useDatabaseSubscription(
 ): UseDatabaseSubscriptionResult {
   const runtime = useNotisRuntime();
   const { subscribe = true, ...documentOptions } = options;
-  const { documents, loading, error, refetch } = useDocuments(databaseSlug, documentOptions);
+  const { documents, loading, isFetching, hasData, error, refetch } = useDocuments(databaseSlug, documentOptions);
   const [live, setLive] = useState(false);
 
   const refetchRef = useRef(refetch);
@@ -72,5 +72,5 @@ export function useDatabaseSubscription(
     };
   }, [runtime, databaseSlug, enabled]);
 
-  return { documents, rows: documents, loading, error, refetch, live };
+  return { documents, rows: documents, loading, isFetching, hasData, error, refetch, live };
 }

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useState } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import { normalizeDocumentRecord } from '../documents';
 import type { DocumentRecord } from '../runtime';
@@ -19,6 +19,8 @@ export interface UseDocumentOptions {
 export interface UseDocumentResult {
   document: DocumentRecord | null;
   loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
   error: Error | null;
   refetch: () => void;
 }
@@ -29,50 +31,13 @@ export function useDocument(
   options: UseDocumentOptions = {},
 ): UseDocumentResult {
   const runtime = useNotisRuntime();
-  const [document, setDocument] = useState<DocumentRecord | null>(null);
-  const [loading, setLoading] = useState(Boolean(documentId));
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const enabled = options.enabled !== false && Boolean(documentId);
-
-  const refetch = useCallback(() => {
-    setFetchKey((key) => key + 1);
-  }, []);
-
-  useEffect(() => {
-    if (!runtime || !enabled || !documentId) {
-      setDocument(null);
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    runtime
-      .callTool<GetDocumentResult>('LOCAL_NOTIS_DATABASE_GET_DOCUMENT', {
-        document_id: documentId,
-      })
-      .then((result) => {
-        if (cancelled) return;
-        if (!result.document) {
-          throw new Error(result.error ?? result.message ?? 'Document not found');
-        }
-        setDocument(normalizeDocumentRecord(result.document));
-        setLoading(false);
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [runtime, documentId, enabled, fetchKey]);
-
-  return { document, loading, error, refetch };
+  const query = useQuery<DocumentRecord>(['document', documentId ?? null], async () => {
+    if (!runtime || !documentId) throw new Error('Document not found');
+    const result = await runtime.callTool<GetDocumentResult>('LOCAL_NOTIS_DATABASE_GET_DOCUMENT', {
+      document_id: documentId,
+    }, { dedupe: true, readOnly: true });
+    if (!result.document) throw new Error(result.error ?? result.message ?? 'Document not found');
+    return normalizeDocumentRecord(result.document);
+  }, { readOnly: true, enabled: options.enabled !== false && Boolean(documentId) });
+  return { document: query.data ?? null, loading: query.loading, isFetching: query.isFetching, hasData: query.hasData, error: query.error, refetch: query.refetch };
 }

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect, useState } from 'react';
+import { useQuery } from './useQuery';
 import { useNotisRuntime } from '../provider';
 import { normalizeDocumentRecord } from '../documents';
 import type { DocumentRecord, QueryFilter } from '../runtime';
@@ -25,6 +25,8 @@ export interface UseDocumentsOptions {
 export interface UseDocumentsResult {
   documents: DocumentRecord[];
   loading: boolean;
+  isFetching: boolean;
+  hasData: boolean;
   error: Error | null;
   refetch: () => void;
 }
@@ -44,78 +46,36 @@ export function useDocuments(
   options: UseDocumentsOptions = {},
 ): UseDocumentsResult {
   const runtime = useNotisRuntime();
-  const [documents, setDocuments] = useState<DocumentRecord[]>([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<Error | null>(null);
-  const [fetchKey, setFetchKey] = useState(0);
-
-  const enabled = options.enabled !== false;
-  const filterKey = JSON.stringify(options.filter ?? null);
-
-  const refetch = useCallback(() => {
-    setFetchKey((key) => key + 1);
-  }, []);
-
-  useEffect(() => {
-    if (!runtime || !enabled) {
-      setLoading(false);
-      return;
-    }
-
-    let cancelled = false;
-    setLoading(true);
-    setError(null);
-
-    const filter = filterKey === 'null' ? null : (JSON.parse(filterKey) as QueryFilter);
-
-    const fetchDocuments = async (): Promise<unknown[]> => {
+  const query = useQuery<DocumentRecord[]>(
+    ['documents', databaseSlug, options.filter ?? null, options.pageSize ?? null, options.offset ?? 0, Boolean(options.fetchAll)],
+    async () => {
+      if (!runtime) throw new Error('Notis runtime not available');
       const allDocuments: unknown[] = [];
       let offset = options.offset ?? 0;
-
       while (true) {
         const result = await runtime.callTool<QueryDatabaseResult>('LOCAL_NOTIS_DATABASE_QUERY', {
           database_slug: databaseSlug,
           query: {
-            ...(filter ?? {}),
+            ...(options.filter ?? {}),
             ...(options.pageSize !== undefined ? { page_size: options.pageSize } : {}),
           },
           ...(offset > 0 ? { offset } : {}),
-        });
+        }, { dedupe: true, readOnly: true });
         const message = result.error ?? result.message;
-        if (!result.documents && message) {
-          throw new Error(message);
-        }
+        if (!result.documents && message) throw new Error(message);
         allDocuments.push(...(result.documents ?? []));
-        if (!options.fetchAll || !result.has_more) return allDocuments;
-
+        if (!options.fetchAll || !result.has_more) break;
         const nextOffset = result.next_offset;
         if (typeof nextOffset !== 'number' || nextOffset <= offset) {
           throw new Error('Database query returned an invalid pagination offset');
         }
         offset = nextOffset;
       }
-    };
-
-    fetchDocuments()
-      .then((result) => {
-        if (cancelled) return;
-        setDocuments(
-          result
-            .map(normalizeDocumentRecord)
-            .filter((document) => document.id),
-        );
-        setLoading(false);
-      })
-      .catch((err) => {
-        if (cancelled) return;
-        setError(err instanceof Error ? err : new Error(String(err)));
-        setLoading(false);
-      });
-
-    return () => {
-      cancelled = true;
-    };
-  }, [runtime, databaseSlug, enabled, fetchKey, filterKey, options.fetchAll, options.offset, options.pageSize]);
-
-  return { documents, loading, error, refetch };
+      return allDocuments.map(normalizeDocumentRecord).filter((document) => document.id);
+    },
+    { readOnly: true, enabled: options.enabled },
+  );
+  return { documents: query.data ?? EMPTY_DOCUMENTS, loading: query.loading, isFetching: query.isFetching, hasData: query.hasData, error: query.error, refetch: query.refetch };
 }
+
+const EMPTY_DOCUMENTS: DocumentRecord[] = [];

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

@@ -0,0 +1,71 @@
+'use client';
+
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import { useNotisRuntime } from '../provider';
+import { createQueryClient, queryKey } from '../queryCache';
+
+export interface UseQueryOptions {
+  /** Required acknowledgement: only idempotent reads may run on mount or prefetch. */
+  readOnly: true;
+  enabled?: boolean;
+  staleTimeMs?: number;
+}
+
+export interface UseQueryResult<T> {
+  data: T | undefined;
+  hasData: boolean;
+  loading: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  refetch: () => Promise<void>;
+}
+
+/** Cached read callback; scope and lifetime are provided by the host, never by app globals. */
+export function useQuery<T>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions): UseQueryResult<T> {
+  const runtime = useNotisRuntime();
+  // Older hosts deliberately get a hook-local cache: no cross-runtime/account reuse.
+  const fallback = useMemo(() => createQueryClient(), [runtime]);
+  const client = runtime?.queryClient ?? fallback;
+  const cacheKey = queryKey(key);
+  const enabled = Boolean(runtime) && options.enabled !== false && options.readOnly === true;
+  const readRef = useRef(read);
+  useLayoutEffect(() => { readRef.current = read; });
+  const subscribe = useCallback((listener: () => void) => enabled ? client.subscribe(cacheKey, listener) : () => {}, [cacheKey, client, enabled]);
+  const snapshot = useSyncExternalStore(subscribe, () => client.getSnapshot<T>(cacheKey), () => client.getSnapshot<T>(cacheKey));
+  const fetch = useCallback(() => {
+    const capturedRead = readRef.current;
+    return client.fetch(cacheKey, capturedRead, { staleTimeMs: options.staleTimeMs });
+  }, [cacheKey, client, options.staleTimeMs]);
+  useEffect(() => {
+    if (!enabled) return;
+    void fetch().catch(() => {}); // Error belongs to the snapshot; no unhandled rejection.
+  }, [enabled, fetch, snapshot.invalidation]);
+  const refetch = useCallback(async () => {
+    if (!enabled) return;
+    client.invalidate(cacheKey);
+    await fetch().catch(() => {});
+  }, [cacheKey, client, enabled, fetch]);
+  return {
+    data: enabled ? snapshot.data : undefined,
+    hasData: enabled && snapshot.hasData,
+    loading: enabled && !snapshot.hasData && !snapshot.error,
+    isFetching: enabled && snapshot.isFetching,
+    error: enabled ? snapshot.error : null,
+    refetch,
+  };
+}
+
+/** Opt-in preparation for small, known read queries. Never use for writes or full-database crawls. */
+export function useQueryClient(): {
+  invalidate(key?: readonly unknown[]): void;
+  prefetch<T>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions): Promise<T | undefined>;
+} {
+  const runtime = useNotisRuntime();
+  return useMemo(() => ({
+    invalidate: (key?: readonly unknown[]) => runtime?.queryClient?.invalidate(key ? queryKey(key) : undefined),
+    prefetch: <T,>(key: readonly unknown[], read: () => Promise<T>, options: UseQueryOptions) => {
+      if (!runtime?.queryClient || options.enabled === false || options.readOnly !== true) return Promise.resolve(undefined);
+      return runtime.queryClient.prefetch(queryKey(key), read, { staleTimeMs: options.staleTimeMs });
+    },
+  }), [runtime]);
+}

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

@@ -0,0 +1,12 @@
+'use client';
+
+import { useNotisRuntime } from '../provider';
+import { useQuery, type UseQueryOptions } from './useQuery';
+
+/** An explicitly identified read-only tool, cached by tool name and exact arguments. */
+export function useToolQuery<T = unknown>(name: string, args: Record<string, unknown> = {}, options: UseQueryOptions) {
+  const runtime = useNotisRuntime();
+  return useQuery<T>(['tool', name, args], () => runtime!.callTool<T>(name, args, {
+    readOnly: true, dedupe: true,
+  }), options);
+}

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

@@ -1,6 +1,6 @@
 'use client';
 
-import { useCallback, useEffect } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef } from 'react';
 import { useNotisRuntime } from '../provider';
 
 interface TopBarSearchOptions {
@@ -24,8 +24,9 @@ interface TopBarSearchActions {
  * While the component is mounted, typing in the top bar calls `onChange`,
  * pressing Enter calls `onSubmit`, and the `value` prop drives the input.
  *
- * Call `setLoading(true)` to show the standard spinner in the top bar while a
- * query is running; `setLoading(false)` restores the search icon.
+ * Use `setLoading(true)` only for an explicitly submitted search action, then
+ * restore the icon with `setLoading(false)`. Automatic reads use content
+ * skeletons initially and refresh populated content silently.
  *
  * Without a portal runtime, this hook is a safe no-op.
  *
@@ -42,21 +43,28 @@ interface TopBarSearchActions {
  * });
  * ```
  *
- * Stabilize `onChange` and `onSubmit` with `useCallback` to avoid re-registering
- * on every render.
+ * Callback refs retain the latest committed handlers without re-registering
+ * search on every app render. Inline callbacks are safe.
  */
 export function useTopBarSearch(opts: TopBarSearchOptions): TopBarSearchActions {
   const runtime = useNotisRuntime();
   const { value, onChange, placeholder, onSubmit } = opts;
+  const callbacks = useRef({ onChange, onSubmit });
+  useLayoutEffect(() => { callbacks.current = { onChange, onSubmit }; });
+  const hasSubmit = Boolean(onSubmit);
 
   useEffect(() => {
     const register = runtime?.registerTopBarSearch;
     if (!register) return;
-    register({ onChange, placeholder, onSubmit });
+    register({
+      onChange: (next) => callbacks.current.onChange(next),
+      placeholder,
+      onSubmit: hasSubmit ? () => callbacks.current.onSubmit?.() : undefined,
+    });
     return () => {
       register(null);
     };
-  }, [runtime, onChange, placeholder, onSubmit]);
+  }, [runtime, placeholder, hasSubmit]);
 
   useEffect(() => {
     runtime?.setTopBarSearchValue?.(value);

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

@@ -10,6 +10,10 @@
 export { NotisProvider, useNotisRuntime } from './provider';
 
 // Hooks
+export { useQuery, useQueryClient } from './hooks/useQuery';
+export type { UseQueryOptions, UseQueryResult } from './hooks/useQuery';
+export { createQueryClient, createPrefetchQueue, queryKey } from './queryCache';
+export type { NotisQueryClient, QuerySnapshot, QueryFetchOptions } from './queryCache';
 export { useNotis } from './hooks/useNotis';
 export { useDocuments } from './hooks/useDocuments';
 export type { UseDocumentsOptions, UseDocumentsResult } from './hooks/useDocuments';
@@ -143,3 +147,7 @@ export type {
   ToolCallOptions,
   ToolInputSchema,
 } from './runtime';
+
+export { useToolQuery } from './hooks/useToolQuery';
+
+export { Skeleton, ViewSkeleton } from './components/Skeleton';

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

@@ -0,0 +1,162 @@
+/** In-memory read snapshots. The host owns the lifetime and authorization scope. */
+export interface QuerySnapshot<T = unknown> {
+  data: T | undefined;
+  hasData: boolean;
+  isFetching: boolean;
+  error: Error | null;
+  updatedAt: number;
+  invalidation: number;
+}
+
+export interface QueryFetchOptions {
+  staleTimeMs?: number;
+  force?: boolean;
+}
+
+export interface NotisQueryClient {
+  getSnapshot<T>(key: string): QuerySnapshot<T>;
+  subscribe(key: string, listener: () => void): () => void;
+  fetch<T>(key: string, read: () => Promise<T>, options?: QueryFetchOptions): Promise<T>;
+  prefetch<T>(key: string, read: () => Promise<T>, options?: QueryFetchOptions): Promise<T>;
+  invalidate(key?: string): void;
+  clear(): void;
+  /** Host-only: permanently retire a revoked security scope. */
+  dispose?(): void;
+  getRevision?(): number;
+}
+
+const EMPTY: QuerySnapshot = Object.freeze({
+  data: undefined, hasData: false, isFetching: false, error: null, updatedAt: 0, invalidation: 0,
+});
+
+/** Stable keys distinguish filters, pagination, and resource identities. */
+export function queryKey(value: unknown): string {
+  if (value instanceof Date) return JSON.stringify(value.toISOString());
+  if (Array.isArray(value)) return `[${value.map(queryKey).join(',')}]`;
+  if (value && typeof value === 'object') {
+    const record = value as Record<string, unknown>;
+    return `{${Object.keys(record).filter((key) => record[key] !== undefined).sort()
+      .map((key) => `${JSON.stringify(key)}:${queryKey(record[key])}`).join(',')}}`;
+  }
+  return JSON.stringify(value) ?? 'null';
+}
+
+/** One shared queue can bound descriptor and data speculation together. */
+export function createPrefetchQueue(concurrency = 2) {
+  let active = 0;
+  const waiting: Array<() => void> = [];
+  function drain() {
+    while (active < concurrency && waiting.length) waiting.shift()!();
+  }
+  return <T>(read: () => Promise<T>): Promise<T> => new Promise<T>((resolve, reject) => {
+    waiting.push(() => {
+      active += 1;
+      Promise.resolve().then(read).then(resolve, reject).finally(() => { active -= 1; drain(); });
+    });
+    drain();
+  });
+}
+
+type Entry = {
+  snapshot: QuerySnapshot;
+  listeners: Set<() => void>;
+  generation: number;
+  pending?: Promise<unknown>;
+};
+
+export function createQueryClient(options: {
+  maxEntries?: number;
+  now?: () => number;
+  schedule?: ReturnType<typeof createPrefetchQueue>;
+} = {}): NotisQueryClient {
+  const entries = new Map<string, Entry>();
+  const now = options.now ?? Date.now;
+  const maxEntries = options.maxEntries ?? 100;
+  const schedule = options.schedule ?? createPrefetchQueue(2);
+  let epoch = 0;
+  let disposed = false;
+  let revision = 0;
+
+  function prune(keep?: string) {
+    for (const [oldKey, old] of entries) {
+      if (entries.size <= maxEntries) break;
+      if (oldKey !== keep && !old.listeners.size && !old.pending) entries.delete(oldKey);
+    }
+  }
+  function entry(key: string): Entry {
+    let value = entries.get(key);
+    if (!value) {
+      value = { snapshot: EMPTY, listeners: new Set(), generation: 0 };
+      entries.set(key, value);
+    }
+    // Only operations, not getSnapshot during render, update the LRU.
+    entries.delete(key);
+    entries.set(key, value);
+    prune(key);
+    return value;
+  }
+  function publish(value: Entry, snapshot: QuerySnapshot) {
+    value.snapshot = snapshot;
+    for (const listener of value.listeners) listener();
+  }
+  const client: NotisQueryClient = {
+    getSnapshot<T>(key: string) { return (entries.get(key)?.snapshot ?? EMPTY) as QuerySnapshot<T>; },
+    subscribe(key, listener) {
+      const value = entry(key);
+      value.listeners.add(listener);
+      return () => { value.listeners.delete(listener); prune(); };
+    },
+    fetch<T>(key: string, read: () => Promise<T>, fetchOptions: QueryFetchOptions = {}) {
+      if (disposed) return Promise.reject(new Error('App query scope is no longer available.'));
+      const value = entry(key);
+      if (value.pending) return value.pending as Promise<T>;
+      if (!fetchOptions.force && value.snapshot.hasData && value.snapshot.updatedAt > 0
+        && now() - value.snapshot.updatedAt < (fetchOptions.staleTimeMs ?? 30_000)) {
+        return Promise.resolve(value.snapshot.data as T);
+      }
+      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) => {
+        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(); });
+      value.pending = request;
+      publish(value, { ...value.snapshot, isFetching: true, error: null });
+      return request;
+    },
+    prefetch<T>(key: string, read: () => Promise<T>, fetchOptions?: QueryFetchOptions) {
+      const requestEpoch = epoch;
+      return schedule(() => {
+        if (epoch !== requestEpoch) throw new Error('App query scope was cleared.');
+        return client.fetch(key, read, fetchOptions);
+      });
+    },
+    getRevision: () => revision,
+    invalidate(key) {
+      revision += 1;
+      for (const [entryKey, value] of entries) {
+        if (key !== undefined && entryKey !== key) continue;
+        value.generation += 1;
+        value.pending = undefined;
+        publish(value, { ...value.snapshot, updatedAt: 0, isFetching: false, invalidation: value.snapshot.invalidation + 1 });
+      }
+    },
+    dispose() { disposed = true; client.clear(); },
+    clear() {
+      revision += 1;
+      epoch += 1;
+      for (const value of entries.values()) {
+        value.generation += 1;
+        value.pending = undefined;
+        publish(value, { ...EMPTY, invalidation: value.snapshot.invalidation + 1 });
+      }
+      for (const [key, value] of entries) if (!value.listeners.size) entries.delete(key);
+    },
+  };
+  return client;
+}

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

@@ -8,6 +8,7 @@
  */
 
 import type { ComponentType } from 'react';
+import type { NotisQueryClient } from './queryCache';
 
 // ---------------------------------------------------------------------------
 // Database types
@@ -106,6 +107,8 @@ export interface ToolDescriptor {
 }
 
 export interface ToolCallOptions {
+  /** Explicitly identifies an idempotent read; never set on a mutation. */
+  readOnly?: boolean;
   /**
    * Coalesce an identical in-flight call. Only opt in for idempotent reads;
    * mutations must execute once per invocation.
@@ -359,6 +362,8 @@ export interface CloudComputerFacts {
 }
 
 export interface NotisRuntime {
+  /** Optional host-scoped in-memory read cache. Older hosts remain supported. */
+  queryClient?: NotisQueryClient;
   app: AppDescriptor;
   route: RouteDescriptor;
   databases: DatabaseDescriptor[];