docs: clarify AFK timeout configuration

[archit-goyal]

Summary

• explain how users can change the AFK timeout from the ActivityWatch config folder
• document the aw-watcher-afk.toml file and commented default setting behavior
• add the current default timeout and poll_time values to the AFK watcher configuration docs

Context

This addresses confusion surfaced in ActivityWatch/activitywatch#1288 and related idle/lock-screen questions by making the AFK watcher configuration path discoverable from the FAQ and configuration reference.

Validation

• Verified defaults against aw-watcher-afk/aw_watcher_afk/config.py
• Verified config filename behavior against aw_core.config.load_config_toml
• git diff --check
• make SPHINXBUILD=.venv/bin/sphinx-build html exits 0; existing upstream/environment warnings remain unrelated to these changed files

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3cb1d8c6ee

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[chatgpt-codex-connector]

Point users to the aw-watcher-afk subdirectory

In the normal aw-qt flow, “Open config folder” opens the ActivityWatch config root, while load_config_toml("aw-watcher-afk", ...) stores this file under the component directory as aw-watcher-afk/aw-watcher-afk.toml. With the current wording, users following these lines will look for aw-watcher-afk.toml directly in the opened folder and may not find it; please include the per-component subdirectory in the path.

Useful? React with 👍 / 👎.

[greptile-apps]

Greptile Summary

This PR improves discoverability of AFK timeout configuration by adding default values to the existing config reference and adding a new FAQ entry that walks users through editing aw-watcher-afk.toml.

• configuration.rst: Adds the default timeout (180 s) and poll_time (5 s) values inline, and adds a paragraph clarifying that the settings live in aw-watcher-afk.toml (not the web UI), with a valid :ref: cross-reference to the platform-specific config directory docs.
• faq.rst: Inserts a new "Can I change when ActivityWatch marks me as AFK?" entry immediately after the existing AFK explanation; the troubleshooting note at the end is a useful addition.
• Neither changed section mentions that the watcher must be restarted after editing the config file — users who save the file and see no change will be left without a resolution path.

Confidence Score: 3/5

Documentation-only change that is accurate and well-placed, but omits the restart step that is essential for the config change to take effect.

The AFK config FAQ and configuration reference additions are factually correct and the cross-references resolve properly. However, both the FAQ answer and the configuration section direct users to edit a file without telling them that the watcher process must be restarted afterwards. Any user who follows the instructions as written will edit and save the file, see no change in behaviour, and be left without a next step — the exact confusion the PR aims to resolve.

src/faq.rst — the new FAQ answer needs a restart instruction before it can fully resolve the user confusion it targets.

Important Files Changed

Filename	Overview
src/faq.rst	Adds a new FAQ entry explaining how to change the AFK timeout; content is accurate and placement is logical, but omits the required restart step after editing the config file.
src/configuration.rst	Adds default values (180 s / 5 s) and a paragraph pointing users to aw-watcher-afk.toml; the :ref: cross-reference to config-directory resolves correctly, but also lacks a note about restarting the watcher after edits.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[User wants to change AFK timeout] --> B[Open ActivityWatch tray menu]
    B --> C[Choose 'Open config folder']
    C --> D[Navigate to aw-watcher-afk folder]
    D --> E[Open aw-watcher-afk.toml]
    E --> F{Setting commented out?}
    F -- Yes --> G[Remove leading # from timeout line]
    F -- No --> H[Edit timeout value directly]
    G --> I[Set timeout = desired seconds]
    H --> I
    I --> J[Save the file]
    J --> K[Restart aw-watcher-afk / ActivityWatch]
    K --> L[New AFK timeout is active]

Loading

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
flowchart TD
    A[User wants to change AFK timeout] --> B[Open ActivityWatch tray menu]
    B --> C[Choose 'Open config folder']
    C --> D[Navigate to aw-watcher-afk folder]
    D --> E[Open aw-watcher-afk.toml]
    E --> F{Setting commented out?}
    F -- Yes --> G[Remove leading # from timeout line]
    F -- No --> H[Edit timeout value directly]
    G --> I[Set timeout = desired seconds]
    H --> I
    I --> J[Save the file]
    J --> K[Restart aw-watcher-afk / ActivityWatch]
    K --> L[New AFK timeout is active]

Loading

_{Reviews (1): Last reviewed commit: "docs: clarify AFK timeout configuration" | Re-trigger Greptile}

[greptile-apps]

Missing restart instruction after config change

Neither the FAQ answer nor the configuration.rst section mentions that aw-watcher-afk must be restarted for the new timeout value to take effect. A user who edits aw-watcher-afk.toml, saves it, and then resumes working will see no change in behaviour and will likely assume they edited the wrong file or made an error. A one-sentence note — e.g. "After saving the file, restart ActivityWatch (or just the AFK watcher) for the change to take effect." — would close this gap. The same note is absent from the configuration.rst addition.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

[archit-goyal]

Addressed the automated feedback in 59fdcf6 by clarifying the aw-watcher-afk/aw-watcher-afk.toml path and adding the restart step after config edits.