aac-cli 0.2.6__tar.gz → 0.2.8__tar.gz

{aac_cli-0.2.6 → aac_cli-0.2.8}/PKG-INFO

@@ -1,10 +1,15 @@
 Metadata-Version: 2.4
 Name: aac-cli
-Version: 0.2.6
+Version: 0.2.8
 Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
 Author: Agent Authority Cloud Project
 License-Expression: Apache-2.0
-Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/aeg.html
+Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/cli/
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
@@ -32,6 +37,10 @@ incoming ones against public trust material the tenant publishes.
 New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-starter-guide/#what-aac-is-for)
 explains what delegated authority between agents buys you, and what it does not.
 
+The [CLI user guide and complete command reference](https://cascadeauth.github.io/aac-starter-guide/cli/)
+cover developer and enterprise onboarding, everyday administration and recovery.
+Select documentation matching `aac --version`.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -59,7 +68,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.11 or newer is required.
+Python 3.11 to 3.14 is supported. Release checks test all four versions.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -796,6 +805,15 @@ AAC.
 
 ## Output and exit codes
 
+For scripts, `aac profile show NAME --field tenant-id` prints the effective
+tenant ID (including `AAC_TENANT_ID` overrides), and
+`aac tenant assign-hosted-domain --field trust-domain` prints the validated
+server-returned domain. Existing agents expose read-only identities through
+`aac agent status --agent NAME --field tenant-id`, `--field hosted-trust-domain`
+or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
+an unavailable value or unhealthy agent fails with empty stdout. `--field`
+cannot be combined with explicit `--output`, or with agent `--remote`.
+
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
 so the JSON stays parseable in scripts; `--output table` prints a readable

aac_cli-0.2.6/aac_cli.egg-info/PKG-INFO → aac_cli-0.2.8/README.md

@@ -1,25 +1,3 @@
-Metadata-Version: 2.4
-Name: aac-cli
-Version: 0.2.6
-Summary: The aac platform CLI — headless operator interface to the AAC control plane (tenant registration, chain audit).
-Author: Agent Authority Cloud Project
-License-Expression: Apache-2.0
-Project-URL: Documentation, https://cascadeauth.github.io/aac-starter-guide/aeg.html
-Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-License-File: NOTICE
-License-File: THIRD_PARTY_NOTICES.md
-Requires-Dist: httpx>=0.28
-Requires-Dist: cryptography>=42.0
-Requires-Dist: PyYAML>=6.0
-Requires-Dist: pyvis<0.4,>=0.3.2
-Requires-Dist: jsonschema>=4.18
-Provides-Extra: test
-Requires-Dist: pytest>=8.0; extra == "test"
-Requires-Dist: pytest-httpx>=0.30; extra == "test"
-Dynamic: license-file
-
 # aac-cli — the `aac` command
 
 `aac` is the command-line tool for tenants of Agent Authority Cloud (AAC).
@@ -32,6 +10,10 @@ incoming ones against public trust material the tenant publishes.
 New to AAC? [What AAC is for](https://cascadeauth.github.io/aac-starter-guide/#what-aac-is-for)
 explains what delegated authority between agents buys you, and what it does not.
 
+The [CLI user guide and complete command reference](https://cascadeauth.github.io/aac-starter-guide/cli/)
+cover developer and enterprise onboarding, everyday administration and recovery.
+Select documentation matching `aac --version`.
+
 The `aac` command is how a tenant's operator does everything that is not
 done by the sidecar itself: register the tenant, sign in, manage keys,
 workloads and domains, and prepare a runnable local workload. Everything
@@ -59,7 +41,7 @@ pip install aac-cli
 aac --version
 ```
 
-Python 3.11 or newer is required.
+Python 3.11 to 3.14 is supported. Release checks test all four versions.
 
 > **Mind the name.** `pip install aac` installs an unrelated project that
 > happens to share the acronym. The AAC package is **`aac-cli`**; the
@@ -796,6 +778,15 @@ AAC.
 
 ## Output and exit codes
 
+For scripts, `aac profile show NAME --field tenant-id` prints the effective
+tenant ID (including `AAC_TENANT_ID` overrides), and
+`aac tenant assign-hosted-domain --field trust-domain` prints the validated
+server-returned domain. Existing agents expose read-only identities through
+`aac agent status --agent NAME --field tenant-id`, `--field hosted-trust-domain`
+or `--field workload-spiffe-id`. A successful scalar is one unquoted line;
+an unavailable value or unhealthy agent fails with empty stdout. `--field`
+cannot be combined with explicit `--output`, or with agent `--remote`.
+
 Every command that reports a result prints one JSON document to standard
 output by default, with progress notes and diagnostics on standard error,
 so the JSON stays parseable in scripts; `--output table` prints a readable

{aac_cli-0.2.6 → aac_cli-0.2.8}/aac_cli/__init__.py

@@ -10,4 +10,4 @@ entrypoint (`aac_cli.cli:entrypoint`).
 # test in bin/tests/test_cli_version_parity.py. A literal keeps the
 # shipped code free of import-time metadata lookups (and their
 # not-installed failure mode).
-__version__ = "0.2.6"
+__version__ = "0.2.8"

{aac_cli-0.2.6 → aac_cli-0.2.8}/aac_cli/_aeg/cli.py

@@ -23,6 +23,7 @@ from .inputs import (
     unjoinable_diagnostics,
 )
 from .model import extract_token_relation_graph
+from .provenance import SourceInput, summarize_sources
 from .visualizer import build_visual_aeg, write_html_aeg
 
 Query = Callable[[str, str], tuple[str, list]]
@@ -98,7 +99,7 @@ def _query(profile: str, root: str):
     raise InputError("online rendering requires the aeg command supplied by aac-cli")
 
 
-def _render(args, events, query: Query) -> int:
+def _render(args, events, query: Query, sources: list[SourceInput]) -> int:
     if args.profile is not None and not args.profile.strip():
         raise InputError("--profile must name an existing AAC CLI profile")
     if not (args.events or args.actions or args.profile or args.trace_json):
@@ -117,6 +118,14 @@ def _render(args, events, query: Query) -> int:
     if args.trace_json:
         trace_root, trace_events = read_trace(read_json(args.trace_json), str(args.trace_json))
         events.extend(trace_events)
+        sources.append(
+            SourceInput(
+                "Control-plane trace data",
+                str(args.trace_json),
+                "Saved export; original fetch time/status unavailable",
+                trace_events,
+            )
+        )
         if root and root != trace_root:
             raise InputError("selected root does not match --trace-json root_token_id")
     if root is None:
@@ -138,13 +147,47 @@ def _render(args, events, query: Query) -> int:
             if queried_root != root:
                 raise InputError("central response root does not match selected root")
             events.extend(central)
-            central_status = "available; best-effort metadata, not a complete execution record"
+            sources.append(
+                SourceInput(
+                    "Control-plane trace data",
+                    f"Profile: {args.profile}",
+                    "Live API query",
+                    central,
+                    "succeeded",
+                )
+            )
+            central_status = (
+                "Live API query succeeded"
+                if central
+                else "Live API query succeeded with no observations"
+            )
         except InputError as exc:
             query_failed = True
-            central_status = str(exc)
-            print(central_status, file=sys.stderr)
+            central_status = (
+                "Live API query failed; local graph is partial. See the command diagnostic."
+            )
+            # Preserve stable public codes without copying transport URLs/secrets.
+            for code in (
+                "ERR_TRACE_NOT_FOUND",
+                "ERR_API_KEY_INVALID",
+                "ERR_DATABASE_UNAVAILABLE",
+                "ERR_RATE_LIMITED",
+                "ERR_RATE_LIMITER_UNAVAILABLE",
+            ):
+                if re.search(r"\b" + code + r"\b", str(exc)):
+                    central_status += f" {code}."
+            sources.append(
+                SourceInput(
+                    "Control-plane trace data",
+                    f"Profile: {args.profile}",
+                    "Live API query",
+                    status="failed",
+                )
+            )
+            # Transport diagnostics may contain URLs; never copy them into a shareable HTML artifact.
+            print(str(exc), file=sys.stderr)
     elif args.trace_json:
-        central_status = f"saved trace: {args.trace_json}; offline metadata export"
+        central_status = "Saved export read offline; original fetch time/status unavailable"
     selected, diagnostics = select_events(events, root)
     graph = extract_token_relation_graph(selected)
     if not graph.tokens:
@@ -152,16 +195,6 @@ def _render(args, events, query: Query) -> int:
             "no reconstructable token observations for the selected root; supply sidecar evidence or an available central trace"
         )
     graph.diagnostics.extend(diagnostics)
-    graph.diagnostics.extend(
-        [
-            f"Selected root: {root}",
-            f"Central evidence: {central_status}",
-            "Partial evidence: only supplied observations are shown. Missing participants, ancestors, fields and outcomes are not success or failure.",
-            "Central metadata intentionally omits private business details, authority caps, exact expiry and full receipts. Forwarding may also omit or delay events.",
-            "Application records are reports, not verified business truth. A mint/receive success does not prove business completion. Receipt verdicts are observations, not re-verification by this tool.",
-            "Distinct action records are retained; these formats do not establish exactly-once business-action counts.",
-        ]
-    )
     protected = [
         *args.events,
         *args.actions,
@@ -171,6 +204,7 @@ def _render(args, events, query: Query) -> int:
     if args.output.resolve() in {path.resolve() for path in protected}:
         raise InputError("--output must not overwrite an evidence input")
     visual = build_visual_aeg(graph)
+    visual.provenance = summarize_sources(sources, selected, central_status=central_status)
     with tempfile.TemporaryDirectory(prefix="aac-aeg-") as directory:
         rendered = write_html_aeg(visual, root, out_dir=Path(directory))
         args.output.parent.mkdir(parents=True, exist_ok=True)
@@ -334,9 +368,17 @@ def main(
     args = parser(prog=prog, version_text=version_text).parse_args(argv)
     events = []
     try:
-        events = read_events(args.events) + read_actions(args.actions)
+        sources = []
+        for paths, reader, kind in (
+            (args.events, read_events, "Sidecar telemetry"),
+            (args.actions, read_actions, "Application action records"),
+        ):
+            for path in paths:
+                records = reader([path])
+                events.extend(records)
+                sources.append(SourceInput(kind, str(path), "Local file", records))
         return (
-            _render(args, events, query or _query)
+            _render(args, events, query or _query, sources)
             if args.command == "render"
             else _list(args, events, list_query)
         )

{aac_cli-0.2.6 → aac_cli-0.2.8}/aac_cli/_aeg/data/renderer-source.json

@@ -1,18 +1,20 @@
 {
-  "content_sha256": "f0477c0f8e73bffe5e111842d8aca3f5745345acb8cb58bed911deba7d826798",
+  "content_sha256": "6e8bcd00bd94c415e04af65deb527be4d1581a6a5396d74c95708d6dda97fca4",
   "files": {
     "__init__.py": "80d80a1ba35353d271cddf02532801c60b57f5ec06fb268ae823747742ce8979",
-    "cli.py": "8fa9605246ba0ddbd24e6034b9582049fac11df139d47ee9e2ee0f322ff53c4c",
+    "cli.py": "98aa2b0c528fefb5f1f90a16584a6fbda1f075ebfcf61605f52948cdb940a1af",
     "data/action-taken-v1.json": "d863343afe7f314646a73cf063480a7e650f93857d2ed5ec3a7b1f9838671fdf",
     "data/predicates-v1.json": "35e83a29feada10e8cfbef7009245146a9717d4f4fd58d74124e0ec91ae922c8",
     "from_sidecar.py": "6ac023f6925a13e94e0fee762656a02ca98981f2add194b052e9014ca48e2219",
     "inputs.py": "ebf1ca77957d29d59683348f6916bac3c21e2037f087f26ff7c7242d75edc77c",
-    "model.py": "b5cc3955c000b7f99881ff5f7f63d482bdc6434347cf2dbc5a2b50e29bfc5bc7",
+    "model.py": "b631dcd7af587dcc89c18e1058bc81fb1043f04250a0d6ea585f9c595fd75cfc",
     "narrative.py": "8ac4b12add84cc8be907cff5f25e58731ab1144888aec8d376e286de461a6179",
+    "provenance.py": "d310e13bfd45cb16edcc72e7b2bc28c916e3ff45208e2b44240e589f0ec0558d",
     "schemas.py": "c47e0138fb8bfeaf1db1725a00d4a37ff4a136a9e8f5907356b1006f301a9ded",
     "temporal.py": "b69081e9280d578dc1261a276da3178e979a02efaf1137f720b4520ed543a36d",
+    "theme.py": "ded47be13f5c591da95a1bb91ee1b665c1570c929d842bdaa1a41325d0b40caa",
     "timeline_source.py": "dc875458d69c6135b3ffe0db9c35e511da603b5d52409f780f3e1b74dc464520",
-    "visualizer.py": "98896508855684c5f91052919d4d70cc7aea116ce532e964c767be3586fc22ee"
+    "visualizer.py": "5eb7b863652c51a4a5751bcd8ae735b688e6e3e61089f0c158473ebb52ae6655"
   },
   "legal": {
     "LICENSE": "0d542e0c8804e39aa7f37eb00da5a762149dc682d7829451287e11b938e94594",

{aac_cli-0.2.6 → aac_cli-0.2.8}/aac_cli/_aeg/model.py

@@ -215,6 +215,9 @@ class TerminalNode:
     action_payload: dict = field(default_factory=dict)
     action_taken_by_spiffe_id: str | None = None
     action_taken_timestamp: str | None = None
+    # Canonical associations observed for this leaf and exact receiver workload.
+    # A trust-domain match, another token, or a wildcard is not such evidence.
+    observed_tenant_ids: tuple[str, ...] = ()
 
 
 @dataclass(frozen=True)
@@ -267,6 +270,9 @@ class TokenRelationGraph:
     actions: dict[str, list[UnifiedEvent]] = field(default_factory=dict)
     diagnostics: list[str] = field(default_factory=list)
     receipts: dict[str, list[UnifiedEvent]] = field(default_factory=dict)
+    # Retain conflicting creation claims even when one token's merged fields
+    # become unknown. Receiving/reporting observations cannot supply this map.
+    creator_tenant_claims: dict[str, tuple[str, ...]] = field(default_factory=dict)
 
 
 # ---------------------------------------------------------------------------
@@ -298,6 +304,37 @@ def extract_token_relation_graph(events: list[UnifiedEvent]) -> TokenRelationGra
         terminals,
     )
 
+    creation_events = [
+        event
+        for event in events
+        if event.event_type in {"mint_root", "attenuate", "composite_mint"}
+        and event.token_id in tokens
+        and not tokens[event.token_id].placeholder
+    ]
+    token_creators: dict[str, set[str]] = {}
+    for event in creation_events:
+        actor = event.raw_event.get("presenter_spiffe_id")
+        candidates = token_creators.setdefault(event.token_id, set())
+        if isinstance(actor, str) and actor:
+            candidates.add(actor)
+        # Another observation of this exact token may supply its agreed
+        # creator workload. Receiving tenant identity is never used here.
+        if tokens[event.token_id].creator_spiffe_id:
+            candidates.add(tokens[event.token_id].creator_spiffe_id)
+    creator_claims: dict[str, set[str]] = {}
+    for event in creation_events:
+        actor = event.raw_event.get("presenter_spiffe_id")
+        tenant = event.raw_event.get("tenant_id")
+        if isinstance(tenant, str) and tenant:
+            # A sparse creation row still disputes the same token's tenant.
+            # Preserve its possible tenant for the recorded creator candidates
+            # instead of silently turning a conflict into a unique association.
+            actors = (
+                (actor,) if isinstance(actor, str) and actor else token_creators[event.token_id]
+            )
+            for candidate in actors:
+                creator_claims.setdefault(candidate, set()).add(tenant)
+
     return TokenRelationGraph(
         tokens=tokens,
         originators=originators,
@@ -306,6 +343,9 @@ def extract_token_relation_graph(events: list[UnifiedEvent]) -> TokenRelationGra
         leaf_token_ids=leaf_token_ids,
         root_token_ids=root_token_ids,
         chain_failures=chain_failures,
+        creator_tenant_claims={
+            actor: tuple(sorted(tenants)) for actor, tenants in creator_claims.items()
+        },
         actions={
             tid: sorted(
                 (e for e in events if e.event_type == "action_taken" and e.token_id == tid),
@@ -787,7 +827,14 @@ def _extract_terminals(
     for the same token_id, its summary + payload + presenter are attached.
     """
     action_by_token: dict[str, list[UnifiedEvent]] = {}
+    receiver_claims: dict[tuple[str, str], set[str]] = {}
     for e in events:
+        if e.event_type in {"token_received", "receipt_observed", "action_taken"} or (
+            e.event_type == "chain_failure" and e.raw_event.get("wire_event_type") == "receive"
+        ):
+            actor, tenant = e.raw_event.get("actor_spiffe_id"), e.raw_event.get("tenant_id")
+            if isinstance(actor, str) and isinstance(tenant, str) and actor and tenant:
+                receiver_claims.setdefault((e.token_id, actor), set()).add(tenant)
         # TENANT_SOURCE_PREFIX (defined in aeg.schemas) is the shared
         # producer/consumer contract — `from_sidecar.py` sets
         # `source=f"{TENANT_SOURCE_PREFIX}{name}"` on per-tenant SIEM
@@ -823,6 +870,14 @@ def _extract_terminals(
             continue
         tenant_id = _tenant_from_spiffe_pattern(audience)
         workload_label = _workload_label_from_spiffe(audience)
+        # Readers accept identity strings, including opaque imported values.
+        # A pattern actor must not establish an exact receiver association even
+        # if it happens to equal the audience string; the view also guards it.
+        observed_tenants = (
+            tuple(sorted(receiver_claims.get((tid, audience), ())))
+            if not any(c in audience for c in "*?[")
+            else ()
+        )
         actions = sorted(
             action_by_token.get(tid, []),
             key=lambda e: (e.timestamp_iso, json.dumps(e.raw_event, sort_keys=True)),
@@ -845,6 +900,7 @@ def _extract_terminals(
                     leaf_token_id=tid,
                     tenant_id=tenant_id,
                     workload_label=workload_label,
+                    observed_tenant_ids=observed_tenants,
                     action_summary=raw.get("action_summary"),
                     action_payload=raw.get("action_payload") or {},
                     # B44.3: read the spec-canonical field name `actor_spiffe_id`
@@ -864,6 +920,7 @@ def _extract_terminals(
                     leaf_token_id=tid,
                     tenant_id=tenant_id,
                     workload_label=workload_label,
+                    observed_tenant_ids=observed_tenants,
                 )
             )
     return out

aac_cli-0.2.8/aac_cli/_aeg/provenance.py

@@ -0,0 +1,194 @@
+"""Render-time input inventory. Never infers acquisition from event contents."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from html import escape
+
+from .schemas import UnifiedEvent
+
+
+def participant_observations(events: list[UnifiedEvent]) -> tuple[tuple[str, str], ...]:
+    """Recorded reporting identity; a received token's presenter is not its reporter."""
+    pairs = set()
+    for event in events:
+        # Use normalized identity fields. Imported _record extensions remain
+        # opaque even when they happen to be dictionaries.
+        raw = event.raw_event
+        tenant = raw.get("tenant_id") or ""
+        actor = raw.get("actor_spiffe_id") or ""
+        if not actor and event.event_type in {"mint_root", "attenuate", "composite_mint"}:
+            actor = raw.get("presenter_spiffe_id") or ""
+        if tenant or actor:
+            pairs.add((str(tenant), str(actor)))
+    return tuple(sorted(pairs))
+
+
+@dataclass
+class SourceInput:
+    kind: str
+    label: str
+    acquisition: str
+    events: list[UnifiedEvent] = field(default_factory=list)
+    status: str = "read"
+
+
+@dataclass(frozen=True)
+class SourceSummary:
+    kind: str
+    label: str
+    acquisition: str
+    status: str
+    matching_records: int
+    participants: tuple[tuple[str, str], ...]
+    first_observed: str | None
+    last_observed: str | None
+
+
+@dataclass(frozen=True)
+class Provenance:
+    sources: tuple[SourceSummary, ...]
+    central_status: str
+
+
+def summarize_sources(
+    sources: list[SourceInput], selected: list[UnifiedEvent], *, central_status: str
+) -> Provenance:
+    # Selection retains the original event objects. Track membership by identity,
+    # not by a filename, timestamp or caller-controlled event field that could
+    # make an overlapping local record look like a successful central query.
+    selected_ids = {id(event) for event in selected}
+    summaries = []
+    for source in sources:
+        matching = [event for event in source.events if id(event) in selected_ids]
+        records = {event.raw_event.get("_source", id(event)) for event in matching}
+        times = sorted(
+            datetime.fromisoformat(event.timestamp_iso.replace("Z", "+00:00"))
+            .astimezone(timezone.utc)
+            .isoformat()
+            for event in matching
+        )
+        summaries.append(
+            SourceSummary(
+                source.kind,
+                source.label,
+                source.acquisition,
+                source.status,
+                len(records),
+                participant_observations(matching),
+                times[0] if times else None,
+                times[-1] if times else None,
+            )
+        )
+    return Provenance(tuple(summaries), central_status)
+
+
+def source_panel(provenance: Provenance | None, diagnostics: list[str]) -> str:
+    """One escaped, initially collapsed panel shared by CLI and hosted renders."""
+    sources = provenance.sources if provenance else ()
+    used = {source.kind for source in sources if source.matching_records}
+    summary = (
+        " + ".join(
+            kind
+            for kind in (
+                "Sidecar telemetry",
+                "Control-plane trace data",
+                "Application action records",
+            )
+            if kind in used
+        )
+        or "Source inventory not supplied"
+    )
+    parts = [
+        '<details id="aac-sources"><summary>Data sources used for this graph'
+        f'<span class="aac-source-summary">{escape(summary)}</span></summary>'
+        '<div class="aac-source-body">'
+    ]
+    if provenance is None:
+        parts.append(
+            "<p>This caller did not supply a source inventory. Files, acquisition method "
+            "and control-plane query status are unknown; they must not be inferred from the graph.</p>"
+        )
+    else:
+        parts.append(
+            f"<p><strong>Control-plane trace:</strong> {escape(provenance.central_status)}</p>"
+        )
+        parts.append(
+            '<div class="aac-source-table"><table><thead><tr><th>Source and input</th>'
+            "<th>Observed tenant / workload</th><th>Matching records</th>"
+            "<th>Observed record span (UTC)</th></tr></thead><tbody>"
+        )
+        for source in sources:
+            identities = (
+                "<br>".join(
+                    f"{escape(tenant or 'Tenant not recorded')} / {escape(actor or 'Workload not recorded')}"
+                    for tenant, actor in source.participants
+                )
+                or "No matching identity observations"
+            )
+            span = (
+                f"{escape(source.first_observed)} → {escape(source.last_observed or '')}"
+                if source.first_observed
+                else "No matching observations"
+            )
+            contribution = "Contributed" if source.matching_records else "Did not contribute"
+            parts.append(
+                f"<tr><td><strong>{escape(source.kind)}</strong><br><code>{escape(source.label)}</code>"
+                f"<br>{escape(source.acquisition)} · {escape(source.status)} · {contribution}</td>"
+                f"<td>{identities}</td><td>{source.matching_records}</td><td>{span}</td></tr>"
+            )
+        parts.append(
+            "</tbody></table></div><p>Counts describe matching input rows for files or normalized "
+            "observations for hosted data, not unique business actions. Timestamp spans describe "
+            "available records, not execution start/end or continuous coverage.</p>"
+        )
+    parts.append(
+        "<h2>Limitations for these inputs</h2><ul><li>Partial evidence: only supplied, "
+        "correlated observations are shown. Missing records do not establish success or failure.</li>"
+        "<li>An intended recipient is named by an audience constraint; that constraint alone "
+        "does not prove delivery or completion. Mint/transport success does not prove a business result.</li>"
+    )
+    if "Control-plane trace data" in used:
+        parts.append(
+            "<li>Central metadata omits private business details, authority caps, exact expiry "
+            "and full receipts. Best-effort forwarding may omit or delay events.</li>"
+        )
+    if "Application action records" in used:
+        parts.append(
+            "<li>Application records are reports, not independently verified business truth.</li>"
+        )
+    if "Sidecar telemetry" in used:
+        parts.append(
+            "<li>Receipt verdicts are recorded sidecar observations; AEG does not re-verify signatures.</li>"
+        )
+    parts.append(
+        "<li>Repeated records do not establish exactly-once business-action counts.</li></ul>"
+    )
+    if diagnostics:
+        parts.append(
+            "<h3>Input diagnostics</h3><ul>"
+            + "".join(f"<li>{escape(note)}</li>" for note in dict.fromkeys(diagnostics))
+            + "</ul>"
+        )
+    parts.append(
+        '<section class="aac-next-steps"><h2>If an action or result is missing</h2>'
+        "<p>Check the chain root/attempt, input files, observed times and query status first.</p><ul>"
+        "<li><strong>Missing tokens, participants or handoffs:</strong> add authorized participants’ "
+        "retained sidecar files with <code>--events FILE</code>. An authorized trace via "
+        "<code>--profile PROFILE</code> or a saved <code>--trace-json FILE</code> export may add "
+        "forwarded observations. For a sidecar + application graph (combo 3), adding a profile "
+        "uses combo 4; it does not guarantee a missing result.</li>"
+        "<li><strong>Missing business details/results:</strong> add matching structured "
+        "<code>action_taken</code> records with <code>--actions FILE</code>; check token IDs and "
+        "the token-to-root mapping. Arbitrary application logs are not supported. More central "
+        "data cannot supply private business payloads or full receipts.</li>"
+        "<li><strong>Failed query:</strong> follow the diagnostic; check profile/access configuration "
+        "and connectivity, then retry. Failure is not a successful empty query.</li>"
+        "<li><strong>Possibly delayed forwarding:</strong> render again later or use retained local "
+        "files. Data never recorded, never forwarded or no longer retained may remain unavailable.</li>"
+        "</ul><p>More source categories help only when matching records exist. Otherwise leave the "
+        "outcome unknown. Rendering again reads evidence; it does not rerun the business action.</p>"
+        "</section></div></details>"
+    )
+    return "".join(parts)