From 06feeb307aa85e4dee326b8e5fd48671e1c8e0b1 Mon Sep 17 00:00:00 2001
From: Jerop Kipruto <jerop@google.com>
Date: Wed, 1 Apr 2026 08:48:07 -0400
Subject: [PATCH] docs(plan): add FAQ section to Plan Mode documentation

This update adds an FAQ section to address common user questions:
- Explains why edits might still occur in Plan Mode due to global policies.
- Recommends using '/policies list' to verify active rules.
- Suggests enabling Alternate Screen Buffer and Incremental Rendering for a better UI experience during long planning sessions and to allow full plan expansion without 'Ctrl+O'.
---
 docs/cli/plan-mode.md | 40 ++++++++++++++++++++++++++++++++++++++++
 1 file changed, 40 insertions(+)

diff --git a/docs/cli/plan-mode.md b/docs/cli/plan-mode.md
index ad87bc591b..95d795334b 100644
--- a/docs/cli/plan-mode.md
+++ b/docs/cli/plan-mode.md
@@ -483,6 +483,46 @@ scripts or CI/CD pipelines), Plan Mode optimizes for automated workflows:
 gemini --approval-mode plan -p "Analyze telemetry and suggest improvements"
 ```
 
+## FAQ
+
+#### Why are edits still being made to my files while in Plan Mode?
+
+Plan Mode is designed to be read-only for your project's source code, but it
+still allows writing to your
+[plans directory](#custom-plan-directory-and-policies). If you see edits
+occurring outside of your plans directory, it is likely due to a custom policy
+rule that is "always active."
+
+Any rule that does not explicitly specify `modes` is considered active in all
+modes, including Plan Mode. To see which rules are currently active in your
+session, use the **`/policies list`** command.
+
+To prevent a rule from applying to Plan Mode, ensure you explicitly list the
+modes it _should_ apply to:
+
+```toml
+[[rule]]
+toolName = "replace"
+# ...
+decision = "allow"
+priority = 100
+# By omitting "plan", this rule will not be active in Plan Mode.
+modes = ["default", "autoEdit"]
+```
+
+#### How can I improve the UI experience for long planning sessions and plan review?
+
+For complex tasks that involve extensive research and long plan drafts, we
+recommend enabling the **Alternate Screen Buffer**. This preserves your terminal
+history, provides a more stable, flicker-free UI, and allows you to view
+expanded plans and tool outputs without needing to use the **`Ctrl+O`**
+shortcut:
+
+1.  Use the `/settings` command.
+2.  Set **Use Alternate Screen Buffer** (`ui.useAlternateBuffer`) to `true`.
+3.  (Optional) Set **Incremental Rendering** (`ui.incrementalRendering`) to
+    `true` for even smoother updates.
+
 [`plan.toml`]:
   https://github.com/google-gemini/gemini-cli/blob/main/packages/core/src/policy/policies/plan.toml
 [Conductor]: https://github.com/gemini-cli-extensions/conductor