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

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

@@ -0,0 +1,142 @@
+# View authoring
+
+A view is the presentation of a Space. A record opens in a view; its database has
+one main view. Words in links describe the destination, while IDs choose it.
+Get links from write results or `LOCAL_NOTIS_FIND_VIEWS`, not by joining labels.
+
+## Start from the collection scaffold
+
+```bash
+notis spaces init "Notes" ./notes --database-key notes --path notes
+notis spaces build ./notes --space collection
+```
+
+`init` is local only. For an existing Space, pull its exact ID instead. Keep its
+lock and local source key; one build/deploy changes that selected Space only.
+A container has children but no page; page-only params/shows/memory belong on views.
+
+## A complete view declaration
+
+The linked `notes` resource below must already resolve to this installation's
+native database. Descriptions explain what a person or agent can do here.
+
+```ts
+import { defineSpace } from '@notis/sdk/config';
+
+export default defineSpace({
+  specVersion: 2,
+  name: 'Notes',
+  path: 'notes',
+  description: 'Browse notes and open one with its files.',
+  readableContext: 'The note parameter opens one note. The list shows all notes available through this Space.',
+  entry: './view.tsx',
+  resources: { notes: { kind: 'database', key: 'notes' } },
+  collection: { database: 'notes', titleProperty: 'title' },
+  params: {
+    note: { type: 'record', database: 'notes', main: true,
+      description: 'The note to open beside the list.' },
+  },
+  shows: { notes: { database: 'notes', where: {}, open: 'note' } },
+  memory: { markdown: true, attachments: true, screenshot: false, snapshots: [] },
+  actions: {
+    read: {
+      tool: 'LOCAL_NOTIS_DATABASE_QUERY',
+      inputs: { type: 'object', additionalProperties: false,
+        required: ['request'], properties: { request: {
+          type: 'object', additionalProperties: false,
+          required: ['filter', 'page_size', 'include_content'],
+          properties: {
+            filter: { type: 'object', additionalProperties: false,
+              required: ['field', 'op', 'value'], properties: {
+                field: { type: 'object', additionalProperties: false,
+                  required: ['column'], properties: { column: { const: 'record_key' } } },
+                op: { const: 'equals' }, value: { type: 'string', format: 'uuid' },
+              } },
+            page_size: { const: 1 }, include_content: { const: true },
+          },
+        } } },
+      arguments: { database_id: { $asset: 'notes' }, request: { $input: 'request' } },
+    },
+  },
+});
+```
+
+Use `useViewParams<typeof definition>()`, `useShown('notes')`, and
+`<DocumentPage recordKey={params.note}>` (the whole note page; use `DocumentEditor` only to embed a body
+inside a layout of your own; if `spaces build` reports no `DocumentPage` export, your CLI predates it: use
+`useNotisRuntime().ui?.DocumentPage` with a `DocumentEditor` fallback, see the SDK reference). Keep hooks unconditional; conditional
+record/list branches can be separate components. The SDK reference covers the
+components and exact navigation helpers. The saved `read` action is deliberately
+constrained to one native record for body/Site reads; `shows.notes` owns the
+Editor’s collection list. Keep both tied to the same declared resource.
+
+## Params and declared lists
+
+- Param types: `record`, `enum`, `text`, `number`, `date`, `boolean`. Each needs a
+  description. Enum values and defaults are typed; a required param has no default.
+- Record params name a declared database and have no default record. `main: true`
+  claims that database's main view. `slugProperty` is a title/number property used
+  for readable link text, not record identity.
+- `path` is descriptive lowercase words, up to four slash-separated segments;
+  do not put IDs, credentials or reserved product routes in it.
+- `shows` for native data is `{database, where, open?}`. `where` is the native filter
+  grammar and is what `useShown` executes, not commentary beside a different query.
+  `open` names a record param over the same database.
+- A project-scoped task list can use
+  `{field: {property: 'Project'}, op: 'contains', value: '{project}'}` with a declared
+  project record param. `{project.Status}` reads a property of that authorized record.
+- For connected-service content use `{about, services?}` and declared actions.
+  This descriptive form is not a native executable list; use `useAction` for reads.
+- Preserve the application's real semantics and option names. For the existing
+  Tasks migration, Inbox is **Project empty OR Status equals Inbox**. Keep imported
+  rows, statuses and creation defaults; add the Inbox option only if absent. Its
+  native filter is `{or: [{field: {property: 'Project'}, op: 'is_empty'},
+  {field: {property: 'Status'}, op: 'equals', value: 'Inbox'}]}`. Other applications
+  must use their own inspected schema rather than copying these labels blindly.
+
+## Create a database in the same release
+
+Replace an existing database reference with:
+
+```ts
+resources: {
+  notes: { kind: 'database', create: {
+    name: 'Notes',
+    schema: {
+      schema_version: 1, value_encoding_version: 1, coercion_version: 1,
+      title_property_id: 'title', property_order: ['title'],
+      properties: { title: { id: 'title', name: 'Name', kind: 'title',
+        storage_family: 'textish', description: '', order: 0, config: {} } },
+    },
+  } },
+},
+```
+
+The same view declares a record param over `notes` with `main: true`. Promotion
+creates the database, link, main view, optional fictional `starterRows` and source
+atomically; a later failure leaves none of them behind. Verification does not create
+it. `create` is creation-only: later schema edits use native database tools;
+`spaces pull` refreshes the declaration from the live schema.
+
+The separate native schema-tool creation route requires `links.add` and
+`main_view: {space_id, param}` in that linked Space. Until the Space next deploys
+that main param, record links open the Space and writes return `view_warning`.
+Inspect current tools for exact argument shapes; do not repeatedly insert rows
+because a pending main view cannot yet open one.
+
+## Rendering and memory
+
+Choose [memory](memory.md) deliberately. `chrome: 'hidden'` is for full-screen
+presentations such as the HTML Space; ordinary collection views keep Portal chrome.
+A Space whose published view hides chrome starts hidden from each person's sidebar,
+like Skill review Spaces; it stays reachable by link and search, and each person
+can show it from the sidebar's hidden Spaces list or the Space's menu.
+Optional `markdown: './markdown.ts'` names a module exporting a pure function of
+`{params, shown}`. Its output must represent this view, not make hidden writes.
+Use `<RenderChartData>` with the chart's actual rows so rendered Markdown contains
+precise labels and values as well as its image.
+
+Add synthetic action/list/body/record fixtures, then build and verify. Verification
+and live rendering share the read-only renderer; fixture success does not prove
+live permissions or data. After an authorized deploy, render the returned view link
+with `notis views render` and inspect both the Markdown and full-height screenshot.

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

