---
name: archlinux
os: lnx
disable-model-invocation: true
description: "Use for Arch Linux setup and troubleshooting: pacman, AUR/PKGBUILD/makepkg, upgrades, maintenance, boot, services, packages. Not generic Linux or Raspberry Pi."
---

# Arch Linux

Arch-specific system/config/troubleshooting/pkg help.
Confirm Arch via `/etc/os-release`; `pacman` alone is not proof.
Keep volatile facts out of memory; fetch current docs.

## Route

- System/maintenance/upgrade → `references/system.md`
- Config changes/mirrors/hooks → `references/config.md`
- Troubleshooting failures → `references/troubleshooting.md`
- Software/pkg/AUR/build issues → `references/software.md`

## Fresh Truth

Local first:

```sh
man pacman pacman.conf makepkg PKGBUILD alpm-hooks paccache pacdiff
```

Web when local docs missing/stale:

```text
https://man.archlinux.org/man/<page>.<section>.en
https://wiki.archlinux.org/title/<Topic>
https://archlinux.org/news/
https://archlinux.org/packages/
https://aur.archlinux.org/
```

Before upgrade advice, check Arch News.
For exact package/repo/current syntax, use current man/wiki/package pages, not memory.

## Local Wiki

If offline/frequent Arch work, check:

```sh
pacman -Qq arch-wiki-docs arch-wiki-lite wikiman 2>/dev/null
```

If absent, suggest installing one.
Do not require it.

## Safety

- No partial upgrades.
  Avoid `pacman -Sy <pkg>`; use full upgrade flow.
- If `-Sy` happened and `-Su` failed:
  resolve + complete upgrade before other pkg ops.
- AUR = untrusted user content.
  Inspect `PKGBUILD`, `*.install`, patches before build.
- `.pacnew`/`.pacsave` need manual merge; never blind overwrite.
- Avoid unless current Arch News/wiki explicitly says so:
  `--overwrite`, `-Rdd`, `--nodeps`, blind `--noconfirm`.
- Do not symlink libraries to fix soname errors; complete/recover upgrade.

## Root Delegation

Do not run root/admin mutations yourself.
Follow [linux](../linux/SKILL.md) for system boundaries and human-run escalation, even when the user authorizes the change.
Give exact command for user to run.
Detect user's shell first for syntax compatibility:

```sh
printf 'SHELL=%s\n' "$SHELL"
getent passwd "$(id -un)" | cut -d: -f7
```

Command style:

- unknown/fish/nu → one simple command per line; avoid arrays, functions,
  process substitution, brace expansion.
- env vars → use `env VAR=value command` for portability.
- complex flow → write tiny script or split steps.
- state impact + rollback/log path before mutating `/etc`, pacman DB, boot,
  services.