📝 docs: migrate to RepositoryBuilder API and add namespace documentation (#392)

## Summary

- Migrate all code examples from deprecated
`Repository()`/`StackOptions`/`RateLimiter(name=)` constructors to the
v0.10.0 `RepositoryBuilder` pattern
- Add namespace documentation throughout: `{ns}/` key prefixes,
GSI3+GSI4 schema, namespace registration, `--namespace` CLI flag,
namespace-scoped IAM policies (TBAC), multi-tenant isolation
- Update README, landing page, architecture, operator guides, user
guides, CLI reference, performance, and monitoring docs

## Test plan

- [x] `mkdocs build --strict` passes with no errors
- [x] Grep verification: no remaining `Repository(name=`,
`RateLimiter(name=`, or `stack_options=StackOptions` in updated files
- [x] Visual review of rendered docs site

Closes #389

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: sodre

README.md

@@ -28,18 +28,15 @@ conda install -c conda-forge zae-limiter
 ## Usage
 
 ```python
-from zae_limiter import RateLimiter, SyncRateLimiter, Limit, StackOptions
+from zae_limiter import Repository, RateLimiter, SyncRepository, SyncRateLimiter, Limit
 
-# async-aws-backed-production-ready-rate-limiter
-limiter = RateLimiter(
-    name="my-app",
-    region="us-east-1",
-    # Declare desired infrastructure state - CloudFormation ensures it matches
-    stack_options=StackOptions(),
-)
+# Async — builder handles infrastructure + namespace resolution
+repo = await Repository.builder("my-app", "us-east-1").build()
+limiter = RateLimiter(repository=repo)
 
-# Sync wrapper shares the same infrastructure and API.
-sync_limiter = SyncRateLimiter(name="my-app", region="us-east-1")
+# Sync wrapper shares the same infrastructure and API
+sync_repo = SyncRepository.builder("my-app", "us-east-1").build()
+sync_limiter = SyncRateLimiter(repository=sync_repo)
 
 # Define default limits (can be overridden per-entity)
 default_limits = [
@@ -70,12 +67,15 @@ with sync_limiter.acquire(
     resource="gpt-4",
     limits=default_limits,
     consume={"rpm": 1, "tpm": 500},
-    use_stored_limits=True,  # Uses proj-1's 100k tpm limit
 ):
     call_api()
 
+# Multi-tenant: each tenant gets an isolated namespace
+tenant_repo = await Repository.builder("my-app", "us-east-1").namespace("tenant-alpha").build()
+tenant_limiter = RateLimiter(repository=tenant_repo)
+
 # Cleanup (removes all data)
-await limiter.delete_stack()
+await repo.delete_stack()
 ```
 
 ## Documentation
@@ -89,6 +89,7 @@ await limiter.delete_stack()
 | [Hierarchical Limits](https://zeroae.github.io/zae-limiter/guide/hierarchical/) | Parent/child entities, cascade mode |
 | [LLM Integration](https://zeroae.github.io/zae-limiter/guide/llm-integration/) | Token estimation and reconciliation |
 | [CLI Reference](https://zeroae.github.io/zae-limiter/cli/) | Deploy, status, delete commands |
+| [Multi-Tenant Guide](https://zeroae.github.io/zae-limiter/infra/production/#multi-tenant-deployments) | Namespace isolation, per-tenant IAM |
 | [Production Guide](https://zeroae.github.io/zae-limiter/infra/production/) | Security, monitoring, cost |
 
 ## Production Deployment

docs/cli.md

@@ -32,3 +32,46 @@ The CLI respects standard AWS environment variables:
 | `2` | Invalid arguments |
 | `3` | AWS API error |
 | `4` | Stack not found |
+
+## Namespace Flag
+
+Most data-access commands accept `--namespace` / `-N` to scope operations to a specific namespace. When omitted, operations default to the `"default"` namespace.
+
+```bash
+# Entity operations in a specific namespace
+zae-limiter entity set-limits user-123 --namespace tenant-alpha -l rpm:1000
+
+# System defaults for a namespace
+zae-limiter system set-defaults --namespace tenant-alpha -l rpm:5000
+
+# Usage and audit scoped to a namespace
+zae-limiter usage list --namespace tenant-alpha
+zae-limiter audit list --namespace tenant-alpha
+```
+
+## Namespace Lifecycle
+
+The `namespace` command group manages the namespace registry:
+
+```bash
+# Register namespaces
+zae-limiter namespace register tenant-alpha tenant-beta
+
+# List active namespaces
+zae-limiter namespace list
+
+# Show namespace details (including opaque ID)
+zae-limiter namespace show tenant-alpha
+
+# Soft delete (data preserved, forward lookup removed)
+zae-limiter namespace delete tenant-alpha
+
+# Recover a soft-deleted namespace
+zae-limiter namespace recover <namespace-id>
+
+# List deleted namespaces (candidates for purge)
+zae-limiter namespace orphans
+
+# Hard delete all data in a namespace (irreversible)
+zae-limiter namespace purge <namespace-id> --yes
+```

docs/contributing/architecture.md

@@ -8,39 +8,53 @@ All data is stored in a single DynamoDB table using a composite key pattern:
 
 | Record Type | PK | SK |
 |-------------|----|----|
-| Entity metadata | `ENTITY#{id}` | `#META` |
-| Bucket | `ENTITY#{id}` | `#BUCKET#{resource}#{limit_name}` |
-| Entity config | `ENTITY#{id}` | `#CONFIG#{resource}` |
-| Resource config | `RESOURCE#{resource}` | `#CONFIG` |
-| System config | `SYSTEM#` | `#CONFIG` |
-| Usage snapshot | `ENTITY#{id}` | `#USAGE#{resource}#{window_key}` |
-| System version | `SYSTEM#` | `#VERSION` |
-| Audit events | `AUDIT#{entity_id}` | `#AUDIT#{timestamp}` |
+| Entity metadata | `{ns}/ENTITY#{id}` | `#META` |
+| Bucket | `{ns}/ENTITY#{id}` | `#BUCKET#{resource}#{limit_name}` |
+| Entity config | `{ns}/ENTITY#{id}` | `#CONFIG#{resource}` |
+| Resource config | `{ns}/RESOURCE#{resource}` | `#CONFIG` |
+| System config | `{ns}/SYSTEM#` | `#CONFIG` |
+| Usage snapshot | `{ns}/ENTITY#{id}` | `#USAGE#{resource}#{window_key}` |
+| System version | `{ns}/SYSTEM#` | `#VERSION` |
+| Audit events | `{ns}/AUDIT#{entity_id}` | `#AUDIT#{timestamp}` |
+| Namespace forward | `_/SYSTEM#` | `#NAMESPACE#{name}` |
+| Namespace reverse | `_/SYSTEM#` | `#NSID#{id}` |
 
 ### Global Secondary Indexes
 
 | Index | Purpose | Key Pattern |
 |-------|---------|-------------|
-| **GSI1** | Parent → Children lookup | `GSI1PK=PARENT#{id}` → `GSI1SK=CHILD#{id}` |
-| **GSI2** | Resource aggregation | `GSI2PK=RESOURCE#{name}` → buckets/usage |
-| **GSI3** | Entity config queries (sparse) | `GSI3PK=ENTITY_CONFIG#{resource}` → `GSI3SK=entity_id` |
+| **GSI1** | Parent → Children lookup | `GSI1PK={ns}/PARENT#{id}` → `GSI1SK=CHILD#{id}` |
+| **GSI2** | Resource aggregation | `GSI2PK={ns}/RESOURCE#{name}` → buckets/usage |
+| **GSI3** | Entity config queries (sparse) | `GSI3PK={ns}/ENTITY_CONFIG#{resource}` → `GSI3SK=entity_id` |
+| **GSI4** | Namespace item discovery (KEYS_ONLY) | `GSI4PK={ns}` → `GSI4SK=PK` |
 
 ### Access Patterns
 
 | Pattern | Query |
 |---------|-------|
-| Get entity | `PK=ENTITY#{id}, SK=#META` |
-| Get buckets | `PK=ENTITY#{id}, SK begins_with #BUCKET#` |
+| Get entity | `PK={ns}/ENTITY#{id}, SK=#META` |
+| Get buckets | `PK={ns}/ENTITY#{id}, SK begins_with #BUCKET#` |
 | Batch get buckets | `BatchGetItem` with multiple PK/SK pairs |
-| Get children | GSI1: `GSI1PK=PARENT#{id}` |
-| Resource capacity | GSI2: `GSI2PK=RESOURCE#{name}, SK begins_with BUCKET#` |
-| Get version | `PK=SYSTEM#, SK=#VERSION` |
-| Get audit events | `PK=AUDIT#{entity_id}, SK begins_with #AUDIT#` |
-| Get usage snapshots | `PK=ENTITY#{id}, SK begins_with #USAGE#` |
-| Get system config | `PK=SYSTEM#, SK=#CONFIG` |
-| Get resource config | `PK=RESOURCE#{resource}, SK=#CONFIG` |
-| Get entity config | `PK=ENTITY#{id}, SK=#CONFIG#{resource}` |
-| List entities with custom limits | GSI3: `GSI3PK=ENTITY_CONFIG#{resource}` |
+| Get children | GSI1: `GSI1PK={ns}/PARENT#{id}` |
+| Resource capacity | GSI2: `GSI2PK={ns}/RESOURCE#{name}, SK begins_with BUCKET#` |
+| Get version | `PK={ns}/SYSTEM#, SK=#VERSION` |
+| Get audit events | `PK={ns}/AUDIT#{entity_id}, SK begins_with #AUDIT#` |
+| Get usage snapshots | `PK={ns}/ENTITY#{id}, SK begins_with #USAGE#` |
+| Get system config | `PK={ns}/SYSTEM#, SK=#CONFIG` |
+| Get resource config | `PK={ns}/RESOURCE#{resource}, SK=#CONFIG` |
+| Get entity config | `PK={ns}/ENTITY#{id}, SK=#CONFIG#{resource}` |
+| List entities with custom limits | GSI3: `GSI3PK={ns}/ENTITY_CONFIG#{resource}` |
+| Namespace forward lookup | `PK=_/SYSTEM#, SK=#NAMESPACE#{name}` |
+| Namespace reverse lookup | `PK=_/SYSTEM#, SK=#NSID#{id}` |
+| List all items in namespace | GSI4: `GSI4PK={ns}` |
+
+### Namespace Isolation
+
+All partition key values are prefixed with an opaque namespace ID (`{ns}/`), providing logical isolation between tenants within a single DynamoDB table. The reserved namespace `_` is used for the namespace registry itself (forward and reverse lookup records).
+
+- **Namespace ID format**: 11-character opaque string generated via `secrets.token_urlsafe(8)`
+- **Default namespace**: Automatically registered on first deploy or `RepositoryBuilder.build()`
+- **GSI4**: A KEYS_ONLY index on `GSI4PK=namespace_id` enables `purge_namespace()` to discover and delete all items belonging to a namespace
 
 ### Optimized Read Patterns
 
@@ -80,7 +94,7 @@ See [ADR-111](../adr/111-flatten-all-records.md).
 ```{.python .lint-only}
 # Entity record (FLAT structure):
 {
-    "PK": "ENTITY#user-1",
+    "PK": "{ns}/ENTITY#user-1",
     "SK": "#META",
     "entity_id": "user-1",
     "name": "User One",
@@ -94,7 +108,7 @@ See [ADR-111](../adr/111-flatten-all-records.md).
 ```python
 # Bucket record (FLAT structure, ADR-114/115):
 {
-    "PK": "ENTITY#user-1",
+    "PK": "{ns}/ENTITY#user-1",
     "SK": "#BUCKET#gpt-4",
     "entity_id": "user-1",
     "resource": "gpt-4",
@@ -105,7 +119,7 @@ See [ADR-111](../adr/111-flatten-all-records.md).
     "b_rpm_cp": 100000,             # capacity_milli for rpm limit
     "b_rpm_tc": 5000,               # total_consumed_milli for rpm
     "rf": 1704067200000,            # last_refill_ms (shared across limits)
-    "GSI2PK": "RESOURCE#gpt-4",
+    "GSI2PK": "{ns}/RESOURCE#gpt-4",
     "ttl": 1234567890
 }
 ```
@@ -121,15 +135,15 @@ exceeds consumption rate. See [Issue #179](https://github.com/zeroae/zae-limiter
 ```python
 # Usage snapshot (FLAT structure):
 {
-    "PK": "ENTITY#user-1",
+    "PK": "{ns}/ENTITY#user-1",
     "SK": "#USAGE#gpt-4#2024-01-01T14:00:00Z",
     "entity_id": "user-1",
     "resource": "gpt-4",        # Top-level attribute
     "window": "hourly",         # Top-level attribute
     "window_start": "...",      # Top-level attribute
     "tpm": 5000,                # Counter at top-level
     "total_events": 10,         # Counter at top-level
-    "GSI2PK": "RESOURCE#gpt-4",
+    "GSI2PK": "{ns}/RESOURCE#gpt-4",
     "ttl": 1234567890
 }
 ```
@@ -147,7 +161,7 @@ See: [Issue #168](https://github.com/zeroae/zae-limiter/issues/168)
 ```python
 # Resource config (composite, FLAT structure):
 {
-    "PK": "RESOURCE#gpt-4",           # or SYSTEM# or ENTITY#{id}
+    "PK": "{ns}/RESOURCE#gpt-4",       # or {ns}/SYSTEM# or {ns}/ENTITY#{id}
     "SK": "#CONFIG",                   # or #CONFIG#{resource} for entity level
     "resource": "gpt-4",
     "l_tpm_cp": 100000,               # capacity for tpm limit
@@ -162,11 +176,13 @@ Config records use four-level precedence: **Entity (resource-specific) > Entity
 
 **Key builders:**
 
-- `pk_system()` - Returns `SYSTEM#`
-- `pk_resource(resource)` - Returns `RESOURCE#{resource}`
-- `pk_entity(entity_id)` - Returns `ENTITY#{entity_id}`
+- `pk_system(namespace_id)` - Returns `{ns}/SYSTEM#`
+- `pk_resource(namespace_id, resource)` - Returns `{ns}/RESOURCE#{resource}`
+- `pk_entity(namespace_id, entity_id)` - Returns `{ns}/ENTITY#{entity_id}`
 - `sk_config()` - Returns `#CONFIG` (system/resource level)
 - `sk_config(resource)` - Returns `#CONFIG#{resource}` (entity level)
+- `sk_namespace(name)` - Returns `#NAMESPACE#{name}` (forward lookup)
+- `sk_nsid(id)` - Returns `#NSID#{id}` (reverse lookup)
 
 **Audit entity IDs for config levels** (see [ADR-106](../adr/106-audit-entity-ids-for-config.md)):
 
@@ -484,7 +500,7 @@ src/zae_limiter/
 ├── exceptions.py          # RateLimitExceeded, RateLimiterUnavailable, etc.
 ├── naming.py              # Resource name validation
 ├── bucket.py              # Token bucket math (integer arithmetic)
-├── schema.py              # DynamoDB key builders
+├── schema.py              # DynamoDB key builders (namespace-prefixed)
 ├── repository_protocol.py # RepositoryProtocol for backend abstraction
 ├── repository.py          # DynamoDB operations
 ├── config_cache.py        # Client-side config caching with TTL

docs/contributing/localstack.md

@@ -93,15 +93,16 @@ async with limiter.acquire(
 
 For quick iteration, declare infrastructure in code:
 
-```python
-from zae_limiter import RateLimiter, StackOptions
+```{.python .requires-localstack}
+from zae_limiter import Repository, RateLimiter
 
-limiter = RateLimiter(
-    name="limiter",
-    endpoint_url="http://localhost:4566",
-    region="us-east-1",
-    stack_options=StackOptions(),  # Declare desired state
+repo = await (
+    Repository.builder("limiter", "us-east-1", endpoint_url="http://localhost:4566")
+    .enable_aggregator(False)
+    .enable_alarms(False)
+    .build()
 )
+limiter = RateLimiter(repository=repo)
 ```
 
 ## Environment Variables

docs/contributing/testing.md

@@ -69,7 +69,7 @@ def localstack_endpoint():
 ```python
 import uuid
 import pytest
-from zae_limiter import Repository, RateLimiter, StackOptions
+from zae_limiter import Repository, RateLimiter
 
 @pytest.fixture(scope="function")
 async def limiter(localstack_endpoint):
@@ -84,16 +84,14 @@ async def limiter(localstack_endpoint):
     # Unique name prevents test interference
     name = f"test-{uuid.uuid4().hex[:8]}"
 
-    repo = Repository(
-        name=name,
-        endpoint_url=localstack_endpoint,
-        region="us-east-1",
-        stack_options=StackOptions(enable_aggregator=False),
+    repo = await (
+        Repository.builder(name, "us-east-1", endpoint_url=localstack_endpoint)
+        .enable_aggregator(False)
+        .build()
     )
     limiter = RateLimiter(repository=repo)
 
-    async with limiter:
-        yield limiter
+    yield limiter
 
     # Cleanup: delete the CloudFormation stack
     await repo.delete_stack()
@@ -122,16 +120,14 @@ async def shared_limiter(localstack_endpoint):
 
     Trade-off: Tests share state, less isolation.
     """
-    repo = Repository(
-        name="integration-test-shared",
-        endpoint_url=localstack_endpoint,
-        region="us-east-1",
-        stack_options=StackOptions(enable_aggregator=False),
+    repo = await (
+        Repository.builder("integration-test-shared", "us-east-1", endpoint_url=localstack_endpoint)
+        .enable_aggregator(False)
+        .build()
     )
     limiter = RateLimiter(repository=repo)
 
-    async with limiter:
-        yield limiter
+    yield limiter
 
     await repo.delete_stack()
 ```
@@ -142,21 +138,19 @@ async def shared_limiter(localstack_endpoint):
 @pytest.fixture(scope="function")
 def sync_limiter(localstack_endpoint):
     """Synchronous rate limiter with cleanup."""
-    from zae_limiter import SyncRepository, SyncRateLimiter, StackOptions
+    from zae_limiter import SyncRepository, SyncRateLimiter
     import uuid
 
     name = f"test-sync-{uuid.uuid4().hex[:8]}"
 
-    repo = SyncRepository(
-        name=name,
-        endpoint_url=localstack_endpoint,
-        region="us-east-1",
-        stack_options=StackOptions(enable_aggregator=False),
+    repo = (
+        SyncRepository.builder(name, "us-east-1", endpoint_url=localstack_endpoint)
+        .enable_aggregator(False)
+        .build()
     )
     limiter = SyncRateLimiter(repository=repo)
 
-    with limiter:
-        yield limiter
+    yield limiter
 
     repo.delete_stack()
 ```