docs: add repository guidelines and documentation

AGENTS.md

@@ -0,0 +1,38 @@
+# AGENTS.md
+
+Instructions for AI coding agents working in this repository.
+
+## Project Overview
+
+ThruBox Client is a zero-runtime-dependency TypeScript SDK for the [ThruBox Server](https://github.com/AOSSIE-Org/ThruBox-Server), a self-hostable encrypted message relay. The SDK sends, receives, and manages encrypted messages over the relay's REST API. Works in Node.js 18+ and modern browsers.
+
+## Repository Layout
+
+- `src/` — SDK source (TypeScript)
+- `tests/` — Vitest test suite
+- `public/` — logo assets referenced by README
+- `brand/` — logo, favicons, and brand guidelines (see `brand/Brand.md`)
+
+## Build, Test & Lint
+
+```bash
+npm install
+npm run build          # tsup — builds ESM + CJS with type declarations
+npm test               # vitest run
+npm run test:watch     # vitest watch mode
+npm run coverage       # vitest run --coverage
+npm run lint           # eslint src/ tests/
+npm run format         # prettier --write
+npm run format:check   # prettier --check
+```
+
+## Hard Constraints
+
+- **Zero runtime dependencies.** Only `devDependencies` may be added for build/test tooling — never add a runtime dependency without discussing it in an issue first. This is enforced by `.coderabbit.yaml` review rules.
+- The package must keep shipping both ESM and CJS builds with TypeScript declarations (via `tsup`) — don't introduce APIs that only work in one module format.
+- Use the native `fetch` API rather than an HTTP client library, to stay dependency-free and work in both Node and browsers.
+
+## Conventions
+
+- New functionality needs tests in `tests/` using Vitest.
+- Errors are typed (specific error classes for rate limiting, payload size, not found, etc.) — follow this pattern for new failure modes rather than throwing generic `Error`.

CONTRIBUTING.md

@@ -1,4 +1,4 @@
-# Contributing to TODO: Project Name
+# Contributing to ThruBox Client SDK
 
 ⭐ First off, thank you for considering contributing to this project! ⭐
 
@@ -9,7 +9,7 @@ We welcome contributions from everyone. By participating in this project, you ag
 **All project communication MUST happen on Discord. We do not pay attention to GitHub notifications.**
 
 - Join our [Discord server](https://discord.gg/hjUhu33uAn) before starting any work
-- Post your PR/issue updates in the relevant Discord channel (**MANDATORY**)
+- Post your PR/issue updates in the [#thrubox channel](https://discord.com/channels/995968619034984528/1525382676964446258) (**MANDATORY**)
 - All discussions, questions, and updates should be on Discord
 - GitHub is for code only - Discord is for communication
 
@@ -68,36 +68,40 @@ What we expect:
 
 ### Prerequisites
 
-TODO: List prerequisites specific to your project
+- Node.js 18 or later
+- npm (or yarn/pnpm)
 
 ### Setup
 
 1. **Fork the Repository**
+
    ```bash
    # Click the 'Fork' button at the top right of this page
    ```
 
 2. **Clone Your Fork**
+
    ```bash
-   git clone https://github.com/YOUR_USERNAME/TODO.git
-   cd TODO
+   git clone https://github.com/YOUR_USERNAME/ThruBox-Client.git
+   cd ThruBox-Client
    ```
 
 3. **Add Upstream Remote**
+
    ```bash
-   git remote add upstream https://github.com/AOSSIE-Org/TODO.git
+   git remote add upstream https://github.com/AOSSIE-Org/ThruBox-Client.git
    ```
 
 4. **Install Dependencies**
+
    ```bash
    npm install
-   # or yarn install
-   # or pnpm install
    ```
 
-5. **Run the Project**
+5. **Build the SDK**
+
    ```bash
-   npm run dev
+   npm run build
    ```
 
 ## 🔄 Development Workflow
@@ -121,12 +125,13 @@ git checkout -b fix/your-bug-fix
 
 ### 3. Test Your Changes
 
-TODO: Add project-specific testing instructions
+Run the test suite (Vitest), linter, and format check before opening a PR:
 
 ```bash
-npm test
-# or
-npm run lint
+npm test              # run the Vitest suite
+npm run coverage       # run tests with coverage
+npm run lint           # ESLint
+npm run format:check   # Prettier check
 ```
 
 ### 4. Commit Your Changes
@@ -210,7 +215,7 @@ Steps to test the changes
 
 ### After Submission
 
-- Post your PR in the project's Discord channel for visibility(**IMPORTANT**)
+- Post your PR in the [#thrubox channel](https://discord.com/channels/995968619034984528/1525382676964446258) for visibility(**IMPORTANT**)
 - Respond to review comments promptly
 - Make requested changes in new commits
 - Be patient - maintainers will review when available
@@ -223,7 +228,7 @@ Steps to test the changes
 
 ## 📝 Code Style Guidelines
 
-TODO: Add project-specific code style guidelines
+This SDK is **zero-dependency at runtime** — only `devDependencies` may be used for build/test tooling. Do not add runtime dependencies without discussing it in an issue first. The package ships both ESM and CJS builds (via `tsup`) with TypeScript declarations, so avoid Node/browser-specific APIs that aren't available in both environments (the SDK uses the native `fetch` API).
 
 ### General Guidelines
 
@@ -538,4 +543,4 @@ If you encounter issues not covered here:
 - Check for existing PRs before starting to avoid duplication, as there might PRs that didn't mention the related issue
 
 
-Thank you for contributing to TODO! Your efforts help make this project better for everyone. 🚀
+Thank you for contributing to ThruBox Client SDK! Your efforts help make this project better for everyone. 🚀

MAINTAINERS.md

@@ -0,0 +1,25 @@
+# Maintainers, Mentors and Ideators
+
+This document lists the individuals fulfilling the key roles of [Maintainer](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Maintainer.md), [Mentor](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Mentors.md) and [Ideator](https://github.com/AOSSIE-Org/Info/blob/main/Roles/Ideator.md) for this repository, in accordance with [AOSSIE's Role Definitions](https://github.com/AOSSIE-Org/Info/tree/main/Roles).
+
+---
+
+> **Note:** If multiple contributors are fulfilling a role in a single repository, please include and fill out the extra columns to clarify responsibilities (e.g., `Project / Feature Idea`, `Area / Focus`, and `Proposal / Discussion Link` for Ideators; `Area / Focus` for Mentors and Maintainers). If there is only one person for a role, do not add these columns.
+
+## Mentors
+
+| Name  | GitHub Username | Discord Username |
+| ----- | ---------------- | ------------------ |
+| Bruno | @Zahnentferner   | @b.wp              |
+
+## Maintainers
+
+| Name    | GitHub Username    | Discord Username | Area / Focus                      |
+| ------- | ------------------- | ------------------ | ----------------------------------- |
+| Atharva | @Atharva0506        | @atharva0506        | Repository Maintenance & Merging |
+| Karan   | @kumawatkaran523    | @karankk9616        | Repository Maintenance & Merging |
+| Aditya  | @adityabhattad2021  | @adityabhattad      | Repository Maintenance & Merging |
+
+## Ideators
+
+_No Ideators are currently assigned to this repository._

README.md

@@ -115,6 +115,23 @@ await relay.delete(messages[0].id);
 
 ---
 
+## 🛠️ Development
+
+To build and test the SDK itself (not just consume it):
+
+```bash
+git clone https://github.com/AOSSIE-Org/ThruBox-Client.git
+cd ThruBox-Client
+npm install
+
+npm run build     # build ESM + CJS output with tsup
+npm test          # run the Vitest suite
+npm run coverage  # run tests with coverage
+npm run lint      # ESLint
+```
+
+---
+
 ## 📖 API Reference
 
 ### `new RelayClient(baseUrl, options?)`

brand/Brand.md

@@ -0,0 +1,43 @@
+# ThruBox Brand Kit
+
+This folder is the canonical source for ThruBox's visual identity: logos, favicons/icons, and color palette. All assets referenced below live in this `brand/` folder.
+
+## Logo
+
+| Asset | File |
+| --- | --- |
+| ThruBox logo (SVG, with wordmark) | [`thrubox-logo.svg`](./thrubox-logo.svg) |
+| AOSSIE org logo (SVG) | [`aossie-logo.svg`](./aossie-logo.svg) |
+
+The ThruBox mark is a Menger-sponge-style cube made of green tessellated tiles wrapped around a padlock, representing an encrypted "box" relaying data between clients.
+
+## Favicons & Icons
+
+Generated from `thrubox-logo.svg` at the standard sizes used across browsers, bookmarks, and mobile home screens:
+
+| File | Size | Use |
+| --- | --- | --- |
+| [`favicon.ico`](./favicon.ico) | 16/32/48 (multi-res) | Classic browser favicon |
+| [`favicon-16x16.png`](./favicon-16x16.png) | 16×16 | Browser tab |
+| [`favicon-32x32.png`](./favicon-32x32.png) | 32×32 | Browser tab (HiDPI) |
+| [`favicon-48x48.png`](./favicon-48x48.png) | 48×48 | Windows taskbar |
+| [`apple-touch-icon.png`](./apple-touch-icon.png) | 180×180 | iOS home screen |
+| [`icon-512.png`](./icon-512.png) | 512×512 | PWA manifest / app icon |
+
+This package has no bundled web app (it's a Node.js/browser SDK library), so these assets aren't wired into an `index.html` — they're provided as the canonical brand exports for use in demo apps, npm listing pages, or documentation sites that consume this SDK.
+
+## Color Palette
+
+Sourced directly from `thrubox-logo.svg`:
+
+| Swatch | Name | Hex | Usage in logo |
+| --- | --- | --- | --- |
+| 🟩 | ThruBox Green (light) | `#3eb03e` | Sponge tile — top face |
+| 🟩 | ThruBox Green (mid) | `#228B22` | Sponge tile — front face, wordmark |
+| 🟩 | ThruBox Green (dark) | `#145A14` | Sponge tile — side face |
+| ⬛ | Outline | `#0f420f` | Tile stroke |
+| 🟨 | Lock Gold | `#FFC517` | Padlock accent, sourced from `thrubox-logo.svg` |
+
+## Typography
+
+This is a non-UI project (TypeScript SDK library) — there is no application typography to document. The wordmark in `thrubox-logo.svg` uses `'Arial Black', system-ui, sans-serif` at weight 900 as a logotype only.