@notis_ai/cli 0.2.0-beta.178.1 → 0.2.0-beta.1792022492092.1

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

@@ -1,63 +1,118 @@
-## 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 |
-| `useAgentContext()` / `NotisCommentBoundary` / `NotisCommentBox` | generic context API and optional UI | App-defined pills, icons, context, attachments and nearby comments; see [Context sharing](context.md) |
-| `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 |
-| `Dialog` | `{ open, onClose, title, description?, role?, children }` | Themed native modal with top-layer stacking, focus handling and background shortcut isolation. Use `role="alertdialog"` for destructive confirmation; put the safe action first. |
-
-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:
+# SDK reference for Space views
+
+Import hooks/components from `@notis/sdk`; configuration helpers are in
+`@notis/sdk/config`. `NotisProvider` already installs shortcut support. Use the
+scoped host runtime—source never owns an account credential or backend transport.
+
+## Records and declared reads
+
+| API | Use |
+| --- | --- |
+| `useViewParams<typeof definition>()` | `{params, invalid, missing, declared, ready}` for declared typed URL params. Unknown names are dropped; invalid values use their declared default. |
+| `useShown<Row>(name, options?)` | Execute the native list in `shows[name]` with current params. Options: `sorts`, `pageSize`, `offset`, `includeContent`; result includes `data`, `loading`, `hasData`, `error`, `refetch`. |
+| `useShownAvailable(name)` | Check whether this host exposes the declared native list. A record Site can expose only its exact server-pinned row scope. |
+| `useAction<Inputs, Result>(name)` / `useActionQuery<Result>(name, inputs)` | Call a declared action; identify read-only calls explicitly and retain request IDs/revisions for writes. Never call account-wide tools from a Space. |
+| `useNativeDocumentBody(binding, recordKey, {readAction, writeAction?, enabled?})` | Markdown body adapter. Keep drafts in the view; save with the original content, record/schema revisions and stable request ID. Rich editing normally uses `DocumentEditor`. |
+| `useNotis()` | Host resource, Space/app labels, route and ready state. Use `resource.id` for the current Space identity. |
 
 ```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
