Add contributor, agent and brand documentation

AGENTS.md

@@ -0,0 +1,87 @@
+# AGENTS.md
+
+Guidance for AI coding agents working in Fate-EVM-Frontend, the EVM frontend for
+Fate Protocol.
+
+## Project Stack
+
+Next.js 15 (App Router), React 19, TypeScript 5, TailwindCSS with shadcn/ui,
+wagmi 2 + viem 2, RainbowKit. Statically exported.
+
+## Commands
+
+```bash
+npm run dev     # dev server on http://localhost:3000
+npm run build   # static export to out/ — this is ALSO the type check
+npm run lint    # eslint
+```
+
+There is no test runner and no standalone `tsc` script. "Verify a change" means
+`npm run lint`, `npm run build`, and driving the flow in a browser with a wallet.
+
+**`build` and `dev` share `distDir: "out"`.** After running a build, delete
+`out/` and `.next/` before returning to `npm run dev`, or dev crashes on the
+export artifacts.
+
+## Architecture Constraints
+
+- `output: "export"` in `next.config.mjs`. There are **no server components
+  fetching data and no API routes**. Every contract read and write happens in
+  the browser. Anything touching chain data needs `"use client"`.
+- **ABIs are hand-maintained TypeScript consts** in `src/utils/abi/`. They are
+  not generated from the contracts repo. If a contract's external surface
+  changes, edit the const by hand, then `src/utils/addresses.ts` after a
+  redeploy.
+- **Adding or enabling a chain touches eight places.** Missing one usually fails
+  silently; `explorer.ts` is the exception and throws on an unknown chain id.
+  - `src/utils/wagmiConfig.ts` — `chains` and `transports`
+  - `src/utils/chains/*.ts` — a viem `Chain` definition, for non-standard chains
+  - `src/utils/chainConfig.ts` — `getChainConfig(chainId)`
+  - `src/utils/rpcTransport.ts` — `DEFAULT_RPC_URLS`
+  - `src/utils/supportedChainFeed.ts` — `CHAIN_PRICE_FEED_OPTIONS`; `SUPPORTED_CHAINS` derives from it
+  - `src/utils/explorer.ts` — explorer base URLs
+  - `src/utils/addresses.ts` — deployed factory addresses
+  - `src/data/tokens/*.json` plus its static import and mapping in `src/utils/tokenList.ts`
+- **Three numeric scales are in play and must not be conflated.** Base-token
+  amounts use the token's own decimals, read on-chain, never assume 18. Oracle
+  prices and sentiment ratios are WAD (1e18). Contract fees use
+  `DENOMINATOR = 100000`. Check which one a value is in before doing arithmetic.
+
+## Code Style Conventions
+
+- Path alias `@/*` maps to `src/*`.
+- Prefer **wagmi + viem**. ethers v6 remains only in `src/lib/prices.ts` and
+  `src/lib/vaultUtils.ts`. Extend the viem path; do not add new ethers code.
+- For batched reads outside React, use
+  `createPublicClient({ transport: http(), batch: { multicall: true } })`.
+- Reuse the shadcn/ui primitives in `src/components/ui` rather than adding new
+  component libraries.
+- Log through `src/lib/logger.ts` and handle errors through
+  `src/lib/errorHandler.ts`. Do not use raw `console.*`.
+- Access IndexedDB through the `useIndexedDB` hook. `src/lib/fatePoolHook.ts` is
+  a legacy compatibility wrapper; do not build on it. Schema changes require
+  bumping `DATABASE_CONFIG.version` in `src/lib/indexeddb/config.ts`.
+
+## Boundaries
+
+- Never commit `.env.local` or any secret. `NEXT_PUBLIC_PROJECT_ID` is required
+  to run the app locally.
+- Never edit `node_modules/`, `.next/`, or `out/`.
+- Do not modify `next.config.mjs`, `tsconfig.json`, or `package.json` unless
+  explicitly asked. The webpack `resolve.fallback` and `alias` entries there stub
+  out `fs`, `net`, `tls` and React Native async-storage, and the static export
+  breaks without them.
+- Do not introduce a server-side data path. The app must remain statically
+  exportable.
+- Brand assets exist twice on purpose: `brand/` is the canonical kit and `public/`
+  is what the app serves. Changing one means changing both. Do not delete the
+  `public/` copies; `Navbar.tsx` imports `public/logo.svg` directly, and
+  `manifest.json` and `layout.tsx` reference the icons by path.
+
+## Git Workflow
+
+- Branch from `main` with a `feat/`, `fix/`, `docs/` or `chore/` prefix.
+- One pull request per concern.
+- Commit subjects: imperative, roughly 50 characters, capitalized, no trailing
+  period. One line, no body.
+- Pull requests go against `main` on the upstream repository, from a fork.

