What is Vise?

Preview release. Vise is usable for guided social.plus SDK integrations, but the CLI surface, evidence format, benchmark methodology, and advisory intelligence may still change as the product hardens through more real projects. Treat it as governed AI assistance with strong validation gates, not a substitute for code review, product QA, or runtime verification.

Vise wraps your AI coding agent in compliance guardrails while it integrates social.plus SDKs. The agent still writes the code — Vise grounds that work in real SDK APIs, checks correctness and completeness, helps align generated UI with your design system, and asks you the calls only a human should make. It does not make AI agents perfect; it gives them a governed loop, explicit gates, and evidence when something is green, intentionally scoped out, or still unverified.

While the agent works, Vise:

• 🧠 Grounds it in the real SDK — extracted, source-anchored facts (real types and field names), so it won't invent a symbol or field the SDK doesn't expose, and pins the version published on npm.
• 🛡️ Enforces 400+ platform-specific checks — the mistakes that pass a demo and break in production.
• ✅ Gates feature completeness — the whole outcome (pagination, empty/error states, the capabilities you asked for), not just the happy path.
• 🎨 Reviews generated UI against your design system — advisory, because brand fit still needs human judgment.
• 🔧 Runs your project's own build / lint / typecheck sensors.

It turns the request into a grounded plan, records a local contract under sp-vise/, and keeps checking until the integration is green, attested, intentionally scoped, or explicitly blocked on your input — so the handoff distinguishes finished work from unverified work instead of treating "the agent stopped" as "done".

🔒 Vise itself does not upload your source code. Your AI coding host follows its own data policy; Vise fetches only the public social.plus docs and the SDK's published version on npm — never your code, file contents, or search queries. VISE_DOCS_OFFLINE=1 runs fully offline.

Vise can also run ahead of that loop: an advisory Engagement Intelligence layer turns a product goal into multiple candidate engagement strategies — what you might build, not only whether you built it right.

Why "Vise"? A bench vise holds the workpiece steady so the craftsman's hands are free to shape it. Vise clamps the integration to the real docs, the real project structure, and the real compliance rules so the agent can focus on building instead of guessing.

It ships as three layers:

| Layer | Purpose | |---|---| | 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 hosts (Claude Code, Cursor, Codex, VS Code, Copilot) |

Quick Start

New to social.plus? Vise integrates the social.plus SDK. To adopt social.plus, talk to our team. Existing customers get their API key + region from the social.plus Console and can follow the SDK getting-started guide. You can install Vise and explore vise inspect/vise plan before you have credentials.

Runtime requirement: Vise requires Node.js 20 or newer. Run node --version before installing if you are unsure which runtime your terminal or CI environment uses.

# 1. Install the CLI
npm install -g @amityco/social-plus-vise
vise doctor                                # verify install

# 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."

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 sign off the blueprint (what gets built) before the agent writes a line; Vise keeps the agent honest. For high-confidence handoff, also launch the app in its real browser, simulator, emulator, or device target and verify the selected social surface with real data. See How it works.

All skill targets:

| 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) |

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.

How it works

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. If the request is too vague to classify, it returns a structured clarify block. If it explicitly names a capability unavailable on the detected platform, it returns supportLevel: "unsupported", a grounded platformAvailability explanation, and stop/alternative steps instead of implementation guidance. For a broad goal it expands the outcome into a blueprint — the surfaces and experience it proposes to build. Use --summary when you only need the route/intake readout before implementation. The agent surfaces questions; you answer.
3. Initialize — vise init writes the sp-vise/ compliance contract. It accepts a reviewed organization Policy Pack directly (--policy-pack, plus --trust-policy for a signed envelope) or a human-reviewed pre-registered Outcome Measurement Plan (--measurement-plan); an initialized repository may later adopt controlled Policy Operations with vise policy accept. For a multi-surface build (a journey spanning more than one surface), init first makes you sign off the blueprint: the what — the solution path (sdk / uikit / hybrid / managed-placement), the experience/surfaces to build, and their cross-surface placement/read/write relationships. A community + feed blueprint, for example, binds the feed and composer to the selected community-detail route instead of accepting two disconnected tabs. This is the alignment gate — "are we building the right thing?" — the human-judgment counterpart to the deterministic compliance gate ("did we build it the right way?") in step 5. init refuses and exits 7 until the request is resolved: status: "needs-clarification" when intake is unanswered or the request can't be classified, and status: "needs-blueprint-confirmation" until the blueprint is signed (--answer blueprint_confirmation=<digest>). The sign-off can't be bypassed, and it re-arms if the path, journey or relationship, design source, accepted policy/trust, or measurement intent changes.
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.
7. Launch and verify — for any user-visible handoff, ask before spending browser/simulator/emulator/device resources. If approved, open the actual target, check the selected journey, and record what data was discovered or created. Discover targets naturally from host app state, SDK queries, user selection, or SDK create-flow return values; if the tenant has no data, prepare Console data or seed safe sample data before calling the surface populated. When a sp-vise/smoke.json contract exists, run vise smoke against captured logs; expect: "populated" requires loaded count=N with N > 0. For a route-specific surface, declare its route and target with vise smoke declare and emit the same non-sensitive values in the marker—for example VISE_SMOKE surface=community-feed route=community-detail target=community state=loaded count=3. For release evidence, add a strict --receipt-context and verify the scoped result with vise smoke verify; this binds source/build/runner/artifact and prior Passport lineage without merging marker, visual, static, and approval claims. Vise retains only normalized VISE_SMOKE markers, so keep the full browser/device console ephemeral, and actually inspect every final screenshot at readable resolution before treating its pixels as proof. If runtime proof genuinely can't be produced — the user declines to spend device/emulator resources, or the environment is deviceless — record an honest waiver with vise smoke waive (rather than leaving a live surface red-forever or faking evidence); vise check then reports runtime-proof-waived as an explicit under-claim. If launch verification is skipped, say what remains unverified.

