Axolotl

Imported from Mystic-Stars/Axolotl (AGENTS.md). Install upstream with npx skills add Mystic-Stars/Axolotl. Copyright stays with the author.

Axolotl Launcher Monorepo

This repository contains the Axolotl Launcher desktop application and its official website. Read the applicable project instructions before editing either surface.

Architecture

• Monorepo tooling: Turborepo (turbo.jsonc) + pnpm workspaces (pnpm-workspace.yaml)
• Frontend: Vue 3 / Nuxt 3, Tailwind CSS v3
• Desktop: Rust / Tauri
• Indentation: Use TAB everywhere, never spaces

Apps (apps/)

Packages (packages/)

Pre-PR Commands

Run these from the root folder before opening a pull request - do not run these after each prompt the user gives you, only run when asked, ask the user a question if they want to run it if the user indicates that they are about to create a pull request.

• Website: pnpm prepr:website
• App frontend: pnpm prepr:frontend:app
• Frontend libs: pnpm prepr:frontend:lib
• All frontend: pnpm prepr

The website and app prepr commands

Dev Commands

• Website: pnpm website:dev
• App: pnpm app:dev (copy .env template in packages/app-lib/ first)

Style Commands

• cargo fmt --all (--check): Format all Rust files (dry-run with --check)
• pnpm --filter @modrinth/[app-frontend/ui] [check/fix]: Use ESLint to check all the app frontend or shared UI files (dry-run with check, write with fix)

Codex Development Workflow

Frontend Formatting Before Commits

• Before committing frontend changes, run the affected package's existing fix script from the repository root. It runs ESLint with --fix followed by Prettier with --write, fixing import sorting, Vue attribute order, and formatting together.
• For app frontend changes, run pnpm --filter @modrinth/app-frontend fix. For shared UI changes, run pnpm --filter @modrinth/ui fix. Run both when both packages are affected; use the corresponding package's fix script for other frontend packages.
• Running Prettier alone is insufficient: import sorting and Vue attribute order are ESLint rules.
• Inspect git diff after automatic fixes. Include relevant fixes in the commit, preserve existing user changes, and avoid staging unrelated formatting changes.
• Resolve any remaining errors before committing. If files were already staged, stage the corrected files again so the commit includes the fixes.
• This commit-time formatting step is authorized whenever a frontend commit is requested or already authorized. It does not require running the full prepr workflow after every prompt.
• Before a pull request, follow the existing Pre-PR Commands rules and run the appropriate prepr command, such as pnpm prepr:frontend:app, for the full workflow including internationalization extraction.

Local App Verification

• Automated visual and interaction tests that run in CI are allowed, and may be run locally while developing them. Do not replace the user's own acceptance check: the user still verifies visual and interaction changes themselves.

Website Verification

• Do not use browser automation tools to perform excessive testing of website frontend changes (interaction flows, theme toggling, responsive checks, screenshots) unless the user explicitly requests it. The user verifies visual and interaction changes themselves.

Remote Commits

• Before pushing a remote commit, inspect its changed paths. If it does not change the desktop app (apps/app/, apps/app-frontend/) or its app-specific dependencies, prevent unnecessary GitHub Actions usage by including [skip ci] in the commit message.
• Never use [skip ci] for commits that affect the desktop app or its build, packaging, or runtime dependencies.

Desktop Onboarding Maintenance

When adding or materially changing a desktop app page, route, navigation entry, large user-facing component, core workflow, settings section, or content-management feature under apps/app-frontend, assess the Axolotl onboarding experience.

• Update the onboarding when the feature is relevant to a new user's first-use journey or changes an existing guided workflow.
• Define tours and localized message descriptors in apps/app-frontend/src/components/ui/onboarding/onboardingConfig.ts. Keep OnboardingOverlay presentational and put reusable runtime behavior in useOnboardingTour; do not add step-ID-specific branches to either file.
• Add one stable, semantic data-onboarding-id to the component that owns each guided target, then reference that ID through targetId in the step configuration. Remove targets when their steps are removed.
• Choose the interaction deliberately: navigate must use the real control and wait for its route, activate must execute the control's original behavior, and inspect must explain a region while any non-onboarding click advances without activating the underlying UI.
• Express workflow branches with branchByTarget and nextByCreationPath in the step configuration instead of hard-coded conditionals. Missing optional targets must time out and skip rather than trap the tour or show placeholder copy.
• Do not add a navigation step for the page that first-run or replay mode already opens. Establish prerequisite route or modal state before starting the tour, then begin with useful page content.
• Keep the step definition, target, interaction, expected route, branch behavior, and English and Simplified Chinese FormatJS copy synchronized with the feature.
• For a major feature that should not appear in the first-run tour, add an appropriate contextual/replayable tour or document why onboarding is not needed.
• Verify first-run and replay modes, target-missing behavior, narrow windows, and guided modals after changing any target. Guided modals must reserve space for the bottom dialogue instead of rendering beneath it.
• Add future mascot assets only through OnboardingMascotStage; do not scatter mascot asset references across onboarding steps.

