docs: make 'python-moodle' the canonical command, 'py-moodle' the alias

AGENTS.md

@@ -2,7 +2,7 @@
 
 ## Purpose
 
-This document provides **implementation and contribution guidelines** for developing new features, modules, or commands within the `py-moodle` project.
+This document provides **implementation and contribution guidelines** for developing new features, modules, or commands within the `python-moodle` project.
 It is designed for both human developers and AI agents that will generate, review, or maintain code in this repository.
 
 ---
@@ -182,23 +182,23 @@ Rules for integration tests:
 
 ## Supported Commands and Features
 
-The CLI uses a subcommand structure. For example, `py-moodle courses list`.
+The CLI uses a subcommand structure. For example, `python-moodle courses list`.
 
 ```sh
 # List all courses
-py-moodle courses list
+python-moodle courses list
 
 # Show details for a specific course
-py-moodle courses show <course-id>
+python-moodle courses show <course-id>
 
 # Create a new course
-py-moodle courses create --fullname "My New Course" --shortname "mynewcourse"
+python-moodle courses create --fullname "My New Course" --shortname "mynewcourse"
 
 # Delete a course
-py-moodle courses delete <course-id>
+python-moodle courses delete <course-id>
 
 # Add a new label to a course section
-py-moodle modules add label <course-id> <section-id> --name "My Label" --intro "Label content"
+python-moodle modules add label <course-id> <section-id> --name "My Label" --intro "Label content"
 ```
 
 ### Capabilities and Webservice Limitations
@@ -342,7 +342,7 @@ MOODLE_PROD_WS_TOKEN=***
 
 ## Naming
 
-The project name is `py-moodle`. If you later publish to PyPI, ensure the name does not clash with Selenium- or API token-based Moodle tools.
+The project name is `python-moodle`. If you later publish to PyPI, ensure the name does not clash with Selenium- or API token-based Moodle tools.
 
 ---
 

Makefile

@@ -45,7 +45,7 @@ lint:
 	flake8
 
 docs:
-	python -m typer py_moodle.cli.app utils docs --output docs/cli.md --name py-moodle
+	python -m typer py_moodle.cli.app utils docs --output docs/cli.md --name python-moodle
 	zensical build
 
 test-unit:

README.md

@@ -1,5 +1,5 @@
 <p align="center">
-  <img src="https://raw.githubusercontent.com/erseco/python-moodle/main/docs/images/py-moodle-icon.png" alt="py-moodle logo" width="128">
+  <img src="https://raw.githubusercontent.com/erseco/python-moodle/main/docs/images/py-moodle-icon.png" alt="python-moodle logo" width="128">
 </p>
 
 # python-moodle
@@ -39,15 +39,15 @@
 pip install python-moodle
 cp .env.example .env
 # Edit .env with your Moodle URL and credentials
