Work on documentation

docs/Home.md

@@ -8,7 +8,11 @@ Work towards the implementation of a software system like that described in [Pos
 
 ## State of Play
 
-You can read about the current [state of play](md_home_2simon_2workspace_2post-scarcity_2docs_2state-of-play.html).
+You can read about the current [state of play](State-of-play.md).
+
+## Roadmap
+
+There is now a [roadmap](Roadmap.md) for the project.
 
 ## AWFUL WARNING 1
 
@@ -17,8 +21,8 @@ This does not work. It isn't likely to work any time soon. If you want to learn
 What it sets out to be is a Lisp-like system which:
 
 * Can make use (albeit not, at least at first, very efficiently) of machines with at least [Zettabytes](http://highscalability.com/blog/2012/9/11/how-big-is-a-petabyte-exabyte-zettabyte-or-a-yottabyte.html) of RAM;
-* Can make reasonable use of machines with at least tens of thousands of processors;
+* Can make reasonable use of machines with at least billions of processors;
-* Can concurrently support significant numbers of concurrent users, all doing different things, without them ever interfering with one another;
+* Can concurrently support significant numbers of users, all doing different things, without them ever interfering with one another;
 * Can ensure that users cannot escalate privilege;
 * Can ensure users private data remains private.
 
@@ -32,3 +36,41 @@ When Linus Torvalds sat down in his bedroom to write Linux, he had something usa
 
 This project is necessarily experimental and exploratory. I write code, it reveals new problems, I think about them, and I mutate the design. This documentation does not always keep up with the developing source code.
 
+## Building
+
+The substrate of this system is written in plain old fashioned C and built with a Makefile. I regret this decision; I think either Zig or Rust would have been better places to start; but neither of them were sufficiently well developed to support what I wanted to do when I did start.
+
+To build, you need a C compiler; I use GCC, others may work. You need a make utility; I use GNU Make. You need [libcurl](https://curl.se/libcurl/).
+
+With these dependencies in place, clone the repository from [here](https://git.journeyman.cc/simon/post-scarcity/), and run `make` in the resulting project directory. If all goes well you will find and executable, `psse`, in the target directory.
+
+## In use
+
+### Invoking
+
+When invoking the system, the following invokation arguments may be passed:
+```
+        -d      Dump memory to standard out at end of run (copious!);
+        -h      Print this message and exit;
+        -p      Show a prompt (default is no prompt);
+        -v LEVEL
+                Set verbosity to the specified level (0...512)
+                Where bits are interpreted as follows:
+                1       ALLOC;
+                2       ARITH;
+                4       BIND;
+                8       BOOTSTRAP;
+                16      EVAL;
+                32      INPUT/OUTPUT;
+                64      LAMBDA;
+                128     REPL;
+                256     STACK.
+```
+
+Note that any verbosity level produces a great deal of output, and although standardising the output to make it more legible is something I'm continually working on, it's still hard to read the output. It is printed to stderr, so can be redirected to a file for later analysis, which is the best plan.
+
+### Functions and symbols
+
+The following functions and keys are provided as of release 0.0.6:
+
+```

docs/Roadmap.md

@@ -0,0 +1,58 @@
+# Roadmap
+
+With the release of 0.0.6 close, it's time to look at a plan for the future development of the project.
+
+I have an almost-working Lisp interpreter, which, as an interpreter, has many of the features of the language I want. It runs in one thread on one processor.
+
+Given how experimental this all is, I don't think I need it to be a polished interpreter, and polished it isn't. Lots of things are broken.
+
+* garbage collection is pretty broken, and I'n beginning to doubt my whole garbage collection strategy;
+* bignums are horribly broken;
+* there's something very broken in shallow-bound symbols, and that matters and wil have to be fixed;
+* there are undoubtedly many other bugs I don't know about.
+
+However, while I will fix bugs where I can, it's good enough for other people to play with if they're mad enough, and it's time to move on.
+
+## Next major milestones
+
+### Simulated hypercube
+
+There is really no point to this whole project while it remains a single thread running on a single processor. Until I can pass off computation to peer neighbours, I can't begin to understand what the right strategies are for when to do so.
+
+`cond` is explicitly sequential, since later clauses should not be executed at all if earlier ones succeed. `progn` is sort of implicitly sequential, since it's the value of the last form in the sequence which will be returned.
+
+For `mapcar`, the right strategy might be to partition the list argument between each of the idle neighbours, and then reassemble the results that come bask.
+
+For most other things, my hunch is that you pass args which are not self-evaluating to idle neighbours, keeping (at least) one on the originating node to work on while they're busy.
+
+But before that can happen, we need a router on each node which can monitor concurrent traffic on six bidirectional links. I think at least initially what gets written across those links is just S-expressions.
+
+I think a working simulated hypercube is the key milestone for version 0.0.7.
+
+### Sysout, sysin, and system persistance
+
+Doctrine is that the post scarcity computing environment doesn't have a file system, but nevertheless we need some way of making an image of a working system so that, after a catastrophic crash or a power outage, it can be brought back up to a known good state. This also really needs to be in 0.0.7. 
+
+### Better command line experience
+
+The current command line experience is embarrasingly poor. Recallable input history, input line editing, and a proper structure editor are all things that I will need for my comfort.
+
+### Users, groups and ACLs
+
+Allowing multiple users to work together within the same post scarcity computing environment while retaining security and privacy is a major goal. So working out ways for users to sign on and be authenticated, and to configure their own environment, and to set up their own access control lists on objects they create, needs to be another nearish term goal. Probably 0.0.8.
+
+### Homogeneities, regularities, slots, migration, permeability
+
+There are a lot of good ideas about the categorisation and organisation of data which are sketched in my original [Post scarcity software](Post-scarcity-software.md) essay which I've never really developed further because I didn't have the right software environment for them, which now I shall have. It would be good to build them.
+
+### Compiler
+
+I do want this system to have a compiler. I do want compiled functions to be the default. And I do want to understand how to write my own compiler for a system like this. But until I know what the processor architecture of the system I'm targetting is, worrying too much about a compiler seems premature.
+
+### Graphical User Interface
+
+Ultimately I want a graphical user interface at least as fluid and flexible as what we had on Interlisp machines 40 years ago. It's not a near term goal there.
+
+### Real hardware
+
+This machine would be **very** expensive to build, and there's no way I'm ever going to afford more than a sixty-four node machine. But it would be nice to have software which would run effectively on a four billion node machine, if one could ever be built. I think that has to be the target for version 1.0.0.

docs/State-of-play.md

@@ -1,5 +1,16 @@
 # State of Play
 
+## 20260225
+
+A productive day!
+
+I awoke with a plan to fix `cond`. This morning, I execoted it, and it worked.
+This afternoon, I fixed `let`. And this evening, I greatly improved `equal`.
+
+The bug in `member` is still unresolved.
+
+We're getting very close to the release of 0.0.6.
+
 ## 20260224
 
 Found a bug in subtraction, which I hoped might be a clue into the bignum bug;

docs/Topology-of-the-hardware-of-the-deep-future.md

@@ -1,4 +1,8 @@
-![HAL 9000 - a vision of the hardware of the deep future](https://vignette4.wikia.nocookie.net/2001/images/5/59/Hal_console.jpg/revision/latest?cb=20090823025755)In thinking about how to write a software architecture that won't quickly become obsolescent, I find that I'm thinking increasingly about the hardware on which it will run.
+# On the topology of the hardware of the deep future
+
+![HAL 9000 - a vision of the hardware of the deep future](https://vignette4.wikia.nocookie.net/2001/images/5/59/Hal_console.jpg/revision/latest?cb=20090823025755)
+
+In thinking about how to write a software architecture that won't quickly become obsolescent, I find that I'm thinking increasingly about the hardware on which it will run.
 
 In [Post Scarcity Hardware](Post-scarcity-hardware.html) I envisaged a single privileged node which managed main memory. Since then I've come to thing that this is a brittle design which will lead to bottle necks, and that each cons page will be managed by a separate node. So there needs to be a hardware architecture which provides the shortest possible paths between nodes.
 
@@ -14,7 +18,7 @@ If you take a square grid and place a processor at every intersection, it has at
 
 So far so good. Now, let's take square grids and stack them. This gives each node at most six proximal neighbours. We form a cube, and the longest distance between two nodes is `3x`. We can link the nodes on the left of the cube to the corresponding nodes on the right and form a (thick walled) cylinder, and the longest distance between two nodes is `2.5x`. Now join the nodes at the top of the cube to the corresponding nodes at the bottom, and we have a thick walled torus. The maximum distance between is now `2x`.
 
-Let's stop for a moment and think about the difference between logical and physical topology. Suppose we have a printed circuit board with 100 processors on it in a regular grid. We probably could physically bend the circuit board to form a cylinder, but there's no need to do so. We achieve exactly the same connection architecture simply by using wires to connect the left side to the right. And if we use wires to connect those at the top with those at the bottom, we've formed a logical torus even though the board is still flat.
+Let's stop for a moment and think about the difference between logical and physical topology. Suppose we have a printed circuit board with 199 processors on it in a regular grid. We probably could physically bend the circuit board to form a cylinder, but there's no need to do so. We achieve exactly the same connection architecture simply by using wires to connect the left side to the right. And if we use wires to connect those at the top with those at the bottom, we've formed a logical torus even though the board is still flat.
 
 It doesn't even need to be a square board. We could have each processor on a separate board in a rack, with each board having four connectors probably all along the same edge, and use patch wires to connect the boards together into a logical torus.