chore: initialize proxyctl specification

docs/agents/domain.md

@@ -0,0 +1,35 @@
+# Domain Docs
+
+How engineering skills should consume this repo's domain documentation.
+
+## Before exploring, read these
+
+- `CONTEXT.md` at the repo root
+- Relevant ADRs under `docs/adr/`
+
+If these files do not exist, proceed silently. The domain-modeling flow creates
+them lazily when terms or decisions are resolved.
+
+## File structure
+
+This is a single-context repo:
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+└── src/
+```
+
+## Use the glossary's vocabulary
+
+Use terms as defined in `CONTEXT.md`. Do not drift to synonyms the glossary
+explicitly avoids.
+
+If a needed concept is missing, reconsider whether new language is necessary or
+note the gap for `/domain-modeling`.
+
+## Flag ADR conflicts
+
+If proposed work contradicts an existing ADR, surface the conflict explicitly
+rather than silently overriding it.

docs/agents/issue-tracker.md

@@ -0,0 +1,30 @@
+# Issue tracker: Local Markdown
+
+Issues and specs for this repo live as Markdown files in `.scratch/`.
+
+## Conventions
+
+- One feature per directory: `.scratch/<feature-slug>/`
+- The spec is `.scratch/<feature-slug>/spec.md`
+- Implementation issues are one file per ticket at
+  `.scratch/<feature-slug>/issues/<NN>-<slug>.md`
+- Tickets are numbered from `01`
+- Comments and conversation history are appended under `## Comments`
+
+## When a skill says "publish to the issue tracker"
+
+Create a new file under `.scratch/<feature-slug>/`, creating the directory if needed.
+
+## When a skill says "fetch the relevant ticket"
+
+Read the referenced file. The user will normally provide its path or issue number.
+
+## Wayfinding operations
+
+- Map: `.scratch/<effort>/map.md`
+- Child ticket: `.scratch/<effort>/issues/NN-<slug>.md`
+- `Type:` records `research`, `prototype`, `grilling`, or `task`
+- `Status:` records `claimed` or `resolved`
+- `Blocked by: NN, NN` declares blocking relationships
+- Claim a ticket by setting `Status: claimed`
+- Resolve it by adding `## Answer`, setting `Status: resolved`, and updating the map

docs/research/linux-proxy-targets.md

