nexus-gateway

Install, enroll, start, and troubleshoot the Linux Nexus Agent on a target host until it connects to the Hub, installs the iptables redirect chain, listens on 19080, and produces traffic_event rows. Encodes every real failure mode hit deploying to an Ubuntu server and a kernel-6.17 Docker desktop on a censored (GFW) network: pending-enrollment (enroll skipped), "Incompatible with this kernel" (iptables-nft vs legacy on new kernels), xtables.lock permission, missing nat modules, SO_MARK self-loop 502s, PeekSNI plain-HTTP stall, SSL_CERT_FILE / browser-CA trust, DNS poisoning (DoT), TLS-SNI reset + egress proxy, QUIC/HTTP3 bypass, and local-proxy loopback bypass. Trigger keywords: deploy linux agent, install nexus-agent on linux, agent won't connect, agent not intercepting, no 19080, iptables Incompatible with this kernel, agent enrollment, browser chatgpt not monitored, agent 502, /linux-agent-deploy.

Audit and enrich a Control Plane OpenAPI spec file claim-by-claim against the handler code. Pre-commit gate for every per-kind spec under docs/users/api/openapi/control-plane/. The spec must mirror what the handlers actually implement — paths, verbs, types, status codes, IAM tiers — and carry the semantic layer only a human audit can supply: accurate field/operation descriptions, request/response examples, enum value sets, and the true required-field set. Trigger keywords: openapi review, openapi audit, review schema, audit api spec, enrich openapi, /openapi-review.

Bring the full Nexus Gateway local stack up from a clean clone — PostgreSQL + Valkey + NATS via docker-compose, four Go services (Hub / Control Plane / AI Gateway / Compliance Proxy), and the Control Plane UI (Vite). Encodes every gotcha a first-time OSS contributor hits so the model can drive the full bring-up without asking the user mid-way. Trigger keywords: run local, start local stack, local bring-up, local dev start, first-run, OSS first run, bootstrap stack, /run-local.

End-to-end smoke test for the Compliance Proxy. Use when the user wants to verify that the running compliance-proxy correctly MITM-intercepts HTTPS provider traffic on `:3128`, applies the compliance pipeline, and writes matching `traffic_event` rows (`source = 'compliance-proxy'`) plus Prometheus counters. Trigger keywords: test compliance proxy, smoke cp, verify compliance proxy, MITM smoke, /v1/messages proxy test, agent upstream simulation. No required input — credentials come from the DB (`Credential` table). Output: a Markdown report at `/tmp/test-compliance-proxy-<UTC-timestamp>.md`.

Use when building, compiling, or publishing the Nexus Gateway AWS AMI / single-instance appliance (the nexus-ami/ Packer image) and registering it to AWS. Covers the full pipeline (Go cross-compile + UI + Prisma + Packer), the EC2 vCPU-quota trap that makes the default m5.4xlarge fail with VcpuLimitExceeded on fresh accounts, the RAM-bound valkey-search compile that OOMs under 48GB, passing an AWS profile, running the ~1h build detached, and verifying the AMI. Trigger keywords: build ami, compile ami, publish ami, packer build, nexus-ami, push ami to aws.

Audit ai-gateway adapter codecs against provider-adapter-architecture.md Section 3a Rules 1-7. Detects per-adapter logic that leaked into the generic spec_adapter dispatcher, ingress bodies passed to PrepareBody without canonicalize, error envelopes that bypass the helper, prefix-lists without empirical evidence, and missing PassthroughRewrite wiring. Trigger keywords: adapter audit, adapter conformance, codec audit, provider adapter check, /adapter-conformance-check.

Use when fixing frontend bugs, UI errors, runtime crashes, or data display issues — traces page to API to backend to database, fixes mismatches, then verifies via curl login + DB queries

Full-surface smoke test for the AI Gateway + Control Plane. Tests every model in the catalog (non-stream + SSE + 2-turn cache), auto-manages routing rules (all OFF for P3; per-rule isolation for P4), cross-checks traffic_event DB rows, diffs Prometheus counters, and auto-fixes failures (investigate → edit code → build → restart gateway → rerun). Includes P3E embeddings phase: per-model six-arm suite (Arm A non-stream basic, Arm B dimensions round-trip, Arm C batch input, Arm D traffic_event cross-check, Arm E Prometheus delta, Arm F cross-ingress consistency) plus reject-asymmetry negative tests (HTTP 400 on provider capability violations). Cache and dry-run arms are explicitly skipped for embeddings (no prompt-cache semantic). Trigger keywords: smoke gateway, full smoke, test all models, verify all providers, /smoke-gateway. Inputs: user provides a virtual key (vk) and optionally --routing to enable routing-ON tests. Output: Markdown report at /tmp/smoke-gateway-<UTC-timestamp>.md

End-to-end synthetic test for the Cursor IDE Tier-1 protobuf normalizer (E46-S12). Sends a hand-rolled GetChatRequest protobuf to api2.cursor.sh through the deployment's compliance proxy on `:3128` (the `--proxy` flag, or any proxy the user supplies), then verifies the resulting traffic_event_normalized row shows `kind=ai-chat`, `detectedSpec=cursor`, `model=claude-sonnet-4-6`, `confidence≈0.95`, and three decoded user/assistant/user messages. Use when validating the cursor adapter end-to-end without waiting to capture real Cursor IDE traffic, after touching anything under `packages/shared/traffic/adapters/ide/cursor/`, or after a Hub/CP/Compliance- Proxy redeploy that touched the normalize pipeline. Trigger keywords: test cursor, cursor protobuf test, cursor adapter smoke, cursor synthetic, /test-cursor-adapter.

