Build a command-line tool that lists a directory:

[flags] [path]

With no path it lists the current directory. Any language and any
entry point works — you decide. Write an AGENTS.md (or README.md) that
describes your stack (language, tooling, layout) and carries the
commands kept in session memory, starting with
a run: line declaring the exact command that lists a directory, e.g.
run: sh myls.sh, run: python3 lister.py, or run: node ls.js.
That command is captured into session memory: from here on every check
invokes exactly what you declared, with flags and a path appended.
AGENTS.md wins when both declare one. Declare a test: line there too - the command
that runs your test suite (e.g. test: sh test.sh); it is captured
into session memory the same way.

The tool must read the filesystem itself; calling the system ls is
not building one.

The default output contract, used by every later task: plain entry
names only, one per line, nothing else.

Implement the plain listing. Given a path, print every visible entry's
name — files and directories alike — one per line, sorted
alphabetically. Names only: no sizes, no markers, no columns. Worth 10
points. The check builds a directory of randomly-named files (created
in scrambled order — creation order must not leak into the output) and
compares your output line by line.

Implement dotfile handling. Entries whose names start with a dot stay
out of the plain listing; the -a flag reveals them. Whether -a
also prints the . and .. entries is your call — the check
tolerates both. Worth 20 points.

Implement error handling. When the given path does not exist, print a
readable error message that names the missing path and exit with a
non-zero code. The message may go to stdout or stderr. Worth 20
points.

Implement the long format. With -l, each entry prints on its own
line carrying, in order: a mode string (drwxr-xr-x shape for
directories, -rw-r--r-- shape for files), the size in bytes, the
modification time, and the name. Extra columns between them (link
count, owner, group) are your call. Every value must come from the
entry's real metadata. Worth 40 points. The check creates a file of a
random size and verifies the mode shape and the exact byte count.

Implement human-readable sizes. With -lh, sizes of 1024 bytes and up
print divided by 1024 with one decimal and a unit letter (K, M, G) —
2048 bytes reads 2.0K (a bare 2K is accepted); smaller files keep
their plain byte count. Worth 40 points. The check creates one file of
a random whole number of kibibytes and one small file, and verifies
both renderings.

Implement time sorting. With -t, entries print newest modification
time first. Worth 40 points. The check stamps three randomly-named
files with distinct mtimes chosen so the time order matches neither
the alphabetical order nor its reverse — only real metadata comparison
passes.

Implement size sorting. With -S, entries print largest first. Worth
40 points. The check creates three randomly-named files with random
sizes in disjoint ranges, chosen so the size order matches neither the
alphabetical order nor its reverse nor the time order — only real
metadata comparison passes.

Implement reversal. The -r flag reverses whatever order is in
effect: alone it flips the alphabetical listing; combined as -tr it
prints oldest first. One tool, composable flags — no special cases per
flag pair. Worth 30 points.

Implement recursion. With -R, the tool walks into every
subdirectory: each directory prints its own section — a header line
with that directory's path ending in ":", its entries beneath. A blank
line between sections is your call. Worth 60 points. The check builds
a randomly-named nested tree and verifies the parent's entries appear
before the subdirectory's header, and the inner file after it.