@appland/appmap 3.140.1 → 3.141.0

package/built/docs/guides/navigating-code-objects.md

@@ -0,0 +1,67 @@
+---
+layout: docs
+title: Docs - Guides
+description: "Explore AppMap's Code Objects view to navigate code functions, HTTP requests, and SQL queries across all AppMap Diagrams."
+guides: true
+name: Navigating Code Objects
+step: 3
+redirect_from: [/docs/your-first-15-minutes-with-appmap/navigating-code-objects, /docs/setup-appmap-in-your-code-editor/navigating-code-objects]
+---
+
+# Navigating Code Objects
+{% include vimeo.html id='916048582' %}
+
+---
+
+**In this video**  
+Dive into the Code objects view, a high level view of code functions,  HTTP requests, and SQL queries across the entire set of your AppMap Diagrams and learn how to locate and navigate to an AppMap from code reference pins on your code functions. 
+
+**Links mentioned**  
+[Rails Sample Application](https://github.com/land-of-apps/sample_app_6th_ed/tree/codespaces-devcontainer)
+
+---
+## Follow along
+
+Welcome to AppMap, In this tutorial we will be diving into advanced navigation of AppMap Diagrams - the Code Objects view. We’ll answer the question, “What if I have a lot of AppMap Diagrams and I don’t know where exactly to look?” 
+
+In this view, we collect all the different code functions and  HTTP server requests and SQL queries all into one list. Every request, query, and function call that occurs anywhere in the whole set of AppMap Diagrams will be in this list. 
+
+## Code Objects View
+
+There are three sections to the Code Objects view. The first section is the Code view, this will show packages, classes, and functions, it will show the framework code as well as my code, essentially everything present within your AppMap Diagrams. We can click on a function to navigate directly to the code. In this example, I’ll navigate to my Application controllers, and view the Microposts controller. This will take me directly to the code for this function. This is a great way to see more comprehensively what you have across your code base. 
+
+<img class="video-screenshot" src="/assets/img/docs/first-fifteen-minutes/code-objects-view.webp"/>
+
+## HTTP Routes List
+
+In the HTTP Service request list, you can see basically a mini spec file showing you what routes are available across all of your AppMap Diagrams. 
+
+If this route only exists in a single AppMap, you’ll be taken directly to the AppMap for this request, but if the route exists in multiple diagrams you’ll get a VScode picker to choose which one to open. 
+
+Here is this route, and here it is shown in a trace view, and you’ll see the status code for that is 302 which is a redirect.
+
+<img class="video-screenshot" src="/assets/img/docs/first-fifteen-minutes/code-objects-trace-view.webp"/>
+
+## SQL Query List
+
+The final section of Code Objects is a list of all the SQL queries across your AppMap Diagrams. Just like before, if you click into it and it is unique across your AppMap set then you’ll be sent directly to the AppMap or the quick picker will prompt you to open one. 
+
+The code view is a handy way to navigate your code base, similar to the file view you’d get in VS Code except this code view will only show the code that participated in your test case recordings or remote recordings.
+
+But it’s more common to simply be navigating within the code itself. So what if you want to get to the AppMap Diagram from within the code?
+
+## Opening AppMap Diagrams from code object names
+
+The command “Open code object in AppMap” can be used to find and open all the AppMap Diagrams that contain a particular code object (package, class, or function name).
+
+<img class="video-screenshot" src="/assets/img/docs/first-fifteen-minutes/code-object-command-palette.webp"/>
+
+To get here in VS Code open the command palette. 
+
+On Mac:
+`Shift + Command + P`
+
+On Windows/Linux:
+`Ctrl + Shift + P`
+
+I can then search for the `UsersController#show` function - if it's in a single AppMap I’ll get taken directly to that AppMap. If it exists in more than one you’ll get the quick picker to choose which one you want.

package/built/docs/guides/openapi.md

@@ -4,7 +4,7 @@ title: Docs - Guides
 description: "Use AppMap to auto generate OpenAPI definitions and document HTTP APIs. AppMap captures runtime behavior, creating accurate API schemas effortlessly."
 guides: true
 name: Generating OpenAPI Definitions
-step: 6
+step: 7
 redirect_from: [/docs/openapi,/docs/openapi/features,/docs/openapi/code-editor-extensions,/docs/openapi/integrations,/docs/openapi/customization,/docs/reference/openapi]
 ---
 

package/built/docs/guides/reading-sql-in-appmap-diagrams.md

@@ -4,7 +4,7 @@ title: Docs - Guides
 description: "Discover SQL commands in AppMap Diagrams to analyze application logic's database interactions, spot inefficiencies, and understand code impacts for improved performance and reliability."
 guides: true
 name: Reading SQL in AppMap Diagrams
-step: 4
+step: 5
 redirect_from: [/docs/guides/reading-sql-in-appmaps]
 ---
 

package/built/docs/guides/refine-appmap-data.md

@@ -4,7 +4,7 @@ title: Docs - Guides
 description: "Optimize AppMap Diagrams by refining recordings to exclude noise. Start with inclusive config, analyze stats, update config, create concise AppMap Diagrams."
 guides: true
 name: Refining AppMap Data
-step: 5
+step: 6
 redirect_from: [/docs/reference/refine-appmaps, /docs/guides/refine-appmaps]
 ---
 

package/built/docs/guides/reverse-engineering.md

@@ -3,7 +3,7 @@ layout: docs
 guides: true
 title: Docs - Guides
 description: "Learn to reverse engineer efficiently using AppMap. Capture code execution details effortlessly. Visualize data for insights. Automate AppMap creation and storage for collaboration."
-step: 8
+step: 9
 render_with_liquid: false
 name: Reverse Engineering
 ---
@@ -47,7 +47,7 @@ AppMap is a powerful tool for reverse-engineering legacy code. Unlike telemetry-
 The data can be further combined, compared, and analyzed to obtain key insights about how the code works and how it can be improved. The purpose of this guide is to provide a step-by-step procedure for characterizing a large codebase with AppMap and obtaining these insights.
 
 ## Pre-requisites
-You should first review our guide on [how AppMap works](/docs/setup-appmap-in-your-code-editor/how-appmap-works).
+You should first review our guide on [how to make AppMap Data](/docs/get-started-with-appmap/making-appmap-data).
 
 # Reverse Engineering an Application - A Step by Step Process
 This section provides a procedure for characterizing your code using AppMap. Consider this procedure as a recommendation on how to get started. For your specific needs, you’ll likely find useful ways to extend and customize these recommendations. 

package/built/docs/guides/runtime-code-review.md

@@ -4,7 +4,7 @@ title: Docs - Guides
 description: "AppMap analyzes runtime changes in your codebase for failed tests, API, security, performance issues, and anti-patterns, providing detailed reports."
 guides: true
 name: Understanding the Runtime Code Review Report
-step: 9
+step: 10
 ---
 
 # Understanding the Runtime Code Review Report <!-- omit in toc -->

package/built/docs/guides/{configuring-analysis.md → using-appmap-analysis.md}

@@ -3,13 +3,19 @@ layout: docs
 title: Docs - Guides
 description: "Configure AppMap Analysis by customizing checks for flexible rule options. Understand findings and their properties for effective analysis."
 guides: true
-name: Configuring Analysis
-step: 7
-redirect_from: [docs/analysis/configuring-checks, /docs/analysis/match-pattern-config, /docs/analysis/findings,/docs/reference/configuring-analysis]
+name: Using AppMap Analysis
+step: 8
+redirect_from: [docs/analysis/configuring-checks, /docs/analysis/match-pattern-config, /docs/analysis/findings,/docs/reference/configuring-analysis,/docs/guides/configuring-analysis]
 ---
 
-# Configuring Analysis <!-- omit in toc -->
+# AppMap Analysis
 
+When there is AppMap Data available in your project, AppMap Runtime Analysis will immediately scan them to detect flaws in the code. These flaws are surfaced as **findings** and are displayed in your code editor as you work so that they can be addressed **before** they are propagated to test or production environments.
+
+- [Navigate Findings](#navigate-findings)
+- [Investigate findings](#investigate-findings)
+- [Use labels to visually explore your code](#use-labels-to-visually-explore-your-code)
+- [Configuring Analysis](#configuring-analysis)
 - [Configuring checks](#configuring-checks)
   - [Example appmap-scanner.yml](#example-appmap-scanneryml)
 - [Match pattern config](#match-pattern-config)
@@ -18,8 +24,50 @@ redirect_from: [docs/analysis/configuring-checks, /docs/analysis/match-pattern-c
   - [Properties](#properties)
   - [Finding hash](#finding-hash)
 
+## Navigate Findings
+
+Findings are displayed In the Runtime Analysis sidebar pane sorted by impact category and type.
+
+<image class="video-screenshot" src="/assets/img/docs/runtime-analysis-sidebar-findings.webp"/> 
+
+Clicking the ‘Overview’ link in the Runtime Analysis sidebar will open the ‘Runtime Analysis Summary’ window which contains a summary of findings for a particular project.
+
+<image class="video-screenshot" src="/assets/img/docs/runtime-analysis-overview-dashboard.webp"/> 
+
+{% include vimeo.html id='916087872' %}
+
+---
+
+**In this video**  
+AppMap Analysis scans your AppMap Data to find software design flaws that impact performance, stability, security and maintainability. This runtime code analysis can find the problems that static code analyzers miss - and that cause 90% of today’s most serious production issues.
+
+**Links mentioned**  
+[AppMap Community Slack](/slack)  
+[Get AppMap for VSCode](https://marketplace.visualstudio.com/items?itemName=appland.appmap)  
+[Get AppMap for JetBrains](https://plugins.jetbrains.com/plugin/16701-appmap)
+
+---
+
+## Investigate findings
+
+Let's look at a sample Ruby on rails application, where AppMap has already been installed and AppMap Data has been generated. From the test cases, you'll see a new option for findings in the left-hand column or an option here for investigate findings.
+
+<img class="video-screenshot" src="/assets/img/appmap-analysis-1.webp"/>
+
+You can see one of the issues we've found is that a log event contained secret data by clicking on the finding will be taken directly to the line of code where this event occurs by hovering over the pin.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-2.webp"/>
+
+## Use labels to visually explore your code
+
+You can open the AppMap and see exactly where the function wrote this secret to a log file. How does AppMap know that this was a secret? Unlike static analyzers and other tools that do pattern matching AppMap knows this function generates secrets because we have built in knowledge of common software libraries with pre-populated labels.
+
+We know exactly where to look to avoid false positives. Developers can extend their labels, whether it's a common library or not with simple code comments on their functions.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-3.webp"/>
+
+If you search for the secret label, you'll see the location in the code where this event occurs by clicking on the function, you'll be taken to the exact location of the AppMap, where the secret was generated. Additionally, you can open the code, combining a visual model alongside the code.
+<img class="video-screenshot" src="/assets/img/appmap-analysis-4.webp"/>
 
-## Configuring checks
+## Configuring Analysis Checks
 
 AppMap Analysis is configured in a YAML document. It's primary job is to specify which scanner rules will check the code.
 Each check specifies a rule id, and may include additional properties that customized and tune the behavior of the rule.

package/built/docs/guides/using-appmap-diagrams.md

@@ -5,8 +5,8 @@ description: "Configure AppMap Analysis by customizing checks for flexible rule
 guides: true
 toc: true
 name: Using AppMap Diagrams
-step: 1
-redirect_from: [/docs/how-to-use-appmap-diagrams.html, /docs/how-to-use-appmap-diagrams, /docs/diagrams/how-to-use-appmaps, /docs/diagrams/sequence-diagrams, /docs/diagrams, /docs/diagrams/how-it-works, /docs/diagrams/dependency-map, /docs/diagrams/trace-view, /docs/diagrams/sequence-diagram, /docs/diagrams/flamegraph]
+step: 2
+redirect_from: [/docs/how-to-use-appmap-diagrams.html, /docs/how-to-use-appmap-diagrams, /docs/diagrams/how-to-use-appmaps, /docs/diagrams/sequence-diagrams, /docs/diagrams, /docs/diagrams/how-it-works, /docs/diagrams/dependency-map, /docs/diagrams/trace-view, /docs/diagrams/sequence-diagram, /docs/diagrams/flamegraph, /docs/setup-appmap-in-your-code-editor/navigating-appmap-diagrams]
 ---
 
 # Using AppMap Diagrams <!-- omit in toc -->

package/built/docs/integrations/atlassian-confluence.md

@@ -16,7 +16,7 @@ Confluence facilitates robust documentation and knowledge sharing. AppMap automa
 ## Requirements
 
 1. A project containing AppMap Data.
-  - How to make AppMap Diagrams [in your code editor](/docs/setup-appmap-in-your-code-editor/)
+  - How to make AppMap Diagrams [in your code editor](/docs/get-started-with-appmap/)
   - How to make AppMap Diagrams [using a GitHub action](/docs/integrations/github-actions) or in [CircleCI](/docs/integrations/circle-ci)
 2. [The AppMap app for Confluence](https://marketplace.atlassian.com/apps/1233075/appmap-for-confluence). 
 

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

@@ -1,31 +1,72 @@
 ---
 layout: docs
 title: Docs - Navie
-name: Bring Your Own Key/Model
-step: 4
+name: Bring Your Own LLM Model
+step: 3
 navie: true
 toc: true
 description: Use AppMap Navie with your own OpenAI account or OpenAI-compatible LLM running either locally or remotely.
 redirect_from: [/docs/navie/bring-your-own-llm, /docs/navie/bring-your-own-key]
 ---
 
-# Bring Your Own LLM
-
-By default, when asking a question to Navie, your code editor will interact with the AppMap hosted proxy for OpenAI.  If you have a requirement to bring your own key or otherwise use your own OpenAI account you can specify your own OpenAI key; this will cause Navie
-to connect to OpenAI directly, without AppMap proxy acting as an intermediate.
+# Bring Your Own LLM Model
 
+By default, when asking a question to Navie, your code editor will interact with the AppMap hosted proxy for OpenAI.  If you have a requirement to bring your own key or otherwise use your own OpenAI account you can specify your own OpenAI key; this will cause Navie to connect to OpenAI directly, without AppMap proxy acting as an intermediate.
+- [Navie AI Recommended Models](#navie-ai-recommended-models)
+- [Bring Your Own OpenAI API Key (BYOK)](#bring-your-own-openai-api-key-byok)
+  - [Configuring Your OpenAI Key](#configuring-your-openai-key)
+  - [Reset Navie AI to use Default Navie Backend](#reset-navie-ai-to-use-default-navie-backend)
 - [Bring Your Own Model (BYOM)](#bring-your-own-model-byom)
-- [Configuration](#configuration)
+  - [Configuration](#configuration)
+  - [Configuring in JetBrains](#configuring-in-jetbrains)
+  - [Configuring in VS Code](#configuring-in-vs-code)
 - [Examples](#examples)
-  - [OpenAI.com](#openaicom)
+  - [OpenAI](#openai)
   - [Azure OpenAI](#azure-openai)
   - [AnyScale Endpoints](#anyscale-endpoints)
   - [Ollama](#ollama)
 
+## Navie AI Recommended Models
+
+<p class="alert alert-danger">
+AppMap Navie AI recommends avoiding models that do not support chat mode.
+</p>
+<!-- This doc is located at https://docs.google.com/presentation/d/145gzoYVsgJ3J4jGh_2Or8ClZ0drqoC-GTjI1UqkyF_o/edit#slide=id.g1ff63dc2dd6_0_0 -->
+
+![Navie Recommended Models](/assets/img/product/navie-model-recommendations.svg)
+
+## Bring Your Own OpenAI API Key (BYOK)
+
+Navie AI uses the AppMap hosted proxy with an AppMap managed OpenAI API key. If you have requirements to use your existing OpenAI API key, you can configure that within AppMap. This will ensure all Navie requests will be interacting with your own OpenAI account. 
+
+### Configuring Your OpenAI Key
+
+In your code editor, open the Navie Chat window. If the model displays `(default)`, this means that Navie is configured to use the AppMap hosted OpenAI proxy.  Click on the gear icon in the top of the Navie Chat window to change the model. 
+
+![Navie Recommended Models](/assets/img/product/navie-default-model.webp)
+
+In the modal, select the option to `Use your own OpenAI API key`
+
+![Navie Recommended Models](/assets/img/product/navie-byok-openai-1.webp)
+
+After you enter your OpenAI API Key in the menu option, hit `enter` and your code editor will be prompted to reload.
+
+![Navie Recommended Models](/assets/img/product/navie-byok-openai-2.webp)
+
+After your code editor reloads, you can confirm your requests are being routed to OpenAI directly in the Navie Chat window. It will list the model `OpenAI` and the location, in this case `via OpenAI`.
+
+![Navie Recommended Models](/assets/img/product/navie-byok-openai-3.webp)
+
+### Reset Navie AI to use Default Navie Backend
+
+At any time, you can unset your OpenAI API Key and revert usage back to using the AppMap hosted OpenAI proxy.  Select the gear icon in the Navie Chat window and select `Use Navie Backend` in the modal. 
+
+![Navie Recommended Models](/assets/img/product/navie-use-default-backend.webp)
+
 ## Bring Your Own Model (BYOM)
 
 <p class="alert alert-info">
-<b>This feature is in early access.</b> We will post various comparisons of AppMap with models, we currently recommend GPT4 from OpenAI via Open AI or Microsoft Azure, and Mixtral-8x7B-Instruct-v0.1.  We will update this section with additional models and more benchmarking details, please check back often for updates.
+<b>This feature is in early access.</b> We currently recommend GPT4-Turbo from OpenAI via OpenAI or Microsoft Azure, and Mixtral-8x7B-Instruct-v0.1.  Refer to the <a href="/docs/navie/bring-your-own-model.html#navie-ai-recommended-models">AppMap Recommended Models documentation</a> for more info
 </p>
 
 Another option is to use a different LLM entirely; you can use any OpenAI-compatible model 
@@ -33,10 +74,9 @@ running either locally or remotely. When configured like this, as in the BYOK ca
 Navie won't contact the AppMap hosted proxy and your conversations will stay private
 between you and the model.
 
-## Configuration
+### Configuration
 
 In order to configure Navie for your own LLM, certain environment variables need to be set for AppMap services.
-Please refer to the IDE-specific pages to see how to configure the variables in [VS Code](/docs/navie/byok/vs-code) and [IntelliJ](/docs/navie/byok/intellij).
 
 You can use the following variables to direct Navie to use any LLM with an OpenAI-compatible API.
 If only the API key is set, Navie will connect to OpenAI.com by default.
@@ -53,9 +93,105 @@ For Azure OpenAI, you need to [create a deployment](https://learn.microsoft.com/
 * `AZURE_OPENAI_API_INSTANCE_NAME` — Azure OpenAI instance name (ie. the part of the URL before `openai.azure.com`)
 * `AZURE_OPENAI_API_DEPLOYMENT_NAME` — Azure OpenAI deployment name.
 
+[Configuring in JetBrains](#configuring-byom-in-jetbrains)  
+[Configuring in VS Code](#configuring-byom-in-vs-code)
+
+### Configuring in JetBrains
+
+In JetBrains, go to settings.
+
+<img class="video-screenshot" alt="a screenshot of the JetBrains menu" src="/assets/img/docs/goto-intellij-settings.webp" />
+
+Go to *Tools* → *AppMap*.
+
+<img class="video-screenshot" alt="a screenshot of the AppMap settings in JetBrains" src="/assets/img/docs/intellij-tools-appmap-settings.webp"/>
+
+Enter the environment editor.
+<img class="video-screenshot" alt="a screenshot of the entering the AppMap environment editor in JetBrains" src="/assets/img/docs/intellij-enter-env-editor.webp"/>
+
+Use the editor to define the relevant environment variables according to the [BYOM documentation](/docs/navie/bring-your-own-model#configuration).
+
+<img class="video-screenshot" alt="a screenshot of the environment editor in JetBrains" src="/assets/img/docs/intellij-env-editor.webp" />
+
+**Reload your IDE for the changes to take effect.**
+
+### Configuring in VS Code
+
+#### Editing AppMap services environment
+
+**Note**: To store the API key securely with VS Code secret storage, follow [the instructions below](#add-a-new-openai-key).
+
+In VS Code, go to settings.
+
+<img class="video-screenshot" src="/assets/img/docs/goto-vscode-settings.webp" alt="a screenshot of the Visual Studio Code menu"/>
+
+ Search for “appmap environment” to reveal “AppMap: Command Line Environment” setting.
+
+<img class="video-screenshot" alt="a screenshot of the AppMap: Command Line Environment settings section" src="/assets/img/docs/search-for-appmap-environment.webp"/>
+
+Use *Add Item* to define the relevant environment variables according to the [BYOM documentation](/docs/navie/bring-your-own-model#configuration).
+
+<img class="video-screenshot" alt="a screenshot showing an example of the bring your own model key value entry" src="/assets/img/docs/byom-key-value-example.webp"/>
+
+Reload your VS Code for the changes to take effect.  
+
+**NOTE:** Please follow the instructions below to set `OPENAI_API_KEY` or `AZURE_OPENAI_API_KEY` securely.
+
+#### Add a new OpenAI Key
+
+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.
+
 ## Examples
 
-### OpenAI.com
+### OpenAI
+
+**Note:** We recommend configuring your OpenAI key using the code editor extension. Follow the [Bring Your Own Key](/docs/navie/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:
 

package/built/docs/navie/how-navie-works.md

@@ -22,6 +22,6 @@ This powerful technique provides the AI with many valuable pieces of information
 
 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. 
 
-<img class="video-screenshot" src="/assets/img/product/navie-architecture.webp"/> 
+![Navie Architecture](/assets/img/product/navie-architecture-slide.svg)
 
 For more details about the privacy and security of your AppMap Data, refer to the [AppMap Security FAQ](https://appmap.io/security)

package/built/docs/navie/index.md

@@ -14,9 +14,7 @@ That means you're not just working with static analysis anymore, and you're not
 
 - [How Navie Works](/docs/navie/how-navie-works)
 - [How to Open Navie](/docs/navie/how-to-open-navie)
-- [Using Navie](/docs/navie/using-navie)
-- [Bring Your Own Key](/docs/navie/bring-your-own-key)
-- [Bring Your Own Model](/docs/navie/bring-your-own-llm)
+- [Bring Your Own LLM Model](/docs/navie/bring-your-own-model)
 
 **Install AppMap for your preferred code editor to get started.**
 

package/built/docs/reference/appmap-java.md

@@ -218,7 +218,7 @@ attribute is ignored.
 The `appmap-java` annotations are provided in the package `com.appland:appmap-annotation`, available on [Maven Central](https://search.maven.org/artifact/com.appland/appmap-annotation). To use them, add that package as a dependency in your build configuration file (`pom.xml`, `build.gradle`).
 
 ### @Labels
-`appmap-java` suports the addition of [code labels](https://appmap.io/docs/appmap-overview.html#features) through the `com.appland.appmap.annotation.Labels` annotation.
+`appmap-java` suports the addition of [code labels](/docs/reference/appmap-java.html#annotations) through the `com.appland.appmap.annotation.Labels` annotation.
 
 #### Usage
 Once the `Labels` annotation is available, you can apply it to methods in your application. For example:

package/built/docs/reference/appmap-python.md

@@ -37,10 +37,15 @@ step: 4
 
 ## About
 
-`appmap` is a Python package for recording [AppMap Diagrams](https://github.com/getappmap/appmap) of your code.
+`appmap` is a Python package for creating [AppMap Diagrams](https://github.com/getappmap/appmap) of
+your code.
 
 {% include docs/what_is_appmap_snippet.md %}
 
+`appmap` works by modifying the way python imports the modules of an application. After a module is
+imported, `appmap` examines it for function definitions. Each function is instrumented, so that when
+it is called, a trace event will be added to the current recording.
+
 ### Supported versions
 
 {% include docs/python_support_matrix.html %}
@@ -48,21 +53,29 @@ step: 4
 Support for new versions is added frequently, please check back regularly for updates.
 
 ## Installation
+`appmap` works best when installed in a virtual environment, usually one associated with a project.
+This helps ensure that the project's code will be instrumented, while reducing the chance of
+interference with other python utilities.
+
+If your project uses `pip` for dependency management, add the `appmap` package to the project's
+requirements file or install it directly. Specifying the `--require-virtualenv` switch ensures that
+it will only be installed in a virtual environment.
 
-If your project uses `pip` for dependency management, add the `appmap` package to the requirements
-file or install it directly with
 ```shell
-pip install appmap
+pip install --require-virtualenv appmap
 ```
 {: .example-code}
 
-For projects that use `poetry` , add the `appmap` package to `pyproject.toml`.
+For projects that use `poetry` , add the `appmap` package to `pyproject.toml`. Note that, by
+default, `poetry` manages dependencies using a virtual environment.
+
 ```
 poetry add --group=dev appmap
 ```
 {: .example-code}
 
-`pipenv` is also supported:
+`pipenv` is also supported. Like `poetry`, `pipenv` installs dependencies in a virtual environment.
+
 ```
 pipenv install --dev appmap
 ```
@@ -72,8 +85,14 @@ pipenv install --dev appmap
 
 ## Configuration
 
-Add your modules as `path` entries in `appmap.yml`, and external packages
-(distributions) as `dist`:
+`appmap` is configured using a YAML file. By default, `appmap` looks in the current working
+directory for a file named `appmap.yml`.
+
+`appmap.yml` contains information used to create AppMap Data files. It allows you to specify the
+application's name, as well as the modules that should be instrumented.
+
+For each module, add the fully-qualified module name as the value of a `path` property. These names
+should be in the format used in an `import` statement:
 
 ```
   name: my_python_app
@@ -92,21 +111,28 @@ Add your modules as `path` entries in `appmap.yml`, and external packages
   #  exclude:
   #  - django.db
 ```
+Notes about this example:
+* The application has two modules that will be recorded: `app.mod1` and
+  `app.mod2`. When the python interpreter imports one of those modules (e.g. by evaluating `import
+  app.mod1`, `from app import mod1`, `from app import *`, etc), `appmap` will instrument the
+  functions in the imported module.
+
+  If the value of a `path` property cannot be parsed as a module name, `appmap` will issue an error
+  and exit.
 
-Note that an `exclude` is resolved relative to the associated path. So, for example, this
-configuration excludes `app.mod2.MyClass`.
+* An `exclude` is resolved relative to the associated path. So, for example, this configuration
+  excludes `app.mod2.MyClass`.
 
-For external [distribution packages](https://packaging.python.org/glossary/#term-Distribution-Package)
-use the `dist` specifier; the names are looked up in the
-[database of installed Python distributions](https://www.python.org/dev/peps/pep-0376/).
-This is generally the same package name as you'd give to `pip install` or put
-in `pyproject.toml`. You can additionally use `path` and `exclude` on `dist`
-entries to limit the capture to specific patterns.
+* An external [distribution
+  package](https://packaging.python.org/glossary/#term-Distribution-Package) can be specified using
+  the `dist` specifier. The names are looked up in the [database of installed Python
+  distributions](https://www.python.org/dev/peps/pep-0376/). This is generally the same package name
+  as you'd give to `pip install` or put in `pyproject.toml`. You can additionally use `path` and
+  `exclude` on `dist` entries to limit the capture to specific patterns.
 
-By default, shallow capture is enabled on `dist` packages, suppressing tracking
-of most internal execution flow. This allows you to capture the interaction without
-getting bogged down with detail. To see these details, set `shallow: false`.
-You can also use `shallow: true` on `path` entries.
+By default, shallow capture is enabled on `dist` packages, suppressing tracking of most internal
+execution flow. This allows you to capture the interaction without getting bogged down with detail.
+To see these details, set `shallow: false`. You can also use `shallow: true` on `path` entries.
 
 ## Enabling and disabling recording