Development

Read the relevant sections before changing QML, JavaScript, configuration, tests, packaging, or runtime behavior. AGENTS.md defines project boundaries and required checks. The usage guide describes supported behavior; TODO.md owns remaining Linux/Plasma parity work. All code paths below are relative to the repository root.

Work from a checkout

Install make, Python 3, GNU gettext, and the Plasma runtime requirements in the README. The check suite also needs Qt 6 QML lint/test tools, ShellCheck, xmllint, and jq. The pinned CI workflow lists the complete test environment; package names vary by distribution.

make install builds and installs the curated .plasmoid archive. Tests and agent instructions are not installed. Reload Plasma after installing changed QML, using the runtime instructions. For an existing checkout, ./install.sh builds, installs, and restarts Plasma.

From this checkout, make update installs the latest immutable GitHub release using the bundled helper. It does not pull Git changes or install local edits. For those, use make install or ./install.sh. Release-package users can use the widget's update settings without a checkout.

Ownership and implementation

• contents/ui/main.qml owns applet processes, refresh/account coordination, selected state, configuration updates, and external effects. Its adapters supply the panel and popup.
• contents/ui/controllers/WidgetUpdateController.qml owns the widget updater's executable source, per-request nonce, captured install mode, timeout, queued install request, and retry/interval timers. It receives update settings and the last successful check timestamp. Its checkNow() entry point still respects disabled checks. Enabled startup still forces a check even with a recent saved timestamp, preserving the previous startup behavior. main.qml persists its status and successful-check signals and delivers its available/installed notifications, preserving the existing privacy and notification-deduplication rules. The module never reads the applet root or writes configuration. UpdateLogic.js keeps the pure scheduling and result decisions shared with settings.
• contents/ui/components/CompactRepresentation.qml renders the panel; FullRepresentation.qml in the same directory renders the popup. Components are presentation-only and receive normalized data plus an explicit parent API such as applet or configPage.
• contents/ui/configProviders.qml owns provider setup processes, prompts, configuration writes, and effects. Its pure protocol and command-planning modules live in contents/ui/config/.
• Pure applet modules live in contents/ui/*.js; their public interfaces have direct tests in tests/tst_*.qml. Configuration is declared in contents/config/main.xml and bound through cfg_* in config pages and Plasmoid.configuration at runtime.
• UsageCache.js reconciles failed usage snapshots and projects a bounded quota cache. main.qml owns context invalidation, configuration reads/writes, and stale notification suppression. Its minute timer expires retained measurements even when automatic refresh is disabled. Persisted records never bypass normalization.

The quota cache adapts the bounded stale reuse and background refresh patterns in RFC 5861; this is a local application policy, not an HTTP cache implementation. Failed retries preserve the original measurement time. The 24-hour retention limit applies in memory and on restore. The context fingerprint isolates CLI/configuration/account selections; it is not an integrity check or encryption. Cached JSON remains untrusted and is rebuilt from allowlisted, bounded fields, following OWASP input validation guidance. Omitting identities, credentials, paths, and provider prose follows OWASP's data minimization guidance. Persistence uses Plasma's existing configuration mapping; the restart smoke test allows its deferred save to complete before starting the second process. The first configuration-checksum callback also saves any successful usage that arrived before it, so startup persistence does not depend on a later refresh. It merges normalized cached providers missing from that early response through UsageCache.restore, preserving live results and marking only restored quotas as stale. A completed early refresh keeps its update label when no stale quotas remain. The restarted fixture delays CLI responses beyond the runner's maximum allowed scenario duration, proving that the second process displays persisted quotas. Quota freshness and service-status evidence are independent: retained rows never reach the notification planner, while a status record from the current response still can. Retaining or expiring quotas must preserve that current status; a later response without status marks the retained incident as unknown to the planner. Incident selection, tooltips, and provider badges/banners also exclude unknown status instead of presenting a retained outage as current.

Before changing behavior, identify its owning QML page, config entry, CLI input, external effects, and cheapest behavioral test. Read the existing implementation and tests. Preserve compatibility and unexpected behavior until evidence or the request shows it should change.

When multiple pages consume one CLI envelope, share the bounded record/envelope contract and keep page-specific projections separate. Avoid both duplicate raw parsing and one lossy result that erases different UI semantics. For a new CLI field, update normalization, rendering, relevant checks, and affected guides. Reconcile the linked issue against its acceptance criteria.

Use names that identify provider, source, account, window, or unit when ambiguous. build*, format*, provider*Url, *Rows, and *Text helpers stay pure; refresh*, load*, parse*, select*, set*, and process* may mutate state. Put non-obvious lifecycle state in names such as connected*, pending*, *Memo, *Revision, and *Initialized, and update it beside its effect. Comments explain a workaround or contract, rather than restating assignments.

For repeated JavaScript in delegates, timers, or callbacks, use named helpers. For repeated or bulky UI blocks, use small presentation-only components. Extraction must hide complexity, not merely reduce line count.

Behavioral contracts to preserve

• Quota thresholds come from QuotaThresholds.js, shared by notifications and usage-bar markers. limitResetArmThreshold detects limit resets separately; it is not a warning threshold. main.qml resets opaque notification state through NotificationPlanner.js; its internal NotificationMemo.js preserves provider status baselines. Settings changes must not announce an ongoing incident again or swallow an incident arriving during refresh. Keep these decisions pure and covered by tests/tst_notification_planner.qml and tests/tst_notification_memo.qml. Predictive warnings prime silently and fire on a new projected-exhaustion transition.
• Sessions normalize display fields only. Discard cwd, transcriptPath, IDs, and PIDs; never render, open, or follow them. Remote/SSH host focus is a macOS-only non-goal.
• PanelRules.js evaluates displayed quotas without effects. Automatic capsules use PanelDisplay.meterRows in primary/secondary order, and either displayed quota can satisfy the provider meter condition. Direct missing quotas stay omitted; runOut depends on paceWarningActive. Panel visibility, order, and metric settings preserve the minute clock and icon fallback and must not fetch data or change notification state.
• Privacy projects display records without changing cached snapshots or account command keys. Preserve config keys and pending defaults across all settings pages. PopupRefreshPolicy.js handles freshness and failed-attempt cooldown, including in-flight/queued work; opening the popup must not start cost scans. See the settings decision record.
• Validate credits.codexCreditLimit as finite non-negative amounts, clamped percentages, and bounded reset metadata. Its denominator belongs only to that nested record, never to a plain usage.credits balance.

QML conventions

• Use PlasmaComponents for panel/popup controls and Kirigami/Qt Quick Controls in settings. Use ContainmentItem only for containment/panel/desktop code, not this applet's root.
• Keep metadata.json, contents/ui, contents/config/main.xml, and contents/config/config.qml in the standard package layout.
• Use checkboxes for booleans, spinboxes/sliders for numbers, text fields for short strings, and a combobox for more than three choices.
• Give visual children a size through layouts, anchors, implicit sizes, or explicit compact dimensions. Items otherwise default to 0x0.
• Use layout minimum/preferred sizes, implicit dimensions, and Kirigami.Units instead of panel-size magic numbers. Prefer anchors/layouts over bindings to sibling geometry, except inside the plain-Item boundary described below.
• Keep layout size hints independent of the geometry the layout computes. Use fixed preferred-size ratios for proportional columns. For width-dependent text caps, a plain Item may size children from its own and sibling widths. Keep those bindings out of layout size hints, and expose implicit sizes independent of the Item's assigned width. See Qt's layout guidance.
• Prefer declarative bindings. Move repeated or expensive calculations into helpers or cached properties. Avoid heavy JavaScript in delegates, compact rendering, timers, and DataSource callbacks; profile before optimizing.
• Keep delegates stable. Add clipping, shaders, or nested layouts only for a visible need.
• External Repeater/view delegate components must declare required property var modelData inside the component. An alias assignment from the parent does not establish the delegate's scope; qmllint may miss the resulting runtime error.
• Use qmlformat for new files or a dedicated formatting change, then inspect the diff. Existing files have no formatter baseline, so preserve formatting during unrelated work.
• Keep qmlls in the editor. Machine-specific .qmlls.ini files stay out of Git; language-server diagnostics do not replace make check.

For translation/catalog changes, follow Translations. The checks validate catalog coverage and arguments, then exercise the QML session, pace, and count adapters against all compiled catalogs. Localized smoke scenarios also verify these adapters through Plasma's actual translation domain. When changing provider identity, check keys, CLI aliases, title, color, docs/dashboard/login URLs, icon assets, and scripts/test_provider_icons.sh. Repeat this comparison during official CLI release audits. The pinned 0.56.2 audit found the same 69 IDs as 0.55.0; the OpenRouter fallback already uses https://openrouter.ai/activity. Treat the catalog as fallback presentation data and use the dated evidence, not an assumed current upstream count.

Regression checks

Use direct adversarial QtTests for pure public behavior. Assert QML wiring, effect ownership, and lifecycle ordering statically. Use runtime checks where static checks cannot establish the behavior. Avoid assertions on private helper names or body decomposition when public behavior is already covered.

scripts/lib/qml_surfaces.py defines QML/JS file groups for the Makefile, hardening checks, and translation extraction. Existing globs cover new files; add a glob only for a new directory. scripts/test_qml_hardening.sh rejects uncovered QML/JS files.

• Use require_in_surface / reject_in_surface in shell, or Surface.require, Surface.function_body, and Surface.id_block in Python, for rules applying to the whole applet or config page. Moving code between files then preserves the check. Use *_in_file only for actual per-file contracts, such as safe icon fallback in each delegate.
• Use require_definition_where_used or Surface.require_definition_where_used for shared unqualified helpers. A declaration in another QML/JS file does not satisfy the caller's scope. These helpers also check the page root when components call applet.foo(...). A plain search for function foo( anywhere in a group can miss broken callers.
• Local bindings for hasOwnKey, isUnsafeObjectKey, copyObject, and shellQuote delegate to contents/ui/Guards.js. Share the implementation through that .pragma library module, including in config pages. tests/tst_guards.qml covers behavior; scripts/test_security_regressions.sh rejects implementations duplicated elsewhere.

Run the relevant check during iteration, then the required make check gate. Read its output for tool failures and skips. CI uses the pinned Plasma image in the workflow, with explicit import warnings and QtTests configured to reject skips. A local machine missing QML modules may provide less coverage; report what actually ran.

tests/test_account_refresh.py runs the production account-selection functions and command binding in Qt's event loop. It counts refresh requests for cached and uncached accounts in single-provider and aggregate modes; CLI effects are replaced by observations at the refresh boundary.

tests/test_widget_update_controller.py instantiates the production updater module and runs temporary executable fixtures through Plasma's real DataSource. It checks overlapping requests, setting changes during a check, captured install mode, invalid results, and cancellation at the production 60-second timeout followed by a successful new request. Static checks preserve the stale-source guard for any callback delivered after retirement. This adds about one minute to make check. Its only substitute is the script URL; it neither contacts GitHub nor installs a release. The module's interface is settings, checkNow(), read-only runtime status, and result signals. The script URL is a local executable dependency, not a widget setting. Internal request state and timers remain inside the module.

tests/tst_panel_settings_geometry.qml records control positions after rendered frames while the real Panel page initializes. It covers narrow/wide windows, larger text, right-to-left layout, and scrolling through expanded options. It requests redraws during observation, requires multiple rendered frames, and compares both coordinates. Direction changes also check that the opposite padding is restored. The QML runner repeats it with the KDE desktop controls style because its scrollbar reserves viewport width, unlike the default overlay style. Every runner invocation applies the strict no-skips check; tests/test_qml_runner.py verifies skip and failure propagation across styles.

make check disables unqualified-name warnings because Plasma injects helpers such as i18n() as context properties. It validates AppStream metadata when kpackagetool6 is available and reports a skip otherwise. On older local Plasma packages without QML type metadata, import/type coverage may be partial; CI supplies the metadata. To require CI's strict checks locally:

CI also runs smoke scenarios under Xvfb and retains screenshots and logs as workflow artifacts. Release publication requires both check and smoke jobs. The check job always runs make check and make package. A lightweight scope job compares the tested PR merge tree with its base parent, or the full before/after range for a push to main. Only changes limited to the editorial Markdown allowlist in scripts/ci_scope.py omit the smoke-runtime job. Images, translations, code, tests, packaging, CI files, unknown paths, missing history, and empty diffs keep graphical coverage. Tags always run it.

The required smoke job reports either successful graphical tests or an explicit documentation-only omission in its summary. It fails if scope detection fails, the runtime result is missing, or required smoke tests fail or are cancelled. The workflow itself has no path filter, so required checks still report a result. This follows GitHub's required-check guidance.

Popup smoke tests

Run the popup smoke test from a graphical Plasma 6 session:

This requires Python 3, GNU gettext, plasmawindowed, dbus-run-session, and the Plasma, Kirigami, and KDE desktop control QML modules. README captures also require the Breeze Dark color scheme. Localized scenarios use the UTF-8 locales in the translation guide; CI generates them during setup. The runner opens a temporary applet for each scenario, captures it, and closes it automatically. List the available scenarios with:

Select one scenario or choose a new artifact directory:

Use --renderer opengl on a graphical session with OpenGL for accurate provider icon colors. The default software renderer checks layout and behavior, but does not render Kirigami's icon color masking. Qt documents the software renderer's effect limitations.

The command prints the artifact directory, defaulting to dist/smoke/run-*. Each scenario produces a PNG and a process log; results.json records pass or failure. Existing output directories are never overwritten. The timeout is 30 seconds per scenario and can be changed with --timeout 60.

The runner copies the current applet into temporary XDG directories under a separate applet ID and uses a private D-Bus session. It sets a synthetic CLI path and disables updates and notifications before QML starts. It does not install a package, use real provider accounts, change the installed widget's settings, or restart Plasma. Temporary files and preview processes are removed on completion, timeout, or interruption.

The capture component selects the real popup views and waits for the expected state before using Qt's grabToImage. QML errors, recursive layout warnings, missing captures, early exits, and timeouts fail the command. Nested-layout QtTests also use failOnWarning and exercise provider details and project rows at narrow and normal popup widths. Screenshots still need visual review: this is not a pixel-comparison test and does not exercise panel placement, key-event dispatch, or the real CLI. Panel scenarios verify capsule count and clipping at small sizes, including zero and absent quotas. panel-vertical and panel-vertical-minimal supply the vertical form-factor input because plasmawindowed has no panel containment. QtTests additionally exercise pointer/keyboard activation and resizing. settings-panel, settings-panel-information, settings-panel-advanced, and settings-panel-narrow verify pending preview changes, collapsed/expanded controls, rendered quota capsules, and a 420-pixel layout with larger text and all additional information enabled. panel-information, panel-information-minimal, and panel-information-single capture grouped text at a 24-pixel panel height, including selection of the second provider. QtTests exercise style selection, disclosure, retained hidden values, defaults, custom order and filtered-meter fallbacks, long-text bounds, exhausted grouped-text width, reordering after disclosure, and activation through both text and meters. The live adapter limits meters to four; a renderer stress test exceeds that limit to verify the zero-width guard independently of theme dimensions. Early preview exits report the process exit code in addition to the log path. usage-retention exercises failed/partial refreshes, recovery, notification suppression, and cache invalidation. It also verifies multiple extra windows through cache decode, QML normalization, and re-encoding, including extra-only and measured-zero quotas. Cost refreshes, range changes, account selection, and cache restore must keep token costs hidden for stale usage. Successful credits-only responses with old timestamps must preserve their balance, including zero, through the next quota-expiry check. usage-cache-restart launches two separate widget processes with the same isolated settings and delays the second CLI refresh to verify startup restoration from disk. Synthetic payloads cover a subset of the CLI 0.56.2 contract; fixture dates are relative to run time. Typography uses Noto Sans and Breeze icons.

make check covers the runner's portable isolation and failure-handling tests and lints the capture QML. make smoke additionally requires the graphical environment and reports a failure rather than silently skipping when that environment is unavailable.

Panel configuration matrix

Capture all 32 combinations of Standard/Minimal and the four content switches (provider name, usage text, credits, meters) with one and three providers in Breeze Light and Breeze Dark:

Run it in a graphical Plasma session or prefix the command with xvfb-run -a. It requires the same tools as the popup smoke runner plus both Breeze color schemes. It always uses OpenGL so provider icon masks render their actual colors. The synthetic CLI, applet installation, configuration, and D-Bus session are isolated using the smoke runner. The installed widget and real credentials are not used. The temporary applet runs the production normalization, settings adapters, and compact renderer.

The default run saves 336 captures: 128 base combinations plus targeted cases for all 24 element orders, five text formats, explicit quotas, visibility rules, missing data, long names, exhausted quotas, and 24/48/64-pixel panel heights. --vertical adds 128 captures covering the base combinations on vertical panels. Unavailable credits are tested with the three-provider fixture. Missing and exhausted quotas are synthetic normalized snapshots within the isolated applet.

The runner rejects missing PNGs, clipped measured elements, and incorrect base text/capsule counts. index.html filters the gallery by theme/provider count/ orientation and base cases; results.json records configuration, text, and geometry; source.json identifies the source digest and Git revision when available. Captures require human visual review: passing assertions does not establish typography or contrast quality. This is a bounded matrix, not every possible font, scale factor, translation, provider payload, or rule threshold.

CI runs the horizontal matrix in smoke-runtime and uploads the panel-matrix artifact. The popup artifact also includes settings-panel-scrolled, which checks that the preview remains visible at the bottom of the expanded options. QtTests cover the corresponding identity fallback and fixed-preview behavior, including the KDE desktop controls style and right-to-left layout.

Runtime verification

After extracting components/delegates or changing their sizing, install or upgrade the widget and inspect recent logs for QML errors and recursive layouts:

Ignore unrelated widget logs unless they mention app.codexbar. The Plasma 6.7.4 configuration loader passes every configuration key to each settings page. On the verified KF 6.29 / Qt 6.11.2 stack, this includes defaults and produces Setting initial properties failed for cfg_* properties absent from that page. Check the named key against the page's ownership before treating this warning as a failed page. Keep default initializers aligned with contents/config/main.xml for loaders that do not inject them. Do not add dummy cfg_* properties to silence these warnings: Plasma saves declared properties on Apply, which can overwrite unrelated or runtime-owned state. The ownership checks in scripts/test_ui_regressions.sh protect this boundary. See KDE's configuration contract.

For a panel smoke check when plasma-sdk is installed:

Use plasmawindowed app.codexbar.plasma for an installed-widget check. Restarting/replacing plasmashell is a final runtime check, not the edit loop. Use qmlprofiler only after reproducing a performance problem, and keep traces in ignored dist/review/ or the OS temp directory.

CLI probes and packaging

The widget expects a working codexbar. Probe the selected official version when investigating a contract; keep raw account output out of logs and commits.

For packaging changes, run make package after make check. Packaging needs Python 3 and GNU gettext. It compiles po/*.po to contents/locale/<language>/LC_MESSAGES/plasma_applet_app.codexbar.plasma.mo and includes the catalogs in the archive. Generated .mo files stay out of Git. For string extraction and catalog updates, follow Translations.

The PACKAGE_FILES list in the Makefile defines the archive contents, including README screenshots. Publishing the resulting dist/codexbar-plasma.plasmoid in a GitHub Release requires user authorization. If a KDE Store channel is introduced, use its KNewStuff/Discover update path for that channel. WidgetKit, Sparkle, Keychain/Full Disk Access UI, and macOS app implementation code remain outside this standalone Plasma repository.

Delivery and CI

Use a codex/ branch and a PR for repository changes. Direct pushes require an explicit exception for the current task. A request to push directly does not authorize weakening protection rules or bypassing failed checks.

Every PR title follows Conventional Commits: type(scope): description, with an optional scope and an optional ! before the colon for breaking changes. Allowed types are feat, fix, docs, style, refactor, perf, test, build, ci, chore, and revert. Use a short description of the final change, for example fix(accounts): release stale requests or docs: clarify installation. Keep the title current when scope changes, and retain that format for the squash commit. The pr-title check validates new and edited titles; title edits run this small workflow without rerunning the full widget suite.

The default branch rules require a PR and successful GitHub Actions check, smoke, and pr-title jobs, tested against the current base branch. The rules also prevent deletion and force pushes. Copilot review remains enabled; no additional human approval count is required. The maintainer can merge their own PR once its checks pass. Inspect the effective rules with:

The agent owns delivery through these completion criteria:

1. After each push, identify the exact commit and its GitHub runs. Follow the required checks and other applicable CI runs until they finish. Queued or running checks are pending, not a completed delivery. Results for an older commit do not validate a newer push.
2. Inspect failed jobs and fix failures caused by the change. Rerun a job only when evidence supports a transient infrastructure failure; repeated failures need diagnosis. Report an external blocker with the run link and failing job. Treat unexpected skips, cancelled runs, and missing required checks as unresolved. The release job is intentionally skipped on non-tag runs. A documentation-only smoke-runtime omission is expected only when the required smoke job confirms it. Superseded PR runs may be cancelled by concurrency; follow the replacement run for the latest commit. Main pushes and release runs are not cancelled when a newer run starts.
3. For a PR-only request, finish when the current PR checks pass and the PR body records their results. Report it as ready for review, not merged. Merge only when authorized; check the current head and base again before merging.
4. After an authorized merge or direct push, follow the runs for the resulting main commit too. Reconcile related issues and report the commit, final CI outcome, and any remaining blocker. Fix a post-merge failure through a PR unless the user explicitly authorizes another delivery route.

Keep progress updates brief while waiting. If the session is interrupted, leave the exact commit, run links, and remaining checks in the handoff so work can resume without treating pending CI as success. A recurring automation is needed only when the user asks for monitoring beyond the active task.

Changelog and releases

CHANGELOG.md is the source of notable widget changes and future GitHub release notes. It follows Keep a Changelog. History starts at 0.2.35, using its published notes; earlier releases remain linked on GitHub.

For every user-visible change, the agent adds or revises an Unreleased entry in the same commit. Describe the observable result and any upgrade action. Group entries under Added, Changed, Deprecated, Removed, Fixed, or Security; include only categories with entries. Group related commits into one useful entry. Internal refactors, tests, and routine instruction edits need no entry unless they affect users or contributors' supported workflows; explain that decision in the PR or direct commit body. TODO owns future Linux parity work.

Before an authorized release:

1. Compare the diff since the last release with Unreleased, including direct commits to main. Correct omissions and remove claims that have not shipped.
2. Move the entries into ## X.Y.Z - YYYY-MM-DD, leaving an empty ## Unreleased first. Use the release date, keep versions newest first, and set KPlugin.Version in metadata.json to that same version. Add a full-diff link with absolute GitHub URLs so it works in both the package and release.
3. Run make check, make package, and python3 scripts/changelog.py --tag vX.Y.Z. Review the extracted notes before committing and pushing the matching tag. Tag publication needs authorization.

make check validates headings, categories, dates, ordering, and the newest version against metadata. The tag workflow also requires an empty Unreleased section and an exact tag match. It extracts the version's body into ignored dist/release-notes.md and publishes it through the release action's body_path. The archive includes the changelog. Keep published sections historical; prepare new changes under Unreleased and correct factual errors explicitly. Existing GitHub releases are not rewritten when this workflow is introduced.

These checks validate structure and release consistency. The agent must still compare the final change with the entries to catch missing or misleading notes.

Repository maintenance

The agent owns repository consistency in every task. Include dependent updates in the same change, without waiting for the user to name each file.

Before editing, trace the affected behavior through its callers, configuration, tests and fixtures, scripts, CI workflows, packaging and metadata, translations, documentation and examples, TODO entries, and related issues. Inspect the relevant files; filename searches alone do not establish whether a dependency is affected.

Before delivery, review the final diff and search for old names, paths, commands, defaults, and claims affected by the change. Update each dependent reference or confirm that it remains valid. Regenerate affected tracked outputs through their existing generators. Remove obsolete references when replacing an interface; preserve compatibility requirements and pinned historical evidence.

Fix stale material discovered during the task when the correction is clear, safe, and within scope. If it needs a separate decision, external contract, or substantial unrelated work, record the evidence and remaining work in TODO for Linux parity, or an existing/new issue for other work under the publication rules in AGENTS.md. Report the exact blocker when issue publication is not authorized. Complete independent work and make any unresolved inconsistency explicit at handoff.

Completion requires consistent affected files, the applicable checks below, and accurate TODO and related issue status after delivery. Passing tests alone does not establish consistency. In the PR verification section or direct commit body, summarize the dependent updates and any unresolved gaps. Version and dependency changes need compatibility evidence; bump versions only as part of their actual update or release workflow. A date change alone is not maintenance.

Documentation and work tracking

TODO.md is the current list of useful Linux/Plasma gaps relative to the official macOS app. Keep implementable work separate from official CLI blockers and explicitly unverified candidates. Guides describe supported behavior. Issues can hold bug reports and discussion; a parity issue is a reference, not a second checklist to maintain. Existing issue links preserve context, and their migration alone does not complete the feature.

For every repository change, including authorized direct commits:

1. Read the relevant guides, TODO entries, pinned evidence, and linked discussion. Compare the requested behavior with current code and its tests.
2. Reconcile the final diff with those references. Update README for setup and requirements, the usage guide for behavior/defaults, and this guide for contributor workflows. Keep contracts in focused guides and maintain the docs index. Remove completed TODO entries in the implementing PR; retain remaining scope when delivery is partial. A documentation-only gap review does not count as implementation.
3. Run make check and applicable example/package checks. Inspect documented commands against their implementation. Review prose for accuracy as well as broken paths. Record documentation and TODO impact in the PR or direct commit body, including why no update is needed when they are unaffected.
4. Reconcile related issues after authorized delivery. Use Closes #123 only when all acceptance criteria are met. For partial work use Refs #123. Keep implementation status in TODO; do not create an issue for every gap.

Keep proposal status visible inside each contract document, with exact verified versions. Dated audits retain their findings; a successor names the evidence it replaces. Current guides describe delivered behavior. During widget release preparation, verify setup, requirements, defaults, and changed features against those guides and TODO. Updating a date alone is not maintenance.

This follows Google's documentation practices and docs as code. GitHub's closing-keyword rules apply when a change reaches the default branch.

Upstream release maintenance

On every new stable official CodexBar release, the agent updates TODO without waiting for a user reminder. Apply the same process during an explicit parity review. The daily agent monitor detects releases; these repository instructions define the review. Instructions alone do not schedule execution.

1. Read TODO from the current default branch and check for an existing parity update PR. Read the official release history through the newest stable release, including every release since the last reviewed version. Record exact tags/commits and dates. Ignore prereleases unless the user requests them. If nothing changed and no verification is pending, finish without a commit or notification.
2. Compare Linux-relevant changes with current Plasma code, schema, tests, and existing guides. Include fixes and changed contracts, not only new features. Recheck carried-forward blockers against official Linux CLI changes. Compare TODO with unresolved findings in pinned audits and linked issues too; a prior tracker migration may be incomplete. Retain unresolved older gaps even when release notes do not mention them.
3. Classify each gap as implementable with the official Linux CLI, blocked on a named official contract, or excluded as macOS-only/not useful on Plasma. Keep only the first two in the actionable inventory. An unverified candidate stays in a separate verification section until there is enough evidence. For a blocker, state the missing field/action and the version last verified. A Swift view model or source declaration alone does not prove emitted Linux output. Keep auth, config parsing, provider fetching, and upstream edits out of the frontend task.
4. Probe changed contracts with a checksum-verified official Linux release asset in an isolated temporary account and cache, using synthetic inputs. Keep host credentials and provider files inaccessible, pass no credential environment, and do not replace the installed CLI. If an asset, tool, or account-free reproduction is unavailable, record the exact limitation. Keep the release reviewed separate from the last verified CLI contract, and never advance a full-audit baseline on the strength of a partial probe.
5. Update TODO in the same PR: add new gaps with evidence and a concrete done condition, remove already implemented ones, and revise resolved blockers. Keep TODO short enough to scan; link substantial reusable evidence in a dated research note and index it. Leave completed behavior in the guides and Git history. Preserve historical evidence, and update maintained claims that the new evidence supersedes.
6. Review the diff, run required checks, and open or update one Conventional Commit PR for the review. Follow its latest CI through completion under delivery and CI. A scheduled review authorizes the TODO and documentation PR, not feature implementation or automatic merge. Reuse an existing update PR and report only a new release, meaningful result, failure, or required user action. Retry unresolved verification on later runs without opening duplicate PRs or repeating unchanged notifications.

A missed scheduled run must catch up from TODO's recorded version. A failed fetch leaves that version unchanged. Report incomplete release coverage explicitly and keep the last fully reviewed release as the next run's starting point. For a partially verified contract, retain its earlier verified version. The monitor runs through the local Codex scheduler; it needs this machine and Codex available. Check the saved automation when changing its cadence or scope.

Maintaining agent instructions

Keep permanent rules in AGENTS.md and Linux parity status in TODO. Add a rule for an observed failure or repeated friction. Put task-specific details in the relevant section of this guide and add a root pointer stating when to read it. Maintain links and the documentation index in the same change.

The repository enforces a 16 KiB AGENTS.md budget, with a working target below 200 lines. These are local maintenance choices. Codex's default budget is 32 KiB across discovered project instructions, so leave room for other files. See Codex discovery.

OpenAI describes using a short instruction file as an index into maintained docs. This motivates our conditional pointers, rather than a duplicate feature inventory. See OpenAI's engineering experience.

Keep CLAUDE.md as the single @AGENTS.md import. Imports load their full contents; adding imports for every guide would restore the context cost. Anthropic recommends concise instructions, generally under 200 lines, rather than imposing that as a loading limit. See Claude memory.

Keep .github/copilot-instructions.md limited to review guidance and consistent with AGENTS.md. GitHub assigns that file higher precedence than AGENTS.md; repository prose cannot reverse product precedence. See GitHub instruction precedence.

QML references

• KDE package setup
• Widget properties
• Configuration
• Testing
• KF6 porting
• Plasma QML API
• Qt QML practices
• Qt Quick performance