# PortaShape Product Experience

## One workspace, several lenses

PortaShape should feel like one continuous environment, not a portal containing unrelated tools. The system model remains present while the user changes lenses according to the current task.

The workspace has six primary lenses:

1. **Explore** — inspect systems, schemas, values, relationships, runtime observations, and provenance.
2. **Shape** — generate, arrange, and use controls, views, dashboards, inspectors, and workflows.
3. **Map** — connect source and destination elements and define correspondence or transformation.
4. **Run** — preview, simulate, approve, execute, synchronize, and monitor work.
5. **Compare** — diff snapshots, environments, runs, mappings, values, behavior, and visual output.
6. **Library** — discover and compose adapters, controls, mappings, transforms, policies, surfaces, workflows, and documentation.

A lens changes emphasis, not identity. Selecting a value in Explore should select the same value in Shape, Map, Run, and Compare.

## The continuous task flow

### 1. Connect

The user connects one or more sources: an API, database, repository, file set, design system, runtime, website, or service.

PortaShape displays connection capabilities and permission boundaries before reading or writing.

### 2. Discover

The system detects or imports schemas, values, types, constraints, relationships, events, runtime signals, and known semantic roles.

Discovery results show confidence and evidence. Users may correct classifications, name concepts, or add annotations. Those decisions become reusable knowledge rather than remaining local UI labels.

### 3. Surface

PortaShape immediately projects useful elements into controls and views. Types, constraints, semantics, and permissions influence control selection.

Examples:

- a color becomes a color control and contrast preview;
- a bounded number becomes a slider or number field;
- an enum becomes a selector;
- a relationship becomes a linked view or graph;
- an event stream becomes a timeline;
- a schema becomes a data editor;
- an animation model becomes curves, timelines, and parameter controls;
- a component becomes an interactive preview with exposed properties.

### 4. Shape

The user adjusts values, composes higher-level controls, saves presets, groups recurring changes, and observes consequences.

The UI distinguishes:

- temporary override;
- proposed change;
- saved option;
- system setting change;
- source patch;
- destination write;
- generated output;
- production execution.

### 5. Relate

The user introduces another system, snapshot, or desired model and connects equivalent or dependent elements.

Mappings may be created by drag-and-drop, selection, search, keyboard actions, bulk operations, code, imported libraries, or suggestions. Suggestions show reasons and confidence.

### 6. Simulate

Before execution, PortaShape shows source, transformed, and destination values; affected elements; warnings; overwritten values; unsupported capabilities; policy results; loss; and unresolved decisions.

The user can interact with the preview using the same controls used for runtime shaping.

### 7. Run

The approved plan executes as a migration, patch, export, synchronization, reconstruction, configuration promotion, or workflow.

Progress is represented as system facts, not decorative loading state. Long-running work has explicit job identity, status, cancellation, retry, and result reports.

### 8. Preserve

The workspace saves the useful explanation as one or more `.posh` artifacts: system snapshot, surface, mapping, transform, workflow, policy, library, or run report.

### 9. Learn

PortaShape identifies repeated adjustments, unresolved patterns, frequently grouped controls, recurring mappings, validation failures, and domain concepts. It suggests reusable abstractions but keeps the generated rule inspectable.

## Workspace anatomy

A coherent default workspace can include:

### System rail

A compact inventory of connected systems, environments, snapshots, branches, and permission state.

### Model explorer

A searchable tree, table, graph, or schema view of elements and relationships.

### Primary canvas

The current composed surface: controls, mapping graph, comparison, dashboard, preview, or workflow.

### Inspector

Metadata, type, scope, authority, constraints, transforms, validation, and provenance for the selected object.

### Runtime and preview pane

Live rendering, system state, events, transformed output, or destination simulation.

### Run and evidence drawer

Planned operations, approvals, warnings, execution state, logs, validation, and resulting artifacts.

The workspace may be embedded, full-screen, sidecar, local development tool, hosted service, or generated project-specific application.

## Generated interface modes

### Automatic

Connect a system and receive a practical first surface based on types, semantics, permissions, and common patterns.

### Guided

Describe a goal such as “tune this component,” “manage customer accounts,” “compare themes,” “migrate this site,” or “monitor this process.” PortaShape composes the relevant system elements and controls.

### Manual

Experts place controls, views, queries, actions, relations, and workflow steps directly.

### Adaptive

The surface evolves with schema changes, runtime observations, saved preferences, usage patterns, and accepted suggestions.

## Interaction model

### Direct manipulation with an inspectable rule underneath

Drag-and-drop may create a mapping or group, but the result becomes a named, editable relation rather than an opaque line.

### Selection persists across lenses

A selected value remains the same object as the user moves from inspection to control to mapping to run evidence.

### Preview is operational

The preview is not only a screenshot. It can expose the transformed values, runtime state, component behavior, validation, and downstream effects that produce the rendered result.

### Controls can become structure

Repeated low-level changes can be promoted into presets, formulas, policies, workflows, or higher-level semantic controls.

### Documentation is attached to the model

Explanations, examples, onboarding material, and operating guidance link to the elements and workflows they describe. Documentation becomes part of the workspace rather than a separate static site.

## Role-sensitive views

PortaShape should adapt presentation and permission without forking the underlying model.

- Developers may prefer schemas, paths, code references, events, patches, and logs.
- Designers may prefer tokens, components, states, visual previews, constraints, and motion controls.
- Operators may prefer records, actions, queues, status, alerts, and playbooks.
- Product teams may prefer goals, experiments, cohorts, options, and outcomes.
- Administrators may prefer settings, permissions, policies, approvals, environments, and audit.

A shared model lets each role communicate through the same element identities and run history.

## Progressive complexity

The smallest successful PortaShape interaction can be:

- connect one source;
- expose one value;
- change it and see the result;
- save the control or snapshot.

The same system can grow into:

- multi-system semantic mapping;
- generated interfaces for multiple roles;
- layered organization and project libraries;
- approval workflows;
- ongoing synchronization;
- complete website reconstruction;
- reusable operational playbooks;
- AI-assisted pattern discovery with structured output.

## Experience rules

- Never hide whether a value is live, proposed, derived, or committed.
- Never imply complete equivalence when a transform is lossy or inferred.
- Never separate a generated control from its source and authority metadata.
- Never require users to rebuild the system model in each feature.
- Prefer visible relationships and narrow operations over global hidden state.
- Use ordinary web semantics, accessible controls, and direct URLs where they strengthen clarity and resilience.