@amityco/social-plus-vise 0.14.4 → 0.14.6

package/CHANGELOG.md

@@ -4,6 +4,34 @@ All notable changes to `@amityco/social-plus-vise` are documented in this file.
 
 The format is loosely based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 0.14.6 — 2026-06-05
+
+**Theme:** Intake questions must reach the human before implementation.
+
+### Added
+- **`vise init` now enforces unresolved blocking intake:** normal init returns `status: "needs-clarification"` and exits 7 when required planning questions are still unanswered. This prevents host agents from skipping surfaced questions and writing a compliance sidecar as if scope were resolved.
+- **`sp-vise/intake.json`:** successful init records the request, outcome, answers, remaining blocking count, and whether unresolved intake was explicitly acknowledged.
+- **`--allow-unresolved-intake`:** explicit bypass for retrospective benchmark/harness initialization only. The acknowledgement is recorded in `sp-vise/intake.json`; customer implementations should answer the blocking questions instead.
+
+### Fixed
+- **Host-project `style.css` design extraction:** `vise design extract --from-project` now detects non-theme-named CSS files that declare custom properties, so common roots like `style.css` produce strong host-project design contracts instead of empty weak contracts.
+- **Design-source wording:** `vise plan` now labels host-project design contracts as the host app's design system, not the customer's prototype, and empty contracts tell the agent to ask for the correct design source instead of implying tokens exist.
+
+### Docs
+- **Skill and tool docs now require surfacing blocking intake questions** before implementation, and release smoke guidance uses `--allow-unresolved-intake` only where a disposable retrospective init is intended.
+
+---
+
+## 0.14.5 — 2026-06-04
+
+**Theme:** Optional feed capabilities become explicit opt-in sensors.
+
+### Changed
+- **Add-feed completeness baseline narrowed to pagination:** image upload, poll creation, and edit post are no longer baseline completeness requirements. The add-feed `completenessChecklist` now gates pagination / load-more only.
+- **Optional feed capabilities require explicit opt-in:** `vise plan` now offers image upload, poll creation, and edit post as `optionalCapabilities`. When the user selects one and the agent carries it into `vise init --answer feed_optional_capabilities=...`, `vise check` runs selected source sensors and exits `selected-capability-failures` (exit code 6) until the selected capability is implemented.
+
+---
+
 ## 0.14.4 — 2026-06-04
 
 **Theme:** Completeness-gap enforcement and add-feed guidance hardening (image upload + poll creation + pagination build step).

package/README.md

@@ -45,7 +45,7 @@ See [Usage Flow](#usage-flow) for the full step-by-step diagram.
 
 Instead of just providing a CLI or AI skills, Vise implements a technique called **Agentic Workflow Governance**. Think of it as a customer-project integration harness: the governed build loop runs inside the target repo, grounded in the real project, real docs, and real validation signals.
 
-Vise wraps your local coding agents in compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 300 platform-specific compliance rules, checks the generated UI against the customer's design system, surfaces the full SDK feature surface so nothing is silently dropped, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
+Vise wraps your local coding agents in compliance guardrails when they integrate social.plus SDKs. It inspects your project, grounds the agent in hosted docs, enforces 300 platform-specific compliance rules, checks the generated UI against the customer's design system, gates narrow baseline capabilities so nothing mandatory is silently dropped, offers richer feed capabilities as explicit opt-ins, and runs your project's own build/lint/typecheck sensors. **Your source code never leaves your machine.**
 
 At a glance, Vise sits between the user's prompt and the agent's code changes. The agent still edits the app; Vise turns the request into a grounded plan, records the local contract, and keeps checking until the integration is ready to ship.
 
@@ -77,18 +77,53 @@ Vise validates on three layers, and the layer is set by the *kind of claim* —
 |---|---|---|---|
 | **SDK compliance** | "this is **wrong**" | 300 deterministic rules (session renewal, live-collection vs one-shot, no secret in logs, parent-child rendering, ban-state gating…) | **Hard gate** — `vise check` blocks until green or attested. A small advisory subset surfaces as informational only and never blocks. |
 | **Design conformance** | "this **looks off**" | extract the customer's design system into a contract, then check token usage | **Advisory** — `vise design check`/`preview`; never fails a build |
-| **Feature completeness** | "this is **missing**" | Vise proposes the full SDK feature surface per outcome; the agent opts out of anything out of scope with a recorded reason | **Decision gate** — `vise check` exits `completeness-gap` until each missing capability is built or validly opted out |
+| **Feature completeness** | "this is **missing**" | Vise proposes a narrow baseline per outcome; for add-feed, pagination is mandatory, while richer feed capabilities are opt-in choices from `vise plan` | **Decision gate** — `vise check` exits `completeness-gap` until each baseline capability is built or validly opted out; selected optional capabilities run separate sensors |
 
-Correctness is gated by deterministic rules or attestations. Completeness is gated by explicit scope decisions: if a capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
+Correctness is gated by deterministic rules or attestations. Baseline completeness is gated by explicit scope decisions: if a baseline capability is legitimately out of scope, record `// vise: scope-omit <id> — <reason>` and it no longer blocks. Optional feed capabilities such as image upload, poll creation, and edit post are offered during planning and become checked only after the user opts in. Conformance remains advisory because "matches the brand" is legitimately subjective. See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md).
 
 ### Relationship to social.plus Block Factory
 
 Vise has two deliberately separate roles:
 
 - **Customer integration helper:** runs inside customer projects to inspect, plan, validate, and sensor-check social.plus SDK integrations.