Desktop Update Announcement Maintenance

Launcher release announcements are bundled with apps/app-frontend and shown after a completed app update and in Settings > Updates.

• Add ordinary release announcements only to apps/app-frontend/src/announcements/catalog.ts; adding an entry must not require changes to App.vue, the updater, or the announcement components.
• Do not edit the announcement catalog unless the user explicitly asks for an update log.
• Ask the user for the exact launcher version before writing the announcement unless they already provided it. Use that version exactly; do not query the remote or infer a version from local metadata to choose one automatically.
• A catalog entry remains editable until its matching release tag has been published to origin. Before changing an existing entry, query both refs/tags/v<version> and refs/tags/<version> with git ls-remote --tags --refs origin; when either exists, the release is published and the entry must not change.
• Give every release an ID in the form launcher-<version>, use the exact launcher version and ISO YYYY-MM-DD publication date, and place the newest release first. An unpublished entry may be amended to include its release changes. Once its release tag is published, never reuse its ID, edit the entry, or change its meaning.
• Use only the Keep a Changelog categories added, changed, deprecated, removed, fixed, and security. Omit empty categories.
• Provide both en-US and zh-CN text for the title and every change. Other locales intentionally fall back to English; do not copy announcement bodies into every locale JSON file.
• Keep entries concise and user-facing. Describe observable features, behavior changes, removals, fixes, and security impact rather than implementation details.
• pending_update_toast_for_version is the persisted trigger for the post-update announcement. Do not add separate per-release startup checks or clear it before the announcement closes.
• Preserve startup dialog priority: initialization errors, first-run onboarding, post-update announcement, then community announcement. A replayed onboarding tour must not consume a pending post-update announcement.
• If the announcement schema, categories, fallback behavior, or dialog priority changes, update the catalog types, both announcement display surfaces, and this section together.
• Keep launcher release notes exclusively in the catalog. Do not create or maintain a separate UPDATE_LOG.md file.
• The GitHub release workflow generates its release body from the matching catalog entry with scripts/axolotl/create-release-notes.mjs; a release tag without a catalog entry must fail preflight.
• Local development builds expose a preview button in Settings > Updates. Use it to test the real announcement modal without changing onboarding or pending-update state; do not add per-version preview branches.

Update Logging Instructions

• Do not write or append an update log unless the user explicitly requests one.
• Do not query a remote release, infer a version from repository metadata, or choose a version automatically. Use the version supplied by the user.
• Follow the project's canonical update-log location and format. Launcher release notes belong in apps/app-frontend/src/announcements/catalog.ts; do not create or maintain a separate UPDATE_LOG.md file for them.

Database Migration Safety

• Treat every migration as immutable as soon as it has been applied to any database, including a local development database. Never edit, rename, reorder, or delete an applied migration.
• Before changing an existing migration, query the active development database's _sqlx_migrations table for its version. If a successful row exists, stop and create a new migration with a higher version instead.
• Fix migration mistakes only with a new forward migration. Do not make an old migration appear compatible by directly changing _sqlx_migrations checksums.
• A historical checksum may be reconciled in application code only when the checksum is explicitly allowlisted, the existing schema is validated structurally, and a tested forward migration brings that schema to the canonical state. Unknown checksums must still fail.
• SQLite table renames do not free global index names. Rebuild migrations must drop or rename legacy indexes before creating replacement indexes.
• Migration tests must cover both a fresh database and an upgrade database containing the exact previous tables, indexes, foreign keys, representative data, malformed provider data, and missing optional data.
• After a migration test, run PRAGMA foreign_key_check, verify that legacy tables and indexes are gone, and verify that provider-qualified data did not change provider identity.
• Migrations must not access the network. Cache data used during migration is untrusted and must be validated or ignored without blocking the upgrade.
• Every new launcher migration under packages/app-lib/migrations/ must update REVERTIBLE_SCHEMA in scripts/axolotl/downgrade-app-db.mjs in the same change. Use the migration's 14-digit timestamp prefix as the key; the downgrade tests reject mappings that do not correspond to an existing migration.
• Record every column and table added by the migration in that mapping so removing the migration record cannot leave schema that makes a later re-upgrade fail with duplicate objects. List tables in reverse creation/dependency order so dependent tables are dropped before their parents. A migration that only changes data and leaves no schema to remove must still be registered with an empty object ({}).
• If a migration adds durable schema that REVERTIBLE_SCHEMA cannot currently describe, extend the downgrade script and its tests in the same change. Do not use --allow-unmapped as an implementation or CI workaround.
• After adding or changing a launcher migration or its downgrade mapping, run node scripts/axolotl/downgrade-app-db.test.mjs; this is part of the CI guardrails. Add or update downgrade test coverage when introducing a new mapping shape or rollback behavior.
• Do not start a migration-watching development process while migration files are still being edited. Finish the migration and its upgrade tests first, then start the app once to apply it.

