@amityco/social-plus-vise 0.14.28 → 1.0.0

package/CHANGELOG.md

@@ -4,8 +4,48 @@ 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).
 
+## 1.0.0 — 2026-06-11
+
+**First stable release.** 1.0 is a stability promise about the contract surface, not a new feature: `vise check` exit codes (0–7) and their precedence, the `sp-vise/` sidecar formats (with backward-read + attestation grandfathering now gated by `test:sidecar-compat`), the CLI command and MCP tool surface, the skill's required loop, and the `packages/schemas` wire formats are now under semver — breaking changes require a major bump. See [`docs/V1_READINESS.md`](docs/V1_READINESS.md) for the decision package and evidence basis (5-platform deterministic E2E journeys with all exit codes asserted on every commit; real-agent semantic matrix; three brownfield pilots green with zero Vise findings). This release consolidates everything developed across the 0.14.x-dev line after the published 0.14.28 (block-aware completeness): the items below plus the platform-hardening and model-facts work noted under the 0.14.28 entry, which reached npm here.
+
+### Changed
+- **Skill: prefer installable blocks over hand-building.** When a Block Factory registry is available, agents are taught to check it first and use the governed `vise blocks` install path, hand-building only the remaining gaps — backed by the 2026-06-10 semantic-matrix measurement (installed path ~9× faster to green than hand-building the same outcome). No registry means hand-build as normal; block existence stays the registry's truth.
+
+### Added
+- **False-negative discovery lane — the third compass (`docs/FN_DISCOVERY.md`).** Vise already had a TP-detection compass (`bench/tp-dashboard.mjs`, seeded from the rules so circular) and an FP compass (happy-path-clean + clone cells + pilots) but NO systematic false-NEGATIVE discovery — violations the rule corpus misses only surfaced by accident. This lane closes that, mirroring the semantic lane's two-half split:
+  - **Measured lane (periodic, never CI)** — `benchmarks/fn-discovery/run-fn-discovery.mjs`: for a chosen rule, hand a real coding agent the rule's INTENT (title + rationale from `rules/*.yaml`, NOT its detector) and ask for SDK-using samples that violate that intent in novel ways; run `vise validate --json` over each; grade CAUGHT vs MISSED; write append-only dated evidence (samples + validate output + `FINDINGS.md`) under `benchmarks/fn-discovery/runs/<date>-<rule>-<generator>/`. Scoped first to TypeScript × secrets/ban-state/feed-target/session-lifecycle. Generator policy mirrors the semantic lane (default `agy`; `agent`; `claude` pinned to Sonnet). Built and proven with a **deterministic STUB generator** (default) so the grading core is testable without spawning agents or spending tokens; the real-agent path is wired but invoked only with `--generator`, and the live discovery round runs later with explicit human authorization.
+  - **Deterministic gate (CI)** — `test/run-fn-regression.mjs` (`test:fn-regression`): a frozen corpus under `test/fixtures/fn-regression/` of previously-discovered false negatives. `fires` entries assert a rule now fires on a committed sample of a class it once missed (so a fixed blind spot can't silently return); seed entries are realistic catches labeled scaffold so the gate is real and grows; quarantined entries are REAL discovered misses asserted to stay missed until a fix lands, then the gate flips loud and the entry is promoted. The gate never patches a rule — fixes are harness-engineering work with their own review.
+  - **Self-test** — `test/run-fn-discovery-selftest.mjs` (`test:fn-discovery-selftest`): runs the stub samples through the real validator + real grader and asserts every CAUGHT/MISSED/CLEAN-OK verdict against the stub's oracle, locking down the lane's plumbing. Both new gates run in `validate` right after `test:harness-e2e`.
+  - **Real false negatives discovered while building (TypeScript):** (1) `secret.inline-api-key` missed a hardcoded key re-wrapped through a template string before `createClient` (`resolveLiteralValue` resolved direct literals only); (2) `feed.target.literal` missed a feed-target literal re-bound through a second const before `createPost` (the AST resolver followed one identifier hop); (3) `feed.target.literal` missed a hardcoded feed target when the `createPost` payload carried an `as any` cast (`pickObjectProperty` required a bare object node). Controls proved the rules fire at the single-hop / un-cast forms. **All three were then fixed in this release** (see Fixed, below); their corpus entries are promoted from quarantine to `fires`, so each blind spot can never silently reopen.
+- **iOS and Flutter model facts upgraded to `names-and-types`** (previously names-only): `scripts/extract-sdk-models.mjs` now grounds both platforms in typed sources instead of the type-less docs-ops surface exports, completing the per-platform grounding table (typescript/android/ios/flutter all names-and-types). Wire format unchanged (`2026-06-10.sdk-model-facts.v1` — names-and-types was already a legal grounding); the `extraction.sourceKind` enum gains `sdk-swiftmodule-abi` and `sdk-source-dart` in `packages/schemas`.
+  - **iOS** — parsed from the prebuilt AmitySDK xcframework's Swift module ABI JSON, canonically the **`ios-arm64` device slice** (the architecture customers ship and the only single-arch slice; the simulator slices were diffed member-for-member identical for the target models). Fields carry the compiler-printed Swift type (`Swift.String?`, `[AmitySDK.AmityCommentAttachment]`) and Optional-wrapper nullability; `declaredIn` stays `null` because a prebuilt binary has no source locations. Discovery follows the import script's pattern: `--ios-abi-json` / `SP_IOS_ABI_JSON`, then the docs-repo-relative `.docs-ops/integration-tests/ios/vendor/AmitySDK.xcframework/...` location beside the surface dir.
+  - **Flutter** — parsed from the local Flutter SDK sources by the new `scripts/dart-model-extractor` helper (package:analyzer `parseString`, **syntax-only**: verbatim declared types and literal `?` nullability, no resolution or inference; analyzer version pinned by the committed `pubspec.lock` and recorded in the extraction provenance). Public instance fields and getters only; untyped members are skipped rather than invented. Real file:line anchors into the SDK checkout. Discovery: `--flutter-sdk-root` / `SP_FLUTTER_SDK_ROOT`, then the `Amity-Social-Cloud-SDK-Flutter-Internal` checkout beside `social-plus-docs`.
+  - **Degradation, recorded:** when the `.abi.json`, the Flutter checkout, or the `dart` toolchain is unreachable at import time, the platform falls back to the previous names-only surface-export extraction and the manifest records a `degradedReason` — grounding never exceeds what the reachable source proves, and the snapshot gates refuse a degraded re-import of the committed names-and-types artifacts. npm tarball 495.2 kB → 503.9 kB (regenerated typed snapshots + the Dart helper).
+
+### Verified (typed iOS/Flutter model facts)
+- `test:sdk-surface` locks the new grounding with real extracted fields: iOS `AmityComment.commentId` as required `Swift.String` and `parentId` as optional `Swift.String?` from the arm64 abi.json (plus all-fields-typed and no-source-locations invariants), Flutter `AmityComment.commentId` as nullable `String?` property anchored to `lib/src/domain/model/amity_comment.dart` and `AmityUser.isFlaggedByMe` as a non-nullable `bool` getter.
+- `test:sdk-facts` serves the typed schemas end to end (`AmityPost.postId` → `Swift.String` on iOS; source-anchored `AmityComment` on Flutter) with the new extractor ids recorded.
+- The schemas self-test now expects names-and-types on every platform and proves the extended `sourceKind` enum bites (doctored unknown sourceKind fails validation).
+- Block Factory seam unchanged by design: contracts are still TypeScript-provenance only, so `validate:sdk-facts` / `validate:adapters` pass untouched; the typed iOS/Flutter facts are ready for future native-platform `sdkProvenance`.
+
+### Verified
+- **Harness E2E platform matrix completed (`test:harness-e2e`):** the deterministic lane-1 journey now runs for **flutter** and **ios** alongside typescript and android — each with the complete journey, no partial credit (HARNESS_E2E.md). Per-platform discoveries baked into the gate: flutter/ios block on `feed_scope`/`feed_target`/`target_screen_or_route` only; `flutter-happy-path` *is* the add-feed gap state (zero-rule clean, no pagination affordance), so its known-good implementation is a structural Dart pagination helper (naming `AmityCollection` would trip the flutter `feed.ui-states-present` sensor); the ios pre-implementation state removes `AppTheme.swift` together with `FeedViewController.swift` because the feed view is the theme's only consumer (`ios.design.reuse-detected-tokens` would otherwise mask the exit-5 gap); the exit-2 injection reuses the rule-coverage-proven `flutter-rule-missing-guards` / `ios-rule-missing-guards` files, which pair the attestation-disallowed `<platform>.secret.inline-api-key` driver with attestation-level findings in one file.
+- **Exit-4 (`contract-drift`) stage:** every platform journey now tampers the recorded `rule_digest` of its feed-target rule in `sp-vise/compliance.json` and asserts `vise check --ci` exits **4** with status `contract-drift`, naming the drifted rule (`stale`, "Rule digest changed since vise init"); restoring the contract bytes restores green. Lane 1 now asserts all documented exit codes 0–7.
+- **Environment-aware iOS sensors stage:** the guarded xcodebuild sensor is asserted in *both* environments on every machine via a controlled `PATH` (stub toolchain → integrity probe + guarded build detected; empty `PATH` → the single skipped-with-reason precondition), so `test:harness-e2e` passes identically on darwin-with-Xcode and ubuntu CI without it.
+
+### Fixed
+- **Three confirmed TypeScript false negatives closed (resolver/extractor precision; behavior-parity — no rule id/severity/semantics change).** All three were surfaced by the FN-discovery lane above and verified with single-hop/un-cast controls: (1) `secret.inline-api-key` now resolves a pure-passthrough template (`` `${X}` `` ≡ `X`) — a committed production key re-wrapped through a template no longer ships undetected; (2) `feed.target.literal` now does bounded multi-hop identifier resolution (depth cap + cycle guard) so a const aliased through another const still resolves — and the shared resolver means **Kotlin/Swift re-bind chains benefit too**; (3) a new `unwrapExpression` peels `as`/`satisfies`/parenthesized/non-null wrappers before object-property extraction, so a hardcoded target inside `createPost({…} as any)` is caught (high-frequency, since agents emit `as any` constantly). Each broadening is guarded against false positives by a dedicated dynamic-clean canary (member-access / parameter / `process.env`-sourced values must stay clean), and `happy-path-clean` (the 5-platform FP canary) stays at zero findings.
+
+### Added (sidecar compatibility + hermetic docs)
+- **`test:sidecar-compat` — the backward-read gate (the semver promise 1.0 makes).** A frozen corpus of authentic `sp-vise/` sidecars generated by the real published `0.14.26` / `0.14.27` / `0.14.28` (`npx … vise init/sync/attest`, provenance recorded per version — not hand-authored) is replayed by the current build, asserting tolerant reads (no crash/parse-failure, coherent status, older `vise_version`/`foundry_version` tolerated, no unknown old-contract rule) and exercising attestation grandfathering live for the first time against a real v1-era host-agent attestation (`compatible_with` honored; `deprecated_versions` honored and flagged for re-attestation; empty `compatible_with` softens to `attestation-needed`, never a hard fail). Boundary: this covers backward reads (old sidecar, new build — the direction 1.0 promises), not forward compatibility.
+- **Hermetic docs CI mode (`VISE_DOCS_OFFLINE=1`).** Doc lookups can serve a committed `docs-cache/` corpus instead of fetching `learn.social.plus`; CI runs hermetic by default, killing the network-flake class. `test:docs-offline` proves zero network dependency (sinkhole host + 1 ms timeout, with an empty-corpus negative control that fails loudly rather than silently hitting the network); the live-fetch path is preserved off the critical path as `test:docs-live`.
+
 ## 0.14.28 — 2026-06-10
 
+> **Note (reconciled at 1.0.0):** the published npm `0.14.28` tarball shipped **block-aware completeness** (and the schemas-seam refactor). The platform-hardening (Swift tree-sitter AST, the guarded iOS build sensor) and field-level model facts described below were committed after that publish and first reached npm in **1.0.0** — they are documented here because that is where the work was authored; the version they shipped in is 1.0.0.
+
+
+
 **Theme:** block-aware completeness — install a block, end green. Plus platform-leg hardening: Swift gets the tree-sitter treatment and iOS gets a guarded build sensor.
 
 ### Added

package/README.md

@@ -89,13 +89,7 @@ The current milestone is the **Learning Engine sensor bridge with score calibrat
 
 ### 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:** 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, 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.
+Vise keeps two deliberately separate personas — the **customer-integration helper** (runs inside customer projects, may write `sp-vise/*`, including the `vise blocks` installer workflow) and the **Block Factory SDK-facts provider** (projectless, read-only, exports SDK symbol/capability/model facts). Vise owns SDK truth and customer-project governance; Block Factory owns the blocks. The canonical ownership table and the seam contracts live in [`../docs/BOUNDARY.md`](../docs/BOUNDARY.md); the provider-side design is [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md).
 
 ### Block Factory user experience
 
@@ -167,7 +161,7 @@ Aggregate: **98/99 expected feed capabilities** and **27/27 selected optional ca
 
 ### Current Release Validation
 
-Version 0.14.26 carries current release proof around the full feed-forward, product-expectation, creative pre-planning, and validation flow:
+Version 1.0.0 carries current release proof around the full feed-forward, product-expectation, creative pre-planning, block-aware completeness, and validation flow:
 
 | Surface | What was validated |
 |---|---|
@@ -180,7 +174,8 @@ Version 0.14.26 carries current release proof around the full feed-forward, prod
 | **Experience Score calibration guard** | Experience Report, Experience Sensors, and Learning Engine snapshots keep `score: null`, while `learning-summary.json` keeps `recommendationOptimization.status: "not-active"`. The shadow benchmark has 70 measured cells; `shadow-policy-v2-draft` independently ranked expected variants first in 21/21 registered ranking/cross-platform cells, its human gate package has named product FP/FN and privacy sign-off recorded, and runtime exposure is limited to the opt-in local `vise creative --ranking-preview` artifact. |
 | **Android workplan dogfood** | A brownfield Android music-player app refreshed under `0.14.24` reached `vise check` green with **43/43 deterministic passes** on the focused feed surface and recorded a green-check workplan snapshot. This is dogfood evidence, not a controlled multi-agent benchmark. |
 | **Shared product expectations** | Public IDs such as `feed.target-resolved`, `feed.post-type-scope-explicit`, `comments.creation-affordance`, `chat.channel-list-order-explicit`, `community.avatar-from-sdk`, `moderation.role-gated-action`, `follow.relationship-live`, `profile.identity-from-sdk`, `profile.social-counts`, and `notifications.tray-live` stay platform-agnostic while check results retain concrete `contractRuleId` and `validator.sensorId` evidence when deterministic sensors exist. |
-| **Rule detection** | TP-track dashboard detects **321/321 seeded rule gaps (100.0%)** in the static corpus. |
+| **Rule detection** | TP-track dashboard detects **100% of seeded rule gaps** in the static corpus (run `npm run bench:tp` for the current seeded count; `npm run validate`'s rule-coverage gate prints the full corpus size). |
+| **Block-aware completeness** | An installed Block Factory block satisfies its declared baseline capabilities: `vise check` counts a checklist item as present with evidence `source: "block:<id>"` when the `sp-vise/blocks.json` entry declares it in `providesCapabilities` and the install is still locally valid (dependency declared, touched files present), and the gap returns on drift. Field-level SDK model facts (`sdk-surface/models.<platform>.json`, wire format `2026-06-10.sdk-model-facts.v1`) ship for all five platform surfaces, names-and-types on every grounded platform. |
 | **Packed-package smoke** | Packed-package and host-agent smokes exercise the release tarball path, surfaced plan questions, selected optional capability sensors, rejected design confirmation handling, and exact contract-rule evidence for shared product expectations. |
 
 ### Supporting Proof
@@ -420,9 +415,9 @@ MCP-capable hosts can call Vise as structured tool calls instead of shell comman
 
 ### Tool names (snake_case per MCP convention)
 
-`inspect_project`, `creative_brief`, `creative_accept`, `ux_harness`, `compile_experience`, `experience_sensors`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `experience_report`, `record_learning`, `show_learning`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `resolve_request`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `suggest_patch`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
+`inspect_project`, `creative_brief`, `creative_accept`, `ux_harness`, `compile_experience`, `experience_sensors`, `plan_harness`, `plan_integration`, `init_compliance`, `check_compliance`, `experience_report`, `record_learning`, `show_learning`, `sync_compliance`, `attest_rule`, `explain_rule`, `init_engagement`, `show_engagement`, `search_docs`, `get_doc_page`, `debug_issue`, `validate_setup`, `run_sensors`, `design_extract`, `design_check`, `design_preview`, `design_reference`, `design_init_tokens`.
 
-These are the same operations as the CLI commands above, exposed as MCP tools.
+These are the same operations as the CLI commands above, exposed as MCP tools. `get_sdk_facts` is also registered as the internal, read-only Block Factory SDK-facts provider tool (it inspects no customer project — see [docs/SDK_FACTS_FOR_BLOCK_FACTORY.md](docs/SDK_FACTS_FOR_BLOCK_FACTORY.md)). The adapter still answers the legacy `resolve_request` and `suggest_patch` names for backward compatibility, but they are deprecated in favour of `plan_integration` plus host-tool edits.
 
 ---
 

package/dist/tools/ast.js

@@ -222,43 +222,148 @@ export function findCallExpressions(tree, calleePattern) {
     });
     return results;
 }
