Write beginning-contributor documentation: launcher architecture, client/server communication, dev environment, AI-agent setup, and the contribution/issue-selection workflow

[swstegall]

Summary

There is no onboarding documentation for new contributors. A newcomer currently has to reverse-engineer the launcher pipeline (detect → patch → manage Wine → login → launch), the module layout, the client↔server login/patch flow, the dev-environment workflow, and the contribution process from the source. This issue tracks writing a beginner-friendly documentation set so someone can go from zero → building the launcher → picking up an issue → opening a PR using only the docs.

Scope / format: for now the documentation lives as plain Markdown files in the repo (under docs/, with CONTRIBUTING.md / CLAUDE.md / AGENTS.md at the repo root where convention expects them). No docs site / generator yet. Each deliverable below can land as its own PR. Link the new docs from README.md.

This is the launcher counterpart of the Garlemald-Server contributor-docs issue. Unlike the server, the client has no Lua runtime, so there is no scripting-runtime deliverable here.

---

Deliverable 1 — Launcher architecture & client/server communication (docs/architecture.md)

What the launcher does end-to-end, how its modules are organized, and how it talks to a Garlemald server.

• The launcher pipeline: detect an installed FFXIV 1.x client → patch it forward to 2012.09.19.0001 (CRC32-verified ZiPatch apply) → on macOS/Linux download & manage a self-contained Wine runtime → run the login handshake against the selected private server → launch ffxivgame.exe.
• Module responsibilities (single-crate garlemald-client, src/):
  • app/ — the eframe/egui GUI (server picker, patch progress, launch button).
  • servers/ — the server registry / selection (persisted as servers.xml, each entry carrying a loginUrl).
  • patcher/ + patch_format/ — patch download (ureq) and the ZiPatch format apply (2010.09.18.0000 → 2012.09.19.0001).
  • login/ + crypto/ — the login flow and session crypto.
  • platform/ — per-OS support: Wine runtime/prefix management on macOS/Linux, native Win32 on Windows.
  • launcher/ — assembling the argv/environment and starting ffxivgame.exe.
  • config/ — config/data paths and preferences.toml. version.rs — the launcher version.
• How the client communicates with the server:
  • Login: login/ opens the selected server's loginUrl in a native WebView (tao + wry) and waits for a redirect to the custom scheme ffxiv://login_success?sessionId=…, capturing the session id. Document this WebView → custom-scheme handshake (anchors: src/login/mod.rs, src/login/webview.rs).
  • Patching: HTTP(S) patch download via ureq from the server/CDN.
  • Gameplay: after launch, the game client itself connects to the server's lobby/world/map services (ports 54994 / 54992 / 1989) — the launcher's job ends at handing off a patched install + a valid session. Cross-reference the Garlemald-Server architecture doc for the server side, and note the hard client-version gate (2012.09.19.0001).
• Include an ASCII flow diagram: detect → patch → (Wine setup) → WebView login (sessionId) → launch → game connects to server.

Deliverable 2 — Developer environment (docs/dev-environment.md)

• Prerequisites & build/run: Rust toolchain (pinned in rust-toolchain.toml), per-platform notes (macOS Apple Silicon + Intel, Linux, Windows) including the eframe/egui GUI backends (glow, wayland, x11); cargo build --release / cargo run.
• Enabling logging:
  • Launcher log verbosity via RUST_LOG (the launcher uses env_logger with a default of info — src/main.rs:30; e.g. RUST_LOG=debug, or per-module like RUST_LOG=garlemald_client::patcher=trace).
  • Wine/game-side logging: <data_dir>/logs/wine.log and the preference flag that raises the Wine log ceiling (src/config/preferences.rs).
• Where launcher state lives, and how to reset it (the launcher analogue of the server's "delete/restore saves"):
  • Config + data live under ProjectDirs("me", "stegall", "garlemald-client") — config_dir() (holds preferences.toml, servers.xml) and data_dir() (holds the self-managed Wine runtime/prefix, logs). On macOS that's ~/Library/Application Support/me.stegall.garlemald-client/ (src/platform/macos.rs). Anchors: src/config/paths.rs.
  • Document how to get a clean slate: clearing/recreating the Wine prefix, resetting preferences.toml / servers.xml, and re-detecting / re-patching an install — plus where the detected/patched game install is referenced.
• Working against a local Garlemald-Server: bring up the server stack, register an account via its web auth, add a 127.0.0.1 server entry (with its loginUrl), and run the launcher end-to-end against it.

Deliverable 3 — AI-agent setup for Claude & OpenAI (docs/agents.md)

• Create and maintain CLAUDE.md (Claude Code / Claude Agent SDK) and AGENTS.md (OpenAI Codex / agents) at the repo root — they do not exist yet. They should capture: how to build/run, where subsystems live (app/patcher/login/platform/…), the AGPL header rules, the develop → PR flow, and the cargo fmt/clippy/test gates the agent must satisfy. Note the cross-platform caveat (Wine/WebView paths differ by OS).
• How to run an agent on an issue: clone your fork, branch off develop, hand the agent the issue as its task (it reads CLAUDE.md/AGENTS.md), let it build + test, then open a PR. Cover both Claude (Claude Code CLI / claude.ai/code) and OpenAI (Codex) setups, including any API-key / auth prerequisites.
• Guardrails: agents must respect the licensing/header conventions, never cross-commit between the workspace's independent repos, and keep CI green before raising a PR.

Deliverable 4 — Contribution & issue-selection workflow (CONTRIBUTING.md)

A step-by-step for a brand-new contributor:

1. Request access — ask (via the project Discord) to be added as a collaborator on the Garlemald-Client repo and the Garlemald project board (Garlemald Project).
2. Pick an issue — choose one from the board's Ready column, assign it to yourself, and move it to In progress.
3. Set up your fork — fork the repo and create a feature branch off develop in your fork (link to docs/RELEASING.md for the develop → main branching model).
4. Contribute — make the change, keep CI green (fmt / clippy / build / test), and open a PR into upstream develop, linking the issue. Move the board card to the appropriate column on PR.

---

Acceptance criteria

• docs/architecture.md — launcher pipeline, module responsibilities, the WebView login + patch/launch client↔server flow, and a flow diagram.
• docs/dev-environment.md — build/run (GUI backends), RUST_LOG/env_logger + Wine-log toggles, launcher-state locations + reset, and running against a local Garlemald-Server.
• docs/agents.md + root CLAUDE.md + root AGENTS.md — agent setup for Claude and OpenAI to work issues.
• CONTRIBUTING.md — collaborator request, board Ready → In progress, fork + develop branch, PR into upstream develop.
• All new docs are linked from README.md, and a newcomer can complete zero → building the launcher → assigned issue → PR using only these documents.

Source pointers (where to mine when writing each doc)

• Pipeline/modules: src/{app,servers,patcher,patch_format,login,crypto,platform,launcher,config}/, src/main.rs, src/version.rs
• Login/handshake: src/login/{mod.rs,webview.rs}, src/crypto/
• Patching: src/patcher/, src/patch_format/
• Platform / Wine: src/platform/ (macos.rs, etc.)
• Logging + paths: src/main.rs (env_logger), src/config/{paths.rs,preferences.rs}
• Branching/release: docs/RELEASING.md
• Server side (cross-reference): the Garlemald-Server docs/architecture.md

Each deliverable can be its own PR/sub-issue; split if that keeps reviews small.