Run the stack

Standalone mode, from the repository root
(docker-compose.yml header comment; steps also in CONTRIBUTING.md, "Profile: developer"):

cp .env.example .env
cp api/.env.example api/.env && php artisan key:generate
./scripts/setup-local-ssl.sh
docker compose up -d
docker compose -f docker-compose.api.yml up -d

A shared-proxy mode also exists for a machine already running another reverse proxy
— see the header comment in docker-compose.yml.

Service	URL	Source
Frontend (Vue/Quasar, via Traefik)	https://ozfile.test	`docker-compose.yml`
API (Laravel, via nginx)	http://localhost:8083	`docker-compose.api.yml` (`OZ_API_PORT`)
Mailpit — outgoing mail in dev	http://localhost:8027	`docker-compose.api.yml` (`OZ_MAILPIT_PORT`)
Traefik dashboard (standalone mode)	http://localhost:8890	`docker-compose.yml`

This app's own routes

Route	Serves	Defined in
/	This page	`api/routes/web.php`
/up	Framework health check	`api/bootstrap/app.php` (`health: '/up'`)

No product API routes yet — api/routes/api.php does not exist on disk. api/AGENTS.md: "product API implementation has not started."

Frontend commands

From webapp/ — webapp/package.json scripts:

`yarn dev`	Vite dev server, port `VITE_PORT` (5173 unless set — `webapp/vite.config.ts:17`)
`yarn dev:docker`	What the `frontend` container runs, bound for Traefik/HMR
`yarn build`	Type-check, then production build
`yarn type-check`	`vue-tsc --build`
`yarn lint`	oxlint then eslint, both with `--fix` — inspect the diff
`yarn format`	prettier, writes source

Run yarn type-check, yarn build and yarn lint before handing off frontend work — webapp/AGENTS.md, "Run and check".

API commands

From api/, inside the team's approved Docker/Composer runtime — never a host-side PHP or Composer (api/AGENTS.md):

composer install
composer validate --strict
composer check-platform-reqs
composer test
vendor/bin/pint --test
php artisan route:list --except-vendor

api/README.md, "Setup and checks".

The `oz` CLI

Plain ESM, Node ≥ 22, no dependencies or build step — tools/oz/README.md:

tools/oz/bin/oz status        # doctor + Atlas + index freshness, degrades gracefully
tools/oz/bin/oz check         # ingest check, then Atlas check, then page tests
tools/oz/bin/oz test [api|webapp|pages|tooling|all]
tools/oz/bin/oz ingest check
tools/oz/bin/oz open <page>   # schema, board, start, changes, study, pitch, atlas…

Read first

README.md — project overview and entrypoints
CONTRIBUTING.md — ownership, delivery workflow, Git rules, setup profiles
AGENTS.md — shared agent instructions
api/AGENTS.md, api/README.md — backend conventions and checks
webapp/AGENTS.md — frontend conventions, run and check
docs/AGENTS.md — sources, citation and domain rules
docs/knowledge/handbook/00-topic-finder.md — handbook index

Conventions

Direct pushes to main are currently allowed while the project is being established — CONTRIBUTING.md, "Shared work and Git".
No session bumps webapp/package.json's version or edits an in-repo changelog; releases are GitHub's — CONTRIBUTING.md, "Application versioning".
No Co-Authored-By or Claude-Session commit trailers — CONTRIBUTING.md, "Shared work and Git".
Each clone needs its own bash .githooks/install.sh --install — a per-clone local Git setting — README.md.