@notis_ai/cli 0.2.5 → 0.2.6

package/skills/notis-apps/SKILL.md

@@ -32,6 +32,7 @@ npx --package @notis_ai/cli@latest -- notis apps create
 npx --package @notis_ai/cli@latest -- notis apps link
 npx --package @notis_ai/cli@latest -- notis apps pull
 npx --package @notis_ai/cli@latest -- notis apps deploy
+npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready
 npx --package @notis_ai/cli@latest -- notis apps doctor
 ```
 
@@ -47,13 +48,17 @@ npx --package @notis_ai/cli@latest -- notis apps ...
 - Build standard pages in `app/`. Do not write raw `views/<slug>/index.js` files.
 - Keep navigation in `notis.config.ts` `routes`; each route needs a stable `slug`.
 - Reference existing databases by slug in `notis.config.ts`; do not assume deploy creates databases automatically.
+- Every native database is owned by exactly one app. Creating one with `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` requires the owning app's slug or id in the `app` argument (create the app first with `LOCAL_NOTIS_CREATE_APP` if needed); deleting an app deletes its databases and their documents.
 - Declare runtime tool access in `notis.config.ts` `tools`.
 - Use `@notis/sdk` hooks instead of direct runtime access.
 - Do not rely on `window.__NOTIS_RUNTIME__` or portal-owned DOM hooks.
 - `npx --package @notis_ai/cli@latest -- notis apps deploy` updates an installed app. It does not publish to the public App Store.
 - **Local development first; deploy is user-gated.** Iterate with `apps dev` and hand off for the **user** to test in the desktop **Local development** sidebar group. Do not run `apps create` / `apps deploy` on your own — a clean build/verify is not permission to deploy. Deploy only when the user has tested the local build and explicitly asks. Finishing a build without deploying is the expected outcome.
 - **Installed app links are explicit.** A mounted dev session updates an installed app only when the checkout is linked by app id in `.notis/state.json` and the active dev-session registry mirrors that id. Name or slug matches may be suggestions, never update targets.
-- Public or team App Store publishing is a Portal review flow.
+- **Store submission is separately user-gated.** Run `apps publish --confirm-ready` only after the user explicitly confirms the current App Details page is ready. Deploy that exact approved state first; never infer Store approval from a deploy request.
+- **Bump `notisAppVersion` for every Store update.** `package.json` must contain a semver `notisAppVersion`; increment it beyond the currently published registry version before deploying an update.
+- **Keep release history in one root `CHANGELOG.md`.** Put the newest entry first and use `## [Release title] - YYYY-MM-DD`, or `{PR_MERGE_DATE}` before publication. Do not add new `versionNotes` fields to `notis.config.ts`. App Details reads **What’s New** and **Version History** from the deployed package manifest; the Store reads the latest published snapshot, so unpublished workspace edits never change it. The manifest exposes `package.json` `notisAppVersion` as the package version shown in App Details.
+- Public submissions still use the registry review flow; the CLI invokes the same authenticated submission endpoint as App Details.
 - Use Phosphor icon names with the `phosphor:` prefix. Do not use emoji icons.
 - Prefer scaffolded shadcn components and portal theme tokens over custom visual systems.
 
@@ -90,8 +95,14 @@ npx --package @notis_ai/cli@latest -- notis apps screenshot
 npx --package @notis_ai/cli@latest -- notis apps verify
 ```
 
-`notis apps screenshot` renders each route in a headless harness and writes
-`metadata/screenshot-N.png` (2000x1250, 16:10). Apps are icon-led like Raycast:
+Declare 3–6 screenshots in `notis.config.ts`, each with a `path`, descriptive
+`alt`, and optional `route`/`scenario`/`focus`/`theme`. Use `focus` to crop to a
+real app root instead of empty browser canvas, and use `theme: 'light'` or
+`theme: 'dark'` for a matching Portal render and Store frame. Paired light/dark
+entries may reuse the same route and scenario. `notis apps screenshot` renders
+those configured states in a headless harness and writes exact 2000x1250 PNGs
+under `metadata/`, using the deterministic Store presentation by default. Use
+`--raw` only for an unframed diagnostic capture. Apps are icon-led like Raycast:
 the app icon represents the app everywhere, so there is no cover image — only
 these screenshots. Re-run after changing routes or UI; it overwrites the set and
 drops stale files. Use `--routes home,history` to capture a subset.
@@ -103,6 +114,12 @@ npx --package @notis_ai/cli@latest -- notis apps create "My App" .
 npx --package @notis_ai/cli@latest -- notis apps deploy
 ```
 
