5.0 KiB
Repository Notes
Repository Access and Gitea MCP
A Gitea MCP server is available for this repository.
- Use the Gitea MCP for all repository interactions whenever the required operation is supported.
- Use the Gitea MCP to inspect files, branches, commits, pull requests, issues, workflow runs, and repository state.
- Make repository changes through the Gitea server rather than creating a separate local clone or working copy.
- Do not clone the repository locally unless explicitly instructed to do so.
- Do not modify a separate local checkout and push it afterwards when the same operation can be performed through the Gitea MCP.
- Before making changes, inspect the current repository state and the files relevant to the task through the Gitea MCP.
- Keep changes focused on the requested task and avoid unrelated refactoring.
Testing and Validation
Do not run repository tests, builds, linters, type checks, E2E tests, security scanners, or other validation commands locally.
The Gitea server and its CI workflows are the authoritative validation environment.
After making changes:
- Commit/push the changes through the Gitea workflow available via MCP.
- Let the Gitea Actions workflows execute the configured checks.
- Inspect the workflow results through the Gitea MCP.
- If a workflow fails, inspect the failing job and its logs, determine the cause, make the required repository changes, and let Gitea run the checks again.
- Continue until the relevant Gitea CI checks pass or a failure requires information or infrastructure outside the repository.
Do not replace Gitea CI validation with local tests.
Do not run commands such as:
npm cinpm run lintnpm run typechecknpm run testnpm run buildnpm run test:e2e
locally unless explicitly instructed by the user.
When reporting completion, include the relevant Gitea workflow/check status. Do not claim that a change is validated unless the corresponding server-side checks have completed successfully.
Next.js
This repository uses Next.js 16 with breaking changes relative to earlier versions. Read the relevant guide in node_modules/next/dist/docs/ before changing framework code and heed deprecation notices.
Do not rely solely on remembered behavior from earlier Next.js versions.
Shape
- The Next.js application lives at the repository root and uses the App Router, React 19, TypeScript, and
output: "standalone". - Pages,
GET /api/events, and health routes run in one Node.js process. - Calendar data is fetched at runtime from an external ICS source.
- TSX content modules live under
src/trip-reports/and are registered insrc/trip-reports/index.ts.
Commands
The following commands document the repository's CI behavior. They are primarily intended to describe what Gitea CI executes, not commands that the agent should run locally.
- Install dependencies exactly as CI does:
npm ci. - Checks:
npm run lint,npm run typecheck,npm run test,npm run build. - E2E smoke test:
npm run test:e2e. - Dev server: set
CALENDAR_URL, then runnpm run dev.
For agent-driven repository changes, validation must be performed by the Gitea server as described above.
Configuration and Assets
.env.exampledocuments safe example settings.CALENDAR_URLis required at runtime but not duringnext build.APP_URLcontrols canonical URLs, sitemap, robots, host checks, and the default CORS origin.- Original image sources live in
.media-source/; generated variants live underpublic/images/. - Use
npm run content:newfor new TSX content modules when working in an environment where repository commands have explicitly been permitted.
Do not commit secrets, production credentials, private API keys, or environment-specific configuration.
CI and Deployment
- Workflows live in
.gitea/workflows/. - CI runs lint, Vitest, typecheck, build, E2E, and security scans.
- Deploy builds and scans a configurable container image, deploys with Docker Compose, verifies app/API/health routes, and supports rollback.
- Treat Gitea Actions as the source of truth for whether a change passes repository validation.
- Inspect failed workflow jobs through Gitea before attempting a fix.
- Do not weaken, skip, remove, or bypass CI checks merely to make a workflow pass unless explicitly requested.
- Do not modify deployment, CI, security scanning, or production configuration unless it is part of the requested task.
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.