TenantAtlas/specs/244-product-knowledge-contextual-help/spec.md

Feature Specification: Product Knowledge & Contextual Help

Feature Branch: 244-product-knowledge-contextual-help
Created: 2026-04-26
Status: Ready for implementation
Input: User description: "Promote the roadmap-fit candidate Product Knowledge & Contextual Help as a narrow, implementation-ready slice that introduces a code-owned contextual help contract for operator-facing guidance on existing onboarding and diagnostics surfaces, reuses glossary and reason-translation foundations, and stops before AI, chatbot, or public docs platform scope."

Spec Candidate Check (mandatory — SPEC-GATE-001)

• Problem: Operators still need founder explanation when onboarding blockers, support-diagnostic summaries, or reason-translated states explain what happened but not the safest next step, the relevant documentation, or the surrounding product meaning.
• Today's failure: Tenant onboarding and support-oriented diagnostic surfaces already expose truthful status and reason signals, but help remains scattered across local copy, existing docs knowledge, or founder memory. That slows onboarding, increases support load, and leaves later AI-assisted support without a trusted product-knowledge source.
• User-visible improvement: Operators see contextual help on two high-value existing surfaces with canonical terminology, troubleshooting hints, and documentation links that match the current issue without replacing the underlying truth or opening raw diagnostics first.
• Smallest enterprise-capable version: Add one code-owned contextual help catalog plus one resolver that reuses the existing glossary, reason-translation, operator-explanation, and required-permissions link helpers for two adoption surfaces only: the managed-tenant onboarding workflow and the support-diagnostic bundle in tenant and operation contexts.
• Explicit non-goals: No public docs site, no AI chatbot, no broad CMS/editor workflow, no complete localization overhaul, no customer-facing help center, no rewrite of every operator surface, and no new persisted product-knowledge table.
• Permanent complexity imported: One bounded ProductKnowledge support namespace, one catalog of stable help topic keys, one resolver/presenter path, one machine-readable source export for later AI/support use, and focused unit plus feature tests.
• Why now: The repo already has PlatformVocabularyGlossary, ReasonPresenter, OperatorExplanationBuilder, ManagedTenantOnboardingWizard, and SupportDiagnosticBundleBuilder. Product Knowledge is the smallest next slice that makes onboarding and support less founder-dependent while preparing a safe knowledge source for later AI-assisted support.
• Why not local: Local page copy would duplicate glossary and reason semantics, drift across onboarding and diagnostics surfaces, and fail to produce one reviewable, versioned, machine-readable product-knowledge source.
• Approval class: Workflow Compression
• Red flags triggered: New meta-infrastructure and a foundation-sounding theme. Defense: the slice stays bounded to two existing adoption surfaces, introduces no new persistence, and reuses existing glossary/reason/support primitives rather than inventing a generic knowledge platform.
• Score: Nutzen: 2 | Dringlichkeit: 2 | Scope: 2 | Komplexität: 1 | Produktnähe: 2 | Wiederverwendung: 2 | Gesamt: 11/12
• Decision: approve

Spec Scope Fields (mandatory)

• Scope: workspace
• Primary Routes:
  • /admin/onboarding
  • /admin/onboarding/{onboardingDraft}
  • existing tenant support-diagnostics entry points on /admin/t/{tenant}
  • existing canonical operation detail support-diagnostics entry points on /admin/operations/{run}
• Data Ownership:
  • No new database table or persisted product-knowledge entity is introduced.
  • The contextual help catalog remains code-owned, reviewable, and versioned in the repository.
  • Source truth remains on PlatformVocabularyGlossary, ReasonResolutionEnvelope, OperatorExplanationPattern, SupportDiagnosticBundleBuilder, and existing route/link helpers.
  • Any machine-readable knowledge source exported by the feature is derived from the code-owned catalog and MUST exclude customer content, provider payloads, and secrets.
• RBAC:
  • This slice introduces no new capability family.
  • Existing onboarding authorization remains authoritative for /admin/onboarding and the managed-tenant onboarding draft flow.
  • Existing support-diagnostics and operation-view entitlement checks remain authoritative for tenant and operation diagnostic entry points.
  • Non-members or wrong-scope actors continue to receive 404. In-scope actors lacking the existing capability continue to receive 403. Help resolution never runs before those scope checks pass.

For canonical-view specs, the spec MUST define:

