Track HiveGrid Cloud planning reference

hivegrid-cloud/docs/quickstart.md

@@ -0,0 +1,88 @@
+# Quickstart
+
+Use this path to get from a fresh checkout to a local web runtime. It is for local development only: keep production secrets out of `.env`, use placeholders in examples, and run browser, Playwright, Cypress, or other E2E checks manually unless a focused run is explicitly approved.
+
+## 1. Enable the pinned package manager
+
+From the repository root, enable Corepack and activate the pinned pnpm version:
+
+```sh
+corepack enable
+corepack prepare pnpm@10.33.0 --activate
+```
+
+Then install dependencies:
+
+```sh
+pnpm install
+```
+
+## 2. Create local environment placeholders
+
+Copy the example environment file:
+
+```sh
+cp .env.example .env
+```
+
+Fill only local placeholder values. Do not paste production credentials, database passwords, API keys, Mailjet credentials, Stripe secrets, OAuth secrets, or deployment tokens into local docs or examples.
+
+Minimum local values to review:
+
+- `APP_NAME`: a local display name.
+- `SESSION_SECRET`: a local placeholder secret.
+- `CRYPTO_SECRET`: a separate local placeholder secret.
+- `DATABASE_URL`: a local PostgreSQL connection string for Prisma.
+- `APP_BASE_DOMAIN`, `WEB_APP_HOST`, `ADMIN_APP_HOST`, `API_HOST`, and `APP_PROTOCOL`: keep the split-host defaults from `.env.example`.
+- `PORT` / `API_PORT`: listener bind ports only; keep defaults unless you need a custom local port.
+
+## 3. Prepare PostgreSQL and Prisma
+
+Start a local PostgreSQL database and point `DATABASE_URL` at it. The active application database uses PostgreSQL through Prisma.
+
+Apply migrations:
+
+```sh
+pnpm exec prisma migrate dev
+```
+
+If you are bootstrapping a disposable local database and migrations are not enough, use a schema push as a local fallback:
+
+```sh
+pnpm exec prisma db push
+```
+
+Keep `DIRECT_URL` as a placeholder unless you intentionally need a direct Prisma database connection for local maintenance.
+
+## 4. Seed local data
+
+Seed the local database after the schema is ready:
+
+```sh
+pnpm seed
+pnpm run permissions:sync
+```
+
+Seeded accounts are development conveniences only. `pnpm run permissions:sync` aligns the static role/permission matrix after schema or permission changes. Do not reuse seeded passwords or seed production databases from this quickstart.
+
+## 5. Start the web runtime
+
+Run the active `@toolctrl/web` React Router runtime in `apps/web/app`:
+
+```sh
+pnpm dev
+```
+
+Open `http://app.localhost:3000` for the tenant app and `http://admin.localhost:3000` for admin. The root `pnpm dev` command starts only the `@toolctrl/web` runtime; when API work is in scope, run `pnpm --filter @toolctrl/api dev` separately and open `http://api.localhost:3001`.
+
+## 6. Optional worker and Redis
+
+Redis is optional for the default quickstart. Only enable it when you are working on queue or worker behavior:
+
+- Set `WORKER_ENABLED=true`.
+- Set `BULLMQ_REDIS_URL` to a local Redis placeholder such as `redis://localhost:6379/0`.
+- Leave `REDIS_URL` as a fallback-only platform binding unless that contract is being tested.
+
+## 7. Verification boundary
+
+For quick local documentation checks, prefer scoped non-E2E commands such as linting changed files or running the milestone docs verifier when available. Browser automation, Playwright, Cypress, and other E2E execution are manual-only by default in this project and should not be added to automated quickstart steps without explicit approval for that exact run.