@amityco/social-plus-vise 1.3.0 → 1.4.0

package/dist/tools/integration.js

@@ -1,10 +1,10 @@
 import { access, readFile } from "node:fs/promises";
 import path from "node:path";
-import { BROAD_SOCIAL_REGEX, DESIGN_REGEX, getOutcomeDefinition, hasAnswer, planContextFor, resolveOutcome, } from "../outcomes.js";
+import { BROAD_SOCIAL_REGEX, DESIGN_REGEX, getOutcomeDefinition, hasAnswer, planContextFor, platformFeatureGapsFor, resolveOutcome, } from "../outcomes.js";
 import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
 import { availableOptionalCapabilityIds, capabilityChecklist, optionalCapabilityChecklist, platformCapabilityAvailability, selectedOptionalCapabilityIds, slimCapabilityAvailability, slimCapabilityItem, } from "../capabilities.js";
 import { applicableCompliancePlanRuleSummaries } from "./compliance.js";
-import { DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID, buildDesignBrief, designContractConfirmationFromAnswers, designPreviewPath, readDesignContract, } from "./design.js";
+import { DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID, buildDesignBrief, designContractConfirmationFromAnswers, designPreviewPath, readDesignContract, readDesignProfile, buildDesignReviewLoop, } from "./design.js";
 import { sdkVersionGuidance } from "./sdkVersion.js";
 import { detectCommandSensors } from "./harness.js";
 import { inspectProject } from "./project.js";
@@ -12,6 +12,11 @@ import { creativeSurfaceHints, readCreativeSelection } from "./creative.js";
 import { buildUxHarness, uxHarnessPlanContext } from "./uxHarness.js";
 import { recommendSolutionPath } from "../solutionPath.js";
 import { recommendUIKitCustomization } from "../uikitCustomization.js";
