📖 User Manual · SkyWeave Alpha

Complete demo platform guide — 60-day plan · Mode B
🇪🇸 Español

Introduction

SkyWeave Alpha is a continuous data-integration substrate for airline decision-making. It replaces the 60-analyst pyramid + the consulting firms (McKinsey, BCG, Bain, Simon-Kucher, Alton, Oliver Wyman, Seabury, ICF) that today charge $5–15M per airline per year.

This demo is the functional implementation of Luis's 60-day plan (Rev 5) in Mode B (synthetic data, no signed DP-1 carrier). It demonstrates the wedge end-to-end: provenance-ingested data → coordinator pipeline → audit chain → 6 surfaces → What-If → RAG scaffold → named connectors → published schemas.

The project's destination: 30 AI agents operating an airline by December 2026, a 10-person airline by 2030. This demo shows the foundation that destination is built on.

The top menu has two zones:

Each surface has its own dashboard with KPI cards at the top and expandable cards below. Click any card to see the full Decision detail: PAL+ decomposition, recommended levers, audit info, raw JSON artifact.

The 6 production surfaces

📊

S1 · Daily Margin Watch

CadenceDaily · publishes 06:00 local BuyerCFO + VP Finance + VP Commercial + VP Revenue DisplacesMcKinsey margin-diagnostic engagements ($500K-2M)

What it does

Attributes every flight's P&L from the previous day against forecast + budget + last-year baselines. Detects margin deviations ≥1σ and emits a Decision Artifact per flagged flight with the full PAL+ decomposition (revenue + ancillary + cargo - 6 cost lines).

How to read the dashboard

  • Top KPI row: total flights, total actual margin vs forecast (delta in red/green), number of anomalies flagged, audit chain integrity.
  • Anomalies section: red cards with flight_number, route, actual margin, deviation_sigma. Click to expand and see narrative + line-by-line PAL+ breakdown + drill-down to Sense record.
  • All flights section: first 50 on-baseline flights. Click any to see its full decomposition.
  • view artifact: each card links to its JSON artifact (deep-linkable, replayable).
💰

S2 · Daily Cost Control

CadenceDaily 06:00 + on-demand scenario triggers BuyerCFO + VP Operations + functional cost owners (Fuel, Crew, MX, Airport, Distribution) DisplacesMcKinsey cost-out programs / Bain cost-PMO ($500K-3M)

What it does

Detects anomalies in EACH cost line (fuel, crew, MX, airport, distribution) with per-population z-score. For each anomaly emits a Decision with narrative + proposed lever (e.g. 'reduce reserve crew at hub by 2 pilots') with estimated USD impact.

How to read the dashboard

  • Top KPI row: cost-line anomalies count, total impact, top opportunity (best single lever).
  • Strategic cards: each anomaly shows which line is off (e.g. 'fuel cost 50% of revenue'), the delta vs baseline, and recommended levers — specific actions with estimated USD impact.
  • Constitution gate: write-back to Hyperion-Sim requires CFO + COO sign-off via audit chain.
🎯

S3 · Daily RM Strategic

CadenceDaily + scenario triggers BuyerVP RM + Director Pricing + RM analyst pyramid + VP Commercial Strategy DisplacesSimon-Kucher / BCG / McKinsey RM strategy engagements ($300K-1M)

What it does

Detects fence redesign opportunities (rules separating corporate from leisure). Computes corp-vs-leisure yield ratio per route and flags routes below the median — where the fence collapsed. Each Decision proposes fence redesign + cluster reassignment with +X bp yield estimate.

How to read the dashboard

  • Does NOT compete with PROS / AirVision / FLYR — those handle day-of-departure tactical bid-price. SkyWeave provides the strategic envelope.
  • Strategic cards: each shows the route, observed corporate vs leisure yields, the ratio, and the redesign proposal.
  • Write-back: strategic params (not bid-prices) go to PROS-Sim strategic-params API.
📦

S4 · Daily Cargo Strategic

