SpaceWanderer/AGENTS.md

SpaceWanderer — Workflow Rules

Change process (mandatory)

1. Small, incremental changes — work is done one change at a time, in smaller parts; each part must be tested thoroughly with unit and e2e tests covering it before moving on. Connected issues/tasks that reference the same part of code MAY be done together on one branch/PR with a single version bump (e.g. two UI tweaks to the same panel).
2. Feature branch + PR — every change lands on a feature branch off master (no direct pushes to master). The branch carries the commits below; open a pull request to master.
3. Changelog entry — every such change is listed in CHANGELOG.md with date, time and version (format: ## v<version> — YYYY-MM-DD HH:MM, then bullet points of what changed).
4. Version bump — the version is updated in package.json.
5. CI must pass — enforced by branch protection on master (required status check CI / build + unit + e2e (pull request)): the PR cannot be merged until CI is green. Merge via auto-merge (POST /repos/{owner}/{repo}/pulls/{n}/merge with body {"do":"merge","merge_style":"merge","merge_when_checks_succeed":true}) so it merges automatically once CI passes. CI never deploys to production; its e2e runs against an isolated stack inside dind.
6. Tag + manual deploy after merge — once merged, tag the version on master. Production (https://space-wanderer.dev.kkhost.pl) is updated manually afterwards: docker compose up -d --build on the host. Not deployed yet — the first deploy happens after the initial scaffold.

E2E tests (mandatory)

1. CI-only — e2e runs ONLY in CI, against an isolated docker stack inside dind built from docker-compose.ci.yml (project name space-wanderer-ci, app container on a static IP; see .gitea/workflows/ci.yml). There are NO local e2e runs at all: locally you verify with npx tsc --noEmit + npx vitest run + npx playwright test --list (typecheck, unit suite, specs compile and list), and the full e2e suite is verified by CI on every PR. CI never deploys to or modifies production.
2. CI env vars (playwright.config.ts, all optional) — E2E_BASE_URL (app under test; CI sets it to the in-network app host, so the config's default of the live Traefik instance at https://space-wanderer.dev.kkhost.pl is never used), E2E_DEPLOY_CMD (runs as Playwright webServer: deploys the stack and waits for readiness before tests start; CI uses build + up -d + logs -f), PW_REMOTE_BROWSER=0 (CI runs local chromium because the shared remote browser server at 192.168.1.4 cannot reach a stack inside dind — when unset, the config defaults to that remote server and to the live instance as baseURL), and E2E_COMPOSE_ARGS, read by e2e/state.spec.ts for its mid-run docker compose restart (CI points it at -f docker-compose.ci.yml -p space-wanderer-ci).

API

1. Live base URL — https://space-wanderer.dev.kkhost.pl (the docker-compose build behind Traefik; not deployed yet).
2. Machine-readable spec — OpenAPI 3.x at /api/openapi; current app version at /api/version.
3. Spec lives in code — generated from lib/openapi.ts, served by app/api/openapi/route.ts; must be updated whenever an endpoint changes.

Other

1. For longer terminal tasks you should use pty_* tools.

This is NOT the Next.js you know

This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory; in monorepos the next package may not be visible from the repo root) before writing any code. Heed deprecation notices.

This block is written and re-added by next dev — verify at node_modules/next/dist/server/lib/generate-agent-files.js. Removing it from a diff only re-creates the uncommitted change; committing it with your work keeps the tree clean.