PRDCT-692: make the Apps section survive the launch — OIDC entry, the Google console as it is, two build paths

_data/navigation.yml

@@ -127,6 +127,10 @@ items:
             title: Authentication
           - url: /data-apps/publish-and-share/
             title: Publish and share
+          - url: /data-apps/operate/
+            title: Operate and update
+          - url: /data-apps/troubleshooting/
+            title: Troubleshooting
       - url: /data-apps/reference/
         title: Reference
       - url: /data-apps/streamlit/

src/content/docs/data-apps/getting-started.md

@@ -101,12 +101,14 @@ Prefer to set the app up yourself, without the chat? Manual creation lives on th
 
 ![The app's configuration page: the Overview tab with Authentication and a Git Repository section, plus the App Info panel showing backend version, size, auto-sleep, and App ID](/data-apps/build-in-ui-config.png)
 
-6. Click **Deploy App**. A short wizard asks for the **backend size** and an **inactivity timeout**, then deploys the app. (The same wizard runs on **Redeploy**.)
+6. Click **Deploy App**. A short wizard asks for the **backend version**, the **backend size** and an **inactivity timeout**, then deploys the app. (The same wizard runs on **Redeploy**.)
 
-![The deploy/redeploy wizard: backend size and inactivity timeout](/data-apps/deploy-timeout-backedsize.png)
+![The deploy/redeploy wizard: backend version, backend size and inactivity timeout](/data-apps/deploy-timeout-backedsize.png)
 
 7. When the status turns **Active**, click **Open App** to open it at its public URL. Use **Redeploy** to apply any later config change; see [App actions](/data-apps/reference/#app-actions).
 
+From here on, the app is something you run rather than something you build: [Operate and update an app](/data-apps/operate/) covers shipping changes, secrets, sleeping and versions.
+
 ---
 
 **Next:** [Build an app locally →](/data-apps/build-locally/)

src/content/docs/data-apps/index.md

@@ -23,12 +23,14 @@ Dashboards and reports, internal tools, data narratives, configurators, and agen
 
 ## Two ways to build
 
-- **[Build with Kai](/data-apps/getting-started/)** — describe the app in plain language and Kai reads your data, builds a live draft you preview and refine, and publishes when you're ready. No coding needed — the walkthrough takes about 10 minutes. The same **Create App** screen also offers [manual creation](/data-apps/getting-started/#create-an-app-manually) if you'd rather configure the app yourself.
-- **[Build locally](/data-apps/build-locally/)** — develop with your own tools and Git account, use the [AI Kit](/ai/ai-kit/) coding-assistant plugins, and sync the app to your project. For developers who want full control — that page covers how Python/JS development works day to day.
+- **[Build with Kai](/data-apps/getting-started/)** — describe the app in plain language and Kai reads your data, builds a live draft you preview and refine, and publishes when you're ready. No coding needed — the walkthrough takes about 10 minutes. The same **Create App** screen also offers [manual creation](/data-apps/getting-started/#create-an-app-manually) if you'd rather configure the app yourself. **You need:** a Keboola project. Nothing else.
+- **[Build locally](/data-apps/build-locally/)** — develop with your own tools and Git account, use the [AI Kit](/ai/ai-kit/) coding-assistant plugins, and sync the app to your project. For developers who want full control — that page covers how Python/JS development works day to day. **You need:** a Git account and somewhere to host the repository; about half an hour the first time.
+
+Both routes end up in a Git repository, either one Keboola manages for the app or one you host. [Two ways to run an app](/data-apps/what-are-apps/#two-ways-to-run-an-app) explains what each gives you, including why the Kai builder appears on one and not the other.
 
 ## Run and share
 
-Every app has its own settings page in **Apps**: who can open it ([Authentication](/data-apps/authentication/) — public, password, or your company SSO), its URL and how to [publish and share](/data-apps/publish-and-share/) it, and operational settings like backend size and auto-sleep ([Reference](/data-apps/reference/)). Deploying and redeploying is one click; logs are right on the app's detail.
+Every app has its own settings page in **Apps**: who can open it ([Authentication](/data-apps/authentication/) — public, password, or your company SSO), its URL and how to [publish and share](/data-apps/publish-and-share/) it, and operational settings like backend size and auto-sleep ([Reference](/data-apps/reference/)). Deploying and redeploying is one click; logs are right on the app's detail. Once it's live, [Operate and update an app](/data-apps/operate/) covers the day-to-day work and [Troubleshooting](/data-apps/troubleshooting/) covers the days it goes wrong.
 
 ## Beyond dashboards
 

src/content/docs/data-apps/operate.md

@@ -0,0 +1,62 @@
+---
+title: Operate and update an app
+slug: 'data-apps/operate'
+description: "Day-to-day work on a deployed Keboola app: read its state, ship a code change, change settings, stop and start it, rotate a secret, delete it."
+---
+
+Once an app is deployed, everything you do with it starts on its page under **Apps**. This page walks through the routine tasks; [Apps reference](/data-apps/reference/) has the full list of settings and actions.
+
+Deploying, starting, stopping, deleting and setting secrets also work from a terminal with `kbagent`; drafts, copying and rollback are UI-only. The `kbagent` commands below all take `--project <alias>`, the name you gave the project when you [connected it](/cli/concepts/#connections-and-config), and `--app-id`, the numeric **App ID** from the **App Info** panel.
+
+## Read the app's state
+
+The header shows the app's status and the one or two actions that make sense for it: **Deploy App** for an app that has never run, **Start App** for a stopped one, **Open App** and **Redeploy App** for a running one, and **Modify with Kai** on apps Kai built. The **⋯** menu holds the rest, and its contents depend on the state too: **Copy app**, **Automate** (add it to a flow), **Debug mode** and **Delete app** are always there, with **Suspend app** on a running app.
+
+The tabs below the header split the app's life into views: **Overview** (the app's settings and its App URL), **Advanced Settings** (environment variables and secrets, theme, data mappings), **All Runs** (every start attempt), **Terminal Logs** (stdout and stderr while it runs), **Versions** (the configuration history), and **Drafts** while Kai has a draft open. The **App Info** panel on the right shows the backend version and size, the auto-sleep timeout, the last change, the owner, and the App ID.
+
+## Ship a code change
+
+How depends on where the code lives; see [Two ways to run an app](/data-apps/what-are-apps/#two-ways-to-run-an-app).
+
+- **Kai built the app.** Click **Modify with Kai** and describe the change. Kai works in a draft with its own live preview; when you're happy, publish it to production. The production app keeps serving the old version until you do. Details: [Build your first app with Kai](/data-apps/getting-started/#how-drafts-become-production).
+- **Your own repository.** Push to the branch set under **Git Repository** on the app's page, then click **Redeploy App**. Keboola clones that branch again, runs your repository's `keboola-config/setup.sh` if it has one, and starts the new version. Push alone changes nothing. The app can report **stopped** for a moment while it restarts, so give it a reload before you worry.
+
+From a terminal, a redeploy is `kbagent data-app deploy --project <alias> --app-id <id> --wait`.
+
+## Change settings
+
+Authentication, secrets, environment variables and the Git branch are edited on the app's page; the backend size and the inactivity timeout are chosen in the deploy wizard each time you deploy or start the app. Nothing you edit on the page takes effect until the app runs again, so after saving click **Redeploy App** on a running app or **Start App** on a stopped one. The wizard asks for backend version, backend size and inactivity timeout every time; keep the current values unless you mean to change them.
+
+Secrets deserve one note: after you save one, the field is masked, and revealing it shows an encrypted value starting with `KBC::ProjectSecure`. That's the secret stored [encrypted](/extend/encryption/), not a replacement, and the rest of the prefix depends on which cloud your stack runs on. To rotate it, paste the new value over the encrypted one and redeploy. How secret names become environment variables: [Secrets](/data-apps/reference/#secrets).
+
+From a terminal: `kbagent data-app secrets-set --project <alias> --app-id <id> --secret '#API_KEY=…'`, then `kbagent data-app deploy`.
+
+## Stop, start, sleep
+
+- **Sleeping** is automatic. After the inactivity timeout (five minutes to 24 hours, set in the deploy wizard) the app suspends; the next visit wakes it and shows a short **waking up** page. You pay only for time the app is awake or waiting to suspend.
+- **Stopping** is deliberate: **⋯ → Suspend app** stops the container and keeps the configuration, so the app stops serving until you bring it back with **Start App**. Use this when an app should be off for days; sleeping already covers being idle overnight.
+- **Redeploy App** restarts a running app with the current configuration and, for apps on your own repository, the current branch head.
+
+From a terminal: `kbagent data-app stop` and `kbagent data-app start`, both with `--project` and `--app-id`.
+
+Sleep and wake behaviour in detail, including the wakeup error page: [Sleep and resume](/data-apps/reference/#sleep-and-resume).
+
+## See what changed, and go back
+
+The **Versions** tab lists the app's configuration history: who changed what, and when. An app is a component configuration like any other, so you can compare versions and [roll back](/components/#rollback-version) to an earlier one. A rollback changes the configuration only, so redeploy afterwards to put the old settings back in service.
+
+Code changes are tracked separately from configuration: for a Kai-built app they're in the Builder's chat and drafts, and for your own repository they're in your Git history.
+
+## Copy, automate, delete
+
+- **Copy app** duplicates the configuration into a new app, so you can try a change without touching the one people use.
+- **Automate** adds the app to a flow, for example to redeploy it after the data it reads has been refreshed.
+- **Delete app** stops the app and deletes its configuration. The App URL stops working immediately; there is no undo. The terminal equivalent, `kbagent data-app delete`, says the same thing in its own words: cascade, irreversible.
+
+## When something is off
+
+Start with [Troubleshooting](/data-apps/troubleshooting/): where the logs are, what the common start failures look like, and what to do about each.
+
+---
+
+**Next:** [Troubleshooting →](/data-apps/troubleshooting/)

src/content/docs/data-apps/publish-and-share.md

@@ -10,7 +10,7 @@ Once your app is ready, publish it and share the link with the people who need i
 
 An app is "published" once it's deployed and reachable at its URL, with the right people able to open it:
 
-1. **Deploy the app.** From the app's configuration, click **Deploy App**. A short wizard asks for the **backend size** and an **inactivity timeout**, then deploys it; when the status turns **Active**, it's served at its public URL. See [App actions](/data-apps/reference/#app-actions).
+1. **Deploy the app.** From the app's configuration, click **Deploy App**. A short wizard asks for the **backend version**, the **backend size** and an **inactivity timeout**, then deploys it; when the status turns **Active**, it's served at its public URL. See [App actions](/data-apps/reference/#app-actions).
 
    ![The Deploy App wizard: Backend Version (Python/JS), Backend Size, and Inactivity Timeout, with a Deploy App button](/data-apps/deploy-timeout-backedsize.png)
 
@@ -25,10 +25,10 @@ Share the app URL — found on the app's **Overview** tab (the **App URL** block
 
 ## Manage a deployed app
 
-From the app's header you can **Modify with Kai**, **Open App**, and **Start App** / **Redeploy App** depending on its state. The **⋯** menu holds the rest — **Copy app**, **Automate** (add it to a flow), **Debug mode**, and **Delete app**. See [App actions](/data-apps/reference/#app-actions) in the reference.
+From the app's header you can **Modify with Kai**, **Open App**, and **Start App** / **Redeploy App** depending on its state. The **⋯** menu holds the rest: **Copy app**, **Automate** (add it to a flow), **Debug mode** and **Delete app**, plus **Suspend app** while the app is running. [Operate and update an app](/data-apps/operate/) walks through each one.
 
 ![The app header with Modify with Kai / Open App / Start App and the ⋯ menu open showing Copy app, Automate, Debug mode, and Delete app](/data-apps/app-actions-menu.png)
 
 ---
 
-**Next:** [Apps reference →](/data-apps/reference/)
+**Next:** [Operate and update an app →](/data-apps/operate/)

src/content/docs/data-apps/reference.md

@@ -181,9 +181,16 @@ Manage a deployed app from its actions menu.
 
 - **Deploy App** — starts the app. Once the deployment job finishes, open the app's public URL with **Open App**.
 - **Open App** — opens a new window with your app.
-- **Redeploy** — apply changes made in the app configuration (they take effect only after a redeploy).
-- **Suspend App** — stops the app. The container stops and the URL is no longer available, but the configuration is kept.
-- **Delete App** — stops the deployment and deletes its configuration.
+- **Redeploy App** — apply changes made in the app configuration (they take effect only after a redeploy).
+- **Start App** — brings a stopped app back with the same settings.
+- **Modify with Kai** — opens the Builder, on apps Kai built.
+- **Suspend app** — stops the app. The container stops and the app no longer serves, but the configuration is kept.
+- **Copy app** — duplicates the configuration into a new app.
+- **Automate** — adds the app to a flow.
+- **Debug mode** — runs the app with extra diagnostics.
+- **Delete app** — stops the deployment and deletes its configuration.
+
+Which of these the header and the **⋯** menu offer depends on the app's state. [Operate and update an app](/data-apps/operate/) walks through them in the order you meet them.
 
 ## Sleep and resume
 
@@ -201,7 +208,7 @@ If something goes wrong, a **wakeup error** page appears; click **Show More** fo
 
 ![Wakeup error](/data-apps/proxy-error-wakeing-up.png)
 
-When you **Deploy** or **Redeploy**, a wizard prompts for the backend size and the auto-sleep timeout (five minutes to 24 hours; default five minutes).
+When you **Deploy** or **Redeploy**, a wizard prompts for the backend version, the backend size and the auto-sleep timeout (five minutes to 24 hours; default five minutes).
 
 ![Deploy timeout and backend size](/data-apps/deploy-timeout-backedsize.png)