mainsequence 4.4.8__tar.gz → 4.4.11__tar.gz

{mainsequence-4.4.8/mainsequence.egg-info → mainsequence-4.4.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mainsequence
-Version: 4.4.8
+Version: 4.4.11
 Summary: Main Sequence SDK 
 Author-email: Main Sequence GmbH <dev@main-sequence.io>
 License: MainSequence GmbH SDK License Agreement

{mainsequence-4.4.8 → mainsequence-4.4.11}/agent_scaffold/AGENTS.md

@@ -17,17 +17,25 @@ uses them to update only the Main Sequence section below.
 <!-- mainsequence-agent-scaffold:start schema=1 source=agent_scaffold -->
 ## Main Sequence Instructions
 
-Before any non-trivial Main Sequence work, update the project SDK first and then refresh the
-installed Main Sequence scaffold files so the local CLI surface, `AGENTS.md`, and
-`.agents/skills/mainsequence/` match the installed SDK version:
+Before any non-trivial Main Sequence work, update the project SDK first, then compare the
+installed SDK version with the managed skills pin:
 
 - `mainsequence project update-sdk --path .`
+
+After the SDK update, inspect `.agents/skills/mainsequence/PINNED_FROM.txt`.
+Its `pinned_version=...` value records the SDK version that supplied the copied
+Main Sequence skills. Compare that value with the installed SDK version reported
+by `mainsequence --version`.
+
+Refresh the managed scaffold only when `PINNED_FROM.txt` is missing or its
+`pinned_version` differs from the installed SDK version:
+
 - `mainsequence project update AGENTS.md --path .`
 - `mainsequence project update_agent_skills --path .`
 
-After refreshing skills, `.agents/skills/mainsequence/PINNED_FROM.txt` records
-the installed SDK version that supplied the copied Main Sequence skills. Inspect
-that sentinel when checking whether the managed skills are current.
+If `pinned_version` already matches the installed SDK version, do not refresh
+`AGENTS.md` or `.agents/skills/mainsequence/` as a startup ritual; continue with
+the task.
 
 Canonical Main Sequence documentation root:
 `https://mainsequence-sdk.github.io/mainsequence-sdk/`
@@ -183,7 +191,13 @@ Typical routing:
 - Command Center workspace JSON creation/update and mounted widget mutation:
   `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
 - AppComponents, custom forms, and widget input or output contracts:
-  `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+  `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
+- Command Center table/pro-table widgets, tabular frames, table visual metadata, formulas,
+  selections, and live merge mappings:
+  `.agents/skills/mainsequence/command_center/widgets/tables/SKILL.md`
+- Command Center tabular transform widgets, projection, filtering, aggregate, pivot, unpivot,
+  computed columns, and seed/live update bindings:
+  `.agents/skills/mainsequence/command_center/widgets/tabular_transform/SKILL.md`
 - predeployment AppComponent/API contract testing through `apiTargetMode: "mock-json"`:
   `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md`
 - jobs, schedules, images, project resources, releases, and Artifacts:
@@ -211,12 +225,15 @@ For any non-trivial Main Sequence task:
     `mainsequence project open-signed-terminal <PROJECT_ID>`
 11. Before proceeding with non-trivial Main Sequence work, update the project SDK:
     `mainsequence project update-sdk --path .`
-12. After updating the SDK, refresh the installed Main Sequence scaffold files:
+12. After updating the SDK, compare `mainsequence --version` with
+    `.agents/skills/mainsequence/PINNED_FROM.txt` field `pinned_version=...`.
+13. If `PINNED_FROM.txt` is missing or `pinned_version` differs from the installed
+    SDK version, refresh the managed scaffold files:
     `mainsequence project update AGENTS.md --path .`
     `mainsequence project update_agent_skills --path .`
-13. Check `.agents/skills/mainsequence/PINNED_FROM.txt` when you need to verify
-    which SDK version supplied the copied Main Sequence skills.
-14. Verify platform state with the CLI or platform tooling instead of guessing.
+14. If `pinned_version` already matches the installed SDK version, do not refresh
+    `AGENTS.md` or `.agents/skills/mainsequence/` as a startup ritual.
+15. Verify platform state with the CLI or platform tooling instead of guessing.
 
 ## Orchestrator Rule
 

{mainsequence-4.4.8 → mainsequence-4.4.11}/agent_scaffold/skills/application_surfaces/api_surfaces/SKILL.md

@@ -51,7 +51,11 @@ This skill must not claim ownership of:
 - Command Center workspaces:
   `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
 - AppComponents and custom forms:
-  `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+  `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
+- Command Center table/pro-table response contracts:
+  `.agents/skills/mainsequence/command_center/widgets/tables/SKILL.md`
+- Command Center tabular transform consumers:
+  `.agents/skills/mainsequence/command_center/widgets/tabular_transform/SKILL.md`
 - Adapter from API provider-side Command Center connection endpoints:
   `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md`
 - predeployment mock API contract validation:
@@ -69,14 +73,18 @@ This skill must not claim ownership of:
 4. `docs/knowledge/fastapi/index.md`
 5. `docs/knowledge/command_center/widget_data_contracts.md`
 6. `docs/knowledge/command_center/forms.md`
-7. `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+7. `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
 
 Also load:
 
 8. `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md` when the API is tied to mounted widgets, workspace payloads, or workspace mutation
-9. `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md` when the API must be consumed through a Command Center Adapter from API connection
-10. `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md` when the contract should be validated in AppComponent mock mode before backend deployment
-11. `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md` when the API must become usable from Command Center or an AppComponent
+9. `.agents/skills/mainsequence/command_center/widgets/tables/SKILL.md` when the API returns
+   `core.tabular_frame@v1`, `meta.tableVisuals`, or table/pro-table widget-facing data
+10. `.agents/skills/mainsequence/command_center/widgets/tabular_transform/SKILL.md` when the API
+    response will be reshaped by `core__tabular-transform`
+11. `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md` when the API must be consumed through a Command Center Adapter from API connection
+12. `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md` when the contract should be validated in AppComponent mock mode before backend deployment
+13. `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md` when the API must become usable from Command Center or an AppComponent
 
 Do not wait for the user to say "Command Center" explicitly if the API is being built as a platform UI surface. That is the default assumption in Main Sequence projects.
 
@@ -138,7 +146,7 @@ In a Main Sequence project, assume API work is for Command Center unless the use
 That means:
 
 - prefer widget-facing contracts by default
-- load `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+- load `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
 - also load `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md` when the API is coupled to mounted workspace widgets or workspace payloads
 - load `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md` when the API will be consumed by connection-first workspace dataflow
 - try to use the existing Command Center SDK response model before inventing a new response shape

{mainsequence-4.4.8 → mainsequence-4.4.11}/agent_scaffold/skills/command_center/adapter_from_api/SKILL.md

@@ -99,6 +99,39 @@ connection/query flow directly. This avoids constant API deployments while itera
 contract, operation metadata, response shape, and widget behavior. Switch to `--api-base-url` only
 when the deployed API is ready to be the stable backend target.
 
+## SDK Helper Modules
+
+Provider code should use the Command Center SDK helpers instead of hand-building the well-known
+contract when the project can depend on `mainsequence-sdk`:
+
+```python
+from mainsequence.client.command_center.contracts.adapter_from_api import (
+    AdapterFromApiConfigVariable,
+    AdapterFromApiParameter,
+    AdapterFromApiSecretInjection,
+    AdapterFromApiSecretVariable,
+)
+from mainsequence.client.command_center.contracts.response_mapping import (
+    make_tabular_response_mapping,
+)
+from mainsequence.client.command_center.contracts.tabular import make_tabular_frame
+from mainsequence.client.command_center.providers.adapter_from_api import (
+    make_health_operation,
+    make_provider_contract,
+    make_query_operation,
+)
+```
+
+Use:
+
+- `contracts.adapter_from_api` for strict provider contract, operation, config variable, and secret
+  variable models
+- `providers.adapter_from_api` for `make_health_operation`, `make_query_operation`, and
+  `make_provider_contract`
+- `contracts.response_mapping` for optional `responseMappings` metadata
+- `contracts.tabular` for canonical `core.tabular_frame@v1` response helpers such as
+  `make_tabular_frame`
+
 ## Scope
 
 This skill owns:
@@ -131,8 +164,10 @@ Route those concerns to the adjacent skills below.
   `.agents/skills/mainsequence/command_center/connections/SKILL.md`
 - Workspace widgets and binding:
   `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
+- Table/pro-table output contracts and `meta.tableVisuals` metadata:
+  `.agents/skills/mainsequence/command_center/widgets/tables/SKILL.md`
 - AppComponent form-driven actions:
-  `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+  `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
 - API mock/prototype validation before deployment:
   `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md`
 - FastAPI resources, images, jobs, and releases:
@@ -330,6 +365,7 @@ For FastAPI providers in Main Sequence repos, full canonical frame endpoints mus
 
 ```python
 from mainsequence.client.command_center.data_models import TabularFrameResponse
+from mainsequence.client.command_center.contracts.tabular import make_tabular_frame
 ```
 
 Declare `response_model=TabularFrameResponse` instead of recreating the canonical frame shape
@@ -420,7 +456,9 @@ Before implementing or revising an API for Adapter from API consumption, decide:
 
 For a FastAPI provider:
 
-- define strict Pydantic models for the Command Center contract
+- use the SDK provider helpers in `mainsequence.client.command_center.providers.adapter_from_api`
+  and strict models in `mainsequence.client.command_center.contracts.adapter_from_api` when the
+  dependency is available
 - set explicit `operation_id` values on routes
 - expose `GET /.well-known/command-center/connection-contract`
 - expose a zero-argument health route

{mainsequence-4.4.8 → mainsequence-4.4.11}/agent_scaffold/skills/command_center/api_mock_prototyping/SKILL.md

@@ -44,9 +44,11 @@ This skill must not claim ownership of:
 ## Route Adjacent Work
 
 - AppComponents and custom forms:
-  `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+  `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
 - Command Center workspaces and widget mutation:
   `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
+- Tabular transform widgets for downstream reshaping in mock validation:
+  `.agents/skills/mainsequence/command_center/widgets/tabular_transform/SKILL.md`
 - APIs and FastAPI:
   `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`
 - Jobs, images, resources, and releases:
@@ -61,7 +63,7 @@ This skill must not claim ownership of:
 2. The SDK client models:
    - `mainsequence/client/command_center/app_component.py`
    - `mainsequence/client/command_center/workspace.py`
-3. `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+3. `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
 4. `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
 
 Only after the mock contract is stable:

{mainsequence-4.4.8 → mainsequence-4.4.11}/agent_scaffold/skills/command_center/connections/SKILL.md

@@ -24,6 +24,11 @@ connection instance and query model are known.
 ## This Skill Can Do
 
 - discover connection types and instances through `mainsequence.client.command_center.connections`
+- use `mainsequence.client.command_center.widgets.connection_query` for connection-query source
+  widget payload drafts
+- use `mainsequence.client.command_center.contracts.*` and
+  `mainsequence.client.command_center.providers.*` when validating Adapter from API provider
+  contracts
 - decide whether an existing connection instance can support the requested workspace data
 - inspect `ConnectionType.queryModels` and `usageGuidance`
 - verify that a query model can publish the required output contract
@@ -48,10 +53,14 @@ This skill must not claim ownership of:
   `.agents/skills/mainsequence/command_center/workspace_design/SKILL.md`
 - Workspace JSON creation and widget mutation:
   `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
+- Table/pro-table consumer contracts, table visual metadata, selection, and live update behavior:
+  `.agents/skills/mainsequence/command_center/widgets/tables/SKILL.md`
+- Tabular transform consumer contracts and source/live update bindings:
+  `.agents/skills/mainsequence/command_center/widgets/tabular_transform/SKILL.md`
 - Adapter from API connection workflow:
   `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md`
 - AppComponent forms and action API contracts:
-  `.agents/skills/mainsequence/command_center/app_components/SKILL.md`
+  `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
 - API implementation:
   `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`
 - Jobs, images, resources, and releases:
@@ -63,6 +72,22 @@ This skill must not claim ownership of:
    - `mainsequence/client/command_center/connections.py`
    - `mainsequence/client/command_center/data_models.py` when validating `core.tabular_frame@v1`
      output shape
+   - `mainsequence/client/command_center/contracts/adapter_from_api.py` when validating provider
+     discovery contracts
+   - `mainsequence/client/command_center/contracts/response_mapping.py` when validating
+     response-mapping metadata
+   - `mainsequence/client/command_center/contracts/tabular.py` when building or checking canonical
+     tabular frames
+   - `mainsequence/client/command_center/contracts/table_visuals.py` when table-specific visual
+     defaults travel with `meta.tableVisuals`
+   - `mainsequence/client/command_center/providers/adapter_from_api.py` when a provider should use
+     SDK contract builders
+   - `mainsequence/client/command_center/widgets/connection_query.py` when creating
+     connection-query source widget payloads
+   - `mainsequence/client/command_center/widgets/tabular_transform.py` when a connection-backed
+     flow needs a `core__tabular-transform` widget
+   - `mainsequence/client/command_center/widgets/bindings.py` when binding seed data or live updates
+     into the transform
 2. Widget registry detail for the source and consumer widgets:
    - `mainsequence cc registered_widget_type list --json`
    - `mainsequence cc registered_widget_type detail <WIDGET_ID> --json`

{mainsequence-4.4.8/agent_scaffold/skills/command_center → mainsequence-4.4.11/agent_scaffold/skills/command_center/widgets}/app_components/SKILL.md

@@ -47,6 +47,8 @@ This skill must not claim ownership of:
 
 - Command Center workspaces:
   `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
+- Command Center table/pro-table output contracts and table visual metadata:
+  `.agents/skills/mainsequence/command_center/widgets/tables/SKILL.md`
 - predeployment mock API contract validation:
   `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md`
 - APIs and FastAPI:
@@ -71,17 +73,19 @@ This skill must not claim ownership of:
 2. `docs/knowledge/command_center/forms.md`
 3. `docs/knowledge/command_center/widget_data_contracts.md`
 4. `mainsequence/client/command_center/app_component.py`
-5. `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md` when API-shaped data must become a connection-backed tabular dataset
-6. `.agents/skills/mainsequence/command_center/connections/SKILL.md` when AppComponent output will be consumed by generic tabular widgets or must align with connection-first dataflow
+5. `.agents/skills/mainsequence/command_center/widgets/tables/SKILL.md` when AppComponent output will feed
+   a table/pro-table widget or needs `core.tabular_frame@v1` plus table visual metadata
+6. `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md` when API-shaped data must become a connection-backed tabular dataset
+7. `.agents/skills/mainsequence/command_center/connections/SKILL.md` when AppComponent output will be consumed by generic tabular widgets or must align with connection-first dataflow
 
 If the AppComponent is backed by project APIs, also read:
 
-7. `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`
-8. `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md`
+8. `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`
+9. `.agents/skills/mainsequence/platform_operations/orchestration_and_releases/SKILL.md`
 
 If the task is about validating the API contract before deployment, also read:
 
-9. `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md`
+10. `.agents/skills/mainsequence/command_center/api_mock_prototyping/SKILL.md`
 
 ## Inputs This Skill Needs
 

mainsequence-4.4.11/agent_scaffold/skills/command_center/widgets/tables/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: command-center-tables
+description: Use this skill when the task is about Command Center table or pro-table widgets, canonical `core.tabular_frame@v1` responses, table-specific frame visual metadata, table widget column schema, formula columns, conditional formatting, selection outputs, or live merge key mappings. This skill owns the boundary between source-owned tabular frame contracts and persisted table widget props. It does not own workspace layout, connection creation, generic API architecture, AppComponent forms, MetaTable schema design, or DataNode storage design.
+---
+
+# Command Center Tables
+
+## Overview
+
+Use this skill when a Command Center table surface needs exact contract work.
+
+There are two table-related surfaces that must stay separate:
+
+- source-owned data contract:
+  `core.tabular_frame@v1` plus optional `meta.tableVisuals`
+- widget-owned presentation contract:
+  `core__table` or `core__pro-table` mounted widget props
+
+Do not mix these contracts. A data producer should return a canonical tabular frame. A workspace
+table widget should define persisted presentation choices, bindings, formulas, selection behavior,
+and live update mappings.
+
+## This Skill Can Do
+
+- design or review a `core.tabular_frame@v1` response intended for table consumption
+- use `make_tabular_frame`, `make_tabular_field`, and related helpers
+- add or review source-owned `meta.tableVisuals` metadata
+- decide whether display semantics belong in `meta.tableVisuals` or table widget props
+- build or review `core__table` mounted widget payloads
+- build or review `core__pro-table` mounted widget payloads
+- define `TableWidgetColumnSchema`
+- define `TableWidgetColumnOverride`
+- define conditional rules and value labels
+- use formula helpers and `make_formula_column` for pro-table only
+- define selection mode and selection key fields
+- define live merge key mappings for incremental table updates
+- verify table/pro-table widget registry details before mounting or mutating a table widget
+
+## This Skill Must Not Claim
+
+This skill must not claim ownership of:
+
+- workspace narrative, layout, or widget selection strategy
+- workspace JSON mutation or widget-scoped patch execution
+- connection type selection or connection instance creation
+- Adapter from API provider discovery contracts outside table-specific frame output decisions
+- AppComponent request forms, editable forms, or notification responses
+- generic FastAPI route architecture
+- MetaTable schema, DataNode storage, migrations, or governed operations
+- resource releases, jobs, images, RBAC, or sharing
+
+## Route Adjacent Work
+
+- Workspace design and deciding whether the view should be a table:
+  `.agents/skills/mainsequence/command_center/workspace_design/SKILL.md`
+- Workspace JSON creation, table mounting, and widget mutation:
+  `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
+- Connection-backed source data and query model selection:
+  `.agents/skills/mainsequence/command_center/connections/SKILL.md`
+- Adapter from API provider contracts:
+  `.agents/skills/mainsequence/command_center/adapter_from_api/SKILL.md`
+- Tabular transform widgets that reshape data before table consumption:
+  `.agents/skills/mainsequence/command_center/widgets/tabular_transform/SKILL.md`
+- AppComponent custom forms and action contracts:
+  `.agents/skills/mainsequence/command_center/widgets/app_components/SKILL.md`
+- APIs and FastAPI:
+  `.agents/skills/mainsequence/application_surfaces/api_surfaces/SKILL.md`
+- MetaTables:
+  `.agents/skills/mainsequence/data_publishing/meta_tables/SKILL.md`
+- DataNodes:
+  `.agents/skills/mainsequence/data_publishing/data_nodes/SKILL.md`
+
+## Read First
+
+1. Verify the table widget catalog through the CLI:
+   - `mainsequence cc registered_widget_type list --json`
+   - identify `core__table` or `core__pro-table`
+   - `mainsequence cc registered_widget_type detail <WIDGET_ID> --json`
+2. `docs/knowledge/command_center/widget_data_contracts.md`
+3. SDK table and tabular models:
+   - `mainsequence/client/command_center/contracts/tabular.py`
+   - `mainsequence/client/command_center/contracts/table_visuals.py`
+   - `mainsequence/client/command_center/widgets/table.py`
+   - `mainsequence/client/command_center/data_models.py`
+4. If the table consumes connection-backed data:
+   - `.agents/skills/mainsequence/command_center/connections/SKILL.md`
+   - `mainsequence/client/command_center/widgets/connection_query.py`
+   - `mainsequence/client/command_center/widgets/bindings.py`
+5. If the table consumes transformed data:
+   - `.agents/skills/mainsequence/command_center/widgets/tabular_transform/SKILL.md`
+   - `mainsequence/client/command_center/widgets/tabular_transform.py`
+6. If mounting or mutating a table widget:
+   - `.agents/skills/mainsequence/command_center/workspace_builder/SKILL.md`
+   - `mainsequence/client/command_center/workspaces/mounted_widgets.py`
+
+Use the SDK helper files above before opening frontend implementation files.
+
+## Inputs This Skill Needs
+
+Before changing a table contract or payload, collect or infer:
+
+- target widget id: `core__table` or `core__pro-table`
+- registry detail for that widget id
+- source mode: bound, connection, connection-stream, or manual
+- source frame shape: columns, rows, fields, source, and meta
+- whether the source emits a full `core.tabular_frame@v1` response
+- which fields are stable identity keys
+- which columns should be visible, hidden, pinned, aligned, formatted, or resized
+- which formatting is source-owned default metadata versus workspace-specific override
+- whether formulas are needed
+- whether row/cell selection is needed and which outputs downstream widgets consume
+- whether live updates need merge mappings from seed fields to live-update fields
+
+## Required Decisions
+
+For every non-trivial table task, decide:
+
+1. Should the data be represented as `core.tabular_frame@v1` before it reaches the table?
+2. Does the table need `core__table` or `core__pro-table`?
+3. Are formula columns required? If yes, use `core__pro-table`.
+4. Which display semantics should be emitted by the source in `meta.tableVisuals`?
+5. Which display choices should remain widget-owned props or user/workspace overrides?
+6. Should column descriptions live in frame `fields`, table widget `schema`, or both?
+7. Does selection need stable `selectionKeyFields` and published selection outputs?
+8. Does incremental/live updating need `liveMergeKeyMappings`?
+9. Is a Tabular Transform widget needed before the table?
+10. Has the exact widget registry detail been checked before authoring payloads?
+
+## Build Rules
+
+### 1. Use Canonical Tabular Frames At The Consumption Boundary
+
+Table and pro-table widgets should consume `core.tabular_frame@v1` for generic tabular data.
+
+Use:
+
+```python
+from mainsequence.client.command_center.contracts.tabular import (
+    make_tabular_field,
+    make_tabular_frame,
+)
+```
+
+Do not bind raw arrays, paginated provider JSON, nested objects, or provider-native payloads
+directly into generic table consumers unless a dedicated widget contract explicitly supports that
+shape.
+
+### 2. Keep Source-Owned Table Defaults In `meta.tableVisuals`
+
+Use `meta.tableVisuals` for source-owned display metadata that should travel with the frame:
+
+```python
+from mainsequence.client.command_center.contracts.table_visuals import (
+    make_table_visual_column,
+    make_table_visuals,
+)
+from mainsequence.client.command_center.contracts.tabular import make_tabular_frame
+
+frame = make_tabular_frame(
+    rows=[{"asset": "BTC", "price": 101.25, "change": 0.015}],
+    columns=["asset", "price", "change"],
+    table_visuals=make_table_visuals(
+        {
+            "price": make_table_visual_column(format="currency", decimals=2),
+            "change": make_table_visual_column(format="percent", decimals=2),
+        }
+    ),
+)
+```
+
+Use `meta.tableVisuals` for stable source semantics such as:
+
+- source-recommended labels
+- numeric, currency, percent, bps, or formula result format hints
+- default decimals
+- default heatmap, bar, gradient, gauge, or threshold hints
+- inline series encoding hints for sparkline-like columns
+
+Do not put user-specific layout, workspace-local overrides, credentials, connection ids, or runtime
+view state into `meta.tableVisuals`.
+
+### 3. Keep Widget-Owned Presentation In Table Props
+
+Use table widget props for persisted workspace presentation:
+
+```python
+from mainsequence.client.command_center.widgets.table import (
+    TableWidgetColumnOverride,
+    TableWidgetColumnSchema,
+    make_table_widget_payload,
+)
+
+payload = make_table_widget_payload(
+    title="Prices",
+    schema=[
+        TableWidgetColumnSchema(key="asset", label="Asset", format="text"),
+        TableWidgetColumnSchema(key="price", label="Price", format="currency"),
+    ],
+    column_overrides={
+        "price": TableWidgetColumnOverride(format="currency", decimals=2, align="right")
+    },
+)
+```
+
+Use widget props for:
+
+- table source mode
+- column schema and persistent column overrides
+- toolbar/search/filter/pagination options
+- value labels and conditional rules
+- selection mode and selection output behavior
+- live merge key mappings
+- workspace-specific formatting choices
+
+### 4. Formula Columns Require Pro Table
+
+Normal table payloads reject formula columns. If the table needs formula columns, use
+`core__pro-table` and `make_pro_table_widget_payload`.
+
+```python
+from mainsequence.client.command_center.widgets.table import (
+    formula_percent_change,
+    make_formula_column,
+    make_pro_table_widget_payload,
+)
+
+payload = make_pro_table_widget_payload(
+    title="Returns",
+    schema=[
+        make_formula_column(
+            key="return_pct",
+            label="Return %",
+            expression=formula_percent_change("price", "previous_price"),
+            result_format="percent",
+        )
+    ],
+)
+```
+
+Do not force formula props into `core__table`.
+
+### 5. Do Not Confuse Frame Fields With Widget Schema
+
+Frame `fields` describe the data contract:
+
+- key
+- label
+- type
+- nullable
+- provenance
+
+Table widget `schema` describes persisted table presentation and table runtime behavior:
+
+- format
+- formula expression
+- min width, flex, pinning
+- compactness
+- heatmap eligibility
+
+It is valid to use both, but they serve different owners. Do not replace a canonical frame field
+description with widget props, and do not put table runtime-only props into frame fields.
+
+### 6. Connection-Backed Tables Must Stay Connection-First
+
+If a table consumes backend-owned data:
+
+1. resolve the connection instance and query model
+2. use a Connection Query source widget
+3. bind the table input to the source widget output
+4. use a Tabular Transform widget before the table when reshaping is needed
+
+Do not store endpoint URLs, credentials, raw provider ids, or route fragments in table widget props.
+
+### 7. Live Merge Keys Must Be Stable
+
+Use `TableLiveMergeKeyMapping` only when seed-frame rows and live-update rows have stable fields
+that identify the same logical row.
+
+Do not configure live merge mappings from display labels, mutable names, timestamps alone, or
+non-unique values.
+
+### 8. Selection Outputs Need Stable Keys
+
+When the table should drive downstream widgets, define:
+
+- `selectionMode`
+- `selectionKeyFields`
+- `publishSelectionOutputs`
+
+Selection key fields must identify rows stably enough for downstream consumers.
+
+## Review Rules
+
+When reviewing table work, look for:
+
+- raw provider JSON bound into a generic table
+- table widget props carrying credentials, endpoint URLs, or backend route fragments
+- display defaults that should be source-owned but were hardcoded as workspace overrides
+- workspace-local overrides pushed into `meta.tableVisuals`
+- formula columns mounted on `core__table` instead of `core__pro-table`
+- duplicate table schema column keys
+- conditional rules referencing missing schema columns
+- selection outputs without stable key fields
+- live merge mappings based on unstable or non-unique fields
+- frame `fields` being used as a substitute for widget runtime schema, or the reverse
+- table payloads authored before registry detail was checked
+
+## Validation Checklist
+
+Do not claim the table contract is ready until:
+
+- the target widget id was verified through registry detail
+- data consumed by generic table widgets is `core.tabular_frame@v1`
+- frame columns and row keys are aligned
+- important field types are represented in `fields`
+- source-specific runtime details live in `source.context`
+- source-owned display defaults, if any, live under `meta.tableVisuals`
+- table widget props serialize through `make_table_widget_payload` or `make_pro_table_widget_payload`
+- formula columns use `core__pro-table`
+- selection and live merge keys are stable when configured
+- the workspace handoff identifies bindings from source outputs to table inputs
+
+## Stop Conditions
+
+Stop and route to the adjacent skill when:
+
+- the task is deciding whether a table is the right widget
+- the table needs a connection instance or query model that does not exist
+- the API cannot emit `core.tabular_frame@v1` but the table needs generic tabular data
+- table widget registry detail is unavailable or contradicts the SDK model
+- formulas are required but `core__pro-table` is unavailable
+- stable selection or live merge keys cannot be identified
+- the task has moved into workspace JSON mutation or backend API implementation