@amityco/social-plus-vise 0.8.1 → 0.12.2

package/dist/server.js

@@ -7,12 +7,14 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import { attestRule, attestRuleTool, checkCompliance, checkComplianceTool, explainRule, explainRuleTool, initCompliance, initComplianceTool, initEngagement, initEngagementTool, showEngagement, showEngagementTool, statusCompliance, syncCompliance, syncComplianceTool, } from "./tools/compliance.js";
+import { designCheckTool, designExtractTool, designPreviewTool } from "./tools/design.js";
 import { getDocPageTool, searchDocsTool } from "./tools/docs.js";
 import { planHarnessTool } from "./tools/harness.js";
 import { planIntegrationTool } from "./tools/integration.js";
 import { inspectProjectTool, validateSetupTool } from "./tools/project.js";
 import { resolveRequestTool, suggestPatchTool } from "./tools/resolve.js";
 import { runSensorsTool } from "./tools/sensors.js";
+import { debugIssueTool, debugIssue } from "./tools/debug.js";
 import { packageName, packageVersion } from "./version.js";
 const tools = new Map([
     searchDocsTool,
@@ -31,6 +33,10 @@ const tools = new Map([
     runSensorsTool,
     validateSetupTool,
     suggestPatchTool,
+    debugIssueTool,
+    designExtractTool,
+    designCheckTool,
+    designPreviewTool,
 ].map((tool) => [tool.name, tool]));
 const bundledSkillName = "social-plus-vise";
 const cliResult = await handleCli(process.argv.slice(2));
@@ -119,6 +125,32 @@ async function handleCli(args) {
             });
             return "exit";
         }
+        if (command === "debug") {
+            assertOnlyKnownFlags(args, ["error", "error-file", "brief"], "debug");
+            let errorMessage = flagValue(args, "error");
+            if (!errorMessage) {
+                const errorFile = flagValue(args, "error-file");
+                if (errorFile) {
+                    errorMessage = await readFile(path.resolve(errorFile), "utf8");
+                }
+                else if (!process.stdin.isTTY) {
+                    const { readFileSync } = await import("node:fs");
+                    try {
+                        errorMessage = readFileSync(0, "utf-8");
+                    }
+                    catch {
+                        errorMessage = undefined;
+                    }
+                }
+            }
+            if (!errorMessage) {
+                console.error("debug requires --error, --error-file, or piped stdin.");
+                process.exitCode = 1;
+                return "exit";
+            }
+            console.log(JSON.stringify(await debugIssue(positionalRepoPath(args.slice(1)), errorMessage, { brief: hasFlag(args, "brief") }), null, 2));
+            return "exit";
+        }
         if (command === "plan" || command === "plan-integration") {
             await printToolResult(planIntegrationTool, {
                 repoPath: positionalRepoPath(args.slice(1)),
@@ -229,6 +261,44 @@ async function handleCli(args) {
             process.exitCode = 1;
             return "exit";
         }
+        if (command === "design") {
+            const sub = args[1];
+            const subArgs = args.slice(2);
+            if (sub === "extract") {
+                assertOnlyKnownFlags(subArgs, ["repo", "no-write", "from-project"], "design extract");
+                if (hasFlag(subArgs, "from-project")) {
+                    await printToolResult(designExtractTool, {
+                        fromProject: true,
+                        repoPath: flagValue(subArgs, "repo") ?? positionalRepoPath(subArgs),
+                        write: !hasFlag(subArgs, "no-write"),
+                    });
+                    return "exit";
+                }
+                await printToolResult(designExtractTool, {
+                    prototypePath: requiredPositionalText(subArgs, "design extract requires a prototype path (file or directory), or use --from-project."),
+                    repoPath: flagValue(subArgs, "repo") ?? ".",
+                    write: !hasFlag(subArgs, "no-write"),
+                });
+                return "exit";
+            }
+            if (sub === "check") {
+                assertOnlyKnownFlags(subArgs, [], "design check");
+                await printToolResult(designCheckTool, { repoPath: positionalRepoPath(subArgs) });
+                return "exit";
+            }
+            if (sub === "preview") {
+                assertOnlyKnownFlags(subArgs, ["reference", "no-write"], "design preview");
+                await printToolResult(designPreviewTool, {
+                    repoPath: positionalRepoPath(subArgs),
+                    reference: flagValue(subArgs, "reference"),
+                    write: !hasFlag(subArgs, "no-write"),
+                });
+                return "exit";
+            }
+            console.error(`Unknown design subcommand: ${sub ?? "(none)"}. Expected "extract", "check", or "preview".`);
+            process.exitCode = 1;
+            return "exit";
+        }
     }
     catch (error) {
         console.error(error instanceof Error ? error.message : String(error));
@@ -349,6 +419,16 @@ Run deterministic social.plus setup validation for the current project.
 
 Usage:
   vise validate [repoPath] [--platform typescript] [--surface apps/web]`;
+    }
+    if (command === "debug") {
+        return `${packageName} debug
+
+Correlate an SDK-specific runtime failure to likely compliance issues and emit a minimal repair brief.
+
+Usage:
+  vise debug [repoPath] --error "401 Unauthorized: TokenExpiredException during social.plus session renewal"
+  vise debug [repoPath] --error-file logs/crash.log
+  vise debug [repoPath] --error-file logs/crash.log --brief`;
     }
     if (command === "run-sensors" || command === "run-sensor" || command === "run_sensor") {
         return `${packageName} run-sensors
@@ -414,6 +494,34 @@ Print a compact compliance summary.
 Usage:
   vise status [repoPath]`;
     }
+    if (command === "design") {
+        return `${packageName} design
+
+Design-contract tooling for social.plus UI generation.
+
+Usage:
+  vise design extract <prototypePath> [--repo .] [--no-write]
+  vise design extract --from-project [repoPath] [--no-write]
+  vise design check [repoPath]
+  vise design preview [repoPath] [--reference <prototypePath>]
+
+extract  Build a graded design contract and write it to sp-vise/design-contract.json.
+         Declared CSS custom properties become exact tokens; repeated literal values
+         become inferred (advisory) tokens; single-use literals are treated as one-offs.
+         With --from-project (no external prototype), derive the contract from the host
+         project's OWN design system: CSS custom properties (incl. shadcn :root and
+         Tailwind v4 @theme), TS/JS token modules, inline tailwind configs, Android
+         colors.xml/dimens.xml, Flutter Color(0x..), and iOS .xcassets/.colorset +
+         Swift colors. Reference values (var()/theme()/calc()) are skipped, so a
+         var-mapped config contributes nothing rather than wrong tokens.
+check    Advisory, non-blocking report on how closely the project's UI code
+         matches the contract (token coverage + on/off-contract color literals).
+         Never fails a build; it is NOT a \`vise check\` gate.
+preview  Write a self-contained sp-vise/design-preview.html: the contract's tokens
+         as visual swatches + the conformance report + the HTML reference embedded
+         (with --reference) for side-by-side review. Vise renders; a human/VLM
+         judges the visual match. Dependency-free — NOT an automated pixel diff.`;
+    }
     return `${packageName}
 
 Skill-guided deterministic CLI for social.plus SDK integration assistance.
@@ -425,6 +533,7 @@ Usage:
   vise install-skill --target codex Install bundled skill guidance
   vise print-skill                 Print bundled skill markdown
   vise inspect [repoPath]          Inspect platform and design signals
+  vise debug [repoPath] --error ... Debug an SDK-specific runtime error and emit a repair brief
   vise plan [repoPath] --request "..." Create an implementation plan
   vise init [repoPath] --request "..." Initialize compliance sidecar
   vise check [repoPath]            Check compliance contract
@@ -434,6 +543,9 @@ Usage:
   vise status [repoPath]           Print compliance summary
   vise validate [repoPath]         Validate setup and common risks
   vise run-sensors [repoPath]      Run detected project sensors
+  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
   vise doctor                      Print install diagnostics
   vise --help                      Show this help
   vise --version                   Show package version
@@ -557,7 +669,7 @@ function skillPathResult() {
     return {
         skill: bundledSkillName,
         source: skillSourceDir(),
-        files: ["SKILL.md"],
+        files: ["SKILL.md", "reference/debugging.md", "reference/operations.md"],
         installExamples: [
             "vise install-skill --target codex",
             "vise install-skill --target claude",
@@ -658,7 +770,7 @@ function ciCheckResult(result) {
     };
 }
 function positionalRepoPath(args) {
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale"]);
+    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {
@@ -680,7 +792,7 @@ function positionalRepoPath(args) {
 }
 function requiredPositionalText(args, message) {
     const values = [];
-    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale"]);
+    const flagsWithValues = new Set(["request", "surface", "surface-path", "platform", "include", "timeout-ms", "query", "path", "limit", "answer", "target", "dest", "destination", "rule", "confidence", "signer", "identity", "evidence-file", "rationale", "repo", "reference"]);
     for (let index = 0; index < args.length; index += 1) {
         const arg = args[index];
         if (!arg) {

package/dist/tools/ast.js

@@ -67,13 +67,38 @@ function getParser(language) {
     }
     return parser;
 }
+// node-tree-sitter's native parser rejects sufficiently large inputs with a
+// native "Invalid argument" error (~32KB string limit). It IS catchable, but an
+// unguarded caller would otherwise abort the whole validate run. We short-circuit
+// before the native call so callers get a clean, documented, catchable error and
+// can degrade to regex-only for that file. Real codebases routinely have files
+// past this size (1000+ line activities/view controllers).
+export const MAX_PARSE_BYTES = 30000;
 /**
  * Parse source content into a tree-sitter syntax tree.
+ * Throws on oversized input (see MAX_PARSE_BYTES) — callers that want graceful
+ * degradation should use tryParse or wrap this in try/catch.
  */
 export function parse(language, source) {
+    if (Buffer.byteLength(source, "utf8") > MAX_PARSE_BYTES) {
+        throw new Error(`source exceeds tree-sitter parse limit (${Buffer.byteLength(source, "utf8")} bytes > ${MAX_PARSE_BYTES})`);
+    }
     const parser = getParser(language);
     return parser.parse(source);
 }
+/**
+ * Parse, returning null instead of throwing when the source can't be parsed
+ * (oversized input, native parser error). Lets validators skip AST analysis for
+ * one file and fall back to regex without aborting the run.
+ */
+export function tryParse(language, source) {
+    try {
+        return parse(language, source);
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Find all call expressions in the tree whose callee matches a pattern.
  * Returns normalised callee strings and argument nodes.

package/dist/tools/compliance.js

@@ -2,9 +2,11 @@ import { createHash, randomUUID } from "node:crypto";
 import { mkdir, readdir, readFile, rm, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { assessProjectCompleteness } from "../capabilities.js";
 import { classifyOutcome } from "../outcomes.js";
 import { objectInput, optionalStringField, stringField, textResult } from "../types.js";
 import { packageVersion } from "../version.js";
+import { readDesignContract } from "./design.js";
 import { inspectProject, validateSetup } from "./project.js";
 const complianceDirName = "sp-vise";
 const attestationsDirName = "attestations";
@@ -161,7 +163,7 @@ function stringArray(value) {
     return value.filter((item) => typeof item === "string" && item.trim() !== "");
 }
 const validTiers = new Set(["free", "pro", "partner"]);
-const validOutcomes = new Set(["setup-sdk", "setup-push", "setup-live-data", "add-feed", "troubleshoot", "validate-setup", "unknown"]);
+const validOutcomes = new Set(["setup-sdk", "setup-push", "setup-live-data", "add-feed", "add-comments", "add-moderation", "add-chat", "troubleshoot", "validate-setup", "unknown"]);
 export async function initEngagement(args) {
     const repoRoot = path.resolve(args.repoPath);
     const engagementFile = engagementPath(repoRoot);
@@ -227,23 +229,45 @@ export async function initCompliance(repoPath, request, surfacePath) {
     const inspection = await inspectProject(repoRoot, surfacePath);
     const outcome = classifyOutcome(request);
     const rules = await applicableRules(outcome, inspection.platforms);
-    const refs = rules.map(ruleRef);
+    const refs = rules.map(ruleRef); // minimal shape — stable digest input
+    const fileRefs = rules.map(ruleRefForFile); // adds title for human/agent readers
     const engagement = await readEngagement(repoRoot);
+    const designContract = await readDesignContract(repoRoot);
     const compliance = {
         schema_version: schemaVersion,
         foundry_version: packageVersion,
-        ruleset_digest: digestJson(refs),
+        ruleset_digest: digestJson(refs), // hash of minimal refs (no title)
         generated_at: new Date().toISOString(),
         last_synced_at: null,
         outcome,
         engagement_id: engagement?.engagement_id,
         surface: inspection.selectedSurface ? { path: inspection.selectedSurface.path, platforms: inspection.selectedSurface.platforms } : undefined,
-        rules: refs,
+        rules: fileRefs, // file carries titles
+        design_contract: designContract
+            ? {
+                digest: designContract.digest,
+                strength: designContract.stats.strength,
+                source_kind: designContract.source.kind,
+                declared_tokens: designContract.stats.declared_tokens,
+                inferred_tokens: designContract.stats.inferred_tokens,
+            }
+            : undefined,
     };
     await mkdir(attestationsDir(repoRoot), { recursive: true });
     await writeJson(compliancePath(repoRoot), compliance);
     await writeJson(path.join(sidecarDir(repoRoot), "inspection.json"), inspection);
     await writeFile(path.join(sidecarDir(repoRoot), "README.md"), sidecarReadme(compliance), "utf8");
+    // Write a frozen check snapshot so agents can see current rule status immediately
+    // without having to run vise check themselves.
+    const checkSnapshot = await checkCompliance(repoPath);
+    await writeJson(path.join(sidecarDir(repoRoot), "findings.json"), {
+        snapshot_at: compliance.generated_at,
+        note: "Snapshot taken at vise init time. Re-run `vise check .` after editing code to see current status.",
+        outcome: checkSnapshot.outcome,
+        status: checkSnapshot.status,
+        summary: checkSnapshot.summary,
+        rules: checkSnapshot.rules,
+    });
     const warnings = [];
     if (engagement && engagement.scope.outcomes.length > 0 && !engagement.scope.outcomes.includes(outcome)) {
         warnings.push(`Outcome "${outcome}" is not in the engagement scope (${engagement.scope.outcomes.join(", ")}). Compliance was still initialized; extend the scope in engagement.json or re-run vise engagement init.`);
@@ -255,12 +279,13 @@ export async function initCompliance(repoPath, request, surfacePath) {
         surfacePath: inspection.selectedSurface?.path,
         rules: refs.length,
         engagement_id: engagement?.engagement_id,
+        ...(compliance.design_contract && { design_contract: compliance.design_contract }),
         ...(warnings.length > 0 && { warnings }),
         nextStep: "Run vise check, then implement until rules pass deterministically or are attested.",
     };
 }
 export async function applicableComplianceRuleSummaries(outcome, platforms) {
-    return (await applicableRules(outcome, platforms)).map(ruleRef);
+    return (await applicableRules(outcome, platforms)).map(ruleRefForFile);
 }
 export async function checkCompliance(repoPath) {
     const repoRoot = path.resolve(repoPath);
@@ -278,8 +303,12 @@ export async function checkCompliance(repoPath) {
         };
     }
     const inspection = await inspectProject(repoRoot, compliance.surface?.path === "." ? undefined : compliance.surface?.path);
-    const platform = inspection.platforms[0] ?? "unknown";
-    const findings = await validateSetup(inspection.effectiveRoot, platform);
+    const detectedPlatforms = inspection.platforms;
+    const recordedPlatforms = compliance.surface?.platforms || [];
+    const platformsToValidate = Array.from(new Set([...detectedPlatforms, ...recordedPlatforms]));
+    const platforms = platformsToValidate.length > 0 ? platformsToValidate : ["unknown"];
+    const allFindings = await Promise.all(platforms.map((p) => validateSetup(inspection.effectiveRoot, p)));
+    const findings = allFindings.flat();
     const findingsById = new Map(findings.map((finding) => [finding.ruleId, finding]));
     const attestations = await readAttestations(repoRoot);
     const results = [];
@@ -295,6 +324,7 @@ export async function checkCompliance(repoPath) {
         // user knows what to provide.
         const blockersFired = await runBlockers(rule, inspection.effectiveRoot);
         if (blockersFired.length > 0) {
+            const attestable = rule.enforcement.attestation.allowed;
             results.push({
                 ruleId: rule.id,
                 title: rule.title,
@@ -303,11 +333,16 @@ export async function checkCompliance(repoPath) {
                 reason: blockersFired.map((blocker) => blocker.reason).join(" "),
                 blockers_fired: blockersFired,
                 current_rule: ruleSummary(rule),
+                ...(attestable && {
+                    next_step: `Provide the file(s) listed in blockers_fired, then run \`vise attest . --rule ${rule.id}\` to record your review decision.`,
+                }),
             });
             continue;
         }
-        const finding = deterministicFinding(rule, findingsById);
-        if (!finding) {
+        const hasDeterministicChecks = (rule.enforcement.deterministic ?? []).length > 0;
+        const isInferential = !hasDeterministicChecks && !!rule.enforcement.inferential;
+        const finding = hasDeterministicChecks ? deterministicFinding(rule, findingsById) : undefined;
+        if (hasDeterministicChecks && !finding) {
             results.push({
                 ruleId: rule.id,
                 title: rule.title,
@@ -332,12 +367,14 @@ export async function checkCompliance(repoPath) {
                         ? "Current deterministic check failed; previously synced deterministic-pass evidence is stale."
                         : "Current deterministic check failed; this rule does not allow attestation.",
                     finding,
-                    recommendation: finding.recommendation,
+                    recommendation: finding?.recommendation,
+                    rationale: rule.rationale,
                     current_rule: ruleSummary(rule),
                 });
                 continue;
             }
-            const exactMatch = attestation.rule_digest === ref.rule_digest && attestation.ruleset_digest === compliance.ruleset_digest;
+            // ruleset_digest is audit metadata; contractDrift above already guarantees the installed ruleset matches compliance.json.
+            const exactMatch = attestation.rule_digest === ref.rule_digest;
             const grandfathered = !exactMatch && isAttestationGrandfathered(rule, attestation);
             if (exactMatch || grandfathered) {
                 const sourceFingerprintStatus = await checkSourceFingerprints(repoRoot, inspection.effectiveRoot, attestation.source_fingerprints ?? []);
@@ -350,7 +387,8 @@ export async function checkCompliance(repoPath) {
                         status: rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
                         reason: "Recorded attestation source fingerprints changed. Re-check the evidence and record a fresh attestation.",
                         finding,
-                        recommendation: finding.recommendation,
+                        recommendation: finding?.recommendation,
+                        rationale: rule.rationale,
                         current_rule: ruleSummary(rule),
                         source_fingerprint_status: sourceFingerprintStatus,
                     });
@@ -375,15 +413,24 @@ export async function checkCompliance(repoPath) {
                 continue;
             }
         }
+        const baseStatus = (rule.enforcement.attestation.allowed || isInferential) ? "attestation-needed" : "deterministic-fail";
+        let fallbackReason = "This rule does not allow attestation.";
+        if (isInferential) {
+            fallbackReason = "Inferential check required. Please provide a host-agent attestation.";
+        }
+        else if (rule.enforcement.attestation.allowed) {
+            fallbackReason = "Deterministic check failed and no valid attestation exists.";
+        }
         results.push({
             ruleId: rule.id,
             title: rule.title,
             severity: rule.severity,
-            status: rule.enforcement.attestation.allowed ? "attestation-needed" : "deterministic-fail",
-            reason: rule.enforcement.attestation.allowed ? "Deterministic check failed and no valid attestation exists." : "This rule does not allow attestation.",
+            status: baseStatus,
+            reason: fallbackReason,
             finding,
-            recommendation: finding.recommendation,
+            recommendation: finding?.recommendation,
             current_rule: ruleSummary(rule),
+            ...(isInferential && { inferential_prompt: rule.enforcement.inferential?.prompt })
         });
     }
     const summary = summarize(results);
@@ -392,6 +439,10 @@ export async function checkCompliance(repoPath) {
     const needsAttestation = results.some((result) => result.status === "attestation-needed" || result.status === "stale");
     // Precedence: blocked (exit 3) > deterministic-failures (2) > needs-attestation (1) > green (0).
     // Contract drift (exit 4) is handled earlier and short-circuits the loop.
+    // Advisory feature-completeness — surfaced but NEVER part of status/exitCode
+    // (completeness is a "this is missing" claim, structurally FP-prone; see the
+    // validation-boundaries principle). Failure to assess is silently ignored.
+    const completeness = (await assessProjectCompleteness(inspection.effectiveRoot, compliance.outcome).catch(() => null)) ?? undefined;
     // Blocked wins because the agent cannot proceed without customer input;
     // surfacing a smaller failure first would distract from the real blocker.
     return {
@@ -407,6 +458,7 @@ export async function checkCompliance(repoPath) {
         surfacePath: compliance.surface?.path,
         summary,
         rules: results,
+        ...(completeness && (completeness.missing.length > 0 || completeness.optedOut.length > 0 || completeness.present.length > 0) ? { completeness } : {}),
     };
 }
 export async function syncCompliance(repoPath) {
@@ -503,12 +555,14 @@ export async function statusCompliance(repoPath) {
     const repoRoot = path.resolve(repoPath);
     const check = await checkCompliance(repoPath);
     const engagement = await readEngagement(repoRoot);
+    const compliance = await readCompliance(repoRoot).catch(() => null);
     return {
         status: check.status,
         exitCode: check.exitCode,
         outcome: check.outcome,
         surfacePath: check.surfacePath,
         summary: check.summary,
+        ...(compliance?.design_contract && { design_contract: compliance.design_contract }),
         ...(engagement && {
             engagement: {
                 engagement_id: engagement.engagement_id,
@@ -542,7 +596,7 @@ async function loadRuleFiles() {
     }
     return loaded;
 }
-async function rulesById() {
+export async function rulesById() {
     const rules = (await loadRuleFiles()).flatMap((file) => file.rules);
     return new Map(rules.map((rule) => [rule.id, rule]));
 }
@@ -554,6 +608,11 @@ function ruleRef(rule) {
         severity: rule.severity,
     };
 }
+// Extends ruleRef with the human-readable title for file output (compliance.json,
+// applicableRules in integration plans). Not used for digest computation.
+function ruleRefForFile(rule) {
+    return { ...ruleRef(rule), title: rule.title };
+}
 function contractDrift(compliance, rules) {
     const results = [];
     const refs = compliance.rules.map((ref) => {
@@ -860,8 +919,11 @@ async function readAttestations(repoRoot) {
             continue;
         }
         const attestation = await readJsonIfExists(path.join(dir, entry));
-        if (attestation?.rule_id) {
-            result.set(attestation.rule_id, attestation);
+        if (attestation?.rule_id && attestation.payload_hash) {
+            const { payload_hash, ...withoutHash } = attestation;
+            if (digestJson(withoutHash) === payload_hash) {
+                result.set(attestation.rule_id, attestation);
+            }
         }
     }
     return result;
@@ -898,8 +960,14 @@ function sidecarReadme(compliance) {
         `- Rules: ${compliance.rules.length}`,
         `- Generated: ${compliance.generated_at}`,
         "",
-        "Run `vise check` to verify current status and `vise sync` to persist deterministic-pass evidence.",
-        "Host-agent and human attestations include source fingerprints for cited files; `vise check` marks them stale if those files change.",
+        "## Quick start",
+        "",
+        "1. Read `findings.json` — it contains a snapshot of rule status taken at init time, including any violations found in the current code.",
+        "2. Fix the issues listed in `findings.json`, then run `npm run sp-check` (or `vise check .` if vise is on PATH) to verify.",
+        "3. Run `vise sync .` to persist deterministic-pass evidence once rules are green.",
+        "4. Run `vise attest . --rule <rule-id> ...` to sign off on intentional implementation decisions.",
+        "",
+        "Attestations include source fingerprints; `vise check` marks them stale if the cited files change.",
         "",
     ].join("\n");
 }