• Default filter behavior when tenant-context is active: N/A - this slice does not add a new canonical list or queue. It annotates existing onboarding and diagnostic detail surfaces only.
• Explicit entitlement checks preventing cross-tenant leakage: Contextual help is resolved only after the host surface has already resolved workspace and tenant entitlement. Help topics may reference only routes, documents, and next steps the current actor is already entitled to see.

Cross-Cutting / Shared Pattern Reuse (mandatory when the feature touches notifications, status messaging, action links, header actions, dashboard signals/cards, alerts, navigation entry points, evidence/report viewers, or any other existing shared operator interaction family; otherwise write N/A - no shared interaction family touched)

• Cross-cutting feature?: yes
• Interaction class(es): status messaging, supporting docs links, troubleshooting guidance, support-diagnostic summaries, onboarding next-step guidance
• Systems touched: ManagedTenantOnboardingWizard, SupportDiagnosticBundleBuilder, PlatformVocabularyGlossary, ReasonPresenter, OperatorExplanationBuilder, ProviderReasonTranslator, and RequiredPermissionsLinks
• Existing pattern(s) to extend: canonical glossary terms, reason-translation envelopes, operator-explanation summaries, support-diagnostic section assembly, and existing required-permissions/admin-consent link helpers
• Shared contract / presenter / builder / renderer to reuse: App\Support\Governance\PlatformVocabularyGlossary, App\Support\ReasonTranslation\ReasonPresenter, App\Support\Ui\OperatorExplanation\OperatorExplanationBuilder, App\Support\SupportDiagnostics\SupportDiagnosticBundleBuilder, and App\Support\Links\RequiredPermissionsLinks
• Why the existing shared path is sufficient or insufficient: existing shared paths already provide truthful labels, diagnostic summaries, glossary boundaries, and remediation links, but they do not provide one reviewable cross-surface product-knowledge layer with stable help topic keys, progressive disclosure copy, or a machine-readable knowledge source.
• Allowed deviation and why: provider-specific consent and required-permissions guidance may remain inside provider-owned help topics because the concrete remediation path is still Microsoft-specific in the current release.
• Consistency impact: topic keys, help headings, glossary nouns, troubleshooting steps, and docs links must stay aligned across onboarding and support diagnostics so the same state does not produce competing explanations.
• Review focus: reviewers must block page-local contextual-help prose that bypasses the shared catalog and must confirm that help copy stays derived from glossary/reason/support truth rather than becoming a second semantic source of truth.

OperationRun UX Impact (mandatory when the feature creates, queues, deduplicates, resumes, blocks, completes, or deep-links to an OperationRun; otherwise write N/A - no OperationRun start or link semantics touched)

• Touches OperationRun start/completion/link UX?: no
• Shared OperationRun UX contract/layer reused: N/A - the slice annotates existing onboarding and support-diagnostic surfaces only and does not change how runs are started, linked, or messaged.
• Delegated start/completion UX behaviors: N/A
• Local surface-owned behavior that remains: N/A
• Queued DB-notification policy: N/A
• Terminal notification path: N/A
• Exception required?: none

Provider Boundary / Platform Core Check (mandatory when the feature changes shared provider/platform seams, identity scope, governed-subject taxonomy, compare strategy selection, provider connection descriptors, or operator vocabulary that may leak provider-specific semantics into platform-core truth; otherwise write N/A - no shared provider/platform boundary touched)

• Shared provider/platform boundary touched?: yes
• Boundary classification: mixed
• Seams affected: provider permission/consent guidance, provider reason translation reuse, glossary-backed terminology, support-diagnostic guidance, and documentation link resolution
• Neutral platform terms preserved or introduced: contextual help, help topic, troubleshooting guidance, next action, support diagnostics, readiness, operator guidance
• Provider-specific semantics retained and why: Microsoft admin consent and required-permissions guidance remain provider-owned because those remediation steps still require exact provider terminology and URLs in the current release.
• Why this does not deepen provider coupling accidentally: provider-specific help remains attached to provider-owned topics and existing provider link helpers. The top-level catalog, topic IDs, glossary references, and host-surface contracts remain platform-neutral.
• Follow-up path: document-in-feature for the Platform Localization v1 dependency boundary; no follow-up spec is required for the bounded first slice itself.

UI / Surface Guardrail Impact (mandatory when operator-facing surfaces are changed; otherwise write N/A)

