1 files changed, 61 insertions, 0 deletions
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..b851b4d
--- /dev/null
+++ b/README.md
@@ -0,0 +1,61 @@
+# panto-codex
+
+Codex subscription defaults for panto. Mark named tables; the extension fills the boilerplate.
+
+## Setup
+
+Requires panto's `configure(config)` extension hook (before auth/provider validation).
+
+```toml
+[extensions]
+rocks = ["panto-codex"]
+
+[auth.codex]
+panto_codex_extension = true
+
+[providers.codex]
+auth = "codex"
+panto_codex_extension = true
+```
+
+```sh
+panto auth login codex
+panto models sync
+panto models list codex:
+```
+
+## Defaults
+
+| Setting | Value |
+| --- | --- |
+| Auth | Codex device OAuth; credentials and refresh stay in panto |
+| Provider | Responses API with the Codex dialect; `openai` model catalog |
+| Endpoint | `https://chatgpt.com/backend-api/codex` |
+| Headers | `OpenAI-Beta: responses=experimental`, `originator: codex_cli_rs` |
+
+## Rules
+
+- Only `panto_codex_extension = true` opts in; auth/provider names are arbitrary.
+- Keep `providers.<name>.auth` explicit; the extension never guesses linkage.
+- Explicit values win, including nested endpoints and case-insensitive headers.
+- Defaults are independent per table/load; no config files are rewritten.
+- No network or credentials in Lua; env/session placeholders stay raw for panto.
+- Rigs must include this extension themselves; `--no-extensions` skips it.
+
+Flat and endpoint-table provider configurations are supported. Overrides must
+remain valid panto configuration.
+
+## Packaging / checks
+
+```sh
+panto lua _selfcheck.lua
+luarocks lint panto-codex-scm-1.rockspec
+```
+
+The rockspec maps `require("panto-codex")` to `init.lua`; no dependencies
+beyond Lua.
+
+## References
+
+- [OpenAI device-login implementation](https://github.com/openai/codex/blob/main/codex-rs/login/src/device_code_auth.rs)
+- [OpenAI authentication documentation](https://developers.openai.com/codex/auth/)