@@ -1,6 +1,6 @@
 ---
 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.
+description: Use when agents should work through the Notis CLI, especially to develop Notis Spaces 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"]
@@ -12,13 +12,13 @@ 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.
+1. Developing Notis Spaces (views, their source and linked Skills) 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 user wants to init, pull, build, verify, preview, deploy or promote a Notis Space 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
@@ -133,7 +133,7 @@ For hosted MCP, fetch the matching `notis://docs/notis-cli/references/<file>.md`
 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)
+- [Space 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

@@ -1,18 +1,19 @@
-# App delivery
+# Space delivery
 
-Use the canonical `notis-apps` skill’s entrypoint and [release guide](../../notis-apps/references/release.md).
+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
+## IMPORTANT: When NOT to use tool access for Space development
 
-When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for app file operations:
+When building or deploying a Space, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for source 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
+- Loading, building or publishing source -- use `notis spaces pull`, `spaces build`, `spaces verify`, `spaces preview`, `spaces deploy` and `spaces promote` as the release guide orders them
+- Validating views -- `spaces build` and `spaces verify` check declarations, fixtures and renders
+- Writing pages -- write standard Vite + React views with `@notis/sdk`, 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.
+Database schemas have two routes: the native database tool (create with `links.add`
+and `main_view`), or a `create` declaration in Space source that the deploy applies
+atomically. Tool calls are also valid for testing runtime behavior after deployment.
+`notis apps` is the legacy App group for accounts not yet moved to Spaces; a legacy
+App cannot declare Skills.

package/dist/base-skills/notis-cli/references/native-databases.md

@@ -5,17 +5,17 @@ Native Notis databases are accessed through the generic tool workflow, not a fir
 - `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
+- `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` -- create or update a database schema. A new database is linked to a Space in the same call (`links.add`) and names its main view; change a database used in Spaces through protocol 1 with its exact Space binding target
+- `LOCAL_NOTIS_DATABASE_DELETE_DATABASE` -- permanently delete a database and all its rows by `database_id`. It is refused for every database a Space links (`database_linked_to_space`: move it instead; a database used only in one Space is deleted with that Space from the bin), for a legacy App 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:
+Example workflow before building a Space view:
 
 ```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}}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_id":"<id from LIST_DATABASES>"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"protocol":1,"target":{"space_id":"<space id>","binding":"<binding id>"},"input":{"mode":"rows","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.
