core-framework 1.6.0__tar.gz → 1.8.0__tar.gz

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/api-layer.mdc

@@ -23,7 +23,7 @@ The API layer is an HTTP adapter, not a business-logic layer.
 
 ## Route decorators (OpenAPI)
 
-- Do **not** set **`summary=`** or **`description=`** on **`@router.get`**, **`post`**, **`patch`**, **`put`**, **`delete`**, or **`APIRoute`-style** registrations. Rely on paths, handler names, **`response_model`**, and Pydantic schemas. Do **not** add route **docstrings** for the same purpose either (see **`no-docstrings`**).
+- Do **not** set **`summary=`** or **`description=`** on **`@router.get`**, **`post`**, **`patch`**, **`put`**, **`delete`**, or **`APIRoute`-style** registrations. Rely on paths, handler names, **`response_model`**, and Pydantic schemas. Do **not** add route **docstrings** for the same purpose either.
 
 ## Response Models
 

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/api-reference-docs.mdc

@@ -1,12 +1,12 @@
 ---
-description: docs/api.md is a minimal API index only
+description: docs/library/api.md is a minimal API index only
 globs:
-  - docs/api.md
+  - docs/library/api.md
 ---
 
-# API Reference (docs/api.md)
+# API Reference (docs/library/api.md)
 
-`docs/api.md` is strictly for **quick viewing** of available APIs. It is an index, not detailed documentation.
+`docs/library/api.md` is strictly for **quick viewing** of available APIs. It is an index, not detailed documentation.
 
 ## Format
 
@@ -28,4 +28,4 @@ globs:
 - Any prose or bullet lists
 - Detailed behavior notes
 
-For detailed API behavior, create or update flow documentation in `docs/flows/` instead.
+For detailed API behavior, create or update flow documentation in `docs/domains/` instead.

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/application-layer.mdc

@@ -77,3 +77,7 @@ async def retrieve_my_username_suggestions(...) -> list[UsernameSuggestion]: ...
 - Input validation (`validate_user_id`, `validate_report_id`, etc.) belongs in schemas
 - Services do NOT raise `RequestValidationError` or import from `fastapi.exceptions`
 - Routers call `validate_*` from schemas before invoking services
+
+## Docstrings
+
+Application functions get a **one-line** docstring (what it does). No `Args` / `Returns` / `Raises` — see **`docstrings.mdc`**.

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/database-triggers.md

@@ -178,7 +178,7 @@ If you ask for a trigger for business logic, I should:
 
 ## Related Documentation
 
-- `docs/database-triggers.md` - **Catalog of all triggers** (update when adding new triggers)
-- `docs/conventions.md` - Database Triggers section
-- `docs/architecture-decisions.md` - Triggers Only for Audit/History
-- `docs/flows/users/change_history.md` - Example of proper trigger usage
+- `docs/platform/database-triggers.md` - **Catalog of all triggers** (update when adding new triggers)
+- `docs/platform/conventions.md` - Database Triggers section
+- `docs/platform/architecture-decisions.md` - Triggers Only for Audit/History
+- `docs/domains/users/change_history.md` - Example of proper trigger usage

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

@@ -0,0 +1,81 @@
+---
+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** depends on which layer owns the symbol. Type hints and keyword-only signatures carry parameter detail in application code; domain and infrastructure document the contract at the boundary.
+
+## Application layer (`core_framework/application/`)
+
+**One short sentence** — what the function does. No `Args`, `Returns`, or `Raises` sections.
+
+```python
+# ✅ Preferred
+async def enqueue_delete_superseded_banner_finals(*, asset_id: str) -> None:
+    """Enqueue cleanup of published finals for a replaced banner asset."""
+    ...
+
+# ❌ Avoid — too heavy for application orchestration
+async def enqueue_delete_superseded_banner_finals(...):
+    """Enqueue cleanup of published finals for a replaced banner asset.
+
+    Args:
+        asset_id: ...
+    Returns:
+        ...
+    """
+```
+
+Applies to **public and private** helpers in application modules. When you touch a function in an application file, use the simple style.
+
+## Domain layer (`core_framework/domains/`)
+
+**Full docstring** on public service, repository, component, and port methods that implement or define behavior:
+
+- Opening summary (one or two sentences)
+- **`Args:`** — keyword-only parameters and meaning
+- **`Returns:`** — when the return value is not obvious from the type alone
+- **`Raises:`** — domain exceptions and validation errors callers should handle
+
+Skip `Raises` only when the method truly cannot raise beyond programming errors. Trivial private helpers may stay undocumented; **exported and orchestration paths** get the full treatment.
+
+```python
+# ✅ Preferred (domain service)
+async def insert_avatar_staging_registry(...) -> AvatarStagingRegistryEntry:
+    """Record a new avatar staging registry row before blob upload completes.
+
+    Args:
+        asset_id: Unique avatar asset identifier.
+        owner_user_id: User who owns the avatar.
+        staging_filename: Basename of the staging blob on disk.
+
+    Returns:
+        Persisted registry entry including staging metadata.
+
+    Raises:
+        DomainValidationError: If required string fields are blank or ``staging_filename``
+            is unsafe.
+    """
+```
+
+Repositories: document query semantics (filtering, empty results, strong vs normal read) in the summary or **`Returns:`** when non-obvious.
+
+## Infrastructure layer (`core_framework/infrastructure/`)
+
+Same as **domain** — adapters implement ports and perform I/O. Document inputs, outputs, failure modes (`Raises:` or raised infrastructure exceptions), and non-obvious side effects (network, disk, SSH).
+
+## When editing
+
+- **New** application functions → simple docstring.
+- **New** domain/infrastructure public methods → full docstring.
+- When you **change** a function in a file, bring **that function's** docstring in line with its layer; do not repo-wide migrate unrelated symbols unless the task asks for it.
+
+## Out of scope
+
+- **API routers and schemas** — no docstring requirement from this rule (OpenAPI and Pydantic carry the contract).
+- **Workers** (`core_framework/worker/`) — thin task/schedule wrappers follow **application** style; logic belongs in application services.

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/domain-services-and-adapters.mdc

