# sshPilot documentation

User-facing documentation (guides, FAQ) lives on the
[wiki](https://github.com/mfat/sshpilot/wiki). This folder holds developer and
platform documentation that versions with the code:

| Document | Contents |
| --- | --- |
| [architecture.md](architecture.md) | How the app is put together: the single SSH connection/auth path, secret backends, askpass mechanics, platform notes and debugging. Read this before changing how the app connects. |
| [running-from-source.md](running-from-source.md) | Running from source on Linux: the hybrid (system PyGObject + venv) and pure-venv (pip-built PyGObject) approaches, plus dev/test setup and troubleshooting. |
| [INSTALL-macos.md](INSTALL-macos.md) | Installing and running from source on macOS (Homebrew GTK stack). |
| [keyboard-shortcuts.md](keyboard-shortcuts.md) | Full shortcut reference for Linux and macOS. |
| [accessibility-automation.md](accessibility-automation.md) | What SSH Pilot exposes over AT-SPI, the rules for accessible names, and what UI automation can and cannot drive through it (Wayland, VTE, drag-and-drop). |
| [diagnostics.md](diagnostics.md) | Where the logs live, the crash report, the `--diagnostics` flags and the bug-report bundle. |
| [agent-architecture.md](agent-architecture.md) | The Ptyxis-style agent that provides host shells with job control under Flatpak. |
| [SSH-config-parsing.md](SSH-config-parsing.md) | Design rationale for host discovery: display-only parsing, `ssh -G` as the source of truth. |
| [command-converter.md](command-converter.md) | The `ssh ...` command-line → connection-data parser (used by CLI connect and available for paste/import). |
| [PLUGIN_SDK.md](PLUGIN_SDK.md) | The plugin API reference: context objects, protocol backends, UI pages, credential dialogs. |
| [IDENTITY_PROVIDERS.md](IDENTITY_PROVIDERS.md) | The identity-provider contract (which key authenticates a connection, and who supplies it). |
| [CREDENTIAL_MANAGER.md](CREDENTIAL_MANAGER.md) | The credential export/backup layer and its secret backends. |
| [plugins/](plugins/) | Writing, packaging and publishing plugins, plus copyable templates. |

## Developer documentation paths

### Current architecture

Start with [architecture.md](architecture.md), then follow its links to the
specific subsystem reference under [architecture/](architecture/). The
daemon-only retirement is the active architecture workstream; current
ownership and boundaries are recorded in the linked ledger below.

The active cross-session retirement ledger for the remaining obsolete
in-process backend paths is [daemon-only-retirement.md](architecture/daemon-only-retirement.md).

### Current public API

Use [api/README.md](api/README.md) for the maintained Protocol 1.0/API 0.39
contract, with generated models and schemas linked from that overview.

### Historical migration records

Phase audits, completion matrices, and superseded implementation inventories
are preserved and explicitly labeled in
[history/frontend-neutral-migration/](history/frontend-neutral-migration/).

## Askpass debug log

The askpass helper and the daemon interaction broker write debug information
to `sshpilot-askpass.log` in the first available of:

1. `$SSHPILOT_ASKPASS_LOG_DIR`, if set
2. `$XDG_RUNTIME_DIR`
3. the system temporary directory

While a connection is active, the GUI also forwards new askpass lines into
the application logger (`ASKPASS: …`), so they appear under `--verbose` /
Help → View Logs. The Askpass category in the log viewer reads the same file.
