# Organizations and teams quick start

## 5-Minute Overview

CloudForge now supports organizations and teams, just like GitHub. Here's the quick version:

### For Users
1. Create an org: `POST /api/orgs` with slug, display_name
2. Invite members to your org
3. Create teams to organize repo access
4. Add members to teams
5. Add repos to teams with permission levels (read/write/admin)

### For Admins
1. Commit the migration and component changes together.
2. Confirm the dependency-aware impact with `node scripts/forge-release-impact.mjs`.
3. Release through `node scripts/forge-release-affected.mjs --sha <exact-sha>`;
   the coordinator owns migration order, component activation, and evidence.
4. Verify the endpoints and release receipts, then monitor the owning components.

## Common Tasks

### Create an Organization
```bash
curl -X POST https://forge.smol.ai/api/orgs \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-corp",
    "display_name": "ACME Corporation",
    "description": "ACME's GitHub clone"
  }'
```

### Add a Member to Org
```bash
curl -X POST https://forge.smol.ai/api/orgs/acme-corp/members \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "username": "alice",
    "role": "member"
  }'
```

### Create a Team
```bash
curl -X POST https://forge.smol.ai/api/orgs/acme-corp/teams \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "backend",
    "display_name": "Backend Engineers",
    "permission": "write"
  }'
```

### Add Member to Team
```bash
curl -X POST https://forge.smol.ai/api/orgs/acme-corp/teams/backend/members \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{"username": "alice"}'
```

### Create Org Repo
```bash
curl -X POST https://forge.smol.ai/api/orgs/acme-corp/repos \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "api-server",
    "description": "Our API",
    "visibility": "private"
  }'
```

`visibility` is required and accepts `public`, `unlisted`, or `private`.

### Add Repo to Team
```bash
curl -X POST https://forge.smol.ai/api/orgs/acme-corp/teams/backend/repos \
  -H "Authorization: Bearer $JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "repo_id": "abc123...",
    "permission": "write"
  }'
```

### Get Team Details (with members & repos)
```bash
curl https://forge.smol.ai/api/orgs/acme-corp/teams/backend
```

### List Org Repos (filtered by access)
```bash
curl https://forge.smol.ai/api/orgs/acme-corp/repos
```

## Permission Levels

When adding repos to teams, choose one:
- **read**: Clone/view only
- **write**: Clone, push, create issues (typical dev)
- **admin**: Modify settings, delete repo (typically leads)

## Roles

Organization member roles:
- **owner**: Full control (created org automatically)
- **admin**: Can manage teams and repos
- **member**: Can access repos via team membership (no org management)

## Default Team

Every org gets a `Members` team automatically:
- Slug: `members`
- Permission: `read`
- Purpose: All org members can see repos
- Cannot delete

## Important Notes

### Personal Repos Still Work
- Create a repo as before: `POST /api/repos`
- You're the owner, no org needed
- Repos are at your username: `/@username/repo-name`

### Org Repos Are Different
- Created via `POST /api/orgs/:org/repos`
- Access via teams, not collaborators
- Located at `/:org/repo-name`
- Only org members can access

### Access Control
- **Personal repo**: Only you can see/edit (unless you add collaborators)
- **Private org repo**: Only org members with team access
- **Public org repo**: Anyone can view, only team members can edit

### Cloning Org Repos
```bash
# With HTTPS
git clone https://forge.smol.ai/acme-corp/api-server.git

# With SSH (if configured)
# SSH is not currently supported; use the HTTPS Smart HTTP URL above.
```

## Troubleshooting

### "User is not an organization member"
When adding someone to a team, they must first be an org member. Add to org first.

### "Cannot delete the default Members team"
The Members team is required. You cannot delete it.

### "Cannot remove the last owner"
Every org needs at least one owner. Promote someone to owner first.

### Team member doesn't see repo
1. Check user is in the org
2. Check user is in the team
3. Check team has access to the repo
4. Check team's permission level

## Next Steps

- Read the [organizations and teams design](../engineering/organizations-design.md) for full API documentation.
- Read [production deployment](../operations/production-deployment.md) for deployment details.
- See the [historical implementation summary](../history/organizations-implementation.md) for the original architecture overview.