@@ -0,0 +1,92 @@
+# Linux proxy configuration targets
+
+## Question
+
+Which commonly used Linux tools need proxy configuration outside the interactive Shell's `HTTP_PROXY`/`HTTPS_PROXY`/`ALL_PROXY` environment?
+
+## Key distinction
+
+“Does not support proxy environment variables” and “does not inherit the current Shell environment” are different problems. Several tools support the variables when present in their own process, but daemons, desktop applications, and commands launched through privilege boundaries often do not receive the interactive Shell's values.
+
+## Findings
+
+### Strong candidates for dedicated Targets
+
+#### Docker daemon
+
+The daemon has its own startup environment and does not inherit later changes to an interactive Shell. Docker supports daemon proxy settings in `daemon.json`, CLI flags, or the daemon service environment, and recommends `daemon.json`. A dedicated Target is justified because it affects daemon operations such as registry access and normally requires a daemon restart.
+
+Source: [Docker — Configure the daemon to use a proxy](https://docs.docker.com/engine/daemon/proxy/)
+
+#### Docker container/build defaults
+
+Docker's client-side `~/.docker/config.json` proxy configuration injects proxy environment variables and build arguments into **new containers and builds**. Docker explicitly states that this does not configure the Docker CLI or daemon and does not affect existing containers. This is a distinct Target from Docker daemon.
+
+Source: [Docker — Configure Docker to use a proxy server](https://docs.docker.com/engine/cli/proxy/)
+
+#### GNOME desktop proxy
+
+GNOME exposes a system proxy setting with None, Manual, and Automatic modes. Its documentation says applications using the network connection use the selected setting. This is valuable for graphical applications that consume desktop settings rather than an interactive Shell's environment.
+
+Source: [GNOME Help — Define proxy settings](https://help.gnome.org/users/gnome-help/stable/net-proxy.html.en)
+
+#### systemd system services
+
+Processes launched by the system service manager generally do not inherit the manager's environment automatically. Their environment is assembled from sources including `Environment=`, `EnvironmentFile=`, and explicitly passed manager variables. Therefore changing the current Shell environment does not reconfigure already managed system services.
+
+This is a real configuration gap, but an unrestricted “all systemd services” Target would be too broad. Individual daemon integrations should be added only when there is a concrete use case.
+
+Sources:
+
+- [systemd.exec — Environment variables in spawned processes](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#Environment%20Variables%20in%20Spawned%20Processes)
+- [systemd.exec — Environment= and EnvironmentFile=](https://www.freedesktop.org/software/systemd/man/latest/systemd.exec.html#Environment=)
+
+### Desktop applications
+
+#### Chromium
+
+Chromium documents use of system network settings, including system proxy settings, and supports explicit proxy command-line switches such as `--proxy-server` and `--proxy-bypass-list`. Its documented configuration surface is therefore the desktop/system setting or launch arguments, not the interactive Shell proxy variables.
+
+A separate Chromium Target is probably unnecessary if the tool supports the desktop's system proxy setting.
+
+Source: [Chromium — Network Settings](https://www.chromium.org/developers/design-documents/network-settings/)
+
+#### Firefox
+
+Firefox exposes its own proxy model with `none`, `system`, `manual`, `autoDetect`, and `autoConfig` modes, including HTTP, SSL, SOCKS, and bypass settings. The official enterprise policy schema provides a manageable configuration surface, but changing enterprise policy is intrusive for a personal switcher. Prefer desktop system proxy support first; consider a Firefox-specific Target only if users require manual Firefox profiles.
+
+Source: [Mozilla Policy Templates — Proxy](https://mozilla.github.io/policy-templates/#proxy)
+
+### Context-dependent candidate
+
+#### Snap on Ubuntu Core
+
+Snap's documented system options include `proxy.http`, `proxy.https`, and `proxy.ftp`, but the documentation marks these options as available only on Ubuntu Core. This is not a strong general-desktop MVP Target.
+
+Source: [Snapcraft — System options](https://snapcraft.io/docs/reference/administration/system-options#heading--proxy)
+
+## Common tools that already support Shell proxy variables
+
+These are not strong dedicated Targets merely because they use package-specific configuration too:
+
+- **APT** supports `http_proxy` and `no_proxy`; it also supports persistent `Acquire::http::Proxy` configuration. A dedicated APT Target can still improve persistence and avoid environments being lost across `sudo`, but APT is not accurately described as lacking environment-variable support. Source: [Debian apt-transport-http(1), Proxy Configuration](https://manpages.debian.org/bookworm/apt/apt-transport-http.1.en.html#Proxy_Configuration)
+- **DNF** uses curl proxy environment variables when its `proxy` option is unset. Source: [DNF Configuration Reference — proxy](https://dnf.readthedocs.io/en/latest/conf_ref.html#proxy-label)
+- **Git** normally uses `http_proxy`, `https_proxy`, and `all_proxy`; `http.proxy` overrides them. Source: [Git config — http.proxy](https://git-scm.com/docs/git-config#Documentation/git-config.txt-httpproxy)
+
+## Recommended scope
+
+For the first release:
+
+1. Shell environment
+2. APT — for persistent/sudo-safe configuration, not because APT lacks environment support
+3. Docker daemon
+4. Docker containers/builds
+5. GNOME desktop proxy, **only if GNOME is detected**
+
+Defer:
+
+- Firefox-specific settings
+- Chromium-specific launch flags
+- arbitrary systemd services
+- Snap/Ubuntu Core
+- desktop integrations other than GNOME until their official configuration contracts are researched