+6. **Only after the user explicitly confirms App Details is ready for Store review**, submit the deployed version:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready
+```
+
 or:
 
 ```bash
@@ -116,6 +133,7 @@ Expected project shape:
 
 ```text
 notis.config.ts
+CHANGELOG.md        # complete Store release history, newest entry first
 vite.config.ts
 app/
 components/
@@ -123,18 +141,38 @@ metadata/          # screenshot-N.png only — generated by `notis apps screensh
 .notis/output/
 ```
 
-`metadata/` holds listing screenshots (`screenshot-1.png`, `screenshot-2.png`,
-…). There is no `cover.png`: apps are icon-led like Raycast and the icon set in
+`metadata/` holds 3–6 listing screenshots (`screenshot-1.png`, `screenshot-2.png`,
+…). Each must be an exact 2000x1250 PNG no larger than 2 MB, with descriptive
+alt text declared in `notis.config.ts`. There is no `cover.png`: apps are icon-led like Raycast and the icon set in
 `notis.config.ts` represents the app in the Store. Generate screenshots with
 `notis apps screenshot` rather than authoring PNGs by hand.
 
 `notis.config.ts` owns:
 
 - app metadata: name, title, description, icon, accent, categories, tagline
+- listing screenshots: stable path, alt text, and optional capture route/scenario/focus/theme
 - database slug references
 - route definitions
 - tool access
 
+`CHANGELOG.md` owns Store release copy. Keep all releases in that single file:
+
+```markdown
+# My App Changelog
+
+## [A Better Workflow] - {PR_MERGE_DATE}
+
+- Added a faster daily workflow.
+
+## [Initial Release] - 2026-07-01
+
+- Published the first version.
+```
+
+Store publication is blocked until the deployed manifest contains at least one
+valid entry. Ordinary local development and deployment still work when an app
+is not being prepared for the Store.
+
 **Icon & accent.** Set `icon` to a `phosphor:<name>` value (e.g. `phosphor:dice-five`) or `metadata/icon.png`. When `icon` is unset, the app shows its **two-letter initials** everywhere (store, sidebar, app details). `accent` optionally pins the avatar color to one of `blue | violet | emerald | amber | rose | sky | fuchsia | teal`; when unset a stable color is derived automatically from the app id. Both flow from `notis.config.ts` through deploy onto the app row and listing, and can also be changed later with the `update_app` tool (`{ "icon": "phosphor:...", "accent": "emerald" }`).
 
 Example:

package/skills/notis-apps/cli.md

@@ -137,9 +137,9 @@ Examples:
 
 ### `npx --package @notis_ai/cli@latest -- notis apps verify [dir]`
 
-Headless render smoke each route in a stub-runtime harness.
+Validate every route and the production Store listing contract.
 
-When to use: After notis apps build, before deploy. Catches render-time crashes and missing runtime calls that the build step cannot detect.
+When to use: After notis apps screenshot, before deploy. Catches render-time crashes, missing runtime calls, and incomplete listing media that the build step cannot detect.
 
 Options:
 - `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
@@ -157,23 +157,25 @@ Examples:
 
 ### `npx --package @notis_ai/cli@latest -- notis apps screenshot [dir]`
 
-Capture listing screenshots of each route via the headless harness.
+Capture configured listing route/scenario states via the headless harness.
 
-When to use: Generate metadata/screenshot-N.png for the App Store listing. Apps are icon-led (like Raycast) — there is no cover image, only these screenshots. Run before notis apps verify / deploy / publish.
+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.
 
 Options:
