docs: fix technical inaccuracies and add undocumented feature coverage

docs/src/content/docs/concepts/context-and-artifacts.md

@@ -66,3 +66,23 @@ A typical workflow looks like this:
 - **Use the right branch.** Point the agent at a feature branch if you do not want changes landing directly on `main`.
 - **Check diffs before pushing.** The file browser shows exactly what changed -- use it.
 - **Combine with workflows.** Workflows like Bugfix or Spec-kit structure the agent's output so artifacts are consistent and easy to review.
+
+## Git operations
+
+After the agent finishes working, you can inspect and manage the resulting Git state directly from the session sidebar. The platform exposes several Git operations that help you review changes, configure remotes, and push code without leaving the UI.
+
+The agent handles most Git work (committing, branching, pulling) during a session. The operations below let you manage what happens *after* the agent is done.
+
+| Operation | What it does |
+|-----------|-------------|
+| **Repository status** | View cloned repositories, their current branch, default branch, and clone state (Cloning, Ready, or Failed). Expand a repository to see all available local branches. |
+| **Git status** | Check whether a repository has uncommitted changes, including counts of added and removed files and total lines changed. |
+| **Configure remote** | Set or change the remote URL for a repository in the session workspace. The branch defaults to `main`. You need write access to the target repository. |
+| **List branches** | View all branches available in a repository's workspace, including branches the agent created during the session. |
+| **Merge status** | Check whether changes can merge cleanly into a target branch. The platform reports conflicting files, local change counts, and whether the remote branch exists. |
+| **Push to remote** | Push the agent's commits to the configured remote repository. If auto-push is off, use this to deliver changes after reviewing them. |
+| **Abandon changes** | Discard all uncommitted changes in a repository, resetting it to the last committed state. This is irreversible. |
+
+:::note
+Some Git operations (push, abandon, create branch) are handled by the agent during the session. The UI operations listed above are available for post-session management and review.
+:::

docs/src/content/docs/concepts/integrations.md

@@ -2,7 +2,7 @@
 title: "Integrations"
 ---
 
-Integrations connect external services to the Ambient Code Platform, giving the AI agent access to tools like repository hosting, issue trackers, and document storage. Integrations are **global** -- once configured, they work across all your workspaces.
+Integrations connect external services to the Ambient Code Platform, giving the AI agent access to tools like repository hosting, issue trackers, and document storage. Integrations are **user-scoped** -- they are tied to your SSO identity and stored at the cluster level, so once configured, they are available across all your workspaces. MCP tools and runner secrets are workspace-scoped.
 
 ## Overview
 
@@ -27,7 +27,7 @@ GitHub integration lets the agent clone repositories, read pull requests, create
 ### GitHub App
 
 1. Navigate to **Integrations > GitHub**.
-2. Click **Connect with GitHub App**.
+2. Click **Connect to GitHub App**.
 3. You will be redirected to GitHub to authorize the Ambient Code Platform app.
 4. Select the organization and repositories you want to grant access to.
 5. Complete the OAuth flow -- you will be redirected back to the platform.
@@ -46,25 +46,12 @@ PATs do not auto-refresh. You will need to rotate them before they expire.
 
 GitLab integration provides the same repository access capabilities as GitHub.
 
-### Setup options
-
-| Method | Best for |
-|--------|---------|
-| **OAuth 2.0** (recommended) | Self-managed and SaaS GitLab instances with SSO. |
-| **Personal Access Token** | Quick setup or service accounts. |
-
-### OAuth
+### Setup
 
 1. Navigate to **Integrations > GitLab**.
-2. Click **Connect with GitLab**.
-3. Authorize the application in GitLab.
-4. You will be redirected back to the platform once complete.
-
-### Personal Access Token
-
-1. In GitLab, go to **Preferences > Access Tokens**.
-2. Create a token with `read_repository` and `write_repository` scopes.
-3. Paste the token in **Integrations > GitLab** on the platform.
+2. Optionally enter your **GitLab instance URL** if you use a self-managed instance (defaults to `https://gitlab.com`).
+3. In GitLab, go to **Preferences > Access Tokens** and create a token with `read_repository` and `write_repository` scopes.
+4. Paste the token and click **Connect**.
 
 ## Jira
 
@@ -73,27 +60,29 @@ Jira integration enables the agent to read issues, create tickets, and update st
 ### Setup
 
 1. Navigate to **Integrations > Jira**.
