@rawan-temo/prisma-zod-generator 3.3.1-config-coercion.0

package/.github/workflows/docs.yml

@@ -0,0 +1,98 @@
+name: Docs
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+concurrency:
+  group: docs-pages
+  cancel-in-progress: false
+
+jobs:
+  filter:
+    runs-on: ubuntu-latest
+    outputs:
+      should_deploy: ${{ steps.compute.outputs.should_deploy }}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Decide if docs should deploy
+        id: compute
+        shell: bash
+        run: |
+          set -euo pipefail
+          PREV="${{ github.event.before }}"
+          CUR="${{ github.sha }}"
+          # Determine diff/log range (handle initial pushes)
+          if [ -z "$PREV" ] || [ "$PREV" = "0000000000000000000000000000000000000000" ]; then
+            RANGE="$CUR~1..$CUR"
+          else
+            RANGE="$PREV..$CUR"
+          fi
+
+          echo "Using range: $RANGE"
+
+          DOCS_CHANGED=false
+          if git diff --name-only $RANGE | grep -E '^website/' >/dev/null 2>&1; then
+            DOCS_CHANGED=true
+          fi
+
+          HAS_FIX_FEAT=false
+          if git log --format=%s $RANGE | grep -Ei '^(feat|fix)(\(|!:|:)' >/dev/null 2>&1; then
+            HAS_FIX_FEAT=true
+          fi
+
+          SHOULD_DEPLOY=false
+          if [ "$DOCS_CHANGED" = true ] || [ "$HAS_FIX_FEAT" = true ]; then
+            SHOULD_DEPLOY=true
+          fi
+
+          echo "docs_changed=$DOCS_CHANGED"
+          echo "feat_or_fix=$HAS_FIX_FEAT"
+          echo "should_deploy=$SHOULD_DEPLOY"
+
+          echo "should_deploy=$SHOULD_DEPLOY" >> "$GITHUB_OUTPUT"
+
+  build:
+    needs: filter
+    if: needs.filter.outputs.should_deploy == 'true'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+      - name: Use Node
+        uses: actions/setup-node@v6
+        with:
+          node-version: 24
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.15.1
+      - name: Install dependencies
+        run: cd website && pnpm install --frozen-lockfile
+      - name: Build docs
+        run: cd website && pnpm run build
+      - name: Upload artifact
+        uses: actions/upload-pages-artifact@v4
+        with:
+          path: website/build
+  deploy:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4

package/.github/workflows/semantic-release.yml

