docs(builder-tools): add add_preset_approval, list_presets, flag_review_item

for-developers/ai-agents/builder-tools.md

@@ -84,7 +84,9 @@ The recommended way to build collections. Each tool sets one field on a session-
 | `set_collection_metadata` | Set collection-level metadata (name, description, image) |
 | `set_token_metadata` | Set per-token metadata URIs |
 | `set_custom_data` | Set custom data on the collection |
-| `add_approval` | Add a collection approval with approvalCriteria |
+| `add_approval` | Add a collection approval with approvalCriteria (raw — full control over every field) |
+| `add_preset_approval` | Add a canonical approval from a named preset (smaller payload, preferred when a preset fits). Output is structurally identical to `add_approval` |
+| `list_presets` | Discover preset IDs + params schemas, filtered by skill (e.g. `{skill: "prediction-market"}`) |
 | `remove_approval` | Remove a collection approval by approvalId |
 | `set_approval_metadata` | Set metadata for a specific approval |
 | `add_alias_path` | Add an alias path (for ICS20-backed smart tokens) |
@@ -159,6 +161,7 @@ Helper tools that generate specific pieces of a collection (approvals, permissio
 | `get_current_timestamp` | Get the current timestamp (for time-based configs) |
 | `diagnose_error` | Diagnose BitBadges transaction errors and get suggested fixes |
 | `search_knowledge_base` | Search across all BitBadges knowledge — docs, learnings, recipes, error patterns, critical rules |
+| `flag_review_item` | Flag a decision the user should review before broadcast (assumptions, substitutions, ambiguity resolutions, defaults picked without user input). Surfaces as `BuildResult.reviewFlags`. Always on — no feature flag |
 
 ### Instructions & Docs
 

for-developers/ai-agents/programmatic-agent.md

@@ -243,19 +243,28 @@ interface BuildResult {
   transaction: any;              // parsed object — not a JSON string
   errors: StructuredError[];     // code, message, path?, fixHint?
   warnings: Warning[];           // non-fatal advisory notes
+  hardErrors: string[];          // raw hard-error strings (backwards-compat)
   advisoryNotes: string[];       // raw review findings
   validation: any;               // SDK validator result
   simulation: any | null;        // null when no simulator configured
   audit: any | null;             // review findings + summary
+  designDecisions: DesignDecisionsResult | null; // ✓/✗/n-a informational checks about what the collection IS
+  reviewFlags: ReviewFlag[];     // items the agent self-surfaced via flag_review_item
   tokensUsed: number;
   costUsd: number;               // always computed per selected model
   rounds: number;
   fixRounds: number;
+  durationMs: number;            // wall-clock duration of the build
+  inferredTokenType?: string | null;                // auto-picked token-type skill, or null for freestyle. undefined when inference was skipped
+  inferredTokenTypeSource?: 'standards' | 'llm';    // provenance of the pick
+  inferredTokenTypeReasoning?: string;              // one-sentence explanation
   trace: BuildTrace;             // full messages + tool calls + prompt hash
   toString(): string;            // human-readable one-liner
 }
 ```
 
+`reviewFlags` and `designDecisions` are always populated when the build produces a collection-shape message (regardless of whether the LLM auditor was enabled). See [Smart Token-Type Detection](smart-token-type-detection.md) for the three `inferredTokenType*` fields.
+
 Errors dispatch on `instanceof`:
 
 ```ts