# AI Documentation Plan

## 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.
- Explain chat modes (Ask, Edit, Plan, Agent) in plain language with examples.

## Current Docs Location
- docs/ai/

## Confluence Mapping
The docs under docs/ai map 1:1 to Confluence pages.

## Top-Level Hierarchy (Confluence)
1. AI Overview
2. iOS (Xcode + optional VS Code)
3. Android (VS Code)
4. Cross-Platform AI Usage
5. iOS MCP (XcodeBuildMCP)
5. Skills Library
6. Usage and Token Budgeting
7. Troubleshooting and FAQ
8. Governance, Privacy, and Policy

## Folder Structure (Current)
- docs/
  - ai/
    - index.md
    - overview.md
    - ios.md
    - ios-xcodebuildmcp.md
    - android.md
    - cross-platform.md
    - skills.md
    - usage-tokens.md
    - troubleshooting.md
    - governance.md
  - planning/
    - AI-Docs-Plan.md

## Assets (Non-Guide Content)
Agent prompts and instruction files are stored under assets/ so they can be moved to a separate distribution repo later.

## Open Items
- Add link to the central assets repo in Skills Library (single source of truth).
- Move assets/ (agents, instructions, skills) into a dedicated distribution repo when ready.
- Add screenshots for setup flows.
- Define section owners and review cadence.
- Add platform-specific prompt examples.
- Identify approved Android MCP tools and add details.

## Doc Navigation Pattern (Required)
When adding, removing, or renaming files under docs/ai:
1. Update docs/ai/index.md
2. Update the page breadcrumb ("You are here")
3. Update the page Contents block
4. Update the Next Steps block
5. Verify links still resolve

## Risks
- Docs drift as tools and plugins update.
- Unclear ownership leads to stale content.

## Mitigations
- Review cadence every quarter.
- Assign owners per section.
- Keep setup steps high level; link to vendor docs when needed.