@amityco/social-plus-vise 1.6.0 → 1.7.0

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

@@ -194,6 +194,26 @@ then render/wire the installed block and fill only the remaining gaps by hand. I
 
 No registry available means hand-build as normal — never assume a block or a registry exists; block existence is the registry's truth, not yours.
 
+## Projectless SDK Facts (Second Persona: Packaging, Not Integrating)
+
+Everything above assumes you are integrating the SDK **into a customer project**. Vise has a second, narrower persona for work that is *about* the SDK rather than about a project — packaging pre-built social.plus blocks, authoring contracts that claim SDK capabilities, or just confirming a symbol exists before writing anything:
+
+```sh
+vise sdk-facts --platform <typescript|react-native|android|ios|flutter> [--capability <id>] [--include-models] --format json
+```
+
+`sdk-facts` is projectless and read-only: it never inspects a repo and never writes `sp-vise/*`. It answers symbol existence, capability support, and (with `--include-models`) extraction-grounded model field schemas from the bundled SDK surface. Absence is reported honestly (`modelFacts.status: "absent"`, capability `missing-symbols`) — never invent a symbol the facts don't prove.
+
+Use it when: (a) a block/package contract must declare which SDK capabilities it depends on, (b) you need to verify an SDK model's real field names before mapping data, or (c) you are inside the Vise / social.plus blocks development workspace itself — where the customer-integration commands above are the wrong tool. `vise init` refuses to write a compliance sidecar into that workspace (`status: "internal-workspace"`, exit 10) and `inspect`/`plan` warn; do not work around the guard with `--allow-internal-workspace` unless you are intentionally running a harness fixture at the workspace root.
+
+## Adding Features To An App That Already Uses social.plus
+
+When the app already has working social.plus integration and the user asks for **another** feature ("we have a feed — add chat"), do not treat it as greenfield and do not fight pre-existing findings by editing code you were not asked to touch. Two situations:
+
+**The existing integration was hand-rolled (no `sp-vise/` directory).** Run `vise init` for the new request as normal. If the init result carries a `brownfield` block, follow it **immediately, before writing any code**: run `vise baseline .`, then gate your work with `vise check --new-only`. The baseline excludes pre-existing rule findings in legacy code; it **never** excludes the new outcome's completeness checklist or selected capabilities — those are your deliverables and still gate. Never record a baseline mid-build: it would swallow your own new findings as "pre-existing". If a legacy finding is in a file you must touch anyway, fix it rather than baselining around it.
+
+**The existing features were built through Vise (`sp-vise/` exists).** The sidecar tracks ONE active engagement at a time: `vise init` with a new request replaces the previous contract (intake, compliance, findings). The switch is governed, not silent — init records the outgoing engagement's final state to `sp-vise/engagements/<outcome>/` and returns an `engagement_switch` disclosure; replacing a **green** engagement additionally requires `--supersede-engagement` (surface the confirmation to the user, don't pass the flag on your own). Superseded engagements stay visible: `vise status` lists them under `previousEngagements`, `vise check --engagement <outcome>` re-verdicts one on demand, and `vise check --all-engagements` re-verdicts all of them alongside the active gate (exit `11` = active work is fine but a finished surface drifted — report it, don't ignore it). `vise workplan` state stays keyed to the old request: a `signedFlowAvailable` block means an in-progress journey exists — ask the user whether to resume it (use the original request wording) or start the new engagement. Do not reuse old intake answers for the new outcome, and do not rely on old attestations to cover new code — attestations expire on outcome switch and must be re-verified for the new engagement.
+
 ## Debugging (Day 2 Operations)
 
 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 whose stack/blame points at a file that imports the SDK, or that surfaced on an SDK-backed social surface** (feed/comments/chat/community/profile). The error *text* need not contain those keywords — a generic-looking `NullPointerException`, `401`, `OutOfMemoryError`, or a `notLoggedIn`/`session not established` message thrown from the social path IS in scope (that is exactly the flagship "feed stays empty / signing-in" class). Skip only genuinely non-SDK UI/CSS/build issues unrelated to any social surface. Full `vise debug` workflow and `repairBrief` format: **see `reference/debugging.md`**.