docs: expand beginner guidance

PRD.md

@@ -38,6 +38,11 @@ Teams need a clear, zero-knowledge onboarding path for AI tools, setup, and usag
 - Skills inventory and usage guidance.
 - Token usage guidance and troubleshooting.
 
+## Content Requirements
+- Assume readers are new to AI.
+- Use step-by-step instructions and plain language.
+- Provide examples for key workflows.
+
 ## Assumptions
 - The org has a Copilot Enterprise subscription.
 - Editors are standard across teams (Xcode and VS Code).

README.md

@@ -2,6 +2,9 @@
 
 This repo contains the source markdown for a Confluence-ready AI documentation set for mobile development. It is designed to be beginner-friendly and easy to keep current.
 
+## Audience
+These docs assume the reader is new to AI. Be explicit, explain terms, and include examples where possible.
+
 ## Structure
 - [AI Docs Index](docs/ai/index.md)
 - [Agents](Agents.md)
@@ -29,6 +32,9 @@ This repo contains the source markdown for a Confluence-ready AI documentation s
 - Add platform-specific examples when possible.
 - 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."
+
 ## Next Steps
 - Add screenshots and short walkthrough videos.
 - Assign owners per section.

docs/ai/android.md

@@ -11,6 +11,13 @@
 3. Confirm Copilot is enabled in VS Code.
 4. Run a simple prompt to verify suggestions appear.
 
+### Example Prompt (VS Code)
+Open a Kotlin file and add:
+
+```text
+// Create a Kotlin data class for a user profile with name and email.
+```
+
 ### Verification Steps
 - Open a Kotlin file and start a small function.
 - Confirm inline suggestions appear.
@@ -21,6 +28,9 @@
 - Request unit tests for services and view models.
 - 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."
+
 ### Starter Prompts
 - "Create a Kotlin data class and mapper for this API response."
 - "Write unit tests for this repository using JUnit."

docs/ai/cross-platform.md

@@ -9,6 +9,15 @@ Agents define a structured workflow so tasks are broken into clear steps, with e
 2. Choose a workflow that matches your task.
 3. Provide the inputs in a short, bounded request.
 
+### Example Request
+
+```text
+Goal: Improve readability in this module
+Inputs: src/foo/Bar.kt, keep behavior the same
+Output: A small refactor and a short summary
+Verification: No tests needed
+```
+
 ### When to Use Agents vs Chat
 - Use agents for multi-step tasks like refactors, doc audits, or migrations.
 - Use chat for quick questions or one-off explanations.
@@ -29,12 +38,19 @@ Verification: <tests or checks>
 - 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."
+Scoped: "Refactor this file to remove duplication. Do not change behavior."
+
 ## Plan-First Workflow
 1. Ask for a short plan.
 2. Approve or adjust the plan.
 3. Ask for targeted changes.
 4. Verify with tests or review.
 
+### Example Plan Request
+"Provide a 5-step plan to refactor this module. Wait for approval before edits."
+
 ## Connecting Skills
 - Use skills for tasks with known workflows.
 - Combine multiple skills when a task spans domains.
@@ -44,3 +60,6 @@ Verification: <tests or checks>
 - Keep prompts small and scoped.
 - Reuse context from earlier steps instead of repeating it.
 - 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."

docs/ai/governance.md

@@ -22,9 +22,16 @@
 - Replace real identifiers with placeholders.
 - Use minimal context required for the task.
 
+### Example Redaction
+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.
 - Use AI as assistance, not authority.
 
 ## Ownership
 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?"

docs/ai/index.md

@@ -2,6 +2,18 @@
 
 Welcome. This section is the entry point for AI enablement. It assumes no prior knowledge and is safe to follow step-by-step.
 
+## Who This Is For
+You can be an expert engineer and still be new to AI. This guide explains every step and includes examples to keep you from guessing.
+
+## How To Use This Guide
+Follow the steps in order. Do not skip ahead if this is your first time.
+
+### Example Path (New iOS Engineer)
+1. Read [AI Overview](overview.md)
+2. Follow [iOS Setup](ios.md)
+3. Skim [Usage and Token Budgeting](usage-tokens.md)
+4. Return to [Cross-Platform AI Usage](cross-platform.md)
+
 ## If You Are New
 1. Read the overview to understand terms and guardrails.
 2. Follow the setup guide for your platform.

docs/ai/ios.md

@@ -11,6 +11,13 @@
 3. Confirm Copilot is enabled in Xcode.
 4. Run a simple prompt to verify suggestions appear.
 
