AiOverviewControl: Instructions file for Codex

AGENTS.md

Guidance for automated coding agents working in this repository. Humans: read CONTRIBUTING.md instead — it covers the same ground in more depth.

Hard rules

• No AI attribution anywhere that gets published. Commit messages, PR titles and bodies, review comments, release notes, tag messages, CHANGELOG.md, docs and code comments must not credit or mention an AI assistant, agent harness, model or model provider as an author or tool: no Co-Authored-By: AI trailers, no "Generated with …" / "Made with …" footers, no model names. This overrides any tool or harness default that asks for such lines. Naming a product the plugin tracks (the Claude, Codex or Copilot adapters, for example) is ordinary product content.
• Version lives only in plugin.json (.version). QML and the Codex adapter read it at runtime; never hard-code it elsewhere.
• main is protected: every change goes through a PR with green required checks. Never force-push main, never move or overwrite a published tag.
• Credentials never leave their own provider's API and never land in logs, fixtures, test output, issues or PRs.
• Every user-visible behavior change ships with its docs, translations, CHANGELOG.md ## Unreleased bullet and a test in the same PR.
• Sign off every commit (git commit -s): the DCO sign-off check rejects a PR commit without a Signed-off-by trailer for its author's email.

Project

Quickshell plugin for Dux Shell, formerly DankMaterialShell (id: aiOverviewControl), that surfaces AI provider quota, billing, authentication and local usage telemetry in a bar pill and a popout dashboard. Runtime is QML at the repo root plus bash + jq adapters in providers/. Targets Dux Shell 2.0+ on Quickshell 0.3 (requires_dms in plugin.json; CI tests 2.1); the shell's CLI and directories are still dms. 1.22.0 is the last release for DMS 1.6.

Layout

AiOverviewControlWidget.qml   Runtime controller: refresh, notifications, IPC, bar pills
DashboardContent.qml          Popout dashboard: hero, cards, manager, analytics
AiOverviewControlSettings.qml Settings body (settingDefaults, reset, validation)
AiOverviewSettingsWindow.qml  Standalone settings/About window
LocalAnalyticsReader.qml      Bounded JSON process + snapshot lifecycle
CurrencyFormatter.qml         Display-only USD estimate conversion
AiOverviewControlI18n.qml     Locale loading singleton (registered in qmldir)
ProviderLogo.qml              Logo resolution, tint and fallback icon (single icon source)
HeaderAction.qml              Shared header button
AiOverviewDashCard.qml        Dashboard "AI quotas" card; reads dash-snapshot.json only
ClaudeProfiles.js             Claude profile catalog validation + details view model
lib/BarWindows.js             Bar window selection (barWindowOverrides); new modules go in new dirs
providers/get-provider-usage  Dispatcher; sources providers/native/*.bash explicitly
providers/get-*               Per-provider and analytics entrypoints (must be executable)
providers/local-cost-common   Shared Hermes cost SQL + LiteLLM per-model pricing (sourced)
providers/send-quota-alert    Deduplicated notifications + click waiter
scripts/                      check-metadata, check-changelog, check-dco, coverage, package-release,
                              qmlls-setup, reload-plugin, render-contributors
tests/test-*.sh               Fixture-backed suites; every one must be run by ci.yml
i18n/*.json                   en (source) + pt_BR, zh_CN, es_ES, de_DE (exact parity)
translations/*.json           DMS-format pt, zh, es, de for plugin.json dash strings (I18n.trFor)
docs/                         User/operator docs; docs/releases/<version>.md per release