feat: prime repo — CLAUDE.md + README, register in state-hub

- CLAUDE.md: session protocol, architecture overview, spec pointers, workplan convention, state-hub repo ID (8a99bb74, netkingdom domain) - README.md: replace repo-seed placeholder with KeyCape description Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
2026-03-13 00:23:19 +01:00
parent 97d3fceea6
commit 3780190456
2 changed files with 155 additions and 2 deletions
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -0,0 +1,111 @@
+# 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.
--- a/README.md
+++ b/README.md
@@ -1,3 +1,45 @@
-# repo-seed
+# KeyCape

-A git repository template to bootstrap coulomb projects from.
+*Prepare for Keycloak without Keycloak*
+
+KeyCape is the lightweight IAM component of [NetKingdom](../net-kingdom/). It
+implements the **NetKingdom IAM Profile** — a versioned OIDC/PKCE contract —
+by orchestrating Authelia, LLDAP, and privacyIDEA. The same profile is
+implemented by Keycloak in expanded-mode deployments.
+
+Applications integrate against the profile, not against Keycape internals. This
+makes the lightweight → expanded migration a tested, automated operation rather
+than a rewrite.
+
+## Status
+
+**Specification phase.** The normative spec (v0.1) is complete. Implementation
+workplans are the next step.
+
+## Key Documents
+
+- `wiki/KeyCapeSpecification_v0.1.md` — Architecture, design intent, objectives
+- `wiki/KeyCapeSpecificationPack_v0.1.md` — Normative implementation spec:
+  canonical identity model, LDAP schema + validator rules, error taxonomy,
+  telemetry schema, migration contract, acceptance test matrix
+
+## Architecture
+
+```
+Application
+    │  (NetKingdom IAM Profile)
+    ▼
+ KeyCape  ←── profile enforcement, claim normalization, telemetry
+  /  |  \
+Auth  LLDAP  privacyIDEA
+elia
+```
+
+**Expanded mode:** Replace KeyCape with Keycloak. Same profile, same tests pass.
+
+## Domain
+
+Part of the **NetKingdom** domain. Tracked in the Custodian State Hub under
+domain `netkingdom`, repo slug `key-cape`.
+
+See `CLAUDE.md` for agent session protocol and workplan conventions.