CONTRIBUTING.md

@@ -0,0 +1,97 @@
+# Contributing to Fate-EVM-Frontend
+
+Thanks for taking the time to contribute. This is the EVM frontend for Fate
+Protocol, a decentralized perpetual prediction market.
+
+## Discord Project Channel
+
+Questions, ideas, or help with a first contribution:
+
+- **Fate channel**: https://discord.com/channels/995968619034984528/1324064370883301386
+
+## Development Setup
+
+1. **Fork and clone:**
+
+   ```bash
+   git clone https://github.com/<your-username>/Fate-EVM-Frontend.git
+   cd Fate-EVM-Frontend
+   git remote add upstream https://github.com/StabilityNexus/Fate-EVM-Frontend.git
+   ```
+
+2. **Install dependencies** (Node.js 18.18 or later; 20 LTS recommended, matching
+   Next.js 15's `^18.18.0 || ^19.8.0 || >= 20.0.0`):
+
+   ```bash
+   npm install
+   ```
+
+3. **Configure environment:**
+
+   ```bash
+   cp env.example .env.local
+   ```
+
+   `NEXT_PUBLIC_PROJECT_ID` is a Reown project ID, free from
+   <https://cloud.reown.com>. Wallet connection will not work without it. RPC
+   endpoints are not required: keyless public defaults per chain live in
+   `src/utils/rpcTransport.ts`.
+
+4. **Run the dev server:**
+
+   ```bash
+   npm run dev
+   ```
+
+   The app runs at `http://localhost:3000`.
+
+> `npm run build` and `npm run dev` share `distDir: "out"`. After a build,
+> delete `out/` and `.next/` before going back to dev, or dev will fail on the
+> export artifacts.
+
+## Verifying a Change
+
+There is no test runner in this repository. Before opening a pull request:
+
+- `npm run lint`
+- `npm run build` — this is also the type check; there is no standalone `tsc` script
+- Exercise the flow in a browser with a wallet on Sepolia or Ethereum Classic
+
+## Coding Style
+
+- TypeScript throughout. The path alias `@/*` maps to `src/*`.
+- The app is a static export, so anything reading chain data runs in the
+  browser. Mark those components `"use client"`.
+- Prefer **wagmi + viem**. ethers v6 survives only in `src/lib/prices.ts` and
+  `src/lib/vaultUtils.ts`; extend the viem path rather than adding new ethers
+  code.
+- UI is shadcn/ui with Tailwind. Reuse the primitives in `src/components/ui`.
+- Log through `src/lib/logger.ts` and handle errors through
+  `src/lib/errorHandler.ts` rather than raw `console` calls.
+- Base-token amounts use the token's own decimals, read on-chain. Never assume
+  18. Oracle prices are WAD (1e18) and contract fees use `DENOMINATOR = 100000`.
+  These three scales are distinct, so check which one a value is in before doing
+  arithmetic on it.
+
+## Changing Contract Calls
+
+ABIs are hand-maintained TypeScript consts in `src/utils/abi/`, not generated.
+If a contract's external surface changes, update the matching const, and update
+`src/utils/addresses.ts` after a redeploy.
+
+## Pull Request Process
+
+1. Branch from `main` with a `feat/`, `fix/`, `docs/` or `chore/` prefix.
+2. Keep one pull request to one concern.
+3. Write commit subjects in the imperative, roughly 50 characters, capitalized,
+   with no trailing period.
+4. Push to your fork and open a pull request against `main` on the upstream
+   repository.
+5. Fill in the pull request template, including the AI usage disclosure.
+6. CodeRabbit reviews automatically. Address its comments alongside maintainer
+   feedback.
+
+## Reporting Issues
+
+Open an issue with a clear description, steps to reproduce, the chain and wallet
+you used, and any console output or screenshots.

README.md

@@ -237,20 +237,12 @@ npm run start
 
 ## Contributing
 
-We welcome contributions of all kinds! To contribute:
+We welcome contributions of all kinds. See **[CONTRIBUTING.md](CONTRIBUTING.md)**
+for development setup, coding style, and the pull request process.
 
-1. Fork the repository and create your feature branch (`git checkout -b feature/AmazingFeature`).
-2. Commit your changes (`git commit -m 'Add some AmazingFeature'`).
-3. Run the development workflow commands to ensure code quality:
-   - `npm run lint`
-4. Push your branch (`git push origin feature/AmazingFeature`).
-5. Open a Pull Request for review.
-
-If you encounter bugs, need help, or have feature requests:
-
-- Please open an issue in this repository providing detailed information.
-- Describe the problem clearly and include any relevant logs or screenshots.
-
-We appreciate your feedback and contributions!
+Questions and ideas are welcome in our
+[Discord channel](https://discord.com/channels/995968619034984528/1324064370883301386).
+If you hit a bug, please open an issue with clear steps to reproduce and any
+relevant logs or screenshots.
 
 © 2025 The Stable Order.

SECURITY.md

@@ -0,0 +1,52 @@
+# Security Policy
+
+## Supported Versions
+
+Fate Protocol's EVM frontend is continuously deployed: a merge to `main` publishes to GitHub Pages,
+and there are no tagged releases. Security fixes therefore target the latest `main`, and users always
+receive the current deployment.
+
+The protocol's smart contracts live in a separate repository. If a report concerns on-chain
+behaviour rather than the interface, please say so and the maintainers will route it.
+
+## Reporting a Vulnerability
+
+Please do not disclose security vulnerabilities through public GitHub issues, pull requests, or
+public Discord channels.
+
+For security-sensitive reports, contact a project maintainer privately. Maintainers are listed in
+[MAINTAINERS.md](MAINTAINERS.md) and can be reached by direct message on the
+[Stability Nexus Discord server](https://discord.gg/hjUhu33uAn).
+
+A vulnerability report should include, where possible:
+
+- the affected component, page, or contract
+- the affected commit, or the date you observed the behaviour on the deployed site
+- a description of the vulnerability and its impact
+- steps to reproduce the issue
+- a proof of concept, if available
+- any suggested mitigation
+
+Please avoid publicly sharing exploit details until the maintainers have had an opportunity to
+investigate and address the issue.
+
+Maintainers aim to acknowledge security reports within 14 days, and will coordinate remediation and
+disclosure with the reporter where appropriate.
+
+## Scope
+
+This repository is a statically exported browser client. It has no server runtime, no API routes,
+and no user accounts or credential storage. Private keys never reach it: transaction signing is
+delegated entirely to the user's wallet.
+
+Reports most relevant to this repository include anything that could cause a user to sign a
+transaction they did not intend, misrepresent on-chain state in a way that changes a trading
+decision, or introduce untrusted content into the interface.
+
+Issues in third-party wallets, RPC providers, or upstream dependencies should be reported to those
+projects directly. If a dependency vulnerability affects Fate specifically, please tell us as well.
+
+## Non-Security Bugs
+
+Non-security bugs and feature requests should continue to be reported through the project's
+[GitHub Issues](https://github.com/StabilityNexus/Fate-EVM-Frontend/issues).