chore: Move chef-cli docs to fern

fern/docs/pages/airdrop/data-extraction.mdx

@@ -1,4 +1,3 @@
-
 In the data extraction phase, the extractor is expected to call the external system's APIs
 to retrieve all the items that were updated since the start of the last extraction.
 If there was no previous extraction (the current run is an initial import),
@@ -43,12 +42,11 @@ Each artifact is submitted with an `item_type`, defining a separate domain objec
 external system and matching the `record_type` in the provided metadata.
 Item types defined when uploading extracted data must validate the declarations in the metadata file.
 
-Extracted data must be normalized.
-
+Extracted data must be normalized:
 - Null values: All fields without a value should either be omitted or set to null.
-For example, if an external system provides values such as "", -1 for missing values,
+For example, if an external system provides values such as "", –1 for missing values,
 those must be set to null.
-- Timestamps: Full-precision timestamps should be formatted as RFC3999 (`1972-03-29T22:04:47+01:00`),
+- Timestamps: Full-precision timestamps should be formatted as RFC3339 (`1972-03-29T22:04:47+01:00`),
 and dates should be just `2020-12-31`.
 - References: references must be strings, not numbers or objects.
 - Number fields must be valid JSON numbers (not strings).
@@ -58,7 +56,7 @@ Each line of the file contains an `id` and the optional `created_date` and `modi
 in the beginning of the record.
 All other fields are contained within the `data` attribute.
 
-```json
+```json {2-4}
 {
     "id": "2102e01F",
     "created_date": "1972-03-29T22:04:47+01:00",
@@ -74,9 +72,26 @@ All other fields are contained within the `data` attribute.
 }
 ```
 
+## Validating extracted data
+
+Extracted artifacts can be validated with the chef-cli using the following command:
+
+```bash
+chef-cli validate-data -m external_domain_metadata.json -r issue < extractor_issues_2.json
+```
 
-Extracted artifacts can be validated with the `chef-cli` using the following command:
+You can also generate example data to show the format the data has to be normalized to, using:
 
 ```bash
-$ chef-cli validate-metadata -m external_domain_metadata.json -r issue < extractor_issues_2.json
+echo '{}' | chef-cli fuzz-extracted -r issue -m external_domain_metadata.json > example_issues.json
 ```
+
+## Deploying and testing the snap-in
+
+Once you have implemented data extraction, you should deploy your snap-in to your test organization and run an import.
+
+To deploy the snap-in, run `make auth` and `make deploy` in the snap-in repository. Then, activate the snap-in by running `devrev snap_in activate`. 
+
+After activation, you can create an import in the DevRev UI, which will initially reach the 'waiting for user input' stage. During this phase, you can verify your data extraction implementation is working correctly.
+
+Relevant documentation can be found under [Snap-in development](/snapin-development/locally-testing-snap-ins).

fern/docs/pages/airdrop/data-model/mapping_reasons.mdx

