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

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

@@ -1,145 +1,107 @@
-## Delivery
-
-Workspace runs released versions only. Local and cloud agents use the same
-workflow. Run Notis commands through
-`npx --package @notis_ai/cli@latest -- notis ...`.
-
-A create/edit request normally authorizes updating that app after checks pass,
-**unless user or repository policy requires explicit deployment consent**.
-Preserve authorization already given. Read-only, preview-only, and no-deploy
-instructions stop at local source, build, and stub verification: no remote
-resource mutation, app activation, or live verification. Store publication always
-needs separate explicit approval. Do not deploy just to obtain visual proof when
-deployment is not authorized; report that the host check remains unverified.
-
-## Update an app
-
-1. **Check identity.** Inspect the effective CLI profile and `apps list --json`.
-   Preserve local edits, then pull the exact editable app ID and intended
-   personal/team scope. Keep its profile-scoped link, current version, and revision.
-   Never silently advance a stale checkout or create a duplicate to avoid a conflict.
-2. **Build and inspect.** Edit the source, increment `notisAppVersion`, and update
-   `CHANGELOG.md`. Run `apps build` and automated `apps verify`, then do the
-   [visual check](design.md#look-at-the-result). For a new app, complete these
-   local checks before creating remote resources.
-3. **Prepare only missing resources.** For an existing app, retain its identity.
-   For a new app, reconcile the exact canonical name, edit permission, and scope
-   against `apps list --json`; reuse one matching editable identity, stop on
-   ambiguity, or create only when none exists. Use `apps create "<display title>"
-   <dir>` (with a verified `--team-id` for team scope), and read back the same ID.
-   Create only necessary missing databases against that app. Verify ownership
-   and database IDs before changing schemas; read back changes. Breaking changes
-   require separate coordination. Never mutate user data merely to test the UI.
-4. **Update Workspace.** Run `apps deploy` against that linked app. It builds and
-   verifies a frozen source/artifact snapshot before activation. `--skip-build`
-   accepts only unchanged valid output and still verifies. Use the supported
-   backend path; do not bypass checks or write directly to storage.
-5. **Verify delivery.** Read back the app ID, integer version, and Portal URL with
-   `apps list --json`. Run `apps verify --mode live`, then open the released app
-   inside Notis and inspect the affected screen and main interaction. Confirm the
-   intended bundle/version, not just the existence of an app with the same name.
-   A successful live harness check alone is not visual proof inside Notis.
-6. **Report accurately.** Give the app link and a brief description of what changed
-   and what was verified. Distinguish local-only, deployed and verified, deployed
-   but unverified, failed before activation, and outcome unknown. If create/deploy
-   has an uncertain outcome, reconcile its exact identity/version before retrying.
+# Delivery
+
+Workspace runs released Space source. Use the same workflow locally and on the
+cloud computer through `npx --package @notis_ai/cli@latest -- notis`.
+A create/edit request authorizes the checked installed-Space update unless the
+user or applicable policy says preview-only/no-deploy. Store publication is a
+separate action. Preserve exact identity and prior authorization.
+
+## Update one Space
+
+1. **Read identity.** Check the active account/endpoint and `spaces get <space-id>`.
+   Pull the exact editable source with `spaces pull <space-id> <dir>`. Keep
+   `.notis/space-lock.json`, resources, source key and current revisions. Never
+   silently advance a stale checkout or create a duplicate to avoid a conflict.
+2. **Build.** Edit the selected definition, its view and linked Skill files.
+   Update `CHANGELOG.md`. Run `spaces build <dir> --space <key>`; it freezes source
+   and artifact bytes and validates the view contract and design.
+3. **Verify.** Run `spaces verify <dir> --space <key> --space-id <space-id>`.
+   This checks current action authorizations and renders explicit fictional
+   fixtures at 390px and 1440px with the shared read-only renderer. Provide exact
+   action/list/body/record fixtures. A denied read, write-on-load or failed width
+   is a failure, not a passing empty page. Inspect both locales and intended states.
+4. **Publish source.** Use `spaces deploy <dir> --space <key> --space-id <space-id>
+   --request-id <stable-id>`. Or `spaces preview` seals a candidate, and
+   `spaces promote <release-id> <dir>` publishes that exact candidate. Preview
+   authoring never silently gains live record-edit authority. Deployment updates
+   the selected Space, not siblings or the Store.
+5. **Read back.** Confirm published source revision and link with `spaces get` or
+   `views find --space-id`. Run `views render <view-link>` and inspect Markdown
+   plus the full-height screenshot. Check the affected interaction in the actual
+   Portal/required Desktop surface, in EN/FR at 390px and 1440px. Fixture success
+   does not prove data, access, collaboration or Site revocation.
+6. **Report.** Return the canonical view link and the exact completed boundary:
+   local-only, deployed/verified, deployed/unverified, failed-before-publication,
+   or outcome-unknown. After an uncertain response, read the same release/request
+   identity before retrying. Never bypass source checks with direct Storage writes.
+
+## Create without duplicates
+
+Start locally with `spaces init`, then build. Discover/list existing Spaces before
+creating the intended remote identity with `LOCAL_NOTIS_MANAGE_SPACE`. Use a stable
+UUID and reconcile an uncertain creation. Read back its revision and resources,
+then verify/deploy with `--space-id`. A source-created database is committed with
+its main view in that publication; no separate provisional database is necessary.
 
 ## What the checks prove
 
-`build` validates the package, enforces design rules, and refreshes its embedded
-SDK. Automated `verify` checks every route at desktop (1280px) and phone (390px)
-widths, render errors, runtime calls, nested boxes, small text, lingering loading
-placeholders, and horizontal overflow. It uses a temporary server and browser;
-printed URLs or `--no-browser` are not passing verification. If tooling is missing,
-install it with `npm exec --yes --package agent-browser@latest -- agent-browser install`.
-
-Stub verification does not establish real account data, permissions, host layout,
-or visual quality. Live verification exercises the authenticated runtime but still
-uses the harness. The final installed-app check establishes the result inside Notis.
-If that surface cannot be inspected, say so rather than claim it passed. No extra
-approval round is needed for an already-authorized check.
-
-`apps screenshot` supports declared scenarios and stub fixtures, including
-`theme: 'dark'`; `--raw` gives uncomposited captures. Store listing screenshots are
-not required for an ordinary Workspace update.
-
-## Special cases — read only when relevant
-
-### Publication privacy and portability gate
-
-Before submitting or updating a Store listing:
-
-1. Inventory the exact public source archive, listing text/media, database schemas,
-   starter rows, bundled skills (including scripts/references), and automation
-   prompts/configuration. Review their actual contents, not just filenames or
-   a passing secret scan. Exclude personal records, transcripts, health/journal
-   history, customer details, private repository/account identifiers, credentials,
-   local paths, run logs, and private links. Do not merely replace a person's name
-   in otherwise real data. Rebuild examples from wholly fictional scenarios.
-2. Keep live owner databases structure-only (`seedDocuments` absent or false).
-   Opting in seeds the database's live rows, including folders: it is not a
-   fixture selector. Use fictional screenshot fixtures and an explicit, idempotent
-   onboarding demo-data option. If starter rows are needed in the install snapshot,
-   publish only from an isolated, verified fictional dataset; never replace or
-   delete the owner's real data to prepare a submission. When the user asks for
-   examples to come with the app, include them in that verified install snapshot:
-   screenshot fixtures or an optional onboarding seed step do not satisfy this.
-3. Bundle the full dependency closure of every app/automation skill, including
-   referenced helpers and resources. Remove private account-specific defaults;
-   resolve the installer's databases, connections, repository, timezone and
-   delivery choices at runtime. Preserve existing owner's schedules and data.
-4. Declare a source-owned onboarding skill. It must work through available MCP
-   tools or the Notis CLI in any agent harness, without requiring Notis Manager,
-   vendor-specific delegation tools, hidden local files, or publisher access.
-   Discover tools and inspect schemas before calls; reconcile existing resources
-   before creating them. Obtain installer choices before enabling automation or
-   external actions. Installing examples must not activate external deliveries.
-5. Test onboarding as an independent harness-native proof agent using an account
-   isolated from the publisher, then rerun to prove no duplicates. Exercise each
-   route and its interactions with fictional data, including empty/error states.
-   Record exact identities, versions, results and run-created resource cleanup in
-   a private Notis document owned by the app, never only in local files; never use
-   owner records as writable test fixtures.
-   For bundled starter-data claims, install the actual published listing into an
-   empty test account and read back its rows before onboarding or any manual data
-   writes. Confirm the installed listing version and remapped relations; do not
-   substitute an editable-source deployment for this Store-install test.
-6. Inspect the final submitted snapshot and media after packaging. Record the
-   privacy audit and verification against that exact source version in the same
-   private Notis document. Any unknown
-   provenance, missing dependency, untested onboarding or suspected personal data
-   blocks submission until resolved. Never equate submission with review approval
-   or Store publication.
-
-### Unreleased container or stale checkout
-
-An unreleased container has no source to pull. Recover its original local source,
-or scaffold only if it cannot be recovered; verify the exact ID and scope and use
-`apps link <app-id> <dir> --expected-version 0`. Reuse the container after a failed
-first release; do not duplicate or automatically delete it. If another release
-has appeared, pull it into a fresh directory and reapply the intended edits without
-replacing its deployment base. Link/deploy guards must reject races and conflicts.
-
-### Restore an older source
-
-Pull the current release into a fresh checkout and the historical source into a
-separate folder (`apps pull <id> <dir> --source-version <n>`). Replace source without
-replacing the current `.notis` link/base, then check and deploy as a new release.
-Preserve app/database/skill IDs. Never decrement versions or imply that source
-restoration undoes user data or external actions.
-
-### Release history and Store publication
-
-Keep all release history in root `CHANGELOG.md`, newest first, with headings
-`## [Release title] - YYYY-MM-DD` (or `{PR_MERGE_DATE}` while unpublished). Do not add
-`versionNotes` to the config. App Details reads deployed history; the Store reads
-its published snapshot. Local edits must not change the published listing.
-
-`apps deploy` updates Workspace only. Use `apps publish --confirm-ready` only after
-the user explicitly approves the current App Details and Store listing. Deploy the
-exact approved source first. Respect listing completeness, visibility, version,
-and pending-review guards. A public submission includes editable source, Store
-assets, source-declared database schemas, and only explicitly opted-in starter
-rows. Do not hand-edit `notis-listing.json` or strip files to pass review; fix the
-source, redeploy, and resubmit. To start from a Store app, use `apps init --from
-<slug>`; `apps pull` is for an accessible installed app, not a Store listing clone.
+| Check | Proves | Does not prove |
+| --- | --- | --- |
+| Build | Current selected source/artifact and schema syntax | Runtime data or access |
+| Verify | Frozen fixture rendering and current declarations/authorizations | Live record values, publication, sharing or visual quality |
+| Live render | Read-only current view data, Markdown and full-height image | Mutation behavior or collaborative editing |
+| Installed interaction | The specific checked host behavior and data readback | Store installation or production release |
+
+`notis spaces screenshot <view-link> --width 390` captures an already deployed
+view. `notis views render` saves Markdown and/or PNG with a new output path; read
+the artifact, not only the command's success message. Missing output is not proof.
+
+## Skills, resources and concurrent edits
+
+Pulled Skill folders, `resources.json` and source share one release transaction.
+Only changed content is sent; unrelated remote edits stay intact. A conflict
+publishes nothing: pull fresh source into a new directory, merge the intended
+change and preserve the new lock. Stale source/record/binding revisions must not
+be replaced with guessed current values merely to force a write.
+
+To restore older source, pull current identity and the desired historical
+revision separately. Reapply the old content against the current lock and publish
+a new revision. Source restoration does not revert user data or provider effects.
+
+## Publication privacy and portability gate
+
+Before an explicitly authorized Store publication:
+
+1. Review the complete snapshot: source, listing, media, schema, selected starter
+   rows, linked Skills/helpers and automations. Exclude personal data, account
+   identifiers, credentials, local paths and private run logs. Use wholly fictional
+   fixtures; redacting a name from real private content is insufficient.
+2. Keep databases structure-only unless the user requested packaged examples.
+   Store `--starter` is an explicit set of record keys per database, not a fixture
+   selector. Never populate it from private notes, leads, history or folders.
+3. Package the full dependency closure. Resolve the installer's own resources and
+   connections; never keep publisher defaults. Preserve existing schedules and
+   local customizations. Installation must not activate external deliveries.
+4. Link a Set up Skill when setup is needed. It must work through native tools or
+   the CLI in any harness, reconcile existing resources and be safe to rerun.
+5. Use an independent isolated installer proof: install the exact listing version,
+   verify remapped main views/relations and any claimed starter rows before setup,
+   run setup twice, exercise fictional views and clean only run-created resources.
+   Record exact identities, versions, results and cleanup in a private Notis
+   record owned by the Space, never only in local files.
+6. Run `spaces store publish <space-id> --dry-run` and review its diff. Execute
+   only the authorized channel/publication, then read back the listing version
+   and review state. Record the privacy audit and verification against that exact
+   source revision in the same private record. Submission is not review approval
+   or public availability.
+
+`spaces store update <install-id> --dry-run` exposes a three-way update plan.
+Resolve each explicit conflict with `keep_mine` or `take_theirs`; retain unrelated
+local changes. Store publication and installed source deployment remain separate.
+
+## Release history
+
+Keep `CHANGELOG.md` newest first, with `## [Release title] - YYYY-MM-DD` headings
+(or `{PR_MERGE_DATE}` before the release date is known). Source history belongs to
+that Space; changing its local changelog does not change an already published
+Store snapshot. Use the verified source revision, not the changelog title, as proof.

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

@@ -1,63 +1,116 @@
-## SDK Hook Reference
-
-All hooks and components below are imported from `@notis/sdk`. `NotisProvider`
-already installs `ShortcutProvider`; app code should not add a second provider.
-
-| API | Signature | Description |
-|-----|-----------|-------------|
-| `useNotis()` | `() => { app, route, databases, collectionItem, resourceId, ready }` | App metadata, current route, selected collection item, decoded exact-resource id, ready state |
-| `useTool<TArgs, TResult>(name)` | `(name: string) => { call, loading, error }` | Call a declared tool with app-defined argument/result types. Identified reads use `call(args, { readOnly: true, dedupe: true })`; never dedupe writes. See [cached-read ownership](design.md#instant-view-loading-contract-required). |
-| `useTools()` | `() => { tools, loading }` | List available tools |
-| `useDocuments(slug, opts?)` | `(slug: string, opts?) => { documents, loading, hasData, error, refetch }` | Query an app database. Bodies are included by default. For metadata-only lists, opt into `includeContent: false`; load the opened record with `useDocument` and defer any full-body search query until needed. Metadata and full-content query caches are separate. |
-| `useNotisNavigation()` | `() => { toRoute, toDocument, toApp }` | Navigate between routes (including `toRoute(path, { resourceId })`), documents, or the app root |
-| `useTopBarSearch(opts)` | `({ value, onChange, placeholder?, onSubmit? }) => { setLoading }` | Bind the current view to the Portal-owned top-bar search input |
-| `useBackend()` | `() => { request }` | Raw backend request proxy with JWT auth |
-| `useDatabaseSubscription(slug, opts?)` | `(slug: string, opts?) => { rows, documents, loading, error, refetch, live }` | Query a database and refetch it when its rows change. `live` is false on hosts without a change feed (temporary test harness, vite preview) -- keep a manual refresh for those |
-| `useHandover()` | `() => { handover, pending, error, available }` | Open manager chat with app/resource context plus an optional starter prompt or declared skill. Omit `prompt` for a context-only composer. `available` is false on hosts with no chat -- fall back to a copyable prompt |
-| `useCloudComputer()` | `() => { facts, loading, error, refresh }` | Read-only cloud computer facts: sandbox existence/status and whether the GitHub CLI is signed in. Requires `capabilities.cloudComputer: 'read'` plus the user's approval; `facts.available === false` means answer from the app's own fallback |
-| `useActiveResource(resource)` | `(ContextResource \| null) => void` | Publish the record currently open in the app so manager handover and context menus stay grounded |
-| `useCollectionInteractions(opts)` | `(opts) => CollectionInteractionController` | Keyboard navigation, active-row state, range/toggle selection, marquee selection, and action dispatch for collection UIs |
-| `useShortcuts(definitions, opts?)` | `(definitions, opts?) => void` | Register scoped keyboard shortcuts. Editable targets are ignored unless explicitly allowed; use `ShortcutHints` to display them |
-| `MarkdownEditor` | `(NotisMarkdownEditorProps) => ReactElement` | Use the host editor with app-owned persistence, stable `resourceKey`, revision-aware `onSave`, and optional `onUploadFile` returning a durable URL |
-| `useAgentContext()` / `NotisCommentBoundary` / `NotisCommentBox` | generic context API and optional UI | App-defined pills, icons, context, attachments and nearby comments; see [Context sharing](context.md) |
-| `NotisSelectionBoundary` | `(NotisSelectionBoundaryProps) => ReactElement` | Attach structured, explicitly untrusted app/resource/selection context to selected content and copy operations |
-| `SelectionCheckbox` / `SelectionMarquee` | components | Standard selection controls backed by `useCollectionInteractions` |
-| `MultiSelectActionBar` | component | Standard bulk actions with pending/disabled state and shortcut support |
-| `Dialog` | `{ open, onClose, title, description?, role?, children }` | Themed native modal with top-layer stacking, focus handling and background shortcut isolation. Use `role="alertdialog"` for destructive confirmation; put the safe action first. |
-
-Import headless collection action types and helpers from
-`@notis/sdk/interactions`. Keep an open detail view synchronized with
-`useActiveResource`, and wrap its selectable content in
-`NotisSelectionBoundary` so the manager receives both the active record and the
-user's exact selection. For `MarkdownEditor`, keep `resourceKey` stable per
-record, pass the latest revision back from `onSave`, reject revision conflicts
-instead of overwriting newer data, and implement `onUploadFile` whenever the
-editor should accept media or file blocks.
-
-### App configuration additions
-
-- `toolBindings` is only for provider-generated public tool names whose upstream
-  action cannot be reconstructed. Keep the exact final public `name` in
-  `tools`, then bind it to `providerToolName`; the public name remains the
-  permission boundary.
-
-### Typed tool calls
-
-`useTool` accepts generic argument and result types. Query the database at dev time to discover actual property shapes, then keep those types in the app:
+# SDK reference for Space views
+
+Import hooks/components from `@notis/sdk`; configuration helpers are in
+`@notis/sdk/config`. `NotisProvider` already installs shortcut support. Use the
+scoped host runtime—source never owns an account credential or backend transport.
+
+## Records and declared reads
+
+| API | Use |
+| --- | --- |
+| `useViewParams<typeof definition>()` | `{params, invalid, missing, declared, ready}` for declared typed URL params. Unknown names are dropped; invalid values use their declared default. |
+| `useShown<Row>(name, options?)` | Execute the native list in `shows[name]` with current params. Options: `sorts`, `pageSize`, `offset`, `includeContent`; result includes `data`, `loading`, `hasData`, `error`, `refetch`. |
+| `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; identify read-only calls explicitly and retain request IDs/revisions for writes. Never call account-wide tools from a Space. |
+| `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/app labels, route and ready state. Use `resource.id` for the current Space identity. |
 
 ```tsx
-type QueryTasksArgs = { database_id?: string; database_slug?: string; query: { page_size?: number } };
-interface TaskDoc {
-  title: string;
-  properties: {
-    Status: string;
-    Priority: string;
-    Due: string;
-  };
-};
-type QueryTasksResult = { documents: TaskDoc[] };
-
-const queryTasks = useTool<QueryTasksArgs, QueryTasksResult>('LOCAL_NOTIS_DATABASE_QUERY');
-const result = await queryTasks.call({ database_id: 'tasks-db-id', query: { page_size: 25 } });
-// result.documents[0].properties.Status is typed as string
+const { resource } = useNotis();
+const nav = useNotisNavigation();
+const { params } = useViewParams<typeof definition>();
+const rows = useShown<{ record_key: string; title: string | null }>('notes');
+// In the row's click handler:
+nav.toSpace(resource.id, { recordKey: row.record_key });
+// In the record branch:
+<DocumentPage recordKey={params.note} breadcrumb={[{ label: 'All notes', onSelect: () => nav.toSpace(resource.id) }]} />
 ```
+
+Keep hooks unconditional. Preserve cached content during refresh; `loading` is
+first-read state, not every fetch. Use [Design](design.md#instant-view-loading-contract-required)
+for loading/error/empty states and explicit read caching.
+
+## First-party record components
+
+| Component | Contract |
+| --- | --- |
+| `<DocumentPage recordKey>` | The full page of a record that is the view's main content (a note, a document): breadcrumb, Saving or Saved, '...' menu, cover, icon, title, meta strip, properties that save automatically, collaborative body. Slots `breadcrumb`, `actions`, `menuItems`, `aboveBody`, `belowBody`; toggles `share` (off by default), `header`, `meta`, `properties`, `width`; `onSaved`; `layout` to rearrange its parts. Pair with `DocumentPageSkeleton` and `usePrefetchRecord()`. Until the Notis CLI you build with exports it (`spaces build` replaces the Space's `packages/sdk` with the CLI's own SDK, and older ones have no `DocumentPage`, so the import fails the build), reach the same host page through `useNotisRuntime().ui?.DocumentPage` and fall back to `DocumentEditor` when it is missing, as the Notes Spaces do in `lib/document-page.tsx`. |
+| `<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. |
+| `<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. |
+
+The published Space declares the database binding; the server rechecks record
+scope and binding revision. A Site exposes read-only body/property snapshots and
+HTML for its pinned record, including a declared non-collection record param.
+It has no upload, collaboration credential, authoring controls or sharing mutation.
+Preview source does not gain live record editing. No app-owned credentials or
+filesystem URLs belong in component props.
+
+## Navigation
+
+`useNotisNavigation()` exposes `toSpace(spaceId, {recordKey?, params?})` and
+`toNamedSpace(alias, {recordKey?, params?})`. 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.
+
+## 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
+
+`<RenderChartData title columns rows>` adds a semantic table for the chart without
+a second visible table. Give it the same labels/values used by the chart. The
+renderer never guesses exact numbers from SVG/canvas geometry: a chart without
+`RenderChartData` 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.
+- `useTopBarSearch` registers a host-owned search field. 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.
+- `useCollectionInteractions`, selection components and `MultiSelectActionBar`
+  support native collection interactions. `Dialog` supplies themed top-layer
+  dialogs, focus handling and shortcut isolation.
+- `MarkdownEditor` is for a view-owned Markdown draft/persistence adapter. Native
+  documents use `DocumentEditor` so collaboration and file authority stay with Notis.
+
+## Offline fixtures
+
+Declare a `verificationFixtures` JSON source with `actions` and optional `context`,
+`shown`, `viewerReads`, `documentBodies`, `recordViews`. Cases match exact action
+inputs/list params. Record views use `{operation: 'record'|'html'|'report', record_key,
+result}`; native record snapshots require `writable: false` and no authoring target.
+Keep every fixture fictional and include every load-time read. Failed or missing
+fixtures fail verification; there is no fallback to the user's real account.

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

@@ -1,23 +1,24 @@
-## Troubleshooting
+# Troubleshooting
 
-Start with the failing screen or operation. Do not invent a second app workflow;
-use the [delivery guide](release.md) and supported Notis CLI commands.
+Start with the actual failing operation and its exact Space, source/record
+revision and current target. [Delivery](release.md) owns the release sequence.
 
-- **App looks wrong despite passing checks:** open it inside Notis and compare
-  the affected region with the request. Check loading and loaded states, viewport
-  sizing, scrolling, and theme. A standalone harness does not reproduce the host's
-  parent layout or shadow boundary. Do not assume the cause from a screenshot alone.
-- **Build reports a design violation:** use the scaffold component or theme token
-  suggested by the diagnostic. Fix the reported file/line rather than hiding the
-  pattern elsewhere. Existing validator exceptions are for justified cases, not a
-  shortcut around visual review.
-- **The configured sidebar is missing:** preserve `routes` and `collection.sidebar`;
-  investigate the host mismatch instead of duplicating the sidebar in app code.
-- **The app shows old code or is missing from Workspace:** check the exact installed
-  app/version and requested bundle first. Local source edits and Desktop restarts
-  do not update a released app. Refresh after confirming the correct release exists.
-- **Deploy transport failure:** run `notis doctor` and read back the exact app/version.
-  Reconcile the outcome before retrying; do not bypass the backend with storage writes.
-- **Database query is empty or properties are undefined:** inspect the actual schema,
-  database ID, and returned property shape through the CLI. Keep types in the app,
-  guard optional fields, and distinguish an error from a successful empty result.
+| Failure | Check |
+| --- | --- |
+| Build rejects a view | Required `specVersion`, path, descriptions, params, executable shows and memory; use the file/line diagnostic. |
+| 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. |
+| Uncertain deployment | Run `notis doctor`, read the same Space and release/request identity, then reconcile before retrying. |
+| 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.