javaBin · Alexanderamiri · Mar 10, 2026 · Mar 10, 2026
diff --git a/CLAUDE.md b/CLAUDE.md
@@ -0,0 +1,24 @@
+# CLAUDE.md — Javabin Docs
+
+Developer-facing documentation for the Javabin platform and JavaZone systems.
+This is a standalone docs repo — no build system, just Markdown files.
+
+## Files
+
+| File | What |
+|------|------|
+| `README.md` | Index of all javaBin systems (platform, JavaZone apps, java.no) |
+| `platform-overview.md` | Platform architecture, components, how apps get CI/CD |
+| `getting-started.md` | How to register a team, add repos, get automated CI/CD |
+| `auth.md` | Identity model: Identity Center, GitHub OIDC, Cognito pools |
+
+## Key Facts
+
+- Teams are the registration unit. Register via `teams/{name}.yaml` in `javaBin/registry`.
+- There is no separate app registration. Apps just need `app.yaml` at repo root and membership in a GitHub team.
+- Platform Terraform and reusable workflows live in `javaBin/platform`.
+
+## Related
+
+- [javaBin/platform](https://github.com/javaBin/platform) — infrastructure code
+- [javaBin/registry](https://github.com/javaBin/registry) — team registration
diff --git a/README.md b/README.md
@@ -5,10 +5,10 @@
 Shared AWS infrastructure for CI/CD, compute, and monitoring. See:
 
 - [Platform Overview](platform-overview.md) — architecture, components, how it works
-- [Getting Started](getting-started.md) — how to register an app and get automated CI/CD
+- [Getting Started](getting-started.md) — how to register a team and get automated CI/CD
 - [Authentication](auth.md) — identity model (OIDC, Identity Center, Cognito)
 - [Platform repo](https://github.com/javaBin/platform) — Terraform code and reusable modules
-- [Registry](https://github.com/javaBin/registry) — app and team registration
+- [Registry](https://github.com/javaBin/registry) — team registration and hero membership
 
 ## JavaZone
 

diff --git a/auth.md b/auth.md
@@ -2,16 +2,21 @@
 
 How identity and access control work in the Javabin platform.
 
+## Google Workspace Accounts
+
+All javaBin heroes get a `@java.no` Google Workspace account, auto-created when their entry is added to `groups/heros.yaml` in the registry. An invite is sent to their personal email. Heroes can also request an email alias (e.g., `alex@java.no`) via PR.
+
 ## Console Access: IAM Identity Center + Google Workspace
 
 IAM Identity Center provides AWS console and CLI access for javaBin volunteers, federated via Google Workspace SAML.
 
 - Google Workspace groups map to IAM Identity Center permission sets
 - Volunteers sign in with their `@java.no` Google account
 - Access is scoped by 3 permission sets: admin, developer, read-only
-- 2FA is enforced on all Identity Center users
+- Group membership is managed in `groups/heros.yaml` — the `memberships` field determines which groups a hero belongs to
+- Groups with `identity_center: true` in `groups/groups.yaml` are synced to Identity Center
 
-**Status**: Live. IAM Identity Center deployed with SAML federation to Google Workspace.
+**Status**: Deployed. Terraform applied from `terraform/org/`.
 
 ## CI/CD Access: GitHub OIDC
 
@@ -39,7 +44,7 @@ auth: internal    # or: external, both, none
 
 The platform creates a Cognito app client and passes the client ID/secret via environment variables.
 
-**Status**: Deployed. Both Cognito pools are managed in Terraform (`terraform/platform/identity/`). Apps that need auth can use Cognito or continue using Auth0 at `login.javazone.no`.
+**Status**: Deployed. Internal pool connected to Google Workspace as IdP. External pool deployed but not yet connected to Google. Apps currently use Auth0 at `login.javazone.no` (migration pending).
 
 ## Developer CLI Authentication
 
@@ -54,7 +59,7 @@ The `javabin` CLI (4 commands: init, register, status, whoami) authenticates via
 |---------|-----------|--------|
 | AWS Console | Identity Center + Google SAML + 2FA | Deployed |
 | CI/CD | GitHub OIDC | Deployed |
-| App users (internal) | Cognito internal pool | Deployed |
-| App users (external) | Cognito external pool | Deployed |
+| App users (internal) | Cognito internal pool + Google IdP | Deployed |
+| App users (external) | Cognito external pool | Deployed (Google IdP not yet connected) |
 | Legacy app auth | Auth0 (`login.javazone.no`) | Active |
 | Developer CLI | gh CLI + AWS credential chain | Implemented |
diff --git a/getting-started.md b/getting-started.md
@@ -1,6 +1,6 @@
 # Getting Started with the Javabin Platform
 
-How to register a team, create a service, and get automated CI/CD.
+How to register a team, add repos, and get automated CI/CD.
 
 ## Prerequisites
 
@@ -16,12 +16,12 @@ brew install javaBin/tap/javabin
 javabin init
 
 # Register your team (opens a PR against javaBin/registry)
-javabin register
+javabin register-team
 ```
 
 The `init` command scaffolds a new service repo from [javaBin/app-template](https://github.com/javaBin/app-template), including `app.yaml` and `Dockerfile`.
 
-The `register` command prompts for team details and creates a registration PR automatically.
+The `register-team` command prompts for team details and creates a team registration PR automatically.
 
 Other commands: `javabin status` (check platform status), `javabin whoami` (show current identity).
 
@@ -37,6 +37,7 @@ description: What your team works on
 members:
   - google: firstname.lastname
     github: github-username
+budget_nok: 5000  # Optional, defaults to 500 NOK/mo
 ```
 
 - `google_group` is derived automatically as `team-{name}@java.no`
@@ -47,20 +48,41 @@ members:
 
 A platform owner (`@javaBin/platform-owners`) reviews and merges it. This triggers team provisioning (Google Group, GitHub team, Cognito group, IAM).
 
-### Step 3: Add app.yaml to your repo
+### Step 3: Add repos to your team
+
+After your team is provisioned, add your repos to the GitHub team:
+
+**Via GitHub UI:**
+1. Go to [github.com/orgs/javaBin/teams](https://github.com/orgs/javaBin/teams)
+2. Select your team
+3. Go to the **Repositories** tab
+4. Click **Add repository** and select your repo
+
+**Via CLI:**
+```bash
+gh api orgs/javaBin/teams/TEAM/repos -f owner=javaBin -f repo=REPO -f permission=push
+```
+
+Replace `TEAM` with your team name and `REPO` with the repository name.
+
+### Step 4: Add app.yaml to your repo
 
 Add an `app.yaml` to your repo root to configure compute, routing, and resources. See the [app.yaml reference](https://github.com/javaBin/platform/blob/main/docs/app-yaml-reference.md).
 
+For CI/CD to work on a repo, the repo needs:
+- To be under a registered team (GitHub team membership)
+- An `app.yaml` at the repo root
+
 ## What Happens After Registration
 
 1. The platform provisions:
    - A **Google Group** (`team-{name}@java.no`)
    - A **GitHub team** with all members as maintainers
-   - An **IAM role** your CI pipeline assumes via GitHub OIDC
-   - An **ECR repository** for your Docker images
+   - A **Cognito group** for identity management
+   - **IAM resources** your CI pipeline assumes via GitHub OIDC
    - A **budget alert** for cost monitoring
 
-2. Push to `main`. The platform CI pipeline automatically:
+2. After you add a repo to your team and include an `app.yaml`, every push to `main` triggers the full pipeline:
    - Builds your code (Java/Maven or TypeScript/pnpm)
    - Builds and pushes a Docker image
    - Plans and applies Terraform infrastructure
@@ -74,12 +96,44 @@ Use the CLI or start from [javaBin/app-template](https://github.com/javaBin/app-
 1. Run `javabin init` (recommended), or click **"Use this template"** on GitHub
 2. Customize `app.yaml` and `Dockerfile`
 3. Register your team in the registry (see above)
-4. Push — CI takes over
+4. Add the repo to your GitHub team (see Step 3 above)
+5. Push — CI takes over
 
 ## Multi-Environment Support
 
 `app.yaml` supports an `environments:` block for dev/prod separation. If omitted, a single production environment is created. See the [app.yaml reference](https://github.com/javaBin/platform/blob/main/docs/app-yaml-reference.md#environments) for details.
 
+## Hero Membership
+
+The registry is also the source of truth for all javaBin hero volunteers (~70 people/year). This is separate from team registration — teams are for app developers who need AWS access, heroes are all active volunteers.
+
+### How hero membership works
+
+1. Board sends yearly Google Forms for hero applications
+2. Responses go to a Google Sheet, board marks approved heroes
+3. Board triggers a sync (Apps Script button or GitHub Actions workflow)
+4. Sync creates a PR on the registry updating `groups/heros.yaml`
+5. PR reviewed and merged — triggers provisioning:
+   - Google Workspace accounts auto-created for new heroes
+   - All heroes added to `helter@java.no`
+   - Heroes added to their membership groups (styret, javazone, pkom, kodesmia, region, etc.)
+
+### Registry structure
+
+```
+registry/
+  teams/              # App developer teams (AWS IAM, budgets, GitHub teams)
+  groups/
+    groups.yaml       # All group definitions (Google email, Cognito/IC flags)
+    heros.yaml        # All hero members (name, email, alias, memberships)
+```
+
+- `groups.yaml` defines what groups exist and their properties
+- `heros.yaml` defines who the heroes are and which groups they belong to
+- Being in `heros.yaml` = member of `helter` (implicitly)
+- The `memberships` field controls additional group assignments
+- Heroes can PR an email alias (e.g., `alex@java.no`)
+
 ## No Per-Repo Workflow Files
 
 The platform provides reusable workflows. Your repo does not need its own `.github/workflows/` directory for standard CI/CD. The entrypoint workflow (`javabin.yml`) detects your repo contents and runs the appropriate build and deploy steps.
diff --git a/platform-overview.md b/platform-overview.md
@@ -37,7 +37,7 @@ Seven Terraform sub-modules manage shared resources:
 | **compute** | ECS Fargate cluster (`javabin-platform`), ECR base config |
 | **monitoring** | SNS topics, EventBridge rules, AWS Config, GuardDuty, Security Hub |
 | **lambdas** | 6 Lambda functions for alerts, cost reporting, compliance, cleanup |
-| **identity** | IAM Identity Center (SAML + Google Workspace), 3 permission sets, Cognito user pools, 2FA enforced |
+| **identity** | Cognito user pools (internal + external). Internal pool connected to Google IdP. Identity Center is in `terraform/org/` (deployed) |
 
 ### Reusable Modules (`terraform/modules/`)
 
@@ -64,18 +64,33 @@ App repos call `javaBin/platform/.github/workflows/javabin.yml` as their CI entr
 | `daily-cost-check` | Daily schedule (08:00 UTC) | Spike detection, silent if no anomalies |
 | `compliance-reporter` | EventBridge (resource create/run) | Reports untagged resources to Slack |
 | `override-cleanup` | Hourly schedule | Deletes stale SSM override tokens |
-| `team-provisioner` | Registry merge (repository_dispatch) | Syncs teams across Google, GitHub, Cognito, IAM |
+| `team-provisioner` | Registry merge | Syncs Google Groups, GitHub teams, AWS Budgets, Cognito, Identity Center. Also handles hero provisioning (Workspace accounts, aliases, group membership) |
 
 ## How Apps Get CI/CD
 
 1. Developer creates a repo from `javaBin/app-template` (or runs `javabin init`)
 2. Registers their team in `javaBin/registry` (PR with `teams/{name}.yaml`)
 3. Platform owner merges — team-provisioner syncs Google Group, GitHub team, Cognito, IAM
-4. Developer adds `app.yaml` to repo root with service config
-5. Every push to `main` triggers the full pipeline: build, plan, review, deploy
+4. Developer adds the repo to their GitHub team (via GitHub UI or `gh api orgs/javaBin/teams/TEAM/repos`)
+5. Developer adds `app.yaml` to repo root with service config
+6. Every push to `main` triggers the full pipeline: build, plan, review, deploy
+
+The registry is the IAM gate: unregistered teams have no IAM role, so CI can't deploy. For CI/CD to work, a repo must be under a registered team and have an `app.yaml` at root.
 
 No per-repo workflow files needed. The platform handles everything.
 
+## Registry: Source of Truth for Memberships
+
+The [registry](https://github.com/javaBin/registry) serves two purposes:
+
+**Teams** (`teams/`) — app developer teams that need AWS access. Each team gets an IAM role, budget, GitHub team, and Google Group.
+
+**Groups & Heroes** (`groups/`) — organizational membership for all javaBin volunteers:
+- `groups.yaml` defines all groups (helter, styret, javazone, pkom, kodesmia, region, drift, admin, developers, etc.) with their properties (Google Workspace email, Cognito/Identity Center flags)
+- `heros.yaml` defines all hero members with their group assignments
+
+Changes to `groups/` trigger provisioning: Google Workspace account creation, group membership sync, email aliases, and Cognito/Identity Center sync where configured. Heroes are synced from a yearly Google Sheets application process.
+
 ## AWS Account
 
 - **Account**: (private — see platform repo)