Agent Maintenance Guide
=======================

This document is written for Kimi and other AI agents that may need to modify,
update, or extend the Evercycle API documentation project.

Project Layout
--------------

::

    /SSD2/sites/Evercycle-Docs/
    ├── docs/
    │   ├── source/              # Sphinx RST source files
    │   │   ├── index.rst        # Main toctree
    │   │   ├── overview.rst
    │   │   ├── architecture.rst
    │   │   ├── api_endpoints.rst
    │   │   ├── operational_flows.rst
    │   │   ├── modules.rst      # Toctree for module docs
    │   │   ├── module_*.rst     # One per Python module
    │   │   ├── examples.rst
    │   │   ├── agents.rst       # This file
    │   │   ├── _static/         # Empty; for CSS/images
    │   │   └── _templates/      # Empty; for HTML overrides
    │   ├── build/               # Generated HTML (do not edit by hand)
    │   └── Makefile             # Auto-generated by sphinx-quickstart
    ├── examples/                # Placeholder for extra code examples
    ├── api_specs/               # Placeholder for OpenAPI/JSON specs
    └── requirements.txt         # Python packages needed to build docs

How to Update the Documentation
--------------------------------

1. **Edit RST files** in ``docs/source/``.
2. **Add new pages** to the appropriate ``toctree`` (e.g., ``index.rst`` or ``modules.rst``).
3. **Re-build HTML** by running:

   .. code-block:: bash

      cd /SSD2/sites/Evercycle-Docs
      pip install -r requirements.txt
      sphinx-build -b html docs/source docs/build/html

4. **Verify** the output in ``docs/build/html/index.html``.
5. **Reload Caddy** if site paths changed (not needed for content-only updates).

Adding a New Python Module
--------------------------

1. Create ``docs/source/module_<name>.rst`` following the style of existing
   module files.
2. Document every public class, method, and function.
3. Add the new file to ``docs/source/modules.rst`` under its ``toctree``.
4. Re-build and verify.

Adding a New API Endpoint
-------------------------

1. Update ``docs/source/api_endpoints.rst``:
   * Add the endpoint to the Flask proxy table.
   * Add the backend endpoint description under the correct heading.
2. Update ``docs/source/operational_flows.rst`` if the new endpoint has a
   unique flow (e.g., special path patching or body merging).
3. Add a curl example to ``docs/source/examples.rst``.
4. Re-build.

Adding Code Examples
--------------------

1. For simple one-liners, add them directly to ``docs/source/examples.rst``.
2. For multi-file or runnable scripts, place them in ``examples/`` and link
   to them using ``:download:`` or a literal block with a file path note.

Styling Conventions
-------------------

* Use ``.. http:get::`` / ``.. http:post::`` etc. for REST endpoints.
* Use ``.. py:function::``, ``.. py:class::``, ``.. py:method::`` for Python APIs.
* Use ``.. code-block:: json`` or ``.. code-block:: bash`` for all code.
* Keep line lengths reasonable (≤120 characters) for readability in terminals.

Do Not Edit by Hand
-------------------

* ``docs/build/html/`` — this is auto-generated. Any hand edits will be lost
  on the next ``sphinx-build``.

Caddy Configuration
-------------------

The documentation site is served at ``https://evercycle-docs.veraetime.net``
from ``/SSD2/sites/Evercycle-Docs/docs/build/html``.

Config file: ``/etc/caddy/sites/evercycle-docs.veraetime.net.caddy``

If the build output directory changes, update the ``root`` directive in that
Caddyfile and run ``caddy reload``.