AGENTS.md@ent git:20260709.e232662A

Immutable. This exact content is served forever at /api/v1/blob/d771aaefc752db97.

# ent/ — AGENTS.md

Ent (`entgo.io/ent`) schemas split into four **tenant scopes**. Almost every file here is generated. The hand-editable surface is small — respect it.

## The four scopes
- `ent/platform/` — global identity: users, orgs, tenants, platform-level config, envelope master keys.
- `ent/org/`      — per-org data (database-per-org): sandbox templates, org-scoped credentials, memory shards, audit logs.
- `ent/team/`     — per-team data (schema-per-team within an org DB): team resources, flows, apps, memory, MCP configs, skills.
- `ent/personal/` — per-user private workspace: personal sessions, credentials, memory, apps.

Cascading defaults flow **downward** (`platform → org → team → personal`); ownership publications flow **upward** only via explicit user actions.

## Editable vs. generated
- **Editable**: `ent/<scope>/schema/*.go` — schema definitions (Fields, Edges, Indexes, Annotations, Mixins).
- **Editable**: `ent/<scope>/generate.go` — the `go:generate` directive.
- **NOT editable** (regenerate instead): everything else under `ent/<scope>/` — `client.go`, `mutation.go`, `*_query.go`, `*_create.go`, `*_update.go`, `*_delete.go`, `runtime.go`, hooks, etc.

If you find yourself opening `mutation.go` to make a code change, stop — you're editing generated code. Update the schema or a hook.

## Regeneration flow
```bash
# From repo root
go generate ./ent/platform/...
go generate ./ent/org/...
go generate ./ent/team/...
go generate ./ent/personal/...
```
Or the umbrella target if present:
```bash
make ent-generate
```

After regenerating:
1. Run `go build ./...`.
2. If you added or renamed fields, generate a migration: `make migrate-diff` (this diffs the ent schema against the Atlas baseline and writes new `*.sql` files under `schema/` and `pkg/store/*/migrations/`).
3. Commit both the schema change **and** the migration in the same commit; the pre-commit hook will refuse otherwise.

## Choosing the right scope
- If it needs cross-org visibility → `platform`.
- If it is per-org configuration or per-org bulk data → `org`.
- If it is a team-shared resource (flow, app, memory, skill, MCP) → `team`.
- If it is private to a single user → `personal`.

When in doubt, ask: "Would exposing this to another team/org be a data leak?" If yes, do not put it in `platform` or `org`.

## References
- `pkg/store/entstore/AGENTS.md` — the router that picks the right ent client at runtime.
- `docs/architecture/multi-tenant-platform.md` — invariants and enforcement points.