Surface / Change	Operator-facing surface change?	Native vs Custom	Shared-Family Relevance	State Layers Touched	Exception Needed?	Low-Impact / N/A Note
Managed tenant onboarding workflow	yes	Native Filament + shared primitives	status messaging, docs links, readiness guidance	page, workflow step, detail reveal	no	Adds contextual help beside existing readiness and verification signals only
Tenant dashboard support-diagnostic preview	yes	Native Filament action + shared diagnostics bundle	diagnostic summaries, docs links, troubleshooting guidance	action preview, diagnostic section detail	no	Help enriches the existing derived bundle instead of creating a second support surface
Operation detail support-diagnostic preview	yes	Native Filament detail action + shared diagnostics bundle	diagnostic summaries, docs links, troubleshooting guidance	detail, action preview, diagnostic section detail	no	Reuses the same help-resolution path as tenant diagnostics with operation-context inputs

Decision-First Surface Role (mandatory when operator-facing surfaces are changed)

Surface	Decision Role	Human-in-the-loop Moment	Immediately Visible for First Decision	On-Demand Detail / Evidence	Why This Is Primary or Why Not	Workflow Alignment	Attention-load Reduction
Managed tenant onboarding workflow	Primary Decision Surface	Decide what blocker to resolve next so onboarding can continue safely	current blocker meaning, one help headline, one safe next step, and one supporting docs link when relevant	full verification detail, provider-specific evidence, operation detail, and raw diagnostics	Primary because the operator is already in the guided setup workflow and needs help in that context	Follows the identify-connect-verify-complete onboarding workflow	Removes the need to switch to founder memory or separate documentation to interpret the blocker
Tenant dashboard support-diagnostic preview	Secondary Context Surface	Decide how to troubleshoot or escalate a tenant issue from one support-safe summary	dominant issue meaning, contextual help headline, troubleshooting hints, and safe next step	full bundle sections, related records, and diagnostic evidence	Secondary because support diagnostics remain a follow-up to tenant work, not the primary workflow	Follows tenant troubleshooting and escalation flow	Reduces cross-page reconstruction and repeated explanation work
Operation detail support-diagnostic preview	Tertiary Evidence / Diagnostics Surface	Decide what the current run outcome means before drilling deeper or escalating	run summary meaning, contextual help headline, troubleshooting hints, and safe next step	canonical run detail, related records, and provider diagnostics	Tertiary because the surface is already evidence-first and the help layer should remain progressive disclosure	Follows monitoring and support drill-in flow	Makes the existing diagnostic surface more self-explanatory without turning it into a new queue

UI/UX Surface Classification (mandatory when operator-facing surfaces are changed)

Surface	Action Surface Class	Surface Type	Likely Next Operator Action	Primary Inspect/Open Model	Row Click	Secondary Actions Placement	Destructive Actions Placement	Canonical Collection Route	Canonical Detail Route	Scope Signals	Canonical Noun	Critical Truth Visible by Default	Exception Type / Justification
Managed tenant onboarding workflow	Workflow / Guided action entry	Guided onboarding / readiness workflow	Resolve the blocker or continue to the next checkpoint	In-page readiness and contextual-help section on the current draft route	forbidden	Supporting docs and diagnostics stay inside the section reveal	Existing destructive draft actions remain in the header only	/admin/onboarding	/admin/onboarding/{onboardingDraft}	Workspace context, linked tenant, provider readiness summary, help topic scope	Onboarding / Onboarding guidance	Blocker meaning, safe next step, and supporting docs link where applicable	guided-workflow exception already inherent to the onboarding wizard
Tenant dashboard support-diagnostic preview	Dashboard / Overview / Actions	Tenant troubleshooting support entry point	Open support diagnostics and follow the documented next troubleshooting step	Explicit support-diagnostics action opens the read-only preview	forbidden	Related record links and docs links remain inside the preview	none	/admin/t/{tenant}	/admin/t/{tenant}	Active workspace, active tenant, help topic scope, bundle freshness	Support diagnostics / Diagnostic help	Dominant issue meaning, troubleshooting guidance, and supporting docs links	dashboard-action entry point only; help remains read-only
Operation detail support-diagnostic preview	Record / Detail / Actions	Canonical diagnostic detail support entry point	Open support diagnostics and follow the documented next troubleshooting step	Existing operation detail plus one explicit support-diagnostics action	forbidden	Related record links and docs links remain inside the preview	none	/admin/operations	/admin/operations/{run}	Workspace context, tenant context when present, help topic scope, bundle freshness	Support diagnostics / Diagnostic help	Dominant issue meaning, troubleshooting guidance, and supporting docs links	none

