Release v1.2.2 — Model metadata overrides fix + Agent guidelines consolidation (#26)

* fix: apply model metadata overrides to provider models (#25)

* fix: apply model metadata overrides to provider models

* test: isolate auth store XDG data home

* fix: treat string metadata matches as literals

* refactor: centralize metadata extraction keys

* fix: refresh legacy generated provider models

---------

Co-authored-by: Sebastian Rumpf <alp4d0g007@googlemail.com>

* docs: consolidate agent guidelines into AGENTS.md and symlink CLAUDE.md

- Rewrite AGENTS.md by cherry-picking the best of AGENTS.md and CLAUDE.md:
  - Keep generic Agent Guidelines framing and all code style rules
  - Add Architecture section (dual entry points, core modules, fetch interceptor, caching)
  - Expand Common Commands (test runner, check:exports, single-file typecheck)
  - Add Testing, Important Configuration, and full Release Process sections
- Delete CLAUDE.md and replace with symlink to AGENTS.md so both Claude Code
  and other agents read from the same canonical source.

* chore: bump version to 1.2.2

* style: fix indentation in getApiMode warn() call

Fixes pre-existing indentation issue flagged by kilo-code-bot review.
No functional change.

* perf: pre-process metadata blocks to avoid redundant regex/alias calculations

Addresses gemini-code-assist review feedback on PR #26:
- Pre-process array-based metadata blocks once: canonicalize string matches,
  compile regexes, and extract metadata upfront.
- Replaces O(N*M) redundant resolveProviderAliasForMetadata + coerceRegExp
  calls inside per-model loops with a single pass over config blocks.
- Adds processedBlockMatches() helper that uses pre-computed canonicalMatch
  instead of re-resolving aliases on every comparison.
- No functional change — all 66 tests pass.

---------

Co-authored-by: Alexander Bien <abien@gmx.net>

Author: Alph4d0g

AGENTS.md

@@ -1,35 +1,73 @@
 # Agent Guidelines for opencode-omniroute-auth
 
-This file provides guidelines for AI agents operating in this repository.
+This file provides guidelines to AI agents when working with code in this repository.
 
 ## Overview
-OpenCode authentication plugin for the OmniRoute API. Features `/connect` command setup, API key auth, dynamic model fetching (`/v1/models`), and TTL caching.
 
-## Commands
+`opencode-omniroute-auth` is an OpenCode authentication plugin for the OmniRoute API. It provides a `/connect omniroute` command, API-key auth, dynamic model fetching from `/v1/models`, and combo model capability enrichment.
 
-### Build & Development
-```bash
-npm install           # Install dependencies
-npm run build         # Build the project (TypeScript compilation)
-npm run dev           # Watch mode for development
-npm run clean         # Clean build output
-npm run prepublishOnly # Build before publishing
-```
+## Common Commands
 
-### Single File Build / Type-Check
 ```bash
-npx tsc --noEmit src/plugin.ts  # Type-check a single file
-npx tsc --build --verbose       # Build with verbose output
-```
+# Build (required before running tests)
+npm run build
 
-### Testing
-*Note: No test suite currently exists. When implemented, use:*
-```bash
-npm test                      # Run all tests
-npx jest src/plugin.test.ts   # Run a single test file
-npm run test:watch            # Run tests in watch mode
+# Watch mode during development
+npm run dev
+
+# Run tests (builds first, then runs Node built-in test runner)
+npm test
+
+# Run a single test file
+npm run build && node --test test/plugin.test.mjs
+
+# Type-check a single file without emitting
+npx tsc --noEmit src/plugin.ts
+
+# Clean build output
+npm run clean
+
+# Validate dist exports satisfy plugin loader constraints
+npm run check:exports
+
+# Full publish prep
+npm run prepublishOnly
 ```
 
+## Architecture
+
+### Dual Entry Points
+
+- **`index.ts`** — Main plugin export (`OmniRouteAuthPlugin`). Required by OpenCode's plugin loader. All root exports must be functions.
+- **`runtime.ts`** — Runtime utilities (`fetchModels`, `clearModelCache`, combo helpers, etc.) exported for programmatic use.
+
+### Core Modules
+
+| File | Responsibility |
+|------|----------------|
+| `src/plugin.ts` | Plugin implementation: `config` hook (registers `omniroute` provider), `auth` hook (`/connect` command), `loadProviderOptions` (fetches models and returns a `fetch` interceptor). |
+| `src/models.ts` | `fetchModels()` fetches `/v1/models`, manages an in-memory cache keyed by `baseUrl:apiKey`, falls back to defaults on failure. Orchestrates metadata enrichment via `models-dev.ts` and combo enrichment via `omniroute-combos.ts`. |
+| `src/models-dev.ts` | Fetches `https://models.dev/api.json`, builds indexed lookup maps (exact/normalized, provider-specific and global), and maps OmniRoute provider keys to models.dev providers via aliases. |
+| `src/omniroute-combos.ts` | Fetches combo definitions from `/api/combos`. Resolves underlying models and calculates lowest-common-denominator capabilities (min context/maxTokens, vision/tools only if ALL underlying models support them). |
+| `src/constants.ts` | Endpoints, default models, TTLs, timeouts. |
+| `src/types.ts` | Shared TypeScript interfaces. |
+
+### Fetch Interceptor (`createFetchInterceptor` in `src/plugin.ts`)
+
+The loader returns a `fetch` function that:
+1. Adds `Authorization: Bearer <apiKey>` and `Content-Type: application/json` headers.
+2. Only intercepts requests to the configured OmniRoute base URL (with safe prefix matching).
+3. Sanitizes Gemini tool schemas by stripping `$schema`, `$ref`, `ref`, and `additionalProperties` keywords when the model name includes "gemini".
+
+### Caching Strategy
+
+Three independent in-memory caches:
+- **Model cache** (`src/models.ts`) — keyed by `baseUrl:apiKey`, TTL defaults to 5 minutes.
+- **models.dev cache** (`src/models-dev.ts`) — global singleton, TTL defaults to 24 hours.
+- **Combo cache** (`src/omniroute-combos.ts`) — global singleton, TTL defaults to 5 minutes.
+
+`clearModelCache()` also clears the combo cache.
+
 ## Code Style Guidelines
 
 ### TypeScript & Formatting
@@ -101,3 +139,75 @@ try {
 ## Common Tasks
 - **Adding Exports**: Add in source file, re-export in `index.ts` (with `.js`), run `npm run build`.
 - **Debugging**: Look for `[OmniRoute]` prefix in console logs.
+
+## Release Process
+
+### 1. Prepare the version bump
+
+1. Update `package.json` version.
+2. Update `CHANGELOG.md` with a new section for the release. Include the date and credit contributors by GitHub username (e.g., `@username`) when applicable.
+3. If there are missing changelog sections for prior releases (e.g., `1.1.0` was released but never documented), add them retroactively so the changelog is complete.
+4. Commit the changes:
+   ```bash
+   git add package.json CHANGELOG.md
+   git commit -m "chore: bump version to X.Y.Z"
+   ```
+
+### 2. Merge to `main`
+
+Ensure the release PR is merged into `main`:
+```bash
+git checkout main
+git pull origin main
+```
+
+### 3. Tag the release
+
+Create and push an annotated tag matching the version:
+```bash
+git tag -a vX.Y.Z -m "Release vX.Y.Z"
+git push origin vX.Y.Z
+```
+
+### 4. Create the GitHub Release
+
+Create a release from the tag using `gh`:
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z" --notes "$(sed -n '/## \[X.Y.Z\]/,/^## /p' CHANGELOG.md | sed '$d')"
+```
+
+Or use a prepared notes file if one exists in `docs/`:
+```bash
+gh release create vX.Y.Z --title "vX.Y.Z" --notes-file docs/release-notes-vX.Y.Z.md
+```
+
+### 5. Publish to npm
+
+1. Verify you are logged in:
+   ```bash
+   npm whoami
+   ```
+2. Run the publish prep (clean, build, and export validation):
+   ```bash
+   npm run prepublishOnly
+   ```
+3. Publish:
+   ```bash
+   npm publish
+   ```
+
+If npm requires an MFA/2FA OTP, publish with:
+```bash
+npm publish --otp <CODE>
+```
+
+### 6. Post-release verification
+
+- Confirm the package version on npm:
+  ```bash
+  npm view opencode-omniroute-auth version
+  ```
+- Confirm the GitHub release exists:
+  ```bash
+  gh release view vX.Y.Z
+  ```

CHANGELOG.md

@@ -2,6 +2,17 @@
 
 All notable changes to this project are documented in this file.
 
+## [1.2.2] - 2026-05-22
+
+### Added
+
+- **Consolidated Agent Guidelines** — Merged `CLAUDE.md` and `AGENTS.md` into a single canonical `AGENTS.md` file. `CLAUDE.md` is now a symlink to `AGENTS.md` so both Claude Code and other agents read from the same source.
+- **Release Process Documentation** — Added complete release process steps to `AGENTS.md` (version bump, changelog, tag, GitHub release, npm publish, verification).
+
+### Fixed
+
+- **Model Metadata Overrides for Provider Models** — Fixed model metadata overrides not being applied to provider models returned by the `provider` hook. (`src/plugin.ts`) (@Alph4d0g)
+
 ## [1.2.1] - 2026-05-19
 
 ### Added

CLAUDE.md

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

CLAUDE.md

@@ -1,6 +1,6 @@
 {
   "name": "opencode-omniroute-auth",
-  "version": "1.2.1",
+  "version": "1.2.2",
   "description": "OpenCode authentication plugin for OmniRoute API with /connect command and dynamic model fetching",
   "type": "module",
   "main": "./dist/index.js",