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

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

@@ -0,0 +1,164 @@
+## How Apps Are Built
+
+All Notis apps are built using the Notis CLI, either locally in a repo workspace or inside a Vercel Sandbox. The platform contract is the same in both cases:
+- the app is a Vite + React project
+- the app uses `@notis/sdk`
+- 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
+
+```
+Notis CLI (local workspace or Vercel Sandbox)
+  -> Vite + React project with @notis/sdk
+  -> notis apps init / build / verify / create / link / pull / deploy
+  -> ES module bundle (app.js + app.css) + manifest
+  -> Portal renders as React component with real tools/databases
+```
+
+`deploy` updates the linked installed app for the current account or team. After the user explicitly confirms the App Details page is ready, `apps publish --confirm-ready` submits that deployed version to the Team or Public Store review flow.
+
+### Key Components
+
+1. **@notis/sdk** (`packages/sdk/`) -- SDK for app developers
+   - `@notis/sdk` -- NotisProvider, runtime hooks, editors, selection helpers, and shortcut primitives
+   - `@notis/sdk/interactions` -- headless collection actions and interaction types
+   - `@notis/sdk/config` -- `defineNotisApp()` for notis.config.ts
+   - `@notis/sdk/vite` -- `notisViteConfig()` for vite.config.ts
+   - `@notis/sdk/styles.css` -- shadow-safe app shell styles and base app-surface classes
+
+2. **CLI** (`packages/cli/src/command-specs/apps.js`) -- release delivery uses init, build, verify, create, deploy, link, pull, doctor, and list
+
+3. **Server** (`server/routers/portal_views/`) -- Returns signed bundle URLs, proxies tool calls
+
+4. **Portal** (`portal/src/components/apps/`) -- Renders app bundles as React components via AppViewRenderer
+
+### Runtime Bridge
+
+Apps communicate with the platform through the `NotisRuntime` interface, provided by the portal via React context:
+
+- **Portal**: the portal creates a real `NotisRuntime` and passes it as a prop to `NotisProvider`. All calls go to `/portal_views/runtime_query` via fetch with the user's JWT.
+- The portal mounts the app inside a shadow-scoped content surface and injects the runtime before app mount. There is no supported window-global runtime fallback.
+
+App code never accesses the runtime directly -- it uses SDK hooks (`useTool`, `useTools`, `useNotis`, etc.) which read from the `NotisProvider` context.
+
+## Manifest Format
+
+Generated by `npx --package @notis_ai/cli@latest -- notis apps build` at `.notis/output/manifest.json`:
+
+```json
+{
+  "version": 1,
+  "spec_version": 4,
+  "app": { "name": "My App", "slug": "my-app", "title": "My App", "description": "...", "icon": "phosphor:..." },
+  "routes": [
+    {
+      "path": "/",
+      "slug": "index",
+      "name": "Dashboard",
+      "icon": "phosphor:squares-four",
+      "default": true,
+      "export_name": "index",
+      "collection": null
+    }
+  ],
+  "bundle": {
+    "js": "bundle/app.js",
+    "css": "bundle/app.css"
+  },
+  "databases": ["tasks", { "slug": "templates", "seed_documents": true }],
+  "tools": ["LOCAL_NOTIS_DATABASE_QUERY"]
+}
+```
+
+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.
+
+## Database Schema
+
+### apps table
+
+| Column | Type | Description |
+|---|---|---|
+| id | uuid PK | App ID |
+| user_id | uuid FK | Owner |
+| team_id | uuid FK | Team (nullable) |
+| name | text | Display name |
+| slug | text UNIQUE | URL slug |
+| description | text | App description |
+| icon | text | Phosphor icon (e.g. "phosphor:list") |
+| status | text | draft, active, archived |
+| visibility | text | private, team |
+| manifest | jsonb | Latest deployed manifest |
+| current_version | integer | Version counter |
+| source_listing_id | uuid FK | Source App Store listing for installed store apps; cleared when submitted as a derivative |
+| installed_snapshot | jsonb | Store-installed baseline used for update/reset comparison |
+| customization_overlay | jsonb | User changes over the installed store baseline |
+| update_status | text | up_to_date, update_available, needs_resolution, update_failed |
+| bundled_automation_ids | uuid[] | Linked automations |
+| bundled_skill_ids | uuid[] | Linked skills |
+
+### databases ownership
+
+Every row in the `databases` table carries `owner_app_id` (uuid FK to
+`apps.id`, `ON DELETE CASCADE`): a database belongs to exactly one app, and
+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)
+
+Files stored in `app-code` bucket at `{app_id}/v{version}/`:
+- `manifest.json`
+- `bundle/app.js`
+- `bundle/app.css`
+
+Editable source snapshots are stored in the private `app-source` bucket at
+`{app_id}/v{version}/`. Portal App Store listing screenshots are uploaded to
+the public `app-listing-assets` bucket before submission.
+
+### Related tables
+
+- **databases** -- Apps reference these rows by slug. Schema lives on the database row (`schema_metadata` / `original_fields`), not in the app manifest.
+- **documents** -- `database_id` links to databases. Properties in `properties` jsonb.
+- **app_store_listings** -- Snapshots for publishing to the app store.
+- **app_submissions** -- Portal review submissions keyed to an app source version and registry slug.
+
+## Server Endpoints
+
+| Endpoint | Method | Purpose |
+|---|---|---|
+| `/portal_views/get` | GET | Route detail + runtime descriptor with signed bundle URLs |
+| `/portal_views/runtime_query` | POST | Proxy tool calls and DB operations |
+| `/portal_views/collection_items` | GET | List collection items |
+| `/portal_views/collection_tree` | GET | List normalized collection tree nodes for a tree sidebar route |
+| `/portal_views/collection_tree/create` | POST | Create a root or child collection row from the sidebar |
+| `/portal_views/collection_tree/rename` | POST | Rename a collection tree item inline |
+| `/portal_views/collection_tree/delete` | POST | Delete a collection tree item from the sidebar |
+| `/portal_apps/list` | GET | List apps |
+| `/portal_apps/get` | GET | Get app detail |
+| `/portal_apps/publish` | POST | Submit a deployed app source snapshot for public store review |
+| `/portal_apps/listing_assets/upload` | POST | Legacy pre-manifest screenshot upload; do not use for current manifest-media workflows |
+| `/portal_apps/submissions` | GET/PATCH | List or edit App Store submissions |
+| `/portal_apps/submissions/withdraw` | POST | Close a pending App Store submission |
+| `/cli_tools` | POST | CLI tool execution (save_app_files, create_app, etc.) |

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

