diff --git a/docs/agent-map.html b/docs/agent-map.html
index 1fbc9b1..54cf973 100644
--- a/docs/agent-map.html
+++ b/docs/agent-map.html
@@ -807,6 +807,60 @@
     }
     .mini-pill:hover { background: rgba(6, 189, 180, 0.14); border-color: var(--teal); }
     .p-dim { margin: 0; font-size: 0.8rem; font-weight: 300; color: var(--ink-4); }
+    .p-summary {
+      margin: 0.35rem 0 0;
+      font-size: 0.92rem;
+      font-weight: 400;
+      line-height: 1.45;
+      color: var(--ink-2);
+      letter-spacing: -0.01em;
+    }
+    .p-purpose {
+      margin: 0.55rem 0 0;
+      font-size: 0.84rem;
+      font-weight: 300;
+      line-height: 1.5;
+      color: var(--ink-3);
+    }
+    .p-io {
+      margin: 0;
+      padding: 0;
+      list-style: none;
+      display: flex;
+      flex-direction: column;
+      gap: 0.35rem;
+      font-size: 0.78rem;
+      line-height: 1.4;
+      color: var(--ink-2);
+    }
+    .p-io li {
+      padding-left: 0.85rem;
+      position: relative;
+    }
+    .p-io li::before {
+      content: "";
+      position: absolute;
+      left: 0;
+      top: 0.55em;
+      width: 5px;
+      height: 5px;
+      border-radius: 50%;
+      background: var(--teal);
+      opacity: 0.7;
+    }
+    .p-usage {
+      margin: 0;
+      padding: 0.75rem 0.85rem;
+      border-radius: 12px;
+      background: rgba(35, 39, 61, 0.04);
+      border: 1px solid var(--hairline);
+      font-family: var(--mono);
+      font-size: 0.68rem;
+      line-height: 1.45;
+      color: var(--navy);
+      white-space: pre-wrap;
+      overflow-x: auto;
+    }
     .conn-list { margin: 0; padding: 0; list-style: none; display: flex; flex-direction: column; gap: 0.4rem; }
     .conn-list li { font-family: var(--mono); font-size: 0.74rem; color: var(--ink-3); }
     .conn-list .dir { color: var(--teal); }
@@ -1843,9 +1897,11 @@ <h2>Every agent, by stage.</h2>
     <div class="panel-inner" id="panel-content"></div>
   </aside>
 
