@blotout/qinto-cli 0.1.15 → 0.1.17

package/README.md

@@ -128,6 +128,48 @@ qinto app publish --site example.com          # …and install it on a site
 qinto app status my-app --site example.com    # desired vs deployed state
 ```
 
+### Get a developer organization
+
+**A team is not an organization.** A team owns sites and installs apps; an organization owns the apps you write. Membership in a
+team — even as its owner — gives you nothing in any organization, and switching the active team does not change that. Until your
+account belongs to an organization, `qinto app register` refuses with one of:
+
+```
+This credential has no organizations. Log in with `qinto login` first.
+Organization <name> is not available to this credential.
+```
+
+Neither is fixed by logging in again. `qinto whoami` says which case you are in — it prints an `Organizations:` block listing each
+organization and your role in it, and prints no such block when you belong to none.
+
+**The CLI cannot create an organization; the Qinto platform does.** Open it in a browser and click **Developer** in the sidebar,
+or go straight to the Developer area:
+
+| Environment | Developer area |
+| --- | --- |
+| `production` | `https://portal.qinto.io/developer` |
+| `sandbox` | `https://portal.qinto.tech/developer` |
+
+**Opening that page is the whole step.** The first visit creates a personal organization named after your email address and makes
+you its owner — nothing is approved, granted, or provisioned by anyone else. Use the organization switcher at the top of the
+Developer sidebar to rename it, or **Create organization** to add another (one per customer or product, say).
+
+To publish under an organization that already exists — a company's, rather than your own — one of its owners invites you under
+**Developer → Organization members** and you accept the emailed link. An organization cannot be joined by naming its id.
+
+Back in the terminal the organization appears immediately: the CLI reads it from the API on every call, so **no new login is
+needed**. Pass it by id or name with `--org`.
+
+```sh
+qinto whoami                                    # confirm the Organizations block now lists it
+qinto app register ./my-app --org "Acme Inc."
+```
+
+If `whoami` still lists no organization when you know you belong to one, the login is too narrow rather than the organization
+missing: your account identity needs the `profile` scope and every `qinto app` command needs `developer`. A plain `qinto login`
+requests both, a login narrowed with `--scopes` may not, and `whoami` names it — `Authenticated with an OAuth token without the
+profile scope.` Run `qinto login --reauthorize` and grant them.
+
 ### Scaffold — `qinto app create [dir]`
 
 Asks for the app name, proposes a slug derived from it that you confirm or replace, and asks which template to start from. It
@@ -168,8 +210,9 @@ declares only its build tooling.
 
 ### Register — `qinto app register [dir]`
 
-Registers the slug under an organization. `create --register` calls it for you; run it directly to register an app you scaffolded
-earlier or wrote by hand. The slug is immutable and unique inside the organization.
+Registers the slug under an organization — see [Get a developer organization](#get-a-developer-organization) when you have none.
+`create --register` calls it for you; run it directly to register an app you scaffolded earlier or wrote by hand. The slug is
+immutable and unique inside the organization.
 
 The slug, name, and description come from `qinto.app.jsonc` — the one in `dir`, or the one in the current directory when you pass
 no `dir`. Pass `--slug`, `--name`, and `--description` only for an app that has no manifest yet; alongside a manifest they are
@@ -220,8 +263,19 @@ goes caller → the site worker's broker → callee, each app in its own worker.
 apps are mounted; a `private` one is refused with `403 forbidden` until you approve it under **App-to-app approvals** on the
 callee's page, exactly as a site manager does on a deployed site.
 
+**An app you call but do not have is mocked for you.** When a mounted app's `rpc.calls` names a slug nothing mounts, `dev`
+scaffolds `mocks/<slug>.ts` inside the calling app — one exported function per function it exposes — and mounts it under that
+slug. `ctx.apps.call('resend', 'send', args)` then takes the real path: caller → broker → the mock's own worker, with no `if` in
+your code and nothing to change when the real app arrives beside you.
+
+If you are logged in, the mock is typed: `dev` fetches the app's published rpc contract, writes it next to the stub as
+`mocks/<slug>.rpc.json`, generates `mocks/<slug>.types.ts` from it, and the platform validates every call and result against it —
+so a mock that lies about its shape fails locally the way the real app would. Commit all three files; the sidecar keeps the mock
+typed offline and for anyone else who checks the app out. Without a contract (not logged in, or the app is unpublished) the stub
+takes and returns `unknown` and the terminal says why.
+
 An app folder added or removed while `dev` is running is not picked up — it says so and asks for a restart. A save inside a
-mounted app rebuilds that app alone.
+mounted app rebuilds that app and every mock alongside it.
 
 Declared `server.schedules` fire on their own while `dev` runs — at the cron's minute, in UTC, with `scheduledTime` set to that
 instant, exactly as the deployed sweep dispatches them. Each schedule on the app's console page also has a **Run now** button,
@@ -489,7 +543,7 @@ digest is what the version is finalized against. Every field and option is docum
 | `variables` | Up to 32 per-install settings a team fills in — `plain` or `secret`, `text`/`password`/`toggle`. |
 | `appVariables` | Up to 16 settings you fill in once for the whole app with `qinto app var set` / `qinto app secret set`. |
 | `endpoints` | Up to 16 HTTP routes served at `https://<site>/app/<slug><path>`. |
-| `rpc` | Functions this app `exposes` to other apps, and the ones it `calls` on them. |
+| `rpc` | Functions this app `exposes` to other apps, and the ones it `calls` on them. Each exposed one is built with `defineRpc`, and publish uploads its argument and result schemas as the version's contract. |
 | `events` | The push topics this app broadcasts to every app on the site. |
 | `ui` | `dir` holding the built panel, and the `build` command that produces it. |
 | `install` | `multiple: true` to let a site install the app more than once, plus a `labelHint`. |