docs: add agent context for oagen-generated code

Adds .claude/CLAUDE.md (with an AGENTS.md symlink) explaining that most
of this SDK is generated by the oagen pipeline from workos/openapi-spec,
how to tell generated files from hand-maintained ones, and that fixes to
generated code belong upstream in oagen/oagen-emitters/openapi-spec.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: gjtorikian

.claude/CLAUDE.md

@@ -0,0 +1,38 @@
+# WorkOS Python SDK — Agent Context
+
+Most code in this repository is **auto-generated**. It is emitted by the
+oagen pipeline from the WorkOS OpenAPI spec. It is not hand-written here,
+and most bugs in it cannot be fixed here.
+
+## The generation pipeline
+
+| Repo | Role |
+| --- | --- |
+| [workos/openapi-spec](https://github.com/workos/openapi-spec) | Source of truth for the API surface (the OpenAPI spec, exported by the WorkOS API) and the orchestration entrypoint for all SDK generation |
+| [workos/oagen](https://github.com/workos/oagen) | The generator engine (spec → IR → code) |
+| [workos/oagen-emitters](https://github.com/workos/oagen-emitters) | The per-language emitters, including the Python emitter that produces this repo's code |
+
+Regeneration runs from a checkout of `openapi-spec`, never from this repo:
+
+```bash
+npm run sdk:generate -- --lang python --output workos-python
+```
+
+## Generated vs. hand-maintained code
+
+- Generated files begin with the header `# This file is auto-generated by oagen. Do not edit.` — treat them as build artifacts.
+- Hand-maintained code is fenced with `@oagen-ignore-start` / `@oagen-ignore-end` markers, or lives in files marked `@oagen-ignore-file`. Only this code is editable in this repo.
+
+## Where to fix an issue
+
+| Symptom | Fix it in |
+| --- | --- |
+| Wrong or missing endpoint, field, type, or enum value | [workos/openapi-spec](https://github.com/workos/openapi-spec) (or the WorkOS API that exports the spec) |
+| Generated Python code is broken or un-idiomatic | [workos/oagen-emitters](https://github.com/workos/oagen-emitters) |
+| Generator behavior: naming, IR, pagination, compat checks | [workos/oagen](https://github.com/workos/oagen) |
+| Code inside `@oagen-ignore` fences or ignore-marked files | This repo — edit normally |
+
+Don't hand-edit a file that has the generated header — the next
+`sdk:generate` run silently overwrites it. Instead, fix the emitter or the
+spec upstream and regenerate. If a requested fix lands in a generated file,
+say so and point at the upstream repo rather than patching it here.

AGENTS.md

@@ -0,0 +1 @@
+.claude/CLAUDE.md