From 62f7ab7a7c42be3ba9f998e12a5a4c5586944828 Mon Sep 17 00:00:00 2001
From: "omkar.ray" <omkar.ray@omkar.ray>
Date: Fri, 5 Jun 2026 12:41:30 +0530
Subject: [PATCH] =?UTF-8?q?docs:=20sharper=20positioning=20=E2=80=94=20exp?=
 =?UTF-8?q?lain=20what=20wiki-trace=20is=20in=2060s?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Two issues with the previous README:

1. "wiki-trace" carries the wrong association. Anyone landing cold
   thinks Wikipedia / knowledge base before they get to LLM tracing.
   The hero badges were strong but the first prose section ("What it
   is") opened with abstract framing.

2. The README had two near-identical sections ("What it is" and "Why
   wiki-trace") making the same point twice. Cut one, sharpened the
   other.

What changed
- Renamed "What it is" to "In one minute" and rewrote it as
  problem -> why existing tools fail -> what we do differently, with
  the one-line patch() example inline so the value is concrete by
  paragraph 4.
- Added a brief "Heads up on the name" callout. Honest about the v0.1
  legacy. Keeps the GitHub URL stable while telling readers the name
  is a codename, not the product.
- Dropped the redundant "Why wiki-trace" bullet list. Same content
  was already covered by the badges + In one minute section.

Net effect: someone landing on the repo cold gets the elevator pitch
in the first 50 lines without having to scroll past badges + ToC +
abstract intro before reaching the value prop.

No code changes. README only.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
---
 README.md | 47 ++++++++++++++++++++++++++---------------------
 1 file changed, 26 insertions(+), 21 deletions(-)

diff --git a/README.md b/README.md
index 14d3d98..ef8b6ae 100644
--- a/README.md
+++ b/README.md
@@ -23,10 +23,28 @@ self-hosted, zero telemetry exfiltration, one line of code.
 
 ---
 
-## What it is
+## In one minute
 
-wiki-trace is the open-source telemetry layer the OpenAI and Anthropic
-SDKs don't ship with. Drop it next to whatever you're already running:
+You're building an LLM app. You ship to production. Now you need to
+know: which prompts are slow, what's it costing, why did that agent
+step fail, who's burning the budget?
+
+The OpenAI and Anthropic SDKs don't ship with telemetry. Tools that
+solve this — Helicone, Phoenix, LangSmith, Weave, Datadog LLM — are
+all SaaS. Your conversations get sent to a third party.
+
+**wiki-trace is the open-source, self-hosted alternative.** Add one
+line of code and every LLM call becomes a traceable event with cost,
+tokens, latency, and replay-ability — running entirely on your
+infrastructure.
+
+```python
+import wikitrace.openai
+wikitrace.openai.patch()        # one line. every request now traced.
+```
+
+That's the whole onboarding. Drop it next to whatever you're already
+running:
 
 - 🐍 **Python SDK** — one-line `patch()` for OpenAI / Anthropic /
   OpenRouter (sync, async, streaming). Decorators for any function.
@@ -47,24 +65,11 @@ SDKs don't ship with. Drop it next to whatever you're already running:
 
 **Open-source. Apache-2.0 / MIT. Your data never leaves your machine.**
 
----
-
-## Why wiki-trace
-
-Building with LLMs is easy. Shipping them is hard. wiki-trace gives
-you the observability layer the OpenAI and Anthropic SDKs don't ship
-with:
-
-- **Logs** — every request, response, model, latency, and token count, captured automatically.
-- **Costs** — built-in price table for 100+ models. See spend by user, session, environment, model.
-- **Sessions** — group multi-step agent runs into one replayable trace. Planner → tool → reflect → answer renders as a tree.
-- **Custom Properties** — tag any request with arbitrary metadata. Slice your dashboard by tenant, feature flag, deploy SHA, anything.
-- **User Metrics** — attribute usage, cost, and latency to end users. Spot the power users and the runaway costs.
-- **Evaluators** — score outputs with built-in judges or your own LLM-as-judge rubrics.
-- **Datasets & Experiments** — version your test sets, run experiments, compare results.
-- **OpenTelemetry export** — pipe everything into Phoenix, Datadog, Honeycomb, Grafana, or any OTLP collector.
-
-Open-source. Self-hosted. Your data never leaves your infrastructure.
+> **Heads up on the name.** "wiki-trace" is a legacy from v0.1, when
+> this project was a wiki/knowledge curation tool. It's now a
+> general-purpose LLM observability platform. The name is sticking
+> for now to preserve the GitHub URL and momentum — think of it as a
+> codename. The product is the tracer.
 
 ---