# AGENTS

This repository is designed for human + AI agent collaboration.

## Read Order

Before meaningful code changes, read:

1. `README.md`
2. `docs/AGENTIC_WORKFLOW.md`
3. `docs/ARCHITECTURE.md`
4. `docs/DEVELOPMENT_WORKFLOW.md`
5. `docs/PRODUCT.md`
6. `docs/CONVENTIONS.md`
7. Relevant file in `docs/FEATURES/`
8. Relevant file in `docs/TASKS/`

## Core Rules

- Do not invent architecture.
- Work from docs, feature specs, and task files instead of long chat history.
- Keep backend code under `backend/src/Socialize.Api`.
- The solution file is `backend/Socialize.slnx`.
- Backend feature code currently follows FastEndpoints module folders under `Modules/<Feature>`.
- Frontend feature-owned code belongs under `frontend/src/features/<feature>`.
- Frontend runtime config must flow through `frontend/src/config.js`.
- If backend contracts change, run `./scripts/update-openapi.sh` when the backend is running.
- Dev servers use HTTP and bind to `0.0.0.0` for LAN access.
- Avoid broad refactors unless the task explicitly asks for one.

## Repository Layout

- `backend/src/Socialize.Api/`: ASP.NET Core `net10.0` API using FastEndpoints, EF Core, PostgreSQL, ASP.NET Identity, and workflow modules.
- `backend/tests/Socialize.Tests/`: backend test project scaffold.
- `frontend/`: Vue 3 + Vite + Vuetify + Pinia SPA.
- `docs/FEATURES/`: product and technical feature specs.
- `docs/TASKS/`: implementation tickets for coding agents.
- `docs/PROMPTS/`: reusable agent prompt templates.
- `docs/DECISIONS/`: architecture and product decision records.
- `shared/openapi/`: backend OpenAPI schema snapshots.
- `scripts/`: root developer workflow commands.
- `deploy/caddy/`: Caddy reverse proxy config for Docker Compose.

## Local Runbook

Start infrastructure:

```bash
./scripts/start-infrastructure.sh
```

Run backend:

```bash
./scripts/dev-backend.sh
```

Run frontend:

```bash
./scripts/dev-frontend.sh
```

Update OpenAPI:

```bash
./scripts/update-openapi.sh
```

## Current Domain Modules

- `Identity`: authentication, refresh tokens, email verification, password reset, social login.
- `Workspaces`: workspace membership, workspace settings, access scoping.
- `Clients`: client records and primary contacts tied to workspaces.
- `Projects`: project pipeline and client/project relationships.
- `ContentItems`: reviewable content records tied to clients/projects.
- `Assets`: linked asset metadata and revision history.
- `Comments`: discussion threads on reviewable work.
- `Approvals`: review decisions and workflow state transitions.
- `Notifications`: activity feed and unread workflow notifications.
- `Feedback`: product feedback reports, screenshots, comments, activity, and developer review workflows.

## Task Discipline

Agents should work from task files in `docs/TASKS/`.

A good task:

- has a clear goal
- names the relevant feature spec
- has a small scope
- lists likely files
- lists validation commands

If no task exists, create one before implementing a meaningful feature.

## Validation

Backend:

```bash
dotnet build backend/Socialize.slnx
dotnet test backend/Socialize.slnx
```

Frontend:

```bash
cd frontend
npm run build
```

Contract changes:

```bash
./scripts/update-openapi.sh
```

## Sharp Edges

- Existing checked-in env and appsettings files may include legacy sensitive-looking values; do not propagate those values into new docs or templates.
- The frontend is still JavaScript, not the TypeScript starter app generated by the bootstrap script. New OpenAPI scaffolding exists, but migrating app code to generated typed API calls should happen by task.
- Feature-owned frontend route views and stores now live under `frontend/src/features/*`; keep future feature work there.