chore: sync main into v1

.agents/skills/review-platform-api-contract/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: review-platform-api-contract
+description: Review Fyle Platform API contract pull requests across runtime code, OpenAPI source and bundles, generated TypeScript, and consumers. Use for changes to endpoints, request or response schemas, requiredness, nullability, enums, or compatibility in fyle-platform-docs, fyle-platform-api, or fyle-platform-types. Produce evidence-backed findings and do not publish review comments unless explicitly asked.
+---
+
+# Review Platform API Contracts
+
+Compare the proposed API contract change with runtime behavior, OpenAPI, and downstream types. Read [references/contract-chain.md](references/contract-chain.md) for repository-specific paths and commands.
+
+## 1. Fix the review scope
+
+- Resolve the PR base and head to immutable commits. Resolve the runtime revision separately: prefer a linked API PR or commit; otherwise use the API default-branch commit only as evidence of current behavior. Never use a sibling checkout unless its commit matches the recorded revision.
+- Label each repository commit as proposed, current, or historical evidence. Do not use current behavior to prove what an old or closed PR did.
+- Read the repository-local guidance files that exist, such as `AGENTS.md` or `CLAUDE.md`, and inspect each working-tree status.
+- Preserve local changes. Use GitHub, `git show`, temporary copies, or a temporary worktree when a sibling repository is dirty.
+- Inspect changed files, checks, reviews, and existing comments so findings are scoped and not duplicated.
+- For docs-backed changes, run `<skill-dir>/scripts/contract_diff_inventory.py` with the PR base and head. Use its source-file, risk, role, and bulk-mode counts as review denominators.
+- Triage changed source lines first. Prioritize `$ref`, requiredness, nullability, enums, shared schemas, and request/response shape changes; trace high-risk candidates through the full chain before expanding the review.
+
+If a required repository is unavailable, continue only with supported conclusions and state the evidence gap.
+
+## 2. Review source before generated output
+
+- Treat `fyle-platform-docs/src/**` as source and `reference/*.yaml` as generated output.
+- Map generated changes back to the exact source schema or path and attach findings there.
+- Read the affected root document's OpenAPI version.
+- Lint and rebuild every role reported by the inventory. A change under `src/components/**` requires every discoverable role root; a role-local change requires that role.
+
+## 3. Prove runtime behavior
+
+Trace each high-risk changed field from the endpoint through the exact runtime path.
+
+Read runtime files from the selected immutable commit with `git show` or an isolated worktree. If no revision is linked strongly enough to support the claim, report the gap instead of treating an unrelated current checkout as proof.
+
+- For requests, inspect the loaded Marshmallow schema, validation, defaults, `post_load`, action logic, and request/error fixtures.
+- For responses, inspect the handler's dump schema, serialization hooks, the object being dumped, models, current database views and constraints, relevant migrations, and response fixtures.
+- For enums, compare OpenAPI with the runtime enum, validators, storage representation, fixtures, migrations, and history for removed values.
+
+Use these contract rules:
+
+- Marshmallow `required` primarily controls loading; it does not prove response-key presence.
+- OpenAPI object-level `required` means the key is present. `nullable` means a present key may be `null`.
+- Omitted and present-with-`null` are different contracts.
+- In OpenAPI 3.0, schema keywords beside `$ref` do not extend the referenced schema. Use `allOf` only after runtime evidence proves the added constraint is correct.
+- When input and output behavior differ, prefer separate request and response schemas over weakening the response contract.
+
+Do not infer runtime behavior from the OpenAPI diff or a Marshmallow field flag alone.
+
+## 4. Check generated types and consumers
+
+- Compare base and proposed bundles in isolated directories in `fyle-platform-types`.
+- Run the version classifier and generate representative before/after TypeScript when the contract shape changes.
+- If dependencies are unavailable, compare the specs and generator configuration only. Generated output is not committed in `fyle-platform-types`; mark TypeScript shape and semver as unverified instead of installing into a sibling repository.
+- Search identifiable consumers for affected imports, enum members, request arguments, optional fields, and null handling.
+- Classify runtime compatibility, documentation accuracy, generated-source compatibility, and semver impact separately.
+
+Do not call a change runtime-breaking only because a generated type breaks, or call it documentation-only when generated consumers need a migration.
+
+## 5. Validate and report
+
+Run the smallest relevant checks from the repository map. Report failures and skipped checks without hiding them.
+
+When the inventory selects bulk mode, account for the whole diff:
+
+- Disposition every changed source file as manually reviewed or covered by a named deterministic check.
+- Triage every risk-marker line and trace every resulting high-risk candidate; group mechanical edits only after proving the same rule covers every member.
+- Report `reviewed/total` for source files, risk-marker lines, high-risk candidates, bundle roles, generated roles, and known consumer symbols. Sampling can support a finding, but cannot support a claim of complete review.
+
+Return findings in severity order. Each finding must include:
+
+1. The exact changed source line; for docs changes, prefer `src/**` over `reference/**`.
+2. The concrete contract mismatch and user or SDK impact.
+3. Concise runtime and generated-type evidence.
+4. A specific requested change and, when useful, a proposed inline comment.
+
+Finish with the reviewed commits, checks run or skipped, evidence gaps, and publication status. Keep comments as proposals unless the user explicitly authorizes posting them.

