moodle-cli 0.5.5 → 0.7.0-alpha.0

package/ONBOARDING.md

@@ -0,0 +1,54 @@
+---
+name: moodle-cli-onboarding
+description: Help a student set up moodle-cli through a short conversation.
+---
+
+# moodle-cli onboarding
+
+You are helping a student connect their university Moodle account to `moodle-cli`. Take ownership of the setup. Keep commands and configuration details out of the conversation unless the student asks or you need their help with an error.
+
+## Start the conversation
+
+Use the student's language and begin with one question:
+
+> What is your university's Moodle URL? You can paste any Moodle page you use, such as the dashboard, a course, or the login page.
+
+Wait for the answer before doing setup work. Do not ask the student to find the site origin, remove part of the URL, choose a runtime, or edit a configuration file.
+
+## Handle the setup
+
+Once the student shares a URL, complete the setup on their computer:
+
+- Check for Node.js 22+ and Bun. Install `moodle-cli` with the runtime available on the computer. Use `bunx --bun moodle-cli` as the command prefix when Bun is the only runtime.
+- Follow redirects and resolve the URL to the final Moodle origin in the form `https://host`. Remove the path, query, and fragment. Confirm that the origin serves Moodle before saving it.
+- Read `~/.config/moodle-cli/config.yaml` if it exists. Set `base_url` to the verified origin and preserve the other settings.
+- Tell the student that Moodle may open in their browser and that you will wait while they complete their university sign-in. Run `moodle auth login`. If a browser opens, let the student finish SSO there, then continue when the command returns.
+- Verify the account with `moodle user --json` and `moodle overview --json`. Diagnose configuration or authentication failures and retry before reporting success. If browser sign-in times out, run `moodle auth login` again after the student is ready.
+- Set up session renewal after verification. On macOS, run `moodle auth keepalive install` and confirm it with `moodle auth keepalive status --json`. On Linux, schedule `moodle auth keepalive --json` every 30 minutes with cron. On other systems, use the operating system scheduler for the same command or explain how to renew with `moodle auth keepalive`.
+- Install the bundled agent skill with `moodle skills add`. In a Bun-only environment, use `bunx --bun skills add https://github.com/bunizao/moodle-cli`.
+
+Do not ask the student to copy a Moodle cookie, `sesskey`, browser database, or API token into the conversation. Do not print credentials. Keep the Moodle session on the student's computer.
+
+## Offer remote access
+
+After local verification succeeds, ask:
+
+> Do you have a Cloudflare account? I can use it to deploy a private remote MCP server, which lets supported web AI clients connect to your Moodle.
+
+If the student declines or has no account, finish the onboarding with local access. Mention that they can add remote access later.
+
+If the student wants remote access, run `moodle mcp deploy`. Let them complete Cloudflare authorization in the browser when Wrangler requests it. The deployment command manages Worker creation, encrypted Moodle session upload, local renewal, and supported client configuration.
+
+Verify the deployment with `moodle mcp status --json`. Continue troubleshooting until the command reports that the Worker and Moodle session are ready. Ask which web AI client the student wants to use, then guide them through that client's current custom MCP connection flow. Put access credentials into the client's connection settings, not the chat.
+
+## Finish with something useful
+
+After both verification commands succeed, run `moodle todo --days 14 --json`. Summarize the student's upcoming work in the language they used.
+
+End with three requests they can try next, adapted to the Moodle data you found:
+
+- “Plan my Moodle work for this week.”
+- “Download the slides from this Moodle link.”
+- “Find forum posts about the next assessment.”
+
+If the student has no upcoming items, say so and use their enrolled units to suggest relevant requests. Report the verified Moodle site and account, but omit session values and internal credentials.

package/README.md

@@ -1,155 +1,214 @@
 # moodle-cli
 
-Terminal-first CLI for Moodle LMS that reuses an authenticated browser session. No Moodle API token required.
+**Give your AI agent access to Moodle.**
 
-## Features
+Let it keep up with deadlines and grades, fetch course files, and search forum discussions. `moodle-cli` finds your active browser session and keeps it alive in the background, so Moodle's login wall stays out of your way.
 
