riverbankcms 0.1.0 → 0.2.2

package/dist/cli/init-docs/content/workflow-remote-setup.md

@@ -1,6 +1,9 @@
 # Remote Site, Key, and User Access Setup
 
-This SDK project can sync content once it has a site ID, dashboard URL, and site-scoped management key. Creating the remote site, issuing keys, and granting dashboard user access are admin operations.
+This SDK project can sync content once it has a site ID, dashboard URL, and
+site-scoped management key. The authenticated Riverbank CLI can create a site
+and link project credentials for the signed-in account. Additional user access
+remains a dashboard operation.
 
 ## Check the Plan
 
@@ -18,18 +21,50 @@ riverbankcms setup plan --env=remote --json
 
 ## Authority Model
 
-- Dashboard/admin users can create sites, issue site-scoped management keys, and grant dashboard access.
-- Approved CMS repo scripts can do the same when run with service-role/admin credentials.
-- SDK management keys can verify access and sync content/config for one site. They cannot create sites, issue new keys, or grant user access.
+- The authenticated Riverbank CLI can create sites and issue project
+  credentials for the signed-in account through `sites create`, `link`, and
+  `init`.
+- Dashboard administrators can manage sites, issue credentials, and grant
+  access to additional users.
+- SDK management keys can verify access and sync content/config for one site.
+  They cannot create sites or grant other users access.
 
-Do not put platform-admin, service-role, or user-session credentials in an SDK site repository.
+The CLI stores its refresh session in the OS credential store when available.
+It never puts account sessions, platform-admin credentials, or service-role
+credentials in an SDK site repository.
+
+Production account OAuth is deliberately rollout-disabled. Use the staging (or
+local) account environment while that rollout is disabled; replace
+`<account-environment>` with `production` only after production account access
+has been explicitly enabled.
 
 ## Remote Setup Lifecycle
 
-1. Create or choose the remote site from the dashboard/admin surface.
-2. Generate a management key for that site.
-3. Grant the site owner or editor dashboard access from the dashboard/admin surface.
-4. Add the remote SDK variables to `.env.local`:
+1. Sign in to the account environment:
+
+```bash
+riverbankcms login --account-env=<account-environment>
+```
+
+2. Create a site or choose one visible to the signed-in account:
+
+```bash
+riverbankcms sites list --account-env=<account-environment>
+riverbankcms sites create --account-env=<account-environment> --name "My Site" --yes
+```
+
+3. Link the project. `--preview` includes preview routes and a preview
+   credential; use `--no-preview` to omit them:
+
+```bash
+riverbankcms link --project . --account-env=<account-environment> --site <site-id> --preview
+```
+
+For a new directory, use `riverbankcms init` instead; it scaffolds, links,
+initializes docs, and builds the complete project.
+
+4. Add the remote SDK variables to `.env.local` when linking an existing
+   project manually:
 
 ```bash
 RIVERBANK_REMOTE_SITE_ID=your-site-id
@@ -48,4 +83,25 @@ riverbankcms push --env=remote --dry-run
 
 ## Existing Sites and Users
 
-For an existing remote site, copy its site ID and create a fresh site-scoped management key if the old one is missing or should be rotated. Associate existing users with the site through the dashboard/admin surface. If the user does not exist yet, invite or create them through that approved flow rather than through the Riverbank CLI.
+For an existing remote site, use `riverbankcms link` so the CLI issues the
+needed site-scoped credentials and writes only ignored project env files.
+Associate additional users with the site through the dashboard/admin surface.
+If local work fails after the site is created, keep the site and resume with
+the reported `riverbankcms init --resume <directory>` command after fixing the
+local error.
+
+## Post-deployment revalidation
+
+`init` scaffolds `/api/revalidate` but does not register a webhook or write a
+webhook secret. Once the deployed site has a public HTTPS origin, activate
+revalidation explicitly:
+
+```bash
+riverbankcms webhooks setup \
+  --env=remote \
+  --url=https://www.example.com/api/revalidate \
+  --yes
+```
+
+Until then, the generated site’s ISR interval is the freshness fallback. Keep
+the one-time webhook secret in the deployment environment, not source control.