From 84e561f2c7112af13c15d9deb9a7efc094cc53cb Mon Sep 17 00:00:00 2001
From: arsam <me@asabbagh.com>
Date: Fri, 18 Sep 2026 23:15:32 +0330
Subject: [PATCH] Import documentation: AGENTS.md

Import the existing local project snapshot. This commit organizes existing files; it does not represent newly developed functionality.
---
 AGENTS.md | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 61 insertions(+)
 create mode 100644 AGENTS.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..5d28436
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,61 @@
+# Repository Guidelines
+
+## Commands
+
+Run from `cshare-app/`:
+
+```sh
+npm run dev       # Vite dev server
+npm run build     # Build + precompress (creates .gz/.br)
+npm run check     # lint + build (run before committing)
+npm run lint      # ESLint
+```
+
+Run from `backend/`:
+
+```sh
+npm run dev       # tsx watch src/server.ts
+npm test          # tsx --test test/*.test.ts
+npm run build     # tsc
+npm run check     # test + build (run before committing)
+```
+
+## Architecture
+
+**Two packages:** `cshare-app/` (React 19 + Vite 8, JavaScript/JSX, no TypeScript) and `backend/` (Express 5 + TypeScript strict mode).
+
+**Backend storage:** Currently uses local JSON (`backend/data/db.json`) and disk storage. PostgreSQL/Redis/R2 adapters are planned in `CONTINUE.md` but not yet implemented.
+
+**Frontend routing:** React Router v7 with lazy-loaded routes. All routes defined in `src/App.jsx`.
+
+**Styling:** Tailwind CSS 4 via `@tailwindcss/vite` plugin (not PostCSS). Custom design system in `src/index.css` with CSS variables and component classes (`.btn`, `.card`, `.input`).
+
+**Toast system:** `ToastProvider` wraps app in `App.jsx`. Use `useToast()` hook → `addToast(message, type)` where type is `'success' | 'info' | 'error'`.
+
+**API client:** `src/lib/api.js` contains `uploadFile` (XHR with progress), `listFiles`, `deleteFile`, `getDashboardStats`, `resolveLink`, `downloadUrl`, `previewUrl`.
+
+## Environment
+
+**Frontend:** Set `VITE_API_BASE_URL=http://localhost:4001` only when API runs on different port. Omit in production if using Nginx reverse proxy (frontend calls `window.location.origin`).
+
+**Backend:** Requires `.env` with `JWT_ACCESS_SECRET`, `JWT_REFRESH_SECRET`, `ADMIN_API_KEY` (64+ char random strings). See `backend/.env.example`.
+
+**Build gotcha:** `dist/` may be owned by root. If `npm run build` fails with `EACCES`, run `sudo chown -R $(whoami) cshare-app/dist/`.
+
+## Key Files
+
+- `CONTINUE.md` — Full production roadmap (Postgres, Redis, R2, auth, Stripe implementation plan)
+- `CLAUDE.md` — Detailed architecture reference
+- `PRODUCTION.md` — Deployment and Nginx configuration
+- `cshare-app/src/App.jsx` — All route definitions
+- `cshare-app/src/lib/api.js` — API client
+- `backend/src/server.ts` — Express app bootstrap
+- `backend/ecosystem.config.cjs` — PM2 configuration (reads `.env` file)
+
+## Style
+
+**Frontend:** PascalCase for components (`UploadPage.jsx`), camelCase for hooks (`useLenis.js`) and data modules (`mockData.js`). Two-space indentation, single quotes, semicolons.
+
+**Backend:** TypeScript strict mode, named exports. Route modules named by resource (`files.ts`, `links.ts`, `auth.ts`).
+
+ESLint configured in `cshare-app/eslint.config.js` (flat config, React hooks + refresh plugins).