docs(returnhub): update documentation for feature-complete baseline

Author: AAdewunmi

README.md

@@ -2,15 +2,16 @@
 
 ReturnHub is a Django 5 application for managing online-retail return cases across customer, merchant, ops, and admin roles. The project combines server-rendered workflow surfaces with DRF APIs, a service-layer workflow core, persisted audit events, and artifact-backed escalation-risk scoring.
 
-## Current state
+## Feature-complete state
 
-The repository currently includes:
+Core ReturnHub development is complete as of April 23, 2026. The repository now represents a feature-complete portfolio baseline for the returns workflow product, including:
 
 - Django 5.1 + Django REST Framework on Python 3.12
 - PostgreSQL-backed local development through Docker Compose
 - seeded demo users, groups, profiles, and 32 stable return cases
 - public landing and role-entry pages
 - authenticated console dashboards for admin, ops, customer, and merchant users
+- customer and merchant case-list portals with stable pagination and role-bound access
 - a standalone ops queue at `/ops/` with filtering, ordering, summary cards, and shared pagination
 - an ops case-detail workspace at `/ops/{case_id}/` with inline status changes, follow-up requests, internal notes, timeline, risk panel, and evidence list
 - a shared case detail route at `/cases/{case_id}/` with role-aware document visibility and inline uploads
@@ -101,6 +102,10 @@ Authenticated console routes:
 
 Workflow routes:
 
+- `/customer/`
+- `/customer/{case_id}/`
+- `/merchant/`
+- `/merchant/{case_id}/`
 - `/ops/`
 - `/ops/{case_id}/`
 - `/cases/{case_id}/`
@@ -121,7 +126,7 @@ Live application routes exposed by `config/urls.py`:
 - `GET /api/returns/{case_id}/audit-export/`
 - `GET /api/analytics/returns/?from=YYYY-MM-DD&to=YYYY-MM-DD`
 
-Behavioral rules currently enforced in code:
+Behavioral rules enforced in code:
 
 - customers and admins can create return cases
 - ops and admins can update status, set priority, and add internal notes
@@ -159,6 +164,8 @@ The project includes:
 - a committed model registry at `ml/registry/model_registry.json`
 - training, retraining, and dataset-generation management commands
 
+The ML layer is production-path ready for this baseline: scoring is artifact-backed when the active model can be loaded, degrades safely to placeholder scoring when artifacts are unavailable, persists `RiskScore`, and emits `risk_scored` audit events.
+
 Current committed active model:
 
 - version: `retrain_baseline-logreg-v1-seed-7-rows-500`
@@ -201,7 +208,7 @@ Shared local password:
 
 - `ChangeMe123!`
 
-Preferred seed command for current manual verification and multi-surface demos:
+Preferred seed command for manual verification and multi-surface demos:
 
 - `docker compose exec -T web python manage.py seed_returnhub_demo`
 
@@ -264,13 +271,17 @@ docker compose exec -T web python manage.py retrain_baseline_model --seed 7 --ro
 
 ## Documentation map
 
-- `README.md`: project overview and current-state summary
+- `README.md`: project overview and feature-complete baseline summary
 - `RUNBOOK.md`: bootstrap and manual verification flow
 - `docs/api/returns-workflow.md`: returns API behavior and permissions
 - `docs/api/ops-queue-contract.md`: shared queue filter, ordering, and pagination contract
 - `docs/ml/baseline-escalation-risk.md`: training, inference, and artifact flow
 - `docs/ml/model-registry.md`: registry structure and active-model metadata
+- `docs/ml/operations.md`: ML operational readiness, scoring, and fallback behavior
 - `docs/ui/product-ui-brief.md`: product-surface intent and route map
 - `docs/ui/design-system.md`: tokens, layout patterns, and component rules
 - `docs/ui/evidence-states.md`: case detail and document-upload state handling
-- `docs/sprint-runbook/sprint-6/sprint-6-multi-surface-verification.md`: current multi-surface verification flow
+- `docs/ui/visual-regression-checklist.md`: manual visual and responsive regression pass
+- `docs/deployment.md`: production-like Docker, Gunicorn, Nginx, and PostgreSQL deployment path
+- `docs/DEMO_SCRIPT.md`: deterministic feature-complete product walkthrough
+- `docs/sprint-runbook/sprint-6/sprint-6-multi-surface-verification.md`: archived multi-surface verification flow retained for sprint evidence

RUNBOOK.md

@@ -1,10 +1,10 @@
 # ReturnHub Runbook
 
-This runbook takes the project from clean clone to a verified local environment and checks the routes, workflows, APIs, ML artifacts, and proof commands that currently match the repository.
+This runbook takes the project from clean clone to a verified local environment and checks the routes, workflows, APIs, ML artifacts, and proof commands that match the feature-complete ReturnHub baseline.
 
