Audience: System Admin, Support, Developer Related: Regression Testing · Organizations · Security and Organization Scoping · Data Retention and Purge

A Diagnostic Clone creates an isolated regression/test organization from selected, non-secret parts of a real organization. It is intended for organization-specific troubleshooting when logs or generic regression data are not enough.

The central safety rule is:

Investigate and experiment in the clone without changing the organization experiencing the actual issue.

The source organization is read during clone creation and targeted copy operations, but Diagnostic Clone workflows do not write repaired settings, test records, display assignments, shopping changes, or other experimental state back to the source.

When to use a Diagnostic Clone

Use a clone when the issue depends on one or more of these organization-scoped conditions:

configuration or rendering preferences;
a specific recipe, recipe cache state, or AI image status;
current Meal Planner data;
a Shopping List, Household List, Recipe Cart, or Kitchen Inventory state;
a display record or current assignment;
an active Let’s Cook session;
current-period organization AI usage/balance context;
a role- or permission-specific workflow.

Prefer read-only diagnostics, Job Status, Performance, Activity, Database Admin, or deployment logs when copying organization data is unnecessary. A clone is not a substitute for troubleshooting DNS, TLS, proxy headers, browser sessions, provider accounts, or physical hardware.

Where to create the clone

A System Admin starts a Diagnostic Clone from the source organization:

Return to the Default Organization context.
Open Administration → Organizations.
Use the 🧪 action beside the organization, or open Organization Details and select Create Diagnostic Clone.
Review the copy options and safety acknowledgement.
Create the clone.
Follow the generated run in Administration → Regression Tests.

If an active clone already exists, the organization action opens that clone or its run instead of creating another. Blackcap permits only one active Diagnostic Clone per source organization.

Regression/test organizations cannot be used as clone sources. The Default Organization can be used when needed.

What the initial clone copies

The initial configuration-focused clone creates exactly one isolated test organization and generated regression users. It copies safe organization configuration through the normal service layer, including applicable:

organization name/time-zone/locale-style preferences;
organization-scoped settings;
Meal Planner settings and slots;
Noun Project Footer settings and matching rules;
grocery departments and canonical/category mappings;
Kitchen Inventory storage locations;
organization AI entitlement/allotment configuration;
other non-secret organization preferences supported by the clone service.

Display rows may be copied as disconnected diagnostic records. If the source has no display, Blackcap can create a safe Mock display so display-dependent workflows can still be tested.

Optional current operational data

The creation page can copy a minimal current-state slice. The same current operational data can be synchronized again later because source state may change during an investigation.

Supported options include applicable current:

display assignments, display content settings, selected/displayed recipe references, and preview artifacts;
current Meal Planner week and recipes required by that week;
entries and recipes referenced by displays showing day/week/month meal-plan content;
active Let’s Cook sessions, recipes, steps/progress, timers, and display state;
the single current active standard Shopping List and related recipes;
Household List items, excluding external provider sessions/mappings;
Recipe Cart contents;
Kitchen Inventory, including on-hand and not-on-hand items;
current billing-period organization AI usage and balance, when that independent option is selected.

Repeated operational sync updates the diagnostic slice rather than duplicating the same Meal Planner slots, lists, sessions, inventory, or cart rows. User-facing names stay recognizable; internal IDs are regenerated and references are remapped to the clone.

When current-period AI usage is not copied, the clone starts with its normal configured monthly allotment. When it is copied, only the active billing-period snapshot and diagnostic-safe job context are included—not older periods, provider credentials, reservations unrelated to the snapshot, or the complete financial ledger.

Targeted copy after creation

Once viewing the Diagnostic Clone, feature pages can offer source-copy panels for focused reproduction:

Recipe Library: search and copy selected source recipes by title or recipe ID;
Shopping Lists: copy selected lists, related recipes, and current Recipe Cart context;
Meal Planner: copy source weeks containing data within the supported window around the source organization’s current planner week.

Recipe copy may include the recipe metadata, editable/converted content, ingredients, tags, safe source-facing paths, ready cache artifacts, thumbnails/images, cache metadata, and recipe-scoped AI image status needed to reproduce the issue. AI jobs and candidate assets are remapped to the diagnostic users/organization where supported.

Copy only the smallest data set needed. A focused recipe copy is safer and easier to interpret than repeatedly importing broad current-state data.

Data that is never copied as live access

Diagnostic Clone does not copy or activate:

passwords, password hashes, MFA secrets, recovery codes, trusted-browser tokens, reset material, or real user sessions;
source users or invitations as normal members;
API Tokens or Chrome Extension tokens;
OAuth access/refresh tokens;
Dropbox, Google Drive, SMTP, AI-provider, authentication-provider, voice-assistant, Noun Project, retailer, or external-list credentials;
browser profiles, cookies, or signed-in provider sessions;
backups or restore staging;
Support Request messages;
source audit history, unrelated background jobs, Performance history, or older AI usage periods;
receiver tokens, kiosk tokens, Remote Pi Client secrets, attached-panel credentials, or live hardware write targets.

