docs: sharpen messaging and feature descriptions

Rewrite README and docs introduction to lead with the value proposition,
reorder features to highlight AI-native capabilities first, and tighten
descriptions across guides for clarity and consistency.

Author: ravisuhag

README.md

@@ -6,17 +6,17 @@
 [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg?logo=apache)](LICENSE)
 [![Version](https://img.shields.io/github/v/release/raystack/compass?logo=semantic-release)](Version)
 
-Compass is a context engine that builds a knowledge graph of your organization's metadata, capturing entities, relationships, and lineage across systems and time, making it discoverable and queryable for both humans and AI agents.
+Compass is a context engine that builds a temporal knowledge graph of your organization — entities, relationships, and documents across every system — queryable by humans and AI agents alike. Search it. Traverse it. Reason over it.
 
 ## Key Features
 
+- **AI-Native** -- Composable MCP tools let AI agents search, traverse, assess impact, and read documents over your organizational graph.
 - **Knowledge Graph** -- Typed, directed, temporal relationships between entities including lineage, ownership, and custom edge types.
+- **Context Assembly** -- Multi-hop bidirectional traversal builds a subgraph around any entity — the full picture in one call.
+- **Impact Analysis** -- Blast radius analysis traces what depends on what and what breaks when something changes.
 - **Hybrid Search** -- Keyword precision with semantic similarity using Postgres-native full-text search and pgvector embeddings.
-- **Context Assembly** -- Multi-hop bidirectional traversal builds a subgraph around any entity.
-- **Impact Analysis** -- Downstream blast radius analysis traces what breaks when something changes.
-- **Documents** -- Attach runbooks, decisions, and annotations to entities, indexed for semantic search.
-- **MCP Server** -- AI agents query the graph via Model Context Protocol.
-- **Open Type System** -- Any entity type, any edge type, any properties.
+- **Documents** -- Attach any document to entities — runbooks, decisions, postmortems, design docs — all indexed for semantic search.
+- **Open Type System** -- Any entity type, any edge type, any properties. Hardware, software, operations, people — anything fits.
 
 ## Documentation
 

docs/docs/guides/context.mdx

@@ -64,4 +64,4 @@ With depth 2, it would also include any entities connected to the Kafka Topic an
 
 ## Impact Analysis
 
-`impact` is the downstream-only counterpart to `get_context` — it answers "if I change this, what breaks?" by tracing edges in one direction. Same depth mechanics, same cycle detection, but only follows downstream relationships. Available as `entity impact` in the CLI, `GetEntityImpact` in the API, and `impact` in MCP.
+`impact` answers "if I change this, what breaks?" by tracing edges downstream from a root entity. Same depth mechanics and cycle detection as `get_context`, but follows relationships in one direction to map the blast radius. Available as `entity impact` in the CLI, `GetEntityImpact` in the API, and `impact` in MCP.

docs/docs/guides/documents.mdx

@@ -1,12 +1,12 @@
 ---
 title: Documents
-description: Attach runbooks, decisions, and annotations to entities.
+description: Attach any document to entities, indexed for semantic search.
 order: 6
 ---
 
 # Documents
 
-Documents are knowledge objects — runbooks, ADRs, annotations, decisions — linked to entities. They are stored as first-class objects, indexed for semantic search, and served through the MCP `get_documents` tool.
+Documents are knowledge objects linked to entities — runbooks, ADRs, postmortems, design docs, or any other document type. They are stored as first-class objects, indexed for semantic search, and served through the MCP `get_documents` tool.
 
 ## Document Model
 

docs/docs/index.mdx

@@ -1,28 +1,30 @@
 ---
 title: Introduction
-description: Compass is a context engine that builds a knowledge graph of your organization's metadata for humans and AI agents.
+description: Compass is a context engine — a temporal knowledge graph queryable by engineers and AI agents.
 order: 1
 ---
 
 # Introduction
 
-Compass is a context engine that builds a knowledge graph of your organization's metadata, capturing entities, relationships, and lineage across systems and time, making it discoverable and queryable for both humans and AI agents.
+Compass is a context engine that builds a temporal knowledge graph of your organization — entities, relationships, and documents across every system — queryable by humans and AI agents alike. Search it. Traverse it. Reason over it.
 
 ## The Problem
 
-Organizational knowledge is fragmented. The same logical entity appears across multiple systems with different names, schemas, and levels of detail. Relationships live in people's heads, scattered across wikis, chat threads, and tribal knowledge. When someone needs context, they spend hours stitching it together. When AI agents need context, they have nowhere to look.
+Organizations build complex systems — hundreds of services, pipelines, models, devices, and operations — all deeply interdependent. The knowledge about how these things connect, why they exist, and what depends on what lives in people's heads, scattered docs, and tribal memory.
 
-Compass solves this by acting as the resolution and serving layer for organizational metadata. It takes raw observations from collection systems like [Meteor](https://github.com/raystack/meteor), resolves them into unified entities, builds a graph of their relationships, and makes everything searchable and traversable.
+Every day, engineers waste hours assembling context manually. AI agents hallucinate because they have no grounded knowledge to reason over. Changes break things nobody predicted. The missing layer is context.
+
+Compass is that layer. It takes raw observations from collection systems like [Meteor](https://github.com/raystack/meteor), resolves them into unified entities, builds a temporal graph of their relationships, and makes everything searchable and traversable — by humans and agents.
 
 ## Key Features
 
+- **AI-Native** -- Composable MCP tools let AI agents search, traverse, assess impact, and read documents. Works with any MCP-compatible client.
 - **Knowledge Graph** -- Typed, directed, temporal relationships between entities including lineage, ownership, documentation, and custom edge types.
+- **Context Assembly** -- Multi-hop bidirectional traversal builds a subgraph around any entity — the full picture in one call.
+- **Impact Analysis** -- Blast radius analysis traces what depends on what and what breaks when something changes.
 - **Hybrid Search** -- Keyword precision combined with semantic similarity using Postgres-native full-text search and pgvector embeddings.
-- **Context Assembly** -- Multi-hop bidirectional traversal builds a subgraph around any entity, assembling the full picture.
-- **Impact Analysis** -- Downstream blast radius analysis traces what breaks when something changes.
-- **Documents** -- Attach runbooks, decisions, and annotations to entities, indexed for semantic search.
-- **MCP Server** -- AI agents query the graph via Model Context Protocol. Works with Claude Code, Cursor, and Windsurf.
-- **Open Type System** -- Any entity type, any edge type, any properties. Compass doesn't prescribe your domain model.
+- **Documents** -- Attach any document to entities — runbooks, decisions, postmortems, design docs — all indexed for semantic search.
+- **Open Type System** -- Any entity type, any edge type, any properties. Hardware, software, operations, people — anything fits.
 
 ## Interfaces
 

docs/docs/internals/architecture.mdx

@@ -43,7 +43,7 @@ Orchestrates graph traversal, hybrid search, and context composition:
 ### Serving Layer
 
 - **Connect RPC** — HTTP and gRPC via a single service definition. API definitions in [raystack/proton](https://github.com/raystack/proton).
-- **MCP Server** — Model Context Protocol at `/mcp` for AI agents. Four composable tools: `search_entities`, `get_context`, `impact`, `get_documents`.
+- **MCP Server** — Model Context Protocol at `/mcp` for AI agents. Composable tools for searching, understanding context, analyzing impact, and retrieving documents.
 
 ## Multi-Tenancy