Give Programs/ one rule: a directory per kind, nothing loose

Five .asm files sat at the top of Programs/ beside six directories, with
nothing to say which a new file should join - and hello.asm, which is the
native assembler's first target and named in sixteen places, looked like a
stray.

    Programs/
      Examples/     what you read to learn: hello, printHello, inputTest,
                    replCalculator, and Fibonacci, primeSieve and gameOfLife
                    as sets of their own
      Libraries/    included by name, no entry point of their own
      Loader/       loader.asm, and the loadable program it reads
      CosmOS/       the system, its applications and its assembler
      testPrograms/ what 'make test' drives

Loader/ is the one worth explaining. loader.asm is not a demonstration: it
reads a program off a disk, puts the two pieces where the header asks, and
jumps to the entry. CosmOS grew out of it and does the same thing as one of
its commands. It is kept because backward compatibility with the simplest
version of the system is a standing goal, and it was sitting loose next to
the demos as though it were one.

Programs/loadable/ was a directory holding one file called hello.asm - a
third thing of that name, and the name said nothing about why it was there.
It is Loader/loadable.asm now, beside the loader that reads it.

Every reference moved with them: the makefile's program list, twelve
manifest lines, makedisks.sh, native.sh, and four paths across the README
and both manuals. Verified by deleting both build directories and running
the whole suite from nothing.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01E2JrLzFvuFX9fgi1LDRjrW

Programs/makefile

@@ -16,23 +16,27 @@ BUILD ?= build
 # CosmOS owns the filesystem library and the service names, so it is a place to look too.
 INCLUDES = -I Libraries -I CosmOS/Source
 
-# The programs worth building. Files in Libraries/ are left out because they have no
+# The programs worth building. Every one lives in a directory that says what kind it is:
-# entry point of their own, and the ones in testPrograms/ are covered by 'make test'
+# Examples/ is what you read to learn, Loader/ is the standalone loader CosmOS grew out of,
-# in the parent directory.
+# CosmOS/ is the system. Files in Libraries/ are left out because they have no entry point
+# of their own, and the ones in testPrograms/ are covered by 'make test' in the parent
+# directory.
 PROGRAMS = \
 	CosmOS/Source/cosmos.asm \
-	hello.asm \
+	Examples/hello.asm \
-	printHello.asm \
+	Examples/printHello.asm \
-	inputTest.asm \
+	Examples/inputTest.asm \
-	replCalculator.asm \
+	Examples/replCalculator.asm \
-	Fibonacci/8bitFibonacci.asm \
+	Examples/Fibonacci/8bitFibonacci.asm \
-	Fibonacci/16bitFibonacci.asm \
+	Examples/Fibonacci/16bitFibonacci.asm \
-	Fibonacci/32bitFibonacci.asm \
+	Examples/Fibonacci/32bitFibonacci.asm \
-	primeSieve/8bitSieve.asm \
+	Examples/primeSieve/8bitSieve.asm \
-	primeSieve/16bitSegmentedSieve.asm \
+	Examples/primeSieve/16bitSegmentedSieve.asm \
-	primeSieve/16bitSegmentedSieveModern.asm \
+	Examples/primeSieve/16bitSegmentedSieveModern.asm \
-	gameOfLife/16x16Life.asm \
+	Examples/gameOfLife/16x16Life.asm \
-	gameOfLife/16x16LifeModern.asm
+	Examples/gameOfLife/16x16LifeModern.asm \
+	Loader/loader.asm \
+	Loader/loadable.asm
 
 BINARIES = $(PROGRAMS:%.asm=$(BUILD)/%.bin)
 DEPENDENCIES = $(BINARIES:.bin=.d)

README.md

@@ -13,7 +13,7 @@ SplitBit is a custom 8 bit system designed for hobbyist projects and experimenta
 - Interrupts: Software traps, hardware lines from devices, and faults, all arriving through one vector table with a full context save.
 - Devices: A bus registry that says what a machine is made of, so a program can ask rather than being told.
 - Filesystem: SBFS, read and written by SplitBit itself, and by a host tool that speaks the same format so an image can be moved either way.
