Start user-engine implementation scaffold

docs/configuration.md

@@ -0,0 +1,44 @@
+# Configuration Boundaries
+
+## Standalone Mode
+
+Standalone mode is for local development, tests, prototypes, and small
+single-service deployments.
+
+Expected characteristics:
+
+- local configuration file or environment variables;
+- local database or file-backed persistence during early development;
+- fixture or local identity claims adapter;
+- deterministic authorization test adapter;
+- no password, MFA, or token issuance responsibility inside user-engine.
+
+## Platform Mode
+
+Platform mode is for a NetKingdom-aligned shared service deployment.
+
+Expected characteristics:
+
+- verified IAM Profile claims arrive from an identity layer;
+- authorization decisions are requested through the authorization check port;
+- runtime secrets are delivered through a scoped secret provider;
+- audit records and outbox events are correlated with platform sinks;
+- tenant and application bindings are explicit.
+
+## Secret Names
+
+The code should refer to logical secret names, not platform paths. Concrete
+secret lookup is owned by the active `SecretProvider` adapter.
+
+Initial logical names:
+
+- `database.url`
+- `event.signing_key`
+- `webhook.shared_secret`
+
+## Production Guardrails
+
+- Local issuers must be rejected by production adapters.
+- Sensitive writes must fail closed when authorization is unavailable.
+- Claims enrichment must be optional and must not make user-engine a token
+  issuer.

docs/development.md

@@ -0,0 +1,42 @@
+# Development
+
+## Stack
+
+The initial implementation uses Python 3.12 and the standard library. The
+first slice intentionally avoids runtime dependencies so the repository can be
+tested immediately in local and agent environments.
+
+## Layout
+
+```text
+src/user_engine/
+  domain/      transport- and persistence-neutral domain schemas
+  ports.py     adapter protocols for identity, authorization, events, audit,
+               membership export, application bindings, and secrets
+  testing/     local fixtures for tests and examples
+tests/         standard-library unittest suite
+```
+
+The domain layer should not import HTTP frameworks, database clients, or
+platform-specific SDKs. Those integrations belong behind ports.
+
+## Commands
+
+```bash
+make test
+```
+
+The command runs:
+
+```bash
+PYTHONPATH=src python3 -m unittest discover -s tests -p 'test_*.py'
+```
+
+## Implementation Rule
+
+Add new behavior in this order:
+
+1. domain schema or port;
+2. local fixture or adapter;
+3. test that proves the boundary;
+4. infrastructure adapter or API surface.