@amityco/social-plus-vise 0.11.0 → 0.12.2

package/rules/sdk-lifecycle.yaml

@@ -963,7 +963,7 @@
     {
       "id": "android.session.renewal",
       "version": 1,
-      "title": "Android login must pass an AmitySessionHandler that renews tokens",
+      "title": "Android login must pass a SessionHandler that renews tokens",
       "severity": "warning",
       "rationale": "Access tokens expire in production. Without a session handler that calls renewal.renew() in sessionWillRenewAccessToken, the SDK cannot refresh sessions and customers see silent auth failures.",
       "applies_when": {
@@ -992,7 +992,7 @@
           "evidence_required": [
             {
               "field": "session_handler",
-              "description": "Where AmitySessionHandler.sessionWillRenewAccessToken implementation lives.",
+              "description": "Where the SessionHandler.sessionWillRenewAccessToken implementation lives.",
               "upload_policy": "upload-with-consent"
             }
           ]
@@ -1007,7 +1007,7 @@
     {
       "id": "flutter.session.renewal",
       "version": 1,
-      "title": "Flutter login must pass an AmitySessionHandler that renews tokens",
+      "title": "Flutter login must pass a session handler callback (AccessTokenRenewal renewal) that renews tokens",
       "severity": "warning",
       "rationale": "Access tokens expire in production. Without a session handler that calls renewal.renew() in sessionWillRenewAccessToken, the SDK cannot refresh sessions and customers see silent auth failures.",
       "applies_when": {
@@ -1051,9 +1051,9 @@
     {
       "id": "ios.session.renewal",
       "version": 1,
-      "title": "iOS login must pass an AmitySessionHandler that renews tokens",
+      "title": "iOS login must pass a SessionHandler that renews tokens",
       "severity": "warning",
-      "rationale": "Access tokens expire in production. Without an AmitySessionHandler that calls renewal.renew() in sessionWillRenewAccessToken, the iOS SDK cannot refresh sessions and customers see silent auth failures.",
+      "rationale": "Access tokens expire in production. Without a SessionHandler that calls renewal.renew() in sessionWillRenewAccessToken, the iOS SDK cannot refresh sessions and customers see silent auth failures.",
       "applies_when": {
         "platforms": [
           "ios"
@@ -1080,7 +1080,7 @@
           "evidence_required": [
             {
               "field": "session_handler",
-              "description": "Where AmitySessionHandler.sessionWillRenewAccessToken implementation lives.",
+              "description": "Where the SessionHandler.sessionWillRenewAccessToken implementation lives.",
               "upload_policy": "upload-with-consent"
             }
           ]
@@ -1380,7 +1380,7 @@
       "version": 1,
       "title": "Android session handler must be retained",
       "severity": "warning",
-      "rationale": "AmitySessionHandler declared as a function-local variable gets garbage collected. The SDK's renewal callback will then call into nothing, causing sessions to silently expire.",
+      "rationale": "A SessionHandler declared as a function-local variable gets garbage collected. The SDK's renewal callback will then call into nothing, causing sessions to silently expire.",
       "applies_when": {
         "platforms": [
           "android"
@@ -1416,7 +1416,7 @@
       "version": 1,
       "title": "Flutter session handler must be retained",
       "severity": "warning",
-      "rationale": "AmitySessionHandler declared as a function-local variable gets garbage collected by Dart. The SDK's renewal callback will then call into nothing, causing sessions to silently expire.",
+      "rationale": "A session handler callback held only as a function-local variable gets garbage collected by Dart. The SDK's renewal callback will then call into nothing, causing sessions to silently expire.",
       "applies_when": {
         "platforms": [
           "flutter"
@@ -1452,7 +1452,7 @@
       "version": 1,
       "title": "iOS session handler must be retained",
       "severity": "warning",
-      "rationale": "AmitySessionHandler declared as a function-local variable will be released by ARC. The SDK's renewal callback will then call into nothing, causing sessions to silently expire.",
+      "rationale": "A SessionHandler declared as a function-local variable will be released by ARC. The SDK's renewal callback will then call into nothing, causing sessions to silently expire.",
       "applies_when": {
         "platforms": [
           "ios"

package/skills/social-plus-vise/SKILL.md

@@ -35,63 +35,17 @@ vise validate .
 vise run-sensors .
 ```
 
+**`vise check .` is mandatory, not optional. You are not done until it passes or every finding is explicitly attested.** Running `vise plan` and `vise inspect` but skipping `vise check` is the most common failure mode — it means the deterministic catch-net never ran and known-bad patterns ship. When you read a `vise plan`, do not truncate it (`| head` drops the implementation steps); read the full `implementationSteps` array.
+
 Treat Vise runtime smoke sensors as real validation. For TypeScript/React Native projects, `vise run-sensors` may include `TypeScript SDK import smoke`; if it fails, the SDK package does not resolve from the host project runtime and the integration is not done.
 
 In CI or pull-request pipelines, use `vise check . --ci`. It is read-only, exits non-zero unless compliance is green, and never writes deterministic-pass records; use `vise sync` only during the implementation loop after a local green check.
 
-## Debugging & Troubleshooting (Day 2 Operations)
-
-If the customer reports an SDK-specific runtime crash, build failure, or logical error (e.g. data not loading), start with `vise debug` before broad repo inspection or sidecar exploration.
-
-**CRITICAL SCOPE LIMIT:** Do NOT spam `vise debug` for generic UI/CSS errors or non-SDK issues. ONLY call `vise debug` if the error explicitly contains keywords like `social.plus`, `social-plus`, `Amity`, `live-collection`, or if the error occurs in a file that imports `social.plus` packages.
-
-For the first repair pass, prefer the compact troubleshooting loop:
-
-```bash
-vise debug . --error-file "logs/crash.log" --brief
-vise check . --ci
-vise run-sensors .
-```
-
-When debugging, pass the stack trace to Vise:
-
-```bash
-vise debug . --error "stack trace or exception message here"
-```
-Or, if the error is in a file:
-```bash
-vise debug . --error-file "logs/crash.log"
-```
-Or, for a compact repair brief:
-```bash
-vise debug . --error-file "logs/crash.log" --brief
-```
-
-The output contains `likelyCause`, `correlatedRules`, and a compact `repairBrief` with:
+## Debugging (Day 2 Operations)
 
-- the primary rule to repair first
-- likely file hints
-- minimum patch shape
-- invariants to preserve
-- verification commands
+If the customer reports an **SDK-specific** runtime crash, build failure, or data-not-loading bug, start with `vise debug .` (with `--error` / `--error-file`) **before** broad repo inspection — do not guess the fix first. Scope limit: only for errors mentioning `social.plus`/`Amity`/`live-collection` or in files importing the SDK; never for generic UI/CSS issues. Full `vise debug` workflow and `repairBrief` format: **see `reference/debugging.md`**.
 
-Do not guess the fix before consulting `vise debug`. Do not read broad `sp-vise/` history on the first pass unless the `repairBrief` is ambiguous or the first repair fails.
-
-## Engagement Scope (Optional)
-
-If the customer has set up `sp-vise/engagement.json` (via `vise engagement init`), respect the declared scope. `vise engagement show .` prints the engagement metadata: tier, customer id, contracted outcomes, reviewer assignment.
-
-When `vise init` reports a `warnings` array containing "not in the engagement scope", surface that to the user — don't silently widen scope. The user either extends the scope by editing `engagement.json` or accepts that the current work is out-of-contract.
-
-If no `engagement.json` exists, do not create one without the user's intent. `vise engagement init` is a contractual artifact; agents should only run it when the user explicitly asks to set up engagement metadata, typically with `--tier`, `--customer-id`, and `--scope`.
-
-If `vise` is not installed, use:
-
-```sh
-npm install -g @amityco/social-plus-vise
-```
-
-Then retry the `vise` command.
+(If `vise` isn't installed: `npm install -g @amityco/social-plus-vise`. Engagement-scope handling — `sp-vise/engagement.json` — is in `reference/operations.md`.)
 
 ## Stop Instead Of Guessing
 
@@ -175,6 +129,15 @@ Amity exposes a global `unreadCount` stream that syncs across devices.
 - **Correct pattern**: Subscribe to the unread stream provided by the SDK (e.g. `AmityCoreClient.unreadCount()`, `getUnreadCount()`, `unread.stream`).
 - **Wrong pattern**: Hand-rolling unread counting on the client (e.g. `posts.filter(p => !p.isRead).length`). This causes counts to go out of sync because the server's read state isn't pushed to the manual counter.
 
+A read *count* with no way to clear it is half a feature: when a channel/thread is opened, mark it read so the server-side count actually decrements (`channel.markAsRead()` / `message.markRead()`, or `startMessageReceiptSync` + `stopMessageReceiptSync` paired with the view lifecycle). Reading the unread stream but never marking read leaves the badge stuck.
+
+### Message Delivery State
+
+A sent message starts in a `syncing` state and can land in `error` (e.g. network failure, or after an SDK session restart). A composer that renders only the optimistic success leaves failed messages silently stuck.
+
+- **Correct pattern**: Observe each message's `syncState` and surface failed sends with a retry/delete affordance; clean up unrecoverable failures (e.g. `deleteFailedMessages()`) on init.
+- **Wrong pattern**: Calling `createMessage` and rendering success unconditionally, with no handling for the `error` syncState.
+
 ### File Upload & Media
 
 Uploading media to external buckets (S3, Cloudinary) directly and trying to attach the resulting URL to an Amity post will fail. The SDK won't recognize external URLs as attachments.
@@ -202,15 +165,36 @@ When using a LiveCollection or live object, also handle connection-state changes
 Always filter post queries to exclude deleted or flagged content. Amity's older SDKs include flagged/deleted posts by default, which can leak moderated content into the feed UI if unfiltered.
 - **Correct pattern:** Apply `.includeDeleted(false)`, `.statuses([.published])`, or `.feedType(AmityFeedType.PUBLISHED)` to your query builders.
 
+### Post Review Queue
+When a community has review enabled (`ADMIN_REVIEW_POST_REQUIRED`), posts flow through `reviewing` → `published`/`declined` feeds. A moderation dashboard that only queries the `published` feed silently misses everything awaiting review.
+- **Correct pattern:** For a moderator surface, query `feedType: 'reviewing'` (gated on the `REVIEW_COMMUNITY_POST` permission) and wire `approvePost()` / `declinePost()`. A regular member feed stays on `published`.
+- This is completeness, not deterministically enforced (most feeds aren't moderator dashboards) — match it to whether you're building a moderation/review surface.
+
 ### Opaque Pagination Cursors
 Amity uses opaque, token-based cursors for pagination. Never attempt to construct the `nextPage` argument using numeric math (e.g., `page * size`). This will cause silent failures or HTTP 400 errors.
 - **Correct pattern:** Pass the exact `nextPageToken` returned from the previous query result, or call `.loadMore()` / `.nextPage()` on the collection itself.
 - **Wrong pattern:** `.nextPage(pageNumber * 20)`
 
 ### Parent-Child Post Rendering
-Amity models image and video attachments as "child posts" attached to a parent post. If your UI only renders the parent post's text, it will silently drop all media attachments.
-- **Correct pattern:** Ensure the post-rendering component recursively processes `post.children`, `.childrenPosts`, or calls `getChildren()`.
-- **Wrong pattern:** `Text(post.data.text)` with no reference to the post's children.
+Amity attaches rich content — **images, videos, files, polls, and rooms/livestreams** — as "child posts" under a parent whose own `dataType` is usually `'text'`. A UI that reads only the parent will silently drop all of it. This applies to **every** media type, not just images: resolving images from `childrenPosts` but gating polls/videos/rooms on the parent's dataType is the most common version of this bug.
+- **Correct pattern:** Resolve every media type from the parent **or** its children, consistently — `post.childrenPosts?.find(c => c.dataType === 'poll')?.getPollInfo()`, same for image/video/room/file. Process `post.children` / `.childrenPosts` / `getChildren()` for all of them.
+- **Wrong pattern:** `Text(post.data.text)` with no children handling — or handling children for images only while checking `post.dataType === 'poll'/'video'/'room'` (the parent) for the rest.
+
+### Render Every Post Type the Feed Returns
+A global or community feed query without a `dataTypes` filter returns **all** post types — text, image, video, file, poll, livestream, and room. A renderer that branches on only one or two types silently renders the rest as blank cards. This is the single most common "the feed looks broken" complaint.
+- **Correct pattern:** Resolve each media type from **both the parent and its `childrenPosts`** — in a feed the parent is usually `dataType: 'text'` and the image/video/poll/room rides on a *child* post (see Parent-Child Post Rendering). Use a helper per type, e.g. `post.dataType === 'poll' ? post.getPollInfo() : post.childrenPosts?.find(c => c.dataType === 'poll')?.getPollInfo()` — and the same for image/video/room/file. For polls, read each answer via `answer.data` (a plain string) and `answer.image?.fileUrl`, support `votePoll`/`unvotePoll`, and show `poll.closedAt`/`closedIn`. For room/livestream, display the entity's `title`/`status` — never the raw `roomId`. **And when you render the text body itself (post or comment): if `metadata` carries mention entries (`{ type: 'user', index, length, userId }`, `length` excluding the `@`), wrap each `[index, index + length + 1]` span in a styled element and resolve `userId` to a display name — don't print raw text and lose the @mention highlight.** (Pass `mentionees` on create so mentioned users are notified.)
+- **Wrong pattern:** Gating media on the **parent's** dataType only — `const poll = post.dataType === 'poll' ? post.getPollInfo() : undefined` — while resolving images from children. The feed parent is `'text'`, so that branch never matches and polls/videos/rooms silently never render. Vise's `posts.parent-child-rendered` flags this inconsistency. Likewise, rendering `data.text` directly with no use of `metadata` mention offsets drops @mention highlights.
+- Coverage of *which* types appear is **not** deterministically enforced (a feed may legitimately contain only some types) — it is your responsibility to match rendering to what the feed can return.
+
+### Read SDK Objects Through Their Accessors, Not Casts
+Casting an SDK return value to a hand-written shape — `(post.data as { text?: string }).text` — silences the type-checker. When an SDK upgrade renames a field, the build still compiles and the bug only appears at runtime.
+- **Correct pattern:** Use the SDK's typed accessors and types (`post.getImageInfo()`, `post.getPollInfo()`, the `Amity.*` types) so `tsc`/`analyze` flags field-level breakage on upgrade.
+- **Wrong pattern:** `as { … }` casts over `post.data`, `comment.data`, `answer.data`, or community/user fields.
+
+### Comment Surfaces Need Read, Write, and an Explicit `pageSize`
+A comment thread is incomplete if it only lists comments. Users expect to post.
+- **Correct pattern:** Pair `CommentRepository.getComments({ …, pageSize: 20 }, cb)` (read) with a composer that calls `createComment` (write), gated behind the user's ban state. Always pass an explicit `pageSize` — the default pagination uses skip/limit, which the server rejects for scrollable queries with a runtime 500000 error. Render replies via `getComments({ parentId })` when `childrenNumber > 0`.
+- **Wrong pattern:** A read-only comment list, or `getComments` with no `pageSize`.
 
 ### Explicit Feed Target Types
 When calling `createPost`, do not hardcode the `targetType` to a literal value like `AmityPostTargetType.COMMUNITY` if the composer component is meant to be reusable.
@@ -239,43 +223,13 @@ Amity routes custom-shape post payloads via the `dataType` tag. Omitting it make
 
 ## SDK Version Handling
 
-Do not use floating SDK dependency versions such as `latest`, `*`, `any`, `+`, or branch-based iOS package references. Pin the social.plus SDK to an explicit version or reviewed semver range, then let the host app's package manager lockfile capture the exact resolved version.
-
-## Attestation Flow
-
-`vise check` reports each applicable rule as one of `deterministic-pass`, `attestation-needed`, `failed`, or `blocked`. `attestation-needed` and `failed` are NOT warnings to skip — they block "I'm done." Resolve them in one of two ways:
-
-1. **Make the deterministic check fire (preferred).** Re-read `vise explain <rule-id>` for the rule's enforcement details, adjust the code so the check passes, then run `vise check` again. After it goes green, run `vise sync` to persist the deterministic-pass attestation files.
-2. **Record an attestation with evidence.** When the rule cannot fire because the customer's architecture is unconventional (DI wrappers, custom abstractions, etc.), use `vise attest`:
+For a **new (greenfield) install**, resolve the **current latest** SDK at install time — never copy a version number from examples, docs snippets, or memory, which go stale (e.g. an old major can lack `StoryRepository`). Install latest, then pin the resolved version: `npm install @amityco/ts-sdk@latest` (TypeScript/React Native; the lockfile captures the exact version), or the latest Maven / CocoaPods·SwiftPM / pub.dev release for Android / iOS / Flutter. `vise plan` surfaces an `sdkVersion` field — for TypeScript/React Native it reports the current npm `latest`; **heed it**.
 
-```bash
-vise attest . \
-  --rule typescript.client.region \
-  --confidence high \
-  --signer host-agent \
-  --rationale "API_REGIONS.EU is explicitly passed as the second argument to Client.createClient in src/socialSDK.ts." \
-  --evidence-file ./.tmp/evidence.json
-```
-
-The evidence file is a JSON object matching the `evidence_required` schema for that rule (`vise explain <rule-id>` shows the required fields). Include concrete source file paths in evidence values whenever the evidence depends on code, for example `{ "region_source": "src/socialSDK.ts" }` or `{ "login_flow": "src/auth/socialSession.ts" }`. `vise attest` fingerprints cited files, and future `vise check` runs mark the attestation stale if those files change.
-
-### Confidence honesty
-
-- `high` — direct evidence the deterministic check would have fired if it had been more flexible. Auto-recorded.
-- `medium` — reasoned about it but cannot point to a single unambiguous location. May require human signer depending on rule.
-- `low` — guess. Always requires `--signer human`.
+Do not use floating SDK dependency versions such as `latest`, `*`, `any`, `+`, or branch-based iOS package references in the committed manifest. Pin the social.plus SDK to an explicit version or reviewed semver range, then let the host app's package manager lockfile capture the exact resolved version. If `vise plan` reports that an **existing** project is on an older major than current latest, treat that as an FYI only — a major upgrade is out of scope unless the task explicitly asks for it.
 
-If the rule's `escalation_threshold` is above your confidence, `vise attest --signer host-agent` is rejected. In v0.4 there is no hosted review queue yet, so the path is: stop, surface to the user with the rule id and the evidence you have, and ask them to run `vise attest --signer human --identity <their name or email>` themselves.
+## Resolving `vise check` Findings
 
-### What `vise sync` is NOT
-
-- `vise sync` does **not** accept `--attest` or any flag. It only persists deterministic-pass results.
-- Passing unknown flags to `vise sync` will error in v0.4 — don't try to use it as a shortcut for attestation.
-- To record an attestation, use `vise attest`. Always.
-
-### Treat warnings as blockers
-
-If a legacy `vise validate` run reports `needs-review` with warnings, those warnings correspond to compliance rules in `attestation-needed` state. Do not interpret them as "code is fine, just static-analysis noise." Run `vise check` to get the structured rule list, then resolve each one as above.
+`vise check` reports each rule as `deterministic-pass`, `attestation-needed`, `failed`, or `blocked`. **`attestation-needed` and `failed` block "I'm done" — they are not skippable warnings.** Resolve each one of two ways: (1) **preferred** — adjust the code so the deterministic check fires (`vise explain <rule-id>` shows what it wants), then `vise check` green → `vise sync`; or (2) record `vise attest` with evidence when the architecture is genuinely unconventional. Confidence honesty, the `vise attest` evidence-file format, escalation/human-signer rules, and "`vise sync` is not attestation": **see `reference/operations.md`**.
 
 ## Feature Guidance
 
@@ -288,6 +242,14 @@ vise plan . --request "<feed or post request>"
 
 Require a concrete target from the app: current user feed, selected community, selected channel, or another user-provided domain object. Do not hardcode random target IDs.
 
+**Decide engagement scope explicitly — Vise authors the checklist, you subtract with a reason.** `vise plan` returns a `completenessChecklist` (the canonical capabilities for the outcome, e.g. comments, reactions, pagination, polls, media, moderation) and `vise check` reports each as present / missing / opted-out. This is **advisory — it never fails the check**; it exists so completeness doesn't depend on your memory. For each capability: build it, or explicitly opt out with a recorded marker in the code so the omission is reviewable, not accidental:
+
+```
+// vise: scope-omit poll — text + image feed only; polls disabled for this tenant
+```
+
+Do not silently drop a capability. `vise check`'s `completeness` section will keep nudging on anything that's neither built nor opted-out.
+
 **Demo wiring (when the app needs to compile before the real target source exists):** even at the top-level `App` / `MaterialApp` / `_app.tsx` / `AppDelegate` wiring site, do not pass a literal string. Use the host platform's compile-time env channel so the rule sees no string literal at the call site:
 
 - Flutter: `const String.fromEnvironment('AMITY_COMMUNITY_ID')` — value injected via `flutter run --dart-define=AMITY_COMMUNITY_ID=…`
@@ -336,6 +298,11 @@ When rendering moderation actions (like `flagPost`, `deletePost`, `banUser`, `mu
 
 Similarly, moderator-only data such as `flagCount` must not be leaked to non-moderators. Rendering `post.flagCount` unconditionally exposes moderation signal to all users, which is a privacy regression. Gating it with a role check ensures it is only visible to authorized users.
 
+**Post/comment actions are gated by the viewer's relationship to the content**, and ownership is distinct from moderator role:
+- **Author** (`post.postedUserId === currentUserId`): show edit (`editPost`/`updateComment`) and delete (`deletePost`/`deleteComment`).
+- **Non-author**: show report/flag (`flagPost`/`flagComment`).
+- A post card with no actions menu at all is incomplete. Do not show edit/delete to non-authors, and do not rely on the server's 403 to hide them.
+
 ### User Ban State
 
 Banned users still see interaction buttons (like `createPost`, `createComment`, `sendMessage`) if you don't check their ban state before rendering them. These API calls will fail on the server, causing a poor UX and support tickets.
@@ -367,16 +334,49 @@ Require chat shape (1:1, group, community), channel source (never hardcode chann
 - Use `community` or `live` for groups.
 If the type intentionally mismatches the UI name, add `// vise: channel type rationale — <reason>` to the code.
 
-## Monorepos
+For communities:
 
-If `vise inspect .` reports multiple surfaces, choose the intended app with the user or surrounding task context. Pass it consistently:
+```bash
+vise search-docs "community create join leave members invitation"
+vise plan . --request "<community request>"
+```
+
+Require the community surface (create, browse/join, detail + members, or membership management), the privacy model (public instant-join vs private join-request approval — they differ), and a concrete community ID source (never hardcode a communityId). Query communities and members through a Live Collection, handle the join-request flow for private communities, gate moderator actions (roles/ban) by role, and clean up observers. `vise plan` returns the community `completenessChecklist`; opt out of anything out of scope with `// vise: scope-omit <id> <reason>`.
+
+For the social graph (follow/followers):
+
+```bash
+vise search-docs "follow unfollow followers following block user"
+vise plan . --request "<follow/social-graph request>"
+```
+
+Require the surface (follow button, follower list, following list, or blocked users), the follow model (automatic vs follow-request approval — they differ), and a concrete target userId source (never invent a userId). Query follower/following lists through a Live Collection; handle the follow-request pending/accept/decline flow when following isn't automatic; clean up observers.
+
+For an in-app notification tray (distinct from push setup — that's a push/FCM/APNS concern):
 
 ```bash
-vise plan . --surface apps/web --request "<user intent>"
-vise validate . --surface apps/web
-vise run-sensors . --surface apps/web
+vise search-docs "in-app notification tray seen settings"
+vise plan . --request "<notification tray request>"
 ```
 
+Observe the notification tray as a Live Object/Collection, mark items/tray seen so the unseen badge clears server-side, respect Amity's server-side notification settings, and clean up the observer.
+
+## Design-Conformant UI (Design Contract)
+
+The customer wants social.plus UI that looks like *their* app, not a generic kit. Match their aesthetic from whatever design signal exists, in this priority:
+
+1. **Customer-provided prototype (HTML/CSS).** If the customer gives you an HTML/CSS prototype (a static mockup, an existing page, a design export), run `vise design extract <prototypePath> --repo .` first. It writes `sp-vise/design-contract.json` — a *graded* contract: **declared** tokens (CSS custom properties — exact, authoritative) and **inferred** tokens (repeated literal values — advisory). `vise plan` then surfaces this contract in its `designContract` field. Build the feed using the declared tokens; treat inferred tokens as advisory and confirm brand values with the customer when the contract `strength` is `weak`.
+2. **Host app's own design system.** With no external prototype, run `vise design extract --from-project .` to derive the contract from the project's *own* design system — CSS custom properties (incl. shadcn `:root` and Tailwind v4 `@theme`), TS/JS token modules (`theme.ts`/`tokens.ts`), inline tailwind configs, and native sources (Android `colors.xml`/`dimens.xml`, Flutter `Color(0x…)`, iOS `.xcassets/*.colorset` + Swift colors). Then build the new surface from those tokens (also enforced by `*.design.reuse-detected-tokens`). `vise inspect` lists the detected design signals.
+3. **Neither.** Use a neutral, accessible default and **state in your summary that no design source was found** — do not invent brand colors, spacing, or a design system. Ask the customer for a prototype, their theme file, or screenshots.
+
+To let the customer (or yourself) **see** the contract and check the match, run `vise design preview .` — it writes a self-contained `sp-vise/design-preview.html` with the tokens as visual swatches, the conformance report, and the HTML prototype embedded (`--reference <prototype>`) for side-by-side review. It's advisory: it renders the artifact for a human/VLM to judge, and is not an automated pixel diff (a true render diff belongs to your own browser tooling, not Vise).
+
+The design contract is **advisory generation guidance**: it shapes what you build, but it is not a deterministic gate and never fails `vise check`. A token-poor prototype yields a weaker — never wrong — contract. When you record a design attestation, cite the contract `digest` so the feed can be claimed conformant to the prototype.
+
+## Monorepos
+
+If `vise inspect .` reports multiple surfaces, pick the intended app and pass `--surface <path>` consistently to `plan`/`validate`/`run-sensors`. Details: `reference/operations.md`.
+
 ## Final Response Discipline
 
 Report:

package/skills/social-plus-vise/reference/debugging.md

@@ -0,0 +1,39 @@
+# Debugging & Troubleshooting (Day 2 Operations)
+
+Load this when the customer reports an SDK-specific runtime crash, build failure, or logical error (e.g. data not loading).
+
+Start with `vise debug` before broad repo inspection or sidecar exploration.
+
+**CRITICAL SCOPE LIMIT:** Do NOT spam `vise debug` for generic UI/CSS errors or non-SDK issues. ONLY call `vise debug` if the error explicitly contains keywords like `social.plus`, `social-plus`, `Amity`, `live-collection`, or if the error occurs in a file that imports `social.plus` packages.
+
+For the first repair pass, prefer the compact troubleshooting loop:
+
+```bash
+vise debug . --error-file "logs/crash.log" --brief
+vise check . --ci
+vise run-sensors .
+```
+
+When debugging, pass the stack trace to Vise:
+
+```bash
+vise debug . --error "stack trace or exception message here"
+```
+Or, if the error is in a file:
+```bash
+vise debug . --error-file "logs/crash.log"
+```
+Or, for a compact repair brief:
+```bash
+vise debug . --error-file "logs/crash.log" --brief
+```
+
+The output contains `likelyCause`, `correlatedRules`, and a compact `repairBrief` with:
+
+- the primary rule to repair first
+- likely file hints
+- minimum patch shape
+- invariants to preserve
+- verification commands
+
+Do not guess the fix before consulting `vise debug`. Do not read broad `sp-vise/` history on the first pass unless the `repairBrief` is ambiguous or the first repair fails.

package/skills/social-plus-vise/reference/operations.md

@@ -0,0 +1,59 @@
+# Operations: Attestation, Engagement Scope, Monorepos
+
+Load this when resolving `vise check` findings, working with engagement scope, or operating in a monorepo.
+
+## Attestation Flow
+
+`vise check` reports each applicable rule as one of `deterministic-pass`, `attestation-needed`, `failed`, or `blocked`. `attestation-needed` and `failed` are NOT warnings to skip — they block "I'm done." Resolve them in one of two ways:
+
+1. **Make the deterministic check fire (preferred).** Re-read `vise explain <rule-id>` for the rule's enforcement details, adjust the code so the check passes, then run `vise check` again. After it goes green, run `vise sync` to persist the deterministic-pass attestation files.
+2. **Record an attestation with evidence.** When the rule cannot fire because the customer's architecture is unconventional (DI wrappers, custom abstractions, etc.), use `vise attest`:
+
+```bash
+vise attest . \
+  --rule typescript.client.region \
+  --confidence high \
+  --signer host-agent \
+  --rationale "API_REGIONS.EU is explicitly passed as the second argument to Client.createClient in src/socialSDK.ts." \
+  --evidence-file ./.tmp/evidence.json
+```
+
+The evidence file is a JSON object matching the `evidence_required` schema for that rule (`vise explain <rule-id>` shows the required fields). Include concrete source file paths in evidence values whenever the evidence depends on code, for example `{ "region_source": "src/socialSDK.ts" }` or `{ "login_flow": "src/auth/socialSession.ts" }`. `vise attest` fingerprints cited files, and future `vise check` runs mark the attestation stale if those files change.
+
+### Confidence honesty
+
+- `high` — direct evidence the deterministic check would have fired if it had been more flexible. Auto-recorded.
+- `medium` — reasoned about it but cannot point to a single unambiguous location. May require human signer depending on rule.
+- `low` — guess. Always requires `--signer human`.
+
+If the rule's `escalation_threshold` is above your confidence, `vise attest --signer host-agent` is rejected. In v0.4 there is no hosted review queue yet, so the path is: stop, surface to the user with the rule id and the evidence you have, and ask them to run `vise attest --signer human --identity <their name or email>` themselves.
+
+### What `vise sync` is NOT
+
+- `vise sync` does **not** accept `--attest` or any flag. It only persists deterministic-pass results.
+- Passing unknown flags to `vise sync` will error in v0.4 — don't try to use it as a shortcut for attestation.
+- To record an attestation, use `vise attest`. Always.
+
+### Treat warnings as blockers
+
+If a legacy `vise validate` run reports `needs-review` with warnings, those warnings correspond to compliance rules in `attestation-needed` state. Do not interpret them as "code is fine, just static-analysis noise." Run `vise check` to get the structured rule list, then resolve each one as above.
+
+## Engagement Scope (Optional)
+
+If the customer has set up `sp-vise/engagement.json` (via `vise engagement init`), respect the declared scope. `vise engagement show .` prints the engagement metadata: tier, customer id, contracted outcomes, reviewer assignment.
+
+When `vise init` reports a `warnings` array containing "not in the engagement scope", surface that to the user — don't silently widen scope. The user either extends the scope by editing `engagement.json` or accepts that the current work is out-of-contract.
+
+If no `engagement.json` exists, do not create one without the user's intent. `vise engagement init` is a contractual artifact; agents should only run it when the user explicitly asks to set up engagement metadata, typically with `--tier`, `--customer-id`, and `--scope`.
+
+If `vise` is not installed, use `npm install -g @amityco/social-plus-vise`, then retry the `vise` command.
+
+## Monorepos
+
+If `vise inspect .` reports multiple surfaces, choose the intended app with the user or surrounding task context. Pass it consistently:
+
+```bash
+vise plan . --surface apps/web --request "<user intent>"
+vise validate . --surface apps/web
+vise run-sensors . --surface apps/web
+```