-py-moodle courses list
+python-moodle courses list
 ```
 
 ### Typical automation tasks
 
 | Task                          | Command / Use case                            |
 | ----------------------------- | --------------------------------------------- |
-| Bulk course creation          | `py-moodle courses create`                    |
-| SCORM upload pipelines        | `py-moodle modules add scorm`                 |
+| Bulk course creation          | `python-moodle courses create`                    |
+| SCORM upload pipelines        | `python-moodle modules add scorm`                 |
 | Content migration             | Script with `list_courses` + `create_course`  |
 | Moodle smoke tests in CI      | `pytest` + `MoodleSession` fixture            |
 | Admin scripting across instances | `--env` flag with multiple `.env` profiles |
@@ -57,7 +57,7 @@ py-moodle courses list
 !!! warning "Experimental"
     This library is under active development. Use a test Moodle instance and back up data before running commands that create, modify, or delete content.
 
-`py-moodle` allows you to automate tedious Moodle tasks—like creating courses, uploading content, and managing modules—directly from your terminal or in your Python scripts. It works by simulating a real user's web session, so it doesn't require API tokens or special Moodle plugins.
+`python-moodle` allows you to automate tedious Moodle tasks—like creating courses, uploading content, and managing modules—directly from your terminal or in your Python scripts. It works by simulating a real user's web session, so it doesn't require API tokens or special Moodle plugins.
 
 ---
 
@@ -69,7 +69,7 @@ py-moodle courses list
 -   **Authentication**: Supports standard Moodle login and SSO/CAS authentication.
 -   **Dual Use**: Can be used as a powerful CLI or imported as a library into your own Python projects.
 -   **High-level `MoodleClient` facade**: A discoverable, object-oriented API (`moodle.courses.list()`, `moodle.scorm.add(...)`) over the function-based library, plus opt-in typed domain models (`Course`, `User`, `Folder`, ...) for IDE autocompletion.
--   **Diagnostics**: `py-moodle doctor run` checks base URL reachability, login, sesskey/webservice token availability, and more in one command.
+-   **Diagnostics**: `python-moodle doctor run` checks base URL reachability, login, sesskey/webservice token availability, and more in one command.
 -   **Idempotent automation**: `courses ensure` creates a course only if it doesn't already exist, safe to run repeatedly in CI/onboarding scripts.
 -   **Safe previews**: `--dry-run` on `courses create`, `courses delete`, and `modules add scorm` shows the planned action without touching Moodle.
 -   **Scripting-friendly output**: `--output table|json|yaml|csv`, plus `--quiet`, `--no-color`, `--verbose`, and `--debug` (with automatic secret redaction) for CI pipelines and shell automation.
@@ -80,7 +80,7 @@ py-moodle courses list
 
 ## Moodle Compatibility
 
-`py-moodle` interacts with Moodle through authenticated web sessions, HTML forms, and page parsing. To make those flows more resilient across Moodle releases, the library now centralizes version-sensitive logic in `py_moodle.compat`.
+`python-moodle` interacts with Moodle through authenticated web sessions, HTML forms, and page parsing. To make those flows more resilient across Moodle releases, the library now centralizes version-sensitive logic in `py_moodle.compat`.
 
 -   **Version detection** happens during login/session initialization. The library first tries `core_webservice_get_site_info` when a webservice token is available, then falls back to probing the dashboard HTML (`/my/`) for Moodle release metadata.
 -   **Version-aware strategies** are grouped into compatibility ranges instead of scattering selectors throughout the codebase. The current built-in strategies cover legacy Moodle 3.x layouts and modern Moodle 4.x/5.x layouts.
@@ -136,17 +136,17 @@ MOODLE_PROD_PASSWORD=your_super_secret_password
 # MOODLE_PROD_WS_TOKEN=your_webservice_token
 ```
 
-Use the `--env` flag or the `MOODLE_ENV` variable to select the environment, e.g. `py-moodle --env prod courses list`.
+Use the `--env` flag or the `MOODLE_ENV` variable to select the environment, e.g. `python-moodle --env prod courses list`.
 
 > **Note**: For local development, you can quickly spin up a Moodle instance using the provided `docker-compose.yml`: `docker-compose up -d`.
 