CadenceDaily + scenario triggers BuyerVP Cargo + Director Cargo + VP Commercial Strategy DisplacesBoutique cargo consultants + ICF cargo studies + Seabury ($200K-600K)

What it does

Recalibrates yield curves per O&D × commodity. Detects routes with cargo yield below network mean (bottom 25%) and proposes recalibration: lift floor rate + rebalance belly capacity vs pax-capacity coupling. Does NOT compete with IBS iCargo tactical booking layer.

How to read the dashboard

  • Yield-per-ton-mile: the key metric compared to network mean per O&D.
  • Levers: each Decision includes specific options (yield curve recalibration, commodity mix shift) with estimated annual USD impact.
  • Write-back: to iCargo-Sim strategic API (not tactical bookings).
✈️

S5 · P11 Fleet Strategy

CadenceProject · quarterly + event-driven rerun BuyerCFO + Treasury + VP Fleet Planning + Corporate Development Displaces3-4 month Alton / Oliver Wyman / ICF fleet review ($1-5M)

What it does

Analyzes multi-year rotation by fleet type. Identifies retirement candidates (under-performers) and expansion candidates (out-performers) with 5-year NPV calculation. Each Decision includes concrete levers (retire over 24mo + redeploy crew, OEM bid evaluation, lessor renegotiation).

How to read the dashboard

  • Horizon: 5 years (NPV calculated at ~8% discount rate).
  • Per fleet type: A320-200, A321neo, B737-800, B737-MAX8, B787-9. Compares avg margin/cycle vs network mean.
  • Levers: retire (with 24-month timeline), OEM bid evaluation, lessor early-return clauses.
🌐

S6 · P10 Network Strategy

CadenceProject · quarterly + event-driven on competitive shifts BuyerVP Commercial Planning + VP Network + CFO Displaces2-3 month Oliver Wyman / Seabury / Alton network engagement ($5-15M)

What it does

Identifies routes to open (top network performers) and routes to close (bottom performers). 5-year NPV per route. Each Decision includes concrete levers: closure + slot redeployment via auction primitive, or frequency add with RM coordination.

How to read the dashboard

  • Bottom-3 + Top-2: the stub shows up to 5 candidates (3 closures + 2 expansions).
  • NPV: calculated over 5 years, baseline discount rate ~8%.
  • Levers: route closure with slot auction, frequency add with bid-price ceiling coordination.

The 8 primitives (F1–F8)

F1

💎 PAL+ Profit Attribution

Decomposes every Decision into USD lines: revenue + ancillary + cargo - 6 cost lines. Each line has formula_hash + evidence_ref (points to content-hash of source Sense record). In the demo it's 9 lines; production has 36 calibration constants tuned against multi-year override telemetry, with cross-cadence dedup graph blocking double-counting. The demo has the full structure but not the calibration.

F2

🔐 Audit-chained Ledger

Append-only per-tenant Merkle chain. Every decision/override/kill-switch/scenario commit is hashed linking to the previous hash. Production: blake3 + AWS KMS Sign (RSA-PSS) + hourly Merkle root pin to S3 Object Lock (compliance mode 7-year). Demo: SHA-256 + verify_chain() returns OK. Independently verifiable without trusting SkyWeave.

F3

⚙️ Coordinator Runtime + Constitution + Kill-Switch

Coordinator base class (ABC) + 6 concrete implementations (Margin, Cost, RM, Cargo, Fleet, Network). Non-bypassable pipeline: run() → constitution → PAL+ → audit → profit_queue. Constitution checks FAR 117 + EU OPS 965 + per-tenant CBA before any Decision reaches audit. Kill-switch halts ≤60s p99 across all coordinators. Plug-in interface so Roberto can inject his optimization engine without touching coordinators.

F4

👁️ Sense Ledger + Inference Cache + Replay Manifest

