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

package/skills/notis-onboarding/BRIEF.md

@@ -94,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
 

package/src/command-specs/apps.js

@@ -1257,22 +1257,15 @@ async function appsDeployHandler(ctx) {
     try { release.close(); }
     catch { warnings.push('The app was updated, but the temporary release directory needs local cleanup.'); }
 
-    // One review report per skill this release changed; share the link when the user should review it.
-    const skillReviews = (Array.isArray(result.payload.skill_reviews) ? result.payload.skill_reviews : [])
-      .filter((review) => review && typeof review.review_url === 'string');
     return ctx.output.emitSuccess({
       command: ctx.spec.command_path.join(' '),
       data: {
         app_id: appId,
         version: deployedVersion,
         idempotency_key: idempotencyKey,
-        ...(skillReviews.length ? { skill_reviews: skillReviews } : {}),
       },
       warnings,
-      humanSummary: [
-        `Deployed to app ${appId} (version ${deployedVersion})`,
-        ...skillReviews.map((review) => `Review ${review.skill} changes: ${review.review_url}`),
-      ].join('\n'),
+      humanSummary: `Deployed to app ${appId} (version ${deployedVersion})`,
       meta: { mutating: true, idempotency_key: idempotencyKey },
     });
   } finally {

package/src/command-specs/files.js

@@ -0,0 +1,29 @@
+import { uploadNativeRecordFileWithCliRuntime } from '../runtime/native-record-files.js';
+import { parseJson } from './helpers.js';
+import { usageError } from '../runtime/errors.js';
+
+export const filesCommandSpecs = [{
+  command_path: ['files', 'upload'],
+  summary: 'Upload a local file for one native record you can edit.',
+  when_to_use: 'Save file bytes without a cloud computer; attach the returned file reference through a normal revision-checked row update.',
+  args_schema: { arguments: [{ token: '<file>', key: 'file', description: 'Local regular file up to 8 MB.' }], options: [
+    { flags: '--target <json>', description: 'Exact native target returned by schema discovery.' },
+    { flags: '--record-key <id>', description: 'Stable record key to attach this file to.' },
+    { flags: '--schema-revision <number>', description: 'Current native schema revision.' },
+    { flags: '--request-id <uuid>', description: 'Stable UUID; reuse with identical bytes after an uncertain response.' },
+    { flags: '--name <name>', description: 'Attachment name; defaults to the local basename.' },
+    { flags: '--content-type <mime>', description: 'File MIME type; inferred from known extensions.' },
+  ] },
+  examples: ['notis files upload ./report.html --target \'{"database_id":"<database-id>"}\' --record-key <record-key> --schema-revision 1 --request-id <uuid>'],
+  mutates: true, idempotent: true, require_auth: true,
+  backend_call: { type: 'http', path: '/portal_native_files/upload' },
+  async handler(ctx) {
+    if (!ctx.options.target || ctx.options.schemaRevision === undefined) throw usageError('Pass the discovered native --target and --schema-revision.');
+    const result = await uploadNativeRecordFileWithCliRuntime({ runtime: ctx.runtime, filePath: ctx.args.file,
+      target: parseJson(ctx.options.target, '--target'), recordKey: ctx.options.recordKey,
+      schemaRevision: Number(ctx.options.schemaRevision), requestId: ctx.options.requestId,
+      ...(ctx.options.name ? { name: ctx.options.name } : {}), ...(ctx.options.contentType ? { contentType: ctx.options.contentType } : {}) });
+    return ctx.output.emitSuccess({ command: 'files upload', data: result,
+      humanSummary: 'Uploaded and verified the file. Attach the returned file reference with a revision-checked record update.', meta: { mutating: true } });
+  },
+}];

package/src/command-specs/handover.js

@@ -2,9 +2,10 @@
  * `notis handover` -- give the branch you are on to a Notis agent.
  *
  * The coding agent already sitting in the user's terminal is the caller here.
- * It pushes the branch, then hands the task to whichever agent the user picked:
- * the hosted Notis agent, or their own Codex/Claude Code running in the Notis
- * cloud sandbox or on their Mac.
+ * It pushes the branch, then hands the task to Notis. By default (`auto`) Notis
+ * picks the agent itself; `--route notis|codex|claude` names one instead, and
+ * the server turns that into a plain sentence in the task ("Use Codex for this
+ * task."), so the user's choice wins like it does in a chat message.
  *
  * The CLI deliberately does not create the cloud workspace itself. Doing so
  * would hard-code the Conductor app's database schema and script paths into the
@@ -28,7 +29,18 @@ import { fetchToolSchema, nextIdempotencyKey, runToolCommand } from './helpers.j
 const HAND_OVER_TOOL = 'LOCAL_NOTIS_HAND_OVER';
 const SEARCH_THREADS_TOOL = 'LOCAL_NOTIS_SEARCH_CODING_AGENT_THREADS';
 
-const ROUTES = ['notis', 'auto', 'codex_cloud', 'claude_cloud', 'codex_local', 'claude_local'];
+// What --route accepts and advertises. `auto` lets Notis pick the agent.
+const ROUTES = ['auto', 'notis', 'codex', 'claude'];
+// Values from before Notis picked the agent itself. Still accepted, so scripts
+// and agents that learned them keep working, but never shown in help, examples
+// or errors. They are sent as typed; the server maps them to codex or claude.
+const LEGACY_ROUTES = new Map([
+  ['codex_cloud', 'codex'],
+  ['codex_local', 'codex'],
+  ['claude_cloud', 'claude'],
+  ['claude_local', 'claude'],
+]);
+const ROUTE_LABELS = { notis: 'Notis', codex: 'Codex', claude: 'Claude' };
 const BRANCH_MODES = ['new', 'same'];
 
 // A cloud coding agent takes minutes to start, and the hand-over POST itself
@@ -44,6 +56,17 @@ const HANDOVER_TIMEOUT_MS = 120_000;
  */
 const HANDOVER_UNAVAILABLE_CODES = new Set(['usage_error', 'forbidden']);
 
+/** A legacy route as the agent it now means; anything else unchanged. */
+function normalizeRoute(route) {
+  return LEGACY_ROUTES.get(route) || route;
+}
+
+/** Who the hand-over went to, in words, for progress lines and the summary. */
+function describeRoute(route) {
+  if (route === 'auto') return 'Notis, which picks the agent';
+  return ROUTE_LABELS[route] || route;
+}
+
 /**
  * Quote a value for the command line the receiving agent is told to run.
  *
@@ -121,8 +144,8 @@ async function handoverStartHandler(ctx) {
     throw usageError(`--branch-mode must be one of: ${BRANCH_MODES.join(', ')}`, { branchMode });
   }
 
-  const route = ctx.options.route || 'notis';
-  if (!ROUTES.includes(route)) {
+  const route = ctx.options.route || 'auto';
+  if (!ROUTES.includes(route) && !LEGACY_ROUTES.has(route)) {
     throw usageError(`--route must be one of: ${ROUTES.join(', ')}`, { route });
   }
 
@@ -223,7 +246,10 @@ async function handoverStartHandler(ctx) {
     repoSlug: ctx.options.repo || null,
   });
 
-  ctx.output.emitProgress({ phase: 'handover', message: `Handing over to ${route}` });
+  ctx.output.emitProgress({
+    phase: 'handover',
+    message: `Handing over to ${describeRoute(normalizeRoute(route))}`,
+  });
   const result = await runToolCommand({
     runtime: {
       ...ctx.runtime,
@@ -255,7 +281,9 @@ async function handoverStartHandler(ctx) {
     branch_mode: branchMode,
     head: repository.head,
     wip_commit: wipCommit,
-    agent_routing: payload.agent_routing || route,
+    // The server answers with auto, notis, codex or claude. An older server
+    // may echo a legacy value back, so map it here too.
+    agent_routing: normalizeRoute(payload.agent_routing || route),
     interaction_id: payload.interaction_id || null,
     thread_id: payload.thread_id || null,
   };
@@ -264,7 +292,7 @@ async function handoverStartHandler(ctx) {
     command: 'handover start',
     data,
     humanSummary:
-      `Handed ${data.branch} over to ${data.agent_routing} ` +
+      `Handed ${data.branch} over to ${describeRoute(data.agent_routing)} ` +
       `(${branchMode === 'same' ? 'continuing the branch' : 'new branch from it'}).`,
     hints: [
       { command: 'notis handover status', reason: 'See what the agent is doing' },
@@ -313,8 +341,8 @@ export const handoverCommandSpecs = [
     summary: 'Hand the current branch to a Notis agent and keep working.',
     when_to_use:
       'Use this when you want Notis to continue work on the branch you are on -- long refactors, ' +
-      'test fixing, or anything that should keep running after you close the laptop. Pick the agent ' +
-      'with --route.',
+      'test fixing, or anything that should keep running after you close the laptop. Notis picks ' +
+      'the agent unless you name one with --route.',
     args_schema: {
       arguments: [{ token: '<task>', description: 'What the agent should do, in plain language.' }],
       options: [
@@ -327,7 +355,7 @@ export const handoverCommandSpecs = [
         {
           flags: '--route <target>',
           description:
-            'Which agent runs it: notis (hosted, default), codex_cloud, claude_cloud, codex_local, claude_local, or auto.',
+            'Which agent runs it: auto (default, Notis picks the agent), notis, codex or claude.',
         },
         { flags: '--repo <slug>', description: 'Configured repository slug on the cloud computer, when you know it.' },
         {
@@ -338,12 +366,13 @@ export const handoverCommandSpecs = [
     },
     examples: [
       'notis handover start "fix the failing auth tests"',
-      'notis handover start "finish the migration" --branch-mode same --route codex_cloud',
-      'notis handover start "add integration tests" --route claude_cloud',
-      'notis handover start "review and clean up this branch" --route claude_local',
+      'notis handover start "finish the migration" --branch-mode same --route codex',
+      'notis handover start "add integration tests" --route claude',
+      'notis handover start "review and clean up this branch" --route notis',
     ],
     output_schema:
-      'Returns the branch, the resolved routing target, and the interaction/thread ids of the started run.',
+      'Returns the branch, the agent routing (auto when Notis picks, otherwise notis, codex or claude), ' +
+      'and the interaction/thread ids of the started run.',
     mutates: true,
     idempotent: false,
     require_auth: true,

package/src/command-specs/helpers.js

@@ -12,6 +12,7 @@ const NOTIS_DATABASE_CORE_NAMES = new Set([
   'get_document',
   'list_databases',
   'upsert_database',
+  'upload_file',
   'delete_database',
 ]);
 

package/src/command-specs/index.js

@@ -1,4 +1,3 @@
-import { reportsCommandSpecs } from './reports.js';
 import { appsCommandSpecs } from './apps.js';
 import { toolsCommandSpecs } from './tools.js';
 import { metaCommandSpecs } from './meta.js';
@@ -10,14 +9,19 @@ import { profileCommandSpecs } from './profile.js';
 import { handoverCommandSpecs } from './handover.js';
 import { agentsCommandSpecs } from './agents.js';
 import { skillsCommandSpecs } from './skills.js';
+import { spacesCommandSpecs } from './spaces.js';
+import { viewsCommandSpecs } from './views.js';
+import { filesCommandSpecs } from './files.js';
 
 export const GROUP_SUMMARIES = {
-  reports: 'Build and save independent SDK reports into app database records.',
+  files: 'Upload local files for native records with verified byte receipts.',
+  views: 'Discover and render the views you can open.',
+  spaces: 'Build independent Spaces and their declared capabilities.',
   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.',
   tools: 'Discover and execute generic tools exposed through Notis.',
-  skills: 'Keep Notis and local-agent skills synchronized.',
+  skills: 'List, edit and link Notis Skills, and keep local-agent skills synchronized.',
   profile: 'Switch between signed-in accounts and their API endpoints.',
   debug: 'Inspect effective runtime context, worker identity, and trace costs.',
   smoke: 'Run deterministic connected-service smoke tests with guaranteed cleanup.',
@@ -29,8 +33,10 @@ export const COMMAND_SPECS = [
   ...onboardingCommandSpecs,
   ...agentsCommandSpecs,
   ...skillsCommandSpecs,
+  ...spacesCommandSpecs,
+  ...viewsCommandSpecs,
+  ...filesCommandSpecs,
   ...appsCommandSpecs,
-  ...reportsCommandSpecs,
   ...handoverCommandSpecs,
   ...toolsCommandSpecs,
   ...diagnosticCommandSpecs,

package/src/command-specs/skills.js

@@ -2,6 +2,81 @@ import { getJwtSubject } from '../runtime/profiles.js';
 import { reconcileAllSkills } from '../runtime/sync-skills.js';
 import { ensureFreshOAuthCredential } from '../runtime/oauth.js';
 import { installSkillSyncService } from '../runtime/skill-sync-service.js';
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { httpRequest } from '../runtime/transport.js';
+import { usageError } from '../runtime/errors.js';
+import { parseJson } from './helpers.js';
+
+async function nativeSkillAuthoring(ctx, body, path = '/portal_skills/native-authoring') {
+  // A Space target, destination or link change touches Spaces: declare the protocol.
+  const spaceTarget = Boolean(body.target?.space_id || body.destination?.space_id || body.links);
+  const result = await httpRequest({ runtime: ctx.runtime, method: 'POST', path, body,
+    ...(spaceTarget ? { spacesProtocol: 1 } : {}) });
+  return ctx.output.emitSuccess({ command: ctx.spec.command_path.join(' '), data: result.payload,
+    humanSummary: JSON.stringify(result.payload, null, 2),
+    meta: { mutating: body.operation !== 'read' && !body.dry_run, request_id: result.requestId } });
+}
+
+function exactKeys(value, keys) {
+  return value && typeof value === 'object' && !Array.isArray(value)
+    && Object.keys(value).sort().join(',') === [...keys].sort().join(',');
+}
+
+function skillTarget(value, updating) {
+  const direct = updating ? ['skill_id', 'access_revision'] : ['skill_id'];
+  const space = updating ? ['space_id', 'binding_id', 'binding_revision', 'expected_skill_id', 'space_revision'] : ['space_id', 'binding_id'];
+  if (!exactKeys(value, direct) && !exactKeys(value, space)) {
+    throw usageError('Use one exact direct or Space target from the Skill inventory or skills read.');
+  }
+  return value;
+}
+
+function requestKey(ctx) {
+  const request = ctx.options.requestId || ctx.globalOptions.idempotencyKey;
+  if (typeof request !== 'string' || !request || request.length > 200) throw usageError('Pass --request-id <stable-key>.');
+  return request;
+}
+
+function linkLabel(link) {
+  return `${link.space_name || link.space_id}/${link.alias}${link.available === false ? ' (unavailable)' : ''}`;
+}
+
+/** One line per Skill: name, ID, kind, editability and its Space links. */
+export function skillInventoryLines(page) {
+  const entries = Array.isArray(page?.skills) ? page.skills : [];
+  if (!entries.length) return 'No Skills match.';
+  const lines = entries.map(entry => {
+    const state = entry.editable ? 'editable' : `read-only${entry.read_only_reason ? ` (${entry.read_only_reason})` : ''}`;
+    const links = (entry.links || []).map(linkLabel);
+    return `${entry.name || entry.skill_id}  ${entry.skill_id}  ${entry.kind}  ${state}  links: ${links.length ? links.join(', ') : 'none'}`;
+  });
+  if (page.has_more && page.next) lines.push(`More Skills: rerun with --after ${page.next}`);
+  return lines.join('\n');
+}
+
+/** What a link change did and where the resource is listed now. */
+export function linkChangeSummary(result) {
+  const parts = [];
+  const added = (result?.added || []).map(link => `${link.space_id}/${link.alias}`);
+  const removed = (result?.removed || []).map(link => `${link.space_id}/${link.alias}`);
+  if (added.length) parts.push(`added: ${added.join(', ')}`);
+  if (removed.length) parts.push(`removed: ${removed.join(', ')}`);
+  if (result?.became_standalone) parts.push('now your standalone Skill');
+  if (result?.replayed) parts.push('confirmed retry');
+  const current = (result?.links || []).map(linkLabel);
+  return `${parts.join('; ') || 'No change'}. Listed in: ${current.length ? current.join(', ') : 'none'}.`;
+}
+
+function linkEntries(value, option, required, optional = []) {
+  const parsed = parseJson(value, option);
+  const valid = entry => entry && typeof entry === 'object' && !Array.isArray(entry)
+    && required.every(key => key in entry) && Object.keys(entry).every(key => required.includes(key) || optional.includes(key));
+  if (!Array.isArray(parsed) || !parsed.length || !parsed.every(valid)) {
+    throw usageError(`${option} must be a JSON array of {${[...required, ...optional.map(key => `${key}?`)].join(', ')}} entries.`);
+  }
+  return parsed;
+}
 
 async function loadSkillSyncEngine() {
   return import('../../dist/skill-sync/index.js');
@@ -48,6 +123,160 @@ export async function syncSkillsHandler(ctx, {
 }
 
 export const skillsCommandSpecs = [
+  {
+    command_path: ['skills', 'list'],
+    summary: 'List every Skill you can see, with its kind, editability and Space links.',
+    when_to_use: 'Find a Skill and its exact edit target before reading or editing it, or see what a Space and its sub-Spaces list. Links to Spaces you cannot open are omitted; an unavailable link gives no access.',
+    args_schema: { arguments: [], options: [
+      { flags: '--space <id>', description: 'Only Skills listed by this Space and, by default, its sub-Spaces.' },
+      { flags: '--no-child-spaces', description: 'With --space: direct links of that Space only.' },
+      { flags: '--include-disabled', description: 'Include Skills you disabled.' },
+      { flags: '--after <cursor>', description: 'Continue from the next cursor of the previous page.' },
+      { flags: '--limit <n>', description: 'Page size between 1 and 100 (default 50).' },
+    ] },
+    examples: ['notis skills list', 'notis skills list --space <space-id> --no-child-spaces --json'],
+    mutates: false, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_skills/inventory' },
+    async handler(ctx) {
+      const body = {};
+      if (ctx.options.space !== undefined) body.space_id = ctx.options.space;
+      if (ctx.options.childSpaces === false) {
+        if (body.space_id === undefined) throw usageError('--no-child-spaces needs --space <id>.');
+        body.include_child_spaces = false;
+      }
+      if (ctx.options.includeDisabled) body.include_disabled = true;
+      if (ctx.options.after !== undefined) body.after = ctx.options.after;
+      if (ctx.options.limit !== undefined) {
+        const limit = Number(ctx.options.limit);
+        if (!/^\d+$/.test(String(ctx.options.limit)) || limit < 1 || limit > 100) throw usageError('Pass --limit between 1 and 100.');
+        body.limit = limit;
+      }
+      const result = await httpRequest({ runtime: ctx.runtime, method: 'POST', path: '/portal_skills/inventory', body });
+      return ctx.output.emitSuccess({ command: 'skills list', data: result.payload,
+        humanSummary: skillInventoryLines(result.payload), meta: { mutating: false, request_id: result.requestId } });
+    },
+  },
+  {
+    command_path: ['skills', 'create'],
+    summary: 'Create a native Skill, standalone or linked to an editable Space.',
+    when_to_use: 'Create complete instructions or files without provider installation. Choose an optional Space destination, dry-run, and keep the exact request key on retry.',
+    args_schema: { arguments: [{ token: '<file>', key: 'file', description: 'JSON containing name, optional description, and skill_md or base64 files.' }],
+      options: [{ flags: '--request-id <key>', description: 'Stable creation intent key; reuse after an uncertain reply.' },
+        { flags: '--dry-run', description: 'Validate without creating an identity or uploading files.' }] },
+    examples: ['notis skills create ./skill.json --request-id create-1 --dry-run'],
+    mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_skills/native-create' },
+    handler(ctx) {
+      const payload = parseJson(readFileSync(resolve(ctx.args.file), 'utf8'), 'Skill creation file');
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+          || Object.keys(payload).some(key => !['destination', 'name', 'description', 'skill_md', 'files'].includes(key))) {
+        throw usageError('Provide a name, complete instructions or files, and an optional current destination; never override ownership.');
+      }
+      const destination = payload.destination ?? { kind: 'standalone' };
+      if (!(exactKeys(destination, ['kind']) && destination.kind === 'standalone')
+          && !exactKeys(destination, ['space_id', 'alias', 'revision'])) throw usageError('Choose a standalone destination or exact Space, alias and revision.');
+      const request = ctx.options.requestId || ctx.globalOptions.idempotencyKey;
+      if (typeof request !== 'string' || !request || request.length > 200) throw usageError('Pass --request-id <stable-key>.');
+      return nativeSkillAuthoring(ctx, { ...payload, operation: 'create', destination,
+        request_id: request, dry_run: Boolean(ctx.options.dryRun) }, '/portal_skills/native-create');
+    },
+  },
+  {
+    command_path: ['skills', 'settings', 'read'],
+    summary: 'Read a native Skill personal enablement, agent targets and settings revision.',
+    when_to_use: 'Inspect direct-owner preferences without changing shared instructions or Space access.',
+    args_schema: { arguments: [{ token: '<skill-id>', key: 'skillId', description: 'Exact native Skill ID.' }], options: [] },
+    mutates: false, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_skills/native-settings' },
+    handler(ctx) { return nativeSkillAuthoring(ctx, { operation: 'read', target: { skill_id: ctx.args.skillId } }, '/portal_skills/native-settings'); },
+  },
+  {
+    command_path: ['skills', 'settings', 'update'],
+    summary: 'Update personal native Skill settings with a current revision and stable retry key.',
+    when_to_use: 'Enable or disable your agents without changing a shared Skill definition or another Space.',
+    args_schema: { arguments: [{ token: '<file>', key: 'file', description: 'JSON with target, revision and patch (enabled or agent_targets).' }],
+      options: [{ flags: '--request-id <key>', description: 'Stable settings intent; reuse after a lost reply.' },
+        { flags: '--dry-run', description: 'Validate current ownership and revision without changing settings.' }] },
+    mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_skills/native-settings' },
+    handler(ctx) {
+      const payload = parseJson(readFileSync(resolve(ctx.args.file), 'utf8'), 'Skill settings file');
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+          || Object.keys(payload).sort().join(',') !== 'patch,revision,target'
+          || !payload.target || Object.keys(payload.target).sort().join(',') !== 'access_revision,skill_id') {
+        throw usageError('Use a current standalone target, settings revision and personal settings patch.');
+      }
+      const request = ctx.options.requestId || ctx.globalOptions.idempotencyKey;
+      if (typeof request !== 'string' || !request || request.length > 200) throw usageError('Pass --request-id <stable-key>.');
+      return nativeSkillAuthoring(ctx, { ...payload, operation: 'update', request_id: request, dry_run: Boolean(ctx.options.dryRun) }, '/portal_skills/native-settings');
+    },
+  },
+  {
+    command_path: ['skills', 'read'],
+    summary: 'Inspect a native Skill through direct ownership or an editable Space link.',
+    when_to_use: 'Read the exact target and content version before editing. A Space target uses its current Editor authority, never a personal fallback.',
+    args_schema: { arguments: [{ token: '[skill-id]', key: 'skillId', description: 'Exact directly owned Skill ID; omit when passing --target.' }],
+      options: [{ flags: '--files', description: 'Include every verified supporting file as base64.' },
+        { flags: '--target <json>', description: 'Exact {skill_id} or {space_id,binding_id} read target; do not combine with a Skill ID.' }] },
+    examples: ['notis skills read <skill-id> --files', 'notis skills read --target \'{"space_id":"<id>","binding_id":"<binding>"}\' --files'],
+    mutates: false, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_skills/native-authoring' },
+    handler(ctx) {
+      if (Boolean(ctx.args.skillId) === Boolean(ctx.options.target)) throw usageError('Pass either a Skill ID or --target <json>.');
+      const target = skillTarget(ctx.options.target ? parseJson(ctx.options.target, '--target') : { skill_id: ctx.args.skillId }, false);
+      return nativeSkillAuthoring(ctx, { operation: 'read', target,
+        include_files: Boolean(ctx.options.files) });
+    },
+  },
+  {
+    command_path: ['skills', 'update'],
+    summary: 'Edit a native Skill through its direct or Space target, preserving its ID and supporting files.',
+    when_to_use: 'Use the target/version from skills list or skills read, dry-run, then reuse the same request key and bytes to save or recover a lost reply. The same edit file works for a standalone or a Space target; an optional links key changes where the Skill is listed in the same transaction.',
+    args_schema: { arguments: [{ token: '<file>', key: 'file', description: 'JSON with direct or Space target, version, skill_md or base64 files, optional name/description and links {add,remove}.' }],
+      options: [{ flags: '--request-id <key>', description: 'Stable edit intent key; reuse after lost replies.' },
+        { flags: '--dry-run', description: 'Check current access, content and revisions without uploading or saving.' }] },
+    examples: ['notis skills update ./skill-edit.json --request-id edit-1 --dry-run'],
+    mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_skills/native-authoring' },
+    handler(ctx) {
+      const payload = parseJson(readFileSync(resolve(ctx.args.file), 'utf8'), 'Skill edit file');
+      if (!payload || typeof payload !== 'object' || Array.isArray(payload)
+          || Object.keys(payload).some(key => !['target', 'version', 'skill_md', 'files', 'name', 'description', 'links'].includes(key))) {
+        throw usageError('Use an exact target, version, skill_md or files, and optional links; never override ownership.');
+      }
+      skillTarget(payload.target, true);
+      if ('links' in payload && (!payload.links || typeof payload.links !== 'object' || Array.isArray(payload.links)
+          || !Object.keys(payload.links).length || Object.keys(payload.links).some(key => !['add', 'remove'].includes(key)))) {
+        throw usageError('links must be an object with add and/or remove arrays.');
+      }
+      return nativeSkillAuthoring(ctx, { ...payload, operation: 'update', request_id: requestKey(ctx),
+        dry_run: Boolean(ctx.options.dryRun) });
+    },
+  },
+  {
+    command_path: ['skills', 'links'],
+    summary: 'Add, remove or move a Skill between Spaces; the Skill keeps its ID.',
+    when_to_use: 'Change where a Skill is listed without editing its content. A move is one add plus one remove in one transaction. You must be an Editor of every Space you touch and able to edit the Skill; removing its last available link keeps it as your own standalone Skill.',
+    args_schema: { arguments: [{ token: '<skill-id>', key: 'skillId', description: 'Exact Skill ID from skills list.' }], options: [
+      { flags: '--add <json>', description: 'JSON array of {space_id, space_revision, alias?} links to add; alias defaults to the Skill name.' },
+      { flags: '--remove <json>', description: 'JSON array of {binding_id, binding_revision} links to remove, from skills list.' },
+      { flags: '--request-id <key>', description: 'Stable intent key; reuse it unchanged when retrying this change.' },
+    ] },
+    examples: ['notis skills links <skill-id> --add \'[{"space_id":"<space-id>","space_revision":3}]\' --request-id link-1',
+      'notis skills links <skill-id> --add \'[{"space_id":"<to-space-id>","space_revision":3}]\' --remove \'[{"binding_id":"<binding-id>","binding_revision":2}]\' --request-id move-1'],
+    mutates: true, idempotent: true, require_auth: true,
+    backend_call: { type: 'http', path: '/portal_spaces/resource-links' },
+    async handler(ctx) {
+      const links = {};
+      if (ctx.options.add !== undefined) links.add = linkEntries(ctx.options.add, '--add', ['space_id', 'space_revision'], ['alias']);
+      if (ctx.options.remove !== undefined) links.remove = linkEntries(ctx.options.remove, '--remove', ['binding_id', 'binding_revision']);
+      if (!Object.keys(links).length) throw usageError('Pass --add and/or --remove.');
+      const body = { kind: 'skill', resource_id: ctx.args.skillId, links, request_id: requestKey(ctx) };
+      const result = await httpRequest({ runtime: ctx.runtime, method: 'POST', path: '/portal_spaces/resource-links', body, spacesProtocol: 1 });
+      return ctx.output.emitSuccess({ command: 'skills links', data: result.payload,
+        humanSummary: linkChangeSummary(result.payload), meta: { mutating: true, request_id: result.requestId } });
+    },
+  },
   {
     command_path: ['skills', 'sync'],
     summary: 'Synchronize account skills and keep the three Notis base skills current.',