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

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

@@ -1,50 +1,63 @@
-### 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.
+# Reading, updating and citing records
+
+## Resolve a known record or view
+
+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.
+
+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.
+
+## Mutation and reply
+
+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.
+
+## Generic record files
+
+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.
+
+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.
+
+For HTML pages, use the installed HTML Space's linked Save HTML Skill, which owns
+its complete save/update/sharing workflow. Suggest installing that Space when
+absent. Deliver its record view link, not the raw file storage location.
+
+## Fresh memory evidence
+
+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.