@notis_ai/cli 0.2.18 → 0.2.20

package/README.md

@@ -1,9 +1,11 @@
 # @notis_ai/cli
 
-Agent-first Notis CLI for apps and generic tool execution.
+Agent-first Notis CLI for Spaces, Skills and generic tool execution.
 
 ## Install
 
+Requires Node.js 22.12.0 or newer (Node 24 LTS recommended). Update Node.js before installing or running the CLI; the CLI never upgrades your host runtime.
+
 Use the Notis CLI through NPX; do not rely on an installed `notis` command. Run `notis login` once to authorize a scoped, revocable OAuth credential in the browser — that is how the CLI signs in everywhere, including on a machine that also runs Notis Desktop.
 
 After local login, the CLI idempotently adds static Notis guidance to detected Codex and Claude Code user instruction files without changing their hooks. Run `notis agents install` when you explicitly want memory hooks that load the user's profile at session start, recall only new relevant memories before prompts, and save completed turns as automatic cross-session context. Codex then asks you to review and trust those hooks once in `/hooks`.
@@ -16,7 +18,7 @@ For CI, hosted agents, or internal scripts, pass a non-persisted token with `NOT
 npx --package @notis_ai/cli@latest -- notis --help
 npx --package @notis_ai/cli@latest -- notis login
 npx --package @notis_ai/cli@latest -- notis doctor
-npx --package @notis_ai/cli@latest -- notis apps list
+npx --package @notis_ai/cli@latest -- notis spaces list
 npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
 ```
 
@@ -59,8 +61,9 @@ The CLI defaults to `json` output in agent or non-TTY contexts and `table` outpu
 - `--non-interactive` — Disable prompts
 - `--profile <name>` — Run as a stored profile instead of the active one
 - `--api-base <url>` — Override the API base for one invocation
-- `--timeout-ms <n>` — HTTP timeout in milliseconds
+- `--timeout-ms <n>` — Time limit in milliseconds for each call, automatic retries included
 - `--idempotency-key <key>` — Override the generated idempotency key for mutating commands
+- `--no-retry` (or `NOTIS_NO_RETRY=1`): turn off automatic retries. By default the CLI retries an interrupted tool call (network error, timeout, 502, 503 or 504) when repeating it is safe: a read, or a write with an idempotency key. It makes up to 3 attempts within `--timeout-ms` and reports the count in `meta.attempts`, or `error.details.attempts` on a failure.
 
 ## Authentication
 
@@ -76,7 +79,7 @@ Options:
 - `--mode <mode>` — auto (default) hands the browser callback to a background listener when this command cannot wait; browser waits in-process; code shows a one-time code to copy.
 - `--paste-code` — Alias for --mode code.
 - `--timeout-seconds <n>` — Authorization lifetime in seconds (default 300 while waiting in a terminal; 1800 for detached or code hand-offs).
-- `--scope <scope>` — OAuth permission to request (repeatable).
+- `--scope <scope>` — OAuth permission to request (repeatable). Default: every permission Notis offers the CLI.
 - `--code <code>` — Redeem the code shown in the browser after a non-interactive login.
 
 Examples:
@@ -90,9 +93,9 @@ Examples:
 
 ### `npx --package @notis_ai/cli@latest -- notis logout`
 
-Revoke and remove the OAuth credential for one CLI profile.
+Sign this computer out of one CLI profile: revoke and remove its OAuth credential.
 
-When to use: Use this to disconnect a single account. Other profiles keep their credentials unless you pass --all-profiles.
+When to use: Use this to disconnect a single account on this computer. Its sign-ins on other computers stay, and other profiles keep their credentials unless you pass --all-profiles.
 
 Options:
 - `--all-profiles` — Clear OAuth credentials and pending authorizations from every CLI profile.
@@ -109,22 +112,117 @@ Examples:
 
 Install Notis instructions and recall/capture hooks for local Codex and Claude Code.
 
-When to use: Run after login to give local coding agents durable Notis CLI guidance, session-start profile context, deduplicated relevant recall, and automatic completed-turn capture. Hosted Notis sandboxes already receive prompt context and are skipped.
+When to use: Run after login to give local coding agents durable Notis CLI guidance, session-start profile context, deduplicated relevant recall, and automatic completed-turn capture. Hosted Notis sandboxes are skipped unless --recall-only is given: that mode installs only recall hooks into the hosted agent's own config folder, signed in with the session's injected credential.
 
 Options:
 - `--codex-only` — Configure only Codex.
 - `--claude-only` — Configure only Claude Code.
 - `--no-memory-hooks` — Install static instructions and remove Notis recall/capture hooks.
+- `--recall-only` — Hosted coding agents: install only recall hooks (no capture, no instructions) into CODEX_HOME or CLAUDE_CONFIG_DIR, signed in with the injected NOTIS_JWT.
+- `--env-file <path>` — With --recall-only: a shell file each hook sources first to pick up the current injected sign-in.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis agents install`
 - `npx --package @notis_ai/cli@latest -- notis agents install --codex-only`
 - `npx --package @notis_ai/cli@latest -- notis agents install --claude-only`
 - `npx --package @notis_ai/cli@latest -- notis agents install --no-memory-hooks`
+- `npx --package @notis_ai/cli@latest -- notis agents install --recall-only --codex-only`
 
 
 ## Skills
 
+### `npx --package @notis_ai/cli@latest -- notis skills list`
+
+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.
+
+Options:
+- `--space <id>` — Only Skills listed by this Space and, by default, its sub-Spaces.
+- `--no-child-spaces` — With --space: direct links of that Space only.
+- `--include-disabled` — Include Skills you disabled.
+- `--after <cursor>` — Continue from the next cursor of the previous page.
+- `--limit <n>` — Page size between 1 and 100 (default 50).
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis skills list`
+- `npx --package @notis_ai/cli@latest -- notis skills list --space <space-id> --no-child-spaces --json`
+
+### `npx --package @notis_ai/cli@latest -- notis skills create <file>`
+
+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.
+
+Options:
+- `--request-id <key>` — Stable creation intent key; reuse after an uncertain reply.
+- `--dry-run` — Validate without creating an identity or uploading files.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis skills create ./skill.json --request-id create-1 --dry-run`
+
+### `npx --package @notis_ai/cli@latest -- notis skills settings read <skill-id>`
+
+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.
+
+Examples:
+
+### `npx --package @notis_ai/cli@latest -- notis skills settings update <file>`
+
+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.
+
+Options:
+- `--request-id <key>` — Stable settings intent; reuse after a lost reply.
+- `--dry-run` — Validate current ownership and revision without changing settings.
+
+Examples:
+
+### `npx --package @notis_ai/cli@latest -- notis skills read [skill-id]`
+
+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.
+
+Options:
+- `--files` — Include every verified supporting file as base64.
+- `--target <json>` — Exact {skill_id} or {space_id,binding_id} read target; do not combine with a Skill ID.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis skills read <skill-id> --files`
+- `npx --package @notis_ai/cli@latest -- notis skills read --target '{"space_id":"<id>","binding_id":"<binding>"}' --files`
+
+### `npx --package @notis_ai/cli@latest -- notis skills update <file>`
+
+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.
+
+Options:
+- `--request-id <key>` — Stable edit intent key; reuse after lost replies.
+- `--dry-run` — Check current access, content and revisions without uploading or saving.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis skills update ./skill-edit.json --request-id edit-1 --dry-run`
+
+### `npx --package @notis_ai/cli@latest -- notis skills links <skill-id>`
+
+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.
+
+Options:
+- `--add <json>` — JSON array of {space_id, space_revision, alias?} links to add; alias defaults to the Skill name.
+- `--remove <json>` — JSON array of {binding_id, binding_revision} links to remove, from skills list.
+- `--request-id <key>` — Stable intent key; reuse it unchanged when retrying this change.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis skills links <skill-id> --add '[{"space_id":"<space-id>","space_revision":3}]' --request-id link-1`
+- `npx --package @notis_ai/cli@latest -- 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`
+
 ### `npx --package @notis_ai/cli@latest -- notis skills sync`
 
 Synchronize account skills and keep the three Notis base skills current.
