chore: initial docs

AI-Docs-Plan.md

@@ -0,0 +1,138 @@
+# AI Documentation Plan
+
+## Purpose
+Create a Confluence-ready hierarchy and an initial documentation set that assumes zero prior knowledge. This plan now maps directly to markdown files under a docs folder.
+
+## Proposed Folder Structure
+- docs/
+  - ai/
+    - index.md
+    - overview.md
+    - ios.md
+    - android.md
+    - cross-platform.md
+    - skills.md
+    - usage-tokens.md
+    - troubleshooting.md
+    - governance.md
+
+## Top-Level Hierarchy (Confluence)
+1. AI Overview
+2. iOS (Xcode + optional VS Code)
+3. Android (VS Code)
+4. Cross-Platform AI Usage
+5. Skills Library
+6. Usage and Token Budgeting
+7. Troubleshooting and FAQ
+8. Governance, Privacy, and Policy
+
+## 1) AI Overview
+- Start Here
+  - What AI is and is not (short definitions)
+  - What problems AI can help with (examples)
+  - What not to use AI for (guardrails)
+- GitHub Copilot Enterprise
+  - What it is
+  - Access requirements
+  - Account setup steps
+- Terminology
+  - Copilot
+  - Chat
+  - Agents
+  - Skills
+  - Tokens and usage
+- Getting Help
+  - Who to contact
+  - Where to report issues
+
+## 2) iOS (Xcode + optional VS Code)
+- Setup Path A: Xcode + GitHub Copilot for Xcode
+  - Prerequisites
+  - Install plugin
+  - Sign in and verify
+  - First-use walkthrough
+- Setup Path B: VS Code + GitHub Copilot extension
+  - When to use VS Code on iOS
+  - Install extension
+  - Sign in and verify
+  - First-use walkthrough
+- iOS-Specific Guidance
+  - Swift/SwiftUI tips
+  - Common prompt patterns for iOS
+- iOS Troubleshooting
+  - Login issues
+  - Suggestions not appearing
+  - Network or policy blocks
+
+## 3) Android (VS Code)
+- Setup: VS Code + GitHub Copilot extension
+  - Prerequisites
+  - Install extension
+  - Sign in and verify
+  - First-use walkthrough
+- Android-Specific Guidance
+  - Kotlin/Java tips
+  - Common prompt patterns for Android
+- Android Troubleshooting
+  - Login issues
+  - Suggestions not appearing
+  - Network or policy blocks
+
+## 4) Cross-Platform AI Usage
+- Agents.md
+  - What it is
+  - How to use it (copy/paste examples)
+  - When to use agents vs chat
+- Prompting Patterns
+  - Asking for refactors
+  - Writing tests
+  - Debugging errors
+  - Explaining unfamiliar code
+- Connecting Skills
+  - When to use a skill
+  - How to chain multiple skills
+  - How to pass context between steps
+
+## 5) Skills Library
+- What skills are
+- How to download existing skills
+- How to enable or configure skills
+- Current Skills (add repo links)
+  - onboarding-cro (link)
+  - revenuecat-ios-integration (link)
+  - find-skills (link)
+  - swiftui-expert-skill (link)
+  - mcp-builder (link)
+  - pdf (link)
+  - skill-creator (link)
+  - template-skill (link)
+  - webapp-testing (link)
+
+## 6) Usage and Token Budgeting
+- How tokens are spent (simple model)
+- Best practices to reduce usage
+  - Use clear, bounded requests
+  - Prefer edits over full rewrites
+  - Reuse context instead of re-sending
+- Daily and monthly budgeting tips
+- Red flags that burn tokens quickly
+- Quick checklist
+
+## 7) Troubleshooting and FAQ
+- Setup and login errors
+- Extension or plugin conflicts
+- Company network restrictions
+- Why suggestions are low quality
+- When to escalate
+
+## 8) Governance, Privacy, and Policy
+- What data is allowed
+- What data is forbidden
+- Safe prompts and examples
+- Compliance and audit expectations
+
+## Next Steps
+- Assign owners per section
+- Link skills to their repos
+- Add screenshots and short videos
+- Set review cadence

