@blotout/qinto-cli 0.1.15 → 0.1.16

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