+const { resource } = useNotis();
+const nav = useNotisNavigation();
+const { params } = useViewParams<typeof definition>();
+const rows = useShown<{ record_key: string; title: string | null }>('notes');
+// In the row's click handler:
+nav.toSpace(resource.id, { recordKey: row.record_key });
+// In the record branch:
+<DocumentPage recordKey={params.note} breadcrumb={[{ label: 'All notes', onSelect: () => nav.toSpace(resource.id) }]} />
 ```
+
+Keep hooks unconditional. Preserve cached content during refresh; `loading` is
+first-read state, not every fetch. Use [Design](design.md#instant-view-loading-contract-required)
+for loading/error/empty states and explicit read caching.
+
+## First-party record components
+
+| Component | Contract |
+| --- | --- |
+| `<DocumentPage recordKey>` | The full page of a record that is the view's main content (a note, a document): breadcrumb, Saving or Saved, '...' menu, cover, icon, title, meta strip, properties that save automatically, collaborative body. Slots `breadcrumb`, `actions`, `menuItems`, `aboveBody`, `belowBody`; toggles `share` (off by default, never offered for a report record; in its own Space's view the record's Site is a row of the view's top bar Share panel, not a toolbar Share), `header`, `meta`, `properties`, `width`; `viewer: 'html'` opens a record whose one stored `.html` file is the page (such as an HTML page saved in Notis Notes) full height under the toolbar, without header, meta, properties or body editor; `onSaved`; `layout` to rearrange its parts. Pair with `DocumentPageSkeleton` and `usePrefetchRecord()`. Until the Notis CLI you build with exports it (`spaces build` replaces the Space's `packages/sdk` with the CLI's own SDK, and older ones have no `DocumentPage`, so the import fails the build), reach the same host page through `useNotisRuntime().ui?.DocumentPage` and fall back to `DocumentEditor` when it is missing, as the Notes Spaces do in `lib/document-page.tsx`. |
+| `<DocumentEditor recordKey>` | Native collaborative body, properties, images and attachments. With separate properties use `showProperties={false}`. |
+| `<RecordProperties recordKey>` | Native revision-checked property editing. |
+| `<HtmlFrame recordKey>` | Attached HTML under viewer CSP and an opaque-origin sandbox. Source cannot relax that boundary. |
+| `<ReportFrame recordKey>` | A report row's saved independent implementation in its database's current view. |
+| `<ShareControl recordKey>` | Private/shared record Site, copy link and revoke. |
+
+The published Space declares the database binding; the server rechecks record
+scope and binding revision. A Site exposes read-only body/property snapshots and
+HTML for its pinned record, including a declared non-collection record param.
+A report row (`<ReportFrame>`) cannot be shared as a Site; a report saved as an
+HTML file can.
+It has no upload, collaboration credential, authoring controls or sharing mutation.
+Preview source does not gain live record editing. No app-owned credentials or
+filesystem URLs belong in component props.
+
+## Navigation
+
+`useNotisNavigation()` exposes `toSpace(spaceId, {recordKey?, params?})` and
+`toNamedSpace(alias, {recordKey?, params?})`. Prefer declared portable navigation
+aliases for sibling destinations; the host resolves them under current access.
+Use declared params for view state, for example `{params: {project: key, period: 'week'}}`.
+The destination drops unknown params and authorizes referenced records. Changing
+a slug cannot change identity. Agents cite current server-returned links.
+
+## Viewer-only exploration
+
+`viewerReads: ['databases', 'skills']` permits read-only inspection of what the
+signed-in viewer already reaches. It creates no shared grant. Use
+`useViewerReadAvailable(family)`, `useViewerDatabases`, `useViewerSkills`, or
+`useViewerRead(operation, input)`. Anonymous Sites cannot use these families.
+Explicit synthetic `viewerReads` fixtures stand in for the viewer's reads offline.
+
+## The viewer's cloud computer
+
+`cloudComputer: 'shell'` (or `'read'` for facts only) lets a page run one command
+or write one file on the signed-in viewer's own cloud computer, after that viewer
+allows it in the Portal prompt. Use `useCloudComputerShell()`: check `level`, call
+`requestApproval()` when `approved` is false (either level; the facts of
+`useCloudComputer()` are read again once allowed), then, when `available` (`shell`),
+`run(command, options)` or
+`upload({ path, content, content_encoding: 'base64', mode: 0o600 })`. Never put
+secrets in a command; send them as upload content. A run is never repeated for one
+request key: pass `requestId` (run option, or `request_id` in the upload) when the
+page retries a run itself; `cloud_computer_already_ran` means it already ran. The
+approval covers only the exact code the viewer allowed, so every new release asks again. Keep a fallback (a Manager
+draft) for Sites, previews offline and viewers who do not allow it. Declare it only
+when the page's core controls run on the cloud computer.
+
+## Visual data and Markdown
+
+`<RenderChartData title columns rows>` adds a semantic table for the chart without
+a second visible table. Give it the same labels/values used by the chart. The
+renderer never guesses exact numbers from SVG/canvas geometry: a chart without
+`RenderChartData` contributes only its accessible name to the Markdown.
+
+An optional `markdown` source module exports a pure function of `{params, shown}`.
+It must describe the rendered selection and its actual data. Ordinary rendering
+extracts tables, lists, controls and visible document/HTML content automatically.
+
+## Host interactions and context
+
+- `useHandover()` exposes `{handover, available, pending, error}`. Call a declared
+  linked Skill with `handover({skill, prompt})`; fall back when no agent UI exists.
+- `useTopBarSearch` registers a host-owned search field. Do not duplicate host chrome.
+- `useActiveResource` publishes the current resource; `useAgentContext`,
+  `NotisSelectionBoundary`, `NotisCommentBoundary` and `NotisCommentBox` support
+  explicit reference context. [Context sharing](context.md) owns the contract.
+- `useCollectionInteractions`, selection components and `MultiSelectActionBar`
+  support native collection interactions. `Dialog` supplies themed top-layer
+  dialogs, focus handling and shortcut isolation.
+- `MarkdownEditor` is for a view-owned Markdown draft/persistence adapter. Native
+  documents use `DocumentEditor` so collaboration and file authority stay with Notis.
+
+## Offline fixtures
+
+Declare a `verificationFixtures` JSON source with `actions` and optional `context`,
+`shown`, `viewerReads`, `documentBodies`, `recordViews`. Cases match exact action
+inputs/list params. Record views use `{operation: 'record'|'html'|'report', record_key,
+result}`; native record snapshots require `writable: false` and no authoring target.
+Keep every fixture fictional and include every load-time read. Failed or missing
+fixtures fail verification; there is no fallback to the user's real account.

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

@@ -1,23 +1,24 @@
-## Troubleshooting
+# 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.
+Start with the actual failing operation and its exact Space, source/record
+revision and current target. [Delivery](release.md) owns the release sequence.
 
-- **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.
+| Failure | Check |
+| --- | --- |
+| Build rejects a view | Required `specVersion`, path, descriptions, params, executable shows and memory; use the file/line diagnostic. |
+| Main-view conflict | Inspect current database links/main view. Move the existing claim explicitly or retain it; do not remove main just to publish. |
+| Source creation fails | Check its canonical schema and same-view main record param. Verify creates no resource; promotion is atomic. |
+| View-link warning after a successful write | Use `FIND_VIEWS` with the returned record key. The write is already committed; do not insert again. |
+| Empty list or missing properties | Inspect the live schema, filter, authorized binding and returned projection. Distinguish a successful empty result from a denied/failed read. |
+| Verification fails on a read | Add the exact fictional case to the selected fixture file. Never fill missing fixtures with live private data. |
+| A caught write-on-load fails rendering | Remove the side effect from initial rendering. A read-only check cannot authorize writes. |
+| Stale binding/schema/record | Read current state, preserve the original receipt/intent and merge the intended edit. Do not overwrite concurrent changes. |
+| Old code in Workspace | Read the published revision and requested bundle; source edits or restarting Desktop do not deploy it. |
+| Uncertain deployment | Run `notis doctor`, read the same Space and release/request identity, then reconcile before retrying. |
+| Screenshot misses content | Inspect actual inner scrolling, lazy data and frame layout; keep full-height limits and treat a failed capture as unverified. |
+| Site unexpectedly has editor controls | Recheck the anonymous scoped runtime. A Site cannot borrow an ambient signed-in session or another record's authority. |
+| Memory hit looks current but access/freshness is unknown | Render its current link and verify the relevant value. Do not release historical content from an unverified read set. |
+
+For visual defects, compare the installed page at 390px and 1440px in EN/FR,
+including loading, empty and error states. A standalone harness cannot certify
+the Portal parent layout, collaboration or public Site behavior.

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

@@ -0,0 +1,145 @@
+# View authoring
+
+A view is the presentation of a Space. A record opens in a view; its database has
+one main view. Words in links describe the destination, while IDs choose it.
+Get links from write results or `LOCAL_NOTIS_FIND_VIEWS`, not by joining labels.
+
+## Start from the collection scaffold
+
+```bash
+notis spaces init "Notes" ./notes --database-key notes --path notes
+notis spaces build ./notes --space collection
+```
+
+`init` is local only. For an existing Space, pull its exact ID instead. Keep its
+lock and local source key; one build/deploy changes that selected Space only.
+A container has children but no page; page-only params/shows/memory belong on views.
+
+## A complete view declaration
+
+The linked `notes` resource below must already resolve to this installation's
+native database. Descriptions explain what a person or agent can do here.
+
+```ts
+import { defineSpace } from '@notis/sdk/config';
+
+export default defineSpace({
+  specVersion: 2,
+  name: 'Notes',
+  path: 'notes',
+  description: 'Browse notes and open one with its files.',
+  readableContext: 'The note parameter opens one note. The list shows all notes available through this Space.',
+  entry: './view.tsx',
+  resources: { notes: { kind: 'database', key: 'notes' } },
+  collection: { database: 'notes', titleProperty: 'title' },
+  params: {
+    note: { type: 'record', database: 'notes', main: true,
+      description: 'The note to open beside the list.' },
+  },
+  shows: { notes: { database: 'notes', where: {}, open: 'note' } },
+  memory: { markdown: true, attachments: true, screenshot: false, snapshots: [] },
+  actions: {
+    read: {
+      tool: 'LOCAL_NOTIS_DATABASE_QUERY',
+      inputs: { type: 'object', additionalProperties: false,
+        required: ['request'], properties: { request: {
+          type: 'object', additionalProperties: false,
+          required: ['filter', 'page_size', 'include_content'],
+          properties: {
+            filter: { type: 'object', additionalProperties: false,
+              required: ['field', 'op', 'value'], properties: {
+                field: { type: 'object', additionalProperties: false,
+                  required: ['column'], properties: { column: { const: 'record_key' } } },
+                op: { const: 'equals' }, value: { type: 'string', format: 'uuid' },
+              } },
+            page_size: { const: 1 }, include_content: { const: true },
+          },
+        } } },
+      arguments: { database_id: { $asset: 'notes' }, request: { $input: 'request' } },
+    },
+  },
+});
+```
+
+Use `useViewParams<typeof definition>()`, `useShown('notes')`, and
+`<DocumentPage recordKey={params.note}>` (the whole note page; use `DocumentEditor` only to embed a body
+inside a layout of your own; if `spaces build` reports no `DocumentPage` export, your CLI predates it: use
+`useNotisRuntime().ui?.DocumentPage` with a `DocumentEditor` fallback, see the SDK reference). Keep hooks unconditional; conditional
+record/list branches can be separate components. The SDK reference covers the
+components and exact navigation helpers. The saved `read` action is deliberately
+constrained to one native record for body/Site reads; `shows.notes` owns the
+Editor’s collection list. Keep both tied to the same declared resource.
+
+## Params and declared lists
+
+- Param types: `record`, `enum`, `text`, `number`, `date`, `boolean`. Each needs a
+  description. Enum values and defaults are typed; a required param has no default.
+- Record params name a declared database and have no default record. `main: true`
+  claims that database's main view. `slugProperty` is a title/number property used
+  for readable link text, not record identity.
+- `path` is descriptive lowercase words, up to four slash-separated segments;
+  do not put IDs, credentials or reserved product routes in it.
+- `shows` for native data is `{database, where, open?}`. `where` is the native filter
+  grammar and is what `useShown` executes, not commentary beside a different query.
+  `open` names a record param over the same database.
+- A project-scoped task list can use
+  `{field: {property: 'Project'}, op: 'contains', value: '{project}'}` with a declared
+  project record param. `{project.Status}` reads a property of that authorized record.
+- For connected-service content use `{about, services?}` and declared actions.
+  This descriptive form is not a native executable list; use `useAction` for reads.
+- Preserve the application's real semantics and option names. For the existing
+  Tasks migration, Inbox is **Project empty OR Status equals Inbox**. Keep imported
+  rows, statuses and creation defaults; add the Inbox option only if absent. Its
+  native filter is `{or: [{field: {property: 'Project'}, op: 'is_empty'},
+  {field: {property: 'Status'}, op: 'equals', value: 'Inbox'}]}`. Other applications
+  must use their own inspected schema rather than copying these labels blindly.
+
+## Create a database in the same release
+
+Replace an existing database reference with:
+
+```ts
+resources: {
+  notes: { kind: 'database', create: {
+    name: 'Notes',
+    schema: {
+      schema_version: 1, value_encoding_version: 1, coercion_version: 1,
+      title_property_id: 'title', property_order: ['title'],
+      properties: { title: { id: 'title', name: 'Name', kind: 'title',
+        storage_family: 'textish', description: '', order: 0, config: {} } },
+    },
+  } },
+},
+```
+
+The same view declares a record param over `notes` with `main: true`. Promotion
+creates the database, link, main view, optional fictional `starterRows` and source
+atomically; a later failure leaves none of them behind. Verification does not create
+it. `create` is creation-only: later schema edits use native database tools;
+`spaces pull` refreshes the declaration from the live schema.
+
+The separate native schema-tool creation route requires `links.add` and
+`main_view: {space_id, param}` in that linked Space. Until the Space next deploys
+that main param, record links open the Space and writes return `view_warning`.
+Inspect current tools for exact argument shapes; do not repeatedly insert rows
+because a pending main view cannot yet open one.
+
+## Rendering and memory
+
+Choose [memory](memory.md) deliberately. `chrome: 'hidden'` is for full-screen
+presentations; ordinary collection views keep Portal chrome.
+A Space whose published view hides chrome starts hidden from each person's sidebar;
+it stays reachable by link and search. Each person can turn on **Show hidden Spaces**
+in the sidebar's Spaces menu, then choose **Show in sidebar** in that Space's menu.
+Skill review Spaces stay out of the sidebar, even with **Show hidden Spaces** on:
+people open them from the Skill page's **Changes** list. A review a person already
+chose to show stays in their sidebar until they hide it.
+Optional `markdown: './markdown.ts'` names a module exporting a pure function of
+`{params, shown}`. Its output must represent this view, not make hidden writes.
+Use `<RenderChartData>` with the chart's actual rows so rendered Markdown contains
+precise labels and values as well as its image.
+
+Add synthetic action/list/body/record fixtures, then build and verify. Verification
+and live rendering share the read-only renderer; fixture success does not prove
+live permissions or data. After an authorized deploy, render the returned view link
+with `notis views render` and inspect both the Markdown and full-height screenshot.

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

@@ -1,9 +1,9 @@
 ---
 name: notis-cli
-description: Use when agents should work through the Notis CLI, especially to develop Notis apps locally or to access Notis, Composio, or MCP tools they do not currently have loaded directly.
+description: Use when agents should work through the Notis CLI, especially to develop Notis Spaces locally or to access Notis, Composio, or MCP tools they do not currently have loaded directly.
 mcp_resource: true
-mcp_tool_patterns: []
-mcp_references: ["references/app-delivery.md", "references/tool-examples.md", "references/native-databases.md", "references/troubleshooting.md"]
+mcp_tool_patterns: ["LOCAL_NOTIS_GET_INTELLIGENCE_POLICY"]
+mcp_references: ["references/app-delivery.md", "references/tool-examples.md", "references/native-databases.md", "references/troubleshooting.md", "references/intelligence.md"]
 ---
 
 # Notis CLI Skill
@@ -12,13 +12,13 @@ Use this skill when the user wants work done through the Notis CLI.
 
 This skill covers two main CLI workflows:
 
-1. Developing Notis apps locally.
+1. Developing Notis Spaces (views, their source and linked Skills) locally.
 2. Accessing Notis, Composio, and MCP tools through the CLI.
 ## When to use this skill
 
 Activate this skill when:
 
-- the user wants to init, develop, build, verify, link, pull, or deploy a Notis app through the CLI
+- the user wants to init, pull, build, verify, preview, deploy or promote a Notis Space through the CLI
 - the current agent does not have the tool it needs in its direct tool list
 - the user wants direct MCP access through Notis
 - the user wants to use an integration-backed capability through Notis rather than a first-class local tool
@@ -28,7 +28,7 @@ Use the registry-resolved published npm package everywhere:
 
 - `npx --package @notis_ai/cli@latest -- notis ...`
 
-Always use this NPX command form so the agent runs the current published CLI. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`. On a local machine the CLI holds its own OAuth grant: `notis login` authorizes one in the browser, and signing in to the Notis desktop app authorizes one automatically for that account. Either way the grant belongs to the CLI, which refreshes it without the desktop app running.
+Always use this NPX command form so the agent runs the current published CLI, with one exception: on the Notis Cloud Computer (home folder `/vercel/sandbox`) the CLI is preinstalled and kept current, so run `notis ...` there with the same arguments, and use the NPX form only if `notis` is not found. Parallel NPX runs reinstall the package and can break each other. In hosted shells, the CLI is pre-authenticated through `NOTIS_JWT`. On a local machine the CLI holds its own OAuth grant: `notis login` authorizes one in the browser, and signing in to the Notis desktop app authorizes one automatically for that account. Either way the grant belongs to the CLI, which refreshes it without the desktop app running.
 
 `@latest` is correct for every account, including beta ones. Each deployment reports which published build belongs to it, `notis login` pins that on the profile, and a later run that finds itself on the wrong build hands the invocation to the right one before doing anything. Never substitute a channel by hand: pinning `@beta` on a production profile is how a machine ends up running a build its API does not expect. `notis doctor` reports the active channel, and `NOTIS_CLI_AUTO_CHANNEL=0` turns the hand-off off for a run.
 
