@appland/appmap 3.168.0 → 3.169.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [@appland/appmap-v3.169.0](https://github.com/getappmap/appmap-js/compare/@appland/appmap-v3.168.1...@appland/appmap-v3.169.0) (2024-10-08)
+
+
+### Features
+
+* Update @appland/navie to v1.33.0 ([5c14b1c](https://github.com/getappmap/appmap-js/commit/5c14b1c78923105bf81d4da592e5f3b4b849495f))
+
+# [@appland/appmap-v3.168.1](https://github.com/getappmap/appmap-js/compare/@appland/appmap-v3.168.0...@appland/appmap-v3.168.1) (2024-10-07)
+
+
+### Bug Fixes
+
+* mjs file is not binary data ([5c26aed](https://github.com/getappmap/appmap-js/commit/5c26aedea2e587571fee4732cea00f72abad052e))
+
 # [@appland/appmap-v3.168.0](https://github.com/getappmap/appmap-js/compare/@appland/appmap-v3.167.0...@appland/appmap-v3.168.0) (2024-10-06)
 
 

package/built/docs/appmap-docs.md

@@ -18,7 +18,7 @@ By using AppMap data, Navie is the first AI code architect with the context to u
 
 Over 90,000 software developers are using the [AppMap extension for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap) and the [AppMap plugin for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap).
 
-<a class="btn btn-primary btn-lg" href="/docs/get-started-with-appmap/">Get Started with AppMap</a>
+<a class="btn btn-primary btn-lg" href="/docs/get-started-with-appmap/">Get Started</a>
 
 ![AppMap Navie with Sequence diagram in Visual Studio Code](/assets/img/docs/vscode-with-navie-prompt.webp)
 _AppMap Navie with Sequence diagram in Visual Studio Code_

package/built/docs/community.md

@@ -3,7 +3,7 @@ layout: docs
 toc: true
 title: Docs - Community
 description: "Join AppMap's vibrant community on Slack for discussions, issue reporting, and become a contributor."
-redirect_from: [/docs/troubleshooting]
+redirect_from: [/docs/troubleshooting, /community]
 ---
 # Community
 

package/built/docs/get-started-with-appmap/index.md

@@ -6,7 +6,7 @@ toc: true
 redirect_from: [/docs/your-first-15-minutes-with-appmap/, /docs/code-editor-extensions/,/docs/code-editor-extensions/appmap-for-vs-code, /docs/code-editor-extensions/appmap-for-jetbrains,/docs/setup-appmap-in-your-code-editor/index.html]
 ---
 
-# Get Started with AppMap
+# Get Started
 
 <p class="alert alert-info">
 If at any point you would like some help, <a href="/slack">join us in Slack</a>!

package/built/docs/get-started-with-appmap/navie-ai-quickstart.md

@@ -20,7 +20,7 @@ redirect_from: [/docs/setup-appmap-in-your-code-editor/navie-ai-quickstart]
 
 By default, Navie uses an AppMap proxy of the latest OpenAI supported AI models. If you would like to customize your own model, you can leverage a variety of other AI model providers such as [Azure OpenAI](https://appmap.io/docs/navie-reference#azure-openai), [Fireworks.ai](https://appmap.io/docs/navie-reference#fireworks-ai), [LM Studio](https://appmap.io/docs/navie-reference#lm-studio), and more.  
 
-If you have an active GitHub Copilot subscription, you can use Navie with the [Copilot Lanauage Model](/docs/navie-reference#github-copilot-language-model) as a supported backend. Refer to the Navie Copilot documentation for instructions on how to enable.
+If you have an active GitHub Copilot subscription, you can use Navie with the [Copilot Language Model](/docs/navie-reference/navie-bring-your-own-model-examples.html#github-copilot-language-model) as a supported backend. Refer to the [Navie Copilot documentation](/docs/navie-reference/navie-bring-your-own-model-examples.html#github-copilot-language-model) for instructions on how to enable.
 
 ## Open AppMap Navie AI
 
@@ -32,20 +32,21 @@ To open the Navie Chat, open the AppMap plugin in the sidebar menu for your code
 
 ## Ask Navie about your App
 
-You can ask questions about your application with Navie immediately after installing the plugin.  AppMap Data is not required but Navie only has partial information about your project and the answers will not include any runtime specific information. 
+You can ask questions about your application with Navie immediately after installing the plugin. Navie will answer questions based on analysis of your project code. For increased accuracy of more complex projects, you can record AppMap data and Navie will utilize this information as well.
 
 By default, Navie will utilize an OpenAI service hosted by AppMap. If, for data privacy or other reasons, you are do not wish to use the AppMap OpenAI proxy, you can [bring your own OpenAI API key](/docs/using-navie-ai/bring-your-own-model.html#bring-your-own-openai-api-key-byok), or use an [entirely different AI Model](/docs/using-navie-ai/bring-your-own-model.html#ollama), hosted in your environment or hosted locally.
 
-When you ask a question to Navie, it will search through all your AppMap Diagrams (if they exist) for your project to pull in relevant traces, sequence diagrams, and code snippets for analysis. It will then send these code snippets and runtime code sequence diagrams to the Generative AI service along with your question. 
+When you ask a question to Navie, it will search through all the available AppMap data for your project to pull in relevant traces, sequence diagrams, and code snippets for analysis. it will send the selected context to your preferred LLM provider.
 
-Refer to the [Using Navie docs](/docs/using-navie-ai/using-navie) to learn more about the advanced Navie chat commands you can use with your question. 
+To achieve the highest quality results, we suggest using the available command modes when prompting Navie. Simply type `@` into the chat input to access the list of available command modes.
 
-After asking Navie a question, Navie will search through your application source code, finding any relevant code snippets. It will include relevant AppMap Data like sequence diagrams and data flows if they exist for your project. You will see on the right hand side of the Navie window the relevant context from your code included with the question. 
+By default, Navie chat is in a default mode called `@explain`. Other specialized modes are available for generating diagrams, planning work, generating code and tests, and more. Consult [Using Navie docs](/docs/navie-reference/navie-commands.html) for more details on Navie commands.
 
 The Navie UI includes a standard chat window, and a context panel which will include all the context that is included in the query to the AI provider.  This context can include things such as:
 
 **Always available:**  
 - Code Snippets
+- Pinned Content
 
 **If AppMap Data exists:**  
 - Sequence Diagrams

package/built/docs/navie-reference/index.md

@@ -0,0 +1,18 @@
+---
+layout: docs
+title: Docs - Reference
+description: "A reference for AppMap Navie AI"
+toc: true
+step: 1
+---
+
+# Navie Reference
+- [Navie Commands](/docs/navie-reference/navie-commands.html)
+- [Navie Options](/docs/navie-reference/navie-options.html)
+- [Bring Your Own Model Examples](/docs/navie-reference/navie-bring-your-own-model-examples.html)
+- [OpenAI Key Management](/docs/navie-reference/navie-openai-key-management.html)
+- [Accessing Navie Logs](/docs/navie-reference/navie-accessing-logs.html)
+- [GitHub Repository](/docs/navie-reference/navie-github-repository.html)
+- [How Navie Works](/docs/navie-reference/navie-how-it-works.html)
+- [Navie User Interface](/docs/navie-reference/navie-user-interface.html)
+- [Pre-built Libraries for Recording AppMap Data](/docs/navie-reference/navie-pre-built-libraries-for-appmap-data.html)

package/built/docs/navie-reference/navie-accessing-logs.md

@@ -0,0 +1,42 @@
+---
+layout: docs
+title: Docs - Reference
+name: Accessing Navie Logs
+toc: true
+step: 7
+navie-reference: true
+description: "Reference Guide to AppMap Navie AI, how-to guide for accessing logs."
+---
+
+
+# Accessing Navie Logs
+
+## Visual Studio Code
+
+You can access the Navie logs in VS Code by opening the `Output` tab and selecting `AppMap Services` from the list of available output logs.  
+
+To open the Output window, on the menu bar, choose View > Output, or in Windows press `Ctrl+Shift+U` or in Mac use `Shift+Command+U`
+
+![Open View in VS Code](/assets/img/docs/vscode-output-1.webp)
+
+Click on the output log dropdown in the right corner to view a list of all the available output logs. 
+
+![Open Output logs list](/assets/img/docs/vscode-output-2.webp)
+
+Select on the `AppMap: Services` log to view the logs from Navie. 
+
+![Select AppMap Services](/assets/img/docs/vscode-output-3.webp)
+
+## JetBrains
+
+You can enable debug logging of Navie in your JetBrains code editor by first opening `Help` > `Diagnostic Tools` > `Debug Log Settings`. 
+
+![JetBrains Debug Log menu](/assets/img/jetbrains-debug-logs.webp)  
+
+In the `Custom Debug Log Configuration` enter `appland` to enable DEBUG level logging for the AppMap plugin. 
+
+![JetBrains Debug Log Configuration](/assets/img/jetbrains-logging-configuration.webp)  
+
+Next, open `Help` > `Show Log...` will open the IDE log file. 
+
+![JetBrains Debug Show Log](/assets/img/jetbrains-show-log.webp)

package/built/docs/navie-reference/navie-bring-your-own-model-examples.md

@@ -0,0 +1,202 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+description: "Reference Guide to AppMap Navie AI, examples of bring-your-own-llm configurations."
+name: Bring Your Own Model Examples
+navie-reference: true
+toc: true
+step: 5
+---
+
+# Bring Your Own Model Examples
+
+## GitHub Copilot Language Model
+
+Starting with VS Code `1.91` and greater, and with an active GitHub Copilot subscription, you can use Navie with the Copilot Language Model as a supported backend model.  This allows you to leverage the powerful runtime powered Navie AI Architect  with your existing Copilot subscription.  This is the recommended option for users in corporate environments where Copilot is the only approved and supported language model. 
+
+#### Requirements <!-- omit in toc -->
+
+The following items are required to use the GitHub Copilot Language Model with Navie:
+
+- VS Code Version `1.91` or greater
+- AppMap Extension version `v0.123.0` or greater
+- GitHub Copilot VS Code extension must be installed
+- Signed into an active paid or trial GitHub Copilot subscription
+
+#### Setup <!-- omit in toc -->
+
+Open the VS Code Settings, and search for `navie vscode`
+
+<img class="video-screenshot" src="/assets/img/product/navie-copilot-1.webp"/> 
+
+Click the box to use the `VS Code language model...`
+
+After clicking the box to enable the VS Code LM, you'll be instructed to reload your VS Code to enable these changes.
+
+<img class="video-screenshot" src="/assets/img/product/navie-copilot-2.webp"/> 
+
+After VS Code finishes reloading, open the AppMap extension.  
+
+Select `New Navie Chat`, and confirm the model listed is `(via copilot)`
+
+<img class="video-screenshot" src="/assets/img/product/navie-copilot-3.webp"/> 
+
+You'll need to allow the AppMap extension access to the Copilot Language Models.  After asking your first question to Navie, click `Allow` to the popup to allow the necessary access. 
+
+<img class="video-screenshot" src="/assets/img/product/navie-copilot-4.webp"/> 
+
+#### Troubleshooting <!-- omit in toc -->
+
+If you attempt to enable the Copilot language models without the Copilot Extension installed, you'll see the following error in your code editor. 
+
+<img class="video-screenshot" src="/assets/img/product/navie-copilot-5.webp"/> 
+
+Click `Install Copilot` to complete the installation for language model support.
+
+If you have the Copilot extension installed, but have not signed in, you'll see the following notice.
+
+<img class="video-screenshot" src="/assets/img/product/navie-copilot-6.webp"/> 
+
+Click the `Sign in to GitHub` and login with an account that has a valid paid or trial GitHub Copilot subscription.
+
+#### Video Demo  <!-- omit in toc -->
+
+{% include vimeo.html id='992238965' %}
+
+## OpenAI
+
+**Note:** We recommend configuring your OpenAI key using the code editor extension. Follow the [Bring Your Own Key](/docs/using-navie-ai/bring-your-own-model.html#configuring-your-openai-key) docs for instructions.  
+
+Only `OPENAI_API_KEY` needs to be set, other settings can stay default:
+
+| `OPENAI_API_KEY`| `sk-9spQsnE3X7myFHnjgNKKgIcGAdaIG78I3HZB4DFDWQGM` |
+
+When using your own OpenAI API key, you can also modify the OpenAI model for Navie to use.  For example if you wanted to use `gpt-3.5` or use an preview model like `gpt-4-vision-preview`.
+
+| `APPMAP_NAVIE_MODEL`| `gpt-4-vision-preview` |
+
+### Anthropic (Claude)
+
+AppMap supports the Anthropic suite of large language models such as Claude Sonnet or Claude Opus.  
+
+To use AppMap Navie with Anthropic LLMs you need to generate an API key for your account.  
+
+Login to your [Anthropic dashboard](https://console.anthropic.com/dashboard), and choose the option to "Get API Keys"
+
+Click the box to "Create Key"
+
+![Anthropic Create Key](/assets/img/product/create-anthropic-key.webp)
+
+In the next box, give your key an easy to recognize name. 
+
+![Anthropic Key Name](/assets/img/product/give-anthropic-key-name.webp)
+
+In your VS Code or JetBrains editor, configure the following environment variables.  For more details on configuring 
+these environment variables in your VS Code or JetBrains editor, refer to the [AppMap BOYK documentation.](/docs/using-navie-ai/bring-your-own-model.html#configuration)
+
+| `ANTHROPIC_API_KEY`| `sk-ant-api03-8SgtgQrGB0vTSsB_DeeIZHvDrfmrg` |
+| `APPMAP_NAVIE_MODEL`| `claude-3-5-sonnet-20240620` |
+
+
+When setting the `APPMAP_NAVIE_MODEL` refer to the [Anthropic documentation](https://docs.anthropic.com/en/docs/intro-to-claude#model-options) for the latest available models to chose from. 
+
+#### Video Demo  <!-- omit in toc -->
+
+{% include vimeo.html id='1003330117' %}
+
+## Azure OpenAI
+
+Assuming you [created](https://learn.microsoft.com/en-us/azure/ai-services/openai/how-to/create-resource) a `navie` GPT-4 deployment on `contoso.openai.azure.com` OpenAI instance:
+
+| `AZURE_OPENAI_API_KEY` | `e50edc22e83f01802893d654c4268c4f` |
+| `AZURE_OPENAI_API_VERSION` | `2024-02-01` |
+| `AZURE_OPENAI_API_INSTANCE_NAME` | `contoso` |
+| `AZURE_OPENAI_API_DEPLOYMENT_NAME` | `navie` |
+
+## AnyScale Endpoints
+
+[AnyScale Endpoints](https://www.anyscale.com/endpoints) allows querying a
+selection of open-source LLMs. After you create an account you can use it by
+setting:
+
+| `OPENAI_API_KEY` | `esecret_myxfwgl1iinbz9q5hkexemk8f4xhcou8` |
+| `OPENAI_BASE_URL` | `https://api.endpoints.anyscale.com/v1` |
+| `APPMAP_NAVIE_MODEL` | `mistralai/Mixtral-8x7B-Instruct-v0.1` |
+
+Consult [AnyScale documentation](https://docs.endpoints.anyscale.com/) for model
+names. Note we recommend using Mixtral models with Navie.
+
+#### Anyscale Demo with VS Code  <!-- omit in toc -->
+
+{% include vimeo.html id='970914908' %}
+
+#### Anyscale Demo with JetBrains  <!-- omit in toc -->
+
+{% include vimeo.html id='970914884' %}
+
+## Fireworks AI
+
+You can use [Fireworks AI](https://fireworks.ai/) and their serverless or on-demand 
+models as a compatible backend for AppMap Navie AI.
+
+After creating an account on Fireworks AI you can configure your Navie environment
+settings:
+
+| `OPENAI_API_KEY` | `WBYq2mKlK8I16ha21k233k2EwzGAJy3e0CLmtNZadJ6byfpu7c` |
+| `OPENAI_BASE_URL` | `https://api.fireworks.ai/inference/v1` |
+| `APPMAP_NAVIE_MODEL` | `accounts/fireworks/models/mixtral-8x22b-instruct` |
+
+Consult the [Fireworks AI documentation](https://fireworks.ai/models) for a full list of 
+the available models they currently support. 
+
+#### Video Demo  <!-- omit in toc -->
+
+{% include vimeo.html id='992941358' %}
+
+### Ollama
+
+You can use [Ollama](https://ollama.com/) to run Navie with local models; after
+you've successfully ran a model with `ollama run` command, you can configure
+Navie to use it:
+
+| `OPENAI_API_KEY` | `dummy` |
+| `OPENAI_BASE_URL` | `http://127.0.0.1:11434/v1` |
+| `APPMAP_NAVIE_MODEL` | `mixtral` |
+
+**Note:** Even though it's running locally a dummy placeholder API key is still required.
+
+## LM Studio
+
+You can use [LM Studio](https://lmstudio.ai/) to run Navie with local models. 
+
+After downloading a model to run, select the option to run a local server.
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-run-local-server.webp"/> 
+
+In the next window, select which model you want to load into the local inference server.
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-load-model.webp"/> 
+
+After loading your model, you can confirm it's successfully running in the logs.  
+
+*NOTE*: Save the URL it's running under to use for `OPENAI_BASE_URL` environment variable.
+
+For example: `http://localhost:1234/v1`
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-confirm-running.webp"/>
+
+In the `Model Inspector` copy the name of the model and use this for the `APPMAP_NAVIE_MODEL` environment variable.
+
+For example: `Meta-Llama-3-8B-Instruct-imatrix`
+
+<img class="video-screenshot" src="/assets/img/product/lmstudio-model-inspector.webp"/>
+
+Continue to configure your local environment with the following environment variables based on your LM Studio configuration.  Refer to the [documentation above](#bring-your-own-model-byom) for steps specific to your code editor.
+
+| `OPENAI_API_KEY` | `dummy` |
+| `OPENAI_BASE_URL` | `http://localhost:1234/v1` |
+| `APPMAP_NAVIE_MODEL` | `Meta-Llama-3-8B-Instruct-imatrix` |
+
+**Note:** Even though it's running locally a dummy placeholder API key is still required.
+
+{% include vimeo.html id='969002308' %}

package/built/docs/navie-reference/navie-commands.md

@@ -0,0 +1,119 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+description: "Reference Guide to AppMap Navie AI, a complete list of the available commands in AppMap Navie AI."
+name: Navie Commands
+navie-reference: true
+toc: true
+step: 3
+---
+
+# Navie Commands
+
+You can ask free-form questions, or start your question with one of these commands:
+
+- [`@plan`](#plan)
+- [`@generate`](#generate)
+- [`@test`](#test)
+- [`@explain`](#explain)
+- [`@diagram`](#diagram)
+- [`@help`](#help)
+
+## @plan
+
+The `@plan` command prefix within Navie focuses the AI response on building a detailed implementation plan for the relevant query.  This will focus Navie on only understanding the problem and the application to generate a step-by-step plan. This will generally not respond with code implementation details, consider using the `@generate` command which can implement code based on the plan.
+
+#### Examples <!-- omit in toc -->
+
+- @plan improve the performance of my slow product listing page.  
+- @plan implement a cache key for my user posting on my social media application.  
+- @plan migrate the /users/setting API endpoint from SQL to MongoDB.  
+
+#### `@plan` Video Demo <!-- omit in toc -->
+
+{% include vimeo.html id='985121150' %}
+
+## @generate
+
+The `@generate` prefix will focus the Navie AI response to optimize for new code creation.  This is useful when you want the Navie AI to respond with code implementations across your entire code base. This will reduce the amount of code explanation and generally the AI will respond only with the specific files and functions that need to be changed in order to implement a specific plan.
+
+#### Examples <!-- omit in toc -->
+
+- @generate Using the django-simple-captcha library add the necessary code for an offline captcha to my new user registration page.
+- @generate Update the function for the physical flow export to include data type via physical_spec_data_type and physical_specification tables without changing the existing functionality.
+- @generate Design and implement a cache key for user posts and show me how to implement it within this code base
+
+#### `@generate` Video Demo <!-- omit in toc -->
+
+{% include vimeo.html id='985121150' %}
+
+## @test
+
+The `@test` command prefix will focus the Navie AI response to optimize for test case creation, such as unit testing or integration testing.  This prefix will understand how your tests are currently written and provide updated tests based on features or code that is provided.  You can use this command along with the `@generate` command to create tests cases for newly generated code.
+
+#### Examples <!-- omit in toc -->
+
+- @test create integration test cases for the user setting page that is migrated to mongodb.  
+- @test create unit and integration tests that fully support the updated cache key functionality.  
+- @test provide detailed test cases examples for testing the updated user billing settings dashboard.  
+
+## @explain
+
+The `@explain` command prefix within Navie serves as a default option focused on helping you learn more about your project. Using the `@explain` prefix will focus the Navie AI response to be more explanatory and will dive into architectural level questions across your entire code base. You can also use this to ask for ways to improve the performance of a feature as well. 
+
+#### Examples <!-- omit in toc -->
+
+- @explain how does user authentication work in this project?
+- @explain how is the export request for physical flows handled, and what are the tables involved?
+- @explain how does the products listing page works and how can I improve the performance?
+
+## @diagram
+
+The `@diagram` command prefix within Navie focuses the AI response to generate Mermaid compatible diagrams.  [Mermaid](https://mermaid.js.org/) is an open source diagramming and charting utility with wide support across tools such as GitHub, Atlassian, and more.  Use the `@diagram` command, and Navie will create and render a Mermaid compatible diagram within the Navie chat window.  You can open this diagram in the [Mermaid Live Editor](https://mermaid.live), copy the Mermaid Definitions to your clipboard, save to disk, or expand a full window view.  Save the Mermaid diagram into any supported tool such as GitHub Issues, Atlassian Confluence, and more. 
+
+#### Example Questions <!-- omit in toc -->
+
+```
+@diagram the functional steps involved when a new user registers for the service.
+```
+  
+<img class="video-screenshot" src="/assets/img/product/sequence-diagram-navie.webp"/> 
+ 
+```
+@diagram the entity relationships between products and other important data objects.
+```
+
+<img class="video-screenshot" src="/assets/img/product/entity-relationship-navie.webp"/> 
+
+```
+@diagram using a flow chart how product sales tax is calculated.
+```
+
+<img class="video-screenshot" src="/assets/img/product/flow-chart-navie.webp"/> 
+
+```
+@diagram create a detailed class map of the users, stores, products and other associated classes used
+```
+
+<img class="video-screenshot" src="/assets/img/product/class-map-navie.webp"/> 
+
+#### Example Diagram Projects <!-- omit in toc -->
+
+Below are a series of open source projects you can use to try out the `@diagram` feature using 
+prebuilt AppMap data in a sample project. Simply clone one of the following projects, open 
+into your code editor with the AppMap extension installed, and ask Navie to generate diagrams.
+
+- [Sample Python Project](https://github.com/land-of-apps/python-diagram-example/blob/master/README.md)
+- [Sample Ruby Project](https://github.com/land-of-apps/rails-diagram-example/blob/main/README.md)
+- [Sample Node (MERN) Project](https://github.com/land-of-apps/mern-diagram-example/blob/master/README.md)
+- [Sample Java Spring Project](https://github.com/land-of-apps/waltz/blob/demo/diagram-examples/demo/diagram-demo.md)
+
+## @help
+
+Navie will help you setup AppMap, including generating AppMap recordings and diagrams.  This prefix will focus the Navie AI response to be more specific towards help with using AppMap products and features.  This will leverage the [AppMap documentation](https://appmap.io/docs) as part of the context related to your question and provide guidance for using AppMap features or diving into advanced AppMap topics. 
+
+#### Examples <!-- omit in toc -->
+
+- @help how do I setup process recording for my node.js project?
+- @help how can I reduce the size of my large AppMap Data recordings?
+- @help how can i export my AppMap data to atlassian confluence? 

package/built/docs/navie-reference/navie-github-repository.md

@@ -0,0 +1,12 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+description: "Reference Guide to AppMap Navie AI, a link to the code repository for AppMap Navie AI."
+name: GitHub Repository
+navie-reference: true
+step: 8
+---
+
+### GitHub Repository
+
+[https://github.com/getappmap/appmap](https://github.com/getappmap/appmap)

package/built/docs/{using-navie-ai/how-navie-works.md → navie-reference/navie-how-it-works.md}

@@ -1,10 +1,11 @@
 ---
 layout: docs
 title: Docs - AppMap Navie
-description: "Enhance Generative AI models with AppMap Navie. Navie leverages RAG to provide accurate answers by searching locally stored AppMap Data for relevant code snippets and application insights."
+description: "Reference Guide to AppMap Navie AI, architectural overview of AppMap Navie AI."
 name: How Navie Works
-step: 1
-navie: true
+navie-reference: true
+step: 10
+toc: true
 ---
 
 # How Navie Works
@@ -18,7 +19,7 @@ This powerful technique provides the AI with many valuable pieces of information
 4) Detailed insights into data flows, SQL queries, and other database interactions.  
 
 
-## Navie Technical Architecture
+### Navie Technical Architecture
 
 Navie integrates seamlessly into your existing AppMap enabled project.  Once you have the AppMap software libraries installed into your project, interact with your application or run tests to automatically generate AppMap Data. All of your code and AppMap Data will stay locally in your environment until you ask Navie a question.  After asking a question to Navie, the relevant AppMap Diagrams and code snippets are located locally by the AppMap search and explain API, then this data is sent to OpenAI (available option to bring your own LLM), and the response is returned to the user. 
 

package/built/docs/navie-reference/navie-openai-key-management.md

@@ -0,0 +1,83 @@
+---
+layout: docs
+title: Docs - AppMap Navie
+description: "Reference Guide to AppMap Navie AI, OpenAI Key Management."
+name: OpenAI Key Management
+navie-reference: true
+toc: true
+step: 6
+---
+
+# OpenAI Key Management
+
+## Visual Studio Code
+
+### Add a new OpenAI Key in VS Code 
+
+The standard way to add an OpenAI API key in VS Code is to use the `gear` icon in the Navie chat window, but you can alternatively set the key using the VS Code Command Palette with an `AppMap` command option.
+
+In VS Code, open the Command Palette.
+
+You can use a hotkey to open the VS Code Command Palette
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+Or you can select `View` -> `Command Palette`
+
+<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
+
+Search for `AppMap Set OpenAPI Key`
+
+<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
+
+Paste your key into the new field and hit enter.
+
+You'll get a notification in VS Code that your key is set. 
+
+**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
+
+<img class="video-screenshot" src="/assets/img/product/byok-key-set.webp"/> 
+
+### Delete a configured OpenAI Key
+
+To delete your key, simply open the Command Palette
+
+You can use a hotkey to open
+   - Mac: `Cmd + Shift + P`
+   - Windows/Linux: `Ctrl + Shift + P`
+
+Or you can select `View` -> `Command Palette`
+
+<img class="video-screenshot" src="/assets/img/product/byok-command-palette.webp"/> 
+
+Search for `AppMap Set OpenAPI Key`
+
+<img class="video-screenshot" src="/assets/img/product/byok-search.webp"/> 
+
+And simply hit enter with the field blank.  VS Code will notify you that the key has been unset.
+
+**NOTE:** You will need to reload your window for the setting to take effect. Use the Command Palette `Developer: Reload Window`
+
+<img class="video-screenshot" src="/assets/img/product/byok-key-erased.webp"/> 
+
+### How is my API key saved securely?
+
+For secure storage of API key secrets within AppMap, we use the default VS Code secret storage which leverages  Electron's safeStorage API to ensure the confidentiality of sensitive information. Upon encryption, secrets are stored within the user data directory in a SQLite database, alongside other VS Code state information. This encryption process involves generating a unique encryption key, which, on macOS, is securely stored within `Keychain Access` under "Code Safe Storage" or "Code - Insiders Safe Storage," depending on the version. This method provides a robust layer of protection, preventing unauthorized access by other applications or users with full disk access. The safeStorage API, accessible in the main process, supports operations such as checking encryption availability, encrypting and decrypting strings, and selecting storage backends on Linux. This approach ensures that your secrets are securely encrypted and stored, safeguarding them from potential threats while maintaining application integrity.
+
+## JetBrains
+
+The standard way to add an OpenAI API key in JetBrains is to use the `gear` icon in the Navie chat window, but you can alternatively set the key directly in the JetBrains settings. 
+
+### Adding or Modifying OpenAI API Key in JetBrains
+
+In JetBrains, open the `Settings` option. 
+
+![Open View in VS Code](/assets/img/docs/jetbrains-settings-1.webp)
+
+In the `Settings` window, search for `appmap` in the search bar on the side.  Under the `Tools -> AppMap` you will see a configuration option for your OpenAI API Key in the `AppMap Services` section.  This is the same section you are able to add/edit/modify your other environment settings for using your own custom models. 
+
+![Open View in VS Code](/assets/img/docs/jetbrains-settings-2.webp)
+
+### How is my API key saved securely?
+
+AppMap follows JetBrains best practices for the storing of sensitive data. The AppMap JetBrains plugin uses the `PasswordSafe` package [to securely persist](https://www.jetbrains.com/help/idea/reference-ide-settings-password-safe.html) your OpenAI API key.  The default storage format for `PasswordSafe` is operating system dependent. Refer to the [JetBrains Developer Documents](https://plugins.jetbrains.com/docs/intellij/persisting-sensitive-data.html#storage) for more information.