X-Git-Url: https://git.giacomolli.uk/onechat/blobdiff_plain/2501e78d10204fac2298db0dee84b3dce379e09b..59e1537e1969f7c109084497287d729edbedba04:/README.rst

diff --git a/README.rst b/README.rst
index 9fbf6dd..18af256 100644
--- a/README.rst
+++ b/README.rst
@@ -73,7 +73,10 @@ Start the daemon, and then the client in another terminal:
 .. code:: console
 
    onechat daemon
-   onechat chat
+   onechat
+
+``onechat`` with no command is the same as ``onechat chat``. ``onechat
+help`` lists the commands.
 
 The daemon owns the root agent in ``agent/`` in the data directory and
 listens on the Unix socket ``onechat.sock`` there. In the client, each
@@ -127,7 +130,9 @@ prompt cache key comes from it.
 ``workdir`` is an absolute path, and its default is the home directory.
 ``agent/instructions.md`` holds the user's instructions: who they are,
 how their files are organized, and how they want work done. The prompt
-ends with them, and a change applies at the next call.
+ends with them, and a change applies at the next call. The agent can
+propose a change to the file, and it makes the change only after the
+user agrees.
 
 **************
  User service
@@ -146,7 +151,7 @@ does not collect the package while the service uses it:
 .. code:: console
 
    nix build --out-link result-service
-   systemctl --user link --force "$(realpath result-service/share/systemd/user/onechat.service)"
+   systemctl --user link --force "$PWD/result-service/share/systemd/user/onechat.service"
    systemctl --user edit onechat.service
 
 In the editor, set the data directory with this drop-in. Replace
@@ -192,9 +197,20 @@ the service:
    systemctl --user daemon-reload
    systemctl --user enable --now onechat.service
    systemctl --user status onechat.service
-   ONECHAT_DIR=DATA_DIR ./result-service/bin/onechat chat
+   ONECHAT_DIR=DATA_DIR ./result-service/bin/onechat
    journalctl --user -u onechat.service -f
 
+After a pull, update the package and unit with:
+
+.. code:: console
+
+   git pull
+   bin/service-update
+
+The script builds with the same ``result-service`` link, reloads the
+user manager, and restarts the service only if it is active. The unit
+link follows ``result-service``, so no new link is needed.
+
 The service starts with the user manager at login, not at boot without a
 login. To stop it, or also remove its start at login:
 
@@ -203,6 +219,34 @@ login. To stop it, or also remove its start at login:
    systemctl --user stop onechat.service
    systemctl --user disable onechat.service
 
+************
+ Daemon log
+************
+
+The daemon writes short events with the part prefix and ordered
+``key=value`` attributes. An error cause comes last. Normal events use
+info, failures that can be retried or lose nothing use warning, and
+failures that lose data or stop work use error.
+
+With ``JOURNAL_STREAM`` set, each line carries a syslog priority without
+a time stamp or level word. The user journal can show only warnings and
+errors:
+
+.. code:: console
+
+   journalctl --user -u onechat -p warning
+
+The summary warning names its node. A schedule run has ``late`` only
+when it ran late:
+
+.. code:: text
+
+   <4>onechat: summary failed level=0 index=0: fake failure
+   <6>onechat: schedule ran id=1
+   <6>onechat: schedule ran id=2 late=1m0s
+
+Outside the journal, each line starts with the time stamp and level.
+
 **********
  Telegram
 **********
@@ -343,12 +387,56 @@ Each batch of a group goes to the chat, also with no turn, and the
 memory tree summarizes it with model calls, which use the quota.
 
 When the session holds a linked device, the daemon connects at its
-start, and after a network failure it connects again by itself. When a
-disconnection lasts 10 minutes, all clients get one notice, and one more
-when the connection comes back. When WhatsApp ends the connection for
-good, for example because another program uses the same session, all
-clients get a notice at once. When the user removes the device in the
-phone, the daemon deletes the session and tells all clients one time.
+start. If the first connection fails, it tries again after 2 seconds,
+then doubles the wait up to 5 minutes. The inbox and commands stay
+active during each wait. An unlink or a logout stops these retries.
+After a network failure of an open connection, the library connects
+again by itself. When a disconnection lasts 10 minutes, all clients get
+one notice, and one more when the connection comes back. When WhatsApp
+ends the connection for good, for example because another program uses
+the same session, all clients get a notice at once. When the user
+removes the device in the phone, the daemon deletes the session and
+tells all clients one time.
+
+*************************
+ Import WhatsApp history
+*************************
+
+Stop the daemon and finish all subagents before an import. Export each
+chat from WhatsApp as a ZIP with ``_chat.txt``. Keep the chat name in
+the ZIP name, such as ``WhatsApp Chat - Example.zip``. Read the plan
+first:
+
+.. code:: console
+
+   onechat import -n CHAT.zip OTHER.zip
+   onechat import CHAT.zip OTHER.zip
+
+``-n`` makes no model call and prints the chats, chat-day batches, local
+dates, cutoff, text bytes, merged message count, and estimated calls.
+The import keeps multiline text, system lines, and omitted-media
+markers. It maps the session's profile name to ``You``. Without that
+name, it keeps the senders as written and says so in the plan. An exact,
+unambiguous local contact or batch name supplies the chat ID when known.
+No network lookup is made.
+
+Each chat and local day becomes one work message marked ``(imported)``.
+Only messages before the first message of the earliest live WhatsApp
+batch enter the import. Live times have minute precision, so the cutoff
+excludes that whole minute. A chat-day already imported is skipped.
+Overlapping chat-days in the supplied ZIPs are refused. Review the
+exports before import: their text goes to the model as chat history.
+
+The import merges the full log in date order and builds its tree with
+real compactor calls, the agent prompt, and the agent cache key. It uses
+a limit of 1,500 calls and the probe's 15-quota-point limit, and prints
+the same usage report. Its estimate is about 1.3 calls per merged
+message, not a cost guarantee. A stopped or failed run leaves the agent
+unchanged. A new run starts over. Success keeps the other agent files
+and renames the old directory to ``agent-backup-TIMESTAMP`` before it
+installs the new one. Keep the backup until the new memory is checked,
+then start the daemon. Message IDs change to their positions in the
+merged log.
 
 ***********
  Schedules
@@ -439,6 +527,9 @@ Build and run:
    nix build
    ./result/bin/onechat
 
+``onechat version`` prints ``yyyy-mm-dd-gitshort`` for a Nix build, adds
+``-dirty`` for a dirty tree, and prints ``dev`` for a direct Go build.
+
 Format and check all files:
 
 .. code:: console