@@ -139,263 +237,560 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis skills sync --json`
 
 
-## Apps
+## Spaces
+
+Build, verify and publish Space views, their linked Skills and resources. The product `notis-spaces` skill owns the workflow and the consequences of links, moves and the bin.
+
+### `npx --package @notis_ai/cli@latest -- notis spaces history list <space-id>`
+
+Read a Space’s saved view versions, newest first.
+
+When to use: Inspect when and by whom a view changed, before restoring or undoing a change.
+
+Options:
+- `--before <revision>` — Read versions before this cursor.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces history list <space-id>`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces history restore <space-id>`
+
+Republish a saved view and its settings as a new version; records stay unchanged.
+
+When to use: Restore a chosen version, or undo your last change using the version immediately before it.
+
+Options:
+- `--target-revision <revision>` — The saved version to restore.
+- `--revision <revision>` — Current Space metadata revision from history list.
+- `--request-id <id>` — Stable restore request ID; reuse on retry.
+- `--dry-run` — Check current access, bindings and saved source without publishing.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces history restore <space-id> --target-revision 2 --revision 5 --request-id undo-last-change --dry-run`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces history read <space-id>`
+
+Read the files of one saved Space version.
+
+When to use: See exactly what a saved version contained, before comparing or restoring it. Editors only.
+
+Options:
+- `--revision <revision>` — The saved version from history list.
+- `--path <path>` — Read only this file or folder.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces history read <space-id> --revision 3 --path app/page.tsx`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces history diff <space-id>`
+
+Compare two saved Space versions, or one with the current version.
+
+When to use: See what changed between versions. Prints the unified diff; pass --json for the full comparison.
+
+Options:
+- `--from <revision>` — The older saved version.
+- `--to <revision>` — The newer saved version, or current (default).
+- `--path <path>` — Compare only this file or folder.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces history diff <space-id> --from 3`
+- `npx --package @notis_ai/cli@latest -- notis spaces history diff <space-id> --from 3 --to 5 --json`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces history name <space-id>`
+
+Name a saved Space version, or clear its name.
+
+When to use: Mark a version worth keeping, such as a launch. Named versions are kept past the usual retention.
+
+Options:
+- `--revision <revision>` — The saved version from history list.
+- `--name <name>` — The version name.
+- `--clear` — Remove the version name.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces history name <space-id> --revision 3 --name "Launch"`
+- `npx --package @notis_ai/cli@latest -- notis spaces history name <space-id> --revision 3 --clear`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces history delete <space-id>`
+
+Delete one saved Space version for good.
+
+When to use: Only when the user asked to delete this version. It cannot be restored afterwards.
+
+Options:
+- `--revision <revision>` — The saved version from history list.
+- `--yes` — Confirm the user asked to delete this version for good.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces history delete <space-id> --revision 3 --yes`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces screenshot <url>`
+
+Capture a full-height PNG of a live view with your current access.
+
+When to use: Check the actual deployed view; writes are blocked and current access is checked again before any output is saved.
+
+Options:
+- `--width <pixels>` — 1440 (default) or 390.
+- `--output-dir <path>` — New output directory; defaults to a unique .notis/renders directory. Existing files are never overwritten.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces screenshot <view-link> --width 390`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces init <name> [dir]`
+
+Scaffold an editable collection view with first-party record components.
+
+When to use: Start a local Space collection source for an existing linked database. Does not create or deploy remote resources.
+
+Options:
+- `--database-key <key>` — Portable key of the database this Space links.
+- `--path <path>` — Descriptive view path; defaults to records.
+- `--title-property <id>` — Canonical title/number property ID, or the title column (default).
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces init Notes ./notes --database-key notes --path notes`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces navigation bind <space-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps list`
+Bind a named destination for the next source publication without granting target access.
 
-List apps the current profile can access.
+When to use: Connect a portable navigation alias to an existing Space or exact record before building and publishing.
 
-When to use: Discover existing apps before linking or deploying.
+Options:
+- `--alias <name>` — Declared portable navigation alias.
+- `--target <json>` — Exact {space_id,document_id?}, or null to remove the draft binding.
+- `--revision <number>` — Current source Space metadata revision.
+- `--dry-run` — Check current source/target access and revision without changing anything.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps list`
-- `npx --package @notis_ai/cli@latest -- notis apps list --json`
+- `npx --package @notis_ai/cli@latest -- notis spaces navigation bind <space-id> --alias history --target '{"space_id":"<history-id>"}' --revision 2 --dry-run`
 
-### `npx --package @notis_ai/cli@latest -- notis apps init <name> [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces resources name <space-id> <binding-id>`
 
-Scaffold a new Notis app project.
+Give an included resource a portable alias before the first source revision.
 
-When to use: Start a new Notis app. Use --from with a published Store app when one is close to the desired app; otherwise creates the bare Vite + React project.
+When to use: Prepare staged resources for source authoring without replacing their IDs, scope or owners.
 
 Options:
-- `--from <slug>` — Start from a published Store app listed by `notis apps scaffolds list`. Downloads its source from the public app registry.
+- `--alias <name>` — Stable lowercase alias to use in source.
+- `--revision <number>` — Current Space metadata revision.
+- `--dry-run` — Check naming, current access and revision without changing metadata.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces resources name <space-id> <binding-id> --alias weekly-report --revision 0 --dry-run`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces links list <space-id>`
+
+List the databases, Skills, automations and records linked into one Space.
+
+When to use: Find a link binding and its revision before removing it, including a link left behind by a deleted Skill.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
-- `npx --package @notis_ai/cli@latest -- notis apps init "Mind the Flo"`
-- `npx --package @notis_ai/cli@latest -- notis apps init "My CRM" --from databases`
-- `npx --package @notis_ai/cli@latest -- notis apps init "My App" ~/code/my-app`
+- `npx --package @notis_ai/cli@latest -- notis spaces links list <space-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
+### `npx --package @notis_ai/cli@latest -- notis spaces links remove <space-id> <binding-id>`
 
-List published Store apps available as scaffolds.
+Remove one database, Skill or automation link from a Space by its binding.
 
-When to use: Discover published Store apps to start from before creating a new app. Every app published to the public Store is automatically a scaffold; use --search to narrow the catalog.
+When to use: Unlist a resource from a Space you edit, including a link whose Skill was deleted. The resource keeps its ID; removing the last available link of a live resource keeps it as its owner's standalone resource.
 
 Options:
-- `--search <term>` — Filter scaffolds by name, tagline, description, or category.
+- `--revision <number>` — Current binding revision from spaces links list.
+- `--request-id <key>` — Stable intent key; reuse it unchanged when retrying this removal.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list`
-- `npx --package @notis_ai/cli@latest -- notis apps scaffolds list --search journal`
-- `npx --package @notis_ai/cli@latest -- notis apps init "My App" --from databases`
+- `npx --package @notis_ai/cli@latest -- notis spaces links remove <space-id> <binding-id> --revision 1 --request-id remove-link-1`
 
-### `npx --package @notis_ai/cli@latest -- notis apps create <name> [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces aliases list`
 