Provider or display shell configuration can appear only in a disconnected, diagnostic-safe form. A copied display must not contact the real receiver, kiosk, Pi client, or physical panel.

Isolation and non-impact guarantees

The clone receives a new organization ID and new IDs for copied resources. Organization-owned reads/writes continue through the normal Active Organization and permission boundaries.

Testing in the clone can safely include:

changing organization settings;
rebuilding copied recipe caches;
reassigning diagnostic displays;
editing copied Meal Planner, Shopping List, Household List, or Inventory records;
running focused regression checks;
reviewing clone-specific Job Status, Performance, Activity, Database Admin, and display diagnostics;
trying a repair or migration hypothesis before separately reviewing production impact.

None of those clone changes are synchronized back to the source organization. A successful experiment is evidence for a proposed fix, not permission to mutate the source automatically. Re-read the live source state and obtain the required authorization before applying any real correction.

Generated users and permission testing

The clone creates generated regression identities rather than copying customer users. Where supported, enable the secondary user and lower-role tests to reproduce Org Admin or ordinary-user behavior. Generated credentials are shown through the regression run details and remain confined to the test organization.

Regression run and visibility

Diagnostic Clone is integrated with the regression harness:

the source organization is associated with the run for attribution;
run history remains platform/Default-owned;
the clone is always left open for investigation;
additional diagnostic regression tests can be appended to the same run after creation;
active diagnostic clones appear in the Regression Tests Test Organizations panel;
the clone is hidden from the normal customer Organizations list;
a banner and run links identify the source/clone relationship.

The Regression Tests page is platform-only and must be opened from Default Organization context. A support-context System Admin viewing another organization as an Org Admin does not gain platform regression access.

Reproduction workflow

Record the source symptom, timestamp, affected user/display/resource, and relevant request/job IDs.
Review the source with read-only diagnostics first.
Create the clone with only the required safe options.
Verify that no live display, provider, email recipient, cloud destination, or external browser session is attached.
Reproduce the issue in the clone.
Compare clone Activity, Job Status, Performance, database state, cache status, and regression steps.
Apply experimental settings or repairs only in the clone.
Document the root cause and proposed production change without copying customer secrets or unnecessary data.
Re-check the source before applying a separately reviewed fix.
Clean up the clone after evidence is retained safely.

Limitations

A Diagnostic Clone does not faithfully reproduce:

public DNS, Nginx/stunnel, TLS, trusted-proxy, or network-path problems;
provider authentication or the current state of external accounts;
real email delivery and recipient mailbox behavior;
signed-in Chrome Extension retailer/external-list browser sessions;
physical e-ink wiring, waveform, panel timing, or panel defects;
exact production concurrency/load or changes made after the snapshot;
a failure caused specifically by a secret, token, or user identity that is intentionally excluded.

A passing clone therefore does not disprove the source issue. It can indicate that an omitted external dependency, hardware condition, timing condition, or newer source change is material.

Cleanup

Use the regression cleanup action when the investigation is complete. Diagnostic organizations remain protected with their run details while the environment still exists; historical run/detail purge becomes eligible only after the clone environment is removed or marked purged according to the retention policy.

Before cleanup, retain only non-sensitive findings needed for the defect/support record. Do not preserve copied organization data in chat-style documentation.

Troubleshooting

Clone creation is blocked

Confirm you are a System Admin in Default Organization context, the source is not itself a regression organization, the safety acknowledgement is selected, and no active clone already exists.

A copied display does not reach the real panel

That is expected and required. Live tokens, client links, and physical targets are removed or replaced with safe diagnostic records.

Provider or external-list behavior is missing

Credentials and browser sessions are intentionally excluded. Use a dedicated non-production provider account or the provider connection test when the issue cannot be reproduced internally.

Copied data looks stale

Run the relevant targeted copy or Current Operational Data sync again. Compare the copy timestamp with the original incident before drawing conclusions.

The issue cannot be reproduced

Compare the copied categories with the source event, then investigate omitted dependencies such as browser/extension version, network path, provider page, hardware, load, or concurrent jobs.

Developer rules

Keep clone creation/copy behavior in regression_diagnostic_clone_service.py and established repositories/services.
Use explicit column lists, provider-aware transactions, and remapped organization/resource IDs.
Make every newly supported feature data type opt-in and scrub secrets/live targets.
Never retain cross-organization foreign keys to the source.
Test that clone creation and later syncs do not mutate the source.
Test both SQLite and PostgreSQL for copy order, constraints, booleans, timestamps, and ID remapping.

On this page