FRST Computer -- User Manual
============================

FRST is a personal computer in the Plan 9 tradition.  E-ink display,
LoRa mesh radio, cryptographic identity.  The system presents itself
as a tree of files: devices, processes, network connections, and
remote services all appear at fixed paths.  Programs read and write
those files; the shell composes them.  There is no other interface.

This manual is in eight parts.  Part I describes the shell and the
filesystem -- how the parts fit together.  Part II walks through the
editing tools.  Parts III and IV cover the network: the data crystal
that carries your TCP, the small-internet clients (gopher, telnet,
the BBS), and the WiFi configuration that brings it all up.  Parts V
through VIII document identity and the mesh, programming, the games
and emulators that ship in /n/local, and the hardware itself.


PART I -- THE SYSTEM
====================


THE SHELL (zrc)
---------------

zrc is a clone of Plan 9's rc(1).  The basics:

  ls                    list current directory
  cat file              print a file
  ls | grep txt         pipe
  echo hello > out      redirect stdout (truncate)
  echo world >> out     redirect stdout (append)
  cat < in              redirect stdin
  x=hello               assign (no spaces around =)
  echo $x               substitute
  files=(a.txt b.txt)   list value
  echo `{date}          command substitution
  if (test -f f) ...    conditional
  for (f in *.rc) ...   loop
  fn greet { ... }      function

Up/down arrows recall history.  $status holds the last command's
exit code.  Source a script with `. PATH`.  Write your own:

  echo 'echo hello $1' > /n/local/rc/hi
  hi world

$path is searched for unqualified command names; the default
includes /n/local/rc and its bbs/games/lib subdirectories.  See
zrc(1) for the complete grammar.


THE FILESYSTEM
--------------

Everything visible to the system lives somewhere in the tree.

  /dev          device files (cons, time, factotum, ...)
  /env          environment variables, one file per name
  /proc         processes
  /srv          posted 9P services
  /n/local      LittleFS, your writable storage
  /n/dc         the data crystal you have attune'd to (when mounted)

  Every command below has a manual page on this deck.  `man cmd`
  reads it, `man -k word` searches when you don't know the name.
  /net          tcp, udp, dns -- synthesized by the network stack

The standard tools work on any of them:

  ls path       list
  cat file      print
  cp src dst    copy
  mv old new    rename / move
  rm file       delete
  mkdir dir     create directory
  stat file     show metadata
  grep PAT file search inside files
  wc file       count lines, words, bytes
  glob PATTERN  match filenames

There is no special API for any of these.  The environment is
files:

  cat /env/user
  echo other > /env/user

The clock is a file:

  cat /dev/time
  echo 1714867200 > /dev/time   # set unix epoch

This is the whole trick.


NAMESPACES
----------

Three operations turn a 9P service into a directory you can ls and
cat.

  srv DIAL NAME            open a connection, post it at /srv/NAME
  mount /srv/NAME PATH     graft the service's filesystem at PATH
  bind SRC DST             rewire one path in your namespace

attune(1) is the script that runs the right combination to bring up
the data crystal:

  attune                   srv tcp!aether...; mount /srv/dc /n/dc;
                            bind /n/dc/net /net

Print the current namespace:

  ns

Drop a connection:

  hangup NAME              tear down /srv/NAME and any mounts


PART II -- EDITORS AND PAGER
============================


READING -- p
------------

p is the pager; it is tuned for e-ink: clean typography, page-at-
a-time, no animation.

  p file              page through file
  cat file | p        pipe anything through it
  p -f file           fast mode -- skip full e-ink refresh on page
                       turn (for dense reading sessions)

  Space, Enter        next page
  b                   previous page
  g, G                first / last page
  /pattern            search forward
  q                   quit


THE EDITORS
-----------

Four editors ship; pick the one that fits the task.

ed(1) is the line editor.  Tiny, fast, scriptable, and the
foundation everything else borrows from:

  ed file
  ,p          print all lines
  3           go to line 3
  a           append (`.' on its own line ends input)
  d           delete current line
  s/old/new/  substitute on current line
  ,s/x/y/g    substitute everywhere
  w           write
  q           quit

sam is structural editing.  Address regions with regular
expressions; chain commands:

  ,x/error/+a/[FIXED] /        prepend [FIXED] before every "error"
  ,x/^[ \t]+$/d                delete blank/whitespace-only lines

