Files
Goldebek/AGENTS.md
T
Per Hoener 572d515d08
Deploy / validate-dispatch (push) Successful in 1s
Deploy / changes (push) Successful in 3s
Deploy / scheduled-rebuild-dev (push) Skipped
Deploy / scheduled-rebuild-master (push) Skipped
Deploy / rollback-dev (push) Skipped
Deploy / rollback-master (push) Skipped
Deploy / secret-scan (push) Successful in 4s
Deploy / app-quality (push) Successful in 1m3s
Deploy / security-deps (push) Successful in 4s
Deploy / context (push) Successful in 0s
Deploy / app-image (push) Successful in 59s
Deploy / deploy-master (push) Skipped
Deploy / deploy-dev (push) Successful in 19s
refine: clarify Gitea MCP usage and repository interaction guidelines
2026-09-20 12:30:36 +02:00

6.3 KiB

Repository Notes

Repository Access and Gitea MCP

A Gitea MCP server is available for this repository.

The Gitea MCP is intended for Gitea-side operations and inspection. It must not be used to edit or update application source code.

Use the Gitea MCP for tasks such as:

  • Inspecting repository state, branches, commits, pull requests, and issues.
  • Inspecting Gitea Actions workflow runs.
  • Reading workflow status and CI results.
  • Inspecting failed jobs and their logs.
  • Working with other Gitea-specific metadata when useful.

Do not use the Gitea MCP to modify, create, or delete application source files.

Code changes must be made directly in the existing local working copy using the normal filesystem and development tools available to the agent.

Use normal Git commands for:

  • Reviewing local changes.
  • Staging changes.
  • Creating commits.
  • Pushing commits to the Gitea repository.

Do not create another clone or separate working copy if the repository is already available locally.

Before making changes:

  1. Inspect the relevant local source files.
  2. Use the Gitea MCP when additional server-side repository context is useful.
  3. Keep changes focused on the requested task.
  4. Avoid unrelated refactoring or formatting changes.

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 code changes:

  1. Review the local diff.
  2. Commit the changes using normal Git.
  3. Push the commit to the Gitea repository using normal Git.
  4. Let the Gitea Actions workflows execute the configured checks.
  5. Inspect the workflow results through the Gitea MCP.
  6. If a workflow fails, inspect the failing job and its logs through the Gitea MCP.
  7. Determine the cause of the failure.
  8. Make the required code changes locally.
  9. Commit and push the fix using normal Git.
  10. Inspect the newly triggered Gitea workflow again.
  11. Continue this cycle until the relevant CI checks pass or the failure requires information, credentials, infrastructure, or another dependency outside the repository.

Do not replace Gitea CI validation with local tests.

Do not run commands such as:

  • npm ci
  • npm run lint
  • npm run typecheck
  • npm run test
  • npm run build
  • npm run test:e2e

locally unless explicitly instructed by the user.

Do not use the Gitea MCP as a substitute for normal source-code editing or Git operations.

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.

Before changing framework-related code, read the relevant guide in node_modules/next/dist/docs/ and heed deprecation notices.

Do not rely solely on remembered behavior from earlier Next.js versions.

If the required documentation is already available locally, read it directly. Do not run npm ci merely to perform validation.

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 in src/trip-reports/index.ts.

Commands

The following commands document the repository's CI and development behavior.

They do not grant permission to execute validation commands 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 run npm run dev.

For agent-driven repository changes, linting, type checking, tests, builds, E2E tests, and security validation must be performed by the Gitea server as described above.

Configuration and Assets

  • .env.example documents safe example settings.
  • CALENDAR_URL is required at runtime but not during next build.
  • APP_URL controls canonical URLs, sitemap, robots, host checks, and the default CORS origin.
  • Original image sources live in .media-source/.
  • Generated image variants live under public/images/.
  • npm run content:new is available for creating new TSX content modules, but do not execute it unless local command execution for that task has explicitly been requested.

Do not commit:

  • Secrets.
  • Production credentials.
  • Private API keys.
  • Tokens.
  • Environment-specific sensitive 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.
  • Deployment uses Docker Compose.
  • Deployment verifies application, API, and health routes.
  • Deployment supports rollback.

Treat Gitea Actions as the source of truth for repository validation.

Use the Gitea MCP to inspect workflow runs, job results, and failure logs.

When CI fails:

  1. Identify the specific failing check.
  2. Read the relevant server-side logs through the Gitea MCP.
  3. Fix the underlying problem in the local source code.
  4. Commit and push the change using normal Git.
  5. Re-check the resulting Gitea Actions run.

Do not weaken, skip, remove, mock out, 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.