Append-only log of every external + internal fetch. Each record content-hashed with SHA-256 (production: blake3). Production: 18+ MCP/computer-use connectors (Altea, SabreSonic, AMOS, NetLine, PROS, etc.) under entitlement-grant. LLM Inference Cache: every LLM call (prompt, model_dated_id, response, sampling_params, KMS signature) → WORM S3. Replay Manifest indexes each decision to its exact Sense records. 3-month byte-equivalent replay in the demo.

F5

🧰 Skill SDK

Deferred in demo — Production: skyweave-cli init / validate / deploy / publish with cosign signing pipeline. Each Skill is a YAML manifest (declared coordinator bindings, data dependencies, constitution rules, PAL+ extensions, renderer template). Marketplace post-Series A. In the demo surfaces ship as internal modules.

F6

📐 Open Ontology + Schemas

5 JSON Schemas (Draft 2020-12) published Apache 2.0: Decision, PALDecomposition, PALLine, SenseRecord, AuditEntry. Industry vocabulary — enables a regulator, a lender, or an academic paper to cite our structures. Publication cost is zero; the moat compounds for years.

F7

🔮 Analyst What-If Engine

Multi-tenant runtime that lets analysts run replayable scenarios across any surface. Production: 50-200 concurrent analyst seats. Demo: single-user runner with replay + fork. Each scenario applies a mutation (fuel ±%, demand ±%, crew premium ±%, etc.) and re-runs the coordinator with mutated data. The delta vs baseline is shown on the What-If page.

F8

🔍 RAG Pipeline (scaffold)

Per-tenant RAG over carrier docs (contracts, JCBA, MELs, ATPCO, AMOS work-order history, NetLine schedules, regulatory environment per-jurisdiction). Production: BGE-large-en embeddings + pgvector HNSW + LoRA fine-tune on RunPod GPU + federated learning. Demo: scaffold only — ingestion structure + hash-bow embedding + cosine retrieval. NO model training. The interface matches production so the swap is drop-in.

Tools

The 6 tool pages from the top menu, one by one:

📋

Decision Artifacts

→ Open artifacts.html

Unified viewer of ALL Decision Artifacts emitted in the last demo run (S1-S6). Each card shows the raw JSON expandable (replayable), the PAL+ decomposition with formula hashes, recommended levers, and the evidence reference (content-hash to source Sense record). Click any card for full drill-down.

🔮

What-If Engine

→ Open whatif.html

6 pre-run scenarios on S1 and S2 with mutations: fuel +20%, fuel -15%, demand -10%, cargo +25%, crew premium +15%. Each scenario runs the coordinator with mutated data and shows delta-vs-baseline on flagged count + USD impact. Permalink + fork: any analyst can branch from a scenario and apply more mutations.

🔍

RAG Index Studio

→ Open rag.html

Shows the RAG index with 5 ingested doc classes: regulatory (FAR 117 summary), contracts (Pilot CBA 2024), manuals (AMOS engine MX), jcba (route constraints), amos_work_orders. Plus 5 sample queries with the top-3 retrieved chunks. Hash-bow embedding for demo (production: BGE-large-en).

🔌

Connectors

→ Open connectors.html

8 vendor stubs scaffolded with sample records in each vendor's real wire-format: Sabre (SabreSonic XML), Amadeus (Altea NDC + Nevio REST), PROS (strategic-params API), AMOS (work-order XML), NetLine (SSIM-X), IBS iCargo (AWB EDIFACT), Hyperion (staging mart), Anaplan (REST v2). Production: MCP + computer-use bindings + entitlement-grant.

🔐

Audit Chain

→ Open audit.html

Shows the audit chain state: integrity check (verify_chain), total entry count, kill-switch events drilled, current Merkle root. The recent entries table shows seq, kind, entry_hash, previous_hash, decision_id, timestamp. A single tampered byte breaks the chain from that point onward.

📐

Open Ontology · Schemas

→ Open schemas.html

The 5 JSON Schemas (Draft 2020-12, Apache 2.0) published Day 1 with the conceptual URL github.com/skyweave/ontology. Each with properties count, description, and the raw schema expandable. These are the public contract — Roberto's engine and any future Skill must conform to these shapes.

