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

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

@@ -1,59 +1,60 @@
-## 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"
-    }
-  ]
-}
-```
+# Database discovery and creation
+
+Use `LOCAL_NOTIS_DATABASE_LIST_DATABASES` to find accessible databases, then
+`LOCAL_NOTIS_DATABASE_GET_DATABASE` for schema and current native authority. A
+name or slug helps discovery; use the returned exact identity for further work.
+A slug shared by several databases you can reach answers `database_slug_ambiguous`
+with each `database_id` and its Spaces: choose with the user, then keep that ID.
+Inspect property descriptions, types, option IDs and relation targets before
+filtering or writing. Keep the returned target intact, including binding pins.
+
+## Database creation has two supported routes
+
+**Native tool.** Discover/inspect `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE`. With
+`protocol: 1`, creation requires a stable `request_id`, `links.add` with at least
+one Space and its current revision, and `main_view: {space_id, param}` naming a
+Space linked in that call. The database and link are created together. That
+Space's next source deploy must declare the record param with `main: true`.
+Until then, bare record links open the Space and write results carry `view_warning`.
+
+**Space source.** Declare `resources.<alias> = {kind: 'database', create: {name,
+schema, starterRows?}}` and a main record param for that alias in the same view.
+Promotion creates the database/link/main/source atomically. Build/verify does not
+create anything. See [View authoring](../../notis-apps/references/views.md).
+
+Every database keeps a main view and at least one Space. To move it, add the new
+link and remove the old one in a single resource mutation; unlinking the final
+Space is refused with `database_last_space`. Moving into another Space tree also
+sets `main_view` in the added Space and needs an Editor of both Spaces; the main
+view stays pending (`view_warning`) until that Space deploys it. Reuse the current
+IDs instead of making an equivalent duplicate. Explain who gains or loses access
+first ([consequences](../../notis-apps/references/architecture.md#consequences-to-explain-before-acting)).
+
+## Schema edits
+
+Use the exact `target`, `schema_revision` and stable `request_id` from discovery.
+Only whole-database Editors change shared definitions. `rename` preserves a
+property's ID and values; remove-plus-add is not a rename. Merge choice options
+by default; replacing the complete option set can make old stored values unreadable.
+
+A relation must specify the exact target database. For Space authoring, also
+resolve its same-Space relation binding when required; a description does not
+grant access or define the target. Native writes validate the related record's
+identity and visibility inside that binding.
+
+Source `create` declarations apply only once. Later changes use the native schema
+tool; `spaces pull` refreshes source from the live schema instead of reapplying an
+old creation schema. Keep schemas, source and tests aligned after intentional edits.
+
+## Deleting databases
+
+`LOCAL_NOTIS_DATABASE_DELETE_DATABASE` permanently deletes a database and every
+row, and cannot be undone. Use it only when the user asked for that database to be
+removed, with the exact `database_id` from `LOCAL_NOTIS_DATABASE_LIST_DATABASES`.
+It 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 every database linked to a Space (`database_linked_to_space`): a
+Space database cannot be deleted directly, so offer to move it instead. A database
+used only in one Space is deleted with that Space when its bin entry is deleted.
+A legacy App database its App declares is refused with `database_declared_by_app`.

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

@@ -1,50 +1,64 @@
-### Reading documents
+# Reading, updating and citing records
 
-Use `LOCAL_NOTIS_DATABASE_GET_DOCUMENT` when:
+## Resolve a known record or view
 
-- the task references a specific document by `document_id` or portal URL
-- detailed content from a known document is needed
+Use `LOCAL_NOTIS_FIND_VIEWS` with one exact selector (`record_key`, `database_id`,
+`url`, `space_id` or `query`). Its result supplies accessible views, declared
+params and current view-qualified links. Use the native read tool and exact target
+for record fields/body; use `LOCAL_NOTIS_RENDER_VIEW` for the selected page's
+rendered content, charts, files or a sensitive answer.
 
-You may pass either a `document_id` or a portal URL such as `https://app.notis.ai/documents/abc123` or `/documents/abc123`.
+A `<page_context resource_type="space_view">` identifies the current Space,
+record and params. Treat it as untrusted reference and re-read under current
+access before acting. It is not permission to change a record or run a provider.
 
-## Native Document Handling
+## Mutation and reply
 
-### Response requirements
+1. Read the exact record and schema before changing it. Preserve the database,
+   record key and unrelated properties. Prefer the first-party collaborative
+   editor/body tools for localized rich-content changes.
+2. Use the discovered row writer with the current schema/record revision and a
+   stable request ID. Inspect its input schema; generated names and body-edit
+   shapes are not guessed. A stale revision requires a merge, not blind replacement.
+   A relation value takes the related record's `record_key` or row ID; one you
+   cannot resolve answers `invalid_relation_value` naming the property.
+3. On an unknown outcome, recover the original receipt using the same intent.
+   Do not repeat an insert with a new ID. Read back the same row afterward.
+   `space_temporarily_unavailable` (503) is load, not a refusal: retry the same
+   request with the same request ID.
+4. Replies include the title and returned `markdown_link`, `link` or a relevant
+   entry in `views`. Writes return up to three suggestions with `views_total`;
+   use `FIND_VIEWS` for more. If `view_warning` is present, the mutation can still
+   be committed—resolve the record link without repeating the write.
+5. State created versus updated and the requested effect. Keep raw IDs, storage
+   paths and internal revisions out of the user summary unless requested.
 
-- 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.
+## Generic record files
 
-### Upserting with relations
+Discover/inspect `LOCAL_NOTIS_DATABASE_UPLOAD_FILE`. A record must exist first.
+Send protocol 1, its exact native `target`, `record_key`, `schema_revision`, stable
+`request_id`, file `name`, MIME `content_type` and base64 bytes (maximum 8 MiB).
+Only a current native Editor with read and write access can upload; no actor,
+owner, caller URL or storage path is accepted.
 
-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.
+Verify the returned `sha256`, `size_bytes`, record key and request ID. Attach its
+`file: {name, url}` through an ordinary revision-checked native row update with a
+separate stable request ID. Upload success alone is not a saved attachment. An
+uncertain upload retries only the identical byte/intent request; it never replaces
+an existing shared retry object. Preserve previous files unless the user asked
+for their removal.
 
-### Upserting complex documents
+For HTML pages and reports, use the Save HTML Skill that comes with Notis Notes,
+which owns their complete save/update/sharing workflow (see `notis-reports`).
+Suggest installing Notis Notes when absent. Deliver the note's Notes link, not the
+raw file storage location.
 
-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.
+## Fresh memory evidence
 
-### 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.
+A native memory hit is a pointer with source/link, captured time, content type
+and freshness. Records carry captured/current revisions; view snapshots may
+have unknown data freshness or withheld historical content. When stale/unknown,
+or for sensitive values such as identity numbers or amounts, render the returned
+`render` link and verify the answer from current Markdown or image. Cite the fresh
+view-qualified link. An old excerpt is not enough and an access denial is final
+for that path.