PUNTAVIA AGENT
=============

This program records how long the computer is worked on and sends it to your
Puntavia server. It has no window: it runs quietly in the background and starts
with the computer.

Everything here is meant for the person the agent is installed for. The server
address and the enrollment key come from whoever keeps the records - the page
"Machines" in the Puntavia cabinet.


INSTALLING
----------

Windows:  unpack the archive anywhere (Downloads is fine) and run Setup.bat.
          It copies the program into %LOCALAPPDATA%\Programs\Timelog and sets
          everything up there; the unpacked folder can be deleted afterwards.

Linux:    ./install.sh   - run it as your normal user, NOT with sudo. The agent
          has to live inside your graphical session, otherwise it sees neither
          windows nor the screen.

macOS:    open the .dmg and drag Puntavia to Applications. See "Screen recording"
          below - without that permission screenshots come out empty.

If a file named preset.bat (Windows) or preset.sh (Linux) sits next to the
installer, the address and the key are already filled in and nothing is asked.

Deploying to many Windows machines at once (GPO, Intune): use Puntavia.msi -

    msiexec /i Puntavia.msi SERVER=https://your-server KEY=enrollment-key /qn

It installs in PROTECTED mode, the same way install-service.bat does: files go
to Program Files, the token and the queue to %ProgramData%\Timelog, and the
agent runs from a scheduled task (TimelogAgent) that a standard user cannot
stop or delete. The machine is registered under the computer name (add
NAME=... to choose another); a newer MSI installed on top upgrades in place.
Requires administrator rights - which is exactly why employees cannot undo it.


ONE ACCOUNT, ONE AGENT
----------------------

The agent belongs to a Windows or Linux account, not to the computer. On a PC
shared by several accounts each one needs its own installation, and each appears
in the reports under its own name (COMPUTER-ACCOUNT by default).

On Windows an administrator can prepare the other accounts without logging into
them: install-for-user.bat, run as administrator. Collection there starts at
that account's next logon - a program cannot be started inside somebody else's
session.


WHAT IS COLLECTED
-----------------

Every few seconds: whether there was a keypress or mouse movement, the name of
the program in front and the title of its window. Every few minutes: a scaled
down screenshot. All of it goes to the server whose address you entered, and is
visible in its reports.

Keystrokes are NOT intercepted. The agent knows only "how many seconds ago the
last input happened", never which keys were pressed. No passwords, no clipboard.

Password manager windows (1Password, KeePass, Bitwarden) and private browser
windows are skipped: no screenshot is taken and the title is replaced with
"[hidden]".

Nothing is collected while the screen is locked.


PAUSE
-----

macOS:    the menu bar icon - "Pause for 15 / 30 / 60 minutes".
Windows:  stop.bat, and start.bat to resume.
Linux:    systemctl --user stop timelog-agent

A pause set from the menu ends by itself, so it cannot be forgotten. While it
lasts the machine is shown on the server as paused.


CHECKING THAT IT WORKS
----------------------

Windows:  status.bat in the installed folder (%LOCALAPPDATA%\Programs\Timelog)
          - running, registered, anything stuck in the queue
Linux:    ./.venv/bin/python -m timelog status
macOS:    the menu bar icon - "Check permissions..."

Losing the network is harmless: unsent measurements pile up locally and go out
when the connection returns. Local screenshot files are deleted only after the
server has accepted them.


SCREEN RECORDING (macOS ONLY)
-----------------------------

macOS asks for permission to record the screen the first time the program runs.
Allow it, then CLOSE THE PROGRAM AND OPEN IT AGAIN: a permission granted to a
running process only takes effect after a restart.

Without it time is still counted, but screenshots come out empty - a bare
desktop with no windows - and window titles are not collected at all.

After updating to a new version macOS may stop recognising the program even
though the checkbox is still ticked. In that case quit Puntavia, run

    tccutil reset ScreenCapture cloud.golova.timelog

in the Terminal, start the program again and allow the request anew.


UPDATING
--------

Windows:  right-click Update.bat -> "Run as administrator". It works both
          for the regular install (Setup.bat) and for the protected one
          (Program Files, install-service.bat or the MSI), keeps the
          registration, the token and the history, and leaves the previous
          code next to the new one as timelog.old. It is enough to put
          Update.bat next to the downloaded archive - unpacking is optional.
Linux:    unpack over the old folder and re-run install.sh.

Setup.bat also updates a regular install, but it asks for the connect code
again. The server recognises the machine by its name and keeps the whole
history - only the token changes. Do not rename the machine in the cabinet
before updating: under a different name a SECOND machine is created and the
history stays with the first one.

macOS: install the new .dmg, then see "Screen recording" above.


REMOVING
--------

Windows:  uninstall.bat in the installed folder
Linux:    systemctl --user disable --now timelog-agent, then delete the folder
macOS:    uninstall.command from the .dmg

Removing the agent stops the collection on this machine. Data already sent stays
on the server - ask whoever keeps the records to remove the machine there too.
