@notis_ai/cli 0.2.0-beta.156.1 → 0.2.0-beta.158.1

package/dist/base-skills/notis-cli/SKILL.md

@@ -4,6 +4,7 @@ description: Use when agents should work through the Notis CLI, especially to de
 feature_flag: cli_access
 mcp_resource: true
 mcp_tool_patterns: []
+mcp_references: ["references/app-delivery.md", "references/tool-examples.md", "references/native-databases.md", "references/troubleshooting.md"]
 ---
 
 # Notis CLI Skill
@@ -14,7 +15,6 @@ This skill covers two main CLI workflows:
 
 1. Developing Notis apps locally.
 2. Accessing Notis, Composio, and MCP tools through the CLI.
-
 ## When to use this skill
 
 Activate this skill when:
@@ -71,146 +71,15 @@ This is especially important when:
 
 Treat the Notis CLI the same way you would treat a Composio-style tool router flow: discover what is available first, then execute the right tool through the CLI.
 
-## Section 1: Developing Notis Apps
-
-Use this section when the goal is to create or update a Notis app from a local
-workspace or a hosted sandbox.
-
-Notis apps are Vite + React projects using `@notis/sdk`. After init or pull and editing, choose one terminal branch: local Desktop uses `dev → build → verify → user approval → deploy`; hosted sandbox uses `build → verify → identity/schema reconciliation → deploy`; Store submission is a later, separately confirmed action.
-
-Important: `deploy` only updates the installed app artifact for the current user or team. Store submission is a separate, user-gated step. After the user explicitly confirms that the current App Details page and Store listing are ready, `apps publish --confirm-ready` submits the matching deployed version through the backend review flow.
-
-Choose the execution path before changing the app:
-
-- **Hosted sandbox**: a sandbox instruction or `/vercel/sandbox` working tree
-  proves that Desktop cannot mount the source. Do not run `apps dev`. A create
-  or edit request authorizes `apps deploy` after `apps build` and automated
-  `apps verify` pass unless the user explicitly requests preview-only,
-  read-only, or no deployment; inspection, review, and diagnosis stay
-  read-only. `apps pull <app-id>` links an existing app. Test before any remote
-  mutation. If an opt-out applies, stop there without create/link, database
-  mutation, deploy, or post-deploy checks. Otherwise, for a new unlinked app,
-  compare profile state and `apps list --json` with the canonical
-  `notis.config.ts` `name` and intended personal/team scope: link one exact
-  editable non-development match after a metadata-only (`include_documents:
-  false`) detail read proves scope, fail on any ambiguity/development
-  collision/scope mismatch, or create only on zero exact matches. Default new
-  apps to personal scope unless the user explicitly asks for team scope. Prove
-  canonicalizing the config title yields its name. For personal creation, run
-  `apps create "<canonical-config-title>" . --json` exactly once. For explicit
-  team scope, discover/describe and dry-run `LOCAL_NOTIS_CREATE_APP`, execute it
-  exactly once with team visibility and verified current team scope, verify the
-  returned identity/scope, and link that exact id. In a fresh sandbox, install Agent Browser with `npm exec --yes --package
-  agent-browser@latest -- agent-browser install` and run verification through
-  `npx --yes --package @notis_ai/cli@latest --package agent-browser@latest --
-  notis apps verify`. Read back the exact app id/version and Portal URL with `apps list --json`, run
-  the same combined command with `apps verify --mode live`, and return the exact
-  Portal URL. Stop before deployment on test failure and before retry on an
-  outcome-unknown create or deploy.
-- **Local computer**: run `apps dev`, let the user test the DEV-badged app, and
-  deploy that development identity directly only after the user explicitly
-  asks; never run `apps create` after `apps dev`.
-
-### App development workflow
-
-1. Scaffold a new app (every published Store app is a scaffold; `notis apps scaffolds list [--search <term>]` lists them from the public registry, and `--from <slug>` downloads that app's source):
-   - `npx --package @notis_ai/cli@latest -- notis apps init ["My App"] [--from <slug>]`
-2. Or pull an existing app's source to edit it (the project is linked automatically):
-   - `npx --package @notis_ai/cli@latest -- notis apps pull <app-id>`
-   - then run `npm install`, increment `notisAppVersion`, and edit
-3. **Local Desktop branch:** run `apps dev` for live testing, confirm the DEV
-   app and root/mount acceptance checks, then run `apps build` and `apps verify`.
-   Let the user test the DEV app and stop for explicit user approval. When
-   approved, run exactly one `apps deploy` to promote the existing `dev_app_id`
-   (or update the already linked app), then read it back. Never run `apps create`
-   after `apps dev`.
-4. **Hosted sandbox branch:** bootstrap Agent Browser as described above, then
-   run `apps build` followed by the automated hosted `apps verify`. If automatic
-   deployment is opted out, stop after those tests with no app create/link,
-   database mutation, deploy, or post-deploy check. Otherwise, for a new hosted
-   app, reconcile `.notis/state.json` and `apps list --json` against
-   the canonical config `name` and intended scope (personal by default; team
-   only when explicitly requested). Include
-   development rows as collision checks. Link one exact editable non-dev match
-   only after a metadata-only (`include_documents: false`) exact app detail
-   proves scope; fail on multiple/scope mismatch, or create only on zero. Prove
-   canonicalize(config title) equals config name. For personal creation, run
-   `apps create "<canonical-config-title>" . --json` exactly once and verify id,
-   slug, edit permission, and personal scope. For explicit team scope, discover
-   and describe `LOCAL_NOTIS_CREATE_APP`, dry-run it, then execute it exactly once
-   with the canonical title, team visibility, and verified current team scope;
-   verify id/slug/team scope/edit permission and `apps link` that exact id. Then
-   compare declared databases, mutate only
-   missing/changed backward-compatible schemas with ownership proof, run exactly
-   one `apps deploy`, and read back id/version/Portal URL before live verify.
-5. Check project health:
-   - `npx --package @notis_ai/cli@latest -- notis apps doctor`
-6. Only after the user explicitly approves the current Store preview, submit the deployed version:
-   - `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready`
-
-### App development rules
-
-- Always `build` before `deploy`; run `verify` before deploy when validating an app change.
-- Never run `apps dev` in a hosted sandbox. Deploy every successfully verified
-  sandbox app create or edit unless explicitly told preview-only, read-only, or
-  no-deploy, then prove the remote id/version and live runtime. Other app tasks
-  do not authorize mutation.
-- Deploy does not create databases. Compare first; materialize only missing or
-  changed hosted-app schemas, and verify exact ownership before an update.
-- Build and verify before hosted app creation or database mutation. Only
-  backward-compatible schema expansion may happen before deployment.
-- In hosted sandboxes, bootstrap `agent-browser` and include its package on the
-  verification command's `PATH`; `--no-browser` is not a passing automated gate.
-- Never deploy a local Desktop edit until the user tests the DEV app and asks.
-- Prefer `npx --package @notis_ai/cli@latest -- notis apps deploy` for the first deploy of a project already run with `apps dev`; it promotes the development app in place.
-- Link before `deploy`, or pass `--app-id <id>` when intentionally deploying without writing local link state.
-- Use `npx --package @notis_ai/cli@latest -- notis apps doctor` to diagnose configuration or dependency issues.
-- Use `npx --package @notis_ai/cli@latest -- notis apps list --json` to discover exact slugs, permissions, versions, and Portal links before linking and after deployment; use a metadata-only (`include_documents: false`) exact app-detail read to prove personal/team scope without materializing databases.
-- Never treat deploy approval as Store approval. Set visibility to Team or Public first, then run `apps publish --confirm-ready` only after the user explicitly confirms the current App Details page and Store listing.
-- `apps publish --confirm-ready` submits the deployed snapshot through the same backend review flow as App Details. It must reject missing confirmation, incomplete listing media, a local/deployed version mismatch, private visibility, or an existing pending review.
-
-### App development command reference
-
-- `npx --package @notis_ai/cli@latest -- notis apps list` -- list accessible apps
-- `npx --package @notis_ai/cli@latest -- notis apps init` -- scaffold a new Vite + React + `@notis/sdk` project
-- `npx --package @notis_ai/cli@latest -- notis apps pull <app-id> [dir] [--force] [--source-version <n>]` -- download the persisted source snapshot for an installed app and link the local directory to that app/version; legacy apps must be redeployed once with the current CLI before they can be pulled
-- `npx --package @notis_ai/cli@latest -- notis apps dev` -- discover local apps, register desktop-local dev sessions, and load them as DEV-badged Workspace rows in the Electron Portal
-- `npx --package @notis_ai/cli@latest -- notis apps build` -- compile the production artifact
-- `npx --package @notis_ai/cli@latest -- notis apps verify` -- headless render-smoke packaged routes before deploy
-- `npx --package @notis_ai/cli@latest -- notis apps create` -- create a fresh remote app and optionally link the local project
-- `npx --package @notis_ai/cli@latest -- notis apps link` -- associate the project with a remote app
-- `npx --package @notis_ai/cli@latest -- notis apps deploy` -- upload the artifact and editable source snapshot to the linked installed app in Notis
-- `npx --package @notis_ai/cli@latest -- notis apps deploy --direct` -- deploy directly to Supabase storage, bypassing the backend server (auto-fallback when server is down)
-- `npx --package @notis_ai/cli@latest -- notis apps publish --confirm-ready` -- submit the matching deployed version for Team or Public Store review after explicit user confirmation
-- `npx --package @notis_ai/cli@latest -- notis apps doctor` -- run project diagnostics
-
-App Details remains the visual review surface and offers the same Publish/Update action. The CLI command is for agents completing an already approved submission; it does not weaken the separate confirmation gate.
-
-If the task is specifically about app structure, runtime behavior, or database/view packaging, pair this skill with the `notis-apps` skill. Use `notis-cli` for the command workflow and `notis-apps` for the product/runtime contract.
-
-## IMPORTANT: When NOT to use tool access for app development
-
-When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for app file operations:
-
-- Loading or saving app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps deploy`
-- Linting app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` which validates automatically
-- Managing app routes -- write standard Vite + React pages in `app/`, not raw JS files
-
-Database schemas are the exception: declaring a slug in `notis.config.ts` does
-not create it. Use the discovery-first native database tool workflow to
-create/update and read back each app-owned schema before deployment. Tool calls
-are also valid for testing runtime behavior after deployment.
-
-## Section 2: Accessing Tools Through the Notis CLI
-
-Use this section when the current agent does not already have the right tool and needs to reach tools through Notis.
-
-This is the main escape hatch for:
-
-- direct MCP access
-- Composio-backed integrations
-- native Notis tools that are available through the generic CLI tool bridge
-- any task where you need to discover the canonical tool name and schema before execution
+## User and repository policy takes precedence
+
+Default delivery below applies only when no more restrictive user or repository
+instruction exists. Explicit preview-only/no-deploy requests and standing requirements
+for explicit deployment consent override the default. Preserve that authority across
+local and cloud runs. For local-only work, build and run stub verification; do not
+create remote resources or activate an app. `apps dev` is not a supported delivery
+path; use the CLI's documented build/verification harness. Store publication remains
+separately authorized.
 
 ### Tool access workflow
 
@@ -258,131 +127,14 @@ discovery request before every connected-service action.
 - 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
-
-Typical toolkit namespaces include:
-
-- `notis` for native Notis tools
-- `composio-*` for Composio-backed integrations
-- `mcp-*` for MCP-backed tools
-
-The pattern is:
-
-1. discover toolkits
-2. search tools
-3. inspect schema if needed
-4. execute the canonical tool
-
-### Tool access examples
-
-Find a tool:
-
-```bash
-npx --package @notis_ai/cli@latest -- notis tools toolkits
-npx --package @notis_ai/cli@latest -- notis tools search "list today's calendar events"
-```
-
-Inspect a tool before execution:
-
-```bash
-npx --package @notis_ai/cli@latest -- notis tools describe composio-googlecalendar-list_events
-npx --package @notis_ai/cli@latest -- notis tools exec composio-googlecalendar-list_events --get-schema
-```
-
-Dry-run a tool call:
-
-```bash
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --dry-run --arguments '{"database_slug":"tasks"}'
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"database_id":"tasks-db-id","query":{"page_size":10}}'
-```
-
-Execute a tool call:
-
-```bash
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"tasks"}'
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"tasks-db-id","query":{"page_size":10}}'
-```
-
-Connect a missing toolkit:
-
-```bash
-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:
-
-- `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. 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:
-
-```bash
-npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_LIST_DATABASES --arguments '{}'
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --get-schema
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"social_media_calendar"}'
-npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"social-media-calendar-db-id","query":{"page_size":1}}'
-```
-
-When `LOCAL_NOTIS_DATABASE_LIST_DATABASES` or `LOCAL_NOTIS_DATABASE_GET_DATABASE` returns a database ID, prefer `database_id` for `LOCAL_NOTIS_DATABASE_QUERY`; `database_slug` remains supported as a fallback.
-
-## Supporting commands
-
-- `npx --package @notis_ai/cli@latest -- notis whoami` — confirm which account and endpoint a command will target
-- `npx --package @notis_ai/cli@latest -- notis doctor` — verify CLI config, auth, routing, and API reachability before relying on the CLI
-- `npx --package @notis_ai/cli@latest -- notis describe <command...>` — get the exact command contract for first-class CLI commands
-
-## Summary
-
-Use `notis-cli` for two things:
-
-1. local app development through `npx --package @notis_ai/cli@latest -- notis apps ...`
-2. tool discovery and execution through `npx --package @notis_ai/cli@latest -- notis tools ...`
-
-Most importantly: if you do not currently have the tool you need, especially for direct MCP or integration work, use the Notis CLI instead of treating the task as blocked.
-
-## Troubleshooting
-
-### CLI returns `auth_expired` or `auth_missing`
-
-The profile's browser authorization has lapsed or was never granted. Run
-`notis login` (add `--profile <name>` when the failing profile is not the
-active one) and have the user approve the browser prompt. In JSON/agent mode
-the first hint is the exact command to run. Do not copy refresh tokens into
-commands or try to mint a credential yourself.
-
-If the profile is a `dev-*` one, the fix is to restart `./dev.sh` in the
-workspace it belongs to, or to switch to a real account profile.
-
-### Deploy fails with "network_error" or "fetch failed"
-
-The CLI defaults to the live Notis API (`https://api.notis.ai`, or
-`https://api-beta.notis.ai` when the signed-in user is on beta). Solutions:
-
-1. Run `npx --package @notis_ai/cli@latest -- notis doctor` and confirm `api_base` is a live Notis host
-2. Use `--direct` for app deploys when you only need Supabase storage upload: `npx --package @notis_ai/cli@latest -- notis apps deploy --direct`
-3. If auth looks stale, run `npx --package @notis_ai/cli@latest -- notis login` and retry
-
-Localhost backends are a Notis-developer test lane only. Do not retarget the CLI at loopback from this skill — that path is owned by `./dev.sh`, which exposes its own lease-backed `dev-*` profile.
-
-### `npx --package @notis_ai/cli@latest -- notis doctor` shows health/tool_roundtrip errors
-
-The CLI health check pings the configured live API. App development commands that are `backend_call: local` (`init`, `build`, `verify`, `link`, `doctor`) work offline. `dev`, `pull`, `create`, `list`, and normal `deploy` need the live API; `deploy --direct` can bypass it when Supabase credentials are available.
-
-### Stale bundle in the portal after deploy
+## Task guides
 
-The portal caches app bundles by version. If you re-deploy to the same version, the portal may serve the cached old bundle. Solutions:
+Read only the guide needed for this task. Relative links resolve in the skill bundle.
+For hosted MCP, fetch the matching `notis://docs/notis-cli/references/<file>.md` URI
+with resources/read or the available Notis resource-fetch tool; the root resource
+also rewrites these links to their published URIs.
 
-1. Hard refresh the portal page (Cmd+Shift+R)
-2. Open browser DevTools > Application > Storage > Clear site data
-3. The bundle cache key includes version number -- incrementing the version forces a fresh load
+- [App delivery](references/app-delivery.md)
+- [Toolkit mental model](references/tool-examples.md)
+- [Native database access](references/native-databases.md)
+- [Supporting commands](references/troubleshooting.md)

package/dist/base-skills/notis-cli/references/app-delivery.md

@@ -0,0 +1,18 @@
+# App delivery
+
+Use the canonical `notis-apps` skill’s entrypoint and [release guide](../../notis-apps/references/release.md).
+For hosted MCP fetch `notis://docs/notis-apps` and `notis://docs/notis-apps/references/release.md`.
+User/repository no-deploy and explicit-consent policies take precedence over default delivery.
+
+## IMPORTANT: When NOT to use tool access for app development
+
+When building or deploying a Notis app, do NOT use `npx --package @notis_ai/cli@latest -- notis tools exec` for app file operations:
+
+- Loading or saving app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` and `npx --package @notis_ai/cli@latest -- notis apps deploy`
+- Linting app files -- use `npx --package @notis_ai/cli@latest -- notis apps build` which validates automatically
+- Managing app routes -- write standard Vite + React pages in `app/`, not raw JS files
+
+Database schemas are the exception: declaring a slug in `notis.config.ts` does
+not create it. Use the discovery-first native database tool workflow to
+create/update and read back each app-owned schema before deployment. Tool calls
+are also valid for testing runtime behavior after deployment.

package/dist/base-skills/notis-cli/references/native-databases.md

@@ -0,0 +1,20 @@
+## 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:
+
+- `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. 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:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools search "list Notis databases"
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_LIST_DATABASES --arguments '{}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --get-schema
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"social_media_calendar"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"social-media-calendar-db-id","query":{"page_size":1}}'
+```
+
+When `LOCAL_NOTIS_DATABASE_LIST_DATABASES` or `LOCAL_NOTIS_DATABASE_GET_DATABASE` returns a database ID, prefer `database_id` for `LOCAL_NOTIS_DATABASE_QUERY`; `database_slug` remains supported as a fallback.

package/dist/base-skills/notis-cli/references/tool-examples.md

@@ -0,0 +1,56 @@
+### Toolkit mental model
+
+Typical toolkit namespaces include:
+
+- `notis` for native Notis tools
+- `composio-*` for Composio-backed integrations
+- `mcp-*` for MCP-backed tools
+
+The pattern is:
+
+1. discover toolkits
+2. search tools
+3. inspect schema if needed
+4. execute the canonical tool
+
+### Tool access examples
+
+Find a tool:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools toolkits
+npx --package @notis_ai/cli@latest -- notis tools search "list today's calendar events"
+```
+
+Inspect a tool before execution:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools describe composio-googlecalendar-list_events
+npx --package @notis_ai/cli@latest -- notis tools exec composio-googlecalendar-list_events --get-schema
+```
+
+Dry-run a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --dry-run --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --dry-run --arguments '{"database_id":"tasks-db-id","query":{"page_size":10}}'
+```
+
+Execute a tool call:
+
+```bash
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_GET_DATABASE --arguments '{"database_slug":"tasks"}'
+npx --package @notis_ai/cli@latest -- notis tools exec LOCAL_NOTIS_DATABASE_QUERY --arguments '{"database_id":"tasks-db-id","query":{"page_size":10}}'
+```
+
+Connect a missing toolkit:
+
+```bash
+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
+```

