ima-claude 2.9.0

package/plugins/ima-claude/skills/discourse-admin/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: discourse-admin
+description: "Discourse admin API for site settings, configuration export/import, categories, groups, and custom user fields. Use when: managing Discourse site configuration, deploying config to staging/production, exporting settings, bulk-updating site settings, managing groups or user fields via API. Triggers on: discourse admin, discourse settings, discourse config, site settings, config-as-code, discourse deploy, discourse staging."
+---
+
+# Discourse Admin API
+
+Manage Discourse site configuration programmatically via the REST API. Export settings, apply environment configs, manage groups and user fields — without clicking through the admin UI.
+
+## When to Use This Skill
+
+- Exporting or importing Discourse site settings
+- Deploying configuration to staging or production environments
+- Bulk-updating site settings via API
+- Managing groups, categories, or custom user fields programmatically
+- Config-as-code workflows for Discourse
+
+**Not this skill**: For Discourse *plugin development* (Ruby/Rails/Ember), use the `discourse` skill instead.
+
+## Quick Start
+
+**Prerequisites**: Configure environments in `~/.claude/discourse-environments.json`:
+```json
+{
+  "local": {
+    "url": "http://localhost:4200",
+    "api_key": "your-local-api-key",
+    "api_username": "system"
+  },
+  "staging": {
+    "url": "https://staging.community.example.com",
+    "api_key": "staging-key",
+    "api_username": "system"
+  }
+}
+```
+
+**Run commands**:
+```bash
+python3 ~/.claude/skills/discourse-admin/scripts/discourse-admin.py export
+python3 ~/.claude/skills/discourse-admin/scripts/discourse-admin.py import base.json staging-overlay.json
+python3 ~/.claude/skills/discourse-admin/scripts/discourse-admin.py diff config.json
+python3 ~/.claude/skills/discourse-admin/scripts/discourse-admin.py get title
+python3 ~/.claude/skills/discourse-admin/scripts/discourse-admin.py set disable_emails yes
+python3 ~/.claude/skills/discourse-admin/scripts/discourse-admin.py envs
+```
+
+## Environment Resolution
+
+Resolved via priority chain (same pattern as `wp-local`):
+
+1. `--env` flag on command line
+2. `$DISCOURSE_ENV` environment variable
+3. `.discourse-env` file in project root or parents
+4. Falls back to `"local"`
+
+```bash
+# Explicit env
+python3 discourse-admin.py --env staging export
+
+# Env var (set in Kitty terminal config)
+export DISCOURSE_ENV=staging
+python3 discourse-admin.py export
+
+# Project file
+echo "staging" > .discourse-env
+python3 discourse-admin.py export
+```
+
+**Credentials** stored in `~/.claude/discourse-environments.json` (not in repo, not in env vars).
+API keys are managed at `/admin/api/keys` in each Discourse instance.
+
+## Config-as-Code Workflow
+
+### Step 1: Export Non-Default Settings
+
+```bash
+python3 discourse-admin.py export discourse-base.json
+```
+
+Exports only settings where value differs from default — typically 50-100 settings, not 500+.
+
+### Step 2: Create Environment Overlays
+
+```
+config/
+  discourse-base.json          # Non-default settings from local
+  discourse-staging.json       # Staging overrides
+  discourse-production.json    # Production overrides
+```
+
+**Staging overlay example** (`discourse-staging.json`):
+```json
+{
+  "title": "[STAGING] Community Forum",
+  "site_description": "Staging environment — do not use for real discussions",
+  "disable_emails": "yes",
+  "notification_email": "noreply-staging@example.com",
+  "discourse_connect_provider_secrets": "staging.example.com|staging-secret-here"
+}
+```
+
+### Step 3: Preview Changes (Dry Run)
+
+```bash
+# Show what would change
+python3 discourse-admin.py --env staging import base.json staging.json --dry-run
+
+# Compare remote vs desired
+python3 discourse-admin.py --env staging diff base.json
+```
+
+### Step 4: Apply Config
+
+```bash
+python3 discourse-admin.py --env staging import discourse-base.json discourse-staging.json
+```
+
+Uses bulk_update endpoint (single request). Falls back to individual updates if bulk fails.
+
+## Site Settings API
+
+The primary endpoint for config-as-code. ~500+ settings covering email, SSO, branding, security, etc.
+
+### Key Endpoints
+
+| Method | Path | Purpose |
+|--------|------|---------|
+| GET | `/admin/site_settings.json` | List all settings |
+| GET | `/admin/site_settings/category/{slug}.json` | Filter by category |
+| PUT | `/admin/site_settings/{name}.json` | Update single setting |
+| PUT | `/admin/site_settings/bulk_update.json` | Update multiple (undocumented, source-verified) |
+
+**Setting categories:** `required`, `basic`, `users`, `email`, `login`, `security`, `onboarding`, `spam`, `rate_limits`, `developer`, `embedding`, `legal`, `branding`, `uncategorized`
+
+## When to Load Reference Files
+
+### Full API Reference
+**File**: `references/api-endpoints.md`
+**Load when**: You need exact parameters, response formats, or edge cases for any admin endpoint (groups, categories, users, user fields, site texts, API keys).
+
+### Known Gotchas
+**File**: `references/gotchas.md`
+**Load when**: Hitting unexpected behavior, 404s, or working with a specific Discourse version. Contains breaking changes across versions and endpoint migration history.
+
+### Staging Defaults
+**File**: `references/staging-defaults.md`
+**Load when**: Setting up a new staging environment. Contains recommended safe defaults and a pre-deploy checklist.
+
+## Common Staging Settings
+
+| Setting | Staging Value | Why |
+|---------|--------------|-----|
+| `disable_emails` | `yes` | Prevent sending real emails |
+| `title` | `[STAGING] ...` | Visual distinction |
+| `notification_email` | staging address | Don't spam real inbox |
+| `discourse_connect_provider_secrets` | staging domains | SSO only for staging WP sites |
+| `enable_local_logins` | `true` | Allow direct login for testing |
+| `min_password_length` | `6` | Easier test accounts |
+| `invite_only` | `true` | Prevent public signups |
+
+## Rate Limiting
+
+- Admin API rate limits are site-setting driven (not hardcoded)
+- Two independent limiters: IP-based (`max_reqs_per_ip_mode`) and API-key-based (`max_admin_api_reqs_per_minute`, default 60)
+- max=0 means BLOCK ALL (not unlimited) — use high numbers like 6000
+- Must flush Redis rate limit keys after changing rate limit config
+
+## Quick Reference (Manual curl)
+
+```bash
+# List all settings
+curl -s -H "Api-Key: $KEY" -H "Api-Username: system" "$URL/admin/site_settings.json"
+
+# Get email settings only
+curl -s -H "Api-Key: $KEY" -H "Api-Username: system" "$URL/admin/site_settings/category/email.json"
+
+# Update a single setting
+curl -s -X PUT -H "Api-Key: $KEY" -H "Api-Username: system" \
+  -H "Content-Type: application/json" \
+  -d '{"disable_emails": "yes"}' \
+  "$URL/admin/site_settings/disable_emails.json"
+
+# List groups
+curl -s -H "Api-Key: $KEY" -H "Api-Username: system" "$URL/groups.json"
+
+# List custom user fields
+curl -s -H "Api-Key: $KEY" -H "Api-Username: system" "$URL/admin/config/user_fields.json"
+
+# List categories
+curl -s -H "Api-Key: $KEY" -H "Api-Username: system" "$URL/categories.json"
+```