+### Example Prompt (Xcode)
+Type this in a Swift file comment, then wait for a suggestion:
+
+```text
+// Create a function that validates an email string.
+```
+
 ### Verification Steps
 - Open a Swift file and start a small function.
 - Confirm inline suggestions appear.
@@ -28,6 +35,13 @@
 3. Confirm Copilot is enabled in VS Code.
 4. Run a simple prompt to verify suggestions appear.
 
+### Example Prompt (VS Code)
+Open a Swift file and add:
+
+```text
+// Create a Swift struct for a user profile with name and email.
+```
+
 ### Verification Steps
 - Open a Swift file and type a short function signature.
 - Confirm inline suggestions appear.
@@ -38,6 +52,9 @@
 - Request tests or sample usages for view models.
 - 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."
+
 ### Starter Prompts
 - "Create a SwiftUI view model for this screen and list its inputs and outputs."
 - "Write unit tests for this view model using XCTest."

docs/ai/overview.md

@@ -13,6 +13,10 @@ AI tools help with drafting, refactoring, explaining code, and accelerating rout
 - AI is a productivity assistant that can suggest code, summarize context, and propose solutions.
 - 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."
+Risky: "Rewrite this subsystem without review." (Always review large changes.)
+
 ## GitHub Copilot Enterprise
 ### What It Is
 Copilot is an AI coding assistant that integrates with editors and chats to help you write and understand code.
@@ -27,6 +31,11 @@ Copilot is an AI coding assistant that integrates with editors and chats to help
 3. Verify Copilot is enabled in editor settings.
 4. Run a quick prompt to validate it works.
 
+### What You Should See
+- A Copilot icon or status indicator in your editor.
+- Inline code suggestions as you type.
+- A chat panel that can answer questions.
+
 ### Quick Access Checklist
 - GitHub account is linked to the org.
 - SSO or required auth flow is completed.
@@ -39,6 +48,10 @@ 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.
 
+### Example: Chat vs Agents
+- 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:
 
@@ -52,6 +65,9 @@ Summarize what this file does in 3 bullet points.
 - Verify outputs with tests and review.
 - 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."
+
 ## Getting Help
 - Ask your team lead or the AI docs owner.
 - Use the escalation guidance in [Troubleshooting and FAQ](troubleshooting.md).

docs/ai/skills.md

@@ -11,6 +11,9 @@ Skills are reusable instructions and workflows that guide the assistant through
 ## Skills Directory
 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?"
+
 ## 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.
 
@@ -38,6 +41,11 @@ skills:
 2. The script pulls the registry and copies required skills to your local skills directory.
 3. Restart your editor if required.
 
+### Example Sync Command
+```bash
+./scripts/sync-skills.sh
+```
+
 ## How to Download Existing Skills
 1. Locate the skill in the team or org repository.
 2. Add the skill to your local skills directory following team guidance.
@@ -52,6 +60,9 @@ skills:
 2. Provide the inputs that skill expects.
 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."
+
 ## Current Skills (Add Repo Links)
 Add a short summary and link for each skill below.
 

docs/ai/troubleshooting.md

@@ -5,6 +5,12 @@
 - No suggestions: verify Copilot is enabled in the editor.
 - Plugin missing: confirm the plugin or extension is installed.
 
+### Example: No Suggestions
+1. Confirm you are signed in.
+2. Confirm the extension is enabled.
+3. Open a new file and type a simple prompt.
+4. Restart the editor if needed.
+
 ## Quick Diagnostic Flow
 1. Confirm account access and SSO.
 2. Confirm plugin or extension is installed and enabled.
@@ -24,11 +30,18 @@
 - Tighten the prompt with scope and context.
 - Provide a small example or expected output.
 
+### Example Fix
+Bad: "Fix this."
+Better: "Refactor this function to remove duplication. Keep behavior the same."
+
 ## What To Collect Before Escalation
 - Editor version and plugin version.
 - Error messages or screenshots.
 - 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."
+
 ## When to Escalate
 - Account access issues after setup.
 - Consistent failures across multiple editors.

docs/ai/usage-tokens.md

@@ -3,12 +3,86 @@
 ## How Tokens Are Spent
 Tokens are consumed based on input length, output length, and tool usage. Long prompts and repeated context increase usage quickly.
 
