chore: add AI tooling config and conventional commits convention (JDWLABS-21)

.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(npx nx *)",
+      "Bash(pnpm *)",
+      "Bash(go build *)",
+      "Bash(go test *)",
+      "Bash(go vet *)",
+      "Bash(git diff*)",
+      "Bash(git log*)",
+      "Bash(git status*)",
+      "Bash(git add *)",
+      "Bash(git commit*)"
+    ],
+    "deny": ["Bash(git push*)", "Bash(rm -rf *)"]
+  }
+}

.github/pull_request_template.md

@@ -0,0 +1,24 @@
+## What
+
+<!-- One sentence: what changed and why -->
+
+## Type of change
+
+- [ ] `feat` — new feature or capability
+- [ ] `fix` — bug fix
+- [ ] `build` — build system or external dependency change
+- [ ] `chore` — maintenance / config / tooling
+- [ ] `ci` — CI/CD pipeline change
+- [ ] `docs` — documentation only
+- [ ] `perf` — performance improvement
+- [ ] `refactor` — restructure, no behavior change
+- [ ] `revert` — revert a previous commit
+- [ ] `style` — formatting / whitespace (no logic change)
+- [ ] `test` — test additions or updates
+
+## Checklist
+
+- [ ] PR title follows conventional commit format: `type(scope): description`
+- [ ] `npx nx affected -t build,test,lint` passes locally
+- [ ] No secrets or credentials in diff
+- [ ] CONTRIBUTING.md consulted for commit message format

.husky/commit-msg

@@ -1 +1,2 @@
+#!/usr/bin/env sh
 npx --no-install commitlint --edit "$1"

AGENTS.md

@@ -0,0 +1,37 @@
+# AGENTS.md
+
+Context for AI agents (OpenAI Codex, GitHub Copilot, and others) working in this repository.
+
+## What This Repo Is
+
+jdwlabs `apps` is an NX monorepo containing the full application stack for the jdwlabs platform:
+
+- **Auth UI** (`apps/angular/authui`) — login, registration, session management
+- **Roles UI** (`apps/angular/rolesui`) — role assignment and management
+- **Users UI** (`apps/angular/usersui`) — user listing and administration
+- **Container** (`apps/angular/container`) — shell app that composes micro-frontends via Module Federation
+- **Platform E2E** (`apps/angular/platform-e2e`) — Cypress end-to-end test suite
+- **Service Discovery** (`apps/go/servicediscovery`) — Go backend service registry
+- **Users/Role service** (`apps/springboot/usersrole`) — Spring Boot/Kotlin user-role assignment API
+- **Auth DB** (`apps/database/authdb`) — database migration management
+
+## Key Concepts
+
+- **Module Federation:** frontends are micro-frontends composed at runtime via Webpack Module Federation — each Angular app is independently deployable but the container app assembles them
+- **NX affected:** CI only builds/tests code touched by a PR — understand the dependency graph before assuming a change is isolated (`npx nx graph` to visualize)
+- **go.work:** a Go workspace at the repo root covers `apps/go/servicediscovery` and `libs/go/shared/util` — always run `go` commands from the repo root
+
+## Navigation
+
+- Angular entry points: `apps/angular/<app>/src/main.ts`
+- Go entry point: `apps/go/servicediscovery/main.go`
+- Spring Boot entry point: `apps/springboot/usersrole/src/main/kotlin/`
+- Shared Angular code: `libs/angular/`
+- Shared Go code: `libs/go/`
+- NX project graph: `npx nx graph`
+
+## Constraints
+
+- Do not add direct dependencies between Angular apps — use shared libs in `libs/angular/`
+- All secrets come from environment variables injected at deploy time — no hardcoded secrets
+- Do not push to remote without developer review

CONTRIBUTING.md

@@ -0,0 +1,106 @@
+# Contributing
+
+## Commit Convention
+
+This repository follows [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/).
+
+### Types
+
+| Type | When to use |
+|------|-------------|
+| `feat` | New feature or user-visible capability |
+| `fix` | Bug fix |
+| `build` | Build system or external dependency change (NX, pnpm, Go modules) |
+| `chore` | Maintenance: config, tooling (no production code change) |
+| `ci` | CI/CD pipeline changes |
+| `docs` | Documentation only (no code changes) |
+| `perf` | Performance improvement |
+| `refactor` | Code restructure with no behavior change |
+| `revert` | Reverting a previous commit |
+| `style` | Formatting or whitespace only (no logic change) |
+| `test` | Adding or updating tests |
+
+### Format
+
+```
+<type>[optional scope]: <description>
+
+[optional body]
+
+[optional footer(s)]
+```
+
+### Examples
+
+```
+feat(authui): add OIDC token refresh flow
+fix(usersrole): return 404 when user not found
+ci: add pnpm cache to build workflow
+docs: document module federation remote config
+chore: upgrade angular to 19.2
+refactor(rolesui): extract role list to shared component
+test(usersrole): add integration test for role assignment
+```
+
+### Footers
+
+Footers appear after an optional body, separated by a blank line. Common footers:
+
+| Footer | When to use |
+|--------|-------------|
+| `Refs: JDWLABS-XX` | Links commit to a Jira issue (does not close it) |
+| `Closes: JDWLABS-XX` | Closes the Jira issue on merge |
+| `Closes: #N` | Closes a GitHub issue by number |
+| `BREAKING CHANGE: <desc>` | Required when a commit introduces a breaking API/interface change |
+| `Co-Authored-By: Name <email>` | Credit a co-author (human or AI) |
+
+**AI contributor footer** — include when commits were written with AI assistance:
+
+```
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+```
+
+**Full examples with footers:**
+
+```
+feat(authui): add OIDC token refresh flow
+
+Implements silent refresh using a hidden iframe per the OIDC spec.
+Falls back to full re-login if the refresh token is expired.
+
+Refs: JDWLABS-42
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
+```
+
+```
+fix!(usersrole): remove deprecated /users/list endpoint
+
+BREAKING CHANGE: /users/list removed; use /users?page=N instead.
+
+Closes: JDWLABS-38
+Closes: #17
+```
+
+### Rules
+
+- Subject line ≤72 characters, lowercase, no trailing period
+- Use imperative mood: "add" not "added" / "adds"
+- Scope is optional but encouraged — use the app or lib name
+- Breaking changes: add `!` after type/scope and a `BREAKING CHANGE:` footer
+
+## Pull Requests
+
+1. Branch from `main`: `git checkout -b feat/short-description`
+2. Keep PRs focused — one logical change per PR
+3. PR title must follow conventional commit format: `type(scope): description`
+4. Fill the PR template completely
+5. Squash-merge to main to keep history clean
+
+## Development Setup
+
+```bash
+pnpm install --frozen-lockfile    # Install dependencies
+npx nx run-many -t build          # Verify build passes
+npx nx run-many -t test           # Verify tests pass
+npx nx run-many -t lint           # Verify lint passes
+```

