Update docs

b-Tomas · b-Tomas · commit c43a839aa4e4 · 2026-01-24T19:23:37.000-03:00
diff --git a/docs/contents/specification/annotation-sync.md b/docs/contents/specification/annotation-sync.md
@@ -5,7 +5,7 @@ description: "API specification for synchronizing annotations between external s
 
 > **Note:** Annotation synchronization is currently an experimental feature with partial support in the InOrbit platform.
 
-The annotation synchronization framework enables connectors to synchronize waypoint annotations between external systems and InOrbit's Config API.
+The annotation synchronization feature enables connectors to synchronize waypoint annotations between external systems and InOrbit's Config API.
 
 For Config API models and client, see [Config API](config-api).
 
@@ -30,10 +30,6 @@ config = AnnotationSyncConfig(
 )
 ```
 
-**Note**: `frame_id` is not configured. The framework automatically starts sync for each unique `frame_id` as robot poses are published.
-
-**Note**: The ownership signature property is `syncOrigin`, with value set to `ConnectorConfig.connector_type`. The manager automatically injects this.
-
 ## Interfaces
 
 ### ExternalAnnotationProvider[TExternalPosition]
@@ -90,7 +86,7 @@ manager = AnnotationSyncManager(
 )
 ```
 
-**Note**: The framework creates manager instances automatically when new `frame_id`s are detected.
+The connector creates manager instances automatically when new `frame_id`s are detected.
 
 ### Methods
 
diff --git a/docs/contents/usage/annotation-sync.md b/docs/contents/usage/annotation-sync.md
@@ -9,110 +9,57 @@ This guide explains how to enable and configure annotation synchronization betwe
 
 ## Terminology
 
-- **Annotation**: An InOrbit `SpatialAnnotation` object. Currently, we support waypoint annotations (`spec.type == "waypoint"`).
+- **Annotation**: An InOrbit `SpatialAnnotation` object. Currently, only waypoint annotations are supported.
 - **Position**: A waypoint/location in the external system.
-- **External system**: Fleet manager or robot software the connector integrates with.
+- **External system**: The software the connector interacts with (fleet manager, robot software).
 
 ## Overview
 
-Annotation synchronization keeps positions/waypoints in sync between:
-- Your **external system** (e.g., MiR Fleet, Bluebotics, robot software)
-- **InOrbit's Config API** (SpatialAnnotation objects)
+Annotation synchronization keeps positions/waypoints in sync between your external system and the InOrbit platform.
 
 ## Sync Modes
 
-| Mode | Direction | Description |
-|------|-----------|-------------|
+| Mode                  | Direction          | Description                        |
+| --------------------- | ------------------ | ---------------------------------- |
 | `external_to_inorbit` | External → InOrbit | External system is source of truth |
-| `inorbit_to_external` | InOrbit → External | InOrbit is source of truth |
+| `inorbit_to_external` | InOrbit → External | InOrbit is source of truth         |
 
 ## Configuration
 
-Annotation sync is configured at the `ConnectorConfig` level:
+Annotation synchronization is configured via the connector YAML configuration file:
 
 ```yaml
-# connector-config.yaml
-
-api_key: ${INORBIT_API_KEY}
-rest_api_url: ${INORBIT_REST_API_URL}
-account_id: ${INORBIT_ACCOUNT_ID}
-connector_type: my_connector
-
-# Annotation synchronization (framework-level feature)
+...
+# Annotation synchronization
 annotation_sync:
   enabled: true
   mode: external_to_inorbit
   sync_interval_seconds: 300
 
   # InOrbit scope settings
-  location_id: "facility-location-id"
-
-# Connector-specific settings
-connector_config:
-  host: 192.168.1.50
+  location_id: "location-tag-id"
+...
 ```
 
-**Note**: `frame_id` is not configured statically. The framework automatically starts
-sync for each frame_id as robot poses are published, supporting fleet connectors with
-robots on multiple maps.
-
-`rest_api_url` points to the InOrbit REST API used by the Config API. It defaults to
-the edge SDK's REST API base URL and can be overridden with `INORBIT_REST_API_URL`.
+The connector automatically starts annotation synchronization for each frame_id as robot poses are published, enabling fleet integrations with
+robots operating on multiple maps.
 
 ### Configuration Fields
 
-| Field | Required | Default | Description |
-|-------|----------|---------|-------------|
-| `enabled` | No | `false` | Enable annotation sync |
-| `mode` | No | `external_to_inorbit` | Sync mode |
-| `sync_interval_seconds` | No | `300` | Interval between syncs |
-| `location_id` | Yes* | - | Location tag ID for scoping |
-
-*Required when `enabled` is `true`. `account_id` must also be set in `ConnectorConfig`.
-
-**Dynamic frame_id**: The framework automatically detects new frame_ids when robot poses
-are published and starts sync for each unique frame. This supports fleet connectors
-where robots operate on multiple maps.
-
-## Choosing the Right Mode
-
-### External to InOrbit (`external_to_inorbit`)
-
-Use when your external system is the source of truth for positions.
-
-**Behavior**:
-- Fetches all positions from external system
-- Creates/updates matching waypoint annotations in InOrbit
-- Marks stale annotations for deletion
-
-**Best for**:
-- Operators who manage waypoints in the external system's UI
-- Systems where the external system has authoritative position data
-
-### InOrbit to External (`inorbit_to_external`)
-
-Use when InOrbit is the source of truth for waypoints.
-
-**Behavior**:
-- Fetches waypoint annotations from InOrbit Config API
-- Creates/updates matching positions in external system
-- Only manages positions derived from owned annotations
-
-**Best for**:
-- Operators who manage waypoints via InOrbit's map editor
-- Centralized waypoint management
+| Field                   | Required | Default               | Description                 |
+| ----------------------- | -------- | --------------------- | --------------------------- |
+| `enabled`               | No       | `false`               | Enable annotation sync      |
+| `mode`                  | No       | `external_to_inorbit` | Sync mode                   |
+| `sync_interval_seconds` | No       | `300`                 | Interval between syncs      |
+| `location_id`           | Yes*     | -                     | Location tag ID for scoping |
 
 ## Ownership Signatures
 
 The sync uses **signature properties** to identify annotations it manages:
 