-- Loadable Programs: A program that was not booted from carries a header saying where it belongs, and Programs/loader.asm reads one off a disk, puts it there, and runs it.
+- Loadable Programs: A program that was not booted from carries a header saying where it belongs, and Programs/Loader/loader.asm reads one off a disk, puts it there, and runs it.
 - An Operating System: CosmOS boots the machine, mounts a disk, lists what is on it, loads a program and runs it, and takes the machine back when it finishes. It comes with a library of programs to run, including a game and a line editor that writes files a person typed.
 - System Services: A loaded program reaches the console and the disk through numbered software interrupts rather than carrying a copy of the code that drives them. The numbers are written down in one file that both sides include, so neither ever types one. It took the editor from 4941 bytes to 1983 without changing a line of what it does.
 - A Native Assembler: SplitBit assembles SplitBit. Programs/CosmOS/Assembler/ is an assembler written in SplitBit assembly that runs under CosmOS, reads source off a SplitBit disk, and writes a binary back to it with no host involved. It builds boot images and loadable applications, following every directive the language has. IT ASSEMBLES COSMOS, AND IT ASSEMBLES ITSELF, both byte for byte identical to what the C assembler produces from the same source. Tests/native.sh then boots the CosmOS that CosmOS built and has that one assemble CosmOS again, so the machinery has been through itself: after that the host is a convenience rather than a necessity.
@@ -35,7 +35,7 @@ make
 The sources are ISO C, and build clean under -std=c11 -pedantic with -Wall -Wextra. Beyond ISO C they need POSIX.1-2008, which the makefile asks for by name, and getopt_long for the long form of the command line options.
 3) Assemble a program:
 ```
-./Assembler Programs/hello.asm
+./Assembler Programs/Examples/hello.asm
 ```
 
 4) Run the program:

SplitBit Assembler Manual.md

@@ -306,7 +306,7 @@ An absolute path is taken as it is written. If the file turns up nowhere, the as
 Because a library is normally referred to by name alone, a program that uses one has to be told where the libraries live:
 
 ```
-Assembler -I Libraries primeSieve/8bitSieve.asm
+Assembler -I Libraries Examples/primeSieve/8bitSieve.asm
 ```
 
 Including the same file twice does nothing the second time, so two libraries may both depend on a third without the program that uses them having to know. The assembler compares files by where they really are rather than by how they were spelled, so the same library reached by two different routes is still only assembled once.
@@ -491,7 +491,7 @@ wrote hello.bin: program 17, data 14, labels 2
 
 Loading and running are separate commands in CosmOS, so the source file is the argument to `run`.
 
-**Its output must be byte for byte what the host assembler produces from the same source**, and `Tests/native.sh` checks exactly that: it assembles `Programs/hello.asm` both ways and compares the files, then runs the one the machine built. This is the discipline SplitDisk and `sbfs.asm` already work under — two implementations of one written specification, each one checking the other. "It ran" is not good enough for an assembler, because a binary with a label one byte out runs right up until it jumps into the middle of an instruction.
+**Its output must be byte for byte what the host assembler produces from the same source**, and `Tests/native.sh` checks exactly that: it assembles `Programs/Examples/hello.asm` both ways and compares the files, then runs the one the machine built. This is the discipline SplitDisk and `sbfs.asm` already work under — two implementations of one written specification, each one checking the other. "It ran" is not good enough for an assembler, because a binary with a label one byte out runs right up until it jumps into the middle of an instruction.
 
 ### How It Differs Inside:
 

SplitBit Programming Manual.md

@@ -688,7 +688,7 @@ A program that was not the one the machine booted from carries sixteen bytes in
 | 14 | 2 | How many bytes of data there are. |
 | 16 | | The code, then the data, then the vectors. |
 
