Separate overview and implementation modes with frontend-first and backend specifications

BuxUp_Implementation_Plan.md

@@ -0,0 +1,268 @@
+# BuxUp — Implementation Plan
+
+## Implementation plan
+
+**Frontend first. Backend second.** This is the build specification for the dashboard-first BuxUp application. The System overview mode explains the product and demonstrates its flows; this mode defines screens, components, behavior, records, services, integration contracts, and acceptance criteria for implementation.
+
+**Working specification · Version 5 · 3 November 2026**
+
+The current page is a static guide with fictional interactive previews. The application described below is proposed work; this update does not deploy a campaign backend or connect the demo to live client records. The overview and this specification have independent chapter menus and Markdown downloads, while sharing the same Light / Dark / System theme controls.
+
+## F01 — Frontend foundation and code structure
+
+Implement the production frontend with **React and TypeScript**, organised by product feature. Begin with the approved layouts and fixtures, define typed API contracts, then connect the real services. Keep page components small enough to separate screen layout, business actions, data access, and reusable controls. React’s [component and state design guide](https://react.dev/learn/thinking-in-react) supports this approach; specific package versions are a setup decision, not fixed by this document.
+
+| Module | Responsibility | Main components |
+| --- | --- | --- |
+| app | Routing, sign-in bootstrap, current user/client scope, layouts, theme, error boundaries | AppShell, RouteGuard, Header, Sidebar, PageTitle, ThemeSwitch |
+| dashboard | Cross-client campaign queues, counts, search, filters, pagination | CampaignKpis, CampaignFilters, CampaignTable, StatusBadge |
+| campaigns | New/existing client intake, job progress, finished packs, revisions, decisions | NewCampaignDialog, BriefFields, CountrySelector, RunProgress, CampaignPack, DecisionPanel |
+| clients | Provider identity, facts, evidence, documents, preferences, history | ClientHeader, ProfileForm, SourcesList, FileUploader, MemoryList |
+| review | Artifact-level findings, source inspection, version comparison, reviewer notes | FindingCard, ClaimHighlight, SourceDrawer, VersionCompare |
+| hermes | Autonomous update activity, notifications, exact diffs, checks, rollback | UpdateFeed, UpdateDetail, DiffViewer, NotificationStatus, RollbackForm |
+| shared | Typed API client, reusable forms/tables/dialogs, date/number formatting, accessibility utilities | Field, Select, Dialog, EmptyState, ErrorState, LoadingState |
+
+Keep API-derived records in a server-data cache with explicit loading, error, stale, and refreshing states. Keep temporary form values, open dialogs, tabs, and selection in local UI state. Store filters and pagination in the URL so links are reproducible. Store only theme preference and harmless display preferences in browser storage; client documents and model credentials do not belong there. Clear scoped caches on sign-out and avoid rendering a previous client’s data during a scope change.
+
+Use one typed status contract shared with the API. The frontend must never infer “Running” from a successful draft generation or an approval click. Replace the public guide’s fictional fixtures only when the corresponding backend endpoint is connected and verified.
+
+## F02 — Application shell, navigation, roles, and visual design
+
+The signed-in landing screen is the **campaign dashboard**. Primary navigation is Dashboard, Clients, Review queue, Notifications, and Hermes updates for permitted admins. There is no conversation-led home screen or chat input. A persistent **New campaign** button opens the intake dialog from the dashboard or selected client context.
+
+| Route | Purpose | Required context |
+| --- | --- | --- |
+| /dashboard | Cross-client KPIs, queues, filters, and campaign rows | Signed-in user; permitted organisation/client scope |
+| /clients | Searchable list of permitted providers | Membership and client access |
+| /clients/:clientId | Profile, files, evidence, memory, and campaigns | Visible client name/domain and role |
+| /campaigns/:campaignId | Brief, current run progress, versions, and next action | Client, offering, countries, state, and owner |
+| /campaigns/:campaignId/versions/:versionId | Immutable finished pack and review decisions | Exact version and artifact manifest |
+| /notifications | Campaign-ready events, failures, and update notices | Scoped inbox and read/delivery state |
+| /admin/hermes/updates | Automatic agent-update history and recovery | Admin access; no change-approval queue |
+
+Use the established cream/green light palette and forest dark palette, with shared design tokens for surfaces, text, borders, warnings, spacing, typography, and focus outlines. Theme changes affect every page, modal, chart/diagram, and preview without changing the current route, reading mode, form contents, or campaign selection. Respect the system theme when System is selected and persist an explicit choice.
+
+On desktop, use a fixed-width sidebar, clear page heading, actions, and a flexible main content area. On tablets, collapse secondary navigation and keep filters reachable. On phones, use compact navigation, stacked KPI tiles and forms, and either labelled campaign cards or a contained table scroller. Page content must not overflow the viewport; wide tables and diagrams scroll inside labelled regions. Validate representative widths of 390, 768, and 1440 pixels.
+
+Role-specific actions are visible only when applicable: operators prepare/review permitted clients, designated client reviewers see their assigned versions, and admins inspect Hermes activity and can request rollback. Display no inaccessible client names in selectors. Client-side role checks improve the interface; backend authorization remains mandatory.
+
+## F03 — Dashboard and review queues
+
+Render the page heading, current scope, New campaign button, five status KPIs, filters, and campaign results in that order. KPI counts and table queries use the same client/country/platform scope. Selecting a KPI filters the queue and shows the active selection; clearing it returns to the full scoped list. Show last-updated time and distinguish a stale cached result from a current response.
+
+| KPI | Backend meaning | Row action |
+| --- | --- | --- |
+| Needs review | Generated versions awaiting internal review | Open the exact finished pack |
+| Running | Campaign launch confirmed by a publishing integration | Inspect launch identity and available results |
+| Approved — awaiting client approval | Internal approval recorded; client decision outstanding | Open client decision workflow |
+| Approved — ready to launch | Required decisions complete for this exact version | Inspect approvals / authorised export or launch |
+| Rejected / changes requested | Review requires a revision with recorded reasons | View instructions and create a new version |
+
+Rows include client, campaign/offer, countries and subdivisions, platforms, version, status, owner/reviewer, updated time, and the next action. Provide client, country, platform, status, owner/reviewer, search, sorting, and pagination controls. Changing a filter resets pagination. An empty filtered queue offers Clear filters; a user with no clients sees a New campaign entry point; a failed load offers Retry without pretending the queue contains zero campaigns.
+
+When a campaign changes state, invalidate both counts and affected row queries. If the server reports a stale version or changed role, explain it and reload the record before accepting another decision. A client decision must never be inferred from an internal reviewer’s action.
+
+## F04 — New campaign dialog and brief validation
+
+Open a labelled modal or mobile full-height sheet with **New client / Existing client** as the first choice. Carry the selected client into the dialog when opened from a client page. Preserve values if validation fails; warn before discarding unsaved work. Save draft is separate from Start research.
+
+| Field | New client | Existing client | Validation and behavior |
+| --- | --- | --- | --- |
+| Provider domain | Required | Display saved domain | Canonicalize server-side; detect duplicates and offer the matching permitted client |
+| Client name | Optional; can be resolved from research | Display saved name | Corrections remain traceable to the provider record |
+| Offering / service | Required to start research | Required new campaign context | Describe the specific service/promotion and relevant terms |
+| Audience and objective | Required to start research | Required | Identify business category, campaign goal, and proposed action |
+| Target countries | At least one required | Confirm for every campaign | Explicit selected countries; headquarters alone is insufficient |
+| States / provinces / regions | Collect where relevant | Collect where relevant | Associate each subdivision with its country; distinguish unknown scope from all regions |
+| Platforms and language | Required | Required | Select at least one supported platform and campaign language |
+| Destination / CTA | Needed for a complete review pack | Needed for a complete review pack | Allow an incomplete draft; show unresolved destination as a review gap |
+| Files, brand references, context | Optional | Optional additional/changed evidence | Show upload/extraction state, versions, remove controls, and limits from backend policy |
+
+Show inline errors beside fields and an error summary linked to them. Disable only the action that cannot proceed and state why; do not erase the form on failure. A duplicate domain should reuse the existing client rather than silently create another one. Backend validation repeats all readiness checks and controls creation races. Use a stable submission/idempotency key so double clicks and network retries create one campaign/run.
+
+File selection is not upload completion. Display filename, type, size, upload progress, queued/extracting/ready/failed status, and a retry/removal action. The supported types, maximum bytes/pages, and handling of unsupported/encrypted files must come from a configured upload policy, shown before submission. Never claim a file has been read until extraction succeeds. The new campaign confirmation returns its ID and the first persisted job state.
+
+## F05 — Client workspace, source management, and scoped knowledge
+
+Each client page keeps its name, canonical domain, identity, user role, and a New campaign action visible. Provide tabs for Overview/Profile, Offerings, Files/Sources, Knowledge, Campaigns, and History. Profile editing uses labelled fields with fact provenance; source detail exposes version, extraction state, checked date, applicability, and linked claims.
+
+Distinguish user-provided, web-discovered, confirmed, inferred, conflicting, expired, and removed information. Do not show an inferred product capability as a confirmed brand fact. Show the client memory scope and why a preference or correction is being reused. Geographic knowledge identifies country/subdivision and applicability; shared skills do not expose another client’s private details.
+
+Add/replace/remove controls show the concrete source affected and dependent facts or campaigns. Replacement creates a source version. Removal invalidates active retrieval and marks dependent material for recheck; the UI reports pending invalidation and failures rather than hiding a row optimistically and implying completion. Review history remains inspectable under the retention policy. Offer conflict resolution and factual corrections through forms attached to the source/fact, without adding a general chat interface.
+
+## F06 — Job progress, finished pack, and human decisions
+
+The campaign page shows a stage timeline: context loading, provider research, jurisdiction research, planning, platform copy, images, separate review, and pack assembly. Each stage shows queued/running/completed/failed/cancelled state, meaningful output, and available retry/cancel actions. Use persisted progress events rather than a fabricated percentage. A reconnect resumes from the last confirmed event; a refresh retrieves the current run.
+
+When work finishes, show **Campaign ready for review**, client and offering, campaign/version, countries, audience, platforms, readiness, and outstanding questions. A partial pack explicitly identifies missing copy, images, research, or extraction. Generation completion does not imply legal clearance or approval.
+
+| Pack area | Required frontend behavior |
+| --- | --- |
+| Overview | Source-backed brief, strategy, reused context, assumptions, missing inputs, and completion state |
+| Copy & images | Platform tabs, selectable headline/body/caption/CTA, readable image text, full-size inspection, copy and download controls |
+| Findings | Exact flagged passage or visual region, severity/status, jurisdiction, why it may apply, linked evidence, uncertainty, and suggested edit |
+| Source drawer | Source document/page, relevant excerpt, checked/effective/expiry dates, applicability, and claims depending on it |
+| Versions & history | Immutable version IDs, before/after artifacts, reviewer identity/time, notes, and approval invalidation |
+| Decision panel | Role-aware internal approval, client decision, rejection or change request with reasons, and current next owner |
+| Export | Server-prepared manifest with exact copy/images, findings, sources, version IDs, decision state, and outstanding questions |
+
+Reviewing a finding must preserve the current artifact and tab. A source drawer returns focus to its trigger. Copy/download buttons report actual success or an actionable error. Export only permitted records and identify draft, partial, and approved status clearly. Actual platform placement requirements are checked before export; a still image is not labelled a finished TikTok video.
+
+A change request records instructions against a base version and selected artifact(s); the server creates a revision job and a new version. Approval sends the expected version/manifest hash and records the decision returned by the server. Internal approval leads to client review; client approval leads to Ready to launch. Changing copy, image, claim, destination, audience, or jurisdiction requires a new version/recheck as appropriate. Only a confirmed launch sets Running.
+
+## F07 — Hermes activity, notifications, and recovery
+
+The Hermes dashboard is an **automatic update activity view**. Filters cover Applied, Checking, Failed, and Rolled back, with scope/type/date and notification read state. Rows show the change, reason, affected scope, version transition, application time, and delivery/read status. There is no Approve update or Activate approved update control.
+
+The detail view contains run evidence, exact before/after diff, checks, anticipated benefit/cost, affected workflows, previous/current versions, monitoring results, and rollback history. A change shown as Applied is already active. Mark read affects notification acknowledgement only. Checking means automatic evaluation is in progress; passing checks apply the candidate and send a notification without waiting for a person.
+
+Admins can request rollback with a reason; show Pending until the server confirms restoration and then link the recovery event. A failed check keeps the prior working version; a regression may trigger automatic rollback. Notify after actual application or recovery. Campaign-ready and failed-job notifications deep-link to their exact run/version; update notifications deep-link to their update record. Repeated event delivery must not create duplicate inbox entries.
+
+## F08 — Frontend quality, accessibility, and integration checks
+
+Define component states before integration: initial loading, background refresh, no records, no filter matches, failed request, access denied, missing capability, partial result, stale data, and successful completion. Use skeletons for unknown data, not fictional zero KPIs. Keep user input after failed saves, prevent repeated submissions, and support retry without duplicated records.
+
+All controls need accessible labels, visible focus, keyboard operation, readable contrast, and status text beyond colour. Dialogs trap focus, close predictably, and return focus to the opening control. Tabs support arrow keys and identify their panels. Announce important asynchronous state changes through a live region without continuously reading every progress event. Reduced-motion preference suppresses decorative motion.
+
+Split large route bundles and lazy-load images/version comparison where useful. Request thumbnails for lists and full media only on inspection; paginate server-side lists. Define performance budgets after representative document sizes, campaign volume, and network conditions are agreed, and measure real response/render timings instead of inventing production guarantees.
+
+**Frontend acceptance checklist:** keyboard-only campaign creation and review; required-country validation; duplicate-domain reuse; lost-connection recovery; partial-image state; internal/client decisions kept separate; no false Running status; role-appropriate controls; stale-version conflict recovery; light/dark/system persistence; mobile widths without page overflow; and Hermes update notifications that never become an approval gate. Exercise unit tests for meaningful state/validation logic, integration tests against contract fixtures, and end-to-end tests for complete user journeys.
+
+## B01 — Backend services and ownership
+
+Use a **Python FastAPI API**, PostgreSQL, durable object storage, a Redis-backed task queue, dedicated campaign workers, and a Hermes worker adapter. Separate API routers and service boundaries for identity, clients, sources, campaigns, reviews, jobs, notifications, and agent updates; see FastAPI’s [application structure guidance](https://fastapi.tiangolo.com/tutorial/bigger-applications/). This is the proposed pilot architecture, not an assertion that those services already run in the current static Space.
+
+The API owns authentication, client authorization, validation, transactions, immutable versions, and status transitions. Workers execute long-running research/extraction/generation jobs and report durable outputs. Hermes coordinates permitted tool/model work and self-improvement. PostgreSQL is the business source of truth; the queue transports tasks, and object storage keeps files/media. A browser disconnect must not cancel or lose a server job unless an explicit cancellation is recorded.
+
+Use an organisation/client authorization context on every request, queued task, retrieval query, export, and signed media URL. Roles include operator, designated reviewer, client reviewer, and admin; exact memberships are configured per client. Return consistent authorization errors without exposing another client’s identity or records. Keep inference credentials server-side. For database row-level protection, explicitly configure and test the intended service role; PostgreSQL’s [row security documentation](https://www.postgresql.org/docs/current/ddl-rowsecurity.html) notes that owner/bypass roles behave differently.
+
+## B02 — Data model, immutable versions, and storage
+
+Use organisation_id and client_id on private records. Campaigns reference one client; campaign_versions are immutable snapshots of the brief, jurisdictions, evidence set, skill/configuration versions, and artifacts. An approval points to one campaign_version and its artifact manifest hash, rather than to a mutable campaign title. All writes include an actor or job identity and timestamp.
+
+Core tables: organisations, users, memberships, clients, client_roles, sources, source_versions, extracted_chunks, facts, campaigns, campaign_versions, jobs, job_steps, artifacts, review_findings, decisions, memories, agent_updates, active_version_sets, notifications, and audit_events. Media bytes belong in object storage; database rows hold references, checksums, ownership, and versions. Retrieval queries enforce permissions before ranking, not after returning a mixed-client result.
+
+Store legal/research applicability with country, subdivision, product/service category, audience, source URL, publication/effective dates when available, checked_at, recheck_at, and uncertainty. Geographic sources can be shared when public; private client evidence cannot be promoted into that shared store. Store provider facts separately from legal applicability and reviewer preferences.
+
+## B03 — API contracts and events
+
+| API or event | Contract |
+| --- | --- |
+| POST /clients and GET /clients | Resolve canonical domains, create clients idempotently, and return only authorised records |
+| POST /campaigns | Save new/existing-client brief, mandatory research fields, country/subdivision scope, and selected platforms |
+| POST /campaigns/{id}/runs | Validate readiness; enqueue one run using an idempotency key; return job ID and initial status |
+| GET /dashboard and GET /campaigns | Return scoped KPI counts and filtered campaign lists from the same status definitions |
+| GET /jobs/{id} and progress events | Report stage state, partial completion, retryable errors, and cancel status without exposing secrets |
+| GET /campaigns/{id}/versions/{version}/pack | Return exact copy/images, findings, evidence manifest, uncertainties, and review history |
+| POST /campaigns/{id}/revisions | Attach reviewer instructions to a base version and enqueue only the affected work plus rechecks |
+| POST /campaigns/{id}/decisions | Enforce reviewer role, expected version/hash, current state, and required reason for changes/rejection |
+| POST /sources and DELETE /sources/{id} | Create upload/extraction records or invalidate source content and its active retrieval dependencies |
+| GET /agent-updates and GET /agent-updates/{id} | Display automatic update history, exact changes, tests, versions, notification status, and rollback evidence |
+| POST /agent-updates/{id}/rollback | Restore the prior compatible version, record reason, and notify; no approve-update endpoint is needed |
+| pack.ready and agent_update.applied | Persist events and notification delivery with retries; user acknowledgement has no activation effect |
+
+These are proposed API contracts, not endpoints already served by the current Space. Use server-side authorization on every record operation and signed, short-lived access to permitted files. Frontend status labels come from backend state, not independent optimistic counters. Optimistic concurrency prevents a reviewer approving a version that changed while the pack was open.
+
+The production API must also support client/profile edits, paginated source/fact history, file-replacement versions, upload policy discovery, signed upload/download actions, authenticated export jobs, scoped notification lists/read acknowledgement, and current-role/session bootstrap. Publish the request/response schema from the API and generate or validate frontend types against it. Include cursor/page metadata and stable sort order for list endpoints; use request correlation IDs and explicit version conflicts for writes.
+
+## B04 — Campaign jobs and review pipeline
+
+1. Validate the brief and client access; capture a run ID, input hash, campaign version, target scope, and active skill/configuration version set.
+2. Retrieve relevant client facts and previous campaign lessons. Refresh stale facts and extract new files; keep conflicting or missing information explicit.
+3. Research the provider’s offering and the laws, regulatory guidance, and platform policies potentially applicable to this product, audience, country, and subdivision. Save source text references and dates, not only search snippets.
+4. Construct a source-backed brief and platform plans. Generate structured copy with claim-to-source links and visual briefs; request images through the verified image adapter.
+5. Run the separate review job on actual copy, image text/content, destination, targeting, and source evidence. Return structured findings with applicability and uncertainty.
+6. Assemble the immutable artifact manifest and final campaign pack. Mark complete or partial accurately; enqueue the Needs review notification with a direct link to the exact pack version.
+7. Persist review decisions and revision instructions. Re-run only changed dependencies, while rechecking anything invalidated by the change. Capture client decisions separately from internal approval.
+8. After a separately authorised export or publication integration, collect actual available outcomes and feedback. A prepared or approved pack alone never increments the Running KPI.
+
+Give each step a persisted state, input/output hash, attempt count, timeout, usage, and error classification. Retry transient failures with bounded backoff; return permanent failures or exhausted retries to the dashboard. Idempotent artifact writes and unique job keys prevent duplicate generations after restarts. Cancellation stops new downstream work and records already incurred usage. Partial packs clearly identify failed/missing artifacts.
+
+## B05 — Hermes and proxy adapters
+
+Create adapters for reasoning, web-grounded research, document reading, and image output. They normalize returned text, citations, media, usage, request IDs, resolved model names, and errors into typed application records. Keep requested aliases configurable, including gemini-3.8-flash-tiered and the requested gemini-3.1-flash-lite image alias. The initial capability test must establish its actual image route mapping before the image stage is enabled.
+
+Hermes’s built-in memory is bounded and profile-scoped; it is not the campaign database. Isolate worker profiles/home directories so concurrent jobs cannot write into one shared private memory file. Supply client context through the permission-scoped application store or a suitably scoped external memory provider; distribute global skills as versioned shared resources without client-private content. See the official [persistent memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) and [skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) documentation for the underlying mechanisms. The BuxUp update service, deployment handlers, and notification dashboard described here are application components to implement.
+
+The Hermes adapter receives an explicit task envelope and permitted source/context handles; it returns artifacts and update events through application services. Durable business state remains in the database. Use one controlled context/session per job and client. A worker crash must not make the application lose campaign state. Store redacted diagnostic traces separately from user-facing explanations; the final pack shows conclusions, supporting evidence, and uncertainty.
+
+## B06 — Client, geographic, and global memory
+
+A memory write includes scope, source, evidence references, applicability, version, status/confidence, creation time, validity/recheck date, and the run that created it. Client memory contains confirmed facts/preferences and reviewer corrections; geographic memory contains sourced public research for a country/subdivision/product/audience; global memory contains generalized workflow improvements without private client content.
+
+Context retrieval enforces organisation/client access before ranking and filters by current product, audience, jurisdiction, freshness, and source deletion state. Do not retrieve all clients and ask the model to ignore unrelated ones. A second campaign should reuse relevant confirmed facts, refresh stale offer details, and research genuinely new locations or products.
+
+Store source-to-fact-to-artifact dependencies so removal, replacement, expiry, or a contradiction invalidates the relevant active material. Shared legal research remains dated evidence with applicability and uncertainty, not a permanent compliance verdict. A single rejected advertisement is client feedback; generalizing it into a global behavior requires evidence and automatic scope/evaluation checks.
+
+Hermes writes scoped memory and shared skill improvements automatically. Every applied shared change gets a version, automatic checks, and an after-update notification. Existing run snapshots and human campaign decisions remain historical and inspectable.
+
+## B07 — Automatic system updates and rollback
+
+Record failure patterns, reviewer corrections, repeated source gaps, and job efficiency signals as improvement inputs. Hermes prepares a machine-readable update manifest containing scope, reason, evidence references, diff, dependency versions, evaluation plan, expected impact, and rollback target. Supported change handlers cover memory, skills/prompts, model/configuration settings, and application-code releases; each uses an explicit versioned apply interface.
+
+Run automated schema checks, regression examples, source-quality checks, client-isolation checks, budget/time limits, and relevant component tests in a separate test environment. A passing candidate is applied automatically: switch the active version pointer transactionally for skills/configuration, or deploy a versioned application build through the deployment worker for code changes. Compare the expected base version before applying so simultaneous updates cannot overwrite each other. No human review or approval gate sits in this path.
+
+Persist the applied update and an outgoing notification in the same transaction (or equivalent durable event mechanism). Notification delivery retries independently; a temporary inbox failure does not roll back an otherwise successful update. Capture who/what was affected, before/after behavior, checks, version, timestamp, and recovery link. Monitor error rate, source support, latency, and cost against the baseline. On a detected regression, restore the previous compatible version automatically and notify again. An admin can also invoke rollback and inspect its reason/history.
+
+Runs already in progress keep their version snapshot. New runs receive the new active version set. Schema changes need reversible or backwards-compatible migrations; destructive data migrations should be handled as separate migration work with backups rather than being treated as a simple skill-file edit. External account access still depends on real credentials and infrastructure capabilities. Autonomous updates do not bypass the application's tenant boundaries or become campaign publication decisions.
+
+## B08 — State transitions, reliability, and operating contracts
+
+Keep campaign, job, artifact, approval, and agent-update state machines separate. The campaign lifecycle is Draft → Researching → Generating → Needs review → Awaiting client approval → Ready to launch → Scheduled/Running → Completed, with explicit partial/failed/cancelled/revision branches. The API validates transitions and records the triggering user or job; it never accepts an arbitrary browser status string as authoritative.
+
+Use a transaction for state changes plus audit/outgoing events. Publish the resulting event asynchronously with stable IDs; clients deduplicate it. Return timestamps in a standard timezone-aware representation and format them for the user in the frontend. Progress events include run ID, campaign/version, stage, event ID, timestamp, status, and structured error when relevant. Support resumable delivery with polling fallback.
+
+API errors contain a stable code, safe message, field errors when relevant, retryability, and a correlation ID. Use version conflicts for stale decisions, readiness errors for missing input, and explicit unavailable-capability responses for unverified routes. Rate limits, model/tool budgets, per-stage timeouts, retry counts, supported upload formats, byte/page limits, and file retention must be configured and visible to the relevant user; do not leave infinite retry or unlimited spend defaults.
+
+Block private/internal destinations in external research fetches, validate redirects, and treat downloaded pages/documents as evidence rather than tool instructions. Validate uploads and storage ownership; handle malformed/encrypted documents explicitly. Redact secrets and unnecessary private content from logs. Use authenticated, permission-scoped access to files and exports, and expire signed links.
+
+Monitor job latency/failures, queue depth, route availability, extraction errors, usage/cost where available, citation quality, notification delivery, and automatic-update regressions. Track workflow/skill versions in each trace. Configure database backups, object retention, restoration exercises, separate staging/production data, and compatible migrations before the pilot. A rollback restores compatible configuration/code without rewriting historical campaign artifacts or decisions.
+
+## R01 — Delivery sequence and dependencies
+
+| Phase | Concrete work and deliverables | Exit condition |
+| --- | --- | --- |
+| 0. Capability spike | Authenticate to the proxy from a worker; exercise main reasoning, grounded search, a PDF, an image input, and actual image generation; capture structured outputs, errors, and route resolution | Each required capability is verified, or explicitly unavailable with a named alternative; text-only image output is a failure |
+| 1. Application foundation | Set up frontend/API/worker projects, server-held secrets, migrations, persistent storage, authentication, organisation/client roles, deployment environments, and operational logs | Authorised users can create clients and retrieve their own records; cross-client access tests fail as expected |
+| 2. Dashboard and intake | Implement KPI queries, paginated/filterable campaign lists, New campaign dialog, new/existing client paths, canonical-domain matching, required countries, optional files, and saved drafts | Counts and lists agree; repeated submission creates one campaign; incomplete drafts cannot enqueue research |
+| 3. Knowledge and files | Fetch provider sources, extract uploaded documents, retain source versions and dates, normalize facts, record conflicts, and apply deletion/replacement invalidation | Profile facts trace to evidence; removed material is absent from active retrieval; stale facts require refresh |
+| 4. Campaign orchestration | Build resumable stages for context, provider research, location research, planning, copy, images, review, and pack assembly | A job survives restart; a failed stage can retry without duplicating artifacts or losing successful stages |
+| 5. Completed pack and decisions | Build the final-results page, platform variants, highlighted findings, source drawer, export, change requests, versioned internal/client decisions, and notification links | An operator can inspect a pack, request a revision, approve internally, then record client approval without marking it running |
+| 6. Scoped learning | Retrieve private client history, applicable country/state knowledge, and active global skills; write feedback with evidence, validity, and version | Second campaign reuses relevant facts; different clients remain isolated; expired facts are rechecked |
+| 7. Autonomous updater | Implement detection, versioned change preparation, automated evaluation, automatic application, notifications, monitoring, and rollback | A passing update applies without human approval; a failed check preserves the previous version; a regression rolls back and notifies |
+| 8. Pilot release | Seed agreed provider/offer/market, run end-to-end examples, exercise failure recovery, restore a backup, and document operating procedures | Pilot acceptance checks pass and reviewers can complete the full workflow from the dashboard |
+
+Phases 0–3 establish the dependencies for a grounded pack. Phase 4 feeds phase 5; phase 6 uses the same versioned sources and decisions. Build update logging and version capture early, then enable phase 7 once repeatable evaluations and a rollback path exist. Scope the first pilot to one offering and market, with multiple clients represented to test isolation. Do not estimate a firm delivery date before the capability spike and deployment choices are resolved.
+
+## R02 — End-to-end acceptance and release
+
+| Scenario | Required result |
+| --- | --- |
+| New client with domain and UK campaign | Client resolves once; provider and jurisdiction evidence appear; pack returns to Needs review |
+| Existing client with another offering | Relevant facts and preferences reused; fresh offering details researched; no duplicate client |
+| Missing countries or platform | Draft can be saved; research job is not enqueued |
+| US campaign with a named state | Country and state applicability are recorded separately and retrieved for that campaign |
+| Cross-client query or adversarial source instructions | Other-client records are not returned; source text cannot grant tool permissions or publish campaigns |
+| Removed or replaced document | Old content leaves active retrieval; dependent claims/campaigns are marked for recheck |
+| Image/search failure | Accurate missing-capability or partial-pack state; retry does not duplicate successful artifacts |
+| Revision after internal approval | New immutable version requires review; the prior approval remains historical and cannot approve new content |
+| Internal then client approval | Exact-version decisions recorded separately; campaign becomes ready to launch, not Running |
+| Passing Hermes update | Applied automatically, with exact diff/version and an after-update notification; no approval action required |
+| Failing update or post-update regression | Previous version retained or restored, with failure/rollback evidence and notification |
+| Worker restart or notification delivery failure | Work resumes idempotently; no lost pack/update events; notification can retry |
+
+Run a small reviewer-labelled dataset through the full workflow and compare claim support, citation applicability, corrections, and preparation time. Use seeded examples for automation and a real provider only with authorised material and reviewer participation. Store test outcomes as actual measurements; keep fictional UI counts and example findings separate from pilot evidence.
+
+For deployment, configure database backups, object retention, secret injection, job monitoring, notification delivery, and restoration procedures. Keep staging and production data separate. Connect only verified model routes, exercise a restore and an automatic-update rollback, then run the agreed pilot cases. Ad-account integration and performance dashboards can follow once the review workflow is reliable; the initial pilot can export approved materials with full provenance.
+
+## References and decisions to resolve
+
+The production framework and service choices remain implementation decisions; the public guide remains a static frontend. Confirm the first provider/offering/market, reviewer memberships, destination and export requirements, image-route mapping, document limits, budget, retention, notification channel, and deployment runtime during setup.
+
+- [React component/state design](https://react.dev/learn/thinking-in-react): component hierarchy and explicit visual states.
+- [FastAPI application structure](https://fastapi.tiangolo.com/tutorial/bigger-applications/): API modules and shared dependencies.
+- [PostgreSQL row security](https://www.postgresql.org/docs/current/ddl-rowsecurity.html): record-level policies and role caveats.
+- [Hermes persistent memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) and [skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills): underlying profile/memory/skill mechanisms.
+- [Configured model proxy](https://huggingface.co/spaces/bardd/gravityyy-proxyyy): requested gateway; real route capabilities require authenticated testing.
+
+Specification updated: 3 November 2026. No new model inference or campaign-specific legal analysis was performed for this documentation update.

BuxUp_System_Plan.md

@@ -4,7 +4,7 @@
 
 A dashboard-first campaign workspace for payment providers. Users see every client’s campaigns, review queues, approval status, and running work in one place. A **New campaign** button opens a structured dialog for a new or existing client, the offering, and the countries where the ads will run. Hermes researches the provider and the applicable product-promotion requirements, prepares platform-specific materials, and returns them for review.
 
-**Working system plan · Version 4 · 2 November 2026**
+**Working system plan · Version 5 · 3 November 2026**
 
 This is the proposed product experience and architecture, ready to read and extend. The diagrams and workspace previews explain the planned system; they are not connected to live client records or model inference on this documentation page.
 
@@ -330,120 +330,13 @@ If the new campaign targets a different state or country, Hermes loads that geog
 
 This is the intended experience: **start with existing knowledge, ask only for what changed, create new versions, and make the reasoning visible.**
 
-## 15 — What to build first, and how to judge it
+## 15 — What the pilot should prove
 
-The first pilot should demonstrate a dashboard across clients, accurate status KPIs, the new/existing-client campaign dialog, mandatory target countries, a grounded provider profile, platform drafts and images, cited product-promotion research, separate internal/client approvals, and a second campaign that reuses the right history. Include a Hermes improvement that passes automatic checks, applies without human approval, and generates an inspectable notification. Keep the first live market and offering narrow even though the architecture supports more locations and clients later.
+The pilot should demonstrate a dashboard across clients, accurate status KPIs, a new/existing-client campaign form, mandatory target countries, a source-backed provider profile, platform drafts and images, cited product-promotion research, and separate internal/client decisions. A second campaign should reuse relevant history while refreshing stale facts. A Hermes improvement should apply automatically and leave an inspectable notification explaining what changed and why.
 
-1. **Capability checks:** verify the authenticated main route, real search citations, one image/PDF extraction, and actual image output through the proxy. Store results and explicit unavailable states.
-2. **Dashboard and client foundation:** build status queues and KPIs, the campaign dialog, stable client identity, profile and file controls, mandatory countries, research evidence, and a profile confirmation step.
-3. **Campaign loop:** add platform-specific drafting, images, scoped product/promotion research, revision handling, separate internal and client approval capture, and truthful running status.
-4. **Reuse test:** run a second campaign for the same client. Confirm that relevant context is reused, expired facts are refreshed, and unrelated client information is absent.
-5. **Hermes admin and learning:** retain client feedback from day one, show automatically applied skill/mode/configuration updates with reasons and evidence, verify notification delivery, and demonstrate failure handling and rollback without an approval gate.
+Measure preparation time, reviewer effort, revision count, factual corrections, citation quality, claims with evidence, context reuse, and cross-client isolation. If a live campaign runs, also measure eligible inquiries and provider feedback; clicks alone are not proof of acquisition value.
 
-Measure preparation time, reviewer effort, revision count, factual corrections, quality of citations, proportion of claims with evidence, context reuse, and cross-client isolation. If a live campaign runs, also measure eligible inquiries and provider feedback; early clicks alone are not proof of acquisition value.
-
-Open decisions to fill in next: the first provider, exact offering, initial country or state, reviewer roles, publishing permissions, image-route mapping, document limits, approved research sources, memory retention, budget, and the pilot’s success thresholds.
-
-## 16 — Detailed implementation plan
-
-Build the pilot as a real application behind the dashboard, with a durable job system and a separate Hermes worker. Keep this public guide as the planning artifact. The existing static Space can host the frontend; backend API, workers, database, object storage, and secret configuration need an actual runtime and persistent services. A browser-only prototype cannot execute the planned agent system.
-
-**Proposed pilot stack:** React with TypeScript for the dashboard, a Python FastAPI application for authenticated APIs, PostgreSQL for transactional records and retrieval metadata, S3-compatible object storage for source files and generated media, and a Redis-backed task queue for long-running jobs. Run Hermes through a dedicated worker adapter and call the existing proxy from server-side model adapters. These are implementation choices to validate in the first setup phase, not dependencies already installed or a claim of a completed backend.
-
-**Build order and dependencies**
-
-| Phase | Concrete work and deliverables | Exit condition |
-| --- | --- | --- |
-| 0. Capability spike | Authenticate to the proxy from a worker; exercise main reasoning, grounded search, a PDF, an image input, and actual image generation; capture structured outputs, errors, and route resolution | Each required capability is verified, or explicitly unavailable with a named alternative; text-only image output is a failure |
-| 1. Application foundation | Set up frontend/API/worker projects, server-held secrets, migrations, persistent storage, authentication, organisation/client roles, deployment environments, and operational logs | Authorised users can create clients and retrieve their own records; cross-client access tests fail as expected |
-| 2. Dashboard and intake | Implement KPI queries, paginated/filterable campaign lists, New campaign dialog, new/existing client paths, canonical-domain matching, required countries, optional files, and saved drafts | Counts and lists agree; repeated submission creates one campaign; incomplete drafts cannot enqueue research |
-| 3. Knowledge and files | Fetch provider sources, extract uploaded documents, retain source versions and dates, normalize facts, record conflicts, and apply deletion/replacement invalidation | Profile facts trace to evidence; removed material is absent from active retrieval; stale facts require refresh |
-| 4. Campaign orchestration | Build resumable stages for context, provider research, location research, planning, copy, images, review, and pack assembly | A job survives restart; a failed stage can retry without duplicating artifacts or losing successful stages |
-| 5. Completed pack and decisions | Build the final-results page, platform variants, highlighted findings, source drawer, export, change requests, versioned internal/client decisions, and notification links | An operator can inspect a pack, request a revision, approve internally, then record client approval without marking it running |
-| 6. Scoped learning | Retrieve private client history, applicable country/state knowledge, and active global skills; write feedback with evidence, validity, and version | Second campaign reuses relevant facts; different clients remain isolated; expired facts are rechecked |
-| 7. Autonomous updater | Implement detection, versioned change preparation, automated evaluation, automatic application, notifications, monitoring, and rollback | A passing update applies without human approval; a failed check preserves the previous version; a regression rolls back and notifies |
-| 8. Pilot release | Seed agreed provider/offer/market, run end-to-end examples, exercise failure recovery, restore a backup, and document operating procedures | Pilot acceptance checks pass and reviewers can complete the full workflow from the dashboard |
-
-Phases 0–3 establish the dependencies for a grounded pack. Phase 4 feeds phase 5; phase 6 uses the same versioned sources and decisions. Build update logging and version capture early, then enable phase 7 once repeatable evaluations and a rollback path exist. Scope the first pilot to one offering and market, with multiple clients represented to test isolation. Do not estimate a firm delivery date before the capability spike and deployment choices are resolved.
-
-**Data model and storage contracts**
-
-Use organisation_id and client_id on private records. Campaigns reference one client; campaign_versions are immutable snapshots of the brief, jurisdictions, evidence set, skill/configuration versions, and artifacts. An approval points to one campaign_version and its artifact manifest hash, rather than to a mutable campaign title. All writes include an actor or job identity and timestamp.
-
-Core tables: organisations, users, memberships, clients, client_roles, sources, source_versions, extracted_chunks, facts, campaigns, campaign_versions, jobs, job_steps, artifacts, review_findings, decisions, memories, agent_updates, active_version_sets, notifications, and audit_events. Media bytes belong in object storage; database rows hold references, checksums, ownership, and versions. Retrieval queries enforce permissions before ranking, not after returning a mixed-client result.
-
-Store legal/research applicability with country, subdivision, product/service category, audience, source URL, publication/effective dates when available, checked_at, recheck_at, and uncertainty. Geographic sources can be shared when public; private client evidence cannot be promoted into that shared store. Store provider facts separately from legal applicability and reviewer preferences.
-
-**API and event boundaries**
-
-| API or event | Contract |
-| --- | --- |
-| POST /clients and GET /clients | Resolve canonical domains, create clients idempotently, and return only authorised records |
-| POST /campaigns | Save new/existing-client brief, mandatory research fields, country/subdivision scope, and selected platforms |
-| POST /campaigns/{id}/runs | Validate readiness; enqueue one run using an idempotency key; return job ID and initial status |
-| GET /dashboard and GET /campaigns | Return scoped KPI counts and filtered campaign lists from the same status definitions |
-| GET /jobs/{id} and progress events | Report stage state, partial completion, retryable errors, and cancel status without exposing secrets |
-| GET /campaigns/{id}/versions/{version}/pack | Return exact copy/images, findings, evidence manifest, uncertainties, and review history |
-| POST /campaigns/{id}/revisions | Attach reviewer instructions to a base version and enqueue only the affected work plus rechecks |
-| POST /campaigns/{id}/decisions | Enforce reviewer role, expected version/hash, current state, and required reason for changes/rejection |
-| POST /sources and DELETE /sources/{id} | Create upload/extraction records or invalidate source content and its active retrieval dependencies |
-| GET /agent-updates and GET /agent-updates/{id} | Display automatic update history, exact changes, tests, versions, notification status, and rollback evidence |
-| POST /agent-updates/{id}/rollback | Restore the prior compatible version, record reason, and notify; no approve-update endpoint is needed |
-| pack.ready and agent_update.applied | Persist events and notification delivery with retries; user acknowledgement has no activation effect |
-
-These are proposed API contracts, not endpoints already served by the current Space. Use server-side authorization on every record operation and signed, short-lived access to permitted files. Frontend status labels come from backend state, not independent optimistic counters. Optimistic concurrency prevents a reviewer approving a version that changed while the pack was open.
-
-**Campaign worker sequence**
-
-1. Validate the brief and client access; capture a run ID, input hash, campaign version, target scope, and active skill/configuration version set.
-2. Retrieve relevant client facts and previous campaign lessons. Refresh stale facts and extract new files; keep conflicting or missing information explicit.
-3. Research the provider’s offering and the laws, regulatory guidance, and platform policies potentially applicable to this product, audience, country, and subdivision. Save source text references and dates, not only search snippets.
-4. Construct a source-backed brief and platform plans. Generate structured copy with claim-to-source links and visual briefs; request images through the verified image adapter.
-5. Run the separate review job on actual copy, image text/content, destination, targeting, and source evidence. Return structured findings with applicability and uncertainty.
-6. Assemble the immutable artifact manifest and final campaign pack. Mark complete or partial accurately; enqueue the Needs review notification with a direct link to the exact pack version.
-7. Persist review decisions and revision instructions. Re-run only changed dependencies, while rechecking anything invalidated by the change. Capture client decisions separately from internal approval.
-8. After a separately authorised export or publication integration, collect actual available outcomes and feedback. A prepared or approved pack alone never increments the Running KPI.
-
-Give each step a persisted state, input/output hash, attempt count, timeout, usage, and error classification. Retry transient failures with bounded backoff; return permanent failures or exhausted retries to the dashboard. Idempotent artifact writes and unique job keys prevent duplicate generations after restarts. Cancellation stops new downstream work and records already incurred usage. Partial packs clearly identify failed/missing artifacts.
-
-**Proxy and Hermes integration**
-
-Create adapters for reasoning, web-grounded research, document reading, and image output. They normalize returned text, citations, media, usage, request IDs, resolved model names, and errors into typed application records. Keep requested aliases configurable, including gemini-3.8-flash-tiered and the requested gemini-3.1-flash-lite image alias. The initial capability test must establish its actual image route mapping before the image stage is enabled.
-
-Hermes’s built-in memory is bounded and profile-scoped; it is not the campaign database. Isolate worker profiles/home directories so concurrent jobs cannot write into one shared private memory file. Supply client context through the permission-scoped application store or a suitably scoped external memory provider; distribute global skills as versioned shared resources without client-private content. See the official [persistent memory](https://hermes-agent.nousresearch.com/docs/user-guide/features/memory) and [skills](https://hermes-agent.nousresearch.com/docs/user-guide/features/skills) documentation for the underlying mechanisms. The BuxUp update service, deployment handlers, and notification dashboard described here are application components to implement.
-
-The Hermes adapter receives an explicit task envelope and permitted source/context handles; it returns artifacts and update events through application services. Durable business state remains in the database. Use one controlled context/session per job and client. A worker crash must not make the application lose campaign state. Store redacted diagnostic traces separately from user-facing explanations; the final pack shows conclusions, supporting evidence, and uncertainty.
-
-**Autonomous self-improvement implementation**
-
-Record failure patterns, reviewer corrections, repeated source gaps, and job efficiency signals as improvement inputs. Hermes prepares a machine-readable update manifest containing scope, reason, evidence references, diff, dependency versions, evaluation plan, expected impact, and rollback target. Supported change handlers cover memory, skills/prompts, model/configuration settings, and application-code releases; each uses an explicit versioned apply interface.
-
-Run automated schema checks, regression examples, source-quality checks, client-isolation checks, budget/time limits, and relevant component tests in a separate test environment. A passing candidate is applied automatically: switch the active version pointer transactionally for skills/configuration, or deploy a versioned application build through the deployment worker for code changes. Compare the expected base version before applying so simultaneous updates cannot overwrite each other. No human review or approval gate sits in this path.
-
-Persist the applied update and an outgoing notification in the same transaction (or equivalent durable event mechanism). Notification delivery retries independently; a temporary inbox failure does not roll back an otherwise successful update. Capture who/what was affected, before/after behavior, checks, version, timestamp, and recovery link. Monitor error rate, source support, latency, and cost against the baseline. On a detected regression, restore the previous compatible version automatically and notify again. An admin can also invoke rollback and inspect its reason/history.
-
-Runs already in progress keep their version snapshot. New runs receive the new active version set. Schema changes need reversible or backwards-compatible migrations; destructive data migrations should be handled as separate migration work with backups rather than being treated as a simple skill-file edit. External account access still depends on real credentials and infrastructure capabilities. Autonomous updates do not bypass the application's tenant boundaries or become campaign publication decisions.
-
-**Acceptance tests and release checks**
-
-| Scenario | Required result |
-| --- | --- |
-| New client with domain and UK campaign | Client resolves once; provider and jurisdiction evidence appear; pack returns to Needs review |
-| Existing client with another offering | Relevant facts and preferences reused; fresh offering details researched; no duplicate client |
-| Missing countries or platform | Draft can be saved; research job is not enqueued |
-| US campaign with a named state | Country and state applicability are recorded separately and retrieved for that campaign |
-| Cross-client query or adversarial source instructions | Other-client records are not returned; source text cannot grant tool permissions or publish campaigns |
-| Removed or replaced document | Old content leaves active retrieval; dependent claims/campaigns are marked for recheck |
-| Image/search failure | Accurate missing-capability or partial-pack state; retry does not duplicate successful artifacts |
-| Revision after internal approval | New immutable version requires review; the prior approval remains historical and cannot approve new content |
-| Internal then client approval | Exact-version decisions recorded separately; campaign becomes ready to launch, not Running |
-| Passing Hermes update | Applied automatically, with exact diff/version and an after-update notification; no approval action required |
-| Failing update or post-update regression | Previous version retained or restored, with failure/rollback evidence and notification |
-| Worker restart or notification delivery failure | Work resumes idempotently; no lost pack/update events; notification can retry |
-
-Run a small reviewer-labelled dataset through the full workflow and compare claim support, citation applicability, corrections, and preparation time. Use seeded examples for automation and a real provider only with authorised material and reviewer participation. Store test outcomes as actual measurements; keep fictional UI counts and example findings separate from pilot evidence.
-
-For deployment, configure database backups, object retention, secret injection, job monitoring, notification delivery, and restoration procedures. Keep staging and production data separate. Connect only verified model routes, exercise a restore and an automatic-update rollback, then run the agreed pilot cases. Ad-account integration and performance dashboards can follow once the review workflow is reliable; the initial pilot can export approved materials with full provenance.
+Agree the first provider, offering, country/state, reviewer roles, publishing permissions, and success thresholds before the pilot. The separate **Implementation plan** reading mode contains the frontend specifications, backend contracts, build sequence, and release checks.
 
 ## Sources and review notes
 
@@ -455,4 +348,4 @@ For deployment, configure database backups, object retention, secret injection,
 - [Google image generation](https://ai.google.dev/gemini-api/docs/image-generation) and [search grounding](https://ai.google.dev/gemini-api/docs/google-search): upstream capability references, not proof of a proxy alias’s live behavior.
 - [FCA financial promotions overview](https://www.fca.org.uk/firms/financial-promotions-adverts): a starting source for relevant UK research; this guide contains no campaign-specific legal determination.
 
-Review date: 2 November 2026. Proxy source and health were inspected; authenticated inference, image generation, PDF extraction, and production campaign execution were not tested as part of this documentation update.
+Plan updated: 3 November 2026. Earlier proxy source and health checks were retained; authenticated inference, image generation, PDF extraction, and production campaign execution were not tested as part of this documentation update.