## Context

Currently SS port (8388), Trojan port (443), and passwords are manually configured in `group_vars` and Ansible Vault. The Surge client config at `docs/surge-client.conf` is a static reference with placeholders users must replace manually. This change automates credential generation and produces a ready-to-use Surge config.

## Goals / Non-Goals

**Goals:**
- Auto-generate random ports (within high-port range) and strong passwords on first deploy
- Persist generated credentials so subsequent playbook runs don't regenerate them
- Render a complete Surge client config with actual parameters after deployment
- Keep manual override possible for users who prefer to set their own values

**Non-Goals:**
- Key rotation automation (out of scope)
- Distributing the generated config to client devices

## Decisions

### 1. Credential generation: Ansible `password` lookup with file persistence

Use Ansible's `lookup('password', ...)` to generate credentials. This generates a random value on first run and persists it to a file on the Ansible controller, so subsequent runs reuse the same value.

```yaml
ss_password: "{{ lookup('password', 'credentials/ss_password length=32 chars=ascii_letters,digits') }}"
ss_port: "{{ lookup('password', 'credentials/ss_port chars=digits length=5') | int % 40000 + 10000 }}"
```

Credentials stored in `credentials/` directory (gitignored). Users can still override by setting variables in `group_vars` or via `--extra-vars`.

**Why over Ansible Vault with manual entry**: Zero-touch setup. New users don't need to manually create passwords or encrypt vault files.

### 2. Port ranges

- SS port: random in 10000–49999 range
- Trojan port: fixed at 443 (required for TLS camouflage — Trojan must listen on 443 to look like HTTPS)

Trojan port stays 443 because changing it defeats the purpose of HTTPS camouflage.

### 3. Surge config generation: local Jinja2 template rendered by Ansible

Create a new playbook task that runs on `localhost` (Ansible controller) after server deployment. It renders `templates/surge-client.conf.j2` using the actual deployed variables (relay IP, landing domain, ports, passwords) and writes to `output/surge-client.conf`.

The old static `docs/surge-client.conf` is removed. The template preserves the same rule structure (Sukka's rulesets, China direct, etc.).

### 4. Credential directory gitignored

Add `credentials/` and `output/` to `.gitignore` to prevent secrets and generated configs from being committed.

## Risks / Trade-offs

- **[Credential loss]** → If `credentials/` directory is deleted, new credentials are generated and servers must be re-provisioned. Mitigation: document backup instructions in README.
- **[Trojan port fixed at 443]** → Cannot randomize without breaking HTTPS camouflage. This is by design.
- **[Controller-local files]** → Credentials and output depend on the Ansible controller's filesystem. Mitigation: users can back up the `credentials/` directory.