Modrinth-plus/AGENTS.md

Agent Instructions

Start by reading CLAUDE.md; it contains the upstream Modrinth monorepo rules. This fork adds Modrinth Plus work on top of those rules.

Repository Rules

• Preserve upstream Modrinth structure and style unless a Modrinth Plus feature requires a focused change.
• Keep desktop app work in the existing app boundaries: apps/app-frontend, apps/app, and packages/app-lib.
• Conserve context tokens: search with rg or targeted file lists first, read only files needed for the task, summarize large outputs, and avoid generated folders, dependency folders, build outputs, or full logs unless directly relevant.
• Do not commit secrets, .env files with private values, private keys, certificates, or tokens.
• At the start of every user-requested task, briefly check for upstream repository updates and apply a safe fast-forward pull when the working tree is clean. If local changes exist, do not overwrite them.
• If GITEA_TOKEN is available locally, use it only for read-only Gitea API checks such as private repository metadata, package-read visibility, and Actions run status. Never print, commit, or store the token.
• After pushing commits that trigger a Gitea workflow, poll the workflow run until it succeeds. If it fails or is cancelled, inspect the failing job/logs, fix the issue when in scope, push again, and repeat the workflow check loop. Fixing and pushing a workflow failure is not a stopping point.
• Gitea Actions artifacts are not Gitea Package Registry packages. If the user expects a package/download entry, add or verify an explicit registry publish step and verify the package URL after the workflow succeeds.
• Keep Codex kit files in source control for agents, but exclude them from user-facing installer/package/release artifacts unless the user explicitly asks to ship repository-maintenance files.

Commands

Use upstream commands where possible:

pnpm install
pnpm --filter @modrinth/app-frontend run lint
cargo fmt --check
cargo clippy --package theseus

If local Node/Rust toolchains are unavailable, use the Gitea runner as the authoritative verification loop.

Security Notes

• Connected Library supports public HTTPS raw manifest URLs only in v1.
• Keep private Git repository authentication out of Connected Library until token storage is designed.
• Document new external network calls in docs/security-review.md.
• Keep CI publishing secrets in repository or organization secrets. REGISTRY_TOKEN is the Gitea package publishing secret.
• Use URL-safe package filenames when publishing to a registry. Do not put raw artifact names with spaces or punctuation directly into upload URLs.