@@ -0,0 +1,209 @@
+name: Semantic Release
+
+on:
+  push:
+    branches: [master]
+  workflow_dispatch:
+
+jobs:
+  # Decide whether this push will actually publish anything, before paying for the
+  # pipeline that would publish it.
+  #
+  # Most pushes to master do not release. `.releaserc.json` marks docs, style, chore,
+  # test, build and ci as `"release": false`, and those are the bulk of the traffic -
+  # over one recent stretch, one of five merges produced a version. Every one of the
+  # other four still ran the whole release job: submodule checkout, install,
+  # gen-example, typecheck, lint, the full test suite, package.sh with obfuscation and
+  # verify:build, roughly fifteen minutes, before semantic-release reached the end and
+  # reported "no relevant changes".
+  #
+  # This job asks commit-analyzer the same question first, for about a minute. It uses
+  # the real plugin and the real `releaseRules` rather than a grep over commit
+  # messages, so the gate cannot disagree with the release it is gating.
+  #
+  # It also does not need the private submodule, which the release job does.
+  plan:
+    runs-on: ubuntu-latest
+    if: "!contains(github.event.head_commit.message, '[skip ci]')"
+    env:
+      HUSKY: 0
+    outputs:
+      will_release: ${{ steps.analyze.outputs.will_release }}
+      next_version: ${{ steps.analyze.outputs.next_version }}
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24.x'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.15.1
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Determine whether this push releases
+        id: analyze
+        shell: bash
+        run: |
+          set -uo pipefail
+          out="$(pnpm run release:predict 2>&1)" || true
+          echo "$out"
+
+          # Fail open. A missed release is expensive and silent; a wasted pipeline run
+          # costs fifteen minutes and is obvious. So only the explicit "nothing to
+          # release" message skips - anything unrecognised, including a future change
+          # to semantic-release's wording, falls through to running the release.
+          if grep -q "The next release version is" <<<"$out"; then
+            version="$(grep -oE "The next release version is [^ ]+" <<<"$out" | tail -1 | awk '{print $NF}')"
+            echo "will_release=true" >> "$GITHUB_OUTPUT"
+            echo "next_version=$version" >> "$GITHUB_OUTPUT"
+            echo "::notice::Releasing $version"
+          elif grep -qE "no new version is released|There are no relevant changes" <<<"$out"; then
+            echo "will_release=false" >> "$GITHUB_OUTPUT"
+            echo "::notice::No releasable commits; skipping the release pipeline."
+          else
+            echo "will_release=true" >> "$GITHUB_OUTPUT"
+            echo "::warning::Could not read a verdict from commit-analyzer; running the release pipeline anyway."
+          fi
+
+  release:
+    runs-on: ubuntu-latest
+    needs: plan
+    if: needs.plan.outputs.will_release == 'true'
+    env:
+      # Disable husky entirely in CI; npm publish runs the packaged
+      # package.json's prepare script inside package/ where no .git exists.
+      HUSKY: 0
+    permissions:
+      contents: write
+      issues: write
+      pull-requests: write
+      # Required for npm Trusted Publishing (OIDC token exchange)
+      id-token: write
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+        with:
+          fetch-depth: 0
+
+      - name: Initialize private submodule
+        env:
+          PRO_KEY: ${{ secrets.SUBMODULE_DEPLOY_KEY }}
+        run: |
+          if [ -z "$PRO_KEY" ]; then
+            echo "SUBMODULE_DEPLOY_KEY secret is not set"
+            exit 1
+          fi
+          if ! command -v ssh-agent >/dev/null; then
+            echo "ssh-agent not available"
+            exit 1
+          fi
+          eval "$(ssh-agent -s)"
+          mkdir -p ~/.ssh
+          ssh_key_path=~/.ssh/id_pro
+          printf '%s' "$PRO_KEY" | tr -d '\r' > temp_key.txt
+          if base64 -d temp_key.txt > "$ssh_key_path" 2>/dev/null; then
+            echo "Submodule key decoded from base64"
+          else
+            echo "Submodule key not base64-encoded; normalising raw key"
+            sed 's/\\n/\n/g' temp_key.txt > "$ssh_key_path"
+          fi
+          rm -f temp_key.txt
+          chmod 600 "$ssh_key_path"
+          ssh-add "$ssh_key_path"
+          ssh-keyscan github.com >> ~/.ssh/known_hosts
+          git config --global url."git@github.com:".insteadOf "https://github.com/"
+          git submodule sync --recursive
+          git submodule update --init --recursive
+
+      - name: Verify pro submodule loaded
+        run: |
+          if [ ! -f "src/pro/index.ts" ]; then
+            echo "❌ Error: Pro submodule not loaded"
+            exit 1
+          fi
+          echo "✅ Pro submodule verified"
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: '24.x'
+
+      - name: Install pnpm
+        uses: pnpm/action-setup@v4
+        with:
+          version: 10.15.1
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build and test
+        run: |
+          pnpm run gen-example
+          pnpm run typecheck
+          pnpm run lint
+          pnpm test
+
+      - name: Build package (with obfuscation)
+        run: ./package.sh
+
+      - name: Verify build and obfuscation
+        run: pnpm verify:build
+
+      - name: Semantic Release (with npm lifecycle)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          # npm auth uses Trusted Publishing (OIDC) — no NPM_TOKEN needed.
+        run: pnpm run release
+
+      # Removed changelog sync: docs page now links to GitHub
+      # Keeping commit step below to capture version/lockfile changes
+
+      - name: Commit and push workflow mutations (if any)
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          # Stage docs and common release-mutation files to avoid failing on dirty tree
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          # `package/` is build output and gitignored, so it is deliberately not listed:
+          # package.sh rewrites package/package.json on every run, and while it was tracked
+          # it dirtied the tree every time and was the only thing this step ever committed.
+          git add -A \
+            website/docs/changelog.md \
+            package.json \
+            pnpm-lock.yaml \
+            CHANGELOG.md || true
+          # If nothing is staged, skip committing to avoid exit 1 from git commit
+          if git diff --cached --quiet; then
+            echo "No docs changes to commit"
+            exit 0
+          fi
+          LAST_TAG=$(git describe --tags --abbrev=0 || echo "latest")
+          git commit -m "chore(ci): commit workflow mutations (version bumps, lockfile, docs) for ${LAST_TAG} [skip ci]"
+          # Push over an explicitly token-authenticated URL rather than `origin`.
+          #
+          # The submodule step above sets a *global*
+          # `url."git@github.com:".insteadOf "https://github.com/"`, so a plain
+          # `git push origin` is rewritten to SSH and authenticates with the only key in the
+          # agent — the submodule's deploy key, which has no write access to this repository.
+          # That failed with "Permission denied (publickey)".
+          #
+          # It went unnoticed because the step exits early unless one of the files above
+          # actually changed, and the only one that regularly did was package/package.json,
+          # now untracked. semantic-release's own push is unaffected: it builds this same
+          # authenticated form, whose prefix does not match the rewrite rule.
+          git push "https://x-access-token:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git" \
+            HEAD:"${GITHUB_REF_NAME}"