Operator Surface Contract (mandatory when operator-facing surfaces are changed)

Surface	Primary Persona	Decision / Operator Action Supported	Surface Type	Primary Operator Question	Default-visible Information	Diagnostics-only Information	Status Dimensions Used	Mutation Scope	Primary Actions	Dangerous Actions
Managed tenant onboarding workflow	Workspace operator managing tenant setup	Decide what the current blocker means and what action to take next	Guided workflow	What does this blocker mean, and what should I do next?	readiness headline, blocker explanation, one safe next action, one docs link where relevant, and current checkpoint context	provider-specific evidence, full verification report, operation detail, low-level identifiers	readiness, data freshness, provider health, operator actionability	Existing onboarding actions keep their current scope; the help layer itself is read-only	Continue onboarding, open docs link, open supporting diagnostics	Existing cancel/delete draft actions remain unchanged
Tenant dashboard support-diagnostic preview	Support-capable tenant operator or manager	Decide whether to troubleshoot, hand off, or escalate a tenant issue	Read-only preview	What does the current tenant issue mean, and which documented next step is safest?	dominant issue explanation, contextual help headline, troubleshooting steps, and docs links	full support bundle sections, related records, provider diagnostics, audit references	execution outcome, provider health, findings pressure, guidance actionability	none	Open support diagnostics, open docs link, open related records	none
Operation detail support-diagnostic preview	Support-capable operator	Decide whether to troubleshoot, hand off, or escalate a run-centered issue	Read-only preview	What does this run outcome mean, and which documented next step applies?	dominant issue explanation, contextual help headline, troubleshooting steps, and docs links	full support bundle sections, run detail, provider diagnostics, audit references	execution outcome, trustworthiness, guidance actionability	none	Open support diagnostics, open docs link, open related records	none

Proportionality Review (mandatory when structural complexity is introduced)

• New source of truth?: no
• New persisted entity/table/artifact?: no
• New abstraction?: yes
• New enum/state/reason family?: no
• New cross-domain UI framework/taxonomy?: yes, one bounded contextual-help topic catalog for the first slice
• Current operator problem: operators still need founder explanation or external notes to interpret onboarding blockers and support-diagnostic dominant issues safely.
• Existing structure is insufficient because: glossary and reason translation explain current state, but they do not provide one reusable, versioned, cross-surface product-knowledge layer with troubleshooting hints, docs links, or a machine-readable knowledge source.
• Narrowest correct implementation: one code-owned contextual-help catalog plus one resolver for onboarding and support diagnostics only, reusing existing glossary/reason/support primitives and avoiding persistence, CMS tooling, or AI execution.
• Ownership cost: maintain help topic keys, docs-link mappings, glossary alignment, fallback handling, and focused unit plus feature tests.
• Alternative intentionally rejected: page-local help copy was rejected as drift-prone, and a full public-docs/help-center platform was rejected as broader than current-release truth.
• Release truth: current-release truth

Compatibility posture

This feature assumes a pre-production environment.

Backward compatibility, legacy aliases, migration shims, historical fixtures, and compatibility-specific tests are out of scope unless explicitly required by this spec.

Canonical replacement is preferred over preservation.

Testing / Lane / Runtime Impact (mandatory for runtime behavior changes)

