@amityco/social-plus-vise 1.1.1 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,49 @@ All notable changes to `@amityco/social-plus-vise` are documented in this file.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.3.0 — 2026-06-19
+
+Discovery + readability surface, CLI/report honesty, and a batch of detector-precision fixes from two real-agent persona-dogfood sweeps (Sonnet 4.6), each fix mutation-verified and the whole batch adversarially reviewed. **No change to `vise check` exit codes, compliance rules, or sidecar *formats*** — the sidecar gains only **additive** fields (see Compatibility). The rule corpus is unchanged, so the contract digest is stable and no re-attestation is triggered.
+
+### Added
+- **`vise explore "<request>"`** — a pre-credentials, read-only discovery command. It maps a free-text request to a candidate feature/setup outcome (and lists the full menu when it can't, instead of dead-ending on `outcome:unknown`); each route carries the capabilities involved, the canonical docs, and the `vise plan` command to start. No project or API key required.
+- **`--format human`** on the read commands (`check` · `status` · `plan` · `doctor` · `explain` · `explore`). **JSON stays the default** — agents, CI, and sidecar-consuming flows parse stdout, so the default is unchanged; `--format human` is opt-in.
+- **`vise explain`** with no id now **enumerates the valid rule ids** (grouped by public id → contract ids) instead of erroring.
+- **`completeness` / selected-capability detail** is now surfaced by **`vise status`** and the init-time `findings.json` snapshot, mirroring `vise check`. Previously a `needs-attestation` / `deterministic-failures` headline (status precedence) hid a co-existing completeness-gap from anything reading those two surfaces.
+- **Brownfield baseline gate.** `vise baseline` (and `vise init --baseline`) snapshots the current pre-existing findings to `sp-vise/baseline.json`, and **`vise check --new-only`** (also `status --new-only`) gates only on findings introduced *since* the baseline — legacy findings are reported (`baselined: true`) but excluded. This makes `check` usable as a per-PR merge gate on an existing codebase. **Gate integrity:** subtraction is an explicit per-invocation flag, *never* the default — a bare `vise check` always gates on everything, so a green exit can never silently mean "no *new* gaps." A stale baseline (ruleset digest moved since it was recorded) is **not** applied (fail-safe: gate on everything and disclose `baseline.stale`). The artifact is additive — absent ⇒ unchanged behavior; the frozen sidecar-compat baseline is unaffected. Known v1 limitation, surfaced in the check output as `baseline.residual_caveat`: the rule+file key can mask a new violation of an already-baselined rule in the same file.
+
+### Changed
+- **Honesty of reports.** `attest` re-runs the deterministic sensor and **discloses** a live violation (without refusing — attestation is the override path); `check`/`status` carry an `evidence_basis_note` (plain-language "passed by absence" caveat); `vise status` propagates the body exit code to the process exit; `--ci` `blockingResultStatuses` enumerates every non-green status (incl. completeness-gap, selected-capability-failures); `explain` surfaces the feedforward/symptoms/inferential corpus fields; `doctor` surfaces the support channel.
+- **`vise debug`** correlates runtime-only symptom matches regardless of compliance status (a passing rule is framed as a runtime/out-of-sensor-reach signal, never a compliance failure), and maps `Cannot find module` / `MODULE_NOT_FOUND` for a **bare package** to a concrete `npm install` remediation — a failing correlated rule still wins the headline (the module hint rides as a secondary note).
+- **`vise init` intake validation.** Out-of-enum values (on closed-enum questions) and unrecognized `--answer` keys now produce advisory **warnings** instead of being silently accepted/dropped. Warnings only — never a rejection — so multi-select and free-form answers are unaffected.
+- **`engagement --scope`** accepts the full planner outcome vocabulary (derived from the classifier order), including `add-follow` / `add-community` / `add-notifications`, which were previously rejected.
+- **Classifier routing.** "community profile" → `add-community`, "user/member profile" (with a social qualifier) → `add-follow`, "notifications tray" → `add-notifications`; a non-social "company/performance/memory profile" stays `unknown`.
+- **`design check` coverage** splits `referenced_in_app` vs `seeded_only_tokens` — tokens that appear only in the Vise-scaffolded token file no longer inflate a false 100% (the raw `referenced` count is unchanged for back-compat).
+
+### Fixed
+- **Advisory routing precision** (advisory-only; no gate change): an explicit "build it with our own component" / "replace the UIKit surface" ask now routes SDK/custom-UI instead of Dynamic-UI; Console/theming phrasing corrected.
+- **Detector false positives.** `posts.status-filtered` no longer mis-attributes to `.d.ts` type stubs; `chat.send-error-handling` requires a real message *send* call (a read-only `markRead` view no longer fires); Android `comments.observer-cleanup` recognizes structured-concurrency cleanup (`stateIn(viewModelScope)` / `collectAsStateWithLifecycle` / `repeatOnLifecycle` / `DisposableEffect`), anchored to the observer's own chain; a negated "no custom code" no longer trips behavior-overrides; `scope-omit` reasons must be auditable (≥ 8 chars).
+- **`*.sdk.version.pinned` messages** now name each platform's real uncontrolled tokens (Android `+`/`:latest`, Flutter `any`, iOS moving branch / unspecified CocoaPods, TypeScript `latest`/`*`/`x` with `^`/`~` accepted). The rule **rationale is unchanged** (it is part of the contract digest; rewording it would force re-attestation — see the digest note in maintainer docs).
+- **`sdk-facts`**: the "names-only grounding" caveat now prints only when grounding is actually names-only; native platforms note that an empty `capabilities` list reflects TypeScript-first capability authoring, not lack of SDK support.
+- **Design contract** confirmation re-routes to `needs-confirmation` when the preview is absent; the design reference inlines only sanitized `:root` token declarations, never raw source.
+- Concrete CLI bugs from the first sweep (broken docs path, `engagement` show/init path mismatch, `workplan.json` persistence, and related discovery/intake edges).
+
+### Compatibility
+- **No exit-code or sidecar-*format* breaking changes.** The `completeness` / `selectedOptionalCapabilities` fields added to `vise status` / the init `findings.json` snapshot, and the new `sp-vise/baseline.json` artifact, are all **additive**; the `test:sidecar-compat` baseline (frozen 1.1.0 sidecar, no baseline.json) stays green. The rule corpus and contract digest are unchanged, so existing attestations are not invalidated. `vise check` with no flags is unchanged — the brownfield baseline only applies under the explicit `--new-only` flag.
+
+## 1.2.0 — 2026-06-18
+
+Adds advisory **solution-path / UIKit routing** and a fail-closed fix to the SwiftPM manifest sensor. No change to `vise check` exit codes, compliance rules, or sidecar **formats**; the one behavior change is the SwiftPM-timeout outcome noted under Changed.
+
+### Added
+- **Solution-path & UIKit routing (advisory).** `vise plan` emits `solutionPath` (`sdk` · `uikit` · `hybrid` · `needs-decision`) so an agent pauses for `--answer solution_path=…` before building the wrong layer, cleanly separating the two integrator postures (SDK/custom-UI vs UIKit/prebuilt-UI). When UIKit is in play it also emits `uikitCustomization`, recommending the lowest-effort tier that meets the goal (Dynamic UI → Component Styling → Localization → Behavior Overrides → Fork and Extend → SDK Custom UI). Both are **advisory only** — they never change outcome classification, compliance rules, the sidecar schema, or `vise check` exit codes. Documented under "Solution path & UIKit routing" in the README; the two postures are described in `docs/PERSONAS.md`.
+- **Real-build readiness checks** surfaced alongside the routing signals.
+
+### Changed
+- **SwiftPM manifest sensor: timeout is now RED (fail-closed), not a skip.** A manifest-parse timeout previously read as a clean green; for a pure-SwiftPM iOS project the manifest sensor is the only sensor, so a stall masqueraded as success. It now reports `timed-out` and the CLI exits non-zero. **Behavior note for consumers:** a network-restricted CI runner that cannot resolve a remote SwiftPM dependency will now go RED on this sensor rather than silently passing — intended fail-closed behavior, not a regression.
+- **Advisory routing engines hardened (two adversarial-verification batches, 28 fixes, every fix mutation-verified).** `recommendSolutionPath` / `recommendUIKitCustomization` precision: UIKit-rejection coverage now spans modal/contracted negators (won't/can't/cannot), intervening verbs ("don't want to use UIKit", "without using UIKit"), and "anything but UIKit" — an explicit rejection routes SDK-first instead of (previously) recommending UIKit; prebuilt idioms are anchored to a UI/social noun; `off-the-shelf` is anchored (so "off-the-shelf analytics" stays SDK-first); localization no longer fires on a programming/design "language"; backend feature capabilities (e.g. livestreaming) surface as a decision rather than a Dynamic-UI default. Advisory-only quality improvements; no gate behavior changes.
+- **Personas split into two integrator postures** (AI-Assisted SDK/Custom-UI Integrator and AI-Assisted UIKit/Prebuilt-UI Adopter), tied to a deterministic behavior contract in the test suite.
+
 ## 1.1.1 — 2026-06-16
 
 Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.

package/README.md

@@ -47,7 +47,7 @@ It turns the request into a grounded plan, records a local contract under `sp-vi
 
 > 🔒 **Your source code never leaves your machine.** Vise fetches only the public social.plus docs and the SDK's published version on npm — never your code, file contents, or search queries. `VISE_DOCS_OFFLINE=1` runs fully offline.
 
-Vise can also run **ahead** of that loop: an advisory [Engagement Intelligence](#engagement-intelligence) layer turns a product goal into a candidate engagement design — *what to build*, not only *whether you built it right*.
+Vise can also run **ahead** of that loop: an advisory [Engagement Intelligence](#engagement-intelligence) layer turns a product goal into multiple candidate engagement strategies — *what you might build*, not only *whether you built it right*.
 
 > **Why "Vise"?** A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Vise clamps the integration to the real docs, the real project structure, and the real compliance rules so the agent can focus on building instead of guessing.
 
@@ -98,12 +98,18 @@ Prefer a per-project install? `npm install -D @amityco/social-plus-vise`, then c
 ## How it works
 
 1. **Inspect** — `vise inspect` detects the platform, app surfaces, available sensors, and design signals from the local repo.
-2. **Plan** — `vise plan --request "..."` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. The agent surfaces them; you answer.
+2. **Plan** — `vise plan --request "..."` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. Use `--summary` when you only need the route/intake readout before implementation. The agent surfaces questions; you answer.
 3. **Initialize** — `vise init` writes the `sp-vise/` compliance contract. While blocking questions are unanswered it refuses, returns `status: "needs-clarification"`, and exits 7 — the agent must ask instead of guessing.
 4. **Build** — the agent edits your code, grounded by `vise search-docs` and `vise get-doc-page`.
 5. **Check & repair** — `vise check` reports deterministic findings, completeness gaps, and attestation needs. The agent fixes findings or records attestations with evidence, looping until green.
 6. **Sense** — `vise run-sensors` runs your project's own typecheck/build/lint/SDK smokes. Done means the contract and evidence are committed, not just that the agent stopped.
 
+### Solution path & UIKit routing (advisory)
+
+Some requests are better served by **social.plus UIKit** (prebuilt social surfaces) than by hand-rolling standard UI directly from SDK primitives. `vise plan` emits an advisory **`solutionPath`** — `sdk`, `uikit`, `hybrid`, or `needs-decision` — so an agent can pause for `--answer solution_path=uikit|sdk|hybrid` before it builds the wrong layer. This separates the two integrator postures cleanly: an **SDK / custom-UI** build (differentiated, direct-SDK) stays SDK-first, a **UIKit / prebuilt-UI** adoption (standard surfaces, fast launch) routes to UIKit, and a genuinely mixed request resolves to `needs-decision` rather than silently picking one. A request that *rejects* UIKit ("don't use UIKit", "we can't use UIKit") routes SDK-first, and a request that names a backend feature capability (e.g. livestreaming) is surfaced as a decision rather than a UIKit-customization default.
+
+When UIKit is in play, `vise plan` can also emit **`uikitCustomization`**, recommending the lowest-effort customization tier that meets the goal — Dynamic UI → Component Styling → Localization → Behavior Overrides → Fork and Extend → SDK Custom UI. Both signals are **advisory only**: they never change outcome classification, compliance rules, the sidecar schema, or `vise check` exit codes.
+
 ### Three validation layers
 
 The layer is set by the *kind of claim*, which is how Vise is designed to avoid false positives where it gates:
@@ -120,9 +126,9 @@ Correctness is gated by deterministic rules or attestations; completeness is gat
 
 ### Engagement Intelligence
 
-**Advisory, in preview.** The three layers above answer *whether you built it right*. Ahead of the build, Vise can also help decide *what to build*: an **Engagement Intelligence** layer turns a product goal into a candidate **engagement design** — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — then compiles the chosen variant into an implementation plan (`vise creative` → `vise creative accept` → `vise experience compile`), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.
+**Advisory, in preview.** The three layers above answer *whether you built it right*. Ahead of the build, Vise can also help reason about *what to build*: an **Engagement Intelligence** layer turns a product goal into multiple candidate **engagement strategies** — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — with rationale, tradeoffs, no-fit guidance, availability boundaries, and review gaps. The human or driving agent still chooses the direction, then Vise compiles that selected variant into an implementation plan (`vise creative` → `vise creative accept` → `vise experience compile`), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.
 
-It is **local-only, never uploads, carries no calibrated score** (a calibration program is in progress), and **never changes `vise check`'s exit codes**. Use it to shape the work; the validation layers still decide when it's done.
+It is **local-only, never uploads, carries no calibrated score**, and **never changes `vise check`'s exit codes**. The opt-in ranking preview is review context, not a top-1 confidence claim or autonomous product-strategy selector. Use it to shape the work; the validation layers still decide when it's done.
 
 ### Design contracts
 
@@ -143,6 +149,8 @@ The mechanism is the durable claim: a checked loop beats the same rules in the p
 
 **Feed completeness (capabilities selected):** when the optional capabilities — image, poll, edit — are selected up front, the Vise arm completed **97–100%** of an 11-item feed checklist across three agents (Cursor/Composer, Claude/Sonnet, Codex/GPT). This is *absolute* completeness from answering Vise's capability questions — **not** a lift over a baseline.
 
+**Engagement Intelligence advisory quality:** a 24-case held-out dogfood set supports the advisory positioning: expected available strategies surfaced in **17/17** cases, multiple strategy options were visible in **20/20** strategy-offer cases, rationale/tradeoff evidence was visible in **24/24**, and no-fit plus availability-gated cases preserved their boundaries. The same run retained **4 ranking-calibration concerns**, so this is **not** a claim of top-1 ranking confidence, autonomous strategy selection, business-outcome lift, or a calibrated score.
+
 **Boundaries:** these are social.plus's own measurements on greenfield work — self-reported, no third-party audit, measured on earlier builds, and not universal claims. Negative results travel with them: no measured advantage on day-2 bug fixing, and the design-conformance arms were measured at different times (the figure is the robust by-name-token signal, not pixel perfection).
 
 <sub>Cursor, Claude, Codex, GitHub Copilot, VS Code, and other product names are trademarks of their respective owners; social.plus is not affiliated with or endorsed by them. Benchmark figures are from social.plus's own measurements.</sub>
@@ -155,21 +163,23 @@ The mechanism is the durable claim: a checked loop beats the same rules in the p
 | **React Native** | ✅ Full | `tsc`, `npm lint`, SDK import smoke |
 | **Flutter / Dart** | ✅ Full | `flutter analyze`, `flutter test` |
 | **Android (Kotlin)** | ✅ Full | Gradle assemble, unit tests |
-| **iOS (Swift)** | ✅ Full | Static rules fully operational (tree-sitter AST for highest-risk rules); build sensor is guarded best-effort — runs only when `xcodebuild` is available, reports environment issues as skipped-with-reason, and still fails on real build errors |
+| **iOS (Swift)** | ✅ Full | Static rules fully operational (tree-sitter AST for highest-risk rules); `Package.swift` enables a SwiftPM manifest sensor, and `.xcodeproj`/`.xcworkspace` enables a guarded `xcodebuild` sensor when available |
 
 Each platform has dozens of rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).
 
 ## CLI Reference
 
-Run `vise <command> --help` for full flags. JSON output is the default for agent-facing commands.
+Run `vise <command> --help` for full flags. JSON output is the default for agent-facing commands; the read commands (`check`, `status`, `plan`, `doctor`, `explain`, `explore`) also accept `--format human` for a readable summary.
 
 ### Inspect, plan, initialize
 
 | Command | Purpose |
 |---|---|
+| `vise explore "<request>"` | Pre-credentials discovery: map a request to what social.plus offers (candidate outcome, capabilities, docs, next command). No project or API key needed |
 | `vise doctor` | Verify install; print version, install path, docs source |
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
-| `vise plan [path] --request "..."` | Grounded implementation plan with intake questions and docs citations |
+| `vise plan [path] --request "..." [--summary]` | Grounded implementation plan with intake questions and docs citations; `--summary` prints a compact route/intake view |
+| `vise plan --summary "..."` | Shortcut for quick routing dogfood or discovery when the current directory is the repo |
 | `vise plan-harness [path] --request "..."` | Pre-planning step: build the harness around the request |
 | `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract once blocking intake is answered; exits 7 (`needs-clarification`) otherwise |
 | `vise workplan next [path] --request "..."` | For broad social requests: print the next uncompleted surface and its focused commands |
@@ -180,7 +190,7 @@ Run `vise <command> --help` for full flags. JSON output is the default for agent
 
 | Command | Purpose |
 |---|---|
-| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Write an advisory Engagement Intelligence brief with candidate solution variants; `--ranking-preview` adds an opt-in, local-only ranking preview that never reorders the default candidates |
+| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Write an advisory Engagement Intelligence brief with multiple candidate solution variants, rationale, tradeoffs, and review gaps; `--ranking-preview` adds opt-in, local-only review context that never reorders the default candidates |
 | `vise creative accept [path] --variant <id>` | Record the selected variant so `plan`/`init`/`workplan` carry it forward; `--variant none --rationale "..."` records a catalog-gap signal instead |
 | `vise ux-harness [path]` | Generate advisory UX expectations from the accepted selection |
 | `vise experience compile [path]` | Compile the accepted variant into an implementation artifact plan |
@@ -189,7 +199,7 @@ Run `vise <command> --help` for full flags. JSON output is the default for agent
 | `vise learning record [path]` | Append a local-only learning event; refreshes the learning summary |
 | `vise learning show [path]` | Read the local learning summary (never changes recommendations) |
 
-Everything in this group is local and advisory: no uploads, no `vise check` exit-code changes, no auto-accepted variants, and no calibrated score until the calibration program graduates one.
+Everything in this group is local and advisory: no uploads, no `vise check` exit-code changes, no auto-accepted variants, no top-1 confidence claim, and no calibrated score.
 
 ### Design contract
 
@@ -216,6 +226,8 @@ Everything in this group is local and advisory: no uploads, no `vise check` exit
 |---|---|
 | `vise check [path]` | Re-validate against the recorded contract: `green`, `needs-attestation`, `deterministic-failures`, `blocked`, or `contract-drift` |
 | `vise check [path] --ci` | Read-only variant that exits non-zero unless green (for CI) |
+| `vise check [path] --new-only` | **Brownfield gate.** With a recorded baseline, gate only on findings introduced *since* the baseline (pre-existing ones are reported but excluded). Default `check` always gates on everything |
+| `vise baseline [path]` | Snapshot the current pre-existing findings to `sp-vise/baseline.json` so `check --new-only` can separate legacy debt from new gaps. `vise init --baseline` records it at init time |
 | `vise validate [path]` | Run the deterministic validators only (no attestation comparison) |
 | `vise sync [path]` | Persist deterministic-pass evidence to `sp-vise/attestations/` |
 | `vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..."` | Record an attestation when a rule passes through architecture the deterministic check can't see |
@@ -299,7 +311,7 @@ Vise writes local planning, compliance, design, and evidence artifacts under `sp
 | `sp-vise/inspection.json` | `vise init` | Platform, surface, and design signals detected at init |
 | `sp-vise/attestations/*.json` | `vise sync` / `vise attest` | Per-rule evidence: signer, confidence, rationale, source fingerprints for drift detection |
 | `sp-vise/creative-brief.json` + `creative-brief.md` | `vise creative` | Advisory brief: goals, archetypes, candidate variants (JSON + human-readable) |
-| `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local ranking preview; `experience_score: null`, no uploads, no default-order change |
+| `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local ranking preview for review context; `experience_score: null`, no uploads, no default-order change, no top-1 confidence claim |
 | `sp-vise/creative-selection.json` | `vise creative accept` | Accepted variant and plan/workplan feed-forward context |
 | `sp-vise/catalog-gap.json` | `vise creative accept --variant none` | Local-only no-fit signal for human catalog review |
 | `sp-vise/ux-harness.json` | `vise creative accept` or `vise ux-harness` | Advisory UX pattern expectations and anti-patterns |

package/dist/capabilities.js

@@ -1256,6 +1256,7 @@ export function assessSelectedOptionalCapabilities(source, outcome, selectedIds
         note: "Selected optional capabilities are enforced only after the user or host agent opts in through `feed_optional_capabilities`. They are source sensors, not baseline compliance rules.",
     };
 }
+const MIN_SCOPE_OMIT_REASON_CHARS = 8;
 export function assessCompleteness(source, outcome) {
     const caps = baselineCapabilities(outcome);
     const optOuts = new Map();
@@ -1265,12 +1266,14 @@ export function assessCompleteness(source, outcome) {
     while ((match = omitPattern.exec(source)) !== null) {
         const id = match[1].toLowerCase();
         const reason = (match[2] ?? "").trim();
-        if (reason) {
+        if (reason.length >= MIN_SCOPE_OMIT_REASON_CHARS) {
             optOuts.set(id, reason);
             invalidOptOuts.delete(id);
         }
         else if (!optOuts.has(id)) {
-            invalidOptOuts.set(id, "scope-omit marker must include a reason");
+            invalidOptOuts.set(id, reason.length === 0
+                ? "scope-omit marker must include a reason"
+                : `scope-omit reason is too short ("${reason}") — give an auditable reason of at least ${MIN_SCOPE_OMIT_REASON_CHARS} characters`);
         }
     }
     const present = [];
@@ -1292,7 +1295,7 @@ export function assessCompleteness(source, outcome) {
             missing.push({
                 id: cap.id,
                 label: cap.label,
-                hint: invalidReason ? `${cap.hint}; found scope-omit marker without a reason, so add a reason or implement it` : cap.hint,
+                hint: invalidReason ? `${cap.hint}; ${invalidReason}` : cap.hint,
             });
         }
     }

package/dist/explore.js

@@ -0,0 +1,51 @@
+import { capabilityChecklist } from "./capabilities.js";
+import { classifyOutcome, getOutcomeDefinition } from "./outcomes.js";
+const DISCOVERY_MENU = [
+    "setup-sdk",
+    "add-feed",
+    "add-comments",
+    "add-chat",
+    "add-community",
+    "add-follow",
+    "add-moderation",
+    "add-notifications",
+    "setup-push",
+    "setup-live-data",
+];
+function outcomeBrief(outcome, platform, request) {
+    const def = getOutcomeDefinition(outcome);
+    return {
+        outcome,
+        summary: def.interpretation,
+        capabilities: capabilityChecklist(outcome).map((capability) => ({ id: capability.id, label: capability.label })),
+        docs: def.docs(platform).slice(0, 4).map((doc) => ({ path: doc.path, reason: doc.reason })),
+        start: `vise plan . --request ${JSON.stringify(request)}`,
+    };
+}
+export function exploreRequest(request, platform = "typescript") {
+    const matched = classifyOutcome(request);
+    const isKnown = matched !== "unknown" && DISCOVERY_MENU.includes(matched);
+    if (isKnown) {
+        return {
+            kind: "exploration",
+            request,
+            platform,
+            matched_outcome: matched,
+            routes: [outcomeBrief(matched, platform, request)],
+            also_available: DISCOVERY_MENU.filter((outcome) => outcome !== matched).map((outcome) => ({
+                outcome,
+                summary: getOutcomeDefinition(outcome).interpretation,
+            })),
+            note: "Discovery is pre-credentials and read-only — no project or API key needed. When you're ready to build, `vise plan`/`vise init` starts a tracked integration.",
+        };
+    }
+    return {
+        kind: "exploration",
+        request,
+        platform,
+        matched_outcome: null,
+        unmatched_note: "This request didn't map to a single social.plus outcome. Below is everything Vise can guide you through — pick one and run its `start` command.",
+        routes: DISCOVERY_MENU.map((outcome) => outcomeBrief(outcome, platform, request)),
+        note: "Discovery is pre-credentials and read-only — no project or API key needed. When you're ready to build, `vise plan`/`vise init` starts a tracked integration.",
+    };
+}

package/dist/humanFormat.js

@@ -0,0 +1,226 @@
+const STATUS_GLOSS = {
+    green: "All applicable rules pass.",
+    "needs-attestation": "Some rules need a host-agent or human attestation before they can pass.",
+    "deterministic-failures": "A deterministic sensor found a violation in the source.",
+    blocked: "An external prerequisite the customer must provide is missing.",
+    "contract-drift": "The recorded ruleset no longer matches the installed Vise — re-run init.",
+    "completeness-gap": "Required capabilities are neither built nor opted out (scope-omit) yet.",
+    "selected-capability-failures": "A selected optional capability's sensor failed.",
+    "needs-clarification": "Blocking intake questions are unresolved.",
+};
+function asString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function asArray(value) {
+    return Array.isArray(value) ? value : [];
+}
+function bullet(lines, indent = "  ") {
+    return lines.map((line) => `${indent}- ${line}`).join("\n");
+}
+function renderCompliance(payload) {
+    const status = asString(payload.status) ?? "unknown";
+    const exitCode = typeof payload.exitCode === "number" ? payload.exitCode : undefined;
+    const outcome = asString(payload.outcome);
+    const surface = asString(payload.surfacePath);
+    const out = [];
+    const head = `social.plus compliance: ${status.toUpperCase()}${exitCode !== undefined ? ` (exit ${exitCode})` : ""}`;
+    const scope = [outcome ? `outcome: ${outcome}` : null, surface ? `surface: ${surface}` : null].filter(Boolean).join(", ");
+    out.push(scope ? `${head} — ${scope}` : head);
+    if (STATUS_GLOSS[status])
+        out.push(STATUS_GLOSS[status]);
+    const summary = payload.summary;
+    if (summary && Object.keys(summary).length > 0) {
+        const parts = Object.entries(summary).map(([key, count]) => `${count} ${key}`);
+        out.push("", `Rules: ${parts.join(", ")}`);
+    }
+    const basisNote = asString(payload.evidence_basis_note);
+    if (basisNote)
+        out.push(`Evidence: ${basisNote}`);
+    const blocking = asArray(payload.rules)
+        .filter((r) => typeof r === "object" && r !== null)
+        .filter((r) => {
+        const s = asString(r.status);
+        return s !== undefined && s !== "deterministic-pass" && s !== "attested" && s !== "advisory";
+    });
+    if (blocking.length > 0) {
+        out.push("", "Needs action:");
+        out.push(bullet(blocking.slice(0, 20).map((r) => {
+            const id = asString(r.ruleId) ?? asString(r.contractRuleId) ?? "(rule)";
+            const reason = asString(r.reason) ?? asString(r.status) ?? "";
+            return reason ? `${id} [${asString(r.status)}]: ${reason}` : `${id} [${asString(r.status)}]`;
+        })));
+        if (blocking.length > 20)
+            out.push(`  …and ${blocking.length - 20} more`);
+    }
+    const completeness = payload.completeness;
+    const missing = asArray(completeness?.missing).filter((m) => typeof m === "object" && m !== null);
+    if (missing.length > 0) {
+        out.push("", "Missing capabilities (build, or `// vise: scope-omit <id> — <reason>`):");
+        out.push(bullet(missing.map((m) => `${asString(m.id) ?? "(capability)"}: ${asString(m.hint) ?? asString(m.label) ?? ""}`.trim())));
+    }
+    const next = asString(payload.nextStep);
+    if (next)
+        out.push("", `Next: ${next}`);
+    return out.join("\n");
+}
+function renderPlan(payload) {
+    const out = [];
+    const outcome = asString(payload.outcome) ?? "(unrouted)";
+    const platform = asString(payload.platform);
+    out.push(`Plan: ${outcome}${platform ? ` — ${platform}` : ""}`);
+    const sp = payload.solutionPath;
+    if (sp) {
+        const rec = asString(sp.recommendation);
+        const conf = asString(sp.confidence);
+        const summary = asString(sp.summary);
+        out.push(`Solution path: ${rec ?? "(n/a)"}${conf ? ` (${conf})` : ""}${summary ? ` — ${summary}` : ""}`);
+    }
+    const uikit = payload.uikitCustomization;
+    if (uikit) {
+        out.push(`UIKit customization: ${asString(uikit.recommendedLevel) ?? "(n/a)"} (${asString(uikit.status) ?? "n/a"})`);
+    }
+    const decisions = asArray(payload.decisionsRequired);
+    if (decisions.length > 0) {
+        out.push("", "Decisions required:");
+        out.push(bullet(decisions.map((d) => (typeof d === "string" ? d : asString(d.question) ?? JSON.stringify(d)))));
+    }
+    const steps = asArray(payload.implementationSteps);
+    if (steps.length > 0) {
+        out.push("", "Build steps:");
+        out.push(steps
+            .slice(0, 30)
+            .map((s, i) => `  ${i + 1}. ${typeof s === "string" ? s : asString(s.step) ?? asString(s.description) ?? JSON.stringify(s)}`)
+            .join("\n"));
+    }
+    const inputs = asArray(payload.requiredInputs).filter((i) => typeof i === "string");
+    if (inputs.length > 0) {
+        out.push("", "Required inputs:");
+        out.push(bullet(inputs));
+    }
+    const intake = payload.intake;
+    const questions = asArray(intake?.questions).filter((q) => typeof q === "object" && q !== null);
+    const blockingQs = questions.filter((q) => q.blocksImplementationWhenMissing === true);
+    if (blockingQs.length > 0) {
+        out.push("", "Open intake (blocking):");
+        out.push(bullet(blockingQs.map((q) => `${asString(q.id) ?? "?"}: ${asString(q.prompt) ?? asString(q.question) ?? ""}`.trim())));
+    }
+    const next = asString(payload.nextStep);
+    if (next)
+        out.push("", `Next: ${next}`);
+    return out.join("\n");
+}
+function renderDoctor(payload) {
+    const out = [];
+    out.push(`${asString(payload.package) ?? "vise"} ${asString(payload.version) ?? ""} — ${asString(payload.status) ?? "?"}`.trim());
+    if (payload.node)
+        out.push(`node: ${asString(payload.node)} (requires ${asString(payload.requiredNodeMajor) ?? "?"})`);
+    out.push(`docs: ${asString(payload.docsSource) ?? "?"}${payload.docsRoot ? ` (${asString(payload.docsRoot)})` : ""}`);
+    if (payload.transport)
+        out.push(`transport: ${asString(payload.transport)}`);
+    const tools = asArray(payload.tools);
+    if (tools.length > 0)
+        out.push(`tools: ${tools.length} registered`);
+    const support = asString(payload.support);
+    if (support)
+        out.push(`support: ${support}`);
+    return out.join("\n");
+}
+function renderExplain(payload) {
+    if (payload.kind === "rule-index") {
+        const out = [`${payload.count} compliance rules. Run \`vise explain <id>\` for the full rule.`, ""];
+        for (const entry of asArray(payload.rules).filter((e) => typeof e === "object" && e !== null)) {
+            const id = asString(entry.id) ?? "(rule)";
+            const sev = asString(entry.severity);
+            const outcomes = asArray(entry.outcomes).join(", ");
+            out.push(`  ${id}${sev ? `  (${sev})` : ""}${outcomes ? `  — ${outcomes}` : ""}`);
+        }
+        return out.join("\n");
+    }
+    if (payload.kind === "product_expectation") {
+        const out = [`${asString(payload.id) ?? "(rule)"} — validated by ${asArray(payload.contract_rules).length} contract rule(s):`];
+        for (const c of asArray(payload.contract_rules).filter((e) => typeof e === "object" && e !== null)) {
+            out.push(`  ${asString(c.contract_rule_id) ?? "?"} — ${asString(c.title) ?? ""}`.trimEnd());
+        }
+        return out.join("\n");
+    }
+    const out = [];
+    const id = asString(payload.id) ?? "(rule)";
+    const contractId = asString(payload.contract_rule_id);
+    const title = asString(payload.title);
+    const sev = asString(payload.severity);
+    const version = payload.version;
+    out.push(`${id}${contractId ? ` (${contractId})` : ""}${title ? ` — ${title}` : ""}${sev ? `  [${sev}${version !== undefined ? `, v${version}` : ""}]` : ""}`);
+    const rationale = asString(payload.rationale);
+    if (rationale)
+        out.push(rationale);
+    const applies = payload.applies_when;
+    if (applies) {
+        const o = asArray(applies.outcomes).join(", ");
+        const p = asArray(applies.platforms).join(", ");
+        const parts = [o ? `outcomes: ${o}` : null, p ? `platforms: ${p}` : null].filter(Boolean).join("; ");
+        if (parts)
+            out.push(`Applies — ${parts}`);
+    }
+    const feedforward = asString(payload.feedforward);
+    if (feedforward)
+        out.push(`Feedforward: ${feedforward}`);
+    const symptoms = asArray(payload.symptoms).filter((s) => typeof s === "string");
+    if (symptoms.length > 0)
+        out.push(`Symptoms: ${symptoms.join(" | ")}`);
+    const attestation = payload.attestation;
+    if (attestation)
+        out.push(`Attestation: ${attestation.allowed ? "allowed" : "not allowed"}${attestation.host_agent_min_confidence ? ` (host-agent min ${asString(attestation.host_agent_min_confidence)})` : ""}`);
+    const digest = asString(payload.rule_digest);
+    if (digest)
+        out.push(`digest: ${digest}`);
+    return out.join("\n");
+}
+function renderExplore(payload) {
+    const out = [];
+    const request = asString(payload.request) ?? "";
+    const matched = asString(payload.matched_outcome);
+    out.push(matched
+        ? `social.plus — best match for "${request}": ${matched}`
+        : `social.plus — what you can build (no single match for "${request}"):`);
+    for (const route of asArray(payload.routes).filter((r) => typeof r === "object" && r !== null)) {
+        out.push("", `▸ ${asString(route.outcome) ?? "(outcome)"} — ${asString(route.summary) ?? ""}`.trimEnd());
+        const caps = asArray(route.capabilities).filter((c) => typeof c === "object" && c !== null);
+        if (caps.length > 0)
+            out.push(`    capabilities: ${caps.map((c) => asString(c.id)).filter(Boolean).join(", ")}`);
+        const start = asString(route.start);
+        if (start)
+            out.push(`    start: ${start}`);
+    }
+    const also = asArray(payload.also_available).filter((a) => typeof a === "object" && a !== null);
+    if (also.length > 0) {
+        out.push("", "Also available:");
+        out.push(bullet(also.map((a) => `${asString(a.outcome) ?? "?"} — ${asString(a.summary) ?? ""}`.trimEnd())));
+    }
+    const note = asString(payload.note);
+    if (note)
+        out.push("", note);
+    return out.join("\n");
+}
+const RENDERERS = {
+    check: renderCompliance,
+    status: renderCompliance,
+    plan: renderPlan,
+    doctor: renderDoctor,
+    explain: renderExplain,
+    explore: renderExplore,
+};
+export function wantsHumanFormat(format) {
+    return format === "human";
+}
+export function renderHuman(command, payload) {
+    const renderer = RENDERERS[command];
+    if (!renderer || typeof payload !== "object" || payload === null) {
+        return null;
+    }
+    try {
+        return renderer(payload);
+    }
+    catch {
+        return null;
+    }
+}

package/dist/outcomes.js

@@ -42,20 +42,21 @@ const CHAT_PATTERNS = [
 ];
 const COMMUNITY_PATTERNS = [
     /\b(create|creating|build|building|manage|managing|join|joining|leave|leaving|set ?up)\s+(a\s+|the\s+)?communit/,
-    /\bcommunit\w*\s+(member|membership|role|invit|categor|setting|management|directory|discovery)/,
+    /\bcommunit\w*\s+(member|membership|role|invit|categor|setting|management|directory|discovery|profile|page)/,
     /\bcommunity\s+(creation|management|members?|roles?|invitations?|categories|settings|moderation)\b/,
 ];
 const FOLLOW_PATTERNS = [
     /\b(follow|unfollow|follower|followers|following)\b/,
     /\b(social graph|user relationship|follow request|followers? list|following list)\b/,
+    /\b(?:user'?s?|member|account|my|your|their)\s+profile\b|\buser_profile_page\b/,
     /\bblocked\s+users?\b/,
     /\bmanage\s+blocked\b/,
     /\bblock\s*list\b/,
     /\bunblock\b/,
 ];
 const NOTIFICATION_PATTERNS = [
-    /\b(notification tray|notification cent(?:er|re)|in-?app notification)/,
-    /\bnotification (?:setting|preference)/,
+    /\b(notifications?\s+tray|notifications?\s+cent(?:er|re)|in-?app notifications?)/,
+    /\bnotifications?\s+(?:setting|preference)/,
 ];
 const TROUBLESHOOT_PATTERNS = [/\b(error|broken|crash|not working|fail|timeout|401|403)\b/];
 const VALIDATE_PATTERNS = [/\b(validate|check|correct|setup right|initiali[sz])\b/];
@@ -212,7 +213,7 @@ export function liveDataPlatformPath(platform) {
 const setupSdk = {
     id: "setup-sdk",
     patterns: SETUP_PATTERNS,
-    interpretation: "Implement setup-sdk.",
+    interpretation: "Set up the social.plus SDK — client creation with the correct region/endpoint, secure session login, and access-token renewal — the foundation every other social.plus feature builds on.",
     docsQuery: (platform) => `${platform} quick start setup`,
     docs: (platform) => [
         platformQuickStart(platform),
@@ -489,8 +490,8 @@ const addFeed = {
     docsQuery: (platform) => `${platform} social feed posts`,
     docs: (platform) => [
         {
-            path: "social-plus-sdk/social/posts",
-            reason: "Canonical social post/feed concepts and API entrypoint.",
+            path: "social-plus-sdk/social/content-management/posts/creation/text-post",
+            reason: "Canonical post model and creation API entrypoint; pair with the live-objects/collections docs below for feed querying.",
         },
         {
             path: "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview",
@@ -601,7 +602,7 @@ const addFeed = {
             {
                 step: "Fetch the canonical social/feed docs and use platform-appropriate live collection patterns.",
                 evidence: [
-                    "social-plus-sdk/social/posts",
+                    "social-plus-sdk/social/content-management/posts/creation/text-post",
                     "social-plus-sdk/core-concepts/realtime-communication/live-objects-collections/overview",
                 ],
             },
@@ -633,11 +634,11 @@ const addFeed = {
             { step: "Implement loading, empty, error, and data states.", evidence: ["implementationRules.file-specific edits"] },
             {
                 step: "In post card renderers, resolve each media type from the parent post OR its childrenPosts — in a feed the parent is usually dataType 'text' and the image/video/poll/clip/room rides on a child post. Handle at minimum: text, image, video, file, poll, clip, room. Do not render placeholder labels like '[Image post]' or '[Poll post]'; read the SDK data/accessors and render the actual content. Do NOT gate media on the parent's dataType alone (e.g. post.dataType === 'poll') — that never matches a text parent and the content silently never renders. When rendering the text body itself (post or comment), apply @mention highlights if metadata carries mention entries ({ type: 'user', index, length, userId }, length excluding the '@'): wrap each [index, index + length + 1] span in a styled element and resolve userId to a display name, rather than printing raw text. Pass mentionees on create so mentioned users are notified.",
-                evidence: ["social-plus-sdk/social/posts", "intake.feed_post_type_scope", "capabilityAvailability.available"],
+                evidence: ["social-plus-sdk/social/content-management/posts/creation/text-post", "intake.feed_post_type_scope", "capabilityAvailability.available"],
             },
             {
                 step: "Read SDK objects through their own typed accessors and types (e.g. post.getImageInfo(), the Amity.* types) instead of casting return values to hand-written shapes like (post.data as { text?: string }). A hand-written cast silences the type-checker, so when an SDK upgrade renames a field your build still compiles and the bug only surfaces at runtime — reading through SDK types lets tsc/analyze flag the breakage.",
-                evidence: ["social-plus-sdk/social/posts"],
+                evidence: ["social-plus-sdk/social/content-management/posts/creation/text-post"],
             },
             {
                 step: "For community and user avatars, use the SDK-provided URL (community.avatar?.fileUrl / community.avatarImage?.getUrl / community.getAvatar()?.getUrl) and fall back to an initial only when the field is absent. Do not derive an initial from the display name as the sole identifier.",
@@ -671,12 +672,12 @@ const addFeed = {
                 step: "If the post composer supports poll creation, implement the two-step creation chain: (1) create the poll with the platform SDK poll repository — returns a Poll/pollId; (2) link that poll into a post with the platform post builder, for example `PostRepository.createPost({ targetType, targetId, data: { text: '', pollId } })` on TypeScript/React Native or Android's dedicated `createPollPost(targetType, targetId, pollId, text, ...)` API. Rendering poll answers (votePoll/unvotePoll) is the read-side; without both creation steps the poll composer silently does nothing. Offer a dedicated poll-builder UI (question input + dynamic answer list) so users can author polls inline.",
                 evidence: [
                     "social-plus-sdk/social/content-management/posts/creation/poll-post",
-                    "social-plus-sdk/social/posts",
+                    "social-plus-sdk/social/content-management/posts/creation/text-post",
                 ],
             },
             {
                 step: "In post card headers, show the post's target context when post.targetType === 'community': display 'Author.displayName › Community.displayName' by subscribing to CommunityRepository.getCommunity(post.targetId, cb) for the live community name.",
-                evidence: ["social-plus-sdk/social/communities", "social-plus-sdk/social/posts"],
+                evidence: ["social-plus-sdk/social/communities", "social-plus-sdk/social/content-management/posts/creation/text-post"],
             },
             {
                 step: "For room-type posts, subscribe to RoomRepository.getRoom(roomId, cb) to get the Room object and display room.title (not room.roomId). Show room.status (live/idle/ended) as a badge.",
@@ -684,7 +685,7 @@ const addFeed = {
             },
             {
                 step: "Give each post card an actions menu gated by the viewer's relationship to the post. If the viewer is the author (post.postedUserId === currentUserId), show edit (PostRepository.editPost) and delete (PostRepository.deletePost). For posts the viewer does not own, show report/flag (PostRepository.flagPost). Author-ownership actions and moderator-role actions are distinct — do not show edit/delete to non-authors.",
-                evidence: ["social-plus-sdk/social/posts", "social-plus-sdk/social/moderation"],
+                evidence: ["social-plus-sdk/social/content-management/posts/creation/text-post", "social-plus-sdk/social/moderation"],
             },
             { step: "Run validate_setup and detected command sensors after edits.", evidence: ["validate_setup", "run_sensors"] },
         ];
@@ -891,7 +892,7 @@ const addModeration = {
         const questions = [
             {
                 id: "moderation_target",
-                question: "What content types need moderation (post, comment, message, user)?",
+                question: "What content types need moderation (posts, comments, messages, users, or all)?",
                 why: "Each content type has different moderation APIs and UI patterns.",
                 required: true,
                 blocksImplementationWhenMissing: true,
@@ -922,7 +923,7 @@ const addModeration = {
         return filterAnswered(ctx.answers, questions);
     },
     requiredInputs: () => [
-        "moderation target types: post, comment, message, user",
+        "moderation target types: posts, comments, messages, users, or all",
         "moderation action set: report, block, mute, hide, admin queue",
         "post-action rendering policy for blocked/hidden content",
     ],