+// Bound on identifier→identifier resolution chains. Five hops covers realistic
+// re-binding (`const RAW = "…"; const T = RAW; const X = T;`) while keeping the
+// walk cheap; a `visited` set guards against cyclic self-reference (which would
+// be a type error anyway, but the parser still produces a tree for it).
+const MAX_RESOLUTION_HOPS = 5;
 /**
  * Resolve an AST node to its literal string value within the same file.
  *
  * Handles:
  * - String literals directly → returns the string value
- * - Identifiers that reference a const/let/var with a string literal initializer
- *   (single-step resolution only)
+ * - A pure-passthrough template literal — `` `${X}` `` with exactly one
+ *   substitution and no cooked text — which is value-equivalent to `X`; the
+ *   substitution is resolved through this same resolver. Templates with any
+ *   literal text (`` `pre${X}` ``) or a dynamic substitution (`` `${a.b}` ``)
+ *   are NOT pure passthrough and stay unresolved. (Arbitrary string
+ *   concatenation is a separate, larger blind spot — intentionally not handled.)
+ * - Identifiers that reference a const/let/var whose initializer resolves to a
+ *   literal, following identifier→identifier re-bind chains up to
+ *   MAX_RESOLUTION_HOPS deep (multi-hop), with a cycle guard. A binding to any
+ *   dynamic expression (member access, call, parameter, env fallback, …)
+ *   terminates the chain and stays unresolved — multi-hop never makes a runtime
+ *   value look literal.
  *
  * Returns undefined if the value cannot be statically resolved.
  */
 export function resolveLiteralValue(node, tree) {
+    return resolveLiteralValueBounded(node, tree, MAX_RESOLUTION_HOPS, new Set());
+}
+function resolveLiteralValueBounded(node, tree, hopsLeft, visited) {
     // Direct string literal
     const directValue = extractStringLiteral(node);
     if (directValue !== undefined)
         return directValue;
-    // Identifier — try to resolve to declaration in same file
-    // TypeScript uses "identifier", Kotlin uses "simple_identifier"
+    // Pure-passthrough template literal: `${X}` (exactly one substitution, no text).
+    // Equivalent to resolving X itself. Bounded to this one shape — not concat.
+    if (node.type === "template_string") {
+        const passthrough = templatePassthroughSubstitution(node);
+        if (passthrough)
+            return resolveLiteralValueBounded(passthrough, tree, hopsLeft, visited);
+    }
+    // Identifier — resolve to its declaration in the same file, then recurse into
+    // the initializer so identifier→identifier re-binds and template re-wraps
+    // chain through to the underlying literal.
+    // TypeScript uses "identifier", Kotlin uses "simple_identifier".
     if (node.type === "identifier" || node.type === "simple_identifier") {
+        if (hopsLeft <= 0)
+            return undefined;
         const name = node.text;
-        return resolveIdentifierToLiteral(name, tree.rootNode);
+        if (visited.has(name))
+            return undefined; // cycle guard
+        visited.add(name);
+        const valueNode = resolveIdentifierToValueNode(name, tree.rootNode);
+        if (!valueNode)
+            return undefined;
+        return resolveLiteralValueBounded(valueNode, tree, hopsLeft - 1, visited);
     }
     return undefined;
 }
