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

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

@@ -0,0 +1,145 @@
+## 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
+
+### Publication privacy and portability gate
+
+Before submitting or updating a Store listing:
+
+1. Inventory the exact public source archive, listing text/media, database schemas,
+   starter rows, bundled skills (including scripts/references), and automation
+   prompts/configuration. Review their actual contents, not just filenames or
+   a passing secret scan. Exclude personal records, transcripts, health/journal
+   history, customer details, private repository/account identifiers, credentials,
+   local paths, run logs, and private links. Do not merely replace a person's name
+   in otherwise real data. Rebuild examples from wholly fictional scenarios.
+2. Keep live owner databases structure-only (`seedDocuments` absent or false).
+   Opting in seeds the database's live rows, including folders: it is not a
+   fixture selector. Use fictional screenshot fixtures and an explicit, idempotent
+   onboarding demo-data option. If starter rows are needed in the install snapshot,
+   publish only from an isolated, verified fictional dataset; never replace or
+   delete the owner's real data to prepare a submission. When the user asks for
+   examples to come with the app, include them in that verified install snapshot:
+   screenshot fixtures or an optional onboarding seed step do not satisfy this.
+3. Bundle the full dependency closure of every app/automation skill, including
+   referenced helpers and resources. Remove private account-specific defaults;
+   resolve the installer's databases, connections, repository, timezone and
+   delivery choices at runtime. Preserve existing owner's schedules and data.
+4. Declare a source-owned onboarding skill. It must work through available MCP
+   tools or the Notis CLI in any agent harness, without requiring Notis Manager,
+   vendor-specific delegation tools, hidden local files, or publisher access.
+   Discover tools and inspect schemas before calls; reconcile existing resources
+   before creating them. Obtain installer choices before enabling automation or
+   external actions. Installing examples must not activate external deliveries.
+5. Test onboarding as an independent harness-native proof agent using an account
+   isolated from the publisher, then rerun to prove no duplicates. Exercise each
+   route and its interactions with fictional data, including empty/error states.
+   Record exact identities, versions, results and run-created resource cleanup in
+   a private Notis document owned by the app, never only in local files; never use
+   owner records as writable test fixtures.
+   For bundled starter-data claims, install the actual published listing into an
+   empty test account and read back its rows before onboarding or any manual data
+   writes. Confirm the installed listing version and remapped relations; do not
+   substitute an editable-source deployment for this Store-install test.
+6. Inspect the final submitted snapshot and media after packaging. Record the
+   privacy audit and verification against that exact source version in the same
+   private Notis document. Any unknown
+   provenance, missing dependency, untested onboarding or suspected personal data
+   blocks submission until resolved. Never equate submission with review approval
+   or Store publication.
+
+### 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,63 @@
+## 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:
+
+```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.

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 apps 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 apps 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 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.
+
+- [App 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,18 @@
+# App 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 app development
+
+When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for app file 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
+
+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.

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. Every database belongs to a Notis app: creation requires the owning app's slug or id in the `app` argument (create the app first with `LOCAL_NOTIS_CREATE_APP` if needed)
+- `LOCAL_NOTIS_DATABASE_DELETE_DATABASE` -- permanently delete a database and all its rows by `database_id`. It is refused for a 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 an app:
+
+```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_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}}'
+```
+
+When `LOCAL_NOTIS_DATABASE_LIST_DATABASES` or `LOCAL_NOTIS_DATABASE_GET_DATABASE` returns a database ID, prefer `database_id` for `LOCAL_NOTIS_DATABASE_QUERY`; `database_slug` remains supported as a fallback.

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_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"database_id":"tasks-db-id","query":{"page_size":10}}'
+```
+
+Execute a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"tasks-db-id","query":{"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
+```

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

@@ -0,0 +1,39 @@
+## Supporting commands
+
+- `npx --package @notis_ai/cli@latest -- notis whoami` — confirm which account and endpoint a command will target
+- `npx --package @notis_ai/cli@latest -- notis doctor` — verify CLI config, auth, routing, and API reachability before relying on the CLI
+- `npx --package @notis_ai/cli@latest -- notis describe <command...>` — get the exact command contract for first-class CLI commands
+
+## Troubleshooting
+
+### CLI returns `auth_expired` or `auth_missing`
+
+The profile's browser authorization has lapsed or was never granted. Run
+`notis login` (add `--profile <name>` when the failing profile is not the
+active one) and have the user approve the browser prompt. In JSON/agent mode
+the first hint is the exact command to run. Do not copy refresh tokens into
+commands or try to mint a credential yourself.
+
+If the profile is a `dev-*` one, the fix is to restart `./dev.sh` in the
+workspace it belongs to, or to switch to a real account profile.
+
+### Deploy fails with "network_error" or "fetch failed"
+
+Run `notis doctor` to verify the effective profile and endpoint. Read back the exact app ID,
+version and release state before retrying. An uncertain network response is not proof of rollback.
+There is no direct storage deployment path. Repair authentication when needed without changing the
+intended profile, then reconcile the previous outcome before starting a new release.
+
+Localhost backends are a Notis-developer test lane owned by `./dev.sh` and its lease-backed profile.
+Do not silently switch between that lane and a live account.
+
+### Health or tool-roundtrip errors
+
+Local scaffold/build and stub verification can run without an API connection (dependencies and
+browser tooling must already be available). `link`, `pull`, `create`, `list`, `deploy`, live verification
+and Store operations require the intended backend. Never bypass it.
+
+### Stale bundle in Portal after an update
+
+Every successful release gets a new integer deployment version. Read back that version, then use
+normal refresh/navigation to load it. Never overwrite or decrement an existing deployment version.