-- **Block Factory SDK facts provider:** planned internal mode for social.plus Block Factory to verify SDK capabilities, symbols, and model schemas before reusable blocks are generated or released.
+- **Block Factory SDK facts provider:** internal mode for social.plus Block Factory to verify SDK capabilities, symbols, and model schemas before reusable blocks are generated or released.
+- **Block installer governance:** customer-project workflow that consumes a Block Factory registry, plans safe package/source changes, writes `sp-vise/blocks.json`, and validates installed block state.
 
-Vise owns SDK truth and customer-project governance. social.plus Block Factory owns block contracts, package adapters, previews, conformance tests, and release readiness. See [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md) for the internal provider-side plan.
+Vise owns SDK truth and customer-project governance. social.plus Block Factory owns block contracts, package adapters, registry metadata, previews, conformance tests, and release readiness. See [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md) for the internal provider-side plan.
+
+### Block Factory user experience
+
+When Vise is used with social.plus Block Factory, the customer experience should feel like asking an AI agent for a social capability rather than manually assembling SDK calls and UI states:
+
+> "Add social.plus comments to this app and match my existing design system."
+
+The agent uses Vise to turn that request into a governed install workflow:
+
+```sh
+vise blocks list --registry ./registry/blocks.json --format json
+vise blocks plan . --block comments --registry ./registry/blocks.json --format json
+vise blocks add . --block comments --registry ./registry/blocks.json --package-source npm --dry-run
+vise blocks add . --block comments --registry ./registry/blocks.json --package-source npm --apply
+vise blocks validate . --block comments --registry ./registry/blocks.json --format json
+vise run-sensors --dry-run
+```
+
+What Vise does:
+
+- Inspects the customer project and detects the target platform.
+- Reads Block Factory registry metadata without owning block product data.
+- Plans package, source-anchor, sidecar, design-contract, and sensor requirements.
+- Applies changes only to package manifests, `sp-vise/blocks.json`, and source files with explicit install anchors.
+- Returns `needs-review` when a brownfield project has no safe install anchor.
+- Validates installed block state and detects drift after future code changes.
+
+Required customer or agent actions:
+
+- Choose the block id and package source.
+- Review the dry-run plan before using `--apply`.
+- Add explicit install anchors when Vise cannot safely edit the project.
+- Keep `sp-vise/blocks.json` committed so future validation has state to compare.
+- Run the target project's normal build, lint, test, and Vise sensors before shipping.
 
 ### Design-conformant UI
 
@@ -253,7 +288,7 @@ flowchart LR
     C --> D{Intake<br/>questions?}
     D -->|Yes| E[Agent asks user<br/>for feed target,<br/>design source, etc.]
     D -->|No| F
-    E --> F[Agent runs<br/>vise init]
+    E --> F[Agent runs<br/>vise init<br/>with answers]
     F --> G[Agent runs<br/>vise search-docs<br/>vise get-doc-page]
     G --> H[Agent edits<br/>your code]
     H --> I[Agent runs<br/>vise check]