Agents.md

@@ -0,0 +1,32 @@
+# Agents
+
+## Purpose
+This file defines how to use agent-style workflows in this project so tasks are clear, scoped, and repeatable.
+
+## When to Use Agents
+- Multi-step changes across files.
+- Refactors with clear acceptance criteria.
+- Audits or documentation updates.
+
+## Common Agent Use Cases
+- Create or expand documentation sections.
+- Plan a refactor before making edits.
+- Summarize and assess risks across files.
+
+## How to Use Agents
+1. Define the outcome in one sentence.
+2. List inputs (files, context, constraints).
+3. Ask for a plan, then approve before edits.
+4. Ask for focused changes and verification steps.
+
+## Suggested Agent Request Template
+- Goal: (one sentence)
+- Inputs: (files, context, constraints)
+- Output: (expected deliverable)
+- Verification: (tests or checks)
+
+## Example
+Goal: Add a troubleshooting section to the AI docs.
+Inputs: docs/ai/troubleshooting.md, AI-Docs-Plan.md
+Output: Updated troubleshooting section with 5 common issues.
+Verification: Manual review.

PRD.md

@@ -0,0 +1,64 @@
+# Product Requirements Document (PRD)
+
+## Product
+AI Documentation for Mobile Development
+
+## Problem Statement
+Teams need a clear, zero-knowledge onboarding path for AI tools, setup, and usage across iOS and Android.
+
+## Goals
+- Provide a structured, searchable AI docs hierarchy.
+- Enable fast setup for Copilot on Xcode and VS Code.
+- Document agents, skills, and token budgeting.
+- Set guardrails for safe AI usage.
+
+## Non-Goals
+- Replacing official vendor documentation.
+- Providing legal or security approvals.
+- Enforcing policy compliance.
+
+## Target Audience
+- Mobile engineers (iOS and Android).
+- New hires and interns.
+- Tech leads who onboard team members.
+
+## User Stories
+- As a new engineer, I can set up Copilot in under 30 minutes.
+- As a lead, I can point people to a single AI docs index.
+- As a contributor, I can add or update skills guidance.
+
+## Success Metrics
+- Time-to-setup under 30 minutes for new users.
+- Reduced setup questions in chat or onboarding sessions.
+- Consistent AI usage aligned with policy.
+
+## Scope
+- Confluence-ready structure with markdown source.
+- iOS and Android setup guides.
+- Skills inventory and usage guidance.
+- Token usage guidance and troubleshooting.
+
+## Assumptions
+- The org has a Copilot Enterprise subscription.
+- Editors are standard across teams (Xcode and VS Code).
+- Policies for data handling are available elsewhere.
+
+## Dependencies
+- GitHub Copilot Enterprise access and provisioning.
+- Editor plugins and extensions are approved for use.
+- A shared location for skills and updates.
+
+## Risks and Mitigations
+- Outdated instructions: set a review cadence.
+- Unclear ownership: assign section owners.
+- Overly generic guidance: add platform-specific examples.
+
+## Milestones
+- Draft structure and initial content.
+- Review with iOS and Android leads.
+- Publish to Confluence and iterate.
+
+## Open Questions
+- Who owns each section and review cadence?
+- Where should skill repo links be hosted?
+- What screenshots and examples are required?

README.md

@@ -0,0 +1,34 @@
+# AI Documentation Project
+
+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.
+
+## Structure
+- [AI Docs Index](docs/ai/index.md)
+- [Agents](Agents.md)
+- [PRD](PRD.md)
+- [AI Docs Plan](AI-Docs-Plan.md)
+
+## 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.
+
+## Local Workflow
+- Edit files in docs/ai.
+- Keep sections short and scannable.
+- Avoid vendor-specific step details that change frequently.
+
+## Publish to Confluence
+1. Copy the page content from each markdown file.
+2. Preserve the hierarchy shown in docs/ai/index.md.
+3. Add screenshots or short videos where helpful.
+
+## Contributing
+- Keep content short, direct, and beginner-friendly.
+- Add platform-specific examples when possible.
+- Update the Skills Library with repo links.
+
+## Next Steps
+- Add screenshots and short walkthrough videos.
+- Assign owners per section.
+- Publish to Confluence.

