docs: add chat mode guidance

Agents.md

@@ -25,6 +25,33 @@ Keep this file aligned with PRD, README, and docs/planning/AI-Docs-Plan.md when
 - Plan a refactor before making edits.
 - Summarize and assess risks across files.
 
+## Chat Types In Copilot (Ask, Edit, Agent, Plan)
+These are the four ways you can run a Copilot chat. Pick the lightest mode that matches the job.
+
+### Ask
+Use this for questions, explanations, summaries, or quick guidance. It does not change files.
+
+Example:
+"Explain what this function does and list the top 3 risks."
+
+### Edit
+Use this for small, specific file edits with clear constraints.
+
+Example:
+"In this file, rename `UserProfile` to `AccountProfile` and update all references. Do not change behavior."
+
+### Plan
+Use this to get a step-by-step plan before any edits happen.
+
+Example:
+"Give me a 5-step plan to refactor this module. Wait for approval before making changes."
+
+### Agent
+Use this for multi-step tasks that span files, require checks, or need a structured workflow.
+
+Example:
+"Refactor these three files to remove duplication, update tests, then summarize the changes and test results."
+
 ## How to Use Agents
 1. Define the outcome in one sentence.
 2. List inputs (files, context, constraints).

PRD.md

@@ -42,6 +42,7 @@ Teams need a clear, zero-knowledge onboarding path for AI tools, setup, and usag
 - Assume readers are new to AI.
 - Use step-by-step instructions and plain language.
 - Provide examples for key workflows.
+- Explain chat modes (Ask, Edit, Plan, Agent) with concrete examples.
 
 ## Definition Of Done (Doc Updates)
 - New markdown files are linked in docs/ai/index.md.

README.md

@@ -13,8 +13,9 @@ These docs assume the reader is new to AI. Be explicit, explain terms, and inclu
 
 ## How to Use
 1. Start at the [AI Docs Index](docs/ai/index.md).
-2. Follow the iOS or Android setup guide.
-3. Review skills and token usage guidance.
+2. Read the overview to learn chat modes (Ask, Edit, Plan, Agent).
+3. Follow the iOS or Android setup guide.
+4. Review skills and token usage guidance.
 
 ## Local Workflow
 - Edit files in docs/ai.

docs/ai/cross-platform.md

@@ -22,6 +22,15 @@ Verification: No tests needed
 - Use agents for multi-step tasks like refactors, doc audits, or migrations.
 - Use chat for quick questions or one-off explanations.
 
+## Chat Modes In Copilot
+Ask: Quick Q and A or summaries. Example: "Explain this error message and list the top 3 likely fixes."
+
+Edit: Targeted file edits with constraints. Example: "In this file, extract a helper function for validation and keep behavior the same."
+
+Plan: Planning only, no edits yet. Example: "Provide a 5-step plan to split this class into smaller components. Wait for approval."
+
+Agent: Multi-step work across files or tools. Example: "Refactor the service layer, update tests, run the test task, and summarize results."
+
 ### Request Template
 Use this structure to get consistent results:
 

docs/ai/overview.md

@@ -48,6 +48,17 @@ Copilot is an AI coding assistant that integrates with editors and chats to help
 - Skills: Reusable knowledge or workflows the assistant can apply.
 - Tokens: The usage units that track AI consumption.
 
+## Chat Types In Plain English
+Copilot chat has four modes. Pick the smallest one that fits the task.
+
+Ask: Quick questions, summaries, or explanations. Example: "Summarize this file in 5 bullets and list 2 risks."
+
+Edit: Small, specific changes with constraints. Example: "Update this function to return nil when the input is empty. Keep behavior the same otherwise."
+
+Plan: A step-by-step plan before edits. Example: "Give me a 6-step plan to add caching to this service. Wait for approval before edits."
+
+Agent: Multi-step work across files with checks. Example: "Refactor these two files, update unit tests, then summarize the changes and test results."
+
 ### Example: Chat vs Agents
 - Chat: "What does this function do?"
 - Agent: "Plan and refactor this module, then list tests to add."

docs/ai/usage-tokens.md

@@ -135,6 +135,15 @@ If each step is done with a 3x model and a growing chat context, your token use
 - Standardize request templates.
 - Agree on when to use agents vs chat.
 
+### Use The Right Chat Mode
+Using the lightest chat mode for the job keeps outputs smaller and cheaper.
+
+Example:
+Ask: "Summarize this file in 5 bullets."
+Plan: "Give me a 5-step plan to refactor this module. Wait for approval."
+Edit: "Update this function to handle empty input. Keep behavior the same otherwise."
+Agent: "Refactor these two files, update tests, and summarize results."
+
 ## Quick Checklist
 - Is the request specific and scoped?
 - Do I need the whole file or just a section?

docs/planning/AI-Docs-Plan.md

@@ -7,6 +7,7 @@ Keep the planning view of the docs hierarchy, scope, and future work. This is a
 - Assume readers are new to AI.
 - Use step-by-step instructions.
 - Provide at least one example per major section.
+- Explain chat modes (Ask, Edit, Plan, Agent) in plain language with examples.
 
 ## Current Docs Location
 - docs/ai/