@@ -0,0 +1,165 @@
+## 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. 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:
+
+```ts
+routes: [
+  {
+    path: '/',
+    slug: 'notes',
+    name: 'Notes',
+    icon: 'phosphor:note-pencil',
+    default: true,
+    collection: {
+      database: 'notes',
+      titleProperty: 'Title',
+      parentProperty: 'Parent note',
+      sidebar: {
+        mode: 'tree',
+        allowCreate: true,
+      },
+    },
+  },
+]
+```
+
+Use the same page template for the root Notes route and collection/sub-collection detail states. The portal sidebar injects live collection items under the static route row when `collection.sidebar.mode === 'tree'`.
+
+For arbitrary app-owned resources that are not Notis collection rows, set `resourceDeepLinks: true` on the route. Read the decoded `?resource=` identifier from `useNotis().resourceId`, and link between routes with `toRoute('/inbox', { resourceId })`. Keep collection links on `?item=`. Publish external preview/source links as the resource `url`; the host separately supplies the exact Notis review link as `active_resource.view_url` for opted-in routes. Handle missing or deleted identifiers with a safe view-level fallback.
+
+### Step 2: Build pages
+
+Standard React pages in `app/`. Use generic SDK tool hooks for data and build on top of the scaffolded flat components and portal shell classes (`notis-app-shell` for ordinary pages, `notis-app-split` for list-plus-detail pages, `notis-app-surface` for a flat panel):
+
+```tsx
+import { useDocuments, ViewSkeleton } from '@notis/sdk';
+import { Card } from '@/components/ui/card';
+
+export default function TasksPage() {
+  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, 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. |
+| 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:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_LIST_DATABASES --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"social_media_calendar"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"social-media-calendar-db-id","query":{"page_size":1}}'
+```
+
+Prefer the database `id` returned by `LOCAL_NOTIS_DATABASE_LIST_DATABASES` or `LOCAL_NOTIS_DATABASE_GET_DATABASE` when calling `LOCAL_NOTIS_DATABASE_QUERY`; use `database_slug` only as a fallback.
+
+Use `LOCAL_NOTIS_DATABASE_GET_DATABASE` through `useTool` when an app needs schema detail at runtime. Keep database-specific result and property helper types inside the app code.
+For document writes, declare the generated canonical tool for the target database, such as `LOCAL_NOTIS_DATABASE_UPSERT_TASKS`, and call it through `useTool`. Pass flat property values; the server wraps them:
+
+```tsx
+const upsertTask = useTool<Record<string, unknown>, { document?: { id: string } }>('LOCAL_NOTIS_DATABASE_UPSERT_TASKS');
+
+await upsertTask.call({
+  title: 'My Task',
+  Status: 'Todo',
+  Priority: 'P1',
+  Due: '2025-04-01',
+  Done: false,
+  Count: 5,
+});
+```
+
+Do NOT pass Notion-style wrappers (`{select: {name: "Todo"}}`) when upserting.
+
+### Step 3: Root layout
+
+```tsx
+import { NotisProvider } from '@notis/sdk';
+import '@notis/sdk/styles.css';
+import './globals.css';
+
+export default function AppShell({ children }: { children: React.ReactNode }) {
+  return <NotisProvider>{children}</NotisProvider>;
+}
+```

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

