docs: standardize example formatting

Agents.md

@@ -9,6 +9,7 @@ Assume the reader is new to AI and needs detailed, step-by-step guidance.
 - Be specific and explicit. Avoid shorthand.
 - Explain terms in plain language.
 - Provide an example whenever possible.
+- Format chat or code examples consistently: use "Example prompt:" with a fenced ```text``` block for chat prompts, and "Example code:" with the right language for code.
 - Prefer checklists, short steps, and concrete outcomes.
 - Assume the reader is an expert engineer but a beginner at AI.
 
@@ -48,13 +49,19 @@ If you had to restart a chat and re-explain the goal, add a short reminder so th
 - "If placement is unclear, ask where the content should live before editing."
 
 ### Example Request
-"Read Agents.md and PRD.md first. Propose a plan. Then add chat mode guidance to docs/ai/usage-tokens.md (reader-facing) with hard examples. Do not add reader content to Agents.md."
+Example prompt:
+```text
+Read Agents.md and PRD.md first. Propose a plan. Then add chat mode guidance to docs/ai/usage-tokens.md (reader-facing) with hard examples. Do not add reader content to Agents.md.
+```
 
 ## Commit And Push After Repo Updates
 If you update any file in this repo, commit and push right away so other developers do not lose their local changes. If you are unsure, ask and confirm before pushing.
 
 ### Example Request
-"Read Agents.md and PRD.md first. Propose a plan, then update docs/ai/ios.md with step-by-step guidance and examples. If you add new files, update docs/ai/index.md."
+Example prompt:
+```text
+Read Agents.md and PRD.md first. Propose a plan, then update docs/ai/ios.md with step-by-step guidance and examples. If you add new files, update docs/ai/index.md.
+```
 
 ## Skills Sync
 This repo uses a skills manifest to standardize skills across developers.
@@ -70,7 +77,10 @@ This repo uses a skills manifest to standardize skills across developers.
 - Verification: (tests or checks)
 
 ## Example
+Example request:
+```text
 Goal: Add a troubleshooting section to the AI docs.
 Inputs: docs/ai/troubleshooting.md, docs/planning/AI-Docs-Plan.md
 Output: Updated troubleshooting section with 5 common issues.
 Verification: Manual review.
+```

README.md

@@ -34,7 +34,10 @@ These docs assume the reader is new to AI. Be explicit, explain terms, and inclu
 - Update the Skills Library with repo links.
 
 ### Example Change
-"Add a new skill link to docs/ai/skills.md and include a 2-sentence description."
+Example prompt:
+```text
+Add a new skill link to docs/ai/skills.md and include a 2-sentence description.
+```
 
 ## Next Steps
 - Add screenshots and short walkthrough videos.

docs/ai/android.md

@@ -14,6 +14,7 @@
 ### Example Prompt (VS Code)
 Open a Kotlin file and add:
 
+Example prompt:
 ```text
 // Create a Kotlin data class for a user profile with name and email.
 ```
@@ -29,7 +30,10 @@ Open a Kotlin file and add:
 - Prefer incremental changes over large rewrites.
 
 ### Example Request
-"Refactor this repository to reduce duplication. Keep the public API the same and list tests to update."
+Example prompt:
+```text
+Refactor this repository to reduce duplication. Keep the public API the same and list tests to update.
+```
 
 ## MCP For Android (High-Level)
 MCP tools can automate Android tasks like builds, tests, and diagnostics. The exact tool depends on your team setup.
@@ -41,9 +45,12 @@ When you identify the approved Android MCP tool(s), add:
 - Example prompts
 
 ### Starter Prompts
-- "Create a Kotlin data class and mapper for this API response."
+Example prompts:
-- "Write unit tests for this repository using JUnit."
+```text
-- "Refactor this file to reduce duplication without changing behavior."
+Create a Kotlin data class and mapper for this API response.
+Write unit tests for this repository using JUnit.
+Refactor this file to reduce duplication without changing behavior.
+```
 
 ## Android Troubleshooting
 - If suggestions are missing, confirm sign-in and access.

docs/ai/cross-platform.md

