# Product and engineering handoff

This package proposes a complete visual and interaction direction. It does not replace backend authorization, change deployed routes, or implement production behavior. Start with the existing contracts and use `route-coverage.csv` to prevent silent feature removal.

## Information architecture

The primary rail has three groups: Workspace (Overview, Intelligence, Inbox), Build & run (Applications, Stacks & catalog, Infrastructure), and Operate (Observability, Security, Cost). Organisation is a stable administrative utility. Help and the personal account remain at the foot of the rail.

Keep existing deep links working during migration. Introduce destination aliases and redirects only after route owners approve the mapping. Preserve organization, cluster, namespace, entity ID, time range, filters, and active tab in navigation. Treat cross-organization context changes as explicit user actions.

## Critical workflow contracts

### Investigation → reviewed action → verified outcome

The reference walkthrough uses one checkout deployment with four replicas. Two pods hit a memory limit after a rollout. An investigation links three sources; the plan changes the container limit from 512 MiB to 768 MiB; a human approves the exact diff; execution revalidates preconditions; a five-minute observation window validates readiness, latency, and error rate. All values are fictional.

Approval must be tied to the immutable plan version, scope, acting identity, and expiry. Any changed resource revision invalidates the relevant precondition. An approved plan is not carte blanche for newly discovered mutations. Execution records each step; partial failure does not erase completed steps. A rollback is a new reviewed action when policy requires it.

Suggested acceptance checks:

- Read-only mode cannot invoke write tools, including through untrusted context.
- A Viewer cannot gain approval authority through the frontend.
- Double-clicking approval does not create duplicate operations.
- Refreshing or leaving the page does not lose the run or its receipt.
- Stale evidence and stale plans are distinguishable and recoverable.
- Cancel/pause semantics explain whether an in-flight infrastructure call can stop.
- Budget exhaustion preserves evidence and does not automatically raise limits.
- “Verified” is impossible until the declared checks and observation window succeed.

### Application → deployment

Retain source-provider permissions and repository ownership. Detection produces inspectable configuration. Generated PRs are proposals, with branch/base and diff visible. Build logs, artifact identity, release history, preview lifetime, secret references, and deployment status remain first-class. A secret binding must not reveal its value in prompts, configuration previews, telemetry, or support bundles.

### Stack draft → ordered deployment

Graph editing writes a recoverable draft. The review screen shows changed fields, deletions, affected resources, dependency order, and preflight checks. Persist version/ETag metadata to handle concurrent edits. A deployment respects parent readiness and stops or proceeds according to an explicit failure policy. A partial retry must not replay unsafe side effects.

### Security finding → remediation

Distinguish unique finding from affected occurrences. Scope, severity, source freshness, fixability, and coverage stay visible. AI may prepare remediation but cannot silently suppress findings or grant exceptions. Exceptions require owner, reason, expiry, and audit. Reports include evidence time and uncovered resources.

### Cost opportunity → realized saving

Keep provider price estimates, forecasts, allocations, and invoices separate. Explain missing provider data and allocation rules. Rightsizing proposals include workload risk, observed usage window, headroom, estimated monthly impact, and verification. A proposed saving is not a realized saving.

## Implementation sequence

| Stage | Deliverable | Gate |
| --- | --- | --- |
| 1. Foundations | Tokens, semantic roles, typography, shared shell, density, core controls | Contrast, keyboard, responsive behavior, no inaccessible custom primitives |
| 2. Context and read-only routes | Overview, lists, detail layouts, filters, search, deep links | Existing route coverage and scoped data correctness |
| 3. AI workspace | Conversations, tasks, evidence, plans, inbox, runs | Permission and approval state-machine tests |
| 4. Delivery/infrastructure | Applications, drafts, stacks, provider adapters, Kubernetes explorer | Feature parity, recovery, safe operation idempotency |
| 5. Security/cost/admin | Findings, policies, cost provenance, billing, access/settings | Owner review of business and permission semantics |
| 6. Release | Instrumentation, staged rollout, accessibility, localization | Task-based usability and regression acceptance |

These are sequencing recommendations, not estimates or a commitment to a specific delivery schedule. Feature flags should allow incremental adoption of the shell and page families without replacing the entire product at once.

## System architecture recommendations

Use one scope model and one operation-status vocabulary across the UI. Keep backend response types, permission gates, event freshness, and polling/subscription behavior explicit. Source-specific adapters normalize presentation without concealing uncertainty. Feature flags must not substitute for authorization.

Prefer existing application primitives where they support the target behavior. Evolve the component library before copying artboards into independent pages. Add stories/fixtures for loading, empty, filtered-empty, unknown, disconnected, unauthorized, failed, partial, stale, expired, and verified states. Keep static placeholders out of production screenshots and analytics.

The design scene model is a reproducible authoring format, not a production UI framework. Its absolute coordinates serve visual review; implementation should use responsive layout primitives, semantic HTML, and actual data components.

## Working with the source package

- `design-lib.mjs`: semantic palette and vector/layout primitives.
- `foundations.mjs`: brand, component rules, responsive examples, and recovery states.
- `screens-intelligence.mjs`: AI operating loop and durable work.
- `screens-platform.mjs`: applications, stacks, catalog, and infrastructure.
- `screens-operations.mjs`: observability, security, and cost.
- `screens-admin.mjs`: organization, accounts, integrations, and AI configuration.
- `details.mjs`: deeper entity, authentication, report, and administrative patterns.
- `coverage.mjs`: current-route-to-design mapping and coverage boards.
- `render.mjs`: SVG export and dark color resolution.
- `figma-runtime.js`: native Figma import; `build.mjs` embeds the model into the shipped `figma-importer/code.js`.

Edit source files and rerun `node scripts/build.mjs`; do not hand-edit generated SVGs, model.js, or code.js unless intentionally breaking reproducibility. The shareable package rebuilds from `audit/route-coverage.json`; the original workspace can additionally regenerate its private evidence inventory from the portal source.

Browser validation uses `@playwright/test` from the original workspace's `portal/node_modules`. When running outside that workspace, install your team's approved Playwright setup and adjust the import path at the top of `scripts/verify-browser.mjs`. Start `node scripts/serve.mjs` before that test. The gallery itself has no build or dependency requirement.

## Quality results and limits

The generated reports are the current machine-readable record. Build checks cover missing targets and frame boundaries. Browser checks measure text width and overlap in rendered SVGs and exercise the main AI walkthrough, gallery search, and Escape dismissal. Semantic contrast tests validate chosen role pairs. The importer is tested against a local API mock, including same-page link destinations; that simulation cannot prove font metrics or every constraint of the live Figma runtime.

Before team publication, import into a new Figma file and inspect Overview, AI plan, Stack builder, a dark frame, and the mobile decision. Confirm text styles, shared control labels, navigation links, and dark-mode variable inheritance. Test the small Core walkthrough first if the editor is constrained. If an import fails, imported artwork may remain; Undo or use a new empty file for a clean retry. Existing artwork is not deleted by the importer.

The ZIP intentionally excludes private live HTML/text captures and source-inventory metadata. The design and screenshots use only illustrative data. No production code, configuration, infrastructure, payment, or customer-facing message was changed.
