From 28728fdcea3a69c64a6f04933956a35ccd91307d Mon Sep 17 00:00:00 2001
From: Fusion <noreply@runfusion.ai>
Date: Thu, 14 May 2026 02:18:25 +0200
Subject: [PATCH] =?UTF-8?q?feat(FN-002):=20complete=20Step=206=20=E2=80=94?=
 =?UTF-8?q?=20Root=20README=20and=20Scope=20Boundaries?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md | 97 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 97 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..ca622ad
--- /dev/null
+++ b/README.md
@@ -0,0 +1,97 @@
+# Headquarter
+
+Hosted workspace and tool-orchestration platform where authenticated users create projects, connect Git repositories, and spawn self-hosted tools such as RunFusion and code-server.
+
+## Current Status
+
+This repository is an initial scaffold (FN-002). It provides:
+
+- React + Vite + TypeScript frontend (`apps/web`)
+- FastAPI + Python backend (`apps/api`)
+- Root monorepo tooling (pnpm workspace, Makefile)
+- Docker Compose local development stack
+- Deployment skeleton for Portainer + Traefik
+- Automated tests (Vitest + pytest)
+
+## Repository Layout
+
+```text
+├── apps/
+│   ├── web/          # React frontend
+│   └── api/          # FastAPI backend
+├── docs/             # Architecture, development, and deployment docs
+├── deploy/           # Portainer/Traefik deployment examples
+├── docker-compose.yml
+├── docker-compose.traefik.yml
+├── package.json      # Root monorepo scripts
+├── Makefile          # Common local workflows
+└── .env.example      # Shared environment variables
+```
+
+## Prerequisites
+
+- Node.js ≥ 20 and pnpm ≥ 9
+- Python ≥ 3.11
+- Docker and Docker Compose (optional, for local Postgres)
+
+## Quickstart
+
+```bash
+# Install dependencies
+make install
+
+# Copy environment examples
+cp .env.example .env
+cp apps/web/.env.example apps/web/.env
+
+# Run tests
+make test
+
+# Start frontend and backend in development mode
+make dev
+```
+
+### Docker Compose
+
+```bash
+docker compose up --build -d
+```
+
+This starts the API, web frontend, and PostgreSQL.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `make install` | Install Node and Python dependencies |
+| `make dev` | Start frontend and backend in parallel |
+| `make test` | Run frontend and backend tests |
+| `make lint` | Run linters |
+| `make typecheck` | Run type checkers |
+| `make build` | Build frontend and backend |
+| `make compose-up` | Start Docker Compose stack |
+| `make compose-down` | Stop Docker Compose stack |
+
+## Documentation
+
+- [Architecture](docs/architecture.md) — System design and MVP phases
+- [Development](docs/development.md) — Local setup and day-to-day commands
+- [Deployment](docs/deployment.md) — Portainer/Traefik assumptions
+- [Deploy Skeleton](deploy/README.md) — Deployment file reference
+
+## Scope Boundaries
+
+This scaffold intentionally defers detailed implementation to follow-up tasks:
+
+- **FN-004** — Backend domain models, database migrations, API endpoints, auth integration
+- **FN-005** — Frontend dashboard navigation, project creation, authenticated flows
+- **FN-006** — Full deployment automation, dynamic Traefik labels for spawned tool containers
+- **FN-003** — Manifest-driven tool registry
+- **FN-007** — Provider-independent Git connection model
+- **FN-008** — RunFusion executable environment proof of concept
+- **FN-009** — Persistent config and secrets handling
+- **FN-010** — code-server manifest and spawn flow
+
+## License
+
+TBD