Code Guidelines

Temporary Test Files

• Delete test files created only for task-local verification after the tests complete. Do not leave temporary test files in the worktree unless the user explicitly asks to keep them.

Comments

• DO NOT use "heading" comments like: === Helper methods ===.
• Use doc comments, but avoid inline comments unless ABSOLUTELY necessary for clarity. Code should aim to be self documenting!

Frontend Styling: Prefer Tailwind Utilities

• Express UI styling with Tailwind utility classes directly on elements. Never add a custom CSS class that only aliases one or a few declarations a utility can express verbatim. BAD: .foo { margin-top: 0.5rem } plus class="foo". GOOD: class="mt-2".
• Use the shared tokens and nothing else: the Tailwind preset lives at packages/tooling-config/tailwind/tailwind-preset.ts, theme variables in packages/assets/styles/variables.scss. Standard mappings: --gap-xs/sm/md/lg/xl → gap-1/2/3/4/6, var(--color-text-primary) → text-[var(--color-text-primary)], var(--color-text-tertiary) → text-[var(--color-text-tertiary)], var(--surface-N) → bg-surface-N / border-surface-N, var(--color-divider) → border-divider, var(--radius-*) → rounded-[var(--radius-*)]. Never reference CSS variables that are not defined in the shared theme (e.g. --color-text-secondary is undefined in the desktop app) — an undefined variable silently disables the declaration.
• Custom classes are acceptable only where utilities cannot express the styling:
  • Anchors for :deep/child-element/pseudo-element selectors and [data-size]-style compound state rules that must keep working;
  • Animated states (@keyframes, transitions), ::before/::after with content, scrollbar pseudo-elements;
  • Platform-conditional rules (.mac/.windows), non-standard-breakpoint media queries, and third-party/rendered content (markdown, terminals, canvas, editors);
  • Genuinely reusable visual variants composed with @apply (prefer @apply over hand-written declarations when composing utilities into a component class).
• In scoped <style> blocks, a rule whose declarations each map 1:1 to utilities is a violation: put the utilities on the element and delete the rule. Do not define utility-alias classes even when scoped — they get duplicated across components and drift.
• Do not copy a style block from one component into another; extract a shared component, an @apply-based class, or use utilities inline.

Bash Guidelines

Output handling

• DO NOT pipe output through head, tail, less, or more
• NEVER use | head -n X or | tail -n X to truncate output
• IMPORTANT: Run commands directly without pipes when possible
• IMPORTANT: If you need to limit output, use command-specific flags (e.g. git log -n 10 instead of git log | head -10)
• ALWAYS read the full output — never pipe through filters

General

• Do not create new non-source code files (e.g. Bash scripts, SQL scripts) unless explicitly prompted to
• For Frontend, use the existing package fix scripts for commit-time automatic fixes as described above. For lint checks, only use the prepr commands; do not use ad hoc lint, typecheck, or tsc commands.
• Types in @modrinth/utils are considered highly outdated, if a component needs them, check if you can switch said component to use types from packages/api-client
• When provided problems, do not say "I didn't introduce these problems" (shifting the blame/effort) - just fix them.

Edit Tool - Whitespace Handling (CLAUDE ONLY)

The Read tool uses → to mark where line numbers end and file content begins.

Rule: Copy the EXACT whitespace that appears after the → marker.

• Whatever appears between → and the code text is what's actually in the file
• That whitespace must be used EXACTLY in Edit tool's old_string
• Don't count arrows, don't interpret - just copy what's after the →

Example: 14→ private byte tag; For Edit, use: private byte tag; (copy everything after →, including the two tabs)

If Edit fails: Stop and explain the problem. Do not attempt sed/awk/bash workarounds.

IMPORTANT: Trust the Read tool output. Copy what's after → into Edit immediately. DO NOT verify with sed/od/grep first - that's wasting time and the instructions already tell you to stop if Edit fails, not to pre-verify.

Standards

Standards available at the @standards/ folder. Read the relevant standard before working on related code:

• @standards/frontend/SURFACE_SYSTEM.md — UI elevation/separator tokens; consult on any UI work using surfaces or strokes
• @standards/frontend/MODALS.md — regular and multistage modal APIs; consult before building or changing any modal
• @standards/frontend/ADDING_API_MODULES.md — adding a new module to packages/api-client
• @standards/frontend/DEPENDENCY_INJECTION.md — the provide/inject DI layer for platform abstraction and page-level context
• @standards/frontend/INTERNATIONALIZATION.md — translatable strings, ICU message format, and i18n conventions
• @standards/frontend/FIGMA_MCP_USAGE.md — translating Figma designs into Vue components via the Figma MCP server
• @standards/maintaining/CHANGELOG.md — changelog entry style; consult when writing or reviewing changelog entries