chore: add Fern regen workflow docs and skills

Add AGENTS.md documenting the SDK regeneration workflow,
CLAUDE.md stub, and Claude Code skills for prepare-regen
and review-regen.

Author: lukeocodes

.claude/skills/prepare-regen.md

@@ -0,0 +1,17 @@
+# Prepare Repo for Fern SDK Regeneration
+
+Triggers: prepare regen, prepare for regeneration, prep for fern, new sdk gen, prepare sdk gen
+
+## Steps
+
+Read AGENTS.md for full context on the regeneration workflow.
+
+1. Fetch latest `main` and create a new branch: `lo/sdk-gen-<YYYY-MM-DD>` (use today's date).
+2. Push the branch to origin.
+3. Create an empty commit (`chore: initialize SDK regeneration branch`) if needed, then create a PR titled `chore: SDK regeneration <YYYY-MM-DD>` with body `## Summary\n- Fern SDK regeneration`.
+4. Read `.fernignore` and identify all frozen generated files (Client & Socket Clients, Type Fixes, Redact type, Listen Clients, Tests & WireMock). Do NOT unfreeze the "always frozen" files listed in AGENTS.md.
+5. Back up each identified file as `<filename>.bak` alongside the original.
+6. Remove their entries and associated comments from `.fernignore`.
+7. Stage the updated `.fernignore` and all `.bak` files.
+8. Commit as `chore: unfreeze files pending regen` and push.
+9. Report the PR URL and confirm the branch is ready for generator output.

.claude/skills/review-regen.md

@@ -0,0 +1,21 @@
+# Review Fern SDK Regeneration
+
+Triggers: review regen, review regeneration, diff regen, compare regen, post regen review
+
+## Steps
+
+Read AGENTS.md for full context on the regeneration workflow.
+
+1. Find all `.bak` files in the repo — these are the pre-regen manually-patched versions.
+2. For each `.bak` file, diff it against the corresponding newly generated file to show what changed.
+3. Identify which manual patches are still needed (the `.bak` has changes the generator doesn't produce).
+4. Present a summary of findings to the user, grouped by category:
+   - Patches no longer needed (generator now handles it)
+   - Patches still needed (must be re-applied)
+   - New changes from the generator worth noting
+5. Wait for user direction on which patches to re-apply.
+6. Re-apply confirmed patches to the generated files.
+7. Re-add entries to `.fernignore` for files that still carry manual patches.
+8. Delete all `.bak` files.
+9. Run `ruff check --fix`, `mypy --ignore-missing-imports src/deepgram/`, and `pytest` to verify.
+10. Commit as `chore: re-apply manual patches after regen` and push.

AGENTS.md

@@ -0,0 +1,65 @@
+# Agents
+
+## Fern SDK Regeneration
+
+### Overview
+
+This SDK is generated by [Fern](https://buildwithfern.com/). Most files under `src/deepgram/` are auto-generated and should not be edited directly. Some files have manual patches (custom auth, type fixes, WebSocket defaults, etc.) and are listed in `.fernignore` to prevent the generator from overwriting them.
+
+When a new Fern generator release is available, we prepare the repo so the generator can overwrite previously-frozen files, then re-apply manual patches after reviewing the diff.
+
+### Files that may be frozen in `.fernignore`
+
+These are the files that typically carry manual patches and get frozen between regenerations:
+
+**Client & Socket Clients:**
+- `src/deepgram/client.py` — Bearer token auth + session ID injection
+- `src/deepgram/speak/v1/socket_client.py` — optional message param defaults, broad exception catch
+- `src/deepgram/listen/v1/socket_client.py` — same as above + `construct_type` for unknown WS messages
+- `src/deepgram/listen/v2/socket_client.py` — same as above
+- `src/deepgram/agent/v1/socket_client.py` — same as above + `_sanitize_numeric_types`
+
+**Type Fixes (Fern generates float where API returns int):**
+- `src/deepgram/types/listen_v1response_results_utterances_item.py`
+- `src/deepgram/types/listen_v1response_results_utterances_item_words_item.py`
+- `src/deepgram/types/listen_v1response_results_channels_item_alternatives_item_paragraphs_paragraphs_item.py`
+
+**Redact type (Union[str, Sequence[str]] support):**
+- `src/deepgram/types/listen_v1redact.py`
+
+**Listen Clients (array param support):**
+- `src/deepgram/listen/v1/client.py`
+- `src/deepgram/listen/v2/client.py`
+
+**Tests & WireMock:**
+- `tests/wire/test_listen_v1_media.py` — manual fix for `transcribe_file()` bytes param
+- `wiremock/wiremock-mappings.json` — removed duplicate stub causing non-deterministic matching
+
+**Always frozen (never unfreeze for regen):**
+- `tests/custom/test_text_builder.py`, `tests/custom/test_transport.py` — hand-written tests
+- `tests/manual/` — manual standalone tests
+- `README.md`, `CHANGELOG.md`, `CONTRIBUTING.md`, `reference.md` — docs
+- `src/deepgram/helpers/` — TextBuilder helpers
+- `src/deepgram/transport_interface.py`, `src/deepgram/transport.py`, `src/deepgram/transports/` — custom transport support
+- `.github/`, `docs/`, `examples/` — folders
+
+### Prepare repo for regeneration
+
+1. **Create a new branch** off `main` named `lo/sdk-gen-<YYYY-MM-DD>`.
+2. **Push the branch** and create a PR titled `chore: SDK regeneration <YYYY-MM-DD>` with an empty commit if needed.
+3. **Identify frozen generated files** in `.fernignore` (the files listed above under Client, Type Fixes, Redact, Listen Clients, Tests & WireMock — NOT the "always frozen" files).
+4. **Back up each file** as `<filename>.bak` alongside the original.
+5. **Remove their entries** (and associated comments) from `.fernignore`.
+6. **Commit** as `chore: unfreeze files pending regen` and push.
+7. The branch is now ready for the Fern generator to push changes.
+
+### After regeneration
+
+The `.bak` files are our manually-patched versions. The newly generated files replace them. By comparing the two, we can see what the generator now produces vs what we had patched.
+
+1. **Diff each `.bak` file against the new generated version** (e.g., `diff src/deepgram/client.py.bak src/deepgram/client.py`) to understand what changed and whether our patches are still needed.
+2. **Re-apply any patches** that are still necessary to the newly generated files.
+3. **Re-add entries to `.fernignore`** for any files that still need manual patches.
+4. **Delete `.bak` files** once review is complete.
+5. **Run tests** (`pytest`) and linting (`ruff check`, `mypy`) to verify.
+6. **Commit** as `chore: re-apply manual patches after regen` and push.

CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md