@@ -7,7 +7,7 @@ globs:
 
 # Domain Services and Adapters
 
-See **`docs/domain-services-and-adapters.md`** for the full model. Apply when adding or changing domain packages and application orchestration.
+See **`docs/platform/domain-services-and-adapters.md`** for the full model. Apply when adding or changing domain packages and application orchestration.
 
 ## Application = orchestration
 
@@ -45,3 +45,7 @@ See **`docs/domain-services-and-adapters.md`** for the full model. Apply when ad
 - **Layout:** `domains/media/shared/`, `avatar/ports/`, `avatar/components/`, `AvatarService`.
 - **Avatar:** `media_deps.avatar_service` only (not individual components).
 - **Cross-domain:** `avatar_ingest_sequence` / profile `avatar_id` via **user** domain; orchestration in `application/media/avatar_service`.
+
+## Docstrings
+
+Domain services, repositories, ports, and components use **full** docstrings (`Args`, `Returns`, `Raises` where applicable). Application orchestration uses **one-line** summaries — see **`docstrings.mdc`**.

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/flow-documentation.mdc

@@ -1,7 +1,7 @@
 ---
 description: Flow docs describe user-facing API behavior. No JSON examples, no implementation details.
 globs:
-  - docs/flows/**/*.md
+  - docs/domains/**/*.md
 ---
 
 # Flow Documentation Rule
@@ -21,7 +21,7 @@ Create a new flow document when:
 
 ## File Location and Naming
 
-- **Location**: `docs/flows/{domain}/{feature}.md`
+- **Location**: `docs/domains/{domain}/{feature}.md`
 - **Naming**: Use lowercase with underscores (e.g., `account_deletion.md`, `change_history.md`)
 - **Domain folders**: `auth`, `users`, `moderation`, `comments`, etc.
 
@@ -310,8 +310,8 @@ All endpoints require authentication via Firebase ID token with admin role.
 
 When flow docs reference implementation details:
 
-- **Architecture decisions**: Link to `docs/architecture-decisions.md`
-- **API reference**: Already covered in `docs/api.md`
+- **Architecture decisions**: Link to `docs/platform/architecture-decisions.md`
+- **API reference**: Already covered in `docs/library/api.md`
 - **Database schema**: Should be in migration files, not flow docs
 - **Code structure**: Should be in code comments or architecture docs
 

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/henry-cursor-rules-sync.mdc

@@ -38,14 +38,13 @@ When a rule encodes a new convention, check whether **`docs/`** in both repos ne
 
 Sync to henry when core changes:
 
-- **`docs/architecture.md`** → henry **`docs/architecture.md`** (Henry preamble + synced body; adapt `docs/flows/…` links in henry to **`docs/core-product-docs.md`**)
-- **`docs/domain-services-and-adapters.md`** → update henry host summary; core remains canonical
-- **`docs/conventions.md`**, **`docs/architecture-decisions.md`** → synced copies in henry when they exist in core (adapt flow-doc links in henry)
-- **`docs/deployment/`**, **`docs/media-upload-pipeline-design.md`** → sync when shared deploy/media docs change (adapt flow links in henry)
+- **`docs/platform/`** — synced platform docs (layers, conventions, ADRs, adapters, etc.); adapt `docs/domains/…` links in henry to **`docs/core-product-docs.md`**
+- **`docs/library/`** — canonical in core-framework only; henry points to it from **`docs/core-product-docs.md`** (do not add **`docs/library/`** under henry-backend)
+- **`docs/deployments/`**, **`docs/domains/media/upload-pipeline-design.md`** → sync when shared deploy/media docs change (adapt flow links in henry)
 
-**Do not** mirror **`docs/flows/`** into henry-backend. Henry maintains **`docs/core-product-docs.md`** as a pointer/index to core product documentation.
+**Do not** mirror **`docs/domains/`** into henry-backend. Henry maintains **`docs/core-product-docs.md`** as a pointer/index to core product documentation.
 
-Do not overwrite henry-only docs (e.g. **`docs/henry-users-architecture.md`**, calculator architecture, **`docs/core-product-docs.md`**, **`docs/flows/henry/`**).
+Do not overwrite henry-only docs (e.g. **`docs/domains/henry/`**, **`docs/core-product-docs.md`**).
 
 ## User-triggered sync
 

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/rules/implementation-workflow.mdc

