Community AppImage reports: Linux distro, launch environment, and Pi config issues

[IgorWarzocha]

Goal

Track AppImage-specific Linux problems in one place.

The current report is: on Ubuntu, the AppImage opens, but models/providers configured for Pi do not show up in Howcode. I could not reproduce it on my Omarchy/Arch machine; the same AppImages read ~/.pi/agent/models.json there.

What belongs here

Examples of reports that fit this thread:

• AppImage starts, but custom Pi models/providers from ~/.pi/agent/models.json do not appear.
• AppImage works when launched from a terminal but not from a desktop entry, file manager, app launcher, or AppImage helper.
• $HOME, XDG_CONFIG_HOME, or PI_CODING_AGENT_AGENT_DIR differs between Pi CLI and Howcode AppImage.
• AppImage portable home/config changes where Howcode/Pi looks for configuration.
• Shell-command or environment-variable auth in models.json works in Pi CLI but not in AppImage.
• A distro-specific AppImage packaging/runtime issue appears on Ubuntu, Fedora, Debian, Arch, etc.

If the issue is a crash, a broken update artifact, or a confirmed single root cause, please open a separate bug and link it here.

How to report an AppImage issue

Please comment with as many of these as possible:

### What goes wrong?
Short description of the AppImage behavior.

### Expected behavior
What works in Pi CLI, dev build, or another install method?

### AppImage and distro
- Howcode AppImage version:
- Distro/version:
- Desktop environment/window manager:
- Install/launch method: terminal, desktop entry, AppImageLauncher, file manager, etc.

### Pi config paths
Run these from the same terminal you use to launch the AppImage:

```bash
echo "HOME=$HOME"
echo "XDG_CONFIG_HOME=$XDG_CONFIG_HOME"
echo "PI_CODING_AGENT_AGENT_DIR=$PI_CODING_AGENT_AGENT_DIR"
ls -la ~/.pi/agent ~/.pi/agent/models.json

Reproduction steps

1. Configure Pi models/providers in ~/.pi/agent/models.json.
2. Launch the AppImage via …
3. Open model picker / start a session / run …
4. Observe …

Logs or screenshots

Attach any terminal output, screenshots, or redacted config snippets.

## Maintainer triage
When a report is confirmed:

- First separate environment/config-path problems from packaged runtime/resource problems.
- Verify whether `PI_CODING_AGENT_AGENT_DIR` is set; Pi uses `$PI_CODING_AGENT_AGENT_DIR/models.json` when present, otherwise `~/.pi/agent/models.json`.
- Check terminal launch versus desktop launch before assuming a packaging bug.
- Split confirmed root causes into child issues when the fix is specific, for example environment inheritance, docs, model picker diagnostics, or AppImage packaging.

## Starting points in the codebase
Likely files for AppImage/Pi config path problems:

- `electron-builder.yml`
- `src/electron/main/runtime/environment.ts`
- `src/electron/main/runtime/app-paths.ts`
- `desktop/pi-module.ts`
- `desktop/runtime/composer-state.ts`
- `desktop/runtime-host/live-runtime-factory.ts`

Relevant Pi behavior:

- Pi's `getAgentDir()` uses `PI_CODING_AGENT_AGENT_DIR` when set.
- Otherwise it falls back to `~/.pi/agent`.
- Howcode currently builds model registries from `${agentDir}/models.json`.

## Acceptance criteria for this epic
- Community AppImage/distro reports have a clear place to collect evidence.
- Confirmed reports are either fixed directly or split into child issues/PRs.
- AppImage model/config behavior is documented clearly enough that users can verify paths without reading the source.
- The AppImage remains validated on at least one maintainer Linux setup and regressions on Ubuntu or other distros become actionable.