diff --git a/README.md b/README.md
index a23f336c..d3f31195 100644
--- a/README.md
+++ b/README.md
@@ -55,10 +55,10 @@ The full list is on the net and involves mostly just work.
 
 ### Parse ruby
 
-Parse simple code, using Parslet. This has been seperated out as it's own gem, salama-reader.
+Parse simple code, using Parslet. This has been separated out as it's own gem, [salama-reader](https://github.com/salama/salama-reader).
 
-Parsing is a surprisingly fiddly process, very space and order sensitive. But Parslet is great and simple
-expressions (including function definitions and calls) are starting to work.
+Parsing is a surprisingly fiddly process, very space and order sensitive. But Parslet is great and
+simple expressions (including function definitions and calls) are starting to work.
 
 I spent some time on the parse testing framework, so it is safe to fiddle and add.
 In fact it is very modular and  so ot is easy to add.
diff --git a/lib/virtual/README.md b/lib/virtual/README.md
index 3c15c638..f6b361b6 100644
--- a/lib/virtual/README.md
+++ b/lib/virtual/README.md
@@ -15,12 +15,13 @@ references and possibly more.
 Values have type in the same way objects have a class. We keep track of the type of a value at runtime,
 also in an similar way that objects have their classes at runtime.
 
-### Layers 
+### Layers
 
-*Ast* instances get created by the salama-reader gem from source. 
-Here we add compile functions to ast classes and  comile the ast layer into Virtual:: objects
+*Ast* instances get created by the [salama-reader](https://github.com/salama/salama-reader) gem from
+source.  Here we add compile functions to ast classes and  compile the AST layer into
+Virtual::Objects and Parfait::Values
 
-The main objects are Space (lots of objects), BootClass (represents a class), 
+The main objects are Space (lots of objects), BootClass (represents a class),
 CompiledMethod (with Blocks and Instruction).
 
 **Virtual** Instructions get further transformed into **register** instructions.
@@ -28,7 +29,7 @@ This is done by an abstractly defined Register Machine with basic Intructions.
 A concrete implementation (like Arm) derives and creates derived Instructions.
 
 The transformation is implemented as **passes** to make it easier to understand what is going on.
-Also this makes it easier to add functionality and optimisations from external (to the gem) sources. 
+Also this makes it easier to add functionality and optimisations from external (to the gem) sources.
 
 The final transformation assigns Positions to all boot objects (Linker) and assembles them into a
 binary representation. The data- part is then a representation of classes in the **parfait** runtime.
@@ -51,7 +52,7 @@ There are compare, branch and call intructions too.
 The micro-kernel idea is well stated by: If you can leave it out, do.
 
 
-As such we are aiming for integer and reference (type) support, and a minimal class system 
+As such we are aiming for integer and reference (type) support, and a minimal class system
 (object/class/aray/hash/string). It is possible to add types to the system in a similar way as we add classes,
 and also implement very machine dependent functionality which nevertheless is fully wrapped as OO.
 
@@ -59,4 +60,3 @@ and also implement very machine dependent functionality which nevertheless is fu
 It is parsed, like any other code and always included in the resulting binary.
 **Builtin** is the part of the runtime that can not be coded in ruby (but is still needed).
 This is coded by construction CompiledMethods in code and neccesarily machine dependant.
-
diff --git a/lib/virtual/compiler/README.md b/lib/virtual/compiler/README.md
index d18ce217..4b699580 100644
--- a/lib/virtual/compiler/README.md
+++ b/lib/virtual/compiler/README.md
@@ -1,8 +1,9 @@
 ### Compiling
 
-The Ast (abstract syntax tree) is created by salama-reader gem and the classes defined there
+The Ast (abstract syntax tree) is created by [salama-reader](https://github.com/salama/salama-reader)
+ gem and the classes defined there
 
-The code in this directory compiles the AST to the virtual machine code.
+The code in this directory compiles the AST to the virtual machine code, and Parfait object structure.
 
 If this were an interpreter, we would just walk the tree and do what it says.
 Since it's not things are a little more difficult, especially in time.