vi is the modal editor:

  hjkl                  move
  i / a / o             insert
  Esc                   normal mode
  dd / yy / p           delete / yank / paste
  /pattern              search
  :w / :q / :wq         write, quit, both
  u                     undo

se is a simple full-screen editor.  No modes, just type; arrow
keys move.

sed is the stream editor for batch jobs:

  sed 's/old/new/' file
  cat log | sed -n '/error/p'


TASKS -- todo
-------------

todo opens an outliner that lives on the device.  Status sigils:

  (blank)   not started
  ~         in progress
  x         done

  todo                   open the default list
  todo /n/local/plans    open a specific list

  a, Enter   add an item
  d, Bksp    delete
  Tab        indent (sub-item)
  Sh-Tab     outdent
  arrows     navigate
  Enter      toggle status
  q          save and quit


PART III -- THE NETWORK
=======================


THE DATA CRYSTAL
----------------

A data crystal is a remote 9P server that exports a filesystem to
your deck: BBS rooms, identity, /net/tcp, time, sometimes more.
You attune to one over BLE L2CAP (deck-to-deck) or TCP (over WiFi
or, in the WASM build, a wss:// bridge).

  attune                bring up the crystal under /n/dc;
                         bind /n/dc/net over /net

The default endpoint is bbs.frstcomputer.net:9777 (plain TCP on
hardware; 8443 over wss:// in the browser).  Override before
calling:

  env dc_host my.host
  env dc_port 9777
  attune

After attune, /net/tcp comes from the crystal -- telnet and gopher
exit through it -- and /n/dc/* exposes whatever filesystems the
crystal provides (typically /forum, /chat, /etc, /admin).

  ls /n/dc
  cat /n/dc/etc/motd

To detach:

  hangup dc


WiFi -- /net/wifi
-----------------

WiFi is configured through files: read /net/wifi/status and
/net/wifi/scan, write verbs to /net/wifi/ctl.

  cat /net/wifi/status                     state + saved networks
  echo scan >/net/wifi/ctl                 start a scan
  cat /net/wifi/scan                       results (re-run after a moment)
  echo 'connect SSID PSK' >/net/wifi/ctl   join, remember, auto-join on boot
  echo 'forget SSID' >/net/wifi/ctl        drop a saved network
  echo 'autoconnect off' >/net/wifi/ctl    disable boot auto-join
  echo disconnect >/net/wifi/ctl

Up to eight networks persist to /lfs/net/credentials; on boot the deck
scans and joins whichever saved network is in range.  The Zephyr `net`
shell namespace (Ctrl-Z, then `net iface`) provides lower-level
diagnostics.


GOPHER -- gopher
----------------

Gopher is what the web could have been: text first, hierarchical,
quiet.

  gopher host                       fetch root menu
  gopher host selector              fetch a specific path
  gopher host selector port         non-default port

  arrows / hjkl    navigate menu items
  Enter            follow item
  b                back
  q                quit

Bookmarks save under /n/local/gopher/.


TELNET, vt, AND BOARDS
----------------------

telnet auto-wraps in vt(1), the terminal emulator, so ANSI art and
cursor movement render right.

  telnet host           default port 23
  telnet host port      explicit port
  telnet -r host        raw, skip the vt wrapper

To leave a session: Ctrl-] then `quit`.

vt is the terminal emulator itself; the wrapper is one of its
modes.  Other modes:

  vt local              promote vt to the active screen for zrc;
                         useful when you want full ANSI behavior
                         on local commands.  Exit with `vt off`.
  vt cat /n/local/log   render a file with full ANSI handling

vt understands a working subset of VT100 plus the parts of ANSI
that BBS art relies on: cursor motion, scroll regions, DEC line
drawing (mapped to CP437), CP437 0x80-0xFF block elements, and an
SGR mapping for monochrome -- bright fg becomes bold, background
colors become inverse, color codes that have no mono equivalent
are dropped.  Blink is silently ignored on e-ink (the panel cannot
do it without thrashing).

boards is a curated dialing book for telnet BBSes:

  boards                show the menu
  boards N              dial entry N directly


THE BBS -- bbs
--------------

bbs is the FRST commons, served over 9P from whichever data
crystal you have attuned to.

  bbs                   start the client
  bbs DIAL              dial a different crystal first

  arrows / hjkl    navigate
  Enter            enter a room / open a message
  Esc, q           back / quit
  /                command line: post, motd, search, info, ...
  R                reply to selected message
  P                post a new message in the current room

The BBS connects as `guest` if no identity is configured; run
setup(1) to claim a handle.  Without an identity, you can read but
your posts will be attributed to "guest".


PART IV -- IDENTITY AND MESH
============================


IDENTITY -- factotum, setup, id
-------------------------------

FRST identifies you on the mesh by a CGA -- a cryptographically
generated address derived from your public key.  The private key
lives in the factotum service at /dev/factotum and never leaves
the deck.  Your handle is yours; logging into any FRST with the
same key reads as the same person to every aetherd.

  setup                 first-boot keypair + handle prompt
  id                    show or manage your identity
  id gen                generate a key (if none yet)
  id set NAME           change your handle
  id del                delete the key (irreversible)
  cat /dev/factotum/ctl current identity

The factotum file under /dev/factotum exposes the key as a 9P
service: aetherd reads it during attune to verify you, but no
file in /dev/factotum exports the private key bytes.


THE AETHER MESH -- chat
-----------------------

LoRa packet messaging, ~900 MHz, no infrastructure, no fees.
Range is line-of-sight kilometers; FRSTs in range relay each
other's packets.

  chat                  open the aether chat client


PART V -- PROGRAMMING
=====================


pforth
------

A portable Forth interpreter with the standard core word set,
embedded into zrc.

  forth                 launch the interpreter
  2 3 + .               5
  : SQUARE DUP * ;      define a word
  7 SQUARE .            49
  INCLUDE /n/local/forth/lib.fth
  BYE                   exit

Forth source lives in /n/local/forth/.


PART VI -- DIVERSIONS
=====================


Games launch directly from the prompt:

  wumpus      hunt the wumpus through a 20-room cave
  hangman     guess the word
  blackjack   beat the dealer
  chess       two-player, algebraic notation (e2e4 ...)
  snake       grow without hitting yourself
  tetris      hjkl moves and rotates
  arithmetic  math drills
  fractal     mandelbrot / julia rendered to e-ink

woz emulates Steve Wozniak's Apple 1:

  woz                   start at the Woz Monitor (\ prompt)
  E000R                 jump to Integer BASIC
  F000R                 jump to the Krusader assembler

Press Ctrl-C to return to zrc.

frotz plays Z-machine interactive fiction:

  frotz file.z5         load a story file
  zork                  shortcut for the bundled Zork I

Smaller diversions:

  fortune               random epigram
  pom                   phase of the moon
  morse TEXT            ascii to morse
  mavis                 typing tutor
  slides FILE.slides    presentation viewer; -a to auto-advance


PART VII -- SYSTEM
==================


DATE AND TIME
-------------

  date                  print
  setdate               interactive set, MS-DOS style
  cat /dev/time         epoch seconds
  echo SECS > /dev/time set epoch directly

Timezone and 12/24-hour preference live in $tz and $time_format
(env(1)); set them in /n/local/rc/lib/profile to persist.


POWER
-----

The display dims after 2 minutes idle and goes dark after 5; any
key wakes it.  The frontlight is on /dev/frontlight:

  echo 50 > /dev/frontlight/level   # 0-100


THE ZEPHYR SHELL
----------------

Beneath zrc is the underlying Zephyr command shell, useful for
low-level diagnostics (network counters, memory, threads).

  Ctrl-Z                drop to Zephyr shell
  shell                 return to zrc

The Zephyr shell does not understand zrc syntax; it has its own
command set.  `help` lists what's available there.


FILESYSTEM UPGRADE
------------------

When new firmware ships with updated bundled files (rc scripts,
text, fonts), the deck warns at boot:

  Bundled content updated since last visit (...)
  Run `fsupgrade` to merge new files...

To take the new files in:

  fsupgrade              merge: bundled files added/updated, your
                          edits preserved
  fsupgrade -f           force: reset /n/local to the bundle,
                          discarding any local edits


PART VIII -- HARDWARE
=====================


  Processor    ESP32-S3 dual-core @ 240 MHz, 8 MB PSRAM
  Display      7.5" e-paper, 800x480, monochrome, partial-refresh
  Radios       LoRa (Semtech SX1262, sub-GHz mesh) and WiFi/BLE 5.0
  Keyboard     wired UART or BLE, 9P over the chosen link
  Storage      16 MB flash: 3 MB LittleFS + NVS + OTA slots
  Lighting     6x WS2812 frontlight LEDs, adjustable
  Boot         MCUboot with secure boot and OTA support


VERSION
=======

frstcomputer.com -- for the few of us.
