SOL CLIPPY
==========

OVERVIEW
--------

Sol Clippy is a native Windows 98 controller for the original Office 2000
CLIPPIT.ACS character. It uses Microsoft Agent 2.0 without modifying Office,
AGENTCTL.DLL, or the character file.

Installed components:

  Controller: C:\SOLCHAT98\SOLCLIP.EXE
  Broker:     C:\SOLCHAT98\SOLCHAT.EXE
  Character:  C:\Program Files\Microsoft Office\Office\CLIPPIT.ACS

USER INTERACTION
----------------

Sol Clippy runs as a hidden host process. It does not have a permanent
controller or miniature chat window.

  Single-click Clippy       Play an allowlisted reaction animation
  Double-click Clippy       Open the transient Chat with Clippy dialog
  Click the tray icon       Open the transient chat dialog
  Right-click the tray icon Open Chat, Open Sol Chat 98, and Exit actions

Clippy remains visible when the full Sol Chat 98 window is minimized, hidden,
or represented only by its Windows taskbar item. Starting Sol Clippy by itself
starts SOLCHAT.EXE /broker invisibly when required.

NETWORK AND IPC ARCHITECTURE
----------------------------

Sol Clippy owns only Microsoft Agent user-interface behavior. Sol Chat 98 owns
networking, authenticated host-bridge access, guest context, and the persisted
sol98-win98 conversation. IPC uses atomic temporary-file replacement under:

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

Direct Clippy prompts are added to the same conversation used by the full Sol
Chat window. Completed full-window responses are also published to Clippy, so
either interface can drive the character.

While a direct request is pending, the balloon cycles through useful status
messages for local brokerage, host-bridge connection, context review, and
model thinking. Raw backend exceptions are not displayed in the balloon.

BALLOONS AND ANIMATIONS
-----------------------

The Agent balloon uses a fixed readable geometry with wrapping and automatic
pacing for longer replies. Successful replies are limited to 2,000 characters
for server-pushed balloon content.

Allowed animation names are:

  Alert, CheckingSomething, Congratulate, EmptyTrash, Explain,
  GestureDown, GestureLeft, GestureRight, GestureUp, GetArtsy,
  GetAttention, GetTechy, GetWizardy, Goodbye, Greeting, Hearing_1,
  Hide, Idle1_1, Idle2, Idle3, IdleHit, LookDown, LookDownLeft,
  LookDownRight, LookLeft, LookRight, LookUp, LookUpLeft, LookUpRight,
  Print, Processing, RestPose, Save, Searching, SendMail, Show,
  Thinking, Wave, and Writing.

Animation names are validated before any Agent method is invoked. Arbitrary
COM method names are never accepted from model or server output.

Microsoft Agent does not expose an independent Balloon.Text setter and appends
new thoughts to an already-visible balloon. The clear-text operation therefore
discards the active balloon request internally and immediately recreates the
same visible balloon with non-readable content. The resulting state retains
both Clippy and the native balloon while removing readable text.

SERVER-PUSH CONTROL
-------------------

The authenticated Linux host bridge exposes:

  POST /clippy/push          Set text and/or play an animation
  POST /clippy/clear         Clear readable text; retain the balloon
  GET  /clippy/state         Inspect queued and applied commands
  GET  /clippy/capabilities  Inspect animations and limits

Sol Chat relays queued commands through local IPC. Sol Clippy acknowledges a
server command only after the Microsoft Agent controller accepts its requested
operations. The host retains unacknowledged commands for retry.

LINUX HOST CONTROLS
-------------------

The host command-line control is:

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

The XFCE status-menu controller is:

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

Its menu provides balloon text with optional animation, all 39 documented
Office 2000 character animations, clear text, command queue/state, Windows 98
VM focus/start, refresh, and quit.
Green means online, amber means a command is pending, and red means the bridge
is unavailable.

The same status menu also starts and stops the host pseudo-seamless overlay
and can attach a full VirtualBox console to the running headless VM. The
overlay controller is:

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

Windows 98 runs at 1600 by 900 pixels. The shaped overlay preserves Clippy,
his balloon, guest windows, desktop icons, the Office toolbar at the top, and
the Windows taskbar at the bottom while removing only the teal guest desktop
background. Clippy remains interactive through forwarded host mouse input.

Using C:\SOLCHAT98\SEAMLESS.HTM as a blank #007c78 Active Desktop web page
covers the ordinary guest icons and produces the nearly complete seamless
effect without hiding Clippy, guest windows, the top Office toolbar, or the
bottom taskbar.

CURRENT BUILD
-------------

The current verified combined deployment image is:

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

SOLCLIP.EXE is a native 32-bit GUI application built for Windows subsystem
version 4.0. The v20 clear-text behavior, subsequent readable-text restore,
and new `Congratulate` animation command 19 were verified against the real
Office 2000 Clippit character in Windows 98. The host capabilities endpoint
and XFCE dropdown expose all 39 documented Office 2000 animation names.

The private complete installer is located at:

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

It includes a Linux host installer and guest/SOL98-GUEST-INSTALL.iso. The
archive contains the app-specific bridge key matched to SOLCHAT.EXE and must
be kept private; licensed Office and Microsoft Agent assets are not included.
