docs+fix: update documentation and API responses for post-0.3.0 changes

docs/api/rest.rst

@@ -24,18 +24,54 @@ Server Capabilities
    .. code-block:: json
 
       {
-        "api_version": "1.0.0",
-        "gateway_version": "0.1.0",
+        "name": "ROS 2 Medkit Gateway",
+        "version": "0.3.0",
+        "api_base": "/api/v1",
         "endpoints": [
-          {"path": "/areas", "supported_methods": ["GET"]},
-          {"path": "/components", "supported_methods": ["GET"]},
-          {"path": "/apps", "supported_methods": ["GET"]}
-        ]
+          "GET /api/v1/health",
+          "GET /api/v1/areas",
+          "GET /api/v1/components",
+          "GET /api/v1/apps",
+          "GET /api/v1/functions",
+          "GET /api/v1/faults",
+          "..."
+        ],
+        "capabilities": {
+          "discovery": true,
+          "data_access": true,
+          "operations": true,
+          "async_actions": true,
+          "configurations": true,
+          "faults": true,
+          "logs": true,
+          "bulk_data": true,
+          "cyclic_subscriptions": true,
+          "updates": false,
+          "authentication": false,
+          "tls": false
+        }
       }
 
 ``GET /api/v1/version-info``
    Get gateway version and status information.
 
+   **Example Response:**
+
+   .. code-block:: json
+
+      {
+        "items": [
+          {
+            "version": "1.0.0",
+            "base_uri": "/api/v1",
+            "vendor_info": {
+              "version": "0.3.0",
+              "name": "ros2_medkit"
+            }
+          }
+        ]
+      }
+
 ``GET /api/v1/health``
    Health check endpoint. Returns HTTP 200 if gateway is operational.
 
@@ -57,7 +93,7 @@ Areas
           {
             "id": "powertrain",
             "name": "Powertrain",
-            "self": "/api/v1/areas/powertrain"
+            "href": "/api/v1/areas/powertrain"
           }
         ]
       }
@@ -71,6 +107,13 @@ Areas
 ``GET /api/v1/areas/{area_id}/components``
    List components in a specific area.
 
+   .. note::
+
+      **ros2_medkit extension:** Areas support resource collections beyond the SOVD spec,
+      which only defines them for apps and components. Areas provide ``/data``, ``/operations``,
+      ``/configurations``, ``/faults``, ``/logs`` (namespace prefix aggregation), and read-only
+      ``/bulk-data``. See :ref:`sovd-compliance` for details.
+
 Components
 ~~~~~~~~~~
 
@@ -86,9 +129,7 @@ Components
           {
             "id": "temp_sensor",
             "name": "temp_sensor",
-            "self": "/api/v1/components/temp_sensor",
-            "area": "powertrain",
-            "resource_collections": ["data", "operations", "configurations", "faults"]
+            "href": "/api/v1/components/temp_sensor"
           }
         ]
       }
@@ -128,6 +169,13 @@ Functions
 ``GET /api/v1/functions/{function_id}/hosts``
    List apps that host this function.
 
+   .. note::
+
+      **ros2_medkit extension:** Functions support resource collections beyond the SOVD spec.
+      ``/data`` and ``/operations`` aggregate from hosted apps (per SOVD). Additionally,
+      ``/configurations``, ``/faults``, ``/logs`` aggregate from hosts, and read-only
+      ``/bulk-data`` is available. See :ref:`sovd-compliance` for details.
+
 Data Endpoints
 --------------
 
@@ -477,6 +525,16 @@ Query and manage faults.
    - **204:** Fault cleared
    - **404:** Fault not found
 
+``DELETE /api/v1/components/{id}/faults``
+   Clear all faults for an entity.
+
+   Accepts the optional ``?status=`` query parameter (same values as ``GET /faults``).
+   Without it, clears pending and confirmed faults.
+
+   - **204:** Faults cleared (or none to clear)
+   - **400:** Invalid status parameter
+   - **503:** Fault manager unavailable
+
 ``DELETE /api/v1/faults``
    Clear all faults across the system *(ros2_medkit extension, not SOVD)*.
 
@@ -491,7 +549,8 @@ Logs Endpoints
 --------------
 
 Query and configure the /rosout ring buffer for an entity. Supported entity types:
-**components** and **apps**.
+**areas** (namespace prefix match), **components** (namespace prefix match), **apps** (exact FQN match),
+and **functions** (aggregated from hosted apps).
 
 .. note::
 
