docs: refresh README branding

README.md

@@ -1,54 +1,96 @@
-# TLDRGraph
+<p align="center">
+  <img src="assets/tldrgraph_logo.svg" alt="TLDRGraph logo" width="380" />
+</p>
 
-TLDRGraph turns a repository into a source-backed feature catalog and interactive
-Workflow Explorer. Your coding agent reads the repository, identifies meaningful
-product and technical capabilities, and records every displayed step with file,
-symbol, and line-range evidence.
+<h1 align="center">TLDRGraph 🌐</h1>
 
-TLDRGraph does not run an AI process itself and does not infer workflows from a
-static graph. It coordinates direct catalog and workflow artifacts with the
-coding agent that already has your repository open.
+<p align="center">
+  <strong>Turn a codebase into source-backed feature workflows.</strong><br>
+  <em>Explore what the software does, follow every decision, and open the code that proves it.</em>
+</p>
 
-## Install
+<p align="center">
+  <a href="https://pypi.org/project/tldrgraph/"><img src="https://img.shields.io/pypi/v/tldrgraph.svg?logo=pypi&logoColor=white" alt="PyPI"></a>
+  <a href="https://pypi.org/project/tldrgraph/"><img src="https://img.shields.io/pypi/pyversions/tldrgraph.svg?logo=python&logoColor=white" alt="Python versions"></a>
+  <a href="https://vikrantd.github.io/TLDRGraph/"><img src="https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg?logo=materialformkdocs&logoColor=white" alt="Documentation"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="MIT License"></a>
+</p>
+
+---
+
+## ✨ See the workflow, then see the proof
+
+TLDRGraph turns a repository into a catalog of meaningful product and technical
+capabilities. For each feature, your coding agent records an evidence-backed
+workflow: every displayed step cites the exact file, symbol, and line range that
+supports it.
+
+It does not invent an architecture from a static graph or run an AI process by
+itself. Instead, it gives the coding agent already working in your repository a
+small, verifiable artifact format to complete.
+
+## 🗺️ Workflow Explorer
+
+Browse the capability catalog, select a workflow, and inspect the source
+evidence behind each part of the flow. The standalone explorer supports:
+
+- Product and technical capability areas, with generated, partial, and pending states.
+- Vertical workflow diagrams with process steps, decision diamonds, labeled branches, and reconvergence.
+- Panning, zooming, and an optional horizontal layout.
+- A detail panel for each workflow element and live cited-source viewing with `tldrgraph ui --serve`.
+- A stale-catalog warning when the repository no longer matches the catalog's source hash.
+
+<p align="center">
+  <img src="assets/workflow_explorer_catalog.png" alt="Workflow Explorer showing a selected source-backed capability flow" width="100%" />
+</p>
+
+## 🚀 Quickstart
+
+### 1. Install
 
 ```bash
 pip install tldrgraph
 ```
 
-## Generate a catalog
+### 2. Generate a source-backed catalog
 
-Run this inside a supported coding-agent session:
+Run TLDRGraph inside a supported coding-agent session:
 
 ```bash
 tldrgraph init
 ```
 
-When `init` reports `needs_feature_workflows`, it includes the current source
-hash. The active agent identifies feature outcomes and immediately writes the v4
-`.tldrgraph/features.yaml` index. It delegates one indexed feature to each
-source-reading subagent; each worker writes only its own v4 workflow file. Run
-`tldrgraph init` again to validate the artifacts and generate the explorer.
+If the command reports `needs_feature_workflows`, it prints the current source
+hash. The active agent then reads the repository, identifies feature outcomes,
+and writes the catalog index. A source-reading worker produces each feature's
+workflow with evidence. Run `tldrgraph init` again to validate those artifacts
+and generate the explorer.
 
-When repository source changes after a catalog exists, run `tldrgraph refresh`
-instead. It performs the same validation and generation flow while making the
-update intent explicit.
+### 3. Explore the result
 
-The final artifacts are:
+```bash
+tldrgraph ui --serve
+```
 
-- `.tldrgraph/features.yaml`
-- `.tldrgraph/workflows/<feature_id>.yaml`
-- `.tldrgraph/TLDRGRAPH_VISUALIZER.html`
+The generated browser application lets you navigate workflows and open their
+cited source ranges. After the repository changes, use `tldrgraph refresh` to
+validate an updated catalog against the new source hash.
 
-## Explore
+## 📦 What TLDRGraph creates
 
-```bash
-tldrgraph ui --serve
+```text
+.tldrgraph/
+├── features.yaml                 # Feature index authored by the active agent
+├── workflows/
+│   └── <feature_id>.yaml         # Evidence-backed workflow per feature
+└── TLDRGRAPH_VISUALIZER.html     # Standalone Workflow Explorer
 ```
 
-The standalone browser application groups product and technical capabilities,
-draws each proven workflow, and opens cited source ranges from the repository.
+The v4 catalog validates every referenced evidence file, symbol, and line
+range against the repository inventory. Catalog and workflow source hashes must
+match the current source before they are accepted as current.
 
-## CLI
+## 🧰 CLI
 
 ```text
 tldrgraph init [PATH] [--json]
@@ -57,6 +99,25 @@ tldrgraph ui [--path PATH] [--serve] [--port PORT] [--open|--no-open]
 tldrgraph install [--path PATH] [--all-agents]
 ```
 
-Version 0.3 is a breaking, workflow-only release. Earlier graph-based commands
-and v1/v2 generated artifacts are not supported; run `tldrgraph init` to create
-the current catalog, then `tldrgraph refresh` after later source changes.
+`init` starts catalog generation, `refresh` makes a later source update
+explicit, and `ui` creates the standalone explorer. `install` writes the
+workflow instructions for supported coding-agent environments.
+
+## 🤖 Built for coding-agent collaboration
+
+TLDRGraph's role is coordination and validation: your active coding agent
+reads the source and authors the catalog artifacts, while independent
+source-reading workers provide feature workflows. This keeps the explorer
+traceable to repository evidence instead of inferred from naming conventions or
+an opaque background analysis process.
+
+For the complete workflow and artifact contract, see the [documentation](https://vikrantd.github.io/TLDRGraph/).
+
+## 🙏 Credits
+
+TLDRGraph builds on the workflow knowledge captured by the coding agent working
+with your repository.
+
+## 📄 License
+
+Distributed under the [MIT License](LICENSE).