Add provider setup shortcuts on upstream base

.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,44 @@
+---
+name: Bug report
+about: Report a problem with the shim, ChatGPT passthrough, or the Desktop patch
+labels: bug
+---
+
+## What happened
+
+<!-- Short description. What did you run, what did you expect, what did you get? -->
+
+## Environment
+
+- Codex Desktop / CLI version: `codex --version` ->
+- OS: macOS arm64 / x86_64 / Linux distro / WSL ->
+- Python version: `python3 --version` ->
+- codex-shim commit: `git -C <path-to-codex-shim> rev-parse --short HEAD` ->
+
+## Repro
+
+```bash
+# Exact commands that reproduce the issue.
+```
+
+## Output
+
+```text
+# Output of: codex-shim status
+```
+
+```text
+# Last ~80 lines of .codex-shim/shim.log (redact API keys / auth tokens).
+```
+
+## Route
+
+- [ ] Configured BYOK/upstream model (slug: `____`)
+- [ ] `gpt-5.5` ChatGPT passthrough
+- [ ] Codex Desktop picker / ASAR patch
+- [ ] Other (please describe)
+
+## Additional context
+
+<!-- Anything else useful: provider name, model id, did this work in a
+previous Codex Desktop build, etc. -->

.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,33 @@
+---
+name: Feature request
+about: Suggest a new capability or behavior change
+labels: enhancement
+---
+
+## What problem are you trying to solve
+
+<!-- Concrete user-visible problem. "Codex picker hides X" is good.
+"Make it more flexible" is not. -->
+
+## Proposed change
+
+<!-- What should the shim do? Where in the code does it land
+(translate.py, server.py, cli.py, catalog.py)? -->
+
+## Alternatives considered
+
+<!-- Other approaches you thought about and why this one wins. -->
+
+## Scope
+
+- [ ] New provider translation
+- [ ] New Codex Desktop / CLI compatibility
+- [ ] CLI / UX
+- [ ] Docs
+- [ ] Other
+
+## Are you willing to send a PR
+
+- [ ] Yes
+- [ ] Maybe, with guidance
+- [ ] No

