@amityco/social-plus-vise 1.4.4 → 1.4.6

package/CHANGELOG.md

@@ -8,6 +8,21 @@ The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/
 
 No changes yet.
 
+## 1.4.6 — 2026-07-02
+
+### Added
+- **Marketing capability explainer.** Added a shipped `docs/vise-how-it-helps.html` page for marketing and sales enablement that explains Vise's agentic workflow, three validation layers, current real-E2E scorecard methodology, and realistic brownfield-style Social+ integration outputs in a light themed gallery.
+
+### Changed
+- **Preview status is explicit in the public README.** The npm README now marks Vise as a preview release and sets the expected boundary for API stability, benchmark methodology, advisory intelligence, code review, QA, and runtime verification.
+
+## 1.4.5 — 2026-07-02
+
+### Changed
+- **Public npm README claim discipline tightened.** Clarified that Vise governs AI agents rather than making them perfect, separated advisory design conformance from hard validation gates, and distinguished Vise's local privacy behavior from each AI host's data policy.
+- **Benchmark scorecard wording refreshed.** The evidence section now identifies the current Codex GPT-5.4 Medium harness, notes equivalent-tier model protocol expectations, adds public-safe benchmark boundaries, and replaces fixture slugs with meaningful brownfield product/social-goal descriptions.
+- **Current tool and platform coverage reflected.** The README now documents `vise sdk-facts`, lists all current MCP tools, and replaces stale/overbroad platform-domain wording with supported-platform language tied to the shipped rule suite.
+
 ## 1.4.4 — 2026-07-02
 
 ### Changed

package/README.md

@@ -6,6 +6,7 @@
 
 <p align="center">
   <a href="https://www.npmjs.com/package/@amityco/social-plus-vise"><img src="https://img.shields.io/npm/v/@amityco/social-plus-vise.svg" alt="npm version" /></a>
+  <img src="https://img.shields.io/badge/Status-Preview-orange.svg" alt="Preview status" />
   <img src="https://img.shields.io/badge/License-Proprietary-blue.svg" alt="License" />
   <a href="https://learn.social.plus"><img src="https://img.shields.io/badge/Docs-learn.social.plus-informational" alt="Docs" /></a>
 </p>
@@ -33,19 +34,21 @@
 
 ## What is Vise?
 
-**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.
+> **Preview release.** Vise is usable for guided social.plus SDK integrations, but the CLI surface, evidence format, benchmark methodology, and advisory intelligence may still change as the product hardens through more real projects. Treat it as governed AI assistance with strong validation gates, not a substitute for code review, product QA, or runtime verification.
+
+**Vise wraps your AI coding agent in compliance guardrails while it integrates social.plus SDKs.** The agent still writes the code — Vise grounds that work in real SDK APIs, checks correctness and completeness, helps align generated UI with your design system, and asks you the calls only a human should make. It does not make AI agents perfect; it gives them a governed loop, explicit gates, and evidence when something is green, intentionally scoped out, or still unverified.
 
 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 400+ platform-specific checks** — 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.**
+- 🎨 **Reviews generated UI against your design system** — advisory, because brand fit still needs human judgment.
 - 🔧 **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.
+It turns the request into a grounded plan, records a local contract under `sp-vise/`, and keeps checking until the integration is **green, attested, intentionally scoped, or explicitly blocked on your input** — so the handoff distinguishes finished work from unverified work instead of treating *"the agent stopped"* as *"done"*.
 
