diff --git a/README.md b/README.md
new file mode 100644
index 0000000..60a50d6
--- /dev/null
+++ b/README.md
@@ -0,0 +1,82 @@
+# MinerOps
+
+MinerOps is a self-hosted mining fleet operations console for tracking, repairing, locating, and controlling WhatsMiner ASICs.
+
+## Current deployment
+
+- Hub CT: 306
+- Public URL: https://plexus.lussier.cc
+- Repository: https://gitea.lussier.cc/lussierj/minerops
+- Backend container: minerops-backend
+- Database container: minerops-postgres
+- Redis container: minerops-redis
+
+## Main pages
+
+- /dashboard - fleet dashboard and repair summary
+- /repairs - repair queue, notes, parts used, history, CSV export
+- /locations - room/rack/shelf location map
+- /system-health - app, database, table size, route, and retention health
+
+## Repair workflow
+
+1. Open /repairs.
+2. Find the miner by MAC, IP, model, serial, or problem.
+3. Add repair notes.
+4. Select parts used and quantity.
+5. Update repair status.
+6. Use History to edit or delete mistaken entries.
+7. Mark Ready to Shelf or use Move to Shelf.
+8. Return the miner to an open shelf position on /locations.
+
+## Repair statuses
+
+- Open
+- Diagnosing
+- Waiting Parts
+- In Progress
+- Testing
+- Ready to Shelf
+- Needs Follow-up
+- Completed
+- Failed
+- Cancelled
+
+## Retention
+
+Retention is currently scheduled in dry-run mode.
+
+Current intended policy:
+
+- Raw status snapshots: 30 days
+- Hourly rollups: 1 year or longer
+- Daily rollups: long term
+- Repair, location, and MAC history: permanent
+
+Verify /system-health before switching retention to apply mode.
+
+## Common commands
+
+Health check:
+
+pct exec 306 -- bash -lc "curl -s http://127.0.0.1:8000/api/health"
+
+Rebuild backend:
+
+pct exec 306 -- bash -lc "cd /opt/minerops && docker compose build backend || docker-compose build backend"
+pct exec 306 -- bash -lc "cd /opt/minerops && docker compose up -d --force-recreate backend || docker-compose up -d --force-recreate backend"
+
+Check logs:
+
+pct exec 306 -- bash -lc "docker logs minerops-backend --since 30m"
+
+Git status:
+
+pct exec 306 -- bash -lc "cd /opt/minerops && git status --short"
+
+## Safety notes
+
+- Do not commit .env.
+- Do not commit backups, logs, database dumps, imports, or runtime data.
+- Check /system-health after major changes.
+- Commit and push after each stable working change.