@@ -10,6 +10,7 @@ Agents define a structured workflow so tasks are broken into clear steps, with e
 3. Provide the inputs in a short, bounded request.
 
 ### Example Request
+Example prompt:
 
 ```text
 Goal: Improve readability in this module
@@ -23,13 +24,18 @@ Verification: No tests needed
 - 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."
+Ask: Quick Q and A or summaries.
+Edit: Targeted file edits with constraints.
+Plan: Planning only, no edits yet.
+Agent: Multi-step work across files or tools.
 
-Edit: Targeted file edits with constraints. Example: "In this file, extract a helper function for validation and keep behavior the same."
+Example prompts:
-
+```text
-Plan: Planning only, no edits yet. Example: "Provide a 5-step plan to split this class into smaller components. Wait for approval."
+Ask: Explain this error message and list the top 3 likely fixes.
-
+Edit: In this file, extract a helper function for validation and keep behavior the same.
-Agent: Multi-step work across files or tools. Example: "Refactor the service layer, update tests, run the test task, and summarize results."
+Plan: Provide a 5-step plan to split this class into smaller components. Wait for approval.
+Agent: Refactor the service layer, update tests, run the test task, and summarize results.
+```
 
 ### Request Template
 Use this structure to get consistent results:
@@ -42,14 +48,20 @@ Verification: <tests or checks>
 ```
 
 ## Prompting Patterns
-- Refactors: "Refactor this file to improve readability without changing behavior."
+Example prompts:
-- Tests: "Add unit tests for this service. Keep the existing public API."
+```text
-- Debugging: "Explain this error and list likely fixes in order."
+Refactors: Refactor this file to improve readability without changing behavior.
-- Understanding code: "Summarize what this module does and call out risks."
+Tests: Add unit tests for this service. Keep the existing public API.
+Debugging: Explain this error and list likely fixes in order.
+Understanding code: Summarize what this module does and call out risks.
+```
 
 ### Example: Too Broad vs Scoped
-Too broad: "Fix everything in this project."
+Example prompts:
-Scoped: "Refactor this file to remove duplication. Do not change behavior."
+```text
+Too broad: Fix everything in this project.
+Scoped: Refactor this file to remove duplication. Do not change behavior.
+```
 
 ## Plan-First Workflow
 1. Ask for a short plan.
@@ -58,7 +70,10 @@ Scoped: "Refactor this file to remove duplication. Do not change behavior."
 4. Verify with tests or review.
 
 ### Example Plan Request
-"Provide a 5-step plan to refactor this module. Wait for approval before edits."
+Example prompt:
+```text
+Provide a 5-step plan to refactor this module. Wait for approval before edits.
+```
 
 ## Connecting Skills
 - Use skills for tasks with known workflows.
@@ -71,7 +86,10 @@ Scoped: "Refactor this file to remove duplication. Do not change behavior."
 - Ask for summaries before asking for edits.
 
 ### Example Summary Request
-"Summarize the decisions so far in 6 bullets so I can start a new chat."
+Example prompt:
+```text
+Summarize the decisions so far in 6 bullets so I can start a new chat.
+```
 
 ## MCP (Model Context Protocol) - Cross-Platform Overview
 MCP is an open standard that lets tools and agents interact with real systems. In plain language, MCP lets the assistant "do" things (like run builds or fetch logs) instead of just talking about them.
@@ -91,7 +109,10 @@ Think of MCP as a set of safe, structured buttons the assistant can press. You a
 3. You ask for a summary and next steps.
 
 ### Example Prompt
-"Use the build MCP tool to run the build and summarize any errors."
+Example prompt:
+```text
+Use the build MCP tool to run the build and summarize any errors.
+```
 
 ### Where To Learn More
 - iOS examples: see [iOS Setup](ios.md)

docs/ai/governance.md

@@ -14,8 +14,11 @@
 - Non-approved proprietary information.
 
 ## Safe Prompt Examples
-- "Summarize this public API and propose tests."
+Example prompts:
-- "Refactor this function without changing behavior."
+```text
+Summarize this public API and propose tests.
+Refactor this function without changing behavior.
+```
 
 ## Redaction Tips
 - Remove secrets before pasting.
@@ -23,8 +26,11 @@
 - Use minimal context required for the task.
 
 ### Example Redaction
