AGENTS.md for macUSB

This file defines how AI coding agents should work in this repository.

Scope and precedence

• This repository intentionally keeps AGENTS.md under docs/ for repository cleanliness.
• Direct user instructions in chat have top priority, except explicit protected-branch safety rules defined in this file.
• If instructions conflict, follow the stricter safety rule and ask for clarification before proceeding.
• docs/AGENTS.md is the single source of truth for process, commit, and changelog rules.

Mandatory context bootstrap

Before implementation, recommendations, or review:

1. Read this file in full.
2. Read docs/reference/README.md.
3. Read the topic-specific runtime reference(s) for the task scope.
4. For downloader-scope tasks, read docs/reference/features/downloader/DOWNLOADER.md.
5. For helper-scope tasks, read docs/reference/features/helper/HELPER.md.
6. If scope is cross-cutting or uncertain, read:
   • docs/reference/core/APP_RUNTIME_OVERVIEW.md
   • docs/reference/core/USER_FLOW.md
   • docs/reference/core/FILE_STRUCTURE.md
   • docs/reference/core/RISK_AREAS.md
   • plus all affected topic references listed in docs/reference/README.md.
7. Build one active ruleset before changing code.

Repository map

• App runtime: macUSB/
• Privileged helper: macUSBHelper/main.swift
• Runtime reference index: docs/reference/README.md
• Downloader runtime reference: docs/reference/features/downloader/DOWNLOADER.md
• Helper runtime reference: docs/reference/features/helper/HELPER.md
• Existing release history (read-only for agents): docs/CHANGELOG.md
• Agent process rules: docs/AGENTS.md

Critical runtime invariants (must preserve)

These are the non-negotiable runtime contracts. If a task touches any of them, preserve behavior unless the user explicitly requests a change.

Permissions and startup gating

• App operation depends on both:
  • Full Disk Access for macUSB
  • Allow in the Background approval for helper operation
• Startup/activation flow must refresh and surface permission/helper readiness state.
• Missing required permissions must be visible in UI and may block reliable helper execution.
• External drive support must default to disabled on launch/termination unless the user explicitly enables it in app options.

User flow and destructive safety

• Main screen sequence remains:
  • WelcomeView -> SystemAnalysisView -> UniversalInstallationView -> CreationProgressView -> FinishUSBView
• Start of installer creation is destructive and must require explicit confirmation.
• Cancel path must preserve deterministic cleanup/result behavior.

USB target safety and capacity

• Before installer recognition, required capacity in UI is unresolved (-- GB).
• For recognized macOS, Linux, Windows, and manual raw-image sources, capacity validation uses the source size plus 5%, rounded up to a whole byte. The UI displays the smallest fitting 2/4/8/16/32/64 GB (and larger doubling) drive class.
• Image sources use the selected image file size; .app sources use the total logical size of regular files in the bundle without following symbolic links.
• If source size is unavailable, an alert explains the fallback: macOS major version >= 15 uses the 32 GB class and 28_000_000_000 bytes; all other flows use the 16 GB class and 15_000_000_000 bytes.
• Proceed action stays blocked until selected target passes validation.
• macOS target selection defaults to physical whole disks and automatically preformats non-PPC whole-disk targets as GPT/HFS+ with the mac_USB label; APFS does not block this path.
• Standard createinstallmedia, restore-legacy (Lion/Mountain Lion), and Mavericks workflows may reuse an existing GPT/HFS+ volume without whole-disk preformat only through the analysis-screen Option override. Restore erases the selected volume through the existing asr pipeline.
• In PPC flow, target formatting behavior is specialized and must not be forced through standard preformat assumptions.

Detection and compatibility routing

• Analysis flags are the source of truth for workflow branch selection.
• Supported detection families include modern, legacy, restore-legacy, PPC, Sierra-specific, Catalina, and Mavericks handling.
• Panther must remain explicitly unsupported.
• For .cdr and .iso, if image is already manually mounted in macOS, analysis must be blocked with user guidance to unmount and retry.

Installer workflow branching