@@ -0,0 +1,42 @@
+
+Airdrop uses transformation methods to map data from one format to another. 
+These methods work on field scope and each have their own requirements. 
+If the data does not meet these requirements, the mapping is not available.
+
+There are several reasons why some mappings might be unavailable.
+
+1. A common reason is mismatch of types. For example, if a DevRev field is expected to be `rich_text`, 
+but the field is set as `text` mapping to some fields is unavailable. 
+Refer to the [supported types](../metadata-extraction.mdx#declare-fields-for-each-record-type) 
+section and the general DevRev documentation for more information.
+2. Only references can be mapped to references. Ensure that source system fields are correctly 
+mapped to reference fields in DevRev.
+3. Currently, support for the `struct` type is limited. Marking a field as a struct in the metadata schema will 
+make it unavailable for mapping outside of using the custom jq transformation method. 
+Refer to the [metadata tips](../faq.mdx#metadata-extraction) for more information.
+4. Links are supported only on works and conversations.
+
+The following transformation methods are provided for **custom fields**:
+1. `make_constrained_simple_value` a simple method that along with mapping allows you to propagate validation constraints from the external system and enforces those in DevRev.
+2. `make_enum` produces an enum field, where external field should be of type enum.
+3. `make_uenum` produces an enum field, where external field should be of type enum.
+4. `reference_custom_field` produces a reference field, where external field should be of type reference.
+
+The following transformation methods are provided for Metadata extraction:
+1. `make_custom_stages` makes custom stages in accordance with the stage diagram data provided in the domain metadata.
+2. `map_enum` produces an enum field, where the external field should be of type enum.
+3. `map_roles` maps permission roles from external to DevRev format.
+4. `use_as_array_value` produces an array field from a scalar (single-value) external field.
+5. `use_devrev_record` enables use of a fixed reference to something in DevRev, where Don should be of right type.
+6. `use_directly` is the identity operator, it returns exactly the input, where external field should be of the same 
+type as the DevRev field. If external field is an array (is marked as collection) internal field has to be an array as well.
+7. `use_fixed_value` produces a fixed value in DevRev, which is useful to map required DevRev fields if source system doesn't have an equivalent field. Only available for boolean or enum DevRev fields
+
+The following transformation methods are provided for both **custom and stock fields**:
+1. `use_rich_text` produces a rich text field, where external field should be of type `rich_text`.
+
+The following transformation methods are available for **constructed custom fields**:
+1. `construct_text_field` produces a text field, where external field should be of type text.
+
+`use_raw_jq` can be used on all fields. It enables the use of `jq` to transform data and should be used sparingly
+if no other transformation method is available.

fern/docs/pages/airdrop/data-model/permissions.mdx

@@ -0,0 +1,30 @@
+DevRev uses the concept of permissions to control access to records. 
+Permissions are associated with users or groups and define the level of access they have to leaf types and their fields.
+
+## Article permissions
+
+{/* TODO: more on article permissions */}
+Articles can be shared with users or groups. 
+
+The `shared_with` field allows to specify the permission level for each user or group using the `permission` type. 
+The `permission` type is a special structure associating a reference to an user-like record type (the field `member_id`)
+with an `enum` value that provides the user with the role or permission level.
+
+## Platform Groups
+
+Platform groups are groups automatically created by the DevRev platform for every organization. 
+For example, DevRev provides *Dev users* and *Rev users* groups that contain all the Dev and Rev users respectively.
+
+We allow developers to map their external default groups to platform groups. 
+This functionality allows for flexible integration with the platform's permission system while allowing for re-mapping by the end user. 
+
+### Implementation Guide
+
+1. Developers need to create a mapping between their external default groups and the platform's 
+internal default groups using a new mapping object. 
+   - To do this define a new object in external metadata. 
+   - The object should have one enum field with the possible values being the default groups available in external system.  
+2. Developers can use initial domain mapping to map their object to the *platform groups* object in devrev.
+3. The platform groups object can be referenced in other objects, for example in the `shared_with` field of articles.
+
+{/* ### Authorization policy */}

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

@@ -0,0 +1,138 @@
+
+Rich text is used in DevRev to represent text fields that can be formatted and can contain mentions. E.g.: description of an issue, body of a conversation, etc.
+
+A simple rich text looks like one markdown string wrapped in an array: `["Hello **world**!"]`.
+Markdown should be compatible with [CommonMark Spec v0.30](https://spec.commonmark.org/0.30).
+
+## Rich text mentions
+
+To support mentions, `rich_text` can be formatted as an array of strings and mention objects like so:  
+```json
+[
+  "Hello ", 
+  {"ref_type":"external_user_type", "id":"1...", "fallback_record_name": "John Doe"}, 
+  "how are you?"
+]
+```
+
+
+Mention represents any mention (user, issue, etc.) in rich text and is defined as:
+| Field                  | Type   | Required | Description                                                                                                                          |
+| ---------------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| `id`                   | String | Yes      | Identifier of the item being mentioned. This could be a user ID or any other identifier, in the format used by the source system.    |
+| `ref_type`             | String | Yes      | Type of the item being mentioned. Examples include "issue", "comment", etc. The recipe converts this according to user mappings. |
+| `fallback_record_name` | String | No       | The text to display if the mention cannot be resolved. This could be a user's display name or a ticket title, for instance.          |
+
+In reverse, the loader should expect the following structure:
+```json
+{
+  "type": "rich_text",
+  "content": [
+    "Hello ",
+    {
+      "ref_type": "external_user_type",
+      "id": "don:identity:dvrv-us-1:devo/xyz:devu/1",
+      "fallback_record_name": "John Smith"
+    },
+    "how are you?"
+  ]
+}
+```
+
+## Importing articles
+
+An article is a document containing essential information about the company's products, services, and processes. Articles support Markdown as well as HTML.
+
+Articles support mentions to artifacts and articles. An inline attachment must be mapped to an artifact. A link to another article must be mapped to an article.
+
+### Managing permissions
+
+You can manage article permissions in the `shared_with` field. Permissions can reference users, groups, and [platform groups](./platform_groups.md).
+
+### Inline attachments
+If an inline attachment is hosted in the source system, it must be created as an artifact in DevRev. 
+The same link cannot be used as the attachment is deleted in the source system when our customers deactivate the account.
+However, creating an artifact is not enough. The artifact must be linked in the appropriate place in the article content. 
+
+The following HTML example shows an inline attachment:
+```html
+<img src="don:core:dvrv-us-1:devo/0:artifact/1" alt="Alt Text"/>
+```
+
+The following Markdown example shows an inline attachment:
+```markdown
+![Alt Text](don:core:dvrv-us-1:devo/0:artifact/1)
+```
+
+Let's say the content of your external system looks like this:
+```html
+<p>This is an article with one image.</p>
+<p><img src="https://devrev.zendesk.com/hc/article_attachments/29908544740244" alt="download.jpeg"></p>
+```
+
+The content in DevRev should look like this:
+```html
+<p>This is an article with one image.</p>
+<p><img src="don:core:dvrv-us-1:devo/0:artifact/1" alt="download.jpeg"></p>
+```
+
+`don:core:dvrv-us-1:devo/0:artifact/1` is the ID of the artifact created in DevRev corresponding to the attachment with ID `29908544740244` in the external source system.
+To achieve this, you need to transform the content of the article to the following JSON:
+```json
+[ 
+    "<p>This is an article with one image.</p><p><img src=\"",
+    {
+        "ref_type": "artifact",
+        "id": "29908544740244",
+        "fallback_record_name": "<fallback link>"
+    },
+    "\" alt=\"download.jpeg\"></p>" 
+]
+```
+
+The `ref_type` should be set to artifact and the ID should be the ID of the attachment in the external source system. The platform replaces the mention block with the ID of the corresponding artifact. The resolved value is not wrapped in double quotes.
+
+### Links to other articles
+If there is a link to another article in the content of the article, you need to create a mention to the article. 
+The link must be to an article that was either created in previous syncs or is created in the current sync. 
+At the extractor stage, it is impossible to predict the ID of the article that is created in DevRev. This is why the platform handles this. This feature is only available for the HTML format. 
+However, since Markdown can contain HTML, you can use the same approach for Markdown as well.
+
+The following HTML example shows a link to another article:
+```html
+<a data-article-id="don:core:dvrv-us-1:devo/0:article/10" href="/ART-10" target="_self">Contact our Support Team</a>
+```
+
+Let's say the content of your external system looks like this:
+```html
+<p>
+You can create an account and log-in <a href="https://devrev.zendesk.com/hc/en-us/articles/360059607772" target="_self">only</a> with the company email.
+</p>
+```
+
+The content in DevRev should look like this:
+```html
+<p>
+You can create an account and log-in <a data-article-id="don:core:dvrv-us-1:devo/0:article/10" href="/ART-10" target="_self">only</a> with the company email.
+</p>
+```
+
+`don:core:dvrv-us-1:devo/0:article/10` is the ID of the article created in DevRev corresponding to the article with ID `360059607772` in the external source system.
+To achieve this, you need to transform the content of the article to the following JSON:
+```json
+[
+    "You can create an account and log-in <a data-article-id=\"",
+    {
+        "ref_type": "article",
+        "id": "360059607772",
+        "fallback_record_name": "<fallback article ID>"
+    },
+    "\" target=\"_self\"> only</a> with the company email."
+]
+```
+
+The `ref_type` should be set to the item type in the external system that is being mapped to articles. 
+For example, if you're importing documents from the external system as articles, 
+the `ref_type` should be set to documents. The ID should be the ID of the item in the external source system. 
+
+The platform replaces the mention block with the ID of the corresponding article in DevRev as well as adds the href attribute with the appropriate value.