-Create a new remote Notis app and optionally link a local project to it.
+List the old App page links you manage and the Space each one opens.
 
-When to use: Provision a fresh remote app before the first deploy. Pass a project directory to link it immediately.
+When to use: Find an old App page link that opens a binned Space (trashed: true) before repointing it.
+
+Options:
+- `--legacy-id <id>` — Old App ID the links belong to.
+- `--kind <kind>` — app (default), report or html.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps create "My App"`
-- `npx --package @notis_ai/cli@latest -- notis apps create "My App" .`
+- `npx --package @notis_ai/cli@latest -- notis spaces aliases list --legacy-id <app-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps dev [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces aliases repoint`
 
-Register a development root and connect its apps to the shared local development host.
+Point one old App page link at a live Space you edit.
 
-When to use: Run this once for any folder that should be watched permanently. The folder itself, direct child apps, and apps/* are discovered automatically by every signed-in Notis Desktop instance. A linked app substitutes its online bundle only when local notisAppVersion is strictly greater than the installed release.
+When to use: Repair an old App page link whose Space was binned. You must own the old App or edit the Space the link opens now, and edit the new Space; everyone who opens the link still needs their own access to it.
 
 Options:
-- `--port <number>` — Local bundle server port (default: 5173).
-- `--scratch` — Use isolated empty databases, bundled skills, and bundled automations for this session instead of the installed app's resources. For fixture work and destructive experiments.
-- `--live-data` — Deprecated: using the installed app's real resources is now the default. Accepted as a no-op; use `--scratch` for the old isolated behavior.
-- `--grant-cloud-shell` — Approve a cloudComputer: 'shell' declaration without the interactive prompt. The grant persists for this dev app; authorship alone never grants it.
+- `--legacy-id <id>` — Old App ID the link belongs to.
+- `--route <slug>` — Old App page route from spaces aliases list.
+- `--space <space-id>` — Live Space the old link should open.
+- `--expected-space <space-id>` — Space the link opens now; the change is refused if it moved since you listed it.
+- `--selection-param <name>` — Declared view parameter that receives the old page selection, if any.
+- `--request-id <key>` — Stable intent key; reuse it unchanged when retrying this change.
+- `--dry-run` — Check authority and the new Space without changing the link.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps dev`
-- `npx --package @notis_ai/cli@latest -- notis apps dev ./my-app`
-- `npx --package @notis_ai/cli@latest -- notis apps dev ./workspace --port 5200`
-- `npx --package @notis_ai/cli@latest -- notis apps dev --scratch  # isolated resources for fixture or schema experiments`
+- `npx --package @notis_ai/cli@latest -- notis spaces aliases repoint --legacy-id <app-id> --route pages --space <space-id> --expected-space <binned-space-id> --request-id repoint-pages --dry-run`
 
-### `npx --package @notis_ai/cli@latest -- notis apps roots list`
+### `npx --package @notis_ai/cli@latest -- notis spaces pull <space-id> [dir]`
 
-List persistent machine-local Notis app development roots.
+Pull one editable Space source snapshot, its resource list and its Skill folders into an empty directory.
 
-When to use: See which folders every local Notis Desktop instance watches for development apps.
+When to use: Edit a Space you can administer: the source, its links (resources.json) and every editable linked Skill (skills/<alias>/) arrive together, with a local lock file so a later deploy sends only what you changed.
+
+Options:
+- `--revision <number>` — Exact published source revision; defaults to the current one.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps roots list`
+- `npx --package @notis_ai/cli@latest -- notis spaces pull <space-id> ./space-source`
 
-### `npx --package @notis_ai/cli@latest -- notis apps roots remove <folder>`
+### `npx --package @notis_ai/cli@latest -- notis spaces verify [dir]`
 
-Stop watching a registered Notis app development root.
+Render one frozen Space with offline fixtures and validate its current action authorizations.
 
-When to use: Remove a persistent development root. The built-in ~/.notis/apps root cannot be removed.
+When to use: Check immutable build bytes and authoring compatibility without executing actions or publishing.
+
+Options:
+- `--space <key>` — Exact source key from the workspace index.
+- `--space-id <id>` — Exact existing destination Space.
+- `--reuse-grants <json>` — Explicit action-key to saved-grant-ID map. Otherwise your own connections are used.
+- `--reuse-grants-only` — Never authorize new actions. Reuse only the supplied saved grants; other declarations remain unavailable. Requires existing bound databases.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps roots remove ./old-apps`
+- `npx --package @notis_ai/cli@latest -- notis spaces verify . --space overview --space-id <space-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps build [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces preview [dir]`
 
-Build and package the app into .notis/output/.
+Seal a checked unpublished revision of the same Space and return its authenticated preview link.
 
-When to use: Prepare the app for verification or deployment.
+When to use: Review a checked candidate using current Editor access without changing live source or cloning the Space.
+
+Options:
+- `--space <key>` — Exact source key from the workspace index.
+- `--space-id <id>` — Exact existing destination Space.
+- `--reuse-grants <json>` — Explicit action-key to saved-grant-ID map. Otherwise your own connections are used.
+- `--reuse-grants-only` — Never authorize new actions. Reuse only the supplied saved grants; other declarations remain unavailable. Requires existing bound databases.
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+- `--dry-run` — Validate without uploading or publishing.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps build`
-- `npx --package @notis_ai/cli@latest -- notis apps build ./my-app`
+- `npx --package @notis_ai/cli@latest -- notis spaces preview . --space overview --space-id <space-id> --request-id release-1`
 
-### `npx --package @notis_ai/cli@latest -- notis apps verify [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces deploy [dir]`
 
-Validate that every route renders and reports Store listing readiness.
+Publish one built Space with a retry-safe, independent source revision.
 
-When to use: Any time after notis apps build, and before deploy. Catches render-time crashes and missing runtime calls. Incomplete listing media is reported as a warning; pass --listing to fail on it instead.
+When to use: Update only the selected existing Space; this does not publish to the Store or change siblings.
 
 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` — Fail instead of warn when the Store listing (tagline, categories, screenshots, changelog) is incomplete.
-- `--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).
+- `--space <key>` — Exact source key from the workspace index.
+- `--space-id <id>` — Exact existing destination Space.
+- `--reuse-grants <json>` — Explicit action-key to saved-grant-ID map. Otherwise your own connections are used.
+- `--reuse-grants-only` — Never authorize new actions. Reuse only the supplied saved grants; other declarations remain unavailable. Requires existing bound databases.
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+- `--dry-run` — Validate without uploading or publishing.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps verify`
-- `npx --package @notis_ai/cli@latest -- notis apps verify --routes notes`
-- `npx --package @notis_ai/cli@latest -- notis apps verify --mode live`
-- `npx --package @notis_ai/cli@latest -- notis apps verify --listing  # gate on Store listing readiness before publish`
-- `npx --package @notis_ai/cli@latest -- notis apps verify --no-browser  # start the harness, drive agent-browser yourself`
+- `npx --package @notis_ai/cli@latest -- notis spaces deploy . --space overview --space-id <space-id> --request-id release-1`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces promote <release-id> [dir]`
+
+Publish the exact sealed Space revision, with its pending Skill and link changes, after current permission and concurrency checks.
+
+When to use: Finish a reviewed preview without rebuilding or substituting a different candidate. The Skill edits, new Skills and list changes the preview carried go live in the same transaction.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces promote <release-id>`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces abandon <release-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps screenshot [dir]`
+Close an unpublished Space preview without changing its live source, Skills or links, or deleting action history.
 
-Capture configured listing route/scenario states via the headless harness.
+When to use: Stop using a candidate while preserving live source and completed effects.
 
-When to use: Generate the 3–6 declared metadata/screenshot-N.png files for the App Store listing. Apps are icon-led (like Raycast) — there is no cover image, only these screenshots. Each screenshot may set a focus selector to remove empty canvas and a light or dark theme that also controls its Store frame. Run before notis apps verify / deploy / publish.
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces abandon <release-id>`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces list`
+
+List Spaces currently available to your account.
+
+When to use: Discover accessible Spaces without exposing an issuer-wide resource catalogue.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces list`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces get <space-id>`
+
+Read one accessible Space and its scoped resources.
+
+When to use: Inspect the current published revision and named capabilities before executing.
 
 Options:
-- `--routes <slugs>` — Comma-separated route slugs. Default: every configured screenshot state.
-- `--port <n>` — Loopback port. Default: auto-pick.
-- `--width <px>` — Viewport width. Default: 2000.
-- `--height <px>` — Viewport height. Default: 1250 (16:10).
-- `--output-dir <dir>` — Where to write screenshot-N.png. Default: metadata/.
-- `--mode <mode>` — stub | live. Default stub. Live renders against real data via the CLI JWT (requires a linked app), so screenshots show actual content instead of empty states.
-- `--raw` — Write the unframed harness capture instead of the default Store presentation.
-- `--skip-build` — Skip notis apps build; reuse existing .notis/output/.
+- `--record <record-key>` — Fixed record context, when this is a record-scoped Space.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps screenshot  # honors notis.config.ts screenshot scenarios`
-- `npx --package @notis_ai/cli@latest -- notis apps screenshot --routes home,history`
-- `npx --package @notis_ai/cli@latest -- notis apps screenshot --mode live  # populated screenshots from real data`
-- `npx --package @notis_ai/cli@latest -- notis apps screenshot --raw  # diagnostic capture without Store framing`
+- `npx --package @notis_ai/cli@latest -- notis spaces get <space-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps link <app-id> [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces action <space-id> <action-id>`
 
-Link a local project to a remote Notis app.
+Execute a declared action using its saved authorization.
 
-When to use: Connect a local project to an existing app for deployment.
+When to use: Use Space capabilities as the actual actor, with the saved issuer connection and payer.
+
+Options:
+- `--revision <number>` — Exact published source revision.
+- `--preview-release <id>` — Exact sealed candidate ID; requires current Editor access.
+- `--schema-revision <number>` — Native schema revision; required for native row writes.
+- `--inputs <json>` — Declared action input values; defaults to {}.
+- `--record <record-key>` — Fixed record context, when this is a record-scoped Space.
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+- `--dry-run` — Validate current access and action inputs without executing or billing.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps link abc123`
-- `npx --package @notis_ai/cli@latest -- notis apps link abc123 ./my-app`
+- `npx --package @notis_ai/cli@latest -- notis spaces action <space-id> refresh --revision 1 --inputs '{}' --request-id refresh-1 --dry-run`
 
-### `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces viewer-read <space-id> <operation>`
 
-Download a Notis app source snapshot into a local project folder.
+Run one declared viewer read as yourself.
 
-When to use: Edit an installed app locally. Preserve any local edits, pull and link the latest persisted source, then increment package.json notisAppVersion above that release before notis apps dev; continue with build and deploy.
+When to use: Check what an explorer Space shows you: the databases or Skills you can open, with your own access and never an issuer grant.
 
 Options:
-- `--force` — Overwrite a non-empty target directory.
-- `--source-version <n>` — Pull a specific app source version (default: latest).
+- `--revision <number>` — Exact published source revision.
+- `--preview-release <id>` — Exact sealed candidate ID; requires current Editor access.
+- `--input <json>` — Read input, e.g. {"database_id":"<id>"}; defaults to {}.
+- `--record <record-key>` — Fixed record context, when this is a record-scoped Space.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps pull abc123`
-- `npx --package @notis_ai/cli@latest -- notis apps pull abc123 ./my-app --force --source-version 3`
+- `npx --package @notis_ai/cli@latest -- notis spaces viewer-read <space-id> list_databases --revision 3`
+- `npx --package @notis_ai/cli@latest -- notis spaces viewer-read <space-id> query_database --revision 3 --input '{"database_id":"<id>","request":{"page_size":20}}'`
 
-### `npx --package @notis_ai/cli@latest -- notis apps deploy [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces grants list <space-id>`
 
-Build and upload the app to the linked Notis app.
+Inspect authorization records for a Space you can edit.
 
-When to use: Ship the installed app to production for the linked user/team app. A project that has only a development app is promoted in place on first deploy: same app id, same databases, dev markers removed. This command does not publish to the app store.
+When to use: Inspect issuers and exact constraints without exposing connection secrets.
 
 Options:
-- `--app-id <id>` — Override linked app ID.
-- `--skip-build` — Skip the build step (use existing .notis/output/).
-- `--direct` — Explicitly upload to Supabase storage, bypassing the backend server.
+- `--record <record-key>` — Fixed record context, when this is a record-scoped Space.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps deploy`
-- `npx --package @notis_ai/cli@latest -- notis apps deploy --skip-build`
-- `npx --package @notis_ai/cli@latest -- notis apps deploy --app-id abc123`
-- `npx --package @notis_ai/cli@latest -- notis apps deploy --direct`
+- `npx --package @notis_ai/cli@latest -- notis spaces grants list <space-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps publish [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces grants create <space-id>`
 
-Submit the deployed app for Store review.
+Authorize an exact template using your current connection.
 
-When to use: After the user explicitly confirms the App Details page and Store listing are ready. Requires the current local project to match the latest deployed version.
+When to use: Create a Space-bound authorization; the server resolves the signed-in issuer connection.
 
 Options:
-- `--app-id <id>` — Override linked app ID.
-- `--confirm-ready` — Confirm the user approved the current App Details page for Store submission.
+- `--template <file>` — Canonical action template JSON file.
+- `--record <record-key>` — Fixed record context, when this is a record-scoped Space.
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+- `--dry-run` — Validate the template and Editor access without creating a grant.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready`
-- `npx --package @notis_ai/cli@latest -- notis apps publish ./my-app --confirm-ready`
+- `npx --package @notis_ai/cli@latest -- notis spaces grants create <space-id> --template action.json --request-id grant-1 --dry-run`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces grants revoke <grant-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps duplicate [dir]`
+Revoke one saved Space authorization.
 
-Duplicate an app into an independent copy with its own databases.
+When to use: Stop future dispatches for an authorization you issued or can administer.
 
-When to use: When the same app should run for a second purpose - a notes app for blog drafts alongside one for bookmarks. The copy shares no data with the source.
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces grants revoke <grant-id>`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces store list`
+
+List Space Store listings you can see.
+
+When to use: Find Space templates published to your team or approved for everyone, and your own listings.
 
 Options:
-- `--app-id <id>` — App to duplicate. Defaults to the app this project is linked to.
-- `--name <name>` — Name for the duplicate (default: the source name followed by "copy").
-- `--copy-documents <mode>` — Which rows to copy: 'declared' (default, the starter content a fresh install would have), 'all', or 'none'.
+- `--channel <team|public>` — Only one channel.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces store list --channel team`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces store get <listing-id>`
+
+Read one Store listing with its versions and your installs.
+
+When to use: Check what a listing contains, its review state and whether your copies have an update.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps duplicate --name "Blog"`
-- `npx --package @notis_ai/cli@latest -- notis apps duplicate --app-id abc123 --name "Bookmarks" --copy-documents none`
+- `npx --package @notis_ai/cli@latest -- notis spaces store get <listing-id>`
 
-### `npx --package @notis_ai/cli@latest -- notis apps doctor [dir]`
+### `npx --package @notis_ai/cli@latest -- notis spaces store installs`
 
-Check project health and readiness.
+List the Spaces you installed from the Store.
 
-When to use: Diagnose issues with a Notis app project.
+When to use: See which installed copies have an update or conflicts to resolve.
 
 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 spaces store installs`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces store publish <space-id>`
+
+Publish a Space and its sub-Spaces as the next Store version.
+
+When to use: Share a Space you own as an installable template: team listings publish at once, public ones wait for review. Notis runs the same safety scan and Owner check as the submission page and explains any refusal.
+
+Options:
+- `--channel <team|public>` — Where to publish.
+- `--metadata <json>` — Listing name, tagline, description, category, icon, accent.
+- `--starter <json>` — Starter row IDs per database ({"<database-id>":["<record-key>"]}).
+- `--notes <text>` — Release notes for this version.
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+- `--dry-run` — Show the package counts and review diff without publishing.
 
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces store publish <space-id> --channel team --request-id publish-1 --dry-run`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces store install <listing-id>`
+
+Install a Store listing as your own independent copy.
+
+When to use: Add a published Space template to your account; your copy keeps your changes on later updates.
+
+Options:
+- `--name <name>` — Name of the installed top Space.
+- `--parent <space-id>` — Install under one of your Spaces.
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+- `--dry-run` — Show what the copy contains without installing.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces store install <listing-id> --request-id install-1`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces store update <install-id>`
+
+Update an installed copy, keeping your changes, or resolve its conflicts.
+
+When to use: Take a newer Store version: unchanged parts update, your edits stay, and parts both sides changed become conflicts you resolve.
+
+Options:
+- `--resolve <json>` — Per conflict key: "keep_mine" or "take_theirs".
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+- `--dry-run` — Show the three-way plan without changing anything.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces store update <install-id> --request-id update-1 --dry-run`
+- `npx --package @notis_ai/cli@latest -- notis spaces store update <install-id> --resolve '{"skill:<key>":"keep_mine"}' --request-id resolve-1`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces store unpublish <listing-id>`
+
+Stop new installs of a Store listing.
+
+When to use: Withdraw a listing: existing copies keep working and a version waiting for review is withdrawn.
+
+Options:
+- `--request-id <key>` — Stable intent key. Reuse after timeouts or lost replies.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces store unpublish <listing-id> --request-id unpublish-1`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces build [dir]`
+
+Build one independent Space and save its frozen source/artifact snapshot.
+
+When to use: Prepare a selected Space for verification without publishing it or changing siblings.
+
+Options:
+- `--space <key>` — Exact source key from the workspace Space index.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces build . --space overview`
+
+### `npx --package @notis_ai/cli@latest -- notis spaces inspect [dir]`
+
+Inspect one local Space definition and its declared capabilities.
+
+When to use: Read the selected source definition without loading sibling definitions or account resources.
+
+Options:
+- `--space <key>` — Exact source key from the workspace Space index.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis spaces inspect . --space overview`
+
+
+## Views
+
+### `npx --package @notis_ai/cli@latest -- notis views find`
+
+Find the views you can open for a record, database, view link, Space or search.
+
+When to use: Get fresh view-qualified links and declared URL parameters before citing or opening a view.
+
+Options:
+- `--record-key <id>` — Find views that show this exact native record.
+- `--database-id <id>` — Find views over this database.
+- `--url <url>` — Resolve this view link and its current parameters.
+- `--space-id <id>` — Describe this Space view.
+- `--query <text>` — Search accessible view names, descriptions and readable context.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis views find --record-key <record-key>`
+- `npx --package @notis_ai/cli@latest -- notis views find --url <view-link>`
+- `npx --package @notis_ai/cli@latest -- notis views find --query inbox`
+
+### `npx --package @notis_ai/cli@latest -- notis views render <url>`
+
+Render a live view as Markdown and a full-height PNG with your current access.
+
+When to use: Check the actual deployed view; writes are blocked and current access is checked again before any output is saved.
+
+Options:
+- `--outputs <kinds>` — Comma-separated markdown,screenshot (default both).
+- `--width <pixels>` — 1440 (default) or 390.
+- `--output-dir <path>` — New output directory; defaults to a unique .notis/renders directory. Existing files are never overwritten.
+
+Examples:
+- `npx --package @notis_ai/cli@latest -- notis views render <view-link> --outputs markdown,screenshot`
+
+
+## Reports and saved HTML
+
+Create independently authored interactive reports as Space views with the product `notis-spaces` guidance and its reports reference. Build and verify the selected source, deploy within the user's authorization, then render its current view link.
+
+Save self-contained HTML pages and reports in Notis Notes with the Save HTML Skill that comes with it; pages and reports saved before Spaces open there too. Its generic file upload is attached to an existing note with a separate revision-checked write; a raw download URL is not a saved page link.
 
 ## Hand-over
 
-Give the branch you are on to a Notis agent, which continues the work in a git worktree on the Notis cloud computer. `--route` picks the agent: the hosted Notis agent, or the user's own Codex/Claude Code in the cloud sandbox or on their Mac. `--branch-mode same` makes the agent commit onto your branch; the default cuts a new branch from it.
+Give the branch you are on to a Notis agent, which continues the work in a git worktree on the Notis cloud computer. The caller chooses who runs it and how from the user's words and passes all three: `--route` (notis, codex or claude), `--intelligence` (low, medium or high) and `--speed` (normal, priority or flex, flex on Notis only). None has a default; `auto` leaves the agent or the intelligence to Notis, only when the user asks for that. `--branch-mode same` makes the agent commit onto your branch; the default cuts a new branch from it. The hand-over starts a Notis thread, shown in the Manager; follow it with `notis handover status <request-id>`. When a start cannot say whether the work began, check `notis handover status` before handing it over again.
 
 ### `npx --package @notis_ai/cli@latest -- notis handover start <task>`
 
 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.
+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. Choose the agent, intelligence and speed yourself from the user's words, even loose ones ("get Claude on it", "this one is tricky", "no rush"), and pass all three; with no agent named, codex for code work. Use auto only when the user asks Notis to pick.
 
 Options:
+- `--route <agent>` — Required. Which agent runs it: notis, codex or claude, or auto only when the user asks Notis to pick.
+- `--intelligence <level>` — Required. low (quick, simple tasks), medium (most multi-step work and coding), high (hard reasoning, investigations, complex code), or auto only when the user asks Notis to pick.
+- `--speed <speed>` — Required. normal (the usual choice), priority (faster, costs more; for Codex or Claude only when the user asks for their fast mode) or flex (cheaper and slower, Notis only).
 - `--branch-mode <mode>` — same = the agent commits onto your branch. new = the agent cuts a new branch from it (default).
-- `--route <target>` — Which agent runs it: notis (hosted, default), codex_cloud, claude_cloud, codex_local, claude_local, or auto.
 - `--repo <slug>` — Configured repository slug on the cloud computer, when you know it.
 - `--no-wip` — Refuse on a dirty tree instead of committing the changes first.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis handover start "fix the failing auth tests"`
-- `npx --package @notis_ai/cli@latest -- notis handover start "finish the migration" --branch-mode same --route codex_cloud`
-- `npx --package @notis_ai/cli@latest -- notis handover start "add integration tests" --route claude_cloud`
-- `npx --package @notis_ai/cli@latest -- notis handover start "review and clean up this branch" --route claude_local`
-
-### `npx --package @notis_ai/cli@latest -- notis handover status`
+- `npx --package @notis_ai/cli@latest -- notis handover start "fix the failing auth tests" --route codex --intelligence medium --speed normal`
+- `npx --package @notis_ai/cli@latest -- notis handover start "finish the migration" --branch-mode same --route codex --intelligence high --speed normal`
+- `npx --package @notis_ai/cli@latest -- notis handover start "add integration tests" --route claude --intelligence medium --speed normal`
+- `npx --package @notis_ai/cli@latest -- notis handover start "review and clean up this branch" --route notis --intelligence low --speed flex`
 
-Show the coding-agent threads Notis is running for you.
+### `npx --package @notis_ai/cli@latest -- notis handover status [request-id]`
 
-When to use: Use this after a hand-over to see whether the agent is still working.
+Follow a hand-over, or list the work Notis is running for you.
 
-Options:
-- `--provider <provider>` — Filter to codex or claude_code.
-- `--refresh` — Force a live refresh instead of cached state.
+When to use: Use this after a hand-over. Pass the request_id `handover start` returned to read its progress and result; with no id it lists the threads still running.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis handover status`
-- `npx --package @notis_ai/cli@latest -- notis handover status --provider codex --refresh`
+- `npx --package @notis_ai/cli@latest -- notis handover status 6f1c2e8a-4b7d-5c3e-9a1f-2d8b7e6c5a4f`
 
 
 ## Generic Tools
@@ -445,6 +840,7 @@ Options:
 - `--file <argument-path=local-path>` — Upload a local file into a file-uploadable tool argument. Repeatable.
 - `--get-schema` — Display the tool parameter schema without executing.
 - `--dry-run` — Validate arguments against the tool schema without executing.
+- `--yes` — Apply a change that asks for confirmation without the Continue? [y/N] prompt.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_slug":"tasks","query":{}}'`
@@ -501,7 +897,7 @@ Examples:
 
 Switch the default profile without signing any profile out.
 
-When to use: Use this to change which account and API subsequent commands target. Every other profile keeps its credential.
+When to use: Use this to change which account and API subsequent commands target. Every other profile keeps its credential. Its skills replace the previous default's in the agent folders (Claude Code, Codex, Cursor) straight away.
 
 Examples:
 - `npx --package @notis_ai/cli@latest -- notis profile use work`
@@ -560,7 +956,7 @@ Describe a first-class CLI command in detail.
 When to use: Use this when an agent or human needs the exact shape, examples, and semantics of a command.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis describe apps deploy`
+- `npx --package @notis_ai/cli@latest -- notis describe spaces deploy`
 - `npx --package @notis_ai/cli@latest -- notis describe tools exec`