-2. Click **Connect with Jira**.
-3. Complete the OAuth 2.0 authorization flow in Atlassian.
+2. Provide your **Jira instance URL** (e.g., `https://yourcompany.atlassian.net`).
+3. Enter the **email address** associated with your Jira account.
+4. Generate an [API token](https://id.atlassian.com/manage-profile/security/api-tokens) from your Atlassian account and paste it into the **API Token** field.
+5. Click **Connect**.
 
 Ensure your Atlassian account has the required project permissions.
 
-## Google Workspace
+## Google Drive
 
-Google Workspace integration allows the agent to access Google Drive, Calendar, and Gmail.
+Google Drive integration allows the agent to access files stored in your Google Drive.
 
 ### Setup
 
-1. Navigate to **Integrations > Google Workspace**.
-2. Click **Connect with Google Workspace**.
-3. Sign in with your Google account and grant the requested permissions.
+1. Navigate to **Integrations > Google Drive**.
+2. Click **Connect Google Drive**.
+3. Sign in with your Google account and grant the requested Drive permissions.
 4. You will be redirected back to the platform once authorization is complete.
 
 ## Troubleshooting
 
 | Symptom | Likely cause | Fix |
 |---------|-------------|-----|
-| Status stays **Disconnected** after setup | OAuth callback did not complete | Retry the connection flow; check for pop-up blockers. |
+| Status stays **Disconnected** after setup | Authorization callback did not complete | Retry the connection flow; check for pop-up blockers. |
 | Token expired errors in sessions | PAT reached its expiry date | Generate a new token and update the integration. |
 | "Insufficient permissions" in agent logs | Token scope is too narrow | Recreate the token with the required scopes. |
 | Jira actions fail | Network or permission issue | Verify the Jira URL is reachable from the cluster and that your account has project access. |

docs/src/content/docs/concepts/scheduled-sessions.md

@@ -0,0 +1,76 @@
+---
+title: "Scheduled Sessions"
+---
+
+A **scheduled session** is a recurring AI agent execution that runs automatically on a cron schedule. Each scheduled session is backed by a Kubernetes CronJob that creates a new agentic session at every scheduled interval, using a preconfigured session template. You can use scheduled sessions to automate repetitive tasks such as nightly code reviews, dependency scans, or periodic issue triage -- without manually creating a session each time.
+
+## Create a scheduled session
+
+Open a workspace and navigate to the **Scheduled Sessions** tab. Click **New Scheduled Session** to open the creation dialog.
+
+| Setting | Description | Default |
+|---------|------------|---------|
+| **Name** | A display name for the schedule (up to 50 characters). | Auto-generated |
+| **Schedule** | How often the session runs. Choose a preset or enter a custom cron expression. | Every hour (`0 * * * *`) |
+| **Initial prompt** | The prompt sent to the agent when each session starts. This defines the task the agent performs on every run. | *(required)* |
+| **Runner type** | The runtime environment for the agent. | Claude Agent SDK |
+| **Model** | Which AI model the agent uses. | Claude Sonnet 4.5 |
+
+### Schedule presets
+
+The creation dialog offers common presets so you do not need to write cron expressions manually:
+
+| Preset | Cron expression |
+|--------|----------------|
+| Every hour | `0 * * * *` |
+| Daily at 9:00 AM | `0 9 * * *` |
+| Every weekday at 9:00 AM | `0 9 * * 1-5` |
+| Weekly on Monday | `0 9 * * 1` |
+| Custom | Enter any valid 5-field cron expression |
+
+When you select or enter a schedule, the dialog shows a human-readable description and previews the next three run times.
+
+### Session template
+
+Each scheduled session stores a **session template** that defines the configuration for every session it creates. The template includes the initial prompt, model, runner type, temperature (0.7), max tokens (4,000), and timeout (300 seconds). To change these values after creation, update the scheduled session.
+
+## Manage schedules
+
+You can manage scheduled sessions from the **Scheduled Sessions** tab or from the actions menu on each row.
+
+| Operation | What it does |
+|-----------|-------------|
+| **Suspend** | Pauses the schedule. No new sessions are created until you resume. Existing running sessions are not affected. |
+| **Resume** | Reactivates a suspended schedule. The next session is created at the next scheduled time. |
+| **Trigger now** | Immediately creates a one-off session from the schedule's template, regardless of the cron timing. The triggered session is linked to the schedule as a child job. |
+| **Update** | Changes the schedule, display name, or session template. You can update any combination of fields. |
+| **Delete** | Permanently removes the schedule and its associated Kubernetes CronJob. Child jobs are cleaned up in the background. |
+
+### Schedule status
+
+Each scheduled session displays one of two statuses:
+
+- **Active** -- the schedule is running and creates sessions at the configured interval.
+- **Suspended** -- the schedule is paused and does not create new sessions.
+
+## View run history
+
+Click a scheduled session name to view its detail page, which lists all sessions created by that schedule. Each run is a standard agentic session that follows the same lifecycle as manually created sessions (Pending, Creating, Running, Completed, Failed, or Stopped). The scheduled sessions list also shows the **Last Run** column, indicating when the most recent session was created.
+
+The platform retains history for the last 5 successful runs and 3 failed runs per schedule.
+
+## Concurrency and reliability
+
+Scheduled sessions use a **forbid-concurrent** policy: if a session from a previous run is still active when the next scheduled time arrives, the new run is skipped. This prevents overlapping agent executions on the same task.
+
+If the platform is unavailable at the scheduled time, the CronJob has a 5-minute starting deadline. Runs that miss this window are skipped entirely.
+
+## Use cases
+
+Scheduled sessions work well for tasks that benefit from regular, unattended execution:
+
+- **Nightly code health reports** -- run a daily scan that reviews code quality, flags potential issues, and generates a summary.
+- **Recurring dependency scans** -- check for outdated or vulnerable dependencies on a weekly cadence.
+- **Periodic issue triage** -- have the agent review and categorize new issues every morning before the team starts work.
+- **Automated documentation updates** -- regenerate or validate documentation against code changes on a schedule.
+- **Regression checks** -- run a suite of verification prompts after each nightly build to catch regressions early.

docs/src/content/docs/concepts/sessions.md

@@ -11,10 +11,10 @@ Click **New Session** inside a workspace. The creation dialog lets you configure
 | Setting | Description | Default |
 |---------|------------|---------|
 | **Display name** | A label for the session. | Auto-generated |
-| **Model** | Which Claude model to use: Claude Sonnet 4.5, Claude Opus 4.6, Claude Opus 4.5, or Claude Haiku 4.5. | Claude Sonnet 4.5 |
+| **Model** | Which AI model to use. Available models: Claude Sonnet 4.5, Claude Opus 4.5, Claude Haiku 4.5, Gemini 2.5 Flash (generally available); Claude Opus 4.6, Claude Sonnet 4.6, Gemini 2.5 Pro (feature-gated, visible only when enabled for your workspace). | Claude Sonnet 4.5 |
 | **Temperature** | Controls response randomness (0 = deterministic, 2 = highly creative). | 0.7 |
-| **Max tokens** | Maximum output length per response (100 -- 8,000). | 4,000 |
-| **Timeout** | Hard limit on total session duration (60 -- 1,800 seconds). | 300 seconds |
+| **Max tokens** | Maximum output length per response. The UI enforces a range of 100--8,000, but the platform API accepts other values. | 4,000 |
+| **Timeout** | Hard limit on total session duration. The UI enforces a range of 60--1,800 seconds, but the platform API accepts other values. A separate `inactivityTimeout` field controls how long a session can remain idle before the platform auto-stops it; if omitted, it falls back to the project-level setting and then to a 24-hour default. | 300 seconds |
 
 After the session is created, you can attach repositories and select a workflow from the session sidebar. See [Context & Artifacts](../context-and-artifacts/) and [Workflows](../workflows/) for details.
 
@@ -62,20 +62,42 @@ At any moment the agent is in one of three states:
 
 If the agent is heading in the wrong direction while it is still **Working**, you can send a new message at any time. The agent will read your message after its current tool call finishes and adjust course.
 
+## Human-in-the-loop
+
+Sometimes the agent needs your input before it can continue. When this happens, the agent pauses and presents a **question panel** in the chat. The agent's status changes to `waiting_input` until you respond. After you submit your answer, the agent resumes work automatically.
+
+### Question types
+
+The question panel supports three input styles depending on what the agent needs to know:
+
+- **Free-text** -- an open text field for you to type any response.
+- **Single-select** -- a list of radio buttons when the agent offers predefined choices. An **Other** option lets you type a custom answer if none of the choices fit.
+- **Multi-select** -- a list of checkboxes when the agent wants you to pick one or more options.
+
+### Multiple questions at once
+
+When the agent has several questions, the panel displays them in a **tabbed interface**. Each tab shows one question, and a counter tracks how many you have answered. After you select an answer the panel auto-advances to the next tab. You can click any tab to revisit a previous answer before submitting.
+
+Once all questions are answered, click **Submit** to send your responses and let the agent continue.
+
 ## Session operations
 
 | Operation | What it does |
 |-----------|-------------|
 | **Stop** | Gracefully halts the agent. You can resume later. |
 | **Resume** | Resumes a stopped session from where it left off. |
 | **Clone** | Creates a new session with the same configuration and repos -- useful for trying a different approach. Chat history is not copied. |
-| **Export** | Exports the chat history in one of three formats: Markdown, PDF, or Google Drive. |
+| **Export** | Downloads session data and offers Markdown or PDF export. If the session is running and Google Drive is connected, you can also save directly to your Drive. |
 | **Delete** | Permanently removes the session and its data. |
 
+## Feedback
+
+You can rate any agent response with a thumbs-up or thumbs-down button that appears alongside messages in the chat. Clicking either button opens a feedback modal where you can optionally add a comment explaining what went well or what could be improved. The platform sends your rating to Langfuse for observability and quality tracking, automatically associating it with the session, message, user, active workflow, and trace so that teams can analyze agent performance over time.
+
 ## Tips for effective sessions
 
 - **Be specific in your first message.** A clear prompt saves back-and-forth. Instead of "fix the bug," try "the login endpoint in `auth.go` returns 500 when the token is expired -- fix the error handling."
 - **Attach the right repos.** The agent can only see code that has been added as context.
-- **Pick the right model.** Sonnet 4.5 is fast and cost-effective for most tasks. Opus 4.6 excels at complex multi-step reasoning.
+- **Pick the right model.** Sonnet 4.5 is fast and cost-effective for most tasks. Opus 4.6 excels at complex multi-step reasoning (if enabled for your workspace).
 - **Use workflows for structured tasks.** If there is a workflow that matches your goal (bug fix, triage, spec writing), attach it from the session sidebar to give the agent a proven plan.
 - **Review tool calls.** Expanding tool-use blocks lets you verify what the agent actually did before merging its changes.