@amityco/social-plus-vise 1.0.1 → 1.1.1

package/CHANGELOG.md

@@ -4,6 +4,50 @@ 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.1.1 — 2026-06-16
+
+Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
+
+### Changed
+- **README Evidence section reworked.** Dropped the pre-1.0 "like-for-like" feed-completeness result (it was measured against an earlier dev build on early-June agent versions); presented the two genuine matched comparisons (SDK compliance, design conformance) as a scannable table; relabeled the former "best case" as **"Feed completeness (capabilities selected)"** and reframed it as *absolute* opt-in completeness rather than a baseline-beating lift; led design conformance with the robust by-name-token signal instead of the fragile one-seed hex anecdote (and dropped the model attribution, given a cross-temporal confound now noted under Boundaries); tightened the limitations and lifted the "stopping condition" framing into the section intro. No benchmark numbers were invented; the SDK-compliance benchmark stays described generically (its internal codename remains denylisted from the shipped surface).
+
+## 1.1.0 — 2026-06-16
+
+Public GA-readiness pass. No change to `vise check` exit codes or sidecar **formats**. The rule corpus gains three corrected rationales (stale/fictional SDK method names) — a deliberate pre-GA contract reset, with the `test:sidecar-compat` baseline re-frozen accordingly (no published 0.14.x consumers to protect; see below).
+
+### Added
+- **Stories rule family (`*.story.live-collection`, all 5 platforms).** Story trays are Live Collections; a one-shot story query renders a tray that never updates as stories are created, viewed, or expire. The new `validateStories` detector flags this exactly like the feed `live-collection.api-mismatch` rule — presence-gated, with the documented TS/RN `getActiveStoriesByTarget(params, callback)` live form (plus iOS `.observe`, Android `PagingData`, Flutter `StreamBuilder`) recognized as reactive. A story-feature request now routes to `setup-live-data`, and the rule's `applies_when` spans the feed/comments/chat/live-data outcomes so coverage fires regardless of routing. Closes the highest-ranked zero-rule gap in `docs/SDK_COVERAGE_AUDIT.md`. Adding a new rule does **not** affect existing sidecars (`vise check` evaluates the rules recorded in `sp-vise/compliance.json`, not the full installed corpus, so the frozen `test:sidecar-compat` baseline reads unchanged).
+- **Search rule family (`*.search.live-collection`, all 5 platforms).** Search results (`searchCommunities`/`searchUsers`/`searchUserByDisplayName`/`searchPostsByHashtag`/`semanticSearch*`) are paginated Live Collections — a one-shot search renders only the first page and never updates. `validateSearch` recognizes the TS/RN `searchX({...}, callback)` live form, iOS `.observe`, Android `PagingData`, and Flutter's `PagingController`/`getPagingData` as reactive. A pure search request routes to `setup-live-data`; a search named alongside a surface routes to that surface (the rule's `applies_when` spans them so coverage still fires). `searchMembers` is left to the existing membership rule.
+- **Notification-tray rule family (`*.notification-tray.live-collection`, 4 platforms).** The notification tray (`getNotificationTrayItems`) is a Live Collection — a one-shot tray never updates as notifications arrive. `validateNotificationTray` flags the one-shot form (TS/RN `getNotificationTrayItems({...}, callback)` live form, iOS `.observe`, Android `PagingData` recognized as reactive); reachable via the existing `add-notifications` routing. Flutter is intentionally uncovered (the Flutter SDK does not expose the tray API).
+- **SDK-surface coverage gate (`test:sdk-coverage`).** `test/coverage-manifest.json` freezes, per area, which platforms ship a rule and whether a completeness capability exists; `test/run-sdk-coverage-gate.mjs` recomputes those two booleans from `rules/*.yaml` rule-ids and `CAPABILITIES` and fails on drift (a covered cell regressing, or a new rule/capability landing unclassified). It never recomputes SDK-surface presence or counts (the curated audit signals), so it stays silent on known gaps and speaks only when Vise-side coverage moves — the guard deferred in `run-capability-consistency.mjs` and quantified in the coverage audit.
+- **Community-membership rule ported to all 5 platforms.** A member list rendered from a one-shot snapshot never updates as people join/leave/change role. Was RN-only (a `searchMembers`-one-shot-Promise premise that doesn't exist on native); the new `validateMembershipList` detector ports the live-collection check to typescript/android/ios/flutter (`*.membership.use-live-collection`); the RN rule is unchanged.
+- **Events rule (`*.event.live-collection`, ts/android/ios).** Event calendars (`getEvents`) and attendee/RSVP lists (`getRSVPs`) are Live Collections; a one-shot render goes stale as people RSVP. Read/list APIs only (never the `createRSVP` mutation). A narrow `EVENT_REGEX` routes event requests to `setup-live-data`. No Flutter event API; RN excluded per the feature matrix.
+- **User-blocking rule (`*.blocked-users.live-collection`, all 5 platforms).** A "Manage Blocked Users" screen built from a one-shot `getBlockedUsers` does not refresh when the user taps unblock. Triggers on `getBlockedUsers` only (not the sanctioned one-shot `getAllBlockedUsers` feed-filter); blocked-users/unblock alts added to the follow router.
+- **Polls rule (`*.poll.vote-status-guard`, all 5 platforms).** A poll renderer that wires a vote action for each answer but never reads poll status / voted-state / vote counts lets the user vote on a closed poll, re-vote, and see no results. A novel co-occurrence detector (vote action + answer rendering + no guard symbol).
+- **Follow-relationships rule ported to ts/rn/android/ios.** `getFollowInfo` read once never reflects follow/unfollow. The follow detector is now cross-platform (per-platform live markers: TS/RN callback, iOS trailing-closure `.observe`, Android `doOnNext`/`.subscribe()`); Flutter is excluded (its `getFollowInfo` is a one-shot Future, so the premise is false there).
+- **Notification-tray observer-leak.** `live.cleanup` now also catches a leaked tray observer — a `getNotificationTrayItems({...}, callback)` subscription whose unsubscriber is never disposed (callback-form only, so it does not double-flag the one-shot tray).
+- **Invitations rule (`*.invitation.live-collection`, ts/rn/android/ios).** Community invitation lists are Live Collections (`getMyCommunityInvitations` → `Amity.InvitationLiveCollection` / `AmityCollection<AmityInvitation>` / `Flowable<PagingData>`); a one-shot render never refreshes as invitations arrive or transition pending→accepted/rejected/cancelled. The new `validateInvitations` detector triggers ONLY on the list observers (`getMyCommunityInvitations`, plus `getMemberInvitations` on android/ios) — never the singular `getInvitation()` status check — with the TS/RN `getMyCommunityInvitations(params, callback)` live form (mutation-verified load-bearing), iOS `.observe`, and Android `PagingData` recognized as reactive. Reachable via add-community. No Flutter rule (no invitation SDK API there). Brand-new rule id — no sidecar re-baseline.
+- **Deprecation warnings for sun-setting chat APIs (`*.chat.deprecated-marker-sync` ts/rn/android/ios, `*.chat.deprecated-subchannel` all 5).** The MarkerSyncEngine receipt-sync API (`startMessageReceiptSync`/`stopMessageReceiptSync`) and manual sub-channel CRUD (`createSubChannel`/`updateSubChannel`/`deleteSubChannel`/`AmitySubChannelQuery`) are being sun-set; the detectors warn on their use and point to the supported replacements — the channel unread count (`channel.unreadCount` / `getTotalChannelUnread`) + `markRead()`, and the channel's default sub-channel (`channel.defaultSubChannelId`). Anchored on the deprecated symbols ONLY — never the valid neighbours that share a prefix (`unreadCount`/`getSubChannelsUnreadCount`/`defaultSubChannelId`/the shared `AmitySubChannelRepository`), verified by no-FP control fixtures. Attestable warnings with a `// vise: <name> intentional` escape hatch.
+- **Live-streaming deprecation (`*.livestream.deprecated-stream`, ts/rn/android/ios).** The legacy **Stream** API (`StreamRepository`/`getStreamById`/`AmityStreamRepository`/`createLiveStreamPost`) is deprecated in favour of the **Room**-based system; the detector warns and points to the Room API (`RoomRepository`/`getRoom`/`createRoomPost`). Anchored on the Amity-qualified legacy symbols only — never bare `getStream` (a substring of Flutter's `getStreamController`) and never the Room replacement. A new narrow `LIVESTREAM_REGEX` routes livestream requests to `setup-live-data`; `applies_when` spans `add-feed`/`setup-live-data`/`validate-setup`. No Flutter rule (no Room API in the Flutter surface yet). The skill gains positive Room guidance (per-platform `getRoom` → observe + dispose, all four `idle/live/ended/recorded` states, `createRoomPost`).
+
+The Batch 2 follow-port + notif-tray entries edit existing rules' `applies_when`/`platforms`, which changes their `rule_digest` — so the `test:sidecar-compat` 1.1.0 fixture was re-baselined accordingly (44→49 rules; pre-GA, no published consumers to protect, same basis as the original 1.1.0 reset). **Deferred (no rule — grounded + adversarially verified):** **categories** (docs explicitly recommend caching category lists, and categories are Console-only with no app-side mutation, so a live-collection rule would false-fire on the sanctioned cached fetch); **live-rooms-presence** (presence is one-shot by design with prescribed ~30s polling). Live-streaming's status-completeness *feature* rule stays deferred for the same false-positive reasons (TS's own documented flow is a one-shot `getRoom` read), but the legacy-Stream→Room **deprecation** shipped this release (see Added). All documented in `docs/SDK_COVERAGE_AUDIT.md`.
+
+### Changed
+- **Rule rationales corrected to real SDK APIs.** Three rules named SDK methods that do not exist or mischaracterized live ones, and `vise explain` surfaced them verbatim: `react-native.follow.status-subscription` (`getFollowStatus` → the real live observer **`getFollowInfo`**), the `image-post.child-resolution-awaited` family (`observePost` → **`getPost`**), and `react-native.membership.use-live-collection` (dropped the false "`searchMembers` is a one-shot Promise" premise — `searchMembers` is itself a LiveCollection; the detector now flags only the genuine no-callback one-shot form). The follow and membership detectors were re-keyed to match, so they fire on real SDK code instead of the fictional names. Because a rule's `rationale`/`title` is part of its `rule_digest`, this is an intentional contract change: the `test:sidecar-compat` baseline was re-frozen from the local 1.1.0 build (the pre-GA 0.14.26/27/28 corpus had no published consumers, so backward-read to it is explicitly not promised). An existing 0.14.x sidecar would correctly report `contract-drift` — the signal to re-run `vise init`; recorded attestations still grandfather.
+- **Public support paths now resolve.** `package.json` `homepage`/`bugs` point to public destinations (learn.social.plus + support@social.plus) instead of the private source repo; the README Support section leads with the public channel. Existing customers can still reach their account team.
+- **README & licensing for prospects.** The README adds a "New to social.plus?" on-ramp (Console signup + SDK getting-started), and the LICENSE now grants a standalone right to install and **evaluate** the tool — not only to integrate as an existing customer.
+- **Evidence section made like-for-like.** The feed benchmark now leads with the matched, pre-registered "roughly doubled" result and labels the 97–100% figures as an explicit opt-in best case (with version/grading caveats); the false-positive claim is restated as "designed to avoid false positives"; a trademark / non-affiliation note was added. The "source code never leaves your machine" line now states exactly what egresses (public docs + npm version check only).
+- **`vise blocks` framed as preview.** The bundled skill marks installable blocks as a preview capability that requires a registry, and drops the unverified "≈9× faster" figure.
+- **Stopped recommending the sun-setting chat APIs.** The read-state capability no longer lists `startMessageReceiptSync` as a detection symbol; the add-chat plan step and the skill now prescribe the channel unread count + `markRead()` and the auto-managed default sub-channel (`channel.defaultSubChannelId`) instead of receipt sync / manual sub-channel management. `docs/SDK_COVERAGE_AUDIT.md`'s "add sub-channel coverage" recommendation is reversed accordingly.
+- **Positioning & README polish.** The README sharpens the two strongest, customer-safe claims (refuses to invent SDK symbols/fields; gating rules are mutation-verified — a check that can't fail is removed rather than shipped as theater), and adds a contents bar + a scannable intro. No exit-code, sidecar, or claim-substance changes.
+- **Internal benchmark codenames scrubbed from shipped artifacts** (README + CHANGELOG) and added to the `test:tarball-hygiene` denylist so they can't recur in the public tarball.
+
+### Removed
+- **Legacy `foundry` / `social-plus-foundry` / `foundry-mcp` bin aliases** (pre-rename brand). The canonical `vise` command and the `spf` / `social-plus-vise` aliases are unchanged. This is the reason for the minor bump — invoking the package as `foundry` no longer works; switch to `vise`. (The `social-plus-foundry` *skill*-directory cleanup on install is unaffected, and the `foundry_version` sidecar field is retained for backward-read compatibility.)
+
+### Maintenance
+- **Tarball-hygiene gate (`test:tarball-hygiene`)** scans the entire shipped file set (compiled help, package metadata, LICENSE, CHANGELOG, bundled sdk-surface) against an internal-term denylist and fails the build before publish — the whole-tarball complement to the README-coverage gate. devDependencies are now stripped from the published manifest at pack time, and `tsconfig` builds with `removeComments` so internal source comments never reach `dist`. Internal references were scrubbed from the shipped surface accordingly.
+
 ## 1.0.1 — 2026-06-12
 
 Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
@@ -11,15 +55,15 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 ### Changed
 - **README rewritten for the public npm page.** Restructured customer-first (what it is → quick start → how it works → evidence → CLI/MCP/CI reference → sidecar contract) and cut from 531 to 308 lines: internal program reporting moved off the public surface, the mermaid diagrams (which npmjs.com renders as raw code blocks) replaced with a numbered flow, relative `docs/` links (which do not resolve from the npm page) removed, and references to pre-release functionality withheld from the public README until announced.
 
-### Internal
+### Maintenance
 - Unit-level regression case for the prose-embedded source-fingerprint path extractor in `test/run-compliance-helpers.mjs` (the 0.14.28 fix; mutation-verified). No shipped behavior change.
 
 ## 1.0.0 — 2026-06-11
 
-**First stable release.** 1.0 is a stability promise about the contract surface, not a new feature: `vise check` exit codes (0–7) and their precedence, the `sp-vise/` sidecar formats (with backward-read + attestation grandfathering now gated by `test:sidecar-compat`), the CLI command and MCP tool surface, the skill's required loop, and the `packages/schemas` wire formats are now under semver — breaking changes require a major bump. See [`docs/V1_READINESS.md`](docs/V1_READINESS.md) for the decision package and evidence basis (5-platform deterministic E2E journeys with all exit codes asserted on every commit; real-agent semantic matrix; three brownfield pilots green with zero Vise findings). This release consolidates everything developed across the 0.14.x-dev line after the published 0.14.28 (block-aware completeness): the items below plus the platform-hardening and model-facts work noted under the 0.14.28 entry, which reached npm here.
+**First stable release.** 1.0 is a stability promise about the contract surface, not a new feature: the CLI exit-code surface (`vise check` 0–6, plus `vise init`'s exit 7 for needs-clarification) and its precedence, the `sp-vise/` sidecar formats (with backward-read + attestation grandfathering now gated by `test:sidecar-compat`), the CLI command and MCP tool surface, the skill's required loop, and the `packages/schemas` wire formats are now under semver — breaking changes require a major bump. See `docs/V1_READINESS.md` (in the source repo) for the decision package and evidence basis (5-platform deterministic E2E journeys with all exit codes asserted on every commit; real-agent semantic matrix; three brownfield pilots green with zero Vise findings). This release consolidates everything developed across the 0.14.x-dev line after the published 0.14.28 (block-aware completeness): the items below plus the platform-hardening and model-facts work noted under the 0.14.28 entry, which reached npm here.
 
 ### Changed
-- **Skill: prefer installable blocks over hand-building.** When a Block Factory registry is available, agents are taught to check it first and use the governed `vise blocks` install path, hand-building only the remaining gaps — backed by the 2026-06-10 semantic-matrix measurement (installed path ~9× faster to green than hand-building the same outcome). No registry means hand-build as normal; block existence stays the registry's truth.
+- **Skill: prefer installable blocks over hand-building.** When a block registry is available, agents are taught to check it first and use the governed `vise blocks` install path, hand-building only the remaining gaps. No registry means hand-build as normal; block existence stays the registry's truth.
 
 ### Added
 - **False-negative discovery lane — the third compass (`docs/FN_DISCOVERY.md`).** Vise already had a TP-detection compass (`bench/tp-dashboard.mjs`, seeded from the rules so circular) and an FP compass (happy-path-clean + clone cells + pilots) but NO systematic false-NEGATIVE discovery — violations the rule corpus misses only surfaced by accident. This lane closes that, mirroring the semantic lane's two-half split:
@@ -28,15 +72,15 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
   - **Self-test** — `test/run-fn-discovery-selftest.mjs` (`test:fn-discovery-selftest`): runs the stub samples through the real validator + real grader and asserts every CAUGHT/MISSED/CLEAN-OK verdict against the stub's oracle, locking down the lane's plumbing. Both new gates run in `validate` right after `test:harness-e2e`.
   - **Real false negatives discovered while building (TypeScript):** (1) `secret.inline-api-key` missed a hardcoded key re-wrapped through a template string before `createClient` (`resolveLiteralValue` resolved direct literals only); (2) `feed.target.literal` missed a feed-target literal re-bound through a second const before `createPost` (the AST resolver followed one identifier hop); (3) `feed.target.literal` missed a hardcoded feed target when the `createPost` payload carried an `as any` cast (`pickObjectProperty` required a bare object node). Controls proved the rules fire at the single-hop / un-cast forms. **All three were then fixed in this release** (see Fixed, below); their corpus entries are promoted from quarantine to `fires`, so each blind spot can never silently reopen.
 - **iOS and Flutter model facts upgraded to `names-and-types`** (previously names-only): `scripts/extract-sdk-models.mjs` now grounds both platforms in typed sources instead of the type-less docs-ops surface exports, completing the per-platform grounding table (typescript/android/ios/flutter all names-and-types). Wire format unchanged (`2026-06-10.sdk-model-facts.v1` — names-and-types was already a legal grounding); the `extraction.sourceKind` enum gains `sdk-swiftmodule-abi` and `sdk-source-dart` in `packages/schemas`.
-  - **iOS** — parsed from the prebuilt AmitySDK xcframework's Swift module ABI JSON, canonically the **`ios-arm64` device slice** (the architecture customers ship and the only single-arch slice; the simulator slices were diffed member-for-member identical for the target models). Fields carry the compiler-printed Swift type (`Swift.String?`, `[AmitySDK.AmityCommentAttachment]`) and Optional-wrapper nullability; `declaredIn` stays `null` because a prebuilt binary has no source locations. Discovery follows the import script's pattern: `--ios-abi-json` / `SP_IOS_ABI_JSON`, then the docs-repo-relative `.docs-ops/integration-tests/ios/vendor/AmitySDK.xcframework/...` location beside the surface dir.
-  - **Flutter** — parsed from the local Flutter SDK sources by the new `scripts/dart-model-extractor` helper (package:analyzer `parseString`, **syntax-only**: verbatim declared types and literal `?` nullability, no resolution or inference; analyzer version pinned by the committed `pubspec.lock` and recorded in the extraction provenance). Public instance fields and getters only; untyped members are skipped rather than invented. Real file:line anchors into the SDK checkout. Discovery: `--flutter-sdk-root` / `SP_FLUTTER_SDK_ROOT`, then the `Amity-Social-Cloud-SDK-Flutter-Internal` checkout beside `social-plus-docs`.
+  - **iOS** — parsed from the prebuilt AmitySDK xcframework's Swift module ABI JSON, canonically the **`ios-arm64` device slice** (the architecture customers ship and the only single-arch slice; the simulator slices were diffed member-for-member identical for the target models). Fields carry the compiler-printed Swift type (`Swift.String?`, `[AmitySDK.AmityCommentAttachment]`) and Optional-wrapper nullability; `declaredIn` stays `null` because a prebuilt binary has no source locations. Discovery follows the import script's pattern: `--ios-abi-json` / `SP_IOS_ABI_JSON`, then the bundled `AmitySDK.xcframework` ABI location beside the surface dir.
+  - **Flutter** — parsed from the local Flutter SDK sources by the new `scripts/dart-model-extractor` helper (package:analyzer `parseString`, **syntax-only**: verbatim declared types and literal `?` nullability, no resolution or inference; analyzer version pinned by the committed `pubspec.lock` and recorded in the extraction provenance). Public instance fields and getters only; untyped members are skipped rather than invented. Real file:line anchors into the SDK checkout. Discovery: `--flutter-sdk-root` / `SP_FLUTTER_SDK_ROOT`, then the local Flutter SDK checkout.
   - **Degradation, recorded:** when the `.abi.json`, the Flutter checkout, or the `dart` toolchain is unreachable at import time, the platform falls back to the previous names-only surface-export extraction and the manifest records a `degradedReason` — grounding never exceeds what the reachable source proves, and the snapshot gates refuse a degraded re-import of the committed names-and-types artifacts. npm tarball 495.2 kB → 503.9 kB (regenerated typed snapshots + the Dart helper).
 
 ### Verified (typed iOS/Flutter model facts)
 - `test:sdk-surface` locks the new grounding with real extracted fields: iOS `AmityComment.commentId` as required `Swift.String` and `parentId` as optional `Swift.String?` from the arm64 abi.json (plus all-fields-typed and no-source-locations invariants), Flutter `AmityComment.commentId` as nullable `String?` property anchored to `lib/src/domain/model/amity_comment.dart` and `AmityUser.isFlaggedByMe` as a non-nullable `bool` getter.
 - `test:sdk-facts` serves the typed schemas end to end (`AmityPost.postId` → `Swift.String` on iOS; source-anchored `AmityComment` on Flutter) with the new extractor ids recorded.
 - The schemas self-test now expects names-and-types on every platform and proves the extended `sourceKind` enum bites (doctored unknown sourceKind fails validation).
-- Block Factory seam unchanged by design: contracts are still TypeScript-provenance only, so `validate:sdk-facts` / `validate:adapters` pass untouched; the typed iOS/Flutter facts are ready for future native-platform `sdkProvenance`.
+- Blocks seam unchanged by design: contracts are still TypeScript-provenance only, so `validate:sdk-facts` / `validate:adapters` pass untouched; the typed iOS/Flutter facts are ready for future native-platform `sdkProvenance`.
 
 ### Verified
 - **Harness E2E platform matrix completed (`test:harness-e2e`):** the deterministic lane-1 journey now runs for **flutter** and **ios** alongside typescript and android — each with the complete journey, no partial credit (HARNESS_E2E.md). Per-platform discoveries baked into the gate: flutter/ios block on `feed_scope`/`feed_target`/`target_screen_or_route` only; `flutter-happy-path` *is* the add-feed gap state (zero-rule clean, no pagination affordance), so its known-good implementation is a structural Dart pagination helper (naming `AmityCollection` would trip the flutter `feed.ui-states-present` sensor); the ios pre-implementation state removes `AppTheme.swift` together with `FeedViewController.swift` because the feed view is the theme's only consumer (`ios.design.reuse-detected-tokens` would otherwise mask the exit-5 gap); the exit-2 injection reuses the rule-coverage-proven `flutter-rule-missing-guards` / `ios-rule-missing-guards` files, which pair the attestation-disallowed `<platform>.secret.inline-api-key` driver with attestation-level findings in one file.
@@ -74,8 +118,8 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
   - All Swift gate rules now use the precise tree-sitter comment stripper, chained onto the conservative scanner so bindings-unavailable/oversized files degrade to the previous behavior, never to raw text. `ios-happy-path` stays at zero findings (FP canary), and a missing `tree-sitter-swift` prebuild degrades only the Swift helpers — ts/tsx/kotlin AST stays up.
 - **Dart AST honestly skipped:** every Dart grammar on npm fails against the pinned `tree-sitter@^0.21` (stale nan binding, ≥0.22-only API, forked core, WASM-only, or an unmaintained vendor-internal fork). Dart rules remain regex + conservative scanner; the verdict and re-evaluation trigger are recorded in ARCHITECTURE.md.
 - **iOS build sensor — guarded best-effort (revises the old "xcodebuild is too fragile to wire" decision):** an `.xcodeproj`/`.xcworkspace` at the surface root now enables two sensors, **only when `xcodebuild` is on PATH** — absent, `vise run-sensors` reports the sensor `skipped` with the install-Xcode precondition (the pf-003 visible-precondition pattern) instead of returning no-sensors. When runnable: a cheap `xcodebuild -list` integrity probe, then a bounded-timeout build with signing disabled (`CODE_SIGNING_ALLOWED=NO`/`CODE_SIGNING_REQUIRED=NO`/`CODE_SIGN_IDENTITY=`). Non-zero exits are classified before being reported: environment-caused failures (Command-Line-Tools-only `xcode-select`, unaccepted Xcode license, signing/provisioning demands, missing simulator/SDK destination, undeterminable workspace scheme) become **skipped-with-reason and exit 0** — never project failure — while real compile/link errors stay `failed` with a non-zero CLI exit (pf-004-era semantics). The classification channel is a new serializable `environmentSkips` field on command sensors, available to any future toolchain with the same exit-code conflation. Locked by a stub-`xcodebuild` controlled-PATH matrix in `test:sensors` (detected+green, detected+real-failure, environmental skips, absent toolchain).
-- **Installed blocks satisfy completeness baselines:** `vise check` previously scanned customer source only, so a capability delivered inside an installed Block Factory package (e.g. the Comments block's composer) still reported `completeness-gap` (exit 5). Now a checklist capability counts as present with evidence `source: "block:<blockId>"` (and a note naming the block) when an installed sidecar entry declares it and the install is still locally valid.
-- **Factory declares, Vise validates:** Block Factory contracts declare `providesCapabilities` using Vise's completeness-checklist id vocabulary (Vise owns the id space, the factory owns the per-block claim; an empty list is legitimate — the Reactions block provides no baseline ids). `vise blocks plan`/`add` carry the registry entry's ids into the install plan and `--apply` records them — plus the manifest `dependencyName` — in `sp-vise/blocks.json` (sidecar `schemaVersion` bumped to `2026-06-10.vise-blocks-sidecar.v1`).
+- **Installed blocks satisfy completeness baselines:** `vise check` previously scanned customer source only, so a capability delivered inside an installed social.plus block package (e.g. the Comments block's composer) still reported `completeness-gap` (exit 5). Now a checklist capability counts as present with evidence `source: "block:<blockId>"` (and a note naming the block) when an installed sidecar entry declares it and the install is still locally valid.
+- **Blocks declare, Vise validates:** installed block contracts declare `providesCapabilities` using Vise's completeness-checklist id vocabulary (Vise owns the id space, the factory owns the per-block claim; an empty list is legitimate — the Reactions block provides no baseline ids). `vise blocks plan`/`add` carry the registry entry's ids into the install plan and `--apply` records them — plus the manifest `dependencyName` — in `sp-vise/blocks.json` (sidecar `schemaVersion` bumped to `2026-06-10.vise-blocks-sidecar.v1`).
 - **Seam guard:** `vise blocks plan`/`add`/`validate` emit a `blocks.providesCapabilities.known` **warning** finding (never a failure) for declared ids outside Vise's completeness vocabulary; unknown ids never satisfy a gap.
 
 ### Changed
@@ -85,11 +129,11 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 ### Verified
 - `test:ast` extended with the Swift section: grammar availability, labeled-argument call extraction, identifier→literal resolution (with the env-fallback `?? ""` and interpolated-string non-resolution cases), comment stripping that preserves `//` inside strings, function-local vs type-scope handler declarations, the three indirect-literal fixtures, and the two false-positive-kill fixtures (each verified to fire under the pre-change regexes). `ios-happy-path` asserted at zero findings; existing `ios-session-handler-local-var`/`-retained` pass/fail semantics asserted unchanged.
 - `test:sensors` gains the stub-`xcodebuild` controlled-PATH matrix: detection with/without the toolchain, detected+green (exit 0), detected+real-build-failure (exit 1, not environment-skipped), no-simulator and CLT-only environmental skips (exit 0), and the absent-toolchain skip end to end.
-- New `test:blocks-completeness` gate: real `blocks add --apply` against the monorepo Block Factory registry, init with answers, `check --ci` green via `block:comments` evidence, gap restored after deleting a touched file and after removing the manifest dependency, empty `providesCapabilities` tolerated end to end, and the unknown-id warning on a doctored registry.
-- The Block Factory react target-project journey (`validate:target-projects:react`) now asserts the full install journey ends **green** with `comment-composer` satisfied by `block:comments`.
+- New `test:blocks-completeness` gate: real `blocks add --apply` against the monorepo block registry, init with answers, `check --ci` green via `block:comments` evidence, gap restored after deleting a touched file and after removing the manifest dependency, empty `providesCapabilities` tolerated end to end, and the unknown-id warning on a doctored registry.
+- The block-install react target-project journey (`validate:target-projects:react`) now asserts the full install journey ends **green** with `comment-composer` satisfied by `block:comments`.
 
-### Internal
-- **Registry seam contract extracted to `packages/schemas`:** the block-registry wire format and the `sp-vise/blocks.json` sidecar shape now live in the root workspace package `@amityco/social-plus-schemas` (private, unpublished) — a JSON Schema (`registry.schema.json`) enforced on the factory's `validate:registry`, plus the TypeScript types formerly hand-written in `src/tools/blocks.ts`. Vise imports them **type-only** via a `workspace:*` devDependency, so nothing from the package survives into the published `dist/` (proven by the packed-tarball E2E). Type-only refactor; no behavior change.
+### Maintenance
+- **Registry seam contract extracted to a shared workspace package:** the block-registry wire format and the `sp-vise/blocks.json` sidecar shape now live in a shared workspace schemas package — a JSON Schema (`registry.schema.json`) enforced on `validate:registry`, plus the TypeScript types formerly hand-written in `src/tools/blocks.ts`. Vise imports them **type-only**, so nothing from the package survives into the published `dist/` (proven by the packed-tarball E2E). Type-only refactor; no behavior change.
 
 ### Fixed
 - **Attestation evidence fingerprints no longer truncate prose-embedded paths:** the source-path extractor's extension alternation was shortest-first, so `.tsx`→`.ts`, `.json`→`.js`, and `.kts`→`.kt` inside evidence prose silently recorded no fingerprint (weakening drift detection for that attestation). Found by the harness E2E attestation stage, which now cites paths in prose as the standing regression test.
@@ -148,7 +192,7 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 
 ### Verified
 - CLI regression coverage now locks next-surface selection, completion recording, and feed-to-comments progression for broad Android social workplans.
-- Dogfooded `0.14.22` on `/Users/admin/Documents/music-player-android`: refreshed the feed contract, reached `vise check` green with 43/43 deterministic passes, synced attestations, and passed Gradle assemble/unit-test sensors.
+- Dogfooded `0.14.22` on a local Android music-player app: refreshed the feed contract, reached `vise check` green with 43/43 deterministic passes, synced attestations, and passed Gradle assemble/unit-test sensors.
 
 ## 0.14.22 — 2026-06-05
 
@@ -324,7 +368,7 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 **Theme:** Optional feed capabilities become explicit opt-in sensors.
 
 ### Added
-- *(backfilled 2026-06-10 — shipped in this release but was never recorded)* **Block installer namespace:** `vise blocks list / plan / add / validate` (PR #143). Reads a social.plus Block Factory registry, plans safe package/source-anchor/sidecar changes, applies them behind `--dry-run`/`--apply`, writes `sp-vise/blocks.json`, and validates installed block state and drift.
+- *(backfilled 2026-06-10 — shipped in this release but was never recorded)* **Block installer namespace:** `vise blocks list / plan / add / validate`. Reads a social.plus block registry, plans safe package/source-anchor/sidecar changes, applies them behind `--dry-run`/`--apply`, writes `sp-vise/blocks.json`, and validates installed block state and drift.
 
 ### Changed
 - **Add-feed completeness baseline narrowed to pagination:** image upload, poll creation, and edit post are no longer baseline completeness requirements. The add-feed `completenessChecklist` now gates pagination / load-more only.
@@ -355,12 +399,12 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 
 ## 0.14.2 — 2026-06-03
 
-**Theme:** SDK facts bridge for social.plus Block Factory.
+**Theme:** SDK facts bridge for social.plus block packaging.
 
 ### Added
 - **Bundled SDK surface snapshot** in `sdk-surface/` for offline/npm use across TypeScript, Android, iOS, and Flutter.
-- **Internal `vise sdk-facts` CLI command and `get_sdk_facts` MCP tool** for Block Factory. The tool is projectless and read-only: it proves SDK symbol/capability/model-symbol facts from the normalized SDK surface without inspecting customer code.
-- **TypeScript Comments/Reactions capability facts** for the first Block Factory validation slice, including React Native aliasing to the TypeScript SDK surface.
+- **`vise sdk-facts` CLI command and `get_sdk_facts` MCP tool** for block packaging. The tool is projectless and read-only: it proves SDK symbol/capability/model-symbol facts from the normalized SDK surface without inspecting customer code.
+- **TypeScript Comments/Reactions capability facts** for the first block validation slice, including React Native aliasing to the TypeScript SDK surface.
 
 ---
 
@@ -402,7 +446,7 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 
 ### Changed
 - **Docs/copy aligned to the `Vise` name:** README, skill, and the generated sidecar no longer reference a non-existent `sp-check` binary (use `vise check`); `run-sensors` safety wording corrected ("runs detected project scripts/wrappers; inspect with `--dry-run` before running in an untrusted project"); `RULES.md` gating semantics corrected — the exit code is driven by `advisory`/`attestation.allowed`, not `severity`.
-- **README benchmark section recalibrated** to match the Commune paper: N=1 caveat moved up front, the deterministic-grader/circularity disclosed, the speculative "rework sessions" table removed, and the null bug-fix-benchmark result noted.
+- **README benchmark section recalibrated** to match the benchmark paper: N=1 caveat moved up front, the deterministic-grader/circularity disclosed, the speculative "rework sessions" table removed, and the null bug-fix-benchmark result noted.
 
 ---
 
@@ -427,7 +471,7 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 - **`reactions.configured-name-used`** (all 5 platforms) downgraded to advisory. Rule fires on ~100% of correct apps (every tenant defaults to `"like"`) and was only clearable by a ritual comment. Version bumped to 2; existing compliance.json files will show contract-drift — run `vise sync` to update.
 
 ### Benchmark
-- Brand benchmark (Spotify Encore × social.plus community feed, Sonnet n=3): pure-mcp 0/3 behavioral compliance (avg 2.3 behavioral findings), vise-design 3/3 (0). Ban-state is the standout discriminator — missed by all pure-mcp agents, fixed by all vise-design agents through the iteration loop.
+- Brand benchmark (an external brand design system × social.plus community feed, Sonnet n=3): pure-mcp 0/3 behavioral compliance (avg 2.3 behavioral findings), vise-design 3/3 (0). Ban-state is the standout discriminator — missed by all pure-mcp agents, fixed by all vise-design agents through the iteration loop.
 - Ambiguous-brief design test: vise-design 0 hex literals (all 3 seeds), pure-mcp 0/2/15 (high variance). Design loop is a variance-reduction tool.
 - Grader now partitions findings into behavioral / file-presence / attestation-dialect; headline score is behavioral-only.
 
@@ -435,7 +479,7 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 
 ## 0.12.3 — 2026-06-02
 
-**Theme:** Design harness graduation — complete token extraction, Circles-inspired visual reference.
+**Theme:** Design harness graduation — complete token extraction, brand-inspired visual reference.
 
 ### Added
 - **`vise design reference [path] [--title <name>]`** — generates a self-contained `sp-vise/design-reference.html` design-system spec: fixed sidebar with grouped nav (COLOR / TYPOGRAPHY / LAYOUT / SURFACE / EFFECTS), sticky topbar, section headers with display-font titles, monospace token-row lists for non-visual groups (motion, breakpoints, z-index), and component samples. Reads source CSS for live `var()` resolution; falls back to contract tokens for native projects (Android/Flutter/iOS correctly grouped by category with concrete values).
@@ -449,7 +493,7 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 ### Changed
 - `renderDesignPreview` now includes sections for all 6 new categories so they aren't silently omitted from `vise design preview` output.
 - `categorizeTokenModuleValue` explicitly excludes the new categories (CSS-only extraction — consistent with the existing opacity exclusion).
-- Streamly seed-ui reference: **69 → 80 tokens**, zero "not extracted" tags in the generated HTML.
+- Seed-UI design reference: **69 → 80 tokens**, zero "not extracted" tags in the generated HTML.
 
 ---
 
@@ -474,7 +518,7 @@ Docs-only patch; no CLI, MCP, rule, or sidecar behavior changes.
 - **Marker-boundary audit** (`bench/audit-marker-boundaries.mjs`) — surfaces `\bIDENT\b` markers that would miss a longer camelCase SDK symbol. An occasional eyeball aid, deliberately **not** a CI gate.
 
 ### Docs
-- **ARCHITECTURE.md** — new "Sources of Truth" section (facts vs. opinion, across the SDK / docs / Vise repos), with a pointer from the docs repo's `.docs-ops/README`.
+- **ARCHITECTURE.md** — new "Sources of Truth" section (facts vs. opinion, across the SDK / docs / Vise repos), with a pointer from the docs repo's internal README.
 
 ---
 
@@ -513,7 +557,7 @@ The design, completeness, and SDK-version layers are **advisory** — they infor
 
 ## 0.10.0 — 2026-05-29
 
-**Theme:** Benchmark-driven sensor expansion. The Commune benchmark (9 new SDK domains: chat, push, social graph, moderation, comments) produced the first measured, defensible advantage for vise+skill over pure MCP: **7/9 working features vs 3/9** with the same agent on the same prompts. This release ships the sensors, rules, and findings.json improvements that produced that result.
+**Theme:** Benchmark-driven sensor expansion. The SDK-compliance benchmark (9 new SDK domains: chat, push, social graph, moderation, comments) produced the first measured, defensible advantage for vise+skill over pure MCP: **7/9 working features vs 3/9** with the same agent on the same prompts. This release ships the sensors, rules, and findings.json improvements that produced that result.
 
 ### Added
 - `react-native.chat.channel-type-dm` / `typescript.chat.channel-type-dm` (`warning`) — DM channels must use `type: 'conversation'`, not `type: 'community'`. Agents consistently choose `community` for 1-to-1 chats because it sounds plausible but silently creates a group channel with the wrong shape. Sensor requires `userIds` co-occurrence to avoid firing on legitimate community broadcasts.
@@ -531,9 +575,9 @@ The design, completeness, and SDK-version layers are **advisory** — they infor
 - README updated with a step-by-step Quick Start that references `findings.json` directly.
 
 ### Benchmark infrastructure (`benchmarks/`)
-- **Commune benchmark** added — 9-slice React Native scenario (CM-SETUP, CM-PRESENCE, CM-FEED, CM-EVENTS, CM-CHAT, CM-PUSH, CM-PROFILE, CM-MODERATE, CM-COMMENTS) covering chat, push, social graph, and moderation domains absent from TouchTunes. Three seed types per slice (`baseline`, `broken`, `greenfield`) for 27 fixture sets total.
+- **SDK-compliance benchmark** added — 9-slice React Native scenario (CM-SETUP, CM-PRESENCE, CM-FEED, CM-EVENTS, CM-CHAT, CM-PUSH, CM-PROFILE, CM-MODERATE, CM-COMMENTS) covering chat, push, social graph, and moderation domains absent from the earlier design benchmark. Three seed types per slice (`baseline`, `broken`, `greenfield`) for 27 fixture sets total.
 - **Rules-as-markdown control arm** (`benchmarks/commune/run-commune-rules-arm.sh`) — injects the rule corpus as a static document into the agent prompt. Built to isolate whether vise's measured advantage comes from *information delivery* (the rules) or the *iterative verification loop* (sp-check).
-- **TouchTunes runner improvements** — workspace isolation (`workspaces/broken/` vs `workspaces/baseline/` so agents can't peek at the answer), `< /dev/null` stdin redirect fix that was causing agy/codex to silently skip cells, `|| true` per-cell error isolation, and grader auto-attestation for no-file and `.d.ts`-pointing rules.
+- **Benchmark runner improvements** — workspace isolation (`workspaces/broken/` vs `workspaces/baseline/` so agents can't peek at the answer), `< /dev/null` stdin redirect fix that was causing agy/codex to silently skip cells, `|| true` per-cell error isolation, and grader auto-attestation for no-file and `.d.ts`-pointing rules.
 - **agy + codex runners** (`run-agy-cells.sh`, `run-codex-cells.sh`) — production-quality scripts with TTY-detection fixes and workspace isolation.
 
 ### Findings & reports

package/LICENSE

@@ -6,11 +6,13 @@ property of AmityCo, Ltd.
 
 PERMITTED USE
 
-You may install and use this Software solely for the purpose of
-integrating the social.plus SDK into your own applications, subject to
-your agreement with AmityCo, Ltd. covering use of the social.plus
-platform. Internal use, evaluation, and integration testing within
-your organisation are permitted.
+You may install and use this Software to integrate the social.plus SDK
+into your own applications, and to evaluate the social.plus SDK and this
+Software for that purpose. Internal use, evaluation, and integration
+testing within your organisation are permitted, including by teams
+assessing whether to adopt social.plus. Use of the Software in production
+alongside the social.plus platform is subject to your agreement with
+AmityCo, Ltd. covering use of the platform.
 
 RESTRICTIONS
 
@@ -37,7 +39,7 @@ Without prior written consent from AmityCo, Ltd. you may not:
 The rule definitions, attestation schema, and compliance contract
 shipped in this Software (the "social.plus integration compliance
 contract") are AmityCo, Ltd.'s intellectual property. Customers own
-the attestations they record under sp-foundry/ in their own
+the attestations they record under sp-vise/ in their own
 repositories.
 
 WARRANTY DISCLAIMER

package/README.md

@@ -16,11 +16,38 @@
 
 ---
 
+<p align="center">
+  <a href="#what-is-vise">What is Vise?</a> ·
+  <a href="#quick-start">Quick start</a> ·
+  <a href="#how-it-works">How it works</a> ·
+  <a href="#evidence">Evidence</a> ·
+  <a href="#supported-platforms">Platforms</a> ·
+  <a href="#cli-reference">CLI reference</a> ·
+  <a href="#mcp-integration">MCP</a> ·
+  <a href="#ci-compliance">CI</a> ·
+  <a href="#compliance-contract">Contract</a> ·
+  <a href="#support">Support</a>
+</p>
+
+---
+
 ## What is Vise?
 
-Vise wraps your AI coding agent in compliance guardrails when it integrates social.plus SDKs. It inspects your project, grounds the agent in the hosted docs, enforces 300+ platform-specific compliance rules, checks generated UI against your design system, gates baseline feature completeness, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
+**Vise wraps your AI coding agent in compliance guardrails while it integrates social.plus SDKs.** The agent still writes the code — Vise makes sure what it writes is real, correct, complete, and on-brand, and asks you the calls only a human should make.
+
+While the agent works, Vise:
+
+- 🧠 **Grounds it in the real SDK** — extracted, source-anchored facts (real types and field names), so it won't invent a symbol or field the SDK doesn't expose, and pins the version published on npm.
+- 🛡️ **Enforces 300+ platform-specific compliance rules** — the mistakes that pass a demo and break in production.
+- ✅ **Gates feature completeness** — the whole outcome (pagination, empty/error states, the capabilities you asked for), not just the happy path.
+- 🎨 **Checks generated UI against your design system.**
+- 🔧 **Runs your project's own build / lint / typecheck sensors.**
+
+It turns the request into a grounded plan, records a local contract under `sp-vise/`, and keeps checking until the integration is **green, attested, or explicitly blocked on your input** — so *"the agent stopped"* and *"the integration is done"* mean the same thing.
+
+> 🔒 **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.
 
-The agent still edits your app. Vise turns the request into a grounded plan, records a local contract under `sp-vise/`, and keeps checking until the integration is green, attested, or explicitly blocked on your input — so "the agent stopped" and "the integration is done" mean the same thing.
+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*.
 
 > **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.
 
@@ -34,6 +61,8 @@ It ships as three layers:
 
 ## Quick Start
 
+> **New to social.plus?** Vise integrates the social.plus SDK. To adopt social.plus, [talk to our team](https://www.social.plus/contact/contact-sales?utm_source=vise&utm_medium=npm-readme&utm_campaign=ga). Existing customers get their **API key + region** from the [social.plus Console](https://console.socialplus.com) and can follow the [SDK getting-started guide](https://learn.social.plus/social-plus-sdk/getting-started/overview). You can install Vise and explore `vise inspect`/`vise plan` before you have credentials.
+
 ```sh
 # 1. Install the CLI
 npm install -g @amityco/social-plus-vise
@@ -77,7 +106,7 @@ Prefer a per-project install? `npm install -D @amityco/social-plus-vise`, then c
 
 ### Three validation layers
 
-The layer is set by the *kind of claim*, which keeps Vise false-positive-free where it gates:
+The layer is set by the *kind of claim*, which is how Vise is designed to avoid false positives where it gates:
 
 | Layer | Claim | How | Enforcement |
 |---|---|---|---|
@@ -85,29 +114,38 @@ The layer is set by the *kind of claim*, which keeps Vise false-positive-free wh
 | **Feature completeness** | "this is **missing**" | A narrow mandatory baseline per outcome (pagination for feeds, a composer for comments, send + read state for chat, SDK-backed counts for profiles); richer capabilities are explicit opt-ins from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline item is built or opted out with `// vise: scope-omit <id> — <reason>` |
 | **Design conformance** | "this **looks off**" | Extract your design system into a contract, confirm a preview, then check token usage | **Advisory** — `vise design check`/`preview`; never fails a build |
 
-Correctness is gated by deterministic rules or attestations; completeness is gated by explicit scope decisions; conformance stays advisory because "matches the brand" is legitimately subjective. `vise explain <ruleId>` prints any rule's rationale, evidence requirements, and remediation.
+Correctness is gated by deterministic rules or attestations; completeness is gated by explicit scope decisions; conformance stays advisory because "matches the brand" is legitimately subjective. Each gating rule is itself mutation-verified — its fix is reverted to confirm the check actually fails without it, so a rule that can't fail is removed rather than shipped as theater. `vise explain <ruleId>` prints any rule's rationale, evidence requirements, and remediation.
 
 **Supported outcomes:** feed · comments · chat · moderation · community · social graph (follow) · in-app notifications · plus setup (SDK, push, live data). `vise plan`/`init` classify the request and tailor the plan, rules, and feature checklist.
 
+### 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.
+
+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.
+
 ### Design contracts
 
 Vise can ingest your aesthetic from an HTML/CSS prototype (`vise design extract`) or from the host app's own design system across web, Android, Flutter, and iOS (`vise design extract --from-project`). The contract is **advisory input for generation**, never an enforcement gate, and it feeds forward into plans only after you confirm the generated preview with `--answer design_contract_confirmation=yes`. For social.plus-specific styling, `vise design init-tokens` scaffolds a dedicated, customer-editable token file (`src/styles/social-plus-tokens.css`) — edit it, re-extract, and future builds inherit the palette with no agent in the loop.
 
 ## Evidence
 
-Feed-completeness benchmark — same feed request, same SDK docs, with and without the Vise workflow (Vise arm explicitly selected optional capabilities):
+Vise's measured effect is on whether an agent builds the *whole* outcome — pagination, empty and error states, the optional capabilities you asked for — or just the happy path. The durable finding across benchmarks is the **mechanism**, not any single percentage: a checked verification loop beats the same rules pasted into a prompt. What Vise reliably changes is the **stopping condition** — the agent isn't done when the code compiles; it's done when the local contract is green, attested, or blocked on an explicit customer decision.
 
-| Agent / model | Docs-only baseline | With Vise |
-|---|---:|---:|
-| Cursor / Composer 2.5 | 30% (3.3/11 avg) | **97%** (32/33) |
-| Claude / Sonnet 4.6 | 27% (3.0/11 avg) | **100%** (33/33) |
-| Codex / GPT-5.4 | 21% (2.3/11 avg) | **100%** (33/33) |
+**Matched comparisons** — Vise's verification loop vs a docs-only baseline, same task and agent:
 
-Aggregate: **98/99** expected feed capabilities and **27/27** selected optional capabilities implemented across the Vise arm.
+| Benchmark | What's measured | Docs-only | With Vise |
+|---|---|---|---|
+| **SDK compliance** | correctness slices passed (greenfield; 9 independent slices, single run per cell, two agents) | 6/9 (67%) | **9/9 (100%)** |
+| **Design conformance** | the brand's *named* design tokens used vs hardcoded values (ambiguous brief, n=3) | ~72% | **~90%** |
 
-- **SDK compliance:** Vise averaged **100%** greenfield compliance where docs/RAG-style controls averaged **67%** (Commune benchmark).
-- **Design drift:** under an ambiguous brief, Vise design runs produced **0/0/0** hex literals across seeds vs **0/2/15** without — variance reduction, not pixel perfection.
-- **Boundaries:** these are best-case/opt-in comparisons for greenfield social.plus work, not universal claims. Negative results travel with the claims — e.g. no measured advantage on day-2 bug fixing. What Vise reliably changes is the **stopping condition**: the agent isn't done when code compiles; it's done when the local contract is green, attested, or blocked on explicit customer input.
+The mechanism is the durable claim: a checked loop beats the same rules in the prompt.
+
+**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.
+
+**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>
 
 ## Supported Platforms
 
@@ -293,13 +331,15 @@ Attestations record SHA-256 source fingerprints of cited files, so later edits t
 ## Support
 
 - **Documentation:** [https://learn.social.plus](https://learn.social.plus) — the same corpus `vise search-docs` grounds agents in.
-- **Bugs / feature requests:** contact your social.plus account team or file an issue with your integration partner.
-- **Skill installation issues:** `vise doctor` prints diagnostics; share the output with support.
+- **Questions, bugs & feature requests:** email [support@social.plus](mailto:support@social.plus). Existing customers can also reach their social.plus account team or integration partner.
+- **Skill installation issues:** run `vise doctor` and include its output.
 - **Version history:** `CHANGELOG.md` ships inside the installed package.
 
 ## License
 
-Proprietary — see the `LICENSE` file included with the package. social.plus Vise is provided to social.plus customers and integration partners under the same agreement as the social.plus SDK.
+Proprietary — see the `LICENSE` file included with the package. **Free to install and evaluate** for integrating the social.plus SDK, including by teams assessing whether to adopt social.plus. Production use alongside the social.plus platform is covered by your social.plus agreement; integration partners are licensed under their partner agreement.
+
+Installing globally (`npm install -g`) or running via `npx` keeps Vise out of your application's dependency tree — and its proprietary license out of your SBOM / dependency-license scanner reports.
 
 ---