GEMINI.md

@@ -0,0 +1,35 @@
+# GEMINI.md
+
+This file provides guidance to Gemini CLI when working in this repository.
+For the canonical reference, see [CLAUDE.md](CLAUDE.md) — this file mirrors that content.
+
+## Repository Overview
+
+NX monorepo for jdwlabs application services. Contains Angular micro-frontends, Go backend services, a Spring Boot/Kotlin service, and database migration tooling.
+
+### Structure
+
+- `apps/angular/` — Angular micro-frontend apps (authui, container, rolesui, usersui, platform-e2e)
+- `apps/go/` — Go services (servicediscovery)
+- `apps/springboot/` — Spring Boot/Kotlin service (usersrole)
+- `apps/database/` — Database migration apps (authdb)
+- `libs/angular/` — Shared Angular libraries
+- `libs/go/` — Shared Go libraries
+
+## Development Commands
+
+```bash
+npx nx build <app-name>           # Build one app
+npx nx test <app-name>            # Test one app
+npx nx lint <app-name>            # Lint one app
+npx nx affected -t build,test     # CI-equivalent: affected apps only
+go build ./...                    # Go workspace build (from repo root)
+go test ./...                     # Go workspace test (from repo root)
+```
+
+## Agent Contract
+
+- Use `npx nx` for all Angular build/test/lint — never `ng` directly
+- Use `go` commands from repo root for Go services (`go.work` covers `apps/go/` and `libs/go/`)
+- Do not modify lockfiles directly
+- Do not push to remote — stage and commit only

scripts/README.md

@@ -7,21 +7,21 @@ These are **not Nx projects** and are excluded from Nx project detection via `.n
 
 All scripts are executable and accept arguments described in the usage comment at the top of each file.
 
-| Script | Purpose |
-|--------|---------|
-| `create-version.sh` | Write a `version.json` file into an app's `public/` dir after a semver release |
-| `format.sh` | Run `nx format:write` across the workspace — called by the Nx `format` target in each app's `project.json` |
-| `prepare-config.sh` | Swap `config.json` to its production values before a Docker image build |
-| `restore-config.sh` | Restore `config.json` to its development defaults after a build |
-| `update-app.sh` | Bump the `appVersion` in a Helm `Chart.yaml` to match the released semver tag |
-| `update-version.sh` | Update the version string in a `build.gradle.kts` (Spring Boot) to match the release tag |
+| Script              | Purpose                                                                                                    |
+| ------------------- | ---------------------------------------------------------------------------------------------------------- |
+| `create-version.sh` | Write a `version.json` file into an app's `public/` dir after a semver release                             |
+| `format.sh`         | Run `nx format:write` across the workspace — called by the Nx `format` target in each app's `project.json` |
+| `prepare-config.sh` | Swap `config.json` to its production values before a Docker image build                                    |
+| `restore-config.sh` | Restore `config.json` to its development defaults after a build                                            |
+| `update-app.sh`     | Bump the `appVersion` in a Helm `Chart.yaml` to match the released semver tag                              |
+| `update-version.sh` | Update the version string in a `build.gradle.kts` (Spring Boot) to match the release tag                   |
 
 ## Docker
 
-| File | Purpose |
-|------|---------|
+| File                  | Purpose                                                                     |
+| --------------------- | --------------------------------------------------------------------------- |
 | `docker/compose.yaml` | Docker Compose config for the local development stack (databases, services) |
-| `docker/config.json` | Docker-related configuration shared across services |
+| `docker/config.json`  | Docker-related configuration shared across services                         |
 
 ## Usage
 

scripts/docker/README.md

@@ -122,4 +122,3 @@ mappings for the microfrontends and their respective URLs and metadata. Below is
 
 Ensure all services are up and running before performing any manual or automated tests. Access each service by
 navigating to their respective URLs as outlined above.
-