-## Sprint 7 walkthrough intent
+## Feature-complete walkthrough intent
 
-This runbook covers the operational commands and checks needed to run, inspect, and verify ReturnHub after Sprint 7. It is intentionally practical. It assumes a working development or production-like environment and focuses on the tasks an operator, reviewer, or hiring manager might perform during a walkthrough.
+This runbook covers the operational commands and checks needed to run, inspect, and verify the completed core ReturnHub product as of April 23, 2026. It is intentionally practical. It assumes a working development or production-like environment and focuses on the tasks an operator, reviewer, or hiring manager might perform during a walkthrough.
 
 Common operator commands:
 
@@ -40,6 +40,7 @@ This runbook verifies:
 - Docker-based local setup with PostgreSQL
 - Django migrations and deterministic demo data
 - public and authenticated UI routes
+- customer and merchant case-list portals
 - ops queue and ops case-detail workflows
 - shared case-detail document upload flow
 - returns, documents, queue, risk, audit-export, and analytics APIs
@@ -187,6 +188,21 @@ Expected behavior:
 - customer sees recent linked cases
 - merchant sees recent linked cases
 
+## Customer and merchant portal verification
+
+Open as the matching seeded users:
+
+- `customer.one` -> `http://127.0.0.1:8000/customer/`
+- `merchant.one` -> `http://127.0.0.1:8000/merchant/`
+
+Verify:
+
+- list pages render with linked cases only
+- pagination uses a page size of `15`
+- page 2 remains reachable in the seeded dataset
+- detail routes at `/customer/<case_id>/` and `/merchant/<case_id>/` enforce role ownership
+- unrelated customer or merchant actors receive a branded `403`
+
 ## Ops queue verification
 
 Open:
@@ -239,7 +255,7 @@ Verify the page renders:
 Expected behavior:
 
 - the route is `ops:case-detail`
-- the page renders current workflow state and ownership context
+- the page renders workflow state and ownership context
 - the page includes documents, notes, timeline, and risk sections
 - sparse cases show stable empty states such as `No documents yet`, `No notes yet`, `No timeline events yet`, and `No score yet`
 
@@ -414,7 +430,7 @@ Check the committed active-model registry.
 docker compose exec -T web python manage.py shell -c "from pathlib import Path; print(Path('ml/registry/model_registry.json').read_text())"
 ```
 
-Expected current active model metadata:
+Expected active model metadata:
 
 - version: `retrain_baseline-logreg-v1-seed-7-rows-500`
 - model type: `logistic_regression`

docs/DEMO_SCRIPT.md

@@ -3,7 +3,7 @@
 
 ## Goal
 
-This script provides a deterministic walkthrough of the current multi-surface ReturnHub product after Sprint 7. It is designed for a five to eight minute demo and follows the repo's current Docker-based workflow, seeded data, and live routes.
+This script provides a deterministic walkthrough of the feature-complete multi-surface ReturnHub product as of April 23, 2026. It is designed for a five to eight minute demo and follows the repo's Docker-based workflow, seeded data, and live routes.
 
 ## Pre-demo preparation
 
@@ -102,6 +102,12 @@ Narration:
 - Ops sees queue-oriented operational context.
 - Customer and merchant consoles show role-specific linked case views.
 
+Optional route callout:
+
+- `customer.one` can also open `http://127.0.0.1:8000/customer/`
+- `merchant.one` can also open `http://127.0.0.1:8000/merchant/`
+- these list portals provide role-bound case browsing with stable pagination
+
 ### 4. Walk through the ops queue
 
 Open:
@@ -237,7 +243,7 @@ Suggested pacing for a five to eight minute walkthrough:
 
 ## Optional proof commands
 
-For a more evidence-driven walkthrough, use the current runbook:
+For a more evidence-driven walkthrough, use the runbook:
 
 - [RUNBOOK.md](../RUNBOOK.md)
 

docs/api/ops-queue-contract.md

@@ -1,7 +1,7 @@
 <!-- path: docs/api/ops-queue-contract.md -->
 # Ops Queue Contract
 
-This document describes the queue contract currently shared by the server-rendered ops surface at `/ops/` and the DRF queue endpoint at `/api/returns/queue/`.
+This document describes the queue contract shared by the feature-complete server-rendered ops surface at `/ops/` and the DRF queue endpoint at `/api/returns/queue/`.
 
 ## Supported query parameters
 
@@ -88,7 +88,7 @@ Pagination links preserve active filters except for `page`.
 
 ## Response shape
 
-The API queue response currently returns:
+The API queue response returns:
 
 - `count`
 - `next`

docs/api/returns-workflow.md

@@ -1,7 +1,7 @@
 <!-- path: docs/api/returns-workflow.md -->
 # Returns Workflow API
 
-This document describes the return-case API behavior implemented in the current repository.
+This document describes the return-case API behavior implemented for the feature-complete ReturnHub baseline.
 
 ## Runtime routes
 
