minor docs/ edits fixing inaccuracies

Author: vredchenko

docs/how-to/database-migrations.md

@@ -33,10 +33,10 @@ python -m alembic upgrade head
 
 This will:
 1. Create the Alembic version tracking table
-2. Apply migration 001: Create user preferences table
-3. Apply baseline migration (6e6302f1ccb6): Create all core SmartEM schema tables (acquisition, grid, gridsquare, micrograph, foilhole, atlas, quality prediction models, etc.)
-4. Apply migration 002: Add performance indexes for acquisition datetime queries
-5. Apply remaining migrations including agent communication tables
+2. Apply migration 001: Create core SmartEM schema baseline (acquisition, grid, gridsquare, micrograph, foilhole, atlas, etc.)
+3. Apply migration 002: Add performance indexes for acquisition datetime queries
+4. Apply migration 003: Add prediction model tables
+5. Apply remaining migrations for quality metrics, training tables, and schema fixes
 
 ### Running Migrations
 
@@ -268,11 +268,17 @@ Ensure your environment variables are set:
 │   ├── env.py                              # Migration environment
 │   ├── script.py.mako                      # Migration template
 │   └── versions/                           # Individual migration files
-│       ├── 001_add_user_preferences.py
-│       ├── 002_add_acquisition_time_index.py
-│       └── 003_seed_system_config.py
+│       ├── 2025_09_18_1042-001_create_core_smartem_schema_baseline.py
+│       ├── 2025_01_11_1431-002_add_acquisition_time_index.py
+│       ├── 2025_09_18_1630-003_add_scifi_robot_prediction_models.py
+│       └── ...                              # Additional migrations
 ```
 
+**Migration file naming convention**: `YYYY_MM_DD_HHMM-NNN_description.py` where:
+- `YYYY_MM_DD_HHMM` is the creation timestamp
+- `NNN` is the sequential migration number
+- `description` describes the change
+
 ## Further Reading
 
 - [Alembic Documentation](https://alembic.sqlalchemy.org/)

docs/how-to/use-core-http-api-client.md

@@ -71,17 +71,16 @@ acquisitions = await client.aget_acquisitions()
 ### Creating an Acquisition
 
 ```python
-from smartem_agent.model.schemas import EpuSessionData
+from smartem_common.schemas import AcquisitionData
 from datetime import datetime
 