@@ -38,7 +38,7 @@ After the user accepts the API layer (or if there was no API layer):
 
 - Implement the **Repository** for the domain layer (Postgres only).
 - Include the **domain model** if data is retrieved from the database.
-- If the feature needs non-SQL I/O (filesystem, HTTP, SSH), add **ports** in the domain and **adapter implementations** under `core_framework/infrastructure/<domain>/` per `docs/domain-services-and-adapters.md`—not in the repository.
+- If the feature needs non-SQL I/O (filesystem, HTTP, SSH), add **ports** in the domain and **adapter implementations** under `core_framework/infrastructure/<domain>/` per `docs/platform/domain-services-and-adapters.md`—not in the repository.
 - Wait for the user to review and accept before proceeding.
 
 ## 4. Service and Application Layer

core_framework-1.8.0/.cursor/rules/karpathy-guidelines.mdc

@@ -0,0 +1,70 @@
+---
+description: Behavioral guidelines to reduce common LLM coding mistakes. Use when writing, reviewing, or refactoring code to avoid overcomplication, make surgical changes, surface assumptions, and define verifiable success criteria.
+alwaysApply: true
+---
+
+# Karpathy behavioral guidelines
+
+Behavioral guidelines to reduce common LLM coding mistakes. Merge with project-specific instructions as needed.
+
+**Tradeoff:** These guidelines bias toward caution over speed. For trivial tasks, use judgment.
+
+## 1. Think Before Coding
+
+**Don't assume. Don't hide confusion. Surface tradeoffs.**
+
+Before implementing:
+- State your assumptions explicitly. If uncertain, ask.
+- If multiple interpretations exist, present them - don't pick silently.
+- If a simpler approach exists, say so. Push back when warranted.
+- If something is unclear, stop. Name what's confusing. Ask.
+
+## 2. Simplicity First
+
+**Minimum code that solves the problem. Nothing speculative.**
+
+- No features beyond what was asked.
+- No abstractions for single-use code.
+- No "flexibility" or "configurability" that wasn't requested.
+- No error handling for impossible scenarios.
+- If you write 200 lines and it could be 50, rewrite it.
+
+Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify.
+
+## 3. Surgical Changes
+
+**Touch only what you must. Clean up only your own mess.**
+
+When editing existing code:
+- Don't "improve" adjacent code, comments, or formatting.
+- Don't refactor things that aren't broken.
+- Match existing style, even if you'd do it differently.
+- If you notice unrelated dead code, mention it - don't delete it.
+
+When your changes create orphans:
+- Remove imports/variables/functions that YOUR changes made unused.
+- Don't remove pre-existing dead code unless asked.
+
+The test: Every changed line should trace directly to the user's request.
+
+## 4. Goal-Driven Execution
+
+**Define success criteria. Loop until verified.**
+
+Transform tasks into verifiable goals:
+- "Add validation" → "Write tests for invalid inputs, then make them pass"
+- "Fix the bug" → "Write a test that reproduces it, then make it pass"
+- "Refactor X" → "Ensure tests pass before and after"
+
+For multi-step tasks, state a brief plan:
+```
+1. [Step] → verify: [check]
+2. [Step] → verify: [check]
+3. [Step] → verify: [check]
+```
+
+Strong success criteria let you loop independently. Weak criteria ("make it work") require constant clarification.
+
+---
+
+**These guidelines are working if:** fewer unnecessary changes in diffs, fewer rewrites due to overcomplication, and clarifying questions come before implementation rather than after mistakes.

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/skills/add-domain/SKILL.md

@@ -111,7 +111,7 @@ A single `class <Domain>Service:` whose **`__init__`** takes `<Domain>Repository
 
 When real behavior is added later, apply `repository-read-consistency` (`/.cursor/rules/repository-read-consistency.mdc`) for reads and `_strong` naming.
 
-If the bounded context needs filesystem, HTTP, or SSH, add **ports/adapters** or extra domain collaborators per `docs/domain-services-and-adapters.md` — do not put that I/O in `repository.py`.
+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`.
 
 ### `__init__.py`
 
@@ -175,7 +175,7 @@ Worker `startup` and API `init_app` already call `configure_application_dependen
 
 - `core_framework/domains/<domain>/README.md` — domain exists in code; `alembic/<domain>/` exists with **empty** `versions/`; **not** in `ALEMBIC_DOMAINS` until first revision; **no** DB schema object until a migration creates it.
 - `CHANGELOG.md` — `### Added` under `[Unreleased]` for domain package, `schema_<domain>`, and Alembic skeleton path (optional). **Do not** list `ALEMBIC_DOMAINS` or revision ids until the first migration lands.
-- Update `docs/architecture.md` and `docs/package-api.md` only when the domain exposes anything to the public surface.
+- Update `docs/library/overview.md` and `docs/library/package-api.md` only when the domain exposes anything to the public surface.
 
 ## Follow-up: first revision + enroll in `cf-alembic`
 

