@notis_ai/cli 0.2.18 → 0.2.19

package/dist/base-skills/notis-spaces/references/sdk.md

@@ -0,0 +1,273 @@
+# SDK reference for Space views
+
+For offline verification, read [the fixture contract](fixtures.md) before
+creating a `verificationFixtures` file. That short reference contains the exact
+list-case format and every required initial-read fixture.
+
+| Import | Holds |
+| --- | --- |
+| `@notis/sdk` | Data hooks, navigation, host interactions and record components |
+| `@notis/sdk/ui` | The toolkit pieces and their hooks |
+| `@notis/sdk/config` | `defineSpace` and view declarations |
+| `@notis/sdk/words` | Pure action ids, EN and FR words and key specs |
+
+`@notis/sdk` and `@notis/sdk/ui` are provided live by the host: never vendor,
+copy or deep-import them (`@notis/sdk/src/...`), and never import the toolkit
+stylesheet; the host adopts it. The host runtime is scoped: source never owns an
+account credential or backend transport.
+
+For a toolkit select, import `NativeSelect` from `@notis/sdk/ui` and pass
+`options={[{value: 'all', label: {en: 'All', fr: 'Tous'}}]}`, `value`,
+`onChange={value => ...}` and an accessible `label`. Its callback receives the
+selected string, not a DOM event; its options come from `options`, not child
+`<option>` elements. Keep the visible field label in the surrounding layout.
+
+## Records and declared reads
+
+| API | Use |
+| --- | --- |
+| `useViewParams<typeof definition>()` | `{params, invalid, missing, declared, ready, setParams}` for declared typed URL params. Unknown names are dropped; invalid values use their declared default. `setParams(changes, {replace?})` changes this view's own params (`null` removes one) and keeps the same Space and record open. |
+| `useShown<Row>(name, options?)` | Execute the native list in `shows[name]` with current params. Options: `sorts`, `pageSize`, `offset`, `includeContent`, `allPages` (every page, for a whole count or a local search); rows are in `data?.rows` and the schema revision a write needs in `data?.schema_revision`, with `loading`, `hasData`, `isFetching`, `error`, `refetch` (resolves to the read's error, or null when it succeeded; it never rejects). |
+| `useShownAvailable(name)` | Check whether this host exposes the declared native list. A record Site can expose only its exact server-pinned row scope. |
+| `useAction<Inputs, Result>(name)` / `useActionQuery<Result>(name, inputs)` | Call a declared action (`call(inputs, options)`); read the result of a declared read action. Never call account-wide tools from a Space. |
+| `useNativeMutation(binding, operation)` | Insert, update or delete one row of a linked database through the action that declares `LOCAL_NOTIS_DATABASE_INSERT`, `_UPDATE` or `_DELETE` on that binding with `request: { $input: 'request' }`. `mutate(input, {schemaRevision, requestId})` returns the receipt (`record_key`, `revision`); a delete moves the record to the bin, leaves every list at once and comes back if the write fails. One new request ID per effect. An insert action takes no `content_markdown`: insert, then save the body with `useNativeDocumentBody` and the record's revision. |
+| `useNativeDelete(binding)` | Trash many rows of one linked database (a deck and its slides, a multi-select). `deleteMany(inputs, {schemaRevision, requestId})` hides every row from the lists at once, runs the writes a few at a time, each with the request ID `${requestId}:${record_key}` (a retry with the same `requestId` replays instead of trashing twice), refreshes the lists once at the end and brings back the rows whose write failed. It never throws for a failed row: it resolves to `{done, failed}`; say how many failed. Use it rather than a loop of `mutate`. |
+| `useNativeDocumentBody(binding, recordKey, {readAction, writeAction?, enabled?})` | Markdown body adapter. Keep drafts in the view; save with the original content, record/schema revisions and stable request ID. Rich editing normally uses `DocumentEditor`. |
+| `useNotis()` | Host resource, Space labels, route and ready state. Use `resource.id` for the current Space identity. |
+
+Keep hooks unconditional. `loading` means no first successful read;
+`isFetching` includes a silent refresh. Do not copy rows into mount-only state
+or clear them on error ([loading rules](design.md#loading-empty-and-error)).
+`Skeleton` and `ViewSkeleton` come from `@notis/sdk`; `ViewSkeleton`'s `label`
+names what loads (`{ en: 'Loading meetings', fr: 'Chargement des réunions' }`),
+said in the Space's language, default Loading content.
+
+For another explicitly idempotent read use `useActionQuery`, or
+`useQuery(keyArray, readCallback, { readOnly: true })` with every input in the
+key. Call declared read actions inside a custom read with
+`{ readOnly: true, dedupe: true }`; never mark a whole tool family read-only.
+`useQueryClient().prefetch(...)` with the exact foreground key prepares a small
+known read after render or on hover; never prefetch a write, a polling action or
+a fan-out aggregate. The host keeps one in-memory cache per account, Space,
+version and permission; do not add module-global or `localStorage` caches of
+user data.
+
+## First-party record components
+
+| Component | Contract |
+| --- | --- |
+| `<DocumentPage recordKey>` | A record as the view's main content: save state, menu, cover, icon, title, meta, properties that save automatically, collaborative body. Slots `breadcrumb`, `actions`, `menuItems`, `aboveBody`, `belowBody`; toggles `share` (off by default, never for a report record), `header`, `meta`, `properties`, `width` (`standard` 900 px centred column by default, `wide` 1200 px, `full`); `viewer: 'html'` shows a record whose one stored `.html` file is the page; `onSaved`; `layout`. Pair with `DocumentPageSkeleton` and `usePrefetchRecord()`. It is the usual `reader` slot of `ListReader`; there it takes no `breadcrumb`, because the top bar crumb already names the open record. A page with a `breadcrumb` (a record opened from the view) names the top bar crumb leaf with its title itself; `topBarTitle` overrides that, and `onTitle` hears the title. |
+| `<DocumentEditor recordKey>` | Native collaborative body, properties, images and attachments. With separate properties use `showProperties={false}`. |
+| `<RecordProperties recordKey>` | Native revision-checked property editing. |
+| `<HtmlFrame recordKey>` | Attached HTML under viewer CSP and an opaque-origin sandbox. Source cannot relax that boundary. `onReady` is called once per page after it has loaded and painted, or when the record cannot load: keep a slide hidden until then instead of showing a half-drawn page. `presentation={{ onAction }}` turns the pointer into a laser dot inside the page, keeps its buttons and links clickable, and hands the presenter's keys and plain clicks back as `next`, `previous`, `first`, `last` or `stop`; the page can send the same actions, so treat them as navigation only. |
+| `<ReportFrame recordKey>` | A report row's saved independent implementation in its database's current view. |
+| `<ShareControl recordKey>` | Private/shared record Site, copy link and revoke. |
+| `<SpacePageFrame href>` | Another Notis Space page, live in this view: `href` is a Notis link (a path or a full link of this origin, such as a Page property). The Portal shows only that page's view (no sidebar, top bar or chat) with the viewer's own session and permissions. `interactive` (default `false`) lets it take clicks and keys; off, the view around it (a deck's arrows and swipes) keeps them. `title`, `className` (sizes the box it fills). Any other link, and every verify or build preview, shows a card with the title, the path and Open page. |
+
+In its own Space's view, a record's Site is a row of the top bar Share panel, not
+a toolbar button. The published Space declares the database binding; the server
+rechecks record scope and binding revision. A Site exposes read-only body and
+property snapshots and HTML for its pinned record, including a declared
+non-collection record param. A report row cannot be shared as a Site; a report
+saved as an HTML file can. A Site has no upload, collaboration credential,
+authoring controls or sharing mutation. No credentials or filesystem URLs belong
+in component props.
+
+## Toolkit pieces
+
+From `@notis/sdk/ui`. Their props live in the piece types; read them there
+rather than from a copy.
+
+- **Lists**: `ListReader`, `Row`, `TabRow`, `SelectionBar`, `Panels`,
+  `OpenAsMenu`, `Keycap`. `ListReader` draws the whole list chrome from props:
+  `search` (the host top bar field), `tabs` (pills in one 44px row), `title`
+  (a short status with its count at the start of that row, such as "23 to
+  triage"), `create` (the "+" at its end), `viewMenu`, `infoLine`,
+  `readerLabel` and `readerActions` (the reader bar), `crumbLabel` (the open
+  item in the top bar crumb), `onOpenChange(id, reason)` (`reason` is `user`,
+  `auto` for a move the list makes itself, or `url`), `renderTile` (tiles), `look` (`two-tone` keeps
+  the list tinted) and `autoOpen` (opens the first item). It has no toolbar or
+  header slot. `Row` takes `wrap` (title lines) and `now` (a fixed clock for
+  relative times). Drag to select is automatic on a list that selects several
+  (`selectable` or a bulk action): a drag from empty space selects the rows
+  under it, as in the Manager; `dragSelect={false}` turns it off. Reorder is
+  off until the view passes `reorder={{ onReorder, canReorder }}`: a row then
+  drags with a line where it lands, or moves with Alt and an arrow key (Alt
+  with Home or End for the ends), and screen readers hear its new place.
+  `onReorder({ item, id, from, to, ids })` gets the moved item, its new index
+  and the whole new order; save `ids` in the view's own order (a position
+  property, for example). The list shows the new order at once and puts the
+  old one back with an error toast if the promise rejects. Pending and
+  disabled rows, and rows `canReorder` refuses, do not move; reorder is off
+  while `search` filters or `groupBy` groups. For a strip of your own (slide
+  thumbnails, a rail), `useReorder({ items, getId, onReorder, orientation })`
+  gives the ordered `items`, `getItemProps(id)` for each element and an
+  `announcer` to render once.
+- **Boards**: `BoardView` is a Kanban board (a funnel, a pipeline): one
+  column per stage (`columns`, each `{ id, label, tone? }`, with `getColumn`
+  saying where an item sits) and a tile per item (`renderTile`, the same
+  `TileParts` as tiles). It is `ListReader` underneath, so `reader`, the open
+  modes, `actions`, selection and `search` work the same; a tile opens on
+  Enter or a click and nothing opens on its own. `onMove(ids, toColumnId,
+  index?)` moves tiles by drag and drop, Shift+Left/Right and M (Move to):
+  update the items in the page (optimistically if you like) and return an
+  undo function for Undo in the toast. Leave `onMove` out for a board that
+  only reads. Use it rather than columns of your own.
+- **Time and numbers**: `PeriodPicker` with `usePeriod`, `DayPicker`,
+  `CalendarView`, `TimelineView`, `Chart`, `StatRow`, `ChartTable`,
+  `RenderChartData`. `Chart` stacks bars or areas (`stacked`) and runs bars
+  left to right (`horizontal`): each label on up to two lines before its bar
+  in a measured axis, and its value after it; `labelFormat` gives that short
+  value ("1.2k") while `format` stays the exact tooltip and table text. Draw
+  category bars this way rather than with your own recharts. For a chart of
+  your own, `ChartContainer` takes `aspect` or `height`; `ChartTooltipContent`
+  and `ChartLegend` also work outside it; `<Bar shape={barShape}
+  label={{ content: barLabel }} />` keeps zero bars and their value labels. A
+  sparkline `null` is a gap. `PeriodPicker` without the `custom` preset offers
+  presets only.
+- **Floating**: `Menu`, `Popover`, `Tooltip`.
+- **Files and pictures**: `AttachmentGallery` and `ImageViewer`, the ones
+  Notis conversations use. `AttachmentGallery` draws a row of file cards
+  (`items`: `url`, `name`, `type` or `kind`, `size`, `thumbnailUrl`); an
+  image card opens `ImageViewer` on the gallery's images (zoom, pan, arrows,
+  copy, download, Escape), and any other card goes to `onOpen` (a new tab by
+  default). `renderOpener` swaps a card's opener, `itemAction` adds a corner
+  button, `viewerActions` adds viewer buttons (class `nui-viewer-btn`) and
+  `onNotice` hears copy and download results. Use `ImageViewer` alone for a
+  picture that opens full screen. Do not build your own lightbox.
+- **Presenting on a second screen**: `useAudienceScreen({ onAction, onClose,
+  title })` works like PowerPoint. `secondScreen` says whether another screen
+  is connected; call `open(anchor)` from the Present press itself. It answers
+  `opened` (the audience window is on the other screen), `one-screen` (present
+  full screen in this window, as before), `press-again` (the browser just asked
+  for permission and used up the press: show `PRESENT_WORDS.pressAgain`) or
+  `blocked` (pop-ups blocked: show `PRESENT_WORDS.blocked`). Render the
+  audience view with `portal(<Slide ... />)` from the same component, so both
+  windows share one state: the current slide, next and previous, and a
+  presented `HtmlFrame`'s laser all stay in sync. Keys, clicks and right clicks
+  in the audience window come back through `onAction` (`next`, `previous`,
+  `first`, `last`, `stop`); the presenter window keeps the normal view (notes,
+  previews, a timer). The browser asks once to place windows on screens; the
+  desktop app never asks. Leaving the view closes the audience window.
+- **Blocks**: `Section`, `Badge`, `Button`, `ToggleGroup`, `SegmentedControl`,
+  `NativeSelect`, `EmptyState`, `Notice`, `Metric`. A page is a stack of
+  `Section`s, full width and without boxes: `kind` is `bar` (period and
+  filters), `stats`, `chart`, `data` (a table) or `form`, and its head takes
+  `title`, `count`, `meta`, `tabs` and `actions`. There is no page heading and
+  no card: the host top bar shows the title. One toggle is a `Button` with
+  `pressed`; several with any number on (filters, chart series) are a
+  `ToggleGroup`; tabs and filters over a whole list or section are pills
+  (`TabRow`); a `SegmentedControl` is only a mode switch inside a section.
+  A `Notice` is read politely, danger too; pass `urgent` only for a problem the
+  person must act on now (it becomes an alert that interrupts the screen reader).
+- **Fields**: `EditableFields` (a form; Save and Cancel show once something
+  changed) or `FieldList` (the same rows without them) around `FieldRow`s holding
+  `FieldText`, `FieldLongText`, `FieldSelect`, `FieldMultiSelect` (`searchable`
+  for a long list, `onAdd` to add the typed text as an option) or
+  `FieldDisclosure` (its summary, such as a `formatLongDay` date, wraps in a
+  narrow reader). A row's `hint` describes its control; `invalid` reads the
+  hint as the error. Their rules ship in the toolkit styles: draw no `<style>`.
+- **Hooks for your own layout**: `useListKeys` and `useSelection` (list keys and
+  selection), `useShortcut` (a key at route scope or below), `usePanels` (split
+  or stacked), `useOpenMode`, `useActions` (standard and own actions),
+  `useLayerRoot` (container for anything floating), `useEscapeLayer`.
+
+A standard action is an id (`archive`, `complete`, `star`, `later`, `move`,
+`assign`, `read`, `delete`...) plus `run`; without `run` it is hidden. The standard
+`delete` hides its records from the lists while `run` works, keeps hidden the
+ones it removed and brings back the ones in `failed` (or all of them when `run`
+throws, and on Undo): return `{ failed }` rather than refetching yourself. An own
+action is `{ id, label: { en, fr }, icon?, key?, tone?, bulk?, appliesTo?, run }`.
+A standard id with a `label` keeps its key, icon and toast: `unarchive` reads
+Move to triage, and a Space whose first stop has a name passes
+`{ id: 'unarchive', label: { en: 'Move to Inbox', fr: 'Remettre dans la boîte' } }`.
+
+A status maps to one of ten groups (`backlog`, `todo`, `active`, `review`,
+`waiting`, `done`, `cancelled`, `failed`, and `up`/`down` for a service), each
+with its icon, words and the one status palette: pass the Space's own status to
+`Row` or `StatusIcon` (with `label` for its own name), never a colour.
+
+## Navigation
+
+`useNotisNavigation()` exposes `toSpace(spaceId, {recordKey?, params?})` and
+`toNamedSpace(alias, {recordKey?, params?})`. Both return a promise that settles
+once the host has taken the navigation and rejects when the host refuses it:
+`await` it (or `void` it in a click handler). Prefer declared portable navigation
+aliases for sibling destinations; the host resolves them under current access.
+Use declared params for view state, for example `{params: {project: key, period: 'week'}}`.
+The destination drops unknown params and authorizes referenced records. Changing
+a slug cannot change identity. Agents cite current server-returned links.
+
+To change the open view's own params (an open item, a tab, a filter), call
+`useViewParams().setParams({open: key})` instead of navigating to the same Space:
+there is no alias to declare and no destination request, and each call adds a
+history entry unless you pass `{replace: true}`. `ListReader` with `openParam` and
+`usePeriod` already write this way.
+
+## Viewer-only exploration
+
+`viewerReads: ['databases', 'skills']` permits read-only inspection of what the
+signed-in viewer already reaches. It creates no shared grant. Use
+`useViewerReadAvailable(family)`, `useViewerDatabases`, `useViewerSkills`, or
+`useViewerRead(operation, input)`. Anonymous Sites cannot use these families.
+Explicit synthetic `viewerReads` fixtures stand in for the viewer's reads offline.
+
+## The viewer's cloud computer
+
+`cloudComputer: 'shell'` (or `'read'` for facts only) lets a page run one command
+or write one file on the signed-in viewer's own cloud computer, after that viewer
+allows it in the Portal prompt. Use `useCloudComputerShell()`: check `level`, call
+`requestApproval()` when `approved` is false (either level; the facts of
+`useCloudComputer()` are read again once allowed), then, when `available` (`shell`),
+`run(command, options)` or
+`upload({ path, content, content_encoding: 'base64', mode: 0o600 })`. Never put
+secrets in a command; send them as upload content. A run is never repeated for one
+request key: pass `requestId` (run option, or `request_id` in the upload) when the
+page retries a run itself; `cloud_computer_already_ran` means it already ran. The
+approval covers only the exact code the viewer allowed, so every new release asks
+again. Keep a fallback (a Manager draft) for Sites, previews offline and viewers
+who do not allow it. Declare it only when the page's core controls run on the
+cloud computer.
+
+## Visual data and Markdown
+
+Give a chart its numbers through `RenderChartData` (the toolkit's `Chart` and
+`ChartTable` already do): it adds a semantic table without a second visible one.
+The renderer never guesses exact numbers from SVG or canvas geometry; a chart
+without it contributes only its accessible name to the Markdown.
+
+An optional `markdown` source module exports a pure function of `{params, shown}`.
+It must describe the rendered selection and its actual data. Ordinary rendering
+extracts tables, lists, controls and visible document/HTML content automatically.
+
+## Host interactions and context
+
+- `useHandover()` exposes `{handover, available, pending, error}`. Call a declared
+  linked Skill with `handover({skill, prompt})`; fall back when no agent UI exists.
+  A selected row goes as `record: {binding, recordKey, readAction}`: the host
+  reads that row without its body, so pass the database's `query_` action (a
+  `read_record_` action fixed to `include_content: true` is refused).
+- The host top bar owns the title, the search and Share. `ListReader` `search`
+  fills the host search field; a Space never wires its own search. The open
+  item joins the crumb through `ListReader` `crumbLabel`, or
+  `useTopBarTitleLeaf(label, onBack)` on your own layout; the view crumb then
+  calls `onBack`. When the item is a record of the Space's `collection`, pass
+  `useTopBarTitleLeaf(label, onBack, { recordKey })` so Editors rename it from
+  the crumb; read its name from your data, which refreshes after the rename. A
+  `DocumentPage` breadcrumb moves into the top bar on wide
+  screens and stays in the page only on narrow ones, so never draw your own
+  title or breadcrumb row. Do not duplicate host chrome.
+- `useActiveResource` publishes the current resource; `useAgentContext`,
+  `NotisSelectionBoundary`, `NotisCommentBoundary` and `NotisCommentBox` support
+  explicit reference context. [Context sharing](context.md) owns the contract.
+- `Dialog` supplies a themed modal with focus handling; while it is open, only
+  its own keys and Escape work. For a confirmation (delete, discard), pass
+  `nativeOnTouch` and mark the buttons `data-dialog-confirm` and
+  `data-dialog-cancel`: phones and tablets then ask with the system dialog.
+- `MarkdownEditor` is for a view-owned Markdown draft/persistence adapter. Native
+  documents use `DocumentEditor` so collaboration and file authority stay with Notis.
+
+## Offline fixtures
+
+Read the complete [offline fixture contract](fixtures.md). Keep every fixture
+fictional; verification never falls back to the user's real account.

package/dist/base-skills/notis-spaces/references/store.md

@@ -0,0 +1,118 @@
+# Store publishing
+
+Use this when the user asks to publish a Space, or an update to one, in the
+Store. You prepare everything; the user chooses where it goes and presses
+Publish on the submission page. Store publication stays separate from deploying
+the installed Space ([Delivery](release.md)).
+
+## Never publish for the user
+
+There is no agent publish operation, and you never press, simulate or script
+the Publish button. Only the page's Publish button publishes, after the user
+picks Team or Public there. Asking you to publish means: prepare the submission
+and send the page link. A team listing goes live as soon as the user presses
+Publish; a public listing goes to the sandbox reviewer, and Notis messages the
+user with its result.
+
+## The flow
+
+All steps use `LOCAL_NOTIS_MANAGE_SPACE`. Each answer is the submission view:
+status, listing text, locales, sample rows and counts, screenshots, findings,
+`can_publish`, `blocked_reason` and `link`.
+
+1. **Prepare.** Call `store_prepare {space_id, request_id}` with the root of the
+   tree to publish and a stable request ID. Notis copies the tree into the
+   user's hidden Store review Space (the test copy, automations paused), pins
+   the source revision, takes screenshots and runs the safety scan. Retry with
+   the same request ID; never prepare twice to recover a lost answer.
+2. **Write the listing** with `store_submission_update {submission_id, metadata,
+   locales}`: name, tagline, description, category, icon and accent in
+   `metadata` (English), and the French name, tagline and description in
+   `locales.fr`. The optional `locales.fr.items` maps `pages`, `databases`,
+   `skills` and `automations` by the immutable `key` returned in the submission's
+   item inventory. Supply display-only `name` and `description` (`summary` for
+   automations), preserving the package's identities and order. A null or blank
+   leaf clears that translation, so the viewer falls back to English. Say what the Space does for the person who installs it, from
+   its views, databases and Skills. Write French as natural French (tu), not a
+   word-for-word translation. No personal names, account details, customer or
+   company data from the source.
+3. **Write sample rows** with `store_submission_update {submission_id,
+   sample_rows}` (see below), then read the screenshots. Pass
+   `retake_screenshots: true` after sample rows or listing text change what the
+   views show.
+4. **Handle the findings** (see below): ask about privacy, fix the rest in the
+   source Space, and list every fix.
+5. **Send the link.** When `can_publish` is true, give the user the page
+   `link`, one short line on what is ready, the fixes you made and their answers.
+   If it stays false, say what still blocks it from `blocked_reason` and what
+   they can do.
+
+## Sample rows
+
+- Up to 8 rows per database, keyed by database key: `{database_key:
+  [{key, properties, body}]}`. Use only properties in that database's schema; a
+  relation lists the `key` of another row in the same sample set. `body` is
+  optional plain text (one paragraph per line); `key` is optional short text.
+- Realistic and wholly synthetic: plausible titles, dates, amounts and states
+  that show every main view working (a few statuses, a spread of dates, at
+  least one row in each group a view shows).
+- Never a real person's name, email address, phone number, company, address or
+  account identifier, and never content copied or paraphrased from the user's
+  own rows, notes, contacts or history. Use invented first names only when a
+  field needs a person ("Alex", "Camille"), and no contact details at all.
+- Sample rows exist only in the test copy and the published version. They never
+  enter the source Space. Installs start with them, and the installer removes
+  all of them with one click; updates never bring them back.
+
+## Findings
+
+Each finding has `id`, `check`, `severity` (`red` or `amber`), `privacy`,
+`where`, `message`, `fix` and `status`. Publish needs no open red finding and no
+unanswered privacy question.
+
+**Privacy.** A finding with `privacy: true` is a candidate, not yet a question.
+Judge whether it carries a real privacy risk for the publisher or for people in
+their data: an outside host that would receive installers' data, an integration
+or MCP call that reads private accounts, a read of Spaces outside the published
+tree, a sharing change, personal data in the listing, screenshots or samples. A
+candidate with no real risk is treated like any other finding. Sample or fake
+data is never a risk: the scan already skips tests, fixtures and placeholder
+hosts, so never ask the user to confirm data you can see is a sample. If one
+still shows up, say it is sample data the scan missed instead of asking about
+it. For each real risk, ask the user one plain question naming what and where, with two choices:
+
+- **Remove**: take it out of what is published.
+- **Keep**: publish it as it is; Notis adds your note to the listing so
+  installers see it.
+
+Record their answer with `store_finding_answer {submission_id, finding_id,
+answer: 'remove'|'keep', note, user_words}`. `user_words` are the user's own
+words; `note` is the short listing sentence for a Keep, written in plain words.
+Never answer a privacy question for the user.
+
+**Everything else.** Fix each non-privacy red finding in the source Space
+through the normal release path: pull, change, build, verify, deploy, read back
+([Delivery](release.md)). Then call `store_prepare` again for the same Space
+with a new request ID, so the open submission pins the new revision and scans
+again. List every fix for the user: what was found, where, and what you changed.
+A finding you cannot fix keeps Publish blocked; say so plainly. Amber findings
+need no fix; mention the ones an installer would notice.
+
+Test chats about the submission run on the test copy only; never write sample
+rows, listing text or fixes for the listing into the source Space's data.
+
+## Updates
+
+Publishing an update follows the same flow: `store_prepare` on the same root
+creates a new submission on the same listing, and Publish adds a new version to
+it. Never create a second listing, a copy of the Space or a new Space to ship an
+update. Installs that differ only in listing text or screenshots update
+themselves; installs of a version that changes code or databases show an
+Update available card and update when their owner chooses.
+
+## Status
+
+Read the submission with `store_submission_read {submission_id}`. `ready` means
+the page can publish; `in_review` means the public review is running and Notis
+will message the user with the result; `published` is live; `rejected` lists what
+to fix, which starts again from step 4 with a new `store_prepare`.

package/dist/base-skills/notis-spaces/references/troubleshooting.md

@@ -0,0 +1,28 @@
+# Troubleshooting
+
+Start with the actual failing operation and its exact Space, source/record
+revision and current target. [Delivery](release.md) owns the release sequence.
+
+| Failure | Check |
+| --- | --- |
+| Build rejects a view | Required `specVersion`, path, descriptions, params, executable shows and memory; use the file/line diagnostic. |
+| Design check rejects a view | Replace the flagged code with the piece or hook the diagnostic names (`useShortcut` for a key listener, `useLayerRoot` for a portal, tokens for a colour, EN and FR copy for a literal). Do not disable the rule. |
+| Main-view conflict | Inspect current database links/main view. Move the existing claim explicitly or retain it; do not remove main just to publish. |
+| Source creation fails | Check its canonical schema and same-view main record param. Verify creates no resource; promotion is atomic. |
+| View-link warning after a successful write | Use `FIND_VIEWS` with the returned record key. The write is already committed; do not insert again. |
+| Empty list or missing properties | Inspect the live schema, filter, authorized binding and returned projection. Distinguish a successful empty result from a denied/failed read. |
+| Verification fails on a read | Add the exact fictional case to the selected fixture file. Never fill missing fixtures with live private data. |
+| A caught write-on-load fails rendering | Remove the side effect from initial rendering. A read-only check cannot authorize writes. |
+| Stale binding/schema/record | Read current state, preserve the original receipt/intent and merge the intended edit. Do not overwrite concurrent changes. |
+| Old code in Workspace | Read the published revision and requested bundle; source edits or restarting Desktop do not deploy it. |
+| `client_update_required` | This Notis app or CLI is too old. Update it, then repeat the same operation. Old apps are not supported. |
+| `protocol_required`, `invalid_protocol` or another 400 naming a `field` | The call is malformed, not out of date. Fix the named field (native Space and database tools take `"protocol": 1`) and call again. |
+| Uncertain deployment | Run `notis doctor`, read the same Space and release/request identity, then reconcile before retrying. |
+| A tool call fails with `network_error`, `network_timeout` or a 502, 503 or 504 | The CLI already retried it where repeating is safe (`attempts` in its answer). Do not add your own retry loop: read back the same target, then run it again only if it did not happen, with the same `request_id`. |
+| Screenshot misses content | Inspect actual inner scrolling, lazy data and frame layout; keep full-height limits and treat a failed capture as unverified. |
+| Site unexpectedly has editor controls | Recheck the anonymous scoped runtime. A Site cannot borrow an ambient signed-in session or another record's authority. |
+| Memory hit looks current but access/freshness is unknown | Render its current link and verify the relevant value. Do not release historical content from an unverified read set. |
+
+For visual defects, compare the installed page at 390px and 1440px in EN/FR,
+including loading, empty and error states. A standalone harness cannot certify
+the Portal parent layout, collaboration or public Site behavior.

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

@@ -0,0 +1,229 @@
+# 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.
+
+## Index the Space in the workspace
+
+The root `notis.config.ts` maps each local Space key to an object with its
+definition file. The value is not a path string or the definition itself:
+
+```ts
+import { defineSpaces } from '@notis/sdk/config';
+
+export default defineSpaces({
+  spaces: { notes: { definition: 'spaces/notes/space.config.ts' } },
+});
+```
+
+That definition file exports `defineSpace`, as below; its `entry` is relative to
+the definition file. `spaces init` creates this index for a new collection.
+When writing a new source workspace through the confined source tools, include
+the index and the definition before requesting a build.
+
+## 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' } },
+    },
+  },
+});
+```
+
+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.
+
+## Write the view
+
+Start from the piece that matches the view. A list beside a reader is one
+`ListReader`:
+
+```tsx
+import { DocumentPage, useAction, useNotisRuntime, useShown } from '@notis/sdk';
+import { ListReader, Row } from '@notis/sdk/ui';
+
+type Note = { record_key: string; title: string; updated_at: string };
+const keys = (items: Note[]) => ({ record_keys: items.map((n) => n.record_key) });
+const copy = { en: { search: 'Search notes' }, fr: { search: 'Rechercher des notes' } };
+
+export default function Notes() {
+  const t = copy[useNotisRuntime()?.context.locale === 'fr' ? 'fr' : 'en'];
+  const notes = useShown<Note>('notes', { allPages: true });
+  const archive = useAction('archive_notes'); // declared write actions
+  const pin = useAction('pin_notes');
+  return (
+    <ListReader
+      label={{ en: 'Notes', fr: 'Notes' }}
+      items={notes.data?.rows ?? []}
+      getId={(n) => n.record_key}
+      openParam="note"
+      search={{ placeholder: t.search,
+        match: (n, query) => n.title.toLocaleLowerCase().includes(query.toLocaleLowerCase()) }}
+      row={(n) => <Row title={n.title} time={n.updated_at} />}
+      readerLabel={(n) => n.title}
+      crumbLabel={(n) => n.title}
+      reader={(n) => <DocumentPage recordKey={n.record_key} />}
+      actions={[
+        { id: 'archive', run: (items) => archive.call(keys(items)) },
+        { id: 'pin', key: 'shift+p', label: { en: 'Pin', fr: 'Épingler' },
+          run: (items) => pin.call(keys(items)) },
+      ]}
+    />
+  );
+}
+```
+
+That is the whole view. J/K (wrapping), Enter, Escape, selection with X,
+Shift+J/K and Mod+A, E with Notis's Archive words and toast, the selection bar,
+the `?` sheet, open as Side, Center or Full, the one-pane rule next to chat and the
+phone layout come with it. `openParam` names the declared record param, so the
+open note lives in the link. `search` fills the host top bar search field and
+filters the loaded notes; `crumbLabel` adds the open note to the top bar crumb
+("Notes / Groceries"); `readerLabel` names it in the reader bar. The view draws
+no title, heading or search field of its own. `archive` is a standard action: it
+brings its own words and key. `pin` is the Space's own: it brings its EN and FR
+words and a key the clash check accepts. Add `tabs` for real saved filters and
+`create` for a "+" that makes a record. Other kinds of view start from their own
+piece; see [Design](design.md#pick-the-piece).
+
+Keep hooks unconditional; conditional record/list branches can be separate
+components. The [SDK reference](sdk.md) covers data hooks, record components,
+navigation and the toolkit pieces.
+
+## 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.
+- One optional (never `required`) record param per view may declare `page: {where}`:
+  a matching saved HTML page or report then opens full screen as its own page, for
+  Editors in the Portal (Back, plus Share for HTML) and, for HTML pages only, on its
+  record Site. `where` compares
+  fixed values over `record_key`/`id`, `content_type`/`file_type`/`title` and select,
+  status or checkbox properties; it never reaches the browser. Viewers still get the
+  view, so keep its own HTML/report rendering. The full rules live under Record pages
+  in the platform reference (`docs/notis-spaces-platform.md`).
+- `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 condition may add `when: 'late'`, naming a boolean param. It is included
+  only when that setting is true; absent/false drops it before pagination.
+  This also gates `is_empty` for unplanned tasks. `tasksViewFilter` pairs with
+  `tasksViewParams`; bind their property names and Done status to the actual schema.
+  Its `today` date param defaults to the declared timezone's today; pin it for
+  dated answers. Clear conflicting date/period/late/unplanned settings in controls.
+- 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; ordinary collection views keep Portal chrome.
+A Space whose published view hides chrome starts hidden from each person's sidebar;
+it stays reachable by link and search. Each person can turn on **Show hidden Spaces**
+in the sidebar's Spaces menu, then choose **Show in sidebar** in that Space's menu.
+Skill review Spaces stay out of the sidebar, even with **Show hidden Spaces** on:
+people open them from the Skill page's **Changes** list. A review a person already
+chose to show stays in their sidebar until they hide it.
+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.