references/dashboard-lifecycle.md

# Shared Real-Dashboard Lifecycle

Treat each real seller or leadership dashboard as a durable, user-customizable operating canvas, never as the fictional Meridian demonstration or a disposable report.

## Orient The User And Establish Their Goal

Before the first clarification, form, source resolution, or local inspection, load the Sales index, focused persona skill, shared instructions, dependencies, and this lifecycle; reading installed instructions is safe setup, not inspecting user files or connectors. Resolve only the earliest unsettled stage: verified role mismatch, matching unpublished-local-dashboard choice, dashboard goal, then design style. Every `request_user_input` call must contain exactly one question object (`questions.length === 1`) and exactly three options; wait for its answer before a separate call for the next stage, even within the same execution turn. Never combine stages or provide the client-added Other option. Honor an explicit request to ask in chat instead.

Ordinarily recommend one private dashboard deployed to Sites and bookmarked for this user as the ideal ongoing setup. Explain that it is first tailored and built locally, published only with permission, kept current only by one approved read-only automation, and available to customize over time. If the user requests only an existing-dashboard choice first, ask only that question; defer discussion of publishing, automation, goals, and style until it is answered. Ask these questions one at a time, never simultaneously.

Before goal/style selection, inspect only the relevant linked workspace or already identified user-owned project for exactly one unpublished dashboard matching verified viewer, persona, represented target, authorized scope, and mode; never perform a broad filesystem or Site scan. If the user already supplies an authoritative matching project identity, rely on it without inspecting files, profiles, CRM, or connectors. Ask the existing-dashboard question only after exactly one matching unpublished dashboard is verified or authoritatively identified. If no matching dashboard exists, skip this question and proceed directly to the dashboard goal or the next genuinely unsettled stage; account names, a requested persona, an unverified candidate, or a matching published Site do not imply an existing unpublished dashboard. Unless the current request already specifies the action, ask one separate `request_user_input` question with exactly **Use existing (Recommended)**, **Modify existing**, and **Create new**; otherwise ask one concise question with those same three choices. Use or modify preserves the same project and saved preferences; create a second dashboard only after the user explicitly selects **Create new**. A matching published private Site is reused or updated by default without this question.

For both personas, selectively personalize goal choices from reliable existing user memories and quickly available, already-authorized context: the current conversation and request, user memories already available in context, an already-loaded authorized role/team/portfolio or profile result, and an already identified matching dashboard's saved preferences. Explicit current-task preferences override saved conventions; use coarse role, team, industry, portfolio, workstream, or design-taste cues only for wording, never as proof of a role, account, metric, source access, or authorization. Use only immediately available context; never perform additional connector probes, searches, or lookups; never inspect other conversations, history, files, CRM, email, Slack, or profiles solely to tailor choices, widen access, or add questions; never invent or disclose private memory details or persist a one-off preference. Keep stable persona fallback defaults when relevant context is insufficient, and retain citations and normal authorization for every factual dashboard claim.

When the user has not already clearly supplied one primary goal, ask exactly: **What do you want front and center in your dashboard? You can always customize this later.** Prefer `request_user_input` with exactly three distinct, substantive persona-specific goals from the focused skill; personalize their descriptions and wording using immediately available authorized context, put the recommended choice first, and suffix its label `(Recommended)`. The client automatically adds free-form **Other**. A broad request naming multiple outcomes does not establish which emphasis the user prefers, so still ask this goal question. Otherwise ask that exact question with the same three choices in chat. Honor one clearly stated or previously saved primary goal without asking again; choosing a focus changes emphasis without removing other grounded dashboard capabilities.

For a seller, always retain the complete grounded Home, Accounts, and Pipeline operating canvas. The saved goal determines only a compact top-of-Home **Your focus** module: verified account priorities and changes, verified opportunity risk and blockers, or verified upcoming meetings and follow-ups. Omit the module when no relevant evidence exists. Preserve working account search, grounded group filters, sourced sorting, seller/customer context, verified stakeholders and next actions, and the existing durable project; never fabricate evidence or create a second dashboard to represent the chosen emphasis.

## Select A Design Direction And Generate Its Visual Reference

