chore: prep v0.2.0 release and upgrade Convex

.github/ISSUE_TEMPLATE/bug.yml

@@ -21,13 +21,13 @@ body:
     id: package-version
     attributes:
       label: Package Version
-      placeholder: "0.1.0"
+      placeholder: "0.2.0"
     validations:
       required: true
   - type: input
     id: convex-version
     attributes:
       label: Convex Version
-      placeholder: "1.33.0"
+      placeholder: "1.36.1"
     validations:
       required: true

AGENTS.md

@@ -14,10 +14,12 @@ Convex component for secure API key management.
 
 ```bash
 pnpm install
-pnpm build:codegen
+pnpm build
 pnpm test
 ```
 
+Use `pnpm build:codegen` only when regenerating checked-in Convex `_generated` files and you have access to the selected Convex project.
+
 ## Structure
 
 - `src/client/index.ts` — `ApiKeys` class (consumer API): create, validate, rotate, revoke, list, update, disable, enable, getUsage, configure

CHANGELOG.md

@@ -4,6 +4,7 @@
 
 ### Breaking Changes
 
+- **Convex compatibility**: this release targets `convex@^1.36.1` and `convex-test@^0.0.50`.
 - **`create()` / `rotate()`**: Secret material (lookupPrefix, secretHex, hash) now generated server-side. Remove these from client args.
 - **Admin mutations** (`revoke`, `disable`, `enable`, `update`, `rotate`, `getUsage`): `ownerId` is now a required argument for auth boundary enforcement.
 - **`apiKeyEvents` table removed**: Audit trail replaced with structured logging (Convex dashboard). Export existing event data before upgrading.
@@ -53,6 +54,8 @@ shardedCounterTest.register(t, "apiKeys/shardedCounter");
 
 ### New Features
 
+- Public client wrapper now forwards optional `limit` to `list()` and `listByTag()`
+- `ValidationFailure` no longer advertises the removed `retryAfter` field
 - Auth boundary: `ownerId` cross-check on all admin mutations
 - Server-side secret generation for `create()` and `rotate()`
 - Input validation: keyPrefix charset, env charset, gracePeriodMs bounds (60s–30d), metadata size (4KB), scopes (50), tags (20)

CLAUDE.md

@@ -44,12 +44,14 @@ src/
 
 ```bash
 pnpm install
-pnpm build:codegen          # Generate Convex types + build
+pnpm build                  # Build the package
 pnpm typecheck              # Type check
 pnpm lint                   # ESLint
 pnpm test                   # vitest with convex-test + @edge-runtime/vm
 ```
 
+Use `pnpm build:codegen` only when regenerating checked-in Convex `_generated` files and you have access to the selected Convex project.
+
 ## Testing
 
 Tests use `convex-test` with the `@edge-runtime/vm` environment. The `src/test.ts` helper registers the component for testing.

CONTRIBUTING.md

@@ -6,12 +6,14 @@ Thanks for your interest in contributing!
 
 ```bash
 pnpm install
-pnpm build:codegen
+pnpm build
 pnpm typecheck
 pnpm lint
 pnpm test
 ```
 
+Use `pnpm build:codegen` only when you need to regenerate checked-in Convex `_generated` files and have access to the selected Convex project.
+
 ## Testing
 
 Tests use [`convex-test`](https://docs.convex.dev/testing) with the `@edge-runtime/vm` environment:
@@ -40,6 +42,9 @@ pnpm test:watch    # watch mode
 
 Maintainers only:
 
+- Preferred: use `.github/workflows/publish.yml` with `workflow_dispatch` for patch/minor/major releases.
+- Local scripts remain available for patch and alpha publishes:
+
 ```bash
 pnpm release       # patch bump + publish
 pnpm alpha         # prerelease (alpha tag)

README.md

@@ -34,10 +34,14 @@ You install one package. The child component is internal — it doesn't appear i
 
 ## Installation
 
+Peer dependency: `convex@^1.36.1`
+
 ```bash
-npm install @vllnt/convex-api-keys
+npm install convex@^1.36.1 @vllnt/convex-api-keys
 ```
 
+If your app already depends on Convex, make sure it satisfies `^1.36.1`.
+
 Register in your `convex/convex.config.ts`:
 
 ```ts
@@ -100,8 +104,9 @@ const { keyId, ownerId, scopes, tags, env, type, metadata, remaining } = result;
 
 ```ts
 const keys = await apiKeys.list(ctx, { ownerId: orgId });
+const firstTwenty = await apiKeys.list(ctx, { ownerId: orgId, limit: 20 });
 const prodKeys = await apiKeys.list(ctx, { ownerId: orgId, env: "live" });
-const taggedKeys = await apiKeys.listByTag(ctx, { ownerId: orgId, tag: "sdk" });
+const taggedKeys = await apiKeys.listByTag(ctx, { ownerId: orgId, tag: "sdk", limit: 20 });
 ```
 
 ### Update metadata (without rotation)

docs/API.md

@@ -2,6 +2,8 @@
 
 Full API reference for `@vllnt/convex-api-keys`.
 
+**Compatibility:** `convex@^1.36.1`
+
 ## ApiKeys Class
 
 ```ts

docs/DEEP-ANALYSIS.md

@@ -1,5 +1,7 @@
 # Deep Analysis: @vllnt/convex-api-keys
 
+> Historical snapshot: this document captures a 2026-03-24 pre-v0.2 review. It is kept for historical context, not as current release guidance. Since then the package added `ownerId` auth-boundary checks, server-side secret generation, structured audit logging, bounded list APIs, and removed the internal rate-limiter / aggregate / crons architecture discussed below. For current behavior, use `README.md` and `docs/API.md`.
+
 **Mode**: Deep | **Perspectives**: 7 (Security, Adversarial, Performance, Scalability, Extensibility, Observability, API Design)
 **Date**: 2026-03-24 | **Verification**: static repo review + `pnpm test` + `pnpm typecheck`
 

docs/ROADMAP.md

@@ -1,5 +1,7 @@
 # Roadmap: @vllnt/convex-api-keys
 
+> Historical roadmap: derived from the pre-v0.2 audit and retained as archive context. Many Phase 1 hardening items shipped in the v0.2.0 line, including `ownerId` auth-boundary checks, server-side secret generation, structured audit logging, bounded list APIs, and removal of the internal rate-limiter / aggregate / crons architecture. Use `CHANGELOG.md`, open issues, and active PRs for current release planning.
+
 Derived from [DEEP-ANALYSIS.md](./DEEP-ANALYSIS.md) (2026-03-24, 6-perspective audit).
 
 ## Priority Legend
@@ -98,8 +100,6 @@ v2.0.0  Phase 4 complete — extensible ecosystem
 
 ## Status
 
-- [x] v0.1.0 shipped (2026-03-24) — feature-complete, 69 tests, OSS grade A
-- [ ] Phase 1 — not started
-- [ ] Phase 2 — not started
-- [ ] Phase 3 — not started
-- [ ] Phase 4 — not started
+- [x] v0.1.0 shipped (2026-03-24) — initial public release
+- [x] v0.2.0 release prep — hardening + docs/package sync + Convex `^1.36.1` compatibility
+- [ ] Remaining items below are historical backlog, not current release gates