diff --git a/agora-yaml.md b/agora-yaml.md
index 26664f7f2..5d0c68ece 100644
--- a/agora-yaml.md
+++ b/agora-yaml.md
@@ -1,12 +1,16 @@
 # Agora Yaml
 
-- [[bmann]] suggested adding [[yaml]] support to the [[agora]].
-  - [[go]] https://github.com/bmann/bmcgarden/blob/master/agora.yaml
-- [[p0]]
-  - It will [[unblock]] many things.
-  - It is a valuable [[design contribution]] from [[bmann]].
-  - https://github.com/flancian/agora/issues/2
 - If you add an ```agora.yaml``` to your [[digital garden]] repository you can use it to configure how the [[agora]] integrates it.
+- a [[project]]
+  - [[bmann]] suggested adding [[yaml]] support to the [[agora]].
+    - [[go]] https://github.com/bmann/bmcgarden/blob/master/agora.yaml
+  - [[p0]]
+    - It will [[unblock]] many things.
+    - It is a valuable [[design contribution]] from [[bmann]].
+    - https://github.com/flancian/agora/issues/2
+  - there's several [[aspects]] to this:
+    - an `agora.yaml` in a garden tells any agora how the garden wishes to be integrated, and how its owner wants to use the [[agora]]
+    - a `gardens.yaml` in an agora configures the [[agora]] in question to interact with a set of data sources.
 - [[push]] [[agora feature requests]]
   - [[idea]] take [[blog posts]] like https://github.com/bmann/bmcgarden/blob/master/_posts/blog/2011-10-11-turning-the-corner-on-ebook-buying.md and integrate them into the date-stripped node, plus perhaps a link from within the date ([[2011-10-11]] in this example).
   
@@ -14,11 +18,12 @@
 
 
 [//begin]: # "Autogenerated link references for markdown compatibility"
+[digital garden]: digital-garden "Digital Garden"
+[agora]: agora "Agora"
+[project]: project "Project"
 [bmann]: bmann "Bmann"
 [yaml]: yaml "Yaml"
-[agora]: agora "Agora"
 [go]: go "Go"
-[digital garden]: digital-garden "Digital Garden"
 [push]: push "Push"
 [idea]: idea "Idea"
 [2021-03-21]: 2021-03-21 "2021-03-21"