From 04ac85107cc17f08a0176fd7b7c4ea45e9534c20 Mon Sep 17 00:00:00 2001 From: Auto Commit Date: Mon, 8 Sep 2025 14:13:08 +0200 Subject: [PATCH] Clean AGENTS.md encoding and update repo/tools sections --- AGENTS.md | 86 +++++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 84 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index fbe2ba9..458c77e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,6 +1,6 @@ # AGENTS.md — Agent Guidance for Event Photo Platform -This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.4, Filament 4, React/Vite PWA). This document defines how AI agents should operate in this repo: roles, permissions, safety rules, and standard workflows. It is the single source of truth for agent behavior. Per-agent details live in docs/agents/. +This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.3, Filament 4, React/Vite PWA). This document defines how AI agents should operate in this repo: roles, permissions, safety rules, and standard workflows. It is the single source of truth for agent behavior. Per-agent details live in docs/agents/. ## Purpose & Scope - Provide clear guardrails and playbooks so agents can assist safely with code, docs, DevOps and project hygiene. @@ -26,11 +26,15 @@ This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.4, ## Tools & Permissions - Languages/Frameworks: PHP 8.3 (Laravel 12), JS/TS (React/Vite/Tailwind), Filament 4. - Dev Commands: composer, npm, vite, artisan, PHPUnit, Pint/ESLint, Docker/Compose (for dev). -- Git Hosting: Gogs at http://192.168.78.2:10880 (token found locally in gogs.ini, never printed or committed). +- Git Hosting: Gogs at http://nas:10880 (token found locally in gogs.ini, never printed or committed). - Issue API: Gogs REST /api/v1 for labels/issues/milestones (token auth). +- Libraries: simplesoftwareio/simple-qrcode for server-side QR generation. ## Repo Structure (high-level) - docs/prp/ — split PRP (authoritative). Start at docs/prp/README.md. +- docs/changes/ — session change logs. +- resources/js/guest/ — Guest PWA source (standalone entry, SW at public/guest-sw.js). +- resources/js/admin/ — Tenant Admin PWA source (standalone entry). - fotospiel_prp.md — legacy monolithic PRP (historical reference; do not edit). - TODO.md — prioritized backlog; mirrored into Issues by Ops Agent. @@ -47,6 +51,84 @@ This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.4, - Releases (Ops Agent): - Tag with semantic version; generate changelog from commits/PRs; ensure legal pages and migration notes are updated. +## Developer Utilities +- Artisan commands: + - media:backfill-thumbnails — generate thumbnails for existing photos. + - tenant:add-dummy — create a demo tenant and admin user (see --help for options). + - tenant:attach-demo-event — attach an existing demo event to a tenant. +- Public APIs for Guest PWA: stats/photos endpoints with ETag; likes; uploads; see docs/prp/03-api.md. + +## Constraints & Red-Lines +- Do not introduce tracking beyond what is documented (anonymous session_id only for guest PWA). +- Do not weaken auth, CSRF, CORS, or role checks. +- Do not expand data retention without updating Privacy policy. + +## Change Management +- Propose updates to this file via PR. Include: + - Motivation and scope, affected agents, roll-out plan. + - Links to updated docs in docs/agents/. + +## References +# AGENTS.md — Agent Guidance for Event Photo Platform + +This repository hosts a multi-tenant event photo platform (Laravel 12, PHP 8.3, Filament 4, React/Vite PWA). This document defines how AI agents should operate in this repo: roles, permissions, safety rules, and standard workflows. It is the single source of truth for agent behavior. Per-agent details live in docs/agents/. + +## Purpose & Scope +- Provide clear guardrails and playbooks so agents can assist safely with code, docs, DevOps and project hygiene. +- Applies to the whole repo unless a component has an explicit per-agent policy in docs/agents/. + +## Roles +- Codegen Agent — implements and edits application code, tests and documentation within scoped tasks. See docs/agents/codegen.md. +- Ops Agent — automates tasks around CI/CD, releases, issue hygiene, and repo maintenance. See docs/agents/ops.md. +- (Optional) Docs Agent — maintains documentation quality; follow Codegen Agent rules with writing focus. + +## Global Policies +- Secrets & Credentials: + - Never commit secrets. The local file gogs.ini (token=…) is ignored via .gitignore and must not be printed into logs. + - ENV values in .env are sensitive; do not commit them or echo to build logs. +- Data Protection: + - Respect GDPR. Do not introduce PII logging. Legal content (Impressum, Privacy, AGB) is managed via Legal Pages resource. +- Safety & Access: + - Prefer least privilege. Do not alter production data or infrastructure from code without explicit human approval. + - When uncertain about a destructive operation, open a PR or create an Issue with a proposal. +- Source of Truth: + - Keep this AGENTS.md authoritative. If per-agent docs diverge, update this file and link the rationale. + +## Tools & Permissions +- Languages/Frameworks: PHP 8.3 (Laravel 12), JS/TS (React/Vite/Tailwind), Filament 4. +- Dev Commands: composer, npm, vite, artisan, PHPUnit, Pint/ESLint, Docker/Compose (for dev). +- Git Hosting: Gogs at http://nas:10880 (token found locally in gogs.ini, never printed or committed). +- Issue API: Gogs REST /api/v1 for labels/issues/milestones (token auth). +- Libraries: simplesoftwareio/simple-qrcode for server-side QR generation. + +## Repo Structure (high-level) +- docs/prp/ — split PRP (authoritative). Start at docs/prp/README.md. +- docs/changes/ — session change logs. +- resources/js/guest/ — Guest PWA source (standalone entry, SW at public/guest-sw.js). +- resources/js/admin/ — Tenant Admin PWA source (standalone entry). +- fotospiel_prp.md — legacy monolithic PRP (historical reference; do not edit). +- TODO.md — prioritized backlog; mirrored into Issues by Ops Agent. + +## Standard Workflows +- Coding tasks (Codegen Agent): + 1) Understand scope; update or create a minimal plan. + 2) Edit code/docs via small, reviewable patches; keep changes focused. + 3) Add/update tests if behavior changes. + 4) Update docs when public surfaces change (PRP, docs/*). + 5) Propose follow-ups as Issues if out of scope. +- Issue hygiene (Ops Agent): + - Import TODO.md tasks as Issues with label TODO; group by Milestone (e.g., Now, Security & Compliance). + - Avoid duplicates by checking existing titles. +- Releases (Ops Agent): + - Tag with semantic version; generate changelog from commits/PRs; ensure legal pages and migration notes are updated. + +## Developer Utilities +- Artisan commands: + - media:backfill-thumbnails — generate thumbnails for existing photos. + - tenant:add-dummy — create a demo tenant and admin user (see --help for options). + - tenant:attach-demo-event — attach an existing demo event to a tenant. +- Public APIs for Guest PWA: stats/photos endpoints with ETag; likes; uploads; see docs/prp/03-api.md. + ## Constraints & Red-Lines - Do not introduce tracking beyond what is documented (anonymous session_id only for guest PWA). - Do not weaken auth, CSRF, CORS, or role checks.