moodle-downloader-mcp: Instructions file for Codex

AGENTS.md — moodle-agent

You are helping with moodle-agent: a CLI that downloads courses from any Moodle site for offline / AI use.

Read first

1. Agent README: README.agents.md — start here
2. Full runbook: docs/AGENT_GUIDE.md
3. Humans: README.md

Universal (no school defaults)

• Every school has its own URL and username format (email, student id, LDAP, index number, …).
• Never invent username patterns. Ask the user what they use on their portal.
• No built-in school URL. Always get URL from the user (or MOODLE_URL).
• Password is never stored — only a webservice token.

Binary

# after: pip install -e .  (or uv / venv)
moodle-agent
# or: python -m moodle_agent.cli

Non-negotiables

• Use --json. stdout = data, stderr = progress.
• Never store or echo passwords/tokens.
• Cold start: moodle-agent setup --json → if not authenticated, ask URL + username + password (or token) → init --force --json.
• Optional URL check (no password): moodle-agent probe --url <URL> --json
• “All courses” → moodle-agent sync --out ./courses --json
• “One course” → courses list → course download <id>
• “One file” → download/sync that course → find file locally (no per-file API in v0.1)
• Prefer offline work under ./courses (or configured out_dir) after download.

Auth (agent)

# 1) What to ask the user
moodle-agent setup --json

# 2) Optional: is this Moodle URL usable?
moodle-agent probe --url "https://moodle.example.edu" --json

# 3) Login (any school)
export MOODLE_URL="https://moodle.example.edu"
export MOODLE_USER="..."          # school-specific format
export MOODLE_PASS='...'          # single quotes if password contains $
moodle-agent init --out ./courses --force --json

# Multi-school:  init --name uni-a …   init --name uni-b …
# Naming prefs:  --name-style preserve|latinica|ascii
#                --course-dir-style fullname|fullname_id|classic