docs/ai/android.md

@@ -0,0 +1,37 @@
+# Android AI Setup
+
+## Setup: VS Code + GitHub Copilot Extension
+### Prerequisites
+- VS Code installed and up to date.
+- GitHub account with Copilot Enterprise access.
+
+### Install and Sign In (High-Level)
+1. Install the GitHub Copilot extension.
+2. Sign in with your GitHub account.
+3. Confirm Copilot is enabled in VS Code.
+4. Run a simple prompt to verify suggestions appear.
+
+### Verification Steps
+- Open a Kotlin file and start a small function.
+- Confirm inline suggestions appear.
+- Open Copilot Chat and ask a short question.
+
+## Android-Specific Guidance
+- Ask for Kotlin/Java patterns with small, bounded tasks.
+- Request unit tests for services and view models.
+- Prefer incremental changes over large rewrites.
+
+### Starter Prompts
+- "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.
+- If the extension is disabled, check extension settings.
+- If responses are blocked, check network or policy constraints.
+
+### Common Setup Gaps
+- Copilot access not provisioned for the GitHub account.
+- VS Code extension disabled after an update.
+- Multiple AI extensions competing for suggestions.

docs/ai/cross-platform.md

@@ -0,0 +1,46 @@
+# Cross-Platform AI Usage
+
+## Agents.md
+### What It Is
+Agents define a structured workflow so tasks are broken into clear steps, with explicit inputs and outputs.
+
+### How to Use It
+1. Read [Agents.md](../../Agents.md).
+2. Choose a workflow that matches your task.
+3. Provide the inputs in a short, bounded request.
+
+### 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.
+
+### Request Template
+Use this structure to get consistent results:
+
+```text
+Goal: <one sentence>
+Inputs: <files, constraints, context>
+Output: <expected deliverable>
+Verification: <tests or checks>
+```
+
+## Prompting Patterns
+- Refactors: "Refactor this file to improve readability without changing behavior."
+- 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."
+
+## 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.
+
+## Connecting Skills
+- Use skills for tasks with known workflows.
+- Combine multiple skills when a task spans domains.
+- Pass concise context between steps to reduce repetition.
+
+## Efficiency Tips
+- Keep prompts small and scoped.
+- Reuse context from earlier steps instead of repeating it.
+- Ask for summaries before asking for edits.

docs/ai/governance.md

@@ -0,0 +1,30 @@
+# Governance, Privacy, and Policy
+
+## Allowed Data
+- Public information or approved internal content.
+- Code that is already in approved repos.
+
+## Handle With Care
+- Customer data or identifiers.
+- Security-sensitive configuration.
+- Anything not explicitly approved by policy.
+
+## Forbidden Data
+- Secrets, credentials, or personal data.
+- Non-approved proprietary information.
+
+## Safe Prompt Examples
+- "Summarize this public API and propose tests."
+- "Refactor this function without changing behavior."
+
+## Redaction Tips
+- Remove secrets before pasting.
+- Replace real identifiers with placeholders.
+- Use minimal context required for the task.
+
+## 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.

docs/ai/index.md

@@ -0,0 +1,23 @@
+# AI Documentation
+
+Welcome. This section is the entry point for AI enablement. It assumes no prior knowledge and is safe to follow step-by-step.
+
+## If You Are New
+1. Read the overview to understand terms and guardrails.
+2. Follow the setup guide for your platform.
+3. Skim skills and usage tips before your first session.
+
+## Start Here
+- [AI Overview](overview.md)
+- [iOS Setup](ios.md)
+- [Android Setup](android.md)
+
+## Usage Guides
+- [Cross-Platform AI Usage](cross-platform.md)
+- [Skills Library](skills.md)
+- [Usage and Token Budgeting](usage-tokens.md)
+- [Troubleshooting and FAQ](troubleshooting.md)
+- [Governance, Privacy, and Policy](governance.md)
+
+## Confluence Mapping
+This folder maps 1:1 to Confluence pages so content can be copied without rework.

