X-Git-Url: https://git.giacomolli.uk/onechat/blobdiff_plain/80fa33c0fd65e4110f88f0cab9b19ca26c27d1f6..e0ab6220b6fd35f7e92a04e4bf149940185713ab:/README.rst

diff --git a/README.rst b/README.rst
index ce4696e..04dcafb 100644
--- a/README.rst
+++ b/README.rst
@@ -5,6 +5,85 @@
 OneChat is a Go program. It prints its name. It is in early development.
 Linux is supported.
 
+****************
+ Data directory
+****************
+
+OneChat keeps its data and its token file in one directory. It uses the
+first of these:
+
+#. ``ONECHAT_DIR``, when it is set.
+#. ``$XDG_DATA_HOME/onechat``, when ``XDG_DATA_HOME`` is an absolute
+   path. A relative value is ignored.
+#. ``~/.local/share/onechat``. With no home directory, OneChat exits
+   with an error.
+
+OneChat creates the directory with mode 0700.
+
+***************
+ Configuration
+***************
+
+``config.json`` in the data directory holds the settings. OneChat does
+not create it. A missing file or field takes the default, and an unknown
+field is an error.
+
+.. code:: json
+
+   {
+     "endpoint": "chatgpt",
+     "compactor": {"model": "gpt-6.1-sol", "effort": "high"}
+   }
+
+``endpoint``
+   ``chatgpt`` (the default) sends model calls to the ChatGPT backend
+   with the subscription login. ``api`` sends them to the OpenAI API
+   with the key in ``OPENAI_API_KEY``, which must then be set. With
+   ``chatgpt``, OneChat ignores ``OPENAI_API_KEY``.
+
+``compactor``
+   The model and the reasoning effort of the summaries. The defaults are
+   ``gpt-6.1-sol`` and ``high``.
+
+*******
+ Login
+*******
+
+The ``chatgpt`` endpoint needs a login with a ChatGPT account:
+
+.. code:: console
+
+   onechat login
+
+The command shows a link and a code. Open the link on any device, enter
+the code, and approve the login. Device code login must be allowed in
+the ChatGPT security settings. OneChat writes the tokens to
+``auth.json`` in the data directory, with mode 0600, and refreshes them
+before they expire. The file belongs to OneChat only. Do not share it
+with the Codex CLI, because each program rotates the refresh token and
+logs the other out.
+
+*******
+ Probe
+*******
+
+``onechat probe LOG COUNT [BUILDS]`` measures the compactor on a log. It
+appends the first COUNT messages of LOG, one JSON object ``{"kind",
+"text"}`` on each line, to a new chat in ``probe/`` in the data
+directory, and builds its tree with real model calls. The calls use the
+quota of the account. The run stops at the first failed call, after 660
+calls, or when the used percent of a quota window grows by more than 15
+points. At the end it reports the calls per message, the cached share of
+the input tokens, the retries, the line sizes, and the quota at the
+first and the last call. BUILDS, from 1 to 8, limits the model calls at
+once in the run.
+
+A test writes a generated log of readable made-up messages:
+
+.. code:: console
+
+   ONECHAT_PROBE_LOG=probe.jsonl go test -run TestProbeLogHasTheSyntheticMix
+
 *************
  Development
 *************
@@ -22,6 +101,10 @@ Or enter it directly:
 
    nix develop
 
+The shell sets ``ONECHAT_DIR`` to ``.devenv/onechat`` in the checkout,
+unless it is already set. Development data goes there, and Git ignores
+``.devenv``.
+
 Build and run:
 
 .. code:: console