@@ -17,7 +17,7 @@ The live application exposes these routes:
 - `GET /api/returns/{case_id}/risk/`
 - `GET /api/returns/{case_id}/audit-export/`
 
-The repository also contains compatibility wrappers in `api/` and canonical route modules in `returns/api/`; both are aligned around the same workflow services.
+The repository also contains compatibility wrappers in `api/` and canonical route modules in `returns/api/`; both are aligned around the same workflow services. The server-rendered customer, merchant, ops, and shared case-detail pages use the same service-layer behavior where applicable.
 
 ## Create case
 

docs/deployment.md

@@ -8,6 +8,11 @@ hosting platform abstraction. The goal is to make one clear operator path that
 can be followed locally, in staging, or in a VM-based deployment with minimal
 translation.
 
+The deployment target is the feature-complete ReturnHub baseline: public role
+entry pages, authenticated dashboards, customer and merchant portals, ops queue
+and case workspace, returns APIs, analytics, audit export, and persisted
+escalation-risk scoring.
+
 This repository defaults to `config.settings.dev` when
 `DJANGO_SETTINGS_MODULE` is unset. Production deployment should override that
 explicitly in the deployment platform, not through ad hoc shell exports.

docs/ml/baseline-escalation-risk.md

@@ -1,9 +1,9 @@
 <!-- path: docs/ml/baseline-escalation-risk.md -->
 # Baseline Escalation Risk
 
-This document describes the ML flow currently implemented for return-case escalation scoring.
+This document describes the ML flow implemented for feature-complete ReturnHub return-case escalation scoring.
 
-## Current approach
+## Implemented approach
 
 The project uses a logistic-regression baseline with:
 
@@ -20,7 +20,7 @@ Training and inference share the feature contract in:
 - `ml/contracts/return_case_features.json`
 - `ml/features.py`
 
-The current implementation includes signals derived from:
+The implementation includes signals derived from:
 
 - item category
 - delivery-to-return timing
@@ -35,7 +35,7 @@ The current implementation includes signals derived from:
 
 Training data is synthetic and deterministic.
 
-Current dataset flows:
+Dataset flows:
 
 - `ml/datasets/synthetic.py` generates seeded rows
 - `ml/datasets/dataset.py` exposes the dataset wrapper
@@ -67,7 +67,7 @@ Retraining wrapper:
 docker compose exec -T web python manage.py retrain_baseline_model --seed 7 --rows 500
 ```
 
-Current committed active version:
+Committed active version:
 
 ```text
 retrain_baseline-logreg-v1-seed-7-rows-500
@@ -86,14 +86,14 @@ Per model version:
 - `<model_version>.pkl`
 - `<model_version>.json`
 
-Committed example artifacts currently present:
+Committed example artifacts:
 
 - `ml_artifacts/retrain_baseline-logreg-v1-seed-7-rows-500.pkl`
 - `ml_artifacts/retrain_baseline-logreg-v1-seed-7-rows-500.json`
 
 ## Metadata contract
 
-Training metadata currently includes:
+Training metadata includes:
 
 - `model_version`
 - `feature_contract_version`
@@ -115,7 +115,7 @@ Runtime scoring path:
 3. `ml/features.extract_case_features(...)` builds the feature vector.
 4. The model returns a probability.
 5. The score is quantized to two decimal places.
-6. Labels are mapped with current thresholds:
+6. Labels are mapped with these thresholds:
    - `>= 0.75` -> `high`
    - `>= 0.45` -> `medium`
    - otherwise -> `low`
@@ -128,7 +128,7 @@ If the active artifact cannot be loaded safely, scoring falls back to the placeh
 
 The returns domain stores one `RiskScore` per case and updates that row on rescore.
 
-Rescoring currently happens on:
+Rescoring happens on:
 
 - case creation
 - status update
@@ -138,15 +138,15 @@ Each rescore emits a `risk_scored` audit event.
 
 ## Dependencies
 
-ML-related runtime packages currently listed in the repository:
+ML-related runtime packages listed in the repository:
 
 - `pandas`
 - `scikit-learn`
 - `joblib`
 
 ## Test coverage
 
-Relevant tests currently cover training, scoring, registry access, artifacts, features, and dataset generation, including:
+Relevant tests cover training, scoring, registry access, artifacts, features, and dataset generation, including:
 
 - `tests/test_baseline_training.py`
 - `tests/test_ml_training.py`

docs/ml/model-registry.md

@@ -11,7 +11,7 @@ Path:
 ml/registry/model_registry.json
 ```
 
-Current structure:
+Structure:
 
 ```json
 {
@@ -25,7 +25,7 @@ Current structure:
 }
 ```
 
-## Current active model
+## Active model
 
 - version: `retrain_baseline-logreg-v1-seed-7-rows-500`
 - model type: `logistic_regression`