# KeyCape — Claude Code Instructions

## What This Repo Is

**KeyCape** is the lightweight IAM component of NetKingdom.

> *"Prepare for Keycloak without Keycloak"*

KeyCape implements the **NetKingdom IAM Profile** — a versioned OIDC/PKCE contract
that NetKingdom applications integrate against. It orchestrates:

| Component    | Role                          |
|--------------|-------------------------------|
| Authelia     | OIDC provider / session / tokens |
| LLDAP        | Lightweight identity directory |
| privacyIDEA  | MFA authority                 |

Keycape is intentionally replaceable by **Keycloak** in expanded mode. All apps
must target the profile, not Keycape or Keycloak incidentals.

## Custodian State Hub Integration

- **Domain:** `netkingdom`
- **Repo ID:** `8a99bb74-1ec0-4478-ac70-35a7cddb0e3c`
- **State Hub API:** `http://127.0.0.1:8000` (run `cd ~/the-custodian/state-hub && make api` if offline)

### Session Protocol

**Start of every session:**
```
get_domain_summary("netkingdom")
```
This gives the full picture of active workstreams, blocking decisions, and recent
progress for the NetKingdom domain at ~10% of the cost of `get_state_summary()`.

**During work:**
- `record_decision()` for any architectural choice (profile extensions, backend selection, etc.)
- `add_progress_event()` for milestones, blockers, discoveries
- `resolve_decision()` once a decision is closed

**End of every session:**
```
add_progress_event(summary="...", event_type="...", workstream_id="<active ws id>")
```

After modifying workplan files, run:
```
cd ~/the-custodian/state-hub && make fix-consistency REPO=key-cape
```

## Key Documents

| Document | Path | Purpose |
|---|---|---|
| Keycape Specification v0.1 | `wiki/KeyCapeSpecification_v0.1.md` | Architecture, design intent, objectives |
| Normative Specification Pack v0.1 | `wiki/KeyCapeSpecificationPack_v0.1.md` | Normative spec for implementation agents: identity model, LDAP schema, error taxonomy, telemetry, migration contract, acceptance test matrix |

## Architecture

```
key-cape/
  wiki/               # Specifications (read before implementing)
  workplans/          # Implementation workplans (ADR-001 convention)
  src/                # Implementation (to be created)
  tests/              # Test suite (to be created)
```

### Lightweight mode stack

```
Application ──→ NetKingdom IAM Profile
                      │
                   KeyCape  ←── config translation, claim normalization
                   /   |  \
           Authelia  LLDAP  privacyIDEA
```

### Expanded mode stack (Keycape → Keycloak)

```
Application ──→ NetKingdom IAM Profile
                      │
                  Keycloak  (same profile, different runtime)
                   /   \
             LDAP      privacyIDEA
```

## Implementation Priorities (from spec)

1. **Profile endpoints** — OIDC discovery, authorization, token, JWKS, userinfo
2. **Canonical identity model** — product-neutral user/group/client schema
3. **Claim normalization** — stable claim set regardless of backend quirks
4. **Unsupported-feature enforcement** — structured errors, never silent emulation
5. **Telemetry** — demand visibility for unsupported features and auth events
6. **Migration tooling** — export/validate for LLDAP → Keycloak path

## Workplan Convention (ADR-001)

Workplans live in `workplans/<id>-<slug>.md` with YAML frontmatter:
```yaml
id: KEY-WP-0001
type: workplan
title: "..."
domain: netkingdom
repo: key-cape
status: todo|active|done
owner: Bernd
topic_slug: netkingdom
```

Tasks are embedded as `## Task Title\n```task\nid: ...\nstatus: todo\n```\n` blocks.