End-to-end synthetic test for the Gemini Web (gemini.google.com) Tier-1 normalizer (E46-S12 + Tier 2 batchexecute detector). Sends a hand-rolled Google batchexecute POST (`f.req=` form-urlencoded JSON envelope) to gemini.google.com's StreamGenerate endpoint through the prod compliance proxy on `:3128` (the `--proxy` flag), then verifies the resulting traffic_event_normalized row shows `kind=ai-chat`, `detectedSpec=gemini-web`, the extracted user prompt, and confidence around 0.85. Use when validating gemini-web adapter end-to-end without waiting to capture real Gemini web traffic, after touching `packages/shared/traffic/adapters/web/geminiweb/` or `packages/shared/transport/normalize/extract/detector.go`'s BatchExecuteDetector, or after Hub/CP/Compliance-Proxy redeploy that changed the normalize pipeline. Trigger keywords: test gemini-web, gemini web test, gemini batchexecute test, geminiweb adapter smoke, /test-geminiweb-adapter.

End-to-end synthetic test for the OpenAI Responses-API ingress (E56). Sends 5 hand-rolled requests through the local AI Gateway on http://localhost:3050/v1/responses covering text non-stream, text SSE, function-call SSE, structured outputs (text.format json_schema), and reasoning-effort=high non-stream. For each arm, verifies HTTP response shape, cross-checks the traffic_event DB row's endpoint_type= "responses", and diffs Prometheus counters. Optional --cross-format arm hits a routing rule that resolves to non-OpenAI to verify the S6 guard rejects previous_response_id / store / built-in tools with a Responses-shape 400. Trigger keywords: test openai responses, responses-api test, /v1/responses synthetic, /test-openai-responses, responses smoke, e56 smoke.

Audit the Control Plane UI + Agent Dashboard against the design-token / CSS framework architecture, including the Tailwind v4 + shadcn surface and the `prime-shadcn-tokens.css` `@theme {}` palette. Detects theme/mode-breaking offenders: hex / rgba / hsla literals in `*.module.css`, hex / rgba inside `style={{}}` blocks in `*.tsx`, raw numeric padding / margin / gap / fontSize / fontWeight / borderRadius / boxShadow / transition / zIndex in inline styles, stale `var(--xxx, FALLBACK)` patterns referencing token names that don't exist, Recharts charts that hardcode hex outside the sanctioned `chartColors.ts`, raw Tailwind palette utilities (`bg-white`, `text-gray-500`, `dark:bg-zinc-900`, etc.) that bypass the semantic shadcn tokens, and i18n hardcoded English strings (delegated to i18n-gap-check). Produces a Markdown report with per-file violation counts, suggested token mappings, and a punch list ranked by theme/mode impact. Trigger keywords: frontend arch review, frontend architecture review, design token che

Review gaps between SDD documents (source of truth) and all related artifacts: architecture, requirements, OpenAPI specs, code implementation, and unit tests. Creates a plan and todo list to bring docs and code into alignment. Use when docs are out of sync with code, after code-heavy changes, or to audit spec-code parity. Trigger keywords: gap review, sync docs, doc drift, code-doc mismatch, audit docs, review gaps, spec parity, doc check.

Scan all frontend i18n keys across the Control Plane UI and the Agent Dashboard, and report gaps + hardcoded English strings. Covers two bundles: control-plane-ui (ns: pages | common | nav | shared) and agent-ui (ns: dashboard | shared). The `shared` namespace lives in `packages/ui-shared/src/i18n/` and is consumed by both. Detects: (1) keys used in source but missing from EN — highest priority, UI renders raw key strings; (2) EN keys missing from ES or ZH — translation gaps; (3) orphan keys in ES/ZH not in EN — stale translations; (4) EN keys not used in source — potentially stale; (5) dynamic `t()` template literals — manual review list; (6) hardcoded English in `.tsx` (JSX text + user-facing attribute literals) that bypass `t()` — manual review list. Trigger keywords: i18n gap, missing translations, i18n check, translation gaps, locale scan, hardcoded strings, untranslated UI, /i18n-gap-check.

Scan the repository for leaked secrets, PII, and production infrastructure before an open-source release — public IPs, non-allowlisted domains, emails/usernames, passwords, API keys, private keys, DB connection strings, device serials / fingerprints / machine IDs, EC2 internal hostnames. The detection is a deterministic Python script (regex + entropy + allowlist) so an LLM drifting cannot cause a missed leak; the LLM's job is only to TRIAGE the script's candidates and drive fixes. Use before publishing, after a history rewrite, or whenever you suspect prod data leaked into the tree. Trigger keywords: secret scan, leak scan, oss scan, pre-release scan, scrub secrets, check for leaked credentials, /oss-secret-scan.

Spec-writing for Spec-Driven Development (SDD) skill for writing requirement specifications before implementation. Use when starting a new feature, planning work, writing requirements, or designing a component. Trigger keywords: spec, specification, SDD, plan feature, write requirements, design feature, spec-driven, new feature, what to build.

Run the full Nexus Gateway end-to-end test program (preflight + L1 smoke + L1 Go integration + L2 protocol + L3 AI-judge + L4 Playwright UI) via tests/run-all.sh and surface the unified markdown report. The single "did my change break something" entry point — covers ~75 business flows across all five services, each verified by HTTP shape + DB cross-check + Prometheus delta or AI-judge verdict. Trigger keywords: test all, run regression, smoke everything, full regression, e2e tests, regression sweep, /test-all. No required inputs; reads tests/.env.local for VKs and admin credentials. Output: a Markdown report at /tmp/nexus-test/test-all-<UTC-timestamp>.md plus a fan-out summary in this conversation.