• Standard path uses createinstallmedia family behavior.
• Legacy restore and Mavericks use restore-style pipelines.
• PPC uses dedicated PPC formatting/restore behavior.
• Catalina/Sierra use dedicated handling where required.
• Temp ownership and cleanup behavior must remain deterministic.

Helper architecture and security invariants

• Privileged install operations must run via SMAppService + LaunchDaemon helper.
• No terminal fallback privileged path.
• App/helper naming, mach service, listener, plist wiring, bundle identifiers, and signing compatibility must stay aligned.
• Helper progress must remain observable in app state.
• Live tool output remains diagnostic data, not stage UI source of truth.

UI/UX invariants

• Flow window contract remains fixed at 550 x 750.
• Bottom action zones use BottomActionBar with safeAreaInset(edge: .bottom).
• Use compatibility wrappers from LiquidGlassCompatibility.swift:
  • macUSBPanelSurface
  • macUSBDockedBarSurface
  • macUSBPrimaryButtonStyle
  • macUSBSecondaryButtonStyle
• Spacing/radii use MacUSBDesignTokens.
• Dynamic lists, their contextual banners/status cards, and conditional header actions must follow the global motion rules in docs/reference/design/DESIGN_SYSTEM.md, including symmetric appearance and disappearance.
• DEBUG UI must not appear in Release builds.

Localization invariants

• Source language is Polish (pl) in every string catalog under macUSB/Resources/.
• New localized UI copy is authored in Polish first; DEBUG-only text follows the exception in UI copy and translation rules below.
• Localized UI state, workflow payloads, and helper transport must carry localization keys instead of prelocalized strings.
• Resolve a key with String(localized:) only at a presentation boundary where an API requires a String; APIs that accept localization keys should receive keys directly.
• Helper localization keys and app-side rendering keys must remain synchronized.
• For strings that mirror macOS system UI, notifications, or alerts, match Apple’s terminology in each language instead of inventing custom wording.

Logging and notifications invariants

• Important app-side runtime logs must go through AppLogging.
• App- and helper-authored diagnostic logs use English and follow the timestamp-then-stage format defined in docs/reference/platform/LOGGING_CONTRACT.md. Stage and workflow labels use uppercase letters; workflow-specific operations use [STAGE_WORKFLOW], and helper-origin lines append [HELPER] after the stage. Apply this contract as logging paths are migrated in stages.
• Logs remain human-readable and export-ready for diagnostics.
• Notification permission prompting remains user-initiated from menu when state is not determined.
• Completion notifications are gated by system authorization and app-level policy.

Delicate risk hotspots

• Version/compatibility heuristics can affect multiple workflows at once.
• USB whole-disk enumeration, Option-volume parent matching, workflow-driven selection normalization, and destructive target formatting are high-risk paths.
• Helper registration/signing/environment drift may surface as late-stage failures.
• Localization key drift between helper and app breaks runtime text quality.
• Notification and permission UX can regress when startup/menu/finish logic diverges.

UI copy and translation rules

The localization-key, source-language, catalog, and translation-review rules in this section apply to localized UI text. Text shown exclusively in DEBUG is exempt from those rules.

