docs: add CALM Copilot Chatmode and Voice Mode documentation

docs/docs/working-with-calm/copilot-chatmode.md

@@ -0,0 +1,113 @@
+---
+id: copilot-chatmode
+title: CALM Copilot Chatmode
+sidebar_position: 6
+---
+
+# CALM Copilot Chatmode
+
+CALM Copilot Chatmode provides AI-powered development assistance for CALM architecture modeling by integrating specialized knowledge and tools directly into VS Code through GitHub Copilot Chat.
+
+## Overview
+
+The `copilot-chatmode` command configures your development environment with comprehensive tool prompts that help GitHub Copilot understand CALM schema requirements, validation rules, and best practices. This enables you to get intelligent assistance when creating and modifying CALM architectures.
+
+## Prerequisites
+
+Before setting up CALM Copilot Chatmode, ensure you have:
+
+- **VS Code**: Version 1.94 or later
+- **GitHub Copilot**: Active GitHub Copilot subscription
+- **GitHub Copilot Chat Extension**: Installed in VS Code
+- **CALM CLI**: Installed globally (`npm install -g @finos/calm-cli`)
+- **Git Repository**: Your project should be in a Git repository
+
+## Setting Up CALM Copilot Chatmode
+
+To set up AI assistance for your CALM project, run the following command in your project directory:
+
+```shell
+calm copilot-chatmode
+```
+
+Or specify a different directory:
+
+```shell
+calm copilot-chatmode --directory /path/to/your/calm-project
+```
+
+This command creates a `.github/chatmodes/CALM.chatmode.md` configuration file in your repository that provides GitHub Copilot with specialized CALM knowledge.
+
+## Command Options
+
+- **`-d, --directory <path>`**: Target directory (defaults to current directory)
+- **`-v, --verbose`**: Enable verbose logging (default: false)
+- **`-h, --help`**: Display help for command
+
+## What Gets Configured
+
+The chatmode setup provides GitHub Copilot with:
+
+- **Schema-Accurate Guidance**: Complete JSON schema definitions for all CALM components ensure that suggestions follow the official CALM specification.
+- **Critical Validation Requirements**: Emphasis on important constraints like `oneOf` requirements for interfaces and proper relationship structures.
+- **Best Practice Enforcement**: Guidance on naming conventions, relationship patterns, and proper architecture structure.
+
+### Specialized Tools
+
+The chatmode includes separate tools for each CALM component:
+
+- **Architecture Creation**: Guide for creating complete CALM architecture documents
+- **Node Creation**: Creating nodes with proper validation and interface definitions
+- **Relationship Creation**: Creating relationships with correct types and constraints
+- **Interface Creation**: Critical guidance for interface `oneOf` constraints
+- **Control Creation**: Security controls, requirements, and configurations
+- **Flow Creation**: Business process flows and transitions
+- **Pattern Creation**: Reusable architectural patterns using JSON schema
+- **Metadata Creation**: Metadata structure and requirements
+- **Documentation Creation**: Generating documentation from CALM models
+
+## Using CALM Copilot Chat
+
+Once configured, you can interact with GitHub Copilot Chat in VS Code:
+
+1. Open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I)
+2. Select the **CALM** chatmode from the mode selector
+3. Ask questions or request assistance with your CALM architecture
+
+### Example Queries
+
+Here are some examples of how to use CALM Copilot Chat:
+
+**Creating Components:**
+```
+Create a new node for an API gateway service with REST interfaces
+```
+
+**Validation Help:**
+```
+Why is my interface definition failing validation?
+```
+
+**Best Practices:**
+```
+What's the recommended way to model a database relationship?
+```
+
+**Documentation:**
+```
+Generate documentation for my CALM architecture
+```
+
+## Updating Chatmode Configuration
+
+If you update the CALM CLI or want to refresh the chatmode configuration:
+
+```shell
+calm copilot-chatmode --directory /path/to/your/calm-project
+```
+
+This will update the chatmode files with the latest tool prompts and guidance.
+
+## Next Steps
+
+- Learn about [Voice Mode](voice-mode) for hands-free architecture modeling

docs/docs/working-with-calm/index.md

@@ -14,5 +14,7 @@ Explore the topics below to get hands-on experience with CALM:
 - [Using the CLI](using-the-cli): Understand the basic usage of the CALM CLI and how to access its commands.
 - [Generate](generate): Discover how to generate architectural architectures from predefined patterns.
 - [Validate](validate): Learn how to validate your architecture against CALM patterns to ensure compliance.
+- [CALM Copilot Chatmode](copilot-chatmode): Set up AI-powered development assistance for CALM architecture modeling.
+- [Voice Mode](voice-mode): Enable hands-free interaction with CALM Copilot Chat using voice commands.
 
 Let's get started and make the most of CALM’s capabilities!

docs/docs/working-with-calm/using-the-cli.md

@@ -28,10 +28,15 @@ Options:
   -h, --help          display help for command
 
 Commands:
