diff --git a/AGENTS.md b/AGENTS.md index 6e9f50d..acef0a3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,13 +4,35 @@ 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. +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 @@ -18,13 +40,19 @@ Do not run repository tests, builds, linters, type checks, E2E tests, security s The Gitea server and its CI workflows are the authoritative validation environment. -After making changes: +After making code changes: -1. Commit/push the changes through the Gitea workflow available via MCP. -2. Let the Gitea Actions workflows execute the configured checks. -3. Inspect the workflow results through the Gitea MCP. -4. 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. -5. Continue until the relevant Gitea CI checks pass or a failure requires information or infrastructure outside the repository. +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. @@ -39,14 +67,22 @@ Do not run commands such as: 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. +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. Read the relevant guide in `node_modules/next/dist/docs/` before changing framework code and heed deprecation notices. +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"`. @@ -56,34 +92,58 @@ Do not rely solely on remembered behavior from earlier Next.js versions. ## 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. +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, validation must be performed by the Gitea server as described above. +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 variants live under `public/images/`. -* Use `npm run content:new` for new TSX content modules when working in an environment where repository commands have explicitly been permitted. +* 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, or environment-specific configuration. +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, 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. +* 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.