@north-light/cli 0.3.436 → 0.3.437

package/dist/builtin-memory/crouter-sdk/guides/apps-on-northlight.md

@@ -25,7 +25,7 @@ The example app texts you, so it asks for the `sms` provider's `sms:send` scope.
 
 Open `https://account.northlight.ai/signup` and create your account. Signup texts a confirmation code to your phone, and that text is sent over iMessage, so use a phone number that has iMessage. A number that cannot receive iMessage gets "We couldn't send the text", and retrying does not help. One phone number belongs to one account.
 
-Install the CLI (`npm i -g @north-light/cli`). Joining needs `crtr` 0.3.434 or later (older versions need `crtr sys daemon stop` first and fail if a viewer is open); `crtr --version` shows yours.
+Install the CLI (`npm i -g @north-light/cli`). Joining needs `crtr` 0.3.436 or later (older versions need `crtr sys daemon stop` first and fail if a viewer is open); `crtr --version` shows yours.
 
 Then join your laptop to the account:
 
@@ -98,10 +98,10 @@ An app can only ask for scopes it has been given. It starts with `crtr:llm` and
 
 ```bash
 crtr cloud apps asks --app-id <client id> --source sms
-crtr cloud apps set-scopes --app-id <client id> --scope crtr:llm --scope crtr:act --scope sms:send
+crtr cloud apps set-scopes --app-id <client id> --add sms:send
 ```
 
-`asks` lists, per source, what the app may ask for and whether it asks now; `sms:send` is under providers, with the consent sentence "Send you text messages from Northlight's number". `set-scopes` replaces the whole list, so repeat `--scope` for every scope you want (`crtr:act` needs `crtr:llm`). Without `sms:send` the consent page does not offer it and `providers.call` for `sms` is refused. Take scope strings from `asks` and do not invent them.
+`asks` lists, per source, what the app may ask for and whether it asks now; `sms:send` is under providers, with the consent sentence "Send you text messages from Northlight's number". `set-scopes --add` adds to the list the app has now and leaves the rest alone; `--remove` drops a scope that is in it (`crtr:act` needs `crtr:llm`, so drop both together). `crtr cloud apps asks --app-id <client id> --requested` shows exactly what the app asks for now. To replace the whole list instead, repeat `--scope` for every scope you want, or pass `--clear`. The console's **What it asks for** tab does the same with an **Add permissions** search. Without `sms:send` the consent page does not offer it and `providers.call` for `sms` is refused. Take scope strings from `asks` and do not invent them.
 
 If your app does not work without a provider being set up first (Doppel needs Context), name it:
 
@@ -251,9 +251,9 @@ Your Northlight chat agent at `https://chat.northlight.ai` can run the same comm
 | `crtr cloud apps get --app-id <id>` | Shows the registration. |
 | `crtr cloud apps update --app-id <id> --name … / --origin … / --logo … / --justification …` | Changes the profile fields you pass. |
 | `crtr cloud apps set-redirect-uris --app-id <id> --redirect-uri …` | Replaces the whole redirect URI list; repeat the flag for each. |
-| `crtr cloud apps asks --app-id <id>` | Lists what an app may ask for, with whether it asks now. Large sources such as `integrations` print as a count. Narrow it with `--query sms:send`, `--source sms`, `--group providers\|apps\|agents\|space`, or `--query <text>`; for example `crtr cloud apps asks --app-id <id> --source sms`. |
-| `crtr cloud apps set-scopes --app-id <id> --scope …` | Replaces the scope list. Repeat `--scope` for every scope; `--clear` empties it; `crtr:act` needs `crtr:llm`. |
-| `crtr cloud apps set-requires --app-id <id> --provider …` | Names providers your app does not work without (for example `context`); `--clear` empties it. |
+| `crtr cloud apps asks --app-id <id>` | Lists what an app may ask for, with whether it asks now. Large sources such as `integrations` print as a count. Narrow it with `--query sms:send`, `--source sms`, `--group providers\|apps\|agents\|space`, or `--query <text>`; `--requested` lists only what the app asks for now. For example `crtr cloud apps asks --app-id <id> --source sms`. |
+| `crtr cloud apps set-scopes --app-id <id> --add … --remove …` | Edits the scope list the app has now; repeat `--add`/`--remove` per scope. Removing a scope that is not in the list is refused. Or replace the whole list with repeated `--scope`; `--clear` empties it. `crtr:act` needs `crtr:llm`. |
+| `crtr cloud apps set-requires --app-id <id> --add … --remove …` | Edits the providers your app does not work without (for example `context`). Or replace the list with repeated `--provider`; `--clear` empties it. |
 | `crtr cloud apps keys add --app-id <id> --jwk '<public JWK>'` | Adds a signing key beside any existing one. Answers `created: false` if that key is already on the app. `keygen --app` calls it for you. |
 | `crtr cloud apps keys list --app-id <id>` | Lists the keys with their `kid` and `active` or `retired` status. |
 | `crtr cloud apps keys retire --app-id <id> --kid <kid>` | Retires a key so it no longer signs in. |
@@ -286,6 +286,22 @@ crtr cloud apps set-listing --app-id <client id> --listed true --price free \
 
 `--text-welcome` is one or two plain sentences, at most 120 characters, with no links. Agents can install an app for people by text only while it is listed (`--listed true`). `crtr cloud apps install --app-id <client id>` sends the signed-in person a text with the install link. Run it only for yourself or for a person who asked: it sends a real text.
 
+### Developing alongside your live app
+
+Once your app is live, you can keep developing on your laptop against production while the live app keeps running. There are two ways to do it.
+
+**Add your localhost callback to the live app.** This is the simplest, and it is fine for most apps. An app can hold several redirect URIs, and each sign-in returns to the one its request names, so your deployed server and your laptop can both sign people in at once:
+
+```bash
+crtr cloud apps set-redirect-uris --app-id <client id> \
+  --redirect-uri https://app.example.com/auth/callback \
+  --redirect-uri http://localhost:3000/auth/callback
+```
+
+`set-redirect-uris` replaces the whole list, so name the live URI too. Give your laptop its own signing key beside the deployed one (`keygen --app` adds it; an app holds at most 2 active keys), so you never copy the production private key to your laptop. Both servers share everything else: the same people, their grants, the app's space and the scopes the app asks for. A scope you add while developing changes what the live app asks of everyone. The origin, `login_start_url` and run notice URL each hold one value, so they keep pointing at the deployed app.
+
+**Register a separate development app.** Do this when you are changing what the app asks for, or need data and grants of its own that live people never touch. Run `crtr cloud apps register` again with a name such as "Texty (dev)", a `localhost` origin and redirect URI, and its own key. It starts in testing and stays there, so only you and the testers you add can sign in, and it never appears in the marketplace. Point your laptop's environment file at its client id. This is how Google recommends separating tiers too: a separate project for development and for production.
+
 ### Rotate keys
 
 Add a new key beside the old one, switch, verify with a real sign-in, then retire the old key: