From 00740f88e1f02391b0b13d2fe7e0c9992f4676b4 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Mar 2026 10:23:12 +0000 Subject: [PATCH 1/4] Add chat feature and Slack integration documentation New pages: - docs/chat.md: Guide for the built-in AI chat (conversations, artifacts, tool calls) - docs/integrations/slack.md: Slack integration for thread-based architecture Q&A Updated pages: - index.md: Add Chat to homepage grid and quick start - getting-started.md: Add built-in chat as primary onboarding path - capabilities.md: Reference chat alongside MCP integrations - workflows.md: Add chat-based Q&A workflow example - integrations/index.md: Add Slack to integrations table - mkdocs.yml: Add Chat and Slack nav entries https://claude.ai/code/session_01ULWBJae5RGzUWdccr3CWA9 --- docs/capabilities.md | 2 +- docs/chat.md | 93 ++++++++++++++++++++++++++++++++++++++ docs/getting-started.md | 13 +++++- docs/index.md | 8 +++- docs/integrations/index.md | 6 +++ docs/integrations/slack.md | 40 ++++++++++++++++ docs/workflows.md | 24 ++++++++++ mkdocs.yml | 2 + 8 files changed, 183 insertions(+), 5 deletions(-) create mode 100644 docs/chat.md create mode 100644 docs/integrations/slack.md diff --git a/docs/capabilities.md b/docs/capabilities.md index 428e7d1..4ab6147 100644 --- a/docs/capabilities.md +++ b/docs/capabilities.md @@ -1,6 +1,6 @@ # What You Can Do -OpenTrace enables your AI assistant to answer questions about your system architecture. Here's what you can ask. +OpenTrace answers questions about your system architecture — either through the built-in [Chat](chat.md) or via [MCP integrations](integrations/index.md) with your existing AI tools. Here's what you can ask. ## Discover Your System diff --git a/docs/chat.md b/docs/chat.md new file mode 100644 index 0000000..e1ff384 --- /dev/null +++ b/docs/chat.md @@ -0,0 +1,93 @@ +# Chat + +OpenTrace Chat is a built-in AI assistant that answers questions about your system architecture directly in the OpenTrace dashboard. No external tools or MCP configuration needed — just open a conversation and ask. + +## Getting Started + +1. Log in to your OpenTrace dashboard +2. Click **Chat** in the sidebar navigation +3. Start a new conversation and ask a question about your system + +!!! tip + If you don't see Chat in the sidebar, the feature may not yet be enabled for your organization. Contact your admin or reach out to support. + +## Conversations + +Chat organizes your interactions into **conversations**. Each conversation maintains its own context, so you can have separate threads for different topics. + +### Creating a Conversation + +Click the **New Chat** button in the chat sidebar to start a fresh conversation. Your conversation will be automatically titled based on your first message. + +### Switching Between Conversations + +The chat sidebar shows all your conversations. Click any conversation to switch to it. Your message history and context are preserved. + +### Archiving Conversations + +To keep your conversation list manageable, you can archive conversations you no longer need. Archived conversations can be restored later. + +## Asking Questions + +Chat has access to your full OpenTrace knowledge graph. You can ask the same types of questions you'd ask through any MCP-connected AI assistant: + +| Category | Example | +|----------|---------| +| **Discovery** | "What services exist in my system?" | +| **Dependencies** | "What does the checkout service depend on?" | +| **Impact Analysis** | "What breaks if the database goes down?" | +| **Connections** | "How does the frontend connect to payments?" | +| **Investigations** | "Help me debug why orders are slow" | + +### Asking About Specific Nodes + +You can start a chat with context already attached. From any node or investigation in OpenTrace, click **Ask about this** to open a new chat pre-loaded with that context. This is useful when you're exploring the graph and want to dive deeper into a specific component. + +## Understanding Responses + +Chat responses include several elements beyond plain text. + +### Tool Calls + +When the AI queries your knowledge graph, you'll see **tool call indicators** showing which tools were used and what data was retrieved. Click on a tool call to expand its details and see the raw results. + +### Artifacts + +Responses may include **artifact chips** — clickable references to nodes in your knowledge graph. These appear as inline links within the response text. + +Clicking an artifact chip opens the **Artifact Panel**, which displays a subgraph visualization centered on that node. This lets you visually explore the component and its immediate connections without leaving the chat. + +### Markdown Formatting + +Responses are rendered with full markdown support including code blocks, tables, and lists. + +## Tips for Effective Questions + +**Be specific about services and components:** + +> "What does order-service depend on?" works better than "Tell me about dependencies" + +**Use the actual names from your system:** + +> Use "user-auth-service" if that's the name in your graph, not just "auth" + +**Ask follow-up questions to drill deeper:** + +> Start with "What services are involved in checkout?" then follow up with "How does checkout-api connect to the database?" + +**Use "Ask about this" for contextual questions:** + +> When viewing a node in the graph, click "Ask about this" to get answers grounded in that specific component. + +## Chat vs. MCP Integrations + +OpenTrace offers two ways to interact with your architecture knowledge: + +| | Chat | MCP Integrations | +|---|------|-----------------| +| **Where** | OpenTrace dashboard | Your existing AI tools (Claude, Copilot, etc.) | +| **Setup** | None — built in | Requires MCP configuration and API token | +| **Best for** | Quick exploration, visual graph browsing | Deep coding sessions, IDE workflows | +| **Graph visualization** | Inline artifact panel | Depends on the AI tool | + +Both approaches query the same knowledge graph and support the same types of questions. Choose whichever fits your workflow. diff --git a/docs/getting-started.md b/docs/getting-started.md index 4216316..81bba7e 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -4,9 +4,17 @@ OpenTrace gives your AI assistant deep knowledge about your system architecture. It understands your services, how they connect, and how they depend on each other. This means you can ask questions about your system and get accurate, contextual answers. -## Setup +## Try the Built-in Chat -To connect OpenTrace to your AI assistant, add the following to your MCP configuration: +The fastest way to get started is the built-in [Chat](chat.md). Log in to your OpenTrace dashboard, open Chat from the sidebar, and start asking questions — no configuration needed. + +> "What services are in my system?" + +> "What does the payment service depend on?" + +## Connect Your AI Assistant + +To use OpenTrace with an external AI assistant (Claude, GitHub Copilot, etc.), add the following to your MCP configuration: ```json { @@ -50,5 +58,6 @@ Your AI assistant now has the context it needs to give you meaningful answers ab ## Next Steps +- [Chat](chat.md) - Use the built-in chat to explore your architecture - [What You Can Do](capabilities.md) - Full list of questions you can ask - [Example Workflows](workflows.md) - Common scenarios and how to approach them diff --git a/docs/index.md b/docs/index.md index be4f0b9..b1a0d6b 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ OpenTrace gives your AI assistant deep understanding of your system architecture ## Quick Start -Connect OpenTrace to your AI assistant and start asking questions: +Ask questions about your architecture using the built-in [Chat](chat.md) or connect OpenTrace to your AI assistant: > "What services are in my system?" @@ -22,9 +22,13 @@ Connect OpenTrace to your AI assistant and start asking questions: Setup OpenTrace and run your first queries +- **[Chat](chat.md)** + + Ask questions about your architecture directly in OpenTrace + - **[Integrations](integrations/index.md)** - Connect GitHub, GitLab, and AWS EKS + Connect GitHub, GitLab, AWS EKS, and Slack - **[What You Can Do](capabilities.md)** diff --git a/docs/integrations/index.md b/docs/integrations/index.md index 6874685..7f165cb 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -10,6 +10,12 @@ OpenTrace connects to your existing tools and infrastructure to build a complete | [Claude Code](claude-code.md) | OAuth / API Token | Architecture knowledge for Claude Code CLI | | [GitHub Copilot](github-copilot.md) | OAuth / API Token | Architecture knowledge for VS Code Copilot | +## Messaging + +| Integration | Authentication | What It Provides | +|-------------|----------------|------------------| +| [Slack](slack.md) | OAuth | Chat with OpenTrace from Slack threads | + ## Data Sources | Integration | Type | What It Provides | Status | diff --git a/docs/integrations/slack.md b/docs/integrations/slack.md new file mode 100644 index 0000000..4282799 --- /dev/null +++ b/docs/integrations/slack.md @@ -0,0 +1,40 @@ +# Slack + +Connect OpenTrace to Slack to ask questions about your system architecture directly from your workspace. + +## Overview + +The Slack integration lets you start OpenTrace Chat conversations from Slack threads. Ask a question in Slack, and the AI responds with answers grounded in your knowledge graph — without leaving your messaging workflow. + +## How It Works + +1. Start or mention OpenTrace in a Slack thread +2. The AI reads the thread context to understand your question +3. OpenTrace queries your knowledge graph and responds in the thread +4. The conversation is also visible in OpenTrace Chat for further exploration + +## Starting a Chat from Slack + +Mention OpenTrace in any channel or thread where the integration is installed. Your message and the surrounding thread context are used to inform the response. + +> @OpenTrace what services depend on the payment API? + +The AI will reply in the same thread with an answer based on your architecture graph. + +## Continuing Conversations + +Each Slack thread maps to an OpenTrace conversation. Follow-up messages in the same thread maintain context, so you can ask progressively deeper questions: + +> @OpenTrace what does checkout-api depend on? + +> @OpenTrace which of those are databases? + +> @OpenTrace what else connects to postgres-main? + +## Viewing in OpenTrace + +Conversations started from Slack also appear in the OpenTrace Chat sidebar. You can continue them in the dashboard if you want access to features like the artifact panel and graph visualization. + +## Setup + +To enable the Slack integration for your organization, contact your OpenTrace admin or visit the integrations page in the dashboard. diff --git a/docs/workflows.md b/docs/workflows.md index b9c3ffc..ba105e0 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -112,6 +112,30 @@ The AI traces deeper connections you might have missed. --- +## Quick Architecture Q&A with Chat + +You need a fast answer about your system without switching tools. Use the built-in [Chat](chat.md): + +**1. Open Chat and ask your question** + +> "What services handle payments in our system?" + +The AI queries your knowledge graph and lists all payment-related services with their dependencies. + +**2. Click on an artifact to visualize** + +When the response mentions a service, click the artifact chip to open the graph visualization panel and see its connections. + +**3. Ask follow-up questions in the same conversation** + +> "Which of those services connect to external payment providers?" + +> "What would break if stripe-gateway goes down?" + +Chat maintains context across the conversation, so each follow-up builds on the previous answers. + +--- + ## Debugging Performance Issues The API is slow. Figure out why: diff --git a/mkdocs.yml b/mkdocs.yml index 6ef2030..562c507 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,6 +69,7 @@ extra: nav: - Home: index.md - Getting Started: getting-started.md + - Chat: chat.md - Integrations: - Overview: integrations/index.md - AI Assistants: @@ -80,6 +81,7 @@ nav: - GitLab: integrations/gitlab.md - Excluding Files from Data Sources: otignore.md - AWS EKS (Early Access): integrations/aws-eks.md + - Slack: integrations/slack.md - What You Can Do: capabilities.md - Example Workflows: workflows.md - Privacy Policy: privacy-policy.md From 7c698ea7bd37fdd48804621043d8c54c72fa44b3 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Mar 2026 11:01:27 +0000 Subject: [PATCH 2/4] Fix chat docs: replace archive with delete to match implementation The actual implementation uses permanent deletion (DeleteConversation), not archiving. There is no archive state or restore capability. https://claude.ai/code/session_01ULWBJae5RGzUWdccr3CWA9 --- docs/chat.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/chat.md b/docs/chat.md index e1ff384..82abd62 100644 --- a/docs/chat.md +++ b/docs/chat.md @@ -23,9 +23,9 @@ Click the **New Chat** button in the chat sidebar to start a fresh conversation. The chat sidebar shows all your conversations. Click any conversation to switch to it. Your message history and context are preserved. -### Archiving Conversations +### Deleting Conversations -To keep your conversation list manageable, you can archive conversations you no longer need. Archived conversations can be restored later. +To keep your conversation list manageable, you can delete conversations you no longer need. Note that deleting a conversation permanently removes it along with all its messages. ## Asking Questions From e97be8fdc5c404737010ed1f12a8b4949ce0e61a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Mar 2026 11:02:41 +0000 Subject: [PATCH 3/4] =?UTF-8?q?Remove=20"Ask=20about=20this"=20references?= =?UTF-8?q?=20=E2=80=94=20feature=20was=20never=20built?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit OT-1064 (linking investigations/nodes to chat) was canceled and OT-1014 (chat in node context) is still in backlog. Removed the section and tip that documented this unimplemented feature. https://claude.ai/code/session_01ULWBJae5RGzUWdccr3CWA9 --- docs/chat.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/docs/chat.md b/docs/chat.md index 82abd62..f2441ae 100644 --- a/docs/chat.md +++ b/docs/chat.md @@ -39,10 +39,6 @@ Chat has access to your full OpenTrace knowledge graph. You can ask the same typ | **Connections** | "How does the frontend connect to payments?" | | **Investigations** | "Help me debug why orders are slow" | -### Asking About Specific Nodes - -You can start a chat with context already attached. From any node or investigation in OpenTrace, click **Ask about this** to open a new chat pre-loaded with that context. This is useful when you're exploring the graph and want to dive deeper into a specific component. - ## Understanding Responses Chat responses include several elements beyond plain text. @@ -75,10 +71,6 @@ Responses are rendered with full markdown support including code blocks, tables, > Start with "What services are involved in checkout?" then follow up with "How does checkout-api connect to the database?" -**Use "Ask about this" for contextual questions:** - -> When viewing a node in the graph, click "Ask about this" to get answers grounded in that specific component. - ## Chat vs. MCP Integrations OpenTrace offers two ways to interact with your architecture knowledge: From d3dfa42605b05930413662e3e12ed789dd97b377 Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 5 Mar 2026 11:05:03 +0000 Subject: [PATCH 4/4] Move Slack docs under Chat section as a sub-page Slack is a way to start chat conversations, not a standalone integration. Restructured to docs/chat/index.md + docs/chat/slack.md and updated all cross-references accordingly. Removed Slack from integrations index. https://claude.ai/code/session_01ULWBJae5RGzUWdccr3CWA9 --- docs/capabilities.md | 2 +- docs/{chat.md => chat/index.md} | 4 ++++ docs/{integrations => chat}/slack.md | 0 docs/getting-started.md | 4 ++-- docs/index.md | 6 +++--- docs/integrations/index.md | 6 ------ docs/workflows.md | 2 +- mkdocs.yml | 5 +++-- 8 files changed, 14 insertions(+), 15 deletions(-) rename docs/{chat.md => chat/index.md} (96%) rename docs/{integrations => chat}/slack.md (100%) diff --git a/docs/capabilities.md b/docs/capabilities.md index 4ab6147..fabc437 100644 --- a/docs/capabilities.md +++ b/docs/capabilities.md @@ -1,6 +1,6 @@ # What You Can Do -OpenTrace answers questions about your system architecture — either through the built-in [Chat](chat.md) or via [MCP integrations](integrations/index.md) with your existing AI tools. Here's what you can ask. +OpenTrace answers questions about your system architecture — either through the built-in [Chat](chat/index.md) or via [MCP integrations](integrations/index.md) with your existing AI tools. Here's what you can ask. ## Discover Your System diff --git a/docs/chat.md b/docs/chat/index.md similarity index 96% rename from docs/chat.md rename to docs/chat/index.md index f2441ae..5d9b7b9 100644 --- a/docs/chat.md +++ b/docs/chat/index.md @@ -83,3 +83,7 @@ OpenTrace offers two ways to interact with your architecture knowledge: | **Graph visualization** | Inline artifact panel | Depends on the AI tool | Both approaches query the same knowledge graph and support the same types of questions. Choose whichever fits your workflow. + +## Chat from Slack + +You can also start OpenTrace Chat conversations directly from Slack. See the [Slack integration](slack.md) page for details. diff --git a/docs/integrations/slack.md b/docs/chat/slack.md similarity index 100% rename from docs/integrations/slack.md rename to docs/chat/slack.md diff --git a/docs/getting-started.md b/docs/getting-started.md index 81bba7e..e752cd4 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -6,7 +6,7 @@ OpenTrace gives your AI assistant deep knowledge about your system architecture. ## Try the Built-in Chat -The fastest way to get started is the built-in [Chat](chat.md). Log in to your OpenTrace dashboard, open Chat from the sidebar, and start asking questions — no configuration needed. +The fastest way to get started is the built-in [Chat](chat/index.md). Log in to your OpenTrace dashboard, open Chat from the sidebar, and start asking questions — no configuration needed. > "What services are in my system?" @@ -58,6 +58,6 @@ Your AI assistant now has the context it needs to give you meaningful answers ab ## Next Steps -- [Chat](chat.md) - Use the built-in chat to explore your architecture +- [Chat](chat/index.md) - Use the built-in chat to explore your architecture - [What You Can Do](capabilities.md) - Full list of questions you can ask - [Example Workflows](workflows.md) - Common scenarios and how to approach them diff --git a/docs/index.md b/docs/index.md index b1a0d6b..6bf89e8 100644 --- a/docs/index.md +++ b/docs/index.md @@ -4,7 +4,7 @@ OpenTrace gives your AI assistant deep understanding of your system architecture ## Quick Start -Ask questions about your architecture using the built-in [Chat](chat.md) or connect OpenTrace to your AI assistant: +Ask questions about your architecture using the built-in [Chat](chat/index.md) or connect OpenTrace to your AI assistant: > "What services are in my system?" @@ -22,13 +22,13 @@ Ask questions about your architecture using the built-in [Chat](chat.md) or conn Setup OpenTrace and run your first queries -- **[Chat](chat.md)** +- **[Chat](chat/index.md)** Ask questions about your architecture directly in OpenTrace - **[Integrations](integrations/index.md)** - Connect GitHub, GitLab, AWS EKS, and Slack + Connect GitHub, GitLab, and AWS EKS - **[What You Can Do](capabilities.md)** diff --git a/docs/integrations/index.md b/docs/integrations/index.md index 7f165cb..6874685 100644 --- a/docs/integrations/index.md +++ b/docs/integrations/index.md @@ -10,12 +10,6 @@ OpenTrace connects to your existing tools and infrastructure to build a complete | [Claude Code](claude-code.md) | OAuth / API Token | Architecture knowledge for Claude Code CLI | | [GitHub Copilot](github-copilot.md) | OAuth / API Token | Architecture knowledge for VS Code Copilot | -## Messaging - -| Integration | Authentication | What It Provides | -|-------------|----------------|------------------| -| [Slack](slack.md) | OAuth | Chat with OpenTrace from Slack threads | - ## Data Sources | Integration | Type | What It Provides | Status | diff --git a/docs/workflows.md b/docs/workflows.md index ba105e0..9d4ee2d 100644 --- a/docs/workflows.md +++ b/docs/workflows.md @@ -114,7 +114,7 @@ The AI traces deeper connections you might have missed. ## Quick Architecture Q&A with Chat -You need a fast answer about your system without switching tools. Use the built-in [Chat](chat.md): +You need a fast answer about your system without switching tools. Use the built-in [Chat](chat/index.md): **1. Open Chat and ask your question** diff --git a/mkdocs.yml b/mkdocs.yml index 562c507..5f33e96 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -69,7 +69,9 @@ extra: nav: - Home: index.md - Getting Started: getting-started.md - - Chat: chat.md + - Chat: + - Overview: chat/index.md + - Slack: chat/slack.md - Integrations: - Overview: integrations/index.md - AI Assistants: @@ -81,7 +83,6 @@ nav: - GitLab: integrations/gitlab.md - Excluding Files from Data Sources: otignore.md - AWS EKS (Early Access): integrations/aws-eks.md - - Slack: integrations/slack.md - What You Can Do: capabilities.md - Example Workflows: workflows.md - Privacy Policy: privacy-policy.md