{core_framework-1.6.0 → core_framework-1.8.0}/.cursor/skills/code-review/SKILL.md

@@ -35,17 +35,17 @@ Apply **`.cursor/rules/code-review-output.mdc`**. The user wants **actionable fi
 
 Read these files **before** proceeding with the review:
 
-1. **`docs/architecture.md`** – Domain boundaries, prohibited practices, and dependency rules
-1. **`docs/domain-services-and-adapters.md`** – Application orchestration vs domain services, ports/adapters, multiple collaborators per bounded context
-1. **`docs/conventions.md`** – Coding conventions, domain rules, caching, Redis, exception handling, API layer rules
-1. **`docs/architecture-decisions.md`** – Intentional design choices; do not flag these as issues
-1. **`.cursor/rules/api-layer.mdc`**, **`.cursor/rules/application-layer.mdc`**, **`.cursor/rules/domain-services-and-adapters.mdc`**, **`.cursor/rules/domain-imports.mdc`**, **`.cursor/rules/domain-caller-context.mdc`** – Apply when reviewing API/application/domain code
+1. **`docs/platform/layers-and-boundaries.md`** – Domain boundaries, prohibited practices, and dependency rules
+1. **`docs/platform/domain-services-and-adapters.md`** – Application orchestration vs domain services, ports/adapters, multiple collaborators per bounded context
+1. **`docs/platform/conventions.md`** – Coding conventions, domain rules, caching, Redis, exception handling, API layer rules
+1. **`docs/platform/architecture-decisions.md`** – Intentional design choices; do not flag these as issues
+1. **`.cursor/rules/api-layer.mdc`**, **`.cursor/rules/application-layer.mdc`**, **`.cursor/rules/docstrings.mdc`**, **`.cursor/rules/domain-services-and-adapters.mdc`**, **`.cursor/rules/domain-imports.mdc`**, **`.cursor/rules/domain-caller-context.mdc`** – Apply when reviewing API/application/domain code
 
 ## Step 2: Key Context
 
 ### Architecture Decisions (do not flag as issues)
 
-- TOML as primary deploy artifact; environment variables can override (see `docs/architecture-decisions.md`)
+- TOML as primary deploy artifact; environment variables can override (see `docs/platform/architecture-decisions.md`)
 - `trusted_hosts=["*"]` in ProxyHeadersMiddleware (runs behind reverse proxy)
 - `-> Any` return types when `response_model` is specified
 - Silent `ForeignKeyViolationError` in `insert_user_block`
@@ -76,6 +76,7 @@ Verify the following. Also apply api-layer, application-layer, and domain-import
 
 ### Application Layer Services (`core_framework/application/**/*_service.py`)
 
+- [ ] **Docstrings** – One-line summary only; no `Args`/`Returns`/`Raises` (see `docstrings.mdc`)
 - [ ] **No HTTP handling** – No `HTTPException`, `RequestValidationError`, `BackgroundTasks`, or other FastAPI HTTP imports
 - [ ] **No Pydantic return types** – Services return `dict`, `list[dict]`, dataclasses, or plain types; routers use `response_model`
 - [ ] **Not found** – Return `None` or `Optional`; routers raise `HTTPException(404)` when appropriate

{core_framework-1.6.0 → core_framework-1.8.0}/.github/workflows/_deploy.yml

@@ -140,7 +140,7 @@ jobs:
             DOCKERHUB_USERNAME="${{ inputs.dockerhub_username }}"
             CONFIG_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/config.toml"
             FIREBASE_CONFIG_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/firebase_config.json"
-            AVATAR_STAGING_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/avatar-staging"
+            MEDIA_STAGING_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/media-staging"
             IMAGE_SERVER_SSH_KEY_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/image_server_ssh_key"
             IMAGE_SERVER_KNOWN_HOSTS_PATH="/home/${{ secrets.SERVER_USER }}/app_configs/core-framework/image_server_known_hosts"
 
@@ -148,21 +148,21 @@ jobs:
             DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
             CONFIG_PATH="$CONFIG_PATH" \
             FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
-            AVATAR_STAGING_PATH="$AVATAR_STAGING_PATH" \
+            MEDIA_STAGING_PATH="$MEDIA_STAGING_PATH" \
             IMAGE_SERVER_SSH_KEY_PATH="$IMAGE_SERVER_SSH_KEY_PATH" \
             IMAGE_SERVER_KNOWN_HOSTS_PATH="$IMAGE_SERVER_KNOWN_HOSTS_PATH" \
             docker compose -f "$COMPOSE_FILE" pull
 
-            echo "Preparing avatar staging directory and image server SSH key permissions"
-            mkdir -p "$AVATAR_STAGING_PATH"
+            echo "Preparing media staging directory and image server SSH key permissions"
+            mkdir -p "$MEDIA_STAGING_PATH"
             docker run --rm \
               --user root \
-              -v "$AVATAR_STAGING_PATH:/app/avatar-staging" \
+              -v "$MEDIA_STAGING_PATH:/app/media-staging" \
               -v "$IMAGE_SERVER_SSH_KEY_PATH:/app/image-server-ssh-key" \
               -v "$IMAGE_SERVER_KNOWN_HOSTS_PATH:/app/image-server-known-hosts" \
               --entrypoint "" \
               "$DOCKERHUB_USERNAME/core-framework:latest" \