@@ -38,11 +38,13 @@ The CLI bundles this `notis-cli` base skill and refreshes its canonical copy und
 
 A profile is one account paired with one API endpoint. Profiles live side by side; switching between them never signs any of them out.
 
-- `npx --package @notis_ai/cli@latest -- notis profile list` — every profile on this machine, with its endpoint, user, and whether it is signed in. The active one is marked.
-- `npx --package @notis_ai/cli@latest -- notis profile use <name>` — change which account subsequent commands run as.
-- `npx --package @notis_ai/cli@latest -- notis --profile <name> <command>` — run a single command as another account without changing the active one.
-- `npx --package @notis_ai/cli@latest -- notis login --profile <name>` — add an account. The existing profiles keep their credentials.
-- `npx --package @notis_ai/cli@latest -- notis logout` — sign out of the active profile only; pass `--all-profiles` to clear every one.
+Notis Desktop signs the CLI in for every account saved in the app, one profile each. `default` keeps its name; each added account gets a profile named after its email with `@` turned into `-` (for example `flo-mindtheflo.com`), and Beta Desktop adds `-beta`. Switching accounts in Desktop never changes the active profile. Only the active profile's skills are linked into Claude Code, Codex and Cursor; every other account's skills sync into their own folder. Signing an account out of Desktop signs it out of the CLI on this computer and removes the profile and skills Desktop made for it. If that was the active profile, the CLI switches to the account Desktop opens next; with no other signed-in Desktop account it stays signed out. Profiles made with `notis login` are never removed or picked automatically.
+
+- `npx --package @notis_ai/cli@latest -- notis profile list`: every profile on this machine, with its endpoint, user, and whether it is signed in. The active one is marked.
+- `npx --package @notis_ai/cli@latest -- notis profile use <name>`: change which account subsequent commands run as, and link that account's skills into the agent folders straight away.
+- `npx --package @notis_ai/cli@latest -- notis --profile <name> <command>`: run a single command as another account without changing the active one.
+- `npx --package @notis_ai/cli@latest -- notis login --profile <name>`: add an account. The existing profiles keep their credentials.
+- `npx --package @notis_ai/cli@latest -- notis logout`: sign this computer out of the active profile only; the account stays signed in on other computers. Pass `--all-profiles` to clear every profile on this computer.
 
 Read the profile before acting on the user's data. `notis whoami` reports the account and endpoint a command will hit; if that is not the account the user meant, switch profiles rather than proceeding.
 
