Merge pull request #820 from smucclaw/thomasgorissen/documentation-v2

serrynaimo · web-flow · commit 27487f87213e · 2026-01-30T08:45:37.000+08:00
feat(documentation): Badges &amp; Licenses
diff --git a/AGENTS.md b/AGENTS.md
@@ -42,7 +42,7 @@ Coding guidelines for AI agents working in this repository.
 | ------------- | ------------------------------------------------------------------- |
 | `doc/`        | L4 language documentation (reference, courses, tutorials, concepts) |
 | `specs/`      | Development specifications (todo, done, proposals, roadmap)         |
-| `*/README.md` | Component-specific setup and usage                                  |
+| `*/README.md` | Component-specific setup and usage for developers                   |
 
 ## Essential Commands
 
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -42,7 +42,7 @@ Coding guidelines for AI agents working in this repository.
 | ------------- | ------------------------------------------------------------------- |
 | `doc/`        | L4 language documentation (reference, courses, tutorials, concepts) |
 | `specs/`      | Development specifications (todo, done, proposals, roadmap)         |
-| `*/README.md` | Component-specific setup and usage                                  |
+| `*/README.md` | Component-specific setup and usage for developers                   |
 
 ## Essential Commands
 
diff --git a/doc/README.md b/doc/README.md
@@ -10,7 +10,7 @@ Welcome to the L4 language documentation. L4 is a domain-specific language for l
 
 New to L4? Start here:
 
