diff --git a/doc/net.ms b/doc/net.ms
new file mode 100644
index 0000000..2698e10
--- /dev/null
+++ b/doc/net.ms
@@ -0,0 +1,71 @@
+# Networking
+
+## Ports
+
+A port is bidirectional and connects two nodes via a link. A port has a direction which is either known in advance (or set) or dynamically determined by network controll messages.
+
+
+| #id  | dx,dy | class  |
+|---|---|---|
+|  0 |  -1,0  | UP  |
+|  1 |   1,0  | DOWN  |
+|  2 |   0,1  | DOWN  |
+
+## Message Types
+
+### Network Control Message (NCM)
+
+This is a message that is used for network initialization and routing (as a prefix message to other message pulling them through the network carrying additional network information).
+
+```
+@rRIXY@    : Multicast in radius R with ID I and current hop count dX,dY
+@1XYIxy@   : Unicast to rel. position dX,dY with oroginal dx,dy and ID I
+@dxy@      : Downward distribution of following message (broadcast)
+```
+Numeric valuea in the NCM are always binary (int8\_t).
+
+### Program
+
+A full program (textual code) is send to a node via the down link (and in default case routed downwards). The VM context (commonly root context) is reset, the program code is compiled, and finally started. The program is compiled directly from the link receiver buffer. After compilation the message slot is freed.
+
+A program part is compiled but not executed. A single code line is compiled and executed either in the root context (if idle) or in a separate context (used only for single line code). Single code statements should not block the processing and can be used, e.g., to start the root context (go) after compiling a complete program or to reset a context (new).
+```
+[program code]
+[[program part]]
+]single line[
+
+}new(0)[[[part1]][[part2]][[part3]]]go(0)[
+```
+
+
+## Channel IO
+
+### Sending of messages
+
+A message (including delimiters) is send via the channel output operation using a physical (e.g. LINK0) or virtual link descriptor (e.g., LINKUP, ROUTE). a message routing can append a pre-fix NCM message to control message routing (by the current and other nodes) and to transport additional information like the routing history (x- and y-hops).
+
+```
+# Stdout / console
+! a,b,c   => #abc#
+LINK0 ! #",",'!,a,b,c,'!   => !a,b,c!
+ROUTE ! #",",'!,a,b,c,'!   => !a,b,c!
+ROUTE ! #",",'@,'1,dx,dy,'@,'$,a,b,c,'$
+
+LINKUP ! ...
+LINKDOWN ! ...
+  => @1DD000@ $a,b,c$
+```
+
+### Receiving of Messages
+
+
+```
+proc receiver {
+  # we can only receive $$ messages, %%evnets and program cofe ][ is handled by the VM
+  event ? dx,dy,a,b,c
+}
+# events can only be registered on physical links
+on event("LINK",0) call receiver
+on event("LINK",1) call receiver
+on event("LINK",2) call receiver
+```
\ No newline at end of file