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

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

@@ -1,72 +1,93 @@
 ---
 name: notis-apps
-description: Design and package Notis apps, or inspect their live views and resources. Use when users want an installable Notis app or need rendered content, charts, or filters that ordinary data tools do not provide.
-feature_flag: store
+description: Explain Notis Spaces, sharing, resource links and lifecycle; build or update their views and linked Skills, or inspect a saved view with its current data.
+feature_flag: spaces
 mcp_resource: true
-mcp_tool_patterns: ["LOCAL_NOTIS_INSTALL_APP"]
-mcp_references: ["references/release.md", "references/architecture.md", "references/design.md", "references/sdk.md", "references/troubleshooting.md", "references/reading.md", "references/context.md"]
+mcp_tool_patterns: ["LOCAL_NOTIS_INSTALL_APP", "LOCAL_NOTIS_MANAGE_SPACE", "LOCAL_NOTIS_FIND_VIEWS", "LOCAL_NOTIS_RENDER_VIEW"]
+mcp_references: ["references/release.md", "references/architecture.md", "references/design.md", "references/sdk.md", "references/views.md", "references/memory.md", "references/troubleshooting.md", "references/reading.md", "references/context.md"]
 ---
 
-# Notis Apps
-
-Build apps that feel native to Notis: compact, readable, responsive, and useful.
-Use Vite + React, `@notis/sdk`, and the existing scaffold components. Use the Notis
-CLI for app operations: `npx --package @notis_ai/cli@latest -- notis ...`.
-
-## Read existing apps and resources
-
-Use ordinary data tools for straightforward reads. When the task needs a live
-render, chart, filter, or visual inspection, follow [Read Notis web content](references/reading.md).
-It covers apps, views, reports, HTML and file documents without requiring the
-user to open Portal or Desktop. Use the agent's available browser capability;
-this is not an app build, deployment, or Portal editing-context workflow.
-
-## Build → inspect → fix → deliver
-
-For every app UI create/edit task, read both [Design](references/design.md) and
-[Delivery](references/release.md). Then:
-
-1. **Understand the result.** Identify the main user action and the requested
-   change. For a reported visual bug, describe what is wrong in the actual
-   screen before editing. Preserve what already works.
-2. **Start from native patterns.** Pull the existing app or choose the closest
-   Store scaffold. Use the appropriate page layout instead of inventing a new
-   visual system. Make routine choices yourself; ask only for missing decisions
-   that materially change the result.
-3. **Build, look, improve.** Run build and verification, then actually inspect
-   the rendered app. Follow the short visual check in the design guide. Fix what
-   is wrong and recheck the affected screen; a passing build is not visual approval.
-4. **Deliver the checked result.** Follow the delivery guide and existing user
-   authorization. Confirm the released result inside Notis before calling it
-   verified. Say plainly what is local, deployed, or still unverified.
-
-## Keep these boundaries
-
-- User and repository instructions take precedence, including preview-only,
-  no-deploy, and explicit-consent requirements. Store publication is separate.
-- Preserve the exact app identity, account/team scope, permissions, and user data.
-  Reconcile an uncertain release instead of blindly retrying it.
-- Before Store submission, complete the [publication privacy and portability gate](references/release.md#publication-privacy-and-portability-gate).
-  Public examples must be fictional; never publish the owner's workspace data.
-- Use SDK hooks and declared tools. Let Notis own its sidebar, search, runtime,
-  and rendering boundary; do not query host DOM or recreate that chrome in the app.
-
-## References — only as needed
-
-- [SDK hooks](references/sdk.md): reads, edits, selection, and navigation.
-- [App contracts](references/architecture.md): configuration, packaging, and data ownership.
-- [Troubleshooting](references/troubleshooting.md): a specific failure or mismatch.
-
-The CLI distributes this skill and its references from the canonical product
-source. Do not maintain competing copies.
-
-## Shared views, independent reports and feedback
-
-Use a shared app view when many records should share one implementation. Use
-`notis-reports` when an app-owned record needs its own independently authored
-SDK presentation. A report is not a new app, and changing it must not deploy or
-replace shared app routes. The agent chooses live data versus captured results.
-
-Share selected text, comments, loaded resources or app-defined annotations through
-[generic context pills](references/context.md). Apps own annotation storage and
-presentation; the chat owns unsent context drafts. Passive context is not execution approval.
+# Notis Spaces
+
+Build compact, readable views with Vite, React and `@notis/sdk`. A Space owns its
+presentation; native databases hold its records. Use the pre-authenticated Notis
+CLI locally or on the cloud computer: `npx --package @notis_ai/cli@latest -- notis`.
+Discover tools and inspect their live schemas before using them.
+
+## Choose the workflow
+
+| Task | Read |
+| --- | --- |
+| Build or change a Space | [View authoring](references/views.md), [Design](references/design.md), then [Delivery](references/release.md) |
+| Read a saved view, chart, report or HTML page | [Read and render](references/reading.md) |
+| Choose a memory policy | [Memory](references/memory.md) |
+| Compose records, navigation or declared reads | [SDK](references/sdk.md) |
+| Explain resources, sharing and lifecycle | [Platform boundaries](references/architecture.md) |
+| Diagnose a failed check or release | [Troubleshooting](references/troubleshooting.md) |
+
+Use ordinary native data tools when they answer the question. For what a page
+actually displays, resolve its current link and render the deployed view.
+
+## Author → verify → deliver
+
+1. Read the exact existing Space and its resources. Preserve IDs, schemas, data,
+   source revision and the deployment lock. A familiar name is not identity.
+2. Pull editable source with `notis spaces pull`. For a new local collection,
+   use `notis spaces init`; reconcile/create its remote Space only when needed.
+3. Every view declares `specVersion: 2`, `path`, `description`, `readableContext`,
+   typed `params`, executable `shows` and an explicit `memory` policy. A native
+   record param identifies the database it opens; its one main view declares
+   `main: true`. Use `useViewParams` and `useShown` in the actual page.
+4. Build and verify the selected frozen source. Keep explicit fictional fixtures
+   for all reads. Inspect EN/FR at 390px and 1440px. Fix failed reads, clipping,
+   wrong data and state transitions before release.
+5. Deploy/promote within the user's authorization. Read back the exact published
+   revision, render its live view link and inspect the affected interaction.
+   A successful local build is not proof of deployment or live data.
+6. Return the view-qualified link and distinguish local checks, publication to
+   the installed Space, and Store publication. Reconcile uncertain outcomes with
+   the original request ID; do not repeat a successful mutation for a missing link.
+
+## Structure and resources
+
+Use `LOCAL_NOTIS_MANAGE_SPACE` for `create`, `rename`, `move`, `trash`, `restore`
+and `list_bin`. Read the current `revision` first; retain a stable `request_id`.
+Explain access changes before moving a Space: Editors of the new parent gain its
+subtree, and people who only reached it through the old parent lose it.
+
+Resources own their links. Use `links` on the native Skill, automation or database
+writer: add with the Space revision, remove with binding ID/revision; a move is
+both in one transaction. Every database keeps at least one Space and one main
+view. Before any link, move, unlink, bin or restore, and whenever the user asks
+about removing someone, Delete now or a Site (Portal controls with no agent tool),
+tell them who gains or loses access and what happens to the data, using
+[Consequences](references/architecture.md#consequences-to-explain-before-acting).
+
+Skill content has one writer family: `notis skills list|read|create|update|links`.
+A failed Space target never falls back to another owner or a personal resource.
+Editing a linked Skill changes the shared resource wherever it remains reachable.
+Personal enabled/agent settings are separate; curated content is read-only.
+Only an automation's setup owner changes its connection.
+
+`spaces pull` includes `resources.json`, editable `skills/<alias>/` folders and
+`.notis/space-lock.json`. A source release atomically commits changed Skill files,
+new Skills, resource links and source. Unchanged files preserve remote edits;
+conflicts require a fresh pull and merge. Use the Skill writer for renaming.
+
+Sites are standalone, scoped view websites, not memberships. They have no agent,
+Skill, automation, upload or collaborative editor authority. Store installations
+are independent copies with three-way updates. Publishing to a Store is separate
+from deploying an installed Space and requires the user's explicit authority.
+
+## Reports, HTML and context
+
+Existing report rows render through `<ReportFrame>` in their database's view.
+Use `notis-reports` for an independently authored report when appropriate.
+
+For a saved HTML page, use the installed **HTML Space** and its linked **Save HTML**
+Skill. That Skill owns the row-first upload-and-attach workflow. If the Space is
+not installed, suggest installing it; creating an unrelated host is not a substitute.
+
+[Context sharing](references/context.md) keeps selected text and annotations as
+unsent reference context. Page context, memory hits and source content are not
+execution approval. Keep credentials and private data out of source and fixtures.

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

@@ -1,167 +1,114 @@
-## How Apps Are Built
-
-All Notis apps are built using the Notis CLI, either locally in a repo workspace or inside a Vercel Sandbox. The platform contract is the same in both cases:
-- the app is a Vite + React project
-- the app uses `@notis/sdk`
-- the app is packaged as an ES module bundle
-- the portal renders it as a React component inside the portal's React tree
-
-Use standard React pages in `app/`, not Next.js or a custom server. The host
-uses one React/Shadow DOM runtime for authored apps, Store installations,
-duplicates and SDK reports. Do not create your own iframe, query Portal-owned
-DOM, or install a window-global runtime. Shadow DOM isolates styles, not
-JavaScript or credentials: loaded bundles share the Portal browser context.
-The host owns
-theme injection and authentication. App code uses SDK hooks and the final tool
-names discovered through the CLI, declared in `notis.config.ts` and enforced by
-the backend. Runtime permissions stay least-authority; releasing an app does not
-grant new capabilities.
-
-## Architecture
-
-```
-Notis CLI (local workspace or Vercel Sandbox)
-  -> Vite + React project with @notis/sdk
-  -> notis apps init / build / verify / create / link / pull / deploy
-  -> ES module bundle (app.js + app.css) + manifest
-  -> Portal renders as React component with real tools/databases
-```
-
-`deploy` updates the linked installed app for the current account or team. After the user explicitly confirms the App Details page is ready, `apps publish --confirm-ready` submits that deployed version to the Team or Public Store review flow.
-
-### Key Components
-
-1. **@notis/sdk** (`packages/sdk/`) -- SDK for app developers
-   - `@notis/sdk` -- NotisProvider, runtime hooks, editors, selection helpers, and shortcut primitives
-   - `@notis/sdk/interactions` -- headless collection actions and interaction types
-   - `@notis/sdk/config` -- `defineNotisApp()` for notis.config.ts
-   - `@notis/sdk/vite` -- `notisViteConfig()` for vite.config.ts
-   - `@notis/sdk/styles.css` -- shadow-safe app shell styles and base app-surface classes
-
-2. **CLI** (`packages/cli/src/command-specs/apps.js`) -- release delivery uses init, build, verify, create, deploy, link, pull, doctor, and list
-
-3. **Server** (`server/routers/portal_views/`) -- Returns signed bundle URLs, proxies tool calls
-
-4. **Portal** (`portal/src/components/apps/`) -- Renders app bundles as React components via AppViewRenderer
-
-### Runtime Bridge
-
-Apps communicate with the platform through the `NotisRuntime` interface, provided by the portal via React context:
-
-- **Portal**: the portal creates a real `NotisRuntime` and passes it as a prop to `NotisProvider`. All calls go to `/portal_views/runtime_query` via fetch with the user's JWT.
-- The portal mounts the app inside a shadow-scoped content surface and injects the runtime before app mount. There is no supported window-global runtime fallback.
-
-App code never accesses the runtime directly -- it uses SDK hooks (`useTool`, `useTools`, `useNotis`, etc.) which read from the `NotisProvider` context.
-
-## Manifest Format
-
-Generated by `npx --package @notis_ai/cli@latest -- notis apps build` at `.notis/output/manifest.json`:
-
-```json
-{
-  "version": 1,
-  "spec_version": 4,
-  "app": { "name": "My App", "slug": "my-app", "title": "My App", "description": "...", "icon": "phosphor:..." },
-  "routes": [
-    {
-      "path": "/",
-      "slug": "index",
-      "name": "Dashboard",
-      "icon": "phosphor:squares-four",
-      "default": true,
-      "export_name": "index",
-      "collection": null
-    }
-  ],
-  "bundle": {
-    "js": "bundle/app.js",
-    "css": "bundle/app.css"
-  },
-  "databases": ["tasks", { "slug": "templates", "seed_documents": true }],
-  "tools": ["LOCAL_NOTIS_DATABASE_QUERY"]
-}
-```
-
-Use the exact final names returned by tool discovery for explicit app tool declarations. App-specific TypeScript shapes for tool arguments and results live in the app code; the SDK exposes generic tool hooks alongside its native database hooks.
-
-Routes are canonical: define navigation in `routes`, give every route an explicit
-`slug`, and do not rely on legacy `views`. A configured `collection.sidebar` tree
-belongs to the host, not app JSX.
-
-Database strings package schema only. The object form shown above opts that database into copying its current rows as Store starter content. Use it sparingly and only for non-personal fixtures/templates every installer is meant to receive.
-Never seed user-created notes, history, leads, or other private records. In source
-config the explicit opt-in is `{ slug: 'templates', seedDocuments: true }`.
-
-For a read-only database catalog app, declare `["LOCAL_NOTIS_DATABASE_LIST_DATABASES", "LOCAL_NOTIS_DATABASE_GET_DATABASE"]`. Use the list tool for the left/catalog pane and the get tool for the selected database detail pane.
-
-## Database Schema
-
-### apps table
-
-| Column | Type | Description |
-|---|---|---|
-| id | uuid PK | App ID |
-| user_id | uuid FK | Owner |
-| team_id | uuid FK | Team (nullable) |
-| name | text | Display name |
-| slug | text UNIQUE | URL slug |
-| description | text | App description |
-| icon | text | Phosphor icon (e.g. "phosphor:list") |
-| status | text | draft, active, archived |
-| visibility | text | private, team |
-| manifest | jsonb | Latest deployed manifest |
-| current_version | integer | Version counter |
-| source_listing_id | uuid FK | Source App Store listing for installed store apps; cleared when submitted as a derivative |
-| installed_snapshot | jsonb | Store-installed baseline used for update/reset comparison |
-| customization_overlay | jsonb | User changes over the installed store baseline |
-| update_status | text | up_to_date, update_available, needs_resolution, update_failed |
-| bundled_automation_ids | uuid[] | Linked automations |
-| bundled_skill_ids | uuid[] | Linked skills |
-
-### databases ownership
-
-Every row in the `databases` table carries `owner_app_id` (uuid FK to
-`apps.id`, `ON DELETE CASCADE`): a database belongs to exactly one app, and
-deleting the app deletes its databases and their documents (`documents` cascade
-from `databases`). Install, resource preparation, and Store updates stamp
-`owner_app_id` automatically; standalone creation requires the `app` argument.
-The app config references existing database slugs; it does not own the schema.
-The database row is the schema source of truth. Treat deployed slugs as stable
-contracts: rename display titles rather than changing slugs behind live callers.
-
-### Storage (Supabase)
-
-Files stored in `app-code` bucket at `{app_id}/v{version}/`:
-- `manifest.json`
-- `bundle/app.js`
-- `bundle/app.css`
-
-Editable source snapshots are stored in the private `app-source` bucket at
-`{app_id}/v{version}/`. Portal App Store listing screenshots are uploaded to
-the public `app-listing-assets` bucket before submission.
-
-### Related tables
-
-- **databases** -- Apps reference these rows by slug. Schema lives on the database row (`schema_metadata` / `original_fields`), not in the app manifest.
-- **documents** -- `database_id` links to databases. Properties in `properties` jsonb.
-- **app_store_listings** -- Snapshots for publishing to the app store.
-- **app_submissions** -- Portal review submissions keyed to an app source version and registry slug.
-
-## Server Endpoints
-
-| Endpoint | Method | Purpose |
-|---|---|---|
-| `/portal_views/get` | GET | Route detail + runtime descriptor with signed bundle URLs |
-| `/portal_views/runtime_query` | POST | Proxy tool calls and DB operations |
-| `/portal_views/collection_items` | GET | List collection items |
-| `/portal_views/collection_tree` | GET | List normalized collection tree nodes for a tree sidebar route |
-| `/portal_views/collection_tree/create` | POST | Create a root or child collection row from the sidebar |
-| `/portal_views/collection_tree/rename` | POST | Rename a collection tree item inline |
-| `/portal_views/collection_tree/delete` | POST | Delete a collection tree item from the sidebar |
-| `/portal_apps/list` | GET | List apps |
-| `/portal_apps/get` | GET | Get app detail |
-| `/portal_apps/publish` | POST | Submit a deployed app source snapshot for public store review |
-| `/portal_apps/listing_assets/upload` | POST | Legacy pre-manifest screenshot upload; do not use for current manifest-media workflows |
-| `/portal_apps/submissions` | GET/PATCH | List or edit App Store submissions |
-| `/portal_apps/submissions/withdraw` | POST | Close a pending App Store submission |
-| `/cli_tools` | POST | CLI tool execution (save_app_files, create_app, etc.) |
+# Platform boundaries
+
+A Space is a place with Editors, resources and optional child Spaces. A view is
+that Space's presentation. A collection is a view over native records. The Python
+backend owns authority, schema validation, connections, billing and orchestration.
+
+## Source and runtime
+
+Use a Vite/React project with `@notis/sdk`; the selected source compiles to an ES
+module and stylesheet. `defineSpaces` indexes independently deployable definitions;
+`defineSpace` declares one Space. The CLI generates the manifest—edit source,
+not generated metadata. [View authoring](views.md) owns its declaration contract.
+
+The Portal renders authored code in a React/Shadow DOM host. Shadow DOM isolates
+styles, not JavaScript authority. SDK hooks receive an opaque scoped runtime;
+source has no account-wide tool, JWT or backend transport. Declare actions and
+resource aliases; the backend resolves exact bindings and saved authorizations.
+Renderers get read-only snapshots, not an editor room or reusable account credential.
+
+Native viewer reads are different: `viewerReads: ['databases', 'skills']` lets a
+signed-in viewer inspect only resources they can already reach, read-only. They
+are unavailable to anonymous Sites. A shared database list uses `shows` instead.
+
+## Ownership and sharing
+
+Every database stays linked to at least one Space and has one main view. A link
+makes the resource reachable to that Space's Editors; it is not a copy. The same
+Skill may be edited through several Spaces without becoming several Skills.
+A failed target never falls back to a different authority.
+
+The protected owner and Editors of a Space and its ancestors can reach it.
+Moving a subtree changes who can reach every child/resource; report the actual
+access delta before moving. Removing an Editor or unlinking a resource revokes
+future reads, writes and memory access through that path.
+
+A Site is a scoped standalone website, not an Editor membership. Record Sites
+stay pinned to their record, including views whose record param is not the
+collection database. First-party body/properties/HTML are read-only snapshots.
+Share controls, uploads, collaboration, agents, Skills and automations are not
+available in that anonymous runtime. See the Site consequences below for its
+declared reads, actions and billing.
+
+## Consequences to explain before acting
+
+For each requested change, explain who may act, who gains or loses access, what
+happens to data and links, and the applicable defaults, limits and recovery
+options below. Preserve conditional consequences even in a short answer;
+translate implementation fields into their practical effect. Before an actual
+change, explain its consequences and act only within the user's authorization.
+Live tool schemas own the arguments.
+
+- **Link** (`links.add` on the Skill, automation or database writer): Editors of
+  that Space and of every Space above it gain the resource. It stays one resource
+  with the same ID: nothing is copied, no grant or connection moves, and an edit
+  shows through every reachable link. Requires Editor on the Space and edit rights
+  on the resource.
+- **Move** (`links.add` plus `links.remove` in one update): the new Space's people
+  gain it; people who reached it only through the old link lose it. IDs, records,
+  schema and bound automations are kept. **A database move across separate Space
+  trees** requires an Editor of the database and of both Spaces. The added Space
+  receives its main view (`main_view`) and its origin moves there. That main view
+  stays pending until the Space deploys a record param with `main: true`;
+  meanwhile, bare record links open that Space (`view_warning`).
+- **Unlink**: people who reached the resource only through that link lose it. The
+  last reachable Skill or automation link leaves it standalone for the remover, and
+  an active automation is paused. A database's last Space link is refused
+  (`database_last_space`): offer the move. `LOCAL_NOTIS_DATABASE_DELETE_DATABASE`
+  refuses a database linked to a Space (`database_linked_to_space`); a database
+  used only in one Space is deleted with that Space when its bin entry is deleted.
+- **Move a Space** (`LOCAL_NOTIS_MANAGE_SPACE` `move`): Editors of the new parent
+  gain the whole subtree; people who reached it only through the old parent lose it.
+- **Bin** (`trash`, only after the user confirms): the subtree leaves everyone's
+  Spaces for 30 days and keeps its links. Databases linked only inside it go too.
+  A database also linked elsewhere stays usable there: the bin lends its main view
+  to a published record-param view in a live Space and its origin to a reachable
+  live link. Automations created only inside it pause. A record's child Space
+  stays under its record, outside the bin, while another live Space still shows
+  that record's database; it goes with the bin only when none does.
+- **Restore** (`restore`): the same IDs, Editors, links and databases return, and
+  paused automations resume. Lent main views and origins come back unless a
+  decision was made meanwhile (a published main claim, an explicit move, a copy).
+  A Space whose parent is still in the bin returns at the top level.
+- **Delete now** (Portal Bin; no agent tool): removes the Spaces, their pages and the
+  databases only they link, with every row whoever wrote it, and their stored files.
+  Databases linked elsewhere stay. Skills and automations stay with a live Space
+  that lists them or become standalone for the person who binned the Space.
+  `bin_entry_in_use` names a Space that still uses one of its records; that Space
+  must move, or be deleted from the bin, first.
+- **Remove a member or leave** (Portal Share window; no agent tool): the person
+  loses the subtree. Their own resources that the Space uses are kept for the Space
+  first. Keep a copy (on by default) gives them a private copy of the pages,
+  databases with their rows and Skills they lose, with automations paused, and
+  switches their own Spaces' links to the copies; unchecked, those links become
+  unavailable (see recovery below). The owner cannot be removed and hands
+  ownership over before leaving.
+- **Site** (Portal; no agent tool): anyone with the link, signed out. A Space Site is
+  the Share window's "Publish as a site". One record uses its page's Share popover
+  (Create public link, then Shared publicly with Copy link and Stop sharing) or
+  "Publish this page as a site" in the Share window. Visitors reach only declared
+  actions and reads. Any paid action or read is billed to the grant issuer, not
+  the visitor. The Site never exposes an agent, Skill or automation, and a record
+  Site cannot reach sibling records. Turning a Site off denies the next request.
+
+**Unavailable-link recovery:** a failed link stays unavailable; it never silently
+switches to another source of access. Explain the applicable choices: relink,
+duplicate or remove it.
+
+## Independent copies
+
+A Space Store snapshot includes source, declared resources, linked Skill closure
+and only explicitly selected fictional starter rows. An installation remaps IDs
+and main-view claims to the installer's independent copy. Updates compare the
+published baseline, new snapshot and local customizations; unresolved conflicts
+stay explicit. [Delivery](release.md) owns validation and publication steps.