• All user-facing UI text available outside DEBUG must use localization keys.
• Text shown only in DEBUG must be an untranslated English literal in code, with no localization key or .xcstrings entry. This includes DEBUG-only controls, statuses, summary values, and alert messages. In SwiftUI, use Text(verbatim:) and nonlocalizing label builders so automatic extraction does not create catalog entries for these literals.
• For every new or modified localized UI text, name its semantic localization key using the area.feature.element format, adding more specific segments when needed. Use the same key in code and in the string catalog assigned to that feature or workflow stage (for example, downloader.disk_image.stage.title in Downloader.xcstrings). Keep the Polish source text and all translations as catalog values, never as the key itself.
• Select the owning catalog using the table map in docs/reference/platform/LOCALIZATION_CONTRACT.md. Welcome, menu actions, and their app/helper messages belong to App.xcstrings; analysis belongs to Analysis.xcstrings; pre-start USB summary, prerequisites, and confirmation belong to Summary.xcstrings; downloader belongs to Downloader.xcstrings; USB execution/progress and helper workflow presentation belong to Creator.xcstrings; finish/result/cleanup/ejection presentation and USB completion notifications belong to FinishUSB.xcstrings. Workflow-qualified and shared-key names follow the naming contract in that reference. Other areas remain in Localizable.xcstrings until they receive a dedicated catalog. Add future feature catalogs deliberately and update the table map with their scope.
• Explicitly select a dedicated catalog using table:, tableName:, or a table-bearing LocalizedStringResource, including dynamic-key presentation boundaries and extraction anchors. A semantic key prefix does not select its table.
• Give shared text a feature-owned copy when isolating that feature's catalog. Keep the original entry for other consumers and use a semantic key in the dedicated catalog.
• During catalog-only migrations, copy existing wording and translations without rewriting them. When replacing a Polish source-text key with a semantic key, preserve its effective Polish source value explicitly in the destination catalog.
• Polish is the source language for new UI copy.
• When planning a change that introduces or modifies UI text, always include the proposed Polish and English wording.
• During implementation, provide translations for every language supported by the application.
• Review every new or modified text twice in each supported language. Both reviews must cover:
  • grammar,
  • style and natural phrasing,
  • correct macOS and Apple terminology,
  • consistency with the meaning and context of the UI element.
• Before completing the task, perform a final verification of all localization keys and translations.
• Edit every .xcstrings catalog in the exact target serialization format produced by Xcode: two-space indentation, spaced "key" : value separators, expanded multiline objects, Xcode's case-insensitive natural catalog order for string keys, lexicographically ordered locale identifiers, and no compact inline localization entries. Opening or saving the catalog in Xcode must not produce a formatting-only diff.
• Mark an actively used localization key as "extractionState" : "manual" when it is intentionally resolved through dynamic indirection that Xcode string extraction cannot discover; do not accept stale for such a key.
• In the post-implementation report, list every localization key created or modified together with its translation in every supported language.
• Do not place a period at the end of banner or alert titles.
• Every NSAlert must include:
  • the application logo,
  • a title,
  • a descriptive message.
• NSAlert buttons must be selected and worded according to the specific action and context. Do not use generic button labels when a more precise label is appropriate.

When to open runtime references

• If a task changes runtime behavior, read the relevant topic file(s) from docs/reference/README.md.
• If a task is cross-cutting (architecture, broad risk analysis, major refactor), read:
  • docs/reference/core/APP_RUNTIME_OVERVIEW.md
  • docs/reference/core/USER_FLOW.md
  • docs/reference/core/FILE_STRUCTURE.md
  • docs/reference/core/RISK_AREAS.md
  • and all affected topic files from docs/reference/README.md.

Workflow (end-to-end)

Use this sequence unless the user explicitly requests a narrower scope that does not compromise safety:

1. Complete the mandatory context bootstrap.
2. Analyze current behavior and gather context from code and docs.
3. Implement the required change.
4. Validate behavior (project policy in this file applies).
5. Update documentation in docs/reference/ when behavior, contracts, or workflows changed.
6. When the user explicitly requests a changelog, prepare Polish and English versions and provide them in the response without editing docs/CHANGELOG.md.
7. Follow the commit cadence defined in the implementation plan. For unplanned but genuinely staged work, announce each stage-ending commit before creating it. For ordinary small changes, do not create commits automatically; suggest one after implementation instead.

Definition of done

A change is done when all applicable conditions are met:

• Mandatory context bootstrap was completed.
• Requested behavior is implemented.
• Validation was run (or explicitly reported if not possible).
• relevant file(s) in docs/reference/ reflect current behavior when relevant.
• Requested changelog text is delivered in Polish and English in the response, without editing docs/CHANGELOG.md.
• No stale documentation links remain.
• Commits listed in an implementation plan and announced commits for genuinely staged work are created at the applicable stages. Ordinary small changes receive a commit suggestion instead, and all commits actually created are included in the post-implementation report.

Validation policy (project-specific)

• Agent validation scope is Debug build only.
• Do not run unit tests or UI tests unless the user explicitly asks.
• Do not run notarization, release signing, release packaging, or distribution steps.
• Preferred build command:

xcodebuild -project macUSB.xcodeproj -scheme macUSB -configuration Debug -destination 'platform=macOS' build

