initial commit

crates/loic-cli/README.md

@@ -0,0 +1,111 @@
+# loic-cli
+
+A command-line oracle for temporal inquiry. The primary display surface for the Loic Calendar's lattice structure.
+
+## Installation
+
+### From Source
+
+```bash
+cargo install --path crates/loic-cli
+```
+
+The binary installs as `loic-cli`.
+
+## Usage
+
+### Default Observation (Entropy-Selected)
+
+```bash
+$ loic-cli
+```
+
+With no arguments, the oracle declines to frame the question. Nine bits of hardware entropy select the mask:
+
+- **75% probability:** A valid mask emerges. The slot machine renders two columns—cosmic and cycle—showing the Hasse diagram neighborhood of the selected observation. Up to three finer neighbors above, the active mask centered, up to three coarser neighbors below.
+- **25% probability:** The cosmic pool overflows. Resolution collapse. Channel 2 falls to resolution zero; Channel 1 keeps producing. Raw entropy floods the terminal. On Ctrl+C, a topological scar—a zero-resource ghost process named with cosmic time digits—detaches into the process table. It ignores every signal it can; only SIGKILL ends it. It persists until reboot.
+
+### Explicit Mask
+
+```bash
+$ loic-cli --mask heptad                    # Single prime
+$ loic-cli --mask pentad,heptad,hendecad    # Combined
+$ loic-cli --mask notyte                    # Cosmic prime observation
+$ loic-cli --mask 0x0480                    # Hex (15-bit, 0x0000–0x7FFF)
+$ loic-cli --mask 0b110                     # Binary
+$ loic-cli --mask 42                        # Decimal
+$ loic-cli --mask whisper                   # No primes: the undivided whole
+$ loic-cli --mask full                      # All fifteen: the finest question there is
+```
+
+The 15 prime names (case-insensitive):
+
+**Cosmic:** Andyte, Xoryte, Oryte, Noryte, Xnoryte, Notyte, Nandyte
+**Cycle:** Dyad, Pentad, Heptad, Hendecad, Sigma, Tau, Phi, Psi
+
+### The Slot Machine
+
+Output is two vertical columns—cosmic and cycle—each showing the Hasse diagram neighborhood of the current mask:
+
+```
+               COSMIC                                CYCLE
+────────────────────────────────────  ────────────────────────────────────
+          Andyte × Notyte                    Dyad × Heptad
+          Xoryte × Notyte                   Pentad × Heptad
+          Oryte × Notyte                   Heptad × Hendecad
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+           ▶ Notyte ◀                       ▶ Heptad ◀
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━  ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+             Whisper                           Whisper
+────────────────────────────────────  ────────────────────────────────────
+ pos 0/298824857074158001946609249                  pos 3/7
+
+  74463832547931847158857533574110627724043672075203207 Planck times into the current cycle subdivision
+```
+
+- **Above the selected row:** Parents—masks engaging one more prime. A larger divisor, a smaller part, a finer resolution: the subdivisions the current one contains.
+- **Selected row (▶ ◀):** The active mask, split into its cosmic and cycle components.
+- **Below:** Children—masks engaging one fewer prime. Coarser: the subdivisions that contain the current one. The Whisper sits at the bottom of every chain.
+- **pos n/total:** Which tick of its own subdivision each channel is currently in, over how many ticks one traversal has, which is the channel's divisor. A single cosmic prime's tick is wider than the age of the universe, so its position is 0 and will remain 0 for some 10³⁰ years through the finest of them, Nandyte, and for some 10⁷⁶ through Notyte, as shown; combine cosmic primes and the ticks shrink accordingly. Once a Phi, a Psi or the cosmic primes make the fraction one of fifty-digit integers, both numbers go to three significant figures and a power of ten; the column is thirty-six cells wide and the universe is not.
+- **Remainder:** Planck times into the current tick on the engaged channel—the cycle channel when both are engaged, since that is the one that turns over within a human lifetime.
+
+### One Line, For Logs
+
+```bash
+$ loic-cli --line heptad,pentad
+[Whisper:0/1] [Pentad×Heptad:4/35] [14910371370088740558946097962660484558587321198353411]
+$ loic-cli --line                           # through an entropy-selected mask, ~25% collapse
+```
+
+Three fields, split on whitespace: the cosmic channel, the cycle channel, the remainder. A channel is its active primes joined with `×`, or `Whisper` when it has none, then `n/total`: the tick of that channel's own subdivision the instant falls in, over the ticks in one traversal. The remainder is the Planck times into the current tick on the engaged channel — the cycle channel when both are. Every number in full; a log has no column to fit. Without a mask the question is unframed, and the oracle answers it the way it always does.
+
+### Cosmological Queries
+
+```bash
+$ loic-cli --cosmic         # Planck times since the Big Bang
+$ loic-cli --terminal       # Planck times until heat death
+$ loic-cli --progress       # Your position in all of time, all 154 digits of it (~10^-93)
+$ loic-cli --whisper        # Planck times since The Whisper (the epoch)
+$ loic-cli --constants      # The cosmological constants, and what your kernel believes TAI is
+```
+
+### Forbidden Commands
+
+Certain operations are heretical. Attempting them exits with a sermon and status 1:
+
+```bash
+$ loic-cli --gregorian    # HERESY
+$ loic-cli --float        # HERESY
+$ loic-cli --timezone     # HERESY
+$ loic-cli --leap         # HERESY
+```
+
+The full list: `--gregorian`, `--unix`, `--float`, `--iso8601`, `--timezone`, `--leap`, `--round`, `--julian`.
+
+## Platform Requirements
+
+Requires Linux with `CLOCK_TAI` support (kernel 3.10+), and a kernel that has been told what TAI is. `CLOCK_TAI` is `CLOCK_REALTIME` plus an offset that only a time daemon with a leap-second table will set: chrony with `leapseclist /usr/share/zoneinfo/leap-seconds.list` or `leapsectz right/UTC`, or ntpd with a `leapfile`. systemd-timesyncd never does. On a machine where the offset is zero, every observing command refuses to run and says why; `--constants` and `--help` still work, so the reason can be read. The oracle cannot divine the current moment on operating systems that have forfeited their right to know what time it is, and it will not pretend to on ones that merely haven't asked.
+
+## License
+
+Dual-licensed under AGPL-3.0 and the Loic Public License. See the workspace root for the terms, and the workspace README for the theoretical substrate the license keeps citing.