• Test purpose / classification: Unit, Feature
• Validation lane(s): fast-feedback, confidence
• Why this classification and these lanes are sufficient: unit tests prove the bounded catalog, topic resolution, glossary linkage, and fallback behavior. Feature tests prove the two adopted surfaces render contextual help only after existing authorization succeeds and do so without introducing new routes, persistence, or browser-only behavior.
• New or expanded test families: one focused ProductKnowledge unit family and targeted feature coverage for onboarding help rendering, support-diagnostic help rendering, and authorization-safe fallback behavior.
• Fixture / helper cost impact: low-to-moderate. Reuse existing onboarding draft, tenant, workspace, provider connection, operation run, and support-diagnostic fixtures. No new browser harness, provider emulator, or heavy-governance lane is required.
• Heavy-family visibility / justification: none
• Special surface test profile: standard-native-filament, monitoring-state-page
• Standard-native relief or required special coverage: ordinary feature coverage is sufficient for the onboarding wizard; the operation detail adoption also needs one monitoring-state-page regression because the contextual help is rendered from the support-diagnostic path on a monitoring-oriented surface.
• Reviewer handoff: reviewers must confirm that contextual help remains registry-backed, progressive, and entitlement-safe; that missing help topics fail predictably; and that help copy does not become a second source of truth or change operation/onboarding authorization semantics.
• Budget / baseline / trend impact: low increase in narrow unit and feature coverage only
• Escalation needed: none
• Active feature PR close-out entry: Guardrail
• Planned validation commands:
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Unit/Support/ProductKnowledge/ContextualHelpCatalogTest.php tests/Unit/Support/ProductKnowledge/ContextualHelpResolverTest.php tests/Unit/Support/ProductKnowledge/ContextualHelpFallbackTest.php
  • export PATH="/bin:/usr/bin:/usr/local/bin:$PATH" && cd apps/platform && ./vendor/bin/sail artisan test --compact tests/Feature/Onboarding/ProductKnowledgeOnboardingHelpTest.php tests/Feature/SupportDiagnostics/ProductKnowledgeSupportDiagnosticHelpTest.php tests/Feature/SupportDiagnostics/ProductKnowledgeAuthorizationTest.php

First-Slice Topic Inventory (mandatory for implementation lock-in)

The first slice is locked to the following eight canonical help topic keys. Adding or replacing a first-slice topic requires an explicit spec update.

Topic Key	Intended Surface Families	Primary Trigger	Shared Truth Reused
admin-consent-required	onboarding, support diagnostics	provider readiness or dominant issue indicates admin consent is still required	RequiredPermissionsLinks, glossary terms, reason translation
required-permissions-missing	onboarding, support diagnostics	provider readiness or dominant issue indicates required permissions are missing or incomplete	RequiredPermissionsLinks, glossary terms, reason translation
connection-unhealthy	onboarding, support diagnostics	provider connection health is degraded or disconnected	operator explanation, reason translation, diagnostic summary
verification-stale	onboarding	verification has not been refreshed recently enough to trust readiness	onboarding verification state, glossary terms
verification-failed	onboarding, support diagnostics	verification or readiness checks completed with a failing result	operator explanation, reason translation
diagnostic-evidence-incomplete	support diagnostics	the bundle cannot prove a dominant issue with high confidence because evidence is incomplete	diagnostic bundle summary, glossary terms
retryable-provider-failure	support diagnostics	support diagnostics indicate a provider-side failure that is safe to retry or re-check	reason translation, operator explanation
manual-handoff-required	support diagnostics	the system can summarize the problem but requires a human support handoff or explicit escalation path	diagnostic bundle summary, glossary terms, approved docs links

User Scenarios & Testing (mandatory)

User Story 1 - Explain Onboarding Blockers In Context (Priority: P1)

As a workspace operator, I want onboarding blockers to show contextual help with canonical terminology, safe next steps, and supporting docs links so I can continue onboarding without founder intervention.

Why this priority: This is the most immediate operator-facing support reduction in the roadmap cluster and reuses the repo's existing onboarding and permission diagnostics foundations.

Independent Test: Open onboarding drafts that are blocked by missing consent, missing permissions, unhealthy provider connection, or stale verification and verify that the wizard shows registry-backed contextual help without changing the existing readiness truth.

Acceptance Scenarios:

1. Given an authorized operator opens an onboarding draft blocked by missing admin consent, When the readiness step renders, Then the workflow shows a contextual help headline, one safe next step, and an admin-consent docs/action link derived from the shared help registry.
2. Given an authorized operator opens an onboarding draft blocked by missing permissions or stale verification, When the readiness step renders, Then the workflow shows glossary-aligned contextual help that explains the blocker without replacing the existing verification or provider-truth sections.
3. Given the current user is not entitled to the onboarding scope, When they attempt to access the draft, Then the system still returns 404 or 403 according to existing rules and reveals no contextual-help details.

---

User Story 2 - Reuse The Same Product Knowledge In Support Diagnostics (Priority: P1)

As a support-capable operator, I want tenant and operation support-diagnostic previews to show the same contextual help language and troubleshooting guidance so support cases stop depending on ad-hoc explanation.

Why this priority: The second high-value surface proves the knowledge layer is genuinely reusable and not just onboarding-local prose.

Independent Test: Open tenant-context and operation-context support diagnostics for the same dominant issue and verify that the preview renders the same registry-backed help topic, troubleshooting hints, and supporting docs links.

