@notis_ai/cli 0.2.0-beta.159.1 → 0.2.0-beta.160.1

package/skills/notis-apps/cli.md

@@ -26,6 +26,10 @@ For source restoration, pull the current release into a fresh checkout and histo
 another folder. Replace source while retaining the current profile/app link and deployment base,
 change the package release label, check resource compatibility and deploy as a new release.
 
+## Reports
+
+For a record-owned report, use `reports init → build → verify/preview → save` instead of the app deployment workflow above. Author exactly one route, select an existing app-owned database, and supply a readable context file. Revisions preserve the record ID and require its freshly read revision. See the product `notis-reports` skill for source recovery, ownership and readback. These commands do not deploy the owning app or publish a Store listing.
+
 ## Commands
 
 ### `npx --package @notis_ai/cli@latest -- notis doctor`
@@ -222,3 +226,88 @@ When to use: Diagnose issues with a Notis app project.
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps doctor`
 - `npx --package @notis_ai/cli@latest -- notis apps doctor ./my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis reports init <name> [dir]`
+
+Init a record-owned SDK report locally.
+
+When to use: Author an independent report without deploying its owning app.
+
+Options:
+- `--from <slug>` — Start from a published Store app listed by `notis apps scaffolds list`. Downloads its source from the public app registry.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
+- `npx --package @notis_ai/cli@latest -- notis reports init "Mind the Flo"`
+- `npx --package @notis_ai/cli@latest -- notis reports init "My CRM" --from databases`
+- `npx --package @notis_ai/cli@latest -- notis reports init "My App" ~/code/my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis reports build [dir]`
+
+Build a record-owned SDK report locally.
+
+When to use: Author an independent report without deploying its owning app.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis reports build`
+- `npx --package @notis_ai/cli@latest -- notis reports build ./my-app`
+
+### `npx --package @notis_ai/cli@latest -- notis reports verify [dir]`
+
+Verify a record-owned SDK report locally.
+
+When to use: Author an independent report without deploying its owning app.
+
+Options:
+- `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
+- `--port <n>` — Loopback port. Default: auto-pick.
+- `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
+- `--mode <mode>` — stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT and fails routes whose runtime calls all errored.
+- `--listing` — Ignored for reports; saving a report does not publish a Store listing.
+- `--no-browser` — Start the harness server and print URLs; do not drive agent-browser.
+- `--keep-open` — Leave server + browser session running after report (for manual triage).
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis reports verify`
+- `npx --package @notis_ai/cli@latest -- notis reports verify --routes notes`
+- `npx --package @notis_ai/cli@latest -- notis reports verify --mode live`
+- `npx --package @notis_ai/cli@latest -- notis reports verify --no-browser  # start the harness, drive agent-browser yourself`
+
+### `npx --package @notis_ai/cli@latest -- notis reports preview [dir]`
+
+Preview a record-owned SDK report locally. Keeps the preview server and browser session open.
+
+When to use: Author an independent report without deploying its owning app.
+
+Options:
+- `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
+- `--port <n>` — Loopback port. Default: auto-pick.
+- `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
+- `--mode <mode>` — stub | live. Default stub. Live posts to /portal_views/runtime_query with the CLI JWT and fails routes whose runtime calls all errored.
+- `--listing` — Ignored for reports; saving a report does not publish a Store listing.
+- `--no-browser` — Start the harness server and print URLs; do not drive agent-browser.
+- `--keep-open` — Leave server + browser session running after report (for manual triage).
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis reports preview`
+- `npx --package @notis_ai/cli@latest -- notis reports preview --routes notes`
+- `npx --package @notis_ai/cli@latest -- notis reports preview --mode live`
+- `npx --package @notis_ai/cli@latest -- notis reports preview --no-browser  # start the harness, drive agent-browser yourself`
+
+### `npx --package @notis_ai/cli@latest -- notis reports save [dir]`
+
+Build, verify and save a report into an app-owned database record.
+
+When to use: Persist an independently authored report, not an app release.
+
+Options:
+- `--database-id <id>` — Required. Owning app database.
+- `--document-id <id>` — Existing record to update or attach to.
+- `--attach` — Attach to an existing non-view record.
+- `--expected-revision <revision>` — Fresh view revision (0 for a record without a view).
+- `--title <title>` — Required, including updates. Record title.
+- `--context-file <file>` — Required. UTF-8 readable report content and structure.
+- `--properties-file <file>` — JSON database property values keyed by name.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis reports save ./weekly-report --database-id <id> --title "Weekly review" --context-file ./context.md`

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

package/src/command-specs/apps.js

@@ -786,7 +786,7 @@ async function appsVerifyHandler(ctx) {
     });
 
     if (keepOpen) {
-      process.stderr.write(`[notis apps verify] harness open at ${baseUrl}. Press Ctrl-C to stop.\n`);
+      process.stderr.write(`[notis apps verify] harness open at ${urls[0]?.url || baseUrl}. Press Ctrl-C to stop.\n`);
       await new Promise(() => {});
     }
 

package/src/command-specs/index.js

@@ -1,3 +1,4 @@
+import { reportsCommandSpecs } from './reports.js';
 import { appsCommandSpecs } from './apps.js';
 import { toolsCommandSpecs } from './tools.js';
 import { metaCommandSpecs } from './meta.js';
@@ -11,6 +12,7 @@ import { agentsCommandSpecs } from './agents.js';
 import { skillsCommandSpecs } from './skills.js';
 
 export const GROUP_SUMMARIES = {
+  reports: 'Build and save independent SDK reports into app database records.',
   apps: 'Develop, deploy, and submit Notis Apps.',
   agents: 'Install Notis context into local coding agents.',
   handover: 'Hand the branch you are on to a Notis agent, hosted or your own Codex/Claude.',
@@ -28,6 +30,7 @@ export const COMMAND_SPECS = [
   ...agentsCommandSpecs,
   ...skillsCommandSpecs,
   ...appsCommandSpecs,
+  ...reportsCommandSpecs,
   ...handoverCommandSpecs,
   ...toolsCommandSpecs,
   ...diagnosticCommandSpecs,

package/src/command-specs/onboarding.js

@@ -157,7 +157,7 @@ async function authenticatedResult(ctx) {
   }
 
   if (onboardingComplete) {
-    const name = state?.settings?.full_name;
+    const name = state?.settings?.first_name;
     const setupSummary = renderAgentSetup(base.agent_setup);
     return ctx.output.emitSuccess({
       command: 'start',

package/src/command-specs/reports.js

@@ -0,0 +1,86 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { appsCommandSpecs } from './apps.js';
+import { buildArtifact, prepareAppRelease, resolveProjectDir } from '../runtime/app-platform.js';
+import { nextIdempotencyKey, runToolCommand } from './helpers.js';
+import { usageError, EXIT_CODES } from '../runtime/errors.js';
+
+const reuse = (command, name = command) => {
+  const spec = appsCommandSpecs.find(item => item.command_path.join(' ') === `apps ${command}`);
+  return {
+    ...spec,
+    handler: async ctx => {
+      const output = new Proxy(ctx.output, {
+        get(target, key) {
+          if (key === 'emitSuccess') return result => {
+            const value = { ...result, warnings: (result.warnings || []).filter(warning => !warning.startsWith('Store readiness:')) };
+            if (value.data?.listing) { value.data = { ...value.data }; delete value.data.listing; }
+            return target.emitSuccess(value);
+          };
+          const value = Reflect.get(target, key);
+          return typeof value === 'function' ? value.bind(target) : value;
+        },
+      });
+      return spec.handler({ ...ctx, options: { ...ctx.options, listing: false, ...(name === 'preview' ? { keepOpen: true } : {}) }, output });
+    },
+    command_path: ['reports', name],
+    summary: `${name[0].toUpperCase() + name.slice(1)} a record-owned SDK report locally.${name === 'preview' ? ' Keeps the preview server and browser session open.' : ''}`,
+    args_schema: {
+      ...spec.args_schema,
+      options: (spec.args_schema?.options || []).map(option => option.flags === '--listing'
+        ? { ...option, description: 'Ignored for reports; saving a report does not publish a Store listing.' }
+        : option),
+    },
+    examples: (spec.examples || []).filter(example => !example.includes('--listing')).map(example => example.replace(`apps ${command}`, `reports ${name}`)),
+    when_to_use: 'Author an independent report without deploying its owning app.',
+  };
+};
+export const reportsCommandSpecs = [
+  reuse('init'), reuse('build'), reuse('verify'), reuse('verify', 'preview'),
+  {
+    command_path: ['reports', 'save'],
+    summary: 'Build, verify and save a report into an app-owned database record.',
+    when_to_use: 'Persist an independently authored report, not an app release.',
+    args_schema: {
+      arguments: [{ token: '[dir]', key: 'dir', description: 'Report source directory.' }],
+      options: [
+        { flags: '--database-id <id>', description: 'Required. Owning app database.' },
+        { flags: '--document-id <id>', description: 'Existing record to update or attach to.' },
+        { flags: '--attach', description: 'Attach to an existing non-view record.' },
+        { flags: '--expected-revision <revision>', description: 'Fresh view revision (0 for a record without a view).' },
+        { flags: '--title <title>', description: 'Required, including updates. Record title.' },
+        { flags: '--context-file <file>', description: 'Required. UTF-8 readable report content and structure.' },
+        { flags: '--properties-file <file>', description: 'JSON database property values keyed by name.' },
+      ],
+    },
+    examples: ['notis reports save ./weekly-report --database-id <id> --title \"Weekly review\" --context-file ./context.md'], mutates: true, idempotent: true,
+    backend_call: { type: 'tool', name: 'LOCAL_NOTIS_SAVE_REPORT' },
+    async handler(ctx) {
+      const dir = resolveProjectDir(ctx.args.dir || '.');
+      if (!ctx.options.databaseId || !ctx.options.title || !ctx.options.contextFile) throw usageError('--database-id, --title and --context-file are required.');
+      if (ctx.options.documentId && (!/^\d+$/.test(String(ctx.options.expectedRevision ?? '')) || !Number.isSafeInteger(Number(ctx.options.expectedRevision)))) throw usageError('--expected-revision is required for update/attach.');
+      if (ctx.options.attach && !ctx.options.documentId) throw usageError('--attach requires --document-id.');
+      const context = readFileSync(resolve(ctx.options.contextFile), 'utf8');
+      const properties = ctx.options.propertiesFile ? JSON.parse(readFileSync(resolve(ctx.options.propertiesFile), 'utf8')) : {};
+      await buildArtifact(dir, { stdio: ctx.output.isMachineMode() ? 'pipe' : 'inherit' });
+      const release = prepareAppRelease(dir);
+      try {
+        if (release.manifest.routes?.length !== 1) throw usageError('Reports require exactly one SDK route.');
+        let verification;
+        const verify = appsCommandSpecs.find(item => item.command_path.join(' ') === 'apps verify');
+        const exit = await verify.handler({ ...ctx, args: { dir: release.projectDir }, options: { skipBuild: true, mode: 'stub' }, output: { ...ctx.output, isMachineMode: () => true, emitSuccess: value => { verification = value; } } });
+        if (exit !== EXIT_CODES.ok || verification?.data?.status !== 'passed') throw usageError('Report verification failed; nothing saved.');
+        const files = { ...release.files, ...Object.fromEntries(Object.entries(release.sourceFiles).map(([path, data]) => [`source/${path}`, data])) };
+        const result = await runToolCommand({ runtime: { ...ctx.runtime, timeoutMs: Math.max(ctx.runtime.timeoutMs || 0, 90000) }, toolName: 'LOCAL_NOTIS_SAVE_REPORT', mutating: true,
+          idempotencyKey: nextIdempotencyKey(ctx.globalOptions), arguments_: {
+            operation: ctx.options.attach ? 'attach' : ctx.options.documentId ? 'update' : 'create',
+            database_id: ctx.options.databaseId, title: ctx.options.title, properties,
+            ...(ctx.options.documentId ? { document_id: ctx.options.documentId, expected_revision: Number(ctx.options.expectedRevision) } : {}),
+            report: { schema: 'notis-report/v2', context, artifact: { manifest: release.manifest, files, encoding: 'base64' } },
+          } });
+        if (!result?.payload?.document?.id || !result.payload.document.view_revision) throw usageError('Save returned no record identity. Read back before retrying; the outcome may be unknown.');
+        return ctx.output.emitSuccess({ command: 'reports save', data: result.payload });
+      } finally { release.close(); }
+    },
+  },
+];

package/src/runtime/skill-sync/index.ts

@@ -80,6 +80,8 @@ function withoutBaseSkillState(state: NotisSyncState): NotisSyncState {
 }
 
 export interface MaterializeCloudSkillsResult {
+  /** Cloud skills verified present in the final scoped disk scan. */
+  materializedSkillNames: string[];
   pulled: number;
   downloaded: number;
   deleted: number;
@@ -89,6 +91,8 @@ export interface MaterializeCloudSkillsResult {
 }
 
 export interface MaterializeCloudSkillsOptions {
+  /** Server-verified Notis identity, when Desktop's auth subject differs. */
+  canonicalUserId?: string;
   /** Re-link only these cloud skills without removing or adopting other links. */
   relinkSkillNames?: readonly string[];
 }
@@ -293,6 +297,7 @@ async function writePulledSkillsToScopedMirror(
     "downloadSkillBundle" | "writeCloudSkillToDisk"
   >,
   failures: SkillSyncFailure[] = [],
+  writtenSkillNames: Set<string> = new Set(),
 ): Promise<number> {
   const localSkillMap = toSkillMap(localSkills);
   const warnSkillSync = (message: string, error: unknown): void => {
@@ -314,6 +319,7 @@ async function writePulledSkillsToScopedMirror(
       })
     ) {
       downloaded += 1;
+      writtenSkillNames.add(cloudSkill.name);
     } else {
       failures.push({ name: cloudSkill.name, error: "Skill content could not be downloaded or written; sync will retry" });
     }
@@ -367,13 +373,14 @@ export async function materializeCloudSkillsForLocalShell(
     );
   }
 
-  const syncPaths = getSkillSyncPathsForUser(authUserId);
+  const syncPaths = getSkillSyncPathsForUser(options.canonicalUserId?.trim() || authUserId);
   const pullResponse = await deps.pullSkills(serverUrl, jwt);
   assertSkillsPullAuthorized(pullResponse);
   const previousState = await deps.readSyncState(syncPaths);
 
   const localSkills = await deps.scanLocalSkills(syncPaths);
   const failedDownloads: SkillSyncFailure[] = [];
+  const writtenSkillNames = new Set<string>();
   const downloaded = await writePulledSkillsToScopedMirror(
     pullResponse,
     localSkills,
@@ -381,6 +388,7 @@ export async function materializeCloudSkillsForLocalShell(
     syncPaths,
     deps,
     failedDownloads,
+    writtenSkillNames,
   );
   const finalLocalSkills = await deps.scanLocalSkills(syncPaths);
   const lastSyncedAt = pullResponse.last_synced_at || new Date().toISOString();
@@ -409,12 +417,31 @@ export async function materializeCloudSkillsForLocalShell(
   }
   for (const failure of failedDownloads) delete verifiedLinks[failure.name];
 
-  await deps.writeSyncState(
-    buildSyncState(pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks, new Set(failedDownloads.map(item => item.name))),
-    syncPaths,
+  const materializedState = buildSyncState(
+    pullResponse, finalLocalSkills, lastSyncedAt, verifiedLinks,
+    new Set(failedDownloads.map(item => item.name)),
   );
+  // Pull-only refresh is not an upload acknowledgement. Keep content baselines
+  // unless we actually wrote cloud content, and retain cloud-missing entries so
+  // the next two-way sync can delete them instead of uploading them as new.
+  for (const [name, entry] of Object.entries(materializedState.skills)) {
+    if (writtenSkillNames.has(name)) continue;
+    const previous = previousState.skills[name];
+    if (previous) {
+      entry.folderHash = previous.folderHash;
+      entry.cloudContentHash = previous.cloudContentHash;
+    } else {
+      delete materializedState.skills[name];
+    }
+  }
+  materializedState.skills = { ...previousState.skills, ...materializedState.skills };
+  await deps.writeSyncState(materializedState, syncPaths);
 
   return {
+    materializedSkillNames: pullResponse.skills
+      .filter((skill) => finalLocalSkills.some((local) => local.name === skill.name)
+        && !failedDownloads.some((failure) => failure.name === skill.name))
+      .map((skill) => skill.name),
     pulled: pullResponse.skills.length,
     downloaded,
     deleted: 0,

package/template/packages/sdk/src/agentContext.ts

@@ -0,0 +1,36 @@
+/** Serializable context shared with the agent. Apps own annotation storage. */
+export interface ContextAttachment {
+  /** Durable HTTPS URL supplied by the app. Sent through the host media pipeline. */
+  url: string;
+  name: string;
+  mimeType: string;
+}
+
+export interface AgentContextContent {
+  title?: string;
+  /** Emoji, Phosphor icon name, or HTTPS image URL. Never executable markup. */
+  icon?: string;
+  /** An app-defined kind, not a closed list of annotation types. */
+  kind?: string;
+  text?: string;
+  comment?: string;
+  preview?: { format: 'text' | 'markdown'; content: string };
+  /** Any JSON-serializable value: coordinates, chart state, loaded records, etc. */
+  data?: unknown;
+  attachments?: ContextAttachment[];
+}
+
+export interface AgentContextItem extends AgentContextContent {
+  /** Stable within this app. The host scopes IDs to the originating app. */
+  id: string;
+  resource?: import('./runtime').ContextResource | null;
+}
+
+/** Host-stamped origin. Apps describe resources; the host identifies the app/view. */
+export interface AgentContextSource {
+  appId: string;
+  appName: string;
+  viewSlug: string;
+  viewName: string;
+  viewUrl?: string | null;
+}

package/template/packages/sdk/src/components/NotisCommentBoundary.tsx

@@ -0,0 +1,172 @@
+'use client';
+import React, { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+import type { ContextResource } from '../runtime';
+import { NotisSelectionBoundary } from './NotisSelectionBoundary';
+import { useAgentContext } from '../hooks/useAgentContext';
+
+export interface NotisCommentBoxProps {
+  quote?: string;
+  value: string;
+  onChange(value: string): void;
+  onSubmit(): void;
+  onCancel(): void;
+  pending?: boolean;
+  error?: string;
+  className?: string;
+}
+
+/** Compact, chrome-themed presentation. Apps retain ownership of comment state. */
+export function NotisCommentBox({ quote, value, onChange, onSubmit, onCancel, pending, error, className = '' }: NotisCommentBoxProps) {
+  return <div data-notis-comment-ui role="dialog" aria-label="Comment on selection"
+    style={{ colorScheme: 'dark', background: 'hsl(var(--sidebar-background, 0 0% 7.5%))', color: 'hsl(var(--sidebar-foreground, 240 4.8% 95.9%))', borderColor: 'hsl(var(--sidebar-border, 0 0% 23.5%))' }}
+    className={`flex min-w-0 flex-col gap-2 rounded-xl border p-2.5 text-sm shadow-lg ${className}`}>
+    <div className="flex min-w-0 items-center gap-2">
+      {quote && <blockquote title={quote} className="min-w-0 flex-1 truncate border-l-2 border-current/40 pl-2 opacity-70">{quote}</blockquote>}
+      <button type="button" aria-label="Cancel comment" onClick={onCancel} disabled={pending} className="ml-auto flex size-7 shrink-0 items-center justify-center rounded-lg opacity-70 hover:bg-white/10 hover:opacity-100 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current disabled:opacity-40 [@media(pointer:coarse)]:size-9">
+        <svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="1.5" strokeLinecap="round"><path d="m6 6 12 12M18 6 6 18" /></svg>
+      </button>
+    </div>
+    <textarea autoFocus rows={2} name="selection-comment" aria-label="Your comment" placeholder="Add a comment…" value={value} onChange={event => onChange(event.target.value)} disabled={pending}
+      onKeyDown={event => { if (event.nativeEvent.isComposing || pending) return; if (event.key === 'Escape') { event.preventDefault(); onCancel(); } if (event.key === 'Enter' && (event.metaKey || event.ctrlKey)) { event.preventDefault(); if (value.trim()) onSubmit(); } }}
+      className="w-full min-w-0 resize-none rounded bg-transparent px-0.5 py-1 text-base text-inherit outline-none placeholder:text-current placeholder:opacity-60 sm:text-sm" />
+    {error && <p role="alert" className="text-sm text-red-300">{error}</p>}
+    <div className="flex items-center justify-between gap-3">
+      <span className="text-xs opacity-60">⌘ / Ctrl ↵ to add</span>
+      <button type="button" disabled={pending || !value.trim()} onClick={onSubmit}
+        style={{ background: 'hsl(var(--sidebar-foreground, 240 4.8% 95.9%))', color: 'hsl(var(--sidebar-background, 0 0% 7.5%))' }}
+        className="min-h-8 shrink-0 rounded-lg px-2.5 text-sm font-medium hover:opacity-90 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current disabled:opacity-40 [@media(pointer:coarse)]:min-h-9">{pending ? 'Adding…' : 'Add to chat'}</button>
+    </div>
+  </div>;
+}
+
+export interface NotisCommentBoundaryProps {
+  resource?: ContextResource | null;
+  children: ReactNode;
+  className?: string;
+  commentClassName?: string;
+  /** Replace the optional standard editor while retaining selection/context behavior. */
+  renderComment?: (props: NotisCommentBoxProps) => ReactNode;
+}
+
+type SelectionRect = Pick<DOMRect, 'left' | 'right' | 'top' | 'bottom'>;
+
+/** Place the tile after the final selected line, otherwise below (or above near the viewport bottom). */
+export function getCommentActionPosition(rects: SelectionRect[], viewport: { width: number; height: number }, rightBoundary = viewport.width, trailing: SelectionRect[] = []) {
+  const last = rects[rects.length - 1];
+  const size = 32, gap = 8;
+  const clampX = (x: number) => Math.max(gap, Math.min(viewport.width - size - gap, x));
+  const clampY = (y: number) => Math.max(gap, Math.min(viewport.height - size - gap, y));
+  const beside = { left: last.right + gap, top: clampY((last.top + last.bottom - size) / 2) };
+  const overlapsText = trailing.some(rect => rect.left < beside.left + size && rect.right > beside.left && rect.top < beside.top + size && rect.bottom > beside.top);
+  if (beside.left + size <= Math.min(viewport.width, rightBoundary) - gap && !overlapsText) return beside;
+  return { left: clampX(last.right - size), top: clampY(last.bottom + gap + size <= viewport.height - gap ? last.bottom + gap : last.top - size - gap) };
+}
+
+/** Browser paragraph selection may include an adjacent block's empty starting boundary. */
+export function getOwnedCommentRange(selected: Range, content: Element): Range | null {
+  const owned = content.ownerDocument.createRange();
+  owned.selectNodeContents(content);
+  const range = selected.cloneRange();
+  // Only clip whitespace outside the resource; actual neighboring content must
+  // never be silently attached to this resource's comment.
+  if (range.compareBoundaryPoints(Range.START_TO_START, owned) < 0) {
+    const before = range.cloneRange();
+    before.setEnd(owned.startContainer, owned.startOffset);
+    if (before.toString().trim()) return null;
+    range.setStart(owned.startContainer, owned.startOffset);
+  }
+  if (range.compareBoundaryPoints(Range.END_TO_END, owned) > 0) {
+    const after = range.cloneRange();
+    after.setStart(owned.endContainer, owned.endOffset);
+    if (after.toString().trim()) return null;
+    range.setEnd(owned.endContainer, owned.endOffset);
+  }
+  if (range.collapsed || !content.contains(range.startContainer) || !content.contains(range.endContainer)) return null;
+  return range;
+}
+
+/** Selection-to-chat convenience. No annotation database, polling or background attachment. */
+export function NotisCommentBoundary({ resource, children, className, commentClassName, renderComment }: NotisCommentBoundaryProps) {
+  const context = useAgentContext();
+  const root = useRef<HTMLDivElement>(null);
+  const [selection, setSelection] = useState<{ id: string; text: string; resource?: ContextResource | null; top: number; left: number } | null>(null);
+  const [editing, setEditing] = useState(false);
+  const editingRef = useRef(false);
+  const [comment, setComment] = useState('');
+  const [pending, setPending] = useState(false);
+  const [error, setError] = useState('');
+  useEffect(() => {
+    const node = root.current;
+    if (!node) return;
+    const document = node.ownerDocument;
+    const scope = node.getRootNode() as ShadowRoot & { getSelection?: () => Selection | null };
+    const clearInvalidSelection = () => {
+      // Opening the editor focuses its input and collapses the browser range.
+      // Keep the captured quote/editor; only the unopened action follows live selection.
+      if (editingRef.current) return;
+      const selected = scope.getSelection?.() || document.defaultView?.getSelection();
+      const content = node.firstElementChild;
+      if (!selected?.rangeCount || selected.isCollapsed || !selected.toString().trim()
+        || !content || !getOwnedCommentRange(selected.getRangeAt(0), content)) setSelection(null);
+    };
+    document.addEventListener('selectionchange', clearInvalidSelection);
+    if (scope !== (document as unknown as ShadowRoot)) scope.addEventListener('selectionchange', clearInvalidSelection);
+    return () => {
+      document.removeEventListener('selectionchange', clearInvalidSelection);
+      if (scope !== (document as unknown as ShadowRoot)) scope.removeEventListener('selectionchange', clearInvalidSelection);
+    };
+  }, []);
+  const open = () => { editingRef.current = true; setEditing(true); };
+  const capture = (target: EventTarget | null) => {
+    // Clicking the action/editor must not unmount it before its click runs.
+    if (editing || (target instanceof Element && target.closest('[data-notis-comment-ui]'))) return;
+    const node = root.current;
+    const scope = node?.getRootNode() as ShadowRoot & { getSelection?: () => Selection | null };
+    const selected = scope?.getSelection?.() || window.getSelection();
+    if (!node || !selected?.rangeCount || selected.isCollapsed) { setSelection(null); return; }
+    const content = node.firstElementChild;
+    const range = content ? getOwnedCommentRange(selected.getRangeAt(0), content) : null;
+    if (!range) { setSelection(null); return; }
+    const start = range.startContainer.nodeType === Node.ELEMENT_NODE ? range.startContainer as Element : range.startContainer.parentElement;
+    const end = range.endContainer.nodeType === Node.ELEMENT_NODE ? range.endContainer as Element : range.endContainer.parentElement;
+    if (!node.contains(range.startContainer) || !node.contains(range.endContainer)
+      || start?.closest('input,textarea,button,[contenteditable],[data-notis-comment-ui]')
+      || end?.closest('input,textarea,button,[contenteditable],[data-notis-comment-ui]')) { setSelection(null); return; }
+    const rect = range.getBoundingClientRect();
+    const lines = Array.from(range.getClientRects?.() || []).filter(line => line.width > 0 && line.height > 0);
+    const boundary = node.firstElementChild?.getBoundingClientRect();
+    const trailing: DOMRect[] = [];
+    const endBlock = end?.closest('p,li,h1,h2,h3,h4,h5,h6,td,th,div');
+    if (endBlock && node.contains(endBlock)) {
+      const remainder = range.cloneRange();
+      remainder.selectNodeContents(endBlock);
+      remainder.setStart(range.endContainer, range.endOffset);
+      trailing.push(...Array.from(remainder.getClientRects?.() || []).filter(line => line.width > 0 && line.height > 0));
+    }
+    const position = getCommentActionPosition(lines.length ? lines : [rect], { width: window.innerWidth, height: window.innerHeight }, boundary?.width ? boundary.right : window.innerWidth, trailing);
+    setSelection({ id: crypto.randomUUID(), text: selected.toString().trim(), resource: resource ? JSON.parse(JSON.stringify(resource)) : null, ...position });
+  };
+  const close = () => { editingRef.current = false; setEditing(false); setSelection(null); setComment(''); setError(''); };
+  const submit = async () => {
+    if (!selection || !comment.trim() || pending) return;
+    setPending(true); setError('');
+    try {
+      const added = await context.add({ id: selection.id, kind: 'comment', title: selection.resource?.label || 'Comment', icon: 'phosphor:chat-text', text: selection.text, comment, resource: selection.resource });
+      if (!added) throw new Error('The comment could not be added to chat.');
+      close();
+    } catch (reason) { setError(reason instanceof Error ? reason.message : 'Could not add this comment.'); }
+    finally { setPending(false); }
+  };
+  const editorProps: NotisCommentBoxProps = { quote: selection?.text, value: comment, onChange: setComment, onSubmit: () => void submit(), onCancel: close, pending, error, className: commentClassName };
+  return <div ref={root} className="contents" onMouseUp={event => capture(event.target)} onDoubleClick={event => capture(event.target)} onKeyUp={event => { if (!editing && (event.shiftKey || event.key === 'Shift' || ((event.metaKey || event.ctrlKey) && event.key.toLowerCase() === 'a'))) capture(event.target); }}>
+    <NotisSelectionBoundary resource={resource} className={className} style={className ? undefined : { display: 'contents' }}>{children}</NotisSelectionBoundary>
+    {selection && <div data-notis-comment-ui className="fixed z-50 max-h-[calc(100dvh-1rem)]" style={{ overflow: editing ? 'auto' : 'visible', top: editing ? Math.min(selection.top, Math.max(8, window.innerHeight - 320)) : selection.top, left: `clamp(8px, ${selection.left}px, calc(100vw - ${editing ? 'min(20rem, calc(100vw - 1rem))' : '2rem'} - 8px))`, width: editing ? 'min(20rem, calc(100vw - 1rem))' : undefined } as CSSProperties}>
+      {editing ? (renderComment ? renderComment(editorProps) : <NotisCommentBox {...editorProps} />) : <button type="button" aria-label="Comment" title="Comment" onMouseDown={event => event.preventDefault()} onClick={open}
+        style={{ background: 'hsl(var(--sidebar-background, 0 0% 7.5%))', color: 'hsl(var(--sidebar-foreground, 240 4.8% 95.9%))' }}
+        className="relative flex size-8 items-center justify-center rounded-lg ring-1 ring-white/15 hover:opacity-90 focus-visible:outline focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-current">
+        <svg aria-hidden="true" width="18" height="18" viewBox="0 0 256 256" fill="currentColor"><path d="M216,48H40A16,16,0,0,0,24,64V224a15.85,15.85,0,0,0,9.24,14.5A16.13,16.13,0,0,0,40,240a15.89,15.89,0,0,0,10.25-3.78l.09-.07L83,208H216a16,16,0,0,0,16-16V64A16,16,0,0,0,216,48ZM40,224h0ZM216,192H80a8,8,0,0,0-5.23,1.95L40,224V64H216ZM88,112a8,8,0,0,1,8-8h64a8,8,0,0,1,0,16H96A8,8,0,0,1,88,112Zm0,32a8,8,0,0,1,8-8h64a8,8,0,1,1,0,16H96A8,8,0,0,1,88,144Z" /></svg>
+        <span aria-hidden="true" className="absolute left-1/2 top-1/2 hidden size-12 -translate-x-1/2 -translate-y-1/2 [@media(pointer:coarse)]:block" />
+      </button>}
+    </div>}
+  </div>;
+}

package/template/packages/sdk/src/components/NotisSelectionBoundary.tsx

@@ -1,5 +1,5 @@
 import type { CSSProperties, ClipboardEvent, ReactNode } from 'react';
-import { useCallback } from 'react';
+import React, { useCallback } from 'react';
 import { useNotisRuntime } from '../provider';
 import type { ContextResource, ContextSelection } from '../runtime';
 
@@ -31,10 +31,13 @@ export function NotisSelectionBoundary({
 }: NotisSelectionBoundaryProps) {
   const runtime = useNotisRuntime();
   const onCopy = useCallback((event: ClipboardEvent<HTMLDivElement>) => {
-    const selection = window.getSelection();
-    const text = selection?.toString().trim() ?? '';
+    const target = event.target as Element | null;
+    if (target?.closest?.('input,textarea,[contenteditable="true"]')) return;
+    const scope = event.currentTarget.getRootNode() as ShadowRoot & { getSelection?: () => Selection | null };
+    const selection = scope?.getSelection?.() || window.getSelection();
+    const text = selection?.toString() ?? '';
     if (
-      !text
+      !text.trim()
       || !selection
       || !event.currentTarget.contains(selection.anchorNode)
       || !event.currentTarget.contains(selection.focusNode)
@@ -42,7 +45,8 @@ export function NotisSelectionBoundary({
 
     const payload: ContextSelection = {
       id: selectionId(),
-      text: text.slice(0, 12_000),
+      text,
+      ...(runtime?.contextSource ? { source: runtime.contextSource } : {}),
       ...(resource ? { resource: { ...resource, snapshot: undefined } } : {}),
     };
     event.clipboardData.setData('text/plain', text);

package/template/packages/sdk/src/hooks/useAgentContext.ts

@@ -0,0 +1,23 @@
+'use client';
+import { useMemo } from 'react';
+import { useNotisRuntime } from '../provider';
+import type { AgentContextItem } from '../agentContext';
+
+/** Share context without owning storage, opening a new thread, or sending a message. */
+export function useAgentContext() {
+  const runtime = useNotisRuntime();
+  return useMemo(() => ({
+    add(item: AgentContextItem): Promise<boolean> {
+      if (!runtime?.addContext) return Promise.reject(new Error('Chat context is unavailable in this host.'));
+      return runtime.addContext(item);
+    },
+    update(item: AgentContextItem): Promise<boolean> {
+      if (!runtime?.updateContext) return Promise.reject(new Error('Chat context is unavailable in this host.'));
+      return runtime.updateContext(item);
+    },
+    remove(id: string): Promise<boolean> {
+      if (!runtime?.removeContext) return Promise.reject(new Error('Chat context is unavailable in this host.'));
+      return runtime.removeContext(id);
+    },
+  }), [runtime]);
+}

package/template/packages/sdk/src/index.ts

@@ -154,3 +154,8 @@ export { Skeleton, ViewSkeleton } from './components/Skeleton';
 
 export { useLongPressSelection } from './hooks/useLongPressSelection';
 export { isInteractionElementVisible } from './interactions/visibility';
+
+export type { AgentContextContent, AgentContextItem, ContextAttachment } from './agentContext';
+export { useAgentContext } from './hooks/useAgentContext';
+export { NotisCommentBoundary, NotisCommentBox } from './components/NotisCommentBoundary';
+export type { NotisCommentBoundaryProps, NotisCommentBoxProps } from './components/NotisCommentBoundary';