docs/ai/ios.md

@@ -0,0 +1,54 @@
+# iOS AI Setup
+
+## Setup Path A: Xcode + GitHub Copilot for Xcode
+### Prerequisites
+- Xcode installed and up to date.
+- GitHub account with Copilot Enterprise access.
+
+### Install and Sign In (High-Level)
+1. Install the GitHub Copilot for Xcode plugin.
+2. Sign in with your GitHub account.
+3. Confirm Copilot is enabled in Xcode.
+4. Run a simple prompt to verify suggestions appear.
+
+### Verification Steps
+- Open a Swift file and start a small function.
+- Confirm inline suggestions appear.
+- Open the Copilot chat panel and ask a short question.
+
+## Setup Path B: VS Code + GitHub Copilot Extension
+### When to Use VS Code on iOS
+- Editing shared docs or configs.
+- Rapid refactors or explorations.
+- Working on multi-platform files.
+
+### Install and Sign In (High-Level)
+1. Install VS Code and the GitHub Copilot extension.
+2. Sign in with your GitHub account.
+3. Confirm Copilot is enabled in VS Code.
+4. Run a simple prompt to verify suggestions appear.
+
+### Verification Steps
+- Open a Swift file and type a short function signature.
+- Confirm inline suggestions appear.
+- Open Copilot Chat and request a short summary.
+
+## iOS-Specific Guidance
+- Ask for Swift/SwiftUI patterns with small, bounded tasks.
+- Request tests or sample usages for view models.
+- Favor refactor or patch requests over full rewrites.
+
+### 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."
+- "Refactor this view to reduce duplication without changing behavior."
+
+## iOS Troubleshooting
+- If suggestions are missing, confirm sign-in and access.
+- If the plugin is not visible, verify extension compatibility.
+- If responses are blocked, check network or policy constraints.
+
+### Common Setup Gaps
+- Copilot access not provisioned for the GitHub account.
+- Xcode plugin disabled after update.
+- Multiple AI plugins competing for suggestions.

docs/ai/overview.md

@@ -0,0 +1,57 @@
+# AI Overview
+
+## Start Here
+AI tools help with drafting, refactoring, explaining code, and accelerating routine tasks. They are not a replacement for engineering judgment, security review, or domain knowledge.
+
+## What To Expect In The First 30 Minutes
+1. Confirm you have access to GitHub Copilot Enterprise.
+2. Install the editor plugin for your platform.
+3. Run a simple prompt to verify suggestions appear.
+4. Read the usage and token guidance to avoid accidental overuse.
+
+## What AI Is and Is Not
+- 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.
+
+## 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.
+
+### Access Requirements
+- You must be provisioned for Copilot Enterprise by the org.
+- You must sign in with your GitHub account that has access.
+
+### Setup Steps (High-Level)
+1. Confirm access with your team or admin.
+2. Sign in to GitHub in your editor or plugin.
+3. Verify Copilot is enabled in editor settings.
+4. Run a quick prompt to validate it works.
+
+### Quick Access Checklist
+- GitHub account is linked to the org.
+- SSO or required auth flow is completed.
+- Copilot is enabled in the editor or plugin settings.
+
+## Terminology
+- Copilot: The AI assistant integrated into your editor.
+- Chat: The conversational interface in your editor.
+- Agents: Structured workflows that break work into steps.
+- Skills: Reusable knowledge or workflows the assistant can apply.
+- Tokens: The usage units that track AI consumption.
+
+## First Prompt (Safe)
+Try a small, safe prompt to confirm everything is working:
+
+```text
+Summarize what this file does in 3 bullet points.
+```
+
+## Guardrails And Good Habits
+- Keep prompts scoped to a single task.
+- Ask for a plan before large changes.
+- Verify outputs with tests and review.
+- Avoid sharing secrets or sensitive data.
+
+## 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

