fix README.md

Author: matt-beanland

README.md

@@ -13,57 +13,68 @@ SPDX-License-Identifier: MIT
 
 [Diffo](https://github.com/diffo-dev/diffo) is a Telecommunications Management Forum (TMF) Service and Resource Manager, built for autonomous networks.
 
-This repo contains two independent example domains, each modelling a different slice of a telco network.
+This repo contains two independent example domains, plus an orientation to the underlying Diffo Provider primitives. Read in this order:
 
-## NBN Domain
+1. **[The Access Domain](documentation/domains/access.md)** — the warm-up. A single fictional telco delivering DSL service over copper to its own customers. Five resources, one service, a small state machine. Walks the pattern end-to-end.
+2. **[The Provider Domain](documentation/domains/provider.md)** — lifts the lid on the primitives Access has been using the whole time (Specification, Instance, typed Characteristics, Pools, Assignments, Relationships, Place, Party, state machine, the TMF JSON encoder).
+3. **[The NBN Domain](documentation/domains/nbn.md)** — the deeper case. A fictional wholesale broadband network shared by many Retail Service Providers. Adds multi-tenancy via Ash Policy, a longer delivery chain, and the named-vs-metrics characteristic pattern with cross-resource inheritance.
 
-A declarative model of a fictional NBN Ethernet access hierarchy — NbnEthernet, UNI, AVC, NTD, CVC, NNI Group, and NNI — built entirely with the Diffo Provider Instance DSL. Includes multi-tenancy via Ash Policy: each RSP can only see and manage the resources they own.
+Each domain ships with a runnable livebook.
 
-[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fdev%2Fdocumentation%2Fdomains%2Fdiffo_example_nbn.livemd)
+## Access Livebook
 
-The livebook walks through provisioning a complete NBN Ethernet access circuit, selecting an RSP to operate as, and demonstrating how the `mine` actions propagate technology, speeds, CVLAN, and port assignments up the resource hierarchy.
+[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fmain%2Fdocumentation%2Fdomains%2Fdiffo_example_access.livemd)
 
-## Access Domain
+End-to-end scenario through the code-interface — exchange shelf with line cards, a customer access path through copper, qualify and design a DSL service for the subscriber, then read the inheritance chain.
 
-A copper-network equivalent covering DSL access services — Cable, Card, Path, and Shelf. Explore `lib/access/` for the domain model.
+## NBN Livebook
+
+[![Run in Livebook](https://livebook.dev/badge/v1/blue.svg)](https://livebook.dev/run?url=https%3A%2F%2Fgithub.com%2Fdiffo-dev%2Fdiffo_example%2Fblob%2Fmain%2Fdocumentation%2Fdomains%2Fdiffo_example_nbn.livemd)
+
+The wholesale story — pick an RSP, build the shareable NNI Group / CVC, provision a subscriber's NBN Ethernet access end-to-end, then read the full delivery chain through inheritance and the live metrics on each resource.
+
+## API reference (auto-generated)
+
+- [Access Domain API](documentation/domains/_access_api.md) — every code-interface function on `DiffoExample.Access`.
+- [NBN Domain API](documentation/domains/_nbn_api.md) — every code-interface function on `DiffoExample.Nbn`.
+
+Both are regenerated from the domain DSL with `mix gen.api_docs`.
 
 ## Installation
 
-If [available in Hex](https://hex.pm/docs/publish), the package can be installed
-by adding `diffo_example` to your list of dependencies in `mix.exs`:
+The package can be installed by adding `diffo_example` to your list of dependencies in `mix.exs`:
 
 ```elixir
 def deps do
   [
-    {:diffo_example, "~> 0.0.2"}
+    {:diffo_example, "~> 0.2"}
   ]
 end
 ```
 
-You need [Neo4j](https://github.com/neo4j/neo4j) available. We recommend the Neo4j Community 5 latest, available at [Neo4j Deploymnent Centre](https://neo4j.com/deployment-center/) which can be installed locally. You can also configure connection to a cloud based database service such as [Neo4j AuraDB](https://neo4j.com/product/auradb/).
+You need [Neo4j](https://github.com/neo4j/neo4j) available. We recommend the Neo4j Community 5 latest, available at the [Neo4j Deployment Centre](https://neo4j.com/deployment-center/) which can be installed locally. You can also configure connection to a cloud-based database service such as [Neo4j AuraDB](https://neo4j.com/product/auradb/).
 
 ## Contributions
 
-Contributions are welcome, please start with an [issue](https://github.com/diffo-dev/diffo_example/issues)
+Contributions are welcome, please start with an [issue](https://github.com/diffo-dev/diffo_example/issues).
 
 ## Acknowledgements
 
 Thanks to my colleagues in the Telco industry.
 
 Thanks to the vibrant Elixir and Ash communities, and in particular the [Ash Core](https://github.com/ash-project) for [ash](https://github.com/ash-project/ash) 🚀
 
-Thanks to [Florin Patrascu](https://github.com/florinpatrascu) for [bolt_sips](https://github.com/florinpatrascu/bolt_sips) and[Luis Sagastume](https://github.com/sagastume) for [boltx](https://github.com/sagastume/boltx), both forerunners of [bolty](https://github.com/diffo-dev/bolty) the bolt driver for neo4j.
+Thanks to [Florin Patrascu](https://github.com/florinpatrascu) for [bolt_sips](https://github.com/florinpatrascu/bolt_sips) and [Luis Sagastume](https://github.com/sagastume) for [boltx](https://github.com/sagastume/boltx), both forerunners of [bolty](https://github.com/diffo-dev/bolty) — the Bolt driver for Neo4j.
 
 Thanks to the [Neo4j Core](https://github.com/neo4j) for [neo4j](https://github.com/neo4j/neo4j) and pioneering work on graph databases.
 
 ## Links
 
-[Diffo TMF Service and Resource Manager](https://github.com/diffo-dev/diffo)
-[Diffo.dev](https://www.diffo.dev)
-[Ash Neo4j Datalayer](https://github.com/diffo-dev/ash_neo4j)
-[bolty](https://github.com/diffo-dev/bolty)
-[Neo4j Deployment Centre](https://neo4j.com/deployment-center/)
-[Ash Outstanding Extension](https://github.com/diffo-dev/ash_outstanding)
-[Outstanding Elixir Protocol](https://github.com/diffo-dev/outstanding)
-[TMF](https://www.tmforum.org)
-
+- [Diffo TMF Service and Resource Manager](https://github.com/diffo-dev/diffo)
+- [Diffo.dev](https://www.diffo.dev)
+- [Ash Neo4j Datalayer](https://github.com/diffo-dev/ash_neo4j)
+- [bolty](https://github.com/diffo-dev/bolty)
+- [Neo4j Deployment Centre](https://neo4j.com/deployment-center/)
+- [Ash Outstanding Extension](https://github.com/diffo-dev/ash_outstanding)
+- [Outstanding Elixir Protocol](https://github.com/diffo-dev/outstanding)
+- [TMF](https://www.tmforum.org)