Acceptance Scenarios:

1. Given a tenant support-diagnostic bundle resolves a dominant issue such as missing permissions or an unhealthy connection, When the preview renders, Then it includes registry-backed contextual help aligned with the dominant issue and leaves the existing diagnostic sections intact.
2. Given an operation-context support-diagnostic bundle resolves the same dominant issue, When the preview renders, Then it uses the same help topic key and glossary-aligned language rather than a second local explanation dialect.
3. Given the dominant issue has no configured help topic in the first slice, When the preview renders, Then the bundle degrades gracefully without exceptions or raw unresolved keys.
4. Given a user lacks the existing support-diagnostic entitlement for the tenant or operation scope, When they attempt to open the preview, Then the host surface preserves the current 404/403 behavior and reveals no contextual-help payload.

---

User Story 3 - Provide A Safe Machine-Readable Knowledge Source (Priority: P2)

As the product owner, I want the first-slice help catalog to expose a machine-readable knowledge source so later AI-assisted support can reuse trusted product knowledge without scraping UI prose or customer data.

Why this priority: This keeps the first slice aligned with later AI-adjacent work without forcing AI execution or broad platform scope into the current implementation.

Independent Test: Resolve the first-slice catalog into a machine-readable knowledge source and verify that it contains only topic metadata, glossary-aligned text, and allowed docs links, with no tenant-specific data or secrets.

Acceptance Scenarios:

1. Given the code-owned help catalog, When the machine-readable knowledge source is exported for internal product use, Then it contains only stable topic keys, headings, troubleshooting steps, and allowed links.
2. Given a help topic references existing route or docs helpers, When the machine-readable knowledge source is built, Then the exported representation contains only safe link metadata and never includes tenant-specific provider payloads, secrets, or free-text customer notes.

Edge Cases

• A host surface may resolve a reason or dominant issue that has no mapped help topic in the first slice; the UI must fail predictably and preserve the underlying truth without showing raw topic keys.
• A provider-owned topic may have both an internal product route and an external Microsoft docs link; the surfaced links must stay ordered and entitlement-safe.
• The same help topic may appear on onboarding and support diagnostics; the wording must remain stable even if the surrounding surface framing differs.
• Progressive disclosure must keep the help block subordinate to the surface's primary truth so the product does not imply the help copy is itself the source of truth.
• Localization remains out of scope for the first slice; help topics must stay ready for later localization without introducing a second vocabulary layer now.

Requirements (mandatory)

Constitution alignment (required): This feature introduces no new Graph call path and no new tenant-changing action. It adds a read-only contextual-help layer on top of existing onboarding and support-diagnostic truths. Existing write, queue, and audit semantics remain unchanged.

Constitution alignment (PROP-001 / ABSTR-001 / PERSIST-001 / STATE-001 / BLOAT-001): The slice introduces one new bounded abstraction because current-release operator workflows now need a reusable help layer. No new persistence, new state family, or generic knowledge platform is introduced.

Constitution alignment (XCUT-001): This slice is cross-cutting across onboarding and support diagnostics. It must reuse the existing glossary, reason-translation, operator-explanation, and support-diagnostic bundle paths rather than introducing page-local help dialects.

Constitution alignment (PROV-001): Provider-specific remediation remains bounded to provider-owned topics and existing docs-link helpers. Platform-core help topics remain provider-neutral.

Constitution alignment (TEST-GOV-001): Proof stays in focused unit and feature lanes only. No browser or heavy-governance family is justified.

Constitution alignment (RBAC-UX): Existing scope and capability checks remain authoritative. Help resolution must not widen access, leak hidden remediation destinations, or replace 404/403 semantics.

Constitution alignment (OPS-UX): The feature does not create or change OperationRun start, completion, notification, or link semantics.

Constitution alignment (BADGE-001): The feature introduces no new badge domain. If existing badge or status labels appear inside help, they must be reused from existing catalog-backed semantics.

Constitution alignment (UI-FIL-001): Operator-facing help must use native Filament or shared diagnostic primitives on adopted surfaces. No ad-hoc status cards or new local status language are allowed.

Constitution alignment (UI-NAMING-001): Help headlines, troubleshooting hints, docs links, and surrounding UI copy must preserve the same canonical vocabulary already used by reason translation, onboarding readiness, and support diagnostics.

Functional Requirements