@@ -0,0 +1,65 @@
+# Skills Library
+
+## What Skills Are
+Skills are reusable instructions and workflows that guide the assistant through specialized tasks.
+
+## When To Use A Skill
+- The task has a repeatable workflow.
+- You want consistent structure and outputs.
+- The task spans multiple files or steps.
+
+## 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.
+
+## 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.
+3. Restart the editor or chat if required so the skill is recognized.
+
+## How to Enable or Configure Skills
+- Follow the instructions provided in each skill's README or SKILL file.
+- Some skills require additional setup, such as environment variables or tools.
+
+## How To Connect Skills
+1. State the primary skill you want to use.
+2. Provide the inputs that skill expects.
+3. If needed, add a secondary skill and explain the handoff.
+
+## Current Skills (Add Repo Links)
+Add a short summary and link for each skill below.
+
+### onboarding-cro
+- Focus: New user onboarding and activation guidance.
+- Repo: (link)
+
+### revenuecat-ios-integration
+- Focus: RevenueCat setup for iOS and SwiftUI.
+- Repo: (link)
+
+### find-skills
+- Focus: Discovering and selecting skills for tasks.
+- Repo: (link)
+
+### swiftui-expert-skill
+- Focus: SwiftUI best practices and patterns.
+- Repo: (link)
+
+### mcp-builder
+- Focus: Building MCP servers and tool integrations.
+- Repo: (link)
+
+### pdf
+- Focus: PDF processing workflows.
+- Repo: (link)
+
+### skill-creator
+- Focus: Creating and maintaining new skills.
+- Repo: (link)
+
+### template-skill
+- Focus: Base template for new skills.
+- Repo: (link)
+
+### webapp-testing
+- Focus: Web app testing workflows.
+- Repo: (link)

docs/ai/troubleshooting.md

@@ -0,0 +1,35 @@
+# Troubleshooting and FAQ
+
+## Common Setup Issues
+- Cannot sign in: confirm GitHub access and SSO.
+- No suggestions: verify Copilot is enabled in the editor.
+- Plugin missing: confirm the plugin or extension is installed.
+
+## Quick Diagnostic Flow
+1. Confirm account access and SSO.
+2. Confirm plugin or extension is installed and enabled.
+3. Restart the editor.
+4. Test with a small prompt in a new file.
+5. If still blocked, escalate.
+
+## Extension or Plugin Conflicts
+- Disable overlapping AI extensions to avoid conflicts.
+- Restart the editor after enabling Copilot.
+
+## Company Network Restrictions
+- Check for blocked endpoints or proxy requirements.
+- Escalate to IT if access appears restricted.
+
+## Low-Quality Suggestions
+- Tighten the prompt with scope and context.
+- Provide a small example or expected output.
+
+## What To Collect Before Escalation
+- Editor version and plugin version.
+- Error messages or screenshots.
+- Whether the issue is reproducible in another editor.
+
+## When to Escalate
+- Account access issues after setup.
+- Consistent failures across multiple editors.
+- Policy or security concerns.

docs/ai/usage-tokens.md

@@ -0,0 +1,40 @@
+# Usage and Token Budgeting
+
+## How Tokens Are Spent
+Tokens are consumed based on input length, output length, and tool usage. Long prompts and repeated context increase usage quickly.
+
+## 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.
+
+## 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."
+- "List risks in this change and suggest tests to add."
+
+## Daily and Monthly Budgeting Tips
+- Batch related questions in a single prompt.
+- Timebox explorations and stop when enough info is gathered.
+- Avoid repeated retries without changing the prompt.
+
+## 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.
+
+## Red Flags That Burn Tokens Quickly
+- Large file pastes with no clear ask.
+- Multiple full rewrites in one session.
+- Repeated "start over" requests.
+
+## Team Habits That Help
+- Capture reusable prompts in a shared doc.
+- Standardize request templates.
+- Agree on when to use agents vs chat.
+
+## Quick Checklist
+- Is the request specific and scoped?
+- Do I need the whole file or just a section?
+- Can I ask for a plan first?