-Before: "User ID 928374 has email jane@company.com and token ABC123."
+Example:
-After: "User ID <USER_ID> has email <EMAIL> and token <TOKEN>."
+```text
+Before: User ID 928374 has email jane@company.com and token ABC123.
+After: User ID <USER_ID> has email <EMAIL> and token <TOKEN>.
+```
 
 ## Compliance Expectations
 - Follow org security policies and data handling rules.
@@ -34,4 +40,7 @@ After: "User ID <USER_ID> has email <EMAIL> and token <TOKEN>."
 If you are unsure about data classification, escalate before using AI.
 
 ### Example Question
-"Is it ok to share this log snippet with user IDs in Copilot?"
+Example prompt:
+```text
+Is it ok to share this log snippet with user IDs in Copilot?
+```

docs/ai/ios-xcodebuildmcp.md

@@ -13,9 +13,12 @@ Common uses include:
 - Capture build output so the assistant can summarize errors
 
 ### Example Requests
-- "Use XcodeBuildMCP to build the app and summarize any errors."
+Example prompts:
-- "Run tests with XcodeBuildMCP and list the failing tests."
+```text
-- "Build with XcodeBuildMCP and extract the first error message."
+Use XcodeBuildMCP to build the app and summarize any errors.
+Run tests with XcodeBuildMCP and list the failing tests.
+Build with XcodeBuildMCP and extract the first error message.
+```
 
 ## What It Can Do (Detailed Examples)
 Below are common tasks and how to ask for them. Adjust the wording to match your project.
@@ -23,32 +26,42 @@ Below are common tasks and how to ask for them. Adjust the wording to match your
 ### Build
 Goal: Run a build and get a short error summary.
 
-Example:
+Example prompt:
-"Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets."
+```text
+Use XcodeBuildMCP to build the app for the iOS simulator and summarize errors in 5 bullets.
+```
 
 ### Unit Tests
 Goal: Run unit tests and list failures.
 
-Example:
+Example prompt:
-"Run unit tests with XcodeBuildMCP and list failing tests with file names."
+```text
+Run unit tests with XcodeBuildMCP and list failing tests with file names.
+```
 
 ### UI Tests
 Goal: Run UI tests on a known simulator.
 
-Example:
+Example prompt:
-"Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures."
+```text
+Run UI tests with XcodeBuildMCP on iPhone 17 Pro Max (iOS 26.2) and list any failures.
+```
 
 ### Screenshots (UI Testing)
 Goal: Trigger a UI test that captures screenshots and then list the generated images.
 
-Example:
+Example prompt:
-"Run the UI test that captures screenshots and list the output paths."
+```text
+Run the UI test that captures screenshots and list the output paths.
+```
 
 ### Build Output Parsing
 Goal: Extract the first error for quick diagnosis.
 
-Example:
+Example prompt:
-"Build with XcodeBuildMCP and extract the first error message only."
+```text
+Build with XcodeBuildMCP and extract the first error message only.
+```
 
 ## Xcode 26.3 MCP Setup (Detailed)
 These steps reflect a common setup as of February 2026. Wording may vary slightly in release candidates.
@@ -109,8 +122,10 @@ Add to VS Code:
 2. Use Copilot Chat in agent mode for multi-step tasks.
 3. MCP tools appear as slash commands once discovered.
 
-Example:
+Example prompt:
-"Use XcodeBuildMCP to build and summarize errors. Then suggest fixes."
+```text
+Use XcodeBuildMCP to build and summarize errors. Then suggest fixes.
+```
 
 ### Tips And Caveats
 - Xcode must be running (or launchable) for MCP tools to respond.

docs/ai/ios.md

@@ -14,6 +14,7 @@
 ### Example Prompt (Xcode)
 Type this in a Swift file comment, then wait for a suggestion:
 
+Example prompt:
 ```text
 // Create a function that validates an email string.
 ```
@@ -38,6 +39,7 @@ Type this in a Swift file comment, then wait for a suggestion:
 ### Example Prompt (VS Code)
 Open a Swift file and add:
 
+Example prompt:
 ```text
 // Create a Swift struct for a user profile with name and email.
 ```