-> 🔒 **Your source code never leaves your machine.** Vise fetches only the public social.plus docs and the SDK's published version on npm — never your code, file contents, or search queries. `VISE_DOCS_OFFLINE=1` runs fully offline.
+> 🔒 **Vise itself does not upload your source code.** Your AI coding host follows its own data policy; Vise fetches only the public social.plus docs and the SDK's published version on npm — never your code, file contents, or search queries. `VISE_DOCS_OFFLINE=1` runs fully offline.
 
 Vise can also run **ahead** of that loop: an advisory [Engagement Intelligence](#engagement-intelligence) layer turns a product goal into multiple candidate engagement strategies — *what you might build*, not only *whether you built it right*.
 
@@ -139,20 +142,33 @@ Vise can ingest your aesthetic from an HTML/CSS prototype (`vise design extract`
 
 ## Evidence
 
-Vise is measured against complete brownfield integrations, not isolated snippets. In the real end-to-end benchmark suite, agents were asked to add social.plus to existing product-shaped apps across five platforms. The score combines workflow guidance, product surface completion, design fit, correctness, and efficiency.
+Vise is measured against complete brownfield integrations, not isolated snippets. In the real end-to-end benchmark suite, agents were asked to add social.plus to existing product-shaped apps across five platforms. The current scorecard was produced with the Codex GPT-5.4 Medium harness; the protocol is designed for equivalent-tier coding models such as Claude Sonnet 4.6 or Gemini Flash 3.5, with each Vise/no-Vise pair kept on the same model and reasoning setting. The score combines workflow guidance, product surface completion, design fit, correctness, and efficiency. These July 2026 social.plus benchmark runs are directional product evidence from representative app fixtures, not a third-party audit.
 
 **Current end-to-end scorecard**
 
-| Platform | Scenario | With Vise | Without Vise | Improvement |
+| Platform | Brownfield product / social goal | With Vise | Without Vise | Improvement |
 |---|---|---:|---:|---:|
-| **Android** | market-pulse | **94.3** | 31.2 | **+63.1** |
-| **iOS** | luminary-club | **90.1** | 43.0 | **+47.1** |
-| **Web** | pulse-studio | **91.4** | 65.6 | **+25.8** |
-| **Flutter** | fieldhouse-club | **92.8** | 33.0 | **+59.8** |
-| **React Native** | arena-fit | **90.3** | 67.3 | **+23.0** |
+| **Android** | Investor watchlist app with social circles | **94.3** | 31.2 | **+63.1** |
+| **iOS** | Editorial audio app with curator clubs | **90.1** | 43.0 | **+47.1** |
+| **Web** | Fitness media app with program communities | **91.4** | 65.6 | **+25.8** |
+| **Flutter** | Training clubhouse with squad discussions | **92.8** | 33.0 | **+59.8** |
+| **React Native** | Athlete training app with clubhouse feed | **90.3** | 67.3 | **+23.0** |
 
 Average with Vise: **91.8**. Average without Vise: **48.0**. Average improvement: **+43.8 points**.
 
+**How the score is calculated:** each run is scored from 0-100 across five dimensions, then weighted into one overall score: capability activation (**25%**), product outcome (**25%**), design integration (**20%**), correctness (**20%**), and efficiency (**10%**). In shorthand:
+
+```text
+overall =
+  capability activation * 0.25 +
+  product outcome       * 0.25 +
+  design integration    * 0.20 +
+  correctness           * 0.20 +
+  efficiency            * 0.10
+```
+
+Capability activation measures whether the Vise arm actually used the governed workflow (inspection, Engagement Intelligence selection, blueprint/sign-off artifacts, docs lookup, checks, sensors, and local `sp-vise/` evidence); no-Vise controls intentionally score 0 on that dimension because they must not use Vise. Product outcome and design integration are judged from runtime-visible social surfaces and screenshots. Correctness covers build/runtime hygiene, SDK-backed source, no leaked secrets, no hardcoded social object IDs, and completed handoff. Efficiency rewards validated, SDK-backed outcome delivered within the time/command budget. Caps lower the score when a run is quota-limited, explicitly unfinished, missing a required multi-surface workplan, or proves too little runtime surface coverage. Platform rows enter the head-to-head average only when the Vise and no-Vise arms target the same platform/scenario and are scored with the same launch-verification standard.
+
 What changed with Vise in the loop:
 
 - The agent starts from a grounded plan instead of guessing the integration shape.
@@ -164,15 +180,15 @@ What changed with Vise in the loop:
 
 ## Supported Platforms
 
-| Platform | Coverage | Sensors |
+| Platform | Status | Sensors |
 |---|---|---|
-| **TypeScript / Next.js / React** | ✅ Full | `tsc`, `npm build`, `npm lint`, SDK import smoke |
-| **React Native** | ✅ Full | `tsc`, `npm lint`, SDK import smoke |
-| **Flutter / Dart** | ✅ Full | `flutter analyze`, `flutter test` |
-| **Android (Kotlin)** | ✅ Full | Gradle assemble, unit tests |
-| **iOS (Swift)** | ✅ Full | Static rules fully operational (tree-sitter AST for highest-risk rules); `Package.swift` enables a SwiftPM manifest sensor, and `.xcodeproj`/`.xcworkspace` enables a guarded `xcodebuild` sensor when available |
+| **TypeScript / Next.js / React** | Supported | `tsc`, `npm build`, `npm lint`, SDK import smoke |
+| **React Native** | Supported | `tsc`, `npm lint`, SDK import smoke |
+| **Flutter / Dart** | Supported | `flutter analyze`, `flutter test` |
+| **Android (Kotlin)** | Supported | Gradle assemble, unit tests |
+| **iOS (Swift)** | Supported | Static rules fully operational (tree-sitter AST for highest-risk rules); `Package.swift` enables a SwiftPM manifest sensor, and `.xcodeproj`/`.xcworkspace` enables a guarded `xcodebuild` sensor when available |
 
-Each platform has dozens of rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).
+Each platform is checked by the shipped rule suite across feed, comments, chat, moderation, communities, social graph, secrets, session & auth, notifications, live data, security, design, and more.
 
 ## CLI Reference
 
@@ -227,6 +243,7 @@ Everything in this group is local and advisory: no uploads, no `vise check` exit
 |---|---|
 | `vise search-docs "<query>"` | Search social.plus docs for relevant pages |
 | `vise get-doc-page <path>` | Fetch a specific doc page by path |
+| `vise sdk-facts --platform <platform> [--capability <capability>] [--format json]` | Read bundled SDK surface facts without a project; useful for agents and block packaging when they need field-level facts before editing |
 | `vise debug [path] --error "..." [--brief]` | Diagnose an SDK-specific runtime failure; `--brief` returns the likely rule, minimal patch shape, and verification commands |
 
 ### Compliance verification
@@ -270,9 +287,9 @@ MCP-capable hosts can call Vise as structured tool calls instead of shell comman
 }
 ```
 
-Tool names (snake_case per MCP convention): `inspect_project`, `creative_brief`, `creative_accept`, `ux_harness`, `compile_experience`, `experience_sensors`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `experience_report`, `record_learning`, `show_learning`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `design_extract`, `design_check`, `design_contrast`, `design_preview`, `design_reference`, `design_init_tokens`.
+Tool names (snake_case per MCP convention): `search_docs`, `get_doc_page`, `inspect_project`, `creative_brief`, `creative_accept`, `ux_harness`, `compile_experience`, `experience_sensors`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `experience_report`, `record_learning`, `show_learning`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `resolve_request`, `run_sensors`, `smoke`, `validate_setup`, `suggest_patch`, `debug_issue`, `design_extract`, `design_check`, `design_contrast`, `design_preview`, `design_reference`, `design_init_tokens`, `get_sdk_facts`.
 
-These mirror the CLI commands above. The adapter still answers the legacy `resolve_request` and `suggest_patch` names, but they are deprecated in favour of `plan_integration` plus host-tool edits.
+Most tools mirror the CLI commands above. The adapter still answers the legacy `resolve_request` and `suggest_patch` names for compatibility, but they are deprecated in favour of `plan_integration` plus host-tool edits.
 
 ## CI Compliance