@@ -133,7 +135,22 @@ For hosted MCP, fetch the matching `notis://docs/notis-cli/references/<file>.md`
 with resources/read or the available Notis resource-fetch tool; the root resource
 also rewrites these links to their published URIs.
 
-- [App delivery](references/app-delivery.md)
+- [Space delivery](references/app-delivery.md)
 - [Toolkit mental model](references/tool-examples.md)
 - [Native database access](references/native-databases.md)
 - [Supporting commands](references/troubleshooting.md)
+
+## Intelligence for skills and delegated work
+
+Skills request `low`, `medium`, or `high`, never a fixed model name. Discover the
+read-only `LOCAL_NOTIS_GET_INTELLIGENCE_POLICY` tool to obtain the shared `contract`
+and current mapping
+for `notis`, `codex`, or `claude_code` and the requested `level`. Resolve model and
+reasoning effort together at the start of each job; validate the selected options
+with the executing harness. Explicit invocation overrides win. A fixed-model
+harness may inherit and disclose that the level was not applied; an automated
+launcher needing an exact selection stops before side effects if policy is unavailable.
+Repository and installed skills consume that same response; neither needs a
+checkout-relative document. Record actual execution receipts, not the level name, as model provenance. Media
+engines remain separate capabilities selected by their tools. See
+[the intelligence contract](references/intelligence.md) for cross-environment details.

