Merge branch 'main' into frontend-identity-method

Author: shalomgk

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,38 @@
+---
+name: Bug report
+about: Create a report to help us improve
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Describe the bug**
+A clear and concise description of what the bug is.
+
+**To Reproduce**
+Steps to reproduce the behavior:
+1. Go to '...'
+2. Click on '....'
+3. Scroll down to '....'
+4. See error
+
+**Expected behavior**
+A clear and concise description of what you expected to happen.
+
+**Screenshots**
+If applicable, add screenshots to help explain your problem.
+
+**Desktop (please complete the following information):**
+ - OS: [e.g. iOS]
+ - Browser [e.g. chrome, safari]
+ - Version [e.g. 22]
+
+**Smartphone (please complete the following information):**
+ - Device: [e.g. iPhone6]
+ - OS: [e.g. iOS8.1]
+ - Browser [e.g. stock browser, safari]
+ - Version [e.g. 22]
+
+**Additional context**
+Add any other context about the problem here.

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,20 @@
+---
+name: Feature request
+about: Suggest an idea for this project
+title: ''
+labels: ''
+assignees: ''
+
+---
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

fern/docs/pages/airdrop/data-model/rich-text-fields.mdx

@@ -23,7 +23,7 @@ Mention objects represents any mention (user, issue, etc.) in rich text and have
 | Field                  | Type   | Required | Description                                                                                                                          |
 | ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
 | `id`                   | String | Yes      | Identifier of the mentioned item (user ID, etc.) in the format used by the source system.                                            |
-| `ref_type`             | String | Yes      | Type of the mentioned item (for example, "issue", "comment"). The recipe converts this based on user mappings.                             |
+| `ref_type`             | String | Yes      | Type of the mentioned item (for example, `issue`, `comment`). It must match the record type defined in external domain metadata. The recipe converts this based on user mappings.                             |
 | `fallback_record_name` | String | No       | Display text if the mention cannot be resolved (user display name, ticket title, etc.).                                              |
 
 In reverse, the loader should expect the following structure:

fern/docs/pages/airdrop/initial-domain-mapping.mdx

@@ -7,6 +7,20 @@ The initial domain mapping is installed with your snap-in.
 On each snap-in version update, function to upload these mappings to the Airdrop
 system is triggered.
 
+## Approaches
+
+You can create initial domain mappings using two methods:
+
+1. **Chef-cli UI**: Interactive web interface for comprehensive mapping creation
+2. **Model Context Protocol (MCP)**: AI-assisted mapping creation for developers (experimental)
+
+Choose the chef-cli UI for manual control or use MCP for rapid prototyping with AI assistance.
+MCP is an experimental feature and works locally without requiring a sync to be created.
+
+<Info>
+For AI-assisted mapping creation, see the [Model Context Protocol integration guide](./mcp.mdx).
+</Info>
+
 ## Chef-cli initial domain mapping setup
 
 ### Prerequisites
@@ -95,7 +109,7 @@ After the blueprint of the test import is completed, the *Install in this org* b
 
 By repeating this process (run a new import, create a different configuration, merge to the initial mappings), you can create an initial mapping that contains multiple options for the user to choose from.
 
-Finally, the Export button allows you to retrieve the `initial_domain_mapping.json`.
+Finally, when all the fields are mapped without deficiencies and the blueprint is installed, the Export button allows you to retrieve the `initial_domain_mapping.json`.
 
 <Tip>
 You can also provide a local metadata file to the command using the `-m` flag, for example: 

fern/docs/pages/airdrop/mcp.mdx

@@ -0,0 +1,83 @@
+The Model Context Protocol (MCP) is an open protocol that enables large language models to interact with applications through standardized interfaces.
+
+Chef-cli provides MCP integration through the `chef-cli mcp initial-mapping` subcommand. 
+This integration allows AI assistants to programmatically edit and test initial domain mapping files.
+
+## Limitations
+
+<Warning>
+MCP integration is experimental. Functionality may vary across different AI models and MCP clients.
+</Warning>
+
+Testing shows good results with Cursor and Claude Code. The AI can prepare initial mappings with significant autonomy, though developer oversight remains essential.
+
+## Prerequisites
+
+- Chef-cli installed and configured
+- MCP-compatible client (Cursor, Claude Code, etc.)
+- External domain metadata file
+- Empty or partially populated initial domain mapping file
+
+## Configuration
+
+Create a `.mcp.json` file with the following content:
+
+```json
+{
+    "mcpServers": {
+        "airdrop": {
+            "command": "chef-cli",
+            "args": [
+                "mcp initial-mapping"
+            ]
+        }
+    }
+}
+```
+
+### Cursor setup
+
+1. Provide `.cursor/mcp.json` in your project root.
+2. Using the editor Agent mode point the AI to the initial domain mapping file.
+3. Use the editor to guide the AI to create the initial domain mappings.
+4. Use `initial-mapping check` to test the initial domain mappings against the local domain metadata file.
+
+### Claude Code setup
+
+1. Provide `.mcp.json` in your project root.
+2. Using the editor point the AI to the initial domain mapping file.
+3. Use the editor to guide the AI to create the initial domain mappings.
+4. Use `initial-mapping check` to test the initial domain mappings against the local domain metadata file.
+
+### Other IDEs
+
+You can use the same `.mcp.json` file in other IDEs that support MCP.
+
+## Usage guidelines
+
+To guide the AI tool, provide the following instructions to your AI assistant:
+
+```markdown
+When asked to perform airdrop initial mapping:
+
+- Refer to the `metadata.json` for the external domain metadata.
+- Use `mappings.json` as your initial domain mapping file.
+- Call 'use_mapping' to test out how the initial mapping behaves on the current metadata
+- Use MCP tools to manipulate the initial mapping when adding and removing record type mappings, or unmapping fields or mapping simple fields. 
+    For more complex field mappings you may edit the mapping file directly. 
+    Refer to the `initial_mappings_schema.yaml` for its proper format.
+    - If doing so, always use 'use_mapping' to verify the mapping file is still valid.
+```
+
+Adjust file paths according to your project structure.
+
+## Available operations
+
+The MCP server provides tools for:
+
+- Testing mappings against metadata
+- Adding and removing record type mappings
+- Field mapping and unmapping operations
+- Validation of mapping file structure
+- Testing initial domain mapping files against local metadata files
+