-Programs/loader.asm reads one off a disk, puts the two pieces where the header asks, and jumps to the entry with BRD. Every part of that already existed: the filesystem finds the file, the memory controller writes Program Memory, and BRD turns an address worked out at run time into somewhere to go. The header is the only new thing. Programs/CosmOS does the same as one of its commands, and then takes the machine back afterwards, which the standalone loader has no way to do.
+Programs/Loader/loader.asm reads one off a disk, puts the two pieces where the header asks, and jumps to the entry with BRD. Every part of that already existed: the filesystem finds the file, the memory controller writes Program Memory, and BRD turns an address worked out at run time into somewhere to go. The header is the only new thing. Programs/CosmOS does the same as one of its commands, and then takes the machine back afterwards, which the standalone loader has no way to do.
 
 The magic matters for the same reason it does everywhere else on this machine. Without it, loading a text file would put nonsense into Program Memory and then jump into it.
 

Tests/makedisks.sh

@@ -46,7 +46,7 @@ for i in 1 2 3 4 5 6 7 8; do "$TOOL" put "$DISKS/sbfs.img" "filler$i.txt" >/dev/
 # bytes, so that what gets loaded is always built from the source beside it.
 "$TOOL" format "$DISKS/load.img" 64 2 >/dev/null
 # The assembler writes a loadable program itself, because the source says where it goes.
-"$ROOT/Assembler" "$ROOT/Programs/loadable/hello.asm" -o "$WORK/hello.sbx" >/dev/null
+"$ROOT/Assembler" "$ROOT/Programs/Loader/loadable.asm" -o "$WORK/hello.sbx" >/dev/null
 "$TOOL" put "$DISKS/load.img" "$WORK/hello.sbx" >/dev/null
 
 # A disk for CosmOS. greet.sbx asks the system for everything it does rather than talking
@@ -170,7 +170,7 @@ awk 'BEGIN { for (i = 0; i < 50; i++) printf "small %05d\n", i }' > small.txt
 # oldest program in the repository: the first thing this machine ever ran is the first
 # thing it assembles for itself.
 "$TOOL" format "$DISKS/asm.img" 2048 4 >/dev/null
-cp "$ROOT/Programs/hello.asm" hello.asm
+cp "$ROOT/Programs/Examples/hello.asm" hello.asm
 "$TOOL" put "$DISKS/asm.img" hello.asm >/dev/null
 "$ROOT/Assembler" -I "$ROOT/Programs/CosmOS/Source" -I "$ROOT/Programs/CosmOS/Assembler" \
     "$ROOT/Programs/CosmOS/Assembler/readTest.asm" -o "$WORK/readTest.sbx" >/dev/null

Tests/manifest

@@ -30,16 +30,16 @@
 # on what a program prints.
 
 # ---- Programs that halt on their own ----
-hello                | hello.asm                          | run      | -                  | -
+hello                | Examples/hello.asm                 | run      | -                  | -
-printHello           | printHello.asm                     | run      | -                  | -
+printHello           | Examples/printHello.asm            | run      | -                  | -
-8bitFibonacci        | Fibonacci/8bitFibonacci.asm        | run      | -                  | -
+8bitFibonacci        | Examples/Fibonacci/8bitFibonacci.asm        | run      | -                  | -
-16bitFibonacci       | Fibonacci/16bitFibonacci.asm       | run      | -                  | -
+16bitFibonacci       | Examples/Fibonacci/16bitFibonacci.asm       | run      | -                  | -
-32bitFibonacci       | Fibonacci/32bitFibonacci.asm       | run      | -                  | -
+32bitFibonacci       | Examples/Fibonacci/32bitFibonacci.asm       | run      | -                  | -
-8bitSieve            | primeSieve/8bitSieve.asm           | run      | -                  | -
+8bitSieve            | Examples/primeSieve/8bitSieve.asm           | run      | -                  | -
-16bitSegmentedSieve  | primeSieve/16bitSegmentedSieve.asm | run      | -                  | -
+16bitSegmentedSieve  | Examples/primeSieve/16bitSegmentedSieve.asm | run      | -                  | -
 # The four pointer rewrite. It emits exactly the same primes as the line above, which
 # is the whole point of keeping both: the pair is a direct before and after.
-16bitSegmentedSieveModern | primeSieve/16bitSegmentedSieveModern.asm | run | -        | -
+16bitSegmentedSieveModern | Examples/primeSieve/16bitSegmentedSieveModern.asm | run | -        | -
 mathTest             | testPrograms/mathTest.asm          | run      | -                  | -
 printTest            | testPrograms/printTest.asm         | run      | -                  | -
 int16print           | Libraries/int16print.asm           | run      | -                  | -