-- Reuses `MoodleSession` from `okta-auth`, your browser, or `MOODLE_SESSION`
-- Uses Moodle AJAX APIs and falls back to authenticated page scraping when needed
-- Lists courses, deadlines, alerts, activities, grades, and forum discussions
-- Agent-friendly JSON/YAML output, field selection, and stable exit codes
+[![npm version](https://img.shields.io/npm/v/moodle-cli?logo=npm)](https://www.npmjs.com/package/moodle-cli)
+[![CI](https://github.com/bunizao/moodle-cli/actions/workflows/ci.yml/badge.svg)](https://github.com/bunizao/moodle-cli/actions/workflows/ci.yml)
+[![Node.js 22+](https://img.shields.io/badge/Node.js-22%2B-339933?logo=nodedotjs&logoColor=white)](https://nodejs.org/)
+[![Bun](https://img.shields.io/badge/Bun-supported-fbf0df?logo=bun&logoColor=black)](https://bun.sh/)
+[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-## Install
+## Quick links
 
-```bash
-npm i -g moodle-cli
+- [Set up with your agent](#start-with-your-agent)
+- [Install and sign in manually](#install-and-sign-in-manually)
+- [Study Boooooooooost](#study-boooooooooost)
+- [Connect web AI through a private MCP server](#remote-mcp-for-web-ai)
+- [Developer and agent reference](#for-developers-and-agents)
+
+## For users
+
+### Start with your agent
+
+Paste this into Codex, Claude Code, OpenClaw, Hermes Agent, or another agent that can use your terminal:
+
+```text
+Can you use https://github.com/bunizao/moodle-cli/raw/main/ONBOARDING.md to help me set up moodle-cli?
 ```
 
-Run without installing:
+Your agent asks for your Moodle URL and opens your university's sign-in page when needed. Finish SSO in the browser while the agent waits; it verifies your account and sets up session renewal before reading Moodle. The same onboarding can deploy a private remote MCP server through your Cloudflare account.
+
+### Install and sign in manually
+
+Use Node.js 22+ or Bun:
 
 ```bash
-npx moodle-cli --help
+# npm
+npm install -g moodle-cli
+
+# Bun
+bun add --global moodle-cli
+
+moodle --version
 ```
 
-Standalone binaries are attached to GitHub Releases for macOS arm64 and Linux x64.
+Run without a global install:
 
-### Existing PyPI Users
+```bash
+npx moodle-cli --help
+bunx --bun moodle-cli --help
+```
 
-The TypeScript CLI keeps the same config file and environment variables as the Python package. Migrate with:
+Sign in and open your dashboard:
 
 ```bash
-uv tool uninstall moodle-cli
-npm i -g moodle-cli
+moodle auth login
+moodle overview
 ```
 
-`~/.config/moodle-cli/config.yaml`, `MOODLE_BASE_URL`, and `MOODLE_SESSION` remain compatible.
+On first use, enter your Moodle site origin, such as `https://moodle.example.edu`. `moodle-cli` validates it and saves it to `~/.config/moodle-cli/config.yaml`. If the CLI cannot find an active session, it opens your university's sign-in page and waits for you to finish.
 
-## Authentication
+Keep the session active on macOS with `moodle auth keepalive install`. On Linux, schedule `moodle auth keepalive --json` every 30 minutes with cron.
 
-Use one of:
+GitHub Releases also provide standalone binaries for macOS arm64 and Linux x64.
 
-- `okta-auth-cli` configured for your Moodle site
-- an active Moodle browser session
-- a `MOODLE_SESSION` environment variable
+### Study Boooooooooost
 
-Optional Okta setup:
+Ask your agent in plain language or run the matching command:
+
+| Student request | CLI command |
+| --- | --- |
+| “Give me a quick Moodle dashboard.” | `moodle overview` |
+| “What is due in the next 14 days?” | `moodle todo --days 14` |
+| “Show my grades and feedback for FIT1045.” | `moodle grades FIT1045` |
+| “Find forum posts about the exam in FIT1045.” | `moodle forums search "exam" --course FIT1045` |
+| “Download the slides from this Moodle link.” | `moodle download '<Moodle URL>' --dest './slides.pdf'` |
+
+Unit arguments accept a Moodle course ID or a unique course name.
+
+#### Paste Moodle links directly
+
+The CLI recognizes course, forum, assignment, quiz, resource, page, folder, and grade-report URLs:
 
 ```bash
-npm i -g okta-auth-cli
-okta config
+moodle 'https://moodle.example.edu/course/view.php?id=34637'
+moodle 'https://moodle.example.edu/mod/forum/discuss.php?d=9001#p9101'
+moodle download 'https://moodle.example.edu/mod/resource/view.php?id=91234' --dest './Week 03/slides.pdf'
 ```
 
-On first run, if no `base_url` is configured, the CLI prompts for the Moodle root URL and saves it to `~/.config/moodle-cli/config.yaml`:
+You can paste the same links into your agent and ask it to inspect the page, find related material, or download the file.
+
+#### Download course files
+
+`moodle download` accepts an activity ID or an authenticated Moodle URL. `--dest` sets the exact local path, and `--force` replaces an existing file after the download completes. Folder activities expose `file_entries` so you can choose which files to save.
 
-```yaml
-base_url: https://school.example.edu
+### Remote MCP for web AI
+
+A private remote MCP server lets a supported web AI client use Moodle when it cannot run the local CLI. You need a Cloudflare account.
+
+```bash
+moodle mcp deploy
+moodle mcp status
 ```
 
-Use a root URL only, not `/login/index.php` or `/my/`.
+`moodle mcp deploy` validates Moodle access, deploys a Cloudflare Worker, uploads an encrypted Moodle session, verifies readiness, and installs session renewal. The guided [`ONBOARDING.md`](ONBOARDING.md) asks whether you want this after local setup and helps connect your web AI client.
 
-## Usage
+### Update
 
 ```bash
-moodle --help
-moodle user
-moodle alerts
-moodle todo
-moodle overview
-moodle courses
-moodle grades 34637
-moodle activities 34637
-moodle https://school.example.edu/course/view.php?id=34637
-moodle https://school.example.edu/mod/forum/discuss.php?d=9001#p9101 --json
-moodle skills
-moodle skills generate
-moodle skills add
-moodle update
-moodle update --check-only
+npm install -g moodle-cli@latest
+bun add --global moodle-cli@latest
 ```
 
-Supported Moodle URLs can be passed as the first argument. The CLI routes forum discussion, forum view, assignment, quiz, resource, link, page, folder, course, and grade report URLs to the shortest matching command.
+Standalone binaries print the latest GitHub Release URL instead of modifying themselves.
+
+## For developers and agents
 
-## Agent Output Contract
+### Command and output contract
 
-JSON-capable commands support:
+Inspect the full machine-readable command tree:
 
-- `--json`: write JSON to stdout
-- `--yaml`: write YAML to stdout
-- `--table`: force human output
-- `--fields a,b,c`: keep only listed top-level fields; arrays apply the filter per item
+```bash
+moodle commands --json
+```
 
-When stdout is not a TTY, the CLI defaults to JSON. `--table` overrides that.
+Commands support:
 
-Invalid `--fields` values fail as usage errors and list valid fields.
+- `--json` or `--yaml` for structured output
+- `--table` for human-readable output
+- `--fields a,b,c` to select fields
+- `-o, --output FILE` to write command output or a download receipt
 
-With JSON output enabled, errors are one parseable JSON line on stderr:
+The CLI prints tables in an interactive terminal and JSON when stdout goes to a pipe or file. Structured errors use one JSON object on stderr:
 
 ```json
-{"error":true,"code":"auth_failed","message":"...","hint":"..."}
+{"ok":false,"error":{"code":"auth","message":"...","hint":"..."},"exit_code":3}
 ```
 
-Exit codes:
-
 | Code | Meaning |
 | --- | --- |
 | 0 | Success |
-| 1 | Unexpected error |
-| 2 | Authentication or configuration error |
-| 3 | Usage error |
-| 4 | Requested course, activity, forum, or discussion was not found |
+| 1 | Network, configuration, or unexpected error |
+| 2 | Usage error |
+| 3 | Authentication error |
+| 4 | Course, activity, forum, or discussion not found |
+| 5 | Moodle rejected the request |
+
+### Agent skill
 
-## Updates
+Install the generated skill bundle:
 
 ```bash
-moodle update --check-only
-moodle update --json
+moodle skills add
+
+# Direct alternatives
+npx skills add https://github.com/bunizao/moodle-cli
+bunx --bun skills add https://github.com/bunizao/moodle-cli
 ```
 
-`moodle update` checks `https://registry.npmjs.org/moodle-cli/latest`. npm installs update with:
+[`SKILL.md`](SKILL.md) routes agents to focused setup, coursework, forum, download, and maintenance guidance under [`references/`](references/).
+
+### MCP lifecycle and protocol
 
 ```bash
-npm install -g moodle-cli@latest
+moodle mcp deploy
+moodle mcp status
+moodle mcp login
+moodle mcp connect
+moodle mcp remove
+moodle mcp serve
+moodle mcp bridge
 ```
 
-Standalone binaries print the latest GitHub Release URL instead of modifying themselves.
+The default client connection uses `moodle mcp bridge`, which keeps the Bearer token out of client configuration. Use `moodle mcp connect CLIENT --mode remote` for clients that support authenticated remote MCP headers.
 
-## Agent Skill
+Alpha version `0.7.0-alpha.0` supports MCP `2026-07-28` and a stateless compatibility lane for `2025-11-25` clients.
 
-Install the bundled agent skill:
+### Configuration
 
-```bash
-npx skills add https://github.com/bunizao/moodle-cli
-```
+| Variable | Purpose |
+| --- | --- |
+| `MOODLE_BASE_URL` | Set the Moodle site origin without writing a config file. |
+| `MOODLE_CONFIG` | Use another YAML config file. |
+| `MOODLE_TOKEN` | Provide a `MoodleSession` cookie value in a non-browser environment. |
+| `MOODLE_SESSION` | Compatibility alias for `MOODLE_TOKEN`. |
 
-The CLI alias delegates to the same command:
+For local use, save `base_url` in `~/.config/moodle-cli/config.yaml`. `MOODLE_URL` remains a deprecated fallback for `MOODLE_BASE_URL`.
 
-```bash
-moodle skills add
-```
+### Build from source
 
-Regenerate `SKILL.md` from the command tree:
+Node.js workflow:
 
 ```bash
+npm ci
+npm run check
+npm test
 npm run build
-npm run skill:generate
-git diff --exit-code SKILL.md
+npm run pack:check
 ```
 
-## Development
+Bun workflow:
 
 ```bash
-npm install
-npm run check
-npm test
-npm run build
+bun install
+bunx tsc --noEmit
+bunx vitest run
+bun run build
+bun run pack:check
 ```
+
+## License
+
+[MIT](LICENSE)

package/SKILL.md

@@ -1,167 +1,38 @@
 ---
 name: moodle-cli
-description: Inspect Moodle data from the terminal with the `moodle` CLI. Use when an agent needs courses, deadlines, grades, alerts, activities, or forum discussions. Prefer JSON output for agent workflows.
+description: Read Moodle data, download local files, and manage a private Moodle MCP deployment with the `moodle` CLI. Use for authenticated profile, unit discovery, deadlines, alerts, sections, activities, grades, forum workflows, local file downloads, supported Moodle URLs, authentication diagnostics, or MCP deploy, status, login, connection, and removal.
 ---
 
-# moodle-cli
+# Moodle CLI
 
-<!-- Generated by `moodle skills generate`. Edit `src/skill.template.md` for prose changes. -->
+<!-- Generated by `moodle skills generate`. Edit `src/skill.template.md` and `src/skill-references/`. -->
 
-Use `moodle` for read-only Moodle access.
+Use `moodle` for read-only Moodle inspection, explicit local file downloads, and private managed MCP lifecycle operations.
 
-## Defaults
+## Core Steps
 
-Use the narrowest command that answers the request.
+1. Classify the request with the branch map below and read that reference file before running a command.
+2. Run the narrowest command that answers the request. Prefer `--json`; add `--fields` when only a few top-level fields matter.
+3. Parse the result locally and answer with the requested facts, exact dates, and relevant Moodle links. The task is complete when the answer is supported by command output rather than inference.
 
-Prefer JSON for agent work. `--json` is explicit, and piped stdout defaults to JSON automatically. Use `--fields` to keep only the top-level fields you need.
+Resolve an unfamiliar unit name with `moodle units --json` before using a unit-specific command. `courses` and `projects` are equivalent aliases. Use `moodle overview --json` only for an explicitly combined snapshot.
 
-Omit `--json` only when a human explicitly wants the formatted terminal view. Use `--table` to force human output in a pipe.
+## Branch Map
 
-Resolve course IDs with `moodle courses --json` before running course-specific commands when the user gives only a course name.
+- **Installation, configuration, authentication failure, session keepalive, or managed MCP lifecycle**: read [references/setup-and-auth.md](references/setup-and-auth.md).
+- **Profile, course discovery, sections, or activity lists**: read [references/profile-and-courses.md](references/profile-and-courses.md).
+- **Deadlines, todo items, alerts, or a combined snapshot**: read [references/deadlines-and-alerts.md](references/deadlines-and-alerts.md).
+- **Grades or assignment, quiz, resource, link, page, and folder detail**: read [references/coursework-and-grades.md](references/coursework-and-grades.md).
+- **Downloading a resource or selected folder files to local paths**: read [references/downloads.md](references/downloads.md).
+- **Forum discovery, search, discussions, posts, groups, or rendering checks**: read [references/forums.md](references/forums.md).
+- **Output selection, field filtering, error handling, or exit codes**: read [references/output-and-errors.md](references/output-and-errors.md).
+- **Updates, skill installation, or skill regeneration**: read [references/maintenance.md](references/maintenance.md).
+- **Exact syntax or all flags**: read [references/command-reference.md](references/command-reference.md).
 
-Avoid `moodle overview --json` unless the user explicitly asks for a combined snapshot across courses, deadlines, and alerts.
+## Shared Rules
 
-## Setup
-
-```bash
-npm i -g moodle-cli
-# or run without installing
-npx moodle-cli --help
-```
-
-Standalone binaries are published on GitHub Releases.
-
-Existing PyPI users should migrate:
-
-```bash
-uv tool uninstall moodle-cli
-npm i -g moodle-cli
-```
-
-Authenticate with an active Moodle browser session, `MOODLE_SESSION`, or `okta-auth-cli`.
-
-Set `MOODLE_BASE_URL` or let the first run prompt for the Moodle root URL and save it to config.
-
-## Forum Routing
-
-For forum requests, prefer `moodle forum find` over manually chaining `forum forums`, `forum discussions`, and `forum discussion`.
-
-If the user already gives a forum discussion URL, skip search and open it directly with `moodle forum discussion DISCUSSION_OR_URL --json`.
-
-If the user gives a forum view URL or discussion URL and wants to browse nearby discussions, use `moodle forum discussions FORUM_OR_URL --json`.
-
-Use scan budgets first when the site may be large:
-
-- `--course` to narrow to one course
-- `--limit-forums` to cap how many forums to scan
-- `--limit-discussions` to cap how many discussions to scan per forum
-
-Grouped forums are handled automatically. Do not assume an empty default forum page means the forum has no discussions.
-
-Default forum agent flow:
-
-1. Start with `moodle forum find QUERY --json`
-2. Add `--unread-only` when the user wants new or unseen content
-3. Add `--list --limit N` when one result is not enough and you need a shortlist
-4. Add `--body` only when the snippet is insufficient and you need the full target post/discussion
-
-Avoid `moodle forum search` unless you explicitly need a larger result set than `forum find --list`.
-
-## Intent To Command
-
-| User intent | Command |
-| --- | --- |
-| Show my profile or account info | moodle user --json |
-| List my courses | moodle courses --json |
-| Find nearest deadlines or upcoming actions | moodle todo --limit 5 --days 14 --json |
-| List alerts or unread notifications | moodle alerts --limit 10 --json |
-| Show a compact dashboard | moodle overview --todo-limit 5 --alerts-limit 5 --json |
-| Show activities in a course | moodle activities COURSE_ID --json |
-| Show course sections | moodle course COURSE_ID --json |
-| Show grades for a course | moodle grades COURSE_ID --json |
-| Find the best forum match | moodle forum find QUERY --json |
-| Open a forum discussion URL or ID | moodle forum discussion DISCUSSION_OR_URL --json |
-| Check whether the CLI has an update | moodle update --json |
-| Install this agent skill | moodle skills add |
-
-## Command Reference
-
-| Command | Description | Arguments | Flags |
-| --- | --- | --- | --- |
-| moodle activities | List activities in a course. | <course> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle alerts | List notifications and message counts. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 20; value required) |
-| moodle assign | Show assignment details. | <assign> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle course | Show course detail with sections. | <course> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle courses | List enrolled courses. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle folder | Show folder details. | <folder> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle forum | Forum utilities. |  |  |
-| moodle forum check | Validate discussion rendering. | <forum> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 20; value required) |
-| moodle forum discussion | Show posts in a forum discussion. | <discussion> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--post (value required)<br>--body |
-| moodle forum discussions | List discussions from a forum. | <forum> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 50; value required)<br>--query (value required) |
-| moodle forum find | Find the best forum match. | <query> | --list<br>--body<br>--json<br>--yaml<br>--table<br>--fields (value required)<br>--course (value required)<br>--forum (value required)<br>--titles-only<br>--unread-only<br>--recent<br>--limit-forums (value required)<br>--limit-discussions (value required)<br>--limit (default: 5; value required) |
-| moodle forum forums | List forum activities. | [query] | --json<br>--yaml<br>--table<br>--fields (value required)<br>--course (value required)<br>--limit (default: 50; value required) |
-| moodle forum search | Search forum discussion titles and post text. | <query> | --json<br>--yaml<br>--table<br>--fields (value required)<br>--course (value required)<br>--forum (value required)<br>--titles-only<br>--unread-only<br>--recent<br>--limit-forums (value required)<br>--limit-discussions (value required)<br>--limit (default: 20; value required) |
-| moodle grades | Show grade details for a course. | <course> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle link | Show link details. | <link> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle overview | Show a compact multi-source overview. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--todo-limit (default: 5; value required)<br>--todo-days (value required)<br>--alerts-limit (default: 5; value required) |
-| moodle page | Show page details. | <page> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle quiz | Show quiz details. | <quiz> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle resource | Show resource details. | <resource> | --json<br>--yaml<br>--table<br>--fields (value required) |
-| moodle skills | Show skill metadata or delegate to the shared skills CLI. |  |  |
-| moodle skills add | Install the published skill through npx skills add. |  |  |
-| moodle skills generate | Regenerate SKILL.md from the CLI command tree. |  |  |
-| moodle todo | List upcoming actionable timeline items. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--limit (default: 20; value required)<br>--days (value required) |
-| moodle update | Check for updates and upgrade the installed CLI. |  | --json<br>--yaml<br>--table<br>--fields (value required)<br>--check-only |
-| moodle user | Show authenticated user info. |  | --json<br>--yaml<br>--table<br>--fields (value required) |
-
-## Agent Output
-
-### Output Contract
-
-- `--json` writes JSON to stdout.
-- `--yaml` writes YAML to stdout when supported.
-- `--table` forces human-readable table/tree output.
-- When stdout is not a TTY, commands default to JSON unless `--table` is set.
-- `--fields a,b,c` keeps only listed top-level fields. Arrays apply the field filter to each item.
-- Invalid `--fields` values are usage errors and list valid fields.
-- With JSON output enabled, errors are one JSON line on stderr: `{"error":true,"code":"auth_failed","message":"...","hint":"..."}`.
-
-Exit codes:
-
-| Code | Meaning |
-| --- | --- |
-| 0 | Success |
-| 1 | Unexpected error |
-| 2 | Authentication or configuration error |
-| 3 | Usage error |
-| 4 | Requested course, activity, forum, or discussion was not found |
-
-## Operating Rules
-
-Parse JSON locally and return a concise answer.
-
-Do not paste full command output unless the user explicitly asks for raw JSON.
-
-If the user asks for "recent", "next", or "nearest", sort by relevance and mention exact timestamps from `due_at` or `created_at`.
-
-If a request is ambiguous between activities, courses, and grades, inspect courses first and then run the smallest follow-up command.
-
-For forum work, do not enumerate forums or discussions first unless the user explicitly asks to browse. Search first, then expand only if needed.
-
-For forum discussion output, prefer structured fields over heuristic text parsing when available:
-
-- `image_urls` for original image links
-- `links` for extracted hyperlinks
-- `tables` for structured table content
-- `group_id` and `group_name` for grouped forum context
-
-## Failure Modes
-
-- Authentication failed: sign in to Moodle in the browser, export `MOODLE_SESSION`, or configure `okta-auth-cli`.
-- Invalid base URL: use the Moodle site root such as `https://school.example.edu`, not `/login/index.php` or `/my/`.
-- Could not check for updates: retry with network access to the npm registry, then run `npm install -g moodle-cli@latest` or download the latest GitHub Release binary.
-
-## Safety
-
-- Treat `MOODLE_SESSION` as a secret and never paste it into chat or logs.
-- The CLI is read-only and does not create or modify Moodle content.
+- Treat `moodle commands --json` as the source of truth for this tool's command tree.
+- Use `--table` only when the user asks for the terminal presentation.
+- Return a concise answer instead of pasting raw output unless raw JSON is requested.
+- Treat `MOODLE_SESSION` as a secret and keep it out of chat, commands shown to the user, and logs.
+- Keep remote Moodle data read-only. `moodle download` may write only the explicitly selected local file path; managed MCP commands may change only the selected Worker, local renewal job, client registration, and MCP deployment credentials.

package/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Moodle CLI"
+  short_description: "Inspect Moodle and download local Moodle files"
+  default_prompt: "Use $moodle-cli to inspect my Moodle data or download selected local Moodle files with the narrowest relevant command."