From bac0a8212ad97377ee9775e38c24e294c4d2fbd4 Mon Sep 17 00:00:00 2001
From: Till JS <tills95@gmail.com>
Date: Fri, 27 Mar 2026 11:50:56 +0100
Subject: [PATCH] docs(auth): document Gilden endpoints and architecture in
 CLAUDE.md

Add guild management endpoints, credit pool endpoints, credit source
routing, and subscription limit documentation to the service CLAUDE.md.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 services/mana-core-auth/CLAUDE.md | 71 +++++++++++++++++++++++++++++++
 1 file changed, 71 insertions(+)

diff --git a/services/mana-core-auth/CLAUDE.md b/services/mana-core-auth/CLAUDE.md
index cdf4e49c4..e6cd533d0 100644
--- a/services/mana-core-auth/CLAUDE.md
+++ b/services/mana-core-auth/CLAUDE.md
@@ -89,18 +89,89 @@ services/mana-core-auth/
 │   │   ├── auth.controller.ts      # Auth endpoints
 │   │   └── dto/                    # Request DTOs
 │   ├── credits/                    # Credit system
+│   │   ├── credits.service.ts      # Personal credit operations
+│   │   ├── guild-pool.service.ts   # Guild shared Mana pool
+│   │   ├── guild.controller.ts     # /credits/guild/* endpoints
+│   │   └── dto/                    # Credit DTOs (incl. creditSource)
+│   ├── guilds/                     # Gilden (guild management)
+│   │   ├── guilds.controller.ts    # /gilden/* endpoints (RPG-branded)
+│   │   ├── guilds.service.ts       # Wraps Better Auth orgs + sub limits
+│   │   └── guilds.module.ts
 │   ├── db/
 │   │   ├── schema/                 # Drizzle schemas
+│   │   │   ├── guilds.schema.ts    # guild_pools, spending_limits, transactions
+│   │   │   └── ...
 │   │   ├── migrations/             # Generated migration files
 │   │   ├── connection.ts           # DB connection
 │   │   └── migrate.ts              # Migration script with advisory locks
 │   └── config/
 │       └── configuration.ts        # App config
+├── postgres/init/
+│   ├── 03-organization-rls.sql     # Org RLS policies
+│   └── 04-guild-rls.sql           # Guild pool RLS policies
 ├── docs/
 │   └── AUTHENTICATION_ARCHITECTURE.md  # READ THIS FIRST
 └── test/
+    └── e2e/
+        └── guild-journey.e2e-spec.ts  # Full guild E2E tests
 ```
 
+## Gilden (Guilds) - Shared Mana Pools
+
+Guilds allow users to share a Mana pool (family, friends, teams). Uses Better Auth's organization plugin under the hood.
+
+### Key Concepts
+
+- **Gilde** = Organization with a shared credit pool
+- **Gildenmeister** = Owner who manages the pool and members
+- **Mana-Pool** = Shared credit balance members spend from directly
+- **Spending Limits** = Optional per-member daily/monthly limits
+
+### Endpoints
+
+**Guild Management** (`/gilden/*`):
+
+| Method | Endpoint | Who | Description |
+|--------|----------|-----|-------------|
+| POST | `/gilden` | Auth user | Create guild + pool |
+| GET | `/gilden` | Auth user | List user's guilds |
+| GET | `/gilden/:id` | Member | Guild details + pool + members |
+| PUT | `/gilden/:id` | Owner/Admin | Update guild |
+| DELETE | `/gilden/:id` | Owner | Delete guild (cascades pool) |
+| POST | `/gilden/:id/invite` | Owner/Admin | Invite member |
+| POST | `/gilden/accept-invitation` | Invitee | Accept invitation |
+| DELETE | `/gilden/:id/members/:mid` | Owner/Admin | Remove member |
+| PUT | `/gilden/:id/members/:mid/role` | Owner/Admin | Change role |
+
+**Guild Credits** (`/credits/guild/*`):
+
+| Method | Endpoint | Who | Description |
+|--------|----------|-----|-------------|
+| GET | `/credits/guild/:id/balance` | Member | Pool balance |
+| POST | `/credits/guild/:id/fund` | Owner/Admin | Fund from personal balance |
+| POST | `/credits/guild/:id/use` | Member | Use credits from pool |
+| GET | `/credits/guild/:id/transactions` | Member | Transaction history |
+| GET | `/credits/guild/:id/members/:uid/spending` | Member/Owner | Spending summary |
+| GET | `/credits/guild/:id/members/:uid/limits` | Member/Owner | Get limits |
+| PUT | `/credits/guild/:id/members/:uid/limits` | Owner/Admin | Set limits |
+
+**Credit Source Routing**: `POST /credits/use` accepts optional `creditSource`:
+```json
+{
+  "amount": 10,
+  "appId": "chat",
+  "description": "AI chat",
+  "creditSource": { "type": "guild", "guildId": "..." }
+}
+```
+
+### Subscription Limits
+
+Guild creation and invites respect the user's subscription plan:
+- `maxOrganizations` = max guilds a user can own
+- `maxTeamMembers` = max members per guild
+- Free tier: 1 guild, 1 member (just themselves)
+
 ## Database Migrations
 
 For comprehensive migration documentation, see **[docs/DATABASE_MIGRATIONS.md](/docs/DATABASE_MIGRATIONS.md)**.