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

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,70 @@
+## 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"
+    }
+  ]
+}
+```
+
+### Deleting databases
+
+Use `LOCAL_NOTIS_DATABASE_DELETE_DATABASE` only when the user asked for a database
+to be removed: it permanently deletes the database and every row, and cannot be
+undone. Pass the exact `database_id` from `LOCAL_NOTIS_DATABASE_LIST_DATABASES`.
+The tool refuses while another database has a relation property pointing to it or
+an automation is triggered by it, and lists them; remove those first (delete the
+relation property with `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE`, action `remove`).
+It also refuses a database its app declares, because the app recreates it empty the
+next time it loads: remove it from the app's databases and deploy, or delete the app.

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.