Solution path routing (advisory)

Some requests are better served by social.plus UIKit (prebuilt social surfaces) than by hand-rolling standard UI directly from SDK primitives. vise plan emits an advisory solutionPath — sdk, uikit, hybrid, managed-placement, or needs-decision — so an agent can pause before it builds the wrong layer. Managed Placement is explicit-selection-only: request text never auto-selects it; use --answer solution_path=managed-placement after reviewing the one-host, remote-delivery path. Existing vise blocks integrations remain supported. A request that rejects UIKit routes SDK-first, while genuinely mixed UIKit/SDK intent resolves to needs-decision rather than silently picking one.

When UIKit is in play, vise plan can also emit uikitCustomization, recommending the lowest-effort customization tier that meets the goal — Dynamic UI → Component Styling → Localization → Behavior Overrides → Fork and Extend → SDK Custom UI. Both signals are advisory only: they never change outcome classification, compliance rules, the sidecar schema, or vise check exit codes.

Three validation layers

The layer is set by the kind of claim, which is how Vise avoids treating "looks plausible" as "ready to ship." The current package covers all three layers across supported platforms: compliance and completeness are enforced by vise check, while design conformance is available as an advisory review loop.

| Layer | Claim | How | Enforcement | |---|---|---|---| | SDK compliance | "this is wrong" | 400+ deterministic checks (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 |

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.

App launch verification is the final acceptance step outside these three layers. vise check and vise run-sensors can prove structure, completeness, and local build commands; a browser or native launch confirms the selected user journey is actually visible.

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.

Vise's versioned capability contract also governs finer feature families—including search, user profiles, advanced chat, rich post creation, channel archive, presence, and room-based livestreaming—per platform. It filters unsupported options from generic plans and completeness checks, while an explicit unsupported request stops before code edits with documented alternatives. This is a reviewed support boundary backed by bundled SDK symbols and model fields; it does not widen exact SDK-version assurance or replace runtime verification.

Those bundled facts now carry a machine-readable reviewed-promotion receipt, complete-surface digest, provenance, 30-day freshness objective, and a versioned five-platform fact-depth assessment. Field-level targets and existing native gaps are explicit; loss of a reviewed minimum or an unknown state blocks promotion even when a symbol still exists. Maintainers can validate one upstream-selected release across all five SDK families, atomically normalize its checksum-bound extraction bundle into candidate knowledge, generate a deterministic impact proposal, and promote only a separately reviewed, evidence-complete exact digest; customers, Day-2 impact, Passports, Governed Release Review, and social.plus blocks all consume the resulting assurance. See docs/SDK_CANDIDATE_INTAKE.md, docs/SDK_KNOWLEDGE_PROMOTION.md, and docs/SDK_FACT_DEPTH.md.

Organization Policy Packs

Policy Packs add explicit organization requirements without changing Vise's global truth. A versioned local JSON file may constrain approved SDK ranges, required proof classes and baseline capabilities, runtime-waiver ownership/scope/expiry, and release severity/owners. Organization conventions can travel in the same file, but remain advisory and never become hidden compliance gates.

# Review policy-packs/example.json, copy/adapt it inside the customer repo, then accept exactly once.
vise init . --request "Set up the social.plus SDK" --policy-pack config/vise-policy.json

# Later reads reuse the accepted path and digest.
vise impact .
vise sdk-release .
vise passport . --write

Selection is never automatic. Supplying --policy-pack to a read command previews it; only vise init --policy-pack accepts it into sp-vise/compliance.json. If the file changes, Day-2 analysis reports the selection stale and ordinary init refuses until a person reviews and explicitly re-accepts the new digest. The pack itself stays in its original repo-relative location and becomes a required, hash-bound Passport artifact.

An approved organization range does not widen Vise's extraction-grounded exact SDK assurance. Likewise, a policy-allowed waiver remains an explicit absence of runtime proof. See docs/POLICY_PACKS.md, the shipped policy-packs/v1.schema.json, and policy-packs/example.json.

Signed distribution is optional. vise trust sign can wrap a reviewed Passport or Policy Pack with a caller-supplied external Ed25519 key; vise trust verify and verify_trust_envelope authenticate it against an explicit local trust policy. Vise never stores private keys or discovers trust remotely. Accept a signed pack with both --policy-pack <envelope> and --trust-policy <policy>; Day-2 operations then re-verify and bind both artifacts. See docs/PORTABLE_TRUST_ENVELOPES.md.

For repository fleets, Organization Policy Operations v1 adds one strict local source manifest around those existing contracts. vise policy status / assess_policy_operations report source drift, deterministic update impact, lifecycle expiry/supersession/revocation, signed-key authorization/rotation/revocation, and exact owner routing. vise policy accept pins the reviewed source and writes a local audit receipt without rewriting policy inputs or asserting release approval. vise check --ci automatically preserves ready, review-required (exit 12), and blocked (exit 13) policy decisions. There is no remote discovery, hosted custody, or automatic acceptance. See docs/POLICY_OPERATIONS.md.

A pack's static-compliance requirement evaluates the full active project, not the brownfield vise check --new-only change gate. A change can therefore pass --new-only while the organization verdict remains non-compliant because of visible legacy debt; the two results answer different release questions.

Outcome Measurement Plans

When a team knows how it intends to evaluate an experience, it can pre-register one aggregate metric before observation starts. A strict local JSON file declares the metric identity and definition, desired direction and tolerance, source category, baseline/observation windows, accountable roles, and explicit human review/consent. It contains no metric values or raw analytics data.

vise init . --request "Build a community participation experience" \
  --measurement-plan config/outcome-measurement-plan.json
vise impact .
vise passport . --write

Vise binds the normalized plan to the accepted engagement, outcome, solution path, confirmed blueprint, and selected variant. An unchanged same-intent plan is reused with its original registration time; changed input or intent requires explicit re-acceptance and still cannot be registered after observation begins. Day-2 impact reports preservation, absence, and drift without mutation. Passports bind the reviewed input and normalized plan, and Outcome Evidence must conform exactly when a plan exists. Existing projects without a plan remain compatible and are labeled unplanned-backward-compatible rather than receiving a false pre-registration claim.

Vise does not fetch analytics, store raw customer data, prove causality, score or rank experiences, upload evidence, aggregate learning, or make product decisions. See docs/OUTCOME_MEASUREMENT_PLAN.md and the shipped docs/outcome-measurement-plan-input.schema.json.

Engagement Intelligence

Advisory, in preview. The three layers above answer whether you built it right. Ahead of the build, Vise can also help reason about what to build: an Engagement Intelligence layer turns a product goal into multiple candidate engagement strategies — archetypes, UX patterns, and solution variants drawn from a social.plus experience catalog — with rationale, tradeoffs, no-fit guidance, availability limits, and review gaps. The driving agent presents the EI choice as a visible decision — recommended experience, concrete fit signals, credible alternatives, tradeoffs, expected blueprint surfaces, and no-fit option — before it accepts a variant. The human or driving agent still chooses the direction, then Vise compiles that selected variant into an implementation plan (vise creative → vise creative accept → vise experience compile), optionally bridging to installable social.plus blocks, plus advisory UX expectations and a multi-dimension experience review.

It is local-only, never uploads, carries no calibrated score, and never changes vise check's exit codes. The opt-in ranking preview is review context, not a top-1 confidence claim or autonomous product-strategy selector. Use it to shape the work; the validation layers still decide when it's done.

Design contracts

Vise can ingest your aesthetic from an HTML/CSS prototype (vise design extract) or from the host app's own design system across web, Android, Flutter, and iOS (vise design extract --from-project). The contract is advisory input for generation, never an enforcement gate, and it feeds forward into plans only after you confirm the generated preview with --answer design_contract_confirmation=yes — and on a multi-surface blueprint that confirmation is folded into the single blueprint sign-off, so you approve the design once for the whole journey rather than per surface. For social.plus-specific styling, vise design init-tokens scaffolds a dedicated, customer-editable token file (src/styles/social-plus-tokens.css) — edit it, re-extract, and future builds inherit the palette with no agent in the loop.

Evidence

We put Vise through the same brownfield social.plus integration twice per platform — once through the governed Vise workflow, once from a structured checklist with Vise switched off (the control) — across five platform families, on a live tenant with no mocking. The precise, uniform benchmark is Claude Sonnet 5; we cross-checked the direction with a second agent, OpenAI Codex GPT-5.4. Read the direction, not the decimals.

Anchor: Claude Sonnet 5, per platform

Composite score, 0–100 shared scale; every control built and launched.

| Platform | Fixture | Vise | no-Vise | Δ | |---|---|--:|--:|--:| | Web | PULSE / pulse-studio | 88.3 | 56.8 | +31.5 | | React Native | Arena Fit | 89.7 | 62.1 | +27.6 | | iOS | Luminary Club | 77.5 | 48.0 | +29.5 | | Android | MarketPulse | 77.5 | 50.1 | +27.4 | | Flutter | Fieldhouse | 78.0 | 48.5 | +29.5 | | Average | 5 fixtures | 82.2 | 53.1 | +29.1 |

That +29.1 full composite still carries the +90 definitional capability axis (the control scores 0 there by construction). Drop it and re-weight the four fair dimensions to 100%:

| | Vise | no-Vise | Δ | |---|--:|--:|--:| | Full weighted composite (incl. capability axis) | 82.2 | 53.1 | +29.1 | | Credible-only (capability axis removed) | 83.0 | 70.8 | +12.1 |

+12.1 is the number to stand behind. It comes from Product outcome +17.6 and Design integration +15.8 (the credible wins); Runtime hygiene is a near-tie (+1.9 — build/launch cleanliness, which a capable agent clears either way; on Android the checklist control actually built cleaner — this is not SDK-rule compliance, see below); Efficiency +11.7 is a scorer budget metric (the governed arm is slower in real time, ~2.7× on web); Capability activation +90 is definitional, kept out of the headline. (Deltas use unrounded composites, so hand-subtracting rounded cells can differ by 0.1.)

Why the hygiene dimension is near-parity — and why that isn't the whole story. The scorer's correctness dimension measures runtime hygiene (build, launch, no crashes/secrets/hardcoded IDs), which strong agents clear with or without Vise. It is not SDK-rule compliance — the thing the 400+ deterministic rules govern. That is measured directly by a separate compliance-findings metric (vise validate on both arms' produced source): an ungoverned control carries real rule violations a smoke test never surfaces, and its runtime symptoms already show up as the product-outcome gap above.

Cross-check: OpenAI Codex GPT-5.4 (directional)

The same A/B run with Codex points the same way — Vise ahead on every platform. Codex's exact figures are directional, not precise: its no-Vise controls are high-variance — on Android a single control has read anywhere from +63 (an unlucky, instrument-affected run on the earlier harness) down to +27 (clean). Run cleanly on the hardened harness (Android and iOS N=3; Flutter one clean launch, the rest watchdog-blocked), Codex's controls land ~65 and its lift settles around +25–30, converging with Sonnet's. Honest cross-model read: both agents show Vise winning by ~+25–30 once controls are run cleanly. We anchor on Sonnet because it is the uniform, current-harness run; Codex is cross-model confirmation of direction.

Methodology & caveats

• Vise is the deterministic CLI under test, not an AI model. Each arm runs the same coding agent on the same brownfield fixture, live tenant, no mocking.
• Scoring weights: capability activation 25% (definitional), product outcome 25%, design integration 20%, runtime hygiene 20% (the scorer's correctness key — build/launch cleanliness, not SDK-rule compliance), efficiency 10%. A separate compliance-findings metric (vise validate on both arms) measures SDK-rule adherence directly. The credible-only composite drops the capability axis and re-weights the other four to 100%.
• Small-N, directional. Controls are n = 1–3 per arm, so neither model is a precise second measurement, and the two are not directly comparable (Codex ran on an earlier harness). The runtime-signal scorer that could over-credit a rendered-but-broken shell is now gated. July 2026 product-evidence runs on representative fixtures — not a third-party audit. For a formal comparison, keep each Vise / no-Vise pair on the same model and reasoning setting.

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.

Supported Platforms

| Platform | Status | Sensors | |---|---|---| | TypeScript / Next.js / React | Supported | tsc, npm build, npm lint, SDK import smoke | | React Native | Supported | tsc, npm lint, SDK import smoke | | Flutter / Dart | Supported | flutter analyze, flutter test | | Android (Kotlin) | Supported | Gradle assemble, unit tests | | iOS (Swift) | Supported | Static rules fully operational (tree-sitter AST for highest-risk rules); Package.swift enables a SwiftPM manifest sensor, and .xcodeproj/.xcworkspace enables a guarded xcodebuild sensor when available |

Each platform is checked by the shipped rule suite across feed, comments, chat, moderation, communities, social graph, secrets, session & auth, notifications, live data, security, design, and more.

CLI Reference

Run vise <command> --help for full flags. JSON output is the default for agent-facing commands; the read commands (check, status, impact, sdk-release, passport, trust, plan, doctor, explain, explore) also accept --format human for a readable summary.

Inspect, plan, initialize

| Command | Purpose | |---|---| | vise explore "<request>" | Pre-credentials discovery: map a request to what social.plus offers (candidate outcome, capabilities, docs, next command). No project or API key needed | | vise doctor | Verify install; print version, install path, docs source | | vise inspect [path] | Detect platform, monorepo surfaces, design signals, available sensors, and bounded scan coverage. An incomplete scan cannot initialize or produce a green check; select a concrete app surface in a large monorepo | | vise impact [path] [--symptom "..."] [--policy-pack <path>] [--trust-policy <path>] [--format human] | Day-2 Change Planner. Compare current project manifests, SDK declarations, platform/surface shape, rules, active and recorded engagements, source-bound attestations, design contract, runtime proof, and accepted organization policy/trust with the last recorded Vise state. An optional reported symptom can correlate missing cross-surface behavior with recorded intent and current source, then print a bounded repair authorization. Read-only: reports preserved/stale/missing/unknown evidence and the smallest safe next commands without writing files or running project sensors | | vise sdk-release [path] [--platform <platform>] [--policy-pack <path>] [--trust-policy <path>] | SDK Release Intelligence. Compare detected SDK declarations—and exact resolved versions from supported lockfiles when available—with Vise's extraction-grounded snapshots, reviewed knowledge, and versioned fact-depth minimum/target gate, plus a separate organization SDK-policy verdict when selected. Reports exact assurance without fetching registries, editing dependencies, or treating semver as semantic proof | | vise sdk-release --from-surface-dir <before> --to-surface-dir <after> | Deterministically diff two SDK snapshots: added/removed symbols, changed model fields/nullability, capability transitions, affected symbol-anchored rules, and migration actions | | vise sdk-release discover --index <release-index.json\|https-url> [--output <discovery.json>] | Validate an upstream-explicit, checksum-bound release set with exactly one selection for TypeScript, React Native, Android, iOS, and Flutter. Does not download SDK artifacts, choose by semver, or promote knowledge | | vise sdk-release intake --discovery <discovery.json> --bundle <extraction-dir> --from-surface-dir <reviewed> --output-dir <candidate> | Verify and normalize the selected four canonical surface/model pairs, atomically write unverified candidate knowledge, and generate the existing semantic/downstream proposal without executing arbitrary extractor commands or touching customer code | | vise sdk-release propose --from-surface-dir <before> --to-surface-dir <candidate> [--output <proposal.json>] | Preview or explicitly persist a deterministic, complete-digest-bound SDK knowledge proposal. This never verifies or promotes the candidate | | vise sdk-release anchors propose --knowledge-proposal <proposal.json> --replacements <replacements.json> --from-surface-dir <before> --to-surface-dir <candidate> --rules-dir <rules> [--output <anchor-proposal.json>] | Bind every removed names-only rule anchor to explicit, unambiguous, platform-aligned replacement candidates and detector-evidence pointers. Exposes an unranked added-symbol pool but never edits rules, approves a choice, or infers semantic equivalence | | vise sdk-release anchors adopt --authoring-proposal <anchor-proposal.json> --review <anchor-review.json> --from-surface-dir <before> --to-surface-dir <candidate> --rules-dir <updated-rules> --output <adoption.json> | CLI-only maintainer verification: require separate semantic/detector/platform approval plus exact passing evidence, re-verify both surface digests and candidate provenance, prove only reviewed rule anchors moved, then write a receipt without editing rules or SDK facts | | vise sdk-release promote --proposal <proposal.json> --to-surface-dir <candidate> --review <review.json> --output-surface-dir <new-dir> | CLI-only maintainer write: require an approved digest-bound review and every command-matched evidence check, then atomically publish a new reviewed SDK surface without changing the candidate | | vise passport [path] [--policy-pack <path>] [--write] [--receipt <ci.json>] | Integration Passport. Compose accepted intent, lifecycle state, SDK and organization-policy assurance, evidence provenance/hashes, runtime proof or waiver, local Outcome Evidence, residual risk, and replay commands into stable digest-bound claims. Read-only by default; --write explicitly stores a private local sidecar artifact | | vise passport verify [path] [--passport <path>] [--trust-policy <path>] | Recompute the passport claim digest and every recorded local evidence state/hash. Preserved includes an artifact intentionally recorded as missing; it does not mean every artifact is present. A signed envelope is authenticated only when the explicit trust policy is supplied. Fails closed and never repairs or rewrites the project | | vise passport compare [path] --from <before.json> --to <after.json> [--trust-policy <path>] | Compare two internally self-consistent passports and compose a digest-bound Governed Release Review decision (ready, review-required, or blocked) from readiness, intent, lifecycle, SDK assurance, Policy Pack severity/owners, evidence, runtime proof, advisory Outcome Evidence, residual risk, receipt, and optional authenticated-envelope provenance. Human output leads with the release decision and regressions while JSON retains every changed path/value; read-only and does not rerun evidence or assert human approval | | vise trust sign [path] --artifact <path> --artifact-type <integration-passport\|policy-pack> --private-key <pem> --issuer <id> --key-id <id> --audience <value> --expires-at <time> --output <path> | CLI-only explicit write: create an Ed25519 Portable Trust Envelope. The supplied external private key is used for this invocation only and is never copied or retained | | vise trust verify [path] --envelope <path> --trust-policy <path> [--expected-artifact-type <type>] | Read-only local authentication of payload digest, signature, issuer/key authorization, audience, expiry, and trust-policy constraints. Artifact semantics are still checked by the consuming Passport or Policy Pack operation | | vise policy status [path] [--source <manifest>] [--ci] | Read-only assess_policy_operations view of the explicit/accepted repository policy source, lifecycle, trust rotation/revocation, deterministic update impact, and exact owner routing; CI exits 0/12/13 for ready/review-required/blocked | | vise policy accept [path] --source <manifest> --recorded-by <identity> --reason <reason> | Explicitly pin one valid current source and Policy Pack digest and write a mode-0600 local review receipt; CLI-only, never rewrites policy inputs or asserts release approval | | vise plan [path] --request "..." [--summary] | Grounded implementation plan with intake questions and docs citations; --summary prints a compact route/intake view | | vise plan --summary "..." | Shortcut for quick routing or discovery when the current directory is the repo | | vise plan-harness [path] --request "..." | Pre-planning step: build the harness around the request | | vise init [path] --request "..." [--answer key=value] [--policy-pack <path>] [--trust-policy <path>] [--measurement-plan <path>] | Write the sp-vise/ compliance contract once blocking intake is answered. --policy-pack accepts one reviewed organization-pack identity/digest; a signed envelope also requires and binds --trust-policy. --measurement-plan accepts one reviewed aggregate measurement definition before observation starts. Exits 7 (needs-clarification) otherwise. Refuses to initialize the Vise / social.plus blocks development workspace itself (status: "internal-workspace", exit 10 — use vise sdk-facts there, or --allow-internal-workspace for an intentional harness run). Replacing a green engagement with a different outcome requires --supersede-engagement (exit 7 otherwise); the outgoing engagement's final state is recorded to sp-vise/engagements/ either way | | 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; ignores unverifiable or drifted snapshot evidence. If the in-scope surface's live vise check is already green, auto-records that one surface (same evidence bar as workplan complete) so a working, check-green surface isn't left uncounted | | vise workplan complete [path] --request "..." --surface <id> | Record a green-checked surface; snapshots evidence plus an integrity manifest under sp-vise/workplan-snapshots/<surface>/ | | vise workplan trim [path] --request "..." --surface <id> --reason "..." | Deliberately omit a companion surface (surface-level scope-omit). --reason required; re-arms the blueprint sign-off gate (re-sign the trimmed blueprint before proceeding) |

Creative pre-planning (advisory)

| Command | Purpose | |---|---| | vise creative [path] --request "..." [--requirements <path\|none>] [--prototype <html>] [--ranking-preview] | Write an advisory Engagement Intelligence brief with multiple candidate solution variants, rationale, tradeoffs, and review gaps; --ranking-preview adds opt-in, local-only review context that never reorders the default candidates | | vise creative accept [path] --variant <id> --rationale "..." --confidence high\|medium\|low | Record the grounded selected variant so plan/init/workplan carry it forward; --variant none --rationale "..." --confidence high\|medium\|low 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; --kind outcome-evidence --evidence <input.json> requires a strict reviewed aggregate input and verified archived Passport; refreshes the learning summary | | vise learning show [path] | Read the local learning summary and advisory Outcome Evidence deltas (never claims causality, scores, uploads, or changes recommendations) |

Everything in this group is local and advisory: no uploads, no vise check exit-code changes, no auto-accepted variants, no top-1 confidence claim, and no calibrated score.

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 (incl. computed WCAG for the brand palette's role pairs when a profile exists); never fails a build | | vise design contrast <foreground> <background> | Compute the WCAG 2.x contrast ratio between two colours (advisory) — check any text/icon colour that isn't a palette role instead of eyeballing it | | 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 sdk-facts --platform <platform> [--capability <capability>] [--format json] | Read bundled SDK surface facts plus the package-owned five-platform fact-depth contract, honest target gaps, and fail-closed promotion gate without a project; useful before editing or packaging a social.plus block | | vise placements plan [path] --placement <id> --package-source <local-path> | Plan explicitly selected Managed Placement host/slot governance without writing; the private pre-launch host requires a local/file source | | vise placements add [path] --placement <id> --package-source <local-path> [--dry-run\|--apply] | Install the host dependency + sidecar; dry-run by default, never guesses slot coordinates, remains additive to vise blocks, and blocks npm until host publication | | vise placements validate [path] [--placement <id>] | Verify one host init, explicit slot/context evidence, secret hygiene, and drift | | 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: green, needs-attestation, deterministic-failures, blocked, contract-drift, completeness-gap, selected-capability-failures, no-platform (no SDK platform detected — reported as a failure, not a vacuous green), or runtime-proof-waived | | vise check [path] --ci [--from-passport <before> --to-passport <after> [--trust-policy <path>]] | Read-only release gate for the active contract and every recorded engagement, optionally composed with the same Governed Release Review returned by Passport comparison. Compliance exit codes remain authoritative; active green with completed-work drift exits 11, and otherwise-green compliance with release evidence that is not ready exits 12 | | vise check [path] --allow-proof-waiver | Accept an honest runtime-proof-waived result (from vise smoke waive) as passing (exit 0) instead of blocking; without it a waiver blocks CI by default | | vise check [path] --new-only | Brownfield gate. With a recorded baseline, gate only on rule findings introduced since the baseline (pre-existing ones are reported but excluded). The outcome's completeness checklist and selected optional capabilities are never excluded — they are the engagement's deliverables and gate like a default check. Default check always gates on everything | | vise check [path] --engagement <outcome> | Re-verdict one recorded engagement (from sp-vise/engagements/) against the current ruleset and code. Exit 11 on drift, 0 when it still holds; never the active engagement's codes. ruleset_upgraded discloses when the installed ruleset moved since it was recorded | | vise check [path] --all-engagements | Run the normal active gate plus re-verdicts of every recorded engagement. Active gate non-green → its normal exit code; active green but a recorded engagement drifted → exit 11 (engagement-drift). Findings already gating the active engagement are counted once there (shared_with_active) | | vise baseline [path] | Snapshot the current pre-existing rule findings to sp-vise/baseline.json so check --new-only can separate legacy debt from new gaps. Deliverables (completeness/selected capabilities) are never baselined. Record it right after vise init, before writing code — a mid-build baseline would swallow your own findings. vise init --baseline records it at init time | | vise validate [path] | Run the deterministic validators only (no attestation comparison) | | vise sync [path] | Persist deterministic-pass evidence to sp-vise/attestations/ | | vise attest [path] --rule <id> --signer host-agent --confidence high --evidence-file evidence.json --rationale "..." | Record an attestation when a rule passes through architecture the deterministic check can't see. Attestations are bound to the engagement outcome they were reviewed under: after vise init switches the sidecar to a different outcome, a rule-global attestation re-gates (stale_engagement_attestation) until re-attested — file-scoped attestations survive the switch because new files re-gate them anyway | | vise explain <ruleId> | Print a rule's rationale, evidence requirements, and remediation | | vise status [path] | Summarize the current compliance state |

Sensors, skill, engagement, server

| Command | Purpose | |---|---| | vise run-sensors [path] [--dry-run] [--include "<sensor name>"] | Run detected project scripts (npm, Gradle, Flutter, lint, typecheck, SDK smokes); --dry-run lists without executing. Every explicit include must match a detected sensor or the command fails; output is bounded and timed-out descendants are terminated | | vise smoke [path] --log <file> | Assess a captured mount-smoke log into a pass/fail verdict + record marker-only evidence (unrelated SDK console lines are dropped from the durable log). expect: "populated" requires loaded count=N with N > 0; this catches session-establish and empty-data gaps that static checks cannot see | | vise smoke [path] --log <file> --receipt-context <json> | Upgrade selected scoped smoke proof with source revision, build, platform/runner, route/target, retained artifact digests, freshness, and prior Passport lineage | | vise smoke verify [path] --evidence <scoped-json> | Read-only full-receipt verification; distinguishes absent, stale, tampered, failed, and passed without launching the app | | vise smoke waive [path] --reason "..." [--mode declined\|deviceless] [--owner ... --scope ... --expires-at ...] | Record an auditable runtime-proof waiver when proof is declined or no device/emulator is available, instead of faking evidence. Optional ownership/scope/expiry metadata supports deterministic Policy Pack constraints, but any supplied scope/expiry remains binding without a pack: wrong-outcome, expired, or inverted-expiry waivers are unusable. A usable waiver produces runtime-proof-waived (exit 9; accept with --allow-proof-waiver) rather than a red-forever live surface | | vise install-skill --target <host> | Install the bundled skill into a coding host (see Quick Start) | | vise print-skill | Print the skill markdown to stdout | | vise engagement init [path] [--tier ...] [--customer-id ...] [--scope ...] | Record optional contractual scope metadata | | vise engagement show [path] | Print the recorded engagement metadata | | vise mcp | Start the stdio MCP compatibility adapter |

MCP Integration

MCP-capable hosts can call Vise as structured tool calls instead of shell commands:

{
  "mcpServers": {
    "social-plus": {
      "command": "vise",
      "args": ["mcp"]
    }
  }
}

Tool names (snake_case per MCP convention): search_docs, get_doc_page, inspect_project, impact_project, analyze_sdk_release, generate_integration_passport, verify_integration_passport, compare_integration_passports, verify_trust_envelope, creative_brief, creative_accept, ux_harness, compile_experience, experience_sensors, plan_harness, plan_integration, init_compliance, check_compliance, experience_report, record_learning, show_learning, sync_compliance, attest_rule, explain_rule, init_engagement, show_engagement, resolve_request, run_sensors, smoke, validate_setup, suggest_patch, debug_issue, design_extract, design_check, design_contrast, design_preview, design_reference, design_init_tokens, get_sdk_facts.

Most tools mirror the CLI commands above. The adapter still answers the legacy resolve_request and suggest_patch names for compatibility, but they are deprecated in favour of plan_integration plus host-tool edits.

CI Compliance

Commit sp-vise/ to your repository, then add vise check --ci to your pipeline:

name: Vise Compliance

on:
  pull_request:
  push:
    branches: [main]

jobs:
  vise-compliance:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: npm install -g @amityco/social-plus-vise
      - run: vise check . --ci

vise check --ci is read-only — it never updates sp-vise/ — and its JSON output includes a structured ci block for pipeline logs. It automatically re-verdicts every recorded engagement, so CI holds previously completed surfaces green without a second --all-engagements command.

For a candidate handoff, add a paired --from-passport and --to-passport (plus --trust-policy when both are signed envelopes). The resulting releaseReview composes Passport integrity/readiness, comparison movement, Policy Pack severity and declared owners, SDK assurance, runtime evidence, and optional authenticity. ready means the automated evidence supports review; Vise still records humanApprovalAsserted: false and never authorizes the release. See docs/GOVERNED_RELEASE_REVIEW.md.

| Exit code | Meaning | |---|---| | 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 — 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 | | 8 | No SDK platform detected (no-platform) — reported as a failure, never a vacuous green | | 9 | Runtime proof waived (runtime-proof-waived) — accept explicitly with --allow-proof-waiver | | 11 | Engagement drift (--ci, --engagement, or --all-engagements): the active gate is green but a recorded engagement re-verdicts non-green — a previously finished surface no longer holds | | 12 | Governed Release Review is review-required or blocked while the underlying compliance gate is otherwise green; existing non-green compliance codes take precedence |

Compliance Contract

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, vise policy accept | Selected rules, ruleset digest, app surface, selected optional capabilities, accepted design digest, optional Policy Pack/Policy Operations plus signed-envelope/trust provenance, measurement-plan references, and the hashed project-manifest/SDK-dependency snapshot used by vise impact | | sp-vise/policy-reviews/ | vise policy accept | Append-only, mode-0600 controlled-update receipts binding previous/current policy sources, deterministic impact, recorder/reason, owners, and the explicit no-release-approval boundary | | sp-vise/measurement-plan.json | vise init --measurement-plan | Normalized, digest-bound, human-reviewed aggregate metric definition and windows bound to accepted intent; mode 0600, local-only, and archived with its engagement on a Day-2 outcome switch | | 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/engagements/<outcome>/*.json | vise init (on an outcome switch) | Engagement ledger: the superseded engagement's final check, contract, and intake (latest per outcome) — surfaced by vise status as previousEngagements | | 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 for review context; experience_score: null, no uploads, no default-order change, no top-1 confidence claim | | 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 --rationale "..." --confidence high\|medium\|low | 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; Outcome Evidence events carry a stable reviewed-evidence digest and Passport/runtime provenance | | sp-vise/learning-summary.json | vise learning record | Derived summary, including advisory Outcome Evidence deltas; score: null and recommendationOptimization.status: "not-active" | | sp-vise/flow.json | vise workplan next / trim | Entry-state, selected solution path, active blueprint digest, sign-off state, and omitted companion surfaces | | sp-vise/flow-blueprint.html | vise workplan next | Human-readable blueprint preview for the alignment gate; review before passing blueprint_confirmation=<digest> | | sp-vise/workplan.json | vise workplan complete | Broad-request progress: completed surfaces, green-check evidence, snapshot integrity digest | | sp-vise/workplan-snapshots/<surface>/ | vise workplan complete | Per-surface snapshots plus snapshot-manifest.json so later focused surfaces don't erase earlier proof | | sp-vise/integration-passport.json | vise passport --write | Sanitized stable claims, SHA-256 claim digest, exact SDK assurance boundary, residual risks, replay commands, and hashes of local intent/contract/evidence artifacts. Written mode 0600; verification never repairs it | | sp-vise/smoke.json | project/runtime harness | Declared runtime-smoke surfaces and expected resolution states | | sp-vise/evidence/runtime-smoke.log | vise smoke | Canonical marker-only runtime log; unrelated browser/device/SDK console lines are removed rather than retained in durable evidence | | sp-vise/evidence/runtime-smoke.json | vise smoke | Captured runtime-smoke verdicts, canonical/input log digests, log-hygiene counts, smoke-config digest, and source provenance used by evidence-citing runtime rules | | sp-vise/evidence/runtime-smoke/<surface>.log | vise smoke | Independent marker-only log for one selected runtime surface | | sp-vise/evidence/runtime-smoke/<surface>.json | vise smoke | Preferred per-surface runtime proof; optional Evidence-native Runtime Receipt v1 adds source/build/runner/artifact/Passport lineage and separate claim states. Sibling refreshes and unrelated source/route drift do not overwrite it; legacy aggregate evidence remains a compatibility fallback | | sp-vise/evidence/runtime-proof-waiver.json | vise smoke waive | Explicit absence-of-proof record; supplied scope/expiry is always binding, and Policy Packs may additionally require owner, scope, expiry, and a bounded validity period | | 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:

vise attest . \
  --rule typescript.client.region \
  --signer host-agent \
  --confidence high \
  --evidence-file evidence.json \
  --rationale "Region is read from NEXT_PUBLIC_AMITY_REGION env var in lib/amity.ts:6"

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 — the same corpus vise search-docs grounds agents in.
• Questions, bugs & feature requests: email [email protected]. Existing customers can also reach their social.plus account team or integration partner.
• Skill installation issues: run vise doctor and include its output.
• Version history: CHANGELOG.md ships inside the installed package.

License

Proprietary — see the LICENSE file included with the package. 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.