After the goal is clear, separately ask: **What look and feel would you like for your dashboard?** unless the user already supplied a direction or the existing dashboard has a saved style. Offer exactly three mutually exclusive visual personalities. The first option is always **Codex Default (Recommended)** with the exact picker description **Clean surfaces, crisp type, quiet contrast.** Use model judgment to choose options two and three as context-appropriate alternatives from the exact canonical catalog below; personalize those choices using the user, persona, goal, reliable existing memories, and immediately available authorized context, but never use a fixed alternative pair. Keep every picker description to at most eight words, adapted from the catalog's character rather than packed with implementation detail.

Treat **Codex Default** as an internal design preset, not a thirteenth catalog direction. Its implementation parameters are: light theme; medium density; system sans typography; `#f6f6f6` page, `#ffffff` primary surfaces, `#f0f0f0` secondary surfaces, and `#e5e5e5` tertiary surfaces; `#171717` primary text and accent; `#626262` secondary text; `#d2d2d2` borders; 6px control radii and 10px medium-container radii; restrained hairline or small shadows; and monospace only for identifiers or code-like values. These parameters mirror the OpenAI/Codex desktop tokens. The dashboard's 44px interactive-target requirement overrides compact source-token control sizing; accessibility, verified-data, and functional-control requirements always take precedence.

The twelve alternative directions remain:

| Direction | Character | Density |
| --- | --- | --- |
| Precision Modern | Crisp grid, warm white, ink, one sharp accent | Medium |
| Executive Briefing | Editorial typography, narrative headlines, restrained charts | Low |
| Mission Control | Dark mode, live status, layered operational detail | High |
| Electric Neon | Charcoal canvas, acid green/violet, glowing signals | Medium–high |
| Swiss Data System | Strong grid, bold type, primary-color blocks | High |
| Soft Utility | Tinted neutrals, rounded controls, approachable calm | Medium |
| Terminal Intelligence | Monospace, command-line cues, raw data confidence | Very high |
| Glass Observatory | Deep gradient, translucent panels, atmospheric charts | Low–medium |
| Financial Ledger | Dense tables, precision numbers, subtle red/green | Very high |
| Magazine Dashboard | Big visual stories, asymmetric composition, curated metrics | Low |
| Builder’s Workbench | Practical, modular, component-library feel | Medium–high |
| Arcade Analytics | Retro-futurist, pixel/signal motifs, playful urgency | Medium |

Preserve each alternative's exact canonical name and its catalog character and density internally without inventing capabilities. Options two and three may be any two of the twelve: dark, neon, translucent, pixel, or playful aesthetics remain selectable when context supports them and must stay professional, readable, accessible, and usable. Only **Codex Default** carries `(Recommended)`; do not suffix either contextual alternative. Existing saved or user-specified custom styles remain valid without re-asking; the client automatically adds free-form **Other**, so never include an explicit Other option. When `request_user_input` is unavailable, ask the same exact question with the same three options. Never imply that visual status is live without verified freshness, that urgency exists without sourced evidence, or that decorative terminal cues run real commands.

After goal and style are known, establish which sections, metrics, charts, rows, and interactions the normal authorized CRM or user-provided evidence actually supports before crafting the storyboard; an intentional empty placeholder still requires no CRM. Never probe sources solely for personalization or speculative widgets. If the user explicitly declines image generation, skip it entirely without an image-permission question or image-tool call. Otherwise invoke and follow the available `imagegen` skill, using its built-in `image_gen` tool to generate exactly one polished `ui-mockup` storyboard showing two or three key screens or states with credible and implementable interactions from verified available data; inspect and use this visual reference before implementation. Include the selected exact direction, character, density, palette, materials, typography, and genuinely feasible interactions in the anonymized storyboard prompt, then carry that same visual design into the implemented dashboard; if coverage is unknown, depict only clean core structure, never speculative KPIs, targets, attainment, charts, or controls. Neon, dark, glass, retro-futurist, pixel, or playful motifs are permitted when they belong to the selected direction; exclude unsupported warning/meta panels, placeholder metric tiles, invented status, pointless radar rings, flashing effects, inaccessible contrast, and dead controls. A Codex pet may appear only when the user supplies an authorized genuine asset and its use fits the request; never generate, imitate, trace, search for, or assume a Codex pet, and omit it otherwise. Use only anonymized labels and empty placeholder data; never include real customer names, CRM values, personally identifiable information, private memory details, secrets, or source credentials in the image prompt. Copy any generated image from `$CODEX_HOME/generated_images/...` into the same stable user-owned dashboard project, and preserve the selected goal, style, and available image path as its durable design reference. The built-in tool needs no API key; never switch to a CLI fallback unless the user explicitly requests it.