package/plugins/ima-claude/skills/discourse-admin/references/api-endpoints.md

@@ -0,0 +1,441 @@
+# Discourse Admin API — Full Endpoint Reference
+
+Source-verified against Discourse source code (`config/routes.rb` and controllers).
+Last verified: 2026-03-02 against Discourse 2026.2.x codebase.
+
+## Table of Contents
+
+1. [Site Settings](#site-settings)
+2. [Categories](#categories)
+3. [Groups](#groups)
+4. [Users](#users)
+5. [Custom User Fields](#custom-user-fields)
+6. [Site Texts (i18n)](#site-texts)
+7. [API Keys](#api-keys)
+
+---
+
+## Site Settings
+
+### GET /admin/site_settings.json
+
+List all site settings.
+
+**Query params:**
+- `categories` — filter by setting categories
+- `plugin` — filter by plugin name
+- `names` — filter specific setting names
+
+**Response:** Array of settings, each with:
+```json
+{
+  "setting": "title",
+  "value": "My Forum",
+  "default": "Discourse",
+  "description": "The name of this site...",
+  "type": "string",
+  "category": "required"
+}
+```
+
+### GET /admin/site_settings/category/{slug}.json
+
+List settings filtered to a category.
+
+**Category slugs:** `required`, `basic`, `users`, `email`, `login`, `security`, `onboarding`, `spam`, `rate_limits`, `developer`, `embedding`, `legal`, `branding`, `uncategorized`
+
+### PUT /admin/site_settings/{setting_name}.json
+
+Update a single setting.
+
+**Body:** `{ "setting_name": "value" }`
+**Response:** `200 OK` (empty body)
+
+### PUT /admin/site_settings/bulk_update.json
+
+Update multiple settings in one request.
+
+**Body:**
+```json
+{
+  "settings": {
+    "setting_1": { "value": "...", "backfill": false },
+    "setting_2": { "value": "..." }
+  }
+}
+```
+
+The `backfill` flag (optional, default false) triggers retroactive application to existing users where applicable.
+
+### PUT /admin/site_settings/user_count.json
+
+Get count of users affected by a setting change (useful before backfill).
+
+---
+
+## Categories
+
+**NOTE:** Category routes are NOT under `/admin/`. Permission checks are inline in the controller via Guardian.
+
+### GET /categories.json
+
+List all categories.
+
+**Query params:** `include_subcategories` (boolean), `page` (integer)
+
+**Response:**
+```json
+{
+  "category_list": {
+    "categories": [
+      {
+        "id": 1,
+        "name": "General",
+        "color": "0088CC",
+        "text_color": "FFFFFF",
+        "slug": "general",
+        "topic_count": 42,
+        "position": 0,
+        "read_restricted": false,
+        "permission": null,
+        "parent_category_id": null
+      }
+    ]
+  }
+}
+```
+
+### GET /site.json
+
+Alternative: returns all categories in a flat array under `categories` key, plus trust levels and other site metadata.
+
+### POST /categories.json
+
+Create category. Requires `can_create_category` permission.
+
+**Body (required):** `name`, `color`, `text_color`
+**Body (optional):** `slug`, `parent_category_id`, `description`, `permissions`
+
+**Permissions format:**
+```json
+{
+  "permissions": {
+    "everyone": 1,
+    "staff": 1,
+    "custom_group": 3
+  }
+}
+```
+Permission levels: `1` = See/Reply/Create, `2` = See/Reply, `3` = See only
+
+### PUT /categories/{id}.json
+
+Update category. Requires `can_edit_category` permission.
+
+**Body:** Any category fields.
+
+### DELETE /categories/{id}.json
+
+Delete category. Requires `can_delete_category` permission.
+
+---
+
+## Groups
+
+### GET /groups.json
+
+List all groups. Public groups visible without auth.
+
+**Query params:** `page` (integer)
+
+**Response:**
+```json
+{
+  "groups": [
+    {
+      "id": 50,
+      "name": "moderators",
+      "display_name": "Forum Moderators",
+      "user_count": 5,
+      "visibility_level": 0,
+      "automatic": false
+    }
+  ]
+}
+```
+
+### GET /groups/{group_name}.json
+
+Get group details by name.
+
+### POST /admin/groups.json
+
+Create group. Requires staff.
+
+**Body (all under `group` key):**
+```json
+{
+  "group": {
+    "name": "my-group",
+    "display_name": "My Group",
+    "visibility_level": 0,
+    "mentionable_level": 0,
+    "messageable_level": 0,
+    "members_visibility_level": 0,
+    "automatic_membership_email_domains": "",
+    "title": "",
+    "primary_group": false,
+    "grant_trust_level": null,
+    "bio_raw": "",
+    "public_admission": false,
+    "public_exit": false,
+    "owner_usernames": "",
+    "usernames": ""
+  }
+}
+```
+
+**Visibility levels:** `0` = public, `1` = logged-in, `2` = members, `3` = staff, `4` = owners
+
+### PUT /groups/{id}.json
+
+Update group. Same fields as create under `group` key.
+
+### DELETE /admin/groups/{id}.json
+
+Delete group. Requires admin.
+
+### PUT /groups/{id}/members.json
+
+Add members.
+
+**Body:** `{ "usernames": "alice,bob,charlie" }`
+**Response:** `{ "success": "OK", "usernames": ["alice", "bob", "charlie"] }`
+
+### DELETE /groups/{id}/members.json
+
+Remove members.
+
+**Body:** `{ "usernames": "alice,bob" }`
+
+### PUT /groups/{id}/owners.json
+
+Add group owners.
+
+**Body:** `{ "usernames": "alice" }`
+
+### DELETE /admin/groups/{id}/owners.json
+
+Remove group owner.
+
+**Body:** `{ "user_id": 123 }` — NOTE: uses `user_id`, not `usernames`
+
+---
+
+## Users
+
+### POST /users.json
+
+Create user.
+
+**Body (required):** `name`, `username`, `email`, `password`
+**Body (optional):** `active` (boolean, skip email confirm), `approved` (boolean), `user_fields[{id}]` (set custom field values by field ID)
+
+### GET /u/{username}.json
+
+Get user profile. Returns `user_fields` keyed by field ID.
+
+### GET /admin/users/{id}.json
+
+Get admin user view. Includes email, IP, groups, flags, suspensions.
+
+### PUT /u/{username}.json
+
+Update user profile.
+
+**Body:** `name`, `bio_raw`, `user_fields[{id}]`, `timezone`, etc.
+
+### GET /u/by-external/{external_id}.json
+
+Lookup user by external (SSO/DiscourseConnect) ID. Admin required.
+
+### GET /admin/users/list/{flag}.json
+
+List users by flag: `active`, `new`, `staff`, `suspended`, `blocked`, `suspect`
+
+**Query params:** `page`, `show_emails`, `order` (`created`, `last_emailed`, etc.), `asc`
+
+### GET /admin/users.json
+
+Search/filter users.
+
+**Query params:** `filter` (searches username/email), `show_emails`
+
+### PUT /admin/users/{id}/activate.json
+
+Activate user account.
+
+### PUT /admin/users/{id}/deactivate.json
+
+Deactivate user account.
+
+### PUT /admin/users/{id}/suspend.json
+
+Suspend user.
+
+**Body (required):** `suspend_until` (ISO 8601), `reason`
+
+### PUT /admin/users/{id}/silence.json
+
+Silence user.
+
+**Body (required):** `silenced_till` (ISO 8601)
+**Body (optional):** `reason`
+
+**Known quirk:** If user is already silenced, the endpoint may NOT update the date.
+
+### DELETE /admin/users/{id}.json
+
+Delete user.
+
+**Body:** `delete_posts`, `block_email`, `block_urls`, `block_ip` (all boolean)
+
+---
+
+## Custom User Fields
+
+**CRITICAL:** Endpoints migrated in Discourse 3.5.0 (late 2025). Old path `/admin/customize/user_fields.json` returns 404.
+
+### GET /admin/config/user_fields.json
+
+List all custom user fields. Both `user_fields` (underscore) and `user-fields` (hyphen) work for GET.
+
+**Response:**
+```json
+[
+  {
+    "id": 1,
+    "name": "Company",
+    "description": "Your company name",
+    "field_type": "text",
+    "editable": true,
+    "required": false,
+    "show_on_profile": true,
+    "show_on_user_card": false,
+    "searchable": false,
+    "position": 0
+  }
+]
+```
+
+### POST /admin/config/user_fields.json
+
+Create custom user field.
+
+**Body:**
+```json
+{
+  "user_field": {
+    "name": "Company",
+    "field_type": "text",
+    "editable": true,
+    "required": false,
+    "show_on_profile": true,
+    "show_on_user_card": false,
+    "searchable": false,
+    "description": "Your company name",
+    "options": ["Option A", "Option B"]
+  }
+}
+```
+
+**Field types:** `text`, `confirm`, `dropdown`, `multiselect`
+**`options` required for:** `dropdown`, `multiselect`
+
+### PUT /admin/config/user_fields/{id}.json
+
+Update custom user field. Same body as create under `user_field` key.
+
+### DELETE /admin/config/user_fields/{id}.json
+
+Delete custom user field.
+
+### Setting Field Values on Users
+
+Field values are set/read on the user object, NOT through admin user fields endpoints:
+
+- **Create:** `POST /users.json` with `user_fields[{field_id}]`
+- **Update:** `PUT /u/{username}.json` with `user_fields[{field_id}]`
+- **Read:** `GET /u/{username}.json` returns `user_fields: { "1": "value" }`
+
+---
+
+## Site Texts
+
+Manage i18n string overrides.
+
+### GET /admin/customize/site_texts.json
+
+List i18n strings.
+
+**Query params:** `q` (search), `locale`, `overridden` ("true"), `outdated` ("true"), `untranslated` ("true"), `page`
+
+### GET /admin/customize/site_texts/{id}.json
+
+Get single string by key.
+
+### PUT /admin/customize/site_texts/{id}.json
+
+Override string translation.
+
+**Body:** `{ "site_text": { "value": "Custom text here" } }`
+
+### DELETE /admin/customize/site_texts/{id}.json
+
+Revert to default translation.
+
+---
+
+## API Keys
+
+### GET /admin/api/keys.json
+
+List API keys (paginated, max 50).
+
+### POST /admin/api/keys.json
+
+Create API key.
+
+**Body:**
+```json
+{
+  "key": {
+    "username": "system",
+    "description": "Config management",
+    "scope_mode": "granular",
+    "scopes": []
+  }
+}
+```
+
+### DELETE /admin/api/keys/{id}.json
+
+Delete API key.
+
+### POST /admin/api/keys/{id}/revoke.json
+
+Revoke key (soft delete).
+
+### POST /admin/api/keys/{id}/undo-revoke.json
+
+Restore revoked key.
+
+---
+
+## Access Control Summary
+
+| Constraint | Who | Used by |
+|------------|-----|---------|
+| `AdminConstraint` | `current_user.admin?` | Site settings, user fields, delete group, API keys |
+| `StaffConstraint` | `current_user.staff?` | Create group, group owner management |
+| Guardian `can_*` | Permission checks | Categories CRUD, user profile updates |