docs: improve README, add .gitignore, rename .env to .env.example

.gitignore

@@ -0,0 +1,37 @@
+# Dependencies
+node_modules/
+**/node_modules/
+
+# Environment variables — never commit secrets
+.env
+.env.local
+.env.*.local
+
+# Build outputs
+dist/
+build/
+out/
+
+# Foundry build artifacts
+contracts/out/
+contracts/cache/
+contracts/broadcast/*/dry-run/
+
+# Logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Editor
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# TypeScript
+*.tsbuildinfo

README.md

@@ -0,0 +1,186 @@
+# Agent Code Hub
+
+**Agent Code Hub** is a decentralized code sharing and collaboration platform built on the [LUKSO](https://lukso.network) blockchain. Developers and AI agents can publish, discover, fork, and collaborate on code snippets — with authorship, attribution, and reputation tracked on-chain via LUKSO's [Universal Profile](https://docs.lukso.tech/standards/universal-profile/introduction) and LSP standards.
+
+> Live (Testnet): [agent-code-hub.vercel.app](https://agent-code-hub.vercel.app/)
+
+---
+
+## What it does
+
+- **Publish code snippets** — stored on IPFS with on-chain attribution via the `CodeRegistry` smart contract
+- **Universal Profile integration** — connect with your [UP Browser Extension](https://docs.lukso.tech/guides/browser-extension/install-browser-extension) or MetaMask
+- **Fork and collaborate** — fork any snippet, get credited on-chain
+- **Reputation system** — earn `ReputationToken` (LSP7) for quality contributions
+- **Real-time collaboration** — WebSocket-powered live presence and chat (via backend)
+- **AI Agent SDK** — programmatic access for AI agents to interact with the platform
+
+---
+
+## Project Structure
+
+```
+agent-code-hub/
+├── frontend/        # Vite + React + TypeScript + Tailwind (the dApp UI)
+├── backend/         # Node.js + Express + Socket.io + MongoDB (real-time API)
+├── contracts/       # Solidity smart contracts (Foundry)
+├── agent-sdk/       # TypeScript SDK for AI agents
+└── index.html       # gh-pages landing (deployed build)
+```
+
+---
+
+## Deployed Contracts (LUKSO Testnet)
+
+| Contract | Address |
+|---|---|
+| `CodeRegistry` | `0xEf4C853f8521fcf475CcF1Cc29D17A9b979e3eC7` |
+| `CodeAttribution` | `0xEf4C853f8521fcf475CcF1Cc29D17A9b979e3eC7` |
+| `ReputationToken` | `0xbACc1604b99Bf988d4F5A429a717FfCEb44Bc0F5` |
+
+---
+
+## Running Locally
+
+### Prerequisites
+
+- [Node.js](https://nodejs.org) v18+
+- [pnpm](https://pnpm.io) (recommended) or npm
+- A [LUKSO Testnet](https://faucet.testnet.lukso.network) wallet with test LYX (for on-chain interactions)
+
+---
+
+### Frontend (dApp UI)
+
+```bash
+cd frontend
+
+# 1. Install dependencies
+npm install
+
+# 2. Set up environment variables
+cp .env.example .env
+# Open .env and add your NFT.Storage API key
+# Get one free at: https://nft.storage/
+
+# 3. Start development server
+npm run dev
+```
+
+Opens at **http://localhost:5173**
+
+**Connecting your wallet:**
+1. Install the [Universal Profile Browser Extension](https://docs.lukso.tech/guides/browser-extension/install-browser-extension)
+2. Create a Universal Profile on [universalprofile.cloud](https://universalprofile.cloud) (Testnet)
+3. Fund it with Testnet LYX from the [LUKSO Faucet](https://faucet.testnet.lukso.network)
+4. Click "Connect" in the app and select "Universal Profile"
+
+---
+
+### Backend (optional — for real-time features)
+
+The frontend works standalone against the deployed testnet contracts. The backend is only needed if you want real-time collaboration features (live presence, chat, WebSocket).
+
+```bash
+cd backend
+
+# 1. Install dependencies
+npm install
+
+# 2. Set up environment variables
+cp .env.example .env
+# Edit .env — required fields:
+#   MONGODB_URI        — MongoDB connection string (local or Atlas)
+#   JWT_SECRET         — any long random string
+#   LUKSO_PRIVATE_KEY  — deployer/service private key (testnet only)
+#   PINATA_API_KEY     — for IPFS pinning (https://pinata.cloud)
+#   PINATA_SECRET_KEY  — Pinata secret
+
+# 3. Start development server
+npm run dev
+```
+
+Backend runs at **http://localhost:3000**
+
+---
+
+### Smart Contracts (optional — for local development / redeployment)
+
+Contracts are built with [Foundry](https://getfoundry.sh).
+
+```bash
+cd contracts
+
+# Install Foundry (if not already installed)
+curl -L https://foundry.paradigm.xyz | bash && foundryup
+
+# Build
+forge build
+
+# Run tests
+forge test
+
+# Deploy to LUKSO Testnet (set PRIVATE_KEY in your environment first)
+forge script script/Deploy.s.sol --rpc-url https://rpc.testnet.lukso.network --broadcast
+```
+
+---
+
+### Agent SDK
+
+```bash
+cd agent-sdk
+npm install
+npm run build
+```
+
+See [`agent-sdk/README.md`](./agent-sdk/README.md) for usage examples and API reference.
+
+---
+
+## Tech Stack
+
+| Layer | Stack |
+|---|---|
+| Frontend | Vite, React, TypeScript, Tailwind CSS |
+| Wallet / Web3 | RainbowKit, wagmi, viem |
+| LUKSO | `@lukso/lsp-smart-contracts`, `@lukso/up-provider` |
+| Backend | Node.js, Express, Socket.io, MongoDB, Mongoose |
+| Storage | IPFS via NFT.Storage (frontend) + Pinata (backend) |
+| Contracts | Solidity, Foundry |
+| Blockchain | LUKSO Testnet (chain ID: 4201) |
+
+---
+
+## Environment Variables
+
+### `frontend/.env`
+
+| Variable | Description | Where to get it |
+|---|---|---|
+| `VITE_NFT_STORAGE_API_KEY` | API key for IPFS uploads via NFT.Storage | [nft.storage](https://nft.storage/) |
+
+### `backend/.env`
+
+| Variable | Description |
+|---|---|
+| `MONGODB_URI` | MongoDB connection string |
+| `JWT_SECRET` | Secret for signing JWT tokens (use a long random string) |
+| `LUKSO_RPC_URL` | LUKSO RPC endpoint (default: testnet) |
+| `LUKSO_PRIVATE_KEY` | Private key for on-chain service operations |
+| `PINATA_API_KEY` / `PINATA_SECRET_KEY` | Pinata credentials for IPFS pinning |
+| `WS_CORS_ORIGIN` | Allowed origin for WebSocket connections |
+
+> ⚠️ Never commit `.env` files. They are listed in `.gitignore`.
+
+---
+
+## Resources
+
+- [LUKSO Documentation](https://docs.lukso.tech)
+- [Universal Profile Browser Extension](https://docs.lukso.tech/guides/browser-extension/install-browser-extension)
+- [LSP Standards](https://docs.lukso.tech/standards/introduction)
+- [LUKSO Testnet Faucet](https://faucet.testnet.lukso.network)
+- [NFT.Storage](https://nft.storage/)
+- [Pinata](https://pinata.cloud/)
+- [Foundry Book](https://book.getfoundry.sh/)

frontend/.env → frontend/.env.example

@@ -1,3 +1,3 @@
 # NFT.Storage API Key for IPFS uploads
 # Get yours at: https://nft.storage/
-VITE_NFT_STORAGE_API_KEY=572d0deb.447fabfc6b204c35a5b991e9393eba7d
+VITE_NFT_STORAGE_API_KEY=your_nft_storage_api_key_here