bgmx

name	bgmx
description	Maintain bgmx project data workflows only when the user explicitly invokes $bgmx or explicitly asks Codex to maintain bgmx data. Covers syncing Bangumi subject data, manually creating Bangumi subject revisions, syncing yuc.wiki seasonal calendars, and switching the active online calendar season.

bgmx

Overview

Use this skill for routine bgmx data maintenance. Treat commands that include --update-server, --update-active, subject revision, or direct bgmw HTTP writes as production-affecting unless the user points at a local --base-url.

Use bgmx ... in examples. If bgmx is unavailable, use npx --yes bgmx ....

Workflow

1. Confirm the CLI is available:

   command -v bgmx >/dev/null 2>&1 && bgmx --version || npx --yes bgmx --version
   

2. Inspect current state before writing:
   • Identify the target API: production default https://bgm.animes.garden/ or a local/dev --base-url.
   • For server updates, create or confirm a .env file in the current working directory with SECRET=<value>. Prefer .env; do not pass secrets directly on the command line.
3. Use read-only commands first when possible:
   • bgmx subject <subject_id>
   • bgmx calendar --season <yyyy-MM>
4. After writing, run the narrow verification command for the affected workflow and summarize the command output.

Sync Bangumi Subjects

Use this when the user asks to refresh bgmx subject data from Bangumi.

• Pull and update all Bangumi subject data:

  bgmx sync bangumi --update-server
  

• Save fetched data without writing the server by running from a directory without SECRET in .env:

  bgmx sync bangumi
  

• Useful options:
  • --out-dir <directory> writes local Bangumi JSON data.
  • --log <file> records unknown subjects and update errors.
  • --concurrency <number> and --retry <number> control fetch behavior.

After syncing, inspect the log for unknown subjects and failures. If the user asks for a release or PR, mention the sync count and any error count.

Manage Subject Revisions

Use revisions for manual corrections to a bgmx subject's search behavior. The CLI is interactive.

1. Inspect the currently effective subject and enabled revisions:

   bgmx subject <subject_id>
   

2. Create a revision:

   bgmx subject revision <subject_id>
   

3. Choose one of the supported fields:
   • search.include
   • search.exclude
   • search.keywords
   • search.before
   • search.after
4. For set fields, choose set.add, set.delete, or field.set. For before/after, enter a parseable datetime.
5. List all revisions, including disabled revisions:

   bgmx subject revision list <subject_id>
   

6. Enable or disable an existing revision:

   bgmx subject revision enable <subject_id> <revision_id>
   bgmx subject revision disable <subject_id> <revision_id>
   

7. Permanently delete a revision only when the user explicitly asks for deletion:

   bgmx subject revision delete <subject_id> <revision_id>
   

Prefer small, targeted revisions. Do not edit database rows directly unless the user explicitly asks for a migration or repair.

Sync And Switch Calendar

Use this section only for calendar update work: importing a yuc.wiki season, resolving Bangumi subject ids, uploading the calendar, marking a season active, or cancelling an active season.

Update And Activate A Calendar

1. Generate an initial yuc calendar session file in a draft directory without .env, so it cannot upload. Use an explicit session file name so it can be reviewed and edited:

   bgmx sync yuc \
     --year 2026 \
     --month 7 \
     --session yuc-2026-07.yaml
   

2. Read the generated session file. Find every calendar item whose id is missing or -1.
3. Infer missing Bangumi subject ids using the available tools:
   • Query bgmx subjects first when useful: bgmx subject <subject_id>.
   • Use bgmc/Bangumi search for candidate subjects.
   • Use web search when title aliases, season naming, or release metadata are ambiguous.
   • Prefer the exact seasonal subject, not the franchise/root subject.
4. Update the session file with resolved Bangumi subject ids.
5. Report the complete calendar before uploading. Include every animation in the season and its Bangumi subject id, grouped by weekday and web/ONA.
6. Wait for the user to confirm the reported calendar.
7. Upload the confirmed calendar and mark the season active:

   bgmx sync yuc \
     --year 2026 \
     --month 7 \
     --session yuc-2026-07.yaml \
     --update-server \
     --update-active true
   

8. Verify the uploaded season:

   bgmx calendar --season 2026-07
   

Calendar seasons use yyyy-MM where MM is 01, 04, 07, or 10. sync yuc derives this season from explicit --year and --month; when both are omitted and --session is set, it derives them from the session file name, with or without the hyphen between year and month.

Cancel An Active Calendar

Use this when the user asks to deactivate a season without deleting its calendar data.

1. Confirm the target season:

   bgmx calendar --season 2026-07
   

2. Mark it inactive:

   bgmx sync yuc \
     --year 2026 \
     --month 7 \
     --session yuc-2026-07.yaml \
     --update-server \
     --update-active false
   

3. Verify active calendar state:

   bgmx calendar
   bgmx calendar --season 2026-07