SOL CHAT 98
===========

OVERVIEW
--------

Sol Chat 98 is a native Win32 application for Windows 98. It does not use
HTML, MSHTML, .NET, or a browser engine. Its networking dependency is the
WinInet component included with Windows 98.

The installed application is:

  C:\SOLCHAT98\SOLCHAT.EXE

The Windows 98 client connects to the authenticated host compatibility bridge
at http://10.0.2.2:8891. The bridge forwards chat turns to:

  https://sol.system42.one/api/chat

The bridge is required because Windows 98 cannot negotiate the public API's
modern HTTPS connection directly. The guest never stores public API
credentials and must not be exposed directly to the modern endpoint.

CHAT, HISTORY, AND CONTEXT
--------------------------

Type a message and click Send. Work is performed off the user-interface
thread so the native window remains responsive while Sol generates a reply.
The bridge buffers the upstream event stream and returns a CP1252 response
with Content-Length for reliable Windows 98 WinInet handling.

Replies are displayed in a native Windows Rich Edit control. Common Markdown
formatting is rendered as Windows text formatting without an HTML engine.
You, Sol, and System labels use distinct transcript styles.

The persisted sol98-win98 conversation is loaded and displayed at startup.
Show Context reveals the stored system prompt, host bridge context, and
current guest state. Hide Context returns to the conversation-only view.
Showing or hiding context is read-only and does not create or remove history.

Extended guest diagnostics are not added to every ordinary turn. The bridge
exposes them to the model through the optional read-only
get_guest_diagnostics function. It can provide a process tree, memory and
resource state, display information, and other guest diagnostics when useful.

SOL CLIPPY BROKERAGE
--------------------

Sol Chat 98 is the sole guest networking and persisted-history broker for the
standalone Sol Clippy controller. Its local IPC files are:

  C:\SOLCHAT98\IPC\CLIPPY.REQ
  C:\SOLCHAT98\IPC\CLIPPY.RES
  C:\SOLCHAT98\IPC\STATUS.TXT
  C:\SOLCHAT98\IPC\PUSH.ACK

SOLCLIP.EXE uses the installed Office 2000 CLIPPIT.ACS character through
Microsoft Agent 2.0. It does not call the network directly. When started by
itself, Sol Clippy starts SOLCHAT.EXE /broker invisibly if a broker is not
already running.

Sol Clippy displays a local startup thought balloon before any network
request. If that balloon appears, the Agent character and balloon path are
working independently of the host bridge and Sol API.

Sol Clippy has no permanent controller window. Single-click the character for
an animation reaction. Double-click the character to open a transient chat
dialog. Its Windows notification-area menu can also open the transient chat,
restore the full Sol Chat window, or exit Sol Clippy. The character remains
visible when Sol Chat is minimized or hidden.

SERVER-SIDE CLIPPY CONTROL
--------------------------

Sol Chat polls the authenticated host bridge for durable server-pushed Clippy
commands. The host endpoints are:

  POST /clippy/push
  POST /clippy/clear
  GET  /clippy/state
  GET  /clippy/capabilities

The private guest relay also uses GET /clippy/next and POST /clippy/ack.
Commands remain queued in host SQLite storage until the Microsoft Agent
controller applies them and writes an acknowledgement through the local
broker.

/clippy/push accepts balloon text up to 2,000 characters and an optional
allowlisted animation. The capabilities endpoint and XFCE menu expose all 39
documented Office 2000 character animations. /clippy/clear removes readable
text while leaving the native balloon visible. Model or server output never
selects arbitrary Agent methods.

HOST CONTROL SURFACES
---------------------

On the Linux host, authenticated controls are available through:

  /home/david/.local/lib/sol98/sol98_clippy_control.py
  /home/david/.local/lib/sol98/sol98_clippy_indicator.py

The first is a command-line client. The second is a persistent XFCE status
icon with online, pending, and offline states. Its menu provides balloon text,
animation, clear-text, command-state, and Windows 98 VM focus controls. The
status icon autostarts through:

  /home/david/.config/autostart/sol98-clippy-controls.desktop

Both host surfaces read the authenticated bridge token from the environment
or /home/david/.config/sol98-chat-bridge.env. The token is not placed in
desktop entries or command-line arguments.

HEADLESS SEAMLESS HOST MODE
---------------------------

The Windows 98 VM normally runs headlessly at 1600 by 900 pixels. The host
pseudo-seamless controller is:

  /home/david/.local/lib/sol98/sol98_seamless.py

Its shaped X11 surface fits the XFCE work area below the top panel, removes
the teal guest desktop background, keeps Windows desktop icons among the host
icons, retains the Office toolbar at the top, and places the Windows taskbar
at the bottom. Mouse and keyboard input are forwarded into the guest.

This is a single normally stacked host overlay, not Oracle Guest Additions
Seamless Mode and not one host task entry per guest window. The XFCE Sol
Clippy status menu can start or stop the overlay and attach a full VirtualBox
console to the running headless VM for maintenance.

Host integration files are:

  /home/david/.local/share/applications/sol98-seamless.desktop
  /home/david/.config/autostart/sol98-seamless.desktop
  /home/david/.cache/sol98-seamless.pid
  /home/david/.cache/sol98-seamless.log

For the most complete visual integration, add
C:\SOLCHAT98\SEAMLESS.HTM as an Active Desktop web page. Its blank #007c78
page covers ordinary guest desktop icons with the same color removed by the
host chroma key. Guest windows, Clippy, the Office toolbar, and the Windows
taskbar remain visible and interactive.

WINDOWS MENUS AND SHORTCUTS
---------------------------

The full Sol Chat window has File, Conversation, View, and Help menus. Help ->
About Sol Chat 98 displays build and integration information. Closing the
window hides it and leaves the broker running. File -> Exit terminates the
broker.

Sol Chat repairs these Windows shortcuts whenever it starts:

  Start Menu\Programs\Sol Chat 98\Sol Chat 98
  Start Menu\Programs\Sol Chat 98\Sol Clippy
  Start Menu\Programs\Sol Chat 98\Read Me
  Desktop\Sol Chat 98
  Desktop\Sol Clippy

INSTALLATION AND CURRENT BUILD
------------------------------

Run D:\INSTALL.BAT from Windows 98 to install the combined package into
C:\SOLCHAT98. The current verified deployment image on the Linux host is:

  /home/david/sol98-complete-installer-2026-07-15/guest/SOL98-GUEST-INSTALL.iso

The verified guest executables are C:\SOLCHAT98\SOLCHAT.EXE and
C:\SOLCHAT98\SOLCLIP.EXE. Both are native 32-bit GUI applications built for
Windows subsystem version 4.0.

The complete private host-and-guest installer is:

  /home/david/sol98-complete-installer-2026-07-15.zip

After extraction, run INSTALL-HOST.sh on Linux and attach
guest/SOL98-GUEST-INSTALL.iso to Windows 98, then run D:\INSTALL.BAT. The ZIP
contains the guest-matching local bridge key and must be kept private. It does
not contain VM disks, Office, Microsoft Agent, or CLIPPIT.ACS.
