core-framework 2.0.0__tar.gz → 2.1.0__tar.gz

core_framework-2.1.0/.agents/skills/fastapi

@@ -0,0 +1 @@
+../../.venv/lib/python3.14/site-packages/fastapi/.agents/skills/fastapi

core_framework-2.1.0/.agents/skills/library-skills/.library-skills.json

@@ -0,0 +1,4 @@
+{
+  "kind": "tool-skill",
+  "version": "0.0.19"
+}

core_framework-2.1.0/.agents/skills/library-skills/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: library-skills
+description: Use Library Skills to discover, install, refresh, repair, check, and manage agent skills from installed packages.
+---
+
+# Library Skills
+
+Use this skill when a project might benefit from agent skills bundled by its installed packages, or when existing Library Skills-managed symlinks are stale, broken, orphaned, or need to be checked.
+
+Run commands from the project root.
+
+Agents bundle their own skills by including an `.agents/skills` directory. More details in [Library Skills](https://library-skills.io).
+
+## First-Time Setup
+
+- Make sure project dependencies are installed first, for example with `uv sync` for Python projects or `npm install` / `bun install` for Node.js projects.
+- Run `uvx library-skills` or `npx library-skills` to discover skills bundled by the installed packages and install selected skills interactively.
+- Use `uvx library-skills --all` or `npx library-skills --all` only when all newly discovered skills should be installed without selecting individual skills.
+- Use `uvx library-skills --tool-skill` or `npx library-skills --tool-skill` to copy this Library Skills tool skill into the project so future agents know how to discover, install, update, repair, and check skills.
+
+## Commands
+
+- Run `uvx library-skills` or `npx library-skills` to discover package-provided skills, install selected new skills, and reconcile existing managed symlinks.
+- Run `uvx library-skills list` or `npx library-skills list` to inspect discovered and installed skills.
+- Run `uvx library-skills list --json` or `npx library-skills list --json` for machine-readable installed status.
+- Run `uvx library-skills scan --json` or `npx library-skills scan --json` for discovery-only automation.
+- Run `uvx library-skills --check` or `npx library-skills --check` to validate managed skill symlink state without changing files.
+- Run `uvx library-skills --yes` or `npx library-skills --yes` to repair stale managed symlinks and remove orphaned managed symlinks non-interactively.
+- Add `--claude` when `.claude/skills` should also be managed.
+- Add `--skill NAME` to install a specific discovered skill by name.
+
+## Safety
+
+- Prefer rerunning `library-skills` over editing managed symlinks manually.
+- If installed skill symlinks are broken, dependencies may not be installed yet. Try the project's normal install command first, such as `uv sync`, `npm install`, or `bun install`, then rerun `library-skills`.
+- Do not delete or overwrite hand-authored skill directories.
+- Library Skills only removes managed symlinks. It should not remove copied or hand-authored skill directories.

core_framework-2.1.0/.cursor/rules/api-layer.mdc

@@ -0,0 +1,36 @@
+---
+description: Core-framework API architecture — HTTP adapters only. FastAPI/Pydantic patterns in the fastapi skill.
+globs:
+  - core_framework/api/**/*.py
+---
+
+# API layer (core-framework)
+
+**Framework patterns:** use the **fastapi** skill (`.cursor/skills/fastapi/`) — `Annotated`, dependencies, routers, Pydantic v2, CLI.
+
+**Validation:** **`api-validation.mdc`**. **Errors:** **`error-boundary.mdc`**. **Domain imports:** **`domain-imports.mdc`**.
+
+## Architecture
+
+The API layer is an HTTP adapter, not a business-logic layer.
+
+- Routers, schemas, and HTTP dependencies only.
+- Call **application** services in `core_framework/application/...` — not domain repositories.
+- No orchestration shared with workers; no worker-only logic here.
+
+## Routers
+
+- Own HTTP concerns: status codes, `HTTPException`, `response_model`, request parsing.
+- When a route sets **`response_model`**, annotate the handler return type as **`typing.Any`** (OpenAPI documents the shape; services may return dicts or domain types). Body-less routes (**`204`**, no **`response_model`**) use **`None`**.
+- Call `validate_*` schema helpers before invoking application services.
+- Do **not** set **`summary=`** or **`description=`** on route decorators or use route docstrings for OpenAPI prose — paths, handler names, **`response_model`**, and schemas suffice.
+
+## Response models
+
+- Do **not** use bare collection types (e.g. `list[Item]`) as `response_model`. Wrap in a named `BaseModel` with an **`items`** field for extensibility.
+
+## Avoid
+
+- Reusable business workflows in API modules.
+- Direct imports from domain internals (only `__init__.py` and `dependencies.py`).
+- `ORJSONResponse` / `UJSONResponse` — use return types / `response_model` per the fastapi skill.

core_framework-2.1.0/.cursor/rules/api-validation.mdc

@@ -0,0 +1,22 @@
+---
+description: API layer must validate all fields that have database constraints
+globs: ["core_framework/api/**/*.py"]
+---
+
+# API validation
+
+Any field with a database constraint (CHECK, NOT NULL, UNIQUE, FK, length) **must** be validated at the API layer before Postgres — return **422**, not **500** from constraint violations.
+
+## How
+
+1. Review migrations when adding endpoints; mirror constraints in Pydantic (`Field`, `field_validator`, enums).
+2. Map common patterns: `varchar(n)` → `max_length`, CHECK patterns → `pattern`/`EmailStr`, enums → Python `Enum`, required → no bare `| None`.
+3. Skip validation only for unconstrained free text, system-generated fields, and internal-only values.
+
+## Layer split
+
+- **API** — client contract, **422**, OpenAPI accuracy.
+- **Domain service** — business preconditions for all callers (workers too); see **`domain-input-guards.mdc`**.
+- Domain backstops must not become a second client channel: **`DomainValidationError`** → **`GENERIC_BAD_REQUEST_DETAIL`** per **`error-boundary.mdc`**.
+
+Canonical doc: **`docs/platform/client-error-visibility.md`**.

core_framework-2.1.0/.cursor/rules/application-layer.mdc

@@ -0,0 +1,29 @@
+---
+description: Application services must be transport-agnostic and return plain Python types
+globs:
+  - core_framework/application/**/*_service.py
+---
+
+# Application layer
+
+Application services orchestrate use cases shared by API and workers. They stay transport-agnostic.
+
+## No HTTP concerns
+
+- Do not import FastAPI/Starlette types, `HTTPException`, `RequestValidationError`, status codes, request/response classes, or background task types.
+- Do not assume the caller is HTTP.
+- Input shape validation belongs in API schemas/routers; services handle use-case orchestration.
+
+## Outcomes
+
+- Return plain Python/domain values: `dict`, `list[dict]`, dataclasses, primitives, `None`, or empty collections.
+- Do not return API/Pydantic `BaseModel` instances.
+- Signal HTTP-meaningful failures with **`application.shared.exceptions`** or plain outcomes (`None`, empty), never typed domain exceptions. See **`error-boundary.mdc`**.
+
+Use a domain dataclass when one domain row matches the response shape; use a `dict` when the payload is composed from several sources.
+
+## Function shape
+
+- Use keyword-only arguments after `*` for application service functions and private helpers.
+- Zero-argument functions are exempt.
+- Use one-line docstrings only; see **`docstrings.mdc`**.

{core_framework-2.0.0 → core_framework-2.1.0}/.cursor/rules/constants-final.mdc

@@ -8,7 +8,7 @@ alwaysApply: false
 
 When introducing or editing **module-level constants** (values that are fixed for the lifetime of the module and not meant to be reassigned):
 
-- Annotate them with **`typing.Final`** and an explicit type, e.g. **`NAME: Final[int] = 42`** or **`_INTERNAL: Final[str] = "henry"`**.
+- Annotate them with **`typing.Final`** and an explicit type, e.g. **`NAME: Final[int] = 42`** or **`_INTERNAL: Final[str] = "example"`**.
 - Prefer **`FrozenSet`**, **`frozenset` literals**, **`MappingProxyType`**, or immutable collections for grouped constants when mutation must be prevented — e.g. **`ProfileUpdate.UPDATE_COLUMNS`** on domain update types.
 - **`Final`** is for **assignment** semantics (no rebinding): it does not freeze mutable object contents unless the type/container is immutable.
 

core_framework-2.1.0/.cursor/rules/constitution.mdc

@@ -0,0 +1,36 @@
+---
+description: Core non-negotiables — behavior, tech stack, layer direction, host scope
+alwaysApply: true
+---
+
+# Constitution
+
+## Behavior
+
+- State assumptions; ask when unclear. Prefer the simplest correct solution.
+- Touch only what the task requires. Match existing style. Remove orphans your edits create.
+- Define verifiable success criteria for non-trivial work.
+
+## Tech stack
+
+- Python 3.14, Pydantic v2, PostgreSQL 18, orjson (not stdlib json).
+- Absolute imports only (`from core_framework....`). Comma-style `except A, B:` is intentional.
+- Prefer newer APIs (`asyncio.TaskGroup` over `gather`).
+
+## Layers
+
+Dependencies point inward: API/worker → application → domain. Never reverse.
+
+- **API/worker** — transport adapters; call application services.
+- **Application** — orchestration shared by API + worker; no FastAPI types.
+- **Domain** — models, repositories (Postgres only), services. No API/worker/application imports except wiring in `dependencies.py`.
+
+Path-scoped rules under `.cursor/rules/` add detail (API, domains, docs, etc.). For FastAPI/Pydantic work in `core_framework/api/`, use the **fastapi** skill (`.cursor/skills/fastapi/`).
+
+## Host applications
+
+Do not edit consuming host repos in the same task as core-framework work unless the user scopes work to a host or asks to sync/upgrade. See the **sync-host-rules** skill.
+
+## Feature implementation
+
+Greenfield features (DB → API → repository → service → tests): use the **implement-feature** skill — one layer per response unless the user says otherwise.

core_framework-2.1.0/.cursor/rules/database-triggers.mdc

@@ -0,0 +1,23 @@
+---
+description: Triggers are for audit/history only — never business logic
+globs:
+  - alembic/**/alembic/versions/*.py
+  - docs/domains/**/*.md
+alwaysApply: false
+---
+
+# Database triggers
+
+**Triggers are for audit/history tracking only.** Never implement business logic, validation policy, side effects, or state transitions in triggers.
+
+## Acceptable
+
+- Immutable change history, actor/timestamp capture, read-only audit rows that do not block the original operation.
+
+## Not acceptable
+
+- Validation that prevents writes, conditional workflows, notifications, cross-table business updates, derived calculations.
+
+Enforce policy in domain services and application orchestration instead. When adding an audit trigger, update **`docs/platform/database-triggers.md`**.
+
+Full rationale: **`docs/platform/conventions.md`** and **`docs/platform/architecture-decisions.md`**.

core_framework-2.1.0/.cursor/rules/docstrings.mdc

@@ -0,0 +1,29 @@
+---
+description: Docstring depth by layer — one-line in application, full Args/Returns/Raises in domain and infrastructure
+globs:
+  - core_framework/application/**/*.py
+  - core_framework/domains/**/*.py
+  - core_framework/infrastructure/**/*.py
+---
+
+# Docstrings by layer
+
+Docstring depth follows the layer boundary.
+
+- **Application** (`core_framework/application/`): one short sentence. No `Args`, `Returns`, or `Raises` sections.
+- **Domain** (`core_framework/domains/`): full docstrings on public service, repository, component, and port methods that implement or define behavior.
+- **Infrastructure** (`core_framework/infrastructure/`): same as domain; document I/O side effects and failure modes.
+
+## Domain/infrastructure contract
+
+Use `Args`, `Returns`, and `Raises` when they clarify the boundary. Repositories should document non-obvious query semantics (filters, empty results, strong vs normal reads).
+
+## When editing
+
+- New functions follow the style for their layer.
+- When changing an existing function, update only that function's docstring if it is out of style.
+- Do not repo-wide migrate unrelated docstrings unless the task asks for it.
+
+## Out of scope
+
+API routers/schemas rely on OpenAPI and Pydantic. Worker wrappers follow application style.

core_framework-2.1.0/.cursor/rules/domain-imports.mdc

@@ -0,0 +1,44 @@
+---
+description: Enforce importing from domain __init__.py in API/application layers
+globs:
+  - core_framework/api/**/*.py
+  - core_framework/application/**/*.py
+---
+
+# Domain imports
+
+When importing from **`core_framework/domains/*`** in API or application code:
+
+## Allowed
+
+- Public symbols from domain **`__init__.py`** (models, enums, constants, outcomes).
+- Services from **`dependencies.py`** (e.g. **`user_service`**).
+
+## Prohibited
+
+- Typed or base **domain exceptions** in API/application — use **`application.shared.exceptions`**.
+- Direct imports from internal modules (`models`, `enums`, `repository`, `service`, `exceptions`).
+
+```python
+# ✅
+from core_framework.domains.user import Profile, UserRole
+from core_framework.domains.user.dependencies import user_service
+
+# ❌
+from core_framework.domains.post import PostNotFoundException
+from core_framework.domains.user.models import Profile
+```
+
+## Export policy
+
+Export from **`__init__.py`** only what outer layers need. Typed exceptions stay internal; export **only** **`BaseXxxException`** per domain for inheritance typing — not for per-domain HTTP handlers. **`DomainValidationError`** lives in **`domains/exceptions.py`** (core handler wiring only).
+
+To see what a domain exports, check its **`__init__.py`** **`__all__`**.
+
+## After a domain call
+
+1. Return **`None`** or empty when the use case allows.
+2. Raise an **application** exception when HTTP must signal failure.
+3. Extend the domain service API to absorb typed exceptions internally.
+
+Application code never imports repositories. Exception boundary details: **`error-boundary.mdc`**.

core_framework-2.1.0/.cursor/rules/domain-input-guards.mdc

@@ -0,0 +1,32 @@
+---
+description: Where to place input guards—API validation vs domain service vs repository vs database
+globs:
+  - core_framework/domains/**/service.py
+  - core_framework/domains/**/repository.py
+---
+
+# Domain input guards
+
+Use layered checks:
+
+- **API/Pydantic**: client contract, **422**, OpenAPI accuracy. See **`api-validation.mdc`**.
+- **Domain service**: primary business preconditions for all callers (HTTP, workers, scripts).
+- **Repository**: thin SQL/data access; only rare SQL-specific safety checks.
+- **Database**: mandatory integrity failsafe, not the normal invalid-input UX path.
+
+## Service policy
+
+- Enforce cheap, clear domain preconditions before persistence: empty batches, pagination bounds, non-negative counts, non-blank required strings, meaningless argument combinations.
+- Prefer early return when safe behavior is obvious.
+- Use **`DomainValidationError`** for caller mistakes that must not become 500; HTTP maps it to generic 400 per **`error-boundary.mdc`**.
+- Typed domain exceptions remain internal control flow; application translates before HTTP.
+
+Use shared helpers in **`core_framework.domains.utils`** (`require_non_blank*`, `validate_pagination_*`, `require_positive_int`) rather than repeating validation logic.
+
+## Repository policy
+
+- Do not duplicate service guards in repositories.
+- Do not use repositories as the main home for product rules.
+- Keep CHECK/NOT NULL/FK/UNIQUE constraints where they express truth in the data model; service checks do not replace them.
+
+When refactoring, move guards toward the service instead of growing repository-only validation.

core_framework-2.1.0/.cursor/rules/error-boundary.mdc

@@ -0,0 +1,55 @@
+---
+description: HTTP error boundaries — application vs domain exceptions, handlers, anti-enumeration
+globs:
+  - core_framework/core/exception_handlers/**/*.py
+  - core_framework/application/**/*_service.py
+  - core_framework/api/**/router.py
+  - core_framework/domains/**/exceptions.py
+---
+
+# Error boundary
+
+Platform contract: **`docs/platform/client-error-visibility.md`**. Domain imports: **`domain-imports.mdc`**.
+
+## Layers
+
+| Layer | Outward errors | HTTP |
+|-------|----------------|------|
+| **Application** | **`application.shared.exceptions`** | Handlers map type → status + `detail` |
+| **Domain typed** | Internal — not imported by API/application | No typed handlers |
+| **Domain `BaseXxxException`** | Handler catch-all only | **500** if leaked |
+| **API** | Pydantic | **422** |
+
+## Application and domain
+
+- Application **must not** import or raise typed domain exceptions. Signal via **`None`**, empty collections, or **`application.shared.exceptions`**.
+- Typed domain exceptions inherit domain **`BaseXxxException`** → **`BaseDomainException`**. Export **only** **`BaseXxxException`** from domain **`__init__.py`**, not typed subclasses.
+- **`DomainValidationError`** → dedicated **400** handler + **`GENERIC_BAD_REQUEST_DETAIL`**; do not put internal reason in HTTP **`detail`**.
+- Leaked typed domain exception → **`BaseDomainException`** handler → **500** + **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`**.
+
+## Handler registration
+
+- Use **`register_exception_handler`** from **`core_framework.core.exception_handlers.common`** — not raw **`app.add_exception_handler`** elsewhere.
+- **`setup.py`**: application types (specific before any base), **`DomainValidationError`**, one **`BaseDomainException`** leak handler, then **`Exception`** unmapped.
+- No per-domain handler modules for typed exceptions. Handlers translate only — no business logic or repository calls.
+- Do not log **error** for expected application 4xx; **`DomainValidationError`** at **warning**/**info**.
+
+## Catalog constants
+
+**`GENERIC_BAD_REQUEST_DETAIL`** (400), **`GENERIC_NOT_FOUND_DETAIL`** (404), **`GENERIC_FORBIDDEN_DETAIL`** (403), **`GENERIC_CONFLICT_DETAIL`** (409), ingest 413/415, **`GENERIC_INTERNAL_SERVER_ERROR_DETAIL`** (500).
+
+## Anti-enumeration (public routes)
+
+- Read-by-id: missing / hidden / withheld → same status + **`GENERIC_NOT_FOUND_DETAIL`** where flow docs align.
+- Idempotent writes on unknown ids → **204** without leaking existence. Empty list pages are OK.
+- Admin/internal routes may differ when documented. Intentional existence-check endpoints are separate product surface.
+
+## Validation order
+
+User-fixable input shape → API schemas (**422**). Domain backstops → **`DomainValidationError`** → generic **400**.
+
+## Logging
+
+Do not **`logger.error`** at every domain **`raise`**.
+
+Apply to new handlers and touched raise sites unless the task scopes repo-wide migration.

core_framework-2.1.0/.cursor/rules/flow-documentation.mdc

@@ -0,0 +1,15 @@
+---
+description: Flow docs describe user-facing API behavior only — no implementation code
+globs:
+  - docs/domains/**/*.md
+alwaysApply: false
+---
+
+# Flow documentation
+
+Flow docs under **`docs/domains/{domain}/`** describe **client-visible API behavior**, not implementation.
+
+- **Include**: endpoints, auth, request/response fields (text, not JSON examples), errors, idempotency, side effects.
+- **Exclude**: Python/SQL snippets, function names, layer internals, schema DDL — see **`no-code-in-docs.mdc`**.
+
+When creating or rewriting flow docs, use the **write-flow-doc** skill and match existing docs (e.g. **`profile.md`**, **`restrictions.md`**).

core_framework-2.1.0/.cursor/rules/layer-boundaries.mdc

@@ -0,0 +1,24 @@
+---
+description: Enforce API, worker, application, and domain layer responsibilities
+globs:
+  - core_framework/api/**/*.py
+  - core_framework/worker/**/*.py
+  - core_framework/application/**/*.py
+  - core_framework/domains/**/*.py
+---
+
+# Layer boundaries
+
+Dependencies point inward: **API/worker → application → domain**. Never reverse.
+
+- **API**: HTTP adapter only; shared orchestration belongs in application.
+- **Worker**: schedules/tasks/job handlers; call application services.
+- **Application**: transport-agnostic orchestration; no FastAPI/Starlette types.
+- **Domain**: business rules, models, repositories, services; no API/worker/application imports.
+
+## Cross-layer rules
+
+- Worker code must not import `core_framework.domains` directly, except documented housekeeping cron handlers that call a configured domain facade.
+- Domain code imports global infrastructure only in `dependencies.py`.
+- Repositories are Postgres-only and must not query other domains' schemas. See **`repository-schema-isolation`**.
+- Non-SQL I/O uses domain ports/components plus infrastructure adapters. See **`domain-services-and-adapters`**.

{core_framework-2.0.0 → core_framework-2.1.0}/.cursor/rules/no-code-in-docs.mdc

@@ -12,7 +12,7 @@ Documentation under **`docs/`** must not carry **implementation** snippets that
 
 - Python class/function definitions or examples
 - **SQL for data access or mutation** — `SELECT`, `INSERT`, `UPDATE`, `DELETE`, `MERGE`, CTE-heavy reports, cleanup queries, etc. (describe behavior in prose or name the operation; do not paste DML/query text)
-- Shell commands
+- Shell commands — **except** in deployment runbooks under **`docs/deployments/`** (see *Exceptions* below)
 - Pseudocode that mimics real code syntax
 - Inline backticked references to internal function/method/class names when prose suffices (prefer describing behavior)
 
@@ -25,6 +25,11 @@ Documentation under **`docs/`** must not carry **implementation** snippets that
 - Plain-text lifecycle diagrams (arrows, boxes)
 - File/directory tree layouts (plain text or a neutral fence such as `text` if helpful)
 
+## Exceptions
+
+- **Deployment runbooks** under **`docs/deployments/`** (setup guides, deploy/release playbooks, SSH/image-server guides) may include fenced **`bash`** shell blocks. These are operator instructions for interactive server setup, not implementation that drifts from source; copy-paste commands are the practical content. This exemption does **not** extend to **`docs/deployments/*-design.md`** design docs, which follow the general rules above.
+- **Design docs** under **`docs/platform/`** and **`docs/library/`** (and **`docs/deployments/*-design.md`**) follow the general allow/exclude lists — DDL is allowed, DML and Python are not. Flow docs under **`docs/domains/**`** are stricter: see **`flow-documentation.mdc`** (no DDL, no JSON request bodies, fields described as text/tables).
+
 ## Rationale
 
-Implementation snippets in docs drift from source. **HTTP listings** stay stable as the public contract. **DDL** documents intended physical shape. **DML** and **application code** belong in migrations and modules.
+Implementation snippets in docs drift from source. **HTTP listings** stay stable as the public contract. **DDL** documents intended physical shape. **DML** and **application code** belong in migrations and modules. Deployment runbooks are operator-facing setup instructions where shell commands are the deliverable, not source-bound implementation.

{core_framework-2.0.0 → core_framework-2.1.0}/.cursor/rules/postgres-config-conventions.mdc

@@ -1,6 +1,12 @@
 ---
 description: Postgres write/read config and wiring conventions
-alwaysApply: true
+globs:
+  - core_framework/core/settings.py
+  - core_framework/core/runtime.py
+  - config.toml
+  - config.toml.template
+  - docs/deployments/**/*.md
+alwaysApply: false
 ---
 
 # Postgres Config Conventions

core_framework-2.1.0/.cursor/rules/strong-reads.mdc

@@ -0,0 +1,37 @@
+---
+description: Strong read policy and repository naming for read-after-write consistency
+globs:
+  - core_framework/domains/**/repository.py
+  - core_framework/domains/**/service.py
+  - core_framework/domains/**/dependencies.py
+  - core_framework/application/**/*_service.py
+---
+
+# Strong reads
+
+## Policy
+
+- **Read-after-write** in the same HTTP request or worker job → **strong** read (required). Refetch with `strong_read_database`, `*_strong` repository methods, or service accessors that call them.
+- **Decision-critical guards** where stale data can cause incorrect branching → **strong** read (required). These are reads performed to decide a branch (for example pre-write existence, role, or state checks that determine whether a write runs or which outcome is returned), even when there is no immediate prior write in the flow. See the "Read Consistency (Strong vs Normal Reads)" ADR.
+- **All other strong-read usage** (e.g., list/browse freshness) → opt-in unless the user explicitly requested it in the task.
+- If a flow writes then reads and only a normal-read API exists, add or extend the `*_strong` path and call it from that flow.
+- Repositories accept `strong_read_database: Postgres` on `__init__` for wiring symmetry even when unused.
+
+## Repository pattern
+
+- Normal reads: explicit methods (e.g. `select_appeal`) using `read_database`.
+- Strong reads: separate methods only where needed (e.g. `select_appeal_strong`) using `strong_read_database`.
+- Share one private helper that accepts a database handle — do not duplicate SQL or mapping.
+- If only strong-read behavior is needed today, use a single method with `_strong` in the name.
+- Service accessors that call strong repository methods should also include `_strong`.
+
+```python
+# Preferred
+async def select_appeal(self, *, appeal_id: int) -> Appeal:
+    return await self._select_appeal_with_database(appeal_id=appeal_id, database=self.read_database)
+
+async def select_appeal_strong(self, *, appeal_id: int) -> Appeal:
+    return await self._select_appeal_with_database(appeal_id=appeal_id, database=self.strong_read_database)
+```
+
+Keep consistency decisions in services/use-case orchestration, not hidden in unrelated call paths.

{core_framework-2.0.0 → core_framework-2.1.0}/.cursor/rules/structured-logging.mdc

@@ -1,6 +1,8 @@
 ---
 description: Use concise English sentences for structlog event strings
-alwaysApply: true
+globs:
+  - core_framework/**/*.py
+alwaysApply: false
 ---
 
 # Structured logging (structlog)

{core_framework-2.0.0 → core_framework-2.1.0}/.cursor/skills/add-domain/SKILL.md

@@ -11,7 +11,18 @@ This skill covers **scaffolding only**: settings, a full **Alembic directory lay
 
 It does **not** cover the API layer or tests — handle those separately following the existing rules.
 
-Follow `implementation-workflow` (`/.cursor/rules/implementation-workflow.mdc`): one step per response, wait for review.
+Follow the **implement-feature** skill: one step per response, wait for review.
+
+## Capability-only domain (no Postgres schema)
+
+Not every domain owns persistence. A **capability-only** domain wraps a non-SQL capability (for example `auth`, which wraps Firebase Admin via `domains/auth/ports/`, `domains/auth/service.py`, and `core_framework/infrastructure/firebase/`). For those, **skip** schema config, the Alembic tree, and `ALEMBIC_DOMAINS` entirely — no `schema_<domain>` in `PostgresSchemasConfig` / `[postgres_schemas]`, no `alembic/<domain>/`, no repository. Scaffold only:
+
+- `domains/<domain>/{__init__.py, exceptions.py, models.py, ports/, service.py, dependencies.py}`
+- A port (`<Name>Port`) describing the capability, a facade `*Service` over it, and an adapter under `core_framework/infrastructure/<domain>/` wired in `dependencies.py` — see `docs/platform/domain-services-and-adapters.md` (Auth section) for the layout.
+- Export only `Base<Domain>Exception` + public models from `__init__.py`; keep the facade service in `dependencies.py`.
+- Wire `configure_<domain>_dependencies()` in `application/bootstrap.py` (no `runtime` needed when there is no Postgres handle).
+
+Use this branch when the user says the domain is "capability-only", "no database", or names an external SDK/service. Otherwise proceed with the persistence-domain steps below.
 
 ## Inputs
 
@@ -109,7 +120,7 @@ A single `class <Domain>Repository:` whose **`__init__`** takes `(write_postgres
 
 A single `class <Domain>Service:` whose **`__init__`** takes `<Domain>Repository` and stores it on a **private** attribute (e.g. `_repository`). **No other methods.** No FastAPI/Starlette imports. No caller-context names per `domain-caller-context`.
 
-When real behavior is added later, apply `repository-read-consistency` (`/.cursor/rules/repository-read-consistency.mdc`) for reads and `_strong` naming.
+When real behavior is added later, apply **strong-reads** (`.cursor/rules/strong-reads.mdc`) for reads and `_strong` naming.
 
 If the bounded context needs filesystem, HTTP, or SSH, add **ports/adapters** or extra domain collaborators per `docs/platform/domain-services-and-adapters.md` — do not put that I/O in `repository.py`.
 
@@ -199,7 +210,7 @@ Do this in a **separate step/PR** when you have DDL to apply.
 
 ## Reminders
 
-- One step per response, wait for review (`implementation-workflow`).
+- One step per response, wait for review (**implement-feature** skill).
 - Domain imports follow `domain-imports`; do not import API/application from domain.
 - Never name domain symbols by caller (`Admin*`, `Api*`, `Worker*`) per `domain-caller-context`.
-- When adding real repository methods later, follow `repository-read-consistency` (`_strong` naming where applicable).
+- When adding real repository methods later, follow **strong-reads** (`_strong` naming where applicable).

core_framework-2.1.0/.cursor/skills/code-review/SKILL.md

@@ -0,0 +1,34 @@
+---
+name: code-review
+description: Review code for quality, architecture compliance, and best practices. Use when the user asks for a code review, audit, or review.
+---
+
+# Code Review
+
+## Output format (required)
+
+**Actionable findings only:**
+
+- Bugs, wrong behavior, improvements, optimizations, doc/code contradictions, parallel implementation drift (sibling flows that diverge without documented reason).
+- Prioritize by severity with file context and fix direction.
+- **Do not** praise, summarize strengths, or pad with checklist pass narratives.
+- One-line scope is fine. If nothing is wrong, say so in one sentence.
+
+Do **not** flag documented accepted trade-offs in **`docs/platform/architecture-decisions.md`** unless the implementation violates them.
+
+## Workflow
+
+1. Read **`docs/platform/layers-and-boundaries.md`**, **`conventions.md`**, and **`architecture-decisions.md`** for the reviewed scope.
+1. Apply **scoped rules** (`.cursor/rules/*.mdc`) matching files under review — especially **`error-boundary`**, **`domain-imports`**, **`api-layer`**, **`application-layer`**, **`strong-reads`**.
+1. Report findings only — no filler.
+
+## Quick checks
+
+- Application services: no HTTP types, no domain exceptions, no Pydantic return types, one-line docstrings.
+- API: thin routers, validation in schemas, orchestration in application — **fastapi** skill + **`api-layer`** / **`api-validation`** / **`error-boundary`** rules.
+- Domain: imports only via **`__init__.py`** / **`dependencies`** from outer layers; no caller-context names (**`domain-caller-context`**).
+- Read-after-write refetches use **`*_strong`** where applicable.
+
+## Parallel drift
+
+Flag sibling modules with the same job but different structure (async layout, cleanup order, error/idempotency contracts) when docs do not explain the difference.

core_framework-2.1.0/.cursor/skills/fastapi

@@ -0,0 +1 @@
+../../.agents/skills/fastapi