+import { classifyEntryState } from "../entryState.js";
+import { readFlowState } from "../flow.js";
+import { clarifyDimensions, clarifyGuidance } from "../requestReadiness.js";
+import { assembleIntake } from "../intake.js";
+import { experienceBundleFor } from "../experience.js";
 export const planIntegrationTool = {
     name: "plan_integration",
     description: "Create a grounded, evidence-backed implementation packet before an AI coding agent edits a customer project.",
@@ -60,6 +65,13 @@ function answersFromInput(raw) {
 }
 async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}) {
     const repoRoot = path.resolve(repoPath);
+    if (!hasAnswer(answers, "solution_path")) {
+        const flow = await readFlowState(repoRoot);
+        const confirmedPath = flow?.request === request && flow.blueprint?.confirmed_digest ? flow.blueprint?.path ?? null : null;
+        if (confirmedPath) {
+            answers = { ...answers, solution_path: confirmedPath };
+        }
+    }
     const inspection = await inspectProject(repoRoot, surfacePath);
     const root = inspection.effectiveRoot;
     const storedCreativeSelection = await readCreativeSelection(repoRoot);
@@ -74,6 +86,14 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
     const uxHarnessOutcome = BROAD_SOCIAL_REGEX.test(request) && !hasAnswer(answers, "feature_surface") ? undefined : outcome;
     const uxHarnessContext = uxHarness ? uxHarnessPlanContext(uxHarness, uxHarnessOutcome) : undefined;
     const platform = preferredPlatform(inspection.platforms);
+    const platformAvailability = platformFeatureGapsFor(request, platform).map((gap) => ({
+        feature: gap.feature,
+        status: "unavailable-on-platform",
+        platform,
+        availableOn: gap.availableOn,
+        sdkSource: gap.sdkSource,
+        guidance: gap.guidance,
+    }));
     const baseSupportLevel = supportFor(outcome, platform);
     const sensors = await detectCommandSensors(root, inspection.platforms);
     const ctx = planContextFor({
@@ -92,7 +112,18 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
     const designContract = await readDesignContract(repoRoot);
     const designReview = designReviewGuidance(repoRoot, designContract, answers);
     const acceptedDesignContract = designReview.status === "accepted" ? designContract : null;
-    const designBrief = acceptedDesignContract ? buildDesignBrief(acceptedDesignContract) : undefined;
+    const designProfile = acceptedDesignContract ? await readDesignProfile(repoRoot) : null;
+    const designBrief = acceptedDesignContract ? buildDesignBrief(acceptedDesignContract, designProfile) : undefined;
+    const designReviewLoop = designProfile
+        ? solutionPath.recommendation === "uikit"
+            ? {
+                status: "uikit",
+                note: "Your social.plus UI comes from themed prebuilt UIKit components — there's no custom render to critique. Run `vise design check` to verify your UIKit theme config (`uikit.config.json` — its `theme.light`/`theme.dark` palette) matches the brand tokens; off-brand colours in it are reported as off-contract. Tune the UIKit theme rather than hand-building screens.",
+            }
+            : solutionPath.recommendation === "sdk" || solutionPath.recommendation === "hybrid"
+                ? buildDesignReviewLoop(designProfile)
+                : undefined
+        : undefined;
     const socialWorkplan = await socialWorkplanFor({
         request,
         answers,
@@ -112,7 +143,9 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
     const intake = intakeFor(ctx, outcomeQuestions, outcome, designBrief, capabilityAvailability, designReview);
     const packageJsonText = await readFile(path.join(root, "package.json"), "utf8").catch(() => undefined);
     const sdkVersion = await sdkVersionGuidance(platform, packageJsonText);
+    const crossPlatformHandoffSteps = crossPlatformImplementationSteps(platform, packageJsonText);
     const decisionsRequired = [
+        ...platformAvailability.map((notice) => `[platform limitation] ${notice.feature} is not exposed by the ${notice.platform} SDK (supported on ${notice.availableOn.join(", ")}). Decide an alternative — see platformAvailability — and state it; do not implement against a non-existent SDK API.`),
         ...solutionPathDecisions(solutionPath, answers),
         ...uikitCustomizationDecisions(uikitCustomization, answers),
         ...(creativeContext
@@ -129,13 +162,32 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
             ? `[resolve before building] ${q.question}`
             : `[decide & state in your summary] ${q.question}`),
     ];
+    const entryState = classifyEntryState({
+        outcome,
+        broadSocialRequest: ctx.broadSocialRequest,
+        mentionsDesign: ctx.mentionsDesign,
+        designSignalCount: ctx.designSignals.length,
+        solutionPath,
+        hasExplicitPathAnswer: hasAnswer(answers, "solution_path"),
+        multiSurface: Boolean(socialWorkplan),
+        creativeSelected: Boolean(creativeSelection),
+    });
+    const platformDetected = inspection.platforms.length > 0;
+    const clarify = clarifyGuidance(clarifyDimensions({
+        outcome,
+        platformDetected,
+        uikitGuidedUnknown: platformDetected && outcome === "unknown" && Boolean(uikitCustomization),
+        creativeSelected: Boolean(creativeSelection),
+    }));
     return {
         outcome,
         platform,
         solutionPath,
+        entryState,
         uikitCustomization,
         supportLevel,
         intent: intentFor(request, definition.interpretation, uikitCustomization),
+        ...(platformAvailability.length > 0 ? { platformAvailability } : {}),
         creativeContext,
         uxHarness: uxHarnessContext,
         socialWorkplan,
@@ -147,10 +199,12 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
             ...uxHarnessImplementationSteps(uxHarnessContext),
             ...solutionPathImplementationSteps(solutionPath),
             ...uikitCustomizationImplementationSteps(uikitCustomization),
+            ...crossPlatformHandoffSteps,
             ...definition.implementationSteps(ctx),
         ],
         validation: ["validate_setup", "run_sensors", ...definition.validation(platform)],
-        nextStep: nextStepForPlan(outcome, uikitCustomization, solutionPath),
+        ...(clarify ? { clarify } : {}),
+        nextStep: clarify ? clarify.nextStep : nextStepForPlan(outcome, uikitCustomization, solutionPath),
         requiredInputs: composeRequiredInputs(ctx, definition.requiredInputs(ctx)),
         targetFiles: await targetFilesFor(root, outcome, platform, inspection.designSignals),
         implementationRules: [
@@ -169,11 +223,168 @@ async function buildIntegrationPlan(repoPath, request, surfacePath, answers = {}
         stopConditions: composeStopConditions(ctx, definition.stopConditions(ctx), inspection.surfaces, surfacePath, Boolean(socialWorkplan), uikitCustomization),
         evidencePolicy: "Every implementation step must cite at least one detected file, docs page, validator rule, or required user input. If evidence is missing, stop and ask the user instead of inventing details.",
         designContract: acceptedDesignContract ? designContractGuidance(acceptedDesignContract) : undefined,
+        brandGrounding: designBrief?.brandGrounding,
+        designReviewLoop,
         completenessChecklist: completenessChecklistFor(outcome),
         optionalCapabilities: optionalCapabilitiesFor(outcome, ctx.answers, request, capabilityAvailability),
+        engagement: engagementMenuFor(outcome),
         sdkVersion,
     };
 }
+function crossPlatformImplementationSteps(platform, packageJsonText) {
+    if (platform === "flutter") {
+        return [
+            {
+                step: "Flutter product-entry pacing handoff: immediately route `lib/main.dart` to a product-native social surface, or create and import a visible product social widget, before broad pub-cache/source-internals research. In bounded dogfood, do not create a shell-first widget; the first social widget should already import `package:amity_sdk/amity_sdk.dart` and contain SDK setup/login plus at least one SDK data API call. Do not stop at static feature-preview cards that merely describe feed/comments/reactions/profile/chat; the surface must render SDK-returned/discovered/created objects, or honestly mark populated proof failed. Do not delete `lib/main.dart` as a standalone operation while preparing a replacement; edit it in place or add a new widget file and import it so interruptions never leave the app without an entry point. Do not spend the implementation budget only on `sp-vise/` artifacts, dependency installs, or reading SDK internals before the running app has a visible social route. If `flutter.sdk.source-used` fires, the app is still a dependency-only/static shell; import/use `package:amity_sdk/amity_sdk.dart` in product source before polishing UI. In dogfood/benchmark work, do not attest `flutter.sdk.source-used`; fix the source, rerun `vise check .`, and remove stale source-used attestations before claiming SDK-backed runtime proof.",
+                evidence: [
+                    "detectedFiles.lib/main.dart",
+                    "runtimeReadiness.targetDiscovery",
+                    "validate_setup.flutter.sdk.source-used",
+                    "implementationSteps",
+                ],
+            },
+            {
+                step: "Flutter dependency handoff: when using amity_sdk 7.x, add a direct `dio: 5.9.2` dependency or another bounded `<5.10.0` constraint before Android build proof. amity_sdk 7.x allows `dio ^5.4.0`, and dio 5.10.0 adds `DioExceptionType.transformTimeout`, which can make the SDK switch non-exhaustive during `assembleDebug` even when `flutter analyze` passes.",
+                evidence: [
+                    "validate_setup.flutter.dependency.dio-compatible",
+                    "pubspec.yaml",
+                    "pubspec.lock",
+                ],
+            },
+            {
+                step: "Flutter runtime-readiness handoff: before any login, feed, message, or live-collection query, call `WidgetsFlutterBinding.ensureInitialized()` and await `AmityCoreClient.setup(option: AmityCoreClientOption.create(apiKey: ..., endpoint: AmityEndpoint.<region>), sycInitialization: true)`. The synchronous flag waits for SDK database adapters such as MessageDbAdapter; without it, builds can pass while runtime fails with `MessageDbAdapter not ready`.",
+                evidence: [
+                    "social-plus-sdk/getting-started/platform-setup/mobile/flutter-quick-start",
+                    "social-plus-sdk/getting-started/authentication",
+                    "validate_setup.flutter.setup.sync-initialization",
+                ],
+            },
+            {
+                step: "Flutter query handoff: expose a reactive session-ready state from the login owner, seed it from the current SDK/session value, and trigger community/feed/chat queries only when that state becomes ready. Do not rely on `AmityCoreClient.observeSessionState().listen(...)` to emit the initial `NotLoggedIn` state; after subscribing, also kick the idempotent login/session branch immediately from `initState` (for example `Future.microtask(_login)` or an equivalent current-state branch), then let later observer emissions re-run post-login queries. A one-shot `initState` check that returns before login/setup completes, or an observer-only login path that never receives the initial state, leaves the screen stuck on signing-in/empty forever; render setup/login/query errors with a retry affordance.",
+                evidence: [
+                    "social-plus-sdk/getting-started/authentication",
+                    "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/flutter",
+                    "validate_setup.flutter.session.initial-login-kickoff",
+                ],
+            },
+            {
+                step: "Flutter populated-proof handoff: do not count a polished empty state as populated runtime proof for community/feed/comments. If discovery returns empty in dogfood, create safe seed data through SDK functions, select the returned community/feed/post in app state, re-query, and render at least one visible community plus one visible post/comment/reaction path. After seed creation, either update UI state from the returned SDK objects or wait for the live collection to emit the created content before handoff; a default screen still showing `0 posts`, `0 comments` on the only visible thread, `syncing`, `waiting on fresh community content`, or a create/prepare failure is not populated proof. If the exact session/coach/squad target cannot be created or populated because of tenant permissions/review mode, fall back to the nearest discovered readable community/feed that already has visible posts only when it passes the product-owned filter below. Do not dump arbitrary readable tenant data into product UI: skip/hide discovered objects whose names or descriptions are raw IDs, numeric-only labels, short random strings such as `rand2`, lorem/test data, `sampleapp` fixtures, or unrelated generated business copy, then keep searching or seed a product-native target. Prefer a product-owned namespace/allowlist such as app-created names, metadata tags, session/program identifiers, or cached IDs returned by the app's own create flow; if the SDK query returns mixed tenant data, render only product-safe matches and never let an unsafe target become the active selected context. Deduplicate discovered/seeded targets by stable SDK ID or normalized product label, and prioritize populated product-owned targets before empty clones; a long rail of repeated zero-post targets is not polished populated proof. Do not rewrite unsafe tenant labels into product copy to make them look acceptable — exclude the object. Apply that filter to every visible rail/list/card and author fallback, not only the selected target. Do not swallow seed/query exceptions silently; record failures in handoff notes and render a product-native retry/error state. If neither seeding nor discovered populated fallback works, record resolved empty-state proof only and do not claim populated proof. Runtime screenshots with yellow/black Flutter overflow banners, red error boxes, clipped action rows, or `BOTTOM OVERFLOWED BY ... PIXELS` are runtime failures; fix layout with bounded cards, Flexible/Expanded/Wrap, maxLines, ellipsis, and responsive spacing before handoff.",
+                evidence: [
+                    "runtimeReadiness.targetDiscovery",
+                    "runtimeReadiness.surfaces.smokeExpectation",
+                ],
+            },
+        ];
+    }
+    if (platform === "react-native") {
+        const rnVersion = reactNativeVersionFromPackage(packageJsonText);
+        const nodeMajor = Number.parseInt(process.versions.node.split(".")[0] ?? "0", 10);
+        const toolchainNote = rnVersion && compareSemver(rnVersion, "0.82.0") >= 0
+            ? ` Detected React Native ${rnVersion}; local Node is ${process.version}. Run npm install/build before Social+ work and treat any RN/Gradle/New-Architecture engine warning as benchmark setup friction until the clean baseline also launches.`
+            : "";
+        const nodeNote = nodeMajor >= 23
+            ? " Node 23+ is ahead of most React Native LTS guidance; if install/build emits engine warnings, prefer an LTS Node for implementation proof or record the warning separately from Social+ correctness."
+            : "";
+        return [
+            {
+                step: "React Native product-entry pacing handoff: immediately route `App.tsx` to a product-native social surface, or create and import a visible product social component, before broad node_modules/source-internals research. In bounded dogfood, do not create a shell-first component; the first social component should already import `@amityco/ts-sdk-react-native` from the package root and contain SDK setup/login plus at least one SDK data API call such as community/feed/comment/reaction retrieval or creation. Do not stop at static feature-preview cards that merely describe feed/comments/reactions/profile/chat; the surface must render SDK-returned/discovered/created objects, or honestly mark populated proof failed. If `react-native.sdk.source-used` fires, the app is still a dependency-only/static shell; import/use the SDK in product source before polishing UI. In dogfood/benchmark work, do not attest `react-native.sdk.source-used`; fix the source, rerun `vise check .`, and remove stale source-used attestations before claiming SDK-backed runtime proof.",
+                evidence: [
+                    "detectedFiles.App.tsx",
+                    "runtimeReadiness.targetDiscovery",
+                    "validate_setup.react-native.sdk.source-used",
+                    "implementationSteps",
+                ],
+            },
+            {
+                step: `React Native runtime-readiness handoff: use \`@amityco/ts-sdk-react-native\`, add an SDK-compatible \`@react-native-async-storage/async-storage\` v1.x app dependency (for example \`^1.24.0\`, not latest 2.x/3.x) and \`@react-native-community/netinfo\` as app dependencies so npm dedupes to one native-backed storage package and React Native autolinks the required native modules, initialize with positional region \`Client.createClient(apiKey, API_REGIONS.SG)\` or the app's configured region, retain the session handler for the app lifetime, and call \`renewal.renew()\` from \`sessionWillRenewAccessToken\`. After \`createClient\`, set a stateful \`clientReady\` flag, call \`Client.login(..., sessionHandler)\` from an effect keyed by \`clientReady\` and the runtime user, set an explicit \`authReady\` / \`loggedIn\` state from the login promise resolution, and drive SDK queries from \`authReady\` or a normalized established session helper; do not rely on \`Client.onSessionStateChange\` alone to advance a cold launch. Add bounded retry/error handling when login stays \`notLoggedIn\`, so runtime proof never ends on a permanent spinner. Never deep-import SDK internals like \`@amityco/ts-sdk-react-native/dist/...\`; Metro/release bundling can fail even when TypeScript or Jest passes. Never seed React state by calling \`Client.isConnected()\` before the createClient path has run; return a safe not-ready state until a local \`clientCreated\` / \`clientReady\` flag is true, because \`Client.isConnected()\` can throw \`Amity SDK (800000): There is no active client\` at launch. Do not use the web-only package or an options-object createClient call.${toolchainNote}${nodeNote}`,
+                evidence: [
+                    "social-plus-sdk/getting-started/platform-setup/web/web-quick-start",
+                    "social-plus-sdk/getting-started/authentication",
+                    "validate_setup.react-native.dependency.async-storage",
+                    "validate_setup.react-native.dependency.async-storage-compatible",
+                    "validate_setup.react-native.dependency.netinfo",
+                    "validate_setup.react-native.session.renewal",
+                    "validate_setup.react-native.client.session-state-after-create",
+                    "validate_setup.react-native.sdk.no-internal-imports",
+                    "sdkVersion",
+                ],
+            },
+            {
+                step: "React Native target-discovery handoff: bridge only local API key/user/region config through ignored native build config; never bridge communityId, postId, channelId, targetId, or feedId. Resolve those from SDK search/list/create results or host navigation/app state, then pass the returned SDK object/id through normal React state. Treat native config bridge and native module output as unproven until a release/debug runtime smoke shows non-empty config, no `NativeModule: AsyncStorage is null` or `NativeModule.RNCNetInfo is null` log, and an established SDK session; a screen that says credentials/config are missing is failed populated proof even if BuildConfig and TypeScript checks pass. Record runtime proof in evidence/notes, not end-user UI: do not render `CLIENT`, `SESSION`, `RUNTIME`, SDK, env, region, setup/readiness-debug labels, visible runtime/probe/status panels, or hidden no-op controls in the product screen.",
+                evidence: [
+                    "requiredInputs.concrete feed target",
+                    "runtimeReadiness.targetDiscovery",
+                    "runtimeReadiness.runtimeProof",
+                ],
+            },
+            {
+                step: "React Native populated-proof handoff: an empty community/feed screen is not populated proof. If tenant discovery returns empty, create safe dogfood community/post/comment data through SDK calls, keep the returned objects in runtime state, re-query, and make the first runtime screen show at least one selected social target and one visible feed/comment/reaction path. Prefer a product-owned namespace/allowlist such as app-created names, metadata tags, program/session identifiers, or cached IDs returned by the app's own create flow. Filter every visible discovered rail/list/card and author fallback so raw IDs, numeric-only labels, short random strings like `rand2`, lorem/test fixtures, `sampleapp`, or unrelated tenant copy never appear in the product UI; never let an unsafe discovered target become the active selection, and do not rewrite bad labels/descriptions into product copy. Deduplicate discovered/seeded targets by stable SDK ID or normalized product label, and prioritize populated product-owned targets before empty clones. Runtime screenshots with red boxes, clipped action rows, or React Native layout/debug artifacts are runtime failures to repair. If data creation is not possible, label the run as resolved empty-state proof instead of product-proven populated proof.",
+                evidence: [
+                    "runtimeReadiness.targetDiscovery",
+                    "runtimeReadiness.surfaces.smokeExpectation",
+                ],
+            },
+        ];
+    }
+    if (platform === "ios") {
+        return [
+            {
+                step: "iOS product-entry pacing handoff: immediately route the SwiftUI root view or target UIViewController to a product-native social surface before broad SwiftPM/source-interface research. In bounded dogfood, the first social source edit should import `AmitySDK`, retain the client/session handler, login/register the runtime user, and use at least one real SDK data API such as `AmityCommunityRepository`, `AmityPostRepository`, `AmityUserRepository`, or `AmityChannelRepository`; `AmityClient` initialization plus static social cards is not enough. If `ios.sdk.source-used` fires, the app is still a dependency-only/static social shell; fix product Swift source and rerun `vise check .` before polishing UI or claiming runtime proof.",
+                evidence: [
+                    "runtimeReadiness.targetDiscovery",
+                    "validate_setup.ios.sdk.source-used",
+                    "implementationSteps",
+                ],
+            },
+            {
+                step: "iOS runtime-readiness handoff: read API key, region, runtime user, and display name from local-only environment or existing host config, never from committed literals. Do not add communityId, postId, channelId, targetId, or feedId to Info.plist/xcconfig/env; discover or create those targets through SDK queries/create flows, store returned objects in app state, and keep VISE_SMOKE markers log-only. For populated proof, the launched social route must show SDK-backed product-safe community/feed/profile/chat data, not static fallback cards or setup/debug labels.",
+                evidence: [
+                    "runtimeReadiness.targetDiscovery",
+                    "runtimeReadiness.runtimeProof",
+                    "runtimeReadiness.surfaces.smokeExpectation",
+                ],
+            },
+        ];
+    }
+    return [];
+}
+function reactNativeVersionFromPackage(packageJsonText) {
+    if (!packageJsonText)
+        return undefined;
+    try {
+        const pkg = JSON.parse(packageJsonText);
+        const raw = pkg.dependencies?.["react-native"] ?? pkg.devDependencies?.["react-native"];
+        if (!raw)
+            return undefined;
+        const match = String(raw).match(/(\d+\.\d+\.\d+)/);
+        return match?.[1];
+    }
+    catch {
+        return undefined;
+    }
+}
+function compareSemver(a, b) {
+    const pa = a.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    const pb = b.split(".").map((part) => Number.parseInt(part, 10) || 0);
+    for (let i = 0; i < 3; i += 1) {
+        if (pa[i] !== pb[i])
+            return pa[i] - pb[i];
+    }
+    return 0;
+}
+function engagementMenuFor(outcome) {
+    const baselineLevers = capabilityChecklist(outcome).map((capability) => capability.id);
+    const optionalLevers = optionalCapabilityChecklist(outcome).map((capability) => capability.id);
+    if (baselineLevers.length === 0 && optionalLevers.length === 0) {
+        return undefined;
+    }
+    return {
+        note: "Engagement levers for this surface (advisory). Build the baseline for completeness; treat the optional levers as the menu that makes the experience compelling — don't ship the bare minimum (e.g. a text-only feed with no reactions or polls).",
+        baselineLevers,
+        optionalLevers,
+        deepenWith: 'Run `vise creative . --request "<intent>"` for Engagement Intelligence (candidate solutions, engagement options, and tradeoffs for this surface) before committing to scope.',
+    };
+}
 function completenessChecklistFor(outcome) {
     const items = capabilityChecklist(outcome);
     if (items.length === 0) {
@@ -292,13 +503,23 @@ function supportLevelForPlan(outcome, platform, baseSupportLevel, uikitCustomiza
     return baseSupportLevel;
 }
 function nextStepForPlan(outcome, uikitCustomization, solutionPath) {
+    const ENGAGEMENT_HINT = " For engagement options (post types, polls, reactions, conversation and following patterns, and other ways to deepen the experience), run `vise creative . --request \"<intent>\"` before building — it surfaces levers `vise plan` lists only tersely under `optionalCapabilities`/`engagement`.";
+    const engagementHint = outcome === "add-feed" ||
+        outcome === "add-community" ||
+        outcome === "add-comments" ||
+        outcome === "add-chat" ||
+        outcome === "add-follow" ||
+        outcome === "add-notifications"
+        ? ENGAGEMENT_HINT
+        : "";
     if (outcome === "unknown" && uikitCustomization) {
-        return "Treat this as UIKit customization guidance first: resolve the UIKit route and concrete app/platform target, then implement customer-owned config, localization, behavior, fork, or SDK custom UI changes with local build evidence. Do not claim `vise check` deterministically validates hidden UIKit internals.";
+        const uikitEngagementHint = solutionPath.decision.requiredBeforeHandRolledUi ? ENGAGEMENT_HINT : "";
+        return "Treat this as UIKit customization guidance first: resolve the UIKit route and concrete app/platform target, then implement customer-owned config, localization, behavior, fork, or SDK custom UI changes with local build evidence. Do not claim `vise check` deterministically validates hidden UIKit internals." + uikitEngagementHint;
     }
     if (solutionPath.decision.requiredBeforeHandRolledUi) {
-        return "First resolve the solution-path decision (UIKit vs SDK vs hybrid). The SDK implementation steps above apply only if you build this surface directly with the SDK (or the SDK side of a hybrid); if the customer uses social.plus UIKit for the standard surface, follow the UIKit guidance instead of hand-rolling those steps. Once the route is settled, implement the applicable steps, then run `vise check .` and fix findings until green — you are not done until the check passes or each finding is explicitly attested.";
+        return "First resolve the solution-path decision (UIKit vs SDK vs hybrid). The SDK implementation steps above apply only if you build this surface directly with the SDK (or the SDK side of a hybrid); if the customer uses social.plus UIKit for the standard surface, follow the UIKit guidance instead of hand-rolling those steps. Once the route is settled, implement the applicable steps, then run `vise check .` and fix findings until green — you are not done until the check passes or each finding is explicitly attested." + engagementHint;
     }
-    return "After implementing every step above, run `vise check .` and fix findings until green. You are not done until the check passes or each finding is explicitly attested.";
+    return "After implementing every step above, run `vise check .` and fix findings until green. You are not done until the check passes or each finding is explicitly attested." + engagementHint;
 }
 function dedupeDocsByPath(docs) {
     const seen = new Set();
@@ -434,6 +655,12 @@ const SOCIAL_SURFACE_SEQUENCE = [
         aliases: [/\b(feed|timeline|news feed|post list|posts?|create post|post creation|compose post|composer|reactions?)\b/i],
         defaultForGenericBroad: true,
     },
+    {
+        id: "livestream",
+        outcome: "setup-live-data",
+        label: "Live room and broadcast",
+        aliases: [/\b(live\s?stream(?:ing)?|live\s+video|live\s+room|broadcast(?:ing)?|go(?:ing)?\s+live)\b/i],
+    },
     {
         id: "comments",
         outcome: "add-comments",
@@ -472,20 +699,17 @@ async function socialWorkplanFor(args) {
     if (hasAnswer(args.answers, "feature_surface")) {
         return undefined;
     }
+    const experience = experienceBundleFor(args.request);
     const creativeHints = args.creativeSelection ? creativeSurfaceHints(args.creativeSelection) : [];
     const useCreativeSequence = creativeHints.length > 1;
-    if (!BROAD_SOCIAL_REGEX.test(args.request) && !useCreativeSequence) {
+    if (!useCreativeSequence) {
         return undefined;
     }
     const matched = SOCIAL_SURFACE_SEQUENCE.filter((surface) => surface.aliases.some((pattern) => pattern.test(args.request)));
-    const selected = useCreativeSequence
-        ? creativeHints.flatMap((hint) => {
-            const surface = SOCIAL_SURFACE_SEQUENCE.find((item) => item.id === hint.id);
-            return surface ? [{ surface, creativeHint: hint }] : [];
-        })
-        : (matched.length > 0
-            ? matched
-            : SOCIAL_SURFACE_SEQUENCE.filter((surface) => surface.defaultForGenericBroad)).map((surface) => ({ surface, creativeHint: undefined }));
+    const selected = creativeHints.flatMap((hint) => {
+        const surface = SOCIAL_SURFACE_SEQUENCE.find((item) => item.id === hint.id);
+        return surface ? [{ surface, creativeHint: hint }] : [];
+    });
     if (selected.length <= 1) {
         return undefined;
     }
@@ -505,8 +729,10 @@ async function socialWorkplanFor(args) {
             }),
             broadSocialRequest: false,
         };
-        const intake = intakeFor(surfaceCtx, definition.intakeQuestions(surfaceCtx), surface.outcome, args.designBrief, capabilityAvailability, args.designReview);
+        const intake = intakeFor(surfaceCtx, definition.intakeQuestions(surfaceCtx), surface.outcome, args.designBrief, capabilityAvailability, args.designReview, [DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID]);
         const matchedPrompt = matched.some((match) => match.id === surface.id);
+        const companionEntry = experience && !matchedPrompt ? experience.surfaces.find((entry) => entry.id === surface.id) : undefined;
+        const companion = companionEntry ? { tier: companionEntry.tier, viaExperience: experience.id } : undefined;
         const commonArgs = `. --request ${shellQuote(args.request)} --answer feature_surface=${surface.id}`;
         sequence.push({
             id: surface.id,
@@ -514,9 +740,12 @@ async function socialWorkplanFor(args) {
             outcome: surface.outcome,
             label: surface.label,
             matchedPrompt,
-            reason: creativeHint?.reason ?? (matchedPrompt
-                ? `The request explicitly mentions ${surface.label.toLowerCase()}.`
-                : "The request is generic broad social work, so Vise includes this core surface in the default sequence."),
+            ...(companion ? { companion } : {}),
+            reason: companion
+                ? `Included to make the ${companion.viaExperience} experience coherent (${companion.tier}); confirm or trim at the blueprint sign-off.`
+                : creativeHint?.reason ?? (matchedPrompt
+                    ? `The request explicitly mentions ${surface.label.toLowerCase()}.`
+                    : "The request is generic broad social work, so Vise includes this core surface in the default sequence."),
             planCommand: `vise plan ${commonArgs}`,
             initCommand: `vise init ${commonArgs}`,
             intake: {
@@ -537,8 +766,8 @@ async function socialWorkplanFor(args) {
         kind: "social-multi-surface",
         status,
         note: useCreativeSequence
-            ? "This accepted creative variant is decomposed into ordered per-surface plans from its experience objects. Initialize and check one surface at a time so each sidecar has one deterministic outcome, while using this sequence as the coordinated product workplan."
-            : "This broad social request is decomposed into ordered per-surface plans. Initialize and check one surface at a time so each sidecar has one outcome, while using this sequence as the coordinated product workplan.",
+            ? "This accepted creative variant is decomposed into ordered per-surface plans from its experience objects. Initialize and check one surface at a time so each sidecar has one deterministic outcome, while using this sequence as the coordinated product workplan. Do not skip ahead to a later surface; after blueprint sign-off `vise init` enforces the next pending surface from `vise workplan next/status`."
+            : "This broad social request is decomposed into ordered per-surface plans. Initialize and check one surface at a time so each sidecar has one outcome, while using this sequence as the coordinated product workplan. Do not skip ahead to a later surface; after blueprint sign-off `vise init` enforces the next pending surface from `vise workplan next/status`.",
         creativeContext: args.creativeSelection
             ? {
                 selectedVariant: creativeContextForPlan(args.creativeSelection).selectedVariant,
@@ -547,7 +776,7 @@ async function socialWorkplanFor(args) {
             : undefined,
         uxHarness: args.uxHarness ? uxHarnessPlanContext(args.uxHarness) : undefined,
         sequence,
-        nextStep: "Resolve each surface's blocking questions, then run the listed plan/init command for that surface before implementation. After each surface build, run `vise check .`, `vise sync .`, `vise validate .`, and `vise run-sensors .`.",
+        nextStep: "Run `vise workplan next/status` and implement only the next pending surface it prints. Resolve that surface's blocking questions, run its listed plan/init command, implement it, then run `vise check .`, `vise sync .`, `vise validate .`, `vise run-sensors .`, and `vise workplan complete` before moving to the next surface.",
     };
 }
 function shellQuote(value) {
@@ -641,74 +870,18 @@ function intentFor(request, interpretation, uikitCustomization) {
         ambiguity: broadSocialRequest || designRequest || uikitCustomization?.status === "needs-decision" || uikitOnlyCustomization ? "high" : "medium",
     };
 }
-function intakeFor(ctx, outcomeQuestions, outcome, brief, availability, designReview) {
-    const questions = [...outcomeQuestions];
-    if (designReview?.status === "needs-confirmation" && !hasAnswer(ctx.answers, DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID)) {
-        questions.push({
-            id: DESIGN_CONTRACT_CONFIRMATION_ANSWER_ID,
-            question: `Open ${designReview.previewPath} and confirm whether this design preview/contract should be used for the social UI.`,
-            why: "A design contract must be explicitly accepted before Vise can feed it forward or let the agent claim design conformance. If it is wrong, reject it and provide the correct design source.",
-            required: true,
-            blocksImplementationWhenMissing: true,
-            options: ["yes", "no"],
-        });
-    }
-    if (designReview?.status === "rejected" && !hasAnswer(ctx.answers, "design_source")) {
-        questions.push({
-            id: "design_source",
-            question: "What design source should replace the rejected preview/contract?",
-            why: "The current design preview was rejected, so Vise must not use it. Provide a prototype, screenshot, theme/token file, or explicitly say to proceed without a design-conformance claim.",
-            required: true,
-            blocksImplementationWhenMissing: true,
-        });
-    }
-    if (ctx.mentionsDesign && ctx.designSignals.length === 0 && !hasAnswer(ctx.answers, "design_source")) {
-        questions.push({
-            id: "design_source",
-            question: "Where are the app's design tokens, theme, or reusable UI components defined?",
-            why: "The user asked to match the existing design, and no local design source was detected.",
-            required: true,
-            blocksImplementationWhenMissing: true,
-        });
-    }
-    if (ctx.mentionsDesign && ctx.designSignals.length > 0 && !hasAnswer(ctx.answers, "confirm_design_source")) {
-        questions.push({
-            id: "confirm_design_source",
-            question: `Should the social UI use the detected design source(s): ${ctx.designSignals.map((signal) => signal.file).join(", ")}?`,
-            why: "Vise found likely design evidence, but the user or host agent should confirm it is the right source before UI edits.",
-            required: true,
-            blocksImplementationWhenMissing: false,
-            options: ["yes", "use another source"],
-        });
-    }
-    if (brief &&
-        designReview?.status === "accepted" &&
-        (outcome === "add-feed" || outcome === "add-chat") &&
-        !brief.roles.some((r) => r.role === "primaryAction") &&
-        !hasAnswer(ctx.answers, "primary_action_token")) {
-        questions.push({
-            id: "primary_action_token",
-            question: "Which design token (or color value) should be used as the primary action color? No primary-action token was confidently identified in the design contract.",
-            why: "A primary action colour is needed for interactive elements (composer button, own-message bubble). Without a confident token, the agent must guess or omit it.",
-            required: false,
-            blocksImplementationWhenMissing: false,
-        });
-    }
-    const availableOptionalIds = availableOptionalCapabilityIds(availability);
-    const optionalChoices = outcome === "add-feed" ? optionalCapabilityChecklist(outcome, availableOptionalIds) : [];
-    if (outcome === "add-feed" && optionalChoices.length > 0 && !hasAnswer(ctx.answers, "feed_optional_capabilities")) {
-        questions.push({
-            id: "feed_optional_capabilities",
-            question: `Which optional feed capabilities should be in scope on ${ctx.platform}: ${optionalChoices.map((capability) => capability.id).join(", ")}, or none?`,
-            why: "These capabilities are useful for full feeds, but should become enforceable only after the customer explicitly opts in. Vise only lists capabilities that appear available in the platform SDK surface; unsupported capabilities must be treated as out of scope or confirmed from docs.",
-            required: false,
-            blocksImplementationWhenMissing: false,
-            options: ["none", ...optionalChoices.map((capability) => capability.id)],
-        });
-    }
-    const remainingBlocking = questions.filter((question) => question.blocksImplementationWhenMissing).length;
+function intakeFor(ctx, outcomeQuestions, outcome, brief, availability, designReview, suppressGateIds) {
+    const { questions, remainingBlocking, status } = assembleIntake({
+        ctx,
+        outcomeQuestions,
+        outcome,
+        designBrief: brief,
+        capabilityAvailability: availability,
+        designReview,
+        suppressGateIds,
+    });
     return {
-        status: remainingBlocking > 0 ? "needs-clarification" : "ready",
+        status,
         questions,
         answers: ctx.answers,
         remainingBlocking,

package/dist/tools/learning.js

@@ -1,5 +1,6 @@
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
+import { sidecarDir } from "../sidecar.js";
 import { objectInput, optionalBooleanField, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
 import { readCreativeSelection } from "./creative.js";
@@ -475,9 +476,6 @@ async function writeLearningSummary(repoRoot, summary) {
     await mkdir(path.dirname(filePath), { recursive: true });
     await writeFile(filePath, `${JSON.stringify(summary, null, 2)}\n`, "utf8");
 }
-function sidecarDir(repoRoot) {
-    return path.join(repoRoot, "sp-vise");
-}
 function privacyBlock() {
     return {
         mode: "local-only",