@@ -266,7 +301,7 @@ flowchart LR
     M --> N[Done.<br/>sp-vise/ contract<br/>committed]
 ```
 
-The flow above is what the skill teaches your AI agent. You — the human — drive intent and approve edits; the agent runs Vise commands deterministically; Vise grounds the agent in real docs and real compliance rules.
+The flow above is what the skill teaches your AI agent. You — the human — drive intent and approve edits; the agent runs Vise commands deterministically; Vise grounds the agent in real docs and real compliance rules. If blocking intake is still unresolved, `vise init` refuses to initialize, returns `status: "needs-clarification"`, and exits 7 so the agent must surface the questions instead of guessing.
 
 ---
 
@@ -280,7 +315,11 @@ The flow above is what the skill teaches your AI agent. You — the human — dr
 | `vise inspect [path]` | Detect platform, monorepo surfaces, design signals, available sensors |
 | `vise plan [path] --request "..."` | Produce a grounded implementation plan with intake questions and docs citations |
 | `vise plan-harness [path] --request "..."` | (Pre-planning step) Build the harness around the request |
-| `vise init [path] --request "..."` | Write the `sp-vise/` compliance contract for this project |
+| `vise init [path] --request "..." [--answer key=value]` | Write the `sp-vise/` compliance contract after blocking intake is answered; returns `needs-clarification` and exits 7 if required answers are missing |
+| `vise blocks list --registry <path>` | Read a social.plus Block Factory registry |
+| `vise blocks plan [path] --block <id> --registry <path>` | Plan safe block package, source-anchor, sidecar, and sensor changes |
+| `vise blocks add [path] --block <id> --registry <path> [--dry-run\|--apply]` | Dry-run or apply safe block installation inside a customer project |
+| `vise blocks validate [path] [--block <id>] --registry <path>` | Validate installed block sidecar state, package presence, and source anchors |
 
 ### Design contract (UI generation)
 
@@ -409,12 +448,13 @@ jobs:
 
 | Code | Meaning |
 |---|---|
-| `0` | All rules pass and all expected capabilities are either present or opted-out |
+| `0` | All rules pass, all baseline capabilities are present or opted-out, and any selected optional capabilities pass |
 | `1` | One or more rules need attestation |
 | `2` | One or more rules have deterministic failures |
 | `3` | One or more blockers fired (missing prerequisite, e.g. `google-services.json`) |
 | `4` | Contract drift — rules in `sp-vise/compliance.json` no longer match the current ruleset |
-| `5` | One or more expected capabilities are neither implemented nor validly opted-out — add the capability or place `// vise: scope-omit <id> — <reason>` |
+| `5` | One or more baseline capabilities are neither implemented nor validly opted-out — add the capability or place `// vise: scope-omit <id> — <reason>` |
+| `6` | One or more explicitly selected optional capabilities failed source sensors |
 
 `vise check --ci` is read-only. It never updates `sp-vise/`. The JSON output includes a `ci` block with structured details for pipeline logs.
 
@@ -422,11 +462,12 @@ jobs:
 
 ## Compliance Contract
 
-After `vise init`, your project gets a `sp-vise/` directory. These files become part of your repo and travel through code review:
+After a successful `vise init`, your project gets a `sp-vise/` directory. If init returns `needs-clarification`, no compliance sidecar is written; answer the blocking questions and run init again. These files become part of your repo and travel through code review:
 
 | File | Created by | What it contains |
 |---|---|---|
 | `sp-vise/compliance.json` | `vise init` | The rules selected for this integration, the Vise version, the ruleset digest, the target app surface, and an optional engagement link. |
+| `sp-vise/intake.json` | `vise init` | The request, outcome, intake answers, remaining blocking count, and any retrospective `--allow-unresolved-intake` acknowledgement. |
 | `sp-vise/attestations/*.json` | `vise sync` (deterministic) or `vise attest` (host-agent / human) | Per-rule evidence: signer, confidence, rationale, cited files (with source fingerprints for drift detection). |
 | `sp-vise/inspection.json` | `vise init` | The platform, monorepo surface, and design-token signals detected at init time. |
 | `sp-vise/design-contract.json` | `vise design extract` | The extracted design contract: declared tokens, breakpoints, advisory components, source file digests (for freshness detection), and a stable digest over design facts. |

