@notis_ai/cli 0.2.18 → 0.2.20

package/dist/view-renderer/src/renderer.js

@@ -0,0 +1,279 @@
+import { readFile } from 'node:fs/promises';
+import { createBrowserPool } from './pool.js';
+import { expandScrollAreas, freezeAnimations, extractRenderedMarkdown, restrictBrowserTransports, freezeFrameViewportSizes, settleFrameImages } from './dom.js';
+import { ViewRenderError, renderFailure } from './errors.js';
+import { createPngStitcher } from './png.js';
+
+export const RENDER_ORIGIN = 'http://notis-render.invalid';
+const READ_OPERATIONS = new Set(['action', 'shown', 'viewer_read', 'document_body', 'record', 'html', 'report', 'resolve_links']);
+const CSP = "default-src 'none'; script-src 'self' blob: data: 'unsafe-inline'; style-src 'self' 'unsafe-inline'; img-src 'self' data: blob:; font-src 'self' data:; connect-src 'self'; frame-src 'self' blob: data:; worker-src 'none'; form-action 'none'; base-uri 'none'; object-src 'none'";
+const DEFAULT_HTML = '<!doctype html><html><head><meta charset="UTF-8"><meta name="viewport" content="width=device-width,initial-scale=1"><link rel="stylesheet" href="/theme.css"><link rel="stylesheet" href="/host.css"></head><body><script src="/host.js"></script></body></html>';
+
+function inputs({ outputs = ['markdown', 'screenshot'], width = 1440, timeoutMs = 45000 }) {
+  if (!Array.isArray(outputs) || !outputs.length || new Set(outputs).size !== outputs.length || outputs.some(value => !['markdown', 'screenshot'].includes(value))) throw new TypeError('Choose markdown and/or screenshot once.');
+  if (![390, 1440].includes(width)) throw new TypeError('Render at 390 or 1440 CSS pixels.');
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 90000) throw new TypeError('Use a bounded render timeout.');
+  return { outputs, width, timeoutMs };
+}
+function publicSnapshot(snapshot) {
+  // Explicit whitelist: never spread a ticket, broker object, endpoint or token
+  // into source-visible bootstrap data, even when the provider adds fields.
+  return { descriptor: snapshot.descriptor, source: snapshot.source, css: snapshot.css || '',
+    cacheKey: snapshot.cacheKey, markdownExport: snapshot.markdownExport || null,
+    url: snapshot.url, hostCss: snapshot.hostCss || '', params: snapshot.params || {}, locale: snapshot.locale || 'en' };
+}
+
+const PNG_LIMIT = 32 * 1024 * 1024;
+const CAPTURE = { type: 'png', animations: 'disabled', caret: 'hide', scale: 'css' };
+
+/**
+ * Chromium rasterizes everything a screenshot captures beyond the viewport, so a
+ * capture outside it costs memory in proportion to the page height, even when
+ * clipped to a slice: a tall page on a small instance is killed for memory.
+ * A page taller than one tile (the viewport, or sliceHeight when smaller) is
+ * scrolled one tile at a time and each tile is captured from the viewport only,
+ * so Chromium never paints more than one viewport, and the tiles are stitched
+ * into the full page. Every page is thus painted the way a browser window shows
+ * it. Expansion already set fixed and sticky elements static, so no element
+ * repeats from one tile to the next.
+ */
+async function capturePage(page, sliceHeight, maxBytes, maxHeight, maxPixels) {
+  // Playwright's own full-page size, so tiles cover exactly what one capture would.
+  const measure = () => page.evaluate(() => {
+    const body = document.body, root = document.documentElement;
+    return { width: Math.max(body.scrollWidth, root.scrollWidth, body.offsetWidth, root.offsetWidth, body.clientWidth, root.clientWidth),
+      height: Math.max(body.scrollHeight, root.scrollHeight, body.offsetHeight, root.offsetHeight, body.clientHeight, root.clientHeight),
+      viewport: { width: innerWidth, height: innerHeight } };
+  });
+  const size = await measure();
+  if (size.height > maxHeight || size.width * size.height > maxPixels)
+    throw new ViewRenderError('render_too_large', 'This view exceeds the full-page render limit; nothing was cropped.', 413);
+  const tile = Math.min(sliceHeight, size.viewport.height);
+  // A page within one tile fits the viewport, where Playwright captures it as is.
+  if (size.height <= tile) return page.screenshot({ ...CAPTURE, fullPage: true });
+  // Each tile is compressed into the output as it is captured, so no tile is held.
+  const stitcher = createPngStitcher({ maxBytes });
+  if (size.width !== size.viewport.width) {
+    // A page wider than the viewport has no viewport tile that holds a whole row:
+    // capture clipped slices of the full layout instead, at their higher cost.
+    for (let y = 0; y < size.height; y += sliceHeight) {
+      const height = Math.min(sliceHeight, size.height - y);
+      const slice = await page.screenshot({ ...CAPTURE, fullPage: true, clip: { x: 0, y, width: size.width, height } });
+      if (slice.readUInt32BE(16) !== size.width || slice.readUInt32BE(20) !== height) throw renderFailure('render_unstable');
+      await stitcher.add(slice);
+    }
+    return stitcher.finish();
+  }
+  for (const frame of page.frames()) await frame.evaluate(freezeAnimations);
+  const session = await page.context().newCDPSession(page);
+  try {
+    for (let y = 0; y < size.height; y += tile) {
+      const height = Math.min(tile, size.height - y);
+      // The last scroll stops at the page end; its tile is still inside the viewport.
+      const top = await page.evaluate(([y, height]) => {
+        window.scrollTo(0, y);
+        return new Promise(resolve => requestAnimationFrame(() => resolve(scrollY))).then(top => (top <= y && top + innerHeight >= y + height ? top : -1));
+      }, [y, height]);
+      if (top < 0) throw renderFailure('render_unstable');
+      const { data } = await session.send('Page.captureScreenshot', { format: 'png', captureBeyondViewport: false,
+        clip: { x: 0, y, width: size.width, height, scale: 1 } });
+      const slice = Buffer.from(data, 'base64');
+      if (slice.readUInt32BE(16) !== size.width || slice.readUInt32BE(20) !== height) throw renderFailure('render_unstable');
+      await stitcher.add(slice);
+    }
+  } finally { await session.detach().catch(() => {}); }
+  // Scrolling must not have revealed more of the page than the tiles covered.
+  const after = await measure();
+  if (after.height !== size.height || after.width !== size.width) throw renderFailure('render_unstable');
+  return stitcher.finish();
+}
+
+function diagnosticFailure(error, stage, fallback = 'render_failed') {
+  const failure = error instanceof ViewRenderError
+    ? new ViewRenderError(error.code, error.message, error.status) : renderFailure(fallback);
+  // Private in-process diagnostics only. Public JSON/error projections cannot
+  // enumerate a browser exception, which may contain source or request data.
+  Object.defineProperties(failure, { cause: { value: error }, stage: { value: stage } });
+  return failure;
+}
+
+/** Shared by CLI and warm service. No broad credential is an argument to this library. */
+export async function renderView({ broker, outputs, width, timeoutMs, signal, pool, host, maxHeight = 60000, maxPixels = 80000000, sliceHeight = 2048, maxPngBytes = PNG_LIMIT }) {
+  const config = inputs({ outputs, width, timeoutMs });
+  if (!Number.isInteger(sliceHeight) || sliceHeight < 256 || sliceHeight > 16384) throw new TypeError('Use a bounded screenshot slice height.');
+  if (!Number.isInteger(maxPngBytes) || maxPngBytes < 1 || maxPngBytes > PNG_LIMIT) throw new TypeError('Use a PNG limit within the render transport limit.');
+  const deadline = AbortSignal.timeout(config.timeoutMs);
+  const cancellation = signal ? AbortSignal.any([signal, deadline]) : deadline;
+  // Fail authorization before opening a browser or exposing cached page data.
+  let snapshot;
+  try { snapshot = await broker.snapshot({ signal: cancellation }); }
+  catch (error) { throw diagnosticFailure(error, 'manifest', cancellation.aborted ? 'render_timeout' : 'render_failed'); }
+  if (!snapshot || typeof snapshot.url !== 'string' || !snapshot.view || !snapshot.descriptor || typeof snapshot.source !== 'string') throw renderFailure('render_manifest_invalid');
+  if (snapshot.render_options && (!Array.isArray(snapshot.render_options.outputs) || snapshot.render_options.width !== config.width
+    || JSON.stringify([...snapshot.render_options.outputs].sort()) !== JSON.stringify([...config.outputs].sort()))) {
+    throw new ViewRenderError('render_options_changed', 'Use the outputs and width authorized for this render.', 409);
+  }
+  const hostSource = host?.script ?? await readFile(new URL('../dist/host.js', import.meta.url), 'utf8');
+  snapshot.hostCss = host ? host.css || '' : await readFile(new URL('../dist/host.css', import.meta.url), 'utf8');
+  snapshot.theme_css ||= host ? host.themeCss || '' : await readFile(new URL('../dist/theme.css', import.meta.url), 'utf8');
+  const ownPool = !pool;
+  pool ||= createBrowserPool();
+  const blocked = [];
+  let authorityLost = false, authorityFailure, transientFailure, assetRequests = 0, assetBytes = 0, readRequests = 0;
+  let stage = 'browser_context';
+  let assetOrigin = null;
+  try { const asset = new URL(snapshot.asset_origin); if (asset.protocol === 'https:' && asset.origin === snapshot.asset_origin) assetOrigin = asset.origin; } catch {}
+  const policy = assetOrigin ? CSP.replace("img-src 'self' data: blob:", "img-src 'self' data: blob: " + assetOrigin).replace("font-src 'self' data:", "font-src 'self' data: " + assetOrigin) : CSP;
+  try {
+    return await pool.use(async context => {
+      stage = 'browser_setup';
+      context.setDefaultTimeout(config.timeoutMs);
+      await context.addInitScript(restrictBrowserTransports);
+      // Offline fixtures freeze "now" so time-windowed reads match their recorded
+      // inputs. Timers keep running; live renders send no clock and use real time.
+      const clock = typeof snapshot.fixed_clock === 'string' ? Date.parse(snapshot.fixed_clock) : NaN;
+      if (Number.isFinite(clock)) await context.clock.setFixedTime(new Date(clock));
+      await context.routeWebSocket('**/*', socket => socket.close({ code: 1008, reason: 'Read-only rendering has no sockets.' }));
+      await context.route('**/*', async route => {
+        const request = route.request();
+        const url = new URL(request.url());
+        const respond = (status, data, contentType = 'application/json') => route.fulfill({ status, body: typeof data === 'string' ? data : JSON.stringify(data),
+          contentType, headers: { 'Cache-Control': 'no-store', 'Content-Security-Policy': policy, 'X-Content-Type-Options': 'nosniff' } });
+        let payload;
+        try {
+          if (url.origin !== RENDER_ORIGIN || url.search || url.hash) {
+            const kind = request.resourceType();
+            if (url.origin === assetOrigin && request.method() === 'GET' && ['image', 'font'].includes(kind)
+                && !url.search && !url.hash && ++assetRequests <= 128) {
+              const asset = await broker.read({ operation: 'asset', url: url.href, kind }, { signal: cancellation });
+              const bytes = Buffer.from(asset.data_base64, 'base64'); assetBytes += bytes.length;
+              if (assetBytes > 32 * 1024 * 1024 || !/^(image|font)\//.test(asset.mime_type)) throw renderFailure('render_asset_limit');
+              return route.fulfill({ status: 200, body: bytes, contentType: asset.mime_type,
+                headers: { 'Cache-Control': 'no-store', 'Access-Control-Allow-Origin': '*', 'X-Content-Type-Options': 'nosniff' } });
+            }
+            if (blocked.length < 100) blocked.push({ code: 'render_egress_denied' });
+            return route.abort('blockedbyclient');
+          }
+          if (request.method() === 'GET') {
+            if (url.pathname === '/') return respond(200, host?.html || DEFAULT_HTML, 'text/html');
+            if (url.pathname === '/host.js') return respond(200, hostSource, 'text/javascript');
+            if (url.pathname === '/host.css') return respond(200, snapshot.hostCss || '', 'text/css');
+            if (url.pathname === '/theme.css') return respond(200, snapshot.theme_css || '', 'text/css');
+            if (url.pathname === '/__snapshot') return respond(200, publicSnapshot(snapshot));
+            return respond(404, { error: 'render_resource_unavailable' });
+          }
+          if (url.pathname !== '/__read' || request.method() !== 'POST' || (request.postData()?.length || 0) > 262144) return respond(403, { error: 'render_read_only' });
+          payload = request.postDataJSON();
+          if (!payload || typeof payload !== 'object' || Array.isArray(payload) || !READ_OPERATIONS.has(payload.operation)) {
+            if (blocked.length < 100) blocked.push({ code: 'render_read_only' });
+            return respond(403, { error: 'render_read_only', message: 'Rendering never changes records or runs write actions.' });
+          }
+          if (++readRequests > 128) throw new ViewRenderError('render_read_limit', 'This render exceeded its read limit.', 429);
+          // The server independently reconstructs and classifies every call.
+          const result = await broker.read(payload, { signal: cancellation });
+          return respond(200, { result });
+        } catch (error) {
+          const code = ['render_read_only', 'render_paid_background_denied'].includes(error?.code) ? error.code : 'render_read_unavailable';
+          if (['render_read_only', 'render_paid_background_denied'].includes(code)) {
+            if (blocked.length < 100) blocked.push({ code, ...(typeof payload?.action_id === 'string' && /^[a-zA-Z0-9_-]{1,100}$/.test(payload.action_id) ? { action_id: payload.action_id } : {}) });
+          } else if (error?.status >= 500 || error?.status === 429) {
+            // Backend load is not an access change: fail the capture as retryable.
+            transientFailure ||= error;
+          } else { authorityLost = true; authorityFailure ||= error; }
+          await respond(error?.status === 401 || error?.status === 404 ? error.status : 403, { error: code, message: 'This read is unavailable in the current render.' }).catch(() => {});
+        }
+      });
+      const page = await context.newPage();
+      context.on('page', child => { if (child !== page) void child.close(); });
+      stage = 'host_navigation';
+      await page.goto(RENDER_ORIGIN, { waitUntil: 'domcontentloaded' });
+      stage = 'host_ready';
+      await page.waitForFunction(() => window.__notisRenderState?.mounted && window.__notisRenderState.pending === 0 && performance.now() - window.__notisRenderState.lastActivity > 100, undefined, { timeout: config.timeoutMs });
+      // A committed data response must settle React layout and browser fonts.
+      stage = 'fonts_layout';
+      await page.evaluate(async () => {
+        await Promise.race([document.fonts.ready, new Promise(resolve => setTimeout(resolve, 2000))]);
+        await new Promise(resolve => requestAnimationFrame(() => requestAnimationFrame(resolve)));
+      });
+      let lastHeight = -1, settled = false;
+      const frozenFrames = new WeakSet();
+      stage = 'layout_expansion';
+      for (let pass = 0; pass < 10; pass++) {
+        for (const frame of [...page.frames()].reverse()) {
+          if (!await frame.evaluate(settleFrameImages)) throw renderFailure('render_asset_unavailable');
+          if (frame !== page.mainFrame() && !frozenFrames.has(frame)) {
+            await frame.evaluate(freezeFrameViewportSizes); frozenFrames.add(frame);
+          }
+          const size = await frame.evaluate(expandScrollAreas, { maxHeight });
+          if (size.tooLarge) throw new ViewRenderError('render_too_large', 'This view exceeds the full-page render limit; nothing was cropped.', 413);
+          if (frame !== page.mainFrame()) await (await frame.frameElement()).evaluate((node, height) => {
+            node.style.setProperty('height', `${height}px`, 'important'); node.style.setProperty('min-height', `${height}px`, 'important');
+            node.style.setProperty('max-height', 'none', 'important'); node.style.setProperty('flex-shrink', '0', 'important');
+            node.style.setProperty('flex-basis', 'auto', 'important');
+          }, size.height);
+        }
+        // Expansion can reveal lazy rows and trigger additional declared reads.
+        // Wait for their committed DOM before deciding that the full page fits.
+        await page.waitForFunction(() => window.__notisRenderState.pending === 0 && performance.now() - window.__notisRenderState.lastActivity > 100,
+          undefined, { timeout: config.timeoutMs });
+        const height = await page.evaluate(() => Math.max(document.documentElement.scrollHeight, document.body.scrollHeight));
+        if (height === lastHeight) { settled = true; break; }
+        lastHeight = height;
+      }
+      if (!settled) throw new ViewRenderError('render_unstable', 'This view did not settle into a full-page capture; nothing was cropped.', 409);
+      if (blocked.some(value => value.code === 'render_paid_background_denied')) throw new ViewRenderError('render_paid_background_denied', 'Background snapshots cannot run paid reads.', 403);
+      const dimensions = await page.evaluate(() => {
+        const body = document.body, root = document.documentElement;
+        return { width: Math.max(body.scrollWidth, root.scrollWidth, body.offsetWidth, root.offsetWidth, body.clientWidth, root.clientWidth),
+          height: Math.max(body.scrollHeight, root.scrollHeight, body.offsetHeight, root.offsetHeight, body.clientHeight, root.clientHeight) };
+      });
+      if (dimensions.height > maxHeight || dimensions.width * dimensions.height > maxPixels) throw new ViewRenderError('render_too_large', 'This view exceeds the full-page render limit; nothing was cropped.', 413);
+      let markdown, screenshot;
+      if (config.outputs.includes('markdown')) {
+        stage = 'markdown';
+        let override;
+        try { override = await page.evaluate(async () => {
+          if (typeof window.__notisRenderMarkdown === 'function') return await window.__notisRenderMarkdown();
+          return null;
+        }); } catch { throw renderFailure('render_markdown_invalid'); }
+        if (override !== null && typeof override !== 'string') throw renderFailure('render_markdown_invalid');
+        markdown = override ?? (await Promise.all(page.frames().map(frame => frame.evaluate(extractRenderedMarkdown, { baseUrl: snapshot.url })))).filter(Boolean).join('\n\n');
+        if (Buffer.byteLength(markdown, 'utf8') > 2000000) throw new ViewRenderError('render_too_large', 'The Markdown exceeds the render limit.', 413);
+        markdown = markdown.replace(/\r\n/g, '\n').trim() + '\n';
+      }
+      if (config.outputs.includes('screenshot')) {
+        stage = 'screenshot';
+        const png = await capturePage(page, sliceHeight, maxPngBytes, maxHeight, maxPixels);
+        if (png.readUInt32BE(20) > maxHeight || png.readUInt32BE(16) * png.readUInt32BE(20) > maxPixels)
+          throw new ViewRenderError('render_too_large', 'This view exceeds the full-page render limit; nothing was cropped.', 413);
+        if (png.length > maxPngBytes) throw new ViewRenderError('render_too_large', 'The PNG exceeds the render transport limit; nothing was cropped.', 413);
+        screenshot = { mime_type: 'image/png', viewport_width: config.width, data_base64: png.toString('base64'), width: png.readUInt32BE(16), height: png.readUInt32BE(20) };
+      }
+      stage = 'read_completion';
+      if (blocked.some(value => value.code === 'render_paid_background_denied')) throw new ViewRenderError('render_paid_background_denied', 'Background snapshots cannot run paid reads.', 403);
+      for (const code of await page.evaluate(() => (window.__notisRenderState.blocked || []).filter(value => value === 'render_read_only').slice(0, 100))) {
+        if (blocked.length < 100) blocked.push({ code });
+      }
+      if (transientFailure && !authorityLost && !cancellation.aborted) {
+        const failure = new ViewRenderError('render_temporarily_unavailable', 'The view could not be rendered right now. Try again in a moment.', 503);
+        Object.defineProperty(failure, 'cause', { value: transientFailure });
+        throw failure;
+      }
+      if (authorityLost || cancellation.aborted || await page.evaluate(() => Boolean(window.__notisRenderState.failed))) {
+        const failure = renderFailure('render_access_changed');
+        if (authorityFailure) Object.defineProperty(failure, 'cause', { value: authorityFailure });
+        throw failure;
+      }
+      // Do not release Markdown or image bytes after revocation/source changes.
+      stage = 'authorize_finish';
+      const finalAuthority = await broker.finish({ signal: cancellation });
+      if (finalAuthority?.valid !== true) throw renderFailure('render_access_changed');
+      return { url: snapshot.url, view: snapshot.view, ...(snapshot.record_key ? { record_key: snapshot.record_key } : {}),
+        ...(typeof finalAuthority.render_id === 'string' ? { render_id: finalAuthority.render_id } : {}),
+        params: snapshot.params || {}, ...(markdown !== undefined ? { markdown } : {}), ...(screenshot ? { screenshot } : {}),
+        rendered_at: new Date().toISOString(), ...(blocked.length ? { blocked_calls: blocked } : {}) };
+    }, { signal: cancellation, width: config.width, locale: snapshot.locale || 'en', timezone: snapshot.timezone || 'UTC' });
+  } catch (error) {
+    throw diagnosticFailure(error, stage, cancellation.aborted ? 'render_timeout' : 'render_failed');
+  } finally { if (ownPool) await pool.close(); }
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.18",
-  "description": "Agent-first Notis CLI for apps and generic tool execution",
+  "version": "0.2.20",
+  "description": "Agent-first Notis CLI for Spaces, Skills and generic tool execution",
   "type": "module",
   "bin": {
     "notis": "bin/notis.js"
@@ -22,19 +22,20 @@
     "prepack": "npm run build",
     "pretest": "npm run build",
     "release:prepare": "npm run build && node ./scripts/prepare-publish.js --apply",
-    "cli:set-mode": "node ./scripts/set-cli-mode.js",
     "smoke": "node ./scripts/smoke-package.js",
-    "test": "node --test --test-timeout=120000"
+    "test": "node --test --test-timeout=120000",
+    "preinstall": "node ./bin/check-runtime.js"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=22.12.0"
   },
   "dependencies": {
-    "commander": "^12.0.0",
-    "sharp": "^0.34.5"
-  },
-  "devDependencies": {
-    "esbuild": "^0.28.2"
+    "@babel/parser": "^7.29.9",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1",
+    "commander": "^15.0.0",
+    "esbuild": "^0.28.2",
+    "playwright-core": "1.63.0"
   },
   "keywords": [
     "notis",
@@ -45,5 +46,14 @@
   "publishConfig": {
     "access": "public"
   },
-  "license": "MIT"
+  "license": "MIT",
+  "devDependencies": {
+    "react": "19.3.0",
+    "react-dom": "19.3.0"
+  },
+  "notisRelease": {
+    "sourceSha": "2f38334adf5ebfc2aecbc3c7ae6f5ad7a14c6a0b",
+    "channel": "stable"
+  },
+  "gitHead": "2f38334adf5ebfc2aecbc3c7ae6f5ad7a14c6a0b"
 }

package/skills/notis-cli/AGENT_INSTRUCTIONS.md

@@ -1,7 +1,7 @@
 <!-- notis-cli:instructions:start -->
 ## Notis CLI
 
-Use the Notis CLI (`npx --package @notis_ai/cli@latest -- notis ...`) whenever the task involves the user's personal data or connected services: integrations (Gmail, Google Calendar, Notion, Slack, GitHub, ...), long-term memories, reminders, automations, native Notis databases and notes, public deep research, or Notis apps. Prefer it over telling the user to operate another app manually, and never treat a task as blocked merely because a capability is absent from the current tool list—reach it through the CLI.
+Use the Notis CLI (`npx --package @notis_ai/cli@latest -- notis ...`) whenever the task involves the user's personal data or connected services: integrations (Gmail, Google Calendar, Notion, Slack, GitHub, ...), long-term memories, reminders, automations, native Notis databases and notes, and public deep research. Prefer it over telling the user to operate another app manually, and never treat a task as blocked merely because a capability is absent from the current tool list—reach it through the CLI.
 
 On a local machine, `notis login` authorizes a scoped, revocable OAuth profile in the browser. Notis Desktop may authorize that profile automatically, but the Desktop app does not need to remain running. Hosted Notis shells use `NOTIS_JWT`. Before acting on personal data, run `notis whoami` when the intended account or endpoint is not already clear.
 
@@ -9,31 +9,82 @@ Relevant Notis long-term memory may be injected into a turn inside `<notis_relev
 
 ### Tool access workflow
 
-1. Discover tools with natural language: `notis tools search "<full description of what you need>"`—never guess tool names. `notis tools toolkits` lists connected namespaces.
+1. Discover tools with natural language: `notis tools search "<full description of what you need>"` for anything not listed below; never guess tool names, identifiers, or argument shapes. `notis tools toolkits` lists connected namespaces.
 2. Inspect the schema when unsure: `notis tools describe <TOOL>` or `notis tools exec <TOOL> --get-schema`.
 3. Validate mutating calls first: `notis tools exec <TOOL> --dry-run --arguments '<json>'`.
 4. Execute: `notis tools exec <TOOL> --arguments '<json>'`; batch independent calls with `notis tools exec-parallel '<json-array>'`.
 5. If an integration is not connected, `notis tools link <toolkit>` prints a connection URL to give the user.
 
-Tool name shapes: `LOCAL_NOTIS_*` (native Notis), `LOCAL_NOTIS_DATABASE_*` (databases and notes), `LOCAL_MCP_*` (the user's connected MCP servers), and integration tools such as `GMAIL_*`, `NOTION_*`, and `GOOGLECALENDAR_*`.
+For memory writes, reminders, automations, database writes, public deep research and Notis Spaces, discover the tools not listed below and follow the applicable installed Skill.
 
-### Main features
+Run one discovery query per capability and reuse its tool names and schemas marked `hasFullSchema: true`; fetch a schema only when it is missing or incomplete. For a large answer, capture it once, keep stderr separate from stdout, and inspect the saved response locally instead of truncating it and repeating discovery. A returned session field is a tool argument, not an instruction to add CLI flags.
 
-- **Memories:** Search with `LOCAL_NOTIS_SEARCH_MEMORIES` before assuming you lack user context; save durable facts and preferences with `LOCAL_NOTIS_SAVE_LONG_TERM_MEMORY`. Never save secrets, failed-operation conclusions, or one-off conversational details.
-- **Reminders:** `LOCAL_NOTIS_LIST_REMINDERS`, `LOCAL_NOTIS_INSERT_REMINDER`, `LOCAL_NOTIS_UPDATE_REMINDER`, `LOCAL_NOTIS_DELETE_REMINDER`. A reminder delivers fixed text at a time (one-off or recurring cron).
-- **Automations:** `LOCAL_NOTIS_INSERT_AUTOMATION`, `LOCAL_NOTIS_UPDATE_AUTOMATION`, and `LOCAL_NOTIS_RUN_AUTOMATION` run an agent prompt on a cron schedule or event trigger; `LOCAL_NOTIS_LIST_INTEGRATION_TRIGGERS` lists triggers. Fixed text at a time is a reminder; work an agent must perform is an automation.
-- **Databases and notes:** `LOCAL_NOTIS_DATABASE_QUERY` reads; generated `LOCAL_NOTIS_DATABASE_UPSERT_<SLUG>` tools write rows; `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` creates or alters a schema. Discover the exact per-database tool names before use.
-- **Deep research:** `LOCAL_NOTIS_DEEP_SEARCH` performs public multi-source research.
-- **Notis apps:** `notis apps init|pull|dev|build|verify|create|link|deploy|doctor`. For local testing, stop after `apps dev`. If deployment is explicitly requested, build and verify first. Store submission is separate: never run `apps publish --confirm-ready` without explicit approval of the current Store preview.
+Tool name shapes: `LOCAL_NOTIS_*` (native Notis), `LOCAL_NOTIS_DATABASE_*` (databases and notes), `CUSTOM_*` (the user's remote MCP servers), `LOCAL_MCP_*` (MCP servers on the user's computer), and integration tools such as `GMAIL_*`, `NOTION_*`, and `GOOGLECALENDAR_*`.
+
+### Notis tools to call directly
+
+Call these with `notis tools exec <TOOL>` (add `--get-schema` first when you need the arguments), without `notis tools search`. Search only for anything else.
+
+```json
+[
+ {
+  "name": "LOCAL_NOTIS_LOAD_CONVERSATION_HISTORY",
+  "description": "Read the current or specified owned topical conversation, including user replies, sent messages, attachments, saved voice transcripts with speaker roles and delivery state. Use LOCAL_NOTIS_SEARCH_THREADS to find another conversation when its thread_id is unknown. Raw provider payloads and developer/tool internals are not returned. Omit after and limit for full history; pass limit (1–200) to page from the start, then reuse next_cursor as after. Cursor reads default to 50 records and return immediately, even when empty. Merge records by record_id, replacing that record’s items on each revision; removed records delete prior items. Reads are independent and never consume another agent’s replies. Poll as often as your task needs; sending is always a separate explicit action."
+ },
+ {
+  "name": "LOCAL_NOTIS_SEARCH_THREADS",
+  "description": "Find the current user's earlier conversations across channels, including voice calls. Search by title/latest inbound user-message preview and filter by channel, source, status, failure cause or date. A failed conversation has status 'failed' and names its saved cause in failure_cause. This is not full-transcript search: broaden a missed keyword query or list recent threads, then inspect likely matches with LOCAL_NOTIS_LOAD_CONVERSATION_HISTORY using the returned thread_id. Returns up to 50 summaries."
+ },
+ {
+  "name": "LOCAL_NOTIS_SEARCH_MEMORIES",
+  "description": "Search the user's Supermemory knowledge, including long-term memories and synced native documents."
+ },
+ {
+  "name": "LOCAL_NOTIS_SEARCH_HELP_CENTER",
+  "description": "Provide exactly one of query or guide_uri. Read a built-in Notis operating guide with guide_uri, or search Help Center documentation (help.notis.ai) with query for features, pricing, setup, troubleshooting and how-tos. Built-in guides come from canonical product Skills and require no shell or account-resource lookup."
+ },
+ {
+  "name": "LOCAL_NOTIS_AUTHENTIFY",
+  "description": "Generate an authentication link or setup request for a toolkit such as Gmail, Google Calendar, PostForMe, or MCP. Use this to help the user connect or reconnect an app."
+ },
+ {
+  "name": "LOCAL_NOTIS_LIST_CHANNEL_CONNECTIONS",
+  "description": "List the current user's connected messaging accounts across Telegram, WhatsApp, Messages, email, and Slack. Email rows cover every email address Notis recognizes for this user: the primary sign-in email (primary=true, cannot be disconnected) and each added address (alias). Returns safe exact selectors for status checks and disconnect previews."
+ },
+ {
+  "name": "LOCAL_NOTIS_GET_CHANNEL_CONNECTION_STATUS",
+  "description": "Authoritatively read one native messaging channel for the current user. Messages results separate owned account state, recent inbound routing, provider-bridge configuration, recorded recipient restriction metadata (live provider state is not checked), and exact outbound receipt state. Report these facets separately; recorded restriction metadata is not a live provider check. provider_accepted means accepted for sending, not received; recipient delivery stays not_checked (unverified) unless a separate delivery receipt proves it. Third-party integration absence (LOCAL_NOTIS_GET_INTEGRATIONS_STATUS) and generic provider text do not prove disconnect; offer reconnect only when the returned account facet requires it. Pass connection_id for verification flows; Slack can be checked by channel after OAuth."
+ },
+ {
+  "name": "LOCAL_NOTIS_BEGIN_CHANNEL_CONNECTION",
+  "description": "Start a provider-verification or authorization flow for one messaging channel. To add an email address or alias, pass channel=email with identifier: Notis emails a one-time confirmation link and also returns a prepared verification email. already_connected means the address is already on this account; code email_in_use means another account owns it. Never report the channel as connected until LOCAL_NOTIS_GET_CHANNEL_CONNECTION_STATUS reads back an owned account."
+ },
+ {
+  "name": "LOCAL_NOTIS_DISCONNECT_CHANNEL_CONNECTION",
+  "description": "Preview or disconnect one exact owned messaging account, including an added email address (alias). Defaults to preview. The primary sign-in email cannot be disconnected. Disconnect pauses active dependent reminders and automations, clears their destination, and never reroutes or resumes them automatically."
+ },
+ {
+  "name": "LOCAL_NOTIS_SEND_USER_MESSAGE",
+  "description": "Send a message to the Notis account owner on a connected channel or account, returning immediately after durable acceptance (not delivery or a user reply). Only for delivering a message to the user on another channel or account; never to answer in the current conversation (your final message is that answer) and never to message other people. Choose the destination explicitly on every send; no automatic channel forwarding. When an account selection is ambiguous, the result lists available selectors. Supply agent_name and agent_description on every call; optional context adds message-specific detail. Omit thread_id to create a topic or supply an existing account-owned thread_id to continue it. Do not resend a pending message. A send from an agent Notis runs (a Notis sub-agent) claims nothing: the user's reply in that thread goes to the Notis orchestrator like any other message, so do not poll for it. Every other accepted send, such as one from an agent outside Notis, claims its thread for your agent: latest send wins, and the orchestrator cannot answer or launch work in agent-owned threads. Poll LOCAL_NOTIS_LOAD_CONVERSATION_HISTORY with that thread_id at your chosen frequency for delivery status and all user replies; reuse its cursor for incremental reads."
+ },
+ {
+  "name": "LOCAL_NOTIS_REPORT_BUG",
+  "description": "Report a bug or issue directly to Flo — the creator of Notis.ai. Use this when a user encounters a problem, error, or unexpected behavior and wants to report it, or asks to escalate a complaint to a human. The bug report will be sent to the team with the user's context (user_id, email, phone, thread_id) for investigation, and returns a ticket ID (e.g. NB-3F9A2C41) — always share it with the user so they can reference the report later. Works regardless of the user's subscription state."
+ },
+ {
+  "name": "LOCAL_NOTIS_GET_INTEGRATIONS_STATUS",
+  "description": "Retrieves authentication status for the user's third-party integrations. It does not report Notis native messaging-channel state: an integration missing here is not a native channel disconnect, so never offer a channel reconnect from it. Use LOCAL_NOTIS_GET_CHANNEL_CONNECTION_STATUS for Telegram, WhatsApp, Messages, email, or Slack channel diagnostics."
+ }
+]
+```
 
 ### Rules
 
-- Discovery first: never invent tool names, identifiers, or argument shapes.
 - Cold discovery can exceed 30 seconds. Use `--timeout-ms 90000` for discovery calls when needed; after `network_timeout`, retry the exact command once with that timeout instead of looping.
-- Before creating a reminder or automation, list existing ones to prevent duplicates. Confirm schedule, timezone, and delivery channel when ambiguous.
 - Before writing a Notion or native database row, read the schema and relevant property descriptions.
 - When answering about meetings or availability, check every connected calendar.
 - Use `notis doctor` before concluding that authentication or API reachability is broken.
 - Keep credentials and other secrets out of tool arguments and search queries unless the target tool explicitly requires them.
 - If the active harness reports DNS or network restriction errors such as `ENOTFOUND`, host resolution failure, or `fetch failed`, rerun the same CLI request with that harness's network restrictions lifted rather than retrying unchanged.
+
 <!-- notis-cli:instructions:end -->

package/skills/notis-onboarding/BRIEF.md

@@ -48,12 +48,12 @@ The fields onboarding collects, wherever it runs. Both the conversational
 onboarding assistant and the CLI brief reference this partial so the two paths
 can never quietly collect different things.
 
-All of these land through `LOCAL_NOTIS_SAVE_USER_SETTINGS`: `full_name` on the
+All of these land through `LOCAL_NOTIS_SAVE_USER_SETTINGS`: `first_name` on the
 user row, the rest merged into the `settings` blob.
 
 | Field | Setting key | What it is for |
 |---|---|---|
-| First name | `full_name` | How Notis addresses the user. Deduce from the email before asking. |
+| First name | `first_name` | How Notis addresses the user. Ask for their given name; preserve compound names and do not infer it from an email address. |
 | Occupation / role | `position` | Tailors examples and suggestions. |
 | Language | `language` | The language Notis replies in. |
 | Time zone | `timezone` | Anchors every scheduled and time-relative request. Ask; never guess silently. |
@@ -63,8 +63,9 @@ Rules that hold on every surface:
 
 * Ask one question at a time. A wall of questions reads as a form, and people
   abandon forms.
-* Skip anything already known or confidently deducible, and say what you deduced
-  rather than asking the user to confirm a blank.
+* For first name, skip only when already saved or provided by the user. Never
+  deduce a name. For other fields, skip known or confidently deducible values
+  and say what you deduced rather than asking the user to confirm a blank.
 * Save as soon as you have the basics rather than batching to the end — a user who
   drops out halfway should not lose what they already told you.
 
@@ -74,7 +75,7 @@ what you inferred, and let the user correct you. Then save:
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_SAVE_USER_SETTINGS \
-  --arguments '{"full_name":"...","position":"...","language":"...","timezone":"..."}'
+  --arguments '{"first_name":"...","position":"...","language":"...","timezone":"..."}'
 ```
 
 ## 2. Connect one app, then immediately read from it
@@ -93,9 +94,13 @@ through the connection and show them the actual result: today's calendar events,
 their most recent email threads, the databases in their Notion. A connected
 integration is a claim; their own data on screen is proof.
 
-If they connect nothing, fall back to installing a public app:
-`LOCAL_NOTIS_LIST_PUBLIC_APP_STORE`, then `LOCAL_NOTIS_INSTALL_APP` with
-`destination_type="personal"`.
+If they connect nothing, you may offer a Space from the Space Store instead, but
+only on an account that has the Store: it is not open to every account yet. Check
+with `notis spaces store list` first. If it answers that Spaces or the Store are
+not available for this account (`spaces_unavailable` or
+`spaces_store_unavailable`), skip this fallback without retrying and go to
+step 3. Otherwise install one with
+`notis spaces store install <listing-id> --request-id <stable-id>`.
 
 ## 3. Finish onboarding
 
@@ -125,4 +130,4 @@ in this document.
 
 What they *do* have: 1,000+ integrations through this CLI, skills that sync to
 their coding agents, long-term memory, notes and databases, and the ability to
-build Notis apps from this machine.
+build Notis Spaces from this machine.

package/skills/notis-query/cli.md

@@ -13,7 +13,7 @@ For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOT
 - `LOCAL_NOTIS_DATABASE_LIST_DATABASES` — list native databases.
 - `LOCAL_NOTIS_DATABASE_GET_DATABASE` — inspect one database schema.
 - `LOCAL_NOTIS_DATABASE_QUERY` — query native database documents.
-- `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` — create or update database schema. Creation requires the owning app's slug or id in the `app` argument (every database belongs to a Notis app).
+- `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` — create or update database schema. Creation links the database to at least one Space with `links.add` and names its main view in that Space with `main_view`.
 
 ## Workflow