@@ -53,12 +55,18 @@ Open a Swift file and add:
 - Favor refactor or patch requests over full rewrites.
 
 ### Example Request
-"Refactor this SwiftUI view to reduce duplication. Do not change behavior. Provide a short diff summary."
+Example prompt:
+```text
+Refactor this SwiftUI view to reduce duplication. Do not change behavior. Provide a short diff summary.
+```
 
 ### Starter Prompts
-- "Create a SwiftUI view model for this screen and list its inputs and outputs."
+Example prompts:
-- "Write unit tests for this view model using XCTest."
+```text
-- "Refactor this view to reduce duplication without changing behavior."
+Create a SwiftUI view model for this screen and list its inputs and outputs.
+Write unit tests for this view model using XCTest.
+Refactor this view to reduce duplication without changing behavior.
+```
 
 ## MCP For iOS
 The detailed MCP setup and XcodeBuildMCP guidance is in a dedicated page:

docs/ai/overview.md

@@ -14,8 +14,11 @@ AI tools help with drafting, refactoring, explaining code, and accelerating rout
 - AI is not a source of truth. Always validate outputs with tests, code review, and domain checks.
 
 ### Example (Good vs Risky)
-Good: "Summarize this file and list the top 3 risks."
+Example prompts:
-Risky: "Rewrite this subsystem without review." (Always review large changes.)
+```text
+Good: Summarize this file and list the top 3 risks.
+Risky: Rewrite this subsystem without review.
+```
 
 ## GitHub Copilot Enterprise
 ### What It Is
@@ -91,17 +94,25 @@ Project example: See [README.md](../../README.md) for the start-here links and l
 ## 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."
+Ask: Quick questions, summaries, or explanations.
+Edit: Small, specific changes with constraints.
+Plan: A step-by-step plan before edits.
+Agent: Multi-step work across files with checks.
 
-Edit: Small, specific changes with constraints. Example: "Update this function to return nil when the input is empty. Keep behavior the same otherwise."
+Example prompts:
-
+```text
-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."
+Ask: Summarize this file in 5 bullets and list 2 risks.
-
+Edit: Update this function to return nil when the input is empty. Keep behavior the same otherwise.
-Agent: Multi-step work across files with checks. Example: "Refactor these two files, update unit tests, then summarize the changes and test results."
+Plan: Give me a 6-step plan to add caching to this service. Wait for approval before edits.
+Agent: Refactor these two files, update unit tests, then summarize the changes and test results.
+```
 
 ### Example: Chat vs Agents
-- Chat: "What does this function do?"
+Example prompts:
-- Agent: "Plan and refactor this module, then list tests to add."
+```text
+Chat: What does this function do?
+Agent: Plan and refactor this module, then list tests to add.
+```
 
 ## First Prompt (Safe)
 Try a small, safe prompt to confirm everything is working:
@@ -117,7 +128,10 @@ Summarize what this file does in 3 bullet points.
 - Avoid sharing secrets or sensitive data.
 
 ### Example: Safe Prompt
-"Refactor only the validation logic in this file. Keep behavior the same and list tests to update."
+Example prompt:
+```text
+Refactor only the validation logic in this file. Keep behavior the same and list tests to update.
+```
 
 ## Getting Help
 - Ask your team lead or the AI docs owner.

docs/ai/skills.md

@@ -12,7 +12,10 @@ Skills are reusable instructions and workflows that guide the assistant through
 Store skills in the team-approved skills directory for your environment. If you do not know the location, ask your team lead or check your internal setup docs.
 
 ### Example Question To Ask
-"Where is the approved skills directory for our team, and how do I add a new skill?"
+Example prompt:
+```text
+Where is the approved skills directory for our team, and how do I add a new skill?
+```
 
 ## Skills Governance And Sync
 To keep skills consistent across teams, use a central skills registry plus a per-project manifest. Avoid copying skills into every repo unless the skill is tightly coupled to the project.
@@ -61,7 +64,10 @@ skills:
 3. If needed, add a secondary skill and explain the handoff.
 
 ### Example Skill Request