+/**
+ * If `node` is a template literal that is a pure passthrough of a single
+ * substitution — `` `${X}` `` with exactly one `template_substitution` child,
+ * no `string_fragment` (cooked text) — return that substitution's inner
+ * expression node. Otherwise undefined.
+ */
+function templatePassthroughSubstitution(node) {
+    if (node.type !== "template_string")
+        return undefined;
+    let substitution;
+    for (let i = 0; i < node.namedChildCount; i++) {
+        const child = node.namedChild(i);
+        if (!child)
+            continue;
+        if (child.type === "template_substitution") {
+            if (substitution)
+                return undefined; // more than one substitution → not passthrough
+            substitution = child;
+        }
+        else {
+            // Any other named child (e.g. string_fragment cooked text) → has literal
+            // content, so not a pure passthrough.
+            return undefined;
+        }
+    }
+    if (!substitution)
+        return undefined;
+    // The substitution wraps a single expression: `${ expr }`.
+    return substitution.namedChild(0) ?? undefined;
+}
+/**
+ * Unwrap TypeScript expression wrappers that are transparent for static value
+ * extraction — type casts and grouping that don't change the runtime value:
+ *   - `expr as T`        (as_expression)
+ *   - `expr satisfies T` (satisfies_expression)
+ *   - `(expr)`           (parenthesized_expression)
+ *   - `expr!`            (non_null_expression)
+ *   - `<T>expr`          (type_assertion, angle-bracket cast)
+ * Nested wrappers are peeled fully (`({ … } as any)!`). The inner expression is
+ * always the wrapper's FIRST named child across these node types. Non-wrapper
+ * nodes are returned unchanged, so callers can apply this unconditionally.
+ *
+ * High-frequency motivation: agents emit `as any` constantly to silence TS
+ * errors, which otherwise hides the payload object from property extraction.
+ */
+export function unwrapExpression(node) {
+    let current = node;
+    const wrappers = new Set([
+        "as_expression",
+        "satisfies_expression",
+        "parenthesized_expression",
+        "non_null_expression",
+        "type_assertion",
+    ]);
+    // Bounded peel: a handful of stacked casts at most; the guard prevents any
+    // pathological loop if a grammar ever yields a self-referential first child.
+    for (let i = 0; i < 16 && wrappers.has(current.type); i++) {
+        const inner = current.namedChild(0);
+        if (!inner)
+            break;
+        current = inner;
+    }
+    return current;
+}
 /**
  * Pick a specific named property from an object argument node.
  * E.g., from `{ userId: HARDCODED }`, pick the value node for "userId".
+ *
+ * The argument is unwrapped first, so a cast/parenthesized/non-null-wrapped
+ * payload (`{ … } as any`, `({ … })`, `{ … }!`) is still treated as the inner
+ * object — otherwise the wrapper hides every property from extraction.
  */
 export function pickObjectProperty(objectNode, propertyName) {
-    if (objectNode.type !== "object")
+    const unwrapped = unwrapExpression(objectNode);
+    if (unwrapped.type !== "object")
         return undefined;
-    for (let i = 0; i < objectNode.namedChildCount; i++) {
-        const prop = objectNode.namedChild(i);
+    for (let i = 0; i < unwrapped.namedChildCount; i++) {
+        const prop = unwrapped.namedChild(i);
         if (!prop || prop.type !== "pair")
             continue;
         const key = prop.childForFieldName("key");
         if (key && key.text === propertyName) {
-            return prop.childForFieldName("value") ?? undefined;
+            const value = prop.childForFieldName("value");
+            return value ? unwrapExpression(value) : undefined;
         }
     }
     return undefined;
@@ -460,7 +565,26 @@ function extractStringLiteral(node) {
     }
     return undefined;
 }
-function resolveIdentifierToLiteral(name, root) {
+/**
+ * Find the binding for `name` in the same file and return the AST node that is
+ * its initializer VALUE — not the resolved string. The caller
+ * (resolveLiteralValueBounded) then recurses into that node, so an initializer
+ * that is itself an identifier (re-bind) or a pure-passthrough template literal
+ * chains through to the underlying literal. Returns undefined when the binding
+ * is absent or is a parameter / dynamic expression rather than a value
+ * initializer.
+ *
+ * Per-platform value node:
+ * - TypeScript/JS: `variable_declarator` → its `value` field.
+ * - Kotlin: `property_declaration` with a `variable_declaration` → the initializer
+ *   sibling (the node after `=`).
+ * - Swift: `property_declaration` with `pattern` → the DIRECT string-literal
+ *   initializer only. A literal nested inside another expression
+ *   (`env["KEY"] ?? ""`) is not a static binding and stays unresolved — so for
+ *   Swift we deliberately surface only a line/multi-line string literal node,
+ *   preserving the prior conservative behavior.
+ */
+function resolveIdentifierToValueNode(name, root) {
     let result;
     walkTree(root, (node) => {
         if (result !== undefined)
@@ -473,41 +597,42 @@ function resolveIdentifierToLiteral(name, root) {
             const valueNode = node.childForFieldName("value");
             if (!valueNode)
                 return;
-            const literal = extractStringLiteral(valueNode);
-            if (literal !== undefined)
-                result = literal;
+            // Casts/grouping around the initializer are transparent (e.g.
+            // `const T = RAW as string;`).
+            result = unwrapExpression(valueNode);
             return;
         }
-        // Kotlin: property_declaration with variable_declaration + string_literal
+        // Kotlin: property_declaration with variable_declaration + initializer
         if (node.type === "property_declaration") {
             const varDecl = node.namedChildren.find((c) => c.type === "variable_declaration");
             if (varDecl) {
                 const idNode = varDecl.namedChildren.find((c) => c.type === "simple_identifier");
                 if (!idNode || idNode.text !== name)
                     return;
-                const strLit = node.namedChildren.find((c) => c.type === "string_literal");
-                if (!strLit)
-                    return;
-                const literal = extractStringLiteral(strLit);
-                if (literal !== undefined)
-                    result = literal;
+                // The initializer is the named child after the variable_declaration.
+                const declIdx = node.namedChildren.indexOf(varDecl);
+                const initializer = node.namedChildren[declIdx + 1];
+                // Only surface a string literal or a re-bind identifier as the value node;
+                // anything else (call, when-expression, etc.) is dynamic and stays
+                // unresolved, matching the prior literal-only behavior.
+                if (initializer && (initializer.type === "string_literal" || initializer.type === "simple_identifier")) {
+                    result = initializer;
+                }
                 return;
             }
             // Swift: property_declaration with pattern → simple_identifier; the string
-            // literal must be a DIRECT child (the initializer) — a literal nested inside
-            // e.g. `env["KEY"] ?? ""` is not a static binding and must not resolve.
+            // literal (or a re-bind identifier) must be a DIRECT child (the
+            // initializer) — a literal nested inside e.g. `env["KEY"] ?? ""` is not a
+            // static binding and must not resolve.
             const pattern = node.namedChildren.find((c) => c.type === "pattern");
             if (!pattern)
                 return;
             const swiftId = pattern.namedChildren.find((c) => c.type === "simple_identifier");
             if (!swiftId || swiftId.text !== name)
                 return;
-            const swiftLit = node.namedChildren.find((c) => c.type === "line_string_literal" || c.type === "multi_line_string_literal");
-            if (!swiftLit)
-                return;
-            const literal = extractStringLiteral(swiftLit);
-            if (literal !== undefined)
-                result = literal;
+            const swiftValue = node.namedChildren.find((c) => c.type === "line_string_literal" || c.type === "multi_line_string_literal" || c.type === "simple_identifier");
+            if (swiftValue)
+                result = swiftValue;
         }
     });
     return result;

package/dist/tools/docs.js

@@ -1,5 +1,6 @@
 import { readdir, readFile } from "node:fs/promises";
 import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { objectInput, optionalNumberField, stringField, textResult } from "../types.js";
 import { packageUserAgent } from "../version.js";
 const DEFAULT_FETCH_TIMEOUT_MS = 15_000;
@@ -10,6 +11,38 @@ let hostedCachePending;
 function localDocsRoot() {
     return process.env.SOCIAL_PLUS_DOCS_ROOT ? path.resolve(process.env.SOCIAL_PLUS_DOCS_ROOT) : undefined;
 }
+// Hermetic ("offline") docs mode. When VISE_DOCS_OFFLINE is set truthy, docs
+// lookups are served from a committed, bundled corpus instead of the hosted
+// learn.social.plus endpoint — so CI (and offline installs) never depend on the
+// docs site being reachable. This kills the learn.social.plus flake class that
+// once hit test:cli. The live-fetch path stays the default when neither
+// VISE_DOCS_OFFLINE nor SOCIAL_PLUS_DOCS_ROOT is set, so real-fetch coverage is
+// preserved (see vise/package.json test:docs-live).
+//
+// Resolution precedence in loadDocPages():
+//   1. SOCIAL_PLUS_DOCS_ROOT (explicit local override) — highest, unchanged.
+//   2. VISE_DOCS_OFFLINE      — serve the bundled docs-cache/ corpus.
+//   3. neither                — live fetch from the hosted docs (default).
+function docsOfflineMode() {
+    const raw = process.env.VISE_DOCS_OFFLINE;
+    if (raw === undefined) {
+        return false;
+    }
+    const normalized = raw.trim().toLowerCase();
+    return normalized !== "" && normalized !== "0" && normalized !== "false" && normalized !== "off" && normalized !== "no";
+}
+// The bundled hermetic corpus ships in the package `files` allowlist as
+// `docs-cache/`. At runtime this module is dist/tools/docs.js, so the corpus is
+// two directories up. An explicit SOCIAL_PLUS_DOCS_OFFLINE_ROOT override is
+// honoured for tests that want to point offline mode at a fixture corpus.
+function bundledDocsCacheRoot() {
+    const override = process.env.SOCIAL_PLUS_DOCS_OFFLINE_ROOT;
+    if (override) {
+        return path.resolve(override);
+    }
+    const moduleDir = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(moduleDir, "..", "..", "docs-cache");
+}
 function docsBaseUrl() {
     return (process.env.SOCIAL_PLUS_DOCS_BASE_URL ?? "https://learn.social.plus").replace(/\/+$/, "");
 }
@@ -110,6 +143,16 @@ async function loadDocPages() {
     if (root) {
         return loadLocalDocPages(root);
     }
+    // Hermetic mode: serve the committed bundled corpus, never the network.
+    if (docsOfflineMode()) {
+        const cacheRoot = bundledDocsCacheRoot();
+        const pages = await loadLocalDocPages(cacheRoot);
+        if (pages.length === 0) {
+            throw new Error(`VISE_DOCS_OFFLINE is set but the bundled docs corpus at ${cacheRoot} is empty or missing. ` +
+                `Set SOCIAL_PLUS_DOCS_ROOT to a local docs directory, point SOCIAL_PLUS_DOCS_OFFLINE_ROOT at a corpus, or unset VISE_DOCS_OFFLINE to fetch live.`);
+        }
+        return pages;
+    }
     const now = Date.now();
     if (hostedCacheEntry && now - hostedCacheEntry.fetchedAt < cacheTtlMs()) {
         return hostedCacheEntry.pages;
@@ -271,6 +314,11 @@ async function findDocFiles(root) {
             if (entry.name === "node_modules" || entry.name === ".git" || entry.name === ".next") {
                 continue;
             }
+            // A README is corpus metadata (e.g. the docs-cache/ provenance note), not
+            // an SDK doc page — don't ingest it as a searchable page.
+            if (/^readme\.(md|mdx)$/i.test(entry.name)) {
+                continue;
+            }
             const entryPath = path.join(directory, entry.name);
             if (entry.isDirectory()) {
                 await walk(entryPath);

package/dist/tools/sdkFacts.js

@@ -51,6 +51,47 @@ const CAPABILITIES = {
             { name: "Reactable", kind: "model", owner: "Amity" },
         ],
     },
+    // Added with the Block Factory feed block (block #3). The bundled model facts
+    // (models.typescript.json) already tagged Amity.Post with capability "posts";
+    // this table entry closes the data/vocabulary gap so sdk-facts can answer for
+    // the posts surface the same way it does for comments and reactions.
+    posts: {
+        required: [
+            { name: "PostRepository", kind: "type" },
+            { name: "getPosts", kind: "member", owner: "PostRepository" },
+            { name: "createPost", kind: "member", owner: "PostRepository" },
+        ],
+        optional: [
+            { name: "getPost", kind: "member", owner: "PostRepository" },
+            { name: "editPost", kind: "member", owner: "PostRepository" },
+            { name: "softDeletePost", kind: "member", owner: "PostRepository" },
+            { name: "hardDeletePost", kind: "member", owner: "PostRepository" },
+            { name: "flagPost", kind: "member", owner: "PostRepository" },
+            { name: "unflagPost", kind: "member", owner: "PostRepository" },
+            { name: "isPostFlaggedByMe", kind: "member", owner: "PostRepository" },
+            { name: "onPostCreated", kind: "member", owner: "PostRepository" },
+            { name: "onPostUpdated", kind: "member", owner: "PostRepository" },
+            { name: "onPostDeleted", kind: "member", owner: "PostRepository" },
+        ],
+        models: [{ name: "Post", kind: "model", owner: "Amity" }],
+    },
+    users: {
+        required: [
+            { name: "UserRepository", kind: "type" },
+            { name: "getUser", kind: "member", owner: "UserRepository" },
+        ],
+        optional: [
+            { name: "blockUser", kind: "member", owner: "UserRepository" },
+            { name: "unBlockUser", kind: "member", owner: "UserRepository" },
+            { name: "follow", kind: "member", owner: "UserRepository" },
+            { name: "unfollow", kind: "member", owner: "UserRepository" },
+            { name: "getFollowers", kind: "member", owner: "UserRepository" },
+            { name: "getFollowings", kind: "member", owner: "UserRepository" },
+            { name: "getFollowInfo", kind: "member", owner: "UserRepository" },
+            { name: "getMyFollowInfo", kind: "member", owner: "UserRepository" },
+        ],
+        models: [{ name: "User", kind: "model", owner: "Amity" }],
+    },
 };
 export const getSdkFactsTool = {
     name: "get_sdk_facts",
@@ -64,7 +105,10 @@ export const getSdkFactsTool = {
             },
             capability: {
                 type: "string",
-                description: "Optional capability filter. Current MVP supports comments and reactions for the TypeScript/React Native surface.",
+                // Derived from the capability table so the description can never
+                // lag behind a newly added capability (the old hand-written text
+                // still said "comments and reactions" after posts landed).
+                description: `Optional capability filter. Known capability ids: ${Object.keys(CAPABILITIES).join(", ")}.`,
             },
             surfaceDir: {
                 type: "string",

package/docs-cache/README.md

@@ -0,0 +1,34 @@
+# Bundled hermetic docs corpus
+
+A committed snapshot of social.plus SDK docs pages, served when **`VISE_DOCS_OFFLINE`** is set so docs lookups (`search_docs` / `get_doc_page`) never depend on `learn.social.plus` being reachable. This kills the docs-site flake class that once hit `test:cli`.
+
+It ships with the package (in the `files` allowlist) so installed users and CI can run docs lookups fully offline.
+
+## How docs resolution chooses this corpus
+
+In `src/tools/docs.ts` `loadDocPages()`:
+
+1. `SOCIAL_PLUS_DOCS_ROOT` set → that local directory (explicit override; unchanged).
+2. `VISE_DOCS_OFFLINE` truthy → **this `docs-cache/` corpus** (or `SOCIAL_PLUS_DOCS_OFFLINE_ROOT` if set, used by tests).
+3. neither → live fetch from the hosted docs (the default; real-fetch coverage lives in `test:docs-live`).
+
+CI / the `validate` chain run hermetic via `test:docs-offline`. The live path is the separate `test:docs-live` lane (set `VISE_DOCS_LIVE=1`), kept off the critical path so a docs outage never reds CI.
+
+## Contents & provenance
+
+The pages are authentic content extracted from the hosted `llms-full.txt`, scoped to the canonical paths Vise relies on (`knownDocPaths()` in `src/outcomes.ts`) plus the post-creation page used by `test/run-cli.mjs`. Each `.mdx` file is `# <title>` followed by the page body, matching the layout `loadLocalDocPages()` expects.
+
+This is a curated subset, not the full site — enough to make docs lookups deterministic and offline, not a mirror.
+
+### Regenerate
+
+```sh
+# 1. Snapshot the hosted llms-full.txt:
+curl -s https://learn.social.plus/llms-full.txt -o /tmp/llms-full.txt
+
+# 2. Extract the knownDocPaths() pages into docs-cache/<path>.mdx, each as
+#    `# <title>\n\n<body>`. (One-off node script split on the
+#    `### [title](url)` page headings, same split parseLlmsFull uses.)
+```
+
+Refresh when `knownDocPaths()` changes or the hosted docs materially move. `test/run-docs-offline.mjs` asserts the corpus answers `flutter quick start` and serves the flutter-quick-start page, so an empty/broken refresh fails CI loudly.