📖 User Guide — Darkstar Alliance Bot
Command prefix: !
How to read this guide
Every command listed below starts with!followed by a group name and then a subcommand (e.g.!war counter).
Top-level commands (no group) are marked with (top-level).
Arguments in<angle brackets>are required;[square brackets]are optional.
Access model (how permissions really work)
- Supreme Admin ID has global bypass in most systems.
- Server owner and users with Discord Administrator permission bypass many category checks.
- Category permissions are managed by
!role add_role/!role add_guild_roleand checked through:super_admin,internal,military,foreign,economy,government,member,salary_admin,leader. - Some commands are strictly Supreme Admin only even if you are admin.
1) Documents & Website Access
Group prefix:
!docs
Member document commands
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!docs |
!docs |
Darkstar member/doc rank ≥ member | Shows docs command help. | Access denied if not a member. |
!docs all_docs (list) |
!docs all_docs |
Darkstar member/doc rank ≥ member | Lists available docs you can access. | This command is only available to Darkstar Alliance members. |
!docs doc (get, document) |
!docs doc <id_or_code> |
Darkstar member/doc rank ≥ member | Generates a secure DM link for one document. Deletes command message in guild. | Missing identifier, doc not found, no DM permission, insufficient tier. |
!docs select_doc (select, choose) |
!docs select_doc |
Darkstar member/doc rank ≥ member | Opens dropdown selector and sends secure access link flow. | Access denied, no docs available. |
!docs reload_docs |
!docs reload_docs |
internal |
Reloads docs from documents/. |
Access denied. |
!docs dashboard |
!docs dashboard |
None | Sends the main website dashboard link. | — |
!docs guide |
!docs guide |
None | Sends the public /guide URL. |
— |
Admin document commands
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!docs admin_panel |
!docs admin_panel |
internal permission |
Creates 6h admin token and DMs links for /admin and /admin/dms. |
Insufficient permissions, DM blocked. |
!docs set_doc_access |
!docs set_doc_access <id_or_code> <admin\|government\|member> |
internal |
Persists access tier on a document. | Usage error, invalid tier, document not found, DB failure. |
!admin set_website_access |
!admin set_website_access @user <government\|member> |
Supreme Admin only | Sets website access level in DB (website_user_access). |
Invalid level, DB error. |
2) Registration & Alliance Binding
Group prefix:
!reg
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!reg register |
!reg register <nation_id> |
Any member (or guild member role if configured) |
Verifies nation via P&W API, ensures no conflicting link, saves Discord↔nation link. | Nation not in alliance, nation already linked, DB unavailable. |
!reg link |
!reg link |
super_admin |
Bulk matches alliance nations to Discord members and creates/updates links. | Access denied, DB not configured, fetch failures. |
!reg debug_link |
!reg debug_link |
super_admin |
Shows matching diagnostics for Discord names vs P&W Discord fields. | Access denied, API failure. |
!reg set_guild_alliance |
!reg set_guild_alliance <alliance_id> |
super_admin + caller must have linked nation in that alliance |
Binds this Discord server to one alliance in server_configs. |
No linked nation, membership verification failed, DB save failed. |
3) Resource Requests
Group prefix:
!req
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!req request_grant |
!req request_grant [reason] |
Darkstar member role | Opens interactive resource request flow and posts reviewable request. | Not member role, nation not linked. |
!req request |
!req request <reason> |
Darkstar member role | Legacy text-entry path to same interactive request flow. | Not member role, nation not linked. |
!req request_wc |
!req request_wc <percentage> |
Darkstar member role | Calculates personal shortages to target 1–110% readiness, posts request embed and reviewer buttons. |
Invalid percentage, nation not linked, invisible resources, not in alliance. |
Reviewer actions on request embeds
- Grant Sent / Deny / Delay / Copy Command buttons require one of:
internal,military,economy. - Side effects: updates status in embed, pins/unpins delayed requests, notifies requester (channel mention or DM fallback).
4) Stockpile / Warchest / Build Monitoring
Group prefix:
!monitor
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!monitor stockpile_check |
!monitor stockpile_check |
None (currently unrestricted) | Runs immediate stockpile check and posts alert embed; pings @everyone if deficiencies exist. |
API errors. |
!monitor warchest_audit |
!monitor warchest_audit |
None (currently unrestricted) | Runs immediate warchest audit and posts summary + secure report link. | API errors. |
!monitor build_audit |
!monitor build_audit |
None (currently unrestricted) | Runs immediate build audit and posts summary + build report link. | API/build fetch errors. |
!monitor stockpile_debug |
!monitor stockpile_debug |
super_admin |
API/env diagnostics and quick health checks. | Access denied, API errors. |
!monitor debug_nation |
!monitor debug_nation [nation_id] |
Own nation or super_admin |
Dumps P&W nation debug data including alliance/resource visibility checks. | Unauthorized for other nation, bad nation id. |
!monitor debug_discord |
!monitor debug_discord |
super_admin |
Shows Discord field coverage from P&W alliance data. | Access denied, API errors. |
5) War Tracking & Countering
Group prefix:
!war
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!war counter |
!war counter <nation_id_or_link> |
None | Generates counter list for target nation and paginated embeds; adds action view on final page. | Bad link format, target not found, tracker not initialized. |
!war war_status |
!war war_status |
None | Shows monitored alliances/channels and tracker cache status. | — |
!war test_counter |
!war test_counter [attacker_score=10000] |
super_admin |
Generates sample counter list for a score. | Access denied, no eligible counters, tracker unavailable. |
!war war_debug |
!war war_debug [nation_id] |
super_admin |
Debugs filtering/eligibility details for one nation or full alliance overview. | Access denied, nation not found / debug errors. |
!war turret_threshold |
!war turret_threshold [value] |
military |
View or set the turret probability threshold (0–100). Omit value to show current setting. |
Requires military permission, value out of range. |
!war logs |
!war logs [limit=25] |
military or leader |
Shows recent counter operations for this guild — one embed per attacker, listing all dispatched counters and their real-time status. | Requires military or leader permission, no logs found. |
!war reliability |
!war reliability [@user] |
None | Shows global and hour-specific counter reliability scores for yourself or a mentioned member. | — |
!war set_warcost_channel |
!war set_warcost_channel [#channel] |
military or leader |
Sets the channel where automatic war-cost reports are posted when wars end. Omit channel to use the current channel. | Requires permission, guild not set up. |
!war testwarcost |
!war testwarcost [hours=24] |
military or leader |
Manually fires war-cost embeds for every war that ended in the last N hours. Bypasses the deduplicate table and DMs a copy to the invoker. | No monitored alliances, API errors. |
!war testwarcostdm |
!war testwarcostdm |
military or leader |
DMs yourself both war-cost embed formats (counter and non-counter) for visual testing without real data. | DMs blocked, WarCost cog not loaded. |
!war test_ma_alert |
!war test_ma_alert |
military or leader |
DMs yourself the current military-advantage (MA) alert snapshot for the guild's alliance. | No alliance configured, DMs blocked, API errors. |
!admin set_war_alerts_channel |
!admin set_war_alerts_channel [#channel] |
Supreme Admin only | Sets or clears guild war-alerts channel in DB. Omit channel to clear. | Only the Supreme Admin can use this command. |
6) Blitz Coordinator (!blitz)
MilCom role required (blitz command group checks configured milcom role IDs).
| Command | Syntax | What it does | Common errors |
|---|---|---|---|
!blitz |
!blitz |
Shows full blitz usage help and option syntax. | — |
!blitz generate |
!blitz generate <att_ids> <def_ids> --sheet <url> [--priority <ids>] [--priority-att <ids>] [--split <aa:id:pct,...>] [--max-off <int>] [--concentration <float>] [--easy] [--min-att <int>] [--use-latest-poll] |
Fetches nations, scores targets, allocates attackers, writes plan to Google Sheet. | Missing --sheet, invalid IDs/flags, API/Sheet failures, access denied. |
!blitz validate |
!blitz validate <sheet_url> |
Validates sheet structure and allocation issues. | Invalid URL / sheet read errors. |
!blitz prep |
!blitz prep <sheet_url> [--timestamp <epoch_or_<t:...>>] |
Sends readiness poll/DM prep flow. | Validation or DM errors. |
!blitz poll-status |
!blitz poll-status |
Shows latest prep poll yes/no/pending. | No recent poll. |
!blitz send |
!blitz send <sheet_url> [--dm] [--mail] [--announce <channel_id>] [--timestamp <epoch_or_<t:...>>] [--use-poll] |
Sends assignment orders via DM/mail and optional announce channel. | No destination mode / invalid options / send failures. |
!blitz status |
!blitz status <sheet_url> |
Checks declaration/assignment progress. | Sheet parse/read failures. |
ID rules: aa:<id> for alliances, plain integers for nations, optional city filter like aa:10259(c10-c20).
7) Mass DM
Top-level commands (no group prefix)
Requires: internal or military (global or guild-scoped), or super_admin, or guild owner/admin, or Supreme Admin.
| Command | Syntax | What it does | Common errors |
|---|---|---|---|
!mass_dm |
!mass_dm |
Opens role picker + compose modal + confirmation UI, then sends DMs in batches. | Access denied, no eligible roles. |
!quick_dm |
!quick_dm @Role <message> |
Immediate mass DM without confirmation UI. | Access denied, empty message, role has no members. |
!dm_history |
!dm_history |
Shows last campaign summaries and failures. | Access denied, no campaigns yet. |
Rate limits: max 5 concurrent DMs, 1.5s batch delay.
8) Role Management
Group prefix:
!role
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!role add_role |
!role add_role @Role <category> |
Super admin manager (super_admin/owner/admin/Supreme) |
Adds global role-category mapping. | Invalid category, DB error. |
!role remove_role |
!role remove_role @Role <category> |
Same as above | Removes global role-category mapping. | Invalid category, DB error. |
!role list_roles |
!role list_roles |
Same as above | Lists global role-category mappings. | Permission denied. |
!role add_guild_role |
!role add_guild_role @Role <category> |
Same as above (in guild) | Adds guild-scoped role-category mapping. | Invalid category, DB error. |
!role remove_guild_role |
!role remove_guild_role @Role <category> |
Same as above (in guild) | Removes guild-scoped role-category mapping. | Invalid category, DB error. |
!role list_guild_roles |
!role list_guild_roles |
Same as above (in guild) | Lists guild-scoped mappings. | Must be in server / permission denied. |
9) Salaries
Group prefix:
!salary
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!salary |
!salary |
None | Shows salary command help. | — |
!salary calculate_salaries |
!salary calculate_salaries |
super_admin |
Computes gov salaries + MMR bonuses and outputs transfer commands. | Access denied, missing audit datasets, API/DB errors. |
!salary set_channel |
!salary set_channel #channel |
super_admin |
Overrides the salary output channel for this guild. | Access denied, must be used in a guild. |
!salary gov_linking |
!salary gov_linking |
super_admin |
Shows which gov-role holders are linked to nations. | Access denied. |
!salary gov_roles |
!salary gov_roles |
super_admin |
Displays current gov role assignments and counts. | Access denied. |
!salary update_government |
!salary update_government |
super_admin |
Shows role config and guidance for updating salary roles. | Access denied. |
!salary test_mmr |
!salary test_mmr [nation_id] |
super_admin |
Tests one nation's MMR eligibility/bonus computation. | No linked nation when omitted, access denied. |
10) Channel Audit
Group prefix:
!audit
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!audit channels |
!audit channels |
super_admin |
Scans city-range categories, validates nation links, renames/moves misplaced channels. | Missing permissions to move/rename channels, nation parse/API failures. |
!audit set_archive |
!audit set_archive <category> |
super_admin |
Sets the Discord category to which misplaced/inactive channels are moved during audits. | Access denied, not a valid category. |
!audit clear_archive |
!audit clear_archive |
super_admin |
Removes the configured archive category. | Access denied, nothing configured. |
!audit fa |
!audit fa <cat_id1>[,cat_id2,...] |
Supreme Admin / bot owner | Analyses FA (foreign affairs) channels using DeepSeek AI, attributes each to an alliance, and appends a diplomatic analysis to that alliance's FA notes. | DeepSeek key not configured, category not found, API errors. |
11) Simulation (!sim) and Profiles (!profile)
Simulation
Group prefix:
!sim
All !sim commands are currently Supreme Admin only.
| Command | Syntax | What it does | Common errors |
|---|---|---|---|
!sim start |
!sim start <profile_name> [position\|none] [rng=on\|off] |
Enables simulation in current text channel with the chosen profile and optional position/RNG event. Default model: Gemini Flash 3. | Not server text channel, no permission, profile missing/malformed, disabled due to missing keys. |
!sim stop |
!sim stop |
Disables simulation in current channel. | No permission. |
!sim model |
!sim model <flash\|glm> |
Changes model tier for current channel: flash = Gemini Flash 3, glm = GLM 5.1. |
Invalid tier, missing key for chosen model, channel not configured. |
!sim status |
!sim status |
Shows current simulation state, active profile, position, model, and RNG event for this channel. | No permission. |
!sim channels |
!sim channels |
Lists all configured simulation channels across all guilds (enabled and disabled). | No permission. |
Profiles
Group prefix:
!profile
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!profile list |
!profile list |
Supreme Admin | Lists saved simulation profiles and their sizes. | Permission denied. |
!profile show |
!profile show <name> |
Supreme Admin | Shows raw profile content (truncated to 1800 chars). | Profile missing. |
!profile export |
!profile export <name> |
Supreme Admin | Exports profile as a .txt file. |
Profile not found. |
!profile import |
!profile import <name> (attach a text file) |
super_admin manager |
Validates and imports/overwrites profile from the attached file. | Missing attachment, file too large, name has spaces, DB save fail. |
!profile set |
!profile set <name> (attach a text file) |
super_admin manager |
Alias for !profile import — sets or replaces a profile's content from an attached file. |
Same as import errors. |
!profile delete |
!profile delete <name> |
super_admin manager |
Deletes a profile permanently. | Not found, DB error. |
!profile purge |
!profile purge |
Supreme Admin only | Deletes all profiles. This cannot be undone. | No profiles to purge. |
12) Beige Snipe (!beigesnipe)
Officer requirement: military permission for most subcommands.
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!beigesnipe |
!beigesnipe |
None | Shows subcommand help. | — |
!beigesnipe subscribe |
!beigesnipe subscribe |
Linked nation required | Opt-in to personal beige-snipe DMs in this guild. | Must link nation first. |
!beigesnipe unsubscribe |
!beigesnipe unsubscribe |
None | Opt-out of DMs. | DB unsubscribe failure. |
!beigesnipe alliance |
!beigesnipe alliance <id[,id...]> |
military |
Imports all nations from one/more alliances into watchlist. | Invalid IDs, API key missing, API errors. |
!beigesnipe add |
!beigesnipe add <nation_id> |
military |
Adds one nation target. | Nation not found/API error. |
!beigesnipe sheet |
!beigesnipe sheet + attach .csv/.txt |
military |
Imports nation IDs and aa: alliance IDs from file. |
Missing/oversized file, download failure, no parseable IDs. |
!beigesnipe list |
!beigesnipe list |
military |
Shows active watchlist with beige status. | Empty watchlist. |
!beigesnipe remove |
!beigesnipe remove <nation_id> |
military |
Removes one target from watchlist. | Target not found. |
!beigesnipe clear |
!beigesnipe clear |
military |
Clears entire watchlist with button confirmation. | Cancel/timeout. |
!beigesnipe status |
!beigesnipe status |
military |
Shows monitor stats, channel config, enabled state. | — |
!beigesnipe setchannel |
!beigesnipe setchannel [#channel] |
military |
Sets/clears guild-wide alerts channel. | Permission or DB failures. |
!beigesnipe refresh |
!beigesnipe refresh |
military |
Runs one monitor cycle immediately. | API/processing failures. |
!beigesnipe activate |
!beigesnipe activate |
military |
Enables monitoring for guild. | DB failures. |
!beigesnipe deactivate |
!beigesnipe deactivate |
military |
Disables monitoring for guild. | DB failures. |
13) Internal Affairs Pipeline (!ia)
Group prefix:
!ia
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!ia |
!ia |
None | Shows IA help/subcommands. | — |
!ia setup |
!ia setup <key> <value> |
admin category |
Sets IA config value. | Unknown key. |
!ia settings |
!ia settings |
admin category |
Shows IA settings + guild alliance + PNW key status. | — |
!ia status |
!ia status [@member] |
Guild-only, no extra role | Shows one applicant or list of active applicants. | No IA record, no active applicants. |
!ia stats |
!ia stats |
government |
Shows pipeline statistics and rates. | DB errors. |
!ia audit |
!ia audit |
government |
Runs applicant audit against current P&W data and posts alert embeds. | Audit failed: ... |
!ia colorcheck_test |
!ia colorcheck_test |
government |
DMs the caller a simulated color-misalignment embed showing what a member would receive if they were on the wrong color. Useful for testing the alert before enabling it. | Missing alliance binding, PNW key, DMs blocked. |
!ia colorcheck_overview |
!ia colorcheck_overview |
government |
Posts a paginated overview of all alliance nations and their current color alignment status (✅ aligned / ❌ misaligned), sorted with misaligned nations first. A button lets you trigger re-alignment messages. | Missing alliance binding, API failures. |
!ia activity_overview |
!ia activity_overview |
government |
Posts a paginated list of all (non-applicant) alliance members sorted by activity tier: 🟢 active within 2 days, 🟠 active 2–5 days ago, 🔴 inactive >5 days, ❔ unknown. | Missing alliance binding, API failures. |
!ia academy |
!ia academy @member |
government |
Marks applicant COMPLETE. | No IA record / already complete. |
!ia escalate |
!ia escalate @member <reason> |
government |
Sets status ESCALATED and appends reason note. | No IA record. |
!ia flag |
!ia flag @member <flag_type> |
government |
Adds boolean flag in applicant record. | No IA record. |
!ia note |
!ia note @member <note> |
government |
Appends timestamped note. | No IA record. |
!ia override |
!ia override @member <status> |
admin |
Force-sets status (supports terminal states). | Unknown status / no IA record. |
!ia reset |
!ia reset @member |
admin |
Deletes one applicant record. | No IA record. |
!ia purge |
!ia purge <all\|applied\|terminal\|inactive> |
admin |
Bulk deletes records by target group. | Unknown target. |
14) Intelligence (!intel) and Oracle (!oracle)
Intelligence commands
Group prefix:
!intel
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!intel analysis |
!intel analysis <channel_id> [additional_notes] |
Government/intel-role check | Builds intelligence report from join-ticket* channel (+ optional backroom), writes file, sends in channel/DM/archive. |
Cooldown active (10s), invalid channel, wrong name/category, missing keys, no messages, permission errors. |
!intel stats |
!intel stats |
Government/intel-role check | Shows session and guild report/token/cost stats. | — |
!intel set_backroom |
!intel set_backroom <channel_id> |
Bot owner | Sets backroom channel for context. | Must be in server. |
!intel clear_backroom |
!intel clear_backroom |
Bot owner | Clears backroom channel. | Must be in server. |
!intel set_pnw_key |
!intel set_pnw_key <key> |
Bot owner | Stores global PnW key in DB and deletes invoking message if possible. | — |
!intel set_anthropic_key |
!intel set_anthropic_key <key> |
Bot owner | Stores global Anthropic key in DB and deletes invoking message if possible. | — |
!intel set_analysis_category |
!intel set_analysis_category <category_id> |
Bot owner | Restricts analysis targets to one category ID. | Must be in server. |
!intel set_reports_channel |
!intel set_reports_channel <channel_id> |
Bot owner | Sets guild archive channel for reports. | Must be in server. |
!intel set_allowed_channels |
!intel set_allowed_channels <channel_id> [channel_id ...] |
Bot owner | Restricts where !intel analysis can be invoked. |
Must be in server. |
!intel set_intel_role |
!intel set_intel_role <role_id\|@role\|exact_name> |
Bot owner | Sets custom role gate for intelligence commands. | Role not found by ID/name. |
!intel clear_intel_role |
!intel clear_intel_role |
Bot owner | Reverts to default Government fallback role gate. | Must be in server. |
Oracle / document-assistant commands
Group prefix:
!oracle
The Oracle is an AI assistant that answers questions about alliance documents. It listens passively in configured channels and responds to messages that are not bot commands.
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!oracle |
!oracle |
Member access check | Shows Oracle command help. | No permission. |
!oracle remove |
!oracle remove <doc_name> |
internal in guild |
Deletes all chunks for a named document from the vector store. | No permission. |
!oracle clear |
!oracle clear |
Member access check | Clears your Oracle conversation history. | No permission. |
!oracle tokens |
!oracle tokens |
Member access check | Shows token/cost usage embed for your current session. | No permission. |
!oracle set_key |
!oracle set_key <key> |
Bot owner | Stores DeepSeek API key in DB and refreshes client. Deletes invoking message. | — |
!oracle set_pnw_key |
!oracle set_pnw_key <key> |
Bot owner | Stores the P&W API key in DB for Oracle lookups. Deletes invoking message. | — |
!oracle add_channel |
!oracle add_channel #channel |
internal in guild |
Adds a channel to the per-guild Oracle allowed-channels list. | No permission, channel not found. |
!oracle remove_channel |
!oracle remove_channel #channel |
internal in guild |
Removes a channel from the per-guild Oracle allowed-channels list. | No permission, channel not in list. |
!oracle channels |
!oracle channels |
Member access check | Lists all configured Oracle allowed channels for this guild. | No permission. |
15) Admin Utility
Group prefix:
!admin
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!admin sync_dms |
!admin sync_dms |
super_admin in guild |
Retro-scans bot DM history into dm_logs. |
No permission, DB URL missing, DB error. |
!admin set_war_alerts_channel |
!admin set_war_alerts_channel [#channel] |
Supreme Admin only | Sets or clears the war-alerts channel for this guild. Omit channel to clear. | Only Supreme Admin, guild not set up. |
!admin set_website_access |
!admin set_website_access @user <government\|member> |
Supreme Admin only | Sets website access level for a Discord user in DB. | Invalid level, DB error. |
16) Beige Cycle (!cycle)
Group prefix:
!cycle
The Beige Cycle system coordinates groups of alliance members to keep an enemy nation in beige (the "out of military" state in Politics & War) indefinitely. When a target's war ends and they would emerge from beige, the system automatically alerts a designated "finisher" to re-declare war before the opponent can rebuild.
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!cycle |
!cycle |
None | Shows beige cycle command help. | — |
!cycle status |
!cycle status [nation_id] |
None | Shows the active cycle group for a specific target, or lists all active groups. | No active group for given nation. |
!cycle list |
!cycle list [status] |
None | Lists cycle groups filtered by status. Default filter: active. Other values: compromised, closed, etc. |
No groups matching status. |
!cycle abort |
!cycle abort <nation_id> |
military |
Manually closes the active cycle group for a target and notifies the involved nations. | No active group, permission denied. |
!cycle reassign |
!cycle reassign <nation_id> <new_finisher_nation_id> |
military |
Changes the designated finisher for an active cycle group and DMs both the old and new finisher. | No active group, permission denied. |
!cycle resume |
!cycle resume <nation_id> |
military |
Resumes a compromised cycle group, setting it back to active. |
No compromised group, permission denied. |
!cycle dm |
!cycle dm <on\|off> |
None | Opts your Discord account in (on) or out (off) of beige cycle DM notifications. |
— |
Cycle test commands (!cycle test)
Subgroup for development and testing purposes. Requires
militaryor leader permission.
| Command | Syntax | What it does |
|---|---|---|
!cycle test trigger |
!cycle test trigger <nation_id> |
Simulates a new war event for a target nation, triggering cycle group creation. |
!cycle test engage |
!cycle test engage <group_id> |
Tests the engagement flow for a cycle group. |
!cycle test fire |
!cycle test fire <group_id> |
Tests the fire (final beige) logic for a cycle group. |
!cycle test sequence |
!cycle test sequence |
Runs through a full automated beige cycle test sequence. |
!cycle test rebuild |
!cycle test rebuild <group_id> |
Rebuilds a cycle group from current war data. |
!cycle test violation |
!cycle test violation |
Simulates a cycle violation event. |
!cycle test peace |
!cycle test peace <group_id> |
Tests the peace/war-end flow for a cycle group. |
!cycle test cleanup |
!cycle test cleanup |
Cleans up stale or test cycle records. |
!cycle test dryrun_dm |
!cycle test dryrun_dm <group_id> |
DMs the caller what the cycle DM messages would look like without sending to real members. |
!cycle test timing_unit |
!cycle test timing_unit |
Tests the beige-turn timing logic. |
17) Community Statistics (!stats)
Group prefix:
!stats
Tracks Discord message activity using a local message_log database table. Most commands require government or internal permission.
Note: Before statistics are meaningful, run
!stats backfillonce to populate historical data.
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!stats |
!stats |
None | Shows stats command help. | — |
!stats backfill |
!stats backfill |
government or internal |
Starts (or resumes) a full channel history backfill for this guild. Only one backfill can run at a time. | Already running. |
!stats channels |
!stats channels [days=30] |
government or internal |
Paginated table of all text channels sorted by activity (deadest first), showing last message age, messages/day rate, and unique authors. | Days out of range (1–365). |
!stats recommend |
!stats recommend |
government or internal |
Sends enriched channel data to Gemini Flash for AI-powered channel pruning recommendations. | Missing AI key, no data. |
!stats member_decay |
!stats member_decay [days=30] |
government or internal |
Lists members who were active 60 days ago but have gone silent in the last N days (retention triage). | Days out of range (1–180), no decay found. |
!stats new_member_engagement |
!stats new_member_engagement [duration] |
government or internal |
Engagement stats for members within an optional time window. Shows how many posted ≥ threshold messages ("engaged") vs. those who are "stuck". Duration formats: 30d, 180s, 1y, or omit for all-time. |
Parse error, no members found. |
!stats activity_heatmap |
!stats activity_heatmap [duration] |
government or internal |
Generates a PNG heatmap (hour × day-of-week) of message volume across the guild. Highlights the peak activity time slot. | matplotlib not installed, no data. |
!stats contributor_distribution |
!stats contributor_distribution [duration] |
government or internal |
Shows which authors generate what percentage of messages. Highlights the Pareto stat: what % of messages come from the top 10% of authors. Lists top-20 contributors. | No data. |
!stats channel_overlap |
!stats channel_overlap [duration] |
government or internal |
For each pair of active channels (≥3 unique authors), shows what % of users from channel A also post in channel B. | Not enough active channels. |
!stats conversation_depth |
!stats conversation_depth [#channel] |
government or internal |
Shows average messages per conversation burst and average participants per burst, per channel or across the whole guild. | No data. |
!stats tickets |
!stats tickets |
government or internal |
Shows ticket channel statistics (open counts, average age, etc.). | No ticket channels found. |
!stats inactive_tickets |
!stats inactive_tickets |
government or internal |
Lists ticket channels that have had no activity recently. | No inactive tickets. |
!stats community_recommend |
!stats community_recommend |
government or internal |
Sends combined community health data to Gemini Flash for a broader AI-powered activity recommendation. | Missing AI key, no data. |
Duration format: 30d = 30 days, 180s = 180 seconds (for testing), 1y = 1 year. Omit for all-time analysis.
18) Diplomas (!diploma)
Group prefix:
!diploma
The diploma system lets administrators create, officialise, and award digital diplomas to Discord members. Each diploma has a public web page and a unique 8-character ID.
Permission: All diploma commands require Discord administrator permission on the server.
| Command | Syntax | What it does | Common errors |
|---|---|---|---|
!diploma |
!diploma |
Shows diploma command help. | — |
!diploma create |
!diploma create <title> <subtitle> <from_line> <qr_url> |
Creates a new diploma, generates a preview image, stores it in DB with a random 8-char ID, and posts the image. Optionally attach a background PNG/JPG. | qrcode library not installed, image generation failure, no DB. |
!diploma register |
!diploma register <diploma_id> <description> |
Marks an existing diploma as official with a description, or creates a new one from an attached image and immediately officializes it. Public page is activated. | Diploma not found, image validation failure, DB error. |
!diploma send |
!diploma send <diploma_id> @user1 [user_id2 …] |
Awards a diploma to one or more users. Posts a confirmation embed and links the public diploma page. | Diploma not found, no recipients provided, already has diploma (skipped). |
!diploma import |
!diploma import <diploma_id> <YYYY-MM-DD> @user1 [user_id2 …] |
Imports historical award records with a specific date (back-dating). | Invalid date, diploma not found. |
!diploma list |
!diploma list |
Lists all diplomas in the database with their official/unofficial status. | No diplomas created. |
!diploma info |
!diploma info <diploma_id> |
Shows full diploma details: title, subtitle, description, status, creation date, and current recipients (up to 20 shown). | Diploma not found. |
!diploma delete |
!diploma delete <diploma_id> |
Deletes a diploma and all recipient records. | Diploma not found, permission denied. |
Public pages: Each diploma has a public page at https://obsidian-pnw.site/diplomas/<diploma_id>.
19) Ribbons (!ribbon)
Group prefix:
!ribbon
The ribbon system is identical in structure to the diploma system but uses a smaller "ribbon" format for less formal recognition. Ribbons use the same database and public web infrastructure.
| Command | Syntax | What it does | Common errors |
|---|---|---|---|
!ribbon |
!ribbon |
Shows ribbon command help. | — |
!ribbon create |
!ribbon create <title> <subtitle> <from_line> <qr_url> |
Creates a new ribbon with a generated image and stores it with a random 8-char ID. Optionally attach a background PNG/JPG. | qrcode library not installed, image generation failure, no DB. |
!ribbon register |
!ribbon register <ribbon_id> <description> |
Marks a ribbon as official with a description, or creates one from an attached image and immediately officializes it. | Ribbon not found, image validation failure, DB error. |
!ribbon send |
!ribbon send <ribbon_id> @user1 [user_id2 …] |
Awards a ribbon to one or more users. Already-awarded recipients are skipped. | Ribbon not found, no recipients provided. |
!ribbon import |
!ribbon import <ribbon_id> <YYYY-MM-DD> @user1 [user_id2 …] |
Back-dates ribbon awards with a specific historical date. | Invalid date, ribbon not found. |
!ribbon list |
!ribbon list |
Lists all ribbons in the database. | No ribbons created. |
!ribbon info |
!ribbon info <ribbon_id> |
Shows full ribbon details and current recipients. | Ribbon not found. |
!ribbon delete |
!ribbon delete <ribbon_id> |
Deletes a ribbon and all recipient records. | Ribbon not found, permission denied. |
Public pages: Each ribbon has a public page at https://obsidian-pnw.site/ribbons/<ribbon_id>.
20) War Cost (!warcost)
Top-level command (no group prefix)
| Command | Syntax | What it does | Common errors |
|---|---|---|---|
!warcost |
!warcost <war_id_or_url> [-d] |
Fetches a P&W war by ID (or URL with war=<id>) and displays a cost breakdown embed: unit losses, infrastructure damage, resource consumption, loot, and net cost at current market prices. Add -d flag for a detailed per-resource breakdown. If the war involves the guild's alliance, a reimbursement button is shown. Counter wars show an additional reimbursement policy note. |
Invalid war ID, PNW_API_KEY not configured, war not found, API error. |
Aliases: none.
Market prices: Uses the lowest active sell offers from P&W's market.
Embed colour: Green if the attacker spent less, red if the attacker spent more, grey if tied.
21) Revenue (!revenue)
Top-level command (no group prefix)
| Command | Syntax | What it does | Common errors |
|---|---|---|---|
!revenue |
!revenue <nation_id\|aa:<alliance_id>> |
Calculates the estimated net daily revenue for a single nation or an entire alliance. Breaks down city income, military upkeep, and trade activity into a resource-by-resource table. Accounts for radiation, color bonuses, and treasure bonuses. | Invalid target format, PNW_API_KEY not configured, no nations found, P&W API error. |
Aliases: !rev, !income.
Revenue components: city buildings income, military unit upkeep (subtracted), trade income.
Modifiers applied: color bloc turn bonus, radiation penalty, treasure bonus, domestic policy multipliers.
22) Forum Watcher (!news)
Group prefix:
!news
The Forum Watcher automatically polls the Politics & War forums RSS feeds and posts summarised articles as Discord embeds. It uses an AI model (HuggingFace) to generate readable summaries.
| Command | Syntax | Permission | What it does | Common errors |
|---|---|---|---|---|
!news |
!news |
None | Shows news command help. | — |
!news setchannel |
!news setchannel [#channel] |
internal |
Sets the channel where new forum articles are automatically posted. Omit channel to clear. | No permission, must be in a server. |
!news check |
!news check |
internal |
Manually triggers an RSS poll and posts any new articles found right now. | No channel configured, no new posts found. |
!news status |
!news status |
internal |
Shows current configuration: news channel, HuggingFace key status, poll interval, and all monitored RSS feeds. | No permission, must be in a server. |
!news test |
!news test |
internal |
Fetches the last 10 forum posts, runs the full AI article generation pipeline for each, and prints verbose output to the bot console. Also posts result embeds in the current channel. | No permission, AI key missing. |
Poll interval: Configurable (default: every few minutes).
RSS sources: Monitors multiple P&W forum sub-feeds (General, Announcements, etc.).
Automated Jobs
| Job | Schedule | What it does |
|---|---|---|
| Stockpile audit | Daily at 14:00 UTC | Runs !monitor stockpile_check automatically. |
| Warchest audit | Daily at 14:00 UTC | Runs !monitor warchest_audit automatically. |
| Build audit | Daily at 14:00 UTC | Runs !monitor build_audit automatically. |
| Salary calculation | Every 14 days | Runs !salary calculate_salaries for bi-weekly payroll. |
| IA cron/audit loop | Every 12 hours | Audits active applicants against P&W data; triggers color-check alerts. |
| War tracker WebSocket | Continuous | Listens to the P&W war events WebSocket for real-time alerts. |
| Beige snipe monitor | Continuous (per guild, when enabled) | Polls for target nations entering/leaving beige. |
| Beige cycle monitor | Continuous | Tracks active beige cycle groups and dispatches finisher DMs. |
| Forum watcher | Periodic | Polls P&W RSS feeds and posts new articles. |