docs: update project documentation (#7)

Author: dearzubi

CONTRIBUTING.md

@@ -0,0 +1,45 @@
+# Contributing
+
+Thanks for contributing. Keep changes focused, small, and aligned with the
+existing project conventions.
+
+## Before you start
+
+- Read `AGENTS.md` for the full coding, documentation, testing, and workflow
+  rules.
+- Use Node 24 and pnpm only.
+- Create branches with a conventional prefix, such as `fix/`, `feat/`,
+  `docs/`, `chore/`, or `refactor/`.
+- Keep dependency changes separate unless they are required for the work.
+
+## Development
+
+```bash
+nvm use
+corepack enable
+pnpm install
+cp .env.example .env
+pnpm dev
+```
+
+Use `pnpm compose up -d postgres redis` when you only need supporting local
+services. Use `pnpm compose up -d --build` when you want the app and services to
+run through Docker Compose.
+
+## Checks
+
+Run the relevant checks before opening a pull request:
+
+```bash
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+## Pull requests
+
+- Use a conventional PR title.
+- Explain what changed and how it was tested.
+- Include both unit and integration coverage for behaviour changes.
+- Do not commit local env overrides or the root `.env`.

README.md

@@ -1,26 +1,44 @@
-# Template
+# NestJs Fastify React Full Stack Template
 
 A reusable full-stack TypeScript application template with NestJS, Fastify,
 React, PostgreSQL, Redis, Docker Compose, and observability built in. See
-`AGENTS.md` for conventions, `docs/adr/` for recorded architectural decisions,
-and `docs/runbooks/` for operational guides.
+`CONTRIBUTING.md` for contribution guidance, `AGENTS.md` for conventions,
+`docs/adr/` for recorded architectural decisions, and `docs/runbooks/` for
+operational guides.
 
-## Quick start
+## Project scope
 
-```bash
-nvm use            # Node 24
-corepack enable    # pnpm 11
-pnpm install
-cp .env.example .env    # docker-compose values; not committed
-# Install once per Docker host. Use 3.7.0-arm64 on ARM64 hosts.
-docker plugin install grafana/loki-docker-driver:3.7.0 --alias loki --grant-all-permissions
-pnpm compose up -d      # postgres, redis, prometheus, grafana, loki, tempo
-pnpm dev
-```
+This template is intentionally kept minimal. It provides the foundation for a
+full-stack service, but it does not try to include every capability a real
+product usually needs.
 
-After cloning for a new project, run the one-time rename helper:
+There is no authentication, authorisation, user management, rate limiting,
+abuse prevention, billing, background job system, email delivery, object
+storage, feature flagging, admin area, or domain-specific workflow. Add those
+pieces deliberately based on the product you are building, rather than carrying
+generic defaults that may not fit.
+
+## Tech stack
+
+| Layer | Tech |
+| --- | --- |
+| Monorepo | pnpm workspaces, TypeScript |
+| Backend | NestJS, Fastify |
+| Frontend | Vite, React, Tailwind CSS, shadcn/ui |
+| Database | PostgreSQL, Kysely, kysely-codegen |
+| Cache | Redis |
+| Validation and config | Zod |
+| Testing | Vitest, Playwright browser mode, Testcontainers |
+| Linting and formatting | Biome |
+| Container runtime | Docker, Docker Compose |
+| Observability | Prometheus, Grafana, Loki, Tempo, OpenTelemetry Collector |
+| Git workflow | Lefthook, commitlint, conventional commits |
+
+## Template cloning and project init
 
 ```bash
+git clone https://github.com/dearzubi/nestjs-fastify-react-template.git my-app
+cd my-app
 bash scripts/init-project.sh acme
 ```
 
@@ -30,10 +48,68 @@ database placeholders, compose identifiers, and observability queries. It also
 adds `docs/superpowers/` to `.git/info/exclude` for local AI-agent working
 files.
 
+## Quick start
+
+### 1. Set up local tooling
+
+```bash
+nvm use
+corepack enable
+```
+
+The Docker Compose stack uses the Loki Docker logging driver. Install it once
+per Docker host. Use `3.7.0-arm64` on ARM64 hosts.
+
+```bash
+docker plugin install grafana/loki-docker-driver:3.7.0 --alias loki --grant-all-permissions
+```
+
+### 2. Install dependencies
+
+```bash
+pnpm install
+```
+
+### 3. Build the project
+
+```bash
+pnpm build
+```
+
+### 4. Prepare the root environment file
+
+```bash
+cp .env.example .env
+```
+
+The root `.env` is used by Docker Compose and is not committed.
+
 Per-app env files (`apps/*/.env`, `apps/*/.env.development`) are committed
 with safe defaults and are loaded automatically. Override locally with
 `apps/*/.env.local` or `apps/*/.env.development.local` (both gitignored).
 
+If the default Postgres host port is already in use, change `POSTGRES_PORT` in
+the root `.env` and set `DATABASE_URL` in `apps/backend/.env.development.local`
+to the same host port.
+
+### 5. Run with local Node processes
+
+Use Docker Compose for the supporting services, then run the backend and web app
+through pnpm.
+
+```bash
+pnpm compose up -d postgres redis
+pnpm dev
+```
+
+### 6. Run fully through Docker Compose
+
+Use this when you want the app and supporting services to run in containers.
+
+```bash
+pnpm compose up -d --build
+```
+
 ## Single-VPS production
 
 See [VPS production deployment](docs/runbooks/vps-production-deployment.md)