docs: comprehensive documentation update and QA verification

- Add complete user-facing documentation suite (USER_GUIDE, FEATURES, ARCHITECTURE, PROVIDERS, TOOLS, MEMORY, SECURITY, PERFORMANCE, INSTALLATION)
- Add SECURITY.md vulnerability reporting policy
- Update README.md with new docs structure and provider list (add Google Gemini, MiniMax, OpenRouter)
- Update AGENTS.md with accurate Xcode version (16.0+) and corrected tool/provider counts
- Update project-docs with latest specifications
- Add llms.txt to gitignore exception
- Full QA pass verifying all documentation against current source code

Author: fewtarius

.gitignore

@@ -22,6 +22,7 @@ nohup.out
 .last_version
 *.log
 /*.txt
+!llms.txt
 /*.json
 
 # Test output

AGENTS.md

@@ -19,7 +19,7 @@ SAM (Synthetic Autonomic Mind) is a native macOS AI assistant built with Swift a
 ### Prerequisites
 
 - macOS 14.0+ (development on macOS 15.0+)
-- Xcode 14.0+ with Swift 6.0+
+- Xcode 16.0+ with Swift 6.0+
 - Command line tools: `xcode-select --install`
 - ccache (optional, speeds up builds): `brew install ccache`
 
@@ -202,18 +202,20 @@ Sources/
 │   └── PropertiesStorage/
 ├── APIFramework/               - Multi-provider support, orchestration
 │   ├── APIProvider.swift (protocol)
-│   ├── Providers/ (OpenAI, Anthropic, DeepSeek, GitHub Copilot)
+│   ├── Providers/ (OpenAI, Anthropic, GitHub Copilot, Google Gemini, DeepSeek, MiniMax, OpenRouter)
 │   ├── AgentOrchestrator.swift (multi-step workflows)
 │   └── ToolCallExtractor.swift
 ├── MCPFramework/               - Model Context Protocol tools
 │   ├── MCPTool.swift (protocol)
-│   ├── Tools/ (10 tools, 60+ operations)
+│   ├── Tools/ (8 tools, 60+ operations)
 │   ├── ToolRegistry.swift
 │   └── ToolResult.swift
 ├── SharedData/                 - Shared types, thread-safe storage
 │   ├── SharedTopics.swift
 │   ├── Storage.swift
 │   └── Locking/
+├── SecurityFramework/          - Authorization, path security
+│   └── SecurityOperations.swift
 └── VoiceFramework/             - Speech recognition, TTS, wake word
     ├── SpeechRecognizer.swift
     ├── TextToSpeech.swift

README.md

@@ -18,9 +18,10 @@ SAM is a native macOS AI assistant built with Swift and SwiftUI. Unlike cloud-on
 
 - **Website:** [www.syntheticautonomicmind.org](https://www.syntheticautonomicmind.org)
 - **Download SAM:** [Latest Release](https://github.com/SyntheticAutonomicMind/SAM/releases)
-- **Documentation:** [User Guides & Tutorials](https://www.syntheticautonomicmind.org)
+- **Documentation:** [User Guide](docs/USER_GUIDE.md) · [Features](docs/FEATURES.md) · [All Docs](docs/)
 - **Source Code:** [GitHub Repository](https://github.com/SyntheticAutonomicMind/SAM)
 - **Report Issues:** [Issue Tracker](https://github.com/SyntheticAutonomicMind/SAM/issues)
+- **Security:** [Security Policy](SECURITY.md)
 - **Support SAM:** [Patreon](https://www.patreon.com/fewtarius)
 
 ---
@@ -118,7 +119,7 @@ SAM's clean interface and natural interactions make powerful AI accessible to ev
 
 ## Features at a Glance
 
-- **Multi‑AI support**: Choose from OpenAI, Anthropic (Claude), GitHub Copilot, DeepSeek, or run models locally (MLX, llama.cpp)
+- **Multi-AI support**: Choose from OpenAI, Anthropic (Claude), GitHub Copilot, Google Gemini, DeepSeek, MiniMax, or run models locally (MLX, llama.cpp)
 - **Voice in & out**: "Hey SAM" wake word, speech recognition, and natural text‑to‑speech
 - **Image generation**: Create images via [ALICE](https://github.com/SyntheticAutonomicMind/ALICE) server with automatic model discovery
 - **Math tools**: Real computation for calculations, conversions, and financial formulas
@@ -146,7 +147,7 @@ Get a glimpse of SAM's native macOS interface in action:
     <td width="50%">
       <h3>Flexible AI Provider Selection</h3>
       <img src=".images/sam-image-2.png"/>
-      <em>Choose from local models (MLX, llama.cpp), or cloud providers (OpenAI, Anthropic, DeepSeek, OpenRouter)</em>
+      <em>Choose from local models (MLX, llama.cpp), or cloud providers (OpenAI, Anthropic, Google Gemini, DeepSeek, MiniMax, OpenRouter)</em>
     </td>
   </tr>
 </table>
@@ -217,7 +218,7 @@ Get a glimpse of SAM's native macOS interface in action:
 - Secure API authentication
 
  **Flexible AI Provider Support**
-- **Cloud AI**: OpenAI, Anthropic (Claude), GitHub Copilot, DeepSeek, OpenRouter
+- **Cloud AI**: OpenAI, Anthropic (Claude), GitHub Copilot, Google Gemini, DeepSeek, MiniMax, OpenRouter
 - **Local Models**: Run AI completely on your Mac with MLX or llama.cpp
 - Switch models mid-conversation
 - Use custom OpenAI-compatible endpoints
@@ -254,7 +255,7 @@ brew upgrade --cask sam
 3. Go to **AI Providers** tab
 4. Click **Add Provider**
 5. Choose your provider:
-  - **Cloud AI**: OpenAI, Claude, GitHub Copilot, or DeepSeek
+  - **Cloud AI**: OpenAI, Claude, GitHub Copilot, Google Gemini, DeepSeek, MiniMax, or OpenRouter
   - **Local Model**: Choose a model to download and run on your Mac
 6. For cloud providers: Enter your API key
 7. Save and start chatting!
@@ -358,6 +359,9 @@ Your feedback helps make SAM better for everyone!
 | **Anthropic** | Claude 3.5 Sonnet, Claude 4 (long context) |
 | **GitHub Copilot** | GPT-4o, Claude 3.5, o1 (requires subscription) |
 | **DeepSeek** | Cost-effective AI models |
+| **Google Gemini** | Gemini 2.5 Pro/Flash, large context windows |
+| **MiniMax** | MiniMax-M2.7, M2.5 (128K context) |
+| **OpenRouter** | Access 100+ models from multiple providers |
 | **Local MLX** | Run models on Apple Silicon Macs |
 | **Local llama.cpp** | Run models on any Mac (Intel or Apple Silicon) |
 | **Custom** | Use any OpenAI-compatible API |
@@ -478,9 +482,8 @@ When you use cloud AI providers (OpenAI, Claude, etc.), only the messages you se
 
 ### Downloaded AI Models
 ```
-~/Library/Caches/sam/models/
-├── mlx/                       # MLX models (Apple Silicon)
-└── gguf/                      # llama.cpp models
+~/Library/Caches/sam-rewritten/models/
+└── {model-name}/              # Individual model files
 ```
 
 ### Working Files
@@ -582,10 +585,19 @@ For developers who want to build SAM from source, see [BUILDING.md](BUILDING.md)
 
 Complete documentation is available:
 
-- **[Website](https://www.syntheticautonomicmind.org)** - User guides and tutorials
-- **[project-docs/](project-docs/)** - Technical documentation for developers
-- **[BUILDING.md](BUILDING.md)** - Build instructions
+- **[User Guide](docs/USER_GUIDE.md)** - Getting started and using SAM
+- **[Features](docs/FEATURES.md)** - Complete feature reference
+- **[Architecture](docs/ARCHITECTURE.md)** - How SAM is built
+- **[Providers](docs/PROVIDERS.md)** - AI provider setup guide
+- **[Tools](docs/TOOLS.md)** - Built-in tools reference
+- **[Memory](docs/MEMORY.md)** - Memory and search system
+- **[Security](docs/SECURITY.md)** - Privacy and security model
+- **[Installation](docs/INSTALLATION.md)** - Installation guide
+- **[Performance](docs/PERFORMANCE.md)** - Performance and optimization
+- **[BUILDING.md](BUILDING.md)** - Build from source
 - **[CONTRIBUTING.md](CONTRIBUTING.md)** - How to contribute
+- **[project-docs/](project-docs/)** - Internal technical specifications
+- **[Website](https://www.syntheticautonomicmind.org)** - Online guides
 
 ---
 

SECURITY.md

@@ -0,0 +1,49 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+If you discover a security vulnerability in SAM, please report it responsibly:
+
+1. **Do not** open a public GitHub issue
+2. Email the maintainer directly at the security contact listed on the [GitHub repository](https://github.com/SyntheticAutonomicMind/SAM)
+3. Include a detailed description of the vulnerability
+4. Include steps to reproduce the issue
+5. Allow reasonable time for a fix before public disclosure
+
+## Response Timeline
+
+- **Acknowledgment:** Within 48 hours
+- **Initial assessment:** Within 1 week
+- **Fix for critical issues:** As soon as possible, targeting same-week release
+- **Fix for non-critical issues:** Included in the next scheduled release
+
+## Supported Versions
+
+Only the latest release is supported with security updates. We recommend always running the most recent version.
+
+| Version | Supported |
+|---------|-----------|
+| Latest release | Yes |
+| Previous releases | No |
+| Development builds | Best effort |
+
+## Scope
+
+The following are in scope for security reports:
+
+- Authentication bypass in the API server
+- Unauthorized file access through the tool system
+- API key exposure or insecure storage
+- Remote code execution vulnerabilities
+- Privilege escalation
+
+The following are out of scope:
+
+- Issues requiring physical access to the Mac
+- Social engineering attacks
+- Vulnerabilities in third-party AI providers (report to the provider directly)
+- Issues in development/debug builds only
+
+## Security Model
+
+For details about SAM's security design, see [docs/SECURITY.md](docs/SECURITY.md).