Outcome
Return Home navigation and signed-context refresh controls. With configured service credentials and an organization, attempts one app_engagement usage event; failure to emit that event does not block the widget.
Before you start
- Verify the authenticated identity, environment and pinned personal or organization context before preparing an action.
- The published application permission is workspace:read. Home registration supports personal household context. This response provides navigation or signed identity, not populated domain data or a workspace grant.
- Authorize the documented engagement, privacy or archival effects before CLI --confirm or MCP confirm:true. A GET request can have effects.
Discover the target
topolo whoami --json
topolo actions get app_topolo_home.widget.get --detail --json
Request
GET /api/widget
Save action input as payload.json. Inspect the plan for the exact path, query and body.
Inspect and test this action in the signed action console, then perform the verification below.
Input fields
Supply an empty input object; credential and resource context are separate.
Exact input schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {},
"additionalProperties": false
}
Effects
- Returns navigation configuration, not populated domain data or a workspace grant.
- With an organization and configured service credentials, attempts a Nexus home.widget_view event with units 1; personal context without an organization emits no usage event.
- A supplied workspace resource header is reflected in navigation scope. It does not independently prove a workspace grant.
Interpret the response
Use response path $.widgets[].id for widget. An empty list does not discover a target.
Confirm HTTP 200, appId and widget contractVersion; inspect launch actions and resource scope. Widget success does not prove Nexus accepted the engagement event. Do not retry merely to obtain an event receipt.
The success schema below was checked against captured handler responses. Signed identity and household metadata can vary. Error examples retain their actual refusal shapes.
Success schema:
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"type": "object",
"properties": {
"success": {
"type": "boolean",
"const": true
},
"contractVersion": {
"type": "string",
"const": "3.0.0"
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"generatedAt": {
"type": "string",
"minLength": 1
},
"widgets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"version": {
"type": "string",
"minLength": 1
},
"appId": {
"type": "string",
"minLength": 1
},
"serviceName": {
"type": "string",
"minLength": 1
},
"lastUpdated": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"stats",
"chart",
"activity",
"notifications",
"actions"
]
},
"presentation": {
"type": "object",
"properties": {
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"contexts": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"personal",
"organization",
"workspace",
"resource"
]
}
},
"supportedSizes": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"defaultSize": {
"enum": [
"compact",
"medium",
"wide",
"full"
]
}
},
"required": [
"title",
"contexts",
"supportedSizes",
"defaultSize"
],
"additionalProperties": false
},
"resource": {
"type": "object",
"properties": {
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"requiredPermissions": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"resourceType",
"requiredPermissions"
],
"additionalProperties": false
},
"state": {
"type": "object",
"properties": {
"status": {
"enum": [
"ready",
"empty",
"unavailable",
"stale",
"error"
]
},
"observedAt": {
"type": "string",
"minLength": 1
},
"lastSuccessfulAt": {
"type": "string",
"minLength": 1
},
"code": {
"type": "string",
"minLength": 1
},
"message": {
"type": "string",
"minLength": 1
}
},
"required": [
"status",
"observedAt"
],
"additionalProperties": false
},
"refresh": {
"type": "object",
"properties": {
"intervalSeconds": {
"type": "number"
},
"timeoutSeconds": {
"type": "number"
},
"maxAgeSeconds": {
"type": "number"
},
"staleWhileRevalidateSeconds": {
"type": "number"
}
},
"required": [
"intervalSeconds",
"timeoutSeconds",
"maxAgeSeconds",
"staleWhileRevalidateSeconds"
],
"additionalProperties": false
},
"configuration": {
"type": "object",
"properties": {
"allowMultipleInstances": {
"type": "boolean"
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"type": {
"enum": [
"string",
"number",
"boolean",
"select",
"multi-select",
"date-range"
]
},
"required": {
"type": "boolean"
},
"options": {
"type": "array",
"items": {
"type": "object",
"properties": {
"value": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
}
},
"required": [
"value",
"label"
],
"additionalProperties": false
}
}
},
"required": [
"key",
"label",
"type",
"required"
],
"additionalProperties": false
}
},
"defaults": {
"type": "object"
}
},
"required": [
"allowMultipleInstances",
"fields",
"defaults"
],
"additionalProperties": false
},
"drilldowns": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"href": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"label",
"href"
],
"additionalProperties": false
}
},
"controls": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
},
"localization": {
"type": "object",
"properties": {
"locale": {
"type": "string",
"minLength": 1
},
"titleKey": {
"type": "string",
"minLength": 1
},
"descriptionKey": {
"type": "string",
"minLength": 1
},
"title": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"locale",
"titleKey"
],
"additionalProperties": false
},
"accessibility": {
"type": "object",
"properties": {
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"label"
],
"additionalProperties": false
},
"contribution": {
"type": "object",
"properties": {
"summary": {
"type": "string",
"minLength": 1
},
"identity": {
"type": "object",
"properties": {
"iconSource": {
"const": "catalog"
}
},
"required": [
"iconSource"
],
"additionalProperties": false
},
"workspaceSelector": {
"type": "object",
"properties": {
"mode": {
"enum": [
"none",
"optional",
"required"
]
},
"resourceType": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"supportsMultiple": {
"type": "boolean"
}
},
"required": [
"mode",
"resourceType",
"label",
"supportsMultiple"
],
"additionalProperties": false
},
"metricDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
}
},
"required": [
"key",
"label",
"description",
"unit",
"semantic",
"aggregation"
],
"additionalProperties": false
}
},
"seriesDefinitions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"metricKey": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"metricKey",
"unit"
],
"additionalProperties": false
}
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"valueType": {
"enum": [
"string",
"number",
"boolean",
"date",
"datetime"
]
}
},
"required": [
"key",
"label",
"description",
"valueType"
],
"additionalProperties": false
}
},
"lifecycleStages": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"order": {
"type": "number"
},
"terminal": {
"type": "boolean"
}
},
"required": [
"key",
"label",
"order",
"terminal"
],
"additionalProperties": false
}
},
"events": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"description"
],
"additionalProperties": false
}
},
"datasets": {
"type": "array",
"minItems": 1,
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"description": {
"type": "string",
"minLength": 1
},
"grain": {
"type": "string",
"minLength": 1
},
"metricKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"seriesKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"dimensionKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"eventKeys": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"actionIds": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
}
},
"required": [
"id",
"label",
"description",
"grain",
"metricKeys",
"seriesKeys",
"dimensionKeys",
"eventKeys",
"actionIds"
],
"additionalProperties": false
}
},
"compatibleVisualizations": {
"type": "array",
"minItems": 1,
"items": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"defaultVisualization": {
"enum": [
"number",
"line",
"area",
"bar",
"donut",
"table",
"funnel",
"timeline",
"actions"
]
}
},
"required": [
"summary",
"identity",
"workspaceSelector",
"metricDefinitions",
"seriesDefinitions",
"dimensions",
"lifecycleStages",
"events",
"datasets",
"compatibleVisualizations",
"defaultVisualization"
],
"additionalProperties": false
},
"metrics": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"unit": {
"type": "string",
"minLength": 1
},
"semantic": {
"enum": [
"gauge",
"counter",
"rate",
"duration",
"currency",
"percentage"
]
},
"aggregation": {
"enum": [
"last",
"sum",
"average",
"minimum",
"maximum",
"count",
"distinct_count"
]
},
"period": {
"type": "object",
"properties": {
"start": {
"type": "string",
"minLength": 1
},
"end": {
"type": "string",
"minLength": 1
},
"timezone": {
"type": "string",
"minLength": 1
}
},
"required": [
"start",
"end",
"timezone"
],
"additionalProperties": false
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
},
"series": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"required": [
"key",
"label",
"value",
"unit",
"semantic",
"aggregation",
"period",
"dimensions"
],
"additionalProperties": false
}
},
"chartType": {
"enum": [
"line",
"bar",
"area",
"pie",
"donut"
]
},
"series": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"unit": {
"type": "string",
"minLength": 1
},
"points": {
"type": "array",
"items": {
"type": "object",
"properties": {
"timestamp": {
"type": "string",
"minLength": 1
},
"value": {
"type": "number"
},
"dimensions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"key": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"value": {
"type": "string",
"minLength": 1
}
},
"required": [
"key",
"label",
"value"
],
"additionalProperties": false
}
}
},
"required": [
"timestamp",
"value",
"dimensions"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"label",
"unit",
"points"
],
"additionalProperties": false
}
},
"activities": {
"type": "array",
"items": {
"type": "object"
}
},
"notifications": {
"type": "array",
"items": {
"type": "object"
}
},
"unreadCount": {
"type": "number"
},
"actions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"label": {
"type": "string",
"minLength": 1
},
"actionId": {
"type": "string",
"minLength": 1
},
"resourceType": {
"type": "string",
"minLength": 1
},
"resourceId": {
"type": "string",
"minLength": 1
},
"input": {
"type": "object"
},
"requiresConfirmation": {
"type": "boolean"
},
"destructive": {
"type": "boolean"
},
"effects": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"verification": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"recovery": {
"type": "object",
"properties": {
"mode": {
"enum": [
"not_applicable",
"retry",
"compensating_action"
]
},
"actionId": {
"type": "string",
"minLength": 1
},
"instructions": {
"type": "string",
"minLength": 1
}
},
"required": [
"mode",
"instructions"
],
"additionalProperties": false
}
},
"required": [
"id",
"label",
"actionId",
"resourceType",
"input",
"requiresConfirmation",
"destructive",
"effects",
"verification",
"recovery"
],
"additionalProperties": false
}
}
},
"required": [
"id",
"version",
"appId",
"serviceName",
"lastUpdated",
"type",
"presentation",
"resource",
"state",
"refresh",
"configuration",
"drilldowns",
"controls",
"localization",
"accessibility",
"contribution"
],
"allOf": [
{
"if": {
"properties": {
"type": {
"const": "stats"
}
}
},
"then": {
"required": [
"metrics"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "chart"
}
}
},
"then": {
"required": [
"chartType",
"series"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "activity"
}
}
},
"then": {
"required": [
"activities"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "notifications"
}
}
},
"then": {
"required": [
"notifications",
"unreadCount"
]
}
},
{
"if": {
"properties": {
"type": {
"const": "actions"
}
}
},
"then": {
"required": [
"actions"
]
}
}
],
"additionalProperties": false
}
},
"workspace": {
"anyOf": [
{
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
}
},
"required": [
"id",
"name"
],
"additionalProperties": true
},
{
"type": "null"
}
]
},
"workspaces": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"anyOf": [
{
"type": "string"
},
{
"type": "number"
}
]
},
"name": {
"type": "string",
"minLength": 1
},
"isDefault": {
"type": "boolean"
}
},
"required": [
"id",
"name"
],
"additionalProperties": false
}
}
},
"required": [
"success",
"contractVersion",
"appId",
"serviceName",
"generatedAt",
"widgets"
],
"additionalProperties": false
}
Worked examples
Actual Home Worker response with synthetic identity and identifiers. Auth grants, platform archival and Nexus usage transport are simulated; Home has no local database. This does not prove live platform archival or Nexus delivery. No request credentials are captured. Captured requests use synthetic principals and identifiers. Registration supports the personal household context; organization privacy and archival require an actual authorized organization context and cannot be inferred from personal access. Refused examples demonstrate boundaries and must not be executed as successful workflows.
Successful request
Actual Home Worker response with synthetic identity and identifiers. Auth grants, platform archival and Nexus usage transport are simulated; Home has no local database. This does not prove live platform archival or Nexus delivery. No request credentials are captured. Captured scenario: widget emits engagement and satisfies the complete SDK action output schema.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_home.widget.get --data @payload.json --json
topolo actions plan app_topolo_home.widget.get --data @payload.json --json
topolo actions call app_topolo_home.widget.get --data @payload.json --confirm --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_home.widget.get",
"input": {},
"confirm": true
}
}
Captured local response · HTTP 200:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_home",
"serviceName": "Home",
"generatedAt": "2026-10-04T03:16:34.118Z",
"widgets": [
{
"id": "home.workspace-launchpad",
"version": "3.0.0",
"type": "actions",
"presentation": {
"title": "Workspace launchpad",
"description": "Home exposes primary workspace and health-check actions for this service.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide",
"full"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "organization",
"resourceId": "org_home_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T03:16:34.118Z",
"lastSuccessfulAt": "2026-10-04T03:16:34.118Z"
},
"refresh": {
"intervalSeconds": 300,
"timeoutSeconds": 10,
"maxAgeSeconds": 300,
"staleWhileRevalidateSeconds": 300
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "defaultDestination",
"label": "Primary destination",
"type": "select",
"required": true,
"options": [
{
"value": "workspace",
"label": "Open app"
},
{
"value": "api-keys",
"label": "Manage API keys"
}
]
}
],
"defaults": {
"defaultDestination": "workspace"
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open app",
"href": "/dashboard"
},
{
"id": "api-keys",
"label": "Manage API keys",
"href": "/settings/api-keys"
}
],
"controls": [
{
"id": "refresh-workspace",
"label": "Refresh workspace context",
"actionId": "app_topolo_home.workspace.bootstrap",
"resourceType": "organization",
"resourceId": "org_home_fixture",
"input": {},
"requiresConfirmation": false,
"destructive": false,
"effects": [
"Reads the current signed Home workspace context without changing it."
],
"verification": [
"Confirm the returned workspace context matches the selected dashboard resource."
],
"recovery": {
"mode": "not_applicable",
"instructions": "This action does not change service state."
}
}
],
"actions": [
{
"id": "refresh-workspace",
"label": "Refresh workspace context",
"actionId": "app_topolo_home.workspace.bootstrap",
"resourceType": "organization",
"resourceId": "org_home_fixture",
"input": {},
"requiresConfirmation": false,
"destructive": false,
"effects": [
"Reads the current signed Home workspace context without changing it."
],
"verification": [
"Confirm the returned workspace context matches the selected dashboard resource."
],
"recovery": {
"mode": "not_applicable",
"instructions": "This action does not change service state."
}
}
],
"localization": {
"locale": "en",
"titleKey": "home.widget.workspaceLaunchpadTitle",
"descriptionKey": "home.widget.summary"
},
"accessibility": {
"label": "Home workspace launchpad",
"description": "Open Home workspace destinations or refresh the signed workspace context."
},
"contribution": {
"summary": "Workspace navigation and signed-context refresh controls for the selected Home scope.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "optional",
"resourceType": "workspace",
"label": "Home workspace",
"supportsMultiple": false
},
"metricDefinitions": [],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Home workspace",
"description": "The workspace or organization whose Home launch destinations are shown.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "home_launchpad",
"label": "Home launchpad",
"description": "Available Home navigation and context-refresh actions.",
"grain": "One action row per available Home destination or context operation.",
"metricKeys": [],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope"
],
"eventKeys": [],
"actionIds": [
"refresh-workspace"
]
}
],
"compatibleVisualizations": [
"actions",
"table"
],
"defaultVisualization": "actions"
},
"appId": "app_topolo_home",
"serviceName": "Home",
"lastUpdated": "2026-10-04T03:16:34.118Z"
}
]
}
HTTP 200. Confirm HTTP 200, appId and widget contractVersion; inspect launch actions and resource scope. Widget success does not prove Nexus accepted the engagement event. Do not retry merely to obtain an event receipt.
Another supported request
Actual Home Worker response with synthetic identity and identifiers. Auth grants, platform archival and Nexus usage transport are simulated; Home has no local database. This does not prove live platform archival or Nexus delivery. No request credentials are captured. Captured scenario: widget still returns navigation when engagement transport fails.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_home.widget.get --data @payload.json --json
topolo actions plan app_topolo_home.widget.get --data @payload.json --json
topolo actions call app_topolo_home.widget.get --data @payload.json --confirm --json
MCP tool and arguments:
{
"tool": "topolo_call_action",
"arguments": {
"actionId": "app_topolo_home.widget.get",
"input": {},
"confirm": true
}
}
Captured local response · HTTP 200:
{
"success": true,
"contractVersion": "3.0.0",
"appId": "app_topolo_home",
"serviceName": "Home",
"generatedAt": "2026-10-04T03:16:34.125Z",
"widgets": [
{
"id": "home.workspace-launchpad",
"version": "3.0.0",
"type": "actions",
"presentation": {
"title": "Workspace launchpad",
"description": "Home exposes primary workspace and health-check actions for this service.",
"contexts": [
"organization",
"workspace"
],
"supportedSizes": [
"compact",
"medium",
"wide",
"full"
],
"defaultSize": "medium"
},
"resource": {
"resourceType": "workspace",
"resourceId": "ws_home_fixture",
"requiredPermissions": [
"workspace:read"
]
},
"state": {
"status": "ready",
"observedAt": "2026-10-04T03:16:34.125Z",
"lastSuccessfulAt": "2026-10-04T03:16:34.125Z"
},
"refresh": {
"intervalSeconds": 300,
"timeoutSeconds": 10,
"maxAgeSeconds": 300,
"staleWhileRevalidateSeconds": 300
},
"configuration": {
"allowMultipleInstances": true,
"fields": [
{
"key": "defaultDestination",
"label": "Primary destination",
"type": "select",
"required": true,
"options": [
{
"value": "workspace",
"label": "Open app"
},
{
"value": "api-keys",
"label": "Manage API keys"
}
]
}
],
"defaults": {
"defaultDestination": "workspace"
}
},
"drilldowns": [
{
"id": "workspace",
"label": "Open app",
"href": "/dashboard"
},
{
"id": "api-keys",
"label": "Manage API keys",
"href": "/settings/api-keys"
}
],
"controls": [
{
"id": "refresh-workspace",
"label": "Refresh workspace context",
"actionId": "app_topolo_home.workspace.bootstrap",
"resourceType": "workspace",
"resourceId": "ws_home_fixture",
"input": {},
"requiresConfirmation": false,
"destructive": false,
"effects": [
"Reads the current signed Home workspace context without changing it."
],
"verification": [
"Confirm the returned workspace context matches the selected dashboard resource."
],
"recovery": {
"mode": "not_applicable",
"instructions": "This action does not change service state."
}
}
],
"actions": [
{
"id": "refresh-workspace",
"label": "Refresh workspace context",
"actionId": "app_topolo_home.workspace.bootstrap",
"resourceType": "workspace",
"resourceId": "ws_home_fixture",
"input": {},
"requiresConfirmation": false,
"destructive": false,
"effects": [
"Reads the current signed Home workspace context without changing it."
],
"verification": [
"Confirm the returned workspace context matches the selected dashboard resource."
],
"recovery": {
"mode": "not_applicable",
"instructions": "This action does not change service state."
}
}
],
"localization": {
"locale": "en",
"titleKey": "home.widget.workspaceLaunchpadTitle",
"descriptionKey": "home.widget.summary"
},
"accessibility": {
"label": "Home workspace launchpad",
"description": "Open Home workspace destinations or refresh the signed workspace context."
},
"contribution": {
"summary": "Workspace navigation and signed-context refresh controls for the selected Home scope.",
"identity": {
"iconSource": "catalog"
},
"workspaceSelector": {
"mode": "required",
"resourceType": "workspace",
"label": "Home workspace",
"supportsMultiple": false
},
"metricDefinitions": [],
"seriesDefinitions": [],
"dimensions": [
{
"key": "workspace_scope",
"label": "Home workspace",
"description": "The workspace or organization whose Home launch destinations are shown.",
"valueType": "string"
}
],
"lifecycleStages": [],
"events": [],
"datasets": [
{
"id": "home_launchpad",
"label": "Home launchpad",
"description": "Available Home navigation and context-refresh actions.",
"grain": "One action row per available Home destination or context operation.",
"metricKeys": [],
"seriesKeys": [],
"dimensionKeys": [
"workspace_scope"
],
"eventKeys": [],
"actionIds": [
"refresh-workspace"
]
}
],
"compatibleVisualizations": [
"actions",
"table"
],
"defaultVisualization": "actions"
},
"appId": "app_topolo_home",
"serviceName": "Home",
"lastUpdated": "2026-10-04T03:16:34.125Z"
}
]
}
HTTP 200. Confirm HTTP 200, appId and widget contractVersion; inspect launch actions and resource scope. Widget success does not prove Nexus accepted the engagement event. Do not retry merely to obtain an event receipt.
Refused request · HTTP 401
Actual Home Worker response with synthetic identity and identifiers. Auth grants, platform archival and Nexus usage transport are simulated; Home has no local database. This does not prove live platform archival or Nexus delivery. No request credentials are captured. Captured scenario: widget and signed bootstrap refuse unauthenticated requests.
Input · payload.json:
{}
CLI:
topolo actions validate app_topolo_home.widget.get --data @payload.json --json
topolo actions plan app_topolo_home.widget.get --data @payload.json --json
Captured local response · HTTP 401:
{
"error": "Authentication token required"
}
HTTP 401. The handler refused this request. Resolve its exact cause before retrying; input validation can reject an invalid fixture before it reaches the handler.
Verify the result
- Confirm HTTP 200, appId and widget contractVersion; inspect launch actions and resource scope.
- Widget success does not prove Nexus accepted the engagement event. Do not retry merely to obtain an event receipt.
Errors and recovery
Authentication token required(HTTP 401): Authenticate through the published login flow, verify the identity and repeat discovery before preparing this action.
Auth, action-input validation and platform resource resolution can refuse a request before its handler. Retain the exact error, request id and context; requesting another context is not a legitimate way to bypass a refusal.
Recovery boundary
No compensating event deletion is published. Fetching again can emit another engagement event.
Evidence
Actual Home Worker response with synthetic identity and identifiers. Auth grants, platform archival and Nexus usage transport are simulated; Home has no local database. This does not prove live platform archival or Nexus delivery. No request credentials are captured. Captured requests use synthetic principals and identifiers. Registration supports the personal household context; organization privacy and archival require an actual authorized organization context and cannot be inferred from personal access. Capture digests and test scenarios are retained in the source fixture records.