-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.
+
TLDRGraph π
-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.
+
+ Turn a codebase into source-backed feature workflows.
+ Explore what the software does, follow every decision, and open the code that proves it.
+
-## Install
+
+
+
+
+
+
+
+---
+
+## β¨ 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.
+
+
+
+
+
+## π 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/.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/
+β βββ .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).
diff --git a/assets/workflow_explorer_catalog.png b/assets/workflow_explorer_catalog.png
new file mode 100644
index 0000000..aced93f
Binary files /dev/null and b/assets/workflow_explorer_catalog.png differ
diff --git a/tldrgraph/visualizer/assets/tldrgraph_logo.svg b/tldrgraph/visualizer/assets/tldrgraph_logo.svg
new file mode 100644
index 0000000..c8eb142
--- /dev/null
+++ b/tldrgraph/visualizer/assets/tldrgraph_logo.svg
@@ -0,0 +1,141 @@
+
+
+ 
+ 
+ 
+
+