Synchronize Documentation for V4

README.md

@@ -37,10 +37,11 @@ In a virtual env with temoa installed, run:
 
 ```bash
 # Create tutorial files in the current directory
-temoa tutorial quick_start
+# Creates tutorial_config.toml and tutorial_database.sqlite
+temoa tutorial
 
 # Run the model
-temoa run quick_start.toml
+temoa run tutorial_config.toml
 ```
 
 ## Package Structure
@@ -99,16 +100,16 @@ Temoa provides a modern, user-friendly CLI built with Typer:
 **Run a model:**
 
 ```bash
-temoa run config.toml
-temoa run config.toml --output results/
-temoa run config.toml --build-only  # Build without solving
+temoa run tutorial_config.toml
+temoa run tutorial_config.toml --output results/
+temoa run tutorial_config.toml --build-only  # Build without solving
 ```
 
 **Validate configuration:**
 
 ```bash
-temoa validate config.toml
-temoa validate config.toml --debug
+temoa validate tutorial_config.toml
+temoa validate tutorial_config.toml --debug
 ```
 
 **Database migration:**
@@ -139,9 +140,9 @@ temoa --help                     # Full help
 When working with the source code, use `uv run` to ensure you're using the correct dependencies:
 
 ```bash
-uv run temoa run config.toml      # Run with project dependencies
-uv run temoa validate config.toml # Validate configuration
-uv run temoa tutorial my_first_model # Create tutorial files
+uv run temoa run tutorial_config.toml      # Run with project dependencies
+uv run temoa validate tutorial_config.toml # Validate configuration
+uv run temoa tutorial             # Create tutorial files
 ```
 
 ## Programmatic Usage
@@ -165,7 +166,7 @@ config = TemoaConfig(
 
 # Build and solve model
 model = TemoaModel(config)
-result = model.run()  # Equivalent to: temoa run config.toml
+result = model.run()  # Equivalent to: temoa run tutorial_config.toml
 
 # Check if run was successful
 if result:
@@ -256,21 +257,21 @@ Builds model without solving. Useful for validation and troubleshooting.
 1. **Setup**: Create configuration and database files:
 
    ```bash
-   temoa tutorial my_project
+   temoa tutorial
    ```
 
 2. **Configure**: Edit the configuration file to match your scenario
 
 3. **Validate**: Check configuration before running:
 
    ```bash
-   temoa validate my_project_config.toml
+   temoa validate tutorial_config.toml
    ```
 
 4. **Run**: Execute the model:
 
    ```bash
-   temoa run my_project_config.toml
+   temoa run tutorial_config.toml
    ```
 
 5. **Review**: Check results in `output_files/YYYY-MM-DD_HHMMSS/`
@@ -326,7 +327,7 @@ If you encounter solver errors:
 pip install ".[solver]"  # Include specific solver packages
 
 # For free solver
-temoa run config.toml --debug  # Get detailed error information
+temoa run tutorial_config.toml --debug  # Get detailed error information
 ```
 
 ## Documentation & Support

docs/README.md

@@ -64,7 +64,8 @@ pdflatex toolsforenergymodeloptimizationandanalysistemoa.tex
 
 The Temoa documentation draws from two main sources:
 
-1. **Static descriptions** - Model elements and concepts described in `source/Documentation.rst`
+1. **Static descriptions** - Model elements and concepts described in `.rst` files in `source/` (e.g., `mathematical_formulation.rst`, `database.rst`)
+
 2. **Code docstrings** - Objective function and constraint documentation from module docstrings in:
    - `temoa/components/costs.py` - Objective function
    - `temoa/components/*.py` - Constraint implementations

docs/source/database.rst

@@ -106,13 +106,15 @@ recommend that you populate input tables in the following order:
   * limit_tech_output_split
 
 
-For help getting started, consider using the ``temoa tutorial <model_name>``
+For help getting started, consider using the ``temoa tutorial``
 command to generate a template project or inspect the example SQL file at
 ``temoa/tutorial_assets/utopia.sql``. To begin building your own database file, use
 ``temoa/db_schema/temoa_schema_v4.sql``, which is a database file with the requisite
 structure but no data added. We recommend leaving the database structure intact,
 and simply adding data to the schema file, or constructing an empty database
 from the schema file and then using a script or database editor to import data.
+For existing databases from older versions, use the ``temoa migrate`` command
+to safely transition your data to the V4 schema.
 Once the sql file is complete, you can convert it into a binary sqlite file by
 installing sqlite3 and executing the following command:
 
@@ -147,12 +149,9 @@ in the config file.
 Data Quality
 ============
 
-In addition to numerous internal checks, Temoa (optionally) employs two quality checks on
-data read in from the database.  The outputs (actions and warnings) generated by these processes
-are reported in the log file for the run.
-
-Both of the checks below can be run to QA data by running the model in `CHECK` mode and inspecting
-the log file.  During `CHECK` mode runs, no solve is attempted on the model.
+Both of the checks below can be run to QA data by using the ``temoa validate``
+command (which runs the model in ``BUILD_ONLY`` mode) and inspecting the log file.
+During validation runs, no solve is attempted on the model.
 
 Price Checking
 --------------

docs/source/quick_start.rst

@@ -38,8 +38,8 @@ Then, install Temoa:
   $ pip install temoa
 
   # Get started
-  $ python -m temoa tutorial my_first_model
-  $ python -m temoa run my_first_model.toml
+  $ temoa tutorial
+  $ temoa run tutorial_config.toml
 
 **Using uv (Alternative)**:
 
@@ -60,8 +60,8 @@ For faster dependency resolution:
   $ uv add temoa
 
   # Get started
-  $ uv run temoa tutorial my_first_model
-  $ uv run temoa run my_first_model.toml
+  $ uv run temoa tutorial
+  $ uv run temoa run tutorial_config.toml
 
 **For Contributors (Development Installation)**:
 
@@ -109,28 +109,27 @@ the log file produced during model execution, (4) return the lp file utilized by
 the solver, and (5) to execute several of the modeling extensions.
 
 .. parsed-literal::
-  $ temoa run config.toml
+  $ temoa run tutorial_config.toml
 
 **For general help, use --help:**
 
 .. parsed-literal::
   $ **temoa --help**
-    usage: temoa [-h] [--version] [--how-to-cite] COMMAND ...
+    Usage: temoa [OPTIONS] COMMAND [ARGS]...
 
     Tools for Energy Model Optimization and Analysis (Temoa)
 
-    options:
-      -h, --help       show this help message and exit
-      --version        Show version information
-      --how-to-cite    Show citation information
-
-    commands:
-      COMMAND
-        run            Run a Temoa model
-        validate       Validate a configuration file
-        check-units    Check unit consistency in a database
-        migrate        Migrate a database to the latest schema
-        tutorial       Create tutorial files
+    Options:
+      -v, --version           Show Temoa version and exit.
+      --how-to-cite           Show citation information and exit.
+      -h, --help              Show this message and exit.
+
+    Commands:
+      validate     Validates a configuration file and database.
+      run          Builds and solves a Temoa model.
+      check-units  Check units consistency in a Temoa database.
+      migrate      Migrate a Temoa database file or directory.
+      tutorial     Create tutorial configuration and database files.
 
 ..
     dated references, preserved as comment here: