@salesforce/afv-skills 1.21.0 → 1.23.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@salesforce/afv-skills",
-  "version": "1.21.0",
+  "version": "1.23.0",
   "description": "Salesforce skills for Agentforce Vibes",
   "license": "CC-BY-NC-4.0",
   "files": [

package/skills/agentforce-architecture-analyze/README.md

@@ -0,0 +1,156 @@
+# agentforce-architecture-analyze
+
+Declared architecture snapshot for a single Agentforce agent: planner + topics + actions + flows + Apex + prompts + NGA plugins. Reads design-time metadata only (`BotDefinition` + `GenAi*` Tooling objects + Metadata API retrieve) — no runtime audit data.
+
+Input: an `agent_api_name` (the `BotDefinition.DeveloperName`) and an org alias. Optional `agent_version_api_name` to pin a version; otherwise the active `BotVersion` resolves.
+
+Output: two files under `~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent>__<version>/` — a normalized `<agent>_<ver>_metadata_tree.json` and a human-readable `<agent>_<ver>_architecture.md`. Override with `--data-dir <path>` (other runtimes pass this to land artifacts under their own distribution layout).
+
+---
+
+## Runtime budget
+
+**30–45s typical, ≤60s hard cap** on the reference fixtures.
+
+A naive sequential implementation (Metadata API retrieves only) would take 90–220s. Speedup: **3–5×**.
+
+Scaling note: large bots with many flows scale approximately linearly in flow count. Each Flow metadata retrieve is an individual SOQL round-trip; a 20-flow bot takes proportionally longer than a 5-flow bot. The 7 planner-side Tooling SOQL fan-outs are constant-cost (single fan-out regardless of bot size); the flow/apex body fetch wave scales with ref count.
+
+---
+
+## Prerequisites
+
+| Tool | Why |
+|---|---|
+| `sf` CLI (authenticated against the target org) | Shells `sf org display --target-org <alias> --json` for access token, and `sf sobject describe` for the 7-day channel probe |
+| Python 3.10+ | `pathlib`, dataclasses, `\|` union types, `concurrent.futures` |
+
+---
+
+## Usage
+
+Invoked conversationally through whatever skill-aware runtime hosts it. Example prompts:
+
+| User says | Skill does |
+|---|---|
+| `document the architecture of MyAgent in my-org-alias` | Resolve active version, fetch tree, render architecture.md + Mermaid |
+| `draw the invocation graph for MySalesAgent v5 in my-org-alias-3` | Same, pinned to v5 |
+| `what tools does MyAgent2 have in my-org-alias-2` | Fetch tree, surface the plugin/function inventory from the rendered architecture.md |
+| `re-fetch the architecture of MyAgent — I think metadata changed` | Pass `--force` to bypass the cache |
+
+See `SKILL.md` for the full flag table and sample prompts.
+
+---
+
+## Directory layout
+
+```
+agentforce-architecture-analyze/
+├── SKILL.md                       Skill contract (inputs, outputs, pipeline, invariants)
+├── README.md                      This file
+├── assets/
+│   ├── soql/*.soql                Tooling + Data SOQL templates
+│   ├── cli/*.yaml                 sf CLI recipes (subprocess invocation specs)
+│   └── mermaid/*.mmd              Mermaid templates for the invocation graph
+├── references/
+│   ├── soql_fields.md             Per-sObject field reference (13 sObjects)
+│   ├── architecture_sections.md   Section-by-section structure of the rendered architecture.md
+│   └── contract.json              metadata_tree.json schema contract
+├── scripts/
+│   ├── _shared/                   Path helpers + fs_guard validators + sql escapers
+│   ├── main.py                    Orchestrator entry point
+│   ├── config.py                  Shared paths, cache TTLs, validated path builders
+│   ├── soql_loader.py             Template loader with fs_guard-validated substitution
+│   ├── sf_cli.py                  sf CLI subprocess wrapper (yaml.safe_load + stderr redaction)
+│   ├── rest_client.py             urllib wrapper (Authorization-stripping redirect handler)
+│   ├── resolve_bot.py             BotDefinition + BotVersion + planner name lookup
+│   ├── retrieve_planner.py        Metadata retrieve for GenAiPlannerBundle + NGA plugins
+│   ├── parallel_retrieve.py       7-channel parallel Tooling SOQL fan-out
+│   ├── parse_bundle.py            XML → normalized node shapes
+│   ├── parse_wave.py              BFS expansion of flow/apex/prompt refs
+│   ├── probe_channels.py          7-day-TTL channel describe probe
+│   ├── cache_check.py             Asset-hash-aware cache freshness
+│   ├── finalize.py                Merge waves → metadata_tree.json
+│   ├── render_architecture.py     architecture.md + Mermaid graph
+│   ├── resolve_invocation_target.py  ID-prefix router for NGA InvocationTargets
+│   └── tests/                     Unit + integration tests (unittest)
+└── tools/
+    ├── emit_env.py                Env-var emit helper (Phase 0.5)
+    ├── emit_result.py             Final RESULT block renderer
+    ├── sanitize.py                Stdin → safe-string filter
+    └── write_emit_ctx.py          Per-phase ctx writer
+```
+
+---
+
+## Architecture
+
+### Channel strategy — SOQL-first
+
+```
+Seed query: planner_definition_by_agent_chain (chain-LIKE lookup → planner id)
+
+6 parallel Tooling SOQL channels (keyed on the resolved planner id):
+    - plugins_by_planner
+    - planner_bundle_functions (join)
+    - functions_by_plugins
+    - planner_attrs_by_parent_ids
+    - plugin_functions_by_plugin_ids (join)
+    - plugin_instructions_by_plugin_ids
+
++ Data API SOQL for Flow / Apex bodies (batched by id list)
++ Metadata retrieve ONLY for:
+    - GenAiPromptTemplate (prompt bodies)
+    - NGA external plugins (when planner is ConcurrentMultiAgentOrchestration etc.)
+```
+
+Most of the 3–5× speedup over a naive Metadata-API-only implementation comes from collapsing a sequential zip-retrieve chain into a single Tooling SOQL fan-out.
+
+### Planner normalization — classic ReAct vs NGA
+
+One tree shape, two planner families:
+
+| `PlannerType` examples | Family | InvocationTarget style |
+|---|---|---|
+| `ReactAiPlannerV1`, `SequentialPlannerIntentClassifier` | Classic ReAct | DeveloperName strings |
+| `ConcurrentMultiAgentOrchestration`, `AnthropicCompatibleV1` | NGA | Sometimes 15/18-char Ids (ID-prefix routed) |
+
+`resolve_invocation_target.py` routes NGA InvocationTargets by Salesforce ID prefix (`01p` → ApexClass, `301` → Flow, etc.). Unknown prefixes become `_unresolved[]` entries with `reason="unknown-id-prefix:<prefix>"` — never silently dropped.
+
+### Cache layers
+
+1. **Tree cache** — `metadata_tree.json` is reused unless `--force`. Cache key includes asset-hashes of every SOQL / YAML / Mermaid template shipped with the skill, so changing a template busts the cache automatically.
+2. **Channel probe cache** — 7-day TTL on `sf sobject describe` results for the 13 sObjects the skill touches. `--reprobe` forces a refresh (needed after Salesforce quarterly releases that rename / remove fields). Mandatory-field gate: a probe that sees any mandatory field missing (per `probe_channels.MANDATORY_FIELDS`) flips `status: PROBE_FAILED` so the caller surfaces a clean error.
+
+---
+
+## Key behaviors
+
+### Idempotence
+
+Re-running the same `(org, agent, version)` overwrites prior artifacts in place. Safe to run repeatedly during development.
+
+### Partial-results surfacing
+
+No silent drops. Any unresolved ref — unknown ID prefix, failed SOQL, missing describe field — lands in `_unresolved[]` with a `reason=...` string. Top-level `STATUS` is `OK` on a clean run, `PARTIAL_OK` when any channel degrades.
+
+### Cycle handling
+
+Per-branch ancestor-path cycle detection is the primary termination primitive: the same flow visited along its own ancestor chain emits `_cycle_back_to:<path>` instead of recursing. `MAX_BFS_DEPTH=20` is a defensive last-resort guard against pathological graphs that evade per-branch detection; real-world agents bottom out well before that.
+
+---
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `sf org display failed` | Re-authenticate: `sf org login web --alias <alias>` |
+| `INVALID_FIELD` from a SOQL asset | Salesforce renamed / removed the field in a quarterly release. Run with `--reprobe` to refresh the 7-day channel cache and pick up the new schema |
+| `STATUS=PROBE_FAILED` on first run | Channel probe saw a mandatory field missing. Check `channels.json` under the probe cache dir for which sObject / field — may require org-side feature enablement |
+| Tree for classic ReAct agent shows `_unresolved` entries for NGA plugins | Expected — the NGA external-plugin retrieve is skipped when the planner shape is classic. Those entries can be ignored |
+
+---
+
+## Author
+
+Raghul Jayagopal (RJ), Salesforce ANZ FDE.

package/skills/agentforce-architecture-analyze/SKILL.md

@@ -0,0 +1,230 @@
+---
+name: agentforce-architecture-analyze
+description: "Declared architecture snapshot for one Agentforce agent: planner, topics, actions, flows, Apex, prompt templates, and NGA plugins. Renders a human-readable architecture document and Mermaid invocation graph from design-time metadata (not runtime audit rows). TRIGGER when user asks to describe, diagram, inventory, audit, document, or diff (e.g. v3 vs v5) the architecture / action tree / topic structure / tool inventory of a specific agent by agent API name in a specific org. DO NOT TRIGGER for runtime session traces, conversation transcripts, generation timings, or gateway audit chains — this skill reads design-time metadata only (use agentforce-d360-analyze for session traces)."
+metadata:
+  version: "1.0"
+---
+
+# agentforce-architecture-analyze — declared architecture snapshot
+
+Design-time metadata tree for one Agentforce agent: planner → topics → actions → flows → Apex → prompts → NGA plugins. Reads declared metadata only — `BotDefinition`, `GenAiPlanner*`, `GenAiPlugin*`, `GenAiFunction*`, `Flow`, `ApexClass`, `GenAiPromptTemplate`. Does **not** read runtime audit rows.
+
+**Runtime budget: 30–45s typical, ≤60s hard cap** on reference fixtures. Sequential baseline would be 90–220s; parallel Tooling SOQL fan-out delivers a 3–5× speedup. Large bots with many flows scale approximately linearly — each flow metadata retrieve is one round-trip.
+
+Runs **inline** — no subagent. Every phase is deterministic file processing.
+
+## If the user hasn't given enough to proceed
+
+When invoked with no `agent_api_name` AND no org alias, print the following block **verbatim** — do not paraphrase, do not pre-run any script. Trigger condition: `$ARGUMENTS` is empty OR names no agent (no `--agent` flag and no known agent API name in the prose) OR names no org (no `--org` flag and no known alias).
+
+> Which agent should I document, and in which org?
+>
+> I need:
+> - **Agent API name** — the `DeveloperName` of the `BotDefinition` (e.g. `MyAgent`, `MySalesAgent`). Not the label.
+> - **Org alias** — for `sf` CLI auth (the alias you configured with `sf org login`)
+>
+> Optional:
+> - **Version** — an `agent_version_api_name` like `v5`. If omitted, I'll resolve the active `BotVersion`.
+> - **`--force`** — ignore cached tree; re-fetch everything.
+> - **`--reprobe`** — re-run the 7-day channel-probe cache (only needed after a Salesforce release).
+>
+> I'll run the metadata pipeline inline. Artifacts land under `~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent_api_name>__<agent_version>/` (overridable with `--data-dir`).
+
+## Pipeline invocation
+
+When the user has supplied `--org <alias>` + `--agent <api_name>` (plus any optional flags), run this block. One `python3` invocation drives the full pipeline. `main.py` writes `.emit_ctx.json`; `emit_result.py` reads it and prints the final `=== RESULT ===` block last to stdout.
+
+```bash
+set -euo pipefail
+
+# zsh arrays are 1-indexed by default; bash arrays are 0-indexed.
+# This block uses 0-indexed semantics throughout (_args[$i] starting at i=0),
+# so under zsh + `set -u` the very first read of `_args[0]` would trip
+# `parameter not set`. KSH_ARRAYS makes zsh treat arrays as 0-indexed,
+# matching the bash shebang's expectation. No-op under bash.
+[ -n "${ZSH_VERSION:-}" ] && setopt KSH_ARRAYS
+
+SKILL_ROOT="${SKILL_ROOT:-${PLUGIN_ROOT:-$HOME/.vibe/skills}/agentforce-architecture-analyze}"
+
+# Argument parser. Accepts both `--org foo` and `--org=foo`.
+# `$ARGUMENTS` is the raw user input Claude Code substitutes.
+ARG_ORG=""
+ARG_AGENT=""
+ARG_VERSION=""
+ARG_FORCE=""
+ARG_REPROBE=""
+ARG_PARALLELISM=""
+ARG_MAX_MERMAID=""
+
+# shellcheck disable=SC2206
+_args=($ARGUMENTS)
+i=0
+while [ $i -lt ${#_args[@]} ]; do
+ tok="${_args[$i]}"
+ case "$tok" in
+ --org=*) ARG_ORG="${tok#--org=}" ;;
+ --org) i=$((i+1)); ARG_ORG="${_args[$i]:-}" ;;
+ --agent=*) ARG_AGENT="${tok#--agent=}" ;;
+ --agent) i=$((i+1)); ARG_AGENT="${_args[$i]:-}" ;;
+ --version=*) ARG_VERSION="${tok#--version=}" ;;
+ --version) i=$((i+1)); ARG_VERSION="${_args[$i]:-}" ;;
+ --parallelism=*) ARG_PARALLELISM="${tok#--parallelism=}" ;;
+ --parallelism) i=$((i+1)); ARG_PARALLELISM="${_args[$i]:-}" ;;
+ --max-mermaid-nodes=*) ARG_MAX_MERMAID="${tok#--max-mermaid-nodes=}" ;;
+ --max-mermaid-nodes) i=$((i+1)); ARG_MAX_MERMAID="${_args[$i]:-}" ;;
+ --force) ARG_FORCE="1" ;;
+ --reprobe) ARG_REPROBE="1" ;;
+ esac
+ i=$((i+1))
+done
+
+# Usage block if required flags missing. Agent reads stderr,
+# prints verbatim, and stops — does NOT pre-run main.py.
+if [ -z "$ARG_ORG" ] || [ -z "$ARG_AGENT" ]; then
+ cat >&2 <<'USAGE'
+> Which agent should I document, and in which org?
+>
+> I need:
+> - **Agent API name** — the BotDefinition.DeveloperName (e.g. `MyAgent`)
+> - **Org alias** — for `sf` CLI auth (the alias you configured with `sf org login`)
+>
+> Optional flags:
+> - `--version v5` — pin a specific BotVersion (default: Active+highest)
+> - `--force` — bypass cache
+> - `--reprobe` — force channel-probe refresh
+> - `--parallelism N` — ThreadPoolExecutor size (default 5)
+> - `--max-mermaid-nodes N` — cap Mermaid node count (default 80)
+USAGE
+ exit 2
+fi
+
+# Fresh work dir per invocation. Epoch + random suffix avoids collisions
+# between concurrent runs on the same host.
+WORK_DIR="/tmp/agentforce-architecture-analyze-$(date +%s)-$RANDOM"
+mkdir -p "$WORK_DIR"
+
+# Input validation at the boundary, BEFORE any python3 call.
+# fs_guard exits 1 and prints an INVALID_INPUT RESULT block on failure;
+# `|| exit 1` is mandatory — bare calls silently continue past failures.
+python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$ARG_AGENT" agent_api_name api_name || exit 1
+python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$ARG_ORG" org_alias not_empty || exit 1
+python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$WORK_DIR" WORK_DIR symlink || exit 1
+python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$WORK_DIR" WORK_DIR owned || exit 1
+if [ -n "$ARG_VERSION" ]; then
+ python3 "$SKILL_ROOT/scripts/_shared/fs_guard.py" "$ARG_VERSION" agent_version api_name || exit 1
+fi
+
+# Single python3 call drives all pipeline phases. main.py writes
+# `.emit_ctx.json` into $WORK_DIR — emit_result.py then renders the
+# RESULT block from that ctx. No subprocess-per-phase.
+_main_args=(--org-alias "$ARG_ORG" --agent "$ARG_AGENT" --work-dir "$WORK_DIR")
+[ -n "$ARG_VERSION" ] && _main_args+=(--version "$ARG_VERSION")
+[ -n "$ARG_FORCE" ] && _main_args+=(--force)
+[ -n "$ARG_REPROBE" ] && _main_args+=(--reprobe)
+[ -n "$ARG_PARALLELISM" ] && _main_args+=(--parallelism "$ARG_PARALLELISM")
+[ -n "$ARG_MAX_MERMAID" ] && _main_args+=(--max-mermaid-nodes "$ARG_MAX_MERMAID")
+
+# main.py returns nonzero on terminal failures; we DON'T short-circuit —
+# emit_result still publishes the failure RESULT block. `set -e` is
+# temporarily relaxed around this single call.
+set +e
+python3 "$SKILL_ROOT/scripts/main.py" "${_main_args[@]}"
+_rc=$?
+set -e
+
+# Final RESULT block is emit_result.py's stdout — MUST be the last thing
+# stdout sees. emit_result exits 0 on render success; the bash harness
+# propagates main.py's rc for the agent's exit status.
+WORK_DIR="$WORK_DIR" python3 "$SKILL_ROOT/tools/emit_result.py"
+exit "$_rc"
+```
+
+## Inputs
+
+| Input | Flag | Required | Default |
+|---|---|---|---|
+| `org_alias` | `--org` | yes | — |
+| `agent_api_name` | `--agent` | yes | — |
+| `agent_version_api_name` | `--version` | no | active BotVersion |
+| `force_refresh` | `--force` | no | false (honor cache) |
+| `reprobe` | `--reprobe` | no | false (honor 7-day channel-probe cache) |
+| `parallelism` | `--parallelism` | no | 5 |
+| `max_mermaid_nodes` | `--max-mermaid-nodes` | no | 80 |
+| `data_dir` | `--data-dir` | no | `~/.vibe/data/agentforce-architecture-analyze` |
+| `cache_dir` | `--cache-dir` | no | `~/.vibe/cache/agentforce-architecture-analyze` |
+
+## Outputs
+
+All artifacts under `~/.vibe/data/agentforce-architecture-analyze/<org_id15>/<agent_api_name>__<agent_version>/` (default; override with `--data-dir <path>`):
+
+```
+<agent>_<ver>_metadata_tree.json   primary artifact — normalized planner/topic/action/flow/apex/prompt/plugin tree
+<agent>_<ver>_architecture.md      human-readable section-by-section rendering (H1 + 7 numbered sections, plus a conditional Dependency graph appendix). Mermaid diagrams are embedded inside the relevant sections (Action tree, Data flow, and Dependency graph)
+```
+
+## Pipeline — inline, no subagent
+
+```
+resolve_bot.py        → BotDefinition + BotVersion + planner name lookup
+retrieve_planner.py   → Metadata API zip retrieve for GenAiPlannerBundle (+ NGA plugins if present)
+parallel_retrieve.py  → 6 parallel Tooling SOQL channels fan out from the planner id
+                          (resolved by the `planner_definition_by_agent_chain` seed query):
+                          - plugins_by_planner (GenAiPluginDefinition)
+                          - planner_bundle_functions (GenAiPlannerFunctionDef join)
+                          - functions_by_plugins (GenAiFunctionDefinition)
+                          - planner_attrs_by_parent_ids (GenAiPlannerAttrDefinition)
+                          - plugin_functions_by_plugin_ids (GenAiPluginFunctionDef join)
+                          - plugin_instructions_by_plugin_ids (GenAiPluginInstructionDef)
+parse_bundle.py       → parse retrieved XML into normalized node shapes
+parse_wave.py         → BFS expansion: flow/apex/prompt refs discovered in nodes
+                          → SOQL for Flow/Apex bodies (batched by id list)
+                          → Metadata retrieve ONLY for GenAiPromptTemplate (+ NGA external plugins conditionally)
+finalize.py           → merge waves into metadata_tree.json
+render_architecture.py → <agent>_<ver>_architecture.md + Mermaid invocation graph (capped at --max-mermaid-nodes)
+```
+
+**Channel strategy — SOQL-first.**
+- **Tooling SOQL** for every normalized tree node (planner, plugins, functions, plugin-functions, plugin-instructions, planner-functions, planner-attrs) — 6 parallel channels keyed on planner id, plus the `planner_definition_by_agent_chain` seed query that resolves the planner id from the agent chain.
+- **Data API SOQL** for Flow (by id) and Apex (by id or name) bodies — batched.
+- **Metadata retrieve** only for two cases: (a) `GenAiPromptTemplate` (prompt bodies aren't cleanly exposed via Tooling SOQL), and (b) NGA **external plugins** when the planner is Native Generative Agent shape (skipped for classic ReAct).
+
+This is where the 3–5× speedup comes from. A naive implementation would retrieve everything via Metadata API zips sequentially; parallel Tooling SOQL covers ~80% of the tree in a single fan-out.
+
+## Planner shapes — classic ReAct vs NGA
+
+The skill normalizes two planner families into a single tree shape:
+
+| Shape | `GenAiPlannerDefinition.PlannerType` | InvocationTarget style | NGA plugins? |
+|---|---|---|---|
+| **Classic ReAct** | `ReactAiPlannerV1` / `SequentialPlannerIntentClassifier` / etc. | DeveloperName strings | no |
+| **NGA** | `ConcurrentMultiAgentOrchestration` / `AnthropicCompatibleV1` / etc. | Sometimes 15/18-char Ids (ID-prefix routed) | yes (external plugins via Metadata retrieve) |
+
+The ID-prefix router in `resolve_invocation_target.py` distinguishes the two: NGA InvocationTargets that look like ids (`01p…` = ApexClass, `301…` = Flow, etc.) get resolved via id-scoped SOQL; DeveloperName targets go through name-scoped SOQL. Unknown prefixes surface as `_unresolved[]` with `reason="unknown-id-prefix:<prefix>"` — never silently dropped.
+
+## Caching
+
+- **Tree cache**: `metadata_tree.json` is reused unless `--force` is passed. Cache key includes the asset-hash of every `.soql` / `.yaml` / `.mmd` template bundled with the skill — bump a template, the cache busts automatically.
+- **Channel probe cache**: 7-day TTL on the per-org `sf sobject describe` results that validate every field name the SOQL assets reference. A Salesforce quarterly release that renames / removes a field triggers `status: PROBE_FAILED`; `--reprobe` forces a refresh.
+
+## Prerequisites
+
+| Tool | Required |
+|---|---|
+| `sf` CLI (authenticated against the target org) | yes — `sf org login web --alias <alias>` |
+| Python 3.10+ | yes |
+
+## Reference docs to load when needed
+
+Do NOT load eagerly. Load when the user's question requires it:
+
+- `references/soql_fields.md` — per-sObject field reference for the 13 sObjects this skill touches (2 Data API + 11 Tooling), with `[mandatory]` vs `[optional]` tags. Load when the user asks about a specific field, or when debugging an `INVALID_FIELD` SOQL error.
+- `references/contract.json` — machine-readable schema for `metadata_tree.json`. Load when writing downstream tooling that consumes the tree.
+- `references/architecture_sections.md` — section-by-section structure of the rendered `<agent>_<ver>_architecture.md`.
+
+## Invariants worth knowing upfront
+
+- **Pipeline is deterministic.** Same `(org, agent, version)` + static org metadata → byte-identical `<agent>_<ver>_metadata_tree.json` and `<agent>_<ver>_architecture.md`. Only manifest timestamps drift across re-runs.
+- **Forward-only traversal.** Every discovered ref goes forward from planner → children. No backward lookups.
+- **Partial results are surfaced, not silenced.** Any unresolved reference lands in `_unresolved[]` with `reason=...`. `STATUS=PARTIAL_OK` if any channel failed; `STATUS=OK` only on a clean run.
+- **Cycle detection is per-branch.** Same flow visited along its own ancestor chain emits `_cycle_back_to:<path>` instead of recursing. A defensive `MAX_BFS_DEPTH=20` guard backs the per-branch ancestor set; real-world agents bottom out well before either limit fires. (Earlier docs claimed a hard cap of 5; that was the historical limit and was abandoned because shared utility flows like `handleFlowFault` tripped it on every nested tree — see `config.MAX_BFS_DEPTH` for the rationale.)
+- **Child ordering is alphabetical by `api_name` (case-insensitive).** Topics come before non-topic plannerActions at the root level. Flow-actionCall order is NOT sorted — that's the flow author's execution sequence.

package/skills/agentforce-architecture-analyze/references/architecture_sections.md

@@ -0,0 +1,243 @@
+# architecture.md section reference
+
+Per-section rendering spec for `scripts/render_architecture.py::render`.
+One `# Architecture` H1, seven numbered `## N. ...` sections, plus one
+conditional "Dependency graph" appendix. Source of truth: the
+`metadata_tree.json` schema produced by `scripts/parse_wave.py` at the
+end of phase 9.
+
+**Source of truth: the live tree** — field shapes evolve as parse_wave
+learns new agent generations. When this doc disagrees with the
+`metadata_tree.json` written by `parse_wave.py` for an actual agent on
+your machine (under `~/.vibe/data/agentforce-architecture-analyze/<org>/<agent>__<ver>/`),
+trust the live tree.
+
+The Mermaid templates live at `assets/mermaid/*.mmd` and are the sole
+consumer of the renderer helpers; each `{{PARAM}}` contract is
+documented in the template's own header comment.
+
+---
+
+## Per-diagram node caps
+
+Default caps (override via `render(..., max_mermaid_nodes={...})`):
+
+| Diagram kind | Default cap | Over-cap behaviour |
+|---|---|---|
+| `flowchart` | 200 | summary placeholder + top-5 fan-out + catalog pointer |
+| `stateDiagram` | 40 | summary placeholder (no fan-out — states are not nodes) |
+| `sequenceDiagram` | 60 | summary placeholder + top-5 fan-out |
+| `graph` | 100 | summary placeholder + top-5 fan-out |
+
+Cap is measured in rendered elements (nodes + edges for flowchart/graph,
+messages for sequenceDiagram, states + transitions for stateDiagram).
+Above cap, the renderer emits a `> [diagram truncated: ...]` blockquote
+with the element count, the top-5 nodes by fan-out (when applicable),
+and a pointer to the catalog section that enumerates the same data
+without compression.
+
+---
+
+## 1. Header + agent overview
+
+**Purpose**: identify the agent and its planner in a single kv table.
+
+**Input fields** (`tree.agent.*`):
+
+- `api_name` — agent developer name
+- `version` — `v<N>` label
+- `master_label` — human-readable name
+- `description` — prose summary
+- `agent_type` — `EinsteinAgentKind` / `EinsteinCopilotForSalesforce` / …
+- `type` — `ExternalCopilot` / `InternalCopilot` / …
+- `agent_template`
+- `bot_source`
+- `generation` — `classic` / `nga` / `search` / `byop`
+- `planner_name`
+- `planner_type`
+- `bot_id`
+
+Plus `tree._schema_version`.
+
+**Output shape**: `# <H1>` with api_name + version, followed by a 2-col
+markdown table.
+
+**Empty/degenerate cases**:
+
+- Missing `api_name` / `version` renders `?` in the H1 (not `None`).
+- Any missing field renders `-` in its row — not empty, because GitHub
+ table rendering collapses empty cells and the row loses alignment.
+
+---
+
+## 2. Anatomy summary
+
+**Purpose**: one-paragraph executive summary plus health callouts.
+
+**Input fields**:
+
+- `tree._kind_counts` — preferred source for topic / action / flow /
+ apex / prompt counts.
+- `tree.depth`, `tree.node_count` — size metrics.
+- `tree._partial`, `tree._partial_reason` — health flag + prose reason.
+- `tree._pending_fetches` — `{"FLOW":[...],"APEX":[...],
+ "PROMPT_TEMPLATE":[...],"STANDARD_ACTION":[...]}`. Count determines
+ the "pending fetches: N" line in the callout.
+- `tree._unresolved` — triggers a second warn callout with the count.
+- `tree.agent.planner_name` — missing -> warn callout.
+
+**Output shape**: `## 2. Anatomy summary` + paragraph + zero-to-three
+blockquote callouts. Callouts render as `> **Health: PARTIAL.**` /
+`> **Health: WARN.**` prefixes with bullet sub-lines.
+
+**Empty/degenerate cases**: if `_kind_counts` is absent, the walker
+supplies counts from its own pass over the tree. Zero topics is valid
+(SequentialPlannerIntentClassifier).
+
+---
+
+## 3. Action tree
+
+**Purpose**: the full declared action tree as a flowchart with per-topic
+subgraphs, plus a deterministic ASCII appendix for diff review.
+
+**Input fields**:
+
+- Walker-derived `topics[]` -> one subgraph per topic.
+- Walker-derived `edges[]` -> `parent_api_name --> child_api_name`.
+- `node._cycle_back_to` -> dotted back-edge `A -.->|cycle_back_to: X| B`.
+- Planner-level actions (top-level `GEN_AI_FUNCTION` with no parent
+ topic) -> synthetic `_plannerActions` subgraph.
+
+**Output shape**: ` ```mermaid ` block with `flowchart TB` + subgraphs
++ edges, followed by a `<details>` with ASCII-tree appendix. When
+above cap, the mermaid block is replaced with the truncation
+placeholder; the ASCII appendix still renders.
+
+**Empty/degenerate cases**:
+
+- No topics, no planner actions -> `%% no topics` + `%% no edges`
+ mermaid comments; diagram still parses.
+- Cycle annotations render in both the mermaid (dotted edge) and the
+ ASCII appendix (`[cycle]` marker on the node line).
+
+---
+
+## 4. Topic anatomy
+
+**Purpose**: per-topic detail dump. One H3 per topic with a bullet list
+of actions.
+
+**Input fields**:
+
+- Walker-derived `topics[]` with `api_name`, `label`, `actions`.
+- `topic.raw.master_label` (preferred) or api_name for the label.
+
+**Output shape**: `## 4. Topic anatomy` + one `### \`<api_name>\``
+block per topic + kv list (`- Label:`, `- Action count:`, `- Actions:`
+with sub-bullets).
+
+**Empty/degenerate cases**: 0 topics -> `_No topics defined (planner
+exposes actions directly)._` italic fallback. This is the expected
+case for `SequentialPlannerIntentClassifier`.
+
+---
+
+## 5. Action catalog
+
+**Purpose**: flat markdown table of every declared action.
+
+**Input fields**:
+
+- Walker-derived `actions[]` with `api_name`, `topic`, `raw.unwraps_to`.
+
+**Output shape**: 3-col table (`Action | Topic | Unwraps to`). Unwraps
+column renders as `KIND \`api_name\`` when `unwraps_to` is present, `-`
+otherwise. Planner-level actions show `(plannerAction)` in the topic
+column.
+
+**Empty/degenerate cases**: no actions -> `_No actions declared._`
+italic fallback.
+
+---
+
+## 6. Data flow / context propagation
+
+**Purpose**: show which slot values propagate from user utterance
+through the planner into each action.
+
+**Input fields**:
+
+- Walker-derived `topics[]` and `actions[]`.
+- `action.raw.planner_attr.variable_name` + `planner_attr.data_type` —
+ labels the edge `A -->|var: Type| B`. When absent, the edge is bare.
+
+**Output shape**: `flowchart LR` via `load_mermaid("data_flow", ...)`.
+Skeleton: `User` -> `Planner` -> each `Topic` -> each `Action` under
+that topic.
+
+**Empty/degenerate cases**: no planner_attr metadata -> every edge is
+bare. 0 topics -> only `User --> Planner` renders (no action-level
+edges). Above cap -> truncation placeholder.
+
+---
+
+## 7. Flow / Apex / Prompt catalogs
+
+**Purpose**: per-artifact detail section for every backing flow, apex
+class, and prompt template referenced by any action.
+
+**Input fields**:
+
+- Walker-derived `flows{}`, `apex{}`, `prompts{}`, keyed on api_name.
+- `node.signature` (or `_signature` fallback) — signature block.
+
+**Output shape**: `### Flows` / `### Apex classes` / `### Prompt
+templates` H3 buckets, each containing `#### \`<api_name>\`` + a fenced
+signature block or `_Signature not captured._` fallback. Prompt
+templates render as a flat bullet list (signature capture is
+per-template prose, not a flow/apex shape).
+
+**Empty/degenerate cases**: no backing artifacts in the tree ->
+`_No backing artifacts in tree._` italic fallback.
+
+---
+
+## 8. Unresolved refs + artifact pointers
+
+**Purpose**: surface every `_unresolved[]` entry and point at the
+sidecar files the reader can open.
+
+**Input fields**:
+
+- `tree._unresolved[]` — list of `{kind, api_name, reason}` records.
+
+**Output shape**: Either a 3-col `Kind | Api name | Reason` table or
+an `_No unresolved references._` italic fallback. Followed by an
+`### Artifact pointers` sub-heading with a bullet list of relative
+paths (tree JSON, manifest, summary).
+
+**Empty/degenerate cases**: always renders — the artifact-pointer list
+is unconditional.
+
+---
+
+## Conditional: Dependency graph
+
+**Purpose**: rendered only when `tree._unresolved[]` is non-empty OR
+the tree contains cycle annotations. Shows cross-artifact dependencies
+plus the unresolved nodes as dashed-outline markers.
+
+**Input fields**:
+
+- Walker-derived `edges[]`.
+- `tree._unresolved[]` — each becomes a `:::unresolved` styled node.
+- Walker-derived `cycles[]` — each becomes a dotted back-edge.
+
+**Output shape**: `graph LR` via `load_mermaid("dependency_graph",
+...)`. Includes a `classDef unresolved` class marker at the bottom of
+the template so unresolved nodes render with `stroke-dasharray`.
+
+**Empty/degenerate cases**: not rendered at all when both conditions
+are false. Above the `graph` cap -> truncation placeholder replaces
+the mermaid block.