• FR-244-001: The system MUST define one code-owned contextual-help catalog for the bounded first slice.
• FR-244-002: The catalog MUST use stable help topic keys and remain reviewable and versioned in the repository.
• FR-244-003: The contextual-help resolver MUST reuse PlatformVocabularyGlossary, reason-translation outputs, operator-explanation outputs, and existing docs-link helpers instead of duplicating those semantics.
• FR-244-004: The managed-tenant onboarding workflow MUST render registry-backed contextual help for the first-slice blocker families when a matching help topic exists.
• FR-244-005: Tenant-context and operation-context support-diagnostic previews MUST render registry-backed contextual help for the first-slice dominant-issue families when a matching help topic exists.
• FR-244-006: Contextual help MUST remain progressive disclosure and MUST NOT replace the host surface's primary truth sections.
• FR-244-007: Each help topic MUST support a bounded shape containing a headline, short explanation, troubleshooting steps, safe next action, and zero or more supporting docs links.
• FR-244-008: Help copy MUST reuse canonical glossary and reason-translation vocabulary and MUST NOT invent conflicting synonyms for onboarding, diagnostics, evidence, drift, support, or operation outcomes.
• FR-244-009: Provider-specific help MUST remain bounded to provider-owned topics and existing provider link helpers.
• FR-244-010: Missing or invalid help topics MUST degrade gracefully without exceptions, broken UI state, or raw unresolved topic keys.
• FR-244-011: The feature MUST expose a machine-readable knowledge source safe for future internal AI/support use without tenant-specific data, provider payloads, or secrets.
• FR-244-012: The first slice MUST NOT introduce a public documentation site, chatbot, CMS/editor, new database table, or customer-facing help center.
• FR-244-013: Contextual help MUST not change existing onboarding, support-diagnostic, or authorization behavior.
• FR-244-014: The feature MUST include regression coverage for onboarding help rendering, support-diagnostic help rendering, and missing-topic fallback behavior.
• FR-244-015: The feature MUST include at least one positive and one negative authorization regression proving that contextual help never leaks hidden scope or destinations.

UI Action Matrix (mandatory when Filament is changed)

Surface	Location	Header Actions	Inspect Affordance (List/Table)	Row Actions (max 2 visible)	Bulk Actions (grouped)	Empty-State CTA(s)	View Header Actions	Create/Edit Save+Cancel	Audit log?	Notes / Exemptions
Managed tenant onboarding workflow	apps/platform/app/Filament/Pages/Workspaces/ManagedTenantOnboardingWizard.php	Existing header actions remain unchanged	N/A	none added by this feature	none	existing empty/start state unchanged	N/A	existing onboarding actions unchanged	no	Adds a read-only contextual-help block only; no new destructive or mutating action
Tenant support-diagnostic preview host	apps/platform/app/Filament/Pages/TenantDashboard.php	Existing support-diagnostics action unchanged	N/A	none added by this feature	none	none	N/A	N/A	no	Help is rendered inside the preview content returned by the shared bundle builder
Operation detail support-diagnostic preview host	apps/platform/app/Filament/Pages/Operations/TenantlessOperationRunViewer.php	Existing support-diagnostics action unchanged	N/A	none added by this feature	none	none	existing run actions unchanged	N/A	no	Monitoring/detail action hierarchy remains unchanged; help annotates preview content only

Key Entities (include if feature involves data)

• Contextual Help Topic: A code-owned, versioned help entry identified by a stable topic key and containing bounded product guidance only.
• Contextual Help Resolution: A derived help payload built from catalog entries plus existing glossary, reason, operator-explanation, and docs-link inputs.
• Machine-Readable Knowledge Source: A safe export of the code-owned help catalog for future internal AI/support consumption.

Success Criteria (mandatory)

Measurable Outcomes

• SC-244-001: The first implementation slice renders registry-backed contextual help on at least two critical surfaces: the managed-tenant onboarding workflow and support-diagnostic previews.
• SC-244-002: In focused regression coverage, 100% of in-scope first-slice blocker and dominant-issue scenarios either render a matching help topic or degrade gracefully without errors or raw unresolved keys.
• SC-244-003: The machine-readable knowledge source contains only code-owned topic metadata and approved links, with 0 tenant-specific records, raw provider payloads, or secrets in regression coverage.
• SC-244-004: The adopted surfaces continue to use existing authorization semantics unchanged, with contextual help visible only after the host surface's existing entitlement checks succeed.