-  <script id="graph-data" type="application/json">{"generated_by":"scripts/generate-manifest.ts","total_nodes":77,"total_edges":27,"nodes":[{"id":"0.1","name":"Airport/City Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airport-code-resolver/index.ts"},{"id":"0.2","name":"Airline Code & Alliance Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airline-code-mapper/index.ts"},{"id":"0.3","name":"Fare Basis Code Decoder","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/fare-basis-decoder/index.ts"},{"id":"0.4","name":"Class of Service Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/class-of-service-mapper/index.ts"},{"id":"0.5","name":"Equipment Type Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/equipment-type-resolver/index.ts"},{"id":"0.6","name":"Currency & Tax Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/currency-tax-resolver/index.ts"},{"id":"0.7","name":"Country Regulatory Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/country-regulatory-resolver/index.ts"},{"id":"1.1","name":"Availability Search","stage":"search","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/availability-search/index.ts"},{"id":"1.2","name":"Schedule Lookup","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/schedule-lookup/index.ts"},{"id":"1.3","name":"Connection Builder","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/connection-builder/index.ts"},{"id":"1.4","name":"Fare Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/fare-shopping/index.ts"},{"id":"1.5","name":"Ancillary Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/ancillary-shopping/index.ts"},{"id":"1.6","name":"Multi-Source Aggregator","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/multi-source-aggregator/index.ts"},{"id":"1.7","name":"Hotel & Car Search","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/hotel-car-search/index.ts"},{"id":"1.8","name":"AI Travel Advisor","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/ai-travel-advisor/index.ts"},{"id":"1.9","name":"Offer Evaluator","stage":"core","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/core/src/agents/shopping/offer-evaluator/index.ts"},{"id":"2.1","name":"Fare Rule Agent","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/fare-rule-agent/index.ts"},{"id":"2.2","name":"Fare Construction","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/fare-construction/index.ts"},{"id":"2.3","name":"Tax Calculation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/tax-calculation/index.ts"},{"id":"2.4","name":"Offer Builder","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/offer-builder/index.ts"},{"id":"2.5","name":"Corporate Policy Validation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/corporate-policy-validation/index.ts"},{"id":"2.6","name":"Dynamic Pricing","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/dynamic-pricing/index.ts"},{"id":"2.7","name":"Revenue Management","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/revenue-management/index.ts"},{"id":"3.1","name":"GDS/NDC Router","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/gds-ndc-router/index.ts"},{"id":"3.2","name":"PNR Builder","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-builder/index.ts"},{"id":"3.3","name":"PNR Validation","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/pnr-validation/index.ts"},{"id":"3.4","name":"Queue Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/queue-management/index.ts"},{"id":"3.5","name":"API Abstraction","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/api-abstraction/index.ts"},{"id":"3.6","name":"Order Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/order-management/index.ts"},{"id":"3.7","name":"Payment Processing","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/payment-processing/index.ts"},{"id":"3.8","name":"PNR Retrieval","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-retrieval/index.ts"},{"id":"4.1","name":"Ticket Issuance","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/ticketing/src/ticket-issuance/index.ts"},{"id":"4.2","name":"EMD Management","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/emd-management/index.ts"},{"id":"4.3","name":"Void Agent","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/void-agent/index.ts"},{"id":"4.4","name":"Itinerary Delivery","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/itinerary-delivery/index.ts"},{"id":"4.5","name":"Document Verification","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/document-verification/index.ts"},{"id":"5.1","name":"Change Management","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/change-management/index.ts"},{"id":"5.2","name":"Exchange/Reissue","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/exchange-reissue/index.ts"},{"id":"5.3","name":"Involuntary Rebook","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/involuntary-rebook/index.ts"},{"id":"5.4","name":"Disruption Response","stage":"exchange","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/exchange/src/disruption-response/index.ts"},{"id":"5.5","name":"Self-Service Rebooking","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/self-service-rebooking/index.ts"},{"id":"5.6","name":"Waitlist Management","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/waitlist-management/index.ts"},{"id":"6.1","name":"Refund Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/refund-processing/index.ts"},{"id":"6.2","name":"ADM Prevention","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-prevention/index.ts"},{"id":"6.3","name":"ADM/ACM Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-acm-processing/index.ts"},{"id":"6.4","name":"Customer Communication","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/customer-communication/index.ts"},{"id":"6.5","name":"Feedback & Complaint","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/feedback-complaint/index.ts"},{"id":"6.6","name":"Loyalty Mileage","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/loyalty-mileage/index.ts"},{"id":"7.1","name":"BSP Reconciliation","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/bsp-reconciliation/index.ts"},{"id":"7.2","name":"ARC Reconciliation","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/arc-reconciliation/index.ts"},{"id":"7.3","name":"Commission Management","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/commission-management/index.ts"},{"id":"7.4","name":"Interline Settlement","stage":"reconciliation","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/reconciliation/src/interline-settlement/index.ts"},{"id":"7.5","name":"Financial Reporting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/financial-reporting/index.ts"},{"id":"7.6","name":"Revenue Accounting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/revenue-accounting/index.ts"},{"id":"8.1","name":"Traveler Profile","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/traveler-profile/index.ts"},{"id":"8.2","name":"Corporate Account","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/corporate-account/index.ts"},{"id":"8.3","name":"Mid-Office Automation","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/mid-office/index.ts"},{"id":"8.4","name":"Reporting & Analytics","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/reporting/index.ts"},{"id":"8.5","name":"Duty of Care","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/duty-of-care/index.ts"},{"id":"9.1","name":"Orchestrator","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/orchestrator/index.ts"},{"id":"9.2","name":"Knowledge Retrieval","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/knowledge/index.ts"},{"id":"9.3","name":"Monitoring & Alerting","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/monitoring/index.ts"},{"id":"9.4","name":"Audit & Compliance","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/audit/index.ts"},{"id":"9.5","name":"Plugin Manager","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/plugin-manager/index.ts"},{"id":"9.6","name":"Performance Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/performance-audit/index.ts"},{"id":"9.7","name":"Routing Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/routing-audit/index.ts"},{"id":"9.8","name":"Recommendation","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/recommendation/index.ts"},{"id":"9.9","name":"Alert","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/alert/index.ts"},{"id":"20.1","name":"Hotel Search Aggregator","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-search/index.ts"},{"id":"20.2","name":"Property Deduplication","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/property-dedup/index.ts"},{"id":"20.3","name":"Hotel Content Normalization","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/content-normalization/index.ts"},{"id":"20.4","name":"Hotel Rate Comparison","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/rate-comparison/index.ts"},{"id":"20.5","name":"Hotel Booking","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-booking/index.ts"},{"id":"20.6","name":"Hotel Modification & Cancellation","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-modification/index.ts"},{"id":"20.7","name":"Confirmation Verification","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/confirmation-verification/index.ts"},{"id":"20.8","name":"Activity Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/activity-search/index.ts"},{"id":"20.9","name":"Transfer Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/transfer-search/index.ts"}],"edges":[{"source":"1.1","target":"1.4","kind":"workflow","label":"search_to_price"},{"source":"1.4","target":"2.1","kind":"workflow","label":"search_to_price"},{"source":"2.1","target":"2.2","kind":"workflow","label":"search_to_price"},{"source":"2.2","target":"2.3","kind":"workflow","label":"search_to_price"},{"source":"3.3","target":"3.1","kind":"workflow","label":"book_to_ticket"},{"source":"3.1","target":"3.2","kind":"workflow","label":"book_to_ticket"},{"source":"3.2","target":"4.1","kind":"workflow","label":"book_to_ticket"},{"source":"1.1","target":"1.4","kind":"workflow","label":"full_booking"},{"source":"1.4","target":"2.1","kind":"workflow","label":"full_booking"},{"source":"2.1","target":"2.2","kind":"workflow","label":"full_booking"},{"source":"2.2","target":"2.3","kind":"workflow","label":"full_booking"},{"source":"2.3","target":"3.3","kind":"workflow","label":"full_booking"},{"source":"3.3","target":"3.1","kind":"workflow","label":"full_booking"},{"source":"3.1","target":"3.2","kind":"workflow","label":"full_booking"},{"source":"3.2","target":"4.1","kind":"workflow","label":"full_booking"},{"source":"5.1","target":"5.2","kind":"workflow","label":"exchange_flow"},{"source":"6.1","target":"6.2","kind":"workflow","label":"refund_flow"},{"source":"1.1","target":"0.1","kind":"package","label":"@otaip/agents-search → @otaip/agents-reference"},{"source":"2.1","target":"0.1","kind":"package","label":"@otaip/agents-pricing → @otaip/agents-reference"},{"source":"3.1","target":"0.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-reference"},{"source":"3.1","target":"1.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-search"},{"source":"3.1","target":"2.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-pricing"},{"source":"4.1","target":"3.1","kind":"package","label":"@otaip/agents-ticketing → @otaip/agents-booking"},{"source":"5.1","target":"1.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-search"},{"source":"5.1","target":"4.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-ticketing"},{"source":"6.1","target":"4.1","kind":"package","label":"@otaip/agents-settlement → @otaip/agents-ticketing"},{"source":"7.1","target":"0.1","kind":"package","label":"@otaip/agents-reconciliation → @otaip/agents-reference"}],"package_deps":[{"from_package":"@otaip/agents-search","to_package":"@otaip/agents-reference","from_stage":"search","to_stage":"reference"},{"from_package":"@otaip/agents-pricing","to_package":"@otaip/agents-reference","from_stage":"pricing","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-reference","from_stage":"booking","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-search","from_stage":"booking","to_stage":"search"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-pricing","from_stage":"booking","to_stage":"pricing"},{"from_package":"@otaip/agents-ticketing","to_package":"@otaip/agents-booking","from_stage":"ticketing","to_stage":"booking"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-search","from_stage":"exchange","to_stage":"search"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-ticketing","from_stage":"exchange","to_stage":"ticketing"},{"from_package":"@otaip/agents-settlement","to_package":"@otaip/agents-ticketing","from_stage":"settlement","to_stage":"ticketing"},{"from_package":"@otaip/agents-reconciliation","to_package":"@otaip/agents-reference","from_stage":"reconciliation","to_stage":"reference"}]}</script>
+  <script id="graph-data" type="application/json">{"graph":{"generated_by":"scripts/generate-manifest.ts","total_nodes":77,"total_edges":27,"nodes":[{"id":"0.1","name":"Airport/City Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airport-code-resolver/index.ts"},{"id":"0.2","name":"Airline Code & Alliance Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/airline-code-mapper/index.ts"},{"id":"0.3","name":"Fare Basis Code Decoder","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/reference/src/fare-basis-decoder/index.ts"},{"id":"0.4","name":"Class of Service Mapper","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/class-of-service-mapper/index.ts"},{"id":"0.5","name":"Equipment Type Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/equipment-type-resolver/index.ts"},{"id":"0.6","name":"Currency & Tax Code Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/currency-tax-resolver/index.ts"},{"id":"0.7","name":"Country Regulatory Resolver","stage":"reference","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reference/src/country-regulatory-resolver/index.ts"},{"id":"1.1","name":"Availability Search","stage":"search","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/availability-search/index.ts"},{"id":"1.2","name":"Schedule Lookup","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/schedule-lookup/index.ts"},{"id":"1.3","name":"Connection Builder","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/connection-builder/index.ts"},{"id":"1.4","name":"Fare Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/fare-shopping/index.ts"},{"id":"1.5","name":"Ancillary Shopping","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/ancillary-shopping/index.ts"},{"id":"1.6","name":"Multi-Source Aggregator","stage":"search","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/search/src/multi-source-aggregator/index.ts"},{"id":"1.7","name":"Hotel & Car Search","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/hotel-car-search/index.ts"},{"id":"1.8","name":"AI Travel Advisor","stage":"search","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/search/src/ai-travel-advisor/index.ts"},{"id":"1.9","name":"Offer Evaluator","stage":"core","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/core/src/agents/shopping/offer-evaluator/index.ts"},{"id":"2.1","name":"Fare Rule Agent","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/fare-rule-agent/index.ts"},{"id":"2.2","name":"Fare Construction","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/fare-construction/index.ts"},{"id":"2.3","name":"Tax Calculation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/tax-calculation/index.ts"},{"id":"2.4","name":"Offer Builder","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/pricing/src/offer-builder/index.ts"},{"id":"2.5","name":"Corporate Policy Validation","stage":"pricing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/pricing/src/corporate-policy-validation/index.ts"},{"id":"2.6","name":"Dynamic Pricing","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/dynamic-pricing/index.ts"},{"id":"2.7","name":"Revenue Management","stage":"pricing","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/pricing/src/revenue-management/index.ts"},{"id":"3.1","name":"GDS/NDC Router","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/gds-ndc-router/index.ts"},{"id":"3.2","name":"PNR Builder","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-builder/index.ts"},{"id":"3.3","name":"PNR Validation","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/pnr-validation/index.ts"},{"id":"3.4","name":"Queue Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/queue-management/index.ts"},{"id":"3.5","name":"API Abstraction","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/api-abstraction/index.ts"},{"id":"3.6","name":"Order Management","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/order-management/index.ts"},{"id":"3.7","name":"Payment Processing","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/booking/src/payment-processing/index.ts"},{"id":"3.8","name":"PNR Retrieval","stage":"booking","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/booking/src/pnr-retrieval/index.ts"},{"id":"4.1","name":"Ticket Issuance","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/ticketing/src/ticket-issuance/index.ts"},{"id":"4.2","name":"EMD Management","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/emd-management/index.ts"},{"id":"4.3","name":"Void Agent","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/void-agent/index.ts"},{"id":"4.4","name":"Itinerary Delivery","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/itinerary-delivery/index.ts"},{"id":"4.5","name":"Document Verification","stage":"ticketing","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/ticketing/src/document-verification/index.ts"},{"id":"5.1","name":"Change Management","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/change-management/index.ts"},{"id":"5.2","name":"Exchange/Reissue","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/exchange-reissue/index.ts"},{"id":"5.3","name":"Involuntary Rebook","stage":"exchange","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/exchange/src/involuntary-rebook/index.ts"},{"id":"5.4","name":"Disruption Response","stage":"exchange","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/exchange/src/disruption-response/index.ts"},{"id":"5.5","name":"Self-Service Rebooking","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/self-service-rebooking/index.ts"},{"id":"5.6","name":"Waitlist Management","stage":"exchange","version":"0.2.0","contract_status":"active","has_contract":true,"source_path":"packages/agents/exchange/src/waitlist-management/index.ts"},{"id":"6.1","name":"Refund Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/refund-processing/index.ts"},{"id":"6.2","name":"ADM Prevention","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-prevention/index.ts"},{"id":"6.3","name":"ADM/ACM Processing","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/adm-acm-processing/index.ts"},{"id":"6.4","name":"Customer Communication","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/customer-communication/index.ts"},{"id":"6.5","name":"Feedback & Complaint","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/feedback-complaint/index.ts"},{"id":"6.6","name":"Loyalty Mileage","stage":"settlement","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/settlement/src/loyalty-mileage/index.ts"},{"id":"7.1","name":"BSP Reconciliation","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/bsp-reconciliation/index.ts"},{"id":"7.2","name":"ARC Reconciliation","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/arc-reconciliation/index.ts"},{"id":"7.3","name":"Commission Management","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/commission-management/index.ts"},{"id":"7.4","name":"Interline Settlement","stage":"reconciliation","version":"0.0.0","contract_status":"stub","has_contract":false,"source_path":"packages/agents/reconciliation/src/interline-settlement/index.ts"},{"id":"7.5","name":"Financial Reporting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/financial-reporting/index.ts"},{"id":"7.6","name":"Revenue Accounting","stage":"reconciliation","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/reconciliation/src/revenue-accounting/index.ts"},{"id":"8.1","name":"Traveler Profile","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/traveler-profile/index.ts"},{"id":"8.2","name":"Corporate Account","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/corporate-account/index.ts"},{"id":"8.3","name":"Mid-Office Automation","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/mid-office/index.ts"},{"id":"8.4","name":"Reporting & Analytics","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/reporting/index.ts"},{"id":"8.5","name":"Duty of Care","stage":"tmc","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-tmc/src/duty-of-care/index.ts"},{"id":"9.1","name":"Orchestrator","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/orchestrator/index.ts"},{"id":"9.2","name":"Knowledge Retrieval","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/knowledge/index.ts"},{"id":"9.3","name":"Monitoring & Alerting","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/monitoring/index.ts"},{"id":"9.4","name":"Audit & Compliance","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/audit/index.ts"},{"id":"9.5","name":"Plugin Manager","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents-platform/src/plugin-manager/index.ts"},{"id":"9.6","name":"Performance Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/performance-audit/index.ts"},{"id":"9.7","name":"Routing Audit","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/routing-audit/index.ts"},{"id":"9.8","name":"Recommendation","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/recommendation/index.ts"},{"id":"9.9","name":"Alert","stage":"platform","version":"0.1.0","contract_status":"active","has_contract":true,"source_path":"packages/agents-platform/src/alert/index.ts"},{"id":"20.1","name":"Hotel Search Aggregator","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-search/index.ts"},{"id":"20.2","name":"Property Deduplication","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/property-dedup/index.ts"},{"id":"20.3","name":"Hotel Content Normalization","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/content-normalization/index.ts"},{"id":"20.4","name":"Hotel Rate Comparison","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/rate-comparison/index.ts"},{"id":"20.5","name":"Hotel Booking","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-booking/index.ts"},{"id":"20.6","name":"Hotel Modification & Cancellation","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/hotel-modification/index.ts"},{"id":"20.7","name":"Confirmation Verification","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/confirmation-verification/index.ts"},{"id":"20.8","name":"Activity Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/activity-search/index.ts"},{"id":"20.9","name":"Transfer Search","stage":"lodging","version":"0.1.0","contract_status":"active","has_contract":false,"source_path":"packages/agents/lodging/src/transfer-search/index.ts"}],"edges":[{"source":"1.1","target":"1.4","kind":"workflow","label":"search_to_price"},{"source":"1.4","target":"2.1","kind":"workflow","label":"search_to_price"},{"source":"2.1","target":"2.2","kind":"workflow","label":"search_to_price"},{"source":"2.2","target":"2.3","kind":"workflow","label":"search_to_price"},{"source":"3.3","target":"3.1","kind":"workflow","label":"book_to_ticket"},{"source":"3.1","target":"3.2","kind":"workflow","label":"book_to_ticket"},{"source":"3.2","target":"4.1","kind":"workflow","label":"book_to_ticket"},{"source":"1.1","target":"1.4","kind":"workflow","label":"full_booking"},{"source":"1.4","target":"2.1","kind":"workflow","label":"full_booking"},{"source":"2.1","target":"2.2","kind":"workflow","label":"full_booking"},{"source":"2.2","target":"2.3","kind":"workflow","label":"full_booking"},{"source":"2.3","target":"3.3","kind":"workflow","label":"full_booking"},{"source":"3.3","target":"3.1","kind":"workflow","label":"full_booking"},{"source":"3.1","target":"3.2","kind":"workflow","label":"full_booking"},{"source":"3.2","target":"4.1","kind":"workflow","label":"full_booking"},{"source":"5.1","target":"5.2","kind":"workflow","label":"exchange_flow"},{"source":"6.1","target":"6.2","kind":"workflow","label":"refund_flow"},{"source":"1.1","target":"0.1","kind":"package","label":"@otaip/agents-search → @otaip/agents-reference"},{"source":"2.1","target":"0.1","kind":"package","label":"@otaip/agents-pricing → @otaip/agents-reference"},{"source":"3.1","target":"0.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-reference"},{"source":"3.1","target":"1.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-search"},{"source":"3.1","target":"2.1","kind":"package","label":"@otaip/agents-booking → @otaip/agents-pricing"},{"source":"4.1","target":"3.1","kind":"package","label":"@otaip/agents-ticketing → @otaip/agents-booking"},{"source":"5.1","target":"1.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-search"},{"source":"5.1","target":"4.1","kind":"package","label":"@otaip/agents-exchange → @otaip/agents-ticketing"},{"source":"6.1","target":"4.1","kind":"package","label":"@otaip/agents-settlement → @otaip/agents-ticketing"},{"source":"7.1","target":"0.1","kind":"package","label":"@otaip/agents-reconciliation → @otaip/agents-reference"}],"package_deps":[{"from_package":"@otaip/agents-search","to_package":"@otaip/agents-reference","from_stage":"search","to_stage":"reference"},{"from_package":"@otaip/agents-pricing","to_package":"@otaip/agents-reference","from_stage":"pricing","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-reference","from_stage":"booking","to_stage":"reference"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-search","from_stage":"booking","to_stage":"search"},{"from_package":"@otaip/agents-booking","to_package":"@otaip/agents-pricing","from_stage":"booking","to_stage":"pricing"},{"from_package":"@otaip/agents-ticketing","to_package":"@otaip/agents-booking","from_stage":"ticketing","to_stage":"booking"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-search","from_stage":"exchange","to_stage":"search"},{"from_package":"@otaip/agents-exchange","to_package":"@otaip/agents-ticketing","from_stage":"exchange","to_stage":"ticketing"},{"from_package":"@otaip/agents-settlement","to_package":"@otaip/agents-ticketing","from_stage":"settlement","to_stage":"ticketing"},{"from_package":"@otaip/agents-reconciliation","to_package":"@otaip/agents-reference","from_stage":"reconciliation","to_stage":"reference"}]},"docs":{"0.1":{"id":"0.1","summary":"Resolves IATA/ICAO airport and city codes to canonical airport records with multi-airport city awareness and historical code handling","className":"AirportCodeResolver","input":"`code` -- IATA 3-letter, ICAO 4-letter, city code, or airport name\n`code_type?` -- `'iata' | 'icao' | 'city' | 'name' | 'auto'` (auto-detected if omitted)\n`include_metro?` -- return all airports in a metro/city code (default: true)\n`include_decommissioned?` -- resolve retired/reassigned codes (default: false)","output":"`resolved_airport` -- canonical airport record (IATA, ICAO, name, city, country, timezone, lat/lon, type, status)\n`metro_airports` -- list of airports in the same metro area\n`match_confidence` -- 0-1 confidence score\n`stale_data?` -- true when dataset is older than 30 days\n`suggestion?` -- fuzzy match suggestion when code not found","usage":"const agent = new AirportCodeResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'JFK', code_type: 'iata' } });\n// result.data.resolved_airport.name => \"John F Kennedy International Airport\"","status":"Implemented","purpose":"Resolves IATA/ICAO airport and city codes to canonical airport records with multi-airport city awareness, fuzzy name matching, and historical code handling."},"0.2":{"id":"0.2","summary":"Resolves IATA/ICAO airline designator codes to canonical airline records with alliance membership mapping and codeshare partner networks","className":"AirlineCodeMapper","input":"`code` -- IATA 2-letter, ICAO 3-letter, or airline name\n`code_type?` -- `'iata' | 'icao' | 'name' | 'auto'`\n`include_codeshares?` -- include codeshare partners (default: false)\n`include_defunct?` -- include ceased-operations airlines (default: false)","output":"`airline` -- canonical airline record (codes, name, callsign, country, alliance, hubs, status)\n`codeshare_partners` -- partner airline list with relationship type\n`match_confidence` -- 0-1 confidence score","usage":"const agent = new AirlineCodeMapper();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'UA', include_codeshares: true } });\n// result.data.airline.name => \"United Airlines\"","status":"Implemented","purpose":"Resolves IATA/ICAO airline codes to canonical airline records with alliance membership and codeshare partner networks."},"0.3":{"id":"0.3","summary":"Decodes ATPCO-standard fare basis codes into human-readable components including cabin class, fare restrictions, advance purchase requirements, and penalty information","className":"FareBasisDecoder","input":"`fare_basis` -- ATPCO fare basis code (max 15 chars, e.g., `\"YOW3M1\"`, `\"TLXP14NR\"`)\n`carrier?` -- IATA airline code for carrier-specific decoding","output":"`decoded` -- parsed components (primary code, cabin class, fare type, season, day-of-week, advance purchase, min/max stay, penalties, ticket designator)\n`match_confidence` -- 1.0 = fully decoded, 0.5-0.9 = partial\n`unparsed_segments` -- parts that could not be decoded","usage":"const agent = new FareBasisDecoder();\nawait agent.initialize();\nconst result = await agent.execute({ data: { fare_basis: 'Y26NR' } });\n// result.data.decoded.cabin_class => \"economy\"","status":"Implemented","purpose":"Decodes ATPCO-standard fare basis codes into human-readable components: cabin class, fare type, season, advance purchase, stay requirements, and penalties."},"0.4":{"id":"0.4","summary":"Maps single-letter booking class codes to cabin class, fare family, upgrade eligibility, and loyalty program earning rates","className":"ClassOfServiceMapper","input":"`booking_class` -- single letter A-Z\n`carrier` -- IATA 2-letter airline code (required -- meanings are carrier-specific)\n`include_loyalty?` -- include loyalty earning rates (default: false)","output":"`mapping` -- cabin class, brand name, fare family, upgrade eligibility/type, same-day change, seat selection, refundable, priority level, loyalty earning\n`match_confidence` -- 1.0 = carrier-specific, 0.7 = IATA default, 0 = unknown","usage":"const agent = new ClassOfServiceMapper();\nawait agent.initialize();\nconst result = await agent.execute({ data: { booking_class: 'J', carrier: 'UA', include_loyalty: true } });\n// result.data.mapping.cabin_class => \"business\"","status":"Implemented","purpose":"Maps single-letter booking class codes to cabin class, fare family, upgrade eligibility, and loyalty program earning rates. Booking classes are carrier-specific."},"0.5":{"id":"0.5","summary":"Resolves IATA aircraft equipment codes to structured equipment data","className":"EquipmentTypeResolver","input":"`operation` -- `'resolve' | 'getSeatingConfig' | 'isWidebody' | 'getSimilarTypes'`\n`code` -- IATA equipment code (e.g., `\"789\"`, `\"320\"`)\n`cabin?` -- cabin code (`'F' | 'C' | 'W' | 'Y'`) for `getSeatingConfig`","output":"`equipment?` -- full equipment info (IATA/ICAO codes, manufacturer, family, body type, seats, range)\n`seatCount?` -- seat count for specific cabin\n`isWidebody?` -- boolean\n`similarTypes?` -- IATA codes of similar aircraft","usage":"const agent = new EquipmentTypeResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { operation: 'resolve', code: '789' } });\n// result.data.equipment.manufacturer => \"Boeing\"","status":"Implemented","purpose":"Resolves IATA aircraft equipment codes to structured equipment data including manufacturer, body type, typical seating, range, and max capacity."},"0.6":{"id":"0.6","summary":"Resolves ISO 4217 currency codes and IATA tax/surcharge codes used in airline pricing and ticketing","className":"CurrencyTaxResolver","input":"`code` -- ISO currency code or IATA tax code\n`code_type?` -- `'currency' | 'tax' | 'auto'`\n`country?` -- ISO 2-letter country code to filter tax applicability","output":"`currency` -- currency details (code, name, symbol, minor units, countries, active status)\n`tax` -- tax details (code, name, description, category, country, applies-to, percentage flag)\n`match_confidence` -- 0-1 confidence score","usage":"const agent = new CurrencyTaxResolver();\nawait agent.initialize();\nconst result = await agent.execute({ data: { code: 'USD' } });\n// result.data.currency.name => \"US Dollar\"","status":"Implemented","purpose":"Resolves ISO 4217 currency codes and IATA tax/surcharge codes used in airline pricing."},"0.7":{"id":"0.7","summary":"APIS requirements, visa requirements, restriction levels. Static dataset -- must NOT be used as legal travel advice","className":"CountryRegulatoryResolver","input":"`operation` -- `'getAPISRequirements' | 'getVisaRequirement' | 'getRestrictionLevel'`\n`countryCode?` -- ISO 2-letter (for APIS and restriction)\n`nationalityCode?` -- ISO 2-letter (for visa)\n`destinationCode?` -- ISO 2-letter (for visa)","output":"`apis?` -- APIS requirements (required fields, advance submission hours)\n`visa?` -- visa requirement (type, max stay days)\n`restriction?` -- restriction level 1-4 with summary","usage":"const agent = new CountryRegulatoryResolver();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { operation: 'getVisaRequirement', nationalityCode: 'US', destinationCode: 'GB' }\n});\n// result.data.visa.requirement => \"visa_free\"","status":"Implemented","purpose":"APIS requirements, visa requirements, and travel restriction levels. Static dataset -- must NOT be used as legal travel advice."},"1.1":{"id":"1.1","summary":"Queries distribution adapters in parallel, normalizes, deduplicates, filters, and sorts flight availability offers","className":"AvailabilitySearch","input":"`origin` -- origin airport/city IATA code\n`destination` -- destination airport/city IATA code\n`departure_date` -- ISO 8601 date\n`return_date?` -- ISO 8601 date for round-trip\n`passengers` -- `PassengerCount[]`\n`cabin_class?` -- `'economy' | 'premium_economy' | 'business' | 'first'`\n`direct_only?` -- only direct flights\n`max_connections?` -- 0-5\n`currency?` -- ISO 4217\n`max_results?` -- 1-200\n`sort_by?` -- `'price' | 'duration' | 'departure' | 'arrival' | 'connections'`\n`sort_order?` -- `'asc' | 'desc'`\n`sources?` -- specific adapter names to query","output":"`offers` -- deduplicated, filtered, sorted `SearchOffer[]`\n`total_raw_offers` -- count before deduplication\n`source_status` -- per-adapter query status (success, count, error, response time)\n`truncated` -- whether results were capped","usage":"new AvailabilitySearch(adapters: DistributionAdapter[]) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Queries distribution adapters in parallel, normalizes, deduplicates, filters, and sorts flight availability offers."},"1.2":{"id":"1.2","summary":"Looks up flight schedules with SSIM operating day parsing, codeshare detection, and connection discovery","className":"ScheduleLookup","input":"`origin` -- airport IATA code\n`destination` -- airport IATA code\n`date` -- ISO 8601 date\n`carrier?` -- filter by carrier IATA code\n`flight_number?` -- specific flight (requires carrier)\n`include_codeshares?` -- default: true\n`include_connections?` -- discover connecting options (default: false)","output":"`flights` -- `ScheduledFlight[]` (carrier, flight number, times, duration, schedule, codeshare info)\n`connections` -- `ConnectionOption[]` (two-leg connections with timing)\n`operates_on_date` -- whether any flights operate on the requested date","status":"Implemented","purpose":"Flight schedule lookup with SSIM operating day parsing, codeshare detection, and connection discovery.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.3":{"id":"1.3","summary":"Validates connections against MCT rules, scores connection quality, and checks interline agreements","className":"ConnectionBuilder","input":"`arriving_segment` -- `FlightSegment` (from `@otaip/core`)\n`departing_segment` -- `FlightSegment`\n`connection_airport` -- IATA 3-letter code\n`has_checked_bags?` -- affects MCT\n`is_interline?` -- different carriers","output":"`validation` -- MCT check result (valid, available/required minutes, buffer, applied rule)\n`quality` -- connection quality score 0-1 with factor breakdown\n`interline` -- interline agreement check (if different carriers)\n`warnings` -- connection warnings","status":"Implemented","purpose":"Validates connections against MCT (Minimum Connection Time) rules, scores connection quality, and checks interline agreements.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.4":{"id":"1.4","summary":"Multi-source fare comparison with fare basis decoding, class mapping, branded fare family grouping, and passenger type pricing","className":"FareShopping","input":"`origin`, `destination`, `departure_date`, `passengers` -- same as availability search\n`cabin_class?`, `currency?`, `sources?` -- filters\n`decode_fare_basis?` -- decode fare basis codes (default: true)\n`group_by_fare_family?` -- group by basic/standard/flex/premium (default: true)","output":"`fares` -- `FareOffer[]` sorted by price, each with decoded fare basis, class info, fare family, passenger pricing\n`fare_families` -- grouped by family with cheapest/most expensive\n`total_fares` -- count\n`sources_queried` -- adapter names","usage":"new FareShopping(adapters: DistributionAdapter[]) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Multi-source fare comparison with fare basis decoding, class mapping, branded fare family grouping, and passenger type pricing."},"1.5":{"id":"1.5","summary":"Searches ancillary offers (seats, bags, meals) across distribution adapters","className":"AncillaryShoppingAgent","input":"`segments` -- flight segments (origin, destination, flight number, date, carrier)\n`passengers` -- passenger references with type (ADT/CHD/INF)\n`pnrRef?` -- PNR reference\n`requestedCategories?` -- filter by category (BAGGAGE, SEAT, MEAL, etc.)","output":"`ancillaries` -- `AncillaryOffer[]` with RFIC/RFISC codes, pricing, availability\n`notSupportedByAdapter` -- true if no adapter configured\n`currency` -- pricing currency","status":"Implemented","purpose":"Searches for available ancillaries (baggage, seats, meals, lounge, Wi-Fi, priority) via an injectable adapter.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.6":{"id":"1.6","summary":"Deduplicates and normalizes flight results from multiple adapter sources","className":"MultiSourceAggregatorAgent","input":"`results` -- `AdapterSearchResult[]` (adapter name, flights, errors, response time)\n`deduplicationStrategy` -- `'keep_cheapest' | 'keep_all' | 'keep_first'`\n`rankBy` -- `'price' | 'duration' | 'stops'`\n`maxResults?` -- limit output count","output":"`flights` -- `NormalizedFlight[]` with sources, lowest price, all prices across adapters\n`totalRaw` -- raw count before dedup\n`totalAfterDedup` -- final count\n`adapterSummary` -- per-adapter stats","status":"Implemented","purpose":"Aggregates search results from multiple adapters with deduplication, price comparison, and ranking.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.7":{"id":"1.7","summary":"Stub agent for hotel and car rental search via distribution adapters","className":"HotelCarSearchAgent","input":"`operation` -- `'searchHotels' | 'searchCars'`\n`hotel?` -- hotel search params (destination, dates, rooms, adults, star rating, max rate)\n`car?` -- car search params (pickup/dropoff location and times, category, driver age)","output":"`hotelResults?` -- hotel offers with rate, room type, cancellation policy\n`carResults?` -- car offers with category, supplier, daily/total rate, features","status":"Implemented (adapter-dependent)","purpose":"Car rental search (and, pending a deferred car-only migration, hotel) via pluggable adapters. Returns empty results when no adapters configured.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"1.8":{"id":"1.8","summary":"Natural language travel query understanding with injectable LLM provider; parses user queries into structured search parameters","className":"AITravelAdvisorAgent","input":"`query` -- natural language travel query\n`travelerContext?` -- preferences (cabin, budget, preferred airlines, passenger counts)","output":"`searchParameters` -- extracted origin, destination, dates, trip type, cabin, passengers, flexible dates\n`summary` -- natural language summary of interpreted query\n`intent` -- `'flight_search' | 'hotel_search' | 'destination_recommendation' | 'price_check' | 'trip_planning' | 'unknown'`","usage":"new AITravelAdvisorAgent({ llmProvider, maxTokens?, temperature? }) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Natural language travel query understanding with injectable LLM provider. Parses user queries into structured search parameters."},"1.9":{"id":"1.9","summary":"Stateless, deterministic scoring engine for flight offers with multi-dimensional scoring, hard filtering, and full audit trail (lives in @otaip/core)","className":"OfferEvaluatorAgent","input":"`offers` -- `EvaluatorOffer[]` with price, itinerary (segments, duration, connections)\n`constraints?` -- latest arrival, prefer direct, max connections, price ceiling, preferred/blacklisted carriers\n`profile?` -- `'BUSINESS_TIME_CRITICAL' | 'BUSINESS_PRICE_CONSTRAINED' | 'LEISURE' | 'CORPORATE_POLICY' | 'CUSTOM'`\n`weights?` -- custom scoring weights (time_buffer, price, connection_quality, journey_duration)","output":"Scored and ranked offers with structured explanation for LLM translation","status":"Implemented","purpose":"Deterministic offer evaluation engine. Scores and ranks flight offers based on traveler profile, constraints, and configurable scoring weights.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.1":{"id":"2.1","summary":"Parses ATPCO fare rules (categories 1-20) into human-readable structured format using curated tariff snapshot data","className":"FareRuleAgent","input":"`fare_basis` -- fare basis code\n`carrier` -- marketing carrier IATA code\n`origin` -- origin IATA code\n`destination` -- destination IATA code\n`travel_date?` -- ISO date for date-based rule filtering\n`categories?` -- specific ATPCO categories 1-50 (all if omitted)","output":"`rules` -- `FareRuleResult[]` with parsed categories, penalty summary, advance purchase, min/max stay, seasonality\n`total_rules` -- count of matched rules\n`valid_for_date` -- whether fare is valid for the specified travel date\n`in_blackout` -- whether travel date falls in a blackout period","status":"Implemented","purpose":"Parses ATPCO fare rules (categories 1-20) into human-readable structured format using curated tariff snapshot data.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.2":{"id":"2.2","summary":"NUC x ROE fare construction with mileage validation, HIP/BHC/CTM checks, surcharges, and IATA rounding. All financial math uses decimal.js","className":"FareConstruction","input":"`journey_type` -- `'OW' | 'RT' | 'CT'` (one-way, round-trip, circle-trip)\n`components` -- fare components (origin, destination, carrier, fare basis, NUC amount)\n`selling_currency` -- ISO 4217 currency\n`point_of_sale?` -- country for ROE selection","output":"`total_nuc` -- sum of components + surcharges\n`roe` -- ROE used for conversion\n`local_amount` -- final amount after IATA rounding\n`currency` -- selling currency\n`mileage_checks` -- per-component TPM/MPM validation\n`mileage_exceeded` -- whether total mileage exceeds MPM\n`mileage_surcharge` -- surcharge details if applicable\n`hip_check`, `bhc_check`, `ctm_check` -- mileage system checks\n`audit_trail` -- full calculation audit","status":"Implemented","purpose":"NUC x ROE fare construction with mileage validation, HIP/BHC/CTM checks, surcharges, and IATA rounding. All financial math uses `decimal.js`.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.3":{"id":"2.3","summary":"Per-segment tax computation with exemption engine, ~30 countries, ~50 tax codes, currency conversion. All financial math uses decimal.js","className":"TaxCalculation","input":"`segments` -- itinerary segments (origin/destination airports and countries, carrier, cabin class, base fare NUC)\n`passenger_type` -- `'adult' | 'child' | 'infant' | 'crew' | 'diplomatic'`\n`is_transit` -- whether transit/connection (\u003c 24h same ticket)\n`is_involuntary` -- whether involuntary reroute\n`total_base_fare_nuc` -- total base fare for percentage-based taxes\n`selling_currency` -- ISO 4217","output":"`taxes` -- `AppliedTax[]` (code, name, country, type, amounts, segment indices, interlineable, exempt status)\n`total_tax` -- total in selling currency\n`breakdown` -- by country, interlineable/non-interlineable totals\n`exemptions_applied` -- list of exemption reasons\n`segments_processed` -- count","status":"Implemented","purpose":"Per-segment tax computation with exemption engine, ~30 countries, ~50 tax codes, currency conversion. All financial math uses `decimal.js`.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.4":{"id":"2.4","summary":"Builds priced offers with TTL management and optional persistence adapter","className":"OfferBuilderAgent","input":"`operation` -- `'buildOffer' | 'getOffer' | 'validateOffer' | 'markUsed' | 'expireOffer' | 'cleanExpired'`\n`buildInput?` -- segments, fare, taxes, ancillaries, passenger count, pricing source, TTL\n`offerId?` -- for get/validate/mark/expire operations\n`currentTime?` -- ISO timestamp override","output":"`offer?` -- full offer record with pricing breakdown, TTL, status\n`valid?` -- offer validity result\n`reason?` -- validation failure reason\n`cleanedCount?` -- number of expired offers cleaned","usage":"new OfferBuilderAgent({ persistence?: PersistenceAdapter }) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Builds, caches, validates, and manages pricing offers with TTL expiration. Supports in-memory or pluggable persistence."},"2.5":{"id":"2.5","summary":"Validates flight offers against corporate travel policies (cabin, budget, advance purchase)","className":"CorporatePolicyValidationAgent","input":"`offer` -- offer details (cabin, fare amount, carrier, fare basis, advance booking days, segments)\n`policy` -- corporate policy (cabin rules, fare rules, booking rules, bypass codes)\n`bypassCode?` -- authorization code to bypass soft violations","output":"`result` -- `'APPROVED' | 'SOFT_VIOLATION' | 'HARD_VIOLATION'`\n`violations` -- `PolicyViolation[]` with rule, severity, detail\n`bypassApplied` -- whether bypass was used","status":"Implemented","purpose":"Validates flight offers against corporate travel policies: cabin class limits, fare ceilings, blocked carriers, advance booking requirements. Supports bypass codes.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"2.6":{"id":"2.6","summary":"Placeholder -- not yet implemented. Requires revenue management integration","className":"DynamicPricingAgent","status":"Coming Soon (stub)","purpose":"Revenue management integration for dynamic fare adjustments. Requires revenue management integration before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"2.7":{"id":"2.7","summary":"Placeholder -- not yet implemented. Requires revenue management integration","className":"RevenueManagementAgent","status":"Coming Soon (stub)","purpose":"Revenue management system integration. Requires revenue management domain input before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"3.1":{"id":"3.1","summary":"Routes booking requests to the correct distribution channel based on carrier config, codeshare rules, and NDC capability","className":"GdsNdcRouter","input":"`segments` -- routing segments (marketing/operating carrier, origin, destination, flight number)\n`preferred_channel?` -- `'GDS' | 'NDC' | 'DIRECT'`\n`preferred_gds?` -- `'AMADEUS' | 'SABRE' | 'TRAVELPORT'`\n`include_fallbacks` -- whether to include fallback channels","output":"`routings` -- per-segment channel routing (primary channel, GDS system, NDC version, fallbacks, booking format)\n`unified_channel` -- whether all segments can use the same channel\n`recommended_channel` -- best channel for entire itinerary\n`gds_format` / `ndc_format` -- format translation stubs","status":"Implemented","purpose":"Routes booking requests to the correct distribution channel (GDS, NDC, or direct API) based on carrier config, codeshare rules, and NDC capability. Per-segment routing with fallback support.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.2":{"id":"3.2","summary":"Constructs GDS-ready PNR commands from normalized booking data. Supports Amadeus, Sabre, and Travelport syntax","className":"PnrBuilder","input":"`gds` -- `'AMADEUS' | 'SABRE' | 'TRAVELPORT'`\n`passengers` -- name, type, DOB, passport, gender, nationality, FOID\n`segments` -- carrier, flight, class, date, origin, destination, status\n`contacts` -- phone, email, type\n`ticketing` -- time limit, type\n`received_from` -- agent identifier\n`ssrs?` -- SSR elements (WCHR, VGML, DOCS, FOID, CTCE, CTCM, INFT)\n`osis?` -- OSI elements\n`is_group?` / `group_name?` -- group PNR support","output":"`gds` -- target GDS\n`commands` -- ordered `PnrCommand[]` with GDS command strings and descriptions\n`passenger_count`, `segment_count`, `is_group`, `infant_count`","status":"Implemented","purpose":"Constructs GDS-ready PNR commands from normalized booking data. Supports Amadeus, Sabre, and Travelport syntax including names, segments, contacts, ticketing, SSR/OSI elements, and group bookings.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.3":{"id":"3.3","summary":"Pre-ticketing validation -- 13 checks to catch errors before ADMs","className":"PnrValidation","input":"`record_locator` -- 6-char PNR\n`passengers` -- passenger data (name, type, DOB, nationality, passport)\n`segments` -- segment data (carrier, flight, status, class, international flag, married group)\n`contact?` -- phone/email\n`ticketing?` -- time limit, arranged status\n`fare?` -- fare data with advance purchase deadline\n`validation_date?` -- ISO date override","output":"`record_locator` -- PNR\n`checks` -- `ValidationCheck[]` (13 checks, each with pass/fail, severity, message)\n`valid` -- overall pass/fail\n`error_count`, `warning_count`","status":"Implemented","purpose":"Pre-ticketing validation with 13 checks to catch errors before ADMs: segment status, passenger data, APIS, ticketing deadline, fare consistency, and more.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.4":{"id":"3.4","summary":"GDS queue monitoring and processing -- priority assignment, categorization, action routing, and queue command generation","className":"QueueManagement","input":"`entries` -- queue items (record locator, GDS, queue number, entry type, deadline, remark)\n`current_time?` -- ISO timestamp for priority calculation\n`gds?` -- GDS system for command generation\n`queue_number?` -- queue to generate read commands for","output":"`results` -- processed items with priority, status, recommended action, target agent\n`commands?` -- GDS queue commands\n`summary` -- counts by priority (urgent/high/normal/low)","status":"Implemented","purpose":"GDS queue monitoring and processing: priority assignment, categorization, action routing, and queue command generation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.5":{"id":"3.5","summary":"Universal HTTP client with circuit breaker, retry logic, timeout handling, rate limiting, and IATA error normalization","className":"ApiAbstraction","input":"`request` -- API request (provider ID, HTTP method, path, headers, body)\n`max_retries?` -- override retry count\n`timeout_ms?` -- override timeout\n`force?` -- skip circuit breaker check","output":"`response` -- API response (status, headers, body, duration, retries)\n`error` -- normalized error (category, original code, retryable flag)\n`circuit_breaker` -- circuit breaker status\n`rate_limit` -- rate limit status\n`success` -- boolean","usage":"new ApiAbstraction(handler?: RequestHandler) Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Universal HTTP client with circuit breaker, retry logic, timeout handling, rate limiting, and IATA error normalization for GDS/NDC/payment providers."},"3.6":{"id":"3.6","summary":"Travel order lifecycle management -- create, modify, cancel, retrieve, and list orders with status tracking and transition validation","className":"OrderManagement","input":"`operation` -- `'createOrder' | 'modifyOrder' | 'cancelOrder' | 'getOrder' | 'listOrders'`\n`createOrder?` -- passenger, items, currency, source\n`modifyOrder?` -- order ID, updated items/details, reason\n`cancelOrder?` -- order ID, reason\n`getOrder?` / `listOrders?` -- retrieval/filtering","output":"`order?` -- order record with status, items, history\n`orders?` -- list of orders\n`operation`, `success`, `errorCode?`, `errorMessage?`","status":"Implemented","purpose":"Travel order lifecycle management: create, modify, cancel, retrieve, and list orders with status tracking and transition validation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.7":{"id":"3.7","summary":"PCI-safe payment instruction builder and transaction recorder. Validates forms of payment, builds GDS FOP strings -- never handles raw card numbers","className":"PaymentProcessing","input":"`operation` -- `'validateFOP' | 'buildPaymentInstruction' | 'recordPayment' | 'getPaymentRecord' | 'buildGDSFOPString'`\nOperation-specific data: FOP details (CC_TOKEN, BSP_CASH, AIRLINE_CREDIT, VOUCHER, UATP), amounts, references","output":"`validation?` -- FOP validation result\n`instruction?` -- payment instruction with GDS string, PCI-safe flag\n`record?` -- payment transaction record\n`gdsString?` -- GDS FOP string","status":"Implemented","purpose":"PCI-safe payment instruction builder and transaction recorder. Validates forms of payment, builds GDS FOP strings, records transactions. Never handles raw card numbers.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"3.8":{"id":"3.8","summary":"Retrieves an existing PNR/booking by record locator across distribution adapters. Read-only -- no side effects","className":"PnrRetrieval","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"4.1":{"id":"4.1","summary":"ETR generation with conjunction ticket support, BSP reporting, and commission handling","className":"TicketIssuance","input":"`record_locator` -- 6-char PNR\n`issuing_carrier` -- 2-letter IATA code\n`passenger_name` -- LAST/FIRST format\n`segments` -- flight segments with carrier, flight number, class, fare basis, dates, baggage\n`base_fare`, `base_fare_currency` -- fare amount\n`equivalent_fare?`, `equivalent_fare_currency?` -- currency conversion\n`taxes` -- tax breakdown items\n`fare_calculation` -- fare calculation line\n`form_of_payment` -- CASH, CREDIT_CARD, INVOICE, MISCELLANEOUS\n`endorsements?`, `commission?`, `bsp_reporting?`, `original_issue?`","output":"`tickets` -- `TicketRecord[]` (13-digit number, coupons with status, fare/tax breakdown, FOP, commission, BSP fields)\n`total_coupons` -- total across all tickets\n`is_conjunction` -- whether conjunction tickets were generated","status":"Implemented","purpose":"ETR (Electronic Ticket Record) generation with conjunction ticket support (auto-split for >4 coupons), BSP reporting fields, and commission handling.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.2":{"id":"4.2","summary":"EMD-A (associated) and EMD-S (standalone) issuance, RFIC/RFISC handling, coupon lifecycle","className":"EmdManagement","input":"`emd_type` -- `'EMD-A' | 'EMD-S'`\n`record_locator`, `issuing_carrier`, `passenger_name`\n`services` -- array of services with RFIC code (A-G), RFISC, description, amount, associated ticket/coupon for EMD-A\n`related_ticket_number?` -- for EMD-A","output":"`emd` -- `EmdRecord` (13-digit EMD number, coupons, amounts)\n`coupon_count`","status":"Implemented","purpose":"EMD-A (associated) and EMD-S (standalone) issuance with RFIC/RFISC handling and coupon lifecycle management.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.3":{"id":"4.3","summary":"Ticket/EMD void processing -- coupon status check, carrier void window, BSP/ARC cut-off validation","className":"VoidAgent","input":"`document_number` -- 13-digit ticket/EMD number\n`issuing_carrier` -- 2-letter IATA code\n`coupons` -- coupon numbers and current statuses\n`issue_datetime` -- ISO datetime of issuance\n`current_datetime?` -- ISO datetime for void window check\n`settlement_system?` -- `'BSP' | 'ARC'`\n`bsp_cutoff_time?` -- HH:MM format","output":"`result` -- void permitted flag, rejection reason, message, void window hours, hours remaining, updated coupon statuses","status":"Implemented","purpose":"Ticket/EMD void processing with coupon status validation, carrier-specific void window enforcement, and BSP/ARC cut-off time checking.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.4":{"id":"4.4","summary":"Multi-channel itinerary rendering: Email (HTML+plain), SMS, WhatsApp. Carrier-neutral templates","className":"ItineraryDelivery","input":"`record_locator` -- booking reference\n`passengers` -- name, ticket number, frequent flyer\n`flights` -- flight details (number, origin, destination, times, cabin, seat, aircraft)\n`total_fare?`, `fare_currency?`\n`contact` -- email, phone, WhatsApp number\n`channels` -- `('EMAIL' | 'SMS' | 'WHATSAPP')[]`\n`agency_name?` -- for itinerary header","output":"`rendered` -- per-channel content (HTML/plain text, subject, SMS segment count)\n`channels_rendered` -- successfully rendered channels","status":"Implemented","purpose":"Multi-channel itinerary rendering: Email (HTML + plain text), SMS, and WhatsApp. Carrier-neutral templates.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"4.5":{"id":"4.5","summary":"APIS validation, passport validity, visa check (stub for Agent 0.7)","className":"DocumentVerification","input":"`passengers` -- ticket name, passport name, passport number/expiry/nationality, DOB, gender\n`segments` -- destination country and travel date\n`passport_validity_months?` -- minimum validity beyond travel date (default: 6)\n`validation_date?` -- ISO date override","output":"`results` -- per-passenger verification (pass/fail, individual checks with severity)\n`all_passed` -- overall pass/fail\n`blocking_failures`, `advisory_warnings` -- counts","status":"Implemented","purpose":"APIS validation, passport validity checking (configurable months threshold), and name matching between ticket and passport.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.1":{"id":"5.1","summary":"ATPCO Category 31 voluntary change assessment: change fees, fare difference, residual value, waiver codes","className":"ChangeManagement","input":"`original_ticket` -- ticket number, issuing carrier, passenger name, record locator, issue date, base fare, total tax, fare basis, refundable flag, booking date\n`requested_itinerary` -- new segments (carrier, flight, origin, destination, date, class, fare basis), new fare, new taxes\n`waiver_code?` -- airline-provided waiver code\n`current_datetime?` -- ISO datetime","output":"`assessment` -- action (`REISSUE | REBOOK | REJECT`), change fee, fare difference, additional collection, residual value, forfeited amount, tax difference, total due, free change flag, summary","status":"Implemented","purpose":"ATPCO Category 31 voluntary change assessment: change fees, fare difference, residual value, waiver codes, 24-hour free change window detection.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.2":{"id":"5.2","summary":"Ticket reissue with residual value, tax carryforward, GDS exchange command stubs, conjunction ticket handling","className":"ExchangeReissue","input":"`original_ticket_number`, `conjunction_originals?`, `original_issue_date`\n`issuing_carrier`, `passenger_name`, `record_locator`\n`original_base_fare`, `original_taxes` -- from original ticket\n`change_fee`, `residual_value`, `waiver_code?` -- from Agent 5.1\n`new_segments` -- new flight segments\n`new_fare`, `new_fare_currency`, `new_taxes`, `fare_calculation`\n`form_of_payment` -- for additional collection\n`gds?` -- GDS for command generation\n`same_origin_destination` -- for tax carryforward eligibility","output":"`reissue` -- new ticket record with full audit trail, exchange commands, tax carryforward details\n`additional_collection` -- amount due\n`credit_amount` -- amount refundable if downgrade","status":"Implemented","purpose":"Ticket reissue with residual value application, tax carryforward, conjunction ticket handling, GDS exchange command generation, and full audit trail.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.3":{"id":"5.3","summary":"Carrier-initiated schedule change handling: trigger assessment, airline protection logic, regulatory entitlements (EU261, US DOT)","className":"InvoluntaryRebook","input":"`original_pnr` -- record locator, passenger, affected segment, issuing carrier, countries, checked-in flag, EU carrier flag\n`schedule_change` -- change type, original/new times, time change minutes, routing changes, equipment changes\n`available_flights?` -- protection flight options with carrier/alliance/interline flags\n`thresholds?` -- override involuntary trigger thresholds\n`is_passenger_no_show?` -- no-show flag","output":"`result` -- involuntary flag, trigger type, protection options (ordered by priority), protection path taken, regulatory flags (EU261/US DOT applicability), original routing credit flag, summary","status":"Implemented","purpose":"Carrier-initiated schedule change handling: trigger assessment (time change, routing change, equipment downgrade, cancellation), airline protection logic (same carrier > alliance > interline), and regulatory entitlement flags (EU261, US DOT).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"5.4":{"id":"5.4","summary":"Placeholder -- not yet implemented. Requires domain input on disruption priority rules","className":"DisruptionResponseAgent","status":"Coming Soon (stub)","purpose":"Requires domain input on disruption priority rules and carrier-specific response procedures.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"5.5":{"id":"5.5","summary":"Placeholder -- not yet implemented. Requires domain input on change fee structures","className":"SelfServiceRebookingAgent","status":"Implemented","purpose":"Orchestrates Availability Search (1.1) and Change Management (5.1) to present priced rebooking alternatives (changeFee + fareDifference + taxDifference per option). Read-only -- does NOT execute the reissue; that is Exchange/Reissue (5.2). Involuntary reasons (schedule change / missed connection / cancellation) waive the change fee; voluntary changes honor ATPCO Cat 31 via 5.1.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"5.6":{"id":"5.6","summary":"Placeholder -- not yet implemented. Requires domain input on waitlist priority scoring","className":"WaitlistManagementAgent","status":"Implemented","purpose":"Stateful in-memory passenger waitlist queue with four operations: addEntry (priority computed at add time), clear (given N seats opened, remove top-N by priority), queryStatus (1-based position + estimated clearance probability), and expire (prune entries past their cutoff). State is in-memory only -- production deployments should pair it with a durable persistence layer.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"6.1":{"id":"6.1","summary":"ATPCO Category 33 refund processing: penalty application, commission recall, BSP/ARC reporting, conjunction ticket handling","className":"RefundProcessing","input":"`ticket_number`, `conjunction_tickets?`\n`issuing_carrier`, `passenger_name`, `record_locator`\n`base_fare`, `base_fare_currency`, `taxes`, `commission?`\n`refund_type` -- `'FULL' | 'PARTIAL' | 'TAX_ONLY'`\n`coupons_to_refund?` -- specific coupons (for partial)\n`total_coupons`, `waiver_code?`, `fare_basis`, `is_refundable`\n`settlement_system` -- `'BSP' | 'ARC'`","output":"`refund` -- penalty applied, base fare refund, tax refund, tax breakdown, commission recalled, net refund, BSP/ARC reporting fields, audit trail\n`net_refund_amount`, `commission_recalled`","status":"Implemented","purpose":"ATPCO Category 33 refund processing: penalty application, commission recall, BSP/ARC reporting fields, conjunction ticket handling. Supports full, partial, and tax-only refunds.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.2":{"id":"6.2","summary":"Pre-ticketing audit: 9 checks covering fare integrity, segment validity, and compliance to prevent Agency Debit Memos","className":"ADMPrevention","input":"`booking` -- record locator, passenger name, segments (with status, class, married group), base fare\n`fare_basis`, `booked_class`\n`commission_rate?`, `carrier_contracted_rate?`\n`endorsement?`, `tour_code?`\n`is_net_remit?`, `net_contracted_amount?`\n`ttl_deadline?`, `duplicate_check_pnrs?`, `current_datetime?`","output":"`result` -- all check results, overall pass/fail, blocking/warning counts","status":"Implemented","purpose":"Pre-ticketing audit with 9 checks: duplicate booking, fare/class mismatch, passive segment, married segment integrity, TTL expiry, commission rate, endorsement box, tour code format, net remit validation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.3":{"id":"6.3","summary":"Agency Debit Memo receipt, assessment, dispute, and Agency Credit Memo application workflows","className":"ADMACMProcessingAgent","input":"`operation` -- `'receiveADM' | 'receiveACM' | 'assessADM' | 'disputeADM' | 'acceptADM' | 'escalateADM' | 'applyACM' | 'getADM' | 'getPendingWithDeadlines'`\nOperation-specific fields: ticket number, airline, amount, reason code, dispute ground/evidence, ADM/ACM IDs","output":"`adm?` -- ADM record with status history\n`acm?` -- ACM record\n`assessment?` -- days remaining, window expired, recommended action\n`disputeResult?` -- dispute outcome\n`pendingDeadlines?` -- urgent ADMs approaching deadline","status":"Implemented","purpose":"Agency Debit Memo receipt, assessment, dispute, and Agency Credit Memo application workflows. Tracks dispute deadlines (15-day window), supports dispute grounds, and manages status transitions.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.4":{"id":"6.4","summary":"Multi-channel customer notification generation for flight disruptions, refunds, and operational changes. 8 notification types x 4 channels","className":"CustomerCommunication","input":"`operation` -- `'generateNotification' | 'generateBatch' | 'getTemplate'`\n`notificationType?` -- notification type\n`channel?` -- delivery channel\n`variables?` -- template variables (passenger name, flight info, amounts, etc.)\n`batchRequests?` -- for batch generation","output":"`notification?` -- generated notification with body, subject, SMS segments, used/missing variables\n`notifications?` -- batch results\n`template?` -- template info with required variables","status":"Implemented","purpose":"Multi-channel customer notification generation. 8 notification types (flight cancelled, delayed, gate change, rebooking confirmed, refund processed, schedule change, waitlist cleared, ADM received) x 4 channels (Email HTML, Email text, SMS, WhatsApp).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.5":{"id":"6.5","summary":"Complaint submission, EU261/US DOT compensation calculation, case management, and regulatory DOT record generation","className":"FeedbackComplaintAgent","input":"`operation` -- `'submitComplaint' | 'updateStatus' | 'getCase' | 'listCases' | 'calculateCompensation' | 'generateDOTRecord'`\nComplaint fields: type, passenger, booking reference, airline, flight, description\nCompensation fields: regulation, distance, delay, alternative offered, fare paid, cabin class\nCase management: case ID, status transitions","output":"`complaintCase?` -- full case record with status history, compensation result\n`cases?` -- filtered case list\n`compensation?` -- EU261/US DOT calculation (eligibility, base/final amount, reduction, notes)\n`dotRecord?` -- DOT regulatory record","status":"Implemented","purpose":"Complaint submission, EU261/US DOT compensation calculation, case management with status tracking, and DOT regulatory record generation.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"6.6":{"id":"6.6","summary":"Mileage accrual calculation, redemption eligibility, status benefits, and alliance status matching","className":"LoyaltyMileageAgent","input":"`operation` -- `'calculateAccrual' | 'checkRedemptionEligibility' | 'getStatusBenefits' | 'matchStatus'`\nAccrual: operating/crediting carrier, booking class, distance, loyalty status\nRedemption: distance, cabin, partner flag, current balance\nBenefits: airline, status tier\nMatch: source/target airline, source status","output":"`accrual?` -- base miles, bonus miles, total, earn rate, partner flag\n`redemption?` -- eligibility, miles required, remaining balance\n`statusBenefits?` -- benefit list by tier\n`statusMatch?` -- matched status at target airline","status":"Implemented","purpose":"Mileage accrual calculation, redemption eligibility checking, status benefits lookup, and cross-airline status matching.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.1":{"id":"7.1","summary":"Matches agency booking records against BSP HOT files, validates commission, identifies discrepancies, flags issues before remittance deadline","className":"BSPReconciliation","input":"`hot_records` -- BSP HOT file records (ticket number, passenger, origin/destination, airline, amounts, commission, transaction type, billing period)\n`agency_records` -- agency-side booking records for comparison","output":"Matched records, unmatched records, discrepancies with severity and type, commission validation results","status":"Implemented","purpose":"Matches agency booking records against BSP HOT files, validates commission rates, identifies discrepancies (missing records, duplicates, amount/commission/currency mismatches, unmatched ADM/ACM), and flags issues before remittance deadline.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.2":{"id":"7.2","summary":"Processes ARC IAR weekly billing, validates commission rates against airline contracts, flags pricing/commission errors","className":"ARCReconciliation","input":"`iar_records` -- ARC IAR records (document number, amounts, commission, transaction type, settlement week, ADM issue dates)\n`agency_records` -- agency-side records for comparison","output":"Matched/unmatched records, discrepancies with severity, ADM dispute window warnings","status":"Implemented","purpose":"Processes ARC IAR (Interactive Agent Reporting) weekly billing, validates commission rates against airline contracts, flags pricing/commission errors, and manages ADM/ACM disputes within the 15-day window.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.3":{"id":"7.3","summary":"Commission agreement management, rate validation, incentive calculation","className":"CommissionManagementAgent","input":"`operation` -- `'registerAgreement' | 'getRate' | 'validateCommission' | 'calculateIncentive' | 'listAgreements'`\nAgreement data: agent ID, airline, type, rate, basis (percent/flat per ticket/segment), fare basis patterns, validity dates, minimum tickets\nValidation: claimed rate vs expected rate\nIncentive: period, ticket count, total fare","output":"`agreement?` -- registered agreement\n`rate?` -- applicable commission rate\n`validation?` -- match/overstated/understated status with variance\n`incentive?` -- earned incentive amount, threshold met flag","status":"Implemented","purpose":"Commission agreement management: register agreements (override, incentive, backend, net fare, standard), look up rates by airline/fare basis, validate claimed commission, and calculate incentive earnings.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.4":{"id":"7.4","summary":"Placeholder -- not yet implemented. Requires domain input on interline prorate methodology","className":"InterlineSettlementAgent","status":"Coming Soon (stub)","purpose":"Requires domain input on interline prorate methodology and SIS (Simplified Interline Settlement) billing rules before implementation can proceed.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"7.5":{"id":"7.5","summary":"Aggregates transaction data into reports (revenue by route, margin analysis, unused tickets, etc.)","className":"FinancialReportingAgent","input":"`type` -- report type (9 report types available)\n`period` -- date range\n`filters?` -- airlines, agents, corporate IDs, currencies, minimum amount\n`groupBy?` -- grouping dimensions\n`records` -- financial records (ticket, refund, ADM, ACM, commission, fee)\n`currency?` -- reporting currency","output":"Report line items with revenue, cost, commission, net per group\nReport totals","status":"Implemented","purpose":"Generates financial reports: revenue by route/agent/corporate client, margin analysis, cost tracking, commission summary, spend by supplier, unused ticket value, and settlement summary.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"7.6":{"id":"7.6","summary":"Coupon lift recording, revenue recognition, uplift/deferred revenue reporting","className":"RevenueAccountingAgent","input":"`operation` -- `'recordLift' | 'recognizeRevenue' | 'getUpliftReport' | 'getDeferredRevenue' | 'recordVoid' | 'recordRefund'`\nLift data: ticket number, coupon number, flight details, fare amount\nReport parameters: date range","output":"Lift records, revenue recognition results, uplift reports (by route/cabin with average yield), deferred revenue reports","status":"Implemented","purpose":"Coupon lift tracking and revenue recognition: record lifted coupons, recognize revenue per flight, generate uplift reports (by route, by cabin), track deferred revenue from open coupons, and handle voids/refunds.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.1":{"id":"8.1","summary":"Stores/retrieves traveler preferences, documents, loyalty programs. Applies profiles to PNRs via SSR injection","className":"TravelerProfileAgent","input":"`operation` -- `'get' | 'create' | 'update' | 'apply_to_pnr' | 'search'`\nProfile data: name, DOB, nationality, passport, loyalty numbers, seat/meal preference, contact info, corporate/employee ID, department, cost center\nPNR application: GDS system, segments for APIS generation","output":"`profile?` -- traveler profile record\n`profiles?` -- search results\nPNR application: generated SSR/OSI commands","status":"Implemented","purpose":"Traveler preferences, identity documents, loyalty programs, and PNR prefill. CRUD operations plus apply-to-PNR for generating SSR/APIS commands.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.2":{"id":"8.2","summary":"Corporate travel policy enforcement, negotiated fares, booking validation","className":"CorporateAccountAgent","input":"`operation` -- `'get_account' | 'create_account' | 'update_account' | 'validate_booking' | 'get_policy' | 'list_accounts' | 'get_preferred_suppliers'`\nAccount data: company name, IATA number, travel policy, negotiated fares, contact info\nBooking validation: segments, cabin, fare amount, advance days","output":"`account?` -- corporate account record\n`accounts?` -- account list\n`validation?` -- policy violations (hard/soft) with details\n`policy?` -- travel policy rules\n`suppliers?` -- preferred suppliers","status":"Implemented","purpose":"Corporate travel policy management, negotiated fare lookup, and booking validation against policy rules (cabin limits, fare ceilings, advance booking, preferred/blacklisted airlines).","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.3":{"id":"8.3","summary":"PNR quality checks, ticketing deadline monitoring, duplicate/passive detection","className":"MidOfficeAgent","input":"`trigger` -- `'scheduled_sweep' | 'pnr_created' | 'ticket_deadline_approaching' | 'queue_pending' | 'manual_review_request'`\n`pnrs` -- PNR records with segments, deadlines, APIS/contact/FOP flags\n`current_datetime?` -- ISO timestamp","output":"Per-PNR issues with severity (urgent/high/medium/low) and issue codes\nSummary counts","status":"Implemented","purpose":"PNR quality checks and ticketing deadline monitoring. Scans PNRs for 10 issue types: TTL urgent/approaching, missing segment status, missing APIS, missing contact/FOP, duplicate PNR, passive segment, policy violation, married segment incomplete.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.4":{"id":"8.4","summary":"Aggregates transaction data into reports (booking volume, revenue, top routes, policy compliance)","className":"ReportingAgent","input":"`report_type` -- report type\n`date_from`, `date_to` -- date range\n`filters?` -- corporate ID, agent, airline, department, currency\n`transactions` -- transaction records (ticket, amounts, airline, dates, in-policy flag, used flag)","output":"Report rows grouped by the relevant dimension\nSummary totals","status":"Implemented","purpose":"Transaction aggregation and report generation across 9 report types: booking volume, revenue summary, top routes, agent productivity, policy compliance, spend by traveler/department/supplier, unused tickets.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"8.5":{"id":"8.5","summary":"Locates travelers in active itineraries during disruptions with destination risk assessment","className":"DutyCareAgent","input":"`operation` -- `'locate_travelers' | 'get_traveler_itinerary' | 'assess_destination_risk' | 'mark_accounted_for'`\nItineraries: traveler ID, segments with dates/times/status\nRisk: country code\nAccountability: traveler ID","output":"`locatedTravelers?` -- current location, status (IN_TRANSIT/AT_DESTINATION/DEPARTED/UNKNOWN), accounted-for flag\n`itinerary?` -- full traveler itinerary\n`risk?` -- country risk level (low/medium/high/critical) with notes","status":"Implemented","purpose":"Traveler location tracking, destination risk assessment, and accountability management for corporate duty-of-care obligations.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.1":{"id":"9.1","summary":"Coordinates multi-agent workflows as a single callable pipeline (search_to_price, book_to_ticket, full_booking, etc.)","className":"OrchestratorAgent","input":"`workflow` -- workflow name\n`input` -- workflow input data\n`options?` -- `stop_on_error?`, `timeout_ms?`","output":"`workflow` -- workflow name\n`status` -- `'completed' | 'failed' | 'partial'`\n`steps` -- per-step results (agent ID, status, duration, output/error)\n`total_duration_ms`\n`final_output?` -- last step output","usage":"Accepts injectable `StepExecutor` for testing without real agent imports. Then call initialize() and execute({ data }).","status":"Implemented","purpose":"Multi-agent workflow coordination. Defines named workflows (search-to-price, book-to-ticket, full booking, exchange flow, refund flow) as step sequences. Supports conditional steps, parallel execution, error handling (stop/skip/continue), and pipeline building."},"9.2":{"id":"9.2","summary":"RAG over travel knowledge base with BM25 relevance scoring and optional hybrid scoring via injectable EmbeddingProvider","className":"KnowledgeAgent","input":"`operation` -- `'query' | 'index_document' | 'list_topics' | 'get_document'`\nQuery: query string, topic filter, max results\nIndex: document ID, title, content, tags, topic","output":"`results?` -- ranked results with relevance score, excerpt, full content\n`document?` -- specific document\n`topics?` -- available topic list\n`query_time_ms?`","status":"Implemented","purpose":"RAG (Retrieval-Augmented Generation) over the travel knowledge base. Indexes documents by topic, supports BM25 + vector hybrid search with injectable embedding provider.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.3":{"id":"9.3","summary":"Tracks agent health, API latency, error rates, SLA compliance","className":"MonitoringAgent","input":"`operation` -- `'record_metric' | 'get_health' | 'list_alerts' | 'acknowledge_alert' | 'get_sla_report'`\nMetric: agent ID, metric type (latency_ms/error/success/timeout), value\nAlert: alert ID for acknowledgment","output":"`health?` -- agent health (status, p50/p95 latency, error rate, total calls)\n`alerts?` -- alert list with severity and fired timestamp\n`slaReport?` -- availability percent, p95 latency, error count","status":"Implemented","purpose":"Agent health monitoring: latency tracking (p50/p95), error rates, SLA compliance reporting. Records metrics, fires alerts on threshold violations, supports alert acknowledgment.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.4":{"id":"9.4","summary":"Audit trail, PII redaction, GDPR/PCI/IATA compliance","className":"AuditAgent","input":"`operation` -- `'log_event' | 'query_audit_log' | 'flag_compliance_issue' | 'get_compliance_report' | 'redact_pii'`\nEvent: type (agent_decision, data_access, booking_created, etc.), agent ID, user/session ID, payload\nCompliance: issue type, description, severity, affected records","output":"`entry?` -- audit log entry with hash, PII redaction flag, retention days\n`entries?` -- query results\n`issue?` -- flagged compliance issue\n`report?` -- compliance report (events with PII, redaction counts, open issues by severity)\n`redactedPayload?` -- PII-redacted data","status":"Implemented","purpose":"Audit trail logging with SHA-256 payload hashing, PII redaction (credit cards, passports, emails, phone numbers, DOB), GDPR/PCI/IATA compliance issue flagging, and compliance reporting.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.5":{"id":"9.5","summary":"Manages third-party agent extensions and capability discovery","className":"PluginManagerAgent","input":"`operation` -- `'register_plugin' | 'unregister_plugin' | 'list_plugins' | 'get_plugin' | 'discover_capabilities' | 'enable_plugin' | 'disable_plugin'`\nPlugin data: name, version, description, author, capabilities, agent IDs, metadata","output":"`plugin?` -- plugin record\n`plugins?` -- plugin list\n`capabilities?` -- capability-to-plugin mapping\n`message?` -- operation result message","status":"Implemented","purpose":"Third-party agent extension management: register/unregister plugins, enable/disable, capability discovery, and plugin metadata management.","usage":"Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas."},"9.6":{"id":"9.6","summary":"Aggregates agent execution metrics from the EventStore within a given time window. Identifies degraded agents","className":"PerformanceAuditAgent","status":"Implemented","purpose":"Aggregates agent execution metrics from the EventStore within a given time window and identifies degraded agents. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.7":{"id":"9.7","summary":"Analyses routing decisions and outcomes from the EventStore within a given time window","className":"RoutingAuditAgent","status":"Implemented","purpose":"Analyses routing decisions and outcomes from the EventStore within a given time window. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.8":{"id":"9.8","summary":"Accepts performance and routing audit reports and produces deterministic recommendations","className":"RecommendationAgent","status":"Implemented","purpose":"Accepts performance and routing audit reports and produces deterministic recommendations. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"9.9":{"id":"9.9","summary":"Queries EventStore events, computes metrics against configurable thresholds, and produces alerts","className":"AlertAgent","status":"Implemented","purpose":"Queries EventStore events, computes metrics against configurable thresholds, and produces alerts. Read-only -- no side effects.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"20.1":{"id":"20.1","summary":"Multi-source hotel availability search across GDS hotel segments, direct APIs, and channel manager feeds","className":"HotelSearchAggregatorAgent","input":"`destination` -- city name, airport code, or coordinates\n`checkIn` -- ISO date string (YYYY-MM-DD)\n`checkOut` -- ISO date string (YYYY-MM-DD)\n`rooms` -- number of rooms needed\n`adults` -- number of adult guests per room\n`children?` -- number of child guests per room\n`starRating?` -- minimum star rating filter\n`maxRatePerNight?` -- maximum nightly rate filter (decimal string)\n`currency?` -- ISO 4217 currency for rate filtering/display\n`rateType?` -- rate type filter\n`chainPreference?` -- chain code (e.g., `\"MC\"` for Marriott)\n`timeoutMs?` -- per-adapter timeout in milliseconds (default: 5000)\n`adapterIds?` -- specific adapter IDs to query (all if omitted)","output":"`properties` -- raw hotel results from all sources (NOT deduplicated)\n`totalResults` -- total result count across all adapters\n`adapterResults` -- per-adapter summary (ID, name, count, response time, timeout/error)\n`partialResults` -- true if some adapters timed out or errored\n`searchId` -- unique search ID for tracing","usage":"const agent = new HotelSearchAggregatorAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    destination: 'New York',\n    checkIn: '2026-06-01',\n    checkOut: '2026-06-03',\n    rooms: 1,\n    adults: 2,\n  },\n});\n// result.data.totalResults => 45\n// result.data.partialResults => false","status":"Implemented","purpose":"Multi-source hotel availability search across GDS hotel segments, direct APIs (Amadeus Hotel, Hotelbeds, Duffel Stays), and channel manager feeds. Returns raw, unmerged results from all connected sources. Supports injectable `HotelSourceAdapter` for plugging in custom sources."},"20.2":{"id":"20.2","summary":"Identifies duplicate properties from multi-source results and merges them into canonical records","className":"PropertyDeduplicationAgent","input":"`properties` -- raw hotel results from Agent 20.1\n`thresholds?` -- custom merge thresholds\n`autoMerge` -- score above which properties are auto-merged (default: 0.85)\n`review` -- score above which properties are flagged for review (default: 0.65)","output":"`canonical` -- canonical property records (one per physical property)\n`mergeLog` -- full audit trail of merge/separate decisions (property IDs, score, decision type, score breakdown)\n`stats` -- summary (input count, output count, auto-merged, review-flagged, separated)","usage":"const agent = new PropertyDeduplicationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: rawResults },\n});\n// result.data.stats.inputCount => 45\n// result.data.stats.outputCount => 28\n// result.data.stats.autoMerged => 12","status":"Implemented","purpose":"Takes raw multi-source hotel results from Agent 20.1 and identifies duplicate properties (40-60% of multi-source results are duplicates). Merges them into canonical property records using weighted scoring: Jaro-Winkler name similarity (0.3), normalized address Levenshtein (0.2), Haversine coordinate proximity (0.25), chain code match (0.15), and star rating match (0.1)."},"20.3":{"id":"20.3","summary":"Standardizes hotel content (room types, amenity names, descriptions, photos) into a consistent OTAIP taxonomy","className":"ContentNormalizationAgent","input":"`properties` -- canonical property records from Agent 20.2","output":"`properties` -- normalized property content records, each containing:\n`canonicalId` -- pass-through from 20.2\n`property` -- original canonical property\n`normalizedRoomTypes` -- room types mapped to OTAIP taxonomy\n`normalizedAmenities` -- amenities mapped to OTAIP taxonomy\n`scoredPhotos` -- scored and categorized photos (category, quality score, primary flag)\n`unmappedRoomTypes` -- raw room types that could not be normalized\n`unmappedAmenities` -- raw amenity strings that could not be normalized\n`stats` -- totals for properties, mapped/unmapped room types, mapped/unmapped amenities","usage":"const agent = new ContentNormalizationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: canonicalProperties },\n});\n// result.data.stats.totalRoomTypesMapped => 84\n// result.data.stats.totalAmenitiesUnmapped => 3","status":"Implemented","purpose":"Standardizes hotel content (room types, amenity names, photos) into a consistent OTAIP taxonomy for comparison and display. Maps raw room types from each source to the normalized taxonomy, merges amenities via union merge, and scores/categorizes photos."},"20.4":{"id":"20.4","summary":"Compares rates for the same canonical property across all sources, identifies best available rate, detects rate parity violations","className":"RateComparisonAgent","input":"`properties` -- canonical properties with source results containing rates\n`currency?` -- preferred currency for display (default: USD)\n`nights?` -- number of nights for the stay (default: 1)","output":"`comparisons` -- per-property rate comparison, each containing:\n`canonicalId` -- canonical property ID\n`propertyName` -- property name\n`rates` -- all rates sorted by total cost (lowest first), with full cost breakdown (room charges, mandatory fees, taxes, grand total)\n`bestByRateType` -- best rate per rate type\n`parity` -- rate parity analysis (at parity flag, lowest/highest source, spread percentage)\n`totalProperties` -- total properties compared\n`parityViolations` -- count of properties with rate parity violations","usage":"const agent = new RateComparisonAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: { properties: canonicalProperties, nights: 2 },\n});\n// result.data.comparisons[0].rates[0].totalCost.grandTotal => { amount: '289.00', currency: 'USD' }\n// result.data.parityViolations => 3","status":"Implemented","purpose":"Compares rates for the same canonical property across all sources, identifies best available rate per rate type, and detects rate parity violations (>2% spread between lowest and highest source). Includes ALL mandatory fees (resort fees, destination fees, taxes) in total cost breakdown."},"20.5":{"id":"20.5","summary":"Executes hotel bookings with three-layer confirmation code system (CRS, PMS, Channel)","className":"HotelBookingAgent","input":"`operation` -- `'book' | 'verify_rate' | 'get_booking'`\n`bookingRequest?` -- required for `book`/`verify_rate`:\n`canonicalPropertyId` -- from Agent 20.2\n`rateId` -- from Agent 20.4\n`source` -- hotel source to book through\n`checkIn` / `checkOut` -- ISO date strings\n`rooms` -- number of rooms\n`guest` -- guest details (name, email, phone, loyalty info)\n`paymentModel` -- payment model\n`specialRequests?` -- free text\n`bookingId?` -- required for `get_booking`","output":"`success` -- whether the operation succeeded\n`booking?` -- booking record (ID, three-layer confirmation codes, status, total charged, payment model, virtual card info, cancellation policy/deadline, guest, original request)\n`error?` -- error message if failed\n`rateChanged?` -- whether rate changed between search and booking\n`newRate?` -- new rate if changed","usage":"const agent = new HotelBookingAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'book',\n    bookingRequest: {\n      canonicalPropertyId: 'canon-001',\n      rateId: 'rate-001',\n      source: 'amadeus_hotel',\n      checkIn: '2026-06-01',\n      checkOut: '2026-06-03',\n      rooms: 1,\n      guest: { firstName: 'John', lastName: 'Smith', email: 'john@example.com' },\n      paymentModel: 'merchant',\n    },\n  },\n});\n// result.data.booking?.confirmation.crs => \"CRS-ABC123\"","status":"Implemented","purpose":"Executes hotel bookings through the optimal source. Manages the full booking flow from rate verification through confirmation, including three-layer confirmation codes (CRS, PMS, channel). Supports VCN (Virtual Card Number) payment with dual folio requirements."},"20.6":{"id":"20.6","summary":"Post-booking changes: free modifications, date changes (cancel/rebook), cancellations with penalty calculation, no-show processing","className":"HotelModificationAgent","input":"`operation` -- `'modify' | 'cancel' | 'check_penalty' | 'process_no_show'`\n`bookingId` -- existing booking ID\n`modifications?` -- free modifications (guest name, bed type, smoking preference, special requests, accessibility needs, guest count)\n`dateChange?` -- new check-in / check-out dates (triggers cancel/rebook)\n`bookedAt?` -- booking timestamp for California 24hr rule check\n`cancellationPolicy?` -- current cancellation policy\n`checkInDate?` -- for deadline calculations\n`nightlyRate?` -- nightly rate from booking record (penalty base)","output":"`success` -- whether the operation succeeded\n`classification` -- `'free_modification' | 'cancel_rebook_required' | 'not_modifiable'`\n`isFreeMod` -- whether this is a free modification\n`penalty?` -- penalty calculation (amount, type, deadline, free window flag, California rule flag)\n`rebookRequired` -- whether a rebook is needed (for date changes)\n`newBookingId?` -- updated confirmation codes (for successful modifications)\n`message` -- error or status message","usage":"const agent = new HotelModificationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'cancel',\n    bookingId: 'BK-001',\n    cancellationPolicy: { type: 'free_cancellation', deadline: '2026-05-30T00:00:00Z' },\n    checkInDate: '2026-06-01',\n    bookedAt: '2026-04-01T10:00:00Z',\n  },\n});\n// result.data.classification => \"free_modification\"\n// result.data.penalty?.isWithinFreeWindow => true","status":"Implemented","purpose":"Handles post-booking changes: free modifications (guest name, bed type, special requests), date changes (which require cancel/rebook -- NOT modifications), cancellations with penalty calculation, and no-show processing. Enforces California 24-hour cancellation rule where applicable."},"20.7":{"id":"20.7","summary":"Cross-checks CRS-to-PMS booking data to detect discrepancies before guest arrival","className":"ConfirmationVerificationAgent","input":"`operation` -- `'verify' | 'check_pms_sync' | 'batch_verify'`\n`bookingId` -- booking ID to verify\n`confirmation` -- three-layer confirmation codes from booking\n`crsData` -- CRS-side booking data (confirmation code, guest name, dates, room type, rates, status)\n`pmsData?` -- PMS-side booking data (may be missing if PMS hasn't synced yet)\n`guest` -- guest details for name verification\n`hoursUntilCheckin?` -- hours until check-in (for escalation urgency)\n`batchBookingIds?` -- additional booking IDs (for `batch_verify`)","output":"`verified` -- whether verification passed with no critical issues\n`discrepancies` -- all detected discrepancies (field, CRS value, PMS value, severity, message)\n`escalationRequired` -- whether human/agent escalation is needed\n`escalationReasons` -- why escalation is needed (pms_code_missing, rate_mismatch, date_mismatch, guest_name_mismatch, waitlist_status, tentative_status, room_type_mismatch, multiple_discrepancies)\n`verifiedAt` -- verification timestamp\n`message` -- summary message","usage":"const agent = new ConfirmationVerificationAgent();\nawait agent.initialize();\nconst result = await agent.execute({\n  data: {\n    operation: 'verify',\n    bookingId: 'BK-001',\n    confirmation: { crs: 'CRS-ABC', pms: 'PMS-123', channel: 'CH-456' },\n    crsData: {\n      confirmationCode: 'CRS-ABC',\n      guestName: 'SMITH/JOHN',\n      checkIn: '2026-06-01',\n      checkOut: '2026-06-03',\n      roomType: 'King Standard',\n      nightlyRate: { amount: '189.00', currency: 'USD' },\n      totalRate: { amount: '378.00', currency: 'USD' },\n      status: 'confirmed',\n    },\n    guest: { firstName: 'John', lastName: 'Smith' },\n  },\n});\n// result.data.verified => true\n// result.data.discrepancies.length => 0","status":"Implemented","purpose":"Cross-checks CRS and PMS booking data to detect discrepancies before guest arrival. Escalates missing PMS codes, waitlist/tentative status, rate/date mismatches. PMS sync can take 1-4 hours; delays beyond 24 hours trigger escalation."},"20.8":{"id":"20.8","summary":"Thin typed wrapper around Hotelbeds Activities search for route→fill orchestration and product-layer activity_search mapping.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."},"20.9":{"id":"20.9","summary":"Thin typed wrapper around Hotelbeds Transfers search for route→fill orchestration.","usage":"Call initialize(), then execute({ data }). See source_path for the typed input/output contract."}}}</script>
   <script>
-    const graph = JSON.parse(document.getElementById('graph-data').textContent);
+    const payload = JSON.parse(document.getElementById('graph-data').textContent);
+    const graph = payload.graph;
+    const agentDocs = payload.docs || {};
     const STAGE_NAMES = {"reference":"Reference","search":"Search","pricing":"Pricing","booking":"Booking","ticketing":"Ticketing","exchange":"Exchange","settlement":"Settlement","reconciliation":"Reconciliation","tmc":"TMC","platform":"Platform","core":"Core","lodging":"Lodging"};
     const nodesById = {};
     for (const n of graph.nodes) nodesById[n.id] = n;
@@ -2075,10 +2131,18 @@ <h2>Every agent, by stage.</h2>
     const panelContent = document.getElementById('panel-content');
     let panelOpen = false;
 
+    function bulletsHtml(block) {
+      if (!block) return '';
+      const lines = String(block).split('\n').map(function (l) { return l.trim(); }).filter(Boolean);
+      if (!lines.length) return '';
+      return '<ul class="p-io">' + lines.map(function (l) { return '<li>' + escape(l) + '</li>'; }).join('') + '</ul>';
+    }
+
     function openPanel(id) {
       const n = nodesById[id];
       if (!n) return;
       selectedAgent = id;
+      const doc = agentDocs[id] || {};
       const wfs = workflowsFor(id);
       const wfUp = [], wfDown = [], depOut = [], depIn = [];
       for (const e of graph.edges) {
@@ -2094,27 +2158,44 @@ <h2>Every agent, by stage.</h2>
       html += '<div class="p-id">' + escape(n.id) + '</div>';
       html += '<h3>' + escape(n.name) + '</h3>';
       html += '<div class="badge' + (n.contract_status === 'stub' ? ' stub' : '') + '"><i></i>' + escape(n.contract_status) + '</div>';
+
+      const summary = doc.summary || '';
+      const purpose = doc.purpose && doc.purpose !== summary ? doc.purpose : '';
+      if (summary) html += '<p class="p-summary">' + escape(summary) + '</p>';
+      if (purpose) html += '<p class="p-purpose">' + escape(purpose) + '</p>';
+
       html += '<dl>';
       html += '<dt>Stage</dt><dd>' + escape(STAGE_NAMES[n.stage] || n.stage) + '</dd>';
       html += '<dt>Version</dt><dd>' + escape(n.version) + '</dd>';
+      if (doc.className) html += '<dt>Class</dt><dd><code>' + escape(doc.className) + '</code></dd>';
       html += '<dt>Contract</dt><dd>' + (n.has_contract ? 'Yes' : 'No') + '</dd>';
+      if (doc.status) html += '<dt>Status</dt><dd>' + escape(doc.status) + '</dd>';
       html += '<dt>Source</dt><dd><code>' + escape(n.source_path) + '</code></dd>';
       html += '</dl>';
 
-      html += '<div class="p-label">Workflows</div>';
+      if (doc.input) {
+        html += '<div class="p-label">Input</div>';
+        html += bulletsHtml(doc.input);
+      }
+      if (doc.output) {
+        html += '<div class="p-label">Output</div>';
+        html += bulletsHtml(doc.output);
+      }
+      if (doc.usage) {
+        html += '<div class="p-label">How to use</div>';
+        html += '<pre class="p-usage">' + escape(doc.usage) + '</pre>';
+      }
+
       if (wfs.length) {
-        html += '<div class="mini-pills">';
+        html += '<div class="p-label">Workflows</div><div class="mini-pills">';
         for (const w of wfs) {
           html += '<button type="button" class="mini-pill" data-wf-jump="' + escape(w) + '">' + escape(w) + '</button>';
         }
         html += '</div>';
-      } else {
-        html += '<p class="p-dim">Not part of a built-in workflow.</p>';
       }
 
-      html += '<div class="p-label">Pipeline connections</div>';
       if (wfUp.length || wfDown.length) {
-        html += '<ul class="conn-list">';
+        html += '<div class="p-label">Pipeline connections</div><ul class="conn-list">';
         for (const e of wfUp) {
           html += '<li><span class="dir">&larr;</span> <button type="button" data-jump="' + escape(e.source) + '">' + escape(e.source) + '</button> <span class="c-kind">' + escape(e.label) + '</span></li>';
         }
@@ -2122,28 +2203,22 @@ <h2>Every agent, by stage.</h2>
           html += '<li><span class="dir">&rarr;</span> <button type="button" data-jump="' + escape(e.target) + '">' + escape(e.target) + '</button> <span class="c-kind">' + escape(e.label) + '</span></li>';
         }
         html += '</ul>';
-      } else {
-        html += '<p class="p-dim">No pipeline edges.</p>';
       }
 
-      html += '<div class="p-label">Depends on</div>';
       if (depOut.length) {
+        html += '<div class="p-label">Depends on</div>';
         for (const e of depOut) {
           const t = nodesById[e.target];
           html += '<div class="dep-row"><button type="button" class="dep-pill" data-jump="' + escape(e.target) + '"><span class="dep-arrow">&#8674;</span> ' + escape(e.target) + (t ? ' · ' + escape(t.name) : '') + '</button><span class="dep-label">' + escape(e.label) + '</span></div>';
         }
-      } else {
-        html += '<p class="p-dim">No package dependencies.</p>';
       }
 
-      html += '<div class="p-label">Required by</div>';
       if (depIn.length) {
+        html += '<div class="p-label">Required by</div>';
         for (const e of depIn) {
           const s = nodesById[e.source];
           html += '<div class="dep-row"><button type="button" class="dep-pill" data-jump="' + escape(e.source) + '"><span class="dep-arrow">&#8672;</span> ' + escape(e.source) + (s ? ' · ' + escape(s.name) : '') + '</button><span class="dep-label">' + escape(e.label) + '</span></div>';
         }
-      } else {
-        html += '<p class="p-dim">Nothing depends on this package.</p>';
       }
 
       panelContent.innerHTML = html;
diff --git a/scripts/agent-docs.ts b/scripts/agent-docs.ts
new file mode 100644
index 0000000..e5fa2e1
--- /dev/null
+++ b/scripts/agent-docs.ts
@@ -0,0 +1,231 @@
+/**
+ * Load human-authored agent descriptions from docs/ for the agent map.
+ * Sources: docs/agents.md (one-liners) + docs/agents/stage-*.md (purpose,
+ * input, output, example). Do not invent domain text — only what is written.
+ */
+
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+export interface AgentDoc {
+  readonly id: string;
+  readonly className?: string;
+  /** One-line from docs/agents.md (or stage purpose fallback). */
+  readonly summary: string;
+  /** Longer purpose prose from stage docs. */
+  readonly purpose?: string;
+  readonly input?: string;
+  readonly output?: string;
+  /** How to use — example code or usage prose from stage docs. */
+  readonly usage?: string;
+  readonly status?: string;
+}
+
+function decodeHtmlEntities(s: string): string {
+  return s
+    .replace(/&#10003;/g, '✓')
+    .replace(/&amp;/g, '&')
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&quot;/g, '"')
+    .replace(/&#39;/g, "'");
+}
+
+/** Parse catalog table rows from docs/agents.md → id → summary. */
+export function parseAgentsCatalog(markdown: string): Map<string, { className: string; name: string; summary: string }> {
+  const out = new Map<string, { className: string; name: string; summary: string }>();
+  for (const line of markdown.split('\n')) {
+    const m = line.match(
+      /^\|\s*(\d+\.\d+)\s*\|\s*`?([^`|]*)`?\s*\|\s*([^|]+)\|\s*([^|]+)\|/,
+    );
+    if (!m) continue;
+    const id = m[1]!;
+    const className = m[2]!.trim();
+    const name = m[3]!.trim();
+    const summary = decodeHtmlEntities(m[4]!.trim());
+    if (!summary) continue;
+    out.set(id, { className, name, summary });
+  }
+  return out;
+}
+
+interface StageBlock {
+  id: string;
+  className?: string;
+  status?: string;
+  purpose?: string;
+  input?: string;
+  output?: string;
+  usage?: string;
+}
+
+/** Split stage markdown into per-agent blocks keyed by **ID:** `x.y`. */
+export function parseStageDoc(markdown: string): StageBlock[] {
+  const blocks: StageBlock[] = [];
+  // Split on ### Agent headings
+  const parts = markdown.split(/^### Agent /m);
+  for (const part of parts.slice(1)) {
+    const idMatch = part.match(/\*\*ID:\*\*\s*`(\d+\.\d+)`/);
+    if (!idMatch) continue;
+    const id = idMatch[1]!;
+    const classMatch = part.match(/\*\*Class:\*\*\s*`([^`]+)`/);
+    const statusMatch = part.match(/\*\*Status:\*\*\s*([^\n]+)/);
+
+    // Purpose: prose after Status line until **Input or **Output or **Example or --- or next heading
+    const afterStatus = part.split(/\*\*Status:\*\*[^\n]*\n+/)[1] ?? '';
+    const purposeMatch = afterStatus.match(
+      /^([\s\S]*?)(?=\n\*\*Input|\n\*\*Output|\n\*\*Example|\n---|\n### |\n## |$)/,
+    );
+    let purpose = purposeMatch?.[1]?.trim() ?? '';
+    // Drop leading blank / non-prose
+    purpose = purpose
+      .split('\n')
+      .filter((l) => !l.startsWith('**') && !l.startsWith('```'))
+      .join('\n')
+      .trim();
+
+    const sectionStop = String.raw`\n\*\*(?:Input|Output|Example|Constructor)|\n---|\n### |\n## |$`;
+    const inputMatch = part.match(
+      new RegExp(String.raw`\*\*Input[^*]*\*\*:?\s*\n([\s\S]*?)(?=${sectionStop})`),
+    );
+    const outputMatch = part.match(
+      new RegExp(String.raw`\*\*Output[^*]*\*\*:?\s*\n([\s\S]*?)(?=${sectionStop})`),
+    );
+    const exampleMatch = part.match(
+      /\*\*Example:\*\*\s*\n```(?:typescript|ts|js)?\n([\s\S]*?)```/,
+    );
+    const constructorMatch = part.match(/\*\*Constructor:\*\*\s*([^\n]+)/);
+
+    const input = inputMatch?.[1]?.trim();
+    const output = outputMatch?.[1]?.trim();
+    let usage: string | undefined;
+    if (exampleMatch?.[1]) {
+      usage = exampleMatch[1].trim();
+    } else if (constructorMatch?.[1]) {
+      const ctor = constructorMatch[1].trim().replace(/^`|`$/g, '');
+      usage = `${ctor} Then call initialize() and execute({ data }).`;
+    }
+
+    blocks.push({
+      id,
+      ...(classMatch ? { className: classMatch[1]!.trim() } : {}),
+      ...(statusMatch ? { status: statusMatch[1]!.trim() } : {}),
+      ...(purpose ? { purpose } : {}),
+      ...(input ? { input } : {}),
+      ...(output ? { output } : {}),
+      ...(usage ? { usage } : {}),
+    });
+  }
+  return blocks;
+}
+
+function formatBulletBlock(raw: string): string {
+  return raw
+    .split('\n')
+    .map((l) => l.replace(/^\s*-\s*/, '').trim())
+    .filter(Boolean)
+    .join('\n');
+}
+
+/** First prose paragraph from a source file's leading block comment. */
+export function summaryFromSourceJsdoc(source: string): string | undefined {
+  const m = source.match(/^\/\*\*([\s\S]*?)\*\//);
+  if (!m) return undefined;
+  const lines = m[1]!
+    .split('\n')
+    .map((l) => l.replace(/^\s*\*\s?/, '').trim())
+    .filter((l) => l && !/^Agent\s+\d+\.\d+/i.test(l));
+  const para = lines.join(' ').replace(/\s+/g, ' ').trim();
+  return para || undefined;
+}
+
+export interface AgentSourceRef {
+  readonly id: string;
+  readonly source_path: string;
+}
+
+/**
+ * Build id → AgentDoc from repo docs. Optionally fill gaps from agent
+ * source-file JSDoc (still authored text — not invented).
+ */
+export function loadAgentDocs(
+  repoRoot: string,
+  sources: readonly AgentSourceRef[] = [],
+): Record<string, AgentDoc> {
+  const catalogPath = join(repoRoot, 'docs/agents.md');
+  const agentsDir = join(repoRoot, 'docs/agents');
+  const catalog = existsSync(catalogPath)
+    ? parseAgentsCatalog(readFileSync(catalogPath, 'utf8'))
+    : new Map();
+
+  const stageBlocks = new Map<string, StageBlock>();
+  if (existsSync(agentsDir)) {
+    for (const file of readdirSync(agentsDir)) {
+      if (!/^stage-.*\.md$/.test(file)) continue;
+      const blocks = parseStageDoc(readFileSync(join(agentsDir, file), 'utf8'));
+      for (const b of blocks) stageBlocks.set(b.id, b);
+    }
+  }
+
+  const ids = new Set([
+    ...catalog.keys(),
+    ...stageBlocks.keys(),
+    ...sources.map((s) => s.id),
+  ]);
+  const out: Record<string, AgentDoc> = {};
+  const sourceById = new Map(sources.map((s) => [s.id, s.source_path]));
+
+  for (const id of ids) {
+    const cat = catalog.get(id);
+    const stage = stageBlocks.get(id);
+    let summary = cat?.summary || stage?.purpose || '';
+
+    if (!summary) {
+      const rel = sourceById.get(id);
+      if (rel) {
+        const abs = join(repoRoot, rel);
+        if (existsSync(abs)) {
+          summary = summaryFromSourceJsdoc(readFileSync(abs, 'utf8')) ?? '';
+        }
+      }
+    }
+    if (!summary && !stage?.purpose && !stage?.usage && !stage?.input) continue;
+
+    const doc: AgentDoc = {
+      id,
+      summary: summary || stage?.purpose || '',
+      ...(cat?.className || stage?.className
+        ? { className: (cat?.className || stage?.className)! }
+        : {}),
+      ...(stage?.input ? { input: formatBulletBlock(stage.input) } : {}),
+      ...(stage?.output ? { output: formatBulletBlock(stage.output) } : {}),
+      ...(stage?.usage ? { usage: stage.usage } : {}),
+      ...(stage?.status ? { status: stage.status } : {}),
+    };
+
+    if (stage?.purpose && stage.purpose.length > (doc.summary?.length ?? 0) + 20) {
+      out[id] = { ...doc, purpose: stage.purpose };
+    } else if (stage?.purpose && stage.purpose !== doc.summary) {
+      out[id] = { ...doc, purpose: stage.purpose };
+    } else {
+      out[id] = doc;
+    }
+
+    // Default how-to when stage docs have I/O but no example/constructor
+    if (!out[id]!.usage && (out[id]!.input || out[id]!.output)) {
+      out[id] = {
+        ...out[id]!,
+        usage:
+          'Call initialize(), then execute({ data }) with the input fields below. See the agent source and stage doc for typed schemas.',
+      };
+    } else if (!out[id]!.usage && out[id]!.summary) {
+      out[id] = {
+        ...out[id]!,
+        usage:
+          'Call initialize(), then execute({ data }). See source_path for the typed input/output contract.',
+      };
+    }
+  }
+
+  return out;
+}
diff --git a/scripts/generate-agent-map-html.ts b/scripts/generate-agent-map-html.ts
index bb4456b..45ba300 100644
--- a/scripts/generate-agent-map-html.ts
+++ b/scripts/generate-agent-map-html.ts
@@ -15,6 +15,7 @@
 import { existsSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadAgentDocs } from './agent-docs.js';
 import type { AgentGraph, AgentGraphNode } from './agent-graph.js';
 
 const GRAPH_PATH = 'agents.graph.json';
@@ -250,7 +251,11 @@ ${rows}
     })
     .join('\n');
 
-  const payload = JSON.stringify(graph);
+  const docs = loadAgentDocs(
+    repoRoot(),
+    graph.nodes.map((n) => ({ id: n.id, source_path: n.source_path })),
+  );
+  const payload = JSON.stringify({ graph, docs });
   const stageNamesJson = JSON.stringify(STAGE_DISPLAY);
 
   return `<!DOCTYPE html>
@@ -1062,6 +1067,60 @@ ${rows}
     }
     .mini-pill:hover { background: rgba(6, 189, 180, 0.14); border-color: var(--teal); }
     .p-dim { margin: 0; font-size: 0.8rem; font-weight: 300; color: var(--ink-4); }
+    .p-summary {
+      margin: 0.35rem 0 0;
+      font-size: 0.92rem;
+      font-weight: 400;
+      line-height: 1.45;
+      color: var(--ink-2);
+      letter-spacing: -0.01em;
+    }
+    .p-purpose {
+      margin: 0.55rem 0 0;
+      font-size: 0.84rem;
+      font-weight: 300;
+      line-height: 1.5;
+      color: var(--ink-3);
+    }
+    .p-io {
+      margin: 0;
+      padding: 0;
+      list-style: none;
+      display: flex;
+      flex-direction: column;
+      gap: 0.35rem;
+      font-size: 0.78rem;
+      line-height: 1.4;
+      color: var(--ink-2);
+    }
+    .p-io li {
+      padding-left: 0.85rem;
+      position: relative;
+    }
+    .p-io li::before {
+      content: "";
+      position: absolute;
+      left: 0;
+      top: 0.55em;
+      width: 5px;
+      height: 5px;
+      border-radius: 50%;
+      background: var(--teal);
+      opacity: 0.7;
+    }
+    .p-usage {
+      margin: 0;
+      padding: 0.75rem 0.85rem;
+      border-radius: 12px;
+      background: rgba(35, 39, 61, 0.04);
+      border: 1px solid var(--hairline);
+      font-family: var(--mono);
+      font-size: 0.68rem;
+      line-height: 1.45;
+      color: var(--navy);
+      white-space: pre-wrap;
+      overflow-x: auto;
+    }
     .conn-list { margin: 0; padding: 0; list-style: none; display: flex; flex-direction: column; gap: 0.4rem; }
     .conn-list li { font-family: var(--mono); font-size: 0.74rem; color: var(--ink-3); }
     .conn-list .dir { color: var(--teal); }
@@ -1213,7 +1272,9 @@ ${tilesHtml}
 
   <script id="graph-data" type="application/json">${payload.replace(/</g, '\\u003c')}</script>
   <script>
-    const graph = JSON.parse(document.getElementById('graph-data').textContent);
+    const payload = JSON.parse(document.getElementById('graph-data').textContent);
+    const graph = payload.graph;
+    const agentDocs = payload.docs || {};
     const STAGE_NAMES = ${stageNamesJson};
     const nodesById = {};
     for (const n of graph.nodes) nodesById[n.id] = n;
@@ -1443,10 +1504,18 @@ ${tilesHtml}
     const panelContent = document.getElementById('panel-content');
     let panelOpen = false;
 
+    function bulletsHtml(block) {
+      if (!block) return '';
+      const lines = String(block).split('\\n').map(function (l) { return l.trim(); }).filter(Boolean);
+      if (!lines.length) return '';
+      return '<ul class="p-io">' + lines.map(function (l) { return '<li>' + escape(l) + '</li>'; }).join('') + '</ul>';
+    }
+
     function openPanel(id) {
       const n = nodesById[id];
       if (!n) return;
       selectedAgent = id;
+      const doc = agentDocs[id] || {};
       const wfs = workflowsFor(id);
       const wfUp = [], wfDown = [], depOut = [], depIn = [];
       for (const e of graph.edges) {
@@ -1462,27 +1531,44 @@ ${tilesHtml}
       html += '<div class="p-id">' + escape(n.id) + '</div>';
       html += '<h3>' + escape(n.name) + '</h3>';
       html += '<div class="badge' + (n.contract_status === 'stub' ? ' stub' : '') + '"><i></i>' + escape(n.contract_status) + '</div>';
+
+      const summary = doc.summary || '';
+      const purpose = doc.purpose && doc.purpose !== summary ? doc.purpose : '';
+      if (summary) html += '<p class="p-summary">' + escape(summary) + '</p>';
+      if (purpose) html += '<p class="p-purpose">' + escape(purpose) + '</p>';
+
       html += '<dl>';
       html += '<dt>Stage</dt><dd>' + escape(STAGE_NAMES[n.stage] || n.stage) + '</dd>';
       html += '<dt>Version</dt><dd>' + escape(n.version) + '</dd>';
+      if (doc.className) html += '<dt>Class</dt><dd><code>' + escape(doc.className) + '</code></dd>';
       html += '<dt>Contract</dt><dd>' + (n.has_contract ? 'Yes' : 'No') + '</dd>';
+      if (doc.status) html += '<dt>Status</dt><dd>' + escape(doc.status) + '</dd>';
       html += '<dt>Source</dt><dd><code>' + escape(n.source_path) + '</code></dd>';
       html += '</dl>';
 
-      html += '<div class="p-label">Workflows</div>';
+      if (doc.input) {
+        html += '<div class="p-label">Input</div>';
+        html += bulletsHtml(doc.input);
+      }
+      if (doc.output) {
+        html += '<div class="p-label">Output</div>';
+        html += bulletsHtml(doc.output);
+      }
+      if (doc.usage) {
+        html += '<div class="p-label">How to use</div>';
+        html += '<pre class="p-usage">' + escape(doc.usage) + '</pre>';
+      }
+
       if (wfs.length) {
-        html += '<div class="mini-pills">';
+        html += '<div class="p-label">Workflows</div><div class="mini-pills">';
         for (const w of wfs) {
           html += '<button type="button" class="mini-pill" data-wf-jump="' + escape(w) + '">' + escape(w) + '</button>';
         }
         html += '</div>';
-      } else {
-        html += '<p class="p-dim">Not part of a built-in workflow.</p>';
       }
 
-      html += '<div class="p-label">Pipeline connections</div>';
       if (wfUp.length || wfDown.length) {
-        html += '<ul class="conn-list">';
+        html += '<div class="p-label">Pipeline connections</div><ul class="conn-list">';
         for (const e of wfUp) {
           html += '<li><span class="dir">&larr;</span> <button type="button" data-jump="' + escape(e.source) + '">' + escape(e.source) + '</button> <span class="c-kind">' + escape(e.label) + '</span></li>';
         }
@@ -1490,28 +1576,22 @@ ${tilesHtml}
           html += '<li><span class="dir">&rarr;</span> <button type="button" data-jump="' + escape(e.target) + '">' + escape(e.target) + '</button> <span class="c-kind">' + escape(e.label) + '</span></li>';
         }
         html += '</ul>';
-      } else {
-        html += '<p class="p-dim">No pipeline edges.</p>';
       }
 
-      html += '<div class="p-label">Depends on</div>';
       if (depOut.length) {
+        html += '<div class="p-label">Depends on</div>';
         for (const e of depOut) {
           const t = nodesById[e.target];
           html += '<div class="dep-row"><button type="button" class="dep-pill" data-jump="' + escape(e.target) + '"><span class="dep-arrow">&#8674;</span> ' + escape(e.target) + (t ? ' · ' + escape(t.name) : '') + '</button><span class="dep-label">' + escape(e.label) + '</span></div>';
         }
-      } else {
-        html += '<p class="p-dim">No package dependencies.</p>';
       }
 
-      html += '<div class="p-label">Required by</div>';
       if (depIn.length) {
+        html += '<div class="p-label">Required by</div>';
         for (const e of depIn) {
           const s = nodesById[e.source];
           html += '<div class="dep-row"><button type="button" class="dep-pill" data-jump="' + escape(e.source) + '"><span class="dep-arrow">&#8672;</span> ' + escape(e.source) + (s ? ' · ' + escape(s.name) : '') + '</button><span class="dep-label">' + escape(e.label) + '</span></div>';
         }
-      } else {
-        html += '<p class="p-dim">Nothing depends on this package.</p>';
       }
 
       panelContent.innerHTML = html;