@@ -595,10 +654,10 @@ The ``context.function``, ``context.file``, and ``context.line`` fields are omit
         "max_entries": 500
       }
 
-   ``severity_filter`` — minimum severity to return in query results (``debug`` | ``info`` | ``warning`` |
+   ``severity_filter`` - minimum severity to return in query results (``debug`` | ``info`` | ``warning`` |
    ``error`` | ``fatal``). Entries below this level are excluded from queries. Default: ``debug``.
 
-   ``max_entries`` — maximum number of entries returned per query. Must be between 1 and 10,000
+   ``max_entries`` - maximum number of entries returned per query. Must be between 1 and 10,000
    (inclusive). Default: ``100``.
 
    **Response 204:** No content.
@@ -1235,33 +1294,97 @@ Topic and parameter paths containing ``/`` must be URL-encoded:
    * - ``/chassis/brakes/command``
      - ``chassis%2Fbrakes%2Fcommand``
 
+.. _sovd-compliance:
+
 SOVD Compliance
 ---------------
 
-The gateway implements a subset of the SOVD (Service-Oriented Vehicle Diagnostics) specification:
+The gateway implements a **pragmatic subset** of the SOVD (Service-Oriented Vehicle
+Diagnostics) standard. We follow SOVD where it matters for interoperability -
+endpoint contracts, data model, entity hierarchy - but extend it where ROS 2
+use cases benefit.
 
-**SOVD-Compliant Endpoints:**
+**SOVD-Aligned Capabilities:**
 
 - Discovery (``/areas``, ``/components``, ``/apps``, ``/functions``)
-- Data access (``/data``)
-- Operations (``/operations``, ``/executions``)
+- Data access (``/data``) with topic sampling and JSON serialization
+- Operations (``/operations``, ``/executions``) with async action support
 - Configurations (``/configurations``)
 - Faults (``/faults``) with ``environment_data`` and SOVD status object
-- Bulk Data (``/bulk-data``) for binary data downloads (rosbags, logs)
+- Logs (``/logs``) with severity filtering and per-entity configuration
+- Bulk Data (``/bulk-data``) with custom categories and rosbag downloads
 - Software Updates (``/updates``) with async prepare/execute lifecycle
-- Cyclic Subscriptions (``/cyclic-subscriptions``) with SSE-based periodic data delivery
+- Cyclic Subscriptions (``/cyclic-subscriptions``) with SSE-based delivery
+
+**Pragmatic Extensions:**
 
-**ros2_medkit Extensions:**
+The SOVD spec defines resource collections only for apps and components. ros2_medkit
+extends this to areas and functions where aggregation makes practical sense:
 
-- ``/health`` - Health check endpoint
+.. list-table:: Resource Collection Support Matrix
+   :header-rows: 1
+   :widths: 20 16 16 16 16 16
+
+   * - Resource
+     - Areas
+     - Components
+     - Apps
+     - Functions
+     - SOVD Spec
+   * - data
+     - aggregated
+     - yes
+     - yes
+     - aggregated
+     - apps, components
+   * - operations
+     - aggregated
+     - yes
+     - yes
+     - aggregated
+     - apps, components
+   * - configurations
+     - aggregated
+     - yes
+     - yes
+     - aggregated
+     - apps, components
+   * - faults
+     - aggregated
+     - yes
+     - yes
+     - aggregated
+     - apps, components
+   * - logs
+     - prefix match
+     - prefix match
+     - exact match
+     - from hosts
+     - apps, components
+   * - bulk-data
+     - read-only
+     - full CRUD
+     - full CRUD
+     - read-only
+     - apps, components
+   * - cyclic-subscriptions
+     - \-
+     - yes
+     - yes
+     - \-
+     - apps, components
+
+Other extensions beyond SOVD:
+
+- Vendor extension fields using ``x-medkit`` prefix (per SOVD extension mechanism)
+- ``DELETE /faults`` - Clear all faults globally
+- ``GET /faults/stream`` - SSE real-time fault notifications
+- ``/health`` - Health check with discovery pipeline diagnostics
 - ``/version-info`` - Gateway version information
-- ``/manifest/status`` - Manifest discovery status
-- SSE fault streaming - Real-time fault notifications
-- ``x-medkit`` extension fields in responses
 
 See Also
---------
+~~~~~~~~
 
+- :doc:`/config/discovery-options` for merge pipeline configuration
 - :doc:`/tutorials/authentication` - Configure authentication
 - :doc:`/config/server` - Server configuration options
-- `Postman Collection <https://github.com/selfpatch/ros2_medkit/tree/main/postman>`_ - Interactive API testing