package/dist/base-skills/notis-cli/references/app-delivery.md

@@ -1,18 +1,19 @@
-# App delivery
+# Space delivery
 
-Use the canonical `notis-apps` skill’s entrypoint and [release guide](../../notis-apps/references/release.md).
+Use the canonical `notis-apps` skill's entrypoint and [release guide](../../notis-apps/references/release.md).
 For hosted MCP fetch `notis://docs/notis-apps` and `notis://docs/notis-apps/references/release.md`.
 User/repository no-deploy and explicit-consent policies take precedence over default delivery.
 
-## IMPORTANT: When NOT to use tool access for app development
+## IMPORTANT: When NOT to use tool access for Space development
 
-When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for app file operations:
+When building or deploying a Space, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for source operations:
 
-- Loading or saving app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps deploy`
-- Linting app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` which validates automatically
-- Managing app routes -- write standard Vite + React pages in `app/`, not raw JS files
+- Loading, building or publishing source -- use `notis spaces pull`, `spaces build`, `spaces verify`, `spaces preview`, `spaces deploy` and `spaces promote` as the release guide orders them
+- Validating views -- `spaces build` and `spaces verify` check declarations, fixtures and renders
+- Writing pages -- write standard Vite + React views with `@notis/sdk`, not raw JS files
 