-              sh -c 'mkdir -p /app/avatar-staging && chown -R appuser:appgroup /app/avatar-staging && chown appuser:appgroup /app/image-server-ssh-key && chmod 600 /app/image-server-ssh-key && chown appuser:appgroup /app/image-server-known-hosts && chmod 644 /app/image-server-known-hosts'
+              sh -c 'mkdir -p /app/media-staging && chown -R appuser:appgroup /app/media-staging && chown appuser:appgroup /app/image-server-ssh-key && chmod 600 /app/image-server-ssh-key && chown appuser:appgroup /app/image-server-known-hosts && chmod 644 /app/image-server-known-hosts'
 
             echo "Running database migrations (cf-alembic iterates core_framework.bundled_alembic.ALEMBIC_DOMAINS in order)"
             docker run --rm \
@@ -175,7 +175,7 @@ jobs:
             DOCKERHUB_USERNAME="$DOCKERHUB_USERNAME" \
             CONFIG_PATH="$CONFIG_PATH" \
             FIREBASE_CONFIG_PATH="$FIREBASE_CONFIG_PATH" \
-            AVATAR_STAGING_PATH="$AVATAR_STAGING_PATH" \
+            MEDIA_STAGING_PATH="$MEDIA_STAGING_PATH" \
             IMAGE_SERVER_SSH_KEY_PATH="$IMAGE_SERVER_SSH_KEY_PATH" \
             IMAGE_SERVER_KNOWN_HOSTS_PATH="$IMAGE_SERVER_KNOWN_HOSTS_PATH" \
             docker compose -f "$COMPOSE_FILE" up -d \

{core_framework-1.6.0 → core_framework-1.8.0}/.gitignore

@@ -11,7 +11,7 @@ wheels/
 .env
 
 # Avatar ingest staging (local disk)
-avatar-staging/
+media-staging/
 
 # Logs
 logs/

{core_framework-1.6.0 → core_framework-1.8.0}/CHANGELOG.md

@@ -1,9 +1,48 @@
 # Changelog
 