.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    name: pytest (${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install package + dev extras
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+      - name: Compile check
+        run: python -m compileall codex_shim/ -q
+      - name: Run tests
+        run: python -m pytest tests/ -q

CHANGELOG.md

@@ -0,0 +1,74 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is loosely based on [Keep a Changelog](https://keepachangelog.com/),
+and this project does not yet follow semantic versioning (pre-1.0).
+
+## Unreleased
+
+### Added
+
+- GitHub Actions CI (`.github/workflows/ci.yml`) running pytest and
+  `compileall` on Python 3.11 and 3.12.
+- `[project.optional-dependencies] dev` in `pyproject.toml` so
+  `pip install -e ".[dev]"` pulls `pytest` and `pytest-asyncio` in one step.
+- `CONTRIBUTING.md` documenting the dev loop, what kinds of PRs are useful,
+  and what to include in bug reports.
+- `.github/ISSUE_TEMPLATE/` with structured bug and feature request templates.
+- `CHANGELOG.md` (this file).
+
+### Changed
+
+- Reframed the project around a generic all-model Codex shim instead of any
+  single upstream app or model store.
+- Made `~/.codex-shim/models.json` the canonical default settings file.
+- Renamed the generated Codex provider to `codex_shim` / "Codex Shim".
+- Settings now prefer a generic top-level `models` array with snake_case keys,
+  while still accepting `customModels` and camelCase aliases for existing
+  exports.
+
+## 2026-05-25 — Auth-gated ChatGPT passthrough + docs hardening
+
+### Added
+
+- `settings.chatgpt_passthrough_available()` checks `~/.codex/auth.json` for a
+  usable `tokens.access_token`. The synthetic `gpt-5.5` slug is now only
+  advertised in `/health`, `/v1/models`, `codex-shim list`, and the generated
+  `custom_model_catalog.json` while that token is present.
+- `_load_models()` in the CLI wraps model settings loading with actionable
+  errors for missing files and invalid JSON.
+- `_entrypoint()` in the CLI catches `BrokenPipeError` at the boundary so
+  piping `codex-shim list` into `head`/`grep` exits cleanly instead of dumping
+  a traceback.
+- Regression tests covering auth-gating, CLI error UX, settings aliases, and
+  catalog generation.
+
+### Changed
+
+- `/health` payload now includes `chatgpt_passthrough: bool` and reports the
+  real model count instead of always-plus-one.
+- `cli._resolve_model_slug("gpt-5.5", ...)` raises `SystemExit` telling the
+  user to run `codex login` when auth.json is missing, instead of returning a
+  slug that would 401 on first request.
+- `default_model_slug` picks the first configured BYOK model when passthrough
+  is not usable, instead of unconditionally returning `gpt-5.5`.
+- README install section recommends `pip install -e .` as the primary path.
+- README benchmarking section: replaced an unsupported "7x fewer input tokens
+  / 5–10x faster" claim with honest anecdata and a note that no reproducible
+  benchmark script ships with the repo yet.
+
+### Fixed
+
+- Codex Desktop picker / `/v1/models` no longer offers `gpt-5.5` when there's
+  no Codex login, removing the misleading "select it to get a 401" footgun.
+
+## 2026-05-25 — Initial public hardening
+
+### Added
+
+- Public-grade README rewrite covering install, ChatGPT passthrough, tool
+  calls, computer use, prompt catching/proxy patterns, benchmarking, security,
+  limitations, troubleshooting, and contributing.
+- `pyproject.toml` build-system, `readme`, `license`, `authors`, `keywords`,
+  classifiers, and project URLs.

CONTRIBUTING.md

@@ -0,0 +1,60 @@
+# Contributing to codex-shim
+
+Thanks for hacking on the shim. Issues and PRs welcome.
+
+## Dev loop
+
+```bash
+git clone https://github.com/0xSero/codex-shim
+cd codex-shim
+python3 -m pip install -e ".[dev]"
+
+python3 -m pytest tests/ -q
+python3 -m compileall codex_shim/ -q
+```
+
+CI runs the same commands on Python 3.11 and 3.12 via
+`.github/workflows/ci.yml`. Match it locally before opening a PR.
+
+## What kinds of changes are useful
+
+- Translation fixes for tricky tool-call / reasoning streams, with a
+  captured fixture under `tests/` proving the bug and the fix.
+- New provider translations (e.g. a new chat-completions or
+  Anthropic-shaped upstream). Add a test that exercises the new shape end
+  to end through `ShimServer`, the way `test_server.py` does.
+- Compatibility notes / safer detection for new Codex Desktop builds,
+  especially around the ASAR picker patch needle in
+  `codex_shim/cli.py::patch_codex_app`.
+- Doc patches that name a specific build / version. "I tested on Codex
+  Desktop 0.x.y on macOS arm64 and it did Z" is more useful than a
+  generic warning.
+
+## Code style
+
+- Match the surrounding file. No new dependencies without a reason.
+- Keep `codex_shim/server.py` translation behavior covered by tests in
+  `tests/test_server.py` or `tests/test_translate.py` — tool-call shape
+  bugs are easy to miss by eyeballing streams.
+- Don't include API keys, ChatGPT access tokens, or `auth.json` contents
+  in fixtures, logs, or test data. Use synthetic tokens (`"stub"`,
+  `"secret"`) like the existing tests.
+
+## Reporting bugs
+
+Please include:
+
+- Codex Desktop / CLI version (`codex --version` and the Desktop About
+  panel).
+- OS (macOS arm64 / x86_64 / Linux distro / WSL).
+- Output of `codex-shim status` and the last ~80 lines of
+  `.codex-shim/shim.log` with API keys redacted.
+- Whether the model is a configured BYOK/upstream entry or the `gpt-5.5`
+  ChatGPT passthrough.
+- Minimal repro: the exact `codex-shim …` invocation and what you
+  expected vs. what happened.
+
+## Security
+
+Don't open public issues for security problems. Email or DM the
+maintainer with details and a repro and we'll coordinate a fix.