-If something is not working for a given environment, run `py-moodle --env prod doctor run` to check base URL reachability, login, sesskey/webservice token availability, and a few other diagnostics in one command (see the [Recipes](https://erseco.github.io/python-moodle/recipes/#diagnosing-a-broken-environment) page for details).
+If something is not working for a given environment, run `python-moodle --env prod doctor run` to check base URL reachability, login, sesskey/webservice token availability, and a few other diagnostics in one command (see the [Recipes](https://erseco.github.io/python-moodle/recipes/#diagnosing-a-broken-environment) page for details).
 
 ---
 
 ## CLI Usage
 
-Once installed, all functionality is available through the `py-moodle` command. Every command and subcommand includes detailed help with the `-h` or `--help` flag.
+Once installed, all functionality is available through the `python-moodle` command (or its shorter alias `py-moodle`). Every command and subcommand includes detailed help with the `-h` or `--help` flag.
 
 ### Common Commands
 
@@ -155,7 +155,7 @@ Here are a few examples of common commands:
 **List all available courses:**
 
 ```bash
-py-moodle courses list
+python-moodle courses list
 ```
 
 *Output:*
@@ -172,32 +172,32 @@ py-moodle courses list
 **Show the structure of a single course:**
 
 ```bash
-py-moodle courses show 2
+python-moodle courses show 2
 ```
 
 **Create a new course:**
 
 ```bash
-py-moodle courses create --fullname "My New Automated Course" --shortname "auto-course-01"
+python-moodle courses create --fullname "My New Automated Course" --shortname "auto-course-01"
 ```
 
 **Add a label to a course section:**
 
 ```bash
-py-moodle modules add label --course-id 2 --section-id 1 --name "Welcome" --intro "<h1>Welcome to the course!</h1>"
+python-moodle modules add label --course-id 2 --section-id 1 --name "Welcome" --intro "<h1>Welcome to the course!</h1>"
 ```
 
 **Upload a SCORM package to a course:**
 
 ```bash
-py-moodle modules add scorm --course-id 2 --section-id 1 --name "My SCORM Package" --path "path/to/your/scorm.zip"
+python-moodle modules add scorm --course-id 2 --section-id 1 --name "My SCORM Package" --path "path/to/your/scorm.zip"
 ```
 
 ---
 
 ## Library Usage (Automation Scripting)
 
-You can also import `py-moodle`'s functions into your own Python scripts to automate complex workflows. The `example_script.py` file provides a comprehensive tutorial.
+You can also import `python-moodle`'s functions into your own Python scripts to automate complex workflows. The `example_script.py` file provides a comprehensive tutorial.
 
 ### Quick Example
 

docs/development.md

@@ -1,14 +1,14 @@
 # Development
 
-Welcome to py-moodle development! This guide covers everything you need to contribute to the project.
+Welcome to python-moodle development! This guide covers everything you need to contribute to the project.
 
 ## Development Setup
 
 ### 1. Clone and Setup
 
 ```bash
 git clone https://github.com/erseco/python-moodle.git
-cd py-moodle
+cd python-moodle
 
 # Create virtual environment
 python -m venv env
@@ -117,7 +117,7 @@ modules is tracked as follow-up work.
 
 ### Transport Strategies
 
-`src/py_moodle/transport/` formalizes the three ways `py-moodle` talks to
+`src/py_moodle/transport/` formalizes the three ways `python-moodle` talks to
 Moodle as explicit, independently testable strategy modules built on top
 of `http.py`:
 

docs/examples.md

@@ -1,6 +1,6 @@
 # Examples
 
-This page contains practical examples of using py-moodle for common tasks.
+This page contains practical examples of using python-moodle for common tasks.
 
 ## Course Management Examples
 
@@ -9,7 +9,7 @@ This page contains practical examples of using py-moodle for common tasks.
 ```bash
 # Create courses from a list
 for course in "Math 101" "Physics 201" "Chemistry 301"; do
-    py-moodle courses create --fullname "$course" --shortname "$(echo $course | tr ' ' '-' | tr '[:upper:]' '[:lower:]')"
+    python-moodle courses create --fullname "$course" --shortname "$(echo $course | tr ' ' '-' | tr '[:upper:]' '[:lower:]')"
 done
 ```
 
@@ -19,7 +19,7 @@ done
 # Add welcome labels to all sections of a course
 course_id=2
 for section in {1..5}; do
-    py-moodle modules add label \
+    python-moodle modules add label \
         --course-id $course_id \
         --section-id $section \
         --name "Section $section Welcome" \
@@ -38,19 +38,19 @@ section_id=1
 folder_name="Course Materials"
 
 # Create the folder first
-py-moodle modules add folder --course-id $course_id --section-id $section_id --name "$folder_name"
+python-moodle modules add folder --course-id $course_id --section-id $section_id --name "$folder_name"
 
 # Upload files (you'll need to get the folder ID from the output above)
 for file in *.pdf; do
-    py-moodle files upload --course-id $course_id --file "$file"
+    python-moodle files upload --course-id $course_id --file "$file"
 done
 ```
 
 ### SCORM Package Upload
 
 ```bash
 # Upload and configure a SCORM package
-py-moodle modules add scorm \
+python-moodle modules add scorm \
     --course-id 2 \
     --section-id 1 \
     --name "Interactive Lesson 1" \

docs/getting-started/configuration.md

@@ -1,6 +1,6 @@
 # Configuration
 
-py-moodle uses environment variables for configuration, typically stored in a `.env` file.
+python-moodle uses environment variables for configuration, typically stored in a `.env` file.
 
 ## Setting Up Credentials
 
@@ -42,9 +42,9 @@ py-moodle uses environment variables for configuration, typically stored in a `.
 Choose which environment configuration to use with the `--env` option or by setting `MOODLE_ENV`.
 
 ```bash
-MOODLE_ENV=prod py-moodle courses list
+MOODLE_ENV=prod python-moodle courses list
 # or
-py-moodle --env prod courses list
+python-moodle --env prod courses list
 ```
 
 If omitted, the environment defaults to `local`.
@@ -54,7 +54,7 @@ If omitted, the environment defaults to `local`.
 Verify your credentials work:
 
 ```bash
-py-moodle courses list
+python-moodle courses list
 ```
 
 If configured correctly, you should see a list of available courses.

docs/getting-started/index.md

@@ -1,16 +1,16 @@
 # Getting Started
 
-Welcome to py-moodle! This section will help you get up and running quickly.
+Welcome to python-moodle! This section will help you get up and running quickly.
 
-## What is py-moodle?
+## What is python-moodle?
 
-py-moodle is a modern Pythonic CLI and library that allows you to manage Moodle instances via web sessions. It provides both a command-line interface and a Python library for automating Moodle tasks.
+python-moodle is a modern Pythonic CLI and library that allows you to manage Moodle instances via web sessions. It provides both a command-line interface and a Python library for automating Moodle tasks.
 
 ## Quick Navigation
 
-- **[Installation](installation.md)** - Install py-moodle on your system
+- **[Installation](installation.md)** - Install python-moodle on your system
 - **[Configuration](configuration.md)** - Set up your Moodle credentials
-- **[Quick Start](quickstart.md)** - Your first py-moodle commands
+- **[Quick Start](quickstart.md)** - Your first python-moodle commands
 
 ## Key Features
 
@@ -21,4 +21,4 @@ py-moodle is a modern Pythonic CLI and library that allows you to manage Moodle
 - ✅ **Multiple content types** - Folders, assignments, SCORM, and more
 
 !!! tip "New to Moodle automation?"
-    Start with the [Quick Start](quickstart.md) guide to see py-moodle in action within minutes.
+    Start with the [Quick Start](quickstart.md) guide to see python-moodle in action within minutes.

docs/getting-started/installation.md

@@ -5,8 +5,8 @@
 !!! note "Package name vs. command name"
     The package is published as **`python-moodle`** (that's what you `pip install`
     and `import py_moodle`), and the CLI is available under **two equivalent
-    command names**: **`py-moodle`** and **`python-moodle`**. Use whichever you
-    prefer — every example in these docs uses `py-moodle`.
+    command names**: **`python-moodle`** (used throughout these docs) and the
+    shorter alias **`py-moodle`**. Use whichever you prefer.
 
 ## Method 1: PyPI (Recommended)
 
@@ -24,7 +24,7 @@ cd python-moodle
 pip install .
 ```
 
-This makes the `py-moodle` (and `python-moodle`) command available system-wide.
+This makes the `python-moodle` command (and its `py-moodle` alias) available system-wide.
 
 ## Method 3: Development Installation
 
@@ -43,9 +43,9 @@ The `-e` flag installs in "editable" mode, so changes to the source code are imm
 Test that the CLI is properly installed (either command works):
 
 ```bash
-py-moodle --help
-# or, equivalently:
 python-moodle --help
+# or, equivalently, the shorter alias:
+py-moodle --help
 ```
 
 You should see the main help screen with available commands.