docs: complete MODULES.md. minor updates elsewhere. prepare for hosting

1 files changed, 41 insertions, 6 deletions

diff --git a/docs/SYNTAX.md b/docs/SYNTAX.md
index a1c8bfb..1bd3331 100644
--- a/docs/SYNTAX.md
+++ b/docs/SYNTAX.md
@@ -1,5 +1,7 @@
 # Syntax: A Casual and Formal Look
 
+> ! This section is **incomplete**. Proceed with caution.
+
 ## Reserved Keywords
 
 The following keywords are reserved:
@@ -15,13 +17,46 @@ The following keywords are reserved:
 - types: `type` `distinct` `ref`
 - types: `struct` `tuple` `union` `enum` `interface`
 - reserved:
-  - `impl` `object` `class` `concept` `auto` `empty` `effect` `case` `nil`
+  - `impl` `object` `class` `concept` `auto` `empty` `effect` `case`
   - `suspend` `resume` `spawn` `pool` `thread` `closure`
   - `cyclic` `acyclic` `sink` `move` `destroy` `copy` `trace` `deepcopy`
 
+The following identifiers are in use by the standard prelude:
+- logic: `not` `and` `or` `xor` `shl` `shr` `div` `mod` `rem`
+- logic: `+` `-` `*` `/` `<` `>` `<=` `>=` `==` `!=` `is`
+- async: `async` `await`
+- types: `int` `uint` `float`
+  - `i8` `i16` `i32` `i64` `i128`
+  - `u8` `u16` `u32` `u64` `u128`
+  - `f32` `f64` `f128`
+  - `dec64` `dec128`
+- types: `bool` `byte` `char` `str`
+- types: `void` `never`
+- strings: `&` (string append)
+
+The following punctuation is taken:
+- `=` (assignment)
+- `.` (chaining)
+- `,` (params)
+- `;` (statements)
+- `:` (types)
+- `#` (comment)
+- `_` (unused bindings)
+- `|` (generics)
+- `\` (string/char escaping)
+- `()` (params, tuples)
+- `{}` (scope, structs)
+- `[]` (generics, lists)
+- `""` (strings)
+- `''` (chars)
+- ``` `` ``` (unquoting)
+- unused: `~` `@` `$` `%`
+
 ## A Formal Grammar
 
-We now shall take a look at a more formal description of Puck's syntax. Syntax rules are described in [extended Backus–Naur form](https://en.wikipedia.org/wiki/Extended_Backus–Naur_form) (EBNF): however, most rules surrounding whitespace, and scope, and line breaks, are modified to how they would appear after a lexing step.
+We now shall take a look at a more formal description of Puck's syntax. 
+
+Syntax rules are described in [extended Backus–Naur form](https://en.wikipedia.org/wiki/Extended_Backus–Naur_form) (EBNF): however, most rules surrounding whitespace, and scope, and line breaks, are modified to how they would appear after a lexing step.
 
 ### Identifiers
 ```
@@ -144,7 +179,7 @@ Body ::= Expr | ('{' Expr (';' Expr)* '}')
 ---
 
 References:
-- https://www.joshwcomeau.com/javascript/statements-vs-expressions/
-- https://pgrandinetti.github.io/compilers/
-- https://docs.swift.org/swift-book/ReferenceManual/LexicalStructure.html
-- https://nim-lang.github.io/Nim/manual.html
+- [Statements vs. Expressions](https://www.joshwcomeau.com/javascript/statements-vs-expressions/)
+- [Swift's Lexical Structure](https://docs.swift.org/swift-book/ReferenceManual/LexicalStructure.html)
+- [The Nim Programming Language](https://nim-lang.github.io/Nim/manual.html)
+- [Pietro's Notes on Compilers](https://pgrandinetti.github.io/compilers/)