Add a modeling spec, just intro text for now

4 files changed, 36 insertions, 2 deletions

diff --git a/build.sh b/build.sh
index 69ebe0d..f595db2 100755
--- a/build.sh
+++ b/build.sh
@@ -2,7 +2,7 @@
 
 set -e
 
-inputs="forgefed vocabulary"
+inputs="forgefed modeling vocabulary"
 
 git_branch=`git rev-parse --abbrev-ref HEAD`
 
diff --git a/html/index.md b/html/index.md
index 22a05e2..5e31727 100644
--- a/html/index.md
+++ b/html/index.md
@@ -58,7 +58,9 @@ platform for testing the protocol and trying new features
 - [Issues tracker](https://notabug.org/peers/forgefed/issues)
 - [Wiki](https://notabug.org/peers/forgefed/wiki)
 - [Forum](https://talk.feneas.org/c/forgefed)
-- [Specification](/vocabulary.html)
+- Specifications:
+    * [Modeling](/modeling.html)
+    * [Vocabulary](/vocabulary.html)
 - [dokk](https://dokk.org/ForgeFed)
 
 
diff --git a/html/template.html b/html/template.html
index c16de67..c8b1a35 100644
--- a/html/template.html
+++ b/html/template.html
@@ -17,6 +17,8 @@
         <a class="nav__link"
            href="/forgefed$suffix$">🗲 behavior</a>
         <a class="nav__link"
+           href="/modeling$suffix$">🛠 modeling</a>
+        <a class="nav__link"
            href="/vocabulary$suffix$">📓 vocabulary</a>
         <a class="nav__link"
            href="https://notabug.org/peers/forgefed/issues">🐞 issues</a>
diff --git a/spec/modeling.md b/spec/modeling.md
new file mode 100644
index 0000000..2cf51a6
--- /dev/null
+++ b/spec/modeling.md
@@ -0,0 +1,30 @@
+---
+title: ForgeFed Modeling
+---
+
+# Abstract
+
+This document describes the rules and guidelines for representing version
+control and project management related objects as linked data, using the
+ForgeFed vocabulary, ActivityStreams 2, and other related vocabularies.
+
+# Introduction
+
+**The ForgeFed modeling specification** is a set of rules and guidelines which
+describe version control repository and project management related objects and
+properties, and specify how to represent them as JSON-LD objects (and linked
+data in general) using the ForgeFed vocabulary and related vocabularies and
+ontologies. Using these modeling rules consistently across implementations and
+instances allows to have a common language spoken across networks of software
+forges, project management apps and more.
+
+The ForgeFed vocabulary specification defines a dedicated vocabulary of
+forge-related terms, and the **modeling specification** uses these terms, along
+with terms that already exist in ActivityPub or elsewhere and can be reused for
+forge federation.
+
+The ForgeFed behavior specification provides instructions for using Activities,
+and which Activities and properties to use, to represent forge events, and
+describes the side-effects these Activities should have. The objects used as
+inputs and outputs of behavior descriptions there are defined here in the
+**modeling specification**.