TuoniNote
=========

Notes attach to commands through the server's v2 command-notes endpoints.
Create or retrieve them through :class:`tuoni.TuoniCommand` using
``add_note()``, ``load_note()``, and ``load_notes()``. Callers with agent and
command identifiers can use :class:`tuoni.TuoniC2` methods
``add_command_note()``, ``load_command_note()``, and ``load_command_notes()``.

With an existing command object::

    note = command.add_note("review", "Checked the command output.")
    note.content = "Reviewed and complete."
    note.update()
    note.reload()
    note.archive()
    archived = command.load_note(note.note_id)

Set the note's attributes and call ``update()`` to save both ``label`` and
``content``. Mutation methods refresh the object from the server response and
return ``None``. Archiving is permanent and can be repeated. Archived notes
remain readable and retain their identifier, but cannot be edited or restored.

Collection methods return one page as a list, oldest first. Defaults are
``page=0``, ``pageSize=100``, and ``include_archived=False``. The maximum page
size is 1,000; ``label`` is an optional exact, case-sensitive filter. Increment
``page`` to fetch more results. Pagination metadata is not returned.

The server requires nonblank labels and content. Labels are trimmed and limited
to 128 characters; content is limited to 2,000 characters and retains whitespace
and line breaks. Reads require ``VIEW_RESOURCES`` and writes require
``SEND_COMMANDS``. Editing or archiving requires the creator's username, or
``MANAGE_USERS`` to override ownership in addition to ``SEND_COMMANDS``.

Server errors propagate through the existing request exceptions: 400 for invalid
input, 403 for permissions or ownership, 404 for an unavailable command or
mismatched note, and 409 for archived-note updates or concurrent changes.

Use :meth:`tuoni.TuoniWebSocket.on_note` for change notifications. Callbacks
receive raw event dictionaries; they do not update existing note objects.

.. autoclass:: tuoni.TuoniNote
   :members:
   :undoc-members: