Add task-oriented recipes page to the docs

docs/recipes.md

@@ -0,0 +1,109 @@
+# Recipes
+
+This page collects task-oriented workflows for common `py-moodle` jobs.
+Use these recipes when you want a copy/paste starting point instead of a full
+command reference.
+
+## Verify your environment and login
+
+Use this recipe first when setting up a new `.env` profile or switching to a
+different Moodle environment.
+
+```bash
+# Use the environment from MOODLE_ENV or pass one explicitly.
+py-moodle --env local site info
+```
+
+If the command succeeds, your credentials, session bootstrap, and base URL are
+working together.
+
+If it fails:
+
+- confirm the selected environment name matches your `.env` keys
+- verify `MOODLE_<ENV>_URL`, `MOODLE_<ENV>_USERNAME`, and
+  `MOODLE_<ENV>_PASSWORD`
+- review the [Troubleshooting](troubleshooting.md) guide for common login and
+  session failures
+
+## Inspect a course before changing it
+
+Use these commands together when you need to confirm IDs and current state
+before creating or deleting content.
+
+```bash
+# Find the course ID you want to work with.
+py-moodle courses list
+
+# Inspect one course in detail.
+py-moodle courses show 2
+
+# List its sections before adding modules.
+py-moodle sections list 2
+```
+
+This flow is useful for scripts and manual operations because it reduces the
+chance of targeting the wrong course or section.
+
+## Create a course and add a welcome label
+
+This is a minimal end-to-end content bootstrap workflow.
+
+```bash
+# 1. Create the course.
+py-moodle courses create \
+  --fullname "Automation Demo" \
+  --shortname "automation-demo"
+
+# 2. Create a section if you need one beyond the default course layout.
+py-moodle sections create 2 --name "Getting Started"
+
+# 3. Add a welcome label to the first section.
+py-moodle modules add label \
+  --course-id 2 \
+  --section-id 1 \
+  --name "Welcome" \
+  --intro "<p>Welcome to the course.</p>"
+```
+
+Replace the example course ID with the ID returned by the create command in
+your environment.
+
+## Upload materials into a folder
+
+Use the dedicated folder commands when you want to manage a reusable course
+materials area.
+
+```bash
+# Create a folder activity in the course.
+py-moodle folders add \
+  --course-id 2 \
+  --section-id 1 \
+  --name "Course Materials"
+
+# Upload a file into the folder activity.
+py-moodle folders add-file 15 ./docs/syllabus.pdf
+
+# Confirm the folder contents.
+py-moodle folders list-content 15
+```
+
+In this recipe, `15` is the folder module ID returned by the add command.
+
+## Run the fastest contributor validation loop
+
+When you are changing code or documentation, this sequence gives the quickest
+feedback with the existing repository tooling.
+
+```bash
+# Fast smoke tests with no live Moodle requirement.
+make test-unit
+
+# Static checks used by CI.
+make lint
+
+# Rebuild the documentation site, including generated CLI docs.
+make docs
+```
+
+Use `make test-local` only when you need Docker-backed integration coverage
+against the local Moodle environment.

mkdocs.yml

@@ -127,6 +127,7 @@ nav:
     - User Management:
       - User: api/user.md
   - Examples: examples.md
+  - Recipes: recipes.md
   - Development: development.md
   - Troubleshooting: troubleshooting.md
   - Improvement Roadmap: roadmap-plan.md