• If local signing blocks Debug verification, use a no-signing fallback only for local validation:

xcodebuild -project macUSB.xcodeproj -scheme macUSB -configuration Debug -destination 'platform=macOS' CODE_SIGNING_ALLOWED=NO build

Change classification

Use these rules to decide required documentation updates:

• Code or runtime behavior changed:
  • update relevant file(s) from docs/reference/README.md.
• User-facing behavior changed and should appear in release notes:
  • prepare a bilingual Polish and English changelog entry only when the user explicitly requests it, and provide it in the response without editing docs/CHANGELOG.md.
• Internal-only refactor with no user-facing impact:
  • no changelog entry is needed unless the user explicitly requests one.
• Documentation-only change:
  • update only affected docs and keep cross-references consistent.

Helper change safety gate

Any major helper change requires explicit user confirmation before implementation.

Treat as major helper change when it affects one or more of:

• XPC protocols or payload schemas.
• Workflow stage model, privileged command pipeline, or cancellation semantics.
• LaunchDaemon plist wiring, service naming, or helper registration lifecycle.
• Entitlements, signing identities, bundle identifiers, or helper security assumptions.

Minor helper changes that do not alter behavior may proceed, but must still be reported clearly.

Decision and escalation rules

• If requirements are ambiguous and materially affect behavior, ask before implementing.
• If multiple valid implementations exist, present tradeoffs and request direction.
• Do not plan fallback paths unless the user explicitly requests a fallback.
• If blocked by environment constraints, report blocker, what was validated, and what remains.
• If a user request is potentially destructive to code/history or clearly high-risk and unreasonable, pause execution, explain the risk, and ask whether to continue despite the risk or stop.

Documentation hygiene

• The root README.md is protected documentation and must never be edited automatically, including as part of a general documentation update. Any README change requires a separate explicit user request that names README.md as in scope.
• If runtime behavior changed, update relevant file(s) from docs/reference/README.md.
• Do not edit docs/CHANGELOG.md. When the user explicitly requests a changelog, provide its Polish and English versions in the response only.
• Keep process rules only in docs/AGENTS.md.
• Keep app behavior and technical reference only in docs/reference/.
• Avoid duplicating the same rule in multiple files.
• Keep links and file paths current after any rename or restructure.

Code structure hygiene

• When adding new features, prefer creating new files/modules instead of extending an unrelated large file when this improves readability, reviewability, and safety.
• When extending an existing feature and the code grows materially, proactively suggest and (when accepted) perform a split into smaller focused files.
• Keep one clear orchestrator per workflow and move helper policies/utilities/IO/details to focused companion files.
• Treat structural refactors as behavior-preserving by default (no runtime/UI changes unless explicitly requested).

File naming rules

• For code files, use letters only (A-Z, a-z) in the filename stem by default.
• Name code files in PascalCase (words joined together, each starting with an uppercase letter) and compose names from:
  • feature/domain prefix,
  • concrete responsibility,
  • role suffix.
• Match existing repository patterns, for example:
  • AnalysisLogicMacOSCompatibility.swift
  • MacOSDiscoveryCatalogParser.swift
  • MacOSDownloadOrchestrator.swift
  • MacOSDownloaderListView.swift
• In code filenames, the underscore (_) is allowed only when an external or required structure mandates it (for example GitHub workflow conventions).
• Do not use spaces, hyphens, digits, or other special characters in code filenames unless required by external format constraints.
• For new documentation files, write the filename stem in uppercase letters and separate words with underscores (for example USB_CREATION_WORKFLOWS.md).

Large file split rule

• If a file becomes materially larger after a change (many additional lines), the agent must explicitly evaluate whether splitting it into smaller focused files makes sense.
• When a split is reasonable, the agent should propose the split before implementation or include the split in the same change when safe.
• Splits should preserve behavior and separate concerns (orchestrator vs helpers/policies/parsers/ui parts).

Branch naming convention

When branch creation is requested:

• Format: <type>/<topic_short>.
• Keep topic_short very short, ideally an acronym.
• Maximum 3 words in topic_short, separated by _.
• Example branch names:
  • feature/usb_apfs_guard
  • improvement/helper_xpc_retry
  • fix/fda_gate