@@ -86,7 +86,7 @@ sbfsEditTest         | testPrograms/sbfsEditTest.asm      | run      | -
 # Loading a program off a disk and running it. Everything below this line existed before
 # the loader did; the only new part is the sixteen bytes on the front of a loadable
 # program saying where it goes.
-loader               | loader.asm                         | run      | -                  | -     | disks/load.img
+loader               | Loader/loader.asm                  | run      | -                  | -     | disks/load.img
 
 # Storage. The image is made fresh for each run, so block 3 starts as zeroes.
 diskTest             | testPrograms/diskTest.asm          | run      | -                  | -     | disk.img
@@ -348,20 +348,20 @@ asm-tokenTest        | CosmOS/Assembler/tokenTest.asm     | assemble | -
 asm-scratch          | CosmOS/Assembler/scratch.asm       | assemble | -                  | -
 
 # ---- Programs driven by console input ----
-inputTest            | inputTest.asm                      | run      | inputTest.in       | -
+inputTest            | Examples/inputTest.asm             | run      | inputTest.in       | -
 inputTestOld         | testPrograms/inputTest.asm         | run      | inputTest.in       | -
-replCalculator       | replCalculator.asm                 | run      | replCalculator.in  | -
+replCalculator       | Examples/replCalculator.asm        | run      | replCalculator.in  | -
 
 # ---- Programs that run forever by design, bounded by a cycle count ----
 # 3,000,000 cycles is about fourteen generations of the glider, which puts
 # evolveBoard and its pointer juggling through its paces many times over.
-16x16Life            | gameOfLife/16x16Life.asm           | run      | -                  | 3000000
+16x16Life            | Examples/gameOfLife/16x16Life.asm           | run      | -                  | 3000000
 # The four pointer rewrite, on the same budget so the two can be compared directly.
 # Note that this cannot show a speed difference: frameDelay is 255 by 255 and swamps
 # the simulation, so both versions render the same fourteen generations and produce
 # identical bytes. What it checks is that the rewrite still evolves the board the same
 # way, which is what a regression test is for.
-16x16LifeModern      | gameOfLife/16x16LifeModern.asm     | run      | -                  | 3000000
+16x16LifeModern      | Examples/gameOfLife/16x16LifeModern.asm     | run      | -                  | 3000000
 
 # ---- Libraries: no entry point, so only check that they assemble ----
 # The CosmOS libraries assemble on their own, unlike print.asm below, which cannot: it

Tests/native.sh

@@ -57,7 +57,7 @@ mkdir -p "$WORK"
     -o "$WORK/Asm.sbx" "$ROOT/Programs/CosmOS/Assembler/Asm.asm" >/dev/null || exit 1
 
 "$TOOL" format "$WORK/native.img" 2048 4 >/dev/null
-"$TOOL" put "$WORK/native.img" "$ROOT/Programs/hello.asm" hello.asm >/dev/null
+"$TOOL" put "$WORK/native.img" "$ROOT/Programs/Examples/hello.asm" hello.asm >/dev/null
 "$TOOL" put "$WORK/native.img" "$WORK/Asm.sbx" Asm.sbx >/dev/null
 
 # The applications, and the file of service names they all include. These are the reason
@@ -86,7 +86,7 @@ done
 check "it wrote a file" grep -q "wrote hello.bin" "$WORK/session.txt"
 
 # ---- And the file is the one the host assembler makes ----
-"$ASM" -o "$WORK/reference.bin" "$ROOT/Programs/hello.asm" >/dev/null
+"$ASM" -o "$WORK/reference.bin" "$ROOT/Programs/Examples/hello.asm" >/dev/null
 "$TOOL" get "$WORK/native.img" hello.bin "$WORK/native.bin" >/dev/null 2>&1
 if [ -f "$WORK/native.bin" ]; then
     REPORT="$(wc -c < "$WORK/native.bin" | tr -d ' ') bytes"