Key concepts

Decision
The atomic unit of SkyWeave output. Every coordinator emits Decisions; the pipeline (Constitution → PAL+ → Audit → Queue) cannot be bypassed. Contains id, surface_id, coordinator_name, flight_date, narrative, levers, impact_usd, PAL+ decomposition. Byte-equivalent replayable.
PAL+ (Profit Attribution Library)
The profit decomposition library. Each PAL+ line is attributed to an underlying_record_key (tail, ESN, route, O&D), with formula_hash + evidence_ref. The cross-cadence dedup graph (NetworkX) blocks two decisions from claiming the same line.
Constitution
The set of rules every Decision must satisfy before reaching audit. Production includes FAR 117 + FAR 121 + EU OPS 965 + IATA 735a + per-tenant CBA. Demo: 4 rules — R-DISCLOSURE (flagged needs narrative), R-SANITY (plausible sigma), R-SURFACE (valid surface_id), R-MATERIALITY (>$1M loss must flag). Violation → ConstitutionViolation → the decision NEVER lands.
Audit Chain (Merkle)
Append-only per-tenant. Each entry hashes (previous_hash + payload_hash + timestamp + tenant_id). A tampered byte breaks the chain. Production: hourly Merkle root + KMS Sign + S3 Object Lock 7-year. Demo: in-memory verify_chain() returns OK.
Coordinator
An instance of the Coordinator base class. Each surface (S1-S6) has its own: MarginCoordinator, CostCoordinator, RMCoordinator, CargoCoordinator, FleetCoordinator, NetworkCoordinator. Each implements run() which returns Decisions; the base class's emit() runs the non-bypassable pipeline.
Sense Ledger
Append-only log of EVERY record that enters the system (CSV ingestion, MCP fetch, computer-use binding). Content-hash (SHA-256/blake3) per record. Entitlement-grant scoped. Every PAL+ line links to its source record via evidence_ref.
Content-hash provenance
Every record in the Sense ledger has a deterministic content_hash. That hash appears as evidence_ref on every PAL+ line, and as source_record_hash on every RAG chunk. End-to-end traceability: USD value → PAL+ line → Sense record → source connector. This is what a consultant cannot deliver.
Replay
The ability to re-derive a decision given the exact inputs at the time of computation. The Replay Manifest indexes each decision to its Sense records + Inference Cache entries. Demo: 3-month byte-equivalent replay on 100% of sampled decisions.
Mode A vs Mode B
Mode A: DP-1 carrier signed, S1-S6 run against carrier's real data. Attestation signer is carrier's CFO + VP RM + VP Cargo + VP Fleet. Mode B: no DP-1, S1-S6 run against synthetic data (BTS T-100 + DB1B + OAG public + 10-K filings). This demo is Mode B.
Mythos timeline / 30-agent destination
The post-alpha roadmap assumes a frontier-class tool-use model lands ≥99.9% reliable + coherent 60-90min reasoning by Dec 2026. Under that assumption: 6 agents at alpha (D45) → 30 agents at M6 (Dec 2026). If Mythos slips: 30 agents lands M9 with human-in-loop intermediate.

Architecture