Branch and merge safety rules

Protected branch: development

• development is permanently non-deletable.
• Deletion of development is forbidden even when explicitly requested by the user.
• The agent must refuse deletion of development regardless of pressure or repeated requests.

New branch base policy

• New branches must be created from development by default.
• If work is clearly scoped to the currently checked out non-main branch, using the current branch as base is allowed.
• Do not create new branches from main unless the user explicitly requests it.
• If a user explicitly requests creating a branch from main, ask for explicit confirmation that main is intentional and development is not desired before creating it.

Protected branch: main

• Automatic merge to main without explicit user instruction is not allowed.
• PRs to main are allowed only when explicitly requested and only from development.
• Merging to main from a PR based on development requires double confirmation and explicit verification before merge execution.
• main is permanently non-deletable (core project branch).
• Deletion of main is forbidden even when explicitly requested by the user.
• The agent must refuse deletion of main regardless of pressure or repeated requests.

Commit rules

Commit message rules

• Write git commit messages in English.
• Use a clear title/summary line plus a readable body written as a paragraph describing the change.
• Base commit title and body on the full scope of changes since the last commit up to the commit being created, not only on the most recent edit made with the agent.
• Keep commit bodies concise and summarized (short paragraph), while still covering the key scope of the full change set.
• Keep commit bodies short by default: one short paragraph, ideally 1-2 sentences.
• Describe only concrete changes included in the commit; keep the wording short, direct, and focused on what actually changed.
• Do not pad commit descriptions with unchanged-behavior clauses using wording such as preserving or while.
• Do not use escaped newline sequences like \n in commit message text; use normal multi-line commit formatting only.
• When creating commits from CLI, never pass \n inside a single -m value; use separate -m flags (title + body) or standard multi-line commit input.
• If a commit includes updates to runtime reference docs under docs/reference/, docs/CHANGELOG.md, and/or docs/AGENTS.md, do not explicitly enumerate those documentation-file updates in the commit title or commit body.
• Do not mention added or updated localization keys, translations, or language coverage in the commit title or body unless the commit contains only translation changes.
• In commit title/body descriptions, omit explicit listing of debug-only functionality that is not present in Release builds.

Commit scope rules

• Create commits automatically only when they are included in an implementation plan or when the implementation is genuinely divided into distinct stages.
• When preparing an implementation plan, include the expected commits, their thematic scopes, and the stages after which they will be created.
• For genuinely staged work without a planned commit, inform the user before creating each stage-ending commit.
• For ordinary small changes, do not create a commit automatically; suggest an appropriate thematic commit after implementation.
• An explicit user request may authorize a commit regardless of the automatic commit conditions above.
• Each commit must comprehensively include the project files belonging to its completed stage without mixing unrelated stages or unrelated user changes.
• A user may explicitly request a different commit scope or cadence.
• In artifact/temporary-output cases, explicitly report those files before committing and ask the user what to do.

Commit and push approval rules

• Local commits that remain unpushed do not require user approval before creation.
• Do not push commits automatically after implementation.
• Push commits only when the user explicitly requests it.
• Before pushing, present all commits to be pushed, including their titles and bodies, for user approval. If the user requests wording changes, amend the proposal and request approval again.

Post-implementation commit reporting rules

• After implementation, report every commit created during the work, including:
  • commit hash,
  • scope of committed files,
  • commit title and commit body/description,
  • whether the commit was pushed,
  • whether the working tree is clean (git status --short has no output).
• If an ordinary small change was not committed, suggest a commit title and body in the post-implementation report.

PR rules

PR title rules

• Write PR titles in English.
• Keep the title short, descriptive, and directly related to the change scope.
• Prefer concise wording focused on user-visible or behavior-impacting change.

PR description rules

• Write PR descriptions in English.
• Keep the description short and concise.
• Include only changes and additions that are actually present in the PR.
• Write the description as sentences, without feature or fix lists.
• Do not pad the description with unchanged-behavior clauses using wording such as preserving or while.
• Do not include testing information in the PR description.
• Do not mention documentation or translation changes unless the PR contains only documentation or translation changes.
• In PR title/description, omit explicit listing of debug-only functionality that is not present in Release builds.

