Add per-file daily/weekly/monthly/yearly task scheduler

.github/workflows/daily-improve.yml

@@ -0,0 +1,68 @@
+name: Daily Improve
+
+# Runs a daily automated improvement pass on mtgBot. It iteratively improves the
+# repository every day: applying content improvements, ensuring documentation
+# coverage, validating the codebase, and committing the results.
+#
+# "Starting now" — the schedule runs every day at 09:00 UTC. It can also be
+# triggered manually from the Actions tab via workflow_dispatch.
+
+on:
+  schedule:
+    # Every day at 09:00 UTC
+    - cron: "0 9 * * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Prevent overlapping daily runs from racing on the same branch.
+concurrency:
+  group: daily-improve
+  cancel-in-progress: false
+
+jobs:
+  improve:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run daily maintenance and improvement pass
+        run: |
+          npm run maintain
+          npm run improve || true
+          npm run improve:content || true
+
+      - name: Regenerate documentation
+        run: |
+          npm run build:toc || true
+          npm run generate:hooks || true
+
+      - name: Validate codebase
+        run: |
+          npm run lint
+          npm test
+          npm run validate:json
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if [ -n "$(git status --porcelain)" ]; then
+            git add -A
+            git commit -m "chore: daily automated improvement ($(date -u +%Y-%m-%d))"
+            git push
+          else
+            echo "No changes to commit."
+          fi

.github/workflows/monthly-tasks.yml

@@ -0,0 +1,63 @@
+name: Monthly Tasks
+
+# Runs the monthly cadence of the per-file task scheduler. It regenerates the
+# task manifest (tasks/tasks.json) and executes the whitelisted monthly
+# commands, then validates and commits any resulting changes.
+#
+# The schedule runs on the 1st of every month at 09:00 UTC. It can also be
+# triggered manually from the Actions tab via workflow_dispatch.
+
+on:
+  schedule:
+    # 09:00 UTC on the 1st of every month
+    - cron: "0 9 1 * *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Prevent overlapping monthly runs from racing on the same branch.
+concurrency:
+  group: monthly-tasks
+  cancel-in-progress: false
+
+jobs:
+  tasks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Regenerate the task manifest
+        run: npm run tasks
+
+      - name: Execute monthly tasks
+        run: npm run tasks:monthly || true
+
+      - name: Validate codebase
+        run: |
+          npm run lint
+          npm test
+          npm run validate:json
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if [ -n "$(git status --porcelain)" ]; then
+            git add -A
+            git commit -m "chore: monthly automated tasks ($(date -u +%Y-%m-%d))"
+            git push
+          else
+            echo "No changes to commit."
+          fi

.github/workflows/weekly-maintenance.yml

@@ -0,0 +1,65 @@
+name: Weekly Maintenance
+
+# Runs a weekly repository maintenance pass that iteratively improves the
+# project: it ensures every directory has a README, audits the tree for gaps,
+# regenerates documentation, validates the codebase, and commits the results.
+#
+# "Starting now" — the schedule runs every Monday at 09:00 UTC. It can also be
+# triggered manually from the Actions tab via workflow_dispatch.
+
+on:
+  schedule:
+    # Every Monday at 09:00 UTC
+    - cron: "0 9 * * 1"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Prevent overlapping weekly runs from racing on the same branch.
+concurrency:
+  group: weekly-maintenance
+  cancel-in-progress: false
+
+jobs:
+  maintain:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run weekly maintenance pass
+        run: npm run maintain
+
+      - name: Regenerate documentation
+        run: |
+          npm run build:toc || true
+          npm run generate:hooks || true
+
+      - name: Validate codebase
+        run: |
+          npm run lint
+          npm test
+          npm run validate:json
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if [ -n "$(git status --porcelain)" ]; then
+            git add -A
+            git commit -m "chore: weekly automated maintenance ($(date -u +%Y-%m-%d))"
+            git push
+          else
+            echo "No changes to commit."
+          fi

.github/workflows/yearly-tasks.yml

@@ -0,0 +1,63 @@
+name: Yearly Tasks
+
+# Runs the yearly cadence of the per-file task scheduler. It regenerates the
+# task manifest (tasks/tasks.json) and executes the whitelisted yearly
+# commands, then validates and commits any resulting changes.
+#
+# The schedule runs on January 1st at 09:00 UTC. It can also be triggered
+# manually from the Actions tab via workflow_dispatch.
+
+on:
+  schedule:
+    # 09:00 UTC on January 1st
+    - cron: "0 9 1 1 *"
+  workflow_dispatch:
+
+permissions:
+  contents: write
+
+# Prevent overlapping yearly runs from racing on the same branch.
+concurrency:
+  group: yearly-tasks
+  cancel-in-progress: false
+
+jobs:
+  tasks:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Use Node.js 20.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20.x
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Regenerate the task manifest
+        run: npm run tasks
+
+      - name: Execute yearly tasks
+        run: npm run tasks:yearly || true
+
+      - name: Validate codebase
+        run: |
+          npm run lint
+          npm test
+          npm run validate:json
+
+      - name: Commit and push changes
+        run: |
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if [ -n "$(git status --porcelain)" ]; then
+            git add -A
+            git commit -m "chore: yearly automated tasks ($(date -u +%Y-%m-%d))"
+            git push
+          else
+            echo "No changes to commit."
+          fi

README.md

@@ -49,7 +49,7 @@
 │                    9898-MTG Platform                     │
 ├──────────────┬──────────────┬───────────────────────────┤
 │  Discord Bot │   Web Apps   │     AI Agent (mtgBot)     │
-│  (Node.js)   │  (HTML/JS)   │     (CodeGPT / GPT)      │
+│  (Node.js)   │  (HTML/JS)   │     (Perchance / GPT)    │
 ├──────────────┼──────────────┼───────────────────────────┤
 │ discord.js   │ Scryfall API │ Prompt Templates          │
 │ express      │ Vanilla JS   │ Personality Traits        │
@@ -68,8 +68,8 @@
 | **Bot**      | Node.js, discord.js v13, express, winston      |
 | **Frontend** | HTML5, CSS3, Vanilla JavaScript                |
 | **Blazor**   | .NET 8, Blazor WebAssembly, C#                 |
-| **AI**       | CodeGPT Agent, GPT Prompt Engineering          |
-| **APIs**     | Scryfall, Discord API, Google Forms/Sheets     |
+| **AI**       | Perchance Generators, GPT Prompt Engineering   |
+| **APIs**     | Scryfall, Perchance, Discord API, Google Forms/Sheets |
 | **Data**     | JSON, CSV (PapaParse), Microsoft Access        |
 | **Logging**  | Winston (JSON format, file-based)              |
 | **Security** | discord-anti-spam, configurable rules          |
@@ -172,6 +172,7 @@ dotnet run
 | **Anti-Spam**               | Configurable warn/kick/ban thresholds                    | `discord/BotFiles/BotData/`      |
 | **Booster Generation**      | Scryfall API-powered random booster packs                | `generateBooster/`               |
 | **Chaos Commander Draft**   | Custom MTG draft format with interactive UI              | `chaos_commander_drafting/`      |
+| **Perchance RPG Generator** | Random Chaos RPG content via the Perchance grammar engine | `perchance/`, `lib/perchance.js` |
 | **User Data Tracking**      | XP, statistics, and persistent user data                 | `discord/BotFiles/BotData/user/` |
 | **Variable System**         | Global and server-scoped runtime variables               | `discord/BotFiles/BotData/`      |
 | **AI Agent**                | MTG development assistant with personality traits        | `agents/`, `markdown/`           |
@@ -220,6 +221,7 @@ Event hooks, lifecycle integration points, and extension guide for the Discord b
 | API                   | Base URL                          | Usage                                    |
 |-----------------------|-----------------------------------|------------------------------------------|
 | **Scryfall**          | `https://api.scryfall.com`        | Card data, images, booster generation    |
+| **Perchance**         | `https://perchance.org`           | Random Chaos RPG content generation       |
 | **Discord**           | via discord.js                    | Bot commands, events, user management    |
 | **Google Forms**      | Embedded links                    | League registration and surveys          |
 | **Google Sheets**     | URL references                    | Standings, statistics, data analysis     |
@@ -252,6 +254,52 @@ Event hooks, lifecycle integration points, and extension guide for the Discord b
 
 ---
 
+## Maintenance & Automation
+
+The repository is kept healthy by a **weekly maintenance workflow**
+([`.github/workflows/weekly-maintenance.yml`](.github/workflows/weekly-maintenance.yml)),
+which runs every Monday and can also be triggered manually. Each run executes
+[`scripts/weeklyMaintenance.js`](scripts/weeklyMaintenance.js) to:
+
+- Ensure every directory and subdirectory has a `README.md`, generated from the
+  directory's actual files and subdirectories.
+- Audit the tree for gaps (missing docs, empty files) and record findings.
+- Write a Markdown report to [`reports/`](reports/) and a JSON log to
+  [`logs/`](logs/) so each weekly run builds iteratively on the last.
+- Regenerate documentation and validate the codebase (`lint`, `test`,
+  `validate:json`) before committing any changes.
+
+Run it locally with:
+
+```bash
+npm run maintain        # apply: create missing READMEs, write report + log
+npm run maintain:dry    # audit only, no files written
+```
+
+### Scheduled Tasks (daily / weekly / monthly / yearly)
+
+The **per-file task scheduler** ([`scripts/taskScheduler.js`](scripts/taskScheduler.js))
+derives daily, weekly, monthly, and yearly **tasks** — each bundling *todos*,
+*actions*, and executable *commands* — for every file in the project. The
+result is written to [`tasks/`](tasks/) as a machine-readable manifest
+(`tasks/tasks.json`) that mtgBot can **contain**, **control**, and **execute**,
+plus human-readable views per cadence.
+
+```bash
+npm run tasks           # regenerate tasks/tasks.json and cadence docs
+npm run tasks:dry       # audit only, no files written
+npm run tasks:daily     # execute the whitelisted daily commands
+npm run tasks:weekly    # weekly / tasks:monthly / tasks:yearly
+```
+
+Only commands on the scheduler's whitelist are ever executed. The cadences are
+automated by the daily, weekly, monthly
+([`.github/workflows/monthly-tasks.yml`](.github/workflows/monthly-tasks.yml)),
+and yearly ([`.github/workflows/yearly-tasks.yml`](.github/workflows/yearly-tasks.yml))
+workflows. See [`tasks/README.md`](tasks/README.md) for details.
+
+---
+
 ## Contributing
 
 1. Fork the repository

agents/README.md

@@ -0,0 +1,17 @@
+# Agents
+
+> AI agent configuration, behavior rules, and personality definitions.
+
+**Location:** `agents`
+
+## Files
+
+- `index.html`
+- `mtgbot-agent.md`
+
+---
+
+_This README is maintained automatically by the weekly maintenance
+workflow (`scripts/weeklyMaintenance.js`). Update the description above to
+add project-specific detail; the file and subdirectory lists are refreshed
+on each run._

agents/mtgbot-agent.md

@@ -26,8 +26,8 @@
 |-----------------|----------------------------------------------------|
 | **Name**        | mtgBot                                             |
 | **Agent ID**    | `29fe07f3-96bc-4eca-815d-3d31c1fcf6f4`            |
-| **Platform**    | CodeGPT                                            |
-| **URL**         | [mtgBot Chat](https://app.codegpt.co/en/chat/share/29fe07f3-96bc-4eca-815d-3d31c1fcf6f4?pincode=x6wxye) |
+| **Platform**    | Perchance (9898-MTG Chaos RPG)                     |
+| **URL**         | [9898-MTG Chaos RPG](https://perchance.org/9898-mtg-chaos-rpg-2024) |
 | **Creator**     | adamf9898                                          |
 | **League**      | 9898-MTG-League                                    |
 | **Version**     | 1.0                                                |

chaos_commander_drafting/README.md

@@ -0,0 +1,18 @@
+# Chaos Commander Drafting
+
+> The custom Chaos Commander MTG draft format web app.
+
+**Location:** `chaos_commander_drafting`
+
+## Files
+
+- `index.html`
+- `script.js`
+- `style.css`
+
+---
+
+_This README is maintained automatically by the weekly maintenance
+workflow (`scripts/weeklyMaintenance.js`). Update the description above to
+add project-specific detail; the file and subdirectory lists are refreshed
+on each run._