-  generate [options]  Generate an architecture from a CALM pattern file.
-  validate [options]  Validate that an architecture conforms to a given CALM pattern.
-  server [options]    Start a HTTP server to proxy CLI commands. (experimental)
-  template [options]  Generate files from a CALM model using a Handlebars template bundle
-  docify [options]    Generate a documentation website off your CALM model
-  help [command]      display help for command
-```
+  generate [options]          Generate an architecture from a CALM pattern file.
+  validate [options]          Validate that an architecture conforms to a given CALM pattern.
+  copilot-chatmode [options]  Augment a git repository with a CALM VSCode chatmode for AI assistance.
+  server [options]            Start a HTTP server to proxy CLI commands. (experimental)
+  template [options]          Generate files from a CALM model using a Handlebars template bundle
+  docify [options]            Generate a documentation website off your CALM model
+  help [command]              display help for command
+```
+
+## AI-Powered Development
+
+CALM CLI includes AI-powered development assistance through the `copilot-chatmode` command. This feature integrates with VS Code and GitHub Copilot to provide intelligent help with architecture modeling. Learn more in the [CALM Copilot Chatmode](copilot-chatmode) section.

docs/docs/working-with-calm/voice-mode.md

@@ -0,0 +1,101 @@
+---
+id: voice-mode
+title: Voice Mode
+sidebar_position: 7
+---
+
+# Voice Mode with CALM Copilot Chat
+
+Voice Mode enables hands-free interaction with CALM Copilot Chat, allowing you to speak architecture queries and receive spoken responses directly in the chat interface.
+
+## Getting Started
+
+### Prerequisites
+
+- **VS Code**: Version 1.94 or later
+- **CALM Copilot Chatmode**: Configured in your repository (see [CALM Copilot Chatmode](copilot-chatmode))
+- **GitHub Copilot Chat**: Active subscription and extension installed
+- **Microphone**: A working microphone
+
+### Setup
+
+1. **Install the VS Code Speech Extension**
+   - Open VS Code Extensions (Ctrl+Shift+X or Cmd+Shift+X)
+   - Search for "VS Code Speech"
+   - Click **Install** on the Microsoft-published extension
+
+2. **Grant Microphone Permissions**
+   - First use will prompt for microphone access - click **Allow**
+   - If prompted on macOS, grant permissions to both "Visual Studio Code" and "Code Helper", then restart VS Code
+   - On Windows, ensure VS Code is enabled in Settings → Privacy → Microphone
+
+3. **Configure VS Code Settings**
+   - Open VS Code Settings (Ctrl+, or Cmd+,)
+   - Search for `accessibility.voice` and add these settings:
+
+```json
+{
+  "accessibility.voice.autoSynthesize": "on",
+  "accessibility.voice.ignoreCodeBlocks": true,
+  "accessibility.voice.speechTimeout": 1200,
+  "accessibility.voice.keywordActivation": "chatInView"
+}
+```
+
+## Using Voice Mode
+
+### Starting a Voice Query
+
+1. Open GitHub Copilot Chat (Ctrl+Shift+I or Cmd+Shift+I)
+2. Select the **CALM** chatmode
+3. Click the microphone icon in the chat input field or press Ctrl+I (Windows/Linux) / Cmd+I (macOS)
+4. Speak your query clearly
+5. The response will appear as you finish speaking (auto-submit after ~1.2 seconds of silence)
+6. Your response will be read aloud automatically
+
+### Quick Voice Activation
+
+Say **"Hey Code"** to activate voice input without clicking anything (requires `keywordActivation` setting enabled above).
+
+### Example Queries
+
+Speak naturally and clearly. Here are examples of how you can use CALM Chatmode via voice:
+
+**Building Your Architecture:**
+
+- "Create a microservices architecture with a web frontend, API gateway, and PostgreSQL database"
+- "Add a node for the authentication service with HTTPS interfaces"
+- "Create a connects-to relationship from the API gateway to the backend services"
+- "Define that the services are deployed in Kubernetes"
+
+**Defining Controls and Compliance:**
+
+- "Add PCI-DSS compliance controls to the payment processor service"
+- "Define encryption-in-transit controls for all API connections"
+- "What security controls should apply to our database?"
+
+**Modeling Business Processes:**
+
+- "Create a flow for the customer onboarding process"
+- "Model the trade execution flow from order placement to settlement"
+- "Show the data journey through our system"
+
+**Validation and Best Practices:**
+
+- "Is my architecture valid?"
+- "What patterns apply to this microservices design?"
+- "What interfaces should the authentication service expose?"
+- "Why is my relationship definition failing validation?"
+
+**Documentation and Visualization:**
+
+- "Generate documentation for my architecture"
+- "Create a visual diagram of the system"
+- "Document all the interfaces and their protocols"
+
+### Listening to Responses
+
+Responses will be read aloud automatically (if `autoSynthesize` is enabled). You can also:
+
+- **Stop playback**: Press **ESC** or click the speaker icon
+- **Manual read-aloud**: Click the speaker icon next to any response to hear it read aloud again