package/dist/capabilities.js

@@ -12,16 +12,14 @@
  * (`// vise: scope-omit <id> <reason>`), which `check` reads and reports. The
  * agent subtracts with justification — it doesn't have to remember the set.
  *
- * Gate-eligibility (not used here — these stay advisory): a capability could only
- * ever graduate to a gate if it has a named SDK-call anchor AND a no-fire fixture.
- * Every capability below is anchored on SDK symbols for exactly that reason, but
- * the output is advisory regardless.
+ * Baseline capability gates must stay narrow. For add-feed, pagination is the
+ * mandatory capability; richer composer affordances are selected optional sensors.
  */
 import { readdir, readFile, stat } from "node:fs/promises";
 import path from "node:path";
-// Canonical, Vise-authored capability set — the SDK feature surface (grounded in
-// rules/*.yaml + SKILL.md, not guessed). Anchored on SDK symbol names (consistent
-// enough across TS/Flutter/Android/iOS to match cross-platform). All advisory.
+// Canonical, Vise-authored capability catalog — the SDK feature surface
+// (grounded in rules/*.yaml + SKILL.md, not guessed). Baseline gating is applied
+// by baselineCapabilities(); not every catalog item is mandatory for every outcome.
 export const CAPABILITIES = [
     // ── add-feed: post dataTypes (a feed parent is usually 'text'; rich content
     //    rides on child posts — render each type the feed can return) ──────────
@@ -368,14 +366,124 @@ export const CAPABILITIES = [
         hint: "respect Amity's server-side notification settings/preferences (getSettings)",
     },
 ];
+// Optional capabilities are not baseline compliance. `vise plan` offers them as
+// explicit feed-forward choices; `vise init --answer feed_optional_capabilities=...`
+// records selected choices; `vise check` then evaluates these source sensors.
+export const OPTIONAL_CAPABILITIES = [
+    {
+        id: "post-image-upload",
+        label: "Image/file upload composer",
+        outcomes: ["add-feed"],
+        aliases: [/image(?:\/file)? upload/i, /image post/i, /file post/i, /attachments?/i, /media upload/i],
+        sensors: [
+            { label: "FileRepository.uploadImage or uploadImage", regex: /FileRepository\.uploadImage\s*\(|(?<![.\w])uploadImage\s*\(/ },
+            { label: "createPost attachments array", regex: /createPost\s*\(\s*\{[\s\S]*?attachments\s*:/ },
+        ],
+        hint: "If the user opts into media posting, implement file picker -> FileRepository.uploadImage(file) -> createPost({ ..., attachments: [{ fileId, fileType: 'image' }] }).",
+    },
+    {
+        id: "post-poll-creation",
+        label: "Poll composer and voting",
+        outcomes: ["add-feed"],
+        aliases: [/poll creation/i, /poll composer/i, /create poll/i, /\bpolls?\b/i],
+        sensors: [
+            { label: "PollRepository.createPoll", regex: /PollRepository\.createPoll\s*\(|(?<![.\w])createPoll\s*\(/ },
+            {
+                label: "createPost links pollId",
+                regex: /createPost\s*\(\s*\{[\s\S]*?data\s*:\s*\{[\s\S]*?\bpollId\b\s*(?::|[,}])/,
+            },
+            { label: "PollRepository.votePoll", regex: /PollRepository\.votePoll\s*\(|(?<![.\w])votePoll\s*\(/ },
+        ],
+        hint: "If the user opts into polls, implement the createPoll -> createPost({ data: { pollId } }) chain and the votePoll read-side interaction.",
+    },
+    {
+        id: "post-edit",
+        label: "Edit own post",
+        outcomes: ["add-feed"],
+        aliases: [/edit post/i, /edit own post/i, /author edit/i, /\beditPost\b/i],
+        sensors: [
+            { label: "PostRepository.editPost", regex: /PostRepository\.editPost\s*\(|(?<![.\w])editPost\s*\(/ },
+        ],
+        hint: "If the user opts into author management, show edit only for post.postedUserId === currentUserId and call PostRepository.editPost with updated text data.",
+    },
+];
 const ADVISORY_NOTE = "Build each missing capability, or opt out with a recorded reason: `// vise: scope-omit <id> — <reason>`. A scope-omit marker without a reason is invalid and still counts as missing. Missing capabilities that are neither built nor validly opted-out cause `vise check` to exit with status `completeness-gap` (exit code 5).";
-/** The Vise-authored capability checklist for an outcome (for `vise plan` feed-forward). */
+const BASELINE_CAPABILITY_IDS_BY_OUTCOME = {
+    "add-feed": ["pagination"],
+};
+function baselineCapabilities(outcome) {
+    const caps = CAPABILITIES.filter((c) => c.outcomes.includes(outcome));
+    const baselineIds = BASELINE_CAPABILITY_IDS_BY_OUTCOME[outcome];
+    if (!baselineIds) {
+        return caps;
+    }
+    const baseline = new Set(baselineIds);
+    return caps.filter((capability) => baseline.has(capability.id));
+}
+/** The Vise-authored baseline capability checklist for an outcome. */
 export function capabilityChecklist(outcome) {
-    return CAPABILITIES.filter((c) => c.outcomes.includes(outcome)).map((c) => ({ id: c.id, label: c.label, hint: c.hint }));
+    return baselineCapabilities(outcome).map((c) => ({ id: c.id, label: c.label, hint: c.hint }));
+}
+/** Optional feed-forward choices. These are not baseline completeness requirements. */
+export function optionalCapabilityChecklist(outcome) {
+    return OPTIONAL_CAPABILITIES.filter((c) => c.outcomes.includes(outcome)).map((c) => ({ id: c.id, label: c.label, hint: c.hint }));
+}
+export function selectedOptionalCapabilityIds(outcome, answers = {}, _request = "") {
+    const candidates = OPTIONAL_CAPABILITIES.filter((capability) => capability.outcomes.includes(outcome));
+    if (candidates.length === 0) {
+        return [];
+    }
+    const answerText = [answers.feed_optional_capabilities, answers.optional_capabilities, answers.selected_capabilities]
+        .filter(Boolean)
+        .join("\n");
+    const normalized = answerText.toLowerCase();
+    if (!normalized.trim() || /\b(none|no optional|default only)\b/.test(normalized)) {
+        return [];
+    }
+    const selected = new Set();
+    for (const capability of candidates) {
+        if (normalized.includes(capability.id.toLowerCase()) || capability.aliases.some((alias) => alias.test(answerText))) {
+            selected.add(capability.id);
+        }
+    }
+    return [...selected].sort();
+}
+export function assessSelectedOptionalCapabilities(source, outcome, selectedIds = []) {
+    const selected = [...new Set(selectedIds.map((id) => id.trim()).filter(Boolean))].sort();
+    if (selected.length === 0) {
+        return null;
+    }
+    const applicable = new Map(OPTIONAL_CAPABILITIES.filter((capability) => capability.outcomes.includes(outcome)).map((capability) => [capability.id, capability]));
+    const passed = [];
+    const failed = [];
+    const unknown = [];
+    for (const id of selected) {
+        const capability = applicable.get(id);
+        if (!capability) {
+            unknown.push(id);
+            continue;
+        }
+        const present = capability.sensors.filter((sensor) => sensor.regex.test(source)).map((sensor) => sensor.label);
+        const missing = capability.sensors.filter((sensor) => !sensor.regex.test(source)).map((sensor) => sensor.label);
+        if (missing.length === 0) {
+            passed.push({ id, label: capability.label, present });
+        }
+        else {
+            failed.push({ id, label: capability.label, missing, hint: capability.hint });
+        }
+    }
+    return {
+        outcome,
+        selected,
+        passed,
+        failed,
+        unknown,
+        note: "Selected optional capabilities are enforced only after the user or host agent opts in through `feed_optional_capabilities`. They are source sensors, not baseline compliance rules.",
+    };
 }
 /** Pure assessment over already-read source text. */
 export function assessCompleteness(source, outcome) {
-    const caps = CAPABILITIES.filter((c) => c.outcomes.includes(outcome));
+    const caps = baselineCapabilities(outcome);
     const optOuts = new Map();
     const invalidOptOuts = new Map();
     const omitPattern = /vise:\s*scope-omit\s+([a-z][\w-]*)\s*(?:[—:|-]+\s*(.*))?/gi;
@@ -422,9 +530,15 @@ const SKIP_DIRS = new Set(["node_modules", ".git", "dist", "build", ".next", "ou
 const MAX_FILES = 1500;
 const MAX_FILE_BYTES = 1_000_000;
 export async function assessProjectCompleteness(root, outcome) {
-    if (CAPABILITIES.every((c) => !c.outcomes.includes(outcome))) {
+    if (baselineCapabilities(outcome).length === 0) {
         return null; // outcome has no completeness checklist
     }
+    return assessCompleteness(await readProjectSource(root), outcome);
+}
+export async function assessProjectSelectedOptionalCapabilities(root, outcome, selectedIds = []) {
+    return assessSelectedOptionalCapabilities(await readProjectSource(root), outcome, selectedIds);
+}
+async function readProjectSource(root) {
     const resolved = path.resolve(root);
     const parts = [];
     const stack = [resolved];
@@ -462,5 +576,5 @@ export async function assessProjectCompleteness(root, outcome) {
             }
         }
     }
-    return assessCompleteness(parts.join("\n"), outcome);
+    return parts.join("\n");
 }

package/dist/server.js

@@ -15,6 +15,7 @@ import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
 import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
 import { runSensorsTool } from "./tools/sensors.js";
 import { getSdkFactsTool } from "./tools/sdkFacts.js";
+import { addBlockInstall, listRegistryBlocks, planBlockInstall, validateBlockInstall } from "./tools/blocks.js";
 import { debugIssueTool, debugIssue } from "./tools/debug.js";
 import { packageName, packageVersion } from "./version.js";
 const tools = new Map([
@@ -217,9 +218,62 @@ async function handleCli(args) {
             });
             return "exit";
         }
+        if (command === "blocks") {
+            const sub = args[1];
+            const subArgs = args.slice(2);
+            if (sub === "list") {
+                assertOnlyKnownFlags(subArgs, ["registry", "format"], "blocks list");
+                assertJsonFormat(subArgs, "blocks list");
+                console.log(JSON.stringify(await listRegistryBlocks(requiredFlagValue(subArgs, "registry", "blocks list requires --registry.")), null, 2));
+                return "exit";
+            }
+            if (sub === "plan") {
+                assertOnlyKnownFlags(subArgs, ["block", "surface", "surface-path", "registry", "format"], "blocks plan");
+                assertJsonFormat(subArgs, "blocks plan");
+                console.log(JSON.stringify(await planBlockInstall({
+                    repoPath: positionalRepoPath(subArgs),
+                    blockId: requiredFlagValue(subArgs, "block", "blocks plan requires --block."),
+                    registryPath: requiredFlagValue(subArgs, "registry", "blocks plan requires --registry."),
+                    surfacePath: flagValue(subArgs, "surface") ?? flagValue(subArgs, "surface-path"),
+                }), null, 2));
+                return "exit";
+            }
+            if (sub === "add") {
+                assertOnlyKnownFlags(subArgs, ["block", "surface", "surface-path", "registry", "package-source", "dry-run", "apply", "format"], "blocks add");
+                assertJsonFormat(subArgs, "blocks add");
+                console.log(JSON.stringify(await addBlockInstall({
+                    repoPath: positionalRepoPath(subArgs),
+                    blockId: requiredFlagValue(subArgs, "block", "blocks add requires --block."),
+                    registryPath: requiredFlagValue(subArgs, "registry", "blocks add requires --registry."),
+                    surfacePath: flagValue(subArgs, "surface") ?? flagValue(subArgs, "surface-path"),
+                    packageSource: flagValue(subArgs, "package-source"),
+                    dryRun: hasFlag(subArgs, "dry-run"),
+                    apply: hasFlag(subArgs, "apply"),
+                }), null, 2));
+                return "exit";
+            }
+            if (sub === "validate") {
+                assertOnlyKnownFlags(subArgs, ["block", "surface", "surface-path", "registry", "format"], "blocks validate");
+                assertJsonFormat(subArgs, "blocks validate");
+                console.log(JSON.stringify(await validateBlockInstall({
+                    repoPath: positionalRepoPath(subArgs),
+                    blockId: flagValue(subArgs, "block"),
+                    registryPath: requiredFlagValue(subArgs, "registry", "blocks validate requires --registry."),
+                    surfacePath: flagValue(subArgs, "surface") ?? flagValue(subArgs, "surface-path"),
+                }), null, 2));
+                return "exit";
+            }
+            console.error(`Unknown blocks subcommand: ${sub ?? "(none)"}. Expected "list", "plan", "add", or "validate".`);
+            process.exitCode = 1;
+            return "exit";
+        }
         if (command === "init") {
-            assertOnlyKnownFlags(args, ["request", "surface", "surface-path"], "init");
-            console.log(JSON.stringify(await initCompliance(positionalRepoPath(args.slice(1)), requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path")), null, 2));
+            assertOnlyKnownFlags(args, ["request", "surface", "surface-path", "answer", "allow-unresolved-intake"], "init");
+            const result = await initCompliance(positionalRepoPath(args.slice(1)), requiredFlagValue(args, "request", "init requires --request."), flagValue(args, "surface") ?? flagValue(args, "surface-path"), keyValueFlag(args, "answer"), { allowUnresolvedIntake: hasFlag(args, "allow-unresolved-intake") });
+            if (result.status === "needs-clarification" && typeof result.exitCode === "number") {
+                process.exitCode = result.exitCode;
+            }
+            console.log(JSON.stringify(result, null, 2));
             return "exit";
         }
         if (command === "check") {
@@ -494,6 +548,20 @@ Usage:
   vise sdk-facts --platform typescript --capability comments --format json
   vise sdk-facts --platform react-native --capability reactions --include-symbols
   vise sdk-facts --platform android --surface-dir ./sdk-surface --format json`;
+    }
+    if (command === "blocks") {
+        return `${packageName} blocks
+
+Install and validate social.plus Block Factory blocks inside customer projects.
+
+Usage:
+  vise blocks list --registry <path> --format json
+  vise blocks plan <repoPath> --block comments --registry <path> --format json
+  vise blocks add <repoPath> --block comments --registry <path> --package-source <npm|path|tarball> [--dry-run|--apply]
+  vise blocks validate <repoPath> [--block comments] --registry <path> --format json
+
+Safety:
+  Dry-run is the default. Apply mode only edits package manifests, explicit source anchors, and sp-vise/blocks.json.`;
     }
     if (command === "init") {
         return `${packageName} init
@@ -501,7 +569,10 @@ Usage:
 Initialize the local sp-vise compliance sidecar for one integration request.
 
 Usage:
-  vise init [repoPath] --request "Add a social feed" [--surface apps/web]`;
+  vise init [repoPath] --request "Add a social feed" [--surface apps/web]
+  vise init [repoPath] --request "Add a social feed" --answer feed_target="existing app community picker"
+  vise init [repoPath] --request "Add a social feed" --answer feed_optional_capabilities=post-poll-creation
+  vise init [repoPath] --request "Add a social feed" --allow-unresolved-intake`;
     }
     if (command === "check") {
         return `${packageName} check
@@ -604,6 +675,7 @@ Usage:
   vise validate [repoPath]         Validate setup and common risks
   vise run-sensors [repoPath]      Run detected project sensors
   vise sdk-facts --platform ...    Internal SDK surface facts for Block Factory
+  vise blocks ...                  Install and validate Block Factory blocks
   vise design extract <prototype>  Extract a design contract from an HTML/CSS prototype
   vise design check [repoPath]     Advisory (non-blocking) UI-vs-contract conformance report
   vise design preview [repoPath]   Write an HTML visual review of the contract + conformance
@@ -857,7 +929,7 @@ function ciCheckResult(result) {
     };
 }
 function positionalRepoPath(args) {
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
+    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference", "registry", "block", "package-source"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -879,7 +951,7 @@ function positionalRepoPath(args) {
 }
 function requiredPositionalText(args, message) {
     const values = [];
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
+    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "capability", "surface-dir", "format", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference", "registry", "block", "package-source"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -936,6 +1008,12 @@ function requiredFlagValue(args, name, message) {
     }
     return value;
 }
+function assertJsonFormat(args, commandName) {
+    const format = flagValue(args, "format") ?? "json";
+    if (format !== "json") {
+        throw new Error(`${commandName} currently supports --format json only.`);
+    }
+}
 function optionalNumberFlag(args, name) {
     const value = flagValue(args, name);
     if (!value) {