-Database schemas are the exception: declaring a slug in `notis.config.ts` does
-not create it. Use the discovery-first native database tool workflow to
-create/update and read back each app-owned schema before deployment. Tool calls
-are also valid for testing runtime behavior after deployment.
+Database schemas have two routes: the native database tool (create with `links.add`
+and `main_view`), or a `create` declaration in Space source that the deploy applies
+atomically. Tool calls are also valid for testing runtime behavior after deployment.
+`notis apps` is the legacy App group for accounts not yet moved to Spaces; a legacy
+App cannot declare Skills.

package/dist/base-skills/notis-cli/references/intelligence.md

@@ -0,0 +1,94 @@
+# Agent intelligence levels
+
+This is one shared contract for repository skills and account-installed skills.
+Read it from the `contract` field returned by `LOCAL_NOTIS_GET_INTELLIGENCE_POLICY`,
+directly as a native tool or through the authenticated Notis CLI. The same response
+contains current harness mappings and a `contract_revision` fingerprint. No local
+repository document is a runtime prerequisite. This bundled guide is the source
+served by that lookup, not a separate environment-specific contract.
+
+Skills request **low**, **medium**, or **high**. They never maintain model names,
+version pins, family aliases, effort tables, or price scorecards. The current
+Notis runtime policy is the source of truth, on every operating system and host.
+
+## Choosing a level
+
+| Level | Work |
+| --- | --- |
+| **low** | Bounded extraction, classification against a supplied rubric, formatting, and repetitive generation from complete inputs. |
+| **medium** | Synthesis, writing and reviewing prose from supplied evidence, and moderately complex bounded work. |
+| **high** | The skill default when unspecified: complex reasoning, investigation, coding, code review, and orchestration. |
+
+These are skill defaults, not changes to account or product defaults. The user's
+explicit instruction for this invocation wins: level, exact model, effort,
+harness, or inheritance from the current session. Preserve the scope of that
+override; never save a lasting preference unless asked. Maximum-depth requests
+are invocation overrides, not a fourth Notis level.
+
+## Resolve at execution time
+
+Discover **get current Notis intelligence policy for each harness** through the
+Notis tool catalogue. The read-only tool is `LOCAL_NOTIS_GET_INTELLIGENCE_POLICY`:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_GET_INTELLIGENCE_POLICY \
+  --arguments '{"harness":"codex","level":"low"}'
+```
+
+Omit arguments to read all levels. Harness keys are `notis`, `codex`, and
+`claude_code`. A local Mac, Windows host, cloud sandbox, or CI runner uses the
+same contract. Cursor or another host must identify its actual execution engine;
+it must not pretend to be a supported harness based on installed binaries.
+
+The projection is generated from the backend native intelligence configuration and external-harness policy. It contains no
+second mapping. Weekly policy changes therefore require no skill edits.
+
+- Resolve **both model and reasoning effort**. Level names are not effort names.
+- Resolve once per delegated job; keep its `policy_revision` and selection stable
+  through claim, generation, retry and completion. A new job gets a fresh policy.
+- Explicit user choices override the selection; validate them with the executing
+  harness. Never substitute another model, buy API capacity, or change accounts
+  because a selection is unavailable.
+- Validate the request against advertised harness capabilities. Policy is not
+  evidence of entitlement, quota, installed support or successful execution.
+- Use native `intelligence_mode` when the Notis delegation interface supports it.
+  External launchers translate the returned selection into their supported options.
+- Do not downgrade or restart the main session to enforce a skill default.
+- A single-model harness can inherit its current configuration and disclose that
+  the requested level was not applied. Unknown or unavailable mappings are not
+  permission to guess a model. Automated launchers that require an exact selection
+  stop before claiming jobs or producing side effects and explain the missing policy.
+- Before this lookup is deployed, use a current runtime-injected policy if present;
+  otherwise use the transparent inheritance behavior above. Do not copy a temporary
+  model table into skills as a rollout workaround.
+
+## Modalities, product assertions and provenance
+
+Image, speech, video, embedding and provider-research engines are capabilities,
+not interchangeable text-reasoning levels. Skills discover the current native
+capability and let its backend select the engine. External scripts requiring an
+exact provider-specific identifier must resolve current supported configuration
+or take an explicit invocation override; they must not pass `low` as an engine ID.
+
+Test specs assert behavior against the current backend configuration, rather than
+freezing last month's model names. Preserve exact comparisons: derive the expected
+identifier from the owning policy or tool configuration, then compare the receipt.
+Do not weaken a routing test to merely check that some model name exists.
+
+Persist **the actual model that ran**, not an intelligence level. Resolve before
+claiming jobs when the identifier participates in a prompt hash or lease contract.
+Verify execution readback before certifying provenance; aliases and requested
+settings are not actual-model receipts. Preserve historical evidence and existing
+records. Do not rewrite an old receipt as today's policy.
+
+## Subscription execution
+
+A level chooses intelligence, not payment authority. Use the current harness's
+sub-agents or the user's subscription CLI. The existing direct-provider approval
+boundary remains in the workspace/account provider-approval policy.
+
+For subscription CLI subprocesses, remove provider API-key/base-URL variables
+from the child environment. Preserve native subscription credentials; never log
+out or rewrite account authentication to enforce a level. Check the harness's
+execution/authentication readback. Resolve only once per job, batch bounded items
+where appropriate, and keep existing concurrency and usage limits.