-1. **[Get L4](https://marketplace.visualstudio.com/items?itemName=Legalese.l4-vscode)** - Download the VS Code extension or [code online](https://jl4.legalese.com)
+1. **[Get L4](https://marketplace.visualstudio.com/items?itemName=Legalese.l4-vscode)** - Download the VS Code extension [![L4 Rules-as-code](https://img.shields.io/visual-studio-marketplace/v/Legalese.l4-vscode?color=blue&logo=visualstudiocode&logoColor=white&label=L4%20Rules-as-code)](https://marketplace.visualstudio.com/items?itemName=Legalese.l4-vscode)
 2. **[Foundation Course](courses/foundation/README.md)** - Learn L4 systematically (start here!)
 3. **[Your First L4 File](tutorials/getting-started/first-l4-file.md)** - Hands-on in 15 minutes
 
@@ -115,8 +115,11 @@ Understand the "why" behind L4:
 
 ---
 
-## More Resources
+## Developer Resources
 
-- **[L4 IDE Repository](https://github.com/smucclaw/l4-ide)** - Source code
-- **[Example Code](https://github.com/smucclaw/l4-ide/tree/main/jl4/examples)** - Working examples
-- **[Experiments](https://github.com/smucclaw/l4-ide/tree/main/jl4/experiments)** - Real-world encodings
+- **[Latest Stable Build](https://github.com/smucclaw/l4-ide/releases)** - [![L4-IDE](https://img.shields.io/github/v/release/smucclaw/l4-ide?color=brightgreen&logo=github&label=L4-IDE)](https://github.com/smucclaw/l4-ide/releases/latest)
+- **[L4 IDE Repository](https://github.com/smucclaw/l4-ide)** - Open-Source code
+
+---
+
+L4 is published under the [Apache-2.0 License](https://github.com/smucclaw/l4-ide/blob/main/LICENSE).
diff --git a/doc/SUMMARY.md b/doc/SUMMARY.md
@@ -7,13 +7,12 @@
 
 - [Reference Home](reference/README.md)
 - [Types](reference/types/README.md)
-- [Coercions](reference/types/coercions.md)
 - [Functions](reference/functions/README.md)
 - [Control-Flow](reference/control-flow/README.md)
-- [Comparisons](reference/comparisons/README.md)
-- [Arithmetic]reference/(arithmetic/README.md)
 - [Operators](reference/operators/README.md)
 - [Syntax](reference/syntax/README.md)
+- [Coercions](reference/types/coercions.md)
+- [Regulative](reference/regulative/README.md)
 - [Built-ins](reference/builtins/README.md)
 - [Libraries](reference/libraries/README.md)
 
diff --git a/doc/reference/GLOSSARY.md b/doc/reference/GLOSSARY.md
@@ -49,14 +49,14 @@ Keywords are reserved words that form the structure of L4 programs.
 
 | Keyword     | Purpose                     | Reference                            |
 | ----------- | --------------------------- | ------------------------------------ |
-| **ABOVE**   | Synonym for GREATER THAN    | [COMPARISONS](comparisons/README.md) |
-| **BELOW**   | Synonym for LESS THAN       | [COMPARISONS](comparisons/README.md) |
-| **EQUALS**  | Equality test               | [COMPARISONS](comparisons/README.md) |
-| **GREATER** | Greater than comparison     | [COMPARISONS](comparisons/README.md) |
-| **LESS**    | Less than comparison        | [COMPARISONS](comparisons/README.md) |
-| **THAN**    | Comparison conjunction word | [COMPARISONS](comparisons/README.md) |
-| **LEAST**   | Used in "AT LEAST" (≥)      | [COMPARISONS](comparisons/README.md) |
-| **MOST**    | Used in "AT MOST" (≤)       | [COMPARISONS](comparisons/README.md) |
+| **ABOVE**   | Synonym for GREATER THAN    | [COMPARISONS](operators/comparisons/README.md) |
+| **BELOW**   | Synonym for LESS THAN       | [COMPARISONS](operators/comparisons/README.md) |
+| **EQUALS**  | Equality test               | [COMPARISONS](operators/comparisons/README.md) |
+| **GREATER** | Greater than comparison     | [COMPARISONS](operators/comparisons/README.md) |
+| **LESS**    | Less than comparison        | [COMPARISONS](operators/comparisons/README.md) |
+| **THAN**    | Comparison conjunction word | [COMPARISONS](operators/comparisons/README.md) |
+| **LEAST**   | Used in "AT LEAST" (≥)      | [COMPARISONS](operators/comparisons/README.md) |
+| **MOST**    | Used in "AT MOST" (≤)       | [COMPARISONS](operators/comparisons/README.md) |
 
 ### Type Keywords
 
@@ -99,12 +99,12 @@ For expressing legal obligations, permissions, and prohibitions.
 
 | Keyword     | Purpose                   | Reference                          |
 | ----------- | ------------------------- | ---------------------------------- |
-| **PLUS**    | Addition                  | [ARITHMETIC](arithmetic/README.md) |
-| **MINUS**   | Subtraction               | [ARITHMETIC](arithmetic/README.md) |
-| **TIMES**   | Multiplication            | [ARITHMETIC](arithmetic/README.md) |
-| **DIVIDED** | Division (use with BY)    | [ARITHMETIC](arithmetic/README.md) |
-| **BY**      | Division conjunction word | [ARITHMETIC](arithmetic/README.md) |
-| **MODULO**  | Modulus (remainder)       | [ARITHMETIC](arithmetic/README.md) |
+| **PLUS**    | Addition                  | [ARITHMETIC](operators/arithmetic/README.md) |
+| **MINUS**   | Subtraction               | [ARITHMETIC](operators/arithmetic/README.md) |
+| **TIMES**   | Multiplication            | [ARITHMETIC](operators/arithmetic/README.md) |
+| **DIVIDED** | Division (use with BY)    | [ARITHMETIC](operators/arithmetic/README.md) |
+| **BY**      | Division conjunction word | [ARITHMETIC](operators/arithmetic/README.md) |
+| **MODULO**  | Modulus (remainder)       | [ARITHMETIC](operators/arithmetic/README.md) |
 
 ### Other Keywords
 
diff --git a/doc/reference/SUMMARY.md b/doc/reference/SUMMARY.md
@@ -11,8 +11,6 @@
 ## Language Details
 
 - [Control-Flow](control-flow/README.md)
-- [Comparisons](comparisons/README.md)
-- [Arithmetic](arithmetic/README.md)
 - [Operators](operators/README.md)
 - [Syntax](syntax/README.md)
 - [Coercions](types/coercions.md)
diff --git a/doc/reference/operators/README.md b/doc/reference/operators/README.md
@@ -19,6 +19,8 @@ L4 operators are organized into categories:
 
 Mathematical operations on numbers.
 
+[Details and examples on arithmetic operators](arithmetic/README.md)
+
 ### Addition
 
 - **Keyword:** PLUS
@@ -61,6 +63,8 @@ Mathematical operations on numbers.
 
 Compare values and return BOOLEAN results.
 
+[Details and examples on comparison operators](comparisons/README.md)
+
 ### Equality
 
 - **Keyword:** EQUALS
diff --git a/doc/reference/operators/arithmetic/README.md b/doc/reference/operators/arithmetic/README.md
@@ -150,15 +150,15 @@ IMPORT math
 #EVAL exp 1            -- 2.718...
 ```
 
-See **[Libraries Reference](../libraries/README.md)** for more functions.
+See **[Libraries Reference](../../libraries/README.md)** for more functions.
 
 ## Related Keywords
 
 - **[COMPARISONS](../comparisons/README.md)** - Compare arithmetic results
-- **[IF](../control-flow/IF.md)** - Conditional arithmetic
+- **[IF](../../control-flow/IF.md)** - Conditional arithmetic
 
 ## See Also
 
-- **[Operators Reference](../operators/README.md)** - Full operator documentation
-- **[Types: NUMBER](../types/README.md)** - Numeric types
-- **[Syntax: Precedence](../syntax/README.md)** - Operator precedence rules
+- **[Operators Reference](../README.md)** - Full operator documentation
+- **[Types: NUMBER](../../types/README.md)** - Numeric types
+- **[Syntax: Precedence](../../syntax/README.md)** - Operator precedence rules
diff --git a/doc/reference/operators/arithmetic/arithmetic-example.l4 b/doc/reference/operators/arithmetic/arithmetic-example.l4
diff --git a/doc/reference/operators/comparisons/README.md b/doc/reference/operators/comparisons/README.md
@@ -119,11 +119,11 @@ Comparisons work on:
 
 ## Related Keywords
 
-- **[AND](../operators/AND.md)** - Combine comparisons
-- **[OR](../operators/OR.md)** - Alternative conditions
-- **[IF](../control-flow/IF.md)** - Use comparisons in conditionals
+- **[AND](../AND.md)** - Combine comparisons
+- **[OR](../OR.md)** - Alternative conditions
+- **[IF](../../control-flow/IF.md)** - Use comparisons in conditionals
 
 ## See Also
 
-- **[Operators Reference](../operators/README.md)** - Full operator documentation
-- **[Types Reference](../types/README.md)** - Comparable types
+- **[Operators Reference](../README.md)** - Full operator documentation
+- **[Types Reference](../../types/README.md)** - Comparable types
diff --git a/doc/reference/operators/comparisons/comparisons-example.l4 b/doc/reference/operators/comparisons/comparisons-example.l4
diff --git a/doc/reference/types/README.md b/doc/reference/types/README.md
@@ -21,9 +21,9 @@ L4's type system is inspired by functional programming languages like Haskell an
 Numeric values including integers and rationals.
 
 - Integers: `42`, `-17`, `0`
-- Rationals: `3.14`, `-0.5`, `2.718`
+- Rationals: `3.14`, `-0.5`, `2.718`, `5.4%`
 - Arbitrary precision arithmetic
-- **Examples:** Age calculations, financial amounts, quantities
+- **Examples:** Age calculations, financial amounts, quantities, percentages
 
 ### STRING
 
@@ -63,7 +63,7 @@ Product types with named fields.
 **Example:** [record-example.l4](record-example.l4)
 
 - Named fields with types
-- Field access with `'s` or `THE ... OF`
+- Field access with `'s`
 - Construction with `WITH` keyword
 - **Examples:** Structured data, entities, configurations
 
