@notis_ai/cli 0.2.0-beta.16.1 → 0.2.0-beta.160.1

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

@@ -0,0 +1,99 @@
+## Delivery
+
+Workspace runs released versions only. Local and cloud agents use the same
+workflow. Run Notis commands through
+`npx --package @notis_ai/cli@latest -- notis ...`.
+
+A create/edit request normally authorizes updating that app after checks pass,
+**unless user or repository policy requires explicit deployment consent**.
+Preserve authorization already given. Read-only, preview-only, and no-deploy
+instructions stop at local source, build, and stub verification: no remote
+resource mutation, app activation, or live verification. Store publication always
+needs separate explicit approval. Do not deploy just to obtain visual proof when
+deployment is not authorized; report that the host check remains unverified.
+
+## Update an app
+
+1. **Check identity.** Inspect the effective CLI profile and `apps list --json`.
+   Preserve local edits, then pull the exact editable app ID and intended
+   personal/team scope. Keep its profile-scoped link, current version, and revision.
+   Never silently advance a stale checkout or create a duplicate to avoid a conflict.
+2. **Build and inspect.** Edit the source, increment `notisAppVersion`, and update
+   `CHANGELOG.md`. Run `apps build` and automated `apps verify`, then do the
+   [visual check](design.md#look-at-the-result). For a new app, complete these
+   local checks before creating remote resources.
+3. **Prepare only missing resources.** For an existing app, retain its identity.
+   For a new app, reconcile the exact canonical name, edit permission, and scope
+   against `apps list --json`; reuse one matching editable identity, stop on
+   ambiguity, or create only when none exists. Use `apps create "<display title>"
+   <dir>` (with a verified `--team-id` for team scope), and read back the same ID.
+   Create only necessary missing databases against that app. Verify ownership
+   and database IDs before changing schemas; read back changes. Breaking changes
+   require separate coordination. Never mutate user data merely to test the UI.
+4. **Update Workspace.** Run `apps deploy` against that linked app. It builds and
+   verifies a frozen source/artifact snapshot before activation. `--skip-build`
+   accepts only unchanged valid output and still verifies. Use the supported
+   backend path; do not bypass checks or write directly to storage.
+5. **Verify delivery.** Read back the app ID, integer version, and Portal URL with
+   `apps list --json`. Run `apps verify --mode live`, then open the released app
+   inside Notis and inspect the affected screen and main interaction. Confirm the
+   intended bundle/version, not just the existence of an app with the same name.
+   A successful live harness check alone is not visual proof inside Notis.
+6. **Report accurately.** Give the app link and a brief description of what changed
+   and what was verified. Distinguish local-only, deployed and verified, deployed
+   but unverified, failed before activation, and outcome unknown. If create/deploy
+   has an uncertain outcome, reconcile its exact identity/version before retrying.
+
+## What the checks prove
+
+`build` validates the package, enforces design rules, and refreshes its embedded
+SDK. Automated `verify` checks every route at desktop (1280px) and phone (390px)
+widths, render errors, runtime calls, nested boxes, small text, lingering loading
+placeholders, and horizontal overflow. It uses a temporary server and browser;
+printed URLs or `--no-browser` are not passing verification. If tooling is missing,
+install it with `npm exec --yes --package agent-browser@latest -- agent-browser install`.
+
+Stub verification does not establish real account data, permissions, host layout,
+or visual quality. Live verification exercises the authenticated runtime but still
+uses the harness. The final installed-app check establishes the result inside Notis.
+If that surface cannot be inspected, say so rather than claim it passed. No extra
+approval round is needed for an already-authorized check.
+
+`apps screenshot` supports declared scenarios and stub fixtures, including
+`theme: 'dark'`; `--raw` gives uncomposited captures. Store listing screenshots are
+not required for an ordinary Workspace update.
+
+## Special cases — read only when relevant
+
+### Unreleased container or stale checkout
+
+An unreleased container has no source to pull. Recover its original local source,
+or scaffold only if it cannot be recovered; verify the exact ID and scope and use
+`apps link <app-id> <dir> --expected-version 0`. Reuse the container after a failed
+first release; do not duplicate or automatically delete it. If another release
+has appeared, pull it into a fresh directory and reapply the intended edits without
+replacing its deployment base. Link/deploy guards must reject races and conflicts.
+
+### Restore an older source
+
+Pull the current release into a fresh checkout and the historical source into a
+separate folder (`apps pull <id> <dir> --source-version <n>`). Replace source without
+replacing the current `.notis` link/base, then check and deploy as a new release.
+Preserve app/database/skill IDs. Never decrement versions or imply that source
+restoration undoes user data or external actions.
+
+### Release history and Store publication
+
+Keep all release history in root `CHANGELOG.md`, newest first, with headings
+`## [Release title] - YYYY-MM-DD` (or `{PR_MERGE_DATE}` while unpublished). Do not add
+`versionNotes` to the config. App Details reads deployed history; the Store reads
+its published snapshot. Local edits must not change the published listing.
+
+`apps deploy` updates Workspace only. Use `apps publish --confirm-ready` only after
+the user explicitly approves the current App Details and Store listing. Deploy the
+exact approved source first. Respect listing completeness, visibility, version,
+and pending-review guards. A public submission includes editable source, Store
+assets, source-declared database schemas, and only explicitly opted-in starter
+rows. Do not hand-edit `notis-listing.json` or strip files to pass review; fix the
+source, redeploy, and resubmit. To start from a Store app, use `apps init --from
+<slug>`; `apps pull` is for an accessible installed app, not a Store listing clone.

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

@@ -0,0 +1,62 @@
+## 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 |
+
+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,140 @@
+---
+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.
+feature_flag: cli_access
+mcp_resource: true
+mcp_tool_patterns: []
+mcp_references: ["references/app-delivery.md", "references/tool-examples.md", "references/native-databases.md", "references/troubleshooting.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)

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/native-databases.md

@@ -0,0 +1,20 @@
+## 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)
+
+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.

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

@@ -0,0 +1,67 @@
+---
+name: notis-query
+description: Use when agents need to query native Notis databases with direct structured filters, sorts, and pagination through `LOCAL_NOTIS_DATABASE_QUERY`.
+feature_flag: store
+mcp_resource: true
+mcp_tool_patterns: ["LOCAL_NOTIS_DATABASE_*"]
+mcp_references: ["references/database-discovery.md", "references/documents.md", "references/query.md"]
+---
+
+# Notis Query Skill
+
+Use this skill when the user wants to search, filter, sort, or page through records in a native Notis database and the task is best handled with structured criteria instead of semantic search.
+
+This skill is the single source of truth for `LOCAL_NOTIS_DATABASE_QUERY`.
+
+## Canonical contract source
+
+For custom view runtime usage, the canonical contract is always MCP `tools/list` `inputSchema` for `LOCAL_NOTIS_DATABASE_QUERY`.
+
+- Use `notisView.listTools()` (or MCP `tools/list`) to read the live schema.
+- Use `notisView.callTool("LOCAL_NOTIS_DATABASE_QUERY", args)` (or MCP `tools/call`) with arguments that match that schema exactly.
+- If this skill text and `inputSchema` ever differ, follow `inputSchema`.
+
+This keeps query arguments aligned with the same tool definitions used by agent runtime and avoids maintaining duplicate schema formats.
+
+## When to use `LOCAL_NOTIS_DATABASE_QUERY`
+
+Use `LOCAL_NOTIS_DATABASE_QUERY` when:
+
+- you already know the target native database
+- the user wants structured filtering or sorting
+- you need predictable pagination over database rows
+- you need to find records before reading or updating a specific document
+- you need to find matching records before calling `LOCAL_NOTIS_DATABASE_GET_DOCUMENT` or a generated database upsert tool
+- the task should use direct database criteria instead of semantic memory search
+
+Do not use `LOCAL_NOTIS_DATABASE_QUERY` when:
+
+- the relevant database is unknown
+- semantic search over broad workspace context is better
+- the task points to one known document by `document_id` or portal URL
+
+Use these tools together:
+
+- `LOCAL_NOTIS_DATABASE_LIST_DATABASES` to discover available databases and confirm the slug
+- `LOCAL_NOTIS_DATABASE_GET_DATABASE` to inspect read-only schema detail, ordered properties, options, and relation targets
+- `LOCAL_NOTIS_DATABASE_QUERY` to find matching records
+- `LOCAL_NOTIS_DATABASE_GET_DOCUMENT` to inspect one specific matching document in full
+- generated database upsert tools to update or create records after you know the right document or relation IDs
+
+Follow the same workflow and use the exact canonical tool names available in the current runtime.
+
+Every database has one owning app; inspect its identity/schema before schema writes.
+Known document IDs/URLs use the document guide, not a broad query. For queries,
+use the query guide for exact filter/property/pagination rules; live inputSchema
+is authoritative. Dry-run writes and read back the resulting state.
+
+## 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-query/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.
+
+- [Native Database Workflow](references/database-discovery.md)
+- [Reading documents](references/documents.md)
+- [Supported execution mode](references/query.md)

package/dist/base-skills/notis-query/references/database-discovery.md

@@ -0,0 +1,59 @@
+## Native Database Workflow
+
+### Listing databases
+
+Use `LOCAL_NOTIS_DATABASE_LIST_DATABASES` (`notis_list_databases` in legacy
+underscore-form references) when:
+
+- you need to confirm which native databases exist
+- you need the database ID or slug before querying or choosing an upsert tool
+- you need database metadata such as name, description, or document counts
+- the orchestrator asks what is available in the user's workspace
+
+Always inspect the user's native Notis databases before creating schema updates or choosing where to save work.
+
+### Creating databases
+
+Use `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` (`notis_upsert_database` in legacy
+underscore-form references) to create or update native databases.
+
+Every native database must belong to a Notis app. When creating a database,
+pass the owning app's slug or id in the `app` field; if the user has no
+suitable app yet, create one first with `LOCAL_NOTIS_CREATE_APP`. Updates do
+not need the `app` field.
+
+Define schemas with appropriate property types:
+
+- `title`
+- `rich_text`
+- `select`
+- `multi_select`
+- `status`
+- `checkbox`
+- `date`
+- `number`
+- `url`
+- `email`
+- `phone_number`
+- `relation`
+
+When adding or updating a `relation` property, always pass the target database explicitly with `database_id`. Do not rely on description text to imply the relation target.
+
+Example relation update:
+
+```json
+{
+  "operation": "update",
+  "database_id": "tasks-db-id",
+  "properties": [
+    {
+      "property_id": "prop_list",
+      "name": "List",
+      "action": "update",
+      "type": "relation",
+      "database_id": "lists-db-id",
+      "description": "Relation to Lists"
+    }
+  ]
+}
+```

package/dist/base-skills/notis-query/references/documents.md

@@ -0,0 +1,50 @@
+### Reading documents
+
+Use `LOCAL_NOTIS_DATABASE_GET_DOCUMENT` when:
+
+- the task references a specific document by `document_id` or portal URL
+- detailed content from a known document is needed
+
+You may pass either a `document_id` or a portal URL such as `https://app.notis.ai/documents/abc123` or `/documents/abc123`.
+
+## Native Document Handling
+
+### Response requirements
+
+- Always include the document title, database name, and a markdown portal link for any document you create or update.
+- Never expose a raw `document_id` in your completion summary unless the user explicitly asked for it.
+- Clearly state whether the document was created or updated.
+- For updates, clearly state whether you replaced the original content or appended to the end.
+
+### Upserting with relations
+
+When upserting into a database that relates to another database, first query for the related record and use the returned `document_id` for the relation.
+
+### Upserting complex documents
+
+For copywriting-style work such as articles or social posts, try to find similar writing by the user and match the user's style and tone.
+
+### Updating a document
+
+1. Retrieve the current content with `LOCAL_NOTIS_DATABASE_GET_DOCUMENT`, `LOCAL_NOTIS_DATABASE_QUERY`, or `LOCAL_NOTIS_SEARCH_MEMORIES` with `memory_kind="native_document"`.
+2. Use the relevant `LOCAL_NOTIS_DATABASE_UPSERT_<DATABASE_SLUG>` tool with the existing `document_id` so the document is updated instead of recreated.
+3. For local edits to an existing document such as appending a bullet, inserting a paragraph, changing one section, or preserving structure, use `edit_mode = "block_operations"` instead of rewriting markdown.
+4. When developer context includes a `<page_context ... resource_type="document" ...>` tag, treat that as the currently open document and fetch it before asking the user for any identifier again.
+
+### Default upsert preferences
+
+As long as they do not conflict with the user's intent, the existing document style, or the tool contract:
+
+- Prefer updating existing documents over creating new ones when the user asked for a modification.
+- Use `replace = true` to replace content and `replace = false` to append when you are in markdown mode.
+- When the user asked to append, insert, tweak, or preserve the rest of an existing document, prefer `block_operations` with `insert_blocks`, `update_block`, `replace_blocks`, or `remove_blocks`.
+- Do not use markdown rewrite mode for surgical edits unless block operations are genuinely impossible for the requested change.
+- Reorganize messy thoughts into a clearer structure.
+- Highlight essential concepts and extract action items.
+- Format notes with markdown titles, subheadings, bold text, blockquotes, ordered lists, and unordered lists when helpful.
+- Add useful insight, challenge weak reasoning, debunk false claims, or enrich the content when appropriate.
+- Fill in missing information the user asked you to complete when the context supports it.
+- Imitate the user's voice when you can infer it from semantic memory search with `memory_kind="native_document"` or existing document context.
+- Save images in document content using standard markdown and in URL properties when relevant.
+- Do not place videos inside document content. Store them only in media properties.
+- Do not add a custom emoji or cover unless the user requested one.