-The ownership signature uses a fixed property name (`syncOrigin`) and the connector type as value:
+The ownership signature uses a fixed property name (`syncOrigin`) and the `connector_type` as value.
 
-```yaml
-connector_type: my-connector
-```
-
-This adds a property to each synced annotation:
+This adds a property to each synchronized annotation:
 
 ```json
 {
@@ -124,41 +71,29 @@ This adds a property to each synced annotation:
 }
 ```
 
-**Why this matters**:
-- Prevents deletion of manually created annotations
-- Enables multiple connectors to manage separate annotation sets
-- Provides clear ownership tracking
+This prevents the deletion of manually created annotations and enables multiple connectors to manage separate annotation sets.
 
-## Implementing in Your Connector
+## Usage
 
-### 1. Define Position Model (Pydantic BaseModel)
-
-External positions **must** be Pydantic `BaseModel` subclasses. This is required for:
-- Type-safe serialization via `model_dump()`
-- Automatic change detection in sync operations
+1. Define a Pydantic model for your external positions. This is required for type-safe serialization via `model_dump()` and automatic change detection in sync operations.
 
 ```python
 from pydantic import BaseModel
 
 class MyPosition(BaseModel):
-    """External system position model (must inherit from BaseModel)."""
+    """External system position model."""
     id: str
     name: str
     x: float
     y: float
     orientation: float
 ```
 
-### 2. Implement ExternalAnnotationProvider
-
-Provides CRUD operations for your external system's positions:
+2. Implement the `ExternalAnnotationProvider` protocol.
 
 ```python
 class MyPositionProvider:
-    """Implements ExternalAnnotationProvider protocol."""
-
-    def __init__(self, client):
-        self._client = client
+    """Provides CRUD operations for your external system's positions."""
 
     async def list_positions(self, frame_id: str) -> list[MyPosition]:
         """Fetch positions for the given frame_id (map).
@@ -186,19 +121,11 @@ class MyPositionProvider:
         await self._client.delete_position(position_id)
 ```
 
-### 3. Implement AnnotationConverter
-
-Converts between positions and waypoint annotations:
+3. Implement the `AnnotationConverter` protocol.
 
 ```python
-from inorbit_connector.annotation_sync.models import (
-    SpatialAnnotationData,
-    WaypointAnnotationSpec,
-    WaypointData,
-)
-
 class MyAnnotationConverter:
-    """Implements AnnotationConverter protocol."""
+    """Converts between positions and waypoint annotations."""
 
     def position_to_annotation(
         self, position: MyPosition, frame_id: str
@@ -240,71 +167,24 @@ class MyAnnotationConverter:
         return position.id
 ```
 
-### 4. Framework Creates Sync Managers Per Frame
-
-The framework automatically creates `AnnotationSyncManager` instances for each unique
-`frame_id` as robot poses are published. You don't need to create managers directly.
-
-**How it works**:
-1. When `publish_robot_pose(robot_id, x, y, yaw, frame_id)` is called
-2. If `frame_id` is new (not seen before), the framework creates a sync manager for it
-3. The manager calls `provider.list_positions(frame_id)` to get positions for that map
-4. The manager calls `converter.position_to_annotation(position, frame_id)` to convert
-
-### 5. Integrate with Connector
-
-Register the implementations and let the framework manage initialization and start/stop:
+4. Register the provider and converter with the connector.
 
 ```python
 class MyConnector(FleetConnector):
     def __init__(self, config):
         super().__init__(config)
 
-        # Create provider and converter (frame_id is handled dynamically)
-        provider = MyPositionProvider(self._my_client)
-        converter = MyAnnotationConverter()
-
-        # Register with framework - sync starts automatically per frame_id
-        self.register_annotation_sync(provider, converter)
-```
-
-**Note**: Always register the provider and converter. The framework checks
-`annotation_sync.enabled` to decide whether to actually run the sync.
-
-## Monitoring Sync Operations
-
-The sync manager logs operations at various levels:
-
-| Level | What's Logged |
-|-------|---------------|
-| INFO | Sync start/complete, counts |
-| DEBUG | Individual create/update/delete |
-| WARNING | Skipped operations, missing data |
-| ERROR | Sync failures with stack traces |
-
-Example log output:
-
-```
-INFO - Starting external → InOrbit annotation sync
-DEBUG - Fetched 42 positions from external system
-INFO - Sync complete: 5 created, 3 updated, 34 up to date, 0 to delete
+        # Register provider and converter
+        self.register_annotation_sync(MyPositionProvider(), MyAnnotationConverter())
 ```
 
 ## Troubleshooting
 
-### Annotations not syncing
-
 1. **Check configuration**: Ensure `enabled: true` and valid `mode`
 2. **Verify API key**: Must have permissions for Config API
-3. **Check auth method**: Config API requires `api_key` (robot keys are not supported)
+3. **Check auth method**: The Config API requires an `api_key`, not an `inorbit_robot_key`
 4. **Check scope**: Ensure `account_id` and `location_id` are correct
 
-### Manual annotations being deleted
-
-Check your ownership signature:
-- Manually created annotations won't have the signature property
-- Only annotations with matching signature are managed by sync
-
 ## See Also
 
 - [Annotation Sync API Reference](../specification/annotation-sync)