package/.gitmodules

@@ -0,0 +1,4 @@
+[submodule "src/pro"]
+	path = src/pro
+	url = git@github.com:omar-dulaimi/prisma-zod-generator-pro.git
+	branch = master

package/.husky/commit-msg

@@ -0,0 +1,44 @@
+# Reject the CI-skip marker when it appears in the body of a commit message.
+#
+# GitHub matches that marker anywhere in the head commit's message, subject and body
+# alike, and skips every workflow for the commit. It also carries into a squash-merge,
+# because the PR's commit body becomes the merge commit's body.
+#
+# That is not hypothetical here: PR #406 was a change *about* the marker, its commit
+# body quoted the literal string three times while explaining the mechanism, and the
+# result was zero checks on the pull request and zero workflow runs on the merge
+# commit. A CI change reached master having never run CI, and nothing reported a
+# problem, because from GitHub's side nothing went wrong.
+#
+# Intentional use stays available: put it in the subject line, which is where
+# semantic-release writes it. Only prose in the body is rejected.
+
+msg_file="$1"
+[ -f "$msg_file" ] || exit 0
+
+# Strip comment lines git adds to the template before looking.
+content="$(grep -v '^#' "$msg_file")"
+subject="$(printf '%s\n' "$content" | sed -n '1p')"
+body="$(printf '%s\n' "$content" | sed -n '2,$p')"
+
+marker='\[(skip ci|ci skip|skip actions|actions skip)\]'
+
+if printf '%s' "$body" | grep -qEi "$marker"; then
+  if printf '%s' "$subject" | grep -qEi "$marker"; then
+    exit 0
+  fi
+  echo ""
+  echo "✖ The CI-skip marker appears in the body of this commit message."
+  echo ""
+  echo "  GitHub reads the entire message, so this silently disables every workflow"
+  echo "  for the commit - and for the squash-merge commit it becomes part of."
+  echo "  A change can reach master without CI ever running, with nothing to show"
+  echo "  for it: no failed check, no skipped check, no run at all."
+  echo ""
+  echo "  If you are describing the marker, write it without the brackets."
+  echo "  If you actually mean to skip CI, put it in the subject line instead."
+  echo ""
+  exit 1
+fi
+
+exit 0

package/.husky/post-checkout

@@ -0,0 +1,2 @@
+# Show repository guidelines after switching branches
+node scripts/agent-banner.js >/dev/null 2>&1 || true

package/.husky/post-merge

@@ -0,0 +1,2 @@
+# Show repository guidelines after merging updates
+node scripts/agent-banner.js >/dev/null 2>&1 || true

package/.husky/pre-push

