@amityco/social-plus-vise 1.2.0 → 1.3.0

package/CHANGELOG.md

@@ -4,6 +4,36 @@ 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.

package/README.md

@@ -169,12 +169,13 @@ Each platform has dozens of rules across 10 compliance domains (feed, comments,
 
 ## 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 "..." [--summary]` | Grounded implementation plan with intake questions and docs citations; `--summary` prints a compact route/intake view |
@@ -225,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 |

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",
     ],