Per PRD §10, the system has 5 architectural surfaces (don't confuse with the 6 production surfaces S1-S6):

And the non-bypassable pipeline every Decision goes through:

┌─────────┐ ┌──────────────┐ ┌─────────┐ ┌──────────┐ ┌──────────────┐ │ Sense │ → │ Optimization │ → │ Constit │ → │ PAL+ │ → │ Audit chain │ │ ledger │ │ engine │ │ ution │ │decompose │ │ (Merkle) │ └─────────┘ └──────────────┘ └─────────┘ └──────────┘ └──────────────┘ │ ▼ violation ConstitutionViolation (decision NEVER lands)

Mode A vs Mode B

Mode A (DP-1 signed): S1-S6 + F7 run against the carrier's real data. Attestation signer is the carrier's CFO + VP RM + VP Cargo + VP Fleet. Pricing anchored against DP-1's real invoice trail.

Mode B (DP-1 NOT signed): S1-S6 + F7 run against synthetic data (BTS T-100 + DB1B + OAG public + comparable 10-K/20-F + synthetic cost ledger). Decision granularity reduced. Attestation signer: founder-grade advisor.

This demo is Mode B. The entire architecture is intact — only the data source + the attestation signer change. When a DP-1 signs, the switch is transparent (same code, different input CSV).

How to run the demo

The demo regenerates on every build (push to main). To run locally:

git clone https://github.com/alfonso2254/skyweave.git
cd skyweave
python3.11 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest tests/ -v
python -m skyweave demo
open demo/output/index.html

CLI flags:

python -m skyweave demo \
  --days 14 \                   # synthetic days
  --flights-per-day 40 \         # flights per day
  --anomaly-rate 0.10 \          # anomaly injection rate
  --seed 42 \                    # reproducibility seed
  --output-dir demo/output

FAQ

Why do numbers change every time it redeploys?
Because the demo regenerates synthetic data on every build with seed=42 but with dates relative to today (yesterday window). The audit chain is also generated from scratch. Changing the seed in the command produces another deterministic distribution.
Why do some surfaces (S3, S4) sometimes have few Decisions?
Because the Stub engine thresholds are intentionally conservative. S3 only flags routes where corp-vs-leisure ratio is below median, S4 only flags bottom-25% routes by cargo yield. Raising --anomaly-rate gives more signal.
How do I replace the StubOptimizationEngine with a real one?
Implement the OptimizationEngine Protocol class (in skyweave/core/protocols.py) with a single method: async def optimize(problem, context) -> OptimizationResult. Pass it to any Coordinator's constructor instead of the Stub. NO coordinator code changes. That's the plug-in interface frozen at M1.
Does the demo have multi-tenancy?
NO. The demo runs single-tenant (tenant::testair). The entire architecture is scoped by tenant_id but the demo doesn't exercise multi-tenancy. Production: per-tenant KMS CMK + Postgres RLS per tenant.
Why SHA-256 and not blake3 in the audit?
Pure demo pragmatism. SHA-256 is Python stdlib. blake3 requires pip install + Rust toolchain on some paths. The Merkle structure is identical. Switching to blake3 is a one-line replacement.
How much does the Dokploy deploy cost?
The container uses ~120MB RAM idle. Minimal CPU. It's Python stdlib HTTP server serving static HTML — cost is trivial. Build time ~27 seconds per push to main.
Can I run the demo on my machine without Docker?
Yes: python3.11 -m venv .venv && source .venv/bin/activate && pip install -e . && python -m skyweave demo && open demo/output/index.html. No external dependencies beyond Python 3.11+, pydantic, rich, pytest.
What if I want to add a 7th surface?
Three files: (1) a new coordinator in skyweave/coordinators/ inheriting from Coordinator ABC, (2) a new OptimizationProblem dataclass in protocols.py, (3) a renderer in skyweave/render/. Then add it to the CLI and to the nav arrays in common.py.

Post-demo roadmap

After the demo, Luis §5 establishes the build order:

  1. Pre-flight (Day -6 to 0): hires signed, AWS+KMS+Postgres+RLS provisioned, OQ-28/29/39 resolved, schemas frozen.
  2. Week 1-3: foundation spine — coordinator runtime + 18 connectors + audit chain + Constitution rule library + PAL+ at 36-constant production depth.
  3. Week 4-5: S1 + S2 at full depth; Roberto's RobertoEngine replaces the StubEngine.
  4. Week 6: S3 + S4 light cloned from scaffold.
  5. Week 7: S5 + S6 light + RAG Phase 1 production + telemetry.
  6. Week 8: integration, demo dry-runs, hardening.
  7. Day 60: Demo Day.