@notis_ai/cli 0.2.17 → 0.2.19

package/src/runtime/skill-sync/symlink-manager.ts

@@ -8,7 +8,7 @@ import {
   NOTIS_SKILL_SYNC_ROOT,
   safeName,
 } from './local-scanner';
-import { normalizeAgentTargets, type CloudSkill, type NotisSyncState } from './types';
+import { normalizeAgentTargets, type AgentTargets, type SkillSyncFailure, type CloudSkill, type NotisSyncState } from './types';
 
 const HOME_DIR = os.homedir();
 
@@ -22,6 +22,22 @@ type ExternalAgent = keyof typeof EXTERNAL_AGENT_SKILL_DIRS;
 
 const EXTERNAL_AGENTS = Object.keys(EXTERNAL_AGENT_SKILL_DIRS) as ExternalAgent[];
 
+const AGENT_FAILURE_LABELS: Record<string, string> = {
+  claude_code: 'Claude Code',
+  cursor: 'Cursor',
+  codex: 'Codex',
+  legacy: 'legacy ~/.agents/skills',
+};
+
+/** Failures are shown next to skill names in the Portal and CLI; never leak raw agent ids. */
+function agentFailureLabel(agent: string): string {
+  return AGENT_FAILURE_LABELS[agent] ?? agent;
+}
+
+function agentFolderFailureName(agent: string): string {
+  return `${agentFailureLabel(agent)} skills folder`;
+}
+
 export interface DeletedAgentSymlink {
   skillId: string;
   skillName: string;
@@ -46,6 +62,8 @@ export interface SymlinkSyncResult {
   linked: number;
   removed: number;
   skipped: number;
+  verifiedAgentLinks?: Record<string, Partial<AgentTargets>>;
+  failures?: SkillSyncFailure[];
 }
 
 /** Remove only links into another account's managed mirror. This is safe even
@@ -128,8 +146,9 @@ async function isManagedSymlink(linkPath: string, managedRoots: string[]): Promi
     return managedRoots.some((root) => (
       resolvedTarget === root || resolvedTarget.startsWith(`${root}${path.sep}`)
     ));
-  } catch {
-    return false;
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return false;
+    throw error;
   }
 }
 
@@ -146,8 +165,8 @@ async function ensureCorrectSymlink(linkPath: string, targetPath: string): Promi
     } else {
       return 'blocked';
     }
-  } catch {
-    // Missing path is expected.
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') throw error;
   }
 
   const relativePath = path.relative(path.dirname(linkPath), targetPath);
@@ -166,6 +185,8 @@ async function removeUndesiredManagedSymlinks(
   agentDir: string,
   desiredSkills: Set<string>,
   managedRoots: string[],
+  failures: SkillSyncFailure[],
+  agent: string,
 ): Promise<number> {
   let removed = 0;
   try {
@@ -173,13 +194,19 @@ async function removeUndesiredManagedSymlinks(
     const existingEntries = await fs.readdir(agentDir, { withFileTypes: true });
     for (const entry of existingEntries) {
       const entryPath = path.join(agentDir, entry.name);
-      if (!desiredSkills.has(entry.name) && await isManagedSymlink(entryPath, managedRoots)) {
-        await fs.unlink(entryPath);
-        removed += 1;
+      try {
+        if (!desiredSkills.has(entry.name) && await isManagedSymlink(entryPath, managedRoots)) {
+          await fs.unlink(entryPath);
+          removed += 1;
+        }
+      } catch (error) {
+        if ((error as NodeJS.ErrnoException)?.code !== 'ENOENT') {
+          failures.push({ name: entry.name, error: `${agentFailureLabel(agent)}: could not remove skill link (${(error as Error).message})` });
+        }
       }
     }
-  } catch {
-    // Missing or unreadable agent directories should not block skill sync.
+  } catch (error) {
+    failures.push({ name: agentFolderFailureName(agent), error: `Could not read agent skills directory (${(error as Error).message})` });
   }
   return removed;
 }
@@ -255,7 +282,9 @@ export async function detectDeletedAgentSymlinks(
         continue;
       }
       const previous = previousState.skills[skill.name];
-      if (!previous) {
+      if (!previous || previous.cloudId !== skill.id
+        || previous.verifiedAgentLinks?.[agent] !== true
+        || !skill.updated_at || previous.cloudUpdatedAt !== skill.updated_at) {
         continue;
       }
 
@@ -293,10 +322,12 @@ export async function syncSymlinks(
 ): Promise<SymlinkSyncResult> {
   await fs.mkdir(skillsDir, { recursive: true });
 
-  const result: SymlinkSyncResult = {
+  const result: Required<SymlinkSyncResult> = {
     linked: 0,
     removed: 0,
     skipped: 0,
+    verifiedAgentLinks: {},
+    failures: [],
   };
   const agentSkillDirs = { ...defaultAgentSkillDirs(skillsDir), ...options.agentSkillDirs };
   const legacyGlobalSkillsDir = options.legacyGlobalSkillsDir || LEGACY_AGENTS_SKILLS_DIR;
@@ -336,23 +367,36 @@ export async function syncSymlinks(
       continue;
     }
 
-    await fs.mkdir(agentDir, { recursive: true });
+    try {
+      await fs.mkdir(agentDir, { recursive: true });
+    } catch (error) {
+      result.failures.push({ name: agentFolderFailureName(agent), error: `Could not create agent skills directory (${(error as Error).message})` });
+      continue;
+    }
 
     const desiredSkills = desiredByAgent[agent];
     if (options.removeUndesired !== false) {
-      result.removed += await removeUndesiredManagedSymlinks(agentDir, desiredSkills, managedRoots);
+      result.removed += await removeUndesiredManagedSymlinks(agentDir, desiredSkills, managedRoots, result.failures, agent);
     }
 
     for (const skillName of desiredSkills) {
       const targetPath = path.join(skillsDir, skillName);
       const linkPath = path.join(agentDir, safeName(skillName, agentDir));
       try {
-        await fs.access(targetPath);
+        if (!(await fs.stat(path.join(targetPath, "SKILL.md"))).isFile()) throw new Error("Missing SKILL.md");
       } catch {
         result.skipped += 1;
+        result.failures.push({ name: skillName, error: `${agentFailureLabel(agent)}: SKILL.md is missing or unreadable` });
+        continue;
+      }
+      let syncOutcome;
+      try {
+        syncOutcome = await ensureCorrectSymlink(linkPath, targetPath);
+      } catch (error) {
+        result.skipped += 1;
+        result.failures.push({ name: skillName, error: `${agentFailureLabel(agent)}: could not create skill link (${(error as Error).message})` });
         continue;
       }
-      const syncOutcome = await ensureCorrectSymlink(linkPath, targetPath);
       if (syncOutcome === 'linked') {
         result.linked += 1;
       } else if (syncOutcome === 'blocked') {
@@ -360,9 +404,13 @@ export async function syncSymlinks(
           `[skill-sync] Could not link "${skillName}" for ${agent}: non-symlink entry blocks ${linkPath}`,
         );
         result.skipped += 1;
+        result.failures.push({ name: skillName, error: `${agentFailureLabel(agent)}: an existing file or folder blocks the skill link` });
       } else {
         result.skipped += 1;
       }
+      if (syncOutcome !== "blocked") {
+        result.verifiedAgentLinks[skillName] = { ...result.verifiedAgentLinks[skillName], [agent]: true };
+      }
     }
   }
 
@@ -376,6 +424,8 @@ export async function syncSymlinks(
       legacyGlobalSkillsDir,
       new Set(),
       managedRoots,
+      result.failures,
+      'legacy',
     );
   }
 

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

@@ -1,22 +1,54 @@
-import type { LocalSkill, NotisSyncState } from "./types";
+import type { CloudSkill, LocalSkill, NotisSyncState } from "./types";
+import { isNativeSkill } from './native-identity';
+import { hasNativeFolderHistory } from './native-plan';
+
+/**
+ * One cloud row per local folder. Several active rows can carry the same skill name
+ * (duplicates created by earlier pushes), and every one of them writes to the same
+ * directory. Applying them all in
+ * one pass replaced that directory several times per sync and left whichever row came
+ * last on disk. The newest revision wins, deterministically.
+ */
+export function selectCloudSkillsToApply(skills: CloudSkill[]): CloudSkill[] {
+  const winners = new Map<string, CloudSkill>();
+  for (const skill of skills) {
+    const current = winners.get(skill.name);
+    if (!current || (skill.updated_at || "") >= (current.updated_at || "")) {
+      winners.set(skill.name, skill);
+    }
+  }
+  return [...winners.values()];
+}
 
 export function getPushCandidates(
   localSkills: LocalSkill[],
   syncState: NotisSyncState,
   cloudCuratedSkillNames: ReadonlySet<string> = new Set(),
   cloudSkillNames?: ReadonlySet<string>,
+  cloudSkills: CloudSkill[] = [],
 ): LocalSkill[] {
   return localSkills.filter((skill) => {
     if (cloudCuratedSkillNames.has(skill.name)) {
       return false;
     }
-    const previous = syncState.skills[skill.name];
+    const previous = syncState.skills[skill.name]
+      || (skill.cloudId ? Object.values(syncState.skills).find(row => row.cloudId === skill.cloudId) : undefined);
+    const native = cloudSkills.find(row => isNativeSkill(row) && row.id === (skill.cloudId || previous?.cloudId));
+    if (native || skill.nativeReference || previous?.nativeReference || previous?.nativeUnavailable) {
+      return Boolean(native && skill.nativeReference && skill.nativeScope === native.native_scope
+        && (previous ? previous.folderHash !== skill.folderHash : skill.nativeBaseFolderHash !== skill.folderHash));
+    }
     if (!previous) {
+      if (hasNativeFolderHistory(syncState, skill.name) || /^native-[a-f0-9-]{36}$/.test(skill.name)) return false;
       return true;
     }
     if (cloudSkillNames && !cloudSkillNames.has(skill.name)) {
       return false;
     }
     return previous.folderHash !== skill.folderHash;
+  }).map(skill => {
+    const previous = syncState.skills[skill.name]
+      || Object.values(syncState.skills).find(row => row.cloudId === skill.cloudId);
+    return { ...skill, ...(skill.cloudId || previous?.cloudId ? { cloudId: skill.cloudId || previous!.cloudId } : {}) };
   });
 }

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

@@ -5,10 +5,37 @@ export interface AgentTargets {
   codex: boolean;
 }
 
+export interface NativeSkillReference {
+  kind: 'native_standalone_skill';
+  skill_id: string;
+  access_revision: number;
+  version: { revision: number; digest: string };
+}
+
 export interface SyncedSkill {
   cloudId: string;
+  nativeReference?: NativeSkillReference;
+  nativeDisplayName?: string;
+  nativeScope?: string;
+  nativeSettingsRevision?: number;
+  /** Retain managed provenance even when its cloud access is removed. */
+  nativeUnavailable?: boolean;
   folderHash: string;
   agentTargets: AgentTargets;
+  /** Actual readable managed links, never inferred from desired targets. */
+  verifiedAgentLinks?: Partial<AgentTargets>;
+  cloudUpdatedAt?: string;
+  /** Content accepted on disk; independent of server-specific folder hash formats. */
+  cloudContentHash?: string;
+  /** Relative paths the last successful write put in this folder. Anything else in
+   * the folder was created locally (a running skill's output) and survives the next
+   * cloud write; anything listed here that the cloud later drops is deleted. */
+  appliedFiles?: string[];
+  /** `skill_folder_hash` of the cloud revision a successful write actually applied.
+   * The server may compute that hash with a different construction than the local
+   * folder hash (bundle-entry hashes do), so only cloud-to-cloud comparison tells
+   * "the cloud moved" apart from "the two sides hash differently". */
+  appliedCloudFolderHash?: string;
   syncedAt: string;
 }
 
@@ -16,6 +43,15 @@ export interface NotisSyncState {
   version: 1;
   lastSyncedAt: string | null;
   skills: Record<string, SyncedSkill>;
+  /** Historical folder aliases are provenance, never authority or write pins. */
+  nativeHistory?: Record<string, { names: string[] }>;
+}
+
+/** A successful write, plus the paths it put on disk so the next one can tell
+ * cloud-managed files apart from whatever ran inside the folder since. */
+export interface SkillWriteOutcome {
+  written: true;
+  appliedFiles: string[];
 }
 
 export interface LocalSkill {
@@ -26,6 +62,12 @@ export interface LocalSkill {
   directoryPath: string;
   sourceUrl?: string;
   bundleFiles?: BundleFile[];
+  cloudId?: string;
+  nativeReference?: NativeSkillReference;
+  displayName?: string;
+  nativeScope?: string;
+  nativeFilesCurrent?: boolean;
+  nativeBaseFolderHash?: string;
 }
 
 export interface BundleFile {
@@ -34,6 +76,7 @@ export interface BundleFile {
 }
 
 export interface CloudSkill {
+  updated_at?: string;
   id: string;
   name: string;
   description: string | null;
@@ -45,9 +88,17 @@ export interface CloudSkill {
   bundle_hydration_failed?: boolean | null;
   source: string;
   status: string;
+  native_reference?: NativeSkillReference;
+  display_name?: string;
+  native_scope?: string;
+  native_settings?: { revision: number; enabled: boolean; agent_targets: AgentTargets; updated_at: string };
 }
 
 export interface SyncSettings {
+  skill_sync_protocol?: number;
+  sync_scope?: string;
+  sync_namespace?: string | null;
+  agent_targets_conditional_updates?: boolean;
   /** Server-verified canonical Notis account id used to scope local mirrors. */
   user_id?: string;
   sync_enabled: boolean;
@@ -66,6 +117,9 @@ export interface EntitlementAccessDetail {
 }
 
 export interface SyncPullResponse {
+  skill_sync_protocol?: number;
+  sync_scope?: string;
+  sync_namespace?: string | null;
   skills: CloudSkill[];
   sync_enabled: boolean;
   last_synced_at: string | null;

package/src/runtime/skill-sync/write-cloud-skill.ts

@@ -1,21 +1,21 @@
-import type { CloudSkill } from './types';
+import type { CloudSkill, SkillWriteOutcome } from './types';
 
 interface WriteCloudSkillDependencies {
   downloadSkillBundle: (bundleUrl: string) => Promise<Buffer>;
-  writeCloudSkillToDisk: (skill: CloudSkill, bundleBytes?: Buffer) => Promise<boolean>;
+  writeCloudSkillToDisk: (skill: CloudSkill, bundleBytes?: Buffer) => Promise<SkillWriteOutcome | boolean>;
   onWarning?: (message: string, error: unknown) => void;
 }
 
 export async function writeCloudSkillWithBundleFallback(
   skill: CloudSkill,
   dependencies: WriteCloudSkillDependencies,
-): Promise<boolean> {
+): Promise<SkillWriteOutcome | boolean> {
   if (skill.skill_source_url) {
     try {
       const bundleBytes = await dependencies.downloadSkillBundle(skill.skill_source_url);
       const wroteBundleToDisk = await dependencies.writeCloudSkillToDisk(skill, bundleBytes);
       if (wroteBundleToDisk) {
-        return true;
+        return wroteBundleToDisk;
       }
 
       dependencies.onWarning?.(

package/src/runtime/skill-sync-service.js

@@ -0,0 +1,109 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { isValidProfileName, loadConfig } from './profiles.js';
+import { withSkillSyncLock } from './sync-skills.js';
+
+export const SKILL_SYNC_SERVICE_LABEL = 'ai.notis.skills-sync';
+const bundlePath = fileURLToPath(new URL('../../dist/skill-sync-worker.mjs', import.meta.url));
+
+function atomicWrite(target, value, mode = 0o600) {
+  mkdirSync(dirname(target), { recursive: true, mode: 0o700 });
+  const temporary = `${target}.${process.pid}.tmp`;
+  writeFileSync(temporary, value, { mode });
+  renameSync(temporary, target);
+}
+
+function xml(value) {
+  return String(value).replaceAll('&', '&amp;').replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;').replaceAll('"', '&quot;').replaceAll("'", '&apos;');
+}
+
+export async function maybeInstallSkillSyncService(runtime, {
+  config = loadConfig(), install = installSkillSyncService,
+  fetchSettings, refresh,
+} = {}) {
+  if (process.platform !== 'darwin' || runtime.credentialKind !== 'oauth'
+    || config.current_profile !== runtime.profileName
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) return;
+  // Ordinary commands must not steal another explicitly bound account's job.
+  const plist = join(homedir(), 'Library', 'LaunchAgents', `${SKILL_SYNC_SERVICE_LABEL}.plist`);
+  if (existsSync(plist)) {
+    const saved = readFileSync(plist, 'utf8');
+    if (runtime.oauthUserId && [runtime.profileName, runtime.apiBase, runtime.oauthUserId]
+      .every(value => saved.includes(`<string>${xml(value)}</string>`))) return install(runtime);
+    return;
+  }
+  const refreshCredential = refresh || (await import('./oauth.js')).ensureFreshOAuthCredential;
+  await refreshCredential(runtime);
+  const getSettings = fetchSettings || (await import('../../dist/skill-sync/index.js')).fetchSyncSettings;
+  const settings = await getSettings(runtime.apiBase, runtime.jwt);
+  if (settings.sync_enabled && settings.user_id === runtime.oauthUserId) return install(runtime);
+}
+
+export async function installSkillSyncService(runtime, options = {}) {
+  if ((options.platform || process.platform) !== 'darwin') return { status: 'unsupported_platform' };
+  if (runtime.credentialKind !== 'oauth' || !runtime.oauthUserId
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) {
+    return { status: 'skipped_non_personal_profile' };
+  }
+  // Registration upgrades must not kill a worker holding the filesystem lock,
+  // nor race another CLI registering the same LaunchAgent.
+  return withSkillSyncLock(() => installSkillSyncServiceLocked(runtime, options),
+    options.home ? { home: options.home } : {});
+}
+
+async function installSkillSyncServiceLocked(runtime, {
+  home = homedir(), platform = process.platform, nodePath = process.execPath,
+  source = bundlePath, run = spawnSync, uid = process.getuid?.(),
+} = {}) {
+  // A single explicitly selected personal account owns global agent folders.
+  // Development and hosted credentials must never enroll a machine-wide job.
+  if (platform !== 'darwin') return { status: 'unsupported_platform' };
+  if (runtime.credentialKind !== 'oauth' || runtime.envCredentialOverride
+    || !isValidProfileName(runtime.profileName)
+    || !['https://api.notis.ai', 'https://api-beta.notis.ai'].includes(runtime.apiBase)) {
+    return { status: 'skipped_non_personal_profile' };
+  }
+  const root = join(home, '.notis', 'skills', 'service');
+  const bundle = readFileSync(source);
+  const digest = createHash('sha256').update(bundle).digest('hex');
+  const installedBundle = join(root, 'runtime', digest, 'worker.mjs');
+  if (!existsSync(installedBundle)
+    || !readFileSync(installedBundle).equals(bundle)) atomicWrite(installedBundle, bundle, 0o500);
+  const args = [nodePath, installedBundle, runtime.profileName, runtime.apiBase, runtime.oauthUserId];
+  if (!runtime.oauthUserId) return { status: 'skipped_missing_account' };
+  const plist = `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+<key>Label</key><string>${SKILL_SYNC_SERVICE_LABEL}</string>
+<key>ProgramArguments</key><array>${args.map(value => `<string>${xml(value)}</string>`).join('')}</array>
+<key>WorkingDirectory</key><string>${xml(root)}</string>
+<key>StartInterval</key><integer>60</integer>
+<key>ProcessType</key><string>Background</string>
+</dict></plist>
+`;
+  const plistPath = join(home, 'Library', 'LaunchAgents', `${SKILL_SYNC_SERVICE_LABEL}.plist`);
+  const domain = `gui/${uid}`;
+  const target = `${domain}/${SKILL_SYNC_SERVICE_LABEL}`;
+  const unchanged = existsSync(plistPath) && readFileSync(plistPath, 'utf8') === plist;
+  const loaded = run('/bin/launchctl', ['print', target], { encoding: 'utf8', timeout: 5000 });
+  if (unchanged && loaded.status === 0) return { status: 'installed', intervalSeconds: 60, profile: runtime.profileName };
+  if (loaded.status === 0) {
+    const stopped = run('/bin/launchctl', ['bootout', target], { encoding: 'utf8', timeout: 5000 });
+    if (stopped.status !== 0) throw new Error('Could not update the existing automatic skill sync job');
+  }
+  atomicWrite(plistPath, plist);
+  let started;
+  // launchd may finish tearing down an old registration after bootout returns.
+  for (let attempt = 0; attempt < 10; attempt++) {
+    started = run('/bin/launchctl', ['bootstrap', domain, plistPath], { encoding: 'utf8', timeout: 5000 });
+    if (started.status === 0) break;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  if (started?.status !== 0) throw new Error('Could not register automatic skill sync with macOS');
+  return { status: 'installed', intervalSeconds: 60, profile: runtime.profileName };
+}

package/src/runtime/source-root.js

@@ -0,0 +1,32 @@
+/**
+ * Commands that write inside a source folder first prove the folder is one.
+ *
+ * 2026-10-02: `notis spaces build .` run from the Notis repository root treated
+ * the repository as a Space source, refreshed "its" embedded SDK and deleted the
+ * canonical packages/sdk/src/presentation.tsx. A source folder is identified by
+ * a marker at its root, checked before any file is read for writing, staged,
+ * refreshed or deleted.
+ */
+import { statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+import { usageError } from './errors.js';
+
+// The workspace Space index (also a legacy App's config) or a pulled Space's lock.
+export const SOURCE_ROOT_MARKERS = Object.freeze(['notis.config.ts', 'notis.config.js', 'notis.config.mjs', '.notis/space-lock.json']);
+
+export function isSourceRoot(directory) {
+  return SOURCE_ROOT_MARKERS.some((name) => {
+    try { return statSync(join(directory, name)).isFile(); } catch { return false; }
+  });
+}
+
+/** Return the resolved folder, or refuse before anything inside it is touched. */
+export function assertSourceRoot(directory) {
+  const root = resolve(directory);
+  if (!isSourceRoot(root)) {
+    throw usageError(`${root} is not a Space source: it has no notis.config.ts (or .js, .mjs) and no .notis/space-lock.json `
+      + 'at its root, so nothing was changed. Run the command in a Space source folder, or pass that folder.');
+  }
+  return root;
+}

package/src/runtime/space-collection-scaffold.js

@@ -0,0 +1,107 @@
+import { writeFileSync, mkdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { scaffoldProject, syncSpaceSdk } from './app-platform.js';
+import { validateViewPath } from './space-view-manifest.js';
+import { usageError } from './errors.js';
+
+/** A local, editable collection layout. No remote database or Space mutation. */
+export async function scaffoldSpaceCollection({ projectDir, name, databaseKey, path = 'records', titleProperty = 'title' }) {
+  if (typeof databaseKey !== 'string' || !/^[a-z][a-z0-9_-]{0,99}$/.test(databaseKey)) throw usageError('Pass the linked database alias as --database-key: start with a lowercase letter, then use lowercase letters, digits, underscores or hyphens (up to 100 characters).');
+  if (typeof name !== 'string' || !name.trim() || typeof titleProperty !== 'string' || !titleProperty.trim()) throw usageError('Choose a Space name and title property.');
+  validateViewPath(path);
+  await scaffoldProject({ projectDir, appName: name });
+  // A Space installs only the SDK's types and build-time entries; the host provides the rest.
+  syncSpaceSdk(projectDir, { log: () => {} });
+  mkdirSync(join(projectDir, 'spaces', 'collection'), { recursive: true });
+  writeFileSync(join(projectDir, 'notis.config.ts'), `import { defineSpaces } from '@notis/sdk/config';
+export default defineSpaces({ spaces: { collection: { definition: 'spaces/collection/space.config.ts' } } });\n`);
+  const definition = { specVersion: 2, name, description: `Browse and edit ${name} records.`, path, entry: './view.tsx', layout: '../../app/layout.tsx',
+    readableContext: `Browse ${name} records. The item parameter opens one record with its properties, collaborative body and sharing controls.`,
+    verificationFixtures: './verification.json',
+    resources: { [databaseKey]: { kind: 'database', key: databaseKey } },
+    collection: { database: databaseKey, titleProperty },
+    params: { item: { type: 'record', database: databaseKey, main: true, description: 'The record opened beside the list.' } },
+    shows: { items: { database: databaseKey, where: {}, open: 'item' } },
+    memory: { markdown: true, attachments: true, screenshot: false, snapshots: [] },
+    // Each action is the linked database's own query, insert or trash: Notis turns it into the binding operation
+    // that useNativeMutation calls, so the view never names an account-wide database.
+    actions: { read: rowAction('LOCAL_NOTIS_DATABASE_QUERY', databaseKey), create: rowAction('LOCAL_NOTIS_DATABASE_INSERT', databaseKey),
+      delete: rowAction('LOCAL_NOTIS_DATABASE_DELETE', databaseKey) },
+  };
+  writeFileSync(join(projectDir, 'spaces/collection/space.config.ts'), `import { defineSpace } from '@notis/sdk/config';\nexport default defineSpace(${JSON.stringify(definition, null, 2)});\n`);
+  writeFileSync(join(projectDir, 'spaces/collection/view.tsx'), collectionView(databaseKey));
+  writeFileSync(join(projectDir, 'spaces/collection/verification.json'), JSON.stringify({
+    actions: {}, shown: { items: [{ params: {}, result: { rows: [], has_more: false, schema_revision: 1 } }] },
+  }, null, 2) + '\n');
+  return { projectDir, key: 'collection', databaseKey };
+}
+
+/** One declared action over the linked database: the tool gets the binding and the view's request, nothing else. */
+function rowAction(tool, databaseKey) {
+  return { tool, inputs: { type: 'object', additionalProperties: false, required: ['request'], properties: { request: { type: 'object' } } },
+    arguments: { database_id: { $asset: databaseKey }, request: { $input: 'request' } } };
+}
+
+/**
+ * The scaffolded view: one ListReader over the linked records, with the host top bar search, an All pill, a "+" that
+ * creates and opens a record, and the record's document page in the reader. The title lives in the host top bar.
+ */
+function collectionView(databaseKey) {
+  return `'use client';
+import { useRef } from 'react';
+import { DocumentPage, useNativeMutation, useShown, useViewParams } from '@notis/sdk';
+import { EmptyState, ListReader, Notice, Row, type ListReaderApi } from '@notis/sdk/ui';
+import definition from './space.config';
+
+type Item = { record_key: string; revision: number; title: string | null; last_edited_time: string | null };
+
+/** The view's words. Spaces are English only; the toolkit's own words follow the Notis language. */
+const t = { list: 'Records', search: 'Search records…', all: 'All', create: 'New record', untitled: 'Untitled',
+  empty: 'No records yet.', remove: 'Delete', failed: 'Could not create the record. Try again.' };
+
+export default function CollectionView() {
+  const { setParams } = useViewParams<typeof definition>();
+  const { data, loading, error, refetch } = useShown<Item>('items', { allPages: true });
+  const insert = useNativeMutation(${JSON.stringify(databaseKey)}, 'insert');
+  const trash = useNativeMutation(${JSON.stringify(databaseKey)}, 'delete');
+  const list = useRef<ListReaderApi>(null);
+  const rows = data?.rows ?? [];
+  const write = () => ({ schemaRevision: data?.schema_revision ?? 0, requestId: crypto.randomUUID() });
+  const title = (record: Item) => record.title || t.untitled;
+
+  async function create() {
+    try {
+      const receipt = await insert.mutate({}, write());
+      await refetch();
+      await setParams({ item: receipt.record_key });
+    } catch {
+      list.current?.notify(t.failed);
+    }
+  }
+
+  async function remove(records: Item[]) {
+    for (const record of records) {
+      await trash.mutate({ record_key: record.record_key, expected_revision: record.revision }, write());
+    }
+    await refetch();
+  }
+
+  // The host top bar shows the Space and view name; the open record joins it as the last crumb.
+  return <ListReader apiRef={list} label={t.list} items={rows} getId={record => record.record_key} openParam="item"
+    loading={loading}
+    search={{ placeholder: t.search, match: (record, query) => title(record).toLocaleLowerCase().includes(query.toLocaleLowerCase()) }}
+    // One real view so far; add a pill per saved filter once the database has one.
+    tabs={{ role: 'filter', items: [{ id: 'all', label: t.all, count: rows.length }], value: 'all', onChange: () => undefined }}
+    create={{ label: t.create, onCreate: () => void create() }}
+    actions={[{ id: 'delete', run: remove }]}
+    empty={error ? <Notice tone="danger" onRetry={() => void refetch()}>{error.message}</Notice> : <EmptyState title={t.empty} />}
+    row={record => <Row title={title(record)} time={record.last_edited_time ?? undefined} />}
+    readerLabel={title}
+    crumbLabel={title}
+    readerActions={(_record, ctx) => [{ id: 'delete', label: t.remove, icon: 'trash', run: () => void ctx.run('delete') }]}
+    reader={record => <DocumentPage key={record.record_key} recordKey={record.record_key} onSaved={refetch} />} />;
+}
+`;
+}
+
+export const COLLECTION_VIEW = collectionView('items');