@notis_ai/cli 0.2.0-beta.19.1 → 0.2.0-beta.196.1

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

@@ -0,0 +1,116 @@
+# 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
+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), `header`, `meta`, `properties`, `width`; `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.
+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

@@ -0,0 +1,24 @@
+# Troubleshooting
+
+Start with the actual failing operation and its exact Space, source/record
+revision and current target. [Delivery](release.md) owns the release sequence.
+
+| 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,142 @@
+# 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 such as the HTML Space; ordinary collection views keep Portal chrome.
+A Space whose published view hides chrome starts hidden from each person's sidebar,
+like Skill review Spaces; it stays reachable by link and search, and each person
+can show it from the sidebar's hidden Spaces list or the Space's menu.
+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

@@ -0,0 +1,154 @@
+---
+name: notis-cli
+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: ["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
+
+Use this skill when the user wants work done through the Notis CLI.
+
+This skill covers two main CLI workflows:
+
+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, 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
+- the task mentions the `notis` CLI directly
+
+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.
+
+`@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.
+
+The CLI bundles this `notis-cli` base skill and refreshes its canonical copy under `~/.notis/skills/base/` on every launch. It is independent of account-skill sync, feature flags, target selection, and cloud deletion.
+
+## Profiles: accounts and endpoints
+
+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.
+
+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.
+
+### Working against a local `./dev.sh` backend
+
+`./dev.sh` exposes its test account as a lease-backed profile (`dev-<workspace>-<hash>`) pointing at the local backend, and prints the name on startup. Its credential stays in that worktree and it is the automatic default there, so `notis ...` targets the local API and test user with no extra flags. It is not a stored account profile and cannot be selected outside the worktree.
+
+Two rules follow from the dev credential being scoped to that local backend:
+
+- A `dev-*` profile only exists while its `./dev.sh` lease is running. If it is stopped, the CLI fails with `dev_runtime_unavailable` instead of sending the test user's token to the live API.
+- To reach a real account from inside a worktree — including when the local backend is wedged — name a real profile explicitly: `notis --profile <name> ...`. That is the supported escape hatch.
+
+## Critical rule for missing tools
+
+If the tool you need is not already available in your current tool surface, do not stop and do not assume the task is blocked.
+
+Use the Notis CLI as the fallback access layer.
+
+This is especially important when:
+
+- you need direct MCP tools
+- you need a Composio-backed integration tool
+- you need a Notis tool that is not exposed as a first-class command in your current environment
+- you need to discover the canonical tool name before execution
+
+Treat the Notis CLI the same way you would treat a Composio-style tool router flow: discover what is available first, then execute the right tool through the CLI.
+
+## User and repository policy takes precedence
+
+Default delivery below applies only when no more restrictive user or repository
+instruction exists. Explicit preview-only/no-deploy requests and standing requirements
+for explicit deployment consent override the default. Preserve that authority across
+local and cloud runs. For local-only work, build and run stub verification; do not
+create remote resources or activate an app. Use the CLI's documented
+build/verification harness. Store publication remains
+separately authorized.
+
+### Tool access workflow
+
+1. List available toolkit namespaces:
+   - `npx --package @notis_ai/cli@latest -- notis tools toolkits --timeout-ms 90000`
+2. Search for the capability you need using natural language:
+   - `npx --package @notis_ai/cli@latest -- notis tools search "<query>" --timeout-ms 90000`
+   - optionally add known field hints with `--known-fields "<key:value>"`
+3. If needed, inspect the exact tool and parameter schema:
+   - `npx --package @notis_ai/cli@latest -- notis tools describe <tool-name> --timeout-ms 90000`
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --get-schema --timeout-ms 90000`
+4. Validate arguments before execution when the tool is mutating or the schema is non-trivial:
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --dry-run --arguments '<json>'`
+5. Execute the tool:
+   - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'`
+6. If multiple independent calls are needed, use:
+   - `npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'`
+7. If the toolkit is not connected yet, start its connection flow:
+   - `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>`
+   - For a revoked or invalid credential-based connection, reconnect with credential JSON on stdin: `npx --package @notis_ai/cli@latest -- notis tools link <toolkit> --reconnect --credentials -`
+
+### Discovery latency and caching
+
+The discovery bridge may query several connected MCP servers on a cold run and
+can legitimately take longer than the CLI's general 30-second timeout. Always
+use `--timeout-ms 90000` for `tools toolkits`, `tools search`, `tools describe`,
+and schema-only discovery calls. If a discovery call returns `network_timeout`,
+retry that same command once with `--timeout-ms 90000`; do not start a new
+query, invent a tool name, or loop on the default 30-second command.
+
+Discovery is idempotent but should be bounded: run the toolkit listing once per
+task, run one natural-language search per distinct capability, and cache the
+returned canonical tool names and schemas for the rest of the current turn.
+After a successful search/schema response, call the returned canonical tool
+directly (with a dry-run before mutations) instead of repeating the same
+discovery request before every connected-service action.
+
+### Tool access rules
+
+- Never guess tool names. Discover them with `npx --package @notis_ai/cli@latest -- notis tools search` first.
+- Prefer first-class CLI commands when they exist, but use `npx --package @notis_ai/cli@latest -- notis tools ...` whenever the capability is not covered by a dedicated command.
+- When you know the tool name but not the argument shape, use `npx --package @notis_ai/cli@latest -- notis tools describe` or `--get-schema` before execution.
+- Use `--dry-run` before mutating calls when you want schema validation without execution.
+- If a toolkit is missing, use `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>` to start the connection flow.
+- Use `--reconnect` to replace an existing connection. If multiple accounts exist, select one with `--connection-id <id>`.
+- For API keys, basic auth, or other credential JSON, prefer `--credentials -` and pipe or redirect stdin. Avoid inline secrets because they can enter shell history and process listings.
+
+## Task guides
+
+Read only the guide needed for this task. Relative links resolve in the skill bundle.
+For hosted MCP, fetch the matching `notis://docs/notis-cli/references/<file>.md` URI
+with resources/read or the available Notis resource-fetch tool; the root resource
+also rewrites these links to their published URIs.
+
+- [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

@@ -0,0 +1,19 @@
+# Space delivery
+
+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 Space development
+
+When building or deploying a Space, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for source operations:
+
+- 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 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.

package/dist/base-skills/notis-cli/references/native-databases.md

@@ -0,0 +1,21 @@
+## Native database access
+
+Native Notis databases are accessed through the generic tool workflow, not a first-class database command group. Use these canonical tool names:
+
+- `LOCAL_NOTIS_DATABASE_LIST_DATABASES` -- list databases accessible to the current profile
+- `LOCAL_NOTIS_DATABASE_GET_DATABASE` -- inspect read-only metadata and schema detail
+- `LOCAL_NOTIS_DATABASE_QUERY` -- query documents from a database
+- `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` -- create or update a database schema. A new database is linked to a Space in the same call (`links.add`) and names its main view; change a database used in Spaces through protocol 1 with its exact Space binding target
+- `LOCAL_NOTIS_DATABASE_DELETE_DATABASE` -- permanently delete a database and all its rows by `database_id`. It is refused for every database a Space links (`database_linked_to_space`: move it instead; a database used only in one Space is deleted with that Space from the bin), for a legacy App database its App declares, and while another database relates to it or an automation is triggered by it; the error says what to remove first
+
+Example workflow before building a Space view:
+
+```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 --get-schema
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_id":"<id from LIST_DATABASES>"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"protocol":1,"target":{"space_id":"<space id>","binding":"<binding id>"},"input":{"mode":"rows","page_size":1}}'
+```
+
+Most databases are used in Spaces. Such a database is read only through one of its links: `GET_DATABASE` with a bare `database_id` returns `resolved_target` (the main view's `{space_id, binding}`), and a bare-id `QUERY` answers `database_in_spaces` with every link. Reuse that exact target with `protocol: 1`. Every database lives in a Space; a `database_slug` resolves among every database you can reach, and a slug several of them share answers `database_slug_ambiguous` with each `database_id` and its Spaces.

package/dist/base-skills/notis-cli/references/tool-examples.md

@@ -0,0 +1,56 @@
+### Toolkit mental model
+
+Typical toolkit namespaces include:
+
+- `notis` for native Notis tools
+- `composio-*` for Composio-backed integrations
+- `mcp-*` for MCP-backed tools
+
+The pattern is:
+
+1. discover toolkits
+2. search tools
+3. inspect schema if needed
+4. execute the canonical tool
+
+### Tool access examples
+
+Find a tool:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools toolkits
+npx --package @notis_ai/cli@latest -- notis tools search "list today's calendar events"
+```
+
+Inspect a tool before execution:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools describe composio-googlecalendar-list_events
+npx --package @notis_ai/cli@latest -- notis tools exec composio-googlecalendar-list_events --get-schema
+```
+
+Dry-run a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --dry-run --arguments '{"database_id":"<tasks database id>"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"protocol":1,"target":{"space_id":"<space id>","binding":"<binding id>"},"input":{"mode":"rows","page_size":10}}'
+```
+
+Execute a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_id":"<tasks database id>"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"protocol":1,"target":{"space_id":"<space id>","binding":"<binding id>"},"input":{"mode":"rows","page_size":10}}'
+```
+
+Connect a missing toolkit:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools link github
+```
+
+Reconnect a credential-based toolkit without putting the secret in shell history:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools link dataforseo --reconnect --credentials - < credentials.json
+```