Issue closure for development to main PRs

• Before preparing a PR from development to main, review the full PR diff, included commits, merged PRs, and related GitHub issues to check whether the PR contains an issue fix or implements an issue request.
• For every issue resolved by the included changes, add a closing reference such as Closes #123 to the proposed PR description before requesting approval, so GitHub automatically closes the issue when the PR is merged into main.
• Confirm that the included changes fully resolve each issue before adding a closing reference. For related or partially addressed issues, use a non-closing reference such as Related to #123.

PR approval gate (mandatory)

• Before creating a PR, present the proposed PR title and PR description to the user for approval.
• Do not create a PR until explicit user approval is given.
• If the user requests wording changes, update the proposal and request approval again.

Post-PR merge prompt (mandatory)

• After creating a PR, if the user did not explicitly request merge execution, ask whether the PR should be merged immediately.

Post-PR reporting rules

• After creating a PR, the agent must report:
  • PR number and URL,
  • source branch and target branch,
  • scope of files included,
  • final PR title and PR description,
  • whether the local working tree is clean (git status --short has no output).

Post-merge branch cleanup prompt (mandatory)

• After merging a PR, if the user did not explicitly request branch deletion, ask whether the source branch should be deleted.
• This prompt does not apply to development.

Changelog rules

General rules

• Do not prepare a changelog automatically after completing work; prepare it only when the user explicitly requests one.
• Write every requested changelog in both Polish and English.
• Provide both language versions directly in the response.
• Never save agent-prepared changelog text to docs/CHANGELOG.md; the file remains read-only for agents.
• Verify each entry against shipped behavior and relevant runtime reference files from docs/reference/README.md.
• Keep wording concise and suitable for GitHub Releases.
• Changes with only marginal product impact do not have to be listed in a release entry.
• Small copy-only edits can be grouped under generic labels such as Poprawki tłumaczeń in Polish and Translation fixes in English, or equivalent general text-fix labels.
• Changelog bullets must stay user-friendly and readable; avoid low-level technical jargon when the change was not significant.

Release entry format

• Release title must contain only the app version, for example:
  • ## v2.0
  • ## v2.0.1
• In both language versions, start each release with one short summary paragraph describing what the release focuses on.
• Keep the summary as one coherent paragraph.
• After adding a new bullet for the currently developed version, update that version summary paragraph so it reflects the full accumulated update scope, with emphasis on newly introduced features and/or key improvements.
• For major releases, the preferred section order is: DODANO, ZMIANY, ULEPSZENIA in Polish and ADDED, CHANGES, IMPROVEMENTS in English.
• For hotfix/patch releases (for example x.x.1), sections are optional when change scope is small.
• Section names are suggestions, not strict requirements; skip unnecessary sections and use better-fitting custom sections when needed.

Bullet style

• Keep bullets factual and user-oriented.
• Do not overdescribe implementation internals unless needed for release clarity.
• Do not use file-based screen names (for example class/file names); describe screens functionally (for example selection screen, analysis screen, summary screen).
• When behavior is conditional, state the condition clearly (for example permissions, toggles, runtime state).
• Use consistent English menu path formatting in both Polish and English changelog entries: Options → ..., Help → ..., Tools → ....
• If a release change is one coherent topic, document it as one bullet; split into multiple bullets only when the release contains clearly separate user-facing topics.
• Write every bullet as a simple, user-friendly summary suitable for GitHub Releases; avoid implementation details and deep technical breakdowns.

Tone and scope

• Avoid unverifiable marketing claims.
• Prefer impact-focused wording over low-level technical details.
• Include technical context only when it helps users understand visible behavior changes.

Explicit non-goals

• Do not create or maintain Copilot-specific instruction files (for example .github/copilot-instructions.md) unless the user explicitly asks.
• Do not assume notarization or release distribution responsibilities in this workflow.

Reporting requirements

After each task, report:

• Files changed.
• Decisions taken and why.
• Validation commands executed and outcomes.
• What was intentionally not executed (for example tests, UI tests, notarization).
• Any remaining risk areas, especially around helper and USB-destructive paths.