@@ -0,0 +1,99 @@
+## 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

@@ -0,0 +1,61 @@
+## SDK Hook Reference
+
+All hooks and components below are imported from `@notis/sdk`. `NotisProvider`
+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. 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 |
+| `useDatabaseSubscription(slug, opts?)` | `(slug: string, opts?) => { rows, documents, loading, error, refetch, live }` | Query a database and refetch it when its rows change. `live` is false on hosts without a change feed (temporary test harness, vite preview) -- keep a manual refresh for those |
+| `useHandover()` | `() => { handover, pending, error, available }` | Open manager chat with app/resource context plus an optional starter prompt or declared skill. Omit `prompt` for a context-only composer. `available` is false on hosts with no chat -- fall back to a copyable prompt |
+| `useCloudComputer()` | `() => { facts, loading, error, refresh }` | Read-only cloud computer facts: sandbox existence/status and whether the GitHub CLI is signed in. Requires `capabilities.cloudComputer: 'read'` plus the user's approval; `facts.available === false` means answer from the app's own fallback |
+| `useActiveResource(resource)` | `(ContextResource \| null) => void` | Publish the record currently open in the app so manager handover and context menus stay grounded |
+| `useCollectionInteractions(opts)` | `(opts) => CollectionInteractionController` | Keyboard navigation, active-row state, range/toggle selection, marquee selection, and action dispatch for collection UIs |
+| `useShortcuts(definitions, opts?)` | `(definitions, opts?) => void` | Register scoped keyboard shortcuts. Editable targets are ignored unless explicitly allowed; use `ShortcutHints` to display them |
+| `MarkdownEditor` | `(NotisMarkdownEditorProps) => ReactElement` | Use the host editor with app-owned persistence, stable `resourceKey`, revision-aware `onSave`, and optional `onUploadFile` returning a durable URL |
+| `NotisSelectionBoundary` | `(NotisSelectionBoundaryProps) => ReactElement` | Attach structured, explicitly untrusted app/resource/selection context to selected content and copy operations |
+| `SelectionCheckbox` / `SelectionMarquee` | components | Standard selection controls backed by `useCollectionInteractions` |
+| `MultiSelectActionBar` | component | Standard bulk actions with pending/disabled state and shortcut support |
+
+Import headless collection action types and helpers from
+`@notis/sdk/interactions`. Keep an open detail view synchronized with
+`useActiveResource`, and wrap its selectable content in
+`NotisSelectionBoundary` so the manager receives both the active record and the
+user's exact selection. For `MarkdownEditor`, keep `resourceKey` stable per
+record, pass the latest revision back from `onSave`, reject revision conflicts
+instead of overwriting newer data, and implement `onUploadFile` whenever the
+editor should accept media or file blocks.
+
+### App configuration additions
+
+- `toolBindings` is only for provider-generated public tool names whose upstream
+  action cannot be reconstructed. Keep the exact final public `name` in
+  `tools`, then bind it to `providerToolName`; the public name remains the
+  permission boundary.
+
+### Typed tool calls
+
+`useTool` accepts generic argument and result types. Query the database at dev time to discover actual property shapes, then keep those types in the app:
+
+```tsx
+type QueryTasksArgs = { database_id?: string; database_slug?: string; query: { page_size?: number } };
+interface TaskDoc {
+  title: string;
+  properties: {
+    Status: string;
+    Priority: string;
+    Due: string;
+  };
+};
+type QueryTasksResult = { documents: TaskDoc[] };
+
+const queryTasks = useTool<QueryTasksArgs, QueryTasksResult>('LOCAL_NOTIS_DATABASE_QUERY');
+const result = await queryTasks.call({ database_id: 'tasks-db-id', query: { page_size: 25 } });
+// result.documents[0].properties.Status is typed as string
+```

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

@@ -0,0 +1,23 @@
+## Troubleshooting
+
+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.
+
+- **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.