@@ -0,0 +1,24 @@
+# Skip hook in CI (e.g., GitHub Actions / semantic-release)
+if [ -n "$CI" ] || [ -n "$GITHUB_ACTIONS" ]; then
+  echo "Skipping pre-push in CI"
+  exit 0
+fi
+
+# Fail on first error
+set -e
+
+# Run type check, lint and prettier check before pushing
+pnpm run typecheck
+pnpm run lint
+pnpm run format:check
+
+# Generate LLM-friendly docs surface and ensure it's committed
+echo "Generating llms.txt…"
+pnpm run llms:gen
+
+# If llms.txt differs from HEAD (staged or unstaged), abort so it can be committed
+if ! git diff --quiet HEAD -- llms.txt; then
+  printf "\nllms.txt was updated by the generator.\n"
+  echo "Please add and commit llms.txt, then push again."
+  exit 1
+fi

package/.nvmrc

@@ -0,0 +1 @@
+24

package/.prettierignore

@@ -0,0 +1,19 @@
+lib/**/*
+package/**/*
+src/schemas/**/*
+src/dsrc/**/*
+node_modules/
+tests/node_modules/
+coverage/
+*.md
+*.json
+*.js.map
+*.d.ts
+# Vendored verbatim from prisma-json-types-generator (MIT, see
+# tests/compat/pjtg/UPSTREAM-LICENSE). Reformatting it would make it ours, and the
+# point of keeping it byte-identical is that it proves compatibility rather than
+# asserting it.
+tests/compat/pjtg/**
+website/build/
+pnpm-lock.yaml
+**/pnpm-lock.yaml

package/.prettierrc

@@ -0,0 +1,10 @@
+{
+  "trailingComma": "all",
+  "tabWidth": 2,
+  "printWidth": 100,
+  "bracketSpacing": true,
+  "semi": true,
+  "singleQuote": true,
+  "arrowParens": "always",
+  "useTabs": false
+}

package/.releaserc.json

@@ -0,0 +1,106 @@
+{
+  "branches": [
+    "master",
+    {
+      "name": "upgrade/prisma-and-dependencies",
+      "prerelease": "beta"
+    }
+  ],
+  "plugins": [
+    [
+      "@semantic-release/commit-analyzer",
+      {
+        "preset": "conventionalcommits",
+        "releaseRules": [
+          { "type": "feat", "release": "minor" },
+          { "type": "fix", "release": "patch" },
+          { "type": "perf", "release": "patch" },
+          { "type": "revert", "release": "patch" },
+          { "type": "docs", "release": false },
+          { "type": "style", "release": false },
+          { "type": "chore", "release": false },
+          { "type": "refactor", "release": "patch" },
+          { "type": "test", "release": false },
+          { "type": "build", "release": false },
+          { "type": "ci", "release": false },
+          { "scope": "breaking", "release": "major" }
+        ]
+      }
+    ],
+    [
+      "@semantic-release/release-notes-generator",
+      {
+        "preset": "conventionalcommits",
+        "presetConfig": {
+          "types": [
+            { "type": "feat", "section": "🚀 Features" },
+            { "type": "fix", "section": "🐛 Bug Fixes" },
+            { "type": "perf", "section": "⚡ Performance Improvements" },
+            { "type": "revert", "section": "⏪ Reverts" },
+            { "type": "refactor", "section": "♻️ Code Refactoring" },
+            { "type": "docs", "section": "📚 Documentation", "hidden": false },
+            { "type": "style", "section": "💄 Styles", "hidden": true },
+            { "type": "chore", "section": "🔧 Miscellaneous Chores", "hidden": true },
+            { "type": "test", "section": "✅ Tests", "hidden": true },
+            { "type": "build", "section": "🏗️ Build System", "hidden": true },
+            { "type": "ci", "section": "👷 CI/CD", "hidden": true }
+          ]
+        }
+      }
+    ],
+    [
+      "@semantic-release/changelog",
+      {
+        "changelogFile": "CHANGELOG.md"
+      }
+    ],
+    [
+      "@semantic-release/npm",
+      {
+        "pkgRoot": ".",
+        "npmPublish": false
+      }
+    ],
+    [
+      "@semantic-release/exec",
+      {
+        "prepareCmd": "pnpm llms:gen"
+      }
+    ],
+    [
+      "@semantic-release/npm",
+      {
+        "pkgRoot": "package"
+      }
+    ],
+    [
+      "@semantic-release/git",
+      {
+        "assets": [
+          "package.json",
+          "package-lock.json",
+          "package/package.json",
+          "CHANGELOG.md",
+          "llms.txt"
+        ],
+        "message": "chore(release): ${nextRelease.version} [skip ci]\n\n${nextRelease.notes}"
+      }
+    ],
+    [
+      "@semantic-release/github",
+      {
+        "assets": [
+          {
+            "path": "package/*.tgz",
+            "label": "Package tarball"
+          }
+        ],
+        "successComment": "🎉 This issue has been resolved in version ${nextRelease.version} 🎉\n\nThe release is available on:\n- [npm package (@latest dist-tag)](https://www.npmjs.com/package/prisma-zod-generator/v/${nextRelease.version})\n- [GitHub release](${releases.url})\n\nYour **${issue.title}** is now live. Thanks for contributing! 🙌",
+        "failComment": "❌ The release from branch `${branch.name}` had an error during the release step.\n\nPlease check the [build logs](https://github.com/omar-dulaimi/prisma-zod-generator/actions/workflows/semantic-release.yml) for more details.",
+        "failTitle": "🚨 The automated release failed",
+        "labels": ["released"],
+        "assignees": ["omar-dulaimi"]
+      }
+    ]
+  ]
+}

