@amityco/social-plus-vise 0.14.28 → 1.0.1

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,213 +16,98 @@
 
 ---
 
-## 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)
-```
+## What is Vise?
 
-**Step 3 in practice:** Open your AI coding tool in your project and prompt:
+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.**
 
-> "Add a social feed to this app using the social.plus SDK."
+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.
 
-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.
+> **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.
 
-See [Usage Flow](#usage-flow) for the full step-by-step diagram.
-
----
-
-## What Vise Does: Agentic Workflow Governance
-
-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.
-
-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.**
-
-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.
-
-```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 has two deliberately separate roles:
-
-- **Customer integration helper:** runs inside customer projects to inspect, plan, validate, and sensor-check social.plus SDK integrations.
-- **Block Factory SDK facts provider:** internal mode for social.plus Block Factory to verify SDK capabilities, symbols, and model schemas before reusable blocks are generated or released.
-- **Block installer governance:** customer-project workflow that consumes a Block Factory registry, plans safe package/source changes, writes `sp-vise/blocks.json`, and validates installed block state.
-
-Vise owns SDK truth and customer-project governance. social.plus Block Factory owns block contracts, package adapters, registry metadata, previews, conformance tests, and release readiness. See [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md) for the internal provider-side plan.
-
-### 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."
-
-The agent uses Vise to turn that request into a governed install workflow:
+## Quick Start
 
 ```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"
-
-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.
-
----
+# 1. Install the CLI
+npm install -g @amityco/social-plus-vise
+vise doctor                                # verify install
 
-## Benchmark Results: Current Claim
+# 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
 
-> **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.**
+# 3. Open your AI coding tool in your project and ask:
+#    "Add a social feed to this app using the social.plus SDK."
+```
 
-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.
+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).
 
-### Latest Quantitative Benchmark
+All skill targets:
 
-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.
+| 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) |
 
-| 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. |
+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`.
 
-Aggregate: **98/99 expected feed capabilities** and **27/27 selected optional capabilities** implemented across the Vise arm.
+## How it works
 
-### Current Release Validation
+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.
 
-Version 0.14.26 carries current release proof around the full feed-forward, product-expectation, creative pre-planning, and validation flow:
+### Three validation layers
 
-| 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 **321/321 seeded rule gaps (100.0%)** in the static corpus. |
-| **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. |
+The layer is set by the *kind of claim*, which keeps Vise false-positive-free where it gates:
 
-### Why the workflow works
+| 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 |
 
-The benchmark story is the product flow:
+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.
 
-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.
+**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.
 
-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.
+### Design contracts
 
-### How to read the evidence
+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.
 
-The benchmark suite is intentionally reported with boundaries:
+## Evidence
 
-- **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.
+Feed-completeness benchmark — same feed request, same SDK docs, with and without the Vise workflow (Vise arm explicitly selected optional capabilities):
 
-### Which mode should I use?
+| 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) |
 
-| 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. |
+Aggregate: **98/99** expected feed capabilities and **27/27** selected optional capabilities implemented across the Vise arm.
 
----
+- **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.
 
 ## Supported Platforms
 
@@ -232,180 +117,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) |
 
-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.
+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.
 
-### Documentation grounding & Troubleshooting
+### Design contract
+
+| 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 |
+
+### 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
-
-| 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
+### Sensors, skill, engagement, server
 
 | 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
 {
@@ -418,17 +210,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`, `resolve_request`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `suggest_patch`, `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.
-
----
+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
@@ -450,53 +238,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 . \
@@ -507,27 +288,18 @@ 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
 
+- **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.
-- **Documentation:** [https://learn.social.plus](https://learn.social.plus)
-- **Skill installation issues:** `vise doctor` prints diagnostic info; share the output with support.
-
----
+- **Skill installation issues:** `vise doctor` prints diagnostics; share the output with support.
+- **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. social.plus Vise is provided to social.plus customers and integration partners under the same agreement as the social.plus SDK.
 
 ---