inter-hub/Web/View/StaticPages/Tutorial.hs

module Web.View.StaticPages.Tutorial where

import Web.View.Prelude

data TutorialView = TutorialView

instance View TutorialView where
    html TutorialView = [hsx|
        <div class="max-w-4xl mx-auto py-10 px-6">
            <div class="mb-8">
                <a href={LandingAction} class="text-sm text-indigo-600 hover:underline">← Home</a>
                <h1 class="text-3xl font-bold text-gray-900 mt-3 mb-2">Developer Tutorial</h1>
                <p class="text-gray-500">How IHF works from a developer perspective — widget lifecycle, governance flow, outcome loop.</p>
            </div>

            {-- Step 1: Hubs and Widgets --}
            <section class="mb-10">
                <h2 class="text-xl font-semibold text-gray-800 mb-3">{stepBadge "1"} Hubs and Widgets</h2>
                <p class="text-gray-600 mb-3">
                    A <strong>Hub</strong> is a bounded domain of responsibility (e.g. Dev Hub, Ops Hub, Fin Hub).
                    Hubs own Widgets — the smallest semantically governable interaction unit.
                    Each widget has a <code class="bg-gray-100 px-1 rounded text-sm">widget_id</code> (stable UUID),
                    a <code class="bg-gray-100 px-1 rounded text-sm">widget_type</code> (from the registry),
                    and a version history.
                </p>
                <div class="bg-gray-900 rounded-lg p-4 text-sm font-mono text-green-400">
                    <div class="text-gray-400 mb-1">-- Every rendered widget wraps its HSX in widgetEnvelope</div>
                    widgetEnvelope widgetId viewContext [hsx|...|]
                </div>
                <p class="text-sm text-gray-500 mt-2">
                    The envelope injects <code>data-widget-id</code> and <code>data-view-context</code> attributes,
                    enabling client-side event capture without coupling to implementation.
                </p>
            </section>

            {-- Step 2: Interaction Events --}
            <section class="mb-10">
                <h2 class="text-xl font-semibold text-gray-800 mb-3">{stepBadge "2"} Interaction Events</h2>
                <p class="text-gray-600 mb-3">
                    When a user or agent interacts with a widget, an <strong>InteractionEvent</strong> is recorded —
                    clicked, viewed, submitted, dismissed, etc. Events are <strong>append-only</strong>:
                    a PostgreSQL trigger prevents UPDATE and DELETE on the <code class="bg-gray-100 px-1 rounded text-sm">interaction_events</code> table.
                </p>
                <div class="bg-gray-900 rounded-lg p-4 text-sm font-mono text-green-400">
                    POST /api/v1/interaction-events<br/>
                    POST /api/v2/interaction-events
                </div>
                <p class="text-sm text-gray-500 mt-2">
                    Events flow into <strong>Annotations</strong> (human/agent commentary with category)
                    and eventually surface as RequirementCandidates.
                </p>
            </section>

            {-- Step 3: Governance flow --}
            <section class="mb-10">
                <h2 class="text-xl font-semibold text-gray-800 mb-3">{stepBadge "3"} Governance Flow</h2>
                <p class="text-gray-600 mb-3">
                    RequirementCandidates go through a triage lifecycle: <em>open → triaged → reviewed → promoted or dismissed</em>.
                    Phase 5 agents can draft Requirements from widget clusters using the Anthropic API.
                    Promoted candidates become <strong>Requirements</strong>, which are linked to <strong>DecisionRecords</strong>.
                </p>
                <div class="grid grid-cols-3 gap-3 text-xs text-center">
                    {flowBox "RequirementCandidate" "open · triaged · reviewed"}
                    {arrow_}
                    {flowBox "Requirement" "linked to Decision"}
                    {arrow_}
                    {flowBox "DecisionRecord" "policy refs · impl refs"}
                </div>
            </section>

            {-- Step 4: Deployment and outcomes --}
            <section class="mb-10">
                <h2 class="text-xl font-semibold text-gray-800 mb-3">{stepBadge "4"} Deployment and Outcomes</h2>
                <p class="text-gray-600 mb-3">
                    A DecisionRecord links to a <strong>DeploymentRecord</strong>. After deployment,
                    <strong>OutcomeSignals</strong> are recorded (also append-only) and evaluated via
                    <strong>ChangeEvaluations</strong>. Outcome feedback flows back to the DecisionRecord,
                    closing the governance loop.
                </p>
            </section>

            {-- Step 5: Learning --}
            <section class="mb-10">
                <h2 class="text-xl font-semibold text-gray-800 mb-3">{stepBadge "5"} Continuous Learning (Phase 12)</h2>
                <p class="text-gray-600 mb-3">
                    Phase 12 layers a learning engine on top of the governance loop:
                </p>
                <ul class="text-sm text-gray-600 space-y-1 list-disc list-inside">
                    <li><strong>OutcomeCorrelations</strong> — compute correlation scores between widget patterns and outcomes</li>
                    <li><strong>PatternPerformanceRecords</strong> — rank widget patterns by observed outcome quality</li>
                    <li><strong>AdaptiveThresholdConfigs</strong> — auto-calibrate friction and triage thresholds per hub</li>
                    <li><strong>InstitutionalKnowledgeBase</strong> — GIN full-text search over all governance decisions</li>
                    <li><strong>LearningInsights</strong> — actionable recommendations surfaced in the Learning Dashboard</li>
                </ul>
            </section>

            {-- Step 6: Hub federation --}
            <section class="mb-10">
                <h2 class="text-xl font-semibold text-gray-800 mb-3">{stepBadge "6"} Hub Federation</h2>
                <p class="text-gray-600 mb-3">
                    Multiple hubs interact via routing rules, stewardship roles, and federated policy overlays.
                    Cross-hub propagation patterns are detected automatically. The GAAF compliance layer
                    enforces type registry discipline and contract stability across hub boundaries.
                </p>
            </section>

            <div class="flex gap-4 text-sm mt-6">
                <a href={ExtensionGuideAction} class="text-indigo-600 hover:underline">Build a domain hub extension →</a>
                <a href={CapabilitiesAction} class="text-indigo-600 hover:underline">Full Capabilities →</a>
                <a href={HubsAction} class="text-indigo-600 hover:underline">Management UI →</a>
            </div>
        </div>
    |]
      where
        stepBadge n = [hsx|
            <span class="inline-flex items-center justify-center w-7 h-7 rounded-full bg-indigo-600 text-white text-sm font-bold mr-2">
                {n :: Text}
            </span>
        |]
        flowBox label_ sub_ = [hsx|
            <div class="bg-indigo-50 border border-indigo-200 rounded p-3">
                <div class="font-medium text-indigo-800 text-xs">{label_ :: Text}</div>
                <div class="text-indigo-500 text-xs mt-0.5">{sub_ :: Text}</div>
            </div>
        |]
        arrow_ = [hsx|<div class="flex items-center justify-center text-gray-400 text-xl">→</div>|]