-# Create an acquisition from EPU session data
-session = EpuSessionData(
-    id="my-acquisition-id",
+# Create an acquisition from acquisition data
+acquisition_data = AcquisitionData(
     name="My Acquisition",
     start_time=datetime.now(),
     storage_path="/path/to/storage"
 )
-response = client.create_acquisition(session)
+response = client.create_acquisition(acquisition_data)
 print(f"Created acquisition with ID: {response.id}")
 
 # Alternatively, create directly with an API request model
@@ -138,29 +137,28 @@ The client supports the full hierarchy of entities:
 Here's an example of creating entities at each level:
 
 ```python
+from smartem_common.schemas import (
+    AcquisitionData, GridData, GridSquareData, FoilHoleData,
+    MicrographData, MicrographManifest
+)
+
 # Create an acquisition
-acquisition = client.create_acquisition(EpuSessionData(id="acq-1", name="Test Acquisition"))
+acquisition_data = AcquisitionData(name="Test Acquisition")
+acquisition = client.create_acquisition(acquisition_data)
 
 # Create a grid for the acquisition
-from smartem_agent.model.schemas import GridData
-
 grid = GridData(data_dir="/path/to/grid")
 grid_response = client.create_acquisition_grid(acquisition.id, grid)
 
 # Create a grid square for the grid
-from smartem_agent.model.schemas import GridSquareData
-
 gridsquare = GridSquareData(id="gs-1", data_dir="/path/to/gridsquare")
 gridsquare_response = client.create_grid_gridsquare(grid_response.id, gridsquare)
 
 # Create a foil hole for the grid square
-from smartem_agent.model.schemas import FoilHoleData
-
 foilhole = FoilHoleData(id="fh-1", gridsquare_id=gridsquare.id)
 foilhole_response = client.create_gridsquare_foilhole(gridsquare_response.id, foilhole)
 
 # Create a micrograph for the foil hole
-from smartem_agent.model.schemas import MicrographData, MicrographManifest
 
 manifest = MicrographManifest(
     unique_id="mic-1",

docs/reference/cli-reference.md

@@ -16,7 +16,7 @@ The CLI is organised into the following command groups:
 
 ## Global Options
 
-All commands support the following verbosity options:
+The following verbosity options are supported by the `watch` command:
 
 | Option | Short | Type | Default | Description |
 |--------|-------|------|---------|-------------|
@@ -27,6 +27,8 @@ All commands support the following verbosity options:
 - **1 (-v)**: INFO level - General information and warnings
 - **2 (-vv)**: DEBUG level - Detailed debugging information
 
+> **Note**: The `-v`/`--verbose` flag currently only works with the `watch` command. Parse and validate commands use default logging levels. This is a known limitation.
+
 ## Parse Commands
 
 Parse commands extract and process data from EPU files without persisting to the backend API. These are primarily used for development, debugging, and data validation purposes.
@@ -44,7 +46,6 @@ python -m smartem_agent parse dir [OPTIONS] EPU_OUTPUT_DIR
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `epu_output_dir` | str | Yes | Path to EPU output directory containing multiple grid directories |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -69,7 +70,6 @@ python -m smartem_agent parse grid [OPTIONS] GRID_DATA_DIR
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `grid_data_dir` | str | Yes | Path to individual grid data directory |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -94,7 +94,6 @@ python -m smartem_agent parse session [OPTIONS] PATH
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | str | Yes | Path to EPU session manifest file |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -116,7 +115,6 @@ python -m smartem_agent parse atlas [OPTIONS] PATH
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | str | Yes | Path to atlas manifest file |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -138,7 +136,6 @@ python -m smartem_agent parse gridsquare-metadata [OPTIONS] PATH
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | str | Yes | Path to grid square metadata file |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -160,7 +157,6 @@ python -m smartem_agent parse gridsquare [OPTIONS] PATH
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | str | Yes | Path to grid square manifest file |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -182,7 +178,6 @@ python -m smartem_agent parse foilhole [OPTIONS] PATH
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | str | Yes | Path to foil hole manifest file |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -204,7 +199,6 @@ python -m smartem_agent parse micrograph [OPTIONS] PATH
 | Parameter | Type | Required | Description |
 |-----------|------|----------|-------------|
 | `path` | str | Yes | Path to micrograph manifest file |
-| `--verbose` | count | No | Verbosity level (see [Global Options](#global-options)) |
 
 **Example:**
 ```bash
@@ -226,7 +220,6 @@ python -m smartem_agent validate [OPTIONS] PATH
 | Parameter | Type | Required | Default | Description |
 |-----------|------|----------|---------|-------------|
 | `path` | str | Yes | - | Path to EPU project directory to validate |
-| `--verbose` | count | No | 0 | Verbosity level (see [Global Options](#global-options)) |
 
 **Exit Codes:**
 - **0**: Directory structure is valid

docs/tutorials/installation.md

@@ -61,13 +61,7 @@ pip install -e .[all]
 
 ## Verify Installation
 
-The library should now be installed with the command-line interface available on your system path. Verify the installation by checking the installed version:
-
-```bash
-smartem-decisions --version
-```
-
-You can also verify that all components are correctly installed by running:
+Verify that all components are correctly installed by running:
 
 ```bash
 # Test core functionality
@@ -77,6 +71,13 @@ python -c "import smartem_backend, smartem_agent, smartem_common; print('Core co
 python -c "import smartem_mcp; print('MCP components available')"
 ```
 
+You can also verify the CLI tools are available:
+
+```bash
+# Check agent CLI is accessible
+python -m smartem_agent --help
+```
+
 ## Next Steps
 
 Once installation is complete, you can proceed to: