feat(ms-ai-architect): add cross-OS scheduling templates (launchd/systemd/Windows) [skip-docs]

plugins/ms-ai-architect/scripts/kb-update/templates/README.md

@@ -0,0 +1,62 @@
+# ms-ai-architect KB-update scheduling templates
+
+These templates are consumed by `scripts/install-kb-cron.mjs` (added in
+Wave 4 / Step 11) which substitutes the documented placeholders and
+hands off to the platform's native scheduler. Do not edit a generated
+file directly — re-run the installer instead so the source-of-truth
+stays in this directory.
+
+## Files
+
+| File | Platform | Scheduler |
+|------|----------|-----------|
+| `com.fromaitochitta.ms-ai-architect.kb-update.plist` | macOS (Intel + Apple Silicon) | `launchctl` (per-user LaunchAgent) |
+| `ms-ai-architect-kb-update.service` | Linux | `systemctl --user` |
+| `ms-ai-architect-kb-update.timer` | Linux | `systemctl --user` (paired with the .service) |
+| `ms-ai-architect-kb-update.ps1` | Windows 10/11 | Task Scheduler via `Register-ScheduledTask` |
+
+## Placeholders
+
+All four templates share the same canonical placeholder set. The
+installer fills them in at install-time and writes the rendered file
+under the platform's scheduler directory.
+
+| Placeholder | Filled with | Source |
+|-------------|-------------|--------|
+| `{{NODE_BIN}}` | Absolute path to the `node` binary that should run the cron | `which node` (POSIX) / `where node` (Windows) at install-time |
+| `{{PLUGIN_ROOT}}` | Absolute path to the `plugins/ms-ai-architect/` directory | Resolved by the installer relative to itself |
+| `{{LOG_FILE}}` | Absolute path to the rotated log file | `getLogDir('ms-ai-architect') + '/kb-update.log'` (per `lib/cross-platform-paths.mjs`) |
+| `{{SCHEDULE_HOUR}}` | Cron-hour, 0-23 | Default `4`; overridable via `--schedule-hour` |
+| `{{SCHEDULE_MINUTE}}` | Cron-minute, 0-59 | Default `23`; overridable via `--schedule-minute` |
+| `{{SCHEDULE_DAY_OF_WEEK}}` | launchd Weekday integer (0=Sunday … 3=Wednesday) | Default `3` (Wednesday) |
+
+The systemd `.timer` and Windows `.ps1` use a literal `Wed`/`Wednesday`
+day name rather than `{{SCHEDULE_DAY_OF_WEEK}}` because their respective
+schedulers expect day-name strings, and the installer currently locks
+the day to Wednesday (per the brief's "weekly Wed" cadence). Changing
+the day requires editing the template — the installer does not yet
+expose a `--schedule-day` flag.
+
+## Install / uninstall
+
+The full install/uninstall flow is implemented by
+`scripts/install-kb-cron.mjs` (Wave 4 / Step 11). Run with `--help` for
+the current option set. The contract for all three platforms is "fires
+while the user is logged in" — there is no system-wide / sudo install
+path because Claude Code's keychain-bound auth dies in unattended
+contexts.
+
+## Why these specific schedulers
+
+- **launchd** is the only first-class scheduler on macOS; cron is a
+  thin user-facing alias. `RunAtLoad` is `false` so loading the job at
+  boot does not trigger an immediate Claude Code session.
+- **systemd `--user` units** keep the symmetry of "user-context only"
+  with launchd's LoginItem and Windows' `InteractiveToken`. The
+  `Persistent=true` setting on the timer ensures a missed run (laptop
+  asleep on Wednesday) fires on next boot rather than being skipped.
+- **Windows Task Scheduler** with `InteractiveToken` is the only logon
+  type that keeps the keychain unlocked, which is required for
+  subscription-auth Claude Code sessions.
+
+See `research/01-cross-os-scheduling.md` for the full background.