-"Use swiftui-expert-skill to review this view for best practices. Then use webapp-testing to validate the web flow."
+Example prompt:
+```text
+Use swiftui-expert-skill to review this view for best practices. Then use webapp-testing to validate the web flow.
+```
 
 ## Current Skills (Add Repo Links)
 Add a short summary and link for each skill below.

docs/ai/troubleshooting.md

@@ -31,8 +31,11 @@
 - Provide a small example or expected output.
 
 ### Example Fix
-Bad: "Fix this."
+Example prompts:
-Better: "Refactor this function to remove duplication. Keep behavior the same."
+```text
+Bad: Fix this.
+Better: Refactor this function to remove duplication. Keep behavior the same.
+```
 
 ## What To Collect Before Escalation
 - Editor version and plugin version.
@@ -40,7 +43,10 @@ Better: "Refactor this function to remove duplication. Keep behavior the same."
 - Whether the issue is reproducible in another editor.
 
 ### Example Escalation Note
-"Copilot suggestions stopped in VS Code 1.92 after extension update. Restarted, still broken. Screenshot attached."
+Example note:
+```text
+Copilot suggestions stopped in VS Code 1.92 after extension update. Restarted, still broken. Screenshot attached.
+```
 
 ## When to Escalate
 - Account access issues after setup.

docs/ai/usage-tokens.md

@@ -27,7 +27,11 @@ Each chat keeps a running memory of what you said. That memory grows over time a
 When a chat gets long, ask for a short summary and start a new chat using that summary. This keeps context small and saves tokens.
 
 #### Example: Resetting A Long Chat
-1. In the long chat, ask: "Summarize the current state and decisions in 8 bullets."
+1. In the long chat, ask:
+
+```text
+Summarize the current state and decisions in 8 bullets.
+```
 2. Copy the summary into a new chat.
 3. Continue from there with a smaller context.
 
@@ -94,9 +98,12 @@ Refactor these two files, update tests, run the test task, and summarize results
 ```
 
 ### Example: Choosing A Model
-- Task: "Summarize this file in 5 bullets." Use a 0.33x or 1x model.
+Example prompts:
-- Task: "Refactor three files and update tests." Start with a 1x model. Move to 3x only if the 1x model fails.
+```text
-- Task: "Explain a confusing production issue with lots of context." Start with 1x, and only move up if needed.
+Summarize this file in 5 bullets. -> Use a 0.33x or 1x model.
+Refactor three files and update tests. -> Start with a 1x model. Move to 3x only if the 1x model fails.
+Explain a confusing production issue with lots of context. -> Start with 1x, and only move up if needed.
+```
 
 ### Quick Glossary
 - Model: The "brain" Copilot uses to answer your question.
@@ -110,14 +117,19 @@ Refactor these two files, update tests, run the test task, and summarize results
 - Ask for summaries before requesting changes.
 
 ### Before And After Example
-Bad: "Rewrite this entire module and update all tests."
+Example prompts:
-
+```text
-Better: "Only refactor the validation functions in this module. Keep existing behavior. List tests to update."
+Bad: Rewrite this entire module and update all tests.
+Better: Only refactor the validation functions in this module. Keep existing behavior. List tests to update.
+```
 
 ## Examples of Efficient Prompts
-- "Summarize this file in 5 bullets. Then propose a refactor plan."
+Example prompts:
-- "Update only the functions in this file that handle validation."
+```text
-- "List risks in this change and suggest tests to add."
+Summarize this file in 5 bullets. Then propose a refactor plan.
+Update only the functions in this file that handle validation.
+List risks in this change and suggest tests to add.
+```
 
 ## Daily and Monthly Budgeting Tips
 - Batch related questions in a single prompt.
@@ -136,8 +148,11 @@ Better: "Only refactor the validation functions in this module. Keep existing be
 - End sessions with a short summary for easy follow-up.
 
 ### Example: One Output Type
-Instead of: "Refactor the file, explain it, and add tests."
+Example prompts:
-Use: "Refactor the file only. Do not explain or add tests."
+```text
+Instead of: Refactor the file, explain it, and add tests.
+Use: Refactor the file only. Do not explain or add tests.
+```
 Then follow up with a separate request if needed.
 
 ## Red Flags That Burn Tokens Quickly