# 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:

```bash
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.