-Notable changes to **core-framework** (import **`core_framework`**). Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is [SemVer](https://semver.org/spec/v2.0.0.html). Stable surface: **`docs/package-api.md`**.
+Notable changes to **core-framework** (import **`core_framework`**). Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); versioning is [SemVer](https://semver.org/spec/v2.0.0.html). Stable surface: **`docs/library/package-api.md`**.
 
 ## [Unreleased]
 
+## [1.8.0] - 2026-06-06
+
+### Added
+
+- **`[avatar].public_path_prefix`** and **`[banner].public_path_prefix`** — optional URL path segment in **`config.toml`** when avatar/banner finals are served under a subdirectory on a shared media host. Empty by default (dedicated product vhost docroot).
+
+- **Follow counts on profile surfaces:** **`GET /users/me/profile`**, **`PATCH /users/me/profile`**, and admin **`GET /admin/users/{user_id}`** profile payload include **`follower_count`** and **`following_count`** (same **user_stats** source as public profile). Follow/unfollow invalidates **`user_stats`** cache for both parties when the edge changes.
+
+- **HEIC/HEIF ingest (avatar and banner):** Allow **`image/heic`** and **`image/heif`** on profile image uploads; decode via **`pillow-heif`** before WebP variant encoding.
+
+- **Image ingest hardening:** Staging decode uses a **30s** timeout, **4096×4096** pixel cap, and Pillow decompression-bomb limits; published WebP finals omit embedded metadata.
+
+- **Structured mentions (posts and comments):** **`post_mentions`** / **`comment_mentions`** persistence; **`mentions`** on **POST** create, **PATCH** replace (omit unchanged, **`[]`** clears), and **GET** responses as **`UserReference`** list. **`mention` inbox notifications** remain **create-only**. Migrations **`post_add_post_mentions`**, **`comment_add_comment_mentions`**. See **`docs/domains/mentions/mentions_in_content.md`**.
+
+### Database
+
+- **Post** migration **`post_add_post_mentions`**; **comment** migration **`comment_add_comment_mentions`**. Run **`uv run cf-alembic`** before deploying.
+
+## [1.7.0] - 2026-06-01
+
+### Added
+
+- **Banner upload (v1):** **`POST /users/me/profile/banner`**, **`media.banner_staging_registry`** / **`banner_ingest_lease`**, worker jobs **`process_banner_asset_variants`** and **`delete_superseded_banner_finals`**, stale banner staging cron, shared **`[media].staging_root`**. **`PATCH /users/me/profile`** no longer accepts **`banner_id`**. See **`docs/domains/media/upload_pipeline.md`**, **`docs/domains/users/banner.md`**, and **`docs/domains/users/profile.md`**.
+
+### Changed
+
+- **Breaking (API):** Profile **`banner`** is now an object **`{ "url": "…", "fallback": "…" }`** instead of a single URL string. **`fallback`** is always the default banner URL for load-error UX.
+- **Breaking (hosts):** **`[avatar].staging_root`** removed; use **`[media].staging_root`** (**`MEDIA_STAGING_PATH`** / **`media-staging`**). Migrate existing host **`avatar-staging`** directories to **`media-staging`** on deploy.
+
+### Database
+
+- **Media** migration **`media_banner_staging_lease`**: **`banner_staging_registry`**, **`banner_ingest_lease`**.
+- **User** migration **`user_add_banner_ingest_sequences`**: **`banner_ingest_sequence`**, **`banner_applied_sequence`** on **`user_profiles`**.
+- Run **`uv run cf-alembic`** (or the host **`cf-alembic`** step) before deploying code that uses banner upload.
+
+### Documentation
+
+- **`docs/domains/users/banner.md`**, profile and upload-pipeline updates, **`docs/deployments/edge-upload-limits.md`** and **`Caddyfile.example`** — banner route body limit.
+
 ## [1.6.0] - 2026-05-27
 
 ### Changed
@@ -14,7 +53,7 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ### Added
 
-- **Avatar upload (v1):** **`POST /users/me/profile/avatar`**, **`media`** schema, worker variant processing, staging sweep cron, **`[avatar].staging_root`** config. See **`docs/flows/media/upload_pipeline.md`** and **`docs/flows/users/profile.md`**.
+- **Avatar upload (v1):** **`POST /users/me/profile/avatar`**, **`media`** schema, worker variant processing, staging sweep cron, **`[avatar].staging_root`** config. See **`docs/domains/media/upload_pipeline.md`** and **`docs/domains/users/profile.md`**.
 
 ### Fixed
 
@@ -23,7 +62,7 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ### Changed
 
-- **Breaking:** **`[image_server].known_hosts_path`** is required; **`SshAvatarFinalsPublisherAdapter`** verifies the image server SSH host key (no longer **`known_hosts=None`**). Deploy must provide **`IMAGE_SERVER_KNOWN_HOSTS`** and mount **`/app/image-server-known-hosts`** on the worker. See **`docs/deployment/image-server-ssh.md`**.
+- **Breaking:** **`[image_server].known_hosts_path`** is required; **`SshAvatarFinalsPublisherAdapter`** verifies the image server SSH host key (no longer **`known_hosts=None`**). Deploy must provide **`IMAGE_SERVER_KNOWN_HOSTS`** and mount **`/app/image-server-known-hosts`** on the worker. See **`docs/deployments/guides/image-server-ssh.md`**.
 - **Breaking:** **`[avatar].avatar_host_domain`** is **host-only** in **`config.toml`** and deploy secret **`AVATAR_HOST_DOMAIN`** (for example **`avatar.example.com`**, no **`https://`**). The application prepends **`https://`** when assembling public avatar URLs. Values that still include a scheme are normalized at load time.
 - **Breaking:** **`[banner]`** config aligns with **`[avatar]`**: **`banner_host_domain`** + **`default_banner_image`** (deploy secrets **`BANNER_HOST_DOMAIN`**, **`BANNER_DEFAULT_IMAGE`**) replace **`base_url`** / **`default_url`**. Hostname is host-only; public banner URLs derive **`https://`** in application code.
 
@@ -35,21 +74,21 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ### Documentation
 
-- **Avatar upload edge limits:** **`docs/deployment/edge-upload-limits.md`**, **`docs/deployment/Caddyfile.example`** — route-scoped reverse-proxy **`max_size`** (**6 MiB** recommended) for **`POST /users/me/profile/avatar`**; updated **`docs/flows/media/upload_pipeline.md`** and **`docs/flows/users/profile.md`**.
-- **Image server SSH:** **`docs/deployment/image-server-ssh.md`**, **`docs/deployment/image-server-known-hosts.example`** — production checklist for **`known_hosts_path`** and **`IMAGE_SERVER_KNOWN_HOSTS`**.
-- **`docs/flows/media/upload_pipeline.md`**: status and HTTP surface aligned with shipped v1 implementation.
-- **`docs/flows/users/profile.md`**: **`POST /users/me/profile/avatar`** flow; **`PATCH`** no longer documents **`avatar_id`** as planned.
-- **`docs/flows/users/avatar.md`**, **`docs/flows/users/change_history.md`**: avatar change path and ingest MIME notes updated.
-- **`docs/flows/users/avatar.md`**, **`docs/flows/users/profile.md`**: **`avatar_host_domain`** documented as host-only; public URLs derive **`https://`** in application code.
-- **`docs/domain-services-and-adapters.md`**: **`banner_host_domain`** / **`default_banner_image`** config shape documented alongside avatar.
+- **Avatar upload edge limits:** **`docs/deployments/edge-upload-limits.md`**, **`docs/deployments/examples/Caddyfile.example`** — route-scoped reverse-proxy **`max_size`** (**6 MiB** recommended) for **`POST /users/me/profile/avatar`**; updated **`docs/domains/media/upload_pipeline.md`** and **`docs/domains/users/profile.md`**.
+- **Image server SSH:** **`docs/deployments/guides/image-server-ssh.md`**, **`docs/deployments/examples/image-server-known-hosts.example`** — production checklist for **`known_hosts_path`** and **`IMAGE_SERVER_KNOWN_HOSTS`**.
+- **`docs/domains/media/upload_pipeline.md`**: status and HTTP surface aligned with shipped v1 implementation.
+- **`docs/domains/users/profile.md`**: **`POST /users/me/profile/avatar`** flow; **`PATCH`** no longer documents **`avatar_id`** as planned.
+- **`docs/domains/users/avatar.md`**, **`docs/domains/users/change_history.md`**: avatar change path and ingest MIME notes updated.
+- **`docs/domains/users/avatar.md`**, **`docs/domains/users/profile.md`**: **`avatar_host_domain`** documented as host-only; public URLs derive **`https://`** in application code.
+- **`docs/platform/domain-services-and-adapters.md`**: **`banner_host_domain`** / **`default_banner_image`** config shape documented alongside avatar.
 
 ## [1.4.0] - 2026-05-19
 
 ### Changed
 
-- **Breaking:** **`avatar`** on profile and related user responses is an object (**`size_128`**, **`size_500`**, **`fallback`**) instead of a single URL string. See **`docs/flows/users/avatar.md`**.
+- **Breaking:** **`avatar`** on profile and related user responses is an object (**`size_128`**, **`size_500`**, **`fallback`**) instead of a single URL string. See **`docs/domains/users/avatar.md`**.
 - **Breaking:** **`[avatar]`** config uses **`avatar_host_domain`** + **`default_avatar_image`** (deploy env **`AVATAR_HOST_DOMAIN`**, **`AVATAR_DEFAULT_IMAGE`**) instead of **`base_url`** / **`default_url`**.
-- **Typed PATCH payloads** — user (preferences, account, profile + admin profile), post, and comment PATCH routes map Pydantic requests to domain `*Update` types at the API boundary; no `model_dump(mode="json")` or dict partial-update payloads through application/domain/repository. See `docs/patch-update-typed-payload.md` and `docs/conventions.md` (*PATCH partial updates*).
+- **Typed PATCH payloads** — user (preferences, account, profile + admin profile), post, and comment PATCH routes map Pydantic requests to domain `*Update` types at the API boundary; no `model_dump(mode="json")` or dict partial-update payloads through application/domain/repository. See `docs/platform/patch-update-typed-payload.md` and `docs/platform/conventions.md` (*PATCH partial updates*).
 - Self-service profile PATCH invalidates **`USER_DETAIL`** only when **`display_name`** or **`avatar_id`** change (fields present in cached identity). **`profile_visibility`** is coerced to **`ProfileVisibility`** on repository read.
 
 ### Added
@@ -62,11 +101,11 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ### Documentation
 
-- **`docs/flows/users/avatar.md`**: multi-size **`avatar`** response shape and CDN URL convention.
-- **`docs/flows/media/upload_pipeline.md`**: upload pipeline design and v1 implementation reference.
-- **`docs/flows/users/profile.md`**: DOB on get/update flows and validation errors.
-- **`docs/flows/users/change_history.md`**: profile **`date_of_birth`** changes are not written to change history (audit trigger unchanged).
-- **`docs/patch-update-typed-payload.md`**: typed PATCH decisions and patterns for partial-update endpoints.
+- **`docs/domains/users/avatar.md`**: multi-size **`avatar`** response shape and CDN URL convention.
+- **`docs/domains/media/upload_pipeline.md`**: upload pipeline design and v1 implementation reference.
+- **`docs/domains/users/profile.md`**: DOB on get/update flows and validation errors.
+- **`docs/domains/users/change_history.md`**: profile **`date_of_birth`** changes are not written to change history (audit trigger unchanged).
+- **`docs/platform/patch-update-typed-payload.md`**: typed PATCH decisions and patterns for partial-update endpoints.
 
 ### Fixed
 
@@ -103,7 +142,7 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ### Documentation
 
-- Follow feature (HTTP, notifications, stats worker, mirrors, **`docs/follow-system-design.md`**, architecture decisions, domain READMEs, **`docs/api.md`**).
+- Follow feature (HTTP, notifications, stats worker, mirrors, **`docs/domains/users/follow-system-design.md`**, architecture decisions, domain READMEs, **`docs/library/api.md`**).
 
 ## [1.1.1] - 2026-04-24
 
@@ -119,7 +158,7 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ### Added
 
-- **`core-framework[testing]`** extra: pytest plugin (**`pytest11`** → **`core_framework.testing.plugin`**), **`TestConfig`**, session fixtures (Postgres, Redis, **`AsyncClient`**, migrations, Firebase helpers, optional SAQ). Parallel (**`pytest -n`**) coordination — see **`docs/testing-plugin-design.md`**. **`create_firebase_user_token`** helper.
+- **`core-framework[testing]`** extra: pytest plugin (**`pytest11`** → **`core_framework.testing.plugin`**), **`TestConfig`**, session fixtures (Postgres, Redis, **`AsyncClient`**, migrations, Firebase helpers, optional SAQ). Parallel (**`pytest -n`**) coordination — see **`docs/library/testing-plugin-design.md`**. **`create_firebase_user_token`** helper.
 
 ### Changed
 
@@ -127,11 +166,11 @@ Notable changes to **core-framework** (import **`core_framework`**). Format foll
 
 ### Documentation
 
-- **`docs/package-api.md`**, **`docs/core-framework-migration.md`**, **`README.md`**, **`docs/testing-plugin-design.md`** updated for testing and entrypoints.
+- **`docs/library/package-api.md`**, **`docs/library/core-framework-migration.md`**, **`README.md`**, **`docs/library/testing-plugin-design.md`** updated for testing and entrypoints.
 
 ## [1.0.0] - 2026-04-18
 
-First **SemVer-stable** release per **`docs/package-api.md`**.
+First **SemVer-stable** release per **`docs/library/package-api.md`**.
 
 ### Breaking
 
@@ -158,7 +197,7 @@ First **SemVer-stable** release per **`docs/package-api.md`**.
 
 ### Documentation
 
-- Mentions flow, **`GET /users/usernames/suggest`**, **`docs/api.md`**.
+- Mentions flow, **`GET /users/usernames/suggest`**, **`docs/library/api.md`**.
 
 ## [0.4.0] - 2026-03-26
 
@@ -180,7 +219,7 @@ First **SemVer-stable** release per **`docs/package-api.md`**.
 
 ### Documentation
 
-- **`README`**, **`docs/core-framework-migration.md`**, **`docs/package-api.md`**, **`docs/architecture.md`** (runtime / bootstrap).
+- **`README`**, **`docs/library/core-framework-migration.md`**, **`docs/library/package-api.md`**, **`docs/library/overview.md`** (runtime / bootstrap).
 
 ### Removed
 
@@ -190,7 +229,7 @@ First **SemVer-stable** release per **`docs/package-api.md`**.
 
 ### Added
 
-- **`init_app(settings)`**, **`create_task_worker(settings)`**, **`CoreRuntime`**, **`build_core_runtime`**, **`configure_application_dependencies`**, **`load_default_settings()`**, **`configure_core_runtime`**. **`docs/package-api.md`**.
+- **`init_app(settings)`**, **`create_task_worker(settings)`**, **`CoreRuntime`**, **`build_core_runtime`**, **`configure_application_dependencies`**, **`load_default_settings()`**, **`configure_core_runtime`**. **`docs/library/package-api.md`**.
 
 ### Changed
 
@@ -211,4 +250,6 @@ First **SemVer-stable** release per **`docs/package-api.md`**.
 [1.4.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.3.0...v1.4.0
 [1.5.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.4.0...v1.5.0
 [1.6.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.5.0...v1.6.0
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.6.0...HEAD
+[1.7.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.6.0...v1.7.0
+[1.8.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.7.0...v1.8.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.8.0...HEAD

{core_framework-1.6.0 → core_framework-1.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 1.6.0
+Version: 1.8.0
 Summary: Core framework package (import as core_framework)
 Project-URL: Homepage, https://github.com/NepNepFFXIV/core-framework
 Project-URL: Repository, https://github.com/NepNepFFXIV/core-framework
@@ -24,6 +24,7 @@ Requires-Dist: itsdangerous>=2.2.0
 Requires-Dist: logfire[asyncpg,fastapi,httpx,redis]>=4.32.1
 Requires-Dist: mashumaro[orjson]>=3.20
 Requires-Dist: orjson>=3.11.7
+Requires-Dist: pillow-heif>=1.3.0
 Requires-Dist: pillow>=12.2.0
 Requires-Dist: python-ulid>=3.1.0
 Requires-Dist: structlog>=25.5.0
@@ -87,7 +88,7 @@ def build_app(settings: HostSettings | None = None) -> FastAPI:
     return app
 ```
 
-From the host repository root, run **`uv run cf-alembic`**. See [core-framework-migration](docs/core-framework-migration.md).
+From the host repository root, run **`uv run cf-alembic`**. See [core-framework-migration](docs/library/core-framework-migration.md).
 
 ## Host pytest
 
@@ -115,4 +116,4 @@ def anyio_backend() -> str:
     return "asyncio"
 ```
 
-See [Package API — Testing](docs/package-api.md#testing-pytest-plugin) and [testing plugin design](docs/testing-plugin-design.md).
+See [Package API — Testing](docs/library/package-api.md#testing-pytest-plugin) and [testing plugin design](docs/library/testing-plugin-design.md).

{core_framework-1.6.0 → core_framework-1.8.0}/README.md

@@ -50,7 +50,7 @@ def build_app(settings: HostSettings | None = None) -> FastAPI:
     return app
 ```
 
-From the host repository root, run **`uv run cf-alembic`**. See [core-framework-migration](docs/core-framework-migration.md).
+From the host repository root, run **`uv run cf-alembic`**. See [core-framework-migration](docs/library/core-framework-migration.md).
 
 ## Host pytest
 
@@ -78,4 +78,4 @@ def anyio_backend() -> str:
     return "asyncio"
 ```
 
-See [Package API — Testing](docs/package-api.md#testing-pytest-plugin) and [testing plugin design](docs/testing-plugin-design.md).
+See [Package API — Testing](docs/library/package-api.md#testing-pytest-plugin) and [testing plugin design](docs/library/testing-plugin-design.md).