package/AGENTS.md

@@ -0,0 +1,119 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+- `src/` — TypeScript source for the generator. Key areas: `variants/`, `generators/`, `utils/`, `config/` (e.g., `src/prisma-generator.ts`, `src/variants/generator.ts`).
+- `tests/` — Vitest test suite (e.g., `tests/prisma-client-esm-config.test.ts`).
+- `prisma/` — Example schemas/utilities used by tests (multi‑provider helpers).
+- `scripts/` — Release and docs tooling.
+- `website/` — Docusaurus documentation site.
+- `.github/` — CI workflows and templates.
+
+## Build, Test, and Development Commands
+Use pnpm.
+- `pnpm install` — Install dependencies.
+- `pnpm build` — Compile TypeScript (tsc).
+- `pnpm test` — Run every Vitest file. Pass a path or `-t <name>` to narrow it.
+- `pnpm test:sequential` — The same suite on one worker, for parallel-only failures.
+- `pnpm test:coverage` — Full suite under c8, with the coverage thresholds enforced.
+- `pnpm lint` — ESLint over `src/` and `tests/` (auto‑fix where safe).
+- `pnpm format` / `pnpm format:check` — Prettier write/check.
+- `pnpm gen-example` — Build and run a local generate cycle.
+
+## Coding Style & Naming Conventions
+- Language: TypeScript; aim for clear, typed APIs.
+- Formatting: Prettier; Linting: ESLint. Run `pnpm format && pnpm lint` before pushing.
+- Indentation: 2 spaces; line endings: LF.
+- Naming: files use kebab‑case (e.g., `prisma-generator.ts`); types/interfaces PascalCase; functions/variables camelCase; prefer named exports.
+- ESM/CJS: Preserve existing module boundaries and index emit patterns.
+
+## Testing Guidelines
+- Framework: Vitest. Tests live under `tests/` and end with `.test.ts`.
+- Add focused tests alongside related areas (e.g., ESM index generation in `tests/prisma-client-esm-config.test.ts`).
+- `pnpm test` is the whole suite; narrow it with a path or `-t <name>` rather than adding a script for it.
+
+## Commit & Pull Request Guidelines
+- Use Conventional Commits with a scope: `type(scope): subject` (e.g., `fix(variants): include .js in ESM index imports`).
+- Choose `type` intentionally based on impact: `feat`, `fix`, `docs`, `refactor`, `chore`, etc.
+- Keep commits small and atomic; update/add tests with behavior changes.
+- Before push: run and commit `pnpm format` and `pnpm lint` fixes; ensure `pnpm build`, `pnpm test`, and `pnpm format:check` pass.
+
+### Pull request body files (important)
+- Never commit PR body files to the repository.
+- Use a temporary file outside the repo (e.g., `/tmp/pr-body.md`) when running `gh pr create`:
+  - `gh pr create --base master --head <branch> --title "fix(scope): concise title" --body-file /tmp/pr-body.md`
+- If a body file must be created within the workspace for tooling reasons, it must be placed under a temp path that is ignored by git (e.g., `.tmp/pr-body.md`), and deleted immediately after PR creation.
+- Ensure the PR body contains: Summary, Motivation/Context, Changes, Testing/Validation, Breaking changes, Related issues (e.g., `Closes #123`), and a short checklist.
+
+### Commit Workflow (Improved)
+Follow this process to create a high‑quality Conventional Commit:
+
+1. Decide scope of commit
+   - If staged changes exist (`git diff --cached --name-only` not empty), commit only those.
+   - Otherwise, stage everything with `git add -A`.
+
+2. Detect package manager / scripts
+   - Prefer `pnpm` when available (lockfile or `corepack pnpm --version`).
+   - Inspect `package.json` for `typecheck`, `lint`, and `format` scripts.
+
+3. Quality gates (best-effort; skip gracefully if unavailable)
+   - Typecheck: run `pnpm run typecheck` (or `npx tsc --noEmit` if TS project detected).
+   - Lint: run `pnpm run lint` (or `npx eslint . --max-warnings=0` if config exists).
+   - Format: run `pnpm run format` (or `npx prettier -w .` if config exists).
+   - If any gate fails, stop and fix before committing.
+
+4. Analyze changes to compose a Conventional Commit
+   - Scope: infer from the most common first path segment of changed files.
+   - Type: `feat`/`fix` for `src/` code; `test`, `docs`, `chore`/`build` as appropriate.
+   - Breaking changes: append `!` and add a `BREAKING CHANGE:` footer when applicable.
+   - Subject: concise, imperative (≤ 72 chars). Body: bullets of key changes; link issues (e.g., `Closes #123`).
+
+5. Commit
+   - Write message to a temp file; then `git commit -F <tempfile>`.
+
+Policies
+- Never mention AI/assistants in commits.
+- Keep subject lines ≤ 72 chars; wrap body at ~100 chars.
+- Use Commitizen (`git cz`) if available; otherwise follow above.
+
+### Pull Request Workflow (Improved)
+Create and push a feature branch, generate a rich PR body, and open a PR with GitHub CLI:
+
+1. Branch strategy
+   - From the default branch (synced to latest `origin/<default>`), create a branch if needed:
+     - Name: `<type>/<scope>-<short-desc-kebab>` (e.g., `feat/api-add-pagination`).
+     - Use `git fetch origin && git rebase origin/<default>` to ensure up-to-date.
+
+2. Commit changes
+   - Run the commit workflow above first to ensure clean, formatted changes.
+
+3. Analyze branch changes
+   - Compare against default: `git log --oneline --no-decorate --reverse origin/<default>..HEAD` and
+     `git diff --name-status origin/<default>..HEAD`.
+   - PR title: from the first non-chore Conventional Commit; else from latest commit.
+   - Aggregate commits to build a comprehensive change list.
+
+4. Generate PR body (markdown)
+   - Include: Summary, Motivation/Context, Changes, Screenshots/Demos (if UI), Testing/Validation, Breaking changes, Related issues (`Closes #123`), Checklist.
+   - Write to a temp file (e.g., `/tmp/pr-body.md` or `.tmp/pr-body.md`).
+
+5. Push & open PR
+   - `git push -u origin HEAD`
+   - `gh pr create --base <default> --title "<title>" --body-file <tempfile>`
+
+6. Labels, reviewers, cleanup
+   - Add labels/reviewers as needed.
+   - Delete the temp body file.
+
+Policies
+- PR title follows Conventional Commits; no AI mentions.
+
+## Windows Execution Policy
+- On Windows hosts, run repository commands through WSL by default.
+- Prefer: `wsl.exe bash -lc "<command>"`.
+- Only use native PowerShell/CMD when the user explicitly asks for it or a task is Windows-only.
+- If WSL is unavailable or broken, stop and ask the user before falling back.
+
+## Local Agent Overrides
+- Codex local override file: `AGENTS.override.md` (applied after this file).
+- Claude local override file: `CLAUDE.local.md` (applied after `CLAUDE.md`).
+- Keep local override files untracked (for example via `.git/info/exclude`).