-- `--routes <slugs>` — Comma-separated route slugs. Default: every route in manifest.
+- `--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/.
 
 Examples:
-- `npx --package @notis_ai/cli@latest -- notis apps screenshot`
+- `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 apps link <app-id> [dir]`
 
@@ -216,6 +218,20 @@ Examples:
 - `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 apps publish [dir]`
+
+Submit the deployed app for Store review.
+
+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.
+
+Options:
+- `--app-id <id>` — Override linked app ID.
+- `--confirm-ready` — Confirm the user approved the current App Details page for Store submission.
+
+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 apps doctor [dir]`
 
 Check project health and readiness.

package/skills/notis-cli/SKILL.md

@@ -140,8 +140,9 @@ This is the main escape hatch for:
    - `npx --package @notis_ai/cli@latest -- notis tools exec <tool-name> --arguments '<json>'`
 6. If multiple independent calls are needed, use:
    - `npx --package @notis_ai/cli@latest -- notis tools exec-parallel '<json-array>'`
-7. If the toolkit is not connected yet, generate the connection URL:
+7. If the toolkit is not connected yet, start its connection flow:
    - `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>`
+   - For a revoked or invalid credential-based connection, reconnect with credential JSON on stdin: `npx --package @notis_ai/cli@latest -- notis tools link <toolkit> --reconnect --credentials -`
 
 ### Tool access rules
 
@@ -150,6 +151,8 @@ This is the main escape hatch for:
 - When you know the tool name but not the argument shape, use `npx --package @notis_ai/cli@latest -- notis tools describe` or `--get-schema` before execution.
 - Use `--dry-run` before mutating calls when you want schema validation without execution.
 - If a toolkit is missing, use `npx --package @notis_ai/cli@latest -- notis tools link <toolkit>` to start the connection flow.
+- Use `--reconnect` to replace an existing connection. If multiple accounts exist, select one with `--connection-id <id>`.
+- For API keys, basic auth, or other credential JSON, prefer `--credentials -` and pipe or redirect stdin. Avoid inline secrets because they can enter shell history and process listings.
 
 ### Toolkit mental model
 
@@ -202,6 +205,12 @@ Connect a missing toolkit:
 npx --package @notis_ai/cli@latest -- notis tools link github
 ```
 
+Reconnect a credential-based toolkit without putting the secret in shell history:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools link dataforseo --reconnect --credentials - < credentials.json
+```
+
 ## Native database access
 
 Native Notis databases are accessed through the generic tool workflow, not a first-class database command group. Use these canonical tool names:
@@ -209,7 +218,7 @@ Native Notis databases are accessed through the generic tool workflow, not a fir
 - `LOCAL_NOTIS_DATABASE_LIST_DATABASES` -- list databases accessible to the current profile
 - `LOCAL_NOTIS_DATABASE_GET_DATABASE` -- inspect read-only metadata and schema detail
 - `LOCAL_NOTIS_DATABASE_QUERY` -- query documents from a database
-- `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` -- create or update a database schema
+- `LOCAL_NOTIS_DATABASE_UPSERT_DATABASE` -- create or update a database schema. Every database belongs to a Notis app: creation requires the owning app's slug or id in the `app` argument (create the app first with `LOCAL_NOTIS_CREATE_APP` if needed)
 
 Example workflow before building an app:
 
@@ -239,6 +248,15 @@ Most importantly: if you do not currently have the tool you need, especially for
 
 ## Troubleshooting
 
+### CLI returns `auth_expired`
+
+Local CLI auth is renewed by Notis Desktop. In JSON/agent mode, follow the
+first hint exactly: on macOS it is an executable `open -a 'Notis'` (or
+`open -a 'Notis Beta'`) command when the owning desktop app is not running.
+Wait for the app to restore the signed-in session, then rerun the original
+command. Do not copy refresh tokens into commands or try to refresh the shared
+desktop session yourself.
+
 ### Deploy fails with "network_error" or "fetch failed"
 
 The backend server at `http://localhost:3001` is not running. Solutions:

package/skills/notis-query/cli.md

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