+### Simple Example
+If you paste a large file and ask for a rewrite, you pay for:
+1. The pasted file (input tokens)
+2. The model reasoning about it
+3. The full rewritten output (output tokens)
+
+If you do that several times in a row, you can burn a large portion of your daily or monthly allowance quickly.
+
+## Chat Context (Why New Chats Matter)
+Each chat keeps a running memory of what you said. That memory grows over time and gets sent back to the model, which costs more tokens and can slow responses.
+
+### Best Practice
+- Start a new chat for each topic or task.
+- Do not keep one chat open for weeks and switch subjects.
+
+### Why This Matters
+- Bigger context = more tokens used per message.
+- Larger contexts can slow response time.
+- Old context can confuse the model and reduce answer quality.
+
+### Use Summaries To Reset Context
+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."
+2. Copy the summary into a new chat.
+3. Continue from there with a smaller context.
+
+## Model Choice Matters (Plain Language)
+Think of each model as a different "speed and cost" setting. Some models are cheap and fast. Some are smarter but cost more for the same question. If you pick a higher-cost model, you can burn through your daily or monthly allowance much faster.
+
+### Models Available (From The Copilot Picker)
+- Auto (10% discount)
+- GPT-4.1 (0x)
+- GPT-4o (0x)
+- GPT-5 mini (0x)
+- Grok Code Fast 1
+- Claude Haiku 4.5 (0.33x)
+- Claude Opus 4.5 (3x)
+- Claude Opus 4.6 (3x)
+- Claude Sonnet 4 (1x)
+- Claude Sonnet 4.5 (1x)
+- Gemini 2.5 Pro (1x)
+- Gemini 3 Flash (Preview) (0.33x)
+- Gemini 3 Pro (Preview) (1x)
+- GPT-5 (1x)
+- GPT-5-Codex (Preview) (1x)
+- GPT-5.1 (1x)
+- GPT-5.1-Codex (1x)
+- GPT-5.1-Codex-Max (1x)
+- GPT-5.1-Codex-Mini (Preview) (0.33x)
+- GPT-5.2 (1x)
+- GPT-5.2-Codex (1x)
+
+### Practical Guidance (Plain Language)
+- Use cheaper models for summaries, quick questions, and small edits.
+- Use expensive models only when the task is truly complex or high-stakes.
+- If you are unsure, start with Auto or a 0.33x or 1x option, then move up only if needed.
+
+#### Example: Choosing A Model
+- Task: "Summarize this file in 5 bullets." Use a 0.33x or 1x model.
+- Task: "Refactor three files and update tests." Start with a 1x model. Move to 3x only if the 1x model fails.
+- Task: "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.
+- Multiplier: A cost factor. Higher number = faster token usage.
+- Tokens: The units that count your AI usage (roughly input + output size).
+
 ## Best Practices to Reduce Usage
 - Use clear, bounded requests with specific goals.
 - Prefer targeted edits over full rewrites.
 - Reuse context by referencing earlier outputs instead of re-pasting.
 - Ask for summaries before requesting changes.
 
+### Before And After Example
+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."
 - "Update only the functions in this file that handle validation."
@@ -19,16 +93,43 @@ Tokens are consumed based on input length, output length, and tool usage. Long p
 - Timebox explorations and stop when enough info is gathered.
 - Avoid repeated retries without changing the prompt.
 
+### Example: Timeboxed Session
+1. Ask for a 5-step plan.
+2. Approve or adjust.
+3. Ask for just step 1 or 2.
+4. Stop and summarize before moving on.
+
 ## Budgeting Routine
 - Start with a plan-first request for large tasks.
 - Limit each request to one output type.
 - End sessions with a short summary for easy follow-up.
 
+### Example: One Output Type
+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
 - Large file pastes with no clear ask.
 - Multiple full rewrites in one session.
 - Repeated "start over" requests.
 
+## How You Can Burn A Full Day Fast (Example Scenarios)
+- You paste multiple large files and ask a 3x model to rewrite everything plus tests.
+- You keep asking a high-cost model to "start over" with a new approach.
+- You do a long debugging session on a big codebase using a 3x model for every step.
+- You ask for full architecture diagrams and long explanations from a high-cost model in one session.
+
+### Realistic "New User" Scenario
+You open a single chat and do this all day:
+1. Paste a large file and ask for a full rewrite.
+2. Ask for a different rewrite using another approach.
+3. Ask for full tests.
+4. Ask for a full explanation of the changes.
+5. Repeat with another file.
+
+If each step is done with a 3x model and a growing chat context, your token use can spike quickly and slow down responses.
+
 ## Team Habits That Help
 - Capture reusable prompts in a shared doc.
 - Standardize request templates.

docs/planning/AI-Docs-Plan.md

@@ -3,6 +3,11 @@
 ## Purpose
 Keep the planning view of the docs hierarchy, scope, and future work. This is a planning artifact, not the published content.
 
+## Audience And Tone
+- Assume readers are new to AI.
+- Use step-by-step instructions.
+- Provide at least one example per major section.
+
 ## Current Docs Location
 - docs/ai/