docs: document definition of workspace activity (#16941)

closes: https://github.com/coder/coder/issues/16884

aligns the documentation with what users see when they adjust settings
and uses the [notion
discussion](https://www.notion.so/coderhq/Definitions-of-Workspace-Usage-Autostop-Dormancy-e7fa8ff782a948c19bbe4ef8315c26cb)
as a reference. This PR reflects current behavior from what I can tell.


[preview](https://coder.com/docs/@16884-define-activity/user-guides/workspace-scheduling#activity-detection)

---------

Co-authored-by: EdwardAngert <17991901+EdwardAngert@users.noreply.github.com>

docs/admin/templates/managing-templates/schedule.md

@@ -14,8 +14,7 @@ Template [admins](../../users/index.md) may define these default values:
   stops it.
 - [**Autostop requirement**](#autostop-requirement): Enforce mandatory workspace
   restarts to apply template updates regardless of user activity.
-- **Activity bump**: The duration of inactivity that must pass before a
-  workspace is automatically stopped.
+- **Activity bump**: The duration by which to extend a workspace's deadline when activity is detected (default: 1 hour). The workspace will be considered inactive when no sessions are detected (VSCode, JetBrains, Terminal, or SSH). For details on what counts as activity, see the [user guide on activity detection](../../../user-guides/workspace-scheduling.md#activity-detection).
 - **Dormancy**: This allows automatic deletion of unused workspaces to reduce
   spend on idle resources.
 

docs/user-guides/workspace-scheduling.md

@@ -37,18 +37,37 @@ days of the week your workspace is allowed to autostart.
 Use autostop to stop a workspace after a number of hours. Autostop won't stop a
 workspace if you're still using it. It will wait for the user to become inactive
 before checking connections again (1 hour by default). Template admins can
-modify the inactivity timeout duration with the
-[inactivity bump](#inactivity-timeout) template setting. Coder checks for active
-connections in the IDE, SSH, Port Forwarding, and coder_app.
+modify this duration with the **activity bump** template setting.
 
 ![Autostop UI](../images/workspaces/autostop.png)
 
-## Inactivity timeout
+## Activity detection
 
-Workspaces will automatically shut down after a period of inactivity. This can
-be configured at the template level, but is visible in the autostop description
+Workspaces automatically shut down after a period of inactivity. The **activity bump**
+duration can be configured at the template level and is visible in the autostop description
 for your workspace.
 
+### What counts as workspace activity?
+
+A workspace is considered "active" when Coder detects one or more active sessions with your workspace. Coder specifically tracks these session types:
+
+- **VSCode sessions**: Using code-server or VS Code with a remote extension
+- **JetBrains IDE sessions**: Using JetBrains Gateway or remote IDE plugins
+- **Terminal sessions**: Using the web terminal (including reconnecting to the web terminal)
+- **SSH sessions**: Connecting via `coder ssh` or SSH config integration
+
+Activity is only detected when there is at least one active session. An open session will keep your workspace marked as active and prevent automatic shutdown.
+
+The following actions do **not** count as workspace activity:
+
+- Viewing workspace details in the dashboard
+- Viewing or editing workspace settings
+- Viewing build logs or audit logs
+- Accessing ports through direct URLs without an active session
+- Background agent statistics reporting
+
+To avoid unexpected cloud costs, close your connections, this includes IDE windows, SSH sessions, and others, when you finish using your workspace.
+
 ## Autostop requirement
 
 > [!NOTE]
@@ -79,13 +98,13 @@ stopped due to the policy at the **start** of the user's quiet hours.
 
 ## Scheduling configuration examples
 
-The combination of autostart, autostop, and the inactivity timer create a
+The combination of autostart, autostop, and the activity bump create a
 powerful system for scheduling your workspace. However, synchronizing all of
 them simultaneously can be somewhat challenging, here are a few example
 configurations to better understand how they interact.
 
 > [!NOTE]
-> The inactivity timer must be configured by your template admin.
+> The activity bump must be configured by your template admin.
 
 ### Working hours
 
@@ -95,14 +114,14 @@ a "working schedule" for your workspace. It's pretty intuitive:
 If I want to use my workspace from 9 to 5 on weekdays, I would set my autostart
 to 9:00 AM every day with an autostop of 9 hours. My workspace will always be
 available during these hours, regardless of how long I spend away from my
-laptop. If I end up working overtime and log off at 6:00 PM, the inactivity
-timer will kick in, postponing the shutdown until 7:00 PM.
+laptop. If I end up working overtime and log off at 6:00 PM, the activity bump
+will kick in, postponing the shutdown until 7:00 PM.
 
-#### Basing solely on inactivity
+#### Basing solely on activity detection
 
 If you'd like to ignore the TTL from autostop and have your workspace solely
-function on inactivity, you can **set your autostop equal to inactivity
-timeout**.
+function on activity detection, you can set your autostop equal to activity
+bump duration.
 
 Let's say that both are set to 5 hours. When either your workspace autostarts or
 you sign in, you will have confidence that the only condition for shutdown is 5
@@ -114,10 +133,10 @@ hours of inactivity.
 > Dormancy is an Enterprise and Premium feature.
 > [Learn more](https://coder.com/pricing#compare-plans).
 
-Dormancy automatically deletes workspaces which remain unused for long
-durations. Template admins configure an inactivity period after which your
-workspaces will gain a `dormant` badge. A separate period determines how long
-workspaces will remain in the dormant state before automatic deletion.
+Dormancy automatically deletes workspaces that remain unused for long
+durations. Template admins configure a dormancy threshold that determines how long
+a workspace can be inactive before it is marked as `dormant`. A separate setting
+determines how long workspaces will remain in the dormant state before automatic deletion.
 
 Licensed admins may also configure failure cleanup, which will automatically
 delete workspaces that remain in a `failed` state for too long.