Use the existing polished demo template only as an optional starting scaffold. Let the chosen goal, exact visual direction, character, density, and feasible image reference determine the result; implement real CSS-variable, theme, typography, component, and layout overrides rather than merely labeling an unchanged template. A selected dark direction must consistently restyle canvas, surfaces, text, muted content, borders, sticky bars, charts, focus indicators, and the document's theme color; glass needs readable contrast and an opaque fallback, and red/green comparisons need redundant text or icons. Tune spacing and density without sacrificing readability, responsive/mobile layout, reduced-motion preferences, or 44px interactive targets. Keep status and urgency evidence-backed, terminal cues purely visual unless real authorized commands exist, and every visible control functional. Preserve exactly one renderer-compatible persona payload assignment (`const payload =` or `window.__LEADERSHIP_DATA__ =`), grounded data bindings, concise required placeholder/representative disclosures, event handlers, and the existing project/Site identity. On later updates, reuse the saved goal, style, and image reference without re-asking or regenerating unless the user requests a new direction or the reference is unavailable; preserve the customized HTML/theme and populate the finished dashboard only with authorized, verified real data or a genuinely empty placeholder.

## Match The Current User To The Dashboard Persona

Use reliable role evidence already available from the current user's profile, authorized CRM ownership or team membership, or the user's own explanation; never probe additional connectors solely to determine a role. A seller dashboard fits a seller or verified account owner; a leadership dashboard fits a sales manager, sales leader, or executive. An unknown, ambiguous, or unverified role is not a mismatch and must not interrupt the normal grounded workflow.

When the current user's role is verified and incompatible, and no explicitly identified, authorized target user was already supplied, briefly explain the mismatch and offer three choices before continuing:

1. A clearly labeled, viewer-owned empty **placeholder** containing no accounts, opportunities, forecasts, metrics, invented sources, or fictional examples; this option can be created without CRM.
2. A clearly labeled **representative** dashboard grounded exclusively in verified records already accessible to the current user, showing the actual represented owner/team, verified sources, and evidence gaps without implying it is the viewer's own account book or team; the represented owner must not be the requesting viewer.
3. A dashboard for a **target user** the current user identifies, after verifying that person's real role, account/team scope, and the requesting user's authorized access.

Wait for the user's choice unless they already specified one. Keep the viewer and represented target distinct; never impersonate a seller or leader, imply unverified authority or ownership, broaden authorized access, invent metrics or other customer data, or treat a placeholder or representative view as a real dashboard for the viewer.

Use renderer `--mode placeholder` or `--mode representative` with matching top-level `dashboardMode`, a `dashboardLabel` visibly containing that mode, and `dashboardIdentity` with the matching `persona`, the verified current viewer as `owner`, and a stable viewer-owned `scope`. A placeholder keeps source lists and account/opportunity collections empty and includes no forecast, metric, or seller/leader role claims. A representative view separately retains the actual verified represented owner/team, authorized scope, and persona-specific verified sources. An authorized target user follows the normal default `--mode real` path. Never change modes when refreshing an existing dashboard.

## Select Exactly One Existing Dashboard

Reuse a current user-linked private Site, a matching existing project's `.openai/hosting.json` project ID, or exactly one verified match on owner, persona, and account/team scope. Also require the same viewer, represented target, and placeholder/representative/real mode when applicable. Preserve that dashboard's URL, project identity, source, and customizations. Never select Meridian, another owner's Site, an unrelated project, an incomplete identity, or an ambiguous match; ask the user to resolve any genuine ambiguity instead of guessing or creating a duplicate. Only an explicit **Create new** selection permits a separate local project.

For a confirmed existing private Site, refresh the same authorized source project and deploy only within the applicable hosting-approval boundary. Follow the installed `sites-building` and `sites-hosting` instructions for the actual existing-project lifecycle; do not replace its source, package manager, hosting metadata, or customized layout with a new starter.

## Start Locally And Ask Before Publishing

