@amityco/social-plus-vise 1.0.0 → 1.1.0

package/README.md

@@ -6,7 +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>
-  <a href="./LICENSE"><img src="https://img.shields.io/badge/License-Proprietary-blue.svg" alt="License" /></a>
+  <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>
 
@@ -16,208 +16,129 @@
 
 ---
 
-## Quick Start
-
-```sh
-# 1. Install
-npm install -g @amityco/social-plus-vise
-
-# 2. Install the AI skill into your coding tool (pick your host)
-vise install-skill --target claude        # Claude Code (personal)
-vise install-skill --target cursor .      # Cursor (project-local)
-vise install-skill --target copilot .     # GitHub Copilot / VS Code
-
-# 3. Ask your AI agent to integrate with social.plus
-#    (the skill handles the rest — inspect, plan, init, code, check)
-```
+<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>
 
-**Step 3 in practice:** Open your AI coding tool in your project and prompt:
+---
 
-> "Add a social feed to this app using the social.plus SDK."
+## What is Vise?
 
-The installed skill teaches your agent to run `vise inspect` → `vise plan` → `vise init` → edit code → `vise check` → `vise run-sensors` automatically. You drive intent; Vise keeps the agent on the rails.
+**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.
 
-See [Usage Flow](#usage-flow) for the full step-by-step diagram.
+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.**
 
-## What Vise Does: Agentic Workflow Governance
+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.
 
-Instead of just providing a CLI or AI skills, Vise implements a technique called **Agentic Workflow Governance**. Think of it as a customer-project integration harness: the governed build loop runs inside the target repo, grounded in the real project, real docs, and real validation signals.
+> 🔒 **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 wraps your local coding agents in compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 300+ platform-specific compliance rules, checks the generated UI against the customer's design system, gates narrow baseline capabilities so nothing mandatory is silently dropped, offers richer feed capabilities as explicit opt-ins, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
+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*.
 
-At a glance, Vise sits between the user's prompt and the agent's code changes. The agent still edits the app; Vise turns the request into a grounded plan, records the local contract, and keeps checking until the integration is ready to ship.
+> **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.
 
-```mermaid
-flowchart LR
-    Prompt["User prompt<br/>Add a social.plus feature"] --> Skill["AI skill<br/>drives the loop"]
-    Skill --> Inspect["Inspect project<br/>platform, app surface,<br/>design signals"]
-    Inspect --> Plan["Plan<br/>outcome, docs,<br/>intake questions"]
-    Plan --> Design["Design + capability preflight<br/>preview confirmation,<br/>feature checklist"]
-    Design --> Build["Agent builds<br/>edits customer code locally"]
-    Build --> Check["Vise check<br/>SDK compliance gate"]
-    Check -->|findings| Build
-    Check --> Sensors["Sensors<br/>typecheck, build,<br/>lint, SDK smoke"]
-    Sensors -->|failures| Build
-    Sensors --> Done["Done<br/>sp-vise contract<br/>and evidence"]
-```
+It ships as three layers:
 
 | Layer | Purpose |
 |---|---|
-| **Skill** (`SKILL.md`) | Tells your AI agent when to inspect, plan, fetch docs, edit, validate, and attest |
+| **Skill** (`SKILL.md`) | Teaches your AI agent when to inspect, plan, fetch docs, edit, validate, and attest |
 | **CLI** (`vise`) | Deterministic engine: inspects repos, searches docs, validates setup, runs sensors, manages attestations |
-| **MCP adapter** | Optional stdio server for MCP-capable tools (Claude Code, Cursor, Codex, VS Code, Copilot) |
-
-### What Vise validates: three layers
+| **MCP adapter** | Optional stdio server for MCP-capable hosts (Claude Code, Cursor, Codex, VS Code, Copilot) |
 
-Vise validates on three layers, and the layer is set by the *kind of claim* — which keeps it false-positive-free where it gates:
-
-| Layer | Claim | How | Enforcement |
-|---|---|---|---|
-| **SDK compliance** | "this is **wrong**" | 300+ deterministic rules (session renewal, live-collection vs one-shot, no secret in logs, parent-child rendering, ban-state gating…) | **Hard gate** — `vise check` blocks until green or attested. A small advisory subset surfaces as informational only and never blocks. |
-| **Design conformance** | "this **looks off**" | extract the customer's design system into a contract, render a preview for confirmation, then check token usage | **Advisory** — `vise design check`/`preview`; never fails a build |
-| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, for add-comments, the composer/write affordance is mandatory, for add-chat, send plus read/unread state are mandatory, and for add-follow/profile, SDK-backed follower/following data is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built, satisfied by an installed Block Factory block (evidence `source: "block:<id>"`, re-validated locally on every check), or validly opted out; selected optional capabilities run separate sensors |
-
-Correctness is gated by deterministic rules or attestations. Baseline completeness is gated by explicit scope decisions: if a baseline capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Installed Block Factory blocks count too: the factory declares the completeness ids a block provides (`providesCapabilities`), `vise blocks add --apply` records them in `sp-vise/blocks.json`, and `vise check` honours them only while the block's manifest dependency and touched files are intact — on drift the gap returns. Optional feed capabilities such as image upload, poll creation, and edit post are offered during planning and become checked only after the user opts in. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
-
-### Engagement Intelligence roadmap
-
-Vise's next architecture track is the social.plus **Engagement Intelligence System**: an outcome-to-experience layer that maps customer goals, archetypes, solution patterns, experience objects, UX patterns, and variants before normal implementation planning. The first advisory runtime slice is `vise creative`: it consumes a request plus optional requirements/prototype inputs, or runs in exploratory mode when requirements are absent, writes a local creative brief for user variant selection, and records the accepted variant so `vise plan`, `vise init`, and `vise workplan` can carry that product/UX direction forward. See [docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md](docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md), [docs/MONOREPO_ARCHITECTURE.md](docs/MONOREPO_ARCHITECTURE.md), and [packages/intelligence](packages/intelligence).
-
-The current milestone is the **Learning Engine sensor bridge with score calibration guardrails**. After creative selection, experience compilation, and sensor review, Vise can keep local learning events that snapshot the selected variant, outcome, Experience Report, and Experience Sensor Framework, then summarize recurring review gaps by variant, outcome, and dimension. The shadow calibration track now has 70 measured cells, including a v2 independent candidate-ranking matrix that ranked the expected variant first in 21/21 registered cells while preserving visible review gaps. The v2 human gate has named product FP/FN and privacy sign-off recorded, including approval that `event-first` beats `creator-first` in the five thin-margin cross-platform cells. Gate 2 exposes this evidence only as an explicit `vise creative --ranking-preview` local advisory preview; the current local dogfood pass covers 18 synthetic prompts spanning ten archetypes and all ten catalog variants (seven available, three gamification variants gated as in-development). Of the 14 available-variant cases, 13 align and 1 is a declared near-miss — in the opt-in preview only, the shadow-policy-v2-draft ranking ranks `live-commerce` just above `discovery-first` for an ecommerce social-discovery prompt, while the brief's keyword default and the agent both pick the human-correct `discovery-first` — with 0 undeclared ranking concerns and 0 candidate-surfacing gaps; the other 4 gamification cases are correctly gated. The paired `live-shopping-stream` control (a clear live-selling prompt) shows the preview correctly elevating `live-commerce` over the keyword default. There are still no uploads, no changed `vise check` exit codes, no calibrated single score, no auto-acceptance, and no default recommendation ranking. See [docs/UX_HARNESS_MVP.md](docs/UX_HARNESS_MVP.md), [docs/LEARNING_ENGINE_MVP.md](docs/LEARNING_ENGINE_MVP.md), [docs/EXPERIENCE_SCORE_CALIBRATION.md](docs/EXPERIENCE_SCORE_CALIBRATION.md), and [docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md](docs/ENGAGEMENT_INTELLIGENCE_SYSTEM.md).
-
-### Relationship to social.plus Block Factory
-
-Vise keeps two deliberately separate personas — the **customer-integration helper** (runs inside customer projects, may write `sp-vise/*`, including the `vise blocks` installer workflow) and the **Block Factory SDK-facts provider** (projectless, read-only, exports SDK symbol/capability/model facts). Vise owns SDK truth and customer-project governance; Block Factory owns the blocks. The canonical ownership table and the seam contracts live in [`../docs/BOUNDARY.md`](../docs/BOUNDARY.md); the provider-side design is [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md).
-
-### Block Factory user experience
-
-When Vise is used with social.plus Block Factory, the customer experience should feel like asking an AI agent for a social capability rather than manually assembling SDK calls and UI states:
-
-> "Add social.plus comments to this app and match my existing design system."
+## Quick Start
 
-The agent uses Vise to turn that request into a governed install workflow:
+> **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
-vise blocks list --registry ./registry/blocks.json --format json
-vise blocks plan . --block comments --registry ./registry/blocks.json --format json
-vise blocks add . --block comments --registry ./registry/blocks.json --package-source npm --dry-run
-vise blocks add . --block comments --registry ./registry/blocks.json --package-source npm --apply
-vise blocks validate . --block comments --registry ./registry/blocks.json --format json
-vise run-sensors --dry-run
-```
-
-What Vise does:
-
-- Inspects the customer project and detects the target platform.
-- Reads Block Factory registry metadata without owning block product data.
-- Plans package, source-anchor, sidecar, design-contract, and sensor requirements.
-- Applies changes only to package manifests, `sp-vise/blocks.json`, and source files with explicit install anchors.
-- Returns `needs-review` when a brownfield project has no safe install anchor.
-- Validates installed block state and detects drift after future code changes.
-
-Required customer or agent actions:
-
-- Choose the block id and package source.
-- Review the dry-run plan before using `--apply`.
-- Add explicit install anchors when Vise cannot safely edit the project.
-- Keep `sp-vise/blocks.json` committed so future validation has state to compare.
-- Run the target project's normal build, lint, test, and Vise sensors before shipping.
-
-### Design-conformant UI
-
-Vise can ingest the customer's aesthetic into a **design contract** and guide generation to match it — from an HTML/CSS prototype (`vise design extract`) or from the host app's own design system across web + Android + Flutter + iOS (`vise design extract --from-project`: CSS vars/Tailwind/token modules, `colors.xml`, Flutter `Color(0x…)`, iOS `.colorset`/Swift). `vise design extract` writes both `sp-vise/design-contract.json` and `sp-vise/design-preview.html`; `vise plan`/`init` withhold design feed-forward until the preview is explicitly accepted with `--answer design_contract_confirmation=yes`. If the preview is rejected (`=no`), Vise asks for a replacement design source and records no design-conformance claim. `vise design check` reports token conformance; `vise design preview` writes a visual review; `vise design reference` generates a full visual design-system spec (swatches, type samples, component demos). All advisory.
-
-**For social.plus-specific styling:** `vise design init-tokens` scaffolds `src/styles/social-plus-tokens.css` in your project — a dedicated token file for social.plus features that you can edit independently from your main app's design system. Greenfield projects get sensible `--sp-*` defaults; brownfield projects get their existing token values seeded in. Edit the file, run `vise design extract --from-project` to refresh the contract, and future agent builds inherit the updated palette — no AI agent needed in the update loop.
-
-### Supported integrations (outcomes)
-
-`vise plan`/`init` classify the request into an outcome and tailor the plan, rules, and feature checklist: **feed** · **comments** · **chat** · **moderation** · **community** · **social graph (follow)** · **in-app notifications** · plus setup (SDK, push, live data).
-
-### Why "Vise"
+# 1. Install the CLI
+npm install -g @amityco/social-plus-vise
+vise doctor                                # verify install
 
-A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Without one, the workpiece drifts and cuts wander. Vise does the same for AI agents integrating SDKs: it clamps the integration to a known-good position (the real docs, the real project structure, the real compliance rules) so the agent can focus on creative work instead of guessing.
+# 2. Install the AI skill into your coding tool
+vise install-skill --target claude        # Claude Code (personal)
+vise install-skill --target cursor .      # Cursor (project-local)
+vise install-skill --target copilot .     # GitHub Copilot / VS Code
 
----
+# 3. Open your AI coding tool in your project and ask:
+#    "Add a social feed to this app using the social.plus SDK."
+```
 
-## Benchmark Results: Current Claim
+The skill drives the loop automatically — `vise inspect` → `vise plan` → `vise init` → edit code → `vise check` → `vise run-sensors`. You drive intent, answer scope questions, and approve the design preview; Vise keeps the agent honest. See [How it works](#how-it-works).
 
-> **Vise gives AI coding agents a governed workflow for social.plus integrations: it makes scope explicit, checks the local code, and turns missing SDK capabilities or compliance gaps into repair work before the agent stops.**
+All skill targets:
 
-The strongest current claim is not a universal speed or quality promise. It is narrower and more useful: for greenfield social.plus SDK work, Vise improves the stopping condition. The agent is not done after reading docs or producing code; it is done when the local contract is green, attested, or blocked on explicit customer input.
+| Host | Install command |
+|---|---|
+| Claude Code (personal scope) | `vise install-skill --target claude` |
+| Claude Code (project scope) | `vise install-skill --target claude-project .` |
+| OpenAI Codex | `vise install-skill --target codex` |
+| Cursor (native skills) | `vise install-skill --target cursor .` |
+| Cursor (legacy rules) | `vise install-skill --target cursor-rules .` |
+| GitHub Copilot / VS Code | `vise install-skill --target vscode .` |
+| Copilot CLI / project | `vise install-skill --target copilot .` |
+| Generic agent project | `vise install-skill --target agents .` |
+| Other coding agents | `vise print-skill` (paste into the host's project instructions) |
 
-### Latest Quantitative Benchmark
+Prefer a per-project install? `npm install -D @amityco/social-plus-vise`, then call `npx vise`. The skill is plain Markdown — read it any time with `vise print-skill`.
 
-The latest feed-completeness benchmark remains the headline product proof. Same feed request, same SDK docs, no Vise workflow in the baseline; the Vise arm explicitly selected feed optional capabilities, persisted that choice into `sp-vise/compliance.json`, and activated selected source sensors.
+## How it works
 
-| Agent / model | Docs-only baseline | Vise opt-in arm | Readout |
-|---|---:|---:|---|
-| Cursor / Composer 2.5 | 30% (3.3/11 avg) | **97% (32/33)** | One seed surfaced the remaining item instead of silently dropping it. |
-| Claude / Sonnet 4.6 medium | 27% (3.0/11 avg) | **100% (33/33)** | All three Vise seeds reached 11/11. |
-| Codex / GPT-5.4 medium | 21% (2.3/11 avg) | **100% (33/33)** | All three Vise seeds reached 11/11. |
+1. **Inspect** — `vise inspect` detects the platform, app surfaces, available sensors, and design signals from the local repo.
+2. **Plan** — `vise plan --request "..."` classifies the outcome, cites docs, and raises blocking intake and design-preview questions. The agent surfaces them; you answer.
+3. **Initialize** — `vise init` writes the `sp-vise/` compliance contract. While blocking questions are unanswered it refuses, returns `status: "needs-clarification"`, and exits 7 — the agent must ask instead of guessing.
+4. **Build** — the agent edits your code, grounded by `vise search-docs` and `vise get-doc-page`.
+5. **Check & repair** — `vise check` reports deterministic findings, completeness gaps, and attestation needs. The agent fixes findings or records attestations with evidence, looping until green.
+6. **Sense** — `vise run-sensors` runs your project's own typecheck/build/lint/SDK smokes. Done means the contract and evidence are committed, not just that the agent stopped.
 
-Aggregate: **98/99 expected feed capabilities** and **27/27 selected optional capabilities** implemented across the Vise arm.
+### Three validation layers
 
-### Current Release Validation
+The layer is set by the *kind of claim*, which is how Vise is designed to avoid false positives where it gates:
 
-Version 1.0.0 carries current release proof around the full feed-forward, product-expectation, creative pre-planning, block-aware completeness, and validation flow:
+| Layer | Claim | How | Enforcement |
+|---|---|---|---|
+| **SDK compliance** | "this is **wrong**" | 300+ deterministic rules (session renewal, live-collection vs one-shot, secret hygiene, parent-child rendering, ban-state gating…) | **Hard gate** — `vise check` blocks until green or attested; a small advisory subset never blocks |
+| **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 |
 
-| Surface | What was validated |
-|---|---|
-| **Creative pre-planning** | `vise creative` produces requirements-driven or exploratory Engagement Intelligence briefs, writes `sp-vise/creative-brief.json` / `.md`, asks for `preferred_solution`, and survives packed-package installation with the intelligence catalog bundled. |
-| **Creative selection bridge** | `vise creative accept --variant <id>` writes `sp-vise/creative-selection.json` and `sp-vise/ux-harness.json`; matching `vise plan`, `vise init`, and `vise workplan next` runs surface the accepted variant, UX expectations, derive workplan surfaces from its experience objects, and mirror the selection into `sp-vise/intake.json`. |
-| **Product flow** | Local end-to-end smoke covers design extraction, plan feed-forward, blocking intake, answered init, capability check, design conformance, and sensor discovery. |
-| **Multi-surface planning** | Broad social requests are decomposed into a `socialWorkplan` sequence for feed, comments, chat, and profile work instead of forcing a single top-level surface choice. `vise workplan next` tells the host agent which surface to implement next, and `vise workplan complete` records green-check progress in `sp-vise/workplan.json` with per-surface snapshots under `sp-vise/workplan-snapshots/<surface>/`. |
-| **Plan questions** | Plans surface blocking questions such as `design_contract_confirmation`, product-scope questions such as `feed_post_type_scope`, `feed_composer_type_scope`, `comment_tray_scope`, `chat_inbox_scope`, and `profile_identity_scope`, plus optional choices such as `feed_optional_capabilities`. Focused plans still accept `feature_surface` answers when the agent is ready to implement one surface. |
-| **Capability-to-sensor flow** | Vise checks platform support, matches the prompt to available capabilities, offers supported features as questions, records answers, and turns selected answers into sensors in `vise check`. |
-| **Experience Score calibration guard** | Experience Report, Experience Sensors, and Learning Engine snapshots keep `score: null`, while `learning-summary.json` keeps `recommendationOptimization.status: "not-active"`. The shadow benchmark has 70 measured cells; `shadow-policy-v2-draft` independently ranked expected variants first in 21/21 registered ranking/cross-platform cells, its human gate package has named product FP/FN and privacy sign-off recorded, and runtime exposure is limited to the opt-in local `vise creative --ranking-preview` artifact. |
-| **Android workplan dogfood** | A brownfield Android music-player app refreshed under `0.14.24` reached `vise check` green with **43/43 deterministic passes** on the focused feed surface and recorded a green-check workplan snapshot. This is dogfood evidence, not a controlled multi-agent benchmark. |
-| **Shared product expectations** | Public IDs such as `feed.target-resolved`, `feed.post-type-scope-explicit`, `comments.creation-affordance`, `chat.channel-list-order-explicit`, `community.avatar-from-sdk`, `moderation.role-gated-action`, `follow.relationship-live`, `profile.identity-from-sdk`, `profile.social-counts`, and `notifications.tray-live` stay platform-agnostic while check results retain concrete `contractRuleId` and `validator.sensorId` evidence when deterministic sensors exist. |
-| **Rule detection** | TP-track dashboard detects **100% of seeded rule gaps** in the static corpus (run `npm run bench:tp` for the current seeded count; `npm run validate`'s rule-coverage gate prints the full corpus size). |
-| **Block-aware completeness** | An installed Block Factory block satisfies its declared baseline capabilities: `vise check` counts a checklist item as present with evidence `source: "block:<id>"` when the `sp-vise/blocks.json` entry declares it in `providesCapabilities` and the install is still locally valid (dependency declared, touched files present), and the gap returns on drift. Field-level SDK model facts (`sdk-surface/models.<platform>.json`, wire format `2026-06-10.sdk-model-facts.v1`) ship for all five platform surfaces, names-and-types on every grounded platform. |
-| **Packed-package smoke** | Packed-package and host-agent smokes exercise the release tarball path, surfaced plan questions, selected optional capability sensors, rejected design confirmation handling, and exact contract-rule evidence for shared product expectations. |
-
-### Supporting Proof
-
-| Surface | Safe claim | Evidence |
-|---|---|---|
-| **Feature completeness** | Vise helps agents build more of the expected SDK capability surface. | Latest comparison: **21-30% without Vise vs 97-100% with Vise**, with **98/99** expected feed capabilities implemented in aggregate. Earlier Capability Matrix work also showed silently dropped items falling from 7.67/11 to 4.0/11. |
-| **SDK compliance** | Vise checks catch greenfield SDK compliance gaps that docs or static guidance can miss. | Commune benchmark: Vise averaged **100% greenfield SDK compliance** where docs/RAG-style controls averaged **67%** across the reported slices. |
-| **Design conformance** | Vise design checks reduce design drift under ambiguous briefs. | Ambiguous Spotify-style design test: Vise design runs produced **0 / 0 / 0 hex literals** across three seeds; without Vise, runs varied **0 / 2 / 15**. This supports variance reduction, not pixel-perfect visual quality. |
-| **Candidate ranking calibration** | Vise can optionally preview `shadow-policy-v2-draft` ranking for surfaced creative variants, without changing default runtime recommendations. | Experience calibration track: **70 measured cells**. `shadow-policy-v2-draft` ranked the expected variant first in **21/21** cells, produced **14** improvement opportunities, has named product approval for **5** thin-margin event-first-over-creator-first cells plus named privacy approval for the benchmark evidence boundary, and is exposed only through explicit `--ranking-preview`. Current local dogfood has **18** prompts (ten archetypes, all **ten** variants — seven available, three gamification gated): of the **14** available-variant cases, **13** aligned and **1** declared near-miss (in the opt-in preview only; the keyword default and the agent both pick the human-correct variant), **0** undeclared ranking concerns, **0** candidate-surfacing gaps; the other **4** gamification cases are gated, and the paired positive control shows the preview correctly elevating the human-correct variant over the keyword default; default activation remains disabled. |
+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.
 
-### Why the workflow works
+**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.
 
-The benchmark story is the product flow:
+### Engagement Intelligence
 
-1. **Inspect** — Vise detects platform, app surface, SDK surface, sensors, and design signals from the local repo.
-2. **Plan** — Vise classifies the outcome, asks blocking intake questions, checks platform capability availability, and offers optional features only when the platform SDK surface supports them.
-3. **Confirm design** — `vise design extract` writes a preview; `plan`/`init` withhold design feed-forward until the user confirms `design_contract_confirmation=yes`.
-4. **Initialize** — `vise init` records the resolved compliance contract, intake answers, selected optional capabilities, inspection result, and accepted design digest.
-5. **Build / check / repair** — selected answers become sensors. The agent edits locally, runs `vise check`, fixes deterministic findings, resolves completeness gaps or selected-capability failures, and then runs project sensors.
+**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.
 
-Static docs can tell an agent what exists. Vise changes the stopping condition: the agent is not done until the local contract is green, attested, or blocked on explicit customer input.
+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.
 
-### How to read the evidence
+### Design contracts
 
-The benchmark suite is intentionally reported with boundaries:
+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.
 
-- **Latest feed-completeness comparison** is the current quantitative product claim for the opt-in capability flow. It is a best-case/opt-in comparison across Cursor, Claude, and Codex, not a universal result for every prompt.
-- **Capability Matrix v1** remains the pre-registered follow-up. It shipped the Row 2 feature-completeness claim, found **no Row 1 SDK-compliance claim** on chat/moderation/push under its registered margin, and withheld the Row 3 design claim on a technicality despite higher by-name token use.
-- **Commune Phase 1** remains useful historical evidence for the compliance loop: two agents reached 9/9 with Vise vs 5-7/9 under controls, but it was N=1 per cell and the grader overlaps Vise's own rules.
-- **Design tests** support design-drift reduction and token cleanup. They do not prove visual taste, pixel perfection, or production-ready UI without human review.
-- **Negative results must travel with the claim:** no measured Vise advantage on day-2 bug fixing; the push slice exposed a non-converging attestation loop when docs and SDK disagreed; earlier enumerative plan-time design guidance measured negative and was retracted; the original `scope-omit` affordance went unused in the matrix.
+## Evidence
 
-### Which mode should I use?
+Vise's measured effect is on **feed-feature completeness** — does the agent build the whole outcome (pagination, empty/error states, the optional capabilities you asked for) or just the happy path?
 
-| If you… | Use | Why |
-|---|---|---|
-| Building new social features with an AI agent | **Vise CLI + Skill** | This is the full governed workflow measured by the benchmarks. |
-| Auditing existing social.plus code | `vise check --ci` | Grades any codebase against the recorded compliance contract. |
-| Enforcing compliance in CI | `vise check --ci` | Exits non-zero on deterministic failures, missing baseline capabilities, failed selected optional sensors, blockers, or drift. |
+- **Like-for-like** (pre-registered, K=3 seeds, one firewalled ground truth): the Vise workflow **roughly doubled** feed-feature completeness over the docs-only baseline — to **58–64%** from **21–30%** — and the effect replicated across all three agents (Cursor/Composer 2.5 30→64%, Claude/Sonnet 4.6 27→61%, Codex/GPT-5.4 21→58%), evidence it's a property of the verification loop rather than one model. (Grading was deterministic-only in two of the three cells, which if anything understates the gap.)
+- **Best case** (the Vise arm explicitly opted into the optional capabilities up front; later build): with image/poll/edit selected, the Vise arm reached **97–100%** of the 11-item feed checklist across Cursor/Composer 2.5, Claude/Sonnet 4.6, and Codex/GPT-5.4. This is an opt-in best case, **not** the like-for-like delta above — the baseline arm was not offered the same selection and ran an earlier build.
+- **SDK compliance:** in a greenfield SDK-compliance benchmark (9 slices, single run per cell) the Vise verification-loop arm scored **9/9 (100%)** vs a docs-only baseline at **6/9 (67%)**. The durable finding is the mechanism — a checked loop beats the same rules pasted into the prompt.
+- **Design drift:** under an ambiguous brief (Sonnet, n=3), Vise design runs held hex-literal variance to **0** while the docs-only arm spiked to 15 on one stochastic seed — variance reduction on bad runs, not pixel perfection (a later pre-registered run saw both arms at 0; the robust signal is by-name token usage).
+- **Boundaries:** these are best-case/opt-in comparisons for greenfield social.plus work, self-reported (no third-party audit), 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.
 
----
+<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
 
@@ -227,180 +148,87 @@ The benchmark suite is intentionally reported with boundaries:
 | **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 rule checks fully operational (highest-risk rules use the Swift tree-sitter AST). Build sensor is **guarded best-effort**: an `.xcodeproj`/`.xcworkspace` enables an `xcodebuild -list` integrity probe plus a signing-disabled build — only when `xcodebuild` is on PATH (absent → skipped with the visible precondition). Environment-caused failures (no simulator runtime, Command-Line-Tools-only `xcode-select`, signing demands, unaccepted license) report **skipped-with-reason**, never project failure; a real build failure still exits non-zero. |
+| **iOS (Swift)** | ✅ Full | Static rules fully operational (tree-sitter AST for highest-risk rules); build sensor is guarded best-effort — runs only when `xcodebuild` is available, reports environment issues as skipped-with-reason, and still fails on real build errors |
 
 Each platform has dozens of rules across 10 compliance domains (feed, comments, moderation, chat, secrets, session & auth, notifications, live objects, logging hygiene, design tokens).
 
----
-
-## Installation
-
-### Install the CLI
-
-```sh
-npm install -g @amityco/social-plus-vise
-vise doctor                                # verify install
-```
-
-Or install per-project:
-
-```sh
-npm install -D @amityco/social-plus-vise
-npx vise --help
-```
-
-### Install the Skill Into Your Coding Tool
-
-The skill is what teaches your AI agent how to use Vise. Pick the matching host:
-
-| Host | Install command |
-|---|---|
-| Claude Code (personal scope) | `vise install-skill --target claude` |
-| Claude Code (project scope) | `vise install-skill --target claude-project .` |
-| OpenAI Codex | `vise install-skill --target codex` |
-| Cursor (native skills) | `vise install-skill --target cursor .` |
-| Cursor (legacy rules) | `vise install-skill --target cursor-rules .` |
-| GitHub Copilot / VS Code | `vise install-skill --target vscode .` |
-| Copilot CLI / project | `vise install-skill --target copilot .` |
-| Generic agent project | `vise install-skill --target agents .` |
-| Other coding agents | `vise print-skill` (paste output into the host's project instructions) |
-
-The skill is plain Markdown; you can read it any time with `vise print-skill`.
-
----
-
-## Usage Flow
-
-```mermaid
-flowchart LR
-    A[User asks AI agent<br/>'Add a social feed'] --> B[Agent runs<br/>vise inspect]
-    B --> C[Agent runs<br/>vise plan --request &quot;...&quot;]
-    C --> D{Blocking intake<br/>or design preview?}
-    D -->|Yes| E[Agent surfaces questions<br/>and opens design preview<br/>for user confirmation]
-    D -->|No| F
-    E --> F[Agent reruns plan/init<br/>with answers]
-    F --> G[Agent runs<br/>vise search-docs<br/>vise get-doc-page]
-    G --> H[Agent edits<br/>your code]
-    H --> I[Agent runs<br/>vise check]
-    I --> J{Green?}
-    J -->|No, fixable| K[Agent fixes<br/>findings, completeness gaps,<br/>or selected sensors]
-    K --> I
-    J -->|No, attest| L[Agent calls<br/>vise attest with<br/>evidence]
-    L --> I
-    J -->|Yes| M[Agent runs<br/>vise run-sensors]
-    M --> N[Done.<br/>sp-vise/ contract<br/>and evidence committed]
-```
-
-The flow above is what the skill teaches your AI agent. You — the human — drive intent, answer scope questions, and approve the design preview before Vise feeds a design contract forward. The agent runs Vise commands deterministically; Vise grounds the agent in real docs and real compliance rules. If blocking intake or design confirmation is still unresolved, `vise init` refuses to initialize, returns `status: "needs-clarification"`, and exits 7 so the agent must surface the questions instead of guessing.
-
----
-
 ## CLI Reference
 
-### Project inspection and planning
+Run `vise <command> --help` for full flags. JSON output is the default for agent-facing commands.
+
+### Inspect, plan, initialize
 
 | Command | Purpose |
 |---|---|
 | `vise doctor` | Verify install; print version, install path, docs source |
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
-| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Produce an advisory Engagement Intelligence brief with 2-3 solution variants before normal implementation planning; `--ranking-preview` also writes an opt-in local candidate-ranking preview without changing the candidate order |
-| `vise creative accept [path] --variant <id>` | Accept a creative variant and write `sp-vise/creative-selection.json` so subsequent `plan`, `init`, and `workplan` runs include the selected product/UX direction. Use `--variant none --rationale "<what is missing>"` to instead record a local `sp-vise/catalog-gap.json` no-fit signal for human catalog review |
-| `vise ux-harness [path]` | Generate or refresh `sp-vise/ux-harness.json` from the accepted creative selection; advisory UX expectations only |
-| `vise experience compile [path]` | Compile the accepted creative variant into `sp-vise/experience-compiler.json`: install guidance, navigation placement, surface plans, UX expectations, Block Factory bridge candidates, design adaptation, and validation commands |
-| `vise experience sensors [path]` | Write `sp-vise/experience-sensors.json`, an advisory sensor framework across technical, design, UX, accessibility, and business-alignment dimensions; no calibrated score yet |
-| `vise experience-report [path]` | Write `sp-vise/experience-report.json`, an advisory dimensioned report for technical compliance, design, UX Harness evidence, and business alignment; no calibrated single score yet |
-| `vise learning record [path]` | Append a local-only learning event for explicit feedback, outcome metrics, or report review; refreshes `sp-vise/learning-summary.json` |
-| `vise learning show [path]` | Read the local learning summary; recommendation ranking is not changed by these events yet |
-| `vise plan [path] --request "..."` | Produce a grounded implementation plan with intake questions and docs citations |
-| `vise plan-harness [path] --request "..."` | (Pre-planning step) Build the harness around the request |
-| `vise workplan next [path] --request "..."` | For broad social requests, print the next uncompleted surface plus focused `plan` / `init` / verification commands |
-| `vise workplan status [path] --request "..."` | Show the broad social workplan sequence and which surfaces are already marked complete |
-| `vise workplan complete [path] --request "..." --surface <id>` | Record a completed workplan surface after green `vise check`; writes progress to `sp-vise/workplan.json` and snapshots the active sidecar under `sp-vise/workplan-snapshots/<surface>/` |
-| `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract after blocking intake is answered; returns `needs-clarification` and exits 7 if required answers are missing |
-| `vise blocks list --registry <path>` | Read a social.plus Block Factory registry |
-| `vise blocks plan [path] --block <id> --registry <path>` | Plan safe block package, source-anchor, sidecar, and sensor changes |
-| `vise blocks add [path] --block <id> --registry <path> [--dry-run\|--apply]` | Dry-run or apply safe block installation inside a customer project |
-| `vise blocks validate [path] [--block <id>] --registry <path>` | Validate installed block sidecar state, package presence, and source anchors |
-
-### Design contract (UI generation)
+| `vise plan [path] --request "..."` | Grounded implementation plan with intake questions and docs citations |
+| `vise plan-harness [path] --request "..."` | Pre-planning step: build the harness around the request |
+| `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract once blocking intake is answered; exits 7 (`needs-clarification`) otherwise |
+| `vise workplan next [path] --request "..."` | For broad social requests: print the next uncompleted surface and its focused commands |
+| `vise workplan status [path] --request "..."` | Show the workplan sequence and completed surfaces |
+| `vise workplan complete [path] --request "..." --surface <id>` | Record a green-checked surface; snapshots evidence under `sp-vise/workplan-snapshots/<surface>/` |
+
+### Creative pre-planning (advisory)
 
 | Command | Purpose |
 |---|---|
-| `vise design extract <prototypePath> [--repo .] [--no-write]` | Read an HTML/CSS prototype and write a graded `sp-vise/design-contract.json` plus `sp-vise/design-preview.html` (declared CSS custom properties become exact tokens; repeated literals become inferred/advisory tokens; single-use literals are dropped) so generated social.plus UI can match the customer's aesthetic after preview confirmation |
-| `vise design extract --from-project [path] [--no-write]` | No external prototype? Derive the contract from the host project's **own** design system and write a preview — CSS custom properties (incl. shadcn `:root` and Tailwind v4 `@theme`), TS/JS token modules, inline tailwind configs, **Android** `colors.xml`/`dimens.xml`, **Flutter** `Color(0x…)`, and **iOS** `.xcassets/*.colorset` + Swift `Color(hex:)`/`Color(red:g:b:)`. Reference values (`var()`/`theme()`/`calc()`) are skipped, so a var-mapped config contributes nothing rather than wrong tokens |
-| `vise design check [path]` | Advisory, **non-blocking** report on how closely the UI code matches the contract (token coverage + on/off-contract color literals). Never fails a build and is **not** a `vise check` gate |
-| `vise design preview [path] [--reference <prototype>]` | Write a self-contained `sp-vise/design-preview.html`: the contract's tokens as visual swatches + the conformance report + the HTML reference embedded for side-by-side review. Vise renders the artifact; a human/VLM judges the visual match. Dependency-free — **not** an automated pixel diff |
-| `vise design reference [path] [--title <name>]` | Write a self-contained `sp-vise/design-reference.html`: human/VLM-readable design-system spec — token swatches, type samples, component demos, and a growth-layer summary. Pairs with `design-contract.json` (machine-readable). Use `--title` to name the design system (e.g. `--title Streamly`). Advisory — **not** an enforcement gate |
-| `vise design init-tokens [path] [--force]` | Scaffold `src/styles/social-plus-tokens.css` — the dedicated, customer-editable token file for social.plus features. **Greenfield:** neutral defaults (full `--sp-*` token set). **Brownfield:** seeded from your existing concrete tokens. Idempotent — never overwrites an existing file (use `--force` to override). After editing, run `vise design extract --from-project` to refresh the contract |
+| `vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview]` | Write an advisory Engagement Intelligence brief with candidate solution variants; `--ranking-preview` adds an opt-in, local-only ranking preview that never reorders the default candidates |
+| `vise creative accept [path] --variant <id>` | Record the selected variant so `plan`/`init`/`workplan` carry it forward; `--variant none --rationale "..."` records a catalog-gap signal instead |
+| `vise ux-harness [path]` | Generate advisory UX expectations from the accepted selection |
+| `vise experience compile [path]` | Compile the accepted variant into an implementation artifact plan |
+| `vise experience sensors [path]` | Write an advisory multi-dimension sensor framework (no calibrated score) |
+| `vise experience-report [path]` | Write an advisory dimensioned review report (no calibrated score) |
+| `vise learning record [path]` | Append a local-only learning event; refreshes the learning summary |
+| `vise learning show [path]` | Read the local learning summary (never changes recommendations) |
+
+Everything in this group is local and advisory: no uploads, no `vise check` exit-code changes, no auto-accepted variants, and no calibrated score until the calibration program graduates one.
+
+### Design contract
 
-The extracted contract is **advisory input for generation**, not an enforcement gate: a token-poor prototype yields a weaker — never wrong — contract, and absence of a prototype simply means no contract (the existing `*.design.reuse-detected-tokens` rules still cover reuse of a host project's own design system). A contract becomes feed-forward guidance only after the user confirms the preview with `--answer design_contract_confirmation=yes`; rejecting it with `=no` asks for a replacement design source and records no design-conformance digest.
+| Command | Purpose |
+|---|---|
+| `vise design extract <prototypePath> [--repo .] [--no-write]` | Extract a graded design contract + visual preview from an HTML/CSS prototype |
+| `vise design extract --from-project [path] [--no-write]` | Derive the contract from the project's own design system: CSS custom properties (incl. shadcn/Tailwind v4 `@theme`), TS/JS token modules, Android `colors.xml`/`dimens.xml`, Flutter `Color(0x…)`, iOS `.colorset`/Swift colors |
+| `vise design check [path]` | Advisory token-conformance report; never fails a build |
+| `vise design preview [path] [--reference <prototype>]` | Write a self-contained visual review (`sp-vise/design-preview.html`) for human/VLM judgment |
+| `vise design reference [path] [--title <name>]` | Write a self-contained design-system spec: swatches, type samples, component demos |
+| `vise design init-tokens [path] [--force]` | Scaffold `src/styles/social-plus-tokens.css` (greenfield defaults or seeded from existing tokens); idempotent |
 
-### Documentation grounding & Troubleshooting
+### Docs grounding & troubleshooting
 
 | Command | Purpose |
 |---|---|
 | `vise search-docs "<query>"` | Search social.plus docs for relevant pages |
 | `vise get-doc-page <path>` | Fetch a specific doc page by path |
-| `vise debug [path] --error "..." [--brief]` | Debug an SDK-specific runtime failure and emit a likely-cause summary plus a minimal repair brief |
+| `vise debug [path] --error "..." [--brief]` | Diagnose an SDK-specific runtime failure; `--brief` returns the likely rule, minimal patch shape, and verification commands |
 
 ### Compliance verification
 
 | Command | Purpose |
 |---|---|
-| `vise check [path]` | Re-validate against the recorded contract; reports `green`, `needs-attestation`, `deterministic-failures`, `blocked`, or `contract-drift` |
-| `vise check [path] --ci` | Same as `check`, but read-only and exits non-zero unless green (for CI pipelines) |
-| `vise validate [path]` | Run the deterministic validators (subset of `check` that doesn't compare against attestations) |
+| `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 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 customer-specific architecture that the deterministic check can't see |
-| `vise explain <ruleId>` | Print the rule's rationale, evidence requirements, and remediation guidance |
+| `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 |
+| `vise explain <ruleId>` | Print a rule's rationale, evidence requirements, and remediation |
 | `vise status [path]` | Summarize the current compliance state |
 
-### Sensors
+### Sensors, skill, engagement, server
 
 | Command | Purpose |
 |---|---|
-| `vise run-sensors [path]` | Run detected project scripts/wrappers (npm scripts, Gradle, Flutter, lint, typecheck, SDK import smokes); inspect with `--dry-run` before running in an untrusted project |
-| `vise run-sensors [path] --dry-run` | List what would run without executing |
-
-### Troubleshooting quick loop
-
-For SDK-specific runtime issues, start with the compact debug flow before broader repo exploration:
-
-```sh
-vise debug . --error-file logs/crash.log --brief
-vise check . --ci
-vise run-sensors .
-```
-
-`vise debug --brief` returns the likely rule, minimum patch shape, invariants to preserve, and verification commands for the first repair pass.
-
-### Skill management
-
-| Command | Purpose |
-|---|---|
-| `vise install-skill --target <host>` | Install the bundled skill into a coding host (see [Installation](#installation)) |
+| `vise run-sensors [path] [--dry-run]` | Run detected project scripts (npm, Gradle, Flutter, lint, typecheck, SDK smokes); `--dry-run` lists without executing |
+| `vise install-skill --target <host>` | Install the bundled skill into a coding host (see [Quick Start](#quick-start)) |
 | `vise print-skill` | Print the skill markdown to stdout |
-
-### Engagement scope (optional contractual metadata)
-
-| Command | Purpose |
-|---|---|
-| `vise engagement init [path] [--tier ...] [--customer-id ...] [--scope ...]` | Record the contractual scope for this integration |
+| `vise engagement init [path] [--tier ...] [--customer-id ...] [--scope ...]` | Record optional contractual scope metadata |
 | `vise engagement show [path]` | Print the recorded engagement metadata |
-
-### MCP server
-
-| Command | Purpose |
-|---|---|
 | `vise mcp` | Start the stdio MCP compatibility adapter |
 
----
-
 ## MCP Integration
 
-MCP-capable hosts can call Vise as structured tool calls instead of shell commands.
-
-### Config
+MCP-capable hosts can call Vise as structured tool calls instead of shell commands:
 
 ```json
 {
@@ -413,17 +241,13 @@ 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_preview`, `design_reference`, `design_init_tokens`.
+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_preview`, `design_reference`, `design_init_tokens`.
 
-These are the same operations as the CLI commands above, exposed as MCP tools. `get_sdk_facts` is also registered as the internal, read-only Block Factory SDK-facts provider tool (it inspects no customer project — see [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md)). The adapter still answers the legacy `resolve_request` and `suggest_patch` names for backward compatibility, but they are deprecated in favour of `plan_integration` plus host-tool edits.
-
----
+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.
 
 ## CI Compliance
 
-Add `vise check --ci` to your CI pipeline after committing `sp-vise/compliance.json` to your repository:
+Commit `sp-vise/` to your repository, then add `vise check --ci` to your pipeline:
 
 ```yaml
 name: Vise Compliance
@@ -445,53 +269,46 @@ jobs:
       - run: vise check . --ci
 ```
 
-**Exit codes:**
+`vise check --ci` is read-only — it never updates `sp-vise/` — and its JSON output includes a structured `ci` block for pipeline logs.
 
-| Code | Meaning |
+| Exit code | Meaning |
 |---|---|
-| `0` | All rules pass, all baseline capabilities are present or opted-out, and any selected optional capabilities pass |
+| `0` | All rules pass; baseline capabilities present or opted-out; selected optional capabilities pass |
 | `1` | One or more rules need attestation |
 | `2` | One or more rules have deterministic failures |
 | `3` | One or more blockers fired (missing prerequisite, e.g. `google-services.json`) |
-| `4` | Contract drift — rules in `sp-vise/compliance.json` no longer match the current ruleset |
-| `5` | One or more baseline capabilities are neither implemented nor validly opted-out — add the capability or place `// vise: scope-omit <id> — <reason>` |
-| `6` | One or more explicitly selected optional capabilities failed source sensors |
-
-`vise check --ci` is read-only. It never updates `sp-vise/`. The JSON output includes a `ci` block with structured details for pipeline logs.
-
----
+| `4` | Contract drift — recorded rules no longer match the current ruleset |
+| `5` | Baseline capability neither implemented nor opted-out (add it or place `// vise: scope-omit <id> — <reason>`) |
+| `6` | An explicitly selected optional capability failed its source sensors |
 
 ## Compliance Contract
 
-Vise writes local planning, compliance, design, and evidence artifacts under `sp-vise/`. `vise creative` can create advisory creative-brief files before implementation; after a successful `vise init`, the compliance contract files are added. If init returns `needs-clarification`, no compliance sidecar is written; answer the blocking questions and run init again. These files become part of your repo and travel through code review:
+Vise writes local planning, compliance, design, and evidence artifacts under `sp-vise/`. These files become part of your repo and travel through code review — **commit them**. `vise check` re-validates against the recorded contract on every run, so a code change that breaks a rule surfaces as `deterministic-fail`, `attestation-needed`, or `blocked` — never a silent regression.
 
 | File | Created by | What it contains |
 |---|---|---|
-| `sp-vise/compliance.json` | `vise init` | The rules selected for this integration, the Vise version, the ruleset digest, the target app surface, selected optional capabilities, optional engagement link, and an accepted design-contract digest when confirmed. |
-| `sp-vise/intake.json` | `vise init` | The request, outcome, intake answers, remaining blocking count, optional creative-selection mirror, design-review status (`absent`, `needs-confirmation`, `accepted`, or `rejected`), and any retrospective `--allow-unresolved-intake` acknowledgement. |
-| `sp-vise/creative-brief.json` | `vise creative` | Advisory Engagement Intelligence brief: mode, objective, inferred goals/archetypes, candidate solution variants, feasibility summary, preferred-solution question, and next plan/workplan commands. |
-| `sp-vise/creative-brief.md` | `vise creative` | Human-readable version of the creative brief for review with the user before selecting a variant. |
-| `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local advisory ranking preview for the surfaced creative candidates using `shadow-policy-v2-draft`; preserves the original candidate order and writes `experience_score: null` with runtime boundary fields confirming no uploads, no auto-acceptance, and no default ranking change. |
-| `sp-vise/creative-selection.json` | `vise creative accept` | Accepted creative variant: source brief, selected goals/archetypes/patterns/objects/UX patterns, surface hints, feasibility notes, and plan/workplan feed-forward context. |
-| `sp-vise/catalog-gap.json` | `vise creative accept --variant none` | Recorded no-fit: the request the agent found no fitting variant for, what the catalog is missing, the nearest existing variant, and the grounding signal. A local-only signal for human catalog review — it does not accept a variant, change the catalog, or upload anything. |
-| `sp-vise/ux-harness.json` | `vise creative accept` or `vise ux-harness` | Advisory UX Harness: selected UX pattern expectations, tradeoffs, anti-patterns, surface expectations, and capability-feed-forward boundary notes. |
-| `sp-vise/experience-compiler.json` | `vise experience compile` | Advisory implementation artifact plan: install guidance, navigation placement, focused surface plans, UX expectations, optional Block Factory bridge candidates, design adaptation, and validation commands. |
-| `sp-vise/experience-sensors.json` | `vise experience sensors` | Advisory sensor framework: technical, design, UX, accessibility, and business-alignment evidence summary, review gaps, commands, and `score: null` until calibrated. |
-| `sp-vise/experience-report.json` | `vise experience-report` | Advisory dimensioned review artifact: technical compliance status, design contract presence, UX Harness evidence, business alignment, optional Experience Sensor snapshot, and `score: null` until calibrated by benchmark/dogfood evidence. |
-| `sp-vise/learning-events.jsonl` | `vise learning record` | Append-only local learning event log for explicit customer/reviewer feedback, outcome metrics, selected variant snapshots, outcome snapshots, Experience Report snapshots, and Experience Sensor snapshots. |
-| `sp-vise/learning-summary.json` | `vise learning record` | Derived local learning summary: feedback counts, variant feedback, metric keys, report/sensor snapshots, recurring review gaps by variant/outcome/dimension, and `recommendationOptimization.status: "not-active"`. |
-| `sp-vise/attestations/*.json` | `vise sync` (deterministic) or `vise attest` (host-agent / human) | Per-rule evidence: signer, confidence, rationale, cited files (with source fingerprints for drift detection). |
-| `sp-vise/inspection.json` | `vise init` | The platform, monorepo surface, and design-token signals detected at init time. |
-| `sp-vise/workplan.json` | `vise workplan complete` | Local progress for broad social workplans: request, completed surface IDs, outcomes, timestamps, green-check evidence, snapshot paths, and optional host-agent notes. |
-| `sp-vise/workplan-snapshots/<surface>/` | `vise workplan complete` | Per-surface compliance/check snapshots copied from the active sidecar so later focused surfaces can overwrite `sp-vise/compliance.json` without erasing earlier proof. |
-| `sp-vise/design-contract.json` | `vise design extract` | The extracted design contract: declared tokens, breakpoints, advisory components, source file digests (for freshness detection), and a stable digest over design facts. |
-| `sp-vise/design-preview.html` | `vise design extract` or `vise design preview` | Self-contained visual review of the design contract, embedded prototype when available, token swatches, and design-check conformance summary. Open this before answering `design_contract_confirmation`. |
-| `sp-vise/design-reference.html` | `vise design reference` | Self-contained HTML design-system spec (token swatches, type samples, components). Human/VLM-readable; open in a browser alongside the app. |
-| `sp-vise/engagement.json` | `vise engagement init` (optional) | Contractual scope: tier, customer ID, contracted outcomes, reviewer assignment. |
-
-**Commit `sp-vise/` to your repo.** `vise check` re-validates against the recorded contract on every run, comparing current code against the recorded attestations. If code changes and breaks a rule, the next `check` reports `deterministic-fail`, `attestation-needed`, or `blocked` — never a silent regression.
-
-If a rule passes through customer-specific architecture the validator can't see (a DI wrapper, an unconventional file layout, etc.), record an attestation:
+| `sp-vise/compliance.json` | `vise init` | Selected rules, ruleset digest, app surface, selected optional capabilities, accepted design digest |
+| `sp-vise/intake.json` | `vise init` | Request, outcome, intake answers, design-review status |
+| `sp-vise/inspection.json` | `vise init` | Platform, surface, and design signals detected at init |
+| `sp-vise/attestations/*.json` | `vise sync` / `vise attest` | Per-rule evidence: signer, confidence, rationale, source fingerprints for drift detection |
+| `sp-vise/creative-brief.json` + `creative-brief.md` | `vise creative` | Advisory brief: goals, archetypes, candidate variants (JSON + human-readable) |
+| `sp-vise/candidate-ranking-preview.json` | `vise creative --ranking-preview` | Opt-in local ranking preview; `experience_score: null`, no uploads, no default-order change |
+| `sp-vise/creative-selection.json` | `vise creative accept` | Accepted variant and plan/workplan feed-forward context |
+| `sp-vise/catalog-gap.json` | `vise creative accept --variant none` | Local-only no-fit signal for human catalog review |
+| `sp-vise/ux-harness.json` | `vise creative accept` or `vise ux-harness` | Advisory UX pattern expectations and anti-patterns |
+| `sp-vise/experience-compiler.json` | `vise experience compile` | Advisory implementation plan: install guidance, surfaces, validation commands |
+| `sp-vise/experience-sensors.json` | `vise experience sensors` | Advisory sensor framework; `score: null` until calibrated |
+| `sp-vise/experience-report.json` | `vise experience-report` | Advisory dimensioned review; `score: null` until calibrated |
+| `sp-vise/learning-events.jsonl` | `vise learning record` | Append-only, local-only learning event log |
+| `sp-vise/learning-summary.json` | `vise learning record` | Derived summary; `recommendationOptimization.status: "not-active"` |
+| `sp-vise/workplan.json` | `vise workplan complete` | Broad-request progress: completed surfaces, green-check evidence |
+| `sp-vise/workplan-snapshots/<surface>/` | `vise workplan complete` | Per-surface snapshots so later focused surfaces don't erase earlier proof |
+| `sp-vise/design-contract.json` | `vise design extract` | Extracted tokens, breakpoints, source digests, stable design digest |
+| `sp-vise/design-preview.html` | `vise design extract` / `preview` | Self-contained visual review; open before answering `design_contract_confirmation` |
+| `sp-vise/design-reference.html` | `vise design reference` | Self-contained design-system spec (swatches, type, components) |
+| `sp-vise/engagement.json` | `vise engagement init` (optional) | Contractual scope: tier, customer ID, outcomes, reviewer |
+
+If a rule passes through customer-specific architecture the validator can't see (a DI wrapper, an unconventional layout), record an attestation:
 
 ```sh
 vise attest . \
@@ -502,27 +319,20 @@ vise attest . \
   --rationale "Region is read from NEXT_PUBLIC_AMITY_REGION env var in lib/amity.ts:6"
 ```
 
-Attestation files record source fingerprints (SHA-256 of cited files) so subsequent edits invalidate stale attestations.
-
----
-
-## Changelog
-
-See [`CHANGELOG.md`](./CHANGELOG.md) for the full version history.
-
----
+Attestations record SHA-256 source fingerprints of cited files, so later edits to those files invalidate the attestation automatically.
 
 ## Support
 
-- **Bugs / feature requests:** contact your social.plus account team or file an issue with your integration partner.
-- **Documentation:** [https://learn.social.plus](https://learn.social.plus)
-- **Skill installation issues:** `vise doctor` prints diagnostic info; share the output with support.
-
----
+- **Documentation:** [https://learn.social.plus](https://learn.social.plus) — the same corpus `vise search-docs` grounds agents in.
+- **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 [`LICENSE`](./LICENSE) for terms. 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.
 
 ---