core-framework 1.5.0__tar.gz → 1.7.0__tar.gz

{core_framework-1.5.0 → core_framework-1.7.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.5.0 → core_framework-1.7.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.5.0 → core_framework-1.7.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.5.0 → core_framework-1.7.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
 

{core_framework-1.5.0 → core_framework-1.7.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.5.0 → core_framework-1.7.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.5.0 → core_framework-1.7.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.7.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.5.0 → core_framework-1.7.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.5.0 → core_framework-1.7.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. **`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/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`

{core_framework-1.5.0 → core_framework-1.7.0}/.github/workflows/_deploy.yml

@@ -41,8 +41,10 @@ jobs:
           ALLOWED_HOSTS: ${{ secrets.ALLOWED_HOSTS }}
           AVATAR_HOST_DOMAIN: ${{ secrets.AVATAR_HOST_DOMAIN }}
           AVATAR_DEFAULT_IMAGE: ${{ secrets.AVATAR_DEFAULT_IMAGE }}
+          AVATAR_PUBLISH_ROOT: ${{ secrets.AVATAR_PUBLISH_ROOT }}
           BANNER_HOST_DOMAIN: ${{ secrets.BANNER_HOST_DOMAIN }}
           BANNER_DEFAULT_IMAGE: ${{ secrets.BANNER_DEFAULT_IMAGE }}
+          BANNER_PUBLISH_ROOT: ${{ secrets.BANNER_PUBLISH_ROOT }}
           IMAGE_SERVER_HOST: ${{ secrets.IMAGE_SERVER_HOST }}
           IMAGE_SERVER_PORT: ${{ secrets.IMAGE_SERVER_PORT }}
           IMAGE_SERVER_USER: ${{ secrets.IMAGE_SERVER_USER }}
@@ -138,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"
 
@@ -146,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 \
@@ -173,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.5.0 → core_framework-1.7.0}/.gitignore

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

{core_framework-1.5.0 → core_framework-1.7.0}/CHANGELOG.md

@@ -1,14 +1,41 @@
 # 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.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
+
+- **Deploy:** **`[avatar].publish_root`** and **`[banner].publish_root`** are rendered from GitHub environment secrets **`AVATAR_PUBLISH_ROOT`** and **`BANNER_PUBLISH_ROOT`** (via **`config.toml.template`**) so image-server docroots can differ per environment. Local **`config.toml`** defaults are unchanged.
+
 ## [1.5.0] - 2026-05-26
 
 ### 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
 
@@ -17,7 +44,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.
 
@@ -29,21 +56,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
@@ -56,11 +83,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
 
@@ -97,7 +124,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
 
@@ -113,7 +140,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
 
@@ -121,11 +148,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
 
@@ -152,7 +179,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
 
@@ -174,7 +201,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
 
@@ -184,7 +211,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
 
@@ -204,4 +231,6 @@ First **SemVer-stable** release per **`docs/package-api.md`**.
 [1.3.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.2.0...v1.3.0
 [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
-[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.5.0...HEAD
+[1.6.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.5.0...v1.6.0
+[1.7.0]: https://github.com/NepNepFFXIV/core-framework/compare/v1.6.0...v1.7.0
+[unreleased]: https://github.com/NepNepFFXIV/core-framework/compare/v1.7.0...HEAD

{core_framework-1.5.0 → core_framework-1.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-framework
-Version: 1.5.0
+Version: 1.7.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
@@ -87,7 +87,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 +115,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.5.0 → core_framework-1.7.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).

core_framework-1.7.0/alembic/media/alembic/versions/media_add_banner_staging_and_lease.py

@@ -0,0 +1,43 @@
+"""add banner staging registry and ingest lease
+
+Revision ID: media_banner_staging_lease
+Revises: v1_media_init
+Create Date: 2026-06-01 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "media_banner_staging_lease"
+down_revision: str | Sequence[str] | None = "v1_media_init"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        create table banner_staging_registry (
+            asset_id varchar(26) not null primary key,
+            owner_user_id varchar(128) not null,
+            staging_filename text not null,
+            created_at timestamptz not null default now()
+        );
+    """)
+
+    op.execute("""
+        create index idx_banner_staging_registry_created_at
+            on banner_staging_registry (created_at);
+    """)
+
+    op.execute("""
+        create table banner_ingest_lease (
+            owner_user_id varchar(128) not null primary key,
+            lease_expires_at timestamptz not null
+        );
+    """)
+
+
+def downgrade() -> None:
+    pass

core_framework-1.7.0/alembic/user/alembic/versions/user_add_banner_ingest_sequences.py

@@ -0,0 +1,34 @@
+"""add banner ingest sequences to user_profiles
+
+Revision ID: user_add_banner_ingest_sequences
+Revises: user_add_avatar_ingest_sequences
+Create Date: 2026-06-01 12:00:00.000000
+
+"""
+
+from collections.abc import Sequence
+
+from alembic import op
+
+revision: str = "user_add_banner_ingest_sequences"
+down_revision: str | Sequence[str] | None = "user_add_avatar_ingest_sequences"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+    op.execute("""
+        alter table user_profiles
+            add column banner_ingest_sequence bigint not null default 0,
+            add column banner_applied_sequence bigint not null default 0;
+    """)
+
+    op.execute("""
+        alter table user_profiles
+            add constraint user_profiles_banner_sequences_ordered
+                check (banner_applied_sequence <= banner_ingest_sequence);
+    """)
+
+
+def downgrade() -> None:
+    pass

{core_framework-1.5.0 → core_framework-1.7.0}/config.toml

@@ -6,15 +6,18 @@ openapi_url = "/openapi.json"
 allowed_hosts = [
     "localhost",
     "127.0.0.1",
-    "test"
+    "api.manga4life.com",
+    "test",
 ]
 secret_key = "local-dev-secret-key-change-in-production"
 
+[media]
+staging_root = "media-staging"
+
 [avatar]
 avatar_host_domain = "avatar.core-framework.com"
 default_avatar_image = "default.webp"
 publish_root = "/var/www/sites/avatar"
-staging_root = "avatar-staging"
 
 [banner]
 banner_host_domain = "banner.core-framework.com"
@@ -39,8 +42,10 @@ logfire_token = "zzz"
 [cors]
 allow_credentials = true
 allowed_origins = [
-    "http://localhost",
-    "http://127.0.0.1",
+    "http://localhost:3000",
+    "http://127.0.0.1:3000",
+    "https://manga4life.com",
+    "https://www.manga4life.com",
 ]
 allowed_methods = [
     "GET",