@notis_ai/cli 0.2.4 → 0.2.6

package/dist/scaffolds/notis-notes/notis.config.ts

@@ -8,7 +8,6 @@ export default defineNotisApp({
   author: { name: 'Notis' },
   categories: ['Productivity'],
   tagline: 'Folder-based notes with gallery, table, and calendar views.',
-  versionNotes: 'Initial scaffold release.',
   databases: ['note_folders', 'notes'],
   routes: [
     {

package/dist/scaffolds/notis-random/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Random Number Generator Changelog
+
+## [Initial Release] - {PR_MERGE_DATE}
+
+- First Store release.

package/dist/scaffolds/notis-random/notis.config.ts

@@ -8,7 +8,6 @@ export default defineNotisApp({
   author: { name: 'Notis' },
   categories: ['Personal'],
   tagline: 'Roll dice, keep history.',
-  versionNotes: 'Initial scaffold release.',
 
   databases: ['rolls'],
 

package/dist/scaffolds/notis-random/src/mock-runtime.ts

@@ -30,6 +30,7 @@ export function installMockRuntime(initialRoute: 'home' | 'history' = 'home'): N
       description: 'Dev preview — data is in-memory only.',
     },
     route: currentRoute(initialRoute),
+    databases: [],
     context: {},
 
     listTools: async () => [

package/dist/scaffolds.json

@@ -12,6 +12,17 @@
       ],
       "tagline": "Explore every database and schema in your Notis workspace."
     },
+    {
+      "slug": "notis-journal",
+      "name": "5 Minutes Journal",
+      "description": "A display-only five-minute journal built from your morning and evening check-ins with Notis. Browse daily mood, energy, motivation, gratitude, intentions, affirmations, highlights, lessons, and free-form reflections, then use Stats to see trends and ritual consistency over time.",
+      "icon": "phosphor:notebook",
+      "categories": [
+        "Personal",
+        "Productivity"
+      ],
+      "tagline": "Five intentional minutes with Notis, split between morning and evening."
+    },
     {
       "slug": "notis-notes",
       "name": "Notis Notes",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@notis_ai/cli",
-  "version": "0.2.4",
+  "version": "0.2.6",
   "description": "Agent-first Notis CLI for apps and generic tool execution",
   "type": "module",
   "bin": {
@@ -29,9 +29,9 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "commander": "^12.0.0"
+    "commander": "^12.0.0",
+    "sharp": "^0.34.5"
   },
-  "devDependencies": {},
   "keywords": [
     "notis",
     "cli",

package/skills/notis-apps/SKILL.md

@@ -26,11 +26,13 @@ Use the Notis CLI for the app lifecycle:
 npx --package @notis_ai/cli@latest -- notis apps init
 npx --package @notis_ai/cli@latest -- notis apps dev
 npx --package @notis_ai/cli@latest -- notis apps build
+npx --package @notis_ai/cli@latest -- notis apps screenshot
 npx --package @notis_ai/cli@latest -- notis apps verify
 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
 ```
 
@@ -46,11 +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.
-- Public or team App Store publishing is a Portal review flow.
+- **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.
+- **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.
 
@@ -70,27 +78,48 @@ npx --package @notis_ai/cli@latest -- notis apps init "My App"
 npx --package @notis_ai/cli@latest -- notis apps pull <app-id> ./my-app
 ```
 
-3. Install dependencies and develop:
+3. Install dependencies and develop. Keep `apps dev` running and **hand off to the user** — it is what surfaces the app in the desktop **Local development** sidebar group, and letting the user test there is the finish line for a build request:
 
 ```bash
 npm install
 npx --package @notis_ai/cli@latest -- notis apps dev
 ```
 
-4. Build and verify:
+The desktop lists a dev app only if its session is in the per-workspace registry it polls: `<workspace>/.context/app-dev-sessions.json`. A current CLI auto-resolves the nearest `.context` registry; on older CLIs (or when launched outside the workspace), pass `NOTIS_APP_DEV_SESSIONS_FILE="$CONDUCTOR_WORKSPACE_PATH/.context/app-dev-sessions.json"`. After starting, confirm your app's `devSlug` is in that file with a fresh `lastHeartbeatAt` — if it isn't, the session landed in the global `~/.notis` registry and the app won't appear in the sidebar.
+
+4. Build, capture listing screenshots, and verify (still local — this does not deploy):
 
 ```bash
 npx --package @notis_ai/cli@latest -- notis apps build
+npx --package @notis_ai/cli@latest -- notis apps screenshot
 npx --package @notis_ai/cli@latest -- notis apps verify
 ```
 
-5. Create or link the remote app, then deploy:
+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.
+
+5. **Only after the user has tested the local build and explicitly asks to deploy**, create or link the remote app, then deploy (this installs or updates the app on the user's account, where it appears under **Workspace** rather than Local development). After first install, keep `.notis/state.json` linked to that installed app id so future dev-session actions become **Update** instead of another **Install**:
 
 ```bash
 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
@@ -104,20 +133,48 @@ Expected project shape:
 
 ```text
 notis.config.ts
+CHANGELOG.md        # complete Store release history, newest entry first
 vite.config.ts
 app/
 components/
-metadata/
+metadata/          # screenshot-N.png only — generated by `notis apps screenshot`
 .notis/output/
 ```
 
+`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, categories, tagline
+- 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:
 
 ```ts
@@ -128,6 +185,7 @@ export default defineNotisApp({
   title: 'My App',
   description: 'A focused Notis app.',
   icon: 'phosphor:squares-four',
+  accent: 'blue',
   databases: ['tasks'],
   routes: [
     {

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.
@@ -155,6 +155,28 @@ Examples:
 - `npx --package @notis_ai/cli@latest -- notis apps verify --mode live`
 - `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 apps screenshot [dir]`
+
+Capture configured listing route/scenario states via the headless harness.
+
+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 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  # 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]`
 
 Link a local project to a remote Notis app.
@@ -196,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