package/dist/base-skills/notis-cli/references/troubleshooting.md

@@ -0,0 +1,39 @@
+## Supporting commands
+
+- `npx --package @notis_ai/cli@latest -- notis whoami` — confirm which account and endpoint a command will target
+- `npx --package @notis_ai/cli@latest -- notis doctor` — verify CLI config, auth, routing, and API reachability before relying on the CLI
+- `npx --package @notis_ai/cli@latest -- notis describe <command...>` — get the exact command contract for first-class CLI commands
+
+## Troubleshooting
+
+### CLI returns `auth_expired` or `auth_missing`
+
+The profile's browser authorization has lapsed or was never granted. Run
+`notis login` (add `--profile <name>` when the failing profile is not the
+active one) and have the user approve the browser prompt. In JSON/agent mode
+the first hint is the exact command to run. Do not copy refresh tokens into
+commands or try to mint a credential yourself.
+
+If the profile is a `dev-*` one, the fix is to restart `./dev.sh` in the
+workspace it belongs to, or to switch to a real account profile.
+
+### Deploy fails with "network_error" or "fetch failed"
+
+Run `notis doctor` to verify the effective profile and endpoint. Read back the exact app ID,
+version and release state before retrying. An uncertain network response is not proof of rollback.
+There is no direct storage deployment path. Repair authentication when needed without changing the
+intended profile, then reconcile the previous outcome before starting a new release.
+
+Localhost backends are a Notis-developer test lane owned by `./dev.sh` and its lease-backed profile.
+Do not silently switch between that lane and a live account.
+
+### Health or tool-roundtrip errors
+
+Local scaffold/build and stub verification can run without an API connection (dependencies and
+browser tooling must already be available). `link`, `pull`, `create`, `list`, `deploy`, live verification
+and Store operations require the intended backend. Never bypass it.
+
+### Stale bundle in Portal after an update
+
+Every successful release gets a new integer deployment version. Read back that version, then use
+normal refresh/navigation to load it. Never overwrite or decrement an existing deployment version.