Without a matching private Site, choose a stable user-owned workspace project keyed to the owner, persona, and scope; never use the installed plugin package or a disposable temporary directory. Render or iterate locally, return the actual working local dashboard first, and offer to create a private Site as one optional next step.

The user's local-first preference overrides the Sites skills' normal auto-publish default. Never call site creation, publish a new Site, change hosting, broaden access, or share externally unless the user explicitly agrees and the operation satisfies its normal approval/security requirements. After explicit private-hosting approval, consult `sites-building` and `sites-hosting`, retain the returned project identity and URL, and use that same project on subsequent requests.

## Offer Exactly One Next Step

After the first working dashboard, offer these one-line next steps one at a time, based on its verified state:

1. Without a matching private Site: ask exactly **Would you like me to publish it with the Sites feature so you can access it from the web?** Publish privately only after explicit approval; public visibility requires separate express authorization.
2. Once that Site exists: offer one read-only refresh automation at a useful cadence, such as weekday mornings, to keep the same dashboard current.
3. Once that automation exists: invite the user to add, customize, or improve the dashboard over time.

Before offering or creating an automation, inspect matching active and paused automations for the same viewer, persona, represented target, authorized scope, and Site; reuse or explicitly update an existing match instead of creating a duplicate. Keep ranking-only automations distinct from full-dashboard refreshes; when one would conflict, offer to upgrade the existing automation while preserving its ranking scope rather than creating a competing schedule. Create or update an automation only after explicit user approval and through `automation_update` when available; never edit automation files directly. Publishing always requires its own separate explicit approval.

## Refresh Grounded Data Without Resetting The Canvas

Populate the matching demo-owned HTML template exclusively with verified real user/customer evidence, except for an explicitly marked, clearly labeled empty placeholder with no CRM or invented facts. `scripts/render_real_dashboard.py --persona seller|leadership --mode real|placeholder|representative --payload <verified-payload.json> --project-dir <stable-user-owned-project>` safely embeds the correctly labeled payload, refuses fictional or unverified-source payloads, rejects incomplete dashboard identity and symlinked projects or pages, preserves customized HTML during refresh, and never creates, publishes, or shares a Site.

Real and representative dashboards require at least one honest verified source in seller `connectedSources` or leadership `sourceCoverage`; an authoritative user-supplied export qualifies when the source record names that actual export instead of inventing a connected CRM or connector. Apply the same omission rules to dashboard HTML and conversational fallback: never display missing-value sentinels or warnings, invented priorities or account-rank ordinals; preserve account order without assigning priority and keep distinct verified account values and opportunity amounts separate. Retain authorization scope, freshness, and user-requested views and preserve verified zero values; never fabricate missing accounts, owners, stakeholders, replies, meetings, sources, forecast targets, weekly movement, seller growth, or scenarios. CRM reads, hosting changes, external sharing, CRM writes, outreach, and automation creation keep their separate approval and security boundaries.

## Verify Every Visible Element Before Handoff

Every visible section, card, chart, tab, search field, and control must be populated with verified evidence, actionable, and genuinely functional. Hide unsupported quota, target, attainment, weekly movement, and other missing-data sections entirely. Never display empty **Unavailable** widgets, **Quota / attainment unavailable**, **No invented target or attainment**, **Evidence & limits**, **Forecast integrity**, evidence-limit or integrity warnings, internal grounding commentary, placeholder metrics, fake radar/status widgets, nonfunctional themed controls, flashing effects, giant decorative whitespace or hero treatments, dead navigation, or nonworking search/buttons. A chosen neon, dark, glass, retro, or playful visual treatment is valid; it never licenses invented data, fake urgency, inaccessible contrast, or pointless radar rings. Explicit placeholder mode may show one clean intentional empty state with no fake functionality; required representative disclosures remain concise.

Before handoff, use a real browser to click every visible navigation item, tab, and button; exercise sorting, search, and filters; open each account drawer/popover; validate close/outside-click, focus-trapping and restoration, Escape, and responsive desktop/mobile behavior; inspect chart values and labels; and verify every row and card against its authorized source evidence. Implement smooth, polished, GPU-friendly opacity/transform drawer/popover animation with an accessible `prefers-reduced-motion` fallback. Remove unsupported or nonworking sections and controls rather than disabling or explaining them. Mention only decision-critical evidence gaps briefly in the conversational response, never in dashboard panels.