.agents/skills/review-platform-api-contract/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Review Platform API Contract"
+  short_description: "Review API contracts across runtime and types"
+  default_prompt: "Use $review-platform-api-contract to review this API contract PR across runtime, OpenAPI source, generated types, and consumers."

.agents/skills/review-platform-api-contract/references/contract-chain.md

@@ -0,0 +1,121 @@
+# Platform API contract chain
+
+The repositories normally live beside one another:
+
+| Repository | Contract role |
+| --- | --- |
+| `fyle-platform-api` | Runtime handlers, schemas, models, database views, migrations, and fixtures |
+| `fyle-platform-docs` | OpenAPI source in `src/` and generated bundles in `reference/` |
+| `fyle-platform-types` | Synced bundles, generated TypeScript, and semver classification |
+| `fyle-app` | Known direct consumer of `@fylein/types`; do not assume it is the only consumer |
+
+Resolve default branches and commits at review time. The contract flow is:
+
+```text
+fyle-platform-api runtime
+  -> fyle-platform-docs/src
+  -> fyle-platform-docs/reference
+  -> fyle-platform-types/specs
+  -> @fylein/types
+  -> consumers
+```
+
+## Record repository state
+
+```bash
+git status --short --branch
+git symbolic-ref --short refs/remotes/origin/HEAD
+git log -1 --format='%H %cI %s'
+gh pr view <number> --json baseRefOid,headRefOid,state,url
+```
+
+The PR base branch may advance after the PR opens. Resolve both PR refs, then use their merge base for the reviewed diff. For runtime evidence, use a linked `fyle-platform-api` PR or commit when one exists. Otherwise, an exact default-branch commit can prove only current behavior. A checked-out branch, similar timestamp, or current file is not evidence for a historical PR unless its commit is the selected revision.
+
+Record the evidence role beside every commit: proposed change, current behavior, or historical context. Read files with `git show <commit>:<path>` or from an isolated worktree so paths from different revisions are not mixed.
+
+Do not switch, pull, install into, or generate inside a dirty sibling. Use read-only evidence or an isolated worktree instead.
+
+## Review and validate docs
+
+`src/<role>/openapi.yaml` declares the document version, tags, security, and path references. Endpoint definitions live in `src/<role>/paths/`; shared schemas live in `src/components/schemas/`. Filenames use `@` for URL separators.
+
+Inventory a docs diff before tracing it:
+
+```bash
+python3 <skill-dir>/scripts/contract_diff_inventory.py \
+  --repo <fyle-platform-docs> --base <base-ref> --head <head-ref>
+```
+
+The script resolves immutable commits, computes the merge base, counts changed source files and risk-marker lines, discovers role roots from `src/*/openapi.yaml`, and selects bulk mode for more than 10 source files or more than 3 directly changed roles. Use `--format json` when file-level details are needed.
+
+`reference/<role>.yaml` is generated. Read the pinned Redocly version from `.github/workflows/bundler.yml` at the reviewed revision and verify its bundle steps cover every discovered role root. Lint and bundle every role reported by the inventory:
+
+```bash
+openapi lint src/<role>/openapi.yaml
+openapi bundle -o /tmp/<role>.yaml src/<role>/openapi.yaml
+```
+
+Compare temporary base and head bundles with their corresponding committed `reference/<role>.yaml` files, then compare base with head. A shared `src/components/**` change requires all role roots because shared-schema fan-out is not reliably visible from changed paths alone.
+
+## Trace runtime behavior
+
+Start from the route and inspect only the evidence needed for the changed field:
+
+- `api/<resource>/<role>.py` or the relevant blueprint and view.
+- `api/<resource>/schema.py` and inherited `core/schema/**` fields.
+- The action class and model validation for writes.
+- `db/models/**` column definitions.
+- Current `db-migrations/views/**` plus migrations that changed the field or view.
+- `api/tests/**/input.yaml` and `expected_output.yaml` for successful and validation-error cases.
+
+Use history when removed enum values or legacy storage are relevant:
+
+```bash
+git log -p -G '<field-or-enum>' --all -- <relevant-paths>
+```
+
+Run the narrowest affected test group or test case using the commands in `fyle-platform-api/CLAUDE.md` when runtime verification is needed.
+
+## Compare generated types
+
+Read `package.json` for the required Node and pnpm versions. The useful entry points are:
+
+```bash
+pnpm test
+OLD_SPECS_DIR=<base-specs> NEW_SPECS_DIR=<head-specs> pnpm run version:check
+OPENAPI_SPECS_DIR=<specs> OPENAPI_OUTPUT_DIR=<output> pnpm exec openapi-ts
+```
+
+Use temporary base/head spec and output directories. `pnpm run build` syncs local docs into the types worktree, so run it only in an isolated worktree.
+
+`dist/` and `.generated/` are ignored rather than committed. If generation dependencies cannot run, compare the input specs and generator configuration, state that generated TypeScript and semver are unverified, and stop short of claiming full-chain validation.
+
+The classifier's highest result wins:
+
+- `major`: `oasdiff breaking` reports a breaking OpenAPI change or a role disappears.
+- `minor`: generated structure changes without an OpenAPI breaking result, or a role appears.
+- `patch`: only generated documentation changes.
+- `none`: no generated or documentation change.
+
+## Account for broad changes
+
+For bulk mode, keep a coverage manifest with these denominators:
+
+- changed `src/**` files reviewed;
+- risk-marker lines triaged and resulting candidates traced to runtime evidence;
+- bundle roles linted and regenerated;
+- generated roles compared when shape changes;
+- affected symbols checked in every known available consumer.
+
+Report each as `reviewed/total` and name the deterministic check used for grouped mechanical edits. Do not describe a sampled review as exhaustive; list any uncovered files, roles, or consumers as evidence gaps.
+
+## Find consumers
+
+`TYPES_CONSUMER_REPOS` is a GitHub repository variable and is not enumerated in source. Search available sibling repositories instead:
+
+```bash
+rg -l '"@fylein/types"\s*:' .. -g 'package.json' -g '!**/node_modules/**' -g '!**/.pnpm-store/**'
+rg '<affected-generated-symbol>' ../<consumer> -g '*.ts' -g '*.tsx' -g '!**/node_modules/**'
+```
+
+Inspect only consumers that use affected generated symbols. State that the search is incomplete when private or unavailable consumers may exist.