+Most databases are used in Spaces. Such a database is read only through one of its links: `GET_DATABASE` with a bare `database_id` returns `resolved_target` (the main view's `{space_id, binding}`), and a bare-id `QUERY` answers `database_in_spaces` with every link. Reuse that exact target with `protocol: 1`. Every database lives in a Space; a `database_slug` resolves among every database you can reach, and a slug several of them share answers `database_slug_ambiguous` with each `database_id` and its Spaces.

package/dist/base-skills/notis-cli/references/tool-examples.md

@@ -32,15 +32,15 @@ npx --package @notis_ai/cli@latest -- notis tools exec composio-googlecalendar-l
 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}}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --dry-run --arguments '{"database_id":"<tasks database id>"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"protocol":1,"target":{"space_id":"<space id>","binding":"<binding id>"},"input":{"mode":"rows","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}}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_id":"<tasks database id>"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"protocol":1,"target":{"space_id":"<space id>","binding":"<binding id>"},"input":{"mode":"rows","page_size":10}}'
 ```
 
 Connect a missing toolkit:

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

@@ -1,67 +1,41 @@
 ---
 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
+description: Discover native Notis databases and query their records with exact structured filters, current Space authority and view-qualified links.
+feature_flag: spaces
 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)
+# Native database queries
+
+Use structured native queries for filtering, sorting, counts, aggregates and
+pagination. Use memory for semantic discovery; use view rendering for what a page
+shows. The live tool `inputSchema` is authoritative.
+
+1. Discover the database and inspect its schema, property descriptions, relation
+   targets and option IDs with `LOCAL_NOTIS_DATABASE_GET_DATABASE`.
+2. Keep its exact returned native `target`, schema revision and available operations.
+   Every database lives in a Space; failed access never falls back to another owner.
+3. Use `LOCAL_NOTIS_DATABASE_QUERY` with `protocol: 1`, that `target` and direct
+   `input`. Build filters from actual field types/options. Page until the returned
+   continuation ends; one page is not the whole database.
+4. For a known record or view link, follow [Reading records](references/documents.md)
+   instead of running broad discovery. View links come from write results or
+   `LOCAL_NOTIS_FIND_VIEWS`; sensitive or stale evidence needs a fresh render.
+5. Writes use discovered native tools with current schema/record revisions and a
+   stable request ID. Dry-run first and read back the committed state. A missing
+   view link is not a failed write and does not justify repeating it.
+
+In authored Space code use `useShown` or declared actions, not account-wide tool
+calls. Load `notis-apps` for [Space authoring](../notis-apps/references/views.md);
+its hosted reference is `notis://docs/notis-apps/references/views.md`.
+
+## Guides
+
+- [Database discovery and creation](references/database-discovery.md)
+- [Structured native query grammar](references/query.md)
+- [Reading, updating and citing records](references/documents.md)
+
+Hosted MCP exposes these references under
+`notis://docs/notis-query/references/<file>.md`; load only the relevant guide.

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

@@ -1,70 +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"
-    }
-  ]
-}
-```
-
-### 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
+# 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 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.
+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`.